Provided by: yaws_1.77-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 --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
              logs.

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

        copy_error_log  = true | false
              Enable or disable copying of the  error  log.  When  we  run  in
              embedded mode, there may very well be some other systems process
              that is responsible for writing the errorlog to a  file  whereas
              when  we  run  in  normal standalone mode, we typically want the
              erlang errorlog written to a report.log file.  Default value  is
              true.

       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
              list/string.

       runmod = ModuleName
              At startup yaws will invoke  ModuleName:start()  in  a  separate
              process. It is possible to have several runmods.  This is useful
              if we want to reuse the yaws startup shell script  for  our  own
              application.

        pick_first_virthost_on_nomatch = true | false
              When  Yaws gets a request, it extracts the Host: header from the
              client request to choose a virtual server  amongst  all  servers
              with  the  same  IP/Port  pair.   This  configuration  parameter
              decides 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.

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.

       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 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,cgi].

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

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

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

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

        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.

       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.

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

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

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

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

       And finally a 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>

       Finally an example with virtual directories, vdirs.

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

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

AUTHOR

       Written by Claes Wikstrom

SEE ALSO

       yaws(1) erl(1)

                                                                  YAWS.CONF(5)