Project: StratoVirt (Runtime / Container Runtime)
File: qmp.md

StratoVirt controls VM's lifecycle and external api interface with in the current version. When running StratoVirt, you must create QMP in cmdline arguments as a management interface. StratoVirt supports UnixSocket-type QMP and TcpSocket-type QMP, you can set it by: ```shell -qmp unix:/path/to/api/socket,server,nowait ``` ```shell -qmp tcp:ip:port,server,nowait ``` Where, the information about 'server' and 'nowait' can be found in On top of that, monitor can be used to create QMP connection as well. The following commands can be used to create a monitor. Three properties can be set for monitor. id: unique device id. chardev: char device of monitor. mode: the model of monitor. NB: currently only "control" is supported. ```shell -chardev socket,path=/path/to/monitor/sock,id=chardev_id,server,nowait -mon chardev=chardevid,id=monitorid,mode=control ``` ```shell -chardev socket,host=ip,port=port,id=chardev_id,server,nowait -mon chardev=chardevid,id=monitorid,mode=control ``` After StratoVirt started, you can connect to StratoVirt's QMP and manage it by QMP. Several steps to connect QMP are showed as following: ```shell $ ncat -U /path/to/api/socket ``` ```shell $ ncat ip port ``` Once connection is built, you will receive a `greeting` message from StratoVirt. ```json { "QMP": { "version": { "StratoVirt": { "micro":1, "minor":0, "major":0 }, "package":"" }, "capabilities":[] } } ``` Now you can input QMP command to control StratoVirt. Add a block backend. `node-name` : the name of the block driver node, must be unique. `file` : the backend file information. `media` : indicate media type of the backend file. Possible values are `disk` or `cdrom`. If not set, default is `disk`. `cache` : if use direct io. `read-only` : if readonly. `driver` : the block image format. Possible values are `raw` or `qcow2`. If not set, default is `raw`. `aio` : the aio type of block device. Micro VM `node-name` in `blockdev-add` should be same as `id` in `device_add`. For `addr`, it start at `0x0` mapping in guest with `vda` on x86_64 platform, and start at `0x1` mapping in guest with `vdb` on aarch64 platform. For `driver`, only `raw` is supported. ```json -> { "execute": "blockdev-add", "arguments": { "node-name": "drive-0", "file": { "driver": "file", "filename": "/path/to/block", "aio": "native" }, "cache": { "direct": true }, "read-only": false } } <- { "return": {} } ``` Remove a block backend. `node-name` : the name of the block driver node. ```json -> { "execute": "blockdev-del", "arguments": { "node-name": "drive-0" } } <- { "return": {} } ``` Add a network backend. `id` : the device's ID, must be unique. `ifname` : the backend tap dev name. `fd` : the opened tap fd. `fds` : the opened tap fds. `queues` : the num of queues for multi-queue. `vhost` : whether to run as a vhost-net device. `vhostfd` : the vhost-net device fd. `vhostfds` : the vhost-net device fds. `chardev` : the chardev name for vhost-user net. Micro VM `id` in `netdevadd` should be same as `id` in `deviceadd`. For `addr`, it start at `0x0` mapping in guest with `eth0`. It does not support multi-queue. ```json -> { "execute": "netdev_add", "arguments": { "id": "net-0", "ifname": "tap0" } } <- { "return": {} } ``` Remove a network backend. `id` : the device's ID. ```json -> { "execute": "netdev_del", "arguments": { "id": "net-0" } } <- { "return": {} } ``` Add a camera backend. `id` : the device's ID, must be unique. `driver` : the backend camera type, eg. v4l2 or demo. `path` : the backend camera file's path, eg. /dev/video0 MicroVM is not supported. ```json -> { "execute": "cameradev_add", "arguments": { "id": "cam-0", "driver": "v4l2", "path": "/dev/video0" } } <- { "return": {} } ``` Remove a camera

`id` : the device's ID. MicroVM is not supported. ```json -> { "execute": "cameradev_del", "arguments": { "id": "cam-0" } } <- { "return": {} } ``` Currently, It only supports Standard VM. Add a character device backend. `id` : the character device's ID, must be unique. `backend` : the chardev backend info. Standard VM `id` in `chardev-add` should be same as `id` in `netdev_add`. ```json -> { "execute": "chardev-add", "arguments": { "id": "chardev_id", "backend": { "type": "socket", "data": { "addr": { "type": "unix", "data": { "path": "/path/to/socket" } }, "server": false } } } } <- { "return": {} } ``` Remove a character device backend. `id` : the character device's ID. ```json -> { "execute": "chardev-remove", "arguments": { "id": "chardev_id" } } <- { "return": {} } ``` StratoVirt supports hot-plug virtio-blk and virtio-net devices with QMP. Standard VM supports hot-plug vfio and vhost-user net devices. Add a device. `id` : the device's ID, must be unique. `driver` : the name of the device's driver. `addr` : the address device insert into. `host` : the PCI device info in the system that contains domain, bus number, slot number and function number. `bus` : the bus device insert into. Only for Standard VM. `mac` : the mac of the net device. `netdev` : the backend of the net device. `drive` : the backend of the block device. `serial` : the serial of the block device. Standard VM Currently, the device can only be hot-plugged to the pcie-root-port device. Therefore, you need to configure the root port on the cmdline before starting the VM. Guest kernel config: CONFIGHOTPLUGPCI_PCIE=y You are not advised to hot plug/unplug devices during VM startup, shutdown or suspension, or when the VM is under high pressure. In this case, the driver in the VM may not respond to requests, causing VM exceptions. ```json -> { "execute": "device_add", "arguments": { "id": "net-0", "driver": "virtio-net-mmio", "addr": "0x0" } } <- { "return": {} } ``` Remove a device from a guest. `id` : the device's ID. The device is actually removed when you receive the DEVICE_DELETED event ```json -> { "execute": "device_del", "arguments": { "id": "net-0" } } <- { "event": "DEVICE_DELETED", "data": { "device": "net-0", "path": "net-0" }, "timestamp": { "seconds": 1614310541, "microseconds": 554250 } } <- { "return": {} } ``` With QMP, you can control VM's lifecycle by command `stop`, `cont`, `quit` and check VM state by `query-status`. Stop all guest VCPUs execution. ```json -> { "execute": "stop" } <- { "event": "STOP", "data": {}, "timestamp": { "seconds": 1583908726, "microseconds": 162739 } } <- { "return": {} } ``` Resume all guest VCPUs execution. ```json -> { "execute": "cont" } <- { "event": "RESUME", "data": {}, "timestamp": { "seconds": 1583908853, "microseconds": 411394 } } <- { "return": {} } ``` Reset all guest VCPUs execution. ```json -> { "execute": "system_reset" } <- { "return": {} } <- { "event": "RESET", "data": { "guest": true }, "timestamp": { "seconds": 1677381086, "microseconds": 432033 } } ``` Requests that a guest perform a powerdown operation. ```json -> { "execute": "system_powerdown" } <- { "return": {} } <- { "event": "POWERDOWN", "data": {}, "timestamp": { "seconds": 1677850193, "microseconds": 617907 } } ``` This command will cause StratoVirt process to exit gracefully. ```json -> { "execute": "quit" } <- { "return": {} } <- { "event": "SHUTDOWN", "data": { "guest": false, "reason": "host-qmp-quit" }, "timestamp": { "ds": 1590563776, "microseconds": 519808 } } ``` Query the running status of all

