Complete README

README.md

@@ -1,4 +1,58 @@
-## ACL examples
+`gobottin` is a LDAP server that uses Consul's key-value store as a storage backend,
+in order to provide a redundant (high-availability) LDAP server on a Nomad+Consul cluster.
+It is a reimplementation of [superboum's Bottin](https://github.com/superboum/bottin)
+using the Go programming language.
+
+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.
+
+# 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.
+
+## Connection to the Consul server
+
+By default, `gobottin` connects to the Consul server on localhost.
+Change this by specifying the `consul_host` key in the json config file.
+
+## Bind address
+
+By default, `gobottin` listens on all interfaces on port 389.
+Change this by setting the `bind_address` key in the json config file.
+
+## TLS
+
+`gobottin` supports SSL connections using the STARTTLS LDAP functionnality.
+To use it, specify the following three keys in the json config file:
+
+- `ssl_server_name`: the host name that clients will use to reach your LDAP server
+- `ssl_cert_file`: path to your SSL certificate (a `.pem` file)
+- `ssl_key_file`: path to your SSL key (a `.pem` file)
+
+## Access control list
+
+`gobottin` supports a flexible syntax to specify access rights to items in the database.
+The ACL is specified as a list of rules. A request will be allowed if there exists a rule that allows it. Otherwise an insufficient permission error will be returned.
+
+The list of ACL rules are specified in the `acl` key of the json config file, as a list of strings whose structure is defined in the next paragraph.
+
+### Rule format
+
+A rule is a string composed of five fields separated by `:`. The fields are the following:
+
+1. The name of the user that must be bound (logged in) for the rule to apply. May contain wildcards such as `*` (see the format used by Go's `path.Match`). The special name `ANONYMOUS` applies to clients before they bind to an LDAP entity.
+2. The groups that the user must be a part of, separated by spaces. Wildcards may also be used. If several groups (or wildcard group patterns) are specified, for each pattern the user must be part of a group that matches it.
+3. The action, a subset of `read`, `add`, `delete`, `modify` separated by spaces.
+4. The target entity of the action as a pattern that may contain wildcards. The special word `SELF` is replaced by the entity name of the bound user before trying to match.
+5. The allowed attributes for a read, add or modify operation. This is specified as a list of patterns to include and exclude attributes, separated by spaces. A pattern that starts by `!` is an exclude pattern, otherwise it is an include pattern. To read/write an attribute, it has to match at least one include pattern and not match any exclude pattern. Delete operations do not check for any attribute, thus as soon as `delete` is included in the allowed actions, the right to delete entities is granted.
+
+
+### Rule examples
 
 ```
 // Anybody (before binding) can bind to an entity under ou=users,dc=gobottin,dc=eu

acl.go

@@ -29,10 +29,14 @@ type ACLEntry struct {
 }
 
 func splitNoEmpty(s string) []string {
-	if len(s) == 0 {
+	tmp := strings.Split(s, " ")
-		return []string{}
+	ret := []string{}
+	for _, s := range tmp {
+		if len(s) > 0 {
+			ret = append(ret, s)
+		}
 	}
-	return strings.Split(s, " ")
+	return ret
 }
 
 func ParseACL(def []string) (ACL, error) {