NAME
POE::Component::GCS::Server::Cfg - Generic network server config
VERSION
This document describes version 0.07, released June, 2006.
SYNOPSIS
use POE::Component::GCS::Server::Cfg;
exit( run POE::Component::GCS::Server( $configFile ) );
DESCRIPTION
This class is used to start a generic network server daemon. To cleanly shutdown the server, send a SIGTERM to the process ID.
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 (include) the server library modules (components).
- 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.
AUTHOR
Chris Cobb, <no spam [at] ccobb [dot] net>
COPYRIGHT
Copyright (c) 2005-2007 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.