~zethra/stargazer

ref: 91f45b21a060f7b5902b61125f4f0ff859afe17d stargazer/doc/stargazer-ini.scd -rw-r--r-- 11.8 KiB
91f45b21 — Ben Aaron Goldberg docs: make requirement of routes clearer in docs 2 months ago
                                                                                
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
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
stargazer.ini(5)

# NAME

*stargazer.ini* - configuration file for *stargazer*(1)

# EXAMPLE CONFIG

```
listen = 0.0.0.0

[:tls]
store = /var/lib/gemini/certs
organiztion = example org

[example.com]
root = /srv/gemini/example.com

[example.com~(.*)\.cgi(.*)]
root = /srv/gemini/example.com/cgi-bin
cgi = on
```

An example config file should also be installed at
*/usr/share/stargazer/config.ini*

# SYNTAX

*stargazer.ini* is an INI file. Each line is either a key/value pair, or a
section heading. Key/value pairs are specified as key=value, and sections as
\[section]. Extra white space in generally ignored.

# CONFIGURATION KEYS

The meaning of the key depends on the section. Anonymous keys (prior to the
first [section] directive) are used to specify parameters for the daemon itself.
Sections whose name is prefixed with ":", e.g. [:tls], are sub-categories of
the daemon configuration. Otherwise, section names refer to the hostnames of
domains serviced by the *stargazer* daemon. Each of these sections is a route
that *stargazer* will server requests to. At least one route must be specified.

## ANONYMOUS KEYS

*listen*
	A space-separated list of addresses that the daemon shall bind to. Each
	address shall take the format *address*:*port*. If :*port* is omitted,
	1965 (the default Gemini port) is presumed. To specify an IPv6 address,
	enclose it in *[]*, e.g. *[::]*.

*connection-logging*
	Whether or not to log connections to stdout. Disabling this may increase
	performance. On by default. Always on if the debug cli flag is on.

*request-timeout*
	Number of seconds to wait for the client to send a complete request.  If
	the timeout is exceeded the timeout, stargazer will send `59 Request
	timeout` and close the connection. 5 seconds by default. Set to 0 to
	disable.

*response-timeout*
	Number of seconds to wait for the client to send a complete request and for
	stargazer to finish sending the response.  If the timeout is exceeded the
	timeout, stargazer will send and close the connection. Disabled by default
	default. *Warning*, if this is set, large files and cgi scripts may be cut
	off before their response finishes.

## TLS KEYS

The following keys are accepted under the *[:tls]* section:

*store*
	Path to the certificate store on disk. This should be a persistent
	directory writable by the daemon. The daemon manages its own
	certificates - no user intervention is required, except in the case of
	moving the daemon to another host, in which case the certificate store
	must be copied to the new host.

*organization*
	An optional key used during certificate generation. Fill this in with
	the name of the organization responsible for the host and it will be
	filled in as the X.509 /O name.

## ROUTING KEYS

To configure *stargazer* to service requests, routing keys must be defined. The
name of the configuration section is used to determine what kinds of requests it
configures.

The format of the section name is the _hostname_ to be serviced, followed by a
token which defines the routing strategy, and a _string_ whose format is
specific to each routing strategy. The token and match string may be omitted
(i.e. [_hostname_] alone), which implies path routing against "/".

|] *:*
:< Route by path prefix. The URL path is compared to "_string_/".
|  *=*
:  Exact match. The URL path must exactly match the _string_.
|  *~*
:  Regular expression routing. The _string_ is a Rust-compatible regular
   expression which is tested against the URL path.

See the docs for the syntax section of the docs for the regex rust crate 
for a definition of the regular expression syntax and features:

https://docs.rs/regex/1.4.2/regex/#syntax

Some example section names and examples of matching paths:

