+------------------------------------------------------------------------------+
| NAGIOS LOOKING GLASS - README                                                |
|------------------------------------------------------------------------------|
| Author:           Andy Shellam <andy@networkmail.eu>                         |
| Last Updated:     4th August 2008                                            |
+------------------------------------------------------------------------------+


+------------------------------------------------------------------------------+

    1.  What is Nagios Looking Glass?
    2.  NLG's Architecture Model
    3.  System Requirements
    4.  Templating System
    5.  Automatic Update Notification
    6.  How to get support/suggest new features for NLG
    7.  TRANSLATORS REQUIRED!! - can you help?
    8.  Support contracts / corporate donations

+------------------------------------------------------------------------------+
- What is Nagios Looking Glass? -
+------------------------------------------------------------------------------+

Speak to network administrators who run Nagios, and you'll soon come across a
common problem - how to provide up-to-the-minute status information from Nagios
to the general public (or a specific set of users), without giving them access
to the Nagios front-end (CGIs), as this can seem over-complicated and a possible
security risk.

Nagios Looking Glass (NLG) can be run on a public webserver, and take its feed
from a separate Nagios server - so the general public will never know the Nagios
server even exists!  It also means you don't have to expose your Nagios server
to the public in your company's DMZ.

If, however, you don't have the luxury of a separate Nagios and web server, NLG
will run perfectly happily on the same machine.

As of 1.0.2, NLG runs happily with upwards of 600 hosts and 6000 services.

+------------------------------------------------------------------------------+
- NLG's Architecture Model -
+------------------------------------------------------------------------------+

NLG was created as a client/server model, with the server-side processing the
status feeds from Nagios (s3_poller.php) and sending the data back to the client
(s3_client.php.)  The client then renders an AJAX-enabled web-page with the
relevant data.

The client-side caches the data on a per-filter/per-group combination to improve 
performance on repeated hits of the same data.  The cache time can be altered
within the configuration.

+------------------------------------------------------------------------------+
- System Requirements -
+------------------------------------------------------------------------------+

On the Nagios server (s3_poller)

  - Nagios 2.x or 3.x series (tested with 2.4 - 2.9, and 3.0)
  - Apache 2.x series (tested with 2.2 series)
  - PHP 5 (tested with PHP 5.1.6 through 5.2.6)
  - Up to 5MB disk space
  - 48MB RAM for 600 hosts and upwards
  - memory_limit set to 32-64MB dependent on the number of hosts/services

On the public-side Web server (s3_client)

  - Apache 2.x series (tested with 2.2 series)
  - PHP 5 (tested with PHP 5.1.6 through 5.2.6)
  - allow_url_fopen enabled in PHP (with HTTP handler enabled)
  - If need to access s3_poller.php via HTTPS, need OpenSSL compiled into PHP
    with HTTPS handler enabled
  - 1MB disk space (plus approx. 100Kb per cache object for 600 hosts/6000 
    services)
  - Dig client tools (able to `dig version.nagioslookingglass.co.uk TXT`)

On user's client machines

  - Firefox (tested with 1.5, 2.0 and 3.0)
  - Internet Explorer (tested with IE 6 and 7)
  - Safari (tested on Mac OSX)
  - JavaScript enabled
  - 16-bit colour
  - 800x600 resolution (ideally 1024x768 or higher)

+------------------------------------------------------------------------------+
- Templating System -
+------------------------------------------------------------------------------+

NLG uses an extensive, flexible templating system that allows you to create a 
complete custom application for your company with nothing more than HTML and JS
knowledge, and utilising the power of the code behind NLG.  This section details
the template components that are required, and the variables you can use to
create your own template.

You can even give your users the option to change templates on-the-fly.

How the templating system validates/finds a template:

NLG first builds a list of all templates that are available on your system - it
does this by finding all directories held within the "templates" subfolder of
the client folder.

It then checks that each template has the following files (as these are the
minimum required to build a template):

  - <template>.css.tpl    - eg. for the default template - default.css.tpl
  - <template>.tpl        - eg. for the default template - default.tpl
  - feed_info.tpl
  - filter_chooser.tpl
  - network_status.tpl
  - server_detail.tpl
  - server_pager.tpl
  - server_summary.tpl
  - server_summary_no_result.tpl
  - template_chooser.tpl
  - update_available.tpl
  - user.js

