| SPACECOOKIE(1) | General Commands Manual | SPACECOOKIE(1) |
spacecookie —
gopher server daemon
spacecookie |
[--version]
config.json |
spacecookie is a simple to use gopher
daemon for serving static files. It is either invoked with the
--version flag to print its version or with the path
to its config file as the single argument. The minimal config file needs to
tell spacecookie about the directory to serve and
the server's name, i. e. the hostname or IP address the server is reachable
through. All configuration options, the format and default values are
explained in
spacecookie.json(5).
On startup, spacecookie will check if it
has been started with systemd socket activation. If that's true, it will use
the socket passed from systemd, if not, it will setup the socket itself.
After that it will call
setuid(2)
to switch to a less privileged user if configured to do so and start
accepting incoming gopher requests on the socket. Note that using socket
activation eliminates the need for starting as a privileged user in the
first place because systemd will take care of the socket. The systemd
integration is explained in more detail in its own section.
spacecookie will not fork
itself to the background or otherwise daemonize which can, however, be
achieved using a supervisor. Logs are always written to
stderr and can be
collected and rotated by another daemon or tool if desired.
Incoming requests are filtered: No files or directories outside
the served directory or that start with a dot may be accessed by clients.
Allowed files are returned to clients unfiltered. For directories,
spacecookie checks if they contain a
‘.gophermap’ file: If they contain
one, it is used to generate the directory response, otherwise one is
generated automatically which involves guessing all file types from file
extensions. The default file type is
‘0’, text file. The file format of the
‘gophermap’ files and its use are
explained in
spacecookie.gophermap(5).
spacecookie optionally supports two
systemd-specific features: It acts as a
notify
type service and supports socket activation.
If you are writing a
systemd.service(5)
file, be sure to use the ‘Type=notify’
directive which allows spacecookie to tell systemd
when it has finished starting up and when it is stopping before actually
exiting.
For socket activation, create a
systemd.socket(5)
file that starts the spacecookie service. This has
several advantages: For one, it allows starting
spacecookie on demand only and reducing the load on
server startup. Additionally it means that the daemon doesn't ever need to
be started as root because it won't need to setup a socket bound to a
well-known port.
Mind the following points when configuring socket activation:
BindIPv6Only=both’ in
systemd.socket(5).
To listen on an IPv4 address only, you can use an IPv6 socket with a
mapped IPv4 address.Make sure to check your socket configuration settings carefully
since spacecookie doesn't run any sanity checks on
the socket received from
systemd(1)
yet.
An example
systemd.service(5)
and
systemd.socket(5)
file are provided in the spacecookie source
distribution in the ‘etc’
directory.
spacecookie.json(5), spacecookie.gophermap(5), systemd.service(5) and systemd.socket(5).
For writing custom gopher application using the spacecookie library refer to the API documentation.
By default, spacecookie always behaves
like a gopher server as described in
RFC1436.
However users can configure spacecookie to utilize
common protocol extensions like the
‘h’ and
‘i’ types and
URLs
to other protocols.
spacecookie has been written and
documented by sternenseemann,
sterni-spacecookie@systemli.org.
spacecookie supports no migitations or
attack surface reduction measures other than automatically switching to a
less privileged user after binding. It is recommended to use this feature
and to make use of containering or sandboxing like for example
systemd.exec(5)
supports.
TLS-enabled gopher, like the
‘gophers’ protocol supported by
curl(1)
is not natively supported by spacecookie at this
time.
| April 18, 2023 | Nixpkgs |