Red Hat Enterprise Virtualization 3.3

Command Line Shell Guide

A Guide for Installing and Using the Command Line Shell for Red Hat Enterprise Virtualization

Legal Notice

Copyright © 2014 Red Hat.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. 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
Preface
1. Document Conventions
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!
1. About the Command Line Interface
1.1. Introduction to the Command Line Interface
2. Using the CLI
2.1. Installing the CLI
2.2. TLS/SSL Certification
2.3. Running the CLI
2.4. Interacting with the CLI
2.5. Collections
3. Quick Start Example
3.1. Creating a Basic Virtualization Environment with the CLI
4. Commands
4.1. Connecting to RHEVM
4.1.1. Connect to RHEVM (connect)
4.1.2. Disconnect from RHEVM (disconnect)
4.2. Resources
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. 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. Show System Summary (summary)
4.3.10. Test Connection (ping)
4.3.11. Exit from the CLI (exit)
4.3.12. End of File (EOF)
4.3.13. Show Help (help)
5. Resource Types
5.1. brick
5.2. cdrom
5.3. cluster
5.4. datacenter
5.5. disk
5.6. glustervolume
5.7. group
5.8. host
5.9. network
5.10. nic
5.11. permission
5.12. permit
5.13. quotas
5.14. role
5.15. snapshot
5.16. storageconnection
5.17. storagedomain
5.18. tag
5.19. template
5.20. user
5.21. vm
5.22. vmpool
5.23. vnicprofile
6. CLI Queries
6.1. Query Syntax
6.2. Wildcards
A. Revision History

Preface

⁠1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

⁠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 submenu 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 → 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 Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your 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: 
​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 Portal at http://access.redhat.com. Through the customer portal, you can:
  • search or browse through a knowledgebase of technical support articles about Red Hat products.
  • submit a support case to Red Hat Global Support Services (GSS).
  • access other product documentation.
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: http://bugzilla.redhat.com/ against the product Red Hat Enterprise Virtualization.
When submitting a bug report, be sure to mention the manual's identifier: Guides-CLI
If you have a suggestion for improving the documentation, try to be as specific as possible 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.

⁠Chapter 1. About the Command Line Interface

1.1. Introduction to 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.
Report a bug

⁠Chapter 2. Using the CLI

2.1. Installing the CLI
2.2. TLS/SSL Certification
2.3. Running the CLI
2.4. Interacting with the CLI
2.5. Collections

⁠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-3.3-rpms
    RHN Classic instructions
    # rhn_register
# rhn-channel --add --channel=rhel-x86_64-server-6-rhevm-3.3

    Note

    See the Red Hat Enterprise Virtualization Manager Release Notes for specific channel names current to your system.
  3. Install the CLI package and dependencies: 
    # yum install rhevm-cli
Report a bug

⁠2.2. TLS/SSL Certification

The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure (HTTPS) ⁠[1] for secure interaction with client software, such as the Manager's SDK and CLI components. This involves a process of obtaining a certificate from the Red Hat Enterprise Virtualization Manager and importing it into the certificate store of your client.

Important

Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a secure network connection.
⁠

Procedure 2.1. Obtaining a Certificate

You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to the client machine using one of three methods:
  1. Method 1 - Use a command line tool to download the certificate from the Manager. Examples of command line tools include cURL and Wget, both of which are available on multiple platforms.
    1. If using cURL: 
      $ curl -o rhevm.cer http://[rhevm-server]/ca.crt
    2. 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.
    1. 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 - Log in to the Manager, export the certificate from the truststore and copy it to your client machine.
    1. Log in to the Manager as the root user.
    2. Export the certificate from the truststore using the Java keytool management utility: 
      $ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer
      This creates a certificate file called rhevm.cer.
    3. Copy the certificate to the client machine using the scp command: 
      $ scp rhevm.cer [username]@[client-machine]:[directory]
Each of these methods results in a certificate file named rhevm.cer on your client machine. An API user imports this file into the certificate store of the client.
⁠

Procedure 2.2. Importing a Certificate to a Client

  • Importing a certificate to a client relies on how the client itself stores and interprets certificates. This guide contains some examples on importing certificates. For clients not using Network Security Services (NSS) or Java KeyStore (JKS), see your client documentation for more information on importing a certificate.
Report a bug

⁠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 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 user name 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 use rname 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
Specify server Certificate Authority file.
-I, --insecure
Allow the CLI to connect via SSL without certification. Use this option with caution because it can 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.
-e, --extended-prompt
Enables the extended prompt option for the shell. This option displays the hostname of the environment in the command prompt. Default is 'false'.

Note

Although users can use the --file option to call a file that includes their password information, this practice is not recommended for security reasons. Users with a non-interactive shell are able to connect to the Red Hat Enterprise Virtualization Manager from within the shell, where the --password option can be used.
Report a bug

⁠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.
⁠

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.
⁠

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
Report a bug

⁠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.
Report a bug

[1] HTTPS is described in RFC 2818 HTTP Over TLS.

⁠Chapter 3. Quick Start Example

3.1. Creating a Basic Virtualization Environment with the CLI

