Introduction
Introduction Statistics Contact Development Disclaimer Help
Fixing geomyidae.8 to a modern troff style. - geomyidae - A small C-based gophe…
git clone git://bitreich.org/geomyidae/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfri…
Log
Files
Refs
Tags
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]
You are viewing proxied material from bitreich.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.