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