Main | Name:

GEOMYIDAE(8)                System Manager's Manual               GEOMYIDAE(8)

NAME
     geomyidae - a gopher daemon for Linux/BSD

SYNOPSIS
     geomyidae [-4] [-6] [-c] [-d] [-e] [-n] [-s] [-y] [-l logfile]
               [-v loglevel] [-b base] [-p port] [-o sport] [-u user]
               [-g group] [-h host] [-i interface ...] [-t keyfile certfile]

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.

   Basic Installation and Startup
          $ wget ftp://bitreich.org/releases/geomyidae/geomyidae-$VERSION.tar.lz
          $ lzip -d geomyidae-$VERSION.tar.lz
          $ tar -xvf geomyidae-*.tar
          $ 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. sacc) to browse:
          $ sacc 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. Logging
     in geomyidae can be done through either logfiles or syslog.

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      Perform reverse lookups.

     -s      Log using syslog for logging.

     -y      Enable HAProxy support.

     -l logfile
             Specify file where log output is written (no default).

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

             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+)

     -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.

     -t keyfile certfile
             Activate gopher TLS and use the private key keyfile and the
             public key certfile for TLS connections (if the feature is
             compiled in.) See ENCRYPTION ONLY support below.

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
     A gph file consists of informational text and links. A link has the form:

           [<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 "/" ).
           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. If this is set to "server" , the server's
           hostname is used.

           <port> = TCP port number (usually 70).  If this is set to "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. If
     you want to display some informational text beginning with "[" you can
     use the special case of an empty item type. "[|[some link" will be
     shortened to "[some link". For dynamically generated content it may be
     desirable to either formally type informational text or run it through a
     filter to prepend "[|" - .ie sed 's,^[,[|&,' .

     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 and a special
     case: standard CGI ( .cgi ), dynamic CGI ( .dcgi ) and HTTP compatibility
     mode.  Despite the names, all three can accept input and generate dynamic
     content; the only difference is that dcgi 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.

     Executed scripts get the full I/O of the socket bound to stdin and
     stdout. You are thus able to write long-lasting streaming services. Radio
     or TV stations over gopher are possible that way.

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

           executable.[d]cgi $search $arguments $host $port $traversal $selector

     where

           search = query string (type 7) or "" (type 0)
           arguments = string behind "?" in selector or ""
           host = server's hostname ("localhost" by default)
           port = server's port ("70" by default)
           traversal = remaining path from path traversal in REST case
           selector = raw selector or full req (See HTTP compatibility mode.)

     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.

     For a special REST path case for the arguments, see the CGI file for the
     description.

     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.)
           SELECTOR = raw selector
           REQUEST = raw selector
           TRAVERSAL = traversal (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_LISTEN_NAME = ip the server received the connection on
           SERVER_PROTOCOL = `gopher/1.0'
           SERVER_SOFTWARE = `geomyidae'
           X_GOPHER_SEARCH = search (See above.)
           SEARCHREQUEST = search (For backwards compatibility.)
           HTTPS and GOPHERS = set, if TLS is used

   The REST path handling
     If a client requests a path in a selector, which has no corresponding
     file or path found, geomyidae will try to traverse from the -b base path
     until a path component / directory is not found. Then geomyidae tries to
     find some index.dcgi or index.cgi file in the last existing directory. If
     this is found and the index files are executable, geomyidae will execute
     them using the traversal and TRAVERSAL parameter and environment variable
     being set to the rest path.

           Selector: /some/v1/service/add/something?args=value
           -> /some/v1/service exists
           -> /some/v1/service/index.dcgi exists
           -> /some/v1/service/index.dcgi "" "args=value" $host $port
           "/add/something" "/some/v1/service/add/something?args=value" is called

   HTTP compatibility
     For maximum flexibility in case someone sends a HTTP request to gopher,
     geomyidae supports a special case of CGI. See this example:

           Client request: GET /some/path HTTP/1.1
           -> /GET exists and is executable
           -> /GET "" "" $host $port "" "GET /some/path HTTP/1.1" is called

     This allows for example simple scripts for icecast upload compatibility
     or handling transparent HTTP right next to gopher, getting TLS for free.

   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:

           [0|System Uptime|/uptime.cgi|frog.bog|70]

     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:

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

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

           % snarf "gopher://frog.bog/7/hello.cgi?FROG.bog[TAB]Christoph" -
           Hello Christoph - welcome to FROG.bog

     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:

           [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]

     A successful query might look like this:

           Search results for "fubar":

           (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.

HAPROXY SUPPORT
     geomyidae has HAProxy support. It can be enabled using the -y parameter.

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.  "2018-01-31 14:18:34 +0000"

     <IP/Host> = client IP/Host served

     ex.  "104.23.33.1"

     <port> = client port served

     ex.  "16857"

     <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

     <item path> = full path to item served

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

ENCRYPTION ONLY
     If you set the sticky bit (chmod +t) on some file or directory, geomyidae
     will only serve it over an encrypted connection. There is the special
     case, that when the sticky bit is set on the base directory, all content
     will only be served over tls.

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

SEE ALSO
     Links for further information on gopher:

           gopher://gopher.floodgap.com
           gopher://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. 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: Christoph Lohmann <20h@R-36.net>

NetBSD 10.0                     March 17, 2021                     NetBSD 10.0

Generated by Keine 1.00