X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=b5eea290efa3778e19513a0413d63bab483b937d;hp=fd0dfd1522444773936a117d83796cbf3e34e4f1;hb=43530f6fe44c20926717a95e02aa19400ad2409c;hpb=710713eaa6b88d0a8b71a7f6ed7f54b96b66c827

diff --git a/pveum.adoc b/pveum.adoc
index fd0dfd1..b5eea29 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -68,7 +68,7 @@ assigned to this user.
 
 [[pveum_groups]]
 Groups
-~~~~~~
+------
 
 Each user can be member of several groups. Groups are the preferred
 way to organize access permissions. You should always grant permission
@@ -77,7 +77,7 @@ much shorter access control list which is easier to handle.
 
 [[pveum_tokens]]
 API Tokens
-~~~~~~~~~~
+----------
 
 API tokens allow stateless access to most parts of the REST API by another
 system, software or API client. Tokens can be generated for individual users
@@ -93,8 +93,8 @@ API tokens come in two basic types:
 * full privileges: the token permissions are identical to that of the
   associated user.
 
-WARNING: The token value is only displayed/returned once when the token is
-generated. It cannot be retrieved over the API at a later time!
+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
@@ -163,6 +163,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.
++
+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::
 
@@ -170,6 +176,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.
 
+[[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
@@ -222,7 +285,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
-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]]