NAME

pveum - Proxmox VE 用户管理器

SYNOPSIS

pveum <COMMAND> [ARGS] [OPTIONS]

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

更新访问控制列表（添加或移除权限）。

<path>: <string>

访问控制路径

--groups <string>

组列表。

--propagate <boolean> (default = 1)

允许传播（继承）权限。

--roles <string>

角色列表。

--tokens <string>

API token 列表。

--users <string>

用户列表。

pveum acl list [FORMAT_OPTIONS]

获取访问控制列表（ACL）。

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

更新访问控制列表（添加或移除权限）。

<path>: <string>

访问控制路径

--groups <string>

组列表。

--propagate <boolean> (default = 1)

允许传播（继承）权限。

--roles <string>

角色列表。

--tokens <string>

API token 列表。

--users <string>

用户列表。

pveum acldel

pveum acl delete 的别名。

pveum aclmod

pveum acl modify 的别名。

pveum group add <groupid> [OPTIONS]

创建新组。

<groupid>: <string>

无可用描述

--comment <string>

无可用描述

pveum group delete <groupid>

删除组。

<groupid>: <string>

无可用描述

pveum group list [FORMAT_OPTIONS]

组索引。

pveum group modify <groupid> [OPTIONS]

更新组数据。

<groupid>: <string>

无可用描述

--comment <string>

无可用描述

pveum groupadd

pveum group add 的别名。

pveum groupdel

pveum group delete 的别名。

pveum groupmod

pveum group modify 的别名。

pveum help [OPTIONS]

获取指定命令的帮助。

--extra-args <array>

显示特定命令的帮助

--verbose <boolean>

详细输出格式。

pveum passwd <userid> [OPTIONS]

更改用户密码。

<userid>: <string>

完整用户 ID，格式为 name@realm。

--confirmation-password <string>

执行此次更改的用户的当前密码。

pveum pool add <poolid> [OPTIONS]

创建新资源池。

<poolid>: <string>

无可用描述

--comment <string>

无可用描述

pveum pool delete <poolid>

删除资源池。

<poolid>: <string>

无可用描述

pveum pool list [OPTIONS] [FORMAT_OPTIONS]

列出资源池或获取资源池配置。

--poolid <string>

无可用描述

--type <lxc | qemu | storage>

无可用描述

Note 需要选项：poolid

pveum pool modify <poolid> [OPTIONS]

更新资源池。

<poolid>: <string>

无可用描述

--allow-move <boolean> (default = 0)

允许添加已在其他资源池中的客户机。该客户机会从当前资源池中移除，并添加到此资源池。

--comment <string>

无可用描述

--delete <boolean> (default = 0)

移除传入的 VMID 和/或存储 ID，而不是添加它们。

--storage <string>

要从此资源池添加或移除的存储 ID 列表。

--vms <string>

要从此资源池添加或移除的客户机 VMID 列表。

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

添加认证服务器。

<realm>: <string>

认证域 ID

--acr-values ^[^\x00-\x1F\x7F <>#"]*$

指定请求 Authorization Server 在 Auth Request 中使用的 Authentication Context Class Reference 值。

--autocreate <boolean> (default = 0)

如果用户不存在，则自动创建用户。

--base_dn <string>

LDAP 基础域名

--bind_dn <string>

LDAP 绑定域名

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

CA 证书存储路径

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

用户名区分大小写

--cert <string>

客户端证书路径

--certkey <string>

客户端证书密钥路径

--check-connection <boolean> (default = 0)

检查到服务器的 bind 连接。

--client-id <string>

OpenID Client ID

--client-key <string>

OpenID Client Key

--comment <string>

描述。

--default <boolean>

将其用作默认 realm

--domain \S+

AD 域名

--filter <string>

用于用户同步的 LDAP 过滤器。

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

组的 objectclasses。

--group_dn <string>

用于组同步的 LDAP 基础域名。如果未设置，将使用 base_dn。

--group_filter <string>

用于组同步的 LDAP 过滤器。

--group_name_attr <string>

表示组名的 LDAP 属性。如果未设置或未找到，将使用 DN 的第一个值作为名称。

--groups-autocreate <boolean> (default = 0)

如果组不存在，则自动创建组。

--groups-claim (?^:[A-Za-z0-9\.\-_]+)

用于获取组的 OpenID claim。

--groups-overwrite <boolean> (default = 0)

登录时会覆盖该用户的所有组。

--issuer-url <string>

OpenID Issuer URL

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

LDAP 协议模式。

--password <string>

LDAP bind 密码。将存储在 /etc/pve/priv/realm/<REALM>.pw。

--port <integer> (1 - 65535)

服务器端口。

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

指定 Authorization Server 是否提示 End-User 重新认证并同意授权。

--query-userinfo <boolean> (default = 1)

启用查询 userinfo 端点以获取 claim 值。

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

指定应授权并返回的 scopes（用户详情），例如 email 或 profile。

--secure <boolean>

使用安全的 LDAPS 协议。已弃用：请改用 mode。

--server1 <string>

服务器 IP 地址（或 DNS 名称）

--server2 <string>

备用服务器 IP 地址（或 DNS 名称）

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

LDAPS TLS/SSL 版本。不建议使用低于 1.2 的版本！

--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+=[^,]+)*

逗号分隔的 key=value 对列表，用于指定哪些 LDAP 属性映射到哪些 PVE 用户字段。例如，要将 LDAP 属性 mail 映射到 PVE 的 email，请写作 email=mail。默认情况下，每个 PVE 用户字段都由同名 LDAP 属性表示。

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

使用双因素认证。

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

Realm 类型。

--user_attr \S{2,}

LDAP 用户属性名

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

用户的 objectclasses。

--username-claim <string>

用于生成唯一用户名的 OpenID claim。

--verify <boolean> (default = 0)

验证服务器的 SSL 证书

pveum realm delete <realm>

删除认证服务器。

<realm>: <string>

认证域 ID

pveum realm list [FORMAT_OPTIONS]

认证域索引。

pveum realm modify <realm> [OPTIONS]

更新认证服务器设置。

<realm>: <string>

认证域 ID

