Authd man-page.
This commit is contained in:
parent
029b0532bc
commit
437a6d5d88
175
man/authd.1
Normal file
175
man/authd.1
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user