[Summary view] [Print] [Text view]

   1  <?php
   2  include ('header.php');
   3  ?>
   4  
   5  <table>
   6      <tr>
   7          <th id=head>Yamoon Help Page</th>
   8      </tr>
   9      <tr>
  10          <td>
  11              Welcome to Yamoon! This is the help page, if you need more information
  12              about internals of Yamoon please refer to the PHP Doc inside the PEAR
  13              classes on /[pear dir]/Yamoon.
  14          </td>
  15      </tr>
  16      <tr>
  17          <td>&nbsp;</td>
  18      </tr>
  19      <tr>
  20          <th id=toc>
  21              Table of Contents
  22          </th>
  23      </tr>
  24      <tr>
  25          <td>
  26              <li><a href="#intro">Introduction to Yamoon</a>
  27              <li><a href="#company">Creating companies, hosts and probes</a>
  28              <li><a href="#status">Managing status and graphics</a>
  29              <li><a href="#admin">Admninistration: managing services and languages</a>
  30          </td>
  31      </tr>
  32      <tr>
  33          <td>&nbsp;</td>
  34      </tr>
  35      <tr>
  36          <th id=intro>
  37              Introduction to Yamoon
  38          </th>
  39      </tr>
  40      <tr>
  41          <td>
  42              Yamoon is a tool to monitor, log and create nice graphics for services
  43              running on hosts of a specified group. It manages services based on a
  44              language like "shell", "perl", "php" with a code like "ping my.host" and
  45              have regular expressions to get the result of the execution.
  46              <p>
  47              There's also a service running on crontab to run all probes each minute
  48              and update the database. After that you can see the status (last year, 
  49              month and day's) and also create the graphics.
  50              <p>
  51              This tool uses MySQL to store all structured data, logs and current status
  52              of all probes, uses PHP to create the interface and provide the classes
  53              to manipulate data and uses MRTG to generate the nice graphics from a
  54              probe's log.
  55          </td>
  56      </tr>
  57      <tr>
  58          <td align=center><a href="#head">Up</a> - <a href="#toc">Table of Contents</a></td>
  59      </tr>
  60      <tr>
  61          <th id=company>
  62              Creating companies, hosts and probes
  63          </th>
  64      </tr>
  65      <tr>
  66          <td>
  67              Create a company on the main page by choosing it's name and clicking on the
  68              button "Create". Now, you can edit it's name, contact, hosts and probes.
  69              <p>
  70              To change the company name and contact just type it on it's respectives
  71              text fields at the top of the page and click on "Update".
  72              <p>
  73              Editing a company you'll see a list of probes and hosts. To create a host
  74              simply type it's fully qualified name on the first text field on hosts list
  75              and click on "Create Host". The second text field is it's IP but, if the name
  76              is on DNS you can leave it empty that Yamoon will try to find it for you.
  77              <p>
  78              Note that when updating a Host, when you erase it's IP Yamoon will force to
  79              find another IP for it. In other words, Yamoon will try hard to not let a host
  80              without IPs. That's a good feature to reload a host's IP when DNS has changed.
  81              <p>
  82              As soon as you have hosts you can start creating probes for them. On the
  83              probes list select a service and a host and click on "Create Probe". You can
  84              create as many distinct probes as you want.
  85              <p>
  86              You can activate and deactivate probes by editing them and selecting it's
  87              status accordingly and clicking on "Update" button.
  88              <p>
  89              At the edit probe and hosts you can change all parameters but Yamoon will clear
  90              all probe's logs and reload all MRTG configurations for that company if you
  91              change it's service and/or host for obvious reasons.
  92          </td>
  93      </tr>
  94      <tr>
  95          <td align=center><a href="#head">Up</a> - <a href="#toc">Table of Contents</a></td>
  96      </tr>
  97      <tr>
  98          <th id=status>
  99              Managing status and graphics
 100          </th>
 101      </tr>
 102      <tr>
 103          <td>
 104              When you click on a comnay's name at index or click on "View status" link you'll
 105              see all probe's current status. This is the heart of Yamoon. There you can see 
 106              four important columns: Active, which tells if the service is being run or not,
 107              Status, which tells if the service is UP or DOWN, Quality, which show the result
 108              for the "quality" regular expression defined on it's service and Delay, which
 109              shows how many seconds the probe took to run.
 110              <p>
 111              The color of each probe's line is defined by its status. If the probe is UP, its
 112              color is green, otherwise it's red.
 113              <p>
 114              There are two actions to be taken for each probe: Status, which shows you what's
 115              the service level (SLA) for that particular probe on the last day, month and year,
 116              and MRTG, which shows you the three graphics for that probe: status, quality and delay.
 117              <p>
 118              If you click on the MRTG link and there's a 404 error page you must first assure all
 119              company's MRTG configuration are up-to-date by clicking on "Reload graphics config"
 120              link at edit page and than "Reload graphics" on the view page to generate all MRTG
 121              graphics.
 122              <p>
 123              Each probe is set to run once in a minute but you can click on the "Run now" link
 124              to force all probe's execution and see its status based on fresh data.
 125          </td>
 126      </tr>
 127      <tr>
 128          <td align=center><a href="#head">Up</a> - <a href="#toc">Table of Contents</a></td>
 129      </tr>
 130      <tr>
 131          <th id=admin>
 132              Admninistration: managing services and languages
 133          </th>
 134      </tr>
 135      <tr>
 136          <td>
 137              The administration is where you define all properties not related to a specific
 138              company. For now there's only two properties: Languages, which are the command
 139              line binary that will be called to run services scripts and Services, that have
 140              the codes and regular expressions to get the results and qualities.
 141              <p>
 142              Each service is associated with a language so if you need a language for your
 143              service that don't exist yet, create it. To create a language is simple, just
 144              click on the "new" link of the languages' list and enter it's name and binary
 145              path. If you don't provide the binary path, Yamoon will try to find it based
 146              on the command name (like 'perl' or 'bash').
 147              <p>
 148              To create a service you'll need a language ('sh' is the default and set to
 149              "/bin/sh -c"). When you have your prefered language you may write the code
 150              that will test the service on the "code" text area. This script must test the
 151              service and return some success/error code to both Result and Quality regular
 152              expressions parse it.
 153              <p>
 154              When your service is 'network' the code may be something like "ping -c 1 $HOST".
 155              It'll return a lines like this:
 156  <pre>
 157      1 packets transmitted, 1 received, 0% packet loss, time 0ms
 158      rtt min/avg/max/mdev = 0.065/0.065/0.065/0.000 ms
 159  </pre>
 160              The "Result" regular expression should get if the packet was received, so it should
 161              be:
 162  <pre>
 163      1 received
 164  </pre>
 165              This way, if no packet was received, the regex will not match and the status is DOWN
 166              or if it matches, the status is UP.
 167              <p>
 168              For the quality regex it's a little more complicated, your regex should return a value
 169              using parenthesis "(" ")" around the number on the command's response that will 
 170              represent the service's quality. On our case, the regular expression:
 171  <pre>
 172      \s\d{1,3}\.\d{3}\/(\d{1,3}\.\d{3})\/
 173  </pre>
 174              will get the first two numbers on the second line that represents the minimum time
 175              and average time of the ping packet (on our case the same number since there's only
 176              one packet. Note the parentesis around the second number:
 177  <pre>
 178      (\d{1,3}\.\d{3})
 179  </pre>
 180              it'll return that number, which in our case is the average time. This denotes the
 181              quality of the link on network services, the latency of the network between our
 182              local host and the remote host.
 183              <p>
 184              Creating services is not a simple thing and involves several tests before it's fully
 185              functional. The idea is to run it from the console until it's done and then port it
 186              as a Yamoon's service.
 187              <p>Note that Yamoon will run the command line folowed by your code so to run a perl
 188              code you must set the command line path to something like:
 189  <pre>
 190      /usr/bin/perl -e 
 191  </pre>
 192              So, when Yamoon calls the system on [$cmd "$code 2>&amp;1"] it'll execute the perl code correctly.
 193              The same way, PHP must be called as "php -q" to avoid HTTP headers, Bash need the "-c"
 194              option to run the script within double quotes and so on. Discover the best command line 
 195              for your prefered programming language.
 196              <p>
 197              Also note that Yamoon always redirects the stderr (standard error) to the stdout (standard
 198              output) using "2>&amp;1" at the end of the system call so you can also use it to status
 199              and quality regex as well.
 200          </td>
 201      </tr>
 202      <tr>
 203          <td align=center><a href="#head">Up</a> - <a href="#toc">Table of Contents</a></td>
 204      </tr>
 205  </table>
 206  
 207  <?php
 208  include ('footer.php');
 209  ?>