document permission syntax

[pve-docs.git] / pveum.adoc

diff --git a/pveum.adoc b/pveum.adoc
index f68b243cf4962bc7700fb52509564b413448ae74..c31383cbb284921351cef1bb1d364c77b99d176e 100644 (file)
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -32,26 +32,22 @@ Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
 authentication server.
 
 By using the role based user- and permission management for all
 authentication server.
 
 By using the role based user- and permission management for all

-objects (VM´s, storages, nodes, etc.) granular access can be defined.
+objects (VMs, storages, nodes, etc.) granular access can be defined.

 
 

+
+[[authentication-realms]]

 Authentication Realms
 ---------------------
 
 Authentication Realms
 ---------------------
 

-Proxmox VE stores all user attributes in `/etc/pve/user.cfg`. So there
-must be an entry for each user in that file. The password is not
-stored, instead you can use configure several realms to verify
-passwords.
-
-Microsoft Active Directory::
-
-LDAP::
+As {pve} users are just counterparts for users existing on some external
+realm, the realms have to be configured in `/etc/pve/domains.cfg`.
+The following realms (authentication methods) are available:

 
 Linux PAM standard authentication::
 
 Linux PAM standard authentication::

-
-You need to create the system users first with `adduser`
-(e.g. `adduser heinz`) and possibly the group as well. After that you
-can create the user on the GUI.
-
+In this case a system user has to exist (eg. created via the `adduser`
+command) on all nodes the user is allowed to login, and the user
+authenticates with their usual system password.
++

 [source,bash]
 ----
 useradd heinz
 [source,bash]
 ----
 useradd heinz


@@ -61,14 +57,97 @@ usermod -a -G watchman heinz
 ----
 
 Proxmox VE authentication server::
 ----
 
 Proxmox VE authentication server::

+This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
+Password are encrypted using the SHA-256 hash method.
+This is the most convenient method for for small (or even medium)
+installations where users do not need access to anything outside of
+{pve}. In this case users are fully managed by {pve} and are able to
+change their own passwords via the GUI.
+
+LDAP::
+It is possible to authenticate users via an LDAP server (eq.
+openldap). The server and an optional fallback server can be
+configured and the connection can be encrypted via SSL.
++
+Users are searched under a 'Base Domain Name' (`base_dn`), with the
+user name found in the attribute specified in the 'User Attribute Name'
+(`user_attr`) field.
++
+For instance, if a user is represented via the
+following ldif dataset:
++
+----
+# user1 of People at ldap-test.com
+dn: uid=user1,ou=People,dc=ldap-test,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+uid: user1
+cn: Test User 1
+sn: Testers
+description: This is the first test user.
+----
++
+The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
+attribute would be `uid`.
++
+If {pve} needs to authenticate (bind) to the ldap server before being
+able to query and authenticate users, a bind domain name can be
+configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
+password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
+(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+single line containing the raw password.
+
+Microsoft Active Directory::
+
+A server and authentication domain need to be specified. Like with
+ldap an optional fallback server, optional port, and SSL
+encryption can be configured.
+
+
+Two factor authentication
+-------------------------
+
+Each realm can optionally be secured additionally by two factor
+authentication. This can be done by selecting one of the available methods
+via the 'TFA' dropdown box when adding or editing an Authentication Realm.
+When a realm has TFA enabled it becomes a requirement and only users with
+configured TFA will be able to login.
+
+Currently there are two methods available:
+
+Time based OATH (TOTP)::
+This uses the standard HMAC-SHA1 algorithm where the current time is hashed
+with the user's configured key. The time step and password length
+parameters are configured.
++
+A user can have multiple keys configured (separated by spaces), and the
+keys can be specified in Base32 (RFC3548) or hexadecimal notation.
++
+{pve} provides a key generation tool (`oathkeygen`) which prints out a
+random key in Base32 notation which can be used directly with various OTP
+tools, such as the `oathtool` command line tool, the Google authenticator
+or FreeOTP Android apps.
+
+YubiKey OTP::
+For authenticating via a YubiKey a Yubico API ID, API KEY and validation
+server URL must be configured, and users must have a YubiKey available. In
+order to get the key ID from a YubiKey, you can trigger the YubiKey once
+after connecting it to USB and copy the first 12 characters of the typed
+password into the user's 'Key IDs' field.
++
+Please refer to the
+https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
+https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
+https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
+host your own verification server].

 
 

