commit a417296299b8fd5073a1fd237562d08ad6ff6100
parent c61be869c93eb515c12f8b773b153b53c9a9409f
Author: Christoph Lohmann <20h@r-36.net>
Date: Tue, 26 Feb 2013 18:49:20 +0100
Adding a new mandoc manpage and NetBSD rc.d.
Thanks Jeff W <jgw@sdf.org>!
Diffstat:
2 files changed, 31 insertions(+), 119 deletions(-)
diff --git a/geomyidae.8 b/geomyidae.8
@@ -14,7 +14,7 @@
.Op Fl d
.Op Fl l Ar logfile
.Op Fl v Ar loglevel
-.Op Fl b Ar base
+.Op Fl b Ar base
.Op Fl p Ar port
.Op Fl o Ar sport
.Op Fl u Ar user
@@ -32,22 +32,20 @@ is a daemon for serving the protocol specified in
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"
directory, tweak the Makefile if desired (installs in
.Qq "/usr/bin"
-by default), then run the
+by default), then run the
.Sq "make ; make install"
commands. The resulting executable should be run by root.
-.Ed
.
.Ss Basic Installation and Startup:
-.Pp
.Bd -literal
+
% wget http://www.r-36.net/src/geomyidae/geomyidae-current.tgz;
% tar -xzvf geomyidae-*.tgz;
% cd geomyidae-*;
@@ -62,7 +60,6 @@ commands. The resulting executable should be run by root.
.Ed
.
.Ss Running
-.Bd -filled
geomyidae 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
@@ -75,27 +72,19 @@ values if set. See
below for specifics. Launching geomyidae automatically is best done via a UNIX
run-time (rc.d) script; several sample rc.d scripts are included in the geomyidae
source archive.
-.Ed
.
.Sh OPTIONS
geomyidae options and default settings:
-.Pp
-.Bl -tag -width ".Fl test Ao Ar string Ac"
+.Bl -tag -width Ds
.
-.Bd -filled
.It Fl d
Don't fork into background
-.Ed
.
-.Bd -filled
.It Fl l Ar logfile
Specify file where log output is written (no default)
-.Ed
.
-.Bd -filled
.It Fl v Ar loglevel
Set the logging level (default: 7)
-.Ed
.
.Bd -literal
Loglevels:
@@ -109,53 +98,38 @@ Loglevels:
(files + directories + HTTP + errors)
.Ed
.
-.Bd -filled
-.It Fl b Ar base
+.It Fl b Ar base
Root directory to serve (default: /var/gopher)
-.Ed
.
-.Bd -filled
.It Fl p Ar port
Port geomyidae should listen on (default: 70)
-.Ed
.
-.Bd -filled
.It Fl o Ar sport
Port geomyidae displays within base directory (default: 70).
Use in conjunction with
.Ic -p
for obfuscating actual port geomyidae is running on.
-.Ed
.
-.Bd -filled
.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).
Helps improve security by reducing privileges during request
processing.
-.Ed
.
-.Bd -filled
.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).
Helps improve security by reducing privileges during request
processing.
-.Ed -filled
.
-.Bd -filled
.It Fl h Ar host
Host to use in directory listings (default: localhost)
-.Ed
.
-.Bd -filled
.It Fl i Ar IP
IP to which geomyidae binds to (default: 127.0.0.1)
-.Ed
.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
@@ -169,13 +143,9 @@ 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
.
.Ss Anatomy of an index.gph file
-.Bd -filled
In general, each line of an index.gph file has the following structure:
-.Ed
-.Pp
.Bl -inset -offset indent
.It Ic [<type>|<desc>|<path>|<host>|<port>]
.El
@@ -206,12 +176,10 @@ In addition, geomyidae provides these:
i Informational Item (used for descriptive purposes)
.Ed
.
-.Pp
.Bd -filled
Unknown file types default to Type "9" (binary).
.Ed
.
-.Pp
.Bd -filled
Note: geomyidae doesn't require "informational" text to be formally
Typed as "[i|...]"; any line
@@ -224,44 +192,33 @@ 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/&&/' .
.Ed
.
-.Bd -filled
.It Ic <desc>
= description of gopher item. Most printable characters should work.
-.Ed
.
-.Bd -filled
.It Ic <path>
= full path to gopher item (base value is
.Qq "/"
). Use the
.Qq "Err"
path for items not intended to be served.
-.Ed
.
-.Bd -filled
.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.
-.Ed
.
-.Bd -filled
.It Ic <port>
= TCP port number (usually 70)
.
If this is set to
.Qq "port"
, the default port of the server is used.
-.Ed
.El
.
.Ss index.gph Example
-.Bd -filled
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:
-.Ed
-.Pp
.Bd -literal -offset indent
Welcome to Frog.bog
[i||Err||]
@@ -280,12 +237,10 @@ Links and Searches
.Ed
.
.Pp
-.Bd -filled
The above looks something like this in a text-based gopher client:
-.Ed
.Pp
.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
-.D1 Welcome to Frog.bog
+.It Ic Welcome to Frog.bog
.Pp
.It Ic (FILE)
About this server
@@ -300,7 +255,7 @@ Snowflake picture
.El
.Pp
.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
-.D1 Links and Searches
+.It Ic Links and Searches
.It Ic (DIR)
Go to R-36.net
.It Ic (HTML)
@@ -312,9 +267,7 @@ Search Veronica II
.It Ic (TEL)
Telnet to SDF Public Access Unix System
.El
-.Pp
.Sh DYNAMIC CONTENT (gopher CGI)
-.Bd -filled
There are two options provided for dynamic content creation: standard CGI (
.Ic .cgi
) and dynamic CGI
@@ -327,11 +280,8 @@ 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.
-.Ed
.Pp
-.Bd -filled
Both .cgi and .dcgi scripts have the same argument call structure (as seen by geomyidae):
-.Ed
.Pp
.D1 executable.[d]cgi $search $arguments $host $port
.Pp
@@ -342,22 +292,15 @@ where
.D1 host = server's hostname ("localhost" by default)
.D1 port = server's port ("70" by default)
.Pp
-.Bd -filled
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.
-.Ed
.
.Ss Some CGI Examples
-.Pp
-.Bd -filled
Note: these are a very simple examples with no fitness checks with respect
to safety/security.
-.Ed
.Pp
-.Bd -filled
ex. uptime.cgi - standard CGI, no queries
-.Ed
.
.Bd -literal -offset indent
#!/bin/sh
@@ -367,21 +310,15 @@ exit 0
.Ed
.
.Pp
-.Bd -filled
Call the above with the following index.gph entry:
-.Ed
.Pp
.D1 [0|System Uptime|/uptime.cgi|frog.bog|70]
.Pp
-.Bd -filled
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:
-.Ed
.Pp
-.Bd -filled
ex. hello.cgi - standard CGI with query
-.Ed
.
.Bd -literal -offset indent
#!/bin/sh
@@ -393,33 +330,25 @@ exit 0
.Ed
.
.Pp
-.Bd -filled
Call the above with the following index.gph entry:
-.Ed
.Pp
.D1 [7|Hello You - Please enter your name|/hello.cgi?|frog.bog|70]
.
.Pp
-.Bd -filled
And do a simple
.Xr snarf 1
-query:
-.Ed
+query (note the inserted TAB):
.Pp
-.D1 % snarf Qo gopher://frog.bog/7/hello.cgi?Christoph Qc -
+.D1 % snarf Qo gopher://frog.bog/7/hello.cgi?[TAB]Christoph Qc -
.D1 Hello Christoph - welcome to Frog.bog
.
.Pp
-.Bd -filled
Dynamic CGI entries are similar to above except that the script
-needs to create output as described in the
+needs to create output as described in the
.Ic FORMATTING
section:
-.Ed
.Pp
-.Bd -filled
ex. jughead.dcgi - dynamic CGI script with query
-.Ed
.
.Bd -literal -offset indent
#!/bin/sh
@@ -427,8 +356,8 @@ ex. jughead.dcgi - dynamic CGI script with query
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:
+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})
@@ -439,19 +368,15 @@ exit 0
.Ed
.
.Pp
-.Bd -filled
Call the above with the following index.gph entry:
-.Ed
.Pp
.D1 [7|Search this Gopher|/jughead.dcgi?|frog.bog|70]
.Pp
-.Bd -filled
A successful query might look like this:
-.Ed
.Pp
-.Bl -tag -width ".It Ic WIDTHS" -compact -offset indent
-.D1 Search results for Qo fubar Qc :
-.D1 ----
+.Bl -tag -width Ds -compact -offset indent
+.It Search results for Qo fubar Qc :
+.Pp
.It Ic (FILE)
How_Things_Break.txt
.It Ic (FILE)
@@ -461,16 +386,10 @@ Phrases_of_the_Ages.txt
.El
.
.Pp
-.Bd -filled
Care should to be exercised to avoid creating miss-Typed entries, unwanted
recursions, and/or unintended writes in the working directory.
-.Ed
-.Pp
.Sh LOG FILES
-.Pp
-.Bd -filled
The log file (ie. /var/log/gopherd.log) has the following structure:
-.Ed
.
.Pp
.Ic [<date>|<IP:port>] <item path> <query> (<status>)
@@ -481,38 +400,32 @@ where,
.Bl -inset
.It Ic <date>
= access date and time (std 'date' format)
-.Bl -inset -offset indent
-ex.
+.Pp
+ ex.
.Qq "Sun Feb 17 06:11:10 PST 2008"
-.El
.It Ic <IP:port>
= client IP address and port served
-.Bl -inset -offset indent
+.Pp
ex.
.Qq "24.208.18.127:16857"
-.El
.Pp
.It Ic <item path>
= full path to item served
-.Bl -inset -offset indent
+.Pp
ex.
.D1 Qo "/PICS/simple2.jpg" Qc for an image file
.D1 Qo "/PICS" Qc for a directory access
-.El
.It Ic <query>
= query term submitted (Type 7 requests only)
-.Bl -inset -offset indent
+.Pp
ex.
.Dl % snarf Qq "gopher://frog.bog/7/hello.cgi?Christoph"
.Dl would log Qo "Christoph" Qc as the query term.
-.El
.It Ic (<status>)
= status of client request
-.Bl -inset -offset indent
+.Pp
ex. - some common status entries:
-.El
.Pp
-.Bl -hang -width XXXXXXXXXXXXXXXX -compact -offset XXXXXXXXXXXX
.It Qo (serving) Qc
=> a successful request
.It Qo (not found) Qc
@@ -522,17 +435,15 @@ ex. - some common status entries:
.It Qo (dir listing) Qc
=> unindexed directory listing
.El
-.El
.
.Sh FILES
README, LICENSE, CGI, index.gph, rc.d/
.
-.Sh "SEE ALSO"
+.Sh SEE ALSO
Links for further information on gopher:
.Pp
.D1 Pa gopher://gopher.floodgap.com
.D1 Pa gopher://gopher.gopherproject.org
-.Pp
.Sh STANDARDS
.Em Internet RFC 1436
.
@@ -553,7 +464,6 @@ geomyidae is released under the MIT/X Consortium License.
.
.Sh BUGS
Dynamic content functionality may vary across gopher clients.
-.Ed
.
.Ss "Reporting Bugs"
Report bugs to:
diff --git a/rc.d/NetBSD.rc.d b/rc.d/NetBSD.rc.d
@@ -1,21 +1,22 @@
#!/bin/sh
#
-# REQUIRE: local
# PROVIDE: geomyidae
+# REQUIRE: LOGIN
+# KEYWORD: shutdown
$_rc_subr_loaded . /etc/rc.subr
name="geomyidae"
rcvar=$name
-command="/usr/pkg/sbin/${name}"
+command="/usr/local/bin/${name}"
#####################################################
# Geomyidae Options Section - "?" => geomyidae(8) #
# Uncomment & define options (defaults are shown) #
#####################################################
#
-#LOGFILE="-l /var/log/gopherd.log"
+#LOGFILE="-l /var/log/gopherlog"
#LOGLEVEL="-v 7"
#HTDOCS="-b /var/gopher"
#PORT="-p 70"
@@ -26,10 +27,11 @@ command="/usr/pkg/sbin/${name}"
#IP="-i 127.0.0.1"
######################################################
-# Now remove any UNDEFINED options from line below: #
+# Next, add all DEFINED options to command_args= #
######################################################
#
-command_args="$LOGFILE $LOGLEVEL $HTDOCS $PORT $SPORT $USR $GRP $HOST $IP"
+#command_args="$LOGFILE $LOGLEVEL $HTDOCS $PORT $SPORT $USR $GRP $HOST $IP"
+command_args=""
######################################################
@@ -43,7 +45,7 @@ command_args="$LOGFILE $LOGLEVEL $HTDOCS $PORT $SPORT $USR $GRP $HOST $IP"
#{
# echo "Starting $name"
# $command $command_args
-# pgrep -x $name > $pidfile
+# pgrep -n $name > $pidfile
#}
######################################################
