Red Hat Training

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

20.36. Displaying Per-guest Virtual Machine Information

20.36.1. Displaying the Guest Virtual Machines

To display a list of active guest virtual machines and their current states with virsh: 
# virsh list
Other options available include:
  • --all - Lists all guest virtual machines. For example: 
    # virsh list --all
 Id Name                 State
----------------------------------
  0 Domain-0             running
  1 Domain202            paused
  2 Domain010            shut off
  3 Domain9600           crashed

    Note

    If no results are displayed when running virsh list --all, it is possible that you did not create the virtual machine as the root user.
    The virsh list --all command recognizes the following states:
    • running - The running state refers to guest virtual machines that are currently active on a CPU.
    • idle - The idle state indicates that the guest virtual machine is idle, and may not be running or able to run. This can occur when the guest virtual machine is waiting on I/O (a traditional wait state) or has gone to sleep because there was nothing else for it to do.
    • paused - When a guest virtual machine is paused, it consumes memory and other resources, but it is not eligible for scheduling CPU resources from the hypervisor. The paused state occurs after using the paused button in virt-manager or the virsh suspend command.
    • in shutdown - The in shutdown state is for guest virtual machines in the process of shutting down. The guest virtual machine is sent a shutdown signal and should be in the process of stopping its operations gracefully. This may not work with all guest virtual machine operating systems; some operating systems do not respond to these signals.
    • shut off - The shut off state indicates that the guest virtual machine is not running. This can be caused when a guest virtual machine completely shuts down or has not been started.
    • crashed - The crashed state indicates that the guest virtual machine has crashed and can only occur if the guest virtual machine has been configured not to restart on crash.
    • pmsuspended - The guest has been suspended by guest power management.
  • --inactive - Lists guest virtual machines that have been defined but are not currently active. This includes machines that are shut off and crashed.
  • --managed-save - Guests that have managed save state enabled will be listed as saved. Note that to filter guests with this option, you also need to use the --all or --inactive options.
  • --name - The command lists the names of the guests instead of the default table format. This option is mutually exclusive with the --uuid option, which only prints a list of guest UUIDs, and with the --table option, which determines that the table style output should be used.
  • --title - Lists also the guest title field, which typically contains a short description of the guest. This option must be used with the default (--table) output format. For example: 
    $ virsh list --title

Id       Name                                          State     Title
----------------------------------------------------------------------------
0        Domain-0                                      running   Mailserver1
2        rhelvm                                        paused
  • --persistent - Only persistent guests are included in a list. Use the --transient argument to list transient guests.
  • --with-managed-save - Lists guests that have been configured with a managed save. To list the guests without one, use the --without-managed-save option.
  • --state-running - Lists only guests that are running. Similarly, use --state-paused for paused guests, --state-shutoff for guests that are turned off, and --state-other lists all states as a fallback.
  • --autostart - Only auto-starting guests are listed. To list guests with this feature disabled, use the argument --no-autostart.
  • --with-snapshot - Lists the guests whose snapshot images can be listed. To filter for guests without a snapshot, use the --without-snapshot option.

20.36.2. Displaying Virtual CPU Information

To display virtual CPU information from a guest virtual machine with virsh: 
# virsh vcpuinfo {domain-id, domain-name or domain-uuid}
An example of virsh vcpuinfo output: 
# virsh vcpuinfo guest1
VCPU:           0
CPU:            2
State:          running
CPU time:       7152.4s
CPU Affinity:   yyyy

VCPU:           1
CPU:            2
State:          running
CPU time:       10889.1s
CPU Affinity:   yyyy

20.36.3. Pinning vCPU to a Host Physical Machine's CPU

The virsh vcpupin command assigns a virtual CPU to a physical one. 
# virsh vcpupin guest1
VCPU: CPU Affinity
----------------------------------
   0: 0-3
   1: 0-3
The vcpupin command can take the following arguments:
  • --vcpu requires the vcpu number
  • [--cpulist] string lists the host physical machine's CPU number(s) to set, or omit option to query
  • --config affects next boot
  • --live affects the running guest virtual machine
  • --current affects the current guest virtual machine state

20.36.4. Displaying Information about the Virtual CPU Counts of a Given Domain

The virsh vcpucount command requires a domain name or a domain ID 
# virsh vcpucount guest1
maximum      config         2
maximum      live           2
current      config         2
current      live           2
The vcpucount can take the following arguments:
  • --maximum get maximum cap on vcpus
  • --active get number of currently active vcpus
  • --live get value from running guest virtual machine
  • --config get value to be used on next boot
  • --current get value according to current guest virtual machine state
  • --guest count that is returned is from the perspective of the guest

20.36.5. Configuring Virtual CPU Affinity

To configure the affinity of virtual CPUs with physical CPUs: 
# virsh vcpupin domain-id vcpu cpulist
The domain-id parameter is the guest virtual machine's ID number or name.
The vcpu parameter denotes the number of virtualized CPUs allocated to the guest virtual machine.The vcpu parameter must be provided.
The cpulist parameter is a list of physical CPU identifier numbers separated by commas. The cpulist parameter determines which physical CPUs the VCPUs can run on.
Additional parameters such as --config effect the next boot, whereas --live effects the running guest virtual machine and --current affects the current guest virtual machine state.

