dnsmanager/man/dnsmanagerd.1

.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 snh
.Op Fl v Ar verbosity
.Op Fl -project Ar project-name
.Op Fl -configuration Ar file
.
.Op Fl -service-name Ar name
.Op Fl -storage-directory Ar path
.Op Fl -recreate-indexes
.
.Op Fl -accepted-domains Ar domains
.Op Fl -template-directory Ar dir
.
.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
document database, see the related documentation 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
.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
.br
[0-4],
.Dq 0
being quiet and
.Dq 4
meaning printing debug values.

.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 dnsmanager :
.Vt IPCMESSAGE .

.It Li service_name
String,
.Dq dnsmanager
.br
.Xr libipc 7
unix socket name.
.El

Specific
.Xr dnsmanagerd
variables:
.Bl -tag -width "template_directory" -compact
.It Li log_file
String?,
.Em none
.br
Path to the log file.

.It Li messages_to_mask
Array of
.Vt DNSManager::MESSAGE ,
.Em [ KEEPALIVE ]
.br
List of high-level
.Em dnsmanagerd
messages to mask in the logs.
.br
The type
.Vt DNSManager::MESSAGE
has an alias:
.Vt DNSMESSAGE .

.It Li recreate_indexes
Bool, false
.br
See
.Xr DoDB
documentation.

.It Li storage_directory
String,
.Pa ./db-dnsmanagerd
.br
See
.Xr DoDB
documentation.

.It Li login
String,
.Dq dnsmanager
.br
.Xr dnsmanagerd
needs to connect itself to
.Xr authd 1
with an admin account to then authenticate its users.

.It Li pass
String?,
.Em none

.It Li template_directory
String,
.Pa /etc/dnsmanager/templates
.br
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

.It Li accepted_domains
Array of String, []
.br
List of all accepted domains. Example: netlib.re.
.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 --configuration No file
Alternative configuration file.

.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/<project-name>/auth.yml
then
.Pa /etc/baguette/<project-name>/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 -recreate-indexes
Recreate database indexes (symbolic links).

.It Fl -storage-directory No dir
Path of the directory where the
.Xr dnsmanagerd
database is stored.
See the
.Xr DoDB
documentation.

.It Fl -accepted-domains No domains
Accepted domains, coma separated.
.br
For example: netlib.re,example.com

.It Fl -template-directory No dir
Directory containing domain templates which are used when creating a new domain.
Templates can be generated by
.Xr write-template-zone-file .
.br
See the following command:
.Nm "write-template-zone-file netlib.re"
.br
This command generates a file
.Pa netlib.re.json
that can be used as a template.
.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 dnsmanagerctl 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 authctl 1
a command-line-interface client for
.Xr authd
.
.It Xr mailer 1
a simple executable to send mails based on templates
.El

The Document-oriented DataBase (DoDB) library used in
.Xr dnsmanagerd .
.br
.Lk https://git.baguette.netlib.re/Baguette/dodb.cr dodb

The online service
.Dq netlib.re
provides an interface for the
.Xr dnsmanagerd
daemon.
.br
.Lk https://www.netlib.re netlib.re

The source code of the web interface:
.br
.Lk https://git.baguette.netlib.re/Baguette/dnsmanager-webclient web-client

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
TODO: expand the documentation