---
layout: doc-full
title: Management API
permalink: /doc/mgmt1/
redirect_from:
- /doc/mgmt/
---

# Management API

*(This page is the current draft of the proposal. It is not implemented yet.)*

The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism.

## The calls

| call                                  | dest      | argument  | inside                                    | return                                                    | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
| `mgmt.vmclass.List`                   | `dom0`    | -         | -                                         | `<class>\n`                                               |
| `mgmt.vm.List`                        | `dom0|<vm>` | -         | -                                         | `<name> class=<class> state=<state>\n`                    |
| `mgmt.vm.Create.<class>`              | `dom0`    | template  | `name=<name> label=<label>`               | -                                                         |
| `mgmt.vm.CreateInPool.<class>`        | `dom0`    | template  | `name=<name> label=<label> pool=<pool>`   | -                                                         |
| `mgmt.vm.CreateTemplate`              | `dom0`    | name      | `root.img`                                | -                                                         |
| `mgmt.vm.Clone`                       | vm        | -         | `name=<name>`                             | -                                                         |
| `mgmt.vm.Remove`                      | vm        | -         | -                                         | -                                                         |
| `mgmt.label.List`                     | `dom0`    | -         | -                                         | `<property>\n`                                            |
| `mgmt.label.Create`                   | `dom0`    | label     | `0xRRGGBB`                                | -                                                         |
| `mgmt.label.Get`                      | `dom0`    | label     | -                                         | `0xRRGGBB`                                                |
| `mgmt.label.Index`                    | `dom0`    | label     | -                                         | `<label-index>`                                           |
| `mgmt.label.Remove`                   | `dom0`    | label     | -                                         | -                                                         |
| `mgmt.property.List`                  | `dom0`    | -         | -                                         | `<property>\n`                                            |
| `mgmt.property.Get`                   | `dom0`    | property  | -                                         | `default={yes|no} type={str|int|bool|vm|label} <value>`   |
| `mgmt.property.Help`                  | `dom0`    | property  | -                                         | `help`                                                    |
| `mgmt.property.HelpRst`               | `dom0`    | property  | -                                         | `help.rst`                                                |
| `mgmt.property.Reset`                 | `dom0`    | property  | -                                         | -                                                         |
| `mgmt.property.Set`                   | `dom0`    | property  | value                                     | -                                                         |
| `mgmt.vm.property.List`               | vm        | -         | -                                         | `<property>\n`                                            |
| `mgmt.vm.property.Get`                | vm        | property  | -                                         | `default={yes|no} <value>`                                |
| `mgmt.vm.property.Help`               | vm        | property  | -                                         | `help`                                                    |
| `mgmt.vm.property.HelpRst`            | vm        | property  | -                                         | `help.rst`                                                |
| `mgmt.vm.property.Reset`              | vm        | property  | -                                         | -                                                         |
| `mgmt.vm.property.Set`                | vm        | property  | value                                     | -                                                         |
| `mgmt.vm.feature.List`                | vm        | -         | -                                         | `<feature>\n`                                             |
| `mgmt.vm.feature.Get`                 | vm        | feature   | -                                         | value                                                     |
| `mgmt.vm.feature.CheckWithTemplate`   | vm        | feature   | -                                         | value                                                     |
| `mgmt.vm.feature.Remove`              | vm        | feature   | -                                         | -                                                         |
| `mgmt.vm.feature.Set`                 | vm        | feature   | value                                     | -                                                         |
| `mgmt.vm.tag.List`                    | vm        | -         | -                                         | `<tag>\n`                                                 |
| `mgmt.vm.tag.Get`                     | vm        | tag       | -                                         | `0` or `1`                                                | retcode? |
| `mgmt.vm.tag.Remove`                  | vm        | tag       | -                                         | -                                                         |
| `mgmt.vm.tag.Set`                     | vm        | tag       | -                                         | -                                                         |
| `mgmt.vm.firewall.List`               | vm        | -         | -                                         | `<rule id> <rule>\n`                                      |
| `mgmt.vm.firewall.InsertRule`         | vm        | rule id   | rule                                      | rule id                                                   | insert before given rule, use `END` as rule id to add rule at the end
| `mgmt.vm.firewall.RemoveRule`         | vm        | rule id   | -                                         | -                                                         |
| `mgmt.vm.firewall.Flush`              | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.device.<class>.Attach`       | vm        | device    | -                                         | -                                                         |
| `mgmt.vm.device.<class>.Detach`       | vm        | device    | -                                         | -                                                         |
| `mgmt.vm.device.<class>.List`         | vm        | -         | -                                         | `<device>\n`                                              |
| `mgmt.vm.device.<class>.Available`    | vm        | -         | -                                         | `<device>\n`                                              |
| `mgmt.vm.microphone.Attach`           | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.microphone.Detach`           | vm        | -         | -                                         | -                                                         |
| `mgmt.pool.List`                      | `dom0`    | -         | -                                         | `<pool>\n`                                                |
| `mgmt.pool.ListDrivers`               | `dom0`    | -         | -                                         | `<pool-driver> <property> ...\n`                          | Properties allowed in `mgmt.pool.Add`
| `mgmt.pool.Info`                      | `dom0`    | pool      | -                                         | `<property>=<value>\n`                                    |
| `mgmt.pool.Add`                       | `dom0`    | driver    | `<property>=<value>\n`                    | -                                                         |
| `mgmt.pool.Remove`                    | `dom0`    | pool      | -                                         | -                                                         |
| `mgmt.pool.volume.List`               | `dom0`    | pool      | -                                         | volume id                                                 |
| `mgmt.pool.volume.Info`               | `dom0`    | pool      | vid                                       | `<property>=<value>\n`                                    |
| `mgmt.pool.volume.ListSnapshots`      | `dom0`    | pool      | vid                                       | `<snapshot>\n`                                            |
| `mgmt.pool.volume.Snapshot`           | `dom0`    | pool      | vid                                       | snapshot                                                  |
| `mgmt.pool.volume.Revert`             | `dom0`    | pool      | `<vid> <snapshot>`                        | -                                                         |
| `mgmt.pool.volume.Resize`             | `dom0`    | pool      | `<vid> <size_in_bytes>`                   | -                                                         |
| `mgmt.vm.volume.List`                 | vm        | -         | -                                         | `<volume>\n`                                              | `<volume>` is per-VM volume name, `<vid>` is pool-unique volume id
| `mgmt.vm.volume.Info`                 | vm        | volume    | -                                         | `<property>=<value>\n`                                    |
| `mgmt.vm.volume.ListSnapshots`        | vm        | volume    | -                                         | snapshot                                                  | duplicate of `mgmt.pool.volume.`, but with other call params |
| `mgmt.vm.volume.Snapshot`             | vm        | volume    | -                                         | snapshot                                                  | id. |
| `mgmt.vm.volume.Revert`               | vm        | volume    | snapshot                                  | -                                                         | id. |
| `mgmt.vm.volume.Resize`               | vm        | volume    | size_in_bytes                             | -                                                         | id. |
| `mgmt.vm.Start`                       | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.Shutdown`                    | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.Pause`                       | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.Unpause`                     | vm        | -         | -                                         | -                                                         |
| `mgmt.vm.Kill`                        | vm        | -         | -                                         | -                                                         |
| `mgmt.backup.Execute`                 | `dom0`    | config i  | -                                         | -                                                         | config in `/etc/qubes/backup/<id>.conf` |
| `mgmt.backup.Info`                    | `dom0`    | ?         | content?                                  | ?                                                         |
| `mgmt.backup.Restore`                 | `dom0`    | ?         | content                                   | ?                                                         |
| `mgmt.Events`                         | `dom0|vm` | -         | -                                         | events                                                    |

Volume properties:
 - `pool`
 - `vid`
 - `size`
 - `usage`
 - `rw`
 - `internal`
 - `source`
 - `save_on_stop`
 - `snap_on_start`


## Returned messages

First byte of a message is a message type. This is 8 bit non-zero integer.
Values start at 0x30 (48, `'0'`, zero digit in ASCII) for readability in hexdump.
Next byte must be 0x00 (a separator).

This alternatively can be thought of as zero-terminated string containing
single ASCII digit.

### OK (0)

```
30 00 <content>
```

Server will close the connection after delivering single message.

### EVENT (1)

```
31 00 <subject> 00 <event> 00 ( <key> 00 <value> 00 )* 00
```

Events are returned as stream of messages in selected API calls. Normally server
will not close the connection.

A method yielding events will not ever return a `OK` or `EXCEPTION` message.

When calling such method, it will produce an artificial event
`connection-established` just after connection, to help avoiding race
conditions during event handler registration.

### EXCEPTION (2)

```
32 00 <type> 00 ( <traceback> )? 00 <format string> 00 ( <field> 00 )*
```

Server will close the connection.

Traceback may be empty, can be enabled server-side as part of debug mode.
Delimiting zero-byte is always present.

Fields are should substituted into `%`-style format string, possibly after
client-side translation, to form final message to be displayed unto user. Server
does not by itself support translation.

## Tags

- `created-by-<vm>`
- `managed-by-<vm>`
- `backup-<id>`

## General notes

- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call

## TODO

- something to configure/update policy
- notifications
  - how to constrain the events?
  - how to pass the parameters? maybe XML, since this is trusted anyway and
    parser may be complicated
- how to constrain the possible values for `mgmt.vm.property.Set` etc, like
  "you can change `netvm`, but you have to pick from this set"; this currently
  can be done by writing an extension
- a call for executing `*.desktop` file from `/usr/share/applications`, for use
  with appmenus without giving access to `qubes.VMShell`; currently this can be
  done by writing custom qrexec calls
- maybe some generator for `.desktop` for appmenus, which would wrap calls in
  `qrexec-client-vm`

<!-- vim: set ts=4 sts=4 sw=4 et : -->