make dinstall: skip mediawiki deb for now
[pve-docs.git] / pveum.adoc
1 [[chapter_user_management]]
2 ifdef::manvolnum[]
3 pveum(1)
4 ========
5 :pve-toplevel:
6
7 NAME
8 ----
9
10 pveum - Proxmox VE User Manager
11
12
13 SYNOPSIS
14 --------
15
16 include::pveum.1-synopsis.adoc[]
17
18
19 DESCRIPTION
20 -----------
21 endif::manvolnum[]
22 ifndef::manvolnum[]
23 User Management
24 ===============
25 :pve-toplevel:
26 endif::manvolnum[]
27
28 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
29
30 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
31 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
32 Directory.
33
34 By using the role based user- and permission management for all
35 objects (VMs, storages, nodes, etc.) granular access can be defined.
36
37
38 [[pveum_users]]
39 Users
40 -----
41
42 {pve} stores user attributes in `/etc/pve/user.cfg`.
43 Passwords are not stored here, users are instead associated with
44 <<pveum_authentication_realms,authentication realms>> described below.
45 Therefore a user is internally often identified by its name and
46 realm in the form `<userid>@<realm>`.
47
48 Each user entry in this file contains the following information:
49
50 * First name
51 * Last name
52 * E-mail address
53 * Group memberships
54 * An optional Expiration date
55 * A comment or note about this user
56 * Whether this user is enabled or disabled
57 * Optional two factor authentication keys
58
59
60 System administrator
61 ~~~~~~~~~~~~~~~~~~~~
62
63 The system's root user can always log in via the Linux PAM realm and is an
64 unconfined administrator. This user cannot be deleted, but attributes can
65 still be changed and system mails will be sent to the email address
66 assigned to this user.
67
68
69 [[pveum_groups]]
70 Groups
71 ~~~~~~
72
73 Each user can be member of several groups. Groups are the preferred
74 way to organize access permissions. You should always grant permission
75 to groups instead of using individual users. That way you will get a
76 much shorter access control list which is easier to handle.
77
78
79 [[pveum_authentication_realms]]
80 Authentication Realms
81 ---------------------
82
83 As {pve} users are just counterparts for users existing on some external
84 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
85 The following realms (authentication methods) are available:
86
87 Linux PAM standard authentication::
88 In this case a system user has to exist (e.g. created via the `adduser`
89 command) on all nodes the user is allowed to login, and the user
90 authenticates with their usual system password.
91 +
92 [source,bash]
93 ----
94 useradd heinz
95 passwd heinz
96 groupadd watchman
97 usermod -a -G watchman heinz
98 ----
99
100 Proxmox VE authentication server::
101 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
102 Password are encrypted using the SHA-256 hash method.
103 This is the most convenient method for small (or even medium)
104 installations where users do not need access to anything outside of
105 {pve}. In this case users are fully managed by {pve} and are able to
106 change their own passwords via the GUI.
107
108 LDAP::
109 It is possible to authenticate users via an LDAP server (e.g.
110 openldap). The server and an optional fallback server can be
111 configured and the connection can be encrypted via SSL.
112 +
113 Users are searched under a 'Base Domain Name' (`base_dn`), with the
114 user name found in the attribute specified in the 'User Attribute Name'
115 (`user_attr`) field.
116 +
117 For instance, if a user is represented via the
118 following ldif dataset:
119 +
120 ----
121 # user1 of People at ldap-test.com
122 dn: uid=user1,ou=People,dc=ldap-test,dc=com
123 objectClass: top
124 objectClass: person
125 objectClass: organizationalPerson
126 objectClass: inetOrgPerson
127 uid: user1
128 cn: Test User 1
129 sn: Testers
130 description: This is the first test user.
131 ----
132 +
133 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
134 attribute would be `uid`.
135 +
136 If {pve} needs to authenticate (bind) to the ldap server before being
137 able to query and authenticate users, a bind domain name can be
138 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
139 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
140 (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
141 single line containing the raw password.
142
143 Microsoft Active Directory::
144
145 A server and authentication domain need to be specified. Like with
146 ldap an optional fallback server, optional port, and SSL
147 encryption can be configured.
148
149
150 [[pveum_tfa_auth]]
151 Two factor authentication
152 -------------------------
153
154 There are two ways to use two factor authentication:
155
156 It can be required by the authentication realm, either via 'TOTP' or
157 'YubiKey OTP'. In this case a newly created user needs their keys added
158 immediately as there is no way to log in without the second factor. In the case
159 of 'TOTP' a user can also change the 'TOTP' later on provided they can log in
160 first.
161
162 Alternatively a user can choose to opt into two factor authentication via 'TOTP'
163 later on even if the realm does not enforce it. As another option, if the server
164 has an 'AppId' configured, a user can opt into 'U2F' authentication, provided
165 the realm does not enforce any other second factor.
166
167 Realm enforced two factor authentication
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169
170 This can be done by selecting one of the available methods
171 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
172 When a realm has TFA enabled it becomes a requirement and only users with
173 configured TFA will be able to login.
174
175 Currently there are two methods available:
176
177 Time based OATH (TOTP)::
178 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
179 with the user's configured key. The time step and password length
180 parameters are configured.
181 +
182 A user can have multiple keys configured (separated by spaces), and the
183 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
184 +
185 {pve} provides a key generation tool (`oathkeygen`) which prints out a
186 random key in Base32 notation which can be used directly with various OTP
187 tools, such as the `oathtool` command line tool, the Google authenticator
188 or FreeOTP Android apps.
189
190 YubiKey OTP::
191 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
192 server URL must be configured, and users must have a YubiKey available. In
193 order to get the key ID from a YubiKey, you can trigger the YubiKey once
194 after connecting it to USB and copy the first 12 characters of the typed
195 password into the user's 'Key IDs' field.
196 +
197 Please refer to the
198 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
199 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
200 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
201 host your own verification server].
202
203 [[pveum_user_configured_totp]]
204 User configured TOTP authentication
205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206
207 A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button
208 in the user list, unless the realm enforces 'YubiKey OTP'.
209
210 [thumbnail="screenshot/gui-datacenter-users-tfa.png"]
211
212 After opening the 'TFA' window, the user is presented with a dialog to setup
213 'TOTP' authentication. The 'Secret' field contains the key, which can simply be
214 generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
215 added to provide information to the 'TOTP' app what the key belongs to.
216 Most 'TOTP' apps will show the issuer name together with the corresponding
217 'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
218
219 After generating a key, a QR code will be displayed which can be used with most
220 OTP apps such as FreeOTP. Now the user needs to verify both the current user
221 password (unless logged in as 'root'), as well as the ability to correctly use
222 the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
223 field before pressing the 'Apply' button.
224
225 Server side U2F configuration
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227
228 To allow users to use 'U2F' authentication, the server needs to have a valid
229 domain with a valid https certificate. Initially an 'AppId'
230 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
231 needs to be configured.
232
233 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
234 unusable!
235
236 This is done via `/etc/pve/datacenter.cfg`, for instance:
237
238 ----
239 u2f: appid=https://mypve.example.com:8006
240 ----
241
242 For a single node, the 'AppId' can simply be the web UI address exactly as it
243 is used in the browser, including the 'https://' and the port as shown above.
244 Please note that some browsers may be more strict than others when matching
245 'AppIds'.
246
247 When using multiple nodes, it is best to have a separate `https` server
248 providing an `appid.json`
249 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
250 file, as it seems to be compatible with most
251 browsers. If all nodes use subdomains of the same top level domain, it may be
252 enough to use the TLD as 'AppId', but note that some browsers may not accept
253 this.
254
255 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
256 situation where this does not happen, particularly when using a top level domain
257 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
258 recommended to test the configuration with multiple browsers, as changing the
259 'AppId' later will render existing 'U2F' registrations unusable.
260
261 [[pveum_user_configured_u2f]]
262 Activating U2F as a user
263 ~~~~~~~~~~~~~~~~~~~~~~~~
264
265 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
266 current password (unless logged in as root), and press the 'Register' button.
267 If the server is setup correctly and the browser accepted the server's provided
268 'AppId', a message will appear prompting the user to press the button on the
269 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
270 on steadily around twice per second).
271
272 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
273 before they can use a 'U2F' token.
274
275 [[pveum_permission_management]]
276 Permission Management
277 ---------------------
278
279 In order for a user to perform an action (such as listing, modifying or
280 deleting a parts of a VM configuration), the user needs to have the
281 appropriate permissions.
282
283 {pve} uses a role and path based permission management system. An entry in
284 the permissions table allows a user or group to take on a specific role
285 when accessing an 'object' or 'path'. This means an such an access rule can
286 be represented as a triple of '(path, user, role)' or '(path, group,
287 role)', with the role containing a set of allowed actions, and the path
288 representing the target of these actions.
289
290
291 [[pveum_roles]]
292 Roles
293 ~~~~~
294
295 A role is simply a list of privileges. Proxmox VE comes with a number
296 of predefined roles which satisfies most needs.
297
298 * `Administrator`: has all privileges
299 * `NoAccess`: has no privileges (used to forbid access)
300 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
301 * `PVEAuditor`: read only access
302 * `PVEDatastoreAdmin`: create and allocate backup space and templates
303 * `PVEDatastoreUser`: allocate backup space and view storage
304 * `PVEPoolAdmin`: allocate pools
305 * `PVESysAdmin`: User ACLs, audit, system console and system logs
306 * `PVETemplateUser`: view and clone templates
307 * `PVEUserAdmin`: user administration
308 * `PVEVMAdmin`: fully administer VMs
309 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
310
311 You can see the whole set of predefined roles on the GUI.
312
313 Adding new roles can be done via both GUI and the command line.
314
315 [thumbnail="screenshot/gui-datacenter-role-add.png"]
316 For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and
317 click on the 'Create' button, there you can set a name and select all desired
318 roles from the 'Privileges' dropdown box.
319
320 To add a role through the command line you can use the 'pveum' CLI tool, like
321 this:
322 [source,bash]
323 ----
324 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
325 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
326 ----
327
328
329 Privileges
330 ~~~~~~~~~~
331
332 A privilege is the right to perform a specific action. To simplify
333 management, lists of privileges are grouped into roles, which can then
334 be used in the permission table. Note that privileges cannot directly be
335 assigned to users and paths without being part of a role.
336
337 We currently use the following privileges:
338
339 Node / System related privileges::
340
341 * `Permissions.Modify`: modify access permissions
342 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
343 * `Sys.Console`: console access to Node
344 * `Sys.Syslog`: view Syslog
345 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
346 * `Sys.Modify`: create/remove/modify node network parameters
347 * `Group.Allocate`: create/remove/modify groups
348 * `Pool.Allocate`: create/remove/modify a pool
349 * `Realm.Allocate`: create/remove/modify authentication realms
350 * `Realm.AllocateUser`: assign user to a realm
351 * `User.Modify`: create/remove/modify user access and details.
352
353 Virtual machine related privileges::
354
355 * `VM.Allocate`: create/remove new VM to server inventory
356 * `VM.Migrate`: migrate VM to alternate server on cluster
357 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
358 * `VM.Console`: console access to VM
359 * `VM.Monitor`: access to VM monitor (kvm)
360 * `VM.Backup`: backup/restore VMs
361 * `VM.Audit`: view VM config
362 * `VM.Clone`: clone/copy a VM
363 * `VM.Config.Disk`: add/modify/delete Disks 
364 * `VM.Config.CDROM`: eject/change CDROM
365 * `VM.Config.CPU`: modify CPU settings
366 * `VM.Config.Memory`: modify Memory settings
367 * `VM.Config.Network`: add/modify/delete Network devices
368 * `VM.Config.HWType`: modify emulated HW type
369 * `VM.Config.Options`: modify any other VM configuration
370 * `VM.Snapshot`: create/remove VM snapshots
371
372 Storage related privileges::
373
374 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
375 * `Datastore.AllocateSpace`: allocate space on a datastore
376 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images 
377 * `Datastore.Audit`: view/browse a datastore
378
379
380 Objects and Paths
381 ~~~~~~~~~~~~~~~~~
382
383 Access permissions are assigned to objects, such as a virtual machines,
384 storages or pools of resources.
385 We use file system like paths to address these objects. These paths form a
386 natural tree, and permissions of higher levels (shorter path) can
387 optionally be propagated down within this hierarchy.
388
389 [[pveum_templated_paths]]
390 Paths can be templated. When an API call requires permissions on a
391 templated path, the path may contain references to parameters of the API
392 call. These references are specified in curly braces. Some parameters are
393 implicitly taken from the API call's URI. For instance the permission path
394 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
395 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
396 refers to the method's `path` parameter.
397
398 Some examples are:
399
400 * `/nodes/{node}`: Access to {pve} server machines
401 * `/vms`: Covers all VMs
402 * `/vms/{vmid}`: Access to specific VMs
403 * `/storage/{storeid}`: Access to a storages
404 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
405 * `/access/groups`: Group administration
406 * `/access/realms/{realmid}`: Administrative access to realms
407
408
409 Inheritance
410 ^^^^^^^^^^^
411
412 As mentioned earlier, object paths form a file system like tree, and
413 permissions can be inherited down that tree (the propagate flag is set
414 by default). We use the following inheritance rules:
415
416 * Permissions for individual users always replace group permissions.
417 * Permissions for groups apply when the user is member of that group.
418 * Permissions replace the ones inherited from an upper level.
419
420
421 [[pveum_pools]]
422 Pools
423 ~~~~~
424
425 Pools can be used to group a set of virtual machines and data
426 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
427 which are inherited to all pool members. This is a great way simplify
428 access control.
429
430
431 What permission do I need?
432 ~~~~~~~~~~~~~~~~~~~~~~~~~~
433
434 The required API permissions are documented for each individual
435 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
436
437 The permissions are specified as a list which can be interpreted as a
438 tree of logic and access-check functions:
439
440 `["and", <subtests>...]` and `["or", <subtests>...]`::
441 Each(`and`) or any(`or`) further element in the current list has to be true.
442
443 `["perm", <path>, [ <privileges>... ], <options>...]`::
444 The `path` is a templated parameter (see
445 <<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
446 option is used, any) of the listed
447 privileges must be allowed on the specified path. If a `require-param`
448 option is specified, then its specified parameter is required even if the
449 API call's schema otherwise lists it as being optional.
450
451 `["userid-group", [ <privileges>... ], <options>...]`::
452 The caller must have any of the listed privileges on `/access/groups`. In
453 addition there are two possible checks depending on whether the
454 `groups_param` option is set:
455 +
456 * `groups_param` is set: The API call has a non-optional `groups` parameter
457 and the caller must have any of the listed privileges on all of the listed
458 groups.
459 * `groups_param` is not set: The user passed via the `userid` parameter
460 must exist and be part of a group on which the caller has any of the listed
461 privileges (via the `/access/groups/<group>` path).
462
463 `["userid-param", "self"]`::
464 The value provided for the API call's `userid` parameter must refer to the
465 user performing the action. (Usually in conjunction with `or`, to allow
466 users to perform an action on themselves even if they don't have elevated
467 privileges.)
468
469 `["userid-param", "Realm.AllocateUser"]`::
470 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
471 `<realm>` referring to the realm of the user passed via the `userid`
472 parameter. Note that the user does not need to exist in order to be
473 associated with a realm, since user IDs are passed in the form of
474 `<username>@<realm>`.
475
476 `["perm-modify", <path>]`::
477 The `path` is a templated parameter (see
478 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
479 `Permissions.Modify` privilege, or,
480 depending on the path, the following privileges as a possible substitute:
481 +
482 * `/storage/...`: additionally requires 'Datastore.Allocate`
483 * `/vms/...`: additionally requires 'VM.Allocate`
484 * `/pool/...`: additionally requires 'Pool.Allocate`
485 +
486 If the path is empty, `Permission.Modify` on `/access` is required.
487
488 Command Line Tool
489 -----------------
490
491 Most users will simply use the GUI to manage users. But there is also
492 a full featured command line tool called `pveum` (short for ``**P**roxmox
493 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
494 line tools are wrappers around the API, so you can also access those
495 function through the REST API.
496
497 Here are some simple usage examples. To show help type:
498
499 [source,bash]
500  pveum
501
502 or (to show detailed help about a specific command)
503
504 [source,bash]
505  pveum help useradd
506
507 Create a new user:
508
509 [source,bash]
510  pveum useradd testuser@pve -comment "Just a test"
511
512 Set or Change the password (not all realms support that):
513
514 [source,bash]
515  pveum passwd testuser@pve
516
517 Disable a user:
518
519 [source,bash]
520  pveum usermod testuser@pve -enable 0
521
522 Create a new group:
523
524 [source,bash]
525  pveum groupadd testgroup
526
527 Create a new role:
528
529 [source,bash]
530  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
531
532
533 Real World Examples
534 -------------------
535
536
537 Administrator Group
538 ~~~~~~~~~~~~~~~~~~~
539
540 One of the most wanted features was the ability to define a group of
541 users with full administrator rights (without using the root account).
542
543 Define the group:
544
545 [source,bash]
546  pveum groupadd admin -comment "System Administrators"
547
548 Then add the permission:
549
550 [source,bash]
551  pveum aclmod / -group admin -role Administrator
552
553 You can finally add users to the new 'admin' group:
554
555 [source,bash]
556  pveum usermod testuser@pve -group admin
557
558
559 Auditors
560 ~~~~~~~~
561
562 You can give read only access to users by assigning the `PVEAuditor`
563 role to users or groups.
564
565 Example1: Allow user `joe@pve` to see everything
566
567 [source,bash]
568  pveum aclmod / -user joe@pve -role PVEAuditor
569
570 Example1: Allow user `joe@pve` to see all virtual machines
571
572 [source,bash]
573  pveum aclmod /vms -user joe@pve -role PVEAuditor
574
575
576 Delegate User Management
577 ~~~~~~~~~~~~~~~~~~~~~~~~
578
579 If you want to delegate user management to user `joe@pve` you can do
580 that with:
581
582 [source,bash]
583  pveum aclmod /access -user joe@pve -role PVEUserAdmin
584
585 User `joe@pve` can now add and remove users, change passwords and
586 other user attributes. This is a very powerful role, and you most
587 likely want to limit that to selected realms and groups. The following
588 example allows `joe@pve` to modify users within realm `pve` if they
589 are members of group `customers`:
590
591 [source,bash]
592  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
593  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
594
595 NOTE: The user is able to add other users, but only if they are
596 members of group `customers` and within realm `pve`.
597
598
599 Pools
600 ~~~~~
601
602 An enterprise is usually structured into several smaller departments,
603 and it is common that you want to assign resources to them and
604 delegate management tasks. A pool is simply a set of virtual machines
605 and data stores. You can create pools on the GUI. After that you can
606 add resources to the pool (VMs, Storage).
607
608 You can also assign permissions to the pool. Those permissions are
609 inherited to all pool members.
610
611 Lets assume you have a software development department, so we first
612 create a group
613
614 [source,bash]
615  pveum groupadd developers -comment "Our software developers"
616
617 Now we create a new user which is a member of that group
618
619 [source,bash]
620  pveum useradd developer1@pve -group developers -password
621
622 NOTE: The -password parameter will prompt you for a password
623
624 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
625
626 [source,bash]
627  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
628
629 Our software developers can now administrate the resources assigned to
630 that pool.
631
632
633 ifdef::manvolnum[]
634 include::pve-copyright.adoc[]
635 endif::manvolnum[]
636