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 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 ./db-dnsmanagerd
(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 --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
.Xr dodb 7
for more information.
.

.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
.
.It Xr dodb 7
a document database library used in
.Xr authd .
.El

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

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


.Sh Limitations
TODO: expand the documentation