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.
167 Linux PAM Standard Authentication
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170 As Linux PAM corresponds to host system users, a system user must exist on each
171 node which the user is allowed to log in on. The user authenticates with their
172 usual system password. This realm is added by default and can't be removed. In
173 terms of configurability, an administrator can choose to require two-factor
174 authentication with logins from the realm and to set the realm as the default
175 authentication realm.
178 {pve} Authentication Server
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
181 The {pve} authentication server realm is a simple Unix-like password store.
182 The realm is created by default, and as with Linux PAM, the only configuration
183 items available are the ability to require two-factor authentication for users
184 of the realm, and to set it as the default realm for login.
186 Unlike the other {pve} realm types, users are created and authenticated entirely
187 through {pve}, rather than authenticating against another system. Hence, you are
188 required to set a password for this type of user upon creation.
194 You can also use an external LDAP server for user authentication (for examle,
195 OpenLDAP). In this realm type, users are searched under a 'Base Domain Name'
196 (`base_dn`), using the username attribute specified in the 'User Attribute Name'
199 A server and optional fallback server can be configured, and the connection can
200 be encrypted via SSL. Furthermore, filters can be configured for directories and
201 groups. Filters allow you to further limit the scope of the realm.
203 For instance, if a user is represented via the following LDIF dataset:
206 # user1 of People at ldap-test.com
207 dn: uid=user1,ou=People,dc=ldap-test,dc=com
210 objectClass: organizationalPerson
211 objectClass: inetOrgPerson
215 description: This is the first test user.
218 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
219 attribute would be `uid`.
221 If {pve} needs to authenticate (bind) to the LDAP server before being
222 able to query and authenticate users, a bind domain name can be
223 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
224 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
225 (for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
226 single line with the raw password.
228 To verify certificates, you need to set `capath`. You can set it either
229 directly to the CA certificate of your LDAP server, or to the system path
230 containing all trusted CA certificates (`/etc/ssl/certs`).
231 Additionally, you need to set the `verify` option, which can also be done over
234 The main configuration options for an LDAP server realm are as follows:
236 * `Realm` (`realm`): The realm identifier for {pve} users
238 * `Base Domain Name` (`base_dn`): The directory which users are searched under
240 * `User Attribute Name` (`user_attr`): The LDAP attribute containing the
241 username that users will log in with
243 * `Server` (`server1`): The server hosting the LDAP directory
245 * `Fallback Server` (`server2`): An optional fallback server address, in case
246 the primary server is unreachable
248 * `Port` (`port`): The port that the LDAP server listens on
250 NOTE: In order to allow a particular user to authenticate using the LDAP server,
251 you must also add them as a user of that realm from the {pve} server. This can
252 be carried out automatically with <<pveum_ldap_sync, syncing>>.
255 Microsoft Active Directory (AD)
256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258 To set up Microsoft AD as a realm, a server address and authentication domain
259 need to be specified. Active Directory supports most of the same properties as
260 LDAP, such as an optional fallback server, port, and SSL encryption.
261 Furthermore, users can be added to {pve} automatically via
262 <<pveum_ldap_sync, sync>> operations, after configuration.
264 As with LDAP, if {pve} needs to authenticate before it binds to the AD server,
265 you must configure the 'Bind User' (`bind_dn`) property. This property is
266 typically required by default for Microsoft AD.
268 The main configuration settings for Microsoft Active Directory are:
270 * `Realm` (`realm`): The realm identifier for {pve} users
272 * `Domain` (`domain`): The AD domain of the server
274 * `Server` (`server1`): The FQDN or IP address of the server
276 * `Fallback Server` (`server2`): An optional fallback server address, in case
277 the primary server is unreachable
279 * `Port` (`port`): The port that the Microsoft AD server listens on
282 Syncing LDAP-Based Realms
283 ~~~~~~~~~~~~~~~~~~~~~~~~~
285 [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
287 It's possible to automatically sync users and groups for LDAP-based realms (LDAP
288 & Microsoft Active Directory), rather than having to add them to {pve} manually.
289 You can access the sync options from the Add/Edit window of the web interface's
290 `Authentication` panel or via the `pveum realm add/modify` commands. You can
291 then carry out the sync operation from the `Authentication` panel of the GUI or
292 using the following command:
295 pveum realm sync <realm>
298 Users and groups are synced to the cluster-wide configuration file,
302 Attributes to Properties
303 ^^^^^^^^^^^^^^^^^^^^^^^^
305 If the sync response includes user attributes, they will be synced into the
306 matching user property in the `user.cfg`. For example: `firstname` or
309 If the names of the attributes are not matching the {pve} properties, you can
310 set a custom field-to-field map in the config by using the `sync_attributes`
313 How such properties are handled if anything vanishes can be controlled via the
314 sync options, see below.
319 The configuration options for syncing LDAP-based realms can be found in the
320 `Sync Options` tab of the Add/Edit window.
322 The configuration options are as follows:
324 * `Bind User` (`bind_dn`): Refers to the LDAP account used to query users
325 and groups. This account needs access to all desired entries. If it's set, the
326 search will be carried out via binding; otherwise, the search will be carried
327 out anonymously. The user must be a complete LDAP formatted distinguished name
328 (DN), for example, `cn=admin,dc=example,dc=com`.
330 * Groupname attr. (group_name_attr): Represents the
331 users' groups. Only entries which adhere to the usual character limitations of
332 the `user.cfg` are synced. Groups are synced with `-$realm` attached to the
333 name, in order to avoid naming conflicts. Please ensure that a sync does not
334 overwrite manually created groups.
336 * `User classes` (`user_classes`): Objects classes associated with users.
338 * `Group classes` (`group_classes`): Objects classes associated with groups.
340 * `E-Mail attribute`: If the LDAP-based server specifies user email addresses,
341 these can also be included in the sync by setting the associated attribute
342 here. From the command line, this is achievable through the
343 `--sync_attributes` parameter.
345 * `User Filter` (`filter`): For further filter options to target specific users.
347 * `Group Filter` (`group_filter`): For further filter options to target specific
350 NOTE: Filters allow you to create a set of additional match criteria, to narrow
351 down the scope of a sync. Information on available LDAP filter types and their
352 usage can be found at https://ldap.com/ldap-filters/[ldap.com].
354 [[pveum_ldap_sync_options]]
358 [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
360 In addition to the options specified in the previous section, you can also
361 configure further options that describe the behavior of the sync operation.
363 These options are either set as parameters before the sync, or as defaults via
364 the realm option `sync-defaults-options`.
366 The main options for syncing are:
368 * `Scope` (`scope`): The scope of what to sync. It can be either `users`,
371 * `Enable new` (`enable-new`): If set, the newly synced users are enabled and
372 can log in. The default is `true`.
374 * `Remove Vanished` (`remove-vanished`): This is a list of options which, when
375 activated, determine if they are removed when they are not returned from
376 the sync response. The options are:
378 - `ACL` (`acl)`: Remove ACLs of users and groups which were not returned
379 returned in the sync response. This most often makes sense together with
382 - `Entry` (`entry`): Removes entries (i.e. users and groups) when they are
383 not returned in the sync response.
385 - `Properties` (`properties`): Removes properties of entries where the user
386 in the sync response did not contain those attributes. This includes
387 all properties, even those never set by a sync. Exceptions are tokens
388 and the enable flag, these will be retained even with this option enabled.
390 * `Preview` (`dry-run`): No data is written to the config. This is useful if you
391 want to see which users and groups would get synced to the `user.cfg`.
398 The main OpenID Connect configuration options are:
400 * `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
401 Proxmox uses the OpenID Connect Discovery protocol to automatically configure
404 While it is possible to use unencrypted `http://` URLs, we strongly recommend to
405 use encrypted `https://` connections.
407 * `Realm` (`realm`): The realm identifier for {pve} users
409 * `Client ID` (`client-id`): OpenID Client ID.
411 * `Client Key` (`client-key`): Optional OpenID Client Key.
413 * `Autocreate Users` (`autocreate`): Automatically create users if they do not
414 exist. While authentication is done at the OpenID server, all users still need
415 an entry in the {pve} user configuration. You can either add them manually, or
416 use the `autocreate` option to automatically add new users.
418 * `Username Claim` (`username-claim`): OpenID claim used to generate the unique
419 username (`subject`, `username` or `email`).
424 The OpenID Connect specification defines a single unique attribute
425 ('claim' in OpenID terms) named `subject`. By default, we use the
426 value of this attribute to generate {pve} usernames, by simple adding
427 `@` and the realm name: `${subject}@${realm}`.
429 Unfortunately, most OpenID servers use random strings for `subject`, like
430 `DGH76OKH34BNG3245SB`, so a typical username would look like
431 `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
432 humans to remember such random strings, making it quite impossible to
433 associate real users with this.
435 The `username-claim` setting allows you to use other attributes for
436 the username mapping. Setting it to `username` is preferred if the
437 OpenID Connect server provides that attribute and guarantees its
440 Another option is to use `email`, which also yields human readable
441 usernames. Again, only use this setting if the server guarantees the
442 uniqueness of this attribute.
447 Here is an example of creating an OpenID realm using Google. You need to
448 replace `--client-id` and `--client-key` with the values
449 from your Google OpenID settings.
452 pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
455 The above command uses `--username-claim email`, so that the usernames on the
456 {pve} side look like `example.user@google.com@myrealm1`.
458 Keycloak (https://www.keycloak.org/) is a popular open source Identity
459 and Access Management tool, which supports OpenID Connect. In the following
460 example, you need to replace the `--issuer-url` and `--client-id` with
464 pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
467 Using `--username-claim username` enables simple usernames on the
468 {pve} side, like `example.user@myrealm2`.
470 WARNING: You need to ensure that the user is not allowed to edit
471 the username setting themselves (on the Keycloak server).
475 Two-Factor Authentication
476 -------------------------
478 There are two ways to use two-factor authentication:
480 It can be required by the authentication realm, either via 'TOTP'
481 (Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly
482 created user needs to have their keys added immediately, as there is no way to
483 log in without the second factor. In the case of 'TOTP', users can
484 also change the 'TOTP' later on, provided they can log in first.
486 Alternatively, users can choose to opt-in to two-factor authentication
487 later on, even if the realm does not enforce it.
489 Available Second Factors
490 ~~~~~~~~~~~~~~~~~~~~~~~~
492 You can set up multiple second factors, in order to avoid a situation in
493 which losing your smartphone or security key locks you out of your
496 The following two-factor authentication methods are available in
497 addition to realm-enforced TOTP and YubiKey OTP:
499 * User configured TOTP
500 (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
501 A short code derived from a shared secret and the current time, it changes
503 * WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
504 A general standard for authentication. It is implemented by various
505 security devices, like hardware keys or trusted platform modules (TPM)
506 from a computer or smart phone.
507 * Single use Recovery Keys. A list of keys which should either be
508 printed out and locked in a secure place or saved digitally in an
509 electronic vault. Each key can be used only once. These are perfect for
510 ensuring that you are not locked out, even if all of your other second
511 factors are lost or corrupt.
513 Before WebAuthn was supported, U2F could be setup by the user. Existing
514 U2F factors can still be used, but it is recommended to switch to
515 WebAuthn, once it is configured on the server.
517 Realm Enforced Two-Factor Authentication
518 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
520 This can be done by selecting one of the available methods via the
521 'TFA' dropdown box when adding or editing an Authentication Realm.
522 When a realm has TFA enabled, it becomes a requirement, and only users
523 with configured TFA will be able to log in.
525 Currently there are two methods available:
527 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm,
528 where the current time is hashed with the user's configured key. The
529 time step and password length parameters are configurable.
531 A user can have multiple keys configured (separated by spaces), and the keys
532 can be specified in Base32 (RFC3548) or hexadecimal notation.
534 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
535 key in Base32 notation, that can be used directly with various OTP tools, such
536 as the `oathtool` command line tool, or on Android Google Authenticator,
537 FreeOTP, andOTP or similar applications.
540 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
541 server URL must be configured, and users must have a YubiKey available. In
542 order to get the key ID from a YubiKey, you can trigger the YubiKey once
543 after connecting it via USB, and copy the first 12 characters of the typed
544 password into the user's 'Key IDs' field.
546 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
547 documentation for how to use the
548 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
549 https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server].
551 [[pveum_user_configured_totp]]
552 User Configured TOTP Authentication
553 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
555 Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login, via
556 the 'TFA' button in the user list (unless the realm enforces 'YubiKey OTP').
558 Users can always add and use one time 'Recovery Keys'.
560 [thumbnail="screenshot/gui-datacenter-two-factor.png"]
562 After opening the 'TFA' window, the user is presented with a dialog to set up
563 'TOTP' authentication. The 'Secret' field contains the key, which can be
564 randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
565 added to provide information to the 'TOTP' app about what the key belongs to.
566 Most 'TOTP' apps will show the issuer name together with the corresponding
567 'OTP' values. The username is also included in the QR code for the 'TOTP' app.
569 After generating a key, a QR code will be displayed, which can be used with most
570 OTP apps such as FreeOTP. The user then needs to verify the current user
571 password (unless logged in as 'root'), as well as the ability to correctly use
572 the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
573 field and pressing the 'Apply' button.
575 [[user_tfa_setup_totp]]
578 [thumbnail="screenshot/pve-gui-tfa-add-totp.png"]
580 There is no server setup required. Simply install a TOTP app on your
581 smartphone (for example, https://freeotp.github.io/[FreeOTP]) and use
582 the Proxmox Backup Server web-interface to add a TOTP factor.
584 [[user_tfa_setup_webauthn]]
587 For WebAuthn to work, you need to have two things:
589 * A trusted HTTPS certificate (for example, by using
590 https://pve.proxmox.com/wiki/Certificate_Management[Let's Encrypt]).
591 While it probably works with an untrusted certificate, some browsers may
592 warn or refuse WebAuthn operations if it is not trusted.
593 * Setup the WebAuthn configuration (see *Datacenter -> Options ->
594 WebAuthn Settings* in the Proxmox VE web interface). This can be
595 auto-filled in most setups.
597 Once you have fulfilled both of these requirements, you can add a WebAuthn
598 configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
601 [[user_tfa_setup_recovery_keys]]
604 [thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]
606 Recovery key codes do not need any preparation; you can simply create a
607 set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
610 NOTE: There can only be one set of single-use recovery keys per user at any
614 [[pveum_configure_webauthn]]
615 Server Side Webauthn Configuration
616 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
618 [thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]
620 To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
621 domain with a valid SSL certificate, otherwise some browsers may warn or refuse
622 to authenticate altogether.
624 NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
625 registrations unusable!
627 This is done via `/etc/pve/datacenter.cfg`. For instance:
630 webauthn: rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
633 [[pveum_configure_u2f]]
634 Server Side U2F Configuration
635 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
637 NOTE: It is recommended to use WebAuthn instead.
639 To allow users to use 'U2F' authentication, it may be necessary to use a valid
640 domain with a valid SSL certificate, otherwise, some browsers may print
641 a warning or reject U2F usage altogether. Initially, an 'AppId'
642 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
643 needs to be configured.
645 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
648 This is done via `/etc/pve/datacenter.cfg`. For instance:
651 u2f: appid=https://mypve.example.com:8006
654 For a single node, the 'AppId' can simply be the address of the web-interface,
655 exactly as it is used in the browser, including the 'https://' and the port, as
656 shown above. Please note that some browsers may be more strict than others when
659 When using multiple nodes, it is best to have a separate `https` server
660 providing an `appid.json`
661 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
662 file, as it seems to be compatible with most
663 browsers. If all nodes use subdomains of the same top level domain, it may be
664 enough to use the TLD as 'AppId'. It should however be noted that some browsers
667 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
668 situations when this does not happen, particularly when using a top level domain
669 'AppId' for a node that is accessed via a subdomain in Chromium. For this reason
670 it is recommended to test the configuration with multiple browsers, as changing
671 the 'AppId' later will render existing 'U2F' registrations unusable.
673 [[pveum_user_configured_u2f]]
674 Activating U2F as a User
675 ~~~~~~~~~~~~~~~~~~~~~~~~
677 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
678 current password (unless logged in as root), and press the 'Register' button.
679 If the server is set up correctly and the browser accepts the server's provided
680 'AppId', a message will appear prompting the user to press the button on the
681 'U2F' device (if it is a 'YubiKey', the button light should be toggling on and
682 off steadily, roughly twice per second).
684 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
685 before they can use a 'U2F' token.
687 [[pveum_permission_management]]
688 Permission Management
689 ---------------------
691 In order for a user to perform an action (such as listing, modifying or
692 deleting parts of a VM's configuration), the user needs to have the
693 appropriate permissions.
695 {pve} uses a role and path based permission management system. An entry in
696 the permissions table allows a user, group or token to take on a specific role
697 when accessing an 'object' or 'path'. This means that such an access rule can
698 be represented as a triple of '(path, user, role)', '(path, group,
699 role)' or '(path, token, role)', with the role containing a set of allowed
700 actions, and the path representing the target of these actions.
707 A role is simply a list of privileges. Proxmox VE comes with a number
708 of predefined roles, which satisfy most requirements.
710 * `Administrator`: has full privileges
711 * `NoAccess`: has no privileges (used to forbid access)
712 * `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`)
713 * `PVEAuditor`: has read only access
714 * `PVEDatastoreAdmin`: create and allocate backup space and templates
715 * `PVEDatastoreUser`: allocate backup space and view storage
716 * `PVEPoolAdmin`: allocate pools
717 * `PVESysAdmin`: User ACLs, audit, system console and system logs
718 * `PVETemplateUser`: view and clone templates
719 * `PVEUserAdmin`: manage users
720 * `PVEVMAdmin`: fully administer VMs
721 * `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management
723 You can see the whole set of predefined roles in the GUI.
725 You can add new roles via the GUI or the command line.
727 [thumbnail="screenshot/gui-datacenter-role-add.png"]
728 From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and
729 click on the 'Create' button. There you can set a role name and select any
730 desired privileges from the 'Privileges' drop-down menu.
732 To add a role through the command line, you can use the 'pveum' CLI tool, for
736 pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
737 pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
744 A privilege is the right to perform a specific action. To simplify
745 management, lists of privileges are grouped into roles, which can then
746 be used in the permission table. Note that privileges cannot be directly
747 assigned to users and paths without being part of a role.
749 We currently support the following privileges:
751 Node / System related privileges::
753 * `Permissions.Modify`: modify access permissions
754 * `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...)
755 * `Sys.Console`: console access to node
756 * `Sys.Syslog`: view syslog
757 * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
758 * `Sys.Modify`: create/modify/remove node network parameters
759 * `Sys.Incoming`: allow incoming data streams from other clusters (experimental)
760 * `Group.Allocate`: create/modify/remove groups
761 * `Pool.Allocate`: create/modify/remove a pool
762 * `Pool.Audit`: view a pool
763 * `Realm.Allocate`: create/modify/remove authentication realms
764 * `Realm.AllocateUser`: assign user to a realm
765 * `User.Modify`: create/modify/remove user access and details.
767 Virtual machine related privileges::
769 * `VM.Allocate`: create/remove VM on a server
770 * `VM.Migrate`: migrate VM to alternate server on cluster
771 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
772 * `VM.Console`: console access to VM
773 * `VM.Monitor`: access to VM monitor (kvm)
774 * `VM.Backup`: backup/restore VMs
775 * `VM.Audit`: view VM config
776 * `VM.Clone`: clone/copy a VM
777 * `VM.Config.Disk`: add/modify/remove disks
778 * `VM.Config.CDROM`: eject/change CD-ROM
779 * `VM.Config.CPU`: modify CPU settings
780 * `VM.Config.Memory`: modify memory settings
781 * `VM.Config.Network`: add/modify/remove network devices
782 * `VM.Config.HWType`: modify emulated hardware types
783 * `VM.Config.Options`: modify any other VM configuration
784 * `VM.Config.Cloudinit`: modify Cloud-init parameters
785 * `VM.Snapshot`: create/delete VM snapshots
787 Storage related privileges::
789 * `Datastore.Allocate`: create/modify/remove a datastore and delete volumes
790 * `Datastore.AllocateSpace`: allocate space on a datastore
791 * `Datastore.AllocateTemplate`: allocate/upload templates and ISO images
792 * `Datastore.Audit`: view/browse a datastore
798 Access permissions are assigned to objects, such as virtual machines,
799 storages or resource pools.
800 We use file system like paths to address these objects. These paths form a
801 natural tree, and permissions of higher levels (shorter paths) can
802 optionally be propagated down within this hierarchy.
804 [[pveum_templated_paths]]
805 Paths can be templated. When an API call requires permissions on a
806 templated path, the path may contain references to parameters of the API
807 call. These references are specified in curly braces. Some parameters are
808 implicitly taken from the API call's URI. For instance, the permission path
809 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
810 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
811 refers to the method's `path` parameter.
815 * `/nodes/{node}`: Access to {pve} server machines
816 * `/vms`: Covers all VMs
817 * `/vms/{vmid}`: Access to specific VMs
818 * `/storage/{storeid}`: Access to a specific storage
819 * `/pool/{poolname}`: Access to resources contained in a specific <<pveum_pools,pool>>
820 * `/access/groups`: Group administration
821 * `/access/realms/{realmid}`: Administrative access to realms
827 As mentioned earlier, object paths form a file system like tree, and
828 permissions can be inherited by objects down that tree (the propagate flag is
829 set by default). We use the following inheritance rules:
831 * Permissions for individual users always replace group permissions.
832 * Permissions for groups apply when the user is member of that group.
833 * Permissions on deeper levels replace those inherited from an upper level.
835 Additionally, privilege separated tokens can never have permissions on any
836 given path that their associated user does not have.
842 Pools can be used to group a set of virtual machines and datastores. You can
843 then simply set permissions on pools (`/pool/{poolid}`), which are inherited by
844 all pool members. This is a great way to simplify access control.
847 Which Permissions Do I Need?
848 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
850 The required API permissions are documented for each individual
851 method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/.
853 The permissions are specified as a list, which can be interpreted as a
854 tree of logic and access-check functions:
856 `["and", <subtests>...]` and `["or", <subtests>...]`::
857 Each(`and`) or any(`or`) further element in the current list has to be true.
859 `["perm", <path>, [ <privileges>... ], <options>...]`::
860 The `path` is a templated parameter (see
861 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
862 option is used, any) of the listed
863 privileges must be allowed on the specified path. If a `require-param`
864 option is specified, then its specified parameter is required even if the
865 API call's schema otherwise lists it as being optional.
867 `["userid-group", [ <privileges>... ], <options>...]`::
868 The caller must have any of the listed privileges on `/access/groups`. In
869 addition, there are two possible checks, depending on whether the
870 `groups_param` option is set:
872 * `groups_param` is set: The API call has a non-optional `groups` parameter
873 and the caller must have any of the listed privileges on all of the listed
875 * `groups_param` is not set: The user passed via the `userid` parameter
876 must exist and be part of a group on which the caller has any of the listed
877 privileges (via the `/access/groups/<group>` path).
879 `["userid-param", "self"]`::
880 The value provided for the API call's `userid` parameter must refer to the
881 user performing the action (usually in conjunction with `or`, to allow
882 users to perform an action on themselves, even if they don't have elevated
885 `["userid-param", "Realm.AllocateUser"]`::
886 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
887 `<realm>` referring to the realm of the user passed via the `userid`
888 parameter. Note that the user does not need to exist in order to be
889 associated with a realm, since user IDs are passed in the form of
890 `<username>@<realm>`.
892 `["perm-modify", <path>]`::
893 The `path` is a templated parameter (see
894 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
895 `Permissions.Modify` privilege or,
896 depending on the path, the following privileges as a possible substitute:
898 * `/storage/...`: requires 'Datastore.Allocate`
899 * `/vms/...`: requires 'VM.Allocate`
900 * `/pool/...`: requires 'Pool.Allocate`
902 If the path is empty, `Permission.Modify` on `/access` is required.
907 Most users will simply use the GUI to manage users. But there is also
908 a fully featured command line tool called `pveum` (short for ``**P**roxmox
909 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
910 line tools are wrappers around the API, so you can also access those
911 functions through the REST API.
913 Here are some simple usage examples. To show help, type:
918 or (to show detailed help about a specific command)
926 pveum user add testuser@pve -comment "Just a test"
928 Set or change the password (not all realms support this):
931 pveum passwd testuser@pve
936 pveum user modify testuser@pve -enable 0
941 pveum group add testgroup
946 pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
956 It is possible that an administrator would want to create a group of users with
957 full administrator rights (without using the root account).
959 To do this, first define the group:
962 pveum group add admin -comment "System Administrators"
964 Then assign the role:
967 pveum acl modify / -group admin -role Administrator
969 Finally, you can add users to the new 'admin' group:
972 pveum user modify testuser@pve -group admin
978 You can give read only access to users by assigning the `PVEAuditor`
979 role to users or groups.
981 Example 1: Allow user `joe@pve` to see everything
984 pveum acl modify / -user joe@pve -role PVEAuditor
986 Example 2: Allow user `joe@pve` to see all virtual machines
989 pveum acl modify /vms -user joe@pve -role PVEAuditor
992 Delegate User Management
993 ~~~~~~~~~~~~~~~~~~~~~~~~
995 If you want to delegate user management to user `joe@pve`, you can do
999 pveum acl modify /access -user joe@pve -role PVEUserAdmin
1001 User `joe@pve` can now add and remove users, and change other user attributes,
1002 such as passwords. This is a very powerful role, and you most
1003 likely want to limit it to selected realms and groups. The following
1004 example allows `joe@pve` to modify users within the realm `pve`, if they
1005 are members of group `customers`:
1008 pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
1009 pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
1011 NOTE: The user is able to add other users, but only if they are
1012 members of the group `customers` and within the realm `pve`.
1014 Limited API Token for Monitoring
1015 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1017 Permissions on API tokens are always a subset of those of their corresponding
1018 user, meaning that an API token can't be used to carry out a task that the
1019 backing user has no permission to do. This section will demonstrate how you can
1020 use an API token with separate privileges, to limit the token owner's
1021 permissions further.
1023 Give the user `joe@pve` the role PVEVMAdmin on all VMs:
1026 pveum acl modify /vms -user joe@pve -role PVEVMAdmin
1028 Add a new API token with separate privileges, which is only allowed to view VM
1029 information (for example, for monitoring purposes):
1032 pveum user token add joe@pve monitoring -privsep 1
1033 pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
1035 Verify the permissions of the user and token:
1038 pveum user permissions joe@pve
1039 pveum user token permissions joe@pve monitoring
1044 An enterprise is usually structured into several smaller departments, and it is
1045 common that you want to assign resources and delegate management tasks to each
1046 of these. Let's assume that you want to set up a pool for a software development
1047 department. First, create a group:
1050 pveum group add developers -comment "Our software developers"
1052 Now we create a new user which is a member of that group:
1055 pveum user add developer1@pve -group developers -password
1057 NOTE: The "-password" parameter will prompt you for a password
1059 Then we create a resource pool for our development department to use:
1062 pveum pool add dev-pool --comment "IT development pool"
1064 Finally, we can assign permissions to that pool:
1067 pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
1069 Our software developers can now administer the resources assigned to
1074 include::pve-copyright.adoc[]