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