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