SPACECOOKIE(1)

📦 version 1.1.0.1, in nixos 26.05, nixpkgs unstable

✨ SPACECOOKIE(1) ✨

okay bestie, so this is the manual page for spacecookie from the General Commands Manual — and honestly? it's giving iconic gopher daemon energy 💅

🌸 NAME 🌸

spacecookie — a gopher server daemon, no cap 🦋

🎀 SYNOPSIS 🎀

spacecookie [--version] config.json

💖 DESCRIPTION 💖

okay so picture this: spacecookie is literally a simple-to-use gopher daemon for serving static files. it's either invoked with the --version flag to print its version (vibe check: passed ✨) 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 the configuration options, the format, and default values are explained in spacecookie.json(5), iykyk 📖

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 set up the socket itself. after that it will call setuid(2) to switch to a less privileged user if configured to do so, and then 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 — main character energy from systemd, honestly 👑 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. it's lowkey giving "I don't do drama, I just log" 💀

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) 🗂️

🦋 SYSTEMD INTEGRATION 🦋

spacecookie optionally supports two systemd-specific features: it acts as a notify type service and supports socket activation. periodt.

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. it's literally keeping systemd in the loop, bestie 🫶

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 set up a socket bound to a well-known port. slay 💅

mind the following points when configuring socket activation:

  • the port set in the systemd.socket(5) file must match the port configured in spacecookie.json(5) ⚠️
  • the socket set up by systemd(1) must use the IPv6 address family and the TCP protocol. it is recommended to always set 'BindIPv6Only=both' in systemd.socket(5). to listen on an IPv4 address only, you can use an IPv6 socket with a mapped IPv4 address 🌐
  • as always, the hostname setting must match the public address or hostname the socket is listening on 🏠
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. not me warning you to double-check your work 😭

an example systemd.service(5) and systemd.socket(5) file are provided in the spacecookie source distribution in the etc directory 📁

🔥 SEE ALSO 🔥

for writing custom gopher applications using the spacecookie library, refer to the API documentation: https://hackage.haskell.org/package/spacecookie 🌈

⭐ STANDARDS ⭐

by default, spacecookie always behaves like a gopher server as described in RFC1436: https://tools.ietf.org/html/rfc1436. fr fr, that's the standard.

however, users can configure spacecookie to utilize common protocol extensions like the 'h' and 'i' types and URLs to other protocols: http://gopher.quux.org:70/Archives/Mailing%20Lists/gopher/gopher.2002-02%7C/MBOX-MESSAGE/34 🧚

💜 AUTHORS 💜

spacecookie has been written and documented by sternenseemann, sterni-spacecookie@systemli.org. iconic behavior, honestly 👑

🍓 SECURITY CONSIDERATIONS 🍓

spacecookie supports no mitigations 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. protect yourself bestie 🛡️

TLS-enabled gopher, like the 'gophers://' protocol supported by curl(1), is not natively supported by spacecookie at this time. sorry, no encrypted gopher era just yet 🙈

✨ sending love from the Debian fam on $Mdocdate$ — signed, SPACECOOKIE(1) 💖🎀🦋

📦 where this page comes from