20.27. Host Machine Management

This section contains the commands needed for managing the host system (referred to as a node by the commands).

20.27.1. Displaying Host Information

The virsh nodeinfo command displays basic information about the host, including the model number, number of CPUs, type of CPU, and size of the physical memory. The output corresponds to the virNodeInfo structure. Specifically, the "CPU socket(s)" field indicates the number of CPU sockets per NUMA cell.

Example 20.54. How to display information about your host machine

The following example retrieves information about your host:
$ virsh nodeinfo
CPU model:           x86_64
CPU(s):              4
CPU frequency:       1199 MHz
CPU socket(s):       1
Core(s) per socket:  2
Thread(s) per core:  2
NUMA cell(s):        1
Memory size:         3715908 KiB

20.27.2. Setting NUMA Parameters

The virsh numatune command can either set or retrieve the NUMA parameters for a specified guest virtual machine. Within the guest virtual machine's configuration XML file these parameters are nested within the <numatune> element. Without using flags, only the current settings are displayed. The numatune domain command requires a specified guest virtual machine name and can take the following arguments:
  • --mode - The mode can be set to either strict, interleave, or preferred. Running domains cannot have their mode changed while live unless the guest virtual machine was started within strict mode.
  • --nodeset contains a list of NUMA nodes that are used by the host physical machine for running the guest virtual machine. The list contains nodes, each separated by a comma, with a dash - used for node ranges and a caret ^ used for excluding a node.
  • Only one of the three following flags can be used per instance
    • --config will effect the next boot of a persistent guest virtual machine
    • --live will set the scheduler information of a running guest virtual machine.
    • --current will effect the current state of the guest virtual machine.

Example 20.55. How to set the NUMA parameters for the guest virtual machine

The following example sets the NUMA mode to strict for nodes 0, 2, and 3 for the running guest1 virtual machine:
virsh numatune guest1 --mode strict --nodeset 0,2-3 --live
Running this command will change the running configuration for guest1 to the following configuration in its XML file.
<numatune>
        <memory mode='strict' nodeset='0,2-3'/>
</numatune>

20.27.3. Displaying the Amount of Free Memory in a NUMA Cell

The virsh freecell command displays the available amount of memory on the machine within a specified NUMA cell. This command can provide one of three different displays of available memory on the machine depending on the options specified. specified cell.

Example 20.56. How to display memory properties for virtual machines and NUMA cells

The following command displays the total amount of available memory in all cells:
virsh freecell
Total: 684096 KiB
To display also the amount of available memory in individual cells, use the --all option:
virsh freecell --all
    0:     804676 KiB
--------------------
Total:     804676 KiB

To display the amount of individual memory in a specific cell, use the --cellno option:
virsh freecell --cellno 0
0: 772496 KiB

20.27.4. Displaying a CPU List

The virsh nodecpumap command displays the number of CPUs that are available to the host machine, and it also lists how many are currently online.

Example 20.57. How to display number of CPUs that available to the host

The following example displays the number of CPUs available to the host:
virsh nodecpumap
   CPUs present: 4
   CPUs online: 1
   CPU map: y

20.27.5. Displaying CPU Statistics

The virsh nodecpustats [cpu_number] [--percent] command displays statistical information about the CPUs load status of the host. If a CPU is specified, the statistics are only for the specified CPU. If the percent option is specified, the command displays the percentage of each type of CPU statistics that were recorded over an one (1) second interval.

Example 20.58. How to display statistical information about CPU usage

The following example returns general statistics about the host CPUs load:
virsh nodecpustats
user:               1056442260000000
system:              401675280000000
idle:               7549613380000000
iowait:               94593570000000
This example displays the statistics for CPU number 2 as percentages:
virsh nodecpustats 2 --percent
usage:            2.0%
user:             1.0%
system:           1.0%
idle:            98.0%
iowait:           0.0%

20.27.6. Managing Devices

20.27.6.1. Attaching and updating a device with virsh

