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
|
<!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(1)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">SPACECOOKIE(1)</td>
<td class="head-vol">General Commands Manual</td>
<td class="head-rtitle">SPACECOOKIE(1)</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</code> —
<span class="Nd">gopher server daemon</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
<tr>
<td><code class="Nm">spacecookie</code></td>
<td>[<code class="Fl">--version</code>]
<var class="Ar">config.json</var></td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><code class="Nm">spacecookie</code> is a simple to use gopher
daemon for serving static files. It is either invoked with the
<code class="Fl">--version</code> flag to print its version or with the path
to its config file as the single argument. The minimal config file needs to
tell <code class="Nm">spacecookie</code> 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
<a class="Xr" href="./spacecookie.json.5.html">spacecookie.json(5)</a>.</p>
<p class="Pp">On startup, <code class="Nm">spacecookie</code> 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
<a class="Xr" href="https://manpages.debian.org/unstable/setuid.2.en.html">setuid(2)</a>
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.</p>
<p class="Pp" id="stderr"><code class="Nm">spacecookie</code> will not fork
itself to the background or otherwise daemonize which can, however, be
achieved using a supervisor. Logs are always written to
<a class="permalink" href="#stderr"><b class="Sy">stderr</b></a> and can be
collected and rotated by another daemon or tool if desired.</p>
<p class="Pp">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,
<code class="Nm">spacecookie</code> checks if they contain a
‘<code class="Li">.gophermap</code>’ 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
‘<code class="Li">0</code>’, text file. The file format of the
‘<code class="Li">gophermap</code>’ files and its use are
explained in
<a class="Xr" href="./spacecookie.gophermap.5.html">spacecookie.gophermap(5)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYSTEMD_INTEGRATION"><a class="permalink" href="#SYSTEMD_INTEGRATION">SYSTEMD
INTEGRATION</a></h1>
<p class="Pp"><code class="Nm">spacecookie</code> optionally supports two
systemd-specific features: It acts as a
<a class="permalink" href="#notify"><b class="Sy" id="notify">notify</b></a>
type service and supports socket activation.</p>
<p class="Pp">If you are writing a
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.service.5.en.html">systemd.service(5)</a>
file, be sure to use the ‘<code class="Li">Type=notify</code>’
directive which allows <code class="Nm">spacecookie</code> to tell systemd
when it has finished starting up and when it is stopping before actually
exiting.</p>
<p class="Pp">For socket activation, create a
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
file that starts the <code class="Nm">spacecookie</code> service. This has
several advantages: For one, it allows starting
<code class="Nm">spacecookie</code> 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.</p>
<p class="Pp">Mind the following points when configuring socket activation:</p>
<ul class="Bl-bullet">
<li>The port set in the
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
file must match the port configured in
<a class="Xr" href="./spacecookie.json.5.html">spacecookie.json(5)</a>.</li>
<li>The socket set up by
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>
must use the IPv6 address family and the TCP protocol. It is recommended
to always set ‘<code class="Li">BindIPv6Only=both</code>’ in
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>.
To listen on an IPv4 address only, you can use an IPv6 socket with a
mapped IPv4 address.</li>
<li id="hostname">As always the
<a class="permalink" href="#hostname"><b class="Sy">hostname</b></a>
setting must match the public address or hostname the socket is listening
on.</li>
</ul>
<p class="Pp">Make sure to check your socket configuration settings carefully
since <code class="Nm">spacecookie</code> doesn't run any sanity checks on
the socket received from
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.1.en.html">systemd(1)</a>
yet.</p>
<p class="Pp">An example
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.service.5.en.html">systemd.service(5)</a>
and
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>
file are provided in the <code class="Nm">spacecookie</code> source
distribution in the ‘<code class="Li">etc</code>’
directory.</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.json.5.html">spacecookie.json(5)</a>,
<a class="Xr" href="./spacecookie.gophermap.5.html">spacecookie.gophermap(5)</a>,
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.service.5.en.html">systemd.service(5)</a>
and
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.socket.5.en.html">systemd.socket(5)</a>.</p>
<p class="Pp">For writing custom gopher application using the spacecookie
library refer to the
<a class="Lk" href="https://hackage.haskell.org/package/spacecookie">API
documentation</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp">By default, <code class="Nm">spacecookie</code> always behaves
like a gopher server as described in
<a class="Lk" href="https://tools.ietf.org/html/rfc1436">RFC1436</a>.
However users can configure <code class="Nm">spacecookie</code> to utilize
common protocol extensions like the
‘<code class="Li">h</code>’ and
‘<code class="Li">i</code>’ types and
<a class="Lk" href="http://gopher.quux.org:70/Archives/Mailing%20Lists/gopher/gopher.2002-02%7C/MBOX-MESSAGE/34">URLs
to other protocols</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><code class="Nm">spacecookie</code> has been written and
documented by <span class="An">sternenseemann</span>,
<a class="Mt" href="mailto:sterni-spacecookie@systemli.org">sterni-spacecookie@systemli.org</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SECURITY_CONSIDERATIONS"><a class="permalink" href="#SECURITY_CONSIDERATIONS">SECURITY
CONSIDERATIONS</a></h1>
<p class="Pp"><code class="Nm">spacecookie</code> 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
<a class="Xr" href="https://manpages.debian.org/unstable/systemd.exec.5.en.html">systemd.exec(5)</a>
supports.</p>
<p class="Pp">TLS-enabled gopher, like the
‘<code class="Li">gophers</code>’ protocol supported by
<a class="Xr" href="https://manpages.debian.org/unstable/curl.1.en.html">curl(1)</a>
is not natively supported by <code class="Nm">spacecookie</code> at this
time.</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>
|
