Difference between revisions of "User Management"

From Proxmox VE
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
[[Category:Reference Documentation]]
 
[[Category:Reference Documentation]]
 
<pvehide>
 
<pvehide>
Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
+
Proxmox VE supports multiple authentication sources, for example Linux PAM,
 
an integrated Proxmox VE authentication server, LDAP, Microsoft Active
 
an integrated Proxmox VE authentication server, LDAP, Microsoft Active
Directory.
+
Directory and OpenID Connect.
By using the role based user- and permission management for all
+
By using role-based user and permission management for all objects (VMs,
objects (VMs, storages, nodes, etc.) granular access can be defined.
+
Storage, nodes, etc.), granular access can be defined.
 
Users
 
Users
 
Proxmox VE stores user attributes in /etc/pve/user.cfg.
 
Proxmox VE stores user attributes in /etc/pve/user.cfg.
Passwords are not stored here, users are instead associated with
+
Passwords are not stored here; users are instead associated with the
 
authentication realms described below.
 
authentication realms described below.
Therefore a user is internally often identified by its name and
+
Therefore, a user is often internally identified by their username and
 
realm in the form &lt;userid&gt;@&lt;realm&gt;.
 
realm in the form &lt;userid&gt;@&lt;realm&gt;.
 
Each user entry in this file contains the following information:
 
Each user entry in this file contains the following information:
Line 20: Line 20:
 
E-mail address
 
E-mail address
 
Group memberships
 
Group memberships
An optional Expiration date
+
An optional expiration date
 
A comment or note about this user
 
A comment or note about this user
 
Whether this user is enabled or disabled
 
Whether this user is enabled or disabled
Optional two factor authentication keys
+
Optional two-factor authentication keys
 +
When you disable or delete a user, or if the expiry date set is
 +
in the past, this user will not be able to log in to new sessions or start new
 +
tasks. All tasks which have already been started by this user (for example,
 +
terminal sessions) will not be terminated automatically by any such event.
 
System administrator
 
System administrator
 
The system&#8217;s root user can always log in via the Linux PAM realm and is an
 
The system&#8217;s root user can always log in via the Linux PAM realm and is an
 
unconfined administrator. This user cannot be deleted, but attributes can
 
unconfined administrator. This user cannot be deleted, but attributes can
still be changed and system mails will be sent to the email address
+
still be changed. System mails will be sent to the email address
 
assigned to this user.
 
assigned to this user.
 
Groups
 
Groups
Each user can be member of several groups. Groups are the preferred
+
Each user can be a member of several groups. Groups are the preferred
way to organize access permissions. You should always grant permission
+
way to organize access permissions. You should always grant permissions
to groups instead of using individual users. That way you will get a
+
to groups instead of individual users. That way you will get a
much shorter access control list which is easier to handle.
+
much more maintainable access control list.
 +
API Tokens
 +
API tokens allow stateless access to most parts of the REST API from another
 +
system, software or API client. Tokens can be generated for individual users
 +
and can be given separate permissions and expiration dates to limit the scope
 +
and duration of the access. Should the API token get compromised, it can be
 +
revoked without disabling the user itself.
 +
API tokens come in two basic types:
 +
Separated privileges: The token needs to be given explicit access with ACLs.
 +
  Its effective permissions are calculated by intersecting user and token
 +
  permissions.
 +
Full privileges: The token&#8217;s permissions are identical to that of the
 +
  associated user.
 +
The token value is only displayed/returned once when the token is
 +
generated. It cannot be retrieved again over the API at a later time!
 +
To use an API token, set the HTTP header Authorization to the displayed value
 +
of the form PVEAPIToken=USER@REALM!TOKENID=UUID when making API requests, or
 +
refer to your API client&#8217;s documentation.
 +
Resource Pools
 +
A resource pool is a set of virtual machines, containers, and storage
 +
devices. It is useful for permission handling in cases where certain users
 +
should have controlled access to a specific set of resources, as it allows for a
 +
single permission to be applied to a set of elements, rather than having to
 +
manage this on a per-resource basis. Resource pools are often used in tandem
 +
with groups, so that the members of a group have permissions on a set of
 +
machines and storage.
 
Authentication Realms
 
Authentication Realms
 
As Proxmox VE users are just counterparts for users existing on some external
 
As Proxmox VE users are just counterparts for users existing on some external
 
realm, the realms have to be configured in /etc/pve/domains.cfg.
 
realm, the realms have to be configured in /etc/pve/domains.cfg.
 
The following realms (authentication methods) are available:
 
The following realms (authentication methods) are available:
Linux PAM standard authentication
+
Linux PAM Standard Authentication
In this case a system user has to exist (e.g. created via the adduser
+
Linux PAM is a framework for system-wide user authentication. These users are
command) on all nodes the user is allowed to login, and the user
+
created on the host system with commands such as adduser. If PAM users exist
authenticates with their usual system password.
+
on the Proxmox VE host system, corresponding entries can be added to Proxmox VE, to allow
useradd heinz
+
these users to log in via their system username and password.
passwd heinz
+
Proxmox VE Authentication Server
groupadd watchman
+
This is a Unix-like password store, which stores hashed passwords in
usermod -a -G watchman heinz
+
/etc/pve/priv/shadow.cfg. Passwords are hashed using the SHA-256 hashing
Proxmox VE authentication server
+
algorithm. This is the most convenient realm for small-scale (or even
This is a unix like password store (/etc/pve/priv/shadow.cfg).
+
mid-scale) installations, where users do not need access to anything outside of
Password are encrypted using the SHA-256 hash method.
+
Proxmox VE. In this case, users are fully managed by Proxmox VE and are able to change
This is the most convenient method for small (or even medium)
+
their own passwords via the GUI.
installations where users do not need access to anything outside of
 
Proxmox VE. In this case users are fully managed by Proxmox VE and are able to
 
change their own passwords via the GUI.
 
 
LDAP
 
LDAP
It is possible to authenticate users via an LDAP server (e.g.
+
LDAP (Lightweight Directory Access Protocol) is an open, cross-platform protocol
openldap). The server and an optional fallback server can be
+
for authentication using directory services. OpenLDAP is a popular open-source
configured and the connection can be encrypted via SSL.
+
implementations of the LDAP protocol.
Users are searched under a Base Domain Name (base_dn), with the
+
Microsoft Active Directory (AD)
user name found in the attribute specified in the User Attribute Name
+
Microsoft Active Directory (AD) is a directory service for Windows domain
 +
networks and is supported as an authentication realm for Proxmox VE. It supports LDAP
 +
as an authentication protocol.
 +
OpenID Connect
 +
OpenID Connect is implemented as an identity layer on top of the OATH 2.0
 +
protocol. It allows clients to verify the identity of the user, based on
 +
authentication performed by an external authorization server.
 +
Linux PAM Standard Authentication
 +
As Linux PAM corresponds to host system users, a system user must exist on each
 +
node which the user is allowed to log in on. The user authenticates with their
 +
usual system password. This realm is added by default and can&#8217;t be removed. In
 +
terms of configurability, an administrator can choose to require two-factor
 +
authentication with logins from the realm and to set the realm as the default
 +
authentication realm.
 +
Proxmox VE Authentication Server
 +
The Proxmox VE authentication server realm is a simple Unix-like password store.
 +
The realm is created by default, and as with Linux PAM, the only configuration
 +
items available are the ability to require two-factor authentication for users
 +
of the realm, and to set it as the default realm for login.
 +
Unlike the other Proxmox VE realm types, users are created and authenticated entirely
 +
through Proxmox VE, rather than authenticating against another system. Hence, you are
 +
required to set a password for this type of user upon creation.
 +
LDAP
 +
You can also use an external LDAP server for user authentication (for examle,
 +
OpenLDAP). In this realm type, users are searched under a Base Domain Name
 +
(base_dn), using the username attribute specified in the User Attribute Name
 
(user_attr) field.
 
(user_attr) field.
For instance, if a user is represented via the
+
A server and optional fallback server can be configured, and the connection can
following ldif dataset:
+
be encrypted via SSL. Furthermore, filters can be configured for directories and
 +
groups. Filters allow you to further limit the scope of the realm.
 +
For instance, if a user is represented via the following LDIF dataset:
 
# user1 of People at ldap-test.com
 
# user1 of People at ldap-test.com
 
dn: uid=user1,ou=People,dc=ldap-test,dc=com
 
dn: uid=user1,ou=People,dc=ldap-test,dc=com
Line 74: Line 127:
 
The Base Domain Name would be ou=People,dc=ldap-test,dc=com and the user
 
The Base Domain Name would be ou=People,dc=ldap-test,dc=com and the user
 
attribute would be uid.
 
attribute would be uid.
If Proxmox VE needs to authenticate (bind) to the ldap server before being
+
If Proxmox VE needs to authenticate (bind) to the LDAP server before being
 
able to query and authenticate users, a bind domain name can be
 
able to query and authenticate users, a bind domain name can be
 
configured via the bind_dn property in /etc/pve/domains.cfg. Its
 
configured via the bind_dn property in /etc/pve/domains.cfg. Its
 
password then has to be stored in /etc/pve/priv/ldap/&lt;realmname&gt;.pw
 
