38 Virtual machine administration using QEMU monitor #
When a virtual machine is invoked by the qemu-system-ARCH
command, for
example qemu-system-x86_64
, a monitor console is
provided for performing interaction with the user. Using the commands
available in the monitor console, it is possible to inspect the running
operating system, change removable media, take screenshots or audio grabs
and control other aspects of the virtual machine.
The following sections list selected useful QEMU monitor commands and
their purpose. To get the full list, enter help
in the
QEMU monitor command line.
38.1 Accessing monitor console #
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"
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
VALChange the state of the mouse buttons (1=left, 2=middle, 4=right).
mouse_set
INDEXSet 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:
memsave
ADDRSIZEFILENAMESaves virtual memory dump starting at ADDR of size SIZE to file FILENAME
pmemsave
ADDRSIZEFILENAMESaves 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) ori
(assembly instruction).The SIZE parameter can be
b
(8 bits),h
(16 bits),w
(32 bits) org
(64 bits). On x86,h
orw
can be specified with thei
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) ori
(asm instruction).The SIZE parameter can be
b
(8 bits),h
(16 bits),w
(32 bits) org
(64 bits). On x86,h
orw
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:
savevm
NAMECreates a new virtual machine snapshot under the tag NAME or replaces an existing snapshot.
loadvm
NAMELoads 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
Unique auto-incremented identification number of the snapshot.
Unique description string of the snapshot. It is meant as a human readable version of the ID.
The disk space occupied by the snapshot. The more memory is consumed by running applications, the bigger the snapshot is.
Time and date the snapshot was created.
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
orquit
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 thisqemu
command line option is not supported).
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.
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"