===============================================================
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 Window 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:
type<tab>name<tab>selector<tab>host<tab>port<crlf>
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.