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