From 0397c51adb5b1c7371aff57265f7ba09a8363ba6 Mon Sep 17 00:00:00 2001 From: Philippe Pittoli Date: Sun, 1 Dec 2024 12:34:18 +0100 Subject: [PATCH] Man pages: authd update and new authc documentation. --- man/authc.1 | 276 ++++++++++++++++++++++++++++++++++++++++++++++++++++ man/authd.1 | 5 +- 2 files changed, 280 insertions(+), 1 deletion(-) create mode 100644 man/authc.1 diff --git a/man/authc.1 b/man/authc.1 new file mode 100644 index 0000000..56c12f7 --- /dev/null +++ b/man/authc.1 @@ -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 diff --git a/man/authd.1 b/man/authd.1 index 60d26f0..a398cb8 100644 --- a/man/authd.1 +++ b/man/authd.1 @@ -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