Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-04-26 18:59:11 -04:00
Code Issues Packages Projects Releases Wiki Activity

q-dev: update docs

Browse Source
This commit is contained in:
Piotr Bartman 2024-03-20 22:20:01 +01:00 committed by Piotr Bartman-Szwarc
parent 941ef46054
commit 3cec58bf7d
No known key found for this signature in database
GPG Key ID: E386DC76B775C5C9
1 changed files with 144 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
developer/services/admin-api.md
View File

@ -63,7 +63,7 @@ The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism. to set the policy using current mechanism.
| call | dest | argument | inside | return | note | | call | dest | argument | inside | return | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- | |------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` | | `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `admin.vm.List` | `dom0 | <vm>` | - | - | `<name> class=<class> state=<state>\n` | | `admin.vm.List` | `dom0 | <vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - | | `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
@ -106,12 +106,15 @@ to set the policy using current mechanism.
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option | `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax | `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule | `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `admin.vm.deviceclass.List` | `dom0` | - | - | `<class>\n` | | `admin.vm.device.<class>.Attach` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary) | `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>` | `admin.vm.device.<class>.Assign` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Set.persistent`| vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>` | `admin.vm.device.<class>.Unassign` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=True` for "persistently" attached devices (default is temporary) | `admin.vm.device.<class>.Set.required` | vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces | `admin.vm.deviceclass.List` | `dom0` | - | - | `<deviceclass>\n` |
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <device-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `device-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Assigned` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Attached` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` | | `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add` | `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` | | `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
@ -302,6 +305,58 @@ destination_vm: sys-net
destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
``` ```
## Device Serialization
Both device and assignment serialization is ASCII-encoded and contains
space-separated key-value pairs. The format includes an `=` between the key
and value, and the value is always enclosed in single quotes (`'`).
Values may contain spaces or even single quotes, which are escaped with a backslash.
If a value is not set (`None`), it is represented as `'unknown'`.
For boolean values, `True` is represented as `'yes'`, and `False` as `'no'`.
The order of key-value pairs is irrelevant. Keys starting with `_`
are considered extra properties and are saved in `data` or `options`
for device or assignment respectively.
Information about the serialization format of specific properties can be found below.
Format:
```
<ident> <property_1>='<value_1>' <property_2>='<value_2>' <property_3>='<value_3>'...
```
Detailed serialization format for a device:
- `ident='<ident>'`
- `backend_domain='<backend_domain.name>'`
- `devclass='<devclass>'`
- `vendor='<vendor>'`
- `product='<product>'`
- `manufacturer='<manufacturer>'`
- `name='<name>'`
- `serial='<serial>'`
- `self_identity='<self_identity>'`
- `interfaces='<interface1><interface2>...'`
Each device interface is represented with a 7-character length. Each device has at least one interface. Since the length of the interface representation is known, they are serialized as a single string with each interface representation concatenated one after another. The order is irrelevant.
- `parent_ident='<parent.ident>' parent_devclass='<parent.devclass>'`
- `attachment='<attachment.name>'`
- `_<key1>='<value1>' _<key2>='<value2>' ...` (extra parameters)
Detailed serialization format for an assignment:
- `ident='<ident>'`
- `backend_domain='<backend_domain.name>'`
- `devclass='<devclass>'`
- `frontend_domain='<frontend_domain.name>'`
- `required='<yes/no>'` (default 'no')
- `attach_automatically='<yes/no>'` (default 'no')
- `_<key1>='<str(value1)>' _<key2>='<str(value2)>' ...` (options)
Example device serialization:
```
1-1.1.1 manufacturer='unknown' self_identity='0000:0000::?******' serial='unknown' ident='1-1.1.1' product='Qubes' vendor='ITL' name='Some untrusted garbage' devclass='bus' backend_domain='vm' interfaces=' ******u03**01' _additional_info='' _date='06.12.23' parent_ident='1-1.1' parent_devclass='None'
```
## General notes ## General notes
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call - there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call