1 [[chapter_user_management]]
10 pveum - Proxmox VE User Manager
16 include::pveum.1-synopsis.adoc[]
28 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
30 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
31 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
34 By using the role based user- and permission management for all
35 objects (VMs, storages, nodes, etc.) granular access can be defined.
42 {pve} stores user attributes in `/etc/pve/user.cfg`.
43 Passwords are not stored here, users are instead associated with
44 <<pveum_authentication_realms,authentication realms>> described below.
45 Therefore a user is internally often identified by its name and
46 realm in the form `<userid>@<realm>`.
48 Each user entry in this file contains the following information:
54 * An optional Expiration date
55 * A comment or note about this user
56 * Whether this user is enabled or disabled
57 * Optional two-factor authentication keys
63 The system's root user can always log in via the Linux PAM realm and is an
64 unconfined administrator. This user cannot be deleted, but attributes can
65 still be changed and system mails will be sent to the email address
66 assigned to this user.
73 Each user can be member of several groups. Groups are the preferred
74 way to organize access permissions. You should always grant permission
75 to groups instead of using individual users. That way you will get a
76 much shorter access control list which is easier to handle.
82 API tokens allow stateless access to most parts of the REST API by another
83 system, software or API client. Tokens can be generated for individual users
84 and can be given separate permissions and expiration dates to limit the scope
85 and duration of the access. Should the API token get compromised it can be
86 revoked without disabling the user itself.
88 API tokens come in two basic types:
90 * separated privileges: the token needs to be given explicit access with ACLs,
91 its effective permissions are calculated by intersecting user and token
93 * full privileges: the token permissions are identical to that of the
96 CAUTION: The token value is only displayed/returned once when the token is
97 generated. It cannot be retrieved again over the API at a later time!
99 To use an API token, set the HTTP header 'Authorization' to the displayed value
100 of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
101 refer to your API client documentation.
103 [[pveum_authentication_realms]]
104 Authentication Realms
105 ---------------------
107 As {pve} users are just counterparts for users existing on some external
108 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
109 The following realms (authentication methods) are available:
111 Linux PAM standard authentication::
112 In this case a system user has to exist (e.g. created via the `adduser`
113 command) on all nodes the user is allowed to login, and the user
114 authenticates with their usual system password.
121 usermod -a -G watchman heinz
124 Proxmox VE authentication server::
125 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
126 Password are encrypted using the SHA-256 hash method.
127 This is the most convenient method for small (or even medium)
128 installations where users do not need access to anything outside of
129 {pve}. In this case users are fully managed by {pve} and are able to
130 change their own passwords via the GUI.
133 It is possible to authenticate users via an LDAP server (e.g.
134 openldap). The server and an optional fallback server can be
135 configured and the connection can be encrypted via SSL.
137 Users are searched under a 'Base Domain Name' (`base_dn`), with the
138 user name found in the attribute specified in the 'User Attribute Name'
141 For instance, if a user is represented via the
142 following ldif dataset:
145 # user1 of People at ldap-test.com
146 dn: uid=user1,ou=People,dc=ldap-test,dc=com
149 objectClass: organizationalPerson
150 objectClass: inetOrgPerson
154 description: This is the first test user.
157 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
158 attribute would be `uid`.
160 If {pve} needs to authenticate (bind) to the ldap server before being
161 able to query and authenticate users, a bind domain name can be
162 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
163 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
164 (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
165 single line containing the raw password.
167 To verify certificates, you need to to set `capath`. You can set it either
168 directly to the CA certificate of your LDAP server, or to the system path
169 containing all trusted CA certificates (`/etc/ssl/certs`).
170 Additionally, you need to set the `verify` option, which can also be doen over
173 Microsoft Active Directory::
175 A server and authentication domain need to be specified. Like with
176 ldap an optional fallback server, optional port, and SSL
177 encryption can be configured.
180 Syncing LDAP-based realms
181 ~~~~~~~~~~~~~~~~~~~~~~~~~
183 [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
185 It is possible to sync users and groups for LDAP based realms. You can use the
189 pveum realm sync <realm>
191 or in the `Authentication` panel of the GUI. Users and groups are synced to the
192 cluster-wide user configuration file `/etc/pve/user.cfg`.
194 Requirements and limitations
195 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
197 The `bind_dn` is used to query the users and groups. This account needs access
198 to all desired entries.
200 The fields which represent the names of the users and groups can be configured
201 via the `user_attr` and `group_name_attr` respectively. Only entries which
202 adhere to the usual character limitations of the user.cfg are synced.
204 Groups are synced with `-$realm` attached to the name, to avoid naming
205 conflicts. Please make sure that a sync does not overwrite manually created
208 [[pveum_ldap_sync_options]]
212 [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
214 The main options for syncing are:
216 * `dry-run`: No data is written to the config. This is useful if you want to
217 see which users and groups would get synced to the user.cfg. This is set
218 when you click `Preview` in the GUI.
220 * `enable-new`: If set, the newly synced users are enabled and can login.
221 The default is `true`.
223 * `full`: If set, the sync uses the LDAP Directory as a source of truth,
224 overwriting information set manually in the user.cfg and deletes users
225 and groups which are not present in the LDAP directory. If not set,
226 only new data is written to the config, and no stale users are deleted.
228 * `purge`: If set, sync removes all corresponding ACLs when removing users
229 and groups. This is only useful with the option `full`.
231 * `scope`: The scope of what to sync. It can be either `users`, `groups` or
234 These options are either set as parameters or as defaults, via the
235 realm option `sync-defaults-options`.
238 Two-factor authentication
239 -------------------------
241 There are two ways to use two-factor authentication:
243 It can be required by the authentication realm, either via 'TOTP'
244 (Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly
245 created user needs their keys added immediately as there is no way to
246 log in without the second factor. In the case of 'TOTP', users can
247 also change the 'TOTP' later on, provided they can log in first.
249 Alternatively, users can choose to opt in to two-factor authentication
250 via 'TOTP' later on, even if the realm does not enforce it. As another
251 option, if the server has an 'AppId' configured, a user can opt into
252 'U2F' authentication, provided the realm does not enforce any other
255 Realm enforced two-factor authentication
256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258 This can be done by selecting one of the available methods via the
259 'TFA' dropdown box when adding or editing an Authentication Realm.
260 When a realm has TFA enabled it becomes a requirement and only users
261 with configured TFA will be able to login.
263 Currently there are two methods available:
265 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm
266 where the current time is hashed with the user's configured key. The
267 time step and password length parameters are configured.
269 A user can have multiple keys configured (separated by spaces), and the keys
270 can be specified in Base32 (RFC3548) or hexadecimal notation.
272 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
273 key in Base32 notation which can be used directly with various OTP tools, such
274 as the `oathtool` command line tool, or on Android Google Authenticator,
275 FreeOTP, andOTP or similar applications.
278 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
279 server URL must be configured, and users must have a YubiKey available. In
280 order to get the key ID from a YubiKey, you can trigger the YubiKey once
281 after connecting it to USB and copy the first 12 characters of the typed
282 password into the user's 'Key IDs' field.
285 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
286 documentation for how to use the
287 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
288 https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host
289 your own verification server].
291 [[pveum_user_configured_totp]]
292 User configured TOTP authentication
293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
295 Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
296 button in the user list (unless the realm enforces 'YubiKey OTP').
298 [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
300 After opening the 'TFA' window, the user is presented with a dialog to setup
301 'TOTP' authentication. The 'Secret' field contains the key, which can simply be
302 generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
303 added to provide information to the 'TOTP' app what the key belongs to.
304 Most 'TOTP' apps will show the issuer name together with the corresponding
305 'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
307 After generating a key, a QR code will be displayed which can be used with most
308 OTP apps such as FreeOTP. Now the user needs to verify both the current user
309 password (unless logged in as 'root'), as well as the ability to correctly use
310 the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
311 field before pressing the 'Apply' button.
313 [[pveum_configure_u2f]]
314 Server side U2F configuration
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317 To allow users to use 'U2F' authentication, the server needs to have a valid
318 domain with a valid https certificate. Initially an 'AppId'
319 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
320 needs to be configured.
322 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
325 This is done via `/etc/pve/datacenter.cfg`, for instance:
328 u2f: appid=https://mypve.example.com:8006
331 For a single node, the 'AppId' can simply be the web UI address exactly as it
332 is used in the browser, including the 'https://' and the port as shown above.
333 Please note that some browsers may be more strict than others when matching
336 When using multiple nodes, it is best to have a separate `https` server
337 providing an `appid.json`
338 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
339 file, as it seems to be compatible with most
340 browsers. If all nodes use subdomains of the same top level domain, it may be
341 enough to use the TLD as 'AppId', but note that some browsers may not accept
344 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
345 situation where this does not happen, particularly when using a top level domain
346 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
347 recommended to test the configuration with multiple browsers, as changing the
348 'AppId' later will render existing 'U2F' registrations unusable.
350 [[pveum_user_configured_u2f]]
351 Activating U2F as a user
352 ~~~~~~~~~~~~~~~~~~~~~~~~
354 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
355 current password (unless logged in as root), and press the 'Register' button.
356 If the server is setup correctly and the browser accepted the server's provided
357 'AppId', a message will appear prompting the user to press the button on the
358 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
359 on steadily around twice per second).
361 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
362 before they can use a 'U2F' token.
364 [[pveum_permission_management]]
365 Permission Management
366 ---------------------
368 In order for a user to perform an action (such as listing, modifying or
369 deleting a parts of a VM configuration), the user needs to have the
370 appropriate permissions.
372 {pve} uses a role and path based permission management system. An entry in
373 the permissions table allows a user, group or token to take on a specific role
374 when accessing an 'object' or 'path'. This means an such an access rule can
375 be represented as a triple of '(path, user, role)', '(path, group,
376 role)' or '(path, token, role)', with the role containing a set of allowed
377 actions, and the path representing the target of these actions.
384 A role is simply a list of privileges. Proxmox VE comes with a number
385 of predefined roles which satisfies most needs.
387 * `Administrator`: has all privileges
388 * `NoAccess`: has no privileges (used to forbid access)
389 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
390 * `PVEAuditor`: read only access
391 * `PVEDatastoreAdmin`: create and allocate backup space and templates
392 * `PVEDatastoreUser`: allocate backup space and view storage
393 * `PVEPoolAdmin`: allocate pools
394 * `PVESysAdmin`: User ACLs, audit, system console and system logs
395 * `PVETemplateUser`: view and clone templates
396 * `PVEUserAdmin`: user administration
397 * `PVEVMAdmin`: fully administer VMs
398 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
400 You can see the whole set of predefined roles on the GUI.
402 Adding new roles can be done via both GUI and the command line.
404 [thumbnail="screenshot/gui-datacenter-role-add.png"]
405 For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and
406 click on the 'Create' button, there you can set a name and select all desired
407 roles from the 'Privileges' dropdown box.
409 To add a role through the command line you can use the 'pveum' CLI tool, like
413 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
414 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
421 A privilege is the right to perform a specific action. To simplify
422 management, lists of privileges are grouped into roles, which can then
423 be used in the permission table. Note that privileges cannot directly be
424 assigned to users and paths without being part of a role.
426 We currently use the following privileges:
428 Node / System related privileges::
430 * `Permissions.Modify`: modify access permissions
431 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
432 * `Sys.Console`: console access to Node
433 * `Sys.Syslog`: view Syslog
434 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
435 * `Sys.Modify`: create/remove/modify node network parameters
436 * `Group.Allocate`: create/remove/modify groups
437 * `Pool.Allocate`: create/remove/modify a pool
438 * `Realm.Allocate`: create/remove/modify authentication realms
439 * `Realm.AllocateUser`: assign user to a realm
440 * `User.Modify`: create/remove/modify user access and details.
442 Virtual machine related privileges::
444 * `VM.Allocate`: create/remove new VM to server inventory
445 * `VM.Migrate`: migrate VM to alternate server on cluster
446 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
447 * `VM.Console`: console access to VM
448 * `VM.Monitor`: access to VM monitor (kvm)
449 * `VM.Backup`: backup/restore VMs
450 * `VM.Audit`: view VM config
451 * `VM.Clone`: clone/copy a VM
452 * `VM.Config.Disk`: add/modify/delete Disks
453 * `VM.Config.CDROM`: eject/change CDROM
454 * `VM.Config.CPU`: modify CPU settings
455 * `VM.Config.Memory`: modify Memory settings
456 * `VM.Config.Network`: add/modify/delete Network devices
457 * `VM.Config.HWType`: modify emulated HW type
458 * `VM.Config.Options`: modify any other VM configuration
459 * `VM.Snapshot`: create/remove VM snapshots
461 Storage related privileges::
463 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
464 * `Datastore.AllocateSpace`: allocate space on a datastore
465 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
466 * `Datastore.Audit`: view/browse a datastore
472 Access permissions are assigned to objects, such as a virtual machines,
473 storages or pools of resources.
474 We use file system like paths to address these objects. These paths form a
475 natural tree, and permissions of higher levels (shorter path) can
476 optionally be propagated down within this hierarchy.
478 [[pveum_templated_paths]]
479 Paths can be templated. When an API call requires permissions on a
480 templated path, the path may contain references to parameters of the API
481 call. These references are specified in curly braces. Some parameters are
482 implicitly taken from the API call's URI. For instance the permission path
483 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
484 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
485 refers to the method's `path` parameter.
489 * `/nodes/{node}`: Access to {pve} server machines
490 * `/vms`: Covers all VMs
491 * `/vms/{vmid}`: Access to specific VMs
492 * `/storage/{storeid}`: Access to a storages
493 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
494 * `/access/groups`: Group administration
495 * `/access/realms/{realmid}`: Administrative access to realms
501 As mentioned earlier, object paths form a file system like tree, and
502 permissions can be inherited down that tree (the propagate flag is set
503 by default). We use the following inheritance rules:
505 * Permissions for individual users always replace group permissions.
506 * Permissions for groups apply when the user is member of that group.
507 * Permissions replace the ones inherited from an upper level.
509 Additionally, privilege separated tokens can never have a permission on any
510 given path that their associated user does not have.
516 Pools can be used to group a set of virtual machines and data
517 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
518 which are inherited to all pool members. This is a great way simplify
522 What permission do I need?
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~
525 The required API permissions are documented for each individual
526 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
528 The permissions are specified as a list which can be interpreted as a
529 tree of logic and access-check functions:
531 `["and", <subtests>...]` and `["or", <subtests>...]`::
532 Each(`and`) or any(`or`) further element in the current list has to be true.
534 `["perm", <path>, [ <privileges>... ], <options>...]`::
535 The `path` is a templated parameter (see
536 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
537 option is used, any) of the listed
538 privileges must be allowed on the specified path. If a `require-param`
539 option is specified, then its specified parameter is required even if the
540 API call's schema otherwise lists it as being optional.
542 `["userid-group", [ <privileges>... ], <options>...]`::
543 The caller must have any of the listed privileges on `/access/groups`. In
544 addition there are two possible checks depending on whether the
545 `groups_param` option is set:
547 * `groups_param` is set: The API call has a non-optional `groups` parameter
548 and the caller must have any of the listed privileges on all of the listed
550 * `groups_param` is not set: The user passed via the `userid` parameter
551 must exist and be part of a group on which the caller has any of the listed
552 privileges (via the `/access/groups/<group>` path).
554 `["userid-param", "self"]`::
555 The value provided for the API call's `userid` parameter must refer to the
556 user performing the action. (Usually in conjunction with `or`, to allow
557 users to perform an action on themselves even if they don't have elevated
560 `["userid-param", "Realm.AllocateUser"]`::
561 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
562 `<realm>` referring to the realm of the user passed via the `userid`
563 parameter. Note that the user does not need to exist in order to be
564 associated with a realm, since user IDs are passed in the form of
565 `<username>@<realm>`.
567 `["perm-modify", <path>]`::
568 The `path` is a templated parameter (see
569 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
570 `Permissions.Modify` privilege, or,
571 depending on the path, the following privileges as a possible substitute:
573 * `/storage/...`: additionally requires 'Datastore.Allocate`
574 * `/vms/...`: additionally requires 'VM.Allocate`
575 * `/pool/...`: additionally requires 'Pool.Allocate`
577 If the path is empty, `Permission.Modify` on `/access` is required.
582 Most users will simply use the GUI to manage users. But there is also
583 a fully featured command line tool called `pveum` (short for ``**P**roxmox
584 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
585 line tools are wrappers around the API, so you can also access those
586 functions through the REST API.
588 Here are some simple usage examples. To show help type:
593 or (to show detailed help about a specific command)
601 pveum useradd testuser@pve -comment "Just a test"
603 Set or Change the password (not all realms support that):
606 pveum passwd testuser@pve
611 pveum usermod testuser@pve -enable 0
616 pveum groupadd testgroup
621 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
631 One of the most wanted features was the ability to define a group of
632 users with full administrator rights (without using the root account).
637 pveum groupadd admin -comment "System Administrators"
639 Then add the permission:
642 pveum aclmod / -group admin -role Administrator
644 You can finally add users to the new 'admin' group:
647 pveum usermod testuser@pve -group admin
653 You can give read only access to users by assigning the `PVEAuditor`
654 role to users or groups.
656 Example1: Allow user `joe@pve` to see everything
659 pveum aclmod / -user joe@pve -role PVEAuditor
661 Example1: Allow user `joe@pve` to see all virtual machines
664 pveum aclmod /vms -user joe@pve -role PVEAuditor
667 Delegate User Management
668 ~~~~~~~~~~~~~~~~~~~~~~~~
670 If you want to delegate user management to user `joe@pve` you can do
674 pveum aclmod /access -user joe@pve -role PVEUserAdmin
676 User `joe@pve` can now add and remove users, change passwords and
677 other user attributes. This is a very powerful role, and you most
678 likely want to limit that to selected realms and groups. The following
679 example allows `joe@pve` to modify users within realm `pve` if they
680 are members of group `customers`:
683 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
684 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
686 NOTE: The user is able to add other users, but only if they are
687 members of group `customers` and within realm `pve`.
689 Limited API token for monitoring
690 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
692 Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
695 pveum aclmod /vms -user joe@pve -role PVEVMAdmin
697 Add a new API token with separate privileges, which is only allowed to view VM
698 information (e.g., for monitoring purposes):
701 pveum user token add joe@pve monitoring -privsep 1
702 pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor
704 Verify the permissions of the user and token:
707 pveum user permissions joe@pve
708 pveum user token permissions joe@pve monitoring
713 An enterprise is usually structured into several smaller departments,
714 and it is common that you want to assign resources to them and
715 delegate management tasks. A pool is simply a set of virtual machines
716 and data stores. You can create pools on the GUI. After that you can
717 add resources to the pool (VMs, Storage).
719 You can also assign permissions to the pool. Those permissions are
720 inherited to all pool members.
722 Lets assume you have a software development department, so we first
726 pveum groupadd developers -comment "Our software developers"
728 Now we create a new user which is a member of that group
731 pveum useradd developer1@pve -group developers -password
733 NOTE: The -password parameter will prompt you for a password
735 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
738 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
740 Our software developers can now administrate the resources assigned to
745 include::pve-copyright.adoc[]