/ 
Zonemaster-Backend-2.1.0
⭐ Starred 14
/ docs/Installation.md

Installation

Table of contents

1. Overview

This document contains all steps needed to install Zonemaster::Backend. For an overview of the Zonemaster product, please see the main Zonemaster Repository.

2. Prerequisites

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 smoke test instruction assumes that you have curl installed.

3. Installation on CentOS

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 cpanm Class::Method::Modifiers Config::IniFiles Daemon::Control JSON::RPC::Dispatch Parallel::ForkManager Plack::Builder Plack::Middleware::Debug Role::Tiny Router::Simple::Declare Starman

Install Zonemaster::Backend:

sudo cpanm Zonemaster::Backend

The 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" zonemaster

Install files to their proper locations:

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -m 755 -d /etc/zonemaster
sudo install -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -m 775 -g zonemaster -d /var/run/zonemaster
sudo install -m 755 ./zm-backend.sh /etc/init.d/

3.2 Database engine installation and configuration (CentOS)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

3.2.1 Instructions for MySQL (CentOS)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/=MySQL/' /etc/zonemaster/backend_config.ini

Install, 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 status

Initialize the database:

mysql --user=root --password < ./initial-mysql.sql

Note: 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.

3.2.2 Instructions for PostgreSQL (CentOS)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/=PostgreSQL/' /etc/zonemaster/backend_config.ini

Add 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.rpm

Install the PostgreSQL packages:

sudo yum -y install postgresql93 postgresql93-server postgresql93-contrib postgresql93-libs postgresql93-devel perl-DBD-Pg

To enable PostgreSQL from boot:

sudo systemctl enable postgresql-9.3

Initialise PostgreSQL:

sudo /usr/pgsql-9.3/bin/postgresql93-setup initdb

Configure:

# In the below file modify all instances of "ident" to "md5"
sudoedit /var/lib/pgsql/9.3/data/pg_hba.conf

Start PostgreSQL:

sudo systemctl start postgresql-9.3

Verify PostgreSQL has started:

sudo systemctl status postgresql-9.3

Initialize Zonemaster database:

sudo -u postgres psql -f ./initial-postgres.sql

Note: 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.

3.2.3 Instructions for SQLite (CentOS)

At this time there is no instruction for using SQLite on CentOS.

3.3 Service configuration and startup (CentOS)

Start the service:

sudo /etc/init.d/zm-backend.sh start

Check that the service has started:

sudo /etc/init.d/zm-backend.sh status

Does not return any status as of now

3.4 Post-installation (CentOS)

See the post-installation section for post-installation matters.

4. Installation on Debian

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 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 librole-tiny-perl librouter-simple-perl libstring-shellquote-perl libtest-requires-perl libtest-warn-perl libtext-microtemplate-perl libtie-simple-perl starman

Install dependencies not available from binary packages:

sudo cpanm Daemon::Control JSON::RPC Net::IP::XS Parallel::ForkManager Plack::Middleware::Debug

Install Zonemaster::Backend:

sudo cpanm Zonemaster::Backend

The 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" zonemaster

Install files to their proper locations:

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
sudo install -m 755 -d /etc/zonemaster
sudo install -m 640 -g zonemaster ./backend_config.ini /etc/zonemaster/
sudo install -m 775 -g zonemaster -d /var/log/zonemaster
sudo install -m 775 -g zonemaster -d /var/run/zonemaster
sudo install -m 755 ./zm-backend.sh /etc/init.d/

4.2 Database engine installation and configuration (Debian)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

4.2.1 Instructions for MySQL (Debian)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/=MySQL/' /etc/zonemaster/backend_config.ini

Install the database engine and its dependencies:

sudo apt-get install mysql-server libdbd-mysql-perl

Initialize the database:

mysql --user=root --password < ./initial-mysql.sql

For latest versions of MySQL, wherein the root password is blank and you get an error "Access denied for the above command" on running the above command , follow the below procedure:

If you know the root password
        mysql -u root 
In MySQL prompt type the following 
        SET PASSWORD FOR 'root'@'localhost' =PASSWORD("root-password");
        flush privileges;
        quit;
Run again 
	mysql --user=root --password < ./initial-mysql.sql

Note: 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.

