8 Linux virsh subcommands for managing VMs on the command line

The virtual shell, or virsh, is a flexible command-line utility for managing virtual machines (VMs) controlled by libvirt, which is a toolkit and API to manage virtualization platforms. It's the default management tool for Linux kernel-based virtual machines (KVMs), and it also supports Xen, VMware, and other platforms.

The virsh command allows you to manage VMs interactively or in batch. It's also helpful for controlling VMs from the Linux shell and integrates with scripts or automation tools. By using virsh, you can quickly connect to a server using secure shell (SSH) and perform operations on your VMs without access to a graphical interface.

When you run virsh without any options, it tries to connect to a local hypervisor. For Linux, the default connection points to a local QEMU system to manage local KVM machines. You can also connect to a remote hypervisor by using the option -c or --connect and specifying the Uniform Resource Identifier (URI) of the remote hypervisor using libvirt's syntax. For more information, consult libvirt's URI specification.

By default, virsh provides hundreds of subcommands and options that allow you to manage every aspect of your virtualization platform or VMs. In this article, I'll share the eight virsh subcommands I use most often. Due to the nature of daily work, most of these subcommands apply directly to VMs (or domains in libvirt terminology) but virsh also has commands to manage the platform itself, such as adding storage pools, networks, and more.

virsh list

virsh list is a basic command that lists all running domains (VMs). You can also list all configured VMs by adding the --all option. This is useful if you want to see all VMs configured in the target hypervisor that you can use on subsequent commands. For example, to list all available virtual machines on a local Linux KVM hypervisor:

# virsh list --all
 Id   Name          State
------------------------------
 3    rh8-vm01      running
 -    crc           shut off
 -    rh8-tower01   shut off

You can use the ID or domain name as input for subsequent commands.

virsh start / reboot / shutdown

Although they are different, I've grouped the start, reboot, and shutdown subcommands because they perform the same basic operation of managing the VM's power state.

To shut down the VM rh8-vm01 (from the list command above):

# virsh shutdown rh8-vm01 
Domain 'rh8-vm01' is being shutdown

# virsh list
 Id   Name   State
--------------------

You can start it up again using the start subcommand:

# virsh start rh8-vm01 
Domain 'rh8-vm01' started

# virsh list
 Id   Name       State
--------------------------
 4    rh8-vm01   running

By using these subcommands, you can quickly start, reboot, or shut down a VM without having to fire up a heavy graphical application.

[ You might also be interested in learning how to edit sshd_config using a Bash script. ]

virsh dumpxml

The dumpxml subcommand dumps the XML configuration for a given domain. You can use it to export the configuration to a file to make changes to an existing VM or use it as a template to create another VM with a similar configuration. By default, it dumps the configuration to STDOUT, so redirect it to a file using shell redirect operators > to save to a file:

# virsh dumpxml rh8-vm01                                                   
<domain type='kvm' id='4'>                                                                    
  <name>rh8-vm01</name>                                                                       
  <uuid>53b92c48-fce3-4464-95bf-6f442e988c94</uuid>
  <metadata>                                                                                  
    <libosinfo:libosinfo xmlns:libosinfo="http://libosinfo.org/xmlns/libvirt/domain/1.0">     
      <libosinfo:os id="http://redhat.com/rhel/8.4"/>                                         
    </libosinfo:libosinfo>                                                                    
  </metadata>                                                                                 
  <memory unit='KiB'>4194304</memory>                                                         
  <currentMemory unit='KiB'>4194304</currentMemory>    
  <vcpu placement='static'>2</vcpu>

... TRUNCATED OUTPUT ...
</domain>

You can use the XML output in scripts and automation tools to automate creating VMs.

virsh domifaddr

The domifaddr subcommand lists all the IP addresses configured for all virtual interfaces in a given VM. It's useful if the VM uses dynamic IP addresses, as it allows you to see the assigned IP address and connect to the VM:

# virsh domifaddr rh8-vm01 
 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 vnet6      52:54:00:c8:17:6e    ipv4         192.168.122.19/24
 vnet7      52:54:00:04:4d:ac    ipv4         192.168.64.210/24

By default, it lists the IP address leased by a DHCP server. If the hypervisor does not provide this information, you can also use the option --source agent to query the guest operating system (OS) directly via the virtualization agent. This requires a virtualization agent installed in the guest OS.

virsh edit

The edit subcommand opens the current XML configuration in your default $EDITOR, allowing you to make live modifications in a VM:

# virsh edit rh8-vm01
<domain type='kvm'>
  <name>rh8-vm01</name>
  <uuid>53b92c48-fce3-4464-95bf-6f442e988c94</uuid>
  <metadata>

... TRUNCATED OUTPUT ...
</domain>

After making your modifications, save the file to apply them. Some modifications may only take effect after a reboot.

virsh net-edit

The net-edit subcommand allows you to make live modifications to a virtual network configuration. It's helpful for changing options to a virtual network, such as associating a given MAC address to an IP address using standard libvirt DHCP configuration. It's a more advanced command that I use regularly. Like the edit subcommand, it opens the configuration file in your default $EDITOR for making changes. Save the file to apply changes:

# virsh net-edit --network hostonly
<network>
  <name>hostonly</name>
  <uuid>eddd03ff-5825-42ef-bc99-968bddf773c2</uuid>
  <bridge name='virbr1' stp='on' delay='0'/>
  <mac address='52:54:00:67:75:b1'/>
  <domain name='hostonly'/>
  <ip address='192.168.64.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.64.128' end='192.168.64.254'/>
    </dhcp>
  </ip>
</network>

You can also use other network-related subcommands starting with net- to manage different aspects of the hypervisor virtual networks.

[ Download now: A sysadmin's guide to Bash scripting. ]

What's next?

virsh is a powerful and flexible utility that allows you to manage every aspect of Linux virtualization and other platforms. For more information about it, consult the man pages or check its online documentation.