    Websmon -- Web-based system performance monitor, version 1.02.
    Copyright (C) 2003-2006 Dmitry Lapenkov. All rights reserved.


    Websmon Monitor. Installation notes.
    ====================================


Before the installation, please look at the general description of
Websmon Monitor in the file readme.txt.

For technical information, please refer to the file websmon.htm.

Also, feel free to visit the Web site at http://www.websmon.com.
You will find there the numerous samples of the statistics Web pages
created by the monitor.


  1. Operating system requirements
  2. Disk space requirements
  3. Installation of the monitor
  4. Setting up the Apache HTTP server's configuration file httpd.conf
  5. Accounts for the user websmon on remote UNIX servers
  6. Setting up the monitor's configuration file websmon.ini
  7. Setting up the crontab file for the user websmon
  8. License information
  9. Starting up the monitor


1. Operating system requirements

Currently, Websmon can be used as a performance monitor for UNIX/Linux servers
running one of the following operating systems:

  - Red Hat Linux 7, 8, 9
  - Red Hat Enterprise Linux AS release 3
  - Fedora Core release 1, 2, 3, 4
  - SuSE Linux 9
  - SuSE Linux Enterprise Server 9, 10
  - Sun Solaris 8, 9, 10
  - SCO UnixWare 7

and for PROGRESS V8.3, V9, and V10 databases running in the client-server mode
on any operating system having the support for TCP connections enabled,
e.g., UNIX or MS Windows (for collecting statistics of the PROGRESS database
resources usage, the PROGRESS V9 or V10 client software needs to be installed
on the statistics server).

The Websmon Monitor version 1.02 can be running on the following
operating systems:

  - Red Hat Linux 9 (Intel)
  - Red Hat Enterprise Linux AS release 3 (Intel)
  - Fedora Core release 1 (Intel)
  - Fedora Core release 2 (Intel)
  - Fedora Core release 3 (Intel)
  - Fedora Core release 4 (Intel)
  - SuSE Linux Professional 9 (Intel)
  - SuSE Linux Enterprise Server 9 (Intel)
  - SuSE Linux Enterprise Server 10 (Intel)
  - Sun Solaris 8 (SPARC)
  - Sun Solaris 9 (SPARC)
  - Sun Solaris 10 (SPARC)
  - SCO UnixWare 7.1 (Intel)


2. Disk space requirements

