GREENSTONE DIGITAL LIBRARY DEVELOPER'S GUIDE

Chapter 4 Configuring your Greenstone site

There are two configuration files in Greenstone that are used for configuring various aspects of your Greenstone site. These files are the “main” configuration file main.cfg, found in GSDLHOME/etc, and the “site” configuration file gsdlsite.cfg, found in GSDLHOME/cgi-bin. These files each control specific aspects of site-wide configuration. Both can be viewed from the Greenstone administration page.

4.1 Main configuration file

The main configuration file main.cfg is used to configure the receptionist—that part of Greenstone that fields queries and displays pages. You can control everything from the languages that the interface can use to what logs are kept.

Site maintenance and logging

Lines in the configuration file dictate how your Greenstone site is maintained, what facilities it offers, which events are logged, and what notification is given to the maintainer. Table 20 details some of the options that are available; the remaining ones are described in the following sections.

Table 20 Configuration options for site maintenance and logging

	Value	Purpose
maintainer	NULL or an E-mail address	E-mail address of the site maintainer to be used for certain notification purposes. If NULL, E-mail events are disabled
MailServer	NULL or a server name	Outgoing mail server for this site. If NULL, mail.maintainer's-domain is used (e.g. if the maintainer is [email protected] the default is mail.example.com.) If this doesn't resolve to a valid smtp server, E-mail events will not work
status	enabled or disabled	Determines whether the “Maintenance and administration” page is to be made available
collector	enabled or disabled	Determines whether the end-user collection building “collector” facility is available
logcgiargs	true or false	If true, a usage log is kept in usage.txt.
usecookies	true or false	If true, information about the site users is collected (using cookies) and written to usage.txt(this only works if logcgiargs is true)
LogDateFormat	LocalTime or UTCTime or Absolute	Format in which time information is written to the log. LocalTime produces the format “Thu Dec 07 12:34 NZDT 2000”, UTCTime is the same format but in GMT, and absolute is an integer representing the number of seconds since 00:00:00 01/01/1970 GMT
LogEvents	AllEvents or CollectorEvents or disabled	Logs certain events to events.txt. AllEvents logs all Greenstone events, CollectorEvents logs only events related to the Collector, and disabled log no events
EmailEvents	enabled or disabled	E-mail the maintainer (if there is one—see the maintainer option) every time an event occurs
EmailUserEvents	enabled or disabled	E-mail the user on certain events—such as the collector finishing a collection build
macrofiles	list of macro filenames	Determine what macros are available for Greenstone's user interface software

Language support

Two kinds of entry in the main.cfg configuration file affect the way that different languages are handled. They determine which languages and encodings are available from the Preferences page. Encoding lines specify the different types of character encoding that can be selected. Language lines specify what user interface languages can be selected (of course, there must be a language macro for each possible language).

The Encoding line can contain four possible values: shortname, longname, map and multibyte. The shortname is the standard charset label, and must be specified for all encodings. The longname gives the encoding name that is displayed on the Preferences page. If it is absent it defaults to the shortname. The map value is mandatory for all encodings except utf8, which is handled internally (and should always be enabled). The multibyte value should be set for all character sets that require more than one byte per character. The file main.cfg specifies many encodings, most of which are commented out. To enable an encoding, remove the comment character “#”.

Each Language line can contain three possible values, shortname, longname, and default_encoding. The shortname is the ISO 639 two-letter language symbol, and is required. The longname is the name that is used for the language on the Preferences page. If absent, it defaults to the shortname. The default_encoding option is used to specify the preferred encoding for this language.

Page parameters and CGI arguments

Page parameters and CGI arguments may be defined from within the main.cfg configuration file. Recall from Figure 40 that most CGI arguments are defined within the library C++ code itself. However, it is occasionally useful to define new arguments or edit existing ones at configuration time, thus avoiding the need to recompile the library.

To do this you use the cgiarg configuration option. Cgiarg may take up to six arguments; shortname, longname, multiplechar, argdefault, defaultstatus and savedarginfo. These arguments correspond to the CGI argument options described in Section 3.8. For example, in the default main.cfg file the cgiarg configuration option is used to set the default values of the existing a and p CGI arguments to p and home respectively.

Page parameters are special cases of CGI arguments which correspond to parameters in Greenstone's macro files. For example, the l CGI argument directly corresponds to the l= parameter in the macro files. To define a CGI argument to also be a page parameter you use the pageparam configuration option.

The best way to learn about the various configuration options possible in the main-cfg configuration file is to experiment with the file itself. Note that if you are using the Windows local library version of Greenstone you must restart the server before any configuration files changes take effect.

4.2 Site configuration file

Table 21 Lines in gsdlsite.cfg

Line	Function
gsdlhome	A path to the GSDLHOME directory.
httpprefix	The web address of GSDLHOME. If the document root on your web server is set to GSDLHOME you do not need this line.
httpimage	The web address of the directory containing the images for the user interface. If your web-server's document root is set to GSDLHOME this will be images.
gwcgi	The web address of this cgi script (usually ends in library). This is not needed if your web server sets the environment variable SCRIPT_NAME.
maxrequests	(Only applies if fast-cgi is in use.) The number of requests fast-cgi should process before it exits. When debugging the library this should be set to a small number, otherwise it should be a large number.

The site configuration file gsdlsite.cfg sets variables that are used by the library software and web-server at run-time, and resides in the same directory as the library program. Table 21 describe the lines in this file; they are explained in Section 5 of the Greenstone Digital Library Installer's Guide.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”