-include::attributes.txt[]
ifdef::manvolnum[]
PVE({manvolnum})
================
+include::attributes.txt[]
NAME
----
ifndef::manvolnum[]
User Management
===============
+include::attributes.txt[]
endif::manvolnum[]
// Copied from pve wiki: Revision as of 16:10, 27 October 2015
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]]
Authentication Realms
---------------------
-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.
-
-Microsoft Active Directory::
-
-LDAP::
+As {pve} users are just counterparts for users existing on some external
+realm, the realms have to be configured in `/etc/pve/domains.cfg`.
+The following realms (authentication methods) are available:
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!
-
+In this case a system user has to exist (eg. created via the `adduser`
+command) on all nodes the user is allowed to login, and the user
+authenticates with their usual system password.
++
[source,bash]
----
useradd heinz
----
Proxmox VE authentication server::
+This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
+Password are encrypted using the SHA-256 hash method.
+This is the most convenient method for for small (or even medium)
+installations where users do not need access to anything outside of
+{pve}. In this case users are fully managed by {pve} and are able to
+change their own passwords via the GUI.
+
+LDAP::
+It is possible to authenticate users via an LDAP server (eq.
+openldap). The server and an optional fallback server can be
+configured and the connection can be encrypted via SSL.
++
+Users are searched under a 'Base Domain Name' (`base_dn`), with the
+user name found in the attribute specified in the 'User Attribute Name'
+(`user_attr`) field.
++
+For instance, if a user is represented via the
+following ldif dataset:
++
+----
+# user1 of People at ldap-test.com
+dn: uid=user1,ou=People,dc=ldap-test,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+uid: user1
+cn: Test User 1
+sn: Testers
+description: This is the first test user.
+----
++
+The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
+attribute would be `uid`.
++
+If {pve} needs to authenticate (bind) to the ldap server before being
+able to query and authenticate users, a bind domain name can be
+configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
+password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
+(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+single line containing the raw password.
+
+Microsoft Active Directory::
+
+A server and authentication domain need to be specified. Like with
+ldap an optional fallback server, optional port, and SSL
+encryption can be configured.
+
+
+Two factor authentication
+-------------------------
+
+Each realm can optionally be secured additionally by two factor
+authentication. This can be done by selecting one of the available methods
+via the 'TFA' dropdown box when adding or editing an Authentication Realm.
+When a realm has TFA enabled it becomes a requirement and only users with
+configured TFA will be able to login.
+
+Currently there are two methods available:
+
+Time based OATH (TOTP)::
+This uses the standard HMAC-SHA1 algorithm where the current time is hashed
+with the user's configured key. The time step and password length
+parameters are configured.
++
+A user can have multiple keys configured (separated by spaces), and the
+keys can be specified in Base32 (RFC3548) or hexadecimal notation.
++
+{pve} provides a key generation tool (`oathkeygen`) which prints out a
+random key in Base32 notation which can be used directly with various OTP
+tools, such as the `oathtool` command line tool, the Google authenticator
+or FreeOTP Android apps.
+
+YubiKey OTP::
+For authenticating via a YubiKey a Yubico API ID, API KEY and validation
+server URL must be configured, and users must have a YubiKey available. In
+order to get the key ID from a YubiKey, you can trigger the YubiKey once
+after connecting it to USB and copy the first 12 characters of the typed
+password into the user's 'Key IDs' field.
++
+Please refer to the
+https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
+https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
+https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
+host your own verification server].
-This is a unix like password store
-('/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