Re: [9front] [patch] improve http challenge documentation in acmed(8)

[ori@eigenstate.org]

I'd posted a diff in IRC, I think, and then promptly lost it.

Rewritten, how does this sound?

--- a/sys/man/8/acmed
+++ b/sys/man/8/acmed
@@ -97,7 +97,7 @@
 .IP
 For HTTP challenges,
 .I chalout
-must be a directory that your webserver will serve at
+must be a directory that your webserver is serving at
 .br
 .BI http:// mydomain.com /.well-known/acme-challenge .
 .br
@@ -111,6 +111,9 @@
 database.
 It defaults to
 .BR /lib/ndb/dnschallenge .
+Because the certificate issuer will access these to
+validate the domain,
+the DNS or HTTP servers must be configured before acmed is run.
 .TP
 .B -t
 .I type
@@ -176,6 +179,11 @@
 .IR webfs (4)
 to be mounted as the ACME protocol uses HTTP
 to talk to the provider.
+Additionally, the contents of the challenge directory must
+be available over plaintext HTTP,
+served at the URL
+.IR http://mydomain.com/.well-known/acme-challenge/$challenge .
+This URL will be accessed during the certificate verification process.
 .IP
 .EX
 auth/acmed me@example.com /sys/lib/tls/acmed/mydomain.com.csr \\

Quoth ori@eigenstate.org:
> I think the phrasing could be better; I'll take a pass over it.
> 
> 
> Quoth eso@self.rodeo:
> > ping
> > 
> > On 2023-12-19 20:22, eso@self.rodeo wrote:
> > > working through the example for http challenge in acmed(8) left out a 
> > > few steps and clarifications. now, following the example with your 
> > > webserver will (should) give your domain https. i also added 
> > > /rc/bin/service/!tcp443 as an example service for acmed(8) to 
> > > reference. while i was at it, i also updated listen(8) to include tcp80 
> > > and tcp443.
> > > 
> > > eso
> > > 
> > > 
> > > diff 66fc6a3e6443d7eb8298f65b0c9803197d196ec7 uncommitted
> > > --- a/sys/man/8/acmed
> > > +++ b/sys/man/8/acmed
> > > @@ -176,11 +176,33 @@
> > >  .IR webfs (4)
> > >  to be mounted as the ACME protocol uses HTTP
> > >  to talk to the provider.
> > > +.PP
> > > +Change -o to be the path your webserver
> > > +will be serving at
> > > +.br
> > > +.BI http:// mydomain.com /.well-known/acme-challenge .
> > >  .IP
> > >  .EX
> > > -auth/acmed me@example.com /sys/lib/tls/acmed/mydomain.com.csr \\
> > > +auth/acmed -o /path/to/webroot/.well-known/acme-challenge/ \\
> > > +me@example.com /sys/lib/tls/acmed/mydomain.com.csr \\
> > >  	> /sys/lib/tls/acmed/mydomain.com.crt
> > >  .EE
> > > +.PP
> > > +The
> > > +.B cert.key
> > > +must also be loaded into
> > > +.IR factotum (4).
> > > +.IP
> > > +.EX
> > > +cat cert.key > /mnt/factotum/ctl
> > > +.EE
> > > +.PP
> > > +Now you can configure
> > > +.BR /rc/bin/service/tcp443
> > > +to handle
> > > +.br
> > > +HTTPS connections with your webserver of choice.
> > > +.br
> > >  .PP
> > >  When using the DNS challenge method,
> > >  your DNS server
> > > --- a/sys/man/8/listen
> > > +++ b/sys/man/8/listen
> > > @@ -1,6 +1,6 @@
> > >  .TH LISTEN 8
> > >  .SH NAME
> > > -listen, listen1, tcp7, tcp9, tcp19, tcp21, tcp23, tcp25, tcp53, 
> > > tcp110, tcp113, tcp143, tcp445, tcp513, tcp515, tcp564, tcp565, tcp566, 
> > > tcp567, tcp993, tcp995, tcp1723, tcp17019, tcp17020 \- listen for calls 
> > > on a network device
> > > +listen, listen1, tcp7, tcp9, tcp19, tcp21, tcp23, tcp25, tcp53, tcp80, 
> > > tcp110, tcp113, tcp143, tcp443, tcp445, tcp513, tcp515, tcp564, tcp565, 
> > > tcp566, tcp567, tcp993, tcp995, tcp1723, tcp17019, tcp17020 \- listen 
> > > for calls on a network device
> > >  .SH SYNOPSIS
> > >  .B aux/listen
> > >  .RB [ -iq ]
> > > @@ -182,6 +182,9 @@
> > >  .B tcp53
> > >  TCP port for DNS.
> > >  .TP
> > > +.B tcp80
> > > +HTTP port.
> > > +.TP
> > >  .B tcp110
> > >  POP3 port.
> > >  .TP
> > > @@ -192,6 +195,9 @@
> > >  .TP
> > >  .B tcp143
> > >  IMAP4rev1 port.
> > > +.TP
> > > +.B tcp443
> > > +HTTPS port.
> > >  .TP
> > >  .B tcp445
> > >  CIFS/SMB file sharing.
> > > 
> > > 
> > > diff 66fc6a3e6443d7eb8298f65b0c9803197d196ec7 uncommitted
> > > --- /dev/null
> > > +++ b/rc/bin/service/!tcp443
> > > @@ -1,0 +1,4 @@
> > > +#!/bin/rc
> > > +
> > > +# See acmed(8)
> > > +/bin/tlssrv -c/sys/lib/tls/acmed/mydomain.com.crt 
> > > /rc/bin/rc-httpd/rc-httpd
>