4 include::attributes.txt[]
11 pveum - Proxmox VE User Manager
17 include::pveum.1-synopsis.adoc[]
27 include::attributes.txt[]
34 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
36 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
37 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
40 By using the role based user- and permission management for all
41 objects (VMs, storages, nodes, etc.) granular access can be defined.
47 {pve} stores user attributes in `/etc/pve/user.cfg`.
48 Passwords are not stored here, users are instead associated with
49 <<authentication-realms,authentication realms>> described below.
50 Therefore a user is internally often identified by its name and
51 realm in the form `<userid>@<realm>`.
53 Each user entry in this file contains the following information:
59 * An optional Expiration date
60 * A comment or note about this user
61 * Whether this user is enabled or disabled
62 * Optional two factor authentication keys
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 and system mails will be sent to the email address
71 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 [[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 Permission Management
193 ---------------------
195 In order for a user to perform an action (such as listing, modifying or
196 deleting a parts of a VM configuration), the user needs to have the
197 appropriate permissions.
199 {pve} uses a role and path based permission management system. An entry in
200 the permissions table allows a user or group to take on a specific role
201 when accessing an 'object' or 'path'. This means an such an access rule can
202 be represented as a triple of '(path, user, role)' or '(path, group,
203 role)', with the role containing a set of allowed actions, and the path
204 representing the target of these actions.
210 A role is simply a list of privileges. Proxmox VE comes with a number
211 of predefined roles which satisfies most needs.
213 * `Administrator`: has all privileges
214 * `NoAccess`: has no privileges (used to forbid access)
215 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
216 * `PVEAuditor`: read only access
217 * `PVEDatastoreAdmin`: create and allocate backup space and templates
218 * `PVEDatastoreUser`: allocate backup space and view storage
219 * `PVEPoolAdmin`: allocate pools
220 * `PVESysAdmin`: User ACLs, audit, system console and system logs
221 * `PVETemplateUser`: view and clone templates
222 * `PVEUserAdmin`: user administration
223 * `PVEVMAdmin`: fully administer VMs
224 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
226 You can see the whole set of predefined roles on the GUI.
228 Adding new roles can currently only be done from the command line, like
233 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
234 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
241 A privilege is the right to perform a specific action. To simplify
242 management, lists of privileges are grouped into roles, which can then
243 be used in the permission table. Note that privileges cannot directly be
244 assigned to users and paths without being part of a role.
246 We currently use the following privileges:
248 Node / System related privileges::
250 * `Permissions.Modify`: modify access permissions
251 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
252 * `Sys.Console`: console access to Node
253 * `Sys.Syslog`: view Syslog
254 * `Sys.Audit`: view node status/config
255 * `Sys.Modify`: create/remove/modify node network parameters
256 * `Group.Allocate`: create/remove/modify groups
257 * `Pool.Allocate`: create/remove/modify a pool
258 * `Realm.Allocate`: create/remove/modify authentication realms
259 * `Realm.AllocateUser`: assign user to a realm
260 * `User.Modify`: create/remove/modify user access and details.
262 Virtual machine related privileges::
264 * `VM.Allocate`: create/remove new VM to server inventory
265 * `VM.Migrate`: migrate VM to alternate server on cluster
266 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
267 * `VM.Console`: console access to VM
268 * `VM.Monitor`: access to VM monitor (kvm)
269 * `VM.Backup`: backup/restore VMs
270 * `VM.Audit`: view VM config
271 * `VM.Clone`: clone/copy a VM
272 * `VM.Config.Disk`: add/modify/delete Disks
273 * `VM.Config.CDROM`: eject/change CDROM
274 * `VM.Config.CPU`: modify CPU settings
275 * `VM.Config.Memory`: modify Memory settings
276 * `VM.Config.Network`: add/modify/delete Network devices
277 * `VM.Config.HWType`: modify emulated HW type
278 * `VM.Config.Options`: modify any other VM configuration
279 * `VM.Snapshot`: create/remove VM snapshots
281 Storage related privileges::
283 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
284 * `Datastore.AllocateSpace`: allocate space on a datastore
285 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
286 * `Datastore.Audit`: view/browse a datastore
292 Access permissions are assigned to objects, such as a virtual machines,
293 storages or pools of resources.
294 We use file system like paths to address these objects. These paths form a
295 natural tree, and permissions of higher levels (shorter path) can
296 optionally be propagated down within this hierarchy.
299 Paths can be templated. When an API call requires permissions on a
300 templated path, the path may contain references to parameters of the API
301 call. These references are specified in curly braces. Some parameters are
302 implicitly taken from the API call's URI. For instance the permission path
303 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
304 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
305 refers to the method's `path` parameter.
309 * `/nodes/{node}`: Access to {pve} server machines
310 * `/vms`: Covers all VMs
311 * `/vms/{vmid}`: Access to specific VMs
312 * `/storage/{storeid}`: Access to a storages
313 * `/pool/{poolname}`: Access to VMs part of a <<resource-pools,pool>
314 * `/access/groups`: Group administration
315 * `/access/realms/{realmid}`: Administrative access to realms
321 As mentioned earlier, object paths form a file system like tree, and
322 permissions can be inherited down that tree (the propagate flag is set
323 by default). We use the following inheritance rules:
325 * Permissions for individual users always replace group permissions.
326 * Permissions for groups apply when the user is member of that group.
327 * Permissions replace the ones inherited from an upper level.
333 Pools can be used to group a set of virtual machines and data
334 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
335 which are inherited to all pool members. This is a great way simplify
339 What permission do I need?
340 ~~~~~~~~~~~~~~~~~~~~~~~~~~
342 The required API permissions are documented for each individual
343 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
345 The permissions are specified as a list which can be interpreted as a
346 tree of logic and access-check functions:
348 `["and", <subtests>...]` and `["or", <subtests>...]`::
349 Each(`and`) or any(`or`) further element in the current list has to be true.
351 `["perm", <path>, [ <privileges>... ], <options>...]`::
352 The `path` is a templated parameter (see <<templated-paths,Objects and
353 Paths>>). All (or , if the `any` option is used, any) of the listed
354 privileges must be allowed on the specified path. If a `require-param`
355 option is specified, then its specified parameter is required even if the
356 API call's schema otherwise lists it as being optional.
358 `["userid-group", [ <privileges>... ], <options>...]`::
359 The callermust have any of the listed privileges on `/access/groups`. In
360 addition there are two possible checks depending on whether the
361 `groups_param` option is set:
363 * `groups_param` is set: The API call has a non-optional `groups` parameter
364 and the caller must have any of the listed privileges on all of the listed
366 * `groups_param` is not set: The user passed via the `userid` parameter
367 must exist and be part of a group on which the caller has any of the listed
368 privileges (via the `/access/groups/<group>` path).
370 `["userid-param", "self"]`::
371 The value provided for the API call's `userid` parameter must refer to the
372 user performing the action. (Usually in conjunction with `or`, to allow
373 users to perform an action on themselves even if they don't have elevated
376 `["userid-param", "Realm.AllocateUser"]`::
377 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
378 `<realm>` refering to the realm of the user passed via the `userid`
379 parameter. Note that the user does not need to exist in order to be
380 associated with a realm, since user IDs are passed in the form of
381 `<username>@<realm>`.
383 `["perm-modify", <path>]`::
384 The `path` is a templated parameter (see <<templated-paths,Objects and
385 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
386 depending on the path, the following privileges as a possible substitute:
388 * `/storage/...`: additionally requires 'Datastore.Allocate`
389 * `/vms/...`: additionally requires 'VM.Allocate`
390 * `/pool/...`: additionally requires 'Pool.Allocate`
392 If the path is empty, `Permission.Modify` on `/access` is required.
397 Most users will simply use the GUI to manage users. But there is also
398 a full featured command line tool called `pveum` (short for ``**P**roxmox
399 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
400 line tools are wrappers around the API, so you can also access those
401 function through the REST API.
403 Here are some simple usage examples. To show help type:
408 or (to show detailed help about a specific command)
416 pveum useradd testuser@pve -comment "Just a test"
418 Set or Change the password (not all realms support that):
421 pveum passwd testuser@pve
426 pveum usermod testuser@pve -enable 0
431 pveum groupadd testgroup
436 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
446 One of the most wanted features was the ability to define a group of
447 users with full administrator rights (without using the root account).
452 pveum groupadd admin -comment "System Administrators"
454 Then add the permission:
457 pveum aclmod / -group admin -role Administrator
459 You can finally add users to the new 'admin' group:
462 pveum usermod testuser@pve -group admin
468 You can give read only access to users by assigning the `PVEAuditor`
469 role to users or groups.
471 Example1: Allow user `joe@pve` to see everything
474 pveum aclmod / -user joe@pve -role PVEAuditor
476 Example1: Allow user `joe@pve` to see all virtual machines
479 pveum aclmod /vms -user joe@pve -role PVEAuditor
482 Delegate User Management
483 ~~~~~~~~~~~~~~~~~~~~~~~~
485 If you want to delegate user managenent to user `joe@pve` you can do
489 pveum aclmod /access -user joe@pve -role PVEUserAdmin
491 User `joe@pve` can now add and remove users, change passwords and
492 other user attributes. This is a very powerful role, and you most
493 likely want to limit that to selected realms and groups. The following
494 example allows `joe@pve` to modify users within realm `pve` if they
495 are members of group `customers`:
498 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
499 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
501 NOTE: The user is able to add other users, but only if they are
502 members of group `customers` and within realm `pve`.
508 An enterprise is usually structured into several smaller departments,
509 and it is common that you want to assign resources to them and
510 delegate management tasks. A pool is simply a set of virtual machines
511 and data stores. You can create pools on the GUI. After that you can
512 add resources to the pool (VMs, Storage).
514 You can also assign permissions to the pool. Those permissions are
515 inherited to all pool members.
517 Lets assume you have a software development department, so we first
521 pveum groupadd developers -comment "Our software developers"
523 Now we create a new user which is a member of that group
526 pveum useradd developer1@pve -group developers -password
528 NOTE: The -password parameter will prompt you for a password
530 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
533 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
535 Our software developers can now administrate the resources assigned to
540 include::pve-copyright.adoc[]