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: 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 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. 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: To display also the amount of available memory in individual cells, use the --all option: To display the amount of individual memory in a specific cell, use the --cellno option: 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: 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: This example displays the statistics for CPU number 2 as percentages: 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. Locate the USB device you want to attach by running the following command: 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 step. <hostdev mode='subsystem' type='usb' managed='yes'> <source> <vendor id='0x17ef'/> <product id='0x480f'/> </source> </hostdev> Figure 20.2. USB devices XML snippet 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 step. For the change take effect at the 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 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 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 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: This example lists SCSI devices available on a host: 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

Commands:
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
<numatune> <memory mode='strict' nodeset='0,2-3'/> </numatune>
virsh freecell Total: 684096 KiB
virsh freecell --all 0: 804676 KiB -------------------- Total: 804676 KiB
virsh freecell --cellno 0 0: 772496 KiB
virsh nodecpumap CPUs present: 4 CPUs online: 1 CPU map: y
virsh nodecpustats user: 1056442260000000 system: 401675280000000 idle: 7549613380000000 iowait: 94593570000000
virsh nodecpustats 2 --percent usage: 2.0% user: 1.0% system: 1.0% idle: 98.0% iowait: 0.0%
lsusb -v idVendor 0x17ef Lenovo idProduct 0x480f Integrated Webcam [R5U877]
<hostdev mode='subsystem' type='usb' managed='yes'> <source> <vendor id='0x17ef'/> <product id='0x480f'/> </source> </hostdev>
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 [...]
virsh nodedev-list --cap scsi scsi_0_0_0_0