Red Hat Virtualization

4.1
RHEVM Shell Guide

Installing and Using the Command Line Shell for Red Hat Virtualization

Red Hat Virtualization Documentation Team

Red Hat Virtualization 4.1 RHEVM Shell Guide

Installing and Using the Command Line Shell for Red Hat Virtualization

Red Hat Virtualization Documentation Team

Red Hat Customer Content Services
[email protected]
Legal Notice
Copyright © 2017 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, OpenShift, 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 guide contains information for installing and using the Red Hat Virtualization Manager
Command Line Shell.
 Table of Contents

Table of Contents
.Chapter
. . . . . . .1.. .Using
. . . . . the
. . . .CLI
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . .
1.1. Installing the CLI 2
1.2. TLS/SSL Certification 2
1.3. .ovirtshellrc Configuration 4
1.4. Running the CLI 5
1.5. Interacting with the CLI 7
1.6. Collections 9

.Chapter
. . . . . . .2.. .Quick
. . . . . Start
. . . . .Example
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
...........
2.1. Creating a Basic Virtualization Environment with the CLI 10

.Chapter
. . . . . . .3.. .Commands
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
...........
3.1. Connecting to RHEVM 15
3.2. Resources 16
3.3. Other Commands 21

.Chapter
. . . . . . .4.. .Resource
. . . . . . . . .Types
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
...........
4.1. brick 27
4.2. cdrom 27
4.3. cluster 28
4.4. datacenter 30
4.5. disk 31
4.6. glustervolume 32
4.7. group 34
4.8. host 34
4.9. network 37
4.10. nic 38
4.11. permission 40
4.12. permit 41
4.13. quotas 42
4.14. role 42
4.15. snapshot 43
4.16. statistic 43
4.17. storageconnection 44
4.18. storagedomain 45
4.19. tag 48
4.20. template 48
4.21. user 54
4.22. vm 54
4.23. vmpool 60
4.24. vnicprofile 61

. . . . . . . .5.. .CLI
Chapter . . . Queries
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
...........
5.1. Query Syntax 63
5.2. Wildcards 63

1
RHEVM Shell Guide

Chapter 1. Using the CLI

The Red Hat Virtualization suite features a command line interface (CLI). This CLI provides users with a
means to connect to Red Hat 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.

Important

Version 4 of the Red Hat Virtualization Manager includes a build of version 3.6 of the CLI for Red Hat
Enterprise Linux 7. This version of the CLI uses version 3.6 of the Python SDK, and the version 3
compatibility mode of the REST API.

1.1. Installing the CLI

Install the Red Hat Virtualization CLI to a client machine:

1. Log into the client machine as the root user.

2. Register your system with the Content Delivery Network, entering your Customer Portal user name
and password when prompted:

# subscription-manager register

3. Find the Red Hat Virtualization subscription pool and note down the pool ID.

# subscription-manager list --available

4. Use the pool identifiers located in the previous step to attach the Red Hat Virtualization
entitlement to the system:

# subscription-manager attach --pool=pool_id

5. Enable the required repository:

# subscription-manager repos --enable=rhel-7-server-rhv-4.1-rpms

6. Install the CLI package and dependencies:

# yum install ovirt-engine-cli

1.2. TLS/SSL Certification

The Red Hat 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 Virtualization Manager and importing it into the certificate store of
your client.

2
 Chapter 1. Using the CLI

Important

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

Procedure 1.1. Obtaining a Certificate

You can obtain a certificate from the Red Hat 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.

a. If using cURL:

$ curl -o rhvm.cer http://[manager-fqdn]/ovirt-

engine/services/pki-resource?resource=ca-
certificate&format=X509-PEM-CA

b. If using Wget:

$ wget -O rhvm.cer http://[manager-fqdn]/ovirt-

engine/services/pki-resource?resource=ca-
certificate&format=X509-PEM-CA

2. Method 2 - Use a web browser to navigate to the certificate located at:

http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-
certificate&format=X509-PEM-CA

Depending on the chosen browser, the certificate either downloads or imports into the browser's
keystore.

a. If the browser downloads the certificate: save the file as rhvm.cer.

If the browser imports the certificate: export it from the browser's certification options and
save it as rhvm.cer.

3. Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to your client
machine.

a. Log in to the Manager as the root user.

b. Export the certificate from the truststore using the Java keytool management utility:

$ keytool -exportcert -keystore /etc/pki/ovirt-

engine/.truststore -alias cacert -storepass mypass -file rhvm.cer

This creates a certificate file called rhvm.cer.

c. Copy the certificate to the client machine using the scp command:

$ scp rhvm.cer [username]@[client-machine]:[directory]

3
RHEVM Shell Guide

Each of these methods results in a certificate file named rhvm.cer on your client machine. An API user
imports this file into the certificate store of the client.

Procedure 1.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.

1.3. .ovirtshellrc Configuration

The .ovirtshellrc file is a configuration file that is automatically created and populated when the user first
connects to the ovirt-shell. It allows users to configure options for connecting to the Red Hat
Virtualization environment. The .ovirtshellrc file is located by default in /home/[user
name]/.ovirtshellrc.

The configuration information of the .ovirtshellrc file falls under two section headings, [cli] and
[ovirt-shell]. These headings are necessary for the configuration file to be parsed.

Table 1.1. [cli] Parameters

Name Type Description

autoconnect boolean Toggles whether to automatically connect to an ovirt-shell session. The
status is either True or False.
autopage boolean Toggles pagination in the shell. The status is either True or False.

Table 1.2. [ovirt-shell] Parameters

Name Type Description

username string User name to be used to log in.
timeout integer Specifies timeout for requests. The default is -1.
extended_prompt boolean Toggles the extended prompt option, which displays the hostname in
the shell command prompt.
url string The address of the Red Hat Virtualization environment.
insecure boolean Toggles CA certificate requirement. The status is either True or
False.
renew_session boolean Toggles automatic renewal of the session upon expiration. 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.
session_timeout integer Specifies timeout (in minutes) for authentication session. Must be a
positive number.
ca_file string Specifies the server CA certificate to use.
dont_validate_ce boolean Toggles validation of server CA certificate. The status is either True or
rt_chain False.
key_file string Specifies client PEM key-file.
password string Password to be used for user name.
cert_file string Specifies client PEM cert-file.

1.4. Running the CLI

4
 Chapter 1. Using the CLI

1.4. Running the CLI

Start the CLI application with the following command:

# ovirt-shell

This ovirt-shell application is an interactive shell for Red Hat Virtualization environments.

The URL, user name, certificate authority file, and password for connecting to the Red Hat Virtualization
Manager can be configured in the .ovirtshellrc file. The ovirt-shell command uses the parameters
in this file to connect to the Manager, so that the user does not need to specify options each time.

Alternatively, users can connect automatically to Red Hat Virtualization Manager using the following
additional options.

# ovirt-shell -c -l "https://[server]/ovirt-engine/api" -P [port] -u

"[user@domain]" -A "[certificate]"

Ensure to replace the following values:

server - The hostname or IP Address of the Red Hat Virtualization Manager. The CLI connects to the Red
Hat Virtualization Manager via the REST API.

user@domain - The user name and directory service domain for the user logging into Red Hat
Virtualization Manager.

certificate - The path name of the Certificate Authority file.

The shell will prompt you for the password, and, if not already provided, the username and the URL for the
Red Hat Virtualization Manager.

Note

You do not need to specify additional options if you have configured your user name, password, URL,
and certificate authority file in the .ovirtshellrc file.

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 ovirt-shell

-h, --help

Show help for ovirt-shell.

-d, --debug

Enables debugging.

5
RHEVM Shell Guide

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

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

-E "command resource", --execute-command=" command resource"

Connects to the Manager to execute only the given commands, in the form of "command
resource;command resource" and prints the output to STDIO.

-f FILE, --file=FILE

Read commands from FILE instead of stdin.

--kerberos

Use a valid Kerberos ticket to authenticate connection to the shell.

6
 Chapter 1. Using the CLI

Note

Users with a non-interactive shell are able to connect to the Red Hat Virtualization Manager from
within the shell, where the --password option can be used.

1.5. Interacting with the CLI

The CLI is an interactive shell for controlling your Red Hat Virtualization environment from the command line.
Type the required command and any additional parameters.

Example 1.1. Entering a shell command

[RHEVM shell (connected)]# show vm RHEL6-Server

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 1.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 echo history remove
summary
action connect exit info shell
update
add console file list show
capabilities disconnect help ping status

