1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
<title>SPACECOOKIE.JSON(5)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">SPACECOOKIE.JSON(5)</td>
<td class="head-vol">File Formats Manual</td>
<td class="head-rtitle">SPACECOOKIE.JSON(5)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">spacecookie.json</code> —
<span class="Nd">configuration file for
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a></span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>
config file is a JSON file which contains a single object. The allowed
fields representing individual settings and their effect are explained
below.</p>
<section class="Ss">
<h2 class="Ss" id="REQUIRED_SETTINGS"><a class="permalink" href="#REQUIRED_SETTINGS">REQUIRED
SETTINGS</a></h2>
<p class="Pp">The following settings must be part of every configuration file as
there is no default or fallback value for them.</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="hostname"><a class="permalink" href="#hostname"><b class="Sy">hostname</b></a></dt>
<dd>Describes the public server name
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> 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
‘<code class="Li">localhost</code>’.
<p class="Pp">Type: string.</p>
</dd>
<dt id="root"><a class="permalink" href="#root"><b class="Sy">root</b></a></dt>
<dd>Sets the the directory
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> 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 <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> is
running as.
<p class="Pp">Type: string.</p>
</dd>
</dl>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="OPTIONAL_SETTINGS"><a class="permalink" href="#OPTIONAL_SETTINGS">OPTIONAL
SETTINGS</a></h2>
<p class="Pp">The following settings are optional, meaning there is either a
default value or an obvious default behavior if they are not given.</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="listen"><a class="permalink" href="#listen"><b class="Sy">listen</b></a></dt>
<dd>Describes the address and port
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> should listen
on. Both aspects can be controlled individually by the two optional fields
described below.
<p class="Pp">Type: object.</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="port"><a class="permalink" href="#port"><b class="Sy">port</b></a></dt>
<dd>Port to listen on. The well-known port for gopher is
<span class="Ms">70</span>.
<p class="Pp">If
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
activation is used, this setting will have no effect on the actual
port the socket is bound to since this is done by
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>.
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
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>
is doing.</p>
<p class="Pp">Type: number. Default:
‘<code class="Li">70</code>’.</p>
</dd>
<dt id="addr"><a class="permalink" href="#addr"><b class="Sy">addr</b></a></dt>
<dd>Address to listen and accept gopher requests on. In contrast to
<b class="Sy">hostname</b>, this option controls the socket setup and
not what is used in gopher menus. This option is especially useful to
limit the addresses
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> will
listen on since it listens on all available addresses for incoming
requests by default, i. e.
<a class="permalink" href="#INADDR_ANY"><b class="Sy" id="INADDR_ANY">INADDR_ANY</b></a>.
For example, ‘<code class="Li">::1</code>’ can be used
to listen on the link-local addresses only which comes in handy if you
are setting up a onion service using
<a class="Xr" href="https://manpages.debian.org/unstable/tor.1.en.html">tor(1)</a>
and want to avoid leaking the server's identity.
<p class="Pp" id="IPV6_V6ONLY">When given,
<a class="Xr" href="https://manpages.debian.org/unstable/getaddrinfo.3.en.html">getaddrinfo(3)</a>
is used to resolve the given hostname or parse the given IP address
and <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>
will only listen on the resulting address(es). Note that
<a class="permalink" href="#IPV6_V6ONLY"><b class="Sy">IPV6_V6ONLY</b></a>
is always disabled, so, if possible, both the resulting v4 and v6
address will be used.</p>
<p class="Pp">If
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
activation is used, this setting has no effect.</p>
<p class="Pp">Type: string.</p>
</dd>
</dl>
</div>
</dd>
<dt id="user"><a class="permalink" href="#user"><b class="Sy">user</b></a></dt>
<dd>The name of the user spacecookie should run as. When this option is given
and not ‘<code class="Li">null</code>’,
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> will call
<a class="Xr" href="https://manpages.debian.org/unstable/setuid.2.en.html">setuid(2)</a>
and
<a class="Xr" href="https://manpages.debian.org/unstable/setgid.2.en.html">setgid(2)</a>
after setting up its socket to switch to that user and their primary
group. Note that this is only necessary to set if
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> 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
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>
socket activation. See the
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> man page for
details on setting this up.
<p class="Pp">Type: string. Default:
‘<code class="Li">null</code>’.</p>
</dd>
<dt id="log"><a class="permalink" href="#log"><b class="Sy">log</b></a></dt>
<dd>Allows to customize the logging output of
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> to
<a class="permalink" href="#stderr"><b class="Sy" id="stderr">stderr</b></a>.
<p class="Pp">Type: object.</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="enable"><a class="permalink" href="#enable"><b class="Sy">enable</b></a></dt>
<dd>Wether to enable logging.
<p class="Pp">Type: bool. Default:
‘<code class="Li">true</code>’.</p>
</dd>
<dt id="hide-ips"><a class="permalink" href="#hide-ips"><b class="Sy">hide-ips</b></a></dt>
<dd>Wether to hide IP addresses of clients in the log output. If enabled,
‘<code class="Li">[redacted]</code>’ is displayed
instead of client's IP addresses to avoid writing personal information
to disk.
<p class="Pp">Type: bool. Default:
‘<code class="Li">true</code>’.</p>
</dd>
<dt id="hide-time"><a class="permalink" href="#hide-time"><b class="Sy">hide-time</b></a></dt>
<dd>If this is set to ‘<code class="Li">true</code>’,
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> 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
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>.
<p class="Pp">Type: bool. Default:
‘<code class="Li">false</code>’.</p>
</dd>
<dt id="level"><a class="permalink" href="#level"><b class="Sy">level</b></a></dt>
<dd>Controls verbosity of logging. It is recommended to either use
"warn" or "info" since "error" hides
warnings that are indicative of configuration issues.
<p class="Pp">Type: either "error", "warn" or
"info". Default: "info".</p>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="DEPRECATED_SETTINGS"><a class="permalink" href="#DEPRECATED_SETTINGS">DEPRECATED
SETTINGS</a></h2>
<p class="Pp">The following settings are only supported for backwards
compatibility and should be replaced in existing configurations in the way
described for each respectively.</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt id="port~2"><a class="permalink" href="#port~2"><b class="Sy">port</b></a></dt>
<dd>The top level <b class="Sy">port</b> is an alias for the setting of the
same name inside the <b class="Sy">listen</b> object and should be
replaced by the latter.</dd>
</dl>
</div>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE"><a class="permalink" href="#EXAMPLE">EXAMPLE</a></h1>
<p class="Pp">The following configuration equates to the default behavior of
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> for all
optional settings, although it is much verboser than necessary.</p>
<div class="Bd Pp Bd-indent Li">
<pre>{
"hostname" : "localhost",
"root" : "/srv/gopher",
"listen" : {
"addr" : "::",
"port" : 70
},
"user" : null,
"log" : {
"enable" : true,
"hide-ips" : true,
"hide-time" : false,
"level" : "info"
}
}</pre>
</div>
<p class="Pp">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
<a class="Xr" href="https://manpages.debian.org/unstable/tor.1.en.html">tor(1)</a>
allows free mapping from local to exposed ports, so
<a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a> can be started
as a normal user.</p>
<div class="Bd Pp Bd-indent Li">
<pre>{
"hostname": "myonionservicehash.onion",
"root": "/srv/onion-gopher",
"listen": {
"addr": "::1",
"port": 7070
},
"log": {
"enable": false
}
}</pre>
</div>
<p class="Pp">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 ‘<code class="Li">gopher</code>’ exists:</p>
<div class="Bd Pp Bd-indent Li">
<pre>{
"hostname": "example.org",
"root": "/srv/gopher",
"user": "gopher"
}</pre>
</div>
<p class="Pp">For a
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
based setup, the ‘<code class="Li">user</code>’ field should
be omitted and <a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>
started as the target user directly in the
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.service.5.en.html">systemd.service(5)</a>
file.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr" href="./spacecookie.1.html">spacecookie(1)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">spacecookie.json</code> documentation has
been written by <span class="An">sternenseemann</span>,
<a class="Mt" href="mailto:sterni-spacecookie@systemli.org">sterni-spacecookie@systemli.org</a>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 3, 2022</td>
<td class="foot-os">NixOS</td>
</tr>
</table>
</body>
</html>
|
