-
Notifications
You must be signed in to change notification settings - Fork 267
/
yaws.conf.5
1781 lines (1461 loc) · 61.1 KB
/
yaws.conf.5
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
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH YAWS.CONF "5" "" "" "User Commands" -*- nroff -*-
.SH NAME
/etc/yaws/yaws.conf \- Configuration file for the Yaws web server
.SH DESCRIPTION
.\" Add any additional description here
.PP
Yaws is fast lightweight web server. It reads a configuration file called
yaws.conf to control its operations. The configuration contains two distinct
parts: a global part which affects all the virtual hosts and a server part where
options for each virtual host is supplied.
.SH GLOBAL PART
.TP
\fBlogdir = [+]Directory\fR
All Yaws logs will be written to files in this directory. If specified with
\fB+\fR, Yaws will attempt to create the directory if it does not exist. There
are several different log files written by Yaws:
\fBreport.log\fR - this is a text file that contains all error logger printouts
from Yaws.
\fB<Host>.access\fR - for each virtual host served by Yaws, a file <Host>.access
will be written that contains an access log in NCSA combined/XLF/ELF log format. (See
http://www.w3.org/TR/WD-logfile.html for more details on Extended Log File
Format.)
\fB<Host>.auth\fR - for each virtual host served by Yaws, a file <Host>.auth
will be written which contains all http auth related messages.
\fBtrace_<YYYYMMDD_hhmmss>\fR - Trace files are written in this subdirectory,
suffixed by the creation date.
.RS 12
\fBtrace.<Pid>.http\fR - this file contains the HTTP trace if that is enabled,
where <Pid> is the process id handling the TCP connection.
\fBtrace.<Pid>.traffic\fR - this file contains the traffic trace if that is
enabled, where <Pid> is the process id handling the TCP connection.
.RE
.IP
Note that <Host>.access and <Host>.auth files will be used only if the directive
\fBlogger_mod\fR is not set or set to yaws_log. The default value for logdir is
\fI"."\fR
.TP
\fBebin_dir = Directory\fR
This directive adds Directory to the Erlang search path. It is possible to have
several of these commands in the configuration file. The default value is
\fI"yaws_dir"/examples/ebin\fR
.TP
\fBsrc_dir = Directory\fR
This directive defines a Directory as a \fIsource\fR directory. Yaws will
compile all erlang modules found in this directory and all its
subdirectories. The compilation occurs when the configuration is loaded or
reloaded. The \fBinclude_dir\fR directives are used to search for includes
files. Multiple \fBsrc_dir\fR directives may be used. There is no such directory
configured by default.
.TP
\fBid = String\fR
It is possible to run multiple Yaws servers on the same machine. We use the id of a
Yaws server to control it using the different control commands such as:
.nf
# /usr/local/bin/yaws --id foobar --stop
.fi
To stop the Yaws server with id "foobar". Each Yaws server will write its
internal data into a file called $HOME/.yaws/yaws/ID where ID is the identity
of the server. Yaws also creates a file called $HOME/.yaws/yaws/ID/CTL
which contains the port number where the server is listening for control
commands. The default id is \fI"default"\fR.
.TP
\fBserver_signature = String\fR
This directive sets the "Server: " output header to the custom value. The
default value is \fI"yaws/%VSN%, Yet Another Web Server"\fR.
.TP
\fBinclude_dir = Directory\fR
This directive adds Directory to the path of directories where the Erlang
compiler searches for include files. We need to use this if we want to
include .hrl files in our Yaws Erlang code. It is possible to have several of
these commands in the configuration file. The default value is
\fI"yaws_dir"/examples/include\fR.
.TP
\fBmax_num_cached_files = Integer\fR
Yaws will cache small files such as commonly accessed GIF images in RAM. This
directive sets a maximum number on the number of cached files. The default
value is \fI400\fR.
.TP
\fBmax_num_cached_bytes = Integer\fR
This directive controls the total amount of RAM which can maximally be used for
cached RAM files. The default value is \fI1000000\fR, 1 megabyte.
.TP
\fBmax_size_cached_file = Integer\fR
This directive sets a maximum size on the files that are RAM cached by Yaws.
The default value is \fI8000\fR, 8 kBytes.
.TP
\fBcache_refresh_secs = Integer\fR
The RAM cache is used to serve pages that sit in the cache. An entry sits in
cache at most cache_refresh_secs number of seconds. The default is
\fI30\fR. This means that when the content is updated under the docroot, that
change doesn't show until 30 seconds have passed. While developing a Yaws site,
it may be convenient to set this value to 0. If the debug flag (-d) is passed to
the Yaws start script, this value is automatically set to 0.
.TP
\fBtrace = false | traffic | http\fR
This enables traffic or http tracing. Tracing is also possible to enable with a
command line flag to Yaws. Default is \fIfalse\fR.
.TP
\fBauth_log = true | false\fR
\fBDeprecated and ignored. Now, this target must be set in server part.\fR
.TP
\fBmax_connections = nolimit | Integer\fR
Set this value to control the maximum number of connections from HTTP clients
into the server. This is implemented by closing the last socket if the limit
threshold is reached.
.TP
\fBkeepalive_maxuses = nolimit | Integer\fR
Normally, Yaws does not restrict the number of times a connection is kept alive
using keepalive. Setting this parameter to an integer X will ensure that
connections are closed once they have been used X times. This can be a useful
to guard against long running connections collecting too much garbage in the
Erlang VM.
.TP
\fBprocess_options = undefined | Proplist\fR
Set process spawn options for client acceptor processes. Options must be
specified as a quoted string of either the atom \fIundefined\fR or as a proplist
of valid process options. The supported options are \fIfullsweep_after\fR,
\fImin_heap_size\fR, and \fImin_bin_vheap_size\fR, each taking an associated
integer value. Other process options are ignored. The proplist may also be
empty. See \fBerlang:spawn_opt/4\fR for details on these options.
.TP
\fBlarge_file_chunk_size = Integer\fR
Set the chunk size used by Yaws to send large files. The default value
is \fI10240\fR.
.TP
\fBlarge_file_sendfile = erlang | disable\fR
Set the version of sendfile method to use to send large files:
\fBerlang\fR - use \fIfile:sendfile/5\fR.
\fBdisable\fR - use \fIgen_tcp:send/2\fR.
The default value is \fIerlang\fR.
.TP
\fBacceptor_pool_size = Integer\fR
Set the size of the pool of cached acceptor processes. The specified value must
be greater than or equal to 0. The default value is \fI8\fR. Specifying a value
of 0 effectively disables the process pool.
.TP
\fBlog_wrap_size = Integer\fR
The logs written by Yaws are all wrap logs, the default value at the size where
they wrap around and the original gets renamed to File.old is \fI1000000\fR, 1
megabyte. This value can be changed.
.br
If we set the value to 0 the logs will never wrap. If we want to use Yaws in
combination with a more traditional log wrapper such as logrotate, set the size
to 0 and Yaws will reopen the logfiles once they have be renamed/removed.
.TP
\fBlog_resolve_hostname = true | false\fR
By default the client host IP is not resolved in the access logs.
.TP
\fBfail_on_bind_err = true | false\fR
Fail completely or not if Yaws fails to bind a listen socket Default is
\fItrue\fR.
.TP
\fBenable_soap = true | false\fR
If true, a soap server will be started at startup of Yaws. Default is
\fIfalse\fR.
.TP
\fBsoap_srv_mods = ListOfModuleSetting\fR
If enable_soap is true, a startup Yaws will invoke \fIyaws_soap_srv:setup()\fR
to setup modules set here. ModuleSetting is either a triad like \fI<Mod,
HandlerFunc, WsdlFile>\fR or a quadruple form like \fI<Mod, HandlerFunc,
WsdlFile, Prefix>\fR which specifies the \fIprefix\fR. A \fIprefix\fR will be
used as argument of \fIyaws_soap_lib:initModel()\fR and then be used as a XML
namespace prefix. Note, the \fIWsdlFile\fR here should be an absolute-path file
in local file systems.
For example, we can specify
.nf
soap_srv_mods=<Mod1, Handler, Wsdl1> <Mod2, Handler, Wsdl2, Prefix> ...
.fi
.TP
\fBphp_exe_path = Path\fR
\fBthis target is deprecated and useless. use 'php_handler' target in server
part instead.\fR
.br
The name of (and possibly path to) the php executable used to interpret php
scripts (if allowed). Default is \fIphp_exe_path = php-cgi\fR.
.TP
\fBcopy_error_log = true | false\fR
Enable or disable copying of the error log. When we run in embedded mode, there
may very well be some other systems process that is responsible for writing the
errorlog to a file whereas when we run in normal standalone mode, we typically
want the Erlang errorlog written to a report.log file. Default value is
\fItrue\fR.
.TP
\fBysession_mod = Module\fR
Allows specifying a different Yaws session storage mechanism instead of an ETS
table. One of the drawbacks of the default yaws_session_server implementation is
that server side cookies are lost when the server restarts. Specifying a
different module here will pass all write/read operations to this module (it
must implement appropriate callbacks).
.TP
\fBysession_cookiegen = Module\fR
Allows specifying a different Yaws session cookie generator than the
built-in default. \fIModule\fR is expected to provide a \fInew_cookie/0\fR
function that returns a session cookie in the form of a list. Such a cookie
generator module must be careful to return a unique cookie each time it's
called.
.TP
\fBysession_idle_timeout = Integer\fR
Controls Yaws session idle cleanup. If a server has been idle for
\fIysession_idle_timeout\fR milliseconds, check all Yaws sessions and
remove any that have timed out. The default \fIysession_idle_timeout\fR
value is 2*60*1000 (2 minutes).
.TP
\fBysession_long_timeout = Integer\fR
Controls Yaws session periodic cleanup. Every \fIysession_long_timeout\fR
milliseconds, check all Yaws sessions and remove any that have timed
out. The default \fIysession_long_timeout\fR value is 60*60*1000 (1 hour).
.TP
\fBrunmod = ModuleName\fR
At startup Yaws will invoke \fIModuleName:start()\fR in a separate process. It
is possible to have several runmods. This is useful if we want to reuse the
Yaws startup shell script for our own application.
.TP
\fBpick_first_virthost_on_nomatch = true | false\fR
When Yaws gets a request, it extracts the Host header from the client
request to choose a virtual server amongst all servers with the same
IP/Port pair. This configuration parameter decides whether Yaws should
pick the first server (as defined in the yaws.conf file) if no name match
or not. If this is false and no Host header is present in the request, Yaws
returns a 400 Bad Request as required by the HTTP standard. In real live
hosting scenarios we typically want this to be false, whereas in
testing/development scenarios it may be convenient to set it to
true. Default is \fItrue\fR.
.TP
\fBkeepalive_timeout = TimeInMilliseconds | infinity\fR
If the HTTP session will be kept alive (i.e., not immediately closed) it will
close after keepalive_timeout milliseconds unless a new request is received in
that time. The default value is \fI30000\fR. The value \fIinfinity\fR is legal
but not recommended.
.TP
\fBsubconfig = File\fR
Load specified config file. Absolute paths or relative ones to the configuration
location are allowed. Unix-style wildcard strings can be used to include several
files at once. See \fIfilelib:wildcard/1\fR for details. Hidden files, starting
by a dot, will be ignored. For example:
.nf
subconfig = /etc/yaws/global.conf
subconfig = /etc/yaws/vhosts/*.conf
.fi
Or, relatively to the configuration location:
.nf
subconfig = global.conf
subconfig = vhosts/*.conf
.fi
.TP
\fBsubconfigdir = Directory\fR
Load all config files found in the specified directory. The given Directory can
be an absolute path or relative to the configuration location. Hidden files,
starting by a dot, will be ignored.
.TP
\fBx_forwarded_for_log_proxy_whitelist = ListOfUpstreamProxyServerIps\fR
\fBthis target is deprecated and will be ignored.\fR
.TP
\fBdefault_type = MimeType\fR
Defines the default MIME type to be used where Yaws cannot determine it by its
MIME types mappings. Default is \fItext/plain\fR.
.TP
\fBdefault_charset = Charset\fR
Defines the default charset to be added when a response content-type is
\fItext/*\fR. By default, no charset is added.
.TP
\fBmime_types_file = File\fR
Overrides the default \fImime.types\fR file included with Yaws. This file must
use the following format:
.nf
# Lines beginning with a '#' or a whitespace are ignored
# blank lines are also ignored
<MIME type> <space separated file extensions>
.fi
The default file is located at \fI${PREFIX}/lib/yaws/priv/mime.types\fR. You
should not edit this file because it may be replaced when you upgrade your
server.
.TP
\fBadd_types = ListOfTypes\fR
Specifies one or more mappings between MIME types and file extensions. More than
one extension can be assigned to a MIME type. \fIListOfTypes\fR is defined as
follows:
.nf
add_types = <MimeType1, Ext> <MimeType2, Ext1 Ext2 ...> ...
.fi
The mappings defined using this directive will overload all other
definitions. If a file extension is defined several times, only the last one is
kept. Multiple \fBadd_types\fR directives may be used.
.TP
\fBadd_charsets = ListOfCharsets\fR
Specifies one or more mappings between charsets and file extensions. More than
one extension can be assigned to a charset. \fIListOfCharsets\fR is defined as
follows:
.nf
add_charsets = <Charset1, Ext> <Charset2, Ext1 Ext2 ...> ...
.fi
The mappings defined using this directive will overload all other
definitions. If a file extension is defined several times, only the last one is
kept. Multiple \fBadd_charsets\fR directives may be used.
.TP
\fBsni = disable | enable | strict\fR
Enables or disables the TLS SNI (Server Name Indication) support.
When disabled (or not supported), all virtual servers in the same group (same
IP/Port) must share the same SSL configuration, especially the same SSL
certificate. Only the HTTP Host header will be considered to find the right
virtual server.
When enabled, SSL configuration can be different from one virtual server to
another; each one can have its own SSL certificate. In this case, if a client
provides a SNI hostname, it will be used to find the right virtual server. To
accept the SNI information from the client, the first virtual server -- the
default one, see \fBpick_first_virthost_on_nomatch\fR -- \fBmust\fR include TLS as
a permitted protocol.
If the \fBsni\fR directive is set to \fIenable\fR, non-SNI clients are allowed.
For such clients, virtual servers are selected as if Yaws did not have SNI
support. If it is set to \fIstrict\fR, SNI hostname is mandatory to access a SSL
virtual server. But in all cases, when SNI support is enabled, if a client
provides a SNI hostname, it \fBmust\fR match the HTTP Host header (which is
mandatory too). Note that the first virtual server (the default one) will be
used for any request where the provided SNI hostname doesn't match any of
virtual server names. So, it is important that the first virtual server have the
most restrictive access control, otherwise clients can access restricted
resources by sending a request for any unknown hostname. (This isn't actually
any different from using virtual servers without SNI support.) If you're using
self-signed certificates, be sure to also set the \fBdepth\fR configuration
variable to 0 to avoid following certificate chains.
The \fBsni\fR directive is a global one, so if you set it to \fIstrict\fR,
non-SNI clients will be refused for \fBall\fR SSL groups. See \fBrequire_sni\fR
directive from the server part to mitigate this requirement.
Default is \fIdisable\fR.
.SH SERVER PART
Yaws can virthost several web servers on the same IP address as well as several
web servers on different IP addresses. This includes SSL servers.
.PP
Each virtual host is defined within a matching pair of \fB<server ServerName>\fR
and \fB</server>\fR. The ServerName will be the name of the webserver.
.PP
The following directives are allowed inside a server definition.
.TP
\fBport = Port\fR
This makes the server listen on Port. Default is \fI8000\fR.
.TP
\fBlisten = IpAddress\fR
This makes the server listen on IpAddress. When virthosting several servers on
the same ip/port address, if the browser doesn't send a Host: field, Yaws will
pick the \fIfirst\fR server specified in the config file. If the specified IP
address is 0.0.0.0 Yaws will listen on all local IP addresses on the specified
port. Default is \fI127.0.0.1\fR. Multiple \fBlisten\fR directives may be used to
specify several addresses to listen on.
.TP
\fBlisten_backlog = Integer\fR
This sets the TCP listen backlog for the server to define the maximum length the
queue of pending connections may grow to. The default is 1024.
.TP
\fB<listen_opts> ... </listen_opts>\fR
Defines extra options to be set on the listen socket and, by inheritance, on
accepted sockets. See \fIinet:setopts/2\fR for details. Supported options are:
\fBbuffer = Integer\fR (default: same as \fIinet:setopts/2\fR)
\fBdelay_send = true | false \fR (default: same as \fIinet:setopts/2\fR)
\fBlinger = Integer | false \fR (default: same as \fIinet:setopts/2\fR)
\fBnodelay = true | false \fR (default: same as \fIinet:setopts/2\fR)
\fBpriority = Integer\fR (default: same as \fIinet:setopts/2\fR)
\fBsndbuf = Integer\fR (default: same as \fIinet:setopts/2\fR)
\fBrecbuf = Integer\fR (default: same as \fIinet:setopts/2\fR)
\fBsend_timeout = Integer | infinity\fR (default: same as \fIinet:setopts/2\fR)
\fBsend_timeout_close = true | false \fR (default: same as \fIinet:setopts/2\fR)
.RE
.TP
\fBserver_signature = String\fR
This directive sets the "Server: " output header to the custom value and
overloads the global one for this virtual server.
.TP
\fBsubconfig = File\fR
Same as \fBsubconfig\fR directive of the global part, but here files should only
contain directives allowed in the server part.
.TP
\fBsubconfigdir = Directory\fR
Same as \fBsubconfigdir\fR directive of the global part, but here files should only
contain directives allowed in server part.
.TP
\fBrhost = Host[:Port]\fR
This forces all local redirects issued by the server to go to Host. This is
useful when Yaws listens to a port which is different from the port that the
user connects to. For example, running Yaws as a non-privileged user makes it
impossible to listen to port 80, since that port can only be opened by a
privileged user. Instead Yaws listens to a high port number port, 8000, and
iptables are used to redirect traffic to port 80 to port 8000 (most NAT:ing
firewalls will also do this for you).
.TP
\fBrmethod = http | https\fR
This forces all local redirects issued by the server to use this method. This is
useful when an SSL off-loader, or stunnel, is used in front of Yaws.
.TP
\fBauth_log = true | false\fR
Enable or disable the auth log for this virtual server. Default is \fItrue\fR.
.TP
\fBaccess_log = true | false\fR
Setting this directive to false turns off traffic logging for this virtual
server. The default value is \fItrue\fR.
.TP
\fBlogger_mod = Module\fR
It is possible to set a special module that handles access and auth logging. The
default is to log all web server traffic to <Host>.access and <Host>.auth files
in the configured or default logdir.
.br
This module must implement the behaviour \fIyaws_logger\fR. Default value is
\fIyaws_log\fR.
The following functions should be exported:
\fBModule:open_log(ServerName, Type, LogDir)\fR
.RS 12
When Yaws is started, this function is called for this virtual server. If the
initialization is successful, the function must return \fI{true,State}\fR and if
an error occurred, it must return \fIfalse\fR.
.RE
.IP
\fBModule:close_log(ServerName, Type, State)\fR
.RS 12
This function is called for this virtual server when Yaws is stopped.
.RE
.IP
\fBModule:wrap_log(ServerName, Type, State, LogWrapSize)\fR
.RS 12
This function is used to rotate log files. It is regularly called by Yaws and
must return the possibly updated internal NewState.
.RE
.IP
\fBModule:write_log(ServerName, Type, State, Infos)\fR
.RS 12
When it needs to log a message, Yaws will call this function. The parameter
Infos is \fI{Ip,Req,InHdrs,OutHdrs,Time}\fR for an access log and
\fI{Ip,Path,Item}\fR for an auth log, where:
\fBIp\fR - IP address of the accessing client (as a tuple).
\fBReq\fR - the HTTP method, URI path, and HTTP version of the request (as a
#http_request{} record).
\fBInHdrs\fR - the HTTP headers which were received from the WWW client (as a
#headers{} record).
\fBOutHdrs\fR - the HTTP headers sent to the WWW client (as a #outh{} record)
\fBPath\fR - the URI path of the request (as a string).
\fBItem\fR - the result of an authentication request. May be \fI{ok,User}\fR,
\fI403\fR or \fI{401,Realm}\fR.
\fBTime\fR - The time taken to serve the request, in microseconds.
.RE
.IP
For all of these callbacks, \fBServerName\fR is the virtual server's name,
\fIType\fR is the atom access or auth and \fIState\fR is the internal state of
the logger.
.TP
\fBshaper = Module\fR
Defines a module to control access to this virtual server. Access can be
controlled based on the IP address of the client. It is also possible to
throttle HTTP requests based on the client's download rate. This module must
implement the behaviour \fIyaws_shaper\fR.
There is no such module configured by default.
.TP
\fBdir_listings = true | true_nozip | false\fR
Setting this directive to false disallows the automatic dir listing feature of
Yaws. A status code 403 Forbidden will be sent. Set to true_nozip to avoid the
auto-generated all.zip entries. Default is \fIfalse\fR.
.TP
\fBextra_cgi_vars = .....\fR
Add additional CGI or FastCGI variables. For example:
.nf
<extra_cgi_vars dir='/path/to/some/scripts'>
var = val
\&...
</extra_cgi_vars>
.fi
.TP
\fBstatistics = true | false\fR
Turns on/off statistics gathering for a virtual server. Default is \fIfalse\fR.
.TP
\fBfcgi_app_server = Host:Port\fR
The hostname and TCP port number of a FastCGI application server.
To specify an IPv6 address, put it inside square brackets (ex:
"[::1]:9000"). The TCP port number is not optional. There is no default
value.
.TP
\fBfcgi_trace_protocol = true | false\fR
Enable or disable tracing of FastCGI protocol messages as info log
messages. Disabled by default.
.TP
\fBfcgi_log_app_error = true | false\fR
Enable or disable logging of application error messages (output to stderr and
non-zero exit value). Disabled by default.
.TP
\fBdeflate = true | false\fR
Turns on or off deflate compression for a server. Default is \fIfalse\fR.
.TP
\fB<deflate> ... </deflate>\fR
This begins and ends the deflate compression configuration for this server. The
following items are allowed within a matching pair of <deflate> and </deflate>
delimiters.
\fBmin_compress_size = nolimit | Integer\fR
.RS 12
Defines the smallest response size that will be compressed. If nolimit is not
used, the specified value must be strictly positive. The default value is
\fInolimit\fR.
.RE
.IP
\fBcompression_level = none | default | best_compression | best_speed | 0..9\fR
.RS 12
Defines the compression level to be used. 0 (\fInone\fR), gives no
compression at all, 1 (\fIbest_speed\fR) gives best speed and 9
(\fIbest_compression\fR) gives best compression. The default value is
\fIdefault\fR.
.RE
.IP
\fBwindow_size = 9..15\fR
.RS 12
Specifies the zlib compression window size. It should be in the range 9 through
15. Larger values of this parameter result in better compression at the expense
of memory usage. The default value is \fI15\fR.
.RE
.IP
\fBmem_level = 1..9\fR
.RS 12
Specifies how much memory should be allocated for the internal compression
state. \fImem_level=1\fR uses minimum memory but is slow and reduces compression
ratio; \fImem_level=9\fR uses maximum memory for optimal speed. The default
value is \fI8\fR.
.RE
.IP
\fBstrategy = default | filtered | huffman_only\fR
.RS 12
This parameter is used to tune the compression algorithm. See \fBzlib(3erl)\fR
for more details on the \fIstrategy\fR parameter. The default value is
\fIdefault\fR.
.RE
.IP
\fBuse_gzip_static = true | false\fR
.RS 12
If true, Yaws will try to serve precompressed versions of static files. It will
look for precompressed files in the same location as original files that end in
".gz". Only files that do not fit in the cache are concerned. The default value
is \fIfalse\fR.
.RE
.IP
\fBmime_types = ListOfTypes | defaults | all\fR
.RS 12
Restricts the deflate compression to particular MIME types. The special value
\fIall\fR enable it for all types (It is a synonym of `*/*'). MIME types into
\fIListOfTypes\fR must have the form `type/subtype' or `type/*' (indicating all
subtypes of that type). Here is an example:
.nf
mime_types = default image/*
mime_types = application/xml application/xhtml+xml application/rss+xml
.fi
By default, the following MIME types are compressed (if
\fBdeflate\fR is set to true): \fItext/*, application/rtf, application/msword,
application/pdf, application/x-dvi, application/javascript\fR. Multiple
\fBmime_types\fR directives can be used.
.RE
.TP
\fBdocroot = Directory ...\fR
This makes the server serve all its content from Directory.
.br
It is possible to pass a space-separated list of directories as docroot. If this
is the case, the various directories will be searched in order for the requested
file. This also works with the ssi and yssi constructs where the full list of
directories will be searched for files to ssi/yssi include. Multiple docroot
directives can be used. You need at least one valid docroot, invalid docroots
are skipped with their associated auth structures.
.TP
\fBauth_skip_docroot = true | false\fR
If true, the docroot will not be searched for \fI.yaws_auth\fR files. This is
useful when the docroot is quite large and the time to search it is prohibitive
when Yaws starts up. Defaults to \fIfalse\fR.
.TP
\fBpartial_post_size = Integer | nolimit\fR
When a Yaws file receives large POSTs, the amount of data received in each chunk
is determined by this parameter. The default value is \fI10240\fR. Setting
it to nolimit is potentially dangerous.
.TP
\fBdav = true | false\fR
Turns on the DAV protocol for this server. The dav support in Yaws is highly
limited. If dav is turned on, .yaws processing of .yaws pages is turned
off. Default is \fIfalse\fR. The socket read timeout is supplied by the
keepalive_timeout setting. If the read is not done within the timeout, the POST
will fail.
.TP
\fBtilde_expand = true|false\fR
If this value is set to false Yaws will never do tilde expansion. The default is
\fIfalse\fR. tilde_expansion is the mechanism whereby a URL on the form
http://www.foo.com/~username is changed into a request where the docroot for
that particular request is set to the directory ~username/public_html/.
.TP
\fBallowed_scripts = ListOfSuffixes\fR
The allowed script types for this server. Recognized are `yaws', `cgi', `fcgi',
`php'. Default is \fIallowed_scripts = yaws php cgi fcgi\fR.
Note: for fcgi scripts, the FastCGI application server is only called if a local
file with the .fcgi extension exists. However, the contents of the local .fcgi
file are ignored.
.TP
\fBtilde_allowed_scripts = ListOfSuffixes\fR
The allowed script types for this server when executing files in a users
public_html folder Recognized are `yaws', `cgi', `fcgi', `php'. Default is
\fItilde_allowed_scripts =\fR i.e. empty
.TP
\fBindex_files = ListOfResources\fR
This directive sets the list of resources to look for, when a directory is
requested by the client. If the last entry begins with a `/', and none of the
earlier resources are found, Yaws will perform a redirect to this uri.
Default is \fIindex_files = index.yaws index.html index.php\fR.
.TP
\fBappmods = ListOfModuleNames\fR
If any of the names in ListOfModuleNames appear as components in the path for a
request, the path request parsing will terminate and that module will be
called. There is also an alternate syntax for specifying the appmods if we don't
want our internal erlang module names to be exposed in the URL paths. We can
specify
.nf
appmods = <Path1, Module1> <Path2, Modules2> ...
.fi
Assume for example that we have the URL
http://www.example.org/myapp/foo/bar/baz?user=joe while we have the module foo
defined as an appmod, the function foo:out(Arg) will be invoked instead of
searching the filesystems below the point foo.
.br
The Arg argument will have the missing path part supplied in its appmoddata
field.
It is also possible to exclude certain directories from appmod processing. This
is particulaly interesting for '/' appmods. Here is an example:
.nf
appmods = </, myapp exclude_paths icons js top/static>
.fi
The above configuration will invoke the 'myapp' erlang module on everything
except any file found in directories 'icons', 'js' and 'top/static' relative to
the docroot.
.TP
\fBdispatchmod = DispatchModule\fR
Set \fIDispatchModule\fR as a server-specific request dispatching
module. Yaws expects \fIDispatchModule\fR to export a \fIdispatch/1\fR
function. When it receives a request, Yaws passes an \fI#arg{}\fR record to
the dispatch module's \fIdispatch/1\fR function, which returns one of the
following atom results:
.RS 12
\fBdone\fR - this indicates the dispatch module handled the request itself
and already sent the response, and Yaws should resume watching for new
requests on the connection
\fBclosed\fR - same as \fIdone\fR but the \fIDispatchModule\fR also closed
the connection
\fBcontinue\fR - the dispatch module has decided not to handle the request,
and instead wants Yaws to perform its regular request dispatching
.RE
.IP
Note that when \fIDispatchModule\fR handles a request itself, Yaws does not
support tracing, increment statistics counters or allow traffic shaping for
that request. It does however still keep track of maximum keepalive uses on
the connection.
.TP
\fBerrormod_404 = Module\fR
It is possible to set a special module that handles 404 Not Found messages. The
function \fIModule:out404(Arg, GC, SC)\fR will be invoked. The arguments are
.RS 12
\fBArg\fR - a #arg{} record
\fBGC\fR - a #gconf{} record (defined in yaws.hrl)
\fBSC\fR - a #sconf{} record (defined in yaws.hrl)
.RE
.IP
The function can and must do the same things that a normal \fIout/1\fR does.
.TP
\fBerrormod_401 = Module\fR
It is possible to set a special module that handles 401 Unauthorized
messages. This can for example be used to display a login page instead. The
function \fIModule:out401(Arg, Auth, Realm)\fR will be invoked. The arguments
are
.RS 12
\fBArg\fR - a #arg{} record
\fBAuth\fR - a #auth{} record
\fBRealm\fR - a string
.RE
.IP
The function can and must do the same things that a normal \fIout/1\fR does.
.TP
\fBerrormod_crash = Module\fR
It is possible to set a special module that handles the HTML generation of
server crash messages. The default is to display the entire formatted crash
message in the browser. This is good for debugging but not in production.
.br
The function \fIModule:crashmsg(Arg, SC, Str)\fR will be called. The \fIStr\fR
is the real crash message formatted as a string.
.br
The function must return, \fI{content,MimeType,Cont}\fR or \fI{html, Str}\fR or
\fI{ehtml, Term}\fR. That data will be shipped to the client.
.TP
\fBexpires = ListOfExpires\fR
Controls the setting of the \fIExpires\fR HTTP header and the \fImax-age\fR
directive of the \fICache-Control\fR HTTP header in server responses for
specific MIME types. The expiration date can be set as relative to either the
time the source file was last modified; as the time of the client access; or as
always in order to empty the cache altogether. ListOfExpires is defined as
follows:
.nf
expires = <MimeType1, access+Seconds> <MimeType2, modify+Seconds> <MimeType3, always> ...
.fi
A MimeType can also have a wildcard as subtype or both as subtype and type,
like type/* or */*.
These HTTP headers are an instruction to the client about the document's
validity and persistence. If cached, the document may be fetched from the cache
rather than from the source until this time has passed. After that, the cache
copy is considered "expired" and invalid, and a new copy must be obtained from
the source. Here is an example:
.nf
expires = <image/gif, access+2592000> <image/png, access+2592000>
expires = <image/jpeg, access+2592000> <text/css, access+2592000>
expires = <text/*, always>
.fi
and here is another:
.nf
expires = <*/*, always>
.fi
.TP
\fBarg_rewrite_mod = Module\fR
It is possible to install a module that rewrites all the Arg #arg{} records
at an early stage in the Yaws server. This can be used to do various
things such as checking a cookie, rewriting paths etc. An arg_rewrite_mod
must export an \fIarg_rewrite/1\fR function taking and returning an #arg{}
record. If the function wants to return a response, it must set the
#arg.state field of its return value to an instance of the
#rewrite_response{} record.
The module \fIyaws_vdir\fR can be used in case you want to serve static content
that is not located in your docroot. See the example at the bottom of this man
page for how to use the \fIopaque\fR + \fIvdir\fR elements to instruct the
\fIyaws_vdir\fR module what paths to rewrite.
.TP
\fBstart_mod = Module\fR
Defines a user provided callback module. At startup of the server,
Module:start/1 will be called. The #sconf{} record (defined in yaws.hrl) will
be used as the input argument. This makes it possible for a user application to
synchronize the startup with the Yaws server as well as getting hold of user
specific configuration data, see the explanation for the <opaque> context.
.TP
\fBrevproxy = Prefix Url [intercept_mod Module]\fR
Make Yaws a reverse proxy. \fIPrefix\fR is a path inside our own docroot
and \fIUrl\fB argument is a URL pointing to a website we want to "mount"
under the \fIPrefix\fR path. This example:
.nf
revproxy = /tmp/foo http://www.example.org
.fi
makes the \fIexample\fR website appear under \fI/tmp/foo\fR.
It is possible to have multiple reverse proxies inside the same server.
You can optionally configure an interception module for each reverse proxy,
allowing your application to examine and modify requests and HTTP headers
as they pass through the proxy from client to backend server and also
examine and modify responses and HTTP headers as they return from the
backend server through the proxy to the client.
You specify an interception module by including the optional
\fIintercept_mod\fR keyword followed by \fIModule\fR, which should be the
name of your interception module.
An interception module is expected to export two functions:
\fIrewrite_request/2\fR and \fIrewrite_response/2\fR. The two arguments
passed to \fIrewrite_request/2\fR function are a \fI#http_request{}\fR record
and a \fI#headers{}\fR record, whereas \fIrewrite_response/2\fR function
takes a \fI#http_response{}\fR record and also a \fI#headers{}\fR record. You
can find definitions for these record types in the \fIyaws_api.hrl\fR
header file. Each function can examine each record instance and can either
return each original instance or can return a modified copy of each
instance in its response. The \fIrewrite_request/2\fR function should
return a tuple of the following form:
.nf
\fI{ok, #http_request{}, #headers{}}\fR
.fi
and the \fIrewrite_response/2\fR function should similarly return a tuple
of the following form:
.nf
\fI{ok, #http_response{}, #headers{}}\fR
.fi
A \fI#headers{}\fR record can easily be manipulated in an interceptor using
the functions listed below:
.nf
\fIyaws_api:set_header/2\fR, \fIyaws_api:set_header/3\fR
\fIyaws_api:get_header/2\fR, \fIyaws_api:get_header/3\fR
\fIyaws_api:delete_header/2\fR
.fi
Any failures in your interception module's functions will result in HTTP
status code 500, indicating an internal server error.
.TP
\fBfwdproxy = true|false\fR
Make Yaws a forward proxy. By enabling this option you can use Yaws as a proxy
for outgoing web traffic, typically by configuring the proxy settings in a
web-browser to explicitly target Yaws as its proxy server.
.TP
\fBservername = Name\fR
If we're virthosting several servers and want to force a server to match
specific Host: headers we can do this with the "servername" directive. This name
doesn't necessarily have to be the same as the the name inside <server Name> in
certain NAT scenarios. Rarely used feature.
.TP
\fBserveralias = ListOfNames\fR
This directive sets the alternate names for a virtual host. A server alias may
contain wildcards:
.RS 12
'*' matches any sequence of zero or more characters
'?' matches one character unless that character is a period ('.')
.RE
.IP
Multiple \fBserveralias\fR directives may be used. Here is an example:
.nf
<server server.domain.com>
serveralias = server server2.domain.com server2
serveralias = *.server.domain.com *.server?.domain.com
...
</server>
.fi
.TP
\fBphp_handler = <Type, Spec>\fR
Set handler to interpret .php files. It can be one of the following definitions:
\fBphp_handler = <cgi, Filename>\fR - The name of (and possibly path to) the php
executable used to interpret php scripts (if allowed).
\fBphp_handler = <fcgi, Host:Port>\fR - Use the specified fastcgi server to
interpret .php files (if allowed).
.RS 12
Yaws does not start the PHP interpreter in fastcgi mode for you. To run PHP in