
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.


