= Configuring iCinga2 on Single server =

This will guide you through installing Icinga setup on Ubuntu 20.04 LTS server; 

=== Requirements ===

* Linux Server running Ubuntu 20.04 LTS
* SSL/ HTTPS Certificates issued ( May be using Letsencrypt or Otherwise)
* sudo access to the server. All following commands have to be entered as the root user. Best way to do it is, by login in as root with {{{ sudo su }}}

Execute the commands as super user

== Installing using a Script ==

Download the script into your server

`wget https://raw.githubusercontent.com/LEARN-LK/Tutorials/master/Scripts/ICINGA2/installing_icinga2_ubuntu.sh`

Assign execute permission for the script

`chmod +x installing_icinga2_ubuntu.sh`

Then execute file using terminal

`./installing_icinga2_ubuntu.sh`

Select `yes` for the options pop up when icinga2-ido-mysql starts installing and creating database for module. Enter a password for when it prompt(it is used for icinga2 database)

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/ido1.jpg, 600)]]

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/idoconfig2.png, 600)]]

Type here the password(This password will be used as icinga2 database password while icingaweb2 confgurations)

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/idoconfig4.png, 600)]]

== Starting Web Setup ==

Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: 

http://IP-ADDRESS/icingaweb2/setup

=== Configuration on web ===

You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time you visit Icinga Web 2 in your browser. When using the web setup you are required to authenticate using a token. 

you can find it by using the icingacli:

`icingacli setup token show`

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/wensetup5.png, 600)]]

Next page will show you the modules:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/mdulelist7.png, 600)]]

You can enable the modules you want by sliding bars and click Next:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/selectingmodules6.png, 600)]]

Please keep the Authentication type as database:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/requirements8.png, 600)]]

As the icingaweb_db resource, please add icingaweb2 database details in Mysql, You can find your database password for icingaweb2 user in `/home/passwords.txt` file

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/icingaweb_db_respurce9.png, 600)]]

Enter Authentication backend as icingaweb2:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/authenticationbackend10.png, 600)]]

Create a loging user for the icingaweb portal:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/creatingadmininstratoraccount11.png, 600)]]

Click next to proceed :

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/applicationconfiguration12.png, 600)]]

Change the database name to icinga2 :

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/monitoringbackekend15.png, 600)]]

Use the password you typed when the mysql ido configurations while executing the installation script:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/idoresource16.png, 600)]]

Enter the api-user details and you can find the details in `/etc/icinga2/conf.d/api-users.conf` file. (If you get an error while validating root, please restart the icinga service by `systemctl restart icinga2` and retry):


[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/apiuser17.png, 600)]]

Click next to proceed :

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/monitoringsecurity18.png, 600)]]

if the configurations are succeeded, following message is shown on the top, and click `Login to icinga web 2` in the right side

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/success20.png, 600)]]

Initial dashboard:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/initialdashboard22.png, 600)]]

=== Setup Icinga Director Module ===

Icinga2 Director Module will allow you to do the configuration by webapp. Unless you have to do it from CLI. We have installed the module from our script.


Let's Initialise a resource for director module. Resources can be created using `Configurations` > `Application` > `Resource` like following image.

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/addingresources24.png, 600)]]

After creating resource for director, select the created resource:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/config_source_fordirector25.png, 600)]]

If it asks API details, Put the hostname as endpoint and host as local host, API user details for director are in `/etc/icinga2/conf.d/api-users.conf` file.

After every deplyment, Please deploy by clicking `Deploy pending changes` on the top of the page :

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/deplypending_changes26.png, 600)]]

== Adding Hosts ==

Before adding hosts, the host templates have to be added. These templates should have the details on how host needs to be checked.

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/host_template28.png, 600)]]

Add the hosts after adding host template:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/add_hosts30.png, 600)]]

== Adding Services ==

Before adding services, the service templates has to be added,

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/service_template32.png, 600)]]

After, services can be added as following as per requirements:

