authd/man/authd.1

.\" .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 Configuration file variables
The following presents the complete list of configuration file variables.

Generic
.Xr libipc 7
related variables:
.
.Bl -tag -width " print functions" -compact
.It Li ipc_timer
Int32, 30_000 (30 seconds)
.
.It Li verbosity
Int32, 4 ([0-4],
.Dq 0
being quiet and
.Dq 4
meaning printing debug values)
.
.It Li print functions
Print functions enable to select messages to print, for example by printing a message each time a message is received while ignoring keepalive messages.

.Bl -tag -width " print_ipc_message_received" -compact
.It Li print_ipc_timer
Bool, false
.It Li print_ipc_connection
Bool, false
.It Li print_ipc_disconnection
Bool, false
.It Li print_ipc_extra_socket
Bool, false
.It Li print_ipc_message_received
Bool, false
.It Li print_ipc_message_sent
Bool, false
.It Li print_ipc_switch
Bool, false
.It Li print_ipc_error
Bool, true
.It Li print_ipc_exception
Bool, true
.It Li print_keepalive
Bool, false
.El
.
.El

Specific
.Xr authd
variables:
.Bl -tag -width " print_password_recovery_parameters" -compact
.It Li service_name
String,
.Dq auth
.It Li recreate_indexes
Bool, false
.It Li storage
String,
.Pa ./storage
.It Li registrations
Bool, false
.It Li require_email
Bool, false
.It Li activation_template
String,
.Dq email-activation
.It Li recovery_template
String,
.Dq email-recovery
.It Li mailer_exe
String,
.Pa /usr/local/bin/mailer
.It Li read_only_profile_keys
Array of String, []
.It Li print_password_recovery_parameters
Bool, false
.El

.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:
.Ev LOGIN
and
.Ev 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 -compact
.
.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