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