{"id":22114020,"url":"https://github.com/plinss/acmebot","last_synced_at":"2025-04-10T01:13:54.825Z","repository":{"id":54489999,"uuid":"77644155","full_name":"plinss/acmebot","owner":"plinss","description":"Certificate manager bot using ACME protocol","archived":false,"fork":false,"pushed_at":"2024-04-14T00:22:41.000Z","size":992,"stargazers_count":116,"open_issues_count":17,"forks_count":20,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-10T01:13:48.811Z","etag":null,"topics":["acme","issue-certificates","letsencrypt","tlsa-records"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plinss.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-29T22:40:28.000Z","updated_at":"2025-03-27T19:18:25.000Z","dependencies_parsed_at":"2023-01-28T14:00:45.134Z","dependency_job_id":"9e1b0750-97e2-49a8-9cf5-c7279cd2a2ed","html_url":"https://github.com/plinss/acmebot","commit_stats":{"total_commits":199,"total_committers":4,"mean_commits":49.75,"dds":"0.025125628140703515","last_synced_commit":"a736f9de67c3b825b2f38faa0a6e146367d430e6"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plinss%2Facmebot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plinss%2Facmebot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plinss%2Facmebot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plinss%2Facmebot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plinss","download_url":"https://codeload.github.com/plinss/acmebot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137891,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acme","issue-certificates","letsencrypt","tlsa-records"],"created_at":"2024-12-01T11:08:21.589Z","updated_at":"2025-04-10T01:13:54.768Z","avatar_url":"https://github.com/plinss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. _bindtool: https://github.com/plinss/bindtool\n\n*******\nacmebot\n*******\n\nACME protocol automatic certitificate manager.\n\nThis tool acquires and maintains certificates from a certificate authority using the ACME protocol, similar to EFF's Certbot.\nWhile developed and tested using Let's Encrypt, the tool should work with any certificate authority using the ACME protocol.\n\n\nFeatures\n========\n\nThis tool is not intended as a replacement for Certbot and does not attempt to replicate all of Certbot's functionality,\nnotably it does not modify configuration files of other services,\nor provide a server to perform stand-alone domain validation.\nIt does however, do a few things that Certbot does not,\nsimplifying certificate management in more advanced environments.\nIn addition to automatically issuing and maintaining certificates,\nthe tool can also maintain associated HPKP headers and TLSA (DANE) records.\n\n\nMaster/Follower Mode\n--------------------\n\nThis tool separates the authorization (domain validation) and certificate issuance processes allowing one machine to maintain authorizations (the master),\nwhile another machine issues certificates (the follower).\nThis is useful for situations where an isolated server is providing a service, such as XMPP,\nbehind a firewall and does not have the ability to perform authorizations over http or configure DNS records,\nbut still needs to obtain and periodically renew one or more certificates.\n\n\nSharing of Private Keys Between Certificates\n--------------------------------------------\n\nThis tool allows multiple certificates to be defined using the same public/private key pair.\n\nWhen deploying Hypertext Puplic Key Pinning (HPKP), you can optionally use the same pins to secure subdomains.\nThis increases security of the site because a visitor to a root domain will have previously obtained pins for subdomains,\nreducing the possibility of a man-in-the-middle attacker installing a false pin on first visit.\n\nThis practice obviously requires the use of the same public/private key pair for the domain and all subdomains.\nHowever, it may not be desirable to use the same certificate for all subdomains, for example,\nexposing the full list of subdomains in the alternative names of the root domain's certificate,\nor reissuing the root domain's certificate every time a subdomain is added or removed.\n\n\nHypertext Public Key Pin (HPKP) Support\n---------------------------------------\n\nThis tool automatically generates and maintains HPKP header information suitable to be directly included in server configuraton files.\nSupport for Apache and Nginx are provided by default, other servers may be added by the user.\n\n\nAutomatic Management of Backup Private Keys\n-------------------------------------------\n\nUsing HPKP requires a second public key to provide a backup when private keys are changed.\nThis tool automatically generates backup keys and switches to the pre-generated backup key when rolling over private keys.\nRolling over private keys can be done automatically and is scheduled independently of certificate expiration.\nPrivate key rollover is prevented in cases where insufficient time has passed to distribute backup HPKP pins.\n\n\nParallel RSA and ECDSA Certificates\n-----------------------------------\n\nThis tool can generate both RSA and ECDSA certificates.\nBy default it will generate and maintain both types of certificates in parallel.\n\n\nCertificate Transparency / Signed Certificate Timestamp Support\n---------------------------------------------------------------\n\nThis tool can automatically register your certificates with multiple certificate transparency logs and retrieve Signed Certificate Timestamps (SCTs) for each.\nThe retrieved SCTs are suitable to be deilvered via a TLS extension,\nSCT TLS extension modules are available for `Apache \u003chttps://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html\u003e`_ and `Nginx \u003chttps://github.com/grahamedgecombe/nginx-ct\u003e`_.\n\n\nOCSP Response File Support\n--------------------------\n\nThis tool automatically obtains and maintains OCSP response files for each configured certificate.\nThese files may be used to serve stapled OCSP responses from your server without relying on the server's OCSP stapling mechanisms.\nSome servers, such as Nginx, obtain stapled OCSP responses lazily and cache the response in memory.\nWhen using the OCSP Must-Staple extension this can result in your server being unreachable until the OCSP response is refreshed,\nduring OCSP responder outages, this can be a significant interval.\nUsing OCSP responses from disk will alleviate this issue.\nOnly OCSP responses with a \"good\" status will be stored.\n\n\nEncrypted Private Keys\n----------------------\n\nPrimary and backup private keys can optionally be encrypted using a passphrase and cipher of your choice.\n\n\nMixed Use of DNS and HTTP Authorization\n---------------------------------------\n\nBy default this tool performs dns-01 authorizartions for domain validation.\nIt is possible to configure overrides for specific domains names to use http-01 authorization instead.\nThis is useful for situations where a domain outside your immediate control has provided an alias to your web site.\n\n\nAutomatic Local or Remote DNS Updates\n-------------------------------------\n\nThis tool can automatically add and remove DNS records for dns-01 authorizations as well as TLSA records.\nUpdates to a local server can be made via an external zone file processor, such as `bindtool`_,\nor to a remote DNS server via RFC 2136 dynamic DNS updates using ``nsupdate``.\nThe choice between local and remote DNS updates can be made on a zone by zone basis.\n\n\nConfigurable Output File Names\n------------------------------\n\nServer administrators often develop their own file naming conventions or need to match naming conventions of other tools.\nThe names and output directories of all certificate, key, and related files are fully configurable.\nThe defaults are intended for standard Debian installations.\n\n\nConfigurable Deployment Hooks\n-----------------------------\n\nEach operation that writes key, certificate, or related files have optional hooks that can call user-specified programs to\nassist in deploying resources to remote servers or coordinating with other tooling.\n\n\nCertificate Installation Verification\n-------------------------------------\n\nThis tool can automatically connect to configured servers and verify that the generated certificates are properly served via TLS.\nAdditional checks are made for OSCP staples and optionally HPKP headers can be verified as well.\n\n\nACME Protocol V1 and V2 Support\n-------------------------------\n\nThis tool supports services running both ACME V1 and ACME V2 APIs.\nWildcard certrificates may be issued when using the V2 API.\n\n\nInstallation\n============\n\nRequires Python 3.7+ and the OpenSSL support.\n\nOn Debian Stretch and later::\n\n    sudo apt-get install python3-pip libssl-dev libffi-dev\n    sudo pip3 install acmebot\n\nYou may want to create a virtual environment and install acmebot there.\nCopy either the ``acmebot.example.json`` file or the ``acmebot.example.yaml`` file to ``acmebot.json`` (or ``acmebot.yaml``) and edit the configuration options.\nThe configuration file can be placed in the current directory that the tool is run from,\nthe /etc/acmebot directory,\nor the same directory that the acmebot tool is installed in.\n\nBy default, debug level output will be written to a log file.\nA configuration file for logrotate is provided in the logrotate.d directory,\nyou may want to copy, or create a link to this file in /etc/logrotate.d.\n\nNote that when using dns-01 authorizations via a local DNS server,\nthis tool needs to be able to add, remove, and update DNS records.\nThis can be achieved by installing it on your master DNS server and using `bindtool`_ to manage the zone file,\nor you can use a custom shell script to update the DNS records.\n\nWhen using dns-01 authorizations via a remote server,\nan update key allowing the creation and deletion of TXT and optionally TLSA record types is required.\n\nOptional: some services require a full certificate chain including the root (OSCP stapling on Nginx, for example).\nIn order to generate these files,\nplace 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.\nNote that the root certificates are the those used to sign RSA and ECDSA client certificates,\nand may not necessarily be of the same type,\ne.g. Let's Encrypt currently signs ECDSA certificates with an RSA root.\nIf your certificate authority uses RSA certificate to sign ECDSA certificates types, place that RSA root certificate in ``root_cert.ecdsa.pem``.\nThe root certificate for Let's Encrypt can be obtained `here \u003chttps://letsencrypt.org/certificates/\u003e`_.\n\n\nUpgrade\n=======\n\nStarting with version 2.0.0 of this tool, the Let's Encrypt ACME V2 API is used by default.\nWhen upgrading to version 2.0.0+, or otherwise changing API endpoints,\nthe client key is regenerated and a new registration is performed.\nIf running in master/follower mode, be sure to run the tool on the master first,\nthen copy the new client key and registration files to the followers before running on the followers.\nExisting private keys and certificates may continue to be used.\n\n\nQuick Start\n===========\n\n\nBasic Configuration\n-------------------\n\nWhile the example configuration file may appear complicated,\nit is meant to show all possible configuration options and their defaults,\nrather than demonstrate a basic simple configuration.\n\nThe only items that must be present in the configuration file to create and maintain a certificate are your account email address,\nand the file name for the certificate.\nBy default, the common name of the certificate will be the same as the certificate file name.\n\nFor example::\n\n    {\n        \"account\": {\n            \"email\": \"admin@example.com\"\n        },\n        \"certificates\": {\n            \"example.com\": {\n                \"alt_names\": {\n                    \"example.com\": [\"@\", \"www\"]\n                }\n            }\n        }\n    }\n\nwill create a certificate named ``example.com``,\nwith the common name of ``example.com``,\nand the subject alternative names of ``example.com`` and ``www.example.com``.\n\nAs many certificates as desired may be configured.\nThe number of alternative names is limited by the certificate authority (Let's Encrypt currently allows 100).\nAlternative names are specified on a DNS zone basis,\nmultiple zones may be specified per certificate.\nThe host name ``\"@\"`` is used for the name of the zone itself.\n\n\nAuthorization Setup\n-------------------\n\nBy default, the tool will attempt dns-01 domain authorizations for every alternative name specified,\nusing local DNS updates.\nSee the later sections on configuring `local \u003c#configuring-local-dns-updates\u003e`_ or `remote \u003c#configuring-remote-dns-updates\u003e`_ DNS updates.\n\nTo use http-01 authorizations instead,\nconfigure the ``http_challenges`` section of the configuration file specifying a challenge directory for each fully qualified host name.\n\nFor example::\n\n    {\n        ...\n        \"http_challenges\": {\n            \"example.com\": \"/var/www/htdocs/.well-known/acme-challenge\",\n            \"www.example.com\": \"/var/www/htdocs/.well-known/acme-challenge\"\n        }\n    }\n\nSee the `HTTP Challenges \u003c#http-challenges\u003e`_ section for more information.\n\n\nFirst Run\n---------\n\nOnce the configuration file is in place,\nsimply execute the tool.\nFor the first run you may wish to select detailed output to see exactly what the tool is doing::\n\n    acmebot --detail\n\nIf all goes well,\nthe tool will generate a public/private key pair used for client authentication to the certificate authority,\nregister an account with the certificate authority,\nprompt to accept the certificate authority's terms of service,\nobtain authorizations for each configured domain name,\ngenerate primary private keys as needed for the configured certificates,\nissue certificates,\ngenerate backup private keys,\ngenerate custom Diffie-Hellman parameters,\nretrieve Signed Certificate Timestamps from certificate transparency logs,\nretrieve an OCSP response from the certificate authority,\nand install the certificates and private keys into /etc/ssl/certs and /etc/ssl/private.\n\nIf desired, you can test the tool using Let's Encrypt's staging server.\nTo do this, specify the staging server's directory URL in the ``acme_directory_url`` setting.\nSee `Staging Environment \u003chttps://letsencrypt.org/docs/staging-environment/\u003e`_ for details.\nWhen switching from the staging to production servers,\nyou should delete the client key and registration files (/var/local/acmebot/\\*.json) to ensure a fresh registration in the production environment.\n\n\nFile Location\n=============\n\nAfter a successful certificate issuance,\nup to twenty one files will be created per certificate.\n\nThe locations for these files can be controlled via the ``directories`` section of the configuration file.\nThe default locations are used here for brevity.\n\nOutput files will be written as a single transaction,\neither all files will be written,\nor no files will be written.\nThis is designed to prevent a mismatch between certificates and private keys should an error happen during file creation.\n\n\nPrivate Keys\n------------\n\nTwo private key files will be created in /etc/ssl/private for each key type.\nThe primary: ``\u003cprivate-key-name\u003e.\u003ckey-type\u003e.key``; and a backup key: ``\u003cprivate-key-name\u003e_backup.\u003ckey-type\u003e.key``.\n\nThe private key files will be written in PEM format and will be readable by owner and group.\n\n\nCertificate Files\n-----------------\n\nTwo certificate files will be created for each key type,\none in /etc/ssl/certs, named ``\u003ccertificate-name\u003e.\u003ckey-type\u003e.pem``,\ncontaining the certificate,\nfollowed by any intermediate certificates sent by the certificate authority,\nfollowed by custom Diffie-Hellman and elliptic curve paramaters;\nthe second file will be created in /etc/ssl/private, named ``\u003ccertificate-name\u003e_full.\u003ckey-type\u003e.key``,\nand will contain the private key,\nfollowed by the certificate,\nfollowed by any intermediate certificates sent by the certificate authority,\nfollowed by custom Diffie-Hellman and elliptic curve paramaters.\n\nThe ``\u003ccertificate-name\u003e_full.\u003ckey-type\u003e.key`` file is useful for services that require both the private key and certificate to be in the same file,\nsuch as ZNC.\n\n\nIntermediate Certificate Chain File\n-----------------------------------\n\nIf the certificate authority uses intermediate certificates to sign your certificates,\na file will be created in /etc/ssl/certs, named ``\u003ccertificate-name\u003e_chain.\u003ckey-type\u003e.pem`` for each key type,\ncontaining the intermediate certificates sent by the certificate authority.\n\nThis file will not be created if the ``chain`` directory is set to ``null``.\n\nNote that the certificate authority may use a different type of certificate as intermediates,\ne.g. an ECDSA client certificate may be signed by an RSA intermediate,\nand therefore the intermediate certificate key type may not match the file name (or certificate type).\n\n\nFull Chain Certificate File\n---------------------------\n\nIf the ``root_cert.\u003ckey-type\u003e.pem`` file is present (see `Installation \u003c#installation\u003e`_),\nthen an additional certificate file will be generated in /etc/ssl/certs,\nnamed ``\u003ccertificate-name\u003e+root.\u003ckey-type\u003e.pem`` for each key type.\nThis file will contain the certificate,\nfollowed by any intermediate certificates sent by the certificate authority,\nfollowed by the root certificate,\nfollowed by custom Diffie-Hellman and elliptic curve paramaters.\n\nIf the ``root_cert.\u003ckey-type\u003e.pem`` file is not found in the same directory as the configuration file,\nthis certificate file will not be created.\n\nThis file is useful for configuring OSCP stapling on Nginx servers.\n\n\nDiffie-Hellman Parameter File\n-----------------------------\n\nIf custom Diffie-Hellman parameters or a custom elliptical curve are configured,\na file will be created in /etc/ssl/params, named ``\u003ccertificate-name\u003e_param.pem``,\ncontaining the Diffie-Hellman parameters and elliptical curve paramaters.\n\nThis file will not be created if the ``param`` directory is set to ``null``.\n\n\nHypertext Public Key Pin (HPKP) Files\n-------------------------------------\n\nTwo additional files will be created in /etc/ssl/hpkp, named ``\u003cprivate-key-name\u003e.apache`` and ``\u003cprivate-key-name\u003e.nginx``.\nThese files contain HTTP header directives setting HPKP for both the primary and backup private keys for each key type.\n\nEach file is suitable to be included in the server configuration for either Apache or Nginx respectively.\n\nThess files will not be created if the ``hpkp`` directory is set to ``null``.\n\n\nSigned Certificate Timestamp (SCT) Files\n----------------------------------------\n\nOne additional file will be created for each key type and configured certificate transparency log in ``/etc/ssl/scts/\u003ccertificate-name\u003e/\u003ckey-type\u003e/\u003clog-name\u003e.sct``.\nThese files contain SCT information in binary form suitable to be included in a TLS extension.\nBy default, SCTs will be retrieved from the Google Icarus and Google Pilot certificate transparency logs.\nThe Google Test Tube certificate transparency log can be used with the Let's Encrypt staging environment for testing.\n\n\nOCSP Response Files\n-------------------\nOne OCSP response file will be created for each key type,\nin /etc/ssl/ocsp, named ``\u003ccertificate-name\u003e.\u003ckey_type\u003e.ocsp``.\nThese files contain OCSP responses in binary form suitable to be used as stapled OCSP responses.\n\n\nArchive Directory\n-----------------\n\nWhenever exsiting files are replaced by subsequent runs of the tool,\nfor example during certificate renewal or private key rollover,\nall existing files are preserved in the archive directory, /etc/ssl/archive.\n\nWithin the archive directory,\na directory will be created with the name of the private key,\ncontaining a datestamped directory with the time of the file transaction (YYYY_MM_DD_HHMMSS).\nAll existing files will be moved into the datestamped directory should they need to be recovered.\n\n\nServer Configuration\n====================\n\nBecause certificate files will be periodically replaced as certificates need to be renewed,\nit is best to have your server configurations simply refer to the certificate and key files in the locations they are created.\nThis will prevent server configurations from having to be updated as certificate files are replaced.\n\nIf the server requires the certificate or key file to be in a particular location or have a different file name,\nit is best to simply create a soft link to the certificate or key file rather than rename or copy the files.\n\nAnother good practice it to isolate the configuration for each certificate into a snippet file,\nfor example using Apache,\ncreate the file /etc/apache2/snippets/ssl/example.com containing::\n\n    SSLCertificateFile    /etc/ssl/certs/example.com.rsa.pem\n    SSLCertificateKeyFile /etc/ssl/private/example.com.rsa.key\n    CTStaticSCTs          /etc/ssl/certs/example.com.rsa.pem /etc/ssl/scts/example.com/rsa        # requires mod_ssl_ct to be installed\n\n    SSLCertificateFile    /etc/ssl/certs/example.com.ecdsa.pem\n    SSLCertificateKeyFile /etc/ssl/private/example.com.ecdsa.key\n    CTStaticSCTs          /etc/ssl/certs/example.com.ecdsa.pem /etc/ssl/scts/example.com/ecdsa    # requires mod_ssl_ct to be installed\n\n    Header always set Strict-Transport-Security \"max-age=63072000\"\n    Include /etc/ssl/hpkp/example.com.apache\n\nand then in each host configuration using that certificate, simply add::\n\n    Include snippets/ssl/example.com\n\nFor Nginx the /etc/nginx/snippets/ssl/example.com file would contain::\n\n    ssl_ct on;                                                          # requires nginx-ct module to be installed\n\n    ssl_certificate         /etc/ssl/certs/example.com.rsa.pem;\n    ssl_certificate_key     /etc/ssl/private/example.com.rsa.key;\n    ssl_ct_static_scts      /etc/ssl/scts/example.com/rsa;              # requires nginx-ct module to be installed\n    ssl_stapling_file       /etc/ssl/ocsp/example.com.rsa.ocsp;\n\n    ssl_certificate         /etc/ssl/certs/example.com.ecdsa.pem;       # requires nginx 1.11.0+ to use multiple certificates\n    ssl_certificate_key     /etc/ssl/private/example.com.ecdsa.key;\n    ssl_ct_static_scts      /etc/ssl/scts/example.com/ecdsa;            # requires nginx-ct module to be installed\n    ssl_stapling_file       /etc/ssl/ocsp/example.com.ecdsa.ocsp;       # requires nginx 1.13.3+ to use with multiple certificates\n\n    ssl_trusted_certificate /etc/ssl/certs/example.com+root.rsa.pem;    # not required if using ssl_stapling_file\n\n    ssl_dhparam             /etc/ssl/params/example.com_param.pem;\n    ssl_ecdh_curve secp384r1;\n\n    add_header Strict-Transport-Security \"max-age=63072000\" always;\n    include /etc/ssl/hpkp/example.com.nginx;\n\nand can be used via::\n\n    include snippets/ssl/example.com;\n\n\nConfiguration\n=============\n\nThe configuration file ``acmebot.json`` or ``acmebot.yaml`` may be placed in the current working directory,\nin /etc/acmebot,\nor in the same directory as the acmebot tool is installed in.\nA different configuration file name may be specified on the command line.\nIf the specified file name is not an absolute path,\nit will be searched for in the same locations,\ne.g. ``acmebot --config config.json`` will load ``./config.json``, ``/etc/acmebot/config.json``, or ``\u003cinstall-dir\u003e/config.json``.\nIf the file extension is omitted, the tool will search for a file with the extensions: ``.json``, ``.yaml``, and ``.yml`` in each location.\nIf the speficied file is an absolute path,\nonly that location will be searched.\n\nAdditional configuration files may be placed in a subdirectory named ``conf.d`` in the same directory as the configuration file.\nAll files with the extensions: ``.json``, ``.yaml``, or ``.yml`` in that subdirectory will be loaded and merged into the configuration,\noverriding any settings in the main configuration file.\nFor example,\nthe configurtaion for each certificate may be placed in a separate file,\nwhile the common settings remain in the main configuration file.\n\nThe configuration file must adhere to standard JSON or YAML formats.\nThe examples given in this document are in JSON format, however, the equivalent structures may be expressed in YAML.\n\nThe files ``acmebot.example.json`` and ``acmebot.example.yaml`` provide a template of all configuration options and their default values.\nEntries inside angle brackets ``\"\u003cexample\u003e\"`` must be replaced (without the angle brackets),\nall other values may be removed unless you want to override the default values.\n\n\nAccount\n-------\n\nEnter the email address you wish to associate with your account on the certificate authority.\nThis email address may be useful in recovering your account should you lose access to your client key.\n\nExample::\n\n    {\n        \"account\": {\n            \"email\": \"admin@example.com\"\n        },\n        ...\n    }\n\n\nSettings\n--------\n\nVarious settings for the tool.\nAll of these need only be present when the desired value is different from the default.\n\n* ``follower_mode`` specifies if the tool should run in master or follower mode.\n  The defalt value is ``false`` (master mode).\n  The master will obtain authorizations and issue certificates,\n  a follower will not attempt to obtain authorizations but can issue certificates.\n* ``log_level`` specifies the amount of information written into the log file.\n  Possible values are ``null``, ``\"normal\"``, ``\"verbose\"``, ``\"debug\"``, and ``\"detail\"``.\n  ``\"verbose\"``, ``\"debug\"``, and ``\"detail\"`` settings correlate to the ``--verbose``, ``--debug`` and ``--detail`` command-line options.\n* ``color_output`` specifies if the output should be colorized.\n  Colorized output will be suppressed on non-tty devices.\n  This option may be overridden via command line options.\n  The default value is ``true``.\n* ``key_types`` specifies the types of private keys to generate by default.\n  The default value is ``['rsa', 'ecdsa']``.\n* ``key_size`` specifies the size (in bits) for RSA private keys.\n  The default value is ``4096``.\n  RSA certificates can be turned off by setting this value to ``0`` or ``null``.\n* ``key_curve`` specifies the curve to use for ECDSA private keys.\n  The default value is ``\"secp384r1\"``.\n  Available curves are ``\"secp256r1\"``, ``\"secp384r1\"``, and ``\"secp521r1\"``.\n  ECDSA certificates can be turned off by setting this value to ``null``.\n* ``key_cipher`` specifies the cipher algorithm used to encrypt private keys.\n  The default value is ``\"blowfish\"``.\n  Available ciphers are those accepted by your version of OpenSSL's EVP_get_cipherbyname().\n* ``key_passphrase`` specifies the passphrase used to encrypt private keys.\n  The default value is ``null``.\n  A value of ``null`` or ``false`` will result in private keys being written unencrypted.\n  A value of ``true`` will cause the password to be read from the command line, the environment, a prompt, or stdin.\n  A string value will be used as the passphrase without further input.\n* ``key_provided`` specifies that the private keys are provided from an external source and the tool should not modify them.\n  The default value is ``false``.\n* ``dhparam_size`` specifies the size (in bits) for custom Diffie-Hellman parameters.\n  The default value is ``2048``.\n  Custom Diffie-Hellman parameters can be turned off by setting this value to ``0`` or ``null``.\n  This value should be at least be equal to half the ``key_size``.\n* ``ecparam_curve`` speficies the curve or list of curves to use for ECDHE negotiation.\n  This value may be a string or a list of strings.\n  The default value is ``[\"secp521r1\", \"secp384r1\", \"secp256k1\"]``.\n  Custom EC parameters can be turned off by setting this value to ``null``.\n  You can run ``openssl ecparam -list_curves`` to find a list of available curves.\n* ``file_user`` specifies the name of the user that will own certificate and private key files.\n  The default value is ``\"root\"``.\n  Note that this tool must run as root, or another user that has rights to set the file ownership to this user.\n* ``file_group`` speficies the name of the group that will own certificate and private key files.\n  The default value is ``\"ssl-cert\"``.\n  Note that this tool must run as root, or another user that has rights to set the file ownership to this group.\n* ``log_user`` specifies the name of the user that will own log files.\n  The default value is ``\"root\"``.\n  Note that this tool must run as root, or another user that has rights to set the file ownership to this user.\n* ``log_group`` speficies the name of the group that will own log files.\n  The default value is ``\"adm\"``.\n  Note that this tool must run as root, or another user that has rights to set the file ownership to this group.\n* ``warning_exit_code`` specifies if warnings will produce a non-zero exit code.\n  The default value is ``false``.\n* ``hpkp_days`` specifies the number of days that HPKP pins should be cached for.\n  The default value is ``60``.\n  HPKP pin files can be turned off by setting this value to ``0`` or ``null``.\n* ``pin_subdomains`` specifies whether the ``includeSubdomains`` directive should be included in the HPKP headers.\n  The default value is ``true``.\n* ``hpkp_report_uri`` specifies the uri to report HPKP failures to.\n  The default value is ``null``.\n  If not null, the ``report-uri`` directive will be included in the HPKP headers.\n* ``ocsp_must_staple`` specifies if the OCSP Must-Staple extension is added to certificates.\n  The default value is ``false``.\n* ``ocsp_responder_urls`` specifies the list of OCSP responders to use if a certificate doesn't provide them.\n  The default value is ``[\"http://ocsp.int-x3.letsencrypt.org\"]``.\n* ``ct_submit_logs`` specifies the list of certificate transparency logs to submit certificates to.\n  The default value is ``[\"google_icarus\", \"google_pilot\"]``.\n  The value ``[\"google_testtube\"]`` can be used with the Let's Encrypt staging environment for testing.\n* ``renewal_days`` specifies the number of days before expiration when the tool will attempt to renew a certificate.\n  The default value is ``30``.\n* ``expiration_days`` specifies the number of days that private keys should be used for.\n  The dafault value is ``730`` (two years).\n  When the backup key reaches this age,\n  the tool will notify the user that a key rollover should be performed,\n  or automatically rollover the private key if ``auto_rollover`` is set to ``true``.\n  Automatic rollover and expiration notices can be disabled by setting this to ``0`` or ``null``.\n* ``auto_rollover`` specifies if the tool should automatically rollover private keys that have expired.\n  The default value is ``false``.\n  Note that when running in a master/follower configuration and sharing private keys between the master and follower,\n  key rollovers must be performed on the master and manually transferred to the follower,\n  therefore automatic rollovers should not be used unless running stand-alone.\n* ``max_dns_lookup_attempts`` specifies the number of times to check for deployed DNS records before attempting authorizations.\n  The default value is ``60``.\n* ``dns_lookup_delay`` specifies the number of seconds to wait between DNS lookups.\n  The default value is ``10``.\n* ``max_domains_per_order`` specifies the maximum number of domains allowed per authorization order.\n  The default value is ``100``, which is the limit set by Let's Encrypt.\n* ``max_authorization_attempts`` specifies the number of times to check for completed authorizations.\n  The default value is ``30``.\n* ``authorization_delay`` specifies the number of seconds to wait between authorization checks.\n  The default value is ``10``.\n* ``cert_poll_time`` specifies the number of seconds to wait for a certificate to be issued.\n  The default value is ``30``.\n* ``max_ocsp_verify_attempts`` specifies the number of times to check for OCSP staples during verification.\n  Retries will only happen when the certificate has the OCSP Must-Staple extension.\n  The default value is ``10``.\n* ``ocsp_verify_retry_delay`` specifies the number of seconds to wait between OCSP staple verification attempts.\n  The default value is ``5``.\n* ``min_run_delay`` specifies the minimum number of seconds to wait if the ``--randomwait`` command line option is present.\n  The default value is ``300``.\n* ``max_run_delay`` specifies the maximum number of seconds to wait if the ``--randomwait`` command line option is present.\n  The default value is ``3600``.\n* ``acme_directory_url`` specifies the primary URL for the ACME service.\n  The default value is ``\"https://acme-v02.api.letsencrypt.org/directory\"``, the Let's Encrypt production API.\n  You can substitute the URL for Let's Encrypt's staging environment or another certificate authority.\n* ``acme_directory_verify_ssl`` specifies whether or not to verify the certificate of the ACME service.\n  The default value is ``True``.\n  Setting this to ``False`` is not recommneded, but may be necessary in environments using a private ACME server.\n* ``reload_zone_command`` specifies the command to execute to reload local DNS zone information.\n  When using `bindtool`_ the ``\"reload-zone.sh\"`` script provides this service.\n  If not using local DNS updates, you may set this to ``null`` to avoid warnings.\n* ``nsupdate_command`` specifies the command to perform DNS updates.\n  The default value is ``\"/usr/bin/nsupdate\"``.\n* ``verify`` specifies the default ports to perform installation verification on.\n  The default value is ``null``.\n* ``services`` specifies the default services to associate with certificates.\n  The default value is ``null``.\n\nExample::\n\n    {\n        ...\n        \"settings\": {\n            \"follower_mode\": false,\n            \"log_level\": \"debug\",\n            \"key_size\": 4096,\n            \"key_curve\": \"secp384r1\",\n            \"key_cipher\": \"blowfish\",\n            \"key_passphrase\": null,\n            \"key_provided\": false,\n            \"dhparam_size\": 2048,\n            \"ecparam_curve\": [\"secp521r1\", \"secp384r1\", \"secp256k1\"],\n            \"file_user\": \"root\",\n            \"file_group\": \"ssl-cert\",\n            \"hpkp_days\": 60,\n            \"pin_subdomains\": true,\n            \"hpkp_report_uri\": null,\n            \"ocsp_must_staple\": false,\n            \"ocsp_responder_urls\": [\"http://ocsp.int-x3.letsencrypt.org\"],\n            \"ct_submit_logs\": [\"google_icarus\", \"google_pilot\"],\n            \"renewal_days\": 30,\n            \"expiration_days\": 730,\n            \"auto_rollover\": false,\n            \"max_dns_lookup_attempts\": 60,\n            \"dns_lookup_delay\": 10,\n            \"max_authorization_attempts\": 30,\n            \"authorization_delay\": 10,\n            \"min_run_delay\": 300,\n            \"max_run_delay\": 3600,\n            \"acme_directory_url\": \"https://acme-v02.api.letsencrypt.org/directory\",\n            \"reload_zone_command\": \"/etc/bind/reload-zone.sh\",\n            \"nsupdate_command\": \"/usr/bin/nsupdate\",\n            \"verify\": [443]\n        },\n        ...\n    }\n\n\nDirectories\n-----------\n\nDirectories used to store the input and output files of the tool.\nRelative paths will be considered relative to the directory of configuration file.\nAll of these need only be present when the desired value is different from the default.\n\n* ``pid`` specifies the directory to store a process ID file.\n  The default value is ``\"/var/run\"``.\n* ``log`` specifies the directory to store the log file.\n  The default value is ``\"/var/log/acmebot\"``.\n* ``resource`` specifies the directory to store the client key and registration files for the ACME account.\n  The default value is ``\"/var/local/acmebot\"``.\n* ``private_key`` specifies the directory to store primary private key files.\n  The default value is ``\"/etc/ssl/private\"``.\n* ``backup_key`` specifies the directory to store backup private key files.\n  The default value is ``\"/etc/ssl/private\"``.\n* ``previous_key`` specifies the directory to store previously used private key files after key rollover.\n  The default value is ``null``.\n* ``full_key`` specifies the directory to store primary private key files that include the certificate chain.\n  The default value is ``\"/etc/ssl/private\"``.\n  Full key files may be omitted by setting this to ``null``.\n* ``certificate`` specifies the directory to store certificate files.\n  The default value is ``\"/etc/ssl/certs\"``.\n* ``full_certificate`` specifies the directory to store full chain certificate files that include the root certificate.\n  The default value is ``\"/etc/ssl/certs\"``.\n  Full certificate files may be omitted by setting this to ``null``.\n* ``chain`` specifies the directory to store certificate intermediate chain files.\n  The default value is ``\"/etc/ssl/certs\"``.\n  Chain files may be omitted by setting this to ``null``.\n* ``param`` specifies the directory to store Diffie-Hellman parameter files.\n  The default value is ``\"/etc/ssl/params\"``.\n  Paramater files may be omitted by setting this to ``null``.\n* ``challenge`` specifies the directory to store ACME dns-01 challenge files.\n  The default value is ``\"/etc/ssl/challenge\"``.\n* ``http_challenge`` specifies the directory to store ACME http-01 challenge files.\n  The default value is ``null``.\n* ``hpkp`` specifies the directory to store HPKP header files.\n  The default value is ``\"/etc/ssl/hpkp\"``.\n  HPKP header files may be turned off by setting this to ``null``.\n* ``sct`` specifies the directory to store Signed Certificate Timestamp files.\n  The default value is ``\"/etc/ssl/scts/\u003ccertificate-name\u003e/\u003ckey-type\u003e\"``.\n  SCT files may be turned off by setting this to ``null``.\n* ``ocsp`` specifies the directory to store OCSP response files.\n  The default value is ``\"/etc/ssl/ocsp\"``.\n  OCSP response files may be turned off by setting this to ``null``.\n* ``update_key`` specifies the directory to search for DNS update key files.\n  The default value is ``\"/etc/ssl/update_keys\"``.\n* ``archive`` specifies the directory to store older versions of files that are replaced by this tool.\n  The default value is ``\"/etc/ssl/archive\"``.\n* ``temp`` specifies the directory to write temporary files to.\n  A value of ``null`` results in using the system defined temp directory.\n  The temp directory must be on the same file system as the output file directories.\n  The default value is ``null``.\n\nExample::\n\n    {\n        ...\n        \"directories\": {\n            \"pid\": \"/var/run\",\n            \"log\": \"/var/log/acmebot\",\n            \"resource\": \"/var/local/acmebot\",\n            \"private_key\": \"/etc/ssl/private\",\n            \"backup_key\": \"/etc/ssl/private\",\n            \"full_key\": \"/etc/ssl/private\",\n            \"certificate\": \"/etc/ssl/certs\",\n            \"full_certificate\": \"/etc/ssl/certs\",\n            \"chain\": \"/etc/ssl/certs\",\n            \"param\": \"/etc/ssl/params\",\n            \"challenge\": \"/etc/ssl/challenges\",\n            \"http_challenge\": \"/var/www/{zone}/{host}/.well-known/acme-challenge\",\n            \"hpkp\": \"/etc/ssl/hpkp\",\n            \"ocsp\": \"/etc/ssl/ocsp/\",\n            \"sct\": \"/etc/ssl/scts/{name}/{key_type}\",\n            \"update_key\": \"/etc/ssl/update_keys\",\n            \"archive\": \"/etc/ssl/archive\"\n        },\n        ...\n    }\n\nDirectory values are treated as Python format strings,\nfields available for directories are: ``name``, ``key_type``, ``suffix``, ``server``.\nThe ``name`` field is the name of the private key or certificate.\nThe ``\"http_challenge\"`` directory uses the fields: ``zone``, ``host``, and ``fqdn``,\nfor the zone name, host name (without the zone), and the fully qualified domain name respectively.\nThe ``host`` value will be ``\".\"`` if the fqdn is the same as the zone name.\n\n\nServices\n--------\n\nThis 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.\nYou may add or remove services as needed.\nThe list of services is arbritrary and they are referenced from individual certificate definitions.\n\nExample::\n\n    {\n        ...\n        \"services\": {\n            \"apache\": \"systemctl reload apache2\",\n            \"coturn\": \"systemctl restart coturn\",\n            \"dovecot\": \"systemctl restart dovecot\",\n            \"etherpad\": \"systemctl restart etherpad\",\n            \"mysql\": \"systemctl reload mysql\",\n            \"nginx\": \"systemctl reload nginx\",\n            \"postfix\": \"systemctl reload postfix\",\n            \"postgresql\": \"systemctl reload postgresql\",\n            \"prosody\": \"systemctl restart prosody\",\n            \"slapd\": \"systemctl restart slapd\",\n            \"synapse\": \"systemctl restart matrix-synapse\",\n            \"znc\": \"systemctl restart znc\"\n        },\n        ...\n    }\n\nTo specify one or more services used by a certificate,\nadd a ``services`` section to the certificate definition listing the services using that certificate.\n\nFor example::\n\n    {\n        \"certificates\": {\n            \"example.com\": {\n                \"alt_names\": {\n                    \"example.com\": [\"@\", \"www\"]\n                },\n                \"services\": [\"nginx\"]\n            }\n        }\n    }\n\nThis will cause the command ``\"systemctl reload nginx\"`` to be executed any time the certificate ``example.com`` is issued, renewed, or updated.\n\n\nCertificates\n------------\n\nThis section defines the set of certificates to issue and maintain.\nThe name of each certificate is used as the name of the certificate files.\n\n* ``common_name`` specifies the common name for the certificate.\n  If omitted, the name of the certificate will be used.\n* ``alt_names`` specifies the set of subject alternative names for the certificate.\n  If specified, the common name of the certificate must be included as one of the alternative names.\n  The alternative names are specified as a list of host names per DNS zone,\n  so that associated DNS updates happen in the correct zone.\n  The zone name may be used directly by specifying ``\"@\"`` for the host name.\n  Multiple zones may be specified.\n  The default value is the common name of the certificate in the zone of the first registered domain name according to the `Public Suffix List \u003chttps://publicsuffix.org/\u003e`_.\n  For example, if the common name is \"example.com\", the default ``alt_names`` will be: ``{\"example.com\": [\"@\"] }``;\n  if the common name is \"foo.bar.example.com\", the default ``alt_names`` will be: ``{ \"example.com\": [\"foo.bar\"] }``.\n* ``services`` specifies the list of services to be reloaded when the certificate is issued, renewed, or modified.\n  This may be omitted.\n  The default value is the value specified in the ``settings`` section.\n* ``dhparam_size`` specifies the number of bits to use for custom Diffie-Hellman paramaters for the certificate.\n  The default value is the value specified in the ``settings`` section.\n  Custom Diffie-Hellman paramaters may be ommitted from the certificate by setting this to ``0`` or ``null``.\n  The value should be at least equal to half the number of bits used for the private key.\n* ``ecparam_curve`` specified the curve or curves used for elliptical curve paramaters.\n  The default value is the value specified in the ``settings`` section.\n  Custom elliptical curve paramaters may be ommitted from the certificate by setting this to ``null``.\n* ``key_types`` specifies the types of keys to create for this certificate.\n  The default value is all available key types.\n  Provide a list of key types to restrict the certificate to only those types.\n  Available types are ``\"rsa\"`` and ``\"ecdsa\"``.\n* ``key_size`` specifies the number of bits to use for the certificate's RSA private key.\n  The default value is the value specified in the ``settings`` section.\n  RSA certificates can be turned off by setting this value to ``0`` or ``null``.\n* ``key_curve`` specifies the curve to use for ECDSA private keys.\n  The default value is the value specified in the ``settings`` section.\n  Available curves are ``\"secp256r1\"``, ``\"secp384r1\"``, and ``\"secp521r1\"``.\n  ECDSA certificates can be turned off by setting this value to ``null``.\n* ``key_cipher`` specifies the cipher algorithm used to encrypt the private keys.\n  The default value is the value specified in the ``settings`` section.\n  Available ciphers those accepted by your version of OpenSSL's EVP_get_cipherbyname().\n* ``key_passphrase`` specifies the passphrase used to encrypt private keys.\n  The default value is the value specified in the ``settings`` section.\n  A value of ``null`` or ``false`` will result in private keys being written unencrypted.\n  A value of ``true`` will cause the password to be read from the command line, the environment, a prompt, or stdin.\n  A string value will be used as the passphrase without further input.\n* ``key_provided`` specifies that the private keys are provided from an external source and the tool should not modify them.\n  The default value is the value specified in the ``settings`` section.\n  This is useful when the same private keys are shared between multiple instances of the tool, e.g. for HPKP purposes.\n* ``expiration_days`` specifies the number of days that the backup private key should be considered valid.\n  The default value is the value specified in the ``settings`` section.\n  When the backup key reaches this age,\n  the tool will notify the user that a key rollover should be performed,\n  or automatically rollover the private key if ``auto_rollover`` is set to ``true``.\n  Automatic rollover and expiration notices can be disabled by setting this to ``0`` or ``null``.\n* ``auto_rollover`` specifies if the tool should automatically rollover the private key when it expires.\n  The default value is the value specified in the ``settings`` section.\n* ``hpkp_days`` specifies the number of days that HPKP pins should be cached by clients.\n  The default value is the value specified in the ``settings`` section.\n  HPKP pin files can be turned off by setting this value to ``0`` or ``null``.\n* ``pin_subdomains`` specifies whether the ``includeSubdomains`` directive should be included in the HPKP headers.\n  The default value is the value specified in the ``settings`` section.\n* ``hpkp_report_uri`` specifies the uri to report HPKP errors to.\n  The default value is the value specified in the ``settings`` section.\n  If not null, the ``report-uri`` directive will be included in the HPKP headers.\n* ``ocsp_must_staple`` specifies if the OCSP Must-Staple extension is added to certificates.\n  The default value is the value specified in the ``settings`` section.\n* ``ocsp_responder_urls`` specifies the list of OCSP responders to use if a certificate doesn't provide them.\n  The default value is the value specified in the ``settings`` section.\n* ``ct_submit_logs`` specifies the list of certificate transparency logs to submit the certificate to.\n  The default value is the value specified in the ``settings`` section.\n  The value ``[\"google_testtube\"]`` can be used with the Let's Encrypt staging environment for testing.\n* ``verify`` specifies the list of ports to perform certificate installation verification on.\n  The default value is the value specified in the ``settings`` section.\n\nExample::\n\n    {\n        ...\n        \"certificates\": {\n            \"example.com\": {\n                \"common_name\": \"example.com\",\n                \"alt_names\": {\n                    \"example.com\": [\"@\", \"www\"]\n                },\n                \"services\": [\"nginx\"],\n                \"dhparam_size\": 2048,\n                \"ecparam_curve\": [\"secp521r1\", \"secp384r1\", \"secp256k1\"],\n                \"key_types\": [\"rsa\", \"ecdsa\"],\n                \"key_size\": 4096,\n                \"key_curve\": \"secp384r1\",\n                \"key_cipher\": \"blowfish\",\n                \"key_passphrase\": null,\n                \"key_provided\": false,\n                \"expiration_days\": 730,\n                \"auto_rollover\": false,\n                \"hpkp_days\": 60,\n                \"pin_subdomains\": true,\n                \"hpkp_report_uri\": null,\n                \"ocsp_must_staple\": false,\n                \"ocsp_responder_urls\": [\"http://ocsp.int-x3.letsencrypt.org\"],\n                \"ct_submit_logs\": [\"google_icarus\", \"google_pilot\"],\n                \"verify\": [443]\n            }\n        }\n    }\n\n\nPrivate Keys\n------------\n\nThis section defines the set of private keys generated and their associated certificates.\nMultiple certificates may share a single private key.\nThis is useful when it is desired to use different certificates for certain subdomains,\nwhile specifying HPKP headers for a root domain that also apply to subdomains.\n\nThe name of each private key is used as the file name for the private key files.\n\nNote that a certificate configured in the ``certificates`` section is equivalent to a private key configured in this section with a single certificate using the same name as the private key.\nAs such, it is an error to specify a certificate using the same name in both the ``certificates`` and ``private_keys`` sections.\n\nThe private key and certificate settings are identical to those specified in the ``certificates`` section,\nexcept settings relevant to the private key: ``key_size``, ``key_curve``, ``key_cipher``, ``key_passphrase``, ``key_provided``, ``expiration_days``, ``auto_rollover``, ``hpkp_days``, ``pin_subdomains``, and ``hpkp_report_uri`` are specified in the private key object rather than the certificate object.\nThe ``key_types`` setting may be specified in the certificate, private key, or both.\n\nExample::\n\n    {\n        ...\n        \"private_keys\": {\n            \"example.com\": {\n                \"certificates\": {\n                    \"example.com\": {\n                        \"common_name\": \"example.com\",\n                        \"alt_names\": {\n                            \"example.com\": [\"@\", \"www\"]\n                        },\n                        \"services\": [\"nginx\"],\n                        \"key_types\": [\"rsa\"],\n                        \"dhparam_size\": 2048,\n                        \"ecparam_curve\": [\"secp521r1\", \"secp384r1\", \"secp256k1\"],\n                        \"ocsp_must_staple\": true,\n                        \"ct_submit_logs\": [\"google_icarus\", \"google_pilot\"],\n                        \"verify\": [443]\n                    },\n                    \"mail.example.com\": {\n                        \"alt_names\": {\n                            \"example.com\": [\"mail\", \"smtp\"]\n                        },\n                        \"services\": [\"dovecot\", \"postfix\"],\n                        \"key_types\": [\"rsa\", \"ecdsa\"]\n                    }\n                },\n                \"key_types\": [\"rsa\", \"ecdsa\"],\n                \"key_size\": 4096,\n                \"key_curve\": \"secp384r1\",\n                \"key_cipher\": \"blowfish\",\n                \"key_passphrase\": null,\n                \"key_provided\": false,\n                \"expiration_days\": 730,\n                \"auto_rollover\": false,\n                \"hpkp_days\": 60,\n                \"pin_subdomains\": true,\n                \"hpkp_report_uri\": null\n            }\n        },\n        ...\n    }\n\nThe above example will generate a single primary/backup private key set and two certificates, ``example.com`` and ``mail.example.com`` both using the same private keys.\nAn ECDSA certicicate will only be generated for ``mail.example.com``.\n\n\nTLSA Records\n------------\n\nWhen using remote DNS updates,\nit is possible to have the tool automatically maintain TLSA records for each certificate.\nNote that this requires configuring zone update keys for each zone containing a TLSA record.\n\nWhen using local DNS updates, the ``reload_zone`` command will be called after certificates are issued, renewed, or modified to allow TLSA records to be updated by a tool such as `bindtool`_.\nThe ``reload_zone`` command will not be called in follower mode.\n\nTo specify TLSA records, add a ``tlsa_records`` name/object pair to each certificate definition, either in the ``certificates`` or ``private_keys`` section.\nTLSA records are specified per DNS zone, similar to ``alt_names``,\nto specify which zone should be updated for each TLSA record.\n\nFor each zone in the TLSA record object,\nspecify a list of either host name strings or objects.\nUsing a host name string is equivalent to::\n\n    {\n        \"host\": \"\u003chost-name\u003e\"\n    }\n\nThe values for the objects are:\n\n* ``host`` specifies the host name for the TLSA record.\n  The default value is ``\"@\"``.\n  The host name ``\"@\"`` is used for the name of the zone itself.\n* ``port`` specifies the port number for the TLSA record.\n  The default value is ``443``.\n* ``usage`` is one of the following: ``\"pkix-ta\"``, ``\"pkix-ee\"``, ``\"dane-ta\"``, or ``\"dane-ee\"``.\n  The default value is ``\"pkix-ee\"``.\n  When specifying an end effector TLSA record (``\"pkix-ee\"`` or ``\"dane-ee\"``),\n  the hash generated will be of the certificate or public key itself.\n  When specifying a trust anchor TLSA record (``\"pkix-ta\"`` or ``\"dane-ta\"``),\n  records will be generated for each of the intermediate and root certificates.\n* ``selector`` is one of the following: ``\"cert\"``, or ``\"spki\"``.\n  The default value is ``\"spki\"``.\n  When specifying a value of ``\"spki\"`` and an end effector usage,\n  records will be generated for both the primary and backup public keys.\n* ``protocol`` specifies the protocol for the TLSA record.\n  The default value is ``\"tcp\"``.\n* ``ttl`` specifies the TTL value for the TLSA records.\n  The default value is ``300``.\n\nExample::\n\n    {\n        ...\n        \"private_keys\": {\n            \"example.com\": {\n                \"certificates\": {\n                    \"example.com\": {\n                        \"alt_names\": {\n                            \"example.com\": [\"@\", \"www\"]\n                        },\n                        \"services\": [\"nginx\"],\n                        \"tlsa_records\": {\n                            \"example.com\": [\n                                \"@\",\n                                {\n                                    \"host\": \"www\",\n                                    \"port\": 443,\n                                    \"usage\": \"pkix-ee\",\n                                    \"selector\": \"spki\",\n                                    \"protocol\": \"tcp\",\n                                    \"ttl\": 300\n                                }\n                            ]\n                        }\n                    },\n                    \"mail.example.com\": {\n                        \"alt_names\": {\n                            \"example.com\": [\"mail\", \"smtp\"]\n                        },\n                        \"services\": [\"dovecot\", \"postfix\"],\n                        \"tlsa_records\": {\n                            \"example.com\": [\n                                {\n                                    \"host\": \"mail\",\n                                    \"port\": 993\n                                },\n                                {\n                                    \"host\": \"smtp\",\n                                    \"port\": 25,\n                                    \"usage\": \"dane-ee\"\n                                },\n                                {\n                                    \"host\": \"smtp\",\n                                    \"port\": 587\n                                }\n                            }\n                        }\n                    }\n                }\n            }\n        },\n        ...\n    }\n\n\nAuthorizations\n--------------\n\nThis section specifies a set of host name authorizations to obtain without issuing certificates.\n\nThis is used when running in a master/follower configuration,\nthe master, having access to local or remote DNS updates or an HTTP server,\nobtains authorizations,\nwhile the follower issues the certificates.\n\nIt is not necessary to specify host name authorizations for any host names used by configured certificates,\nbut it is not an error to have overlap.\n\nAuthorizations are specified per DNS zone so that associated DNS updates happen in the correct zone.\n\nSimplar to ``alt-names``, a host name of ``\"@\"`` may be used to specify the zone name.\n\nExample::\n\n    {\n        ...\n        \"authorizations\": {\n            \"example.com\": [\"@\", \"www\"]\n        },\n        ...\n    }\n\n\nHTTP Challenges\n---------------\n\nBy default, the tool will attempt dns-01 domain authorizations for every alternative name specified,\nusing local or remote DNS updates.\n\nTo use http-01 authorizations instead,\nconfigure the ``http_challenges`` section of the configuration file specifying a challenge directory for each fully qualified domain name,\nor configure a ``http_challenge`` directory.\n\nIt is possible to mix usage of dns-01 and http-01 domain authorizations on a host by host basis,\nsimply specify a http challenge directory only for those hosts requiring http-01 authentication.\n\nExample::\n\n    {\n        ...\n        \"http_challenges\": {\n            \"example.com\": \"/var/www/htdocs/.well-known/acme-challenge\"\n            \"www.example.com\": \"/var/www/htdocs/.well-known/acme-challenge\"\n        },\n        ...\n    }\n\nThe ``http_challenges`` must specify a directory on the local file system such that files placed there will be served via an already running http server for each given domain name.\nIn the above example,\nfiles placed in ``/var/www/htdocs/.well-known/acme-challenge`` must be publicly available at:\n``http://example.com/.well-known/acme-challenge/file-name``\nand\n``http://www.example.com/.well-known/acme-challenge/file-name``\n\nAlternatively, if your are primarily using http-01 authorizations and all challenge directories have a similar path,\nyou may configure a single ``http_challenge`` directory using a python format string with the fields ``zone``, ``host``, and ``fqdn``.\n\nExample::\n\n    {\n        ...\n        \"directories\": {\n            \"http_challenge\": \"/var/www/{zone}/{host}/.well-known/acme-challenge\"\n        },\n        ...\n    }\n\nIf an ``http_challenge`` directory is configured,\nall domain authorizations will default to http-01.\nTo use dns-01 authorizations for selected domain names,\nadd an ``http_challenges`` entry configured with a ``null`` value.\n\n\nZone Update Keys\n----------------\n\nWhen using remote DNS updates,\nit is necessary to specify a TSIG key used to sign the update requests.\n\nFor each zone using remote DNS udpates,\nspecify either a string containing the file name of the TSIG key,\nor an object with further options.\n\nThe TSIG file name may an absolute path or a path relative to the ``update_key`` directory setting.\nBoth the ``\u003ckey-file\u003e.key`` file and the ``\u003ckey-file\u003e.private`` files must be present.\n\nAny zone referred to in a certificate, private key, or authorization that does not have a corresponding zone update key will use local DNS updates unless an HTTP challenge directory has been specified for every host in that zone.\n\n* ``file`` specifies the name of the TSIG key file.\n* ``server`` specifies the name of the DNS server to send update requests to.\n  If omitted, the primary name server from the zone's SOA record will be used.\n* ``port`` specifies the port to send update requests to.\n  The default value is ``53``.\n\nExample::\n\n    {\n        ...\n        \"zone_update_keys\": {\n            \"example1.com\": \"update.example1.com.key\",\n            \"example2.com\": {\n                \"file\": \"update.example2.com.key\",\n                \"server\": \"ns1.example2.com\",\n                \"port\": 53\n            }\n        },\n        ...\n    }\n\n\nKey Type Suffix\n---------------\n\nEach certificate and key file will have a suffix, just before the file extension,\nindicating the type of key the file is for.\n\nThe default suffix used for each key type can be overridden in the ``key_type_suffixes`` section.\nIf you are only using a single key type, or want to omit the suffix from one key type,\nset it to an empty string.\nNote that if using multiple key types the suffix must be unique or files will be overridden.\n\nExample::\n\n    {\n        ...\n        \"key_type_suffixes\": {\n            \"rsa\": \".rsa\",\n            \"ecdsa\": \".ecdsa\"\n        },\n        ...\n    }\n\n\nFile Name Patterns\n------------------\n\nAll output file names can be overridden using standard Python format strings.\nFields available for file names are: ``name``, ``key_type``, ``suffix``, ``server``.\nThe ``name`` field is the name of the private key or certificate.\n\n* ``log`` specifies the name of the log file.\n* ``private_key`` specifies the name of primary private key files.\n* ``backup_key`` specifies the name of backup private key files.\n* ``full_key`` specifies the name of primary private key files that include the certificate chain.\n* ``certificate`` specifies the name of certificate files.\n* ``full_certificate`` specifies the name of certificate files that include the root certificate.\n* ``chain`` specifies the name of intemediate certificate files.\n* ``param`` specifies the name of Diffie-Hellman parameter files.\n* ``challenge`` specifies the name of ACME challenge files used for local DNS updates.\n* ``hpkp`` specifies the name of HPKP header files.\n* ``ocsp`` specifies the name of OCSP response files.\n* ``sct`` specifies the name of SCT files.\n\nExample::\n\n    {   ...\n        \"file_names\": {\n            \"log\": \"acmebot.log\",\n            \"private_key\": \"{name}{suffix}.key\",\n            \"backup_key\": \"{name}_backup{suffix}.key\",\n            \"full_key\": \"{name}_full{suffix}.key\",\n            \"certificate\": \"{name}{suffix}.pem\",\n            \"full_certificate\": \"{name}+root{suffix}.pem\",\n            \"chain\": \"{name}_chain{suffix}.pem\",\n            \"param\": \"{name}_param.pem\",\n            \"challenge\": \"{name}\",\n            \"hpkp\": \"{name}.{server}\",\n            \"ocsp\": \"{name}{suffix}.ocsp\",\n            \"sct\": \"{ct_log_name}.sct\"\n        },\n        ...\n    }\n\n\nHPKP Headers\n------------\n\nThis section defines the set of HPKP header files that will be generated and their contents.\nHeader files for additional servers can be added at will,\none file will be generated for each server.\nUsing standard Python format strings, the ``{header}`` field will be replaced with the HPKP header,\nthe ``{key_name}`` field will be replaced with the name of the private key,\nand ``{server}`` will be replaced with the server name.\nThe default servers can be omitted by setting the header to ``null``.\n\nExample::\n\n    {\n        ...\n        \"hpkp_headers\": {\n            \"apache\": \"Header always set Public-Key-Pins \\\"{header}\\\"\\n\",\n            \"nginx\": \"add_header Public-Key-Pins \\\"{header}\\\" always;\\n\"\n        },\n        ...\n    }\n\n\nCertificate Transparency Logs\n-----------------------------\n\nThis section defines the set of certificate transparency logs available to submit certificates to and retrieve SCTs from.\nAdditional logs can be aded at will.\nEach log definition requires the primary API URL of the log, and the log's ID in base64 format.\nA list of currently active logs and their IDs can be found at `certificate-transparency.org \u003chttps://www.certificate-transparency.org/known-logs\u003e`_.\n\nExample::\n\n    {\n        ...,\n        \"ct_logs\": {\n            \"google_pilot\": {\n                \"url\": \"https://ct.googleapis.com/pilot\",\n                \"id\": \"pLkJkLQYWBSHuxOizGdwCjw1mAT5G9+443fNDsgN3BA=\"\n            },\n            \"google_icarus\": {\n                \"url\": \"https://ct.googleapis.com/icarus\",\n                \"id\": \"KTxRllTIOWW6qlD8WAfUt2+/WHopctykwwz05UVH9Hg=\"\n            }\n        },\n        ...\n    }\n\n\nDeployment Hooks\n----------------\n\nThis section defines the set of hooks that can be called via the shell when given actions happen.\nParamaters to hooks are specified using Python format strings.\nFields available for each hook are described below.\nOutput from the hooks will be captured in the log.\nHooks returing a non-zero status code will generate warnings,\nbut will not otherwise affect the operation of this tool.\n\n* ``set_dns_challenge`` is called for each DNS challenge record that is set.\n  Available fields are ``domain``, ``zone``, and ``challenge``.\n* ``clear_dns_challenge`` is called for each DNS challenge record that is removed.\n  Available fields are ``domain``, ``zone``, and ``challenge``.\n* ``dns_zone_update`` is called when a DNS zone is updated via either local or remote updates.\n  Available field is ``zone``.\n* ``set_http_challenge`` is called for each HTTP challenge file that is installed.\n  Available fields are ``domain``, and ``challenge_file``.\n* ``clear_http_challenge`` is called for each HTTP challenge file that is removed.\n  Available fields are ``domain``, and ``challenge_file``.\n* ``private_key_rollover`` is called when a private key is replaced by a backup private key.\n  Available fields are ``key_name``, ``key_type``, ``backup_key_file``, ``private_key_file``, ``previous_key_file``, and ``passphrase``.\n* ``private_key_installed`` is called when a private key is installed.\n  Available fields are ``key_name``, ``key_type``, ``private_key_file``, and ``passphrase``.\n* ``backup_key_installed`` is called when a backup private key is installed.\n  Available fields are ``key_name``, ``key_type``, ``backup_key_file``, and ``passphrase``.\n* ``previous_key_installed`` is called when a previous private key is installed after key rollover.\n  Available fields are ``key_name``, ``key_type``, ``previous_key_file``, and ``passphrase``.\n* ``hpkp_header_installed`` is called when a HPKP header file is installed.\n  Available fields are ``key_name``, ``server``, ``header``, and ``hpkp_file``.\n* ``certificate_installed`` is called when a certificate file is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, and ``certificate_file``.\n* ``full_certificate_installed`` is called when a certificate file that includes the root is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, and ``full_certificate_file``.\n* ``chain_installed`` is called when a certificate intermediate chain file is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, and ``chain_file``.\n* ``full_key_installed`` is called when a private key including the full certificate chain file is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, and ``full_key_file``.\n* ``params_installed`` is called when a params file is installed.\n  Available fields are ``key_name``, ``certificate_name``, and ``params_file``.\n* ``sct_installed`` is called when a SCT file is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, ``ct_log_name``, and ``sct_file``.\n* ``ocsp_installed`` is called when an OSCP file is installed.\n  Available fields are ``key_name``, ``key_type``, ``certificate_name``, and ``ocsp_file``.\n\nExample::\n\n    {\n        ...\n        \"hooks\": {\n            certificate_installed\": \"scp {certificate_file} remote-server:/etc/ssl/certs/\"\n        },\n        ...\n    }\n\n\nCertificate Installation Verification\n-------------------------------------\n\nThe tool may be configured to perform installation verification of certificates.\nWhen verifying installation, the tool will connect to every subject alternative host name for each certificate on all avaialable IP addresses,\nper each configured port,\nperform a TLS handshake,\nand compare the served certificate chain to the specified certificate.\n\nEach configured port may be an integer port number,\nor an object specifying connection details.\n\nWhen using an object, the avaialable fields are:\n\n* ``port`` specifies the port number to connect to.\n  Required.\n* ``starttls`` specifies the STARTTLS mechanism that should be used to initiate a TLS session.\n  Allowed values are: ``null``, ``smtp``, ``pop3``, ``imap``, ``sieve``, ``ftp``, ``ldap``, and ``xmpp``.\n  The default value is ``null``.\n* ``protocol`` specifies the protocol used to obtain additional information to verify.\n  Currently this can retrieve Public-Key-Pins http headers to ensure that they are properly set.\n  Allowed values are: ``null``, and ``http``.\n  The default value is ``null``.\n* ``hosts`` specifies a list of fully qualified domain names to test.\n  This allows testing only a subset of the alternative names specified for the certificate.\n  Each host name must be present as an alternative name for the certificate.\n  The default value is all alternative names.\n* ``key_types`` specifies a list of key types to test.\n  This allows testing only a subset of the avaialable key types.\n  The default value is all avaialable key types.\n\nExample::\n\n    {\n        ...\n        \"verify\": [\n            {\n                \"port\": 443,\n                \"protocol\": \"http\"\n            },\n            {\n                \"port\": 25,\n                \"starttls\": \"smtp\",\n                \"hosts\": \"smtp.example.com\",\n                \"key_types\": \"rsa\"\n            },\n            993\n        ]\n        ...\n    }\n\n\nConfiguring Local DNS Updates\n=============================\n\nIn order to perform dns-01 authorizations,\nand to keep TLSA records up to date,\nthe tool will need to be able to add, remove, and update various DNS records.\n\nFor updating DNS on a local server,\nthis tool was designed to use a bind zone file pre-processor,\nsuch as `bindtool`_,\nbut may be used with another tool instead.\n\nWhen using `bindtool`_, be sure to configure bindtool's ``acme_path`` to be equal to the value of the ``challenge`` directory, so that it can find the ACME challenge files.\n\nWhen the tool needs to update a DNS zone, it will call the configured ``reload_zone`` command with the name of the zone as its argument.\nWhen _acme-challenge records need to be set, a file will be placed in the ``challenge`` directory with the name of the zone in question, e.g. ``/etc/ssl/challenges/example.com``.\nThe challenge file is a JSON format file containing a single object.\nThe name/value pairs of that object are the fully qualified domain names of the records needing to be set, and the values of the records, e.g.::\n\n    {\n        \"www.example.com\": \"gfj9Xq...Rg85nM\"\n    }\n\nWhich should result in the following DNS record created in the zone::\n\n    _acme-challenge.www.example.com. 300 IN TXT \"gfj9Xq...Rg85nM\"\n\nNote that domain names containing wildcards must have the wildcard component removed in the corresponding TXT record, e.g.::\n\n    {\n        \"example.com\": \"jc87sd...kO89hG\"\n        \"*.example.com\": \"gfj9Xq...Rg85nM\"\n    }\n\nMust result in the following DNS records created in the zone::\n\n    _acme-challenge.example.com. 300 IN TXT \"jc87sd...kO89hG\"\n    _acme-challenge.example.com. 300 IN TXT \"gfj9Xq...Rg85nM\"\n\nIf there is no file in the ``challenge`` directory with the same name as the zone, all _acme-challenge records should be removed.\n\nAny time the ``reload_zone`` is called, it should also update any TLSA records asscoiated with the zone based on the certificates or private keys present.\n\nAll of these functions are provided automatically by `bindtool`_ via the use of ``{{acme:}}`` and ``{{tlsa:}}`` commands in the zone file.\nFor example, the zone file::\n\n    {{soa:ns1.example.com:admin@example.com}}\n\n    {{ip4=192.0.2.0}}\n\n    @   NS  ns1\n    @   NS  ns2\n\n    @   A   {{ip4}}\n    www A   {{ip4}}\n\n    {{tlsa:443}}\n    {{tlsa:443:www}}\n\n    {{acme:}}\n\n    {{caa:letsencrypt.org}}\n\nWill define the zone ``example.com`` using the nameservers ``ns1.example.com`` and ``ns1.example.com``, providing the hosts ``example.com`` and ``www.example.com``, with TLSA records pinning the primary and backup keys.\n\n\nConfiguring Remote DNS Updates\n==============================\n\nIf the tool is not run on a machine also hosting a DNS server, then http-01 authorizations or remote DNS updates must be used.\n\nThe use remote DNS udpates via RFC 2136 dynamic updates,\nconfigure a zone update key for each zone.\nSee the `Zone Update Keys \u003c#zone-update-keys\u003e`_ section for more information.\n\nIt is also necesary to have the ``nsupdate`` tool installed and the ``nsupdate_command`` configured in the ``settings`` configuration section.\n\nZone update keys may be generated via the ``dnssec-keygen`` tool.\n\nFor example::\n\n    dnssec-keygen -r /dev/urandom -a HMAC-MD5 -b 512 -n HOST update.example.com\n\nwill generate two files, named Kupdate.example.com.+157+NNNNN.key and Kupdate.example.com.+157+NNNNN.private.\nSpecify the .key file as the zone update key.\n\nTo configure bind to allow remote DNS updates, add an entry to named.conf.keys for the update key containg the key value from the private key file, e.g.::\n\n    key update.example.com. {\n        algorithm hmac-md5;\n        secret \"sSeWrBDen...9WESlnEwQ==\";\n    };\n\nand then add an ``allow-update`` entry to the zone configuration, e.g.::\n\n    zone \"example.com\" {\n        type master;\n        allow-update { key update.example.com.; };\n        ...\n    };\n\n\nRunning the Tool\n================\n\nOn first run, the tool will generate a client key,\nregister that key with the certificate authority,\naccept the certificate authority's terms and conditions,\nperform all needed domain authorizations,\ngenerate primary private keys,\nissue certificates,\ngenerate backup private keys,\ngenerate custom Diffie-Hellman parameters,\ninstall certificate and key files,\nupdate TLSA records,\nretrieve current Signed Certificate Timestamps (SCTs) from configured certificate transparency logs,\nretrieve OCSP staples,\nreload services associated to the certificates,\nand perform configured certificate installation verification.\n\nEach subsequent run will ensure that all authorizations remain valid,\ncheck if any backup private keys have passed their expiration date,\ncheck if any certificate's expiration dates are within the renewal window,\nor have changes to the configured common name, or subject alternative names,\nor no longer match their associated private key files.\n\nIf a backup private key has passed its expiration date,\nthe tool will rollover the private key or emit a warning recommending that the private key be rolled over,\nsee the `Private Key Rollover \u003c#private-key-rollover\u003e`_ section for more information.\n\nIf a certificate needs to be renewed or has been modified,\nthe certificate will be re-issued and reinstalled.\n\nWhen certificates are issued or re-issued,\nlocal DNS updates will be attempted (to update TLSA records) and associated services will be reloaded.\n\nWhen using remote DNS updates,\nall configured TLSA records will be verified and updated as needed on each run.\n\nConfigured certificate transparency logs will be queried and SCT files will be updated as necessary.\n\nAll certificates and private keys will normally be processed on each run,\nto restrict processing to specific private keys (and their certificates),\nyou can list the names of the private keys to process on the command line.\n\n\nDaily Run Via cron\n------------------\n\nIn order to ensure that certificates in use do not expire,\nit is recommended that the tool be run at least once per day via a cron job.\n\nBy default, the tool only generates output when actions are taken making it cron friendly.\nNormal output can be supressed via the ``--quiet`` command line option.\n\nTo prevent multiple instances running at the same time,\na random wait can be introduced via the ``--randomwait`` command line option.\nThe minimum and maximum wait times can be controlled via the ``min_run_delay`` and ``max_run_delay`` settings.\n\nExample cron entry, in file /etc/cron.d/acmebot::\n\n    MAILTO=admin@example.com\n\n    20 0 * * * root /usr/local/bin/acmebot --randomwait\n\nThis will run the tool as root every day at 20 minutes past midnight plus a random delay of five minutes to an hour.\nAny output will be mailed to admin@example.com.\n\nIf using OCSP response files, it may be desirable to refresh OCSP responses at a shorter interval.\n(Currently Let's Encrypt updates OCSP responses every three days.)\nTo refresh OCSP responses every six hours, add the line:\n\n    20 6,12,18 * * * root /usr/local/bin/acmebot --ocsp --randomwait\n\n\nOutput Options\n--------------\n\nNormally the tool will only generate output to stdout when certificates are issued or private keys need to be rolled over.\nMore detailed output can be obtained by using any of the ``--verbose``, ``--debug``, or ``--detail`` options on the command line.\n\nNormal output may be supressed by using the ``--quiet`` option.\n\nError and warning output will be sent to stderr and cannot be supressed.\n\nThe output can be colorized by type by adding the ``--color`` option,\nor colorized output can be suppressed via the ``--no-color`` option.\n\n\nPrivate Key Rollover\n--------------------\n\nDuring normal operations the private keys for certificates will not be modified,\nthis allows renewing or modifying certificates without the need to update associated pinning information,\nsuch as HPKP headers or TLSA records using spki selectors.\n\nHowever, it is a good security practice to replace the private keys at regular intervals,\nor immediately if it is believed that the primary private key may have been compromised.\nThis tool maintains a backup private key for each primary private key and generates pinning information including the backup key as appropriate to allow smooth transitions to the backup key.\n\nWhen the backup private key reaches the age specified via the ``expiration_days`` setting,\nthe tool will notify you that it is time to rollover the private key,\nunless the ``auto_rollover`` setting has been set to ``true``,\nin which case it will automatically perform the rollover.\n\nThe rollover process will archive the current primary private key,\nre-issue certificates using the existing backup key as the new primary key,\ngenerate a new backup private key,\ngenerate new custom Diffie-Hellman parameters,\nand reset HPKP headers and TLSA records as appropriate.\n\nIf the ``previous_key`` directory is specified,\nthe current primary private key will be stored in that directory as a previous private key.\nWhile previous private key files are present,\ntheir key signatures will be added to HPKP pins and TLSA records.\nThis can assist in key rollover when keys are pinned for subdomains and private keys are shared between multiple servers.\nOnce the new primary and backup keys have been distributed to the other servers,\nthe previous private key file may be safely removed.\n\nTo manually rollover private keys, simply run the tool with the ``--rollover`` option.\nYou can specify the names of individual private keys on the command line to rollover,\notherwise all private keys will be rolled over.\n\nNote that the tool will refuse to rollover a private key if the current backup key is younger than the HPKP duration.\nA private key rollover during this interval may cause a web site to become inaccessable to clients that have previously cached HPKP headers but not yet retrieved the current backup key pin.\nIf it is necessary to rollover the private key anyway,\nfor example if it is believed that the backup key has been compromised as well,\nadd the ``--force`` option on the command line to force the private key rollover.\n\n\nForced Certificate Renewal\n--------------------------\n\nNormally certificates will be automatically renewed when the tool is run within the certificate renewal window,\ne.g. within ``renewal_days`` of the certificate's expiration date.\nTo cause certificates to be renewed before this time,\nrun the tool with the ``--renew`` option on the command line.\n\n\nRevoking Certificates\n---------------------\n\nShould it become necessary to revoke a certificate,\nfor example if it is believed that the private key has been compromised,\nrun the tool with the ``--revoke`` option on the command line.\n\nWhen revoking certificates, as a safety measure,\nit is necessary to also specify the name of the private key (or keys) that should be revoked.\nAll certificates using that private key will be revoked,\nthe certificate files and the primary private key file will be moved to the archive,\nand remote DNS TLSA records will be removed.\n\nThe next time the tool is run after a revocation,\nany revoked certificates that are still configured will automatically perform a private key rollover.\n\n\nAuthorization Only\n------------------\n\nUse of the ``--auth`` option on the command line will limit the tool to only performing domain authorizations.\n\n\nCertificates Only\n-----------------\n\nUse of the ``--certs`` option on the command line will limit the tool to only issuing and renewing certificates and keys,\nand updating related files such as Diffie-Hellman paramaters and HPKP headers.\n\n\nRemote TLSA Updates\n-------------------\n\nUse of the ``--tlsa`` option on the command line will limit the tool to only verifying and updating configured TLSA records via remote DNS updates.\n\n\nSigned Certificate Timestamp Updates\n------------------------------------\n\nUse of the ``--sct`` option on the command line will limit the tool to only verifying and updating configured Signed Certificate Timestamp files.\n\n\nOCSP Response Updates\n---------------------\n\nUse of the ``--ocsp`` option on the command line will limit the tool to only updating configured OCSP response files.\n\n\nCertificate Installation Verification\n-------------------------------------\n\nUse of the ``--verify`` option on the command line will limit the tool to only performing certificate installation verification.\n\n\nMultiple Operations\n-------------------\n\nThe ``--auth``, ``--certs``, ``--tlsa``, ``--sct``, ``-ocsp``, and ``--verify`` options may be combined to perform a combinations of operations.\nIf none of these options are specified, all operations will be performed as necessary and configured.\nThe order of the operations will not be affected by the order of the command line options.\n\n\nPrivate Key Encryption\n----------------------\n\nWhen encrypting private keys, a passphrase must be provided.\nThere are several options for providing the key.\n\nPassphrases may be specified directly in the configuration file,\nboth as a default passphrase applying to all keys,\nor specific passphrases for each key.\nStoring passphrases in cleartext in the configuration file obviously does little to protect the private keys if the configuration file is stored on the same machine.\nEither protect the configuration file or use an alternate method of providing passphrases.\n\nAlternatively, by setting the passphrase to ``true`` in the configuration file (the binary value, not the string ``\"true\"``),\nthe tool will attempt to obtain the passphrases at runtime.\n\nRuntime passphrases may be provided on the command line, via an environment variable, via a text prompt, or via an input file.\n\nA command line passphrase is passed via the ``--pass`` option, e.g.::\n\n    acmebot --pass \"passphrase\"\n\nTo use an environment variable, set the passphrase in ``ACMEBOT_PASSPHRASE``.\n\nA passphrase passed at the command line or an environment variable will be used for every private key that has it's ``key_passphrase`` set to ``true``.\nIf different passphrases are desired for different keys,\nrun the tool for each key specifying the private key name on the command line to restrict processing to that key.\n\nIf the passphrase is not provided on the command line or an environment variable,\nand the tool is run via a TTY device (e.g. manually in a terminal),\nit will prompt the user for each passphrase as needed.\nDifferent passphrases may be provided for each private key (the same passphrase will be used for all key types of that key).\n\nFinally, the passphrases may be stored in a file, one per line, and input redirected from that file, e.g.::\n\n    acmebot \u003c passphrase_file.txt\n\nPassphrases passed via an input file will be used in the order that the private keys are defined in the configuration file.\nIf both certificates and private key sections are defined, the private keys will be processed first, then the certificates.\nYou may wish to run the tool without the input file first to verify the private key order.\n\n\n\nMaster/Follower Setup\n=====================\n\nIn some circumstances, it is useful to run the tool in a master/follower configuration.\nIn this setup, the master performs domain authorizations\nwhile the follower issues and maintains certificates.\n\nThis setup is useful when the follower machine does not have the ability to perform domain authorizations,\nfor example, an XMPP server behind a firewall that does not have port 80 open or access to a DNS server.\n\nTo create a master/follower setup,\nfirst install and configure the tool on the master server as normal.\nThe master server may also issue certificates, but it is not necessary.\n\nConfigure any required domain authorizations (see the `Authorizations \u003c#authorizations\u003e`_ section) on the master and run the tool.\n\nThen install the tool on the follower server.\nIt is not necessary to configure HTTP challenges or remote DNS update keys on the follower.\n\nBefore running the tool on the follower server,\ncopy the client key and registration files from the master server.\nThese files are normally found in ``/var/local/acmebot`` but an alternate location can be configured in the ``resource`` directory setting.\n\nIf the master server also issues certificates for the same domain names or parent domain names as the follower,\nyou may want to copy the primary and backup private keys for those certificates to the follower.\nThis will cause the follower certificates to use the same keys allowing HPKP headers to safey include subdomains.\n\nSet the follower ``follower_mode`` setting to ``true`` and configure desired certificates on the follower.\n\nRun the tool on the follower server.\n\nWhen setting up cron jobs for the master and follower,\nbe sure the follower runs several minutes after the master so that all authorizations will be complete.\nThe master can theoretically take (``max_dns_lookup_attempts`` x ``dns_lookup_delay``) + (``max_authorization_attempts`` x ``authorization_delay``) seconds to obtain domain authorizations (15 minutes at the default settings).\n\nIt is possible to run several follower servers for each master,\nthe follower cron jobs should not all run at the same time.\n\nThe follower server may maintain TLSA records if remote DNS updates are configured on the follower,\notherwise it is recommended to use spki selectors for TLSA records so that certificate renewals on the follower will not invalidate TLSA records.\n\nIf private keys are shared between a master and follower,\nbe sure to turn off ``auto_rollover`` and only perform private key rollovers on the master.\nIt is also useful to specify the ``previous_key`` directory to preserve previous key pins during the key rollover process.\nAfter a private key rollover, copy the new primary and backup private key files to the followers.\nThe follower will automatically detect the new private key and re-issue certificates on the next run.\nOnce all the followers have updated their certificates to the new keys,\nyou can safely delete the previous private key file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplinss%2Facmebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplinss%2Facmebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplinss%2Facmebot/lists"}