NAME

POE::Component::GCS::Server::Cfg - Generic network server config

VERSION

This document describes version 0.09, released February, 2010.

SYNOPSIS

# Server usage - used indirecly to configure server during startup

use POE::Component::GCS::Server;
$configFile = "/path/to/GCS/config/file";
exit( run POE::Component::GCS::Server( $configFile ) );

# Client usage - used to obtain port number(s) of a running server

use POE::Component::GCS::Server::Cfg qw( client );   # client flag

$configClass = "POE::Component::GCS::Server::Cfg";
$configFile  = "/path/to/GCS/config/file";
$config   = $cfgClass->new( $cfgFile );     # will skip loadLibs()
$msgPort  = $config->get('MsgPort');        # '0' when not in use
$txtPort  = $config->get('TxtPort');        # '0' when not in use

DESCRIPTION

This class is used to start a generic network server daemon. To cleanly shutdown the server, send a SIGTERM to the process ID.

Client scripts may use this module to obtain the current server port number(s) for running services. However, in this case, add the string 'client' to the 'use' statement, as shown above, to avoid loading all of the additional server classes.

Constructor

new ( [ ConfigFile ] )

This creates a new generic server configuration object. Note that the object created is implemented as a 'singleton', meaning that any subsequent calls to this method will return the original object created by the first call to this method.

The optional ConfigFile parameter can be added to specify an external file used to configure a the server. When used, this is expected to be either a full or relative path to the file.

Methods

configEnv ( )

Configure the server Environment Variables.

configLibs ( )

Configure the server library modules (components).

loadLibs ( )

Include all of the server library modules (components). This should be skipped when using this module in client scripts, for example to obtain the port number(s) of a running server. See the Synopsis section, above, for the correct client syntax.

configVars ( )

Configure defaults for server variables.

configFile ( [ ConfigFile ] )

Load locally customized defaults from an external data file. This is expected to be either a full or relative path to the file.

Config File Format

The format of the external configuration file, available to allow local customization to the server consists of a Perl 'hash' data structure. The configurable possibilites include the following.

# File:  conf/gcs/gcs.conf
{ 
   LogLevel    => 3,
   LogFile     => 'server.log',
   PidFile     => 'server.pid',
   UidFile     => 'uidgid.dat',

   MsgPort     => 0,
   TxtPort     => 23457,

   ProcMax     => 5,
   QueueMax    => 0,

   Uid         => 0,
   Gid         => 0,
 # Uname       => '',
 # Gname       => '',

   PathEnv     => '/bin:/sbin:/usr/bin/:/usr/sbin',
   QueueIdEnv  => 'GCS_RESOURCE_ID',
   CfgErrFatal => 'no',

   CfgClass    => "POE::Component::GCS::Server::Cfg",
   CmdClass    => "POE::Component::GCS::Server::Cmd",
   LogClass    => "POE::Component::GCS::Server::Log",
   MsgClass    => "POE::Component::GCS::Server::Msg",
   ProcClass   => "POE::Component::GCS::Server::Proc",
   QueueClass  => "POE::Component::GCS::Server::Queue",
   TaskClass   => "POE::Component::GCS::Server::Task",
   TcpClass    => "POE::Component::GCS::Server::TCP",
}

Config File Variables

LogLevel

The default logging level for the server daemon. If no entry is made in this file, the default value is 3. This can be overridden during debugging by starting the server with the '-D [<n>]' command-line option.

In addition there are three other server command-line options that effect GCS server logging. These are handy when you temporarialy want additional information added to the GCS server log. As this can get rather verbose, and is not always useful information, it is usually best to leave the logging value set to a low number.

-logincr           # increment current logging level
-logdecr           # decrement current logging level
-logreset          # reset logging level to default

Note that the minimum logging level currently available is 3.

LogFile

Location of the GCS server daemon's log file.

PidFile

Location of the GCS server daemon's pid file. This is used for two purposes. One, when starting a GCS server, to ensure that only one server process runs at a time, and two, when using the GCS server startup script to signal a running server. Use the '-h' (--help) command-line option to see the available signal options.

UidFile

Location of the GCS server daemon's 'UidGid' file. This file is optional. When used, this file will contain one line with a numeric uid, a colon, and a numeric gid (nnnnn:nnn).

Also see the 'Uid' and 'Gid' parameters, below.

MsgPort

Port number on which to start a Message-based connection. All client communication on this port is expected to be an object of the POE::Event::Message class, or a subclass thereof.

See POE::Component::GCS::ClientMsg as one example of a Message-based client class, and see POE::Component::GCS::Server::Msg as an example of subclassing the 'POE::Event::Message' class.

Note: One of 'MsgPort' or 'TxtPort' must be used or, when the server is started, it will simply exit as there is no port on which to listen.

TxtPort

Port number on which to start a Message-based connection. All client communication on this port is expected to be plain text.

See 'POE::Component::GCS::ClientTxt' as one example of a Text-based client class.

Note: One of 'TxtPort' or 'MsgPort' must be used or, when the server is started, it will simply exit as there is no port on which to listen.

Uid

Uname

If you wish to ensure that the GCS server daemon runs as a specific user, enter one or the other of a numeric Uid or string Uname value, but not both.

These are optional. See the 'UidFile' parameter, above.

Gid

Gname

If you wish to ensure that the GCS server daemon runs as a specific group, enter one or the other of a numeric Gid or string Gname value, but not both.

PathEnv

It is a good idea to limit the PATH Environment Variable when starting a daemon process. Enter a limited set of paths here. If no entry is specified, the default is as follows.

/bin:/sbin:/usr/bin/:/usr/sbin

CfgErrFatal => 'no',

It is possible to 'reconfigure' a running GCS server daemon. Edit the server config file, then use the '-reconfig' command-line option of the server startup command.

When using the '-reconfig' option, if errors are detected in the config file, this flag determines what should happen. When this flag is set to any 'true' value, reconfig errors will cause the daemon to terminate. When this is set to any 'false' value, any errors are ignored and the current config value(s) are retained.

ProcdMax

Specifies the maximum number of child processes that can run concurrently. When tasks in the queue exceed this number, they will remain in the queue and, as running child procs exit, they will be allowed to run based on the priority value used when added to the queue.

Default value is 5.

QueueMax

Specifies the maximum number of tasks that can be queued. When additional requests to queue tasks are received, the message for that task is set to an error status, and a 'Job queue is full' error.

Default value is 0, meaning unlimited.

QueueIdEnv

This one is a little esoteric. It is possible, when controlling some limited number of child process to 'multi-process' a task, that you will want to correlate each child process to a unique external resource.

To make this possible, an Environment Variable will be set in each child process to a unique 'Queue Slot' value. Say for example that the GCS server is configured to only allow 5 concurrent child processes. Each running child will have an EV set in the range '[0..4]' which is guaranteed to be unique for each concurrent child process. The default value for this variable is shown here.

GCS_RESOURCE_ID

This way, when a specific child process is a script or module that you create, it can map this EV to the external resource that is available for its use. Clear as mud? See a longer comment in the source code for the 'POE::Component::GCS::Server::Proc' class.

DEPENDENCIES

None currently. An external configuration file is optional.

SEE ALSO

For discussion of the generic server, see POE::Component::GCS::Server.

For an example of client usage, see POE::Component::GCS::Client.

AUTHOR

Chris Cobb, <no spam [at] ccobb [dot] net>

COPYRIGHT

Copyright (c) 2005-2010 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.