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