password then has to be stored in /etc/pve/priv/ldap/&lt;realmname&gt;.pw
(e.g. /etc/pve/priv/ldap/my-ldap.pw). This file should contain a
+
(for example, /etc/pve/priv/ldap/my-ldap.pw). This file should contain a
single line containing the raw password.
+
single line with the raw password.
Microsoft Active Directory
+
To verify certificates, you need to set capath. You can set it either
A server and authentication domain need to be specified. Like with
+
directly to the CA certificate of your LDAP server, or to the system path
ldap an optional fallback server, optional port, and SSL
+
containing all trusted CA certificates (/etc/ssl/certs).
encryption can be configured.
+
Additionally, you need to set the verify option, which can also be done over
Two factor authentication
+
the web interface.
There are two ways to use two factor authentication:
+
The main configuration options for an LDAP server realm are as follows:
It can be required by the authentication realm, either via TOTP or
+
Realm (realm): The realm identifier for Proxmox VE users
YubiKey OTP. In this case a newly created user needs their keys added
+
Base Domain Name (base_dn): The directory which users are searched under
immediately as there is no way to log in without the second factor. In the case
+
User Attribute Name (user_attr): The LDAP attribute containing the
of TOTP a user can also change the TOTP later on provided they can log in
+
  username that users will log in with
first.
+
Server (server1): The server hosting the LDAP directory
Alternatively a user can choose to opt into two factor authentication via TOTP
+
Fallback Server (server2): An optional fallback server address, in case
later on even if the realm does not enforce it. As another option, if the server
+
  the primary server is unreachable
has an AppId configured, a user can opt into U2F authentication, provided
+
Port (port): The port that the LDAP server listens on
the realm does not enforce any other second factor.
+
In order to allow a particular user to authenticate using the LDAP server,
Realm enforced two factor authentication
+
you must also add them as a user of that realm from the Proxmox VE server. This can
This can be done by selecting one of the available methods
+
be carried out automatically with  syncing.
via the TFA dropdown box when adding or editing an Authentication Realm.
+
Microsoft Active Directory (AD)
When a realm has TFA enabled it becomes a requirement and only users with
+
To set up Microsoft AD as a realm, a server address and authentication domain
configured TFA will be able to login.
+
need to be specified. Active Directory supports most of the same properties as
 +
LDAP, such as an optional fallback server, port, and SSL encryption.
 +
Furthermore, users can be added to Proxmox VE automatically via
 +
sync operations, after configuration.
 +
As with LDAP, if Proxmox VE needs to authenticate before it binds to the AD server,
 +
you must configure the Bind User (bind_dn) property. This property is
 +
typically required by default for Microsoft AD.
 +
The main configuration settings for Microsoft Active Directory are:
 +
Realm (realm): The realm identifier for Proxmox VE users
 +
Domain (domain): The AD domain of the server
 +
Server (server1): The FQDN or IP address of the server
 +
Fallback Server (server2): An optional fallback server address, in case
 +
  the primary server is unreachable
 +
Port (port): The port that the Microsoft AD server listens on
 +
Syncing LDAP-Based Realms
 +
It&#8217;s possible to automatically sync users and groups for LDAP-based realms (LDAP
 +
&amp; Microsoft Active Directory), rather than having to add them to Proxmox VE manually.
 +
You can access the sync options from the Add/Edit window of the web interface&#8217;s
 +
Authentication panel or via the pveum realm add/modify commands. You can
 +
then carry out the sync operation from the Authentication panel of the GUI or
 +
using the following command:
 +
pveum realm sync &lt;realm&gt;
 +
Users and groups are synced to the cluster-wide configuration file,
 +
/etc/pve/user.cfg.
 +
Sync Configuration
 +
The configuration options for syncing LDAP-based realms can be found in the
 +
Sync Options tab of the Add/Edit window.
 +
The configuration options are as follows:
 +
Bind User (bind_dn): Refers to the LDAP account used to query users
 +
  and groups. This account needs access to all desired entries. If it&#8217;s set, the
 +
  search will be carried out via binding; otherwise, the search will be carried
 +
  out anonymously. The user must be a complete LDAP formatted distinguished name
 +
  (DN), for example, cn=admin,dc=example,dc=com.
 +
Groupname attr. (group_name_attr): Represents the
 +
  users' groups. Only entries which adhere to the usual character limitations of
 +
  the user.cfg are synced. Groups are synced with -$realm attached to the
 +
  name, in order to avoid naming conflicts. Please ensure that a sync does not
 +
  overwrite manually created groups.
 +
User classes (user_classes): Objects classes associated with users.
 +
Group classes (group_classes): Objects classes associated with groups.
 +
E-Mail attribute: If the LDAP-based server specifies user email addresses,
 +
  these can also be included in the sync by setting the associated attribute
 +
  here. From the command line, this is achievable through the
 +
  --sync_attributes parameter.
 +
User Filter (filter): For further filter options to target specific users.
 +
Group Filter (group_filter): For further filter options to target specific
 +
  groups.
 +
Filters allow you to create a set of additional match criteria, to narrow
 +
down the scope of a sync. Information on available LDAP filter types and their
 +
usage can be found at ldap.com.
 +
Sync Options
 +
In addition to the options specified in the previous section, you can also
 +
configure further options that describe the behavior of the sync operation.
 +
These options are either set as parameters before the sync, or as defaults via
 +
the realm option sync-defaults-options.
 +
The main options for syncing are:
 +
Scope (scope): The scope of what to sync. It can be either users,
 +
  groups or both.
 +
Enable new (enable-new): If set, the newly synced users are enabled and
 +
  can log in. The default is true.
 +
Full (full): If set, the sync uses the LDAP directory as a source of
 +
  truth, overwriting information set manually in the user.cfg and deleting
 +
  users and groups which are not present in the LDAP directory. If not set, only
 +
  new data is written to the configuration, and no stale users are deleted.
 +
Purge ACLs (purge): If set, sync removes all corresponding ACLs when
 +
  removing users and groups. This is only useful with the option full.
 +
Preview (dry-run): No data is written to the config. This is useful if you
 +
  want to see which users and groups would get synced to the user.cfg.
 +
OpenID Connect
 +
The main OpenID Connect configuration options are:
 +
Issuer URL (issuer-url): This is the URL of the authorization server.
 +
Proxmox uses the OpenID Connect Discovery protocol to automatically configure
 +
further details.
 +
While it is possible to use unencrypted http:// URLs, we strongly recommend to
 +
use encrypted https:// connections.
 +
Realm (realm): The realm identifier for Proxmox VE users
 +
Client ID (client-id):  OpenID Client ID.
 +
Client Key (client-key): Optional OpenID Client Key.
 +
Autocreate Users (autocreate): Automatically create users if they do not
 +
exist. While authentication is done at the OpenID server, all users still need
 +
an entry in the Proxmox VE user configuration. You can either add them manually, or
 +
use the autocreate option to automatically add new users.
 +
Username Claim (username-claim): OpenID claim used to generate the unique
 +
username (subject, username or email).
 +
Username mapping
 +
The OpenID Connect specification defines a single unique attribute
 +
(claim in OpenID terms) named subject. By default, we use the
 +
value of this attribute to generate Proxmox VE usernames, by simple adding
 +
@ and the realm name: ${subject}@${realm}.
 +
Unfortunately, most OpenID servers use random strings for subject, like
 +
DGH76OKH34BNG3245SB, so a typical username would look like
 +
DGH76OKH34BNG3245SB@yourrealm. While unique, it is difficult for
 +
humans to remember such random strings, making it quite impossible to
 +
associate real users with this.
 +
The username-claim setting allows you to use other attributes for
 +
the username mapping. Setting it to username is preferred if the
 +
OpenID Connect server provides that attribute and guarantees its
 +
uniqueness.
 +
Another option is to use email, which also yields human readable
 +
usernames. Again, only use this setting if the server guarantees the
 +
uniqueness of this attribute.
 +
Examples
 +
Here is an example of creating an OpenID realm using Google. You need to
 +
replace --client-id and --client-key with the values
 +
from your Google OpenID settings.
 +
pveum realm add myrealm1 --type openid --issuer-url  https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
 +
The above command uses --username-claim email, so that the usernames on the
 +
Proxmox VE side look like example.user@google.com@myrealm1.
 +
