QUICKSTART.txt

   1 ===========
   2 00. Content
   3 ===========
   4
   5 - 01. On the remote host
   6 - 02. On the Nagios host
   7
   8
   9 ======================
  10 01. On the remote host
  11 ======================
  12
  13 ---------------------------
  14 01.01. Create a "conf" file
  15 ---------------------------
  16
  17 Disclaimer:
  18 For now, we use a INI-like format. This may change in the future!
  19
  20 You may use "sample-configs/conf/nagixsc_debian.conf" (Debian setup) or
  21 "sample-configs/conf/nagixsc_usrlocal.conf" (installed from source to
  22 /usr/local/nagios/) as templates.
  23
  24 One section for each monitored host is required. The section name (in square
  25 brackets) is the Nagios hostname. The section includes service descriptions
  26 and the commands to be executed.
  27
  28 Option names starting with an underscore are considered Nag(ix)SC-internal
  29 definitions and, thus, are not treated as services. The following internal
  30 options are available:
  31
  32 - "_host_name": Set the hostname to the one specified, overwriting the section
  33                 name.
  34
  35 The section named "[nagixsc]" is reserved for future extensions!
  36
  37
  38 ----------------------------------------------
  39 01.02. Executing checks, Creating the XML file
  40 ----------------------------------------------
  41
  42 For debugging and testing purposes, create the XML file on the command line:
  43
  44 % ./nagixsc_conf2xml.py -e plain -c sample-configs/conf/nagixsc.conf
  45
  46 The switch "-e plain" disables encoding of the data to get human-readable
  47 output. This should not be used in production!
  48
  49 The output will give a good idea about how Nag(ix)SC works internally. Now,
  50 you should go ahead and create a small custom config file ;-)
  51
  52 Then, create an XML file suitable for further processing:
  53
  54 % ./nagixsc_conf2xml.py -c sample-configs/conf/nagixsc.conf -o /tmp/nagixsc.xml
  55
  56 This XML file may be made published by a web-server to be queried from Nagios.
  57
  58
  59 ----------------------------
  60 01.03. Checking the XML file
  61 ----------------------------
  62
  63 Use "nagixsc_read_xml.py" to dump the content of an Nag(ix)SC XML file:
  64
  65 % ./nagixsc_read_xml.py -f /tmp/nagixsc.xml
  66
  67 The content will be displayed as one block for each check or as formatted
  68 Python dictionary.
  69
  70
  71 ======================
  72 02. On the Nagios host
  73 ======================
  74
  75 ------------------------------------
  76 02.01. Transfer of the check results
  77 ------------------------------------
  78
  79 There are two ways to access the check results: either by making them
  80 available in the filesystem ("-f") or by accessing a web-server ("-u"). In the
  81 examples, we'll use the former approach.
  82
  83 The tool "nagixsc_xml2nagios.py" supports five different modes of operation,
  84 specified by the "-O" switch:
  85
  86 - "passive": Submit the results as passive service check to Nagios using the
  87              Nagios command pipe. No output is generated making it suitable
  88              for processing by cron.
  89
  90 - "passive_check": Submit passive service checks using the output format and
  91                    return code of Nagios plugins (one line of output and
  92                    appropriate exit code).
  93
  94 - "checkresult": Dump the results to the Nagios "checkresults" directory. This
  95                  is also suitable for cron.
  96
  97 - "checkresult_check": Same as "checkresult" but behave like a Nagios plugin
  98                        (one line of output and appropriate exit code).
  99
 100 - "active": Look for a host/service tuple in the XML file and behave like a
 101             Nagios plugin.
 102
 103 Examples:
 104
 105 % ./nagixsc_xml2nagios.py -O passive -f /tmp/nagixsc.xml
 106 %
 107
 108 % ./nagixsc_xml2nagios.py -O passive_check -f /tmp/nagixsc.xml
 109 Nag(ix)SC OK - Check results are 25077576 seconds old
 110 %
 111
 112 % ./nagixsc_xml2nagios.py -O checkresult -f /tmp/nagixsc.xml
 113 %
 114
 115 % ./nagixsc_xml2nagios.py -O checkresult_check -f /tmp/nagixsc.xml
 116 Nag(ix)SC OK - Wrote checkresult files for 6 services
 117 %
 118
 119 % ./nagixsc_xml2nagios.py -O active -f /tmp/nagixsc.xml -D Disk_Root
 120 DISK OK - free space: / 2167 MB (22% inode=97%);| /=7353MB;8568;9044;0;9520
 121 %
 122
 123 Nag(ix)SC tries to auto-detect the location of "nagios.cmd" and the
 124 "checkresult" directory. If this does not work, you can specify the locations
 125 using the "-p" (pipe) and "-r" (resultdir) options.
 126
 127 For testing and debugging, create temporary files and have a look at the
 128 generated output:
 129
 130 % touch /tmp/nagixsc.cmd # or: mkdir /tmp/nagixsc.result
 131 % nagixsc_xm2nagios.py -p /tmp/nagixsc.cmd [...]
 132 # or: nagixsc_xm2nagios.py -r /tmp/nagixsc.result
 133
 134 --------------------
 135 02.02. Outdated data
 136 --------------------
 137
 138 Data older than four hours (14400 seconds) is considered to be outdated by
 139 "nagixsc_xml2nagios.py" and marked using "Nag(ix)SC: Check result is XX(>1440)
 140 seconds old". This behavior may be customized using the following options:
 141
 142 - "-s SEC": specify the maximum age after which to consider data outdated
 143
 144 - "-m": let the check return the status UNKNOWN when encountering outdated
 145         data
 146
 147 -------------------------
 148 02.03. Further parameters
 149 -------------------------
 150
 151 - "-S": Verify the XML file using the specified DTD file. Nag(ix)SC ships the
 152         file "xml/nagixsc.dtd" for this purpose (no guarantees whatsoever,
 153         though ;-))
 154
 155 - "-H": Filter the XML file for the specified hostname and ignore checks for
 156         different hosts. This may be combined with all variants.
 157
 158 - "-D": Filter the XML file for the specified (service) description. If
 159         combined with "-H", look for the given host/service tuple. Else, use
 160         the first host specified in the XML file.
 161