diff --git a/man/dnsmanagerd.1 b/man/dnsmanagerd.1 new file mode 100644 index 0000000..ddd4a87 --- /dev/null +++ b/man/dnsmanagerd.1 @@ -0,0 +1,241 @@ +.\" .Xr = application with a manual page +.\" . = application with a manual page +.\" Recent mdoc style: +.Dd 24 november 2024 +.Dt "dnsmanagerd" 1 +.Os Linux "(Ubuntu and Alpine)" + +.Sh Name +.Nm dnsmanagerd +.Nd the DNS manager daemon. + +.Sh Description +The +.Nm dnsmanagerd +daemon is a micro-service providing DNS domains and zones management. + +.Sh Synopsis +. +.Nm dnsmanagerd +.Op Fl snREh +.Op Fl v Ar verbosity +.Op Fl -project Ar project-name +. +.Op Fl s Ar service-name +.Op Fl r Ar path +.Op Fl l Ar login +.Op Fl p Ar password + +.Sh Configuration +Most of the actual configuration will reasonably come from a configuration file, not from command line parameters. + +By default, configuration is read from +.Pa $XDG_CONFIG_HOME/baguette/dnsmanager.yml +or +.Pa /etc/baguette/dnsmanager.yml . + +Configuration file is in YAML, see the following example: + +.in +4 +.nf +recreate_indexes: true +accepted_domains: + - netlib.re + - codelib.re +.fi +.in + +In this example, indexes are recreated, which is related to the +.Xr dodb 7 +document database, see the related manual page to learn more. +Also, there is a list of accepted domains for +.Xr dnsmanagerd +to handle. + +.Sh Configuration file variables +The following presents the complete list of configuration file variables. + +Generic +.Xr libipc 7 +related variables: +. +.Bl -tag -width " print functions" -compact +.It Li ipc_timer +Int32, 30_000 (30 seconds) +. +.It Li verbosity +Int32, 4 ([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. + +.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 +.El +. +.El + +Specific +.Xr dnsmanagerd +variables: +.Bl -tag -width "template_directory" -compact +.It Li service_name +String, +.Dq dnsmanager +(\c +.Xr libipc 7 +unix socket name) + +.It Li recreate_indexes +Bool, false (see +.Xr dodb 7 +man-page) +.It Li storage_directory +String, +.Pa ./storage +(see +.Xr dodb 7 +man-page) + +.It Li login +.Xr dnsmanagerd +needs to connect itself to +.Xr authd 1 +with an admin account to then authenticate its users. + +String, +.Dq dnsmanager +.It Li pass +String?, +.Em none + +.It Li template_directory +New domains require to load a template so users won't have to enter some necessary entries themselves. +For example, SOA and NS RRs are pre-loaded and updated by an administrator when required. +.br +See +.Pa tools/write-template-zone-file.cr + +String, +.Pa /etc/dnsmanager/templates + +.It Li accepted_domains +List of all accepted domains. Example: netlib.re. + +Array of String, [] +.El + +.Sh Options +.Bl -tag -width "-t activation-template-name," +.It Li -s , --simulation +Print configuration then quit. +. +.It Li -n , --no-configuration +No configuration file should be read. +. +.It Li -v No verbosity , Li --verbosity No level +Verbosity level. From 0 to 4. Default: 4. +. +.It Li --project No project-name +Project name, used for slotting to enable several instances of +.Nm authd +to run at the same time. +Will search in +.Pa $XDG_CONFIG_HOME/baguette//auth.yml +then +.Pa /etc/baguette//auth.yml . +. +.It Li -h , --help +Show some help, but won't cover as much as the actual manual. +. +.It Li --service_name No name +Name of the +.Xr libipc 7 +unix socket used by +.Xr dnsmanagerd +to be contacted. + +.It Fl r No storage-directory , Fl -root No directory +Path of the directory where the +.Xr dnsmanagerd +database is stored. +See +.Xr dodb 7 +for more information. +. +.El + +Options related to the +.Xr authd 1 +service used by +.Xr dnsmanagerd +to authenticate users (see +.Sx Configuration file variables ) . +Of course, it is preferable to get these parameters from a private configuration file. + +.Bl -tag -width "template_directory" -compact +.It Fl l No login , Fl -login No login +. +.It Fl p No password , Fl -pass No password +.El +. +.Sh Detailed description +The code is based on the +.Nm libipc +library and (trivial) JSON requests, enabling a simple API. + +TODO: expand the documentation +.Sh See also +TODO: expand the documentation + +.Bl -tag -width "Xr libipc" -compact +. +.It Xr libipc 7 +the documentation of the way libipc works +. +.It Xr dnsmanager-client 1 +a command-line-interface client for +.Xr dnsmanagerd +. +.It Xr authd 1 +an authentication and authorization micro-service used by +.Xr dnsmanagerd +to handle users (authentication, authorization, preferences and profile) +. +.It Xr authc 1 +a command-line-interface client for +.Xr authd +. +.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 +TODO: expand the documentation