Choose a command and press double TAB to view the next set of available parameters for the command.
For the add command, this lists all resources.

[RHEVM shell (connected)]# add TAB TAB

affinitygroup datacenter event group nic
quota label template vmpool cdrom
disk filter host permission role
storagedomain user cluster qos glustervolume
network permit snapshot tag vm

Double TAB also completes commands and parameters.

[RHEVM shell (connected)]# add vm TAB TAB

comment console-enabled cpu-architecture delete_protected
description disks-clone display-type io-threads
memory name os-type rng_device-source
stateless soundcard_enabled start_paused timezone
[RHEVM shell (connected)]# add vm naTAB TAB
[RHEVM shell (connected)]# add vm --name

7
RHEVM Shell Guide

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)]# add vTAB TAB

vmpool vm

The CLI provides functions to run Linux commands using either the shell command or the bang (!)
character.

Example 1.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 1.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 1.5. Using online help for the show command

[RHEVM shell (connected)]# help show

8
 Chapter 1. Using the CLI

You can also connect to the Manager from the Linux shell to execute specific commands, in the form of
"command resource" and print them to STDIO

Example 1.6. Connecting to the Manager to execute specific commands

Use the --execute or -E parameter to connect to the Manager to execute the specific commands.

# ovirt-shell -c -l "https://[server]/ovirt-engine/api" -P [port] -u

"[user@domain]" -A "[certificate]" -E "list vms;list hosts"
[RHEVM shell (connected)]# list vms

id : 9e6977f4-4351-4feb-bba0-dc7c22adec30
name : desktop-01

id : 60b12e28-7965-4296-86bf-c991aa32c2d5
name : server-01

[RHEVM shell (connected)]# list hosts

id : 3598cdb9-d21b-49bd-9491-59faff89b113
name : Gluster

id : a0c384f9-0940-4562-9c42-4ceaadf8f1f1
name : Host-01

id : 593ec966-c3ea-4bdc-84ad-5dc3f9fe64c7
name : Host-03

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

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

9
RHEVM Shell Guide

Chapter 2. Quick Start Example

2.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 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 Virtualization Manager;

An installation of the CLI on either the Red Hat 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 Virtualization Manager generates a globally unique identifier (GUID) for each resource.
Identifier codes in this example might appear different to the identifier codes in your Red Hat
Virtualization environment.

Procedure 2.1. Quick Start Example

1. Load the CLI shell and connect to your Red Hat Virtualization Manager.

# ovirt-shell -c --url https://[rhevm-host]/ovirt-engine/api --

username [user]@[domain] --ca-file certificate/authority/path/name

2. List all data centers in the environment. This example uses the Default data center.

[RHEVM shell (connected)]# list datacenters

id : 5e3b55d8-c585-11e1-a7df-001a4a400e0d
name : Default
description: The default Data Center

3. List all host clusters and note down the relevant cluster ID or cluster name, which will be required
when adding the host and for creating a virtual machine. This example uses the Default cluster to
group resources in your Red Hat Virtualization environment.

[RHEVM shell (connected)]# list clusters

id : 99408929-82cf-4dc7-a532-9d998063fa95
name : Default
description: The default server cluster

10
 Chapter 2. Quick Start Example

4. List all CPU profiles and note down the relevant CPU profile ID, which will be required when creating
a virtual machine. This example uses the Default CPU profile.

[RHEVM shell (connected)]# list cpuprofiles

id : 0000001a-001a-001a-001a-00000000035e
name : Default

5. List all logical networks with the show-all option to view the details of the logical networks in the
environment. Red Hat Virtualization Manager creates a default logical network called ovirtmgmt for
management traffic. This example uses the ovirtmgmt logical network on the Default data center.

[RHEVM shell (connected)]# list networks --show-all

id : 00000000-0000-0000-0000-000000000009
name : ovirtmgmt
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.

6. Add the Red Hat Enterprise Linux host to the virtualization environment as a new hypervisor. The
host is activated automatically.

[RHEVM shell (connected)]# add host --name MyHost --address

host.example.com --cluster-name Default --root_password p@55w0rd!

7. Add an NFS share as a data storage domain by creating, attaching, and activating the NFS share.
An NFS data storage domain is an exported NFS share attached to a data center. It provides storage
for virtual machines. Ensure to substitute storage-address and storage-path with the correct
values for the NFS server.

a. Create a data storage domain.

[RHEVM shell (connected)]# add storagedomain --host-name MyHost

--type data --storage-type nfs --storage_format v3 --storage-
address x.x.x.x --storage-path /exports/data --name DataStorage

b. Verify that the created storage domain is available. The creation process might take several
minutes. Once the status-state is unattached, you can proceed to the next step.

[RHEVM shell (connected)]# show storagedomain DataStorage

id : xxxx
name : DataStorage
master : False
status-state : unattached
...

11
RHEVM Shell Guide

c. Attach the data storage domain to the data center. The storage domain is activated
automatically.

[RHEVM shell (connected)] # add storagedomain --datacenter-

identifier Default --name DataStorage

Note

If the storage domain is not activated, activate it manually using the following
command:

[RHEVM shell (connected)]# action storagedomain DataStorage

--datacenter-identifier Default activate

8. Add an NFS share as the ISO storage domain by creating, attaching, and activating the NFS share.
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. Ensure to substitute storage-
address and storage-path with the correct values for the NFS server.

a. Create an ISO storage domain.

[RHEVM shell (connected)]# add storagedomain --host-name MyHost

--type iso --storage-type nfs --storage_format v3 --storage-
address x.x.x.x --storage-path /exports/iso --name ISOStorage

b. Verify that the created storage domain is available. The creation process might take a while.
Once the status-state is unattached, you can proceed to the next step.

[RHEVM shell (connected)]# show storagedomain --name ISOStorage

id : xxxx
name : ISOStorage
master : False
status-state : unattached
...

c. Attach the ISO storage domain to the data center. The storage domain is activated
automatically.

[RHEVM shell (connected)] # add storagedomain --datacenter-

identifier Default --name ISOStorage

9. Create a new virtual machine.

[RHEVM shell (connected)]# add vm --name MyVM --cluster-name Default -

-template-name Blank --memory 536870912 --os-boot boot.dev=hd --
cpu_profile-id 0000001a-001a-001a-001a-00000000035e

10. 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
ovirtmgmt network.

12
 Chapter 2. Quick Start Example

