X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=294de43c342ed8b3ab9e20dc53de12872d12644b;hp=78c514a578a9f82533a8f298aff1da9504de0a27;hb=c80b9ee6b4bfec0ecc7398a443c9c89f8783646b;hpb=9e8f2770b0b2e65938a2f543f861e88a57305000 diff --git a/pveum.adoc b/pveum.adoc index 78c514a..294de43 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -27,14 +27,53 @@ endif::manvolnum[] // Copied from pve wiki: Revision as of 16:10, 27 October 2015 -Proxmox VE supports multiple authentication sources, e.g. Microsoft -Active Directory, LDAP, Linux PAM or the integrated Proxmox VE -authentication server. +Proxmox VE supports multiple authentication sources, e.g. Linux PAM, +an integrated Proxmox VE authentication server, LDAP, Microsoft Active +Directory. By using the role based user- and permission management for all objects (VMs, storages, nodes, etc.) granular access can be defined. +Users +----- + +{pve} stores user attributes in `/etc/pve/user.cfg`. +Passwords are not stored here, users are instead associated with +<> described below. +Therefore a user is internally often identified by its name and +realm in the form `@`. + +Each user entry in this file contains the following information: + +* First name +* Last name +* E-mail address +* Group memberships +* An optional Expiration date +* A comment or note about this user +* Whether this user is enabled or disabled +* Optional two factor authentication keys + + +System administrator +~~~~~~~~~~~~~~~~~~~~ + +The system's root user can always log in via the Linux PAM realm and is an +unconfined administrator. This user cannot be deleted, but attributes can +still be changed and system mails will be sent to the email address +assigned to this user. + + +Groups +~~~~~~ + +Each user can be member of several groups. Groups are the preferred +way to organize access permissions. You should always grant permission +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]] Authentication Realms --------------------- @@ -148,39 +187,6 @@ Terms and Definitions --------------------- -Users -~~~~~ - -A Proxmox VE user name consists of two parts: `@`. The -login screen on the GUI shows them a separate items, but it is -internally used as single string. - -We store the following attribute for users (`/etc/pve/user.cfg`): - -* first name -* last name -* email address -* expiration date -* flag to enable/disable account -* comment - - -Superuser -^^^^^^^^^ - -The traditional unix superuser account is called `root@pam`. All -system mails are forwarded to the email assigned to that account. - - -Groups -~~~~~~ - -Each user can be member of several groups. Groups are the preferred -way to organize access permissions. You should always grant permission -to groups instead of using individual users. That way you will get a -much shorter access control list which is easier to handle. - - Objects and Paths ~~~~~~~~~~~~~~~~~ @@ -292,16 +298,9 @@ As mentioned earlier, object paths form a file system like tree, and permissions can be inherited down that tree (the propagate flag is set by default). We use the following inheritance rules: -* permission for individual users always overwrite group permission. -* permission for groups apply when the user is member of that group. -* permission set at higher level always overwrites inherited permissions. - - -What permission do I need? -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The required API permissions are documented for each individual -method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ +* Permissions for individual users always replace group permissions. +* Permissions for groups apply when the user is member of that group. +* Permissions replace the ones inherited from an upper level. Pools @@ -312,6 +311,62 @@ stores. You can then simply set permissions on pools (`/pool/{poolid}`), which are inherited to all pool members. This is a great way simplify access control. + +What permission do I need? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The required API permissions are documented for each individual +method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ + +The permissions are specified as a list which can be interpreted as a +tree of logic and access-check functions: + +`["and", ...]` and `["or", ...]`:: +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 +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. + +`["userid-group", [ ... ], ...]`:: +The callermust have any of the listed privileges on `/access/groups`. In +addition there are two possible checks depending on whether the +`groups_param` option is set: ++ +* `groups_param` is set: The API call has a non-optional `groups` parameter +and the caller must have any of the listed privileges on all of the listed +groups. +* `groups_param` is not set: The user passed via the `userid` parameter +must exist and be part of a group on which the caller has any of the listed +privileges (via the `/access/groups/` path). + +`["userid-param", "self"]`:: +The value provided for the API call's `userid` parameter must refer to the +user performing the action. (Usually in conjunction with `or`, to allow +users to perform an action on themselves even if they don't have elevated +privileges.) + +`["userid-param", "Realm.AllocateUser"]`:: +The user needs `Realm.AllocateUser` access to `/access/realm/`, with +`` refering to the realm of the user passed via the `userid` +parameter. Note that the user does not need to exist in order to be +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, +depending on the path, the following privileges as a possible substitute: ++ +* `/storage/...`: additionally requires 'Datastore.Allocate` +* `/vms/...`: additionally requires 'VM.Allocate` +* `/pool/...`: additionally requires 'Pool.Allocate` ++ +If the path is empty, `Permission.Modify` on `/access` is required. + Command Line Tool -----------------