diff --git a/README.md b/README.md index c7e09b2..9d58abe 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,8 @@ +# Bottin + +
+ + Bottin 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) @@ -21,7 +26,7 @@ The configuration file is a JSON file whose contents is described in the followi Bottin is licensed under the terms of the GPLv3. -# Server initialization +## Server initialization When Bottin is launched on an empty database, it creates a special admin entity with the name `cn=admin,your_suffix`. @@ -33,36 +38,36 @@ 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 Bottin +## Configuration of Bottin -## Logging +### Logging Bottin supports all of the log levels of [logrus](https://github.com/sirupsen/logrus). The log level can be specified in the key `log_level` of the json config file, or in the environment variable `BOTTIN_LOG_LEVEL`. By default, the log level is set to `info`. -## The LDAP suffix +### The LDAP suffix Bottin 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 +### Connection to the Consul server By default, Bottin connects to the Consul server on localhost. Change this by specifying the `consul_host` key in the json config file. -## Bind addresses +### Bind addresses -### Insecure port +#### Insecure port By default, Bottin listens on all interfaces on port 389 for standard non-TLS connections. Change the value of the `bind` key in the json config file to change this behaviour (default value: `0.0.0.0:389`). An empty string will disable this port and Bottin will not listen for non-TLS connections. -### Secure port +#### Secure port If a TLS configuration is provided (see next section), Bottin also listens on all interfaces on port 636 for TLS connections. Change the value of the @@ -70,7 +75,7 @@ on all interfaces on port 636 for TLS connections. Change the value of the value: `0.0.0.0:636`). An empty string will disable this port and Bottin will not listen for TLS connections. -## TLS +### TLS Bottin supports TLS connections using either fully secure connections or using the STARTLS functionnality of the LDAP protocol to upgrade from an @@ -87,14 +92,14 @@ insecure port, independently of whether the secure port is enabled or not. The secure port is disabled and a warning is shown if the `bind_secure` value is set (non-empty) and no valid TLS configuration is provided. -## Access control list +### Access control list Bottin 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 +#### Rule format A rule is a string composed of five fields separated by `:`. The fields are the following: @@ -105,7 +110,7 @@ A rule is a string composed of five fields separated by `:`. The fields are the 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 +#### Rule examples - Anybody (before binding) can bind to an entity under `ou=users,dc=bottin,dc=eu`: `ANONYMOUS::bind:*,ou=users,dc=bottin,dc=eu:` diff --git a/bottin.png b/bottin.png new file mode 100644 index 0000000..709df01 Binary files /dev/null and b/bottin.png differ