Provided by: yaws_2.1.1+dfsg-1_all bug

NAME

       /etc/yaws/yaws.conf - Configuration file for the Yaws web server

DESCRIPTION

       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.

GLOBAL PART

       logdir = [+]Directory
              All Yaws logs will be written to files in this directory. If specified with +, Yaws
              will  attempt  to  create  the  directory  if  it does not exist. There are several
              different log files written by Yaws:

              report.log - this is a text file that contains  all  error  logger  printouts  from
              Yaws.

              <Host>.access  - 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.)

              <Host>.auth  -  for  each  virtual  host served by Yaws, a file <Host>.auth will be
              written which contains all http auth related messages.

              trace_<YYYYMMDD_hhmmss> - Trace files are written in this subdirectory, suffixed by
              the creation date.

                   trace.<Pid>.http - this file contains the HTTP trace if that is enabled, where
                   <Pid> is the process id handling the TCP connection.

                   trace.<Pid>.traffic - this file contains the traffic trace if that is enabled,
                   where <Pid> is the process id handling the TCP connection.

              Note  that  <Host>.access  and <Host>.auth files will be used only if the directive
              logger_mod is not set or set to yaws_log. The default value for logdir is "."

       ebin_dir = Directory
              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
              "yaws_dir"/examples/ebin

       src_dir = Directory
              This directive defines a Directory as a source 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 include_dir directives are
              used  to  search for includes files. Multiple src_dir directives may be used. There
              is no such directory configured by default.

       id = String
              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:

                # /usr/local/bin/yaws --id foobar --stop

              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
              "default".

       server_signature = String
              This  directive  sets the "Server: " output header to the custom value. The default
              value is "yaws/%VSN%, Yet Another Web Server".

       include_dir = Directory
              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 "yaws_dir"/examples/include.

       max_num_cached_files = Integer
              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 400.

       max_num_cached_bytes = Integer
              This  directive  controls  the  total amount of RAM which can maximally be used for
              cached RAM files. The default value is 1000000, 1 megabyte.

       max_size_cached_file = Integer
              This directive sets a maximum size on the files that are RAM cached by  Yaws.   The
              default value is 8000, 8 kBytes.

       cache_refresh_secs = Integer
              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 30.  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.

       trace  = false | traffic | http
              This enables traffic or http tracing. Tracing is also possible  to  enable  with  a
              command line flag to Yaws. Default is false.

       auth_log  = true | false
              Deprecated and ignored. Now, this target must be set in server part.

       max_connections = nolimit | Integer
              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.

       keepalive_maxuses = nolimit | Integer
              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.

       process_options = undefined | Proplist
              Set process spawn options for client acceptor processes.  Options must be specified
              as a quoted string of either the atom undefined or as a proplist of  valid  process
              options.   The   supported   options   are   fullsweep_after,   min_heap_size,  and
              min_bin_vheap_size, each taking an associated integer value. Other process  options
              are  ignored. The proplist may also be empty. See erlang:spawn_opt/4 for details on
              these options.

       large_file_chunk_size = Integer
              Set the chunk size used by Yaws to send large files. The default value is 10240.

       large_file_sendfile = erlang | disable
              Set the version of sendfile method to use to send large files:

              erlang - use file:sendfile/5.

              disable - use gen_tcp:send/2.

              The default value is erlang.

       acceptor_pool_size = Integer
              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 8. Specifying a value of 0
              effectively disables the process pool.

       log_wrap_size = Integer
              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 1000000, 1 megabyte.
              This value can be changed.
              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.

       log_resolve_hostname = true | false
              By default the client host IP is not resolved in the access logs.

       fail_on_bind_err = true | false
              Fail completely or not if Yaws fails to bind a listen socket Default is true.

       enable_soap = true | false
              If true, a soap server will be started at startup of Yaws.  Default is false.

       soap_srv_mods = ListOfModuleSetting
              If enable_soap is true, a startup Yaws will invoke yaws_soap_srv:setup()  to  setup
              modules set here. ModuleSetting is either a triad like <Mod, HandlerFunc, WsdlFile>
              or a quadruple form like <Mod, HandlerFunc, WsdlFile, Prefix> which  specifies  the
              prefix.  A prefix will be used as argument of yaws_soap_lib:initModel() and then be
              used as a XML namespace prefix.  Note, the WsdlFile here should be an absolute-path
              file in local file systems.

              For example, we can specify

                soap_srv_mods=<Mod1, Handler, Wsdl1> <Mod2, Handler, Wsdl2, Prefix> ...

       php_exe_path = Path
              this  target  is  deprecated  and  useless. use 'php_handler' target in server part
              instead.
              The name of (and possibly path to) the php executable used to interpret php scripts
              (if allowed).  Default is php_exe_path = php-cgi.

       copy_error_log  = true | false
              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 true.

       ysession_mod = Module
              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).

       ysession_cookiegen = Module
              Allows specifying a different Yaws  session  cookie  generator  than  the  built-in
              default.  Module  is  expected  to  provide  a new_cookie/0 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.

       ysession_idle_timeout = Integer
              Controls   Yaws   session   idle   cleanup.   If   a   server  has  been  idle  for
              ysession_idle_timeout milliseconds, check all Yaws sessions  and  remove  any  that
              have timed out. The default ysession_idle_timeout value is 2*60*1000 (2 minutes).

       ysession_long_timeout = Integer
              Controls  Yaws  session periodic cleanup. Every ysession_long_timeout milliseconds,
              check  all  Yaws  sessions  and  remove  any  that  have  timed  out.  The  default
              ysession_long_timeout value is 60*60*1000 (1 hour).

       runmod = ModuleName
              At  startup  Yaws  will  invoke  ModuleName:start()  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.

       pick_first_virthost_on_nomatch = true | false
              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 true.

       keepalive_timeout = TimeInMilliseconds | infinity
              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 30000. The value infinity is legal but not recommended.

       subconfig = File
              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 filelib:wildcard/1 for details. Hidden files, starting by a dot,
              will be ignored. For example:

                subconfig = /etc/yaws/global.conf
                subconfig = /etc/yaws/vhosts/*.conf

              Or, relatively to the configuration location:

                subconfig = global.conf
                subconfig = vhosts/*.conf

       subconfigdir = Directory
              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.

       x_forwarded_for_log_proxy_whitelist = ListOfUpstreamProxyServerIps
              this target is deprecated and will be ignored.

       default_type = MimeType
              Defines the default MIME type to be used where Yaws cannot determine it by its MIME
              types mappings. Default is text/plain.

       default_charset = Charset
              Defines the default charset to be added when a response content-type is text/*.  By
              default, no charset is added.

       mime_types_file = File
              Overrides  the  default  mime.types file included with Yaws. This file must use the
              following format:

                # Lines beginning with a '#' or a whitespace are ignored
                # blank lines are also ignored
                <MIME type> <space separated file extensions>

              The default file is located at ${PREFIX}/lib/yaws/priv/mime.types. You  should  not
              edit this file because it may be replaced when you upgrade your server.

       add_types = ListOfTypes
              Specifies  one  or  more mappings between MIME types and file extensions. More than
              one extension can be assigned to a MIME type. ListOfTypes is defined as follows:

                add_types = <MimeType1, Ext> <MimeType2, Ext1 Ext2 ...> ...

              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
              add_types directives may be used.

       add_charsets = ListOfCharsets
              Specifies one or more mappings between charsets and file extensions. More than  one
              extension can be assigned to a charset. ListOfCharsets is defined as follows:

                add_charsets = <Charset1, Ext> <Charset2, Ext1 Ext2 ...> ...

              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
              add_charsets directives may be used.

       sni = disable | enable | strict
              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  pick_first_virthost_on_nomatch  --  must  include  TLS  as  a  permitted
              protocol.

              If  the  sni  directive  is  set  to enable, 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 strict, 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  must
              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  depth
              configuration variable to 0 to avoid following certificate chains.

              The sni directive is a global one, so if you set it to strict, non-SNI clients will
              be  refused  for  all SSL groups. See require_sni directive from the server part to
              mitigate this requirement.

              Default is disable.

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.

       Each  virtual host is defined within a matching pair of <server ServerName> and </server>.
       The ServerName will be the name of the webserver.

       The following directives are allowed inside a server definition.

       port = Port
              This makes the server listen on Port. Default is 8000.

       listen = IpAddress
              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
              first 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
              127.0.0.1.  Multiple listen directives may be used to specify several addresses  to
              listen on.

       listen_backlog = Integer
              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.

       <listen_opts> ... </listen_opts>
              Defines extra options to be set on  the  listen  socket  and,  by  inheritance,  on
              accepted sockets. See inet:setopts/2 for details. Supported options are:

              buffer = Integer (default: same as inet:setopts/2)

              delay_send = true  | false  (default: same as inet:setopts/2)

              linger = Integer | false  (default: same as inet:setopts/2)

              nodelay = true | false  (default: same as inet:setopts/2)

              priority = Integer (default: same as inet:setopts/2)

              sndbuf = Integer (default: same as inet:setopts/2)

              recbuf = Integer (default: same as inet:setopts/2)

              send_timeout = Integer | infinity (default: same as inet:setopts/2)

              send_timeout_close = true | false  (default: same as inet:setopts/2)

       server_signature = String
              This  directive sets the "Server: " output header to the custom value and overloads
              the global one for this virtual server.

       subconfig = File
              Same as subconfig directive of the global part, but here files should only  contain
              directives allowed in the server part.

       subconfigdir = Directory
              Same  as  subconfigdir  directive  of  the  global part, but here files should only
              contain directives allowed in server part.

       rhost = Host[:Port]
              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).

       rmethod = http | https
              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.

       auth_log  = true | false
              Enable or disable the auth log for this virtual server. Default is true.

       access_log = true | false
              Setting this directive to false turns off traffic logging for this virtual  server.
              The default value is true.

       logger_mod = Module
              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.
              This module must implement the behaviour yaws_logger. Default value is yaws_log.

              The following functions should be exported:

              Module:open_log(ServerName, Type, LogDir)
                   When  Yaws is started, this function is called for this virtual server. If the
                   initialization is successful, the function must return {true,State} and if  an
                   error occurred, it must return false.

              Module:close_log(ServerName, Type, State)
                   This function is called for this virtual server when Yaws is stopped.

              Module:wrap_log(ServerName, Type, State, LogWrapSize)
                   This  function is used to rotate log files. It is regularly called by Yaws and
                   must return the possibly updated internal NewState.

              Module:write_log(ServerName, Type, State, Infos)
                   When it needs to log a message, Yaws will call this  function.  The  parameter
                   Infos is {Ip,Req,InHdrs,OutHdrs,Time} for an access log and {Ip,Path,Item} for
                   an auth log, where:

                   Ip - IP address of the accessing client (as a tuple).

                   Req - the HTTP method, URI path,  and  HTTP  version  of  the  request  (as  a
                   #http_request{} record).

                   InHdrs  -  the  HTTP  headers  which  were  received from the WWW client (as a
                   #headers{} record).

                   OutHdrs - the HTTP headers sent to the WWW client (as a #outh{} record)

                   Path - the URI path of the request (as a string).

                   Item - the result of an authentication  request.  May  be  {ok,User},  403  or
                   {401,Realm}.

                   Time - The time taken to serve the request, in microseconds.

              For  all  of  these callbacks, ServerName is the virtual server's name, Type is the
              atom access or auth and State is the internal state of the logger.

       shaper = Module
              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 yaws_shaper.

              There is no such module configured by default.

       dir_listings = true | true_nozip | false
              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 false.

       extra_cgi_vars = .....
              Add additional CGI or FastCGI variables. For example:

                <extra_cgi_vars dir='/path/to/some/scripts'>
                  var = val
                  ...
                </extra_cgi_vars>

       statistics  = true | false
              Turns on/off statistics gathering for a virtual server. Default is false.

       fcgi_app_server = Host:Port
              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.

       fcgi_trace_protocol = true | false
              Enable  or  disable  tracing  of  FastCGI  protocol  messages as info log messages.
              Disabled by default.

       fcgi_log_app_error = true | false
              Enable or disable logging of application error messages (output to stderr and  non-
              zero exit value). Disabled by default.

       deflate = true | false
              Turns on or off deflate compression for a server. Default is false.

       <deflate> ... </deflate>
              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.

              min_compress_size = nolimit | Integer
                   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
                   nolimit.

              compression_level = none | default | best_compression | best_speed | 0..9
                   Defines  the  compression  level to be used. 0 (none), gives no compression at
                   all, 1 (best_speed) gives best  speed  and  9  (best_compression)  gives  best
                   compression. The default value is default.

              window_size = 9..15
                   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 15.

              mem_level = 1..9
                   Specifies  how  much  memory  should be allocated for the internal compression
                   state. mem_level=1 uses minimum memory but is  slow  and  reduces  compression
                   ratio; mem_level=9 uses maximum memory for optimal speed. The default value is
                   8.

              strategy = default | filtered | huffman_only
                   This parameter is used to tune the compression algorithm. See  zlib(3erl)  for
                   more details on the strategy parameter. The default value is default.

              use_gzip_static = true | false
                   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 false.

              mime_types = ListOfTypes | defaults | all
                   Restricts the deflate compression to particular MIME types. The special  value
                   all  enable  it  for  all  types  (It  is a synonym of `*/*'). MIME types into
                   ListOfTypes must have the form  `type/subtype'  or  `type/*'  (indicating  all
                   subtypes of that type). Here is an example:

                     mime_types = default image/*
                     mime_types = application/xml application/xhtml+xml application/rss+xml

                   By  default,  the  following  MIME  types are compressed (if deflate is set to
                   true):   text/*,   application/rtf,    application/msword,    application/pdf,
                   application/x-dvi,  application/javascript. Multiple mime_types directives can
                   be used.

       docroot = Directory ...
              This makes the server serve all its content from Directory.
              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.

       auth_skip_docroot = true | false
              If true, the docroot will not be searched for .yaws_auth files. This is useful when
              the docroot is quite large and the time to  search  it  is  prohibitive  when  Yaws
              starts up. Defaults to false.

       partial_post_size = Integer | nolimit
              When a Yaws file receives large POSTs, the amount of data received in each chunk is
              determined by this parameter.  The default value is 10240. Setting it to nolimit is
              potentially dangerous.

       dav = true | false
              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  false.  The  socket  read timeout is supplied by the keepalive_timeout
              setting.  If the read is not done within the timeout, the POST will fail.

       tilde_expand = true|false
              If this value is set to false Yaws will never do tilde expansion.  The  default  is
              false.   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/.

       allowed_scripts = ListOfSuffixes
              The  allowed  script  types for this server.  Recognized are `yaws', `cgi', `fcgi',
              `php'.  Default is allowed_scripts = yaws php cgi fcgi.

              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.

       tilde_allowed_scripts = ListOfSuffixes
              The allowed  script  types  for  this  server  when  executing  files  in  a  users
              public_html  folder  Recognized  are  `yaws',  `cgi',  `fcgi',  `php'.   Default is
              tilde_allowed_scripts = i.e. empty

       index_files = ListOfResources
              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
              index_files = index.yaws index.html index.php.

       appmods = ListOfModuleNames
              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

                appmods = <Path1, Module1> <Path2, Modules2> ...

              Assume       for       example       that       we       have        the        URL
              http://www.hyber.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.
              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:

                appmods = </, myapp exclude_paths icons js top/static>

              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.

       dispatchmod = DispatchModule
              Set DispatchModule as a server-specific request dispatching  module.  Yaws  expects
              DispatchModule  to  export  a dispatch/1 function. When it receives a request, Yaws
              passes an #arg{} record to the dispatch module's dispatch/1 function, which returns
              one of the following atom results:

                   done  -  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

                   closed - same as done but the DispatchModule also closed the connection

                   continue  -  the  dispatch  module  has decided not to handle the request, and
                   instead wants Yaws to perform its regular request dispatching

              Note that when DispatchModule 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.

       errormod_404 = Module
              It is possible to set a special module that handles 404  Not  Found  messages.  The
              function Module:out404(Arg, GC, SC) will be invoked. The arguments are

                   Arg - a #arg{} record

                   GC - a #gconf{} record (defined in yaws.hrl)

                   SC - a #sconf{} record (defined in yaws.hrl)

              The function can and must do the same things that a normal out/1 does.

       errormod_401 = Module
              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
              Module:out401(Arg, Auth, Realm) will be invoked. The arguments are

                   Arg - a #arg{} record

                   Auth - a #auth{} record

                   Realm - a string

              The function can and must do the same things that a normal out/1 does.

       errormod_crash = Module
              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.
              The  function  Module:crashmsg(Arg,  SC,  Str)  will be called. The Str is the real
              crash message formatted as a string.
              The function must return, {content,MimeType,Cont} or {html, Str} or {ehtml,  Term}.
              That data will be shipped to the client.

       expires = ListOfExpires
              Controls  the  setting  of the Expires HTTP header and the max-age directive of the
              Cache-Control 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:

                expires = <MimeType1, access+Seconds> <MimeType2, modify+Seconds> <MimeType3, always> ...

              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:

                expires = <image/gif, access+2592000> <image/png, access+2592000>
                expires = <image/jpeg, access+2592000> <text/css, access+2592000>
                expires = <text/*, always>

              and here is another:

                expires = <*/*, always>

       arg_rewrite_mod = Module
              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
              arg_rewrite/1 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  yaws_vdir 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  opaque + vdir elements to instruct the yaws_vdir module what paths to
              rewrite.

       start_mod = Module
              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.

       revproxy = Prefix Url [intercept_mod Module]
              Make Yaws a reverse proxy. Prefix is a path inside our own docroot and Url argument
              is  a  URL  pointing  to  a  website we want to "mount" under the Prefix path. This
              example:

                revproxy = /tmp/foo http://yaws.hyber.org

              makes the hyber website appear under /tmp/foo.

              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 intercept_mod  keyword
              followed by Module, which should be the name of your interception module.

              An  interception  module is expected to export two functions: rewrite_request/2 and
              rewrite_response/2. The two arguments passed to rewrite_request/2  function  are  a
              #http_request{} record and a #headers{} record, whereas rewrite_response/2 function
              takes a #http_response{}  record  and  also  a  #headers{}  record.  You  can  find
              definitions  for  these record types in the yaws_api.hrl 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 rewrite_request/2
              function should return a tuple of the following form:

                {ok, #http_request{}, #headers{}}

              and the  rewrite_response/2  function  should  similarly  return  a  tuple  of  the
              following form:

                {ok, #http_response{}, #headers{}}

              A #headers{} record can easily be manipulated in an interceptor using the functions
              listed below:

                yaws_api:set_header/2, yaws_api:set_header/3
                yaws_api:get_header/2, yaws_api:get_header/3
                yaws_api:delete_header/2

              Any failures in your interception module's functions will  result  in  HTTP  status
              code 500, indicating an internal server error.

       fwdproxy = true|false
              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.

       servername = Name
              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.

       serveralias = ListOfNames

              This directive sets the alternate names for a virtual  host.  A  server  alias  may
              contain wildcards:
                    '*' matches any sequence of zero or more characters
                    '?' matches one character unless that character is a period ('.')

              Multiple serveralias directives may be used. Here is an example:

                <server server.domain.com>
                  serveralias = server server2.domain.com server2
                  serveralias = *.server.domain.com *.server?.domain.com
                  ...
                </server>

       php_handler = <Type, Spec>
              Set handler to interpret .php files. It can be one of the following definitions:

              php_handler  =  <cgi,  Filename>  -  The  name  of  (and  possibly path to) the php
              executable used to interpret php scripts (if allowed).

              php_handler = <fcgi, Host:Port> - Use the specified  fastcgi  server  to  interpret
              .php files (if allowed).

                   Yaws does not start the PHP interpreter in fastcgi mode for you. To run PHP in
                   fastcgi mode, call it with the -b option. For example:

                     php5-cgi -b '127.0.0.1:54321'

                   This starts a php5 in fastcgi mode listening on the local  network  interface.
                   To make use of this PHP server from Yaws, specify:

                     php_handler = <fcgi, 127.0.0.1:54321>

                   If you need to specify an IPv6 address, use square brackets:

                     php_handler = <fcgi, [::1]:54321>

                   The  PHP  interpreter  needs read access to the files it is to serve. Thus, if
                   you run it in a different security context than Yaws itself, make sure it  has
                   access to the .php files.
                   Please  note  that  anyone  who  is  able to connect to the php fastcgi server
                   directly can use it to read any file to which it has read access.  You  should
                   consider  this  when  setting  up  a  system  with  several mutually untrusted
                   instances of php.

              php_handler = <extern, Module:Function | Node:Module:Function> -  Use  an  external
              handler, possibly on another node, to interpret .php files (if allowed).

                   To  interpret  a  .php file, the function Module:Function(Arg) will be invoked
                   (Evaluated inside a rpc call if a Node is specified), where Arg is  an  #arg{}
                   record.
                   The function must do the same things that a normal out/1 does.

              Default value is <cgi, "/usr/bin/php-cgi">.

       phpfcgi = Host:Port
              this target is deprecated. use 'php_handler' target in server part instead.
              Using this directive is the same as: php_handler = <fcgi, Host:Port>.

       default_type = MimeType
              Overloads the global default_type value for this virtual server.

       default_charset = Charset
              Overloads the global default_charset value for this virtual server.

       mime_types_file = File
              Overloads the global mime_type_file value for this virtual server. Mappings defined
              in File will not overload those defined by add_types directives in the global part.

       add_types = ListOfTypes
              Overloads the global add_types values for this virtual  server.  If  a  mapping  is
              defined  in  the  global  part and redefined in a server part using this directive,
              then it is replaced. Else it is kept.

       add_charsets = ListOfCharsets
              Overloads the global add_charsets values for this virtual server. If a  mapping  is
              defined  in  the  global  part and redefined in a server part using this directive,
              then it is replaced. Else it is kept.

       nslookup_pref = [inet | inet6]
              For fcgi servers and revproxy URLs, define  the  name  resolution  preference.  For
              example, to perform only IPv4 name resolution, use [inet]. To do both IPv4 and IPv6
              but try IPv6 first, use [inet6, inet].  Default value is [inet].

       <ssl> ... </ssl>

              This begins and ends an  SSL  configuration  for  this  server.  It's  possible  to
              virthost several SSL servers on the same IP/Port. If SNI support is disabled or not
              supported, they must share the same certificate configuration. In  this  situation,
              it  is  complicated  to  virthost several SSL servers on the same IP/Port since the
              certificate is typically bound to a domainname in  the  common  name  part  of  the
              certificate.  One  solution  to this problem is to have a certificate with multiple
              subjectAltNames. If SNI support is enabled, SSL servers on  the  same  IP/Port  can
              have their own SSL configuration with a different SSL certificate for each one. See
              the global sni directive.

              The SNI support was introduced in the SSL application in Erlang/OTP 18.0. It is  an
              extension  to  the  TLS protocol (RFC 4366), which allows the client to include the
              requested hostname in the first message of its SSL handshake.

              See also  http://wiki.cacert.org/VhostTaskForce#Interoperability_Test  for  browser
              compatibility.

              keyfile = File
                   Specifies  which  file  contains  the  private key for the certificate. If not
                   specified then the certificate file will be used.

              certfile = File
                   Specifies which file contains the certificate for the server.

              cacertfile = File
                   A file containing trusted certificates to use during client authentication and
                   to  use  when  attempting  to build the server certificate chain.  The list is
                   also used in the list of acceptable client CAs passed to  the  client  when  a
                   certificate is requested.

              dhfile = File
                   A  file  containing  PEM-encoded  Diffie-Hellman  parameters to be used by the
                   server if a cipher suite using Diffie-Hellman key exchange is  negotiated.  If
                   not specified, default parameters are used.

              verify = verify_none | verify_peer
                   Specifies  the  level of verification the server does on client certs. Setting
                   verify_none means that the x509 validation will  be  skipped  (no  certificate
                   request  is  sent to the client), verify_peer means that a certificate request
                   is sent to the client (x509 validation is performed.

                   You might want to use fail_if_no_peer_cert in combination with verify_peer.

              fail_if_no_peer_cert = true | false
                   If verify is set to verify_peer and set to true the connection  will  fail  if
                   the  client does not send a certificate (i.e. an empty certificate). If set to
                   false the server will fail only if an  invalid  certificate  is  supplied  (an
                   empty certificate is considered valid).

              depth = Int
                   Specifies  the  depth  of  certificate chains the server is prepared to follow
                   when verifying client certs. For the OTP new SSL  implementation  it  is  also
                   used  to  specify  how  far the server (Yaws in our case) shall follow the SSL
                   certificates we present to the clients. Hence,  using  self-signed  certs,  we
                   typically need to set this to 0.

              password = String
                   If  the  private  key  is  encrypted on disc, this password is the 3DES key to
                   decrypt it.

              ciphers = String
                   This string specifies the SSL cipher string. The  syntax  of  the  SSL  cipher
                   string    is    a    4-tuple   representation   of   the   map   returned   by
                   ssl:cipher_suites/2,3: {#{key_exchange}, #{cipher}, #{mac}, #{prf}}.

                   ciphers = "[{dhe_rsa,aes_256_cbc,sha,default_prf}, \
                               {dhe_dss,aes_256_cbc,sha,default_prf}]"

                   In older versions of Yaws, a cipher tuple lacked the #{prf} element. When Yaws
                   reads a cipher of the old format from configuration, it attempts to convert it
                   to a 4-tuple by adding default_prf for the #{prf} element. Be aware that  this
                   may  not  work  for all ciphers; if it fails, manual intervention is needed to
                   properly configure the ciphers in the new format.

              eccs = String
                   This string specifies the supported Elliptic  Curve  Cryptography  (ECC).   It
                   must  be  a  subset  of ssl:eccs().  For PCI DSS compliance (which is the main
                   reason why you would want to change this), set it on a single line to:

                   eccs = "[sect571r1, sect571k1, secp521r1, brainpoolP512r1, \
                            sect409k1, sect409r1, brainpoolP384r1, secp384r1, \
                            sect283k1, sect283r1, brainpoolP256r1, secp256k1, \
                            secp256r1, sect239k1, xsect233k1, sect233r1, \
                            secp224k1, secp224r1]"

              secure_renegotiate = true | false | undefined
                   Specifies whether to reject renegotiation attempt that does not live up to RFC
                   5746. By default secure_renegotiate is set to false for protocol versions that
                   support it, i.e. secure renegotiation will be used if  possible  but  it  will
                   fallback  to unsecure renegotiation if the peer does not support RFC 5746. Set
                   it to undefined to use the ssl module default setting  to  avoid  errors  with
                   protocol  versions  that  don't  support it, such as TLS version 1.3. For more
                   details, see the ssl manual page at http://www.erlang.org/doc/man/ssl.html

              client_renegotiation = true | false | undefined
                   Enables or  disables  the  Erlang/OTP  SSL  application  client  renegotiation
                   option.  Defaults  to  true  for  protocol versions that support it. Set it to
                   undefined to use the ssl module default setting to avoid errors with  protocol
                   versions that don't support it, such as TLS version 1.3. For more details, see
                   the ssl manual page at http://www.erlang.org/doc/man/ssl.html

              honor_cipher_order = true | false
                   If true (the default), use the server's preference for  cipher  selection.  If
                   false, use the client's preference.

              protocol_version = ProtocolList
                   Specifies  the  list  of  SSL  protocols  that  will be supported. If not set,
                   defaults to all  protocols  supported  by  the  erlang  ssl  application.  For
                   example, to support only TLS versions 1.3, 1.2, 1.1, and 1:

                   protocol_version = tlsv1.3, tlsv1.2, tlsv1.1, tlsv1

              require_sni = true | false
                   If  true,the  server  will  reject  non-SNI  clients  and clients providing an
                   unknown SNI hostname (this last remark is only relevant for the first  virtual
                   server  of  a SSL group). This directive is ignored if SNI support is disabled
                   (or not supported).

                   Default is false.

       <redirect> ... </redirect>
              Defines a redirect mapping. The following items are allowed within a matching  pair
              of <redirect> and </redirect> delimiters.

              We can have a series of redirect rules in one of the formats below:

                Path = URL
                Path = code
                Path = code URL

              Path  must  be  an  url-decoded  path  beginning  with a slash. URL may be either a
              relative URL (a path beginning with a slash), or an  absolute  URL.  In  the  first
              case, the scheme:hostname:port of the current server will be added. All accesses to
              Path will be redirected to URL/Path (or  scheme:hostname:port/URL/Path  if  URL  is
              relative).  URL must be url-encoded. Note that the original path is appended to the
              redirected URL.

              For example, assume we have the following redirect configuration:

                <redirect>
                  /foo = http://www.mysite.org/zapp
                  /bar = /tomato.html
                </redirect>

              Assuming this config resides on a site called http://abc.com, we have the following
              redirects:

                http://abc.com/foo -> http://www.mysite.org/zapp/foo
                http://abc.com/foo/test -> http://www.mysite.org/zapp/foo/test
                http://abc.com/bar -> http://abc.com/tomato.html/bar
                http://abc.com/bar/x/y/z -> http://abc.com/tomato.html/bar/x/y/z

              By  default,  Yaws will perform a 302 redirect. The HTTP status code can be changed
              using the code parameter. Note that the status code must be known by Yaws.

              •  For 3xx status codes, the URL parameter must be present  and  will  be  used  to
                 build the new location.

              •  For  other  status  codes  (1xx,  2xx,  4xx  and 5xx), it can be omitted. In the
                 absence of URL, Yaws will return a generic response with  the  specified  status
                 code.

              •  Otherwise,  the  URL  parameter  must  be  a  relative  URL  and will be used to
                 customize the response.

              Sometimes we do not want to have the original path appended to the redirected path.
              To get that behaviour we specify the config with '==' instead of '='.

                <redirect>
                  /foo == http://www.mysite.org/zapp
                  /bar = /tomato.html
                </redirect>

              Now   a   request   for   http://abc.com/foo/x/y/z   simply   gets   redirected  to
              http://www.mysite.org/zapp. This is typically used when we  simply  want  a  static
              redirect at some place in the docroot.

              When we specify a relative URL as the target for the redirect, the redirect will be
              to the current http(s) server.

       <auth> ... </auth>
              Defines an auth structure. The following items are allowed within a  matching  pair
              of <auth> and </auth> delimiters.

              docroot = Docroot
                   If  a docroot is defined, this auth structure will be tested only for requests
                   in the specified docroot. No docroot configured means all  docroots.   If  two
                   auth  structures  are defined, one with a docroot and one with no docroot, the
                   first of both overrides the second one for requests in the configured docroot.

              dir = Dir
                   Makes Dir to be controlled by WWW-authenticate headers. In order for a user to
                   have  access  to WWW-Authenticate controlled directory, the user must supply a
                   password. The Dir must be specified relative to the docroot.  Multiple dir can
                   be used. If no dir is set, the default value, "/", will be used.

              realm = Realm
                   In  the  directory  defined  here,  the  WWW-Authenticate Realm is set to this
                   value.

              authmod = AuthMod
                   If an auth module is defined then AuthMod:auth(Arg, Auth) will be  called  for
                   all  access  to the directory. The auth/2 function should return one of: true,
                   false, {false, Realm}, {appmod, Mod}.  If {appmod, Mod}  is  returned  then  a
                   call  to  Mod:out401(Arg, Auth, Realm) will be used to deliver the content. If
                   errormod_401 is defined, the call to Mod will  be  ignored.  (Mod:out(Arg)  is
                   deprecated).

                   This can, for example, be used to implement cookie authentication.  The auth()
                   callback would check if a valid cookie header is  present,  if  not  it  would
                   return  {appmod,  ?MODULE}  and the out401/1 function in the same module would
                   return {redirect_local, "/login.html"}.

              user = User:Password | "User:{Algo}Hash" | "User:{Algo}$Salt$Hash"
                   Inside this directory, the user User has  access  if  the  user  supplies  the
                   password  Password  in the popup dialogue presented by the browser. It is also
                   possible to provide a hashed password, encoded in base64. In  that  case,  the
                   algorithm  used  to  hash  the  password  must be set. Algo must be one of the
                   following algorithms:

                       md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512

                   It is possible to use salted hashes. If so, the Salt must be provided, encoded
                   in base64. We can specify multiple users inside a single <auth> </auth> pair.

              pam service = pam-service
                   If  the  item  pam  is  part  of  the  auth  structure,  Yaws will also try to
                   authenticate the user using "pam"  using  the  pam  service  indicated.  Usual
                   services  are typically found under /etc/pam.d. Usual values are "system-auth"
                   etc.

                   pam authentication is performed by an Erlang port program which  is  typically
                   installed as suid root by the Yaws install script.

              allow = all | ListOfHost
                   The  allow  directive  affects  which  hosts can access an area of the server.
                   Access can be controlled by  IP  address  or  IP  address  range.  If  all  is
                   specified,  then all hosts are allowed access, subject to the configuration of
                   the deny and order directives. To allow only particular  hosts  or  groups  of
                   hosts  to access the server, the host can be specified in any of the following
                   formats:

                   A full IP address
                     allow = 10.1.2.3
                     allow = 192.168.1.104, 192.168.1.205

                   A network/netmask pair
                     allow = 10.1.0.0/255.255.0.0

                   A network/nnn CIDR specification
                     allow = 10.1.0.0/16

              deny = all | ListOfHost
                   This directive allows access to the  server  to  be  restricted  based  on  IP
                   address.  The  arguments for the deny directive are identical to the arguments
                   for the allow directive.

              order = Ordering
                   The order directive, along with allow and deny directives, controls  a  three-
                   pass  access  control system. The first pass processes either all allow or all
                   deny directives, as specified by the order directive. The second  pass  parses
                   the  rest  of  the  directives  (deny or allow). The third pass applies to all
                   requests which do not match either of the first two.

                   Ordering is one of (Default value is deny,allow):

                   allow,deny
                          First, all allow directives are evaluated; at least one must match,  or
                          the  request  is  rejected. Next, deny directives are evaluated. If any
                          matches, the request is rejected. Last, any requests which do not match
                          an allow or a deny directive are denied by default.

                   deny,allow
                          First,  all  deny directives are evaluated; if any matched, the request
                          is denied unless it also matches an allow directive. Any requests which
                          do not match any allow or deny directives are permitted.

       <opaque> ... </opaque>
              This  begins and ends an opaque configuration context for this server, where 'Key =
              Value' directives can be specified. These directives are ignored by Yaws (hence the
              name  opaque),  but  can  be accessed as a list of tuples {Key,Value} stored in the
              #sconf.opaque record entry. See also the description of the start_mod directive.

              This mechanism can be used to pass data from a  surrounding  application  into  the
              individual .yaws pages.

       strip_undefined_bindings = true | false
              Change  the behavior of the {bindings, [...]} directive to treat all undefined keys
              found in returned out/1 content as if  they  were  defined  with  an  empty  value,
              resulting  in  all  undefined  bindings  effectively being stripped out of returned
              content. By default,  strip_undefined_bindings  is  false,  which  means  undefined
              bindings are ignored and their text is left as is in returned content.

              This  setting applies only for out/1 content, not to static pages or other returned
              content.

       <extra_response_headers> ... </extra_response_headers>
              This begins and ends a configuration context for extra response  headers  for  this
              server,  where  directives  for  adding  headers,  erasing headers, and modules for
              handling extra response headers can be specified as follows:

                   add Hdr = Value
                          Add Hdr with value Value to the response,  but  only  if  the  response
                          status code is one of these values:

                               200 OK
                               201 Created
                               204 No Content
                               206 Partial Content
                               301 Moved Permanently
                               302 Found
                               303 See Other
                               304 Not Modified
                               307 Temporary Redirect
                               308 Permanent Redirect

                   For any other status code, Hdr is not added.

                   always add Hdr = Value
                          Unconditionally add Hdr with value Value to the response, regardless of
                          the response status code.

                   erase Hdr
                          Remove Hdr and its associated value from the response.

                   extramod = Module
                          Specifies a module to call to  process  extra  response  headers.  Yaws
                          calls Module:extra_response_headers/3 passing the following arguments:

                               Response headers
                                      An Erlang map holding the response headers with header name
                                      strings as keys and strings as header values

                               Arg    An #arg{} record representing the request. In  cases  where
                                      an extramod module is called following the invocation of an
                                      appmod, the #arg{} record field appmod_name  indicates  the
                                      name  of the appmod that serviced the request, allowing the
                                      extramod to return extra HTTP headers appropriate for  that
                                      appmod.

                               {StatusCode,Version}
                                      A  tuple  where  StatusCode is the numeric HTTP status code
                                      for the response, and Version is  a  tuple  specifying  the
                                      HTTP version, e.g. {1,1} for HTTP 1.1.

                   The Module:extra_response_headers/3 function should return either the original
                   header map or a modified map  where  headers  have  been  added,  changed,  or
                   deleted. Added headers are not subject to the status code restrictions for the
                   add  extra  response   header   directive,   but   the   function   can   call
                   yaws_api:http_extra_response_headers_add_status_codes/0  to  retrieve the list
                   of the status codes for which adding headers is normally allowed.

                   For response headers that can have  multiple  settings,  such  as  Set-Cookie,
                   multiple  values  can be specified in the extra response header map by using a
                   value of {multi, [Value]} where [Value] is  a  list  of  one  or  more  header
                   values.  The  Set-Cookie  header  is  a  standard  special case for which Yaws
                   converts a multi header into a separate Set-Cookie header for each value;  for
                   other  headers,  Yaws converts a multi header into a single HTTP header with a
                   comma-separated value.

       Note that extra response headers do not  apply  to  responses  returned  directly  by  any
       DispatchModule.

       options_asterisk_methods = Methods
              Setting  options_asterisk_methods  to  a comma-separated list of HTTP Methods makes
              Yaws respond to an OPTIONS request that specifies a literal * as the target with  a
              200  OK  status  and  an  Allow  header  listing  the  specified  Methods.  If  the
              configuration does not explicitly specify options_asterisk_methods,  Yaws  defaults
              to  responding  to  OPTIONS  *  requests  with  a 200 OK status and an Allow header
              listing these HTTP methods:

                GET, HEAD, POST, PUT, DELETE, OPTIONS

              RFC 7231 section 4.3 lists the standard HTTP method names:

                GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE

              An options_asterisk_methods setting can include any of these HTTP method  names  as
              well  as  PATCH. PATCH is not mentioned in RFC 7231 but Yaws supports it. Yaws does
              not implement CONNECT, but it supports it in options_asterisk_methods because  it's
              possible to implement support for it using a dispatchmod.

              If  options_asterisk_methods  is  set to an empty value, Yaws responds to OPTIONS *
              requests with status 400 Bad Request.

EXAMPLES

       The following example defines a single server on port 80.

           logdir = /var/log/yaws
           <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
           </server>

       And this example shows a similar setup but two web servers on the same IP address.

           logdir = /var/log/yaws
           <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
           </server>

           <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
           </server>

       An example with www-authenticate and no access logging at all.

           logdir = /var/log/yaws
           <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
               access_log = false
               <auth>
                   dir = secret/dir1
                   realm = foobar
                   user = jonny:verysecretpwd
                   user = benny:thequestion
                   user = ronny:havinganamethatendswithy
              </auth>
           </server>

       An example specifying a user defined module to be called at startup, as well as some  user
       specific configuration.

           <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
               start_mod = btt
               <opaque>
                       mydbdir = /tmp
                       mylogdir = /tmp/log
               </opaque>
           </server>

       An   example   specifying  the  GSSAPI/SPNEGO  module  (authmod_gssapi)  to  be  used  for
       authentication. This module requires  egssapi  version  0.1~pre2  or  later  available  at
       http://www.hem.za.org/egssapi/.

       The  Kerberos5  keytab  is  specified  as 'keytab = File' directive in opaque. This keytab
       should contain the keys of  the  HTTP  service  principal,  'HTTP/www.funky.org'  in  this
       example.

           <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
               start_mod = authmod_gssapi
               <auth>
                       authmod = authmod_gssapi
                       dir = secret/dir1
               </auth>
               <opaque>
                       keytab = /etc/yaws/http.keytab
               </opaque>
           </server>

       And  finally  a slightly more complex example with two servers on the same IP, and one SSL
       server on a different IP.

       When there are more than one server on the same IP, and  they  have  different  names  the
       server  must be able to choose one of them if the client doesn't send a Host: header. Yaws
       will choose the first one defined in the conf file.

           logdir = /var/log/yaws
           max_num_cached_files = 8000
           max_num_cached_bytes = 6000000

           <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
           </server>

           <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
           </server>

           <server www.funky.org>
               port = 443
               listen = 192.168.128.32
               docroot = /var/yaws/www_funky_org
               <ssl>
                  keyfile = /etc/funky.key
                  certfile = /etc/funky.cert
                  password = gazonk
               </ssl>
           </server>

       Finally an example with virtual directories, vdirs.

           <server server.domain>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
               arg_rewrite_mod = yaws_vdir
               <opaque>
                   vdir = "/virtual1/ /usr/local/somewhere/notrelated/to/main/docroot"
                   vdir = "/myapp/ /some/other/path can include/spaces"
                   vdir = "/icons/  /usr/local/www/yaws/icons"
               </opaque>
           </server>

       The first defined vdir can then be accessed at or under http://server.domain/virtual1/  or
       http://server.domain/virtual1

AUTHOR

       Written by Claes Wikstrom

SEE ALSO

       yaws(1) erl(1)

                                                                                     YAWS.CONF(5)