motsognir(8) - FreeBSD Ports 15.1.quarterly Manual Pages

home | help

MOTSOGNIR(8) The mighty gopher server MOTSOGNIR(8)

NAME
motsognir - a simple, fast gopher server with CGI and PHP support

INTRODUCTION
Motsognir is a robust, reliable and easy to install open-source gopher
server for Unix-like systems. Motsognir supports server-side CGI applica-
tions and PHP scripts, is plainly compatible with UTF-8 filesystems, and is
entirely written in ANSI C without external dependencies. It supports both
IPv4 and IPv6 'out of the box', without requiring any special configura-
tion.

Gopher is a distributed document search and retrieval network protocol de-
signed for the Internet. Its goal is to function as an improved form of
Anonymous FTP, enhanced with hyperlinking features similar to that of the
World Wide Web.

I wrote Motsognir primarily for fun, but it appears to have become a strong
gopher server implementation with some very nice points: easy to install,
lightweight, portable, secure...

The Motsognir gopher server is meant to be used for small projects (like
home servers), but should scale well on bigger architectures as well. All
the configuration is done via a single configuration file, which has very
reasonable defaults. That makes Motsognir easily maintainable, and allows
the administrator to have a full knowledge of what features are allowed/en-
abled on the server.

INSTALLATION
Motsognir is already available prepackaged for a variety of operating sys-
tems. If you could not find a package suitable for your system, then in-
stalling Motsognir on your system is still very easy. On the first place,
you will have to build it. Assuming you have the basic GNU development
tools installed (make, gcc), building Motsognir should be as easy as:

# make

This will generate a 'motsognir' executable. You will need to install it to
your system:

# make install

Now, all you have to do is edit your /etc/motsognir.conf file to make it
suit your needs, and then launch motsognir:

# /usr/sbin/motsognir

Last note: If you wish to store the motsognir.conf file outside of /etc/,
this is possible as well, but you will have to instruct motsognir about its
location every time your run it:

# /usr/sbin/motsognir --config /my/custom/location/motsognir.conf

CONFIGURATION FILE
The Motsognir's configuration file is located by default in /etc/motsog-
nir.conf, and should be readable by the user which will run the motsognir
service. The configuration file is a plain-text file, containing some to-
kens with values. All lines beginning with the "#" character are ignored
(and can be used to put some comments in the configuration file). If any
of the parameter is missing from the configuration file, or have an empty
value, Motsognir will load a default value instead. Here is an example of a
self-explanatory configuration file:

##############################################################
# #
# CONFIGURATION FILE FOR THE MOTSOGNIR GOPHER SERVER #
# #
##############################################################

## Server's hostname ##
# The hostname the gopher server is reachable at. This setting is highly
# recommended, because the gopher protocol is heavily relying on
# self-pointing links. If not declared, the server's IP address will be used
# instead.
#GopherHostname=gopher.example.com

## Gopher TCP port ##
# The TCP port on which the public Gopher server listens on.
# Usually, gopher servers are published on port 70. Default: 70.
GopherPort=70

## Bind on IP address ##
# Set this 'bind' parameter to the IP address you'd like Motsognir to listen
# on. Note, that this parameter must be either an IPv6 address, or an IPv4
# address written in IPv4-mapped IPv6 notation (for ex. "::FFFF:10.0.0.1").
# If not specified, Motsognir will listen on all available IP addresses.
# This setting might be useful if you have a multihomed server, and you would
# like to serve different content for each IP address.
# Examples:
# bind=2001:DB8:135:A0E3::2
# bind=::FFFF:192.168.0.3
bind=

## Root directory ##
# That's the local path to Gopher resources. Note, that if you use
# a chroot configuration, you must provide here the virtual path
# instead of the real one.
# The default path is /var/gopher/
GopherRoot=/var/gopher/

## User home directories ##
# If you'd like to serve gopher content from user directories, using the
# classic /~user/ URL scheme, then define the user directories location here
# below. The configured location must contain a '%s' tag, which will be
# substituted with the username by motsognir. This must be an absolute path.
# If nothing is configured, then support for serving content from user
# directories won't be available. Example:
# UserDir=/home/%s/public_gopher/
UserDir=

## chroot configuration ##
# If you'd like to put Motsognir inside a chroot jail, configure here
# the chroot directory that shall be used.
# By default no chroot is used.
chroot=

