[pve-devel] [PATCH v2 docs 11/12] move and expand the Objects and Paths section

[Wolfgang Bumiller]

It now gets more technical to finish the documentation of
the permission checks found in the API documentation, and is
the final section about the various parts making up the
access control lists.
---
 pveum.adoc | 39 +++++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 10 deletions(-)

diff --git a/pveum.adoc b/pveum.adoc
index 36426cf..9addcb7 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -229,16 +229,6 @@ pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
 ----
 
 
-Objects and Paths
-~~~~~~~~~~~~~~~~~
-
-Access permissions are assigned to objects, such as a virtual machines
-(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
-resources (`/pool/{poolname}`). We use file system like paths to
-address those objects. Those paths form a natural tree, and
-permissions can be inherited down that hierarchy.
-
-
 Privileges
 ~~~~~~~~~~
 
@@ -290,6 +280,35 @@ Storage related privileges::
 * `Datastore.Audit`: view/browse a datastore
 
 
+Objects and Paths
+~~~~~~~~~~~~~~~~~
+
+Access permissions are assigned to objects, such as a virtual machines,
+storages or pools of resources.
+We use file system like paths to address these objects. These paths form a
+natural tree, and permissions of higher levels (shorter path) can
+optionally be propagated down within this hierarchy.
+
+[[templated-paths]]
+Paths can be templated. When an API call requires permissions on a
+templated path, the path may contain references to parameters of the API
+call. These references are specified in curly braces. Some parameters are
+implicitly taken from the API call's URI. For instance the permission path
+`/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
+`/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
+refers to the method's `path` parameter.
+
+Some examples are:
+
+* `/nodes/{node}`: Access to {pve} server machines
+* `/vms`: Covers all VMs
+* `/vms/{vmid}`: Access to specific VMs
+* `/storage/{storeid}`: Access to a storages
+* `/pool/{poolname}`: Access to VMs part of a <<resource-pools,pool>
+* `/access/groups`: Group administration
+* `/access/realms/{realmid}`: Administrative access to realms
+
+
 Permissions
 ~~~~~~~~~~~
 
-- 
2.1.4