From 4cd40ef8a62391057aa5643b6a4a512fa9eb5730 Mon Sep 17 00:00:00 2001
From: Philippe Pittoli <karchnu@karchnu.fr>
Date: Fri, 13 Dec 2024 01:42:21 +0100
Subject: [PATCH] `authd` man-page update regarding logging facility, mostly.

---
 man/authd.1 | 116 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 76 insertions(+), 40 deletions(-)

diff --git a/man/authd.1 b/man/authd.1
index 305e179..5624d5c 100644
--- a/man/authd.1
+++ b/man/authd.1
@@ -58,8 +58,8 @@ to encrypt users's password is read from the file
 .Pa /var/authd/secret-password .
 .br
 Finally, indexes are recreated, which is related to the
-.Xr dodb 7
-document database, see the related manual page to learn more.
+.Xr DoDB
+document database, see the related documentation to learn more.
 
 .Sh Configuration file variables
 The following presents the complete list of configuration file variables.
@@ -70,50 +70,72 @@ related variables:
 .
 .Bl -tag -width " print functions" -compact
 .It Li ipc_timer
-Int32, 30_000 (30 seconds)
-.
+Int32, 30_000
+.br
+The IPC timer wakes the process by default every 30 seconds.
+There is no much point changing this value since nothing is executed periodically anyway, at least for now.
+
 .It Li verbosity
-Int32, 4 ([0-4],
+Int32, 4
+.br
+[0-4],
 .Dq 0
 being quiet and
 .Dq 4
-meaning printing debug values)
-.
-.It Li print functions
-Print functions enable to select messages to print, for example by printing a message each time a message is received while ignoring keepalive messages.
+meaning printing debug values.
 
-.Bl -tag -width " print_ipc_message_received" -compact
-.It Li print_ipc_timer
-Bool, false
-.It Li print_ipc_connection
-Bool, false
-.It Li print_ipc_disconnection
-Bool, false
-.It Li print_ipc_extra_socket
-Bool, false
-.It Li print_ipc_message_received
-Bool, false
-.It Li print_ipc_message_sent
-Bool, false
-.It Li print_ipc_switch
-Bool, false
-.It Li print_ipc_error
-Bool, true
-.It Li print_ipc_exception
-Bool, true
-.It Li print_keepalive
-Bool, false
+.It Li ipc_messages_to_show
+Array of
+.Vt Baguette::Configuration::IPC::MESSAGE ,
+[ERROR, EXCEPTION]
+
+Types of IPC messages to print, for example all connections.
+This is mainly for debug since it is very low-level.
+High-level messages are more relevant to log.
+By default, errors and exceptions are logged.
+
+See
+.Xr Baguette-crystal-base ,
+which includes the
+.Vt Baguette::Configuration::IPC::MESSAGE
+definition.
+This type has an alias in
+.Xr authd :
+.Vt IPCMESSAGE .
+
+.It Li service_name
+String,
+.Dq auth
+.br
+.Xr libipc 7
+unix socket name.
 .El
-.
 .El
 
 Specific
 .Xr authd
 variables:
-.Bl -tag -width " print_password_recovery_parameters" -compact
-.It Li service_name
-String,
-.Dq auth
+.Bl -tag -width " print_password_recovery" -compact
+.It Li log_file
+String?,
+.Em none
+.br
+Path to the log file.
+
+.It Li messages_to_mask
+Array of
+.Vt AuthD::MESSAGE ,
+.Em [ KEEPALIVE ]
+.br
+List of high-level
+.Em authd
+messages to mask in the logs.
+.br
+The type
+.Vt AuthD::MESSAGE
+has an alias:
+.Vt AUTHMESSAGE .
+
 .It Li recreate_indexes
 Bool, false
 .It Li storage_directory
@@ -250,13 +272,27 @@ 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
 
+The Document-oriented DataBase (DoDB) library used in
+.Xr authd .
+.br
+.Lk https://git.baguette.netlib.re/Baguette/dodb.cr dodb
+
+The online service
+.Dq netlib.re
+is the first one to use the
+.Xr authd
+daemon.
+.br
+.Lk https://www.netlib.re netlib.re
+
+The logging and configuration library for the whole
+.Dq baguette
+project.
+.br
+.Lk https://git.baguette.netlib.re/Baguette/baguette-crystal-base baguette-crystal-base
+
 .Sh Limitations
 WARNING:
 .Xr authd