|[ *[example.org:/foo]*
:< /foo, /foo/bar, /foo/bar/baz
|  *[example.org=/foo.txt]*
:  /foo.txt
|  *[example.org~/[a-z]+\\.(png|jpg|webp)]*
:  /foo.png, /bar.webp

Routes should be ordered from least to most specific. The matching algorithm
attempts to match the URL against each route in reverse order, and chooses the
first route which matches.

Within each routing section, the following keys are used to configure how
*stargazer* will respond to matching requests:

*root*
	Configures the path on disk from which files shall be served for this
	host. The path component of the URL will be appended to this value to
	form the path to files on disk to serve.

	If example.org/foo/bar.txt is requested, and a route is configured for
	*[example.org:/foo]* with the root set to /srv/gemini,
	/srv/gemini/foo/bar.txt will be served.

*rewrite*
	If regular expression routing is used, the rewrite directive may be used
	to rewrite the URL path component before proceeding. The URL will be set
	to the value of the rewrite expression. If *\\N* appears in the rewrite
	value, where *N* is a number, that capture group will be substituted for
	*\\N*. If *\\{name}* appears, where *name* is a named capture group, it
	will be substituted. Capture group 0 refers to the entire matched path.

	Example:

	```
	[localhost~^/([a-zA-Z]+)\.(?P<extension>png|jpg)$]
	root=./root
	rewrite=/images/\1.\{extension}
	```

	This will rewrite a request for /example.png to /images/example.png.

*index*
	Configures the name of the index file which shall be served in the event
	that a request for this host does not include the filename part.
	Defaults to "index.gmi".

*auto-index*
	"on" to enable the auto-index feature, which presents clients with a
	list of files in the requested directory when an index file cannot be
	found. Off by default. Only availible for static file routes.

*lang*
	Set this value as the *lang* parameter for gemini files served under this
	route. The lang param will only be set for text/gemini responses. The Gemini
	Specification says that the lang parameter should contain a comma separated
	list of language identifier from RFC 4646. Stargazer will use the lang
	parameter as given in this config. It is up to the user to provid a valid
	list of languages. Currently, this parameter is only used when serving
	static files.

*charset*
	Set this value as the *charset* parameter for text files served under this
	route. The lang param will only be set for text/\* responses. If the lang
	paraparameter is also set, then lang will be set instead of charset for
	text/gemini responses. The Gemini Specification says that the charset
	parameter should be a character set specified in RFC 2046. Stargazer will
	use the charset parameter as given in this config. It is up to the user to
	provid a valid charset value. Currently, this parameter is only used when
	serving static files.

*redirect*
	Send a redirect to this URI instead of serving other content. The URI
	exactly as written will be send to the client. Mutually exclusive with most
	other settings.

*permanent*
	Send a permanent redirect instead of a temporary redirect. Requires
	*redirect* to be set.

*cgi*
	"on" to enable CGI support. *root* must also be configured. See "CGI
	Support" for details. Mutually exclusive with *auto-index*.

*cgi-user*
	Run CGI process as this user and their primary group. Set to the name of
	the user. Otherwise process is run as same user as stargazer, which can be
	a security issue if the CGI process is untrusted (not that running
	untrusted CGI processes is a good idea to begin with). The user stargazer
	is run as must be able to setuid the child process to the user specified.

*scgi*
	"on" to enable SCGI support. *scg-address* must also be set.See "SCI
	Support" for details. *root*, *index*, and *auto-index* not allowed when
	*scgi* is on.

*scgi-address*
	The address of the SCGI server to connect to. If this is a valid file
	system path that exists, stargazer will connect to a Unix domain socket at
	that path to send requests. Otherwise the address value will be treated as a
	socket address and requests will be made over TCP.

*cgi-timeout*
	Maximum amount of time a CGI/SCGI process on this route is allowed to run.
	If the timeout is exceeded, stargazer will send a CGI error to the client
	and either kill the CGI process or close the SCGI connection. Values is a
	whole number of seconds. By default CGI processes have no timeout and
	stargazer will wait indefinitely for them to finish.

# CGI Support

*stargazer* supports a limited version of CGI, compatible with the Jetforce
server. It is not a faithful implementation of RFC 3875, but is sufficient for
most of the needs of Gemini servers.

Set *cgi=on* for a route configuration to enable CGI for that route and set
*root* to the path where the CGI scripts are found. If a client requests a
script, it will be executed, and must print a Gemini response (including status
code and meta) to stdout.

If a CGI process exceeded the timeout set by *cgi-timeout* or if connection to
client is lost and the CGI process is still running it will be killed. On \*nix
systems, the CGI process will receive a SIGTERM. If it is still running after 3
seconds it will receive a SIGKILL. On other systems (i.e. Windows) the CGI
process will just be killed. If *cgi-timeout* is exceeded, stargazer will send
a CGI error message to the gemini client before closing the connection.

When stargazer exits, any CGI processes that are currently running will receive
a SIGHUP.

The following environment variables will be set:

[[ *Variable*
:[ *Example*
:< *Description*
|  *GATEWAY_INTERFACE*
:  CGI/1.1
:  CGI version
|  *SERVER_PROTOCOL*
:  GEMINI
:  The server protocol
|  *SERVER_SOFTWARE*
:  stargazer/0.1.0
:  The stargazer server name and version
|  *GEMINI_URL*
:  See [1]
:  The URL requested by the client
|  *SCRIPT_NAME*
:  /cgi-bin/foo.sh
:  The portion of the URL referring to the script name.
|  *PATH_INFO*
:  /bar
:  The remainder of the path following *SCRIPT_NAME*.
|  *QUERY_STRING*
:  hello=world
:  The query string portion of the URL. [3]
|  *SERVER_NAME*, *HOSTNAME*
:  example.org
:  The server host name.
|  *SERVER_PORT*
:  1965
:  The server port number.
|  *REMOTE_HOST*, *REMOTE_ADDR*
:  10.10.0.2
:  The clients IP address.
|  *TLS_CLIENT_HASH*
:  See [2]
:  A fingerprint that can be used to uniquely identify the cert.
|  *TLS_CLIENT_NOT_BEFORE*
:  2020-10-22T04:31:40Z
:  The date the client's cert is not valid before. See [4].
|  *TLS_CLIENT_NOT_AFTER*
:  2021-10-22T04:31:59Z
:  The date the client's cert is not valid after. See [4].
|  *REMOTE_USER*
:  "My cert"
:  The client cert's issuer field.

\[1]: gemini://example.org/cgi-bin/foo.sh/bar?hello=world ++
\[2]: 1flC87yanv8KQ027TrvOOP/kA5yTWn3xLPJ+GxgaNB4= ++
\[3]: stargazer will attempt to percent decode the query string as UTF-8. If
this fails the string will be provided as is, undecoded.
\[4]: Timestamps are rfc3339 complaint, exact format is unspecified.

The exit status of the script is ignored.

# SCGI Support

*stargazer* has SCGI support similar to its CGI support.  Set *scgi=on* for a
route configuration to enable SCGI for that route and set *scgi-address* to the
address of the SCGI server. The address can either be a path to an Unix Domain
Socket or the TCP Socket address. The headers included in the SCGI request match
the CGI parameters list above with a few exceptions.

If the SCGI server doesn't finish responding before *cgi-timeout* is exceeded
(assuming one is set) stargazer will close the connection to the SCGI server
and send a CGI error to the gemini client.

If the connection to the gemini client is lost stargazer will close the
connection to the SCGI server.

New headers:

[[ *Variable*
:[ *Example*
:< *Description*
|  *CONTENT_LENGTH*
:  0
:  Length in bytes of the request body.  See [1].
|  *SCGI*
:  1
:  SCGI Version

\[1]: Aways *0* since gemini doesn't have request bodies but included as it's
required by the SCGI protocol.

CGI header that are omitted from SCGI:

- *GATEWAY_INTERFACE*

# AUTHORS

Maintained by Ben Aaron Goldberg <ben@benaaron.dev>. Up-to-date sources can be
found at https://sr.ht/~zethra/stargazer/ and bugs/patches can be submitted by
email to ~zethra/stargazer@lists.sr.ht.