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

[Aaron Lauterer]

Sorry, I didn't get to read v1 in time. Some nits regarding grammar, 
reading flow and such inline:

Other than those:
Reviewed-By: Aaron Lauterer <a.lauterer at proxmox.com>

On 4/30/20 2:27 PM, 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>
> ---
> changes from v1:
> * incorporated suggestions from Alwin, thanks :)
> * re-worded the sentence about limitations to specify the character
>    limitations of user.cfg
>   pveum.adoc | 47 +++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 47 insertions(+)
> 
> diff --git a/pveum.adoc b/pveum.adoc
> index c89d4b8..80b3385 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.


The last part `to the user.cfg` makes this sentence somewhat cumbersome 
and hard to read.

Without knowing the full technical details, would it be okay to rewrite 
it to:

"... or in the `Authentication` panel of the GUI. Users and groups are 
synced to the `user.cfg`".

Or maybe even drop the mention of the user.cfg completely?

> +
> +Requirements and limitations
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The `bind_dn` is used to query the users and groups, so this account

s/, so this/. This/

> +should be able to see all desired entries.

s/should be able to see/needs access to/

though this is just a preference of mine and not something that really 
should be changed.

> +
> +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.

is there another chapter explaining the character limitations in the 
user.cfg to which we could link to?

> +
> +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.
> +
> +Options
> +^^^^^^^
> +
> +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 deleting users
> +  and groups which are not returned. If not set, only new data is

possibly
s/returned/present in the LDAP/
to make it clearer?

> +  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
>