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