certwrapper is a wrapper that requests and maintains a certificate from an ACME server (such as
Let's Encrypt) using a DNS challenge, and then runs another program that will make use of it.
The certificate is refreshed before it is due to expire, and the underlying process is SIGHUP'd.
A new certificate is also obtained if the configured domains or key type no longer match the existing one.
If a renewal fails, certwrapper logs the error and tries again an hour later. It only refuses to start the
underlying process if it can't obtain a certificate and doesn't already have a valid one.
This is designed to be used by other services that accept PEM certificates but don't have their own way of requesting ACME certificates; it's a bit nicer than having separate scripts to manage the process, especially if you're running the service in a container.
Usage: certwrapper [options] /path/to/target [target options]
Certwrapper options:
-acme-email string
E-mail address to supply to the ACME server.
-acme-endpoint string
ACME endpoint to request certificates from. (default "https://acme-v02.api.letsencrypt.org/directory")
-certificate-path string
Path to save the certificate. (default "cert/certificate.pem")
-dns-provider string
DNS provider to use. See https://go-acme.github.io/lego/dns/.
-domains string
Comma-separated list of domains to request on the certificate.
-issuer-path string
Path to save the issuer's certificate. (default "cert/issuer.pem")
-key-type string
Type of private key to use when generating a certificate. One of: EC256, EC384, RSA2048, RSA3072, RSA4096, RSA8192. (default "EC384")
-log.format string
Format of log output ('json' or 'text') (default "text")
-log.level string
Lowest level of logs that should be output
-private-key-path string
Path to save the private key. (default "cert/privatekey.pem")
-strip-env string
Comma-separated list of environment variables to withhold from the target, such as DNS provider credentials. A trailing * matches any variable starting with the preceding text.
-user-path string
Path to save user registration data. (default "cert/user.json")
acme-email, domains and dns-provider are required options. Everything else has sensible defaults.
Key types from certwrapper v4, such as P384, are still accepted.
The dns-provider option must be set to one of the providers supported by Lego. Configuration for individual providers is done via environment variables, which are documented on the Lego provider page.
Alternatively, certwrapper can be configured using environment variables prefixed with CERTWRAPPER_, for
example the private-key-path flag can be set using a CERTWRAPPER_PRIVATE_KEY_PATH env var.
The target inherits certwrapper's environment, except for the CERTWRAPPER_ variables and anything listed in
strip-env. Use it to keep DNS provider credentials out of the target's environment, for example
-strip-env 'CF_*,CLOUDFLARE_*', so they can't end up in its logs or error pages.
certwrapper logs to stderr. log.level is one of debug, info (the default), warn or error.
certwrapper will connect the target binary's stdin, stderr and stdout to its own. It will also relay any SIGINT, SIGTERM, SIGHUP, SIGUSR1 and SIGUSR2 signals to the child process.
Saved files are replaced atomically with new files with 0600 permissions, so certwrapper needs write access
to the directories containing them. If you're using containers, mount those directories rather than the individual
files, as a file that is itself a mount point can't be replaced. certwrapper exits at startup if it finds one.
If you are building certwrapper and know in advance which DNS provider you wish to use, you can use a
build tag to eliminate all the others. This can significantly reduce the binary size and shave
a second or two off the build times. The build constraints take the format lego_<provider> e.g.
lego_cloudflare or lego_httpreq. For example, building with just httpreq support:
go build -tags lego_httpreq github.com/csmith/certwrapper
Trying to use any other provider with one of these builds will result in an error.