RHEVM Shell Guide
Installing and Using the Command Line Shell for Red Hat Virtualization
Abstract
Chapter 1. Using the CLI
Important
1.1. Installing the CLI
- Log into the client machine as the
root
user. - Register your system with the Content Delivery Network, entering your Customer Portal user name and password when prompted:
# subscription-manager register
- Find the
Red Hat Virtualization
subscription pool and note down the pool ID.# subscription-manager list --available
- 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
- Enable the required repository:
# subscription-manager repos --enable=rhel-7-server-rhv-4.1-rpms
- Install the CLI package and dependencies:
# yum install ovirt-engine-cli
1.2. TLS/SSL Certification
Important
Procedure 1.1. Obtaining a Certificate
- 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.
- If using cURL:
$ curl -o rhvm.cer http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
- If using Wget:
$ wget -O rhvm.cer http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
- 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.- 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 asrhvm.cer
.
- Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to your client machine.
- Log in to the Manager as the
root
user. - 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 calledrhvm.cer
. - Copy the certificate to the client machine using the
scp
command:$ scp rhvm.cer [username]@[client-machine]:[directory]
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
.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
.
.ovirtshellrc
file falls under two section headings, [cli]
and [ovirt-shell]
. These headings are necessary for the configuration file to be parsed.
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 .
|
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_cert_chain
|
boolean
|
Toggles validation of server CA certificate. The status is either
True or 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
# ovirt-shell
ovirt-shell
application is an interactive shell for Red Hat Virtualization environments.
.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.
# ovirt-shell -c -l "https://[server]/ovirt-engine/api" -P [port] -u "[user@domain]" -A "[certificate]"
- 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.
Note
.ovirtshellrc
file.
Note
Options for ovirt-shell
- -h, --help
- Show help for
ovirt-shell
. - -d, --debug
- Enables debugging.
- -l URL, --url=URL
- Specifies the API entry point URL.
- -u USERNAME, --username=USERNAME
- Connect as this user.
- -K KEY_FILE, --key-file=KEY_FILE
- Specify key file.
- -C CERT_FILE, --cert-file=CERT_FILE
- Specify certificate file.
- -A CA_FILE, --ca-file=CA_FILE
- Specify server Certificate Authority file.
- -I, --insecure
- Allow the CLI to connect via SSL without certification. Use this option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
- -F, --filter
- Enable filtering based upon user permissions.
- -P PORT, --port=PORT
- Specify port.
- -T TIMEOUT, --timeout=TIMEOUT
- Specify timeout.
- -c, --connect
- Automatically connect.
- -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.
Note
1.5. Interacting with the CLI
Example 1.1. Entering a shell command
[RHEVM shell (connected)]# show vm RHEL6-Server
TAB
key twice, similar to the bash shell.
Example 1.2. Listing and automatic completion of commands and parameters
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
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
TAB
also completes commands and parameters.
[RHEVM shell (connected)]# add vmTAB 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
TAB
also automatically formats na
to the --name
parameter, including the prefix.
TAB
lists them.
[RHEVM shell (connected)]# add vTAB TAB
vmpool vm
shell
command or the bang (!
) character.
Example 1.3. Running Linux shell commands
shell
command:
[RHEVM shell (connected)]# shell ls -la
!
) character:
[RHEVM shell (connected)]# !ls -la
Example 1.4. Piping CLI commands
[RHEVM shell (connected)]# list vms --show-all | grep "Example" name : Example1 name : Example2 name : ExampleEngineering description : An Example description name : BestExampleVM
[RHEVM shell (connected)]# list vms --show-all > list vms --show-all > VM_List.txt
help
command.
Example 1.5. Using online help for the show
command
[RHEVM shell (connected)]# help show
Example 1.6. Connecting to the Manager to execute specific commands
--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
[RHEVM shell (connected)]# command --param-collection {subparam1=value1;subparam2=value2;subparam3=value3;...},{subparam1=value1;subparam2=value2;subparam3=value3;...},...
Chapter 2. Quick Start Example
2.1. Creating a Basic Virtualization Environment with the CLI
- 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
Procedure 2.1. Quick Start Example
- 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
- 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
- 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
- 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
- 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 calledovirtmgmt
for management traffic. This example uses theovirtmgmt
logical network on theDefault
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 thedata_center-id
value matches theid
for theDefault
data center. - 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!
- 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
andstorage-path
with the correct values for the NFS server.- 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
- Verify that the created storage domain is available. The creation process might take several minutes. Once the
status-state
isunattached
, you can proceed to the next step.[RHEVM shell (connected)]# show storagedomain DataStorage id : xxxx name : DataStorage master : False status-state : unattached ...
- 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
- 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
andstorage-path
with the correct values for the NFS server.- 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
- Verify that the created storage domain is available. The creation process might take a while. Once the
status-state
isunattached
, you can proceed to the next step.[RHEVM shell (connected)]# show storagedomain --name ISOStorage id : xxxx name : ISOStorage master : False status-state : unattached ...
- 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
- 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
- Use the
add nic
command to add a new network interface. Add thevm-identifier
option to attach the interface as a sub-resource ofMyVM
and anetwork-name
option to connect to theovirtmgmt
network.[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --network-name ovirtmgmt --bootable true
- Use the
add disk
command to add a new virtual hard disk. Add thevm-identifier
option to attach the disk as a sub-resource ofMyVM
.[RHEVM shell (connected)]# add disk --vm-identifier MyVM --provisioned_size 8589934592 --interface virtio --format cow --storage_domains-storage_domain storage_domain.name=DataStorage
- 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):
- 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
- Add a virtual CD-ROM drive for your installation media. Add the
vm-identifier
option to attach the CD-ROM as a sub-resource ofMyVM
.[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.6-x86_64-dvd.iso
- 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 thevm-os-boot
option. This changes the boot device tocdrom
for this initial boot session. After installation, the virtual machine restarts and restores the boot device back tohd
. - Use the
list events
with an additionalquery
option to display specific event types. Thestart
action for the virtual machine adds several entries in theevents
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. - Use the
show event
command to display comprehensive details of an event. This command can be used to show events bytype
,name
, andid
.[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
- 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'sdisplay-type
. Protocols available include SPICE (default) and VNC.
Chapter 3. Commands
3.1. Connecting to RHEVM
3.1.1. Connect to RHEVM (connect)
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.
connect [options]
Note
.ovirtshellrc
file.
Option | Description | Required |
---|---|---|
--url | The URL to the Red Hat Virtualization Manager's REST API. This takes the form of https://[server]/ovirt-engine/api . | Yes |
--username | The user name and directory service domain of the user attempting access to the Red Hat Virtualization Manager. This takes the form of [username]@[domain]. | Yes |
--password | The password for the user attempting access to the Red Hat Virtualization Manager. | Yes |
--key-file | The key file for connection via SSL. | No |
--cert-file | The certificate file for connection via SSL. | No |
--ca-file | The certificate authority file for connection via SSL. | Yes, unless --insecure is used |
--insecure | Allow the CLI to connect via SSL without certification. Use this option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server. | Yes, but only if no certificate authority is provided |
--filter | Enable filtering based upon user permissions. | No |
--port | The port number for connection to the REST API, if not specified as part of the --url . | No |
--timeout | The timeout period for connection. | No |
Example 3.1. Example for connect
when .ovirtshellrc
is not configured
[RHEVM shell (disconnected)]# connect --url "https://rhevm.example.com/ovirt-engine/api" --username "admin@exampleids.com" --password "p@55w0rd!" --ca-file "/home/user/ca.crt" ========================================== >>> connected to RHEVM manager 4.0.0.0 <<< ========================================== [RHEVM shell (connected)]#
Note
3.1.2. Disconnect from RHEVM (disconnect)
disconnect
command disconnects from Red Hat Virtualization Manager.
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)
list
command to display all resources of a specific type. Lists also include optional search queries to filter results.
list [collection] [options]
Option | Description |
---|---|
--show-all | Displays all non-empty properties for each listed resource. Without this option, only the id , name and description properties display. |
--query [QUERY] | Filters the list using a server-side query based upon Red Hat Virtualization Manager query language. |
--kwargs [QUERY] | Filters the list using a client-side query. |
--case_sensitive true|false | Match search queries using case sensitivity. |
--max | Maximum number of results for display. |
Note
Example 3.3. Examples for list
[RHEVM shell (connected)]# list vms
[RHEVM shell (connected)]# list vms --show-all
[RHEVM shell (connected)]# list vms --query "status=up"
[RHEVM shell (connected)]# list users --query "usrname=jsmith@*" --case_sensitive false
[RHEVM shell (connected)]# list --help
3.2.2. Show a Resource (show)
show
command to display resource properties.
show [resource] [id|name] [options]
Note
Example 3.4. Examples for show
id
:
[RHEVM shell (connected)]# show vm fcadfd5f-9a12-4a1e-bb9b-2b9d5c2e04c3
name
:
[RHEVM shell (connected)]# show vm RHEL6-Server
3.2.3. Add a Resource (add)
add
command to add a new resource.
add [resource] [options]
Note
Example 3.5. Examples for add
[RHEVM shell (connected)]# add vm [vm-options]
[RHEVM shell (connected)]# add user [user-options]
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)
update
command to modify an existing resource.
update [resource] [id|name] [options]
Note
Example 3.6. Examples for update
[RHEVM shell (connected)]# update vm RHEL6-Server [vm-options]
3.2.5. Remove a Resource (remove)
remove
command to remove a resource.
remove [resource] [id|name] [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
Example 3.7. Examples for remove
[RHEVM shell (connected)]# remove vm RHEL6-Server
[RHEVM shell (connected)]# remove vm RHEL6-Server --async true
[RHEVM shell (connected)]# remove vm RHEL6-Server --force
3.2.6. Perform Action on a Resource (action)
action
command to perform a special function relevant to resource type.
action [resource] [id|name] [action] [options]
Note
Example 3.8. Examples for action
[RHEVM shell (connected)]# action vm RHEL6-Server start
[RHEVM shell (connected)]# action vm RHEL6-Server stop
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)
--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
[RHEVM shell (connected)]# add nic --vm-identifier RHEL6-Server [nic-options]
--vm-identifier RHEL6-Server
option. This adds a NIC on the RHEL6-Server virtual machine.
[RHEVM shell (connected)]# add disk --vm-identifier RHEL6-Server [user-options]
--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)
EOF
command to leave the CLI shell using a Ctrl+D
sequence.
EOF
Example 3.10. Example for EOF
[RHEVM shell (connected)]# EOF
3.3.2. List System Capabilities (capabilities)
capabilties
--features
command to list all version capabilities and new features of the current version.
capabilities
--features
Example 3.11. Example for capabilities
[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)
clear
command to clear the CLI screen.
clear
Example 3.12. Example for clear
[RHEVM shell (connected)]# clear
3.3.4. Connect to VM (console)
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.
console [vm-id|vm-name]
Example 3.13. Example for console
[RHEVM shell (connected)]# console RHEL6-Server
3.3.5. Print Input (echo)
echo
command to print input to the screen. Use the $out
variable to print the last shell command output.
echo [input]
Example 3.14. Example for echo
[RHEVM shell (connected)]# echo "Example text!"
[RHEVM shell (connected)]# echo $out
3.3.6. Exit from the CLI (exit)
exit
command to leave a CLI.
exit
Example 3.15. Example for exit
[RHEVM shell (connected)]# exit
3.3.7. Run a Script (file)
file
command to run a CLI script file. A script is a plain text file that contains a list of commands for execution.
file [file-location]
Example 3.16. Example for file
[RHEVM shell (connected)]# file /example/example-script
3.3.8. Show Help (help)
help
command displays help for CLI command and resource combinations.
help [command] [resource] [options]
Example 3.17. Examples for help
[RHEVM shell (connected)]# help
add
command:
[RHEVM shell (connected)]# help add
add
command on the vm
resource type:
[RHEVM shell (connected)]# help add vm
3.3.9. Display the User Command History (history)
history
command to display the history of user commands for the CLI shell.
history
Example 3.18. Example for history
[RHEVM shell (connected)]# history
Example 3.19. Example for history --first
--first
n parameter:
[RHEVM shell (connected)]# history --first 5
Example 3.20. Example for history --last
--last
n parameter:
[RHEVM shell (connected)]# history --last 5
3.3.10. Show CLI Information (info)
info
command to display environment connection details and version information.
info
Example 3.21. Example for info
[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)
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.
ping
Example 3.22. Example for ping
[RHEVM shell (connected)]# ping success: RHEVM manager could be reached OK.
3.3.12. Run a Shell Command (shell)
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.
shell [vm-id|vm-name]
Example 3.23. Examples for shell
[RHEVM shell (connected)]# shell ls
[RHEVM shell (connected)]# shell touch example.txt
[RHEVM shell (connected)]# shell cp example.txt /example-dir/.
Note
shell
using the bang (!
) character. For example:
[RHEVM shell (connected)]# !touch example.txt
3.3.13. Show Last Status (status)
status
command to display the most recently run command status.
status
Example 3.24. Example for status
[RHEVM shell (connected)]# status last command status: 0 (OK)
3.3.14. Show System Summary (summary)
summary
command to display a summary of the system status.
summary
Example 3.25. Example for summary
[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
Chapter 4. Resource Types
4.1. brick
brick
resource type groups all Gluster bricks in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--server_id
|
string
|
The address of the Gluster server.
|
Yes
|
Yes
|
No
|
--brick_dir
|
string
|
The brick's directory on the Gluster server.
|
Yes
|
Yes
|
No
|
--replica_count
|
integer
|
Defines the file replication count for a replicated volume.
|
No
|
Yes
|
No
|
--stripe_count
|
Integer
|
Defines the stripe count for a striped volume
|
No
|
Yes
|
No
|
glustervolume
options for resource-based commands.
Option | Description |
---|---|
--cluster-identifier | Reference to the cluster that contains a glustervolume sub-resource. |
--glustervolume-identifier | Adds the brick to a glustervolume as a sub-resource. |
Example 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
cdrom
resource type groups all virtual CD-ROM drive resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--file-id
|
string
|
Defines the file name of the ISO that resides on an ISO storage domain.
|
Yes
|
Yes
|
Yes
|
Example 4.2. Creating a new CD-ROM
[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.2-x86_64-dvd.iso.iso
Example 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
cluster
resource type groups all host cluster resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--cpu-id
|
string
|
A server CPU reference that defines the CPU type all hosts must support in the cluster.
|
Yes
|
Yes
|
Yes
|
--data_center-id|name
|
string
|
A reference to the data center for a host cluster.
|
Yes
|
Yes
|
No
|
--name
|
string
|
The name of a host cluster.
|
Yes
|
Yes
|
Yes
|
--version-major
|
int
|
The major version number of the cluster. For example, for Red Hat Virtualization 4.1, the major version is 4.
|
Yes
|
Yes
|
Yes
|
--version-minor
|
int
|
The minor version number of the cluster. For example, for Red Hat Virtualization 4.1, the minor version is 0.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the host cluster.
|
No
|
Yes
|
Yes
|
--error_handling-on_error
|
string
|
Defines virtual machine handling when a host within a cluster becomes non-operational, including
migrate , do_not_migrate and migrate_highly_available .
|
No
|
Yes
|
Yes
|
--gluster_service
|
Boolean
|
The status is either
true or false .
|
No
|
Yes
|
Yes
|
--memory_policy-overcommit-percent
|
double
|
The percentage of host memory allowed in use before a host can no longer run any more virtual machines. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include
100 (None), 150 (Server Load) and 200 (Desktop Load).
|
No
|
Yes
|
Yes
|
--memory_policy-transparent_hugepages-enabled
|
Boolean
|
Defines the enabled status of Transparent Hugepages. The status is either
true or false .
|
No
|
Yes
|
Yes
|
--scheduling_policy-policy
|
string
|
The VM scheduling mode for hosts in the cluster, such as
evenly_distributed , power_saving or blank for none.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-duration
|
int
|
The number of seconds the host can be overloaded before the scheduler starts and moves the load to another host.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-high
|
int
|
Controls the highest CPU usage percentage the host can have before being considered overloaded.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-low
|
int
|
Controls the lowest CPU usage percentage the host can have before being considered underutilized.
|
No
|
Yes
|
Yes
|
--threads_as_cores
|
Boolean
|
Hosts treat threads as cores, allowing hosts to run virtual machines with a total number of processor cores greater than the number of cores in the host. The status is either
true or false .
|
No
|
No
|
No
|
--trusted_service
|
Boolean
|
Defines whether an OpenAttestation server is used to verify hosts.
|
No
|
Yes
|
Yes
|
--virt_service
|
Boolean
|
The status is either
true or false .
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
Example 4.5. Creating a new cluster
[RHEVM shell (connected)]# add cluster --name Engineering --cpu-id "Intel Penryn Family" --datacenter-name Default --version-major 3 --version-minor 2
Example 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
datacenter
resource type groups all data center resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the data center.
|
Yes
|
Yes
|
Yes
|
--storage_type
|
string
|
The type of storage for the data center, including
iscsi , fcp , nfs , localfs or posixfs .
|
Yes
|
Yes
|
Yes
|
--version-major
|
int
|
The major version number of the data center. For example, for Red Hat Virtualization 4.1, the major version is 4.
|
Yes
|
Yes
|
Yes
|
--version-minor
|
int
|
The minor version number of the data center. For example, for Red Hat Virtualization 4.1, the minor version is 0.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the data center.
|
No
|
Yes
|
Yes
|
--storage_format
|
string
|
The metadata format for the data center, including
v1 , v2 or v3 .
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
Example 4.8. Creating a new data center
[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --version-major 3 --version-minor 2
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
disk
resource type groups all virtual hard disk resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--provisioned_size
|
int
|
The reserved storage space for the disk. This space is preallocated for the disk to use, even if the disk
size is less than the provisioned_size
|
Yes
|
Yes
|
Yes
|
--interface
|
string
|
The interface type of the disk. Either
ide or virtio .
|
Yes
|
Yes
|
Yes
|
--format
|
string
|
The underlying storage format. Copy On Write (
cow ) allows snapshots, with a small performance overhead. Raw (raw ) does not allow snapshots, but offers improved performance.
|
Yes
|
Yes
|
Yes
|
--size
|
int
|
The actual size of the disk.
|
No
|
Yes
|
Yes
|
--sparse
|
Boolean
| true if the physical storage for the disk should not be preallocated.
|
No
|
Yes
|
Yes
|
--bootable
|
Boolean
| true if this disk is to be marked as bootable.
|
No
|
Yes
|
Yes
|
--shareable
|
Boolean
| true if this disk is shareable.
|
No
|
Yes
|
Yes
|
--allow_snapshot
|
Boolean
| true if this disk allows snapshots.
|
No
|
Yes
|
Yes
|
--propagate_errors
|
Boolean
| true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS.
|
No
|
Yes
|
Yes
|
--wipe_after_delete
|
boolean
| true if the underlying physical storage for the disk should be zeroed when the disk is deleted. This increases security but is a more intensive operation and may prolong delete times.
|
No
|
Yes
|
Yes
|
--storage_domains-storage_domain
|
collection
|
Defines a specific storage domain for the disk.
|
No
|
Yes
|
No
|
--storage_domains-storage_domain
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
storage_domain.id|name
|
string
|
A reference to a storage domain for the disk.
|
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
Action | Description |
---|---|
activate | Activate a disk on a virtual machine. |
deactivate | Deactivate a disk on a virtual machine. |
4.6. glustervolume
glustervolume
resource type groups all Gluster storage volume resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the Gluster volume.
|
Yes
|
Yes
|
No
|
--volume_type
|
string
|
Defines the Gluster volume type. Choose from
DISTRIBUTE , REPLICATE , DISTRIBUTED_REPLICATE , STRIPE or DISTRIBUTED_STRIPE .
|
Yes
|
Yes
|
No
|
--bricks-brick
|
collection
|
A new Gluster volume requires a set of Gluster bricks to add and manage. This parameter references a collection of brick details. Specify at least one brick but list multiple
bricks-brick parameters for multiple bricks. See below for collection details.
|
Yes
|
Yes
|
No
|
--transport_types
|
collection
|
A reference to available transport methods for the Gluster volume. See below for collection details.
|
No
|
Yes
|
No
|
--replica_count
|
integer
|
Defines the file replication count for a replicated volume.
|
No
|
Yes
|
No
|
--stripe_count
|
Integer
|
Defines the stripe count for a striped volume
|
No
|
Yes
|
No
|
--options-option
|
collection
|
A reference to options for the Gluster volume. See below for collection details.
|
No
|
Yes
|
No
|
--bricks-brick
parameter is a collection that uses the sub-parameters in the following table.
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.
|
--transport_types
parameter is a collection that uses the sub-parameters in the following table.
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 .
|
--options-option
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
option.name
|
string
|
The Gluster option name.
|
option.value
|
string
|
The Gluster option value.
|
glustervolume
options for resource-based commands.
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
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
group
resource type defines all identity service groups for a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the group, usually the full group path within the identity directory service.
|
No
|
No
|
No
|
Example 4.16. Creating a group
[RHEVM shell (connected)]# add group --name www.example.com/accounts/groups/mygroup --domain-name example.com
4.8. host
host
resource type groups all host resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the host.
|
Yes
|
Yes
|
Yes
|
--address
|
string
|
The IP address or hostname for the host.
|
Yes
|
Yes
|
Yes
|
--root_password
|
string
|
The password for the host's
root user.
|
Yes
|
Yes
|
Yes
|
--cluster-id|name
|
string
|
Defines the cluster that includes the host.
|
Yes
|
Yes
|
Yes
|
--port
|
int
|
The port for communication with the VDSM daemon running on the host.
|
No
|
Yes
|
Yes
|
--storage_manager-priority
|
int
|
Sets the priority of host order for storage pool manager (SPM).
|
No
|
Yes
|
Yes
|
--power_management-type
|
string
|
The type of power management device in the host.
|
No
|
Yes
|
Yes
|
--power_management-enabled
|
boolean
|
Indicates whether power management configuration is enabled or disabled.
|
No
|
Yes
|
Yes
|
--power_management-address
|
string
|
The host name or IP address of the power management device.
|
No
|
Yes
|
Yes
|
--power_management-user_name
|
string
|
A valid user name for power management.
|
No
|
Yes
|
Yes
|
--power_management-password
|
string
|
A valid, robust password for power management.
|
No
|
Yes
|
Yes
|
--power_management-options-option
|
collection
|
Fencing options for the selected
power_management-type .
|
No
|
Yes
|
Yes
|
--reboot_after_installation
|
boolean
|
Defines if the host reboots after VDSM installation.
|
No
|
Yes
|
No
|
--power_management-options-option
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
option.name
|
string
|
Power management option name.
|
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
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. |
fence
action.
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
4.9. network
network
resource type groups all logical network resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--data_center-id|name
|
string
|
A reference to the data center for a logical network.
|
Yes
|
Yes
|
No
|
--name
|
string
|
A plain text name for the logical network.
|
Yes
|
Yes
|
No
|
--description
|
string
|
A description for the logical network.
|
No
|
Yes
|
Yes
|
--vlan-id
|
string
|
A VLAN tag.
|
No
|
Yes
|
Yes
|
--ip-address
|
string
|
The IP address for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--ip-gateway
|
string
|
The gateway for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--ip-netmask
|
string
|
The netmask for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--display
|
boolean
|
Signifies if a logical network is used for display communication usage. Set to either
true or false .
|
No
|
Yes
|
Yes
|
--stp
|
boolean
|
Set to
true if Spanning Tree Protocol is enabled on this network.
|
No
|
Yes
|
Yes
|
--mtu
|
int
|
Sets a user-defined value for the maximum transmission unit of the logical network.
|
No
|
Yes
|
Yes
|
--usages-usage
|
collection
|
Defines usage parameters for the logical network.
|
No
|
No
|
Yes
|
--usages-usage
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
usage
|
string
|
Usage types for the network. Options include
VM and DISPLAY .
|
network
options for resource-based commands.
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
[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
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.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--network-id|name
|
string
|
A reference to the network, if any, that the interface is attached.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the host network interface, e.g.
eth0 .
|
Yes
|
Yes
|
Yes
|
--bonding-slaves-host_nic
|
collection
|
A collection of slave network interfaces that form a bonded interface.
|
No
|
Yes
|
Yes
|
--bonding-options-option
|
collection
|
A list of options for a bonded interface. Each option contains property
name and value attributes.
|
No
|
Yes
|
Yes
|
--ip-gateway
|
string
|
The IP address for the network's gateway.
|
No
|
Yes
|
Yes
|
--boot_protocol
|
string
|
The protocol for IP address assignment when the host is booting, such as
dhcp or static .
|
No
|
Yes
|
Yes
|
--mac
|
string
|
The MAC address of the interface.
|
No
|
Yes
|
Yes
|
--ip-address
|
string
|
The IP address of the interface.
|
No
|
Yes
|
Yes
|
--ip-netmask
|
string
|
The netmask for the interface's IP address.
|
No
|
Yes
|
Yes
|
--ip-mtu
|
int
|
The maximum transmission unit for the interface.
|
No
|
No
|
Yes
|
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--network-id|name
|
string
|
A reference to the network, if any, that the interface is attached.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the interface, e.g.
eth0 .
|
Yes
|
Yes
|
Yes
|
--mac-address
|
string
|
The MAC address of the interface.
|
No
|
Yes
|
Yes
|
--interface
|
string
|
Defines the interface type, such as
e1000 , virtio , rtl8139 and rtl8139_virtio .
|
No
|
Yes
|
Yes
|
--port_mirroring-networks-network
|
collection
|
Defines a set of networks to copy (mirror) network data from the network interface.
|
No
|
Yes
|
Yes
|
--bonding-slaves-host_nic
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
host_nic.id|name
|
string
|
A reference to another host NIC to bond.
|
--bonding-options-option
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
option.name
|
string
|
The bonding option name.
|
option.value
|
string
|
The bonding option value.
|
type
|
string
|
The bonding option type.
|
--port_mirroring-networks-network
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
network.id
|
string
|
A reference to the network to mirror.
|
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
[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
Action | Description |
---|---|
attach | Attach a NIC to a host. |
detach | Detach a NIC from a host. |
Action | Description |
---|---|
activate | Activate a NIC on a virtual machine. |
deactivate | Deactivate a NIC on a virtual machine. |
4.11. permission
permission
resource type groups all permission resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--user-id , --group-id
|
string
|
A reference to the user or group using the permission.
|
Yes
|
Yes
|
No
|
--role-id
|
string
|
A reference to a role to assign for the permission.
|
Yes
|
Yes
|
No
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
permission
options for resource-based commands.
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-identifier
|
Adds the permission to a storage domain.
|
--template-identifier
|
Adds the permission to a template.
|
--vm-identifier
|
Adds the permission to a virtual machine.
|
--vmpool-identifier
|
Adds the permission to a virtual machine pool.
|
--vnicprofile-identifier
|
Adds the permission to a VNIC profile.
|
Example 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
permit
resource type groups all individual permits for roles in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--id
|
string
|
A reference to the permit to add.
|
Yes
|
Yes
|
No
|
permit
options for resource-based commands.
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
quota
resource type groups all datacenter quotas in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the quota.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the quota.
|
Yes
|
Yes
|
Yes
|
4.14. role
role
resource type groups all individual roles in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the role.
|
Yes
|
Yes
|
Yes
|
--permits-permit
|
collection
|
A list of permits for initial inclusion with the role. Additional permits included with the permit resource type.
|
Yes
|
Yes
|
No
|
--description
|
string
|
A description for the role.
|
No
|
Yes
|
Yes
|
--administrative
|
Boolean
|
Set to
true if this is an administrative role.
|
No
|
Yes
|
Yes
|
--permits-permit
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
permit.id
|
string
|
A reference to a permit to add to the role's permits.
|
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
snapshot
resource type groups all virtual machine snapshot resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--description
|
string
|
A description for the snapshot.
|
Yes
|
Yes
|
No
|
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]
Action | Description |
---|---|
restore | Restore a snapshot. |
4.16. statistic
statistic
resource type groups statistics for resources in a Red Hat Virtualization environment. Resource statistics are listed based on their resource identifier.
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-identifier | The resource identifier to view statistics for the specified gluster 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-identifier | The resource identifier to view statistics for the specified storage domain. |
--vm-identifier | The resource identifier to view statistics for the specified virtual machine. |
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
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
storageconnection
resource type allows you to add, edit, and delete storage connections.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--address
|
string
|
The hostname or IP address of the storage domain.
|
Yes (NFS and iSCSI only)
|
Yes
|
Yes
|
--correlation_id
|
string
|
A tagging identifier for the storage connection.
|
No
|
No
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--iqn
|
string
|
The target IQN for the storage device.
|
Yes (iSCSI only)
|
Yes
|
Yes
|
--mount_options
|
string
|
The options for mounting the PosixFS share.
|
No
|
Yes
|
Yes
|
--nfs_retrans
|
integer
|
The number of retransmissions the NFS client will attempt to complete a request.
|
No
|
Yes
|
Yes
|
--nfs_timeo
|
integer
|
The amount of time, in deciseconds, the NFS client will wait for a request to complete.
|
No
|
Yes
|
Yes
|
--nfs_version
|
string
|
The version of NFS used.
|
No
|
Yes
|
Yes
|
--password
|
string
|
A CHAP password for logging into a target of an iSCSI storage domain.
|
No
|
Yes
|
Yes
|
--path
|
string
|
The mounted file path of the storage domain. The path cannot be updated to one already used by a storage connection.
|
Yes (NFS, local, and PosixFS only)
|
Yes
|
Yes
|
--port
|
integer
|
The TCP port used for the iSCSI storage domain.
|
Yes (iSCSI only)
|
Yes
|
Yes
|
--storagedomain-identifier
|
string
|
A reference to a storage domain for the disk.
|
No
|
No
|
No
|
--type
|
string
|
The type of storage domain.
|
Yes
|
Yes
|
No
|
--username
|
string
|
A CHAP user name for logging into a target of an iSCSI storage domain.
|
No
|
Yes
|
Yes
|
--vfs_type
|
string
|
The Linux-supported file system type of the PosixFS share.
|
Yes (PosixFS only)
|
Yes
|
Yes
|
Example 4.35. Creating a new storage connection
[RHEVM shell (connected)]# add storageconnection --address storage.example.com --path /storage/nfs --type nfs
4.18. storagedomain
storagedomain
resource type groups all storage domain resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the storage domain.
|
No
|
Yes
|
Yes
|
--format
|
Boolean
|
The metadata format for the data center, including
v1 , v2 or v3 .
|
Yes
|
Yes
|
No
|
--host-id|name
|
string
|
A reference to the host from which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified.
|
Yes
|
Yes
|
No
|
--storage-address
|
string
|
The IP address or hostname of the storage device.
|
Yes
|
Yes
|
No
|
--storage-logical_unit
|
collection
|
The logical unit information of the storage device.
|
See below
|
Yes
|
No
|
--storage-mount_options
|
string
|
The options for mounting the storage domain.
|
See below
|
Yes
|
No
|
--storage-override_luns
|
Boolean
|
Defines whether to override the logical unit number. The status is either
true or false .
|
See below
|
Yes
|
No
|
--storage-path
|
string
|
The path on the storage device to use for the storage domain.
|
See below
|
Yes
|
No
|
--storage-type
|
string
|
The type of storage for the data center, including
iscsi , fcp , nfs , glusterfs , localfs or posixfs .
|
Yes
|
Yes
|
No
|
--storage-vfs_type
|
string
|
Defines the file system type of the storage domain.
|
See below
|
Yes
|
No
|
--type
|
string
|
The type of storage domain, including
data , iso and export .
|
Yes
|
Yes
|
No
|
--storage-logical_unit
parameter is a collection that requires all sub-parameters in the following table.
Name | Type | Description |
---|---|---|
logical_unit.address
|
string
|
The address of the server containing the storage device.
|
logical_unit.port
|
integer
|
The port number of the server.
|
logical_unit.target
|
string
|
The target IQN for the storage device.
|
logical_unit.username
|
string
|
A CHAP user name for logging into a target.
|
logical_unit.password
|
string
|
A CHAP password for logging into a target.
|
logical_unit.serial
|
string
|
The serial ID for the target.
|
logical_unit.vendor_id
|
string
|
The vendor name for the target.
|
logical_unit.product_id
|
string
|
The product code for the target.
|
logical_unit.lun_mapping
|
integer
|
The Logical Unit Number device mapping for the target.
|
logical_unit.portal
|
string
|
The logical unit portal.
|
logical_unit.paths
|
integer
|
The logical unit paths.
|
logical_unit.id
|
string
|
A reference to the logical unit ID.
|
storage-type
.
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
|
storagedomain
options for resource-based commands.
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
[RHEVM shell (connected)]# update storagedomain DataStorage --name DataStorageOld
Example 4.39. Deleting a storage domain
[RHEVM shell (connected)]# remove storagedomain DataStorage
Action | Description |
---|---|
activate | Activate a storage domain on a data center. |
deactivate | Deactivate a storage domain on a data center. |
4.19. tag
tag
resource type groups all tags in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the tag.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the string.
|
Yes
|
Yes
|
Yes
|
--parent-name
|
string
|
A reference to the parent tag that the tag is attached.
|
Yes
|
Yes
|
Yes
|
Example 4.40. Creating a new tag
[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine tag" --parent MyParentTag
4.20. template
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.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--vm-id|name
|
string
|
A reference to the virtual machine used as the basis for the template.
|
Yes
|
Yes
|
No
|
--name
|
string
|
The name of the virtual machine template.
|
Yes
|
Yes
|
Yes
|
--memory
|
long
|
The amount of memory for the virtual machine template in bytes.
|
No
|
Yes
|
Yes
|
--cpu-topology-cores
|
int
|
The number of CPU cores available to the virtual machine template.
|
No
|
Yes
|
Yes
|
--high_availability-enabled
|
Boolean
|
Set to
true to enable high availability for the virtual machine template.
|
No
|
Yes
|
Yes
|
--os-cmdline
|
string
|
A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--origin
|
string
|
The virtual machine template's origin. Specify
rhev , vmware , or xen .
|
No
|
Yes
|
Yes
|
--high_availability-priority
|
int
|
Sets the priority value (i.e. boot order) of each virtual machine template's high availability.
|
No
|
Yes
|
Yes
|
--timezone
|
string
|
The Sysprep timezone setting for a Windows virtual machine template. Specify formats such as
GMT+00:00 .
|
No
|
Yes
|
Yes
|
--domain-name
|
string
|
The domain name of the virtual machine template.
|
No
|
Yes
|
Yes
|
--type
|
string
|
Defines the virtual machine type. Specify either
desktop or server .
|
No
|
Yes
|
Yes
|
--stateless
|
boolean
|
Set to
true if the resulting virtual machines are stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and removed at shutdown. This means state changes do not persist after a reboot.
|
No
|
Yes
|
Yes
|
--delete_protected
|
boolean
|
Set to
true to make it impossible to delete a virtual machine created from this template.
|
No
|
Yes
|
Yes
|
--sso-methods-method
|
collection
|
Defines the single sign-on method used. For example,
--sso-methods-method method.id=GUEST_AGENT .
|
No
|
Yes
|
Yes
|
--rng_device-rate-bytes
|
int
|
Specifies how many bytes are permitted to be consumed per period.
|
No
|
Yes
|
Yes
|
--rng_device-rate-period
|
int
|
Specifies the duration of a period in milliseconds. If specified,
--rng_device-rate-bytes must be specified as well.
|
No
|
Yes
|
Yes
|
--rng_device-source
|
string
|
The source of the random number generator. Specify either
random or hwrng .
|
No
|
Yes
|
Yes
|
--console-enabled
|
boolean
|
Set to
true to enable the VirtIO console device feature.
|
No
|
Yes
|
Yes
|
--placement_policy-affinity
|
string
|
The migration affinity for each virtual machine created from the template. Specify
migratable , user_migratable , or pinned .
|
No
|
Yes
|
Yes
|
--description
|
string
|
A description for the virtual machine template.
|
No
|
Yes
|
Yes
|
--comment
|
string
|
A comment for the virtual machine template.
|
No
|
Yes
|
Yes
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--os-type
|
string
|
The operating system type for the virtual machine template.
|
No
|
Yes
|
Yes
|
--os-boot
|
collection
|
The boot device for the virtual machine template. Specify
cdrom , hd , or network . For example, --os-boot boot.dev=hd .
|
No
|
Yes
|
Yes
|
--cpu-topology-sockets
|
int
|
The number of CPU sockets available to the virtual machine template.
|
No
|
Yes
|
Yes
|
--cpu_shares
|
int
|
The level of CPU resources a virtual machine 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.
|
No
|
Yes
|
Yes
|
--cpu-architecture
|
string
|
Defines the CPU architecture. Specify
x86_64 , ppc64 , or undefined .
|
No
|
Yes
|
Yes
|
--os-kernel
|
string
|
A path to a kernel image the resulting virtual machines are configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--display-type
|
string
|
Defines the display type. Specify either
spice or vnc .
|
No
|
Yes
|
Yes
|
--display-monitors
|
int
|
Defines the number of displays available.
|
No
|
Yes
|
Yes
|
--display-single_qxl_pci
|
boolean
|
Set to
true to drive multiple monitors using a single virtual PCI device.
|
No
|
Yes
|
Yes
|
--display-allow_override
|
boolean
|
Set to
true to allow override of the template console settings.
|
No
|
Yes
|
Yes
|
--display-smartcard_enabled
|
boolean
|
Set to
true to enable the Smart card feature for virtual machines.
|
No
|
Yes
|
Yes
|
--display-file_transfer_enabled
|
boolean
|
Set to
true to enable SPICE file transfer.
|
No
|
Yes
|
Yes
|
--display-copy_paste_enabled
|
boolean
|
Set to
true to enable SPICE clipboard copy and paste.
|
No
|
Yes
|
Yes
|
--display-keyboard_layout
|
string
|
Defines the keyboard layout for the virtual machine. This option is only available when using the VNC protocol. Specify formats such as
en-US .
|
No
|
Yes
|
Yes
|
--os-initRd
|
string
|
A path to an initrd image to be used with a specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--usb-enabled
|
Boolean
|
Set to
true to enable USB support on the virtual machine. This option is only available for virtual machines using the SPICE protocol.
|
No
|
Yes
|
Yes
|
--usb-type
|
string
|
Defines the USB type if USB support is enabled. Specify either
Legacy or Native .
Important
The Legacy USB option has been deprecated and will be removed in Red Hat Virtualization 4.1.
|
No
|
Yes
|
Yes
|
--tunnel_migration
|
boolean
|
Set to
true to enable data transport over a libvirt daemon. A tunneled transport uses a stronger encryption algorithm but increases the data load during transport.
|
No
|
Yes
|
Yes
|
--migration_downtime
|
int
|
Defines the maximum number of milliseconds that the virtual machine can be down during live migration.
|
No
|
Yes
|
Yes
|
--virtio_scsi-enabled
|
boolean
|
Set to
true to allow attaching a VirtIO console device to the virtual machine.
|
No
|
Yes
|
Yes
|
--soundcard_enabled:
|
boolean
|
Set to
true to enable sound cards.
|
No
|
Yes
|
Yes
|
--vm-disks-disk
|
collection
|
References to disks attached to the template.
|
No
|
Yes
|
No
|
--id
|
string
|
The ID of the virtual machine template.
|
No
|
Yes
|
Yes
|
--permissions-clone
|
boolean
|
Set to
true to copy the permissions of the source virtual machine to the template.
|
No
|
Yes
|
Yes
|
--version-version_name
|
string
|
Used with the
--version-base_template-id parameter. Defines the name for the sub template.
|
No
|
Yes
|
Yes
|
--version-base_template-id
|
string
|
Defines the template ID to be used as the root template. Used if you want to create this template as a sub template of a root template.
|
No
|
Yes
|
Yes
|
--cpu-cpu_tune-vcpu_pin
|
collection
|
Defines which virtual CPUs of a virtual machine to pin to the physical CPUs of a host.
|
No
|
Yes
|
Yes
|
--serial_number-policy
|
string
|
Defines the serial number policy for the virtual machine template. Specify
host , vm , or custom . If custom is used, also define the serial number value using --serial_number-value .
|
No
|
Yes
|
Yes
|
--serial_number-value
|
string
|
Defines the serial number for the virtual machine template.
|
No
|
Yes
|
Yes
|
--bios-boot_menu-enabled
|
boolean
|
Set to
true to enable boot menu.
|
No
|
Yes
|
Yes
|
--cluster-id
|
string
|
Defines the cluster to use by specifying the cluster ID.
|
No
|
Yes
|
Yes
|
--cluster-name
|
string
|
Defines the cluster to use by specifying the cluster name.
|
No
|
Yes
|
Yes
|
--cpu_profile-id
|
string
|
Defines the CPU profile to use. Use the
list cpuprofiles command to retrieve a full list of CPU profile IDs.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
Yes
|
Yes
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
Yes
|
--sso-methods-method
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
method.id
|
string
|
The single sign-on method used:
GUEST_AGENT .
|
--custom_properties-custom_property
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property value.
|
--os-boot
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
boot.dev
|
string
|
The boot device for the virtual machine template. Specify
cdrom , hd , or network .
|
--vm-disks-disk
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
disk.id
|
string
|
A reference to a virtual disk.
|
storage_domains.storage_domain
|
collection
|
Defines a set of sub-parameters for the disk's storage domain.
|
--cpu-cpu_tune-vcpu_pin
parameter is a collection that uses the sub-parameters in the following table.
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
Action | Description |
---|---|
export | Export a template to an export storage domain. |
4.21. user
user
resource type groups all users in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--user_name
|
string
|
The user name from the directory service.
|
Yes
|
Yes
|
No
|
--domain-id|name
|
string
|
A reference to the directory service domain.
|
Yes
|
Yes
|
No
|
Example 4.44. Creating a new user
[RHEVM shell (connected)]# add user --user_name jsmith --domain-name example.com
4.22. vm
vm
resource type groups all virtual machine resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the virtual machine
|
Yes
|
Yes
|
Yes
|
--template-id|name
|
string
|
A reference to the template used as the basis for the virtual machine.
|
Yes
|
Yes
|
No
|
--cluster-id|name
|
string
|
A reference to the cluster that includes this VM.
|
Yes
|
Yes
|
Yes
|
--instance_type-id|name
|
string
|
Defines the instance type. Specify
custom , large , medium , small , tiny , or xlarge .
|
No
|
Yes
|
Yes
|
--quota-id
|
string
|
A reference to the quota usage for the virtual machine.
|
No
|
Yes
|
No
|
--timezone
|
string
|
The Sysprep time zone setting for a Windows virtual machine.
|
No
|
Yes
|
Yes
|
--os-boot
|
collection
|
The boot device for the virtual machine. Specify
cdrom , hd , or network .
|
No
|
Yes
|
Yes
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--os-type
|
string
|
The operating system type for this virtual machine.
|
No
|
Yes
|
Yes
|
--usb-enabled
|
boolean
|
Defines the USB policy for a virtual machine. Set to
true to enable USB on the virtual machine.
|
No
|
Yes
|
Yes
|
--usb-type
|
string
|
Defines the USB type if enabled.
|
No
|
Yes
|
Yes
|
--type
|
string
|
Defines the virtual machine type. Specify either
desktop or server .
|
No
|
Yes
|
Yes
|
--os-initRd
|
string
|
A path to an initrd image to be used with a specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--display-monitors
|
int
|
Defines the number of displays available.
|
No
|
Yes
|
Yes
|
--display-single_qxl_pci
|
boolean
|
Set to
true to drive multiple monitors using a single virtual PCI device.
|
No
|
Yes
|
Yes
|
--display-type
|
string
|
Defines the display type. Specify either
spice or vnc .
|
No
|
Yes
|
Yes
|
--display-allow_override
|
boolean
|
Set to
true to allow override of the virtual machine console settings.
|
No
|
Yes
|
Yes
|
--display-smartcard_enabled
|
boolean
|
Set to
true to enable the Smart card feature.
|
No
|
Yes
|
Yes
|
--display-file_transfer_enabled
|
boolean
|
Set to
true to enable SPICE file transfer.
|
No
|
Yes
|
Yes
|
--display-copy_paste_enabled
|
boolean
|
Set to
true to enable SPICE clipboard copy and paste.
|
No
|
Yes
|
Yes
|
--display-keyboard_layout
|
string
|
Defines the keyboard layout for the virtual machine. This option is only available when using the VNC protocol. Specify formats such as
en-US .
|
No
|
Yes
|
Yes
|
--os-cmdline
|
string
|
A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--cpu-topology-cores
|
int
|
The number of CPU cores available to the virtual machine.
|
No
|
Yes
|
Yes
|
--cpu-architecture
|
string
|
Defines the CPU architecture. Specify
x86_64 , ppc64 , or undefined .
|
No
|
Yes
|
Yes
|
--memory
|
long
|
The amount of memory for the virtual machine in bytes.
|
No
|
Yes
|
Yes
|
--memory_policy-guaranteed
|
long
|
The minimum amount of memory, in bytes, guaranteed on a host in order for the virtual machine to run.
|
No
|
Yes
|
Yes
|
--memory_policy-ballooning
|
boolean
|
Set to
true to enable memory balloon device.
|
No
|
Yes
|
Yes
|
--high_availability-priority
|
int
|
Sets the priority value (migration and restart order) of each virtual machine using high availability.
|
No
|
Yes
|
Yes
|
--high_availability-enabled
|
boolean
|
Defines whether high availability is enabled for the virtual machine.
|
No
|
Yes
|
Yes
|
--domain-name
|
string
|
The domain name of the virtual machine.
|
No
|
Yes
|
Yes
|
--description
|
string
|
A description of the virtual machine.
|
No
|
Yes
|
Yes
|
--comment
|
string
|
A comment for the virtual machine.
|
No
|
Yes
|
Yes
|
--stateless
|
boolean
|
Set to
true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and removed at shutdown. This means state changes do not persist after a reboot.
|
No
|
Yes
|
Yes
|
--permissions-clone
|
boolean
|
Set to
true to copy the permissions of the source virtual machine to the template.
|
No
|
Yes
|
Yes
|
--delete_protected
|
boolean
|
Set to
true to make it impossible to delete a virtual machine created from this template.
|
No
|
Yes
|
Yes
|
--sso-methods-method
|
collection
|
Defines the single sign-on method used. For example,
--sso-methods-method method.id=GUEST_AGENT .
|
No
|
Yes
|
Yes
|
--rng_device-rate-bytes
|
int
|
Specifies how many bytes are permitted to be consumed per period.
|
No
|
Yes
|
Yes
|
--rng_device-rate-period
|
int
|
Specifies the duration of a period in milliseconds. If specified,
--rng_device-rate-bytes must be specified as well.
|
No
|
Yes
|
Yes
|
--rng_device-source
|
string
|
The source of the random number generator. Specify either
random or hwrng .
|
No
|
Yes
|
Yes
|
--console-enabled
|
boolean
|
Set to
true to enable the VirtIO console device feature.
|
No
|
Yes
|
Yes
|
--cpu-mode
|
string
|
Defines the CPU mode. Specify
custom , host_model , or host_passthrough .
|
No
|
Yes
|
Yes
|
--cpu-topology-sockets
|
int
|
The number of CPU sockets available to the virtual machine.
|
No
|
Yes
|
Yes
|
--cpu_shares
|
int
|
The level of CPU resources a virtual machine 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.
|
No
|
Yes
|
Yes
|
--placement_policy-affinity
|
string
|
The migration affinity for each virtual machine. Specify
migratable , user_migratable , or pinned .
|
No
|
Yes
|
Yes
|
--placement_policy-host-id|name
|
string
|
A reference to the preferred host for migration affinity.
|
No
|
Yes
|
Yes
|
--origin
|
string
|
The virtual machine's origin. Specify
rhev , vmware , or xen .
|
No
|
Yes
|
Yes
|
--os-kernel
|
string
|
A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--disks-clone
|
boolean
|
Defines whether to clone the disk from the defined
template .
|
No
|
Yes
|
No
|
--disks-disk
|
collection
|
References to disks attached to the virtual machine.
|
No
|
Yes
|
Yes
|
--tunnel_migration
|
boolean
|
Set to
true to enable data transport over a libvirt daemon. A tunneled transport uses a stronger encryption algorithm but increases the data load during transport.
|
No
|
Yes
|
Yes
|
--migration_downtime
|
int
|
Defines the maximum number of milliseconds that the virtual machine can be down during live migration.
|
No
|
Yes
|
Yes
|
--virtio_scsi-enabled
|
boolean
|
Set to
true to allow attaching a VirtIO console device to the virtual machine.
|
No
|
Yes
|
Yes
|
--soundcard_enabled:
|
boolean
|
Set to
true to enable sound cards.
|
No
|
Yes
|
Yes
|
--payloads-payload
|
collection
|
Defines content to send to the virtual machine upon booting.
|
No
|
Yes
|
Yes
|
--initialization-configuration-type
|
string
| Defines the virtual machine format. Accepts only ovf . |
No
|
Yes
|
Yes
|
--initialization-configuration-data
|
string
|
This parameter must match the
--initialization-configuration-type parameter. Accepts only ovf .
|
No
|
Yes
|
Yes
|
--cpu-cpu_tune-vcpu_pin
|
collection
|
Defines which virtual CPUs of a virtual machine to pin to the physical CPUs of a host.
|
No
|
Yes
|
Yes
|
--serial_number-policy
|
string
|
Defines the serial number policy for the virtual machine template. Specify
host , vm , or custom . If custom is used, also define the serial number value using --serial_number-value .
|
No
|
Yes
|
Yes
|
--serial_number-value
|
string
|
Defines the serial number for the virtual machine template.
|
No
|
Yes
|
Yes
|
--bios-boot_menu-enabled
|
boolean
|
Set to
true to enable boot menu.
|
No
|
Yes
|
Yes
|
--numa_tune_mode
|
string
|
Defines how to allocate memory for the domain process on a NUMA host. Specify
interleave , strict , or preferred . If no value is given, the parameter defaults to strict .
|
No
|
Yes
|
Yes
|
--cpu_profile-id
|
string
|
Defines the CPU profile to use. Use the
list cpuprofiles command to retrieve a full list of CPU profile IDs.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
--os-boot
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
boot.dev
|
string
|
The boot device for the virtual machine template. Specify
cdrom , hd , or network .
|
--custom_properties-custom_property
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property value.
|
--sso-methods-method
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
method.id
|
string
|
The single sign-on method used:
GUEST_AGENT .
|
--disks-disk
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
disk.id
|
string
|
A reference to a virtual disk.
|
storage_domains.storage_domain
|
collection
|
Defines a set of sub-parameters for the disk's storage domain.
|
--payloads-payload
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
payload.type
|
string
|
Payload delivery type. Specify either
cdrom or floppy .
|
payload.file.name
|
string
|
The payload file name and location on the root file system of the virtual machine.
|
payload.file.content
|
string
|
The content to deliver to the file.
|
--cpu-cpu_tune-vcpu_pin
parameter is a collection that uses the sub-parameters in the following table.
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
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
vmpool
resource type groups all virtual machine pool resources in a Red Hat Virtualization environment.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--cluster-id|name
|
string
|
A reference to the cluster for the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--template-id|name
|
string
|
A reference to the template for the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--size
|
integer
|
The number of the virtual machines in the pool.
|
Yes
|
Yes
|
Yes
|
Example 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
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.
Name | Type | Description | Required | User Creatable | User Updatable |
---|---|---|---|---|---|
--name
|
string
|
The name of the VNIC profile.
|
Yes
|
Yes
|
Yes
|
--network-id
|
string
|
A reference to the logical network to which the profile will be applied.
|
Yes
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
--description
|
string
|
A description for the profile.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--port_mirroring
|
Boolean
|
Toggles whether port mirroring is used for the profile. The status is either
True or False . Default is False s
|
No
|
No
|
No
|
--custom_properties-custom_property
parameter is a collection that uses the sub-parameters in the following table.
Name | Type | Description |
---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property 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
Chapter 5. CLI Queries
5.1. Query Syntax
list
command uses the --query
attribute to perform server-side queries, which uses the same format as Red Hat Virtualization Manager search query language:
Collection | Criteria | Result |
---|---|---|
hosts | vms.status=up | Displays a list of all hosts running virtual machines that are up . |
vms | domain=qa.company.com | Displays a list of all virtual machines running on the specified domain. |
vms | users.name=mary | Displays a list of all virtual machines belonging to users with the user name mary . |
events | severity>normal sortby time | Displays the list of all events with severity higher than normal and sorted by the time element values. |
events | severity>normal sortby time desc | Displays the list of all events with severity higher than normal and sorted by the time element values in descending order. |
5.2. Wildcards
Example 5.1. Wildcard search query for name=vm*
[RHEVM shell (connected)]# list vms --query "name=vm*"
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"
v
and ending with 1
, such as vm1
, vr1
or virtualmachine1
.