From d82e47c449c707f2edac80d50b6d684c98982f07 Mon Sep 17 00:00:00 2001
From: Wojtek Porczyk <woju@invisiblethingslab.com>
Date: Thu, 24 Nov 2016 15:10:41 +0100
Subject: [PATCH] services/mgmt1: various updates

- remove `1` from RPC names
- change `mgmt.vm.Create` wrt class
- misc notes and TODOs

QubesOS/qubes-issues#853
---
 services/mgmt1.md | 125 ++++++++++++++++++++++++++--------------------
 1 file changed, 70 insertions(+), 55 deletions(-)

diff --git a/services/mgmt1.md b/services/mgmt1.md
index 16a31cf0..331d15e4 100644
--- a/services/mgmt1.md
+++ b/services/mgmt1.md
@@ -15,61 +15,60 @@ to set the policy using current mechanism.
 
 | call                                    | dest                   | argument      | inside                                    | return                                   | note |
 | --------------------------------------- | ---------------------- | ------------- | ----------------------------------------- | ---------------------------------------- | ---- |
-| `mgmt1.vm.List`                         | `dom0`                 | -             | -                                         | `<name> class=<class> state=<state>\n`   |
-| `mgmt1.vm.Create`                       | template or `dom0`     | class         | `name=<name> label=<label>`               | -                                        |
-| `mgmt1.vm.CreateInPool`                 | template or `dom0`     | class         | `name=<name> label=<label> pool=<pool>`   | -                                        |
-| `mgmt1.vm.CreateTemplate`               | `dom0`                 | name          | `root.img`                                | -                                        |
-| `mgmt1.vm.property.List`                | vm                     | -             | -                                         | `<property>\n`                           |
-| `mgmt1.vm.property.Get`                 | vm                     | property      | -                                         | `default={yes|no} <value>`               |
-| `mgmt1.vm.property.Help`                | vm                     | property      | -                                         | `help.rst`                               |
-| `mgmt1.vm.property.Reset`               | vm                     | property      | -                                         | -                                        |
-| `mgmt1.vm.property.Set`                 | vm                     | property      | value                                     | -                                        |
-| `mgmt1.vm.feature.List`                 | vm                     | -             | -                                         | `<feature>\n`                            |
-| `mgmt1.vm.feature.Get`                  | vm                     | feature       | -                                         | value                                    |
-| `mgmt1.vm.feature.CheckWithTemplate`    | vm                     | feature       | -                                         | value                                    |
-| `mgmt1.vm.feature.Remove`               | vm                     | feature       | -                                         | -                                        |
-| `mgmt1.vm.feature.Set`                  | vm                     | feature       | value                                     | -                                        |
-| `mgmt1.vm.tag.List`                     | vm                     | tag           | -                                         | `<tag>\n`                                |
-| `mgmt1.vm.tag.Get`                      | vm                     | tag           | -                                         | `0` or `1`                               |retcode? |
-| `mgmt1.vm.tag.Remove`                   | vm                     | tag           | -                                         | -                                        |
-| `mgmt1.vm.tag.Set`                      | vm                     | tag           | -                                         | -                                        |
-| `mgmt1.vm.firewall.Get`                 | vm                     | position      | -                                         | `<rule id> <rule>\n`                     |
-| `mgmt1.vm.firewall.InsertRule`          | vm                     | position      | rule                                      | rule id                                  |
-| `mgmt1.vm.firewall.RemoveRule`          | vm                     | rule id       | -                                         | -                                        |
-| `mgmt1.vm.firewall.Flush`               | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.device.<class>.Attach`        | vm                     | device        | -                                         | -                                        |
-| `mgmt1.vm.device.<class>.Detach`        | vm                     | device        | -                                         | -                                        |
-| `mgmt1.vm.device.<class>.List`          | vm                     | -             | -                                         | `<device>\n`                             |
-| `mgmt1.vm.device.<class>.Available`     | vm                     | -             | -                                         | `<device>\n`                             |
-| `mgmt1.vm.microphone.Attach`            | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.microphone.Detach`            | vm                     | -             | -                                         | -                                        |
-| `mgmt1.pool.List`                       | `dom0`                 | -             | -                                         | `<pool>\n`                               |
-| `mgmt1.pool.Info`                       | `dom0`                 | pool          | -                                         | `<property>=<value>\n`                   |
-| `mgmt1.pool.Add`                        | `dom0`                 | pool          | `<property>=<value>\n`                    | -                                        |
-| `mgmt1.pool.Remove`                     | `dom0`                 | pool          | -                                         | -                                        |
-| `mgmt1.pool.volume.List`                | `dom0`                 | pool          | -                                         | volume id                                |
-| `mgmt1.pool.volume.Info`                | `dom0`                 | pool:vid      | -                                         | `<property>=<value>\n`                   |
-| `mgmt1.pool.volume.ListSnapshots`       | `dom0`                 | pool:vid      | -                                         | `<snapshot>\n`                           |
-| `mgmt1.pool.volume.Snapshot`            | `dom0`                 | pool:vid      | -                                         | snapshot                                 |
-| `mgmt1.pool.volume.Revert`              | `dom0`                 | pool:vid      | snapshot                                  | -                                        |
-| `mgmt1.pool.volume.Extend`              | `dom0`                 | pool:vid      | -                                         | `<size_in_bytes>`                        |
-| `mgmt1.vm.volume.List`                  | vm                     | -/pool?       | -                                         | ?                                        |
-| `mgmt1.vm.volume.Info`                  | vm                     | volume        | -                                         | ?                                        |
-| `mgmt1.vm.volume.ListSnapshots`         | vm                     | volume        | -                                         | snapshot                                 |duplicate of `mgmt1.pool.volume.`, but with other call params |
-| `mgmt1.vm.volume.Snapshot`              | vm                     | volume        | -                                         | snapshot                                 |id. |
-| `mgmt1.vm.volume.Revert`                | vm                     | volume        | snapshot                                  | -                                        |id. |
-| `mgmt1.vm.volume.Extend`                | vm                     | volume        | -                                         | `<size_in_bytes>`                        |id. |
-| `mgmt1.vm.volume.Attach`                | vm                     | volume        | -                                         | -                                        |
-| `mgmt1.vm.volume.Detach`                | vm                     | volume        | -                                         | -                                        |
-| `mgmt1.vm.Start`                        | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.Shutdown`                     | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.Pause`                        | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.Unpause`                      | vm                     | -             | -                                         | -                                        |
-| `mgmt1.vm.Kill`                         | vm                     | -             | -                                         | -                                        |
-| `mgmt1.backup.Execute`                  | `dom0`                 | config id     | -                                         | -                                        |config in `/etc/qubes/backup/<id>.conf` |
-| `mgmt1.backup.Info`                     | `dom0`                 | ?             | content?                                  | ?                                        |
-| `mgmt1.backup.Restore`                  | `dom0`                 | ?             | content                                   | ?                                        |
-
+| `mgmt.vm.List`                          | `dom0`                 | -             | -                                         | `<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.property.List`                 | vm                     | -             | -                                         | `<property>\n`                           |
+| `mgmt.vm.property.Get`                  | vm                     | property      | -                                         | `default={yes|no} <value>`               |
+| `mgmt.vm.property.Help`                 | 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           | -                                         | `<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.Get`                  | vm                     | position      | -                                         | `<rule id> <rule>\n`                     |
+| `mgmt.vm.firewall.InsertRule`           | vm                     | position      | rule                                      | rule id                                  |
+| `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.Info`                        | `dom0`                 | pool          | -                                         | `<property>=<value>\n`                   |
+| `mgmt.pool.Add`                         | `dom0`                 | pool          | `<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.Extend`               | `dom0`                 | pool:vid      | -                                         | `<size_in_bytes>`                        |
+| `mgmt.vm.volume.List`                   | vm                     | -/pool?       | -                                         | ?                                        |
+| `mgmt.vm.volume.Info`                   | vm                     | volume        | -                                         | ?                                        |
+| `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.Extend`                 | vm                     | volume        | -                                         | `<size_in_bytes>`                        | id. |
+| `mgmt.vm.volume.Attach`                 | vm                     | volume        | -                                         | -                                        |
+| `mgmt.vm.volume.Detach`                 | vm                     | volume        | -                                         | -                                        |
+| `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 id     | -                                         | -                                        | config in `/etc/qubes/backup/<id>.conf` |
+| `mgmt.backup.Info`                      | `dom0`                 | ?             | content?                                  | ?                                        |
+| `mgmt.backup.Restore`                   | `dom0`                 | ?             | content                                   | ?                                        |
 
 ## Tags
 
@@ -77,6 +76,22 @@ to set the policy using current mechanism.
 - `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`