host your own verification server].
-Terms and Definitions
+Permission Management
---------------------
+In order for a user to perform an action (such as listing, modifying or
+deleting a parts of a VM configuration), the user needs to have the
+appropriate permissions.
-Objects and Paths
-~~~~~~~~~~~~~~~~~
+{pve} uses a role and path based permission management system. An entry in
+the permissions table allows a user or group to take on a specific role
+when accessing an 'object' or 'path'. This means an such an access rule can
+be represented as a triple of '(path, user, role)' or '(path, group,
+role)', with the role containing a set of allowed actions, and the path
+representing the target of these actions.
-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.
+
+Roles
+~~~~~
+
+A role is simply a list of privileges. Proxmox VE comes with a number
+of predefined roles which satisfies most needs.
+
+* `Administrator`: has all privileges
+* `NoAccess`: has no privileges (used to forbid access)
+* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
+* `PVEAuditor`: read only access
+* `PVEDatastoreAdmin`: create and allocate backup space and templates
+* `PVEDatastoreUser`: allocate backup space and view storage
+* `PVEPoolAdmin`: allocate pools
+* `PVESysAdmin`: User ACLs, audit, system console and system logs
+* `PVETemplateUser`: view and clone templates
+* `PVEUserAdmin`: user administration
+* `PVEVMAdmin`: fully administer VMs
+* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
+
+You can see the whole set of predefined roles on the GUI.
+
+Adding new roles can currently only be done from the command line, like
+this:
+
+[source,bash]
+----
+pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
+----
Privileges
A privilege is the right to perform a specific action. To simplify
management, lists of privileges are grouped into roles, which can then
-be uses to set permissions.
+be used in the permission table. Note that privileges cannot directly be
+assigned to users and paths without being part of a role.
We currently use the following privileges:
* `Datastore.Audit`: view/browse a datastore
-Roles
-~~~~~
-
-A role is simply a list of privileges. Proxmox VE comes with a number
-of predefined roles which satisfies most needs.
-
-* `Administrator`: has all privileges
-* `NoAccess`: has no privileges (used to forbid access)
-* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
-* `PVEAuditor`: read only access
-* `PVEDatastoreAdmin`: create and allocate backup space and templates
-* `PVEDatastoreUser`: allocate backup space and view storage
-* `PVEPoolAdmin`: allocate pools
-* `PVESysAdmin`: User ACLs, audit, system console and system logs
-* `PVETemplateUser`: view and clone templates
-* `PVEUserAdmin`: user administration
-* `PVEVMAdmin`: fully administer VMs
-* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
-
-You can see the whole set of predefined roles on the GUI.
-
-Adding new roles using the CLI:
-
-[source,bash]
-----
-pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
-pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
-----
-
-
-Permissions
-~~~~~~~~~~~
-
-Permissions are the way we control access to objects. In technical
-terms they are simply a triple containing `<path,user,role>`. This
-concept is also known as access control lists. Each permission
-specifies a subject (user or group) and a role (set of privileges) on
-a specific path.
+Objects and Paths
+~~~~~~~~~~~~~~~~~
-When a subject requests an action on an object, the framework looks up
-the roles assigned to that subject (using the object path). The set of
-roles defines the granted privileges.
+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
Inheritance
projects / pve-docs.git / blobdiff