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 ", and on other operating systems, you would run "java aftershock.Aftershock ". In both cases, "" 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.