+------------------------------------------------------------------------------+
:                            methodica LogzMon  1.4                            :
:                              Installation Guide                              :
+------------------------------------------------------------------------------+


Index
-----

1. Introduction
2. Contents
3. Installation
4. Configuration
5. Security
6. Legal


1. Introduction
   ------------
   
   LogzMon is as log file viewer and monitor.
   The program lists files found in pre-determined directories on a server
   file system. The contents of these ASCII files and archives (ZIP/GZ)
   may be displayed in detail. Highlighting and hiding of lines can be
   configured.
   Usually these files are log files. In fact, any ASCII text files are 
   processed.
   
   In auto-refresh mode the client periodically sends requests to update
   the content of the choosen file. Also are pre-defined actions issued,
   which include sending messages thru SMTP or SYSLOG protocol, or thru SMS.
   
   A set of server-side PHP scripts, style sheets, templates, and pictures is
   used to generate HTML and JavaScript code run in a browser on the client
   side. Any modern browser should appropriate.
   The client browser and the server-side components communicate using
   AJAX technology. Therefore the browsers must allow for running JavaScript
   and - in the case of Microsoft's Internet Explorer (IE) - their ActiveX
   AJAX component.
   
   Since the files are completely read into a memory array this tool is 
   suited for small and medium size log files, but is possibly not suited 
   for very large files. Where the limit is depends from the memory 
   available on the server where LogzMon is run. To give an idea: when we 
   assume that an average line of a log file has 200 characters a file with 
   40'000 lines would take 8 MBytes to hold in memory.


2. Contents
   --------
   
   root
   +- admin                              [directory]
      +- logviewer                       [directory]
         +- css                          [directory]
            +- standard.css              Style sheet medium size window
            +- standard_large.css        Style sheet large size window
            +- standard_small.css        Style sheet small size window
            +- standard1.css             As above, non-IE browsers
            +- standard1_large.css       As above, non-IE browsers
            +- standard1_small.css       As above, non-IE browsers
         +- help                         [directory]
            +- help_en.htm               Help pages, english
            +- help_en*.htm
            +- help_de.htm               Help pages, german
            +- help_de*.htm
         +- HTML                         [directory]
            +- Template                  [directory], Template modules
               +- IT.php
               +- IT_Error.php
               +- ITX.php
         +- templates                    [directory]
            +- logviewer.htm.tpl         Template for client window
            +- *.png                     Pictures for logviewer.htm.tpl
         +- logviewer.php                Main LogzMon script
         +- logviewer_config.inc.php     Configuration file, sample
         +- logviewer_lang_de.php        German text particles
         +- logviewer_lang_en.php        English text particles
         +- addon_smsclick.php           Add-on to send SMS messages
         +- addon_smtpmail.php           Add-on to send e-Mail messages
         +- addon_syslog.php             Add-on to send SYSLOG messages
         +- scandir.inc.php              Include file for logviewer.php (1)
         +- syslog.php                   Include file for addon_syslog.php (2)
         +- zip.lib.php                  Include file for logviewer.php (2)
         +- index.htm, index.html        Index file redirecting to logviewer.php
         
         (1) This file is required for PHP versions < 5 only.
             We suggest you leave it here anyway.
         (2) These files might be installed already as PHP modules.
             Then you could delete them here.
   
   
