]>
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 | ||
5462c161 WB |
30 | Proxmox VE supports multiple authentication sources, e.g. Linux PAM, |
31 | an integrated Proxmox VE authentication server, LDAP, Microsoft Active | |
32 | Directory. | |
3c8533f2 DM |
33 | |
34 | By using the role based user- and permission management for all | |
5eba0743 FG |
35 | objects (VMs, storages, nodes, etc.) granular access can be defined. |
36 | ||
3c8533f2 | 37 | |
c80b9ee6 WB |
38 | Users |
39 | ----- | |
40 | ||
41 | {pve} stores user attributes in `/etc/pve/user.cfg`. | |
42 | Passwords are not stored here, users are instead associated with | |
43 | <<authentication-realms,authentication realms>> described below. | |
44 | Therefore a user is internally often identified by its name and | |
45 | realm in the form `<userid>@<realm>`. | |
46 | ||
47 | Each user entry in this file contains the following information: | |
48 | ||
49 | * First name | |
50 | * Last name | |
51 | * E-mail address | |
52 | * Group memberships | |
53 | * An optional Expiration date | |
54 | * A comment or note about this user | |
55 | * Whether this user is enabled or disabled | |
56 | * Optional two factor authentication keys | |
57 | ||
58 | ||
59 | System administrator | |
60 | ~~~~~~~~~~~~~~~~~~~~ | |
61 | ||
62 | The system's root user can always log in via the Linux PAM realm and is an | |
63 | unconfined administrator. This user cannot be deleted, but attributes can | |
64 | still be changed and system mails will be sent to the email address | |
65 | assigned to this user. | |
66 | ||
67 | ||
68 | Groups | |
69 | ~~~~~~ | |
70 | ||
71 | Each user can be member of several groups. Groups are the preferred | |
72 | way to organize access permissions. You should always grant permission | |
73 | to groups instead of using individual users. That way you will get a | |
74 | much shorter access control list which is easier to handle. | |
75 | ||
76 | ||
d6614202 | 77 | [[authentication-realms]] |
3c8533f2 DM |
78 | Authentication Realms |
79 | --------------------- | |
80 | ||
d6614202 WB |
81 | As {pve} users are just counterparts for users existing on some external |
82 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
83 | The following realms (authentication methods) are available: | |
3c8533f2 DM |
84 | |
85 | Linux PAM standard authentication:: | |
d6614202 WB |
86 | In this case a system user has to exist (eg. created via the `adduser` |
87 | command) on all nodes the user is allowed to login, and the user | |
88 | authenticates with their usual system password. | |
89 | + | |
3c8533f2 DM |
90 | [source,bash] |
91 | ---- | |
92 | useradd heinz | |
93 | passwd heinz | |
94 | groupadd watchman | |
95 | usermod -a -G watchman heinz | |
96 | ---- | |
97 | ||
98 | Proxmox VE authentication server:: | |
d6614202 WB |
99 | This is a unix like password store (`/etc/pve/priv/shadow.cfg`). |
100 | Password are encrypted using the SHA-256 hash method. | |
101 | This is the most convenient method for for small (or even medium) | |
102 | installations where users do not need access to anything outside of | |
103 | {pve}. In this case users are fully managed by {pve} and are able to | |
104 | change their own passwords via the GUI. | |
105 | ||
106 | LDAP:: | |
107 | It is possible to authenticate users via an LDAP server (eq. | |
108 | openldap). The server and an optional fallback server can be | |
109 | configured and the connection can be encrypted via SSL. | |
110 | + | |
111 | Users are searched under a 'Base Domain Name' (`base_dn`), with the | |
112 | user name found in the attribute specified in the 'User Attribute Name' | |
113 | (`user_attr`) field. | |
114 | + | |
115 | For instance, if a user is represented via the | |
116 | following ldif dataset: | |
117 | + | |
118 | ---- | |
119 | # user1 of People at ldap-test.com | |
120 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
121 | objectClass: top | |
122 | objectClass: person | |
123 | objectClass: organizationalPerson | |
124 | objectClass: inetOrgPerson | |
125 | uid: user1 | |
126 | cn: Test User 1 | |
127 | sn: Testers | |
128 | description: This is the first test user. | |
129 | ---- | |
130 | + | |
131 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user | |
132 | attribute would be `uid`. | |
133 | + | |
134 | If {pve} needs to authenticate (bind) to the ldap server before being | |
135 | able to query and authenticate users, a bind domain name can be | |
136 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
137 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
138 | (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a | |
139 | single line containing the raw password. | |
140 | ||
141 | Microsoft Active Directory:: | |
3c8533f2 | 142 | |
d6614202 WB |
143 | A server and authentication domain need to be specified. Like with |
144 | ldap an optional fallback server, optional port, and SSL | |
145 | encryption can be configured. | |
3c8533f2 | 146 | |
5eba0743 | 147 | |
9e8f2770 WB |
148 | Two factor authentication |
149 | ------------------------- | |
150 | ||
151 | Each realm can optionally be secured additionally by two factor | |
152 | authentication. This can be done by selecting one of the available methods | |
153 | via the 'TFA' dropdown box when adding or editing an Authentication Realm. | |
154 | When a realm has TFA enabled it becomes a requirement and only users with | |
155 | configured TFA will be able to login. | |
156 | ||
157 | Currently there are two methods available: | |
158 | ||
159 | Time based OATH (TOTP):: | |
160 | This uses the standard HMAC-SHA1 algorithm where the current time is hashed | |
161 | with the user's configured key. The time step and password length | |
162 | parameters are configured. | |
163 | + | |
164 | A user can have multiple keys configured (separated by spaces), and the | |
165 | keys can be specified in Base32 (RFC3548) or hexadecimal notation. | |
166 | + | |
167 | {pve} provides a key generation tool (`oathkeygen`) which prints out a | |
168 | random key in Base32 notation which can be used directly with various OTP | |
169 | tools, such as the `oathtool` command line tool, the Google authenticator | |
170 | or FreeOTP Android apps. | |
171 | ||
172 | YubiKey OTP:: | |
173 | For authenticating via a YubiKey a Yubico API ID, API KEY and validation | |
174 | server URL must be configured, and users must have a YubiKey available. In | |
175 | order to get the key ID from a YubiKey, you can trigger the YubiKey once | |
176 | after connecting it to USB and copy the first 12 characters of the typed | |
177 | password into the user's 'Key IDs' field. | |
178 | + | |
179 | Please refer to the | |
180 | https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the | |
181 | https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or | |
182 | https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[ | |
183 | host your own verification server]. | |
184 | ||
185 | ||
04f44730 | 186 | Permission Management |
3c8533f2 DM |
187 | --------------------- |
188 | ||
04f44730 WB |
189 | In order for a user to perform an action (such as listing, modifying or |
190 | deleting a parts of a VM configuration), the user needs to have the | |
191 | appropriate permissions. | |
192 | ||
193 | {pve} uses a role and path based permission management system. An entry in | |
194 | the permissions table allows a user or group to take on a specific role | |
195 | when accessing an 'object' or 'path'. This means an such an access rule can | |
196 | be represented as a triple of '(path, user, role)' or '(path, group, | |
197 | role)', with the role containing a set of allowed actions, and the path | |
198 | representing the target of these actions. | |
199 | ||
5eba0743 | 200 | |
853d288b WB |
201 | Roles |
202 | ~~~~~ | |
203 | ||
204 | A role is simply a list of privileges. Proxmox VE comes with a number | |
205 | of predefined roles which satisfies most needs. | |
206 | ||
207 | * `Administrator`: has all privileges | |
208 | * `NoAccess`: has no privileges (used to forbid access) | |
209 | * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). | |
210 | * `PVEAuditor`: read only access | |
211 | * `PVEDatastoreAdmin`: create and allocate backup space and templates | |
212 | * `PVEDatastoreUser`: allocate backup space and view storage | |
213 | * `PVEPoolAdmin`: allocate pools | |
214 | * `PVESysAdmin`: User ACLs, audit, system console and system logs | |
215 | * `PVETemplateUser`: view and clone templates | |
216 | * `PVEUserAdmin`: user administration | |
217 | * `PVEVMAdmin`: fully administer VMs | |
218 | * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management | |
219 | ||
220 | You can see the whole set of predefined roles on the GUI. | |
221 | ||
222 | Adding new roles can currently only be done from the command line, like | |
223 | this: | |
224 | ||
225 | [source,bash] | |
226 | ---- | |
227 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
228 | pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" | |
229 | ---- | |
230 | ||
231 | ||
3c8533f2 DM |
232 | Objects and Paths |
233 | ~~~~~~~~~~~~~~~~~ | |
234 | ||
235 | Access permissions are assigned to objects, such as a virtual machines | |
8c1189b6 FG |
236 | (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of |
237 | resources (`/pool/{poolname}`). We use file system like paths to | |
3c8533f2 DM |
238 | address those objects. Those paths form a natural tree, and |
239 | permissions can be inherited down that hierarchy. | |
240 | ||
5eba0743 | 241 | |
3c8533f2 DM |
242 | Privileges |
243 | ~~~~~~~~~~ | |
244 | ||
245 | A privilege is the right to perform a specific action. To simplify | |
246 | management, lists of privileges are grouped into roles, which can then | |
0e1fda70 WB |
247 | be used in the permission table. Note that privileges cannot directly be |
248 | assigned to users and paths without being part of a role. | |
3c8533f2 DM |
249 | |
250 | We currently use the following privileges: | |
251 | ||
252 | Node / System related privileges:: | |
253 | ||
254 | * `Permissions.Modify`: modify access permissions | |
255 | * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...) | |
256 | * `Sys.Console`: console access to Node | |
257 | * `Sys.Syslog`: view Syslog | |
258 | * `Sys.Audit`: view node status/config | |
259 | * `Sys.Modify`: create/remove/modify node network parameters | |
260 | * `Group.Allocate`: create/remove/modify groups | |
261 | * `Pool.Allocate`: create/remove/modify a pool | |
262 | * `Realm.Allocate`: create/remove/modify authentication realms | |
263 | * `Realm.AllocateUser`: assign user to a realm | |
264 | * `User.Modify`: create/remove/modify user access and details. | |
265 | ||
266 | Virtual machine related privileges:: | |
267 | ||
268 | * `VM.Allocate`: create/remove new VM to server inventory | |
269 | * `VM.Migrate`: migrate VM to alternate server on cluster | |
270 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
271 | * `VM.Console`: console access to VM | |
272 | * `VM.Monitor`: access to VM monitor (kvm) | |
273 | * `VM.Backup`: backup/restore VMs | |
274 | * `VM.Audit`: view VM config | |
275 | * `VM.Clone`: clone/copy a VM | |
276 | * `VM.Config.Disk`: add/modify/delete Disks | |
277 | * `VM.Config.CDROM`: eject/change CDROM | |
278 | * `VM.Config.CPU`: modify CPU settings | |
279 | * `VM.Config.Memory`: modify Memory settings | |
280 | * `VM.Config.Network`: add/modify/delete Network devices | |
281 | * `VM.Config.HWType`: modify emulated HW type | |
282 | * `VM.Config.Options`: modify any other VM configuration | |
283 | * `VM.Snapshot`: create/remove VM snapshots | |
284 | ||
285 | Storage related privileges:: | |
286 | ||
287 | * `Datastore.Allocate`: create/remove/modify a data store, delete volumes | |
288 | * `Datastore.AllocateSpace`: allocate space on a datastore | |
289 | * `Datastore.AllocateTemplate`: allocate/upload templates and iso images | |
290 | * `Datastore.Audit`: view/browse a datastore | |
291 | ||
5eba0743 | 292 | |
3c8533f2 DM |
293 | Permissions |
294 | ~~~~~~~~~~~ | |
295 | ||
296 | Permissions are the way we control access to objects. In technical | |
297 | terms they are simply a triple containing `<path,user,role>`. This | |
298 | concept is also known as access control lists. Each permission | |
299 | specifies a subject (user or group) and a role (set of privileges) on | |
300 | a specific path. | |
301 | ||
302 | When a subject requests an action on an object, the framework looks up | |
303 | the roles assigned to that subject (using the object path). The set of | |
304 | roles defines the granted privileges. | |
305 | ||
5eba0743 | 306 | |
3c8533f2 DM |
307 | Inheritance |
308 | ^^^^^^^^^^^ | |
309 | ||
5eba0743 | 310 | As mentioned earlier, object paths form a file system like tree, and |
3c8533f2 DM |
311 | permissions can be inherited down that tree (the propagate flag is set |
312 | by default). We use the following inheritance rules: | |
313 | ||
74936daf WB |
314 | * Permissions for individual users always replace group permissions. |
315 | * Permissions for groups apply when the user is member of that group. | |
316 | * Permissions replace the ones inherited from an upper level. | |
3c8533f2 | 317 | |
5eba0743 | 318 | |
3c8533f2 DM |
319 | Pools |
320 | ~~~~~ | |
321 | ||
322 | Pools can be used to group a set of virtual machines and data | |
8c1189b6 | 323 | stores. You can then simply set permissions on pools (`/pool/{poolid}`), |
3c8533f2 DM |
324 | which are inherited to all pool members. This is a great way simplify |
325 | access control. | |
326 | ||
74936daf WB |
327 | |
328 | What permission do I need? | |
329 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
330 | ||
331 | The required API permissions are documented for each individual | |
332 | method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ | |
333 | ||
334 | The permissions are specified as a list which can be interpreted as a | |
335 | tree of logic and access-check functions: | |
336 | ||
337 | `["and", <subtests>...]` and `["or", <subtests>...]`:: | |
338 | Each(`and`) or any(`or`) further element in the current list has to be true. | |
339 | ||
340 | `["perm", <path>, [ <privileges>... ], <options>...]`:: | |
341 | The `path` is a templated parameter (see <<templated-paths,Objects and | |
342 | Paths>>). All (or , if the `any` option is used, any) of the listed | |
343 | privileges must be allowed on the specified path. If a `require-param` | |
344 | option is specified, then its specified parameter is required even if the | |
345 | API call's schema otherwise lists it as being optional. | |
346 | ||
347 | `["userid-group", [ <privileges>... ], <options>...]`:: | |
348 | The callermust have any of the listed privileges on `/access/groups`. In | |
349 | addition there are two possible checks depending on whether the | |
350 | `groups_param` option is set: | |
351 | + | |
352 | * `groups_param` is set: The API call has a non-optional `groups` parameter | |
353 | and the caller must have any of the listed privileges on all of the listed | |
354 | groups. | |
355 | * `groups_param` is not set: The user passed via the `userid` parameter | |
356 | must exist and be part of a group on which the caller has any of the listed | |
357 | privileges (via the `/access/groups/<group>` path). | |
358 | ||
359 | `["userid-param", "self"]`:: | |
360 | The value provided for the API call's `userid` parameter must refer to the | |
361 | user performing the action. (Usually in conjunction with `or`, to allow | |
362 | users to perform an action on themselves even if they don't have elevated | |
363 | privileges.) | |
364 | ||
365 | `["userid-param", "Realm.AllocateUser"]`:: | |
366 | The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with | |
367 | `<realm>` refering to the realm of the user passed via the `userid` | |
368 | parameter. Note that the user does not need to exist in order to be | |
369 | associated with a realm, since user IDs are passed in the form of | |
370 | `<username>@<realm>`. | |
371 | ||
372 | `["perm-modify", <path>]`:: | |
373 | The `path` is a templated parameter (see <<templated-paths,Objects and | |
374 | Paths>>). The user needs either the `Permissions.Modify` privilege, or, | |
375 | depending on the path, the following privileges as a possible substitute: | |
376 | + | |
377 | * `/storage/...`: additionally requires 'Datastore.Allocate` | |
378 | * `/vms/...`: additionally requires 'VM.Allocate` | |
379 | * `/pool/...`: additionally requires 'Pool.Allocate` | |
380 | + | |
381 | If the path is empty, `Permission.Modify` on `/access` is required. | |
382 | ||
3c8533f2 DM |
383 | Command Line Tool |
384 | ----------------- | |
385 | ||
386 | Most users will simply use the GUI to manage users. But there is also | |
8c1189b6 | 387 | a full featured command line tool called `pveum` (short for ``**P**roxmox |
4f6e7e05 WB |
388 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command |
389 | line tools are wrappers around the API, so you can also access those | |
390 | function through the REST API. | |
3c8533f2 DM |
391 | |
392 | Here are some simple usage examples. To show help type: | |
393 | ||
394 | [source,bash] | |
395 | pveum | |
396 | ||
397 | or (to show detailed help about a specific command) | |
398 | ||
399 | [source,bash] | |
400 | pveum help useradd | |
401 | ||
402 | Create a new user: | |
403 | ||
404 | [source,bash] | |
405 | pveum useradd testuser@pve -comment "Just a test" | |
406 | ||
407 | Set or Change the password (not all realms support that): | |
408 | ||
409 | [source,bash] | |
410 | pveum passwd testuser@pve | |
411 | ||
412 | Disable a user: | |
413 | ||
414 | [source,bash] | |
415 | pveum usermod testuser@pve -enable 0 | |
416 | ||
417 | Create a new group: | |
418 | ||
419 | [source,bash] | |
420 | pveum groupadd testgroup | |
421 | ||
422 | Create a new role: | |
423 | ||
424 | [source,bash] | |
425 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
426 | ||
427 | ||
428 | Real World Examples | |
429 | ------------------- | |
430 | ||
5eba0743 | 431 | |
3c8533f2 DM |
432 | Administrator Group |
433 | ~~~~~~~~~~~~~~~~~~~ | |
434 | ||
435 | One of the most wanted features was the ability to define a group of | |
5eba0743 | 436 | users with full administrator rights (without using the root account). |
3c8533f2 DM |
437 | |
438 | Define the group: | |
439 | ||
440 | [source,bash] | |
441 | pveum groupadd admin -comment "System Administrators" | |
442 | ||
443 | Then add the permission: | |
444 | ||
445 | [source,bash] | |
446 | pveum aclmod / -group admin -role Administrator | |
447 | ||
448 | You can finally add users to the new 'admin' group: | |
449 | ||
450 | [source,bash] | |
451 | pveum usermod testuser@pve -group admin | |
452 | ||
453 | ||
454 | Auditors | |
455 | ~~~~~~~~ | |
456 | ||
457 | You can give read only access to users by assigning the `PVEAuditor` | |
458 | role to users or groups. | |
459 | ||
8c1189b6 | 460 | Example1: Allow user `joe@pve` to see everything |
3c8533f2 DM |
461 | |
462 | [source,bash] | |
463 | pveum aclmod / -user joe@pve -role PVEAuditor | |
464 | ||
8c1189b6 | 465 | Example1: Allow user `joe@pve` to see all virtual machines |
3c8533f2 DM |
466 | |
467 | [source,bash] | |
468 | pveum aclmod /vms -user joe@pve -role PVEAuditor | |
469 | ||
5eba0743 | 470 | |
3c8533f2 DM |
471 | Delegate User Management |
472 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
473 | ||
8c1189b6 | 474 | If you want to delegate user managenent to user `joe@pve` you can do |
3c8533f2 DM |
475 | that with: |
476 | ||
477 | [source,bash] | |
478 | pveum aclmod /access -user joe@pve -role PVEUserAdmin | |
479 | ||
8c1189b6 | 480 | User `joe@pve` can now add and remove users, change passwords and |
3c8533f2 DM |
481 | other user attributes. This is a very powerful role, and you most |
482 | likely want to limit that to selected realms and groups. The following | |
8c1189b6 FG |
483 | example allows `joe@pve` to modify users within realm `pve` if they |
484 | are members of group `customers`: | |
3c8533f2 DM |
485 | |
486 | [source,bash] | |
487 | pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin | |
488 | pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin | |
489 | ||
0abc65b0 | 490 | NOTE: The user is able to add other users, but only if they are |
8c1189b6 FG |
491 | members of group `customers` and within realm `pve`. |
492 | ||
3c8533f2 DM |
493 | |
494 | Pools | |
495 | ~~~~~ | |
496 | ||
497 | An enterprise is usually structured into several smaller departments, | |
498 | and it is common that you want to assign resources to them and | |
499 | delegate management tasks. A pool is simply a set of virtual machines | |
500 | and data stores. You can create pools on the GUI. After that you can | |
501 | add resources to the pool (VMs, Storage). | |
502 | ||
503 | You can also assign permissions to the pool. Those permissions are | |
504 | inherited to all pool members. | |
505 | ||
506 | Lets assume you have a software development department, so we first | |
507 | create a group | |
508 | ||
509 | [source,bash] | |
510 | pveum groupadd developers -comment "Our software developers" | |
511 | ||
512 | Now we create a new user which is a member of that group | |
513 | ||
514 | [source,bash] | |
515 | pveum useradd developer1@pve -group developers -password | |
516 | ||
0abc65b0 | 517 | NOTE: The -password parameter will prompt you for a password |
3c8533f2 | 518 | |
8c1189b6 | 519 | I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: |
3c8533f2 DM |
520 | |
521 | [source,bash] | |
522 | pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin | |
523 | ||
524 | Our software developers can now administrate the resources assigned to | |
525 | that pool. | |
526 | ||
527 | ||
528 | ifdef::manvolnum[] | |
529 | include::pve-copyright.adoc[] | |
530 | endif::manvolnum[] | |
531 |