Complete readme

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`:
-// Anybody (before binding) can bind to an entity under ou=users,dc=gobottin,dc=eu
+  `ANONYMOUS::bind:*,ou=users,dc=gobottin,dc=eu:`
-"ANONYMOUS::bind:*,ou=users,dc=gobottin,dc=eu:",
+
-// Anybody (before binding) can bind to the specific admin entity
+- Anybody (before binding) can bind to the specific admin entity:
-"ANONYMOUS::bind:cn=admin,dc=gobottin,dc=eu:",
+  `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 who is logged in can read anything that is not a userpassword attribute:
-// Anybody can read and modify anything from their own entry
+  `*,dc=gobottin,dc=eu::read:*:* !userpassword`
-"*::read modify:SELF:*",
+
-// The admin can read, add, modify, delete anything
+- Anybody can read and modify anything from their own entry:
-"cn=admin,dc=gobottin,dc=eu::read add modify delete:*:*",
+  `*::read modify:SELF:*`
-// Members of the admin group can read, add, modify, delete anything
+
-"*:cn=admin,ou=groups,dc=gobottin,dc=eu:read add modify delete:*:*"
+- 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:*:*`