From d831b0929350a8667843e6061ae1fc1ade87d995 Mon Sep 17 00:00:00 2001
From: kakwa <carpentier.pf@gmail.com>
Date: Tue, 12 Feb 2019 23:06:42 +0100
Subject: [PATCH] improve documentation

* improve documentation for key: True flag in attributes.yml
* improve documentation for the ldap filters and their templating
* improve comment in the .ini file
---
 conf/ldapcherry.ini | 10 +++++++++-
 docs/backends.rst   |  8 ++++++--
 docs/deploy.rst     |  7 ++++++-
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/conf/ldapcherry.ini b/conf/ldapcherry.ini
index d6f4c6f..dfbe87a 100644
--- a/conf/ldapcherry.ini
+++ b/conf/ldapcherry.ini
@@ -106,16 +106,24 @@ ldap.timeout = 1
 ldap.groupdn = 'ou=group,dc=example,dc=org'
 # users dn
 ldap.userdn = 'ou=people,dc=example,dc=org'
-# ldapsearch filter to get a user
+
+# ldapsearch filter to get a specific user
+# %(username)s is content of the attribute marked 'key: True' in the attributes.file conf
 ldap.user_filter_tmpl = '(uid=%(username)s)'
 # ldapsearch filter to get groups of a user
+# %(username)s is content of the attribute marked 'key: True' in the attributes.file conf
 ldap.group_filter_tmpl = '(member=uid=%(username)s,ou=People,dc=example,dc=org)'
 # filter to search users
+# %(searchstring)s is content passed through the search box
 ldap.search_filter_tmpl = '(|(uid=%(searchstring)s*)(sn=%(searchstring)s*))'
 
 # ldap group attributes and how to fill them
+# 'member' is the name of the attribute
+# for the template, any of the user's ldap attributes can be user
 ldap.group_attr.member = "%(dn)s"
+# same with memverUid and the uid user's attribute
 #ldap.group_attr.memberUid = "%(uid)s"
+
 # object classes of a user entry
 ldap.objectclasses = 'top, person, posixAccount, inetOrgPerson'
 # dn entry attribute for an ldap user
diff --git a/docs/backends.rst b/docs/backends.rst
index 878fa7a..8b23a8b 100644
--- a/docs/backends.rst
+++ b/docs/backends.rst
@@ -73,7 +73,10 @@ The ldap backend exposes the following parameters:
 | userdn                   | backends | The ldap dn where users are        | ldap dn                  |                                            |
 +--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+
 | user_filter_tmpl         | backends | The search filter template         | ldap search filter       | The user identifier is passed through      |
-|                          |          | to recover a given user            | template                 | the **username** variable (*%(username)s*).|
+|                          |          | to recover a given user            | template                 | the **username** variable (*%(username)s*) |
+|                          |          |                                    |                          |                                            |
+|                          |          |                                    |                          | **username** is the attribute marked by    |
+|                          |          |                                    |                          | **key: True** in the **attribute.yml** file|
 +--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+
 | group_filter_tmpl        | backends | The search filter template to      | ldap search filter       | The following variables are usable:        |
 |                          |          | recover the groups of a given user | template                 | * **username**: the user key attribute     |
@@ -83,7 +86,8 @@ The ldap backend exposes the following parameters:
 |                          |          |                                    |                          |   in groups dn entries                     |
 |                          |          |                                    |                          | * every user attributes are exposed        |
 |                          |          |                                    |                          |   in the template                          |
-|                          |          |                                    |                          | * multiple attributes can be set           |
+|                          |          |                                    |                          | * multiple <memver attr> attributes        |
+|                          |          |                                    |                          |   can be set                               |
 +--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+
 | objectclasses            | backends | list of object classes for users   | comma separated list     |                                            |
 +--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+
diff --git a/docs/deploy.rst b/docs/deploy.rst
index 2475b41..5859d0c 100644
--- a/docs/deploy.rst
+++ b/docs/deploy.rst
@@ -112,7 +112,12 @@ If **type** is set to **stringlist** the parameter **values** must be filled wit
 Key attribute:
 ^^^^^^^^^^^^^^
 
-One attribute must be used as a unique key across all backends:
+One attribute must be used as a unique key across all backends.
+
+It acts as a reconciliation key.
+
+It also marks which attribute must be used within ldapcherry (ex: querysting parameter in links)
+to point to one given user.
 
 To set the key attribute, you must set **key** to **True** on this attribute.