[[Image(https://ws.learn.ac.lk/raw-attachment/wiki/NSM2021/Agenda/iCinga/service33.png, 600)]]



== Following is the Manual Installation == 

If you have completed the scripted installation, do not proceed. ( This is for references )

=== Ubuntu Repositories===

You need to add the Icinga repository to your package management configuration. The following commands must be executed with root permissions unless noted otherwise.

`apt-get update`

`apt-get -y install apt-transport-https wget gnupg`

`wget -O - https://packages.icinga.com/icinga.key | apt-key add -`

`. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; `

`echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" >  /etc/apt/sources.list.d/${DIST}-icinga.list`

`echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> /etc/apt/sources.list.d/${DIST}-icinga.list`

`apt-get update`

=== Installing Icinga 2  ===

The following commands must be executed with root permissions unless noted otherwise.

`apt-get install icinga2`

=== Setting 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.

`apt-get install monitoring-plugins`

=== Running Service ===

Start the service using following command

`systemctl restart icinga2`

Enabling the service if a reboot happens

`systemctl enable icinga2`

Extra :

If you’re stuck with configuration errors, you can manually invoke the configuration validation.

`icinga2 daemon -C`

=== Configuration Syntax Highlighting  ===

==== If you are using Vim ====

`apt-get install vim-icinga2 vim-addon-manager`

`vim-addon-manager -w install 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`

Note : 
If you are using Nano the syntax files are installed with the icinga2-common package already

=== Setting up Icinga Web 2 ===

==== Configuring DB IDO MySQL ====

Installing MySQL database server 

`apt-get install mariadb-server`

`mysql_secure_installation`

(After executing `mysql_secure_installation`, change the root password and remove test database.)


==== Installing the IDO modules for MySQL ==== 

The next step is to install the icinga2-ido-mysql

`apt-get install icinga2-ido-mysql`

Select `yes` for the options pop up and enter a password for when it prompt(it is used for icinga2 database)

Note :

(OPTIONAL)The Ubuntu packages provide a database configuration wizard by default. You can skip the automated setup and install/upgrade the database manually if you prefer.

==== Setting up the MySQL database ====

{{{
 mysql -u root -p

CREATE DATABASE icinga;

CREATE USER 'icinga'@'localhost' IDENTIFIED BY '###PASSSWORD### ;

GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost';

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`

==== Enabling the IDO MySQL module ====

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

You can enable the ido-mysql feature configuration file using icinga2 feature enable:

`icinga2 feature enable ido-mysql`

You will see Module 'ido-mysql' was enabled.

Make sure to restart Icinga 2 for these changes to take effect.

`systemctl restart icinga2`



==== Setting Up Icinga 2 REST API ====

Icinga Web 2 and other web interfaces require 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.


`vim /etc/icinga2/conf.d/api-users.conf`

{{{
object ApiUser "icingaweb2" {
  password = "Wijsn8Z9eRs5E25d"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}
}}}

(add an api user for the director as well)

Restart Icinga 2 to activate the configuration.

`systemctl restart icinga2`

==== Installing Icinga Web 2 ====

`apt-get install icingaweb2 libapache2-mod-php`

=== Preparing Web Setup ===

You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time you visit Icinga Web 2 in your browser. When using the web setup you are required to authenticate using a token. In order to generate a token use the icingacli:

`icingacli setup token create`

In case you do not remember the token you can show it using the icingacli:

`icingacli setup token show`

On Debian and derivates, you need to manually create a database and a database user prior to starting the web wizard. 
This is due to local security restrictions whereas the web wizard cannot create a database/user through a local unix domain socket.

==== Database for backend use ====

log as root user

`mysql -u root -p`

then execute the following commands to create icingaweb db and director db

===== For icingaweb db ====

{{{
CREATE DATABASE icingaweb2;

CREATE USER icingaweb2@localhost IDENTIFIED BY '##PASSWORD##';

GRANT ALL ON icingaweb2.* TO icingaweb2@localhost;

Flush privileges;

quit
}}}

===== director db =====

{{{
CREATE DATABASE director CHARACTER SET 'utf8';

CREATE USER director@localhost IDENTIFIED BY '##PASSWORD##';

GRANT ALL ON director.* TO director@localhost;

Flush privileges;

quit
}}}

=== enabling reactbundle module ===

Copy following script to a bash flle and execute or execute in the terminal. 

{{{
REACTBUNDLE_MODULE_NAME=reactbundle

REACTBUNDLE_MODULE_VERSION=v0.9.0

REACTBUNDLE_REPO="https://github.com/Icinga/icingaweb2-module-${REACTBUNDLE_MODULE_NAME}"

MODULES_PATH="/usr/share/icingaweb2/modules"

git config --global advice.detachedHead false

git clone ${REACTBUNDLE_REPO} "${MODULES_PATH}/${REACTBUNDLE_MODULE_NAME}" --branch "${REACTBUNDLE_MODULE_VERSION}"

icingacli module enable "${REACTBUNDLE_MODULE_NAME}"
}}}

=== enabling ipl module ===

Copy following script to a bash flle and execute or execute in the terminal. 

{{{
IPL_MODULE_NAME=ipl

IPL_MODULE_VERSION=v0.5.0

IPL_REPO="https://github.com/Icinga/icingaweb2-module-${IPL_MODULE_NAME}"

MODULES_PATH="/usr/share/icingaweb2/modules"

git clone ${IPL_REPO} "${MODULES_PATH}/${IPL_MODULE_NAME}" --branch "${IPL_MODULE_VERSION}"

icingacli module enable "${IPL_MODULE_NAME}"
}}}

=== enabling incubator module ===

Copy following script to a bash flle and execute or execute in the terminal. 

{{{
INCUBATOR_MODULE_NAME=incubator

INCUBATOR_MODULE_VERSION=v0.6.0

INCUBATOR_REPO="https://github.com/Icinga/icingaweb2-module-${INCUBATOR_MODULE_NAME}"

MODULES_PATH="/usr/share/icingaweb2/modules"

git clone ${INCUBATOR_REPO} "${MODULES_PATH}/${INCUBATOR_MODULE_NAME}" --branch "${INCUBATOR_MODULE_VERSION}"

icingacli module enable "${INCUBATOR_MODULE_NAME}"
}}}

=== Enabling Director in Icinga ===

Copy following script to a bash flle and execute. The script with the files to the relevant directory using the script

{{{

ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"

REPO_URL="https://github.com/icinga/icingaweb2-module-director"

TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"

MODULE_VERSION="1.8.0"

git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
}}}

and then enable the icinga-director module 

`icingacli module enable director`

=== enabling business process module ===

Copy following script to a bash flle and execute or execute in the terminal. 

{{{
BS_PROCESS_ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"

BS_PROCESS_REPO_URL="https://github.com/Icinga/icingaweb2-module-businessprocess"

BS_PROCESS_TARGET_DIR="${ICINGAWEB_MODULEPATH}/businessprocess"

git clone "${BS_PROCESS_REPO_URL}" "${BS_PROCESS_TARGET_DIR}"
}}}

`icingacli module enable businessprocess`

=== changing the permission for relevant users ===

`chown -R www-data:icingaweb2 /etc/icingaweb2/`

=== Running a demon for director service ===

`useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /bin/false icingadirector`

`apt install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector`

{{{
MODULE_PATH=/usr/share/icingaweb2/modules/director

cp "${MODULE_PATH}/contrib/systemd/icinga-director.service" /etc/systemd/system/
}}}

`systemctl daemon-reload`

`systemctl enable icinga-director.service`

`systemctl start icinga-director.service`