Fixed some typos and slight language improvements
[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 Two factor authentication
151 -------------------------
152
153 Each realm can optionally be secured additionally by two factor
154 authentication. This can be done by selecting one of the available methods
155 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
156 When a realm has TFA enabled it becomes a requirement and only users with
157 configured TFA will be able to login.
158
159 Currently there are two methods available:
160
161 Time based OATH (TOTP)::
162 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
163 with the user's configured key. The time step and password length
164 parameters are configured.
165 +
166 A user can have multiple keys configured (separated by spaces), and the
167 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
168 +
169 {pve} provides a key generation tool (`oathkeygen`) which prints out a
170 random key in Base32 notation which can be used directly with various OTP
171 tools, such as the `oathtool` command line tool, the Google authenticator
172 or FreeOTP Android apps.
173
174 YubiKey OTP::
175 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
176 server URL must be configured, and users must have a YubiKey available. In
177 order to get the key ID from a YubiKey, you can trigger the YubiKey once
178 after connecting it to USB and copy the first 12 characters of the typed
179 password into the user's 'Key IDs' field.
180 +
181 Please refer to the
182 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
183 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
184 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
185 host your own verification server].
186
187
188 [[pveum_permission_management]]
189 Permission Management
190 ---------------------
191
192 In order for a user to perform an action (such as listing, modifying or
193 deleting a parts of a VM configuration), the user needs to have the
194 appropriate permissions.
195
196 {pve} uses a role and path based permission management system. An entry in
197 the permissions table allows a user or group to take on a specific role
198 when accessing an 'object' or 'path'. This means an such an access rule can
199 be represented as a triple of '(path, user, role)' or '(path, group,
200 role)', with the role containing a set of allowed actions, and the path
201 representing the target of these actions.
202
203
204 [[pveum_roles]]
205 Roles
206 ~~~~~
207
208 A role is simply a list of privileges. Proxmox VE comes with a number
209 of predefined roles which satisfies most needs.
210
211 * `Administrator`: has all privileges
212 * `NoAccess`: has no privileges (used to forbid access)
213 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
214 * `PVEAuditor`: read only access
215 * `PVEDatastoreAdmin`: create and allocate backup space and templates
216 * `PVEDatastoreUser`: allocate backup space and view storage
217 * `PVEPoolAdmin`: allocate pools
218 * `PVESysAdmin`: User ACLs, audit, system console and system logs
219 * `PVETemplateUser`: view and clone templates
220 * `PVEUserAdmin`: user administration
221 * `PVEVMAdmin`: fully administer VMs
222 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
223
224 You can see the whole set of predefined roles on the GUI.
225
226 Adding new roles can be done via both GUI and the command line, like
227 this:
228
229 [source,bash]
230 ----
231 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
232 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
233 ----
234
235
236 Privileges
237 ~~~~~~~~~~
238
239 A privilege is the right to perform a specific action. To simplify
240 management, lists of privileges are grouped into roles, which can then
241 be used in the permission table. Note that privileges cannot directly be
242 assigned to users and paths without being part of a role.
243
244 We currently use the following privileges:
245
246 Node / System related privileges::
247
248 * `Permissions.Modify`: modify access permissions
249 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
250 * `Sys.Console`: console access to Node
251 * `Sys.Syslog`: view Syslog
252 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
253 * `Sys.Modify`: create/remove/modify node network parameters
254 * `Group.Allocate`: create/remove/modify groups
255 * `Pool.Allocate`: create/remove/modify a pool
256 * `Realm.Allocate`: create/remove/modify authentication realms
257 * `Realm.AllocateUser`: assign user to a realm
258 * `User.Modify`: create/remove/modify user access and details.
259
260 Virtual machine related privileges::
261
262 * `VM.Allocate`: create/remove new VM to server inventory
263 * `VM.Migrate`: migrate VM to alternate server on cluster
264 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
265 * `VM.Console`: console access to VM
266 * `VM.Monitor`: access to VM monitor (kvm)
267 * `VM.Backup`: backup/restore VMs
268 * `VM.Audit`: view VM config
269 * `VM.Clone`: clone/copy a VM
270 * `VM.Config.Disk`: add/modify/delete Disks 
271 * `VM.Config.CDROM`: eject/change CDROM
272 * `VM.Config.CPU`: modify CPU settings
273 * `VM.Config.Memory`: modify Memory settings
274 * `VM.Config.Network`: add/modify/delete Network devices
275 * `VM.Config.HWType`: modify emulated HW type
276 * `VM.Config.Options`: modify any other VM configuration
277 * `VM.Snapshot`: create/remove VM snapshots
278
279 Storage related privileges::
280
281 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
282 * `Datastore.AllocateSpace`: allocate space on a datastore
283 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images 
284 * `Datastore.Audit`: view/browse a datastore
285
286
287 Objects and Paths
288 ~~~~~~~~~~~~~~~~~
289
290 Access permissions are assigned to objects, such as a virtual machines,
291 storages or pools of resources.
292 We use file system like paths to address these objects. These paths form a
293 natural tree, and permissions of higher levels (shorter path) can
294 optionally be propagated down within this hierarchy.
295
296 [[pveum_templated_paths]]
297 Paths can be templated. When an API call requires permissions on a
298 templated path, the path may contain references to parameters of the API
299 call. These references are specified in curly braces. Some parameters are
300 implicitly taken from the API call's URI. For instance the permission path
301 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
302 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
303 refers to the method's `path` parameter.
304
305 Some examples are:
306
307 * `/nodes/{node}`: Access to {pve} server machines
308 * `/vms`: Covers all VMs
309 * `/vms/{vmid}`: Access to specific VMs
310 * `/storage/{storeid}`: Access to a storages
311 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
312 * `/access/groups`: Group administration
313 * `/access/realms/{realmid}`: Administrative access to realms
314
315
316 Inheritance
317 ^^^^^^^^^^^
318
319 As mentioned earlier, object paths form a file system like tree, and
320 permissions can be inherited down that tree (the propagate flag is set
321 by default). We use the following inheritance rules:
322
323 * Permissions for individual users always replace group permissions.
324 * Permissions for groups apply when the user is member of that group.
325 * Permissions replace the ones inherited from an upper level.
326
327
328 [[pveum_pools]]
329 Pools
330 ~~~~~
331
332 Pools can be used to group a set of virtual machines and data
333 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
334 which are inherited to all pool members. This is a great way simplify
335 access control.
336
337
338 What permission do I need?
339 ~~~~~~~~~~~~~~~~~~~~~~~~~~
340
341 The required API permissions are documented for each individual
342 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
343
344 The permissions are specified as a list which can be interpreted as a
345 tree of logic and access-check functions:
346
347 `["and", <subtests>...]` and `["or", <subtests>...]`::
348 Each(`and`) or any(`or`) further element in the current list has to be true.
349
350 `["perm", <path>, [ <privileges>... ], <options>...]`::
351 The `path` is a templated parameter (see
352 <<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
353 option is used, any) of the listed
354 privileges must be allowed on the specified path. If a `require-param`
355 option is specified, then its specified parameter is required even if the
356 API call's schema otherwise lists it as being optional.
357
358 `["userid-group", [ <privileges>... ], <options>...]`::
359 The caller must have any of the listed privileges on `/access/groups`. In
360 addition there are two possible checks depending on whether the
361 `groups_param` option is set:
362 +
363 * `groups_param` is set: The API call has a non-optional `groups` parameter
364 and the caller must have any of the listed privileges on all of the listed
365 groups.
366 * `groups_param` is not set: The user passed via the `userid` parameter
367 must exist and be part of a group on which the caller has any of the listed
368 privileges (via the `/access/groups/<group>` path).
369
370 `["userid-param", "self"]`::
371 The value provided for the API call's `userid` parameter must refer to the
372 user performing the action. (Usually in conjunction with `or`, to allow
373 users to perform an action on themselves even if they don't have elevated
374 privileges.)
375
376 `["userid-param", "Realm.AllocateUser"]`::
377 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
378 `<realm>` referring to the realm of the user passed via the `userid`
379 parameter. Note that the user does not need to exist in order to be
380 associated with a realm, since user IDs are passed in the form of
381 `<username>@<realm>`.
382
383 `["perm-modify", <path>]`::
384 The `path` is a templated parameter (see
385 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
386 `Permissions.Modify` privilege, or,
387 depending on the path, the following privileges as a possible substitute:
388 +
389 * `/storage/...`: additionally requires 'Datastore.Allocate`
390 * `/vms/...`: additionally requires 'VM.Allocate`
391 * `/pool/...`: additionally requires 'Pool.Allocate`
392 +
393 If the path is empty, `Permission.Modify` on `/access` is required.
394
395 Command Line Tool
396 -----------------
397
398 Most users will simply use the GUI to manage users. But there is also
399 a full featured command line tool called `pveum` (short for ``**P**roxmox
400 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
401 line tools are wrappers around the API, so you can also access those
402 function through the REST API.
403
404 Here are some simple usage examples. To show help type:
405
406 [source,bash]
407  pveum
408
409 or (to show detailed help about a specific command)
410
411 [source,bash]
412  pveum help useradd
413
414 Create a new user:
415
416 [source,bash]
417  pveum useradd testuser@pve -comment "Just a test"
418
419 Set or Change the password (not all realms support that):
420
421 [source,bash]
422  pveum passwd testuser@pve
423
424 Disable a user:
425
426 [source,bash]
427  pveum usermod testuser@pve -enable 0
428
429 Create a new group:
430
431 [source,bash]
432  pveum groupadd testgroup
433
434 Create a new role:
435
436 [source,bash]
437  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
438
439
440 Real World Examples
441 -------------------
442
443
444 Administrator Group
445 ~~~~~~~~~~~~~~~~~~~
446
447 One of the most wanted features was the ability to define a group of
448 users with full administrator rights (without using the root account).
449
450 Define the group:
451
452 [source,bash]
453  pveum groupadd admin -comment "System Administrators"
454
455 Then add the permission:
456
457 [source,bash]
458  pveum aclmod / -group admin -role Administrator
459
460 You can finally add users to the new 'admin' group:
461
462 [source,bash]
463  pveum usermod testuser@pve -group admin
464
465
466 Auditors
467 ~~~~~~~~
468
469 You can give read only access to users by assigning the `PVEAuditor`
470 role to users or groups.
471
472 Example1: Allow user `joe@pve` to see everything
473
474 [source,bash]
475  pveum aclmod / -user joe@pve -role PVEAuditor
476
477 Example1: Allow user `joe@pve` to see all virtual machines
478
479 [source,bash]
480  pveum aclmod /vms -user joe@pve -role PVEAuditor
481
482
483 Delegate User Management
484 ~~~~~~~~~~~~~~~~~~~~~~~~
485
486 If you want to delegate user management to user `joe@pve` you can do
487 that with:
488
489 [source,bash]
490  pveum aclmod /access -user joe@pve -role PVEUserAdmin
491
492 User `joe@pve` can now add and remove users, change passwords and
493 other user attributes. This is a very powerful role, and you most
494 likely want to limit that to selected realms and groups. The following
495 example allows `joe@pve` to modify users within realm `pve` if they
496 are members of group `customers`:
497
498 [source,bash]
499  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
500  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
501
502 NOTE: The user is able to add other users, but only if they are
503 members of group `customers` and within realm `pve`.
504
505
506 Pools
507 ~~~~~
508
509 An enterprise is usually structured into several smaller departments,
510 and it is common that you want to assign resources to them and
511 delegate management tasks. A pool is simply a set of virtual machines
512 and data stores. You can create pools on the GUI. After that you can
513 add resources to the pool (VMs, Storage).
514
515 You can also assign permissions to the pool. Those permissions are
516 inherited to all pool members.
517
518 Lets assume you have a software development department, so we first
519 create a group
520
521 [source,bash]
522  pveum groupadd developers -comment "Our software developers"
523
524 Now we create a new user which is a member of that group
525
526 [source,bash]
527  pveum useradd developer1@pve -group developers -password
528
529 NOTE: The -password parameter will prompt you for a password
530
531 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
532
533 [source,bash]
534  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
535
536 Our software developers can now administrate the resources assigned to
537 that pool.
538
539
540 ifdef::manvolnum[]
541 include::pve-copyright.adoc[]
542 endif::manvolnum[]
543