move include after document header
[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 (VM´s, storages, nodes, etc.) granular access can be defined.
36
37 Authentication Realms
38 ---------------------
39
40 Proxmox VE stores all user attributes in '/etc/pve/user.cfg'. So there
41 must be an entry for each user in that file. The password is not
42 stored, instead you can use configure several realms to verify
43 passwords.
44
45 Microsoft Active Directory::
46
47 LDAP::
48
49 Linux PAM standard authentication::
50
51 You need to create the system users first with 'adduser'
52 (e.g. adduser heinz) and possibly the group as well. After that you
53 can create the user on the GUI!
54
55 [source,bash]
56 ----
57 useradd heinz
58 passwd heinz
59 groupadd watchman
60 usermod -a -G watchman heinz
61 ----
62
63 Proxmox VE authentication server::
64
65 This is a unix like password store
66 ('/etc/pve/priv/shadow.cfg'). Password are encrypted using the SHA-256
67 hash method. Users are allowed to change passwords.
68
69 Terms and Definitions
70 ---------------------
71
72 Users
73 ~~~~~
74
75 A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The
76 login screen on the GUI shows them a separate items, but it is
77 internally used as single string.
78
79 We 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
88 Superuser
89 ^^^^^^^^^
90
91 The traditional unix superuser account is called 'root@pam'. All
92 system mails are forwarded to the email assigned to that account.
93
94 Groups
95 ~~~~~~
96
97 Each user can be member of several groups. Groups are the preferred
98 way to organize access permissions. You should always grant permission
99 to groups instead of using individual users. That way you will get a
100 much shorter access control list which is easier to handle.
101
102 Objects and Paths
103 ~~~~~~~~~~~~~~~~~
104
105 Access permissions are assigned to objects, such as a virtual machines
106 ('/vms/{vmid}') or a storage ('/storage/{storeid}') or a pool of
107 resources ('/pool/{poolname}'). We use filesystem like paths to
108 address those objects. Those paths form a natural tree, and
109 permissions can be inherited down that hierarchy.
110
111 Privileges
112 ~~~~~~~~~~
113
114 A privilege is the right to perform a specific action. To simplify
115 management, lists of privileges are grouped into roles, which can then
116 be uses to set permissions.
117
118 We currently use the following privileges:
119
120 Node / 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
134 Virtual 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
153 Storage 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
160 Roles
161 ~~~~~
162
163 A role is simply a list of privileges. Proxmox VE comes with a number
164 of 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
179 You can see the whole set of predefined roles on the GUI.
180
181 Adding new roles using the CLI:
182
183 [source,bash]
184 ----
185 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
186 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
187 ----
188
189
190 Permissions
191 ~~~~~~~~~~~
192
193 Permissions are the way we control access to objects. In technical
194 terms they are simply a triple containing `<path,user,role>`. This
195 concept is also known as access control lists. Each permission
196 specifies a subject (user or group) and a role (set of privileges) on
197 a specific path.
198
199 When a subject requests an action on an object, the framework looks up
200 the roles assigned to that subject (using the object path). The set of
201 roles defines the granted privileges.
202
203 Inheritance
204 ^^^^^^^^^^^
205
206 As mentioned earlier, object paths forms a filesystem like tree, and
207 permissions can be inherited down that tree (the propagate flag is set
208 by 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
214 What permission do I need?
215 ^^^^^^^^^^^^^^^^^^^^^^^^^^
216 The required API permissions are documented for each individual method, and can be found at http://pve.proxmox.com/pve2-api-doc/
217
218 Pools
219 ~~~~~
220
221 Pools can be used to group a set of virtual machines and data
222 stores. You can then simply set permissions on pools ('/pool/{poolid}'),
223 which are inherited to all pool members. This is a great way simplify
224 access control.
225
226 Command Line Tool
227 -----------------
228
229 Most users will simply use the GUI to manage users. But there is also
230 a full featured command line tool called 'pveum' (short for 'Proxmox
231 VE User Manager'). I will use that tool in the following
232 examples. Please note that all Proxmox VE command line tools are
233 wrappers around the API, so you can also access those function through
234 the REST API.
235
236 Here are some simple usage examples. To show help type:
237
238 [source,bash]
239  pveum
240
241 or (to show detailed help about a specific command)
242
243 [source,bash]
244  pveum help useradd
245
246 Create a new user:
247
248 [source,bash]
249  pveum useradd testuser@pve -comment "Just a test"
250
251 Set or Change the password (not all realms support that):
252
253 [source,bash]
254  pveum passwd testuser@pve
255
256 Disable a user:
257
258 [source,bash]
259  pveum usermod testuser@pve -enable 0
260
261 Create a new group:
262
263 [source,bash]
264  pveum groupadd testgroup
265
266 Create a new role:
267
268 [source,bash]
269  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
270
271
272 Real World Examples
273 -------------------
274
275 Administrator Group
276 ~~~~~~~~~~~~~~~~~~~
277
278 One of the most wanted features was the ability to define a group of
279 users with full administartor rights (without using the root account).
280
281 Define the group:
282
283 [source,bash]
284  pveum groupadd admin -comment "System Administrators"
285
286 Then add the permission:
287
288 [source,bash]
289  pveum aclmod / -group admin -role Administrator
290
291 You can finally add users to the new 'admin' group:
292
293 [source,bash]
294  pveum usermod testuser@pve -group admin
295
296
297 Auditors
298 ~~~~~~~~
299
300 You can give read only access to users by assigning the `PVEAuditor`
301 role to users or groups.
302
303 Example1: Allow user 'joe@pve' to see everything
304
305 [source,bash]
306  pveum aclmod / -user joe@pve -role PVEAuditor
307
308 Example1: Allow user 'joe@pve' to see all virtual machines
309
310 [source,bash]
311  pveum aclmod /vms -user joe@pve -role PVEAuditor
312
313 Delegate User Management
314 ~~~~~~~~~~~~~~~~~~~~~~~~
315
316 If you want to delegate user managenent to user 'joe@pve' you can do
317 that with:
318
319 [source,bash]
320  pveum aclmod /access -user joe@pve -role PVEUserAdmin
321
322 User 'joe@pve' can now add and remove users, change passwords and
323 other user attributes. This is a very powerful role, and you most
324 likely want to limit that to selected realms and groups. The following
325 example allows 'joe@pve' to modify users within realm 'pve' if they
326 are members of group 'customers':
327
328 [source,bash]
329  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
330  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
331
332 Note: The user is able to add other users, but only if they are
333 members of group 'customers' and within realm 'pve'.
334
335 Pools
336 ~~~~~
337
338 An enterprise is usually structured into several smaller departments,
339 and it is common that you want to assign resources to them and
340 delegate management tasks. A pool is simply a set of virtual machines
341 and data stores. You can create pools on the GUI. After that you can
342 add resources to the pool (VMs, Storage).
343
344 You can also assign permissions to the pool. Those permissions are
345 inherited to all pool members.
346
347 Lets assume you have a software development department, so we first
348 create a group
349
350 [source,bash]
351  pveum groupadd developers -comment "Our software developers"
352
353 Now we create a new user which is a member of that group
354
355 [source,bash]
356  pveum useradd developer1@pve -group developers -password
357
358 Note: The -password parameter will prompt you for a password
359
360 I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
361
362 [source,bash]
363  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
364
365 Our software developers can now administrate the resources assigned to
366 that pool.
367
368
369 ifdef::manvolnum[]
370 include::pve-copyright.adoc[]
371 endif::manvolnum[]
372