Reorder users and groups section above realms section.
[pve-docs.git] / pveum.adoc
1 ifdef::manvolnum[]
2 PVE({manvolnum})
3 ================
4 include::attributes.txt[]
5
6 NAME
7 ----
8
9 pveum - Proxmox VE User Manager
10
11
12 SYNOPSYS
13 --------
14
15 include::pveum.1-synopsis.adoc[]
16
17
18 DESCRIPTION
19 -----------
20 endif::manvolnum[]
21
22 ifndef::manvolnum[]
23 User Management
24 ===============
25 include::attributes.txt[]
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 Users
39 -----
40
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>`.
46
47 Each user entry in this file contains the following information:
48
49 * First name
50 * Last name
51 * E-mail address
52 * Group memberships
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
57
58
59 System administrator
60 ~~~~~~~~~~~~~~~~~~~~
61
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.
66
67
68 Groups
69 ~~~~~~
70
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.
75
76
77 [[authentication-realms]]
78 Authentication Realms
79 ---------------------
80
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:
84
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.
89 +
90 [source,bash]
91 ----
92 useradd heinz
93 passwd heinz
94 groupadd watchman
95 usermod -a -G watchman heinz
96 ----
97
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.
105
106 LDAP::
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.
110 +
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'
113 (`user_attr`) field.
114 +
115 For instance, if a user is represented via the
116 following ldif dataset:
117 +
118 ----
119 # user1 of People at ldap-test.com
120 dn: uid=user1,ou=People,dc=ldap-test,dc=com
121 objectClass: top
122 objectClass: person
123 objectClass: organizationalPerson
124 objectClass: inetOrgPerson
125 uid: user1
126 cn: Test User 1
127 sn: Testers
128 description: This is the first test user.
129 ----
130 +
131 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
132 attribute would be `uid`.
133 +
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.
140
141 Microsoft Active Directory::
142
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.
146
147
148 Two factor authentication
149 -------------------------
150
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.
156
157 Currently there are two methods available:
158
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.
163 +
164 A user can have multiple keys configured (separated by spaces), and the
165 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
166 +
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.
171
172 YubiKey OTP::
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.
178 +
179 Please refer to the
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].
184
185
186 Terms and Definitions
187 ---------------------
188
189
190 Objects and Paths
191 ~~~~~~~~~~~~~~~~~
192
193 Access permissions are assigned to objects, such as a virtual machines
194 (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
195 resources (`/pool/{poolname}`). We use file system like paths to
196 address those objects. Those paths form a natural tree, and
197 permissions can be inherited down that hierarchy.
198
199
200 Privileges
201 ~~~~~~~~~~
202
203 A privilege is the right to perform a specific action. To simplify
204 management, lists of privileges are grouped into roles, which can then
205 be uses to set permissions.
206
207 We currently use the following privileges:
208
209 Node / System related privileges::
210
211 * `Permissions.Modify`: modify access permissions
212 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
213 * `Sys.Console`: console access to Node
214 * `Sys.Syslog`: view Syslog
215 * `Sys.Audit`: view node status/config
216 * `Sys.Modify`: create/remove/modify node network parameters
217 * `Group.Allocate`: create/remove/modify groups
218 * `Pool.Allocate`: create/remove/modify a pool
219 * `Realm.Allocate`: create/remove/modify authentication realms
220 * `Realm.AllocateUser`: assign user to a realm
221 * `User.Modify`: create/remove/modify user access and details.
222
223 Virtual machine related privileges::
224
225 * `VM.Allocate`: create/remove new VM to server inventory
226 * `VM.Migrate`: migrate VM to alternate server on cluster
227 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
228 * `VM.Console`: console access to VM
229 * `VM.Monitor`: access to VM monitor (kvm)
230 * `VM.Backup`: backup/restore VMs
231 * `VM.Audit`: view VM config
232 * `VM.Clone`: clone/copy a VM
233 * `VM.Config.Disk`: add/modify/delete Disks
234 * `VM.Config.CDROM`: eject/change CDROM
235 * `VM.Config.CPU`: modify CPU settings
236 * `VM.Config.Memory`: modify Memory settings
237 * `VM.Config.Network`: add/modify/delete Network devices
238 * `VM.Config.HWType`: modify emulated HW type
239 * `VM.Config.Options`: modify any other VM configuration
240 * `VM.Snapshot`: create/remove VM snapshots
241
242 Storage related privileges::
243
244 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
245 * `Datastore.AllocateSpace`: allocate space on a datastore
246 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
247 * `Datastore.Audit`: view/browse a datastore
248
249
250 Roles
251 ~~~~~
252
253 A role is simply a list of privileges. Proxmox VE comes with a number
254 of predefined roles which satisfies most needs.
255
256 * `Administrator`: has all privileges
257 * `NoAccess`: has no privileges (used to forbid access)
258 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
259 * `PVEAuditor`: read only access
260 * `PVEDatastoreAdmin`: create and allocate backup space and templates
261 * `PVEDatastoreUser`: allocate backup space and view storage
262 * `PVEPoolAdmin`: allocate pools
263 * `PVESysAdmin`: User ACLs, audit, system console and system logs
264 * `PVETemplateUser`: view and clone templates
265 * `PVEUserAdmin`: user administration
266 * `PVEVMAdmin`: fully administer VMs
267 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
268
269 You can see the whole set of predefined roles on the GUI.
270
271 Adding new roles using the CLI:
272
273 [source,bash]
274 ----
275 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
276 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
277 ----
278
279
280 Permissions
281 ~~~~~~~~~~~
282
283 Permissions are the way we control access to objects. In technical
284 terms they are simply a triple containing `<path,user,role>`. This
285 concept is also known as access control lists. Each permission
286 specifies a subject (user or group) and a role (set of privileges) on
287 a specific path.
288
289 When a subject requests an action on an object, the framework looks up
290 the roles assigned to that subject (using the object path). The set of
291 roles defines the granted privileges.
292
293
294 Inheritance
295 ^^^^^^^^^^^
296
297 As mentioned earlier, object paths form a file system like tree, and
298 permissions can be inherited down that tree (the propagate flag is set
299 by default). We use the following inheritance rules:
300
301 * Permissions for individual users always replace group permissions.
302 * Permissions for groups apply when the user is member of that group.
303 * Permissions replace the ones inherited from an upper level.
304
305
306 Pools
307 ~~~~~
308
309 Pools can be used to group a set of virtual machines and data
310 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
311 which are inherited to all pool members. This is a great way simplify
312 access control.
313
314
315 What permission do I need?
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~
317
318 The required API permissions are documented for each individual
319 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
320
321 The permissions are specified as a list which can be interpreted as a
322 tree of logic and access-check functions:
323
324 `["and", <subtests>...]` and `["or", <subtests>...]`::
325 Each(`and`) or any(`or`) further element in the current list has to be true.
326
327 `["perm", <path>, [ <privileges>... ], <options>...]`::
328 The `path` is a templated parameter (see <<templated-paths,Objects and
329 Paths>>). All (or , if the `any` option is used, any) of the listed
330 privileges must be allowed on the specified path. If a `require-param`
331 option is specified, then its specified parameter is required even if the
332 API call's schema otherwise lists it as being optional.
333
334 `["userid-group", [ <privileges>... ], <options>...]`::
335 The callermust have any of the listed privileges on `/access/groups`. In
336 addition there are two possible checks depending on whether the
337 `groups_param` option is set:
338 +
339 * `groups_param` is set: The API call has a non-optional `groups` parameter
340 and the caller must have any of the listed privileges on all of the listed
341 groups.
342 * `groups_param` is not set: The user passed via the `userid` parameter
343 must exist and be part of a group on which the caller has any of the listed
344 privileges (via the `/access/groups/<group>` path).
345
346 `["userid-param", "self"]`::
347 The value provided for the API call's `userid` parameter must refer to the
348 user performing the action. (Usually in conjunction with `or`, to allow
349 users to perform an action on themselves even if they don't have elevated
350 privileges.)
351
352 `["userid-param", "Realm.AllocateUser"]`::
353 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
354 `<realm>` refering to the realm of the user passed via the `userid`
355 parameter. Note that the user does not need to exist in order to be
356 associated with a realm, since user IDs are passed in the form of
357 `<username>@<realm>`.
358
359 `["perm-modify", <path>]`::
360 The `path` is a templated parameter (see <<templated-paths,Objects and
361 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
362 depending on the path, the following privileges as a possible substitute:
363 +
364 * `/storage/...`: additionally requires 'Datastore.Allocate`
365 * `/vms/...`: additionally requires 'VM.Allocate`
366 * `/pool/...`: additionally requires 'Pool.Allocate`
367 +
368 If the path is empty, `Permission.Modify` on `/access` is required.
369
370 Command Line Tool
371 -----------------
372
373 Most users will simply use the GUI to manage users. But there is also
374 a full featured command line tool called `pveum` (short for ``**P**roxmox
375 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
376 line tools are wrappers around the API, so you can also access those
377 function through the REST API.
378
379 Here are some simple usage examples. To show help type:
380
381 [source,bash]
382 pveum
383
384 or (to show detailed help about a specific command)
385
386 [source,bash]
387 pveum help useradd
388
389 Create a new user:
390
391 [source,bash]
392 pveum useradd testuser@pve -comment "Just a test"
393
394 Set or Change the password (not all realms support that):
395
396 [source,bash]
397 pveum passwd testuser@pve
398
399 Disable a user:
400
401 [source,bash]
402 pveum usermod testuser@pve -enable 0
403
404 Create a new group:
405
406 [source,bash]
407 pveum groupadd testgroup
408
409 Create a new role:
410
411 [source,bash]
412 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
413
414
415 Real World Examples
416 -------------------
417
418
419 Administrator Group
420 ~~~~~~~~~~~~~~~~~~~
421
422 One of the most wanted features was the ability to define a group of
423 users with full administrator rights (without using the root account).
424
425 Define the group:
426
427 [source,bash]
428 pveum groupadd admin -comment "System Administrators"
429
430 Then add the permission:
431
432 [source,bash]
433 pveum aclmod / -group admin -role Administrator
434
435 You can finally add users to the new 'admin' group:
436
437 [source,bash]
438 pveum usermod testuser@pve -group admin
439
440
441 Auditors
442 ~~~~~~~~
443
444 You can give read only access to users by assigning the `PVEAuditor`
445 role to users or groups.
446
447 Example1: Allow user `joe@pve` to see everything
448
449 [source,bash]
450 pveum aclmod / -user joe@pve -role PVEAuditor
451
452 Example1: Allow user `joe@pve` to see all virtual machines
453
454 [source,bash]
455 pveum aclmod /vms -user joe@pve -role PVEAuditor
456
457
458 Delegate User Management
459 ~~~~~~~~~~~~~~~~~~~~~~~~
460
461 If you want to delegate user managenent to user `joe@pve` you can do
462 that with:
463
464 [source,bash]
465 pveum aclmod /access -user joe@pve -role PVEUserAdmin
466
467 User `joe@pve` can now add and remove users, change passwords and
468 other user attributes. This is a very powerful role, and you most
469 likely want to limit that to selected realms and groups. The following
470 example allows `joe@pve` to modify users within realm `pve` if they
471 are members of group `customers`:
472
473 [source,bash]
474 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
475 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
476
477 NOTE: The user is able to add other users, but only if they are
478 members of group `customers` and within realm `pve`.
479
480
481 Pools
482 ~~~~~
483
484 An enterprise is usually structured into several smaller departments,
485 and it is common that you want to assign resources to them and
486 delegate management tasks. A pool is simply a set of virtual machines
487 and data stores. You can create pools on the GUI. After that you can
488 add resources to the pool (VMs, Storage).
489
490 You can also assign permissions to the pool. Those permissions are
491 inherited to all pool members.
492
493 Lets assume you have a software development department, so we first
494 create a group
495
496 [source,bash]
497 pveum groupadd developers -comment "Our software developers"
498
499 Now we create a new user which is a member of that group
500
501 [source,bash]
502 pveum useradd developer1@pve -group developers -password
503
504 NOTE: The -password parameter will prompt you for a password
505
506 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
507
508 [source,bash]
509 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
510
511 Our software developers can now administrate the resources assigned to
512 that pool.
513
514
515 ifdef::manvolnum[]
516 include::pve-copyright.adoc[]
517 endif::manvolnum[]
518