Man pages: authd update and new authc documentation.

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

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