II.e Configure the Gopher Server -------------------------------- The file named by the GOPHER_CONFIG logical will be read by the GOPHERD.EXE program during initialization. The file allows you to specify overrides to compiled defaults and the GOPHER_DATADIR logical (if any), and is recommended to be used over editing the CONF.H file prior to building the executable. The file can reside just about anywhere, but (see the Hidden specification below) it is perfectly acceptable to put it in the root of the data directory. An example configuration file follows: Access: default read browse search Access: .stupid.domain !read !browse !search Access: 123.456. browse !read !search Admin: J.Lance Wilkinson AdminEmail: GopherAdmin@psulias.psu.edu HostAlias: psulias.psu.edu Site: Penn State University Libraries Org: Penn State University Libraries Loc: E8 Pattee Library, University Park, PA 16802 LogFile: GOPHER_ROOT:[_vms2_13.log]_GOPHER.LOG ErrorFile: GOPHER_ROOT:[_vms2_13.log]_GOPHER.ERR Geog: Centre County, Pennsylvania, U.S.A. BummerMsg: Sorry, access denied at this time. Language: EN_US Ignore: .OBJ Ignore: .EXE Ignore: .DAT Ignore: .MAI Abstract: OpenVMS Gopher+ server supporting the PSU Libraries VeronicaIndex: Yes Include: GOPHER_ROOT:[_vms2_13.support]common.cfg MaxConnections: 100 Ext: .BCK 9 9 VMS_Saveset Ext: .BCK-2048 9 9 VMS_Saveset Ext: .EXE 9 9 Executable Ext: .HQX 4 4 Macintosh-BINHEX Ext: .OBJ 9 9 Object Ext: .TAR 9 9 TARred Ext: .TAR_Z 9 9 TARred_COMPRESSed Ext: .UU 6 6 UUENCODEd Ext: .UUE 6 6 UUENCODEd Ext: .Z 9 9 COMPRESSed Ext: .ZIP 9 9 ZIP DataDirectory: GOPHER_ROOT:[000000] Port: 70 Inetd: FALSE MaxLoad: 15.0 TimeZone: EDT IsGplus: TRUE IgnoreAll: FALSE SortDir: TRUE FTPPort: NONE EXECPort: NONE SRCHPort: 7070 OVERPort: 170, 1024 SortShell: FALSE SortGREP: TRUE SortCMD1: TRUE ReadTimeout: 300 Console: Central+Network Hidden: _ Link: . LookAside: _lookaside DName: %fn [%ts, %sz] DHead: GOPHER_ROOT:[_vms2_13.support]Standard_Disclaimer.txt DFoot: -- standard disclaimers apply -- ScratchDir: GOPHER_ROOT:[_scratch] SupportDir: GOPHER_ROOT:[_vms2_13.support] SpawnInit: GOPHER_ROOT:[_vms2_13.support]GOPHER_SPAWN_INIT.COM Restart: GOPHERD_RESTART_70 LogTag: pid Cn# Rollover: Daily Cache: FALSE Do_chroot: FALSE The syntax of a configuration file is as follows: := CR-LF := | := | "#" [] := ":" ["!"] The keywords and interpretation of the texts following them are: Access: Specifies sites which are to be denied access or explicitly granted access to the server. Multiple Access specifications may be made. Default behavior allows access by any and all clients. The for the Access specification is formatted as follows: [["!"]][,["!"]]... is the domain name or IP number of a site whose clients are to be granted or denied access. "default" may be specified to define a default set of access permissions. Specifying a site with a prefixing "." (e.g., Access:.psu.edu) specifies that any host with a name ending in ".psu.edu" should match the specification. Similarly, specifying a site in dotted decimal form with a suffixing "." (e.g., Access:128.118.) specifies that any host with an IP address starting with "128.118." should match the specification. The keyword "default" may be used as a site name to define a catchall access restriction to be applied to any sites which are not explicitly listed in one or more Access: specifications. specifies "b" for browse, "r" for read, "s" for search, "f" for ftp gateway and "e" for script execution permissions. A numeric value may be specified also, to indicate the maximum number of concurrent connections allowed from the site in the Access specification. The maximum sessions option is allowed but not used by the OpenVMS server since it does not use forking to implement multiple connection services. "!" prefixing a permission item denies the access, while omitting the "!" grants the access. Note that because of this syntax, OpenVMS-style inline commentary ("!" prefixing any other text), allowed with most other configuration lines, is not allowed with an Access specification. Also note that multiple permissions associated with a site should be specified on a single line, separated by commas or spaces, for example: Access:.unc.edu b,r,!s AuthScript: Currently unimplemented. No default is defined. AuthItem: Currently unimplemented. No default is defined. ServerPW: Currently unimplemented. No default is defined. Admin: The name of the warm-bodied (?) individual responsible for Gopher Server administration at the local site. No default is defined. Your server will complain if you omit a specification. AdminEmail: The Email address of the individual named in the Admin specification. No default is defined. Your server will complain if you omit a specification. Note because some Email addresses might contain "!", OpenVMS-style inline commentary ("!" prefixing any other text), allowed with most other configuration lines, is not allowed with an AdminEmail specification. HostAlias: The HostAlias keyword specifies the fully-qualified domain name of your local host. It is used by the server to identify itself, and to substitute for "+" when found in a Host=+ specification in a .link or lookaside file. The default resolves to the current host. Site: Name of the local site. No default is defined. Your server will complain if you omit a specification. Org: The name of the organization offering the Gopher Server to the public, often the organization within which the individual named in the Admin specification works. No default is defined. Your server will complain if you omit a specification. Loc: The real-world address of the organization named in the Org specification. No default is defined. Your server will complain if you omit a specification. LogFile: The name of the log file where the Gopher Server is to store its event/transaction log. The file named will be created by the server if it does not exist, and appended to if it does exist. No default is defined. The optional Rollover: specification may modify the value of the LogFile name at runtime. You may specify the keyword "SYSLOG" to use a syslogd procedure for logging instead of a log file. ErrorFile: The name of the log file where the Gopher Server is to direct its debugging messages. The file named will be created by by the server if it does not exist, and appended to if it does exist. No default is defined. INETD servers attempt to write traceback dumps here if possible. Geog: The longitude/latitude coordinates for targeting missles at the site or some other (hopefully more useful) geographic information. No default is defined. BummerMsg: The text of a message to be displayed back to a client if access is denied to a particular resource or document. No default is defined. Language: The ISO code for the native language the server defaults to. Currently unimplemented, but eventually this could provide for internationalization of messages generated by the server to clients prefering alternate languages. No default is defined. ViewExt: Currently unimplemented. No default is defined. BlockExt: Currently unimplemented. No default is defined. BlockRefExt: Currently unimplemented. No default is defined. Ignore: Specifies default *exclusion* of files by extension. Multiple Ignore specifications my be made. No defaults are defined. The for the Ignore specification is exactly the same as the subfield of the Ext specification's . In fact, specifying "3" as the subfield on an Ext specification has the same effect as the Ignore specification. Ignore_Patt: Currently unimplemented. No default is defined. Decoder: Currently unimplemented. No default is defined. Abstract: A one-line description of what clients will find on this server -- a mission statement or a summary of what's available. No default is defined. Your server will complain if you omit a specification. VeronicaIndex: YES or NO, is Veronica Harvesting (or any robot harvesting?) to be allowed. Specify NO if you don't wish your server to be accessed by Veronica (a GopherSpace Harvesting Robot), YES if you will allow this. The default is YES. Note this simply presumes that, when provided with this information, the robot attempting to harvest your site's GopherSpace will honor it. CacheTime: Currently unimplemented. No default is defined. FileSep: Currently unimplemented. No default is defined. Include: A filename to be read for configuration information. Gopher configuration files may be nested up to 10 levels deep. No default is defined. A useful application of this feature is a single file with configuration specifications common to both a detached process server and INETD servers. BlockScript: Currently unimplemented. No default is defined. MaxConnections: The number of clients to be allowed to connect simultaneously. Since the OpenVMS Gopher+ Server doesn't use forking to effect multiple connection servicing, this field is pretty irrelevant. No default is defined. Ext: Specifies type of file by extension. Multiple Ext specifications may be made. No defaults are defined. The for the Ext specification is formatted as follows: is the extension itself, the last character(s) of the file being described. This might be a complete filename or any trailing subset of its characters, like .OBJ, .EXE, ME.TXT, etc. is a single character specifying the Gopher type of any document ending with the specified characters. 0 is file, 1 is directory, 7 is searchable index, and so on, according to the standard Gopher capabilities in the GOPHER_FYI_RFC. is a prefix to be applied to the path of files matching . is a text string naming a Gopher+ type. Since this is not a Gopher+ server, this option is presently ignored. DataDirectory: The path to the root directory, overriding the GOPHER_DATADIR logical. The default is DATA_DIRECTORY as defined in the CONF.H file (GOPHER_DATADIR by default). Port: The numeric TCP/IP port, overriding the GOPHER_PORT defined in the CONF.H file (70 by default). Inetd: TRUE or FALSE, is server started automatically. Specify TRUE if the server will be started automatically upon reception of a connection request on its port using whatever mechanism your site's TCP/IP Agent provides; specify FALSE if the server will be started as a detached process. No default is defined. MaxLoad: System load maximum (15 minute average) beyond which the server is to refuse client requests. Specify as a floating point number. Default is 0.0, which indicates that no load restrictions are to be imposed. TimeZone: A numeric specification of the local time zone, specified as an offset from Greenwich Mean Time (GMT). For example, +0300 is GMT plus 3 hours (east of Greenwich) -0445 is GMT minus 4 hours, 45 minutes (west of Greenwich). Alternatively, any text string may be used. No default is assumed. If a GMT offset is specified with less than 3 digits, it will be multiplied by 100 to assume 0 minutes. The keyword "TZ:" may be used as well as "TimeZone:" IsGplus: TRUE or FALSE. Specifies whether the server is to assume, wherever appropriate, that it should respond as a Gopher+ server. The default is is FALSE to allow structured and deliberate adoption of Gopher+ attributes in Gopher0 Gopher Spaces. IgnoreAll: TRUE or FALSE. Specifies whether the server is to by default scan or ignore non-link files in directories. The default is FALSE. SortDir: TRUE or FALSE, specifies whether directories should be sorted; default TRUE. FTPPort: NONE or a port number, specifies the port for a local gopher server which supports anonymous FTP (aFTP) gateway accesses. Since these gateway accesses can introduce extra load on a gopher server, you may wish to disable them by specifying NONE. The default is whatever your default port is defined to be. When NONE, no aFTP gateway requests are honored. When a different port value than your default Port: specification is supplied, it is assumed another server exists on that port configured to honor aFTP gateway requests. When a link tuple with Port=+ and Path=ftp.... is offered back to a client, this port is substituted instead of the standard port. EXECPort: NONE or a port number, specifies the port for a local gopher server which supports EXEC script accesses. Since these script executions can introduce extra load on a gopher server, you may wish to disable them by specifying NONE. The default is whatever your default port is defined to be. When NONE, no EXEC script requests are honored. When a different port value than your default Port: specification is supplied, it is assumed another server exists on that port configured to honor EXEC script requests. When a link tuple with Port=+ and Path=exec... is offered back to a client, this port is substi- tuted instead of the standard port. SRCHPort: NONE or a port number, specifies the port for a local gopher server which supports search index accesses. Since these searches can introduce extra load on a gopher server, you may wish to disable them by specifying NONE. The default is whatever your default port is defined to be. When NONE, no index search requests are honored. When a different port value than your default Port: specification is supplied, it is assumed another server exists on that port configured to honor search index requests. When a link tuple with Port=+ and Path=7... is offered back to a client, this port is substituted instead of the standard port. OVERPort: NONE or a port number and threshold pair, specifies the port for a local gopher server which can serve resources exceeding the threshold size in bytes. Since serving large files can introduce extra load on a gopher server, you may wish to have an alternate server handle large documents. The default port is whatever your default port is defined to be. When NONE, no filtration is performed on the basis of size. When a different port value and threshold are specified, it is assumed that another server exists on that port configured to serve out large files. Specify the port and threshold separated by a comma; for example: OVERPort: 7070, 1024 to serve only files smaller that 1K through the current server, and redirect all resources exceeding 1K to be served through the server on port 7070. SortShell: TRUE or FALSE, specifies whether result menus from shell searches should be sorted. Overridable at the individual link tuple level by specifying ":sort:" or ":nosort:" immediately after the "7" in the selector string for the Path= specifica- tion. SortGREP: TRUE or FALSE, specifies whether result menus from GREP searches should be sorted. Overridable at the individual link tuple level by specifying ":sort:" or ":nosort:" immediately after the "7" in the selector string for the Path= specification. SortCMD1: TRUE or FALSE, specifies whether result menus from CMD1 searches should be sorted. Overridable at the individual link tuple level by specifying ":sort:" or ":nosort:" immediately after the "7" in the selector string for the Path= specification. Does not apply to 7$version, 7$ftplink or 7$go4link pseudo- searches (all these are implicitly "7:nosort:$..."). ReadTimeout: The number of seconds the server is to wait following a client's connection for resolution of the client's IP address and receipt of the client's request before giving up and breaking the connection. Default is 300, or five minutes, as coded for the value of READTIMEOUT in the CONF.H file. Detached process servers might benefit from shorter timeouts, such as 1 or 2 minutes (60 or 120 seconds). Console: The operator console terminal type or types to receive any $SNDOPR system service messages from the server. Generally these are server abort-level messages. One or more keywords may be specified, separated by "+". Default is Central+Network. Keywords that may be specified are: Cards Card device operator Central Central operator Cluster VMSCluster operator Device Device status information Disks Disk operator Network Network operator Tapes Tape operator Print Printer operator Security Security operator Oper1 system manager-defined operators thru Oper12 1 through 12 Hidden: The character string which prefixes files which the server is not to detect when building directory menus. Default is "_". This is because there really aren't hidden files in OpenVMS like in Unix, and while we could prefix them with "." like .links files, maybe there's something in one of them that would be accepted as a .links entry, but we don't want it to be treated as such. Lots of files, including SERVER_ERROR files, can be kept in the root data directory and elsewhere, undetected by the server, in this manner. Link: The character string which prefixes files which the server is detect and treat as menu specification files (.LINKS) when building directory menus. Default is ".". Everything else got parameterized, why not this? LookAside: The name of a subdirectory which is considered a lookaside directory. Default is ".cap". In any given parent directory, this subdirectory, if it exists, contains lookaside files for other files in the parent directory. Such directories are always ignored when building menus. DName: Specifies a default Name= equivalence for documents which are not paired with a lookaside file. This offers a way to achieve the behavior of a Unix server with the "date+size" patch, by specifying "%fn [%ts, %sz]" for a DName: option. Documents of types where the "date+size" patch is inappropriate (directories, indexes, etc.) are not subjected to the DName substitution; instead, only the actual document name is offered. DHead: Specifies a default line of text to prefix all Type=0 documents when the server delivers them to clients. If a valid filename (which exists) is specified, the entire file's contents is prefixed before the documents. This is a method of adding standard disclaimers or copyright notices. DFoot: Specifies a default line of text to suffix all Type=0 documents when the server delivers them to clients. If a valid filename (which exists) is specified, the entire file's contents is suffixed after the documents. This is a method of adding standard disclaimers or copyright notices. ScratchDir: The path to a device/directory to which the gopher server has full access (Read, Write, Execute and Delete). The default is SYS$SCRATCH:, but for INETD servers this must be explicitly specified since they do not have the SYS$SCRATCH: logical defined. SupportDir: The path to a device/directory to which the gopher server has Read access. No default is defined. The support directory should contain, at minimum, the site-customized SERVER_ERROR.* files which the server issues to the client when an error occurs. As well the support directory is an ideal place to store the server's configuration file and the file named in the SpawnInit: specification. For .SHELL, .SCRIPT and .ASK files with no directory/path specification (which by default says they should exist in the directory named by the DataDir: configure file specification), the server will also check in this directory for these files. SpawnInit: The fully-qualified filespec (device:[dir]filename) for a DCL command file to be executed by any subprocesses spawned by the gopher server. Included in this file should be symbol and/or logical definitions which the subprocesses (e.g., GREP searches) will require but are not defined due to INETD startup. Note the use of GOPHER$ROOT:[v1216] is specific to the site psulias.psu.edu; in no way should you feel obligated to use the same device and directory tree specification. Restart: Specifies a LNM$SYSTEM_TABLE ($ define/system/exec) logical name for which the server is to check prior to each transaction read; if the logical exists, the server exits cleanly. If unspecified the default is the value of RESTART in CONF.H (normally, this is GOPHER_RESTART). A tie-in to the port is advised (but not auto-matically imposed by the server), such as GOPHER_RESTART_70 or RESTART_GOPHER_ON_PORT_1075. LogTag: Specifies a text string and tokens to be used to differentiate multiple server's messages in a log file. The text specified will appear in every log entry generated by the server, before the client's IP number or DNS host name. Tokens are separated by whitespace in the configuration specification, but are separated by "/" in the log entries. "Dbg" will appear as the first item in the log tag for any server running in DEBUG mode. Other tokens are: pid - The server's process id. If the server is an INETD server, "i" prefixes the process id. node - The server's OpenVMS node name. host - The server's HostAlias name. Cn# - The current connection number. Texts which don't match tokens are simply inserted into the tag text. Rollover: Specifies a log file rollover period. Valid keywords are ANNUALLY, MONTHLY, WEEKLY, DAILY, HOURLY and NEVER. Any unrecognized keywords are assumed to be NEVER; Default is NEVER. Specifying a keyword appends additional text to the Logfile: specified filename, if any. The resultant filename is the file actually written to by the server for any given log entry; in the following examples, assume the current timestamp is 1-Jul-1993:16:32 -- ANNUALLY append current year (e.g. "1993") MONTHLY append current year and month (e.g., "199307") WEEKLY append current year, month and date of last Sunday (or current date if Sunday, e.g. "19930627") DAILY append current year, month and date (e.g., "19930701") HOURLY append current year, month, date and (24-) hour (e.g., "1993070116") Note that the rollover specification (or default of NEVER) has a side effect in the original allocation and extension alloca- tions for the log file. A different value for each rollover selection is defined in CONF.H, based on a gut-feel for the file size. These may be changed by editing CONF.H and recompiling and relinking the server. Cache: TRUE or FALSE, is server caching directories. FALSE until implemented in the OpenVMS server. Do_chroot: TRUE or FALSE, will program perform chroot() calls. FALSE since that isn't needed in the OpenVMS implementation. .