The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
VBTK-0.20
River stage zero No dependents
++
/ VBTK::Server

NAME

VBTK::Server - Main server process for the VBTK toolkit

SYNOPSIS

Note that defining a VBTK::Server makes use of several modules. A typical configuration would look something like this:

  use VBTK::Server
  use VBTK::Actions::Email
  use VBTK::Actions::Email::Page

  # Setup email actions
  new VBTK::Actions::Email ( Name => 'emailMe',  To => 'me@mydomain.com' );
  new VBTK::Actions::Email ( Name => 'emailBob', To => 'bob@mydomain.com' );

  # Setup paging actions
  new VBTK::Actions::Email::Page ( Name => 'pageMe',  To => 'page.me@mydomain.com');
  new VBTK::Actions::Email::Page ( Name => 'pageBob', To => 'page.bob@mydomain.com');

  # Setup some action groups
  new VBTK::Actions ( Name => 'emailSA', SubActionList => 'emailMe,emailBob' );
  new VBTK::Actions ( Name => 'pageSA',  SubActionList => 'pageMe,pageBob,emailSA' );

  # Initialize a server object.
  $server = new VBTK::Server (
    ObjectPrefix => 'sfo',
    SmtpHost     => 'mysmtphost',
    MailFrom     => 'vbtk@settomydomain.com',
    CompanyName  => 'My Company',
    AdminEmail   => 'sysop@settomydomain.com',
  );

  # Point to another VB server with which we will exchange heartbeats
  # and relay requests
  $server->addRemoteServer(
    RemoteURI      => 'http://myotherserver:4712' );

  # Create templates to match up status change actions with objects

  # Critical objects, page and email
  $server->addTemplate (
    Pattern        => 'nyc.*http|mainserver.*ping',
    StatusChangeActions => { 
      Failed  => 'pageSA',
      Expired => 'pageSA',
      Warning => 'emailSA' } );

  # Everything else, just email
  $server->addTemplate (
    Pattern         => '.*',
    StatusChangeActions => { 
      Failed  => 'emailSA',
      Expired => 'emailSA',
      Warning => 'emailSA' } );

  # Start the server listening and handling requests.
  $server->run;

DESCRIPTION

VBTK::Server is the central process for the VBTK toolkit. It is used to define and start a vbserver daemon which gathers together, evaluates, and displays all the statuses, test data, and graphs of the various test programs. It uses the HTTP::Daemon module to provide an HTTP/1.1 server which is the access point for client processes to submit data and for users to view data.

The server process makes use of the VBTK::PHttpd and VBTK::PHtml modules. The entire user interface is written in PHTML (something I whipped up), and so can be easily customized by anyone who is familiar with HTML and PERL.

METHODS

The following methods are supported

$s = new VBTK::Server (<parm1> => <val1>, <parm2> => <val2>, ...)

The constructor passes many of it's parameters on in a call to VBTK::PHttpd. All of these parms will default to a useable value if not specified. This call initializes the daemon, but does not start it listening yet. The allowed parameters are:

LocalPort

The TCP port number on which the VBServer will start it's web server listening for requests. See VBTK::PHttpd. Defaults to the environment variable $VBPORT as explained in the VBTK manpage.

LocalAddr

The IP address to which the VBServer's web server will bind itself. If unspecified, it will bind itself to '*'. See "item_LocalAddr" in VBTK::PHttpd. (Defaults to undef)

ObjectDir

The directory in which object state is stored. (Defaults to $VBOBJ, see the VBTK manpage for more details)

DocRoot

The docRoot directory for the VBServer web server. (Defaults to $VBHOME/web)

ObjectPrefix

VBObject names which start with a '.' will have this pre-pended to it. This allows the use of the identical vb scripts in different zones. (Defaults to 'local'). It is strongly recommended that you specify an object prefix of your own. Do not use the same prefix on two different VBTK::Server instances or things will get very confusing.

ExternalUrl

When VBServer sends notification emails, it will use this value to form the URL which allows one-click access to the object. (Defaults to '$VBURI/status.phtml'. See the VBTK manpage for more details)

HousekeepingInterval

Number of seconds between housekeeping runs. Housekeeping includes executing pending actions, checking object expiration times, etc. (Defaults to 60)

SmtpHost

A string containing the hostname or IP to direct email to when triggering actions. This value is passed directly to the Mail::Sendmail package.

EmailFrom

