mgod copyright (C) 2006-2018 Máté Nagy <[email protected]>
This software is available under the GNU General Public License (Version 3)
(a copy of which can be found in the file COPYING).
 -> gopher://port70.net/1mgod


mgod: a mini gopher server for inetd

Mgod can serve a directory structure, taking extra data from hidden files in
each directory (called .gopher).  It can invoke external scripts or
executables for search string processing.

Gopher+ used to be supported, but support was eventually removed.
Gopher+ requests for the root menu result in a "trampoline" menu that tells
the client to use the plain gopher protocol.


CHANGELOG

SVN:
  - added support for . and .. in relative links
  - better logging through httpgate

1.0:
  - license changed to GPL v3
  - Gopher+ support removed
  - Removed original support for search processors (now only dirproc-style
    support remains)
  - Check for access permissions (don't serve files/dirs not readable by all)
  - Better file type classification (by a table defined at the head of the .c)

1.1:
  - Bug fix for files with 7-character long extensions provided by Jonathan Neuschäfer


INSTALLING

Compile the server by typing "make".
Add this line to your /etc/inetd.conf:

gopher    stream    tcp    nowait    nobody    /usr/sbin/tcpd    <exec>

Replace <exec> with your mgod command line:
/path/to/mgod -n server_name -r root_dir

Then restart inetd.

ARGUMENTS

-n <servername>
    Set server name (default 127.0.0.1). You'll need to set this to the
    visible internet name of your server.

-p <serverport>
    Set server port (default 70).

-r <rootdir>
    Set the root directory of your content (default /var/gopher).

-l <logfile>
    Enable logging to a file.

-b <basename>
    Use filename instead of ".gopher" (appending .rec for ".gopher.rec")

-P <peer>
    Specify connection peer IP/name (for logging). If not specified, mgod will
    try to examine the stdin socket (fd 0) to get this information (and set
    it to "unknown" on failure).

-s <selector>
    Specify selector (instead of reading it from stdin as usual).


CONTENT


All normal files (that don't begin with '.') and directories under the root
dir are served and included in the menu. When the name begins with '.',
the file or directory is still served, but not included in the generated menu.
".gopher" and ".gopher.rec" files aren't served directly.
Files/directories not readable by all will not be served.

You can control menu generation by creating a file named ".gopher" in the
directory in question.

Along the path, every directory is checked for the existence of a file called
".gopher.rec" (for recursive). If it exists, it's read the same way as a
menu file. It can't contain any menu items or info lines, otherwise things
will break. However, you can set options perfectly well.

A menu file is included in the menu before the directory listing, each line
as an info line, unless the line begins with a special control character,
or the line contains one or more tab characters.

If the line contains tab characters, but no special control character at
the beginning, it is interpreted as a gopher menu line:
    info<TAB>selector<TAB>host<TAB>port

If 'port' is skipped, but 'host' is specified, 70 is filled in as port.
If both 'host' and 'port' is skipped, the line is considered 'local';
configured server host and port are filled in.

For local lines, if the selector doesn't begin with '/' or 'URL:', the
current path is prepended. If the selector begins with '/', it is considered
an absolute path (current path is not prepended, but the beginning '/' is
cut off).

In relative links, "." and ".." elements are supported and resolved.
Absolute links are not processed this way.

If the info field is empty, but the selector is specified, the directory entry
printing mechanism is invoked on the selector (unless it begins with 'URL:',
in which case the info field is filled in by the URL itself).

Special control characters (at the beginning of a line):

#
    Lines beginning with # are ignored.

"
    Use the rest as an info line (so you may have an info line beginning with
    any special character).

:
    Include the rest of the line directly in the menu. This is useful for
    external links. For example:

    :1Quux Gopher Site<TAB><TAB>gopher.quux.org<TAB>70

.
    Include the rest of the line directly in the menu; append server
    address and port. Useful for custom internal links. For example:

    .0About Us<TAB>aboutus.txt

`
    Works like ".", except the current path is prepended to the link.
    (Useful for relative links.)

!
    The rest of the line is interpreted as a special command.
    These can be:
    nolist   - disable automatic directory listing (so only the contents
                of .gopher will be visible in the menu)
    reverse  - reverse the direction of file sorting
    mtime    - sort by time of last modification instead of file name
    dirmixed - sort directories together with files (instead of placing
               them first)
    blog     - a hack: mtime is prepended to file descriptions
    include <file> - read file as a control file
    proc <command> - execute command, interpret output as control file
    limit [num]    - limit directory lists to n entries (def 20)

    summary [length] - first LENGTH (default 72) printable characters are
                       appended after text files as a summarizing info line

    dirproc <name> <command>
        Register a directory processor, interpreting output as a control file.
        (See below.)

    dirproc-raw <name> <command>
        Register a directory processor, passing output directly to the client.
        (See below.)

    For example to list files by mtime in reverse order:

    !reverse
    !mtime

=
    You can specify name aliases for entries of the file list.
    The format is:

    =Description<TAB>filename

    When a filename matching an alias is encountered, its description
    showing in the menu will be as given (instead of just the file name).
    If the description is an empty string, the file will be skipped
    altogether.


The server generates html redirect pages for URL:<url> style requests (as
the wikipedia article on gopher describes).

Files with the .g extension are included in the menu as menu files (type 1),
with the .g removed from the description. When serving such a file, it's opened
and processed as a control file.



DIRECTORY PROCESSORS


You can use external programs for generating gopher content.
These external programs can be specified using the "dirproc" and "dirproc-raw"
special commands, which are to be put in .gopher.rec files.

Explanation:
 ".gopher" files are only read when the menu for that one specific directory is
 requested, while ".gopher.rec" files are always read, from each directory from
 the server root to the directory of the requested selector.

 The dirproc commands establish "virtual selectors" under a directory; so to
 get them processed, you can't put them in the .gopher file for that directory,
 since that will only get read when that directory is directly requested in the
 selector.

When a directory processor is registered under a name, requests for that name,
and everything below a directory of such name will result in running the
specified command in the shell. The output of the command will either be
processed as a control file (when registered by "dirproc"), or passed on
to the client directly (when registered by "dirproc-raw").

Dirproc registrations only have effect in the directory where the .gopher.rec
file was processed (so they don't get inherited by subdirectories, like
all other commands in .gopher.rec files do).

The program run by the shell command will have access to some environment
variables:

 QUERY
  This will contain the section of the selected path starting with the
  processor name. So if the processor was registered as "a/b/c/proc",
  and the request was made for "a/b/c/proc/x", QUERY will be "proc/x".

 PEER
  IP/name of the connected peer (might be "unknown").

 SEARCH
  When a search argument was received, this env will be set to that string.

When executing the command, the current directory will be the directory
where the processor was registered.


HTTPGATE

httpgate.c is a small CGI program that provides a HTTP gateway for your gopher
content. It calls mgod directly to obtain the data.

To use it, copy httpgate.cfg.h.sample to httpgate.cfg.h, and edit it for
configuration (such as the path to the mgod executable). Then compile httpgate
("make httpgate"). Finally, set up your web server to use the resulting file
as a CGI.