cloud-hypervisor/docs/api.md

1 - [Cloud Hypervisor API](#cloud-hypervisor-api)
2   - [External API](#external-api)
3     - [REST API](#rest-api)
4       - [REST API Location and availability](#rest-api-location-and-availability)
5       - [REST API Endpoints](#rest-api-endpoints)
6         - [Virtual Machine Manager (VMM) Actions](#virtual-machine-manager-vmm-actions)
7         - [Virtual Machine (VM) Actions](#virtual-machine-vm-actions)
8       - [REST API Examples](#rest-api-examples)
9         - [Create a Virtual Machine](#create-a-virtual-machine)
10         - [Boot a Virtual Machine](#boot-a-virtual-machine)
11         - [Dump a Virtual Machine Information](#dump-a-virtual-machine-information)
12         - [Reboot a Virtual Machine](#reboot-a-virtual-machine)
13         - [Shut a Virtual Machine Down](#shut-a-virtual-machine-down)
14     - [D-Bus API](#d-bus-api)
15       - [D-Bus API Location and availability](#d-bus-api-location-and-availability)
16       - [D-Bus API Interface](#d-bus-api-interface)
17     - [Command Line Interface](#command-line-interface)
18 …- [REST API, D-Bus API and CLI Architectural Relationship](#rest-api-and-cli-architectural-relatio…
19   - [Internal API](#internal-api)
20     - [Goals and Design](#goals-and-design)
21   - [End to End Example](#end-to-end-example)
29    including a REST API, a Command Line Interface (CLI) or a D-Bus based API,
32 1. **The internal API**, based on [rust's Multi-Producer, Single-Consumer (MPSC)](https://doc.rust-…
45 collection of RPC-style, static methods.
47 The API is [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
48 …ment](https://raw.githubusercontent.com/cloud-hypervisor/cloud-hypervisor/master/vmm/src/api/opena…
54 through either a local UNIX socket as given in the Cloud Hypervisor option `--api-socket path=...`
55 or a fd with `--api-socket fd=...`.
58 $ ./target/debug/cloud-hypervisor --api-socket path=/tmp/cloud-hypervisor.sock
60     API server: /tmp/cloud-hypervisor.sock
75 | ----------------------------------- | --------------- | ------------ | --------------------------…
82 …---------------------------------- | ----------------------- | ------------------------------- | -…
88 | Trigger power button of the VM     | `/vm.power-button`      | N/A                             | …
96 | Add/remove memory from a zone      | `/vm.resize-zone`       | `/schemas/VmResizeZone`         | …
98 | Add VFIO PCI device to the VM      | `/vm.add-device`        | `/schemas/VmAddDevice`          | …
99 | Add disk device to the VM          | `/vm.add-disk`          | `/schemas/DiskConfig`           | …
100 | Add fs device to the VM            | `/vm.add-fs`            | `/schemas/FsConfig`             | …
101 | Add pmem device to the VM          | `/vm.add-pmem`          | `/schemas/PmemConfig`           | …
102 | Add network device to the VM       | `/vm.add-net`           | `/schemas/NetConfig`            | …
103 | Add userspace PCI device to the VM | `/vm.add-user-device`   | `/schemas/VmAddUserDevice`      | …
104 | Add vdpa device to the VM          | `/vm.add-vdpa`          | `/schemas/VdpaConfig`           | …
105 | Add vsock device to the VM         | `/vm.add-vsock`         | `/schemas/VsockConfig`          | …
106 | Remove device from the VM          | `/vm.remove-device`     | `/schemas/VmRemoveDevice`       | …
109 | Prepare to receive a migration     | `/vm.receive-migration` | `/schemas/ReceiveMigrationData` | …
110 | Start to send migration to target  | `/vm.send-migration`    | `/schemas/SendMigrationData`    | …
114 enabled. Without this feature, the corresponding [REST API](#rest-api) or
115 [D-Bus API](#d-bus-api) endpoints are not available.
120 the REST API available at `/tmp/cloud-hypervisor.sock`:
123 $ ./target/debug/cloud-hypervisor --api-socket /tmp/cloud-hypervisor.sock
125     API server: /tmp/cloud-hypervisor.sock
140 * Direct kernel boot from a custom 5.6.0-rc4 Linux kernel located at
141   `/opt/clh/kernel/vmlinux-virtio-fs-virtio-iommu`
143   `/opt/clh/images/focal-server-cloudimg-amd64.raw`
148 curl --unix-socket /tmp/cloud-hypervisor.sock -i \
149      -X PUT 'http://localhost/api/v1/vm.create'  \
150      -H 'Accept: application/json'               \
151      -H 'Content-Type: application/json'         \
152      -d '{
154 …"payload":{"kernel":"/opt/clh/kernel/vmlinux-virtio-fs-virtio-iommu", "cmdline":"console=ttyS0 con…
155          "disks":[{"path":"/opt/clh/images/focal-server-cloudimg-amd64.raw"}],
168 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.boot'
178 curl --unix-socket /tmp/cloud-hypervisor.sock -i \
179      -X GET 'http://localhost/api/v1/vm.info' \
180      -H 'Accept: application/json'
190 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.reboot'
200 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.shutdown'
203 ### D-Bus API
205 Cloud Hypervisor offers a D-Bus API as an alternative to its REST API. This
206 D-Bus API fully reflects the functionality of the REST API, exposing the
207 same group of endpoints. It can be a drop-in replacement since it also
210 In addition, the D-Bus API also exposes events from `event-monitor` in the
211 form of a D-Bus signal to which users can subscribe. For more information,
212 see [D-Bus API Interface](#d-bus-api-interface).
214 #### D-Bus API Location and availability
217 wish to use the D-Bus API, must explicitly enable it with the `dbus_api`
221 $ ./scripts/dev_cli.sh build --release --libc musl -- --features dbus_api
228   --dbus-service-name
230   --dbus-object-path
232   --dbus-system-bus use the system bus instead of a session bus
238 $ ./cloud-hypervisor --dbus-service-name "org.cloudhypervisor.DBusApi" \
239                      --dbus-object-path "/org/cloudhypervisor/DBusApi"
245 #### D-Bus API Interface
247 Please refer to the [REST API](#rest-api) documentation for everything that
248 is in common with the REST API. As previously mentioned, the D-Bus API can
249 be used as a drop-in replacement for the [REST API](#rest-api).
251 The D-Bus interface also exposes a signal, named `Event`, which is emitted
252 whenever a new event is published from the `event-monitor` crate. Here is its
272 Hypervisor from the CLI, you must use either the [REST API](#rest-api)
273 or the [D-Bus API](#d-bus-api).
278    the VM config. Run `cloud-hypervisor --help` for a complete list of CLI
279    options. As soon as the `cloud-hypervisor` binary is launched, contrary
280    to the [D-Bus API](#d-bus-api), the [REST API](#rest-api) is available
281    for controlling and managing the VM. The [D-Bus API](#d-bus-api) doesn't start
283 1. Start either the REST API, D-Bus API or both simultaneously without passing
286    API does not exclude another; it is possible to have both the REST and D-Bus
289 ### REST API, D-Bus API and CLI Architectural Relationship
291 The REST API, D-Bus API and the CLI all rely on a common, [internal API](#internal-api).
295 [internal API](#internal-api) commands.
298 [Firecracker's `micro_http`](https://github.com/firecracker-microvm/micro-http)
300 [internal API](#internal-api) commands.
302 The D-Bus API is implemented using the [zbus](https://github.com/dbus2/zbus)
303 crate and runs in its own thread. Whenever it needs to call the [internal API](#internal-api),
304 the [blocking](https://github.com/smol-rs/blocking) crate is used perform the call in zbus' async c…
306 As a summary, the REST API, the D-Bus API and the CLI are essentially frontends for the
307 [internal API](#internal-api):
310                                   +------------------+
312                        +--------->+    micro_http    +--------+
314                        |          +------------------+        |
315                        |                                      |      +------------------------+
317 +------------+         |            +----------+              |      |                        |
318 |            |         |  D-Bus API |          |              |      | +--------------+       |
319 |    User    +---------+----------->+   zbus   +--------------+------> | Internal API |       |
320 |            |         |            |          |              |      | +--------------+       |
321 +------------+         |            +----------+              |      |                        |
323                        |                                      |      +------------------------+
324                        |            +----------+              |                 VMM
326                        +----------->+   clap   +--------------+
328                                     +----------+
336 by the different Cloud Hypervisor threads (VMM, HTTP, D-Bus, control loop,
339 It is based on [rust's Multi-Producer, Single-Consumer (MPSC)](https://doc.rust-lang.org/std/sync/m…
343 API producers are the HTTP thread handling the [REST API](#rest-api), the
344 D-Bus thread handling the [D-Bus API](#d-bus-api) and the main thread that
345 initially parses the [CLI](#command-line-interface).
351 visible requests through the [REST API](#rest-api), the [D-Bus API](#d-bus-api)
352 or the [CLI](#command-line-interface) interfaces.
354 The API follows a command-response scheme that closely maps the [REST API](#rest-api).
357 Commands are [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) based messages and
362 internal API command payload carry the [Sender](https://doc.rust-lang.org/std/sync/mpsc/struct.Send…
363 end of an [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) channel.
367 1. Creating an [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) response
369 1. Passing the [Sender](https://doc.rust-lang.org/std/sync/mpsc/struct.Sender.html)
371 1. Waiting for the internal API command's response on the [Receiver](https://doc.rust-lang.org/std/…
378 [REST API](#rest-api) call, to the reply the external user will receive:
381    [REST API](#rest-api) in order to creates a virtual machine:
386 	curl --unix-socket /tmp/cloud-hypervisor.sock -i \
387 		-X PUT 'http://localhost/api/v1/vm.create'  \
388 		-H 'Accept: application/json'               \
389 		-H 'Content-Type: application/json'         \
390 		-d '{
392 …"payload":{"kernel":"/opt/clh/kernel/vmlinux-virtio-fs-virtio-iommu", "cmdline":"console=ttyS0 con…
393 			"disks":[{"path":"/opt/clh/images/focal-server-cloudimg-amd64.raw"}],
398 1. The Cloud Hypervisor HTTP thread processes the request and de-serializes the
401    [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) channel for the internal API
404    virtual machine. The command's payload is made of the de-serialized
421    internal API [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) channel:
428    [Sender](https://doc.rust-lang.org/std/sync/mpsc/struct.Sender.html) from the
461    [micro_http](https://github.com/firecracker-microvm/micro-http)