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_resource_pools]]
107 [thumbnail="screenshot/gui-datacenter-pool-window.png"]
109 A resource pool is a set of virtual machines, containers, and storage
110 devices. It is useful for permission handling in cases where certain users
111 should have controlled access to a specific set of resources, as it allows for a
112 single permission to be applied to a set of elements, rather than having to
113 manage this on a per resource basis. Resource pools are often used in tandem
114 with groups so that the members of a group have permissions on a set of machines
117 [[pveum_authentication_realms]]
118 Authentication Realms
119 ---------------------
121 As {pve} users are just counterparts for users existing on some external
122 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
123 The following realms (authentication methods) are available:
125 Linux PAM standard authentication::
126 In this case a system user has to exist (e.g. created via the `adduser`
127 command) on all nodes the user is allowed to login, and the user
128 authenticates with their usual system password.
135 usermod -a -G watchman heinz
138 Proxmox VE authentication server::
139 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
140 Password are encrypted using the SHA-256 hash method.
141 This is the most convenient method for small (or even medium)
142 installations where users do not need access to anything outside of
143 {pve}. In this case users are fully managed by {pve} and are able to
144 change their own passwords via the GUI.
147 It is possible to authenticate users via an LDAP server (e.g.
148 openldap). The server and an optional fallback server can be
149 configured and the connection can be encrypted via SSL.
151 Users are searched under a 'Base Domain Name' (`base_dn`), with the
152 user name found in the attribute specified in the 'User Attribute Name'
155 For instance, if a user is represented via the
156 following ldif dataset:
159 # user1 of People at ldap-test.com
160 dn: uid=user1,ou=People,dc=ldap-test,dc=com
163 objectClass: organizationalPerson
164 objectClass: inetOrgPerson
168 description: This is the first test user.
171 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
172 attribute would be `uid`.
174 If {pve} needs to authenticate (bind) to the LDAP server before being
175 able to query and authenticate users, a bind domain name can be
176 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
177 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
178 (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
179 single line containing the raw password.
181 To verify certificates, you need to to set `capath`. You can set it either
182 directly to the CA certificate of your LDAP server, or to the system path
183 containing all trusted CA certificates (`/etc/ssl/certs`).
184 Additionally, you need to set the `verify` option, which can also be done over
187 Microsoft Active Directory::
189 A server and authentication domain need to be specified. Like with LDAP, an
190 optional fallback server, port, and SSL encryption can be configured.
193 Syncing LDAP-based realms
194 ~~~~~~~~~~~~~~~~~~~~~~~~~
196 [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
198 It is possible to sync users and groups for LDAP based realms. You can use the
202 pveum realm sync <realm>
204 or in the `Authentication` panel of the GUI. Users and groups are synced to the
205 cluster-wide user configuration file `/etc/pve/user.cfg`.
207 Requirements and limitations
208 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
210 The `bind_dn` is used to query the users and groups. This account needs access
211 to all desired entries.
213 The fields which represent the names of the users and groups can be configured
214 via the `user_attr` and `group_name_attr` respectively. Only entries which
215 adhere to the usual character limitations of the user.cfg are synced.
217 Groups are synced with `-$realm` attached to the name, to avoid naming
218 conflicts. Please make sure that a sync does not overwrite manually created
221 [[pveum_ldap_sync_options]]
225 [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
227 The main options for syncing are:
229 * `dry-run`: No data is written to the config. This is useful if you want to
230 see which users and groups would get synced to the user.cfg. This is set
231 when you click `Preview` in the GUI.
233 * `enable-new`: If set, the newly synced users are enabled and can login.
234 The default is `true`.
236 * `full`: If set, the sync uses the LDAP Directory as a source of truth,
237 overwriting information set manually in the user.cfg and deletes users
238 and groups which are not present in the LDAP directory. If not set,
239 only new data is written to the config, and no stale users are deleted.
241 * `purge`: If set, sync removes all corresponding ACLs when removing users
242 and groups. This is only useful with the option `full`.
244 * `scope`: The scope of what to sync. It can be either `users`, `groups` or
247 These options are either set as parameters or as defaults, via the
248 realm option `sync-defaults-options`.
251 Two-factor authentication
252 -------------------------
254 There are two ways to use two-factor authentication:
256 It can be required by the authentication realm, either via 'TOTP'
257 (Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly
258 created user needs their keys added immediately as there is no way to
259 log in without the second factor. In the case of 'TOTP', users can
260 also change the 'TOTP' later on, provided they can log in first.
262 Alternatively, users can choose to opt in to two-factor authentication
263 via 'TOTP' later on, even if the realm does not enforce it. As another
264 option, if the server has an 'AppId' configured, a user can opt into
265 'U2F' authentication, provided the realm does not enforce any other
268 Realm enforced two-factor authentication
269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271 This can be done by selecting one of the available methods via the
272 'TFA' dropdown box when adding or editing an Authentication Realm.
273 When a realm has TFA enabled it becomes a requirement and only users
274 with configured TFA will be able to login.
276 Currently there are two methods available:
278 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm
279 where the current time is hashed with the user's configured key. The
280 time step and password length parameters are configured.
282 A user can have multiple keys configured (separated by spaces), and the keys
283 can be specified in Base32 (RFC3548) or hexadecimal notation.
285 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
286 key in Base32 notation which can be used directly with various OTP tools, such
287 as the `oathtool` command line tool, or on Android Google Authenticator,
288 FreeOTP, andOTP or similar applications.
291 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
292 server URL must be configured, and users must have a YubiKey available. In
293 order to get the key ID from a YubiKey, you can trigger the YubiKey once
294 after connecting it to USB and copy the first 12 characters of the typed
295 password into the user's 'Key IDs' field.
298 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
299 documentation for how to use the
300 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
301 https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host
302 your own verification server].
304 [[pveum_user_configured_totp]]
305 User configured TOTP authentication
306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
308 Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
309 button in the user list (unless the realm enforces 'YubiKey OTP').
311 [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
313 After opening the 'TFA' window, the user is presented with a dialog to setup
314 'TOTP' authentication. The 'Secret' field contains the key, which can simply be
315 generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
316 added to provide information to the 'TOTP' app what the key belongs to.
317 Most 'TOTP' apps will show the issuer name together with the corresponding
318 'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
320 After generating a key, a QR code will be displayed which can be used with most
321 OTP apps such as FreeOTP. Now the user needs to verify both the current user
322 password (unless logged in as 'root'), as well as the ability to correctly use
323 the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
324 field before pressing the 'Apply' button.
326 [[pveum_configure_u2f]]
327 Server side U2F configuration
328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330 To allow users to use 'U2F' authentication, the server needs to have a valid
331 domain with a valid https certificate. Initially an 'AppId'
332 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
333 needs to be configured.
335 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
338 This is done via `/etc/pve/datacenter.cfg`, for instance:
341 u2f: appid=https://mypve.example.com:8006
344 For a single node, the 'AppId' can simply be the web UI address exactly as it
345 is used in the browser, including the 'https://' and the port as shown above.
346 Please note that some browsers may be more strict than others when matching
349 When using multiple nodes, it is best to have a separate `https` server
350 providing an `appid.json`
351 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
352 file, as it seems to be compatible with most
353 browsers. If all nodes use subdomains of the same top level domain, it may be
354 enough to use the TLD as 'AppId', but note that some browsers may not accept
357 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
358 situation where this does not happen, particularly when using a top level domain
359 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
360 recommended to test the configuration with multiple browsers, as changing the
361 'AppId' later will render existing 'U2F' registrations unusable.
363 [[pveum_user_configured_u2f]]
364 Activating U2F as a user
365 ~~~~~~~~~~~~~~~~~~~~~~~~
367 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
368 current password (unless logged in as root), and press the 'Register' button.
369 If the server is setup correctly and the browser accepted the server's provided
370 'AppId', a message will appear prompting the user to press the button on the
371 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
372 on steadily around twice per second).
374 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
375 before they can use a 'U2F' token.
377 [[pveum_permission_management]]
378 Permission Management
379 ---------------------
381 In order for a user to perform an action (such as listing, modifying or
382 deleting a parts of a VM configuration), the user needs to have the
383 appropriate permissions.
385 {pve} uses a role and path based permission management system. An entry in
386 the permissions table allows a user, group or token to take on a specific role
387 when accessing an 'object' or 'path'. This means an such an access rule can
388 be represented as a triple of '(path, user, role)', '(path, group,
389 role)' or '(path, token, role)', with the role containing a set of allowed
390 actions, and the path representing the target of these actions.
397 A role is simply a list of privileges. Proxmox VE comes with a number
398 of predefined roles which satisfies most needs.
400 * `Administrator`: has all privileges
401 * `NoAccess`: has no privileges (used to forbid access)
402 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
403 * `PVEAuditor`: read only access
404 * `PVEDatastoreAdmin`: create and allocate backup space and templates
405 * `PVEDatastoreUser`: allocate backup space and view storage
406 * `PVEPoolAdmin`: allocate pools
407 * `PVESysAdmin`: User ACLs, audit, system console and system logs
408 * `PVETemplateUser`: view and clone templates
409 * `PVEUserAdmin`: user administration
410 * `PVEVMAdmin`: fully administer VMs
411 * `PVEVMUser`: view, backup, config CD-ROM, VM console, VM power management
413 You can see the whole set of predefined roles on the GUI.
415 Adding new roles can be done via both GUI and the command line.
417 [thumbnail="screenshot/gui-datacenter-role-add.png"]
418 For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and
419 click on the 'Create' button, there you can set a name and select all desired
420 roles from the 'Privileges' dropdown box.
422 To add a role through the command line you can use the 'pveum' CLI tool, like
426 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
427 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
434 A privilege is the right to perform a specific action. To simplify
435 management, lists of privileges are grouped into roles, which can then
436 be used in the permission table. Note that privileges cannot directly be
437 assigned to users and paths without being part of a role.
439 We currently use the following privileges:
441 Node / System related privileges::
443 * `Permissions.Modify`: modify access permissions
444 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
445 * `Sys.Console`: console access to Node
446 * `Sys.Syslog`: view Syslog
447 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
448 * `Sys.Modify`: create/remove/modify node network parameters
449 * `Group.Allocate`: create/remove/modify groups
450 * `Pool.Allocate`: create/remove/modify a pool
451 * `Realm.Allocate`: create/remove/modify authentication realms
452 * `Realm.AllocateUser`: assign user to a realm
453 * `User.Modify`: create/remove/modify user access and details.
455 Virtual machine related privileges::
457 * `VM.Allocate`: create/remove new VM to server inventory
458 * `VM.Migrate`: migrate VM to alternate server on cluster
459 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
460 * `VM.Console`: console access to VM
461 * `VM.Monitor`: access to VM monitor (kvm)
462 * `VM.Backup`: backup/restore VMs
463 * `VM.Audit`: view VM config
464 * `VM.Clone`: clone/copy a VM
465 * `VM.Config.Disk`: add/modify/delete Disks
466 * `VM.Config.CDROM`: eject/change CD-ROM
467 * `VM.Config.CPU`: modify CPU settings
468 * `VM.Config.Memory`: modify Memory settings
469 * `VM.Config.Network`: add/modify/delete Network devices
470 * `VM.Config.HWType`: modify emulated HW type
471 * `VM.Config.Options`: modify any other VM configuration
472 * `VM.Snapshot`: create/remove VM snapshots
474 Storage related privileges::
476 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
477 * `Datastore.AllocateSpace`: allocate space on a datastore
478 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
479 * `Datastore.Audit`: view/browse a datastore
485 Access permissions are assigned to objects, such as a virtual machines,
486 storages or pools of resources.
487 We use file system like paths to address these objects. These paths form a
488 natural tree, and permissions of higher levels (shorter path) can
489 optionally be propagated down within this hierarchy.
491 [[pveum_templated_paths]]
492 Paths can be templated. When an API call requires permissions on a
493 templated path, the path may contain references to parameters of the API
494 call. These references are specified in curly braces. Some parameters are
495 implicitly taken from the API call's URI. For instance the permission path
496 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
497 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
498 refers to the method's `path` parameter.
502 * `/nodes/{node}`: Access to {pve} server machines
503 * `/vms`: Covers all VMs
504 * `/vms/{vmid}`: Access to specific VMs
505 * `/storage/{storeid}`: Access to a storages
506 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
507 * `/access/groups`: Group administration
508 * `/access/realms/{realmid}`: Administrative access to realms
514 As mentioned earlier, object paths form a file system like tree, and
515 permissions can be inherited down that tree (the propagate flag is set
516 by default). We use the following inheritance rules:
518 * Permissions for individual users always replace group permissions.
519 * Permissions for groups apply when the user is member of that group.
520 * Permissions replace the ones inherited from an upper level.
522 Additionally, privilege separated tokens can never have a permission on any
523 given path that their associated user does not have.
529 Pools can be used to group a set of virtual machines and data
530 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
531 which are inherited to all pool members. This is a great way simplify
535 What permission do I need?
536 ~~~~~~~~~~~~~~~~~~~~~~~~~~
538 The required API permissions are documented for each individual
539 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
541 The permissions are specified as a list which can be interpreted as a
542 tree of logic and access-check functions:
544 `["and", <subtests>...]` and `["or", <subtests>...]`::
545 Each(`and`) or any(`or`) further element in the current list has to be true.
547 `["perm", <path>, [ <privileges>... ], <options>...]`::
548 The `path` is a templated parameter (see
549 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
550 option is used, any) of the listed
551 privileges must be allowed on the specified path. If a `require-param`
552 option is specified, then its specified parameter is required even if the
553 API call's schema otherwise lists it as being optional.
555 `["userid-group", [ <privileges>... ], <options>...]`::
556 The caller must have any of the listed privileges on `/access/groups`. In
557 addition there are two possible checks depending on whether the
558 `groups_param` option is set:
560 * `groups_param` is set: The API call has a non-optional `groups` parameter
561 and the caller must have any of the listed privileges on all of the listed
563 * `groups_param` is not set: The user passed via the `userid` parameter
564 must exist and be part of a group on which the caller has any of the listed
565 privileges (via the `/access/groups/<group>` path).
567 `["userid-param", "self"]`::
568 The value provided for the API call's `userid` parameter must refer to the
569 user performing the action. (Usually in conjunction with `or`, to allow
570 users to perform an action on themselves even if they don't have elevated
573 `["userid-param", "Realm.AllocateUser"]`::
574 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
575 `<realm>` referring to the realm of the user passed via the `userid`
576 parameter. Note that the user does not need to exist in order to be
577 associated with a realm, since user IDs are passed in the form of
578 `<username>@<realm>`.
580 `["perm-modify", <path>]`::
581 The `path` is a templated parameter (see
582 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
583 `Permissions.Modify` privilege, or,
584 depending on the path, the following privileges as a possible substitute:
586 * `/storage/...`: additionally requires 'Datastore.Allocate`
587 * `/vms/...`: additionally requires 'VM.Allocate`
588 * `/pool/...`: additionally requires 'Pool.Allocate`
590 If the path is empty, `Permission.Modify` on `/access` is required.
595 Most users will simply use the GUI to manage users. But there is also
596 a fully featured command line tool called `pveum` (short for ``**P**roxmox
597 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
598 line tools are wrappers around the API, so you can also access those
599 functions through the REST API.
601 Here are some simple usage examples. To show help type:
606 or (to show detailed help about a specific command)
614 pveum user add testuser@pve -comment "Just a test"
616 Set or Change the password (not all realms support that):
619 pveum passwd testuser@pve
624 pveum user modify testuser@pve -enable 0
629 pveum group add testgroup
634 pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
644 One of the most wanted features was the ability to define a group of
645 users with full administrator rights (without using the root account).
650 pveum group add admin -comment "System Administrators"
652 Then add the permission:
655 pveum acl modify / -group admin -role Administrator
657 You can finally add users to the new 'admin' group:
660 pveum user modify testuser@pve -group admin
666 You can give read only access to users by assigning the `PVEAuditor`
667 role to users or groups.
669 Example1: Allow user `joe@pve` to see everything
672 pveum acl modify / -user joe@pve -role PVEAuditor
674 Example1: Allow user `joe@pve` to see all virtual machines
677 pveum acl modify /vms -user joe@pve -role PVEAuditor
680 Delegate User Management
681 ~~~~~~~~~~~~~~~~~~~~~~~~
683 If you want to delegate user management to user `joe@pve` you can do
687 pveum acl modify /access -user joe@pve -role PVEUserAdmin
689 User `joe@pve` can now add and remove users, change passwords and
690 other user attributes. This is a very powerful role, and you most
691 likely want to limit that to selected realms and groups. The following
692 example allows `joe@pve` to modify users within realm `pve` if they
693 are members of group `customers`:
696 pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
697 pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
699 NOTE: The user is able to add other users, but only if they are
700 members of group `customers` and within realm `pve`.
702 Limited API token for monitoring
703 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
705 Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
708 pveum acl modify /vms -user joe@pve -role PVEVMAdmin
710 Add a new API token with separate privileges, which is only allowed to view VM
711 information (e.g., for monitoring purposes):
714 pveum user token add joe@pve monitoring -privsep 1
715 pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
717 Verify the permissions of the user and token:
720 pveum user permissions joe@pve
721 pveum user token permissions joe@pve monitoring
726 An enterprise is usually structured into several smaller departments, and it is
727 common that you want to assign resources and delegate management tasks to each
728 of these. Let's assume that you want to set up a pool for a software development
729 department. First, create a group
732 pveum group add developers -comment "Our software developers"
734 Now we create a new user which is a member of that group
737 pveum user add developer1@pve -group developers -password
739 NOTE: The -password parameter will prompt you for a password
741 Then we create a resource pool for our development department to use
744 pveum pool add dev-pool --comment "IT development pool"
746 Finally, we can assign permissions to that pool
749 pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
751 Our software developers can now administrate the resources assigned to
756 include::pve-copyright.adoc[]