Provided by: yaws_1.80-1ubuntu1_i386 bug


       /etc/yaws.conf - Configuration file for the yaws webserver


       Yaws  is  fast  lightweight  webserver.  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.  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  which  contains an access log in
              Common Log Format.

              trace.http - this file  contains  the  HTTP  trace  if  that  is

              auth.log  -  If  configured, all http auth related messages goes

              trace.traffic - this file contains the traffic trace if that  is

              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 command in  the  configuration

        id = String
              It is possible run multiple yaws servers on the same machine. We
              use the id of a yaws server to control it  using  the  different
              ctl commands such as:

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

              To  stop the Yaws server with id "foobar". Each Yaws server will
              write its internals data into a file called  $HOME/.yaws/yaws/ID
              where  ID  the  identity of the server. Yaws also creates a file
              called ${VARDIR}/run/yaws/ctl-${ID} which contain the portnumber
              where the server is listening for control commands.

        include_dir = Directory
              This  directive  adds Directory to the path of directories where
              the erlang compiler seraches for include files. We need  to  use
              this if we want to include .hrl files in our yaws erlang code.

        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 i 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  = traffic | http
              This  enables  traffic or http tracing. Tracing is also possible
              to enable with a command line flag to yaws.

        auth_log  = true | false
              Enable or disable the auth log. Default is true.

        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 M. This value can 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 = Bool
              By  default  the  client  host  IP is not resolved in the access

        fail_on_bind_err = Bool
              Fail completely or not if yaws fails to  bind  a  listen  socket
              Default is true.

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

       php_exe_path = Path
              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

       backwards_compat_parse  = true | false
              Versions  of  Yaws  >  than 1.41 changes the return value of the
              parse_query and  parse_post  functions.  Earlier  versions  used
              {Key,  Val} where Key was an atom. This made Yaws vulnerable for
              DOS attacks. Set this  flag  to  keep  the  old  deprecated  and
              vulnerable   behaviour.  In  versions  >   1.41  the  Key  is  a

       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 wether yaws should pick the first  (as  difined  in  the
              yaws.conf  file)  if no name match or not.  In real live hosting
              scenarios  we  typically  want  this  to  be  false  whereas  in
              testing/development scenarios we want

        use_fdsrv = true | false
              This feature makes it possible to bind to ports < 1024 even when
              we’re not running as  root.  It  requires  the  Jungerl  package
              called  fd_server  to be properly installed.. The feature doen’t
              (yet) work with SSL.

        use_large_ssl_pool = true | false
              SSL servers by default has a pool of pending accept processes.

              An SSL connection might include user interaction.  So while  one
              person  has  a dialog box on the screen asking him to review the
              server’s certificate, no other person is able to establish a new
              connnection  to  the  server unless we run multiple SSL acceptor
              processes.  The default is 8, if we set the  this  configurable,
              we  use  50 pending accept processes. So in environments where a
              large number of slow connectors is expected,  this  configurable
              makes sense.

        subconfig = File
              Load specified config file.

        subconfigdir = Directory
              Load all config file in specified directory.


       Yaws  can virthost several webservers on the same ip address as well as
       several webservers on different ip addresses. The on limitation here is
       that  there can be only one server with ssl enabled per each individual
       ip address.

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

       The following directives are allowed inside a server definition.

       port = Port
              This makes the server listen on Port

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

       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 the same as the default provided by gen_tcp:listen/2,
              which is 5.

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

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

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

       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

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

        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.

       partial_post_size = Integer
              When a yaws file  receives  large  POSTs,  the  amount  of  data
              received in each chunk is determined by the this parameter.  The
              deafult value is 10240.

        dav = true | false
              Turns on the DAV protocol for this server.

       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 ob the form
              is  changed into a request where the docroot for that particular
              request is  set  to  the  directory  ~username/public_html/  The
              default value is false.

       allowed_scripts = [ListOfSuffixes]
              The  allowed  script  types  for  this  server.   Recognized are
              ‘yaws’,   ‘cgi’,   ‘php’.    Default   is   allowed_scripts    =

       tilde_allowed_scripts = [ListOfSuffixes]
              The allowed script types for this server when executing files in
              a users public_html folder  Recognized are ‘yaws’, ‘cgi’, ‘php’.
              Default is tilde_allowed_scripts = [].

       appmods = [ListOfModuleNames]
              If  any  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

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

              Assume    for    example    that     we     have     the     URL
      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.

       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 is a #arg{} record

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

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

              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 formated 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 formated as a string.

              The function must return, {content,MimeType,Cont} or {html, Str}
              or {ehtml, Term}. That data will be shipped to the client.

       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.

       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 syncronize 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
              Make yaws a reverse proxy. The Prefix is a path inside  our  own
              docroot  and the Url argument is an url pointing to a website we
              want to "mount" under the path which is Prefix.

              Example: revproxy = /tmp/foo

              Makes the hyber website appear under /tmp/foo

              It is possible to have multiple reverse proxies inside the  same

              WARNING, this feature is yet not in production quality.

       servername = Name
              If  we’re  virthosting everal 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.

        <ssl>  .... </ssl>
              This begins and ends an SSL configuration for this server.

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

        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

        verify = 1 | 2 | 3
              Specifies  the  level  of verification the server does on clinet
              certs. 1 means nothing, 2 means the  the  server  will  ask  the
              client  for  a  cert but not fail if the client doesn’t supply a
              client cert, 3 means that the  server  requires  the  client  to
              supply a client cert.

        depth = Int
              Specifies the depth of certificate chains the server is prepared
              to follow when verifying client certs.

        password = String
              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 little horrible sublanguage of  its  own.
              It is documented in the ssl man page for "ciphers".

              Ends an SSL definition

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

       Path = [Scheme://]Host[:Port]
              All     accesses    to    Path    will    be    redirected    to
              [Scheme://]Host[:Port]Path.  Scheme and Port  is  optional.  The
              default  is to use the servers scheme and port, rsheme and rport
              will be used if defined. To redirect all references  to  a  site
              use "/" as Path.

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

       dir = Dir
              Makes Dir to be controlled bu WWW-authenticate headers. In order
              for   a  user  to  have  access  to  WWW-Authenticate  controled
              directory, the user must supply a  password.  The  Dir  must  be
              specified relative to the docroot.

       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:out(Arg)
              will be used to deliver the content.

              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 out/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 presented
              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 prefered to have the  users
              in  a  file  called  .yaws_auth  in  the  actual  directory. The
              .yaws_auth file has to be file parseable by file:consult/1

              Each row of the file must contain terms on the form

              {User, Password}.

              Where both User and Password should be strings.  The  .yaws_auth
              file  mechanism  is not (yet) recursive. Thus any subdirectories
              to Dir are not automatically also 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.

              Ends an auth definition

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

        keyfile = File


       The following example defines a single server on port 80.

       logdir = /var/log/yaws
               port = 80
               listen =
               docroot = /var/yaws/www

       And  this  example shows a similar setup but two webservers on the same
       ip address

       logdir = /var/log/yaws
               port = 80
               listen =
               docroot = /var/yaws/www

               port = 80
               listen =
               docroot = /var/yaws/www_funky_org

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

       logdir = /var/log/yaws
               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.

               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

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

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

               port = 80
               listen =
               docroot = /var/yaws/www

               port = 80
               listen =
               docroot = /var/yaws/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)