Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Mail Systems
Eclipse Documentation

How To Guides
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Problem Solutions
Privacy Policy




Red Hat Enterprise Linux 9 Essentials Book now available.

Purchase a copy of Red Hat Enterprise Linux 9 (RHEL 9) Essentials

Red Hat Enterprise Linux 9 Essentials Print and eBook (PDF) editions contain 34 chapters and 298 pages

Preview Book

Chapter 19. Managing guests with virsh

virsh is a command line interface tool for managing guests and the hypervisor.
The virsh tool is built on the libvirt management API and operates as an alternative to the xm command and the graphical guest Manager(virt-manager). virsh can be used in read-only mode by unprivileged users. You can use virsh to execute scripts for the guest machines.
virsh command quick reference
The following tables provide a quick reference for all virsh command line options.
Command Description
help Prints basic help information
list Lists all guests
dumpxml Outputs the XML configuration file for the guest
create Creates a guest from an XML configuration file and starts the new guest
start Starts an inactive guest
destroy Forcibly stops a guest
define Creates a guest from an XML configuration file but does not start the new guest.
domid Displays the domain ID
domuuid Displays the UUID
dominfo Displays guest information
domname Displays the domain name.
domstate Displays the state of a guest
quit Quits the interactive terminal
reboot Reboots a guest
restore Restores a previously saved guest stored in a file
resume Resumes a paused guest
save Save the present state of a guest to a file
shutdown Gracefully shuts down a guest
suspend Pauses a guest
undefine Deletes all files associated with a guest
Table 19.1. virsh commands

The following virsh command options to manage guest and hypervisor resources:
Command Description
setmem Sets the allocated memory for a guest
setmaxmem Sets maximum memory limit for the hypervisor
setvcpus Changes number of virtual CPUs assigned to a guest
vcpuinfo Displays vCPU information about a guest
vcpupin Controls the vCPU affinity of a guest
Table 19.2. Resource management options

These are miscellaneous virsh options:
Command Description
version Displays the version of virsh
nodeinfo Outputs information about the hypervisor
Table 19.3. Miscellaneous options

Connecting to the hypervisor
Connect to a hypervisor session with virsh:
# virsh connect 
[hypervisor name or location]

Where <name> is the machine name of the hypervisor. To initiate a read-only connection, append the above command with -readonly.
Creating a virtual machine XML dump(configuration file)
Output a guest's XML configuration file with virsh:
virsh dumpxml 
[domain-id, domain-name or domain-uuid]

This command outputs the domain information (in XML) to stdout. You save the data by piping the output to a file.
virsh dumpxml 

