# StratoVirt Guidebook

## 1. General Setting

StratoVirt можно запустить только через аргументы командной строки.

### 1.1 Machine Config

Общая конфигурация машины, включая:
* type: тип машины, доступны три типа машин: «none», «microvm», «q35» (платформа x86_64) и «virt» (платформа aarch64).
* dump-guest-core: включение гостевой памяти в файл coredump или нет, значение по умолчанию — true.
* mem-share: гостевая память доступна для совместного использования с другими процессами или нет. По умолчанию эта опция отключена.
* accel: модуль ускорения, поддерживаемое значение `kvm`. (необязательно). Если не установлено, по умолчанию используется KVM.
* usb: использовать ли USB. поддерживаемое значение `off`. (необязательно). Если не задано, по умолчанию отключено.

NB: тип машины «none» используется для получения возможностей stratovirt.

```shell
# cmdline
-machine [type=]name[,dump-guest-core={on|off}][,mem-share={on|off}]
```

### 1.2 CPU Config

#### 1.2.1 CPU Number

StratoVirt поддерживает настройку количества VCPU (**nr_vcpus**).

Это позволяет вам установить максимальное количество VCPU, которое будет поддерживать виртуальная машина. Максимальное значение — 254, а минимальное разумное значение — 1.

По умолчанию после загрузки виртуальная машина подключит все настроенные вами процессоры.
Для `smp` поддерживаются четыре свойства:
* cpus: количество VCPU.
* maxcpus: максимальное количество VCPU.
* sockets: количество сокетов. (необязательно). Если не указано, его значение зависит от значения `maxcpus`. На машине arm, если вы запускаете microvm, значение socket должно быть пока равно единице.
* dies: количество кристаллов. (необязательно). Если не указано, по умолчанию равен единице.
* clusters: количество кластеров. (необязательно). Если не указано, по умолчанию равен единице.
* cores: количество ядер. (необязательно). Если не указано, его значение зависит от значения `maxcpus`.
* threads: количество потоков. (необязательно). Если не указано, его значение зависит от значения `maxcpus`.

NB: аргументы топологии процессора используются для взаимодействия с libvirt.

Если он настроен, сокеты * кристаллы * кластеры * ядра * потоки должны быть равны `maxcpus`, а `maxcpus` должен быть больше или равен `cpus`.


```shell
# cmdline
-smp [cpus=]n[,maxcpus=<maxcpus>][,sockets=<sockets>][,dies=<dies>][,clusters=<clusters>][,cores=<cores>][,threads=<threads>]
```

#### 1.2.2 CPU Features

StratoVirt позволяет настраивать функции процессора.

В настоящее время поддерживаются следующие параметры:

* CPU Family: Установите семейство процессоров для виртуальной машины, по умолчанию `host`, и это единственный поддерживаемый вариант в настоящее время.
* pmu: Включает PMU armv8 для виртуальной машины. Должно быть `off` или `on`, по умолчанию `off`. (В настоящее время поддерживается только на aarch64)
* sve: Включает функцию SVE для виртуальной машины. Должен быть `off` или `on`, по умолчанию `off`. (В настоящее время поддерживается только на aarch64)

```shell
# cmdline
-cpu host[,pmu={on|off}][,sve={on|off}]
```

### 1.3 Memory

#### 1.3.1 Memory Size

StratoVirt поддерживает установку размера памяти виртуальной машины в командной строке.

Это позволяет установить размер памяти, который будет поддерживать виртуальная машина.
Можно выбрать `G` в качестве единицы измерения (по умолчанию единица измерения — `M`). Размер памяти должен быть целым числом.

Размер памяти виртуальной машины по умолчанию составляет 256 МБ. Поддерживаемый размер памяти виртуальной машины составляет от [128 МБ, 512 ГБ].

```shell
# cmdline
-m [size=]<megs>[m|M|g|G]

-m 256m
-m 256
-m 1G
```

#### 1.3.2 Memory Prealloc
Функция предварительного выделения памяти используется для предварительного выделения физической памяти виртуальной машины и создания её таблиц страниц.
Используя эту функцию, количество ошибок страниц уменьшится, а производительность доступа к памяти виртуальной машины улучшится.

Примечание: Эта опция повлияет на время запуска виртуальной машины.

Вы можете использовать следующую командную строку для настройки предварительного распределения памяти.

```shell
-mem-prealloc
```

### 1.4 Backend file of memory

StratoVirt поддерживает настройку файла бэкенда памяти виртуальной машины.

Это позволяет указать путь к файлу бэкенда, который может быть либо каталогом, либо файлом.
Путь должен быть абсолютным путём.

```shell
# cmdline
-mem-path <filebackend_path>
```

#### 1.4.1 hugepages

Файл бэкенда памяти можно использовать, чтобы позволить гостю использовать hugetlbfs на хосте. Он поддерживает страницы памяти размером 2 Мбайт или 1 Гбайт.
Следующие шаги показывают, как использовать огромные страницы:

