277 lines
4.8 KiB
Groff
277 lines
4.8 KiB
Groff
.\" .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
|