Installing Icinga TOTP on Debian

The recommended way to install Icinga TOTP is to use prebuilt packages from our official release repository. If the repository is not configured yet, please add it first before installing the package.

All packages we provide are signed with the following key.

Adding Icinga Package Repository

Add our GPG Key:

apt update
apt -y install apt-transport-https wget

wget -O icinga-archive-keyring.deb "https://packages.icinga.com/icinga-archive-keyring_latest+debian$(
 . /etc/os-release; echo "$VERSION_ID"
).deb"

apt install ./icinga-archive-keyring.deb

Add the Repository:

DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
 echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-${DIST} main" > \
 /etc/apt/sources.list.d/${DIST}-icinga.list
 echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-${DIST} main" >> \
 /etc/apt/sources.list.d/${DIST}-icinga.list

apt update

Installing the Package

Use your distribution’s package manager to install the icinga-totp-web package as follows:

apt install icinga-totp-web

Setting up the Database

A MySQL or PostgreSQL database is required to store TOTP secrets. Please follow the steps listed for your target database.

Setting up a MySQL Database

Set up a MySQL database for Icinga TOTP Web:

# mysql -u root -p

CREATE DATABASE totp;
CREATE USER 'totp'@'localhost' IDENTIFIED BY 'CHANGEME';
GRANT ALL ON totp.* TO 'totp'@'localhost';

Import the schema:

mysql -u totp -p totp < /usr/share/icingaweb2/modules/totp/schema/mysql/schema.sql

Setting up a PostgreSQL Database

Allow authenticated local sessions for the totp database user by modifying the pg_hba.conf file. Its location is operating-system specific, but can be queried:

su postgres -c "psql -c 'show hba_file;'"

Add the following entries before any broader matching rules:

local totp totp              scram-sha-256
host  totp totp 127.0.0.1/32 scram-sha-256
host  totp totp      ::1/128 scram-sha-256

Use md5 instead of scram-sha-256 only with PostgreSQL versions older than 10.

For a remote database server, make sure PostgreSQL listens on an address reachable from Icinga Web. Then add host entries before any broader matching rules, only for the Icinga Web server addresses or subnets that should connect to PostgreSQL. For example, if Icinga Web connects from 192.0.2.43:

host  totp totp 192.0.2.43/32 scram-sha-256

To apply the changes, reload PostgreSQL:

systemctl reload postgresql

Now proceed with actually creating both user and database.

The example below uses the en_US.UTF-8 locale. This locale must be available on the PostgreSQL server. Use locale -a to list available locale names and replace en_US.UTF-8 with the exact UTF-8 locale name on your system, such as en_US.utf8.

# su -l postgres

createuser -P totp
createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O totp totp

Import the schema:

psql -U totp totp < /usr/share/icingaweb2/modules/totp/schema/pgsql/schema.sql

Enabling the Module

Enable the module using the icingacli:

icingacli module enable totp

This concludes the installation. Now proceed with the configuration.