```json -> {"execute": "query-status"} <- {"return": { "running": true,"singlestep": false,"status": "running"}} ``` With QMP command you can set target memory size of guest and get memory size of guest. Set target memory size of guest. `value` : the memory size. ```json -> { "execute": "balloon", "arguments": { "value": 2147483648 } } <- { "return": {} } ``` Get memory size of guest. ```json -> { "execute": "query-balloon" } <- { "return": { "actual": 2147483648 } } ``` Take a snapshot of the VM into the specified directory. `uri` : template path. ```json -> { "execute": "migrate", "arguments": { "uri": "file:path/to/template" } } <- { "return": {} } ``` Get snapshot state. Now there are 5 states during snapshot: `None`: Resource is not prepared all. `Setup`: Resource is setup, ready to do snapshot. `Active`: In snapshot. `Completed`: Snapshot succeed. `Failed`: Snapshot failed. ```json -> { "execute": "query-migrate" } <- { "return": { "status": "completed" } } ``` Create disk internal snapshot. `device` - the valid block device. `name` - the snapshot name. ```json -> { "execute": "blockdev-snapshot-internal-sync", "arguments": { "device": "disk0", "name": "snapshot1" } } <- { "return": {} } ``` Delete disk internal snapshot. `device` - the valid block device. `name` - the snapshot name. ```json -> { "execute": "blockdev-snapshot-delete-internal-sync", "arguments": { "device": "disk0", "name": "snapshot1" } } <- { "return": { "id": "1", "name": "snapshot0", "vm-state-size": 0, "date-sec": 1000012, "date-nsec": 10, "vm-clock-sec": 100, vm-clock-nsec": 20, "icount": 220414 } } ``` Query vcpu register value. `addr` : the register address. `vcpu` : vcpu id. The VM will pause during the query and then resume. Only aarch64 is supported now. ```json -> {"execute": "query-vcpu-reg", "arguments": {"addr": "603000000013df1a", "vcpu": 0}} <- {"return": "348531C5"} ``` Query the value of the guest physical address. `gpa` : the guest physical address. ```json -> {"execute": "query-mem-gpa", "arguments": {"gpa": "13c4d1d00" }} <- {"return": "B9000001"} ``` Query the display image of virtiogpu. Currently only stdvm and gtk supports. ```json -> { "execute": "query-display-image" } <- { "return": { "fileDir": "/tmp/stratovirt-images", "isSuccess": true } } ``` Query whether the trace state is enabled. `name` : Pattern used to match trace name. ```json -> { "execute": "trace-get-state", "arguments": { "name": "trace_name" } } <- { "return": [ { "name": "trace_name", "state": "disabled" } ] } ``` Set the state of trace. `name` : Pattern used to match trace name. `enable` : Whether to enable trace state. ```json -> { "execute": "trace-set-state", "arguments": { "name": "trace_name","enable": true } } <- { "return": {} } ``` Receive a file descriptor via SCM rights and assign it a name. ```json -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } <- { "return": {} } ``` Control if the scream device can use host's microphone record. `authorized` : "on" means scream can use host's microphone record, "off" opposites in meaning. ```json -> { "execute": "switch-audio-record", "arguments": { "authorized": "on" } } <- { "return": {} } ``` When some events happen, connected client will receive QMP events. Now StratoVirt supports these events: `SHUTDOWN`: Emitted when the virtual machine has shut down, indicating that StratoVirt is about to exit. `RESET`: Emitted when the virtual machine is reset. `STOP`: Emitted when the virtual machine is stopped. `RESUME`: Emitted when the virtual machine resumes execution. `POWERDOWN`: Emitted when the virtual machine powerdown execution. `DEVICE_DELETED`: Emitted whenever the device removal completion is acknowledged by the guest. `BALLOON_CHANGED`: Emitted when the virtual machine changes the actual BALLOON level. QMP use `leak bucket` to control QMP command flow. Now QMP server accept 100 commands per second.