Inhaltsverzeichnis

Icinga2 - API-Zugriff (Apache)

Icinga2 - API-Zugriff (Apache)

Icinga ist eine vollständig auf Open-Source-Basis basierende, skalierbare und erweiterbare Monitoring-Lösung welche die Verfügbarkeit von definierten Ressource überprüft und über eine Benachrichtigungssystem verfügt.

Beschreibung	Externer Link
Homepage	https://www.icinga.org/
Dokumentation	http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc
Download	http://packages.icinga.org/
API	https://icinga.com/docs/icinga2/latest/doc/12-icinga2-api/

Ab hier werden zur Ausführung nachfolgender Befehle root-Rechte benötigt. Um der Benutzer root zu werden, melden Sie sich bitte als root-Benutzer am System an, oder wechseln mit nachfolgendem Befehl zum Benutzer root:

$ su -
Password:

Voraussetzungen

Für nachfolgende Konfiguration ist es erforderlich, dass eine funktionsfähige Installation von Icinga bereits vorhanden ist. Siehe auch nachfolgende interne Links:

Icinga2
Icinga2 - Grundkonfiguration

Als Voraussetzung für die Nutzung der Icinga2 API sind folgende Komponenten erforderlich:

Lauffähige Version von Icinga 2 ab der API Version 2.6+
- Siehe auch den internen Link Icinga2
Lauffähiger Web-Server z.B. Apache HTTP Server
- Siehe auch den internen Link: Apache HTTP Server CentOS 7

Vorbereitung

Nachfolgend soll eine eigener Benutzer mit einem dazugehörigen Passwort angelegt werden, um auf die Icinga2 API über einen Apache HTTP Server zugreifen zu können.

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

Die Icinga2-API benötigt entweder „basic auth“ oder Client-Zertifikate für die Authentifizierung.

Nachfolgende API-User-Berechtigungen werden entsprechend den Anforderungen festgelegt. Standardmäßig werden nur Daten von den Endpunkten /v1/status und /v1/objects abgerufen.

HINWEIS - Je nach verwendeter Abfrage-Software, z.B.

müssen die Berechtigungen ggf. sehr weitreichend sein !!!

Nachfolgende Ergänzungen in den Konfigurationsdatei /etc/icinga2/conf.d/api-users.conf müssen am Ende der Konfigurationsdatei angehängt werden, damit zur Icinga2-Konfiguration ein neues API-User-Objekt hinzugefügt wird:

(Komplette Konfigurationsdatei)

/**********************************************************************
 * The APIUser objects are used for authentication against the API.   *
 **********************************************************************/
 
object ApiUser "root" {
  password      = "supergeheim"
  // client_cn  = ""
 
  permissions   = [ "*" ]
}
 
object ApiUser "dashing" {
  password = "geheim"
  // client_cn  = ""
 
  permissions = [ "status/query", "objects/query/*" ]
}
 
object ApiUser "apiuser" {
  password      = "auchgeheim"
  // client_cn  = ""
 
  permissions   = [ "*" ]
}

Ergänzungen:

object ApiUser "apiuser" {
  password = "auchgeheim"
  // client_cn  = ""
 
  permissions   = [ "*" ]
}

Hinzufügen eines neuen neues API-User-Objekts zur Icinga2-Konfiguration.

icinga2: Features

Nachfolgend ist sicher zu stellen, dass auch das entsprechende Feature in Icinga2 aktiv (enabled) ist. Nachfolgender Befehl zeigt, wie dies überprüft werden kann:

# icinga2 feature list
Disabled features: debuglog elasticsearch gelf influxdb livestatus opentsdb perfdata
Enabled features: api checker command compatlog graphite ido-mysql mainlog notification statusdata syslog

WICHTIG - Das Feature - api muss bei Enabled features: gelistet sein!

Falls dies nicht der Fall sein sollte, kann dies mit nachfolgendem Befehl nachgeholt werden:

# icinga2 feature enable api

icinga2: Neustart

Danach kann der icinga2-Server mit nachfolgendem Befehle neu gestartet werden:

# systemctl restart icinga2

Mit nachfolgendem Befehl kann der Status des Icinga-Servers abgefragt werden:

