pveum.adoc

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