docs/man: Auto-generate markdown manpages

This patch adds auto-generation of markdown manpages, for ease of
reference in other documents and links.

docs/man/chasquid-util.1

@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "chasquid-util 1"
-.TH chasquid-util 1 "2023-07-30" "" ""
+.TH chasquid-util 1 "2023-07-29" "" ""
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

docs/man/chasquid-util.1.md

@@ -0,0 +1,62 @@
+# NAME
+
+chasquid-util - chasquid management tool
+
+# SYNOPSIS
+
+**chasquid-util** \[_options_\] user-add _user@domain_ \[--password=_password_\]
+
+**chasquid-util** \[_options_\] user-remove _user@domain_
+
+**chasquid-util** \[_options_\] authenticate _user@domain_ \[--password=_password_\]
+
+**chasquid-util** \[_options_\] check-userdb _domain_
+
+**chasquid-util** \[_options_\] aliases-resolve _addr_
+
+**chasquid-util** \[_options_\] domaininfo-remove _domain_
+
+**chasquid-util** \[_options_\] print-config
+
+# DESCRIPTION
+
+chasquid-util is a command-line utility for [chasquid(1)](chasquid.1.md) operations.
+
+# OPTIONS
+
+- **user-add** _user@domain_ \[--password=_password_\]
+
+    Add a new user to the domain.
+
+- **user-remove** _user@domain_
+
+    Remove the user from the domain.
+
+- **authenticate** _user@domain_ \[--password=_password_\]
+
+    Check the user's password.
+
+- **check-userdb** _domain_
+
+    Check the integrity of the domain's users database.
+
+- **aliases-resolve** _addr_
+
+    Resolve the given address. Talks to the running chasquid instance.
+
+- **domaininfo-remove** _domain_
+
+    Remove the domain information entry. This can be used to manually allow a
+    security level downgrade. Talks to the running chasquid instance.
+
+- **print-config**
+
+    Parse and print the configuration in a human-readable way.
+
+- **-C** or **--configdir=<path**>
+
+    Configuration directory.
+
+# SEE ALSO
+
+[chasquid(1)](chasquid.1.md)

docs/man/chasquid.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "chasquid 1"
-.TH chasquid 1 "2020-05-16" "" ""
+.TH chasquid 1 "2023-10-03" "" ""
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -211,7 +211,7 @@ Certificate (full chain).
 .IX Item "certs/mx.example.com/privkey.pem"
 Private key.
 .PP
