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. Microsoft
31 Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
32 authentication server.
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 * permission for individual users always overwrite group permission.
296 * permission for groups apply when the user is member of that group.
297 * permission set at higher level always overwrites inherited permissions.
300 What permission do I need?
301 ^^^^^^^^^^^^^^^^^^^^^^^^^^
303 The required API permissions are documented for each individual
304 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
310 Pools can be used to group a set of virtual machines and data
311 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
312 which are inherited to all pool members. This is a great way simplify
318 Most users will simply use the GUI to manage users. But there is also
319 a full featured command line tool called `pveum` (short for ``**P**roxmox
320 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
321 line tools are wrappers around the API, so you can also access those
322 function through the REST API.
324 Here are some simple usage examples. To show help type:
329 or (to show detailed help about a specific command)
337 pveum useradd testuser@pve -comment "Just a test"
339 Set or Change the password (not all realms support that):
342 pveum passwd testuser@pve
347 pveum usermod testuser@pve -enable 0
352 pveum groupadd testgroup
357 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
367 One of the most wanted features was the ability to define a group of
368 users with full administrator rights (without using the root account).
373 pveum groupadd admin -comment "System Administrators"
375 Then add the permission:
378 pveum aclmod / -group admin -role Administrator
380 You can finally add users to the new 'admin' group:
383 pveum usermod testuser@pve -group admin
389 You can give read only access to users by assigning the `PVEAuditor`
390 role to users or groups.
392 Example1: Allow user `joe@pve` to see everything
395 pveum aclmod / -user joe@pve -role PVEAuditor
397 Example1: Allow user `joe@pve` to see all virtual machines
400 pveum aclmod /vms -user joe@pve -role PVEAuditor
403 Delegate User Management
404 ~~~~~~~~~~~~~~~~~~~~~~~~
406 If you want to delegate user managenent to user `joe@pve` you can do
410 pveum aclmod /access -user joe@pve -role PVEUserAdmin
412 User `joe@pve` can now add and remove users, change passwords and
413 other user attributes. This is a very powerful role, and you most
414 likely want to limit that to selected realms and groups. The following
415 example allows `joe@pve` to modify users within realm `pve` if they
416 are members of group `customers`:
419 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
420 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
422 NOTE: The user is able to add other users, but only if they are
423 members of group `customers` and within realm `pve`.
429 An enterprise is usually structured into several smaller departments,
430 and it is common that you want to assign resources to them and
431 delegate management tasks. A pool is simply a set of virtual machines
432 and data stores. You can create pools on the GUI. After that you can
433 add resources to the pool (VMs, Storage).
435 You can also assign permissions to the pool. Those permissions are
436 inherited to all pool members.
438 Lets assume you have a software development department, so we first
442 pveum groupadd developers -comment "Our software developers"
444 Now we create a new user which is a member of that group
447 pveum useradd developer1@pve -group developers -password
449 NOTE: The -password parameter will prompt you for a password
451 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
454 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
456 Our software developers can now administrate the resources assigned to
461 include::pve-copyright.adoc[]