Virtualization Virsh Lead image: © Sellingpix,
© Sellingpix,

Remotely controllingvirtual machines with virsh

Engine Room toBridge

With the command-line tool virsh, a part of the libvirt library, you can query virtual machines to discover their state of health, launch or shut down virtual machines, and perform other tasks – all of which can be conveniently scripted. By Tim Schürmann

The libvirt project has set the objective of creating a standardized management center for a variety of virtualization solutions and hypervisors [1]. Many administrators in production environments only know it as the colorful virt-manager front end, which manages virtual machines on Qemu/KVM. However, virt-manager isn't even part of the libvirt project, which only provides a handful of command-line programs, one of which is the overlooked but essential virsh.

Building Blocks

Like any other libvirt tool, virsh relies on the libvirt library, which in turn provides the interface to the libvirtd daemon. The daemon runs on the machine hosting the virtual machines, also known as a node, and controls the hypervisor operations (Figure 1), making libvirtd basically indispensable to administrators.

Virsh passes the commands on to the other libvirt package components.
Figure 1: Virsh passes the commands on to the other libvirt package components.

After installing libvirt, you can immediately start using virsh – at least normally you can. Many distributions, two of them being Debian and Ubuntu, have offloaded the libvirt tools into a separate package. In this case, you need to install virsh by installing the libvirt-bin package: The counterpart on openSUSE goes by the name of libvirt-client.

To make sure the program in place on your disk is working, just type virsh version. If you see an error message, you need to become root and try your luck again. If virsh tells you something about a connection error, you need to enable the libvirtd. Most distributions will launch the daemon automatically after you install the libvirt packages, but some manual attention is required in some cases – on openSUSE 11.3, you would issue the rclibvirtd start command, for example. After doing this, virsh version should output the version numbers of the components involved and then wait for more commands.


Typing the following line:

virsh -c qemu:///system list --all

connects Virsh (-c for connect) with Qemu on the current system and lists all existing virtual machines, including those running and paused (--all). The cryptic qemu:///system is a Uniform Resource Identifier (URI) that allows virsh to state the virtualization solution in use. In this example, it is Qemu/KVM. Table 1 lists other supported URIs. Libvirt, and thus also virsh, can basically control virtual machines on Qemu/KVM, Xen, LXC, OpenVZ, VirtualBox, Microsoft Hyper-V, and VMware ESX, GSX, Workstation, and Player.

Tabelle 1: Virsh-Supported URIs














Microsoft Hyper-V


VMware ESX


VMware GSX


VMware Player


VMware Workstation

For this to work, libvirt needs to be built with the corresponding support enabled (or the corresponding drivers in place). The libvirt packages provided by some distributions are versions that can only cooperate with Qemu/KVM. The following examples thus focus on this virtualization solution.

If the virtual machine is running on a remote machine, you need to integrate the IP address or domain name into the URI. The command

virsh -c qemu:// list --all

lists all the virtual machines running on host If needed, you can stipulate the connection type:

virsh -c qemu+ssh://admin list --all

Here, virsh opens a connection to the host named and the user admin using a secure SSH connection to do so. For more examples of the URI structure, see the libvirt hypervisor web page [2].

To save typing, you can store the URI in the VIRSH_DEFAULT_CONNECT_URI environment variable and then do without it for future calls to virsh:

export VIRSH_DEFAULT_CONNECT_URI=qemu:///system
virsh list --all

The following provides information on the debian virtual machine (see Figure 2),

Two virtual machines are running on this host; the machine named debian only uses one CPU, although the physical processor could give it more. The information is sent to standard output and can be dissected with grep.
Figure 2: Two virtual machines are running on this host; the machine named debian only uses one CPU, although the physical processor could give it more. The information is sent to standard output and can be dissected with grep.
virsh -c qemu:///system dominfo debian


virsh -c qemu:///system nodeinfo

returns the current status of the guest.


The following command uses ACPI to shut down a virtual machine named debian, which is currently twiddling its thumbs:

virsh -c qemu://system shutdown debian

If the virtual machine doesn't respond, you can also force this by issuing the

virsh -c qemu:///system destroy debian

command. To view and modify the configuration of the virtual machine, whichever way it was switched off, you can type:

virsh -c qemu:///system edit debian

This launches Vim and opens the matching XML file. If the Vim editor is too spartan for your liking, you can dump the XML into a text file with,

virsh -c qemu:///system dumpxml debian >/tmp/debian.xml

modify the file manually, and use it to create a new virtual machine:

virsh -c qemu:///system create /tmp/debian.xml

At first glance, this kind of management might seem more complex than a graphical interface; however, you can add the commands to a (Bash) script and thus semi-automatically start a number of virtual machines or change their configurations, retrospectively.

Tweaking and Tinkering

To modify memory use and the number of processors available to a virtual machine, you don't need to access the XML file. Instead, each tweak has a practical and short command. For example,

virsh -c qemu:///system setmem debian 250000

assigns 250,000KB of memory to the debian virtual machine, and the following command assigns two virtual CPUs:

virsh -c qemu:///system setvcpus debian 2

The migrate command moves a virtual machine to another host:

virsh -c qemu:///system migrate  --livedebian  qemu://

This moves the debian virtual machine to the machine, with --live forcing the migration.


Virsh also supports an interactive mode. If you leave out the parameters, you automatically enter this mode, as in:

virsh -c qemu///system

In the virsh shell, you also can run the commands mentioned previously, such as list --all; quit takes you back to the operating system shell. If needed, you can even type

virsh -c qemu:///system console debian

to access the console on an active virtual machine.


Although virsh syntax can be difficult to grasp, you will find yourself integrating the tool into your own Bash scripts after a short learning curve. After doing so, a short status report on your active virtual machines is a one-liner – and much quicker than clicking you way through the statistics tabs in virt-manager. Virsh supports more even commands (Table 2) and actions (see the "Top Tool!" box). For an initial overview, just type virsh help or consult the incomplete virt-top reference [3].

Tabelle 2: Virsh Commands at a Glance



list --all

Lists all virtual machines.

list --inactive

Lists all inactive virtual machines.

dominfo VM

Returns information about the virtual machine named VM.


Returns information about the guest system.

edit VM

Changes the settings for the named virtual machine.

start VM

Starts the named virtual machine.

shutdown VM

Shuts down the named virtual machine.

destroy VM

Kills the named virtual machine.

suspend VM

Pauses the named virtual machine.

resume VM

Resumes the named virtual machine.

console VM

Activates the management console for the named virtual machine.

dumpxml VM

Sends the XML configuration file of the named virtual machine to standard output.

create vm.xml

Creates a new virtual machine from information in the vm.xml configuration file.

undefine VM

Deletes the entire named virtual machine.

setmem VM memory

Allots mem kilobytes of memory to the named virtual machine.

setvcpus VM cpu

Assigns cpu virtual CPUs to the named virtual machine.

migrate VM URI

Migrates the named virtual machine to the URI guest system.