ceph: section language fixup

[pve-docs.git] / pveum.adoc

diff --git a/pveum.adoc b/pveum.adoc
index c89d4b872caa7be377f8fe1fa222af3581c3f23b..1f7c69fb7a1a8b7ce8cdb2f00a89857afd4194c4 100644 (file)
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -100,6 +100,20 @@ 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 documentation.
 
 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
 ---------------------
 [[pveum_authentication_realms]]
 Authentication Realms
 ---------------------


@@ -163,6 +177,12 @@ 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.
 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 doen over
+the web interface.

 
 Microsoft Active Directory::
 
 
 Microsoft Active Directory::
 


@@ -170,6 +190,63 @@ A server and authentication domain need to be specified. Like with
 ldap an optional fallback server, optional port, and SSL
 encryption can be configured.
 
 ldap an optional fallback server, optional port, and SSL
 encryption can be configured.
 

+[[pveum_ldap_sync]]
+Syncing LDAP-based realms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[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 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
+adhere to the usual character limitations of the user.cfg are synced.
+
+Groups are synced with `-$realm` attached to the name, to avoid naming
+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
+  see which users and groups would get synced to the user.cfg. This is set
+  when you click `Preview` in the GUI.
+
+* `enable-new`: If set, the newly synced users are enabled and can login.
+  The default is `true`.
+
+* `full`: If set, the sync uses the LDAP Directory as a source of truth,
+  overwriting information set manually in the user.cfg and deletes users
+  and groups which are not present in the LDAP directory. If not set,
+  only new data is written to the config, and no stale users are deleted.
+
+* `purge`: If set, sync removes all corresponding ACLs when removing users
+  and groups. This is only useful with the option `full`.
+
+* `scope`: The scope of what to sync. It can be either `users`, `groups` or
+  `both`.
+
+These options are either set as parameters or as defaults, via the
+realm option `sync-defaults-options`.

 
 [[pveum_tfa_auth]]
 Two-factor authentication
 
 [[pveum_tfa_auth]]
 Two-factor authentication


@@ -222,7 +299,7 @@ password into the user's 'Key IDs' field.
 Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
 documentation for how to use the
 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
 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]]
 your own verification server].
 
 [[pveum_user_configured_totp]]


@@ -530,12 +607,12 @@ Here are some simple usage examples. To show help type:
 or (to show detailed help about a specific command)
 
 [source,bash]
 or (to show detailed help about a specific command)
 
 [source,bash]

- pveum help useradd
+ pveum help user add

 
 Create a new user:
 
 [source,bash]
 
 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):
 
 
 Set or Change the password (not all realms support that):
 


@@ -545,17 +622,17 @@ Set or Change the password (not all realms support that):
 Disable a user:
 
 [source,bash]
 Disable a user:
 
 [source,bash]

- pveum usermod testuser@pve -enable 0
+ pveum user modify testuser@pve -enable 0

 
 Create a new group:
 
 [source,bash]
 
 Create a new group:
 
 [source,bash]

- pveum groupadd testgroup
+ pveum group add testgroup

 
 Create a new role:
 
 [source,bash]
 
 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
 
 
 Real World Examples


@@ -571,17 +648,17 @@ users with full administrator rights (without using the root account).
 Define the group:
 
 [source,bash]
 Define the group:
 
 [source,bash]

- pveum groupadd admin -comment "System Administrators"
+ pveum group add admin -comment "System Administrators"

 
 Then add the permission:
 
 [source,bash]
 
 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]
 
 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
 
 
 Auditors


@@ -593,12 +670,12 @@ role to users or groups.
 Example1: Allow user `joe@pve` to see everything
 
 [source,bash]
 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]
 
 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
 
 
 Delegate User Management


@@ -608,7 +685,7 @@ If you want to delegate user management to user `joe@pve` you can do
 that with:
 
 [source,bash]
 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
 
 User `joe@pve` can now add and remove users, change passwords and
 other user attributes. This is a very powerful role, and you most


@@ -617,8 +694,8 @@ example allows `joe@pve` to modify users within realm `pve` if they
 are members of group `customers`:
 
 [source,bash]
 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`.
 
 NOTE: The user is able to add other users, but only if they are
 members of group `customers` and within realm `pve`.


@@ -629,14 +706,14 @@ Limited API token for monitoring
 Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
 
 [source,bash]
 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
 
 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:
 
 
 Verify the permissions of the user and token:
 


@@ -644,35 +721,33 @@ Verify the permissions of the user and token:
  pveum user permissions joe@pve
  pveum user token permissions joe@pve monitoring
 
  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).
-
-You can also assign permissions to the pool. Those permissions are
-inherited to all pool members.
+Resource Pools
+~~~~~~~~~~~~~~

 
 

-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]
 
 [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]
 
 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
 
 
 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]
 
 [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.
 
 Our software developers can now administrate the resources assigned to
 that pool.