Bucktooth: Mole care and feeding
--------------------------------

If you set a file to be executable by the server's uid, the server will
try to execute it. These executables, which are analogous to CGIs, are called
moles. (In Bucktooth 0.2, if you make gophermap executable, then it is also
treated this way.)

Unlike CGIs, which get arguments from web forms and spit out documents,
moles get their arguments from the selector used to access them and can,
depending on how they are presented in the gophermap file, masquerade as
virtual directory trees and virtual files. In fact, these questions are
actually virtual files generated by a mole called dbrowse, within a directory
that dbrowse is also serving. Moreover, you can force a mole to be presented
in many different content ways, including as a .gif, a text file, whichever,
determined by the item type you attach to it in the gophermap file.

If the mole is masquerading as a directory (i.e., in gophermap, it has an
itemtype of 1 specified), the mole is expected to return a list of "files"
(can be either real files or a list of choices) in Gopher RFC 1436 format.
The library "gopherlib.pl" can help with this if you choose to program in
Perl. It is documented elsewhere, and is included in the stuff/ directory
of the standard Bucktooth distribution.

If the mole is masquerading as a search server (i.e., in gophermap, it
has an itemtype of 7 specified), the mole does not need to do anything
special. It will be provided with the arguments it requests from the client
as command-line arguments, and the client will request this data from the
user internally. Itemtype 7 search servers are expected to emit results
in gophermenu (itemtype 1) form; see above.

To communicate, the mole simply should dump its data to standard output. Moles
do not need to send a "Content-type" header like CGIs do because the item
type has already told the client that information.

Moles receive their arguments on the command line. Arguments are considered
to begin after a ? in the selector string sent to the server.

Bucktooth provides the mole some CGI-like environment variables, including

REMOTE_HOST
REMOTE_ADDR
REMOTE_PORT
SERVER_HOST
SERVER_PORT

It also defines

SELECTOR

the full selector string sent to the server, including arguments; and

REQUEST

the request for the mole, without trailing arguments.

The dbrowse mole is included in the stuff/ directory for your interest and
amusement. It needs gopherlib.pl.

If you have DNS anti-spoofing on (Bucktooth 0.2 and up), then REMOTE_HOST
will be hostname/IP (e.g., localhost/127.0.0.1) to allow you to parse both
and compare. If the address has no PTR, then it will be IP/IP for
consistency (e.g., 127.0.0.1/127.0.0.1).

Certain filesystems (Cygwin comes to mind) may have impoverished execute
bits -- i.e., everything has them set, so Bucktooth tries to execute everything
and usually fails. If you are in such a situation, you can restrict Bucktooth
0.2.6 and up to only execute a specified extension (the default is .mol),
meaning a mole must have execute bits *and* that extension to be executed by
the server. Otherwise, it is served as usual. You should not turn this on if
you can avoid it. If this *is* enabled, there is one gotcha with gophermaps: an
executable gophermap must also have the extension (e.g., gophermap.mol), but a
regular gophermap must NOT. If you have both in the same directory, then the
mole-ified gophermap takes precedence and is executed, and the regular
gophermap is simply ignored.


.