acmebot 2.17.0
ACME protocol automatic certitificate manager
Requires Python: >=3.8

.. _bindtool: https://github.com/plinss/bindtool

*******
acmebot
*******

ACME protocol automatic certitificate manager.

This tool acquires and maintains certificates from a certificate authority using the ACME protocol, similar to EFF's Certbot.
While developed and tested using Let's Encrypt, the tool should work with any certificate authority using the ACME protocol.


Features
========

This tool is not intended as a replacement for Certbot and does not attempt to replicate all of Certbot's functionality,
notably it does not modify configuration files of other services,
or provide a server to perform stand-alone domain validation.
It does however, do a few things that Certbot does not,
simplifying certificate management in more advanced environments.
In addition to automatically issuing and maintaining certificates,
the tool can also maintain associated HPKP headers and TLSA (DANE) records.


Master/Follower Mode
--------------------

This tool separates the authorization (domain validation) and certificate issuance processes allowing one machine to maintain authorizations (the master),
while another machine issues certificates (the follower).
This is useful for situations where an isolated server is providing a service, such as XMPP,
behind a firewall and does not have the ability to perform authorizations over http or configure DNS records,
but still needs to obtain and periodically renew one or more certificates.


Sharing of Private Keys Between Certificates
--------------------------------------------

This tool allows multiple certificates to be defined using the same public/private key pair.

When deploying Hypertext Puplic Key Pinning (HPKP), you can optionally use the same pins to secure subdomains.
This increases security of the site because a visitor to a root domain will have previously obtained pins for subdomains,
reducing the possibility of a man-in-the-middle attacker installing a false pin on first visit.

This practice obviously requires the use of the same public/private key pair for the domain and all subdomains.
However, it may not be desirable to use the same certificate for all subdomains, for example,
exposing the full list of subdomains in the alternative names of the root domain's certificate,
or reissuing the root domain's certificate every time a subdomain is added or removed.


Hypertext Public Key Pin (HPKP) Support
---------------------------------------

This tool automatically generates and maintains HPKP header information suitable to be directly included in server configuraton files.
Support for Apache and Nginx are provided by default, other servers may be added by the user.


Automatic Management of Backup Private Keys
-------------------------------------------

Using HPKP requires a second public key to provide a backup when private keys are changed.
This tool automatically generates backup keys and switches to the pre-generated backup key when rolling over private keys.
Rolling over private keys can be done automatically and is scheduled independently of certificate expiration.
Private key rollover is prevented in cases where insufficient time has passed to distribute backup HPKP pins.


Parallel RSA and ECDSA Certificates
-----------------------------------

This tool can generate both RSA and ECDSA certificates.
By default it will generate and maintain both types of certificates in parallel.


Certificate Transparency / Signed Certificate Timestamp Support
---------------------------------------------------------------

This tool can automatically register your certificates with multiple certificate transparency logs and retrieve Signed Certificate Timestamps (SCTs) for each.
The retrieved SCTs are suitable to be deilvered via a TLS extension,
SCT TLS extension modules are available for `Apache <https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_ and `Nginx <https://github.com/grahamedgecombe/nginx-ct>`_.


OCSP Response File Support
--------------------------

This tool automatically obtains and maintains OCSP response files for each configured certificate.
These files may be used to serve stapled OCSP responses from your server without relying on the server's OCSP stapling mechanisms.
Some servers, such as Nginx, obtain stapled OCSP responses lazily and cache the response in memory.
When using the OCSP Must-Staple extension this can result in your server being unreachable until the OCSP response is refreshed,
during OCSP responder outages, this can be a significant interval.
Using OCSP responses from disk will alleviate this issue.
Only OCSP responses with a "good" status will be stored.


Encrypted Private Keys
----------------------

Primary and backup private keys can optionally be encrypted using a passphrase and cipher of your choice.


Mixed Use of DNS and HTTP Authorization
---------------------------------------

By default this tool performs dns-01 authorizartions for domain validation.
It is possible to configure overrides for specific domains names to use http-01 authorization instead.
This is useful for situations where a domain outside your immediate control has provided an alias to your web site.


Automatic Local or Remote DNS Updates
-------------------------------------

