=============================================================== This is 'node-gopher', the White Mesa gopher server for node.js =============================================================== Version 0.1.1 (2 Feb 2014) Copyright (c) 2014 Robert Cunnings, NW8L Tested on Windows 7 and Linux Mint 15 Features -------- * Supports RFC 1436 Gopher Protocol (no Gopher+ capability). * Gophermap support for defining menus. * Logging in common logfile format, with log rotation. * CGI-like support for executing scripts to generate a response. * Configurable path aliasing for file and directory selectors. * Configurable file name extension to gopher type mapping. White Mesa node-gopher is a node.js application. It is implemented in these js files: server.js gopher.js logger.js requestHandlers.js and the configuration file is: node-gopher.config Dependencies ------------ Requires that node.js be installed. See http://nodejs.org for details. Invocation ---------- Open a terminal window and navigate to the directory containing the server's .js files. Type 'node server.js' to start the node-gopher service. The server will print status information to standard output while running. CGI script error stream output will also be printed to the terminal window. node-gopher can be run as a service on Linux hosts. In Windows the service may be invoked from a batch file placed in the "Startup" folder on a workstation or even as a Windows Service using one of the tools available for that purpose. Configuration file ------------------ The configuration file is expected to reside in the same directory as server.js and be named 'node-gopher.config'. It contains the following sections: [server] [item-types] [alias-map] [cgi-script-map] [cgi-alias-map] Each section contains a number of name/value pairs, one pair per line. A line beginning with a '#' or ';' character is ignored (commented out). * [server] section Here are configured the following: host -> the host name (default: 'localhost') port -> the TCP port to listen on (default: 70) log-filename -> the log file name (default: './node-gopher.log') log-rot-interval -> the time interval in hours between log rotations (default: 24) log-enable -> 1 if logging enabled, 0 if logging disabled (default: 1) Example: [server] host=whitemesa.net port=7070 log-filename=./logs/node-gopher.log log-rot-interval=12 log-enable=1 * [item-types] section This contains mappings between filename extensions and the gopher item type they should be associated with. Most common types are defined by default in server.js, but here new associations can be made or default associations changed. Example: [item-types] .txt=0 .log=0 #.foo=0 .foo=9 .jpg=I .gif=g .bmp=I * [alias-map] section This contains mappings between path aliases in selectors and corresponding real paths in the host filesystem. Example (for Windows host): [alias-map] /=/home/gopher /physics=/home/bob/science #/=c:\gopher (for Windows instance) #/physics=c:\temp\science (for Windows instance) * [cgi-script-map] section This contains mappings between CGI script filename extensions and the executable file to be invoked for scripts of that type. Example: [cgi-script-map] .py=/usr/bin/python .pl=/usr/bin/perl #.py=python (for Windows instance) #.pl=perl (for Windows instance) * [cgi-alias-map] section This contains mappings between path aliases in CGI script selectors and corresponding real paths in the host filesystem. NOTE: CGI script selectors MUST be based on a path alias defined in this section - if not, they won't be executed! Example: [cgi-alias-map] /cgi=/usr/local/bin/gopher-cgi-bin #/cgi=c:\gopher\cgi-bin (for Windows instance) In this example all CGI script selectors must be based on path /cgi (e.g. '/cgi/foo/bar.py'). If not they won't be executed, but treated as a normal file selector instead. Gophermap support ----------------- The usual RFC 1436 compliant lines of the form: typenameselectorhostport are understood. Host and port fields are optional for local selectors. The selector may be relative to the current directory. In addition, the following special constructs are supported: * A line containing only the character '.' means "stop processing the gophermap and generate no further output". * A line containing only the character '*' means "stop processing the gophermap and generate a listing of the current directory". Normally placed at the end of the gophermap to force the listing after preliminary menu lines are printed. * A line containing only the character 'D' means "print the selector for the current directory". Used ahead of '*' line to provide a title for the directory listing. * A '-' character at the start of a line means "don't include this file in any directory listing that follows". Glob patterns using characters '*', '?' and '.' are supported. Examples: -foo.txt -bar.* Used to control visibility of files in directory listings. * A '#' character at the start of a line means "ignore this line". Used to comment out lines in the gophermap. CGI-like support ---------------- Script files must be based on a CGI path alias defined in the configuration file's [cgi-alias-map] section to be executed. The executable invoked depends on the mapping between the script's filename extension and an executable file in the configuration file's [cgi-script-map] section. When a CGI script is run it sees the following request meta-variables in the environment it inherits: * QUERY_STRING -> the search string for item type 7 (search) requests OR if this not found then any RFC 1738 'searchpart' (query string) found appended to the selector. * SCRIPT_NAME -> the request selector * SERVER_NAME -> the server host name (from the config file) * SERVER_PORT -> the server port number (from the config file) * REMOTE_ADDR -> the IP address of the host making the request * SERVER_PROTOCOL -> "Gopher" * SERVER_SOFTWARE -> "White Mesa node-gopher/0.1.0" The included python script "env.py" can be used to observe the environment constructed for the CGI process by the server. Logging ------- Gopher transactions are logged in common logfile format, with HTTP status codes used to reflect error conditions. Example: 127.0.0.1 - - [30/Jan/2014:12:19:19 -0700] "/cgi/env.py" 200 4698 "" Logfile rotation is automatic. The logfile being retired is given a new name which incorporates a UTC timestamp for later reference. Log settings are specified in the configuration file's [server] section. License ------- See the file "LICENSE.txt" for information on the terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES. .