of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
refer to your API client documentation.
+[[pveum_resource_pools]]
+Resource Pools
+--------------
+
+[thumbnail="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.
+
[[pveum_authentication_realms]]
Authentication Realms
---------------------
The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
attribute would be `uid`.
+
-If {pve} needs to authenticate (bind) to the ldap server before being
+If {pve} needs to authenticate (bind) to the LDAP server before being
able to query and authenticate users, a bind domain name can be
configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
(e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
single line containing the raw password.
++
+To verify certificates, you need to 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.
Microsoft Active Directory::
-A server and authentication domain need to be specified. Like with
-ldap an optional fallback server, optional port, and SSL
-encryption can be configured.
+A server and authentication domain need to be specified. Like with LDAP, an
+optional fallback server, port, and SSL encryption can be configured.
[[pveum_ldap_sync]]
Syncing LDAP-based realms
~~~~~~~~~~~~~~~~~~~~~~~~~
-It is possible to sync users and groups for LDAP based realms using
- pveum sync <realm>
-or in the `Authentication` panel of the GUI. Users and groups are synced
-to `/etc/pve/user.cfg`.
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
+
+It is possible to sync users and groups for LDAP based realms. You can use the
+CLI command
+
+----
+ pveum realm sync <realm>
+----
+or in the `Authentication` panel of the GUI. Users and groups are synced to the
+cluster-wide user configuration file `/etc/pve/user.cfg`.
Requirements and limitations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The `bind_dn` is used to query the users and groups. This account
-needs access to all desired entries.
+The `bind_dn` is used to query the users and groups. This account needs access
+to all desired entries.
The fields which represent the names of the users and groups can be configured
via the `user_attr` and `group_name_attr` respectively. Only entries which
conflicts. Please make sure that a sync does not overwrite manually created
groups.
+[[pveum_ldap_sync_options]]
Options
^^^^^^^
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
+
The main options for syncing are:
* `dry-run`: No data is written to the config. This is useful if you want to
Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
documentation for how to use the
https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
-https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[host
+https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host
your own verification server].
[[pveum_user_configured_totp]]
Server side U2F configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To allow users to use 'U2F' authentication, the server needs to have a valid
-domain with a valid https certificate. Initially an 'AppId'
+To allow users to use 'U2F' authentication, it may be necessary to use a valid
+domain with a valid https certificate, otherwise some browsers may print
+a warning or reject U2F usage altogether. Initially an 'AppId'
footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
needs to be configured.
* `PVETemplateUser`: view and clone templates
* `PVEUserAdmin`: user administration
* `PVEVMAdmin`: fully administer VMs
-* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
+* `PVEVMUser`: view, backup, config CD-ROM, VM console, VM power management
You can see the whole set of predefined roles on the GUI.
* `VM.Audit`: view VM config
* `VM.Clone`: clone/copy a VM
* `VM.Config.Disk`: add/modify/delete Disks
-* `VM.Config.CDROM`: eject/change CDROM
+* `VM.Config.CDROM`: eject/change CD-ROM
* `VM.Config.CPU`: modify CPU settings
* `VM.Config.Memory`: modify Memory settings
* `VM.Config.Network`: add/modify/delete Network devices
or (to show detailed help about a specific command)
[source,bash]
- pveum help useradd
+ pveum help user add
Create a new user:
[source,bash]
- 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):
Disable a user:
[source,bash]
- pveum usermod testuser@pve -enable 0
+ pveum user modify testuser@pve -enable 0
Create a new group:
[source,bash]
- pveum groupadd testgroup
+ pveum group add testgroup
Create a new role:
[source,bash]
- pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+ pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
Real World Examples
Define the group:
[source,bash]
- pveum groupadd admin -comment "System Administrators"
+ pveum group add admin -comment "System Administrators"
Then add the permission:
[source,bash]
- pveum aclmod / -group admin -role Administrator
+ pveum acl modify / -group admin -role Administrator
You can finally add users to the new 'admin' group:
[source,bash]
- pveum usermod testuser@pve -group admin
+ pveum user modify testuser@pve -group admin
Auditors
Example1: Allow user `joe@pve` to see everything
[source,bash]
- 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
[source,bash]
- pveum aclmod /vms -user joe@pve -role PVEAuditor
+ pveum acl modify /vms -user joe@pve -role PVEAuditor
Delegate User Management
that with:
[source,bash]
- 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
other user attributes. This is a very powerful role, and you most
are members of group `customers`:
[source,bash]
- pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
- pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
+ 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 group `customers` and within realm `pve`.
Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
[source,bash]
- pveum aclmod /vms -user joe@pve -role PVEVMAdmin
+ 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 (e.g., for monitoring purposes):
[source,bash]
pveum user token add joe@pve monitoring -privsep 1
- pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor
+ 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
-Pools
-~~~~~
-
-An enterprise is usually structured into several smaller departments,
-and it is common that you want to assign resources to them and
-delegate management tasks. A pool is simply a set of virtual machines
-and data stores. You can create pools on the GUI. After that you can
-add resources to the pool (VMs, Storage).
+Resource Pools
+~~~~~~~~~~~~~~
-You can also assign permissions to the pool. Those permissions are
-inherited to all pool members.
-
-Lets assume you have a software development department, so we first
-create a group
+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
[source,bash]
- pveum groupadd developers -comment "Our software developers"
+ pveum group add developers -comment "Our software developers"
Now we create a new user which is a member of that group
[source,bash]
- pveum useradd developer1@pve -group developers -password
+ pveum user add developer1@pve -group developers -password
NOTE: The -password parameter will prompt you for a password
-I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
+Then we create a resource pool for our development department to use
+
+[source,bash]
+ pveum pool add dev-pool --comment "IT development pool"
+
+Finally, we can assign permissions to that pool
[source,bash]
- pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
+ pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
Our software developers can now administrate the resources assigned to
that pool.
projects / pve-docs.git / blobdiff