Differences

This shows you the differences between two versions of the page.

Link to this comparison view

legacy:manuals:en:develop:configuring_your_greenstone_site [2013/10/17 11:44] (current)
Line 1: Line 1:
 +====== <!-- id:1143 -->​Configuring your Greenstone site ======
 +
 +<!-- id:1144 -->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.
 +
 +===== <!-- id:1145 -->Main configuration file =====
 +
 +<!-- id:1146 -->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.
 +
 +==== <!-- id:1147 -->Site maintenance and logging ====
 +
 +<!-- id:1148 -->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 >|
 +| | <!-- id:1150 -->​**Value** | <!-- id:1151 -->​**Purpose** |
 +| <!-- id:1152 -->//​maintainer//​ | <!-- id:1153 -->NULL or an E-mail address | <!-- id:1154 -->​E-mail address of the site maintainer to be used for certain notification purposes. If NULL, E-mail events are disabled |
 +| <!-- id:1155 -->//​MailServer//​ | <!-- id:1156 -->NULL or a server name | <!-- id:1157 -->​Outgoing mail server for this site. If NULL, //​mail.maintainer'​s-domain//​ is used (e.g. if the maintainer is //​help@example.com//​ the default is // mail.example.com //.) If this doesn'​t resolve to a valid smtp server, E-mail events will not work |
 +| <!-- id:1158 -->//​status//​ | <!-- id:1159 -->//​enabled//​ or //​disabled//​ | <!-- id:1160 -->​Determines whether the “Maintenance and administration” page is to be made available |
 +| <!-- id:1161 -->//​collector//​ | <!-- id:1162 -->//​enabled//​ or //​disabled//​ | <!-- id:1163 -->​Determines whether the end-user collection building “collector” facility is available |
 +| <!-- id:1164 -->//​logcgiargs//​ | <!-- id:1165 -->//​true//​ or //false// | <!-- id:1166 -->If //true//, a usage log is kept in //​usage.txt//​. |
 +| <!-- id:1167 -->//​usecookies//​ | <!-- id:1168 -->//​true//​ or //false// | <!-- id:1169 -->If //true//, information about the site users is collected (using cookies) and written to //​usage.txt//​(this only works if //​logcgiargs//​ is //true//) |
 +| <!-- id:1170 -->//​LogDateFormat//​ | <!-- id:1171 -->//​LocalTime//​ or <​br/>//​UTCTime//​ or <​br/>//​Absolute//​ | <!-- id:1172 -->​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 |
 +| <!-- id:1173 -->//​LogEvents//​ | <!-- id:1174 -->//​AllEvents//​ or <​br/>//​CollectorEvents//<​br/>​or //​disabled//​ | <!-- id:1175 -->Logs certain events to //​events.txt//​. //​AllEvents//​ logs all Greenstone events, //​CollectorEvents//​ logs only events related to the Collector, and //​disabled//​ log no events |
 +| <!-- id:1176 -->//​EmailEvents//​ | <!-- id:1177 -->//​enabled//​ or //​disabled//​ | <!-- id:1178 -->​E-mail the maintainer (if there is one—see the maintainer option) every time an event occurs |
 +| <!-- id:1179 -->//​EmailUserEvents//​ | <!-- id:1180 -->//​enabled//​ or //​disabled//​ | <!-- id:1181 -->​E-mail the user on certain events—such as the collector finishing a collection build |
 +| <!-- id:1182 -->//​macrofiles//​ | <!-- id:1183 -->list of macro filenames | <!-- id:1184 -->​Determine what macros are available for Greenstone'​s user interface software |
 +
 +==== <!-- id:1185 -->​Language support ====
 +
 +<!-- id:1186 -->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).
 +
 +<!-- id:1187 -->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 “#”.
 +
 +<!-- id:1188 -->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.
 +
 +==== <!-- id:1189 -->Page parameters and CGI arguments ====
 +
 +<!-- id:1190 -->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.
 +
 +<!-- id:1191 -->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|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.
 +
 +<!-- id:1192 -->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.
 +
 +<!-- id:1193 -->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.
 +
 +===== <!-- id:1194 -->Site configuration file =====
 +
 +<​tblcaption table_lines_in_gsdlsitecfg|Lines in //​gsdlsite.cfg//></​tblcaption>​
 +|< - 132 397 >|
 +| <!-- id:1196 -->​**Line** | <!-- id:1197 -->​**Function** |
 +| <!-- id:1198 -->//​gsdlhome//​ | <!-- id:1199 -->A path to the //​GSDLHOME//​ directory. |
 +| <!-- id:1200 -->//​httpprefix//​ | <!-- id:1201 -->The web address of //​GSDLHOME//​. If the document root on your web server is set to //​GSDLHOME//​ you do not need this line. |
 +| <!-- id:1202 -->//​httpimage//​ | <!-- id:1203 -->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//. |
 +| <!-- id:1204 -->//​gwcgi//​ | <!-- id:1205 -->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//​. |
 +| <!-- id:1206 -->//​maxrequests//​ | <!-- id:1207 -->(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. |
 +
 +<!-- id:1208 -->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.//
 +