NAME

pveum - Proxmox VE User Manager

SYNOPSIS

pveum <COMMAND> [ARGS] [OPTIONS]

pveum acl delete <path> --roles <string> [OPTIONS]

Update Access Control List (add or remove permissions).

<path>: <string>

--groups <string>

--propagate <boolean> (default = 1)

--roles <string>

--tokens <string>

--users <string>

pveum acl list [FORMAT_OPTIONS]

Get Access Control List (ACLs).

pveum acl modify <path> --roles <string> [OPTIONS]

Update Access Control List (add or remove permissions).

<path>: <string>

--groups <string>

--propagate <boolean> (default = 1)

--roles <string>

--tokens <string>

--users <string>

pveum acldel

An alias for pveum acl delete.

pveum aclmod

An alias for pveum acl modify.

pveum group add <groupid> [OPTIONS]

Create new group.

<groupid>: <string>

--comment <string>

pveum group delete <groupid>

Delete group.

<groupid>: <string>

pveum group list [FORMAT_OPTIONS]

Group index.

pveum group modify <groupid> [OPTIONS]

Update group data.

<groupid>: <string>

--comment <string>

pveum groupadd

An alias for pveum group add.

pveum groupdel

An alias for pveum group delete.

pveum groupmod

An alias for pveum group modify.

pveum help [OPTIONS]

Get help about specified command.

--extra-args <array>

--verbose <boolean>

pveum passwd <userid>

Change user password.

<userid>: <string>

pveum pool add <poolid> [OPTIONS]

Create new pool.

<poolid>: <string>

--comment <string>

pveum pool delete <poolid>

Delete pool.

<poolid>: <string>

pveum pool list [FORMAT_OPTIONS]

Pool index.

pveum pool modify <poolid> [OPTIONS]

Update pool data.

<poolid>: <string>

--comment <string>

--delete <boolean>

--storage <string>

--vms <string>

pveum realm add <realm> --type <string> [OPTIONS]

Add an authentication server.

<realm>: <string>

--acr-values <string>

--autocreate <boolean> (default = 0)

--base_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--bind_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--capath <string> (default = /etc/ssl/certs)

--case-sensitive <boolean> (default = 1)

--cert <string>

--certkey <string>

--client-id <string>

--client-key <string>

--comment <string>

--default <boolean>

--domain \S+

--filter <string>

--group_classes <string> (default = groupOfNames, group, univentionGroup, ipausergroup)

--group_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--group_filter <string>

--group_name_attr <string>

--issuer-url <string>

--mode <ldap | ldap+starttls | ldaps> (default = ldap)

--password <string>

--port <integer> (1 - 65535)

--prompt (?:none|login|consent|select_account|\S+)

--scopes <string> (default = email profile)

--secure <boolean>

--server1 <string>

--server2 <string>

--sslversion <tlsv1 | tlsv1_1 | tlsv1_2 | tlsv1_3>

--sync-defaults-options [enable-new=<1|0>] [,full=<1|0>] [,purge=<1|0>] [,remove-vanished=([acl];[properties];[entry])|none] [,scope=<users|groups|both>]

--sync_attributes \w+=[^,]+(,\s*\w+=[^,]+)*

--tfa type=<TFATYPE> [,digits=<COUNT>] [,id=<ID>] [,key=<KEY>] [,step=<SECONDS>] [,url=<URL>]

--type <ad | ldap | openid | pam | pve>

--user_attr \S{2,}

--user_classes <string> (default = inetorgperson, posixaccount, person, user)

--username-claim <string>

--verify <boolean> (default = 0)

pveum realm delete <realm>

Delete an authentication server.

<realm>: <string>

pveum realm list [FORMAT_OPTIONS]

Authentication domain index.

pveum realm modify <realm> [OPTIONS]

Update authentication server settings.

<realm>: <string>

--acr-values <string>

--autocreate <boolean> (default = 0)

--base_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--bind_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--capath <string> (default = /etc/ssl/certs)

--case-sensitive <boolean> (default = 1)

--cert <string>

--certkey <string>

--client-id <string>

--client-key <string>

--comment <string>

--default <boolean>

--delete <string>

--digest <string>

--domain \S+

--filter <string>

--group_classes <string> (default = groupOfNames, group, univentionGroup, ipausergroup)