--acr-values ^[^\x00-\x1F\x7F <>#"]*$

指定请求 Authorization Server 在 Auth Request 中使用的 Authentication Context Class Reference 值。

--autocreate <boolean> (default = 0)

如果用户不存在，则自动创建用户。

--base_dn <string>

LDAP 基础域名

--bind_dn <string>

LDAP 绑定域名

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

CA 证书存储路径

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

用户名区分大小写

--cert <string>

客户端证书路径

--certkey <string>

客户端证书密钥路径

--check-connection <boolean> (default = 0)

检查到服务器的 bind 连接。

--client-id <string>

OpenID Client ID

--client-key <string>

OpenID Client Key

--comment <string>

描述。

--default <boolean>

将其用作默认 realm

--delete <string>

要删除的设置列表。

--digest <string>

如果当前配置文件具有不同 digest，则阻止更改。可用于防止并发修改。

--domain \S+

AD 域名

--filter <string>

用于用户同步的 LDAP 过滤器。

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

组的 objectclasses。

--group_dn <string>

用于组同步的 LDAP 基础域名。如果未设置，将使用 base_dn。

--group_filter <string>

用于组同步的 LDAP 过滤器。

--group_name_attr <string>

表示组名的 LDAP 属性。如果未设置或未找到，将使用 DN 的第一个值作为名称。

--groups-autocreate <boolean> (default = 0)

如果组不存在，则自动创建组。

--groups-claim (?^:[A-Za-z0-9\.\-_]+)

用于获取组的 OpenID claim。

--groups-overwrite <boolean> (default = 0)

登录时会覆盖该用户的所有组。

--issuer-url <string>

OpenID Issuer URL

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

LDAP 协议模式。

--password <string>

LDAP bind 密码。将存储在 /etc/pve/priv/realm/<REALM>.pw。

--port <integer> (1 - 65535)

服务器端口。

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

指定 Authorization Server 是否提示 End-User 重新认证并同意授权。

--query-userinfo <boolean> (default = 1)

启用查询 userinfo 端点以获取 claim 值。

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

指定应授权并返回的 scopes（用户详情），例如 email 或 profile。

--secure <boolean>

使用安全的 LDAPS 协议。已弃用：请改用 mode。

--server1 <string>

服务器 IP 地址（或 DNS 名称）

--server2 <string>

备用服务器 IP 地址（或 DNS 名称）

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

LDAPS TLS/SSL 版本。不建议使用低于 1.2 的版本！

--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+=[^,]+)*

逗号分隔的 key=value 对列表，用于指定哪些 LDAP 属性映射到哪些 PVE 用户字段。例如，要将 LDAP 属性 mail 映射到 PVE 的 email，请写作 email=mail。默认情况下，每个 PVE 用户字段都由同名 LDAP 属性表示。

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

使用双因素认证。

--user_attr \S{2,}

LDAP 用户属性名

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

用户的 objectclasses。

--verify <boolean> (default = 0)

验证服务器的 SSL 证书

pveum realm sync <realm> [OPTIONS]

将配置的 LDAP 中的用户和/或组同步到 user.cfg。NOTE: 同步后的组名为 name-$realm，请确保这些组不存在，以防被覆盖。

<realm>: <string>

认证域 ID

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

如果设置，则不写入任何内容。

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

立即启用新同步的用户。

--full <boolean>

已弃用：请改用 remove-vanished。如果设置，则使用 LDAP Directory 作为事实来源，删除同步结果中未返回的用户或组，并移除已同步用户的所有本地修改属性。如果未设置，则仅同步已同步数据中存在的信息，不删除或修改其他任何内容。

--purge <boolean>

已弃用：请改用 remove-vanished。移除同步过程中从配置中删除的用户或组的 ACL。

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

分号分隔的列表，指定同步期间对应对象或用户消失时要移除的内容。可用值如下：entry 表示当同步结果未返回用户/组时移除该用户/组。properties 表示移除现有用户/组中未出现在源端的已设置属性（包括自定义属性）。acl 表示当同步结果未返回用户/组时移除 acl。也可以使用 none（默认值）代替列表。

--scope <both | groups | users>

选择要同步的内容。

pveum role add <roleid> [OPTIONS]

创建新角色。

<roleid>: <string>

无可用描述

--privs <string>

无可用描述

pveum role delete <roleid>

删除角色。

<roleid>: <string>

无可用描述

pveum role list [FORMAT_OPTIONS]

角色索引。

pveum role modify <roleid> [OPTIONS]

更新现有角色。

<roleid>: <string>

无可用描述

--append <boolean>

无可用描述

Note 需要选项：privs
--privs <string>

无可用描述

pveum roleadd

pveum role add 的别名。

pveum roledel

pveum role delete 的别名。

pveum rolemod

pveum role modify 的别名。

pveum ticket <username> [OPTIONS]

创建或验证认证 ticket。

<username>: <string>

用户名

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

该参数现在会被忽略，并假定为 1。

--otp <string>

用于双因素认证的一次性密码。

--path <string>

验证 ticket，并检查用户是否在 path 上拥有 privs 访问权限

Note 需要选项：privs
--privs <string>

验证 ticket，并检查用户是否在 path 上拥有 privs 访问权限

Note 需要选项：path
--realm <string>

可以选择通过该参数传入 realm。通常 realm 会直接添加到用户名中，格式为 <username>@<realm>。

--tfa-challenge <string>

用户要响应的已签名 TFA challenge 字符串。

pveum user add <userid> [OPTIONS]

创建新用户。

<userid>: <string>

完整用户 ID，格式为 name@realm。

--comment <string>

无可用描述

--email <string>

无可用描述

--enable <boolean> (default = 1)

启用账户（默认）。可以将其设置为 0 以禁用账户

--expire <integer> (0 - N)

账户过期日期（自 epoch 起的秒数）。0 表示无过期日期。

--firstname <string>

无可用描述

--groups <string>

无可用描述

--keys [0-9a-zA-Z!=]{0,4096}

双因素认证密钥（yubico）。

--lastname <string>

无可用描述

--password <string>

初始密码。

pveum user delete <userid>

删除用户。

<userid>: <string>

完整用户 ID，格式为 name@realm。

pveum user list [OPTIONS] [FORMAT_OPTIONS]

用户索引。

--enabled <boolean>

按 enable 属性进行可选过滤。

--full <boolean> (default = 0)

包含组和 token 信息。

pveum user modify <userid> [OPTIONS]

更新用户配置。

<userid>: <string>

完整用户 ID，格式为 name@realm。

--append <boolean>

无可用描述

Note 需要选项：groups
--comment <string>

无可用描述

--email <string>

无可用描述

--enable <boolean> (default = 1)

启用账户（默认）。可以将其设置为 0 以禁用账户

--expire <integer> (0 - N)

账户过期日期（自 epoch 起的秒数）。0 表示无过期日期。

--firstname <string>

无可用描述

--groups <string>

无可用描述

--keys [0-9a-zA-Z!=]{0,4096}

