+------------------------------------------------------------------------------+
: 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:
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 Clickatell’s
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: Sender’s name.
E.g. 'LogzMon'.
from_address: Sender’s mailbox address.
E.g.: 'ogzmon@yourhost.com'
to_name: Recipient's name.
to_address: Recipient’s mailbox address.
Subject: E-mail subject.
E.g.: [LogzMon] Alert
SMSCLICK: Format:
'sender|recipient'
sender: Sender identification.
E.g. 'LogzMon Yourhost.com'.
recipient: Recipient’s 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 don’t 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 don’t 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 .