--group_dn (?^:\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#]))(,\s*\w+=(?^:("[^"]+"|[^ ,+"/<>;=#][^,+"/<>;=]*[^ ,+"/<>;=]|[^ ,+"/<>;=#])))*)

--group_filter <string>

--group_name_attr <string>

--issuer-url <string>

--mode <ldap | ldap+starttls | ldaps> (default = ldap)

--password <string>

--port <integer> (1 - 65535)

--prompt (?:none|login|consent|select_account|\S+)

--scopes <string> (default = email profile)

--secure <boolean>

--server1 <string>

--server2 <string>

--sslversion <tlsv1 | tlsv1_1 | tlsv1_2 | tlsv1_3>

--sync-defaults-options [enable-new=<1|0>] [,full=<1|0>] [,purge=<1|0>] [,remove-vanished=([acl];[properties];[entry])|none] [,scope=<users|groups|both>]

--sync_attributes \w+=[^,]+(,\s*\w+=[^,]+)*

--tfa type=<TFATYPE> [,digits=<COUNT>] [,id=<ID>] [,key=<KEY>] [,step=<SECONDS>] [,url=<URL>]

--user_attr \S{2,}

--user_classes <string> (default = inetorgperson, posixaccount, person, user)

--verify <boolean> (default = 0)

pveum realm sync <realm> [OPTIONS]

Syncs users and/or groups from the configured LDAP to user.cfg. NOTE: Synced groups will have the name name-$realm, so make sure those groups do not exist to prevent overwriting.

<realm>: <string>

--dry-run <boolean> (default = 0)

--enable-new <boolean> (default = 1)

--full <boolean>

--purge <boolean>

--remove-vanished ([acl];[properties];[entry])|none (default = none)

--scope <both | groups | users>

pveum role add <roleid> [OPTIONS]

Create new role.

<roleid>: <string>

--privs <string>

pveum role delete <roleid>

Delete role.

<roleid>: <string>

pveum role list [FORMAT_OPTIONS]

Role index.

pveum role modify <roleid> [OPTIONS]

Update an existing role.

<roleid>: <string>

--append <boolean>

--privs <string>

pveum roleadd

An alias for pveum role add.

pveum roledel

An alias for pveum role delete.

pveum rolemod

An alias for pveum role modify.

pveum ticket <username> [OPTIONS]

Create or verify authentication ticket.

<username>: <string>

--new-format <boolean> (default = 0)

--otp <string>

--path <string>

--privs <string>

--realm <string>

--tfa-challenge <string>

pveum user add <userid> [OPTIONS]

Create new user.

<userid>: <string>

--comment <string>

--email <string>

--enable <boolean> (default = 1)

--expire <integer> (0 - N)

--firstname <string>

--groups <string>

--keys <string>

--lastname <string>

--password <string>

pveum user delete <userid>

Delete user.

<userid>: <string>

pveum user list [OPTIONS] [FORMAT_OPTIONS]

User index.

--enabled <boolean>

--full <boolean> (default = 0)

pveum user modify <userid> [OPTIONS]

Update user configuration.

<userid>: <string>

--append <boolean>

--comment <string>

--email <string>

--enable <boolean> (default = 1)

--expire <integer> (0 - N)

--firstname <string>

--groups <string>

--keys <string>

--lastname <string>

pveum user permissions [<userid>] [OPTIONS] [FORMAT_OPTIONS]

Retrieve effective permissions of given user/token.

<userid>: (?^:^(?^:[^\s:/]+)\@(?^:[A-Za-z][A-Za-z0-9\.\-_]+)(?:!(?^:[A-Za-z][A-Za-z0-9\.\-_]+))?$)

--path <string>

pveum user tfa delete <userid> [OPTIONS]

Delete TFA entries from a user.

<userid>: <string>

--id <string>

pveum user token add <userid> <tokenid> [OPTIONS] [FORMAT_OPTIONS]

Generate a new API token for a specific user. NOTE: returns API token value, which needs to be stored as it cannot be retrieved afterwards!

<userid>: <string>

<tokenid>: (?^:[A-Za-z][A-Za-z0-9\.\-_]+)

--comment <string>

--expire <integer> (0 - N) (default = same as user)

--privsep <boolean> (default = 1)

pveum user token list <userid> [FORMAT_OPTIONS]

Get user API tokens.

<userid>: <string>

pveum user token modify <userid> <tokenid> [OPTIONS] [FORMAT_OPTIONS]

Update API token for a specific user.

<userid>: <string>

<tokenid>: (?^:[A-Za-z][A-Za-z0-9\.\-_]+)

--comment <string>

--expire <integer> (0 - N) (default = same as user)

--privsep <boolean> (default = 1)

pveum user token permissions <userid> <tokenid> [OPTIONS] [FORMAT_OPTIONS]

Retrieve effective permissions of given token.

<userid>: <string>

<tokenid>: (?^:[A-Za-z][A-Za-z0-9\.\-_]+)

--path <string>

pveum user token remove <userid> <tokenid> [FORMAT_OPTIONS]

Remove API token for a specific user.

<userid>: <string>

<tokenid>: (?^:[A-Za-z][A-Za-z0-9\.\-_]+)

pveum useradd

An alias for pveum user add.

pveum userdel

An alias for pveum user delete.

pveum usermod

An alias for pveum user modify.

DESCRIPTION

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 (man pveum(1)) 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:

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:

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

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

Proxmox VE Authentication Server

LDAP

Microsoft Active Directory (AD)

OpenID Connect

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

pveum realm sync <realm>

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

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

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.

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

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

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.

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

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

pveum group add admin -comment "System Administrators"

pveum acl modify / -group admin -role Administrator

pveum user modify testuser@pve -group admin

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

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

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

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

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

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

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

pveum group add developers -comment "Our software developers"

pveum user add developer1@pve -group developers -password

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

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

COPYRIGHT AND DISCLAIMER

Copyright © 2007-2022 Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/

AUTHOR

Proxmox Server Solutions Gmbh
www.proxmox.com

NOTES

1.

ldap.com

2.

RFC2253

3.

Time-based One-Time Password

4.

Web Authentication

5.

YubiKey OTP

6.

YubiCloud

7.

host your own verification server

8.

FreeOTP

9.

Let’s Encrypt

10.

AppId https://developers.yubico.com/U2F/App_ID.html

11.

Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html