109 lines
4.3 KiB
Markdown
109 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.
|