308 lines
6.3 KiB
Groff
308 lines
6.3 KiB
Groff
.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
|