1 [[chapter_user_management]]
13 pveum - Proxmox VE User Manager
19 include::pveum.1-synopsis.adoc[]
31 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
33 {pve} supports multiple authentication sources, for example Linux PAM,
34 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
35 Directory and OpenID Connect.
37 By using role-based user and permission management for all objects (VMs,
38 Storage, nodes, etc.), granular access can be defined.
45 {pve} stores user attributes in `/etc/pve/user.cfg`.
46 Passwords are not stored here; users are instead associated with the
47 <<pveum_authentication_realms,authentication realms>> described below.
48 Therefore, a user is often internally identified by their username and
49 realm in the form `<userid>@<realm>`.
51 Each user entry in this file contains the following information:
57 * An optional expiration date
58 * A comment or note about this user
59 * Whether this user is enabled or disabled
60 * Optional two-factor authentication keys
62 CAUTION: When you disable or delete a user, or if the expiry date set is
63 in the past, this user will not be able to log in to new sessions or start new
64 tasks. All tasks which have already been started by this user (for example,
65 terminal sessions) will **not** be terminated automatically by any such event.
71 The system's root user can always log in via the Linux PAM realm and is an
72 unconfined administrator. This user cannot be deleted, but attributes can
73 still be changed. System mails will be sent to the email address
74 assigned to this user.
81 Each user can be a member of several groups. Groups are the preferred
82 way to organize access permissions. You should always grant permissions
83 to groups instead of individual users. That way you will get a
84 much more maintainable access control list.
90 API tokens allow stateless access to most parts of the REST API from another
91 system, software or API client. Tokens can be generated for individual users
92 and can be given separate permissions and expiration dates to limit the scope
93 and duration of the access. Should the API token get compromised, it can be
94 revoked without disabling the user itself.
96 API tokens come in two basic types:
98 * Separated privileges: The token needs to be given explicit access with ACLs.
99 Its effective permissions are calculated by intersecting user and token
101 * Full privileges: The token's permissions are identical to that of the
104 CAUTION: The token value is only displayed/returned once when the token is
105 generated. It cannot be retrieved again over the API at a later time!
107 To use an API token, set the HTTP header 'Authorization' to the displayed value
108 of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
109 refer to your API client's documentation.
111 [[pveum_resource_pools]]
115 [thumbnail="screenshot/gui-datacenter-pool-window.png"]
117 A resource pool is a set of virtual machines, containers, and storage
118 devices. It is useful for permission handling in cases where certain users
119 should have controlled access to a specific set of resources, as it allows for a
120 single permission to be applied to a set of elements, rather than having to
121 manage this on a per-resource basis. Resource pools are often used in tandem
122 with groups, so that the members of a group have permissions on a set of
123 machines and storage.
125 [[pveum_authentication_realms]]
126 Authentication Realms
127 ---------------------
129 As {pve} users are just counterparts for users existing on some external
130 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
131 The following realms (authentication methods) are available:
133 Linux PAM Standard Authentication::
135 Linux PAM is a framework for system-wide user authentication. These users are
136 created on the host system with commands such as `adduser`. If PAM users exist
137 on the {pve} host system, corresponding entries can be added to {pve}, to allow
138 these users to log in via their system username and password.
140 {pve} Authentication Server::
142 This is a Unix-like password store, which stores hashed passwords in
143 `/etc/pve/priv/shadow.cfg`. Passwords are hashed using the SHA-256 hashing
144 algorithm. This is the most convenient realm for small-scale (or even
145 mid-scale) installations, where users do not need access to anything outside of
146 {pve}. In this case, users are fully managed by {pve} and are able to change
147 their own passwords via the GUI.
151 LDAP (Lightweight Directory Access Protocol) is an open, cross-platform protocol
152 for authentication using directory services. OpenLDAP is a popular open-source
153 implementations of the LDAP protocol.
155 Microsoft Active Directory (AD)::
157 Microsoft Active Directory (AD) is a directory service for Windows domain
158 networks and is supported as an authentication realm for {pve}. It supports LDAP
159 as an authentication protocol.
163 OpenID Connect is implemented as an identity layer on top of the OATH 2.0
164 protocol. It allows clients to verify the identity of the user, based on
165 authentication performed by an external authorization server.
168 Linux PAM Standard Authentication
169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
171 As Linux PAM corresponds to host system users, a system user must exist on each
172 node which the user is allowed to log in on. The user authenticates with their
173 usual system password. This realm is added by default and can't be removed. In
174 terms of configurability, an administrator can choose to require two-factor
175 authentication with logins from the realm and to set the realm as the default
176 authentication realm.
180 {pve} Authentication Server
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
183 The {pve} authentication server realm is a simple Unix-like password store.
184 The realm is created by default, and as with Linux PAM, the only configuration
185 items available are the ability to require two-factor authentication for users
186 of the realm, and to set it as the default realm for login.
188 Unlike the other {pve} realm types, users are created and authenticated entirely
189 through {pve}, rather than authenticating against another system. Hence, you are
190 required to set a password for this type of user upon creation.
197 You can also use an external LDAP server for user authentication (for examle,
198 OpenLDAP). In this realm type, users are searched under a 'Base Domain Name'
199 (`base_dn`), using the username attribute specified in the 'User Attribute Name'
202 A server and optional fallback server can be configured, and the connection can
203 be encrypted via SSL. Furthermore, filters can be configured for directories and
204 groups. Filters allow you to further limit the scope of the realm.
206 For instance, if a user is represented via the following LDIF dataset:
209 # user1 of People at ldap-test.com
210 dn: uid=user1,ou=People,dc=ldap-test,dc=com
213 objectClass: organizationalPerson
214 objectClass: inetOrgPerson
218 description: This is the first test user.
221 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
222 attribute would be `uid`.
224 If {pve} needs to authenticate (bind) to the LDAP server before being
225 able to query and authenticate users, a bind domain name can be
226 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
227 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
228 (for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
229 single line with the raw password.
231 To verify certificates, you need to set `capath`. You can set it either
232 directly to the CA certificate of your LDAP server, or to the system path
233 containing all trusted CA certificates (`/etc/ssl/certs`).
234 Additionally, you need to set the `verify` option, which can also be done over
237 The main configuration options for an LDAP server realm are as follows:
239 * `Realm` (`realm`): The realm identifier for {pve} users
241 * `Base Domain Name` (`base_dn`): The directory which users are searched under
243 * `User Attribute Name` (`user_attr`): The LDAP attribute containing the
244 username that users will log in with
246 * `Server` (`server1`): The server hosting the LDAP directory
248 * `Fallback Server` (`server2`): An optional fallback server address, in case
249 the primary server is unreachable
251 * `Port` (`port`): The port that the LDAP server listens on
253 NOTE: In order to allow a particular user to authenticate using the LDAP server,
254 you must also add them as a user of that realm from the {pve} server. This can
255 be carried out automatically with <<pveum_ldap_sync, syncing>>.
259 Microsoft Active Directory (AD)
260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
262 To set up Microsoft AD as a realm, a server address and authentication domain
263 need to be specified. Active Directory supports most of the same properties as
264 LDAP, such as an optional fallback server, port, and SSL encryption.
265 Furthermore, users can be added to {pve} automatically via
266 <<pveum_ldap_sync, sync>> operations, after configuration.
268 As with LDAP, if {pve} needs to authenticate before it binds to the AD server,
269 you must configure the 'Bind User' (`bind_dn`) property. This property is
270 typically required by default for Microsoft AD.
272 The main configuration settings for Microsoft Active Directory are:
274 * `Realm` (`realm`): The realm identifier for {pve} users
276 * `Domain` (`domain`): The AD domain of the server
278 * `Server` (`server1`): The FQDN or IP address of the server
280 * `Fallback Server` (`server2`): An optional fallback server address, in case
281 the primary server is unreachable
283 * `Port` (`port`): The port that the Microsoft AD server listens on
286 Syncing LDAP-Based Realms
287 ~~~~~~~~~~~~~~~~~~~~~~~~~
289 [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
291 It's possible to automatically sync users and groups for LDAP-based realms (LDAP
292 & Microsoft Active Directory), rather than having to add them to {pve} manually.
293 You can access the sync options from the Add/Edit window of the web interface's
294 `Authentication` panel or via the `pveum realm add/modify` commands. You can
295 then carry out the sync operation from the `Authentication` panel of the GUI or
296 using the following command:
299 pveum realm sync <realm>
302 Users and groups are synced to the cluster-wide configuration file,
306 Attributes to Properties
307 ^^^^^^^^^^^^^^^^^^^^^^^^
309 If the sync response includes user attributes, they will be synced into the
310 matching user property in the `user.cfg`. For example: `firstname` or
313 If the names of the attributes are not matching the {pve} properties, you can
314 set a custom field-to-field map in the config by using the `sync_attributes`
317 How such properties are handled if anything vanishes can be controlled via the
318 sync options, see below.
323 The configuration options for syncing LDAP-based realms can be found in the
324 `Sync Options` tab of the Add/Edit window.
326 The configuration options are as follows:
328 * `Bind User` (`bind_dn`): Refers to the LDAP account used to query users
329 and groups. This account needs access to all desired entries. If it's set, the
330 search will be carried out via binding; otherwise, the search will be carried
331 out anonymously. The user must be a complete LDAP formatted distinguished name
332 (DN), for example, `cn=admin,dc=example,dc=com`.
334 * Groupname attr. (group_name_attr): Represents the
335 users' groups. Only entries which adhere to the usual character limitations of
336 the `user.cfg` are synced. Groups are synced with `-$realm` attached to the
337 name, in order to avoid naming conflicts. Please ensure that a sync does not
338 overwrite manually created groups.
340 * `User classes` (`user_classes`): Objects classes associated with users.
342 * `Group classes` (`group_classes`): Objects classes associated with groups.
344 * `E-Mail attribute`: If the LDAP-based server specifies user email addresses,
345 these can also be included in the sync by setting the associated attribute
346 here. From the command line, this is achievable through the
347 `--sync_attributes` parameter.
349 * `User Filter` (`filter`): For further filter options to target specific users.
351 * `Group Filter` (`group_filter`): For further filter options to target specific
354 NOTE: Filters allow you to create a set of additional match criteria, to narrow
355 down the scope of a sync. Information on available LDAP filter types and their
356 usage can be found at https://ldap.com/ldap-filters/[ldap.com].
358 [[pveum_ldap_sync_options]]
362 [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
364 In addition to the options specified in the previous section, you can also
365 configure further options that describe the behavior of the sync operation.
367 These options are either set as parameters before the sync, or as defaults via
368 the realm option `sync-defaults-options`.
370 The main options for syncing are:
372 * `Scope` (`scope`): The scope of what to sync. It can be either `users`,
375 * `Enable new` (`enable-new`): If set, the newly synced users are enabled and
376 can log in. The default is `true`.
378 * `Remove Vanished` (`remove-vanished`): This is a list of options which, when
379 activated, determine if they are removed when they are not returned from
380 the sync response. The options are:
382 - `ACL` (`acl)`: Remove ACLs of users and groups which were not returned
383 returned in the sync response. This most often makes sense together with
386 - `Entry` (`entry`): Removes entries (i.e. users and groups) when they are
387 not returned in the sync response.
389 - `Properties` (`properties`): Removes properties of entries where the user
390 in the sync response did not contain those attributes. This includes
391 all properties, even those never set by a sync. Exceptions are tokens
392 and the enable flag, these will be retained even with this option enabled.
394 * `Preview` (`dry-run`): No data is written to the config. This is useful if you
395 want to see which users and groups would get synced to the `user.cfg`.
397 [[pveum_ldap_reserved_characters]]
401 Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be
402 easily used in attribute values in DNs without being escaped properly.
404 Following characters need escaping:
410 * Forward slashes (`/`)
411 * Angle brackets (`<>`)
415 To use such characters in DNs, surround the attribute value in double quotes.
416 For example, to bind with a user with the CN (Common Name) `Example, User`, use
417 `CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`.
419 This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes.
421 NOTE: Users with colons and forward slashes cannot be synced since these are
422 reserved characters in usernames.
428 The main OpenID Connect configuration options are:
430 * `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
431 Proxmox uses the OpenID Connect Discovery protocol to automatically configure
434 While it is possible to use unencrypted `http://` URLs, we strongly recommend to
435 use encrypted `https://` connections.
437 * `Realm` (`realm`): The realm identifier for {pve} users
439 * `Client ID` (`client-id`): OpenID Client ID.
441 * `Client Key` (`client-key`): Optional OpenID Client Key.
443 * `Autocreate Users` (`autocreate`): Automatically create users if they do not
444 exist. While authentication is done at the OpenID server, all users still need
445 an entry in the {pve} user configuration. You can either add them manually, or
446 use the `autocreate` option to automatically add new users.
448 * `Username Claim` (`username-claim`): OpenID claim used to generate the unique
449 username (`subject`, `username` or `email`).
454 The OpenID Connect specification defines a single unique attribute
455 ('claim' in OpenID terms) named `subject`. By default, we use the
456 value of this attribute to generate {pve} usernames, by simple adding
457 `@` and the realm name: `${subject}@${realm}`.
459 Unfortunately, most OpenID servers use random strings for `subject`, like
460 `DGH76OKH34BNG3245SB`, so a typical username would look like
461 `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
462 humans to remember such random strings, making it quite impossible to
463 associate real users with this.
465 The `username-claim` setting allows you to use other attributes for
466 the username mapping. Setting it to `username` is preferred if the
467 OpenID Connect server provides that attribute and guarantees its
470 Another option is to use `email`, which also yields human readable
471 usernames. Again, only use this setting if the server guarantees the
472 uniqueness of this attribute.
477 Here is an example of creating an OpenID realm using Google. You need to
478 replace `--client-id` and `--client-key` with the values
479 from your Google OpenID settings.
482 pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
485 The above command uses `--username-claim email`, so that the usernames on the
486 {pve} side look like `example.user@google.com@myrealm1`.
488 Keycloak (https://www.keycloak.org/) is a popular open source Identity
489 and Access Management tool, which supports OpenID Connect. In the following
490 example, you need to replace the `--issuer-url` and `--client-id` with
494 pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
497 Using `--username-claim username` enables simple usernames on the
498 {pve} side, like `example.user@myrealm2`.
500 WARNING: You need to ensure that the user is not allowed to edit
501 the username setting themselves (on the Keycloak server).
505 Two-Factor Authentication
506 -------------------------
508 There are two ways to use two-factor authentication:
510 It can be required by the authentication realm, either via 'TOTP'
511 (Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly
512 created user needs to have their keys added immediately, as there is no way to
513 log in without the second factor. In the case of 'TOTP', users can
514 also change the 'TOTP' later on, provided they can log in first.
516 Alternatively, users can choose to opt-in to two-factor authentication
517 later on, even if the realm does not enforce it.
519 Available Second Factors
520 ~~~~~~~~~~~~~~~~~~~~~~~~
522 You can set up multiple second factors, in order to avoid a situation in
523 which losing your smartphone or security key locks you out of your
526 The following two-factor authentication methods are available in
527 addition to realm-enforced TOTP and YubiKey OTP:
529 * User configured TOTP
530 (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
531 A short code derived from a shared secret and the current time, it changes
533 * WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
534 A general standard for authentication. It is implemented by various
535 security devices, like hardware keys or trusted platform modules (TPM)
536 from a computer or smart phone.
537 * Single use Recovery Keys. A list of keys which should either be
538 printed out and locked in a secure place or saved digitally in an
539 electronic vault. Each key can be used only once. These are perfect for
540 ensuring that you are not locked out, even if all of your other second
541 factors are lost or corrupt.
543 Before WebAuthn was supported, U2F could be setup by the user. Existing
544 U2F factors can still be used, but it is recommended to switch to
545 WebAuthn, once it is configured on the server.
547 Realm Enforced Two-Factor Authentication
548 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
550 This can be done by selecting one of the available methods via the
551 'TFA' dropdown box when adding or editing an Authentication Realm.
552 When a realm has TFA enabled, it becomes a requirement, and only users
553 with configured TFA will be able to log in.
555 Currently there are two methods available:
557 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm,
558 where the current time is hashed with the user's configured key. The
559 time step and password length parameters are configurable.
561 A user can have multiple keys configured (separated by spaces), and the keys
562 can be specified in Base32 (RFC3548) or hexadecimal notation.
564 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
565 key in Base32 notation, that can be used directly with various OTP tools, such
566 as the `oathtool` command line tool, or on Android Google Authenticator,
567 FreeOTP, andOTP or similar applications.
570 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
571 server URL must be configured, and users must have a YubiKey available. In
572 order to get the key ID from a YubiKey, you can trigger the YubiKey once
573 after connecting it via USB, and copy the first 12 characters of the typed
574 password into the user's 'Key IDs' field.
576 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
577 documentation for how to use the
578 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
579 https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server].
581 [[pveum_user_configured_totp]]
582 User Configured TOTP Authentication
583 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
585 Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login, via
586 the 'TFA' button in the user list (unless the realm enforces 'YubiKey OTP').
588 Users can always add and use one time 'Recovery Keys'.
590 [thumbnail="screenshot/gui-datacenter-two-factor.png"]
592 After opening the 'TFA' window, the user is presented with a dialog to set up
593 'TOTP' authentication. The 'Secret' field contains the key, which can be
594 randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
595 added to provide information to the 'TOTP' app about what the key belongs to.
596 Most 'TOTP' apps will show the issuer name together with the corresponding
597 'OTP' values. The username is also included in the QR code for the 'TOTP' app.
599 After generating a key, a QR code will be displayed, which can be used with most
600 OTP apps such as FreeOTP. The user then needs to verify the current user
601 password (unless logged in as 'root'), as well as the ability to correctly use
602 the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
603 field and pressing the 'Apply' button.
605 [[user_tfa_setup_totp]]
608 [thumbnail="screenshot/pve-gui-tfa-add-totp.png"]
610 There is no server setup required. Simply install a TOTP app on your
611 smartphone (for example, https://freeotp.github.io/[FreeOTP]) and use
612 the Proxmox Backup Server web-interface to add a TOTP factor.
614 [[user_tfa_setup_webauthn]]
617 For WebAuthn to work, you need to have two things:
619 * A trusted HTTPS certificate (for example, by using
620 https://pve.proxmox.com/wiki/Certificate_Management[Let's Encrypt]).
621 While it probably works with an untrusted certificate, some browsers may
622 warn or refuse WebAuthn operations if it is not trusted.
623 * Setup the WebAuthn configuration (see *Datacenter -> Options ->
624 WebAuthn Settings* in the Proxmox VE web interface). This can be
625 auto-filled in most setups.
627 Once you have fulfilled both of these requirements, you can add a WebAuthn
628 configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
631 [[user_tfa_setup_recovery_keys]]
634 [thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]
636 Recovery key codes do not need any preparation; you can simply create a
637 set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
640 NOTE: There can only be one set of single-use recovery keys per user at any
644 [[pveum_configure_webauthn]]
645 Server Side Webauthn Configuration
646 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
648 [thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]
650 To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
651 domain with a valid SSL certificate, otherwise some browsers may warn or refuse
652 to authenticate altogether.
654 NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
655 registrations unusable!
657 This is done via `/etc/pve/datacenter.cfg`. For instance:
660 webauthn: rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
663 [[pveum_configure_u2f]]
664 Server Side U2F Configuration
665 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
667 NOTE: It is recommended to use WebAuthn instead.
669 To allow users to use 'U2F' authentication, it may be necessary to use a valid
670 domain with a valid SSL certificate, otherwise, some browsers may print
671 a warning or reject U2F usage altogether. Initially, an 'AppId'
672 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
673 needs to be configured.
675 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
678 This is done via `/etc/pve/datacenter.cfg`. For instance:
681 u2f: appid=https://mypve.example.com:8006
684 For a single node, the 'AppId' can simply be the address of the web-interface,
685 exactly as it is used in the browser, including the 'https://' and the port, as
686 shown above. Please note that some browsers may be more strict than others when
689 When using multiple nodes, it is best to have a separate `https` server
690 providing an `appid.json`
691 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
692 file, as it seems to be compatible with most
693 browsers. If all nodes use subdomains of the same top level domain, it may be
694 enough to use the TLD as 'AppId'. It should however be noted that some browsers
697 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
698 situations when this does not happen, particularly when using a top level domain
699 'AppId' for a node that is accessed via a subdomain in Chromium. For this reason
700 it is recommended to test the configuration with multiple browsers, as changing
701 the 'AppId' later will render existing 'U2F' registrations unusable.
703 [[pveum_user_configured_u2f]]
704 Activating U2F as a User
705 ~~~~~~~~~~~~~~~~~~~~~~~~
707 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
708 current password (unless logged in as root), and press the 'Register' button.
709 If the server is set up correctly and the browser accepts the server's provided
710 'AppId', a message will appear prompting the user to press the button on the
711 'U2F' device (if it is a 'YubiKey', the button light should be toggling on and
712 off steadily, roughly twice per second).
714 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
715 before they can use a 'U2F' token.
717 [[pveum_permission_management]]
718 Permission Management
719 ---------------------
721 In order for a user to perform an action (such as listing, modifying or
722 deleting parts of a VM's configuration), the user needs to have the
723 appropriate permissions.
725 {pve} uses a role and path based permission management system. An entry in
726 the permissions table allows a user, group or token to take on a specific role
727 when accessing an 'object' or 'path'. This means that such an access rule can
728 be represented as a triple of '(path, user, role)', '(path, group,
729 role)' or '(path, token, role)', with the role containing a set of allowed
730 actions, and the path representing the target of these actions.
737 A role is simply a list of privileges. Proxmox VE comes with a number
738 of predefined roles, which satisfy most requirements.
740 * `Administrator`: has full privileges
741 * `NoAccess`: has no privileges (used to forbid access)
742 * `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`)
743 * `PVEAuditor`: has read only access
744 * `PVEDatastoreAdmin`: create and allocate backup space and templates
745 * `PVEDatastoreUser`: allocate backup space and view storage
746 * `PVEPoolAdmin`: allocate pools
747 * `PVESysAdmin`: User ACLs, audit, system console and system logs
748 * `PVETemplateUser`: view and clone templates
749 * `PVEUserAdmin`: manage users
750 * `PVEVMAdmin`: fully administer VMs
751 * `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management
753 You can see the whole set of predefined roles in the GUI.
755 You can add new roles via the GUI or the command line.
757 [thumbnail="screenshot/gui-datacenter-role-add.png"]
758 From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and
759 click on the 'Create' button. There you can set a role name and select any
760 desired privileges from the 'Privileges' drop-down menu.
762 To add a role through the command line, you can use the 'pveum' CLI tool, for
766 pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
767 pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
774 A privilege is the right to perform a specific action. To simplify
775 management, lists of privileges are grouped into roles, which can then
776 be used in the permission table. Note that privileges cannot be directly
777 assigned to users and paths without being part of a role.
779 We currently support the following privileges:
781 Node / System related privileges::
783 * `Permissions.Modify`: modify access permissions
784 * `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...)
785 * `Sys.Console`: console access to node
786 * `Sys.Syslog`: view syslog
787 * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
788 * `Sys.Modify`: create/modify/remove node network parameters
789 * `Sys.Incoming`: allow incoming data streams from other clusters (experimental)
790 * `Group.Allocate`: create/modify/remove groups
791 * `Pool.Allocate`: create/modify/remove a pool
792 * `Pool.Audit`: view a pool
793 * `Realm.Allocate`: create/modify/remove authentication realms
794 * `Realm.AllocateUser`: assign user to a realm
795 * `User.Modify`: create/modify/remove user access and details.
797 Virtual machine related privileges::
799 * `VM.Allocate`: create/remove VM on a server
800 * `VM.Migrate`: migrate VM to alternate server on cluster
801 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
802 * `VM.Console`: console access to VM
803 * `VM.Monitor`: access to VM monitor (kvm)
804 * `VM.Backup`: backup/restore VMs
805 * `VM.Audit`: view VM config
806 * `VM.Clone`: clone/copy a VM
807 * `VM.Config.Disk`: add/modify/remove disks
808 * `VM.Config.CDROM`: eject/change CD-ROM
809 * `VM.Config.CPU`: modify CPU settings
810 * `VM.Config.Memory`: modify memory settings
811 * `VM.Config.Network`: add/modify/remove network devices
812 * `VM.Config.HWType`: modify emulated hardware types
813 * `VM.Config.Options`: modify any other VM configuration
814 * `VM.Config.Cloudinit`: modify Cloud-init parameters
815 * `VM.Snapshot`: create/delete VM snapshots
817 Storage related privileges::
819 * `Datastore.Allocate`: create/modify/remove a datastore and delete volumes
820 * `Datastore.AllocateSpace`: allocate space on a datastore
821 * `Datastore.AllocateTemplate`: allocate/upload templates and ISO images
822 * `Datastore.Audit`: view/browse a datastore
828 Access permissions are assigned to objects, such as virtual machines,
829 storages or resource pools.
830 We use file system like paths to address these objects. These paths form a
831 natural tree, and permissions of higher levels (shorter paths) can
832 optionally be propagated down within this hierarchy.
834 [[pveum_templated_paths]]
835 Paths can be templated. When an API call requires permissions on a
836 templated path, the path may contain references to parameters of the API
837 call. These references are specified in curly braces. Some parameters are
838 implicitly taken from the API call's URI. For instance, the permission path
839 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
840 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
841 refers to the method's `path` parameter.
845 * `/nodes/{node}`: Access to {pve} server machines
846 * `/vms`: Covers all VMs
847 * `/vms/{vmid}`: Access to specific VMs
848 * `/storage/{storeid}`: Access to a specific storage
849 * `/pool/{poolname}`: Access to resources contained in a specific <<pveum_pools,pool>>
850 * `/access/groups`: Group administration
851 * `/access/realms/{realmid}`: Administrative access to realms
857 As mentioned earlier, object paths form a file system like tree, and
858 permissions can be inherited by objects down that tree (the propagate flag is
859 set by default). We use the following inheritance rules:
861 * Permissions for individual users always replace group permissions.
862 * Permissions for groups apply when the user is member of that group.
863 * Permissions on deeper levels replace those inherited from an upper level.
865 Additionally, privilege separated tokens can never have permissions on any
866 given path that their associated user does not have.
872 Pools can be used to group a set of virtual machines and datastores. You can
873 then simply set permissions on pools (`/pool/{poolid}`), which are inherited by
874 all pool members. This is a great way to simplify access control.
877 Which Permissions Do I Need?
878 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
880 The required API permissions are documented for each individual
881 method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/.
883 The permissions are specified as a list, which can be interpreted as a
884 tree of logic and access-check functions:
886 `["and", <subtests>...]` and `["or", <subtests>...]`::
887 Each(`and`) or any(`or`) further element in the current list has to be true.
889 `["perm", <path>, [ <privileges>... ], <options>...]`::
890 The `path` is a templated parameter (see
891 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
892 option is used, any) of the listed
893 privileges must be allowed on the specified path. If a `require-param`
894 option is specified, then its specified parameter is required even if the
895 API call's schema otherwise lists it as being optional.
897 `["userid-group", [ <privileges>... ], <options>...]`::
898 The caller must have any of the listed privileges on `/access/groups`. In
899 addition, there are two possible checks, depending on whether the
900 `groups_param` option is set:
902 * `groups_param` is set: The API call has a non-optional `groups` parameter
903 and the caller must have any of the listed privileges on all of the listed
905 * `groups_param` is not set: The user passed via the `userid` parameter
906 must exist and be part of a group on which the caller has any of the listed
907 privileges (via the `/access/groups/<group>` path).
909 `["userid-param", "self"]`::
910 The value provided for the API call's `userid` parameter must refer to the
911 user performing the action (usually in conjunction with `or`, to allow
912 users to perform an action on themselves, even if they don't have elevated
915 `["userid-param", "Realm.AllocateUser"]`::
916 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
917 `<realm>` referring to the realm of the user passed via the `userid`
918 parameter. Note that the user does not need to exist in order to be
919 associated with a realm, since user IDs are passed in the form of
920 `<username>@<realm>`.
922 `["perm-modify", <path>]`::
923 The `path` is a templated parameter (see
924 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
925 `Permissions.Modify` privilege or,
926 depending on the path, the following privileges as a possible substitute:
928 * `/storage/...`: requires 'Datastore.Allocate`
929 * `/vms/...`: requires 'VM.Allocate`
930 * `/pool/...`: requires 'Pool.Allocate`
932 If the path is empty, `Permission.Modify` on `/access` is required.
937 Most users will simply use the GUI to manage users. But there is also
938 a fully featured command line tool called `pveum` (short for ``**P**roxmox
939 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
940 line tools are wrappers around the API, so you can also access those
941 functions through the REST API.
943 Here are some simple usage examples. To show help, type:
948 or (to show detailed help about a specific command)
956 pveum user add testuser@pve -comment "Just a test"
958 Set or change the password (not all realms support this):
961 pveum passwd testuser@pve
966 pveum user modify testuser@pve -enable 0
971 pveum group add testgroup
976 pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
986 It is possible that an administrator would want to create a group of users with
987 full administrator rights (without using the root account).
989 To do this, first define the group:
992 pveum group add admin -comment "System Administrators"
994 Then assign the role:
997 pveum acl modify / -group admin -role Administrator
999 Finally, you can add users to the new 'admin' group:
1002 pveum user modify testuser@pve -group admin
1008 You can give read only access to users by assigning the `PVEAuditor`
1009 role to users or groups.
1011 Example 1: Allow user `joe@pve` to see everything
1014 pveum acl modify / -user joe@pve -role PVEAuditor
1016 Example 2: Allow user `joe@pve` to see all virtual machines
1019 pveum acl modify /vms -user joe@pve -role PVEAuditor
1022 Delegate User Management
1023 ~~~~~~~~~~~~~~~~~~~~~~~~
1025 If you want to delegate user management to user `joe@pve`, you can do
1029 pveum acl modify /access -user joe@pve -role PVEUserAdmin
1031 User `joe@pve` can now add and remove users, and change other user attributes,
1032 such as passwords. This is a very powerful role, and you most
1033 likely want to limit it to selected realms and groups. The following
1034 example allows `joe@pve` to modify users within the realm `pve`, if they
1035 are members of group `customers`:
1038 pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
1039 pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
1041 NOTE: The user is able to add other users, but only if they are
1042 members of the group `customers` and within the realm `pve`.
1044 Limited API Token for Monitoring
1045 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1047 Permissions on API tokens are always a subset of those of their corresponding
1048 user, meaning that an API token can't be used to carry out a task that the
1049 backing user has no permission to do. This section will demonstrate how you can
1050 use an API token with separate privileges, to limit the token owner's
1051 permissions further.
1053 Give the user `joe@pve` the role PVEVMAdmin on all VMs:
1056 pveum acl modify /vms -user joe@pve -role PVEVMAdmin
1058 Add a new API token with separate privileges, which is only allowed to view VM
1059 information (for example, for monitoring purposes):
1062 pveum user token add joe@pve monitoring -privsep 1
1063 pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
1065 Verify the permissions of the user and token:
1068 pveum user permissions joe@pve
1069 pveum user token permissions joe@pve monitoring
1074 An enterprise is usually structured into several smaller departments, and it is
1075 common that you want to assign resources and delegate management tasks to each
1076 of these. Let's assume that you want to set up a pool for a software development
1077 department. First, create a group:
1080 pveum group add developers -comment "Our software developers"
1082 Now we create a new user which is a member of that group:
1085 pveum user add developer1@pve -group developers -password
1087 NOTE: The "-password" parameter will prompt you for a password
1089 Then we create a resource pool for our development department to use:
1092 pveum pool add dev-pool --comment "IT development pool"
1094 Finally, we can assign permissions to that pool:
1097 pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
1099 Our software developers can now administer the resources assigned to
1104 include::pve-copyright.adoc[]