4 include::attributes.txt[]
10 pveum - Proxmox VE User Manager
16 include::pveum.1-synopsis.adoc[]
26 include::attributes.txt[]
33 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
35 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
36 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
39 By using the role based user- and permission management for all
40 objects (VMs, storages, nodes, etc.) granular access can be defined.
46 {pve} stores user attributes in `/etc/pve/user.cfg`.
47 Passwords are not stored here, users are instead associated with
48 <<authentication-realms,authentication realms>> described below.
49 Therefore a user is internally often identified by its name and
50 realm in the form `<userid>@<realm>`.
52 Each user entry in this file contains the following information:
58 * An optional Expiration date
59 * A comment or note about this user
60 * Whether this user is enabled or disabled
61 * Optional two factor authentication keys
67 The system's root user can always log in via the Linux PAM realm and is an
68 unconfined administrator. This user cannot be deleted, but attributes can
69 still be changed and system mails will be sent to the email address
70 assigned to this user.
76 Each user can be member of several groups. Groups are the preferred
77 way to organize access permissions. You should always grant permission
78 to groups instead of using individual users. That way you will get a
79 much shorter access control list which is easier to handle.
82 [[authentication-realms]]
86 As {pve} users are just counterparts for users existing on some external
87 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
88 The following realms (authentication methods) are available:
90 Linux PAM standard authentication::
91 In this case a system user has to exist (eg. created via the `adduser`
92 command) on all nodes the user is allowed to login, and the user
93 authenticates with their usual system password.
100 usermod -a -G watchman heinz
103 Proxmox VE authentication server::
104 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
105 Password are encrypted using the SHA-256 hash method.
106 This is the most convenient method for for small (or even medium)
107 installations where users do not need access to anything outside of
108 {pve}. In this case users are fully managed by {pve} and are able to
109 change their own passwords via the GUI.
112 It is possible to authenticate users via an LDAP server (eq.
113 openldap). The server and an optional fallback server can be
114 configured and the connection can be encrypted via SSL.
116 Users are searched under a 'Base Domain Name' (`base_dn`), with the
117 user name found in the attribute specified in the 'User Attribute Name'
120 For instance, if a user is represented via the
121 following ldif dataset:
124 # user1 of People at ldap-test.com
125 dn: uid=user1,ou=People,dc=ldap-test,dc=com
128 objectClass: organizationalPerson
129 objectClass: inetOrgPerson
133 description: This is the first test user.
136 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
137 attribute would be `uid`.
139 If {pve} needs to authenticate (bind) to the ldap server before being
140 able to query and authenticate users, a bind domain name can be
141 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
142 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
143 (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
144 single line containing the raw password.
146 Microsoft Active Directory::
148 A server and authentication domain need to be specified. Like with
149 ldap an optional fallback server, optional port, and SSL
150 encryption can be configured.
153 Two factor authentication
154 -------------------------
156 Each realm can optionally be secured additionally by two factor
157 authentication. This can be done by selecting one of the available methods
158 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
159 When a realm has TFA enabled it becomes a requirement and only users with
160 configured TFA will be able to login.
162 Currently there are two methods available:
164 Time based OATH (TOTP)::
165 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
166 with the user's configured key. The time step and password length
167 parameters are configured.
169 A user can have multiple keys configured (separated by spaces), and the
170 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
172 {pve} provides a key generation tool (`oathkeygen`) which prints out a
173 random key in Base32 notation which can be used directly with various OTP
174 tools, such as the `oathtool` command line tool, the Google authenticator
175 or FreeOTP Android apps.
178 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
179 server URL must be configured, and users must have a YubiKey available. In
180 order to get the key ID from a YubiKey, you can trigger the YubiKey once
181 after connecting it to USB and copy the first 12 characters of the typed
182 password into the user's 'Key IDs' field.
185 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
186 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
187 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
188 host your own verification server].
191 Permission Management
192 ---------------------
194 In order for a user to perform an action (such as listing, modifying or
195 deleting a parts of a VM configuration), the user needs to have the
196 appropriate permissions.
198 {pve} uses a role and path based permission management system. An entry in
199 the permissions table allows a user or group to take on a specific role
200 when accessing an 'object' or 'path'. This means an such an access rule can
201 be represented as a triple of '(path, user, role)' or '(path, group,
202 role)', with the role containing a set of allowed actions, and the path
203 representing the target of these actions.
209 A role is simply a list of privileges. Proxmox VE comes with a number
210 of predefined roles which satisfies most needs.
212 * `Administrator`: has all privileges
213 * `NoAccess`: has no privileges (used to forbid access)
214 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
215 * `PVEAuditor`: read only access
216 * `PVEDatastoreAdmin`: create and allocate backup space and templates
217 * `PVEDatastoreUser`: allocate backup space and view storage
218 * `PVEPoolAdmin`: allocate pools
219 * `PVESysAdmin`: User ACLs, audit, system console and system logs
220 * `PVETemplateUser`: view and clone templates
221 * `PVEUserAdmin`: user administration
222 * `PVEVMAdmin`: fully administer VMs
223 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
225 You can see the whole set of predefined roles on the GUI.
227 Adding new roles can currently only be done from the command line, like
232 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
233 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
240 A privilege is the right to perform a specific action. To simplify
241 management, lists of privileges are grouped into roles, which can then
242 be used in the permission table. Note that privileges cannot directly be
243 assigned to users and paths without being part of a role.
245 We currently use the following privileges:
247 Node / System related privileges::
249 * `Permissions.Modify`: modify access permissions
250 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
251 * `Sys.Console`: console access to Node
252 * `Sys.Syslog`: view Syslog
253 * `Sys.Audit`: view node status/config
254 * `Sys.Modify`: create/remove/modify node network parameters
255 * `Group.Allocate`: create/remove/modify groups
256 * `Pool.Allocate`: create/remove/modify a pool
257 * `Realm.Allocate`: create/remove/modify authentication realms
258 * `Realm.AllocateUser`: assign user to a realm
259 * `User.Modify`: create/remove/modify user access and details.
261 Virtual machine related privileges::
263 * `VM.Allocate`: create/remove new VM to server inventory
264 * `VM.Migrate`: migrate VM to alternate server on cluster
265 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
266 * `VM.Console`: console access to VM
267 * `VM.Monitor`: access to VM monitor (kvm)
268 * `VM.Backup`: backup/restore VMs
269 * `VM.Audit`: view VM config
270 * `VM.Clone`: clone/copy a VM
271 * `VM.Config.Disk`: add/modify/delete Disks
272 * `VM.Config.CDROM`: eject/change CDROM
273 * `VM.Config.CPU`: modify CPU settings
274 * `VM.Config.Memory`: modify Memory settings
275 * `VM.Config.Network`: add/modify/delete Network devices
276 * `VM.Config.HWType`: modify emulated HW type
277 * `VM.Config.Options`: modify any other VM configuration
278 * `VM.Snapshot`: create/remove VM snapshots
280 Storage related privileges::
282 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
283 * `Datastore.AllocateSpace`: allocate space on a datastore
284 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
285 * `Datastore.Audit`: view/browse a datastore
291 Access permissions are assigned to objects, such as a virtual machines,
292 storages or pools of resources.
293 We use file system like paths to address these objects. These paths form a
294 natural tree, and permissions of higher levels (shorter path) can
295 optionally be propagated down within this hierarchy.
298 Paths can be templated. When an API call requires permissions on a
299 templated path, the path may contain references to parameters of the API
300 call. These references are specified in curly braces. Some parameters are
301 implicitly taken from the API call's URI. For instance the permission path
302 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
303 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
304 refers to the method's `path` parameter.
308 * `/nodes/{node}`: Access to {pve} server machines
309 * `/vms`: Covers all VMs
310 * `/vms/{vmid}`: Access to specific VMs
311 * `/storage/{storeid}`: Access to a storages
312 * `/pool/{poolname}`: Access to VMs part of a <<resource-pools,pool>
313 * `/access/groups`: Group administration
314 * `/access/realms/{realmid}`: Administrative access to realms
320 As mentioned earlier, object paths form a file system like tree, and
321 permissions can be inherited down that tree (the propagate flag is set
322 by default). We use the following inheritance rules:
324 * Permissions for individual users always replace group permissions.
325 * Permissions for groups apply when the user is member of that group.
326 * Permissions replace the ones inherited from an upper level.
332 Pools can be used to group a set of virtual machines and data
333 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
334 which are inherited to all pool members. This is a great way simplify
338 What permission do I need?
339 ~~~~~~~~~~~~~~~~~~~~~~~~~~
341 The required API permissions are documented for each individual
342 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
344 The permissions are specified as a list which can be interpreted as a
345 tree of logic and access-check functions:
347 `["and", <subtests>...]` and `["or", <subtests>...]`::
348 Each(`and`) or any(`or`) further element in the current list has to be true.
350 `["perm", <path>, [ <privileges>... ], <options>...]`::
351 The `path` is a templated parameter (see <<templated-paths,Objects and
352 Paths>>). All (or , if the `any` option is used, any) of the listed
353 privileges must be allowed on the specified path. If a `require-param`
354 option is specified, then its specified parameter is required even if the
355 API call's schema otherwise lists it as being optional.
357 `["userid-group", [ <privileges>... ], <options>...]`::
358 The callermust have any of the listed privileges on `/access/groups`. In
359 addition there are two possible checks depending on whether the
360 `groups_param` option is set:
362 * `groups_param` is set: The API call has a non-optional `groups` parameter
363 and the caller must have any of the listed privileges on all of the listed
365 * `groups_param` is not set: The user passed via the `userid` parameter
366 must exist and be part of a group on which the caller has any of the listed
367 privileges (via the `/access/groups/<group>` path).
369 `["userid-param", "self"]`::
370 The value provided for the API call's `userid` parameter must refer to the
371 user performing the action. (Usually in conjunction with `or`, to allow
372 users to perform an action on themselves even if they don't have elevated
375 `["userid-param", "Realm.AllocateUser"]`::
376 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
377 `<realm>` refering to the realm of the user passed via the `userid`
378 parameter. Note that the user does not need to exist in order to be
379 associated with a realm, since user IDs are passed in the form of
380 `<username>@<realm>`.
382 `["perm-modify", <path>]`::
383 The `path` is a templated parameter (see <<templated-paths,Objects and
384 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
385 depending on the path, the following privileges as a possible substitute:
387 * `/storage/...`: additionally requires 'Datastore.Allocate`
388 * `/vms/...`: additionally requires 'VM.Allocate`
389 * `/pool/...`: additionally requires 'Pool.Allocate`
391 If the path is empty, `Permission.Modify` on `/access` is required.
396 Most users will simply use the GUI to manage users. But there is also
397 a full featured command line tool called `pveum` (short for ``**P**roxmox
398 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
399 line tools are wrappers around the API, so you can also access those
400 function through the REST API.
402 Here are some simple usage examples. To show help type:
407 or (to show detailed help about a specific command)
415 pveum useradd testuser@pve -comment "Just a test"
417 Set or Change the password (not all realms support that):
420 pveum passwd testuser@pve
425 pveum usermod testuser@pve -enable 0
430 pveum groupadd testgroup
435 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
445 One of the most wanted features was the ability to define a group of
446 users with full administrator rights (without using the root account).
451 pveum groupadd admin -comment "System Administrators"
453 Then add the permission:
456 pveum aclmod / -group admin -role Administrator
458 You can finally add users to the new 'admin' group:
461 pveum usermod testuser@pve -group admin
467 You can give read only access to users by assigning the `PVEAuditor`
468 role to users or groups.
470 Example1: Allow user `joe@pve` to see everything
473 pveum aclmod / -user joe@pve -role PVEAuditor
475 Example1: Allow user `joe@pve` to see all virtual machines
478 pveum aclmod /vms -user joe@pve -role PVEAuditor
481 Delegate User Management
482 ~~~~~~~~~~~~~~~~~~~~~~~~
484 If you want to delegate user managenent to user `joe@pve` you can do
488 pveum aclmod /access -user joe@pve -role PVEUserAdmin
490 User `joe@pve` can now add and remove users, change passwords and
491 other user attributes. This is a very powerful role, and you most
492 likely want to limit that to selected realms and groups. The following
493 example allows `joe@pve` to modify users within realm `pve` if they
494 are members of group `customers`:
497 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
498 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
500 NOTE: The user is able to add other users, but only if they are
501 members of group `customers` and within realm `pve`.
507 An enterprise is usually structured into several smaller departments,
508 and it is common that you want to assign resources to them and
509 delegate management tasks. A pool is simply a set of virtual machines
510 and data stores. You can create pools on the GUI. After that you can
511 add resources to the pool (VMs, Storage).
513 You can also assign permissions to the pool. Those permissions are
514 inherited to all pool members.
516 Lets assume you have a software development department, so we first
520 pveum groupadd developers -comment "Our software developers"
522 Now we create a new user which is a member of that group
525 pveum useradd developer1@pve -group developers -password
527 NOTE: The -password parameter will prompt you for a password
529 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
532 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
534 Our software developers can now administrate the resources assigned to
539 include::pve-copyright.adoc[]