SPACECOOKIE.JSON(5) File Formats Manual SPACECOOKIE.JSON(5)

spacecookie.json — configuration file for spacecookie(1)

The spacecookie(1) config file is a JSON file which contains a single object. The allowed fields representing individual settings and their effect are explained below.

The following settings must be part of every configuration file as there is no default or fallback value for them.

Describes the public server name spacecookie(1) is reachable through, i. e. the address clients will use to connect to it. It will be used to populate gopher menus with the correct server name, so follow up requests from clients actually reach the correct server. For testing purposes, it can be useful to set it to ‘localhost’.

Type: string.

Sets the 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.

The following settings are optional, meaning there is either a default value or an obvious default behavior if they are not given.

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 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 this 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’.

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 option 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. . For example, ‘::1’ can be used to listen on the link-local addresses only which comes in handy if you are setting up a 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 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.

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’.

Allows to customize the logging output of spacecookie(1) to .

Type: object.

Wether to enable logging.

Type: bool. Default: ‘true’.

Wether to hide IP addresses of clients in the log output. If enabled, ‘[redacted]’ is displayed instead of client's IP addresses to avoid writing personal information to disk.

Type: bool. Default: ‘true’.

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’.

Controls verbosity of logging. It is recommended to either use "warn" or "info" since "error" hides warnings that are indicative of configuration issues.

Type: either "error", "warn" or "info". Default: "info".

The following settings are only supported for backwards compatibility and should be replaced in existing configurations in the way described for each respectively.

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.

The following configuration equates to the default behavior of spacecookie(1) for all optional settings, although it is much verboser than necessary.

{
  "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.

{
  "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.

spacecookie(1).

The spacecookie.json documentation has been written by sternenseemann, sterni-spacecookie@systemli.org.

April 18, 2023 Nixpkgs