[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --

network-name ovirtmgmt --bootable true

11. 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 --
storage_domains-storage_domain storage_domain.name=DataStorage

12. On the Manager, upload ISO images to the ISOStorage domain for the virtual machines to use. Red
Hat Virtualization Manager provides an ISO uploader tool that ensures images are uploaded into the
correct directory path with the correct user permissions.

# engine-iso-uploader --iso-domain=ISOStorage upload rhel-server-6.6-

x86_64-dvd.iso
Please provide the REST API password for the admin@internal oVirt
Engine user (CTRL+D to abort):

13. In the CLI shell, use the list files command to list the available ISO files in the storage domain.

[RHEVM shell (connected)]# list files --storagedomain-identifier

ISOStorage

14. Add a virtual CD-ROM drive 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.6-x86_64-dvd.iso

15. Start the virtual machine. The virtual environment is complete and the virtual machine contains all
necessary components to function.

[RHEVM shell (connected)]# action vm MyVM start --vm-os-boot

boot.dev=cdrom

Note the use of the vm-os-boot 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.

16. Use the list events with an additional query option to display specific event types. The start
action for the virtual machine adds several entries in the events collection.

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

17. Use the show event command to display comprehensive details of an event. This command can be
used to show events by type, name, and id.

13
RHEVM Shell Guide

[RHEVM shell (connected)]# show event '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

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

14
 Chapter 3. Commands

Chapter 3. Commands

3.1. Connecting to RHEVM

3.1.1. Connect to RHEVM (connect)

The connect command connects to Red Hat Virtualization Manager. The URL, user name, certificate
authority file, and password for connecting to the Red Hat Virtualization Manager can be configured in the
.ovirtshellrc file. The connect command uses the parameters in this file to connect to the Manager, so
that the user does not need to specify options each time.

Syntax

connect [options]

Note

You do not need to specify additional options if you have configured your user name, password, URL,
and certificate authority file in the .ovirtshellrc file.

Table 3.1. Options for connect

Option Description Required

--url The URL to the Red Hat Virtualization Manager's REST API. This Yes
takes the form of https://[server]/ovirt-engine/api.
--username The user name and directory service domain of the user Yes
attempting access to the Red Hat Virtualization Manager. This
takes the form of [username]@[domain].
--password The password for the user attempting access to the Red Hat Yes
Virtualization Manager.
--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 Yes, but
option with caution because it can allow man-in-the-middle only if no
(MITM) attackers to spoof the identity of the server. 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 No
as part of the --url.
--timeout The timeout period for connection. No

Example 3.1. Example for connect when .ovirtshellrc is not configured

[RHEVM shell (disconnected)]# connect --url

"https://rhevm.example.com/ovirt-engine/api" --username

15
RHEVM Shell Guide

"[email protected]" --password "p@55w0rd!" --ca-file

"/home/user/ca.crt"

==========================================
>>> connected to RHEVM manager 4.0.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.

3.1.2. Disconnect from RHEVM (disconnect)

The disconnect command disconnects from Red Hat Virtualization Manager.

Syntax

disconnect

Example 3.2. Example for disconnect

[RHEVM shell (connected)]# disconnect

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

[RHEVM shell (disconnected)]#

3.2. Resources

3.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 3.2. list standard options

Option Description

16
 Chapter 3. Commands

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
Virtualization Manager query language.
--kwargs [QUERY] Filters the list using a client-side query.
--case_sensitive Match search queries using case sensitivity.
true|false
--max Maximum number of results for display.

Note

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

Example 3.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 virtual machines with a status of 'up':

[RHEVM shell (connected)]# list vms --query "status=up"

List users that match the specified user name across all domains with the use of a wildcard:

[RHEVM shell (connected)]# list users --query "usrname=jsmith@*" --

case_sensitive false

Get help with list search syntax:

[RHEVM shell (connected)]# list --help

3.2.2. Show a Resource (show)

Use the show command to display resource properties.

Syntax

show [resource] [id|name] [options]

17
RHEVM Shell Guide

Note

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

Example 3.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

3.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 3.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'

3.2.4. Update a Resource (update)

Use the update command to modify an existing resource.

Syntax

18
 Chapter 3. Commands

update [resource] [id|name] [options]

Note

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

Example 3.6. Examples for update

Update a virtual machine:

[RHEVM shell (connected)]# update vm RHEL6-Server [vm-options]

3.2.5. Remove a Resource (remove)

Use the remove command to remove a resource.

Syntax

remove [resource] [id|name] [options]

Table 3.3. 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 3.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

19
RHEVM Shell Guide

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

3.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 3.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]

20
 Chapter 3. Commands

Note the use of the --vm-identifier RHEL6-Server option. This adds a storage disk on the RHEL6-
Server virtual machine.

3.3. Other Commands

3.3.1. End of File (EOF)

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

Syntax

EOF

Example 3.10. Example for EOF

Leave the CLI shell:

[RHEVM shell (connected)]# EOF

3.3.2. List System Capabilities (capabilities)

Use the capabilties --features command to list all version capabilities and new features of the current
version.

Syntax

capabilities --features

Example 3.11. Example for capabilities

List system capabilities of the current version:

[RHEVM shell (connected)]# capabilities --features

name : Search - Case Sensitivity

description : Ability to specify whether a search
query should ignore case, by providing a URL parameter
url-parameters_set-parameter-name : case_sensitive
url-parameters_set-parameter-context: matrix
url-parameters_set-parameter-type : boolean
:

3.3.3. Clear the Screen (clear)

Use the clear command to clear the CLI screen.

Syntax

21
RHEVM Shell Guide

clear

Example 3.12. Example for clear

Clear the screen:

[RHEVM shell (connected)]# clear

3.3.4. 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 3.13. Example for console

Open graphical console to a virtual machines:

[RHEVM shell (connected)]# console RHEL6-Server

3.3.5. 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 3.14. Example for echo

Print input:

[RHEVM shell (connected)]# echo "Example text!"

Print last output:

[RHEVM shell (connected)]# echo $out

3.3.6. Exit from the CLI (exit)

Use the exit command to leave a CLI.

Syntax

22
 Chapter 3. Commands

exit

Example 3.15. Example for exit

Leave the CLI:

[RHEVM shell (connected)]# exit

3.3.7. 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 3.16. Example for file

Run a script file:

[RHEVM shell (connected)]# file /example/example-script

3.3.8. Show Help (help)

Use the help command displays help for CLI command and resource combinations.

Syntax

help [command] [resource] [options]

Example 3.17. 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

3.3.9. Display the User Command History (history)

23
RHEVM Shell Guide

Use the history command to display the history of user commands for the CLI shell.

Syntax

history

Example 3.18. Example for history

Display the user command history:

[RHEVM shell (connected)]# history

Example 3.19. Example for history --first

Display the first specified entries in the user command history with the --first n parameter:

[RHEVM shell (connected)]# history --first 5

Example 3.20. Example for history --last

Display the last specified entries in the user command history with the --last n parameter:

[RHEVM shell (connected)]# history --last 5

3.3.10. Show CLI Information (info)

Use the info command to display environment connection details and version information.

Syntax

info

Example 3.21. 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/ovirt-engine/api

3.3.11. Test Connection (ping)

24
 Chapter 3. Commands

Use the ping command tests the connection to your Red Hat Virtualization Manager. The command retrieves
a remote resource and ensures the URL, user name and password for the connection are correct.

Syntax

ping

Example 3.22. Example for ping

Test your connection:

[RHEVM shell (connected)]# ping

success: RHEVM manager could be reached OK.

3.3.12. 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 Virtualization Manager shell.

Syntax

shell [vm-id|vm-name]

Example 3.23. 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

3.3.13. Show Last Status (status)

25
RHEVM Shell Guide

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

Syntax

status

Example 3.24. Example for status

View the last status:

[RHEVM shell (connected)]# status

last command status: 0 (OK)

3.3.14. Show System Summary (summary)

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

Syntax

summary

Example 3.25. 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

26
 Chapter 4. Resource Types

Chapter 4. Resource Types

4.1. brick
The brick resource type groups all Gluster bricks in a Red Hat Virtualization environment.

Table 4.1. Gluster brick parameters

Name Type Description Requi User User

red Creat Updat
able able
--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
-- integer Defines the file replication count for a replicated No Yes No
replica_coun volume.
t
-- Intege Defines the stripe count for a striped volume No Yes No
stripe_count r

The following table lists additional glustervolume options for resource-based commands.

Table 4.2. Additional command options

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

Example 4.1. Creating a bricks

[RHEVM shell (connected)]# add brick --cluster-identifier Default --

glustervolume-identifier GlusterVol1 --server_id="server1" --
brick_dir="/exp1"

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

Table 4.3. CD-ROM parameters

Name Type Description Requi User User

red Creat Updat
able able
--file-id string Defines the file name of the ISO that resides on an Yes Yes Yes
ISO storage domain.

Example 4.2. Creating a new CD-ROM

27
RHEVM Shell Guide

