]>
Commit | Line | Data |
---|---|---|
3c8533f2 DM |
1 | ifdef::manvolnum[] |
2 | PVE({manvolnum}) | |
3 | ================ | |
38fd0958 | 4 | include::attributes.txt[] |
3c8533f2 DM |
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 | =============== | |
38fd0958 | 25 | include::attributes.txt[] |
3c8533f2 DM |
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 | |
3b26ef9e EK |
106 | ('/vms/\{vmid\}') or a storage ('/storage/\{storeid\}') or a pool of |
107 | resources ('/pool/\{poolname\}'). We use filesystem like paths to | |
3c8533f2 DM |
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 | |
3b26ef9e | 222 | stores. You can then simply set permissions on pools ('/pool/\{poolid\}'), |
3c8533f2 DM |
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 | ||
0abc65b0 | 332 | NOTE: The user is able to add other users, but only if they are |
3c8533f2 DM |
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 | ||
0abc65b0 | 358 | NOTE: The -password parameter will prompt you for a password |
3c8533f2 DM |
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 |