双因素认证密钥（yubico）。

--lastname <string>

无可用描述

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

获取指定用户/token 的有效权限。

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

用户 ID 或完整 API token ID

--path <string>

只输出该特定路径，而不是整棵树。

pveum user tfa delete <userid> [OPTIONS]

删除用户的 TFA 条目。

<userid>: <string>

完整用户 ID，格式为 name@realm。

--id <string>

TFA ID；如果未提供，则删除所有 TFA 条目。

pveum user tfa list [<userid>]

列出 TFA 条目。

<userid>: <string>

完整用户 ID，格式为 name@realm。

pveum user tfa unlock <userid>

解锁用户的 TFA 认证。

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

为特定用户生成新的 API token。NOTE: 返回 API token 值；需要保存该值，因为之后无法再次取回！

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

用户专属 token 标识符。

--comment <string>

无可用描述

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

API token 过期日期（自 epoch 起的秒数）。0 表示无过期日期。

--privsep <boolean> (default = 1)

使用独立 ACL 限制 API token 权限（默认），或授予对应用户的完整权限。

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

移除特定用户的 API token。

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

用户专属 token 标识符。

pveum user token list <userid> [FORMAT_OPTIONS]

获取用户 API token。

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

更新特定用户的 API token。

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

用户专属 token 标识符。

--comment <string>

无可用描述

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

API token 过期日期（自 epoch 起的秒数）。0 表示无过期日期。

--privsep <boolean> (default = 1)

使用独立 ACL 限制 API token 权限（默认），或授予对应用户的完整权限。

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

获取指定 token 的有效权限。

<userid>: <string>

完整用户 ID，格式为 name@realm。

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

用户专属 token 标识符。

--path <string>

只输出该特定路径，而不是整棵树。

pveum user token remove

pveum user token delete 的别名。

pveum useradd

pveum user add 的别名。

pveum userdel

pveum user delete 的别名。

pveum usermod

pveum user modify 的别名。

DESCRIPTION

Proxmox VE 支持多个认证源，例如 Linux PAM、集成的 Proxmox VE 认证服务器、LDAP、 Microsoft Active Directory 和 OpenID Connect。

通过对所有对象（VM、存储、节点等）使用基于角色的用户和权限管理，可以定义细粒度访问控制。

用户

Proxmox VE 将用户属性存储在 /etc/pve/user.cfg 中。密码不存储在这里；用户会关联到下文描述的 认证域。因此，在内部通常以 <userid>@<realm> 的形式， 通过用户名和域来标识用户。

该文件中的每个用户条目都包含以下信息：

  • 名

  • 姓

  • 电子邮件地址

  • 组成员关系

  • 可选的过期日期

  • 关于该用户的注释或备注

  • 该用户是否启用或禁用

  • 可选的双因素认证密钥

Caution 当禁用或删除用户，或者设置的过期日期已在过去时，该用户将无法登录新会话或启动 新任务。该用户已经启动的所有任务（例如终端会话）都不会因这些事件而自动终止。

系统管理员

系统的 root 用户始终可以通过 Linux PAM 域登录，并且是不受限制的管理员。该用户不能删除， 但仍可更改其属性。系统邮件会发送到分配给该用户的电子邮件地址。

组

每个用户可以属于多个组。组是组织访问权限的首选方式。应始终向组授予权限，而不是向单个用户 授予权限。这样可以获得更易维护的访问控制列表。

API token

API token 允许其他系统、软件或 API 客户端以无状态方式访问 REST API 的大部分内容。 可以为单个用户生成 token，并为其授予独立权限和过期日期，以限制访问范围和持续时间。如果 API token 泄露，可以撤销它，而无需禁用用户本身。

API token 有两种基本类型：

  • Separated privileges：需要通过 ACL 显式授予 token 访问权限。其有效权限通过用户权限与 token 权限的交集计算得出。

  • Full privileges：token 权限与关联用户的权限完全相同。

Caution token 值只会在生成 token 时显示/返回一次。之后无法再通过 API 取回！

使用 API token 时，请在发起 API 请求时将 HTTP header Authorization 设置为显示的值， 格式为 PVEAPIToken=USER@REALM!TOKENID=UUID；也可以参考所用 API 客户端的文档。

资源池

screenshot/gui-datacenter-pool-window.png

资源池是一组虚拟机、容器和存储设备。在某些用户应受控访问特定资源集合的场景中，它非常适合 处理权限，因为可以将单个权限应用到一组元素，而不必逐个资源管理。资源池通常与组配合使用， 使组成员对一组机器和存储拥有权限。

认证域

由于 Proxmox VE 用户只是某些外部域中已有用户的对应项，因此必须在 /etc/pve/domains.cfg 中配置这些域。可用的域（认证方法）如下：

Linux PAM 标准认证

Linux PAM 是用于系统范围用户认证的框架。这些用户通过 adduser 等命令在主机系统上创建。 如果 Proxmox VE 主机系统中存在 PAM 用户，可以在 Proxmox VE 中添加对应条目，使这些用户能够通过其 系统用户名和密码登录。

Proxmox VE Authentication Server

这是一个类 Unix 的密码存储，会在 /etc/pve/priv/shadow.cfg 中存储哈希后的密码。密码使用 SHA-256 哈希算法处理。对于用户不需要访问 Proxmox VE 外部任何内容的小规模（甚至中等规模）安装， 这是最方便的域。在这种情况下，用户完全由 Proxmox VE 管理，并且可以通过 GUI 修改自己的密码。

LDAP

LDAP（Lightweight Directory Access Protocol）是一种开放、跨平台的协议，用于通过目录 服务进行认证。OpenLDAP 是流行的开源 LDAP 协议实现。

Microsoft Active Directory（AD）

Microsoft Active Directory（AD）是用于 Windows 域网络的目录服务，Proxmox VE 支持将其作为 认证域。它支持 LDAP 作为认证协议。

OpenID Connect

OpenID Connect 是构建在 OAuth 2.0 协议之上的身份层。它允许客户端基于外部授权服务器 执行的认证来验证用户身份。

Linux PAM 标准认证

由于 Linux PAM 对应主机系统用户，因此用户允许登录的每个节点上都必须存在系统用户。 用户使用其常规系统密码进行认证。该域默认添加，且无法移除。

通过 GUI 或等价的 /access/password API 端点修改密码时，只会应用到本地节点，而不是 集群范围。即使 Proxmox VE 采用多主设计，为不同节点使用不同密码仍可带来安全收益。

在可配置性方面，管理员可以选择要求来自该域的登录使用双因素认证，也可以将该域设置为默认 认证域。