```shell
# mount hugetlbfs в каталоге на хосте
$ mount -t hugetlbfs hugetlbfs /path/to/hugepages

# установите количество огромных страниц

*Примечание: В тексте запроса присутствуют фрагменты кода на языке программирования Shell, но они не были переведены.* **Параметры ядра**

```shell
# cmdline
-initrd <путь_к_initrd>
```

### 1.8 Глобальная конфигурация

Пользователи могут задать глобальную конфигурацию с помощью параметра -global.

Можно установить одно свойство:

* pcie-root-port.fast-unplug: переключатель функции быстрого отключения, поддерживается только Kata.

```shell
-global pcie-root-port.fast-unplug={0|1}
```

### 1.9 Логирование

StratoVirt поддерживает вывод журнала в stderr и файл журнала.

Вы можете включить логирование StratoVirt с помощью:

```shell
# Вывод журнала в stderr
-D
# Вывод журнала в файл журнала
-D <путь_к_файлу_журнала>
```

Уровень логирования StratoVirt зависит от переменной среды `STRATOVIRT_LOG_LEVEL`.
StratoVirt поддерживает пять уровней логирования: `trace`, `debug`, `info`, `warn`, `error`. По умолчанию уровень равен `error`.
Если параметр -D не установлен, журналы по умолчанию выводятся в stderr.

### 1.10 Запуск в качестве демона

StratoVirt может работать как демон.

```shell
# cmdline
-daemonize
```

**При запуске StratoVirt в качестве демона вам не разрешается связывать последовательный порт с stdio или выводить журнал в stdio.**

Также вы можете восстановить **номер pid** StratoVirt в файле с помощью:

```shell
# cmdline
-pidfile <путь_к_pid_файлу>
```

### 1.11 SMBIOS
Спецификация SMBIOS определяет структуры данных и информацию, которая будет входить в структуры данных, связанные с системой. Наличие этих полей позволяет системным администраторам удалённо идентифицировать и управлять этими системами.

```shell
# cmdline
# тип 0: информация о BIOS, поддержка версии и даты выпуска строки.
-smbios type=0[,vendor=str][,version=str][,date=str]
# тип 1: Информация о системе, информация в этой структуре определяет атрибуты
# общей системы и предназначена для связи с группой Component ID системного MIF.
-smbios type=1[,manufacturer=str][,version=str][,product=str][,serial=str][,uuid=str][,sku=str][,family=str]
# тип 2: Информация о базовой плате, информация в этой структуре определяет атрибуты базовой платы системы
# (например, материнская плата, планарный, серверный блейд или другой стандартный системный модуль).
-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]
# тип 3: Информация об оболочке системы, определяет атрибуты механической оболочки(ов) системы.
# Например, если система включала отдельную оболочку для своих периферийных устройств,
# будут возвращены две структуры: одна для основной системной оболочки и вторая для оболочки периферийного устройства.
-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]
# тип 4: Информация о процессоре, определяет атрибуты одного процессора;
# отдельный экземпляр структуры предоставляется для каждого процессорного сокета/слота системы.
# Например, система с процессором IntelDX2 будет иметь один экземпляр структуры,
# а система с процессором IntelSX2 будет иметь структуру для описания основного процессора
# и вторую структуру для описания сопроцессора 80487.
-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str][,max-speed=%d][,current-speed=%d]
# тип 17: Устройство памяти, эта структура описывает отдельное устройство памяти.
-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]

## 2. Конфигурация устройства

Для типа машины «microvm» поддерживаются только virtio-mmio и устаревшие устройства. Максимальное количество пользовательских создаваемых устройств составляет 11 на x86_64 и 160 на aarch64.

Для стандартной виртуальной машины (тип машины «q35» на x86_64, и «virt» на aarch64) вместо virtio-mmio поддерживаются устройства virtio-pci. Что касается мостов PCI, они пока не реализованы, в настоящее время существует только один корневой автобус с именем pcie.0. В результате можно настроить всего 32 устройства PCI.

### 2.1 iothread

Iothread используется устройствами для повышения производительности ввода-вывода. StratoVirt создаст несколько дополнительных потоков из-за конфигурации iothread, и эти потоки могут использоваться исключительно устройствами, что повышает производительность.

Примечание: настоятельно рекомендуется использовать iothread, если конкретное устройство его поддерживает, иначе есть риск того, что основной поток зависнет. **Virtio-blk**

Virtio block device — это виртуальное блочное устройство, которое обрабатывает запросы на чтение и запись в очереди virtio от гостя.

Для virtio block device поддерживаются четырнадцать свойств:
* id: уникальный идентификатор устройства в StratoVirt.
* file: путь к файлу бэкэнда на хосте.
* serial: серийный номер virtio блока (необязательно).
* readonly: является ли virtio блок устройством только для чтения (необязательно). Если не установлено, по умолчанию используется значение false.
* direct: открыть блочное устройство с режимом O_DIRECT (необязательно). Если не установлено, по умолчанию используется значение true.
* iothread: указать, какой поток io будет использоваться (необязательно). Если не указано, будет использоваться основной поток.
* throttling.iops-total: используется для ограничения операций ввода-вывода для блочного устройства (необязательно).
* discard: освободить неиспользуемое дисковое пространство (необязательно). «unmap/ignore» означает «включено/выключено». Если не установлено, по умолчанию используется значение ignore.
* detect-zeroes: оптимизировать запись нулей на диск (необязательно). «unmap» означает, что можно освободить дисковое пространство при использовании discard «unmap». Если discard установлен как «ignore», «unmap» detect-zeroes равнозначно «on». Если не установлено, по умолчанию используется значение off.
* if: тип диска, для блочного диска должно быть «none» (необязательно). Если не установлено, по умолчанию используется значение none.
* format: формат образа блока (необязательно). Возможные значения: «raw» или «qcow2». Если не установлено, по умолчанию используется «raw». NB: в настоящее время для microvm поддерживается только «raw».
* num-queues: атрибут num-queues контролирует количество очередей, которые будут использоваться для блочного устройства (необязательно). Максимальное количество поддерживаемых очередей — 32. Если не установлено, количество блоков по умолчанию — наименьшее из количества vCPU и максимального количества очередей (например, min(vcpu_count, 32)).
* bootindex: порядок загрузки блочного устройства (необязательно). Если не установлено, приоритет наименьший. Число колеблется от 0 до 255, чем меньше число, тем выше приоритет. Определяет порядок загрузочных устройств, которые прошивка будет использовать для загрузки гостевой ОС.
* aio: тип aio блочного устройства (необязательно). Возможные значения: «native», «io_uring» или «off». Если не установлено, используется «native» при значении «direct» true, в противном случае используется «off» по умолчанию.

Для virtio-blk-pci требуются ещё четыре свойства:
* bus: имя шины, к которой нужно подключиться.
* addr: включая номер слота и номер функции. Первое число представляет номер слота устройства, а второе — номер его функции.
* multifunction: открывать ли мультифункцию для устройства (необязательно). Если не установлено, по умолчанию используется значение false.
* queue-size: необязательный размер virtqueue для всех очередей (необязательно). Диапазон конфигурации составляет (2, 1024], и размер очереди должен быть степенью двойки. Размер очереди по умолчанию равен 256.

