.\" .Xr = application with a manual page
.\" . = application with a manual page
.\" Recent mdoc style:
.Dd 24 november 2024
.Dt "authctl" 1
.Os Linux "(Ubuntu and Alpine)"

.Sh Name
.Nm authctl
.Nd a client for the
.Xr authd 1
authentication daemon.

.Sh Description
.Nm authctl
is a client for the
.Xr authd 1
daemon, a micro-service providing authentication and authorization services.

.Sh Synopsis
.
.Nm authctl
.Op Fl h
.Ar COMMAND No
.Op Ar help
.Op Fl v Ar verbosity
.Op Fl -project Ar project-name
.in

.Ar COMMAND No
can be:

.Bl -tag -width " print functions" -compact
.It Li bootstrap
Add the first user (an admin).
.It Li migration-script
Adding a batch of users from old code base.
.It Li user
Operations on users.
.It Li permission
Permissions management.
.El

After the command is passed, you can always put the
.Ar -h No
flag to learn about the next parameters to give.

.Sh Configuration
Some parameters will reasonably come from a configuration file instead of the command-line interface, at least for
.Dq login
and
.Dq password .

By default, configuration is read from
.Pa $XDG_CONFIG_HOME/baguette/auth.yml
or
.Pa /etc/baguette/auth.yml ,
exactly as the
.Xr authd 1
daemon.

Configuration file is in YAML, see the following example:

.in +4
.nf
login: john42
password: banana
.fi
.in

In this example, the login and password of the user are set.
The
.Xr authctl
application won't require them as command-line parameters for performing authenticated actions.

.Sh Configuration file variables
The following presents the complete list of configuration file variables.

.Bl -tag -width "Li password" -compact
.It Li verbosity
Int32, 4 ([0-4],
.Dq 0
being quiet and
.Dq 4
meaning printing debug values)
.
.It Li login
String, empty by default.
.
.It Li password
String, empty by default.
.El

.Sh Options
.Bl -tag -width "-t activation-template-name,"
.It Li -v No verbosity , Li --verbosity No level
Verbosity level. From 0 to 4. Default: 4.
.
.It Li -h , --help
Show some help, but won't cover as much as the actual manual.
.El

.Sh Detailed command arguments

Add the first user (will automatically be an admin).
.br
.Nm authctl
.Ar bootstrap No
.Ar login
.Ar email-address

(Temporary, will be removed someday) add a batch of users from old code base.
.br
.Nm authctl
.Ar migration-script No


Operations on users.
.br
.Nm authctl
.Ar user No
.Ar subcommand No
.br
.in +4
Subcommands:
.Bl -tag -width "change-password" -compact
.It Li add
Adding a user to the DB.
.It ""
.Nm add
.Ar login
.Ar email-address

.It Li migrate
Adding a user from old code base.
.It ""
.Nm migrate
.Ar login
.Ar hashed-password-old-algorithm

.It Li mod
Modify a user account.
.It ""
.Nm mod
.Ar userid
.Bq Fl e Ar email | Fl P Ar profile

.It Li change-password
Change the password of a user (requires admin).
.It ""
.Nm change-password
.Ar userid

.It Li delete
Remove user.
.It ""
.Nm delete
.Ar userid

.It Li validate
Validate user.
.It ""
.Nm validate
.Ar login
.Ar activation-key

.It Li get
Get user info.
.It ""
.Nm get
.Ar login

.It Li search
Search user.
.It ""
.Nm search
.Ar login

.It Li recover
Recover user password.
.It ""
.Nm recover
.Ar login

.It Li register
Register a user (requires activation from the token sent by email).
.It ""
.Nm register
.Ar login
.Ar email-address
.El

(PS: use
.Ar -h No
to learn more about the parameters and options of the subcommands.)
.in -4

Operations on permissions.
.br
.Nm authctl
.Ar permission No
.Brq set \*(Ba check

.Bl -tag -width "check" -compact
.It Li set
permission set user-id application resource permission
.br
Available permissions:
.Em none read edit admin .
.It ""
Example:
.Nm authctl
.Ar permission set 1000 dnsmanager
"*"
.Ar edit

.It Li check
permission check user-id application resource
.br
Available permissions:
.Em none read edit admin .
.It ""
Example:
.Nm authctl
.Ar permission check 1000 forum
"/thread15/"
.El

.in +4
(PS: use
.Ar -h No
to learn more about the parameters and options of the subcommands.)
.in -4

.Sh Detailed description
The code is based on the
.Nm libipc
library and (trivial) JSON requests, enabling a simple API to exchange messages between two applications on the same machine.

.Sh See also
TODO: expand the documentation

.Bl -bullet -compact
.
.It
.Xr libipc 7
the documentation of the way libipc works
.
.It
.Xr authd 1
the authentication and authorization daemon related to this client.
.
.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

.Sh Limitations
WARNING:
.Xr authctl
doesn't handle all possible commands of the
.Xr authd
application.

TODO: expand the documentation