Fixing geomyidae.8 to a modern troff style. - geomyidae - a small C-based gophe… | |
git clone git://git.codemadness.org/geomyidae | |
Log | |
Files | |
Refs | |
README | |
LICENSE | |
--- | |
commit b0020aba7262324964672cdce0c6924e45b85a88 | |
parent 5efc3bd3f2f7949c70d1d3fe49c00e8f2c3961f4 | |
Author: Christoph Lohmann <[email protected]> | |
Date: Mon, 6 Jan 2025 13:41:23 +0100 | |
Fixing geomyidae.8 to a modern troff style. | |
Thanks Lucas de Sena <[email protected]> | |
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 … | |
.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 print… | |
. | |
.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 insertio… | |
.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 exam… | |
+All scripts must be under the gopher root directory and be executable by the s… | |
+.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 o… | |
-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 … | |
-.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 A… | |
+.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… | |
+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 … | |
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> … | |
. | |
.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 … | |
+.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… | |
.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 [email protected] | |
+.An "Christoph Lohmann" Aq Mt [email protected] |