Authors:

Feature pages are design documents that developers have created while collaborating on oVirt.

Most of them are outdated, but provide historical design context.

They are not user documentation and should not be treated as such.

Documentation is available here.

ovirt-shell is Deprecated: It uses the v3 REST API, and lacks all features available since oVirt 4.0. Consider using Ansible as a replacement for automation purposes.

CLI

oVirt CLI is a dynamic, runtime interface discovering command line interface for the oVirt engine

Concepts

  • dynamic interface that can work against any version of sdk discovering it at runtime
  • Interactive prompt
  • Smart auto-completion
  • Smart help
  • Generic interface (list, show, add, update, action verbs).
  • Self descriptive.

Usage

Help

syntax

  • note help is dynamically created for each command respectively
    help
    

    or

    help <command> [arguments] [options]
    

Auto-Completion

available commands

[oVirt shell (connected)]# <TAB><TAB>
EOF         clear       console     remove      echo        help        ping
show        update      action      connect     add         disconnect
exit        list        shell       status

available options for specific command

[oVirt shell (connected)]# add <TAB><TAB>
cdrom          datacenter     group          network        permission     role           storagedomain  template       vm
cluster        disk           host           nic            permit         snapshot       tag            user           vmpool

available options for command on specific resource

[oVirt shell (connected)]# add vm <TAB><TAB>
cluster-id                               display-type                             os-boot-dev                              template-id
cluster-name                             domain-name                              os-cmdline                               template-name
cpu-topology-cores                       high_availability-enabled                os-initRd                                timezone
cpu-topology-sockets                     high_availability-priority               os-kernel                                type
custom_properties-custom_property        memory                                   os-type                                  usb-enabled
description                              name                                     placement_policy-affinity
display-monitors                         origin                                   stateless

available options for command on specific sub-resource

[oVirt shell (connected)]# add nic --vm-identifier xxx `<TAB><TAB>`
interface     mac-address   name          network-id    network-name
  • note typing beginning of the option name and then hitting <TAB>, will convert

option to appropriate option format adding prefix or suffix.

Connect

get help for connect

[mpastern@ovirt-engine-cli (master)]$ ovirt-shell --help

Usage: ovirt-shell [options]
       ovirt-shell [options] command...
