Darstellung des IPS Temperatur-Sensors
Darstellung des IPS Energy-Sensors
Einsatz:
Nutzung der Datenbasis von Symcon mittels Plugin für die verbreitenen Monitoring Frameworks Icinga/Nagios. Diese weit verbreiteten OpenSource Frameworks wurden primär für die Überwachung von Computern und den darauf laufenden Diensten entwickelt. Mittels einfacher Scripte (so genannter Plugins) ist es möglich, Daten zu jedem denkbaren Prozess zu sammeln, auf Fehlerzustände zu untersuchen, mit anderen Daten zu verknüpfen und übersichtlich darzustellen. Damit ist auch der Einsatz solcher professionellen Werkzeuge in der immer mehr wachsenden privaten IT-Landschaft ein interessantes Thema.
Ich beziehe mich hier auf Icinga, da ich es selber einsetze und für die
bessere Alternative halte. Das Plugin-Konzept und die Konfiguration ist bei beiden Frameworks ähnlich.
Ein Plugin-Script gibt an das Framework über den Return Code die Zustände "OK","WARNING","CRITICAL" oder "UNKNOWN"
sowie optional über STDOUT eine Meldung und "Performancedaten" zurück
(siehe Plugin API).
Man kann Prüfungen auf Schwellwerte (für Warnungen oder kritische Zustände) integrieren und damit den zurückgegebenen Zustand definieren.
Der zurückgegebene Zustand ist die Basis für Darstellung im Framework und Notifikationen. Man kann an diese Zustände auch
"Eventhandler" binden,die dann selbstständig Aktionen ausführen können.
Funktion:
Der folgende Text bezieht sich auf die Nutzung der JSON-API, welche ab IPsycon V3.0 verfügbar ist.
Vom Icinga/Nagios Framework wird ein Plugin im Rahmen eines "Checks" in konfigurierbaren Abständen (check_interval) ausgeführt. Zum Auslesen der IPS-Variablen wird dabei eine Verbindung über das Netzwerk zum IPS-Server aufgebaut und Daten über die JSON API ausgetauscht. So ist es möglich, das IPSymcon unter Windows läuft, der Icinga Service aber unter Unix.
Über diese Verbindung wird mittels der ID einer Variable das zugehörige Variablenobjekt abgefragt, welches neben dem eigentlichen Wert auch noch Informationen zum Typ , letzte Aktualisierung und mehr enthält. Mit einem zusätzlichen Zugriff auf den Objektmanager und des Variablenprofiles kann auch der Name der Variable und der Anzeige-Suffix ausgelesen werden. Als Grundgerüst zur Abfrage des IPSymcon-Servers wird dabei eine Klasse (PHP bzw Perlmodul) zur Kapselung der nativen IPSymcon-Befehle mit Hilfe der JSON-API eingesetzt.
Die IPS-Daten müssen noch aufgearbeitet werden.
So werden ein passender Return Code ("UNKNOWN" für Fehler bzw "OK") sowie auf STDOUT das Ergebnis in Textform zurück gegeben.
Für spätere Auswertungen werden die ausgelesenen Werte auch als "Performancedaten" übergeben.
Diese Daten können in eine Datenbank geschrieben werden oder z.B. mit
PNP in Icinga Web visualisiert werden.
Installation und Konfiguration
Auf dem Monitoring Server muss neben der lauffähigen Icinga Installation für PHP-basierte Checks die Json- und Mbstring-Extensions installiert sein.
Die Perl-Scripte benötigen die Standard REST::Client, MIME::Base64 und Json-Module sowie den IPS-Json Wrapper sowie deren Abhängigkeiten.
#Icinga Konfiguration
#icinga.cfg
#add
cfg_dir=/icinga_home/etc/templates
cfg_dir=/icinga_home/etc/servers
#-------------
#resource definition
#-------------
#resource.cfg
#add path to the scripts (etc/ownchecks)
$USER2$=/icinga_home/etc/ownchecks
#define ips host/port and auth to connect
$USER3$=-H ips -P 82 -u apiuser -p apipass
#or use config file IPS_JSON_config.cfg with -c option as below
#-------------
#IPS_JSON_config.cfg for PHP and Perl
#commandline parameter will have precedence over this
#this code will be executed by the calling script, no Tags allowed
$host='ips';
$user="user@ipsymcon.de";
$password="ipsymcon";
$port=3777;
$age=3600;
#--------------
#Command definition
#--------------
#create new file for icinga commands (ips_commands.cfg in etc/templates)
define command {
#special multi variable check
command_name check_ips_temperature
command_line $USER2$/check_ips_temperature_json.pl -c $USER2$/IPS_JSON_config.cfg -H $ARG1$ -t $ARG2$ -f $ARG3$ $ARG4$
}
define command {
#single variable check
command_name check_ips_perl
command_line $USER2$/check_ips_json.pl -c $USER2$/IPS_JSON_config.cfg -H $ARG1$ -i $ARG2$ $ARG3$ $ARG4$
}
#alternativ in with php version
define command {
#single variable check
command_name check_ips_php
command_line $USER2$/check_ips_json.php -c $USER2$/IPS_JSON_config.cfg -H $ARG1$ -i $ARG2$ $ARG3$ $ARG4$
}
#---------------
#Service definition
#---------------
#ips.cfg in etc/servers anlegen und anpassen
define host{
use windows-server ; Inherit default values from a template
host_name ips ; The name we're giving to this server
alias IPS Server ; A longer name for the server
address 192.168.xxx.yyy ; IP address of the server
}
#ips checks
define service {
use generic-service,srv-pnp
host_name ips
service_description Temperatur Terasse
check_command check_ips_temperature!$HOSTADDRESS$!10295!44934!-a 300
notification_interval 0
}
define service {
use generic-service,srv-pnp
host_name ips
service_description Stromverbrauch
check_command check_ips_perl!$HOSTADDRESS!50474!-a 600
notification_interval 0
}
#--------------
Aufruf:./check_ips_json.pl -h ./check_ips_json.pl [-h] | -i <VariableID> [-c <critical level>(absolute)] [-w <warning level>(absolute)] [-f <config_file>]|[-H <IPSHOST> -P <IPS_APIPORT> [-a <maxage in sec > ] [-u <apiuser>] [-p <apipassword>] ./check_ips_json.php -h Usage: check_ips_json.php [-h] -i <Variable ID> [-c <critical level>(absolute)] [-w <warning level>(absolute)] [-f <config_file>|-H <ipshost> -P <port> -u <apiuser> -p <api_password>]z.B. mit IPS_JSON_config.cfg im gleichen Verzeichnis
./check_ips_json.pl -i 43491 OK - HMS_Temperatur_2:-17.7 °C, Age=285s |HMS_Temperatur_2=-17.7;;;;
erweitertes Beispiel
Für eine genauere Steuerung der Abläufe und Rückgabewerte habe ich das Script etwas abgewandelt,um es als Basis für alle Abfragen von IPS-Variablen einsetzen zu können. Hier wird der ausgelesene Wert und das Alter des Wertes über STDOUT an ein übergeordnete Script gegeben. Die Formatierung und endgültige Zustandsbewertung wird dort gemacht. Beispielhaft habe ich meine Konfiguration und Pluginscripte für die Abfrage eines Temperatur/Feuchtesensors sowie eines Energiemessgerätes bereitgestellt. Die Scripte befinden sich im Samples Downloadfile.
Darstellung des IPS Temperatur-Sensors
Darstellung des IPS Energy-Sensors
Weitere Anwendungen der JSON-API
Durch den universellen Charakter der JSON API muss die Anbindung an IPS keine Einbahnstrassse sein. Auch das Ansteuern von Aktoren oder das Ausführen von IPSymcon-Scripten ist möglich. Im Download sind auch dafür Beispiele enthalten.