This tool can automatically add and remove DNS records for dns-01 authorizations as well as TLSA records.
Updates to a local server can be made via an external zone file processor, such as `bindtool`_,
or to a remote DNS server via RFC 2136 dynamic DNS updates using ``nsupdate``.
The choice between local and remote DNS updates can be made on a zone by zone basis.


Configurable Output File Names
------------------------------

Server administrators often develop their own file naming conventions or need to match naming conventions of other tools.
The names and output directories of all certificate, key, and related files are fully configurable.
The defaults are intended for standard Debian installations.


Configurable Deployment Hooks
-----------------------------

Each operation that writes key, certificate, or related files have optional hooks that can call user-specified programs to
assist in deploying resources to remote servers or coordinating with other tooling.


Certificate Installation Verification
-------------------------------------

This tool can automatically connect to configured servers and verify that the generated certificates are properly served via TLS.
Additional checks are made for OSCP staples and optionally HPKP headers can be verified as well.


ACME Protocol V2 Support
------------------------

This tool supports services ACME V2 APIs.


Installation
============

Requires Python 3.8+ and OpenSSL support.

On Debian Stretch and later::

    sudo apt-get install python3-pip libssl-dev libffi-dev
    sudo pip3 install acmebot

You may want to create a virtual environment and install acmebot there.
Copy either the ``acmebot.example.json`` file or the ``acmebot.example.yaml`` file to ``acmebot.json`` (or ``acmebot.yaml``) and edit the configuration options.
The configuration file can be placed in the current directory that the tool is run from,
the /etc/acmebot directory,
or the same directory that the acmebot tool is installed in.

By default, debug level output will be written to a log file.
A configuration file for logrotate is provided in the logrotate.d directory,
you may want to copy, or create a link to this file in /etc/logrotate.d.

Note that when using dns-01 authorizations via a local DNS server,
this tool needs to be able to add, remove, and update DNS records.
This can be achieved by installing it on your master DNS server and using `bindtool`_ to manage the zone file,
or you can use a custom shell script to update the DNS records.

When using dns-01 authorizations via a remote server,
an update key allowing the creation and deletion of TXT and optionally TLSA record types is required.

Optional: some services require a full certificate chain including the root (OSCP stapling on Nginx, for example).
In order to generate these files,
place a copy of the root certificates from your certificate authority of choice in the same directory as the configuration file with the file names ``root_cert.rsa.pem`` and ``root_cert.ecdsa.pem`` for RSA and ECDSA certificate roots respectively.
Note that the root certificates are the those used to sign RSA and ECDSA client certificates,
and may not necessarily be of the same type,
e.g. Let's Encrypt currently signs ECDSA certificates with an RSA root.
If your certificate authority uses RSA certificate to sign ECDSA certificates types, place that RSA root certificate in ``root_cert.ecdsa.pem``.
The root certificate for Let's Encrypt can be obtained `here <https://letsencrypt.org/certificates/>`_.


Upgrade
=======

Starting with version 2.0.0 of this tool, the Let's Encrypt ACME V2 API is used by default.
When upgrading to version 2.0.0+, or otherwise changing API endpoints,
the client key is regenerated and a new registration is performed.
If running in master/follower mode, be sure to run the tool on the master first,
then copy the new client key and registration files to the followers before running on the followers.
Existing private keys and certificates may continue to be used.


Quick Start
===========


Basic Configuration
-------------------

While the example configuration file may appear complicated,
it is meant to show all possible configuration options and their defaults,
rather than demonstrate a basic simple configuration.

The only items that must be present in the configuration file to create and maintain a certificate are your account email address,
and the file name for the certificate.
By default, the common name of the certificate will be the same as the certificate file name.

For example::

    {
        "account": {
            "email": "admin@example.com"
        },
        "certificates": {
            "example.com": {
                "alt_names": {
                    "example.com": ["@", "www"]
                }
            }
        }
    }

will create a certificate named ``example.com``,
with the common name of ``example.com``,
and the subject alternative names of ``example.com`` and ``www.example.com``.

