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