302 lines
6.2 KiB
Groff
302 lines
6.2 KiB
Groff
.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
|