As many certificates as desired may be configured.
The number of alternative names is limited by the certificate authority (Let's Encrypt currently allows 100).
Alternative names are specified on a DNS zone basis,
multiple zones may be specified per certificate.
The host name ``"@"`` is used for the name of the zone itself.


Authorization Setup
-------------------

By default, the tool will attempt dns-01 domain authorizations for every alternative name specified,
using local DNS updates.
See the later sections on configuring `local <#configuring-local-dns-updates>`_ or `remote <#configuring-remote-dns-updates>`_ DNS updates.

To use http-01 authorizations instead,
configure the ``http_challenges`` section of the configuration file specifying a challenge directory for each fully qualified host name.

For example::

    {
        ...
        "http_challenges": {
            "example.com": "/var/www/htdocs/.well-known/acme-challenge",
            "www.example.com": "/var/www/htdocs/.well-known/acme-challenge"
        }
    }

See the `HTTP Challenges <#http-challenges>`_ section for more information.


First Run
---------

Once the configuration file is in place,
simply execute the tool.
For the first run you may wish to select detailed output to see exactly what the tool is doing::

    acmebot --detail

If all goes well,
the tool will generate a public/private key pair used for client authentication to the certificate authority,
register an account with the certificate authority,
prompt to accept the certificate authority's terms of service,
obtain authorizations for each configured domain name,
generate primary private keys as needed for the configured certificates,
issue certificates,
generate backup private keys,
generate custom Diffie-Hellman parameters,
retrieve Signed Certificate Timestamps from certificate transparency logs,
retrieve an OCSP response from the certificate authority,
and install the certificates and private keys into /etc/ssl/certs and /etc/ssl/private.

If desired, you can test the tool using Let's Encrypt's staging server.
To do this, specify the staging server's directory URL in the ``acme_directory_url`` setting.
See `Staging Environment <https://letsencrypt.org/docs/staging-environment/>`_ for details.
When switching from the staging to production servers,
you should delete the client key and registration files (/var/local/acmebot/\*.json) to ensure a fresh registration in the production environment.


File Location
=============

After a successful certificate issuance,
up to twenty one files will be created per certificate.

The locations for these files can be controlled via the ``directories`` section of the configuration file.
The default locations are used here for brevity.

Output files will be written as a single transaction,
either all files will be written,
or no files will be written.
This is designed to prevent a mismatch between certificates and private keys should an error happen during file creation.


Private Keys
------------

Two private key files will be created in /etc/ssl/private for each key type.
The primary: ``<private-key-name>.<key-type>.key``; and a backup key: ``<private-key-name>_backup.<key-type>.key``.

The private key files will be written in PEM format and will be readable by owner and group.


Certificate Files
-----------------

Two certificate files will be created for each key type,
one in /etc/ssl/certs, named ``<certificate-name>.<key-type>.pem``,
containing the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by custom Diffie-Hellman and elliptic curve paramaters;
the second file will be created in /etc/ssl/private, named ``<certificate-name>_full.<key-type>.key``,
and will contain the private key,
followed by the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by custom Diffie-Hellman and elliptic curve paramaters.

The ``<certificate-name>_full.<key-type>.key`` file is useful for services that require both the private key and certificate to be in the same file,
such as ZNC.


Intermediate Certificate Chain File
-----------------------------------

If the certificate authority uses intermediate certificates to sign your certificates,
a file will be created in /etc/ssl/certs, named ``<certificate-name>_chain.<key-type>.pem`` for each key type,
containing the intermediate certificates sent by the certificate authority.

This file will not be created if the ``chain`` directory is set to ``null``.

Note that the certificate authority may use a different type of certificate as intermediates,
e.g. an ECDSA client certificate may be signed by an RSA intermediate,
and therefore the intermediate certificate key type may not match the file name (or certificate type).


Full Chain Certificate File
---------------------------

If the ``root_cert.<key-type>.pem`` file is present (see `Installation <#installation>`_),
then an additional certificate file will be generated in /etc/ssl/certs,
named ``<certificate-name>+root.<key-type>.pem`` for each key type.
This file will contain the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by the root certificate,
followed by custom Diffie-Hellman and elliptic curve paramaters.

If the ``root_cert.<key-type>.pem`` file is not found in the same directory as the configuration file,
this certificate file will not be created.

This file is useful for configuring OSCP stapling on Nginx servers.


Diffie-Hellman Parameter File
-----------------------------

If custom Diffie-Hellman parameters or a custom elliptical curve are configured,
a file will be created in /etc/ssl/params, named ``<certificate-name>_param.pem``,
containing the Diffie-Hellman parameters and elliptical curve paramaters.

This file will not be created if the ``param`` directory is set to ``null``.


Hypertext Public Key Pin (HPKP) Files
-------------------------------------

Two additional files will be created in /etc/ssl/hpkp, named ``<private-key-name>.apache`` and ``<private-key-name>.nginx``.
These files contain HTTP header directives setting HPKP for both the primary and backup private keys for each key type.

Each file is suitable to be included in the server configuration for either Apache or Nginx respectively.

Thess files will not be created if the ``hpkp`` directory is set to ``null``.


Signed Certificate Timestamp (SCT) Files
----------------------------------------

One additional file will be created for each key type and configured certificate transparency log in ``/etc/ssl/scts/<certificate-name>/<key-type>/<log-name>.sct``.
These files contain SCT information in binary form suitable to be included in a TLS extension.
By default, SCTs will be retrieved from the Google Icarus and Google Pilot certificate transparency logs.
The Google Test Tube certificate transparency log can be used with the Let's Encrypt staging environment for testing.


OCSP Response Files
-------------------
One OCSP response file will be created for each key type,
in /etc/ssl/ocsp, named ``<certificate-name>.<key_type>.ocsp``.
These files contain OCSP responses in binary form suitable to be used as stapled OCSP responses.


Archive Directory
-----------------

Whenever exsiting files are replaced by subsequent runs of the tool,
for example during certificate renewal or private key rollover,
all existing files are preserved in the archive directory, /etc/ssl/archive.

Within the archive directory,
a directory will be created with the name of the private key,
containing a datestamped directory with the time of the file transaction (YYYY_MM_DD_HHMMSS).
All existing files will be moved into the datestamped directory should they need to be recovered.


Server Configuration
====================

Because certificate files will be periodically replaced as certificates need to be renewed,
it is best to have your server configurations simply refer to the certificate and key files in the locations they are created.
This will prevent server configurations from having to be updated as certificate files are replaced.

If the server requires the certificate or key file to be in a particular location or have a different file name,
it is best to simply create a soft link to the certificate or key file rather than rename or copy the files.

Another good practice it to isolate the configuration for each certificate into a snippet file,
for example using Apache,
create the file /etc/apache2/snippets/ssl/example.com containing::

    SSLCertificateFile    /etc/ssl/certs/example.com.rsa.pem
    SSLCertificateKeyFile /etc/ssl/private/example.com.rsa.key
    CTStaticSCTs          /etc/ssl/certs/example.com.rsa.pem /etc/ssl/scts/example.com/rsa        # requires mod_ssl_ct to be installed

    SSLCertificateFile    /etc/ssl/certs/example.com.ecdsa.pem
    SSLCertificateKeyFile /etc/ssl/private/example.com.ecdsa.key
    CTStaticSCTs          /etc/ssl/certs/example.com.ecdsa.pem /etc/ssl/scts/example.com/ecdsa    # requires mod_ssl_ct to be installed

    Header always set Strict-Transport-Security "max-age=63072000"
    Include /etc/ssl/hpkp/example.com.apache

and then in each host configuration using that certificate, simply add::

    Include snippets/ssl/example.com

For Nginx the /etc/nginx/snippets/ssl/example.com file would contain::

    ssl_ct on;                                                          # requires nginx-ct module to be installed

    ssl_certificate         /etc/ssl/certs/example.com.rsa.pem;
    ssl_certificate_key     /etc/ssl/private/example.com.rsa.key;
    ssl_ct_static_scts      /etc/ssl/scts/example.com/rsa;              # requires nginx-ct module to be installed
    ssl_stapling_file       /etc/ssl/ocsp/example.com.rsa.ocsp;

    ssl_certificate         /etc/ssl/certs/example.com.ecdsa.pem;       # requires nginx 1.11.0+ to use multiple certificates
    ssl_certificate_key     /etc/ssl/private/example.com.ecdsa.key;
    ssl_ct_static_scts      /etc/ssl/scts/example.com/ecdsa;            # requires nginx-ct module to be installed
    ssl_stapling_file       /etc/ssl/ocsp/example.com.ecdsa.ocsp;       # requires nginx 1.13.3+ to use with multiple certificates

    ssl_trusted_certificate /etc/ssl/certs/example.com+root.rsa.pem;    # not required if using ssl_stapling_file

    ssl_dhparam             /etc/ssl/params/example.com_param.pem;
    ssl_ecdh_curve secp384r1;

    add_header Strict-Transport-Security "max-age=63072000" always;
    include /etc/ssl/hpkp/example.com.nginx;

and can be used via::

    include snippets/ssl/example.com;


Configuration
=============

The configuration file ``acmebot.json`` or ``acmebot.yaml`` may be placed in the current working directory,
in /etc/acmebot,
or in the same directory as the acmebot tool is installed in.
A different configuration file name may be specified on the command line.
If the specified file name is not an absolute path,
it will be searched for in the same locations,
e.g. ``acmebot --config config.json`` will load ``./config.json``, ``/etc/acmebot/config.json``, or ``<install-dir>/config.json``.
If the file extension is omitted, the tool will search for a file with the extensions: ``.json``, ``.yaml``, and ``.yml`` in each location.
If the speficied file is an absolute path,
only that location will be searched.

Additional configuration files may be placed in a subdirectory named ``conf.d`` in the same directory as the configuration file.
All files with the extensions: ``.json``, ``.yaml``, or ``.yml`` in that subdirectory will be loaded and merged into the configuration,
overriding any settings in the main configuration file.
For example,
the configurtaion for each certificate may be placed in a separate file,
while the common settings remain in the main configuration file.

The configuration file must adhere to standard JSON or YAML formats.
The examples given in this document are in JSON format, however, the equivalent structures may be expressed in YAML.

The files ``acmebot.example.json`` and ``acmebot.example.yaml`` provide a template of all configuration options and their default values.
Entries inside angle brackets ``"<example>"`` must be replaced (without the angle brackets),
all other values may be removed unless you want to override the default values.


Account
-------

Enter the email address you wish to associate with your account on the certificate authority.
This email address may be useful in recovering your account should you lose access to your client key.

Example::

    {
        "account": {
            "email": "admin@example.com"
        },
        ...
    }


Settings
--------

Various settings for the tool.
All of these need only be present when the desired value is different from the default.

* ``follower_mode`` specifies if the tool should run in master or follower mode.
  The defalt value is ``false`` (master mode).
  The master will obtain authorizations and issue certificates,
  a follower will not attempt to obtain authorizations but can issue certificates.
* ``log_level`` specifies the amount of information written into the log file.
  Possible values are ``null``, ``"normal"``, ``"verbose"``, ``"debug"``, and ``"detail"``.
  ``"verbose"``, ``"debug"``, and ``"detail"`` settings correlate to the ``--verbose``, ``--debug`` and ``--detail`` command-line options.
* ``color_output`` specifies if the output should be colorized.
  Colorized output will be suppressed on non-tty devices.
  This option may be overridden via command line options.
  The default value is ``true``.
* ``key_types`` specifies the types of private keys to generate by default.
  The default value is ``['rsa', 'ecdsa']``.
* ``key_size`` specifies the size (in bits) for RSA private keys.
  The default value is ``4096``.
  RSA certificates can be turned off by setting this value to ``0`` or ``null``.
* ``key_curve`` specifies the curve to use for ECDSA private keys.
  The default value is ``"secp384r1"``.
  Available curves are ``"secp256r1"``, ``"secp384r1"``, and ``"secp521r1"``.
  ECDSA certificates can be turned off by setting this value to ``null``.
* ``key_cipher`` specifies the cipher algorithm used to encrypt private keys.
  The default value is ``"blowfish"``.
  Available ciphers are those accepted by your version of OpenSSL's EVP_get_cipherbyname().
* ``key_passphrase`` specifies the passphrase used to encrypt private keys.
  The default value is ``null``.
  A value of ``null`` or ``false`` will result in private keys being written unencrypted.
  A value of ``true`` will cause the password to be read from the command line, the environment, a prompt, or stdin.
  A string value will be used as the passphrase without further input.
* ``key_provided`` specifies that the private keys are provided from an external source and the tool should not modify them.
  The default value is ``false``.
* ``dhparam_size`` specifies the size (in bits) for custom Diffie-Hellman parameters.
  The default value is ``2048``.
  Custom Diffie-Hellman parameters can be turned off by setting this value to ``0`` or ``null``.
  This value should be at least be equal to half the ``key_size``.
* ``ecparam_curve`` speficies the curve or list of curves to use for ECDHE negotiation.
  This value may be a string or a list of strings.
  The default value is ``["secp521r1", "secp384r1", "secp256k1"]``.
  Custom EC parameters can be turned off by setting this value to ``null``.
  You can run ``openssl ecparam -list_curves`` to find a list of available curves.
* ``file_user`` specifies the name of the user that will own certificate and private key files.
  The default value is ``"root"``.
  Note that this tool must run as root, or another user that has rights to set the file ownership to this user.
* ``file_group`` speficies the name of the group that will own certificate and private key files.
  The default value is ``"ssl-cert"``.
  Note that this tool must run as root, or another user that has rights to set the file ownership to this group.
* ``log_user`` specifies the name of the user that will own log files.
  The default value is ``"root"``.
  Note that this tool must run as root, or another user that has rights to set the file ownership to this user.
* ``log_group`` speficies the name of the group that will own log files.
  The default value is ``"adm"``.
  Note that this tool must run as root, or another user that has rights to set the file ownership to this group.
* ``warning_exit_code`` specifies if warnings will produce a non-zero exit code.
  The default value is ``false``.
* ``hpkp_days`` specifies the number of days that HPKP pins should be cached for.
  The default value is ``60``.
  HPKP pin files can be turned off by setting this value to ``0`` or ``null``.
* ``pin_subdomains`` specifies whether the ``includeSubdomains`` directive should be included in the HPKP headers.
  The default value is ``true``.
* ``hpkp_report_uri`` specifies the uri to report HPKP failures to.
  The default value is ``null``.
  If not null, the ``report-uri`` directive will be included in the HPKP headers.
* ``ocsp_must_staple`` specifies if the OCSP Must-Staple extension is added to certificates.
  The default value is ``false``.
* ``ocsp_responder_urls`` specifies the list of OCSP responders to use if a certificate doesn't provide them.
  The default value is ``["http://ocsp.int-x3.letsencrypt.org"]``.
* ``ct_submit_logs`` specifies the list of certificate transparency logs to submit certificates to.
  The default value is ``["google_icarus", "google_pilot"]``.
  The value ``["google_testtube"]`` can be used with the Let's Encrypt staging environment for testing.
* ``renewal_days`` specifies the number of days before expiration when the tool will attempt to renew a certificate.
  The default value is ``30``.
* ``expiration_days`` specifies the number of days that private keys should be used for.
  The dafault value is ``730`` (two years).
  When the backup key reaches this age,
  the tool will notify the user that a key rollover should be performed,
  or automatically rollover the private key if ``auto_rollover`` is set to ``true``.
  Automatic rollover and expiration notices can be disabled by setting this to ``0`` or ``null``.
* ``auto_rollover`` specifies if the tool should automatically rollover private keys that have expired.
  The default value is ``false``.
  Note that when running in a master/follower configuration and sharing private keys between the master and follower,
  key rollovers must be performed on the master and manually transferred to the follower,
  therefore automatic rollovers should not be used unless running stand-alone.
* ``max_dns_lookup_attempts`` specifies the number of times to check for deployed DNS records before attempting authorizations.
  The default value is ``60``.
* ``dns_lookup_delay`` specifies the number of seconds to wait between DNS lookups.
  The default value is ``10``.
* ``max_domains_per_order`` specifies the maximum number of domains allowed per authorization order.
  The default value is ``100``, which is the limit set by Let's Encrypt.
* ``max_authorization_attempts`` specifies the number of times to check for completed authorizations.
  The default value is ``30``.
* ``authorization_delay`` specifies the number of seconds to wait between authorization checks.
  The default value is ``10``.
* ``cert_poll_time`` specifies the number of seconds to wait for a certificate to be issued.
  The default value is ``30``.
* ``max_ocsp_verify_attempts`` specifies the number of times to check for OCSP staples during verification.
  Retries will only happen when the certificate has the OCSP Must-Staple extension.
  The default value is ``10``.
* ``ocsp_verify_retry_delay`` specifies the number of seconds to wait between OCSP staple verification attempts.
  The default value is ``5``.
* ``min_run_delay`` specifies the minimum number of seconds to wait if the ``--randomwait`` command line option is present.
  The default value is ``300``.
* ``max_run_delay`` specifies the maximum number of seconds to wait if the ``--randomwait`` command line option is present.
  The default value is ``3600``.
* ``acme_directory_url`` specifies the primary URL for the ACME service.
  The default value is ``"https://acme-v02.api.letsencrypt.org/directory"``, the Let's Encrypt production API.
  You can substitute the URL for Let's Encrypt's staging environment or another certificate authority.
* ``acme_directory_verify_ssl`` specifies whether or not to verify the certificate of the ACME service.
  The default value is ``True``.
  Setting this to ``False`` is not recommneded, but may be necessary in environments using a private ACME server.
* ``reload_zone_command`` specifies the command to execute to reload local DNS zone information.
  When using `bindtool`_ the ``"reload-zone.sh"`` script provides this service.
  If not using local DNS updates, you may set this to ``null`` to avoid warnings.
* ``nsupdate_command`` specifies the command to perform DNS updates.
  The default value is ``"/usr/bin/nsupdate"``.
* ``verify`` specifies the default ports to perform installation verification on.
  The default value is ``null``.
* ``services`` specifies the default services to associate with certificates.
  The default value is ``null``.

Example::

    {
        ...
        "settings": {
            "follower_mode": false,
            "log_level": "debug",
            "key_size": 4096,
            "key_curve": "secp384r1",
            "key_cipher": "blowfish",
            "key_passphrase": null,
            "key_provided": false,
            "dhparam_size": 2048,
            "ecparam_curve": ["secp521r1", "secp384r1", "secp256k1"],
            "file_user": "root",
            "file_group": "ssl-cert",
            "hpkp_days": 60,
            "pin_subdomains": true,
            "hpkp_report_uri": null,
            "ocsp_must_staple": false,
            "ocsp_responder_urls": ["http://ocsp.int-x3.letsencrypt.org"],
            "ct_submit_logs": ["google_icarus", "google_pilot"],
            "renewal_days": 30,
            "expiration_days": 730,
            "auto_rollover": false,
            "max_dns_lookup_attempts": 60,
            "dns_lookup_delay": 10,
            "max_authorization_attempts": 30,
            "authorization_delay": 10,
            "min_run_delay": 300,
            "max_run_delay": 3600,
            "acme_directory_url": "https://acme-v02.api.letsencrypt.org/directory",
            "reload_zone_command": "/etc/bind/reload-zone.sh",
            "nsupdate_command": "/usr/bin/nsupdate",
            "verify": [443]
        },
        ...
    }


Directories
-----------

Directories used to store the input and output files of the tool.
Relative paths will be considered relative to the directory of configuration file.
All of these need only be present when the desired value is different from the default.

* ``pid`` specifies the directory to store a process ID file.
  The default value is ``"/var/run"``.
* ``log`` specifies the directory to store the log file.
  The default value is ``"/var/log/acmebot"``.
* ``resource`` specifies the directory to store the client key and registration files for the ACME account.
  The default value is ``"/var/local/acmebot"``.
* ``private_key`` specifies the directory to store primary private key files.
  The default value is ``"/etc/ssl/private"``.
* ``backup_key`` specifies the directory to store backup private key files.
  The default value is ``"/etc/ssl/private"``.
* ``previous_key`` specifies the directory to store previously used private key files after key rollover.
  The default value is ``null``.
* ``full_key`` specifies the directory to store primary private key files that include the certificate chain.
  The default value is ``"/etc/ssl/private"``.
  Full key files may be omitted by setting this to ``null``.
* ``certificate`` specifies the directory to store certificate files.
  The default value is ``"/etc/ssl/certs"``.
* ``full_certificate`` specifies the directory to store full chain certificate files that include the root certificate.
  The default value is ``"/etc/ssl/certs"``.
  Full certificate files may be omitted by setting this to ``null``.
* ``chain`` specifies the directory to store certificate intermediate chain files.
  The default value is ``"/etc/ssl/certs"``.
  Chain files may be omitted by setting this to ``null``.
* ``param`` specifies the directory to store Diffie-Hellman parameter files.
  The default value is ``"/etc/ssl/params"``.
  Paramater files may be omitted by setting this to ``null``.
* ``challenge`` specifies the directory to store ACME dns-01 challenge files.
  The default value is ``"/etc/ssl/challenge"``.
* ``http_challenge`` specifies the directory to store ACME http-01 challenge files.
  The default value is ``null``.
* ``hpkp`` specifies the directory to store HPKP header files.
  The default value is ``"/etc/ssl/hpkp"``.
  HPKP header files may be turned off by setting this to ``null``.
* ``sct`` specifies the directory to store Signed Certificate Timestamp files.
  The default value is ``"/etc/ssl/scts/<certificate-name>/<key-type>"``.
  SCT files may be turned off by setting this to ``null``.
* ``ocsp`` specifies the directory to store OCSP response files.
  The default value is ``"/etc/ssl/ocsp"``.
  OCSP response files may be turned off by setting this to ``null``.
* ``update_key`` specifies the directory to search for DNS update key files.
  The default value is ``"/etc/ssl/update_keys"``.
* ``archive`` specifies the directory to store older versions of files that are replaced by this tool.
  The default value is ``"/etc/ssl/archive"``.
* ``temp`` specifies the directory to write temporary files to.
  A value of ``null`` results in using the system defined temp directory.
  The temp directory must be on the same file system as the output file directories.
  The default value is ``null``.

Example::

    {
        ...
        "directories": {
            "pid": "/var/run",
            "log": "/var/log/acmebot",
            "resource": "/var/local/acmebot",
            "private_key": "/etc/ssl/private",
            "backup_key": "/etc/ssl/private",
            "full_key": "/etc/ssl/private",
            "certificate": "/etc/ssl/certs",
            "full_certificate": "/etc/ssl/certs",
            "chain": "/etc/ssl/certs",
            "param": "/etc/ssl/params",
            "challenge": "/etc/ssl/challenges",
            "http_challenge": "/var/www/{zone}/{host}/.well-known/acme-challenge",
            "hpkp": "/etc/ssl/hpkp",
            "ocsp": "/etc/ssl/ocsp/",
            "sct": "/etc/ssl/scts/{name}/{key_type}",
            "update_key": "/etc/ssl/update_keys",
            "archive": "/etc/ssl/archive"
        },
        ...
    }

Directory values are treated as Python format strings,
fields available for directories are: ``name``, ``key_type``, ``suffix``, ``server``.
The ``name`` field is the name of the private key or certificate.
The ``"http_challenge"`` directory uses the fields: ``zone``, ``host``, and ``fqdn``,
for the zone name, host name (without the zone), and the fully qualified domain name respectively.
The ``host`` value will be ``"."`` if the fqdn is the same as the zone name.


Services
--------

This specifies a list of services that are used by issued certificates and the commands necessary to restart or reload the service when a certificate is issued or changed.
You may add or remove services as needed.
The list of services is arbritrary and they are referenced from individual certificate definitions.

Example::

    {
        ...
        "services": {
            "apache": "systemctl reload apache2",
            "coturn": "systemctl restart coturn",
            "dovecot": "systemctl restart dovecot",
            "etherpad": "systemctl restart etherpad",
            "mysql": "systemctl reload mysql",
            "nginx": "systemctl reload nginx",
            "postfix": "systemctl reload postfix",
            "postgresql": "systemctl reload postgresql",
            "prosody": "systemctl restart prosody",
            "slapd": "systemctl restart slapd",
            "synapse": "systemctl restart matrix-synapse",
            "znc": "systemctl restart znc"
        },
        ...
    }

To specify one or more services used by a certificate,
add a ``services`` section to the certificate definition listing the services using that certificate.

For example::

    {
        "certificates": {
            "example.com": {
                "alt_names": {
                    "example.com": ["@", "www"]
                },
                "services": ["nginx"]
            }
        }
    }

This will cause the command ``"systemctl reload nginx"`` to be executed any time the certificate ``example.com`` is issued, renewed, or updated.


Certificates
------------

This section defines the set of certificates to issue and maintain.
The name of each certificate is used as the name of the certificate files.

* ``common_name`` specifies the common name for the certificate.
  If omitted, the name of the certificate will be used.
* ``alt_names`` specifies the set of subject alternative names for the certificate.
  If specified, the common name of the certificate must be included as one of the alternative names.
  The alternative names are specified as a list of host names per DNS zone,
  so that associated DNS updates happen in the correct zone.
  The zone name may be used directly by specifying ``"@"`` for the host name.
  Multiple zones may be specified.
  The default value is the common name of the certificate in the zone of the first registered domain name