For information on attaching storage devices, see Section 13.3.6, “Adding Storage Devices to Guests”.

Procedure 20.4. Hot plugging USB devices for use by the guest virtual machine

USB devices can be either attached to the virtual machine that is running by hot plugging, or while the guest is shut off. The device you want to use in the guest must be attached to the host machine.
  1. Locate the USB device you want to attach by running the following command:
    lsusb -v
    
    idVendor           0x17ef Lenovo
    idProduct          0x480f Integrated Webcam [R5U877]
    
  2. Create an XML file and give it a logical name (usb_device.xml, for example). Copy the vendor and product ID number (a hexidecimal number) exactly as was displayed in your search. Add this information to the XML file as shown in Figure 20.2, “USB devices XML snippet”. Remember the name of this file as you will need it in the next step.
    <hostdev mode='subsystem' type='usb' managed='yes'>
      <source>
        <vendor id='0x17ef'/>
        <product id='0x480f'/>
      </source>
    </hostdev>

    Figure 20.2. USB devices XML snippet

  3. Attach the device by running the following command. When you run the command, replace guest1 with the name of your virtual machine and usb_device.xml with the name of your XML file that contains the vendor and product ID of your device, which you created in the previous step. For the change take effect at the next reboot, use the --config argument. For the change to take effect on the current guest virtual machine, use the --current argument. See the virsh man page for additional arguments.
    virsh attach-device guest1 --file usb_device.xml --config

Example 20.59. How to hot unplug devices from a guest virtual machine

The following example detaches the USB device configured with the usb_device1.xml file from the guest1 virtual machine:
virsh detach-device guest1 --file usb_device.xml

20.27.6.2. Attaching interface devices

The virsh attach-interface domain type source [<target>] [<mac>] [<script>] [<model>] [<inbound>] [<outbound>] [--config] [--live] [--current] command can take the following arguments:
  • --type - allows you to set the interface type
  • --source - allows you to set the source of the network interface
  • --live - gets its value from running guest virtual machine configuration settings
  • --config - takes effect at next boot
  • --current - gets its value according to the current configuration settings
  • --target - indicates the target device in the guest virtual machine.
  • --mac - use this option to specify the MAC address of the network interface
  • --script - use this option to specify a path to a script file handling a bridge instead of the default one.
  • --model - use this option to specify the model type.
  • --inbound - controls the inbound bandwidth of the interface. Acceptable values are average, peak, and burst.
  • --outbound - controls the outbound bandwidth of the interface. Acceptable values are average, peak, and burst.

    Note

    Values for average and peak are expressed in kilobytes per second, while burst is expressed in kilobytes in a single burst at peak speed as described in the Network XML upstream documentation.
The type can be either network to indicate a physical network device, or bridge to indicate a bridge to a device. source is the source of the device. To remove the attached device, use the virsh detach-device command.

Example 20.60. How to attach a device to the guest virtual machine

The following example attaches the networkw network device to the guest1 virtual machine. The interface model is going to be presented to the guest as virtio:
virsh attach-interface guest1 networkw --model virtio

20.27.6.3. Changing the media of a CDROM

The virsh change-media command changes the media of a CDROM to another source or format. The command takes the following arguments. More examples and explanation for these arguments can also be found in the man page.
  • --path - A string containing a fully-qualified path or target of disk device
  • --source - A string containing the source of the media
  • --eject - Ejects the media
  • --insert - Inserts the media
  • --update - Updates the media
  • --current - Can be either or both of --live and --config, which depends on implementation of hypervisor driver
  • --live - Alters the live configuration of running guest virtual machine
  • --config - Alters the persistent configuration, effect observed on next boot
  • --force - Forces media to change

20.27.7. Setting and Displaying the Node Memory Parameters

