[pve-devel] [PATCH docs] add documenation for ldap syncing

[Dominik Csapak]

explaining the main Requirements and limitations, as well as the
most important sync options

Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
---
 pveum.adoc | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/pveum.adoc b/pveum.adoc
index c89d4b8..5881fa9 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -170,6 +170,53 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to sync users and groups for ldap based realms using
+  pveum sync <realm>
+or in the `Authentication` panel of the GUI to the user.cfg.
+
+Requirements and limitations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `bind_dn` will be used to query the users and groups, so this account
+should be able to see all desired entries.
+
+The names of the users and groups (configurable via `user_attr` and
+`group_name_attr` respectively) have to adhere to the limitations of usual
+users and groups in the config.
+
+Groups will be synced with `-$realm` attached to the name, to avoid naming
+conflicts. Please make sure that a sync does not overwrite manually created
+groups.
+
+Options
+^^^^^^^
+
+The main options for syncing are:
+
+* `dry-run`: No data will actually be synced. 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 usses the LDAP Directory as source of truth,
+  overwriting information set manually in the user.cfg and deleting users
+  and groups which were not returned. If not set, only new data
+  will be written to the config, and no stale users will be 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. Can be either `users`, `groups` or
+  `both`.
+
+These options either to be set either as parameters, or as defaults, via the
+realm option `sync-defaults-options`.
 
 [[pveum_tfa_auth]]
 Two-factor authentication
-- 
2.20.1