20.36.6. Configuring Virtual CPU Count

Use this command to change the number of virtual CPUs active in a guest virtual machine. By default, this command works on active guest virtual machines. To change the inactive settings that will be used the next time a guest virtual machine is started, use the --config flag.To modify the number of CPUs assigned to a guest virtual machine with virsh: 
# virsh setvcpus {domain-name, domain-id or domain-uuid} count [[--config] [--live] | [--current]] [--maximum] [--guest]
For example: 
# virsh setvcpus guestVM1 2 --live
will set the number of vCPUs to guestVM1 to two and this action will be performed while the guestVM1 is running.

Important

Hot unplugging vCPUs is not supported on Red Hat Enterprise Linux 7.
The count value may be limited by host, hypervisor, or a limit coming from the original description of the guest virtual machine.
If the --config flag is specified, the change is made to the stored XML configuration for the guest virtual machine, and will only take effect when the guest is started.
If --live is specified, the guest virtual machine must be active, and the change takes place immediately. This option will allow hot plugging of a vCPU. Both the --config and --live flags may be specified together if supported by the hypervisor.
If --current is specified, the flag affects the current guest virtual machine state.
When no flags are specified, the --live flag is assumed. The command will fail if the guest virtual machine is not active. In addition, if no flags are specified, it is up to the hypervisor whether the --config flag is also assumed. This determines whether the XML configuration is adjusted to make the change persistent.
The --maximum flag controls the maximum number of virtual CPUs that can be hot-plugged the next time the guest virtual machine is booted. Therefore, it can only be used with the --config flag, not with the --live flag.
Note that count cannot exceed the number of CPUs assigned to the guest virtual machine.
If --guest is specified, the flag modifies the CPU state in the current guest virtual machine.

20.36.7. Configuring Memory Allocation

To modify a guest virtual machine's memory allocation with virsh: 
# virsh setmem {domain-id or domain-name} count
For example: 
# virsh setmem vr-rhel6u1-x86_64-kvm --kilobytes 1025000
You must specify the count in kilobytes. The new count value cannot exceed the amount you specified for the guest virtual machine. Values lower than 64 MB are unlikely to work with most guest virtual machine operating systems. A higher maximum memory value does not affect active guest virtual machines. If the new value is lower than the available memory, it will shrink possibly causing the guest virtual machine to crash.
This command has the following options
  • domain - specified by a domain name, id, or uuid
  • size - Determines the new memory size, as a scaled integer. The default unit is KiB, but a different one can be specified:
    Valid memory units include:
    • b or bytes for bytes
    • KB for kilobytes (103 or blocks of 1,000 bytes)
    • k or KiB for kibibytes (210 or blocks of 1024 bytes)
    • MB for megabytes (106 or blocks of 1,000,000 bytes)
    • M or MiB for mebibytes (220 or blocks of 1,048,576 bytes)
    • GB for gigabytes (109 or blocks of 1,000,000,000 bytes)
    • G or GiB for gibibytes (230 or blocks of 1,073,741,824 bytes)
    • TB for terabytes (1012 or blocks of 1,000,000,000,000 bytes)
    • T or TiB for tebibytes (240 or blocks of 1,099,511,627,776 bytes)
    Note that all values will be rounded up to the nearest kibibyte by libvirt, and may be further rounded to the granularity supported by the hypervisor. Some hypervisors also enforce a minimum, such as 4000KiB (or 4000 x 210 or 4,096,000 bytes). The units for this value are determined by the optional attribute memory unit, which defaults to the kibibytes (KiB) as a unit of measure where the value given is multiplied by 210 or blocks of 1024 bytes.
  • --config - the command takes effect on the next boot
  • --live - the command controls the memory of a running guest virtual machine
  • --current - the command controls the memory on the current guest virtual machine

20.36.8. Changing the Memory Allocation for the Domain

The virsh setmaxmem domain size --config --live --current command allows the setting of the maximum memory allocation for a guest virtual machine as shown: 
# virsh setmaxmem guest1 1024 --current
The size that can be given for the maximum memory is a scaled integer that by default is expressed in kibibytes, unless a supported suffix is provided. The following arguments can be used with this command:
  • --config - takes affect next boot
  • --live - controls the memory of the running guest virtual machine, providing the hypervisor supports this action as not all hypervisors allow live changes of the maximum memory limit.
  • --current - controls the memory on the current guest virtual machine

20.36.9. Displaying Guest Virtual Machine Block Device Information

Use the virsh domblkstat command to display block device statistics for a running guest virtual machine. Use the --human to display the statistics in a more user friendly way. 
# virsh domblkstat GuestName block-device

20.36.10. Displaying Guest Virtual Machine Network Device Information

Use the virsh domifstat command to display network interface statistics for a running guest virtual machine. 
# virsh domifstat GuestName interface-device