The virsh node-memory-tune [shm-pages-to-scan] [shm-sleep-milisecs] [shm-merge-across-nodes] command displays and allows you to set the node memory parameters. The following parameters may be set with this command:
  • --shm-pages-to-scan - sets the number of pages to scan before the kernel samepage merging (KSM) service goes to sleep.
  • --shm-sleep-milisecs - sets the number of miliseconds that KSM will sleep before the next scan
  • --shm-merge-across-nodes - specifies if pages from different NUMA nodes can be merged

Example 20.61. How to merge memory pages across NUMA nodes

The following example merges all of the memory pages from all of the NUMA nodes:
virsh node-memory-tune --shm-merge-across-nodes 1

20.27.8. Listing Devices on a Host

The virsh nodedev-list --cap --tree command lists all the devices available on the host that are known to the libvirt service. --cap is used to filter the list by capability types, each separated by a comma, and cannot be used with --tree. Using the argument --tree, puts the output into a tree structure.

Example 20.62. How to display the devices available on a host

The following example lists devices that are available on a host in a tree format. Note that the list has been truncated:
virsh nodedev-list --tree
computer
  |
  +- net_lo_00_00_00_00_00_00
  +- net_macvtap0_52_54_00_12_fe_50
  +- net_tun0
  +- net_virbr0_nic_52_54_00_03_7d_cb
  +- pci_0000_00_00_0
  +- pci_0000_00_02_0
  +- pci_0000_00_16_0
  +- pci_0000_00_19_0
  |   |
  |   +- net_eth0_f0_de_f1_3a_35_4f
	[...]
This example lists SCSI devices available on a host:
# virsh nodedev-list --cap scsi
scsi_0_0_0_0

20.27.9. Creating Devices on Host Machines

The virsh nodedev-create file command allows you to create a device on a host physical machine and then assign it to a guest virtual machine. Although libvirt automatically detects which host nodes are available for use, this command allows you to register hardware that libvirt did not detect. The specified file should contain the XML description for the top level <device> description of the host device. For an example of such file, see Example 20.65, “How to retrieve the XML file for a device”.

Example 20.63. How to create a device from an XML file

In this example, you have already created an XML file for your PCI device and have saved it as scsi_host2.xml. The following command enables you to attach this device to your guests:
virsh nodedev-create scsi_host2.xml

20.27.10. Removing a Device

The virsh nodedev-destroy command removes the device from the host. Note that the virsh node device driver does not support persistent configurations, so rebooting the host machine makes the device usable again.
Also note that different assignments expect the device to be bound to different back-end driver (vfio, kvm). Using the --driver argument allows you to specify the intended back-end driver.

Example 20.64. How to remove a device from a host physical machine

The following example removes a SCSI device named scsi_host2 from the host machine:
virsh nodedev-destroy scsi_host2

20.27.11. Collect Device Configuration Settings

The virsh nodedev-dumpxml device command outputs the XML representation for the specified host device, including information such as the device name, the bus to which the device is connected, the vendor, product ID, capabilities, as well as any information usable by libvirt. The argument device can either be a device name or WWN pair in WWNN, WWPN format (HBA only).

Example 20.65. How to retrieve the XML file for a device

The following example retrieves the XML file for a SCSI device identified as scsi_host2. The name was obtained by using the virsh nodedev-list command:
virsh nodedev-dumpxml scsi_host2
   <device>
     <name>scsi_host2</name>
     <parent>scsi_host1</parent>
     <capability type='scsi_host'>
       <capability type='fc_host'>
         <wwnn>2001001b32a9da5b</wwnn>
         <wwpn>2101001b32a9da5b</wwpn>
       </capability>
     </capability>
   </device>

20.27.12. Triggering a Reset for a Device

The virsh nodedev-reset device command triggers a device reset for the specified device. Running this command is useful prior to transferring a node device between guest virtual machine pass through or the host physical machine. libvirt will do this action automatically, when required, but this command allows an explicit reset when needed.

Example 20.66. How to reset a device on a guest virtual machine

The following example resets the device on the guest virtual machine named scsi_host2:
virsh nodedev-reset scsi_host2