ACME utilities ============== tinyacme -------- This is a trivial Go wrapper around the net/http and x/crypto/acme packages, primarily intended for provisioning TLS certificates for non-web services. Given a list of hostnames as command-line arguments, it resolves them to a complete set of IPv4 and IPv6 addresses, binds to every address on the https port tcp/443, then obtains TLS certificates from an ACME-based provider by responding to TLS-ALPN-01 challenges. The ACME endpoint can be specified using the ACMEURL environment variable. If this is unset, the Let's Encrypt ACME v2 service is used by default: https://acme-v02.api.letsencrypt.org/directory If any of the addresses is in use or not local, tinyacme will die with an error before any certificates are ordered. Otherwise, for each hostname, a combined PEM-format key and certificate file is written in the current directory, with mode 0600 and filename matching the hostname. On subsequent invocations, tinyacme will first validate existing certificate files and only renew them if they are invalid or within 30 days of expiry. acmeproxy --------- This extends tinyacme into an https-to-http reverse proxy suitable for TLS termination. It resolves the hostnames given as command-line arguments and listens for https connections on the resulting addresses, obtaining TLS certificates as required. Once running, inbound requests are proxied to the non-TLS http service on the same local address and hostname. An X-Forwarded-For: header is added to every request; if one is already present, the client address is appended to the existing chain. Inbound HTTP/2 connections are supported as well as HTTP/1.1. As with tinyacme, certificates are cached in the current directory and will be renewed 30 days from expiry. This happens transparently during normal operation and does not require a restart or other intervention. Certificate-provisioning, TLS or HTTP proxy errors are logged to stdout while the proxy runs, but successfully proxied requests are silent. Fatal errors on startup are reported to stderr and result in a non-zero exit status as with tinyacme. On receipt of SIGTERM, SIGHUP or SIGINT, the proxy stops accepting new connections, waits for outstanding requests to complete, then gracefully exits. acmefront --------- This is a variant of acmeproxy which listens for both http and https requests, intended as a complete (if somewhat opinionated) web front-end. Inbound http requests receive a 301 Moved Permanently response, redirecting them to the corresponding https URL. Inbound https requests are proxied to the local http socket specified as the first argument, before the list of hostnames. The socket address should be a path to a unix socket containing at least one '/', or a TCP address in the form HOSTNAME:PORT, IPv4:PORT or [IPv6]:PORT. The Host: header is passed through acmefront unmodified, so a single target web service can dispatch on it to deliver multiple virtual services in the traditional way. Building and installing ----------------------- To build binaries, run 'go build tinyacme.go', 'go build acmeproxy.go' and 'go build acmefront.go' in the source tree. To install, copy these binaries into a directory on your path. They should compile and run on any platform with Go 1.17 or later. Static binaries independent of the host libc can be built with the '-tags netgo' go build option. Please report any problems or bugs to Chris Webb <chris@arachsys.com>. Copying ------- These utilities were written by Chris Webb <chris@arachsys.com> and are distributed as Free Software under the terms of the MIT license in COPYING.