authentication server.
By using the role based user- and permission management for all
-objects (VM´s, storages, nodes, etc.) granular access can be defined.
+objects (VMs, storages, nodes, etc.) granular access can be defined.
+
Authentication Realms
---------------------
-Proxmox VE stores all user attributes in '/etc/pve/user.cfg'. So there
+Proxmox VE stores all user attributes in `/etc/pve/user.cfg`. So there
must be an entry for each user in that file. The password is not
stored, instead you can use configure several realms to verify
passwords.
Linux PAM standard authentication::
-You need to create the system users first with 'adduser'
-(e.g. adduser heinz) and possibly the group as well. After that you
-can create the user on the GUI!
+You need to create the system users first with `adduser`
+(e.g. `adduser heinz`) and possibly the group as well. After that you
+can create the user on the GUI.
[source,bash]
----
Proxmox VE authentication server::
This is a unix like password store
-('/etc/pve/priv/shadow.cfg'). Password are encrypted using the SHA-256
+(`/etc/pve/priv/shadow.cfg`). Password are encrypted using the SHA-256
hash method. Users are allowed to change passwords.
+
Terms and Definitions
---------------------
+
Users
~~~~~
login screen on the GUI shows them a separate items, but it is
internally used as single string.
-We store the following attribute for users ('/etc/pve/user.cfg'):
+We store the following attribute for users (`/etc/pve/user.cfg`):
* first name
* last name
* flag to enable/disable account
* comment
+
Superuser
^^^^^^^^^
-The traditional unix superuser account is called 'root@pam'. All
+The traditional unix superuser account is called `root@pam`. All
system mails are forwarded to the email assigned to that account.
+
Groups
~~~~~~
to groups instead of using individual users. That way you will get a
much shorter access control list which is easier to handle.
+
Objects and Paths
~~~~~~~~~~~~~~~~~
Access permissions are assigned to objects, such as a virtual machines
-('/vms/{vmid}') or a storage ('/storage/{storeid}') or a pool of
-resources ('/pool/{poolname}'). We use filesystem like paths to
+(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
+resources (`/pool/{poolname}`). We use file system like paths to
address those objects. Those paths form a natural tree, and
permissions can be inherited down that hierarchy.
+
Privileges
~~~~~~~~~~
* `Datastore.AllocateTemplate`: allocate/upload templates and iso images
* `Datastore.Audit`: view/browse a datastore
+
Roles
~~~~~
the roles assigned to that subject (using the object path). The set of
roles defines the granted privileges.
+
Inheritance
^^^^^^^^^^^
-As mentioned earlier, object paths forms a filesystem like tree, and
+As mentioned earlier, object paths form a file system like tree, and
permissions can be inherited down that tree (the propagate flag is set
by default). We use the following inheritance rules:
* permission for groups apply when the user is member of that group.
* permission set at higher level always overwrites inherited permissions.
+
What permission do I need?
^^^^^^^^^^^^^^^^^^^^^^^^^^
-The required API permissions are documented for each individual method, and can be found at http://pve.proxmox.com/pve2-api-doc/
+
+The required API permissions are documented for each individual
+method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
+
Pools
~~~~~
Pools can be used to group a set of virtual machines and data
-stores. You can then simply set permissions on pools ('/pool/{poolid}'),
+stores. You can then simply set permissions on pools (`/pool/{poolid}`),
which are inherited to all pool members. This is a great way simplify
access control.
-----------------
Most users will simply use the GUI to manage users. But there is also
-a full featured command line tool called 'pveum' (short for 'Proxmox
-VE User Manager'). I will use that tool in the following
-examples. Please note that all Proxmox VE command line tools are
-wrappers around the API, so you can also access those function through
-the REST API.
+a full featured command line tool called `pveum` (short for ``**P**roxmox
+**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
+line tools are wrappers around the API, so you can also access those
+function through the REST API.
Here are some simple usage examples. To show help type:
Real World Examples
-------------------
+
Administrator Group
~~~~~~~~~~~~~~~~~~~
One of the most wanted features was the ability to define a group of
-users with full administartor rights (without using the root account).
+users with full administrator rights (without using the root account).
Define the group:
You can give read only access to users by assigning the `PVEAuditor`
role to users or groups.
-Example1: Allow user 'joe@pve' to see everything
+Example1: Allow user `joe@pve` to see everything
[source,bash]
pveum aclmod / -user joe@pve -role PVEAuditor
-Example1: Allow user 'joe@pve' to see all virtual machines
+Example1: Allow user `joe@pve` to see all virtual machines
[source,bash]
pveum aclmod /vms -user joe@pve -role PVEAuditor
+
Delegate User Management
~~~~~~~~~~~~~~~~~~~~~~~~
-If you want to delegate user managenent to user 'joe@pve' you can do
+If you want to delegate user managenent to user `joe@pve` you can do
that with:
[source,bash]
pveum aclmod /access -user joe@pve -role PVEUserAdmin
-User 'joe@pve' can now add and remove users, change passwords and
+User `joe@pve` can now add and remove users, change passwords and
other user attributes. This is a very powerful role, and you most
likely want to limit that to selected realms and groups. The following
-example allows 'joe@pve' to modify users within realm 'pve' if they
-are members of group 'customers':
+example allows `joe@pve` to modify users within realm `pve` if they
+are members of group `customers`:
[source,bash]
pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
-Note: The user is able to add other users, but only if they are
-members of group 'customers' and within realm 'pve'.
+NOTE: The user is able to add other users, but only if they are
+members of group `customers` and within realm `pve`.
+
Pools
~~~~~
[source,bash]
pveum useradd developer1@pve -group developers -password
-Note: The -password parameter will prompt you for a password
+NOTE: The -password parameter will prompt you for a password
-I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
+I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
[source,bash]
pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
projects / pve-docs.git / blobdiff