tinyacme

README

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.