Virtualization Guide

38.1 Accessing monitor console #

Tip: No monitor console for libvirt

You can access the monitor console only if you started the virtual machine directly with the qemu-system-ARCH command and are viewing its graphical output in a built-in QEMU window.

If you started the virtual machine with libvirt, for example, using virt-manager, and are viewing its output via VNC or Spice sessions, you cannot access the monitor console directly. You can, however, send the monitor command to the virtual machine via virsh:

# virsh qemu-monitor-command COMMAND

The way you access the monitor console depends on which display device you use to view the output of a virtual machine. Find more details about displays in Section 37.3.2.2, “Display options”. For example, to view the monitor while the -display gtk option is in use, press Ctrl–Alt–2. Similarly, when the -nographic option is in use, you can switch to the monitor console by pressing the following key combination: Ctrl–AC.

To get help while using the console, use help or ?. To get help for a specific command, use help COMMAND.

38.2 Getting information about the guest system #

To get information about the guest system, use info. If used without any option, the list of possible options is printed. Options determine which part of the system is analyzed:

info version: Shows the version of QEMU.
info commands: Lists available QMP commands.
info network: Shows the network state.
info chardev: Shows the character devices.
info block: Information about block devices, such as hard disks, floppy drives, or CD-ROMs.
info blockstats: Read and write statistics on block devices.
info registers: Shows the CPU registers.
info cpus: Shows information about available CPUs.
info history: Shows the command line history.
info irq: Shows the interrupt statistics.
info pic: Shows the i8259 (PIC) state.
info pci: Shows the PCI information.
info tlb: Shows virtual to physical memory mappings.
info mem: Shows the active virtual memory mappings.
info jit: Shows dynamic compiler information.
info kvm: Shows the KVM information.
info numa: Shows the NUMA information.
info usb: Shows the guest USB devices.
info usbhost: Shows the host USB devices.
info profile: Shows the profiling information.
info capture: Shows the capture (audio grab) information.
info snapshots: Shows the currently saved virtual machine snapshots.
info status: Shows the current virtual machine status.
info mice: Shows which guest mice are receiving events.
info vnc: Shows the VNC server status.
info name: Shows the current virtual machine name.
info uuid: Shows the current virtual machine UUID.
info usernet: Shows the user network stack connection states.
info migrate: Shows the migration status.
info balloon: Shows the balloon device information.
info qtree: Shows the device tree.
info qdm: Shows the qdev device model list.
info roms: Shows the ROMs.
info migrate_cache_size: Shows the current migration xbzrle (“Xor Based Zero Run Length Encoding”) cache size.
info migrate_capabilities: Shows the status of the multiple migration capabilities, such as xbzrle compression.
info mtree: Shows the VM Guest memory hierarchy.
info trace-events: Shows available trace-events and their status.

38.3 Changing VNC password #

To change the VNC password, use the change vnc password command and enter the new password:

(qemu) change vnc password
Password: ********
(qemu)

38.4 Managing devices #

To add a new disk while the guest is running (hotplug), use the drive_add and device_add commands. First define a new drive to be added as a device to bus 0:

(qemu) drive_add 0 if=none,file=/tmp/test.img,format=raw,id=disk1
OK

You can confirm your new device by querying the block subsystem:

(qemu) info block
[...]
disk1: removable=1 locked=0 tray-open=0 file=/tmp/test.img ro=0 drv=raw \
encrypted=0 bps=0 bps_rd=0 bps_wr=0 iops=0 iops_rd=0 iops_wr=0

After the new drive is defined, it needs to be connected to a device so that the guest can see it. The typical device would be a virtio-blk-pci or scsi-disk. To get the full list of available values, run:

(qemu) device_add ?
name "VGA", bus PCI
name "usb-storage", bus usb-bus
[...]
name "virtio-blk-pci", bus virtio-bus

Now add the device

(qemu) device_add virtio-blk-pci,drive=disk1,id=myvirtio1

