X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=db196b537389a2631113f11ac268987cf0e8ad2c;hp=f1abd942dfdbe669e77dbe51a4686f4805abdca3;hb=c8bdafbd1ad8c4787a576ee22d8eb2e64aaf8e91;hpb=853d288bd5ae906fc99b3008d37ba81e8951dd08 diff --git a/pveum.adoc b/pveum.adoc index f1abd94..db196b5 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -1,7 +1,8 @@ +[[chapter_user_management]] ifdef::manvolnum[] -PVE({manvolnum}) -================ -include::attributes.txt[] +pveum(1) +======== +:pve-toplevel: NAME ---- @@ -9,7 +10,7 @@ NAME pveum - Proxmox VE User Manager -SYNOPSYS +SYNOPSIS -------- include::pveum.1-synopsis.adoc[] @@ -18,11 +19,10 @@ include::pveum.1-synopsis.adoc[] DESCRIPTION ----------- endif::manvolnum[] - ifndef::manvolnum[] User Management =============== -include::attributes.txt[] +:pve-toplevel: endif::manvolnum[] // Copied from pve wiki: Revision as of 16:10, 27 October 2015 @@ -35,12 +35,13 @@ By using the role based user- and permission management for all objects (VMs, storages, nodes, etc.) granular access can be defined. +[[pveum_users]] Users ----- {pve} stores user attributes in `/etc/pve/user.cfg`. Passwords are not stored here, users are instead associated with -<> described below. +<> described below. Therefore a user is internally often identified by its name and realm in the form `@`. @@ -65,6 +66,7 @@ still be changed and system mails will be sent to the email address assigned to this user. +[[pveum_groups]] Groups ~~~~~~ @@ -74,7 +76,7 @@ to groups instead of using individual users. That way you will get a much shorter access control list which is easier to handle. -[[authentication-realms]] +[[pveum_authentication_realms]] Authentication Realms --------------------- @@ -183,6 +185,7 @@ https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation host your own verification server]. +[[pveum_permission_management]] Permission Management --------------------- @@ -198,6 +201,7 @@ role)', with the role containing a set of allowed actions, and the path representing the target of these actions. +[[pveum_roles]] Roles ~~~~~ @@ -229,22 +233,13 @@ 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 ~~~~~~~~~~ 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: @@ -289,18 +284,33 @@ Storage related privileges:: * `Datastore.Audit`: view/browse a datastore -Permissions -~~~~~~~~~~~ +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. + +[[pveum_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. -Permissions are the way we control access to objects. In technical -terms they are simply a triple containing ``. 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. +Some examples are: -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. +* `/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 <> +* `/access/groups`: Group administration +* `/access/realms/{realmid}`: Administrative access to realms Inheritance @@ -315,6 +325,7 @@ by default). We use the following inheritance rules: * Permissions replace the ones inherited from an upper level. +[[pveum_pools]] Pools ~~~~~ @@ -337,8 +348,9 @@ tree of logic and access-check functions: Each(`and`) or any(`or`) further element in the current list has to be true. `["perm", , [ ... ], ...]`:: -The `path` is a templated parameter (see <>). All (or , if the `any` option is used, any) of the listed +The `path` is a templated parameter (see +<>). All (or , if the `any` +option is used, any) of the listed privileges must be allowed on the specified path. If a `require-param` option is specified, then its specified parameter is required even if the API call's schema otherwise lists it as being optional. @@ -369,8 +381,9 @@ associated with a realm, since user IDs are passed in the form of `@`. `["perm-modify", ]`:: -The `path` is a templated parameter (see <>). The user needs either the `Permissions.Modify` privilege, or, +The `path` is a templated parameter (see +<>). The user needs either the +`Permissions.Modify` privilege, or, depending on the path, the following privileges as a possible substitute: + * `/storage/...`: additionally requires 'Datastore.Allocate`