~zethra/stargazer

ref: fbbf828c33087d1601d81db7c99c41d71fcb930f stargazer/doc/stargazer.ini.5.txt -rw-r--r-- 17.9 KiB
fbbf828c — Ben Aaron Goldberg config: add bad config for testing 4 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
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
stargazer.ini(5)	  File Formats Manual	      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 gen‐
       erally 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 pre‐
       fixed 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 sec‐
       tions 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 pre‐
	   sumed. 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 re‐
	   quired, 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-	/foo.png, /bar.webp
       z]+\.(png|jpg|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 direc‐
	   tive 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/ex‐
	   ample.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/gem‐
	   ini 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 con‐
	   tent. 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 pro‐
	   cesses 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. Oth‐
	   erwise the address value will be treated as a socket ad‐
	   dress 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 run‐
       ning 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 run‐
       ning 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 proto‐ │
       │		   │			  │ col		      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │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 follow‐  │
       │		   │			  │ ing SCRIPT_NAME.  │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │QUERY_STRING	   │ hello=world	  │ The query string  │
       │		   │			  │ portion of the    │
       │		   │			  │ URL. [3]	      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │SERVER_NAME,	   │ example.org	  │ The server host   │
       │HOSTNAME	   │			  │ name.	      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │SERVER_PORT	   │ 1965		  │ The server port   │
       │		   │			  │ number.	      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │REMOTE_HOST, RE‐   │ 10.10.0.2		  │ The clients IP    │
       │MOTE_ADDR	   │			  │ address.	      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │TLS_CLIENT_HASH	   │ See [2]		  │ A fingerprint     │
       │		   │			  │ that can be used  │
       │		   │			  │ to uniquely iden‐ │
       │		   │			  │ tify the cert.    │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │TLS_CLIENT_NOT_BE‐ │ 2020-10-22T04:31:40Z │ The date the      │
       │FORE		   │			  │ client's cert is  │
       │		   │			  │ not valid before. │
       │		   │			  │ See [4].	      │
       ├───────────────────┼──────────────────────┼───────────────────┤
       │TLS_CLIENT_NOT_AF‐ │ 2021-10-22T04:31:59Z │ The date the      │
       │TER		   │			  │ 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, un‐
       decoded. [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 ad‐
       dress 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 con‐
       nection 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 in‐
       cluded 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.

			      2021-07-06	      stargazer.ini(5)