- 1. Overview
- 2. Prerequisites
- 3. Installation on Rocky Linux
- 4. Installation on Debian and Ubuntu
- 5. Installation on FreeBSD
- 6. Installation on CentOS Linux 7
- 7. Post-installation
- 8. Installation with MariaDB
- 9. Installation with PostgreSQL
- 10. Cleaning up the database
- 11. Optional features
This document contains all steps needed to install Zonemaster::Backend. For an overview of the Zonemaster product, please see the main Zonemaster Repository.
If you upgrade your Zonemaster installation with a newer version of Zonemaster::Backend instead, and want to keep the database, then see the Upgrade document. Otherwise remove the database and continue with this installation document.
Before installing Zonemaster::Backend, you should install Zonemaster::Engine.
Note: Zonemaster::Engine and Zonemaster::LDNS are dependencies of Zonemaster::Backend. Zonemaster::LDNS has a special installation requirement, and Zonemaster::Engine has a list of dependencies that you may prefer to install from your operating system distribution (rather than CPAN). We recommend following the Zonemaster::Engine installation instruction.
Prerequisite for FreeBSD is that the package system is updated and activated (see the FreeBSD section of Zonemaster::Engine installation).
For details on supported versions of Perl, database engine and operating system for Zonemaster::Backend, see the declaration of prerequisites.
Note: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.
Install dependencies available from binary packages:
sudo dnf -y install jq perl-Class-Method-Modifiers perl-Config-IniFiles perl-DBD-SQLite perl-DBI perl-HTML-Parser perl-JSON-RPC perl-libwww-perl perl-Log-Dispatch perl-Mojolicious perl-Net-Server perl-Parallel-ForkManager perl-Plack perl-Plack-Test perl-Role-Tiny perl-Router-Simple perl-String-ShellQuote perl-Test-Differences perl-Test-Exception perl-Test-Mojo perl-Test-NoWarnings perl-Test-Warn perl-Try-Tiny perl-libintl redhat-lsb-coreNote: perl-Net-Server and perl-Test-Warn are listed here even though they are not direct dependencies. They are transitive dependencies with build problems when installed using cpanm.
Install dependencies not available from binary packages:
sudo cpanm Daemon::Control JSON::Validator Log::Any Log::Any::Adapter::Dispatch Starman Plack::Middleware::ReverseProxyInstall Zonemaster::Backend:
sudo cpanm Zonemaster::BackendThe command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.
Add Zonemaster user (unless it already exists):
sudo useradd -r -c "Zonemaster daemon user" zonemasterInstall files to their proper locations:
cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -d /etc/zonemaster
sudo install -v -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -v -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -v -m 755 ./zm-rpcapi.lsb /etc/init.d/zm-rpcapi
sudo install -v -m 755 ./zm-testagent.lsb /etc/init.d/zm-testagent
sudo install -v -m 755 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.confCheck the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
The installation instructions below assumes that this is a new installation.
Note: Zonemaster with SQLite is not meant for an installation with heavy load.
Create database directory:
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemasterSome parameters can be changed, see the backend configuration documentation for details.
See sections for MariaDB and PostgreSQL.
Create the database tables:
sudo -u zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.plMake sure our tmpfiles configuration takes effect:
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.confEnable services at boot time and start them:
sudo systemctl enable zm-rpcapi
sudo systemctl enable zm-testagent
sudo systemctl start zm-rpcapi
sudo systemctl start zm-testagentSee the post-installation section for post-installation matters.
Note: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.
Install required locales:
sudo perl -pi -e 's/^# (da_DK\.UTF-8.*|en_US\.UTF-8.*|es_ES\.UTF-8.*|fi_FI\.UTF-8.*|fr_FR\.UTF-8.*|nb_NO\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
sudo locale-genAfter the update, locale -a should at least list the following locales:
da_DK.utf8
en_US.utf8
es_ES.utf8
fi_FI.utf8
fr_FR.utf8
nb_NO.utf8
sv_SE.utf8
Install dependencies available from binary packages:
sudo apt install jq libclass-method-modifiers-perl libconfig-inifiles-perl libdbd-sqlite3-perl libdaemon-control-perl libdbi-perl libfile-sharedir-perl libfile-slurp-perl libhtml-parser-perl libmojolicious-perl libio-stringy-perl libjson-pp-perl libjson-rpc-perl libjson-validator-perl liblog-any-adapter-dispatch-perl liblog-any-perl liblog-dispatch-perl libmoose-perl libparallel-forkmanager-perl libplack-perl libplack-middleware-debug-perl libplack-middleware-reverseproxy-perl librole-tiny-perl librouter-simple-perl libstring-shellquote-perl libtest-nowarnings-perl libtest-differences-perl libtest-exception-perl libtry-tiny-perl libintl-perl perl-doc starmanNote: libio-stringy-perl is listed here even though it's not a direct dependency. It's an undeclared dependency of libconfig-inifiles-perl.
Install Zonemaster::Backend:
sudo cpanm Zonemaster::BackendThe command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.
Add Zonemaster user (unless it already exists):
sudo useradd -r -c "Zonemaster daemon user" zonemasterInstall files to their proper locations:
cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -d /etc/zonemaster
sudo install -v -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -v -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -v -m 755 ./zm-rpcapi.lsb /etc/init.d/zm-rpcapi
sudo install -v -m 755 ./zm-testagent.lsb /etc/init.d/zm-testagent
sudo install -v -m 755 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.confIf this is an update of Zonemaster-Backend, you should remove any
/etc/init.d/zm-backend.sh(script from previous version of Zonemaster-Backend).
Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
The installation instructions below assumes that this is a new installation.
Note: Zonemaster with SQLite is not meant for an installation with heavy load.
Create database directory:
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemasterSome parameters can be changed, see the backend configuration documentation for details.
See sections for MariaDB and PostgreSQL.
Create the database tables:
sudo -u zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.plMake sure our tmpfiles configuration takes effect:
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.confEnable services at boot time and start them:
sudo systemctl enable zm-rpcapi
sudo systemctl enable zm-testagent
sudo systemctl start zm-rpcapi
sudo systemctl start zm-testagentSee the post-installation section for post-installation matters.
For all commands below, acquire privileges, i.e. become root:
su -lNote: Zonemaster::LDNS and Zonemaster::Engine are not listed here as they are dealt with in the prerequisites section.
Install dependencies available from binary packages:
pkg install jq p5-Class-Method-Modifiers p5-Config-IniFiles p5-Daemon-Control p5-DBI p5-File-ShareDir p5-File-Slurp p5-HTML-Parser p5-JSON-PP p5-JSON-RPC p5-Mojolicious p5-Moose p5-Parallel-ForkManager p5-Plack p5-Plack-Middleware-ReverseProxy p5-Role-Tiny p5-Router-Simple p5-Starman p5-String-ShellQuote p5-DBD-SQLite p5-Log-Dispatch p5-Log-Any p5-Log-Any-Adapter-Dispatch p5-JSON-Validator p5-YAML-LibYAML p5-Test-NoWarnings p5-Test-Differences p5-Test-Exception p5-Locale-libintl gmakeInstall Zonemaster::Backend:
cpanm Zonemaster::BackendThe command above might try to install "DBD::Pg" and "DBD::mysql". You can ignore if it fails. The relevant libraries are installed further down in these instructions.
Unless they already exist, add zonemaster user and zonemaster group
(the group is created automatically):
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
pw useradd zonemaster -C freebsd-pwd.conf -s /sbin/nologin -d /nonexistent -c "Zonemaster daemon user"Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
install -v -m 755 -d /usr/local/etc/zonemaster
install -v -m 640 -g zonemaster ./backend_config.ini /usr/local/etc/zonemaster/
install -v -m 775 -g zonemaster -d /var/log/zonemaster
install -v -m 775 -g zonemaster -d /var/run/zonemaster
install -v -m 755 ./zm_rpcapi-bsd /usr/local/etc/rc.d/zm_rpcapi
install -v -m 755 ./zm_testagent-bsd /usr/local/etc/rc.d/zm_testagentCheck the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
The installation instructions below assumes that this is a new installation.
Note: Zonemaster with SQLite is not meant for an installation with heavy load.
Configure Zonemaster::Backend to use the correct database path:
sed -i '' '/[[:<:]]database_file[[:>:]]/ s:=.*:= /var/db/zonemaster/db.sqlite:' /usr/local/etc/zonemaster/backend_config.iniCreate database directory:
install -v -m 755 -o zonemaster -g zonemaster -d /var/db/zonemasterSome parameters can be changed, see the backend configuration documentation for details.
See sections for MariaDB and PostgreSQL.
Create the database tables:
su -m zonemaster -c "`perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir(qw(Zonemaster-Backend))'`/create_db.pl"Enable services at startup and start service:
sysrc zm_rpcapi_enable="YES"
sysrc zm_testagent_enable="YES"
service zm_rpcapi start
service zm_testagent startTo check that the running daemons run:
service zm_rpcapi status
service zm_testagent statusSee the post-installation section for post-installation matters.
Follow the instructions for Rocky Linux and
use yum instead of dnf.
Note that there is no official support for PostgreSQL on Zonemaster on CentOS Linux 7.
If you have followed the installation instructions for Zonemaster::Backend above, you should be able to use the API on localhost port 5000 as below.
zmtest zonemaster.netThe command is expected to immediately print out a testid, followed by a percentage ticking up from 0% to 100%. Once the number reaches 100% a JSON object is printed and zmtest terminates.
- For a web interface, follow the Zonemaster::GUI installation instructions.
- For a command line interface, follow the Zonemaster::CLI installation instruction.
- For a JSON-RPC API, see the Zonemaster::Backend JSON-RPC API documentation.
First follow the installation instructions for the OS in question, and then go to this section to install MariaDB.
Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.iniNote: See the backend configuration documentation for details.
Install, configure and start database engine:
sudo dnf -y install mariadb-server
sudo systemctl enable mariadb
sudo systemctl start mariadbTo create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password. To be safe, run the commands one by one.
sudo mysql -e "CREATE DATABASE zonemaster;"sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"sudo mysql -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"Update the /etc/zonemaster/backend_config.ini file with database name,
username and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.iniNote: See the backend configuration documentation for details.
Install the database engine and its dependencies:
sudo apt install mariadb-server libdbd-mysql-perlTo create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password. To be safe, run the commands one by one.
sudo mysql -e "CREATE DATABASE zonemaster;"sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"sudo mysql -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"Update the /etc/zonemaster/backend_config.ini file with database name, username
and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
MariaDB is not compatible with Zonemaster on FreeBSD. MySQL is used instead.
Configure Zonemaster::Backend to use the correct database engine:
sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= MySQL/' /usr/local/etc/zonemaster/backend_config.iniNote: See the backend configuration documentation for details.
Install, configure and start database engine (and Perl bindings):
pkg install mysql57-server p5-DBD-mysqlsysrc mysql_enable="YES"
service mysql-server startRead the current root password for MySQL (unless it has been changed already).
cat /root/.mysql_secretSet password for MySQL root (required by MySQL). Use the password from
/root/.mysql_secret when prompted for password, and then the new password
when prompted for that.
/usr/local/bin/mysqladmin -u root -p password '<selected root password>'To create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. Run the command on one line. Use the MySQL root password when prompted.
mysql -u root -p -e "CREATE DATABASE zonemaster;" -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';" -e "GRANT ALL ON zonemaster.* TO 'zonemaster'@'localhost';"Update the /usr/local/etc/zonemaster/backend_config.ini file with database
name, username and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
First follow the installation instructions for the OS in question, and then go to this section to install PostgreSQL.
Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.iniNote: See the backend configuration documentation for details.
Install, configure and start database engine:
sudo dnf -y install postgresql-server perl-DBD-Pg
sudo postgresql-setup --initdb --unit postgresql
sudo sed -i '/^[^#]/ s/ident$/md5/' /var/lib/pgsql/data/pg_hba.conf
sudo systemctl enable postgresql
sudo systemctl start postgresqlTo create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. To be safe run the commands one by one.
sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"sudo -u postgres psql -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"Note: You may get error messages from these commands about lack of permission to change directory. You can safely ignore those messages.
Update the /etc/zonemaster/backend_config.ini file with database name, username
and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.iniInstall the database engine and Perl bindings:
sudo apt install postgresql libdbd-pg-perlNote: See the backend configuration documentation for details.
To create the database and the database user (unless you keep an old database). Edit the command first if you want a non-default database name, user name or password. To be safe run the commands one by one.
sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
sudo -u postgres psql -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"
Update the /etc/zonemaster/backend_config.ini file with database name, username
and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
Configure Zonemaster::Backend to use the correct database engine:
sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= PostgreSQL/' /usr/local/etc/zonemaster/backend_config.iniNote: See the backend configuration documentation for details.
Install, configure and start database engine and Perl bindings:
pkg install p5-DBD-PgThe Perl bindings library (p5-DBD-Pg) has a dependency to a specific version
of postgresql-client. Determine what version was installed:
pkg info | grep postgresql | grep clientIf the installed client is not version 13 then adjust the following command to
install postgresql-server with the same version as postgresql-client
installed.
pkg install postgresql13-serverEnable daemon, initiate and start:
sysrc postgresql_enable="YES"
service postgresql initdb
service postgresql startTo create the database and the database user (unless you keep an old database). Edit the commands first if you want a non-default database name, user name or password.
psql -U postgres -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
psql -U postgres -c "CREATE DATABASE zonemaster WITH OWNER 'zonemaster' ENCODING 'UTF8';"Update the /usr/local/etc/zonemaster/backend_config.ini file with database
name, username and password if non-default values are used.
Now go back to "Database configuration" to create the database tables and then continue with the steps after that.
If, at some point, you want to delete all traces of Zonemaster in the database,
you can run the file cleanup-mysql.sql or file cleanup-postgres.sql
as a database administrator. Commands
for locating and running the file are below. It removes the user and drops the
database (obviously taking all data with it).
Each script uses default values, you may need to adapt them to your setup.
Rocky Linux, Debian and Ubuntu:
sudo mysql --user=root < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sqlFreeBSD (you will get prompted for MySQL password):
mysql --user=root -p < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sqlRocky Linux, Debian and Ubuntu:
sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/cleanup-postgres.sqlFreeBSD (as root):
psql -U postgres -f `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-postgres.sqlRemove the database file and recreate it following the installation instructions above.
Statsd metrics are available, to enable the feature install the additional
Net::Statsd module. See the configuration to
configure the receiver.
The list of metrics is available in the Telemetry document.
sudo cpanm Net::Statsdsudo apt install libnet-statsd-perlcpanm Net::Statsd