From 437a6d5d884fb7611736673350503742616ca731 Mon Sep 17 00:00:00 2001
From: Philippe Pittoli <karchnu@karchnu.fr>
Date: Sat, 30 Nov 2024 19:41:12 +0100
Subject: [PATCH] Authd man-page.

---
 man/authd.1 | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 man/authd.1

diff --git a/man/authd.1 b/man/authd.1
new file mode 100644
index 0000000..3594edb
--- /dev/null
+++ b/man/authd.1
@@ -0,0 +1,175 @@
+.\" .Xr = application with a manual page
+.\" . = application with a manual page
+.\" Recent mdoc style:
+.Dd 24 november 2024
+.Dt "authd" 1
+.Os Linux "(Ubuntu and Alpine)"
+
+.Sh Name
+.Nm authd
+.Nd the authentication daemon.
+
+.Sh Description
+The
+.Nm authd
+daemon is a micro-service providing authentication and authorization services.
+
+.Sh Synopsis
+.
+.Nm authd
+.Op Fl snREh
+.Op Fl k Ar key-file
+.Op Fl v Ar verbosity
+.Op Fl -project Ar project-name
+.Op Fl -storage Ar path
+.Op Fl t Ar account-activation-template
+.Op Fl r Ar account-recovery-template
+.Op Fl m Ar mailer
+.Op Fl x Ar read-only-key
+
+.Sh Configuration
+Most of the actual configuration will reasonably come from a configuration file, not from command line parameters.
+
+By default, configuration is read from
+.Pa $XDG_CONFIG_HOME/baguette/auth.yml
+or
+.Pa /etc/baguette/auth.yml .
+
+Configuration file is in YAML, see the following example:
+
+.in +4
+.nf
+mailer_exe: /home/john/mailer
+secret_key_file: /var/authd/secret-password
+recreate_indexes: true
+.fi
+.in
+
+In this example, the path to a custom
+.Xr mailer
+application is configured.
+.br
+The
+.Dq "master password"
+used by
+.Xr authd
+to encrypt users's password is read from the file
+.Pa /var/authd/secret-password .
+.br
+Finally, indexes are recreated, which is related to the
+.Xr dodb 7
+document database, see the related manual page to learn more.
+
+.Sh Options
+.Bl -tag -width "-t activation-template-name,"
+.It Li -s , --simulation
+Print configuration then quit.
+.
+.It Li -n , --no-configuration
+No configuration file should be read.
+.
+.It Li -v No verbosity , Li --verbosity No level
+Verbosity level. From 0 to 4. Default: 4.
+.
+.It Li --project No project-name
+Project name, used for slotting to enable several instances of
+.Nm authd
+to run at the same time.
+Will search in
+.Pa $XDG_CONFIG_HOME/baguette/<project-name>/auth.yml
+then
+.Pa /etc/baguette/<project-name>/auth.yml .
+.
+.It Li -h , --help
+Show some help, but won't cover as much as the actual manual.
+.
+.It Li --storage No directory
+Directory in which to store users.
+.
+.It Li -k No file , Li --key-file No file
+JWT key file.
+.
+.It Li -R , --allow-registrations
+Allow user registration.
+.
+.It Li -E , --require-email
+Require an email from users at registration.
+.
+.It Li -t No activation-template-name , Li --activation-template No name
+Email activation template.
+.
+.It Li -r No recovery-template-name , Li --recovery-template No name
+Email recovery template.
+.
+.It Li -m No mailer-exe , Li --mailer No mailer-exe
+Application to send registration emails.
+.
+.It Li -x No key , Li --read-only-profile-key No key
+Mark a user profile key as being read-only.
+.El
+.
+.Sh Detailed description
+The code is based on the
+.Nm libipc
+library and (trivial) JSON requests, enabling a simple API.
+.
+.Sh Required tooling for user registration
+Two applications are required for
+.Xr authd
+to send emails upon user registration: an SMTP server and a
+.Xr mailer ,
+an application that is called upon user registration.
+
+The
+.Xr mailer 1
+application takes three parameters: "send", a template name and the target email address.
+This application also takes two environment variables: LOGIN and TOKEN.
+See
+.Pa src/process.cr .
+.br
+Example:
+.br
+$ LOGIN=john TOKEN=a-b-c-d
+.Nm mailer
+send registration-template 'john@example.com'
+
+An example of such mailer can be found here:
+.br
+.Lk https://git.baguette.netlib.re/Baguette/mailer mailer
+
+.Sh See also
+TODO: expand the documentation
+
+.Bl -bullet
+.
+.It
+.Xr libipc 7
+the documentation of the way libipc works
+.
+.It
+.Xr authc 1
+a command-line-interface client for
+.Xr authd
+.
+.It
+.Xr dnsmanagerd 1
+a DNS manager service using
+.Xr authd
+to handle users (authentication, authorization, preferences and profile)
+.
+.It
+.Xr mailer 1
+a simple executable to send mails based on templates
+.
+.It
+.Xr dodb 7
+a document database library used in
+.Xr authd .
+.El
+
+.Sh Limitations
+WARNING:
+.Xr authd
+doesn't handle all possible email addresses.
+
+TODO: expand the documentation