1 include::attributes.txt[]
9 pveum - Proxmox VE User Manager
15 include::pveum.1-synopsis.adoc[]
27 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
29 Proxmox VE supports multiple authentication sources, e.g. Microsoft
30 Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
31 authentication server.
33 By using the role based user- and permission management for all
34 objects (VM´s, storages, nodes, etc.) granular access can be defined.
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
44 Microsoft Active Directory::
48 Linux PAM standard authentication::
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!
59 usermod -a -G watchman heinz
62 Proxmox VE authentication server::
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.
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.
78 We store the following attribute for users ('/etc/pve/user.cfg'):
84 * flag to enable/disable account
90 The traditional unix superuser account is called 'root@pam'. All
91 system mails are forwarded to the email assigned to that account.
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.
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.
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.
117 We currently use the following privileges:
119 Node / System related privileges::
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.
133 Virtual machine related privileges::
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
152 Storage related privileges::
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
162 A role is simply a list of privileges. Proxmox VE comes with a number
163 of predefined roles which satisfies most needs.
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
178 You can see the whole set of predefined roles on the GUI.
180 Adding new roles using the CLI:
184 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
185 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
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
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.
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:
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.
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/
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
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
235 Here are some simple usage examples. To show help type:
240 or (to show detailed help about a specific command)
248 pveum useradd testuser@pve -comment "Just a test"
250 Set or Change the password (not all realms support that):
253 pveum passwd testuser@pve
258 pveum usermod testuser@pve -enable 0
263 pveum groupadd testgroup
268 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
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).
283 pveum groupadd admin -comment "System Administrators"
285 Then add the permission:
288 pveum aclmod / -group admin -role Administrator
290 You can finally add users to the new 'admin' group:
293 pveum usermod testuser@pve -group admin
299 You can give read only access to users by assigning the `PVEAuditor`
300 role to users or groups.
302 Example1: Allow user 'joe@pve' to see everything
305 pveum aclmod / -user joe@pve -role PVEAuditor
307 Example1: Allow user 'joe@pve' to see all virtual machines
310 pveum aclmod /vms -user joe@pve -role PVEAuditor
312 Delegate User Management
313 ~~~~~~~~~~~~~~~~~~~~~~~~
315 If you want to delegate user managenent to user 'joe@pve' you can do
319 pveum aclmod /access -user joe@pve -role PVEUserAdmin
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':
328 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
329 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
331 Note: The user is able to add other users, but only if they are
332 members of group 'customers' and within realm 'pve'.
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).
343 You can also assign permissions to the pool. Those permissions are
344 inherited to all pool members.
346 Lets assume you have a software development department, so we first
350 pveum groupadd developers -comment "Our software developers"
352 Now we create a new user which is a member of that group
355 pveum useradd developer1@pve -group developers -password
357 Note: The -password parameter will prompt you for a password
359 I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
362 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
364 Our software developers can now administrate the resources assigned to
369 include::pve-copyright.adoc[]