documentation improvements

10 files changed, 132 insertions, 17 deletions

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.7
index dedf250..5e46215 100644
--- a/lfacme-dns.5
+++ b/lfacme-dns.7
@@ -1,6 +1,6 @@
 .\" This source code is released into the public domain.
 .Dd June 4, 2025
-.Dt LFACME-DNS 5
+.Dt LFACME-DNS 7
 .Os
 .Sh NAME
 .Nm lfacme-dns
@@ -56,5 +56,6 @@ to authenticate the DNS update.
 .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.7
index ed5ca8e..25b7aac 100644
--- a/lfacme-http.5
+++ b/lfacme-http.7
@@ -1,6 +1,6 @@
 .\" This source code is released into the public domain.
 .Dd June 4, 2025
-.Dt LFACME-HTTP 5
+.Dt LFACME-HTTP 7
 .Os
 .Sh NAME
 .Nm lfacme-http
@@ -53,4 +53,5 @@ on the web server for the domain to be validated.
 .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.7
index 27973c7..b3afd0c 100644
--- a/lfacme-kerberos.5
+++ b/lfacme-kerberos.7
@@ -1,6 +1,6 @@
 .\" This source code is released into the public domain.
 .Dd June 4, 2025
-.Dt LFACME-KERBEROS 5
+.Dt LFACME-KERBEROS 7
 .Os
 .Sh NAME
 .Nm lfacme-kerberos
@@ -70,5 +70,6 @@ The default value is
 .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