[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-

server-6.2-x86_64-dvd.iso.iso

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

[RHEVM shell (connected)]# remove cdrom --vm-identifier MyVM rhel-server-

6.3-x86_64-dvd.iso.iso

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

Table 4.4. Cluster parameters

Name Type Description Requi User User

red Creat Updat
able able
--cpu-id string A server CPU reference that defines the CPU type all Yes Yes Yes
hosts must support in the cluster.
-- string A reference to the data center for a host cluster. Yes Yes No
data_center-
id|name
--name string The name of a host cluster. Yes Yes Yes
--version- int The major version number of the cluster. For Yes Yes Yes
major example, for Red Hat Virtualization 4.1, the major
version is 4.
--version- int The minor version number of the cluster. For Yes Yes Yes
minor example, for Red Hat Virtualization 4.1, the minor
version is 0.
-- string A description for the host cluster. No Yes Yes
description
-- string Defines virtual machine handling when a host within No Yes Yes
error_handli a cluster becomes non-operational, including
ng-on_error migrate, do_not_migrate and
migrate_highly_available.
-- Boolea The status is either true or false. No Yes Yes
gluster_serv n
ice

28
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
-- double The percentage of host memory allowed in use No Yes Yes
memory_polic before a host can no longer run any more virtual
y- machines. Virtual machines can use more than the
overcommit- available host memory due to memory sharing under
percent KSM. Recommended values include 100 (None),
150 (Server Load) and 200 (Desktop Load).
-- Boolea Defines the enabled status of Transparent No Yes Yes
memory_polic n Hugepages. The status is either true or false.
y-
transparent_
hugepages-
enabled
-- string The VM scheduling mode for hosts in the cluster, No Yes Yes
scheduling_p such as evenly_distributed, power_saving or
olicy-policy blank for none.
-- int The number of seconds the host can be overloaded No Yes Yes
scheduling_p before the scheduler starts and moves the load to
olicy- another host.
thresholds-
duration
-- int Controls the highest CPU usage percentage the host No Yes Yes
scheduling_p can have before being considered overloaded.
olicy-
thresholds-
high
-- int Controls the lowest CPU usage percentage the host No Yes Yes
scheduling_p can have before being considered underutilized.
olicy-
thresholds-
low
-- Boolea Hosts treat threads as cores, allowing hosts to run No No No
threads_as_c n virtual machines with a total number of processor
ores cores greater than the number of cores in the host.
The status is either true or false.
-- Boolea Defines whether an OpenAttestation server is used No Yes Yes
trusted_serv n to verify hosts.
ice
-- Boolea The status is either true or false. No Yes Yes
virt_service n
--expect '201- Request becomes asynchronous until the expected No No No
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.
-- string A tagging identifier of an action for cross-system No Yes No
correlation_ logging. If the client does not define the identifier,
id one will be generated.

Example 4.5. Creating a new cluster

29
RHEVM Shell Guide

[RHEVM shell (connected)]# add cluster --name Engineering --cpu-id "Intel

Penryn Family" --datacenter-name Default --version-major 3 --version-minor
2

Example 4.6. Updating a cluster

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

Example 4.7. Deleting a cluster

[RHEVM shell (connected)]# remove cluster Engineering

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

Table 4.5. Data Center Parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the data center. Yes Yes Yes
-- string The type of storage for the data center, including Yes Yes Yes
storage_type iscsi, fcp, nfs, localfs or posixfs.
--version- int The major version number of the data center. For Yes Yes Yes
major example, for Red Hat Virtualization 4.1, the major
version is 4.
--version- int The minor version number of the data center. For Yes Yes Yes
minor example, for Red Hat Virtualization 4.1, the minor
version is 0.
-- string A description for the data center. No Yes Yes
description
-- string The metadata format for the data center, including No Yes Yes
storage_form v1, v2 or v3.
at
--expect '201- Request becomes asynchronous until the expected No No No
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.
-- string A tagging identifier of an action for cross-system No Yes No
correlation_ logging. If the client does not define the identifier,
id one will be generated.

Example 4.8. Creating a new data center

[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs

--version-major 3 --version-minor 2

30
 Chapter 4. Resource Types

Example 4.9. Updating a data center

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

Example 4.10. Deleting a data center

[RHEVM shell (connected)]# remove datacenter Boston

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

Table 4.6. Disk parameters

Name Type Description Requi User User

red Creat Updat
able able
-- int The reserved storage space for the disk. This space Yes Yes Yes
provisioned_ is preallocated for the disk to use, even if the disk
size size is less than the provisioned_size
--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) Yes Yes Yes
allows snapshots, with a small performance
overhead. Raw (raw) does not allow snapshots, but
offers improved performance.
--size int The actual size of the disk. No Yes Yes
--sparse Boole true if the physical storage for the disk should not No Yes Yes
an be preallocated.
--bootable Boole true if this disk is to be marked as bootable. No Yes Yes
an
--shareable Boole true if this disk is shareable. No Yes Yes
an
-- Boole true if this disk allows snapshots. No Yes Yes
allow_snapsh an
ot
-- Boole true if disk errors should not cause virtual machine No Yes Yes
propagate_er an to be paused and, instead, disk errors should be
rors propagated to the guest OS.
-- boole true if the underlying physical storage for the disk No Yes Yes
wipe_after_d an should be zeroed when the disk is deleted. This
elete increases security but is a more intensive operation
and may prolong delete times.
-- collec Defines a specific storage domain for the disk. No Yes No
storage_doma tion
ins-
storage_doma
in

31
RHEVM Shell Guide

The --storage_domains-storage_domain parameter is a collection that uses the sub-parameters in the

following table.

Table 4.7. --storage_domains-storage_domain parameters

Name Type Description

storage_domain.i string A reference to a storage domain for the disk.
d|name

The following table lists additional disk options for resource-based commands.

Table 4.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 4.11. Creating a new disk

[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size

8589934592 --interface virtio --format cow

Example 4.12. Updating a storage domain

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

Example 4.13. Deleting a storage domain

[RHEVM shell (connected)]# remove disk MyDisk

The following table lists actions for a virtual disk resource.

Table 4.9. Virtual disk actions

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

4.6. glustervolume
The glustervolume resource type groups all Gluster storage volume resources in a Red Hat Virtualization
environment.

Table 4.10. Gluster volume parameters

32
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the Gluster volume. Yes Yes No
-- string Defines the Gluster volume type. Choose from Yes Yes No
volume_type DISTRIBUTE, REPLICATE,
DISTRIBUTED_REPLICATE, STRIPE or
DISTRIBUTED_STRIPE.
--bricks- collecti A new Gluster volume requires a set of Gluster bricks Yes Yes No
brick on 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.
-- collecti A reference to available transport methods for the No Yes No
transport_ty on Gluster volume. See below for collection details.
pes
-- integer Defines the file replication count for a replicated No Yes No
replica_coun volume.
t
-- Intege Defines the stripe count for a striped volume No Yes No
stripe_count r
--options- collecti A reference to options for the Gluster volume. See No Yes No
option on below for collection details.

The --bricks-brick parameter is a collection that uses the sub-parameters in the following table.

Table 4.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 4.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 4.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 4.14. Additional command options

33
RHEVM Shell Guide

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

Example 4.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 4.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 4.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.

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

Table 4.16. Group parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the group, usually the full group path No No No
within the identity directory service.

Example 4.16. Creating a group

[RHEVM shell (connected)]# add group --name

www.example.com/accounts/groups/mygroup --domain-name example.com

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

34
 Chapter 4. Resource Types

Table 4.17. Host parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the host. Yes Yes Yes
--address string The IP address or hostname for the host. Yes Yes Yes
-- string The password for the host's root user. Yes Yes Yes
root_passwor
d
--cluster- string Defines the cluster that includes the host. Yes Yes Yes
id|name
--port int The port for communication with the VDSM daemon No Yes Yes
running on the host.
-- int Sets the priority of host order for storage pool No Yes Yes
storage_mana manager (SPM).
ger-priority
-- string The type of power management device in the host. No Yes Yes
power_manage
ment-type
-- boolea Indicates whether power management configuration No Yes Yes
power_manage n is enabled or disabled.
ment-enabled
-- string The host name or IP address of the power No Yes Yes
power_manage management device.
ment-address
-- string A valid user name for power management. No Yes Yes
power_manage
ment-
user_name
-- string A valid, robust password for power management. No Yes Yes
power_manage
ment-
password
-- collecti Fencing options for the selected No Yes Yes
power_manage on power_management-type.
ment-
options-
option
-- boolea Defines if the host reboots after VDSM installation. No Yes No
reboot_after n
_installatio
n

The --power_management-options-option parameter is a collection that uses the sub-parameters in

the following table.

Table 4.18. --power_management-options-option parameters

Name Type Description

option.name string Power management option name.

35
RHEVM Shell Guide

Name Type Description

option.value string Power management option value.

Example 4.17. Creating a new host

[RHEVM shell (connected)]# add host --name Host1 --address

host1.example.com --root_password p@55w0rd! --cluster-name Default

Example 4.18. Updating a host

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

Example 4.19. Deleting a host

[RHEVM shell (connected)]# remove host Host1

The following table lists actions for a host resource.

Table 4.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 4.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.

Example 4.20. Confirming a host is rebooted

[RHEVM shell (connected)]# action host Host1 fence --fence_type manual

36
 Chapter 4. Resource Types

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

Table 4.21. Logical network parameters

Name Type Description Requi User User

red Creat Updat
able able
-- string A reference to the data center for a logical network. Yes Yes No
data_center-
id|name
--name string A plain text name for the logical network. Yes Yes No
-- string A description for the logical network. No Yes Yes
description
--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 boolea Signifies if a logical network is used for display No Yes Yes
n communication usage. Set to either true or false.
--stp boolea Set to true if Spanning Tree Protocol is enabled on No Yes Yes
n this network.
--mtu int Sets a user-defined value for the maximum No Yes Yes
transmission unit of the logical network.
--usages- collecti Defines usage parameters for the logical network. No No Yes
usage on

The --usages-usage parameter is a collection that uses the sub-parameters in the following table.

Table 4.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 4.23. Additional command options

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

Example 4.21. Creating a new network

[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name

Default

Example 4.22. Attaching an existing network to a cluster

37
RHEVM Shell Guide

[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name

Default --cluster-identifier Default

Example 4.23. Updating a network

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

Example 4.24. Deleting a network

[RHEVM shell (connected)]# remove network WebNetwork

4.10. nic

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

Name Type Description Requi User User

red Creat Updat
able able
--network- string A reference to the network, if any, that the interface Yes Yes Yes
id|name is attached.
--name string The name of the host network interface, e.g. eth0. Yes Yes Yes
--bonding- collec A collection of slave network interfaces that form a No Yes Yes
slaves- tion bonded interface.
host_nic
--bonding- collec A list of options for a bonded interface. Each option No Yes Yes
options- tion contains property name and value attributes.
option
--ip-gateway string The IP address for the network's gateway. No Yes Yes
-- string The protocol for IP address assignment when the No Yes Yes
boot_protoco host is booting, such as dhcp or static.
l
--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 4.25. Virtual Machine network interface parameters

38
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--network- string A reference to the network, if any, that the interface Yes Yes Yes
id|name is attached.
--name string The name of the interface, e.g. eth0. Yes Yes Yes
--mac- string The MAC address of the interface. No Yes Yes
address
--interface string Defines the interface type, such as e1000, virtio, No Yes Yes
rtl8139 and rtl8139_virtio.
-- collec Defines a set of networks to copy (mirror) network No Yes Yes
port_mirrori tion data from the network interface.
ng-networks-
network

The --bonding-slaves-host_nic parameter is a collection that uses the sub-parameters in the following
table.

Table 4.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 4.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 4.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 4.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 4.25. Creating a new network interface on a virtual machine

39
RHEVM Shell Guide

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

network-name MyNetwork

Example 4.26. Updating a network interface on a virtual machine

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

address 10.5.68.123

Example 4.27. Deleting a network interface on a virtual machine

[RHEVM shell (connected)]# remove nic eth0 --vm-identifier MyVM1

Example 4.28. Configuring network bonding on a host

[RHEVM shell (connected)]# add nic --host-identifier MyHost1 --name bond1

--network-name MyNetwork --bonding-slaves-host_nic host_nic.name=eth0 --
bonding-slaves-host_nic host_nic.name=eth1

Example 4.29. Assigning a logical network to a host network interface

[RHEVM shell (connected)]# action nic eth0 attach --host-identifier

MyHost1 --network-name MyNetwork

The following table lists actions for a host NIC resource.

Table 4.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 4.31. Virtual machine NIC actions

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

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

Table 4.32. Permission parameters

40
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--user-id, -- string A reference to the user or group using the Yes Yes No
group-id permission.
--role-id string A reference to a role to assign for the permission. Yes Yes No
--expect '201- Request becomes asynchronous until the expected No No No
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.

The following table lists additional permission options for resource-based commands.

Table 4.33. Additional command options

Option Description
--cluster-identifier Adds the permission to a cluster.
--correlation-id A tagging identifier for cross-system logging.
--cpuprofile-identifier Adds the permission to a CPU profile.
--datacenter-identifier Adds the permission to a data center.
--disk-identifier Adds the permission to a disk.
--diskprofile-identifier Adds the permission to a disk profile.
--host-identifier Adds the permission to a host.
--iscsibond-identifier Adds the permission to an iSCSI bond.
--network-identifier Adds the permission to a network.
--storagedomain- Adds the permission to a storage domain.
identifier
--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 4.30. Creating a new permission

[RHEVM shell (connected)]# add permission --role-id 00000000-0000-0000-

0000-000000000001 --user-id 8b9456ae-e2c8-426e-922d-b01bb8a805fb

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

Table 4.34. Permission parameters

Name Type Description Requi User User

red Creat Updat
able able
--id string A reference to the permit to add. Yes Yes No

41
RHEVM Shell Guide

The following table lists additional permit options for resource-based commands.

Table 4.35. Additional command options

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

Example 4.31. Creating a new permission

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

4.13. quotas
The quota resource type groups all datacenter quotas in a Red Hat Virtualization environment.

Table 4.36. Quota parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the quota. Yes Yes Yes
-- string A description for the quota. Yes Yes Yes
description

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

Table 4.37. Role parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the role. Yes Yes Yes
--permits- collecti A list of permits for initial inclusion with the role. Yes Yes No
permit on Additional permits included with the permit resource
type.
-- string A description for the role. No Yes Yes
description
-- Boolea Set to true if this is an administrative role. No Yes Yes
administrati n
ve

The --permits-permit parameter is a collection that uses the sub-parameters in the following table.

Table 4.38. --permits-permit parameters

Name Type Description

permit.id string A reference to a permit to add to the role's permits.

42
 Chapter 4. Resource Types

Example 4.32. Creating a new role

[RHEVM shell (connected)]# add role --name MyRole --permits-permit

{permit.id: 1;},{permit.id: 2;)

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

Table 4.39. Snapshot parameters

Name Type Description Requi User User

red Creat Updat
able able
-- string A description for the snapshot. Yes Yes No
description

The following table lists additional snapshot options for resource-based commands.

Table 4.40. Additional command options

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

Example 4.33. Creating a new snapshot

[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description

'My Snapshot'

Example 4.34. Deleting a storage domain

[RHEVM shell (connected)]# remove snapshot [snapshot_id]

The following table lists actions for a virtual machine snapshot resource.

Table 4.41. Virtual machine snapshot actions

Action Description
restore Restore a snapshot.

4.16. statistic
The statistic resource type groups statistics for resources in a Red Hat Virtualization environment.
Resource statistics are listed based on their resource identifier.

43
RHEVM Shell Guide

Table 4.42. statistic resource identifiers

Option Description
--brick-identifier The resource identifier to view statistics for the specified brick.
--cluster-identifier The resource identifier to view statistics for the specified cluster.
--datacenter-identifier The resource identifier to view statistics for the specified data center.
--disk-identifier The resource identifier to view statistics for the specified virtual disk.
--glustervolume- The resource identifier to view statistics for the specified gluster
identifier volume.
--host-identifier The resource identifier to view statistics for the specified host.
--job-identifier The resource identifier to view statistics for the specified job.
--nic-identifier The resource identifier to view statistics for the specified NIC.
--numanode-identifier The resource identifier to view statistics for the specified NUMA node.
--step-identifier The resource identifier to view statistics for the specified step.
--storagedomain- The resource identifier to view statistics for the specified storage
identifier domain.
--vm-identifier The resource identifier to view statistics for the specified virtual
machine.

View the collection of statistics for each resource by using the list command and the relevant resource
identifier. The following example provides a list of the available statistics for the specified host:

[RHEVM shell (connected)]# list statistics --host-identifier Host_name|id

The name or id of the provided statistics can be used with the show command and the resource identifier to
view further information on the specified statistic. The following example shows the details of the specified
statistic for the host:

[RHEVM shell (connected)]# show statistic statistic_name|id --host-

identifier Host name|id

4.17. storageconnection

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

Table 4.43. Storage connection parameters

Name Type Description Requi User User

red Creat Updat
able able
--address string The hostname or IP address of the storage domain. Yes Yes Yes
(NFS
and
iSCSI
only)
-- string A tagging identifier for the storage connection. No No Yes
correlation_
id

44
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--expect '201- Request becomes asynchronous until the expected No No No
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.
--iqn string The target IQN for the storage device. Yes Yes Yes
(iSCSI
only)
-- string The options for mounting the PosixFS share. No Yes Yes
mount_option
s
-- integer The number of retransmissions the NFS client will No Yes Yes
nfs_retrans attempt to complete a request.
--nfs_timeo integer The amount of time, in deciseconds, the NFS client No Yes Yes
will wait for a request to complete.
-- string The version of NFS used. No Yes Yes
nfs_version
--password string A CHAP password for logging into a target of an No Yes Yes
iSCSI storage domain.
--path string The mounted file path of the storage domain. The Yes Yes Yes
path cannot be updated to one already used by a (NFS,
storage connection. local,
and
Posix
FS
only)
--port integer The TCP port used for the iSCSI storage domain. Yes Yes Yes
(iSCSI
only)
-- string A reference to a storage domain for the disk. No No No
storagedomai
n-identifier
--type string The type of storage domain. Yes Yes No
--username string A CHAP user name for logging into a target of an No Yes Yes
iSCSI storage domain.
--vfs_type string The Linux-supported file system type of the PosixFS Yes Yes Yes
share. (Posix
FS
only)

Example 4.35. Creating a new storage connection

[RHEVM shell (connected)]# add storageconnection --address

storage.example.com --path /storage/nfs --type nfs

4.18. storagedomain

45
RHEVM Shell Guide

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

Table 4.44. Storage domain parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the storage domain. No Yes Yes
--format Boolea The metadata format for the data center, including Yes Yes No
n v1, v2 or v3.
--host- string A reference to the host from which this storage Yes Yes No
id|name domain should be initialized. The only restriction on
this host is that it should have access to the physical
storage specified.
--storage- string The IP address or hostname of the storage device. Yes Yes No
address
--storage- collecti The logical unit information of the storage device. See Yes No
logical_unit on below
--storage- string The options for mounting the storage domain. See Yes No
mount_option below
s
--storage- Boolea Defines whether to override the logical unit number. See Yes No
override_lun n The status is either true or false. below
s
--storage- string The path on the storage device to use for the storage See Yes No
path domain. below
--storage- string The type of storage for the data center, including Yes Yes No
type iscsi, fcp, nfs, glusterfs, localfs or
posixfs.
--storage- string Defines the file system type of the storage domain. See Yes No
vfs_type below
--type string The type of storage domain, including data, iso Yes Yes No
and export.

The --storage-logical_unit parameter is a collection that requires all sub-parameters in the following
table.

Table 4.45. storage-logical_unit parameters

Name Type Description

logical_unit.add string The address of the server containing the storage device.
ress
logical_unit.por integer The port number of the server.
t
logical_unit.tar string The target IQN for the storage device.
get
logical_unit.use string A CHAP user name for logging into a target.
rname
logical_unit.pas string A CHAP password for logging into a target.
sword

46
 Chapter 4. Resource Types

Name Type Description

logical_unit.ser string The serial ID for the target.
ial
logical_unit.ven string The vendor name for the target.
dor_id
logical_unit.pro string The product code for the target.
duct_id
logical_unit.lun integer The Logical Unit Number device mapping for the target.
_mapping
logical_unit.por string The logical unit portal.
tal
logical_unit.pat integer The logical unit paths.
hs
logical_unit.id string A reference to the logical unit ID.

Use the following parameters depending on storage-type.

Table 4.46. Storage type parameters

Type Parameters
nfs --storage-address, --storage-path
iscsi or fcp --storage-address, --storage-logical_unit, --storage-
override_luns
glusterfs --storage-address, --storage-path, --storage-vfs_type
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 4.47. Additional command options

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

Example 4.36. Creating a new storage domain

[RHEVM shell (connected)]# add storagedomain --name DataStorage --

datacenter-name Default -type data

Example 4.37. Adding a gluster storage domain

[RHEVM shell (connected)]# add storagedomain --type data --storage-type

glusterfs --name RHS_01 --storage-address 192.0.2.0 --storage-path Vol_ONE
--storage-vfs_type glusterfs

Example 4.38. Updating a storage domain

47
RHEVM Shell Guide

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

DataStorageOld

Example 4.39. Deleting a storage domain

[RHEVM shell (connected)]# remove storagedomain DataStorage

The following table lists actions for a storage domain resource.

Table 4.48. Storage domain actions

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

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

Table 4.49. Tag parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the tag. Yes Yes Yes
-- string A description for the string. Yes Yes Yes
description
--parent- string A reference to the parent tag that the tag is attached. Yes Yes Yes
name

Example 4.40. Creating a new tag

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

4.20. template

The template resource type groups all virtual machine templates in a Red Hat Virtualization environment.
Only --vm-id|name and --name are required parameters. If the optional parameters are not specified, the
template will inherit the settings from the virtual machine used to make the template.

Table 4.50. Template parameters

48
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--vm-id|name string A reference to the virtual machine used as the basis Yes Yes No
for the template.
--name string The name of the virtual machine template. Yes Yes Yes
--memory long The amount of memory for the virtual machine No Yes Yes
template in bytes.
--cpu- int The number of CPU cores available to the virtual No Yes Yes
topology- machine template.
cores
-- Boolea Set to true to enable high availability for the virtual No Yes Yes
high_availab n machine template.
ility-
enabled
--os-cmdline string A kernel command line parameter string to be used No Yes Yes
with the defined kernel. This option supports booting
a Linux kernel directly rather than through the BIOS
bootloader.
--origin string The virtual machine template's origin. Specify rhev, No Yes Yes
vmware, or xen.
-- int Sets the priority value (i.e. boot order) of each virtual No Yes Yes
high_availab machine template's high availability.
ility-
priority
--timezone string The Sysprep timezone setting for a Windows virtual No Yes Yes
machine template. Specify formats such as
GMT+00:00.
--domain- string The domain name of the virtual machine template. No Yes Yes
name
--type string Defines the virtual machine type. Specify either No Yes Yes
desktop or server.
--stateless boolea Set to true if the resulting virtual machines are No Yes Yes
n 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.
-- boolea Set to true to make it impossible to delete a virtual No Yes Yes
delete_prote n machine created from this template.
cted
--sso- collecti Defines the single sign-on method used. For No Yes Yes
methods- on example, --sso-methods-method
method method.id=GUEST_AGENT.
-- int Specifies how many bytes are permitted to be No Yes Yes
rng_device- consumed per period.
rate-bytes
-- int Specifies the duration of a period in milliseconds. If No Yes Yes
rng_device- specified, --rng_device-rate-bytes must be
rate-period specified as well.

49
RHEVM Shell Guide

Name Type Description Requi User User

red Creat Updat
able able
-- string The source of the random number generator. Specify No Yes Yes
rng_device- either random or hwrng.
source
--console- boolea Set to true to enable the VirtIO console device No Yes Yes
enabled n feature.
-- string The migration affinity for each virtual machine No Yes Yes
placement_po created from the template. Specify migratable,
licy- user_migratable, or pinned.
affinity
-- string A description for the virtual machine template. No Yes Yes
description
--comment string A comment for the virtual machine template. No Yes Yes
-- collecti A set of user-defined environment variables passed No Yes Yes
custom_prope on as parameters to custom scripts.
rties-
custom_prope
rty
--os-type string The operating system type for the virtual machine No Yes Yes
template.
--os-boot collecti The boot device for the virtual machine template. No Yes Yes
on Specify cdrom, hd, or network. For example, --
os-boot boot.dev=hd.
--cpu- int The number of CPU sockets available to the virtual No Yes Yes
topology- machine template.
sockets
--cpu_shares int The level of CPU resources a virtual machine can No Yes Yes
demand relative to other virtual machines. For
example, 512 for low priority virtual machines, 1024
for medium priority virtual machines, and 2048 for
high priority virtual machines.
--cpu- string Defines the CPU architecture. Specify x86_64, No Yes Yes
architecture ppc64, or undefined.
--os-kernel string A path to a kernel image the resulting virtual No Yes Yes
machines are configured to boot. This option
supports booting a Linux kernel directly rather than
through the BIOS bootloader.
--display- string Defines the display type. Specify either spice or No Yes Yes
type vnc.
--display- int Defines the number of displays available. No Yes Yes
monitors
--display- boolea Set to true to drive multiple monitors using a single No Yes Yes
single_qxl_p n virtual PCI device.
ci
--display- boolea Set to true to allow override of the template console No Yes Yes
allow_overri n settings.
de

50
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--display- boolea Set to true to enable the Smart card feature for No Yes Yes
smartcard_en n virtual machines.
abled
--display- boolea Set to true to enable SPICE file transfer. No Yes Yes
file_transfe n
r_enabled
--display- boolea Set to true to enable SPICE clipboard copy and No Yes Yes
copy_paste_e n paste.
nabled
--display- string Defines the keyboard layout for the virtual machine. No Yes Yes
keyboard_lay This option is only available when using the VNC
out protocol. Specify formats such as en-US.
--os-initRd string A path to an initrd image to be used with a specified No Yes Yes
kernel. This option supports booting a Linux kernel
directly rather than through the BIOS bootloader.
--usb- Boolea Set to true to enable USB support on the virtual No Yes Yes
enabled n machine. This option is only available for virtual
machines using the SPICE protocol.
--usb-type string Defines the USB type if USB support is enabled. No Yes Yes
Specify either Legacy or Native.

Important

The Legacy USB option has been deprecated

and will be removed in Red Hat Virtualization
4.1.

-- boolea Set to true to enable data transport over a libvirt No Yes Yes
tunnel_migra n daemon. A tunneled transport uses a stronger
tion encryption algorithm but increases the data load
during transport.
-- int Defines the maximum number of milliseconds that No Yes Yes
migration_do the virtual machine can be down during live
wntime migration.
-- boolea Set to true to allow attaching a VirtIO console No Yes Yes
virtio_scsi- n device to the virtual machine.
enabled
-- boolea Set to true to enable sound cards. No Yes Yes
soundcard_en n
abled:
--vm-disks- collecti References to disks attached to the template. No Yes No
disk on
--id string The ID of the virtual machine template. No Yes Yes
-- boolea Set to true to copy the permissions of the source No Yes Yes
permissions- n virtual machine to the template.
clone

51
RHEVM Shell Guide

Name Type Description Requi User User

red Creat Updat
able able
--version- string Used with the --version-base_template-id No Yes Yes
version_name parameter. Defines the name for the sub template.
--version- string Defines the template ID to be used as the root No Yes Yes
base_templat template. Used if you want to create this template as
e-id a sub template of a root template.
--cpu- collecti Defines which virtual CPUs of a virtual machine to No Yes Yes
cpu_tune- on pin to the physical CPUs of a host.
vcpu_pin
-- string Defines the serial number policy for the virtual No Yes Yes
serial_numbe machine template. Specify host, vm, or custom. If
r-policy custom is used, also define the serial number value
using --serial_number-value.
-- string Defines the serial number for the virtual machine No Yes Yes
serial_numbe template.
r-value
--bios- boolea Set to true to enable boot menu. No Yes Yes
boot_menu- n
enabled
--cluster-id string Defines the cluster to use by specifying the cluster No Yes Yes
ID.
--cluster- string Defines the cluster to use by specifying the cluster No Yes Yes
name name.
-- string Defines the CPU profile to use. Use the list No Yes Yes
cpu_profile- cpuprofiles command to retrieve a full list of CPU
id profile IDs.
--expect '201- Request becomes asynchronous until the expected No Yes Yes
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.
-- string A tagging identifier of an action for cross-system No Yes Yes
correlation_ logging. If the client does not define the identifier,
id one will be generated.

The --sso-methods-method parameter is a collection that uses the sub-parameters in the following table.

Table 4.51. --sso-methods-method parameters

Name Type Description

method.id string The single sign-on method used: GUEST_AGENT.

The --custom_properties-custom_property parameter is a collection that uses the sub-parameters

in the following table.

Table 4.52. --custom_properties-custom_property parameters

Name Type Description

custom_property. string The custom property name.
name

52
 Chapter 4. Resource Types

Name Type Description

custom_property. string The custom property value.
value

The --os-boot parameter is a collection that uses the sub-parameters in the following table.

Table 4.53. --os-boot parameters

Name Type Description

boot.dev string The boot device for the virtual machine template. Specify cdrom, hd,
or network.

The --vm-disks-disk parameter is a collection that uses the sub-parameters in the following table.

Table 4.54. --vm-disks-disk parameters

Name Type Description

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

The --cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in the following
table.

Table 4.55. --cpu-cpu_tune-vcpu_pin parameters

Name Type Description

vcpu_pin.vcpu int The virtual CPU to assign.
vcpu_pin.cpu_set string The physical CPUs on the host.

Example 4.41. Creating a new template

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

Example 4.42. Updating a template

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

Example 4.43. Deleting a template

[RHEVM shell (connected)]# remove template MyTemplate1

The following table lists actions for a virtual machine template resource.

Table 4.56. Virtual machine template actions

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

53
RHEVM Shell Guide

Action Description

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

Table 4.57. User parameters

Name Type Description Requi User User

red Creat Updat
able able
--user_name string The user name from the directory service. Yes Yes No
--domain- string A reference to the directory service domain. Yes Yes No
id|name

Example 4.44. Creating a new user

[RHEVM shell (connected)]# add user --user_name jsmith --domain-name

example.com

4.22. vm

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

Table 4.58. Virtual machine parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the virtual machine Yes Yes Yes
-- string A reference to the template used as the basis Yes Yes No
template- for the virtual machine.
id|name
--cluster- string A reference to the cluster that includes this VM. Yes Yes Yes
id|name
-- string Defines the instance type. Specify custom, No Yes Yes
instance_t large, medium, small, tiny, or xlarge.
ype-
id|name
--quota-id string A reference to the quota usage for the virtual No Yes No
machine.
--timezone string The Sysprep time zone setting for a Windows No Yes Yes
virtual machine.
--os-boot collection The boot device for the virtual machine. Specify No Yes Yes
cdrom, hd, or network.

54
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
-- collection A set of user-defined environment variables No Yes Yes
custom_pro passed as parameters to custom scripts.
perties-
custom_pro
perty
--os-type string The operating system type for this virtual No Yes Yes
machine.
--usb- boolean Defines the USB policy for a virtual machine. No Yes Yes
enabled Set to true to enable USB on the virtual
machine.
--usb-type string Defines the USB type if enabled. No Yes Yes
--type string Defines the virtual machine type. Specify either No Yes Yes
desktop or server.
--os- string A path to an initrd image to be used with a No Yes Yes
initRd specified kernel. This option supports booting a
Linux kernel directly rather than through the
BIOS bootloader.
--display- int Defines the number of displays available. No Yes Yes
monitors
--display- boolean Set to true to drive multiple monitors using a No Yes Yes
single_qxl single virtual PCI device.
_pci
--display- string Defines the display type. Specify either spice No Yes Yes
type or vnc.
--display- boolean Set to true to allow override of the virtual No Yes Yes
allow_over machine console settings.
ride
--display- boolean Set to true to enable the Smart card feature. No Yes Yes
smartcard_
enabled
--display- boolean Set to true to enable SPICE file transfer. No Yes Yes
file_trans
fer_enable
d
--display- boolean Set to true to enable SPICE clipboard copy No Yes Yes
copy_paste and paste.
_enabled
--display- string Defines the keyboard layout for the virtual No Yes Yes
keyboard_l machine. This option is only available when
ayout using the VNC protocol. Specify formats such
as en-US.
--os- string A kernel command line parameter string to be No Yes Yes
cmdline used with the defined kernel. This option
supports booting a Linux kernel directly rather
than through the BIOS bootloader.
--cpu- int The number of CPU cores available to the No Yes Yes
topology- virtual machine.
cores

55
RHEVM Shell Guide

Name Type Description Requi User User

red Creat Updat
able able
--cpu- string Defines the CPU architecture. Specify x86_64, No Yes Yes
architectu ppc64, or undefined.
re
--memory long The amount of memory for the virtual machine No Yes Yes
in bytes.
-- long The minimum amount of memory, in bytes, No Yes Yes
memory_pol guaranteed on a host in order for the virtual
icy- machine to run.
guaranteed
-- boolean Set to true to enable memory balloon device. No Yes Yes
memory_pol
icy-
ballooning
-- int Sets the priority value (migration and restart No Yes Yes
high_avail order) of each virtual machine using high
ability- availability.
priority
-- boolean Defines whether high availability is enabled for No Yes Yes
high_avail the virtual machine.
ability-
enabled
--domain- string The domain name of the virtual machine. No Yes Yes
name
-- string A description of the virtual machine. No Yes Yes
descriptio
n
--comment string A comment for the virtual machine. No Yes Yes
-- boolean Set to true if the virtual machine is stateless. A No Yes Yes
stateless 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.
-- boolean Set to true to copy the permissions of the No Yes Yes
permission source virtual machine to the template.
s-clone
-- boolean Set to true to make it impossible to delete a No Yes Yes
delete_pro virtual machine created from this template.
tected
--sso- collection Defines the single sign-on method used. For No Yes Yes
methods- example, --sso-methods-method
method method.id=GUEST_AGENT.
-- int Specifies how many bytes are permitted to be No Yes Yes
rng_device consumed per period.
-rate-
bytes

56
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
-- int Specifies the duration of a period in No Yes Yes
rng_device milliseconds. If specified, --rng_device-
-rate- rate-bytes must be specified as well.
period
-- string The source of the random number generator. No Yes Yes
rng_device Specify either random or hwrng.
-source
--console- boolean Set to true to enable the VirtIO console device No Yes Yes
enabled feature.
--cpu-mode string Defines the CPU mode. Specify custom, No Yes Yes
host_model, or host_passthrough.
--cpu- int The number of CPU sockets available to the No Yes Yes
topology- virtual machine.
sockets
-- int The level of CPU resources a virtual machine No Yes Yes
cpu_shares can demand relative to other virtual machines.
For example, 512 for low priority virtual
machines, 1024 for medium priority virtual
machines, and 2048 for high priority virtual
machines.
-- string The migration affinity for each virtual machine. No Yes Yes
placement_ Specify migratable, user_migratable, or
policy- pinned.
affinity
-- string A reference to the preferred host for migration No Yes Yes
placement_ affinity.
policy-
host-
id|name
--origin string The virtual machine's origin. Specify rhev, No Yes Yes
vmware, or xen.
--os- string A path to a kernel image the virtual machine is No Yes Yes
kernel configured to boot. This option supports booting
a Linux kernel directly rather than through the
BIOS bootloader.
--disks- boolean Defines whether to clone the disk from the No Yes No
clone defined template.
--disks- collection References to disks attached to the virtual No Yes Yes
disk machine.
-- boolean Set to true to enable data transport over a No Yes Yes
tunnel_mig libvirt daemon. A tunneled transport uses a
ration stronger encryption algorithm but increases the
data load during transport.
-- int Defines the maximum number of milliseconds No Yes Yes
migration_ that the virtual machine can be down during live
downtime migration.

57
RHEVM Shell Guide

Name Type Description Requi User User

red Creat Updat
able able
-- boolean Set to true to allow attaching a VirtIO console No Yes Yes
virtio_scs device to the virtual machine.
i-enabled
-- boolean Set to true to enable sound cards. No Yes Yes
soundcard_
enabled:
-- collection Defines content to send to the virtual machine No Yes Yes
payloads- upon booting.
payload
-- string Defines the virtual machine format. Accepts only No Yes Yes
initializa ovf.
tion-
configurat
ion-type
-- string This parameter must match the -- No Yes Yes
initializa initialization-configuration-type
tion- parameter. Accepts only ovf.
configurat
ion-data
--cpu- collection Defines which virtual CPUs of a virtual machine No Yes Yes
cpu_tune- to pin to the physical CPUs of a host.
vcpu_pin
-- string Defines the serial number policy for the virtual No Yes Yes
serial_num machine template. Specify host, vm, or
ber-policy custom. If custom is used, also define the
serial number value using --serial_number-
value.
-- string Defines the serial number for the virtual No Yes Yes
serial_num machine template.
ber-value
--bios- boolean Set to true to enable boot menu. No Yes Yes
boot_menu-
enabled
-- string Defines how to allocate memory for the domain No Yes Yes
numa_tune_ process on a NUMA host. Specify
mode interleave, strict, or preferred. If no
value is given, the parameter defaults to
strict.
-- string Defines the CPU profile to use. Use the list No Yes Yes
cpu_profil cpuprofiles command to retrieve a full list of
e-id CPU profile IDs.
--expect '201-created' Request becomes asynchronous until the No No No
expected HTTP header is returned. Useful for
long-running tasks that would otherwise return
as successful before the task is completed.
-- string A tagging identifier of an action for cross-system No Yes No
correlatio logging. If the client does not define the
n_id identifier, one will be generated.

58
 Chapter 4. Resource Types

The --os-boot parameter is a collection that uses the sub-parameters in the following table.

Table 4.59. --os-boot parameters

Name Type Description

boot.dev string The boot device for the virtual machine template. Specify cdrom, hd,
or network.

The --custom_properties-custom_property parameter is a collection that uses the sub-parameters

in the following table.

Table 4.60. --custom_properties-custom_property parameters

Name Type Description

custom_property. string The custom property name.
name
custom_property. string The custom property value.
value

The --sso-methods-method parameter is a collection that uses the sub-parameters in the following table.

Table 4.61. --sso-methods-method parameters

Name Type Description

method.id string The single sign-on method used: GUEST_AGENT.

The --disks-disk parameter is a collection that uses the sub-parameters in the following table.

Table 4.62. --disks-disk parameters

Name Type Description

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

The --payloads-payload parameter is a collection that uses the sub-parameters in the following table.

Table 4.63. --payloads-payload parameters

Name Type Description

payload.type string Payload delivery type. Specify either cdrom or floppy.
payload.file.nam string The payload file name and location on the root file system of the virtual
e machine.
payload.file.con string The content to deliver to the file.
tent

The --cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in the following
table.

Table 4.64. --cpu-cpu_tune-vcpu_pin

59
RHEVM Shell Guide

Name Type Description

vcpu_pin.vcpu int The virtual CPU to assign.
vcpu_pin.cpu_set string The physical CPUs on the host.

Example 4.45. Creating a new virtual machine

[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --

cluster-name Default --memory 536870912

Example 4.46. Updating a virtual machine

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

Example 4.47. Deleting a virtual machine

[RHEVM shell (connected)]# remove vm MyVM

The following table lists actions for a virtual machine resource.

Table 4.65. Virtual machine actions

Action Description
start Launch a virtual machine.
stop Stop a virtual machine.
shutdown Shut down a virtual machine.
suspend Suspend a virtual machine.
detach Detach a virtual machine from a pool.
migrate Migrate a virtual machine to another host.
cancelmigration Stop migration in progress.
export Export a virtual machine to an export storage domain.
move Move virtual disks to another storage domain.
ticket Create a ticket for console access.
logon Enable user logon for console access using third-party applications.

4.23. vmpool

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

Table 4.66. Virtual machine pool parameters

Name Type Description Requi User User

red Creat Updat
able able
--cluster- string A reference to the cluster for the virtual machine Yes Yes Yes
id|name pool.

60
 Chapter 4. Resource Types

Name Type Description Requi User User

red Creat Updat
able able
--template- string A reference to the template for the virtual machine Yes Yes Yes
id|name pool.
--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 4.48. Creating a new virtual machine pool

[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-

name MyTemplate --name MyPool --size 3

Example 4.49. Updating a virtual machine pool

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

Example 4.50. Deleting a virtual machine pool

[RHEVM shell (connected)]# remove vmpool MyPool

4.24. 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 Virtualization environment.

Table 4.67. Virtual Network Interface Controller Profile Parameters

Name Type Description Requi User User

red Creat Updat
able able
--name string The name of the VNIC profile. Yes Yes Yes
--network-id string A reference to the logical network to which the profile Yes No No
will be applied.
-- string A tagging identifier of an action for cross-system No Yes No
correlation_ logging. If the client does not define the identifier,
id one will be generated.
-- string A description for the profile. No Yes Yes
description
--expect '201- Request becomes asynchronous until the expected No No No
create HTTP header is returned. Useful for long-running
d' tasks that would otherwise return as successful
before the task is completed.

61
RHEVM Shell Guide

Name Type Description Requi User User

red Creat Updat
able able
-- collecti A set of user-defined environment variables passed No Yes Yes
custom_prope on as parameters to custom scripts.
rties-
custom_prope
rty
-- Boolea Toggles whether port mirroring is used for the profile. No No No
port_mirrori n The status is either True or False. Default is
ng Falses

The --custom_properties-custom_property parameter is a collection that uses the sub-parameters

in the following table.

Table 4.68. --custom_properties-custom_property parameters

Name Type Description

custom_property. string The custom property name.
name
custom_property. string The custom property value.
value

Example 4.51. Creating a new vnic profile

[RHEVM shell (connected)]# add vnicprofile --name Gold --network-id

08305a2f-6952-4999-9646-c16137dc6d42

Example 4.52. Updating a vnic profile

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

Example 4.53. Deleting a vnic profile

[RHEVM shell (connected)]# remove vnicprofile Gold

62
 Chapter 5. CLI Queries

Chapter 5. CLI Queries

5.1. Query Syntax

The CLI list command uses the --query attribute to perform server-side queries, which uses the same
format as Red Hat Virtualization Manager search query language:

Table 5.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 Displays the list of all events
time with severity higher than normal
and sorted by the time element
values.
events severity>normal sortby Displays the list of all events
time desc with severity higher than normal
and sorted by the time element
values in descending order.

5.2. Wildcards

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

Example 5.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 5.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.

63