and confirm with

(qemu) info pci
[...]
Bus  0, device   4, function 0:
    SCSI controller: PCI device 1af4:1001
      IRQ 0.
      BAR0: I/O at 0xffffffffffffffff [0x003e].
      BAR1: 32 bit memory at 0xffffffffffffffff [0x00000ffe].
      id "myvirtio1"

Tip

Devices added with the device_add command can be removed from the guest with device_del. Enter help device_del on the QEMU monitor command line for more information.

To release the device or file connected to the removable media device, use the eject DEVICE command. Use the optional -f to force ejection.

To change removable media (like CD-ROMs), use the change DEVICE command. The name of the removable media can be determined using the info block command:

(qemu) info block
ide1-cd0: type=cdrom removable=1 locked=0 file=/dev/sr0 ro=1 drv=host_device
(qemu) change ide1-cd0 /path/to/image

38.5 Controlling keyboard and mouse #

It is possible to use the monitor console to emulate keyboard and mouse input if necessary. For example, if your graphical user interface intercepts certain key combinations at low level (such as Ctrl–Alt–F1 in X Window Syustem), you can still enter them using the sendkey KEYS:

sendkey ctrl-alt-f1

To list the key names used in the KEYS option, enter sendkey and press →|.

To control the mouse, the following commands can be used:

mouse_move DX dy [DZ]: Move the active mouse pointer to the specified coordinates dx, dy with the optional scroll axis dz.
mouse_button VAL: Change the state of the mouse buttons (1=left, 2=middle, 4=right).
mouse_set INDEX: Set which mouse device receives events. Device index numbers can be obtained with the info mice command.

38.6 Changing available memory #

If the virtual machine was started with the -balloon virtio option (the paravirtualized balloon device is therefore enabled), you can change the available memory dynamically. For more information about enabling the balloon device, see Section 36.1, “Basic installation with qemu-system-ARCH”.

To get information about the balloon device in the monitor console and to determine whether the device is enabled, use the info balloon command:

(qemu) info balloon

If the balloon device is enabled, use the balloon MEMORY_IN_MB command to set the requested amount of memory:

(qemu) balloon 400

38.7 Dumping virtual machine memory #

To save the content of the virtual machine memory to a disk or console output, use the following commands:

memsaveADDRSIZEFILENAME

Saves virtual memory dump starting at ADDR of size SIZE to file FILENAME

pmemsaveADDRSIZEFILENAME

Saves physical memory dump starting at ADDR of size SIZE to file FILENAME-

x /FMTADDR

Makes a virtual memory dump starting at address ADDR and formatted according to the FMT string. The FMT string consists of three parameters COUNTFORMATSIZE:

The COUNT parameter is the number of items to be dumped.

The FORMAT can be x (hex), d (signed decimal), u (unsigned decimal), o (octal), c (char) or i (assembly instruction).

The SIZE parameter can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, h or w can be specified with the i format to respectively select 16 or 32-bit code instruction size.

xp /FMTADDR

Makes a physical memory dump starting at address ADDR and formatted according to the FMT string. The FMT string consists of three parameters COUNTFORMATSIZE:

The COUNT parameter is the number of the items to be dumped.

The FORMAT can be x (hex), d (signed decimal), u (unsigned decimal), o (octal), c (char) or i (asm instruction).

The SIZE parameter can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, h or w can be specified with thei format to respectively select 16 or 32-bit code instruction size.

38.8 Managing virtual machine snapshots #

Managing snapshots in QEMU monitor is not supported by SUSE yet. The information found in this section may be helpful in specific cases.

Virtual Machine snapshots are snapshots of the complete virtual machine including the state of CPU, RAM and the content of all writable disks. To use virtual machine snapshots, you must have at least one non-removable and writable block device using the qcow2 disk image format.

