From 50a45b3c9cb2a105931bf62c08775cab3c220d06 Mon Sep 17 00:00:00 2001 From: Sebastian Harl Date: Thu, 3 Mar 2011 13:15:56 +0100 Subject: [PATCH] Added English translations for QUICKSTART.txt and obsess.README. --- QUICKSTART.de.txt | 2 +- QUICKSTART.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++ obsess.README | 48 +++++++------- obsess.README.de | 53 +++++++++++++++ 4 files changed, 238 insertions(+), 26 deletions(-) create mode 100644 QUICKSTART.txt create mode 100644 obsess.README.de diff --git a/QUICKSTART.de.txt b/QUICKSTART.de.txt index 92d4875..f1e2a7a 100644 --- a/QUICKSTART.de.txt +++ b/QUICKSTART.de.txt @@ -130,7 +130,7 @@ Nag(ix)SC OK - Check results are 25077576 seconds old Nag(ix)SC OK - Wrote checkresult files for 6 services % -./nagixsc_xml2nagios.py -O active -f /tmp/nagixsc.xml -D Disk_Root +% ./nagixsc_xml2nagios.py -O active -f /tmp/nagixsc.xml -D Disk_Root DISK OK - free space: / 2167 MB (22% inode=97%);| /=7353MB;8568;9044;0;9520 % diff --git a/QUICKSTART.txt b/QUICKSTART.txt new file mode 100644 index 0000000..95f5970 --- /dev/null +++ b/QUICKSTART.txt @@ -0,0 +1,161 @@ +=========== +00. Content +=========== + +- 01. On the remote host +- 02. On the Nagios host + + +====================== +01. On the remote host +====================== + +--------------------------- +01.01. Create a "conf" file +--------------------------- + +Disclaimer: +For now, we use a INI-like format. This may change in the future! + +You may use "sample-configs/conf/nagixsc_debian.conf" (Debian setup) or +"sample-configs/conf/nagixsc_usrlocal.conf" (installed from source to +/usr/local/nagios/) as templates. + +One section for each monitored host is required. The section name (in square +brackets) is the Nagios hostname. The section includes service descriptions +and the commands to be executed. + +Option names starting with an underscore are considered Nag(ix)SC-internal +definitions and, thus, are not treated as services. The following internal +options are available: + +- "_host_name": Set the hostname to the one specified, overwriting the section + name. + +The section named "[nagixsc]" is reserved for future extensions! + + +---------------------------------------------- +01.02. Executing checks, Creating the XML file +---------------------------------------------- + +For debugging and testing purposes, create the XML file on the command line: + +% ./nagixsc_conf2xml.py -e plain -c sample-configs/conf/nagixsc.conf + +The switch "-e plain" disables encoding of the data to get human-readable +output. This should not be used in production! + +The output will give a good idea about how Nag(ix)SC works internally. Now, +you should go ahead and create a small custom config file ;-) + +Then, create an XML file suitable for further processing: + +% ./nagixsc_conf2xml.py -c sample-configs/conf/nagixsc.conf -o /tmp/nagixsc.xml + +This XML file may be made published by a web-server to be queried from Nagios. + + +---------------------------- +01.03. Checking the XML file +---------------------------- + +Use "nagixsc_read_xml.py" to dump the content of an Nag(ix)SC XML file: + +% ./nagixsc_read_xml.py -f /tmp/nagixsc.xml + +The content will be displayed as one block for each check or as formatted +Python dictionary. + + +====================== +02. On the Nagios host +====================== + +------------------------------------ +02.01. Transfer of the check results +------------------------------------ + +There are two ways to access the check results: either by making them +available in the filesystem ("-f") or by accessing a web-server ("-u"). In the +examples, we'll use the former approach. + +The tool "nagixsc_xml2nagios.py" supports five different modes of operation, +specified by the "-O" switch: + +- "passive": Submit the results as passive service check to Nagios using the + Nagios command pipe. No output is generated making it suitable + for processing by cron. + +- "passive_check": Submit passive service checks using the output format and + return code of Nagios plugins (one line of output and + appropriate exit code). + +- "checkresult": Dump the results to the Nagios "checkresults" directory. This + is also suitable for cron. + +- "checkresult_check": Same as "checkresult" but behave like a Nagios plugin + (one line of output and appropriate exit code). + +- "active": Look for a host/service tuple in the XML file and behave like a + Nagios plugin. + +Examples: + +% ./nagixsc_xml2nagios.py -O passive -f /tmp/nagixsc.xml +% + +% ./nagixsc_xml2nagios.py -O passive_check -f /tmp/nagixsc.xml +Nag(ix)SC OK - Check results are 25077576 seconds old +% + +% ./nagixsc_xml2nagios.py -O checkresult -f /tmp/nagixsc.xml +% + +% ./nagixsc_xml2nagios.py -O checkresult_check -f /tmp/nagixsc.xml +Nag(ix)SC OK - Wrote checkresult files for 6 services +% + +% ./nagixsc_xml2nagios.py -O active -f /tmp/nagixsc.xml -D Disk_Root +DISK OK - free space: / 2167 MB (22% inode=97%);| /=7353MB;8568;9044;0;9520 +% + +Nag(ix)SC tries to auto-detect the location of "nagios.cmd" and the +"checkresult" directory. If this does not work, you can specify the locations +using the "-p" (pipe) and "-r" (resultdir) options. + +For testing and debugging, create temporary files and have a look at the +generated output: + +% touch /tmp/nagixsc.cmd # or: mkdir /tmp/nagixsc.result +% nagixsc_xm2nagios.py -p /tmp/nagixsc.cmd [...] +# or: nagixsc_xm2nagios.py -r /tmp/nagixsc.result + +-------------------- +02.02. Outdated data +-------------------- + +Data older than four hours (14400 seconds) is considered to be outdated by +"nagixsc_xml2nagios.py" and marked using "Nag(ix)SC: Check result is XX(>1440) +seconds old". This behavior may be customized using the following options: + +- "-s SEC": specify the maximum age after which to consider data outdated + +- "-m": let the check return the status UNKNOWN when encountering outdated + data + +------------------------- +02.03. Further parameters +------------------------- + +- "-S": Verify the XML file using the specified DTD file. Nag(ix)SC ships the + file "xml/nagixsc.dtd" for this purpose (no guarantees whatsoever, + though ;-)) + +- "-H": Filter the XML file for the specified hostname and ignore checks for + different hosts. This may be combined with all variants. + +- "-D": Filter the XML file for the specified (service) description. If + combined with "-H", look for the given host/service tuple. Else, use + the first host specified in the XML file. + diff --git a/obsess.README b/obsess.README index 72c0edf..c54255f 100644 --- a/obsess.README +++ b/obsess.README @@ -7,7 +7,6 @@ obsess_over_hosts=1 ochp_command=ochp2out - commands: ========= @@ -22,32 +21,31 @@ define command { } -Vorteile: -========= +Advantages/benefits: +==================== + +- Do NOT start a shell to analyse the return-code and then format a string + using "printf" as documented in the original documentation. +- Block the Nagios process for a minimum amount of time. The original script + calls "send_nsca" directly, thus blocking Nagios until the NSCA network + packet has been sent (which might include a timeout in case the server is + unreachable). Here, we only write a single spool-file from the shell started + by Nagios. +- Send multiple check results at once. Nagios writes multiple check results + basically at the same time. While NSCA uses one network connection for every + single one of those (which requires a TCP handshake, etc. for each of them), + Nag(ix)SC creates a single XML file from all entries in the spool file. +- A separate, stand-alone process ("obsess_daemon.py") takes care of sending + the XML file. + -- Anders als in der originalen Dokumentation wird NICHT noch eine Shell - gestartet, die die Return-Codes analysiert und dann mit Hilfe von "printf" - den String formatiert. -- Das Original-Skript ruft "send_nsca" direkt auf. Dies wiederum blockiert den - Nagios so lange, bis das NSCA-Netzwerkpaket verschickt werden konnte (Man - bedenke das Timeout, wenn der Server nicht erreicht werden kann). - Das Wegschreiben der Spool-Datei hier macht die von Nagios sowieso geforkte - und gestartete Shell. Die Blockierung des Nagios-Prozess (sollte) ist somit - minimal. -- Nagios schreibt mehrere Check-Ergebniss praktisch auf einmal weg (vgl. - Zeitstempel). NSCA schickt alle Pakete einzeln (für jedes einen - TCP-Handshake...), Nag(ix)SC packt die Ergebnisse aus einem Spool-File in - ein XML und schickt mehrere bis viele Check-Ergebnisse auf einmal los. -- Das Senden der XML-Files passiert unabhängig von Nagios durch einen eigenen - Prozess ("obsess_daemon.py") - - -Hinweis: +Caveats: ======== -- "obsess_daemon.py" ist noch kein richtiger Daemon, einfach an der - Kommandozeile start und gut laufen lassen (Debug-Ausgaben!) -- Zum "auf die Finger guggen": +- "obsess_daeon.py" is not a real daemon yet. Start it in a terminal (and + watch the debugging output). +- Watch what's going on: % cd /tmp/nagixsc.spool - % watch -n2 "cat */*[0-9] |wc -l; (for F in xmlout/*; do ~/src/nagixsc/nagixsc_read_xml.py -f \$F; done)|grep -c RetCode" + % watch -n2 "cat */*[0-9] | wc -l; (for F in xmlout/*; do + ~/src/nagixsc/nagixsc_read_xml.py -f \$F; done) | grep -c RetCode" diff --git a/obsess.README.de b/obsess.README.de new file mode 100644 index 0000000..20fe95c --- /dev/null +++ b/obsess.README.de @@ -0,0 +1,53 @@ +nagios.cfg: +=========== + +obsess_over_services=1 +ocsp_command=ocsp2out +obsess_over_hosts=1 +ochp_command=ochp2out + + + +commands: +========= + +define command { + command_name ocsp2out + command_line echo >>/tmp/nagixsc.spool/new/$TIMET$ LASTSERVICECHECK::$LASTSERVICECHECK$ HOSTNAME::\'$HOSTNAME$\' SERVICEDESC::\'$SERVICEDESC$\' SERVICESTATEID::$SERVICESTATEID$ SERVICEOUTPUT::\'$SERVICEOUTPUT$\' LONGSERVICEOUTPUT::\'$LONGSERVICEOUTPUT$\' +} + +define command { + command_name ochp2out + command_line echo >>/tmp/nagixsc.spool/new/$TIMET$ LASTHOSTCHECK::$LASTHOSTCHECK$ HOSTNAME::\'$HOSTNAME$\' HOSTSTATEID::$HOSTSTATEID$ HOSTOUTPUT::\'$HOSTOUTPUT$\' LONGHOSTOUTPUT::\'$LONGHOSTOUTPUT$\' +} + + +Vorteile: +========= + +- Anders als in der originalen Dokumentation wird NICHT noch eine Shell + gestartet, die die Return-Codes analysiert und dann mit Hilfe von "printf" + den String formatiert. +- Das Original-Skript ruft "send_nsca" direkt auf. Dies wiederum blockiert den + Nagios so lange, bis das NSCA-Netzwerkpaket verschickt werden konnte (man + bedenke das Timeout, wenn der Server nicht erreicht werden kann). + Das Wegschreiben der Spool-Datei hier macht die von Nagios sowieso geforkte + und gestartete Shell. Die Blockierung des Nagios-Prozess (sollte) ist somit + minimal. +- Nagios schreibt mehrere Check-Ergebniss praktisch auf einmal weg (vgl. + Zeitstempel). NSCA schickt alle Pakete einzeln (für jedes einen + TCP-Handshake...), Nag(ix)SC packt die Ergebnisse aus einem Spool-File in + ein XML-Datei und schickt mehrere bis viele Check-Ergebnisse auf einmal los. +- Das Senden der XML-Files passiert unabhängig von Nagios durch einen eigenen + Prozess ("obsess_daemon.py"). + + +Hinweise: +========= + +- "obsess_daemon.py" ist noch kein richtiger Daemon; einfach an der + Kommandozeile starten und laufen lassen (Debug-Ausgaben!) +- Zum "auf die Finger guggen": + % cd /tmp/nagixsc.spool + % watch -n2 "cat */*[0-9] |wc -l; (for F in xmlout/*; do ~/src/nagixsc/nagixsc_read_xml.py -f \$F; done)|grep -c RetCode" + -- 2.30.2