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