expand the authentication realm descriptions
[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
30Proxmox VE supports multiple authentication sources, e.g. Microsoft
31Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
32authentication server.
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
d6614202 38[[authentication-realms]]
3c8533f2
DM
39Authentication Realms
40---------------------
41
d6614202
WB
42As {pve} users are just counterparts for users existing on some external
43realm, the realms have to be configured in `/etc/pve/domains.cfg`.
44The following realms (authentication methods) are available:
3c8533f2
DM
45
46Linux PAM standard authentication::
d6614202
WB
47In this case a system user has to exist (eg. created via the `adduser`
48command) on all nodes the user is allowed to login, and the user
49authenticates with their usual system password.
50+
3c8533f2
DM
51[source,bash]
52----
53useradd heinz
54passwd heinz
55groupadd watchman
56usermod -a -G watchman heinz
57----
58
59Proxmox VE authentication server::
d6614202
WB
60This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
61Password are encrypted using the SHA-256 hash method.
62This is the most convenient method for for small (or even medium)
63installations 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
65change their own passwords via the GUI.
66
67LDAP::
68It is possible to authenticate users via an LDAP server (eq.
69openldap). The server and an optional fallback server can be
70configured and the connection can be encrypted via SSL.
71+
72Users are searched under a 'Base Domain Name' (`base_dn`), with the
73user name found in the attribute specified in the 'User Attribute Name'
74(`user_attr`) field.
75+
76For instance, if a user is represented via the
77following ldif dataset:
78+
79----
80# user1 of People at ldap-test.com
81dn: uid=user1,ou=People,dc=ldap-test,dc=com
82objectClass: top
83objectClass: person
84objectClass: organizationalPerson
85objectClass: inetOrgPerson
86uid: user1
87cn: Test User 1
88sn: Testers
89description: This is the first test user.
90----
91+
92The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
93attribute would be `uid`.
94+
95If {pve} needs to authenticate (bind) to the ldap server before being
96able to query and authenticate users, a bind domain name can be
97configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
98password 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
100single line containing the raw password.
101
102Microsoft Active Directory::
3c8533f2 103
d6614202
WB
104A server and authentication domain need to be specified. Like with
105ldap an optional fallback server, optional port, and SSL
106encryption can be configured.
3c8533f2 107
5eba0743 108
3c8533f2
DM
109Terms and Definitions
110---------------------
111
5eba0743 112
3c8533f2
DM
113Users
114~~~~~
115
116A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The
117login screen on the GUI shows them a separate items, but it is
118internally used as single string.
119
8c1189b6 120We store the following attribute for users (`/etc/pve/user.cfg`):
3c8533f2
DM
121
122* first name
123* last name
124* email address
125* expiration date
126* flag to enable/disable account
127* comment
128
5eba0743 129
3c8533f2
DM
130Superuser
131^^^^^^^^^
132
8c1189b6 133The traditional unix superuser account is called `root@pam`. All
3c8533f2
DM
134system mails are forwarded to the email assigned to that account.
135
5eba0743 136
3c8533f2
DM
137Groups
138~~~~~~
139
140Each user can be member of several groups. Groups are the preferred
141way to organize access permissions. You should always grant permission
142to groups instead of using individual users. That way you will get a
143much shorter access control list which is easier to handle.
144
5eba0743 145
3c8533f2
DM
146Objects and Paths
147~~~~~~~~~~~~~~~~~
148
149Access permissions are assigned to objects, such as a virtual machines
8c1189b6
FG
150(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
151resources (`/pool/{poolname}`). We use file system like paths to
3c8533f2
DM
152address those objects. Those paths form a natural tree, and
153permissions can be inherited down that hierarchy.
154
5eba0743 155
3c8533f2
DM
156Privileges
157~~~~~~~~~~
158
159A privilege is the right to perform a specific action. To simplify
160management, lists of privileges are grouped into roles, which can then
161be uses to set permissions.
162
163We currently use the following privileges:
164
165Node / System related privileges::
166
167* `Permissions.Modify`: modify access permissions
168* `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
169* `Sys.Console`: console access to Node
170* `Sys.Syslog`: view Syslog
171* `Sys.Audit`: view node status/config
172* `Sys.Modify`: create/remove/modify node network parameters
173* `Group.Allocate`: create/remove/modify groups
174* `Pool.Allocate`: create/remove/modify a pool
175* `Realm.Allocate`: create/remove/modify authentication realms
176* `Realm.AllocateUser`: assign user to a realm
177* `User.Modify`: create/remove/modify user access and details.
178
179Virtual machine related privileges::
180
181* `VM.Allocate`: create/remove new VM to server inventory
182* `VM.Migrate`: migrate VM to alternate server on cluster
183* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
184* `VM.Console`: console access to VM
185* `VM.Monitor`: access to VM monitor (kvm)
186* `VM.Backup`: backup/restore VMs
187* `VM.Audit`: view VM config
188* `VM.Clone`: clone/copy a VM
189* `VM.Config.Disk`: add/modify/delete Disks
190* `VM.Config.CDROM`: eject/change CDROM
191* `VM.Config.CPU`: modify CPU settings
192* `VM.Config.Memory`: modify Memory settings
193* `VM.Config.Network`: add/modify/delete Network devices
194* `VM.Config.HWType`: modify emulated HW type
195* `VM.Config.Options`: modify any other VM configuration
196* `VM.Snapshot`: create/remove VM snapshots
197
198Storage related privileges::
199
200* `Datastore.Allocate`: create/remove/modify a data store, delete volumes
201* `Datastore.AllocateSpace`: allocate space on a datastore
202* `Datastore.AllocateTemplate`: allocate/upload templates and iso images
203* `Datastore.Audit`: view/browse a datastore
204
5eba0743 205
3c8533f2
DM
206Roles
207~~~~~
208
209A role is simply a list of privileges. Proxmox VE comes with a number
210of predefined roles which satisfies most needs.
211
212* `Administrator`: has all privileges
213* `NoAccess`: has no privileges (used to forbid access)
214* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
215* `PVEAuditor`: read only access
216* `PVEDatastoreAdmin`: create and allocate backup space and templates
217* `PVEDatastoreUser`: allocate backup space and view storage
218* `PVEPoolAdmin`: allocate pools
219* `PVESysAdmin`: User ACLs, audit, system console and system logs
220* `PVETemplateUser`: view and clone templates
221* `PVEUserAdmin`: user administration
222* `PVEVMAdmin`: fully administer VMs
223* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
224
225You can see the whole set of predefined roles on the GUI.
226
227Adding new roles using the CLI:
228
229[source,bash]
230----
231pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
232pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
233----
234
235
236Permissions
237~~~~~~~~~~~
238
239Permissions are the way we control access to objects. In technical
240terms they are simply a triple containing `<path,user,role>`. This
241concept is also known as access control lists. Each permission
242specifies a subject (user or group) and a role (set of privileges) on
243a specific path.
244
245When a subject requests an action on an object, the framework looks up
246the roles assigned to that subject (using the object path). The set of
247roles defines the granted privileges.
248
5eba0743 249
3c8533f2
DM
250Inheritance
251^^^^^^^^^^^
252
5eba0743 253As mentioned earlier, object paths form a file system like tree, and
3c8533f2
DM
254permissions can be inherited down that tree (the propagate flag is set
255by default). We use the following inheritance rules:
256
257* permission for individual users always overwrite group permission.
258* permission for groups apply when the user is member of that group.
259* permission set at higher level always overwrites inherited permissions.
260
5eba0743 261
3c8533f2
DM
262What permission do I need?
263^^^^^^^^^^^^^^^^^^^^^^^^^^
4b048bf2
EK
264
265The required API permissions are documented for each individual
266method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
3c8533f2 267
5eba0743 268
3c8533f2
DM
269Pools
270~~~~~
271
272Pools can be used to group a set of virtual machines and data
8c1189b6 273stores. You can then simply set permissions on pools (`/pool/{poolid}`),
3c8533f2
DM
274which are inherited to all pool members. This is a great way simplify
275access control.
276
277Command Line Tool
278-----------------
279
280Most users will simply use the GUI to manage users. But there is also
8c1189b6 281a full featured command line tool called `pveum` (short for ``**P**roxmox
4f6e7e05
WB
282**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
283line tools are wrappers around the API, so you can also access those
284function through the REST API.
3c8533f2
DM
285
286Here are some simple usage examples. To show help type:
287
288[source,bash]
289 pveum
290
291or (to show detailed help about a specific command)
292
293[source,bash]
294 pveum help useradd
295
296Create a new user:
297
298[source,bash]
299 pveum useradd testuser@pve -comment "Just a test"
300
301Set or Change the password (not all realms support that):
302
303[source,bash]
304 pveum passwd testuser@pve
305
306Disable a user:
307
308[source,bash]
309 pveum usermod testuser@pve -enable 0
310
311Create a new group:
312
313[source,bash]
314 pveum groupadd testgroup
315
316Create a new role:
317
318[source,bash]
319 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
320
321
322Real World Examples
323-------------------
324
5eba0743 325
3c8533f2
DM
326Administrator Group
327~~~~~~~~~~~~~~~~~~~
328
329One of the most wanted features was the ability to define a group of
5eba0743 330users with full administrator rights (without using the root account).
3c8533f2
DM
331
332Define the group:
333
334[source,bash]
335 pveum groupadd admin -comment "System Administrators"
336
337Then add the permission:
338
339[source,bash]
340 pveum aclmod / -group admin -role Administrator
341
342You can finally add users to the new 'admin' group:
343
344[source,bash]
345 pveum usermod testuser@pve -group admin
346
347
348Auditors
349~~~~~~~~
350
351You can give read only access to users by assigning the `PVEAuditor`
352role to users or groups.
353
8c1189b6 354Example1: Allow user `joe@pve` to see everything
3c8533f2
DM
355
356[source,bash]
357 pveum aclmod / -user joe@pve -role PVEAuditor
358
8c1189b6 359Example1: Allow user `joe@pve` to see all virtual machines
3c8533f2
DM
360
361[source,bash]
362 pveum aclmod /vms -user joe@pve -role PVEAuditor
363
5eba0743 364
3c8533f2
DM
365Delegate User Management
366~~~~~~~~~~~~~~~~~~~~~~~~
367
8c1189b6 368If you want to delegate user managenent to user `joe@pve` you can do
3c8533f2
DM
369that with:
370
371[source,bash]
372 pveum aclmod /access -user joe@pve -role PVEUserAdmin
373
8c1189b6 374User `joe@pve` can now add and remove users, change passwords and
3c8533f2
DM
375other user attributes. This is a very powerful role, and you most
376likely want to limit that to selected realms and groups. The following
8c1189b6
FG
377example allows `joe@pve` to modify users within realm `pve` if they
378are members of group `customers`:
3c8533f2
DM
379
380[source,bash]
381 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
382 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
383
0abc65b0 384NOTE: The user is able to add other users, but only if they are
8c1189b6
FG
385members of group `customers` and within realm `pve`.
386
3c8533f2
DM
387
388Pools
389~~~~~
390
391An enterprise is usually structured into several smaller departments,
392and it is common that you want to assign resources to them and
393delegate management tasks. A pool is simply a set of virtual machines
394and data stores. You can create pools on the GUI. After that you can
395add resources to the pool (VMs, Storage).
396
397You can also assign permissions to the pool. Those permissions are
398inherited to all pool members.
399
400Lets assume you have a software development department, so we first
401create a group
402
403[source,bash]
404 pveum groupadd developers -comment "Our software developers"
405
406Now we create a new user which is a member of that group
407
408[source,bash]
409 pveum useradd developer1@pve -group developers -password
410
0abc65b0 411NOTE: The -password parameter will prompt you for a password
3c8533f2 412
8c1189b6 413I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
3c8533f2
DM
414
415[source,bash]
416 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
417
418Our software developers can now administrate the resources assigned to
419that pool.
420
421
422ifdef::manvolnum[]
423include::pve-copyright.adoc[]
424endif::manvolnum[]
425