Keycloak (https://www.keycloak.org/) is a popular open source Identity
 +
and Access Management tool, which supports OpenID Connect. In the following
 +
example, you need to replace the --issuer-url and --client-id with
 +
your information:
 +
pveum realm add myrealm2 --type openid --issuer-url  https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username
 +
Using --username-claim username enables simple usernames on the
 +
Proxmox VE side, like example.user@myrealm2.
 +
You need to ensure that the user is not allowed to edit
 +
the username setting themselves (on the Keycloak server).
 +
Two-Factor Authentication
 +
There are two ways to use two-factor authentication:
 +
It can be required by the authentication realm, either via TOTP
 +
(Time-based One-Time Password) or YubiKey OTP. In this case, a newly
 +
created user needs to have their keys added immediately, as there is no way to
 +
log in without the second factor. In the case of TOTP, users can
 +
also change the TOTP later on, provided they can log in first.
 +
Alternatively, users can choose to opt-in to two-factor authentication
 +
later on, even if the realm does not enforce it.
 +
Available Second Factors
 +
You can set up multiple second factors, in order to avoid a situation in
 +
which losing your smartphone or security key locks you out of your
 +
account permanently.
 +
The following two-factor authentication methods are available in
 +
addition to realm-enforced TOTP and YubiKey OTP:
 +
User configured TOTP
 +
  (Time-based One-Time Password).
 +
  A short code derived from a shared secret and the current time, it changes
 +
  every 30 seconds.
 +
WebAuthn (Web Authentication).
 +
  A general standard for authentication. It is implemented by various
 +
  security devices, like hardware keys or trusted platform modules (TPM)
 +
  from a computer or smart phone.
 +
Single use Recovery Keys. A list of keys which should either be
 +
  printed out and locked in a secure place or saved digitally in an
 +
  electronic vault. Each key can be used only once. These are perfect for
 +
  ensuring that you are not locked out, even if all of your other second
 +
  factors are lost or corrupt.
 +
Before WebAuthn was supported, U2F could be setup by the user. Existing
 +
U2F factors can still be used, but it is recommended to switch to
 +
WebAuthn, once it is configured on the server.
 +
Realm Enforced 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 log in.
 
Currently there are two methods available:
 
Currently there are two methods available:
Time based OATH (TOTP)
+
Time-based OATH (TOTP)
This uses the standard HMAC-SHA1 algorithm where the current time is hashed
+
This uses the standard HMAC-SHA1 algorithm,
with the user&#8217;s configured key. The time step and password length
+
where the current time is hashed with the user&#8217;s configured key. The
parameters are configured.
+
time step and password length parameters are configurable.
A user can have multiple keys configured (separated by spaces), and the
+
A user can have multiple keys configured (separated by spaces), and the keys
keys can be specified in Base32 (RFC3548) or hexadecimal notation.
+
can be specified in Base32 (RFC3548) or hexadecimal notation.
Proxmox VE provides a key generation tool (oathkeygen) which prints out a
+
Proxmox VE provides a key generation tool (oathkeygen) which prints out a random
random key in Base32 notation which can be used directly with various OTP
+
key in Base32 notation, that can be used directly with various OTP tools, such
tools, such as the oathtool command line tool, the Google authenticator
+
as the oathtool command line tool, or on Android Google Authenticator,
or FreeOTP Android apps.
+
FreeOTP, andOTP or similar applications.
 
YubiKey OTP
 
YubiKey OTP
 
For authenticating via a YubiKey a Yubico API ID, API KEY and validation
 
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
 
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
 
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
+
after connecting it via USB, and copy the first 12 characters of the typed
 
password into the user&#8217;s Key IDs field.
 
password into the user&#8217;s Key IDs field.
Please refer to the
+
Please refer to the YubiKey OTP
YubiKey OTP documentation for how to use the
+
documentation for how to use the
 
YubiCloud or
 
YubiCloud or
 
host your own verification server.
 
host your own verification server.
User configured TOTP authentication
+
User Configured TOTP Authentication
A user can choose to use TOTP as a second factor on login via the TFA button
+
Users can choose to enable TOTP or WebAuthn as a second factor on login, via
in the user list, unless the realm enforces YubiKey OTP.
+
the TFA button in the user list (unless the realm enforces YubiKey OTP).
After opening the TFA window, the user is presented with a dialog to setup
+
Users can always add and use one time Recovery Keys.
TOTP authentication. The Secret field contains the key, which can simply be
+
After opening the TFA window, the user is presented with a dialog to set up
generated randomly via the Randomize button. An optional Issuer Name can be
+
TOTP authentication. The Secret field contains the key, which can be
added to provide information to the TOTP app what the key belongs to.
+
randomly generated via the Randomize button. An optional Issuer Name can be
 +
added to provide information to the TOTP app about what the key belongs to.
 
Most TOTP apps will show the issuer name together with the corresponding
 
Most TOTP apps will show the issuer name together with the corresponding
OTP values. The user name is also included in the QR code for the TOTP app.
+
OTP values. The username is also included in the QR code for the TOTP app.
After generating a key, a QR code will be displayed which can be used with most
+
After generating a key, a QR code will be displayed, which can be used with most
OTP apps such as FreeOTP. Now the user needs to verify both the current user
+
OTP apps such as FreeOTP. The user then needs to verify the current user
 
password (unless logged in as root), as well as the ability to correctly use
 
password (unless logged in as root), as well as the ability to correctly use
the TOTP key by typing the current OTP value into the Verification Code
+
the TOTP key, by typing the current OTP value into the Verification Code
field before pressing the Apply button.
+
field and pressing the Apply button.
Server side U2F configuration
+
TOTP
To allow users to use U2F authentication, the server needs to have a valid
+
There is no server setup required. Simply install a TOTP app on your
domain with a valid https certificate. Initially an AppId
+
smartphone (for example, FreeOTP) and use
 +
the Proxmox Backup Server web-interface to add a TOTP factor.
 +
WebAuthn
 +
For WebAuthn to work, you need to have two things:
 +
A trusted HTTPS certificate (for example, by using
 +
  Let&#8217;s Encrypt).
 +
  While it probably works with an untrusted certificate, some browsers may
 +
  warn or refuse WebAuthn operations if it is not trusted.
 +
Setup the WebAuthn configuration (see Datacenter &#8594; Options &#8594;
 +
  WebAuthn Settings in the Proxmox VE web interface). This can be
 +
  auto-filled in most setups.
 +
Once you have fulfilled both of these requirements, you can add a WebAuthn
 +
configuration in the Two Factor panel under Datacenter &#8594; Permissions &#8594; Two
 +
Factor.
 +
Recovery Keys
 +
Recovery key codes do not need any preparation; you can simply create a
 +
set of recovery keys in the Two Factor panel under Datacenter &#8594; Permissions
 +
&#8594; Two Factor.
 +
There can only be one set of single-use recovery keys per user at any
 +
time.
 +
Server Side Webauthn Configuration
 +
To allow users to use WebAuthn authentication, it is necessaary to use a valid
 +
domain with a valid SSL certificate, otherwise some browsers may warn or refuse
 +
to authenticate altogether.
 +
Changing the WebAuthn configuration may render all existing WebAuthn
 +
registrations unusable!
 +
This is done via /etc/pve/datacenter.cfg. For instance:
 +
webauthn:
 +
rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
 +
Server Side U2F Configuration
 +
It is recommended to use WebAuthn instead.
 +
To allow users to use U2F authentication, it may be necessary to use a valid
 +
domain with a valid SSL certificate, otherwise, some browsers may print
 +
a warning or reject U2F usage altogether. Initially, an AppId
 
[AppId https://developers.yubico.com/U2F/App_ID.html]
 
[AppId https://developers.yubico.com/U2F/App_ID.html]
 
needs to be configured.
 
needs to be configured.
 
Changing the AppId will render all existing U2F registrations
 
Changing the AppId will render all existing U2F registrations
 
unusable!
 
unusable!
This is done via /etc/pve/datacenter.cfg, for instance:
+
This is done via /etc/pve/datacenter.cfg. For instance:
 
u2f: appid=https://mypve.example.com:8006
 
u2f: appid=https://mypve.example.com:8006
For a single node, the AppId can simply be the web UI address exactly as it
+
For a single node, the AppId can simply be the address of the web-interface,
is used in the browser, including the https:// and the port as shown above.
+
exactly as it is used in the browser, including the https:// and the port, as
Please note that some browsers may be more strict than others when matching
+
shown above. Please note that some browsers may be more strict than others when
AppIds.
+
matching AppIds.
 
When using multiple nodes, it is best to have a separate https server
 
When using multiple nodes, it is best to have a separate https server
 
providing an appid.json
 
providing an appid.json
Line 153: Line 392:
 
file, as it seems to be compatible with most
 
file, as it seems to be compatible with most
 
browsers. If all nodes use subdomains of the same top level domain, it may be
 
browsers. If all nodes use subdomains of the same top level domain, it may be
enough to use the TLD as AppId, but note that some browsers may not accept
+
enough to use the TLD as AppId. It should however be noted that some browsers
this.
+
may not accept this.
 
A bad AppId will usually produce an error, but we have encountered
 
A bad AppId will usually produce an error, but we have encountered
situation where this does not happen, particularly when using a top level domain
+
situations when this does not happen, particularly when using a top level domain
AppId for a node accessed via a subdomain in Chromium. For this reason it is
+
AppId for a node that is accessed via a subdomain in Chromium. For this reason
recommended to test the configuration with multiple browsers, as changing the
+
it is recommended to test the configuration with multiple browsers, as changing
AppId later will render existing U2F registrations unusable.
+
the AppId later will render existing U2F registrations unusable.
Activating U2F as a user
+
Activating U2F as a User
 
To enable U2F authentication, open the TFA window&#8217;s U2F tab, type in the
 
To enable U2F authentication, open the TFA window&#8217;s U2F tab, type in the
 
current password (unless logged in as root), and press the Register button.
 
current password (unless logged in as root), and press the Register button.
If the server is setup correctly and the browser accepted the server&#8217;s provided
+
If the server is set up correctly and the browser accepts the server&#8217;s provided
 
AppId, a message will appear prompting the user to press the button on the
 
AppId, a message will appear prompting the user to press the button on the
U2F device (if it is a YubiKey the button light should be toggling off and
+
U2F device (if it is a YubiKey, the button light should be toggling on and
on steadily around twice per second).
+
off steadily, roughly twice per second).
 
Firefox users may need to enable security.webauth.u2f via about:config
 
Firefox users may need to enable security.webauth.u2f via about:config
 
before they can use a U2F token.
 
before they can use a U2F token.
 
Permission Management
 
Permission Management
 
In order for a user to perform an action (such as listing, modifying or
 
In order for a user to perform an action (such as listing, modifying or
deleting a parts of a VM configuration), the user needs to have the
+
deleting parts of a VM&#8217;s configuration), the user needs to have the
 
appropriate permissions.
 
appropriate permissions.
 
Proxmox VE uses a role and path based permission management system. An entry in
 
Proxmox VE uses a role and path based permission management system. An entry in
the permissions table allows a user or group to take on a specific role
+
the permissions table allows a user, group or token to take on a specific role
when accessing an object or path. This means an such an access rule can
+
when accessing an object or path. This means that such an access rule can
be represented as a triple of (path, user, role) or (path, group,
+
be represented as a triple of (path, user, role), (path, group,
role), with the role containing a set of allowed actions, and the path
+
role) or (path, token, role), with the role containing a set of allowed
representing the target of these actions.
+
actions, and the path representing the target of these actions.
 
Roles
 
Roles
 
A role is simply a list of privileges. Proxmox VE comes with a number
 
A role is simply a list of privileges. Proxmox VE comes with a number
of predefined roles which satisfies most needs.
+
of predefined roles, which satisfy most requirements.
Administrator: has all privileges
+
Administrator: has full privileges
 
NoAccess: has no privileges (used to forbid access)
 
NoAccess: has no privileges (used to forbid access)
PVEAdmin: can do most things, but miss rights to modify system settings (Sys.PowerMgmt, Sys.Modify, Realm.Allocate).
+
PVEAdmin: can do most tasks, but has no rights to modify system settings (Sys.PowerMgmt, Sys.Modify, Realm.Allocate)
PVEAuditor: read only access
+
PVEAuditor: has read only access
 
PVEDatastoreAdmin: create and allocate backup space and templates
 
PVEDatastoreAdmin: create and allocate backup space and templates
 
PVEDatastoreUser: allocate backup space and view storage
 
PVEDatastoreUser: allocate backup space and view storage
Line 191: Line 430:
 
PVESysAdmin: User ACLs, audit, system console and system logs
 
PVESysAdmin: User ACLs, audit, system console and system logs
 
PVETemplateUser: view and clone templates
 
PVETemplateUser: view and clone templates
PVEUserAdmin: user administration
+
PVEUserAdmin: manage users
 
PVEVMAdmin: fully administer VMs
 
PVEVMAdmin: fully administer VMs
PVEVMUser: view, backup, config CDROM, VM console, VM power management
+
PVEVMUser: view, backup, configure CD-ROM, VM console, VM power management
You can see the whole set of predefined roles on the GUI.
+
You can see the whole set of predefined roles in the GUI.
Adding new roles can be done via both GUI and the command line.
+
You can add new roles via the GUI or the command line.
For the GUI just navigate to Permissions &#8594; User Tab from Datacenter and
+
From the GUI, navigate to the Permissions &#8594; Roles tab from Datacenter and
click on the Create button, there you can set a name and select all desired
+
click on the Create button. There you can set a role name and select any
roles from the Privileges dropdown box.
+
desired privileges from the Privileges drop-down menu.
To add a role through the command line you can use the pveum CLI tool, like
+
To add a role through the command line, you can use the pveum CLI tool, for
this:
+
example:
pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+
pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
+
pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
 
Privileges
 
Privileges
 
A privilege is the right to perform a specific action. To simplify
 
A privilege is the right to perform a specific action. To simplify
 
management, lists of privileges are grouped into roles, which can then
 
management, lists of privileges are grouped into roles, which can then
be used in the permission table. Note that privileges cannot directly be
+
be used in the permission table. Note that privileges cannot be directly
 
assigned to users and paths without being part of a role.
 
assigned to users and paths without being part of a role.
We currently use the following privileges:
+
We currently support the following privileges:
 
Node / System related privileges
 
Node / System related privileges
 
Permissions.Modify: modify access permissions
 
Permissions.Modify: modify access permissions
Sys.PowerMgmt: Node power management (start, stop, reset, shutdown, &#8230;)
+
Sys.PowerMgmt: node power management (start, stop, reset, shutdown, &#8230;)
Sys.Console: console access to Node
+
Sys.Console: console access to node
Sys.Syslog: view Syslog
+
Sys.Syslog: view syslog
Sys.Audit: view node status/config, Corosync cluster config and HA config
+
Sys.Audit: view node status/config, Corosync cluster config, and HA config
Sys.Modify: create/remove/modify node network parameters
+
Sys.Modify: create/modify/remove node network parameters
Group.Allocate: create/remove/modify groups
+
Group.Allocate: create/modify/remove groups
Pool.Allocate: create/remove/modify a pool
+
Pool.Allocate: create/modify/remove a pool
Realm.Allocate: create/remove/modify authentication realms
+
Pool.Audit: view a pool
 +
Realm.Allocate: create/modify/remove authentication realms
 
Realm.AllocateUser: assign user to a realm
 
Realm.AllocateUser: assign user to a realm
User.Modify: create/remove/modify user access and details.
+
User.Modify: create/modify/remove user access and details.
 
Virtual machine related privileges
 
Virtual machine related privileges
VM.Allocate: create/remove new VM to server inventory
+
VM.Allocate: create/remove VM on a server
 
VM.Migrate: migrate VM to alternate server on cluster
 
VM.Migrate: migrate VM to alternate server on cluster
 
VM.PowerMgmt: power management (start, stop, reset, shutdown, &#8230;)
 
VM.PowerMgmt: power management (start, stop, reset, shutdown, &#8230;)
Line 230: Line 470:
 
VM.Audit: view VM config
 
VM.Audit: view VM config
 
VM.Clone: clone/copy a VM
 
VM.Clone: clone/copy a VM
VM.Config.Disk: add/modify/delete Disks
+
VM.Config.Disk: add/modify/remove disks
VM.Config.CDROM: eject/change CDROM
+
VM.Config.CDROM: eject/change CD-ROM
 
VM.Config.CPU: modify CPU settings
 
VM.Config.CPU: modify CPU settings
VM.Config.Memory: modify Memory settings
+
VM.Config.Memory: modify memory settings
VM.Config.Network: add/modify/delete Network devices
+
VM.Config.Network: add/modify/remove network devices
VM.Config.HWType: modify emulated HW type
+
VM.Config.HWType: modify emulated hardware types
 
VM.Config.Options: modify any other VM configuration
 
VM.Config.Options: modify any other VM configuration
VM.Snapshot: create/remove VM snapshots
+
VM.Snapshot: create/delete VM snapshots
 
Storage related privileges
 
Storage related privileges
Datastore.Allocate: create/remove/modify a data store, delete volumes
+
Datastore.Allocate: create/modify/remove a datastore and delete volumes
 
Datastore.AllocateSpace: allocate space on a datastore
 
Datastore.AllocateSpace: allocate space on a datastore
Datastore.AllocateTemplate: allocate/upload templates and iso images
+
Datastore.AllocateTemplate: allocate/upload templates and ISO images
 
Datastore.Audit: view/browse a datastore
 
Datastore.Audit: view/browse a datastore
 
Objects and Paths
 
Objects and Paths
Access permissions are assigned to objects, such as a virtual machines,
+
Access permissions are assigned to objects, such as virtual machines,
storages or pools of resources.
+
storages or resource pools.
 
We use file system like paths to address these objects. These paths form a
 
We use file system like paths to address these objects. These paths form a
natural tree, and permissions of higher levels (shorter path) can
+
natural tree, and permissions of higher levels (shorter paths) can
 
optionally be propagated down within this hierarchy.
 
optionally be propagated down within this hierarchy.
 
Paths can be templated. When an API call requires permissions on a
 
Paths can be templated. When an API call requires permissions on a
 
templated path, the path may contain references to parameters of the API
 
templated path, the path may contain references to parameters of the API
 
call. These references are specified in curly braces. Some parameters are
 
call. These references are specified in curly braces. Some parameters are
implicitly taken from the API call&#8217;s URI. For instance the permission path
+
implicitly taken from the API call&#8217;s URI. For instance, the permission path
 
/nodes/{node} when calling /nodes/mynode/status requires permissions on
 
/nodes/{node} when calling /nodes/mynode/status requires permissions on
 
/nodes/mynode, while the path {path} in a PUT request to /access/acl
 
/nodes/mynode, while the path {path} in a PUT request to /access/acl
Line 260: Line 500:
 
/vms: Covers all VMs
 
/vms: Covers all VMs
 
/vms/{vmid}: Access to specific VMs
 
/vms/{vmid}: Access to specific VMs
/storage/{storeid}: Access to a storages
+
/storage/{storeid}: Access to a specific storage
/pool/{poolname}: Access to VMs part of a pool
+
/pool/{poolname}: Access to resources contained in a specific pool
 
/access/groups: Group administration
 
/access/groups: Group administration
 
/access/realms/{realmid}: Administrative access to realms
 
/access/realms/{realmid}: Administrative access to realms
 
Inheritance
 
Inheritance
 
As mentioned earlier, object paths form a file system 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
+
permissions can be inherited by objects down that tree (the propagate flag is
by default). We use the following inheritance rules:
+
set by default). We use the following inheritance rules:
 
Permissions for individual users always replace group permissions.
 
Permissions for individual users always replace group permissions.
 
Permissions for groups apply when the user is member of that group.
 
Permissions for groups apply when the user is member of that group.
Permissions replace the ones inherited from an upper level.
+
Permissions on deeper levels replace those inherited from an upper level.
 +
Additionally, privilege separated tokens can never have permissions on any
 +
given path that their associated user does not have.
 
Pools
 
Pools
Pools can be used to group a set of virtual machines and data
+
Pools can be used to group a set of virtual machines and datastores. You can
stores. You can then simply set permissions on pools (/pool/{poolid}),
+
then simply set permissions on pools (/pool/{poolid}), which are inherited by
which are inherited to all pool members. This is a great way simplify
+
all pool members. This is a great way to simplify access control.
access control.
+
Which Permissions Do I Need?
What permission do I need?
 
 
The required API permissions are documented for each individual
 
The required API permissions are documented for each individual
method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
+
method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/.
The permissions are specified as a list which can be interpreted as a
+
The permissions are specified as a list, which can be interpreted as a
 
tree of logic and access-check functions:
 
tree of logic and access-check functions:
 
["and", &lt;subtests&gt;...] and ["or", &lt;subtests&gt;...]
 
["and", &lt;subtests&gt;...] and ["or", &lt;subtests&gt;...]
Line 285: Line 526:
 
["perm", &lt;path&gt;, [ &lt;privileges&gt;... ], &lt;options&gt;...]
 
["perm", &lt;path&gt;, [ &lt;privileges&gt;... ], &lt;options&gt;...]
 
The path is a templated parameter (see
 
The path is a templated parameter (see
Objects and Paths). All (or , if the any
+
Objects and Paths). All (or, if the any
 
option is used, any) of the listed
 
option is used, any) of the listed
 
privileges must be allowed on the specified path. If a require-param
 
privileges must be allowed on the specified path. If a require-param
Line 292: Line 533:
 
["userid-group", [ &lt;privileges&gt;... ], &lt;options&gt;...]
 
["userid-group", [ &lt;privileges&gt;... ], &lt;options&gt;...]
 
The caller must have any of the listed privileges on /access/groups. In
 
The caller must have any of the listed privileges on /access/groups. In
addition there are two possible checks depending on whether the
+
addition, there are two possible checks, depending on whether the
 
groups_param option is set:
 
groups_param option is set:
 
groups_param is set: The API call has a non-optional groups parameter
 
groups_param is set: The API call has a non-optional groups parameter
Line 302: Line 543:
 
["userid-param", "self"]
 
["userid-param", "self"]
 
The value provided for the API call&#8217;s userid parameter must refer to the
 
The value provided for the API call&#8217;s userid parameter must refer to the
user performing the action. (Usually in conjunction with or, to allow
+
user performing the action (usually in conjunction with or, to allow
users to perform an action on themselves even if they don&#8217;t have elevated
+
users to perform an action on themselves, even if they don&#8217;t have elevated
privileges.)
+
privileges).
 
["userid-param", "Realm.AllocateUser"]
 
["userid-param", "Realm.AllocateUser"]
 
The user needs Realm.AllocateUser access to /access/realm/&lt;realm&gt;, with
 
The user needs Realm.AllocateUser access to /access/realm/&lt;realm&gt;, with
Line 314: Line 555:
 
The path is a templated parameter (see
 
The path is a templated parameter (see
 
Objects and Paths). The user needs either the
 
Objects and Paths). The user needs either the
Permissions.Modify privilege, or,
+
Permissions.Modify privilege or,
 
depending on the path, the following privileges as a possible substitute:
 
depending on the path, the following privileges as a possible substitute:
 
/storage/...: additionally requires 'Datastore.Allocate`
 
/storage/...: additionally requires 'Datastore.Allocate`
Line 322: Line 563:
 
Command Line Tool
 
Command Line Tool
 
Most users will simply use the GUI to manage users. But there is also
 
Most users will simply use the GUI to manage users. But there is also
a full featured command line tool called pveum (short for &#8220;Proxmox
+
a fully featured command line tool called pveum (short for &#8220;Proxmox
 
VE User Manager&#8221;). Please note that all Proxmox VE command
 
VE User Manager&#8221;). Please note that all Proxmox VE command
 
line tools are wrappers around the API, so you can also access those
 
line tools are wrappers around the API, so you can also access those
function through the REST API.
+
functions through the REST API.
Here are some simple usage examples. To show help type:
+
Here are some simple usage examples. To show help, type:
 
pveum
 
pveum
 
or (to show detailed help about a specific command)
 
or (to show detailed help about a specific command)
pveum help useradd
+
pveum help user add
 
Create a new user:
 
Create a new user:
pveum useradd testuser@pve -comment "Just a test"
+
pveum user add testuser@pve -comment "Just a test"
Set or Change the password (not all realms support that):
+
Set or change the password (not all realms support this):
 
pveum passwd testuser@pve
 
pveum passwd testuser@pve
 
Disable a user:
 
Disable a user:
pveum usermod testuser@pve -enable 0
+
pveum user modify testuser@pve -enable 0
 
Create a new group:
 
Create a new group:
pveum groupadd testgroup
+
pveum group add testgroup
 
Create a new role:
 
Create a new role:
pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+
pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
 
Real World Examples
 
Real World Examples
 
Administrator Group
 
Administrator Group
One of the most wanted features was the ability to define a group of
+
It is possible that an administrator would want to create a group of users with
users with full administrator rights (without using the root account).
+
full administrator rights (without using the root account).
Define the group:
+
To do this, first define the group:
pveum groupadd admin -comment "System Administrators"
+
pveum group add admin -comment "System Administrators"
Then add the permission:
+
Then assign the role:
pveum aclmod / -group admin -role Administrator
+
pveum acl modify / -group admin -role Administrator
You can finally add users to the new admin group:
+
Finally, you can add users to the new admin group:
pveum usermod testuser@pve -group admin
+
pveum user modify testuser@pve -group admin
 
Auditors
 
Auditors
 
You can give read only access to users by assigning the PVEAuditor
 
You can give read only access to users by assigning the PVEAuditor
 
role to users or groups.
 
role to users or groups.
Example1: Allow user joe@pve to see everything
+
Example 1: Allow user joe@pve to see everything
pveum aclmod / -user joe@pve -role PVEAuditor
+
pveum acl modify / -user joe@pve -role PVEAuditor
Example1: Allow user joe@pve to see all virtual machines
+
Example 2: Allow user joe@pve to see all virtual machines
pveum aclmod /vms -user joe@pve -role PVEAuditor
+
pveum acl modify /vms -user joe@pve -role PVEAuditor
 
Delegate User Management
 
Delegate User Management
If you want to delegate user management to user joe@pve you can do
+
If you want to delegate user management to user joe@pve, you can do
 
that with:
 
that with:
pveum aclmod /access -user joe@pve -role PVEUserAdmin
+
pveum acl modify /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, and change other user attributes,
other user attributes. This is a very powerful role, and you most
+
such as passwords. This is a very powerful role, and you most
likely want to limit that to selected realms and groups. The following
+
likely want to limit it to selected realms and groups. The following
example allows joe@pve to modify users within realm pve if they
+
example allows joe@pve to modify users within the realm pve, if they
 
are members of group customers:
 
are members of group customers:
pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
+
pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
+
pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
 
The user is able to add other users, but only if they are
 
The user is able to add other users, but only if they are
members of group customers and within realm pve.
+
members of the group customers and within the realm pve.
Pools
+
Limited API Token for Monitoring
An enterprise is usually structured into several smaller departments,
+
Permissions on API tokens are always a subset of those of their corresponding
and it is common that you want to assign resources to them and
+
user, meaning that an API token can&#8217;t be used to carry out a task that the
delegate management tasks. A pool is simply a set of virtual machines
+
backing user has no permission to do. This section will demonstrate how you can
and data stores. You can create pools on the GUI. After that you can
+
use an API token with separate privileges, to limit the token owner&#8217;s
add resources to the pool (VMs, Storage).
+
permissions further.
You can also assign permissions to the pool. Those permissions are
+
Give the user joe@pve the role PVEVMAdmin on all VMs:
inherited to all pool members.
+
pveum acl modify /vms -user joe@pve -role PVEVMAdmin
Lets assume you have a software development department, so we first
+
Add a new API token with separate privileges, which is only allowed to view VM
create a group
+
information (for example, for monitoring purposes):
pveum groupadd developers -comment "Our software developers"
+
pveum user token add joe@pve monitoring -privsep 1
Now we create a new user which is a member of that group
+
pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
pveum useradd developer1@pve -group developers -password
+
Verify the permissions of the user and token:
The -password parameter will prompt you for a password
+
pveum user permissions joe@pve
I assume we already created a pool called &#8220;dev-pool&#8221; on the GUI. So we can now assign permission to that pool:
+
pveum user token permissions joe@pve monitoring
pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
+
Resource Pools
Our software developers can now administrate the resources assigned to
+
An enterprise is usually structured into several smaller departments, and it is
 +
common that you want to assign resources and delegate management tasks to each
 +
of these. Let&#8217;s assume that you want to set up a pool for a software development
 +
department. First, create a group:
 +
pveum group add developers -comment "Our software developers"
 +
Now we create a new user which is a member of that group:
 +
pveum user add developer1@pve -group developers -password
 +
The "-password" parameter will prompt you for a password
 +
Then we create a resource pool for our development department to use:
 +
pveum pool add dev-pool --comment "IT development pool"
 +
Finally, we can assign permissions to that pool:
 +
pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
 +
Our software developers can now administer the resources assigned to
 
that pool.
 
that pool.
 
</pvehide>
 
</pvehide>

Latest revision as of 10:27, 17 November 2021

Proxmox VE supports multiple authentication sources, for example Linux PAM, an integrated Proxmox VE authentication server, LDAP, Microsoft Active Directory and OpenID Connect.

By using role-based user and permission management for all objects (VMs, Storage, nodes, etc.), granular access can be defined.

Users

Proxmox VE stores user attributes in /etc/pve/user.cfg. Passwords are not stored here; users are instead associated with the authentication realms described below. Therefore, a user is often internally identified by their username and realm in the form <userid>@<realm>.

Each user entry in this file contains the following information:

  • First name

  • Last name

  • E-mail address

  • Group memberships

  • An optional expiration date

  • A comment or note about this user

  • Whether this user is enabled or disabled

  • Optional two-factor authentication keys

Caution When you disable or delete a user, or if the expiry date set is in the past, this user will not be able to log in to new sessions or start new tasks. All tasks which have already been started by this user (for example, terminal sessions) will not be terminated automatically by any such event.

System administrator

The system’s root user can always log in via the Linux PAM realm and is an unconfined administrator. This user cannot be deleted, but attributes can still be changed. System mails will be sent to the email address assigned to this user.

Groups

Each user can be a member of several groups. Groups are the preferred way to organize access permissions. You should always grant permissions to groups instead of individual users. That way you will get a much more maintainable access control list.

API Tokens

API tokens allow stateless access to most parts of the REST API from another system, software or API client. Tokens can be generated for individual users and can be given separate permissions and expiration dates to limit the scope and duration of the access. Should the API token get compromised, it can be revoked without disabling the user itself.

API tokens come in two basic types:

  • Separated privileges: The token needs to be given explicit access with ACLs. Its effective permissions are calculated by intersecting user and token permissions.

  • Full privileges: The token’s permissions are identical to that of the associated user.

Caution The token value is only displayed/returned once when the token is generated. It cannot be retrieved again over the API at a later time!

To use an API token, set the HTTP header Authorization to the displayed value of the form PVEAPIToken=USER@REALM!TOKENID=UUID when making API requests, or refer to your API client’s documentation.

Resource Pools

screenshot/gui-datacenter-pool-window.png

A resource pool is a set of virtual machines, containers, and storage devices. It is useful for permission handling in cases where certain users should have controlled access to a specific set of resources, as it allows for a single permission to be applied to a set of elements, rather than having to manage this on a per-resource basis. Resource pools are often used in tandem with groups, so that the members of a group have permissions on a set of machines and storage.

Authentication Realms

As Proxmox VE 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

Linux PAM is a framework for system-wide user authentication. These users are created on the host system with commands such as adduser. If PAM users exist on the Proxmox VE host system, corresponding entries can be added to Proxmox VE, to allow these users to log in via their system username and password.

Proxmox VE Authentication Server

This is a Unix-like password store, which stores hashed passwords in /etc/pve/priv/shadow.cfg. Passwords are hashed using the SHA-256 hashing algorithm. This is the most convenient realm for small-scale (or even mid-scale) installations, where users do not need access to anything outside of Proxmox VE. In this case, users are fully managed by Proxmox VE and are able to change their own passwords via the GUI.

LDAP

LDAP (Lightweight Directory Access Protocol) is an open, cross-platform protocol for authentication using directory services. OpenLDAP is a popular open-source implementations of the LDAP protocol.

Microsoft Active Directory (AD)

Microsoft Active Directory (AD) is a directory service for Windows domain networks and is supported as an authentication realm for Proxmox VE. It supports LDAP as an authentication protocol.

OpenID Connect

OpenID Connect is implemented as an identity layer on top of the OATH 2.0 protocol. It allows clients to verify the identity of the user, based on authentication performed by an external authorization server.

Linux PAM Standard Authentication

As Linux PAM corresponds to host system users, a system user must exist on each node which the user is allowed to log in on. The user authenticates with their usual system password. This realm is added by default and can’t be removed. In terms of configurability, an administrator can choose to require two-factor authentication with logins from the realm and to set the realm as the default authentication realm.

Proxmox VE Authentication Server

The Proxmox VE authentication server realm is a simple Unix-like password store. The realm is created by default, and as with Linux PAM, the only configuration items available are the ability to require two-factor authentication for users of the realm, and to set it as the default realm for login.

Unlike the other Proxmox VE realm types, users are created and authenticated entirely through Proxmox VE, rather than authenticating against another system. Hence, you are required to set a password for this type of user upon creation.

LDAP

You can also use an external LDAP server for user authentication (for examle, OpenLDAP). In this realm type, users are searched under a Base Domain Name (base_dn), using the username attribute specified in the User Attribute Name (user_attr) field.

A server and optional fallback server can be configured, and the connection can be encrypted via SSL. Furthermore, filters can be configured for directories and groups. Filters allow you to further limit the scope of the realm.

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 Proxmox VE 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 (for example, /etc/pve/priv/ldap/my-ldap.pw). This file should contain a single line with the raw password.

To verify certificates, you need to set capath. You can set it either directly to the CA certificate of your LDAP server, or to the system path containing all trusted CA certificates (/etc/ssl/certs). Additionally, you need to set the verify option, which can also be done over the web interface.

The main configuration options for an LDAP server realm are as follows:

  • Realm (realm): The realm identifier for Proxmox VE users

  • Base Domain Name (base_dn): The directory which users are searched under

  • User Attribute Name (user_attr): The LDAP attribute containing the username that users will log in with

  • Server (server1): The server hosting the LDAP directory

  • Fallback Server (server2): An optional fallback server address, in case the primary server is unreachable

  • Port (port): The port that the LDAP server listens on

Note In order to allow a particular user to authenticate using the LDAP server, you must also add them as a user of that realm from the Proxmox VE server. This can be carried out automatically with syncing.

Microsoft Active Directory (AD)

To set up Microsoft AD as a realm, a server address and authentication domain need to be specified. Active Directory supports most of the same properties as LDAP, such as an optional fallback server, port, and SSL encryption. Furthermore, users can be added to Proxmox VE automatically via sync operations, after configuration.

As with LDAP, if Proxmox VE needs to authenticate before it binds to the AD server, you must configure the Bind User (bind_dn) property. This property is typically required by default for Microsoft AD.

The main configuration settings for Microsoft Active Directory are:

  • Realm (realm): The realm identifier for Proxmox VE users

  • Domain (domain): The AD domain of the server

  • Server (server1): The FQDN or IP address of the server

  • Fallback Server (server2): An optional fallback server address, in case the primary server is unreachable

  • Port (port): The port that the Microsoft AD server listens on

Syncing LDAP-Based Realms

screenshot/gui-datacenter-realm-add-ldap.png

It’s possible to automatically sync users and groups for LDAP-based realms (LDAP & Microsoft Active Directory), rather than having to add them to Proxmox VE manually. You can access the sync options from the Add/Edit window of the web interface’s Authentication panel or via the pveum realm add/modify commands. You can then carry out the sync operation from the Authentication panel of the GUI or using the following command:

pveum realm sync <realm>

Users and groups are synced to the cluster-wide configuration file, /etc/pve/user.cfg.

Sync Configuration

The configuration options for syncing LDAP-based realms can be found in the Sync Options tab of the Add/Edit window.

The configuration options are as follows:

  • Bind User (bind_dn): Refers to the LDAP account used to query users and groups. This account needs access to all desired entries. If it’s set, the search will be carried out via binding; otherwise, the search will be carried out anonymously. The user must be a complete LDAP formatted distinguished name (DN), for example, cn=admin,dc=example,dc=com.

  • Groupname attr. (group_name_attr): Represents the users' groups. Only entries which adhere to the usual character limitations of the user.cfg are synced. Groups are synced with -$realm attached to the name, in order to avoid naming conflicts. Please ensure that a sync does not overwrite manually created groups.

  • User classes (user_classes): Objects classes associated with users.

  • Group classes (group_classes): Objects classes associated with groups.

  • E-Mail attribute: If the LDAP-based server specifies user email addresses, these can also be included in the sync by setting the associated attribute here. From the command line, this is achievable through the --sync_attributes parameter.

  • User Filter (filter): For further filter options to target specific users.

  • Group Filter (group_filter): For further filter options to target specific groups.

Note Filters allow you to create a set of additional match criteria, to narrow down the scope of a sync. Information on available LDAP filter types and their usage can be found at ldap.com.

Sync Options

screenshot/gui-datacenter-realm-add-ldap-sync-options.png

In addition to the options specified in the previous section, you can also configure further options that describe the behavior of the sync operation.

These options are either set as parameters before the sync, or as defaults via the realm option sync-defaults-options.

The main options for syncing are:

  • Scope (scope): The scope of what to sync. It can be either users, groups or both.

  • Enable new (enable-new): If set, the newly synced users are enabled and can log in. The default is true.

  • Full (full): If set, the sync uses the LDAP directory as a source of truth, overwriting information set manually in the user.cfg and deleting users and groups which are not present in the LDAP directory. If not set, only new data is written to the configuration, and no stale users are deleted.

  • Purge ACLs (purge): If set, sync removes all corresponding ACLs when removing users and groups. This is only useful with the option full.

  • Preview (dry-run): No data is written to the config. This is useful if you want to see which users and groups would get synced to the user.cfg.

OpenID Connect

The main OpenID Connect configuration options are:

  • Issuer URL (issuer-url): This is the URL of the authorization server. Proxmox uses the OpenID Connect Discovery protocol to automatically configure further details.

    While it is possible to use unencrypted http:// URLs, we strongly recommend to use encrypted https:// connections.

  • Realm (realm): The realm identifier for Proxmox VE users

  • Client ID (client-id): OpenID Client ID.

  • Client Key (client-key): Optional OpenID Client Key.

  • Autocreate Users (autocreate): Automatically create users if they do not exist. While authentication is done at the OpenID server, all users still need an entry in the Proxmox VE user configuration. You can either add them manually, or use the autocreate option to automatically add new users.

  • Username Claim (username-claim): OpenID claim used to generate the unique username (subject, username or email).

Username mapping

The OpenID Connect specification defines a single unique attribute (claim in OpenID terms) named subject. By default, we use the value of this attribute to generate Proxmox VE usernames, by simple adding @ and the realm name: ${subject}@${realm}.

Unfortunately, most OpenID servers use random strings for subject, like DGH76OKH34BNG3245SB, so a typical username would look like DGH76OKH34BNG3245SB@yourrealm. While unique, it is difficult for humans to remember such random strings, making it quite impossible to associate real users with this.

The username-claim setting allows you to use other attributes for the username mapping. Setting it to username is preferred if the OpenID Connect server provides that attribute and guarantees its uniqueness.

Another option is to use email, which also yields human readable usernames. Again, only use this setting if the server guarantees the uniqueness of this attribute.

Examples

Here is an example of creating an OpenID realm using Google. You need to replace --client-id and --client-key with the values from your Google OpenID settings.

pveum realm add myrealm1 --type openid --issuer-url  https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email

The above command uses --username-claim email, so that the usernames on the Proxmox VE side look like example.user@google.com@myrealm1.

Keycloak (https://www.keycloak.org/) is a popular open source Identity and Access Management tool, which supports OpenID Connect. In the following example, you need to replace the --issuer-url and --client-id with your information:

pveum realm add myrealm2 --type openid --issuer-url  https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username

Using --username-claim username enables simple usernames on the Proxmox VE side, like example.user@myrealm2.

Warning You need to ensure that the user is not allowed to edit the username setting themselves (on the Keycloak server).

Two-Factor Authentication

There are two ways to use two-factor authentication:

It can be required by the authentication realm, either via TOTP (Time-based One-Time Password) or YubiKey OTP. In this case, a newly created user needs to have their keys added immediately, as there is no way to log in without the second factor. In the case of TOTP, users can also change the TOTP later on, provided they can log in first.

Alternatively, users can choose to opt-in to two-factor authentication later on, even if the realm does not enforce it.

Available Second Factors

You can set up multiple second factors, in order to avoid a situation in which losing your smartphone or security key locks you out of your account permanently.

The following two-factor authentication methods are available in addition to realm-enforced TOTP and YubiKey OTP:

  • User configured TOTP (Time-based One-Time Password). A short code derived from a shared secret and the current time, it changes every 30 seconds.

  • WebAuthn (Web Authentication). A general standard for authentication. It is implemented by various security devices, like hardware keys or trusted platform modules (TPM) from a computer or smart phone.

  • Single use Recovery Keys. A list of keys which should either be printed out and locked in a secure place or saved digitally in an electronic vault. Each key can be used only once. These are perfect for ensuring that you are not locked out, even if all of your other second factors are lost or corrupt.

Before WebAuthn was supported, U2F could be setup by the user. Existing U2F factors can still be used, but it is recommended to switch to WebAuthn, once it is configured on the server.

Realm Enforced 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 log in.

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 configurable.

A user can have multiple keys configured (separated by spaces), and the keys can be specified in Base32 (RFC3548) or hexadecimal notation.

Proxmox VE provides a key generation tool (oathkeygen) which prints out a random key in Base32 notation, that can be used directly with various OTP tools, such as the oathtool command line tool, or on Android Google Authenticator, FreeOTP, andOTP or similar applications.

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 via USB, and copy the first 12 characters of the typed password into the user’s Key IDs field.

Please refer to the YubiKey OTP documentation for how to use the YubiCloud or host your own verification server.

User Configured TOTP Authentication

Users can choose to enable TOTP or WebAuthn as a second factor on login, via the TFA button in the user list (unless the realm enforces YubiKey OTP).

Users can always add and use one time Recovery Keys.

screenshot/gui-datacenter-two-factor.png

After opening the TFA window, the user is presented with a dialog to set up TOTP authentication. The Secret field contains the key, which can be randomly generated via the Randomize button. An optional Issuer Name can be added to provide information to the TOTP app about what the key belongs to. Most TOTP apps will show the issuer name together with the corresponding OTP values. The username is also included in the QR code for the TOTP app.

After generating a key, a QR code will be displayed, which can be used with most OTP apps such as FreeOTP. The user then needs to verify the current user password (unless logged in as root), as well as the ability to correctly use the TOTP key, by typing the current OTP value into the Verification Code field and pressing the Apply button.

TOTP

screenshot/pve-gui-tfa-add-totp.png

There is no server setup required. Simply install a TOTP app on your smartphone (for example, FreeOTP) and use the Proxmox Backup Server web-interface to add a TOTP factor.

WebAuthn

For WebAuthn to work, you need to have two things:

  • A trusted HTTPS certificate (for example, by using Let’s Encrypt). While it probably works with an untrusted certificate, some browsers may warn or refuse WebAuthn operations if it is not trusted.

  • Setup the WebAuthn configuration (see Datacenter → Options → WebAuthn Settings in the Proxmox VE web interface). This can be auto-filled in most setups.

Once you have fulfilled both of these requirements, you can add a WebAuthn configuration in the Two Factor panel under Datacenter → Permissions → Two Factor.

Recovery Keys

screenshot/pve-gui-tfa-add-recovery-keys.png

Recovery key codes do not need any preparation; you can simply create a set of recovery keys in the Two Factor panel under Datacenter → Permissions → Two Factor.

Note There can only be one set of single-use recovery keys per user at any time.

Server Side Webauthn Configuration

screenshot/gui-datacenter-webauthn-edit.png

To allow users to use WebAuthn authentication, it is necessaary to use a valid domain with a valid SSL certificate, otherwise some browsers may warn or refuse to authenticate altogether.

Note Changing the WebAuthn configuration may render all existing WebAuthn registrations unusable!

This is done via /etc/pve/datacenter.cfg. For instance:

webauthn:
rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com

Server Side U2F Configuration

Note It is recommended to use WebAuthn instead.

To allow users to use U2F authentication, it may be necessary to use a valid domain with a valid SSL certificate, otherwise, some browsers may print a warning or reject U2F usage altogether. Initially, an AppId
[AppId https://developers.yubico.com/U2F/App_ID.html]
needs to be configured.

Note Changing the AppId will render all existing U2F registrations unusable!

This is done via /etc/pve/datacenter.cfg. For instance:

u2f: appid=https://mypve.example.com:8006

For a single node, the AppId can simply be the address of the web-interface, exactly as it is used in the browser, including the https:// and the port, as shown above. Please note that some browsers may be more strict than others when matching AppIds.

When using multiple nodes, it is best to have a separate https server providing an appid.json
[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
file, as it seems to be compatible with most browsers. If all nodes use subdomains of the same top level domain, it may be enough to use the TLD as AppId. It should however be noted that some browsers may not accept this.

Note A bad AppId will usually produce an error, but we have encountered situations when this does not happen, particularly when using a top level domain AppId for a node that is accessed via a subdomain in Chromium. For this reason it is recommended to test the configuration with multiple browsers, as changing the AppId later will render existing U2F registrations unusable.

Activating U2F as a User

To enable U2F authentication, open the TFA window’s U2F tab, type in the current password (unless logged in as root), and press the Register button. If the server is set up correctly and the browser accepts the server’s provided AppId, a message will appear prompting the user to press the button on the U2F device (if it is a YubiKey, the button light should be toggling on and off steadily, roughly twice per second).

Firefox users may need to enable security.webauth.u2f via about:config before they can use a U2F token.

Permission Management

In order for a user to perform an action (such as listing, modifying or deleting parts of a VM’s configuration), the user needs to have the appropriate permissions.

Proxmox VE uses a role and path based permission management system. An entry in the permissions table allows a user, group or token to take on a specific role when accessing an object or path. This means that such an access rule can be represented as a triple of (path, user, role), (path, group, role) or (path, token, role), with the role containing a set of allowed actions, and the path representing the target of these actions.

Roles

A role is simply a list of privileges. Proxmox VE comes with a number of predefined roles, which satisfy most requirements.

  • Administrator: has full privileges

  • NoAccess: has no privileges (used to forbid access)

  • PVEAdmin: can do most tasks, but has no rights to modify system settings (Sys.PowerMgmt, Sys.Modify, Realm.Allocate)

  • PVEAuditor: has read only access

  • PVEDatastoreAdmin: create and allocate backup space and templates

  • PVEDatastoreUser: allocate backup space and view storage

  • PVEPoolAdmin: allocate pools

  • PVESysAdmin: User ACLs, audit, system console and system logs

  • PVETemplateUser: view and clone templates

  • PVEUserAdmin: manage users

  • PVEVMAdmin: fully administer VMs

  • PVEVMUser: view, backup, configure CD-ROM, VM console, VM power management

You can see the whole set of predefined roles in the GUI.

You can add new roles via the GUI or the command line.

screenshot/gui-datacenter-role-add.png

From the GUI, navigate to the Permissions → Roles tab from Datacenter and click on the Create button. There you can set a role name and select any desired privileges from the Privileges drop-down menu.

To add a role through the command line, you can use the pveum CLI tool, for example:

pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"

Privileges

A privilege is the right to perform a specific action. To simplify management, lists of privileges are grouped into roles, which can then be used in the permission table. Note that privileges cannot be directly assigned to users and paths without being part of a role.

We currently support the following privileges:

Node / System related privileges
  • Permissions.Modify: modify access permissions

  • Sys.PowerMgmt: node power management (start, stop, reset, shutdown, …)

  • Sys.Console: console access to node

  • Sys.Syslog: view syslog

  • Sys.Audit: view node status/config, Corosync cluster config, and HA config

  • Sys.Modify: create/modify/remove node network parameters

  • Group.Allocate: create/modify/remove groups

  • Pool.Allocate: create/modify/remove a pool

  • Pool.Audit: view a pool

  • Realm.Allocate: create/modify/remove authentication realms

  • Realm.AllocateUser: assign user to a realm

  • User.Modify: create/modify/remove user access and details.

Virtual machine related privileges
  • VM.Allocate: create/remove VM on a server

  • VM.Migrate: migrate VM to alternate server on cluster

  • VM.PowerMgmt: power management (start, stop, reset, shutdown, …)

  • VM.Console: console access to VM

  • VM.Monitor: access to VM monitor (kvm)

  • VM.Backup: backup/restore VMs

  • VM.Audit: view VM config

  • VM.Clone: clone/copy a VM

  • VM.Config.Disk: add/modify/remove disks

  • VM.Config.CDROM: eject/change CD-ROM

  • VM.Config.CPU: modify CPU settings

  • VM.Config.Memory: modify memory settings

  • VM.Config.Network: add/modify/remove network devices

  • VM.Config.HWType: modify emulated hardware types

  • VM.Config.Options: modify any other VM configuration

  • VM.Snapshot: create/delete VM snapshots

Storage related privileges
  • Datastore.Allocate: create/modify/remove a datastore and delete volumes

  • Datastore.AllocateSpace: allocate space on a datastore

  • Datastore.AllocateTemplate: allocate/upload templates and ISO images

  • Datastore.Audit: view/browse a datastore

Objects and Paths

Access permissions are assigned to objects, such as virtual machines, storages or resource pools. We use file system like paths to address these objects. These paths form a natural tree, and permissions of higher levels (shorter paths) can optionally be propagated down within this hierarchy.

Paths can be templated. When an API call requires permissions on a templated path, the path may contain references to parameters of the API call. These references are specified in curly braces. Some parameters are implicitly taken from the API call’s URI. For instance, the permission path /nodes/{node} when calling /nodes/mynode/status requires permissions on /nodes/mynode, while the path {path} in a PUT request to /access/acl refers to the method’s path parameter.

Some examples are:

  • /nodes/{node}: Access to Proxmox VE server machines

  • /vms: Covers all VMs

  • /vms/{vmid}: Access to specific VMs

  • /storage/{storeid}: Access to a specific storage

  • /pool/{poolname}: Access to resources contained in a specific pool

  • /access/groups: Group administration

  • /access/realms/{realmid}: Administrative access to realms

Inheritance

As mentioned earlier, object paths form a file system like tree, and permissions can be inherited by objects down that tree (the propagate flag is set by default). We use the following inheritance rules:

  • Permissions for individual users always replace group permissions.

  • Permissions for groups apply when the user is member of that group.

  • Permissions on deeper levels replace those inherited from an upper level.

Additionally, privilege separated tokens can never have permissions on any given path that their associated user does not have.

Pools

Pools can be used to group a set of virtual machines and datastores. You can then simply set permissions on pools (/pool/{poolid}), which are inherited by all pool members. This is a great way to simplify access control.

Which Permissions Do I Need?

The required API permissions are documented for each individual method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/.

The permissions are specified as a list, which can be interpreted as a tree of logic and access-check functions:

["and", <subtests>...] and ["or", <subtests>...]

Each(and) or any(or) further element in the current list has to be true.

["perm", <path>, [ <privileges>... ], <options>...]

The path is a templated parameter (see Objects and Paths). All (or, if the any option is used, any) of the listed privileges must be allowed on the specified path. If a require-param option is specified, then its specified parameter is required even if the API call’s schema otherwise lists it as being optional.

["userid-group", [ <privileges>... ], <options>...]

The caller must have any of the listed privileges on /access/groups. In addition, there are two possible checks, depending on whether the groups_param option is set:

  • groups_param is set: The API call has a non-optional groups parameter and the caller must have any of the listed privileges on all of the listed groups.

  • groups_param is not set: The user passed via the userid parameter must exist and be part of a group on which the caller has any of the listed privileges (via the /access/groups/<group> path).

["userid-param", "self"]

The value provided for the API call’s userid parameter must refer to the user performing the action (usually in conjunction with or, to allow users to perform an action on themselves, even if they don’t have elevated privileges).

["userid-param", "Realm.AllocateUser"]

The user needs Realm.AllocateUser access to /access/realm/<realm>, with <realm> referring to the realm of the user passed via the userid parameter. Note that the user does not need to exist in order to be associated with a realm, since user IDs are passed in the form of <username>@<realm>.

["perm-modify", <path>]

The path is a templated parameter (see Objects and Paths). The user needs either the Permissions.Modify privilege or, depending on the path, the following privileges as a possible substitute:

  • /storage/...: additionally requires 'Datastore.Allocate`

  • /vms/...: additionally requires 'VM.Allocate`

  • /pool/...: additionally requires 'Pool.Allocate`

    If the path is empty, Permission.Modify on /access is required.

Command Line Tool

Most users will simply use the GUI to manage users. But there is also a fully featured command line tool called pveum (short for “Proxmox VE User Manager”). Please note that all Proxmox VE command line tools are wrappers around the API, so you can also access those functions through the REST API.

Here are some simple usage examples. To show help, type:

pveum

or (to show detailed help about a specific command)

pveum help user add

Create a new user:

pveum user add testuser@pve -comment "Just a test"

Set or change the password (not all realms support this):

pveum passwd testuser@pve

Disable a user:

pveum user modify testuser@pve -enable 0

Create a new group:

pveum group add testgroup

Create a new role:

pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"

Real World Examples

Administrator Group

It is possible that an administrator would want to create a group of users with full administrator rights (without using the root account).

To do this, first define the group:

pveum group add admin -comment "System Administrators"

Then assign the role:

pveum acl modify / -group admin -role Administrator

Finally, you can add users to the new admin group:

pveum user modify testuser@pve -group admin

Auditors

You can give read only access to users by assigning the PVEAuditor role to users or groups.

Example 1: Allow user joe@pve to see everything

pveum acl modify / -user joe@pve -role PVEAuditor

Example 2: Allow user joe@pve to see all virtual machines

pveum acl modify /vms -user joe@pve -role PVEAuditor

Delegate User Management

If you want to delegate user management to user joe@pve, you can do that with:

pveum acl modify /access -user joe@pve -role PVEUserAdmin

User joe@pve can now add and remove users, and change other user attributes, such as passwords. This is a very powerful role, and you most likely want to limit it to selected realms and groups. The following example allows joe@pve to modify users within the realm pve, if they are members of group customers:

pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
Note The user is able to add other users, but only if they are members of the group customers and within the realm pve.

Limited API Token for Monitoring

Permissions on API tokens are always a subset of those of their corresponding user, meaning that an API token can’t be used to carry out a task that the backing user has no permission to do. This section will demonstrate how you can use an API token with separate privileges, to limit the token owner’s permissions further.

Give the user joe@pve the role PVEVMAdmin on all VMs:

pveum acl modify /vms -user joe@pve -role PVEVMAdmin

Add a new API token with separate privileges, which is only allowed to view VM information (for example, for monitoring purposes):

pveum user token add joe@pve monitoring -privsep 1
pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor

Verify the permissions of the user and token:

pveum user permissions joe@pve
pveum user token permissions joe@pve monitoring

Resource Pools

An enterprise is usually structured into several smaller departments, and it is common that you want to assign resources and delegate management tasks to each of these. Let’s assume that you want to set up a pool for a software development department. First, create a group:

pveum group add developers -comment "Our software developers"

Now we create a new user which is a member of that group:

pveum user add developer1@pve -group developers -password
Note The "-password" parameter will prompt you for a password

Then we create a resource pool for our development department to use:

pveum pool add dev-pool --comment "IT development pool"

Finally, we can assign permissions to that pool:

pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin

Our software developers can now administer the resources assigned to that pool.