fetchcert/README.md

108 lines
4.3 KiB
Markdown

fetchcert
=========
`fetchcert` is a somewhat overengineered program that fetches certificates from
LDAP servers, installs them if they are new or have changed, and runs commands
after that.
It can be used as a standalone program (e.g. from a cron) or as a server which
uses a UNIX socket to receive commands. This ability could be used to connect
the server to a message bus, for example.
Configuration
-------------
`fetchcert` reads its configuration from a YAML file. The
`fetch-certificates.yml.example` file in this repository contains information
about the specific structure of the file; this section describes the principles
behind it.
### Certificates
that lists PEM files that
must be maintained. Each PEM file can be generated by:
* prepending and/or appending local PEM files,
* adding an end-entity certificate from the LDAP server,
* adding CA certificates from the LDAP server.
CA certificate chains can be specified directly as a list of LDAP DNs. However
it is also possible to use some LDAP attribute (e.g. `seeAlso`) to represent the
next CA certificate in the chain. `fetchcert` is capable of following these
links.
### Commands and handlers
When a PEM file is replaced by the program, it is capable of running various
commands. Each PEM file section can configure:
* __pre-commands__, which will be executed right after the certificate is
replaced ;
* __handlers__; a handler is only executed once, even if multiple certificates
triggered it. Handlers are defined as lists of command in another section
of the configuration file.
* __post-commands__ are executed for each PEM file after handlers have run.
Execution of commands is interrupted for a given file if a command fails.
### Other configuration elements
In addition to the certificate files and handlers, the configuration file must
also contain the LDAP server(s) configuration, and the configuration for the
UNIX socket if the program is used in client/server mode.
Usage
-----
### Common options
The following options are available in all modes:
* `-c <file>` / `--config <file>` specifies the path to the configuration
file; by default `/etc/fetch-certificates.yml` will be used.
* `-F <log-file>` / `--log-file <log-file>` specifies the path to a log file.
By default, logs are not written to a file.
* `-g <server>:<port>` / `--log-graylog <server>:<port>` sends logs to a
Graylog server using GELF over UDP.
* `-l <log-level>` / `--log-level <log-level>` can be used to change the log
level, which defaults to `info`.
* `-q` / `--quiet` prevents logging to the standard error stream.
* `-s` / `--syslog` send logs to syslog. Logs will be sent with the
`fetchcert` application name.
The `-h` / `--help` can be used to display command line help. Finally, the
`-m` / `--mode` option can be used to specify the execution mode (standalone,
client or server). See below for more information.
### Standalone mode
If the `-m standalone` option is specified (or if no `-m` option is used), the
program runs in standalone mode, updating certificate files and running commands
directly.
* `-f` / `--force` forces the program to replace all certificate files and
execute the commands and handlers.
* `-u <dn>` / `--update <dn>` specifies a LDAP DN which will act as a
selector. Only files which use the certificate from that DN will be
considered for update.
### Client mode
If the `-m client` option is specified, the program runs in client mode. In this
mode, it will send commands and update requests to the server based on the
command line arguments below.
* `-C <command>` / `--command <command>` sends the command to the server. The
command may be either `Q` (which will cause the server to stop) or `R`
(which will force the server to reload its configuration file). If this
command line option is used, the client will not send an update request.
* `-f` / `--force` sends a flag that forces the server to replace all
certificate files and execute the commands and handlers.
* `-u <dn>` / `--update <dn>` specifies a LDAP DN which will act as a
selector. The server will only replace files which use the certificate from
that DN.
### Server mode
If the `-m server` command line option is specified, the program starts and
runs in server mode. No additional options are needed.