Если вы хотите загрузить виртуальную машину с virtio блоком в качестве rootfs, вам следует добавить «root=DEVICE_NAME_IN_GUESTOS» в параметры ядра. DEVICE_NAME_IN_GUESTOS будет от vda до vdz по порядку.

```shell
# virtio mmio block device.
-drive id=<drive_id>,file=<path_on_host>[,readonly={on|off}][,direct={on|off}][,throttling.iops-total=<limit>][,discard={unmap|ignore}][,detect-zeroes={unmap|on|off}]
-device virtio-blk-device,drive=<drive_id>,id=<blkid>[,iothread=<iothread1>][,serial=<serial_num>]
# virtio pci block device.
-drive id=<drive_id>,file=<path_on_host>[,readonly={on|off}][,direct={on|off}][,throttling.iops-total=<limit>][,discard={unmap|ignore}][,detect-zeroes={unmap|on|off}]
-device virtio-blk-pci,id=<blk_id>,drive=<drive_id>,bus=<pcie.0>,addr=<0x3>[,multifunction={on|off}][,iothread=<iothread1>][,serial=<serial_num>][,num-queues=<N>][,bootindex=<N>][,queue-size=<queuesize>]

StratoVirt также поддерживает vhost-user-blk для повышения производительности хранилища.

Вы можете использовать его, добавив новое устройство, ещё одно свойство поддерживается устройством vhost-user-blk, кроме virtio-blk.

* chardev: id для символьного устройства, это означает, что вам нужно сначала добавить chardev, а затем использовать его id, чтобы найти символьное устройство.

```shell
# vhost user blk mmio device
-chardev socket,id=<chardevid>,path=<socket_path>
-device vhost-user-blk-device,id=<blk_id>,chardev=<chardev_id>[,num-queues=<N>][,queue-size=<queuesize>]
# vhost Функция number должна быть установлена в ноль.

* queue-size: необязательный размер virtqueue для всех очередей. (необязательно) Диапазон конфигурации составляет [256, 4096], и размер очереди должен быть степенью двойки. Размер очереди по умолчанию равен 256.
```shell
# virtio mmio net device
-netdev tap,id=<netdevid>,ifname=<host_dev_name>
-device virtio-net-device,id=<net_id>,netdev=<netdev_id>[,iothread=<iothread1>][,mac=<macaddr>]
# virtio pci net device
-netdev tap,id=<netdevid>,ifname=<host_dev_name>[,queues=<N>]
-device virtio-net-pci,id=<net_id>,netdev=<netdev_id>,bus=<pcie.0>,addr=<0x2>[,multifunction={on|off}][,iothread=<iothread1>][,mac=<macaddr>][,mq={on|off}][,queue-size=<queuesize>]
```

StratoVirt также поддерживает vhost-net для повышения производительности в сети. Его можно настроить, указав свойство `vhost`, и поддерживается ещё одно свойство для устройства vhost-net.

* vhostfd: fd для устройства vhost-net, его можно настроить при `vhost=on`. Если этот аргумент не указан при `vhost=on`, StratoVirt получает его, открывая `/dev/vhost-net` автоматически.

```shell
# virtio mmio net device
-netdev tap,id=<netdevid>,ifname=<host_dev_name>[,vhost=on[,vhostfd=<N>]]
-device virtio-net-device,id=<net_id>,netdev=<netdev_id>[,iothread=<iothread1>][,mac=<macaddr>]
# virtio pci net device
-netdev tap,id=<netdevid>,ifname=<host_dev_name>[,vhost=on[,vhostfd=<N>,queues=<N>]]
-device virtio-net-pci,id=<net_id>,netdev=<netdev_id>,bus=<pcie.0>,addr=<0x2>[,multifunction={on|off}][,iothread=<iothread1>][,mac=<macaddr>][,mq={on|off}]
```

StratoVirt также поддерживает vhost-user net для повышения производительности с помощью ovs-dpdk. При использовании vhost-user net следует открыть общую память (`-mem-share=on`) и огромные страницы (`-mem-path ...`), если используется vhost-user net.

```shell
# virtio mmio net device
-chardev socket,id=chardevid,path=socket_path
-netdev vhost-user,id=<netdevid>,chardev=<chardevid>
-device virtio-net-device,id=<net_id>,netdev=<netdev_id>[,iothread=<iothread1>][,mac=<macaddr>]
# virtio pci net device
-chardev socket,id=chardevid,path=socket_path
-netdev vhost-user,id=<netdevid>,chardev=<chardevid>[,queues=<N>]
-device virtio-net-pci,id=<net_id>,netdev=<netdev_id>,bus=<pcie.0>,addr=<0x2>[,multifunction={on|off}][,iothread=<iothread1>][,mac=<macaddr>][,mq={on|off}]
```

**Как настроить устройство tap?**

```shell
# На хосте
$ brctl addbr qbr0
$ ip tuntap add tap0 mode tap
$ brctl addif qbr0 tap0
$ ip link set qbr0 up
$ ip link set tap0 up
$ ip address add 1.1.1.1/24 dev qbr0

# Запустить StratoVirt
... -netdev tap,id=netdevid,ifname=tap0 ...

# В гостевой системе
$ ip link set eth0 up
$ ip addr add 1.1.1.2/24 dev eth0

# Теперь сеть доступна
$ ping 1.1.1.1
```

Примечание: Если вы хотите использовать несколько очередей, создайте устройство tap следующим образом:
```shell
# На хосте
$ brctl addbr qbr0
$ ip tuntap add tap1 mode tap multi_queue
$ brctl addif qbr0 tap1
$ ip link set qbr0 up
$ ip link set tap1 up
$ ip address add 1.1.1.1/24 dev qbr0
```

**Как создать порт с помощью ovs-dpdk?**

```shell
# Запуск демонов open vSwitch
$ ovs-ctl start
# Инициализация базы данных
$ ovs-vsctl init
# Инициализация dpdk
$ ovs-vsctl set Open_vSwitch . other_config:dpdk-init=true
# Настройка маски lcore для dpdk
$ ovs-vsctl set Open_vSwitch . other_config:dpdk-lcore-mask=0xf
# Настройка огромных страниц для dpdk-socket-mem (2G)
$ ovs-vsctl set Open_vSwitch . other_config:dpdk-socket-mem=1024
# Настройка PMD (Pull Mode Driver) маски CPU
$ ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=0xf
# Добавление моста
$ ovs-vsctl add-br ovs_br -- set bridge ovs_br datapath_type=netdev
# Добавление порта
$ ovs-vsctl add-port ovs_br port1 -- set Interface port1 type=dpdkvhostuser
$ ovs-vsctl add-port ovs_br port2 -- set Interface port2 type=dpdkvhostuser
# Установка количества rxq/txq
$ ovs-vsctl set Interface port1 options:n_rxq=num,n_txq=num
$ ovs-vsctl set Interface port2 options:n_rxq=num,n_txq=num
```

### 2.4 Virtio-console

Устройство virtio console — это простое устройство для передачи данных между гостевой и хост-системой. Консольное устройство может иметь один или несколько портов. Эти порты могут быть обычными портами или консольными портами. Символьные устройства /dev/vport\*p\* в гостевой операционной системе Linux будут созданы после настройки порта (независимо от того, является ли он консольным портом или нет). Символьные устройства находятся на В запросе используется язык **технической направленности**, связанный с разработкой и тестированием программного обеспечения. Основной язык текста запроса — английский.

**Перевод на русский язык:**

