From 09aa3870070960d37d7bdbb724f4ac7b68395fdf Mon Sep 17 00:00:00 2001 From: Lexi Winter Date: Wed, 4 Jun 2025 10:29:47 +0100 Subject: documentation improvements --- lfacme-kerberos.7 | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 lfacme-kerberos.7 (limited to 'lfacme-kerberos.7') 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 -- cgit v1.2.3