The file guest.xml can then be used to recreate the guest (refer to Creating a guest from a configuration file. You can edit this XML configuration file to configure additional devices or to deploy additional guests. Refer to Section 26.1, “Using XML configuration files with virsh” for more information on modifying files created with virsh dumpxml.
An example of virsh dumpxml output:
# virsh dumpxml r5b2-mySQL01
<domain type='xen' id='13'>
		<cmdline>ro root=/dev/VolGroup00/LogVol00 rhgb quiet</cmdline>
		<interface type='bridge'>
			<source bridge='xenbr0'/>
			<mac address='00:16:3e:49:1d:11'/>
			<script path='vif-bridge'/>
		<graphics type='vnc' port='5900'/>
		<console tty='/dev/pts/4'/>
Creating a guest from a configuration file
Guests can be created from XML configuration files. You can copy existing XML from previously created guests or use the dumpxml option(refer to Creating a virtual machine XML dump(configuration file)). To create a guest with virsh from an XML file:
# virsh create 

Suspending a guest
Suspend a guest with virsh:
virsh suspend 
[domain-id, domain-name or domain-uuid]

When a domain is in a suspended state, it consumes system RAM but not processor resources. Disk and network I/O does not occur while the guest is suspended. This operation is immediate and the guest can be restarted with the resume(Resuming a guest) option.
Resuming a guest
Restore a suspended guest with virsh using the resume option:
virsh resume 
[domain-id, domain-name or domain-uuid]

This operation is immediate and the guest parameters are preserved for suspend and resume operations.
Save a guest
Save the current state of a guest to a file using the virsh command:
virsh save 
[domain-name] [domain-id or domain-uuid] [filename]

This stops the guest you specify and saves the data to a file, which may take some time given the amount of memory in use by your guest. You can restore the state of the guest with the restore(Restore a guest) option. Save is similar to pause, instead of just pausing a guest the present state of the guest is saved.
Restore a guest
Restore a guest previously saved with the virsh save command(Save a guest) using virsh:
virsh restore 

This restarts the saved guest, which may take some time. The guest's name and UUID are preserved but are allocated for a new id.
Shut down a guest
Shut down a guest using the virsh command:
virsh shutdown 
[domain-id, domain-name or domain-uuid]

You can control the behavior of the rebooting guest by modifying the on_shutdown parameter in the guest's configuration file file.
Rebooting a guest
Reboot a guest using virsh command:
virsh reboot 
[domain-id, domain-name or domain-uuid]

You can control the behavior of the rebooting guest by modifying the on_reboot parameter in the guest's configuration file file.
Forcing a guest to stop
Force a guest to stop with the virsh command:
virsh destroy 
[domain-id, domain-name or domain-uuid]

This command does an immediate ungraceful shutdown and stops any guest domain sessions (which could potentially lead to file corrupted file systems still in use by the guest). You should use the destroy option only when the guest is unresponsive. For para-virtualized guests, use the shutdown option(Shut down a guest) instead.
Getting the domain ID of a guest
To get the domain ID with virsh:
virsh domid 
[domain-name or domain-uuid]

Getting the domain name of a guest
To get the domain name with virsh:
virsh domname [domain-id or domain-uuid]
Getting the UUID of a guest
To get the UUID with virsh :
virsh domuuid [domain-id or domain-name]
An example of virsh domuuid output:
# virsh domuuid r5b2-mySQL01
Displaying guest Information
Using virsh with the guest's domain ID, domain name or UUID you can display information on the specified guest:
virsh dominfo 
[domain-id, domain-name or domain-uuid]

This is an example of virsh dominfo output:
# virsh dominfo r5b2-mySQL01
id:             13
name:           r5b2-mysql01
uuid:           4a4c59a7-ee3f-c781-96e4-288f2862f011
os type:      	linux
state:          blocked
cpu(s):         1
cpu time:     	11.0s
max memory:     512000 kb
used memory:    512000 kb
Displaying hypervisor information
To display hypervisor information virsh:
virsh nodeinfo
An example of virsh nodeinfo output:
CPU model                    x86_64
CPU (s)                      8
CPU frequency                2895 Mhz
CPU socket(s)                2      
Core(s) per socket           2
Threads per core:            2
Numa cell(s)                 1
Memory size:                 1046528 kb
This displays the node information and the machines that support the virtualization process.
Displaying the guests
To display the guest list and their current states with virsh:
virsh list
Other options available include:
the --inactive option which lists inactive domains (domains that have been defined but are not currently active), and
the --all domain lists all domains, whether active or not. Your output should resemble the this example:
 Id Name                 State
  0 Domain-0             running
  1 Domain202            paused
  2 Domain010            inactive
  3 Domain9600           crashed
The output from virsh list is categorized as one of the six states(listed below).
  • The running(r) state refers to domains which are currently active on a CPU.
  • Domains listed as blocked(b) are blocked, and are not running or runnable. This is caused by a domain waiting on I/O (a traditional wait state) or domains in a sleep mode.
  • The paused(p) state lists domains that are paused. This usually occurs after an administrator uses xm pause or virsh suspend. When a domain is paused it consumes memory and other resources but it is ineligible for scheduling and CPU resources from the hypervisor.
  • The shutdown(s) state is for domains in the process of shutting down. The guest operating system is sent a shutdown signal and should be in the process of stopping its operations gracefully. This may not work with all guest operating systems as some do not read these signals correctly.
  • Domains in the dying(d) state are in is in process of dying, which is a state where the domain has not completely shut-down or crashed.
  • crashed(c) domains have failed while running and are no longer running. The domain has crashed, which is always a violent ending. This state can only occur if the domain has been configured not to restart on crash. Refer to the domain configuration manual page( man xmdomain.cfg) for more information.
Displaying virtual CPU information
To display virtual CPU information from a guest with virsh:
virsh vcpuinfo [domain-id, domain-name or domain-uuid]
An example of virsh vcpuinfo output:
# virsh vcpuinfo r5b2-mySQL01
VCPU:           0
CPU:            0
State:          blocked
CPU time:       0.0s
CPU Affinity:   yy
Configuring virtual CPU affinity
To configure the affinity of virtual CPUs with physical CPUs:
virsh vcpupin [domain-id, domain-name or domain-uuid] [vcpu] , [cpulist]
Where [vcpu] is the virtual VCPU number and [cpulist] lists the physical number of CPUs.
Configuring virtual CPU count
To modify a domain's number of CPUs with virsh:
virsh setvcpus 
[domain-name, domain-id or domain-uuid] [count]

The new count value cannot exceed the count above the amount specified when the guest was created.
Configuring memory allocation
To modify a guest's memory allocation with virsh :
virsh setmem [domain-id or domain-name]  [count]
You must specify the [count] in kilobytes. The new count value cannot exceed the amount you specified when you created the guest. Values lower than 64 MB are unlikely to work with most guest operating systems. A higher maximum memory value will not affect the an active guest unless the new value is lower which will shrink the available memory usage.
Managing virtual networks
This section covers managing virtual networks with the virsh command. To list virtual networks:
virsh net-list
This command generates output similar to:
[root@domain ~]# virsh net-list
Name                 State      Autostart
default              active     yes      
vnet1	             active     yes      
vnet2	             active     yes
To view network information for a specific virtual network:
virsh net-dumpxml [vnet name]
This displays information about a specified virtual network in XML format:
# virsh net-dumpxml vnet1
  <forward dev='eth0'/>
  <bridge name='vnet0' stp='on' forwardDelay='0' />
  <ip address='' netmask=''>
      <range start='' end='' />
Other virsh commands used in managing virtual networks are:
  • virsh net-autostart [network name] — Autostart a network specified as [network name]
  • virsh net-create [XML file] — generates and starts a new network using an existing XML file.
  • virsh net-define [XML file] — generates a new network device from an existing XML file without starting it.
  • virsh net-destroy [network name] — destroy a network specified as [network name] .
  • virsh net-name [network UUID] — convert a specified [network UUID] to a network name.
  • virsh net-uuid [network name — convert a specified [network name] to a network UUID.
  • virsh net-start [name of an inactive network] — starts an inactive network.
  • virsh net-undefine [name of an inactive network] — removes the definition of an inactive network.

  Published under the terms of the GNU General Public License Design by Interspire