Table of contents
- 1. Overview
- 2. Prerequisites
- 3. Installation on CentOS
- 4. Installation on Debian
- 5. Installation on FreeBSD
- 6. Installation on Ubuntu
- 7. Post-installation
This document contains all steps needed to install Zonemaster::Backend. For an overview of the Zonemaster product, please see the main Zonemaster Repository.
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 yum -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-Net-Server perl-Parallel-ForkManager perl-Plack perl-Plack-Test perl-Role-Tiny perl-Router-Simple perl-String-ShellQuote perl-Test-NoWarnings perl-Test-Warn perl-Try-Tiny 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 StarmanInstall 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.confIf this is an update of Zonemaster-Backend, you should remove any
/etc/init.d/zm-backend.shand/etc/init.d/zm-centos.sh(scripts 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. If you upgrade and want to keep the database, go to section 7.4 first. If you instead want to start from afresh, then go to section 7.3 and remove the old database first.
If you keep the database, skip the initialization of the Zonemaster database, but if you have removed the old Zonemaster database, then do the initialization.
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 yum -y install mariadb-server
sudo systemctl enable mariadb
sudo systemctl start mariadbInitialize the database (unless you keep an old database):
sudo mysql < $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/initial-mysql.sqlNote: This creates a database called
zonemaster, as well as a user called "zonemaster" with the password "zonemaster" (as stated in the config file). This user has just enough permissions to run the backend software.
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:
-
On CentOS 7:
sudo rpm -iUvh https://yum.postgresql.org/9.3/redhat/rhel-7-x86_64/pgdg-centos93-9.3-3.noarch.rpm sudo yum -y install postgresql93-server perl-DBD-Pg sudo /usr/pgsql-9.3/bin/postgresql93-setup initdb sudo sed -i '/^[^#]/ s/ident$/md5/' /var/lib/pgsql/9.3/data/pg_hba.conf sudo systemctl enable postgresql-9.3 sudo systemctl start postgresql-9.3
-
On CentOS 8:
sudo yum -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 postgresql
Initialize Zonemaster database (unless you keep an old database):
sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/initial-postgres.sqlNote: This creates a database called
zonemaster, as well as a user called "zonemaster" with the password "zonemaster" (as stated in the config file). This user has just enough permissions to run the backend software.
Note: Zonemaster with SQLite is not meant for an installation with heavy load.
Configure Zonemaster::Backend to use the correct database engine and database path:
sudo sed -i '/\bengine\b/ s/=.*/= SQLite/' /etc/zonemaster/backend_config.iniCreate database directory, set correct ownership and create database:
cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster
sudo perl create_db_sqlite.pl
sudo chown zonemaster:zonemaster /var/lib/zonemaster/db.sqliteNote: See the backend configuration documentation for details.
Make 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.*|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
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 libdbi-perl libfile-sharedir-perl libfile-slurp-perl libhtml-parser-perl libio-stringy-perl libjson-pp-perl libjson-rpc-perl liblog-any-adapter-dispatch-perl liblog-any-perl liblog-dispatch-perl libmoose-perl libparallel-forkmanager-perl libplack-perl libplack-middleware-debug-perl librole-tiny-perl librouter-simple-perl libstring-shellquote-perl libtest-nowarnings-perl libtry-tiny-perl 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 dependencies not available from binary packages:
sudo cpanm Daemon::Control JSON::ValidatorInstall 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. If you upgrade and want to keep the database, go to section 7.4 first. If you instead want to start from afresh, then go to section 7.3 and remove the old database first.
If you keep the database, skip the initialization of the Zonemaster database, but if you have removed the old Zonemaster database, then do the initialization.
Install the database engine and its dependencies:
sudo apt install mariadb-server libdbd-mysql-perlConfigure 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.
Initialize Zonemaster database (unless you keep an old database):
sudo mysql < $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/initial-mysql.sqlNote: This creates a database called
zonemaster, as well as a user called "zonemaster" with the password "zonemaster" (as stated in the config file). This user has just enough permissions to run the backend software.
Install database engine and Perl bindings:
sudo apt install postgresql libdbd-pg-perlConfigure 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.
Initialize Zonemaster database (unless you keep an old database):
sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/initial-postgres.sqlNote: This creates a database called
zonemaster, as well as a user called "zonemaster" with the password "zonemaster" (as stated in the config file). This user has just enough permissions to run the backend software.
Note: Zonemaster with SQLite is not meant for an installation with heavy load.
All binaries and Perl bindings are already installed.
Configure Zonemaster::Backend to use the correct database engine and database path:
sudo sed -i '/\bengine\b/ s/=.*/= SQLite/' /etc/zonemaster/backend_config.iniCreate database directory, set correct ownership and create database:
cd `perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")'`
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster
sudo perl create_db_sqlite.pl
sudo chown zonemaster:zonemaster /var/lib/zonemaster/db.sqliteSQLite will not run as a daemon and does not need to be started.
Note: See the backend configuration documentation for details.
Make 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-Moose p5-Parallel-ForkManager p5-Plack 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-NoWarningsInstall 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. If you upgrade and want to keep the database, go to section 7.4 first. If you instead want to start from afresh, then go to section 7.3 and remove the old database first.
If you keep the database, skip the initialization of the Zonemaster database, but if you have removed the old Zonemaster database, then do the initialization.
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-mysql
sysrc mysql_enable="YES"
service mysql-server startRead the current root password for MySQL:
cat /root/.mysql_secretConnect to MySQL interactively:
mysql -u root -h localhost -pReset root password in MySQL (required by MySQL). Replace
<selected root password> with the password from the file above
(or another one of your choice):
ALTER USER 'root'@'localhost' IDENTIFIED BY '<selected root password>';Logout from database:
exit;Unless you keep an old database, initialize the database (and give the root password when prompted):
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
mysql -u root -p < ./initial-mysql.sqlNote: This creates a database called
zonemaster, as well as a user called "zonemaster" with the password "zonemaster" (as stated in the config file). This user has just enough permissions to run the backend software.
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 postgresql12-server p5-DBD-Pg
sysrc postgresql_enable="YES"
service postgresql initdb
service postgresql startInitialize Zonemaster database (unless you keep an old database):
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
psql -U postgres -f ./initial-postgres.sqlNote: Zonemaster with SQLite is not meant for an installation with heavy load.
All binaries and Perl bindings are already installed.
Configure Zonemaster::Backend to use the correct database engine and database path:
sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= SQLite/' /usr/local/etc/zonemaster/backend_config.ini
sed -i '' '/[[:<:]]database_file[[:>:]]/ s:=.*:= /var/db/zonemaster/db.sqlite:' /usr/local/etc/zonemaster/backend_config.iniCreate database directory, set correct ownership and create database:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
install -v -m 755 -o zonemaster -g zonemaster -d /var/db/zonemaster
env ZONEMASTER_BACKEND_CONFIG_FILE=/usr/local/etc/zonemaster/backend_config.ini su -m zonemaster -c "perl create_db_sqlite.pl"SQLite will not run as a daemon and does not need to be started.
Note: See the backend configuration documentation for details.
Enable services at startup:
sysrc zm_rpcapi_enable="YES"
sysrc zm_testagent_enable="YES"Start services:
service zm_rpcapi start
service zm_testagent startTo check the running daemons run:
service mysql-server status # If mysql-server is installed
service postgresql status # If postgresql is installed
service zm_rpcapi status
service zm_testagent statusSee the post-installation section for post-installation matters.
Use the procedure for installation on Debian.
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.
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).
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
mysql --user=root --password < ./cleanup-mysql.sqlcd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo -u postgres psql -f ./cleanup-postgres.sql # MUST BE VERIFIED!Remove the database file and recreate it following the installation instructions above.
If you upgrade your Zonemaster installation with a newer version of Zonemaster-Backend and keep the database, then you might have to upgrade the database to use it with the new version of Zonemaster-Backend. Please see the upgrade information.
For SQLite database upgrading is not needed as of now.