reorder the roles section
[pve-docs.git] / pveum.adoc
CommitLineData
3c8533f2
DM
1ifdef::manvolnum[]
2PVE({manvolnum})
3================
38fd0958 4include::attributes.txt[]
3c8533f2
DM
5
6NAME
7----
8
9pveum - Proxmox VE User Manager
10
11
12SYNOPSYS
13--------
14
15include::pveum.1-synopsis.adoc[]
16
17
18DESCRIPTION
19-----------
20endif::manvolnum[]
21
22ifndef::manvolnum[]
23User Management
24===============
38fd0958 25include::attributes.txt[]
3c8533f2
DM
26endif::manvolnum[]
27
28// Copied from pve wiki: Revision as of 16:10, 27 October 2015
29
5462c161
WB
30Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
31an integrated Proxmox VE authentication server, LDAP, Microsoft Active
32Directory.
3c8533f2
DM
33
34By using the role based user- and permission management for all
5eba0743
FG
35objects (VMs, storages, nodes, etc.) granular access can be defined.
36
3c8533f2 37
c80b9ee6
WB
38Users
39-----
40
41{pve} stores user attributes in `/etc/pve/user.cfg`.
42Passwords are not stored here, users are instead associated with
43<<authentication-realms,authentication realms>> described below.
44Therefore a user is internally often identified by its name and
45realm in the form `<userid>@<realm>`.
46
47Each 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
59System administrator
60~~~~~~~~~~~~~~~~~~~~
61
62The system's root user can always log in via the Linux PAM realm and is an
63unconfined administrator. This user cannot be deleted, but attributes can
64still be changed and system mails will be sent to the email address
65assigned to this user.
66
67
68Groups
69~~~~~~
70
71Each user can be member of several groups. Groups are the preferred
72way to organize access permissions. You should always grant permission
73to groups instead of using individual users. That way you will get a
74much shorter access control list which is easier to handle.
75
76
d6614202 77[[authentication-realms]]
3c8533f2
DM
78Authentication Realms
79---------------------
80
d6614202
WB
81As {pve} users are just counterparts for users existing on some external
82realm, the realms have to be configured in `/etc/pve/domains.cfg`.
83The following realms (authentication methods) are available:
3c8533f2
DM
84
85Linux PAM standard authentication::
d6614202
WB
86In this case a system user has to exist (eg. created via the `adduser`
87command) on all nodes the user is allowed to login, and the user
88authenticates with their usual system password.
89+
3c8533f2
DM
90[source,bash]
91----
92useradd heinz
93passwd heinz
94groupadd watchman
95usermod -a -G watchman heinz
96----
97
98Proxmox VE authentication server::
d6614202
WB
99This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
100Password are encrypted using the SHA-256 hash method.
101This is the most convenient method for for small (or even medium)
102installations 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
104change their own passwords via the GUI.
105
106LDAP::
107It is possible to authenticate users via an LDAP server (eq.
108openldap). The server and an optional fallback server can be
109configured and the connection can be encrypted via SSL.
110+
111Users are searched under a 'Base Domain Name' (`base_dn`), with the
112user name found in the attribute specified in the 'User Attribute Name'
113(`user_attr`) field.
114+
115For instance, if a user is represented via the
116following ldif dataset:
117+
118----
119# user1 of People at ldap-test.com
120dn: uid=user1,ou=People,dc=ldap-test,dc=com
121objectClass: top
122objectClass: person
123objectClass: organizationalPerson
124objectClass: inetOrgPerson
125uid: user1
126cn: Test User 1
127sn: Testers
128description: This is the first test user.
129----
130+
131The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
132attribute would be `uid`.
133+
134If {pve} needs to authenticate (bind) to the ldap server before being
135able to query and authenticate users, a bind domain name can be
136configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
137password 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
139single line containing the raw password.
140
141Microsoft Active Directory::
3c8533f2 142
d6614202
WB
143A server and authentication domain need to be specified. Like with
144ldap an optional fallback server, optional port, and SSL
145encryption can be configured.
3c8533f2 146
5eba0743 147
9e8f2770
WB
148Two factor authentication
149-------------------------
150
151Each realm can optionally be secured additionally by two factor
152authentication. This can be done by selecting one of the available methods
153via the 'TFA' dropdown box when adding or editing an Authentication Realm.
154When a realm has TFA enabled it becomes a requirement and only users with
155configured TFA will be able to login.
156
157Currently there are two methods available:
158
159Time based OATH (TOTP)::
160This uses the standard HMAC-SHA1 algorithm where the current time is hashed
161with the user's configured key. The time step and password length
162parameters are configured.
163+
164A user can have multiple keys configured (separated by spaces), and the
165keys can be specified in Base32 (RFC3548) or hexadecimal notation.
166+
167{pve} provides a key generation tool (`oathkeygen`) which prints out a
168random key in Base32 notation which can be used directly with various OTP
169tools, such as the `oathtool` command line tool, the Google authenticator
170or FreeOTP Android apps.
171
172YubiKey OTP::
173For authenticating via a YubiKey a Yubico API ID, API KEY and validation
174server URL must be configured, and users must have a YubiKey available. In
175order to get the key ID from a YubiKey, you can trigger the YubiKey once
176after connecting it to USB and copy the first 12 characters of the typed
177password into the user's 'Key IDs' field.
178+
179Please refer to the
180https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
181https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
182https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
183host your own verification server].
184
185
04f44730 186Permission Management
3c8533f2
DM
187---------------------
188
04f44730
WB
189In order for a user to perform an action (such as listing, modifying or
190deleting a parts of a VM configuration), the user needs to have the
191appropriate permissions.
192
193{pve} uses a role and path based permission management system. An entry in
194the permissions table allows a user or group to take on a specific role
195when accessing an 'object' or 'path'. This means an such an access rule can
196be represented as a triple of '(path, user, role)' or '(path, group,
197role)', with the role containing a set of allowed actions, and the path
198representing the target of these actions.
199
5eba0743 200
853d288b
WB
201Roles
202~~~~~
203
204A role is simply a list of privileges. Proxmox VE comes with a number
205of predefined roles which satisfies most needs.
206
207* `Administrator`: has all privileges
208* `NoAccess`: has no privileges (used to forbid access)
209* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
210* `PVEAuditor`: read only access
211* `PVEDatastoreAdmin`: create and allocate backup space and templates
212* `PVEDatastoreUser`: allocate backup space and view storage
213* `PVEPoolAdmin`: allocate pools
214* `PVESysAdmin`: User ACLs, audit, system console and system logs
215* `PVETemplateUser`: view and clone templates
216* `PVEUserAdmin`: user administration
217* `PVEVMAdmin`: fully administer VMs
218* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
219
220You can see the whole set of predefined roles on the GUI.
221
222Adding new roles can currently only be done from the command line, like
223this:
224
225[source,bash]
226----
227pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
228pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
229----
230
231
3c8533f2
DM
232Objects and Paths
233~~~~~~~~~~~~~~~~~
234
235Access permissions are assigned to objects, such as a virtual machines
8c1189b6
FG
236(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
237resources (`/pool/{poolname}`). We use file system like paths to
3c8533f2
DM
238address those objects. Those paths form a natural tree, and
239permissions can be inherited down that hierarchy.
240
5eba0743 241
3c8533f2
DM
242Privileges
243~~~~~~~~~~
244
245A privilege is the right to perform a specific action. To simplify
246management, lists of privileges are grouped into roles, which can then
247be uses to set permissions.
248
249We currently use the following privileges:
250
251Node / System related privileges::
252
253* `Permissions.Modify`: modify access permissions
254* `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
255* `Sys.Console`: console access to Node
256* `Sys.Syslog`: view Syslog
257* `Sys.Audit`: view node status/config
258* `Sys.Modify`: create/remove/modify node network parameters
259* `Group.Allocate`: create/remove/modify groups
260* `Pool.Allocate`: create/remove/modify a pool
261* `Realm.Allocate`: create/remove/modify authentication realms
262* `Realm.AllocateUser`: assign user to a realm
263* `User.Modify`: create/remove/modify user access and details.
264
265Virtual machine related privileges::
266
267* `VM.Allocate`: create/remove new VM to server inventory
268* `VM.Migrate`: migrate VM to alternate server on cluster
269* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
270* `VM.Console`: console access to VM
271* `VM.Monitor`: access to VM monitor (kvm)
272* `VM.Backup`: backup/restore VMs
273* `VM.Audit`: view VM config
274* `VM.Clone`: clone/copy a VM
275* `VM.Config.Disk`: add/modify/delete Disks
276* `VM.Config.CDROM`: eject/change CDROM
277* `VM.Config.CPU`: modify CPU settings
278* `VM.Config.Memory`: modify Memory settings
279* `VM.Config.Network`: add/modify/delete Network devices
280* `VM.Config.HWType`: modify emulated HW type
281* `VM.Config.Options`: modify any other VM configuration
282* `VM.Snapshot`: create/remove VM snapshots
283
284Storage related privileges::
285
286* `Datastore.Allocate`: create/remove/modify a data store, delete volumes
287* `Datastore.AllocateSpace`: allocate space on a datastore
288* `Datastore.AllocateTemplate`: allocate/upload templates and iso images
289* `Datastore.Audit`: view/browse a datastore
290
5eba0743 291
3c8533f2
DM
292Permissions
293~~~~~~~~~~~
294
295Permissions are the way we control access to objects. In technical
296terms they are simply a triple containing `<path,user,role>`. This
297concept is also known as access control lists. Each permission
298specifies a subject (user or group) and a role (set of privileges) on
299a specific path.
300
301When a subject requests an action on an object, the framework looks up
302the roles assigned to that subject (using the object path). The set of
303roles defines the granted privileges.
304
5eba0743 305
3c8533f2
DM
306Inheritance
307^^^^^^^^^^^
308
5eba0743 309As mentioned earlier, object paths form a file system like tree, and
3c8533f2
DM
310permissions can be inherited down that tree (the propagate flag is set
311by default). We use the following inheritance rules:
312
74936daf
WB
313* Permissions for individual users always replace group permissions.
314* Permissions for groups apply when the user is member of that group.
315* Permissions replace the ones inherited from an upper level.
3c8533f2 316
5eba0743 317
3c8533f2
DM
318Pools
319~~~~~
320
321Pools can be used to group a set of virtual machines and data
8c1189b6 322stores. You can then simply set permissions on pools (`/pool/{poolid}`),
3c8533f2
DM
323which are inherited to all pool members. This is a great way simplify
324access control.
325
74936daf
WB
326
327What permission do I need?
328~~~~~~~~~~~~~~~~~~~~~~~~~~
329
330The required API permissions are documented for each individual
331method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
332
333The permissions are specified as a list which can be interpreted as a
334tree of logic and access-check functions:
335
336`["and", <subtests>...]` and `["or", <subtests>...]`::
337Each(`and`) or any(`or`) further element in the current list has to be true.
338
339`["perm", <path>, [ <privileges>... ], <options>...]`::
340The `path` is a templated parameter (see <<templated-paths,Objects and
341Paths>>). All (or , if the `any` option is used, any) of the listed
342privileges must be allowed on the specified path. If a `require-param`
343option is specified, then its specified parameter is required even if the
344API call's schema otherwise lists it as being optional.
345
346`["userid-group", [ <privileges>... ], <options>...]`::
347The callermust have any of the listed privileges on `/access/groups`. In
348addition there are two possible checks depending on whether the
349`groups_param` option is set:
350+
351* `groups_param` is set: The API call has a non-optional `groups` parameter
352and the caller must have any of the listed privileges on all of the listed
353groups.
354* `groups_param` is not set: The user passed via the `userid` parameter
355must exist and be part of a group on which the caller has any of the listed
356privileges (via the `/access/groups/<group>` path).
357
358`["userid-param", "self"]`::
359The value provided for the API call's `userid` parameter must refer to the
360user performing the action. (Usually in conjunction with `or`, to allow
361users to perform an action on themselves even if they don't have elevated
362privileges.)
363
364`["userid-param", "Realm.AllocateUser"]`::
365The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
366`<realm>` refering to the realm of the user passed via the `userid`
367parameter. Note that the user does not need to exist in order to be
368associated with a realm, since user IDs are passed in the form of
369`<username>@<realm>`.
370
371`["perm-modify", <path>]`::
372The `path` is a templated parameter (see <<templated-paths,Objects and
373Paths>>). The user needs either the `Permissions.Modify` privilege, or,
374depending on the path, the following privileges as a possible substitute:
375+
376* `/storage/...`: additionally requires 'Datastore.Allocate`
377* `/vms/...`: additionally requires 'VM.Allocate`
378* `/pool/...`: additionally requires 'Pool.Allocate`
379+
380If the path is empty, `Permission.Modify` on `/access` is required.
381
3c8533f2
DM
382Command Line Tool
383-----------------
384
385Most users will simply use the GUI to manage users. But there is also
8c1189b6 386a full featured command line tool called `pveum` (short for ``**P**roxmox
4f6e7e05
WB
387**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
388line tools are wrappers around the API, so you can also access those
389function through the REST API.
3c8533f2
DM
390
391Here are some simple usage examples. To show help type:
392
393[source,bash]
394 pveum
395
396or (to show detailed help about a specific command)
397
398[source,bash]
399 pveum help useradd
400
401Create a new user:
402
403[source,bash]
404 pveum useradd testuser@pve -comment "Just a test"
405
406Set or Change the password (not all realms support that):
407
408[source,bash]
409 pveum passwd testuser@pve
410
411Disable a user:
412
413[source,bash]
414 pveum usermod testuser@pve -enable 0
415
416Create a new group:
417
418[source,bash]
419 pveum groupadd testgroup
420
421Create a new role:
422
423[source,bash]
424 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
425
426
427Real World Examples
428-------------------
429
5eba0743 430
3c8533f2
DM
431Administrator Group
432~~~~~~~~~~~~~~~~~~~
433
434One of the most wanted features was the ability to define a group of
5eba0743 435users with full administrator rights (without using the root account).
3c8533f2
DM
436
437Define the group:
438
439[source,bash]
440 pveum groupadd admin -comment "System Administrators"
441
442Then add the permission:
443
444[source,bash]
445 pveum aclmod / -group admin -role Administrator
446
447You can finally add users to the new 'admin' group:
448
449[source,bash]
450 pveum usermod testuser@pve -group admin
451
452
453Auditors
454~~~~~~~~
455
456You can give read only access to users by assigning the `PVEAuditor`
457role to users or groups.
458
8c1189b6 459Example1: Allow user `joe@pve` to see everything
3c8533f2
DM
460
461[source,bash]
462 pveum aclmod / -user joe@pve -role PVEAuditor
463
8c1189b6 464Example1: Allow user `joe@pve` to see all virtual machines
3c8533f2
DM
465
466[source,bash]
467 pveum aclmod /vms -user joe@pve -role PVEAuditor
468
5eba0743 469
3c8533f2
DM
470Delegate User Management
471~~~~~~~~~~~~~~~~~~~~~~~~
472
8c1189b6 473If you want to delegate user managenent to user `joe@pve` you can do
3c8533f2
DM
474that with:
475
476[source,bash]
477 pveum aclmod /access -user joe@pve -role PVEUserAdmin
478
8c1189b6 479User `joe@pve` can now add and remove users, change passwords and
3c8533f2
DM
480other user attributes. This is a very powerful role, and you most
481likely want to limit that to selected realms and groups. The following
8c1189b6
FG
482example allows `joe@pve` to modify users within realm `pve` if they
483are members of group `customers`:
3c8533f2
DM
484
485[source,bash]
486 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
487 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
488
0abc65b0 489NOTE: The user is able to add other users, but only if they are
8c1189b6
FG
490members of group `customers` and within realm `pve`.
491
3c8533f2
DM
492
493Pools
494~~~~~
495
496An enterprise is usually structured into several smaller departments,
497and it is common that you want to assign resources to them and
498delegate management tasks. A pool is simply a set of virtual machines
499and data stores. You can create pools on the GUI. After that you can
500add resources to the pool (VMs, Storage).
501
502You can also assign permissions to the pool. Those permissions are
503inherited to all pool members.
504
505Lets assume you have a software development department, so we first
506create a group
507
508[source,bash]
509 pveum groupadd developers -comment "Our software developers"
510
511Now we create a new user which is a member of that group
512
513[source,bash]
514 pveum useradd developer1@pve -group developers -password
515
0abc65b0 516NOTE: The -password parameter will prompt you for a password
3c8533f2 517
8c1189b6 518I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
3c8533f2
DM
519
520[source,bash]
521 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
522
523Our software developers can now administrate the resources assigned to
524that pool.
525
526
527ifdef::manvolnum[]
528include::pve-copyright.adoc[]
529endif::manvolnum[]
530