LTS

    Innovation Version

      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}}
      

      Bug Catching

      Buggy Content

      Bug Description

      Submit As Issue

      It's a little complicated....

      I'd like to ask someone.

      PR

      Just a small problem.

      I can fix it online!

      Bug Type
      Specifications and Common Mistakes

      ● Misspellings or punctuation mistakes;

      ● Incorrect links, empty cells, or wrong formats;

      ● Chinese characters in English context;

      ● Minor inconsistencies between the UI and descriptions;

      ● Low writing fluency that does not affect understanding;

      ● Incorrect version numbers, including software package names and version numbers on the UI.

      Usability

      ● Incorrect or missing key steps;

      ● Missing prerequisites or precautions;

      ● Ambiguous figures, tables, or texts;

      ● Unclear logic, such as missing classifications, items, and steps.

      Correctness

      ● Technical principles, function descriptions, or specifications inconsistent with those of the software;

      ● Incorrect schematic or architecture diagrams;

      ● Incorrect commands or command parameters;

      ● Incorrect code;

      ● Commands inconsistent with the functions;

      ● Wrong screenshots.

      Risk Warnings

      ● Lack of risk warnings for operations that may damage the system or important data.

      Content Compliance

      ● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

      ● Copyright infringement.

      How satisfied are you with this document

      Not satisfied at all
      Very satisfied
      Submit
      Click to create an issue. An issue template will be automatically generated based on your feedback.
      Bug Catching
      编组 3备份