]>
Commit | Line | Data |
---|---|---|
80c0adcb | 1 | [[chapter_user_management]] |
3c8533f2 | 2 | ifdef::manvolnum[] |
b2f242ab DM |
3 | pveum(1) |
4 | ======== | |
5f09af76 DM |
5 | :pve-toplevel: |
6 | ||
3c8533f2 DM |
7 | NAME |
8 | ---- | |
9 | ||
10 | pveum - Proxmox VE User Manager | |
11 | ||
12 | ||
49a5e11c | 13 | SYNOPSIS |
3c8533f2 DM |
14 | -------- |
15 | ||
16 | include::pveum.1-synopsis.adoc[] | |
17 | ||
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
21 | endif::manvolnum[] | |
3c8533f2 DM |
22 | ifndef::manvolnum[] |
23 | User Management | |
24 | =============== | |
5f09af76 | 25 | :pve-toplevel: |
194d2f29 | 26 | endif::manvolnum[] |
5f09af76 | 27 | |
3c8533f2 DM |
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 | |
f3ee27eb | 32 | Directory and OpenId Connect. |
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 | |
80c0adcb | 38 | [[pveum_users]] |
c80b9ee6 WB |
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 | |
80c0adcb | 44 | <<pveum_authentication_realms,authentication realms>> described below. |
c80b9ee6 WB |
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 | |
74662f51 | 57 | * Optional two-factor authentication keys |
c80b9ee6 | 58 | |
f06ba6a6 TL |
59 | CAUTION: When you disabled or delete a user, or the expiry date got set and is |
60 | in the past, this user will not be able to log in to new sessions or start new | |
61 | tasks. All tasks which already have been started by this user (for example | |
62 | terminal sessions) will **not** be terminated automatically by any such event. | |
8d02d0a2 | 63 | |
c80b9ee6 WB |
64 | |
65 | System administrator | |
66 | ~~~~~~~~~~~~~~~~~~~~ | |
67 | ||
68 | The system's root user can always log in via the Linux PAM realm and is an | |
69 | unconfined administrator. This user cannot be deleted, but attributes can | |
70 | still be changed and system mails will be sent to the email address | |
71 | assigned to this user. | |
72 | ||
73 | ||
80c0adcb | 74 | [[pveum_groups]] |
c80b9ee6 | 75 | Groups |
a10a91c2 | 76 | ------ |
c80b9ee6 WB |
77 | |
78 | Each user can be member of several groups. Groups are the preferred | |
79 | way to organize access permissions. You should always grant permission | |
80 | to groups instead of using individual users. That way you will get a | |
81 | much shorter access control list which is easier to handle. | |
82 | ||
181db098 FG |
83 | [[pveum_tokens]] |
84 | API Tokens | |
a10a91c2 | 85 | ---------- |
181db098 | 86 | |
710713ea TL |
87 | API tokens allow stateless access to most parts of the REST API by another |
88 | system, software or API client. Tokens can be generated for individual users | |
89 | and can be given separate permissions and expiration dates to limit the scope | |
90 | and duration of the access. Should the API token get compromised it can be | |
91 | revoked without disabling the user itself. | |
181db098 FG |
92 | |
93 | API tokens come in two basic types: | |
94 | ||
95 | * separated privileges: the token needs to be given explicit access with ACLs, | |
96 | its effective permissions are calculated by intersecting user and token | |
97 | permissions. | |
98 | * full privileges: the token permissions are identical to that of the | |
99 | associated user. | |
100 | ||
c6e098a2 TL |
101 | CAUTION: The token value is only displayed/returned once when the token is |
102 | generated. It cannot be retrieved again over the API at a later time! | |
181db098 FG |
103 | |
104 | To use an API token, set the HTTP header 'Authorization' to the displayed value | |
105 | of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or | |
106 | refer to your API client documentation. | |
c80b9ee6 | 107 | |
23b447be DW |
108 | [[pveum_resource_pools]] |
109 | Resource Pools | |
110 | -------------- | |
111 | ||
112 | [thumbnail="screenshot/gui-datacenter-pool-window.png"] | |
113 | ||
114 | A resource pool is a set of virtual machines, containers, and storage | |
115 | devices. It is useful for permission handling in cases where certain users | |
116 | should have controlled access to a specific set of resources, as it allows for a | |
117 | single permission to be applied to a set of elements, rather than having to | |
118 | manage this on a per resource basis. Resource pools are often used in tandem | |
119 | with groups so that the members of a group have permissions on a set of machines | |
120 | and storage. | |
121 | ||
80c0adcb | 122 | [[pveum_authentication_realms]] |
3c8533f2 DM |
123 | Authentication Realms |
124 | --------------------- | |
125 | ||
d6614202 WB |
126 | As {pve} users are just counterparts for users existing on some external |
127 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
128 | The following realms (authentication methods) are available: | |
3c8533f2 DM |
129 | |
130 | Linux PAM standard authentication:: | |
470d4313 | 131 | In this case a system user has to exist (e.g. created via the `adduser` |
d6614202 WB |
132 | command) on all nodes the user is allowed to login, and the user |
133 | authenticates with their usual system password. | |
134 | + | |
3c8533f2 DM |
135 | [source,bash] |
136 | ---- | |
137 | useradd heinz | |
138 | passwd heinz | |
139 | groupadd watchman | |
140 | usermod -a -G watchman heinz | |
141 | ---- | |
142 | ||
143 | Proxmox VE authentication server:: | |
d6614202 WB |
144 | This is a unix like password store (`/etc/pve/priv/shadow.cfg`). |
145 | Password are encrypted using the SHA-256 hash method. | |
44f38275 | 146 | This is the most convenient method for small (or even medium) |
d6614202 WB |
147 | installations where users do not need access to anything outside of |
148 | {pve}. In this case users are fully managed by {pve} and are able to | |
149 | change their own passwords via the GUI. | |
150 | ||
151 | LDAP:: | |
470d4313 | 152 | It is possible to authenticate users via an LDAP server (e.g. |
d6614202 WB |
153 | openldap). The server and an optional fallback server can be |
154 | configured and the connection can be encrypted via SSL. | |
155 | + | |
156 | Users are searched under a 'Base Domain Name' (`base_dn`), with the | |
157 | user name found in the attribute specified in the 'User Attribute Name' | |
158 | (`user_attr`) field. | |
159 | + | |
160 | For instance, if a user is represented via the | |
161 | following ldif dataset: | |
162 | + | |
163 | ---- | |
164 | # user1 of People at ldap-test.com | |
165 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
166 | objectClass: top | |
167 | objectClass: person | |
168 | objectClass: organizationalPerson | |
169 | objectClass: inetOrgPerson | |
170 | uid: user1 | |
171 | cn: Test User 1 | |
172 | sn: Testers | |
173 | description: This is the first test user. | |
174 | ---- | |
175 | + | |
176 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user | |
177 | attribute would be `uid`. | |
178 | + | |
3a433e9b | 179 | If {pve} needs to authenticate (bind) to the LDAP server before being |
d6614202 WB |
180 | able to query and authenticate users, a bind domain name can be |
181 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
182 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
470d4313 | 183 | (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a |
d6614202 | 184 | single line containing the raw password. |
0fb9147a | 185 | + |
4ab527b1 TL |
186 | To verify certificates, you need to to set `capath`. You can set it either |
187 | directly to the CA certificate of your LDAP server, or to the system path | |
188 | containing all trusted CA certificates (`/etc/ssl/certs`). | |
3a433e9b | 189 | Additionally, you need to set the `verify` option, which can also be done over |
4ab527b1 | 190 | the web interface. |
d6614202 WB |
191 | |
192 | Microsoft Active Directory:: | |
3c8533f2 | 193 | |
3a433e9b OB |
194 | A server and authentication domain need to be specified. Like with LDAP, an |
195 | optional fallback server, port, and SSL encryption can be configured. | |
3c8533f2 | 196 | |
f3ee27eb DM |
197 | OpenId Connect:: |
198 | ||
199 | OpenID Connect allows clients to verify the identity of the user based | |
200 | on the authentication performed by an external authorization | |
201 | server. | |
202 | ||
203 | ||
204 | [[pveum_openid]] | |
205 | OpenId Connect | |
206 | ~~~~~~~~~~~~~~ | |
207 | ||
208 | The main OpenID Connect configuration options are: | |
209 | ||
210 | * `issuer-url`: This is the Url to the authorization server. Proxmox | |
211 | uses the OpenID Connect Discovery protocol to automatiocally configure | |
212 | further details. | |
213 | + | |
214 | While it is possible to use unencrypted `http://` Urls, we strongly recommend to | |
215 | use encrypted `https://` connections. | |
216 | ||
217 | * `client-id`: OpenID Client ID. | |
218 | ||
219 | * `client-key`: Optional OpenID Client Key. | |
220 | ||
221 | * `autocreate`: Automatically create users if they do not exist. While | |
62547dfa | 222 | authentication is done at the OpenID server, all users still need an |
f3ee27eb DM |
223 | entry in the {pve} user configuration. You can either add them |
224 | manually, or use the `autocreate` option to automatically add new | |
225 | users. | |
226 | ||
227 | * `username-claim`: OpenID claim used to generate the unique username | |
228 | (`subject`, `username` or `email`). | |
229 | ||
230 | Username mapping | |
231 | ^^^^^^^^^^^^^^^^ | |
232 | ||
233 | The Openid Connect specification defines a single unique attribute | |
234 | ('claim' in OpenId terms) named `subject`. By default, we use the | |
235 | value of this attribute to generate {pve} usernames, by simple adding | |
236 | `@` and the realm name: `${subject}@${realm}`. | |
237 | ||
238 | Unfortunately, most OpenID server use random strings for `subject`, like | |
239 | `DGH76OKH34BNG3245SB`, so a typical username would look like | |
240 | `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is really hard for | |
241 | humans to remember such random strings, making it quite impossible to | |
242 | associate real users with that. | |
243 | ||
244 | The `username-claim` setting allows you to use other attributes for | |
245 | the username mapping. Setting it to `username` is preferred, if the | |
62547dfa | 246 | OpenId Connect server provides that attribute and guarantee its |
f3ee27eb DM |
247 | uniqueness. |
248 | ||
249 | Another option is to use `email`, which also yields to human readable | |
62547dfa | 250 | usernames. Again, only use this setting if the server guarantees the |
f3ee27eb DM |
251 | uniqueness of this attribute. |
252 | ||
253 | Examples | |
254 | ^^^^^^^^ | |
255 | ||
256 | Here is an example to create an OpenId realm using Google. You need to | |
257 | replace `--client-id` and `--client-key` with the values | |
258 | from your Google OpenId settings. | |
259 | ||
260 | ---- | |
261 | pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email | |
262 | ---- | |
263 | ||
264 | Above setup uses `--username-claim email`, so the usernames at the | |
265 | {pve} side looks like `example.user@google.com@myrealm1`. | |
266 | ||
267 | KeyCloak (https://www.keycloak.org/) is a popular Open Source Identity | |
268 | and Access Management supporting OpenId Connect. In the following | |
269 | example, you need to replace the `--issuer-url` and `--client-id` with | |
270 | your setting: | |
271 | ||
272 | ---- | |
273 | pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username | |
274 | ---- | |
275 | ||
276 | Using `--username-claim username` yields to simple usernames on the | |
277 | {pve} side, like `example.user@myrealm2`. | |
278 | ||
279 | WARNING: You need to make sure that the user is not allowed to edit | |
280 | the username setting himself (on the Keycloak server). | |
281 | ||
282 | ||
a160926a DC |
283 | [[pveum_ldap_sync]] |
284 | Syncing LDAP-based realms | |
285 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
286 | ||
41c386ba TL |
287 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"] |
288 | ||
f5eb2299 TL |
289 | It is possible to sync users and groups for LDAP based realms. You can use the |
290 | CLI command | |
291 | ||
292 | ---- | |
8ab21a40 | 293 | pveum realm sync <realm> |
f5eb2299 TL |
294 | ---- |
295 | or in the `Authentication` panel of the GUI. Users and groups are synced to the | |
296 | cluster-wide user configuration file `/etc/pve/user.cfg`. | |
a160926a DC |
297 | |
298 | Requirements and limitations | |
299 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
300 | ||
f5eb2299 TL |
301 | The `bind_dn` is used to query the users and groups. This account needs access |
302 | to all desired entries. | |
a160926a DC |
303 | |
304 | The fields which represent the names of the users and groups can be configured | |
305 | via the `user_attr` and `group_name_attr` respectively. Only entries which | |
306 | adhere to the usual character limitations of the user.cfg are synced. | |
307 | ||
308 | Groups are synced with `-$realm` attached to the name, to avoid naming | |
309 | conflicts. Please make sure that a sync does not overwrite manually created | |
310 | groups. | |
311 | ||
f5eb2299 | 312 | [[pveum_ldap_sync_options]] |
a160926a DC |
313 | Options |
314 | ^^^^^^^ | |
315 | ||
41c386ba TL |
316 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"] |
317 | ||
a160926a DC |
318 | The main options for syncing are: |
319 | ||
320 | * `dry-run`: No data is written to the config. This is useful if you want to | |
321 | see which users and groups would get synced to the user.cfg. This is set | |
322 | when you click `Preview` in the GUI. | |
323 | ||
324 | * `enable-new`: If set, the newly synced users are enabled and can login. | |
325 | The default is `true`. | |
326 | ||
327 | * `full`: If set, the sync uses the LDAP Directory as a source of truth, | |
328 | overwriting information set manually in the user.cfg and deletes users | |
329 | and groups which are not present in the LDAP directory. If not set, | |
330 | only new data is written to the config, and no stale users are deleted. | |
331 | ||
332 | * `purge`: If set, sync removes all corresponding ACLs when removing users | |
333 | and groups. This is only useful with the option `full`. | |
334 | ||
335 | * `scope`: The scope of what to sync. It can be either `users`, `groups` or | |
336 | `both`. | |
337 | ||
338 | These options are either set as parameters or as defaults, via the | |
339 | realm option `sync-defaults-options`. | |
5eba0743 | 340 | |
0523992b | 341 | [[pveum_tfa_auth]] |
74662f51 | 342 | Two-factor authentication |
9e8f2770 WB |
343 | ------------------------- |
344 | ||
74662f51 | 345 | There are two ways to use two-factor authentication: |
2837cf1d | 346 | |
74662f51 OB |
347 | It can be required by the authentication realm, either via 'TOTP' |
348 | (Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly | |
349 | created user needs their keys added immediately as there is no way to | |
350 | log in without the second factor. In the case of 'TOTP', users can | |
351 | also change the 'TOTP' later on, provided they can log in first. | |
2837cf1d | 352 | |
74662f51 OB |
353 | Alternatively, users can choose to opt in to two-factor authentication |
354 | via 'TOTP' later on, even if the realm does not enforce it. As another | |
355 | option, if the server has an 'AppId' configured, a user can opt into | |
356 | 'U2F' authentication, provided the realm does not enforce any other | |
357 | second factor. | |
2837cf1d | 358 | |
74662f51 | 359 | Realm enforced two-factor authentication |
2837cf1d WB |
360 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
361 | ||
74662f51 OB |
362 | This can be done by selecting one of the available methods via the |
363 | 'TFA' dropdown box when adding or editing an Authentication Realm. | |
364 | When a realm has TFA enabled it becomes a requirement and only users | |
365 | with configured TFA will be able to login. | |
9e8f2770 WB |
366 | |
367 | Currently there are two methods available: | |
368 | ||
74662f51 OB |
369 | Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm |
370 | where the current time is hashed with the user's configured key. The | |
371 | time step and password length parameters are configured. | |
9e8f2770 | 372 | + |
74662f51 OB |
373 | A user can have multiple keys configured (separated by spaces), and the keys |
374 | can be specified in Base32 (RFC3548) or hexadecimal notation. | |
9e8f2770 | 375 | + |
74662f51 OB |
376 | {pve} provides a key generation tool (`oathkeygen`) which prints out a random |
377 | key in Base32 notation which can be used directly with various OTP tools, such | |
378 | as the `oathtool` command line tool, or on Android Google Authenticator, | |
379 | FreeOTP, andOTP or similar applications. | |
9e8f2770 WB |
380 | |
381 | YubiKey OTP:: | |
382 | For authenticating via a YubiKey a Yubico API ID, API KEY and validation | |
383 | server URL must be configured, and users must have a YubiKey available. In | |
384 | order to get the key ID from a YubiKey, you can trigger the YubiKey once | |
385 | after connecting it to USB and copy the first 12 characters of the typed | |
386 | password into the user's 'Key IDs' field. | |
74662f51 | 387 | |
9e8f2770 | 388 | + |
74662f51 OB |
389 | Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP] |
390 | documentation for how to use the | |
9e8f2770 | 391 | https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or |
88636df1 | 392 | https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host |
74662f51 | 393 | your own verification server]. |
9e8f2770 | 394 | |
0523992b | 395 | [[pveum_user_configured_totp]] |
2837cf1d WB |
396 | User configured TOTP authentication |
397 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
398 | ||
74662f51 OB |
399 | Users can choose to enable 'TOTP' as a second factor on login via the 'TFA' |
400 | button in the user list (unless the realm enforces 'YubiKey OTP'). | |
2837cf1d | 401 | |
2b59fcfb TL |
402 | [thumbnail="screenshot/gui-datacenter-users-tfa.png"] |
403 | ||
2837cf1d WB |
404 | After opening the 'TFA' window, the user is presented with a dialog to setup |
405 | 'TOTP' authentication. The 'Secret' field contains the key, which can simply be | |
406 | generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be | |
407 | added to provide information to the 'TOTP' app what the key belongs to. | |
408 | Most 'TOTP' apps will show the issuer name together with the corresponding | |
409 | 'OTP' values. The user name is also included in the QR code for the 'TOTP' app. | |
410 | ||
411 | After generating a key, a QR code will be displayed which can be used with most | |
412 | OTP apps such as FreeOTP. Now the user needs to verify both the current user | |
413 | password (unless logged in as 'root'), as well as the ability to correctly use | |
414 | the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code' | |
415 | field before pressing the 'Apply' button. | |
416 | ||
97d63abc | 417 | [[pveum_configure_u2f]] |
2837cf1d WB |
418 | Server side U2F configuration |
419 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
420 | ||
58df830b DC |
421 | To allow users to use 'U2F' authentication, it may be necessary to use a valid |
422 | domain with a valid https certificate, otherwise some browsers may print | |
423 | a warning or reject U2F usage altogether. Initially an 'AppId' | |
2837cf1d WB |
424 | footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] |
425 | needs to be configured. | |
426 | ||
427 | NOTE: Changing the 'AppId' will render all existing 'U2F' registrations | |
428 | unusable! | |
429 | ||
430 | This is done via `/etc/pve/datacenter.cfg`, for instance: | |
431 | ||
432 | ---- | |
433 | u2f: appid=https://mypve.example.com:8006 | |
434 | ---- | |
435 | ||
436 | For a single node, the 'AppId' can simply be the web UI address exactly as it | |
437 | is used in the browser, including the 'https://' and the port as shown above. | |
438 | Please note that some browsers may be more strict than others when matching | |
439 | 'AppIds'. | |
440 | ||
441 | When using multiple nodes, it is best to have a separate `https` server | |
442 | providing an `appid.json` | |
443 | footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html] | |
444 | file, as it seems to be compatible with most | |
445 | browsers. If all nodes use subdomains of the same top level domain, it may be | |
446 | enough to use the TLD as 'AppId', but note that some browsers may not accept | |
447 | this. | |
448 | ||
449 | NOTE: A bad 'AppId' will usually produce an error, but we have encountered | |
450 | situation where this does not happen, particularly when using a top level domain | |
451 | 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is | |
452 | recommended to test the configuration with multiple browsers, as changing the | |
453 | 'AppId' later will render existing 'U2F' registrations unusable. | |
454 | ||
0523992b | 455 | [[pveum_user_configured_u2f]] |
2837cf1d WB |
456 | Activating U2F as a user |
457 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
458 | ||
459 | To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the | |
460 | current password (unless logged in as root), and press the 'Register' button. | |
461 | If the server is setup correctly and the browser accepted the server's provided | |
462 | 'AppId', a message will appear prompting the user to press the button on the | |
463 | 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and | |
464 | on steadily around twice per second). | |
465 | ||
466 | Firefox users may need to enable 'security.webauth.u2f' via 'about:config' | |
467 | before they can use a 'U2F' token. | |
9e8f2770 | 468 | |
80c0adcb | 469 | [[pveum_permission_management]] |
04f44730 | 470 | Permission Management |
3c8533f2 DM |
471 | --------------------- |
472 | ||
04f44730 WB |
473 | In order for a user to perform an action (such as listing, modifying or |
474 | deleting a parts of a VM configuration), the user needs to have the | |
475 | appropriate permissions. | |
476 | ||
477 | {pve} uses a role and path based permission management system. An entry in | |
181db098 | 478 | the permissions table allows a user, group or token to take on a specific role |
04f44730 | 479 | when accessing an 'object' or 'path'. This means an such an access rule can |
181db098 FG |
480 | be represented as a triple of '(path, user, role)', '(path, group, |
481 | role)' or '(path, token, role)', with the role containing a set of allowed | |
482 | actions, and the path representing the target of these actions. | |
04f44730 | 483 | |
5eba0743 | 484 | |
80c0adcb | 485 | [[pveum_roles]] |
853d288b WB |
486 | Roles |
487 | ~~~~~ | |
488 | ||
489 | A role is simply a list of privileges. Proxmox VE comes with a number | |
490 | of predefined roles which satisfies most needs. | |
491 | ||
492 | * `Administrator`: has all privileges | |
493 | * `NoAccess`: has no privileges (used to forbid access) | |
494 | * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). | |
495 | * `PVEAuditor`: read only access | |
496 | * `PVEDatastoreAdmin`: create and allocate backup space and templates | |
497 | * `PVEDatastoreUser`: allocate backup space and view storage | |
498 | * `PVEPoolAdmin`: allocate pools | |
499 | * `PVESysAdmin`: User ACLs, audit, system console and system logs | |
500 | * `PVETemplateUser`: view and clone templates | |
501 | * `PVEUserAdmin`: user administration | |
502 | * `PVEVMAdmin`: fully administer VMs | |
3a433e9b | 503 | * `PVEVMUser`: view, backup, config CD-ROM, VM console, VM power management |
853d288b WB |
504 | |
505 | You can see the whole set of predefined roles on the GUI. | |
506 | ||
5e6b02ff TL |
507 | Adding new roles can be done via both GUI and the command line. |
508 | ||
509 | [thumbnail="screenshot/gui-datacenter-role-add.png"] | |
510 | For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and | |
511 | click on the 'Create' button, there you can set a name and select all desired | |
512 | roles from the 'Privileges' dropdown box. | |
853d288b | 513 | |
5e6b02ff TL |
514 | To add a role through the command line you can use the 'pveum' CLI tool, like |
515 | this: | |
853d288b WB |
516 | [source,bash] |
517 | ---- | |
518 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
519 | pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" | |
520 | ---- | |
521 | ||
522 | ||
3c8533f2 DM |
523 | Privileges |
524 | ~~~~~~~~~~ | |
525 | ||
526 | A privilege is the right to perform a specific action. To simplify | |
527 | management, lists of privileges are grouped into roles, which can then | |
0e1fda70 WB |
528 | be used in the permission table. Note that privileges cannot directly be |
529 | assigned to users and paths without being part of a role. | |
3c8533f2 DM |
530 | |
531 | We currently use the following privileges: | |
532 | ||
533 | Node / System related privileges:: | |
534 | ||
535 | * `Permissions.Modify`: modify access permissions | |
536 | * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...) | |
537 | * `Sys.Console`: console access to Node | |
538 | * `Sys.Syslog`: view Syslog | |
ced79689 | 539 | * `Sys.Audit`: view node status/config, Corosync cluster config and HA config |
3c8533f2 DM |
540 | * `Sys.Modify`: create/remove/modify node network parameters |
541 | * `Group.Allocate`: create/remove/modify groups | |
542 | * `Pool.Allocate`: create/remove/modify a pool | |
696ebb3c | 543 | * `Pool.Audit`: view a pool |
3c8533f2 DM |
544 | * `Realm.Allocate`: create/remove/modify authentication realms |
545 | * `Realm.AllocateUser`: assign user to a realm | |
546 | * `User.Modify`: create/remove/modify user access and details. | |
547 | ||
548 | Virtual machine related privileges:: | |
549 | ||
550 | * `VM.Allocate`: create/remove new VM to server inventory | |
551 | * `VM.Migrate`: migrate VM to alternate server on cluster | |
552 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
553 | * `VM.Console`: console access to VM | |
554 | * `VM.Monitor`: access to VM monitor (kvm) | |
555 | * `VM.Backup`: backup/restore VMs | |
556 | * `VM.Audit`: view VM config | |
557 | * `VM.Clone`: clone/copy a VM | |
558 | * `VM.Config.Disk`: add/modify/delete Disks | |
3a433e9b | 559 | * `VM.Config.CDROM`: eject/change CD-ROM |
3c8533f2 DM |
560 | * `VM.Config.CPU`: modify CPU settings |
561 | * `VM.Config.Memory`: modify Memory settings | |
562 | * `VM.Config.Network`: add/modify/delete Network devices | |
563 | * `VM.Config.HWType`: modify emulated HW type | |
564 | * `VM.Config.Options`: modify any other VM configuration | |
565 | * `VM.Snapshot`: create/remove VM snapshots | |
566 | ||
567 | Storage related privileges:: | |
568 | ||
569 | * `Datastore.Allocate`: create/remove/modify a data store, delete volumes | |
570 | * `Datastore.AllocateSpace`: allocate space on a datastore | |
571 | * `Datastore.AllocateTemplate`: allocate/upload templates and iso images | |
572 | * `Datastore.Audit`: view/browse a datastore | |
573 | ||
5eba0743 | 574 | |
b8eeec52 WB |
575 | Objects and Paths |
576 | ~~~~~~~~~~~~~~~~~ | |
577 | ||
578 | Access permissions are assigned to objects, such as a virtual machines, | |
579 | storages or pools of resources. | |
580 | We use file system like paths to address these objects. These paths form a | |
581 | natural tree, and permissions of higher levels (shorter path) can | |
582 | optionally be propagated down within this hierarchy. | |
583 | ||
7d48940b | 584 | [[pveum_templated_paths]] |
b8eeec52 WB |
585 | Paths can be templated. When an API call requires permissions on a |
586 | templated path, the path may contain references to parameters of the API | |
587 | call. These references are specified in curly braces. Some parameters are | |
588 | implicitly taken from the API call's URI. For instance the permission path | |
589 | `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on | |
590 | `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` | |
591 | refers to the method's `path` parameter. | |
592 | ||
593 | Some examples are: | |
594 | ||
595 | * `/nodes/{node}`: Access to {pve} server machines | |
596 | * `/vms`: Covers all VMs | |
597 | * `/vms/{vmid}`: Access to specific VMs | |
598 | * `/storage/{storeid}`: Access to a storages | |
7d48940b | 599 | * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>> |
b8eeec52 WB |
600 | * `/access/groups`: Group administration |
601 | * `/access/realms/{realmid}`: Administrative access to realms | |
602 | ||
603 | ||
3c8533f2 DM |
604 | Inheritance |
605 | ^^^^^^^^^^^ | |
606 | ||
5eba0743 | 607 | As mentioned earlier, object paths form a file system like tree, and |
3c8533f2 DM |
608 | permissions can be inherited down that tree (the propagate flag is set |
609 | by default). We use the following inheritance rules: | |
610 | ||
74936daf WB |
611 | * Permissions for individual users always replace group permissions. |
612 | * Permissions for groups apply when the user is member of that group. | |
613 | * Permissions replace the ones inherited from an upper level. | |
3c8533f2 | 614 | |
181db098 FG |
615 | Additionally, privilege separated tokens can never have a permission on any |
616 | given path that their associated user does not have. | |
5eba0743 | 617 | |
80c0adcb | 618 | [[pveum_pools]] |
3c8533f2 DM |
619 | Pools |
620 | ~~~~~ | |
621 | ||
622 | Pools can be used to group a set of virtual machines and data | |
8c1189b6 | 623 | stores. You can then simply set permissions on pools (`/pool/{poolid}`), |
3c8533f2 DM |
624 | which are inherited to all pool members. This is a great way simplify |
625 | access control. | |
626 | ||
74936daf WB |
627 | |
628 | What permission do I need? | |
629 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
630 | ||
631 | The required API permissions are documented for each individual | |
a55d30db | 632 | method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/ |
74936daf WB |
633 | |
634 | The permissions are specified as a list which can be interpreted as a | |
635 | tree of logic and access-check functions: | |
636 | ||
637 | `["and", <subtests>...]` and `["or", <subtests>...]`:: | |
638 | Each(`and`) or any(`or`) further element in the current list has to be true. | |
639 | ||
640 | `["perm", <path>, [ <privileges>... ], <options>...]`:: | |
7d48940b | 641 | The `path` is a templated parameter (see |
87ba80b0 | 642 | <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any` |
7d48940b | 643 | option is used, any) of the listed |
74936daf WB |
644 | privileges must be allowed on the specified path. If a `require-param` |
645 | option is specified, then its specified parameter is required even if the | |
646 | API call's schema otherwise lists it as being optional. | |
647 | ||
648 | `["userid-group", [ <privileges>... ], <options>...]`:: | |
470d4313 | 649 | The caller must have any of the listed privileges on `/access/groups`. In |
74936daf WB |
650 | addition there are two possible checks depending on whether the |
651 | `groups_param` option is set: | |
652 | + | |
653 | * `groups_param` is set: The API call has a non-optional `groups` parameter | |
654 | and the caller must have any of the listed privileges on all of the listed | |
655 | groups. | |
656 | * `groups_param` is not set: The user passed via the `userid` parameter | |
657 | must exist and be part of a group on which the caller has any of the listed | |
658 | privileges (via the `/access/groups/<group>` path). | |
659 | ||
660 | `["userid-param", "self"]`:: | |
661 | The value provided for the API call's `userid` parameter must refer to the | |
662 | user performing the action. (Usually in conjunction with `or`, to allow | |
663 | users to perform an action on themselves even if they don't have elevated | |
664 | privileges.) | |
665 | ||
666 | `["userid-param", "Realm.AllocateUser"]`:: | |
667 | The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with | |
470d4313 | 668 | `<realm>` referring to the realm of the user passed via the `userid` |
74936daf WB |
669 | parameter. Note that the user does not need to exist in order to be |
670 | associated with a realm, since user IDs are passed in the form of | |
671 | `<username>@<realm>`. | |
672 | ||
673 | `["perm-modify", <path>]`:: | |
7d48940b DM |
674 | The `path` is a templated parameter (see |
675 | <<pveum_templated_paths,Objects and Paths>>). The user needs either the | |
676 | `Permissions.Modify` privilege, or, | |
74936daf WB |
677 | depending on the path, the following privileges as a possible substitute: |
678 | + | |
679 | * `/storage/...`: additionally requires 'Datastore.Allocate` | |
680 | * `/vms/...`: additionally requires 'VM.Allocate` | |
681 | * `/pool/...`: additionally requires 'Pool.Allocate` | |
682 | + | |
683 | If the path is empty, `Permission.Modify` on `/access` is required. | |
684 | ||
3c8533f2 DM |
685 | Command Line Tool |
686 | ----------------- | |
687 | ||
688 | Most users will simply use the GUI to manage users. But there is also | |
87ba80b0 | 689 | a fully featured command line tool called `pveum` (short for ``**P**roxmox |
4f6e7e05 WB |
690 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command |
691 | line tools are wrappers around the API, so you can also access those | |
87ba80b0 | 692 | functions through the REST API. |
3c8533f2 DM |
693 | |
694 | Here are some simple usage examples. To show help type: | |
695 | ||
696 | [source,bash] | |
697 | pveum | |
698 | ||
699 | or (to show detailed help about a specific command) | |
700 | ||
701 | [source,bash] | |
9135e321 | 702 | pveum help user add |
3c8533f2 DM |
703 | |
704 | Create a new user: | |
705 | ||
706 | [source,bash] | |
9135e321 | 707 | pveum user add testuser@pve -comment "Just a test" |
3c8533f2 DM |
708 | |
709 | Set or Change the password (not all realms support that): | |
710 | ||
711 | [source,bash] | |
712 | pveum passwd testuser@pve | |
713 | ||
714 | Disable a user: | |
715 | ||
716 | [source,bash] | |
9135e321 | 717 | pveum user modify testuser@pve -enable 0 |
3c8533f2 DM |
718 | |
719 | Create a new group: | |
720 | ||
721 | [source,bash] | |
9135e321 | 722 | pveum group add testgroup |
3c8533f2 DM |
723 | |
724 | Create a new role: | |
725 | ||
726 | [source,bash] | |
9135e321 | 727 | pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console" |
3c8533f2 DM |
728 | |
729 | ||
730 | Real World Examples | |
731 | ------------------- | |
732 | ||
5eba0743 | 733 | |
3c8533f2 DM |
734 | Administrator Group |
735 | ~~~~~~~~~~~~~~~~~~~ | |
736 | ||
737 | One of the most wanted features was the ability to define a group of | |
5eba0743 | 738 | users with full administrator rights (without using the root account). |
3c8533f2 DM |
739 | |
740 | Define the group: | |
741 | ||
742 | [source,bash] | |
9135e321 | 743 | pveum group add admin -comment "System Administrators" |
3c8533f2 DM |
744 | |
745 | Then add the permission: | |
746 | ||
747 | [source,bash] | |
9135e321 | 748 | pveum acl modify / -group admin -role Administrator |
3c8533f2 DM |
749 | |
750 | You can finally add users to the new 'admin' group: | |
751 | ||
752 | [source,bash] | |
9135e321 | 753 | pveum user modify testuser@pve -group admin |
3c8533f2 DM |
754 | |
755 | ||
756 | Auditors | |
757 | ~~~~~~~~ | |
758 | ||
759 | You can give read only access to users by assigning the `PVEAuditor` | |
760 | role to users or groups. | |
761 | ||
8c1189b6 | 762 | Example1: Allow user `joe@pve` to see everything |
3c8533f2 DM |
763 | |
764 | [source,bash] | |
9135e321 | 765 | pveum acl modify / -user joe@pve -role PVEAuditor |
3c8533f2 | 766 | |
8c1189b6 | 767 | Example1: Allow user `joe@pve` to see all virtual machines |
3c8533f2 DM |
768 | |
769 | [source,bash] | |
9135e321 | 770 | pveum acl modify /vms -user joe@pve -role PVEAuditor |
3c8533f2 | 771 | |
5eba0743 | 772 | |
3c8533f2 DM |
773 | Delegate User Management |
774 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
775 | ||
470d4313 | 776 | If you want to delegate user management to user `joe@pve` you can do |
3c8533f2 DM |
777 | that with: |
778 | ||
779 | [source,bash] | |
9135e321 | 780 | pveum acl modify /access -user joe@pve -role PVEUserAdmin |
3c8533f2 | 781 | |
8c1189b6 | 782 | User `joe@pve` can now add and remove users, change passwords and |
3c8533f2 DM |
783 | other user attributes. This is a very powerful role, and you most |
784 | likely want to limit that to selected realms and groups. The following | |
8c1189b6 FG |
785 | example allows `joe@pve` to modify users within realm `pve` if they |
786 | are members of group `customers`: | |
3c8533f2 DM |
787 | |
788 | [source,bash] | |
9135e321 TL |
789 | pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin |
790 | pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin | |
3c8533f2 | 791 | |
0abc65b0 | 792 | NOTE: The user is able to add other users, but only if they are |
8c1189b6 FG |
793 | members of group `customers` and within realm `pve`. |
794 | ||
181db098 FG |
795 | Limited API token for monitoring |
796 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
797 | ||
798 | Given a user `joe@pve` with the PVEVMAdmin role on all VMs: | |
799 | ||
800 | [source,bash] | |
9135e321 | 801 | pveum acl modify /vms -user joe@pve -role PVEVMAdmin |
181db098 FG |
802 | |
803 | Add a new API token with separate privileges, which is only allowed to view VM | |
804 | information (e.g., for monitoring purposes): | |
805 | ||
806 | [source,bash] | |
807 | pveum user token add joe@pve monitoring -privsep 1 | |
9135e321 | 808 | pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor |
181db098 FG |
809 | |
810 | Verify the permissions of the user and token: | |
811 | ||
812 | [source,bash] | |
813 | pveum user permissions joe@pve | |
814 | pveum user token permissions joe@pve monitoring | |
3c8533f2 | 815 | |
23b447be DW |
816 | Resource Pools |
817 | ~~~~~~~~~~~~~~ | |
3c8533f2 | 818 | |
23b447be DW |
819 | An enterprise is usually structured into several smaller departments, and it is |
820 | common that you want to assign resources and delegate management tasks to each | |
821 | of these. Let's assume that you want to set up a pool for a software development | |
822 | department. First, create a group | |
3c8533f2 DM |
823 | |
824 | [source,bash] | |
9135e321 | 825 | pveum group add developers -comment "Our software developers" |
3c8533f2 DM |
826 | |
827 | Now we create a new user which is a member of that group | |
828 | ||
829 | [source,bash] | |
9135e321 | 830 | pveum user add developer1@pve -group developers -password |
3c8533f2 | 831 | |
0abc65b0 | 832 | NOTE: The -password parameter will prompt you for a password |
3c8533f2 | 833 | |
23b447be DW |
834 | Then we create a resource pool for our development department to use |
835 | ||
836 | [source,bash] | |
9135e321 | 837 | pveum pool add dev-pool --comment "IT development pool" |
23b447be DW |
838 | |
839 | Finally, we can assign permissions to that pool | |
3c8533f2 DM |
840 | |
841 | [source,bash] | |
9135e321 | 842 | pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin |
3c8533f2 DM |
843 | |
844 | Our software developers can now administrate the resources assigned to | |
845 | that pool. | |
846 | ||
847 | ||
848 | ifdef::manvolnum[] | |
849 | include::pve-copyright.adoc[] | |
850 | endif::manvolnum[] | |
851 |