For installation, you need at least 125MB of disk space in the monitor's
working directory of the statistics server (by default, it's /home/websmon).

For further work, the monitor will need at most X MB of disk space per year,
where X is:

      X = 20 * N_servers + 34 * N_dbservers

or, with automatic archiving of the collected statistics data turned on:

      X = 7 * N_servers + 12 * N_dbservers

Here N_servers is the number of UNIX servers, and N_dbservers is the number
of PROGRESS databases to monitor.


3. Installation of the monitor

   WARNING:

      The author of this software which is hereinafter
             referred to as "Websmon Monitor"
               CAN NOT BE HELD RESPONSIBLE
       for ANY possible consequences of installation
      and/or subsequent use or misuse of the software.


To install the Websmon Monitor software, you need to log in to the UNIX server
under the root account (or you can use the sudo command):

      su root

First, mount the distributive CD-ROM (e.g., on /mnt) and run
the installation script:

      sh /mnt/install.sh

Alternatively, you can copy the distributive files appropriate to the
operating system of a statistics server to a temporary directory (e.g.,
to /tmp) and perform the installation of the monitor from this directory:

      cp /mnt/* /tmp         # files that are common for all OS
      cp /mnt/linux/* /tmp   # files specific for Red Hat Linux / SuSE Linux
      sh /tmp/install.sh

The installation script will determine the name of the server (the host name)
and the type of the operating system, then you will be prompted for
the start of the installation.

Enter YES (or press ENTER) to continue, or NO to cancel the installation and
to exit to the operating system.

Next, the installation script will create the group "websmon", the account
and the home directory for the user "websmon" as needed.

Then you will be asked for a new password for this user.

After that, the script will be installing the monitor's files to the home
directory specified (i.e., /home/websmon).

After that, the certain definitions of shell variables taken from
/home/websmon/misc/profile will be added to the file /home/websmon/.profile,
the owner of /home/websmon will be set to the  value of websmon:websmon:

      chown -R websmon:websmon /home/websmon

and the access permissions will be changed for /home/websmon:

      chmod 770 /home/websmon

Then, the script will create several symlinks in the /usr/lib directory
for the certain library files from /home/websmon/lib: libperl, libgd,
libpng, libz, linjpeg.

These symlinks will be created only if they are required to properly
run the monitor.

Next, you will need to specify a port number (i.e., a HTTP service)
for the Apache Web server (port 8080 is recommended).

Please check in advance if the port selected is free in your system;
you can use any port for the monitor (e.g., the usual HTTP port 80),
but for a port with number less than 1023 the HTTP server should be
started by the super-user (i.e. root).

Next, the installation scripts will ask you if the Apache HTTP server
should be started up and shut down automatically by calling the
boot-stage shell scripts from the directories /etc/rcN.d.

If your answer is positive (which is recommended), the symlinks to the
control script /home/websmon/bin/wmhttpd in the above mentioned
directories will be created.

After that, you will be opted to start the Web server.

Finally, the monitor's configuration file /home/websmon/websmon.ini
will be set up by running the wmsetup program (see Chapter 6),
then the crontab file for the user websmon (see Chapter 7) will be
created and you will be promted to edit this crontab file.
After that, the installation of Websmon Monitor is finished.

In the end, you might want to check if the Apache HTTP server is
working. For this, go to Chapter 9.


4. Setting up the Apache HTTP server's configuration file httpd.conf

If you don't want to use the dedicated Apache HTTP server and prefer
to run an existed (system-wide) Apache Web server, you will need to edit
its configuration file httpd.conf accordingly.

To do so, append the content of /home/websmon/misc/apache.conf to the
Apache configuration file (e.g., to /usr/local/apache/conf/httpd.conf):

      cat /home/websmon/misc/apache.conf >>/usr/local/apache/conf/httpd.conf

After this, you need to check the new configuration:

      /usr/local/apache/bin/apachectl configtest

and then you have to restart the Apache HTTP server:

      /usr/local/apache/bin/apachectl restart


5. Accounts for the user websmon on remote UNIX servers

On every remote UNIX server to monitor, you need to create an account
for the user websmon. For instance, you can use the following command:

      /usr/sbin/useradd -d /home/websmon websmon

Also, you need to provide access to the mentioned remote UNIX
servers (via ssh or rsh protocols) for the user websmon without giving
the password.


6. Setting up the monitor's configuration file websmon.ini

The Websmon Monitor configuration file websmon.ini contains the list of
hosts, TCP services, and PROGRESS databases to monitor.
This file is used by all three systems of the monitor: wmgather, wmshow,
and wmwatch.

The default configuration file will be looked for in the following places
(note the order):

  - $WEBSMON_INI
  - $WEBSMON/websmon.ini
  - /home/websmon/websmon.ini
  - /etc/websmon.ini

Only the first configuration file found will be used for the monitor.

The configuration file consists of a number of section with the section
names in square brackets.

Each regular section name represents either a host name or a PROGRESS
database service name. For instance, the section name [saturn] defines
a host with the name saturn, and the section name [saturn:bisquit]
represents a PROGRESS database server running on the host saturn
through the TCP service bisquit (which name of course should be
defined in the /etc/service file). Note the colon character (:) that
separates the host name and the service name.

Instead of TCP service names, one can use the corresponding port numbers.
For instance, if the service bisquit stands for the port 55000/tcp, the
section name above might look like [saturn:55000].

Every definition for a host or a database should reside in the
separate section, and the definitions for the database services
running on a certain host should appear in the configuration file
after the definition for the host itself.

Every section can contain one or more section parameters in the form of

      name = value

(the single-line value), or

      name = <<EOT
        value1
        value2
        ......
EOT

(the multi-line value).

Section ends at the beginning of a new section or at the end of the
configuration file.

The leading whitespaces as well as the blank and comment lines are ignored
(a comment line starts with the hash character (#) at the beginning of
a line).

Beside the regular sections, the configuration file websmon.ini has
several special sections containing the important monitor settings.
The names of these special sections begin with and end in a colon
character (:).

Among these, the sections [:default:] and [:license:] should be
described especially.

The section [:default:] contains the default values of all parameters
for the hosts and PROGRESS databases listed in the configuration file.

This mechanism allows you to omit most if not all of these numerous
parameters when adding a new section.

Another section named [:license:] contains the license information for
the monitor: license registration codes (parameter RegCode), serial number
of the license (parameter S/N), max number of UNIX servers allowed to be
monitored (MaxUnixSrv) and max number of PROGRESS databases allowed to be
monitored (MaxProgSrv).

To set up the Websmon Monitor configuration file, you can start with replacing
the license information, then you have to add the definitions for the
hosts and PROGRESS databases you are planning to monitor or to watch for.

The following parameters are mandatory:

  - For a host definition, these are the host name (i.e., the section
    name [hostname]) and the type of operating system (parameter "ostype");
  - For a PROGRESS database, these are the host name and database
    service (i.e., the section name [hostname:service]).

All other parameters are optional and if omitted they will be taken
from the section [:default:].

Please note that the statistics of usage of the UNIX server resources
will be collected only for the hosts with the parameter "ostype" set to
one of the values "unixware", "solaris", or "linux" and with the parameter
"active" set to "yes" or "1".

For the PROGRESS database, the statistics is collected if the parameter
"dbactive" defined for this database is set to "yes" or "1".

The complete list of all parameters allowed in the configuration file
websmon.ini along with their detailed description you can find in the
file websmon.txt.

To facilitate the process of setting up the configuration file websmon.ini,
one can use the following interactive program:

      /home/websmon/bin/wmsetup

or, for the configuration file config_file.ini

      /home/websmon/bin/wmsetup config_file.ini


7. Setting up the user websmon's crontab file

To automate the process of collecting the statistics, the crontab file
for the user websmon should be created.
Its prototype can be found in the file /home/websmon/misc/crontab.

You can change the frequency of collecting the statistics and/or
checking the availability of hosts, TCP services, and PROGRESS databases
listed in the configuration file websmon.ini by editing the crontab file:

      su root -c "crontab -e -u websmon"

The statistics of the resources's usage of UNIX servers and PROGRESS
databases are callected (by default, every 5 minutes) by shell script

      /home/websmon/bin/websmon

The availability of hosts, TCP services and PROGRESS databases is checked
(by default, every one minute) by the command

      /home/websmon/bin/wmwatch

Primary statistics stored in CSV data files and the monitor's log file
websmon.log is archived by default once a month by shell script

      /home/websmon/bin/wmzip


8. License information

The trial 30-day license for the monitor can be obtained free of charge.
You just need to send an e-mail at the following address:

      websmon@websmon.com

To obtain a new permanent license or to renew the existing license for
the monitor, use the address above. Please also specify your system ID
and the existing Websmon Monitor license information, if applicable.

You can get the unique ID of your system by running the following command:

      /home/websmon/bin/wmsysid

To change the license information, edit the section [:license:] of
the configuration file websmon.ini. Or you can use the program

      /home/websmon/bin/wmsetup -license

Note: The permanent license for the monitor depends on the network hardware
configuration of the UNIX server the monitor is running on.
So you might need to update the license after every change of yor network
configuration.  Of course in this case a new license will be provided
for you free of charge.


9. Starting up the monitor

The monitor's system wmgather that is responsible for collecting the
system statistics from UNIX servers and PROGRESS databases is started
up automatically once you have set up the Websmon Monitor configuration
file websmon.ini and the crontab file for the user websmon.
Please note the order - the configuration file has to be set up first.

The user websmon has to be permitted to use the cron daemon so you might need
to check the configuration files of the cron daemon cron.allow and cron.deny.

To run the Web application wmshow, you need to start up the Apache HTTP server
in the first place.

To run the dedicated Apache server which is installed along with the monitor,
you can use the command (or actually the shell script)

      /home/websmon/bin/wmhttpd start

To check the proper operation of the Apache Web server you have started,
go to the server's test page:

      http://HOSTNAME:PORT

Here HOSTNAME is the name of the UNIX server where the monitor is installed
and the Web server is running, and PORT is the port number
(i.e. HTTP service) used by the Apache Web server.

The host name can be shown by calling the command

      /bin/hostname

By default, the port number used for the monitor is set to 8080.
The port number can be changed, see the file
/home/websmon/apache/conf/httpd.conf, parameter Port.

The main (start) Web page created by the wmshow Web application can be
accessed at the following address:

      http://HOSTNAME:PORT/websmon

Note: the system statistics collected by the monitor can be viewed
through the wmshow application after two full cycles of gathering are
completed (i.e., after 2 * 5 = 10 minutes of work of the monitor).



  ------------------------------------------------------------
  PROGRESS is a trademark of the Progress Software Corporation



