Long-Term Supported Versions

    Configuring a VM


    Different from Libvirt that uses XML files to configure VMs, StratoVirt can use command line parameters or the JSON file to configure the VM CPU, memory, and disk information. This section describes the two configuration methods.

    If both methods can be used, incline to the command line configuration.

    In this document, /path/to/socket is the socket file in the user-defined path.


    • Number of VM CPUs: [1,254]
    • VM memory size: [128MiB,512GiB]
    • Number of VM disks (including hot swap disks): [0,6]
    • Number of VM NICs (including hot swap NICs): [0,2]
    • The VM console device supports only single way connection.
    • On the x86_64 platform, a maximum of 11 mmio devices can be configured. But a maximum of two other devices except disks and NICs is recommended. On the AArch64 platform, the maximum of mmio devices is 160, but the maximum of other devices is recommend to be 12, also excluding disks and NICs.

    Minimum Configuration

    The minimum configuration of the StratoVirt is as follows:

    • There is a Linux kernel file in PE format.
    • Set the rootfs image as the virtio-blk device and add it to kernel parameters.
    • Use api-channel to control StratoVirt.
    • If you want to use ttyS0 for login, add a serial port to the startup command line and add ttyS0 to kernel parameters.

    Command Line Configuration


    Command line configuration directly specifies the VM configuration content using command line parameters.

    Command Format

    The format of the command configured by running the cmdline command is as follows:

    $ /path/to/stratovirt -[Parameter 1] [Parameter Option] -[Parameter 2] [Parameter Option] ...


    1. To ensure that the socket required by api-channel can be created, run the following command to clear the environment:

      $rm [parameter] [user-defined socket file path]
    2. Run the cmdline command.

      $ /path/to/stratovirt -[Parameter 1] [Parameter Option] -[Parameter 2] [Parameter Option] ...

    Parameter Description

    The following table lists the parameters of the cmdline command.

    Table 1 Description of command line configuration parameters

    -nameVMNameConfigures the VM name (a string of 1 to 255 characters).
    -kernel/path/to/vmlinux.binConfigures the kernel image.
    -appendconsole=ttyS0 root=/dev/vda reboot=k panic=1Configures kernel command line parameters.
    -initrd/path/to/initrd.imgConfigures the initrd file.
    -smp[cpus=] Number of CPUsConfigures the number of CPUs. The value range is [1,254].
    -mByte/MiB/GiBConfigures the memory size. The value range is [128MiB,512GiB].
    -driveid=rootfs,file=/path/to/rootfs[,readonly=false,direct=true,serial=serial_num]Configures the virtio-blk device.
    -netdevid=iface_id,netdev=tap0[,mac=mac_address]Configures the virtio-net device.
    -chardevid=console_id,path=/path/to/socketConfigures virtio-console. Ensure that the socket file does not exist before running the command.
    -devicevsock,id=vsock_id,guest-cid=3Configures vhost-vsock.
    -api-channelunix:/path/to/socketConfigures api-channel. Before running this command, ensure that the socket file does not exist.
    -serialstdioConfigures a serial port device.
    -D/path/to/logfileConfigures log files.
    -pidfile/path/to/pidfileConfigures the PID file. This parameter must be used together with -daemonize.
    -disable-seccompN/ADisables the Seccomp, which is enabled by default.
    -omit_vm_memoryN/ADo not dump the VM memory when the process enters the panic state.
    -daemonizeN/AEnables the daemon process.


    1. Delete the socket file to ensure that the api-channel can be created.

      $ rm -f /tmp/stratovirt.socket
    2. Run StratoVirt.

      $ /path/to/stratovirt \
          -kernel /path/to/vmlinux.bin \
          -append console=ttyS0 root=/dev/vda rw reboot=k panic=1 \
          -drive file=/home/rootfs.ext4,id=rootfs,readonly=false \
          -api-channel unix:/tmp/stratovirt.socket \
          -serial stdio

      After the running is successful, the VM is created and started based on the specified configuration parameters.

    JSON Configuration


    Configuration using the JSON file indicates that when running StratoVirt to create a VM, the system reads the specified JSON file that contains the VM configuration.

    Command Format

    The format of the command for configuring a VM using the JSON file is as follows. In this command, /path/to/json indicates the path of the corresponding file.

    $ /path/to/stratovirt -config /path/to/json -[Parameter] [Parameter Option]


    1. Create a JSON file and write the VM configuration to the file.

    2. Run the StratoVirt command to create a VM.

      $ /path/to/stratovirt -config /path/to/json - [Parameter] [Parameter Option]

    Parameter Description

    The following table describes the configurable parameters in the JSON file.

    Table 2 Parameters in the configuration file

    boot-source"kernel_image_path": "/path/to/vmlinux.bin","boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/vda quiet","initrd_fs_path": "/path/to/initrd.img"Configures the kernel image and kernel parameters. The initrd_fs_path parameter is optional.
    machine-config"name": "abc","vcpu_count": 4,"mem_size": 805306368,"omit_vm_memory": trueConfigures the virtual CPU and memory size. The omit_vm_memory parameter is optional.
    drive"drive_id": "rootfs","path_on_host": "/path/to/rootfs.ext4","read_only": false,"direct": true,"serial_num": "xxxxx"Configures the virtio-blk disk. The serial_num parameter is optional.
    net"iface_id": "net0","host_dev_name": "tap0","mac": "xx:xx:xx:xx:xx:xx"Configures the virtio-net NIC. The mac parameter is optional.
    console"console_id": "charconsole0","socket_path": "/path/to/socket"Configures the virtio-console serial port. Before running the serial port, ensure that the socket file does not exist.
    vsock"vsock_id": "vsock0","guest_cid": 3Configures the virtio-vsock device.
    serial"stdio": trueConfigures a serial port device.

    The following table lists the parameters running in JSON.

    Table 3 Parameters running in JSON

    -config/path/to/jsonConfigures the file path.
    -api-channelunix:/path/to/socketConfigures api-channel. Before running this command, ensure that the socket file does not exist.
    -D/path/to/logfileConfigures log files.
    -pidfile/path/to/pidfileConfigures the PID file, which must be used together with daemonize. Before running the command, make sure that the PID file does not exist.
    -disable-seccompN/ADisables the Seccomp, which is enabled by default.
    -daemonizeN/AEnables the daemon process.


    1. Create a JSON file, for example, /home/config.json. The file content is as follows:
      "boot-source": {
        "kernel_image_path": "/path/to/vmlinux.bin",
        "boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/vda quiet"
      "machine-config": {
        "name": "abc",
        "vcpu_count": 2,
        "mem_size": 268435456,
        "omit_vm_memory": false
      "drive": [
          "drive_id": "rootfs",
          "path_on_host": "/path/to/rootfs.ext4",
          "direct": true,
          "read_only": false,
          "serial_num": "abcd"
      "net": [
          "iface_id": "net0",
          "host_dev_name": "tap0",
          "mac": "0e:90:df:9f:a8:88"
      "console": {
        "console_id": "charconsole0",
        "socket_path": "/path/to/console.socket"
      "serial": {
        "stdio": true
      "vsock": {
        "vsock_id": "vsock-123321132",
        "guest_cid": 4
    1. Run StratoVirt to read the JSON file and create and start the VM.
    $ /path/to/stratovirt \
        -config /home/config.json \
        -api-channel unix:/tmp/stratovirt.socket

    Successful execution of the command indicates that the VM is successfully created and started.

    Bug Catching

    Buggy Content

    Bug Description

    Submit As Issue

    It's a little complicated....

    I'd like to ask someone.


    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.


    ● Incorrect or missing key steps;

    ● Missing prerequisites or precautions;

    ● Ambiguous figures, tables, or texts;

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


    ● 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
    Click to create an issue. An issue template will be automatically generated based on your feedback.
    Bug Catching
    编组 3备份