From 7b77bfc66c94e80e4c65e9d087e5a10ce849bd01 Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Sun, 26 Jan 2020 20:18:22 +0100
Subject: [PATCH] Complete readme

---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 40 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index c70e888..3207454 100644
--- a/README.md
+++ b/README.md
@@ -3,17 +3,39 @@ in order to provide a redundant (high-availability) LDAP server on a Nomad+Consu
 It is a reimplementation of [superboum's Bottin](https://github.com/superboum/bottin)
 using the Go programming language.
 
+Features:
+
+- most LDAP operations implemented (add, modify, delete, compare, search with most basic filters)
+- TLS support with STARTTLS
+- Access control through an ACL (hardcoded in the configuration file)
+
+
 Building `gobottin` can be done simply by running `go build` in this folder.
 
 `gobottin` takes a single command line argument, `-config <filename>`, which is the
 path to its config file (defaults to `./config.json`).
 The configuration file is a JSON file whose contents is described in the following section.
 
+
+# Server initialization
+
+When `gobottin` is launched on an empty database,
+it creates a special admin entity with the name `cn=admin,your_suffix`.
+It will have a randomly generated password that is printed out by the server.
+Check your logs to retrieve the password.
+
+The admin entity has no powers other than those granted by the ACL rules,
+so unless you don't want to use it, make sure to keep rules that allow to
+bind to the admin entity and that allows the admin entity to do everything.
+
+
 # Configuration of `gobottin`
 
 ## The LDAP suffix
 
-`gobottin` only handles LDAP entries under a given path, which is typically of the form `dn=sld,dn=tld`, where `sld.tld` is your domain name. Specify this suffix in the `suffix` key of the json config file.
+`gobottin` only handles LDAP entries under a given path, which is typically of
+the form `dn=sld,dn=tld`, where `sld.tld` is your domain name. Specify this
+suffix in the `suffix` key of the json config file.
 
 ## Connection to the Consul server
 
@@ -54,17 +76,20 @@ A rule is a string composed of five fields separated by `:`. The fields are the
 
 ### Rule examples
 
-```
-// Anybody (before binding) can bind to an entity under ou=users,dc=gobottin,dc=eu
-"ANONYMOUS::bind:*,ou=users,dc=gobottin,dc=eu:",
-// Anybody (before binding) can bind to the specific admin entity
-"ANONYMOUS::bind:cn=admin,dc=gobottin,dc=eu:",
-// Anybody who is logged in can read anything that is not a userpassword attribute
-"*,dc=gobottin,dc=eu::read:*:* !userpassword",
-// Anybody can read and modify anything from their own entry
-"*::read modify:SELF:*",
-// The admin can read, add, modify, delete anything
-"cn=admin,dc=gobottin,dc=eu::read add modify delete:*:*",
-// Members of the admin group can read, add, modify, delete anything
-"*:cn=admin,ou=groups,dc=gobottin,dc=eu:read add modify delete:*:*"
-```
+- Anybody (before binding) can bind to an entity under `ou=users,dc=gobottin,dc=eu`:
+  `ANONYMOUS::bind:*,ou=users,dc=gobottin,dc=eu:`
+
+- Anybody (before binding) can bind to the specific admin entity:
+  `ANONYMOUS::bind:cn=admin,dc=gobottin,dc=eu:`
+
+- Anybody who is logged in can read anything that is not a userpassword attribute:
+  `*,dc=gobottin,dc=eu::read:*:* !userpassword`
+
+- Anybody can read and modify anything from their own entry:
+  `*::read modify:SELF:*`
+
+- The admin can read, add, modify, delete anything:
+  `cn=admin,dc=gobottin,dc=eu::read add modify delete:*:*`
+
+- Members of the admin group can read, add, modify, delete anything:
+  `*:cn=admin,ou=groups,dc=gobottin,dc=eu:read add modify delete:*:*`