Snapshots are helpful when you need to save your virtual machine in a particular state. For example, after you have configured network services on a virtualized server and want to quickly start the virtual machine in the same state that was saved last. You can also create a snapshot after the virtual machine has been powered off to create a backup state before you try something experimental and make VM Guest unstable. This section introduces the former case, while the latter is described in Section 36.2.3, “Managing snapshots of virtual machines with qemu-img”.

The following commands are available for managing snapshots in QEMU monitor:

savevmNAME

Creates a new virtual machine snapshot under the tag NAME or replaces an existing snapshot.

loadvmNAME

Loads a virtual machine snapshot tagged NAME.

delvm

Deletes a virtual machine snapshot.

info snapshots

Prints information about available snapshots.

(qemu) info snapshots
Snapshot list:
ID1      TAG2                 VM SIZE3   DATE4          VM CLOCK5
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965

1	Unique auto-incremented identification number of the snapshot.
2	Unique description string of the snapshot. It is meant as a human readable version of the ID.
3	The disk space occupied by the snapshot. The more memory is consumed by running applications, the bigger the snapshot is.
4	Time and date the snapshot was created.
5	The current state of the virtual machine's clock.

38.9 Suspending and resuming virtual machine execution #

The following commands are available for suspending and resuming virtual machines:

stop: Suspends the execution of the virtual machine.
cont: Resumes the execution of the virtual machine.
system_reset: Resets the virtual machine. The effect is similar to the reset button on a physical machine. This may leave the file system in an unclean state.
system_powerdown: Sends an ACPI shutdown request to the machine. The effect is similar to the power button on a physical machine.
q or quit: Terminates QEMU immediately.

38.10 Live migration #

The live migration process allows to transmit any virtual machine from one host system to another host system without any interruption in availability. It is possible to change hosts permanently or only during maintenance.

The requirements for live migration:

All requirements from Section 17.2, “Migration requirements” are applicable.
Live migration is only possible between VM Host Servers with the same CPU features.
AHCI interface, VirtFS feature, and the -mem-path command line option are not compatible with migration.
The guest on the source and destination hosts must be started in the same way.
-snapshot qemu command line option should not be used for migration (and this qemu command line option is not supported).

Important: Support status

The postcopy mode is not yet supported in SUSE Linux Enterprise Server. It is released as a technology preview only. For more information about postcopy, see https://wiki.qemu.org/Features/PostCopyLiveMigration.

More recommendations can be found at the following Web site: https://www.linux-kvm.org/page/Migration

The live migration process has the following steps:

The virtual machine instance is running on the source host.
The virtual machine is started on the destination host in the frozen listening mode. The parameters used are the same as on the source host plus the -incoming tcp:IP:PORT parameter, where IP specifies the IP address and PORT specifies the port for listening to the incoming migration. If 0 is set as IP address, the virtual machine listens on all interfaces.
On the source host, switch to the monitor console and use the migrate -d tcp: DESTINATION_IP:PORT command to initiate the migration.
To determine the state of the migration, use the info migrate command in the monitor console on the source host.
To cancel the migration, use the migrate_cancel command in the monitor console on the source host.
To set the maximum tolerable downtime for migration in seconds, use the migrate_set_downtime NUMBER_OF_SECONDS command.
To set the maximum speed for migration in bytes per second, use the migrate_set_speed BYTES_PER_SECOND command.

38.11 QMP - QEMU machine protocol #

QMP is a JSON-based protocol that allows applications—such as libvirt—to communicate with a running QEMU instance. There are several ways you can access the QEMU monitor using QMP commands.

38.11.1 Access QMP via standard input/output #

The most flexible way to use QMP is by specifying the -mon option. The following example creates a QMP instance using standard input/output. In the following examples, -> marks lines with commands sent from client to the running QEMU instance, while <- marks lines with the output returned from QEMU.

> sudo qemu-system-x86_64 [...] \
-chardev stdio,id=mon0 \
-mon chardev=mon0,mode=control,pretty=on