/dev/hvc0 to /dev/hvc7 в гостевой системе Linux будет создан после настройки порта консоли. Для настройки virtio-консоли потребуется перенаправление chardev. Подробнее см. раздел 2.12 Chardev (#212-chardev).

Для virtconsole (порт консоли) и virtserialport (общий порт) можно задать три свойства:
* id: уникальный идентификатор устройства.
* chardev: символьное устройство этой консоли/общего порта.
* nr: уникальный номер порта для этого порта. (необязательно) Если установлено, все virtserialports и virtconsoles должны быть установлены. nr = 0 разрешено только для virtconsole. По умолчанию nr для общего порта начинается с 1, а для порта консоли — с 0. Если не установлено, nr = 0 будет присвоен первому порту консоли в командной строке. И nr = 0 будет зарезервирован, если в командной строке нет порта консоли.

Для virtio-serial-pci требуется ещё четыре свойства:
* bus: номер шины virtio-консоли.
* addr: включая номер слота и номер функции. Первое число представляет номер слота устройства, второе — номер его функции.
* multifunction: открывать ли мультифункцию для устройства. (необязательно) Если не задано, по умолчанию используется значение false.
* max_ports: максимальное количество портов, которое мы можем иметь для устройства virtio-serial. Диапазон конфигурации [1, 31]. (необязательно) Если не установлено, по умолчанию равно 31.

Для virtio-serial-device требуются ещё два свойства:
* bus: номер шины virtio-консоли.
* addr: включая номер слота и номер функции. Первое число представляет номер слота устройства, второе — номер его функции.

```shell
# virtio mmio device using console port
-device virtio-serial-device[,id=<virtio-serial0>]
-chardev socket,path=<socket_path>,id=<virtioconsole1>,server,nowait
-device virtconsole,id=<console_id>,chardev=<virtioconsole1>,nr=0

# virtio mmio device using generic port
-device virtio-serial-device[,id=<virtio-serial0>]
-chardev socket,path=<socket_path>,id=<virtioserialport1>,server,nowait
-device virtserialport,id=<serialport_id>,chardev=<virtioserialport1>,nr=0

# virtio pci device
-device virtio-serial-pci,id=<virtio-serial0>,bus=<pcie.0>,addr=<0x3>[,multifunction={on|off},max_ports=<number>]
-chardev socket,path=<socket_path0>,id=<virtioconsole0>,server,nowait
-device virtconsole,id=<portid0>,chardev=<virtioconsole0>,nr=0
-chardev socket,path=<socket_path1>,id=<virtioconsole1>,server,nowait
-device virtserialport,id=<portid1>,chardev=<virtioconsole1>,nr=1
```
NB: В настоящее время поддерживается только одно virtio-устройство консоли. В microvm поддерживается только один порт.

### 2.5 Virtio-vsock

Virtio vsock — это устройство связи хост/гость, похожее на virtio-консоль, но имеющее более высокую производительность.

Если вы хотите использовать его, вам необходимо:

* Конфигурация ядра хоста: CONFIG_VHOST_VSOCK=m.
* Конфигурация гостевого ядра: CONFIG_VIRTIO_VSOCKETS=y.

И `modprobe vhost_vsock` на хосте.

Три свойства могут быть заданы для устройства virtio vsock:

* vsock_id: уникальный идентификатор устройства в StratoVirt.
* guest_cid: уникальный Context-ID на хосте для каждого гостя, он должен удовлетворять `3<=guest_cid<u32:MAX`.
* vhostfd: fd устройства vsock. (необязательно).

Для vhost-vsock-pci требуются ещё две характеристики:
* bus: имя шины, к которой нужно подключиться.
* addr: включая номер слота и номер функции. Первый номер представляет номер слота
устройства, второй — номер функции устройства.

```shell
# virtio ммio устройство.
-device vhost-vsock-device,id=<vsock_id>,guest-cid=<N>

# virtio устройство pci.
-device vhost-vsock-pci,id=<vsock_id>,guest-cid=<N>,bus=<pcie.0>,addr=<0x3>[,multifunction={on|off}]
```

Можно установить только одно устройство virtio vsock для одной виртуальной машины.

Также можно использовать [`nc-vsock`](https://github.com/stefanha/nc-vsock) для тестирования virtio-vsock.

```shell
# В гостевой системе
$ nc-vsock -l port_num

# На хосте
$ nc-vsock guest_cid port_num
```

### 2.6 Serial

Serial — устаревшее устройство для виртуальных машин, это интерфейс связи, который соединяет гостя и хост.

Обычно мы используем serial как ttyS0 для вывода консольных сообщений в StratoVirt.

В StratoVirt есть два способа настроить serial и связать его с символьным устройством хоста.
NB: Можно настроить только *один* serial. **Требуется. См. раздел 2.12 Chardev**

```shell
# Добавить chardev и перенаправить последовательный порт на chardev
-chardev backend,id=<chardev_id>[,path=<путь>,server,nowait]
-serial chardev:chardev_id
```

Или вы можете просто использовать `-serial dev`, чтобы связать последовательный интерфейс с символьным устройством.

```shell
# Упрощённые методы перенаправления
-serial stdio
-serial pty
-serial socket,path=<socket_path>,server,nowait
-serial socket,port=<порт>[,host=<хост>],server,nowait
-serial file,path=<file_path>
```

**2.7 Virtio-balloon**

Balloon — это устройство virtio, оно предлагает гибкий механизм памяти для виртуальной машины (VM).

Для virtio-balloon поддерживаются два свойства:
* deflate_on_oom: Сжимать баллон при нехватке памяти у гостя. Если deflate_on_oom не было согласовано, драйвер НЕ ДОЛЖЕН использовать страницы из баллона, когда num_pages меньше или равно фактическому количеству страниц в баллоне. Если было согласовано deflate_on_oom, драйвер МОЖЕТ использовать страницы из баллона, если это требуется для стабильности системы (например, если память требуется приложениям, работающим внутри гостя). Эта функция может предотвратить OOM в гостевой системе.
* free_page_reporting: сообщать о свободных гостевых страницах. Эту функцию можно использовать для повторного использования памяти.

Для virtio-balloon-pci требуются ещё два свойства:
* bus: имя шины, к которой нужно подключиться.
* addr: включая номер слота и номер функции. Первое число представляет номер слота устройства, а второе — номер его функции.

```shell
# Устройство mmio virtio balloon
-device virtio-balloon-device[,deflate-on-oom={true|false}][,free-page-reporting={true|false}]
# Устройство PCI virtio balloon
-device virtio-balloon-pci,id=<balloon_id>,bus=<pcie.0>,addr=<0x4>[,deflate-on-oom={true|false}][,free-page-reporting={true|false}][,multifunction={on|off}]
```

Примечание: избегайте совместного использования устройств balloon и vfio, устройство balloon недействительно, когда память — огромные страницы. Размер памяти balloon должен быть целым числом, кратным размеру гостевой страницы.

**2.8 Virtio-rng**

Virtio rng — это паравиртуализированный генератор случайных чисел, он предоставляет гостю аппаратное устройство rng.

Если вы хотите его использовать, вам потребуется:

* Конфигурация ядра гостя: CONFIG_HW_RANDOM=y CONFIG_HW_RANDOM_VIA=y CONFIG_HW_RANDOM_VIRTIO=y

Поддерживаются пять свойств для virtio-rng:
* filename: путь символьного устройства, генерирующего случайные числа на хосте.
* period: период таймера для ограничения скорости потока символов. Единица измерения — миллисекунды.
* max-bytes: максимальное количество байтов, которое символьное устройство генерирует со случайным числом за «период» времени.

Для virtio-rng-pci необходимы ещё два свойства:
* bus: название шины, к которой необходимо подключиться.
* addr: включая номер слота и номер функции. Первое число представляет собой номер слота устройства, а второе — номер его функции. Поскольку устройство virtio pci rng является однофункциональным устройством, номер функции следует установить равным нулю.

NB:
* Ограниченная скорость будет преобразована в байты/сек. Например, если period=100, max-bytes=100; окончательный результат заключается в том, что максимальное количество байт, сгенерированных устройством rng, составляет 1000.
* Ограниченная скорость должна быть между 64 (включительно) и 1000000000 (включительно), то есть: 64 <= max-bytes/period * 1000 <= 1000000000.

```shell
# Устройство rng-random mmio
-object rng-random,id=<objrng0>,filename=<random_file_path>
-device virtio-rng-device,rng=<objrng0>,max-bytes=<1234>,period=<1000>
# Устройство virtio pci rng
-object rng-random,id=<objrng0>,filename=<random_file_path>
-device virtio-rng-pci,id=<rng_id>,rng=<objrng0>[,max-bytes=<1234>][,period=<1000>],bus=<pcie.0>,addr=<0x1>[,multifunction={on|off}]
```

**2.9 PCIe root port**

Порт PCI Express на корневом комплексе, который сопоставляет часть иерархии через связанный виртуальный мост PCI-PCI.

Четыре параметра поддерживаются для pcie root port:
* port: номер порта корневого порта.
* bus: имя шины, к которой необходимо подключиться.
* addr: включая номер слота и номер функции.
* id: имя вторичной шины.
* chassis: номер шасси. Взаимодействие с libvirt. Настроенный USB-контроллер может поддерживать только USB-клавиатуру и USB-планшет.

#### 2.13.2 USB-клавиатура
USB-клавиатура — это клавиатура, которая использует протокол USB. Она должна быть подключена к USB-контроллеру. Клавиатура и светодиоды пока не поддерживаются.

Для USB-клавиатуры можно задать одно свойство:
* id: уникальный идентификатор устройства.
```shell
-device usb-kbd,id=<kbd>
```
Примечание: Можно настроить только одну клавиатуру.

#### 2.13.3 USB-планшет
Указательное устройство, которое использует абсолютные координаты. Оно должно быть подключено к USB-контроллеру.

Для USB-планшета можно задать одно свойство:
* id: уникальный идентификатор устройства.

```shell
-device usb-tablet,id=<tablet>
```

Примечание: Можно настроить только один планшет.

#### 2.13.4 USB-камера
Видеокамера на основе протокола USB video class. Должна быть подключена к USB-контроллеру.

Можно задать три свойства для USB-камеры:
* id: уникальный идентификатор устройства;
* backend: тип внутреннего устройства, либо «v4l2», либо «demo»;
* path: путь к файлу, используемый для подключения к бэкэнду, требуется для «v4l2», но не для «demo». Например, /dev/video0.

```shell
-device usb-camera,id=<camera>,backend="v4l2",path="/dev/video0"
-device usb-camera,id=<camera>,backend="demo"
```

Примечание: Можно настроить только одну камеру.

Если вы хотите включить USB-камеру, см. раздел [4. Сборка с функциями](docs/build_guide.md).

#### 2.13.5 USB-накопитель
Устройство хранения данных USB, основанное на классическом протоколе передачи данных только для массовых операций. Должно быть подключено к USB-контроллеру.

Три свойства можно задать для USB-накопителя:
* id: уникальный идентификатор устройства;
* file: путь к файлу образа бэкэнда;
* media: тип носителя хранилища. Возможные значения: «диск» или «cdrom». Если не задано, по умолчанию используется «диск».

```shell
-device usb-storage,drive=<drive_id>,id=<storage_id>
-drive id=<drive_id>,file=<path_on_host>[,media={disk|cdrom}],aio=off,direct=false
```

Примечание: «aio=off, direct=false» должны быть настроены, другие значения aio/direct не поддерживаются.

#### 2.13.6 USB-хост
Устройство USB-хоста, основанное на протоколе USB. Должно быть подключено к USB-контроллеру.

Шесть свойств можно задать для USB-хоста:
* id: уникальный идентификатор устройства;
* hostbus: номер шины USB-устройства хоста;
* hostaddr: адрес номера USB-устройства хоста;
* hostport: физический номер USB-устройства хоста;
* vendorid: идентификатор поставщика USB-устройства хоста;
* productid: идентификатор продукта USB-устройства хоста.
* isobufs: количество буферов изохронной передачи. Если не указано, по умолчанию равно 4;
* isobsize: размер буфера изохронной передачи. Если не указано, по умолчанию равен 32.

Пропустить через устройство хоста, идентифицированное по шине и адресу:

```shell
-device usb-host,id=<hostid>,hostbus=<bus>,hostaddr=<addr>[,isobufs=<number>][,isobsize=<size>]
```

Пропустите через устройство хоста, идентифицированное по шине и физическому порту:

```shell
-device usb-host,id=<hostid>,hostbus=<bus>,hostport=<port>[,isobufs=<number>][,isobsize=<size>]
```

Пропустите через устройство хоста, идентифицированное по идентификатору поставщика и продукта:

```shell
-device usb-host,id=<hostid>,vendorid=<vendor>,productid=<product>[,isobufs=<number>][,isobsize=<size>]
```

Примечание:
1. Комбинация идентификатора поставщика и идентификатора продукта имеет приоритет над комбинацией номера шины и физического номера порта.
2. Комбинация номера шины и физического порта имеет приоритет перед комбинацией номера шины и адреса.

См. раздел [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить USB-хост.

### 2.14 Virtio SCSI-контроллер
Virtio SCSI-контроллер — это PCI-устройство, к которому можно подключить SCSI-устройство.

Шесть свойств можно задать для Virtio-SCSI-контроллера:
* id: уникальный идентификатор устройства;
* bus: номер шины устройства;
* addr: включая номер слота и номер функции;
* iothread: указывает, какой поток iothread будет использоваться, если не указан, будет использоваться основной поток (необязательно);
* num-queues: атрибут num-queues определяет количество очередей запросов, которые будут использоваться для SCSI-контроллера. Если не установлено, используется значение по умолчанию — 1 очередь блоков. Поддерживается максимум 32 очереди (необязательно);
* queue-size: необязательный размер virtqueue для всех очередей. Диапазон конфигурации составляет (2, 1024], а размер очереди должен быть степенью двойки. По умолчанию. **Размер очереди равен 256.**

```shell
-device virtio-scsi-pci,id=<scsi_id>,bus=<pcie.0>,addr=<0x3>[,multifunction={on|off}][,iothread=<iothread1>][,num-queues=<N>][,queue-size=<queuesize>]
```

**2.15 Virtio Scsi HardDisk**

Virtio Scsi HardDisk — это виртуальное блочное устройство, которое обрабатывает запросы на чтение и запись в очереди virtio от гостя.

Для virtio-scsi hd можно задать десять свойств.
* file: путь к файлу образа бэкэнда.
* id: уникальный идентификатор устройства.
* bus: имя шины scsi, поддерживается только $scsi_controller_name + ".0".
* scsi-id: номер идентификатора (target) четырёхуровневого иерархического адреса scsi (хост, канал, цель, lun). Диапазон конфигурации [0, 255]. Конфигурация загрузочного диска scsi [0, 31].
* lun: номер lun (lun) четырёхуровневого иерархического адреса scsi (хост, канал, цель, lun). Диапазон конфигурации [0, 255]. Диапазон конфигурации загрузочного диска scsi [0, 7].
* serial: серийный номер устройства virtio scsi. (необязательно)
* readonly: является ли устройство scsi доступным только для чтения или нет. По умолчанию false. (необязательно)
* direct: открыть блочное устройство с режимом `O_DIRECT`. (необязательно) Если не установлено, по умолчанию true.
* aio: тип aio блочного устройства (необязательно). Возможные значения: `native`, `io_uring` или `off`. Если не задано, по умолчанию `native`, если `direct` истинно, иначе по умолчанию `off`.
* bootindex: порядок загрузки устройства scsi. (необязательно) Если не установлен, приоритет наименьший.
Число варьируется от 0 до 255, чем меньше число, тем выше приоритет.
Определяет порядок загрузочных устройств, которые прошивка будет использовать для загрузки гостевой ОС.

```shell
-device virtio-scsi-pci,bus=pcie.1,addr=0x0,id=scsi0[,multifunction=on,iothread=iothread1,num-queues=4]
-drive file=path_on_host,id=drive-scsi0-0-0-0[,readonly=true,aio=native,direct=true]
-device scsi-hd,bus=scsi0.0,scsi-id=0,lun=0,drive=drive-scsi0-0-0-0,id=scsi0-0-0-0[,serial=123456,bootindex=1]
```

**2.16 Display**

Stratovirt поддерживает несколько методов отображения, включая `GTK` и `VNC`, что позволяет пользователям взаимодействовать с виртуальной машиной.

Также поддерживается отображение на OpenHarmony OS (OHOS), но требуется реализация клиентской программы.

#### 2.16.1 GTK

Графический интерфейс, нарисованный с помощью инструментария gtk. Подробнее см. на сайте [GTK](https://www.gtk.org).

Можно задать два свойства для GTK.
* appname: строка имени программы, которая будет отображаться в строке заголовка окна.
* full-screen: если настроено, начальное окно будет занимать весь экран.

Пример конфигурации:

```shell
-display gtk[,appname=<application_name>,full-screen={on|off}]
```

Примечание: перед использованием gtk необходимо убедиться, что инструментарий gtk установлен.

См. раздел [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить GTK.

#### 2.16.2 VNC

VNC может предоставить пользователям способ удалённого входа в виртуальные машины.

Чтобы использовать VNC, необходимо настроить значение ip и порта. IP-адрес можно установить на указанное значение или `0.0.0.0`, что означает, что отслеживаются все IP-адреса на сетевой карте хоста.

```shell
-vnc 0.0.0.0:0
-vnc <IP:port>
```

Шифрование TLS является необязательной конфигурацией. Можно задать три свойства для зашифрованной передачи:
* тип сертификата;
* id: уникальный объектный идентификатор;
* dir: каталог сертификатов. Вы должны поместить в этот каталог легальный институциональный сертификат, сертификат сервера и закрытый ключ для шифрования сертификата.

```shell
-object tls-creds-x509,id=<vnc-tls-creds0>,dir=</etc/pki/vnc>
```

Аутентификация является необязательной настройкой, она зависит от службы saslauth. Чтобы использовать эту функцию, вы должны убедиться, что служба saslauthd работает нормально, и настроить поддерживаемый механизм аутентификации в `/etc/sasl2/stratovirt.conf`.

Пример конфигурации для файла `/etc/sasl2/stratovirt.conf`:

```shell
# Использование службы saslauthd
pwcheck_method: saslauthd
# Механизм аутентификации
mech_list: plain
```

Можно задать три свойства для аутентификации:
* authz-simple;
* id: уникальный объектный идентификатор;
* identity: указать имя пользователя, который может войти в систему.

```shell
-object authz-simple,id=authz0,identity=username
```

Пример конфигурации:

```shell
-object **authz-simple, id=authz0, identity=username**

-object tls-creds-x509, id=vnc-tls-creds0, dir=/etc/pki/vnc
-vnc 0.0.0.0:0, tls-creds=vnc-tls-creds0, sasl=on, sasl-authz=authz0
```
Note: 1. Только один клиент может быть подключён одновременно. Последующие подключения клиентов приведут к сбою. 2. Шифрование TLS можно настроить отдельно, но аутентификацию необходимо использовать вместе с шифрованием.

Пожалуйста, обратитесь к [4. Сборка с функциями] (docs/build_guide.md), если вы хотите включить VNC.

#### 2.16.2 Сервер OHUI

Сервер OHUI поддерживает отображение на OHOS. Он опирается на UDS для связи с клиентом OHUI. По сути, он работает как VNC. Клиент получает действия клавиатуры и мыши и отправляет их на сервер, а также отображает изображение виртуальной машины на экране. Сервер обрабатывает действия клавиатуры и мыши, а также передаёт изображение виртуальной машины.

Пример конфигурации:

```shell
[-object iothread,id=<threadID>]
-display ohui[,iothread=<threadID>,socks-path=</path/to/dir>]
```

Примечание: «socks-path» указывает, где находится файл UDS. По умолчанию это /tmp.

### 2.17 Virtio-fs
Virtio-fs — это общая файловая система, которая позволяет виртуальным машинам получать доступ к дереву каталогов на хосте. В отличие от существующих подходов, она разработана для обеспечения локальной семантики файловой системы и производительности.

#### 2.17.1 Устройство virtio fs
Три свойства могут быть установлены для устройства virtio fs.
* chardevid: идентификатор символьного устройства
* device_id: уникальный идентификатор устройства
* mount_tag: тег монтирования общего каталога, который можно монтировать в гостевой системе

```shell
# vhost user fs mmio device
-chardev socket,id=<chardevid>,path=<socket_path>
-device vhost-user-fs-device,id=<device id>,chardev=<chardevid>,tag=<mount tag>
# vhost user fs pci device
-chardev socket,id=<chardevid>,path=<socket_path>
-device vhost-user-fs-pci,id=<device id>,chardev=<chardevid>,tag=<mount tag>
```

#### 2.17.2 vhost_user_fs

Примечание: двоичный файл vhost_user_fs StratoVirt был удалён. Поскольку существует новая реализация Rust virtiofsd на «https://gitlab.com/virtio-fs/virtiofsd», она помечена как стабильная, и существующий проект должен рассмотреть возможность её использования вместо неё.

*Как настроить совместное использование файлов на основе StratoVirt и virtiofsd?*

```shell
host# Настройте сервер virtiofsd, см. «https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md»

host# stratovirt \
        -machine type=q35,dump-guest-core=off,mem-share=on \
        -smp 1 \
        -m 1024 \
        -kernel <ваш образ> \
        -append root=/dev/vda console=ttyS0 reboot=k panic=1 random.trust_cpu=on rw \
        -drive file=<ваш путь к файлу>,if=pflash,unit=0 \
        -qmp unix:/tmp/qmp2.socket,server,nowait \
        -drive id=drive_id,file=<ваш образ>,direct=on \
        -device virtio-blk-pci,drive=drive_id,bug=pcie.0,addr=1,id=blk -serial stdio -disable-seccomp \
        -chardev socket,id=virtio_fs,path=/path/to/virtiofsd.sock,server,nowait \
        -device vhost-user-fs-pci,id=device_id,chardev=virtio_fs,tag=myfs,bus=pcie.0,addr=0x7

guest# mount -t virtiofs myfs /mnt
```

### 2.18 virtio-gpu
virtio-gpu — это виртуализированная видеокарта, которая позволяет виртуальным машинам отображать с её помощью. Обычно используется в сочетании с VNC, окончательные изображения отображаются на клиенте VNC.

Пример конфигурации：
```shell
-device virtio-gpu-pci,id=<ваш id>,bus=pcie.0,addr=0x2.0x0[,max_outputs=<ваш max_outputs>][,edid=true|false][,xres=<ваша ожидаемая ширина>][,yres= <ваша ожидаемая высота>][,max_hostmem=<максимальный объём памяти, который может использовать графическая карта>]
```

Помимо необходимой информации о слоте, для virtio-gpu поддерживаются пять дополнительных свойств.
* max_outputs: количество экранов, поддерживаемых текущей видеокартой. Максимальное значение — 16 (можно переключиться с помощью ctrl + alt + <num>, подробности см. в разделе «Переключение клиента VNC»).
* edid: функция Edid, ядро виртуальной машины может проверять эту функцию для HiDPi. Рекомендуется установить значение true.
* xres/yres: размер окон входа.
* max_hostmem: максимальный объём памяти, которую может занимать видеокарта на хосте, выражается в байтах. Рекомендуется устанавливать не менее 256 МиБ, иначе это повлияет на поддерживаемые конечные разрешения.

Примечание:
1. Поддерживается только 2D virtio-gpu.
2. Live **Миграция не поддерживается.**

Пожалуйста, обратитесь к [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить virtio-gpu.

### 2.19 ivshmem-scream

ivshmem-scream — это виртуальная звуковая карта, которая использует общую память Intel-VM для передачи аудиоданных.

Для устройства ivshmem-scream поддерживаются девять свойств:
* id: уникальный идентификатор устройства.
* memdev: конфигурация внутреннего запоминающего устройства, используемого ivshmem.
* interface: настройка интерфейсов воспроизведения и записи звука, в настоящее время может быть установлен на ALSA, PulseAudio или Demo.
* playback: путь для хранения аудио. Когда интерфейс установлен на Demo, воспроизведение является обязательным.
* record: путь получения аудио. Когда интерфейс установлен на Demo, запись обязательна.
* bus: номер шины устройства.
* addr: включая номер слота и номер функции.
* share: общая память должна быть установлена в положение «on».
* size: размер общей памяти, рекомендуется 2M.

Пример конфигурации:
```shell
-device ivshmem-scream,id=<scream_id>,memdev=<object_id>,interface=<interfaces>[,playback=<playback path>][,record=<record path>],bus=pcie.0,addr=0x2.0x0
-object memory-backend-ram,id=<object_id>,share=on,size=2M
```

Пожалуйста, обратитесь к [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить scream.

### 2.20 ramfb
Ramfb — это простое устройство отображения. Оно используется в системе Windows на aarch64.

Поддерживаются два свойства для устройства ramfb:
* id: уникальный идентификатор устройства.
* install: при установке системы Windows установка значения true автоматически приведёт к нажатию клавиши Enter, чтобы пропустить этап, на котором необходимо вручную нажать любую клавишу для загрузки с компакт-диска или DVD.

Пример конфигурации：
```shell
-device ramfb,id=<ramfb id>[,install=true|false]
```

Примечание: поддерживается только на aarch64.

Пожалуйста, обратитесь к [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить ramfb.

### 2.21 pvpanic
pvpanic — это виртуальное устройство PCI. Оно используется для предоставления виртуальной машине возможности обнаруживать сбои или отказы гостевой операционной системы.

Четыре свойства поддерживаются для устройства pvpanic:
* id: уникальный идентификатор устройства.
* bus: номер шины устройства.
* addr: номер слота.
* supported-features: поддерживаемые функции, 0–3 относятся к None, panicked, crashload и panicked and crashload соответственно. Рекомендуется значение 3.

Пример конфигурации：
```shell
-device pvpanic,id=<pvpanic_pci>,bus=<pcie.0>,addr=<0x7>[,supported-features=<0|1|2|3>]
```

Пожалуйста, обратитесь к [4. Сборка с функциями](docs/build_guide.md), если вы хотите включить pvpanic.

## 3. Trace

Пользователи могут указать файл конфигурации, который перечисляет события для трассировки.

Можно установить одно свойство:

* events: файл со списком событий для отслеживания.

```shell
-trace file=<file>
```

## 4. Seccomp

StratoVirt использует seccomp(2) для ограничения системных вызовов в процессе StratoVirt по умолчанию. Это оказывает небольшое влияние на производительность StratoVirt.

Если вы хотите отключить seccomp, вы можете запустить StratoVirt с помощью -disable-seccomp.
```shell
# cmdline
-disable-seccomp
```

## 5. Snapshot и Restore

StratoVirt поддерживает создание моментального снимка приостановленной виртуальной машины в качестве шаблона виртуальной машины. Этот шаблон можно использовать для быстрого запуска новой виртуальной машины. Быстрый запуск пропускает стадию загрузки ядра и инициализации пользовательского пространства, чтобы загрузить виртуальную машину за очень короткое время.

### 5.1 Восстановление из шаблона виртуальной машины

Восстановите из шаблона виртуальной машины с помощью следующей команды:
```shell
$ ./stratovirt \
    -machine microvm \
    -kernel path/to/vmlinux.bin \
    -append "console=ttyS0 pci=off reboot=k quiet panic=1 root=/dev/vda" \
    -drive file=path/to/rootfs,id=rootfs,readonly=off,direct=off \
    -device virtio-blk-device,drive=rootfs,id=rootfs \
    -qmp unix:path/to/socket,server,nowait \
    -serial stdio \
    -incoming file:path/to/template
```

* incoming: путь к шаблону.

См. раздел «Snapshot и Restore» (snapshot.md) для получения подробной информации.

## 6. Ozone
Ozone — это облегчённый защищённый «песочниц» для StratoVirt, он обеспечивает безопасную среду для StratoVirt путём ограничения ресурсов StratoVirt с использованием «пространства имён». Пожалуйста, запустите ozone с правами суперпользователя.

### 6.1 Использование
Ozone можно запустить с помощью следующих команд:
```shell
$ ./ozone \
    -name stratovirt_ozone \
    -exec_file