-Note the \fIcerts/\fR directory layout matches the one from \fBcertbot\fR\|(1) (client for
+Note the \fIcerts/\fR directory layout matches the one from certbot (client for
 Let's Encrypt \s-1CA\s0), so you can just symlink \fIcerts/\fR to
 \&\fI/etc/letsencrypt/live\fR.
 .PP

docs/man/chasquid.1.md

@@ -0,0 +1,112 @@
+# NAME
+
+chasquid - SMTP (email) server
+
+# SYNOPSIS
+
+**chasquid** \[_options_...\]
+
+# DESCRIPTION
+
+chasquid is an SMTP (email) server with a focus on simplicity, security, and
+ease of operation.
+
+It's written in Go, and distributed under the Apache license 2.0.
+
+# OPTIONS
+
+- **-config\_dir** _dir_
+
+    configuration directory (default `/etc/chasquid`)
+
+- **-config\_overrides** _config_
+
+    configuration values (in text protobuf format) to override the on-disk
+    configuration with. This should only be needed in very specific cases for
+    deployments where editing the configuration file is not feasible.
+
+- **-alsologtostderr**
+
+    also log to stderr, in addition to the file
+
+- **-logfile** _file_
+
+    file to log to (enables logtime)
+
+- **-logtime**
+
+    include the time when writing the log to stderr
+
+- **-logtosyslog** _tag_
+
+    log to syslog, with the given tag
+
+- **-v** _level_
+
+    verbosity level (1 = debug)
+
+- **-version**
+
+    show version and exit
+
+# FILES
+
+The daemon's configuration is by default in `/etc/chasquid/`, and can be
+changed with the _-config\_dir_ flag.
+
+Inside that directory, the daemon expects the following structure:
+
+- `chasquid.conf`
+
+    Main config file, see [chasquid.conf(5)](chasquid.conf.5.md).
+
+- `domains/`
+
+    Per-domain configuration.
+
+- `domains/example.com/`
+
+    Domain-specific configuration. Can be empty.
+
+- `domains/example.com/users`
+
+    User and password database for this domain.
+
+- `domains/example.com/aliases`
+
+    Aliases for the domain.
+
+- `certs/`
+
+    Certificates to use, one directory per pair.
+
+- `certs/mx.example.com/`
+
+    Certificates for this domain.
+
+- `certs/mx.example.com/fullchain.pem`
+
+    Certificate (full chain).
+
+- `certs/mx.example.com/privkey.pem`
+
+    Private key.
+
+Note the `certs/` directory layout matches the one from certbot (client for
+Let's Encrypt CA), so you can just symlink `certs/` to
+`/etc/letsencrypt/live`.
+
+Make sure the user you use to run chasquid under ("mail" in the example
+config) can access the certificates and private keys.
+
+# CONTACT
+
+[Main website](https://blitiri.com.ar/p/chasquid).
+
+If you have any questions, comments or patches please send them to the mailing
+list, `chasquid@googlegroups.com`.  To subscribe, send an email to
+`chasquid+subscribe@googlegroups.com`.
+
+# SEE ALSO
+
+[chasquid-util(1)](chasquid-util.1.md), [chasquid.conf(5)](chasquid.conf.5.md)

docs/man/chasquid.1.pod

@@ -102,7 +102,7 @@ Private key.
 
 =back
 
-Note the F<certs/> directory layout matches the one from certbot(1) (client for
+Note the F<certs/> directory layout matches the one from certbot (client for
 Let's Encrypt CA), so you can just symlink F<certs/> to
 F</etc/letsencrypt/live>.
 

docs/man/chasquid.conf.5

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================

docs/man/chasquid.conf.5.md

@@ -0,0 +1,123 @@
+# NAME
+
+[chasquid.conf(5)](chasquid.conf.5.md) -- chasquid configuration file
+
+# SYNOPSIS
+
+[chasquid.conf(5)](chasquid.conf.5.md) is [chasquid(1)](chasquid.1.md)'s main configuration file.
+
+# DESCRIPTION
+
+The file is in protocol buffers' text format.
+
+Comments start with `#`. Empty lines are allowed.  Values are of the form
+`key: value`. Values can be strings (quoted), integers, or booleans (`true` or
+`false`).
+
+Some values might be repeated, for example the listening addresses.
+
+# OPTIONS
+
+- **hostname** (string):
+
+    Default hostname to use when saying hello. This is used to say hello to
+    clients (for aesthetic purposes), and as the HELO/EHLO domain on outgoing SMTP
+    connections (so ideally it would resolve back to the server, but it isn't a
+    big deal if it doesn't). Default: the system's hostname.
+
+- **max\_data\_size\_mb** (int):
+
+    Maximum email size, in megabytes. Default: 50.
+
+- **smtp\_address** (repeated string):
+
+    Addresses to listen on for SMTP (usually port 25). Default: "systemd", which
+    means systemd passes sockets to us. systemd sockets must be named with
+    **FileDescriptorName=smtp**.
+
+- **submission\_address** (repeated string):
+
+    Addresses to listen on for submission (usually port 587). Default: "systemd",
+    which means systemd passes sockets to us. systemd sockets must be named with
+    **FileDescriptorName=submission**.
+
+- **submission\_over\_tls\_address** (repeated string):
+
+    Addresses to listen on for submission-over-TLS (usually port 465). Default:
+    "systemd", which means systemd passes sockets to us. systemd sockets must be
+    named with **FileDescriptorName=submission\_tls**.
+
+- **monitoring\_address** (string):
+
+    Address for the monitoring HTTP server. Do NOT expose this to the public
+    internet. Default: no monitoring server.
+
+- **mail\_delivery\_agent\_bin** (string):
+
+    Mail delivery agent (MDA, also known as LDA) to use. This should point
+    to the binary to use to deliver email to local users. The content of the
+    email will be passed via stdin. If it exits unsuccessfully, we assume
+    the mail was not delivered. Default: `maildrop`.
+
+- **mail\_delivery\_agent\_args** (repeated string):
+
+    Command line arguments for the mail delivery agent. One per argument.
+    Some replacements will be done.
+
+    On an email sent from marsnik@mars to venera@venus:
+
+        %from%        -> from address (marsnik@mars)
+        %from_user%   -> from user (marsnik)
+        %from_domain% -> from domain (mars)
+        %to%          -> to address (venera@venus)
+        %to_user%     -> to user (venera)
+        %to_domain%   -> to domain (venus)
+
+    Default: `"-f", "%from%", "-d", "%to_user%"`  (adequate for procmail and
+    maildrop).
+
+- **data\_dir** (string):
+
+    Directory where we store our persistent data. Default:
+    `/var/lib/chasquid`.
+
+- **suffix\_separators** (string):
+
+    Suffix separator, to perform suffix removal of local users.  For
+    example, if you set this to `-+`, email to local user `user-blah` and
+    `user+blah` will be delivered to `user`.  Including `+` is strongly
+    encouraged, as it is assumed for email forwarding.  Default: `+`.
+
+- **drop\_characters** (string):
+
+    Characters to drop from the user part on local emails.  For example, if
+    you set this to `._`, email to local user `u.se_r` will be delivered to
+    `user`.  Default: `.`.
+
+- **mail\_log\_path** (string):
+
+    Path where to write the mail log to.  If `<syslog>`, log using the
+    syslog (at `MAIL|INFO` priority).  If `<stdout>`, log to stdout; if
+    `<stderr>`, log to stderr.  Default: `<syslog>`.
+
+- **dovecot\_auth** (bool):
+
+    Enable dovecot authentication. If true, users that are not found in chasquid's
+    databases will be authenticated via dovecot.  Default: `false`.
+
+    The path to dovecot's auth sockets is autodetected, but can be manually
+    overridden using the `dovecot_userdb_path` and `dovecot_client_path` if
+    needed.
+
+- **haproxy\_incoming** (bool):
+
+    **EXPERIMENTAL**, might change in backwards-incompatible ways.
+
+    If true, expect incoming SMTP connections to use the HAProxy protocol.
+    This allows deploying chasquid behind a HAProxy server, as the address
+    information is preserved, and SPF checks can be performed properly.
+    Default: `false`.
+
+# SEE ALSO
+
+[chasquid(1)](chasquid.1.md)

docs/man/generate.sh

@@ -24,4 +24,7 @@ for IN in *.pod; do
 	pod2man --section="$SECTION" --name="$NAME" \
 		--release "" --center "" \
 		"$IN" "$OUT"
+	pod2markdown "$IN" \
+		| sed 's@\([a-z.-]\+\)(\([1-9]\))@[\1(\2)](\1.\2.md)@g' \
+		> "$OUT.md"
 done

docs/man/index.md

@@ -13,17 +13,13 @@ From the latest Debian package:
 - [smtp-check(1)](https://manpages.debian.org/unstable/chasquid/smtp-check.1):
   SMTP setup checker.
 
-From the development branch (more likely to change, but useful when doing
+From the current branch (more likely to change, but useful when doing
 development or running experimental versions):
 
-- [chasquid(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.1.pod):
-  the main binary.
-- [chasquid.conf(5)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.conf.5.pod):
-  the configuration file and structure.
-- [chasquid-util(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid-util.1.pod):
-  the command-line utility helper.
-- [mda-lmtp(1)](https://github.com/albertito/chasquid/blob/next/docs/man/mda-lmtp.1.pod):
-  helper to integrate with LMTP delivery.
-- [smtp-check(1)](https://github.com/albertito/chasquid/blob/next/docs/man/smtp-check.1.pod):
-  SMTP setup checker.
+- [chasquid(1)](chasquid.1.md): the main binary.
+- [chasquid.conf(5)](chasquid.conf.5.md): the configuration file and
+  structure.
+- [chasquid-util(1)](chasquid-util.1.md): the command-line utility helper.
+- [mda-lmtp(1)](mda-lmtp.1.md): helper to integrate with LMTP delivery.
+- [smtp-check(1)](smtp-check.1.md): SMTP setup checker.
 

docs/man/mda-lmtp.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================

docs/man/mda-lmtp.1.md

@@ -0,0 +1,62 @@
+# NAME
+
+mda-lmtp - MDA that uses LMTP to do the mail delivery
+
+# SYNOPSIS
+
+mda-lmtp
+\[**-addr\_network** _net_\]
+**-addr** _addr_
+**-d** _recipient_
+**-f** _from_
+
+# DESCRIPTION
+
+mda-lmtp is a very basic MDA that uses LMTP to do the mail delivery.
+
+It takes command line arguments similar to maildrop or procmail, reads an
+email via standard input, and sends it over the given LMTP server.  Supports
+connecting to LMTP servers over UNIX sockets and TCP.
+
+It can be used when your mail server does not support LMTP directly.
+
+# EXAMPLE
+
+**mda-lmtp** _--addr=localhost:1234_ _-f juan@casa_ _-d jose_ < email
+
+# OPTIONS
+
+- **-addr** _address_
+
+    LMTP server address to connect to.
+
+- **-addr\_network** _network_
+
+    Network of the LMTP address (e.g. _unix_ or _tcp_). If not present, it will
+    be autodetected from the address itself.
+
+- **-d** _recipient_
+
+    Recipient.
+
+- **-f** _from_
+
+    Whom the message is from.
+
+# RETURN VALUES
+
+- **0**
+
+    success
+
+- **75**
+
+    temporary failure
+
+- _other_
+
+    permanent failures (usually indicate misconfiguration)
+
+# SEE ALSO
+
+[chasquid(1)](chasquid.1.md)

docs/man/smtp-check.1

@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "smtp-check 1"
-.TH smtp-check 1 "2023-07-16" "" ""
+.TH smtp-check 1 "2023-07-14" "" ""
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

docs/man/smtp-check.1.md

@@ -0,0 +1,30 @@
+# NAME
+
+smtp-check - SMTP setup checker
+
+# SYNOPSIS
+
+**smtp-check** \[-port _port_\] \[-localname _domain_\] \[-skip\_tls\_check\] _domain_
+
+# DESCRIPTION
+
+smtp-check is a command-line too for checking SMTP setups (DNS records, TLS
+certificates, SPF, etc.).
+
+# OPTIONS
+
+- **-port** _port_:
+
+    Port to use for connecting to the MX servers.
+
+- **-localname** _domain_:
+
+    Local name to use for the EHLO command.
+
+- **-skip\_tls\_check**:
+
+    Skip TLS check (useful if connections are blocked).
+
+# SEE ALSO
+
+[chasquid(1)](chasquid.1.md)