# systemctl status icinga2.service
● icinga2.service - Icinga host/service/network monitoring system
   Loaded: loaded (/usr/lib/systemd/system/icinga2.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2016-12-26 10:53:37 CET; 16s ago
  Process: 32190 ExecStart=/usr/sbin/icinga2 daemon -d -e ${ICINGA2_ERROR_LOG} (code=exited, status=0/SUCCESS)
  Process: 32127 ExecStartPre=/usr/lib/icinga2/prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
 Main PID: 32221 (icinga2)
   CGroup: /system.slice/icinga2.service
           ├─32212 /usr/lib64/icinga2/sbin/icinga2 --no-stack-rlimit daemon -...
           └─32221 /usr/lib64/icinga2/sbin/icinga2 --no-stack-rlimit daemon -...

Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:36 server11.idmz.tachtler.net icinga2[32190]: [2016-12-26 10:53:...
Dec 26 10:53:37 server11.idmz.tachtler.net systemd[1]: Started Icinga host/se...
Hint: Some lines were ellipsized, use -l to show in full.

Nachfolgende LOG-Dateien sollten Auskunft darüber geben, wie der Start und der Status des Icinga-Servers ist.

/var/log/icinga2/icinga2.log
/var/log/icinga2/error.log

Die LOG-Datei /var/log/icinga2/error.log sollte hingegen leer sein!

Konfiguration

Nachfolgend die VHOST-Konfiguration für den Apache HTTP Server.

WICHTIG - Nachfolgende Konfigurationen stellen eine grundlegende Apache HTTP Server-VHOST-Konfiguration dar.
Weitere Einzelheiten zu Apache HTTP Server-VHOST sind in der Dokumentation zum Apache HTTP Server verfügbar!

/etc/httpd/conf.d/httpd-vhost.conf

Nachfolgend ein Beispiel für einen Apache HTTP Server-VHOST via https:

#
# VirtualHost HTTPS
#
<VirtualHost *:443>
        ServerAdmin hostmaster@tachtler.net
        ServerName icingaapiaccess.tachtler.net
        ServerPath /
 
        # ----------------------------------------------------------
        # HTTPS settings
        # ----------------------------------------------------------
        SSLEngine on
        SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
        SSLHonorCipherOrder on
        SSLCipherSuite "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:!aNULL:!MD5:!DSS"
        SSLCertificateFile /etc/pki/tls/cert.pem
        SSLCertificateKeyFile /etc/pki/tls/private.pem
        SSLCertificateChainFile /etc/pki/tls/chain.pem
        SSLCACertificateFile /etc/pki/tls/fullchain.pem
 
        # ----------------------------------------------------------
        # Location settings
        # ----------------------------------------------------------
        <Location />
        </Location>
 
        # ----------------------------------------------------------
        # Proxy settings
        # ----------------------------------------------------------
        SSLProxyEngine on
 
        SSLProxyVerify none
        SSLProxyCheckPeerCN off
        SSLProxyCheckPeerName off
        SSLProxyCheckPeerExpire off
        SSLProxyProtocol all -SSLv3 -SSLv2
        ProxyTimeout 1200
 
        ProxyRequests Off
        ProxyPreserveHost On
        ProxyPass / https://localhost:5665/ retry=0 timeout=300 keepalive=on
        ProxyPassReverse / https://localhost:5665/
 
        # ----------------------------------------------------------
        # Logging settings
        # ----------------------------------------------------------
        ErrorLog "logs/error_log"
        CustomLog "logs/access_log" combined
</VirtualHost>

Icinga2: API-Test

WICHTIG - Bei der Konfiguration ist darauf zu achten, dass die Icinga2 API unter nachfolgender URL zu erreichen ist:

https://localhost:5665

Dies kann durch ausführen von nachfolgendem Befehl ausprobiert werden:

# curl -k -s -u apiuser:auchgeheim 'https://localhost:5665/v1'
<html><head><title>Icinga 2</title></head><h1>Hello from Icinga 2 (Version: r2.10.1-1)!</h1><p>
You are authenticated as <b>apiuser</b>. Your user has the following permissions:</p> <ul><li>*</li></ul>
<p>More information about API requests is available in the <a href="https://docs.icinga.com/icinga2/latest"
target="_blank">documentation</a>.</p></html>

Apache: Neustart

Nach Durchführung der vorhergehenden Konfigurationsschritte, sollte einem Neustart nichts im Wege stehen und die Apache VHOST-Konfiguration angezogen werden:

# systemctl restart httpd.service

HINWEIS - Es erfolgen keine weiteren Ausgaben, wenn der Start erfolgreich war !

Apache: API-Abfrage

Nun sollte die Icinga2 API unter nachfolgender URL zu erreichen ist:

https://icingaapiaccess.tachtler.net/v1

Dies kann durch ausführen von nachfolgendem Befehl ausprobiert werden:

# curl -k -s -u apiuser:auchgeheim 'https://icingaapiaccess.tachtler.net/v1'
<html><head><title>Icinga 2</title></head><h1>Hello from Icinga 2 (Version: r2.10.1-1)!</h1><p>
You are authenticated as <b>apiuser</b>. Your user has the following permissions:</p> <ul><li>*</li></ul>
<p>More information about API requests is available in the <a href="https://docs.icinga.com/icinga2/latest"
target="_blank">documentation</a>.</p></html>