GEOMYIDAE(8)

NAME
Geomyidae - a gopher daemon for Linux/BSD

SYNOPSIS
Geomyidae [-d] [-l logfile] [-v loglevel] [-b base] [-p port] [-o sport] [-u user] [-g group] [-h host] [-i IP]

DESCRIPTION
Geomyidae is a daemon for serving the protocol specified in RFC 1436 (Gopher). Under 1000 lines of C by design, it is lightweight yet supports dynamic content, automatic file/directory indexing, logging and privilege separation.

IMPLEMENTATION
Installation is straightforward: grab the zipped tar file, expand it in an appropriate temp directory, change to the "../Geomyidae-x.xx" directory, tweak the Makefile if desired (installs in "/usr/bin" by default), then run the ‘make ; make install’ commands. The resulting executable should be run by root.

  Installation example:

         % wget http://www.r-36.net/Geomyidae-0.12.tgz;
         % tar -xzvf Geomyidae-0.12.tgz;
         % cd Geomyidae-0.12;
         % make; sudo make install;
         % sudo mkdir -p /var/gopher;
         % sudo cp index.gph /var/gopher;
         % sudo Geomyidae -l /var/log/geomyidae.log -b /var/gopher -p 70;
         % tail -f /var/log/geomyidae.log;
         #
         # Use whatever gopher client you like to gopher to
         # gopher://localhost
         #
         # Have fun!

  Running
Geomyidae should normally be started by root. Though, it can be started by a regular user provided that the base directory and its contents are owned by the same user. Geomyidae will only serve content within the base directory tree and will drop privileges to the -u user and -g group values if set. See OPTIONS below for specifics.

OPTIONS
Geomyidae options and default settings:

-d  Don't fork into background.

-l logfile
    Specify the file where the log output will be written (default: no default).

-v loglevel
    Set the logging level (default: 15).

        Loglevels:
                0 - no logging
                1 - served plain files
                2 - directory listings
                4 - HTTP redirects
                8 - errors (e.g., not found)
          e.g.:
                1 + 2 + 4 + 8 = 15
                (files + directories + HTTP + errors)

-b base
    Root directory to serve (default: /var/gopher)

-p port
    Port Geomyidae should listen on (default: 70)

-o sport
    Port Geomyidae displays within base directory (default: 70). Use in conjunction with -p for obfuscating actual port Geomyidae is running on.

-u user
    Sets the user to which privileges drop when Geomyidae is ready to accept network connections (default: user Geomyidae runs as). Helps improve security by reducing privileges during request processing.

-g group
    Sets the group to which privileges drop when Geomyidae is ready to accept network connections (default: group Geomyidae runs as). Helps improve security by reducing privileges during request processing.

-h host
    Host to use in directory listings (default: localhost)

-i IP
    IP to which Geomyidae binds to (default: 127.0.0.1)

FORMATTING
Structured Gopher space(s) can be created with Geomyidae through the use of special indexing files of the form <name>.gph which, if present, Geomyidae uses to format and/or filter the contents of the base directory (/var/gopher by default) and create gopher menus. However, index files are not required: if no .gph files are found Geomyidae simply lists the directory contents in alphanumeric order. In addition, a directory can utilize multiple index files to create a layered gopher environment without the use of sub-directories: ie. pictures.gph, music.gph, documents.gph could be "directories" within main.gph, yet all reside in /var/gopher along with their respective files (*.jpg, *.mp3, *.pdf for example).

  Anatomy of an index.gph file
In general, each line of an index.gph file has the following structure:

[<type>|<desc>|<path>|<port>]

where,

<type> = A valid gopher Item Type.

Some common Gopher Types as defined in RFC 1436 :

     0   Item is a file
     1   Gopher directory
     3   Error
     7   Item is an Index-Search server.
     8   Item points to a text-based telnet session.
     9   Binary file. Client reads until TCP connection closes!
     g   GIF format graphics file.
     I   Indeterminate image file. Client decides how to display.

In addition, Geomyidae provides these:

     h   Item is a hypertext (HTTP) link
     i   Informational Item (used for descriptive purposes)

Note: Geomyidae doesn't require "informational" text to be formally Typed as "[i|...]"; any line not beginning with "[" is treated as informational, greatly simplifying the formatting of index.gph files.

<desc> = description of gopher item. Most printable characters should work.

<path> = full path to gopher item (base value is / ). Use the "Err" path for items not intended to be served.

<host> = hostname or IP hosting the gopher item. Must be resolvable for the intended clients.

<port> = TCP port number ( usually 70) May be omitted if defaults are used.

  index.gph Example
