GEOMYIDAE

Provided by Geomyidae package
Section: Maintenance Commands (8)
Index Return to Main Contents

BSD mandoc

NAME

geomyidae - a gopher daemon for Linux/BSD

SYNOPSIS

-words [-4 ] [-6 ] [-c ] [-d ] [-e ] [-n ] [-l logfile ] [-v loglevel ] [-b base ] [-p port ] [-o sport ] [-u user ] [-g group ] [-h host ] [-i interface ... ]

DESCRIPTION

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 Qq ../geomyidae-x.xx directory, tweak the Makefile if desired (installs in Qq /usr/bin by default), then run the ‘make ; make install’ commands. The resulting executable should be run by root.

Basic Installation and Startup:


     % wget http://www.r-36.net/src/geomyidae/geomyidae-current.tgz;
     % tar -xzvf geomyidae-*.tgz;
     % cd geomyidae-*;
     % 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 (ie. lynx) to browse:
     % lynx gopher://localhost

Running

geomyidae should normally be started by root, although 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. Launching geomyidae automatically is best done via a UNIX run-time (rc.d) script; several sample rc.d scripts are included in the geomyidae source archive.

OPTIONS

geomyidae options and default settings:

-4

Only use IPv4.

-6

Only use IPv6.

-c

Use chroot(2) for the base directory (by default off).

-d

Don't fork into background. If no log file is given, this implies logging to the standard output.

-e

Disable execution of any CGI or DCGI script.

-n

Don't perform reverse lookups.

-l logfile

Specify file where log output is written (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)
        16 - client connections
  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 interface

Defines the interface to which geomyidae binds to (default: 0.0.0.0). Multiple interfaces can be given.

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 index.gph, index.cgi or index.dcgi file is 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>|<host>|<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)

Unknown file types default to Type "9" (binary).

<desc>

= description of gopher item. Most printable characters should work.

<path>

= full or relative path to gopher item (base value is Qq / ). Use the Qq Err path for items not intended to be served.

<host>

= hostname or IP hosting the gopher item. Must be resolvable for the intended clients. If this is set to Qq server , the server's hostname is used.

<port>

= TCP port number (usually 70) If this is set to Qq port , the default port of the server is used.

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. However, if a line begins with a "t", this "t" is left out. This quirk is there to allow "informational" text lines beginning with a "[" to display. For dynamically generated index files it may be desirable to either formally Type informational text or run it through a filter to add a second "t" - .ie sed 's/^t/&&/' . Note 2: You can escape a pipe ("|") character in for example a <desc> field by prepending a slash ("\"). Note 3: The gph parser is very forgiving. If the link structure is not parsed correctly, then the original line is printed.

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||Err||]
[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]
ttry our snowflakes!

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|null|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 try our snowflakes!

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

DYNAMIC CONTENT (gopher CGI)

There are two options provided for dynamic content creation: standard CGI ( .cgi ) and dynamic CGI ( .dcgi ). Despite the names, both can accept input and generate dynamic content; the only difference is the latter re-formats it's output so it appears to the server as a standard geomyidae index (.gph) file. This makes the creation of on-the-fly gopher directories much easier (see examples). All scripts must be under the gopher root directory and be executable by the same user:group running geomyidae. Consequently, it is best to use the -u and -g server options to avoid running as root.

Both .cgi and .dcgi scripts have the same argument call structure (as seen by geomyidae):

where

All terms are tab-separated (per gopher protocol) which can cause some surprises depending on how a script is written. See the CGI file (included in the geomyidae source archive) for further elaboration.

QUIRK: The original gopher client tried to be too intelligent. It is using gopher+ when you request some resource. When "search" is just the value "+", "!", "$" or empty, geomyidae will display a gopher+ redirect instead of invoking the script. Be careful to design your search script so the user is unlikely to enter those values. The designers of gopher+ did not think of classic gopher to survive. It survived gopher+.

Additionally to the above arguments several environment variables are set.

