Andrew Burden
Dan Macpherson
Red Hat Enterprise Virtualization
3.2
Command Line Shell Guide
A Guide for Installing and Using the Command Line Shell for Red Hat
Enterprise Virtualization
Edition 1
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
A Guide for Installing and Using the Command Line Shell for Red Hat
Enterprise Virtualization
Edition 1
Andrew Burden
aburden@redhat.co m
Dan Macpherso n
dmacpher@redhat.co m
Legal Notice
Copyright © 2013 Red Hat, Inc.
This document is licensed by Red Hat under the
Creative Commons Attribution-ShareAlike 3.0 Unported
. If you distribute this document, or a modified version of it, you must provide attribution to Red
Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be
removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section
4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo,
and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and other
countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or
endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack Logo are either registered trademarks/service marks or
trademarks/service marks of the OpenStack Foundation, in the United States and other countries 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 other trademarks are the property of their respective owners.
Abstract
This following guide contains information for installing and using the Red Hat Enterprise Virtualization
Manager Command Line Shell
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table of Contents
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. We Need Feedback!
Chapter 1. About the Command Line Interface
1.1. Introduction to the Command Line Interface
2.1. Installing the CLI
2.2. TLS/SSL Certification
2.3. Running the CLI
2.4. Interacting with the CLI
2.5. Collections
Chapter 3. Quick Start Example
3.1. Creating a Basic Virtualization Environment with the CLI
4.1.1. Connect to RHEVM (connect)
4.1.2. Disconnect from RHEVM (disconnect)
4.2.1. List Resources in a Collection (list)
4.2.2. Show a Resource (show)
4.2.3. Add a Resource (add)
4.2.4. Update a Resource (update)
4.2.5. Remove a Resource (remove)
4.2.6. Perform Action on a Resource (action)
4.2.7. Using Sub-Resources (--RESOURCE-identifier)
4.3.1. .rhevmshellrc Configuration
4.3.2. Connect to VM (console)
4.3.3. Run a Shell Command (shell)
4.3.4. Run a Script (file)
4.3.5. Clear the Screen (clear)
4.3.6. Print Input (echo)
4.3.7. Show Last Status (status)
4.3.8. Show CLI Information (info)
4.3.9. Test Connection (ping)
4.3.10. Exit from the CLI (exit)
4.3.11. End of File (EOF)
4.3.12. Show Help (help)
5.1. datacenter
5.2. cluster
5.3. glustervolume
5.4. brick
4
4
4
5
6
6
6
7
8
8
9
9
9
10
12
14
15
15
19
19
19
20
20
20
21
22
22
23
24
24
25
25
25
26
26
27
27
27
28
28
29
29
29
31
31
32
34
36
Table of Contents
1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5. network
5.6. storagedomain
5.7. host
5.8. vm
5.9. nic
5.10. disk
5.11. cdrom
5.12. snapshot
5.13. template
5.14. vmpool
5.15. role
5.16. group
5.17. user
5.18. permission
5.19. permit
5.20. tag
5.21. quotas
6.1. Query Syntax
6.2. Wildcards
37
39
41
43
47
50
52
53
54
57
58
59
59
60
60
61
61
63
63
63
65
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
2
Table of Contents
3
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the
set. The
Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative
but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation
Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These
conventions, 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 to highlight
keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working
directory, enter the cat my_next_bestselling_novel command at the shell 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 and all
distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part 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 key combination:
a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned 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 for
directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text;
labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose System → Preferences → Mouse from the main menu bar to launch Mouse
Preferences. In the Buttons tab, select the Left-handed mouse check box 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 Applications → Accessories →
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4
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 Character T able. 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 document and choose Edit → Paste from the gedit menu
bar.
The above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in proportional bold and 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 or variable
text. Italics denotes text you do not input literally or displayed text that changes depending on
circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell
prompt. If the remote machine is example.com and your username on that machine is
john, type ssh john@example.com.
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 package command. It
will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:
Publican is a DocBook publishing system.
1.2. Pull-quote Conventions
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 svn
books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
Preface
5
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 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 should
have 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 to the
current session, or services that need restarting before an update will apply. Ignoring a box
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. Getting Help and Giving Feedback
2.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
6
. 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.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and
technology. You can find a list of publicly available mailing lists at
https://www.redhat.com/mailman/listinfo
.
Click on the name of any mailing list to subscribe to that list or 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 manual
better, we would love to hear from you! Please submit a report in Bugzilla:
Red Hat Enterprise Virtualization Manager
.
When submitting a bug report, be sure to mention the manual's identifier:
If you have a suggestion for improving the documentation, try to be as specific as possible when
describing it. If you have found an error, please include the section number and some of the surrounding
text so we can find it easily.
Preface
7
Chapter 1. About the Command Line Interface
1.1. Introduction to the Command Line Interface
The Red Hat Enterprise Virtualization suite features a command line interface (CLI). This CLI provides
users with a means to connect to Red Hat Enterprise Virtualization Manager outside of the standard
web interface. The CLI also contains a scripting system, which helps system administrators perform
periodic maintenance or repetitive tasks on their virtualization environment via client machines.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
8
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:
Subscription Manager instructions
# subscription-manager list --available | grep -A8 "Red Hat Enterprise
Virtualization"
# subscription-manager subscribe --pool=POOLID
# yum-config-manager --enablerepo=rhel-6-server-rhevm-version.number-rpms
RHN Classic instructions
# rhn_register
# rhn-channel --add --channel=rhel-x86_64-server-6-rhevm-version.number
Note
Refer to the Red Hat Enterprise Virtualization Manager Release Notes for specific channel
names current to your system.
3. Install the CLI package and dependencies:
# yum install rhevm-cli
2.2. TLS/SSL Certification
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 CLI components.
This involves a process of attaining a certificate from your Red Hat Enterprise Virtualization Manager
server and importing it into your client's certificate store.
Important
Attain your certificate from the Red Hat Enterprise Virtualization Manager server using a secure
network connection.
Procedure 2.1. Attain a certificate
This process helps a user attain a certificate from the Red Hat Enterprise Virtualization Manager and
transfer it to the client machine. A user achieves this using one of three methods:
Chapter 2. Using the CLI
9
1. Method 1 - Use a command line tool to download the certificate from the server. Examples of
command line tools include cURL and Wget; both are available for multiple platforms.
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 the browser's
keystore.
a. If the browser downloads the certificate: save the file as rhevm.cer.
If the browser imports the certificate: export it from the browser's certification options
and save it as rhevm.cer.
3. Method 3 - Access your Red Hat Enterprise Virtualization Manager server either physically or
through a secure shell (SSH) client, export the certificate from the server's keystore and copy it to
your client machine.
a. Access your Red Hat Enterprise Virtualization Manager server as the root user.
b. Export a certificate from the server's keystore using the Java keytool management utility:
keytool -exportcert -keystore /etc/pki/rhevm/.keystore -alias rhevm -
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 the three methods results in a certificate file named rhevm.cer on your client machine. An API
user imports this file into the client's certificate store.
Procedure 2.2. Import a certificate to your client
A certificate import for your client relies on how the client itself stores and interprets certificates. This
guide contains some examples on importing certificates. For clients not using Network Security
Services (NSS) or Java KeyStore (JKS), please refer to your client documentation for more
information on importing a certificate.
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 Virtualization
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
10
environments.
Users connect automatically to Red Hat Enterprise Virtualization Manager using the following additional
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 CLI
connects to the Red Hat Enterprise Virtualization Manager via the REST API.
user@domain - The username and directory service domain for the user logging into Red Hat
Enterprise 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 username and the url for the
Red Hat Enterprise Virtualization Manager.
Note
The certificate is the only obligatory option as the others used in this example will be prompted by
the shell. Instead of specifying the certificate you can use the '--insecure' option to connect
without certification, however this is not recommended as it may allow man-in-the-middle (MITM)
attackers to spoof the identity of the server.
Options 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-file=KEY_FILE
Specify key file.
-C CERT_FILE, --cert-file=CERT_FILE
Specify certificate file.
-A CA_FILE, --ca-file=CA_FILE
Chapter 2. Using the CLI
11
Specify server Certificate Authority file.
-I, --insecure
Allow the CLI to connect via SSL without certification. This option should be used with caution,
as it may allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
-F, --filter
Enable filtering based upon user permissions.
-P PORT, --port=PORT
Specify port.
-T TIMEOUT, --timeout=TIMEOUT
Specify timeout.
-c, --connect
Automatically connect.
-f FILE, --file=FILE
Read commands from FILE instead of stdin.
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 are able to
connect to the Red Hat Enterprise Virtualization Manager from within the shell, where the --
password option can be used.
2.4. Interacting with the CLI
The CLI is an interactive shell for controlling your Red Hat Enterprise Virtualization environment from the
command line. Type the required command and any additional parameters.
Example 2.1. Entering a shell command
[RHEVM shell (connected)]# show vm --name desktop_vms
To support the construction of command and parameter combinations, the CLI includes the functionality
to list and automatically complete commands and parameters by pressing the TAB key twice, similar to
the bash shell.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
12
Example 2.2. Listing and automatic completion of commands and parameters
Press double TAB at a blank prompt to list all available commands.
[RHEVM shell (connected)]# TAB TAB
EOF clear console remove echo file
history ping show update action connect
add disconnect exit help list shell
status
Choose a command and press double TAB to view the next set of available parameters for the
command. For the show, this lists all resources.
[RHEVM shell (connected)]# show TAB TAB
brick datacenter event group nic
quota statistic template vmpool cdrom
disk file host permission role
storagedomain user cluster domain glustervolume
network permit snapshot tag vm
Double TAB also completes commands and parameters.
[RHEVM shell (connected)]# show vm TAB TAB
kwargs 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 the prefix.
If the incomplete parameter matches multiple parameters, double TAB lists them.
[RHEVM shell (connected)]# show vTAB TAB
vmpool 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
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.
Chapter 2. Using the CLI
13
Example 2.4 . Piping CLI commands
Pipe CLI data to a Linux shell command:
[RHEVM shell (connected)]# list vms --show-all | grep "Example"
name : Example1
name : Example2
name : ExampleEngineering
description : An Example description
name : 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 command via
the help command.
Example 2.5. Using online help for the show command
[RHEVM shell (connected)]# help show
2.5. Collections
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.
HTTPS is d escrib ed in
.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
14
Chapter 3. Quick Start Example
3.1. Creating a Basic Virtualization Environment with the CLI
This chapter provides an example to demonstrate the CLI's ability to add a virtual machine within a basic
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 client machine;
and,
An ISO file containing a desired virtual machine operating system to install. This chapter uses Red
Hat Enterprise Linux Server 6 for our installation ISO example.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) each
resource's ID. Identifier codes in this example might appear different to the identifier codes in your
Red Hat Enterprise Virtualization environment.
Procedure 3.1. Quick Start Example
1. Load the CLI shell and connect to your Red Hat Enterprise Virtualization Manager
The following step run the CLI shell command with additional parameters to connect to your
virtualization environment.
# rhevm-shell -c -url "https://[rhevm-host]/api" -user "[user]@[domain]" -
password '[password]'
2. List data centers
Red Hat Enterprise Virtualization Manager adds a Default data center on installation. This
example uses the Default data center as the basis for our virtual environment.
[RHEVM shell (connected)]# list datacenters
id : 5e3b55d8-c585-11e1-a7df-001a4a400e0d
name : Default
description: The default Data Center
3. List host clusters
Red Hat Enterprise Virtualization Manager adds a Default host cluster on installation. This
example uses the Default cluster to group resources in your Red Hat Enterprise Virtualization
environment.
Chapter 3. Quick Start Example
15
[RHEVM shell (connected)]# list clusters
id : 99408929-82cf-4dc7-a532-9d998063fa95
name : Default
description: The default server cluster
4. List logical networks
Red Hat Enterprise Virtualization Manager creates a default logical network called rhevm for
management traffic. This example uses the rhevm logical network on the Default data center.
[RHEVM shell (connected)]# list networks --show-all
id : 00000000-0000-0000-0000-000000000009
name : rhevm
description : Management Network
data_center-id: 5e3b55d8-c585-11e1-a7df-001a4a400e0d
mtu : 0
required : True
status-state : operational
stp : False
usages-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 virtualization
environment 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. Activate 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 provides
storage for virtual machines. Add the NFS share as a data storage domain with the add
storagedom ain command.
[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 from your
NFS server.
Note the datacenter-identifier option attaches the storage domain to the Default data
center as a sub-resource.
After creation, use the action storagedomain to activate the storage domain.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
16
[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 provides
storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Add the NFS share as 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 from your
NFS server.
Note the datacenter-identifier option attaches the storage domain to the Default data
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 interface
Use the add nic command to add a new network interface. Add the vm-identifier option to
attach the interface as a sub-resource of MyVM and a network-name option to connect to the
rhevm network.
[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --
network-name rhevm --bootable true
11. Create virtual machine hard disk
Use the add disk command to add a new virtual hard disk. Add the vm-identifier option 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 for an
operating system installation. This example uses a Red Hat Enterprise Server 6 ISO image for
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 ensures images are
uploaded into the correct directory path with the correct user permissions. Once uploaded, use the
list files to show files in the storage domain.
[RHEVM shell (connected)]# list files --storagedomain-identifier
Chapter 3. Quick Start Example
17
Use the add cdrom command to add a new virtual CD-ROM for your installation media. Add the
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 necessary components 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 this
initial boot session. After installation, the virtual machine restarts and restores the boot device
back to hd.
14. List Events
The start action for the virtual machine adds several entries in the events collection. Use the
list events with an additional query to display the events.
[RHEVM shell (connected)]# list events --query "type=153"
id : 105
description: MyVM was started by admin (Host: MyHost).
The "type=153" query refers to events where a user starts a virtual machine.
15. 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 virtual
machine's display-type. Protocols available include SPICE (default) and VNC.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
18
Chapter 4. Commands
4.1. Connecting 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. Options for connect
Option
Description
Required
--url
The URL to the Red Hat Enterprise Virtualization Manager's
REST API. This takes the form of https://[server]/api.
Yes
--user
The username and directory service domain of the user
attempting access to the Red Hat Enterprise Virtualization
Manager. This takes the form of [username]@[domain].
Yes
--password
The password for the user attempting access to the Red Hat
Enterprise 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 is
used
--insecure
Allow the CLI to connect via SSL without certification. This
option should be used with caution, as it may allow man-in-the-
middle (MITM) attackers to spoof the identity of the server.
Yes, but
only if no
certificate
authority is
provided
--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
--tim eout
The timeout period for connection.
No
Example 4 .1. Example for connect
[RHEVM shell (disconnected)]# connect --url
"https://rhevm.example.com/api" --user "admin@exampleids.com" --password
"p@55w0rd!" --ca-file "/home/user/ca.crt"
==========================================
>>> connected to RHEVM manager 3.2.0.0 <<<
==========================================
[RHEVM shell (connected)]#
Chapter 4. Commands
19
Note
Instead of specifying the certificate you can use the '--insecure' option to connect without
certification, however this is not recommended as it may allow man-in-the-middle (MITM) attackers
to spoof the identity of the server.
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)]#
4.2. Resources
4.2.1. List Resources in a Collection (list)
Use the list command to display all resources of a specific type. Lists also include optional search
queries to filter results.
Syntax
list [collection] [options]
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
20
Table 4 .2. list standard options
Option
Description
--show-all
Displays all non-empty properties for each listed resource. Without
this option, only the id, name and description properties
display.
--query [QUERY]
Filters the list using a server-side query based upon Red Hat
Enterprise Virtualization Manager query language. For more
information about search query language, refer to Appendix E.1.
Search of the Red Hat Enterprise Virtualization 3.2 Administration
Guide.
--kwargs [QUERY]
Filters the list using a client-side query.
--case_sensitive
true|false
Match search queries using case sensitivity.
--m ax
Maximum number of results for display.
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 server-side query:
[RHEVM shell (connected)]# list vms --query "type=server"
List server virtual machines using a client-side query:
[RHEVM shell (connected)]# list vms --query "status=up"
4.2.2. Show a Resource (show)
Use the show command to display resource properties.
Syntax
show [resource] [id|name] [options]
Chapter 4. Commands
21
Table 4 .3. show standard options
Option
Description
--id [UUID]
Identify resource with the resource's UUID value.
--nam e [NAME]
Identify resource with the name value.
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
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 show
Create a virtual machine:
[RHEVM shell (connected)]# add vm [vm-options]
Create a user:
[RHEVM shell (connected)]# add user [user-options]
4.2.4. Update a Resource (update)
Red Hat Enterprise Virtualization 3.2 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]
4.2.5. Remove a Resource (remove)
Use the remove command to remove a resource.
Syntax
rem ove [resource] [id|name] [options]
Table 4 .4 . remove standard options
Option
Description
--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. This action
applies only to datacenter and vm resources.
Note
Options specific to resource types are listed in the definition pages for each resource type.
Chapter 4. Commands
23
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
Force remove virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server --force
4.2.6. Perform Action on a Resource (action)
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
4.2.7. Using Sub-Resources (--RESOURCE-identifier)
Certain resources act as sub-resources of other resources. This means there is a dependent
relationship 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 a parent
resource.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
24
Example 4 .9. Examples for creating sub-resources with add
Create a NIC on a virtual machine:
[RHEVM shell (connected)]# add nic --vm-identifier RHEL6-Server [nic-options]
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 the
RHEL6-Server virtual machine.
4.3. Other Commands
4.3.1. .rhevmshellrc Configuration
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
Description
url
string
The address of the Red Hat Enterprise Virtualization environment.
usernam e
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 can toggle filtering
off. The status is either True or False.
tim eout
integer
Requests timeout. The default is -1.
4.3.2. Connect to VM (console)
Use the console command to open a graphical console to a virtual machine. This command opens
either an external VNC or SPICE client based upon the virtual machine's display-type parameter.
Syntax
console [vm-id|vm-name]
Chapter 4. Commands
25
Example 4 .10. Example for console
Open graphical console to a virtual machines:
[RHEVM shell (connected)]# console RHEL6-Server
4.3.3. Run a Shell Command (shell)
Use the shell command to run a command from the Linux shell. This command helps with performing
file management tasks in conjunction with the Red Hat Enterprise Virtualization Manager shell.
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
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 of
commands for execution.
Syntax
file [file-location]
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
26
Example 4 .12. Example for file
Run a script file:
[RHEVM shell (connected)]# file /example/example-script
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
4.3.6. Print Input (echo)
Use the echo command to print input to the screen. Use the $out variable to print the last shell
command 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
4.3.7. Show Last Status (status)
Use the status command to display the most recently run command status.
Syntax
status
Chapter 4. Commands
27
Example 4 .15. Example for status
View the last status:
[RHEVM shell (connected)]# status
last command status: 0 (OK)
4.3.8. Show CLI Information (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.1
sdk version : 3.1.0.4
cli version : 3.1.0.6
python version : 2.7.3.final.0
entry point : https://www.example.com:8443/api
4.3.9. Test Connection (ping)
Use the ping command tests the connection to your Red Hat Enterprise Virtualization Manager. The
command retrieves a remote resource and ensures the URL, username and password for the
connection are correct.
Syntax
ping
Example 4 .17. Example for ping
Test your connection:
[RHEVM shell (connected)]# ping
success: RHEVM manager could be reached OK.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
28
4.3.10. Exit from the CLI (exit)
Use the exit command to leave a CLI.
Syntax
exit
Example 4 .18. Example for exit
Leave the CLI:
[RHEVM shell (connected)]# exit
4.3.11. End of File (EOF)
Use the EOF command to leave the CLI shell using a Ctrl+D sequence.
Syntax
EOF
Example 4 .19. Example for EOF
Leave the CLI shell:
[RHEVM shell (connected)]# EOF
4.3.12. Show Help (help)
Use the help command displays help for CLI command and resource combinations.
Syntax
help [command] [resource] [options]
Chapter 4. Commands
29
Example 4 .20. 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
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
30
Chapter 5. Resource Types
5.1. datacenter
The datacenter resource type groups all data center resources in a Red Hat Enterprise Virtualization
environment.
Table 5.1. Data Center Parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the data center.
Yes
Yes
Yes
--
storage_typ
e
string
The type of storage for the data center, including
iscsi, fcp, nfs, localfs or posixfs.
Yes
Yes
Yes
--version-
m ajor
int
The major version number of the data center. For
example, for Red Hat Enterprise Virtualization 3.2,
the major version is 3.
Yes
Yes
Yes
--version-
m inor
int
The minor version number of the data center. For
example, for Red Hat Enterprise Virtualization 3.2,
the minor version is 2.
Yes
Yes
Yes
--
description
string
A description for the data center.
No
Yes
Yes
--
storage_for
m at
string
The metadata format for the data center, including
v1, v2 or v3.
No
Yes
Yes
--expect
'201-
create
d'
Request becomes asynchronous until the
expected HTTP header is returned. Useful for
long-running tasks that would otherwise return as
successful before the task is completed.
No
No
No
--
correlation
_id
string
A tagging identifier of an action for cross-system
logging. If the client does not define the identifier,
one will be generated.
No
Yes
No
Example 5.1. Creating a new data center
[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --
version-major 3 --version-minor 2
Example 5.2. Updating a data center
[RHEVM shell (connected)]# update datacenter Boston --name India
Chapter 5. Resource Types
31
Example 5.3. Deleting a data center
[RHEVM shell (connected)]# remove datacenter Boston
5.2. cluster
The cluster resource type groups all host cluster resources in a Red Hat Enterprise Virtualization
environment.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
32
Table 5.2. Cluster parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--
data_center
-id|nam e
string
A reference to the data center for a host cluster.
Yes
Yes
No
--nam e
string
The name of a host cluster.
Yes
Yes
Yes
--version-
m ajor
int
The major version number of the cluster. For
example, for Red Hat Enterprise Virtualization 3.2,
the major version is 3.
Yes
Yes
Yes
--version-
m inor
int
The minor version number of the cluster. For
example, for Red Hat Enterprise Virtualization 3.2,
the minor version is 2.
Yes
Yes
Yes
--cpu-id
string
A server CPU reference that defines the CPU type
all hosts must support in the cluster.
Yes
Yes
Yes
--
description
string
A description for the host cluster.
No
Yes
Yes
--
m em ory_poli
cy-
overcom m it-
percent
doubl
e
The percentage of host memory allowed in use
before a host can no longer run any more virtual
machines. Virtual machines can use more than the
available host memory due to memory sharing
under KSM. Recommended values include 100
(None), 150 (Server Load) and 200 (Desktop
Load).
No
Yes
Yes
--
m em ory_poli
cy-
transparent
_hugepages-
enabled
Boole
an
Defines the enabled status of Transparent
Hugepages. 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 the
host can have before being considered
underutilized.
No
Yes
Yes
--
scheduling_
policy-
thresholds-
high
int
Controls the highest CPU usage percentage the
host can have before being considered
overloaded.
No
Yes
Yes
--
scheduling_
policy-
int
The number of seconds the host needs to be
overloaded before the scheduler starts and
moves the load to another host.
No
Yes
Yes
Chapter 5. Resource Types
33
thresholds-
duration
--
error_handl
ing-
on_error
string
Defines virtual machine handling when a host
within a cluster becomes non-operational,
including migrate, do_not_migrate and
m igrate_highly_available.
No
Yes
Yes
--
virt_servic
e
Boole
an
.The status is either true or false.
No
Yes
Yes
--
gluster_ser
vice
Boole
an
.The status is either true or false.
No
Yes
Yes
--
threads_as_
cores
Boole
an
Hosts treat threads as cores, allowing hosts to
run virtual machines with a total number of
processor cores greater than the number of cores
in the host. The status is either true or false.
No
No
No
--expect
'201-
create
d'
Request becomes asynchronous until the
expected HTTP header is returned. Useful for
long-running tasks that would otherwise return as
successful before the task is completed.
No
No
No
--
correlation
_id
string
A tagging identifier of an action for cross-system
logging. If the client does not define the identifier,
one will be generated.
No
Yes
No
Example 5.4 . Creating 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.5. Updating a cluster
[RHEVM shell (connected)]# update cluster Engineering --name Finance
Example 5.6. Deleting a cluster
[RHEVM shell (connected)]# remove cluster Engineering
5.3. glustervolume
Important
The information in this section is provided as a technical preview only.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
34
The glustervolume resource type groups all Gluster storage volume resources in a Red Hat
Enterprise Virtualization environment.
Table 5.3. Gluster volume parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the gluster volume.
Yes
Yes
No
--
volum e_type
string
Defines the Gluster volume type. Choose from
DIST RIBUT E, REPLICAT E,
DIST RIBUT ED_REPLICAT E, ST RIPE or
DIST RIBUT ED_ST RIPE.
Yes
Yes
No
--bricks-
brick
collect
ion
A new Gluster volume requires a set of Gluster
bricks to add and manage. This parameter
references a collection of brick details. Specify at
least one brick but list multiple bricks-brick
parameters for multiple bricks. See below for
collection details.
Yes
Yes
No
--
transport_t
ypes
collect
ion
A reference to available transport methods for the
Gluster volume. See below for collection details.
No
Yes
No
--
replica_cou
nt
intege
r
Defines the file replication count for a replicated
volume.
No
Yes
No
--
stripe_coun
t
Intege
r
Defines the stripe count for a striped volume
No
Yes
No
--options-
option
collect
ion
A reference to options for the Gluster volume. See
below for collection details.
No
Yes
No
The --bricks-brick parameter is a collection that uses the sub-parameters in the following table.
Table 5.4 . bricks-brick parameters
Name
Type
Description
brick.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 following table.
Table 5.5. transport_types parameters
Name
Type
Description
transport_type
string
Defines a transport type to use. Specify multiple transport_type
parameters for more than one type. Choose from TCP and RDMA.
The --options-option parameter is a collection that uses the sub-parameters in the following table.
Chapter 5. Resource Types
35
Table 5.6. options-option parameters
Name
Type
Description
option.nam e
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.7. Additional command options
Option
Description
--cluster-identifier
Adds the Gluster volume to a cluster as a sub-resource.
Example 5.7. Creating a Gluster volume 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"
Example 5.8. Deleting a Gluster volume
[RHEVM shell (connected)]# remove glustervolume --cluster-identifier Default --
name GlusterVol1
The following table lists actions for a Gluster volume resource.
Table 5.8. Gluster volume actions
Action
Description
start
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.
5.4. 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 Virtualization environment.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
36
Table 5.9. Gluster brick parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--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_cou
nt
intege
r
Defines the file replication count for a replicated
volume.
No
Yes
No
--
stripe_coun
t
Intege
r
Defines the stripe count for a striped volume
No
Yes
No
The following table lists additional glustervolume options for resource-based commands.
Table 5.10. Additional command options
Option
Description
--cluster-identifier
Reference to the cluster that contains a glustervolume sub-
resource.
--glustervolum e-
identifier
Adds the brick to a glustervolume as a sub-resource.
Example 5.9. Creating a bricks
[RHEVM shell (connected)]# add brick --cluster-identifier Default --
glustervolume-identifier GlusterVol1 --server_id="server1" --brick_dir="/exp1"
5.5. network
The network resource type groups all logical network resources in a Red Hat Enterprise Virtualization
environment.
Chapter 5. Resource Types
37
Table 5.11. Logical network parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--
data_center
-id|nam e
string
A reference to the data center for a logical
network.
Yes
Yes
No
--nam e
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-
netm ask
string
The netmask for the logical network's bridge.
No
Yes
Yes
--display
boole
an
Signifies if a logical network is used for display
communication usage. Set to either true or
false.
No
Yes
Yes
--stp
boole
an
Set to true if Spanning Tree Protocol is enabled
on this network.
No
Yes
Yes
--m tu
int
Sets a user-defined value for the maximum
transmission unit of the logical network.
No
Yes
Yes
--usages-
usage
collect
ion
Defines usage parameters for the logical network.
No
No
Yes
The --usages-usage parameter is a collection that uses the sub-parameters in the following table.
Table 5.12. usages-usage parameters
Name
Type
Description
usage
string
Usage types for the network. Options include VM and DISPLAY.
The following table lists additional network options for resource-based commands.
Table 5.13. Additional command options
Option
Description
--cluster-identifier
Adds the network to a cluster as a sub-resource.
Example 5.10. Creating a new network
[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name
Default --cluster-identifier Default
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
38
Example 5.11. Updating a network
[RHEVM shell (connected)]# update network WebNetwork --name DataNetwork
Example 5.12. Deleting a network
[RHEVM shell (connected)]# remove network WebNetwork
5.6. storagedomain
The storagedomain resource type groups all storage domain resources in a Red Hat Enterprise
Virtualization environment.
Table 5.14 . Storage domain parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the storage domain.
No
Yes
Yes
--form at
Boole
an
The metadata format for the data center, including
v1, v2 or v3.
Yes
Yes
No
--host-
id|nam e
string
A reference to the host from which this storage
domain should be initialized. The only restriction
on this host is that it should have access to the
physical storage specified.
Yes
Yes
No
--storage-
address
string
The IP address or hostname of the storage
device.
Yes
Yes
No
--storage-
logical_uni
t
collect
ion
The logical unit information of the storage device.
See
below
Yes
No
--storage-
m ount_optio
ns
string
The options for mounting the storage domain.
See
below
Yes
No
--storage-
override_lu
ns
Boole
an
Defines whether to override the logical unit
number. The status is either true or false.
See
below
Yes
No
--storage-
path
string
The path on the storage device to use for the
storage domain.
See
below
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 storage
domain.
See
below
Yes
No
--type
string
The type of storage domain, including data, iso
and export.
Yes
Yes
No
Chapter 5. Resource Types
39
The --storage-logical_unit parameter is a collection that requires all sub-parameters in the
following table.
Table 5.15. storage-logical_unit parameters
Name
Type
Description
logical_unit.ad
dress
string
The address of the server containing the storage device.
logical_unit.po
rt
integer
The port number of the server.
logical_unit.ta
rget
string
The target IQN for the storage device.
logical_unit.us
ernam e
string
A CHAP user name for logging into a target.
logical_unit.pa
ssword
string
A CHAP password for logging into a target.
logical_unit.se
rial
string
The serial ID for the target.
logical_unit.ve
ndor_id
string
The vendor name for the target.
logical_unit.pr
oduct_id
string
The product code for the target.
logical_unit.lu
n_m apping
integer
The Logical Unit Number device mapping for the target.
logical_unit.po
rtal
string
The logical unit portal.
logical_unit.pa
ths
integer
The logical unit paths.
logical_unit.id string
A reference to the logical unit ID.
Use the following parameters depending on storage-type.
Table 5.16. Storage type parameters
Type
Parameters
nfs
--storage-address, --storage-path
iscsi or fcp
--storage-address, --storage-logical_unit, --storage-
override_luns
local
--storage-path
posixfs
--storage-path, --storage-vfs_type, --storage-address, --
storage-m ount_options
The following table lists additional storagedomain options for resource-based commands.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4 0
Table 5.17. Additional command options
Option
Description
--datacenter-identifier
Adds the storage domain to a datacenter as a sub-resource.
Example 5.13. Creating a new storage domain
[RHEVM shell (connected)]# add storagedomain --name DataStorage --datacenter-
name Default -type data
Example 5.14 . Updating a storage domain
[RHEVM shell (connected)]# update storagedomain DataStorage --name
DataStorageOld
Example 5.15. Deleting a storage domain
[RHEVM shell (connected)]# remove storagedomain DataStorage
The following table lists actions for a storage domain resource.
Table 5.18. Storage domain actions
Action
Description
activate
Activate a storage domain on a data center.
deactivate
Deactivate a storage domain on a data center.
5.7. host
The host resource type groups all host resources in a Red Hat Enterprise Virtualization environment.
Chapter 5. Resource Types
4 1
Table 5.19. Host parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the host.
Yes
Yes
Yes
--address
string
The IP address or hostname for the host.
Yes
Yes
Yes
--
root_passwo
rd
string
The password for the host's root user.
Yes
Yes
Yes
--cluster-
id|nam e
string
Defines the cluster that includes the host.
Yes
Yes
Yes
--port
int
The port for communication with the VDSM
daemon running on the host.
No
Yes
Yes
--
storage_m an
ager-
priority
int
Sets the priority of host order for storage pool
manager (SPM).
No
Yes
Yes
--
power_m anag
em ent-type
string
The fencing device code for host power
management.
No
Yes
Yes
--
power_m anag
em ent-
enabled
boole
an
Indicates whether power management
configuration is enabled or disabled.
No
Yes
Yes
--
power_m anag
em ent-
address
string
The host name or IP address of the power
management device.
No
Yes
Yes
--
power_m anag
em ent-
user_nam e
string
A valid user name for power management.
No
Yes
Yes
--
power_m anag
em ent-
password
string
A valid, robust password for power management.
No
Yes
Yes
--
power_m anag
em ent-
options-
option
collect
ion
Fencing options for the selected
power_m anagem ent-type.
No
Yes
Yes
--
reboot_afte
r_installat
ion
boole
an
Defines if the host reboots after VDSM installation. No
Yes
No
The --power_management-options-option parameter is a collection that uses the sub-
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4 2
parameters in the following table.
Table 5.20. --power_management-options-option parameters
Name
Type
Description
option.nam e
string
Power management option name.
option.value
string
Power management option value.
Example 5.16. Creating a new host
[RHEVM shell (connected)]# add host --name Host1 --address host1.example.com --
root_password p@55w0rd! --cluster-name Default
Example 5.17. Updating a host
[RHEVM shell (connected)]# update host Host1 --name Host2
Example 5.18. Deleting a host
[RHEVM shell (connected)]# remove host Host1
The following table lists actions for a host resource.
Table 5.21. Host actions
Action
Description
activate
Activate a host.
deactivate
Deactivate a host.
approve
Approve a host.
install
Install VDSM on a host.
fence
Fence a host.
com m itnetconfig
Save the network configuration.
iscsidiscover
Perform an iSCSI discover command.
iscsilogin
Perform an iSCSI login command.
5.8. vm
The vm resource type groups all virtual machine resources in a Red Hat Enterprise Virtualization
environment.
Chapter 5. Resource Types
4 3
Table 5.22. Virtual machine parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--cluster-
id|nam e
string
A reference to the cluster that includes this VM.
Yes
Yes
Yes
--cpu-
topology-
cores
int
The number of CPU cores available to the virtual
machine.
No
Yes
Yes
--cpu-
topology-
sockets
int
The number of CPU sockets available to the
virtual machine.
No
Yes
Yes
--
custom _prop
erties-
custom _prop
erty
collect
ion
A set of user-defined environment variable
passed as parameters to custom scripts.
No
Yes
Yes
--
description
string
A description of the virtual machine.
No
Yes
Yes
--disks-
clone
Boole
an
Defines whether to clone the disk from the defined
tem plate.
No
Yes
No
--display-
allow_recon
nect
Boole
an
Defines whether to allow reconnection via console
display.
No
Yes
Yes
--display-
m onitors
int
Defines the number of displays available.
No
Yes
Yes
--display-
type
string
Defines the display type, including spice or vnc.
No
Yes
Yes
--dom ain-
nam e
string
The domain name of the virtual machine.
No
Yes
Yes
--
high_availa
bility-
enabled
Boole
an
Defines if high availability is enabled for the virtual
machine.
No
Yes
Yes
--
high_availa
bility-
priority
int
Sets the priority value (migration and restart
order) of each virtual machine using high
availability.
No
Yes
Yes
--m em ory
long
The amount of memory for the virtual machine in
bytes.
No
Yes
Yes
--nam e
string
The name of the virtual machine
Yes
Yes
Yes
--origin
string
The virtual machine's origin, including rhev,
vm ware or xen.
No
Yes
Yes
--os-boot-
dev
string
The boot device for the virtual machine, including
cdrom , hd, network.
No
Yes
Yes
--os-
string
A kernel command line parameter string to be
No
Yes
Yes
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4 4
cm dline
used with the defined kernel. This option supports
booting a Linux kernel directly rather than through
the BIOS bootloader.
--os-initRd
string
A path to an initrd image to be used with a
specified kernel. This option supports booting a
Linux kernel directly rather than through the BIOS
bootloader.
No
Yes
Yes
--os-kernel
string
A path to a kernel image the virtual machine is
configured to boot. This option supports booting a
Linux kernel directly rather than through the BIOS
bootloader.
No
Yes
Yes
--os-type
string
The operating system type for this virtual machine. No
Yes
Yes
--payloads-
payload
collect
ion
Defines content to send to the virtual machine
upon booting.
No
Yes
Yes
--
placem ent_p
olicy-
affinity
string
The migration affinity for each virtual machine,
including migratable, user_migratable or
pinned.
No
Yes
Yes
--
placem ent_p
olicy-host-
id|nam e
string
A reference to the preferred host for migration
affinity.
No
Yes
Yes
--quota-id
string
A reference to the quota usage for the virtual
machine.
No
Yes
No
--stateless
Boole
an
true if the virtual machine is stateless. A
stateless virtual machine contains a snapshot of
its disk image taken at boot and removed at
shutdown. This means state changes do not
persist after a reboot.
No
Yes
Yes
--tem plate-
id|nam e
string
A reference to the template used as the basis for
the virtual machine.
Yes
Yes
No
--tim ezone
string
The the Sysprep timezone setting for a Windows
virtual machine.
No
Yes
Yes
--type
string
Defines the virtual machine type. Either desktop
or server.
No
Yes
Yes
--usb-
enabled
Boole
an
Defines the USB policy for a virtual machine. Set to
true to enable USB on the virtual machine.
No
Yes
Yes
--usb-type
string
Defines the USB type if enabled.
No
Yes
Yes
--expect
'201-
create
d'
Request becomes asynchronous until the
expected HTTP header is returned. Useful for
long-running tasks that would otherwise return as
successful before the task is completed.
No
No
No
--
correlation
_id
string
A tagging identifier of an action for cross-system
logging. If the client does not define the identifier,
one will be generated.
No
Yes
No
The --custom_properties-custom_property parameter is a collection that uses the sub-
parameters in the following table.
Chapter 5. Resource Types
4 5
Table 5.23. --custom_properties-custom_property parameters
Name
Type
Description
custom _property
.nam e
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 following
table.
Table 5.24 . --payloads-payload parameters
Name
Type
Description
payload.type
string
Payload delivery type, including cdrom or floppy.
payload.file.n
am e
string
The payload file name and location on the root file system of the
virtual machine.
payload.file.c
ontent
string
The content to deliver to the file.
Example 5.19. Creating a new virtual machine
[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-
name Default --memory 536870912
Example 5.20. Updating a virtual machine
[RHEVM shell (connected)]# update vm MyVM --memory 1073741824
Example 5.21. Deleting a virtual machine
[RHEVM shell (connected)]# remove vm MyVM
The following table lists actions for a virtual machine resource.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4 6
Table 5.25. Virtual machine actions
Action
Description
start
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.
m igrate
Migrate the virtual machine to another host.
cancelm igration
Stop migration in progress
export
Export a virtual machine to an export storage domain
m ove
Move virtual machine disks to another storage domain.
ticket
Create a ticket for console access.
5.9. nic
The nic resource type groups network interface resources in a Red Hat Enterprise Virtualization
environment. These resources acts as sub-resources for both host and vm resources but are defined
differently for each. This section contains two tables with parameters for each.
Chapter 5. Resource Types
4 7
Table 5.26. Host network interface parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--network-
id|nam e
string A reference to the network, if any, that the
interface is attached.
Yes
Yes
Yes
--nam e
string The name of the host network interface, e.g. eth0. Yes
Yes
Yes
--bonding-
slaves-
host_nic
collec
tion
A collection of slave network interfaces that form a
bonded interface.
No
Yes
Yes
--bonding-
options-
option
collec
tion
A list of options for a bonded interface. Each
option contains property name and value
attributes.
No
Yes
Yes
--ip-
gateway
string The IP address for the network's gateway.
No
Yes
Yes
--
boot_protoc
ol
string The protocol for IP address assignment when the
host is booting, such as dhcp or static.
No
Yes
Yes
--m ac
string The MAC address of the interface.
No
Yes
Yes
--ip-
address
string The IP address of the interface.
No
Yes
Yes
--ip-
netm ask
string The netmask for the interface's IP address.
No
Yes
Yes
--ip-m tu
int
The maximum transmission unit for the interface.
No
No
Yes
Table 5.27. Virtual Machine network interface parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--network-
id|nam e
string A reference to the network, if any, that the
interface is attached.
Yes
Yes
Yes
--nam e
string The name of the interface, e.g. eth0.
Yes
Yes
Yes
--m ac-
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
--
port_m irror
ing-
networks-
network
collec
tion
Defines a set of networks to copy (mirror) network
data from the network interface.
No
Yes
Yes
The --bonding-slaves-host_nic parameter is a collection that uses the sub-parameters in the
following table.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
4 8
Table 5.28. --bonding-slaves-host_nic
Name
Type
Description
host_nic.id|nam
e
string
A reference to another host NIC to bond.
The --bonding-options-option parameter is a collection that uses the sub-parameters in the
following table.
Table 5.29. --bonding-options-option
Name
Type
Description
option.nam e
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.30. --port_mirroring-networks-network
Name
Type
Description
network.id
string
A reference to the network to mirror.
The following table lists additional NIC options for resource-based commands.
Table 5.31. Additional command options
Option
Description
--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.22. Creating a new network interface on a host
[RHEVM shell (connected)]# add nic --host-identifier MyHost1 --name eth0 --
network MyNetwork
Example 5.23. Creating a new network interface on a virtual machine
[RHEVM shell (connected)]# add nic --vm-identifier MyVM1 --name eth0 --network
MyNetwork
Example 5.24 . Updating a network interface
[RHEVM shell (connected)]# update nic eth0 --vm-identifier MyVM1 --ip-address
10.5.68.123
Chapter 5. Resource Types
4 9
Example 5.25. Deleting a network interface
[RHEVM shell (connected)]# remove nic eth0 --vm-identifier MyVM1
The following table lists actions for a host NIC resource.
Table 5.32. Host NIC actions
Action
Description
attach
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.33. Virtual machine NIC actions
Action
Description
activate
Activate a NIC on a virtual machine.
deactivate
Deactivate a NIC on a virtual machine.
5.10. disk
The disk resource type groups all virtual hard disk resources in a Red Hat Enterprise Virtualization
environment.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
50
Table 5.34 . Disk parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--
provisioned
_size
int
The reserved storage space for the disk. This
space is preallocated for the disk to use, even if
the 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
--form at
string The underlying storage format. Copy On Write
(cow) allows snapshots, with a small performance
overhead. Raw (raw) does not allow snapshots,
but offers improved performance.
Yes
Yes
Yes
--size
int
The actual size of the disk.
No
Yes
Yes
--sparse
Boole
an
true if the physical storage for the disk should
not be preallocated.
No
Yes
Yes
--bootable
Boole
an
true if this disk is to be marked as bootable.
No
Yes
Yes
--shareable
Boole
an
true if this disk is shareable.
No
Yes
Yes
--
allow_snaps
hot
Boole
an
true if this disk allows snapshots.
No
Yes
Yes
--
propagate_e
rrors
Boole
an
true if disk errors should not cause virtual
machine to be paused and, instead, disk errors
should be propagated to the guest OS.
No
Yes
Yes
--
wipe_after_
rem ove
boole
an
true if the underlying physical storage for the
disk should be zeroed when the disk is removed.
No
Yes
Yes
--
storage_dom
ains-
storage_dom
ain
collec
tion
Defines a specific storage domain for the disk.
No
Yes
No
The --storage_domains-storage_domain parameter is a collection that uses the sub-parameters
in the following table.
Table 5.35. --storage_domains-storage_domain parameters
Name
Type
Description
storage_dom ain
.id|nam e
string
A reference to a storage domain for the disk.
The following table lists additional disk options for resource-based commands.
Chapter 5. Resource Types
51
Table 5.36. Additional command options
Option
Description
--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.26. Creating a new disk
[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size 8589934592
--interface virtio --format cow
Example 5.27. Updating a storage domain
[RHEVM shell (connected)]# update disk MyDisk --shareable true
Example 5.28. Deleting a storage domain
[RHEVM shell (connected)]# remove disk MyDisk
The following table lists actions for a virtual machine disk resource.
Table 5.37. Virtual machine disk actions
Action
Description
activate
Activate a disk on a virtual machine.
deactivate
Deactivate a disk on a virtual machine.
5.11. cdrom
The cdrom resource type groups all virtual CD-ROM drive resources in a Red Hat Enterprise
Virtualization environment.
Table 5.38. CD-ROM parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--file-id
string
Defines the file name of the ISO that resides on an
ISO storage domain.
Yes
Yes
Yes
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
52
Example 5.29. Creating 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.30. Updating a CD-ROM
[RHEVM shell (connected)]# update cdrom --vm-identifier MyVM --file-id rhel-
server-6.3-x86_64-dvd.iso.iso
Example 5.31. Deleting a CD-ROM
[RHEVM shell (connected)]# remove cdrom --vm-identifier MyVM rhel-server-6.3-
x86_64-dvd.iso.iso
5.12. snapshot
The snapshot resource type groups all virtual machine snapshot resources in a Red Hat Enterprise
Virtualization environment.
Table 5.39. Snapshot parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--
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. Additional command options
Option
Description
--vm -identifier
Adds the disk to a vm as a sub-resource.
Example 5.32. Creating a new snapshot
[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description 'My
Snapshot'
Example 5.33. Deleting a storage domain
[RHEVM shell (connected)]# remove snapshot [snapshot_id]
Chapter 5. Resource Types
53
The following table lists actions for a virtual machine snapshot resource.
Table 5.4 1. Virtual machine snapshot actions
Action
Description
restore
Restore a snapshot.
5.13. template
The template resource type groups all virtual machine templates in a Red Hat Enterprise Virtualization
environment.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
54
Table 5.4 2. Template parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--vm -
id|nam e
string
A reference to the virtual machine used as a basis
for the template.
Yes
Yes
No
--nam e
string
The name of the virtual machine template.
Yes
Yes
Yes
--m em ory
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 virtual
machine template.
No
Yes
Yes
--
high_availa
bility-
enabled
Boole
an
Defines if high availability is enabled for the virtual
machine template.
No
Yes
Yes
--os-
cm dline
string
A kernel command line parameter string to be
used with the defined kernel. This option supports
booting a Linux kernel directly rather than through
the BIOS bootloader.
No
Yes
Yes
--origin
string
The virtual machine template's origin, including
rhev, vm ware or xen.
No
Yes
Yes
--
high_availa
bility-
priority
int
Sets the priority value (i.e. boot order) of each
virtual machine template's high availability.
No
Yes
Yes
--tim ezone
string
The the Sysprep timezone setting for a Windows
virtual machine template.
No
Yes
Yes
--dom ain-
nam e
string
The domain name of the virtual machine template.
No
Yes
Yes
--type
string
Defines the virtual machine type. Either desktop
or server.
No
Yes
Yes
--stateless
boole
an
true if the resulting virtual machines are
stateless. A stateless virtual machine contains a
snapshot of its disk image taken at boot and
removed at shutdown. This means state changes
do not persist after a reboot.
No
Yes
Yes
--
placem ent_p
olicy-
affinity
string
The migration affinity for each virtual machine
created from the template. Includes migratable,
user_m igratable or pinned.
No
Yes
Yes
--
description
string
A description for the template.
No
Yes
Yes
--
custom _prop
erties-
custom _prop
collect
ion
A set of user-defined environment variables
passed as parameters to custom scripts.
No
Yes
Yes
Chapter 5. Resource Types
55
erty
--os-type
string
The operating system type for this virtual machine
template.
No
Yes
Yes
--os-boot-
dev
string
The boot device for the virtual machine template,
including cdrom, hd, network.
No
Yes
Yes
--cpu-
topology-
sockets
int
The number of CPU sockets available to the
virtual machine template.
No
Yes
Yes
--os-kernel
string
A path to a kernel image the resulting virtual
machines are configured to boot. This option
supports booting a Linux kernel directly rather
than through the BIOS bootloader.
No
Yes
Yes
--display-
type
string
Defines the display type, including spice or vnc.
No
Yes
Yes
--display-
m onitors
int
Defines the number of displays available.
No
Yes
Yes
--display-
allow_recon
nect
Boole
an
Defines whether to allow reconnection via console
display.
No
Yes
Yes
--os-initRd
string
A path to an initrd image to be used with a
specified kernel. This option supports booting a
Linux kernel directly rather than through the BIOS
bootloader.
No
Yes
Yes
--usb-
enabled
Boole
an
Defines the USB policy for a virtual machine. Set to
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
collect
ion
References to disks attached to the template.
No
Yes
No
The --custom_properties-custom_property parameter is a collection that uses the sub-
parameters in the following table.
Table 5.4 3. --custom_properties-custom_property parameters
Name
Type
Description
custom _property
.nam e
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 following table.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
56
Table 5.4 4 . --vm-disks-disk parameters
Name
Type
Description
disk.id
string
A reference to a virtual machine disk.
storage_dom ain
s.storage_dom ai
n
collection Defines a set of sub-parameters for the disk's storage domain.
Example 5.34 . Creating a new template
[RHEVM shell (connected)]# add template --name MyTemplate1 --vm-name MyVM1
Example 5.35. Updating a template
[RHEVM shell (connected)]# update template MyTemplate1 --memory 1073741824
Example 5.36. Deleting a template
[RHEVM shell (connected)]# remove template MyTemplate1
The following table lists actions for a virtual machine template resource.
Table 5.4 5. Virtual machine template actions
Action
Description
export
Export a template to an export storage domain.
5.14. vmpool
The vmpool resource type groups all virtual machine pool resources in a Red Hat Enterprise
Virtualization environment.
Table 5.4 6. Virtual machine pool parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--cluster-
id|nam e
string
A reference to the cluster for the virtual machine
pool.
Yes
Yes
Yes
--tem plate-
id|nam e
string
A reference to the template for the virtual machine
pool.
Yes
Yes
Yes
--nam e
string
The name of the virtual machine pool.
Yes
Yes
Yes
--size
intege
r
The number of the virtual machines in the pool.
Yes
Yes
Yes
Chapter 5. Resource Types
57
Example 5.37. Creating a new virtual machine pool
[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-name
MyTemplate --name MyPool --size 3
Example 5.38. Updating a virtual machine pool
[RHEVM shell (connected)]# update vmpool MyPool --size 4
Example 5.39. Deleting a virtual machine pool
[RHEVM shell (connected)]# remove vmpool MyPool
5.15. role
The role resource type groups all individual roles in a Red Hat Enterprise Virtualization environment.
Table 5.4 7. Role parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the role.
Yes
Yes
Yes
--perm its-
perm it
collect
ion
A list of permits for initial inclusion with the role.
Additional permits included with the permit
resource type.
Yes
Yes
No
--
description
string
A description for the role.
No
Yes
Yes
--
adm inistrat
ive
Boole
an
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 following table.
Table 5.4 8. --permits-permit parameters
Name
Type
Description
perm it.id
string
A reference to a permit to add to the role's permits.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
58
Example 5.4 0. Creating a new role
[RHEVM shell (connected)]# add role --name MyRole --permits-permit {permit.id:
1;},{permit.id: 2;)
5.16. group
The group resource type defines all identity service groups for a Red Hat Enterprise Virtualization
environment.
Table 5.4 9. Group parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the group, usually the full group path
within the identity directory service.
No
No
No
Example 5.4 1. Creating a group
[RHEVM shell (connected)]# add group --name
www.example.com/accounts/groups/mygroup
5.17. user
The user resource type groups all users in a Red Hat Enterprise Virtualization environment.
Table 5.50. User parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--user_nam e
string
The username from the directory service.
Yes
Yes
No
--dom ain-
id|nam e
string
A reference to the directory service domain.
Yes
Yes
No
Example 5.4 2. Creating a new user
[RHEVM shell (connected)]# add user -user_name jsmith --domain-name
www.example.com/accounts/groups/mygroup
Chapter 5. Resource Types
59
5.18. permission
The permission resource type groups all permission resources in a Red Hat Enterprise Virtualization
environment.
Table 5.51. Permission parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--user-id, --
group-id
string
A reference to the user or group using the
permission.
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.52. Additional command options
Option
Description
--cluster-identifier
Adds the permission to a cluster.
--datacenter-identifier
Adds the permission to a data center.
--group-identifier
Adds the permission to a group.
--host-identifier
Adds the permission to a host.
--storagedom ain-
identifier
Adds the permission to a storage domain.
--tem plate-identifier
Adds the permission to a template.
--user-identifier
Adds the permission to a user.
--vm -identifier
Adds the permission to a virtual machine.
--vm pool-identifier
Adds the permission to a virtual machine pool.
Example 5.4 3. Creating a new permission
[RHEVM shell (connected)]# add permission --vm-identifier MyVM1 --role-id
MyRole --user-id jsmith
5.19. permit
The permit resource type groups all individual permits for roles in a Red Hat Enterprise Virtualization
environment.
Table 5.53. Permission parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--id
string
A reference to the permit to add.
Yes
Yes
No
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
60
The following table lists additional permit options for resource-based commands.
Table 5.54 . Additional command options
Option
Description
--role-identifier
Adds the permit to a role.
Example 5.4 4 . Creating a new permission
[RHEVM shell (connected)]# add permit --role-identifier MyRole --id 1
5.20. tag
The tag resource type groups all tags in a Red Hat Enterprise Virtualization environment.
Table 5.55. Tag parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the tag.
Yes
Yes
Yes
--
description
string
A description for the string.
Yes
Yes
Yes
--parent-
nam e
string
A reference to the parent tag that the tag is
attached.
Yes
Yes
Yes
Example 5.4 5. Creating a new tag
[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine
tag" --parent MyParentTag
5.21. 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 Virtualization
environment.
Chapter 5. Resource Types
61
Table 5.56. Quota parameters
Name
Type
Description
Requ
ired
User
Crea
table
User
Upda
table
--nam e
string
The name of the quota.
Yes
Yes
Yes
--
description
string
A description for the quota.
Yes
Yes
Yes
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
62
Chapter 6. CLI Queries
6.1. Query Syntax
The CLI list command uses the --query attribute to perform server-side queries, which uses the
same format as Red Hat Enterprise Virtualization Manager search query language:
Table 6.1. Example search queries
Collection
Criteria
Result
hosts
vm s.status=up
Displays a list of all hosts
running virtual machines that
are up.
vm s
dom ain=qa.com pany.com
Displays a list of all virtual
machines running on the
specified domain.
vm s
users.nam e=m ary
Displays a list of all virtual
machines belonging to users
with the username mary.
events
severity>norm al sortby
tim e
Displays the list of all events
with severity higher than
norm al and sorted by the
tim e element values.
events
severity>norm al sortby
tim e desc
Displays the list of all events
with severity higher than
norm al and sorted by the
tim e element values in
descending order.
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.
Chapter 6. CLI Queries
63
Revision History
Revision 3.2-13.4 00
2013-10-31
Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 3.2-13
Mon May 27 2013
Cheryn Tan
Built for RHEV 3.2 general availability.
Revision 3.2-12
Fri May 03 2013
Andrew Burden
Added 'draft' status to build
Revision 3.2-11
Tue Apr 23 2013
Andrew Burden
BZ#947707 - Added '--expect' and 'correlation_id' to datacenter parameter table
BZ#947713 - Added '--threads_as_cores', '--expect', and '--correlation_id' to cluster parameter table
Revision 3.2-10
Wed Apr 17 2013
Andrew Burden
BZ#947009 - Added kwargs option
Revision 3.2-9
Tue Mar 26 2013
Andrew Burden
BZ#923073 - Corrected the 'add glustervolume' example
BZ#927028 - Added 'TLS/SSL Certification' topic
Revision 3.2-8
Wed Mar 13 2013
Andrew Burden
Updated autopage in .rhevmshellrc section
Revision 3.2-7
Tue Mar 05 2013
Andrew Burden
Fixed typos in .rhevmshellrc section
Revision 3.2-6
Fri Mar 01 2013
Andrew Burden
Brew for BETA-1
Revision 3.2-6
Mon Feb 11 2013
Andrew Burden
BZ#909107 - incorrect query value
BZ#884690 - added admonition
Revision 3.2-5
Fri Feb 1 2013
Andrew Burden
Fixed a formatting problem
Revision 3.2-4
Thu Jan 31 2013
Andrew Burden
Updated RHN Channel information
Revision 3.2-3
Wed Jan 23 2013
Andrew Burden
BZ#893782 - Updated the 'Required' field.
Revision 3.2-1
Tue Jan 22 2013
Andrew Burden
BZ#893782 - Corrected rhevm-shell connection examples to include certification authority.
BZ#891722 - Created a topic describing variables for the .rhevmshellrc config file.
BZ#888491 - Replaced specific RHN channel with reference to 'Release Notes'.
BZ#885074 - Corrected "-a" option with "-A".
Revision History
65
BZ#884690 - Updated rhevm-shell options.
Branched from 3.1 docs.
Red Hat Enterprise Virtualization 3.2 Command Line Shell Guide
66
Document Outline
- Table of Contents
- Preface
- Chapter 1. About the Command Line Interface
- Chapter 2. Using the CLI
- Chapter 3. Quick Start Example
- Chapter 4. Commands
- 4.1. Connecting to RHEVM
- 4.2. Resources
- 4.3. Other Commands
- 4.3.1. .rhevmshellrc Configuration
- 4.3.2. Connect to VM (console)
- 4.3.3. Run a Shell Command (shell)
- 4.3.4. Run a Script (file)
- 4.3.5. Clear the Screen (clear)
- 4.3.6. Print Input (echo)
- 4.3.7. Show Last Status (status)
- 4.3.8. Show CLI Information (info)
- 4.3.9. Test Connection (ping)
- 4.3.10. Exit from the CLI (exit)
- 4.3.11. End of File (EOF)
- 4.3.12. Show Help (help)
- Chapter 5. Resource Types
- Chapter 6. CLI Queries
- Revision History
Wyszukiwarka
Podobne podstrony:
Red Hat Enterprise Virtualization 3 3 Command Line Shell Guide en US
Red Hat Storage 2 1 Console Command Line Shell Guide en US
Red Hat Enterprise Linux 5 Global Network Block Device en US
Red Hat Enterprise Linux OpenStack Platform 2 Release Notes en US
Red Hat Enterprise Linux 5 Beta 5 11 Release Notes en US
Red Hat Enterprise Virtualization 3 1 User Portal Guide en US
Red Hat Enterprise Virtualization 3 2 User Portal Guide en US
Red Hat Enterprise Virtualization 3 0 Hypervisor Deployment Guide en US
Red Hat Enterprise Virtualization 3 0 User Portal Guide en US
Red Hat Enterprise Linux 6 Virtualization Tuning and Optimization Guide en US
Red Hat Enterprise Virtualization 3 2 Manager Release Notes en US
Red Hat Enterprise Linux OpenStack Platform 3 Deployment Guide Foreman Technology Preview en US
Red Hat Storage 2 0 2 0 Update 4 and Update 5 Release Notes en US
Red Hat Enterprise Linux 6 Beta Virtualization Getting Started Guide en US
Red Hat Enterprise Linux 6 Virtualization Getting Started Guide en US
Red Hat Enterprise Linux 6 Performance Tuning Guide en US
Red Hat Enterprise MRG 2 Tuna User Guide en US
Red Hat Enterprise Linux 6 Migration Planning Guide en US
red hat enterprise linux 5 io tuning guide
więcej podobnych podstron