SPACECOOKIE(1) General Commands Manual SPACECOOKIE(1)

spacecookiegopher 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 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 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:

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,

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