GATEWAY_INTERFACE = `CGI/1.1'

PATH_INFO = script which is executed

PATH_TRANSLATED = absolute path with script which is executed

QUERY_STRING = arguments (See above.)

REMOTE_ADDR = IP of the client

REMOTE_HOST = REMOTE_ADDR

REQUEST_METHOD = `GET'

SCRIPT_NAME = script which is executed

SERVER_NAME = server's hostname

SERVER_PORT = server's port

SERVER_PROTOCOL = `gopher/1.0'

SERVER_SOFTWARE = `geomyidae'

X_GOPHER_SEARCH = search (See above.)

Some CGI Examples

Note: these are a very simple examples with no fitness checks with respect to safety/security.

ex. uptime.cgi - standard CGI, no queries

#!/bin/sh
#  uptime.cgi - prints system uptime(1)
/usr/bin/uptime
exit 0

Call the above with the following index.gph entry:

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

ex. hello.cgi - standard CGI with query

#!/bin/sh
#  hello.cgi - welcome user
NAME=$1
HOSTNAME=$2
echo ""
echo Hello $NAME - welcome to $HOSTNAME
exit 0

Call the above with the following index.gph entry:

And do a simple snarf(1) query (note the inserted TAB):

Dynamic CGI entries are similar to above except that the script needs to create output as described in the FORMATTING section:

ex. jughead.dcgi - dynamic CGI script with query

#!/bin/sh
# jughead.dcgi - jughead-like local gopher search
KWRD="$1"
ARCHIVE="/var/gopher/textfiles/"
echo "[i|Search results for \"${KWRD}\":|Err||]"
echo "[i||Err||]"
# grep(1) recursive, case-insensitive KWRD search of ARCHIVE:
for RESULT in $(/usr/bin/grep -i -l -m1 ${KWRD} -r $ARCHIVE)
do
        DESC=$(/usr/bin/basename ${RESULT})
        PATH=$(echo "$RESULT" | /usr/bin/sed 's/^\/var\/gopher//')
        echo "[0|${DESC}|${PATH}|frog.bog|70]"
done
exit 0

Call the above with the following index.gph entry:

A successful query might look like this:

Search results for Qo fubar Qc :
(FILE): How_Things_Break.txt
(FILE): Origins_of_Words.txt
(FILE): Phrases_of_the_Ages.txt

Care should to be exercised to avoid creating miss-Typed entries, unwanted recursions, and/or unintended writes in the working directory.

LOG FILES

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

[<date>|<IP/Host>|<port>|<status>] <item path>

where,

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

ex. Qq 2018-01-31 14:18:34 +0000
<IP/Host>: = client IP/Host served
ex. Qq 104.23.33.1
<port>: = client port served
ex. Qq 16857
<status>: = status of client request
ex. - some common status entries:
Qo serving Qc => a successful request
Qo not found Qc => an unsuccessful request
Qo HTTP redirect Qc => web link redirect (Type h)
Qo dir listing Qc => unindexed directory listing
<item path>: = full path to item served
ex.

FILES

README, LICENSE, CGI, index.gph, rc.d/, LINKS, gph/

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. Due to inconsistencies and the UNIX culture, the name was changed to lowercase in 2010.

AUTHORS

See LICENSE file for authors in the distribution.

LICENSE

geomyidae is released under the MIT/X Consortium License.

BUGS

Dynamic content functionality may vary across gopher clients.

Reporting Bugs

Report bugs to: An Christoph Lohmann Aq 20h@R-36.net

SliTaz Man Pages

GEOMYIDAE

NAME

SYNOPSIS

DESCRIPTION

IMPLEMENTATION

Basic Installation and Startup:

Running

OPTIONS

FORMATTING

Anatomy of an index.gph file

index.gph Example

DYNAMIC CONTENT (gopher CGI)

Some CGI Examples

LOG FILES

FILES

SEE ALSO

STANDARDS

HISTORY

AUTHORS

LICENSE

BUGS

Reporting Bugs

Index