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 | |
5eba0743 FG |
35 | objects (VMs, storages, nodes, etc.) granular access can be defined. |
36 | ||
3c8533f2 | 37 | |
d6614202 | 38 | [[authentication-realms]] |
3c8533f2 DM |
39 | Authentication Realms |
40 | --------------------- | |
41 | ||
d6614202 WB |
42 | As {pve} users are just counterparts for users existing on some external |
43 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
44 | The following realms (authentication methods) are available: | |
3c8533f2 DM |
45 | |
46 | Linux PAM standard authentication:: | |
d6614202 WB |
47 | In this case a system user has to exist (eg. created via the `adduser` |
48 | command) on all nodes the user is allowed to login, and the user | |
49 | authenticates with their usual system password. | |
50 | + | |
3c8533f2 DM |
51 | [source,bash] |
52 | ---- | |
53 | useradd heinz | |
54 | passwd heinz | |
55 | groupadd watchman | |
56 | usermod -a -G watchman heinz | |
57 | ---- | |
58 | ||
59 | Proxmox VE authentication server:: | |
d6614202 WB |
60 | This is a unix like password store (`/etc/pve/priv/shadow.cfg`). |
61 | Password are encrypted using the SHA-256 hash method. | |
62 | This is the most convenient method for for small (or even medium) | |
63 | installations where users do not need access to anything outside of | |
64 | {pve}. In this case users are fully managed by {pve} and are able to | |
65 | change their own passwords via the GUI. | |
66 | ||
67 | LDAP:: | |
68 | It is possible to authenticate users via an LDAP server (eq. | |
69 | openldap). The server and an optional fallback server can be | |
70 | configured and the connection can be encrypted via SSL. | |
71 | + | |
72 | Users are searched under a 'Base Domain Name' (`base_dn`), with the | |
73 | user name found in the attribute specified in the 'User Attribute Name' | |
74 | (`user_attr`) field. | |
75 | + | |
76 | For instance, if a user is represented via the | |
77 | following ldif dataset: | |
78 | + | |
79 | ---- | |
80 | # user1 of People at ldap-test.com | |
81 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
82 | objectClass: top | |
83 | objectClass: person | |
84 | objectClass: organizationalPerson | |
85 | objectClass: inetOrgPerson | |
86 | uid: user1 | |
87 | cn: Test User 1 | |
88 | sn: Testers | |
89 | description: This is the first test user. | |
90 | ---- | |
91 | + | |
92 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user | |
93 | attribute would be `uid`. | |
94 | + | |
95 | If {pve} needs to authenticate (bind) to the ldap server before being | |
96 | able to query and authenticate users, a bind domain name can be | |
97 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
98 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
99 | (eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a | |
100 | single line containing the raw password. | |
101 | ||
102 | Microsoft Active Directory:: | |
3c8533f2 | 103 | |
d6614202 WB |
104 | A server and authentication domain need to be specified. Like with |
105 | ldap an optional fallback server, optional port, and SSL | |
106 | encryption can be configured. | |
3c8533f2 | 107 | |
5eba0743 | 108 | |
3c8533f2 DM |
109 | Terms and Definitions |
110 | --------------------- | |
111 | ||
5eba0743 | 112 | |
3c8533f2 DM |
113 | Users |
114 | ~~~~~ | |
115 | ||
116 | A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The | |
117 | login screen on the GUI shows them a separate items, but it is | |
118 | internally used as single string. | |
119 | ||
8c1189b6 | 120 | We store the following attribute for users (`/etc/pve/user.cfg`): |
3c8533f2 DM |
121 | |
122 | * first name | |
123 | * last name | |
124 | * email address | |
125 | * expiration date | |
126 | * flag to enable/disable account | |
127 | * comment | |
128 | ||
5eba0743 | 129 | |
3c8533f2 DM |
130 | Superuser |
131 | ^^^^^^^^^ | |
132 | ||
8c1189b6 | 133 | The traditional unix superuser account is called `root@pam`. All |
3c8533f2 DM |
134 | system mails are forwarded to the email assigned to that account. |
135 | ||
5eba0743 | 136 | |
3c8533f2 DM |
137 | Groups |
138 | ~~~~~~ | |
139 | ||
140 | Each user can be member of several groups. Groups are the preferred | |
141 | way to organize access permissions. You should always grant permission | |
142 | to groups instead of using individual users. That way you will get a | |
143 | much shorter access control list which is easier to handle. | |
144 | ||
5eba0743 | 145 | |
3c8533f2 DM |
146 | Objects and Paths |
147 | ~~~~~~~~~~~~~~~~~ | |
148 | ||
149 | Access permissions are assigned to objects, such as a virtual machines | |
8c1189b6 FG |
150 | (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of |
151 | resources (`/pool/{poolname}`). We use file system like paths to | |
3c8533f2 DM |
152 | address those objects. Those paths form a natural tree, and |
153 | permissions can be inherited down that hierarchy. | |
154 | ||
5eba0743 | 155 | |
3c8533f2 DM |
156 | Privileges |
157 | ~~~~~~~~~~ | |
158 | ||
159 | A privilege is the right to perform a specific action. To simplify | |
160 | management, lists of privileges are grouped into roles, which can then | |
161 | be uses to set permissions. | |
162 | ||
163 | We currently use the following privileges: | |
164 | ||
165 | Node / System related privileges:: | |
166 | ||
167 | * `Permissions.Modify`: modify access permissions | |
168 | * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...) | |
169 | * `Sys.Console`: console access to Node | |
170 | * `Sys.Syslog`: view Syslog | |
171 | * `Sys.Audit`: view node status/config | |
172 | * `Sys.Modify`: create/remove/modify node network parameters | |
173 | * `Group.Allocate`: create/remove/modify groups | |
174 | * `Pool.Allocate`: create/remove/modify a pool | |
175 | * `Realm.Allocate`: create/remove/modify authentication realms | |
176 | * `Realm.AllocateUser`: assign user to a realm | |
177 | * `User.Modify`: create/remove/modify user access and details. | |
178 | ||
179 | Virtual machine related privileges:: | |
180 | ||
181 | * `VM.Allocate`: create/remove new VM to server inventory | |
182 | * `VM.Migrate`: migrate VM to alternate server on cluster | |
183 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
184 | * `VM.Console`: console access to VM | |
185 | * `VM.Monitor`: access to VM monitor (kvm) | |
186 | * `VM.Backup`: backup/restore VMs | |
187 | * `VM.Audit`: view VM config | |
188 | * `VM.Clone`: clone/copy a VM | |
189 | * `VM.Config.Disk`: add/modify/delete Disks | |
190 | * `VM.Config.CDROM`: eject/change CDROM | |
191 | * `VM.Config.CPU`: modify CPU settings | |
192 | * `VM.Config.Memory`: modify Memory settings | |
193 | * `VM.Config.Network`: add/modify/delete Network devices | |
194 | * `VM.Config.HWType`: modify emulated HW type | |
195 | * `VM.Config.Options`: modify any other VM configuration | |
196 | * `VM.Snapshot`: create/remove VM snapshots | |
197 | ||
198 | Storage related privileges:: | |
199 | ||
200 | * `Datastore.Allocate`: create/remove/modify a data store, delete volumes | |
201 | * `Datastore.AllocateSpace`: allocate space on a datastore | |
202 | * `Datastore.AllocateTemplate`: allocate/upload templates and iso images | |
203 | * `Datastore.Audit`: view/browse a datastore | |
204 | ||
5eba0743 | 205 | |
3c8533f2 DM |
206 | Roles |
207 | ~~~~~ | |
208 | ||
209 | A role is simply a list of privileges. Proxmox VE comes with a number | |
210 | of predefined roles which satisfies most needs. | |
211 | ||
212 | * `Administrator`: has all privileges | |
213 | * `NoAccess`: has no privileges (used to forbid access) | |
214 | * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). | |
215 | * `PVEAuditor`: read only access | |
216 | * `PVEDatastoreAdmin`: create and allocate backup space and templates | |
217 | * `PVEDatastoreUser`: allocate backup space and view storage | |
218 | * `PVEPoolAdmin`: allocate pools | |
219 | * `PVESysAdmin`: User ACLs, audit, system console and system logs | |
220 | * `PVETemplateUser`: view and clone templates | |
221 | * `PVEUserAdmin`: user administration | |
222 | * `PVEVMAdmin`: fully administer VMs | |
223 | * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management | |
224 | ||
225 | You can see the whole set of predefined roles on the GUI. | |
226 | ||
227 | Adding new roles using the CLI: | |
228 | ||
229 | [source,bash] | |
230 | ---- | |
231 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
232 | pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" | |
233 | ---- | |
234 | ||
235 | ||
236 | Permissions | |
237 | ~~~~~~~~~~~ | |
238 | ||
239 | Permissions are the way we control access to objects. In technical | |
240 | terms they are simply a triple containing `<path,user,role>`. This | |
241 | concept is also known as access control lists. Each permission | |
242 | specifies a subject (user or group) and a role (set of privileges) on | |
243 | a specific path. | |
244 | ||
245 | When a subject requests an action on an object, the framework looks up | |
246 | the roles assigned to that subject (using the object path). The set of | |
247 | roles defines the granted privileges. | |
248 | ||
5eba0743 | 249 | |
3c8533f2 DM |
250 | Inheritance |
251 | ^^^^^^^^^^^ | |
252 | ||
5eba0743 | 253 | As mentioned earlier, object paths form a file system like tree, and |
3c8533f2 DM |
254 | permissions can be inherited down that tree (the propagate flag is set |
255 | by default). We use the following inheritance rules: | |
256 | ||
257 | * permission for individual users always overwrite group permission. | |
258 | * permission for groups apply when the user is member of that group. | |
259 | * permission set at higher level always overwrites inherited permissions. | |
260 | ||
5eba0743 | 261 | |
3c8533f2 DM |
262 | What permission do I need? |
263 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
4b048bf2 EK |
264 | |
265 | The required API permissions are documented for each individual | |
266 | method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ | |
3c8533f2 | 267 | |
5eba0743 | 268 | |
3c8533f2 DM |
269 | Pools |
270 | ~~~~~ | |
271 | ||
272 | Pools can be used to group a set of virtual machines and data | |
8c1189b6 | 273 | stores. You can then simply set permissions on pools (`/pool/{poolid}`), |
3c8533f2 DM |
274 | which are inherited to all pool members. This is a great way simplify |
275 | access control. | |
276 | ||
277 | Command Line Tool | |
278 | ----------------- | |
279 | ||
280 | Most users will simply use the GUI to manage users. But there is also | |
8c1189b6 | 281 | a full featured command line tool called `pveum` (short for ``**P**roxmox |
4f6e7e05 WB |
282 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command |
283 | line tools are wrappers around the API, so you can also access those | |
284 | function through the REST API. | |
3c8533f2 DM |
285 | |
286 | Here are some simple usage examples. To show help type: | |
287 | ||
288 | [source,bash] | |
289 | pveum | |
290 | ||
291 | or (to show detailed help about a specific command) | |
292 | ||
293 | [source,bash] | |
294 | pveum help useradd | |
295 | ||
296 | Create a new user: | |
297 | ||
298 | [source,bash] | |
299 | pveum useradd testuser@pve -comment "Just a test" | |
300 | ||
301 | Set or Change the password (not all realms support that): | |
302 | ||
303 | [source,bash] | |
304 | pveum passwd testuser@pve | |
305 | ||
306 | Disable a user: | |
307 | ||
308 | [source,bash] | |
309 | pveum usermod testuser@pve -enable 0 | |
310 | ||
311 | Create a new group: | |
312 | ||
313 | [source,bash] | |
314 | pveum groupadd testgroup | |
315 | ||
316 | Create a new role: | |
317 | ||
318 | [source,bash] | |
319 | pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" | |
320 | ||
321 | ||
322 | Real World Examples | |
323 | ------------------- | |
324 | ||
5eba0743 | 325 | |
3c8533f2 DM |
326 | Administrator Group |
327 | ~~~~~~~~~~~~~~~~~~~ | |
328 | ||
329 | One of the most wanted features was the ability to define a group of | |
5eba0743 | 330 | users with full administrator rights (without using the root account). |
3c8533f2 DM |
331 | |
332 | Define the group: | |
333 | ||
334 | [source,bash] | |
335 | pveum groupadd admin -comment "System Administrators" | |
336 | ||
337 | Then add the permission: | |
338 | ||
339 | [source,bash] | |
340 | pveum aclmod / -group admin -role Administrator | |
341 | ||
342 | You can finally add users to the new 'admin' group: | |
343 | ||
344 | [source,bash] | |
345 | pveum usermod testuser@pve -group admin | |
346 | ||
347 | ||
348 | Auditors | |
349 | ~~~~~~~~ | |
350 | ||
351 | You can give read only access to users by assigning the `PVEAuditor` | |
352 | role to users or groups. | |
353 | ||
8c1189b6 | 354 | Example1: Allow user `joe@pve` to see everything |
3c8533f2 DM |
355 | |
356 | [source,bash] | |
357 | pveum aclmod / -user joe@pve -role PVEAuditor | |
358 | ||
8c1189b6 | 359 | Example1: Allow user `joe@pve` to see all virtual machines |
3c8533f2 DM |
360 | |
361 | [source,bash] | |
362 | pveum aclmod /vms -user joe@pve -role PVEAuditor | |
363 | ||
5eba0743 | 364 | |
3c8533f2 DM |
365 | Delegate User Management |
366 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
367 | ||
8c1189b6 | 368 | If you want to delegate user managenent to user `joe@pve` you can do |
3c8533f2 DM |
369 | that with: |
370 | ||
371 | [source,bash] | |
372 | pveum aclmod /access -user joe@pve -role PVEUserAdmin | |
373 | ||
8c1189b6 | 374 | User `joe@pve` can now add and remove users, change passwords and |
3c8533f2 DM |
375 | other user attributes. This is a very powerful role, and you most |
376 | likely want to limit that to selected realms and groups. The following | |
8c1189b6 FG |
377 | example allows `joe@pve` to modify users within realm `pve` if they |
378 | are members of group `customers`: | |
3c8533f2 DM |
379 | |
380 | [source,bash] | |
381 | pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin | |
382 | pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin | |
383 | ||
0abc65b0 | 384 | NOTE: The user is able to add other users, but only if they are |
8c1189b6 FG |
385 | members of group `customers` and within realm `pve`. |
386 | ||
3c8533f2 DM |
387 | |
388 | Pools | |
389 | ~~~~~ | |
390 | ||
391 | An enterprise is usually structured into several smaller departments, | |
392 | and it is common that you want to assign resources to them and | |
393 | delegate management tasks. A pool is simply a set of virtual machines | |
394 | and data stores. You can create pools on the GUI. After that you can | |
395 | add resources to the pool (VMs, Storage). | |
396 | ||
397 | You can also assign permissions to the pool. Those permissions are | |
398 | inherited to all pool members. | |
399 | ||
400 | Lets assume you have a software development department, so we first | |
401 | create a group | |
402 | ||
403 | [source,bash] | |
404 | pveum groupadd developers -comment "Our software developers" | |
405 | ||
406 | Now we create a new user which is a member of that group | |
407 | ||
408 | [source,bash] | |
409 | pveum useradd developer1@pve -group developers -password | |
410 | ||
0abc65b0 | 411 | NOTE: The -password parameter will prompt you for a password |
3c8533f2 | 412 | |
8c1189b6 | 413 | I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: |
3c8533f2 DM |
414 | |
415 | [source,bash] | |
416 | pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin | |
417 | ||
418 | Our software developers can now administrate the resources assigned to | |
419 | that pool. | |
420 | ||
421 | ||
422 | ifdef::manvolnum[] | |
423 | include::pve-copyright.adoc[] | |
424 | endif::manvolnum[] | |
425 |