Provided by: yaws_1.57-1_i386 bug

NAME

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

DESCRIPTION

       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.

GLOBAL PART

       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
              enabled

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

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

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

        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 -I foobar -s

              To  stop  the  Yaws  server with id "foobar". Only the user that
              started the server called foobar is allowd to stop  and  control
              it.  This  is  achieved  through file permissions on the control
              file which will reside in "/tmp/yaws/foobar/ctl"

              There can never be two yaws servers on  the  same  machine  with
              identical ids.

        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.

        log_resolve_hostname = Bool
              By default the client host IP is  not  resolved  in  the  access
              logs.

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

        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.

       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  deeprecated  and
              vulnerable  behaviour.  I  versions  >  that  1.41  the Key is a
              list/string.

        username = Username
              When running a Yaws server in production, it may  feel  safe  to
              run  yaws as a different user than root. Set this value to a non
              priviliged username on the system, such as "nobody".  Yaws  will
              initially  have  to  run  a  root in order to properly listen to
              priviliged ports .

SERVER PART

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

       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.

       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 all.zip
              entries.

        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.

       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 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/  The
              default value is false.

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

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

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

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

       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 http://yaws.hyber.org

              Makes the hyber website appear under /tmp/foo

              It is possible to have multiple reverse proxies inside the  same
              server.

              WARNING, this feature is yet not in production quality.

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

        keyfile = File
              Specifies   which   file   contains  the  private  key  for  the
              certificate.

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

        cacertfile = File
              File If the server is setup to require client certificates. This
              file  needs  to  contain  all the certificates of the acceptable
              signers for the client certs.

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

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

       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

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

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

       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

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

AUTHOR

       Written by Claes Wikstrom

SEE ALSO

       yaws(1) erl(1)

                                                                  YAWS.CONF(5)