# Websmon Monitor - Technical information
Websmon 1.01 -- Web-based system performance monitor for UNIX servers and PROGRESS databases
Keywords: websmon, system monitor, websmon monitor, performance monitor, unix, linux, system statistics, server statistics, progress, database statistics

|  | Websmon -- Web-based system performance monitor. Copyright © 2003-2005 Dmitry Lapenkov. All rights reserved. | [ Read in Russian ]

## Websmon Monitor. Technical information.

Before you go, please read the general description of the Websmon monitor that you can find in the file Readme.

The installation notes can be found in the file Install.

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.

Websmon, or Web-based system performance monitor, is a perfomance monitoring and management system for local and remote UNIX servers and PROGRESS databases.

Shortly, the monitor consists of three independent systems which are as follows:

- wmgather - a system which collects the performance statistics from the UNIX servers and PROGRESS databases specified in the configuration file. The gathered information is then stored in the CSV data files and in the RRD databases (on the Round Robin Database format, read in the file /home/websmon/rrdtool/doc/rrdtutorial.txt).
- wmshow - a system makes the graphical representation of the statistics collected by wmgather. It also shows the actual status of the hosts, TCP services and PROGRESS databases specified. Currently, this is a Web application running on top of the Apache Web server.
- wmwatch - a system which monitors the activity of the hosts, TCP services and PROGRESS databases specified and sends an alert to a system administrator in case when above mentioned servers or services become inactive.

1. Websmon monitor directories structure.
2. wmshow - A system for graphical representation of the performance statistics gathered by the monitor.
   1. Main (top) web page created by the monitor.
   2. Web pages containing performance statistics of the UNIX servers.
   3. Web pages containing performance statistics of the PROGRESS databases.
   4. Web pages containing system statistics of the UNIX server resources.
   5. Web pages containing system statistics of the PROGRESS database resources.
3. Utilities and scripts of the monitor.
   1. websmon - A wrapper shell script for collecting system performance statistics.
   2. wmbar - A helper CGI program for the wmshow system.
   3. wmdbrrd - A utility program for storing PROGRESS database-related statistics in the RRD files.
   4. wmexport - A shell script for exporting CSV statistic files.
   5. wmgather - A program for collecting system statistics serially.
   6. wmgather2 - A program for collecting system statistics in the parallelized mode.
   7. wmhttpd - A control shell script for the Apache HTTP server.
   8. wmimport - A shell script for importing CSV statistic files.
   9. wmmkrrd - A utility program for rebuilding RRD files from a CSV statistic file.
   10. wmsetup - A program to help set up the monitor configuration file.
   11. wmsysid - A utility program for showing the unique system ID of a UNIX server.
   12. wmwatch - A program for monitoring activity of the hosts, TCP services and PROGRESS databases.
   13. wmzip - A shell script for archiving old CSV statistic files having created by the monitor.
4. The monitor configuration file websmon.ini.
   1. Where the configuration file resides.
   2. Several examples of the configuration file's sections.
   3. Section [:default:] - Default values of the monitor configuration parameters.
   4. Section [:system:] - System-wide settings of the monitor.
   5. Section [:graph:] - Settings of the graphs created by the wmshow system.
   6. Section [:bar:] - Settings of the graphic bars created by the wmshow system.
   7. Section [:license:] - License information of the monitor.
   8. A sample monitor configuration file.
   9. How to add a definition for a new host.
   10. How to add a definition for a new PROGRESS database.
5. Description of statistic data files being created by the monitor.
   1. CSV files containing UNIX server statistics.
   2. RRD files containing UNIX server statistics.
   3. CSV files containing PROGRESS database statistics.
   4. RRD files containing PROGRESS database statistics.
6. Error messages produced by the monitor.
7. Appendix.

### 1. Websmon monitor directories structure.

By default, the Websmon monitor is installed to the directory /home/websmon. The monitor installation has the structure of directories as shown below:

/home/websmon/ |  | Configuration file websmon.ini and log file websmon.log
/home/websmon/apache/ |  | Apache HTTP server
/home/websmon/bin/ |  | executable files and scripts
/home/websmon/doc/ |  | documentation
/home/websmon/icons/ |  | icon and image files for the wmshow system
/home/websmon/include/ |  | include files coming with the Open Source Software packages required for the monitor
/home/websmon/lib/ |  | library files required for the monitor including Perl 5.8 and additional Perl modules
/home/websmon/man/ |  | manuals coming along with the Open Source Software packages required for the monitor
/home/websmon/misc/ |  | miscellaneous files (among them, the prototypes of the crontab, .profile, apache.conf files, etc)
/home/websmon/pro/ |  | files of the PROGRESS databases statistics procedures
/home/websmon/rrdtool/ |  | RRD libraries required for the monitor
/home/websmon/src/ |  | source code of the Open Source Software packages used for the monitor (including Perl 5 and RRD tool)
/home/websmon/stats/ |  | a directory to store the CSV and RRD statistic files created by the monitor
/home/websmon/stats/HOST1/ |  | system statistics for the UNIX server HOST1 (an example)
/home/websmon/stats/HOST1/SVCE1/ |  | system statistics for the PROGRESS database server running on the UNIX host HOST1 through the TCP service SVCE1 (an example)
/home/websmon/stats/HOST2/SVCE2/ |  | system statistics for the PROGRESS database server running on the non-UNIX host HOST2 through the TCP service SVCE2 (an example)

### 2. wmshow - A system for graphical representation of the performance statistics gathered by the monitor.

The Web application wmshow which is intended to be running under the Apache Web server shows the collected system statistics in the form of the dynamically created web pages that contain both the text and graphical information that is explained below.

| SYNTAX: |  | wmshow [ini-file]
|  |  | wmshow -help

Optional parameters:

| ini-file |  | - configuration file name, by default, /home/websmon/websmon.ini
| -help |  | - show the program's version

### 2.1. Main (top) web page created by the monitor (1st level of statistics)

The main web page created by the wmshow system contains visual information on hosts, TCP services, and PROGRESS databases activity as well as basic inomation related to the PROGRESS databases such as database size, free space, and number of users connected.

The address of this page is as follows:

       http://statserver:8080/websmon

Here and below statserver means the name of the statistics server where the monitor is installed and runs, and 8080 is the default Apache HTTP server port number.

Figure 1. Main (top) web page of the monitor.

Here, the list of the hosts is shown. Before the host name, a host activity icon (green or red one) appears that may follows a small postal icon. This latter means that the system administrator whose name and address can be found at the bottom of the web page will be alerted when (and if) this host fails. For further information, see the description of the monitor configuration parameter email.

After the host name, the host description is shown (see the configuration parameter desc).

The names of the hosts (UNIX servers) for that the performance statistics is collected appear as the hypertext links to the web pages containing the UNIX server performance statistics (i.e., the 2nd level statistics pages, see p.2.2).

For an active host, the list of the TCP services running on the host can be viewed to the right of the host description. Each TCP service name precedes an service activity icon (green or red one). For the details, see the description of the configuration parameter TCP_services.

Below the host description line, the PROGRESS databases descriptions running on the host may appear. Each database description (parameter dbdesc) is a link to the respected web page containing the PROGRESS database performance statistics (i.e., the 2nd level statistics pages, see p.2.3). Like the UNIX hosts described above, each PROGRESS database description has its activity icon and (possibly) postal icon (see the configuration parameter dbemail). Note that these databases description lines appears on the main web page only if the respected host is up and running, and marked as active in the configuration file.

To the right of an active database's description, there is the useful information about the PROGRESS database shown (such as the number of database users connected, the PROGRESS database size and free space, and the database BI file size).

At the bottom of each web page created by the wmshow system of the monitor, the name and email address of the system administrator appear (see parameter MAIL).

Also, the creation time of the page is shown in the top right corner of the main page.

### 2.2. Web pages containing performance statistics of the UNIX servers. (2nd level of statistics)

These pages contain the summary of statistics of usage of the resources related to the UNIX servers and the links to the respected web pages containing statistics for a particular resource.

The addresses of these pages are as shown below:

       http://statserver:8080/websmon?host=HOSTNAME

(A web page containing the performance statistics for the UNIX server HOSTNAME)

Figure 2. A sample UNIX server performance statistics page. *

* Only top half of the page shown

At the top of the page, the UNIX server name and the time of last update of the statistics gathered are shown.

Below, there are the links to the web pages containing the statistics of usage of the particular UNIX servers resources (i.e., the 3rd level statistics pages, see p.2.4) appeared.

Here is the list of the UNIX server resources available on this page:

- UNIX server load average. Also, the last known value of this resource is shown.
- Number of UNIX users logged to the system. The last known value is shown.
- Number of running processes. The last known value is displayed.
- Percentage of the server CPU usage statistics. Four links have appeared here: total CPU utilization, user, system, and wait I/O utilizations. To the right of the link, the last known value of the total CPU utilization is shown as both the text and the graphic bar.
- Server memory usage. The total memory size and the percentage of used memory are displayed as the text and the graphic bar.
- Disk swap space utilization. The total size of the swap area and the percentage of used swap space are shown as the text and the graphic bar.
- Filesystems usage statistics. Two links are displayed for each filesystem listed in the configuration file's parameter fss: the first points to the web page containing the disk space utilization statistics, the second link leads to the page containing the statistics of inodes utilization for the particular filesystem. Also, the last known values of the filesystem size and used space are shown as both the text values and the graphic bar.
- Network interfaces activity. Two links pointed to the pages containing statistics of the total network traffic and of the total network errors are shown. The same links for each network interface listed in the configuration parameter ifs can also be displayed.
- System I/O statistics.
- System paging statistics.
- System swapping statistics.
- OS kernel semaphores operations activity statistics.
- OS kernel message queues activity statistics.
- System context switching activity statistics.
- UNIX server uptime statistics.

