SysPage -- HTML Server Tool

SysPage is a daemon process for OS/2 which can

  1. write HTML page(s) containing intermediate and long term performance/usage information for an OS/2 system, with as low an overhead as possible.
  2. log process start, stop, and user-defined events to HTML or disk.
  3. optionally accept authorized commands from the WEB and display output

Legal Issues

 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
 * THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

How to Get Started

There is a single argument to the program: the path to a file which contains configuration information for SysPage and the templates for the desired HTML.

The file consists of sections headed by the brackets "[<" in the first position of a new line, enclosing the section name with ">]". The names of these sections are pre-defined by SysPage, although their relationship to displayed variables and row definitions may be re-defined by the user. The currently supported section names are: Config, Commands, IPL, Process, Module, Log, Aux1, and Aux2. The first two sections contain parametric information and the others contain HTML source interspersed with symbolic variables.

Configuration Section

[<Config>]

The configuration section will accept lines beginning with a '#' sign as comments. Blank and empty lines are ignored. This section is NOT reloaded during execution; the program must be cycled to effect any changes. Items in the configuration section are of the form 'Keyword = value'. The following are the recognized keywords:


Commands Section

Commands which may be executed through the defined command-port by a CGI program (the source for sysphmsg.c is in the disribution). This section allows comment lines with a leading '#' sign. Each line in this section defines a program or internal command. There are four tokens to a line when defining an external command, and only two tokens for a Syspage internal command.
Command Verb
The string used to identify this function in the VALUE clause of an HTML INPUT statement with NAME 'CMDVERB'.
Authorization Group
The auth-group where this command belongs. These names are assigned with the Command_IPs parameter.
Command Path
The full file path to the executable, including the .EXE suffix.
Log attribute
Required but currently ignored; must be LOG or NOLOG.

You will need to compile (and modify for your site requirements) the CGI program sysphmsg.c included in the distribution.

HTML Sections

Other sections are basically HTML page text containing symbolic variables to be substituted. These variables are prefixed with the string "%&" or "%%". "%%" is used to denote an OS/2 environment variable. Variables which are part of table rows are pre-defined for those rows. These variables are case-insensitive. Output Path is the full path specification for HTML output from this section. These keywords are case insensitive. The realationship of HTML sections and table rows is basically at the discretion of the user. Most of the sections have names which suggest the table row which they might contain. This is not hard and fast.

The Report_Interval parameters designated indicate an integer value specifying the number of Peek_Intervals between generations of that report. For the IPL report, the value is required but ignored.

The Output_Path strings designated below should probably point into the same directory. This directory would greatly benefit from being on a RAM (VDISK.SYS) or Virtual Disk (Albert Shan's SVDISK.SYS) for low overhead. I've been running mine out via NFS to a Linux directory soft-linked into the Apache Document path.


Other variables are available for any one of the pages, but are recomputed and reformatted for each request:

The variable '%&reload' is evaluated depending on the HTML file that is being processed. It returns the millisecond value of the corresponding configuration variable. For the Module section, it returns Module_Interval * ( Peek_Interval * 100 ); for the Process section, it uses Process_Interval * ( Peek_Interval * 100 ).

Environment variables are substituted at program start and identified with a '%%' prefix, i.e., %%hostname, %%tz.

Table Definitions

Table definitions are 'special' symbolic variables for which an entire set of rows is substituted. The symbol must begin in the first column of an HTML template line. Available tables are Partitions, Modules, Processes, Ldevices, LogTable, and Units. The table row data will ordinarily be refreshed during the corresponding report generation cycle.

Units

"%&Units" represents the physical hard drive units present at boot time. The sub fields are:

Partitions

"%&Partitions" represents the entire table row, and the subfields "%&PhysDisk", etc. the request for and order of the subfields. So, the entire "Partitions" entry must be given, with as many subfields as desired, in their desired order. Here are the members of the Partitions group.

Processes

The "%&Processes" table has the following entries:

The "%&Ldevices" table has the following entries:

Modules

The "%&Modules" table has the following entries:

All these entries may represent multiple invocations of the module.

TotElapsed has the granularity of the Peek_Interval.

Aux1 and Aux2 Tables

The AUX1 and AUX2 page definitions may contain any symbolic, environment, or table row variables that the user requires to be in a separate page.

Log

The "%&LogTable" table row has the following entries:


The Logtable set of rows has some special features. If you are using the Log_Port option and sysplogp to supply SYSLOG entries to the log, and especially if you have defined Log_Port as 514 and are collecting all SYSLOG output via SysPage/2, the field "LOGEVENT" will contain the SYSLOG tag field; the field "LOGMODHANDLE" will contain the SYSLOG priority value. If 'TAG=' was specified on the 'sysplog' invocation, the issuing PID will be available in "LOGPID" otherwise blanks will be supplied.

FileDir[path-info]

The "%&FileDir" table row has the following entries:


The FileDir row requires additional syntax. The template line should start with %&FileDir[x:\complete\path\to\dir\*] if all the files of a given directory are desired, or with an exact path if only one file is desired. Wildcards are permitted as with the DosFindFirst API. Don't forget the open and close brackets for this file specification.

Attention Routine

If SysPage is started in a text window, entering a Ctrl-C into this window will obtain the attention of a routine which accepts command lines. SysPage will continue to collect data and emit HTML while the user interacts with it in this way. When the Attention Routine is activated, it will display some of its single-character options and their meanings. The Attention Routine functions are:

The 'R'eload function should also refresh the entries in the Command section.

The 'M' request will display some internal information about the threads controlled by the Schedule subsystem. The thread ID is given as 'TID', followed by state which should be 'Running' or 'Waiting'. This is from Schedule's point of view; i.e., 'Running' means that some piece of work is currently scheduled to run on this thread. The thread itself may be waiting for a system event. So the Attention and UDP Ports tasks will generally appear to be 'Running'. The 'Attention' task actually is running since it is producing the task list.

Diagnostics

To obtain the ID string for the version that you have, execute SYSPAGE.EXE without any argument. This will display usage and version. SysPage is linked with some routines which attempt to write a post-mortem dump file containing context information, stack, and heap. The debug version of the program corresponds to the large shipped SYSPAGE.MAP file. Should a program exception occur, these routines will attempt to write a file named like 'M2DUMP.nnn' in your SPOOL directory; i.e., the directory defined in System-Setup->Spooler under the tab Spool Path. If at all possible, obtain this file as produced by the debug version. The production version will produce a dump, but the SYSPAGE.MAP shipped in the product.zip package will only give general offsets within object segments. Please ZIP the dump file and corresponding map file for whatever version was in use at the time of the error, and email it to sbsbugs@dashs.denver.co.us

Using the 'G' Attention Routine command, you can peek at the memory usage of the program. This should tend to level off at some point. There probably exists some leakage in the area of HTML-reload which has not yet been addressed.