Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Chapter 14. Managing guest virtual machines with virsh

virsh is a command line interface tool for managing guest virtual machines and the hypervisor. The virsh command-line tool is built on the libvirt management API and operates as an alternative to the qemu-kvm command and the graphical virt-manager application. The virsh command can be used in read-only mode by unprivileged users or, with root access, full administration functionality. The virsh command is ideal for scripting virtualization administration.

14.1. Generic Commands

The commands in this section are generic because they are not specific to any domain.

14.1.1. help

$ virsh help [command|group] The help command can be used with or without options. When used without options, all commands are listed, one per line. When used with an option, it is grouped into categories, displaying the keyword for each group.
To display the commands that are only for a specific option, you need to give the keyword for that group as an option. For example: 
$ virsh help pool
 Storage Pool (help keyword 'pool'):
    find-storage-pool-sources-as   find potential storage pool sources
    find-storage-pool-sources      discover potential storage pool sources
    pool-autostart                 autostart a pool
    pool-build                     build a pool
    pool-create-as                 create a pool from a set of args
    pool-create                    create a pool from an XML file
    pool-define-as                 define a pool from a set of args
    pool-define                    define (but don't start) a pool from an XML file
    pool-delete                    delete a pool
    pool-destroy                   destroy (stop) a pool
    pool-dumpxml                   pool information in XML
    pool-edit                      edit XML configuration for a storage pool
    pool-info                      storage pool information
    pool-list                      list pools
    pool-name                      convert a pool UUID to pool name
    pool-refresh                   refresh a pool
    pool-start                     start a (previously defined) inactive pool
    pool-undefine                  undefine an inactive pool
    pool-uuid                      convert a pool name to pool UUID
Using the same command with a command option, gives the help information on that one specific command. For example: 
$ virsh help vol-path
  NAME
    vol-path - returns the volume path for a given volume name or key

  SYNOPSIS
    vol-path <vol> [--pool <string>]

  OPTIONS
    [--vol] <string>  volume name or key
    --pool <string>  pool name or uuid

14.1.2. quit and exit

The quit command and the exit command will close the terminal. For example: 
$ virsh exit
$ virsh quit

14.1.3. version

The version command displays the current libvirt version and displays information about where the build is from. For example: 
$ virsh version
Compiled against library: libvirt 1.1.1
Using library: libvirt 1.1.1
Using API: QEMU 1.1.1
Running hypervisor: QEMU 1.5.3

14.1.4. Argument Display

The virsh echo [--shell][--xml][arg] command echos or displays the specified argument. Each argument echoed will be separated by a space. by using the --shell option, the output will be single quoted where needed so that it is suitable for reusing in a shell command. If the --xml option is used the output will be made suitable for use in an XML file. For example, the command virsh echo --shell "hello world" will send the output 'hello world'.

14.1.5. connect

Connects to a hypervisor session. When the shell is first started this command runs automatically when the URI parameter is requested by the -c command. The URI specifies how to connect to the hypervisor. The most commonly used URIs are:
  • xen:/// - connects to the local Xen hypervisor.
  • qemu:///system - connects locally as root to the daemon supervising QEMU and KVM domains.
  • xen:///session - connects locally as a user to the user's set of QEMU and KVM domains.
  • lxc:/// - connects to a local Linux container.
Additional values are available on libvirt's website http://libvirt.org/uri.html.
The command can be run as follows: 
$ virsh connect {name|URI}
Where {name} is the machine name (host name) or URL (the output of the virsh uri command) of the hypervisor. To initiate a read-only connection, append the above command with --readonly. For more information on URIs refer to Remote URIs. If you are unsure of the URI, the virsh uri command will display it: 
$ virsh uri
qemu:///session

14.1.6. Displaying Basic Information

The following commands may be used to display basic information:
  • $ hostname - displays the hypervisor's host name
  • $ sysinfo - displays the XML representation of the hypervisor's system information, if available

14.1.7. Injecting NMI

The $ virsh inject-nmi [domain] injects NMI (non-maskable interrupt) message to the guest virtual machine. This is used when response time is critical, such as non-recoverable hardware errors. To run this command: 
$ virsh inject-nmi guest-1