.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//auth.yml then .Pa /etc/baguette//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