Provided by: yaws_1.73-2_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.

        tmpdir = Dir
              Yaws generates files when generating dynamic content, i.e.  when
              processing .yaws pages. These files end up in tmpdir. Default is
              $HOME/.yaws

        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.

        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 .

        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.

       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.

        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.

       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>

       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)