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.