uGopherServer, the universal gopher server
See LICENSE for copyright information

uGopherServer is a modern, featureful and relatively secure gopher
daemon built to be run under inetd, available under the 2-clause
BSD license. Binaries are available under the combination of the
2-clause BSD license, the SSLeay license and the OpenSSL license.

uGS accepts the environment variables "REMOTE_ADDR" and "REMOTE_HOST"
with the same semantics so that if it is being run behind some kind
of proxy, it is possible for that proxy, with a counterpart
shielding uGS, to pass the address through to uGS.

It is based on the proven codebase of Gophernicus 2014, and includes
numerous additions for TLS support, including user privilege droppage,
and obviously, TLS support. You MUST have OpenSSL available in
/usr/lib and /usr/include for it to compile.

Command line options:
    -h hostname   Change server hostname (FQDN)      [$HOSTNAME]
    -p port       Change server port                 [70]
                  Note that for a -S instance, you must specify a -p
                  above 100000 (it is suggested, if listening on
                  105, formerly the CSO/ph port, to use -p 100105) 
    -r root       Change gopher root                 [/var/gopher]
    -t type       Change default gopher filetype     [0]
    -g mapfile    Change gophermap file              [gophermap]
    -a tagfile    Change gophertag file              [gophertag]
    -c cgidir     Change CGI script directory        [/cgi-bin/]
    -u userdir    Change users personal gopherspace  [public_gopher]
    -l logfile    Log to Apache-compatible combined format logfile

    -H headerext  Change extension of header file    [Ghdr]
    -T tagext     Change extension of tag file       [Gtag]
    -F footerext  Change extension of footer file    [Gftr]

    -w width      Change default page width          [70]
                  Many sites would benefit from boosting this to 132.

    -o charset    Change default output charset      [US-ASCII]

    -s seconds    Session timeout in seconds         [1800]
    -i hits       Maximum hits until throttling      [4096]
    -k kbytes     Maximum transfer until throttling  [4194304]

    -f filterdir  Specify directory for output filters
    -e ext=type   Map file extension to gopher filetype
    -R old=new    Rewrite the beginning of a selector

    -D text|file  Set or load server description for caps.txt
    -L text|file  Set or load server location for caps.txt
    -A admin      Set admin email for caps.txt

    -S certkeypem Enable SSL/TLS protection          [disabled]
                  Requires a gophernicus compiled with OpenSSL
                  support. The argument must be specified and
                  is a path, preferably absolute, to your SSL
                  certificate. Must be readable by the user
                  the process runs as before going privdrop.
    -K cipherlist Specify custom cipherlist. No effect unless
                  -S. Normally you don't need to.

    -U droptouser Drop privileges to this username   [<none>]
                  after reading certificates.
    -G group      Drop privileges to this group      [group of -U]
                  after reading certificates.
    The above two options are unnecessary if running plaintext,
    however if the daemon is started as root, you must use them
    or disable root checking (not recommended.)

    -nv           Disable virtual hosting
    -nl           Disable parent directory links
    -nh           Disable menu header (title)
    -nf           Disable menu footer
    -nd           Disable dates and filesizes in menus
    -nc           Disable file content detection
    -no           Disable charset conversion for output
    -nq           Disable HTTP-style query strings (?query)
    -ns           Disable logging to syslog
    -na           Disable autogenerated caps.txt
    -nm           Disable shared memory use (for debugging)
    -nr           Disable root user checking (for debugging)

    -d            Debug to syslog (not for production use)
    -b            Display the BSD license
    -?            Display this help
 

Setting up a gopher site
========================

After succesfully installing uGopherServer (see INSTALL) you need to set
up the gopher root directory. By default uGopherServer serves documents
from /var/gopher so start by creating that directory and making sure
it's world-readable. Then, simply add files and directories under your
root, fire up a gopher browser (Firefox, Lynx) and open up this URL:

gopher://<HOSTNAME>/   (where <HOSTNAME> is your servers hostname)

That's it, your first gopher site is now up and running. If the links
on the root menu don't work, make sure you are using the -h <HOSTNAME>
parameter in your inetd.conf (with a valid resolveable hostname
instead of <HOSTNAME> - see INSTALL).


Security
========

Gophernicus, on which uGopherServer is based, was written with high
security in mind. There should be no buffer overflows or memory
allocation problems; it should be safe to run a publicly available
gopher server with uGopherServer.

However, the security settings (which are non-changeable) are so strict
that you need to keep one thing in mind. uGopherServer will only serve
world-readable content. Being readable by the server process is not
enough, all files and directories MUST be world-readable or they are
simply hidden from all listings and denied if a client asks for them.


Gophermaps
==========

By default all gopher menus are automatically generated from the
content of the directory being viewed. If you want to have
informational text along with the files, or if you want to completely
replace the generated menu with your own you need to take a look at
gophermaps. See the file README.gophermap for more information.

Menus can be writ piecemeal in part if you desire to have a preamble
before every menu item in uGopherServer. foo.Ghdr will be a
preamble to the item, and foo.Gftr will be the postamble.

Gophertags
==========