⁠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 --username [user]@[domain] --ca-file certificate/authority/path/name

  2. List data centers

    Red Hat Enterprise Virtualization Manager adds a Default data center on installation. 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. 
    [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 storagedomain 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. 
    [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
    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. Show Event

    Use show event to display comprehensive details of an event. This command can be used to show events by type, name and id. 
    [RHEVM shell (connected)]# show event --id 60

id            : 60
description   : New Tag foo was created by admin@internal.
code          : 432
correlation_id: 3e4d4350
custom_id     : -1
flood_rate    : 30
origin        : oVirt
severity      : normal
time          : 2013-07-03 10:57:43.257000+03:00
user-id       : fdfc627c-d875-11e0-90f0-83df133b58cc

  16. Access Virtual Machine

    Access your virtual machine with the console command. 
    [RHEVM shell (connected)]# console MyVM

    Important

    Ensure your client machine has a console application installed to match the virtual machine's display-type. Protocols available include SPICE (default) and VNC.
Report a bug

⁠Chapter 4. Commands

4.1. Connecting to RHEVM
4.1.1. Connect to RHEVM (connect)
4.1.2. Disconnect from RHEVM (disconnect)
4.2. Resources
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. 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. Show System Summary (summary)
4.3.10. Test Connection (ping)
4.3.11. Exit from the CLI (exit)
4.3.12. End of File (EOF)
4.3.13. Show Help (help)

⁠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
--username The user name 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. Use this option with caution because it can 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
--timeout The timeout period for connection. No
⁠

Example 4.1. Example for connect

[RHEVM shell (disconnected)]# connect --url "https://rhevm.example.com/api" --username "admin@exampleids.com" --password "p@55w0rd!" --ca-file "/home/user/ca.crt"

 ==========================================
 >>> connected to RHEVM manager 3.2.0.0 <<<
 ==========================================

[RHEVM shell (connected)]#

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.
Report a bug

⁠4.1.2. Disconnect from RHEVM (disconnect)

The disconnect command disconnects from Red Hat Enterprise Virtualization Manager.
Syntax
disconnect
⁠

Example 4.2. Example for disconnect

[RHEVM shell (connected)]# disconnect

  =======================================
  >>> disconnected from RHEVM manager <<<
  =======================================

[RHEVM shell (disconnected)]#
Report a bug

⁠4.2. Resources

⁠4.2.1. List Resources in a 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]
⁠

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.
--kwargs [QUERY] Filters the list using a client-side query.
--case_sensitive true|false Match search queries using case sensitivity.
--max 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 client-side query: 
[RHEVM shell (connected)]# list vms --query "status=up"
List users by their user names with a client-side query: 
[RHEVM shell (connected)]# list users --query "usrname=jsmith@*"  --case_sensitive false
Get help with list search syntax: 
[RHEVM shell (connected)]# list --help
Report a bug

⁠4.2.2. Show a Resource (show)

Use the show command to display resource properties.
Syntax
show [resource] [id|name] [options]
⁠

Table 4.3. show standard options

Option Description
--id [UUID] Identify resource with the resource's UUID value.
--name [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
Report a bug

⁠4.2.3. Add a Resource (add)

Use the add command to add a new resource.
Syntax
add [resource] [options]

Note

Options specific to resource types are listed in the definition pages for each resource type.
⁠

Example 4.5. Examples for add

Create a virtual machine: 
[RHEVM shell (connected)]# add vm [vm-options]
Create a user: 
[RHEVM shell (connected)]# add user [user-options]
The add command can be made synchronous (if supported) by using the expect option: 
[RHEVM shell (connected)]# add vm [vm-options] --expect '201-created'
Report a bug

⁠4.2.4. Update a Resource (update)

Use the update command to modify an existing resource.
Syntax
update [resource] [id|name] [options]

Note

Options specific to resource types are listed in the definition pages for each resource type.
⁠

Example 4.6. Examples for update

Update a virtual machine: 
[RHEVM shell (connected)]# update vm RHEL6-Server [vm-options]
Report a bug

⁠4.2.5. Remove a Resource (remove)

Use the remove command to remove a resource.
Syntax
remove [resource] [id|name] [options]
⁠

Table 4.4. remove standard 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.
⁠

Example 4.7. Examples for remove

Remove a virtual machine: 
[RHEVM shell (connected)]# remove vm RHEL6-Server
Asynchronous removal of a virtual machine: 
[RHEVM shell (connected)]# remove vm RHEL6-Server --async true
Force remove virtual machine: 
[RHEVM shell (connected)]# remove vm RHEL6-Server --force
Report a bug

⁠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
The action command can be made synchronous (if supported) by using the async option: 
[RHEVM shell (connected)]# action vm [vm-options] --async false
Report a bug

⁠4.2.7. Using Sub-Resources (--RESOURCE-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.
⁠

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.
Report a bug

⁠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.
username
string
User name to be used to log in.
password
string
Password to be used for user name.
insecure
boolean
Toggles CA certificate requirement. The status is either True or False.
autopage
boolean
Toggles pagination in the shell. The status is either True or False.
filter
boolean
Toggles object filtering. Object filtering allows users to fetch objects according to their permissions. Only admin roles can toggle filtering off. The status is either True or False.
timeout
integer
Requests timeout. The default is -1.
extended_prompt
boolean
Toggles the extended prompt option, which displays the hostname in the shell command prompt
Report a bug

⁠4.3.2. Connect to VM (console)

Use the console command to open a graphical console to a virtual machine. This command opens either an external VNC or SPICE client based upon the virtual machine's display-type parameter.
Syntax
console [vm-id|vm-name]
⁠

Example 4.10. Example for console

Open graphical console to a virtual machines: 
[RHEVM shell (connected)]# console RHEL6-Server
Report a bug

⁠4.3.3. Run a Shell Command (shell)

Use the shell command to run a command from the Linux shell. This command helps 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
Report a bug

⁠4.3.4. Run a Script (file)

Use the file command to run a CLI script file. A script is a plain text file that contains a list of commands for execution.
Syntax
file [file-location]
⁠

Example 4.12. Example for file

Run a script file: 
[RHEVM shell (connected)]# file /example/example-script
Report a bug

⁠4.3.5. Clear the Screen (clear)

Use the clear command to clear the CLI screen.
Syntax
clear
⁠

Example 4.13. Example for clear

Clear the screen: 
[RHEVM shell (connected)]# clear
Report a bug

⁠4.3.6. Print Input (echo)

Use the echo command to print input to the screen. Use the $out variable to print the last 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
Report a bug

⁠4.3.7. Show Last Status (status)

Use the status command to display the most recently run command status.
Syntax
status
⁠

Example 4.15. Example for status

View the last status: 
[RHEVM shell (connected)]# status

last command status: 0 (OK)
Report a bug

⁠4.3.8. Show CLI 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
Report a bug

⁠4.3.9. Show System Summary (summary)

Use the summary command to display a summary of the system status.
Syntax
summary
⁠

Example 4.17. Example for summary

Display system status: 
[RHEVM shell (connected)]# summary

hosts-active          : 1
hosts-total           : 2
storage_domains-active: 2
storage_domains-total : 3
users-active          : 1
users-total           : 1
vms-active            : 1
vms-total             : 1
Report a bug

⁠4.3.10. 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, user name and password for the connection are correct.
Syntax
ping
⁠

Example 4.18. Example for ping

Test your connection: 
[RHEVM shell (connected)]# ping

success: RHEVM manager could be reached OK.
Report a bug

⁠4.3.11. Exit from the CLI (exit)

Use the exit command to leave a CLI.
Syntax
exit
⁠

Example 4.19. Example for exit

Leave the CLI: 
[RHEVM shell (connected)]# exit
Report a bug

⁠4.3.12. End of File (EOF)

Use the EOF command to leave the CLI shell using a Ctrl+D sequence.
Syntax
EOF
⁠

Example 4.20. Example for EOF

Leave the CLI shell: 
[RHEVM shell (connected)]# EOF
Report a bug

⁠4.3.13. Show Help (help)

Use the help command displays help for CLI command and resource combinations.
Syntax
help [command] [resource] [options]
⁠

Example 4.21. Examples for help

Get CLI help: 
[RHEVM shell (connected)]# help
Get help for the add command: 
[RHEVM shell (connected)]# help add
Get help for the add command on the vm resource type: 
[RHEVM shell (connected)]# help add vm
Report a bug

⁠Chapter 5. Resource Types

5.1. brick
5.2. cdrom
5.3. cluster
5.4. datacenter
5.5. disk
5.6. glustervolume
5.7. group
5.8. host
5.9. network
5.10. nic
5.11. permission
5.12. permit
5.13. quotas
5.14. role
5.15. snapshot
5.16. storageconnection
5.17. storagedomain
5.18. tag
5.19. template
5.20. user
5.21. vm
5.22. vmpool
5.23. vnicprofile

⁠5.1. brick

Important

The information in this section is provided as a technical preview only.
The brick resource type groups all Gluster bricks in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.1. Gluster brick parameters

Name Type Description Required User Creatable User Updatable
--server_id
string
The address of the Gluster server.
Yes
Yes
No
--brick_dir
string
The brick's directory on the Gluster server.
Yes
Yes
No
--replica_count
integer
Defines the file replication count for a replicated volume.
No
Yes
No
--stripe_count
Integer
Defines the stripe count for a striped volume
No
Yes
No
The following table lists additional glustervolume options for resource-based commands.
⁠

Table 5.2. Additional command options

Option Description
--cluster-identifier Reference to the cluster that contains a glustervolume sub-resource.
--glustervolume-identifier Adds the brick to a glustervolume as a sub-resource.
⁠

Example 5.1. Creating a bricks

[RHEVM shell (connected)]# add brick --cluster-identifier Default --glustervolume-identifier GlusterVol1 --server_id="server1" --brick_dir="/exp1"
Report a bug

⁠5.2. cdrom

The cdrom resource type groups all virtual CD-ROM drive resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.3. CD-ROM parameters

Name Type Description Required User Creatable User Updatable
--file-id
string
Defines the file name of the ISO that resides on an ISO storage domain.
Yes
Yes
Yes
⁠

Example 5.2. 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.3. 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.4. Deleting a CD-ROM

[RHEVM shell (connected)]# remove cdrom --vm-identifier MyVM rhel-server-6.3-x86_64-dvd.iso.iso
Report a bug

⁠5.3. cluster

The cluster resource type groups all host cluster resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.4. Cluster parameters

Name Type Description Required User Creatable User Updatable
--data_center-id|name
string
A reference to the data center for a host cluster.
Yes
Yes
No
--name
string
The name of a host cluster.
Yes
Yes
Yes
--version-major
int
The major version number of the cluster. For example, for Red Hat Enterprise Virtualization 3.2, the major version is 3.
Yes
Yes
Yes
--version-minor
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
--memory_policy-overcommit-percent
double
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
--memory_policy-transparent_hugepages-enabled
Boolean
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-thresholds-duration
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
--error_handling-on_error
string
Defines virtual machine handling when a host within a cluster becomes non-operational, including migrate, do_not_migrate and migrate_highly_available.
No
Yes
Yes
--virt_service
Boolean
.The status is either true or false.
No
Yes
Yes
--gluster_service
Boolean
.The status is either true or false.
No
Yes
Yes
--threads_as_cores
Boolean
Hosts treat threads as cores, allowing hosts 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-created'
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.5. 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.6. Updating a cluster

[RHEVM shell (connected)]# update cluster Engineering --name Finance
⁠

Example 5.7. Deleting a cluster

[RHEVM shell (connected)]# remove cluster Engineering
Report a bug

⁠5.4. datacenter

The datacenter resource type groups all data center resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.5. Data Center Parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the data center.
Yes
Yes
Yes
--storage_type
string
The type of storage for the data center, including iscsi, fcp, nfs, localfs or posixfs.
Yes
Yes
Yes
--version-major
int
The major version number of the data center. For example, for Red Hat Enterprise Virtualization 3.2, the major version is 3.
Yes
Yes
Yes
--version-minor
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_format
string
The metadata format for the data center, including v1, v2 or v3.
No
Yes
Yes
--expect
'201-created'
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.8. Creating a new data center

[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --version-major 3 --version-minor 2
⁠

Example 5.9. Updating a data center

[RHEVM shell (connected)]# update datacenter Boston --name India
⁠

Example 5.10. Deleting a data center

[RHEVM shell (connected)]# remove datacenter Boston
Report a bug

⁠5.5. disk

The disk resource type groups all virtual hard disk resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.6. Disk parameters

Name Type Description Required User Creatable User Updatable
--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
--format
 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
 Boolean
true if the physical storage for the disk should not be preallocated.
No
Yes
Yes
--bootable
 Boolean
true if this disk is to be marked as bootable.
No
Yes
Yes
--shareable
 Boolean
true if this disk is shareable.
No
Yes
Yes
--allow_snapshot
 Boolean
true if this disk allows snapshots.
No
Yes
Yes
--propagate_errors
 Boolean
true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS.
No
Yes
Yes
--wipe_after_remove
 boolean
true if the underlying physical storage for the disk should be zeroed when the disk is removed.
No
Yes
Yes
--storage_domains-storage_domain
 collection
Defines a specific storage domain for the disk.
No
Yes
No
The --storage_domains-storage_domain parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.7. --storage_domains-storage_domain parameters

Name Type Description
storage_domain.id|name
string
A reference to a storage domain for the disk.
The following table lists additional disk options for resource-based commands.
⁠

Table 5.8. 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.11. Creating a new disk

[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size 8589934592 --interface virtio --format cow
⁠

Example 5.12. Updating a storage domain

[RHEVM shell (connected)]# update disk MyDisk --shareable true
⁠

Example 5.13. Deleting a storage domain

[RHEVM shell (connected)]# remove disk MyDisk
The following table lists actions for a virtual machine disk resource.
⁠

Table 5.9. Virtual machine disk actions

Action Description
activate Activate a disk on a virtual machine.
deactivate Deactivate a disk on a virtual machine.
Report a bug

⁠5.6. glustervolume

Important

The information in this section is provided as a technical preview only.
The glustervolume resource type groups all Gluster storage volume resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.10. Gluster volume parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the Gluster volume.
Yes
Yes
No
--volume_type
string
Defines the Gluster volume type. Choose from DISTRIBUTE, REPLICATE, DISTRIBUTED_REPLICATE, STRIPE or DISTRIBUTED_STRIPE.
Yes
Yes
No
--bricks-brick
collection
A new Gluster volume requires a set of 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_types
collection
A reference to available transport methods for the Gluster volume. See below for collection details.
No
Yes
No
--replica_count
integer
Defines the file replication count for a replicated volume.
No
Yes
No
--stripe_count
Integer
Defines the stripe count for a striped volume
No
Yes
No
--options-option
collection
A reference to options for the Gluster volume. 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.11. 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.12. 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.
⁠

Table 5.13. options-option parameters

Name Type Description
option.name
string
The Gluster option name.
option.value
string
The Gluster option value.
The following table lists additional glustervolume options for resource-based commands.
⁠

Table 5.14. Additional command options

Option Description
--cluster-identifier Adds the Gluster volume to a cluster as a sub-resource.
⁠

Example 5.14. 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.15. 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.15. 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.
Report a bug

⁠5.7. group

The group resource type defines all identity service groups for a Red Hat Enterprise Virtualization environment.
⁠

Table 5.16. Group parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the group, usually the full group path within the identity directory service.
No
No
No
⁠

Example 5.16. Creating a group

[RHEVM shell (connected)]# add group --name www.example.com/accounts/groups/mygroup
Report a bug

⁠5.8. host

The host resource type groups all host resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.17. Host parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the host.
Yes
Yes
Yes
--address
string
The IP address or hostname for the host.
Yes
Yes
Yes
--root_password
string
The password for the host's root user.
Yes
Yes
Yes
--cluster-id|name
string
Defines the cluster that includes the host.
Yes
Yes
Yes
--port
int
The port for communication with the VDSM daemon running on the host.
No
Yes
Yes
--storage_manager-priority
int
Sets the priority of host order for storage pool manager (SPM).
No
Yes
Yes
--power_management-type
string
The fencing device code for host power management.
No
Yes
Yes
--power_management-enabled
boolean
Indicates whether power management configuration is enabled or disabled.
No
Yes
Yes
--power_management-address
string
The host name or IP address of the power management device.
No
Yes
Yes
--power_management-user_name
string
A valid user name for power management.
No
Yes
Yes
--power_management-password
string
A valid, robust password for power management.
No
Yes
Yes
--power_management-options-option
collection
Fencing options for the selected power_management-type.
No
Yes
Yes
--reboot_after_installation
boolean
Defines if the host reboots after VDSM installation.
No
Yes
No
The --power_management-options-option parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.18. --power_management-options-option parameters

Name Type Description
option.name
string
Power management option name.
option.value
string
Power management option value.
⁠

Example 5.17. Creating a new host

[RHEVM shell (connected)]# add host --name Host1 --address host1.example.com --root_password p@55w0rd! --cluster-name Default
⁠

Example 5.18. Updating a host

[RHEVM shell (connected)]# update host Host1 --name Host2
⁠

Example 5.19. Deleting a host

[RHEVM shell (connected)]# remove host Host1
The following table lists actions for a host resource.
⁠

Table 5.19. Host actions

Action Description
activate Activate a host.
approve Approve a host.
commitnetconfig Save the network configuration.
deactivate Deactivate a host.
fence Fence a host.
forceselectspm Select the host to be the Storage Pool Manager.
install Install VDSM on a host.
iscsidiscover Perform an iSCSI discover command.
iscsilogin Perform an iSCSI login command.
The following table lists additional options for the fence action.
⁠

Table 5.20. Fencing options

Option Description
manual Manually fence the host. Use this action to confirm to the Manager that the host became non-responsive and was manually rebooted.
restart Restart the host, implemented as stop, wait, status, start, wait, status.
start Power on the host.
stop Power off the host.
status Check the operational status of the host.
Report a bug

⁠5.9. network

The network resource type groups all logical network resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.21. Logical network parameters

Name Type Description Required User Creatable User Updatable
--data_center-id|name
string
A reference to the data center for a logical network.
Yes
Yes
No
--name
string
A plain text name for the logical network.
Yes
Yes
No
--description
string
A description for the logical network.
No
Yes
Yes
--vlan-id
string
A VLAN tag.
No
Yes
Yes
--ip-address
string
The IP address for the logical network's bridge.
No
Yes
Yes
--ip-gateway
string
The gateway for the logical network's bridge.
No
Yes
Yes
--ip-netmask
string
The netmask for the logical network's bridge.
No
Yes
Yes
--display
boolean
Signifies if a logical network is used for display communication usage. Set to either true or false.
No
Yes
Yes
--stp
boolean
Set to true if Spanning Tree Protocol is enabled on this network.
No
Yes
Yes
--mtu
int
Sets a user-defined value for the maximum transmission unit of the logical network.
No
Yes
Yes
--usages-usage
collection
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.22. 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.23. Additional command options

Option Description
--cluster-identifier Adds the network to a cluster as a sub-resource.
⁠

Example 5.20. Creating a new network

[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name Default --cluster-identifier Default
⁠

Example 5.21. Updating a network

[RHEVM shell (connected)]# update network WebNetwork --name DataNetwork
⁠

Example 5.22. Deleting a network

[RHEVM shell (connected)]# remove network WebNetwork
Report a bug

⁠5.10. nic

The nic resource type groups network interface resources in a Red Hat Enterprise 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.
⁠

Table 5.24. Host network interface parameters

Name Type Description Required User Creatable User Updatable
--network-id|name
 string
A reference to the network, if any, that the interface is attached.
Yes
Yes
Yes
--name
 string
The name of the host network interface, e.g. eth0.
Yes
Yes
Yes
--bonding-slaves-host_nic
 collection
A collection of slave network interfaces that form a bonded interface.
No
Yes
Yes
--bonding-options-option
 collection
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_protocol
 string
The protocol for IP address assignment when the host is booting, such as dhcp or static.
No
Yes
Yes
--mac
 string
The MAC address of the interface.
No
Yes
Yes
--ip-address
 string
The IP address of the interface.
No
Yes
Yes
--ip-netmask
 string
The netmask for the interface's IP address.
No
Yes
Yes
--ip-mtu
int
The maximum transmission unit for the interface.
No
No
Yes
⁠

Table 5.25. Virtual Machine network interface parameters

Name Type Description Required User Creatable User Updatable
--network-id|name
 string
A reference to the network, if any, that the interface is attached.
Yes
Yes
Yes
--name
 string
The name of the interface, e.g. eth0.
Yes
Yes
Yes
--mac-address
 string
The MAC address of the interface.
No
Yes
Yes
--interface
 string
Defines the interface type, such as e1000, virtio, rtl8139 and rtl8139_virtio.
No
Yes
Yes
--port_mirroring-networks-network
 collection
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.
⁠

Table 5.26. --bonding-slaves-host_nic

Name Type Description
host_nic.id|name
string
A reference to another host NIC to bond.
The --bonding-options-option parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.27. --bonding-options-option

Name Type Description
option.name
string
The bonding option name.
option.value
string
The bonding option value.
type
string
The bonding option type.
The --port_mirroring-networks-network parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.28. --port_mirroring-networks-network

Name Type Description
network.id
string
A reference to the network to mirror.
The following table lists additional NIC options for resource-based commands.
⁠

Table 5.29. 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.23. Creating a new network interface on a host

[RHEVM shell (connected)]# add nic --host-identifier MyHost1 --name eth0 --network MyNetwork
⁠

Example 5.24. Creating a new network interface on a virtual machine

[RHEVM shell (connected)]# add nic --vm-identifier MyVM1 --name eth0 --network MyNetwork
⁠

Example 5.25. Updating a network interface

[RHEVM shell (connected)]# update nic eth0 --vm-identifier MyVM1 --ip-address 10.5.68.123
⁠

Example 5.26. 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.30. 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.31. Virtual machine NIC actions

Action Description
activate Activate a NIC on a virtual machine.
deactivate Deactivate a NIC on a virtual machine.
Report a bug

⁠5.11. permission

The permission resource type groups all permission resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.32. Permission parameters

Name Type Description Required User Creatable User Updatable
--user-identifier, --group-identifier
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.33. Additional command options

Option Description
--cluster-identifier
Adds the permission to a cluster.
--datacenter-identifier
Adds the permission to a data center.
--disk-identifier
Adds the permission to a disk.
--host-identifier
Adds the permission to a host.
--network-identifier
Adds the permission to a network.
--storagedomain-identifier
Adds the permission to a storage domain.
--template-identifier
Adds the permission to a template.
--vm-identifier
Adds the permission to a virtual machine.
--vmpool-identifier
Adds the permission to a virtual machine pool.
--vnicprofile-identifier
Adds the permission to a VNIC profile.
⁠

Example 5.27. Creating a new permission

[RHEVM shell (connected)]# add permission --vm-identifier MyVM1 --role-id 00000000-0000-0000-0000-000000000001 --user-id 8b9456ae-e2c8-426e-922d-b01bb8a805fb --data_center-id 5849b030-626e-47cb-ad90-3ce782d831b3
Report a bug

⁠5.12. permit

The permit resource type groups all individual permits for roles in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.34. Permission parameters

Name Type Description Required User Creatable User Updatable
--id
string
A reference to the permit to add.
Yes
Yes
No
The following table lists additional permit options for resource-based commands.
⁠

Table 5.35. Additional command options

Option Description
--role-identifier
Adds the permit to a role.
⁠

Example 5.28. Creating a new permission

[RHEVM shell (connected)]# add permit --role-identifier MyRole --id 1
Report a bug

⁠5.13. quotas

Important

The information in this section is provided as a technical preview only.
The quota resource type groups all datacenter quotas in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.36. Quota parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the quota.
Yes
Yes
Yes
--description
string
A description for the quota.
Yes
Yes
Yes
Report a bug

⁠5.14. role

The role resource type groups all individual roles in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.37. Role parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the role.
Yes
Yes
Yes
--permits-permit
collection
A list of permits for initial inclusion with the role. Additional permits included with the permit resource type.
Yes
Yes
No
--description
string
A description for the role.
No
Yes
Yes
--administrative
Boolean
Set to true if this is an administrative role.
No
Yes
Yes
The --permits-permit parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.38. --permits-permit parameters

Name Type Description
permit.id
string
A reference to a permit to add to the role's permits.
⁠

Example 5.29. Creating a new role

[RHEVM shell (connected)]# add role --name MyRole --permits-permit {permit.id: 1;},{permit.id: 2;)
Report a bug

⁠5.15. snapshot

The snapshot resource type groups all virtual machine snapshot resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.39. Snapshot parameters

Name Type Description Required User Creatable User Updatable
--description
string
A description for the snapshot.
Yes
Yes
No
The following table lists additional snapshot options for resource-based commands.
⁠

Table 5.40. Additional command options

Option Description
--vm-identifier Adds the disk to a vm as a sub-resource.
⁠

Example 5.30. Creating a new snapshot

[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description 'My Snapshot'
⁠

Example 5.31. Deleting a storage domain

[RHEVM shell (connected)]# remove snapshot [snapshot_id]
The following table lists actions for a virtual machine snapshot resource.
⁠

Table 5.41. Virtual machine snapshot actions

Action Description
restore Restore a snapshot.
Report a bug

⁠5.16. storageconnection

The storageconnection resource type allows you to add, edit, and delete storage connections.
⁠

Table 5.42. Storage connection parameters

Name Type Description Required User Creatable User Updatable
--address
string
The hostname or IP address of the storage domain.
Yes (NFS and iSCSI only)
Yes
Yes
--correlation_id
string
A tagging identifier for the storage connection.
No
No
Yes
--expect
'201-created'
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
--iqn
string
The target IQN for the storage device.
Yes (iSCSI only)
Yes
Yes
--mount_options
string
The options for mounting the PosixFS share.
No
Yes
Yes
--nfs_retrans
integer
The number of retransmissions the NFS client will attempt to complete a request.
No
Yes
Yes
--nfs_timeo
integer
The amount of time, in deciseconds, the NFS client will wait for a request to complete.
No
Yes
Yes
--nfs_version
string
The version of NFS used.
No
Yes
Yes
--password
string
A CHAP password for logging into a target of an iSCSI storage domain.
No
Yes
Yes
--path
string
The mounted file path of the storage domain. The path cannot be updated to one already used by a storage connection.
Yes (NFS, local, and PosixFS only)
Yes
Yes
--port
integer
The TCP port used for the iSCSI storage domain.
Yes (iSCSI only)
Yes
Yes
--storagedomain-identifier
string
A reference to a storage domain for the disk.
No
No
No
--type
string
The type of storage domain.
Yes
Yes
No
--username
string
A CHAP user name for logging into a target of an iSCSI storage domain.
No
Yes
Yes
--vfs_type
string
The Linux-supported file system type of the PosixFS share.
Yes (PosixFS only)
Yes
Yes
⁠

Example 5.32. Creating a new storage connection

[RHEVM shell (connected)]# add storageconnection --address storage.example.com --path /storage/nfs --type nfs
Report a bug

⁠5.17. storagedomain

The storagedomain resource type groups all storage domain resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.43. Storage domain parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the storage domain.
No
Yes
Yes
--format
Boolean
The metadata format for the data center, including v1, v2 or v3.
Yes
Yes
No
--host-id|name
string
A reference to the host from which this 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_unit
collection
The logical unit information of the storage device.
See below
Yes
No
--storage-mount_options
string
The options for mounting the storage domain.
See below
Yes
No
--storage-override_luns
Boolean
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
The --storage-logical_unit parameter is a collection that requires all sub-parameters in the following table.
⁠

Table 5.44. storage-logical_unit parameters

Name Type Description
logical_unit.address
string
The address of the server containing the storage device.
logical_unit.port
integer
The port number of the server.
logical_unit.target
string
The target IQN for the storage device.
logical_unit.username
string
A CHAP user name for logging into a target.
logical_unit.password
string
A CHAP password for logging into a target.
logical_unit.serial
string
The serial ID for the target.
logical_unit.vendor_id
string
The vendor name for the target.
logical_unit.product_id
string
The product code for the target.
logical_unit.lun_mapping
integer
The Logical Unit Number device mapping for the target.
logical_unit.portal
string
The logical unit portal.
logical_unit.paths
integer
The logical unit paths.
logical_unit.id
string
A reference to the logical unit ID.
Use the following parameters depending on storage-type.
⁠

Table 5.45. 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-mount_options
The following table lists additional storagedomain options for resource-based commands.
⁠

Table 5.46. Additional command options

Option Description
--datacenter-identifier Adds the storage domain to a datacenter as a sub-resource.
⁠

Example 5.33. Creating a new storage domain

[RHEVM shell (connected)]# add storagedomain --name DataStorage --datacenter-name Default -type data
⁠

Example 5.34. Updating a storage domain

[RHEVM shell (connected)]# update storagedomain DataStorage --name DataStorageOld
⁠

Example 5.35. Deleting a storage domain

[RHEVM shell (connected)]# remove storagedomain DataStorage
The following table lists actions for a storage domain resource.
⁠

Table 5.47. Storage domain actions

Action Description
activate Activate a storage domain on a data center.
deactivate Deactivate a storage domain on a data center.
Report a bug

⁠5.18. tag

The tag resource type groups all tags in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.48. Tag parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the tag.
Yes
Yes
Yes
--description
string
A description for the string.
Yes
Yes
Yes
--parent-name
string
A reference to the parent tag that the tag is attached.
Yes
Yes
Yes
⁠

Example 5.36. Creating a new tag

[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine tag" --parent MyParentTag
Report a bug

⁠5.19. template

The template resource type groups all virtual machine templates in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.49. Template parameters

Name Type Description Required User Creatable User Updatable
--vm-id|name
string
A reference to the virtual machine used as a basis for the template.
Yes
Yes
No
--name
string
The name of the virtual machine template.
Yes
Yes
Yes
--memory
long
The amount of memory for the virtual machine template in bytes.
No
Yes
Yes
--cpu-topology-cores
int
The number of CPU cores available to the virtual machine template.
No
Yes
Yes
--high_availability-enabled
Boolean
Defines if high availability is enabled for the virtual machine template.
No
Yes
Yes
--os-cmdline
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, vmware or xen.
No
Yes
Yes
--high_availability-priority
int
Sets the priority value (i.e. boot order) of each virtual machine template's high availability.
No
Yes
Yes
--timezone
string
The the Sysprep timezone setting for a Windows virtual machine template.
No
Yes
Yes
--domain-name
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
boolean
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
--placement_policy-affinity
string
The migration affinity for each virtual machine created from the template. Includes migratable, user_migratable or pinned.
No
Yes
Yes
--description
string
A description for the template.
No
Yes
Yes
--custom_properties-custom_property
collection
A set of user-defined environment variables passed as parameters to custom scripts.
No
Yes
Yes
--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-monitors
int
Defines the number of displays available.
No
Yes
Yes
--display-allow_reconnect
Boolean
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
Boolean
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
collection
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.50. --custom_properties-custom_property parameters

Name Type Description
custom_property.name
string
The custom property name.
custom_property.value
string
The custom property value.
The --vm-disks-disk parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.51. --vm-disks-disk parameters

Name Type Description
disk.id
string
A reference to a virtual machine disk.
storage_domains.storage_domain
collection
Defines a set of sub-parameters for the disk's storage domain.
⁠

Example 5.37. Creating a new template

[RHEVM shell (connected)]# add template --name MyTemplate1 --vm-name MyVM1
⁠

Example 5.38. Updating a template

[RHEVM shell (connected)]# update template MyTemplate1 --memory 1073741824
⁠

Example 5.39. Deleting a template

[RHEVM shell (connected)]# remove template MyTemplate1
The following table lists actions for a virtual machine template resource.
⁠

Table 5.52. Virtual machine template actions

Action Description
export Export a template to an export storage domain.
Report a bug

⁠5.20. user

The user resource type groups all users in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.53. User parameters

Name Type Description Required User Creatable User Updatable
--user_name
string
The user name from the directory service.
Yes
Yes
No
--domain-id|name
string
A reference to the directory service domain.
Yes
Yes
No
⁠

Example 5.40. Creating a new user

[RHEVM shell (connected)]# add user --user_name jsmith --domain-name example.com
Report a bug

⁠5.21. vm

The vm resource type groups all virtual machine resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.54. Virtual machine parameters

Name Type Description Required User Creatable User Updatable
--cluster-id|name
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_properties-custom_property
collection
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
Boolean
Defines whether to clone the disk from the defined template.
No
Yes
No
--display-allow_reconnect
Boolean
Defines whether to allow reconnection via console display.
No
Yes
Yes
--display-monitors
int
Defines the number of displays available.
No
Yes
Yes
--display-type
string
Defines the display type, including spice or vnc.
No
Yes
Yes
--domain-name
string
The domain name of the virtual machine.
No
Yes
Yes
--high_availability-enabled
Boolean
Defines if high availability is enabled for the virtual machine.
No
Yes
Yes
--high_availability-priority
int
Sets the priority value (migration and restart order) of each virtual machine using high availability.
No
Yes
Yes
--memory
long
The amount of memory for the virtual machine in bytes.
No
Yes
Yes
--name
string
The name of the virtual machine
Yes
Yes
Yes
--origin
string
The virtual machine's origin, including rhev, vmware or xen.
No
Yes
Yes
--os-boot-dev
string
The boot device for the virtual machine, including cdrom, hd, network.
No
Yes
Yes
--os-cmdline
string
A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
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
--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
collection
Defines content to send to the virtual machine upon booting.
No
Yes
Yes
--placement_policy-affinity
string
The migration affinity for each virtual machine, including migratable, user_migratable or pinned.
No
Yes
Yes
--placement_policy-host-id|name
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
Boolean
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
--template-id|name
string
A reference to the template used as the basis for the virtual machine.
Yes
Yes
No
--timezone
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
Boolean
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-created'
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.
⁠

Table 5.55. --custom_properties-custom_property parameters

Name Type Description
custom_property.name
string
The custom property name.
custom_property.value
string
The custom property value.
The --payloads-payload parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.56. --payloads-payload parameters

Name Type Description
payload.type
string
Payload delivery type, including cdrom or floppy.
payload.file.name
string
The payload file name and location on the root file system of the virtual machine.
payload.file.content
string
The content to deliver to the file.
⁠

Example 5.41. Creating a new virtual machine

[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-name Default --memory 536870912
⁠

Example 5.42. Updating a virtual machine

[RHEVM shell (connected)]# update vm MyVM --memory 1073741824
⁠

Example 5.43. Deleting a virtual machine

[RHEVM shell (connected)]# remove vm MyVM
The following table lists actions for a virtual machine resource.
⁠

Table 5.57. 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.
migrate Migrate the virtual machine to another host.
cancelmigration Stop migration in progress
export Export a virtual machine to an export storage domain
move Move virtual machine disks to another storage domain.
ticket Create a ticket for console access.
Report a bug

⁠5.22. vmpool

The vmpool resource type groups all virtual machine pool resources in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.58. Virtual machine pool parameters

Name Type Description Required User Creatable User Updatable
--cluster-id|name
string
A reference to the cluster for the virtual machine pool.
Yes
Yes
Yes
--template-id|name
string
A reference to the template for the virtual machine pool.
Yes
Yes
Yes
--name
string
The name of the virtual machine pool.
Yes
Yes
Yes
--size
integer
The number of the virtual machines in the pool.
Yes
Yes
Yes
⁠

Example 5.44. Creating a new virtual machine pool

[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-name MyTemplate --name MyPool --size 3
⁠

Example 5.45. Updating a virtual machine pool

[RHEVM shell (connected)]# update vmpool MyPool --size 4
⁠

Example 5.46. Deleting a virtual machine pool

[RHEVM shell (connected)]# remove vmpool MyPool
Report a bug

⁠5.23. vnicprofile

The vnicprofile resource type groups all VNIC (virtual network interface controller) profiles, also referred to as VM (virtual machine) interface profiles, in a Red Hat Enterprise Virtualization environment.
⁠

Table 5.59. Virtual Network Interface Controller Profile Parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the VNIC profile.
Yes
Yes
Yes
--network-id
string
A reference to the logical network to which the profile will be applied.
Yes
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
--description
string
A description for the profile.
No
Yes
Yes
--expect
'201-created'
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
--custom_properties-custom_property
collection
A set of user-defined environment variables passed as parameters to custom scripts.
No
Yes
Yes
--port_mirroring
Boolean
Toggles whether port mirroring is used for the profile. The status is either True or False. Default is Falses
No
No
No
The --custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
⁠

Table 5.60. --custom_properties-custom_property parameters

Name Type Description
custom_property.name
string
The custom property name.
custom_property.value
string
The custom property value.
⁠

Example 5.47. Creating a new vnic profile

[RHEVM shell (connected)]# add vnicprofile --name Gold --network-id 08305a2f-6952-4999-9646-c16137dc6d42
⁠

Example 5.48. Updating a vnic profile

[RHEVM shell (connected)]# update vnicprofile Gold --port_mirroring true
⁠

Example 5.49. Deleting a vnic profile

[RHEVM shell (connected)]# remove vnicprofile Gold
Report a bug

⁠Chapter 6. CLI Queries

6.1. Query Syntax
6.2. Wildcards

⁠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 vms.status=up Displays a list of all hosts running virtual machines that are up.
vms domain=qa.company.com Displays a list of all virtual machines running on the specified domain.
vms users.name=mary Displays a list of all virtual machines belonging to users with the user name mary.
events severity>normal sortby time Displays the list of all events with severity higher than normal and sorted by the time element values.
events severity>normal sortby time desc Displays the list of all events with severity higher than normal and sorted by the time element values in descending order.
Report a bug

⁠6.2. Wildcards

Search queries substitute part of a value with an asterisk as a wildcard.
⁠

Example 6.1. Wildcard search query for name=vm*

[RHEVM shell (connected)]# list vms --query "name=vm*"
This query would result in all virtual machines with names beginning with vm, such as vm1, vm2, vma or vm-webserver.
⁠

Example 6.2. Wildcard search query for name=v*1

[RHEVM shell (connected)]# list vms --query "name=v*1"
This query would result in all virtual machines with names beginning with v and ending with 1, such as vm1, vr1 or virtualmachine1.
Report a bug

Revision History

Revision History
Revision 3.3-10Tue 09 Dec 2014Andrew Burden
BZ#1142384 - Removed reference to Admin Guide search syntax; replaced with example showing syntax.
BZ#1142372 - Corrected the 'user_name' parameter and the example usage of 'domain-name'.
BZ#1142345 - Fixed example so that it correctly uses UUIDs instead of names. Made contents of tables match reality
Revision 3.3-9Thu 13 Mar 2014Andrew Burden
BZ#1055327 - Added examples to 'storageconnection' section.
Revision 3.3-8Mon 24 Feb 2014Andrew Burden
BZ#1055327 - Added resource type 'storageconnection'.
Revision 3.3-7Wed 19 Feb 2014Andrew Dahms
BZ#1039880 - Updated the command for exporting certificates from truststores.
Revision 3.3-6Fri 06 Dec 2013Andrew Dahms
BZ#1038837 - Changed references to 'version.number' to '3.3'.
Revision 3.3-5Mon 14 Oct 2013 Red Hat Engineering Content Services
BZ#999431 - Added table 'Fencing options' to host resource section.
Revision 3.3-4Thu 10 Oct 2013Andrew Burden
BZ#1016953 - New section 'vnicprofile' added.
Revision 3.3-3Tue 20 Aug 2013Andrew Burden
BZ#976628 - Documented the '--extended-prompt' option for the rhevm-shell.
BZ#998378 - Documented the 'forceselectspm' host action for manually selecting SPM.
BZ#976618 - New topic for 'summary' command.
Revision 3.3-2Thu 15 Aug 2013Andrew Burden
BZ#887860 - updated async and sync options for resources.
Revision 3.3-1Thu 18 Jul 2013Tim Hildred
Initial creation for Red Hat Enterprise Virtualization 3.3 release.