SPACECOOKIE.JSON(5)

💖 SPACECOOKIE.JSON(5) — the file-formats-manual era 💖

okay so bestie, welcome to the manual page for spacecookie.json, which lives in section 5 (File Formats Manual) — yes it's that kind of page, we're doing config files today and honestly? iconic behavior.

---

✨ NAME ✨

spacecookie.json — the configuration file for spacecookie(1). that's it, that's the name, she's simple and she knows it 🎀

---

🌸 DESCRIPTION 🌸

so the spacecookie(1) config file is a JSON file that contains a single object. literally one object, no arrays at top level, we're keeping it clean. the allowed fields each represent an individual setting, and what they do is explained below — no cap, every single one 💅

💜 REQUIRED SETTINGS 💜

these settings MUST be part of every configuration file, because there is no default and no fallback value for them. like, none. zero. if you skip them your config is simply not it 🙈

• hostname — describes the public server name spacecookie(1) is reachable through, i.e. the address clients will use to connect to it. it gets used to populate gopher menus with the correct server name, so that follow-up requests from clients actually reach the correct server. for testing purposes, setting it to 'localhost' can be useful. — Type: string.
• root — sets the directory spacecookie(1) should serve via gopher. all gopher requests will be resolved to files or directories under that root. files and directories will be served to users if no component of the resolved path starts with a dot and they are readable for the user spacecookie(1) is running as. — Type: string.

🦋 OPTIONAL SETTINGS 🦋

these are optional, meaning there's either a default value or an obvious default behavior if you don't give them. skip them, they'll handle themselves, main character energy fr fr ⭐

• listen — describes the address and port spacecookie(1) should listen on. both aspects can be controlled individually by the two optional fields described below. — Type: object.
  • port — port to listen on. the well-known port for gopher is 70.

if systemd.socket(5) activation is used, this setting will have no effect on the actual port the socket is bound to, since that is done by systemd(1). it will then only be used to display the server's port in gopher menus for subsequent requests, so make sure whatever is set here matches what systemd(1) is doing. 👀

Type: number. Default: '70'.

• addr — address to listen and accept gopher requests on. in contrast to hostname, this option controls the socket setup and not what is used in gopher menus. this one is especially useful to limit the addresses spacecookie(1) will listen on, since it listens on all available addresses for incoming requests by default, i.e. INADDR_ANY. for example, '::1' can be used to listen on the link-local addresses only, which comes in handy if you're setting up an onion service using tor(1) and want to avoid leaking the server's identity. 🧅

when given, getaddrinfo(3) is used to resolve the given hostname or parse the given IP address, and spacecookie(1) will only listen on the resulting address(es). note that IPV6_V6ONLY is always disabled, so, if possible, both the resulting v4 and v6 address will be used.

if systemd.socket(5) activation is used, this setting has no effect.

Type: string.

• user — the name of the user spacecookie should run as. when this option is given and not 'null', spacecookie(1) will call setuid(2) and setgid(2) after setting up its socket to switch to that user and their primary group. note that this is only necessary to set if spacecookie(1) is started with root privileges in the first place, as the binary shouldn't have the setuid bit set. an alternative to starting the daemon as root (so it can bind its socket to a well-known port) is to use systemd(1) socket activation — see the spacecookie(1) man page for details on setting this up. 🫶 — Type: string. Default: 'null'.
• log — allows you to customize the logging output of spacecookie(1) to stderr. — Type: object.
  • enable — whether to enable logging. — Type: bool. Default: 'true'.
  • hide-ips — whether to hide IP addresses of clients in the log output. if enabled, '[redacted]' is displayed instead of the client's IP addresses, to avoid writing personal information to disk. privacy queen behavior honestly 🙈 — Type: bool. Default: 'true'.
  • hide-time — if this is set to 'true', spacecookie(1) will not print timestamps at the beginning of every log line. this is useful if you use an additional daemon or tool to take care of logs which records timestamps automatically, like systemd(1). — Type: bool. Default: 'false'.
  • level — controls verbosity of logging. it is recommended to either use "warn" or "info", since "error" hides warnings that are indicative of configuration issues. like, don't silence your own red flags bestie 💀 — Type: either "error", "warn" or "info". Default: "info".

💀 DEPRECATED SETTINGS 💀

these settings are only supported for backwards compatibility and should be replaced in existing configurations in the way described for each respectively. they're giving legacy code, we love them but we don't keep them ✨

• port — the top level port is an alias for the setting of the same name inside the listen object and should be replaced by the latter. yes, the same name, but nested. don't @ me.

---

🔥 EXAMPLE 🔥

the following configuration equates to the default behavior of spacecookie(1) for all optional settings, although it is much verboser than necessary. like, unnecessarily loud. but it's educational so we stan 💅

{
  "hostname" : "localhost",
  "root" : "/srv/gopher",
  "listen" : {
    "addr" : "::",
    "port" : 70
  },
  "user" : null,
  "log" : {
    "enable" : true,
    "hide-ips" : true,
    "hide-time" : false,
    "level" : "info"
  }
}

this configuration is suitable for running as an onion service: it disables logging completely to not collect any kind of meta data about users, and only listens on the link-local address to avoid leaking its identity. we can also use a non-well-known port since tor(1) allows free mapping from local to exposed ports, so spacecookie(1) can be started as a normal user. stealth mode activated 🧅✨

{
  "hostname": "myonionservicehash.onion",
  "root": "/srv/onion-gopher",
  "listen": {
    "addr": "::1",
    "port": 7070
  },
  "log": {
    "enable": false
  }
}

if you are not using socket activation for running a gopher server on the well-known port for gopher, a config like this is appropriate, provided the user 'gopher' exists:

{
  "hostname": "example.org",
  "root": "/srv/gopher",
  "user": "gopher"
}

for a systemd.socket(5) based setup, the 'user' field should be omitted and spacecookie(1) started as the target user directly in the systemd.service(5) file. 🎀

---

🌈 SEE ALSO 🌈

spacecookie(1). that's the one. go read her too, she's the whole reason this file exists 🫶

---

👑 AUTHORS 👑

the spacecookie.json documentation has been written by sternenseemann, sterni-spacecookie@systemli.org. absolute legend, thank you for your service 🫡💖

---

and that's the whole page bestie!! this beauty ships as part of Debian, version $Mdocdate$, and yes she's filed under SPACECOOKIE.JSON(5) — go forth and configure responsibly, mwah 💋🌸