1YAWS.CONF(5) User Commands YAWS.CONF(5)
2
3
4
6 /etc/yaws/yaws.conf - Configuration file for the Yaws web server
7
9 Yaws is fast lightweight web server. It reads a configuration file
10 called yaws.conf to control its operations. The configuration contains
11 two distinct parts: a global part which affects all the virtual hosts
12 and a server part where options for each virtual host is supplied.
13
14
16 logdir = [+]Directory
17 All Yaws logs will be written to files in this directory. If
18 specified with +, Yaws will attempt to create the directory if
19 it does not exist. There are several different log files written
20 by Yaws:
21
22 report.log - this is a text file that contains all error logger
23 printouts from Yaws.
24
25 <Host>.access - for each virtual host served by Yaws, a file
26 <Host>.access will be written that contains an access log in
27 NCSA combined/XLF/ELF log format. (See http://www.w3.org/TR/WD-
28 logfile.html for more details on Extended Log File Format.)
29
30 <Host>.auth - for each virtual host served by Yaws, a file
31 <Host>.auth will be written which contains all http auth related
32 messages.
33
34 trace_<YYYYMMDD_hhmmss> - Trace files are written in this subdi‐
35 rectory, suffixed by the creation date.
36
37 trace.<Pid>.http - this file contains the HTTP trace if
38 that is enabled, where <Pid> is the process id handling the
39 TCP connection.
40
41 trace.<Pid>.traffic - this file contains the traffic trace
42 if that is enabled, where <Pid> is the process id handling
43 the TCP connection.
44
45
46 Note that <Host>.access and <Host>.auth files will be used only
47 if the directive logger_mod is not set or set to yaws_log. The
48 default value for logdir is "."
49
50
51 ebin_dir = Directory
52 This directive adds Directory to the Erlang search path. It is
53 possible to have several of these commands in the configuration
54 file. The default value is "yaws_dir"/examples/ebin
55
56
57 src_dir = Directory
58 This directive defines a Directory as a source directory. Yaws
59 will compile all erlang modules found in this directory and all
60 its subdirectories. The compilation occurs when the configura‐
61 tion is loaded or reloaded. The include_dir directives are used
62 to search for includes files. Multiple src_dir directives may be
63 used. There is no such directory configured by default.
64
65
66
67 id = String
68 It is possible to run multiple Yaws servers on the same machine.
69 We use the id of a Yaws server to control it using the different
70 control commands such as:
71
72 # /usr/local/bin/yaws --id foobar --stop
73
74 To stop the Yaws server with id "foobar". Each Yaws server will
75 write its internal data into a file called $HOME/.yaws/yaws/ID
76 where ID is the identity of the server. Yaws also creates a file
77 called $HOME/.yaws/yaws/ID/CTL which contains the port number
78 where the server is listening for control commands. The default
79 id is "default".
80
81
82 server_signature = String
83 This directive sets the "Server: " output header to the custom
84 value. The default value is "yaws/%VSN%, Yet Another Web
85 Server".
86
87
88 include_dir = Directory
89 This directive adds Directory to the path of directories where
90 the Erlang compiler searches for include files. We need to use
91 this if we want to include .hrl files in our Yaws Erlang code.
92 It is possible to have several of these commands in the configu‐
93 ration file. The default value is "yaws_dir"/examples/include.
94
95
96 max_num_cached_files = Integer
97 Yaws will cache small files such as commonly accessed GIF images
98 in RAM. This directive sets a maximum number on the number of
99 cached files. The default value is 400.
100
101
102 max_num_cached_bytes = Integer
103 This directive controls the total amount of RAM which can maxi‐
104 mally be used for cached RAM files. The default value is
105 1000000, 1 megabyte.
106
107
108 max_size_cached_file = Integer
109 This directive sets a maximum size on the files that are RAM
110 cached by Yaws. The default value is 8000, 8 kBytes.
111
112
113 cache_refresh_secs = Integer
114 The RAM cache is used to serve pages that sit in the cache. An
115 entry sits in cache at most cache_refresh_secs number of sec‐
116 onds. The default is 30. This means that when the content is
117 updated under the docroot, that change doesn't show until 30
118 seconds have passed. While developing a Yaws site, it may be
119 convenient to set this value to 0. If the debug flag (-d) is
120 passed to the Yaws start script, this value is automatically set
121 to 0.
122
123
124 trace = false | traffic | http
125 This enables traffic or http tracing. Tracing is also possible
126 to enable with a command line flag to Yaws. Default is false.
127
128
129 auth_log = true | false
130 Deprecated and ignored. Now, this target must be set in server
131 part.
132
133
134 max_connections = nolimit | Integer
135 Set this value to control the maximum number of connections from
136 HTTP clients into the server. This is implemented by closing the
137 last socket if the limit threshold is reached.
138
139
140 keepalive_maxuses = nolimit | Integer
141 Normally, Yaws does not restrict the number of times a connec‐
142 tion is kept alive using keepalive. Setting this parameter to an
143 integer X will ensure that connections are closed once they have
144 been used X times. This can be a useful to guard against long
145 running connections collecting too much garbage in the Erlang
146 VM.
147
148
149 process_options = undefined | Proplist
150 Set process spawn options for client acceptor processes.
151 Options must be specified as a quoted string of either the atom
152 undefined or as a proplist of valid process options. The sup‐
153 ported options are fullsweep_after, min_heap_size, and
154 min_bin_vheap_size, each taking an associated integer value.
155 Other process options are ignored. The proplist may also be
156 empty. See erlang:spawn_opt/4 for details on these options.
157
158
159 large_file_chunk_size = Integer
160 Set the chunk size used by Yaws to send large files. The default
161 value is 10240.
162
163
164 large_file_sendfile = erlang | disable
165 Set the version of sendfile method to use to send large files:
166
167 erlang - use file:sendfile/5.
168
169 disable - use gen_tcp:send/2.
170
171 The default value is erlang.
172
173
174 acceptor_pool_size = Integer
175 Set the size of the pool of cached acceptor processes. The spec‐
176 ified value must be greater than or equal to 0. The default
177 value is 8. Specifying a value of 0 effectively disables the
178 process pool.
179
180
181 log_wrap_size = Integer
182 The logs written by Yaws are all wrap logs, the default value at
183 the size where they wrap around and the original gets renamed to
184 File.old is 1000000, 1 megabyte. This value can be changed.
185 If we set the value to 0 the logs will never wrap. If we want to
186 use Yaws in combination with a more traditional log wrapper such
187 as logrotate, set the size to 0 and Yaws will reopen the log‐
188 files once they have be renamed/removed.
189
190
191 log_resolve_hostname = true | false
192 By default the client host IP is not resolved in the access
193 logs.
194
195
196
197 fail_on_bind_err = true | false
198 Fail completely or not if Yaws fails to bind a listen socket
199 Default is true.
200
201
202 enable_soap = true | false
203 If true, a soap server will be started at startup of Yaws.
204 Default is false.
205
206
207 soap_srv_mods = ListOfModuleSetting
208 If enable_soap is true, a startup Yaws will invoke
209 yaws_soap_srv:setup() to setup modules set here. ModuleSetting
210 is either a triad like <Mod, HandlerFunc, WsdlFile> or a quadru‐
211 ple form like <Mod, HandlerFunc, WsdlFile, Prefix> which speci‐
212 fies the prefix. A prefix will be used as argument of
213 yaws_soap_lib:initModel() and then be used as a XML namespace
214 prefix. Note, the WsdlFile here should be an absolute-path file
215 in local file systems.
216
217 For example, we can specify
218
219 soap_srv_mods=<Mod1, Handler, Wsdl1> <Mod2, Handler, Wsdl2, Prefix> ...
220
221
222 php_exe_path = Path
223 this target is deprecated and useless. use 'php_handler' target
224 in server part instead.
225 The name of (and possibly path to) the php executable used to
226 interpret php scripts (if allowed). Default is php_exe_path =
227 php-cgi.
228
229
230 copy_error_log = true | false
231 Enable or disable copying of the error log. When we run in
232 embedded mode, there may very well be some other systems process
233 that is responsible for writing the errorlog to a file whereas
234 when we run in normal standalone mode, we typically want the
235 Erlang errorlog written to a report.log file. Default value is
236 true.
237
238
239 ysession_mod = Module
240 Allows specifying a different Yaws session storage mechanism
241 instead of an ETS table. One of the drawbacks of the default
242 yaws_session_server implementation is that server side cookies
243 are lost when the server restarts. Specifying a different module
244 here will pass all write/read operations to this module (it must
245 implement appropriate callbacks).
246
247
248 ysession_cookiegen = Module
249 Allows specifying a different Yaws session cookie generator than
250 the built-in default. Module is expected to provide a
251 new_cookie/0 function that returns a session cookie in the form
252 of a list. Such a cookie generator module must be careful to
253 return a unique cookie each time it's called.
254
255
256 ysession_idle_timeout = Integer
257 Controls Yaws session idle cleanup. If a server has been idle
258 for ysession_idle_timeout milliseconds, check all Yaws sessions
259 and remove any that have timed out. The default yses‐
260 sion_idle_timeout value is 2*60*1000 (2 minutes).
261
262
263 ysession_long_timeout = Integer
264 Controls Yaws session periodic cleanup. Every yses‐
265 sion_long_timeout milliseconds, check all Yaws sessions and
266 remove any that have timed out. The default ysession_long_time‐
267 out value is 60*60*1000 (1 hour).
268
269
270 runmod = ModuleName
271 At startup Yaws will invoke ModuleName:start() in a separate
272 process. It is possible to have several runmods. This is useful
273 if we want to reuse the Yaws startup shell script for our own
274 application.
275
276
277 pick_first_virthost_on_nomatch = true | false
278 When Yaws gets a request, it extracts the Host header from the
279 client request to choose a virtual server amongst all servers
280 with the same IP/Port pair. This configuration parameter
281 decides whether Yaws should pick the first server (as defined in
282 the yaws.conf file) if no name match or not. If this is false
283 and no Host header is present in the request, Yaws returns a 400
284 Bad Request as required by the HTTP standard. In real live host‐
285 ing scenarios we typically want this to be false, whereas in
286 testing/development scenarios it may be convenient to set it to
287 true. Default is true.
288
289
290 keepalive_timeout = TimeInMilliseconds | infinity
291 If the HTTP session will be kept alive (i.e., not immediately
292 closed) it will close after keepalive_timeout milliseconds
293 unless a new request is received in that time. The default value
294 is 30000. The value infinity is legal but not recommended.
295
296
297 subconfig = File
298 Load specified config file. Absolute paths or relative ones to
299 the configuration location are allowed. Unix-style wildcard
300 strings can be used to include several files at once. See
301 filelib:wildcard/1 for details. Hidden files, starting by a dot,
302 will be ignored. For example:
303
304 subconfig = /etc/yaws/global.conf
305 subconfig = /etc/yaws/vhosts/*.conf
306
307 Or, relatively to the configuration location:
308
309 subconfig = global.conf
310 subconfig = vhosts/*.conf
311
312
313 subconfigdir = Directory
314 Load all config files found in the specified directory. The
315 given Directory can be an absolute path or relative to the con‐
316 figuration location. Hidden files, starting by a dot, will be
317 ignored.
318
319
320 x_forwarded_for_log_proxy_whitelist = ListOfUpstreamProxyServerIps
321 this target is deprecated and will be ignored.
322
323
324 default_type = MimeType
325 Defines the default MIME type to be used where Yaws cannot
326 determine it by its MIME types mappings. Default is text/plain.
327
328
329 default_charset = Charset
330 Defines the default charset to be added when a response content-
331 type is text/*. By default, no charset is added.
332
333
334 mime_types_file = File
335 Overrides the default mime.types file included with Yaws. This
336 file must use the following format:
337
338 # Lines beginning with a '#' or a whitespace are ignored
339 # blank lines are also ignored
340 <MIME type> <space separated file extensions>
341
342 The default file is located at ${PRE‐
343 FIX}/lib/yaws/priv/mime.types. You should not edit this file
344 because it may be replaced when you upgrade your server.
345
346
347 add_types = ListOfTypes
348 Specifies one or more mappings between MIME types and file
349 extensions. More than one extension can be assigned to a MIME
350 type. ListOfTypes is defined as follows:
351
352 add_types = <MimeType1, Ext> <MimeType2, Ext1 Ext2 ...> ...
353
354 The mappings defined using this directive will overload all
355 other definitions. If a file extension is defined several times,
356 only the last one is kept. Multiple add_types directives may be
357 used.
358
359
360 add_charsets = ListOfCharsets
361 Specifies one or more mappings between charsets and file exten‐
362 sions. More than one extension can be assigned to a charset.
363 ListOfCharsets is defined as follows:
364
365 add_charsets = <Charset1, Ext> <Charset2, Ext1 Ext2 ...> ...
366
367 The mappings defined using this directive will overload all
368 other definitions. If a file extension is defined several times,
369 only the last one is kept. Multiple add_charsets directives may
370 be used.
371
372
373 sni = disable | enable | strict
374 Enables or disables the TLS SNI (Server Name Indication) sup‐
375 port.
376
377 When disabled (or not supported), all virtual servers in the
378 same group (same IP/Port) must share the same SSL configuration,
379 especially the same SSL certificate. Only the HTTP Host header
380 will be considered to find the right virtual server.
381
382 When enabled, SSL configuration can be different from a virtual
383 server to another, each one can have its own SSL certificate. In
384 this case, if a client provides a SNI hostname, it will be used
385 to find the right virtual server. To accept the SNI information
386 from the client, The first virtual server (the default one, see
387 pick_first_virthost_on_nomatch) must include TLS as a permitted
388 protocol.
389
390 If sni directive is set to enable, non SNI clients are allowed.
391 For such clients, virtual servers are selected as if Yaws did
392 not have SNI support. If it is set to strict, SNI hostname is
393 mandatary to access a SSL virtual server. But, in all cases,
394 when SNI support is enabled, if a client provides a SNI host‐
395 name, it must match the HTTP Host header (which is mandatory
396 too). Note that the first virtual server (the default one) will
397 be used for any request where the provided SNI hostname doesn't
398 match any of virtual server names. So, it is important that the
399 first virtual server have the most restrictive access control,
400 otherwise clients can access restricted resources by sending a
401 request for any unknown hostname. (This isn't actually any dif‐
402 ferent from using virtual servers without SNI support.)
403
404 The sni directive is a global one, so if you set it to strict,
405 non SNI clients will be refused for all SSL groups. See
406 require_sni directive from the server part to mitigate this
407 requirement.
408
409 Default is disable.
410
411 WARNING: The SNI support was introduced in the SSL application
412 in Erlang/OTP 18.0, so Yaws ignores it for previous releases.
413
414
416 Yaws can virthost several web servers on the same IP address as well as
417 several web servers on different IP addresses. This includes SSL
418 servers.
419
420 Each virtual host is defined within a matching pair of <server Server‐
421 Name> and </server>. The ServerName will be the name of the webserver.
422
423
424 The following directives are allowed inside a server definition.
425
426 port = Port
427 This makes the server listen on Port. Default is 8000.
428
429 listen = IpAddress
430 This makes the server listen on IpAddress. When virthosting
431 several servers on the same ip/port address, if the browser
432 doesn't send a Host: field, Yaws will pick the first server
433 specified in the config file. If the specified IP address is
434 0.0.0.0 Yaws will listen on all local IP addresses on the speci‐
435 fied port. Default is 127.0.0.1. Multiple listen directives may
436 be used to specify several addresses to listen on.
437
438
439 listen_backlog = Integer
440 This sets the TCP listen backlog for the server to define the
441 maximum length the queue of pending connections may grow to. The
442 default is 1024.
443
444
445 <listen_opts> ... </listen_opts>
446 Defines extra options to be set on the listen socket and, by
447 inheritance, on accepted sockets. See inet:setopts/2 for
448 details. Supported options are:
449
450 buffer = Integer (default: same as inet:setopts/2)
451
452 delay_send = true | false (default: same as inet:setopts/2)
453
454 linger = Integer | false (default: same as inet:setopts/2)
455
456 nodelay = true | false (default: same as inet:setopts/2)
457
458 priority = Integer (default: same as inet:setopts/2)
459
460 sndbuf = Integer (default: same as inet:setopts/2)
461
462 recbuf = Integer (default: same as inet:setopts/2)
463
464 send_timeout = Integer | infinity (default: same as
465 inet:setopts/2)
466
467 send_timeout_close = true | false (default: same as
468 inet:setopts/2)
469
470
471 server_signature = String
472 This directive sets the "Server: " output header to the custom
473 value and overloads the global one for this virtual server.
474
475
476 subconfig = File
477 Same as subconfig directive of the global part, but here files
478 should only contain directives allowed in the server part.
479
480
481
482 subconfigdir = Directory
483 Same as subconfigdir directive of the global part, but here
484 files should only contain directives allowed in server part.
485
486
487 rhost = Host[:Port]
488 This forces all local redirects issued by the server to go to
489 Host. This is useful when Yaws listens to a port which is dif‐
490 ferent from the port that the user connects to. For example,
491 running Yaws as a non-privileged user makes it impossible to
492 listen to port 80, since that port can only be opened by a priv‐
493 ileged user. Instead Yaws listens to a high port number port,
494 8000, and iptables are used to redirect traffic to port 80 to
495 port 8000 (most NAT:ing firewalls will also do this for you).
496
497
498 rmethod = http | https
499 This forces all local redirects issued by the server to use this
500 method. This is useful when an SSL off-loader, or stunnel, is
501 used in front of Yaws.
502
503
504 auth_log = true | false
505 Enable or disable the auth log for this virtual server. Default
506 is true.
507
508
509 access_log = true | false
510 Setting this directive to false turns off traffic logging for
511 this virtual server. The default value is true.
512
513
514 logger_mod = Module
515 It is possible to set a special module that handles access and
516 auth logging. The default is to log all web server traffic to
517 <Host>.access and <Host>.auth files in the configured or default
518 logdir.
519 This module must implement the behaviour yaws_logger. Default
520 value is yaws_log.
521
522 The following functions should be exported:
523
524 Module:open_log(ServerName, Type, LogDir)
525 When Yaws is started, this function is called for this vir‐
526 tual server. If the initialization is successful, the func‐
527 tion must return {true,State} and if an error occurred, it
528 must return false.
529
530
531 Module:close_log(ServerName, Type, State)
532 This function is called for this virtual server when Yaws
533 is stopped.
534
535
536 Module:wrap_log(ServerName, Type, State, LogWrapSize)
537 This function is used to rotate log files. It is regularly
538 called by Yaws and must return the possibly updated inter‐
539 nal NewState.
540
541
542 Module:write_log(ServerName, Type, State, Infos)
543 When it needs to log a message, Yaws will call this func‐
544 tion. The parameter Infos is {Ip,Req,InHdrs,OutHdrs,Time}
545 for an access log and {Ip,Path,Item} for an auth log,
546 where:
547
548 Ip - IP address of the accessing client (as a tuple).
549
550 Req - the HTTP method, URI path, and HTTP version of the
551 request (as a #http_request{} record).
552
553 InHdrs - the HTTP headers which were received from the WWW
554 client (as a #headers{} record).
555
556 OutHdrs - the HTTP headers sent to the WWW client (as a
557 #outh{} record)
558
559 Path - the URI path of the request (as a string).
560
561 Item - the result of an authentication request. May be
562 {ok,User}, 403 or {401,Realm}.
563
564 Time - The time taken to serve the request, in microsec‐
565 onds.
566
567
568 For all of these callbacks, ServerName is the virtual server's
569 name, Type is the atom access or auth and State is the internal
570 state of the logger.
571
572
573 shaper = Module
574 Defines a module to control access to this virtual server.
575 Access can be controlled based on the IP address of the client.
576 It is also possible to throttle HTTP requests based on the
577 client's download rate. This module must implement the behaviour
578 yaws_shaper.
579
580 There is no such module configured by default.
581
582
583 dir_listings = true | true_nozip | false
584 Setting this directive to false disallows the automatic dir
585 listing feature of Yaws. A status code 403 Forbidden will be
586 sent. Set to true_nozip to avoid the auto-generated all.zip
587 entries. Default is false.
588
589
590 extra_cgi_vars = .....
591 Add additional CGI or FastCGI variables. For example:
592
593 <extra_cgi_vars dir='/path/to/some/scripts'>
594 var = val
595 ...
596 </extra_cgi_vars>
597
598
599 statistics = true | false
600 Turns on/off statistics gathering for a virtual server. Default
601 is false.
602
603
604 fcgi_app_server = Host:Port
605 The hostname and TCP port number of a FastCGI application
606 server. To specify an IPv6 address, put it inside square brack‐
607 ets (ex: "[::1]:9000"). The TCP port number is not optional.
608 There is no default value.
609
610
611 fcgi_trace_protocol = true | false
612 Enable or disable tracing of FastCGI protocol messages as info
613 log messages. Disabled by default.
614
615
616 fcgi_log_app_error = true | false
617 Enable or disable logging of application error messages (output
618 to stderr and non-zero exit value). Disabled by default.
619
620
621 deflate = true | false
622 Turns on or off deflate compression for a server. Default is
623 false.
624
625
626
627 <deflate> ... </deflate>
628 This begins and ends the deflate compression configuration for
629 this server. The following items are allowed within a matching
630 pair of <deflate> and </deflate> delimiters.
631
632 min_compress_size = nolimit | Integer
633 Defines the smallest response size that will be compressed.
634 If nolimit is not used, the specified value must be
635 strictly positive. The default value is nolimit.
636
637
638 compression_level = none | default | best_compression |
639 best_speed | 0..9
640 Defines the compression level to be used. 0 (none), gives
641 no compression at all, 1 (best_speed) gives best speed and
642 9 (best_compression) gives best compression. The default
643 value is default.
644
645
646 window_size = 9..15
647 Specifies the zlib compression window size. It should be in
648 the range 9 through 15. Larger values of this parameter
649 result in better compression at the expense of memory
650 usage. The default value is 15.
651
652
653 mem_level = 1..9
654 Specifies how much memory should be allocated for the
655 internal compression state. mem_level=1 uses minimum memory
656 but is slow and reduces compression ratio; mem_level=9 uses
657 maximum memory for optimal speed. The default value is 8.
658
659
660 strategy = default | filtered | huffman_only
661 This parameter is used to tune the compression algorithm.
662 See zlib(3erl) for more details on the strategy parameter.
663 The default value is default.
664
665
666 use_gzip_static = true | false
667 If true, Yaws will try to serve precompressed versions of
668 static files. It will look for precompressed files in the
669 same location as original files that end in ".gz". Only
670 files that do not fit in the cache are concerned. The
671 default value is false.
672
673
674 mime_types = ListOfTypes | defaults | all
675 Restricts the deflate compression to particular MIME types.
676 The special value all enable it for all types (It is a syn‐
677 onym of `*/*'). MIME types into ListOfTypes must have the
678 form `type/subtype' or `type/*' (indicating all subtypes of
679 that type). Here is an example:
680
681 mime_types = default image/*
682 mime_types = application/xml application/xhtml+xml application/rss+xml
683
684 By default, the following MIME types are compressed (if
685 deflate is set to true): text/*, application/rtf, applica‐
686 tion/msword, application/pdf, application/x-dvi, applica‐
687 tion/javascript, application/x-javascript. Multiple
688 mime_types directive can be used.
689
690
691 docroot = Directory ...
692 This makes the server serve all its content from Directory.
693 It is possible to pass a space-separated list of directories as
694 docroot. If this is the case, the various directories will be
695 searched in order for the requested file. This also works with
696 the ssi and yssi constructs where the full list of directories
697 will be searched for files to ssi/yssi include. Multiple docroot
698 directives can be used. You need at least one valid docroot,
699 invalid docroots are skipped with their associated auth struc‐
700 tures.
701
702
703 auth_skip_docroot = true | false
704 If true, the docroot will not be searched for .yaws_auth files.
705 This is useful when the docroot is quite large and the time to
706 search it is prohibitive when Yaws starts up. Defaults to false.
707
708
709 partial_post_size = Integer | nolimit
710 When a Yaws file receives large POSTs, the amount of data
711 received in each chunk is determined by this parameter. The
712 default value is 10240. Setting it to nolimit is potentially
713 dangerous.
714
715
716
717 dav = true | false
718 Turns on the DAV protocol for this server. The dav support in
719 Yaws is highly limited. If dav is turned on, .yaws processing of
720 .yaws pages is turned off. Default is false. The socket read
721 timeout is supplied by the keepalive_timeout setting. If the
722 read is not done within the timeout, the POST will fail.
723
724
725 tilde_expand = true|false
726 If this value is set to false Yaws will never do tilde expan‐
727 sion. The default is false. tilde_expansion is the mechanism
728 whereby a URL on the form http://www.foo.com/~username is
729 changed into a request where the docroot for that particular
730 request is set to the directory ~username/public_html/.
731
732
733 allowed_scripts = ListOfSuffixes
734 The allowed script types for this server. Recognized are
735 `yaws', `cgi', `fcgi', `php'. Default is allowed_scripts = yaws
736 php cgi fcgi.
737
738 Note: for fcgi scripts, the FastCGI application server is only
739 called if a local file with the .fcgi extension exists. However,
740 the contents of the local .fcgi file are ignored.
741
742
743 tilde_allowed_scripts = ListOfSuffixes
744 The allowed script types for this server when executing files in
745 a users public_html folder Recognized are `yaws', `cgi', `fcgi',
746 `php'. Default is tilde_allowed_scripts = i.e. empty
747
748
749 index_files = ListOfResources
750 This directive sets the list of resources to look for, when a
751 directory is requested by the client. If the last entry begins
752 with a `/', and none of the earlier resources are found, Yaws
753 will perform a redirect to this uri. Default is index_files =
754 index.yaws index.html index.php.
755
756
757 appmods = ListOfModuleNames
758 If any of the names in ListOfModuleNames appear as components in
759 the path for a request, the path request parsing will terminate
760 and that module will be called. There is also an alternate syn‐
761 tax for specifying the appmods if we don't want our internal
762 erlang module names to be exposed in the URL paths. We can
763 specify
764
765 appmods = <Path1, Module1> <Path2, Modules2> ...
766
767 Assume for example that we have the URL
768 http://www.hyber.org/myapp/foo/bar/baz?user=joe while we have
769 the module foo defined as an appmod, the function foo:out(Arg)
770 will be invoked instead of searching the filesystems below the
771 point foo.
772 The Arg argument will have the missing path part supplied in its
773 appmoddata field.
774
775 It is also possible to exclude certain directories from appmod
776 processing. This is particulaly interesting for '/' appmods.
777 Here is an example:
778
779 appmods = </, myapp exclude_paths icons js top/static>
780
781 The above configuration will invoke the 'myapp' erlang module on
782 everything except any file found in directories 'icons', 'js'
783 and 'top/static' relative to the docroot.
784
785
786 dispatchmod = DispatchModule
787 Set DispatchModule as a server-specific request dispatching mod‐
788 ule. Yaws expects DispatchModule to export a dispatch/1 func‐
789 tion. When it receives a request, Yaws passes an #arg{} record
790 to the dispatch module's dispatch/1 function, which returns one
791 of the following atom results:
792
793 done - this indicates the dispatch module handled the
794 request itself and already sent the response, and Yaws
795 should resume watching for new requests on the connection
796
797 closed - same as done but the DispatchModule also closed
798 the connection
799
800 continue - the dispatch module has decided not to handle
801 the request, and instead wants Yaws to perform its regular
802 request dispatching
803
804
805 Note that when DispatchModule handles a request itself, Yaws
806 does not support tracing, increment statistics counters or allow
807 traffic shaping for that request. It does however still keep
808 track of maximum keepalive uses on the connection.
809
810
811 errormod_404 = Module
812 It is possible to set a special module that handles 404 Not
813 Found messages. The function Module:out404(Arg, GC, SC) will be
814 invoked. The arguments are
815
816 Arg - a #arg{} record
817
818 GC - a #gconf{} record (defined in yaws.hrl)
819
820 SC - a #sconf{} record (defined in yaws.hrl)
821
822
823 The function can and must do the same things that a normal out/1
824 does.
825
826
827 errormod_401 = Module
828 It is possible to set a special module that handles 401 Unautho‐
829 rized messages. This can for example be used to display a login
830 page instead. The function Module:out401(Arg, Auth, Realm) will
831 be invoked. The arguments are
832
833 Arg - a #arg{} record
834
835 Auth - a #auth{} record
836
837 Realm - a string
838
839
840 The function can and must do the same things that a normal out/1
841 does.
842
843
844 errormod_crash = Module
845 It is possible to set a special module that handles the HTML
846 generation of server crash messages. The default is to display
847 the entire formatted crash message in the browser. This is good
848 for debugging but not in production.
849 The function Module:crashmsg(Arg, SC, Str) will be called. The
850 Str is the real crash message formatted as a string.
851 The function must return, {content,MimeType,Cont} or {html, Str}
852 or {ehtml, Term}. That data will be shipped to the client.
853
854
855 expires = ListOfExpires
856 Controls the setting of the Expires HTTP header and the max-age
857 directive of the Cache-Control HTTP header in server responses
858 for specific MIME types. The expiration date can be set as rela‐
859 tive to either the time the source file was last modified; as
860 the time of the client access; or as always in order to empty
861 the cache altogether. ListOfExpires is defined as follows:
862
863 expires = <MimeType1, access+Seconds> <MimeType2, modify+Seconds> <MimeType3, always> ...
864
865 A MimeType can also have a wildcard as subtype or both as sub‐
866 type and type, like type/* or */*.
867
868 These HTTP headers are an instruction to the client about the
869 document's validity and persistence. If cached, the document may
870 be fetched from the cache rather than from the source until this
871 time has passed. After that, the cache copy is considered
872 "expired" and invalid, and a new copy must be obtained from the
873 source. Here is an example:
874
875 expires = <image/gif, access+2592000> <image/png, access+2592000>
876 expires = <image/jpeg, access+2592000> <text/css, access+2592000>
877 expires = <text/*, always>
878
879 and here is another:
880
881 expires = <*/*, always>
882
883
884 arg_rewrite_mod = Module
885 It is possible to install a module that rewrites all the Arg
886 #arg{} records at an early stage in the Yaws server. This can
887 be used to do various things such as checking a cookie, rewrit‐
888 ing paths etc. An arg_rewrite_mod must export an arg_rewrite/1
889 function taking and returning an #arg{} record. If the function
890 wants to return a response, it must set the #arg.state field of
891 its return value to an instance of the #rewrite_response{}
892 record.
893
894 The module yaws_vdir can be used in case you want to serve
895 static content that is not located in your docroot. See the
896 example at the bottom of this man page for how to use the opaque
897 + vdir elements to instruct the yaws_vdir module what paths to
898 rewrite.
899
900
901 start_mod = Module
902 Defines a user provided callback module. At startup of the
903 server, Module:start/1 will be called. The #sconf{} record
904 (defined in yaws.hrl) will be used as the input argument. This
905 makes it possible for a user application to synchronize the
906 startup with the Yaws server as well as getting hold of user
907 specific configuration data, see the explanation for the
908 <opaque> context.
909
910
911 revproxy = Prefix Url [intercept_mod Module]
912 Make Yaws a reverse proxy. Prefix is a path inside our own doc‐
913 root and Url argument is a URL pointing to a website we want to
914 "mount" under the Prefix path. This example:
915
916 revproxy = /tmp/foo http://yaws.hyber.org
917
918 makes the hyber website appear under /tmp/foo.
919
920 It is possible to have multiple reverse proxies inside the same
921 server.
922
923 You can optionally configure an interception module for each
924 reverse proxy, allowing your application to examine and modify
925 requests and HTTP headers as they pass through the proxy from
926 client to backend server and also examine and modify responses
927 and HTTP headers as they return from the backend server through
928 the proxy to the client.
929
930 You specify an interception module by including the optional
931 intercept_mod keyword followed by Module, which should be the
932 name of your interception module.
933
934 An interception module is expected to export two functions: re‐
935 write_request/2 and rewrite_response/2. The two arguments passed
936 to rewrite_request/2 function are a #http_request{} record and a
937 #headers{} record, whereas rewrite_response/2 function takes a
938 #http_response{} record and also a #headers{} record. You can
939 find definitions for these record types in the yaws_api.hrl
940 header file. Each function can examine each record instance and
941 can either return each original instance or can return a modi‐
942 fied copy of each instance in its response. The re‐
943 write_request/2 function should return a tuple of the following
944 form:
945
946 {ok, #http_request{}, #headers{}}
947
948 and the rewrite_response/2 function should similarly return a
949 tuple of the following form:
950
951 {ok, #http_response{}, #headers{}}
952
953 A #headers{} record can easily be manipulated in an interceptor
954 using the functions listed below:
955
956 yaws_api:set_header/2, yaws_api:set_header/3
957 yaws_api:get_header/2, yaws_api:get_header/3
958 yaws_api:delete_header/2
959
960 Any failures in your interception module's functions will result
961 in HTTP status code 500, indicating an internal server error.
962
963
964 fwdproxy = true|false
965 Make Yaws a forward proxy. By enabling this option you can use
966 Yaws as a proxy for outgoing web traffic, typically by configur‐
967 ing the proxy settings in a web-browser to explicitly target
968 Yaws as its proxy server.
969
970
971 servername = Name
972 If we're virthosting several servers and want to force a server
973 to match specific Host: headers we can do this with the "server‐
974 name" directive. This name doesn't necessarily have to be the
975 same as the the name inside <server Name> in certain NAT scenar‐
976 ios. Rarely used feature.
977
978
979 serveralias = ListOfNames
980
981 This directive sets the alternate names for a virtual host. A
982 server alias may contain wildcards:
983 '*' matches any sequence of zero or more characters
984 '?' matches one character unless that character is a
985 period ('.')
986
987 Multiple serveralias directives may be used. Here is an example:
988
989 <server server.domain.com>
990 serveralias = server server2.domain.com server2
991 serveralias = *.server.domain.com *.server?.domain.com
992 ...
993 </server>
994
995
996
997 php_handler = <Type, Spec>
998 Set handler to interpret .php files. It can be one of the fol‐
999 lowing definitions:
1000
1001 php_handler = <cgi, Filename> - The name of (and possibly path
1002 to) the php executable used to interpret php scripts (if
1003 allowed).
1004
1005 php_handler = <fcgi, Host:Port> - Use the specified fastcgi
1006 server to interpret .php files (if allowed).
1007
1008 Yaws does not start the PHP interpreter in fastcgi mode for
1009 you. To run PHP in fastcgi mode, call it with the -b
1010 option. For example:
1011
1012 php5-cgi -b '127.0.0.1:54321'
1013
1014 This starts a php5 in fastcgi mode listening on the local
1015 network interface. To make use of this PHP server from
1016 Yaws, specify:
1017
1018 php_handler = <fcgi, 127.0.0.1:54321>
1019
1020 If you need to specify an IPv6 address, use square brack‐
1021 ets:
1022
1023 php_handler = <fcgi, [::1]:54321>
1024
1025 The PHP interpreter needs read access to the files it is to
1026 serve. Thus, if you run it in a different security context
1027 than Yaws itself, make sure it has access to the .php
1028 files.
1029 Please note that anyone who is able to connect to the php
1030 fastcgi server directly can use it to read any file to
1031 which it has read access. You should consider this when
1032 setting up a system with several mutually untrusted
1033 instances of php.
1034
1035
1036 php_handler = <extern, Module:Function | Node:Module:Function> -
1037 Use an external handler, possibly on another node, to interpret
1038 .php files (if allowed).
1039
1040 To interpret a .php file, the function Module:Function(Arg)
1041 will be invoked (Evaluated inside a rpc call if a Node is
1042 specified), where Arg is an #arg{} record.
1043 The function must do the same things that a normal out/1
1044 does.
1045
1046
1047 Default value is <cgi, "/usr/bin/php-cgi">.
1048
1049
1050 phpfcgi = Host:Port
1051 this target is deprecated. use 'php_handler' target in server
1052 part instead.
1053 Using this directive is the same as: php_handler = <fcgi,
1054 Host:Port>.
1055
1056
1057 default_type = MimeType
1058 Overloads the global default_type value for this virtual server.
1059
1060 default_charset = Charset
1061 Overloads the global default_charset value for this virtual
1062 server.
1063
1064
1065 mime_types_file = File
1066 Overloads the global mime_type_file value for this virtual
1067 server. Mappings defined in File will not overload those defined
1068 by add_types directives in the global part.
1069
1070
1071 add_types = ListOfTypes
1072 Overloads the global add_types values for this virtual server.
1073 If a mapping is defined in the global part and redefined in a
1074 server part using this directive, then it is replaced. Else it
1075 is kept.
1076
1077
1078 add_charsets = ListOfCharsets
1079 Overloads the global add_charsets values for this virtual
1080 server. If a mapping is defined in the global part and redefined
1081 in a server part using this directive, then it is replaced. Else
1082 it is kept.
1083
1084
1085 nslookup_pref = [inet | inet6]
1086 For fcgi servers and revproxy URLs, define the name resolution
1087 preference. For example, to perform only IPv4 name resolution,
1088 use [inet]. To do both IPv4 and IPv6 but try IPv6 first, use
1089 [inet6, inet]. Default value is [inet].
1090
1091
1092 <ssl> ... </ssl>
1093
1094 This begins and ends an SSL configuration for this server. It's
1095 possible to virthost several SSL servers on the same IP/Port. If
1096 SNI support is disabled or not supported, they must share the
1097 same certificate configuration. In this situation, it is compli‐
1098 cated to virthost several SSL servers on the same IP/Port since
1099 the certificate is typically bound to a domainname in the common
1100 name part of the certificate. One solution to this problem is to
1101 have a certificate with multiple subjectAltNames. If SNI support
1102 is enabled, SSL servers on the same IP/Port can have their own
1103 SSL configuration with a different SSL certificate for each one.
1104 See the global sni directive.
1105
1106 The SNI support was introduced in the SSL application in
1107 Erlang/OTP 18.0. It is an extension to the TLS protocol (RFC
1108 4366), which allows the client to include the requested hostname
1109 in the first message of its SSL handshake.
1110
1111 See also http://wiki.cacert.org/VhostTaskForce#Interoperabil‐
1112 ity_Test for browser compatibility.
1113
1114 keyfile = File
1115 Specifies which file contains the private key for the cer‐
1116 tificate. If not specified then the certificate file will
1117 be used.
1118
1119
1120 certfile = File
1121 Specifies which file contains the certificate for the
1122 server.
1123
1124
1125 cacertfile = File
1126 A file containing trusted certificates to use during client
1127 authentication and to use when attempting to build the
1128 server certificate chain. The list is also used in the
1129 list of acceptable client CAs passed to the client when a
1130 certificate is requested.
1131
1132
1133 dhfile = File
1134 A file containing PEM-encoded Diffie-Hellman parameters to
1135 be used by the server if a cipher suite using Diffie-Hell‐
1136 man key exchange is negotiated. If not specified, default
1137 parameters are used.
1138
1139
1140 verify = verify_none | verify_peer
1141 Specifies the level of verification the server does on
1142 client certs. Setting verify_none means that the x509 vali‐
1143 dation will be skipped (no certificate request is sent to
1144 the client), verify_peer means that a certificate request
1145 is sent to the client (x509 validation is performed.
1146
1147 You might want to use fail_if_no_peer_cert in combination
1148 with verify_peer.
1149
1150
1151 fail_if_no_peer_cert = true | false
1152 If verify is set to verify_peer and set to true the connec‐
1153 tion will fail if the client does not send a certificate
1154 (i.e. an empty certificate). If set to false the server
1155 will fail only if an invalid certificate is supplied (an
1156 empty certificate is considered valid).
1157
1158
1159 depth = Int
1160 Specifies the depth of certificate chains the server is
1161 prepared to follow when verifying client certs. For the OTP
1162 new SSL implementation it is also used to specify how far
1163 the server, i.e. we, shall follow the SSL certificates we
1164 present to the clients. Hence, using self-signed certs, we
1165 typically need to set this to 0.
1166
1167
1168 password = String
1169 If the private key is encrypted on disc, this password is
1170 the 3DES key to decrypt it.
1171
1172
1173 ciphers = String
1174 This string specifies the SSL cipher string. The syntax of
1175 the SSL cipher string is an erlang term compliant with the
1176 output of ssl:cipher_suites().
1177
1178 ciphers = "[{dhe_rsa,aes_256_cbc,sha}, \
1179 {dhe_dss,aes_256_cbc,sha}]"
1180
1181
1182 secure_renegotiate = true | false
1183 Specifies whether to reject renegotiation attempt that does
1184 not live up to RFC 5746. By default secure_renegotiate is
1185 set to false i.e. secure renegotiation will be used if pos‐
1186 sible but it will fallback to unsecure renegotiation if the
1187 peer does not support RFC 5746.
1188
1189
1190 client_renegotiation = true | false
1191 Enables or disables the Erlang/OTP SSL application client
1192 renegotiation option. Defaults to true. See the ssl manual
1193 page at http://www.erlang.org/doc/man/ssl.html for more
1194 details.
1195
1196 WARNING: This option was introduced in the SSL application
1197 in Erlang/OTP 18.0, so Yaws ignores it for previous
1198 releases.
1199
1200
1201 honor_cipher_order = true | false
1202 If true (the default), use the server's preference for
1203 cipher selection. If false, use the client's preference.
1204
1205 WARNING: This option was introduced in the SSL application
1206 in Erlang/OTP 17.0, so Yaws ignores it for previous
1207 releases.
1208
1209
1210 protocol_version = ProtocolList
1211 Specifies the list of SSL protocols that will be supported.
1212 If not set, defaults to all protocols supported by the
1213 erlang ssl application. For example, to support only TLS
1214 versions 1.2, 1.1, and 1:
1215
1216 protocol_version = tlsv1.2, tlsv1.1, tlsv1
1217
1218
1219 require_sni = true | false
1220 If true,the server will reject non SNI clients and clients
1221 providing an unknown SNI hostname (this last remark is only
1222 relevant for the first virtual server of a SSL group). This
1223 directive is ignored if SNI support is disabled (or not
1224 supported).
1225
1226 Default is false.
1227
1228
1229 <redirect> ... </redirect>
1230 Defines a redirect mapping. The following items are allowed
1231 within a matching pair of <redirect> and </redirect> delimiters.
1232
1233 We can have a series of redirect rules in one of the formats
1234 below:
1235
1236 Path = URL
1237 Path = code
1238 Path = code URL
1239
1240 Path must be an url-decoded path beginning with a slash. URL may
1241 be either a relative URL (a path beginning with a slash), or an
1242 absolute URL. In the first case, the scheme:hostname:port of the
1243 current server will be added. All accesses to Path will be redi‐
1244 rected to URL/Path (or scheme:hostname:port/URL/Path if URL is
1245 relative). URL must be url-encoded. Note that the original path
1246 is appended to the redirected URL.
1247
1248 For example, assume we have the following redirect configura‐
1249 tion:
1250
1251 <redirect>
1252 /foo = http://www.mysite.org/zapp
1253 /bar = /tomato.html
1254 </redirect>
1255
1256 Assuming this config resides on a site called http://abc.com, we
1257 have the following redirects:
1258
1259 http://abc.com/foo -> http://www.mysite.org/zapp/foo
1260 http://abc.com/foo/test -> http://www.mysite.org/zapp/foo/test
1261 http://abc.com/bar -> http://abc.com/tomato.html/bar
1262 http://abc.com/bar/x/y/z -> http://abc.com/tomato.html/bar/x/y/z
1263
1264 By default, Yaws will perform a 302 redirect. The HTTP status
1265 code can be changed using the code parameter. Note that the sta‐
1266 tus code must be known by Yaws.
1267
1268 · For 3xx status codes, the URL parameter must be present and
1269 will be used to build the new location.
1270
1271 · For other status codes (1xx, 2xx, 4xx and 5xx), it can be
1272 omitted. In the absence of URL, Yaws will return a generic
1273 response with the specified status code.
1274
1275 · Otherwise, the URL parameter must be a relative URL and will
1276 be used to customize the response.
1277
1278 Sometimes we do not want to have the original path appended to
1279 the redirected path. To get that behaviour we specify the config
1280 with '==' instead of '='.
1281
1282 <redirect>
1283 /foo == http://www.mysite.org/zapp
1284 /bar = /tomato.html
1285 </redirect>
1286
1287 Now a request for http://abc.com/foo/x/y/z simply gets redi‐
1288 rected to http://www.mysite.org/zapp. This is typically used
1289 when we simply want a static redirect at some place in the doc‐
1290 root.
1291
1292 When we specify a relative URL as the target for the redirect,
1293 the redirect will be to the current http(s) server.
1294
1295
1296 <auth> ... </auth>
1297 Defines an auth structure. The following items are allowed
1298 within a matching pair of <auth> and </auth> delimiters.
1299
1300 docroot = Docroot
1301 If a docroot is defined, this auth structure will be tested
1302 only for requests in the specified docroot. No docroot con‐
1303 figured means all docroots. If two auth structures are
1304 defined, one with a docroot and one with no docroot, the
1305 first of both overrides the second one for requests in the
1306 configured docroot.
1307
1308
1309 dir = Dir
1310 Makes Dir to be controlled by WWW-authenticate headers. In
1311 order for a user to have access to WWW-Authenticate con‐
1312 trolled directory, the user must supply a password. The Dir
1313 must be specified relative to the docroot. Multiple dir
1314 can be used. If no dir is set, the default value, "/", will
1315 be used.
1316
1317
1318 realm = Realm
1319 In the directory defined here, the WWW-Authenticate Realm
1320 is set to this value.
1321
1322
1323 authmod = AuthMod
1324 If an auth module is defined then AuthMod:auth(Arg, Auth)
1325 will be called for all access to the directory. The auth/2
1326 function should return one of: true, false, {false, Realm},
1327 {appmod, Mod}. If {appmod, Mod} is returned then a call to
1328 Mod:out401(Arg, Auth, Realm) will be used to deliver the
1329 content. If errormod_401 is defined, the call to Mod will
1330 be ignored. (Mod:out(Arg) is deprecated).
1331
1332 This can, for example, be used to implement cookie authen‐
1333 tication. The auth() callback would check if a valid
1334 cookie header is present, if not it would return {appmod,
1335 ?MODULE} and the out401/1 function in the same module would
1336 return {redirect_local, "/login.html"}.
1337
1338
1339 user = User:Password | "User:{Algo}Hash" |
1340 "User:{Algo}$Salt$Hash"
1341 Inside this directory, the user User has access if the user
1342 supplies the password Password in the popup dialogue pre‐
1343 sented by the browser. It is also possible to provide a
1344 hashed password, encoded in base64. In that case, the algo‐
1345 rithm used to hash the password must be set. Algo must be a
1346 one of the following algorithms:
1347
1348 md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512
1349
1350 It is possible to use salted hashes. If so, the Salt must
1351 be provided, encoded in base64. We can obviously have sev‐
1352 eral of these value inside a single <auth> </auth> pair.
1353
1354
1355
1356 pam service = pam-service
1357 If the item pam is part of the auth structure, Yaws will
1358 also try to authenticate the user using "pam" using the pam
1359 service indicated. Usual services are typically found under
1360 /etc/pam.d. Usual values are "system-auth" etc.
1361
1362 pam authentication is performed by an Erlang port program
1363 which is typically installed as suid root by the Yaws
1364 install script.
1365
1366
1367 allow = all | ListOfHost
1368 The allow directive affects which hosts can access an area
1369 of the server. Access can be controlled by IP address or IP
1370 address range. If all is specified, then all hosts are
1371 allowed access, subject to the configuration of the deny
1372 and order directives. To allow only particular hosts or
1373 groups of hosts to access the server, the host can be spec‐
1374 ified in any of the following formats:
1375
1376 A full IP address
1377 allow = 10.1.2.3
1378 allow = 192.168.1.104, 192.168.1.205
1379
1380 A network/netmask pair
1381 allow = 10.1.0.0/255.255.0.0
1382
1383
1384 A network/nnn CIDR specification
1385 allow = 10.1.0.0/16
1386
1387
1388 deny = all | ListOfHost
1389 This directive allows access to the server to be restricted
1390 based on IP address. The arguments for the deny directive
1391 are identical to the arguments for the allow directive.
1392
1393
1394 order = Ordering
1395 The order directive, along with allow and deny directives,
1396 controls a three-pass access control system. The first pass
1397 processes either all allow or all deny directives, as spec‐
1398 ified by the order directive. The second pass parses the
1399 rest of the directives (deny or allow). The third pass
1400 applies to all requests which do not match either of the
1401 first two.
1402
1403 Ordering is one of (Default value is deny,allow):
1404
1405
1406 allow,deny
1407 First, all allow directives are evaluated; at least
1408 one must match, or the request is rejected. Next,
1409 deny directives are evaluated. If any matches, the
1410 request is rejected. Last, any requests which do not
1411 match an allow or a deny directive are denied by
1412 default.
1413
1414
1415 deny,allow
1416 First, all deny directives are evaluated; if any
1417 matched, the request is denied unless it also
1418 matches an allow directive. Any requests which do
1419 not match any allow or deny directives are permit‐
1420 ted.
1421
1422
1423 <opaque> ... </opaque>
1424 This begins and ends an opaque configuration context for this
1425 server, where 'Key = Value' directives can be specified. These
1426 directives are ignored by Yaws (hence the name opaque), but can
1427 be accessed as a list of tuples {Key,Value} stored in the
1428 #sconf.opaque record entry. See also the description of the
1429 start_mod directive.
1430
1431 This mechanism can be used to pass data from a surrounding
1432 application into the individual .yaws pages.
1433
1434
1435
1436
1437
1439 The following example defines a single server on port 80.
1440
1441 logdir = /var/log/yaws
1442 <server www.mydomain.org>
1443 port = 80
1444 listen = 192.168.128.31
1445 docroot = /var/yaws/www
1446 </server>
1447
1448
1449 And this example shows a similar setup but two web servers on the same
1450 IP address.
1451
1452 logdir = /var/log/yaws
1453 <server www.mydomain.org>
1454 port = 80
1455 listen = 192.168.128.31
1456 docroot = /var/yaws/www
1457 </server>
1458
1459 <server www.funky.org>
1460 port = 80
1461 listen = 192.168.128.31
1462 docroot = /var/yaws/www_funky_org
1463 </server>
1464
1465
1466 An example with www-authenticate and no access logging at all.
1467
1468 logdir = /var/log/yaws
1469 <server www.mydomain.org>
1470 port = 80
1471 listen = 192.168.128.31
1472 docroot = /var/yaws/www
1473 access_log = false
1474 <auth>
1475 dir = secret/dir1
1476 realm = foobar
1477 user = jonny:verysecretpwd
1478 user = benny:thequestion
1479 user = ronny:havinganamethatendswithy
1480 </auth>
1481 </server>
1482
1483
1484
1485 An example specifying a user defined module to be called at startup, as
1486 well as some user specific configuration.
1487
1488 <server www.funky.org>
1489 port = 80
1490 listen = 192.168.128.31
1491 docroot = /var/yaws/www_funky_org
1492 start_mod = btt
1493 <opaque>
1494 mydbdir = /tmp
1495 mylogdir = /tmp/log
1496 </opaque>
1497 </server>
1498
1499
1500
1501 An example specifying the GSSAPI/SPNEGO module (authmod_gssapi) to be
1502 used for authentication. This module requires egssapi version 0.1~pre2
1503 or later available at http://www.hem.za.org/egssapi/.
1504
1505 The Kerberos5 keytab is specified as 'keytab = File' directive in
1506 opaque. This keytab should contain the keys of the HTTP service princi‐
1507 pal, 'HTTP/www.funky.org' in this example.
1508
1509 <server www.funky.org>
1510 port = 80
1511 listen = 192.168.128.31
1512 docroot = /var/yaws/www_funky_org
1513 start_mod = authmod_gssapi
1514 <auth>
1515 authmod = authmod_gssapi
1516 dir = secret/dir1
1517 </auth>
1518 <opaque>
1519 keytab = /etc/yaws/http.keytab
1520 </opaque>
1521 </server>
1522
1523
1524
1525 And finally a slightly more complex example with two servers on the
1526 same IP, and one SSL server on a different IP.
1527
1528 When there are more than one server on the same IP, and they have dif‐
1529 ferent names the server must be able to choose one of them if the
1530 client doesn't send a Host: header. Yaws will choose the first one
1531 defined in the conf file.
1532
1533 logdir = /var/log/yaws
1534 max_num_cached_files = 8000
1535 max_num_cached_bytes = 6000000
1536
1537 <server www.mydomain.org>
1538 port = 80
1539 listen = 192.168.128.31
1540 docroot = /var/yaws/www
1541 </server>
1542
1543 <server www.funky.org>
1544 port = 80
1545 listen = 192.168.128.31
1546 docroot = /var/yaws/www_funky_org
1547 </server>
1548
1549 <server www.funky.org>
1550 port = 443
1551 listen = 192.168.128.32
1552 docroot = /var/yaws/www_funky_org
1553 <ssl>
1554 keyfile = /etc/funky.key
1555 certfile = /etc/funky.cert
1556 password = gazonk
1557 </ssl>
1558 </server>
1559
1560
1561
1562 Finally an example with virtual directories, vdirs.
1563
1564 <server server.domain>
1565 port = 80
1566 listen = 192.168.128.31
1567 docroot = /var/yaws/www
1568 arg_rewrite_mod = yaws_vdir
1569 <opaque>
1570 vdir = "/virtual1/ /usr/local/somewhere/notrelated/to/main/docroot"
1571 vdir = "/myapp/ /some/other/path can include/spaces"
1572 vdir = "/icons/ /usr/local/www/yaws/icons"
1573 </opaque>
1574 </server>
1575
1576
1577 The first defined vdir can then be accessed at or under
1578 http://server.domain/virtual1/ or http://server.domain/virtual1
1579
1580
1581
1582
1584 Written by Claes Wikstrom
1585
1587 yaws(1) erl(1)
1588
1589
1590
1591 YAWS.CONF(5)