Table of Contents
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.
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 <tblref table_configuration_options_for_site_maintenance_and_logging> details some of the options that are available; the remaining ones are described in the following sections.
<tblcaption table_configuration_options_for_site_maintenance_and_logging|Configuration options for site maintenance and logging></tblcaption>
| < - 132 151 246 > | ||
| 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 <br/>UTCTime or <br/>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 <br/>CollectorEvents<br/>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 <imgref figure_using_the_cgiargsinfoclass_from_pageactioncpp> 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 receptionist. 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.
Site configuration file
<tblcaption table_lines_in_gsdlsitecfg|Lines in gsdlsite.cfg></tblcaption>
| < - 132 397 > | |
| 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 <tblref table_lines_in_gsdlsitecfg> describe the lines in this file; they are explained in Section 5 of the Greenstone Digital Library Installer's Guide.