This document describes prerequisites, installation, configuration, startup and post-install sanity checking for Zonemaster::Backend. The final section wraps up with a few pointer to interfaces for 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.
For details on supported versions of Perl, database engine and operating system for Zonemaster::Backend, see the declaration of prerequisites.
Note: In addition to the normal dependencies, the post-installation sanity check instruction assumes that you have curl installed.
This instruction covers the following operating systems:
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 install perl-Module-Install perl-IO-CaptureOutput perl-String-ShellQuote Install dependencies not available from binary packages:
sudo cpan -i Config::IniFiles Daemon::Control JSON::RPC::Dispatch Parallel::ForkManager Plack::Builder Plack::Middleware::Debug Router::Simple::Declare Starman Install Zonemaster::Backend:
sudo cpan -i 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:
sudo useradd -r -c "Zonemaster daemon user" zonemasterCheck the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -d /etc/zonemaster
sudo install --mode=755 ./backend_config.ini /etc/zonemaster/
sudo install --mode=755 ./zm-centos.sh /etc/init.d/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/=MySQL/' /etc/zonemaster/backend_config.iniInstall, configure and start database engine (and Perl bindings):
sudo rpm -ivh http://repo.mysql.com/mysql-community-release-el7-5.noarch.rpm
sudo yum install mysql-server perl-DBD-mysql
sudo systemctl start mysqld Verify that MySQL has started:
service mysqld statusInitialize the database:
mysql --user=root --password < ./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.Only run this command during an initial installation of the Zonemaster backend. If you do this on an existing system, you will wipe out the data in your database.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -d /etc/zonemaster
sudo install --mode=755 ./backend_config.ini /etc/zonemaster/
sudo install --mode=755 ./zm-centos.sh /etc/init.d/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/=PostgreSQL/' /etc/zonemaster/backend_config.iniAdd PostgreSQL package repository needed to get the appropriate PostgreSQL binary package
sudo rpm -iUvh https://yum.postgresql.org/9.3/redhat/rhel-7-x86_64/pgdg-centos93-9.3-3.noarch.rpmInstall the PostgreSQL packages:
sudo yum -y install postgresql93 postgresql93-server postgresql93-contrib postgresql93-libs postgresql93-devel perl-DBD-PgTo enable PostgreSQL from boot:
sudo systemctl enable postgresql-9.3Initialise PostgreSQL:
sudo /usr/pgsql-9.3/bin/postgresql93-setup initdbConfigure:
# In the below file modify all instances of "ident" to "md5"
sudoedit /var/lib/pgsql/9.3/data/pg_hba.confStart PostgreSQL:
sudo systemctl start postgresql-9.3 Verify PostgreSQL has started:
sudo systemctl status postgresql-9.3Initialize Zonemaster database:
sudo -u postgres psql -f ./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.
At this time there is no instruction for using SQLite on CentOS.
Start the service:
sudo /etc/init.d/zm-centos.sh startCheck that the service has started:
sudo /etc/init.d/zm-centos.sh statusIf you followed this instructions to the letter, you should be able to use the API on localhost port 5000, like this:
curl -s -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"version_info","id":"1"}' http://localhost:5000/ && echoThe command is expected to give an immediate JSON response similiar to :
{ "jsonrpc": "2.0", "id": 1, "result": { "zonemaster_backend": "1.0.7", "zonemaster_engine": "v1.0.14" } }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 apt-get install libclass-method-modifiers-perl libconfig-inifiles-perl libdaemon-control-perl libdata-dump-perl libdbd-sqlite3-perl libdbi-perl libfile-sharedir-perl libfile-slurp-perl libhtml-parser-perl libintl-perl libio-captureoutput-perl libjson-pp-perl libmoose-perl libplack-perl librouter-simple-perl libstring-shellquote-perl libtest-requires-perl libtest-warn-perl libtext-microtemplate-perl libtie-simple-perl starmanInstall dependencies not available from binary packages:
sudo cpan -i JSON::RPC Plack::Middleware::Debug Parallel::ForkManager Net::IP::XSInstall Zonemaster::Backend:
sudo cpan -i 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.
Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -d /etc/zonemaster
sudo install --mode=755 ./backend_config.ini /etc/zonemaster/
sudo install --mode=755 ./zm-backend.sh /etc/init.d/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/=MySQL/' /etc/zonemaster/backend_config.iniInstall the database engine and its dependencies:
sudo apt-get install mysql-server libdbd-mysql-perlInitialize the database:
mysql --user=root --password < ./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.Only run this command during an initial installation of the Zonemaster backend. If you do this on an existing system, you will wipe out the data in your database.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -d /etc/zonemaster
sudo install --mode=755 ./backend_config.ini /etc/zonemaster/
sudo install --mode=755 ./zm-backend.sh /etc/init.d/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sudo sed -i '/\bengine\b/ s/=.*/=PostgreSQL/' /etc/zonemaster/backend_config.iniThe following block of commands is for Debian 7 only. For all others, go to the step of installing database engine. First create or edit Debian 7 sources list file. Then fetch and import the repository signing key. And finally update the package lists.
echo -e "\ndeb http://apt.postgresql.org/pub/repos/apt/ wheezy-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgdg.list
wget -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get updateFor all versions of Debian and Ubuntu, install, configure and start database engine (and Perl bindings):
sudo apt-get install libdbd-pg-perl postgresqlCheck that you have a PostgreSQL installation 9.2 or later. The version should also match the supported database engine version depending on OS found in Zonemaster/README.
psql --versionInitialize the database:
sudo -u postgres psql -f ./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.
At this time there is no instruction for configuring/creating a database in SQLite
Add zm-backend.sh to start up script:
sudo update-rc.d zm-backend.sh defaultsStart the service:
sudo service zm-backend.sh startCheck that the service has started:
sudo service zm-backend.sh statusIf you followed this instructions to the letter, you should be able to use the API on localhost port 5000, like this:
curl -s -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"version_info","id":"1"}' http://localhost:5000/ && echoThe command is expected to give an immediate JSON response similiar to:
{ "jsonrpc": "2.0", "id": 1, "result": { "zonemaster_backend": "1.0.7", "zonemaster_engine": "v1.0.14" } }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 p5-Config-IniFiles p5-Daemon-Control p5-DBI p5-File-ShareDir p5-File-Slurp p5-HTML-Parser p5-IO-CaptureOutput p5-JSON-PP p5-JSON-RPC p5-Locale-libintl p5-Moose p5-Parallel-ForkManager p5-Plack p5-Plack-Middleware-Debug p5-Router-Simple p5-Starman p5-String-ShellQuoteInstall dependencies not available from binary packages:
cpan -i Net::IP::XSInstall Zonemaster::Backend:
cpan -i 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.
Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
install -d /etc/zonemaster
install -m 644 ./backend_config.ini /etc/zonemaster/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sed -i '/\bengine\b/ s/=.*/=MySQL/' /usr/local/etc/zonemaster/backend_config.iniInstall, configure and start database engine (and Perl bindings):
pkg install mysql56-server p5-DBD-mysql
echo 'mysql_enable="YES"' | tee -a /etc/rc.conf
service mysql-server startInitialize the database:
mysql < ./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.Only run this command during an initial installation of the Zonemaster backend. If you do this on an existing system, you will wipe out the data in your database.
Install files to their proper locations:
cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
install -d /etc/zonemaster
install -m 644 ./backend_config.ini /etc/zonemaster/
mkdir "$HOME/logs"Configure Zonemaster::Backend to use the correct database engine:
sed -i '/\bengine\b/ s/=.*/=PostgreSQL/' /usr/local/etc/zonemaster/backend_config.iniInstall, configure and start database engine (and Perl bindings):
pkg install postgresql95-server p5-DBD-Pg
echo 'postgresql_enable="YES"' | tee -a /etc/rc.conf
service postgresql initdb
service postgresql startToDo: Add instruction about the
config_logfilter_1=/full/path/to/a/config_file.jsonline.
Initialize the database:
psql -U pgsql -f ./initial-postgres.sql template1At this time there is no instruction for configuring and creating a database in SQLite.
At this time there is no instruction for automatically running Zonemaster Web backends nor Workers as services on FreeBSD.
starman --error-log="$HOME/logs/error.log" --pid-file="$HOME/logs/starman.pid" --listen=127.0.0.1:5000 --daemonize /usr/local/bin/zonemaster_backend_rpcapi.psgi
zonemaster_backend_testagent startIf you followed this instructions to the letter, you should be able to use the API on localhost port 5000, like this:
curl -s -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"version_info","id":"1"}' http://localhost:5000/ && echoThe command is expected to give an immediate JSON response similiar to :
{ "jsonrpc": "2.0", "id": 1, "result": { "zonemaster_backend": "1.0.7", "zonemaster_engine": "v1.0.14" } }Use the procedure for installation on Debian.
- 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!Copyright (c) 2013 - 2017, IIS (The Internet Foundation in Sweden)
Copyright (c) 2013 - 2017, AFNIC
Creative Commons Attribution 4.0 International License
You should have received a copy of the license along with this work. If not, see https://creativecommons.org/licenses/by/4.0/.