README: update and simplify a little

3 files changed, 61 insertions, 61 deletions

diff --git a/Makefile b/Makefile
index 81f227c..8aef3e8 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,8 @@
 # This source code is released into the public domain.
 
-.PHONY:	default all install install-lib install-bin install-conf \
-	install-hook install-man install-periodic
-.SUFFIXES: .5 .5.in .7 .7.in .8 .8.in .sh .sh.in .sample .sample.in
+# These directories may be customised to change where things are installed.
+# To avoid issues when updating, consider providing the new values on the
+# make(1) command line instead of editing this file.
 
 PREFIX?=	/usr/local
 DESTDIR?=
@@ -17,6 +17,8 @@ MAN7DIR?=	${MANDIR}/man7
 MAN8DIR?=	${MANDIR}/man8
 HOOKDIR?=	${CONFDIR}/hooks
 
+### No user-servicable parts below this point.
+
 LIBMODE?=	0644
 LIB=		init.sh dnsutils.sh
 
@@ -55,6 +57,10 @@ REPLACE=	sed	-e 's,__PREFIX__,${PREFIX},g' \
 			-e 's,__LIBDIR__,${LIBDIR},g' \
 			-e 's,__BINDIR__,${BINDIR},g'
 
+.PHONY:	default all install install-lib install-bin install-conf \
+	install-hook install-man install-periodic
+.SUFFIXES: .5 .5.in .7 .7.in .8 .8.in .sh .sh.in .sample .sample.in
+
 default: all
 
 all: ${MAN5} ${MAN7} ${MAN8} ${LIB} ${BIN} ${CHALLENGE} ${HOOK} ${PERIODIC} ${CONF}
diff --git a/README b/README
index 8a57484..6183550 100644
--- a/README
+++ b/README
@@ -14,49 +14,47 @@ if it doesn't work, it shouldn't be difficult to port.
 requirements
 ------------
 
-+ POSIX-compatible /bin/sh
-+ uacme (in FreeBSD: security/uacme)
-+ OpenSSL command-line tool
-
-if you want to use the HTTP challenge handler:
-
-+ a web server installed on the host
-
-if you want to use the DNS challenge handlers:
-
-+ BIND's "dig" and "nsupdate" (in FreeBSD: dns/bind-tools)
-
-if you want to use the Kerberos DNS challenge handler:
-
-+ Kerberos kinit (either MIT or Heimdal should work)
++ 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
 -------
 
-# make install [PREFIX=/usr/local] [DESTDIR=/some/where]
+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 prepend to PREFIX when installing files, and may be used when
+DESTDIR is prepended to PREFIX when installing files, and may be used when
 creating packages.
 
-a FreeBSD periodic(8) script is provided as "900.lfacme.sh" 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.
+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):
-	/usr/local/etc/lfacme/acme.conf and
-	/usr/local/etc/lfacme/domains.conf
++ 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(7)
+to begin with.
+
 known issues
 ------------
 
@@ -76,39 +74,9 @@ there are two configuration files:
 these both come with manual pages which explain how to configure them,
 and sample configs are provided.
 
-BIND + Kerberos configuration
------------------------------
-
-if you want to use the provided Kerberos dns-01 challenge, you must configure
-your DNS server to accept Kerberos-authenticated dynamic updates.
-
-first, tell BIND where to load its Kerberos keytab from:
-
-	options {
-		tkey-gssapi-keytab "/usr/local/etc/namedb/krb5.keytab";
-	};
-
-the keytab MUST contain a server key for "DNS/name.of.server@<realm>", where
-"name.of.server" MUST be the SOA MNAME for the zone(s) you want to update.
-this is not configurable, it's a requirement of how the protocol works.
-
-an update policy like this will allow any host to update ACME challenges for
-its own hostname:
-
-	update-policy {
-		# note: "EXAMPLE.ORG" is the Kerberos realm, not the DNS zone!
-		grant EXAMPLE.ORG krb5-selfsub . TXT;
-	};
-
-or to let a specific host update some other records:
-
-	update-policy {
-		grant "host/server.example.org@EXAMPLE.ORG"
-			name _acme-challenge.example.org. TXT;
-
-		grant "host/server.example.org@EXAMPLE.ORG"
-			name _acme-challenge.www.example.org. TXT;
-	};
+questions, comments?
+--------------------
 
-this might also work with the Microsoft Windows DNS server,
-but that hasn't been tested.
+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.
diff --git a/lfacme-kerberos.7.in b/lfacme-kerberos.7.in
index b3afd0c..8b9f85e 100644
--- a/lfacme-kerberos.7.in
+++ b/lfacme-kerberos.7.in
@@ -66,6 +66,32 @@ This must contain a key for the principal configured by
 The default value is
 .Pa /etc/krb5.keytab .
 .El
+.Sh DNS SERVER CONFIGURATION
+For
+.Nm
+to work, the DNS server must be configured to accept Kerberos-authenticated
+Dynamic DNS updates.
+Using ISC BIND, this can be achieved using a zone update-policy.
+For example, to allow any host in the
+.Dq EXAMPLE.ORG
+Kerberos realm to issue certificates for its own hostname
+(and subdomains thereof):
+.Bd -literal -offset indent
+update-policy {
+	grant EXAMPLE.ORG krb5-selfsub . TXT;
+};
+.Ed
+.Pp
+Or to allow a specific host to issue certificates for a different DNS label:
+.Bd -literal -offset indent
+update-policy {
+	grant "host/server.example.org@EXAMPLE.ORG"
+		name _acme-challenge.www.example.org. TXT;
+};
+.Ed
+.Pp
+Suitable configuration for other DNS servers (e.g., the Microsoft Windows
+DNS server) is left as an exercise for the reader.
 .Sh SEE ALSO
 .Xr acme.conf 5 ,
 .Xr domains.conf 5 ,