mand

.\" geomyidae.8 handcrafted in GNU groff -mdoc using nvi
.\"
.Dd February 23, 2020
.Dt GEOMYIDAE 8
.Os
.
.Sh NAME
.Nm geomyidae
.Nd a gopher daemon for Linux/BSD
.
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl 4
.Op Fl 6
.Op Fl c
.Op Fl d
.Op Fl e
.Op Fl n
.Op Fl l Ar logfile
.Op Fl v Ar loglevel
.Op Fl b Ar base
.Op Fl p Ar port
.Op Fl o Ar sport
.Op Fl u Ar user
.Op Fl g Ar group
.Op Fl h Ar host
.Op Fl i Ar interface ...
.Op Fl t Ar keyfile certfile
.Ek
.
.Sh DESCRIPTION
.Bd -filled
.Nm
is a daemon for serving the protocol specified in
.Em 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.
.Ed
.
.Sh IMPLEMENTATION
.Bd -filled
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
.Sq "make ; make install"
commands.  The resulting executable should be run by root.
.Ed
.
.Ss Basic Installation and Startup:
.Bd -literal

     $ 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
.Ed
.
.Ss 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
.Fl u Ar user
and
.Fl g Ar group
values if set.  See
.Ic 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.
.
.Sh OPTIONS
geomyidae options and default settings:
.Bl -tag -width Ds
.
.It Fl 4
Only use IPv4.
.
.It Fl 6
Only use IPv6.
.
.It Fl c
Use
.Xr chroot 2
for the
.Ar base
directory (by default off).
.
.It Fl d
Don't fork into background. If no log file is given, this implies logging to
the standard output.
.
.It Fl e
Disable execution of any CGI or DCGI script.
.
.It Fl n
Don't perform reverse lookups.
.
.It Fl l Ar logfile
Specify file where log output is written (no default).
.
.It Fl v Ar loglevel
Set the logging level (default: 47).
.
.Bd -literal
Loglevels:
        0  - no logging
        1  - served plain files
        2  - directory listings
        4  - HTTP redirects
        8  - errors (e.g., not found)
        16 - client connections
        32 - gopher+ redirects
  e.g.:
        1 + 2 + 4 + 8 + 32 = 47
        (files + directories + HTTP + errors + gopher+)
.Ed
.
.It Fl b Ar base
Root directory to serve (default: /var/gopher).
.
.It Fl p Ar port
Port geomyidae should listen on (default: 70).
.
.It Fl o Ar sport
Port geomyidae displays within base directory (default: 70).
Use in conjunction with
.Ic -p
for obfuscating actual port geomyidae is running on.
.
.It Fl u Ar 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.
.
.It Fl g Ar 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.
.
.It Fl h Ar host
Host to use in directory listings (default: localhost).
.
.It Fl i Ar interface
Defines the interface to which geomyidae binds to (default: 0.0.0.0).
Multiple interfaces can be given.
.
.It Fl t Ar keyfile certfile
Activate gopher TLS and use the private key
.Ar keyfile
and the public key
.Ar certfile
for TLS connections (if the feature is compiled in.)
.El
.
.Sh FORMATTING
.Bd -filled
Structured Gopher space(s) can be created with geomyidae through the
use of special indexing files of the form
.Ic <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
.Em 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).
.Ed
.
.Ss Anatomy of an index.gph file
A gph file consists of informational text and links. A link has the form:
.Bl -inset -offset indent
.It Ic [<type>|<desc>|<path>|<host>|<port>]
.El
.Pp
where,
.Bl -inset -offset indent
.It Ic <type>
= A valid gopher Item Type.
.Pp
Some common Gopher Types as defined in
.Em RFC 1436
:
.
.Bd -literal
 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.
.Ed
.Pp
In addition, geomyidae provides these:
.Bd -literal
 h   Item is a hypertext (HTTP) link.
 i   Informational Item (used for descriptive purposes).
