Docs: recommend to install from packages
This commit is contained in:
Eric Lippmann
Thomas Gelf
parent
e42912d3e8
commit
fb4b1cff92
|
|
@ -1,151 +1,75 @@
|
|||
<a id="Installation"></a>Installation
|
||||
=====================================
|
||||
<!-- {% if index %} -->
|
||||
# Installing Icinga Director
|
||||
|
||||
These are the instructions for manual Director installations. You can
|
||||
learn more about how to automate this in the [automation](03-Automation.md) section
|
||||
of this documentation. In case you already installed Director and want to upgrade
|
||||
to the latest version, please [read on here](05-Upgrading.md).
|
||||
The recommended way to install Icinga Director and its dependencies is to use prebuilt packages for
|
||||
all supported platforms from our official release repository.
|
||||
Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is required to run Icinga Director
|
||||
and if it is not already set up, it is best to do this first.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
The following steps will guide you through installing and setting up Icinga Director.
|
||||
|
||||
* Icinga 2 (>= 2.8.0)
|
||||
* It is recommended to use the latest feature release of Icinga 2
|
||||
* All versions since 2.4.3 should also work fine, but
|
||||
we do no longer test and support them.
|
||||
* Some features require newer Icinga 2 releases
|
||||
* Flapping requires 2.8 for the thresholds to work - and at least 2.7 on all
|
||||
nodes
|
||||
* Icinga Web 2 (>= 2.8.0). All versions since 2.2 should also work fine, but
|
||||
might show smaller UI bugs and are not actively tested
|
||||
* The following Icinga modules must be installed and enabled:
|
||||
* [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (>=0.18.0)
|
||||
* If you are using Icinga Web < 2.9.0, the following modules are also required
|
||||
* [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (>=0.5.0)
|
||||
* [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (>=0.9.0)
|
||||
* A database: MariaDB (>= 10.1), MySQL (>= 5.7), PostgreSQL (>= 9.6). Other
|
||||
forks and older versions might work, but are neither tested not supported
|
||||
* PHP (>= 7.3)
|
||||
* Director v1.10 is the last version with support for PHP v5.6
|
||||
* php-pdo-mysql and/or php-pdo-pgsql
|
||||
* php-curl
|
||||
* php-iconv
|
||||
* php-pcntl (might already be built into your PHP binary)
|
||||
* php-posix (on RHEL/CentOS this is php-process, or rh-php7x-php-process)
|
||||
* php-sockets (might already be built into your PHP binary)
|
||||
* php-mbstring and php-json (already required by Icinga Web 2)
|
||||
To upgrade an existing Icinga Director installation to a newer version,
|
||||
see the [upgrading](05-Upgrading.md) documentation for the necessary steps.
|
||||
|
||||
Optional Requirements
|
||||
---------------------
|
||||
* For IBM DB2 Imports: php-pdo-ibm
|
||||
* For MSSQL Imports: php-mssql or php-pdo-dblib (or -sybase on some platforms)
|
||||
* For Oracle DB Imports: php-oci8 or php-pdo-oci
|
||||
* For Sqlite Imports: php-pdo-sqlite
|
||||
If you want to automate the installation, configuration and upgrade,
|
||||
you can learn more about it in the [automation](03-Automation.md) section of this documentation.
|
||||
|
||||
Database
|
||||
--------
|
||||
## Optional Requirements
|
||||
|
||||
### Create an empty Icinga Director database
|
||||
The following requirements are not necessary for installation,
|
||||
but may be needed later if you want to import from one of the listed sources:
|
||||
|
||||
HINT: You should replace `some-password` with a secure custom password.
|
||||
* For **IBM Db2** imports: `php-pdo-ibm`
|
||||
* For **Microsoft SQL Server** imports: `php-mssql`, `php-pdo-dblib` or `php-sybase` depending on your platform
|
||||
* For **Oracle Database** imports: `php-oci8` or `php-pdo-oci` depending on your platform
|
||||
* For **SQLite** imports: `php-pdo-sqlite`
|
||||
<!-- {% else %} -->
|
||||
<!-- {% if not icingaDocs %} -->
|
||||
|
||||
#### MySQL (or MariaDB)
|
||||
## Installing Icinga Director Package
|
||||
|
||||
mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
|
||||
CREATE USER director@localhost IDENTIFIED BY 'some-password';
|
||||
If the [repository](https://packaages.icinga.com) is not configured yet, please add it first.
|
||||
Then use your distribution's package manager to install the `icinga-director` package
|
||||
or install [from source](02-Installation.md.d/From-Source.md).
|
||||
<!-- {% endif %} -->
|
||||
|
||||
## Setting up the Database
|
||||
|
||||
A MySQL (≥5.7), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Director.
|
||||
Please follow the steps listed for your target database, to set up the database and the user.
|
||||
The schema will be imported later via the web interface.
|
||||
|
||||
### Setting up a MySQL or MariaDB Database
|
||||
|
||||
> **Warning**
|
||||
> Make sure to replace `CHANGEME` with a secure password.
|
||||
|
||||
```
|
||||
mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
|
||||
CREATE USER director@localhost IDENTIFIED BY 'CHANGEME';
|
||||
GRANT ALL ON director.* TO director@localhost;"
|
||||
|
||||
In case your MySQL root user is password-protected, please add `-p` to this
|
||||
command.
|
||||
|
||||
#### PostgreSQL
|
||||
|
||||
psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
|
||||
psql director -q -c "CREATE USER director WITH PASSWORD 'some-password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE director TO director;
|
||||
CREATE EXTENSION pgcrypto;"
|
||||
|
||||
Web-based Configuration
|
||||
-----------------------
|
||||
|
||||
The following steps should guide you through the web-based Kickstart wizard.
|
||||
In case you prefer automated configuration, you should check the dedicated
|
||||
[documentation section](03-Automation.md).
|
||||
|
||||
### Create a Database resource
|
||||
|
||||
In your web frontend please go to `Configuration / Application / Resources`
|
||||
and create a new database resource pointing to your newly created database.
|
||||
Please make sure that you choose `utf8` as an encoding.
|
||||
|
||||
|
||||
### Install the Director module
|
||||
|
||||
As with any Icinga Web 2 module, installation is pretty straight-forward. In
|
||||
case you're installing it from source all you have to do is to drop the director
|
||||
module in one of your module paths. You can examine (and set) the module path(s)
|
||||
in `Configuration / Application`. In a typical environment you'll probably drop the
|
||||
module to `/usr/share/icingaweb2/modules/director`. Please note that the directory
|
||||
name MUST be `director` and not `icingaweb2-module-director` or anything else.
|
||||
|
||||
#### Installation from release tarball
|
||||
|
||||
Download the [latest version](https://github.com/Icinga/icingaweb2-module-director/releases)
|
||||
and extract it to a folder named `director` in one of your Icinga Web 2 module path directories.
|
||||
|
||||
You might want to use a script as follows for this task:
|
||||
|
||||
```shell
|
||||
MODULE_VERSION="1.10.1"
|
||||
ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
|
||||
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
|
||||
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
|
||||
URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
|
||||
|
||||
useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /bin/false icingadirector
|
||||
install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector
|
||||
install -d -m 0755 "${TARGET_DIR}"
|
||||
wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1
|
||||
cp "${TARGET_DIR}/contrib/systemd/icinga-director.service" /etc/systemd/system/
|
||||
|
||||
icingacli module enable director
|
||||
systemctl daemon-reload
|
||||
systemctl enable icinga-director.service
|
||||
systemctl start icinga-director.service
|
||||
```
|
||||
|
||||
Proceed to running the kickstart wizard.
|
||||
### Setting up a PostgreSQL Database
|
||||
|
||||
#### Installation from GIT repository
|
||||
> **Warning**
|
||||
> Make sure to replace `CHANGEME` with a secure password.
|
||||
|
||||
Another convenient method is the installation directly from our GIT repository.
|
||||
Just clone the repository to one of your Icinga Web 2 module path directories.
|
||||
It will be immediately ready for use:
|
||||
|
||||
```shell
|
||||
MODULE_VERSION="1.10.1"
|
||||
ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
|
||||
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
|
||||
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
|
||||
|
||||
useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /bin/false icingadirector
|
||||
install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector
|
||||
git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
|
||||
cp "${TARGET_DIR}/contrib/systemd/icinga-director.service" /etc/systemd/system/
|
||||
|
||||
icingacli module enable director
|
||||
systemctl daemon-reload
|
||||
systemctl enable icinga-director.service
|
||||
systemctl start icinga-director.service
|
||||
```
|
||||
psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
|
||||
psql director -q -c "CREATE USER director WITH PASSWORD 'CHANGEME';
|
||||
GRANT ALL PRIVILEGES ON DATABASE director TO director;
|
||||
CREATE EXTENSION pgcrypto;"
|
||||
```
|
||||
|
||||
Proceed to running the kickstart wizard.
|
||||
## Configuring Icinga Director
|
||||
|
||||
### Run the graphical kickstart wizard
|
||||
Log in to your running Icinga Web setup with a privileged user
|
||||
and follow the steps below to configure Icinga Director:
|
||||
|
||||
Choose either `Icinga Director` directly from the main menu or
|
||||
navigate into `Configuration / Modules / director` and select the `Configuration`
|
||||
tab.
|
||||
|
||||
Either way you'll reach the kickstart wizards. Follow the instructions, and
|
||||
you're all done!
|
||||
1. Create a new resource for the Icinga Director [database](#setting-up-the-database) via the
|
||||
`Configuration → Application → Resources` menu.
|
||||
Please make sure that you configure `utf8` as encoding.
|
||||
2. Select `Icinga Director` directly from the main menu
|
||||
and you will be taken to the kickstart wizard. Follow the instructions and you are done!
|
||||
<!-- {% endif %} --><!-- {# end else if index #} -->
|
||||
|
|
|
|||
|
|
@ -0,0 +1,83 @@
|
|||
# Installing Icinga Director from Source
|
||||
|
||||
These are the instructions for manual Director installations.
|
||||
|
||||
Please see the Icinga Web documentation on
|
||||
[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source.
|
||||
Make sure you use `director` as the module name. The following requirements must also be met.
|
||||
|
||||
## Requirements
|
||||
|
||||
* PHP (≥7.3)
|
||||
* Director v1.10 is the last version with support for PHP v5.6
|
||||
* [Icinga 2](https://github.com/Icinga/icinga2) (≥2.8.0)
|
||||
* It is recommended to use the latest feature release of Icinga 2
|
||||
* All versions since 2.4.3 should also work fine, but
|
||||
we do no longer test and support them.
|
||||
* Some features require newer Icinga 2 releases
|
||||
* Flapping requires 2.8 for the thresholds to work - and at least 2.7 on all
|
||||
nodes
|
||||
* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.8.0). All versions since 2.2 should also work fine, but
|
||||
might show smaller UI bugs and are not actively tested
|
||||
* The following Icinga modules must be installed and enabled:
|
||||
* [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (≥0.18.0)
|
||||
* If you are using Icinga Web <2.9.0, the following modules are also required
|
||||
* [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (≥0.5.0)
|
||||
* [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (≥0.9.0)
|
||||
* A database: MariaDB (≥10.1), MySQL (≥5.7), PostgreSQL (≥9.6). Other
|
||||
forks and older versions might work, but are neither tested nor supported
|
||||
* `php-pdo-mysql` and/or `php-pdo-pgsql`
|
||||
* `php-curl`
|
||||
* `php-iconv`
|
||||
* `php-pcntl` (might already be built into your PHP binary)
|
||||
* `php-posix` or `php-process` depending on your platform
|
||||
* `php-sockets` (might already be built into your PHP binary)
|
||||
|
||||
## Installing from Release Tarball
|
||||
|
||||
Download the [latest version](https://github.com/Icinga/icingaweb2-module-director/releases)
|
||||
and extract it to a folder named `director` in one of your Icinga Web module path directories.
|
||||
|
||||
You might want to use a script as follows for this task:
|
||||
|
||||
```shell
|
||||
MODULE_VERSION="1.10.1"
|
||||
ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
|
||||
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
|
||||
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
|
||||
URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
|
||||
|
||||
install -d -m 0755 "${TARGET_DIR}"
|
||||
wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1
|
||||
icingacli module enable director
|
||||
```
|
||||
|
||||
## Installing from Git Repository
|
||||
|
||||
Another convenient method is to install directly from our Git repository.
|
||||
Simply clone the repository in one of your Icinga web module path directories.
|
||||
|
||||
You might want to use a script as follows for this task:
|
||||
|
||||
```shell
|
||||
MODULE_VERSION="1.10.1"
|
||||
ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
|
||||
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
|
||||
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
|
||||
|
||||
git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
|
||||
icingacli module enable director
|
||||
```
|
||||
|
||||
## Setting up the Director Daemon
|
||||
|
||||
For manual installations, the daemon user, its directory, and the systemd service need to be set up:
|
||||
|
||||
```shell
|
||||
useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /sbin/nologin icingadirector
|
||||
install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector
|
||||
install -pm 0644 contrib/systemd/icinga-director.service /etc/systemd/system
|
||||
systemctl daemon-reload
|
||||
systemctl enable --now icinga-director
|
||||
```
|
||||
<!-- {% include "02-Installation.md" %} -->
|
||||
Loading…
Reference in New Issue