ExSite::Config - ExSite configuration file

Config.pm contains general configuration parameters, site-specific setup data, and global variables used throughout the ExSite system.

This file is designed so that it never has to be modified. To set configuration variables, use an ``exsite.conf'' file, which will be loaded automatically, overriding the presets below. Handlers and custom setup routines can be defined in the module myConfig.pm.


Usage:

use ExSite::Config;

In addition, every program should also include the following first line of executable code:

&exsite_init;

Configuration Management

All system parameters are stored in one of four configuration hashes, which are exported automatically to every program that uses Config.pm:

%config
%config is used for system constants that do not normally change.

The system constants in %config are read first from the hard-coded values in Config.pm, and then from the local configuration file ``exsite.conf'', which can override the former values. Modifications to the site configuration should be made in exsite.conf, not in Config.pm.

Specific configuration parameters are described in the ExSite Configuration documentation, or in Config.pm.

Any module or other package can read its own configuration file(s) into %config, by calling: &ExSite::Config::read_exsite_conf().

%share
%share is used as a general-purpose shared-memory area. %share is cleared on each page request.

The %share hash is used for sharing data between widely separated modules and routines. The primary difference between %config and %share is that the former is regarded as persistent (values stay the same from request to request), while the latter is volatile (values vary from request to request).

The differences are not especially significant for normal CGI setups, since %config must be reloaded on each request anyway. But in a persistent perl or persistent data store configuration, %config may only be configured once at server startup, whereas %share will be cleared and rebuilt on every request. If you do not follow this convention, you may have problems when switching to use persistence.

%share is empty when initialized by default, and is cleared every time &exsite_init() is called. %share will be used to store pointers to the current database and page objects ($share{DB} and $share{Page}, respectively), plus any other shareable data placed there by localization routines and content modules.

%session
%session is used for session constants that need to be remembered for short times between page requests, but not for extended periods.

The %session hash stores semi-persistent data. That is, it remembers data between different page requests, but clears the data after a certain amount of time has passed. It is a useful mechanism for temporarily preserving state. By default, session data is stored for a maximum of 1 hour if no page requests renew the session, or 24 hours if the session is continually renewed. After this time, the session will be closed, and a new one will have to be opened.

If session management is enabled on a particular installation of ExSite, then %session will automatically be filled with the current session data. (See ExSite::Session for technical details.) These data include _atime and _ctime, which are timestamp values (Unix system times) of the last access, and the creation time of the session. If session management is not enabled, then the contents of %session are undefined (but will probably be blank in a conventional CGI setup).

You can also use %cookie to store semi-persistent data. %session is more secure and reliable if enabled, since the data is stored on the server. Note that when a session is initiated, the session ID is stored in %cookie, so both are in fact needed to make proper use of sessions.

Warning: session management is not enabled by default in the standard ExSite distribution. In this case, %session will be cleared on each page request, like %share.

%cookie
%cookie is used for session-like variables that are tracked client-side rather than server-side. As the name implies, these variables are stored as cookies in the user's browser. The %cookie hash automatically acquires all of the relevant cookies, and can be inspected to view the values of those cookies at any time.

Changing/setting cookie values is also easy; simply assign a new value to a cookie name, eg.

    $cookie{name} = $value;

The appropriate HTTP headers will be printed to ensure that the new cookie data is sent to the client browser for storage.

Because browsers can disregard cookies, and cookies can be manually deleted or edited at any time, there is no guarantee that cookies will in fact persist, nor that they will not be tampered with. They are also transmitted in cleartext, so are vulnerable to snooping. That means that %cookie is a useful convenience, but not a secure place for storing data. Sensitive data should be encrypted before being placed into a cookie. For example:

ExSite identity cookie
In ``cookie'' mode, it stores DES-encrypted password to validate the user identity. In ``crypt'' mode, it stores TEA-encrypted username and access level.

ExSite session ID
The session ID is an MD5 hash of several identifying values. This makes active session IDs hard to guess, and fairly secure from a keyspace attack. However, it is not very secure from a spoofing attack if an active session ID is sniffed from network traffic.


Setup and Configuration Routines

server_autoconf() - autoconfigure ExSite

This routine attempts to set the various server configuration parameters (ie. file paths and machine names) automatically, by inferring them from the server environment.

WARNING: auto-configuration will probably fail when testing CGI programs from the command line for testing/debugging purposes. If you need to have correct configuration, then either hard-code your configurations in exsite.conf, or set some environment variables on your command line to resemble the server environment. The following environment variables are used for auto-configuration: DOCUMENT_ROOT, SCRIPT_NAME, SCRIPT_FILENAME, HTTPS, HTTP_HOST.

read_exsite_conf() - load config parameters from a file

This routine loads configuration values from files. By default it looks for ``exsite.conf'' files in the conf, ExSite and . directories. An alternate filename can be given. By default configuration values are read straight into the root of %config, but a starting key can be given, eg. &read_exsite_conf("MyModule.conf","MyModule") will read the values in MyModule.conf into $config{MyModule}{...}.

Configuration files contain parameters and values, separated by ``='' (with any amount of whitespace around the ``=''. Values extend from the first non-whitespace character after the ``='', to the end of line. Simple parameters are placed directly into %config's keys. Parameters of the form ``a.b.c'' are stored as $config{a}{b}{c}. Config array references can be created using ``+='' to set the values in the array.

Example exsite.conf settings:

trim_whitespace = 0

form.style=list

db_ops.new.url = append.cgi

exsite_init() - generic ExSite initialization routine

This routine configures ExSite, and performs any local initializations. This routine is called automatically at the start of all generic CGI scripts, and should be called by custom scripts as well.

Local initialization can be done in &myConfig::my_exsite_init, which is called automatically from here. Note that my_exsite_init() is called on every initialization, so it should try to avoid reconfiguring static configurations (eg. handler registration) on every pass.

exsite_close() - clean up

page_header($title) - standard top-of-page HTML

Outputs the standard HTML to begin an ExSite administration page (eg. a control panel). Optionally, a page title can be provided.

Invokes &myConfig::my_page_header, which should contain any localized code for generating locally customized page headers.

page_footer() - standard end-of-page HTML

Outputs the standard HTML to end an ExSite administration page. Invokes &myConfig::my_page_footer, which should contain any localized code for generating the page footer.

get_obj() - fetch a standard object

There are a handful of global objects that ExSite commonly works with. The most common are the primary database object, and the current page being constructed. These are normally stored in %share to make them available to all components.

You can use get_obj() to fetch a predefined object safely. That is, it will return the predefined object if it exists, and it will create the object if it does not exist.

Example:

my $db = &get_obj('DB');

install_handlers() - register handlers

Handlers allow plug ins or other subsystems to register special business logic that should take precedence over the default logic in certain cases.

The ExSite base system has to do this in a few cases for its content management tables, which have their own logic that differs from the generic database handling. Otherwise, it is expected that most handlers will be site-specific (registered in myConfig::my_handlers() ) or plug-in-specific (registered from the plug-in module in ExSite::Modules).