## Paranoid mode ##
# For paranoidal security, you might want to enable "Paranoid mode". In this
# mode, Motsognir accepts to serve only files with permissions set to "world
# readable".
# Possible values: 0 (disabled) or 1 (enabled). Disabled by default.
ParanoidMode=0

## Activate the verbose mode ##
# Here you can enable/disable the verbose mode. In verbose mode,
# Motsognir will generate much more logs. This is useful only in
# debug situations.
# Possible values: 0 (disabled) or 1 (enabled). Disabled by default.
Verbose=0

## CGI support ##
# The line below enables/disables CGI support. Read the manual
# for details.
# Possible values: 0 (disabled) or 1 (enabled). Disabled by default.
GopherCgiSupport=0

## PHP support ##
# There you can enable PHP support.
# Possible values: 0 (disabled) or 1 (enabled). Disabled by default.
GopherPhpSupport=0

## Run as another user ##
# If you start motsognir under a root account, you might want to configure
# it so it drops root privileges as soon as it doesn't need them anymore and
# switches to another user. This is recommended for increased security,
# unless you already run Motsognir as a non-root user.
# To do so, provide here the username of the user that Motsognir should run
# as. Default = no value.
RunAsUser=

## Default gophermap #
# If you wish that your server would use a default gophermap when displaying
# a directory that do not have a gophermap, you can specify here a path to
# the gophermap file you'd like to use.
DefaultGophermap=

## HTTP error file
# When Motsognir receives a HTTP request, it answers with a HTTP error,
# along with a html message indicating why it is wrong. If you'd like to use
# a custom html file, you can set it here. Note, that the specified file is
# loaded when Motsognir's starts. If you modify the file afterwards, you'll
# need to restart the Motsognir process for the file to be reloaded.
# Example: HttpErrFile=/etc/motsognir-httperr.html
HttpErrFile=

## Caps.txt support ##
# Caps.txt is a specific file-like selector, which allows a gopher client to
# know more about the server's implementation (for example what the path's
# delimiter is, where is the server located, etc). When enabled, Motsognir
# will answer with caps-compatible data to requests for "/caps.txt".
# Caps support is enabled by default (CapsSupport=1).
CapsSupport=1

## Caps additionnal informations ##
# If Caps support is enabled, you can specify there some additional
# informations about your server. These informations will be served
# to gopher clients along with the CAPS.TXT data.
# Example:
# CapsServerArchitecture=Linux/i386
# CapsServerDescription=This is my server
# CapsServerGeolocationString=Dobrogoszcz, Poland
CapsServerArchitecture=
CapsServerDescription=
CapsServerGeolocationString=

# [End of file here]

DIRECTORY LISTINGS
As any other gopher server, Motsognir will present to gopher clients list-
ings of available directories with a specific presentation. A specific re-
quirement of the Gopher protocol is that it needs to provide a "type" for
every resource. To detect that gopher type, Motsognir is simply basing on
the file's extension. Below is a table containing all relations between go-
pher filetypes and real file extensions (at least that's the way Motsognir
handles them):

Then, once all filetypes present in a given directory are known, Motsognir
will send a directory listing to the remote gopher client. Gophermaps
There are situations when you would like to have the absolute control on
how the server will display a directory. That's why Motsognir supports go-
phermaps. If Motsognir finds a file called "gophermap" (without any exten-
sion) in a directory, then it doesn't check the directory content, and sim-
ply outputs to the user the content of the gophermap. Note, that if you en-
able CGI and/or PHP support, Motsognir will also look for respectively go-
phermap.cgi and gophermap.php files. A gophermap file contains gopher en-
tries as described by the RFC 1436. There's an example of a gophermap file
(of course <tab> have to be replaced by real tabs):

iWelcome to my gopher server!<tab>fake<tab>null<tab>0
i<tab>fake<tab>null<tab>0
0About my server<tab>/about.txt<tab>mygopher.domain.net<tab>70
1Download<tab>/download<tab>mygopher.domain.net<tab>70
1A link to a friend's server<tab><tab>friend.domain.net<tab>70
hMy Website<tab>URL:http://mywebsite.com<tab><tab>

You can omit the server's address and server's port parts in your gophermap
files (unless these are dynamically generated via CGI or PHP). If you don't
specify a port, Motsognir provides the one your server is using (usually
70). If you don't specify a host, Motsognir provides your server's host-
name. If you specify a relative selector (not beginning by a / character)
instead of an absolute path, Motsognir sticks on the path of the currently
browsed directory (but only if the host part is omitted, or pointing to
your own server). Therefore, a simpler form of the above gophermap could
look like that:

iWelcome to my gopher server!
i
0About my server<tab>about.txt
1Download<tab>download
1A link to a friend's server<tab>friend.domain.net<tab>70
hMy Website<tab>URL:http://mywebsite.com

A special feature of Motsognir regarding gophermap files is the ability to
generate a dynamic file listing inside a gophermap, using a special %FILES%
directive. Example:

iWelcome to my gopher server!
i
0About my server<tab>about.txt
i
iBelow are all the files I have in this directory:
%FILES%
i
iEnjoy!

Motsognir provides you with a feature that allows you to set a gophermap to
be used by any directory that do not have its own gophermap. This is the
'default' gophermap. The default gophermap have to be declared in the Mot-
sognir's configuration file, via the 'DefaultGophermap' directive.

CGI SUPPORT
Motsognir supports CGI application, which allows to run custom scripts and
applications interacting with the gopher client. Let's see how CGI works.
Each time a client requests the URL corresponding to your CGI program, the
server will execute it in real-time, then the output of your program will
go more or less directly to the client. In fact, when it comes to answer to
the client, the CGI application will output a gopher response (ie. a plain
text file for file type #0, a directory listing for file type #1, etc...).
This response will be catched by Motsognir, and forwarded to the gopher
client as being the request's answer. The Motsognir gopher server provides
some information to the CGI application, by setting some environment vari-
ables. Note, that for security reasons - and unlike some other CGI imple-
mentations - Motsognir will never feed CGI scripts with any command-line
parameters. Motsognir will set several environment variables, which can be
read by the called CGI script. Here is the complete list of these vari-
ables:

QUERY_STRING The URL parameters, as provided by the client
SERVER_SOFTWARE The name and version of the server software
SERVER_NAME The server's hostname, DNS alias, or IP address, used for self-referencing links
GATEWAY_INTERFACE The revision of the CGI specification, as supported by the server
REMOTE_ADDR The IP address of the remote client
REMOTE_HOST Same as REMOTE_ADDR
SCRIPT_NAME Script name (for self-referencing links)
SERVER_PORT The port number to which the request was sent

Note, that the QUERY_STRING variable will contain data inputed by the user.
For type #7 items, it will contain the search string (on type #7 items, the
gopher client usually asks the user for a query, using some kind of pop-
up). For any other item's type, the QUERY_STRING variable will contain the
part of the URL after the first "?" character (if any). For example, for a
request on "gopher://mygopher.server.com/0/myprog.cgi?hellothere", the
QUERY_STRING variable will contain the data "hellothere".

HOW TO ENABLE CGI SUPPORT
If you would like to use CGI applications on your Motsognir server, you
will have to enable CGI support in the Motsognir's configuration file (Go-
pherCgiSupport = 1). You will also have to make sure that your CGI programs
use the extension *.cgi.

PHP SUPPORT
PHP is a scripting language that is very popular in the web world. You can
use it with gopher, as well. Motsognir provides PHP support since its v1.0.
The PHP concept is very similar to CGI (historically, PHP was in fact born
as a set of custom CGI scripts), therefore you are advised to read the
chapter about CGI first. Most of it applies to PHP, too. The main differ-
ence is that instead of trying to directly execute PHP files, Motsognir
will feed them to your system's php interpreter, and collect the result.
To pass data to your PHP application, you will have to rely on the
QUERY_STRING environment variable. How to enable PHP support in Motsognir
First of all, make sure that php is available on your system. Then, simply
enable the parameter in Motsognir's configuration file (GopherPhpSupport =
1). Note, that all your php files must have the extension *.php to be rec-
ognized by Motsognir. Example Here below is a simple example of a PHP file
that could be used as a dynamic (PHP) gophermap with Motsognir.

<?php
echo "iHello, this is a php-driven gophermap\tx\tx\t0\r\n";
echo "i\tx\tx\t0\r\n";
echo "iCurrent date is " . date(DATE_RFC822) . "\tx\tx\t0\r\n";
echo "iServer powered by {$_SERVER}\tx\tx\t0\r\n";
echo "i\tx\tx\t0\r\n";
echo "1Go back\t\t{$_SERVER}\t{$_SERVER}\r\n";
?>

CAPS.TXT SUPPORT
Motsognir supports caps.txt since version 0.99.1. Caps.txt is a file-like
selector, which allows a gopher client to know more about the server's go-
pher implementation (like what is the path delimiter character, how are
structured server's paths, what the server's location is, etc). Caps.txt
support is configurable via the Motsognir's configuration file, using fol-
lowing tokens:

