lfacme: a simple ACME client based on uacme
===========================================

lfacme is a wrapper around uacme to make it a bit more flexible.  i wrote it
primarily for my own use, but you're welcome to use it too.

lfacme comes with challenge handlers for basic HTTP validation (http-01),
DNS validation (dns-01) using TSIG- or Kerberos-authenticated nsupdate,
and TLS validation (tls-alpn-01) using uacme's ualpn proxy.

it can also be used with any uacme-compatible challenge handler.

it's only tested on FreeBSD and may or may not work on other platforms.
if it doesn't work, it shouldn't be difficult to port.

requirements
------------

+ POSIX-compatible /bin/sh.
+ OpenSSL command-line tool.
+ uacme (in FreeBSD: security/uacme).
+ if you want to use the provided DNS-based validation scripts,
  BIND's "dig" and "nsupdate" tools (in FreeBSD: dns/bind-tools).

install
-------

simply run:

	# make install [PREFIX=/usr/local] [DESTDIR=/some/where]

PREFIX is the base directory to install into.  if not specified, /usr/local
is assumed.

DESTDIR is prepended to PREFIX when installing files, and may be used when
creating packages.

some other variables (like CONFDIR) can also be set; see Makefile for a
complete list.  for example, for an SVR4-style installation:

	# make install PREFIX=/opt/lfacme CONFDIR=/etc/opt/lfacme

a FreeBSD periodic(8) script is provided and will be installed automatically
on FreeBSD.  to run lfacme-renew once a day to renew certificates, set
"daily_lfacme_enable=YES" in /etc/periodic.conf.

usage
-----

+ create the config files (see below)
+ run "lfacme setup" to create an ACME account
+ run "lfacme renew" to issue certificates
+ put "lfacme renew" in cron if you want to renew certificates automatically.
  it's fine to run this once a day, since it won't renew certificates unless
  they're going to expire soon.

the lfacme documentation is provided as online manual pages; see lfacme(8)
to begin with.

known issues
------------

+ we disable ARI in uacme (uacme --no-ari) because it's broken on non-glibc
  platforms.  this is a uacme bug: ndilieto/uacme#91.
  the only impact of this is that certificates will be renewed 30 days before
  expiry, instead of when the ACME server wants us to renew them.
 
config files
------------

there are two configuration files:

+ acme.conf configures the global behaviour of lfacme
+ domains.conf lists the certificates lfacme should issue

these both come with manual pages which explain how to configure them,
and sample configs are provided.

questions, comments?
--------------------

send any feedback (bugs, feature requests or patches) to lexi@le-fay.org.
alternatively, you can create an issue in the GitHub repository at
https://github.com/llfw/lfacme.