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