There are also several reports on the actual status of the UNIX server presented below on the page (see the examples listed):

- Detailed UNIX server status report
- List of logged UNIX users
- List of running UNIX processes

At the bottom of the page, there is a list of the PROGRESS database names running on the host. Every database name is linked to the respected web page containing the performance statistics of the database, and there is also certain important database information shown here (same as that presented on the main page).

Finally, the navigation icons linked to the main page are shown in the top right and bottom right corners of the page.

### 2.3. Web pages containing performance statistics of the PROGRESS databases. (2nd level of statistics)

These pages contain the summary of statistics of usage of the resources related to the PROGRESS databases and the links to the respected web pages containing statistics for a particular resource.

The addresses of these pages are as shown below:

       http://statserver:8080/websmon?host=HOSTNAME&service=SERVICENAME

(A web page containing the performance statistics for the PROGRESS datebase running on the host HOSTNAME through the TCP service SERVICENAME)

< align=center width=758 height=420 src="image/wm4.png" alt="Websmon - PROGRESS database server page">
Figure 3. A sample PROGRESS database performance statistics page. *

* Only top half of the page shown

At the top of the page, the PROGRESS database name, the name of the host that the database server is running on (which is the link to the respected 2nd level statistics web page, see p.2.2), and the time of last update of the statistics gathered are shown.

Below, there are the links to the web pages containing the statistics of usage of the particular PROGRESS databases resources appeared (i.e., the 3rd level statistics pages, see p.2.5).

Here is the list of the PROGRESS database resources available on this page:

- Total number of the database connections. The last known values of connections here and below are shown.
- Number of the database users connected.
- Number of the self-serving clients connected.
- Number of the remote clients connected.
- Number of the additional PROGRESS database servers running.
- Size of the database data files. The last known values of the database size and used database space are shown as both the text and the graphic bar.
- Database BI file (area) size. The last known value of the BI file size is shown.
- Database AI file size. The last known value of the AI file size is displayed (the value shown is zero if the After-Imaging is not enabled).
- Database AI extent generation number (for the fixed length database AI files).
- Database cache (buffer pool) hit ratios percentage. The last known value is shown as the text and the graphic bar.
- Database cache buffers utilization statistics: total number of buffers in the pool and the percentage of used buffers. The last know values are shown as the text and the graphic bar.
- Database locking table utilization statistics: total number of database record locks available and percentage of used locks. The last know values are shown as the text and the graphic bar.
- Summary of usage of the PROGRESS database writers: the APW, BIW, and AIW utilization statistics.
- Statistics of PROGRESS Asynchronous Page Writers usage: the number of the PROGRESS APW(s) running, and the APW utilization percentage value. The latter (as both the last known text value and the graphic bar) is displayed only if a PROGRESS APW is started.
- Statistics of PROGRESS Before Image Writer usage: a flag shown if the PROGRESS BIW is running, and the BIW utilization percentage value. The last known text value of the utilization and the graphic bar are displayed only if the PROGRESS BIW is started.
- Statistics of PROGRESS After Image Writer usage: a flag shown if the PROGRESS AIW is running, and the AIW utilization percentage value. The last known text value of the utilization and the graphic bar are displayed only if the After-Imaging is enabled and the PROGRESS AIW is started.
- Summary of the database block I/O activity.
- Database I/O activity shown separately for database data blocks.
- Database I/O activity shown separately for database index blocks.
- Database read activity, both for the data and index blocks.
- Database write activity, both for the data and index blocks.
- Database BI file I/O activity.
- Database AI file write activity.
- Database transactional activity (the commit and undo rates are shown).
- Summary of the database record access activity: records creation, reading, updating, deletion rates.
- Database records creation statistics.
- Database records reading statistics.
- Database records updating statistics.
- Database records deletion statistics.
- Summary of the database index access activity: index creation, finding, deletion rates.
- Database index creation statistics.
- Database index finding statistics.
- Database index deletion statistics.
- Database checkpoints statistics: number of the database dirty blocks and flushed blocks.
- Statistics of waits for the busy database BI buffers and for the empty BI buffers.
- Statistics of waits for the total database AI buffers and for the busy AI buffers.
- Statistics of waits for the locked database records.
- Database uptime statistics.

There are also several reports on the actual status of the PROGRESS database server presented below on the page (see the examples listed):

- Detailed database status report
- Database user list

Finally, the navigation icons linked to the main page are shown in the top right and bottom right corners of the page.

### 2.4. Web pages containing system statistics of the UNIX server resources. (3rd level of statistics)

These pages contain the statistics of usage of the particular UNIX server resources.

The addresses of these pages are as shown below:

       http://statserver:8080/websmon?host=HOSTNAME&page=RESOURCE

(A web page containing the statistics of usage of the resource RESOURCE of the UNIX server HOSTNAME)

< align=center width=758 height=420 src="image/wm3.png" alt="Websmon - Server load averages page">
Figure 4. A sample UNIX server resource statistics page - Server load averages. *

* Only top half of the page shown

At the top of the page, the UNIX server name (which is the link to the respected 2nd level statistics web page, see p.2.2), the name of the particular system resource, and the time of last update of the statistics gathered are shown.

Next on the page, there are four graphs showing the graphical representation of the statistics gathered for the particular system resource. Each graph represents the changes of a monitored resource value for the certain period of time (which is displayed on the X axis) with the different average as follows:

- The most detailed daily graph shows the values of a system resource with the 5 minute average on the Y axis for the period of last 33 hours.
- The weekly graph shows the system resource values with the 30 minute average for the last 8 days.
- The monthly graph shows the resource values with the 2-hour average for the last 5 weeks.
- And finally, the yearly graph shows the values of a resource with the 24-hour average on the Y axis for the period of last 13 months.

The above mentioned graphs can be laid out on the web page either in one or in two columns. For more details, see the configuration parameter layout.

There are the maximum, average, and current values of the monitored resource displayed under each graph (i.e. the values with the 5 minute, 30 minute, 2 hour, or 24 hour average).

The following units can be used for the displayed resources values:

- u = micro (10E-6)
- m = milli (10E-3)
- k = kilo (10E3)
- K = 1024
- M = Mega (10E6)
- G = Giga (10E9)
- T = Tera (10E12)

The navigation icons linked to the respected UNIX server performance statistics web page and to the main web page are shown in the top right and bottom right corners of the page.

### 2.5. Web pages containing system statistics of the PROGRESS database resources. (3rd level of statistics)

These pages contain the statistics of usage of the particular PROGRESS databases resources.

The addresses of these pages are as shown below:

       http://statserver:8080/websmon?host=HOSTNAME&service=SERVICENAME&page=RESOURCE

(A web page containing the statistics of usage of the resource RESOURCE of the PROGRESS datebase running on the host HOSTNAME through the TCP service SERVICENAME)

Figure 5. A sample PROGRESS database resource statistics page - Total number of the database connections. *

* Only top half of the page shown

