Package: acertmgr
ACERTMGRThis is an automated certificate manager using ACME/letsencrypt with minimal dependencies.Running ACERTMGRThe main file acertmgr.py is intended to be run regularly (e.g. as daily cron job / systemd timer) as root or user with enough privileges.RequirementsPython (2.7+ and 3.5+ should work)cryptography>=0.6Optional requirements (to use specified features)PyYAML: to parse YAML-formatted configuration filesdnspython: used by dns.* challenge handlersidna: to allow automatic conversion of unicode domain names to their IDNA2008 counterpartscryptography>=2.1: for creating certificates with the OCSP must-staple flag (cert_must_staple)cryptography>=2.6: for usage of Ed25519/Ed448 keysSetupYou should decide which challenge mode you want to use with acertmgr:webdir: In this mode, responses to challenges are put into a directory, to be served by an existing webserverstandalone: In this mode, challenges are completed by acertmgr directly. This starts a webserver to solve the challenges, which can be used standalone or together with an existing webserver that forwards request to a specified local port/address.dns.*: This mode puts the challenge into a TXT record for the domain (usually _acme-challenge.) where it will be parsed from by the authoritydns.* (Alias mode): Can be used similar to the above but allows redirection of _acme-challenge. to any other (updatable domain) defined in dns_updatedomain via CNAME (e.g. _acme-challenge.example.net IN CNAME bla.foo.bar with dns_updatedomain="bla.foo.bar" in domainconfig)dns.nsupdate: Updates the TXT record using RFC2136You can optionally provide the private key files to be used with the ACME protocol (if you do not they will be automatically created):The account private key is (by default) expected at/etc/acertmgr/account.key(used to register an account with the authorities server)The domain private keys are (by default) expected at/etc/acertmgr/{cert_id}.keyIf you are missing these keys, they will be created for you (using RSA with the configured key_length) or you can create them using e.g.openssl genrsa 4096 > /etc/acertmgr/account.keyDo not forget to set proper permissions of the keys usingchmod 0400 /etc/acertmgr/*.keyif you created those manuallyFinally, you need to setup the configuration files, as shown in the next section.
While testing, you can use the acme-staging authority instead, in order to avoid issuing too many certificates.Authorities (e.g. our default Let's Encrypt) will require you to accept their Terms of Service. This can be done either in the optional global config file and/or via a commandline parameter (see acertmgr.py --help).ConfigurationConfiguration examples are included in thedocs/directory. All configuration files can use yaml (requires PyYAML) or json syntax. (Note: The JSON examples may be incomplete due to inability to express comments in JSON)Unless specified with a commandline parameter (see acertmgr.py --help) the optional global configuration is read from/etc/acertmgr/acertmgr.conf.
Domains for which certificates should be obtained/renewed are be configured in/etc/acertmgr/*.conf(the global configuration is always excluded if it is in the same directory).
By default the directory (work_dir) containing the working data (csr,certificate,key and ca files) is located at/etc/acertmgr/.4 configuration contexts are known (domainconfig (d) > globalconfig (g) > commandline (c) > built-in defaults) with the following directives (subject to change, usual usage context written bold):DirectiveContextDescriptionBuilt-in Default-c/--config-filecglobal configuration file (optional)/etc/acertmgr/acertmgr.conf-d/--config-dircdirectory containing domain configuration files (ending with .conf, globalconfig will be excluded automatically if in same directory)/etc/acertmgr/*.conf-w/--work-dircworking directory containing csr/certificates/keys/ca files/etc/acertmgr--force-renewc(or --renew-now) Immediately renew all certificates containing the given domain(s)--revokecRevoke the certificate at the given path--revoke-reasoncProvide a reason code for the revocation (seehttps://tools.ietf.org/html/rfc5280#section-5.3.1for valid values)domain (san-domain...):d(domainconfig section start) Domains to use in the cert request. This value will be MD5-hashed as cert_id.apid,gDetermines the API version usedv2authorityd,gURL to the certificate authorities ACME API root (without trailing /directory or similar)https://acme-v02.api.letsencrypt.orgauthority_tos_agreementd,g,cIndicates agreement to the ToS of the certificate authority (--authority-tos-agreement on command line)authority_contact_emaild,g(v2 API only) Contact e-mail to be registered with your account keyaccount_keyd,gPath to the account key{work_dir}/account.keyaccount_key_algorithmd,gKey-algorithm for newly generated account keys (RSA, EC, ED25519, ED448)RSAaccount_key_lengthd,gKey-length for newly generated RSA account keys (in bits) or EC curve (256=P-256, 384=P-384, 521=P-521)depends on account_key_algorithmttl_daysd,gRenew certificate if it has less than this value validity left30validate_ocspd,gRenew certificate if it's OCSP status is REVOKED. Allowed values for this key are: false, sha1, sha224, sha256, sha384, sha512sha1 (as mandated by RFC5019)cert_dird,gDirectory containing all certificate related data (crt,key,csr){work_dir}key_algorithmd,gKey-algorithm for newly generated private keys (RSA, ECC, ED25519, ED448)RSAkey_lengthd,gKey-length for newly generated RSA private keys (in bits) or EC curve (256=P-256, 384=P-384, 521=P-521)depends on key_algorithmcsr_staticd,gWhether to re-use a static CSR or generate a new dynamic CSRfalsecsr_filed,gPath to store (and load) the certificate CSR file{cert_dir}/{cert_id}.csrca_staticd,gWhether to re-use a static CA or download a CA filefalseca_filed,gPath to store (and load) the certificate authority file{cert_dir}/{cert_id}.cacert_filedPath to store (and load) the certificate file{cert_dir}/{cert_id}.crtcert_revoke_supersededd,gRevoke the previous certificate with reason "superseded" after successful deploymentfalsecert_must_stapled,gGenerate a certificate (request) with the OCSP must-staple flag (will be honoured on the next newly generated CSR if using csr_static=true)falsekey_filed,gPath to store (and load) the private key file{cert_dir}/{cert_id}.keymoded,gMode of challenge handling usedstandalonewebdird,g[webdir] Put acme challenges into this path/var/www/acme-challenge/http_verifyd,g[webdir/standalone] Verify challenge before attempting authorizationtruebind_addressd,g[standalone] Serve the challenge using a HTTP server on given IPportd,g[standalone] Serve the challenge using a HTTP server on this port80dns_ttld,g[dns.*] Write TXT records with this TTL (also determines the update wait time at twice this value60dns_updatedomaind,g[dns.*] Write the TXT records to this domain (you have to create the necessary CNAME on the real challenge domain manually)dns_verify_intervald,g[dns.*] Do verification checks when starting the challenge every {dns_verify_interval} seconds10dns_verify_failtimed,g[dns.*] Fail challenge TXT record verification after {dns_verify_failtime} seconds{dns_waittime} + 1dns_verify_waittimed,g[dns.*] Assume DNS challenges are valid after {dns_verify_waittime}2 * {dns_ttl}dns_verify_all_nsd,g[dns.*] Verify DNS challenges by querying all known zone NS servers (resolved by zone master from SOA or dns_verify_server)falsedns_verify_serverd,g[dns.*] Verify DNS challenges by querying this DNS server unless 'dns_verify_all_ns' is enabled, then use to determine zone NSnsupdate_serverd,g[dns.nsupdate] DNS Server to delegate the update to{determine from zone SOA}nsupdate_verifyd,g[dns.nsupdate] Verify TXT record on the update server upon creationtruensupdate_keyfiled,g[dns.nsupdate] Bind-formatted TSIG key file to use for updates (may be used instead of nsupdate_key*)nsupdate_keynamed,g[dns.nsupdate] TSIG key name to use for updatesnsupdate_keyvalued,g[dns.nsupdate] TSIG key value to use for updatesnsupdate_keyalgorithmd,g[dns.nsupdate] TSIG key algorithm to use for updatesHMAC-MD5.SIG-ALG.REG.INTdefaults:gDefault deployment action settings used by all domainspathd(deployment) deploy certificate data to the given fileformatd,g(defaults)(deployment) deploy one or more of the following data to the file at path: key,crt,causerd,g(defaults)(deployment) change the user of the file deployed at path to this value (optional, defaults to acertmgr current effective user)groupd,g(defaults)(deployment) change the group of the file deployed at path to this value (optional,defaults to acertmgr current effective group)permd,g(defaults)(deployment) change the permissions of the file deployed at path to this value (optional, CAUTION: uses system defaults for new files)actiond,g(defaults)(deployment) run the following action after deployment is finished. This command will be run in a shell and supports it's syntax. (optional)SecurityPlease keep the following in mind when using this software:DO read the source code, since it (usually) will be run as rootMake sure that your configuration files are NOT writable by other users - arbitrary commands can be executed after updating certificatesTry to run this program non-privileged if possible. This requires you to:Create a dedicated user for acertmgr (e.g. acertmgr)Run a acertmgr as that user (add acertmgr to that users cron!)Access rights to read/write all files configured with the created userRun any programs/scripts defined on cert update as the created user (might need work-arounds with sudo or wrapper scripts)