authd/man/authd.1

.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 -configuration Ar file
.Op Fl -project Ar project-name
.
.Op Fl -storage-directory Ar path
.Op Fl -service-name Ar name
.Op Fl -recreate-indexes
.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
document database, see the related documentation 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
.br
The IPC timer wakes the process by default every 30 seconds.
There is no much point changing this value since nothing is executed periodically anyway, at least for now.

.It Li verbosity
Int32, 4
.br
[0-4],
.Dq 0
being quiet and
.Dq 4
meaning printing debug values.

.It Li ipc_messages_to_show
Array of
.Vt Baguette::Configuration::IPC::MESSAGE ,
[ERROR, EXCEPTION]

Types of IPC messages to print, for example all connections.
This is mainly for debug since it is very low-level.
High-level messages are more relevant to log.
By default, errors and exceptions are logged.

See
.Xr Baguette-crystal-base ,
which includes the
.Vt Baguette::Configuration::IPC::MESSAGE
definition.
This type has an alias in
.Xr authd :
.Vt IPCMESSAGE .

.It Li service_name
String,
.Dq auth
.br
.Xr libipc 7
unix socket name.
.El
.El

Specific
.Xr authd
variables:
.Bl -tag -width " print_password_recovery" -compact
.It Li log_file
String?,
.Em none
.br
Path to the log file.

.It Li messages_to_mask
Array of
.Vt AuthD::MESSAGE ,
.Em [ KEEPALIVE ]
.br
List of high-level
.Em authd
messages to mask in the logs.
.br
The type
.Vt AuthD::MESSAGE
has an alias:
.Vt AUTHMESSAGE .

.It Li recreate_indexes
Bool, false
.It Li storage_directory
String,
.Pa ./db-authd
.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 --configuration No file
Alternative configuration file.
.
.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 --service-name No service_name
Service name (IPC).
.
.It Li --recreate-indexes
Recreate database indexes (symbolic links).
.
.It Li --storage-directory 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 authctl 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
.El

The Document-oriented DataBase (DoDB) library used in
.Xr authd .
.br
.Lk https://git.baguette.netlib.re/Baguette/dodb.cr dodb

The online service
.Dq netlib.re
is the first one to use the
.Xr authd
daemon.
.br
.Lk https://www.netlib.re netlib.re

The logging and configuration library for the whole
.Dq baguette
project.
.br
.Lk https://git.baguette.netlib.re/Baguette/baguette-crystal-base baguette-crystal-base

.Sh Limitations
WARNING:
.Xr authd
doesn't handle all possible email addresses.

TODO: expand the documentation