YAWS.CONF(5)                     User Commands                    YAWS.CONF(5)

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

       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.

       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

              trace_<YYYYMMDD_hhmmss> - Trace files are written in this subdi-
              rectory, 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  configura-
              tion  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

       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 configu-
              ration 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  maxi-
              mally  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  sec-
              onds.  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.

       use_old_ssl = true | false
              This  re-enables  the  old OTP SSL implementation. By default we
              use the new SSL implementation.

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

       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 connec-
              tion 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

       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  sup-
              ported   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  when  send-
              file is not supported or disabled. The default value is 10240.

       large_file_sendfile = erlang | yaws | disable
              Set  the  version  of sendfile method to use to send large files
              (if supported):

              erlang - use file:sendfile/5, if supported.

              yaws - use Yaws sendfile linked-in driver, if supported.

              disable - do not use any sendfile method, but gen_tcp:send/2.

              The default value is yaws.

       acceptor_pool_size = Integer
              Set the size of the pool of cached acceptor processes. The spec-
              ified  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 log-
              files once they have be renamed/removed.

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

       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 quadru-
              ple form like <Mod, HandlerFunc, WsdlFile, Prefix> which  speci-
              fies   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  =

       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

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

       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

       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 host-
              ing  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

              WARNING:  because  of  a  bug  in  filelib:wildcard/2,  wildcard
              strings are forbidden for Erlang/OTP R15B03 and previous.

       subconfigdir = Directory
              Load  all  config  files  found  in the specified directory. The
              given Directory can be an absolute path or relative to the  con-
              figuration  location.  Hidden  files, starting by a dot, will be

       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     ${PRE-
              FIX}/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

       add_charsets = ListOfCharsets
              Specifies one or more mappings between charsets and file  exten-
              sions.  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.

       Yaws can virthost several web servers on the same IP address as well as
       several web servers  on  different  IP  addresses.  This  includes  SSL

       Each  virtual host is defined within a matching pair of <server Server-
       Name> 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
     Yaws will listen on all local IP addresses on the speci-
              fied port. Default is  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

              send_timeout_close   =   true   |   false    (default:  same  as

       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  dif-
              ferent  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 priv-
              ileged 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
              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 vir-
                   tual server. If the initialization is successful, the func-
                   tion 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 inter-
                   nal NewState.

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

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

              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

              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

       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 brack-
              ets (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

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

              compress_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 syn-
                   onym 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, applica-
                   tion/msword, application/pdf,  application/x-dvi,  applica-
                   tion/javascript,     application/x-javascript.     Multiple
                   mime_types directive 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  struc-

       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

       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  expan-
              sion.  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  syn-
              tax  for  specifying  the  appmods if we don't want our internal
              erlang module names to be exposed in  the  URL  paths.   We  can

                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 mod-
              ule.  Yaws  expects  DispatchModule to export a dispatch/1 func-
              tion. 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

       errormod_401 = Module
              It is possible to set a special module that handles 401 Unautho-
              rized 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

       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 rela-
              tive  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 sub-
              type 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, rewrit-
              ing 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{}

              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

       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  doc-
              root  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

              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:  re-
              write_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 modi-
              fied  copy  of  each  instance  in   its   response.   The   re-
              write_request/2  function should return a tuple of the following

                {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

              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 configur-
              ing  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 "server-
              name" directive. This name doesn't necessarily have  to  be  the
              same as the the name inside <server Name> in certain NAT scenar-
              ios. 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

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

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

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

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

                   If you need to specify an IPv6 address, use  square  brack-

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

              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,

       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

       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  given
              that they all share the same certificate configuration.  In gen-
              eral it is complicated to virthost several SSL  servers  on  the
              same  IP  address  since the certificate is typically bound to a
              domainname in the common name  part  of  the  certificate.   One
              solution  (the  only?)  to this problem is to have a certificate
              with multiple subjectAltNames. See http://wiki.cacert.org/Vhost-

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

              certfile = File
                   Specifies  which  file  contains  the  certificate  for the

              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-Hell-
                   man key exchange is negotiated. If not  specified,  default
                   parameters are used.

              verify = 0 | 1 | 2 | verify_none | verify_peer
                   Specifies  the  level  of  verification  the server does on
                   client certs.  0 means that the server will not ask  for  a
                   cert  (verify_none),  1  means that the server will ask the
                   client for a cert but not fail if the client does not  sup-
                   ply  a  client  cert  (verify_peer,  fail_if_no_peer_cert =
                   false), 2 means that the server requires the client to sup-
                   ply  a  client  cert  (verify_peer,  fail_if_no_peer_cert =

                   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 connec-
                   tion  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,  i.e. we, 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  an erlang term compliant with the
                   output of ssl:cipher_suites().

                   ciphers = "[{dhe_rsa,aes_256_cbc,sha}, \

              secure_renegotiate = true | false
                   Specifies whether to reject renegotiation attempt that does
                   not  live  up to RFC 5746. By default secure_renegotiate is
                   set to false i.e. secure renegotiation will be used if pos-
                   sible but it will fallback to unsecure renegotiation if the
                   peer does not support RFC 5746.

              client_renegotiation = true | false
                   Enables or disables the Erlang/OTP SSL  application  client
                   renegotiation  option. Defaults to true. See the ssl manual
                   page  at  http://www.erlang.org/doc/man/ssl.html  for  more

                   WARNING:  This option was introduced in the SSL application
                   in  Erlang/OTP  18.0,  so  Yaws  ignores  it  for  previous

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

                   WARNING: This option was introduced in the SSL  application
                   in  Erlang/OTP  17.0,  so  Yaws  ignores  it  for  previous

              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.2, 1.1, and 1:

                   protocol_version = tlsv1.2, tlsv1.1, tlsv1

                   WARNING:  Erlang/OTP  R16B01 or higher is required in order
                   to let it work (because of a bug in previous releases).

       <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

                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 redi-
              rected 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  configura-

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

              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 sta-
              tus 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 '='.

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

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

              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 con-
                   figured  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 con-
                   trolled 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  authen-
                   tication.   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
                   Inside this directory, the user User has access if the user
                   supplies  the  password Password in the popup dialogue pre-
                   sented by the browser.  We can obviously  have  several  of
                   these value inside a single <auth> </auth> pair.

                   The  usage  of  User:Password  in the actual config file is
                   deprecated as of release 1.51. It is preferred to have  the
                   users  in a file called .yaws_auth in the actual directory.
                   The .yaws_auth file has to be parseable by file:consult/1.

                   Each row of the file must contain terms in this form:

                       {User, Password}.

                   where both User and Password should be strings.

                   The .yaws_auth file mechanism is recursive, so  any  subdi-
                   rectories  of  Dir  are  also  automatically protected. The
                   .yaws_auth file is never visible in a dir listing.

              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 spec-
                   ified in any of the following formats:

                   A full IP address
                     allow =
                     allow =,

                   A network/netmask pair
                     allow =

                   A network/nnn CIDR specification
                     allow =

              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 spec-
                   ified 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):

                          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

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

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

       The following example defines a single server on port 80.

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

       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 =
               docroot = /var/yaws/www

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

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

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

       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 =
               docroot = /var/yaws/www_funky_org
               start_mod = btt
                       mydbdir = /tmp
                       mylogdir = /tmp/log

       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 princi-
       pal, 'HTTP/www.funky.org' in this example.

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

       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 dif-
       ferent 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 =
               docroot = /var/yaws/www

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

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

       Finally an example with virtual directories, vdirs.

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

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

       Written by Claes Wikstrom

       yaws(1) erl(1)


Valid XHTML 1.0!