Embed Size (px)
Citation preview
Andrew Burden Dan Macpherson
Red Hat Enterprise Virtualization 3.3Command Line Shell Guide
A Guide for Installing and Using the Command Line Shell for Red HatEnterprise Virtualizat ion
Red Hat Enterprise Virtualizat ion 3.3 Command Line Shell Guide
A Guide for Installing and Using the Command Line Shell for Red HatEnterprise Virtualizat ion
Andrew [email protected]
Legal Notice
Copyright © 2014 Red Hat.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0Unported License. If you distribute this document, o r a modified version o f it, you must provideattribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all RedHat trademarks must be removed.
Red Hat, as the licensor o f this document, waives the right to enforce, and agrees not to assert,Section 4d o f CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the InfinityLogo, and RHCE are trademarks o f Red Hat, Inc., registered in the United States and o thercountries.
Linux ® is the registered trademark o f Linus Torvalds in the United States and o ther countries.
Java ® is a registered trademark o f Oracle and/or its affiliates.
XFS ® is a trademark o f Silicon Graphics International Corp. or its subsidiaries in the UnitedStates and/or o ther countries.
MySQL ® is a registered trademark o f MySQL AB in the United States, the European Union andother countries.
Node.js ® is an o fficial trademark o f Joyent. Red Hat Software Collections is not fo rmallyrelated to or endorsed by the o fficial Joyent Node.js open source or commercial pro ject.
The OpenStack ® Word Mark and OpenStack Logo are either registered trademarks/servicemarks or trademarks/service marks o f the OpenStack Foundation, in the United States and o thercountries and are used with the OpenStack Foundation's permission. We are not affiliated with,endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All o ther trademarks are the property o f their respective owners.
AbstractThis fo llowing guide contains information for installing and using the Red Hat EnterpriseVirtualization Manager Command Line Shell
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table of Contents
Preface1. Do cument Co nventio ns1.1. Typ o g rap hic Co nventio ns1.2. Pull-q uo te Co nventio ns1.3. No tes and Warning s
2. Getting Help and G iving Feed b ack2.1. Do Yo u Need Help ?2.2. We Need Feed b ack!
Chapt er 1 . About t he Command Line Int erface1.1. Intro d uctio n to the Co mmand Line Interface
Chapt er 2 . Using t he CLI2.1. Install ing the CLI2.2. TLS/SSL Certificatio n2.3. Running the CLI2.4. Interacting with the CLI2.5. Co llectio ns
Chapt er 3. Quick St art Example3.1. Creating a Basic Virtualizatio n Enviro nment with the CLI
Chapt er 4 . Commands4.1. Co nnecting to RHEVM4.1.1. Co nnect to RHEVM (co nnect)4.1.2. Disco nnect fro m RHEVM (d isco nnect)
4.2. Reso urces4.2.1. Lis t Reso urces in a Co llectio n (l is t)4.2.2. Sho w a Reso urce (sho w)4.2.3. Ad d a Reso urce (ad d )4.2.4. Up d ate a Reso urce (up d ate)4.2.5. Remo ve a Reso urce (remo ve)4.2.6 . Perfo rm Actio n o n a Reso urce (actio n)4.2.7. Using Sub -Reso urces (--RESOURCE-id entifier)
4.3. O ther Co mmand s4.3.1. .rhevmshellrc Co nfig uratio n4.3.2. Co nnect to VM (co nso le)4.3.3. Run a Shell Co mmand (shell)4.3.4. Run a Scrip t (fi le)4.3.5. Clear the Screen (c lear)4.3.6 . Print Inp ut (echo )4.3.7. Sho w Last Status (status)4.3.8 . Sho w CLI Info rmatio n (info )4.3.9 . Sho w System Summary (summary)4.3.10 . Test Co nnectio n (p ing )4.3.11. Exit fro m the CLI (exit)4.3.12. End o f File (EOF)4.3.13. Sho w Help (help )
Chapt er 5. Resource T ypes5.1. b rick5.2. cd ro m5.3. c luster
33345556
77
888
101113
1 414
1 919192020202122222324242525252626272727282829292930
31313132
T able of Cont ent s
1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4. d atacenter5.5. d isk5.6 . g lustervo lume5.7. g ro up5.8 . ho st5.9 . netwo rk5.10 . nic5.11. p ermissio n5.12. p ermit5.13. q uo tas5.14. ro le5.15. snap sho t5.16 . s to rag eco nnectio n5.17. s to rag ed o main5.18 . tag5.19 . temp late5.20 . user5.21. vm5.22. vmp o o l5.23. vnicp ro fi le
Chapt er 6 . CLI Queries6 .1. Query Syntax6 .2. Wild card s
Revision Hist ory
3435373939414345464647484850525255555959
6 16 16 1
6 3
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
2
Preface
1. Document Convent ions
This manual uses several conventions to highlight certain words and phrases and draw attention tospecific pieces of information.
1.1. T ypographic Convent ions
Four typographic conventions are used to call attention to specific words and phrases. Theseconventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used tohighlight keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your currentworking directory, enter the cat my_next_bestselling_novel command at theshell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold andall distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects eachpart of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a keycombination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned valuesmentioned within a paragraph will be presented as above, in mono-spaced bold . For example:
File-related classes include filesystem for file systems, file for files, and dir fordirectories. Each class has its own associated set of permissions.
Proport ional Bold
This denotes words or phrases encountered on a system, including application names; dialog-boxtext; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. Forexample:
Choose System → Preferences → Mouse from the main menu bar to launchMouse Preferences . In the Buttons tab, select the Left-handed mouse checkbox and click Close to switch the primary mouse button from the left to the right(making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applicat ions →Accessories → Character Map from the main menu bar. Next, choose Search →Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the
Preface
3
Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your documentand choose Edit → Paste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specificmenu names; and buttons and text found within a GUI interface, all presented in proportional boldand all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable orvariable text. Italics denotes text you do not input literally or displayed text that changes dependingon circumstance. For example:
To connect to a remote machine using ssh, type ssh [email protected] at ashell prompt. If the remote machine is example.com and your username on thatmachine is john, type ssh [email protected].
The mount -o remount file-system command remounts the named file system.For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q packagecommand. It will return a result as follows: package-version-release.
Note the words in bold italics above: username, domain.name, file-system, package, version andrelease. Each word is a placeholder, either for text you enter when issuing a command or for textdisplayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new andimportant term. For example:
Publican is a DocBook publishing system.
1.2. Pull-quote Convent ions
Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books Desktop documentation drafts mss photos stuff svnbooks_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
static int kvm_vm_ioctl_deassign_device(struct kvm *kvm, struct kvm_assigned_pci_dev *assigned_dev){ int r = 0; struct kvm_assigned_dev_kernel *match;
mutex_lock(&kvm->lock);
match = kvm_find_assigned_dev(&kvm->arch.assigned_dev_head, assigned_dev->assigned_dev_id); if (!match) { printk(KERN_INFO "%s: device hasn't been assigned
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4
before, " "so cannot be deassigned\n", __func__); r = -EINVAL; goto out; }
kvm_deassign_device(kvm, match);
kvm_free_assigned_device(kvm, match);
out: mutex_unlock(&kvm->lock); return r;}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note shouldhave no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply tothe current session, or services that need restarting before an update will apply. Ignoring abox labeled “ Important” will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
2. Get t ing Help and Giving Feedback
2.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red HatCustomer Portal at http://access.redhat.com. Through the customer portal, you can:
search or browse through a knowledgebase of technical support articles about Red Hat products.
submit a support case to Red Hat Global Support Services (GSS).
access other product documentation.
Preface
5
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software andtechnology. You can find a list of publicly available mailing lists athttps://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that listor to access the list archives.
2.2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manualbetter, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/against the product Red Hat Enterprise Virtualiz at ion.
When submitting a bug report, be sure to mention the manual's identifier: Guides-CLI
If you have a suggestion for improving the documentation, try to be as specific as possible whendescribing it. If you have found an error, please include the section number and some of thesurrounding text so we can find it easily.
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
6
Chapter 1. About the Command Line Interface
1.1. Int roduct ion to the Command Line Interface
The Red Hat Enterprise Virtualization suite features a command line interface (CLI). This CLI providesusers with a means to connect to Red Hat Enterprise Virtualization Manager outside of the standardweb interface. The CLI also contains a scripting system, which helps system administrators performperiodic maintenance or repetitive tasks on their virtualization environment via client machines.
Report a bug
Chapt er 1 . About t he Command Line Int erface
7
Chapter 2. Using the CLI
2.1. Installing the CLI
Install the Red Hat Enterprise Virtualization CLI to a client machine:
1. Log into the client machine as the root user.
2. Subscribe to the Red Hat Enterprise Virtualization Manager Channels:
Subscript ion Manager inst ruct ions
# subscription-manager list --available | grep -A8 "Red Hat Enterprise Virtualization"# subscription-manager subscribe --pool=POOLID# yum-config-manager --enablerepo=rhel-6-server-rhevm-3.3-rpms
RHN Classic inst ruct ions
# rhn_register# rhn-channel --add --channel=rhel-x86_64-server-6-rhevm-3.3
Note
See the Red Hat Enterprise Virtualization Manager Release Notes for specific channelnames current to your system.
3. Install the CLI package and dependencies:
# yum install rhevm-cli
Report a bug
2.2. TLS/SSL Cert ificat ion
The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure
(HTTPS) for secure interaction with client software, such as the Manager's SDK and CLIcomponents. This involves a process of obtaining a certificate from the Red Hat EnterpriseVirtualization Manager and importing it into the certificate store of your client.
Important
Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a securenetwork connection.
Procedure 2.1. Obtain ing a Cert if icate
[1]
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
8
You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to theclient machine using one of three methods:
1. Method 1 - Use a command line tool to download the certificate from the Manager. Examplesof command line tools include cURL and Wget , both of which are available on multipleplatforms.
a. If using cURL:
$ curl -o rhevm.cer http://[rhevm-server]/ca.crt
b. If using Wget :
$ wget -O rhevm.cer http://[rhevm-server]/ca.crt
2. Method 2 - Use a web browser to navigate to the certificate located at:
http://[rhevm-server]/ca.crt
Depending on the chosen browser, the certificate either downloads or imports into thebrowser's keystore.
a. If the browser downloads the cert if icate: save the file as rhevm.cer.
If the browser imports the cert if icate: export it from the browser's certificationoptions and save it as rhevm.cer.
3. Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to yourclient machine.
a. Log in to the Manager as the root user.
b. Export the certificate from the truststore using the Java keytool management utility:
$ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer
This creates a certificate file called rhevm.cer.
c. Copy the certificate to the client machine using the scp command:
$ scp rhevm.cer [username]@[client-machine]:[directory]
Each of these methods results in a certificate file named rhevm.cer on your client machine. An APIuser imports this file into the certificate store of the client.
Procedure 2.2. Import ing a Cert if icate to a Client
Importing a certificate to a client relies on how the client itself stores and interprets certificates.This guide contains some examples on importing certificates. For clients not using NetworkSecurity Services (NSS) or Java KeyStore (JKS), see your client documentation for moreinformation on importing a certificate.
Report a bug
Chapt er 2 . Using t he CLI
9
2.3. Running the CLI
Start the CLI application with the following command:
# rhevm-shell
This rhevm-shell application is an interactive shell for Red Hat Enterprise Virtualizationenvironments.
Users connect automatically to Red Hat Enterprise Virtualization Manager using the followingadditional options.
# rhevm-shell -c -l "https://[server]/api" -P [port] -u "[user@domain]" -A "[certificate]"
Ensure to replace the following values:
server - The hostname or IP Address of the Red Hat Enterprise Virtualization Manager. The CLIconnects to the Red Hat Enterprise Virtualization Manager via the REST API.
user@domain - The user name and directory service domain for the user logging into Red HatEnterprise Virtualization Manager.
certificate - The path name of the Certificate Authority file.
The shell will prompt you for the password, and, if not already provided, the use rname and the URLfor the Red Hat Enterprise Virtualization Manager.
Note
The certificate is the only obligatory option as the others used in this example will be promptedby the shell. Instead of specifying the certificate you can use the '--insecure' option to connectwithout certification, however this is not recommended as it may allow man-in-the-middle(MITM) attackers to spoof the identity of the server.
Opt ions for rhevm-shell
-h , - -help
Show help for rhevm-shell .
-d , - -debug
Enables debugging.
- l URL, - -url= URL
Specifies the API entry point URL.
-u USERNAME, - -username= USERNAME
Connect as this user.
-K KEY_FILE, - -key- f ile= KEY_FILE
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
10
Specify key file.
-C CERT_FILE, - -cert - f ile= CERT_FILE
Specify certificate file.
-A CA_FILE, - -ca- f ile= CA_FILE
Specify server Certificate Authority file.
- I , - - insecure
Allow the CLI to connect via SSL without certification. Use this option with caution becauseit can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
-F, - - f i lter
Enable filtering based upon user permissions.
-P PORT, - -port= PORT
Specify port.
-T TIMEOUT, - - t imeout= TIMEOUT
Specify timeout.
-c, - -connect
Automatically connect.
- f FILE, - - f i le= FILE
Read commands from FILE instead of stdin.
-e, - -extended-prompt
Enables the extended prompt option for the shell. This option displays the hostname of theenvironment in the command prompt. Default is ' false'.
Note
Although users can use the --file option to call a file that includes their password information,this practice is not recommended for security reasons. Users with a non-interactive shell areable to connect to the Red Hat Enterprise Virtualization Manager from within the shell, wherethe --password option can be used.
Report a bug
2.4 . Interact ing with the CLI
The CLI is an interactive shell for controlling your Red Hat Enterprise Virtualization environment fromthe command line. Type the required command and any additional parameters.
Example 2.1. Entering a shell command
Chapt er 2 . Using t he CLI
11
[RHEVM shell (connected)]# show vm --name desktop_vms
To support the construction of command and parameter combinations, the CLI includes thefunctionality to list and automatically complete commands and parameters by pressing the TAB keytwice, similar to the bash shell.
Example 2.2. List ing and automat ic complet ion of commands and parameters
Press double TAB at a blank prompt to list all available commands.
[RHEVM shell (connected)]# TAB TABEOF clear console remove echo filehistory ping show update action connectadd disconnect exit help list shellstatus
Choose a command and press double TAB to view the next set of available parameters for thecommand. For the show, this lists all resources.
[RHEVM shell (connected)]# show TAB TABbrick datacenter event group nicquota statistic template vmpool cdromdisk file host permission rolestoragedomain user cluster domain glustervolumenetwork permit snapshot tag vm
Double TAB also completes commands and parameters.
[RHEVM shell (connected)]# show vm TAB TABkwargs name show-all storagedomain [RHEVM shell (connected)]# show vm naTAB TAB[RHEVM shell (connected)]# show vm --name
Note that the double TAB also automatically formats na to the --name parameter, including theprefix.
If the incomplete parameter matches multiple parameters, double TAB lists them.
[RHEVM shell (connected)]# show vTAB TABvmpool vm
The CLI provides functions to run Linux commands using either the shell command or the bang (! )character.
Example 2.3. Running Linux shell commands
Use the shell command:
[RHEVM shell (connected)]# shell ls -la
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
12
Or use the bang (! ) character:
[RHEVM shell (connected)]# !ls -la
Similar to the Linux shell, the CLI can pipe data to other commands and sources.
Example 2.4 . Pip ing CLI commands
Pipe CLI data to a Linux shell command:
[RHEVM shell (connected)]# list vms --show-all | grep "Example"name : Example1name : Example2name : ExampleEngineeringdescription : An Example descriptionname : BestExampleVM
Pipe CLI data to a file:
[RHEVM shell (connected)]# list vms --show-all > list vms --show-all > VM_List.txt
The CLI also contains an online help system to provide descriptions and syntax for each commandvia the help command.
Example 2.5. Using online help for the show command
[RHEVM shell (connected)]# help show
Report a bug
2.5. Collect ions
Some command parameters require a collection. A collection is a set of sub-parameter data.Collections are defined using the following syntax.
[RHEVM shell (connected)]# command --param-collection {subparam1=value1;subparam2=value2;subparam3=value3;...},{subparam1=value1;subparam2=value2;subparam3=value3;...},...
Sub-parameters for collections are listed after resource parameter listings on each resource page.
Report a bug
[1] HTTPS is d escrib ed in RFC 28 18 HTTP Over TLS.
Chapt er 2 . Using t he CLI
13
Chapter 3. Quick Start Example
3.1. Creat ing a Basic Virtualizat ion Environment with the CLI
This chapter provides an example to demonstrate the CLI's ability to add a virtual machine within abasic Red Hat Enterprise Virtualization environment. This example uses the following prerequisites:
A networked and configured Red Hat Enterprise Linux host for use as a hypervisor;
A networked and configured NFS storage server with two shares:
/exports/data - The data storage domain; and
/exports/iso - The ISO storage domain.
A networked and configured Red Hat Enterprise Virtualization Manager;
An installation of the CLI on either the Red Hat Enterprise Virtualization Manager or a clientmachine; and,
An ISO file containing a desired virtual machine operating system to install. This chapter usesRed Hat Enterprise Linux Server 6 for our installation ISO example.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) eachresource's ID. Identifier codes in this example might appear different to the identifier codes inyour Red Hat Enterprise Virtualization environment.
Procedure 3.1. Quick Start Example
1. Load the CLI shell and connect to your Red Hat Enterprise Virtualiz at ionManager
The following step run the CLI shell command with additional parameters to connect to yourvirtualization environment.
# rhevm-shell -c --url https://[rhevm-host]/api --username [user]@[domain] --ca-file certificate/authority/path/name
2. List data centers
Red Hat Enterprise Virtualization Manager adds a Default data center on installation. Thisexample uses the Default data center as the basis for our virtual environment.
[RHEVM shell (connected)]# list datacenters
id : 5e3b55d8-c585-11e1-a7df-001a4a400e0dname : Defaultdescription: The default Data Center
3. List host clusters
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
14
Red Hat Enterprise Virtualization Manager adds a Default host cluster on installation. Thisexample uses the Default cluster to group resources in your Red Hat EnterpriseVirtualization environment.
[RHEVM shell (connected)]# list clusters
id : 99408929-82cf-4dc7-a532-9d998063fa95name : Defaultdescription: The default server cluster
4. List log ical networks
Red Hat Enterprise Virtualization Manager creates a default logical network called rhevm formanagement traffic. This example uses the rhevm logical network on the Default datacenter.
[RHEVM shell (connected)]# list networks --show-all
id : 00000000-0000-0000-0000-000000000009name : rhevmdescription : Management Networkdata_center-id: 5e3b55d8-c585-11e1-a7df-001a4a400e0dmtu : 0required : Truestatus-state : operationalstp : Falseusages-usage : VM
Note the data_center-id value matches the id for the Default data center.
5. Create host
Use the add host command to add the Red Hat Enterprise Linux host to the virtualizationenvironment as a new hypervisor. Name this host MyHost.
[RHEVM shell (connected)]# add host --name MyHost --address host.example.com --root_password p@55w0rd!
Ensure to substitute address and root_password with the correct values from your host.
6. Act ivate host
Activate the host after creation using the action host command.
[RHEVM shell (connected)]# action host MyHost activate
7. Create NFS data storage
An NFS data storage domain is an exported NFS share attached to a data center. It providesstorage for virtual machines. Add the NFS share as a data storage domain with the add storagedomain command.
Chapt er 3. Quick St art Example
15
[RHEVM shell (connected)]# add storagedomain --name DataStorage --host-name MyHost --type data --storage-type nfs --format v1 --storage-address '192.168.0.10' --storage-path /exports/data --datacenter-identifier Default
Ensure to substitute storage-address and storage-path with the correct values fromyour NFS server.
Note the datacenter-identifier option attaches the storage domain to the Defaultdata center as a sub-resource.
After creation, use the action storagedomain to activate the storage domain.
[RHEVM shell (connected)]# action storagedomain DataStorage activate
8. Create NFS ISO storage
An NFS ISO storage domain is an exported NFS share attached to a data center. It providesstorage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Add the NFS shareas an ISO storage domain with the add storagedomain command.
[RHEVM shell (connected)]# add storagedomain --name ISOStorage --host-name MyHost --type iso --storage-type nfs --format v1 --storage-address '192.168.0.10' --storage-path /exports/iso --datacenter-identifier Default
Ensure to substitute storage-address and storage-path with the correct values fromyour NFS server.
Note the datacenter-identifier option attaches the storage domain to the Defaultdata center as a sub-resource.
After creation, use the action storagedomain to activate the storage domain.
[RHEVM shell (connected)]# action storagedomain ISOStorage activate
9. Create virtual machine
Use the add vm command to add a new virtual machine.
[RHEVM shell (connected)]# add vm --name MyVM --cluster-name Default --template-name Blank --memory 536870912 --os-boot-dev hd
10. Create virtual machine network in terface
Use the add nic command to add a new network interface. Add the vm-identifier optionto attach the interface as a sub-resource of MyVM and a network-name option to connect tothe rhevm network.
[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --network-name rhevm --bootable true
11. Create virtual machine hard d isk
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
16
Use the add disk command to add a new virtual hard disk. Add the vm-identifieroption to attach the disk as a sub-resource of MyVM.
[RHEVM shell (connected)]# add disk --vm-identifier MyVM --provisioned_size 8589934592 --interface virtio --format cow
12. Add virtual machine CD-ROM drive
The boot media for our example virtual machine requires an CD-ROM or DVD ISO image foran operating system installation. This example uses a Red Hat Enterprise Server 6 ISO imagefor installation.
ISO images must be available in the ISOStorage domain for the virtual machines to use.Red Hat Enterprise Virtualization Manager provides an ISO uploader tool that ensuresimages are uploaded into the correct directory path with the correct user permissions. Onceuploaded, use the list files to show files in the storage domain.
[RHEVM shell (connected)]# list files --storagedomain-identifier
Use the add cdrom command to add a new virtual CD-ROM for your installation media. Addthe vm-identifier option to attach the CD-ROM as a sub-resource of MyVM.
[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.0-x86_64-dvd.iso
13. Start virtual machine
The virtual environment is complete and the virtual machine contains all necessarycomponents to function. Start the virtual machine with the action vm command.
[RHEVM shell (connected)]# action vm start --vm-os-boot-dev cdrom
Note the use of the vm-os-boot-dev option. This changes the boot device to cdrom for thisinitial boot session. After installation, the virtual machine restarts and restores the boot deviceback to hd .
14. List Events
The start action for the virtual machine adds several entries in the events collection. Usethe list events with an additional query to display the events.
[RHEVM shell (connected)]# list events --query "type=153"
id : 105description: MyVM was started by admin (Host: MyHost).
The "type=153" query refers to events where a user starts a virtual machine.
15. Show Event
Use show event to display comprehensive details of an event. This command can be usedto show events by type, name and id .
[RHEVM shell (connected)]# show event --id 60
Chapt er 3. Quick St art Example
17
id : 60description : New Tag foo was created by [email protected] : 432correlation_id: 3e4d4350custom_id : -1flood_rate : 30origin : oVirtseverity : normaltime : 2013-07-03 10:57:43.257000+03:00user-id : fdfc627c-d875-11e0-90f0-83df133b58cc
16. Access Virtual Machine
Access your virtual machine with the console command.
[RHEVM shell (connected)]# console MyVM
Important
Ensure your client machine has a console application installed to match the virtualmachine's display-type. Protocols available include SPICE (default) and VNC .
Report a bug
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
18
Chapter 4. Commands
4.1. Connect ing to RHEVM
4 .1.1. Connect to RHEVM (connect )
The connect command connects to Red Hat Enterprise Virtualization Manager.
Syntax
connect [options]
Table 4 .1. Opt ions for connect
Opt ion Descript ion Required--url The URL to the Red Hat Enterprise Virtualization Manager's
REST API. This takes the form of https://[server]/api .Yes
--username The user name and directory service domain of the userattempting access to the Red Hat Enterprise VirtualizationManager. This takes the form of [username]@[domain].
Yes
--password The password for the user attempting access to the Red HatEnterprise Virtualization Manager.
Yes
--key-file The key file for connection via SSL. No--cert-file The certificate file for connection via SSL. No--ca-file The certificate authority file for connection via SSL. Yes,
unless --insecure isused
--insecure Allow the CLI to connect via SSL without certification. Usethis option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
Yes, butonly if nocertificateauthorityisprovided
--filter Enable filtering based upon user permissions. No--port The port number for connection to the REST API, if not
specified as part of the --url .No
--timeout The timeout period for connection. No
Example 4 .1. Example for connect
[RHEVM shell (disconnected)]# connect --url "https://rhevm.example.com/api" --username "[email protected]" --password "p@55w0rd!" --ca-file "/home/user/ca.crt"
========================================== >>> connected to RHEVM manager 3.2.0.0 <<< ==========================================
[RHEVM shell (connected)]#
Chapt er 4 . Commands
19
Note
Instead of specifying the certificate you can use the '--insecure' option to connect withoutcertification, however this is not recommended as it may allow man-in-the-middle (MITM)attackers to spoof the identity of the server.
Report a bug
4 .1.2. Disconnect from RHEVM (disconnect )
The disconnect command disconnects from Red Hat Enterprise Virtualization Manager.
Syntax
disconnect
Example 4 .2. Example for disconnect
[RHEVM shell (connected)]# disconnect
======================================= >>> disconnected from RHEVM manager <<< =======================================
[RHEVM shell (disconnected)]#
Report a bug
4.2. Resources
4 .2.1. List Resources in a Collect ion (list )
Use the list command to display all resources of a specific type. Lists also include optional searchqueries to filter results.
Syntax
list [collection] [options]
Table 4 .2. list standard opt ions
Opt ion Descript ion--show-all Displays all non-empty properties for each listed resource.
Without this option, only the id , name and descriptionproperties display.
--query [QUERY] Filters the list using a server-side query based upon Red HatEnterprise Virtualization Manager query language.
--kwargs [QUERY] Filters the list using a client-side query.
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
20
--case_sensitive true|false
Match search queries using case sensitivity.
--max Maximum number of results for display.
Opt ion Descript ion
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 4 .3. Examples for list
List virtual machines:
[RHEVM shell (connected)]# list vms
List virtual machines with all properties listed:
[RHEVM shell (connected)]# list vms --show-all
List server virtual machines using a client-side query:
[RHEVM shell (connected)]# list vms --query "status=up"
List users by their user names with a client-side query:
[RHEVM shell (connected)]# list users --query "usrname=jsmith@*" --case_sensitive false
Get help with list search syntax:
[RHEVM shell (connected)]# list --help
Report a bug
4 .2.2. Show a Resource (show)
Use the show command to display resource properties.
Syntax
show [resource] [id|name] [options]
Table 4 .3. show standard opt ions
Opt ion Descript ion--id [UUID] Identify resource with the resource's UUID value.--name [NAME] Identify resource with the name value.
Chapt er 4 . Commands
21
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 4 .4 . Examples for show
Show virtual machines based upon id :
[RHEVM shell (connected)]# show vm fcadfd5f-9a12-4a1e-bb9b-2b9d5c2e04c3
Show virtual machines based upon name:
[RHEVM shell (connected)]# show vm RHEL6-Server
Report a bug
4 .2.3. Add a Resource (add)
Use the add command to add a new resource.
Syntax
add [resource] [options]
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 4 .5. Examples for add
Create a virtual machine:
[RHEVM shell (connected)]# add vm [vm-options]
Create a user:
[RHEVM shell (connected)]# add user [user-options]
The add command can be made synchronous (if supported) by using the expect option:
[RHEVM shell (connected)]# add vm [vm-options] --expect '201-created'
Report a bug
4 .2.4 . Update a Resource (update)
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
22
Use the update command to modify an existing resource.
Syntax
update [resource] [id|name] [options]
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 4 .6 . Examples for update
Update a virtual machine:
[RHEVM shell (connected)]# update vm RHEL6-Server [vm-options]
Report a bug
4 .2.5. Remove a Resource (remove)
Use the remove command to remove a resource.
Syntax
remove [resource] [id|name] [options]
Table 4 .4 . remove standard opt ions
Opt ion Descript ion--async Perform an asynchronous removal of the resource.--force Perform a force remove of the resource. This removes all
database entries and associations for a particular resource. Thisaction applies only to datacenter and vm resources.
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 4 .7. Examples for remove
Remove a virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server
Asynchronous removal of a virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server --async true
Chapt er 4 . Commands
23
Force remove virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server --force
Report a bug
4 .2.6. Perform Act ion on a Resource (act ion)
Use the action command to perform a special function relevant to resource type.
Syntax
action [resource] [id|name] [action] [options]
Note
Options specific to resource actions are listed in the definition pages for each resource type.
Example 4 .8. Examples for action
Start a virtual machine
[RHEVM shell (connected)]# action vm RHEL6-Server start
Stop a virtual machine:
[RHEVM shell (connected)]# action vm RHEL6-Server stop
The action command can be made synchronous (if supported) by using the async option:
[RHEVM shell (connected)]# action vm [vm-options] --async false
Report a bug
4 .2.7. Using Sub-Resources (--RESOURCE-ident ifier)
Certain resources act as sub-resources of other resources. This means there is a dependentrelationship between the sub-resource and its parent resource. Use the --RESOURCE-identifier [name] option, where RESOURCE is the parent resource type, to target a sub-resource part of aparent resource.
Example 4 .9 . Examples for creat ing sub-resources with add
Create a NIC on a virtual machine:
[RHEVM shell (connected)]# add nic --vm-identifier RHEL6-Server [nic-options]
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
24
Note the use of the --vm-identifier RHEL6-Server option. This adds a NIC on the RHEL6-Server virtual machine.
Create a storage disk on a virtual machine:
[RHEVM shell (connected)]# add disk --vm-identifier RHEL6-Server [user-options]
Note the use of the --vm-identifier RHEL6-Server option. This adds a storage disk on theRHEL6-Server virtual machine.
Report a bug
4.3. Other Commands
4 .3.1. .rhevmshellrc Configurat ion
The .rhevmshellrc config file allows users to configure options for connecting to the rhevm-shell. The.rhevmshellrc file is located by default in /home/[user name]/.rhevmshellrc
Table 4 .5. .rhevmshellrc Parameters
Name Type Descript ionurl string The address of the Red Hat Enterprise Virtualization environment.username string User name to be used to log in.password string Password to be used for user name.insecure boolean Toggles CA certificate requirement. The status is either True or
False.autopage boolean Toggles pagination in the shell. The status is either True or
False.filter boolean Toggles object filtering. Object filtering allows users to fetch
objects according to their permissions. Only admin roles cantoggle filtering off. The status is either True or False.
timeout integer Requests timeout. The default is -1.extended_prompt boolean Toggles the extended prompt option, which displays the
hostname in the shell command prompt
Report a bug
4 .3.2. Connect to VM (console)
Use the console command to open a graphical console to a virtual machine. This command openseither an external VNC or SPICE client based upon the virtual machine's display-type parameter.
Syntax
console [vm-id|vm-name]
Example 4 .10. Example for console
Open graphical console to a virtual machines:
Chapt er 4 . Commands
25
[RHEVM shell (connected)]# console RHEL6-Server
Report a bug
4 .3.3. Run a Shell Command (shell)
Use the shell command to run a command from the Linux shell. This command helps withperforming file management tasks in conjunction with the Red Hat Enterprise Virtualization Managershell.
Syntax
shell [vm-id|vm-name]
Example 4 .11. Examples for shell
List files in current working directory:
[RHEVM shell (connected)]# shell ls
Create a file:
[RHEVM shell (connected)]# shell touch example.txt
Copy a file:
[RHEVM shell (connected)]# shell cp example.txt /example-dir/.
Note
The CLI offers an alternative to the shell using the bang (! ) character. For example:
[RHEVM shell (connected)]# !touch example.txt
Report a bug
4 .3.4 . Run a Script (file)
Use the file command to run a CLI script file. A script is a plain text file that contains a list ofcommands for execution.
Syntax
file [file-location]
Example 4 .12. Example for file
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
26
Run a script file:
[RHEVM shell (connected)]# file /example/example-script
Report a bug
4 .3.5. Clear the Screen (clear)
Use the clear command to clear the CLI screen.
Syntax
clear
Example 4 .13. Example for clear
Clear the screen:
[RHEVM shell (connected)]# clear
Report a bug
4 .3.6. Print Input (echo)
Use the echo command to print input to the screen. Use the $out variable to print the last shellcommand output.
Syntax
echo [input]
Example 4 .14 . Example for echo
Print input:
[RHEVM shell (connected)]# echo "Example text!"
Print last output:
[RHEVM shell (connected)]# echo $out
Report a bug
4 .3.7. Show Last Status (status)
Use the status command to display the most recently run command status.
Syntax
Chapt er 4 . Commands
27
status
Example 4 .15. Example for status
View the last status:
[RHEVM shell (connected)]# status
last command status: 0 (OK)
Report a bug
4 .3.8. Show CLI Informat ion (info)
Use the info command to display environment connection details and version information.
Syntax
info
Example 4 .16 . Example for info
View CLI information:
[RHEVM shell (connected)]# info
backend version: 3.1sdk version : 3.1.0.4cli version : 3.1.0.6python version : 2.7.3.final.0
entry point : https://www.example.com:8443/api
Report a bug
4 .3.9. Show System Summary (summary)
Use the summary command to display a summary of the system status.
Syntax
summary
Example 4 .17. Example for summary
Display system status:
[RHEVM shell (connected)]# summary
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
28
hosts-active : 1hosts-total : 2storage_domains-active: 2storage_domains-total : 3users-active : 1users-total : 1vms-active : 1vms-total : 1
Report a bug
4 .3.10. T est Connect ion (ping)
Use the ping command tests the connection to your Red Hat Enterprise Virtualization Manager. Thecommand retrieves a remote resource and ensures the URL, user name and password for theconnection are correct.
Syntax
ping
Example 4 .18. Example for ping
Test your connection:
[RHEVM shell (connected)]# ping
success: RHEVM manager could be reached OK.
Report a bug
4 .3.11. Exit from the CLI (exit )
Use the exit command to leave a CLI.
Syntax
exit
Example 4 .19 . Example for exit
Leave the CLI:
[RHEVM shell (connected)]# exit
Report a bug
4 .3.12. End of File (EOF)
Chapt er 4 . Commands
29
Use the EOF command to leave the CLI shell using a Ctrl+D sequence.
Syntax
EOF
Example 4 .20. Example for EOF
Leave the CLI shell:
[RHEVM shell (connected)]# EOF
Report a bug
4 .3.13. Show Help (help)
Use the help command displays help for CLI command and resource combinations.
Syntax
help [command] [resource] [options]
Example 4 .21. Examples for help
Get CLI help:
[RHEVM shell (connected)]# help
Get help for the add command:
[RHEVM shell (connected)]# help add
Get help for the add command on the vm resource type:
[RHEVM shell (connected)]# help add vm
Report a bug
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
30
Chapter 5. Resource Types
5.1. brick
Important
The information in this section is provided as a technical preview only.
The brick resource type groups all Gluster bricks in a Red Hat Enterprise Virtualizationenvironment.
Table 5.1. G luster brick parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--server_id string The address of the Gluster server. Yes Yes No--brick_dir string The brick's directory on the Gluster server. Yes Yes No--replica_count
integer
Defines the file replication count for a replicatedvolume.
No Yes No
--stripe_count
Integer
Defines the stripe count for a striped volume No Yes No
The following table lists additional glustervolume options for resource-based commands.
Table 5.2. Addit ional command opt ions
Opt ion Descript ion--cluster-identifier Reference to the cluster that contains a glustervolume sub-
resource.--glustervolume-identifier
Adds the brick to a glustervolume as a sub-resource.
Example 5.1. Creat ing a bricks
[RHEVM shell (connected)]# add brick --cluster-identifier Default --glustervolume-identifier GlusterVol1 --server_id="server1" --brick_dir="/exp1"
Report a bug
5.2. cdrom
The cdrom resource type groups all virtual CD-ROM drive resources in a Red Hat EnterpriseVirtualization environment.
Chapt er 5. Resource T ypes
31
Table 5.3. CD-ROM parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--file-id string Defines the file name of the ISO that resides onan ISO storage domain.
Yes Yes Yes
Example 5.2. Creat ing a new CD-ROM
[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.2-x86_64-dvd.iso.iso
Example 5.3. Updat ing a CD-ROM
[RHEVM shell (connected)]# update cdrom --vm-identifier MyVM --file-id rhel-server-6.3-x86_64-dvd.iso.iso
Example 5.4 . Delet ing a CD-ROM
[RHEVM shell (connected)]# remove cdrom --vm-identifier MyVM rhel-server-6.3-x86_64-dvd.iso.iso
Report a bug
5.3. cluster
The cluster resource type groups all host cluster resources in a Red Hat Enterprise Virtualizationenvironment.
Table 5.4 . Cluster parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--data_center-id|name
string A reference to the data center for a host cluster. Yes Yes No
--name string The name of a host cluster. Yes Yes Yes--version-major
int The major version number of the cluster. Forexample, for Red Hat Enterprise Virtualization3.2, the major version is 3.
Yes Yes Yes
--version-minor
int The minor version number of the cluster. Forexample, for Red Hat Enterprise Virtualization3.2, the minor version is 2.
Yes Yes Yes
--cpu-id string A server CPU reference that defines the CPU typeall hosts must support in the cluster.
Yes Yes Yes
--description
string A description for the host cluster. No Yes Yes
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
32
--memory_policy-overcommit-percent
double
The percentage of host memory allowed in usebefore a host can no longer run any more virtualmachines. Virtual machines can use more thanthe available host memory due to memorysharing under KSM. Recommended valuesinclude 100 (None), 150 (Server Load) and 200(Desktop Load).
No Yes Yes
--memory_policy-transparent_hugepages-enabled
Boolean
Defines the enabled status of TransparentHugepages. The status is either true or false.
No Yes Yes
--scheduling_policy-policy
string The VM scheduling mode for hosts in the cluster,such as evenly_distributed , power_saving or blank for none.
No Yes Yes
--scheduling_policy-thresholds-low
int Controls the lowest CPU usage percentage thehost can have before being consideredunderutilized.
No Yes Yes
--scheduling_policy-thresholds-high
int Controls the highest CPU usage percentage thehost can have before being consideredoverloaded.
No Yes Yes
--scheduling_policy-thresholds-duration
int The number of seconds the host needs to beoverloaded before the scheduler starts andmoves the load to another host.
No Yes Yes
--error_handling-on_error
string Defines virtual machine handling when a hostwithin a cluster becomes non-operational,including migrate, do_not_migrate and migrate_highly_available.
No Yes Yes
--virt_service
Boolean
.The status is either true or false. No Yes Yes
--gluster_service
Boolean
.The status is either true or false. No Yes Yes
--threads_as_cores
Boolean
Hosts treat threads as cores, allowing hosts torun virtual machines with a total number ofprocessor cores greater than the number ofcores in the host. The status is either true or false.
No No No
Name Type Descript ion Required
UserCreatable
UserUpdatable
Chapt er 5. Resource T ypes
33
--expect '201-created'
Request becomes asynchronous until theexpected HTTP header is returned. Useful forlong-running tasks that would otherwise returnas successful before the task is completed.
No No No
--correlation_id
string A tagging identifier of an action for cross-systemlogging. If the client does not define the identifier,one will be generated.
No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
Example 5.5. Creat ing a new cluster
[RHEVM shell (connected)]# add cluster --name Engineering --cpu-id "Intel Penryn Family" --datacenter-name Default --version-major 3 --version-minor 2
Example 5.6 . Updat ing a cluster
[RHEVM shell (connected)]# update cluster Engineering --name Finance
Example 5.7. Delet ing a cluster
[RHEVM shell (connected)]# remove cluster Engineering
Report a bug
5.4 . datacenter
The datacenter resource type groups all data center resources in a Red Hat EnterpriseVirtualization environment.
Table 5.5. Data Center Parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the data center. Yes Yes Yes--storage_type
string The type of storage for the data center, including iscsi , fcp, nfs, localfs or posixfs.
Yes Yes Yes
--version-major
int The major version number of the data center. Forexample, for Red Hat Enterprise Virtualization3.2, the major version is 3.
Yes Yes Yes
--version-minor
int The minor version number of the data center. Forexample, for Red Hat Enterprise Virtualization3.2, the minor version is 2.
Yes Yes Yes
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
34
--description
string A description for the data center. No Yes Yes
--storage_format
string The metadata format for the data center,including v1, v2 or v3.
No Yes Yes
--expect '201-created'
Request becomes asynchronous until theexpected HTTP header is returned. Useful forlong-running tasks that would otherwise returnas successful before the task is completed.
No No No
--correlation_id
string A tagging identifier of an action for cross-systemlogging. If the client does not define the identifier,one will be generated.
No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
Example 5.8. Creat ing a new data center
[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --version-major 3 --version-minor 2
Example 5.9 . Updat ing a data center
[RHEVM shell (connected)]# update datacenter Boston --name India
Example 5.10. Delet ing a data center
[RHEVM shell (connected)]# remove datacenter Boston
Report a bug
5.5. disk
The disk resource type groups all virtual hard disk resources in a Red Hat Enterprise Virtualizationenvironment.
Table 5.6 . Disk parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--provisioned_size
int The reserved storage space for the disk. Thisspace is preallocated for the disk to use, even ifthe disk size is less than the provisioned_size
Yes Yes Yes
--interface string The interface type of the disk. Either ide or virtio .
Yes Yes Yes
Chapt er 5. Resource T ypes
35
--format string The underlying storage format. Copy On Write(cow) allows snapshots, with a smallperformance overhead. Raw (raw) does notallow snapshots, but offers improvedperformance.
Yes Yes Yes
--size int The actual size of the disk. No Yes Yes--sparse Bool
eantrue if the physical storage for the disk shouldnot be preallocated.
No Yes Yes
--bootable Boolean
true if this disk is to be marked as bootable. No Yes Yes
--shareable Boolean
true if this disk is shareable. No Yes Yes
--allow_snapshot
Boolean
true if this disk allows snapshots. No Yes Yes
--propagate_errors
Boolean
true if disk errors should not cause virtualmachine to be paused and, instead, disk errorsshould be propagated to the guest OS.
No Yes Yes
--wipe_after_remove
boolean
true if the underlying physical storage for thedisk should be zeroed when the disk is removed.
No Yes Yes
--storage_domains-storage_domain
collection
Defines a specific storage domain for the disk. No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --storage_domains-storage_domain parameter is a collection that uses the sub-parameters in the following table.
Table 5.7. - -storage_domains-storage_domain parameters
Name Type Descript ionstorage_domain.id|name
string A reference to a storage domain for the disk.
The following table lists additional disk options for resource-based commands.
Table 5.8. Addit ional command opt ions
Opt ion Descript ion--vm-identifier Adds the disk to a vm as a sub-resource.--alias Identifies a disk name when using a show command. Use --
alias instead of the --name parameter for disk-specific queries.
Example 5.11. Creat ing a new disk
[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size 8589934592 --interface virtio --format cow
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
36
Example 5.12. Updat ing a storage domain
[RHEVM shell (connected)]# update disk MyDisk --shareable true
Example 5.13. Delet ing a storage domain
[RHEVM shell (connected)]# remove disk MyDisk
The following table lists actions for a virtual machine disk resource.
Table 5.9 . Virtual machine d isk act ions
Act ion Descript ionactivate Activate a disk on a virtual machine.deactivate Deactivate a disk on a virtual machine.
Report a bug
5.6. glustervolume
Important
The information in this section is provided as a technical preview only.
The glustervolume resource type groups all Gluster storage volume resources in a Red HatEnterprise Virtualization environment.
Table 5.10. G luster vo lume parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the Gluster volume. Yes Yes No--volume_type
string Defines the Gluster volume type. Choose from DISTRIBUTE, REPLICATE, DISTRIBUTED_REPLICATE, STRIPE or DISTRIBUTED_STRIPE.
Yes Yes No
--bricks-brick
collection
A new Gluster volume requires a set of Glusterbricks to add and manage. This parameterreferences a collection of brick details. Specify atleast one brick but list multiple bricks-brickparameters for multiple bricks. See below forcollection details.
Yes Yes No
--transport_types
collection
A reference to available transport methods for theGluster volume. See below for collection details.
No Yes No
Chapt er 5. Resource T ypes
37
--replica_count
integer
Defines the file replication count for a replicatedvolume.
No Yes No
--stripe_count
Integer
Defines the stripe count for a striped volume No Yes No
--options-option
collection
A reference to options for the Gluster volume. Seebelow for collection details.
No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --bricks-brick parameter is a collection that uses the sub-parameters in the following table.
Table 5.11. bricks-brick parameters
Name Type Descript ionbrick.server_id string The address of the Gluster server.brick.brick_dir
string The brick's directory on the Gluster server.
The --transport_types parameter is a collection that uses the sub-parameters in the followingtable.
Table 5.12. t ransport_types parameters
Name Type Descript iontransport_type string Defines a transport type to use. Specify multiple
transport_type parameters for more than one type. Choosefrom TCP and RDMA.
The --options-option parameter is a collection that uses the sub-parameters in the followingtable.
Table 5.13. opt ions-opt ion parameters
Name Type Descript ionoption.name string The Gluster option name.option.value string The Gluster option value.
The following table lists additional glustervolume options for resource-based commands.
Table 5.14 . Addit ional command opt ions
Opt ion Descript ion--cluster-identifier Adds the Gluster volume to a cluster as a sub-resource.
Example 5.14 . Creat ing a G luster vo lume with two bricks
[RHEVM shell (connected)]# add glustervolume --cluster-identifier Default --name GlusterVol1 --volume-type DISTRIBUTE --bricks-brick "brick.server_id=UUID,brick.brick_dir=filepath"--bricks-brick "brick.server_id=UUID,brick.brick_dir=filepath"
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
38
Example 5.15. Delet ing a G luster vo lume
[RHEVM shell (connected)]# remove glustervolume --cluster-identifier Default --name GlusterVol1
The following table lists actions for a Gluster volume resource.
Table 5.15. G luster vo lume act ions
Act ion Descript ionstart Makes a Gluster volume available for use.stop Deactivates a Gluster volume.setOption Sets a Gluster volume option.resetOption Resets a Gluster volume option to the default.resetAllOptions Resets all Gluster volume options to defaults.
Report a bug
5.7. group
The group resource type defines all identity service groups for a Red Hat Enterprise Virtualizationenvironment.
Table 5.16 . Group parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the group, usually the full grouppath within the identity directory service.
No No No
Example 5.16 . Creat ing a group
[RHEVM shell (connected)]# add group --name www.example.com/accounts/groups/mygroup
Report a bug
5.8. host
The host resource type groups all host resources in a Red Hat Enterprise Virtualization environment.
Table 5.17. Host parameters
Chapt er 5. Resource T ypes
39
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the host. Yes Yes Yes--address string The IP address or hostname for the host. Yes Yes Yes--root_password
string The password for the host's root user. Yes Yes Yes
--cluster-id|name
string Defines the cluster that includes the host. Yes Yes Yes
--port int The port for communication with the VDSMdaemon running on the host.
No Yes Yes
--storage_manager-priority
int Sets the priority of host order for storage poolmanager (SPM).
No Yes Yes
--power_management-type
string The fencing device code for host powermanagement.
No Yes Yes
--power_management-enabled
boolean
Indicates whether power managementconfiguration is enabled or disabled.
No Yes Yes
--power_management-address
string The host name or IP address of the powermanagement device.
No Yes Yes
--power_management-user_name
string A valid user name for power management. No Yes Yes
--power_management-password
string A valid, robust password for power management. No Yes Yes
--power_management-options-option
collection
Fencing options for the selected power_management-type.
No Yes Yes
--reboot_after_installation
boolean
Defines if the host reboots after VDSMinstallation.
No Yes No
The --power_management-options-option parameter is a collection that uses the sub-parameters in the following table.
Table 5.18. - -power_management -opt ions-opt ion parameters
Name Type Descript ionoption.name string Power management option name.option.value string Power management option value.
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4 0
Example 5.17. Creat ing a new host
[RHEVM shell (connected)]# add host --name Host1 --address host1.example.com --root_password p@55w0rd! --cluster-name Default
Example 5.18. Updat ing a host
[RHEVM shell (connected)]# update host Host1 --name Host2
Example 5.19 . Delet ing a host
[RHEVM shell (connected)]# remove host Host1
The following table lists actions for a host resource.
Table 5.19 . Host act ions
Act ion Descript ionactivate Activate a host.approve Approve a host.commitnetconfig Save the network configuration.deactivate Deactivate a host.fence Fence a host.forceselectspm Select the host to be the Storage Pool Manager.install Install VDSM on a host.iscsidiscover Perform an iSCSI discover command.iscsilogin Perform an iSCSI login command.
The following table lists additional options for the fence action.
Table 5.20. Fencing opt ions
Opt ion Descript ionmanual Manually fence the host. Use this action to confirm to the
Manager that the host became non-responsive and was manuallyrebooted.
restart Restart the host, implemented as stop, wait, status, start, wait,status.
start Power on the host.stop Power off the host.status Check the operational status of the host.
Report a bug
5.9. network
The network resource type groups all logical network resources in a Red Hat EnterpriseVirtualization environment.
Chapt er 5. Resource T ypes
4 1
Table 5.21. Logical network parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--data_center-id|name
string A reference to the data center for a logicalnetwork.
Yes Yes No
--name string A plain text name for the logical network. Yes Yes No--description
string A description for the logical network. No Yes Yes
--vlan-id string A VLAN tag. No Yes Yes--ip-address
string The IP address for the logical network's bridge. No Yes Yes
--ip-gateway
string The gateway for the logical network's bridge. No Yes Yes
--ip-netmask
string The netmask for the logical network's bridge. No Yes Yes
--display boolean
Signifies if a logical network is used for displaycommunication usage. Set to either true or false.
No Yes Yes
--stp boolean
Set to true if Spanning Tree Protocol is enabledon this network.
No Yes Yes
--mtu int Sets a user-defined value for the maximumtransmission unit of the logical network.
No Yes Yes
--usages-usage
collection
Defines usage parameters for the logicalnetwork.
No No Yes
The --usages-usage parameter is a collection that uses the sub-parameters in the following table.
Table 5.22. usages-usage parameters
Name Type Descript ionusage string Usage types for the network. Options include VM and DISPLAY .
The following table lists additional network options for resource-based commands.
Table 5.23. Addit ional command opt ions
Opt ion Descript ion--cluster-identifier Adds the network to a cluster as a sub-resource.
Example 5.20. Creat ing a new network
[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name Default --cluster-identifier Default
Example 5.21. Updat ing a network
[RHEVM shell (connected)]# update network WebNetwork --name DataNetwork
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4 2
Example 5.22. Delet ing a network
[RHEVM shell (connected)]# remove network WebNetwork
Report a bug
5.10. nic
The nic resource type groups network interface resources in a Red Hat Enterprise Virtualizationenvironment. These resources acts as sub-resources for both host and vm resources but are defineddifferently for each. This section contains two tables with parameters for each.
Table 5.24 . Host network in terface parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--network-id|name
string A reference to the network, if any, that theinterface is attached.
Yes Yes Yes
--name string The name of the host network interface, e.g. eth0 .
Yes Yes Yes
--bonding-slaves-host_nic
collection
A collection of slave network interfaces that forma bonded interface.
No Yes Yes
--bonding-options-option
collection
A list of options for a bonded interface. Eachoption contains property name and valueattributes.
No Yes Yes
--ip-gateway
string The IP address for the network's gateway. No Yes Yes
--boot_protocol
string The protocol for IP address assignment when thehost is booting, such as dhcp or static.
No Yes Yes
--mac string The MAC address of the interface. No Yes Yes--ip-address
string The IP address of the interface. No Yes Yes
--ip-netmask
string The netmask for the interface's IP address. No Yes Yes
--ip-mtu int The maximum transmission unit for the interface. No No Yes
Table 5.25. Virtual Machine network in terface parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--network-id|name
string A reference to the network, if any, that theinterface is attached.
Yes Yes Yes
--name string The name of the interface, e.g. eth0 . Yes Yes Yes--mac-address
string The MAC address of the interface. No Yes Yes
--interface string Defines the interface type, such as e1000 , virtio , rtl8139 and rtl8139_virtio .
No Yes Yes
Chapt er 5. Resource T ypes
4 3
--port_mirroring-networks-network
collection
Defines a set of networks to copy (mirror)network data from the network interface.
No Yes Yes
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --bonding-slaves-host_nic parameter is a collection that uses the sub-parameters in thefollowing table.
Table 5.26 . - -bonding-slaves-host_nic
Name Type Descript ionhost_nic.id|name
string A reference to another host NIC to bond.
The --bonding-options-option parameter is a collection that uses the sub-parameters in thefollowing table.
Table 5.27. - -bonding-opt ions-opt ion
Name Type Descript ionoption.name string The bonding option name.option.value string The bonding option value.type string The bonding option type.
The --port_mirroring-networks-network parameter is a collection that uses the sub-parameters in the following table.
Table 5.28. - -port_mirroring-networks-network
Name Type Descript ionnetwork.id string A reference to the network to mirror.
The following table lists additional NIC options for resource-based commands.
Table 5.29 . Addit ional command opt ions
Opt ion Descript ion--host-identifier Adds the NIC to a host as a sub-resource.--vm-identifier Adds the NIC to a vm as a sub-resource.
Example 5.23. Creat ing a new network in terface on a host
[RHEVM shell (connected)]# add nic --host-identifier MyHost1 --name eth0 --network MyNetwork
Example 5.24 . Creat ing a new network in terface on a virtual machine
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4 4
[RHEVM shell (connected)]# add nic --vm-identifier MyVM1 --name eth0 --network MyNetwork
Example 5.25. Updat ing a network in terface
[RHEVM shell (connected)]# update nic eth0 --vm-identifier MyVM1 --ip-address 10.5.68.123
Example 5.26 . Delet ing a network in terface
[RHEVM shell (connected)]# remove nic eth0 --vm-identifier MyVM1
The following table lists actions for a host NIC resource.
Table 5.30. Host NIC act ions
Act ion Descript ionattach Attach a NIC to a host.detach Detach a NIC from a host.
The following table lists actions for a virtual machine NIC resource.
Table 5.31. Virtual machine NIC act ions
Act ion Descript ionactivate Activate a NIC on a virtual machine.deactivate Deactivate a NIC on a virtual machine.
Report a bug
5.11. permission
The permission resource type groups all permission resources in a Red Hat EnterpriseVirtualization environment.
Table 5.32. Permission parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--user-identifier, --group-identifier
string A reference to the user or group using thepermission.
Yes Yes No
--role-id string A reference to a role to assign for the permission. Yes Yes No
The following table lists additional permission options for resource-based commands.
Table 5.33. Addit ional command opt ions
Chapt er 5. Resource T ypes
4 5
Opt ion Descript ion--cluster-identifier Adds the permission to a cluster.--datacenter-identifier Adds the permission to a data center.--disk-identifier Adds the permission to a disk.--host-identifier Adds the permission to a host.--network-identifier Adds the permission to a network.--storagedomain-identifier
Adds the permission to a storage domain.
--template-identifier Adds the permission to a template.--vm-identifier Adds the permission to a virtual machine.--vmpool-identifier Adds the permission to a virtual machine pool.--vnicprofile-identifier
Adds the permission to a VNIC profile.
Example 5.27. Creat ing a new permission
[RHEVM shell (connected)]# add permission --vm-identifier MyVM1 --role-id 00000000-0000-0000-0000-000000000001 --user-id 8b9456ae-e2c8-426e-922d-b01bb8a805fb --data_center-id 5849b030-626e-47cb-ad90-3ce782d831b3
Report a bug
5.12. permit
The permit resource type groups all individual permits for roles in a Red Hat EnterpriseVirtualization environment.
Table 5.34 . Permission parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--id string A reference to the permit to add. Yes Yes No
The following table lists additional permit options for resource-based commands.
Table 5.35. Addit ional command opt ions
Opt ion Descript ion--role-identifier Adds the permit to a role.
Example 5.28. Creat ing a new permission
[RHEVM shell (connected)]# add permit --role-identifier MyRole --id 1
Report a bug
5.13. quotas
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4 6
5.13. quotas
Important
The information in this section is provided as a technical preview only.
The quota resource type groups all datacenter quotas in a Red Hat Enterprise Virtualizationenvironment.
Table 5.36 . Quota parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the quota. Yes Yes Yes--description
string A description for the quota. Yes Yes Yes
Report a bug
5.14. role
The role resource type groups all individual roles in a Red Hat Enterprise Virtualizationenvironment.
Table 5.37. Role parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the role. Yes Yes Yes--permits-permit
collection
A list of permits for initial inclusion with the role.Additional permits included with the permitresource type.
Yes Yes No
--description
string A description for the role. No Yes Yes
--administrative
Boolean
Set to true if this is an administrative role. No Yes Yes
The --permits-permit parameter is a collection that uses the sub-parameters in the followingtable.
Table 5.38. - -permits-permit parameters
Name Type Descript ionpermit.id string A reference to a permit to add to the role's permits.
Example 5.29 . Creat ing a new ro le
Chapt er 5. Resource T ypes
4 7
[RHEVM shell (connected)]# add role --name MyRole --permits-permit {permit.id: 1;},{permit.id: 2;)
Report a bug
5.15. snapshot
The snapshot resource type groups all virtual machine snapshot resources in a Red Hat EnterpriseVirtualization environment.
Table 5.39 . Snapshot parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--description
string A description for the snapshot. Yes Yes No
The following table lists additional snapshot options for resource-based commands.
Table 5.4 0. Addit ional command opt ions
Opt ion Descript ion--vm-identifier Adds the disk to a vm as a sub-resource.
Example 5.30. Creat ing a new snapshot
[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description 'My Snapshot'
Example 5.31. Delet ing a storage domain
[RHEVM shell (connected)]# remove snapshot [snapshot_id]
The following table lists actions for a virtual machine snapshot resource.
Table 5.4 1. Virtual machine snapshot act ions
Act ion Descript ionrestore Restore a snapshot.
Report a bug
5.16. storageconnect ion
The storageconnection resource type allows you to add, edit, and delete storage connections.
Table 5.4 2. Storage connect ion parameters
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
4 8
Name Type Descript ion Required
UserCreatable
UserUpdatable
--address string The hostname or IP address of the storagedomain.
Yes(NFSandiSCSIonly)
Yes Yes
--correlation_id
string A tagging identifier for the storage connection. No No Yes
--expect '201-created'
Request becomes asynchronous until theexpected HTTP header is returned. Useful forlong-running tasks that would otherwise returnas successful before the task is completed.
No No No
--iqn string The target IQN for the storage device. Yes(iSCSI only)
Yes Yes
--mount_options
string The options for mounting the PosixFS share. No Yes Yes
--nfs_retrans
integer
The number of retransmissions the NFS clientwill attempt to complete a request.
No Yes Yes
--nfs_timeo integer
The amount of time, in deciseconds, the NFSclient will wait for a request to complete.
No Yes Yes
--nfs_version
string The version of NFS used. No Yes Yes
--password string A CHAP password for logging into a target of aniSCSI storage domain.
No Yes Yes
--path string The mounted file path of the storage domain. Thepath cannot be updated to one already used bya storage connection.
Yes(NFS,local,andPosixFSonly)
Yes Yes
--port integer
The TCP port used for the iSCSI storage domain. Yes(iSCSI only)
Yes Yes
--storagedomain-identifier
string A reference to a storage domain for the disk. No No No
--type string The type of storage domain. Yes Yes No--username string A CHAP user name for logging into a target of an
iSCSI storage domain.No Yes Yes
--vfs_type string The Linux-supported file system type of thePosixFS share.
Yes(PosixFSonly)
Yes Yes
Example 5.32. Creat ing a new storage connect ion
Chapt er 5. Resource T ypes
4 9
[RHEVM shell (connected)]# add storageconnection --address storage.example.com --path /storage/nfs --type nfs
Report a bug
5.17. storagedomain
The storagedomain resource type groups all storage domain resources in a Red Hat EnterpriseVirtualization environment.
Table 5.4 3. Storage domain parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the storage domain. No Yes Yes--format Boole
anThe metadata format for the data center,including v1, v2 or v3.
Yes Yes No
--host-id|name
string A reference to the host from which this storagedomain should be initialized. The only restrictionon this host is that it should have access to thephysical storage specified.
Yes Yes No
--storage-address
string The IP address or hostname of the storagedevice.
Yes Yes No
--storage-logical_unit
collection
The logical unit information of the storagedevice.
Seebelow
Yes No
--storage-mount_options
string The options for mounting the storage domain. Seebelow
Yes No
--storage-override_luns
Boolean
Defines whether to override the logical unitnumber. The status is either true or false.
Seebelow
Yes No
--storage-path
string The path on the storage device to use for thestorage domain.
Seebelow
Yes No
--storage-type
string The type of storage for the data center, including iscsi , fcp, nfs, localfs or posixfs.
Yes Yes No
--storage-vfs_type
string Defines the file system type of the storagedomain.
Seebelow
Yes No
--type string The type of storage domain, including data, iso and export.
Yes Yes No
The --storage-logical_unit parameter is a collection that requires all sub-parameters in thefollowing table.
Table 5.4 4 . storage- logical_unit parameters
Name Type Descript ionlogical_unit.address
string The address of the server containing the storage device.
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
50
logical_unit.port
integer The port number of the server.
logical_unit.target
string The target IQN for the storage device.
logical_unit.username
string A CHAP user name for logging into a target.
logical_unit.password
string A CHAP password for logging into a target.
logical_unit.serial
string The serial ID for the target.
logical_unit.vendor_id
string The vendor name for the target.
logical_unit.product_id
string The product code for the target.
logical_unit.lun_mapping
integer The Logical Unit Number device mapping for the target.
logical_unit.portal
string The logical unit portal.
logical_unit.paths
integer The logical unit paths.
logical_unit.id
string A reference to the logical unit ID.
Name Type Descript ion
Use the following parameters depending on storage-type.
Table 5.4 5. Storage type parameters
Type Parametersnfs --storage-address, --storage-pathiscsi or fcp --storage-address, --storage-logical_unit, --storage-
override_luns
local --storage-path
posixfs --storage-path, --storage-vfs_type, --storage-address, --storage-mount_options
The following table lists additional storagedomain options for resource-based commands.
Table 5.4 6 . Addit ional command opt ions
Opt ion Descript ion--datacenter-identifier Adds the storage domain to a datacenter as a sub-resource.
Example 5.33. Creat ing a new storage domain
[RHEVM shell (connected)]# add storagedomain --name DataStorage --datacenter-name Default -type data
Example 5.34 . Updat ing a storage domain
Chapt er 5. Resource T ypes
51
[RHEVM shell (connected)]# update storagedomain DataStorage --name DataStorageOld
Example 5.35. Delet ing a storage domain
[RHEVM shell (connected)]# remove storagedomain DataStorage
The following table lists actions for a storage domain resource.
Table 5.4 7. Storage domain act ions
Act ion Descript ionactivate Activate a storage domain on a data center.deactivate Deactivate a storage domain on a data center.
Report a bug
5.18. t ag
The tag resource type groups all tags in a Red Hat Enterprise Virtualization environment.
Table 5.4 8. Tag parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the tag. Yes Yes Yes--description
string A description for the string. Yes Yes Yes
--parent-name
string A reference to the parent tag that the tag isattached.
Yes Yes Yes
Example 5.36 . Creat ing a new tag
[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine tag" --parent MyParentTag
Report a bug
5.19. t emplate
The template resource type groups all virtual machine templates in a Red Hat EnterpriseVirtualization environment.
Table 5.4 9 . Template parameters
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
52
Name Type Descript ion Required
UserCreatable
UserUpdatable
--vm-id|name
string A reference to the virtual machine used as abasis for the template.
Yes Yes No
--name string The name of the virtual machine template. Yes Yes Yes--memory long The amount of memory for the virtual machine
template in bytes.No Yes Yes
--cpu-topology-cores
int The number of CPU cores available to the virtualmachine template.
No Yes Yes
--high_availability-enabled
Boolean
Defines if high availability is enabled for thevirtual machine template.
No Yes Yes
--os-cmdline
string A kernel command line parameter string to beused with the defined kernel. This optionsupports booting a Linux kernel directly ratherthan through the BIOS bootloader.
No Yes Yes
--origin string The virtual machine template's origin, including rhev, vmware or xen.
No Yes Yes
--high_availability-priority
int Sets the priority value (i.e. boot order) of eachvirtual machine template's high availability.
No Yes Yes
--timezone string The the Sysprep timezone setting for a Windowsvirtual machine template.
No Yes Yes
--domain-name
string The domain name of the virtual machinetemplate.
No Yes Yes
--type string Defines the virtual machine type. Either desktopor server.
No Yes Yes
--stateless boolean
true if the resulting virtual machines arestateless. A stateless virtual machine contains asnapshot of its disk image taken at boot andremoved at shutdown. This means state changesdo not persist after a reboot.
No Yes Yes
--placement_policy-affinity
string The migration affinity for each virtual machinecreated from the template. Includes migratable, user_migratable or pinned .
No Yes Yes
--description
string A description for the template. No Yes Yes
--custom_properties-custom_property
collection
A set of user-defined environment variablespassed as parameters to custom scripts.
No Yes Yes
--os-type string The operating system type for this virtualmachine template.
No Yes Yes
--os-boot-dev
string The boot device for the virtual machine template,including cdrom, hd , network.
No Yes Yes
Chapt er 5. Resource T ypes
53
--cpu-topology-sockets
int The number of CPU sockets available to thevirtual machine template.
No Yes Yes
--os-kernel string A path to a kernel image the resulting virtualmachines are configured to boot. This optionsupports booting a Linux kernel directly ratherthan through the BIOS bootloader.
No Yes Yes
--display-type
string Defines the display type, including spice or vnc.
No Yes Yes
--display-monitors
int Defines the number of displays available. No Yes Yes
--display-allow_reconnect
Boolean
Defines whether to allow reconnection viaconsole display.
No Yes Yes
--os-initRd string A path to an initrd image to be used with aspecified kernel. This option supports booting aLinux kernel directly rather than through theBIOS bootloader.
No Yes Yes
--usb-enabled
Boolean
Defines the USB policy for a virtual machine. Setto true to enable USB on the virtual machine.
No Yes Yes
--usb-type string Defines the USB type if enabled. No Yes Yes--vm-disks-disk
collection
References to disks attached to the template. No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Table 5.50. - -custom_propert ies-custom_property parameters
Name Type Descript ioncustom_property.name
string The custom property name.
custom_property.value
string The custom property value.
The --vm-disks-disk parameter is a collection that uses the sub-parameters in the followingtable.
Table 5.51. - -vm-disks-d isk parameters
Name Type Descript iondisk.id string A reference to a virtual machine disk.storage_domains.storage_domain
collection
Defines a set of sub-parameters for the disk's storage domain.
Example 5.37. Creat ing a new template
[RHEVM shell (connected)]# add template --name MyTemplate1 --vm-name MyVM1
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
54
Example 5.38. Updat ing a template
[RHEVM shell (connected)]# update template MyTemplate1 --memory 1073741824
Example 5.39 . Delet ing a template
[RHEVM shell (connected)]# remove template MyTemplate1
The following table lists actions for a virtual machine template resource.
Table 5.52. Virtual machine template act ions
Act ion Descript ionexport Export a template to an export storage domain.
Report a bug
5.20. user
The user resource type groups all users in a Red Hat Enterprise Virtualization environment.
Table 5.53. User parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--user_name string The user name from the directory service. Yes Yes No--domain-id|name
string A reference to the directory service domain. Yes Yes No
Example 5.4 0. Creat ing a new user
[RHEVM shell (connected)]# add user --user_name jsmith --domain-name example.com
Report a bug
5.21. vm
The vm resource type groups all virtual machine resources in a Red Hat Enterprise Virtualizationenvironment.
Table 5.54 . Virtual machine parameters
Chapt er 5. Resource T ypes
55
Name Type Descript ion Required
UserCreatable
UserUpdatable
--cluster-id|name
string A reference to the cluster that includes thisVM.
Yes Yes Yes
--cpu-topology-cores
int The number of CPU cores available to thevirtual machine.
No Yes Yes
--cpu-topology-sockets
int The number of CPU sockets available to thevirtual machine.
No Yes Yes
--custom_properties-custom_property
collection A set of user-defined environment variablepassed as parameters to custom scripts.
No Yes Yes
--description
string A description of the virtual machine. No Yes Yes
--disks-clone
Boolean Defines whether to clone the disk from thedefined template.
No Yes No
--display-allow_reconnect
Boolean Defines whether to allow reconnection viaconsole display.
No Yes Yes
--display-monitors
int Defines the number of displays available. No Yes Yes
--display-type
string Defines the display type, including spiceor vnc.
No Yes Yes
--domain-name
string The domain name of the virtual machine. No Yes Yes
--high_availability-enabled
Boolean Defines if high availability is enabled for thevirtual machine.
No Yes Yes
--high_availability-priority
int Sets the priority value (migration and restartorder) of each virtual machine using highavailability.
No Yes Yes
--memory long The amount of memory for the virtualmachine in bytes.
No Yes Yes
--name string The name of the virtual machine Yes Yes Yes--origin string The virtual machine's origin, including
rhev, vmware or xen.No Yes Yes
--os-boot-dev
string The boot device for the virtual machine,including cdrom, hd , network.
No Yes Yes
--os-cmdline
string A kernel command line parameter string tobe used with the defined kernel. This optionsupports booting a Linux kernel directlyrather than through the BIOS bootloader.
No Yes Yes
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
56
--os-initRd
string A path to an initrd image to be used with aspecified kernel. This option supportsbooting a Linux kernel directly rather thanthrough the BIOS bootloader.
No Yes Yes
--os-kernel
string A path to a kernel image the virtual machineis configured to boot. This option supportsbooting a Linux kernel directly rather thanthrough the BIOS bootloader.
No Yes Yes
--os-type string The operating system type for this virtualmachine.
No Yes Yes
--payloads-payload
collection Defines content to send to the virtualmachine upon booting.
No Yes Yes
--placement_policy-affinity
string The migration affinity for each virtualmachine, including migratable, user_migratable or pinned .
No Yes Yes
--placement_policy-host-id|name
string A reference to the preferred host formigration affinity.
No Yes Yes
--quota-id
string A reference to the quota usage for the virtualmachine.
No Yes No
--stateless
Boolean true if the virtual machine is stateless. Astateless virtual machine contains asnapshot of its disk image taken at boot andremoved at shutdown. This means statechanges do not persist after a reboot.
No Yes Yes
--template-id|name
string A reference to the template used as the basisfor the virtual machine.
Yes Yes No
--timezone
string The the Sysprep timezone setting for aWindows virtual machine.
No Yes Yes
--type string Defines the virtual machine type. Either desktop or server.
No Yes Yes
--usb-enabled
Boolean Defines the USB policy for a virtualmachine. Set to true to enable USB on thevirtual machine.
No Yes Yes
--usb-type string Defines the USB type if enabled. No Yes Yes--expect '201-created' Request becomes asynchronous until the
expected HTTP header is returned. Usefulfor long-running tasks that would otherwisereturn as successful before the task iscompleted.
No No No
--correlation_id
string A tagging identifier of an action for cross-system logging. If the client does not definethe identifier, one will be generated.
No Yes No
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Chapt er 5. Resource T ypes
57
Table 5.55. - -custom_propert ies-custom_property parameters
Name Type Descript ioncustom_property.name
string The custom property name.
custom_property.value
string The custom property value.
The --payloads-payload parameter is a collection that uses the sub-parameters in the followingtable.
Table 5.56 . - -payloads-payload parameters
Name Type Descript ionpayload.type string Payload delivery type, including cdrom or floppy.payload.file.name
string The payload file name and location on the root file system of thevirtual machine.
payload.file.content
string The content to deliver to the file.
Example 5.4 1. Creat ing a new virtual machine
[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-name Default --memory 536870912
Example 5.4 2. Updat ing a virtual machine
[RHEVM shell (connected)]# update vm MyVM --memory 1073741824
Example 5.4 3. Delet ing a virtual machine
[RHEVM shell (connected)]# remove vm MyVM
The following table lists actions for a virtual machine resource.
Table 5.57. Virtual machine act ions
Act ion Descript ionstart Launch a virtual machine.stop Stop a virtual machine.shutdown Shutdown a virtual machine.suspend Suspend a virtual machine.detach Detach a virtual machine from a pool.migrate Migrate the virtual machine to another host.cancelmigration Stop migration in progressexport Export a virtual machine to an export storage domainmove Move virtual machine disks to another storage domain.ticket Create a ticket for console access.
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
58
Report a bug
5.22. vmpool
The vmpool resource type groups all virtual machine pool resources in a Red Hat EnterpriseVirtualization environment.
Table 5.58. Virtual machine pool parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--cluster-id|name
string A reference to the cluster for the virtual machinepool.
Yes Yes Yes
--template-id|name
string A reference to the template for the virtual machinepool.
Yes Yes Yes
--name string The name of the virtual machine pool. Yes Yes Yes--size intege
rThe number of the virtual machines in the pool. Yes Yes Yes
Example 5.4 4 . Creat ing a new virtual machine pool
[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-name MyTemplate --name MyPool --size 3
Example 5.4 5. Updat ing a virtual machine pool
[RHEVM shell (connected)]# update vmpool MyPool --size 4
Example 5.4 6 . Delet ing a virtual machine pool
[RHEVM shell (connected)]# remove vmpool MyPool
Report a bug
5.23. vnicprofile
The vnicprofile resource type groups all VNIC (virtual network interface controller) profiles, alsoreferred to as VM (virtual machine) interface profiles, in a Red Hat Enterprise Virtualizationenvironment.
Table 5.59 . Virtual Network In terface Contro ller Prof ile Parameters
Name Type Descript ion Required
UserCreatable
UserUpdatable
--name string The name of the VNIC profile. Yes Yes Yes
Chapt er 5. Resource T ypes
59
--network-id
string A reference to the logical network to which theprofile will be applied.
Yes No No
--correlation_id
string A tagging identifier of an action for cross-systemlogging. If the client does not define the identifier,one will be generated.
No Yes No
--description
string A description for the profile. No Yes Yes
--expect '201-created'
Request becomes asynchronous until theexpected HTTP header is returned. Useful forlong-running tasks that would otherwise returnas successful before the task is completed.
No No No
--custom_properties-custom_property
collection
A set of user-defined environment variablespassed as parameters to custom scripts.
No Yes Yes
--port_mirroring
Boolean
Toggles whether port mirroring is used for theprofile. The status is either True or False.Default is Falses
No No No
Name Type Descript ion Required
UserCreatable
UserUpdatable
The --custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Table 5.6 0. - -custom_propert ies-custom_property parameters
Name Type Descript ioncustom_property.name
string The custom property name.
custom_property.value
string The custom property value.
Example 5.4 7. Creat ing a new vnic prof ile
[RHEVM shell (connected)]# add vnicprofile --name Gold --network-id 08305a2f-6952-4999-9646-c16137dc6d42
Example 5.4 8. Updat ing a vnic prof ile
[RHEVM shell (connected)]# update vnicprofile Gold --port_mirroring true
Example 5.4 9 . Delet ing a vnic prof ile
[RHEVM shell (connected)]# remove vnicprofile Gold
Report a bug
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
60
Chapter 6. CLI Queries
6.1. Query Syntax
The CLI list command uses the --query attribute to perform server-side queries, which uses thesame format as Red Hat Enterprise Virtualization Manager search query language:
Table 6 .1. Example search queries
Collect ion Criteria Resulthosts vms.status=up Displays a list of all hosts
running virtual machines thatare up.
vms domain=qa.company.com Displays a list of all virtualmachines running on thespecified domain.
vms users.name=mary Displays a list of all virtualmachines belonging to userswith the user name mary.
events severity>normal sortby time
Displays the list of all eventswith severity higher than normal and sorted by the time element values.
events severity>normal sortby time desc
Displays the list of all eventswith severity higher than normal and sorted by the time element values indescending order.
Report a bug
6.2. Wildcards
Search queries substitute part of a value with an asterisk as a wildcard.
Example 6 .1. Wildcard search query for name= vm*
[RHEVM shell (connected)]# list vms --query "name=vm*"
This query would result in all virtual machines with names beginning with vm, such as vm1, vm2, vma or vm-webserver.
Example 6 .2. Wildcard search query for name= v*1
[RHEVM shell (connected)]# list vms --query "name=v*1"
This query would result in all virtual machines with names beginning with v and ending with 1,such as vm1, vr1 or virtualmachine1.
Chapt er 6 . CLI Queries
61
Report a bug
Red Hat Ent erprise Virt ualizat ion 3.3 Command Line Shell Guide
62
Revision History
Revision 3.3-10 Tue 09 Dec 2014 Andrew BurdenBZ#1142384 - Removed reference to Admin Guide search syntax; replaced with example showingsyntax.BZ#1142372 - Corrected the 'user_name' parameter and the example usage of 'domain-name'.BZ#1142345 - Fixed example so that it correctly uses UUIDs instead of names. Made contents oftables match reality
Revision 3.3-9 Thu 13 Mar 2014 Andrew BurdenBZ#1055327 - Added examples to 'storageconnection' section.
Revision 3.3-8 Mon 24 Feb 2014 Andrew BurdenBZ#1055327 - Added resource type 'storageconnection'.
Revision 3.3-7 Wed 19 Feb 2014 Andrew DahmsBZ#1039880 - Updated the command for exporting certificates from truststores.
Revision 3.3-6 Fri 06 Dec 2013 Andrew DahmsBZ#1038837 - Changed references to 'version.number' to '3.3'.
Revision 3.3-5 Mon 14 Oct 2013 Red Hat EngineeringContent Services
BZ#999431 - Added table 'Fencing options' to host resource section.
Revision 3.3-4 Thu 10 Oct 2013 Andrew BurdenBZ#1016953 - New section 'vnicprofile' added.
Revision 3.3-3 Tue 20 Aug 2013 Andrew BurdenBZ#976628 - Documented the '--extended-prompt' option for the rhevm-shell.BZ#998378 - Documented the 'forceselectspm' host action for manually selecting SPM.BZ#976618 - New topic for 'summary' command.
Revision 3.3-2 Thu 15 Aug 2013 Andrew BurdenBZ#887860 - updated async and sync options for resources.
Revision 3.3-1 Thu 18 Jul 2013 Tim HildredInitial creation for Red Hat Enterprise Virtualization 3.3 release.
Revision Hist ory
63
