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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>tipidee: the /etc/tipidee.conf configuration file</title>
<meta name="Description" content="tipidee: the /etc/tipidee.conf configuration file" />
<meta name="Keywords" content="tipidee configuration file" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">tipidee</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>/etc/tipidee.conf</tt> configuration file </h1>
<h2> Goal and usage </h2>
<p>
<tt>/etc/tipidee.conf</tt> is a text file written by the web administrator
to configure the <a href="tipideed.html">tipideed</a> server. After writing
or modifying this file, the administrator is expected to run the
<a href="tipidee-config.html">tipidee-config</a> program, that will read
<tt>/etc/tipidee.conf</tt> and output a <tt>/etc/tipidee.conf.cdb</tt> file
that will be suitable for <a href="tipideed.html">tipideed</a> to use.
</p>
<p>
<a href="tipidee-config.html">tipidee-config</a> provides sane defaults,
so an empty <tt>/etc/tipidee.conf</tt> file is perfectly usable
for purely static installations. But an empty file still needs to be
created, unless <a href="tipidee-config.html">tipidee-config</a> is run
with the <tt>-i /dev/null</tt> option.
</p>
<h2> Description </h2>
<p>
The <tt>/etc/tipidee.conf</tt> file contains a series of lines; every line is an
instruction. Lines do not wrap around and there is no quoting, so a newline is
always the end of an instruction. Empty lines, or lines containing only
whitespace, or lines beginning with <tt>#</tt> (comments), are ignored.
If a line contains a <tt>#</tt> that is not in the middle or end of a word, the
rest of the line is also considered a comment, and ignored.
</p>
<p>
Words on a line are separated by whitespace (spaces or tabs).
Instructions are one <em>directive</em>, the first word in the line, followed by
one or more <em>arguments</em>. Most directives take a fixed number of
arguments; some of them take a variable number. There are several types
of directives.
</p>
<div id="preprocess">
<h3> Preprocessing directives </h3>
</div>
<p>
These are meta-directives: they do not control <a href="tipideed.html">tipideed</a>'s
behaviour directly, but tell <a href="tipidee-config.html">tipidee-config</a> to
include other files. They allow administrators and packagers to write modular, pluggable
configuration files. Preprocessing directives always start with a <tt>!</tt>
(exclamation point, or <em>bang</em>) character.
</p>
<p>
You will probably never see preprocessing directives in simple configuration files.
They are meant for bigger or more generic configurations.
</p>
<div id="!include">
<h4> The <tt>!include</tt> directive </h4>
</div>
<p>
<code> !include <em>file</em> </code>
</p>
<ul>
<li> This directive will replace itself with the contents of <em>file</em>. </li>
<li> <em>file</em> can be a relative or absolute path. If relative, then
it is relative to the directory of the file being currently processed, i.e.
the file containing the <tt>!include</tt> directive. In other words, things
will work as you intuitively expect. </li>
</ul>
<div id="!includedir">
<h4> The <tt>!includedir</tt> directive </h4>
</div>
<p>
<code> !includedir <em>dir</em> </code>
</p>
<ul>
<li> This directive will include every file in directory <em>dir</em>. </li>
<li> File names starting with a <tt>.</tt> (dot) will be ignored (i.e. not included). </li>
<li> The inclusion order is deterministic: file names are sorted according to the C locale. </li>
<li> <em>dir</em> can be a relative or absolute path. If relative, then
it is relative to the directory of the file being currently processed, i.e.
the file containing the <tt>!includedir</tt> directive. In other words, things
will work as you intuitively expect. </li>
</ul>
<div id="!included:">
<h4> The <tt>!included:</tt> directive </h4>
</div>
<p>
<code> !included: unique </code> <br>
<code> !included: multiple </code>
</p>
<ul>
<li> This directive is usually written at the beginning of a file. Only one
such directive per file is allowed. </li>
<li> <tt>!included:</tt> governs what happens when a file is included
<em>more than once</em>.
<ul>
<li> If a file contains an <tt>!included: unique</tt> line, then all
inclusions of this file after the first one will be ignored: the contents
of the file will appear only once. </li>
<li> If a file contains an <tt>!included: multiple</tt> line, then the
file will be expanded into its contents <em>every time</em> the file is
included. </li>
<li> If a file does not contain an <tt>!included:</tt> directive, then
including it twice is an error, and
<a href="tipidee-config-preprocess.html">tipidee-config-preprocess</a>,
the program in charge of the preprocessing directives, will complain and
exit. </li>
</ul> </li>
<li> Don't forget the <tt>:</tt> (colon) at the end of the <tt>!included:</tt>
directive! </li>
</ul>
<div id="global">
<h3> Simple global settings </h3>
</div>
<p>
Global directives control global aspects of <a href="tipideed.html">tipideed</a>
— values that apply to the server itself, no matter what domain it is
serving.
<p>
Some global directives are introduced by their own keywords, see below.
Others are simple configuration values that would clutter up the
directive namespace, so we put them together under a unique umbrella,
the <tt>global</tt> directive.
<tt>global</tt> takes two arguments: the name of a setting and its value.
</p>
<div id="read_timeout">
<h4> <tt>read_timeout</tt> </h4>
</div>
<p>
<code> global read_timeout <em>t</em> </code>
</p>
<ul>
<li> <em>t</em> is a non-negative integer, in milliseconds. It represents
the maximum duration that a client is allowed to be idle. </li>
<li> If <em>t</em> milliseconds elapse without the client sending a request,
<a href="tipideed.html">tipideed</a> will assume it is done, close the
connection and exit. Also, if <em>t</em> milliseconds elapse while the client
is sending a request, and the request is still not complete,
<a href="tipideed.html">tipideed</a> will also close the connection. </li>
<li> The default is 0, meaning infinite: <a href="tipideed.html">tipideed</a>
will never slam the door into a client's face, even if the client is
excessively slow or fails to close a connection it's not using anymore. </li>
<li> A good setting is <tt>global read_timeout 60000</tt>, closing connections
after one minute of inactivity. </li>
</ul>
<div id="write_timeout">
<h4> <tt>write_timeout</tt> </h4>
</div>
<p>
<code> global write_timeout <em>t</em> </code>
</p>
<ul>
<li> <em>t</em> is a non-negative integer, in milliseconds. It represents
the maximum duration that <a href="tipideed.html">tipideed</a> will accept
to wait when sending data to the client. </li>
<li> If <em>t</em> milliseconds elapse while <a href="tipideed.html">tipideed</a>
is sending data to the client, <a href="tipideed.html">tipideed</a> will
give up and exit with an error message. </li>
<li> This typically happens when the network is congested, and the kernel's
socket send buffers are full. It could also mean that a client is failing to
read the data it has requested; or that the data is <em>very large</em> and
taking time to transfer. </li>
<li> The default is 0, meaning infinite: <a href="tipideed.html">tipideed</a>
will wait forever until the network uncongests and its client starts to behave. </li>
<li> An example setting is <tt>global write_timeout 600000</tt>, closing connections
if a transfer takes more than 10 minutes; but servers serving large files to
clients on slow connections will want a larger value. </li>
</ul>
<div id="cgi_timeout">
<h4> <tt>cgi_timeout</tt> </h4>
</div>
<p>
<code> global cgi_timeout <em>t</em> </code>
</p>
<ul>
<li> <em>t</em> is a non-negative integer, in milliseconds. It represents
the maximum duration that a CGI script spawned by
<a href="tipideed.html">tipideed</a> is allowed to run. </li>
<li> If <em>t</em> milliseconds elapse while a CGI script is running, and
<a href="tipideed.html">tipideed</a> hasn't gotten a full response yet,
the script will be killed, and <a href="tipideed.html">tipideed</a> will
send a 504 (Gateway Timeout) response to the client. </li>
<li> The default is 0, meaning infinite: <a href="tipideed.html">tipideed</a>
will wait forever until CGI scripts write their output. </li>
<li> An example setting is <tt>global cgi_timeout 10000</tt>, giving any
CGI scripts 10 seconds to complete — most users aren't willing to wait
more than a few seconds for a page to render anyway. </li>
</ul>
<div id="max_request_body_length">
<h4> <tt>max_request_body_length</tt> </h4>
</div>
<p>
<code> global max_request_body_length <em>n</em> </code>
</p>
<ul>
<li> <em>n</em> is a non-negative integer, in bytes. It represents the
maximum size that <a href="tipideed.html">tipideed</a> will accept for
the body of an HTTP request. </li>
<li> If the client sends a request with a body larger than <em>n</em> bytes,
<a href="tipideed.html">tipideed</a> will send a 413 (Content Too Large)
response and close the connection. </li>
<li> The default is 8192, which is large enough for most. </li>
<li> An example setting is <tt>global max_request_body_length 500</tt>,
when the administrator knows that no script on the site needs an input of
more than 500 bytes and anything larger is malicious. </li>
</ul>
<div id="max_cgi_body_length">
<h4> <tt>max_cgi_body_length</tt> </h4>
</div>
<p>
<code> global max_cgi_body_length <em>n</em> </code>
</p>
<ul>
<li> <em>n</em> is a non-negative integer, in bytes. It represents the
maximum size that <a href="tipideed.html">tipideed</a> will accept for
a CGI script's answer that it needs to process. </li>
<li> If a CGI script writes more than <em>n</em> bytes to its stdout,
<a href="tipideed.html">tipideed</a> will send a 502 (Bad Gateway)
response to the client and die with an error message. </li>
<li> This limit does not apply to NPH scripts, which send their stdout
directly to the client without any processing by <a href="tipideed.html">tipideed</a>. </li>
<li> The default is 4194304 (4 mebibytes). </li>
<li> An example setting is <tt>global max_cgi_body_length 100000000</tt>,
when the administrator knows that CGI scripts can write up to 100 megabytes.
Note that the CGI specification forces web servers to read the whole CGI
output in memory, so the larger the value, the more RAM
<a href="tipideed.html">tipideed</a> may consume in order to hold CGI
output data. And this is "private dirty" memory, i.e. memory that
<em>really</em> counts towards resource use on your server, so be careful with
that setting — and with the CGI scripts you choose to run. </li>
</ul>
<div id="executable_means_cgi">
<h4> <tt>executable_means_cgi</tt> </h4>
</div>
<p>
<code> global executable_means_cgi <em>value</em> </code>
</p>
<ul>
<li> <em>value</em> is a non-negative integer. If it is nonzero, then
all the documents that have an executable bit for "others" will be
considered CGI scripts by default. </li>
<li> This is useful when your CGI scripts are scattered among your
documents and you cannot gather them under a hierarchy like <tt>/cgi-bin/</tt>. </li>
<li> On the other hand, it should only be used by administrators who keep a
tight control on their documents. It is dangerous to activate this option
with dynamically managed content, because there could be files created with
the wrong permissions and improperly identified as CGI scripts, resulting in
failures or even security holes. </li>
<li> The classification of a given executable file as a CGI script
can be overridden by a local <tt>noncgi</tt> directive, see below. Such
a directive can protect dynamically managed content that is restricted
to a given hierarchy. </li>
</ul>
<div id="index-file">
<h3> The <tt>index-file</tt> directive </h3>
</div>
<p>
<code> index-file <em>file1</em> <em>file2</em> ... </code>
</p>
<p>
<tt>index-file</tt> is a global directive, the first one in this
list that is introduced by its own keyword and does not use <tt>global</tt>.
</p>
<ul>
<li> The <tt>index-file</tt> directive has a variable number of
arguments. <em>file1</em>, <em>file2</em>, and so on are the names of the
files that should be used to try and complete the URI when a client request
resolves to a directory. </li>
<li> For instance: <tt>index-file index.cgi index.html index.htm</tt>
means that when <a href="tipideed.html">tipideed</a> is asked to serve
<tt>http://example.com</tt>, it will first try to serve as if the request
had been <tt>http://example.com/index.cgi</tt>, then
<tt>http://example.com/index.html</tt>, then <tt>http://example.com/index.htm</tt>.
The first resource found is the one that is served; if none of the
resources exist, <a href="tipideed.html">tipideed</a> responds 404 (Not Found). </li>
<li> This is valid for any subdirectory: <tt>http://example.com/foo</tt>, if the
<tt>/foo</tt> resource resolves to a directory, is expanded to
<tt>http://example.com/foo/index.cgi</tt>, then (if not found)
<tt>http://example.com/foo/index.html</tt>, then (if not found)
<tt>http://example.com/foo/index.htm</tt>. </li>
<li> The default is <tt>index-file index.html</tt>, meaning that
only the <tt>index.html</tt> file will be looked up when a resource resolves
to a directory. </li>
</ul>
<div id="log">
<h3> The <tt>log</tt> directive </h3>
</div>
<p>
<tt>log</tt> is a global directive, introduced by the
keyword <tt>log</tt>. It allows the user to control what will appear in
<a href="tipideed.html">tipideed</a>'s log output.
</p>
<p>
<code> log nothing </code> <br>
<code> log <em>keyword1</em> <em>keyword2</em> ... </code>
</p>
<ul>
<li> <a href="tipideed.html">tipideed</a> writes all its logs to stderr.
It prints fatal error messages
with the prefix "<tt>tipideed: pid <em>pid</em>: fatal: </tt>",
and warning messages
with the prefix "<tt>tipideed: pid <em>pid</em>: warning: </tt>".
In normal operation, if everything goes well, you should never see
any of these. </li>
<li> Depending on what the <tt>log</tt> directive says, it also prints
informational messages related to what it's doing. These informational
messages all have the prefix "<tt>tipideed: pid <em>pid</em>: info: </tt>".
<ul>
<li> One line when <a href="tipideed.html">tipideed</a> starts and one
when it exits, if the <tt>log</tt> directive includes the <tt>start</tt> keyword. </li>
<li> Up to three lines per client request, controlled by the <tt>request</tt>,
<tt>resource</tt> and <tt>answer</tt> keywords. If you have a CGI script outputting
local redirections (which is rare), there may be several <tt>resource</tt> lines. </li>
</ul> </li>
<li> If no <tt>log</tt> directive has been provided, the default is
<tt>log request answer answer_size</tt>. </li>
</ul>
<p>
Here is the full list of keywords and what they do:
</p>
<dl>
<dt> <tt>nothing</tt> </dt> <dd> Don't log anything else than warning and error messages. This
keyword cannot be given with other keywords. </dd>
<dt> <tt>start</tt> </dt> <dd> Log a <tt>start</tt> line when <a href="tipideed.html">tipideed</a> starts
and an <tt>exit <em>exitcode</em></tt> line when it exits. </dd>
<dt> <tt>ip</tt> </dt> <dd> Add an <tt>ip <em>client_ip</em></tt> field to the <tt>start</tt> line.
This is potentially PII, so make sure to stay compliant with your local laws if you activate it.
<em>client_ip</em> is read from the TCPREMOTEIP environment variable.
This keyword has no effect when given without the <tt>start</tt> keyword. </dd>
<dt> <tt>hostname</tt> </dt> <dd> Add a <tt>host <em>client_hostname</em> </tt> field to the <tt>start</tt> line.
This is potentially PII, so make sure to stay compliant with your local laws if you activate it.
<em>client_hostname</em> is read from the TCPREMOTEHOST environment variable if it exists, or made up from
TCPREMOTEIP otherwise. Make sure to invoke
<a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a> before
<a href="tipideed.html">tipideed</a> in order to get meaningful values for this field.
This keyword has no effect when given without the <tt>start</tt> keyword. </dd>
<dt> <tt>host_as_prefix</tt> </dt> <dd> Prepend all <tt>request</tt>, <tt>resource</tt> and <tt>answer</tt>
lines with a <tt>host <em>host</em></tt> field. (This field will not be repeated in the <tt>request</tt>
line, so it changes the order of the fields in that line.) <em>host</em> is the virtual host the request is addressed
to. <tt>host_as_prefix</tt> is useful when you want to log entries for different virtual hosts to
different locations: for instance, if you're using
<a href="//skarnet.org/software/s6/s6-log.html">s6-log</a>, and want entries for <tt>example.com</tt> and
<tt>example.org</tt> to be logged to different backends, you would use the <tt>host_as_prefix</tt> directive,
and use <code>- +"^tipidee: pid [[:digit:]]*: info: host example\\.com " </code> in your logging script
to select <tt>example.com</tt>-related lines, and
<code>- +"^tipidee: pid [[:digit:]]*: info: host example\\.org " </code>
to select <tt>example.org</tt>-related lines. Note that warning and error messages would still need an additional
backend, as well as potential <tt>start</tt> and <tt>exit</tt> lines. </dd>
<dt> <tt>request</tt> </dt> <dd> Log a <tt>request</tt> line when <a href="tipideed.html">tipideed</a>
receives a request from its client. The line looks like <tt>request <em>method</em> host <em>host</em> path "<em>path</em>"
http <em>version</em></tt>. The path is decoded, but if there are non-printable characters in it, they are
encoded as hexadecimal values <tt>\0xab</tt>. If the request line includes a query, a <tt>query <em>query</em></tt> field
is added before the <tt>http</tt> field. </dd>
<dt> <tt>referrer</tt> </dt> <dd> Add a <tt>referrer "<em>referrer</em>"</tt> field to the <tt>request</tt> line, for
requests that include a <tt>Referer:</tt> header. <em>referrer</em> is quoted like <em>path</em>, to avoid
malicious clients messing with log lines.
This keyword has no effect when given without the <tt>request</tt> keyword. </dd>
<dt> <tt>user-agent</tt> </dt> <dd> Add a <tt>user-agent "<em>user-agent</em>"</tt> field to the <tt>request</tt> line, for
requests that include a <tt>User-Agent:</tt> header. <em>user-agent</em> is quoted like <em>path</em>, to avoid
malicious clients messing with log lines.
This keyword has no effect when given without the <tt>request</tt> keyword. </dd>
<dt> <tt>x-forwarded-for</tt> </dt> <dd> Add a <tt>x-forwarded-for "<em>xff</em>"</tt> field to the <tt>request</tt> line, for
requests that include an <tt>X-Forwarded-For:</tt> header. <em>xx</em> is quoted like <em>path</em> and <em>user-agent</em>,
for the same reasons.
This keyword has no effect when given without the <tt>request</tt> keyword. <br>
Note that if the connection is proxied, the <tt>start</tt> line, if any, will only have information about
the proxy, and only <tt>x-forwarded-for</tt> will have information about the client. Also note that
the information in an <tt>X-Forwarded-For:</tt> header is potentially PII, so make sure to stay
compliant with your local laws if you activate the option. </dd>
<dt> <tt>resource</tt> </dt> <dd> Log a <tt>resource</tt> line when <a href="tipideed.html">tipideed</a>
has found a resource corresponding to the URI and is willing to serve it. The line looks like
<tt>resource <em>file</em> type <em>type</em></tt>.
<em>file</em> is the path to the served file; the first component of that path is always
the document root of the virtual host. <em>type</em>
is <tt>nph</tt> for an NPH script, <tt>cgi</tt> for a CGI script, or the Content-Type for a regular file.
If it's a CGI or NPH script being called with a non-empty PATH_INFO, an additional <tt>path_info <em>path_info</em></tt>
field is added to the log line.
If a served CGI script outputs a local redirection, several <tt>resource</tt> lines may appear for
a single request. </dd>
<dt> <tt>answer</tt> </dt> <dd> Log an <tt>answer</tt> line when <a href="tipideed.html">tipideed</a>
answers the currently processed request. The line looks like <tt>answer <em>status</em></tt>, where <em>status</em> is
the 3-digit status code returned to the client. Note that there will be no <tt>answer</tt> line
when a NPH script is being run (because <a href="tipideed.html">tipideed</a> execs into the
NPH script). </dd>
<dt> <tt>answer_size</tt> </dt> <dd> Add a <tt>size <em>size</em></tt> field to the <tt>answer</tt> line,
containing the Content-Length of the answer.
This keyword has no effect when given without the <tt>answer</tt> keyword. </dd>
<dt> <tt>debug</tt> </dt> <dd> Log debug information. You should not need this in regular use. </dd>
</ul>
<div id="content-type">
<h3> The <tt>content-type</tt> directive </h3>
</div>
<p>
<tt>content-type</tt> is a global directive, introduced by the
keyword <tt>content-type</tt>. It allows
the user to define mappings from a document's extension to a standard Content-Type.
</p>
<p>
<code> content-type <em>type</em> <em>extension1</em> <em>extension2</em> ... </code>
</p>
<ul>
<li> Files ending with <em>extension1</em>, <em>extension2</em>, and so on, will be served
to clients with the <tt>Content-Type: <em>type</em></tt> header.
<li> Extensions must be listed <em>with</em> their initial dot. </li>
<li> Example: <tt>content-type text/html .html .htm</tt> means that files
ending in <tt>.html</tt> or <tt>.htm</tt> should be served as <tt>text/html</tt>.
<li> tipidee already comes with a
<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/tipidee/tree/src/config/defaults.c#n19">large
list</a> of default Content-Type mappings; this directive should only be necessary if you're
serving files with uncommon extensions or have specific needs. </li>
</ul>
<div id="custom-header">
<h3> The <tt>custom-header</tt> directive </h3>
</div>
<p>
<tt>custom-header</tt> is global directive, introduced by the
keyword <tt>custom-header</tt>. It allows
the user to define custom headers that are to be added to every response.
It takes a subcommand, that is used to define what should be done with
the header:
</p>
<p>
<code> custom-header add <em>name</em> <em>value</em> </code> <br>
<code> custom-header always <em>name</em> <em>value</em> </code> <br>
<code> custom-header remove <em>name</em> </code> <br>
<code> custom-header never <em>name</em> </code>
</p>
<ul>
<li> <tt>custom-header add</tt> tells tipidee to add a header named <em>name</em>
with the value <em>value</em> to all its answers. A CGI script can override <em>value</em>
by providing its own <em>name</em> header. </li>
<li> <tt>custom-header always</tt> is like <tt>custom-header add</tt>, except a CGI script
cannot override <em>value</em>, which will always be used. </li>
<li> <tt>custom-header remove</tt> tells tipidee to <em>not</em> provide a <em>name</em>
header. This is only useful for a few overridable headers that tipidee provides by default,
such as <tt>Content-Security-Policy</tt> or <tt>Referrer-Policy</tt>. If a CGI script
provides such a header, the CGI header will be used despite the directive. </li>
<li> <tt>custom-header never</tt> is like <tt>custom-header remove</tt>, except even a
CGI script cannot provide a <em>name</em> header, which will be stripped from its output. </li>
<li> Some headers cannot be customized. <a href="tipidee-config.html">tipidee-config</a>
will reject an attempt to add, or remove, a <tt>Connection</tt> header, for instance. </li>
</ul>
<div id="local">
<h3> Local directives </h3>
</div>
<p>
All the other directives are <em>local</em>: they only apply to the current <em>domain</em>.
Except for <tt>domain</tt>, they can only be used after a <tt>domain</tt> directive.
</p>
<div id="domain">
<h4> <tt>domain</tt> </h4>
</div>
<p>
<code> domain <em>domain</em> </code>
</p>
<ul>
<li> <tt>domain</tt> is a special directive in that it is stateful. Instead of
having a direct effect on the configuration, it merely defines the domain that
the next local directives will apply to. <tt>domain example.com</tt> means
that a subsequent <tt>cgi /cgi-bin/</tt> line will declare that a resource
under <tt>//example.com/cgi-bin/</tt> is a CGI script. </li>
<li> The current domain remains defined and active until the next
<tt>domain</tt> directive. </li>
<li> Global directives are unaffected by the current domain. It is good
practice to declare global directives <em>before</em> the first <tt>domain</tt>
line, but it is not mandatory. </li>
<li> If your resources are accessible via several URIs, the declared <tt>domain</tt>
should be the <em>canonical</em> one, i.e. the name of the <strong>real</strong>
directory hosting them, and not the symlinks. E.g. if you are serving files in
the real directory <tt>/home/www/docs/example.com</tt>, with <tt>example.com:80</tt>
and <tt>example.com:443</tt> being symlinks to <tt>example.com</tt>, then
<tt>domain example.com</tt> is the correct declaration for settings that will apply
to these files. And if you are hosting a different set of documents in the real
directory <tt>/home/www/docs/example.com:81</tt>, and <tt>example.com:444</tt> is
a symlink to <tt>example.com:81</tt>, then these will be affected by the settings
declared under <tt>domain example.com:81</tt>. </li>
<li> The point of all this is to make virtual hosting as flexible as possible,
allowing you to have different configurations for different virtual hosts —
including serving different sets of documents for the same host on different ports!)
— without needing to duplicate the configuration when you are serving the same
sets of documents over several ports, e.g. when you're serving both HTTP and HTTPS. </li>
<li> Complex configurations can benefit from the <tt>!include</tt> or
<tt>!includedir</tt> primitives, by putting the configuration related to one domain
in a dedicated file, and having the main <tt>/etc/tipidee.conf</tt> only declare
global configuration and include all the domain-specific files. </li>
</ul>
<div id="cgi">
<h4> <tt>cgi</tt> </h4>
</div>
<p>
<code> cgi <em>directory</em> </code> <br>
<code> cgi <em>file</em> </code>
</p>
<ul>
<li> The <tt>cgi <em>directory</em></tt> directive tells
<a href="tipideed.html">tipideed</a> that under the current domain,
all the files under <em>directory</em> (and its whole sub-hierarchy)
are CGI scripts. <em>directory</em> is absolute (it must start with
a slash, referring to the document root for the current domain), and
must end with a slash as well. </li>
<li> The <tt>cgi <em>file</em></tt> directive tells
<a href="tipideed.html">tipideed</a> that under the current domain,
<em>file</em> is a CGI script, regardless of its location.
<em>file</em> is absolute (it must start with
a slash, referring to the document root for the current domain), but
must not end with a slash. </li>
<li> A common use is: <tt>cgi /cgi-bin/</tt> </li>
<li> By default, no CGI directories or files are defined, so an
empty tipidee configuration will only serve static files. </li>
</ul>
<div id="noncgi">
<h4> <tt>noncgi</tt> </h4>
</div>
<p>
<code> noncgi <em>directory</em> </code> <br>
<code> noncgi <em>file</em> </code>
</p>
<ul>
<li> The <tt>noncgi <em>directory</em></tt> directive tells
<a href="tipideed.html">tipideed</a> that under the current domain,
all the files under <em>directory</em> (and its whole sub-hierarchy)
are <em>not</em> CGI scripts.
<li> The <tt>noncgi <em>file</em></tt> directive tells
<a href="tipideed.html">tipideed</a> that under the current domain,
<em>file</em> is <em>not</em> a CGI script, regardless of its location.
<li> This is a rare directive, only useful if for some reason you have
a static document under <tt>/cgi-bin</tt> or equivalent. </li>
</ul>
<div id="nph-prefix">
<h4> <tt>nph-prefix</tt> </h4>
</div>
<p>
<code> nph-prefix <em>prefix</em> </code>
</p>
<ul>
<li> This directive tells <a href="tipideed.html">tipideed</a> that
CGI scripts (recognized as such by a <tt>cgi</tt> directive) whose name
starts with <em>prefix</em> are
<a href="https://datatracker.ietf.org/doc/html/rfc3875#section-5">non-parsed header</a>
scripts. </li>
<li> Common usage is <tt>nph-prefix nph-</tt> — paired with <tt>cgi /cgi-bin/</tt>,
this means that under the current domain, scripts of the form
<tt>/cgi-bin/nph-foobar</tt> are NPH. </li>
</ul>
<div id="nph">
<h4> <tt>nph</tt> </h4>
</div>
<p>
<code> nph <em>directory</em> </code> <br>
<code> nph <em>file</em> </code>
</p>
<ul>
<li> This is an alternative way of specifying which scripts are
<a href="https://datatracker.ietf.org/doc/html/rfc3875#section-5">NPH</a>.
This directive says that CGI scripts under <em>directory</em> are NPH
(provided they're also recognized as CGI), and that <em>file</em> is NPH
(provided it's also recognized as CGI). </li>
<li> For instance, having both <tt>cgi /cgi-bin/</tt> and <tt>nph /cgi-bin/</tt>
means that <em>all</em> the CGI scripts under <tt>/cgi-bin</tt> are considered NPH. </li>
</ul>
<div id="nonnph">
<h4> <tt>nonnph</tt> </h4>
</div>
<p>
<code> nonnph <em>directory</em> </code> <br>
<code> nonnph <em>file</em> </code>
</p>
<ul>
<li> This is the opposite, saying that CGI scripts under <em>directory</em>,
or CGI script <em>file</em>, are <em>not</em> NPH. </li>
<li> This is a rare directive, only useful if the vast majority of your
scripts, but not all of them, are NPH. </li>
</ul>
<div id="basic-auth">
<h4> <tt>basic-auth</tt> </h4>
</div>
<p>
<code> basic-auth <em>directory</em> </code> <br>
<code> basic-auth <em>file</em> </code>
</p>
<ul>
<li> This directive tells <a href="tipideed.html">tipideed</a> that
file <em>file</em>, or all files under <em>directory</em>, are protected
by <a href="https://datatracker.ietf.org/doc/html/rfc7617">Basic HTTP
authentication</a>. </li>
<li> This feature is currently unimplemented, so
<a href="tipidee-config.html">tipidee-config</a> will print a warning if
it finds such a directive in your configuration file. </li>
<li> Implementation of this feature has been delayed because it needs an
additional database to store the <tt>resource:user:password</tt> tuples,
with more restricted permissions than <tt>/etc/tipidee.conf.cdb</tt>, since
passwords are confidential information. This is planned in a future version
of tipidee. And yes, existing web servers that make the administrator store
cleartext passwords in the generic configuration file are terrible. </li>
</ul>
<div id="no-auth">
<h4> <tt>no-auth</tt> </h4>
</div>
<p>
<code> no-auth <em>directory</em> </code> <br>
<code> no-auth <em>file</em> </code>
</p>
<ul>
<li> This is the opposite, saying that files under <em>directory</em>,
or specific file <em>file</em>, do <em>not</em> require authentication. </li>
<li> This is a rare directive, only useful if you have a whole directory
under <tt>basic-auth</tt> but want to carve exceptions. </li>
</ul>
<div id="file-type">
<h4> <tt>file-type</tt> </h4>
</div>
<p>
<code> file-type <em>directory</em> <em>type</em> </code> <br>
<code> file-type <em>file</em> </code> <em>type</em>
</p>
<ul>
<li> <tt>file-type</tt> is similar to <a href="#content-type"><tt>content-type</tt></a>,
but local. For files under <em>directory</em>, or for specific file <em>file</em>, it
overrides the default Content-Type associated with their extension, and gives them the
Content-Type <em>type</em> instead. </li>
<li> <tt>file-type /source/ text/plain</tt> will serve all files under the current
domain under the <tt>/source</tt> directory as <tt>text/plain</tt>. </li>
<li> <tt>file-type /source/file.html text/html</tt> will serve <tt>/source/file.html</tt>
under the current domain as <tt>text/html</tt>, even with the previous more generic
rule applying to <tt>/source</tt>. </li>
</ul>
<div id="redirect">
<h4> <tt>redirect</tt> </h4>
</div>
<p>
<code> redirect <em>resource</em> <em>rtype</em> <em>target</em> </code>
</p>
<ul>
<li> <em>resource</em> is the URI to redirect, relative to the current domain.
For instance, if the current domain is <tt>example.com</tt> and <em>resource</em>
is <tt>foobar.html</tt>, then a request for <tt>http://example.com/foobar.html</tt>
will be redirected to <em>target</em>. </li>
<li> <em>rtype</em> is the type of redirection. It is one of the following four numbers:
<ul>
<li> <a href="https://datatracker.ietf.org/doc/html/rfc9110#section-15.4.9"><tt>308</tt></a>: permanent redirection </li>
<li> <a href="https://datatracker.ietf.org/doc/html/rfc9110#section-15.4.8"><tt>307</tt></a>: temporary redirection </li>
<li> <a href="https://datatracker.ietf.org/doc/html/rfc9110#section-15.4.2"><tt>301</tt></a>: permanent redirection
while allowing the client to change the request method. You generally should not need this. </li>
<li> <a href="https://datatracker.ietf.org/doc/html/rfc9110#section-15.4.3"><tt>302</tt></a>: temporary redirection
while allowing the client to change the request method. You generally should not need this. </li>
</ul> </li>
<li> <em>target</em> is the target of the redirection. It must be a full URL starting
with <tt>http://</tt> or <tt>https://</tt>. (If you want local redirection under the
same virtual domain, this directive is not what you want: instead, you can make a
symbolic link in your filesystem.) </li>
<li> Unlike files or directories given as arguments in other local directives,
<em>resource</em> does not need to exist in the filesystem.
<a href="tipideed.html">tipideed</a> processes redirections <em>before</em> looking
up resources in the filesystem. This is more efficient, but comes with a caveat:
a file will only be served if there is no redirection directive for that resource,
so make sure to keep your configuration file up-to-date. </li>
<li> This also means that the "real directory" rule does not apply to redirections.
Instead, you can declare a redirection under the <tt>example.com:80</tt> domain, whether
or not <tt>/home/www/docs/example.com:80</tt> is a real directory; the redirection
will <em>only</em> apply to requests received on port 80 (and not, for instance, to
requests received on port 443). But if you declare a redirection under the
<tt>example.com</tt> domain, it will apply to requests received on <em>any</em> port. </li>
</ul>
<div id="custom-response">
<h4> <tt>custom-response</tt> </h4>
</div>
<p>
<code> custom-response <em>status</em> <em>file</em> </code>
</p>
<ul>
<li> <tt>custom-response</tt> allows you to customize the contents of HTTP error
responses for the current domain. </li>
<li> <em>status</em> is the 3-digit HTTP response code you want to specify a custom response for. </li>
<li> <em>file</em> is the file containing the body of the HTTP response that will be
sent to the client if <a href="tipideed.html">tipideed</a> finds that it must answer
with a <em>status</em> code.
<ul>
<li> <em>file</em> is used relative to tipideed's working directory (even if
it is given absolute). It does not have to be under the current domain's document root:
it is <strong>not a resource</strong>, and is not handled as such.
However, <em>file</em> cannot go up the filesystem hierarchy: it will always
be under tipideed's working directory. </li>
<li> The Content-Type for <em>file</em> is determined by its extension,
and mappings you add via <tt>content-type</tt> directives will work. However,
since <em>file</em> is not a resource, <tt>file-type</tt>
directives will not work, even if <em>file</em> is under the current virtual
domain's document root. Don't try to be smart with this. Just name your
custom files <tt>e404.html</tt> or something. </li>
</ul> </li>
<li> The instruction is only valid for <em>status</em> responses to requests
targetting the current domain. You can specify another <tt>custom-response</tt>,
or even the same one, after the next <tt>domain</tt> directive. </li>
<li> An example: <tt>custom-response 404 /errors/404.html</tt> under
a <tt>domain example.com</tt> line will mean that the <tt>errors/404.html</tt>
file will be served as the text/html body of any "404 Not Found" response
tipideed may send to requests addressed to <tt>example.com</tt>. The
<tt>errors</tt> subdirectory is at the same level as the <tt>example.com</tt>
subdirectory. </li>
<li> If tipideed cannot open <em>file</em>, it will log a warning message
and answer the client with a basic builtin response. </li>
<li> Not every HTTP status code is used by tipideed. Nothing will happen
if you define custom responses for codes that aren't used. </li>
</ul>
</body>
</html>
|
