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