3. Installation
   ------------
   
   The program is available in one of these forms:
   - A ZIP file for Windows platforms,
   - A TAR file for UNIX / LINUX platforms,
   - An installer file for Windows platforms.
   
   With either the ZIP or TAR files do...
   - Expand the archive to a directory where you will have access using your
     web server. If you already have directory called "admin" you should expand
     the archive to the parent directory of "admin". All the LogzMon files will
     be stored in /admin/logviewer/ and its sub-directories.
           
   With the Installer file (Windows platforms only) do...
   - Execute the installer program (double click)
   - Follow the instructions and provide the installation parameters such
     as the directory where you wish to install LogzMon.
     
   In both cases do...
   - Edit the configuration file /admin/logviewer/logviewer_config.inc.php to
     meet your installation and needs. (See section 4. Configuration below.)
   - Edit the file /admin/logviewer/index.htm to provide the correct user_name.
     Note: the user_name is used to differentiate among configurations within
     the configuration file.
     The line to edit:
     <meta HTTP-EQUIV=REFRESH CONTENT="0;
           URL=logviewer.php?mode=init&user=user_name">
     If necessary, edit the name extension of this file to match the default
     page name configuration of your web server (e.g. "index.html").

   Now you shold be able to call the program from your browser with a URL 
   similar to this:
     http://www.yourhost.com/admin/logviewer/

   And, finally, edit the addon-files(*) you intend to use:
     - Action type SMSCLICK: "addon_smsclick.php":
       $apiid      = '1234567';   // Clickatell HTTP API id.
       $user       = 'your_user'; // Clickatell account user ID.
       $password   = 'your_pswd'; // Clickatell account password.
       $callback   = '1';         // Callback from Clickatell wanted. 1=YES, 0=No
		                  // If YES, a callback URL must be configured 
		                  // with your Clickatell account.
     - Action type SMTPMAIL: "addon_smtpmail.php":
       $smtpServer = "mail.yourdomain.com";
       $port       = "25";        // modifiy if different
       $timeout    = "30";        // probably no need to modify
       $username   = "your_acct"; // Your mail User-ID. Leave empty if no
       				  // SMPT authentication needed.
       $password   = "your_pswd"; // Password for your mail account
                                  // Irrelevant when $username empty.
     - Action type SYSLOG: "addon_syslog.php":
       $facility   = (isset($params[0]))?$params[0]:23;          // default: local7
       $severity   = (isset($params[1]))?$params[1]:5;           // default: notice
       $hostname   = (isset($params[2]))?$params[2]:'';
       $process    = (isset($params[3]))?$params[3]:'';
       $serverip   = (isset($params[4]))?$params[4]:'127.0.0.1'; // default: locahost
       $serverport = (isset($params[5]))?$params[5]:514;         // default: 514

   (*) The corresponding code sequences in the addon-files are marked like this:
       //  COFIGURATION BEGIN ----------------------------------------
           ...
       //  COFIGURATION END ------------------------------------------
 
 