4.2.2 Instructions for PostgreSQL (Debian)

Configure Zonemaster::Backend to use the correct database engine:

sudo sed -i '/\bengine\b/ s/=.*/=PostgreSQL/' /etc/zonemaster/backend_config.ini

Install, configure and start database engine (and Perl bindings):

sudo apt-get install libdbd-pg-perl postgresql

Check 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 --version

Initialize the database:

sudo -u postgres psql -f ./initial-postgres.sql

Note: 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.

4.2.3 Instructions for SQLite (Debian)

At this time there is no instruction for configuring/creating a database in SQLite

4.3 Service configuration and startup (Debian)

Add zm-backend.sh to start up script:

sudo update-rc.d zm-backend.sh defaults

Start the service:

sudo service zm-backend.sh start

If the start command did not give any output (depends on OS and version) then check that the service has started with the following command (if you get output with the start command, you probably do not get it with the status command).

sudo service zm-backend.sh status

4.4 Post-installation (Debian)

See the post-installation section for post-installation matters.

5. Installation on FreeBSD

For all commands below, acquire privileges, i.e. become root:

su -l

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:

pkg install p5-Class-Method-Modifiers 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-Role-Tiny p5-Router-Simple p5-Starman p5-String-ShellQuote

Optionally install Curl (only needed for the post-installation smoke test)

pkg install curl

Install dependencies not available from binary packages:

cpanm Net::IP::XS

Install Zonemaster::Backend:

cpanm Zonemaster::Backend

The 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 and group:

pw groupadd zonemaster
pw useradd zonemaster -g zonemaster -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 -m 755 -d /usr/local/etc/zonemaster
install -m 640 -g zonemaster ./backend_config.ini /usr/local/etc/zonemaster/
install -m 775 -g zonemaster -d /var/log/zonemaster
install -m 775 -g zonemaster -d /var/run/zonemaster
install -m 755 ./zm_rpcapi-bsd /usr/local/etc/rc.d/zm_rpcapi
install -m 755 ./zm_testagent-bsd /usr/local/etc/rc.d/zm_testagent

5.2 Database engine installation and configuration (FreeBSD)

Check the declaration of prerequisites to make sure your preferred combination of operating system version and database engine version is supported.

5.2.1 Instructions for MySQL (FreeBSD)

Configure Zonemaster::Backend to use the correct database engine:

sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/=MySQL/' /usr/local/etc/zonemaster/backend_config.ini

Install, configure and start database engine (and Perl bindings):

pkg install mysql56-server p5-DBD-mysql
sysrc mysql_enable="YES"
service mysql-server start

Initialize the database:

mysql < ./initial-mysql.sql

Note: 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.

5.2.2 Instructions for PostgreSQL (FreeBSD)

Configure Zonemaster::Backend to use the correct database engine:

sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/=PostgreSQL/' /usr/local/etc/zonemaster/backend_config.ini

Install, configure and start database engine (and Perl bindings):

pkg install postgresql95-server p5-DBD-Pg
sysrc postgresql_enable="YES"
service postgresql initdb
service postgresql start

Initialize the database:

psql -U pgsql -f ./initial-postgres.sql template1

5.2.3 Instructions for SQLite (FreeBSD)

At this time there is no instruction for configuring and creating a database in SQLite.

5.3 Service startup (FreeBSD)

Enable services at startup:

sysrc zm_rpcapi_enable="YES"
sysrc zm_testagent_enable="YES"

Start services:

service zm_rpcapi start
service zm_testagent start

5.4 Post-installation (FreeBSD)

See the post-installation section for post-installation matters.

6. Installation on Ubuntu

Use the procedure for installation on Debian.

7. Post-installation

7.1 Smoke test

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. The command requires that curl is installed.

curl -s -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"version_info","id":"1"}' http://localhost:5000/ && echo

The command is expected to give an immediate JSON response similiar to:

{"id":"1","jsonrpc":"2.0","result":{"zonemaster_backend":"2.0.2","zonemaster_engine":"v2.0.6"}}

7.2. What to do next?

7.3. Cleaning up the database

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).

7.3.1 MySQL

cd `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`
mysql --user=root --password < ./cleanup-mysql.sql

7.3.2 PostgreSQL

cd `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/.