Install Icinga 2 on Amazon Linux¶
Add Icinga Package Repository ¶
We recommend using our official repositories. Here’s how to add it to your system:
Amazon Linux 2 Repository ¶
Info
A paid repository subscription is required for Amazon Linux repositories. Get more information on icinga.com/subscription
Don’t forget to fill in the username and password section with your credentials in the local .repo file.
rpm --import https://packages.icinga.com/icinga.key
wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
The packages for Amazon Linux 2 depend on other packages which are distributed as part of the EPEL repository.
yum install epel-release
Install Icinga 2 ¶
You can install Icinga 2 by using your distribution’s package manager
to install the icinga2
package. The following commands must be executed
with root
permissions unless noted otherwise.
Tip
If you have SELinux enabled, the package icinga2-selinux
is also required.
yum install icinga2
systemctl enable icinga2
systemctl start icinga2
Systemd Service ¶
The majority of supported distributions use systemd. The Icinga 2 packages automatically install the necessary systemd unit files.
If you’re stuck with configuration errors, you can manually invoke the configuration validation.
icinga2 daemon -C
Tip
If you are running into fork errors with systemd enabled distributions, please check the troubleshooting chapter.
Set up Check Plugins ¶
Without plugins Icinga 2 does not know how to check external services. The Monitoring Plugins Project provides an extensive set of plugins which can be used with Icinga 2 to check whether services are working properly.
These plugins are required to make the example configuration work out-of-the-box.
Depending on which directory your plugins are installed into you may need to
update the global PluginDir
constant in your Icinga 2 configuration.
This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries.
Tip
Please refer to the service monitoring chapter for details about how to integrate additional check plugins into your Icinga 2 setup.
The packages for Amazon Linux 2 depend on other packages which are distributed as part of the EPEL repository.
amazon-linux-extras install epel
yum install nagios-plugins-all
Set up Database ¶
The IDO (Icinga Data Output) feature for Icinga 2 stores all configuration and status information into a database. Icinga Web 2 connects to the IDO database to visualize the data properly. You can either use a MySQL or PostgreSQL database.
We recommend to install and configure the IDO feature before continuing with the installation of Icinga Web 2.
Note
We’re currently working on a new data backend called Icinga DB. If you want to try the latest release candidate skip to the Icinga DB Chapter. Please keep in mind, that this version is not ready for use in production and currently only supports MySQL.
IDO with MySQL ¶
Install MySQL Server ¶
yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
Install IDO Feature ¶
The next step is to install the icinga2-ido-mysql
package using your
distribution’s package manager.
yum install icinga2-ido-mysql
Set up MySQL database ¶
Set up a MySQL database for Icinga 2:
# mysql -u root -p
CREATE DATABASE icinga;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
quit
After creating the database you can import the Icinga 2 IDO schema using the following command. Enter the root password into the prompt when asked.
mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
Enable the IDO MySQL feature ¶
The package provides a new configuration file that is installed in
/etc/icinga2/features-available/ido-mysql.conf
. You can update
the database credentials in this file.
All available attributes are explained in the IdoMysqlConnection object chapter.
Enable the ido-mysql
feature configuration file using the icinga2
command:
# icinga2 feature enable ido-mysql
Module 'ido-mysql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2.
systemctl restart icinga2
IDO with PostgreSQL ¶
Install PostgreSQL server ¶
yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
Install IDO Feature ¶
The next step is to install the icinga2-ido-pgsql
package using your
distribution’s package manager.
yum install icinga2-ido-pgsql
Set up PostgreSQL database¶
Set up a PostgreSQL database for Icinga 2:
cd /tmp
sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
sudo -u postgres createdb -O icinga -E UTF8 icinga
Note
It is assumed here that your locale is set to utf-8, you may run into problems otherwise.
Locate your pg_hba.conf
configuration file and add the icinga user with md5
as authentication method
and restart the postgresql server. Common locations for pg_hba.conf
are either
/etc/postgresql/*/main/pg_hba.conf
or /var/lib/pgsql/data/pg_hba.conf
.
# icinga
local icinga icinga md5
host icinga icinga 127.0.0.1/32 md5
host icinga icinga ::1/128 md5
# "local" is for Unix domain socket connections only
local all all ident
# IPv4 local connections:
host all all 127.0.0.1/32 ident
# IPv6 local connections:
host all all ::1/128 ident
Restart PostgreSQL:
systemctl restart postgresql
After creating the database and permissions you need to import the IDO database schema using the following command:
export PGPASSWORD=icinga
psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
Enable the IDO PostgreSQL feature ¶
The package provides a new configuration file that is installed in
/etc/icinga2/features-available/ido-pgsql.conf
. You can update
the database credentials in this file.
All available attributes are explained in the IdoPgsqlConnection object chapter.
Enable the ido-pgsql
feature configuration file using the icinga2
command:
# icinga2 feature enable ido-pgsql
Module 'ido-pgsql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2.
systemctl restart icinga2
Icinga DB ¶
Icinga DB is a new data backend currently in development. It’s purpose is to synchronise data between Icinga 2 (Redis) and Icinga Web 2 (MySQL), some day replacing the IDO. Don’t worry, we won’t drop support on the IDO any time soon.
Note
Icinga DB is not ready to be used in production and should only be used for testing purposes.
Configue Icinga DB ¶
First, make sure to setup Icinga DB itself and its database backends (Redis and MySQL) by following the installation instructions.
Enable Icinga DB feature ¶
Icinga 2 provides a configuration file that is installed in
/etc/icinga2/features-available/icingadb.conf
. You can update
the Redis credentials in this file.
All available attributes are explained in the IcingaDB object chapter.
You can enable the icingadb
feature configuration file using
icinga2 feature enable
:
# icinga2 feature enable icingadb
Module 'icingadb' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2.
systemctl restart icinga2
Set up Icinga 2 REST API ¶
Icinga Web 2 requires the REST API to send actions (reschedule check, etc.) and query object details.
You can run the CLI command icinga2 api setup
to enable the
api
feature and set up
certificates as well as a new API user root
with an auto-generated password in the
/etc/icinga2/conf.d/api-users.conf
configuration file:
icinga2 api setup
Edit the api-users.conf
file and add a new ApiUser object. Specify the permissions
attribute with minimal permissions required by Icinga Web 2.
object ApiUser "icingaweb2" {
password = "Wijsn8Z9eRs5E25d"
permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}
Restart Icinga 2 to activate the configuration.
systemctl restart icinga2
Install Icinga Web 2¶
You are now ready to start the installation of Icinga Web 2. Please follow the Icinga Web 2 installation instructions.
Note
If you’re using Icinga DB, follow the installation instructions to install and enable the Icinga DB Web module.
Syntax Highlighting ¶
Icinga 2 provides configuration examples for syntax highlighting using the vim
and nano
editors.
Using Vim ¶
Install the package vim-icinga2
with your distribution’s package manager.
yum install vim-icinga2
Ensure that syntax highlighting is enabled e.g. by editing the user’s vimrc
configuration file:
# vim ~/.vimrc
syntax on
Test it:
vim /etc/icinga2/conf.d/templates.conf
Using Nano ¶
Install the package nano-icinga2
with your distribution’s package manager.
yum install nano-icinga2
Copy the /etc/nanorc
sample file to your home directory.
cp /etc/nanorc ~/.nanorc
Include the icinga2.nanorc
file.
$ vim ~/.nanorc
## Icinga 2
include "/usr/share/nano/icinga2.nanorc"
Test it:
nano /etc/icinga2/conf.d/templates.conf
Installation Overview ¶
Enabled Features during Installation ¶
The default installation will enable three features required for a basic Icinga 2 installation:
checker
for executing checksnotification
for sending notificationsmainlog
for writing theicinga2.log
file
You can verify that by calling icinga2 feature list
CLI command to see which features are
enabled and disabled.
# icinga2 feature list
Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
Enabled features: checker mainlog notification
Installation Paths ¶
By default Icinga 2 uses the following files and directories:
Path | Description |
---|---|
/etc/icinga2 | Contains Icinga 2 configuration files. |
/usr/lib/systemd/system/icinga2.service | The Icinga 2 systemd service file on systems using systemd. |
/etc/systemd/system/icinga2.service.d/limits.conf | On distributions with systemd >227, additional service limits are required. |
/etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC. |
/usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary. |
/usr/lib*/icinga2 | Libraries and the Icinga 2 binary (use find /usr -type f -name icinga2 to locate the binary path). |
/usr/share/doc/icinga2 | Documentation files that come with Icinga 2. |
/usr/share/icinga2/include | The Icinga Template Library and plugin command configuration. |
/var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api). |
/var/run/icinga2 | PID file. |
/var/run/icinga2/cmd | Command pipe and Livestatus socket. |
/var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files. |
/var/spool/icinga2 | Used for performance data spool files. |
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. |
Addons ¶
A number of additional features are available in the form of addons. A list of popular addons is available in the Addons and Plugins chapter.
Backup ¶
Ensure to include the following in your backups:
- Configuration files in
/etc/icinga2
- Certificate files in
/var/lib/icinga2/ca
(Master CA key pair) and/var/lib/icinga2/certs
(node certificates) - Runtime files in
/var/lib/icinga2
- Optional: IDO database backup
Database Backup ¶
MySQL/MariaDB:
PostgreSQL: