Aftershock Gopher Server
Version 1.01
Rob Linwood (rcl211@nyu.edu)
============================

:: Part I: Getting Started

Read the enclosed README file.  This contains information on installation for
this release.


:: Part II: Configuration Files

Aftershock is configured through the use of a configuration file.  By default,
this file is called "aftershock.conf", although you may use another file by
specifying it on the command line.  For example, under Unix, you would use the
command "aftershock <config-file>", and on other operating systems, you would
run "java aftershock.Aftershock <config-file>".  In both cases, "<config-file>"
should be replaced with the name of your configuration file.

The format of the configuration file is very simple.  Blank lines, and lines
which begin with a '#' are ignored.  All other lines are interpreted as
settings.  Each setting consists of a name and a value.  Consider the example

PortNum: 70

In this case, the name is "PortNum", and the value is 70.  All configuration
settings are given in this Name: Value syntax.  Each setting must be on its
own line.  The names of settings are not case-sensitive.  The following
settings are currently used:

PortNum
HostName
GopherRoot
UserName
LinkFileName
FileTypesFile
Filter
CheckCacheTimes
ListenerBufferSize
AccessLogFile
ErrorLogFile
ExceptionLogFile
InfoLogFile
AccessLogFormat
ErrorLogFormat
ExceptionLogFormat
InfoLogFormat
Filter

With the exception of Filter, which has a special meaning, all of these, if
used more than once, will overwrite their earlier settings.  You do not need
to set all of these - most have sensible default values, or are set up already
in the example aftershock.conf file in the Aftershock distribution.

They are described in detail below:

PortNum
=======
Type: Integer
Default: 70
Description: 
This defines which TCP port Aftershock will listen on.  The standard port for
Gopher is port 70 (the Aftershock default).  However, on multiuser systems
like Unix, users who do not have adminstrator rights cannot use ports below 
1024.  As a result, users of those systems will have to run Aftershock on 
another port, such as 7000.


HostName
========
Type: Internet host name or IP address, such as mypc.example.org or 192.168.0.1
Default: 127.0.0.1
Description: 
Aftershock needs to know which host name to use when generating dynamic
directories and links.  Set this to your host name, or 127.0.0.1 if you are
testing Aftershock.


GopherRoot
==========
Type: Directory name
Default: None
Description: 
This should name a directory which is used as the root of the file system
Aftershock is serving.  Set this to something, and then stick all the files
you want to make accessible there.


LinkFileName
============
Type: File name
Default: .Link
Description: 
Used to set the name of the Link files which are looked for every time a 
request for a directory is received from a client.  The default name ".Link"
was chosen for compatability with other Gopher servers.  For information on
Link files, see the section on "Link Files" below.


FileTypesFile
=============
Type: File name
Default: file.types
Description: 
The name of the file to read file types in from.  For a description of this
file, see the section on "File Types" below.  This setting is not neccesary -
Aftershock contains default file types.


Filter
======
Type: Regular Expression
Default: None
Description: 
Filter is a special setting, in that there can be more than one listed, and
rather than overwriting earlier definitions, additional Filter settings add
to the setting.

A Filter is a regular expression of the same kind as in Perl and Unix programs
like sed or grep.  For information on Java regexs, please see
http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html

Filter defines file name filters that prevent certain files
from being listed in automatic directory listings.  When a client requests a
directory for which no Link file exists (See the "Link Files" section), then
Aftershock will build a directory response based on all the files in the
directory.  Often, there may be files that you don't want automatically listed.
To do this, make a filter for them.

The default aftershock.conf has a line that reads "Filter: ^\.(.+)", which
filters out any file beginning with a "." character.  To filter out one file,
for example "secrets.txt", you would add "Filter ^secrets\.txt" to your
configuration file.


CheckCacheTimes
===============
Type: True or False
Default: False
Description: 
In order to save time on disk accesses, Aftershock stores data from files it
has read before into a cache in memory.  While saving the file in cache, it
also sets a timestamp, which shows exactly when the file was cached. Setting
CheckCacheTimes to true causes Aftershock to compare that timestamp to the
file modification date of the file on disk on every request.  If the file on
disk is more recent, then Aftershock will discard the old file and load the
new copy from disk.

If you have files that change often, you will want to set this to true, as
there is currently no other way to expire files from the cache.

For more on caching, see the section "Caching" below.

ListenerBufferSize
==================
Type: Integer
Default: 1024
Description: 
This is the size of the buffer used by the Gopher Listener (which waits for
incoming requests).  You can set this if you want, but there's probably
no real need to change it.


