💾 Archived View for tilde.pink › docs › gformat.txt captured on 2023-01-29 at 05:15:47.
⬅️ Previous capture (2020-11-07)
-=-=-=-=-=-=-
FORMATTING
Structured Gopher space(s) can be created with geomyidae through the use
of special indexing files of the form <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. However, index files
are 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 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).
Anatomy of an index.gph file
In general, each line of an index.gph file has the following structure:
[<type>|<desc>|<path>|<host>|<port>]
where,
<type> = A valid gopher Item Type.
Some common Gopher Types as defined in RFC 1436 :
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.
In addition, geomyidae provides these:
h Item is a hypertext (HTTP) link
i Informational Item (used for descriptive purposes)
Unknown file types default to Type "9" (binary).
<desc> = description of gopher item. Most printable characters
should work.
<path> = full or relative path to gopher item (base value is "/" ).
Use the "Err" path for items not intended to be served.
<host> = hostname or IP hosting the gopher item. Must be resolvable
for the intended clients. If this is set to "server" , the server's
hostname is used.
<port> = TCP port number (usually 70) If this is set to "port" ,
the default port of the server is used.
Note: geomyidae doesn't require "informational" text to be formally Typed
as "[i|...]"; any line not beginning with "[" is treated as
informational, greatly simplifying the formatting of index.gph files.
However, if a line begins with a "t", this "t" is left out. This quirk
is there to allow "informational" text lines beginning with a "[" to
display. For dynamically generated index files it may be desirable to
either formally Type informational text or run it through a filter to add
a second "t" - .ie sed 's/^t/&&/' .
Note 2: You can escape a pipe ("|") character in for example a <desc>
field by prepending a slash ("\").
Note 3: The gph parser is very forgiving. If the link structure is not
parsed correctly, then the original line is printed.
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:
Welcome to Frog.bog
[i||Err||]
[0|About this server|about.txt|frog.bog|70]
[0|Daily Log|/dtail.cgi|frog.bog|70]
[1|Phlog: like a blog, but not|/PHLOG|frog.bog|70]
[9|Some binary file|widget.exe|frog.bog|70]
[I|Snowflake picture|snowflake.jpg|frog.bog|70]
ttry our snowflakes!
Links and Searches
[1|Go to R-36.net|/|gopher.r-36.net|70]
[h|Go to NetBSD.org|URL:http://netbsd.org|frog.bog|70]
[7|Query US Weather by Zipcode|/weather.cgi?|frog.bog|70]
[7|Search Veronica II|/v2/vs|gopher.floodgap.com|70]
[8|Telnet to SDF Public Access Unix System|null|freeshell.org|23]
The above looks something like this in a text-based gopher client:
Welcome to Frog.bog
(FILE) About this server
(FILE) Daily Log
(DIR) Phlog: like a blog, but not
(BIN) Some binary file
(IMG) Snowflake picture try our snowflakes!
Links and Searches
(DIR) Go to R-36.net
(HTML) Go to NetBSD.org
(?) Query US Weather by Zipcode
(?) Search Veronica II
(TEL) Telnet to SDF Public Access Unix System
DYNAMIC CONTENT (gopher CGI)
There are two options provided for dynamic content creation: standard CGI
( .cgi ) and dynamic CGI ( .dcgi ). Despite the names, both can accept
input and generate dynamic content; the only difference is the latter 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.
Both .cgi and .dcgi scripts have the same argument call structure (as
seen by geomyidae):
executable.[d]cgi $search $arguments $host $port
where
search = query string (type 7) or "" (type 0)
arguments = string after "?" in the path or ""
host = server's hostname ("localhost" by default)
port = server's port ("70" by default)
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.
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+.
Additionally to the above arguments several environment variables are
set.
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.)
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_PROTOCOL = `gopher/1.0'
SERVER_SOFTWARE = `geomyidae'
X_GOPHER_SEARCH = search (See above.)
Some CGI Examples
Note: these are a very simple examples with no fitness checks with
respect to safety/security.
ex. uptime.cgi - standard CGI, no queries
#!/bin/sh
# uptime.cgi - prints system uptime(1)
/usr/bin/uptime
exit 0
Call the above with the following index.gph entry:
[0|System Uptime|/uptime.cgi|frog.bog|70]
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> field:
ex. hello.cgi - standard CGI with query
#!/bin/sh
# hello.cgi - welcome user
NAME=$1
HOSTNAME=$2
echo ""
echo Hello $NAME - welcome to $HOSTNAME
exit 0
Call the above with the following index.gph entry:
[7|Hello You - Please enter your
name|/hello.cgi?FROG.bog|frog.bog|70]
And do a simple snarf(1) query (note the inserted TAB):
% snarf "gopher://frog.bog/7/hello.cgi?FROG.bog[TAB]Christoph" -
Hello Christoph - welcome to FROG.bog
Dynamic CGI entries are similar to above except that the script needs to
create output as described in the FORMATTING section:
ex. jughead.dcgi - dynamic CGI script with query
#!/bin/sh
# jughead.dcgi - jughead-like local gopher search
KWRD="$1"
ARCHIVE="/var/gopher/textfiles/"
echo "[i|Search results for \"${KWRD}\":|Err||]"
echo "[i||Err||]"
# grep(1) recursive, case-insensitive KWRD search of ARCHIVE:
for RESULT in $(/usr/bin/grep -i -l -m1 ${KWRD} -r $ARCHIVE)
do
DESC=$(/usr/bin/basename ${RESULT})
PATH=$(echo "$RESULT" | /usr/bin/sed 's/^\/var\/gopher//')
echo "[0|${DESC}|${PATH}|frog.bog|70]"
done
exit 0
Call the above with the following index.gph entry:
[7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
A successful query might look like this:
Search results for "fubar":
(FILE) How_Things_Break.txt
(FILE) Origins_of_Words.txt
(FILE) Phrases_of_the_Ages.txt
Care should to be exercised to avoid creating miss-Typed entries,
unwanted recursions, and/or unintended writes in the working directory.