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

[Alwin Antreich]

My suggestions inline.

On Thu, Apr 30, 2020 at 01:14:27PM +0200, Dominik Csapak wrote:
> 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
s/ldap/LDAP

> +  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.
s/will be/is/

> +
> +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.
For me, this is hard to read. It may be better in two sentences. And
what does it mean, adhere to the limitations?

eg:
The user and group names have to adhere to the limitation of the
configuration.  Configurable via `user_attr` and `group_name_attr`
respectively.

> +
> +Groups will be synced with `-$realm` attached to the name, to avoid naming
s/will be/are/

> +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.
s/will actually/is/

> +
> +* `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,
s/usses/uses/
s/as source/as a source/

> +  overwriting information set manually in the user.cfg and deleting users
> +  and groups which were not returned. If not set, only new data
s/were not returned/are not returned/

> +  will be written to the config, and no stale users will be deleted.
s/will be/is/

> +
> +* `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
s/Can be/It can be/

> +  `both`.
> +
> +These options either to be set either as parameters, or as defaults, via the
These options are either set as parameters or as defaults, via the

> +realm option `sync-defaults-options`.
>  
>  [[pveum_tfa_auth]]
>  Two-factor authentication
> -- 
> 2.20.1