feat: add full Zonemaster stack with Docker and Spanish UI
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
32
zonemaster/docs/public/installation/README.md
Normal file
32
zonemaster/docs/public/installation/README.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Installation instructions
|
||||
|
||||
## Manual installation
|
||||
|
||||
Before installing Zonemaster, check the [prerequisites] first.
|
||||
|
||||
Start by installing the following components, in order:
|
||||
|
||||
* [Zonemaster-LDNS];
|
||||
* [Zonemaster-Engine];
|
||||
* [Zonemaster-CLI].
|
||||
|
||||
At this point, tests can be run from the command-line on the local machine.
|
||||
To install the Web GUI, install the following additional components, in order:
|
||||
|
||||
* [Zonemaster-Backend];
|
||||
* [Zonemaster-GUI].
|
||||
|
||||
## Docker
|
||||
|
||||
Most Zonemaster components are available as [Docker] containers. See the dedicated
|
||||
[Docker document] for more information.
|
||||
|
||||
[Docker]: https://www.docker.com/get-started/
|
||||
[Docker document]: docker.md
|
||||
[prerequisites]: prerequisites.md
|
||||
[prerequisites]: prerequisites.md
|
||||
[Zonemaster-Backend]: zonemaster-backend.md
|
||||
[Zonemaster-CLI]: zonemaster-cli.md
|
||||
[Zonemaster-Engine]: zonemaster-engine.md
|
||||
[Zonemaster-GUI]: zonemaster-gui.md
|
||||
[Zonemaster-LDNS]: zonemaster-ldns.md
|
||||
17
zonemaster/docs/public/installation/docker.md
Normal file
17
zonemaster/docs/public/installation/docker.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Docker
|
||||
|
||||
The following components are available on [Docker Hub], and can conveniently be
|
||||
downloaded and run without any installation. Through [Docker], Zonemaster can
|
||||
be run on Linux, MacOS and Windows.
|
||||
|
||||
- Zonemaster-CLI: see [Using Zonemaster-CLI Docker] for how to run Zonemaster-CLI on [Docker].
|
||||
- Zonemaster-Backend: see [Using Zonemaster-Backend Docker] for how to run Zonemaster-Backend
|
||||
and Zonemaster-CLI on [Docker].
|
||||
|
||||
To build your own Docker image, see the [Docker Image Creation] documentation.
|
||||
|
||||
[Docker]: https://www.docker.com/get-started/
|
||||
[Docker Hub]: https://hub.docker.com/u/zonemaster
|
||||
[Docker Image Creation]: https://github.com/zonemaster/zonemaster/blob/master/docs/internal/maintenance/ReleaseProcess-create-docker-image.md
|
||||
[Using Zonemaster-Backend Docker]: ../using/backend/Using-Zonemaster-Backend-Docker.md
|
||||
[Using Zonemaster-CLI Docker]: ../using/cli.md
|
||||
93
zonemaster/docs/public/installation/prerequisites.md
Normal file
93
zonemaster/docs/public/installation/prerequisites.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Prerequisites
|
||||
|
||||
Zonemaster comes with documentation for and has been tested on the operating systems
|
||||
and processor architecture listed below.
|
||||
|
||||
## Supported processor architectures
|
||||
|
||||
* x86_64 / amd64
|
||||
|
||||
## Supported operating system versions
|
||||
|
||||
| Operating System | Version |
|
||||
|:-----------------|:-------:|
|
||||
| [Debian] | 13 |
|
||||
| [Docker] | n/a |
|
||||
| [FreeBSD] | 14 |
|
||||
| [Rocky Linux] | 8 |
|
||||
| [Rocky Linux] | 9 |
|
||||
| [Rocky Linux] | 10 |
|
||||
| [Ubuntu] | 22.04 |
|
||||
| [Ubuntu] | 24.04 |
|
||||
|
||||
Only the latest long-term supported version of Debian and FreeBSD, respectively,
|
||||
is supported. All long-term supported versions of Rocky Linux and Ubuntu are
|
||||
supported, unless such a version has end of support before the expected next
|
||||
release of Zonemaster.
|
||||
|
||||
Only the Docker images provided by the Zonemaster project on [Docker Hub] are
|
||||
supported. Currently only Zonemaster-CLI is supported on Docker. Docker itself
|
||||
can run on any of the [Docker] supported OSs (Linux, macOS and Windows).
|
||||
|
||||
## Supported database engine versions
|
||||
|
||||
| Operating System | MariaDB | PostgreSQL |
|
||||
|------------------|---------|------------|
|
||||
| Debian 13 | 11.8 | 17 |
|
||||
| Docker | n/a | n/a |
|
||||
| FreeBSD 14 | 8.0 (*) | 17 |
|
||||
| Rocky Linux 8 | 10.3 | 10 |
|
||||
| Rocky Linux 9 | 10.5 | 13 |
|
||||
| Rocky Linux 10 | 10.11 | 16 |
|
||||
| Ubuntu 22.04 | 10.6 | 14 |
|
||||
| Ubuntu 24.04 | 10.11 | 16 |
|
||||
|
||||
* (*) FreeBSD uses MySQL, not MariaDB.
|
||||
* SQLite is bundled in Perl DBD::SQLite and loaded as a dependency to
|
||||
Zonemaster-Backend.
|
||||
* Zonemaster Backend has been tested with the combination of OS and database
|
||||
engine version listed in the table above.
|
||||
* Zonemaster depends on functionality introduced in PostgreSQL version 10, and
|
||||
earlier versions of PostgreSQL are as such not supported.
|
||||
* Zonemaster Backend has not been published on [Docker Hub].
|
||||
|
||||
## Supported Perl versions
|
||||
|
||||
| Operating System | Perl |
|
||||
|------------------|-------|
|
||||
| Debian 13 | 5.40 |
|
||||
| Docker | (*) |
|
||||
| FreeBSD 14 | 5.42 |
|
||||
| Rocky Linux 8 | 5.26 |
|
||||
| Rocky Linux 9 | 5.32 |
|
||||
| Rocky Linux 10 | 5.40 |
|
||||
| Ubuntu 22.04 | 5.34 |
|
||||
| Ubuntu 24.04 | 5.38 |
|
||||
|
||||
|
||||
* Zonemaster technically requires Perl version 5.26 or higher, but has only been tested with the versions in the table above.
|
||||
* Zonemaster has been tested with the default version of Perl in the OSs as
|
||||
listed in the table above.
|
||||
* (*) Perl is included in the Docker images published on [Docker Hub].
|
||||
|
||||
## Supported Client Browser versions
|
||||
|
||||
Zonemaster GUI is tested on the browsers in the table below.
|
||||
The latest version of the browser at the time of testing is used.
|
||||
|
||||
Browser |
|
||||
------- |
|
||||
Firefox |
|
||||
Chrome |
|
||||
|
||||
|
||||
Zonemaster GUI is tested manually and with testing tools. See the
|
||||
[Zonemaster-gui repository][Zonemaster-GUI] for more details.
|
||||
|
||||
[Debian]: https://www.debian.org/
|
||||
[Docker Hub]: https://hub.docker.com/u/zonemaster
|
||||
[Docker]: https://www.docker.com/get-started/
|
||||
[FreeBSD]: https://www.freebsd.org/
|
||||
[Rocky Linux]: https://rockylinux.org/
|
||||
[Ubuntu]: https://ubuntu.com/
|
||||
[Zonemaster-GUI]: https://github.com/zonemaster/zonemaster-gui
|
||||
842
zonemaster/docs/public/installation/zonemaster-backend.md
Normal file
842
zonemaster/docs/public/installation/zonemaster-backend.md
Normal file
@@ -0,0 +1,842 @@
|
||||
# Installation: Zonemaster-Backend
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [1. Overview](#1-overview)
|
||||
* [2. Prerequisites][prerequisites section]
|
||||
* [3. Installation on Rocky Linux](#3-installation-on-rocky-linux)
|
||||
* [3.1 Install Zonemaster::Backend and related dependencies (Rocky Linux)](#31-install-zonemasterbackend-and-related-dependencies-rocky-linux)
|
||||
* [3.2 Database engine installation (Rocky Linux)](#32-database-engine-installation-rocky-linux)
|
||||
* [3.3 Database configuration (Rocky Linux)](#33-database-configuration-rocky-linux)
|
||||
* [3.4 Service configuration and startup (Rocky Linux)](#34-service-configuration-and-startup-rocky-linux)
|
||||
* [3.5 Post-installation (Rocky Linux)](#35-post-installation-rocky-linux)
|
||||
* [4. Installation on Debian and Ubuntu](#4-installation-on-debian-and-ubuntu)
|
||||
* [4.1 Install Zonemaster::Backend and related dependencies (Debian/Ubuntu)](#41-install-zonemasterbackend-and-related-dependencies-debianubuntu)
|
||||
* [4.2 Database engine installation (Debian/Ubuntu)](#42-database-engine-installation-debianubuntu)
|
||||
* [4.3 Database configuration (Debian/Ubuntu)](#43-database-configuration-debianubuntu)
|
||||
* [4.4 Service configuration and startup (Debian/Ubuntu)](#44-service-configuration-and-startup-debianubuntu)
|
||||
* [4.5 Post-installation (Debian/Ubuntu)](#45-post-installation-debianubuntu)
|
||||
* [5. Installation on FreeBSD](#5-installation-on-freebsd)
|
||||
* [5.1 Install Zonemaster::Backend and related dependencies (FreeBSD)](#51-install-zonemasterbackend-and-related-dependencies-freebsd)
|
||||
* [5.2 Database engine installation (FreeBSD)](#52-database-engine-installation-freebsd)
|
||||
* [5.3 Database configuration (FreeBSD)](#53-database-configuration-freebsd)
|
||||
* [5.4 Service startup (FreeBSD)](#54-service-startup-freebsd)
|
||||
* [5.5 Post-installation (FreeBSD)](#55-post-installation-freebsd)
|
||||
* [6. Post-installation][Post-installation]
|
||||
* [6.1 Smoke test](#61-smoke-test)
|
||||
* [6.2 Troubleshooting installation](#62-troubleshooting-installation)
|
||||
* [6.3 What to do next?](#63-what-to-do-next)
|
||||
* [7. Installation with MariaDB](#7-installation-with-mariadb)
|
||||
* [7.1 MariaDB (Rocky Linux)][MariaDB instructions Rocky Linux]
|
||||
* [7.2. MariaDB (Debian/Ubuntu)][MariaDB instructions Debian]
|
||||
* [7.3. MySQL (FreeBSD)][MySQL instructions FreeBSD]
|
||||
* [8. Installation with PostgreSQL](#8-installation-with-postgresql)
|
||||
* [8.1. PostgreSQL (Rocky Linux)][PostgreSQL instructions Rocky Linux]
|
||||
* [8.2. PostgreSQL (Debian/Ubuntu)][PostgreSQL instructions Debian]
|
||||
* [8.3. PostgreSQL (FreeBSD)][PostgreSQL instructions FreeBSD]
|
||||
* [9. Cleaning up the database][Removing database]
|
||||
* [9.1. MariaDB and MySQL](#91-mariadb-and-mysql)
|
||||
* [9.2. PostgreSQL](#92-postgresql)
|
||||
* [9.3. SQLite](#93-sqlite)
|
||||
* [10. Optional features](#10-optional-features)
|
||||
* [10.1. Metrics](#101-metrics)
|
||||
* [10.2 Global cache](#102-global-cache)
|
||||
|
||||
|
||||
## 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].
|
||||
|
||||
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][Removing database] and
|
||||
continue with this installation document.
|
||||
|
||||
An alternative to installing Zonemaster-Backend is to run it under [Docker]. See [Using the Backend] for run it under Docker.
|
||||
|
||||
## 2. Prerequisites
|
||||
|
||||
Before installing Zonemaster::Backend, you should [install Zonemaster::Engine
|
||||
][Zonemaster::Engine installation].
|
||||
|
||||
> **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].
|
||||
|
||||
|
||||
## 3. Installation on Rocky Linux
|
||||
|
||||
### 3.1 Install Zonemaster::Backend and related dependencies (Rocky Linux)
|
||||
|
||||
> **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:
|
||||
|
||||
```sh
|
||||
sudo dnf install --assumeyes jq perl-Class-Method-Modifiers perl-Config-IniFiles perl-DBD-SQLite perl-DBI perl-File-ShareDir perl-File-Slurp perl-HTML-Parser perl-JSON-PP perl-libwww-perl perl-Log-Dispatch perl-Mojolicious perl-Moose perl-Net-Server perl-Parallel-ForkManager perl-Plack perl-Plack-Test perl-Role-Tiny perl-Test-Differences perl-Test-Exception perl-Test-Mojo perl-Test-NoWarnings perl-Try-Tiny perl-libintl perl-LWP-Protocol-https
|
||||
```
|
||||
|
||||
Install dependencies not available from binary packages:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Daemon::Control JSON::RPC JSON::Validator Log::Any Log::Any::Adapter::Dispatch Net::IP::XS Plack::Middleware::ReverseProxy Router::Simple Starman
|
||||
```
|
||||
|
||||
For Rocky Linux 8 only, install DBD::SQLite from CPAN as the one in the system packages repository is too old:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest DBD::SQLite
|
||||
```
|
||||
|
||||
Install Zonemaster::Backend:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::Backend
|
||||
```
|
||||
|
||||
Add Zonemaster user (unless it already exists):
|
||||
|
||||
```sh
|
||||
sudo useradd --system --home-dir=/nonexistent --shell=/usr/sbin/nologin --comment="Zonemaster daemon user" zonemaster
|
||||
```
|
||||
|
||||
Install files to their proper locations:
|
||||
|
||||
```sh
|
||||
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 644 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.conf
|
||||
sudo install -v -m 644 -Z ./zm-rpcapi.service /etc/systemd/system/
|
||||
sudo install -v -m 644 -Z ./zm-testagent.service /etc/systemd/system/
|
||||
```
|
||||
|
||||
### 3.2 Database engine installation (Rocky Linux)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### 3.2.1 Instructions for SQLite (Rocky Linux)
|
||||
|
||||
> **Note:** Zonemaster with SQLite is not meant for an installation with heavy
|
||||
> load.
|
||||
|
||||
Create database directory:
|
||||
|
||||
```sh
|
||||
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster
|
||||
```
|
||||
|
||||
> Some parameters can be changed, see the [backend configuration] documentation
|
||||
> for details.
|
||||
|
||||
|
||||
#### 3.2.2 Instructions for other engines (Rocky Linux)
|
||||
|
||||
See sections for [MariaDB][MariaDB instructions Rocky Linux] and
|
||||
[PostgreSQL][PostgreSQL instructions Rocky Linux].
|
||||
|
||||
|
||||
### 3.3 Database configuration (Rocky Linux)
|
||||
|
||||
Create the database tables:
|
||||
|
||||
```sh
|
||||
(cd / && sudo --user=zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.pl)
|
||||
```
|
||||
|
||||
|
||||
### 3.4 Service configuration and startup (Rocky Linux)
|
||||
|
||||
Make sure our tmpfiles configuration takes effect:
|
||||
|
||||
```sh
|
||||
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf
|
||||
```
|
||||
|
||||
Enable services at boot time and start them:
|
||||
|
||||
```sh
|
||||
sudo systemctl enable zm-rpcapi
|
||||
sudo systemctl enable zm-testagent
|
||||
sudo systemctl start zm-rpcapi
|
||||
sudo systemctl start zm-testagent
|
||||
```
|
||||
|
||||
If you have changed database daemon, restart the services:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart zm-rpcapi
|
||||
sudo systemctl restart zm-testagent
|
||||
```
|
||||
|
||||
### 3.5 Post-installation (Rocky Linux)
|
||||
|
||||
To check if the daemons are running, do:
|
||||
|
||||
```sh
|
||||
sudo systemctl status --no-pager zm-rpcapi
|
||||
sudo systemctl status --no-pager zm-testagent
|
||||
```
|
||||
|
||||
See the [post-installation] section for post-installation matters.
|
||||
|
||||
|
||||
## 4. Installation on Debian and Ubuntu
|
||||
|
||||
### 4.1 Install Zonemaster::Backend and related dependencies (Debian/Ubuntu)
|
||||
|
||||
> **Note:** Zonemaster::LDNS and Zonemaster::Engine are not listed here as they
|
||||
> are dealt with in the [prerequisites section].
|
||||
|
||||
Install required locales:
|
||||
|
||||
```sh
|
||||
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.*|sl_SI\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
|
||||
sudo locale-gen
|
||||
```
|
||||
|
||||
After 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
|
||||
sl_SI.utf8
|
||||
sv_SE.utf8
|
||||
```
|
||||
|
||||
Install dependencies available from binary packages:
|
||||
|
||||
```sh
|
||||
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 libtest-nowarnings-perl libtest-differences-perl libtest-exception-perl libtry-tiny-perl libintl-perl perl-doc starman
|
||||
```
|
||||
> **Note**: libio-stringy-perl is listed here even though it's not a direct
|
||||
> dependency. It's an undeclared dependency of libconfig-inifiles-perl.
|
||||
|
||||
For Ubuntu 20.04 only, install JSON::Validator from CPAN as the one in the system packages repository is too old:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest JSON::Validator
|
||||
```
|
||||
|
||||
Install Zonemaster::Backend:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::Backend
|
||||
```
|
||||
|
||||
Add Zonemaster user (unless it already exists):
|
||||
|
||||
```sh
|
||||
sudo useradd -r -c "Zonemaster daemon user" zonemaster
|
||||
```
|
||||
|
||||
Install files to their proper locations:
|
||||
|
||||
```sh
|
||||
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 644 ./tmpfiles.conf /usr/lib/tmpfiles.d/zonemaster.conf
|
||||
```
|
||||
|
||||
> If this is an update of Zonemaster-Backend, you should remove any
|
||||
> `/etc/init.d/zm-backend.sh` (script from previous version of Zonemaster-Backend).
|
||||
|
||||
|
||||
### 4.2 Database engine installation (Debian/Ubuntu)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### 4.2.1 Instructions for SQLite (Debian/Ubuntu)
|
||||
|
||||
> **Note:** Zonemaster with SQLite is not meant for an installation with heavy
|
||||
> load.
|
||||
|
||||
Create database directory:
|
||||
|
||||
```sh
|
||||
sudo install -v -m 755 -o zonemaster -g zonemaster -d /var/lib/zonemaster
|
||||
```
|
||||
|
||||
> Some parameters can be changed, see the [backend configuration] documentation
|
||||
> for details.
|
||||
|
||||
|
||||
#### 4.2.2 Instructions for other engines (Debian/Ubuntu)
|
||||
|
||||
See sections for [MariaDB][MariaDB instructions Debian] and
|
||||
[PostgreSQL][PostgreSQL instructions Debian].
|
||||
|
||||
|
||||
### 4.3 Database configuration (Debian/Ubuntu)
|
||||
|
||||
Create the database tables:
|
||||
|
||||
```sh
|
||||
sudo -u zonemaster $(perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")')/create_db.pl
|
||||
```
|
||||
|
||||
|
||||
### 4.4 Service configuration and startup (Debian/Ubuntu)
|
||||
|
||||
Make sure our tmpfiles configuration takes effect:
|
||||
|
||||
```sh
|
||||
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/zonemaster.conf
|
||||
```
|
||||
|
||||
Enable services at boot time and start them:
|
||||
|
||||
```sh
|
||||
sudo systemctl enable zm-rpcapi
|
||||
sudo systemctl enable zm-testagent
|
||||
sudo systemctl start zm-rpcapi
|
||||
sudo systemctl start zm-testagent
|
||||
```
|
||||
|
||||
If you have changed database daemon, restart the services:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart zm-rpcapi
|
||||
sudo systemctl restart zm-testagent
|
||||
```
|
||||
|
||||
### 4.5 Post-installation (Debian/Ubuntu)
|
||||
|
||||
To check if the daemons are running, do:
|
||||
|
||||
```sh
|
||||
sudo systemctl status zm-rpcapi
|
||||
sudo systemctl status zm-testagent
|
||||
```
|
||||
|
||||
See the [post-installation] section for post-installation matters.
|
||||
|
||||
|
||||
## 5. Installation on FreeBSD
|
||||
|
||||
For all commands below, acquire privileges, i.e. become root:
|
||||
|
||||
```sh
|
||||
su -l
|
||||
```
|
||||
|
||||
### 5.1 Install Zonemaster::Backend and related dependencies (FreeBSD)
|
||||
|
||||
> **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:
|
||||
|
||||
```sh
|
||||
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-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 gmake
|
||||
```
|
||||
<!-- JSON::Validator requires YAML::PP, but p5-JSON-Validator currently lacks a dependency on p5-YAML-LibYAML -->
|
||||
|
||||
Install Zonemaster::Backend:
|
||||
|
||||
```sh
|
||||
cpanm --notest Zonemaster::Backend
|
||||
```
|
||||
|
||||
Unless they already exist, add `zonemaster` user and `zonemaster` group:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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_testagent
|
||||
```
|
||||
|
||||
### 5.2 Database engine installation (FreeBSD)
|
||||
|
||||
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.
|
||||
|
||||
#### 5.2.1 Instructions for SQLite (FreeBSD)
|
||||
|
||||
> **Note:** Zonemaster with SQLite is not meant for an installation with heavy
|
||||
> load.
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database path:
|
||||
|
||||
```sh
|
||||
sed -i '' '/[[:<:]]database_file[[:>:]]/ s:=.*:= /var/db/zonemaster/db.sqlite:' /usr/local/etc/zonemaster/backend_config.ini
|
||||
```
|
||||
|
||||
Create database directory:
|
||||
|
||||
```sh
|
||||
install -v -m 755 -o zonemaster -g zonemaster -d /var/db/zonemaster
|
||||
```
|
||||
|
||||
> Some parameters can be changed, see the [backend configuration] documentation
|
||||
> for details.
|
||||
|
||||
#### 5.2.2 Instructions for other engines (FreeBSD)
|
||||
|
||||
See sections for [MySQL][MySQL instructions FreeBSD] and
|
||||
[PostgreSQL][PostgreSQL instructions FreeBSD].
|
||||
|
||||
|
||||
### 5.3 Database configuration (FreeBSD)
|
||||
|
||||
Create the database tables:
|
||||
|
||||
```sh
|
||||
su -m zonemaster -c "`perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir(qw(Zonemaster-Backend))'`/create_db.pl"
|
||||
```
|
||||
|
||||
|
||||
### 5.4 Service startup (FreeBSD)
|
||||
|
||||
Enable services at startup and start service:
|
||||
|
||||
```sh
|
||||
sysrc zm_rpcapi_enable="YES"
|
||||
sysrc zm_testagent_enable="YES"
|
||||
service zm_rpcapi start
|
||||
service zm_testagent start
|
||||
```
|
||||
|
||||
If you have changed database daemon, restart the services:
|
||||
|
||||
```sh
|
||||
service zm_rpcapi restart
|
||||
service zm_testagent restart
|
||||
```
|
||||
|
||||
### 5.5 Post-installation (FreeBSD)
|
||||
|
||||
To check that the running daemons run:
|
||||
|
||||
```sh
|
||||
service zm_rpcapi status
|
||||
service zm_testagent status
|
||||
```
|
||||
|
||||
See the [post-installation] section for post-installation matters.
|
||||
|
||||
|
||||
## 6. Post-installation
|
||||
|
||||
### 6.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.
|
||||
|
||||
```sh
|
||||
zmtest zonemaster.net
|
||||
```
|
||||
|
||||
The 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.
|
||||
|
||||
### 6.2 Troubleshooting installation
|
||||
|
||||
If you have any issue with installation, and installed with `cpanm`, redo the
|
||||
installation above but without the `--notest` and with the `--verbose` option.
|
||||
Installation will take longer time.
|
||||
|
||||
### 6.3. What to do next?
|
||||
|
||||
* For the Zonemaster-Backend functions see the following documents:
|
||||
* [Using Zonemaster-Backend JSON-RPC API]
|
||||
* Backend [JSON-RPC API] documentation
|
||||
* [Using Zonemaster-Backend for batch testing]
|
||||
* [Backend configuration]
|
||||
* Zonemaster [Profiles]
|
||||
* [Backend Environment variables]
|
||||
* For a web interface, follow the [Zonemaster::GUI installation] instructions.
|
||||
* For a command line interface, follow the [Zonemaster::CLI installation] instruction.
|
||||
|
||||
## 7. Installation with MariaDB
|
||||
|
||||
First follow the installation instructions for the OS in question, and then go
|
||||
to this section to install MariaDB.
|
||||
|
||||
### 7.1. MariaDB (Rocky Linux)
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.ini
|
||||
```
|
||||
|
||||
> **Note:** See the [backend configuration] documentation for details.
|
||||
|
||||
Install database engine:
|
||||
|
||||
```sh
|
||||
sudo dnf -y install mariadb-server perl-DBD-mysql
|
||||
```
|
||||
|
||||
To 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.
|
||||
|
||||
```sh
|
||||
sudo systemctl start mariadb
|
||||
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](#33-database-configuration-rocky-linux)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
### 7.2. MariaDB (Debian/Ubuntu)
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sudo sed -i '/\bengine\b/ s/=.*/= MySQL/' /etc/zonemaster/backend_config.ini
|
||||
```
|
||||
|
||||
> **Note:** See the [backend configuration] documentation for details.
|
||||
|
||||
Install the database engine and its dependencies:
|
||||
|
||||
```sh
|
||||
sudo apt install mariadb-server libdbd-mysql-perl
|
||||
```
|
||||
|
||||
To 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.
|
||||
|
||||
```sh
|
||||
sudo mysql -e "CREATE DATABASE zonemaster;"
|
||||
```
|
||||
```sh
|
||||
sudo mysql -e "CREATE USER 'zonemaster'@'localhost' IDENTIFIED BY 'zonemaster';"
|
||||
```
|
||||
```sh
|
||||
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](#43-database-configuration-debianubuntu)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
### 7.3. MySQL (FreeBSD)
|
||||
|
||||
> MariaDB is not compatible with Zonemaster on FreeBSD. MySQL is used instead.
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= MySQL/' /usr/local/etc/zonemaster/backend_config.ini
|
||||
```
|
||||
> **Note:** See the [backend configuration] documentation for details.
|
||||
|
||||
Install, configure and start database engine (and Perl bindings):
|
||||
|
||||
```sh
|
||||
pkg install mysql80-server p5-DBD-mysql
|
||||
```
|
||||
|
||||
```sh
|
||||
sysrc mysql_enable="YES"
|
||||
service mysql-server start
|
||||
```
|
||||
|
||||
By default the MySQL root password is empty. Just press ENTER if prompted for
|
||||
password. The advice is to set a 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.
|
||||
|
||||
```sh
|
||||
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](#53-database-configuration-freebsd)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
## 8. Installation with PostgreSQL
|
||||
|
||||
First follow the installation instructions for the OS in question, and then go
|
||||
to this section to install PostgreSQL.
|
||||
|
||||
### 8.1. PostgreSQL (Rocky Linux)
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.ini
|
||||
```
|
||||
|
||||
> **Note:** See the [backend configuration] documentation for details.
|
||||
|
||||
Install, initialize and configure database engine:
|
||||
|
||||
```sh
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
sudo systemctl start postgresql
|
||||
sudo --login --user=postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
|
||||
sudo --login --user=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](#33-database-configuration-rocky-linux)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
### 8.2. PostgreSQL (Debian/Ubuntu)
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sudo sed -i '/\bengine\b/ s/=.*/= PostgreSQL/' /etc/zonemaster/backend_config.ini
|
||||
```
|
||||
|
||||
Install the database engine and Perl bindings:
|
||||
|
||||
```sh
|
||||
sudo apt install postgresql libdbd-pg-perl
|
||||
```
|
||||
|
||||
> **Note:** 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.
|
||||
|
||||
```sh
|
||||
sudo -u postgres psql -c "CREATE USER zonemaster WITH PASSWORD 'zonemaster';"
|
||||
|
||||
```
|
||||
```sh
|
||||
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](#43-database-configuration-debianubuntu)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
### 8.3. PostgreSQL (FreeBSD)
|
||||
|
||||
Configure Zonemaster::Backend to use the correct database engine:
|
||||
|
||||
```sh
|
||||
sed -i '' '/[[:<:]]engine[[:>:]]/ s/=.*/= PostgreSQL/' /usr/local/etc/zonemaster/backend_config.ini
|
||||
```
|
||||
> **Note:** See the [backend configuration] documentation for details.
|
||||
|
||||
Install, configure and start database engine and Perl bindings:
|
||||
|
||||
```sh
|
||||
pkg install p5-DBD-Pg
|
||||
```
|
||||
|
||||
The Perl bindings library (`p5-DBD-Pg`) has a dependency to a specific version
|
||||
of `postgresql-client`. Determine what version was installed:
|
||||
|
||||
```sh
|
||||
pkg info | grep postgresql | grep client
|
||||
```
|
||||
Replace `XX` in the command below to install `postgresql-server` with the same
|
||||
major version as the installed `postgresql-client`, e.g. `17`.
|
||||
|
||||
```sh
|
||||
pkg install postgresqlXX-server
|
||||
```
|
||||
|
||||
Enable daemon, initiate and start:
|
||||
|
||||
```sh
|
||||
sysrc postgresql_enable="YES"
|
||||
service postgresql initdb
|
||||
service postgresql start
|
||||
```
|
||||
|
||||
To 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.
|
||||
|
||||
```sh
|
||||
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](#53-database-configuration-freebsd)"
|
||||
to create the database tables and then continue with the steps after that.
|
||||
|
||||
|
||||
## 9. 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).
|
||||
|
||||
> Each script uses default values, you may need to adapt them to your setup.
|
||||
|
||||
### 9.1. MariaDB and MySQL
|
||||
|
||||
Rocky Linux, Debian and Ubuntu:
|
||||
|
||||
```sh
|
||||
sudo mysql --user=root < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sql
|
||||
```
|
||||
|
||||
FreeBSD (you will get prompted for MySQL password):
|
||||
|
||||
```sh
|
||||
mysql --user=root -p < `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-mysql.sql
|
||||
```
|
||||
|
||||
### 9.2. PostgreSQL
|
||||
|
||||
Rocky Linux, Debian and Ubuntu:
|
||||
|
||||
```sh
|
||||
sudo -u postgres psql -f $(perl -MFile::ShareDir=dist_dir -E 'say dist_dir("Zonemaster-Backend")')/cleanup-postgres.sql
|
||||
```
|
||||
|
||||
FreeBSD (as root):
|
||||
|
||||
```sh
|
||||
psql -U postgres -f `perl -MFile::ShareDir -le 'print File::ShareDir::dist_dir("Zonemaster-Backend")'`/cleanup-postgres.sql
|
||||
```
|
||||
|
||||
### 9.3. SQLite
|
||||
|
||||
Remove the database file and recreate it following the installation instructions above.
|
||||
|
||||
## 10. Optional features
|
||||
|
||||
### 10.1 Metrics
|
||||
|
||||
Statsd metrics are available, to enable the feature install the additional
|
||||
`Net::Statsd` module. See the [configuration][Backend configuration] to
|
||||
configure the receiver.
|
||||
|
||||
The list of metrics is available in the [Telemetry document][metrics].
|
||||
|
||||
### 10.1.1 Installation on Rocky Linux
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Net::Statsd
|
||||
```
|
||||
|
||||
### 10.1.2 Installation on Debian / Ubuntu
|
||||
|
||||
|
||||
```sh
|
||||
sudo apt install libnet-statsd-perl
|
||||
```
|
||||
|
||||
### 10.1.3 Installation on Freebsd
|
||||
|
||||
```sh
|
||||
cpanm --notest Net::Statsd
|
||||
```
|
||||
|
||||
### 10.2 Global cache
|
||||
|
||||
If Zonemaster-Backend is to be used for large batches, global cache can improve
|
||||
performance. See [Global cache in Zonemaster-Engine].
|
||||
|
||||
|
||||
[Backend Environment variables]: ../configuration/backend-environment-variables.md
|
||||
[Backend configuration]: ../configuration/backend.md
|
||||
[Declaration of prerequisites]: prerequisites.md
|
||||
[Global cache in Zonemaster-Engine]: ../configuration/global-cache.md
|
||||
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
|
||||
[Main Zonemaster repository]: https://github.com/zonemaster/zonemaster/blob/master/README.md
|
||||
[MariaDB instructions Debian]: #72-mariadb-debianubuntu
|
||||
[MariaDB instructions Rocky Linux]: #71-mariadb-rocky-linux
|
||||
[Metrics]: ../using/backend/telemetry.md#metrics
|
||||
[MySQL instructions FreeBSD]: #73-mysql-freebsd
|
||||
[Post-installation]: #6-post-installation
|
||||
[PostgreSQL instructions Debian]: #82-postgresql-debianubuntu
|
||||
[PostgreSQL instructions FreeBSD]: #83-postgresql-freebsd
|
||||
[PostgreSQL instructions Rocky Linux]: #81-postgresql-rocky-linux
|
||||
[Prerequisites section]: #2-prerequisites
|
||||
[Profiles]: ../configuration/profiles.md
|
||||
[Removing database]: #9-cleaning-up-the-database
|
||||
[Upgrade document]: ../upgrading/backend.md
|
||||
[Using Zonemaster-Backend for batch testing]: ../using/backend/Using-Zonemaster-Backend-for-batch-testing.md
|
||||
[Using Zonemaster-Backend JSON-RPC API]: ../using/backend/Using-Zonemaster-Backend-JSON-RPC-API.md
|
||||
[Zonemaster::CLI installation]: zonemaster-cli.md
|
||||
[Zonemaster::Engine installation]: zonemaster-engine.md
|
||||
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
|
||||
[Zonemaster::GUI installation]: zonemaster-gui.md
|
||||
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md
|
||||
[Docker]: https://en.wikipedia.org/wiki/Docker_(software)
|
||||
[Using the Backend]: ../using/backend/
|
||||
200
zonemaster/docs/public/installation/zonemaster-cli.md
Normal file
200
zonemaster/docs/public/installation/zonemaster-cli.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Installation: Zonemaster-CLI
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [Overview](#overview)
|
||||
* [Prerequisites for CPAN installation](#prerequisites-for-cpan-installation)
|
||||
* [Local installation](#local-installation)
|
||||
* [Installation on Rocky Linux](#installation-on-rocky-linux)
|
||||
* [Installation on Debian and Ubuntu](#installation-on-debian-and-ubuntu)
|
||||
* [Installation on FreeBSD](#installation-on-freebsd)
|
||||
* [Post-installation sanity check](#post-installation-sanity-check)
|
||||
* [Using Zonemaster-CLI](#using-zonemaster-cli)
|
||||
* [Global cache](#global-cache)
|
||||
* [What to do next?](#what-to-do-next)
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
Zonemaster-CLI provides a CLI (command line interface) to Zonemaster. To install
|
||||
follow the instructions below. An alternative to installing Zonemaster-CLI is to
|
||||
run it under [Docker]. See [Using the CLI] for run it under Docker.
|
||||
|
||||
|
||||
## Prerequisites for CPAN installation
|
||||
|
||||
Before installing Zonemaster::CLI from CPAN, you should [install
|
||||
Zonemaster::Engine][Zonemaster::Engine installation], unless you are
|
||||
to install on Debian using pre-built packages (see below).
|
||||
|
||||
> **Note:** [Zonemaster::Engine] and [Zonemaster::LDNS] are dependencies of
|
||||
> Zonemaster::CLI. 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 and operating system for
|
||||
Zonemaster::CLI, see the [declaration of prerequisites].
|
||||
|
||||
|
||||
## Local installation
|
||||
|
||||
### Installation on Rocky Linux
|
||||
|
||||
1) Install dependencies:
|
||||
|
||||
```sh
|
||||
sudo dnf install --assumeyes perl-JSON-XS perl-Try-Tiny perl-Test-Deep perl-Mojolicious
|
||||
```
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest JSON::Validator
|
||||
```
|
||||
|
||||
> Note: Test::Deep and Mojolicious are indirect dependencies. They are dependencies
|
||||
> of JSON::Validator.
|
||||
|
||||
2) Install Zonemaster::CLI
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::CLI
|
||||
```
|
||||
|
||||
|
||||
### Installation on Debian and Ubuntu
|
||||
|
||||
Using pre-built packages is the preferred method for Debian and Ubuntu.
|
||||
|
||||
#### Installation from pre-built packages
|
||||
|
||||
1) Add Zonemaster packages repository to repository list
|
||||
```sh
|
||||
curl -LOs https://package.zonemaster.net/setup.sh
|
||||
sudo sh setup.sh
|
||||
```
|
||||
2) Install Zonemaster CLI
|
||||
```sh
|
||||
sudo apt install zonemaster-cli
|
||||
```
|
||||
3) Update configuration of "locale"
|
||||
|
||||
```sh
|
||||
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.*|sl_SI\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
|
||||
sudo locale-gen
|
||||
```
|
||||
|
||||
After 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
|
||||
sl_SI.utf8
|
||||
sv_SE.utf8
|
||||
```
|
||||
|
||||
#### Installation from CPAN
|
||||
|
||||
1) Install dependencies:
|
||||
|
||||
```sh
|
||||
sudo apt-get install locales libmodule-install-perl libtry-tiny-perl libjson-validator-perl
|
||||
```
|
||||
|
||||
2) Install Zonemaster::CLI:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::CLI
|
||||
```
|
||||
3) Update configuration of "locale"
|
||||
|
||||
```sh
|
||||
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.*|sl_SI\.UTF-8.*|sv_SE\.UTF-8.*)/$1/' /etc/locale.gen
|
||||
sudo locale-gen
|
||||
```
|
||||
|
||||
After 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
|
||||
sl_SI.utf8
|
||||
sv_SE.utf8
|
||||
```
|
||||
|
||||
### Installation on FreeBSD
|
||||
|
||||
1) Become root:
|
||||
|
||||
```sh
|
||||
su -l
|
||||
```
|
||||
|
||||
2) Install dependencies available from binary packages:
|
||||
|
||||
```sh
|
||||
pkg install gmake p5-JSON-XS p5-Locale-libintl p5-Try-Tiny p5-JSON-Validator
|
||||
```
|
||||
|
||||
3) Install Zonemaster::CLI:
|
||||
|
||||
```sh
|
||||
cpanm --notest Zonemaster::CLI
|
||||
```
|
||||
|
||||
## Post-installation sanity check
|
||||
|
||||
Run the zonemaster-cli command:
|
||||
|
||||
```sh
|
||||
zonemaster-cli --test basic zonemaster.net
|
||||
```
|
||||
|
||||
The command is expected to take a few seconds and print some results about the
|
||||
delegation of zonemaster.net.
|
||||
|
||||
Also, verify that the manual page is properly installed:
|
||||
|
||||
```sh
|
||||
man zonemaster-cli
|
||||
```
|
||||
|
||||
|
||||
## Using Zonemaster-CLI
|
||||
|
||||
See [Using the CLI] for an overview on how to use `zonemaster-cli` after
|
||||
installation.
|
||||
|
||||
|
||||
## Global cache
|
||||
|
||||
If Zonemaster-CLI is to be used for large batches, global cache can improve
|
||||
performance. See [Global cache in Zonemaster-Engine].
|
||||
|
||||
|
||||
## What to do next?
|
||||
|
||||
* For a web GUI, follow the [Zonemaster::Backend][Zonemaster::Backend
|
||||
installation] and [Zonemaster::GUI installation] instructions.
|
||||
* For a [JSON-RPC][JSON-RPC API] frontend, follow the [Zonemaster::Backend
|
||||
installation] instruction.
|
||||
|
||||
|
||||
[Declaration of prerequisites]: prerequisites.md
|
||||
[Docker]: https://en.wikipedia.org/wiki/Docker_(software)
|
||||
[Global cache in Zonemaster-Engine]: ../configuration/global-cache.md
|
||||
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
|
||||
[Using the CLI]: ../using/cli.md
|
||||
[Zonemaster::Backend installation]: zonemaster-backend.md
|
||||
[Zonemaster::Engine installation]: zonemaster-engine.md
|
||||
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
|
||||
[Zonemaster::GUI installation]: zonemaster-gui.md
|
||||
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md
|
||||
195
zonemaster/docs/public/installation/zonemaster-engine.md
Normal file
195
zonemaster/docs/public/installation/zonemaster-engine.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Installation: Zonemaster-Engine
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [Local installation](#local-installation)
|
||||
* [Installation on Rocky Linux](#installation-on-rocky-linux)
|
||||
* [Installation on Debian and Ubuntu](#installation-on-debian-and-ubuntu)
|
||||
* [Installation on FreeBSD](#installation-on-freebsd)
|
||||
* [Post-installation sanity check](#post-installation-sanity-check)
|
||||
* [Troubleshooting installation](#troubleshooting-installation)
|
||||
* [Global cache](#global-cache)
|
||||
* [What to do next](#what-to-do-next)
|
||||
|
||||
|
||||
## Local installation
|
||||
|
||||
### Installation on Rocky Linux
|
||||
|
||||
1) Install the [EPEL] repository:
|
||||
|
||||
```sh
|
||||
sudo dnf install --assumeyes epel-release
|
||||
sudo crb enable
|
||||
```
|
||||
|
||||
2) Enable SHA-1 in the crypto policy:
|
||||
|
||||
```sh
|
||||
sudo tee /etc/crypto-policies/policies/modules/DNSSEC.pmod <<'EOF'
|
||||
hash@openssl = SHA1+
|
||||
sign@openssl = RSA-SHA1+
|
||||
EOF
|
||||
sudo update-crypto-policies --set DEFAULT:DNSSEC
|
||||
```
|
||||
|
||||
3) Install locales:
|
||||
|
||||
```sh
|
||||
sudo dnf install --assumeyes glibc-all-langpacks
|
||||
```
|
||||
|
||||
4) Install binary packages:
|
||||
|
||||
```sh
|
||||
sudo dnf install --assumeyes cpanminus gcc libidn2-devel openssl-devel perl-Class-Accessor perl-Clone perl-core perl-Devel-CheckLib perl-ExtUtils-PkgConfig perl-File-ShareDir perl-File-Slurp perl-libintl perl-IO-Socket-INET6 perl-List-Compare perl-List-MoreUtils perl-Mail-SPF perl-Module-Find perl-Module-Install perl-Net-DNS perl-Pod-Coverage perl-Readonly perl-Sub-Override perl-Test-Differences perl-Test-Exception perl-Test-Fatal perl-Test-NoWarnings perl-Test-Pod perl-Text-CSV perl-Test-Simple
|
||||
```
|
||||
|
||||
5) Install packages from CPAN:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Email::Valid Locale::PO Log::Any MIME::Base32 Module::Install::XSUtil Net::IP::XS YAML::XS
|
||||
```
|
||||
|
||||
6) Install Zonemaster::LDNS and Zonemaster::Engine:
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::LDNS Zonemaster::Engine
|
||||
```
|
||||
|
||||
### Installation on Debian and Ubuntu
|
||||
|
||||
Using pre-built packages is the preferred method for Debian and Ubuntu.
|
||||
|
||||
#### Installation from pre-built packages
|
||||
|
||||
1) Upgrade to latest patch level
|
||||
|
||||
```sh
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
|
||||
2) Add Zonemaster packages repository to repository list
|
||||
```sh
|
||||
curl -LOs https://package.zonemaster.net/setup.sh
|
||||
sudo sh setup.sh
|
||||
```
|
||||
|
||||
3) Install Zonemaster Engine
|
||||
```sh
|
||||
sudo apt install libzonemaster-engine-perl
|
||||
```
|
||||
|
||||
#### Installation from CPAN
|
||||
|
||||
1) Upgrade to latest patch level
|
||||
|
||||
```sh
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
|
||||
2) Install dependencies from binary packages:
|
||||
|
||||
```sh
|
||||
sudo apt install autoconf automake build-essential cpanminus libclass-accessor-perl libclone-perl libdevel-checklib-perl libemail-valid-perl libextutils-pkgconfig-perl libfile-sharedir-perl libfile-slurp-perl libidn2-dev libintl-perl libio-socket-inet6-perl liblist-compare-perl liblist-moreutils-perl liblocale-po-perl liblog-any-perl libmail-spf-perl libmime-base32-perl libmodule-find-perl libmodule-install-perl libmodule-install-xsutil-perl libnet-dns-perl libnet-ip-xs-perl libpod-coverage-perl libreadonly-perl libssl-dev libsub-override-perl libtest-differences-perl libtest-exception-perl libtest-fatal-perl libtest-nowarnings-perl libtest-pod-perl libtext-csv-perl libyaml-libyaml-perl libtool m4
|
||||
```
|
||||
|
||||
3) Install Zonemaster::LDNS and Zonemaster::Engine.
|
||||
|
||||
```sh
|
||||
sudo cpanm --notest Zonemaster::LDNS Zonemaster::Engine
|
||||
```
|
||||
|
||||
### Installation on FreeBSD
|
||||
|
||||
1) Become root:
|
||||
|
||||
```sh
|
||||
su -l
|
||||
```
|
||||
|
||||
2) Update list of package repositories:
|
||||
|
||||
Create the file `/usr/local/etc/pkg/repos/FreeBSD.conf` with the
|
||||
following content, unless it is already updated:
|
||||
|
||||
```
|
||||
FreeBSD: {
|
||||
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
|
||||
}
|
||||
```
|
||||
|
||||
3) Check or activate the package system:
|
||||
|
||||
Run the following command, and accept the installation of the `pkg` package
|
||||
if suggested.
|
||||
|
||||
```
|
||||
pkg info -E pkg
|
||||
```
|
||||
|
||||
4) Update local package repository:
|
||||
|
||||
```
|
||||
pkg update -f
|
||||
```
|
||||
|
||||
5) Install dependencies from binary packages:
|
||||
|
||||
```sh
|
||||
pkg install devel/gmake dns/ldns libidn2 p5-App-cpanminus p5-Class-Accessor p5-Clone p5-Devel-CheckLib p5-Email-Valid p5-ExtUtils-PkgConfig p5-File-ShareDir p5-File-Slurp p5-IO-Socket-INET6 p5-List-Compare p5-List-MoreUtils p5-Locale-libintl p5-Locale-PO p5-Log-Any p5-Mail-SPF p5-MIME-Base32 p5-Module-Find p5-Module-Install p5-Module-Install-XSUtil p5-Net-DNS p5-Net-IP-XS p5-Pod-Coverage p5-Readonly p5-Sub-Override p5-Test-Differences p5-Test-Exception p5-Test-Fatal p5-Test-NoWarnings p5-Test-Pod p5-Text-CSV p5-YAML-LibYAML
|
||||
```
|
||||
|
||||
6) Install Zonemaster::LDNS:
|
||||
|
||||
```sh
|
||||
cpanm --notest --configure-args="--no-internal-ldns" Zonemaster::LDNS
|
||||
```
|
||||
|
||||
7) Install Zonemaster::Engine:
|
||||
|
||||
```sh
|
||||
cpanm --notest Zonemaster::Engine
|
||||
```
|
||||
|
||||
## Post-installation sanity check
|
||||
|
||||
Make sure Zonemaster::Engine is properly installed.
|
||||
|
||||
```sh
|
||||
time perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'
|
||||
```
|
||||
|
||||
The command is expected to take a few seconds and print some results about the
|
||||
delegation of zonemaster.net.
|
||||
|
||||
|
||||
## Troubleshooting installation
|
||||
|
||||
If you have any issue with installation, and installed with `cpanm`, redo the
|
||||
installation above but without the `--notest` and with the `--verbose` option.
|
||||
Installation will take longer time.
|
||||
|
||||
|
||||
## Global cache
|
||||
|
||||
Global cache is a feature that can be enabled in Zonemaster-Engine and consists
|
||||
in a shared, persistent cache. It can increase the performance when many tests
|
||||
are run within a short time frame. See [global cache configuration].
|
||||
|
||||
|
||||
## What to do next
|
||||
|
||||
* For a command line interface, follow the [Zonemaster::CLI installation] instruction.
|
||||
* For a web interface, follow the [Zonemaster::Backend installation] and [Zonemaster::GUI installation] instructions.
|
||||
* For a [JSON-RPC API], follow the [Zonemaster::Backend installation] instruction.
|
||||
* For a Perl API, see the [Zonemaster::Engine API] documentation.
|
||||
|
||||
|
||||
[EPEL]: https://docs.fedoraproject.org/en-US/epel/
|
||||
[Global cache configuration]: ../configuration/global-cache.md
|
||||
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
|
||||
[Zonemaster::Backend installation]: zonemaster-backend.md
|
||||
[Zonemaster::CLI installation]: zonemaster-cli.md
|
||||
[Zonemaster::Engine API]: https://metacpan.org/pod/Zonemaster::Engine
|
||||
[Zonemaster::GUI installation]: zonemaster-gui.md
|
||||
284
zonemaster/docs/public/installation/zonemaster-gui.md
Normal file
284
zonemaster/docs/public/installation/zonemaster-gui.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# Installation: Zonemaster-GUI
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing Zonemaster-GUI, you should [install Zonemaster::Engine
|
||||
][Zonemaster::Engine installation] and [Zonemaster::Backend][Zonemaster::Backend
|
||||
installation].
|
||||
|
||||
Prerequisite for FreeBSD is that the package system is updated and activated,
|
||||
see FreeBSD section of [install Zonemaster::Engine][Zonemaster::Engine
|
||||
installation].
|
||||
|
||||
## Upgrading or installation of custom built Zonemaster-GUI
|
||||
|
||||
### Upgrading
|
||||
|
||||
If this installation is an upgrade or reinstallation of Zonemaster-GUI and if
|
||||
changes were made to the shipped configuration files
|
||||
(`/var/www/html/zonemaster-web-gui/dist/config.json` and the `zonemaster.conf`
|
||||
Apache configuration file), make sure to back up these files beforehand.
|
||||
|
||||
You should also consider saving the old version under a new path instead of
|
||||
just removing it.
|
||||
|
||||
Else upgrading is as simple as removing the old version and installing the new
|
||||
version in the same way as a new installation.
|
||||
|
||||
### Installing a custom built Zonemaster-GUI
|
||||
|
||||
If you have done a custom build of Zonemaster-GUI following the instructions in
|
||||
[building GUI] you will have a zip file that you will use instead of downloading
|
||||
it from GitHub. Else you can follow the instructions below.
|
||||
|
||||
## Installation
|
||||
|
||||
This instruction covers the following operating systems:
|
||||
|
||||
1. [Rocky Linux](#1-rocky-linux)
|
||||
2. [Debian and Ubuntu](#2-debian-and-ubuntu)
|
||||
3. [FreeBSD](#3-freebsd)
|
||||
|
||||
|
||||
### 1. Rocky Linux
|
||||
|
||||
#### Install Apache
|
||||
|
||||
```sh
|
||||
sudo dnf update
|
||||
sudo dnf -y install httpd unzip
|
||||
```
|
||||
|
||||
#### Remove old Zonemaster-GUI
|
||||
|
||||
If an old version is installed, remove it first:
|
||||
```sh
|
||||
sudo rm -r /var/www/html/zonemaster-web-gui
|
||||
```
|
||||
|
||||
#### Install Zonemaster-GUI
|
||||
|
||||
```sh
|
||||
curl -L -O https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.zip
|
||||
sudo install -vd /var/www/html/zonemaster-web-gui
|
||||
sudo install -vd /var/log/zonemaster
|
||||
sudo unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui_v5.0.1.zip
|
||||
rm -f zonemaster_web_gui_v5.0.1.zip
|
||||
```
|
||||
|
||||
#### Configure Apache site
|
||||
|
||||
```sh
|
||||
sudo chcon -R -t httpd_sys_content_t /var/www/html/zonemaster-web-gui/dist
|
||||
sudo chcon -R -t httpd_sys_rw_content_t /var/log/zonemaster
|
||||
sudo setsebool -P httpd_can_network_connect=1
|
||||
sudo install -v /var/www/html/zonemaster-web-gui/zonemaster.conf-example /etc/httpd/conf.d/zonemaster.conf
|
||||
```
|
||||
|
||||
Optionally update the zonemaster.conf.
|
||||
E.g. if Zonemaster-Backend RPCAPI runs on another server or on another port (not
|
||||
port 5000), update ProxyPass and ProxyPassReserve.
|
||||
Or if you want provide your own settings for ServerName, ServerAlias and ServerAdmin.
|
||||
|
||||
```sh
|
||||
sudoedit /etc/httpd/conf.d/zonemaster.conf
|
||||
```
|
||||
|
||||
#### Start Apache and allow remote access
|
||||
|
||||
```sh
|
||||
sudo systemctl enable httpd
|
||||
sudo systemctl start httpd
|
||||
sudo firewall-cmd --add-service http --permanent
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
### 2. Debian and Ubuntu
|
||||
|
||||
#### Install Apache
|
||||
|
||||
```sh
|
||||
sudo apt-get update && sudo apt-get upgrade -y
|
||||
sudo apt-get install -y apache2 unzip
|
||||
```
|
||||
|
||||
#### Basic Apache configuration
|
||||
|
||||
```sh
|
||||
sudo a2enmod proxy proxy_http rewrite
|
||||
sudo a2dissite 000-default
|
||||
sudo systemctl enable apache2
|
||||
sudo systemctl restart apache2
|
||||
```
|
||||
|
||||
#### Remove old Zonemaster-GUI
|
||||
|
||||
If an old version is installed, remove it first:
|
||||
```sh
|
||||
sudo rm -r /var/www/html/zonemaster-web-gui
|
||||
```
|
||||
|
||||
#### Install Zonemaster-GUI
|
||||
|
||||
```sh
|
||||
wget https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.zip -O zonemaster_web_gui_v5.0.1.zip
|
||||
sudo unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui_v5.0.1.zip
|
||||
sudo install -vd /var/log/zonemaster
|
||||
sudo install -v /var/www/html/zonemaster-web-gui/zonemaster.conf-example /etc/apache2/sites-available/zonemaster.conf
|
||||
rm -f zonemaster_web_gui_v5.0.1.zip
|
||||
```
|
||||
|
||||
#### Configure Zonemaster-GUI
|
||||
|
||||
```sh
|
||||
sudo a2ensite zonemaster #Activate the website
|
||||
```
|
||||
Then update the zonemaster.conf file with your own ServerName, ServerAlias and ServerAdmin.
|
||||
For testing on a local machine, you can edit zonemaster.conf and change the "*:80" part of
|
||||
to the host's IP or using localhost as ServerName if that is appropriate.
|
||||
|
||||
|
||||
#### Reload Apache
|
||||
|
||||
```sh
|
||||
sudo systemctl reload apache2
|
||||
```
|
||||
|
||||
### 3. FreeBSD
|
||||
|
||||
For all commands below become root:
|
||||
|
||||
```sh
|
||||
su -l
|
||||
```
|
||||
|
||||
#### Update list of package repositories
|
||||
Create the file `/usr/local/etc/pkg/repos/FreeBSD.conf` with the following
|
||||
content, unless it is already updated:
|
||||
|
||||
```
|
||||
FreeBSD: {
|
||||
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
|
||||
}
|
||||
```
|
||||
|
||||
#### Check or activate the package system
|
||||
|
||||
Run the following command, and accept the installation of the `pkg` package
|
||||
if suggested.
|
||||
|
||||
```
|
||||
pkg info -E pkg
|
||||
```
|
||||
|
||||
Update local package repository:
|
||||
|
||||
```
|
||||
pkg update -f
|
||||
```
|
||||
|
||||
#### Install Apache and its dependencies
|
||||
|
||||
See [tutorial on Apache on FreeBSD].
|
||||
|
||||
```sh
|
||||
pkg install apache24
|
||||
```
|
||||
|
||||
#### Enable Apache as a service
|
||||
|
||||
```sh
|
||||
sysrc apache24_enable=yes
|
||||
```
|
||||
|
||||
#### Enable three apache modules in Apache configuration file
|
||||
|
||||
```sh
|
||||
perl -pi -e 's/^#(LoadModule (proxy_module|proxy_http_module|rewrite_module) libexec)/$1/' /usr/local/etc/apache24/httpd.conf
|
||||
```
|
||||
|
||||
#### Start Apache
|
||||
|
||||
```sh
|
||||
service apache24 start
|
||||
```
|
||||
|
||||
If you want Apache to listen to an external IP address and it says that it only
|
||||
listens to localhost (127.0.0.1/::1) then you have to set `ServerName` in
|
||||
`/usr/local/etc/apache24/httpd.conf`, e.g. `ServerName 192.0.2.246:80`, and
|
||||
restart Apache.
|
||||
|
||||
#### Remove old Zonemaster-GUI
|
||||
|
||||
If an old version is installed, remove it first:
|
||||
```sh
|
||||
rm -r /var/www/html/zonemaster-web-gui
|
||||
```
|
||||
|
||||
#### Install Zonemaster-GUI
|
||||
|
||||
```sh
|
||||
fetch https://github.com/zonemaster/zonemaster-gui/releases/download/v5.0.1/zonemaster_web_gui_v5.0.1.zip
|
||||
mkdir -p /var/www/html/zonemaster-web-gui
|
||||
mkdir -p /var/log/zonemaster
|
||||
unzip -d /var/www/html/zonemaster-web-gui zonemaster_web_gui_v5.0.1.zip
|
||||
rm zonemaster_web_gui_v5.0.1.zip
|
||||
```
|
||||
|
||||
#### Basic Apache configuration
|
||||
|
||||
```sh
|
||||
install /var/www/html/zonemaster-web-gui/zonemaster.conf-example /usr/local/etc/apache24/Includes/zonemaster.conf
|
||||
```
|
||||
Then update `/usr/local/etc/apache24/Includes/zonemaster.conf` with your own ServerAdmin.
|
||||
If Zonemaster-Backend RPCAPI runs on another server or on another port (not port 5000)
|
||||
then update the URL for the `ProxyPass` and `ProxyPassReverse` keys in the same
|
||||
file so that it points to correct IP address or server name and correct port.
|
||||
|
||||
|
||||
#### Restart Apache
|
||||
```sh
|
||||
service apache24 restart
|
||||
```
|
||||
|
||||
|
||||
## Post-installation sanity check
|
||||
|
||||
Make sure Zonemaster-GUI is properly installed.
|
||||
|
||||
1. Point your browser at `http://localhost/` (or the address of the server where
|
||||
you installed Zonemaster-GUI).
|
||||
|
||||
2. Verify that the Zonemaster-GUI is shown with the text "Program versions" in
|
||||
its page footer.
|
||||
|
||||
3. Verify that when you mouse over this text the versions of the following
|
||||
Zonemaster components are shown: Zonemaster-LDNS, Zonemaster-Engine,
|
||||
Zonemaster-Backend and Zonemaster-GUI.
|
||||
|
||||
## What to do next?
|
||||
|
||||
* For a JSON-RPC API, see the Zonemaster::Backend [JSON-RPC API] documentation.
|
||||
* For a command line interface, follow the [Zonemaster::CLI installation] instruction.
|
||||
* For a Perl API, see the [Zonemaster::Engine API] documentation.
|
||||
* For HTTPS, see [Let's Encrypt / Certbot] or providers of public certificates.
|
||||
|
||||
## Configuring and customizing GUI
|
||||
|
||||
It is possible to change the behavior and visual aspects of GUI. See
|
||||
section [configuring GUI] for how to customize the GUI.
|
||||
|
||||
|
||||
[building GUI]: ../configuration/gui/building-custom-gui.md
|
||||
[JSON-RPC API]: ../using/backend/rpcapi-reference.md
|
||||
[Let's Encrypt / Certbot]: https://certbot.eff.org/instructions
|
||||
[Main Zonemaster repository]: https://github.com/zonemaster/zonemaster/blob/master/README.md
|
||||
[Tutorial on Apache on FreeBSD]: https://www.digitalocean.com/community/tutorials/how-to-install-an-apache-mysql-and-php-famp-stack-on-freebsd-10-1
|
||||
[Zonemaster::Backend installation]: zonemaster-backend.md
|
||||
[Zonemaster::Backend]: https://github.com/zonemaster/zonemaster-backend/blob/master/README.md
|
||||
[Zonemaster::CLI installation]: zonemaster-cli.md
|
||||
[Zonemaster::Engine API]: https://metacpan.org/dist/Zonemaster-Engine/view/lib/Zonemaster/Engine/Overview.pod
|
||||
[Zonemaster::Engine installation]: zonemaster-engine.md
|
||||
[Zonemaster::Engine]: https://github.com/zonemaster/zonemaster-engine/blob/master/README.md
|
||||
[Zonemaster::LDNS]: https://github.com/zonemaster/zonemaster-ldns/blob/master/README.md
|
||||
[Configuring GUI]: ../configuration/gui/README.md
|
||||
149
zonemaster/docs/public/installation/zonemaster-ldns.md
Normal file
149
zonemaster/docs/public/installation/zonemaster-ldns.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Installation: Zonemaster-LDNS
|
||||
|
||||
## Recommended installation
|
||||
|
||||
The recommended way to install Zonemaster::LDNS is to follow the
|
||||
[installation instructions for Zonemaster::Engine] where you will find all
|
||||
prerequisites and dependencies for Zonemaster::LDNS before installing it.
|
||||
|
||||
## Installation from source
|
||||
|
||||
Override the default set of features by appending `--FEATURE` and/or
|
||||
`--no-FEATURE` options to the `perl Makefile.PL` command.
|
||||
|
||||
```sh
|
||||
git clone https://github.com/zonemaster/zonemaster-ldns
|
||||
cd zonemaster-ldns
|
||||
perl Makefile.PL
|
||||
make
|
||||
make test
|
||||
make install
|
||||
```
|
||||
|
||||
> **Note:** The source ZIP files downloaded from GitHub are broken with
|
||||
> respect to this instruction.
|
||||
|
||||
|
||||
### Optional features
|
||||
|
||||
When installing from source, you can choose to enable or disable a number
|
||||
of optional features using command line options to the `perl Makefile.PL`
|
||||
commands.
|
||||
|
||||
#### Ed25519
|
||||
|
||||
Enabled by default.
|
||||
Disabled with `--no-ed25519`
|
||||
|
||||
Requires support for algorithms Ed25519 and Ed448 in both openssl and ldns.
|
||||
|
||||
>
|
||||
> *Note:* Zonemaster Engine relies on this feature for its analysis when Ed25519
|
||||
> (DNSKEY algorithm 15) or Ed448 (DNSKEY algorithm 16) is being used in DNSSEC
|
||||
> signatures.
|
||||
>
|
||||
|
||||
#### IDN
|
||||
|
||||
Enabled by default.
|
||||
Disable with `--no-idn`.
|
||||
|
||||
If the IDN feature is enabled, the GNU `libidn2` library will be used to
|
||||
add a simple function that converts strings from Perl's internal encoding
|
||||
to IDNA domain name format.
|
||||
In order to convert strings from whatever encoding you have to Perl's
|
||||
internal format, use L<Encode>.
|
||||
If you need any kind of control or options, use [Net::LibIDN].
|
||||
The included function here is only meant to assist in the most basic case,
|
||||
although that should cover a lot of real-world use cases.
|
||||
|
||||
> **Note:** The Zonemaster Engine test suite assumes this feature
|
||||
> is enabled.
|
||||
|
||||
#### Internal ldns
|
||||
|
||||
Enabled by default.
|
||||
Disable with `--no-internal-ldns`.
|
||||
|
||||
When enabled, an included version of ldns is statically linked into
|
||||
Zonemaster::LDNS.
|
||||
When disabled, libldns is dynamically linked just like other dependencies.
|
||||
|
||||
#### Custom OpenSSL
|
||||
|
||||
Disabled by default.
|
||||
Enabled with `--prefix-openssl=/path/to/openssl` or
|
||||
`--openssl-inc=/path/to/openssl_inc` or `--openssl-lib=/path/to/openssl_lib`.
|
||||
|
||||
Enabling this makes the build tools look for OpenSSL in a non-standard place.
|
||||
|
||||
Technically this does two things:
|
||||
* Libcrypto is sought in the `lib` directory under the given directory.
|
||||
* The `include` directory under the given directory is added to the include
|
||||
path.
|
||||
|
||||
> **Note:** The `lib` directory under the given path must be known to the
|
||||
> dynamic linker or feature checks will fail.
|
||||
|
||||
If both headers and libraries directories (`include` and `lib`) are not in the
|
||||
same parent directory, use `--openssl-inc` and `--openssl-lib` options to
|
||||
specify both paths.
|
||||
|
||||
|
||||
#### Custom LDNS
|
||||
|
||||
Disabled by default.
|
||||
Enabled with `--ldns-inc=/path/to/ldns_inc` or `--ldns-lib=/path/to/ldns_lib`.
|
||||
|
||||
Enabling this makes the build tools look for LDNS in a non-standard place.
|
||||
|
||||
> Requires [Internal LDNS] to be disabled.
|
||||
|
||||
|
||||
#### Custom Libidn
|
||||
|
||||
Disabled by default.
|
||||
Enabled with `--libidn-inc=/path/to/libidn_inc` or
|
||||
`--libidn-lib=/path/to/ldns_lib`.
|
||||
|
||||
Enabling this makes the build tools look for Libidn in a non-standard place.
|
||||
|
||||
> Requires [IDN] to be enabled.
|
||||
|
||||
|
||||
#### Debug
|
||||
|
||||
Disabled by default.
|
||||
Enabled with `--debug`.
|
||||
|
||||
Gives a more verbose output.
|
||||
|
||||
|
||||
## Post-installation sanity check
|
||||
|
||||
```sh
|
||||
perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("8.8.8.8")->query("zonemaster.net")->string'
|
||||
```
|
||||
|
||||
The above command should print some `dig`-like output.
|
||||
|
||||
|
||||
### Testing
|
||||
|
||||
Some of the unit tests depend on data on the Internet, which may change. To avoid
|
||||
false fails, those unit tests are only run if the environment variable
|
||||
`TEST_WITH_NETWORK` is `true`. By default that variable is unset (those tests are
|
||||
not run). To run all tests, execute
|
||||
|
||||
```sh
|
||||
TEST_WITH_NETWORK=1 make test
|
||||
```
|
||||
|
||||
|
||||
[Docker Hub]: https://hub.docker.com/u/zonemaster
|
||||
[Docker Image Creation]: ../../internal/maintenance/ReleaseProcess-create-docker-image.md
|
||||
[IDN]: #idn
|
||||
[Installation instructions for Zonemaster::Engine]: zonemaster-engine.md
|
||||
[Internal LDNS]: #internal-ldns
|
||||
[Net::LibIDN]: https://metacpan.org/pod/Net::LibIDN
|
||||
[USING]: ../using/
|
||||
Reference in New Issue
Block a user