Managing VMs

Overview

StratoVirt allows you to query VM information and manage VM resources and lifecycle with QMP. To query the information about a VM, connect to the VM first.

Querying VM Information

Introduction

StratoVirt can be used to query the VM status, vCPU topology, and vCPU online status.

Querying VM Status

Run the query-status command to query the running status of a VM.

  • Usage:

    { “execute”: “query-status” }

  • Example:

<- { "execute": "query-status" }
-> { "return": { "running": true,"singlestep": false,"status": "running" } 

Querying Topology Information

Run the query-cpus command to query the topologies of all CPUs.

  • Usage:

    { “execute”: “query-cpus” }

  • Example:

<- { "execute": "query-cpus" }
-> {"return":[{"CPU":0,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom_path":"/machine/unattached/device[0]","thread_id":8439},{"CPU":1,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom_path":"/machine/unattached/device[1]","thread_id":8440}]}

Querying vCPU Online Status

Run the query-hotpluggable-cpus command to query the online/offline statuses of all vCPUs.

  • Usage:

    { “execute”: “query-hotpluggable-cpus” }

  • Example:

<- { "execute": "query-hotpluggable-cpus" }
-> {"return":[{"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom-path":"/machine/unattached/device[0]","type":"host-x86-cpu","vcpus-count":1},{"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom-path":"/machine/unattached/device[1]","type":"host-x86-cpu","vcpus-count":1}]}

Online vCPUs have the qom-path item, while offline vCPUs do not.

Managing VM Lifecycle

Introduction

StratoVirt can manage the lifecycle of a VM, including starting, suspending, resuming, and exiting the VM.

Creating and Starting a VM

As described in the “Configuring VMs” chapter, you can specify the VM configuration by using command line parameters or a JSON file, and run the stratovirt command on the host to create and start a VM.

  • When using the command line parameters to specify the VM configuration, run the following command to create and start the VM:
$/path/to/stratovirt - *[Parameter 1] [Parameter option] - [Parameter 2] [Parameter option]*...
  • When using the JSON file to specify the VM configuration, run the following command to create and start the VM:
$ /path/to/stratovirt \
    -config /path/to/json \
    -api-channel unix:/path/to/socket

In the preceding commands, /path/to/json indicates the path of the JSON configuration file./path/to/socket indicates the specified socket file, for example, /tmp/stratovirt.socket. After the preceding commands are executed, the socket file is automatically created. To properly start the VM, ensure that the socket file does not exist before creating it.

After the VM is started, there are two NICs: eth0 and eth1. The two NICs are reserved for hot plugging: eth0 first and then eth1. Currently, only two virtio-net NICs can be hot plugged.

Connecting to a VM

StratoVirt uses QMP to manage VMs. To suspend, resume, or exit a VM, connect it the StratoVirt through QMP first.

Open a new CLI (CLI B) on the host and run the following command to connect to the api-channel as the root user:

# ncat -U /path/to/socket

After the connection is set up, you will receive a greeting message from StratoVirt, as shown in the following:

{"QMP":{"version":{"qemu":{"micro":1,"minor":0,"major":4},"package":""},"capabilities":[]}}

You can now manage the VM by entering the QMP commands in CLI B.

QMP provides stop, cont, quit, and query-status commands to manage and query VM statuses.

All QMP commands for managing VMs are entered in CLI B. <- indicates the command input, and -> indicates the QMP returned result.

Suspending a VM

QMP provides the stop command to suspend a VM, that is, to suspend all vCPUs of the VM. The command syntax is as follows:

{“execute”:“stop”}

Example:

The stop command and the command output are as follows:

<- {"execute":"stop"}
-> {"event":"STOP","data":{},"timestamp":{"seconds":1583908726,"microseconds":162739}}
-> {"return":{}}

Restoring a VM

QMP provides the cont command to resume a suspended VM, that is, to resume all vCPUs of the VM. The command syntax is as follows:

{“execute”:“cont”}

Example:

The cont command and the command output are as follows:

<- {"execute":"cont"}
-> {"event":"RESUME","data":{},"timestamp":{"seconds":1583908853,"microseconds":411394}}
-> {"return":{}}

Exiting a VM

QMP provides the quit command to exit a VM, that is, to exit the StratoVirt process. The command syntax is as follows:

{“execute”:“quit”}

Example:

<- {"execute":"quit"}
-> {"return":{}}
-> {"event":"SHUTDOWN","data":{"guest":false,"reason":"host-qmp-quit"},"timestamp":{"ds":1590563776,"microseconds":519808}}

Managing VM Resources

Hot-Pluggable Disks

StratoVirt allows you to adjust the number of disks when a VM is running. That is, you can add or delete VM disks without interrupting services.

Hot Plugged-in Disks

Usage:

{"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}}
{"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}}

Parameters:

  • The value of node-name in blockdev-add must be the same as the value of id in device_add. For example, both values are drive-0 in the preceding example.

  • /path/to/block is the image path of the hot plugged-in disks. It cannot be the path of the disk image that boots the rootfs.

  • For addr, 0x0 is mapped to vda of the VM, 0x1 is mapped to vdb, and so on. To be compatible with the QMP protocol, addr can be replaced by lun, but lun=0 is mapped to the vdb of the client.

  • StratoVirt supports a maximum of four virtio-blk disks. Note this when hot plugging in disks.

Example:

<- {"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}}
-> {"return": {}}
<- {"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}}
-> {"return": {}}

Hot Plugged-out Disks

Usage:

{“execute”: “device_del”, “arguments”: {“id”:“drive-0”}}

Parameters:

id indicates the ID of the hot plugged-out disk.

Example:

<- {"execute": "device_del", "arguments": {"id": "drive-0"}}
-> {"event":"DEVICE_DELETED","data":{"device":"drive-0","path":"drive-0"},"timestamp":{"seconds":1598513162,"microseconds":367129}}
-> {"return": {}}

Hot-Pluggable NICs

StratoVirt allows you to adjust the number of NICs when a VM is running. That is, you can add or delete VM NICs without interrupting services.

Hot Plugged-in NICs

Preparations (Requiring the root Permission)

  1. Create and enable a Linux bridge. For example, if the bridge name is qbr0, run the following command:
# brctl addbr qbr0
# ifconfig qbr0 up
  1. Create and enable a tap device. For example, if the tap device name is tap0, run the following command:
# ip tuntap add tap0 mode tap
# ifconfig tap0 up
  1. Add the tap device to the bridge.
# brctl addif qbr0 tap0

Usage:

{"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}}
{"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}}

Parameters:

  • id in netdev_add must be the same as that in device_add. ifname is the name of the backend tap device.

  • For addr, 0x0 is mapped to eth0 of the VM, 0x1 is mapped to eth1, and so on.

  • StratoVirt supports a maximum of two virtio-net NICs. Therefore, pay attention to the specification restrictions when hot plugging in NICs.

Example:

<- {"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}}
-> {"return": {}}
<- {"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}} 
-> {"return": {}}

addr:0x0 corresponds to eth0 in the VM.

Hot Plugged-out NICs

Usage:

{“execute”: “device_del”, “arguments”: {“id”: “net-0”}}

Parameters:

id: NIC ID, for example, net-0.

Example:

<- {"execute": "device_del", "arguments": {"id": "net-0"}}
-> {"event":"DEVICE_DELETED","data":{"device":"net-0","path":"net-0"},"timestamp":{"seconds":1598513339,"microseconds":97310}}
-> {"return": {}}

Using Ballon Devices

The balloon device is used to reclaim idle memory from a VM. It called by running the QMP command.

Usage:

{"execute": "balloon", "arguments": {"value": 2147483648‬}}

Parameters:

  • value: guest memory size to be set. The unit is byte. Memory compression is performed by page. If the value is greater than the memory value configured during VM startup, the latter is used.

Example:

The memory size configured during VM startup is 4 GiB. If the idle memory of the VM queried by running the free command is greater than 2 GiB, you can run the QMP command to set the guest memory size to 2147483648 bytes.

<- {"execute": "balloon", "arguments": {"value": 2147483648‬}}
-> {"return": {}}

Query the actual memory of the VM:

<- {"execute": "query-balloon"}
-> {"return":{"actual":2147483648}}

有奖捉虫

“有虫”文档片段

存在的问题

提交类型 issue
有点复杂...
找人问问吧。
PR
小问题,全程线上修改...
一键搞定!
问题类型
规范和低错类

● 错别字或拼写错误;标点符号使用错误;

● 链接错误、空单元格、格式错误;

● 英文中包含中文字符;

● 界面和描述不一致,但不影响操作;

● 表述不通顺,但不影响理解;

● 版本号不匹配:如软件包名称、界面版本号;

易用性

● 关键步骤错误或缺失,无法指导用户完成任务;

● 缺少必要的前提条件、注意事项等;

● 图形、表格、文字等晦涩难懂;

● 逻辑不清晰,该分类、分项、分步骤的没有给出;

正确性

● 技术原理、功能、规格等描述和软件不一致,存在错误;

● 原理图、架构图等存在错误;

● 命令、命令参数等错误;

● 代码片段错误;

● 命令无法完成对应功能;

● 界面错误,无法指导操作;

风险提示

● 对重要数据或系统存在风险的操作,缺少安全提示;

内容合规

● 违反法律法规,涉及政治、领土主权等敏感词;

● 内容侵权;

您对文档的总体满意度

非常不满意
非常满意
创Issue赢奖品
根据您的反馈,会自动生成issue模板。您只需点击按钮,创建issue即可。