* An optional Expiration date
* A comment or note about this user
* Whether this user is enabled or disabled
-* Optional two factor authentication keys
+* Optional two-factor authentication keys
System administrator
[[pveum_groups]]
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.
+[[pveum_tokens]]
+API Tokens
+----------
+
+API tokens allow stateless access to most parts of the REST API by another
+system, software or API client. Tokens can be generated for individual users
+and can be given separate permissions and expiration dates to limit the scope
+and duration of the access. Should the API token get compromised it can be
+revoked without disabling the user itself.
+
+API tokens come in two basic types:
+
+* separated privileges: the token needs to be given explicit access with ACLs,
+ its effective permissions are calculated by intersecting user and token
+ permissions.
+* full privileges: the token permissions are identical to that of the
+ associated user.
+
+CAUTION: The token value is only displayed/returned once when the token is
+generated. It cannot be retrieved again over the API at a later time!
+
+To use an API token, set the HTTP header 'Authorization' to the displayed value
+of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
+refer to your API client documentation.
+
+[[pveum_resource_pools]]
+Resource Pools
+--------------
+
+[thumbnail="screenshot/gui-datacenter-pool-window.png"]
+
+A resource pool is a set of virtual machines, containers, and storage
+devices. It is useful for permission handling in cases where certain users
+should have controlled access to a specific set of resources, as it allows for a
+single permission to be applied to a set of elements, rather than having to
+manage this on a per resource basis. Resource pools are often used in tandem
+with groups so that the members of a group have permissions on a set of machines
+and storage.
[[pveum_authentication_realms]]
Authentication Realms
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
+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`
(e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
single line containing the raw password.
++
+To verify certificates, you need to to set `capath`. You can set it either
+directly to the CA certificate of your LDAP server, or to the system path
+containing all trusted CA certificates (`/etc/ssl/certs`).
+Additionally, you need to set the `verify` option, which can also be done over
+the web interface.
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.
+A server and authentication domain need to be specified. Like with LDAP, an
+optional fallback server, port, and SSL encryption can be configured.
+
+[[pveum_ldap_sync]]
+Syncing LDAP-based realms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
+
+It is possible to sync users and groups for LDAP based realms. You can use the
+CLI command
+
+----
+ pveum realm sync <realm>
+----
+or in the `Authentication` panel of the GUI. Users and groups are synced to the
+cluster-wide user configuration file `/etc/pve/user.cfg`.
+
+Requirements and limitations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `bind_dn` is used to query the users and groups. This account needs access
+to all desired entries.
+
+The fields which represent the names of the users and groups can be configured
+via the `user_attr` and `group_name_attr` respectively. Only entries which
+adhere to the usual character limitations of the user.cfg are synced.
+
+Groups are synced with `-$realm` attached to the name, to avoid naming
+conflicts. Please make sure that a sync does not overwrite manually created
+groups.
+
+[[pveum_ldap_sync_options]]
+Options
+^^^^^^^
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
+
+The main options for syncing are:
+
+* `dry-run`: No data is written to the config. This is useful if you want to
+ see which users and groups would get synced to the user.cfg. This is set
+ when you click `Preview` in the GUI.
+
+* `enable-new`: If set, the newly synced users are enabled and can login.
+ The default is `true`.
+
+* `full`: If set, the sync uses the LDAP Directory as a source of truth,
+ overwriting information set manually in the user.cfg and deletes users
+ and groups which are not present in the LDAP directory. If not set,
+ only new data is written to the config, and no stale users are deleted.
+
+* `purge`: If set, sync removes all corresponding ACLs when removing users
+ and groups. This is only useful with the option `full`.
+
+* `scope`: The scope of what to sync. It can be either `users`, `groups` or
+ `both`.
+
+These options are either set as parameters or as defaults, via the
+realm option `sync-defaults-options`.
[[pveum_tfa_auth]]
-Two factor authentication
+Two-factor authentication
-------------------------
-There are two ways to use two factor authentication:
+There are two ways to use two-factor authentication:
-It can be required by the authentication realm, either via 'TOTP' or
-'YubiKey OTP'. In this case a newly created user needs their keys added
-immediately as there is no way to log in without the second factor. In the case
-of 'TOTP' a user can also change the 'TOTP' later on provided they can log in
-first.
+It can be required by the authentication realm, either via 'TOTP'
+(Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly
+created user needs their keys added immediately as there is no way to
+log in without the second factor. In the case of 'TOTP', users can
+also change the 'TOTP' later on, provided they can log in first.
-Alternatively a user can choose to opt into two factor authentication via 'TOTP'
-later on even if the realm does not enforce it. As another option, if the server
-has an 'AppId' configured, a user can opt into 'U2F' authentication, provided
-the realm does not enforce any other second factor.
+Alternatively, users can choose to opt in to two-factor authentication
+via 'TOTP' later on, even if the realm does not enforce it. As another
+option, if the server has an 'AppId' configured, a user can opt into
+'U2F' authentication, provided the realm does not enforce any other
+second factor.
-Realm enforced two factor authentication
+Realm enforced 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.
+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.
+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.
+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.
+{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, or on Android Google Authenticator,
+FreeOTP, andOTP or similar applications.
YubiKey OTP::
For authenticating via a YubiKey a Yubico API ID, API KEY and validation
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
+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].
+https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host
+your own verification server].
[[pveum_user_configured_totp]]
User configured TOTP authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button
-in the user list, unless the realm enforces 'YubiKey OTP'.
+Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
+button in the user list (unless the realm enforces 'YubiKey OTP').
[thumbnail="screenshot/gui-datacenter-users-tfa.png"]
the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
field before pressing the 'Apply' button.
+[[pveum_configure_u2f]]
Server side U2F configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To allow users to use 'U2F' authentication, the server needs to have a valid
-domain with a valid https certificate. Initially an 'AppId'
+To allow users to use 'U2F' authentication, it may be necessary to use a valid
+domain with a valid https certificate, otherwise some browsers may print
+a warning or reject U2F usage altogether. Initially an 'AppId'
footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
needs to be configured.
appropriate permissions.
{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
+the permissions table allows a user, group or token 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.
+be represented as a triple of '(path, user, role)', '(path, group,
+role)' or '(path, token, role)', with the role containing a set of allowed
+actions, and the path representing the target of these actions.
[[pveum_roles]]
* `PVETemplateUser`: view and clone templates
* `PVEUserAdmin`: user administration
* `PVEVMAdmin`: fully administer VMs
-* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
+* `PVEVMUser`: view, backup, config CD-ROM, VM console, VM power management
You can see the whole set of predefined roles on the GUI.
* `VM.Audit`: view VM config
* `VM.Clone`: clone/copy a VM
* `VM.Config.Disk`: add/modify/delete Disks
-* `VM.Config.CDROM`: eject/change CDROM
+* `VM.Config.CDROM`: eject/change CD-ROM
* `VM.Config.CPU`: modify CPU settings
* `VM.Config.Memory`: modify Memory settings
* `VM.Config.Network`: add/modify/delete Network devices
* Permissions for groups apply when the user is member of that group.
* Permissions replace the ones inherited from an upper level.
+Additionally, privilege separated tokens can never have a permission on any
+given path that their associated user does not have.
[[pveum_pools]]
Pools
or (to show detailed help about a specific command)
[source,bash]
- pveum help useradd
+ pveum help user add
Create a new user:
[source,bash]
- pveum useradd testuser@pve -comment "Just a test"
+ pveum user add testuser@pve -comment "Just a test"
Set or Change the password (not all realms support that):
Disable a user:
[source,bash]
- pveum usermod testuser@pve -enable 0
+ pveum user modify testuser@pve -enable 0
Create a new group:
[source,bash]
- pveum groupadd testgroup
+ pveum group add testgroup
Create a new role:
[source,bash]
- pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+ pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
Real World Examples
Define the group:
[source,bash]
- pveum groupadd admin -comment "System Administrators"
+ pveum group add admin -comment "System Administrators"
Then add the permission:
[source,bash]
- pveum aclmod / -group admin -role Administrator
+ pveum acl modify / -group admin -role Administrator
You can finally add users to the new 'admin' group:
[source,bash]
- pveum usermod testuser@pve -group admin
+ pveum user modify testuser@pve -group admin
Auditors
Example1: Allow user `joe@pve` to see everything
[source,bash]
- pveum aclmod / -user joe@pve -role PVEAuditor
+ pveum acl modify / -user joe@pve -role PVEAuditor
Example1: Allow user `joe@pve` to see all virtual machines
[source,bash]
- pveum aclmod /vms -user joe@pve -role PVEAuditor
+ pveum acl modify /vms -user joe@pve -role PVEAuditor
Delegate User Management
that with:
[source,bash]
- pveum aclmod /access -user joe@pve -role PVEUserAdmin
+ pveum acl modify /access -user joe@pve -role PVEUserAdmin
User `joe@pve` can now add and remove users, change passwords and
other user attributes. This is a very powerful role, and you most
are members of group `customers`:
[source,bash]
- pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
- pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
+ pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
+ pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
NOTE: The user is able to add other users, but only if they are
members of group `customers` and within realm `pve`.
+Limited API token for monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Pools
-~~~~~
+Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
-An enterprise is usually structured into several smaller departments,
-and it is common that you want to assign resources to them and
-delegate management tasks. A pool is simply a set of virtual machines
-and data stores. You can create pools on the GUI. After that you can
-add resources to the pool (VMs, Storage).
+[source,bash]
+ pveum acl modify /vms -user joe@pve -role PVEVMAdmin
+
+Add a new API token with separate privileges, which is only allowed to view VM
+information (e.g., for monitoring purposes):
+
+[source,bash]
+ pveum user token add joe@pve monitoring -privsep 1
+ pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
+
+Verify the permissions of the user and token:
-You can also assign permissions to the pool. Those permissions are
-inherited to all pool members.
+[source,bash]
+ pveum user permissions joe@pve
+ pveum user token permissions joe@pve monitoring
+
+Resource Pools
+~~~~~~~~~~~~~~
-Lets assume you have a software development department, so we first
-create a group
+An enterprise is usually structured into several smaller departments, and it is
+common that you want to assign resources and delegate management tasks to each
+of these. Let's assume that you want to set up a pool for a software development
+department. First, create a group
[source,bash]
- pveum groupadd developers -comment "Our software developers"
+ pveum group add developers -comment "Our software developers"
Now we create a new user which is a member of that group
[source,bash]
- pveum useradd developer1@pve -group developers -password
+ pveum user add developer1@pve -group developers -password
NOTE: The -password parameter will prompt you for a password
-I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
+Then we create a resource pool for our development department to use
+
+[source,bash]
+ pveum pool add dev-pool --comment "IT development pool"
+
+Finally, we can assign permissions to that pool
[source,bash]
- pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
+ pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
Our software developers can now administrate the resources assigned to
that pool.
projects / pve-docs.git / blobdiff