1 [[chapter_user_management]]
5 include::attributes.txt[]
11 pveum - Proxmox VE User Manager
17 include::pveum.1-synopsis.adoc[]
26 include::attributes.txt[]
32 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
34 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
35 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
38 By using the role based user- and permission management for all
39 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 <<pveum_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.
77 Each user can be member of several groups. Groups are the preferred
78 way to organize access permissions. You should always grant permission
79 to groups instead of using individual users. That way you will get a
80 much shorter access control list which is easier to handle.
83 [[pveum_authentication_realms]]
87 As {pve} users are just counterparts for users existing on some external
88 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
89 The following realms (authentication methods) are available:
91 Linux PAM standard authentication::
92 In this case a system user has to exist (eg. created via the `adduser`
93 command) on all nodes the user is allowed to login, and the user
94 authenticates with their usual system password.
101 usermod -a -G watchman heinz
104 Proxmox VE authentication server::
105 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
106 Password are encrypted using the SHA-256 hash method.
107 This is the most convenient method for for small (or even medium)
108 installations where users do not need access to anything outside of
109 {pve}. In this case users are fully managed by {pve} and are able to
110 change their own passwords via the GUI.
113 It is possible to authenticate users via an LDAP server (eq.
114 openldap). The server and an optional fallback server can be
115 configured and the connection can be encrypted via SSL.
117 Users are searched under a 'Base Domain Name' (`base_dn`), with the
118 user name found in the attribute specified in the 'User Attribute Name'
121 For instance, if a user is represented via the
122 following ldif dataset:
125 # user1 of People at ldap-test.com
126 dn: uid=user1,ou=People,dc=ldap-test,dc=com
129 objectClass: organizationalPerson
130 objectClass: inetOrgPerson
134 description: This is the first test user.
137 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
138 attribute would be `uid`.
140 If {pve} needs to authenticate (bind) to the ldap server before being
141 able to query and authenticate users, a bind domain name can be
142 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
143 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
144 (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
145 single line containing the raw password.
147 Microsoft Active Directory::
149 A server and authentication domain need to be specified. Like with
150 ldap an optional fallback server, optional port, and SSL
151 encryption can be configured.
154 Two factor authentication
155 -------------------------
157 Each realm can optionally be secured additionally by two factor
158 authentication. This can be done by selecting one of the available methods
159 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
160 When a realm has TFA enabled it becomes a requirement and only users with
161 configured TFA will be able to login.
163 Currently there are two methods available:
165 Time based OATH (TOTP)::
166 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
167 with the user's configured key. The time step and password length
168 parameters are configured.
170 A user can have multiple keys configured (separated by spaces), and the
171 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
173 {pve} provides a key generation tool (`oathkeygen`) which prints out a
174 random key in Base32 notation which can be used directly with various OTP
175 tools, such as the `oathtool` command line tool, the Google authenticator
176 or FreeOTP Android apps.
179 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
180 server URL must be configured, and users must have a YubiKey available. In
181 order to get the key ID from a YubiKey, you can trigger the YubiKey once
182 after connecting it to USB and copy the first 12 characters of the typed
183 password into the user's 'Key IDs' field.
186 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
187 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
188 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
189 host your own verification server].
192 [[pveum_permission_management]]
193 Permission Management
194 ---------------------
196 In order for a user to perform an action (such as listing, modifying or
197 deleting a parts of a VM configuration), the user needs to have the
198 appropriate permissions.
200 {pve} uses a role and path based permission management system. An entry in
201 the permissions table allows a user or group to take on a specific role
202 when accessing an 'object' or 'path'. This means an such an access rule can
203 be represented as a triple of '(path, user, role)' or '(path, group,
204 role)', with the role containing a set of allowed actions, and the path
205 representing the target of these actions.
212 A role is simply a list of privileges. Proxmox VE comes with a number
213 of predefined roles which satisfies most needs.
215 * `Administrator`: has all privileges
216 * `NoAccess`: has no privileges (used to forbid access)
217 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
218 * `PVEAuditor`: read only access
219 * `PVEDatastoreAdmin`: create and allocate backup space and templates
220 * `PVEDatastoreUser`: allocate backup space and view storage
221 * `PVEPoolAdmin`: allocate pools
222 * `PVESysAdmin`: User ACLs, audit, system console and system logs
223 * `PVETemplateUser`: view and clone templates
224 * `PVEUserAdmin`: user administration
225 * `PVEVMAdmin`: fully administer VMs
226 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
228 You can see the whole set of predefined roles on the GUI.
230 Adding new roles can currently only be done from the command line, like
235 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
236 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
243 A privilege is the right to perform a specific action. To simplify
244 management, lists of privileges are grouped into roles, which can then
245 be used in the permission table. Note that privileges cannot directly be
246 assigned to users and paths without being part of a role.
248 We currently use the following privileges:
250 Node / System related privileges::
252 * `Permissions.Modify`: modify access permissions
253 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
254 * `Sys.Console`: console access to Node
255 * `Sys.Syslog`: view Syslog
256 * `Sys.Audit`: view node status/config
257 * `Sys.Modify`: create/remove/modify node network parameters
258 * `Group.Allocate`: create/remove/modify groups
259 * `Pool.Allocate`: create/remove/modify a pool
260 * `Realm.Allocate`: create/remove/modify authentication realms
261 * `Realm.AllocateUser`: assign user to a realm
262 * `User.Modify`: create/remove/modify user access and details.
264 Virtual machine related privileges::
266 * `VM.Allocate`: create/remove new VM to server inventory
267 * `VM.Migrate`: migrate VM to alternate server on cluster
268 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
269 * `VM.Console`: console access to VM
270 * `VM.Monitor`: access to VM monitor (kvm)
271 * `VM.Backup`: backup/restore VMs
272 * `VM.Audit`: view VM config
273 * `VM.Clone`: clone/copy a VM
274 * `VM.Config.Disk`: add/modify/delete Disks
275 * `VM.Config.CDROM`: eject/change CDROM
276 * `VM.Config.CPU`: modify CPU settings
277 * `VM.Config.Memory`: modify Memory settings
278 * `VM.Config.Network`: add/modify/delete Network devices
279 * `VM.Config.HWType`: modify emulated HW type
280 * `VM.Config.Options`: modify any other VM configuration
281 * `VM.Snapshot`: create/remove VM snapshots
283 Storage related privileges::
285 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
286 * `Datastore.AllocateSpace`: allocate space on a datastore
287 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
288 * `Datastore.Audit`: view/browse a datastore
294 Access permissions are assigned to objects, such as a virtual machines,
295 storages or pools of resources.
296 We use file system like paths to address these objects. These paths form a
297 natural tree, and permissions of higher levels (shorter path) can
298 optionally be propagated down within this hierarchy.
301 Paths can be templated. When an API call requires permissions on a
302 templated path, the path may contain references to parameters of the API
303 call. These references are specified in curly braces. Some parameters are
304 implicitly taken from the API call's URI. For instance the permission path
305 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
306 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
307 refers to the method's `path` parameter.
311 * `/nodes/{node}`: Access to {pve} server machines
312 * `/vms`: Covers all VMs
313 * `/vms/{vmid}`: Access to specific VMs
314 * `/storage/{storeid}`: Access to a storages
315 * `/pool/{poolname}`: Access to VMs part of a <<resource-pools,pool>
316 * `/access/groups`: Group administration
317 * `/access/realms/{realmid}`: Administrative access to realms
323 As mentioned earlier, object paths form a file system like tree, and
324 permissions can be inherited down that tree (the propagate flag is set
325 by default). We use the following inheritance rules:
327 * Permissions for individual users always replace group permissions.
328 * Permissions for groups apply when the user is member of that group.
329 * Permissions replace the ones inherited from an upper level.
336 Pools can be used to group a set of virtual machines and data
337 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
338 which are inherited to all pool members. This is a great way simplify
342 What permission do I need?
343 ~~~~~~~~~~~~~~~~~~~~~~~~~~
345 The required API permissions are documented for each individual
346 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
348 The permissions are specified as a list which can be interpreted as a
349 tree of logic and access-check functions:
351 `["and", <subtests>...]` and `["or", <subtests>...]`::
352 Each(`and`) or any(`or`) further element in the current list has to be true.
354 `["perm", <path>, [ <privileges>... ], <options>...]`::
355 The `path` is a templated parameter (see <<templated-paths,Objects and
356 Paths>>). All (or , if the `any` option is used, any) of the listed
357 privileges must be allowed on the specified path. If a `require-param`
358 option is specified, then its specified parameter is required even if the
359 API call's schema otherwise lists it as being optional.
361 `["userid-group", [ <privileges>... ], <options>...]`::
362 The callermust have any of the listed privileges on `/access/groups`. In
363 addition there are two possible checks depending on whether the
364 `groups_param` option is set:
366 * `groups_param` is set: The API call has a non-optional `groups` parameter
367 and the caller must have any of the listed privileges on all of the listed
369 * `groups_param` is not set: The user passed via the `userid` parameter
370 must exist and be part of a group on which the caller has any of the listed
371 privileges (via the `/access/groups/<group>` path).
373 `["userid-param", "self"]`::
374 The value provided for the API call's `userid` parameter must refer to the
375 user performing the action. (Usually in conjunction with `or`, to allow
376 users to perform an action on themselves even if they don't have elevated
379 `["userid-param", "Realm.AllocateUser"]`::
380 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
381 `<realm>` refering to the realm of the user passed via the `userid`
382 parameter. Note that the user does not need to exist in order to be
383 associated with a realm, since user IDs are passed in the form of
384 `<username>@<realm>`.
386 `["perm-modify", <path>]`::
387 The `path` is a templated parameter (see <<templated-paths,Objects and
388 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
389 depending on the path, the following privileges as a possible substitute:
391 * `/storage/...`: additionally requires 'Datastore.Allocate`
392 * `/vms/...`: additionally requires 'VM.Allocate`
393 * `/pool/...`: additionally requires 'Pool.Allocate`
395 If the path is empty, `Permission.Modify` on `/access` is required.
400 Most users will simply use the GUI to manage users. But there is also
401 a full featured command line tool called `pveum` (short for ``**P**roxmox
402 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
403 line tools are wrappers around the API, so you can also access those
404 function through the REST API.
406 Here are some simple usage examples. To show help type:
411 or (to show detailed help about a specific command)
419 pveum useradd testuser@pve -comment "Just a test"
421 Set or Change the password (not all realms support that):
424 pveum passwd testuser@pve
429 pveum usermod testuser@pve -enable 0
434 pveum groupadd testgroup
439 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
449 One of the most wanted features was the ability to define a group of
450 users with full administrator rights (without using the root account).
455 pveum groupadd admin -comment "System Administrators"
457 Then add the permission:
460 pveum aclmod / -group admin -role Administrator
462 You can finally add users to the new 'admin' group:
465 pveum usermod testuser@pve -group admin
471 You can give read only access to users by assigning the `PVEAuditor`
472 role to users or groups.
474 Example1: Allow user `joe@pve` to see everything
477 pveum aclmod / -user joe@pve -role PVEAuditor
479 Example1: Allow user `joe@pve` to see all virtual machines
482 pveum aclmod /vms -user joe@pve -role PVEAuditor
485 Delegate User Management
486 ~~~~~~~~~~~~~~~~~~~~~~~~
488 If you want to delegate user managenent to user `joe@pve` you can do
492 pveum aclmod /access -user joe@pve -role PVEUserAdmin
494 User `joe@pve` can now add and remove users, change passwords and
495 other user attributes. This is a very powerful role, and you most
496 likely want to limit that to selected realms and groups. The following
497 example allows `joe@pve` to modify users within realm `pve` if they
498 are members of group `customers`:
501 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
502 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
504 NOTE: The user is able to add other users, but only if they are
505 members of group `customers` and within realm `pve`.
511 An enterprise is usually structured into several smaller departments,
512 and it is common that you want to assign resources to them and
513 delegate management tasks. A pool is simply a set of virtual machines
514 and data stores. You can create pools on the GUI. After that you can
515 add resources to the pool (VMs, Storage).
517 You can also assign permissions to the pool. Those permissions are
518 inherited to all pool members.
520 Lets assume you have a software development department, so we first
524 pveum groupadd developers -comment "Our software developers"
526 Now we create a new user which is a member of that group
529 pveum useradd developer1@pve -group developers -password
531 NOTE: The -password parameter will prompt you for a password
533 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
536 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
538 Our software developers can now administrate the resources assigned to
543 include::pve-copyright.adoc[]