A root.gph file for a server running on host=frog.bog, port=70. Note use of optional [i]nformational Item (line 2) for vertical space insertion:

    Welcome to Frog.bog
    [i||||]
    [0|About this server|about.txt|frog.bog|70]
    [0|Daily Log|/dtail.cgi|frog.bog|70]
    [1|Phlog: like a blog, but not|/PHLOG|frog.bog|70]
    [9|Some binary file|widget.exe|frog.bog|70]
    [I|Snowflake picture|snowflake.jpg|frog.bog|70]
    Links and Searches
    [1|Go to R-36.net|/|gopher.r-36.net|70]
    [h|Go to NetBSD.org|URL:http://netbsd.org|frog.bog|70]
    [7|Query US Weather by Zipcode|/weather.cgi?|frog.bog|70]
    [7|Search Veronica II|/v2/vs|gopher.floodgap.com|70]
    [8|Telnet to SDF Public Access Unix System||freeshell.org|23]

The above looks something like this in a text-based gopher client:

Welcome to Frog.bog

(FILE)
    About this server
(FILE)
    Daily Log
(DIR)
    Phlog: like a blog, but not
(BIN)
    Some binary file
(IMG)
    Snowflake picture

Links and Searches
(DIR)
    Go to R-36.net
(HTML)
    Go to NetBSD.org
(?) Query US Weather by Zipcode
(?) Search Veronica II
(TEL)
    Telnet to SDF Public Access Unix System

USING DYNAMIC CONTENT
Dynamic content can be generated under Geomyidae by simply creating a file in for form of <name>.cgi in a directory that is being served. Such files are run as a shell script. (See below for description.)

ex. dtail.cgi - prints daily log entries

    #!/bin/sh -e
    echo "Logged activity for `date '+%A, %B %d, %Y'` :"
    echo "==============================================="
    LOG="/var/log/gopherd.log"
    DATE=`date "+%a %b %d"`
    /usr/bin/grep "$DATE" $LOG
    exit 0

Geomyidae supports two variable queries. The basic form is

    executable.cgi{argv[1]}?{argv[2]}

where

    argv[1] = strings (everything before the '?' in the query)
    argv[2] = arguments (everything behind the '?' in the query)

A search query request must have an item Type of "7" to be called from an index.gph file. It may also need a "?" suffix in the <path> field.

ex. hello.cgi - say hello to user

    #!/bin/sh
    NAME=$1
    echo ""
    echo Hello $NAME - welcome to Frog.bog
    exit 0

Call the above with the following index.gph entry:

    [7|Hello You - Please enter your name|/hello.cgi?|frog.bog|70]

And do a simple snarf(1) query:

    % snarf "gopher://frog.bog/7/hello.cgi?Christoph" -
    Hello Christoph - welcome to Frog.bog
    %

LOG FILES

The log file (/var/log/gopherd.log is default) has the following structure:

[<date>|<IP:port>] <item path> <query> (<status>)

where,

<date> = access date and time (std 'date' format)

ex. "Sun Feb 17 06:11:10 PST 2008"

<IP:port> = client IP address and port served

ex. "24.208.18.127:16857"

<item path> = full path to item served

ex.
    "/PICS/simple2.jpg" for an image file
    "/PICS" for a directory access

<query> = query term submitted (Type 7 requests only)

ex.
    % snarf "gopher://frog.bog/7/hello.cgi?Christoph"
    would log "Christoph" as the query term.

(<status>) = status of client request

ex. - some common status entries:

"(serving)"
    => a successful request
"(not found)"
    => an unsuccessful request
"(HTTP redirect)"
    => web link redirect (Type h)
"(dir listing)"
    => unindexed directory listing

FILES
README, LICENSE, index.gph

SEE ALSO
Links for further information on gopher:

    gopher://gopher.gopherproject.org
    http://www.gopherproject.org

STANDARDS
Internet RFC 1436

HISTORY
Geomyidae started as a Linux/BSD port of the Plan 9 gopherd_P9 server. Originally called gopherd_BSD, the name was later changed to Geomyidae (latin), the taxonomic family of burrowing rodents known as "pocket gophers" which are in fact the true gophers.

AUTHORS
Geomyidae written by:
    Christoph Lohmann <20h@R-36.net>

Manpage written by:
    Jeff Woodall <jgw@freeshell.org>

LICENSE
Geomyidae is public domain software with the following provision: the GPL Version 2 (GPL-2) license applies if someone decides to release and/or sell original or modified versions of Geomyidae without crediting the original developer(s). A copy of GPL-2 is available at either http://www.gnu.org/licenses/gpl-2.0.html or http://www.opensource.org

BUGS
Geomyidae occasionally aborts silently if too many simultaneous requests are made. Limiting gopher traffic via firewall rules may help.

Dynamic content functionality may vary across gopher clients.

  Reporting Bugs
Report bugs to: Christoph Lohmann <20h@R-36.net>