From 77743bd02f880f580fd27c47dd21bd358f770d36 Mon Sep 17 00:00:00 2001
From: Laurent Peuch <cortex@worlddomination.be>
Date: Sun, 13 Aug 2017 23:05:37 +0200
Subject: [PATCH] [doc] document adding stuff in LDAP

---
 doc/ldap.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/doc/ldap.rst b/doc/ldap.rst
index ebec7c38..20f88e12 100644
--- a/doc/ldap.rst
+++ b/doc/ldap.rst
@@ -233,6 +233,70 @@ According to :file:`ldapvi` this is the domain schema (on YunoHost 2.7):
     virtualdomain: domain.com
 
 
+Adding data in LDAP
+===================
+
+Adding stuff in LDAP seems pretty simple, according to existing code it looks like this:
+
+::
+
+    auth.add('key=%s,ou=some_location', {'attribute1': 'value', ...})
+
+They weird stuff is the path you need to create. This looks like that for domain and users:
+
+::
+
+    # domain
+    auth.add('virtualdomain=%s,ou=domains' % domain, attr_dict)
+
+    # user
+    auth.add('uid=%s,ou=users' % username, attr_dict)
+
+You need to respect the expected attributes. Refer to the schemas for that.
+
+:file:`auth.add` seems to return something false when it failed (None probably)
+so you need to check it's return code.
+
+Here is the docstring:
+
+.. automethod:: moulinette.authenticators.ldap.Authenticator.add
+
+Adding user in LDAP
+-------------------
+
+Here is how it's done for a new user:
+
+::
+
+    auth.add('uid=%s,ou=users' % username, {
+        'objectClass': ['mailAccount', 'inetOrgPerson', 'posixAccount'],
+        'givenName': firstname,
+        'sn': lastname,
+        'displayName': '%s %s' % (firstname, lastname),
+        'cn': fullname,
+        'uid': username,
+        'mail': mail,
+        'maildrop': username,
+        'mailuserquota': mailbox_quota,
+        'userPassword': user_pwd,
+        'gidNumber': uid,
+        'uidNumber': uid,
+        'homeDirectory': '/home/' + username,
+        'loginShell': '/bin/false'
+    })
+
+Adding a domain in LDAP
+-----------------------
+
+Here is how it's done for a new domain:
+
+::
+
+    auth.add('virtualdomain=%s,ou=domains' % domain, {
+        'objectClass': ['mailDomain', 'top']
+        'virtualdomain': domain,
+    })
+
 Updating LDAP data
 ==================