AccessLogFile
=============
Type: File Name
Default: None
Description: 
The name of the file in which to record all client accesses.  This directory
this file is in must exist before Aftershock can use it.  

For more information on logging, see the section "Logging" below.


ErrorLogFile
============
Type: File Name
Default: None
Description: 
The name of the file in which to log all server errors.  This directory
this file is in must exist before Aftershock can use it.  

If you see lots of these in your logs, please post a bug report on the
Aftershock project page (http://sf.net/projects/aftershock)

For more information on logging, see the section "Logging" below.


ExceptionLogFile
================
Type: File Name
Default: None
Description: 
The name of the file in which to record Java Exceptions.  This directory
this file is in must exist before Aftershock can use it.  

Exceptions are error conditions which generally mean that there is a bug in
Aftershock.  If you see lots of these in your logs, please post a bug report
on the Aftershock project page (http://sf.net/projects/aftershock)

For more information on logging, see the section "Logging" below.


InfoLogFile
===========
Type: File Name
Default: None
Description: 
The name of the file in which to record server info messages.  This directory
this file is in must exist before Aftershock can use it.  

The info log contains messages about events like startup and shutdown.

For more information on logging, see the section "Logging" below.


AccessLogFormat
===============
Type: Log Format String
Default: {DATE} {TIME} - {SELECTOR} - {REMOTEIP} - {PROTOCOL} 
Description: 
This is the format string used to format client access log records to the
access log.  For information on Log Format Strings, see the section of this
manual on Logging.


ErrorLogFormat
==============
Type: Log Format String
Default: {DATE} {TIME} - {MESSAGE}
Description: 
This is the format string used to format server error messages to the
error log.  For information on Log Format Strings, see the section of this
manual on Logging.


ExceptionLogFormat
==================
Type: Log Format String
Default: {DATE} {TIME} - {EXCEPTION} {NEWLINE} {STACK}
Description: 
This is the format string used to format Java exceptions log records to the
exception log.  For information on Log Format Strings, see the section of this
manual on Logging.


InfoLogFormat
=============
Type: Log Format String
Default: {DATE} {TIME} - {MESSAGE}
Description: 
This is the format string used to format server info messages to the
access log.  For information on Log Format Strings, see the section of this
manual on Logging.



One important thing to know for troubleshooting is that Aftershock does not
consider the names of settings to be special.  That is, Aftershock will accept
as valid any Name: Value pair given in the configuration file.  This is meant
to allow for future expandability, but a practical concern is that misspelled
Names will not be flagged as incorrect.  So, as in example, if you had
"PortNun: 7000" in your configuration file instead of "PortNum: 7000", 
Aftershock would store the "PortNun" setting and continue along with the
default port number.


:: Part III: File Types

In the Gopher world, all files are given a type.  This type represents what
sort of data the file holds - for example it could be an image, or a sound, or
a Zip archive.  Types are represented in Gopher as a single character - 'g'
means that a file is a GIF image, and 'h' means that it is HTML.  File types
can be managed by editing a file type file (whose name is given in the 
FileTypesFile setting in the config file).  The file types file supports two
settings: AddType and DefaultType. 

An example of AddType is:

AddType: tgz 9

An AddType setting takes two values, the first being a file extension, and the
second being the file type character.  In the example, files with the extension
".tgz" will be given file type '9', which means that it is a binary data file.
There can be any number of AddType settings in the file types file.  If two
AddTypes refer to the same extension, the one added last will be used.

Setting the DefaultType setting, as in

DefaultType: 0

tells Aftershock to use type '0' (plain text) for all files which either have
no extension, or whose extension doesn't have a type listed.  Unlike AddType,
there should only be one DefaultType setting.

Aftershock has the following types built in.  They can be overridden through
use of the file types file:

DefaultType: 0
txt  - 0
jpg  - I
gif  - g
html - h
htm  - h
hqx  - 4
exe  - 5
com  - 5
uue  - 6
gz   - 9
zip  - 9
jar  - 9

Directories have a file type of '1'.

:: Part IV: Link Files

Link files allow you to customize directory output and link to other network
resources (such as other Gopher sites, web sites, or telnet sessions).  Links
are stored in a file which is by default called ".Link" (you can specify 
another name by setting the LinkFileName setting in the configuration file).
When Aftershock is sent a request for a directory, it first searches for a 
link file in that directory.  If it finds one, it will read it and produce a
menu from it.  Otherwise, it will create a menu automatically.

Inside a link file are link entries.  Each link entry is made up of the
following fields: Name, Type, Path, Host, Port.  These are specified inside
the Link file as in this example:

Name=Super-Dimensional Fortress Gopher
Type=1
Path=/
Host=freeshell.org
Port=70

This adds a link to the gopher site running on port 70 of freeshell.org, with
a path of "/" (ie, the root directory).  The Name is what the Gopher client
would display to the user.  The Type indicates the file type (see the section
"File Types" above), which for directories shoudl be '1'.  In URL terms, this
would correspond gopher://freeshell.org:70/

Of the five fields, only one is required, Name.  Three of the remaining fields
have default values.  They are:

Type - default is 'i'.  This means "information" and is explained below.
Port - default is the port Aftershock is listening on
Host - default is the hostname given in the configuration file.

If Path is not given, then it is assumed that there is no path element.  The
advantage of having default values for Port and Host is that you can create
links to items on your local server without having to update those if you
change port numbers or machines.

The default Type, 'i', means that the line is informational.  No link will
be shown, but rather the value of the Name field will be displayed to the
user in some way.  To include plain text in a directory listing, just use
several Name= in a row, for example:

Name=This is a big block of text.
Name=There is no need for adding a Path, Type, Host, or Port
Name=because they would not be used.


:: Part V: Logging

Aftershock makes logs of certain events that occur.  This helps with things
like tracking how many visitors you recieve or hunting down bugs in the
Aftershock code.  There are four types of events that Aftershock records:

Access    - these occur when a client makes a request of your server
Error     - when Aftershock encounters an error situation 
Exception - when a programming error occurs
Info      - any non-critical information, such as startup time.

Each of these types has a seperate file and log format.  The file names and
formats are specified in the configuration file.

Log formats determine how the logged events appear in the file.  They are
specified as strings of characters in which certain special tokens are
replaced by the information which they represent.  A token is a string encased
in curly braces ("{" and "}") which has a special meaning.  Some tokens are
only valid for some event types.  Any characters which are not part of a token
are written to the log file unaltered.  

The token types are:

All Events:
{DATE}      - Replaced by the current date, formatted to your locale.
{TIME}      - Replaced by the current time, formatted to your locale.
{NEWLINE}   - Adds a newline character ('\n' in Java) to the log file

Access:
{REMOTEIP}  - Replaced by the IP address of the client
{SELECTOR}  - Replaced by the selector (file name) the client requested
{PROTOCOL}  - Protocol used in the request - either "gopher" or "gopher+"

Error and Info:
{MESSAGE}   - The error or informational message

Exception:
{EXCEPTION} - The exception text
{STACK}     - The stack trace from the exception

For example, when a client access is logged when the default AccessLogFormat
is in use, it will produce output like:

11/11/03 11:37:35 PM - /logos - /127.0.0.1 - gopher

It should be clear that the "11/11/03" is the date, "11:37:35 PM" is the time
"/logos" is the selector, "/127.0.0.1" is the remote IP, and "gopher" is the
client protocol used.

Dates and times are locale-sensitive.  That means that they will be rendered
according to your locale (your country and language).  Someone running 
Aftershock on a machine configured for European use would see dates and
times displayed differently. 


:: Part VI: Aftershock on Unix

Aftershock has special support for running on Unix and Unix-like systems
such as Linux, FreeBSD, and MacOS X.  Specifically, Aftershock may be set up
to start its listener running, and then switch to another user.  This may be
useful in cases in which you wish to have Aftershock bind to the standard
Gopher port (70), but not to have Aftershock run with root privliges. To
enable this feature, set the UserName setting in the configuration file to
the appropriate user.  Then, compile the support library by unzipping the
src.jarle that came with the Aftershock distribution, and running 
"make install" in the src/jni directory.  If all goes well, the next time
you start Aftershock, user switching should work.


:: Part VII: Caching

In order to speed up subsequent sends of the same file or directory, Aftershock
uses caching to save the contents of a file or disk in memory.  By default,
once Aftershock caches a file, it will never reload it from disk.  You can
force it to look at file modification dates to see if a new version is
available by setting the CheckCacheTimes setting to true.


:: Part VIII: Further Considerations

Aftershock will never send a file whose name begins with a period ("."). This
is both for reasons of security (for example, a malicious client could send a
selector of "../../etc/passwd" to attempt to climb out of the gopher root
directory, and Aftershock will not allow it), and because such files (often 
called "dotfiles") are meant to be hidden.  

