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 Microsoft Active Directory::
169 A server and authentication domain need to be specified. Like with
170 ldap an optional fallback server, optional port, and SSL
171 encryption can be configured.
174 Syncing LDAP-based realms
175 ~~~~~~~~~~~~~~~~~~~~~~~~~
177 It is possible to sync users and groups for LDAP based realms. You can use the
183 or in the `Authentication` panel of the GUI. Users and groups are synced to the
184 cluster-wide user configuration file `/etc/pve/user.cfg`.
186 Requirements and limitations
187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189 The `bind_dn` is used to query the users and groups. This account needs access
190 to all desired entries.
192 The fields which represent the names of the users and groups can be configured
193 via the `user_attr` and `group_name_attr` respectively. Only entries which
194 adhere to the usual character limitations of the user.cfg are synced.
196 Groups are synced with `-$realm` attached to the name, to avoid naming
197 conflicts. Please make sure that a sync does not overwrite manually created
200 [[pveum_ldap_sync_options]]
204 The main options for syncing are:
206 * `dry-run`: No data is written to the config. This is useful if you want to
207 see which users and groups would get synced to the user.cfg. This is set
208 when you click `Preview` in the GUI.
210 * `enable-new`: If set, the newly synced users are enabled and can login.
211 The default is `true`.
213 * `full`: If set, the sync uses the LDAP Directory as a source of truth,
214 overwriting information set manually in the user.cfg and deletes users
215 and groups which are not present in the LDAP directory. If not set,
216 only new data is written to the config, and no stale users are deleted.
218 * `purge`: If set, sync removes all corresponding ACLs when removing users
219 and groups. This is only useful with the option `full`.
221 * `scope`: The scope of what to sync. It can be either `users`, `groups` or
224 These options are either set as parameters or as defaults, via the
225 realm option `sync-defaults-options`.
228 Two-factor authentication
229 -------------------------
231 There are two ways to use two-factor authentication:
233 It can be required by the authentication realm, either via 'TOTP'
234 (Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly
235 created user needs their keys added immediately as there is no way to
236 log in without the second factor. In the case of 'TOTP', users can
237 also change the 'TOTP' later on, provided they can log in first.
239 Alternatively, users can choose to opt in to two-factor authentication
240 via 'TOTP' later on, even if the realm does not enforce it. As another
241 option, if the server has an 'AppId' configured, a user can opt into
242 'U2F' authentication, provided the realm does not enforce any other
245 Realm enforced two-factor authentication
246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248 This can be done by selecting one of the available methods via the
249 'TFA' dropdown box when adding or editing an Authentication Realm.
250 When a realm has TFA enabled it becomes a requirement and only users
251 with configured TFA will be able to login.
253 Currently there are two methods available:
255 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm
256 where the current time is hashed with the user's configured key. The
257 time step and password length parameters are configured.
259 A user can have multiple keys configured (separated by spaces), and the keys
260 can be specified in Base32 (RFC3548) or hexadecimal notation.
262 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
263 key in Base32 notation which can be used directly with various OTP tools, such
264 as the `oathtool` command line tool, or on Android Google Authenticator,
265 FreeOTP, andOTP or similar applications.
268 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
269 server URL must be configured, and users must have a YubiKey available. In
270 order to get the key ID from a YubiKey, you can trigger the YubiKey once
271 after connecting it to USB and copy the first 12 characters of the typed
272 password into the user's 'Key IDs' field.
275 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
276 documentation for how to use the
277 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
278 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[host
279 your own verification server].
281 [[pveum_user_configured_totp]]
282 User configured TOTP authentication
283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
286 button in the user list (unless the realm enforces 'YubiKey OTP').
288 [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
290 After opening the 'TFA' window, the user is presented with a dialog to setup
291 'TOTP' authentication. The 'Secret' field contains the key, which can simply be
292 generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
293 added to provide information to the 'TOTP' app what the key belongs to.
294 Most 'TOTP' apps will show the issuer name together with the corresponding
295 'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
297 After generating a key, a QR code will be displayed which can be used with most
298 OTP apps such as FreeOTP. Now the user needs to verify both the current user
299 password (unless logged in as 'root'), as well as the ability to correctly use
300 the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
301 field before pressing the 'Apply' button.
303 [[pveum_configure_u2f]]
304 Server side U2F configuration
305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
307 To allow users to use 'U2F' authentication, the server needs to have a valid
308 domain with a valid https certificate. Initially an 'AppId'
309 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
310 needs to be configured.
312 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
315 This is done via `/etc/pve/datacenter.cfg`, for instance:
318 u2f: appid=https://mypve.example.com:8006
321 For a single node, the 'AppId' can simply be the web UI address exactly as it
322 is used in the browser, including the 'https://' and the port as shown above.
323 Please note that some browsers may be more strict than others when matching
326 When using multiple nodes, it is best to have a separate `https` server
327 providing an `appid.json`
328 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
329 file, as it seems to be compatible with most
330 browsers. If all nodes use subdomains of the same top level domain, it may be
331 enough to use the TLD as 'AppId', but note that some browsers may not accept
334 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
335 situation where this does not happen, particularly when using a top level domain
336 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
337 recommended to test the configuration with multiple browsers, as changing the
338 'AppId' later will render existing 'U2F' registrations unusable.
340 [[pveum_user_configured_u2f]]
341 Activating U2F as a user
342 ~~~~~~~~~~~~~~~~~~~~~~~~
344 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
345 current password (unless logged in as root), and press the 'Register' button.
346 If the server is setup correctly and the browser accepted the server's provided
347 'AppId', a message will appear prompting the user to press the button on the
348 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
349 on steadily around twice per second).
351 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
352 before they can use a 'U2F' token.
354 [[pveum_permission_management]]
355 Permission Management
356 ---------------------
358 In order for a user to perform an action (such as listing, modifying or
359 deleting a parts of a VM configuration), the user needs to have the
360 appropriate permissions.
362 {pve} uses a role and path based permission management system. An entry in
363 the permissions table allows a user, group or token to take on a specific role
364 when accessing an 'object' or 'path'. This means an such an access rule can
365 be represented as a triple of '(path, user, role)', '(path, group,
366 role)' or '(path, token, role)', with the role containing a set of allowed
367 actions, and the path representing the target of these actions.
374 A role is simply a list of privileges. Proxmox VE comes with a number
375 of predefined roles which satisfies most needs.
377 * `Administrator`: has all privileges
378 * `NoAccess`: has no privileges (used to forbid access)
379 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
380 * `PVEAuditor`: read only access
381 * `PVEDatastoreAdmin`: create and allocate backup space and templates
382 * `PVEDatastoreUser`: allocate backup space and view storage
383 * `PVEPoolAdmin`: allocate pools
384 * `PVESysAdmin`: User ACLs, audit, system console and system logs
385 * `PVETemplateUser`: view and clone templates
386 * `PVEUserAdmin`: user administration
387 * `PVEVMAdmin`: fully administer VMs
388 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
390 You can see the whole set of predefined roles on the GUI.
392 Adding new roles can be done via both GUI and the command line.
394 [thumbnail="screenshot/gui-datacenter-role-add.png"]
395 For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and
396 click on the 'Create' button, there you can set a name and select all desired
397 roles from the 'Privileges' dropdown box.
399 To add a role through the command line you can use the 'pveum' CLI tool, like
403 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
404 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
411 A privilege is the right to perform a specific action. To simplify
412 management, lists of privileges are grouped into roles, which can then
413 be used in the permission table. Note that privileges cannot directly be
414 assigned to users and paths without being part of a role.
416 We currently use the following privileges:
418 Node / System related privileges::
420 * `Permissions.Modify`: modify access permissions
421 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
422 * `Sys.Console`: console access to Node
423 * `Sys.Syslog`: view Syslog
424 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
425 * `Sys.Modify`: create/remove/modify node network parameters
426 * `Group.Allocate`: create/remove/modify groups
427 * `Pool.Allocate`: create/remove/modify a pool
428 * `Realm.Allocate`: create/remove/modify authentication realms
429 * `Realm.AllocateUser`: assign user to a realm
430 * `User.Modify`: create/remove/modify user access and details.
432 Virtual machine related privileges::
434 * `VM.Allocate`: create/remove new VM to server inventory
435 * `VM.Migrate`: migrate VM to alternate server on cluster
436 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
437 * `VM.Console`: console access to VM
438 * `VM.Monitor`: access to VM monitor (kvm)
439 * `VM.Backup`: backup/restore VMs
440 * `VM.Audit`: view VM config
441 * `VM.Clone`: clone/copy a VM
442 * `VM.Config.Disk`: add/modify/delete Disks
443 * `VM.Config.CDROM`: eject/change CDROM
444 * `VM.Config.CPU`: modify CPU settings
445 * `VM.Config.Memory`: modify Memory settings
446 * `VM.Config.Network`: add/modify/delete Network devices
447 * `VM.Config.HWType`: modify emulated HW type
448 * `VM.Config.Options`: modify any other VM configuration
449 * `VM.Snapshot`: create/remove VM snapshots
451 Storage related privileges::
453 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
454 * `Datastore.AllocateSpace`: allocate space on a datastore
455 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
456 * `Datastore.Audit`: view/browse a datastore
462 Access permissions are assigned to objects, such as a virtual machines,
463 storages or pools of resources.
464 We use file system like paths to address these objects. These paths form a
465 natural tree, and permissions of higher levels (shorter path) can
466 optionally be propagated down within this hierarchy.
468 [[pveum_templated_paths]]
469 Paths can be templated. When an API call requires permissions on a
470 templated path, the path may contain references to parameters of the API
471 call. These references are specified in curly braces. Some parameters are
472 implicitly taken from the API call's URI. For instance the permission path
473 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
474 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
475 refers to the method's `path` parameter.
479 * `/nodes/{node}`: Access to {pve} server machines
480 * `/vms`: Covers all VMs
481 * `/vms/{vmid}`: Access to specific VMs
482 * `/storage/{storeid}`: Access to a storages
483 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
484 * `/access/groups`: Group administration
485 * `/access/realms/{realmid}`: Administrative access to realms
491 As mentioned earlier, object paths form a file system like tree, and
492 permissions can be inherited down that tree (the propagate flag is set
493 by default). We use the following inheritance rules:
495 * Permissions for individual users always replace group permissions.
496 * Permissions for groups apply when the user is member of that group.
497 * Permissions replace the ones inherited from an upper level.
499 Additionally, privilege separated tokens can never have a permission on any
500 given path that their associated user does not have.
506 Pools can be used to group a set of virtual machines and data
507 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
508 which are inherited to all pool members. This is a great way simplify
512 What permission do I need?
513 ~~~~~~~~~~~~~~~~~~~~~~~~~~
515 The required API permissions are documented for each individual
516 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
518 The permissions are specified as a list which can be interpreted as a
519 tree of logic and access-check functions:
521 `["and", <subtests>...]` and `["or", <subtests>...]`::
522 Each(`and`) or any(`or`) further element in the current list has to be true.
524 `["perm", <path>, [ <privileges>... ], <options>...]`::
525 The `path` is a templated parameter (see
526 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
527 option is used, any) of the listed
528 privileges must be allowed on the specified path. If a `require-param`
529 option is specified, then its specified parameter is required even if the
530 API call's schema otherwise lists it as being optional.
532 `["userid-group", [ <privileges>... ], <options>...]`::
533 The caller must have any of the listed privileges on `/access/groups`. In
534 addition there are two possible checks depending on whether the
535 `groups_param` option is set:
537 * `groups_param` is set: The API call has a non-optional `groups` parameter
538 and the caller must have any of the listed privileges on all of the listed
540 * `groups_param` is not set: The user passed via the `userid` parameter
541 must exist and be part of a group on which the caller has any of the listed
542 privileges (via the `/access/groups/<group>` path).
544 `["userid-param", "self"]`::
545 The value provided for the API call's `userid` parameter must refer to the
546 user performing the action. (Usually in conjunction with `or`, to allow
547 users to perform an action on themselves even if they don't have elevated
550 `["userid-param", "Realm.AllocateUser"]`::
551 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
552 `<realm>` referring to the realm of the user passed via the `userid`
553 parameter. Note that the user does not need to exist in order to be
554 associated with a realm, since user IDs are passed in the form of
555 `<username>@<realm>`.
557 `["perm-modify", <path>]`::
558 The `path` is a templated parameter (see
559 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
560 `Permissions.Modify` privilege, or,
561 depending on the path, the following privileges as a possible substitute:
563 * `/storage/...`: additionally requires 'Datastore.Allocate`
564 * `/vms/...`: additionally requires 'VM.Allocate`
565 * `/pool/...`: additionally requires 'Pool.Allocate`
567 If the path is empty, `Permission.Modify` on `/access` is required.
572 Most users will simply use the GUI to manage users. But there is also
573 a fully featured command line tool called `pveum` (short for ``**P**roxmox
574 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
575 line tools are wrappers around the API, so you can also access those
576 functions through the REST API.
578 Here are some simple usage examples. To show help type:
583 or (to show detailed help about a specific command)
591 pveum useradd testuser@pve -comment "Just a test"
593 Set or Change the password (not all realms support that):
596 pveum passwd testuser@pve
601 pveum usermod testuser@pve -enable 0
606 pveum groupadd testgroup
611 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
621 One of the most wanted features was the ability to define a group of
622 users with full administrator rights (without using the root account).
627 pveum groupadd admin -comment "System Administrators"
629 Then add the permission:
632 pveum aclmod / -group admin -role Administrator
634 You can finally add users to the new 'admin' group:
637 pveum usermod testuser@pve -group admin
643 You can give read only access to users by assigning the `PVEAuditor`
644 role to users or groups.
646 Example1: Allow user `joe@pve` to see everything
649 pveum aclmod / -user joe@pve -role PVEAuditor
651 Example1: Allow user `joe@pve` to see all virtual machines
654 pveum aclmod /vms -user joe@pve -role PVEAuditor
657 Delegate User Management
658 ~~~~~~~~~~~~~~~~~~~~~~~~
660 If you want to delegate user management to user `joe@pve` you can do
664 pveum aclmod /access -user joe@pve -role PVEUserAdmin
666 User `joe@pve` can now add and remove users, change passwords and
667 other user attributes. This is a very powerful role, and you most
668 likely want to limit that to selected realms and groups. The following
669 example allows `joe@pve` to modify users within realm `pve` if they
670 are members of group `customers`:
673 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
674 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
676 NOTE: The user is able to add other users, but only if they are
677 members of group `customers` and within realm `pve`.
679 Limited API token for monitoring
680 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
682 Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
685 pveum aclmod /vms -user joe@pve -role PVEVMAdmin
687 Add a new API token with separate privileges, which is only allowed to view VM
688 information (e.g., for monitoring purposes):
691 pveum user token add joe@pve monitoring -privsep 1
692 pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor
694 Verify the permissions of the user and token:
697 pveum user permissions joe@pve
698 pveum user token permissions joe@pve monitoring
703 An enterprise is usually structured into several smaller departments,
704 and it is common that you want to assign resources to them and
705 delegate management tasks. A pool is simply a set of virtual machines
706 and data stores. You can create pools on the GUI. After that you can
707 add resources to the pool (VMs, Storage).
709 You can also assign permissions to the pool. Those permissions are
710 inherited to all pool members.
712 Lets assume you have a software development department, so we first
716 pveum groupadd developers -comment "Our software developers"
718 Now we create a new user which is a member of that group
721 pveum useradd developer1@pve -group developers -password
723 NOTE: The -password parameter will prompt you for a password
725 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
728 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
730 Our software developers can now administrate the resources assigned to
735 include::pve-copyright.adoc[]