This program is a command-line interface to oVirt Virtualization.
Options:
 -h, --help            show this help message and exit
 -l URL, --url=URL     specifies the API entry point URL
                       (http[s]://server[:port]/api)
 -u USERNAME, --username=USERNAME
                       connect as this user
 -K KEY_FILE, --key-file=KEY_FILE
                       specify client PEM key-file
 -C CERT_FILE, --cert-file=CERT_FILE
                       specify client PEM cert-file
 -A CA_FILE, --ca-file=CA_FILE
                       specify server CA cert-file
 -I, --insecure        allow connecting to SSL sites without certificates
 -F, --filter          enables user permission based filtering
 -P PORT, --port=PORT  specify port
 -T TIMEOUT, --timeout=TIMEOUT
                       specify timeout
 -c, --connect         automatically connect
 -f FILE, --file=FILE  read commands from FILE instead of stdin

connect from ovirt-shell

[mpastern@ovirt-engine-cli (master)]$ ovirt-shell

 ++++++++++++++++++++++++++++++++++++++++++

           Welcome to oVirt shell

 ++++++++++++++++++++++++++++++++++++++++++

[oVirt shell (disconnected)]# connect --url "http://server:8080/api" --user "user@domain" --password 'password'

==========================================
>>> connected to oVirt manager 3.2.0.0 <<<
==========================================

[oVirt shell (connected)]#

connect from linux shell

configuration file based login
  1. vi ~/.ovirtshellrc

  2. set args:

[ovirt-shell]
username = user@domain
url = http[s]://server[:port]/api
#insecure = False
#filter = False
#timeout = -1
password = ******
  • NOTE: if url/username/password is not configured/commented in .ovirtshellrc and ovirt-shell executed in auto-connect mode (ovirt-shell -c/--connect), you will be prompted to specify it upon login
  1. run ovirt-shell
[mpastern@ovirt-engine-cli (master)]$ ovirt-shell -c

==========================================
>>> connected to oVirt manager 3.2.0.0 <<<
==========================================
++++++++++++++++++++++++++++++++++++++++++

       Welcome to oVirt shell

++++++++++++++++++++++++++++++++++++++++++
[oVirt shell (connected)]#
cli options based login
[mpastern@ovirt-engine-cli (master)]$ ovirt-shell -c -l "http://server:8080/api" -u "user@domain"
Password: ****
==========================================
>>> connected to oVirt manager 3.1.0.0 <<<
==========================================

++++++++++++++++++++++++++++++++++++++++++

     Welcome to oVirt shell

++++++++++++++++++++++++++++++++++++++++++


[oVirt shell (connected)]#

Querying

list

list resources
[oVirt shell (connected)]# list vms

id         : aa849efc-4194-4b00-b274-ab32d4c222c9
name       : aa

id         : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name       : demo

[oVirt shell (connected)]# list vms --show-all

id                        : aa849efc-4194-4b00-b274-ab32d4c222c9
name                      : aa
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-02-16T20:00:50.859+02:00
display-monitors          : 1
display-type              : spice
high_availability-enabled : False
high_availability-priority: 1
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : ovirt
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T13:36:27.880Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True

id                        : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name                      : demo
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-02-16T11:15:56.014+02:00
display-address           : 10.35.1.127
display-monitors          : 1
display-type              : vnc
high_availability-enabled : False
high_availability-priority: 1
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : ovirt
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T13:36:27.887Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
  • notice: --show-all option extends listed entities (default mode is collapsed).
list resources using oVirt query engine filtering
[oVirt shell (connected)]# list vms --query "name=demo"

id         : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name       : demo
list resources using client side filtering
[oVirt shell (connected)]# list vms --kwargs "memory=1073741824"

id         : aa849efc-4194-4b00-b274-ab32d4c222c9
name       : aa

id         : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name       : demo

id         : f4a51ae1-4f31-45ee-ab6d-d5965e3bcf71
name       : iscsi_desktop
description: myvm

id         : fea05ded-c246-4e51-885e-fef33a7ef2ad
name       : pythond_sdk_poc2
list sub-resources
[oVirt shell (connected)]# list disks --vm-identifier nfs_desktop

id         : 889bad90-6efa-42c5-a545-d0ce2033218d
name       : Disk 2

id         : 7a014754-a10e-42b3-91ff-6a325043f9b0
name       : Disk 4

id         : 4d267464-e126-45fa-8e42-381e2f82354a
name       : Disk 1

id         : b007747c-ad99-4c03-a318-42ad502afb23
name       : Disk 3

[oVirt shell (connected)]# list nics --vm-identifier demo

id         : fbc1f30f-7c21-44e7-9c0a-7e4ffb57fcb4
name       : nic3

id         : 1f295a64-0a4a-4fba-928d-162b458503a5
name       : nic1

id         : 7ba3c79c-c619-422f-9035-6b5c8e5ea9e6
name       : nic2
  • note: ether id or name can be used as --resource-identifier
list sub-resources using client side filtering
[oVirt shell (connected)]# list disks --vm-identifier nfs_desktop --kwargs "name=Disk 3"

id         : b007747c-ad99-4c03-a318-42ad502afb23
name       : Disk 3

[oVirt shell (connected)]# list vms --kwargs "usb-enabled=True"

id         : aa849efc-4194-4b00-b274-ab32d4c222c9
name       : aa

id         : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name       : demo
  • note: ether id or name can be used as –resource-identifier

show

show resource
[oVirt shell (connected)]# show vm demo

id                        : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6
name                      : demo
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-02-16T11:15:56.014+02:00
display-address           : 10.35.1.127
display-monitors          : 1
display-type              : vnc
high_availability-enabled : False
high_availability-priority: 1
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : ovirt
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T13:55:15.443Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True

[oVirt shell (connected)]# show vm --name nfs_desktop

id                        : e0adee2b-2c95-483e-8259-2d8b29aa414d
name                      : nfs_desktop
description               : updated_desc
cluster-id                : f16a5ea6-0b88-11e1-9844-bb5eb66ca68b
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2011-11-10T14:12:09.379+02:00
display-address           : 0
display-monitors          : 1
display-type              : spice
high_availability-enabled : False
high_availability-priority: 1
memory                    : 536870912
memory_policy-guaranteed  : 536870912
origin                    : rhev
os-boot-dev               : hd
os-type                   : rhel_6x64
placement_policy-affinity : migratable
start_time                : 2012-02-29T13:55:56.448Z
stateless                 : False
status-state              : down
template-id               : 00000000-0000-0000-0000-000000000000
type                      : desktop
usb-enabled               : True
show resource using client side filtering
[oVirt shell (connected)]# show vm --id f4a51ae1-4f31-45ee-ab6d-d5965e3bcf71

id                        : f4a51ae1-4f31-45ee-ab6d-d5965e3bcf71
name                      : iscsi_desktop
description               : myvm
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-01-04T13:27:05.266+02:00
display-monitors          : 4
display-type              : spice
high_availability-enabled : True
high_availability-priority: 7
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : rhev
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T13:57:07.096Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True
show sub-resource
[oVirt shell (connected)]# show nic nic1 --vm-identifier demo

id         : 1f295a64-0a4a-4fba-928d-162b458503a5
name       : nic1
interface  : virtio
mac-address: 00:1a:4a:16:01:68
network-id : d85a5cb2-057b-40ec-8d9c-b4ee6a7646c4
vm-id      : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6

Add

add resource

[oVirt shell (connected)]# add vm --name demo2 --template-name iscsi_desktop_tmpl --cluster-name Default_iscsi

id                        : dd981334-afb7-4142-a880-536bb8aef53f
name                      : demo2
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_status-state     : pending
creation_time             : 2012-02-29T16:01:57.896+02:00
display-monitors          : 1
display-type              : spice
high_availability-enabled : False
high_availability-priority: 1
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : ovirt
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T14:02:01.533Z
stateless                 : False
status-state              : image_locked
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True

[oVirt shell (connected)]# add datacenter --name mydc --storage_type nfs --version-major 3 --version-minor 1

id                              : 4c490b43-e681-49d8-958c-9300787982eb
name                            : mydc
status-state                    : uninitialized
storage_type                    : nfs
supported_versions-version-major: 3
supported_versions-version-minor: 1
version-major                   : 3
version-minor                   : 1

add sub-resource

[oVirt shell (connected)]# add nic --vm-identifier demo2 --network-name engine --name mynic

id         : a211d8bb-8abb-429b-8d36-fc4eb44b6ea8
name       : mynic
interface  : virtio
mac-address: 00:1a:4a:16:01:5a
network-id : d85a5cb2-057b-40ec-8d9c-b4ee6a7646c4
vm-id      : dd981334-afb7-4142-a880-536bb8aef53f

Remove

remove resource

[oVirt shell (connected)]# remove vm aa

remove sub-resource

[oVirt shell (connected)]# remove disk "Disk 1" --vm-identifier demo2
  • note: ether id or name can be used as –resource-identifier

Update

  • note: You have to quote the description if it contains spaces. E.g. “iscsi_desktop desc”

update resource

[oVirt shell (connected)]# update vm iscsi_desktop --description iscsi_desktop_desc

id                        : f4a51ae1-4f31-45ee-ab6d-d5965e3bcf71
name                      : iscsi_desktop
description               : iscsi_desktop_desc
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-01-04T13:27:05.266+02:00
display-monitors          : 4
display-type              : spice
high_availability-enabled : True
high_availability-priority: 7
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : rhev
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T14:08:15.353Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True

[oVirt shell (connected)]# update vm iscsi_desktop --display-monitors 2 --description test1

id                        : f4a51ae1-4f31-45ee-ab6d-d5965e3bcf71
name                      : iscsi_desktop
description               : test1
cluster-id                : e8861726-0b88-11e1-bd8c-27fb0a7aaa76
cpu-topology-cores        : 1
cpu-topology-sockets      : 1
creation_time             : 2012-01-04T13:27:05.266+02:00
display-monitors          : 2
display-type              : spice
high_availability-enabled : True
high_availability-priority: 7
memory                    : 1073741824
memory_policy-guaranteed  : 1073741824
origin                    : rhev
os-boot-dev               : hd
os-type                   : unassigned
placement_policy-affinity : migratable
start_time                : 2012-02-29T14:11:13.357Z
stateless                 : False
status-state              : down
template-id               : 9c42b69e-daa3-48d7-bf97-779603892f15
type                      : desktop
usb-enabled               : True

update sub-resource

[oVirt shell (connected)]# update nic nic1 --vm-identifier demo --interface virtio

id         : 1f295a64-0a4a-4fba-928d-162b458503a5
name       : nic1
interface  : virtio
mac-address: 00:1a:4a:16:01:68
network-id : d85a5cb2-057b-40ec-8d9c-b4ee6a7646c4
vm-id      : 7b4ebc3f-40ba-4eb3-94ef-ca222d62fbe6

Action

action on resource

[oVirt shell (connected)]# action vm demo start --vm-display-type vnc --async true
error:
status: 400
reason: Bad Request
detail: [Cannot run VM. Low disk space on relevant Storage Domain.]

action on sub-resource

[oVirt shell (connected)]# action nic bond0 attach --host-identifier grey-vdsa
error:
status: 400
reason: Bad Request
detail: Action [network.id|name] required for attach

Console

connect to vm using vm name

console 'my_vm'

connect to vm using vm id

console '7dff8517-7007-42cd-9cf7-b7a13a9d96b7'

Scripting

Writing a script

Format

no special format, just commands in plain text

less /home/mpastern/script
--------------------------

list vms
show vm test | grep status
list vms --query "name=test*" --show-all | grep status
list clusters
list datacenters
...

Executing script

From linux shell
[mpastern@lp /]#  ovirt-shell -f /home/mpastern/script
From ovirt shell
[oVirt shell (connected)]# file /home/mpastern/script

Examples

Run all vms
The script
  1. the script (less run_all_vms.txt) will look like:
list vms | grep name | sed s/'name       :'/'action vm'/ | sed -e 's/$/ start/' > /home/mpastern/new_script_to_run
       file /home/mpastern/new_script_to_run
  1. run the script
[RHEVM shell (connected)]# file /home/mpastern/run_all_vms
Explanations
  1. run rhevm command and process the output saving it in to temp script new_script_to_run
list vms | grep name | sed s/'name       :'/'action vm'/ | sed -e 's/$/ start/' > /home/mpastern/new_script_to_run
  1. invoke temp script internally at runtime
file /home/mpastern/new_script_to_run

Tweaks

disable pagination

at /home/user/.ovirtshellrc change autopage to False

Deployment

pypi

http://pypi.python.org/pypi/ovirt-shell

# easy_install ovirt-shell

rpm

To build rpm and install it, from ovirt-engine-cli repo:

# yum install -y rpm-build python-devel python-setuptools python-kitchen

# make rpm

# yum localinstall rpmtop/RPMS/noarch/ovirt-engine-cli-x.y-z.noarch.rpm

Because lxml is not yet packaged, please follow the instructions below to get lxml installed.

development deployment

For local install in site-packages, from ovirt-engine-cli repo:

# yum install python-ply libxml2-devel libxslt-devel pexpect python-kitchen
# python setup.py develop

That will install lxml, because EPEL’s python-lxml is not yet up to the version required by CLI.

  • note: both deployment procedures require super-user permissions

TODO list

Bugzila

Maintainers

Michael Pasternak: mishka8520@yahoo.com, Juan Hernandez: juan.hernandez@redhat.com