At the top of the page, the PROGRESS database name (which is the link to the respected 2nd level statistics web page, see p.2.3, the name of the host that the database server is running on (which is also the link to the respected web page, see p.2.2), the name of the particular system resource, and the time of last update of the statistics gathered are shown.

Next on the page, there are four graphs showing the graphical representation of the statistics gathered for the particular system resource. For the further information on the graphs, see p.2.4.

The navigation icons linked to the respected PROGRESS database performance statistics web page and to the main web page are shown in the top right and bottom right corners of the page.

### 3. Utilities and scripts of the monitor.

For every program described below, you can use the parameter -help to display a short help message showing the program's version and the list of options.

### 3.1. websmon - A wrapper shell script for collecting system performance statistics.

This shell script is a wrapper for the programs wmgather or wmgather2 and is intended to be run from within the crontab file of the user websmon. Use the crontab settings to change the statistics poll frequency. The name of the program to be called (wmgather/wmgather2) is defined inside the script.

| SYNTAX: |  | websmon
|  |  | websmon -help

### 3.2. wmbar - A helper CGI program for the wmshow system.

This is a helper CGI program which produces a single graphic bar of the specified length, width and color in the in the PNG format. It is intended to be invoked from the Web application wmshow.

| SYNTAX: |  | <img width=WIDTH height=HEIGHT src="wmbar?CGI-parameters">
|  |  | wmbar -help

Possible CGI parameters (any parameter can be omited):

| width |  | - length of the bar being created in pixels
| height |  | - height of the bar in pixels
| val |  | - length of the bar's filled part
| fg |  | - color of the filled part (here and below, a color should be specified in the standard form #RRGGBB)
| bg |  | - background color of the bar
| border |  | - border color
| refresh |  | - refresh time in seconds

### 3.3. wmdbrrd - A utility program to store PROGRESS database-related statistics in the RRD files.

This utility updates the RRD files containing the statistics of usage of the PROGRESS databases resources and is intended to be called from the program wmgather2 (and actually from within the PROGRESS procedure dbstatx2.p).

| SYNTAX: |  | wmdbrrd dbtype dir step logfile record
|  |  | wmdbrrd -help

Required parameters:

| dbtype |  | - type of the database, for Websmon version 1.0 always set to progress
| dir |  | - RRD directory, for instance, /home/websmon/stats/server1/db1
| step |  | - step (i.e., data sampling interval) for the respected RRD files in minutes. By default, the value of step is 5 minutes.
| logfile |  | - log file name, by default, /home/websmon/websmon.log The file name - means STDOUT.
| record |  | - a statistics data record in the CSV format (see p.5.3).

### 3.4. wmexport - A shell script for exporting CSV statistic files.

This shell script exports the gathered statistics off-line to the remote Websmon monitor creating either a file wm%HOST%SVCE%MM%YYYY.tgz which contains both the PROGRESS database related and the UNIX server related statistics or a file wm%HOST%MM%YYYY.tgz which contains only the UNIX server related statistics gathered in the month MM of a year YYYY.

Here SVCE is the name of a TCP service through which a PROGRESS database server is running on the host (UNIX server) HOST.

| SYNTAX: |  | wmexport -H host [-S service] [-d outdir] [-m month] [-y year]
|  |  | wmexport -help

Required parameter:

| -H host |  | - name of the host (UNIX server) for which the statistics is gathered

Optional parameters:

| -S service |  | - name of the TCP service through which the PROGRESS database server is running on the host By default, only the UNIX server related statistics will be exported.
| -d outdir |  | - export file directory, by default, /home/websmon
| -m month |  | - month number (1..12) that the gathered statistics should be exported for (by default, current month)
| -y year |  | - year (2000..2099) that the gathered statistics should be exported for (by default, current year)

### 3.5. wmgather - A program for collecting system statistics serially.

This program collects the statistics from all UNIX servers and PROGRESS databases listed in the configuration file websmon.ini polling them one-after-one then stores the gathered data to the CSV files and updates the respected RRD files.

| SYNTAX: |  | wmgather [-no-rrd-update] [ini-file]
|  |  | wmgather -help

Optional parameters:

| -no-rrd-update |  | - do not update the RRD files, only store the statistic data to the CSV files
| ini-file |  | - configuration file name, by default, /home/websmon/websmon.ini

### 3.6. wmgather2 - A program for collecting system statistics in the parallelized mode.

This program collects the statistics from all UNIX servers and PROGRESS databases listed in the configuration file websmon.ini then stores the gathered data to the CSV files and updates the respected RRD files.

The UNIX servers are polled one-after-one meanwhile all PROGRESS database servers running on a host are polling simultaneously.

| SYNTAX: |  | wmgather2 [-no-rrd-update] [ini-file]
|  |  | wmgather2 -help

Optional parameters:

| -no-rrd-update |  | - do not update the RRD files, only store the statistic data to the CSV files
| ini-file |  | - configuration file name, by default, /home/websmon/websmon.ini

### 3.7. wmhttpd - A control shell script for the Apache HTTP server.

This control script is primarely intended to run the monitor's Apache HTTP server httpd when called from a UNIX boot up directory, i.e. /etc/rcN.d.

| SYNTAX: |  | wmhttpd start
|  |  | wmhttpd stop
|  |  | wmhttpd restart
|  |  | wmhttpd status
|  |  | wmhttpd configtest
|  |  | wmhttpd help

Being called without parameters, wmhttpd prints a short help message showing its version and the list of options.

Control parameters:

| start |  | - start up the HTTP server
| stop |  | - shut down the HTTP server
| restart |  | - restart the HTTP server
| status |  | - print status of the server
| configtest |  | - check the server's configuration file httpd.conf
| help |  | - print the help message

### 3.8. wmimport - A shell script for importing CSV statistic files.

This shell script imports the gathered statistics from a remote Websmon monitor in the off-line mode. It reads the export file created by the script wmexport and rebuilds the CSV and RRD files.

| SYNTAX: |  | wmimport -f file [-d dir] [-y] [-s] [-i interval] [-q]
|  |  | wmimport -help

Required parameter:

| -f file |  | - export file name wm%HOST%SVCE%MM%YYYY.tgz or wm%HOST%MM%YYYY.tgz containing the statistics gathered in the month MM of the year YYYY for the UNIX server HOST and/or for the PROGRESS database running through the TCP service SVCE

Optional parameters:

| -d dir |  | - statistics directory name (by default, /home/websmon/stats)
| -y |  | - create the statistics directory without confirmation if it is not exist (by default, the confirmation is required)
| -s |  | - import only the PROGRESS database related statistics (by default, all statistics found in the export file is imported)
| -i interval |  | - explicitly specify the data sampling interval (in minutes) used for rebuilding the RRD files (by default, the step value is based on the data found in the imported CSV files)
| -q |  | - quiet mode (useful for the batch processing)

### 3.9. wmmkrrd - A utility program for rebuilding RRD files from a CSV statistic file.

This utility rebuilds the RRD files from a CSV data file and is intended to be called from the script wmimport.

| SYNTAX: |  | wmmkrrd [-quiet -step value] -unix CSV_file RRD_dir
|  |  | wmmkrrd [-quiet -step value] -progress CSV_file RRD_dir
|  |  | wmmkrrd -help

Required parameters:

| -unix |  | - rebuild the UNIX server related RRD files
| -progress |  | - rebuild the PROGRESS database server related RRD files
| file |  | - a CSV file name
| dir |  | - directory name for the RRD files

Optional parameters:

| -quiet |  | - quiet mode for batch processing
| -step value |  | - data sampling interval (in minutes) used for rebuilding the RRD files. By default, the step value is based on the data found in a CSV file.

### 3.10. wmsetup - A program to help set up the monitor configuration file.

This interactive program is a kind of wizard intended to help setting up the configuration file websmon.ini.

First, the program will require you to enter the monitor license information.

Next, wmsetup will ask you for the SMTP mail server name.

Then, the program will ask for the value of the interval to be used while gathering statistics (that is, by default, 5 minutes).

Note: Here and below, do not change the default values unless you really need to do so!

Then, the program will set up the parameters used by wmshow, such as the graphs size, their orientation on a web page, the size and colors of the graphic bars, the colors and a background image (if any) for the web pages created by the monitor, etc. The bars colors are defined in the form RRGGB, where the components RR, GG, and BB are the hexadecimal values of the red, blue, and green colors, respectively.

The colors used for the graphic bars should be defined as follows:

           main_fg:main_bg:warning_level:warn_fg:warn_bg:alarm_level:alarm_fg:alarm_bg

For instance:

           00cc00:8fffff:80:ffff00:8fffff:98:ff0000:8fffff

Here main_fg and main_bg are the main and the background colors used for the representation of the "normal" state of a system parameter, for example, the green bar 00cc00 on the blue background 8fffff while a parameter is in a range of 0% to the warning_level (here, 80%) of its max possible value. When the parameter's value is in the "warning" state, i.e. it is more than the warning_level (80% of the maximum), but still less than the alarm level (98%), the warn_fg and warn_bg colors are used to render the bar (here, the yellow bar ffff00 on the blue background 8fffff). And finally, when the value of the system parameter is more than the alarm level (98%), alarm_fg and alarm_bg bar colors are used (here, the red bar ff0000 on the blue background 8fffff).

Of course, the reverse color set can also be used.

After defining the parameters of wmshow, wmsetup will set up the name of the directory where the statistics CSV and RRD files reside (by default, /home/websmon/stats), and the directory for the monitor lock files (by default, /tmp/websmon).

Finally, the wmsetup will begin setting up the UNIX servers and PROGRESS databases which should be monitored.

For every monitor configuration parameter, there is a default value in the configuration file so you can just leave it unchanged. The two exceptions are the name of a mail (SMTP) server existed in your computer system (used by wmwatch program to notify a system administrator when a server or a database fails) and the names and addresses of the system administrators.

You always can exit from wmsetup program without any changes made to the configuration file by just answering a next question q[uit]

| SYNTAX: |  | wmsetup [ini-file]
|  |  | wmsetup -license [ini-file]
|  |  | wmsetup -help

Optional parameters:

| ini-file |  | - configuration file name, by default, /home/websmon/websmon.ini
| -license |  | - change the Websmon monitor's license information only

### 3.11. wmsysid - A utility program for showing the unique system ID of a UNIX server.

This utility is used to obtain a unique ID string of a UNIX server based on the server's hardware configuration.

| SYNTAX: |  | wmsysid [-quiet]
|  |  | wmsysid -help

Optional parameter:

| -quiet |  | - show the system ID only (by default, the name of the UNIX server is also printed)

### 3.12. wmwatch - A program for monitoring activity of the hosts, TCP services and PROGRESS databases.

This utility checks the activity of the hosts (including but not limited to UNIX servers), the TCP services running on the mentioned hosts, and the PROGRESS database specified in the monitor configuration file websmon.ini. When a server, a service, or a PROGRESS database becomes inactive, the system administrator will be alerted by email. The wmwatch program is intended to be invoke from within the crontab file of the user websmon. You can change the frequence of checking there (by default, the checking is performed every minute).

| SYNTAX: |  | wmwatch [-verbose] [ini-file]
|  |  | wmwatch -help

Optional parameters:

| -verbose |  | - display more verbose error messages
| ini-file |  | - configuration file name, by default, /home/websmon/websmon.ini

### 3.13. wmzip - A shell script for archiving old CSV statistic files having created by the monitor.

Being called without parameters, this shell script archives old CSV data files found under the directory /home/websmon/stats/.

Use the parameter -log to archive the monitor log file /home/websmon/websmon.log.

The script is intended to be run from within the crontab file of the user websmon, usually one time a month.

| SYNTAX: |  | wmzip
|  |  | wmzip -log
|  |  | wmzip -help

### 4. The monitor configuration file websmon.ini.

The configuration file (by default, /home/websmon/websmon.ini; see also p.4.1) is a plain text file which consists of a number of sections.

Each section is preceded with a line indicating the section name in square brackets, for instance [SECTION], and it ends either at the beginning of the next section or at the end of the configuration file.
The name of a section should be made up of the word characters, i.e. letters, numbers, underscores, and dashes.

Comment lines (those begin with either the hash mark # or the semicolon ; characters) and blank lines will be ignored.

Parameters are specified in each section as Name=Value:

     [Section1]
      Parameter1 = Value1
      Parameter2 = Value2
      ...

Any whitespaces around the equals sign will be ignored, and the value extends to the end of the line. Parameter lines can be continued by use of the backslash (\) character at the end of the line:

     [Section2]
      Parameter1 = Value1 Value2 \
                   Value3 \
                   Value4 ...

Parameter names are localized to the namespace of the section, but must be unique within a section. Multi-line parameters may also be defined ala UNIX "here document" syntax:

     [Section3]
      Parameter_Name=<<EOT
       Value1
       Value2
       ......
    EOT

All leading whitespaces in the parameter lines will be ignored.

The names of the mandatory (service) sections begin and end with the colon (:) character, for instance, [:license:].

The service sections are as follows:

| [:default:] |  | - section contains the default values for the parameters of all sections that define UNIX servers or PROGRESS databases
| [:system:] |  | - section contains the system-wide settings for the monitor (like names of the directories, etc)
| [:graph:] |  | - section contains the settings for the wmshow graphs
| [:bar:] |  | - section contains the settings for the wmshow graphic bars
| [:license:] |  | - section contains the license information

Names of all other sections consist of either a UNIX server name (for instance, [sun] for the UNIX server sun, see ) or a host name and a TCP service name, or a TCP port number (for instance, [sun:dbsvce] for the PROGRESS database server running through the TCP service dbsvce on the host sun; note the separating colon :). The section names are case-sensitive so be careful!

The monitor configuration parameters are described below, see [:default:].

Note: The section that defines a host should go before any section with the definitions for the PROGRESS databases running on this host.

### 4.1. Where the configuration file resides.

The monitor will look for its configuration file in the following directories (note the order):

- 1st argument of the command line if any given
- shell environment variable WEBSMON_INI if it is defined
- $WEBSMON/websmon.ini (if the shell variable WEBSMON is defined)
- /home/websmon/websmon.ini
- $HOME/websmon.ini
- /etc/websmon.ini

If not found or if an error occured, the configuration file will be silently ignored and the next one from the list above will be used.

### 4.2. Several examples of the configuration file's sections.

4.2.1. Section containing the definitions for the host sun (OS Sun Solaris).

Additionally, the TCP services telnet, SSH, FTP, SMTP, HTTP, the file systems /usr, /var, /tmp, /home, /home2, /u, and the network interfaces ge0 and hme0 are monitored for this host:

    # Production server running Sun Solaris 8
    [sun]
       ostype = solaris
       desc = Sun Solaris 8
       TCP_services =<<EOT
             telnet = 23
             SSH = 22
             FTP = 21
             SMTP = 25
             HTTP = 80
    EOT
       email = telnet,SSH,FTP
       fss = / /usr /var /tmp /home /home2 /u
       ifs = ge0 hme0

4.2.2. Section containing the definitions for the host neptune (OS MS Windows 2000)

Additionally, the TCP services FTP, SMTP, and HTTP are monitored for this host:

    # MS Windows 2000 FTP and mail server
    [neptune]
       ostype = mswin2k
       desc = MS Windows 2000
       TCP_services =<<EOT
             FTP = 21
             SMTP = 25
             HTTP = 80
    EOT
       email = SMTP

4.2.3. Section containing the definitions for the host mars (OS Novell Netware 5):

    # File server running Novell Netware 5
    [mars]
       ostype = netware
       desc = Novell Netware 5
       email = yes

4.2.4. Section containing the definitions for the PROGRESS database prodb1 running on the host sun through the TCP service dbservice1:

    # PROGRESS V9.1D database running on the host 'sun' under Sun Solaris 8
    [sun:dbservice1]
       dbname = prodb1
       dbdesc = PROGRESS database #1
       dbactive = yes
       dbemail = yes
    # E-Mail settings
       MAIL =<<EOT
           To = Database Administrator <dba@domain.com>
           Subject = PROGRESS database sun:prodb1 is down!
           Message = PROGRESS database PRODB1 running on SUN is down on %date at %time
    EOT
    # Environment variables
      ENV =<<EOT
            DLC = /usr/dlc-9.1d
            PROMSGS = /usr/dlc-9.1d/prolang/ame/promsgs.ame
            PROTERMCAP = /usr/dlc-9.1d/protermcap
            TERM = ansi
    EOT

4.2.5. Section containing the definitions for the PROGRESS database prodb2 running on the host neptune through the TCP port 55252:

    # PROGRESS V8.3C database running on the host 'neptune' under MS Windows 2000
    [neptune:55252]
       dbname = prodb2
       dbdesc = PROGRESS database #2
       dbactive = yes
       dbemail = yes
    # E-Mail settings
       MAIL =<<EOT
           To = Database Administrator <dba@domain.com>
           Subject = PROGRESS database neptune:prodb2 is down!
           Message = PROGRESS database PRODB2 running on NEPTUNE is down on %date at %time
    EOT
    # Environment variables
      ENV =<<EOT
            DLC = /usr/dlc83c
            PROMSGS = /usr/dlc83c/prolang/ame/promsgs.ame
            PROTERMCAP = /usr/dlc83c/protermcap
            TERM = ansi
    EOT
    # Additional PROGRESS session parameters (for MS Windows 2K)
      dbparams = -Mm 512

### 4.3. Section [:default:] - Default values of the monitor configuration parameters.

In this section, the default values for the host and PROGRESS database configuration parameters are set so that one can omit almost all of the parameters while defining a host or a database.

Parameters with the names other than specified below will silently be ignored.

#### ostype = undefined

The default type of the operating system running on the host [undefined]. Any value of this parameter is acceptable (for instance, mswin, MS_Windows_NT, WindowsNT, etc for the MS Windows NT operating system), but note that the UNIX system statistics will be gathered and shown only for the hosts with the parameter ostype set to the following values: linux for OS Red Hat Linux 7, 8, 9, and Red Hat Enterprise Linux AS 3, solaris for OS Sun Solaris 8 and 9, and unixware for OS SCO UnixWare 7.

You also can try the value ostype=aix for the OS IBM AIX, but as for Websmon monitor version 1.0, the support for this OS is in the beta-testing stage.

#### desc = no host description

A default host description which is printed on the web pages created by the monitor.

This is a short text string of 30-40 characters length, for instance:

        desc = Sun E6500 production server

#### active = yes

The default host status [host is active].

You can temporarily disable collecting the system statistics from a particular host (and from any of the databases running on that host) by just assigning the parameter active to any of the following values: no, not, off, disabled, or 0.

The values above are case-insensitive, e.g.

        active = NOT

#### TCP_services =

The default list of TCP services that should be monitored by the wmwatch system and status of which will be displayed by the wmshow system [empty list].

The list is a multi-line parameter where each value is a pair of TCP_service_name=port_number, for instance:

        TCP_services =<<EOT
            telnet = 23
            SSH = 22
            FTP = 21
            SMTP = 25
            HTTP = 80
    EOT

If you want a system administrator to be alerted when a TCP service fails (becomes inactive), just add TCP_service_name (e.g. telnet) to the value of the configuration parameter email.
Separate the names with spaces or commas, e.g.

        email = SSH,telnet,FTP

#### pingmode = tcp

The default type of TCP protocol to be used while checking the remote hosts activity (reachability), one of tcp (strongly recommended), udp, icmp [tcp].

Note that specifying the icmp protocol requires that the monitor programs be run as root or that the program be setuid to root (what is probably not that you want to use).

#### timeout = 2

The default value of timeout used when a remote host or a TCP service is checking for activity [2 seconds].

#### email = no

This configuration parameter determines whether or not a system administrator is alerted by email when a remote host or one of the TCP services running on the host becomes inactive (i.e., when a failure occurs).

By default, no notifications will be sent (which means that the parameter is set to one of no, not, off, disabled, or 0).

If this parameter is set to yes, on, enabled, or 1, the system administrator will be notified when the hosts itself becomes inactive, e.g.

        email = Yes

If you want to send a notification when one or another TCP service running on a remote host fails, you need to add the names of the services you want to watch for to the current value of the parameter.
Separate the service names with spaces or commas, e.g.

        email = telnet SSH FTP HTTP

The names of the TCP services mentioned here have to be defined in the configuration parameter TCP_services. Note that in this case, the administrator will also be alerted when the remote hosts goes down.

#### remsh = /usr/local/bin/ssh

The default name of the remote shell program to be used to collect statistics from the remote UNIX servers [ssh]. You can add some options to the shell definition, for instance:

        remsh = rsh

or, to explicitly use the SSH protocol version 1:

        remsh = /usr/local/ssh/bin/ssh -1

#### interval = 10

The default sampling interval value (in seconds) to be used while collecting the UNIX server statistics [10 seconds].

#### ifs =

The default list of the UNIX server network interfaces for which the network traffic and errors statistics should be displayed by the wmshow system [empty list].

The network interfaces should be separated by spaces or commas, for instance:

        ifs = hme0 hme1

If this parameter is not set, only the summary of the network statistics will be shown by the monitor.

#### fss = /

The default list of the UNIX server filesystems for which the statistics of the disk space and inodes utilization should be displayed by the wmshow system [/].

The network interfaces should be separated by spaces or commas, for instance:

        fss = / /usr /var /tmp /home /home2

If this parameter is not set, only the root (/) filesystem usage statistics will be shown by the monitor.

#### dbtype = PROGRESS

The default type of the database [PROGRESS].

For Websmon monitor version 1.0, this parameter is always set to PROGRESS (i.e., reserved for the future use).

#### dbname = database_name

The default database name, for instance:

        dbname = test_db

#### dbdesc = PROGRESS database

A default PROGRESS database description which is printed on the web pages created by the monitor.

This is a short text string of 20-30 characters length, for instance:

        dbdesc = Production database for Bank A

#### dbactive = yes

The default status of the PROGRESS database [database is active].

You can temporarily disable collecting the system statistics from a particular PROGRESS database by just assigning the parameter dbactive to any of the following values: no, not, off, disabled, or 0.

The values above are case-insensitive, e.g.

        dbactive = NOT

#### dbparams = -T /tmp

The optional parameters for the PROGRESS client session [-T /tmp].

These optional PROGRESS parameters are used to connect to a remote PROGRESS database for collecting statistics and for making on-line database reports.

For instance, in order to connect to the PROGRESS database running on a server under the MS Windows NT operating system, you may need the following PROGRESS client session parameters:

        dbparams = -T /tmp -Mm 512

#### dbemail = no

This configuration parameter determines whether or not a database administrator is alerted by email when a PROGRESS database fails or is shutting down.

By default, no notifications will be sent (which means that the parameter is set to one of no, not, off, disabled, or 0).

If this parameter is set to yes, on, enabled, or 1, the administrator will be notified when a database becomes inactive, e.g.

        dbemail = Yes

#### dbinterval = 10

The default sampling interval value (in seconds) to be used while collecting the PROGRESS database statistics [10 seconds].

#### MAIL = value

A default list of the email templates used for notifying the system adminitrator.

The list is a multi-line parameter where each value is a pair of Email_header_name=Email_header_value, for instance:

        MAIL =<<EOT
             From = Websmon System Monitor <websmon@localhost>
             To   = System Administrator <root@localhost>
             CC   =
             BCC  =
             X-Mailer = Mail::Sendmail
             Subject = %host:%service is down
             Message = %host:%service is down on %date at %time
    EOT

You can use here the arbitrary text strings and the following substitutions:

| %date |  | - data when the email is sent; format: DayOfWeek Day-Month-Year
| %time |  | - time when the email is sent; format: HH:MM:SS
| %host |  | - the name of the host from whence the message is sent
| %service |  | - the name of the stopped service (optional)

#### ENV = value

A default list of the environment variables to be set before collecting the system statistics (this feature is especially useful for a PROGRESS client session, for example, it could be necessary to set certain shell variables before running the PROGRESS client if there are multiple PROGRESS installations existing in your system).

The list is a multi-line parameter where each value is a pair of shell_variable_name=value, for instance:

        ENV =<<EOT
            DLC=/usr/dlc_91d
            PROMSGS=/usr/dlc_91d/prolang/ame/promsgs.ame
            PROTERMCAP=/usr/dlc_91d/protermcap
            TERM=ansi
    EOT

### 4.4. Section [:system:] - System-wide settings of the monitor

Parameters given here define system settings of the monitor, e.g. directories for temporary monitor files and files containing statistic data, colors and/or background image used on the web pages created by the monitor, etc.

These parameters cannot be redefined for any specific host and/or database server.

#### flagdir = /tmp/websmon

Parameter flagdir defines the directory containing temporary lock files created by the monitor. By default, this is /tmp/websmon.

#### logfile = /home/websmon/websmon.log

Parameter logfile defines the log file name of the monitor, by default, /home/websmon/websmon.log. The file name - means STDOUT.

#### statdir = /home/websmon/stats

Parameter statdir defines the directory containing statistic data files (in the subdirectories statdir/SERVER and statdir/SERVER/SERVICE, where SERVER means host names, and SERVICE means names of TCP-services used by database servers).

The statistics file names are constructed from the month and year of creation (YYYYMM), for instance, the file name 200401.csv means statistics collected in the January of 2004.

#### polling_interval = 5

This parameter defines the interval of gathering statistics for the wmgather system (in minutes). The parameter should be the same as the calling interval for the script websmon ib the crontab-file of the user websmon.

This parameter also defines the refresh time for all but the main web pages created by the monitor.

By default, the value of polling_interval is set to 5 minutes. It is not recommended to change this parameter.

#### refresh = 30

Refresh time for the main (top) web page created by the monitor. By default, 30 seconds.

#### bg_color = fff6f0

#### text_color = 000000

#### value_color = 0000ff

#### alink_color = ff00ff

These parameters define the following colors used on the web pages created by the monitor:

- Color of the background of a web page (bg_color)
- Color of the text (text_color)
- Color of the numeric values (value_color)
- Color of the web links (alink_color) shown on a web page

Here and after, the values of the color parameters are given in the form of RRGGBB, where RR, GG, BB are the hexadecimal values of the red, green, and blue components of a color.

#### background = bg4.jpg

This parameter defines the name of the file containing the optional background image (wallpaper) used on the web pages created by the monitor. By default, the file name is bg4.jpg.

All image files should be placed to the directory defined in the configuration parameter (alias) wmicons of the Apache configuration file httpd.conf (by default, the directory /home/websmon/icons).

For more information on the image files used by the monitor, see p.7.

#### charset = iso-8859-1

The encoding used in the web pages created by the monitor, by default the code page ISO 8859-1.

#### MailServers = localhost

The space-separated list of the domain names and/or IP addresses of the mail servers used by the monitor to send out alerts and notifications. Optionally a domain name can be followed by an SMTP port number, for instance:

        MailServers = mail ms2:25 backup_mail:8025

#### UNIX_info = on

Specify this parameter to include certain predefined online reports on the status of UNIX servers on the web pages created by the monitor:

- Detailed report on the status of the server
- List of logged UNIX users
- List of running processes

NOTE: If the wmshow system is running under an Apache HTTP server other than that bundled with the monitor, you may have problems connecting to the remote UNIX servers using the account websmon because by default wmshow runs under the effective UID apache.

Another problem may come up with the suEXEC Apache server directive that should be enabled when building the Apache executable file.

To avoid such problems, use the bundled Apache HTTP server and start it up under the account websmon.

Otherwise, you should disable this parameter:

        UNIX_info = off

### 4.5. Section [:graph:] - Settings of the graphs created by the wmshow system.

Parameters here define the appearance of the graphs shown on the web pages created by the wmshow system.

The value of a color is given in the form of RRGGBB, where RR, GG, BB are the hexadecimal values of the red, green, and blue components of the color.

#### width = 400

Width (X size) of the graphs in pixels; by default, graph width is 400 pixels.

#### height = 100

Height (Y size) of the graphs in pixels; by default, graph height is 100 pixels.

#### ygrid =

The type of the grid (Y grid lines) shown on the graphs; by default, the regular grid lines are used.

Alse, you can use the following grid types:

        ygrid = -R

or

        ygrid = -Y --no-minor

Do not change this parameter unless you know what you are doing. For more information, see man rrdgraph

#### colorFont = 000000

#### colorBold = 0000ff

#### colorBG = f5f5f5

#### colorMgrid = 000000

#### colorFrame = 000000

#### colorArrow = ff0220

#### colorError = ff0220

#### colorVrule = ff0000

Colors used in the graphs are:

- color of the text (colorFont)
- color of the bold text (colorBold)
- color of the background (colorBG)
- color of the major grid (colorMgrid)
- color of the frame (colorFrame)
- color of the arrow on the horizontal axis (time axis) (colorArrow)
- color of the error messages (colorError)
- color of the vertical rule marking start of the day, week, month, and year (colorVrule)

#### color1 = 00cc00

#### color2 = 0000ff

#### color3 = ffaa00

#### color4 = ff00ff

#### color1max = 077727

#### color2max = 077c77

Graph data colors are: four basic colors for the statistic data shown on the graphs as the lines and/or filled areas and two colors for the lines of maximum values.

Values of the basic colors are green, blue, yellow and violet. Maximum values lines are of dark-green and dark-blue colors.

#### layout = square

Orientation of the graphs on the web pages created by the monitor is:

| layout = vertical |  | - the default vertical layout (in one column): daily statistics graph weekly statistics graph monthly statistics graph yearly statistics graph
| layout = square |  | - the square layout (in two columns): daily graph weekly graph monthly graph yearly graph

### 4.6. Section [:bar:] - Settings of the graphic bars created by the wmshow system.

Parameters in this section define the appearance of the single graphic bars shown on the web pages created by the monitor. These bars are graphically representing the values of certain parameters and/or system resources used by UNIX servers and PROGRESS database servers.

Colors used in the bars are defined as follows:

        main_fg:main_bg:%warning:warn_fg:warn_bg:%alarm:alarm_fg:alarm_bg

    Example:
        0000ff:8fffff:80:ffff00:8fffff:98:ff0000:ffc0c0

Here main_fg and main_bg are the foreground and background colors of the bar while the parameter value is in its normal range (i.e., when it is below the %warning level); in this example, the normal colors are blue on light cyan when the parameter is in the range of 0..80 percent of its maximum value.

When the parameter is in the range of %warning..%alarm percent of its maximum, the next color pair warn_fg and warn_bg will be used: the warning colors are yellow on light cyan when the value is in the range of 80..98 percent of its maximum.

And finally, when the value of the parameter is above than the %alarm level, the colors alarm_fg and alarm_bg will be used to display the parameter: red on pink in the example above when the parameter is higher than 98 percent of the maximum.

#### width = 202

Width (X size) of the bars in pixels; by default, bar width is 202 pixels.

#### height = 9

Height (Y size) of the bars in pixels; by default, bar height is 9 pixels.

#### colorBorder = 000000

Color of the bar border: by default, black color is used (000000).

#### colorCPU = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

Bar colors for the CPU load of a UNIX server: warning when the CPU load is more than 90%, alarm level is 95%.

#### colorMem = 0000ff:8fffff:98:ffff00:8fffff:99:ff0000:ffc0c0

Bar colors for the memory usage of a UNIX server: warning when more than 98% of the memory is in use, alarm level is 99%.

#### colorSwap = 0000ff:8fffff:80:ffff00:8fffff:90:ff0000:ffc0c0

Bar colors for the swap space usage of a UNIX server: warning when more than 80% of the swap space is in use, alarm level is 90%.

#### colorFS = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

Bar colors for the disk space usage of a UNIX server file system: warning when more than 90% of the file system space is in use, alarm level is 95%.

#### colorDBsize = 0000ff:8fffff:97:ffff00:8fffff:99:ff0000:ffc0c0

Bar colors for the PROGRESS database file space use: warning level when more than 97% of the db space is in use, alarm level is 99%.

#### colorDBhits = ff0000:ffc0c0:90:ffff00:8fffff:95:0000ff:8fffff

Bar colors for the database cache hits level (note the inverted color map): warning when the value of db cache hits is less than 95%, alarm when the value is below 90%.

#### colorDBbufs = ff0000:ffc0c0:75:ffff00:8fffff:80:0000ff:8fffff

Bar colors for the database cache utilization level (note the inverted color map): warning when the db cache utilization value is less than 80%, alarm when the value is below 75%.

#### colorDBlocks = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

Bar colors for the database locking table utilization level: warning when more than 90% of the locking table is in use, alarm when the value is above 95%.

#### colorAPW = ff0000:ffc0c0:50:ffff00:8fffff:75:0000ff:8fffff

Bar colors for the PROGRESS database Asynchronous Page Writers utilization level: warning when the APW utilization is less than 75%, alarm when the value is below 50%.

#### colorBIW = ff0000:ffc0c0:75:ffff00:8fffff:90:0000ff:8fffff

Bar colors for the PROGRESS database BI Writer utilization level: warning when the BIW utilization is less than 90%, alarm when the value is below 75%.

#### colorAIW = ff0000:ffc0c0:75:ffff00:8fffff:90:0000ff:8fffff

Bar colors for the PROGRESS database AI Writer utilization level: warning when the AIW utilization is less than 90%, alarm when the value is below 75%.

### 4.7. Section [:license:] - License information of the monitor.

Parameters in this section define the type of the monitor license.

#### S/N

License serial number (for permanent licenses only).

#### RegCode

A string of the license registration code.

#### MaxUnixSrv

Maximum number of UNIX servers to be monitored (for permanent licenses only).

The value of this parameter is an integer, UNLIMITED, or NONE.

#### MaxProgSrv

Maximum number of PROGRESS databases to be monitored (for permanent license only).

The value of this parameter is an integer, UNLIMITED, or NONE.

### 4.8. A sample monitor configuration file.

    #comment
    #
    # @(#) A sample Websmon Monitor configuration file
    #
    # Websmon -- Web-based system performance monitor, version 1.01.
    # Copyright (C) 2003-2005 Dmitry Lapenkov. All rights reserved.
    #
    #

    ##################
    ## UNIX servers

    # SCO UnixWare 7
    [unixware]
       ostype = unixware
       desc = SCO UnixWare 7.1.1
       TCP_services =<<EOT
             telnet = 23
             SSH = 22
             FTP = 21
             HTTP = 80
    EOT
       remsh = rsh
       ifs = net0
       fss = / /usr /var /home /home2

    # Sun Solaris 8
    [sun]
       ostype = solaris
       desc = Sun Solaris 8
       TCP_services =<<EOT
             telnet = 23
             SSH = 22
             FTP = 21
             SMTP = 25
             HTTP = 80
    EOT
       fss = / /usr /home

    # Red Hat Linux 9
    [rhlinux]
       ostype = linux
       desc = Red Hat Linux 9
       TCP_services =<<EOT
             SSH = 22
             HTTP = 80
    EOT
       fss = / /usr

    # FreeBSD 5
    [mailsrv]
       ostype = freebsd
       desc = FreeBSD 5
       TCP_services =<<EOT
             SSH = 22
             FTP = 21
             DNS = 53
             SMTP = 25
             POP3 = 110
             HTTP = 8080
    EOT

    # MS Windows 2000
    [mswin2000]
       ostype = mswin2k
       desc = MS Windows 2000
       TCP_services =<<EOT
             FTP = 21
             SMTP = 25
             HTTP = 80
    EOT

    ###############################
    ## PROGRESS database servers

    # PROGRESS database prodb1 on sun
    [sun:prodb1]
       dbname = test
       dbdesc = Test database
       dbactive = yes

    #####################################################################
    ## Default settings for UNIX servers and PROGRESS database servers

    [:default:]

    # Default OS type [undefined]
      ostype = undefined

    # Default host description
      desc = no description

    # Default host state [active]
      active = yes

    # Default list of TCP services to be monitored [none]
      TCP_services =

    # Default protocol for 'ping': one of tcp, udp, icmp [tcp]
      pingmode = tcp

    # Default timeout for 'ping' [2 sec]
      timeout = 2

    # Should a UNIX sysadmin be alerted by email when UNIX server is down? [no]
      email = no

    # Default remote shell to access a remote host: rsh, ssh, etc [ssh]
      remsh = /usr/local/bin/ssh

    # Default sampling interval for a UNIX server [10 sec]
      interval = 10

    # Default list of network interfaces to be monitored [none]
      ifs =

    # Default list of UNIX file systems to be monitored [root file system only]
      fss = /

    # Default database type [PROGRESS]
      dbtype = PROGRESS

    # Default database name [dbname]
      dbname = dbname

    # Default database description
      dbdesc = PROGRESS database

    # Default state of a database server [active]
      dbactive = yes

    # Additional PROGRESS session parameters [-T /tmp]
      dbparams = -T /tmp

    # Should a DBA be alerted by email when database server is down? [no]
      dbemail = no

    # Default sampling interval for a database server [10 sec]
      dbinterval = 10

    # Default templates for the email notifications
      MAIL =<<EOT
             From = Websmon System Monitor <websmon@localhost>
             To   = System Administrator <root@localhost>
             CC   =
             BCC  =
             X-Mailer = Mail::Sendmail
             Subject = %host:%service is down
             Message = %host:%service is down on %date at %time
    EOT

    # Environment variables
      ENV =<<EOT
            DLC = /usr/dlc
            PROMSGS = /usr/dlc/prolang/ame/promsgs.ame
            PROTERMCAP = /usr/dlc/protermcap
            TERM = ansi
    EOT

    ######################
    ## Graphs settings

    [:graph:]

    # Width of the graphs (X size) [400]
    # width = 400

    # Height of the graphs (Y size) [100]
    # height = 100

    # Graphs colors: font is black, bold is red, background is grey, major grid and
    #     frame are black, arrow head and error text are red, vertical ruler is red
    # colorFont = 000000
    # colorBold = 0000ff
    # colorBG   = f5f5f5
    # colorMgrid = 000000
    # colorFrame = 000000
    # colorArrow = ff0220
    # colorError = ff0220
    # colorVrule = ff0000

    # Graphs colors: 1st line is green and 2nd line is blue,
    #                3rd line is yellow, 4th line is violet
    # Maxima lines: 1st is dark green, 2nd is navy blue
    # color1 = 00cc00
    # color2 = 0000ff
    # color3 = ffaa00
    # color4 = ff00ff
    # color1max = 077727
    # color2max = 077c77

    # Graphs orientation: [vertical]
      layout = square

    ######################
    ## Bars settings

    [:bar:]

    # Width of the bars being created (X size) [202]
    # width = 202

    # Height of the bars being created (Y size) [9]
    # height = 9

    # Bars border color: black
    # colorBorder = 000000

    # Bars colors: CPU utilization bars
    #     default: blue on light blue, light yellow on light blue, red on pink
    # colorCPU = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

    # Bars colors: memory utilization bar
    # colorMem = 0000ff:8fffff:98:ffff00:8fffff:99:ff0000:ffc0c0

    # Bars colors: swap space utilization bar
    # colorSwap = 0000ff:8fffff:80:ffff00:8fffff:90:ff0000:ffc0c0

    # Bars colors: filesystem utilization bar
    # colorFS = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

    # Bars colors: database space utilization bar
    # colorDBsize = 0000ff:8fffff:97:ffff00:8fffff:99:ff0000:ffc0c0

    # Bars colors: database cache hits bar (inverted color map)
    # colorDBhits = ff0000:ffc0c0:90:ffff00:8fffff:95:0000ff:8fffff

    # Bars colors: database cache utilization bar (inverted color map)
    # colorDBbufs = ff0000:ffc0c0:75:ffff00:8fffff:80:0000ff:8fffff

    # Bars colors: database locking table utilization bar
    # colorDBlocks = 0000ff:8fffff:90:ffff00:8fffff:95:ff0000:ffc0c0

    # Bars colors: PROGRESS APW utilization bar (inverted color map)
    # colorAPW = ff0000:ffc0c0:50:ffff00:8fffff:75:0000ff:8fffff

    # Bars colors: PROGRESS BIW utilization bar (inverted color map)
    # colorBIW = ff0000:ffc0c0:75:ffff00:8fffff:90:0000ff:8fffff

    # Bars colors: PROGRESS AIW utilization bar (inverted color map)
    # colorAIW = ff0000:ffc0c0:75:ffff00:8fffff:90:0000ff:8fffff

    ######################
    ## System settings

    [:system:]

    # Directory where all Websmon flag and lock files reside [/tmp/websmon]
    # flagdir = /tmp/websmon

    # Websmon log file (- means STDOUT) [/home/websmon/websmon.log]
    # logfile = /home/websmon/websmon.log

    # Directory where .csv and .rrd statistic data files reside [/home/websmon/stats]
    # statdir = /home/websmon/stats

    # Polling interval for wmgather [5 minutes]
      polling_interval = 5

    # Refresh time for main Websmon page [30 sec]
    # refresh = 30

    # Colors of Websmon pages
    # bg_color = fff6f0
    # text_color = 000000
    # value_color = 0000ff
    # alink_color = ff00ff

    # Background image for Websmon pages (remove this if you want no background images)
      background = bg4.jpg

    # Charset of web pages being created [ISO 8859-1]
    # charset = iso-8859-1

    # List of SMTP mail servers (mail_server_name[:port] ...) [localhost]
      MailServers = mailsrv localhost

    # Should the current UNIX host information be presented on the web pages?
      UNIX_info = on

    ###########################
    ## Registration settings

    [:license:]

    # Registration code
      RegCode = $9BFF-09230-5CE6E-FAFBB-F7BE2

### 4.9. How to add a definition for a new host.

To define a new host in the configuration file websmon.ini, append the new section to the file (i.e., specify the host name), for instance:

        [new_host_name]

Then specify the type of the operating system running on the server using the parameter ostype (by default, its value is undefined):

        [new_host_name]
         ostype = solaris

If omitted, all other parameters will be taken from the section [:default:]. However, it is useful to specify the host definition string using the parameter desc:

        [new_host_name]
         ostype = solaris
         desc = A Sun Solaris server

### 4.10. How to add a definition for a new PROGRESS database.

You can add the definition for the database if the host for the db server is already defined in the configuration file. Otherwise, you have to add the definition for the host first (see p.4.9).

To define a new database server in the configuration file, append a new section with the section name consisting of the name of the host, a colon, and the known TCP service name used for connecting to the database. Of course, the TCP service name should be defined somewhere in the system, usually in the file /etc/services.

Also, you have to define the name of the database using the parameter dbname, for instance:

        [host_name:proservice1]
         dbname = testdb1

If omitted, all other parameters will be taken from the section [:default:]. However, it is useful to specify the database definition string using the parameter dbdesc.

Note: In the configuration file, the section for a database server should go after the section for the host on which the database server is running, for instance:

        [host_name]
         ostype = linux
         desc = Dell server under RHEL AS 3.0

        [host_name:proservice1]
         dbname = testdb1
         dbdesc = Test database

### 5. Description of the statistic data files being created by the monitor.

The statistics collecting system wmgather creates the CSV data files and then updates the statistics database stored in the RRD format. These files are located in the following directories:

/home/websmon/stats/SERVER contains the statistics collected from the UNIX server SERVER
/home/websmon/stats/SERVER/SERVICE contains the statistics collected from the PROGRESS database running on the host SERVER through the TCP service SERVICE

The CSV file names are constructed from the month and year of creation in the form YYYYMM, for instance, the file name 200401.csv means statistics collected in the January of 2004.

More information on the Round Robin Database (RRD) databases including the detailed description of the formats you will find here: /home/websmon/rrdtool/doc/rrdtutorial.txt

### 5.1. CSV files containing UNIX server statistics.

The format of CSV files containing UNIX servers statistics is as follows:

     # Comment - UNIX server name, month and year of collecting data
      # Comment - list of the CSV fields names

List of the fields of a CSV record:

1. Report timestamp, date part in the form of dd/mm/yy
2. Report timestamp, time part in the form of HH:MM:SS
3. UNIX server uptime in seconds
4. Number of logged UNIX users in the system
5. 1-minute server load average
6. 5-minute server load average
7. Server CPU load: %usr part
8. Server CPU load: %sys part
9. Server CPU load: %wio part
10. Server CPU load: %idle part
11. Total size of the server RAM, K bytes
12. Free memory, K bytes
13. Total size of the disk swap space, K bytes
14. Free swap space, K bytes
15. System I/O activity: system read rate, block per second
16. System I/O activity: system write rate, block per second
17. System paging: paging in rate, page per second
18. System paging: paging out rate, page per second
19. System swapping: swapping in rate, block per second
20. System swapping: swapping out rate, block per second
21. Number of processes running in the system
22. System context switching rate, switch per second
23. System semaphores operation activity, semaphore per second
24. System message queues operation activity, message per second
25. Network I/O statistics as follows:

                  IF1=rx:tx:ierr:oerr IF2=rx:tx:ierr:oerr ...

    Here IF1, IF2, etc are the names of network interfaces,
    rx - incoming traffic on the interface, packets
    tx - outgoing traffic on the interface, packets
    ierr - number of incoming errors occured on the interface
    oerr - number of outgoing errors occured on the interface
    Example:

                  eth0=456720:445767:0:0 lo=24192:24192:0:0

26. Server file system usage in the following format:

                  /fs1=sizeK:freeK:inodes:ifree /fs2=sizeK:freeK:inodes:ifree ...

    Here /fs1, /fs2 ... are the file system names,
    sizeK - total file system size, K bytes
    freeK - free space left on the filesystem, K bytes
    inodes - total number of inodes
    ifree - free inodes left
    Example:

                  /=2023952:556092:257536:204506 /usr=6158948:2577944:783360:616935

### 5.2. RRD files containing UNIX server statistics.

Along with CSV data files containing the system statistics gathered from specified UNIX servers, the wmgather system of the Websmon monitor creates and then updates the corresponding statistics database stored in the RRD format.

This database consists of the following files:

| cpusys.rrd |  | - %sys CPU, %total (%sys+%usr+%wio) CPU
| cpuusr.rrd |  | - %usr CPU, %total CPU
| cpuwio.rrd |  | - %wio CPU, %total CPU
| cswitch.rrd |  | - system context switches, switch per sec
| fs%.rrd |  | - root filesystem: used filesystem space in K, total filesystem size in K
| in%.rrd |  | - root filesystem: used inodes, total number of inodes
| fs%usr.rrd |  | - /usr filesystem: space
| in%usr.rrd |  | - /usr filesystem: inodes
| fs%_FILESYSTEM.rrd |  |
| in%_FILESYSTEM.rrd |  | - and so on for each filesystem listed in the configuration file websmon.ini
| neterrs.rrd |  | - total of network errors: incoming errors, outgoing errors
| network.rrd |  | - total of network traffic: incoming and outgoing traffic, pkt/s
| iferr_eth0.rrd |  | - network errors on 'eth0': incoming errors, outgoing errors
| if_eth0.rrd |  | - network traffic on 'eth0': incoming and outgoing traffic, pkt/s
| iferr_ppp0.rrd |  | - network errors on 'ppp0': incoming errors, outgoing errors
| if_ppp0.rrd |  | - network traffic on 'ppp0': incoming and outgoing traffic, pkt/s
| iferr_NETWORK_INTERFACE.rrd |  |
| if_NETWORK_INTERFACE.rrd |  | - and so on for each network interface listed in the configuration file websmon.ini
| io.rrd |  | - system I/O: system reading activity rate, blk/s, system writing activity rate, blk/s
| load.rrd |  | - server load averages: 1-minute averages, 5-minute averages
| memory.rrd |  | - server memory: used memory in K, total memory in K
| message.rrd |  | - kernel message queues activity, msg/s
| paging.rrd |  | - system paging: paging in and paging out rates, page/s
| process.rrd |  | - number of running processes
| semaphore.rrd |  | - kernel semaphores activity, sema/s
| swapping.rrd |  | - system swapping: swapping in and swapping out rates, blk/s
| swap.rrd |  | - disk swap space: used swap space in K, total swap space in K
| uptime.rrd |  | - server uptime, seconds
| users.rrd |  | - number of logged users

### 5.3. CSV files comtaining PROGRESS database statistics.

The format of CSV files containing PROGRESS databases statistics is as follows:

     # Comment - database name, host name, month and year of collecting data
      # Comment - list of the CSV fields names

List of the fields of a CSV record:

1. Report timestamp, date part in the form of dd/mm/yy
2. Report timestamp, time part in the form of HH:MM:SS
3. Database server uptime in seconds
4. Number of the non-batch database clients connected
5. Number of the batch database clients connected
6. Number of the self-serving (SELF) database clients connected
7. Number of the remote (REMC) database clients connected
8. Number of the additional database servers (SERV) running
9. Total database size in blocks
10. Number of the free blocks
11. Number of the empty blocks
12. Total BI file size, K
13. BI cluster size, K
14. Number of the closed BI clusters
15. Free space in the currently used BI cluster in bytes
16. Total AI file size, K (0, if only fixed-length AI extents are used)
17. AI extent generation number (for fixed-length AI extents)
18. Database data block size, K
19. Database BI block size, K
20. Database AI block size, K
21. Total number of buffers in the database buffer pool (database cache size)
22. Number of used buffers in the buffer pool
23. Total number of logical read requests from the database (total values here and after mean the values accumulated since the last database open, i.e., since starting the database broker)
24. Total number of OS read requests
25. Current database cache hit ratio in %% (current values here and after mean the momentary values got from the last database sampling interval, that is by default 30 seconds)
26. Total number of the database blocks read
27. Total number of the database blocks written
28. Current database block reading rate, block per second
29. Current database block writing rate, block per second
30. Total number of the BI blocks read
31. Total number of the BI blocks written
32. Current BI block reading rate, block per second
33. Current BI block writing rate, block per second
34. Total number of the AI blocks written (number since enabling After Imaging subsystem)
35. Current AI block writing rate, block per second
36. Current rate of the database transactions committed, transaction per second
37. Current rate of the database transactions undone, transaction per second
38. Current database record reading rate, record per second
39. Current database record creation rate, record per second
40. Current database record updating rate, record per second
41. Current database record deletion rate, record per second
42. Total number of the database writes
43. Total number of writes performed by PROGRESS APWs
44. Current PROGRESS APW using rate, %%
45. Total number of BI writes
46. Total number of BI writes performed by PROGRESS BIW
47. Current PROGRESS BIW using rate, %%
48. Total number of AI writes
49. Total number of AI writes performed by PROGRESS AIW
50. Current PROGRESS AIW using rate, %%
51. Number of PROGRESS APW running
52. Number of PROGRESS BIW running (that is, 0 or 1)
53. Number of PROGRESS AIW running (that is, 0 or 1)
54. Total number of the database checkpoint operations that have been performed since the database open
55. Start time of the most recent database checkpoint
56. End time of the most recent database checkpoint
57. Number of the modified (dirty) database buffers scheduled to be written before the end of the last checkpoint
58. Number of flushed blocks that were not written during the last checkpoint and that had to be written all at once at the end of the checkpoint
59. System database locking table size
60. Number of database record locks currently in use
61. Number of database record locks used since database open
62. Number of times users have waited for shared and exclusive locks on the database buffers
63. Number of times users have waited to access a locked database record
64. Current reading rate of database data blocks, block per second
65. Current writing rate of database data blocks, block per second
66. Current reading rate of database index blocks, block per second
67. Current writing rate of database index blocks, block per second
68. Current database index creation rate, index per second
69. Current database index deletion rate, index per second
70. Current database index finding rate, index per second
71. Number of waits for busy BI buffers
72. Number of waits for empty BI buffers
73. Number of waits for busy AI buffers
74. Total number of waits for AI buffers
75. Request rate for exclusive locks, request per second
76. Granting rate for exclusive locks, lock per second
77. Number of times processes waited for exclusive lock
78. Request rate for share locks, request per second
79. Granting rate for share locks, lock per second
80. Number of times processes waited for share lock
81. Request rate for record get locks, request per second
82. Granting rate for record get locks, lock per second
83. Number of times processes waited for record gets

### 5.4. RRD files containing PROGRESS database statistics.

Along with a CSV data file containing the system statistics gathered from a specified PROGRESS database, the wmgather system of the Websmon monitor creates and then updates the corresponding statistics database stored in the RRD format.

This database consists of the following files:

| activity.rrd |  | - transactions committed, transactions undone in transaction per second
| aiextnum.rrd |  | - AI extent generation number
| aiio.rrd |  | - AI block writing rate, block per second
| aisize.rrd |  | - AI size, bytes
| aiwait.rrd |  | - number of busy AI buffers waits, total AI buffers waits
| aiw.rrd |  | - AI writes performed by AIW, % (current / cumulative values)
| apw.rrd |  | - DB writes performed by APW, % (current / cumulative values)
| biio.rrd |  | - BI block I/O rates, block per second
| bisize.rrd |  | - BI size, bytes
| biwait.rrd |  | - number of busy BI buffers waits and empty BI buffers waits
| biw.rrd |  | - BI writes performed by BIW, % (current / cumulative values)
| cachebufs.rrd |  | - number of used buffers, total number of db cache buffers
| cachehits.rrd |  | - db cache hit ratios (current / cumulative values)
| checkpoint.rrd |  | - number of flushed blocks, number of dirty blocks
| dataio.rrd |  | - database data blocks I/O rates, block per second
| dbio.rrd |  | - database I/O rates, block per second
| dbread.rrd |  | - database data and index blocks reading rates, block per second
| dbremc.rrd |  | - number of REMC database connections, total db connections
| dbself.rrd |  | - number of SELF database connections, total db connections
| dbserver.rrd |  | - number of database SERVers runnning, REMC db connections
| dbsize.rrd |  | - used database space in bytes, database size in bytes
| dbuptime.rrd |  | - database uptime in seconds
| dbusers.rrd |  | - user database connections, total (user+batch) db connections
| dbwrite.rrd |  | - database data and index blocks writing rates, block per second
| indexc.rrd |  | - database index creation rate, index per second
| indexd.rrd |  | - database index deletion rate, index per second
| indexf.rrd |  | - database index finding rate, index per second
| indexio.rrd |  | - database index blocks I/O rates, block per second
| locktable.rrd |  | - number of record locks currently in use, locking table size
| naiw.rrd |  | - number of PROGRESS AIW running (that is, 0 or 1)
| napw.rrd |  | - number of PROGRESS APW running
| nbiw.rrd |  | - number of PROGRESS BIW running (that is, 0 or 1)
| recc.rrd |  | - database record creation rate, record per second
| recd.rrd |  | - database record deletion rate, record per second
| recr.rrd |  | - database record reading rate, record per second
| recu.rrd |  | - database record updating rate, record per second
| recwait.rrd |  | - number of waits for locked database records

### 6. Error messages produced by the monitor.

All messages created by the monitor are stored in the monitor log file websmon.log which locates at the /home/websmon directory.
The log file is archived on a regular basis by the shell script wmzip.

Certain UNIX system error messages (e.g., those produced by the cron daemon) may be sent to the local email address of user websmon.
To read these messages, you can the UNIX command mail (or the command su root -c "mail -u websmon", if you are logged in not as the user websmon).

The messages on the failures of the hosts, TCP sercices, and PROGRESS databases are sent by the wmwatch system of the monitor to the email addresses specified in the configuration file (see the configuration parameters email and dbemail).

The error messages produced by the Apache HTTP server (which is used by the wmshow system) are stored in the log file of the HTTP server /home/websmon/apache/logs/error_log

### 7. Appendix.

A short description of the files resided in the /home/websmon/misc directory:

| apache.conf |  | - List of the Apache HTTP server configuration file httpd.conf directives required by the Websmon monitor in order to work properly (for instance, it contains the directory and script aliases and the icons directory path for the wmshow and wmbar Web applications)
| crontab |  | - A prototype of the user websmon's crontab file
| profile |  | - Settings required for the .profile file of the user websmon
| websmon.ini |  | - A sample configuration file of the Websmon monitor

uw7_top.tgz

- A top utility (an executable for the SCO UnixWare 7.1 operating system) required by the monitor for gathering the UNIX system statistics from the servers running SCO UnixWare (particularly, for the server load averages data).
You need to install this utility on the remote servers running SCO UnixWare 7 for which the performance statistics is being gathered (unless of course top already exists somewhere in the system), otherwise you will not have the server load average statistics being gathered (but note that all other statistics data will be gathered as usual).
The top utility should be installed to the /usr/local/bin directory on the servers using the following command:
cd / ; su root -c "gzip -cd uw7_top.tgz | tar xvf -"

aix_top.tgz

- A top utility (an executable for the IBM AIX 4.2 operating system) required by the monitor for gathering the UNIX system statistics from the servers running IBM AIX (particularly, for the disk swap space utilization data).
The top utility should be installed to the /usr/local/bin directory on the servers using the following command:
cd / ; su root -c "gzip -cd aix_top.tgz | tar xvf -"

PROGRESS © is a trademark of the Progress Software Corporation