pveum.adoc

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