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.
38 [[authentication-realms]]
42 As {pve} users are just counterparts for users existing on some external
43 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
44 The following realms (authentication methods) are available:
46 Linux PAM standard authentication::
47 In this case a system user has to exist (eg. created via the `adduser`
48 command) on all nodes the user is allowed to login, and the user
49 authenticates with their usual system password.
56 usermod -a -G watchman heinz
59 Proxmox VE authentication server::
60 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
61 Password are encrypted using the SHA-256 hash method.
62 This is the most convenient method for for small (or even medium)
63 installations where users do not need access to anything outside of
64 {pve}. In this case users are fully managed by {pve} and are able to
65 change their own passwords via the GUI.
68 It is possible to authenticate users via an LDAP server (eq.
69 openldap). The server and an optional fallback server can be
70 configured and the connection can be encrypted via SSL.
72 Users are searched under a 'Base Domain Name' (`base_dn`), with the
73 user name found in the attribute specified in the 'User Attribute Name'
76 For instance, if a user is represented via the
77 following ldif dataset:
80 # user1 of People at ldap-test.com
81 dn: uid=user1,ou=People,dc=ldap-test,dc=com
84 objectClass: organizationalPerson
85 objectClass: inetOrgPerson
89 description: This is the first test user.
92 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
93 attribute would be `uid`.
95 If {pve} needs to authenticate (bind) to the ldap server before being
96 able to query and authenticate users, a bind domain name can be
97 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
98 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
99 (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
100 single line containing the raw password.
102 Microsoft Active Directory::
104 A server and authentication domain need to be specified. Like with
105 ldap an optional fallback server, optional port, and SSL
106 encryption can be configured.
109 Two factor authentication
110 -------------------------
112 Each realm can optionally be secured additionally by two factor
113 authentication. This can be done by selecting one of the available methods
114 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
115 When a realm has TFA enabled it becomes a requirement and only users with
116 configured TFA will be able to login.
118 Currently there are two methods available:
120 Time based OATH (TOTP)::
121 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
122 with the user's configured key. The time step and password length
123 parameters are configured.
125 A user can have multiple keys configured (separated by spaces), and the
126 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
128 {pve} provides a key generation tool (`oathkeygen`) which prints out a
129 random key in Base32 notation which can be used directly with various OTP
130 tools, such as the `oathtool` command line tool, the Google authenticator
131 or FreeOTP Android apps.
134 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
135 server URL must be configured, and users must have a YubiKey available. In
136 order to get the key ID from a YubiKey, you can trigger the YubiKey once
137 after connecting it to USB and copy the first 12 characters of the typed
138 password into the user's 'Key IDs' field.
141 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
142 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
143 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
144 host your own verification server].
147 Terms and Definitions
148 ---------------------
154 A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The
155 login screen on the GUI shows them a separate items, but it is
156 internally used as single string.
158 We store the following attribute for users (`/etc/pve/user.cfg`):
164 * flag to enable/disable account
171 The traditional unix superuser account is called `root@pam`. All
172 system mails are forwarded to the email assigned to that account.
178 Each user can be member of several groups. Groups are the preferred
179 way to organize access permissions. You should always grant permission
180 to groups instead of using individual users. That way you will get a
181 much shorter access control list which is easier to handle.
187 Access permissions are assigned to objects, such as a virtual machines
188 (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
189 resources (`/pool/{poolname}`). We use file system like paths to
190 address those objects. Those paths form a natural tree, and
191 permissions can be inherited down that hierarchy.
197 A privilege is the right to perform a specific action. To simplify
198 management, lists of privileges are grouped into roles, which can then
199 be uses to set permissions.
201 We currently use the following privileges:
203 Node / System related privileges::
205 * `Permissions.Modify`: modify access permissions
206 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
207 * `Sys.Console`: console access to Node
208 * `Sys.Syslog`: view Syslog
209 * `Sys.Audit`: view node status/config
210 * `Sys.Modify`: create/remove/modify node network parameters
211 * `Group.Allocate`: create/remove/modify groups
212 * `Pool.Allocate`: create/remove/modify a pool
213 * `Realm.Allocate`: create/remove/modify authentication realms
214 * `Realm.AllocateUser`: assign user to a realm
215 * `User.Modify`: create/remove/modify user access and details.
217 Virtual machine related privileges::
219 * `VM.Allocate`: create/remove new VM to server inventory
220 * `VM.Migrate`: migrate VM to alternate server on cluster
221 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
222 * `VM.Console`: console access to VM
223 * `VM.Monitor`: access to VM monitor (kvm)
224 * `VM.Backup`: backup/restore VMs
225 * `VM.Audit`: view VM config
226 * `VM.Clone`: clone/copy a VM
227 * `VM.Config.Disk`: add/modify/delete Disks
228 * `VM.Config.CDROM`: eject/change CDROM
229 * `VM.Config.CPU`: modify CPU settings
230 * `VM.Config.Memory`: modify Memory settings
231 * `VM.Config.Network`: add/modify/delete Network devices
232 * `VM.Config.HWType`: modify emulated HW type
233 * `VM.Config.Options`: modify any other VM configuration
234 * `VM.Snapshot`: create/remove VM snapshots
236 Storage related privileges::
238 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
239 * `Datastore.AllocateSpace`: allocate space on a datastore
240 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
241 * `Datastore.Audit`: view/browse a datastore
247 A role is simply a list of privileges. Proxmox VE comes with a number
248 of predefined roles which satisfies most needs.
250 * `Administrator`: has all privileges
251 * `NoAccess`: has no privileges (used to forbid access)
252 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
253 * `PVEAuditor`: read only access
254 * `PVEDatastoreAdmin`: create and allocate backup space and templates
255 * `PVEDatastoreUser`: allocate backup space and view storage
256 * `PVEPoolAdmin`: allocate pools
257 * `PVESysAdmin`: User ACLs, audit, system console and system logs
258 * `PVETemplateUser`: view and clone templates
259 * `PVEUserAdmin`: user administration
260 * `PVEVMAdmin`: fully administer VMs
261 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
263 You can see the whole set of predefined roles on the GUI.
265 Adding new roles using the CLI:
269 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
270 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
277 Permissions are the way we control access to objects. In technical
278 terms they are simply a triple containing `<path,user,role>`. This
279 concept is also known as access control lists. Each permission
280 specifies a subject (user or group) and a role (set of privileges) on
283 When a subject requests an action on an object, the framework looks up
284 the roles assigned to that subject (using the object path). The set of
285 roles defines the granted privileges.
291 As mentioned earlier, object paths form a file system like tree, and
292 permissions can be inherited down that tree (the propagate flag is set
293 by default). We use the following inheritance rules:
295 * Permissions for individual users always replace group permissions.
296 * Permissions for groups apply when the user is member of that group.
297 * Permissions replace the ones inherited from an upper level.
303 Pools can be used to group a set of virtual machines and data
304 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
305 which are inherited to all pool members. This is a great way simplify
309 What permission do I need?
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~
312 The required API permissions are documented for each individual
313 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
315 The permissions are specified as a list which can be interpreted as a
316 tree of logic and access-check functions:
318 `["and", <subtests>...]` and `["or", <subtests>...]`::
319 Each(`and`) or any(`or`) further element in the current list has to be true.
321 `["perm", <path>, [ <privileges>... ], <options>...]`::
322 The `path` is a templated parameter (see <<templated-paths,Objects and
323 Paths>>). All (or , if the `any` option is used, any) of the listed
324 privileges must be allowed on the specified path. If a `require-param`
325 option is specified, then its specified parameter is required even if the
326 API call's schema otherwise lists it as being optional.
328 `["userid-group", [ <privileges>... ], <options>...]`::
329 The callermust have any of the listed privileges on `/access/groups`. In
330 addition there are two possible checks depending on whether the
331 `groups_param` option is set:
333 * `groups_param` is set: The API call has a non-optional `groups` parameter
334 and the caller must have any of the listed privileges on all of the listed
336 * `groups_param` is not set: The user passed via the `userid` parameter
337 must exist and be part of a group on which the caller has any of the listed
338 privileges (via the `/access/groups/<group>` path).
340 `["userid-param", "self"]`::
341 The value provided for the API call's `userid` parameter must refer to the
342 user performing the action. (Usually in conjunction with `or`, to allow
343 users to perform an action on themselves even if they don't have elevated
346 `["userid-param", "Realm.AllocateUser"]`::
347 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
348 `<realm>` refering to the realm of the user passed via the `userid`
349 parameter. Note that the user does not need to exist in order to be
350 associated with a realm, since user IDs are passed in the form of
351 `<username>@<realm>`.
353 `["perm-modify", <path>]`::
354 The `path` is a templated parameter (see <<templated-paths,Objects and
355 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
356 depending on the path, the following privileges as a possible substitute:
358 * `/storage/...`: additionally requires 'Datastore.Allocate`
359 * `/vms/...`: additionally requires 'VM.Allocate`
360 * `/pool/...`: additionally requires 'Pool.Allocate`
362 If the path is empty, `Permission.Modify` on `/access` is required.
367 Most users will simply use the GUI to manage users. But there is also
368 a full featured command line tool called `pveum` (short for ``**P**roxmox
369 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
370 line tools are wrappers around the API, so you can also access those
371 function through the REST API.
373 Here are some simple usage examples. To show help type:
378 or (to show detailed help about a specific command)
386 pveum useradd testuser@pve -comment "Just a test"
388 Set or Change the password (not all realms support that):
391 pveum passwd testuser@pve
396 pveum usermod testuser@pve -enable 0
401 pveum groupadd testgroup
406 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
416 One of the most wanted features was the ability to define a group of
417 users with full administrator rights (without using the root account).
422 pveum groupadd admin -comment "System Administrators"
424 Then add the permission:
427 pveum aclmod / -group admin -role Administrator
429 You can finally add users to the new 'admin' group:
432 pveum usermod testuser@pve -group admin
438 You can give read only access to users by assigning the `PVEAuditor`
439 role to users or groups.
441 Example1: Allow user `joe@pve` to see everything
444 pveum aclmod / -user joe@pve -role PVEAuditor
446 Example1: Allow user `joe@pve` to see all virtual machines
449 pveum aclmod /vms -user joe@pve -role PVEAuditor
452 Delegate User Management
453 ~~~~~~~~~~~~~~~~~~~~~~~~
455 If you want to delegate user managenent to user `joe@pve` you can do
459 pveum aclmod /access -user joe@pve -role PVEUserAdmin
461 User `joe@pve` can now add and remove users, change passwords and
462 other user attributes. This is a very powerful role, and you most
463 likely want to limit that to selected realms and groups. The following
464 example allows `joe@pve` to modify users within realm `pve` if they
465 are members of group `customers`:
468 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
469 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
471 NOTE: The user is able to add other users, but only if they are
472 members of group `customers` and within realm `pve`.
478 An enterprise is usually structured into several smaller departments,
479 and it is common that you want to assign resources to them and
480 delegate management tasks. A pool is simply a set of virtual machines
481 and data stores. You can create pools on the GUI. After that you can
482 add resources to the pool (VMs, Storage).
484 You can also assign permissions to the pool. Those permissions are
485 inherited to all pool members.
487 Lets assume you have a software development department, so we first
491 pveum groupadd developers -comment "Our software developers"
493 Now we create a new user which is a member of that group
496 pveum useradd developer1@pve -group developers -password
498 NOTE: The -password parameter will prompt you for a password
500 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
503 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
505 Our software developers can now administrate the resources assigned to
510 include::pve-copyright.adoc[]