]>
Commit | Line | Data |
---|---|---|
1 | [[chapter_user_management]] | |
2 | ifdef::manvolnum[] | |
3 | pveum(1) | |
4 | ======== | |
5 | :pve-toplevel: | |
6 | ||
7 | NAME | |
8 | ---- | |
9 | ||
10 | pveum - Proxmox VE User Manager | |
11 | ||
12 | ||
13 | SYNOPSIS | |
14 | -------- | |
15 | ||
16 | include::pveum.1-synopsis.adoc[] | |
17 | ||
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
21 | endif::manvolnum[] | |
22 | ifndef::manvolnum[] | |
23 | User Management | |
24 | =============== | |
25 | :pve-toplevel: | |
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. Linux PAM, | |
31 | an integrated Proxmox VE authentication server, LDAP, Microsoft Active | |
32 | Directory. | |
33 | ||
34 | By using the role based user- and permission management for all | |
35 | objects (VMs, storages, nodes, etc.) granular access can be defined. | |
36 | ||
37 | ||
38 | [[pveum_users]] | |
39 | Users | |
40 | ----- | |
41 | ||
42 | {pve} stores user attributes in `/etc/pve/user.cfg`. | |
43 | Passwords are not stored here, users are instead associated with | |
44 | <<pveum_authentication_realms,authentication realms>> described below. | |
45 | Therefore a user is internally often identified by its name and | |
46 | realm in the form `<userid>@<realm>`. | |
47 | ||
48 | Each user entry in this file contains the following information: | |
49 | ||
50 | * First name | |
51 | * Last name | |
52 | * E-mail address | |
53 | * Group memberships | |
54 | * An optional Expiration date | |
55 | * A comment or note about this user | |
56 | * Whether this user is enabled or disabled | |
57 | * Optional two factor authentication keys | |
58 | ||
59 | ||
60 | System administrator | |
61 | ~~~~~~~~~~~~~~~~~~~~ | |
62 | ||
63 | The system's root user can always log in via the Linux PAM realm and is an | |
64 | unconfined administrator. This user cannot be deleted, but attributes can | |
65 | still be changed and system mails will be sent to the email address | |
66 | assigned to this user. | |
67 | ||
68 | ||
69 | [[pveum_groups]] | |
70 | Groups | |
71 | ~~~~~~ | |
72 | ||
73 | Each user can be member of several groups. Groups are the preferred | |
74 | way to organize access permissions. You should always grant permission | |
75 | to groups instead of using individual users. That way you will get a | |
76 | much shorter access control list which is easier to handle. | |
77 | ||
78 | ||
79 | [[pveum_authentication_realms]] | |
80 | Authentication Realms | |
81 | --------------------- | |
82 | ||
83 | As {pve} users are just counterparts for users existing on some external | |
84 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
85 | The following realms (authentication methods) are available: | |
86 | ||
87 | Linux PAM standard authentication:: | |
88 | In this case a system user has to exist (e.g. created via the `adduser` | |
89 | command) on all nodes the user is allowed to login, and the user | |
90 | authenticates with their usual system password. | |
91 | + | |
92 | [source,bash] | |
93 | ---- | |
94 | useradd heinz | |
95 | passwd heinz | |
96 | groupadd watchman | |
97 | usermod -a -G watchman heinz | |
98 | ---- | |
99 | ||
100 | Proxmox VE authentication server:: | |
101 | This is a unix like password store (`/etc/pve/priv/shadow.cfg`). | |
102 | Password are encrypted using the SHA-256 hash method. | |
103 | This is the most convenient method for small (or even medium) | |
104 | installations where users do not need access to anything outside of | |
105 | {pve}. In this case users are fully managed by {pve} and are able to | |
106 | change their own passwords via the GUI. | |
107 | ||
108 | LDAP:: | |
109 | It is possible to authenticate users via an LDAP server (e.g. | |
110 | openldap). The server and an optional fallback server can be | |
111 | configured and the connection can be encrypted via SSL. | |
112 | + | |
113 | Users are searched under a 'Base Domain Name' (`base_dn`), with the | |
114 | user name found in the attribute specified in the 'User Attribute Name' | |
115 | (`user_attr`) field. | |
116 | + | |
117 | For instance, if a user is represented via the | |
118 | following ldif dataset: | |
119 | + | |
120 | ---- | |
121 | # user1 of People at ldap-test.com | |
122 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
123 | objectClass: top | |
124 | objectClass: person | |
125 | objectClass: organizationalPerson | |
126 | objectClass: inetOrgPerson | |
127 | uid: user1 | |
128 | cn: Test User 1 | |
129 | sn: Testers | |
130 | description: This is the first test user. | |
131 | ---- | |
132 | + | |
133 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user | |
134 | attribute would be `uid`. | |
135 | + | |
136 | If {pve} needs to authenticate (bind) to the ldap server before being | |
137 | able to query and authenticate users, a bind domain name can be | |
138 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
139 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
140 | (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a | |
141 | single line containing the raw password. | |
142 | ||
143 | Microsoft Active Directory:: | |
144 | ||
145 | A server and authentication domain need to be specified. Like with | |
146 | ldap an optional fallback server, optional port, and SSL | |
147 | encryption can be configured. | |
148 | ||
149 | ||
150 | [[pveum_tfa_auth]] | |
151 | Two factor authentication | |
152 | ------------------------- | |
153 | ||
154 | There are two ways to use two factor authentication: | |
155 | ||
156 | It can be required by the authentication realm, either via 'TOTP' or | |
157 | 'YubiKey OTP'. In this case a newly created user needs their keys added | |
158 | immediately as there is no way to log in without the second factor. In the case | |
159 | of 'TOTP' a user can also change the 'TOTP' later on provided they can log in | |
160 | first. | |
161 | ||
162 | Alternatively a user can choose to opt into two factor authentication via 'TOTP' | |
163 | later on even if the realm does not enforce it. As another option, if the server | |
164 | has an 'AppId' configured, a user can opt into 'U2F' authentication, provided | |
165 | the realm does not enforce any other second factor. | |
166 | ||
167 | Realm enforced two factor authentication | |
168 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
169 | ||
170 | This can be done by selecting one of the available methods | |
171 | via the 'TFA' dropdown box when adding or editing an Authentication Realm. | |
172 | When a realm has TFA enabled it becomes a requirement and only users with | |
173 | configured TFA will be able to login. | |
174 | ||
175 | Currently there are two methods available: | |
176 | ||
177 | Time based OATH (TOTP):: | |
178 | This uses the standard HMAC-SHA1 algorithm where the current time is hashed | |
179 | with the user's configured key. The time step and password length | |
180 | parameters are configured. | |
181 | + | |
182 | A user can have multiple keys configured (separated by spaces), and the | |
183 | keys can be specified in Base32 (RFC3548) or hexadecimal notation. | |
184 | + | |
185 | {pve} provides a key generation tool (`oathkeygen`) which prints out a | |
186 | random key in Base32 notation which can be used directly with various OTP | |
187 | tools, such as the `oathtool` command line tool, the Google authenticator | |
188 | or FreeOTP Android apps. | |
189 | ||
190 | YubiKey OTP:: | |
191 | For authenticating via a YubiKey a Yubico API ID, API KEY and validation | |
192 | server URL must be configured, and users must have a YubiKey available. In | |
193 | order to get the key ID from a YubiKey, you can trigger the YubiKey once | |
194 | after connecting it to USB and copy the first 12 characters of the typed | |
195 | password into the user's 'Key IDs' field. | |
196 | + | |
197 | Please refer to the | |
198 | https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the | |
199 | https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or | |
200 | https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[ | |
201 | host your own verification server]. | |
202 | ||
203 | [[pveum_user_configured_totp]] | |
204 | User configured TOTP authentication | |
205 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
206 | ||
207 | A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button | |
208 | in the user list, unless the realm enforces 'YubiKey OTP'. | |
209 | ||
210 | [thumbnail="screenshot/gui-datacenter-users-tfa.png"] | |
211 | ||
212 | After opening the 'TFA' window, the user is presented with a dialog to setup | |
213 | 'TOTP' authentication. The 'Secret' field contains the key, which can simply be | |
214 | generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be | |
215 | added to provide information to the 'TOTP' app what the key belongs to. | |
216 | Most 'TOTP' apps will show the issuer name together with the corresponding | |
217 | 'OTP' values. The user name is also included in the QR code for the 'TOTP' app. | |
218 | ||
219 | After generating a key, a QR code will be displayed which can be used with most | |
220 | OTP apps such as FreeOTP. Now the user needs to verify both the current user | |
221 | password (unless logged in as 'root'), as well as the ability to correctly use | |
222 | the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code' | |
223 | field before pressing the 'Apply' button. | |
224 | ||
225 | Server side U2F configuration | |
226 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
227 | ||
228 | To allow users to use 'U2F' authentication, the server needs to have a valid | |
229 | domain with a valid https certificate. Initially an 'AppId' | |
230 | footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] | |
231 | needs to be configured. | |
232 | ||
233 | NOTE: Changing the 'AppId' will render all existing 'U2F' registrations | |
234 | unusable! | |
235 | ||
236 | This is done via `/etc/pve/datacenter.cfg`, for instance: | |
237 | ||
238 | ---- | |
239 | u2f: appid=https://mypve.example.com:8006 | |
240 | ---- | |
241 | ||
242 | For a single node, the 'AppId' can simply be the web UI address exactly as it | |
243 | is used in the browser, including the 'https://' and the port as shown above. | |
244 | Please note that some browsers may be more strict than others when matching | |
245 | 'AppIds'. | |
246 | ||
247 | When using multiple nodes, it is best to have a separate `https` server | |
248 | providing an `appid.json` | |
249 | footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html] | |
250 | file, as it seems to be compatible with most | |
251 | browsers. If all nodes use subdomains of the same top level domain, it may be | |
252 | enough to use the TLD as 'AppId', but note that some browsers may not accept | |
253 | this. | |
254 | ||
255 | NOTE: A bad 'AppId' will usually produce an error, but we have encountered | |
256 | situation where this does not happen, particularly when using a top level domain | |
257 | 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is | |
258 | recommended to test the configuration with multiple browsers, as changing the | |
259 | 'AppId' later will render existing 'U2F' registrations unusable. | |
260 | ||
261 | [[pveum_user_configured_u2f]] | |
262 | Activating U2F as a user | |
263 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
264 | ||
265 | To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the | |
266 | current password (unless logged in as root), and press the 'Register' button. | |
267 | If the server is setup correctly and the browser accepted the server's provided | |
268 | 'AppId', a message will appear prompting the user to press the button on the | |
269 | 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and | |
270 | on steadily around twice per second). | |
271 | ||
272 | Firefox users may need to enable 'security.webauth.u2f' via 'about:config' | |
273 | before they can use a 'U2F' token. | |
274 | ||
275 | [[pveum_permission_management]] | |
276 | Permission Management | |
277 | --------------------- | |
278 | ||
279 | In order for a user to perform an action (such as listing, modifying or | |
280 | deleting a parts of a VM configuration), the user needs to have the | |
281 | appropriate permissions. | |
282 | ||
283 | {pve} uses a role and path based permission management system. An entry in | |
284 | the permissions table allows a user or group to take on a specific role | |
285 | when accessing an 'object' or 'path'. This means an such an access rule can | |
286 | be represented as a triple of '(path, user, role)' or '(path, group, | |
287 | role)', with the role containing a set of allowed actions, and the path | |
288 | representing the target of these actions. | |
289 | ||
290 | ||
291 | [[pveum_roles]] | |
292 | Roles | |
293 | ~~~~~ | |
294 | ||
295 | A role is simply a list of privileges. Proxmox VE comes with a number | |
296 | of predefined roles which satisfies most needs. | |
297 | ||
298 | * `Administrator`: has all privileges | |
299 | * `NoAccess`: has no privileges (used to forbid access) | |
300 | * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). | |
301 | * `PVEAuditor`: read only access | |
302 | * `PVEDatastoreAdmin`: create and allocate backup space and templates | |
303 | * `PVEDatastoreUser`: allocate backup space and view storage | |
304 | * `PVEPoolAdmin`: allocate pools | |
305 | * `PVESysAdmin`: User ACLs, audit, system console and system logs | |
306 | * `PVETemplateUser`: view and clone templates | |
307 | * `PVEUserAdmin`: user administration | |
308 | * `PVEVMAdmin`: fully administer VMs | |
309 | * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management | |
310 | ||
311 | You can see the whole set of predefined roles on the GUI. | |
312 | ||
313 | Adding new roles can be done via both GUI and the command line. | |
314 | ||
315 | [thumbnail="screenshot/gui-datacenter-role-add.png"] | |
316 | For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and | |
317 | click on the 'Create' button, there you can set a name and select all desired | |
318 | roles from the 'Privileges' dropdown box. | |
319 | ||
320 | To add a role through the command line you can use the 'pveum' CLI tool, like | |
321 | this: | |
322 | [source,bash] | |
323 | ---- | |
324 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
325 | pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" | |
326 | ---- | |
327 | ||
328 | ||
329 | Privileges | |
330 | ~~~~~~~~~~ | |
331 | ||
332 | A privilege is the right to perform a specific action. To simplify | |
333 | management, lists of privileges are grouped into roles, which can then | |
334 | be used in the permission table. Note that privileges cannot directly be | |
335 | assigned to users and paths without being part of a role. | |
336 | ||
337 | We currently use the following privileges: | |
338 | ||
339 | Node / System related privileges:: | |
340 | ||
341 | * `Permissions.Modify`: modify access permissions | |
342 | * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...) | |
343 | * `Sys.Console`: console access to Node | |
344 | * `Sys.Syslog`: view Syslog | |
345 | * `Sys.Audit`: view node status/config, Corosync cluster config and HA config | |
346 | * `Sys.Modify`: create/remove/modify node network parameters | |
347 | * `Group.Allocate`: create/remove/modify groups | |
348 | * `Pool.Allocate`: create/remove/modify a pool | |
349 | * `Realm.Allocate`: create/remove/modify authentication realms | |
350 | * `Realm.AllocateUser`: assign user to a realm | |
351 | * `User.Modify`: create/remove/modify user access and details. | |
352 | ||
353 | Virtual machine related privileges:: | |
354 | ||
355 | * `VM.Allocate`: create/remove new VM to server inventory | |
356 | * `VM.Migrate`: migrate VM to alternate server on cluster | |
357 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
358 | * `VM.Console`: console access to VM | |
359 | * `VM.Monitor`: access to VM monitor (kvm) | |
360 | * `VM.Backup`: backup/restore VMs | |
361 | * `VM.Audit`: view VM config | |
362 | * `VM.Clone`: clone/copy a VM | |
363 | * `VM.Config.Disk`: add/modify/delete Disks | |
364 | * `VM.Config.CDROM`: eject/change CDROM | |
365 | * `VM.Config.CPU`: modify CPU settings | |
366 | * `VM.Config.Memory`: modify Memory settings | |
367 | * `VM.Config.Network`: add/modify/delete Network devices | |
368 | * `VM.Config.HWType`: modify emulated HW type | |
369 | * `VM.Config.Options`: modify any other VM configuration | |
370 | * `VM.Snapshot`: create/remove VM snapshots | |
371 | ||
372 | Storage related privileges:: | |
373 | ||
374 | * `Datastore.Allocate`: create/remove/modify a data store, delete volumes | |
375 | * `Datastore.AllocateSpace`: allocate space on a datastore | |
376 | * `Datastore.AllocateTemplate`: allocate/upload templates and iso images | |
377 | * `Datastore.Audit`: view/browse a datastore | |
378 | ||
379 | ||
380 | Objects and Paths | |
381 | ~~~~~~~~~~~~~~~~~ | |
382 | ||
383 | Access permissions are assigned to objects, such as a virtual machines, | |
384 | storages or pools of resources. | |
385 | We use file system like paths to address these objects. These paths form a | |
386 | natural tree, and permissions of higher levels (shorter path) can | |
387 | optionally be propagated down within this hierarchy. | |
388 | ||
389 | [[pveum_templated_paths]] | |
390 | Paths can be templated. When an API call requires permissions on a | |
391 | templated path, the path may contain references to parameters of the API | |
392 | call. These references are specified in curly braces. Some parameters are | |
393 | implicitly taken from the API call's URI. For instance the permission path | |
394 | `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on | |
395 | `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` | |
396 | refers to the method's `path` parameter. | |
397 | ||
398 | Some examples are: | |
399 | ||
400 | * `/nodes/{node}`: Access to {pve} server machines | |
401 | * `/vms`: Covers all VMs | |
402 | * `/vms/{vmid}`: Access to specific VMs | |
403 | * `/storage/{storeid}`: Access to a storages | |
404 | * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>> | |
405 | * `/access/groups`: Group administration | |
406 | * `/access/realms/{realmid}`: Administrative access to realms | |
407 | ||
408 | ||
409 | Inheritance | |
410 | ^^^^^^^^^^^ | |
411 | ||
412 | As mentioned earlier, object paths form a file system like tree, and | |
413 | permissions can be inherited down that tree (the propagate flag is set | |
414 | by default). We use the following inheritance rules: | |
415 | ||
416 | * Permissions for individual users always replace group permissions. | |
417 | * Permissions for groups apply when the user is member of that group. | |
418 | * Permissions replace the ones inherited from an upper level. | |
419 | ||
420 | ||
421 | [[pveum_pools]] | |
422 | Pools | |
423 | ~~~~~ | |
424 | ||
425 | Pools can be used to group a set of virtual machines and data | |
426 | stores. You can then simply set permissions on pools (`/pool/{poolid}`), | |
427 | which are inherited to all pool members. This is a great way simplify | |
428 | access control. | |
429 | ||
430 | ||
431 | What permission do I need? | |
432 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
433 | ||
434 | The required API permissions are documented for each individual | |
435 | method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ | |
436 | ||
437 | The permissions are specified as a list which can be interpreted as a | |
438 | tree of logic and access-check functions: | |
439 | ||
440 | `["and", <subtests>...]` and `["or", <subtests>...]`:: | |
441 | Each(`and`) or any(`or`) further element in the current list has to be true. | |
442 | ||
443 | `["perm", <path>, [ <privileges>... ], <options>...]`:: | |
444 | The `path` is a templated parameter (see | |
445 | <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any` | |
446 | option is used, any) of the listed | |
447 | privileges must be allowed on the specified path. If a `require-param` | |
448 | option is specified, then its specified parameter is required even if the | |
449 | API call's schema otherwise lists it as being optional. | |
450 | ||
451 | `["userid-group", [ <privileges>... ], <options>...]`:: | |
452 | The caller must have any of the listed privileges on `/access/groups`. In | |
453 | addition there are two possible checks depending on whether the | |
454 | `groups_param` option is set: | |
455 | + | |
456 | * `groups_param` is set: The API call has a non-optional `groups` parameter | |
457 | and the caller must have any of the listed privileges on all of the listed | |
458 | groups. | |
459 | * `groups_param` is not set: The user passed via the `userid` parameter | |
460 | must exist and be part of a group on which the caller has any of the listed | |
461 | privileges (via the `/access/groups/<group>` path). | |
462 | ||
463 | `["userid-param", "self"]`:: | |
464 | The value provided for the API call's `userid` parameter must refer to the | |
465 | user performing the action. (Usually in conjunction with `or`, to allow | |
466 | users to perform an action on themselves even if they don't have elevated | |
467 | privileges.) | |
468 | ||
469 | `["userid-param", "Realm.AllocateUser"]`:: | |
470 | The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with | |
471 | `<realm>` referring to the realm of the user passed via the `userid` | |
472 | parameter. Note that the user does not need to exist in order to be | |
473 | associated with a realm, since user IDs are passed in the form of | |
474 | `<username>@<realm>`. | |
475 | ||
476 | `["perm-modify", <path>]`:: | |
477 | The `path` is a templated parameter (see | |
478 | <<pveum_templated_paths,Objects and Paths>>). The user needs either the | |
479 | `Permissions.Modify` privilege, or, | |
480 | depending on the path, the following privileges as a possible substitute: | |
481 | + | |
482 | * `/storage/...`: additionally requires 'Datastore.Allocate` | |
483 | * `/vms/...`: additionally requires 'VM.Allocate` | |
484 | * `/pool/...`: additionally requires 'Pool.Allocate` | |
485 | + | |
486 | If the path is empty, `Permission.Modify` on `/access` is required. | |
487 | ||
488 | Command Line Tool | |
489 | ----------------- | |
490 | ||
491 | Most users will simply use the GUI to manage users. But there is also | |
492 | a fully featured command line tool called `pveum` (short for ``**P**roxmox | |
493 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command | |
494 | line tools are wrappers around the API, so you can also access those | |
495 | functions through the REST API. | |
496 | ||
497 | Here are some simple usage examples. To show help type: | |
498 | ||
499 | [source,bash] | |
500 | pveum | |
501 | ||
502 | or (to show detailed help about a specific command) | |
503 | ||
504 | [source,bash] | |
505 | pveum help useradd | |
506 | ||
507 | Create a new user: | |
508 | ||
509 | [source,bash] | |
510 | pveum useradd testuser@pve -comment "Just a test" | |
511 | ||
512 | Set or Change the password (not all realms support that): | |
513 | ||
514 | [source,bash] | |
515 | pveum passwd testuser@pve | |
516 | ||
517 | Disable a user: | |
518 | ||
519 | [source,bash] | |
520 | pveum usermod testuser@pve -enable 0 | |
521 | ||
522 | Create a new group: | |
523 | ||
524 | [source,bash] | |
525 | pveum groupadd testgroup | |
526 | ||
527 | Create a new role: | |
528 | ||
529 | [source,bash] | |
530 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
531 | ||
532 | ||
533 | Real World Examples | |
534 | ------------------- | |
535 | ||
536 | ||
537 | Administrator Group | |
538 | ~~~~~~~~~~~~~~~~~~~ | |
539 | ||
540 | One of the most wanted features was the ability to define a group of | |
541 | users with full administrator rights (without using the root account). | |
542 | ||
543 | Define the group: | |
544 | ||
545 | [source,bash] | |
546 | pveum groupadd admin -comment "System Administrators" | |
547 | ||
548 | Then add the permission: | |
549 | ||
550 | [source,bash] | |
551 | pveum aclmod / -group admin -role Administrator | |
552 | ||
553 | You can finally add users to the new 'admin' group: | |
554 | ||
555 | [source,bash] | |
556 | pveum usermod testuser@pve -group admin | |
557 | ||
558 | ||
559 | Auditors | |
560 | ~~~~~~~~ | |
561 | ||
562 | You can give read only access to users by assigning the `PVEAuditor` | |
563 | role to users or groups. | |
564 | ||
565 | Example1: Allow user `joe@pve` to see everything | |
566 | ||
567 | [source,bash] | |
568 | pveum aclmod / -user joe@pve -role PVEAuditor | |
569 | ||
570 | Example1: Allow user `joe@pve` to see all virtual machines | |
571 | ||
572 | [source,bash] | |
573 | pveum aclmod /vms -user joe@pve -role PVEAuditor | |
574 | ||
575 | ||
576 | Delegate User Management | |
577 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
578 | ||
579 | If you want to delegate user management to user `joe@pve` you can do | |
580 | that with: | |
581 | ||
582 | [source,bash] | |
583 | pveum aclmod /access -user joe@pve -role PVEUserAdmin | |
584 | ||
585 | User `joe@pve` can now add and remove users, change passwords and | |
586 | other user attributes. This is a very powerful role, and you most | |
587 | likely want to limit that to selected realms and groups. The following | |
588 | example allows `joe@pve` to modify users within realm `pve` if they | |
589 | are members of group `customers`: | |
590 | ||
591 | [source,bash] | |
592 | pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin | |
593 | pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin | |
594 | ||
595 | NOTE: The user is able to add other users, but only if they are | |
596 | members of group `customers` and within realm `pve`. | |
597 | ||
598 | ||
599 | Pools | |
600 | ~~~~~ | |
601 | ||
602 | An enterprise is usually structured into several smaller departments, | |
603 | and it is common that you want to assign resources to them and | |
604 | delegate management tasks. A pool is simply a set of virtual machines | |
605 | and data stores. You can create pools on the GUI. After that you can | |
606 | add resources to the pool (VMs, Storage). | |
607 | ||
608 | You can also assign permissions to the pool. Those permissions are | |
609 | inherited to all pool members. | |
610 | ||
611 | Lets assume you have a software development department, so we first | |
612 | create a group | |
613 | ||
614 | [source,bash] | |
615 | pveum groupadd developers -comment "Our software developers" | |
616 | ||
617 | Now we create a new user which is a member of that group | |
618 | ||
619 | [source,bash] | |
620 | pveum useradd developer1@pve -group developers -password | |
621 | ||
622 | NOTE: The -password parameter will prompt you for a password | |
623 | ||
624 | I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: | |
625 | ||
626 | [source,bash] | |
627 | pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin | |
628 | ||
629 | Our software developers can now administrate the resources assigned to | |
630 | that pool. | |
631 | ||
632 | ||
633 | ifdef::manvolnum[] | |
634 | include::pve-copyright.adoc[] | |
635 | endif::manvolnum[] | |
636 |