If you would like to have full access to what Motsognir sends in Caps.txt
data, you might consider disabling the caps.txt support in Motsognir
(CapsSupport=0), and simply host your own caps.txt file in the server's
root. Here is an example of such custom caps.txt file:

CAPS
CapsVersion=1
ExpireCapsAfter=3600
PathDelimiter=/
PathIdentity=.
PathParent=..
PathParentDouble=FALSE
PathKeepPreDelimeter=FALSE
ServerSoftware=Motsognir
ServerSoftwareVersion=1.0
ServerArchitecture=Linux/i386
ServerDescription=This is my gopher server
ServerGeolocationString=Dobrogoszcz, Poland

SECURITY CONSIDERATIONS
Like for any unix daemon, there are a few security aspects that one should
always keep in mind. Even the most carefully written programs can have
bugs, some of which could be exploited by malicious persons. This is the
reason why a system administrator should apply some security limitations
even to simplest or most trusted daemons.

RUNNING MOTSOGNIR AS A NON-PRIVILEGED (NON-ROOT) USER
A system daemon should not be run as root. In the (unlikely!) situation
where an attacker would gain control over Motsognir, having the process
running as an unprivileged user would greatly reduce the panel of harmful
actions that could be performed on your server. However, there is a prob-
lem: you will usually want to run your gopher server under the standard
TCP/70 port...and this being a low port requires the process to have root
privileges. That's why Motsognir provides a special configuration option
'RunAsUser'. It allows to set the username we'd like Motsognir to use, and
then, when Motsognir will be launched, it will first open the listening
port, and then drop its privileges and switch to the configured user.

CHOOSE YOUR FILE PERMISSIONS WISELY
If your Motsognir server runs as a non-privileged user, then it makes much
sense to limit permissions on files that it serves. If the gopher server is
not supposed to modify a file, this file should be set as 'read-only' and
owned by root. This way, even if Motsognir becomes compromised, it still
won't be able to modify these files.

USE PARANOID MODE IF YOU ARE (REALLY) PARANOID
By default, Motsognir will happily serve anything that is located somewhere
in the gopher root path, and that is readable by the gopher-running user.
To make things even more strict, you might want to use Motsognir's "Para-
noid mode" (configurable in Motsognir's configuration file). In this mode,
Motsognir will accept to serve only files that have "world readable" per-
missions set.

TRAP THE DAEMON INSIDE A CHROOT JAIL
The principle of a chroot jail is simple: run a process inside a 'virtual-
ized' environment with a modified root path (for example, mapping a chroot
/ on /srv/gopher/). This technique is used to make it impossible for the
process to access any file outside the chroot jail. A process can need some
files, like shared libraries, or configuration files, to run properly. If
chrooting a process, one would need to put all these files into the chroot
as well (and the process' executable file itself!). To avoid these prob-
lems, Motsognir provides a 'chroot' configuration parameter that, once set,
will make Motsognir run, load its configuration, and only then perform a
chroot to the designated directory. Note, that if you use any kind of dy-
namic files (*.cgi or *.php), you will need to take care to put all depen-
dencies of these applications inside the chroot jail. This includes a shell
at /bin/sh, all system libs that your applications might require, etc. Of-
ten a working /proc will also be needed.

LEGAL MUMBO-JUMBO
Copyright (C) Mateusz Viste 2008-2015 http://motsognir.sourceforge.net go-
pher://gopher.viste-family.net/1/projects/motsognir/

All rights reserved. This product or documentation is protected by copy-
right and is distributed under licenses restricting its use, copying, dis-
tribution and decompilation. See the GNU General Public License as pub-
lished by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version for details. The copyright owner gives
no warranties and makes no representations about the contents of this man-
ual and specifically disclaims warranties of merchantability or fitness to
any purpose. The copyright owner reserves the right to revise this manual
and to make changes from time to time in its content without notifying any
person of such revision or changes.

GRAPHIC IMAGES
The image of the dwarf on the cover of the printed manual is based on the
original work of Lorenz Frolich (1820-1908).

TRADEMARKS
Unix is a registered trademark of UNIX System Laboratories, Inc. Windows,
WindowsNT, and Win32 are registered trademarks of Microsoft Corp. All other
product names mentioned herein are the trademarks of their respective own-
ers.

November 1, 2014 MOTSOGNIR(8)

Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=motsognir&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help