infrastructure-doc/man/netlibre.8

.\" Some useful macros.
.de cmd
.Nd "\\$*"
.br
..
.de path
.Nm "\\$*"
..
.de cmdname
.Nm "\\$*"
..
.de TITLE
.Sh "\\$*"
..
.de SUBTITLE
.Nm "\\$*"
.br
..
.
.\" Old manpage style:
.\" .TH deployment 7 "24th november 2024" "netlib.re" "deployment manual"
.
.\" Recent mdoc style:
.Dd 24 november 2024
.Dt "netlib.re deployment" 8
.Os Linux "(Ubuntu and Alpine)"
.
.TITLE NETLIB.RE DEPLOYMENT
This manual page serves as documentation for the deployment and maintenance of the netlib.re service.
The following subjects will be covered.

.Nm "tooling"
.Nd "both custom and the already packaged ones"
.br
.Nm "config"
.Nd "how to deploy from scratch"
.br
.Nm "testing"
.Nd "how to do some testing"
.br
.Nm "limitations"
.Nd "what could go wrong and what's to anticipate"

The deployment was done on two machines:
.br
.Nm BAGUETTE
(primary)
.Nd 89.234.141.125, ns0.karchnu.fr
.br
.Nm GANDI
(secondary)
.Nd 92.243.18.19, ns1.karchnu.fr

.TITLE TOOLING
.Nm authd
(custom)
.Nd the authentication daemon
.br
.Nm dnsmanagerd
(custom)
.Nd the dns manager daemon
.br
.Nm mailer
(custom)
.Nd a simple executable to send template mails
.br
.Nm watchdog scripts
(custom)
.Nd to sync directories between primary and secondary NS
.br
.Nm smtp server
(such as OpenSMTPd)
.Nd to send registration and password recovery emails
.br
.Nm inotifywait
.Nd wait for changes on the file system (used for domain sync)
.br
.Nm "dig, ss and netstat"
.Nd to test the name servers and to debug network-related stuff

.TITLE DEPLOYMENT
.SUBTITLE install powerdns
.cmd ubuntu $ apt install pdns-server pdns-backend-bind
.cmd alpine $ apk add pdns pdns-backend-bind

.SUBTITLE stop (and disable) systemd-resolved
This tool prevents powerdns to start since it works on the same port (53).
.br
.cmd ubuntu $ systemctl stop systemd-resolved
.cmd ubuntu $ systemctl disable systemd-resolved
.cmd alpine $ no systemd-resolved by default on this system

.SUBTITLE run powerdns
.cmd ubuntu $ systemctl restart pdns
.cmd alpine $ service pdns restart
NOTE : powerdns documentation on alpine is basically just a lot of SQL files in /usr/share/doc/pdns/

.SUBTITLE install inotify-tools
.cmd ubuntu $ apt install inotify-tools
.cmd alpine $ apk add inotify-tools

.SUBTITLE install an smtp server
.cmd alpine $ apk add opensmtpd
Actual configuration of the smtp (+SPF, DKIM, etc.) should be taken care of.
An example of OpenSMTPd configuration is in this repository (infrastructure-doc).

.TITLE TESTING TOOLS
.SUBTITLE testing port 53
.cmd ubuntu $ ss -pln | grep :53
.cmd alpine $ netstat -ta

.SUBTITLE install dig
.cmd ubuntu $ apt install dnsutils
.cmd alpine $ already installed?

.SUBTITLE testing the deployment and zone updates
.cmd $ dig @ns0.karchnu.fr <domain>

.TITLE CONFIGURATION and ZONE UPDATES
Well, there isn't much configuration since both powerdns instances just run "as is" with the bind backend that is filled on-the-fly.

.SUBTITLE watchdogs in a few words
A watchdog is (in this context) a command watching a directory.
These commands should run either on the primary or secondary name server.
They are distributed with
.cmdname dnsmanagerd
in the
.path deployment
directory.

.SUBTITLE primary-watchdog.sh (on primary)
Reads file in
.path /var/powerdns
and run a command (pdns_control bind-reload-now) to update the zone, then send the new (or updated) file on the secondary name server.
In case the domain wasn't already served, the domain is added (pdns_control bind-add-zone).

.SUBTITLE secondary-watchdog.sh (on secondary)
Same as primary-watchdog.sh but without remote operations.

.SUBTITLE primary-dnsmanagerd-to-powerdns.sh (on primary)
TODO: explanations, why doesn't dnsmanagerd use
.path /var/powerdns
directly?
.\" Since there is a migration to handle,
.\" .cmdname dnsmanagerd
.\" writes bind9 files in a temporary directory before being sent to /var/powerdns.
.\" This enables to first load old zones (they are still served as before) then to update them on-the-fly once the users make changes on the new website.

TODO: expand the documentation

.TITLE LIMITATIONS
TODO: expand the documentation