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 Permission Management
 187 ---------------------
 188
 189 In order for a user to perform an action (such as listing, modifying or
 190 deleting a parts of a VM configuration), the user needs to have the
 191 appropriate permissions.
 192
 193 {pve} uses a role and path based permission management system. An entry in
 194 the permissions table allows a user or group to take on a specific role
 195 when accessing an 'object' or 'path'. This means an such an access rule can
 196 be represented as a triple of '(path, user, role)' or '(path, group,
 197 role)', with the role containing a set of allowed actions, and the path
 198 representing the target of these actions.
 199
 200
 201 Objects and Paths
 202 ~~~~~~~~~~~~~~~~~
 203
 204 Access permissions are assigned to objects, such as a virtual machines
 205 (`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
 206 resources (`/pool/{poolname}`). We use file system like paths to
 207 address those objects. Those paths form a natural tree, and
 208 permissions can be inherited down that hierarchy.
 209
 210
 211 Privileges
 212 ~~~~~~~~~~
 213
 214 A privilege is the right to perform a specific action. To simplify
 215 management, lists of privileges are grouped into roles, which can then
 216 be uses to set permissions.
 217
 218 We currently use the following privileges:
 219
 220 Node / System related privileges::
 221
 222 * `Permissions.Modify`: modify access permissions
 223 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
 224 * `Sys.Console`: console access to Node
 225 * `Sys.Syslog`: view Syslog
 226 * `Sys.Audit`: view node status/config
 227 * `Sys.Modify`: create/remove/modify node network parameters
 228 * `Group.Allocate`: create/remove/modify groups
 229 * `Pool.Allocate`: create/remove/modify a pool
 230 * `Realm.Allocate`: create/remove/modify authentication realms
 231 * `Realm.AllocateUser`: assign user to a realm
 232 * `User.Modify`: create/remove/modify user access and details.
 233
 234 Virtual machine related privileges::
 235
 236 * `VM.Allocate`: create/remove new VM to server inventory
 237 * `VM.Migrate`: migrate VM to alternate server on cluster
 238 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
 239 * `VM.Console`: console access to VM
 240 * `VM.Monitor`: access to VM monitor (kvm)
 241 * `VM.Backup`: backup/restore VMs
 242 * `VM.Audit`: view VM config
 243 * `VM.Clone`: clone/copy a VM
 244 * `VM.Config.Disk`: add/modify/delete Disks
 245 * `VM.Config.CDROM`: eject/change CDROM
 246 * `VM.Config.CPU`: modify CPU settings
 247 * `VM.Config.Memory`: modify Memory settings
 248 * `VM.Config.Network`: add/modify/delete Network devices
 249 * `VM.Config.HWType`: modify emulated HW type
 250 * `VM.Config.Options`: modify any other VM configuration
 251 * `VM.Snapshot`: create/remove VM snapshots
 252
 253 Storage related privileges::
 254
 255 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
 256 * `Datastore.AllocateSpace`: allocate space on a datastore
 257 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images
 258 * `Datastore.Audit`: view/browse a datastore
 259
 260
 261 Roles
 262 ~~~~~
 263
 264 A role is simply a list of privileges. Proxmox VE comes with a number
 265 of predefined roles which satisfies most needs.
 266
 267 * `Administrator`: has all privileges
 268 * `NoAccess`: has no privileges (used to forbid access)
 269 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
 270 * `PVEAuditor`: read only access
 271 * `PVEDatastoreAdmin`: create and allocate backup space and templates
 272 * `PVEDatastoreUser`: allocate backup space and view storage
 273 * `PVEPoolAdmin`: allocate pools
 274 * `PVESysAdmin`: User ACLs, audit, system console and system logs
 275 * `PVETemplateUser`: view and clone templates
 276 * `PVEUserAdmin`: user administration
 277 * `PVEVMAdmin`: fully administer VMs
 278 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
 279
 280 You can see the whole set of predefined roles on the GUI.
 281
 282 Adding new roles using the CLI:
 283
 284 [source,bash]
 285 ----
 286 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
 287 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
 288 ----
 289
 290
 291 Permissions
 292 ~~~~~~~~~~~
 293
 294 Permissions are the way we control access to objects. In technical
 295 terms they are simply a triple containing `<path,user,role>`. This
 296 concept is also known as access control lists. Each permission
 297 specifies a subject (user or group) and a role (set of privileges) on
 298 a specific path.
 299
 300 When a subject requests an action on an object, the framework looks up
 301 the roles assigned to that subject (using the object path). The set of
 302 roles defines the granted privileges.
 303
 304
 305 Inheritance
 306 ^^^^^^^^^^^
 307
 308 As mentioned earlier, object paths form a file system like tree, and
 309 permissions can be inherited down that tree (the propagate flag is set
 310 by default). We use the following inheritance rules:
 311
 312 * Permissions for individual users always replace group permissions.
 313 * Permissions for groups apply when the user is member of that group.
 314 * Permissions replace the ones inherited from an upper level.
 315
 316
 317 Pools
 318 ~~~~~
 319
 320 Pools can be used to group a set of virtual machines and data
 321 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
 322 which are inherited to all pool members. This is a great way simplify
 323 access control.
 324
 325
 326 What permission do I need?
 327 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 328
 329 The required API permissions are documented for each individual
 330 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
 331
 332 The permissions are specified as a list which can be interpreted as a
 333 tree of logic and access-check functions:
 334
 335 `["and", <subtests>...]` and `["or", <subtests>...]`::
 336 Each(`and`) or any(`or`) further element in the current list has to be true.
 337
 338 `["perm", <path>, [ <privileges>... ], <options>...]`::
 339 The `path` is a templated parameter (see <<templated-paths,Objects and
 340 Paths>>). All (or , if the `any` option is used, any) of the listed
 341 privileges must be allowed on the specified path. If a `require-param`
 342 option is specified, then its specified parameter is required even if the
 343 API call's schema otherwise lists it as being optional.
 344
 345 `["userid-group", [ <privileges>... ], <options>...]`::
 346 The callermust have any of the listed privileges on `/access/groups`. In
 347 addition there are two possible checks depending on whether the
 348 `groups_param` option is set:
 349 +
 350 * `groups_param` is set: The API call has a non-optional `groups` parameter
 351 and the caller must have any of the listed privileges on all of the listed
 352 groups.
 353 * `groups_param` is not set: The user passed via the `userid` parameter
 354 must exist and be part of a group on which the caller has any of the listed
 355 privileges (via the `/access/groups/<group>` path).
 356
 357 `["userid-param", "self"]`::
 358 The value provided for the API call's `userid` parameter must refer to the
 359 user performing the action. (Usually in conjunction with `or`, to allow
 360 users to perform an action on themselves even if they don't have elevated
 361 privileges.)
 362
 363 `["userid-param", "Realm.AllocateUser"]`::
 364 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
 365 `<realm>` refering to the realm of the user passed via the `userid`
 366 parameter. Note that the user does not need to exist in order to be
 367 associated with a realm, since user IDs are passed in the form of
 368 `<username>@<realm>`.
 369
 370 `["perm-modify", <path>]`::
 371 The `path` is a templated parameter (see <<templated-paths,Objects and
 372 Paths>>). The user needs either the `Permissions.Modify` privilege, or,
 373 depending on the path, the following privileges as a possible substitute:
 374 +
 375 * `/storage/...`: additionally requires 'Datastore.Allocate`
 376 * `/vms/...`: additionally requires 'VM.Allocate`
 377 * `/pool/...`: additionally requires 'Pool.Allocate`
 378 +
 379 If the path is empty, `Permission.Modify` on `/access` is required.
 380
 381 Command Line Tool
 382 -----------------
 383
 384 Most users will simply use the GUI to manage users. But there is also
 385 a full featured command line tool called `pveum` (short for ``**P**roxmox
 386 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
 387 line tools are wrappers around the API, so you can also access those
 388 function through the REST API.
 389
 390 Here are some simple usage examples. To show help type:
 391
 392 [source,bash]
 393  pveum
 394
 395 or (to show detailed help about a specific command)
 396
 397 [source,bash]
 398  pveum help useradd
 399
 400 Create a new user:
 401
 402 [source,bash]
 403  pveum useradd testuser@pve -comment "Just a test"
 404
 405 Set or Change the password (not all realms support that):
 406
 407 [source,bash]
 408  pveum passwd testuser@pve
 409
 410 Disable a user:
 411
 412 [source,bash]
 413  pveum usermod testuser@pve -enable 0
 414
 415 Create a new group:
 416
 417 [source,bash]
 418  pveum groupadd testgroup
 419
 420 Create a new role:
 421
 422 [source,bash]
 423  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
 424
 425
 426 Real World Examples
 427 -------------------
 428
 429
 430 Administrator Group
 431 ~~~~~~~~~~~~~~~~~~~
 432
 433 One of the most wanted features was the ability to define a group of
 434 users with full administrator rights (without using the root account).
 435
 436 Define the group:
 437
 438 [source,bash]
 439  pveum groupadd admin -comment "System Administrators"
 440
 441 Then add the permission:
 442
 443 [source,bash]
 444  pveum aclmod / -group admin -role Administrator
 445
 446 You can finally add users to the new 'admin' group:
 447
 448 [source,bash]
 449  pveum usermod testuser@pve -group admin
 450
 451
 452 Auditors
 453 ~~~~~~~~
 454
 455 You can give read only access to users by assigning the `PVEAuditor`
 456 role to users or groups.
 457
 458 Example1: Allow user `joe@pve` to see everything
 459
 460 [source,bash]
 461  pveum aclmod / -user joe@pve -role PVEAuditor
 462
 463 Example1: Allow user `joe@pve` to see all virtual machines
 464
 465 [source,bash]
 466  pveum aclmod /vms -user joe@pve -role PVEAuditor
 467
 468
 469 Delegate User Management
 470 ~~~~~~~~~~~~~~~~~~~~~~~~
 471
 472 If you want to delegate user managenent to user `joe@pve` you can do
 473 that with:
 474
 475 [source,bash]
 476  pveum aclmod /access -user joe@pve -role PVEUserAdmin
 477
 478 User `joe@pve` can now add and remove users, change passwords and
 479 other user attributes. This is a very powerful role, and you most
 480 likely want to limit that to selected realms and groups. The following
 481 example allows `joe@pve` to modify users within realm `pve` if they
 482 are members of group `customers`:
 483
 484 [source,bash]
 485  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
 486  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
 487
 488 NOTE: The user is able to add other users, but only if they are
 489 members of group `customers` and within realm `pve`.
 490
 491
 492 Pools
 493 ~~~~~
 494
 495 An enterprise is usually structured into several smaller departments,
 496 and it is common that you want to assign resources to them and
 497 delegate management tasks. A pool is simply a set of virtual machines
 498 and data stores. You can create pools on the GUI. After that you can
 499 add resources to the pool (VMs, Storage).
 500
 501 You can also assign permissions to the pool. Those permissions are
 502 inherited to all pool members.
 503
 504 Lets assume you have a software development department, so we first
 505 create a group
 506
 507 [source,bash]
 508  pveum groupadd developers -comment "Our software developers"
 509
 510 Now we create a new user which is a member of that group
 511
 512 [source,bash]
 513  pveum useradd developer1@pve -group developers -password
 514
 515 NOTE: The -password parameter will prompt you for a password
 516
 517 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
 518
 519 [source,bash]
 520  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
 521
 522 Our software developers can now administrate the resources assigned to
 523 that pool.
 524
 525
 526 ifdef::manvolnum[]
 527 include::pve-copyright.adoc[]
 528 endif::manvolnum[]
 529