Added English translations for QUICKSTART.txt and obsess.README.

diff --git a/QUICKSTART.de.txt b/QUICKSTART.de.txt
index 92d4875935e8ca0ef1827b01381accb668746f9c..f1e2a7a0260b0514f53da3b1cc5f3edaf3e47c6b 100644 (file)
--- 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 (file)
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 72c0edf852145ae78c90e47e9e5810d9d642f75e..c54255fe0ad1e39566b9f15307b77b114383a077 100644 (file)
--- 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 (file)
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"
+