geomyidae

A small C-based gopherd. (gopher://bitreich.org/1/scm/geomyidae)
git clone git://r-36.net/geomyidae
Log | Files | Refs | README | LICENSE

geomyidae.8 (14839B)


      1 .\" geomyidae.8 handcrafted in GNU groff -mdoc using nvi
      2 .\"
      3 .Dd February 23, 2020
      4 .Dt GEOMYIDAE 8
      5 .Os
      6 .
      7 .Sh NAME
      8 .Nm geomyidae
      9 .Nd a gopher daemon for Linux/BSD
     10 .
     11 .Sh SYNOPSIS
     12 .Nm
     13 .Bk -words
     14 .Op Fl 4
     15 .Op Fl 6
     16 .Op Fl c
     17 .Op Fl d
     18 .Op Fl e
     19 .Op Fl n
     20 .Op Fl l Ar logfile
     21 .Op Fl v Ar loglevel
     22 .Op Fl b Ar base
     23 .Op Fl p Ar port
     24 .Op Fl o Ar sport
     25 .Op Fl u Ar user
     26 .Op Fl g Ar group
     27 .Op Fl h Ar host
     28 .Op Fl i Ar interface ...
     29 .Op Fl t Ar keyfile certfile
     30 .Ek
     31 .
     32 .Sh DESCRIPTION
     33 .Bd -filled
     34 .Nm
     35 is a daemon for serving the protocol specified in
     36 .Em RFC 1436
     37 (Gopher). Under 1000 lines of C by design, it is lightweight yet supports
     38 dynamic content, automatic file/directory indexing, logging and privilege
     39 separation.
     40 .Ed
     41 .
     42 .Sh IMPLEMENTATION
     43 .Bd -filled
     44 Installation is straightforward: grab the zipped tar file, expand it in
     45 an appropriate temp directory, change to the
     46 .Qq "../geomyidae-x.xx"
     47 directory, tweak the Makefile if desired (installs in
     48 .Qq "/usr/bin"
     49 by default), then run the
     50 .Sq "make ; make install"
     51 commands.  The resulting executable should be run by root.
     52 .Ed
     53 .
     54 .Ss Basic Installation and Startup:
     55 .Bd -literal
     56 
     57      $ wget http://www.r-36.net/src/geomyidae/geomyidae-current.tgz
     58      $ tar -xzvf geomyidae-*.tgz
     59      $ cd geomyidae-*
     60      $ make; sudo make install
     61      $ sudo mkdir -p /var/gopher
     62      $ sudo cp index.gph /var/gopher
     63      $ sudo geomyidae -l /var/log/geomyidae.log -b /var/gopher -p 70
     64      $ tail -f /var/log/geomyidae.log
     65 
     66      Use whatever gopher client you like (ie. lynx) to browse:
     67      $ lynx gopher://localhost
     68 .Ed
     69 .
     70 .Ss Running
     71 geomyidae should normally be started by root, although it can be started
     72 by a regular user provided that the base directory and its contents are owned
     73 by the same user.  geomyidae will only serve content within the base directory
     74 tree and will drop privileges to the
     75 .Fl u Ar user
     76 and
     77 .Fl g Ar group
     78 values if set.  See
     79 .Ic OPTIONS
     80 below for specifics.  Launching geomyidae automatically is best done via a UNIX
     81 run-time (rc.d) script; several sample rc.d scripts are included in the geomyidae
     82 source archive.
     83 .
     84 .Sh OPTIONS
     85 geomyidae options and default settings:
     86 .Bl -tag -width Ds
     87 .
     88 .It Fl 4
     89 Only use IPv4.
     90 .
     91 .It Fl 6
     92 Only use IPv6.
     93 .
     94 .It Fl c
     95 Use
     96 .Xr chroot 2
     97 for the
     98 .Ar base
     99 directory (by default off).
    100 .
    101 .It Fl d
    102 Don't fork into background. If no log file is given, this implies logging to
    103 the standard output.
    104 .
    105 .It Fl e
    106 Disable execution of any CGI or DCGI script.
    107 .
    108 .It Fl n
    109 Don't perform reverse lookups.
    110 .
    111 .It Fl l Ar logfile
    112 Specify file where log output is written (no default).
    113 .
    114 .It Fl v Ar loglevel
    115 Set the logging level (default: 47).
    116 .
    117 .Bd -literal
    118 Loglevels:
    119         0  - no logging
    120         1  - served plain files
    121         2  - directory listings
    122         4  - HTTP redirects
    123         8  - errors (e.g., not found)
    124         16 - client connections
    125         32 - gopher+ redirects
    126   e.g.:
    127         1 + 2 + 4 + 8 + 32 = 47
    128         (files + directories + HTTP + errors + gopher+)
    129 .Ed
    130 .
    131 .It Fl b Ar base
    132 Root directory to serve (default: /var/gopher).
    133 .
    134 .It Fl p Ar port
    135 Port geomyidae should listen on (default: 70).
    136 .
    137 .It Fl o Ar sport
    138 Port geomyidae displays within base directory (default: 70).
    139 Use in conjunction with
    140 .Ic -p
    141 for obfuscating actual port geomyidae is running on.
    142 .
    143 .It Fl u Ar user
    144 Sets the user to which privileges drop when geomyidae is ready
    145 to accept network connections (default: user geomyidae runs as).
    146 Helps improve security by reducing privileges during request
    147 processing.
    148 .
    149 .It Fl g Ar group
    150 Sets the group to which privileges drop when geomyidae is ready
    151 to accept network connections (default: group geomyidae runs as).
    152 Helps improve security by reducing privileges during request
    153 processing.
    154 .
    155 .It Fl h Ar host
    156 Host to use in directory listings (default: localhost).
    157 .
    158 .It Fl i Ar interface
    159 Defines the interface to which geomyidae binds to (default: 0.0.0.0).
    160 Multiple interfaces can be given.
    161 .
    162 .It Fl t Ar keyfile certfile
    163 Activate gopher TLS and use the private key
    164 .Ar keyfile
    165 and the public key
    166 .Ar certfile
    167 for TLS connections (if the feature is compiled in.)
    168 .El
    169 .
    170 .Sh FORMATTING
    171 .Bd -filled
    172 Structured Gopher space(s) can be created with geomyidae through the
    173 use of special indexing files of the form
    174 .Ic <name>.gph
    175 which, if present, geomyidae uses to format and/or filter the contents of
    176 the base directory (/var/gopher by default) and create gopher menus.
    177 However, index files are
    178 .Em not
    179 required: if no index.gph, index.cgi or index.dcgi
    180 file is found, geomyidae simply lists the directory
    181 contents in alphanumeric order.  In addition, a directory can utilize
    182 multiple index files to create a layered gopher environment without the
    183 use of sub-directories: ie. pictures.gph, music.gph, documents.gph could
    184 be "directories" within main.gph, yet all reside in /var/gopher along with
    185 their respective files (*.jpg, *.mp3, *.pdf for example).
    186 .Ed
    187 .
    188 .Ss Anatomy of an index.gph file
    189 A gph file consists of informational text and links. A link has the form:
    190 .Bl -inset -offset indent
    191 .It Ic [<type>|<desc>|<path>|<host>|<port>]
    192 .El
    193 .Pp
    194 where,
    195 .Bl -inset -offset indent
    196 .It Ic <type>
    197 = A valid gopher Item Type.
    198 .Pp
    199 Some common Gopher Types as defined in
    200 .Em RFC 1436
    201 :
    202 .
    203 .Bd -literal
    204  0   Item is a file.
    205  1   Gopher directory.
    206  3   Error.
    207  7   Item is an Index-Search server.
    208  8   Item points to a text-based telnet session.
    209  9   Binary file. Client reads until TCP connection closes!
    210  g   GIF format graphics file.
    211  I   Indeterminate image file. Client decides how to display.
    212 .Ed
    213 .Pp
    214 In addition, geomyidae provides these:
    215 .Bd -literal
    216  h   Item is a hypertext (HTTP) link.
    217  i   Informational Item (used for descriptive purposes).
    218 .Ed
    219 .
    220 .Bd -filled
    221 Unknown file types default to Type "9" (binary).
    222 .Ed
    223 .
    224 .It Ic <desc>
    225 = description of gopher item. Most printable characters should work.
    226 .
    227 .It Ic <path>
    228 = full or relative path to gopher item (base value is
    229 .Qq "/"
    230 ). Use the
    231 .Qq "Err"
    232 path for items not intended to be served.
    233 .
    234 .It Ic <host>
    235 = hostname or IP hosting the gopher item. Must be resolvable for the
    236 intended clients. If this is set to
    237 .Qq "server"
    238 , the server's hostname is used.
    239 .
    240 .It Ic <port>
    241 = TCP port number (usually 70).
    242 .
    243 If this is set to
    244 .Qq "port"
    245 , the default port of the server is used.
    246 .El
    247 .
    248 .Bd -filled
    249 Note: geomyidae doesn't require "informational" text to be formally
    250 Typed as "[i|...]"; any line
    251 .Em not
    252 beginning with "[" is treated as informational, greatly simplifying the
    253 formatting of index.gph files.  However, if a line begins with a "t", this
    254 "t" is left out.  This quirk is there to allow "informational" text lines
    255 beginning with a "[" to display.  For dynamically generated index files
    256 it may be desirable to either formally Type informational text or run
    257 it through a filter to add a second "t" - .ie sed 's/^t/&&/' .
    258 .Ed
    259 .Bd -filled
    260 Note 2: You can escape a pipe ("|") character in for example a
    261 .Em <desc>
    262 field by prepending a slash ("\\").
    263 .Ed
    264 .Bd -filled
    265 Note 3: The gph parser is very forgiving. If the link structure is not parsed
    266 correctly, then the original line is printed.
    267 .Ed
    268 .
    269 .Ss index.gph Example
    270 A root.gph file for a server running on host=frog.bog, port=70.  Note use
    271 of optional [i]nformational Item (line 2) for vertical space insertion:
    272 .Bd -literal -offset indent
    273 Welcome to Frog.bog
    274 [i||Err||]
    275 [0|About this server|about.txt|frog.bog|70]
    276 [0|Daily Log|/dtail.cgi|frog.bog|70]
    277 [1|Phlog: like a blog, but not|/PHLOG|frog.bog|70]
    278 [9|Some binary file|widget.exe|frog.bog|70]
    279 [I|Snowflake picture|snowflake.jpg|frog.bog|70]
    280 ttry our snowflakes!
    281 
    282 Links and Searches
    283 [1|Go to R-36.net|/|gopher.r-36.net|70]
    284 [h|Go to NetBSD.org|URL:http://netbsd.org|frog.bog|70]
    285 [7|Query US Weather by Zipcode|/weather.cgi?|frog.bog|70]
    286 [7|Search Veronica II|/v2/vs|gopher.floodgap.com|70]
    287 [8|Telnet to SDF Public Access Unix System|null|freeshell.org|23]
    288 .Ed
    289 .
    290 .Pp
    291 The above looks something like this in a text-based gopher client:
    292 .Pp
    293 .Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
    294 .It Ic Welcome to Frog.bog
    295 .Pp
    296 .It Ic (FILE)
    297 About this server
    298 .It Ic (FILE)
    299 Daily Log
    300 .It Ic (DIR)
    301 Phlog: like a blog, but not
    302 .It Ic (BIN)
    303 Some binary file
    304 .It Ic (IMG)
    305 Snowflake picture
    306 .Pp
    307 try our snowflakes!
    308 .El
    309 .Pp
    310 .Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
    311 .It Ic Links and Searches
    312 .It Ic (DIR)
    313 Go to R-36.net
    314 .It Ic (HTML)
    315 Go to NetBSD.org
    316 .It Ic (?)
    317 Query US Weather by Zipcode
    318 .It Ic (?)
    319 Search Veronica II
    320 .It Ic (TEL)
    321 Telnet to SDF Public Access Unix System
    322 .El
    323 .Sh DYNAMIC CONTENT (gopher CGI)
    324 .Bd -filled
    325 There are two options provided for dynamic content creation: standard CGI (
    326 .Ic .cgi
    327 ) and dynamic CGI
    328 (
    329 .Ic .dcgi
    330 ). Despite the names, both can accept input and generate dynamic content;
    331 the only difference is the latter re-formats it's output so it appears to
    332 the server as a standard geomyidae index (.gph) file. This makes the
    333 creation of on-the-fly gopher directories much easier (see examples).
    334 All scripts must be under the gopher root directory and be executable by
    335 the same user:group running geomyidae.  Consequently, it is best to use
    336 the -u and -g server options to avoid running as root.
    337 .Pp
    338 Both .cgi and .dcgi scripts have the same argument call structure (as seen by geomyidae):
    339 .Pp
    340 .D1  executable.[d]cgi $search $arguments $host $port
    341 .Pp
    342 where
    343 .Pp
    344 .D1 search = query string (type 7) or Qo Qc (type 0)
    345 .D1 arguments = string after Qo ? Qc in the path or Qo Qc
    346 .D1 host = server's hostname ("localhost" by default)
    347 .D1 port = server's port ("70" by default)
    348 .Pp
    349 All terms are tab-separated (per gopher protocol) which can cause some
    350 surprises depending on how a script is written.  See the CGI file (included
    351 in the geomyidae source archive) for further elaboration.
    352 .Pp
    353 QUIRK: The original gopher client tried to be too intelligent. It is using
    354 gopher+ when you request some resource. When "search" is just the value "+",
    355 "!", "$" or empty, geomyidae will display a gopher+ redirect instead of invoking the
    356 script. Be careful to design your search script so the user is unlikely to
    357 enter those values. The designers of gopher+ did not think of classic gopher
    358 to survive. It survived gopher+.
    359 .Pp
    360 Additionally to the above arguments several environment variables are set.
    361 .Pp
    362 .Dl GATEWAY_INTERFACE = `CGI/1.1'
    363 .Dl PATH_INFO = script which is executed
    364 .Dl PATH_TRANSLATED = absolute path with script which is executed
    365 .Dl QUERY_STRING = arguments (See above.)
    366 .Dl SELECTOR = arguments (For backwards compatibility.)
    367 .Dl REQUEST = arguments (For backwards compatibility.)
    368 .Dl REMOTE_ADDR = IP of the client
    369 .Dl REMOTE_HOST = REMOTE_ADDR
    370 .Dl REQUEST_METHOD = `GET'
    371 .Dl SCRIPT_NAME = script which is executed
    372 .Dl SERVER_NAME = server's hostname
    373 .Dl SERVER_PORT = server's port
    374 .Dl SERVER_PROTOCOL = `gopher/1.0'
    375 .Dl SERVER_SOFTWARE = `geomyidae'
    376 .Dl X_GOPHER_SEARCH = search (See above.)
    377 .Dl SEARCHREQUEST = search (For backwards compatibility.)
    378 .Dl HTTPS and GOPHERS = set, if TLS is used
    379 .Pp
    380 .Ed
    381 .
    382 .Ss Some CGI Examples
    383 Note: these are a very simple examples with no fitness checks with respect
    384 to safety/security.
    385 .Pp
    386 ex. uptime.cgi - standard CGI, no queries
    387 .
    388 .Bd -literal -offset indent
    389 #!/bin/sh
    390 #  uptime.cgi - prints system uptime(1)
    391 /usr/bin/uptime
    392 exit 0
    393 .Ed
    394 .
    395 .Pp
    396 Call the above with the following index.gph entry:
    397 .Pp
    398 .D1 [0|System Uptime|/uptime.cgi|frog.bog|70]
    399 .Pp
    400 A search query request must have an item Type of "7" to be called
    401 from an index.gph file.  It also needs a "?" suffix in the <path>
    402 field:
    403 .Pp
    404 ex. hello.cgi - standard CGI with query
    405 .
    406 .Bd -literal -offset indent
    407 #!/bin/sh
    408 #  hello.cgi - welcome user
    409 NAME=$1
    410 HOSTNAME=$2
    411 echo ""
    412 echo Hello $NAME - welcome to $HOSTNAME
    413 exit 0
    414 .Ed
    415 .
    416 .Pp
    417 Call the above with the following index.gph entry:
    418 .Pp
    419 .D1 [7|Hello You - Please enter your name|/hello.cgi?FROG.bog|frog.bog|70]
    420 .
    421 .Pp
    422 And do a simple
    423 .Xr snarf 1
    424 query (note the inserted TAB):
    425 .Pp
    426 .D1 % snarf Qo gopher://frog.bog/7/hello.cgi?FROG.bog[TAB]Christoph Qc -
    427 .D1 Hello Christoph - welcome to FROG.bog
    428 .
    429 .Pp
    430 Dynamic CGI entries are similar to above except that the script
    431 needs to create output as described in the
    432 .Ic FORMATTING
    433 section:
    434 .Pp
    435 ex. jughead.dcgi - dynamic CGI script with query
    436 .
    437 .Bd -literal -offset indent
    438 #!/bin/sh
    439 # jughead.dcgi - jughead-like local gopher search
    440 KWRD="$1"
    441 ARCHIVE="/var/gopher/textfiles/"
    442 echo "[i|Search results for \\"${KWRD}\\":|Err||]"
    443 echo "[i||Err||]"
    444 # grep(1) recursive, case-insensitive KWRD search of ARCHIVE:
    445 for RESULT in $(/usr/bin/grep -i -l -m1 ${KWRD} -r $ARCHIVE)
    446 do
    447         DESC=$(/usr/bin/basename ${RESULT})
    448         PATH=$(echo "$RESULT" | /usr/bin/sed 's/^\\/var\\/gopher//')
    449         echo "[0|${DESC}|${PATH}|frog.bog|70]"
    450 done
    451 exit 0
    452 .Ed
    453 .
    454 .Pp
    455 Call the above with the following index.gph entry:
    456 .Pp
    457 .D1 [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
    458 .Pp
    459 A successful query might look like this:
    460 .Pp
    461 .Bl -tag -width Ds -compact -offset indent
    462 .It Search results for Qo fubar Qc :
    463 .Pp
    464 .It Ic (FILE)
    465 How_Things_Break.txt
    466 .It Ic (FILE)
    467 Origins_of_Words.txt
    468 .It Ic (FILE)
    469 Phrases_of_the_Ages.txt
    470 .El
    471 .
    472 .Pp
    473 Care should to be exercised to avoid creating miss-Typed entries, unwanted
    474 recursions, and/or unintended writes in the working directory.
    475 .Sh LOG FILES
    476 The log file (ie. /var/log/gopherd.log) has the following structure:
    477 .
    478 .Pp
    479 .Ic [<date>|<IP/Host>|<port>|<status>] <item path>
    480 .
    481 .Pp
    482 where,
    483 .
    484 .Bl -inset
    485 .It Ic <date>
    486 = access date and time (std 'date' format)
    487 .Pp
    488  ex.
    489 .Qq "2018-01-31 14:18:34 +0000"
    490 .It Ic <IP/Host>
    491 = client IP/Host served
    492 .Pp
    493 ex.
    494 .Qq "104.23.33.1"
    495 .It Ic <port>
    496 = client port served
    497 .Pp
    498 ex.
    499 .Qq "16857"
    500 .It Ic <status>
    501 = status of client request
    502 .Pp
    503 ex. - some common status entries:
    504 .It Qo serving Qc
    505 => a successful request
    506 .It Qo not found Qc
    507 => an unsuccessful request
    508 .It Qo HTTP redirect Qc
    509 => web link redirect (Type h)
    510 .It Qo dir listing Qc
    511 => unindexed directory listing
    512 .Pp
    513 .It Ic <item path>
    514 = full path to item served
    515 .Pp
    516 ex.
    517 .D1 Qo "/PICS/simple2.jpg" Qc for an image file
    518 .D1 Qo "/PICS" Qc for a directory access
    519 .El
    520 .
    521 .Sh FILES
    522 README, LICENSE, CGI, index.gph, rc.d/, LINKS, gph/
    523 .
    524 .Sh SEE ALSO
    525 Links for further information on gopher:
    526 .Pp
    527 .D1 Pa gopher://gopher.floodgap.com
    528 .D1 Pa gopher://gopherproject.org
    529 .Sh STANDARDS
    530 .Em Internet RFC 1436
    531 .
    532 .Sh HISTORY
    533 .Bd -filled
    534 geomyidae started as a Linux/BSD port of the Plan 9 gopherd_P9 server.
    535 Originally called gopherd_BSD, the name was later changed to Geomyidae
    536 (latin), the taxonomic family of burrowing rodents known as "pocket
    537 gophers" which are in fact the true gophers. Due to inconsistencies
    538 and the UNIX culture, the name was changed to lowercase in 2010.
    539 .Ed
    540 .
    541 .Sh AUTHORS
    542 See LICENSE file for authors in the distribution.
    543 .
    544 .Sh LICENSE
    545 geomyidae is released under the MIT/X Consortium License.
    546 .
    547 .Sh BUGS
    548 Dynamic content functionality may vary across gopher clients.
    549 .
    550 .Ss "Reporting Bugs"
    551 Report bugs to:
    552 .An "Christoph Lohmann" Aq 20h@R-36.net