Man pages: authd update and new authc documentation.
This commit is contained in:
parent
173a5e18a1
commit
0397c51adb
276
man/authc.1
Normal file
276
man/authc.1
Normal file
@ -0,0 +1,276 @@
|
||||
.\" .Xr = application with a manual page
|
||||
.\" . = application with a manual page
|
||||
.\" Recent mdoc style:
|
||||
.Dd 24 november 2024
|
||||
.Dt "authc" 1
|
||||
.Os Linux "(Ubuntu and Alpine)"
|
||||
|
||||
.Sh Name
|
||||
.Nm authc
|
||||
.Nd a client for the
|
||||
.Xr authd 1
|
||||
authentication daemon.
|
||||
|
||||
.Sh Description
|
||||
.Nm authc
|
||||
is a client for the
|
||||
.Xr authd 1
|
||||
daemon, a micro-service providing authentication and authorization services.
|
||||
|
||||
.Sh Synopsis
|
||||
.
|
||||
.Nm authc
|
||||
.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 authc
|
||||
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 authc
|
||||
.Ar bootstrap No
|
||||
.Ar login
|
||||
.Ar email-address
|
||||
|
||||
(Temporary, will be removed someday) add a batch of users from old code base.
|
||||
.br
|
||||
.Nm authc
|
||||
.Ar migration-script No
|
||||
|
||||
|
||||
Operations on users.
|
||||
.br
|
||||
.Nm authc
|
||||
.Ar user No
|
||||
.Ar subcommand No
|
||||
|
||||
.Ar subcommand : No
|
||||
.in +4
|
||||
.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 authc
|
||||
.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 authc
|
||||
.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 authc
|
||||
.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
|
||||
.
|
||||
.It
|
||||
.Xr dodb 7
|
||||
a document database library used in
|
||||
.Xr authd .
|
||||
.El
|
||||
|
||||
.Sh Limitations
|
||||
WARNING:
|
||||
.Xr authc
|
||||
doesn't handle all possible commands of the
|
||||
.Xr authd
|
||||
application.
|
||||
|
||||
TODO: expand the documentation
|
@ -200,7 +200,10 @@ 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.
|
||||
This application also takes two environment variables:
|
||||
.Ev LOGIN
|
||||
and
|
||||
.Ev TOKEN .
|
||||
See
|
||||
.Pa src/process.cr .
|
||||
.br
|
||||
|
Loading…
Reference in New Issue
Block a user