From 09aa3870070960d37d7bdbb724f4ac7b68395fdf Mon Sep 17 00:00:00 2001 From: Lexi Winter Date: Wed, 4 Jun 2025 10:29:47 +0100 Subject: documentation improvements --- Makefile | 15 ++++++++--- acme.conf.5 | 7 +++++ init.sh | 24 +++++++++++------- kerberos.sh | 4 +++ lfacme-dns.5 | 60 ------------------------------------------- lfacme-dns.7 | 61 ++++++++++++++++++++++++++++++++++++++++++++ lfacme-http.5 | 56 ---------------------------------------- lfacme-http.7 | 57 +++++++++++++++++++++++++++++++++++++++++ lfacme-kerberos.5 | 74 ----------------------------------------------------- lfacme-kerberos.7 | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ lfacme-renew.8 | 6 +++++ lfacme-setup.8 | 8 +++++- lfacme.7 | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 13 files changed, 319 insertions(+), 204 deletions(-) delete mode 100644 lfacme-dns.5 create mode 100644 lfacme-dns.7 delete mode 100644 lfacme-http.5 create mode 100644 lfacme-http.7 delete mode 100644 lfacme-kerberos.5 create mode 100644 lfacme-kerberos.7 create mode 100644 lfacme.7 diff --git a/Makefile b/Makefile index bdbb426..007b02c 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ BINDIR?= ${DESTDIR}${PREFIX}/sbin CONFDIR?= ${DESTDIR}${PREFIX}/etc MANDIR?= ${DESTDIR}${PREFIX}/share/man MAN5DIR?= ${MANDIR}/man5 +MAN7DIR?= ${MANDIR}/man7 MAN8DIR?= ${MANDIR}/man8 HOOKDIR?= ${CONFDIR}/hooks @@ -32,10 +33,11 @@ HOOK= example-hook.sh MANMODE?= 0644 MAN5= acme.conf.5 \ - domains.conf.5 \ - lfacme-dns.5 \ - lfacme-http.5 \ - lfacme-kerberos.5 + domains.conf.5 +MAN7= lfacme.7 \ + lfacme-dns.7 \ + lfacme-http.7 \ + lfacme-kerberos.7 MAN8= lfacme-renew.8 \ lfacme-setup.8 @@ -94,6 +96,11 @@ install-man: echo "install ${MAN5DIR}/$$man"; \ install -C -m ${MANMODE} "$$man" "${MAN5DIR}/$$man"; \ done + @echo 'create ${MAN7DIR}'; install -d ${MAN7DIR} + @for man in ${MAN7}; do \ + echo "install ${MAN7DIR}/$$man"; \ + install -C -m ${MANMODE} "$$man" "${MAN7DIR}/$$man"; \ + done @echo 'create ${MAN8DIR}'; install -d ${MAN8DIR} @for man in ${MAN8}; do \ echo "install ${MAN8DIR}/$$man"; \ diff --git a/acme.conf.5 b/acme.conf.5 index 0f17377..f1f2638 100644 --- a/acme.conf.5 +++ b/acme.conf.5 @@ -17,6 +17,13 @@ Each option should be configured as a variable assignment, i.e. .Dq Ar option Ns = Ns Ar value . .Pp +Alternatively, options may be set as environment variables prior to running +.Nm lfacme +utilities. +If all required options are set in the environment, then creating the +.Nm +file is not required. +.Pp The following configuration variables are supported: .Bl -tag -width indent .It Va ACME_URL diff --git a/init.sh b/init.sh index a1353a4..c48e942 100644 --- a/init.sh +++ b/init.sh @@ -21,6 +21,12 @@ _warn() { printf >&2 '%s: WARNING: %s\n' "$_PROGNAME" "$_msg" } +_info() { + local _fmt=$1; shift + local _msg="$(printf "$_fmt" "$@")" + printf '%s: %s\n' "$_PROGNAME" "$_msg" +} + _verbose() { if [ -z "$LFACME_VERBOSE" ]; then return @@ -54,28 +60,28 @@ _CONFIG="${_CONFDIR}/acme.conf" # Read and validate the configuration file. -if ! [ -f "$_CONFIG" ]; then - _fatal "missing %s" "$_CONFIG" +if [ -f "$_CONFIG" ]; then + . "$_CONFIG" fi -. "$_CONFIG" - if [ -z "$ACME_URL" ]; then - _fatal "ACME_URL must be set in %s" "$_CONFIG" + _fatal "missing configuration setting: ACME_URL" fi if [ -z "$ACME_DATADIR" ]; then ACME_DATADIR="/var/db/lfacme" fi -if [ -z "$ACME_KERBEROS_PRINCIPAL" ]; then - ACME_KERBEROS_PRINCIPAL="host/$(hostname)" -fi - if [ -z "$ACME_HOOKDIR" ]; then ACME_HOOKDIR="${_CONFDIR}/hooks" fi +# Create our data directory. +if [ ! -d "$ACME_DATADIR" ]; then + _info "creating directory %s" "$ACME_DATADIR" + mkdir -p "$ACME_DATADIR" +fi + # The domains.conf file. _DOMAINS="${_CONFDIR}/domains.conf" diff --git a/kerberos.sh b/kerberos.sh index 08663d8..543abc6 100644 --- a/kerberos.sh +++ b/kerberos.sh @@ -23,6 +23,10 @@ if [ "$METHOD" != "dns-01" ]; then exit 1 fi +if [ -z "$ACME_KERBEROS_PRINCIPAL" ]; then + ACME_KERBEROS_PRINCIPAL="host/$(hostname)" +fi + if [ -z "$ACME_KERBEROS_KEYTAB" ]; then ACME_KERBEROS_KEYTAB="/etc/krb5.keytab" fi diff --git a/lfacme-dns.5 b/lfacme-dns.5 deleted file mode 100644 index dedf250..0000000 --- a/lfacme-dns.5 +++ /dev/null @@ -1,60 +0,0 @@ -.\" This source code is released into the public domain. -.Dd June 4, 2025 -.Dt LFACME-DNS 5 -.Os -.Sh NAME -.Nm lfacme-dns -.Nd validate an ACME challenge via TSIG DNS updates -.Sh SYNOPSIS -In -.Xr domains.conf 5 : -.Bd -ragged -offset indent -.Ar domain -challenge=dns -.Ed -.Sh DESCRIPTION -The -.Nm -challenge hook will respond to an ACME domain validation using a DNS-based -.Dq dns-01 -authorization with TSIG-authenticated Dynamic DNS updates. -To use this challenge hook, configure one or more domains with -.Dq challenge=dns -in -.Xr domains.conf 5 . -.Pp -The -.Dq dns-01 -challenge expects the authorization token to be created as a TXT record at the -DNS name -.Dq _acme-challenge. Ns Ar domain . -When -.Nm -responds to the challenge, it will use -.Xr nsupdate 1 -to create this record. -The DNS update will be sent to the zone's master server (determined by the -MNAME field in the SOA record), and will be authenticated using the TSIG -key file configured by -.Ar ACME_DNS_KEYFILE -in -.Xr acme.conf 5 . -.Pp -Once validation is complete, the previously created DNS record will be removed. -.Sh CONFIGURATION -The -.Nm -challenge hook supports the following configuration options in -.Xr acme.conf 5 : -.Bl -tag -width indent -.It Va ACME_DNS_KEYFILE -(Required.) -The key file that will be passed to -.Xr nsupdate 1 -to authenticate the DNS update. -.El -.Sh SEE ALSO -.Xr acme.conf 5 , -.Xr domains.conf 5 , -.Xr lfacme-renew 8 , -.Xr nsupdate 1 diff --git a/lfacme-dns.7 b/lfacme-dns.7 new file mode 100644 index 0000000..5e46215 --- /dev/null +++ b/lfacme-dns.7 @@ -0,0 +1,61 @@ +.\" This source code is released into the public domain. +.Dd June 4, 2025 +.Dt LFACME-DNS 7 +.Os +.Sh NAME +.Nm lfacme-dns +.Nd validate an ACME challenge via TSIG DNS updates +.Sh SYNOPSIS +In +.Xr domains.conf 5 : +.Bd -ragged -offset indent +.Ar domain +challenge=dns +.Ed +.Sh DESCRIPTION +The +.Nm +challenge hook will respond to an ACME domain validation using a DNS-based +.Dq dns-01 +authorization with TSIG-authenticated Dynamic DNS updates. +To use this challenge hook, configure one or more domains with +.Dq challenge=dns +in +.Xr domains.conf 5 . +.Pp +The +.Dq dns-01 +challenge expects the authorization token to be created as a TXT record at the +DNS name +.Dq _acme-challenge. Ns Ar domain . +When +.Nm +responds to the challenge, it will use +.Xr nsupdate 1 +to create this record. +The DNS update will be sent to the zone's master server (determined by the +MNAME field in the SOA record), and will be authenticated using the TSIG +key file configured by +.Ar ACME_DNS_KEYFILE +in +.Xr acme.conf 5 . +.Pp +Once validation is complete, the previously created DNS record will be removed. +.Sh CONFIGURATION +The +.Nm +challenge hook supports the following configuration options in +.Xr acme.conf 5 : +.Bl -tag -width indent +.It Va ACME_DNS_KEYFILE +(Required.) +The key file that will be passed to +.Xr nsupdate 1 +to authenticate the DNS update. +.El +.Sh SEE ALSO +.Xr acme.conf 5 , +.Xr domains.conf 5 , +.Xr lfacme 7 , +.Xr lfacme-renew 8 , +.Xr nsupdate 1 diff --git a/lfacme-http.5 b/lfacme-http.5 deleted file mode 100644 index ed5ca8e..0000000 --- a/lfacme-http.5 +++ /dev/null @@ -1,56 +0,0 @@ -.\" This source code is released into the public domain. -.Dd June 4, 2025 -.Dt LFACME-HTTP 5 -.Os -.Sh NAME -.Nm lfacme-http -.Nd validate an ACME challenge via HTTP -.Sh SYNOPSIS -In -.Xr domains.conf 5 : -.Bd -ragged -offset indent -.Ar domain -challenge=http -.Ed -.Sh DESCRIPTION -The -.Nm -challenge hook will respond to an ACME domain validation using an HTTP-based -.Dq http-01 -authorization. -To use this challenge hook, configure one or more domains with -.Dq challenge=http -in -.Xr domains.conf 5 . -.Pp -The -.Dq http-01 -challenge expects the authorization token to be served via HTTP at the path -.Dq /.well-known/acme-challenge/ Ns Ar token -on the domain to be validated. -When -.Nm -responds to the challenge, it will place the token in the directory configured -by -.Ar ACME_HTTP_CHALLENGE_DIR -in -.Xr acme.conf 5 . -This directory must be mapped to the appropriate path on the web server for -the challenge to succeed. -.Sh CONFIGURATION -The -.Nm -challenge hook supports the following configuration options in -.Xr acme.conf 5 : -.Bl -tag -width indent -.It Va ACME_HTTP_CHALLENGE_DIR -(Required.) -The directory to place the challenge tokens in. -The contents of this directory should be served at the path -.Dq /.well-known/acme-challenge -on the web server for the domain to be validated. -.El -.Sh SEE ALSO -.Xr acme.conf 5 , -.Xr domains.conf 5 , -.Xr lfacme-renew 8 diff --git a/lfacme-http.7 b/lfacme-http.7 new file mode 100644 index 0000000..25b7aac --- /dev/null +++ b/lfacme-http.7 @@ -0,0 +1,57 @@ +.\" This source code is released into the public domain. +.Dd June 4, 2025 +.Dt LFACME-HTTP 7 +.Os +.Sh NAME +.Nm lfacme-http +.Nd validate an ACME challenge via HTTP +.Sh SYNOPSIS +In +.Xr domains.conf 5 : +.Bd -ragged -offset indent +.Ar domain +challenge=http +.Ed +.Sh DESCRIPTION +The +.Nm +challenge hook will respond to an ACME domain validation using an HTTP-based +.Dq http-01 +authorization. +To use this challenge hook, configure one or more domains with +.Dq challenge=http +in +.Xr domains.conf 5 . +.Pp +The +.Dq http-01 +challenge expects the authorization token to be served via HTTP at the path +.Dq /.well-known/acme-challenge/ Ns Ar token +on the domain to be validated. +When +.Nm +responds to the challenge, it will place the token in the directory configured +by +.Ar ACME_HTTP_CHALLENGE_DIR +in +.Xr acme.conf 5 . +This directory must be mapped to the appropriate path on the web server for +the challenge to succeed. +.Sh CONFIGURATION +The +.Nm +challenge hook supports the following configuration options in +.Xr acme.conf 5 : +.Bl -tag -width indent +.It Va ACME_HTTP_CHALLENGE_DIR +(Required.) +The directory to place the challenge tokens in. +The contents of this directory should be served at the path +.Dq /.well-known/acme-challenge +on the web server for the domain to be validated. +.El +.Sh SEE ALSO +.Xr acme.conf 5 , +.Xr domains.conf 5 , +.Xr lfacme 7 , +.Xr lfacme-renew 8 diff --git a/lfacme-kerberos.5 b/lfacme-kerberos.5 deleted file mode 100644 index 27973c7..0000000 --- a/lfacme-kerberos.5 +++ /dev/null @@ -1,74 +0,0 @@ -.\" This source code is released into the public domain. -.Dd June 4, 2025 -.Dt LFACME-KERBEROS 5 -.Os -.Sh NAME -.Nm lfacme-kerberos -.Nd validate an ACME challenge via GSS-TSIG DNS updates -.Sh SYNOPSIS -In -.Xr domains.conf 5 : -.Bd -ragged -offset indent -.Ar domain -challenge=kerberos -.Ed -.Sh DESCRIPTION -The -.Nm -challenge hook will respond to an ACME domain validation using a DNS-based -.Dq dns-01 -authorization with GSS-TSIG Dynamic DNS updates. -To use this challenge hook, configure one or more domains with -.Dq challenge=kerberos -in -.Xr domains.conf 5 . -.Pp -The -.Dq dns-01 -challenge expects the authorization token to be created as a TXT record at the -DNS name -.Dq _acme-challenge. Ns Ar domain . -When -.Nm -responds to the challenge, it will use -.Xr nsupdate 1 -with the -.Fl g -flag to create this token. -The DNS update will be sent to the zone's master server, as determined by the -MNAME field in the SOA record. -.Pp -Before sending the update, -.Nm -will retrieve a Kerberos ticket using -.Xr kinit 1 -for the principal configured by -.Ar ACME_KERBEROS_PRINCIPAL -in -.Xr acme.conf 5 . -.Sh CONFIGURATION -The -.Nm -challenge hook supports the following configuration options in -.Xr acme.conf 5 : -.Bl -tag -width indent -.It Va ACME_KERBEROS_PRINCIPAL -The Kerberos principal to authenticate as when sending the DNS update. -The default value is -.Dq host/$(hostname) , -which assumes a default realm has been configured in -.Pa /etc/krb5.conf . -Explicitly configuring the principal is recommended, but not required. -.It Va ACME_KERBEROS_KEYTAB -The keytab used to issue the Kerberos ticket. -This must contain a key for the principal configured by -.Va ACME_KERBEROS_PRINCIPAL . -The default value is -.Pa /etc/krb5.keytab . -.El -.Sh SEE ALSO -.Xr acme.conf 5 , -.Xr domains.conf 5 , -.Xr kinit 1 , -.Xr lfacme-renew 8 , -.Xr nsupdate 1 diff --git a/lfacme-kerberos.7 b/lfacme-kerberos.7 new file mode 100644 index 0000000..b3afd0c --- /dev/null +++ b/lfacme-kerberos.7 @@ -0,0 +1,75 @@ +.\" This source code is released into the public domain. +.Dd June 4, 2025 +.Dt LFACME-KERBEROS 7 +.Os +.Sh NAME +.Nm lfacme-kerberos +.Nd validate an ACME challenge via GSS-TSIG DNS updates +.Sh SYNOPSIS +In +.Xr domains.conf 5 : +.Bd -ragged -offset indent +.Ar domain +challenge=kerberos +.Ed +.Sh DESCRIPTION +The +.Nm +challenge hook will respond to an ACME domain validation using a DNS-based +.Dq dns-01 +authorization with GSS-TSIG Dynamic DNS updates. +To use this challenge hook, configure one or more domains with +.Dq challenge=kerberos +in +.Xr domains.conf 5 . +.Pp +The +.Dq dns-01 +challenge expects the authorization token to be created as a TXT record at the +DNS name +.Dq _acme-challenge. Ns Ar domain . +When +.Nm +responds to the challenge, it will use +.Xr nsupdate 1 +with the +.Fl g +flag to create this token. +The DNS update will be sent to the zone's master server, as determined by the +MNAME field in the SOA record. +.Pp +Before sending the update, +.Nm +will retrieve a Kerberos ticket using +.Xr kinit 1 +for the principal configured by +.Ar ACME_KERBEROS_PRINCIPAL +in +.Xr acme.conf 5 . +.Sh CONFIGURATION +The +.Nm +challenge hook supports the following configuration options in +.Xr acme.conf 5 : +.Bl -tag -width indent +.It Va ACME_KERBEROS_PRINCIPAL +The Kerberos principal to authenticate as when sending the DNS update. +The default value is +.Dq host/$(hostname) , +which assumes a default realm has been configured in +.Pa /etc/krb5.conf . +Explicitly configuring the principal is recommended, but not required. +.It Va ACME_KERBEROS_KEYTAB +The keytab used to issue the Kerberos ticket. +This must contain a key for the principal configured by +.Va ACME_KERBEROS_PRINCIPAL . +The default value is +.Pa /etc/krb5.keytab . +.El +.Sh SEE ALSO +.Xr acme.conf 5 , +.Xr domains.conf 5 , +.Xr kinit 1 , +.Xr lfacme 7 , +.Xr lfacme-renew 8 , +.Xr nsupdate 1 diff --git a/lfacme-renew.8 b/lfacme-renew.8 index 1ed3aba..5d54e17 100644 --- a/lfacme-renew.8 +++ b/lfacme-renew.8 @@ -37,6 +37,12 @@ This also passes the .Fl v option to uacme. .El +.Sh ENVIRONMENT +Refer to +.Xr lfacme 8 +for a list of environment variables which affect the operation of +.Nm . .Sh SEE ALSO .Xr domains.conf 5 , +.Xr lfacme 7 , .Xr lfacme-setup 8 diff --git a/lfacme-setup.8 b/lfacme-setup.8 index 3cb1a3b..f34e518 100644 --- a/lfacme-setup.8 +++ b/lfacme-setup.8 @@ -35,5 +35,11 @@ option to uacme. If the ACME provider requires accepting terms of service, accept the provided terms automatically. .El +.Sh ENVIRONMENT +Refer to +.Xr lfacme 8 +for a list of environment variables which affect the operation of +.Nm . .Sh SEE ALSO -.Xr acme.conf 5 +.Xr acme.conf 5 , +.Xr lfacme 7 diff --git a/lfacme.7 b/lfacme.7 new file mode 100644 index 0000000..bed5a08 --- /dev/null +++ b/lfacme.7 @@ -0,0 +1,76 @@ +.\" This source code is released into the public domain. +.Dd June 4, 2025 +.Dt LFACME 7 +.Os +.Sh NAME +.Nm lfacme +.Nd issue, renew and manage ACME certificates +.Sh SYNOPSIS +.Nm lfacme-setup +.Op opts +.Nm lfacme-renew +.Op opts +.Sh DESCRIPTION +The +.Nm +software package supports management of TLS certificates using an ACME server. +Certificates can be automatically issued and renewed, and a hook system allows +software using those certificates to be automatically (re)configured. +.Pp +Prior to using +.Nm , +two configuration files must be created: +.Pa /usr/local/etc/lfacme/acme.conf +and +.Pa /usr/local/etc/lfacme/domains.conf . +Samples of both files are provided in +.Pa /usr/local/etc/lfacme . +Refer to +.Xr acme.conf 5 +and +.Xr domains.conf 5 +for more detailed documentation on these files. +.Pp +To perform initial setup, run +.Xr lfacme-setup 8 . +This will register an account on the ACME server, and create any required +local data. +Running +.Xr lfacme-setup 8 +will not issue any certificates. +.Pp +To issue or renew certificates, run +.Xr lfacme-renew 8 . +This will examine the certificates configured in +.Xr domains.conf 5 ; +new certificates will be issued, while existing certificates will be renewed +if necessary. +To ensure certificates are automatically renewed when required, +.Xr lfacme-renew 8 +should be run regularly, e.g. using +.Xr cron 8 . +.Sh ENVIRONMENT +The following environment variables affect the executation of the +.Nm +utilities: +.Bl -tag -width LFACME_VERBOSE +.It Ev LFACME_CONFDIR +Override the default configuration directory. +This is equivalent to specifying the +.Fl c +flag on the command line. +.It Ev LFACME_VERBOSE +If set to a non-empty string, run in verbose mode. +This is equivalent to specifying the +.Fl v +flag on the command line. +.El +.Pp +Additionally, any configuration settings described in +.Xr acme.conf 5 +may also be set in the environment. +.Sh SEE ALSO +.Xr acme.conf 5 , +.Xr domains.conf 5 , +.Xr lfacme-renew 8 , +.Xr lfacme-setup 8 -- cgit v1.2.3