Proxmox VE Authentication Server

Proxmox VE 认证服务器域是一个简单的类 Unix 密码存储。该域默认创建；与 Linux PAM 一样， 可用的配置项只有：要求该域用户使用双因素认证，以及将其设置为默认登录域。

与其他 Proxmox VE 域类型不同，这类用户完全通过 Proxmox VE 创建和认证，而不是向另一个系统认证。 因此，创建此类用户时必须为其设置密码。

LDAP

也可以使用外部 LDAP 服务器进行用户认证（例如 OpenLDAP）。在此域类型中，会在 Base Domain Name (base_dn) 下搜索用户，并使用 User Attribute Name (user_attr) 字段中指定的用户名属性。

可以配置服务器和可选备用服务器，并可通过 SSL 加密连接。此外，可以为目录和组配置过滤器。 过滤器允许进一步限制该域的范围。

例如，如果用户由以下 LDIF 数据集表示：

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

Base Domain Name 将是 ou=People,dc=ldap-test,dc=com，用户属性将是 uid。

如果 Proxmox VE 在查询和认证用户前需要先向 LDAP 服务器认证（bind），可以通过 /etc/pve/domains.cfg 中的 bind_dn 属性配置 bind domain name。其密码必须存储在 /etc/pve/priv/realm/<realmname>.pw 中（例如 /etc/pve/priv/realm/my-ldap.pw）。 该文件应只包含一行原始密码。

要验证证书，需要设置 capath。可以将其直接设置为 LDAP 服务器的 CA 证书，也可以设置为 包含所有受信任 CA 证书的系统路径（/etc/ssl/certs）。此外，还需要设置 verify 选项， 这也可以通过 Web 界面完成。

LDAP 服务器域的主要配置选项如下：

  • Realm (realm): Proxmox VE 用户的域标识符

  • Base Domain Name (base_dn): 搜索用户所在的目录

  • User Attribute Name (user_attr): 包含用户登录用户名的 LDAP 属性

  • Server (server1): 托管 LDAP 目录的服务器

  • Fallback Server (server2): 可选备用服务器地址，用于主服务器不可达时

  • Port (port): LDAP 服务器监听的端口

Note 要允许特定用户使用 LDAP 服务器认证，还必须从 Proxmox VE 服务器将其添加为该域的用户。 这可以通过 同步 自动完成。

Microsoft Active Directory（AD）

要将 Microsoft AD 设置为域，需要指定服务器地址和认证域。Active Directory 支持大多数与 LDAP 相同的属性，例如可选备用服务器、端口和 SSL 加密。此外，配置完成后，可以通过 同步 操作自动将用户添加到 Proxmox VE。

与 LDAP 一样，如果 Proxmox VE 在绑定到 AD 服务器前需要认证，必须配置 Bind User (bind_dn) 属性。对于 Microsoft AD，通常默认需要该属性。

Microsoft Active Directory 的主要配置设置如下：

  • Realm (realm): Proxmox VE 用户的域标识符

  • Domain (domain): 服务器的 AD 域

  • Server (server1): 服务器的 FQDN 或 IP 地址

  • Fallback Server (server2): 可选备用服务器地址，用于主服务器不可达时

  • Port (port): Microsoft AD 服务器监听的端口

Note Microsoft AD 通常以大小写不敏感方式检查用户名等值。要让 Proxmox VE 执行相同行为， 可以在 Web UI 中编辑该域，或使用 CLI 禁用默认的 case-sensitive 选项（将 ID 替换为 域 ID）： pveum realm modify ID --case-sensitive 0

同步基于 LDAP 的域

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

可以为基于 LDAP 的域（LDAP 和 Microsoft Active Directory）自动同步用户和组，而不必手动 将它们添加到 Proxmox VE。可以从 Web 界面 Authentication 面板的 Add/Edit 窗口访问同步选项， 也可以通过 pveum realm add/modify 命令访问。之后可以从 GUI 的 Authentication 面板 执行同步操作，或使用以下命令：

pveum realm sync <realm>

用户和组会同步到集群范围配置文件 /etc/pve/user.cfg。

属性到属性映射

如果同步响应包含用户属性，它们会同步到 user.cfg 中匹配的用户属性。例如：firstname 或 lastname。

如果属性名称与 Proxmox VE 属性不匹配，可以使用 sync_attributes 选项在配置中设置自定义 字段到字段映射。

如果某些内容消失，这些属性的处理方式可以通过同步选项控制，见下文。

同步配置

同步基于 LDAP 的域所需的配置选项，可以在 Add/Edit 窗口的 Sync Options 选项卡中找到。

配置选项如下：

  • Bind User (bind_dn): 指用于查询用户和组的 LDAP 账号。该账号需要能够访问所有目标 条目。如果设置了该项，搜索会通过绑定执行；否则搜索会匿名执行。该用户必须是完整的 LDAP 格式 distinguished name（DN），例如 cn=admin,dc=example,dc=com。

  • Groupname attr. (group_name_attr): 表示用户所属的组。只会同步符合 user.cfg 常规字符 限制的条目。为避免命名冲突，组同步时会在名称后附加 -$realm。请确保同步不会覆盖手动 创建的组。

  • User classes (user_classes): 与用户关联的对象类。

  • Group classes (group_classes): 与组关联的对象类。

  • E-Mail attribute: 如果基于 LDAP 的服务器指定了用户电子邮件地址，可以在此处设置关联 属性，将其包含在同步中。从命令行可通过 --sync_attributes 参数实现。

  • User Filter (filter): 用于定位特定用户的进一步过滤选项。

  • Group Filter (group_filter): 用于定位特定组的进一步过滤选项。

Note 过滤器允许创建一组额外匹配条件，以缩小同步范围。可用 LDAP 过滤器类型及其用法的信息 可在 ldap.com 查看。

同步选项

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

除上一节指定的选项外，还可以配置更多用于描述同步操作行为的选项。

这些选项可以在同步前作为参数设置，也可以通过域选项 sync-defaults-options 设置为默认值。

主要同步选项如下：

  • Scope (scope): 要同步的范围。可以是 users、groups 或 both。

  • Enable new (enable-new): 如果设置，新同步的用户会被启用并可登录。默认值为 true。

  • Remove Vanished (remove-vanished): 这是一个选项列表。启用后，当同步响应未返回相应 内容时，会决定是否移除它们。选项包括：

    • ACL (acl): 移除同步响应中未返回的用户和组的 ACL。它通常与 Entry 一起使用 最有意义。

    • Entry (entry): 当同步响应未返回条目（即用户和组）时移除这些条目。

    • Properties (properties): 当同步响应中的用户未包含某些属性时，移除条目的这些属性。 这包括所有属性，即使它们从未由同步设置。例外是 token 和 enable 标志，即使启用此选项， 它们也会保留。

  • Preview (dry-run): 不向配置写入任何数据。如果想查看哪些用户和组会同步到 user.cfg，这会很有用。