4. Configuration
   -------------

   The configuration file is stored on the server as logviewer_config.inc.php. 
   It contains PHP code that is executed at runtime. 
   Therefore the configuration follows the PHP syntax rules.

   WARNING:
   The configuration file is included and interpreted at runtime as PHP code.
   Therefore, if the PHP interpreter detects one ore more syntax errors in the 
   configuration file, it usually will not execute the LogzMon main script.
   So, be very careful when editing this file!

   The configuration file sections:
   -	Logfiles,
   -	Logdirs,
   -	Archivedirs,
   -	Filters,
   -	Filtersets,
   -	Actions, and
   -	General purpose constants (defines).

   Different configurations may be combined within the same configuration file 
   by un-commenting the statement 'if ($user==) {  }' and by submitting the 
   parameter user=user_name with the first call of LogzMon
   E.g.: 
   https://www.yourserver.com/admin/logviewer/logviewer.php?user=ADMINISTRATOR.


   Section Logfiles
   ----------------
   
   Purpose:
   A list of filenames (including full paths) to be listed in the index window.

   Syntax:
   $logfiles = array (
   	array ('full_filename','identifier'),
	array (),
	
   );

   Where:
   full_filename	is the name of the log file to show, including the full
                        file path.
                        E.g.:
                           'F:\web\logs\syslog_catchall.txt' or
                           '/var/www/www.yourhost.com/logs/syslog_catchall.txt'
   identifier           is an (optional) identifier to display together with 
                        the file name. This can be helpful if several log files
                        with the same name but from different directories are
                        to be monitored.
                        
   Note: please make sure that the user account under which the web server
         runs has (read) access to the files configured here.


   Section LogDirs
   ---------------

   Purpose:
   A list of directories containing log files to monitor.
   Only log files with file extensions corresponding to the 'logext' constant 
   are listed.

   Syntax:
   $logdirs = array (
	array ('directory_name','identifier'),
	array (..),
	
   );

   Where:
   directory_name       is the directory path of log files to include. 
                        E.g.:
                          'F:\web\www.yourhost.com\logs' or
                          '/var/www/www.yourhost.com/logs'
                        Do not add ending backslashes or slashes.
   identifier           An (optional) identifier to display together with the
                        file names. This can be helpful if several log files 
                        with the same name but from different directories are 
                        to be monitored.

   Note: please make sure that the user account under which the web server
         runs has (read) access to the directories and files configured here.


   Section ArchiveDirs
   -------------------
   
   Purpose:
   List of directories containing log archive files to monitor.
   Only log files with file extensions corresponding to the arcext constant are
   listed.

   Syntax:
   $archivedirs = array (
   	array ('directory_name','identifier'),
   	array (),
   	
   );

   Where:
   directory_name       is the directory path of log files to include. 
                        E.g.:
                           'F:\web\www.yourhost.com\logs\archive' or
                           '/var/www/www.yourhost.com/logs/archive'
                        Do not add ending backslashes or slashes.
   identifier           is an (optional) identifier to display together with 
                        the file names. This can be helpful if several log 
                        files with the same name but from different directories 
                        are to be monitored.

   Note: please make sure that the user account under which the web server
         runs has (read) access to the directories and files configured here.


   Section Filters
   ---------------
   
   Purpose:
   Filters are applied on every line of a log file or archive to determine
   - Highlighting of selected lines,
   - actions to perform when Auto-refresh mode is set to ON.
   Filters are only honored when no Filterset applies.

   Syntax:
   $filters = array (
   	array ('filter_regex','foreground','background','actions'),
   	array (),
   	
   );

   Where:
   filter_regex         is the filter pattern, as a regular expression.
                        Foreground and background parameters are honored if the
                        filter_regex matches the line string.
                        Unix-/ Linux users should be quite accustomed to 
                        regular expressions. Additional information can be 
                        found here:
                        -  http://www.regular-expressions.info
                        -  http://www.amk.ca/python/howto/regex/.
                        -  http://en.wikipedia.org/wiki/Regular_expression
                        Meta characters must be escaped by preceding 
                        backslashes (\) to be taken literally.
                        This is a comprehensive list of the meta characters: 
                           ^ $ * + ? {} [ ] \ | ( )
                        Patterns may be concatenated using the pipe (|) 
                        character.
                        Instead of a pattern, the name of a constant (without 
                        apostrophes) may be given.
   foreground           Either one of:
                         The RGB code of the foreground color, 
                         the keyword 'hide', or 
                         empty string (= no highlighting).
                        If foreground = 'hide' the matching lines are not 
                        displayed at all. Otherwise the matching lines are 
                        displayed with the foreground color specified.
                        RGB color format is: #rrggbb, where 
                         rr = hexadecimal RED value (00..FF),
                         gg = hexadecimal GREEN value (00..FF),
                         bb = hexadecimal BLUE value (00..FF).
   background           Either one of:
                         The RGB code of the background color, 
                         empty string (= no highlighting).
   actions              The name of one or more actions to perform when in 
                        Auto-refresh mode. Action names may be concatenated 
                        using the pipe (|) character.


   Section Filtersets
   ------------------

   Purpose:
   Filters are applied on every line of a log file or archive to determine
   - highlighting of selected lines,
   - actions to perform when Auto-refresh mode is set to ON.
   The filters of a filter set are applied to lines of a file or archive if the 
   filterset_regex matches the file or archive name only.
   Only the filters of the first matching filter set are applied.

   Syntax:
   $filterset = array (
      array ('filterset_regex',
         array ('filter_regex','foreground','background','actions'),
         array (),
      ),
      array ('filterset_regex',
         array ('filter_regex','foreground','background','actions'),
         array (),
      ),
   );

   Where:
   filterset_regex	is the filter pattern, as a regular expression, used
                        to select the files to apply the filter rules upon.
                        Meta characters must be escaped by preceding 
                        backslashes (\) to be taken literally.
                        This is a comprehensive list of the meta characters: 
                           ^ $ * + ? {} [ ] \ | ( )
                        Patterns may be concatenated using the pipe (|) 
                        character.
   filter_regex         Filter rule as described above, see Filters.
   actions              The name of one or more actions to perform when in 
                        Auto-refresh mode. Action names may be concatenated 
                        using the pipe (|) character.


   Actions
   -------
   
   Purpose:
   Actions are performed when the Auto-refresh mode is set to ON, and the 
   corresponding filter_regex (see Filters and Filtersets) matches a line 
   string.
   An action sends a message to an addressee according to one of three action
   types:
   - SYSLOG: Sends a message to a syslog daemon within the intranet or thru the
     internet.
   - SMTPMAIL: Send a message to an e-mail box using an SMTP server,
   - SMSCLICK: Send a short message to a mobile phone using Clickatells 
     service. 
     (Note: You must have an account and a HTTP API number from Clickatell 
     (http://www.clickatell.com) to use this action type.)

   Action types are implemented as add-on modules. So, it would be quite easy 
   to add more types.

   Syntax:
   $actions = array (
      array ('action_name','action_type',
         'action_parameters',
         'message_regex,
         'message_text
      ),
      Array(),
   );

   Where:
   action_name          is a name of your choice to link filters to.
   action_type          is one of the three types SYSLOG, SMTPMAIL, or SMSCLICK
                        as described above.
   action_parameters    are parameters used by the add-on module. They are 
                        different for every module. The parameters are 
                        concatenated using the pipe character (|).

      SYSLOG:           Format:
                        'facility|level|host|process|daemon_ip|daemon_port'
         facility:      Facility code. E.g. 23 (= local 7).
         level:         Log level. E.g.: 5 (= notice).
         host:          Host name or IP.
         process:       Process name.
         daemon_ip:     IP address of the syslog daemon.
         daemon_port:   Port number where the syslog daemon is listening.
         (The SYSLOG add-on always uses the UDP protocol.)
         
         Facilities:    Facility  name  Alternative Name  Value
                        --------------- ----------------- ------------
                        Kernel 	Kern                        0
                        User                                1 
                        Mail                                2 
                        Daemon                              3 
                        Auth                                4 
                        Syslog                              5 
                        Lpr                                 6 
                        News                                7 
                        UUCP                                8 
                        Cron                                9 
                        System0         Security           10 
                        System1         FTP                11 
                        System2         NTP                12 
                        System3         Logaudit           13 
                        System4         Logalert           14 
                        System5         Clock              15 
                        Local0                             16 
                        Local1                             17 
                        Local2                             18 
                        Local3                             19 
                        Local4                             20 
                        Local5                             21 
                        Local6                             22 
                        Local7                             23 
         
         Levels         Level name      Alternative name   Value
                        --------------- ----------------- ------------         
                        Emergency       Emerg               0 
                        Alert                               1 
                        Critical        Crit                2 
                        Error           Err                 3 
                        Warning         Warn                4 
                        Notice                              5 
                        Information     Info                6 
                        Debug                               7 

      SMTPMAIL:         Format:
                        'from_name|from_address|to_name|to_address|subject'
         from_name:     Senders name.
                        E.g. 'LogzMon'.
         from_address:  Senders mailbox address.
                        E.g.: 'ogzmon@yourhost.com'
         to_name:       Recipient's name.
         to_address:    Recipients mailbox address.
         Subject:       E-mail subject.
                        E.g.: [LogzMon] Alert

      SMSCLICK:         Format:
                        'sender|recipient'
         sender:        Sender identification.
                        E.g. 'LogzMon Yourhost.com'.
         recipient:     Recipients mobile phone number.
                        E.g.: +491079999999.
      message_regex:    Regex-pattern to match the line string.
                        E.g.: 
                        '\A([\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}) (.*) 
                           401 401'
                        would match an IP address followed by some text plus 
                        the return codes 401 401. Two text particles, $1 and $2
                        (corresponding to the two expressions in brackets), can
                        be referenced afterwards - $1 being the IP address and 
                        $2 the text between the IP address and the return codes.
	                If you dont need text particles just specify this 
	                parameter as '.*', meaning any text.
                        Meta characters must be escaped by preceding backslashes 
                        (\) to be taken literally.
                        This is a comprehensive list of the meta characters:
                           ^ $ * + ? {} [ ] \ | ( )
                        Patterns may be concatenated using the pipe (|) 
                        character.
      message_text:     Message text, optionally containing text particle 
                        references as $1,$2$n respectively.
                        E.g.:
                        'Access requested to protected area from 
                            IP=$1.\n\n$line'
                        Note: 
                        these standard text particles are always available:
                           - $0:     the entire matching string,
                           - $line:  the entire line string,
                           - $file:  the file name string.

   Section Defines
   ---------------

   Purpose:
   Define constants.
   Most of the defines are mandatory, few optional.

   Syntax:
   Define ('constant_name', 'constant_value');

   Where:
   constant_name is one of these:
      logext            (Current) log file name extensions, delimited by 
                        underlines.
                        Used together with the 'Logdirs' section definitions. 
                        Should files without extension be included you can 
                        write two unerlines (__).
                        E.g.: define('logext', '_log_lg_');
                        Mandatory.
      arcext            Archive file name extensions, delimited by underlines. 
                        Used together with the 'Archivedirs' section 
                        definitions. 
                        Should files without extension be included you can 
                        write two unerlines (__).
                        E.g.: define('arcext', '_gz_'); 
                        Mandatory.
      language          2-digit language code.
                        Currently valid values are: 'en'=English, 'de'=German
                        Mandatory.
      refresh_interval_seconds
                        In Auto-refresh mode, interval between requests to 
                        refresh the file contents in seconds 
                        (e.g. 720 = 12 minutes). 
                        Mandatory.
      refresh_test_milliseonds
                        In Auto-refresh mode, interval for testing the refresh 
                        counter. Minimum interval in milliseconds the refresh-
                        counter is updated.
                        (E.g. 30000 = 1/2 minute).
                        Mandatory.
      size              Client window size preferred.
                        Valid values are: small, medium=standard, large
                        The user may change this value on the client side. 
                        Mandatory.
      host_name         Name of the host you are monitoring with LogzMon. 
                        Mandatory.
      host_name_url     Hyperlink to use when the user clicks on the Host name. 
                        Mandatory.
      SuppressIpLookups If a log or archive file line does contain an IP 
                        address a hyperlink is added to do lookup page to 
                        identify the owner of this IP. You can suppress this 
                        feature by assigning then value true (without quote 
                        characters) to this constant.
                        Mandatory.
      SuppressHttpLookups
                        If a log or archive file line contains an already 
                        resolved hostname instead of an IP address a hyperlink 
                        is added to a lookup page to identify the owner of 
                        this hostname. You can suppress this feature by 
                        assigning then value true (without quote characters) to
                        this constant.
                        Mandatory.
      any other         For use with filter, filtersets, or other configuration
                        definitions of your choice. Make sure you dont use 
                        quote characters when referencing such constants.
                        Optional.


5. Security
   --------
   
   Possibly you are using your web server to process sensitive transations
   and data. Then you should be avare that the information provided by
   LogzMon and potentially transported thru the public internet is equally 
   sensitive.
   
   Please consider one or more of the following measures to secure your 
   LogzMon installation:
   
   - Use the HTTP over SSL (https).
     Install LogzMon in a path where you can access it using the HTTPS 
     protocol, making sure all the data transferred betwenn the server
     and the client are encrypted and worthless for someone snooping
     your connections.
     
   - Enforce user authentication.
     Protect the path where you install LogzMon with at least basic user
     authentication (user-ID and password). If available, use strong
     authentication (user-ID, password, certificate or one-time-password,
     etc.).
     
   - Restrict access to LogzMon to a range of IP addresses you trust.
     You can restrict access to LogzMon by the .htaccess mechanism or
     thru the web server configuration. If possible, configure a separate
     virtual administration server which you could protect stronger than
     you probably would protect public servers.

     
6. Legal
   -----
   
     LogzMon 1.4, Log Viewer and Monitor
     Copyright (C) 2007 methodica, Hans E. Herger
   
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, version 3 of the License.
   
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     The author may UNDER NO CIRCUMSTANCES BE MADE LIABLE FOR ANY 
     CONSEQUENCES OF USING THE PROGRAM. IF THIS WAIVER OF ALL LIABILITY 
     CONTRADICTS THE LAW WHERE YOU INTEND TO USE THE PROGRAM ITS USE IS 
     STRICTLY PROHIBITED.
     See the GNU General Public License for more details.
   
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

