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 {pve} supports multiple authentication sources, for example Linux PAM,
31 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
32 Directory and OpenID Connect.
34 By using role-based user and permission management for all objects (VMs,
35 Storage, 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 the
44 <<pveum_authentication_realms,authentication realms>> described below.
45 Therefore, a user is often internally identified by their username 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
59 CAUTION: When you disable or delete a user, or if the expiry date set is
60 in the past, this user will not be able to log in to new sessions or start new
61 tasks. All tasks which have already been started by this user (for example,
62 terminal sessions) will **not** be terminated automatically by any such event.
68 The system's root user can always log in via the Linux PAM realm and is an
69 unconfined administrator. This user cannot be deleted, but attributes can
70 still be changed. System mails will be sent to the email address
71 assigned to this user.
78 Each user can be a member of several groups. Groups are the preferred
79 way to organize access permissions. You should always grant permissions
80 to groups instead of individual users. That way you will get a
81 much more maintainable access control list.
87 API tokens allow stateless access to most parts of the REST API from another
88 system, software or API client. Tokens can be generated for individual users
89 and can be given separate permissions and expiration dates to limit the scope
90 and duration of the access. Should the API token get compromised, it can be
91 revoked without disabling the user itself.
93 API tokens come in two basic types:
95 * Separated privileges: The token needs to be given explicit access with ACLs.
96 Its effective permissions are calculated by intersecting user and token
98 * Full privileges: The token's permissions are identical to that of the
101 CAUTION: The token value is only displayed/returned once when the token is
102 generated. It cannot be retrieved again over the API at a later time!
104 To use an API token, set the HTTP header 'Authorization' to the displayed value
105 of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
106 refer to your API client's documentation.
108 [[pveum_resource_pools]]
112 [thumbnail="screenshot/gui-datacenter-pool-window.png"]
114 A resource pool is a set of virtual machines, containers, and storage
115 devices. It is useful for permission handling in cases where certain users
116 should have controlled access to a specific set of resources, as it allows for a
117 single permission to be applied to a set of elements, rather than having to
118 manage this on a per-resource basis. Resource pools are often used in tandem
119 with groups, so that the members of a group have permissions on a set of
120 machines and storage.
122 [[pveum_authentication_realms]]
123 Authentication Realms
124 ---------------------
126 As {pve} users are just counterparts for users existing on some external
127 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
128 The following realms (authentication methods) are available:
130 Linux PAM standard authentication::
131 In this case, a system user must exist (for example, created via the `adduser`
132 command) on each node which the user is allowed to log in, and the user
133 authenticates with their usual system password.
140 usermod -a -G watchman heinz
143 Proxmox VE authentication server::
144 This is a Unix-like password store (`/etc/pve/priv/shadow.cfg`).
145 Passwords are encrypted using the SHA-256 hashing algorithm.
146 This is the most convenient method for small-scale (or even mid-scale)
147 installations, where users do not need access to anything outside of
148 {pve}. In this case, users are fully managed by {pve} and are able to
149 change their own passwords via the GUI.
152 It is possible to authenticate users via an LDAP server (for example,
153 openldap). A server and optional fallback server can be
154 configured, and the connection can be encrypted via SSL.
156 Users are searched under a 'Base Domain Name' (`base_dn`), with the
157 username found in the attribute specified in the 'User Attribute Name'
160 For instance, if a user is represented via the
161 following LDIF dataset:
164 # user1 of People at ldap-test.com
165 dn: uid=user1,ou=People,dc=ldap-test,dc=com
168 objectClass: organizationalPerson
169 objectClass: inetOrgPerson
173 description: This is the first test user.
176 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
177 attribute would be `uid`.
179 If {pve} needs to authenticate (bind) to the LDAP server before being
180 able to query and authenticate users, a bind domain name can be
181 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
182 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
183 (for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
184 single line with the raw password.
186 To verify certificates, you need to set `capath`. You can set it either
187 directly to the CA certificate of your LDAP server, or to the system path
188 containing all trusted CA certificates (`/etc/ssl/certs`).
189 Additionally, you need to set the `verify` option, which can also be done over
192 NOTE: In order to allow a particular user to authenticate using the LDAP server,
193 you must also add them as a user of that realm from the {pve} server.
195 A server and authentication domain need to be specified. Like with LDAP, an
196 optional fallback server, port, and SSL encryption can be configured.
200 OpenID Connect allows clients to verify the identity of the user, based on
201 authentication performed by an external authorization server.
208 The main OpenID Connect configuration options are:
210 * `issuer-url`: This is the URL to the authorization server. Proxmox
211 uses the OpenID Connect Discovery protocol to automatically configure
214 While it is possible to use unencrypted `http://` URLs, we strongly recommend to
215 use encrypted `https://` connections.
217 * `client-id`: OpenID Client ID.
219 * `client-key`: Optional OpenID Client Key.
221 * `autocreate`: Automatically create users if they do not exist. While
222 authentication is done at the OpenID server, all users still need an
223 entry in the {pve} user configuration. You can either add them
224 manually, or use the `autocreate` option to automatically add new
227 * `username-claim`: OpenID claim used to generate the unique username
228 (`subject`, `username` or `email`).
233 The OpenID Connect specification defines a single unique attribute
234 ('claim' in OpenID terms) named `subject`. By default, we use the
235 value of this attribute to generate {pve} usernames, by simple adding
236 `@` and the realm name: `${subject}@${realm}`.
238 Unfortunately, most OpenID servers use random strings for `subject`, like
239 `DGH76OKH34BNG3245SB`, so a typical username would look like
240 `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
241 humans to remember such random strings, making it quite impossible to
242 associate real users with this.
244 The `username-claim` setting allows you to use other attributes for
245 the username mapping. Setting it to `username` is preferred if the
246 OpenID Connect server provides that attribute and guarantees its
249 Another option is to use `email`, which also yields human readable
250 usernames. Again, only use this setting if the server guarantees the
251 uniqueness of this attribute.
256 Here is an example of creating an OpenID realm using Google. You need to
257 replace `--client-id` and `--client-key` with the values
258 from your Google OpenID settings.
261 pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
264 The above command uses `--username-claim email`, so that the usernames on the
265 {pve} side look like `example.user@google.com@myrealm1`.
267 Keycloak (https://www.keycloak.org/) is a popular open source Identity
268 and Access Management tool, which supports OpenID Connect. In the following
269 example, you need to replace the `--issuer-url` and `--client-id` with
273 pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username
276 Using `--username-claim username` enables simple usernames on the
277 {pve} side, like `example.user@myrealm2`.
279 WARNING: You need to ensure that the user is not allowed to edit
280 the username setting themselves (on the Keycloak server).
284 Syncing LDAP-based realms
285 ~~~~~~~~~~~~~~~~~~~~~~~~~
287 [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
289 It is possible to sync users and groups for LDAP-based realms. You can use the
290 following CLI command:
293 pveum realm sync <realm>
296 or the `Authentication` panel of the GUI. Users and groups are synced to the
297 cluster-wide user configuration file `/etc/pve/user.cfg`.
299 Requirements and limitations
300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
302 The `bind_dn` is used to query users and groups. This account needs access
303 to all desired entries.
305 The fields which represent the names of the users and groups can be configured
306 via the `user_attr` and `group_name_attr` respectively. Only entries which
307 adhere to the usual character limitations of the `user.cfg` are synced.
309 Groups are synced with `-$realm` attached to the name, in order to avoid naming
310 conflicts. Please ensure that a sync does not overwrite manually created
313 [[pveum_ldap_sync_options]]
317 [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
319 The main options for syncing are:
321 * `dry-run`: No data is written to the config. This is useful if you want to
322 see which users and groups would get synced to the `user.cfg`. This is set
323 when you click `Preview` in the GUI.
325 * `enable-new`: If set, the newly synced users are enabled and can log in.
326 The default is `true`.
328 * `full`: If set, the sync uses the LDAP directory as a source of truth,
329 overwriting information set manually in the `user.cfg` and deleting users
330 and groups which are not present in the LDAP directory. If not set,
331 only new data is written to the config, and no stale users are deleted.
333 * `purge`: If set, sync removes all corresponding ACLs when removing users
334 and groups. This is only useful with the option `full`.
336 * `scope`: The scope of what to sync. It can be either `users`, `groups` or
339 These options are either set as parameters or as defaults via the
340 realm option `sync-defaults-options`.
343 Two-Factor Authentication
344 -------------------------
346 There are two ways to use two-factor authentication:
348 It can be required by the authentication realm, either via 'TOTP'
349 (Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly
350 created user needs to have their keys added immediately, as there is no way to
351 log in without the second factor. In the case of 'TOTP', users can
352 also change the 'TOTP' later on, provided they can log in first.
354 Alternatively, users can choose to opt-in to two-factor authentication
355 via 'TOTP' later on, even if the realm does not enforce it. As another
356 option, if the server has an 'AppId' configured, a user can opt-in to
357 'U2F' authentication, provided the realm does not enforce any other
360 Realm Enforced Two-Factor Authentication
361 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363 This can be done by selecting one of the available methods via the
364 'TFA' dropdown box when adding or editing an Authentication Realm.
365 When a realm has TFA enabled, it becomes a requirement, and only users
366 with configured TFA will be able to log in.
368 Currently there are two methods available:
370 Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm,
371 where the current time is hashed with the user's configured key. The
372 time step and password length parameters are configurable.
374 A user can have multiple keys configured (separated by spaces), and the keys
375 can be specified in Base32 (RFC3548) or hexadecimal notation.
377 {pve} provides a key generation tool (`oathkeygen`) which prints out a random
378 key in Base32 notation, that can be used directly with various OTP tools, such
379 as the `oathtool` command line tool, or on Android Google Authenticator,
380 FreeOTP, andOTP or similar applications.
383 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
384 server URL must be configured, and users must have a YubiKey available. In
385 order to get the key ID from a YubiKey, you can trigger the YubiKey once
386 after connecting it via USB, and copy the first 12 characters of the typed
387 password into the user's 'Key IDs' field.
389 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
390 documentation for how to use the
391 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
392 https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server].
394 [[pveum_user_configured_totp]]
395 User Configured TOTP Authentication
396 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
398 Users can choose to enable 'TOTP' as a second factor on login, via the 'TFA'
399 button in the user list (unless the realm enforces 'YubiKey OTP').
401 [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
403 After opening the 'TFA' window, the user is presented with a dialog to set up
404 'TOTP' authentication. The 'Secret' field contains the key, which can be
405 randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
406 added to provide information to the 'TOTP' app about what the key belongs to.
407 Most 'TOTP' apps will show the issuer name together with the corresponding
408 'OTP' values. The username is also included in the QR code for the 'TOTP' app.
410 After generating a key, a QR code will be displayed, which can be used with most
411 OTP apps such as FreeOTP. The user then needs to verify the current user
412 password (unless logged in as 'root'), as well as the ability to correctly use
413 the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
414 field and pressing the 'Apply' button.
416 [[pveum_configure_u2f]]
417 Server Side U2F Configuration
418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
420 To allow users to use 'U2F' authentication, it may be necessary to use a valid
421 domain with a valid SSL certificate, otherwise, some browsers may print
422 a warning or reject U2F usage altogether. Initially, an 'AppId'
423 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
424 needs to be configured.
426 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
429 This is done via `/etc/pve/datacenter.cfg`. For instance:
432 u2f: appid=https://mypve.example.com:8006
435 For a single node, the 'AppId' can simply be the address of the web-interface,
436 exactly as it is used in the browser, including the 'https://' and the port, as
437 shown above. Please note that some browsers may be more strict than others when
440 When using multiple nodes, it is best to have a separate `https` server
441 providing an `appid.json`
442 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
443 file, as it seems to be compatible with most
444 browsers. If all nodes use subdomains of the same top level domain, it may be
445 enough to use the TLD as 'AppId'. It should however be noted that some browsers
448 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
449 situations when this does not happen, particularly when using a top level domain
450 'AppId' for a node that is accessed via a subdomain in Chromium. For this reason
451 it is recommended to test the configuration with multiple browsers, as changing
452 the 'AppId' later will render existing 'U2F' registrations unusable.
454 [[pveum_user_configured_u2f]]
455 Activating U2F as a User
456 ~~~~~~~~~~~~~~~~~~~~~~~~
458 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
459 current password (unless logged in as root), and press the 'Register' button.
460 If the server is set up correctly and the browser accepts the server's provided
461 'AppId', a message will appear prompting the user to press the button on the
462 'U2F' device (if it is a 'YubiKey', the button light should be toggling on and
463 off steadily, roughly twice per second).
465 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
466 before they can use a 'U2F' token.
468 [[pveum_permission_management]]
469 Permission Management
470 ---------------------
472 In order for a user to perform an action (such as listing, modifying or
473 deleting parts of a VM's configuration), the user needs to have the
474 appropriate permissions.
476 {pve} uses a role and path based permission management system. An entry in
477 the permissions table allows a user, group or token to take on a specific role
478 when accessing an 'object' or 'path'. This means that such an access rule can
479 be represented as a triple of '(path, user, role)', '(path, group,
480 role)' or '(path, token, role)', with the role containing a set of allowed
481 actions, and the path representing the target of these actions.
488 A role is simply a list of privileges. Proxmox VE comes with a number
489 of predefined roles, which satisfy most requirements.
491 * `Administrator`: has full privileges
492 * `NoAccess`: has no privileges (used to forbid access)
493 * `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`)
494 * `PVEAuditor`: has read only access
495 * `PVEDatastoreAdmin`: create and allocate backup space and templates
496 * `PVEDatastoreUser`: allocate backup space and view storage
497 * `PVEPoolAdmin`: allocate pools
498 * `PVESysAdmin`: User ACLs, audit, system console and system logs
499 * `PVETemplateUser`: view and clone templates
500 * `PVEUserAdmin`: manage users
501 * `PVEVMAdmin`: fully administer VMs
502 * `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management
504 You can see the whole set of predefined roles in the GUI.
506 You can add new roles via the GUI or the command line.
508 [thumbnail="screenshot/gui-datacenter-role-add.png"]
509 From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and
510 click on the 'Create' button. There you can set a role name and select any
511 desired privileges from the 'Privileges' drop-down menu.
513 To add a role through the command line, you can use the 'pveum' CLI tool, for
517 pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
518 pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
525 A privilege is the right to perform a specific action. To simplify
526 management, lists of privileges are grouped into roles, which can then
527 be used in the permission table. Note that privileges cannot be directly
528 assigned to users and paths without being part of a role.
530 We currently support the following privileges:
532 Node / System related privileges::
534 * `Permissions.Modify`: modify access permissions
535 * `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...)
536 * `Sys.Console`: console access to node
537 * `Sys.Syslog`: view syslog
538 * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
539 * `Sys.Modify`: create/modify/remove node network parameters
540 * `Group.Allocate`: create/modify/remove groups
541 * `Pool.Allocate`: create/modify/remove a pool
542 * `Pool.Audit`: view a pool
543 * `Realm.Allocate`: create/modify/remove authentication realms
544 * `Realm.AllocateUser`: assign user to a realm
545 * `User.Modify`: create/modify/remove user access and details.
547 Virtual machine related privileges::
549 * `VM.Allocate`: create/remove VM on a server
550 * `VM.Migrate`: migrate VM to alternate server on cluster
551 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
552 * `VM.Console`: console access to VM
553 * `VM.Monitor`: access to VM monitor (kvm)
554 * `VM.Backup`: backup/restore VMs
555 * `VM.Audit`: view VM config
556 * `VM.Clone`: clone/copy a VM
557 * `VM.Config.Disk`: add/modify/remove disks
558 * `VM.Config.CDROM`: eject/change CD-ROM
559 * `VM.Config.CPU`: modify CPU settings
560 * `VM.Config.Memory`: modify memory settings
561 * `VM.Config.Network`: add/modify/remove network devices
562 * `VM.Config.HWType`: modify emulated hardware types
563 * `VM.Config.Options`: modify any other VM configuration
564 * `VM.Snapshot`: create/delete VM snapshots
566 Storage related privileges::
568 * `Datastore.Allocate`: create/modify/remove a datastore and delete volumes
569 * `Datastore.AllocateSpace`: allocate space on a datastore
570 * `Datastore.AllocateTemplate`: allocate/upload templates and ISO images
571 * `Datastore.Audit`: view/browse a datastore
577 Access permissions are assigned to objects, such as virtual machines,
578 storages or resource pools.
579 We use file system like paths to address these objects. These paths form a
580 natural tree, and permissions of higher levels (shorter paths) can
581 optionally be propagated down within this hierarchy.
583 [[pveum_templated_paths]]
584 Paths can be templated. When an API call requires permissions on a
585 templated path, the path may contain references to parameters of the API
586 call. These references are specified in curly braces. Some parameters are
587 implicitly taken from the API call's URI. For instance, the permission path
588 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
589 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
590 refers to the method's `path` parameter.
594 * `/nodes/{node}`: Access to {pve} server machines
595 * `/vms`: Covers all VMs
596 * `/vms/{vmid}`: Access to specific VMs
597 * `/storage/{storeid}`: Access to a specific storage
598 * `/pool/{poolname}`: Access to resources contained in a specific <<pveum_pools,pool>>
599 * `/access/groups`: Group administration
600 * `/access/realms/{realmid}`: Administrative access to realms
606 As mentioned earlier, object paths form a file system like tree, and
607 permissions can be inherited by objects down that tree (the propagate flag is
608 set by default). We use the following inheritance rules:
610 * Permissions for individual users always replace group permissions.
611 * Permissions for groups apply when the user is member of that group.
612 * Permissions on deeper levels replace those inherited from an upper level.
614 Additionally, privilege separated tokens can never have permissions on any
615 given path that their associated user does not have.
621 Pools can be used to group a set of virtual machines and datastores. You can
622 then simply set permissions on pools (`/pool/{poolid}`), which are inherited by
623 all pool members. This is a great way to simplify access control.
626 Which Permissions Do I Need?
627 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
629 The required API permissions are documented for each individual
630 method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/.
632 The permissions are specified as a list, which can be interpreted as a
633 tree of logic and access-check functions:
635 `["and", <subtests>...]` and `["or", <subtests>...]`::
636 Each(`and`) or any(`or`) further element in the current list has to be true.
638 `["perm", <path>, [ <privileges>... ], <options>...]`::
639 The `path` is a templated parameter (see
640 <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any`
641 option is used, any) of the listed
642 privileges must be allowed on the specified path. If a `require-param`
643 option is specified, then its specified parameter is required even if the
644 API call's schema otherwise lists it as being optional.
646 `["userid-group", [ <privileges>... ], <options>...]`::
647 The caller must have any of the listed privileges on `/access/groups`. In
648 addition, there are two possible checks, depending on whether the
649 `groups_param` option is set:
651 * `groups_param` is set: The API call has a non-optional `groups` parameter
652 and the caller must have any of the listed privileges on all of the listed
654 * `groups_param` is not set: The user passed via the `userid` parameter
655 must exist and be part of a group on which the caller has any of the listed
656 privileges (via the `/access/groups/<group>` path).
658 `["userid-param", "self"]`::
659 The value provided for the API call's `userid` parameter must refer to the
660 user performing the action (usually in conjunction with `or`, to allow
661 users to perform an action on themselves, even if they don't have elevated
664 `["userid-param", "Realm.AllocateUser"]`::
665 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
666 `<realm>` referring to the realm of the user passed via the `userid`
667 parameter. Note that the user does not need to exist in order to be
668 associated with a realm, since user IDs are passed in the form of
669 `<username>@<realm>`.
671 `["perm-modify", <path>]`::
672 The `path` is a templated parameter (see
673 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
674 `Permissions.Modify` privilege or,
675 depending on the path, the following privileges as a possible substitute:
677 * `/storage/...`: additionally requires 'Datastore.Allocate`
678 * `/vms/...`: additionally requires 'VM.Allocate`
679 * `/pool/...`: additionally requires 'Pool.Allocate`
681 If the path is empty, `Permission.Modify` on `/access` is required.
686 Most users will simply use the GUI to manage users. But there is also
687 a fully featured command line tool called `pveum` (short for ``**P**roxmox
688 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
689 line tools are wrappers around the API, so you can also access those
690 functions through the REST API.
692 Here are some simple usage examples. To show help, type:
697 or (to show detailed help about a specific command)
705 pveum user add testuser@pve -comment "Just a test"
707 Set or change the password (not all realms support this):
710 pveum passwd testuser@pve
715 pveum user modify testuser@pve -enable 0
720 pveum group add testgroup
725 pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
735 It is possible that an administrator would want to create a group of users with
736 full administrator rights (without using the root account).
738 To do this, first define the group:
741 pveum group add admin -comment "System Administrators"
743 Then assign the role:
746 pveum acl modify / -group admin -role Administrator
748 Finally, you can add users to the new 'admin' group:
751 pveum user modify testuser@pve -group admin
757 You can give read only access to users by assigning the `PVEAuditor`
758 role to users or groups.
760 Example 1: Allow user `joe@pve` to see everything
763 pveum acl modify / -user joe@pve -role PVEAuditor
765 Example 2: Allow user `joe@pve` to see all virtual machines
768 pveum acl modify /vms -user joe@pve -role PVEAuditor
771 Delegate User Management
772 ~~~~~~~~~~~~~~~~~~~~~~~~
774 If you want to delegate user management to user `joe@pve`, you can do
778 pveum acl modify /access -user joe@pve -role PVEUserAdmin
780 User `joe@pve` can now add and remove users, and change other user attributes,
781 such as passwords. This is a very powerful role, and you most
782 likely want to limit it to selected realms and groups. The following
783 example allows `joe@pve` to modify users within the realm `pve`, if they
784 are members of group `customers`:
787 pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
788 pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
790 NOTE: The user is able to add other users, but only if they are
791 members of the group `customers` and within the realm `pve`.
793 Limited API Token for Monitoring
794 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
796 Permissions on API tokens are always a subset of those of their corresponding
797 user, meaning that an API token can't be used to carry out a task that the
798 backing user has no permission to do. This section will demonstrate how you can
799 use an API token with separate privileges, to limit the token owner's
802 Give the user `joe@pve` the role PVEVMAdmin on all VMs:
805 pveum acl modify /vms -user joe@pve -role PVEVMAdmin
807 Add a new API token with separate privileges, which is only allowed to view VM
808 information (for example, for monitoring purposes):
811 pveum user token add joe@pve monitoring -privsep 1
812 pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
814 Verify the permissions of the user and token:
817 pveum user permissions joe@pve
818 pveum user token permissions joe@pve monitoring
823 An enterprise is usually structured into several smaller departments, and it is
824 common that you want to assign resources and delegate management tasks to each
825 of these. Let's assume that you want to set up a pool for a software development
826 department. First, create a group:
829 pveum group add developers -comment "Our software developers"
831 Now we create a new user which is a member of that group:
834 pveum user add developer1@pve -group developers -password
836 NOTE: The "-password" parameter will prompt you for a password
838 Then we create a resource pool for our development department to use:
841 pveum pool add dev-pool --comment "IT development pool"
843 Finally, we can assign permissions to that pool:
846 pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
848 Our software developers can now administer the resources assigned to
853 include::pve-copyright.adoc[]