If you request, for example www.yourserver.com/s3_client.php?template=<template>
NLG will try to find <template> in the template list.  If the specified template
could not be found, or was not validated, the 'default' template will be shown
instead.

If there is a problem with the 'default' template, an error will be generated
and NLG will not run.

Each of the above template files create a different part of the final template.
These are described below:

  <template>.tpl
      This is the core page layout template, including all style-sheet links
  <template>.css.tpl
      This is the core CSS style-sheet - additional stylesheets can be added
      using standard <link rel="stylesheet" type="text/css" href="<file>.css" />
      HTML syntax in <template>.tpl
  filter_chooser.tpl
      This is used to create the 'server filter' selector
  feed_info.tpl
      This tells the user whether the feed is using cached data, or live data
      from the Nagios server
  network_status.tpl
      This creates the front-page/network-status page (left-hand side)
  server_detail.tpl
      This creates the server status page for a specific server (left-hand side)
  server_pager.tpl
      This creates the 'server pager' selector
  server_summary.tpl
      This creates the server summary list on the right-hand side of the screen
  server_summary_no_result.tpl
      This creates the server summary on the right-hand side of the screen when
      the user has selected a filter that doesn't return any servers
  template_chooser.tpl
      This creates the 'change template' selector (not present in 'default')
  update_available.tpl
      The contents of this template are included in <template>.tpl when an
      update is available and the address has the "checkupdate=yes" parameter
  user.js
      Additional javascript functions customised to the template can be entered
      in this file
      
Please see the administration manual for a full list of variables you can use.

+------------------------------------------------------------------------------+
- Automatic Update Notification -
+------------------------------------------------------------------------------+

The system administrator can now check for an update to NLG by simply going to 
s3_client.php?checkupdate=yes.  If an update is available, you'll be notified by 
a yellow bar at the top of the application, with a link to download it.

If you set the relevant config option, you can always be notified of an update
on-screen rather than having to go to s3_client.php?checkupdate=yes.

Technical Details:

When the checkupdate=yes parameter is passed to s3_client.php, the application
looks up the DNS TXT record for version.nagioslookingglass.co.uk by using a shell
call to "dig version.looking-glass.andyshellam.eu TXT", so you must have dig 
installed on the web front-end machine to use this functionality.

The string returned from the DNS lookup will be of the form - "1.0.0/S3".
If this does not match NLG_VERSION, the update notification will be shown.

+------------------------------------------------------------------------------+
- How to get support/suggest new features for NLG -                      
+------------------------------------------------------------------------------+

For general 'how do I do this?' queries, I advise you to ask on the nagios-users
mailing list (http://lists.sourceforge.net/mailman/listinfo/nagios-users.)

Network Mail are in the process of creating an online forum and an NLG-specific
mailing list, so please watch www.nagioslookingglass.co.uk for more information.

+------------------------------------------------------------------------------+
- TRANSLATORS REQUIRED!! - can you help? -
+------------------------------------------------------------------------------+

To support multi-language installations, we need people who can translate the
core 'en' language file into other languages.

If you can help, please edit "server/sync-files/s3_lang_en.inc.php" with your
translation and save as "server/sync-files/s3_lang_<2-DIGIT-COUNTRY-ID>.inc.php"

Parts of the template may also need translating.  Future versions of NLG will
automatically include the relevant template based on language selection, but this
has not yet been implemented.

Send the file back to myself, andy.shellam@mailnetwork.co.uk, and I'll include
it in the next release.

+------------------------------------------------------------------------------+
- Commercial services for Nagios Looking Glass -
+------------------------------------------------------------------------------+

Managed hosting, support contracts and custom template designing for Nagios
Looking Glass are available.  Please e-mail sales@networkmail.eu for more info.

Corporations can also benefit from the project by donating to show their thanks,
or by sponsoring a forthcoming development.  In return we will advertise on the
donor heavily on the website and mailing lists when they become available.

Online sponsorship forms will be available within the next 6 months - in the
meantime if you're interested, please contact sales@networkmail.eu.