<- {
    "QMP": {
        "version": {
            "qemu": {
                "micro": 0,
                "minor": 0,
                "major": 2
            },
            "package": ""
        },
        "capabilities": [
        ]
    }
}

When a new QMP connection is established, QMP sends its greeting message and enters capabilities negotiation mode. In this mode, only the qmp_capabilities command works. To exit capabilities negotiation mode and enter command mode, the qmp_capabilities command must be issued first:

-> { "execute": "qmp_capabilities" }
<- {
    "return": {
    }
}

"return": {} is a QMP's success response.

QMP's commands can have arguments. For example, to eject a CD-ROM drive, enter the following:

->{ "execute": "eject", "arguments": { "device": "ide1-cd0" } }
<- {
    "timestamp": {
        "seconds": 1410353381,
        "microseconds": 763480
    },
    "event": "DEVICE_TRAY_MOVED",
    "data": {
        "device": "ide1-cd0",
        "tray-open": true
    }
}
{
    "return": {
    }
}

38.11.2 Access QMP via telnet #

Instead of the standard input/output, you can connect the QMP interface to a network socket and communicate with it via a specified port:

> sudo qemu-system-x86_64 [...] \
-chardev socket,id=mon0,host=localhost,port=4444,server,nowait \
-mon chardev=mon0,mode=control,pretty=on

And then run telnet to connect to port 4444:

> telnet localhost 4444
Trying ::1...
Connected to localhost.
Escape character is '^]'.
<- {
    "QMP": {
        "version": {
            "qemu": {
                "micro": 0,
                "minor": 0,
                "major": 2
            },
            "package": ""
        },
        "capabilities": [
        ]
    }
}

You can create several monitor interfaces at the same time. The following example creates one HMP instance—human monitor which understands “normal” QEMU monitor's commands—on the standard input/output, and one QMP instance on localhost port 4444:

> sudo qemu-system-x86_64 [...] \
-chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
-chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
  -mon chardev=mon1,mode=control,pretty=on

38.11.3 Access QMP via Unix socket #

Invoke QEMU using the -qmp option, and create a Unix socket:

> sudo qemu-system-x86_64 [...] \
-qmp unix:/tmp/qmp-sock,server --monitor stdio

QEMU waiting for connection on: unix:./qmp-sock,server

To communicate with the QEMU instance via the /tmp/qmp-sock socket, use nc (see man 1 nc for more information) from another terminal on the same host:

> sudo nc -U /tmp/qmp-sock
<- {"QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 2} [...]

38.11.4 Access QMP via `libvirt`'s `virsh` command #

If you run your virtual machines under libvirt (see Part II, “Managing virtual machines with libvirt”), you can communicate with its running guests by running the virsh qemu-monitor-command:

> sudo virsh qemu-monitor-command vm_guest1 \
--pretty '{"execute":"query-kvm"}'
<- {
    "return": {
        "enabled": true,
        "present": true
    },
    "id": "libvirt-8"
}

In the above example, we ran the simple command query-kvm which checks if the host is capable of running KVM and if KVM is enabled.

Tip: Generating human-readable output

To use the standard human-readable output format of QEMU instead of the JSON format, use the --hmp option:

> sudo virsh qemu-monitor-command vm_guest1 --hmp "query-kvm"

38 Virtual machine administration using QEMU monitor #

38.1 Accessing monitor console #

38.2 Getting information about the guest system #

38.3 Changing VNC password #

38.4 Managing devices #

38.5 Controlling keyboard and mouse #

38.6 Changing available memory #

38.7 Dumping virtual machine memory #

38.8 Managing virtual machine snapshots #

38.9 Suspending and resuming virtual machine execution #

38.10 Live migration #

38.11 QMP - QEMU machine protocol #

38.11.1 Access QMP via standard input/output #

38.11.2 Access QMP via telnet #

38.11.3 Access QMP via Unix socket #

38.11.4 Access QMP via libvirt's virsh command #

38.11.4 Access QMP via `libvirt`'s `virsh` command #