A gophertag file can be used to virtually rename a directory. Let's
assume that you have a directory called "foo" somewhere - it will
be listed as "foo" in all automatically generated menus. Now if you
create a file foo/gophertag and put the text "bar" into it the menus
will show "bar" but the links will still point to "foo". This is
useful for creating descriptive names for directories without
littering the file system with spaces and weird characters.

This feature is also supported for files now - create a foo.Gtag
to rename foo to the contents of the first line of foo.Gtag.

Personal gopherspaces
=====================

Gophernicus, and by extension, uGopherServer supports user
personal gopherspaces. If a user has a world-readable directory
called public_gopher/ in their home, a request for

   gopher://<HOSTNAME>/1/~user/

will serve documents from that directory.


Virtual hosting
===============

uGS supports virtual hosting, or serving more than one logical
domain using the same IP address. Since gopher (RFC1436) doesn't
support virtual hosting this requires some clever (but mostly
invisible) hacks.

To enable virtual hosting create one or more directories under your
gopher root which are named after your domain names. The primary vhost
directory (set with the -h <HOSTNAME> option) must exist or virtual
hosting will be disabled. Then simply add content to the hostname
directories and you're up and running.

Almost.

To make gopher clients work properly with virtual hosting, create a
root gophermap for each of your domains and include the "%" type
character to create a list of all available virtual hosts (see
README.gophermap). The generated virtual host links will be created so
that standard gopher clients will find the correct domain even when
they don't specifically tell the server which host they're trying to
reach.


CGI support
===========

uGopherServer supports most parts of the CGI/1.1 standard. Most
standard CGI variables are set, and some non-standard ones are added.

Currently, user input is broken due to debugging work done on the CGI
support. Query strings still work.

By default all scripts and binaries under any directory called
/cgi-bin/ are executed as CGI scripts (this includes cgi-bin
directories under users personal gopherspaces). Also, if a gophermap
is marked executable it is also processed as an CGI script.

As with regular files, CGI scripts must be world-executable (and
readable) or they will be ignored. Make sure your CGI script is safe
with ANY user input as poorly coded CGI scripts are the number #1
security problem with publicly open *nix servers.


Output filtering and PHP support
================================

In addition to CGI scripts uGopherServer supports output filtering
scripts. By default output filtering is turned off, but you can turn
it on by using the -f <FILTERDIR> option, creating that directory
and creating one or more scripts in there named by either the file
suffix, or by the gopher filetype char.

If a file is to be served out which matches either the file suffix
script, or the filetype script then instead of simply sending the
file to client the output filter script is executed with the
original file as the first parameter and the output of the script
is then sent to client.

For PHP support install the CLI version of the PHP interpreter and
then symlink (or copy) that binary to the directory specified with
-f option using the destination name "php".

$ ln -s /usr/bin/php5-cli /usr/lib/gophernicus/filters/php

After that all files with the php suffix will be "filtered" through
the PHP command line interpreter. In other words, PHP starts working.
And don't use the CGI version of PHP as it outputs HTTP headers the
gopher protocol doesn't have.


Charset support and conversions
===============================

uGopherServer supports three charsets: US-ASCII, ISO-8859-1 and
UTF-8. All textual input is internally upconverted to UTF-8 and then
downconverted to whatever charset the client is asking for. The
conversion is input autosensing which means that you don't have to
specify your filesystem charset, or the charset of your text files -
it's all detected automatically.

With standard gopher clients this is a bit of a problem as your text
files WILL be converted to 7-bit US-ASCII. This means that all 8-bit
charaters WILL BE LOST. This decision was made because no gopher
client that I tested was reliably cabable of decoding anything else
than pure US-ASCII. If you want to disable the conversion use the
"-no" option, or if you'd like to change the default output charset to
something else than US-ASCII just use for example the "-o ISO-8859-1"
option.


Selector rewriting
==================

Selector rewriting lets you rewrite parts of the selector on the fly.
Well, not parts, but really just the start of it. And the rewrite
engine here is nothing like Apache's mod_rewrite as I was too lazy
to integrate any regex libraries... So, all it does is rewrite a
fixed string at the start of the selector to something else. This
will let you move your directories around while making sure that
existing deeplinks still work.

Examples:

  -R "/~user=/~luser"
  -R "/old-dir=/new-dir"

*yawn*... Either this feature needs to be removed in Universal or
be drastically modified... Maybe send the rewriting to a CGI...


Session tracking and statistics
===============================

To enable virtual hosting with gopher (RFC1436) clients Gophernicus
tracks users and their session. As a side effect of that session
tracking, Gophernicus has simple throttling controls to keep nasty
users from killing your precious 120MHz PPC 604e server from dying
under the load. The throttling defaults are high enough that normal
human users will never hit the limits, but it's possible (and mostly
preferrable) that a badly behaving crawling agent will be throttled.

The current sessions and other real-time status data can be viewed
by opening the URL gopher://<HOSTNAME>/0/server-status . This status
view has been modeled after the Apache server-status which means
that it's possible to integrate Gophernicus into existing server
monitoring systems. To ease up such integrations, Gophernicus
supports HTTP requests of the server-status page using an URL like
http://<HOSTNAME>:70/server-status?auto