A string used as the 'From' address when triggering actions which send email.

CompanyName

A string which will be shown in the web interface as the company name.

AdminEmail

A string containing an email address which will be shown in the footer of each page of the web interface as the vbtk admin.

UseWatchDog

A boolean (0 or 1) indicating whether to use a watchdog process to start the real server process. The watchdog process will re-start the server process if it dies for any reason. I haven't ever seen it just die, so I've never really used this, but it's there just in case. (Defaults to 0).

$s->addRemoteServer(<parm1> => <val1>, <parm2> => <val2>, ...)

The 'addRemoteServer' method is used to define additional VB servers with which the local VB server should maintain a heartbeat. The allowed parameters are:

HeartbeatObject

Defines the name of the VB object which will store the status of the heartbeat transmission on the remote server. (Defaults to '.<hostname>.hrtbt')

LocalHeartbeatObject

Defines the name of the VB object which will store the status of the heartbeat transmission on the local server. (Defaults to '.<hostname>.hrtbt')

RemoteURI

The URI of the remote VB server. (ie: 'http://remoteserver:4712') (Required)

DontShowMatrix

A boolean value (0 or 1) indicating whether the matrix from this remote server should be pulled and shown with the local server's matrix. A value of 1 means that it will not be shown. This is nice for pulling together all the statuses from all your slave servers into a single web page. (Defaults to 0)

$s->addTemplate(<parm1> => <val1>, <parm2> => <val2>, ...)

Templates are used to assign properties to VB objects based on patterns. This allows the assignment of expiration periods, status change actions, etc., based on how the objects are named. Template settings are only used if the corresponding values were not specified directly in the client-side object definition itself. The allowed paramters are:

Pattern

A string containing a perl pattern which will be used to match this template to a VBTK::Server object name. New objects are compared to each pattern sequentially, in the order that the templates were added. Once a match is found, the object will inherit the template settings.

    Pattern => '.*http.*',
ExpireAfter

A string containing a date or time expression used to indicate how long the server should allow the object to be idle before changing the status to 'Expired'. The expression will be passed to the Date::Manip library for evaluation, so you can put in almost any recognizable date or time expression. (ie: 1 day, 3 weeks, etc.)

    ExpireAfter => '10 min',
StatusHistoryLimit

A number indicating how many status change events to maintain in the history for this object. You can view history entries under the 'History' tab in the VBTK::Server web interface.

    StatusHistoryLimit => '20',
StatusChangeActions

A pointer to a hash, containing 'Status' => 'ActionList' pairs. These pairs will be used to determine which actions to trigger when the object changes to the specified status. For example:

    StatusChangeAction => {
        Failed  => 'pageMe,emailMe',
        Warning => 'emailMe' }

See the legend on the VBTK::Server web page for a list of valid statuses.

StatusUpgradeRules

A pointer to an array of strings containing expressions which define rules for upgrading the status based on repetition of a lower level status within a specified timeframe. The expression must be of the form:

Upgrade to <newStatus> if <testStatus> occurs <count> times in <time expression>

For example:

    StatusUpgradeRules => [
      'Upgrade to Failed if Warning occurs 2 times in 6 min' ]
Description

A text description which will be displayed for this object under the 'Info' tab in the VBTK::Server web interface.

    Description => qw( This object monitors the web server ),
$s->run(<returnAfter>)

This method starts up the server process. It will handle requests to the web interface for <returnAfter> seconds or forever if no <returnAfter> is specified. Don't specify a <returnAfter> value unless you have your own outer loop you need to run through periodically. Call it as the very last step in setting up your server.

CUSTOMIZING THE WEB INTERFACE

The document root for the built-in web server is in $VBHOME/web. There you will find '.phtml' and images files which make up the web interface. PHTML is an extension of standard HTML which makes use of <!--#perl tags to create dynamic HTML. See VBTK::PHtml for more details.

Customizing the web interface is quite simple if you know a little HTML and perl. Just look through the comments and code in the '.phtml' files and make changes as needed.

SEE ALSO

VBTK::Actions
VBTK::Controller
VBTK::PHttpd
VBTK::PHtml
HTTP::Daemon
Mail::Sendmail

AUTHOR

Brent Henry, vbtoolkit@yahoo.com

COPYRIGHT

Copyright (C) 1996-2002 Brent Henry

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation available at: http://www.gnu.org/copyleft/gpl.html

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.