pveum.adoc

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