保留字符

某些字符是保留字符（参见 RFC2253），如果未正确转义， 就不能轻易用于 DN 中的属性值。

以下字符需要转义：

  • 开头或结尾的空格（ ）

  • 开头的井号 (#)

  • 逗号 (,)

  • 加号 (+)

  • 双引号 (")

  • 正斜杠 (/)

  • 尖括号 (<>)

  • 分号 (;)

  • 等号 (=)

要在 DN 中使用这类字符，请将属性值放入双引号中。例如，要以 CN（Common Name）为 Example, User 的用户进行绑定，请使用 CN="Example, User",OU=people,DC=example,DC=com 作为 bind_dn 的值。

这适用于 base_dn、bind_dn 和 group_dn 属性。

Note 带有冒号和正斜杠的用户无法同步，因为这些是用户名中的保留字符。

OpenID Connect

OpenID Connect 的主要配置选项如下：

  • Issuer URL (issuer-url): 授权服务器的 URL。Proxmox VE 使用 OpenID Connect Discovery 协议自动配置更多细节。

    虽然可以使用未加密的 http:// URL，但强烈建议使用加密的 https:// 连接。

  • Realm (realm): Proxmox VE 用户的域标识符

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

  • Client Key (client-key): 可选 OpenID Client Key。

  • Autocreate Users (autocreate): 如果用户不存在，则自动创建用户。虽然认证在 OpenID 服务器完成，但所有用户仍需要在 Proxmox VE 用户配置中有条目。可以手动添加，也可以使用 autocreate 选项自动添加新用户。

  • Username Claim (username-claim): 用于生成唯一用户名的 OpenID claim（subject、 username 或 email）。

  • Autocreate Groups (groups-autocreate): 创建 claim 中的所有组，而不是使用现有 PVE 组 （默认行为）。

  • Groups Claim (groups-claim): 用于从 ID token 或 userinfo endpoint 获取组的 OpenID claim。

  • Overwrite Groups (groups-overwrite): 覆盖分配给用户的所有组，而不是追加到现有组 （默认行为）。

用户名映射

OpenID Connect 规范定义了一个名为 subject 的唯一属性（OpenID 术语中称为 claim）。 默认情况下，我们使用该属性的值生成 Proxmox VE 用户名，方式是简单追加 @ 和域名： ${subject}@${realm}。

遗憾的是，大多数 OpenID 服务器会为 subject 使用随机字符串，例如 DGH76OKH34BNG3245SB，因此典型用户名会类似 DGH76OKH34BNG3245SB@yourrealm。 虽然它是唯一的，但这类随机字符串很难记忆，也几乎无法将其与真实用户关联起来。

username-claim 设置允许使用其他属性进行用户名映射。如果 OpenID Connect 服务器提供 username 属性并保证其唯一性，建议将其设置为 username。

另一个选项是使用 email，这也会生成便于人类阅读的用户名。同样，只有在服务器保证该属性 唯一时才应使用此设置。

组映射

在 OpenID 配置中指定 groups-claim 设置会启用组映射功能。groups-claim 中提供的数据 应是字符串列表，对应用户在 Proxmox VE 中应属于的组。为避免冲突，来自 OpenID claim 的组名会 附加 -<realm name> 后缀（例如，域 oidc 中的 OpenID 组名 my-openid-group，在 Proxmox VE 中的组名会是 my-openid-group-oidc）。

默认情况下，OpenID provider 报告但在 Proxmox VE 中不存在的任何组都会被忽略。如果希望 OpenID provider 报告的所有组都存在于 Proxmox VE 中，可以使用 groups-autocreate 选项在用户登录时 自动创建这些组。

默认情况下，组会追加到用户现有组中。某些场景下，可能希望使用 OpenID provider 提供的组 覆盖用户在 Proxmox VE 中已有的组。启用 groups-overwrite 设置后，会先从 Proxmox VE 中移除该用户的 所有组，再添加 OpenID provider 报告的组。

在某些情况下，OpenID 服务器可能发送包含 Proxmox VE 组 ID 无效字符的 groups claim。任何包含 Proxmox VE 组名不允许字符的组都不会被包含，并会向日志发送警告。

高级设置

  • Query userinfo endpoint (query-userinfo): 启用该选项后，OpenID Connect 认证器需要 查询 "userinfo" endpoint 以获取 claim 值。对于某些不支持 "userinfo" endpoint 的身份 提供方（例如 ADFS），禁用该选项会很有用。

示例

以下是使用 Google 创建 OpenID 域的示例。需要将 --client-id 和 --client-key 替换为 Google OpenID 设置中的值。

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

上述命令使用 --username-claim email，因此 Proxmox VE 端的用户名类似 example.user@google.com@myrealm1。

Keycloak (https://www.keycloak.org/) 是流行的开源 Identity and Access Management 工具，支持 OpenID Connect。在以下示例中，需要将 --issuer-url 和 --client-id 替换为 你的信息：

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

使用 --username-claim username 会在 Proxmox VE 端启用简单用户名，例如 example.user@myrealm2。

Warning 需要确保用户不允许自行编辑用户名设置（在 Keycloak 服务器上）。

双因素认证

双因素认证有两种使用方式：

可以由认证域强制要求，方式可以是 TOTP（Time-based One-Time Password）或 YubiKey OTP。在这种情况下，新创建用户需要立即添加其密钥，因为没有第二因素就无法登录。 对于 TOTP，只要用户能先登录，也可以稍后更改 TOTP。

或者，即使域没有强制要求，用户也可以稍后自行选择启用双因素认证。

可用的第二因素

可以设置多个第二因素，以避免因丢失智能手机或安全密钥而永久无法访问账号。

除域强制的 TOTP 和 YubiKey OTP 外，还可使用以下双因素认证方法：

  • 用户配置的 TOTP (Time-based One-Time Password). 它是由共享密钥和当前时间派生出的短代码，每 30 秒变化一次。

  • WebAuthn (Web Authentication). 它是一种通用认证标准。各种安全设备都实现了该标准，例如硬件密钥，或来自计算机/智能手机的 trusted platform module（TPM）。

  • 一次性 Recovery Keys。这是一组密钥，应打印出来并锁在安全位置，或以数字形式保存在电子 保险库中。每个密钥只能使用一次。即使所有其他第二因素丢失或损坏，它们也非常适合用于确保 你不会被锁定在账号之外。

在支持 WebAuthn 之前，用户可以设置 U2F。现有 U2F 因素仍可继续使用，但建议在服务器配置 WebAuthn 后切换到 WebAuthn。

认证域强制双因素认证

添加或编辑 Authentication Realm 时，可以通过 TFA 下拉框选择一种可用方法来完成此设置。 当域启用 TFA 后，它会成为强制要求，只有已配置 TFA 的用户才能登录。

当前有两种可用方法：

Time-based OATH (TOTP)

它使用标准 HMAC-SHA1 算法，将当前时间与用户配置的密钥一起 进行哈希处理。时间步长和密码长度参数均可配置。

用户可以配置多个密钥（用空格分隔），密钥可以用 Base32（RFC3548）或十六进制表示法指定。

Proxmox VE 提供密钥生成工具 (oathkeygen)，它会打印一个 Base32 表示法的随机密钥，可直接用于 各种 OTP 工具，例如 oathtool 命令行工具，或 Android 上的 Google Authenticator、 FreeOTP、andOTP 或类似应用。

YubiKey OTP

要通过 YubiKey 认证，必须配置 Yubico API ID、API KEY 和验证服务器 URL，用户也必须拥有 可用的 YubiKey。要从 YubiKey 获取 key ID，可以通过 USB 连接后触发一次 YubiKey，并将输入 密码的前 12 个字符复制到用户的 Key IDs 字段中。

关于如何使用 YubiCloud or host your own verification server， 请参考 YubiKey OTP 文档。

双因素认证限制与锁定

第二因素用于在用户密码泄露或被猜中时保护用户。不过，某些因素仍可能被暴力破解。因此， 当第二因素登录尝试失败次数过多时，用户会被锁定。

对于 TOTP，失败 8 次会禁用用户的 TOTP 因素。使用恢复密钥登录时会解锁它们。如果 TOTP 是唯一可用因素，则需要管理员干预，并强烈建议要求用户立即修改密码。

由于 FIDO2/Webauthn 和恢复密钥较不容易受到暴力攻击，因此限制更高（100 次尝试），但超过 限制后所有第二因素都会被阻止一小时。

管理员可以随时通过 UI 中的用户列表或命令行解锁用户的双因素认证：

 pveum user tfa unlock joe@pve

用户配置的 TOTP 认证

用户可以通过用户列表中的 TFA 按钮，选择启用 TOTP 或 WebAuthn 作为登录第二因素 （除非该域强制使用 YubiKey OTP）。

用户始终可以添加并使用一次性 Recovery Keys。

screenshot/gui-datacenter-two-factor.png

打开 TFA 窗口后，用户会看到用于设置 TOTP 认证的对话框。Secret 字段包含密钥，可通过 Randomize 按钮随机生成。可以添加可选的 Issuer Name，用于向 TOTP 应用提供该密钥 归属信息。大多数 TOTP 应用会同时显示 issuer name 和对应的 OTP 值。用户名也会包含在 TOTP 应用的二维码中。

生成密钥后，会显示一个二维码，可与 FreeOTP 等大多数 OTP 应用一起使用。然后，用户需要验证 当前用户密码（除非以 root 登录），并通过在 Verification Code 字段中输入当前 OTP 值并按 Apply 按钮，验证其能够正确使用 TOTP 密钥。

TOTP

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

不需要服务器端设置。只需在智能手机上安装 TOTP 应用（例如 FreeOTP），并使用 Proxmox VE Web 界面添加 TOTP 因素。

WebAuthn

要让 WebAuthn 工作，需要满足两个条件：

  • 受信任的 HTTPS 证书（例如使用 Let’s Encrypt）。 虽然使用不受信任证书也可能工作，但如果证书不受信任，某些浏览器可能会警告或拒绝 WebAuthn 操作。

  • 设置 WebAuthn 配置（参见 Proxmox VE Web 界面中的 Datacenter → Options → WebAuthn Settings）。在大多数设置中，这可以自动填充。

满足这两个要求后，可以在 Datacenter → Permissions → Two Factor 下的 Two Factor 面板中添加 WebAuthn 配置。

Recovery Keys

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

恢复密钥代码不需要任何准备；可以直接在 Datacenter → Permissions → Two Factor 下的 Two Factor 面板中创建一组恢复密钥。

Note 每个用户在任意时刻只能拥有一组一次性恢复密钥。

服务器端 Webauthn 配置

screenshot/gui-datacenter-webauthn-edit.png

要允许用户使用 WebAuthn 认证，必须使用带有效 SSL 证书的有效域名；否则某些浏览器可能警告 或完全拒绝认证。

Note 更改 WebAuthn 配置可能导致所有现有 WebAuthn 注册无法使用！

这通过 /etc/pve/datacenter.cfg 完成。例如：

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

服务器端 U2F 配置

Note 建议改用 WebAuthn。

要允许用户使用 U2F 认证，可能需要使用带有效 SSL 证书的有效域名；否则某些浏览器可能显示 警告，或完全拒绝使用 U2F。首先，需要配置 AppId
[AppId https://developers.yubico.com/U2F/App_ID.html]
 。

Note 更改 AppId 会导致所有现有 U2F 注册无法使用！

这通过 /etc/pve/datacenter.cfg 完成。例如：

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

对于单个节点，AppId 可以简单设置为 Web 界面的地址，完全按照浏览器中使用的形式，包括 https:// 和端口，如上所示。请注意，在匹配 AppIds 时，某些浏览器可能比其他浏览器更严格。

使用多个节点时，最好有一个单独的 https 服务器提供 appid.json
[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
 文件，因为这似乎与大多数浏览器兼容。如果所有节点都使用同一顶级域下的子域，则使用 TLD 作为 AppId 可能已经足够。但需要注意，某些浏览器可能不接受这种做法。

Note 错误的 AppId 通常会产生错误，但我们也遇到过不报错的情况，尤其是在 Chromium 中， 通过子域访问某个节点却为其使用顶级域 AppId 时。因此建议使用多个浏览器测试配置，因为之后 更改 AppId 会导致现有 U2F 注册无法使用。

用户启用 U2F

要启用 U2F 认证，请打开 TFA 窗口的 U2F 选项卡，输入当前密码（除非以 root 登录）， 然后按 Register 按钮。如果服务器设置正确，并且浏览器接受服务器提供的 AppId，会出现 提示用户按下 U2F 设备按钮的消息（如果是 YubiKey，按钮灯应稳定地亮灭切换，大约每秒两次）。

Firefox 用户可能需要先通过 about:config 启用 security.webauth.u2f，才能使用 U2F token。

权限管理

为了让用户执行某个操作（例如列出、修改或删除 VM 配置的部分内容），该用户需要具备相应权限。

Proxmox VE 使用基于角色和路径的权限管理系统。权限表中的条目允许用户、组或 token 在访问某个 object 或 path 时承担特定角色。这意味着此类访问规则可以表示为 (path, user, role)、(path, group, role) 或 (path, token, role) 三元组，其中角色 包含一组允许的动作，而路径表示这些动作的目标。

角色

角色本质上是一组权限列表。Proxmox VE 随附多个预定义角色，可满足大多数需求。

  • Administrator: 拥有全部权限

  • NoAccess: 没有任何权限（用于禁止访问）

  • PVEAdmin: 可以执行大多数任务，但无权修改系统设置 (Sys.PowerMgmt, Sys.Modify, Realm.Allocate) 或权限 (Permissions.Modify)

  • PVEAuditor: 拥有只读访问权限

  • PVEDatastoreAdmin: 创建并分配备份空间和模板

  • PVEDatastoreUser: 分配备份空间并查看存储

  • PVEMappingAdmin: 管理资源映射

  • PVEMappingUser: 查看和使用资源映射

  • PVEPoolAdmin: 分配池

  • PVEPoolUser: 查看池

  • PVESDNAdmin: 管理 SDN 配置

  • PVESDNUser: 访问 bridge/vnet

  • PVESysAdmin: 审计、系统控制台和系统日志

  • PVETemplateUser: 查看和克隆模板

  • PVEUserAdmin: 管理用户

  • PVEVMAdmin: 完整管理 VM

  • PVEVMUser: 查看、备份、配置 CD-ROM、VM 控制台、VM 电源管理

可以在 GUI 中查看完整的预定义角色集合。

可以通过 GUI 或命令行添加新角色。

screenshot/gui-datacenter-role-add.png

在 GUI 中，从 Datacenter 导航到 Permissions → Roles 选项卡，然后点击 Create 按钮。可以在那里设置角色名称，并从 Privileges 下拉菜单中选择所需权限。

要通过命令行添加角色，可以使用 pveum CLI 工具，例如：

pveum role add VM_Power-only --privs "VM.PowerMgmt VM.Console"
pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
Note 以 PVE 开头的角色始终是内置角色，自定义角色不允许使用此前缀。

权限

权限是执行特定操作的权利。为简化管理，权限列表会组合成角色，然后可在权限表中使用。请注意， 权限不能不经角色而直接分配给用户和路径。

当前支持以下权限：

节点/系统相关权限

  • Group.Allocate: 创建/修改/移除组

  • Mapping.Audit: 查看资源映射

  • Mapping.Modify: 管理资源映射

  • Mapping.Use: 使用资源映射

  • Permissions.Modify: 修改访问权限

  • Pool.Allocate: 创建/修改/移除池

  • Pool.Audit: 查看池

  • Realm.AllocateUser: 将用户分配到域

  • Realm.Allocate: 创建/修改/移除认证域

  • SDN.Allocate: 管理 SDN 配置

  • SDN.Audit: 查看 SDN 配置

  • Sys.Audit: 查看节点状态/配置、Corosync 集群配置和 HA 配置

  • Sys.Console: 节点控制台访问

  • Sys.Incoming: 允许来自其他集群的入站数据流（实验性）

  • Sys.Modify: 创建/修改/移除节点网络参数

  • Sys.PowerMgmt: 节点电源管理（start、stop、reset、shutdown 等）

  • Sys.Syslog: 查看 syslog

  • User.Modify: 创建/修改/移除用户访问和详细信息。

虚拟机相关权限

  • SDN.Use: 访问 SDN vnet 和本地网络 bridge

  • VM.Allocate: 在服务器上创建/移除 VM

  • VM.Audit: 查看 VM 配置

  • VM.Backup: 备份/还原 VM

  • VM.Clone: 克隆/复制 VM

  • VM.Config.CDROM: 弹出/更换 CD-ROM

  • VM.Config.CPU: 修改 CPU 设置

  • VM.Config.Cloudinit: 修改 Cloud-init 参数

  • VM.Config.Disk: 添加/修改/移除磁盘

  • VM.Config.HWType: 修改模拟硬件类型

  • VM.Config.Memory: 修改内存设置

  • VM.Config.Network: 添加/修改/移除网络设备

  • VM.Config.Options: 修改任何其他 VM 配置

  • VM.Console: VM 控制台访问

  • VM.Migrate: 将 VM 迁移到集群中的其他服务器

  • VM.Monitor: 访问 VM monitor (kvm)

  • VM.PowerMgmt: 电源管理（start、stop、reset、shutdown 等）

  • VM.Snapshot.Rollback: 将 VM 回滚到某个快照

  • VM.Snapshot: 创建/删除 VM 快照

存储相关权限

  • Datastore.Allocate: 创建/修改/移除 datastore，并删除卷

  • Datastore.AllocateSpace: 在 datastore 上分配空间

  • Datastore.AllocateTemplate: 分配/上传模板和 ISO 镜像

  • Datastore.Audit: 查看/浏览 datastore

Warning Permissions.Modify 和 Sys.Modify 都应谨慎处理，因为它们允许修改系统及其配置中 危险或敏感的部分。
Warning 请仔细阅读下文关于继承的章节，以理解已分配角色（及其权限）如何沿 ACL 树传播。

对象和路径

访问权限会分配给对象，例如虚拟机、存储或资源池。我们使用类似文件系统的路径来寻址这些对象。 这些路径形成一棵自然树，高层级（较短路径）的权限可以选择性地在此层级结构中向下传播。

路径可以模板化。当 API 调用需要某个模板化路径上的权限时，该路径可能包含对 API 调用参数的 引用。这些引用用花括号指定。有些参数会从 API 调用的 URI 中隐式取得。例如，在调用 /nodes/mynode/status 时，权限路径 /nodes/{node} 要求拥有 /nodes/mynode 上的权限； 而对 /access/acl 的 PUT 请求中的路径 {path} 则引用该方法的 path 参数。

一些示例如下：

  • /nodes/{node}: 访问 Proxmox VE 服务器机器

  • /vms: 覆盖所有 VM

  • /vms/{vmid}: 访问特定 VM

  • /storage/{storeid}: 访问特定存储

  • /pool/{poolname}: 访问特定 池 中包含的资源

  • /access/groups: 组管理

  • /access/realms/{realmid}: 对域的管理访问

继承

如前所述，对象路径形成一棵类似文件系统的树，权限可以被树中下层对象继承（propagate 标志 默认设置）。我们使用以下继承规则：

  • 单个用户的权限始终替代组权限。

  • 当用户属于某个组时，组权限会生效。

  • 更深层级的权限会替代从上层继承的权限。

  • NoAccess 会取消给定路径上的所有其他角色。

此外，权限分离 token 在任何给定路径上都不能拥有其关联用户没有的权限。

池

池可用于对一组虚拟机和 datastore 分组。之后只需在池 (/pool/{poolid}) 上设置权限， 所有池成员都会继承这些权限。这是简化访问控制的好方法。

我需要哪些权限？

每个单独方法所需的 API 权限都有文档记录，可在 https://pve.proxmox.com/pve-docs/api-viewer/ 找到。

权限以列表形式指定，可解释为逻辑和访问检查函数构成的树：

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

当前列表中的后续元素必须全部（and）或任意一个（or）为真。

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

path 是模板化参数（参见 对象和路径）。指定路径上必须允许列出的 所有权限（或者，如果使用 any 选项，则允许任意一个权限）。如果指定了 require-param 选项，那么即使 API 调用的 schema 将其列为可选参数，该选项指定的参数也仍是必需的。

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

调用者必须在 /access/groups 上拥有列出的任意权限。此外，根据是否设置 groups_param 选项，有两种可能检查：

  • 设置了 groups_param：API 调用有一个不可选的 groups 参数，调用者必须在列出的所有组上 拥有列出的任意权限。

  • 未设置 groups_param：通过 userid 参数传入的用户必须存在，并且必须属于某个组， 调用者在该组上拥有列出的任意权限（通过 /access/groups/<group> 路径）。

["userid-param", "self"]

为 API 调用的 userid 参数提供的值必须指向执行该操作的用户（通常与 or 结合使用， 允许用户在没有提升权限的情况下对自己执行操作）。

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

用户需要对 /access/realm/<realm> 拥有 Realm.AllocateUser 访问权限，其中 <realm> 指通过 userid 参数传入用户所属的域。请注意，用户无需已经存在即可与域关联，因为用户 ID 以 <username>@<realm> 形式传入。

["perm-modify", <path>]

path 是模板化参数（参见 对象和路径）。用户需要 Permissions.Modify 权限，或者根据路径，可以使用以下权限作为替代：

  • /storage/...: 需要 Datastore.Allocate

  • /vms/...: 需要 VM.Allocate

  • /pool/...: 需要 Pool.Allocate

    如果路径为空，则需要 /access 上的 Permissions.Modify。

    如果用户没有 Permissions.Modify 权限，则只能在给定路径上委派自己权限的子集（例如， 拥有 PVEVMAdmin 的用户可以分配 PVEVMUser，但不能分配 PVEAdmin）。

命令行工具

大多数用户会直接使用 GUI 管理用户。但也有一个功能完整的命令行工具，名为 pveum （“Proxmox VE User Manager” 的缩写）。请注意，所有 Proxmox VE 命令行工具都是 API 的包装器，因此也可以通过 REST API 访问这些功能。

下面是一些简单用法示例。要显示帮助，请输入：

 pveum

或者（显示特定命令的详细帮助）：

 pveum help user add

创建新用户：

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

设置或更改密码（并非所有域都支持）：

 pveum passwd testuser@pve

禁用用户：

 pveum user modify testuser@pve -enable 0

创建新组：

 pveum group add testgroup

创建新角色：

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

真实场景示例

管理员组

管理员可能希望创建一组拥有完整管理员权限的用户（而不使用 root 账号）。

为此，首先定义该组：

 pveum group add admin -comment "System Administrators"

然后分配角色：

 pveum acl modify / -group admin -role Administrator

最后，可以将用户添加到新的 admin 组：

 pveum user modify testuser@pve -group admin

审计员

可以通过向用户或组分配 PVEAuditor 角色，授予只读访问权限。

示例 1：允许用户 joe@pve 查看所有内容

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

示例 2：允许用户 joe@pve 查看所有虚拟机

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

委派用户管理

如果希望将用户管理委派给用户 joe@pve，可以使用：

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

用户 joe@pve 现在可以添加和移除用户，并更改其他用户属性，例如密码。这是一个非常强大的 角色，通常应将其限制在选定域和组内。以下示例允许 joe@pve 修改 pve 域内且属于 customers 组的用户：

 pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
 pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
Note 该用户能够添加其他用户，但仅限这些用户属于 customers 组且位于 pve 域内。

用于监控的受限 API token

API token 上的权限始终是其对应用户权限的子集，这意味着 API token 不能用于执行其背后用户 无权执行的任务。本节演示如何使用具有独立权限的 API token，进一步限制 token 所有者的权限。

授予用户 joe@pve 对所有 VM 的 PVEVMAdmin 角色：

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

添加一个具有独立权限的新 API token，只允许查看 VM 信息（例如用于监控）：

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

验证用户和 token 的权限：

 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
Note "-password" 参数会提示输入密码。

然后创建供开发部门使用的资源池：

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

最后，可以为该池分配权限：

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

现在，软件开发人员可以管理分配给该池的资源。

版权和免责声明

Copyright © 2022-2025 成都市梨儿方信息技术有限责任公司.

本程序是自由软件：你可以依据自由软件基金会发布的 GNU Affero General Public License 条款重新分发和/或修改本程序；可使用该许可证第 3 版，或（由你选择）任何后续版本。

发布本程序是希望它能够有用，但不提供任何担保；甚至不包含对适销性或特定用途适用性的默示担保。更多详情请参见 GNU Affero General Public License。

你应当已经随本程序收到一份 GNU Affero General Public License 的副本。如果没有，请访问： https://www.gnu.org/licenses/

Copyright © 2007-2022 Proxmox Server Solutions GmbH

本程序是自由软件：你可以依据自由软件基金会发布的 GNU Affero General Public License 条款重新分发和/或修改本程序；可使用该许可证第 3 版，或（由你选择）任何后续版本。

发布本程序是希望它能够有用，但不提供任何担保；甚至不包含对适销性或特定用途适用性的默示担保。更多详情请参见 GNU Affero General Public License。

你应当已经随本程序收到一份 GNU Affero General Public License 的副本。如果没有，请访问： https://www.gnu.org/licenses/