-This is a unix like password store
-(`/etc/pve/priv/shadow.cfg`). Password are encrypted using the SHA-256
-hash method. Users are allowed to change passwords.

 
 Terms and Definitions
 ---------------------
 
 
 Terms and Definitions
 ---------------------
 

+

 Users
 ~~~~~
 
 Users
 ~~~~~
 


@@ -85,12 +164,14 @@ We store the following attribute for users (`/etc/pve/user.cfg`):
 * flag to enable/disable account
 * comment
 
 * 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.
 
 Superuser
 ^^^^^^^^^
 
 The traditional unix superuser account is called `root@pam`. All
 system mails are forwarded to the email assigned to that account.
 

+

 Groups
 ~~~~~~
 
 Groups
 ~~~~~~
 


@@ -99,6 +180,7 @@ 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.
 
 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
 ~~~~~~~~~~~~~~~~~
 
 Objects and Paths
 ~~~~~~~~~~~~~~~~~
 


@@ -108,6 +190,7 @@ 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.
 
 address those objects. Those paths form a natural tree, and
 permissions can be inherited down that hierarchy.
 

+

 Privileges
 ~~~~~~~~~~
 
 Privileges
 ~~~~~~~~~~
 


@@ -157,6 +240,7 @@ Storage related privileges::
 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images 
 * `Datastore.Audit`: view/browse a datastore
 
 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images 
 * `Datastore.Audit`: view/browse a datastore
 

+

 Roles
 ~~~~~
 
 Roles
 ~~~~~
 


@@ -200,22 +284,18 @@ 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.
 
 the roles assigned to that subject (using the object path). The set of
 roles defines the granted privileges.
 

+

 Inheritance
 ^^^^^^^^^^^
 
 Inheritance
 ^^^^^^^^^^^
 

-As mentioned earlier, object paths forms a filesystem like tree, and
+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:
 
 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.
+* 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.

 
 

-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/

 
 Pools
 ~~~~~
 
 Pools
 ~~~~~


@@ -225,15 +305,70 @@ 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.
 
 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", <subtests>...]` and `["or", <subtests>...]`::
+Each(`and`) or any(`or`) further element in the current list has to be true.
+
+`["perm", <path>, [ <privileges>... ], <options>...]`::
+The `path` is a templated parameter (see <<templated-paths,Objects and
+Paths>>). 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", [ <privileges>... ], <options>...]`::
+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/<group>` 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/<realm>`, with
+`<realm>` 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
+`<username>@<realm>`.
+
+`["perm-modify", <path>]`::
+The `path` is a templated parameter (see <<templated-paths,Objects and
+Paths>>). 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
 -----------------
 
 Most users will simply use the GUI to manage users. But there is also
 a full featured command line tool called `pveum` (short for ``**P**roxmox
 Command Line Tool
 -----------------
 
 Most users will simply use the GUI to manage users. But there is also
 a full featured command line tool called `pveum` (short for ``**P**roxmox

-**VE** **U**ser **M**anager''). I will use that tool in the following
-examples. Please note that all Proxmox VE command line tools are
-wrappers around the API, so you can also access those function through
-the REST API.
+**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
+line tools are wrappers around the API, so you can also access those
+function through the REST API.

 
 Here are some simple usage examples. To show help type:
 
 
 Here are some simple usage examples. To show help type:
 


@@ -274,11 +409,12 @@ Create a new role:
 Real World Examples
 -------------------
 
 Real World Examples
 -------------------
 

+

 Administrator Group
 ~~~~~~~~~~~~~~~~~~~
 
 One of the most wanted features was the ability to define a group of
 Administrator Group
 ~~~~~~~~~~~~~~~~~~~
 
 One of the most wanted features was the ability to define a group of

-users with full administartor rights (without using the root account).
+users with full administrator rights (without using the root account).

 
 Define the group:
 
 
 Define the group:
 


@@ -312,6 +448,7 @@ Example1: Allow user `joe@pve` to see all virtual machines
 [source,bash]
  pveum aclmod /vms -user joe@pve -role PVEAuditor
 
 [source,bash]
  pveum aclmod /vms -user joe@pve -role PVEAuditor
 

+

 Delegate User Management
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Delegate User Management
 ~~~~~~~~~~~~~~~~~~~~~~~~