4 include::attributes.txt[]
9 pveum - Proxmox VE User Manager
15 include::pveum.1-synopsis.adoc[]
25 include::attributes.txt[]
28 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
30 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
31 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
34 By using the role based user- and permission management for all
35 objects (VMs, storages, nodes, etc.) granular access can be defined.
41 {pve} stores user attributes in `/etc/pve/user.cfg`.
42 Passwords are not stored here, users are instead associated with
43 <<authentication-realms,authentication realms>> described below.
44 Therefore a user is internally often identified by its name and
45 realm in the form `<userid>@<realm>`.
47 Each user entry in this file contains the following information:
53 * An optional Expiration date
54 * A comment or note about this user
55 * Whether this user is enabled or disabled
56 * Optional two factor authentication keys
62 The system's root user can always log in via the Linux PAM realm and is an
63 unconfined administrator. This user cannot be deleted, but attributes can
64 still be changed and system mails will be sent to the email address
65 assigned to this user.
71 Each user can be member of several groups. Groups are the preferred
72 way to organize access permissions. You should always grant permission
73 to groups instead of using individual users. That way you will get a
74 much shorter access control list which is easier to handle.
77 [[authentication-realms]]
81 As {pve} users are just counterparts for users existing on some external
82 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
83 The following realms (authentication methods) are available:
85 Linux PAM standard authentication::
86 In this case a system user has to exist (eg. created via the `adduser`
87 command) on all nodes the user is allowed to login, and the user
88 authenticates with their usual system password.
95 usermod -a -G watchman heinz
98 Proxmox VE authentication server::
99 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
100 Password are encrypted using the SHA-256 hash method.
101 This is the most convenient method for for small (or even medium)
102 installations where users do not need access to anything outside of
103 {pve}. In this case users are fully managed by {pve} and are able to
104 change their own passwords via the GUI.
107 It is possible to authenticate users via an LDAP server (eq.
108 openldap). The server and an optional fallback server can be
109 configured and the connection can be encrypted via SSL.
111 Users are searched under a 'Base Domain Name' (`base_dn`), with the
112 user name found in the attribute specified in the 'User Attribute Name'
115 For instance, if a user is represented via the
116 following ldif dataset:
119 # user1 of People at ldap-test.com
120 dn: uid=user1,ou=People,dc=ldap-test,dc=com
123 objectClass: organizationalPerson
124 objectClass: inetOrgPerson
128 description: This is the first test user.
131 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
132 attribute would be `uid`.
134 If {pve} needs to authenticate (bind) to the ldap server before being
135 able to query and authenticate users, a bind domain name can be
136 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
137 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
138 (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
139 single line containing the raw password.
141 Microsoft Active Directory::
143 A server and authentication domain need to be specified. Like with
144 ldap an optional fallback server, optional port, and SSL
145 encryption can be configured.
148 Two factor authentication
149 -------------------------
151 Each realm can optionally be secured additionally by two factor
152 authentication. This can be done by selecting one of the available methods
153 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
154 When a realm has TFA enabled it becomes a requirement and only users with
155 configured TFA will be able to login.
157 Currently there are two methods available:
159 Time based OATH (TOTP)::
160 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
161 with the user's configured key. The time step and password length
162 parameters are configured.
164 A user can have multiple keys configured (separated by spaces), and the
165 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
167 {pve} provides a key generation tool (`oathkeygen`) which prints out a
168 random key in Base32 notation which can be used directly with various OTP
169 tools, such as the `oathtool` command line tool, the Google authenticator
170 or FreeOTP Android apps.
173 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
174 server URL must be configured, and users must have a YubiKey available. In
175 order to get the key ID from a YubiKey, you can trigger the YubiKey once
176 after connecting it to USB and copy the first 12 characters of the typed
177 password into the user's 'Key IDs' field.
180 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
181 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
182 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
183 host your own verification server].
186 Permission Management
187 ---------------------
189 In order for a user to perform an action (such as listing, modifying or
190 deleting a parts of a VM configuration), the user needs to have the
191 appropriate permissions.
193 {pve} uses a role and path based permission management system. An entry in
194 the permissions table allows a user or group to take on a specific role
195 when accessing an 'object' or 'path'. This means an such an access rule can
196 be represented as a triple of '(path, user, role)' or '(path, group,
197 role)', with the role containing a set of allowed actions, and the path
198 representing the target of these actions.
204 A role is simply a list of privileges. Proxmox VE comes with a number
205 of predefined roles which satisfies most needs.
207 * `Administrator`: has all privileges
208 * `NoAccess`: has no privileges (used to forbid access)
209 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
210 * `PVEAuditor`: read only access
211 * `PVEDatastoreAdmin`: create and allocate backup space and templates
212 * `PVEDatastoreUser`: allocate backup space and view storage
213 * `PVEPoolAdmin`: allocate pools
214 * `PVESysAdmin`: User ACLs, audit, system console and system logs
215 * `PVETemplateUser`: view and clone templates
216 * `PVEUserAdmin`: user administration
217 * `PVEVMAdmin`: fully administer VMs
218 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
220 You can see the whole set of predefined roles on the GUI.
222 Adding new roles can currently only be done from the command line, like
227 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
228 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
235 Access permissions are assigned to objects, such as a virtual machines
236 (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
237 resources (`/pool/{poolname}`). We use file system like paths to
238 address those objects. Those paths form a natural tree, and
239 permissions can be inherited down that hierarchy.
245 A privilege is the right to perform a specific action. To simplify
246 management, lists of privileges are grouped into roles, which can then
247 be used in the permission table. Note that privileges cannot directly be
248 assigned to users and paths without being part of a role.
250 We currently use the following privileges:
252 Node / System related privileges::
254 * `Permissions.Modify`: modify access permissions
255 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
256 * `Sys.Console`: console access to Node
257 * `Sys.Syslog`: view Syslog
258 * `Sys.Audit`: view node status/config
259 * `Sys.Modify`: create/remove/modify node network parameters
260 * `Group.Allocate`: create/remove/modify groups
261 * `Pool.Allocate`: create/remove/modify a pool
262 * `Realm.Allocate`: create/remove/modify authentication realms
263 * `Realm.AllocateUser`: assign user to a realm
264 * `User.Modify`: create/remove/modify user access and details.
266 Virtual machine related privileges::
268 * `VM.Allocate`: create/remove new VM to server inventory
269 * `VM.Migrate`: migrate VM to alternate server on cluster
270 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
271 * `VM.Console`: console access to VM
272 * `VM.Monitor`: access to VM monitor (kvm)
273 * `VM.Backup`: backup/restore VMs
274 * `VM.Audit`: view VM config
275 * `VM.Clone`: clone/copy a VM
276 * `VM.Config.Disk`: add/modify/delete Disks
277 * `VM.Config.CDROM`: eject/change CDROM
278 * `VM.Config.CPU`: modify CPU settings
279 * `VM.Config.Memory`: modify Memory settings
280 * `VM.Config.Network`: add/modify/delete Network devices
281 * `VM.Config.HWType`: modify emulated HW type
282 * `VM.Config.Options`: modify any other VM configuration
283 * `VM.Snapshot`: create/remove VM snapshots
285 Storage related privileges::
287 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
288 * `Datastore.AllocateSpace`: allocate space on a datastore
289 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
290 * `Datastore.Audit`: view/browse a datastore
296 Permissions are the way we control access to objects. In technical
297 terms they are simply a triple containing `<path,user,role>`. This
298 concept is also known as access control lists. Each permission
299 specifies a subject (user or group) and a role (set of privileges) on
302 When a subject requests an action on an object, the framework looks up
303 the roles assigned to that subject (using the object path). The set of
304 roles defines the granted privileges.
310 As mentioned earlier, object paths form a file system like tree, and
311 permissions can be inherited down that tree (the propagate flag is set
312 by default). We use the following inheritance rules:
314 * Permissions for individual users always replace group permissions.
315 * Permissions for groups apply when the user is member of that group.
316 * Permissions replace the ones inherited from an upper level.
322 Pools can be used to group a set of virtual machines and data
323 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
324 which are inherited to all pool members. This is a great way simplify
328 What permission do I need?
329 ~~~~~~~~~~~~~~~~~~~~~~~~~~
331 The required API permissions are documented for each individual
332 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
334 The permissions are specified as a list which can be interpreted as a
335 tree of logic and access-check functions:
337 `["and", <subtests>...]` and `["or", <subtests>...]`::
338 Each(`and`) or any(`or`) further element in the current list has to be true.
340 `["perm", <path>, [ <privileges>... ], <options>...]`::
341 The `path` is a templated parameter (see <<templated-paths,Objects and
342 Paths>>). All (or , if the `any` option is used, any) of the listed
343 privileges must be allowed on the specified path. If a `require-param`
344 option is specified, then its specified parameter is required even if the
345 API call's schema otherwise lists it as being optional.
347 `["userid-group", [ <privileges>... ], <options>...]`::
348 The callermust have any of the listed privileges on `/access/groups`. In
349 addition there are two possible checks depending on whether the
350 `groups_param` option is set:
352 * `groups_param` is set: The API call has a non-optional `groups` parameter
353 and the caller must have any of the listed privileges on all of the listed
355 * `groups_param` is not set: The user passed via the `userid` parameter
356 must exist and be part of a group on which the caller has any of the listed
357 privileges (via the `/access/groups/<group>` path).
359 `["userid-param", "self"]`::
360 The value provided for the API call's `userid` parameter must refer to the
361 user performing the action. (Usually in conjunction with `or`, to allow
362 users to perform an action on themselves even if they don't have elevated
365 `["userid-param", "Realm.AllocateUser"]`::
366 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
367 `<realm>` refering to the realm of the user passed via the `userid`
368 parameter. Note that the user does not need to exist in order to be
369 associated with a realm, since user IDs are passed in the form of
370 `<username>@<realm>`.
372 `["perm-modify", <path>]`::
373 The `path` is a templated parameter (see <<templated-paths,Objects and
374 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
375 depending on the path, the following privileges as a possible substitute:
377 * `/storage/...`: additionally requires 'Datastore.Allocate`
378 * `/vms/...`: additionally requires 'VM.Allocate`
379 * `/pool/...`: additionally requires 'Pool.Allocate`
381 If the path is empty, `Permission.Modify` on `/access` is required.
386 Most users will simply use the GUI to manage users. But there is also
387 a full featured command line tool called `pveum` (short for ``**P**roxmox
388 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
389 line tools are wrappers around the API, so you can also access those
390 function through the REST API.
392 Here are some simple usage examples. To show help type:
397 or (to show detailed help about a specific command)
405 pveum useradd testuser@pve -comment "Just a test"
407 Set or Change the password (not all realms support that):
410 pveum passwd testuser@pve
415 pveum usermod testuser@pve -enable 0
420 pveum groupadd testgroup
425 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
435 One of the most wanted features was the ability to define a group of
436 users with full administrator rights (without using the root account).
441 pveum groupadd admin -comment "System Administrators"
443 Then add the permission:
446 pveum aclmod / -group admin -role Administrator
448 You can finally add users to the new 'admin' group:
451 pveum usermod testuser@pve -group admin
457 You can give read only access to users by assigning the `PVEAuditor`
458 role to users or groups.
460 Example1: Allow user `joe@pve` to see everything
463 pveum aclmod / -user joe@pve -role PVEAuditor
465 Example1: Allow user `joe@pve` to see all virtual machines
468 pveum aclmod /vms -user joe@pve -role PVEAuditor
471 Delegate User Management
472 ~~~~~~~~~~~~~~~~~~~~~~~~
474 If you want to delegate user managenent to user `joe@pve` you can do
478 pveum aclmod /access -user joe@pve -role PVEUserAdmin
480 User `joe@pve` can now add and remove users, change passwords and
481 other user attributes. This is a very powerful role, and you most
482 likely want to limit that to selected realms and groups. The following
483 example allows `joe@pve` to modify users within realm `pve` if they
484 are members of group `customers`:
487 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
488 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
490 NOTE: The user is able to add other users, but only if they are
491 members of group `customers` and within realm `pve`.
497 An enterprise is usually structured into several smaller departments,
498 and it is common that you want to assign resources to them and
499 delegate management tasks. A pool is simply a set of virtual machines
500 and data stores. You can create pools on the GUI. After that you can
501 add resources to the pool (VMs, Storage).
503 You can also assign permissions to the pool. Those permissions are
504 inherited to all pool members.
506 Lets assume you have a software development department, so we first
510 pveum groupadd developers -comment "Our software developers"
512 Now we create a new user which is a member of that group
515 pveum useradd developer1@pve -group developers -password
517 NOTE: The -password parameter will prompt you for a password
519 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
522 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
524 Our software developers can now administrate the resources assigned to
529 include::pve-copyright.adoc[]