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 The required API permissions are documented for each individual method, and can be found at http://pve.proxmox.com/pve2-api-doc/
 217
 218 Pools
 219 ~~~~~
 220
 221 Pools can be used to group a set of virtual machines and data
 222 stores. You can then simply set permissions on pools ('/pool/{poolid}'),
 223 which are inherited to all pool members. This is a great way simplify
 224 access control.
 225
 226 Command Line Tool
 227 -----------------
 228
 229 Most users will simply use the GUI to manage users. But there is also
 230 a full featured command line tool called 'pveum' (short for 'Proxmox
 231 VE User Manager'). I will use that tool in the following
 232 examples. Please note that all Proxmox VE command line tools are
 233 wrappers around the API, so you can also access those function through
 234 the REST API.
 235
 236 Here are some simple usage examples. To show help type:
 237
 238 [source,bash]
 239  pveum
 240
 241 or (to show detailed help about a specific command)
 242
 243 [source,bash]
 244  pveum help useradd
 245
 246 Create a new user:
 247
 248 [source,bash]
 249  pveum useradd testuser@pve -comment "Just a test"
 250
 251 Set or Change the password (not all realms support that):
 252
 253 [source,bash]
 254  pveum passwd testuser@pve
 255
 256 Disable a user:
 257
 258 [source,bash]
 259  pveum usermod testuser@pve -enable 0
 260
 261 Create a new group:
 262
 263 [source,bash]
 264  pveum groupadd testgroup
 265
 266 Create a new role:
 267
 268 [source,bash]
 269  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
 270
 271
 272 Real World Examples
 273 -------------------
 274
 275 Administrator Group
 276 ~~~~~~~~~~~~~~~~~~~
 277
 278 One of the most wanted features was the ability to define a group of
 279 users with full administartor rights (without using the root account).
 280
 281 Define the group:
 282
 283 [source,bash]
 284  pveum groupadd admin -comment "System Administrators"
 285
 286 Then add the permission:
 287
 288 [source,bash]
 289  pveum aclmod / -group admin -role Administrator
 290
 291 You can finally add users to the new 'admin' group:
 292
 293 [source,bash]
 294  pveum usermod testuser@pve -group admin
 295
 296
 297 Auditors
 298 ~~~~~~~~
 299
 300 You can give read only access to users by assigning the `PVEAuditor`
 301 role to users or groups.
 302
 303 Example1: Allow user 'joe@pve' to see everything
 304
 305 [source,bash]
 306  pveum aclmod / -user joe@pve -role PVEAuditor
 307
 308 Example1: Allow user 'joe@pve' to see all virtual machines
 309
 310 [source,bash]
 311  pveum aclmod /vms -user joe@pve -role PVEAuditor
 312
 313 Delegate User Management
 314 ~~~~~~~~~~~~~~~~~~~~~~~~
 315
 316 If you want to delegate user managenent to user 'joe@pve' you can do
 317 that with:
 318
 319 [source,bash]
 320  pveum aclmod /access -user joe@pve -role PVEUserAdmin
 321
 322 User 'joe@pve' can now add and remove users, change passwords and
 323 other user attributes. This is a very powerful role, and you most
 324 likely want to limit that to selected realms and groups. The following
 325 example allows 'joe@pve' to modify users within realm 'pve' if they
 326 are members of group 'customers':
 327
 328 [source,bash]
 329  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
 330  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
 331
 332 NOTE: The user is able to add other users, but only if they are
 333 members of group 'customers' and within realm 'pve'.
 334
 335 Pools
 336 ~~~~~
 337
 338 An enterprise is usually structured into several smaller departments,
 339 and it is common that you want to assign resources to them and
 340 delegate management tasks. A pool is simply a set of virtual machines
 341 and data stores. You can create pools on the GUI. After that you can
 342 add resources to the pool (VMs, Storage).
 343
 344 You can also assign permissions to the pool. Those permissions are
 345 inherited to all pool members.
 346
 347 Lets assume you have a software development department, so we first
 348 create a group
 349
 350 [source,bash]
 351  pveum groupadd developers -comment "Our software developers"
 352
 353 Now we create a new user which is a member of that group
 354
 355 [source,bash]
 356  pveum useradd developer1@pve -group developers -password
 357
 358 NOTE: The -password parameter will prompt you for a password
 359
 360 I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
 361
 362 [source,bash]
 363  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
 364
 365 Our software developers can now administrate the resources assigned to
 366 that pool.
 367
 368
 369 ifdef::manvolnum[]
 370 include::pve-copyright.adoc[]
 371 endif::manvolnum[]
 372