.Ed
.
.Bd -filled
Unknown file types default to Type "9" (binary).
.Ed
.
.It Ic <desc>
= description of gopher item. Most printable characters should work.
.
.It Ic <path>
= full or relative path to gopher item (base value is
.Qq "/"
). Use the
.Qq "Err"
path for items not intended to be served.
.
.It Ic <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.
.
.It Ic <port>
= TCP port number (usually 70).
.
If this is set to
.Qq "port"
, the default port of the server is used.
.El
.
.Bd -filled
Note: geomyidae doesn't require "informational" text to be formally
Typed as "[i|...]"; any line
.Em 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/&&/' .
.Ed
.Bd -filled
Note 2: You can escape a pipe ("|") character in for example a
.Em <desc>
field by prepending a slash ("\\").
.Ed
.Bd -filled
Note 3: The gph parser is very forgiving. If the link structure is not parsed
correctly, then the original line is printed.
.Ed
.
.Ss 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:
.Bd -literal -offset indent
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]
.Ed
.
.Pp
The above looks something like this in a text-based gopher client:
.Pp
.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
.It Ic Welcome to Frog.bog
.Pp
.It Ic (FILE)
About this server
.It Ic (FILE)
Daily Log
.It Ic (DIR)
Phlog: like a blog, but not
.It Ic (BIN)
Some binary file
.It Ic (IMG)
Snowflake picture
.Pp
try our snowflakes!
.El
.Pp
.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
.It Ic Links and Searches
.It Ic (DIR)
Go to R-36.net
.It Ic (HTML)
Go to NetBSD.org
.It Ic (?)
Query US Weather by Zipcode
.It Ic (?)
Search Veronica II
.It Ic (TEL)
Telnet to SDF Public Access Unix System
.El
.Sh DYNAMIC CONTENT (gopher CGI)
.Bd -filled
There are two options provided for dynamic content creation: standard CGI (
.Ic .cgi
) and dynamic CGI
(
.Ic .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.
.Pp
Both .cgi and .dcgi scripts have the same argument call structure (as seen by geomyidae):
.Pp
.D1  executable.[d]cgi $search $arguments $host $port
.Pp
where
.Pp
.D1 search = query string (type 7) or Qo Qc (type 0)
.D1 arguments = string after Qo ? Qc in the path or Qo Qc
.D1 host = server's hostname ("localhost" by default)
.D1 port = server's port ("70" by default)
.Pp
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.
.Pp
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+.
.Pp
Additionally to the above arguments several environment variables are set.
.Pp
.Dl GATEWAY_INTERFACE = `CGI/1.1'
.Dl PATH_INFO = script which is executed
.Dl PATH_TRANSLATED = absolute path with script which is executed
.Dl QUERY_STRING = arguments (See above.)
.Dl SELECTOR = arguments (For backwards compatibility.)
.Dl REQUEST = arguments (For backwards compatibility.)
.Dl REMOTE_ADDR = IP of the client
.Dl REMOTE_HOST = REMOTE_ADDR
.Dl REQUEST_METHOD = `GET'
.Dl SCRIPT_NAME = script which is executed
.Dl SERVER_NAME = server's hostname
.Dl SERVER_PORT = server's port
.Dl SERVER_PROTOCOL = `gopher/1.0'
.Dl SERVER_SOFTWARE = `geomyidae'
.Dl X_GOPHER_SEARCH = search (See above.)
.Dl SEARCHREQUEST = search (For backwards compatibility.)
.Dl HTTPS and GOPHERS = set, if TLS is used
.Pp
.Ed
.
.Ss Some CGI Examples
Note: these are a very simple examples with no fitness checks with respect
to safety/security.
.Pp
ex. uptime.cgi - standard CGI, no queries
.
.Bd -literal -offset indent
#!/bin/sh
#  uptime.cgi - prints system uptime(1)
/usr/bin/uptime
exit 0
.Ed
.
.Pp
Call the above with the following index.gph entry:
.Pp
.D1 [0|System Uptime|/uptime.cgi|frog.bog|70]
.Pp
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:
.Pp
ex. hello.cgi - standard CGI with query
.
.Bd -literal -offset indent
#!/bin/sh
#  hello.cgi - welcome user
NAME=$1
HOSTNAME=$2
echo ""
echo Hello $NAME - welcome to $HOSTNAME
exit 0
.Ed
.
.Pp
Call the above with the following index.gph entry:
.Pp
.D1 [7|Hello You - Please enter your name|/hello.cgi?FROG.bog|frog.bog|70]
.
.Pp
And do a simple
.Xr snarf 1
query (note the inserted TAB):
.Pp
.D1 % snarf Qo gopher://frog.bog/7/hello.cgi?FROG.bog[TAB]Christoph Qc -
.D1 Hello Christoph - welcome to FROG.bog
.
.Pp
Dynamic CGI entries are similar to above except that the script
needs to create output as described in the
.Ic FORMATTING
section:
.Pp
ex. jughead.dcgi - dynamic CGI script with query
.
.Bd -literal -offset indent
#!/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
.Ed
.
.Pp
Call the above with the following index.gph entry:
.Pp
.D1 [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
.Pp
A successful query might look like this:
.Pp
.Bl -tag -width Ds -compact -offset indent
.It Search results for Qo fubar Qc :
.Pp
.It Ic (FILE)
How_Things_Break.txt
.It Ic (FILE)
Origins_of_Words.txt
.It Ic (FILE)
Phrases_of_the_Ages.txt
.El
.
.Pp
Care should to be exercised to avoid creating miss-Typed entries, unwanted
recursions, and/or unintended writes in the working directory.
.Sh LOG FILES
The log file (ie. /var/log/gopherd.log) has the following structure:
.
.Pp
.Ic [<date>|<IP/Host>|<port>|<status>] <item path>
.
.Pp
where,
.
.Bl -inset
.It Ic <date>
= access date and time (std 'date' format)
.Pp
 ex.
.Qq "2018-01-31 14:18:34 +0000"
.It Ic <IP/Host>
= client IP/Host served
.Pp
ex.
.Qq "104.23.33.1"
.It Ic <port>
= client port served
.Pp
ex.
.Qq "16857"
.It Ic <status>
= status of client request
.Pp
ex. - some common status entries:
.It Qo serving Qc
=> a successful request
.It Qo not found Qc
=> an unsuccessful request
.It Qo HTTP redirect Qc
=> web link redirect (Type h)
.It Qo dir listing Qc
=> unindexed directory listing
.Pp
.It Ic <item path>
= full path to item served
.Pp
ex.
.D1 Qo "/PICS/simple2.jpg" Qc for an image file
.D1 Qo "/PICS" Qc for a directory access
.El
.
.Sh FILES
README, LICENSE, CGI, index.gph, rc.d/, LINKS, gph/
.
.Sh SEE ALSO
Links for further information on gopher:
.Pp
.D1 Pa gopher://gopher.floodgap.com
.D1 Pa gopher://gopherproject.org
.Sh STANDARDS
.Em Internet RFC 1436
.
.Sh HISTORY
.Bd -filled
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.
.Ed
.
.Sh AUTHORS
See LICENSE file for authors in the distribution.
.
.Sh LICENSE
geomyidae is released under the MIT/X Consortium License.
.
.Sh BUGS
Dynamic content functionality may vary across gopher clients.
.
.Ss "Reporting Bugs"
Report bugs to:
.An "Christoph Lohmann" Aq 20h@R-36.net