Commit f095fa5e authored by ale's avatar ale

Fix the documentation for backends_dir

It wasn't updated after the config refactoring.
parent 33ded555
Pipeline #2652 passed with stages
in 1 minute and 56 seconds
......@@ -64,12 +64,14 @@ The YAML file should contain a dictionary with the following attributes:
file (using the `services` attribute), it is possible to define
additional services in YAML-encoded files (having a *.yml*
extension), which is more automation-friendly.
* `backends` is a dictionary describing all known backends and their
configuration parameters. The *file* backend is predefined and always
exists (it requires no configuration).
* `backends_dir` (optional) points at a directory containing backend
configuration as YAML-encoded files: all files with a *.yml*
extension will be loaded.
* `rate_limits` defines the global rate limiters and blacklists. See
the *Rate limiting* section below.
* `enabled_backends` is the list of user backends that should be
enabled (the available backends are *file* and *ldap*)
* `ldap_config` specifies the configuration for the LDAP backend --
see the *LDAP Backend* section below
* `user_meta_server` holds the configuration for the user-meta-server
backend:
* `url` is the URL of the service
......@@ -80,6 +82,28 @@ The YAML file should contain a dictionary with the following attributes:
* `memcache_servers` contains a list of memcached server addresses (in
host:port format)
## Example configuration
An example configuration using both the *sql* backend (with default
schema and queries) for normal users, and the *file* backend for admin
users could look like this:
```yaml
---
backends:
sql:
driver: sqlite3
db_uri: users.db
services:
example_service:
backends:
- backend: sql
- backend: file
params:
src: admins.yml
static_groups: [admins]
```
## Rate limiting
Rate limits and blacklists are global (available to all services), to
......@@ -103,12 +127,12 @@ should specify the following attributes:
Each service definition is a dictionary with the following attributes:
* `backends` is a list of user backend specifications, each one should
include a backend-specific configuration under an attribute named
after the backend itself:
* `file` is simply a path to a user list file, see the *File
backend* section below
* `ldap` configues the LDAP backend for this service
* `backends` is a list of user backend specifications, each one a
dictionary/map with the following attributes:
* `backend` must be the name of a backend that appears in the
top-level configuration map *backends*.
* `params` is a map of backend-specific attributes that configure
the backend for this service.
* `static_groups` is a list of group names that users sourced from
this backend will automatically be added to
* `challenge_response` is a boolean parameter that, when true, enables
......@@ -127,30 +151,34 @@ Each service definition is a dictionary with the following attributes:
## File backend
The *file* backend reads users and their credentials from a
YAML-encoded file. This file should contain a list of dictionaries,
each representing a user, with the following attributes:
YAML-encoded file. The service-specific configuration parameters are:
* `src` should point at the users file.
This file should contain a list of dictionaries, each representing a
user, with the following attributes:
* `name` is the username
* `email` is the email associated with the user (optional)
* `password` stores the encrypted password
* `totp_secret` stores the *unencrypted* TOTP secret seed
* `u2f_registrations` is a list of U2F registrations with `key_handle`
and `public_key` attributes, in the format used by *pamu2fcfg* (for
convenience)
* `groups` is a list of group names that the user belongs to
The file backend only supports TOTP as a two-factor authentication
method, U2F support is currently missing.
## LDAP Backend
The *ldap* backend will look up user information in a LDAP database.
It needs some parameters to be passed in the top-level *ldap_config*
dictionary:
The backend connects to a single LDAP server and requires the
following top-level configuration:
* `uri` of the LDAP server (like *ldapi:///var/run/ldap/ldapi*)
* `bind_dn` is the DN to bind with
* `bind_pw_file` points at a file containing the bind password
The *ldap* backend will currently always attempt to bind on every
connection.
Each service can then use different queries, as shown in the next
section.
### Query definition
......
......@@ -36,7 +36,7 @@ type Config struct {
ServicesDir string `yaml:"services_dir"`
// Enabled backends.
Backends map[string]yaml.MapSlice `yaml:"enabled_backends"`
Backends map[string]yaml.MapSlice `yaml:"backends"`
// If set, load more backend definitions from *.yml files in this directory.
BackendsDir string `yaml:"backends_dir"`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment