commit b0020aba7262324964672cdce0c6924e45b85a88
parent 5efc3bd3f2f7949c70d1d3fe49c00e8f2c3961f4
Author: Christoph Lohmann <20h@r-36.net>
Date: Mon, 6 Jan 2025 13:41:23 +0100
Fixing geomyidae.8 to a modern troff style.
Thanks Lucas de Sena <lucas@seninha.org>
Sorry, your e-mail was no complete patch with all metadata.
Diffstat:
| M | geomyidae.8 | | | 749 | +++++++++++++++++++++++++++++++++++++++++++++++++------------------------------ |
1 file changed, 463 insertions(+), 286 deletions(-)
diff --git a/geomyidae.8 b/geomyidae.8
@@ -1,6 +1,6 @@
.\" geomyidae.8 handcrafted in GNU groff -mdoc using nvi
.\"
-.Dd March 17, 2021
+.Dd January 4, 2025
.Dt GEOMYIDAE 8
.Os
.
@@ -32,60 +32,71 @@
.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"
+.Qq Pa "../geomyidae-x.xx"
directory, tweak the Makefile if desired (installs in
-.Qq "/usr/bin"
+.Qq Pa "/usr/bin"
by default), then run the
-.Sq "make ; make install"
-commands. The resulting executable should be run by root.
-.Ed
+.Qq Ql "make ; make install"
+commands.
+The resulting executable should be run by root.
.
.Ss Basic Installation and Startup
-.Bd -literal
- $ 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
+.Bd -literal -offset indent
+$ 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
+.Ed
+.
+.Pp
+Use whatever gopher client you like (ie. sacc) to browse:
+.Bd -literal -offset indent
+$ sacc gopher://localhost
.Ed
.
.Ss Running
-geomyidae should normally be started by root, although it can be started
+.Nm
+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
+by the same user.
+.Nm
+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
+values if set.
+See
+.Sx OPTIONS
+below for specifics.
+Launching
+.Nm
+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.
+.Nm
+source archive.
+Logging in
+.Nm
+can be done through either logfiles or syslog.
.
.Sh OPTIONS
-geomyidae options and default settings:
+.Nm
+options and default settings:
.Bl -tag -width Ds
.
.It Fl 4
@@ -102,8 +113,10 @@ for the
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.
+Don't fork into background.
+If no
+.Ar logfile
+is given, this implies logging to the standard output.
.
.It Fl e
Disable execution of any CGI or DCGI script.
@@ -122,42 +135,67 @@ 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+)
+.Bl -tag -width "XX" -compact
+.It Cm 0
+no logging
+.It Cm 1
+served plain files
+.It Cm 2
+directory listings
+.It Cm 4
+HTTP redirects
+.It Cm 8
+errors (e.g., not found)
+.It Cm 16
+client connections
+.It Cm 32
+gopher+ redirects
+.El
+.Pp
+E.g.:
+.Bd -literal -offset indent
+1 + 2 + 4 + 8 + 32 = 47
+(files + directories + HTTP + errors + gopher+)
.Ed
.
.It Fl b Ar base
-Root directory to serve (default: /var/gopher).
+Root directory to serve
+.Po
+default:
+.Pa /var/gopher
+.Pc .
.
.It Fl p Ar port
-Port geomyidae should listen on (default: 70).
+Port
+.Nm
+should listen on (default: 70).
.
.It Fl o Ar sport
-Port geomyidae displays within base directory (default: 70).
+Port
+.Nm
+displays within base directory (default: 70).
Use in conjunction with
.Ic -p
-for obfuscating actual port geomyidae is running on.
+for obfuscating actual port
+.Nm
+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).
+Sets the user to which privileges drop when
+.Nm
+is ready to accept network connections (default: user
+.Nm
+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).
+Sets the group to which privileges drop when
+.Nm
+is ready to accept network connections (default: group
+.Nm
+runs as).
Helps improve security by reducing privileges during request
processing.
.
@@ -165,7 +203,13 @@ processing.
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).
+Defines the interface to which
+.Nm
+binds to
+.Po
+default:
+.Cm 0.0.0.0
+.Pc .
Multiple interfaces can be given.
.
.It Fl t Ar keyfile certfile
@@ -173,112 +217,161 @@ 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.) See ENCRYPTION ONLY
+for TLS connections (if the feature is compiled in.) See
+.Sx ENCRYPTION ONLY
support below.
.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.
+Structured Gopher space(s) can be created with
+.Nm
+through the use of special indexing files of the form
+.Pa <name>.gph
+which, if present,
+.Nm
+uses to format and/or filter the contents of the base directory
+.Po
+.Pa /var/gopher
+by default
+.Pc
+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
+required: if no
+.Pa index.gph ,
+.Pa index.cgi
+or
+.Pa index.dcgi
+file is found,
+.Nm
+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
+use of sub-directories: ie.
+.Pa pictures.gph ,
+.Pa music.gph
+and
+.Pa documents.gph
+could be "directories" within
+.Pa main.gph ,
+yet all reside in
+.Pa /var/gopher
+along with their respective files (*.jpg, *.mp3, *.pdf for example).
.
.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
+A gph file consists of informational text and links.
+A link has the form:
+.Pp
+.Dl [ Ar <type> Ns | Ns Ar <desc> Ns | Ns Ar <path> Ns | Ns Ar <host> Ns | Ns Ar <port> ]
.Pp
where,
-.Bl -inset -offset indent
-.It Ic <type>
-= A valid gopher Item Type.
+.Bl -tag -width "<XXXX>"
+.It Ar <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
+.Em RFC 1436 :
+.
+.Bl -tag -width "XX" -compact
+.It Cm 0
+Item is a file.
+.It Cm 1
+Gopher directory.
+.It Cm 3
+Error.
+.It Cm 7
+Item is an Index-Search server.
+.It Cm 8
+Item points to a text-based telnet session.
+.It Cm 9
+Binary file.
+Client reads until TCP connection closes!
+.It Cm g
+GIF format graphics file.
+.It Cm I
+Indeterminate image file.
+Client decides how to display.
+.El
.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
+In addition,
+.Nm
+provides these:
+.Bl -tag -width "XX" -compact
+.It Cm h
+Item is a hypertext (HTTP) link.
+.It Cm i
+Informational Item (used for descriptive purposes).
+.El
+.Pp
+Unknown file types default to Type
+.Qq Cm "9"
+(binary).
.
-.It Ic <desc>
-= description of gopher item. Most printable characters should work.
+.It Ar <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"
+.It Ar <path>
+Full or relative path to gopher item (base value is
+.Qq Pa "/" ) .
+Use the
+.Qq Pa "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).
+.It Ar <host>
+Hostname or IP hosting the gopher item.
+Must be resolvable for the intended clients.
+If this is set to
+.Qq Cm "server" ,
+the server's hostname is used.
.
+.It Ar <port>
+TCP port number (usually 70).
If this is set to
-.Qq "port"
-, the default port of the server is used.
+.Qq Cm "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
+.Pp
+Note:
+.Nm
+doesn't require "informational" text to be formally typed as
+.Ql "[i|...]" ;
+any line
.Em 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,^[,[|&,' .
-.Ed
-.Bd -filled
-Note 2: You can escape a pipe ("|") character in for example a
-.Em <desc>
+beginning with
+.Ql "\(lB"
+is treated as informational, greatly simplifying the formatting of
+.Pa index.gph
+files.
+If you want to display some informational text beginning with
+.Ql "\(lB"
+you can use the special case of an empty item type.
+.Ql "[|[some link"
+will be shortened to
+.Ql "[some link" .
+For dynamically generated content it may be desirable to either formally type
+informational text or run it through a filter to prepend
+.Ql "[|"
+- \.ie
+.Ql "sed 's,^[,[|&,'" .
+.Pp
+Note 2: You can escape a pipe
+.Pq Ql "\(ba"
+character in for example a
+.Cm <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
+.Pp
+Note 3: The gph parser is very forgiving.
+If the link structure is not parsed correctly, then the original line is printed.
.
.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:
+A
+.Pa root.gph
+file for a server running on
+.Ql host=frog.bog ,
+.Ql 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||]
@@ -299,118 +392,165 @@ Links and Searches
.
.Pp
The above looks something like this in a text-based gopher client:
+.Bd -filled -offset indent
+.Bl -tag -width "(XXXXX)" -compact
+.It Sy Welcome to Frog.bog
.Pp
-.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
-.It Ic Welcome to Frog.bog
-.Pp
-.It Ic (FILE)
+.It Sy (FILE)
About this server
-.It Ic (FILE)
+.It Sy (FILE)
Daily Log
-.It Ic (DIR)
+.It Sy (DIR)
Phlog: like a blog, but not
-.It Ic (BIN)
+.It Sy (BIN)
Some binary file
-.It Ic (IMG)
+.It Sy (IMG)
Snowflake picture
+.El
.Pp
try our snowflakes!
-.El
.Pp
-.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
-.It Ic Links and Searches
-.It Ic (DIR)
+.Bl -tag -width "(XXXXX)" -compact
+.It Sy Links and Searches
+.It Sy (DIR)
Go to R-36.net
-.It Ic (HTML)
+.It Sy (HTML)
Go to NetBSD.org
-.It Ic (?)
+.It Sy (?)
Query US Weather by Zipcode
-.It Ic (?)
+.It Sy (?)
Search Veronica II
-.It Ic (TEL)
+.It Sy (TEL)
Telnet to SDF Public Access Unix System
.El
+.Ed
.Sh DYNAMIC CONTENT (gopher CGI)
There are two options provided for dynamic content creation and a special
-case: standard CGI (
-.Ic .cgi
-), dynamic CGI
-(
-.Ic .dcgi
-) and HTTP compatibility mode.
+case: standard CGI
+.Pq Pa ".cgi" ,
+dynamic CGI
+.Pq Pa ".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.
+the server as a standard
+.Nm
+index
+.Pq Pa ".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
+.Ar "user:group"
+running
+.Nm .
+Consequently, it is best to use the
+.Fl u
+and
+.Fl g
+server options to avoid running as root.
.Pp
-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.
+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.
.Pp
-Both .cgi and .dcgi scripts have the same argument call structure (as seen by geomyidae):
-.Bd -literal -offset indent
-executable.[d]cgi $search $arguments $host $port $traversal $selector
-.Ed
-.Pp
-where
-.Bd -literal -offset indent
-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.)
-.Ed
+Both
+.Pa ".cgi"
+and
+.Pa ".dcgi"
+scripts have the same argument call structure (as seen by
+.Nm ) :
+.Pp
+.Dl Ic executable.[d]cgi Ar search Ar arguments Ar host Ar port Ar traversal Ar selector
+.Pp
+where:
+.Bl -tag -width "XXXXXXXXX" -compact
+.It Ar search
+Query string (type 7) or "" (type 0).
+.It Ar arguments
+String behind "?" in selector or "".
+.It Ar host
+Server's hostname ("localhost" by default).
+.It Ar port
+Server's port ("70" by default).
+.It Ar traversal
+Remaining path from path traversal in REST case.
+.It Ar selector
+Raw selector or full req (See HTTP compatibility mode.)
+.El
.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.
+surprises depending on how a script is written.
+See the CGI file (included in the
+.Nm
+source archive) for further elaboration.
.Pp
For a special REST path case for the arguments, see the CGI file for the
description.
.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+.
+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,
+.Nm
+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.
-.Bd -literal -offset indent
-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
-.Ed
+.Bl -tag -width "SERVER_LISTEN_NAME" -compact
+.It Ev GATEWAY_INTERFACE
+.Qq Cm GI/1.1
+.It Ev PATH_INFO
+Script which is executed
+.It Ev PATH_TRANSLATED
+Absolute path with script which is executed
+.It Ev QUERY_STRING
+Arguments (See above.)
+.It Ev SELECTOR
+Raw selector
+.It Ev REQUEST
+Raw selector
+.It Ev TRAVERSAL
+Traversal (See above.)
+.It Ev REMOTE_ADDR , REMOTE_HOST
+IP of the client
+.It Ev REQUEST_METHOD
+.Qq Cm GET
+.It Ev SCRIPT_NAME
+Script which is executed.
+.It Ev SERVER_NAME
+Server's hostname.
+.It Ev SERVER_PORT
+Server's port.
+.It Ev SERVER_LISTEN_NAME
+Ip the server received the connection on.
+.It Ev SERVER_PROTOCOL
+.Qq Cm gopher/1.0
+.It Ev SERVER_SOFTWARE
+.Qq Cm geomyidae
+.It Ev X_GOPHER_SEARCH
+Search (See above.)
+.It Ev SEARCHREQUEST
+Search (For backwards compatibility.)
+.It Ev HTTPS , GOPHERS
+Set, if TLS is used.
+.El
.
.Ss 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
+file or path found,
+.Nm
+will try to traverse from the
.Fl b Ar 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.
+path until a path component / directory is not found.
+Then
+.Nm
+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,
+.Nm
+will execute them using the traversal and
+.Ev TRAVERSAL
+parameter and environment variable being set to the rest path.
.Bd -literal -offset indent
Selector: /some/v1/service/add/something?args=value
-> /some/v1/service exists
@@ -421,13 +561,15 @@ Selector: /some/v1/service/add/something?args=value
.
.Ss HTTP compatibility
For maximum flexibility in case someone sends a HTTP request to gopher,
-geomyidae supports a special case of CGI. See this example:
+.Nm
+supports a special case of CGI.
+See this example:
.Bd -literal -offset indent
Client request: GET /some/path HTTP/1.1
-> /GET exists and is executable
-> /GET "" "" $host $port "" "GET /some/path HTTP/1.1" is called
.Ed
-
+.Pp
This allows for example simple scripts for icecast upload compatibility
or handling transparent HTTP right next to gopher, getting TLS for free.
.
@@ -435,7 +577,8 @@ or handling transparent HTTP right next to gopher, getting TLS for free.
Note: these are a very simple examples with no fitness checks with respect
to safety/security.
.Pp
-ex. uptime.cgi - standard CGI, no queries
+ex.
+.Pa uptime.cgi - standard CGI, no queries
.
.Bd -literal -offset indent
#!/bin/sh
@@ -447,13 +590,21 @@ exit 0
.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>
+.Dl [0|System Uptime|/uptime.cgi|frog.bog|70]
+.Pp
+A search query request must have an item Type of
+.Qq Cm "7"
+to be called from an
+.Pq index.gph
+file.
+It also needs a
+.Qq Cm "?\&"
+suffix in the
+.Ar <path>
field:
.Pp
-ex. hello.cgi - standard CGI with query
+ex.
+.Pa hello.cgi - standard CGI with query
.
.Bd -literal -offset indent
#!/bin/sh
@@ -467,24 +618,27 @@ exit 0
.
.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]
+.Bd -literal -offset indent
+[7|Hello You - Please enter your name|/hello.cgi?FROG.bog|frog.bog|70]
+.Ed
.
.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
+.Bd -literal -offset indent
+% snarf "gopher://frog.bog/7/hello.cgi?FROG.bog[TAB]Christoph" -
+Hello Christoph - welcome to FROG.bog
+.Ed
.
.Pp
Dynamic CGI entries are similar to above except that the script
needs to create output as described in the
-.Ic FORMATTING
+.Sx FORMATTING
section:
.Pp
-ex. jughead.dcgi - dynamic CGI script with query
+ex.
+.Pa jughead.dcgi - dynamic CGI script with query
.
.Bd -literal -offset indent
#!/bin/sh
@@ -506,112 +660,135 @@ exit 0
.Pp
Call the above with the following index.gph entry:
.Pp
-.D1 [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
+.Dl [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
.Pp
A successful query might look like this:
+.Bd -filled -offset indent
+Search results for
+.Qq fubar :
.Pp
-.Bl -tag -width Ds -compact -offset indent
-.It Search results for Qo fubar Qc :
-.Pp
-.It Ic (FILE)
+.Bl -tag -width "(XXXX)" -compact
+.It Sy (FILE)
How_Things_Break.txt
-.It Ic (FILE)
+.It Sy (FILE)
Origins_of_Words.txt
-.It Ic (FILE)
+.It Sy (FILE)
Phrases_of_the_Ages.txt
.El
+.Ed
.
.Pp
-Care should to be exercised to avoid creating miss-Typed entries, unwanted
+Care should to be exercised to avoid creating mistyped entries, unwanted
recursions, and/or unintended writes in the working directory.
.Sh HAPROXY SUPPORT
-geomyidae has
+.Nm
+has
.Em HAProxy
-support. It can be enabled using the
+support.
+It can be enabled using the
.Fl y
parameter.
.
.Sh LOG FILES
The log file (ie. /var/log/gopherd.log) has the following structure:
-.
-.Pp
-.Ic [<date>|<IP/Host>|<port>|<status>] <item path>
+.Dl [ Ns Ar <date> Ns | Ns Ar <IP/Host> Ns | Ns Ar <port> Ns | Ns Ar <status> Ns ] Ar <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
+.Bl -tag -width "<XXXX XXXX>"
+.It Ar <date>
+Access date and time (std 'date' format).
+.br
ex.
-.Qq "104.23.33.1"
-.It Ic <port>
-= client port served
-.Pp
+.Qq Cm "2018-01-31 14:18:34 +0000"
+.It Ar <IP/Host>
+Client IP/Host served
+.br
ex.
-.Qq "16857"
-.It Ic <status>
-= status of client request
-.Pp
+.Qq Cm "104.23.33.1"
+.It Ar <port>
+Client port served
+.br
+ex.
+.Qq Cm "16857"
+.It Ar <status>
+Status of client request
+.br
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
-.It Ic <item path>
-= full path to item served
-.Pp
+.Bl -tag -width "XXXX XXXXXXXX" -compact
+.It Qq Cm serving
+A successful request.
+.It Qq Cm not found
+An unsuccessful request.
+.It Qq Cm HTTP redirect
+Web link redirect (Type h).
+.It Qq Cm dir listing
+Unindexed directory listing.
+.El
+.It Ar <item path>
+Full path to item served
+.br
ex.
-.D1 Qo "/PICS/simple2.jpg" Qc for an image file
-.D1 Qo "/PICS" Qc for a directory access
+.Qq Pa "/PICS/simple2.jpg"
+for an image file;
+.Qq Pa "/PICS"
+for a directory access.
.El
.
.Sh 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
+If you set the sticky bit
+.Pq Ql "chmod +t"
+on some file or directory,
+.Nm
+will only serve it over an encrypted connection.
+There is the special case, that when the sticky bit is set on the
.Ar base
-directory, all content will only be served over tls.
+directory, all content will only be served over TLS.
.
.Sh FILES
-README, LICENSE, CGI, index.gph, rc.d/, LINKS, gph/
+.Pa 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
+.Lk gopher://gopher.floodgap.com "Floodgap Systems"
+.Pp
+.Lk gopher://gopherproject.org "The Gopher Project"
.Sh STANDARDS
-.Em Internet RFC 1436
+.Rs
+.%A F. Anklesaria
+.%A M. McCahill
+.%A P. Lindner
+.%A D. Johnson
+.%A D. Torrey
+.%A B. Alberti
+.%D March 1993
+.%R RFC 1436
+.%T The Internet Gopher Protocol (a distributed document search and retrieval protocol)
+.Re
.
.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.
+.Nm
+started as a Linux/BSD port of the Plan 9 gopherd_P9 server.
+Originally called gopherd_BSD, the name was later changed to
+.Qq Em Geomyidae
+(latin), the taxonomic family of burrowing rodents known as
+.Qq Em "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.
+.Nm
+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
+.An "Christoph Lohmann" Aq Mt 20h@R-36.net
