Provided by: mathopd_1.5p6-1_i386 bug

NAME

       mathopd.conf - Configuration file for the Mathopd HTTP server

DESCRIPTION

       /etc/mathopd.conf  is the default configuration file for the mathopd(8)
       HTTP server.

       A configuration file for mathopd consists  of  zero  or  more  ’items’,
       possibly mixed with comment text.

       An  item  is a configuration keyword followed by zero or one arguments,
       as indicated by the syntax below.

       I have taken the liberty of introducing some meta-concepts to make  the
       syntax more readable.

       When  you  read  the  phrase  "X-block",  please  replace  it  with the
       following.

           X-block: "{" X-items "}"

           X-items:
             <nothing>
             X-item X-items

       Keywords and arguments are separated by whitespace,  that  is,  spaces,
       tab characters, carriage returns, or line feeds.

       A  string  is anything enclosed in double quotes ("). The quotes can be
       omitted if the string is actually just a single word.  To  include  the
       double  quote  character  itself  in a string, precede the quote with a
       backslash (’´).

       An integer is represented using the normal  ’C’  conventions:  ’0x’  in
       front indicates a hexadecimal number, ’0’ in front indicates octal.

       The  ’#’  character,  when  not used inside a string, is considered the
       beginning of comment  text.  A  comment  lasts  until  the  next  line.
       Comments are ignored when the input file is parsed.

OPTIONS

       AcceptMulti
              · Where:    Tuning
              · Type:     Flag
              · Default:  On

              By default, Mathopd will try to accept more connections after it
              has accepted one, until the accept  call  indicates  a  blocking
              condition.  When there is hardly any traffic, this means that an
              extra system call is made each time a connection  comes  in.  If
              you  don’t want that behaviour, use this keyword to turn it off.

       Access
              · Where:   Control
              · Type:    Block
              · Default: Inherits from previous Access blocks

              The Access block can be used to allow or deny access to specific
              IP addresses. Mathopd has a default-allow policy, so if you have
              no Access blocks, access is allowed to anyone.  If you  do  have
              Access  blocks, make sure that you put the access entries in the
              correct order. Mathopd scans access blocks from  the  bottom  up
              until a match is found.  Example:

                 Control {
                   Access {
                     Deny 0/0
                     Allow 127.0.0.1/32
                   }
                 }

              This  will  allow  access  to 127.0.0.1, while denying access to
              anyone else.

       Address
              · Where:   Server
              · Type:    Address
              · Default: 0 (any address)

              If you want a server to listen on  a  specific  address,  rather
              than any address, use this keyword.  Example:

                Server {
                  Address 127.0.0.1
                }

       Admin
              · Where:   Control
              · Type:    String
              · Default: (none)

              The  value  of  this keyword, if set, is displayed in HTTP error
              messages.

       Alias
              · Where:   Control
              · Type:    String

              Control blocks that contain an Alias keyword are used in URI-to-
              path translation. A block with an Alias keyword must have one or
              more Location keywords  as  well.  Generally  speaking,  Mathopd
              scans  Control  blocks  until it can match the directory part of
              the Request-URI with the alias.  Scanning starts in the  Virtual
              server  and continues upwards. Scanning stops as soon as a match
              is found.

              Example:

                Control {
                  Alias /
                  Location /usr/share/doc/handbook
                }
                Control {
                  Alias /boland
                  Location /usr/home/boland/www
                }

              The above is an example of two aliases. Note that the  order  of
              the  aliases  matters:  if you switch the two around, unexpected
              things will happen (the more specific alias will be obscured  by
              the ’/’ alias.)

       Allow
              · Where:   Access
              · Type:    Network

       AllowDotfiles
              · Where:   Control
              · Type:    Flag
              · Default: Off

              Normally,  Mathopd  will  not  serve any file if any part of its
              pathname  contains  ’/.’,  for   security   reasons.    If   the
              AllowDotFiles  flag is set, there restrictions are lifted a bit,
              although  constructions  like  ’/./’,  ’/../’,  etc.  are  still
              disallowed.

       AnyHost
              · Where:   Virtual

              If a virtual server has this keyword, it will match on any Host:
              header that is sent by the client. Other  virtual  servers  that
              have  an  explicit Host name are still checked, so the ’AnyHost’
              virtual server will only be used as a last resort. See also  the
              discussion of wildcard expansion under the ’Location’ keyword.

       Apply
              · Where:   Clients
              · Type:    Network

       AutoIndexCommand
              · Where:   Control

              If  a  request  for  a  directory is made, and none of the files
              specified by IndexNames is  found  in  that  directory,  mathopd
              will,  as  a last resort, run a special CGI script to generate a
              directory listing. The AutoIndexCommand determines which  script
              exactly.  The script must be an absolute pathname.

       Backlog
              · Where:   Server
              · Type:    Integer
              · Default: 128

              If   all   connections  are  in  use,  and  there  are  no  idle
              connections,  Mathopd  will  make  no  attempt  to  accept   new
              connections. The operating system may hold on to new connections
              though, in which case they will be picked up by Mathopd as  soon
              as  one  connection becomes idle. The number of connections that
              can ’hang in the air’ in  this  fashion  is  determined  by  the
              Backlog  parameter.   Normally  one  should never have to change
              this number.

       BufSize
              · Where:   Tuning
              · Type:    Integer
              · Default: 12288

              The server uses two buffers to store incoming and outgoing data.
              The  size  of  the outgoing buffer is determined by the value of
              the BufSize keyword.  Larger buffers can  lead  to  less  system
              calls, but also increase the amount of memory used by the server
              process.

              Note: if you run a version of Mathopd that uses sendfile(),  the
              default bufsize is way too large, and you should decrease it.

       BytesRead
              · Where:   LogFormat

              The  number  of  octets  (bytes)  read  from the client during a
              single request.

       BytesWritten
              · Where:   LogFormat

              The number of octets (bytes) sent to the client during a  single
              request.   Note  that  this  number  may  not be accurate in all
              cases.  If a  network  error  occurs  after  a  successful  send
              operation, the logged number of bytes sent will be too big.

       ChildLog
              · Where:   Control
              · Type:    String

              If  a  child  process, such as a CGI script, writes a message to
              its standard error file descriptor (fd 2) it will end up in  the
              file  designated  by  the  ChildLog  keyword.  If no ChildLog is
              specified, diagnostic messages will be thrown away.

       Clients
              · Where:   Control
              · Type:    Block

              This directive is similar to ’Access’,  except  that  it  causes
              ’conditional  alias matching’, rather than blocking traffic with
              ’403 Forbidden’ errors.  As such, it is only useful when used in
              combination  with  Control  blocks  that  contain  an  Alias. To
              distinguish a ’Clients’ access list from a ’normal’ access list,
              the  keywords  to  be  used  inside  the  list  are  ’Apply’ and
              ’NoApply’, rather than ’Allow’ and ’Deny’.

              All this is perhaps best illustrated by an example.

                Control {
                  Alias /
                  Location /usr/share/doc/handbook
                }
                Control {
                  Alias /
                  Location /usr/share/doc/internal/handbook
                  Clients {
                    Apply 192.168.57.0/24
                  }
                }

              In  this  example,  visitors  from  within  the  192.168.57.0/24
              network     will     get     their     content    served    from
              /usr/share/doc/internal/handbook, whereas other clients will see
              /usr/share/doc/handbook.  Note  that  the  order  of the control
              blocks matters. If  you  put  the  unconditional  alias  at  the
              bottom,  rather than at the top, it will be matched first by the
              server, thus occluding the conditional alias.

       Clobber
              · Where:   Tuning
              · Type:    Flag
              · Default: On

              Normally, Mathopd closes connections that are idle  when  a  new
              connection  arrives  and  the  maximum number of connections has
              been reached. This behaviour is called ’clobbering’.  By setting
              the  ’Clobber’  flag  to  ’Off’,  new connections cannot be made
              until an existing connection terminates by itself or times  out.

       ContentLength
              · Where:   LogFormat

              The total size of the resource requested by the client.

       Control
              · Where:   Global, Server, Virtual
              · Type:    Block

              The  ’Control’  keyword starts a so-called control block. As the
              name suggests, it controls the behaviour of the server. In  fact
              the  keyword itself does not do very much; the directives inside
              the control block do all the work.

              Unless the block contains an Alias directive, settings that  are
              specified  inside  a  control  block  are  inherited by all next
              blocks that are on an equal or lower level.

              Control blocks can appear at  three  different  levels.  Control
              bocks  that  appear at the ’top’ level in the configuration file
              are called global control blocks.  Next,  one  can  put  control
              blocks  inside  Server  blocks.  The  settings defined there are
              local to that specific server. And finally one can have  control
              blocks  inside  Virtual  blocks.  These blocks are on the lowest
              level.

              Usually a configuration file is made up of one very large global
              control  block, followed by a bunch of Virtual servers that each
              contain a small control block, mostly containing just  an  Alias
              and a Location directive.

       CoreDirectory
              · Where:   Global
              · Type:    String

              Normally,  for practical reasons, the server changes its current
              directory to the root directory "/". If this is undesirable  for
              whatever  reason,  you  can specify an alternate directory here.
              As a side effect, if mathopd dumps core for whatever reason, the
              core  file  will be in this directory. Actually if the server is
              started by root it will never dump core for security reasons, so
              this feature is a bit useless.

       Ctime
              · Where:   LogFormat

              The  current time in ’C’ format (e.g. Sun Mar 30 21:44:52 2003.)

       Deny
              · Where:   Access
              · Type:    Network

       EncryptedUserFile
              · Where:   Control
              · Type:    Flag
              · Default: Off

              Normally, the UserFile (see the descriptions of  the  Realm  and
              Userfile  keywords) contains passwords in clear-text format.  If
              you want to use encrypted  passwords  (for  example,  using  the
              ’htpasswd’  program) you must set the value of EncryptedUserFile
              to ’On’ in the control  block  that  contains  the  UserFile  in
              question.

       Error401File
              · Where:   Control
              · Type:    String

              The  contents  of  this  file will be displayed whenever a ’401’
              (not authorized) error occurs. The file may be a CGI  script  or
              an  external  command.  If  CGI  scripts are used, the script is
              responsible for sending the proper status code.

       Error403File
              · Where:   Control
              · Type:    String

              The contents of this file will be  displayed  whenever  a  ’403’
              (forbidden)    error   occurs.   For   more   information,   see
              Error401File.

       Error404File
              · Where:   Control
              · Type:    String

              The contents of this file will be  displayed  whenever  a  ’404’
              (not   found)   error   occurs.   For   more   information,  see
              Error401File.

       ErrorLog
              · Where:   Global
              · Type:    String

              The server process will print  diagnostics  messages  into  this
              file.  Mathopd will open the error log in write-only mode. If it
              does not have permission to do  that,  the  program  will  exit.
              Note  that if the value of ErrorLog contains a percent sign (%),
              the name of the error logfile will be expanded using a strftime-
              like contruction (see also: Log.)

       ExactMatch
              · Where:   Control
              · Type:    Flag

              The ExactMatch causes an Alias to be used only if it matches the
              request-URI exactly. This is rather a hack.  It  was  originally
              designed to disallow users more than one html page per web site.
              The way this is done is as follows

                Control {
                  IndexNames { index.html }
                  Types {
                    text/html { html htm }
                  }
                }
                Server {
                  Virtual {
                    Host www.another.example
                    Control {
                      Alias /
                      Location /var/www/www.another.example
                      Specials {
                        Dummy { html htm }
                      }
                    }
                    Control {
                      Alias /
                      Location /var/www/www.another.example
                      ExactMatch On
                    }
                  }
                  # other virtual servers ...
                }

              Now if someone requests http://www.another.example/,  the  alias
              will  match  exactly, so the control block at the bottom will be
              in effect. On the other hand, if a request  is  made  for,  say,
              http://www.another.example/foo.html,  the  alias  will not match
              exactly, so the second control block from  the  bottom  will  be
              used.   This  control  block  overrides the type declaration for
              html and htm extensions, effectively hiding these files, even if
              they  were  to exist physically. Note that files with extensions
              other than html and htm are processed normally, so that you  can
              for example still have things like images on your home page.

       Export
              · Where:   Control
              · Type:    Block

              Some  operating  systems require that some environment variables
              have certain  values  in  order  for  child  processes  to  work
              correctly.   To  export  these variables to child processes, use
              the ’Export’ keyword. If you want to  export  certain  variables
              with preset values, use ’PutEnv’ instead.  Example:

                Control {
                  Export { TZ LD_LIBRARY_PATH }
                }

       External
              · Where:   Control
              · Type:    Block

              The  ’External’  keywords  defines  a set of filename extensions
              that get special treatment.  (See  also:  Types,  Specials.)  If
              mathopd  processes  a  filename  whose  extension is match in an
              ’External’ block, it will run an external program with the  name
              of  the  file  as  its first argument. Before execution, mathopd
              will change its current directory to the directory that contains
              the file that is being served.  Example:

                Control {
                  External {
                    /usr/bin/perl { .pl }
                  }
                }

              This  will  treat  all files that end with ’.pl’ as CGI scripts,
              interpreted by /usr/bin/perl.

              It is possible to pass  additional  arguments  to  interpreters.
              For  example,  if you want to run all perl scripts with the ’-T’
              option, use the following construction:

                Control {
                  External {
                    "/usr/bin/perl -T" { .pl }
                  }
                }

       ExtraHeaders
              · Where:   Control
              · Type:    Block

              Use this keyword to add extra HTTP headers. This is perhaps best
              demonstrated by an example.

                Control {
                  ExtraHeaders { "Cache-Control: max-age=3600" }
                }

              If  this  is  done,  all  responses,  well,  to  be precise, all
              responses with status code 200, will be accompanied by a

                Cache-Control: max-age=3600

              HTTP header.

       Host
              · Where:   Virtual
              · Type:    String

              A virtual server has zero or  more  names.  To  name  a  virtual
              server,  use the ’Host’ keyword. More than one ‘Host’ keyword is
              allowed for each virtual server.

       IndexNames
              · Where:   Control
              · Type:    Block

              Any request that ends with  a  slash  (’/’)  is  treated  as  an
              ‘index’.   The  terminology is a bit confusing, since no indexes
              are actually being made. What happens is that mathopd  will  map
              the  request-URI  to a directory. This directory is then scanned
              for a set of files called indexes. (For instance  ’index.html’).
              As  soon  as  a  file  is  found,  that file will be sent to the
              client.  Example:

                Control {
                  IndexNames { index.html Default.htm }
                }

              Note that the value of ’IndexNames’ is  carried  over  into  all
              subsequent  control  blocks.  That  is, if you define IndexNames
              once it is not possible to reset its value later on.

       InputBufSize
              · Where:   Tuning
              · Type:    Integer
              · Default: 2048

              The input buffer contains the complete set of  headers  sent  by
              the  client. As such, it needs to be large enough to contain all
              those headers. Usually the default value of 2048  is  sufficient
              and does not need to be changed.

       LocalAddress
              · Where:   LogFormat

              The local Internet address of the connection.

       LocalPort
              · Where:   LogFormat

              The port number of the server.

       Location
              · Where:   Control
              · Type:    String

              The  Location  keyword  is  used  in  combination with the Alias
              keyword.  There are two types of locations:  physical  locations
              and  ’redirects’.   A physicial location is anything that starts
              with a slash (’/’), a redirect is anything else.   When  mathopd
              processes a request, the Alias that matches the Request-URI sent
              by the client is replaced with its corresponding  location.  For
              example, in the following situation

                Control {
                  Alias /doc
                  Location /usr/share/doc/handbook
                }

              when  a  client  requests a URI ’/doc/x11.html’, the server will
              send the contents of /usr/share/doc/handbook/x11.html.  When the
              location is a redirect, the server will send a HTTP ’302’ status
              response, which should cause  the  client  to  redirect  to  the
              desired location. Example:

                Control {
                  Alias /secure
                  Location https://an.example
                }

              In    this    example,    when    a   client   request   a   URI
              ’/secure/test.html’, the server  will  redirect  the  client  to
              ’https://an.example/test.html’.

              More  than  one  Location  keywords  can be used with one alias.
              Mathopd will  rotate  the  locations  on  a  round-robin  bases.
              Example:

                Control {
                  Alias /download
                  Location http://mirror1.an.example/download
                  Location http://mirror2.an.example/download
                  Location http://mirror3.an.example/download
                }

              The  first client that request something under /download will be
              redirected to mirrior1.an.example, the second client to mirror2,
              the third to mirror3, the fourth to mirror1, and so on.

              Wildcard  expansion:  the  wildcard  character  ’*’  in Location
              values is expanded to the current value  of  the  ’host’  header
              sent  by the client (after conversion to lower case.) This makes
              it possible to define a very large number of virtual servers  in
              one go.  Example:

                Server {
                  Virtual {
                    AnyHost
                    Control {
                      Alias /
                      Location /home/www/*
                    }
                  }
                }

              With      this      setting,     a     request     for,     say,
              http://an.example/foo.html   will    result    in    the    file
              /home/www/an.example/foo.html.

       Log
              · Where:   Global
              · Type:    String

              This  keyword  determines  where  the  access log is stored. The
              server creates one and only one access log,  regardless  of  the
              number  of  (virtual) servers. The log file must be writeable by
              the user the server runs as. If no log file exists, Mathopd will
              try to create one. In that case, the server must also have write
              access to the directory that will contain the log  file.   There
              are some hacks that make it easier to maintain logs for distinct
              time periods. Before Mathopd tries to open the log file, it will
              expand  any  ’%’  constructs  in  the  log file name, similar to
              date(1) and strftime(3). For example, if

                Log /var/mathopd/log.%Y%m%d

              is used, Mathopd will expand the %Y, %m and %d in the file name,
              to     something    like    /var/mathopd/log.20020831    Mathopd
              automatically rotates the log file every hour.  If  during  this
              process  Mathopd cannot create a new log file for any reason, it
              will continue to append to the  old  log.   The  format  of  the
              access  log  is  determined  by  whatever  is  specified  in the
              LogFormat block (see below.)

       LogFormat
              · Where:   Global
              · Type:    Block

              This keyword determines the order in  which  items  are  written
              into  the  log  file. Each line of the log file consists of some
              tab- separated fields. The contents of each field is  determined
              by  whatever  is inside the LogFormat block. For example, if the
              following is specified

                LogFormat { CTime URI }

              the first field in the log file corresponds to the date and time
              of the request, and the second field corresponds to the client’s
              request-URI at that time.

              The default field order for the log is as follows.

                Ctime
                RemoteUser
                RemoteAddress
                RemotePort
                ServerName
                Method
                Uri
                Status
                ContentLength
                Referer
                UserAgent
                BytesRead
                BytesWritten

              In addition to the above, the following fields are available:-

                LocalAddress
                LocalPort
                Version
                QueryString
                TimeTaken
                MicroTime

       LogGMT
              · Where:   Global
              · Type:    Flag
              · Default: Off

              Normally time stamps in log files are in local time.  If  LogGMT
              is  set  to ’On’, time stamps are in GMT. Note that this setting
              also affects naming of log  files  when  ’%’  constructions  are
              used. (See the ’Log’ keyword.)

       Method
              · Where:   LogFormat

              The client’s request-method, usually GET.

       MicroTime
              · Where:   LogFormat

              The time, measured in seconds, with microsecond precision, since
              00:00:00 UTC, January 1, 1970. (Or whatever is returned  by  the
              gettimeofday() system call.)

       NoApply
              · Where:   Clients
              · Type:    Network

       NoHost
              · Where:   Virtual

              A Virtual server that has the "NoHost" keyword will be used when
              no Host header is sent by the client.

       NumConnections
              · Where:   Tuning
              · Type:    Integer
              · Default: 64

              The NumConnections parameter determines  how  many  simultaneous
              requests  can  be  handled.  The default is probably too low for
              high-traffic systems.  Mathopd uses a fixed block of memory  for
              each  connection,  so  the higher you set this tunable, the more
              memory the server will use.

              See also: Clobber.

              Note: the amount of memory that is used by Mathopd  for  buffers
              can be approximated by the formula

                Memory =
                  NumConnections   *   (BufSize   +   InputBufSize   +   2   *
              ScriptBufSize)

       NumHeaders
              · Where:   Tuning
              · Type:    Integer
              · Default: 100

              This keyword has a dual purpose.

              Mathopd keeps track of the HTTP  headers  that  are  sent  by  a
              client  to  pass  on  to  child  processes.  Since each of these
              headers must be stored somewhere, a fixed amount  of  memory  is
              set  aside  for  these.  The  number  of  HTTP  headers that are
              actually stored is determined by the value of NumHeaders.  If  a
              client  sends  more headers these will still be processed by the
              server, but they will not be available as environment variables.

              This  keyword  has  an  additional  function:  it determines the
              maximum number of headers that a CGI script can send. It  is  an
              error for a script to send more than this number of headers.

       PIDFile
              · Where:   Global
              · Type:    String

              The  PIDFile  keyword  specifies a file in which the server will
              record its process ID, for tracking purposes.

       PathArgs
              · Where:   Control
              · Type:    Flag

              If you want  to  redirect  a  user  to  a  different  web  site,
              regardless  of  the  actual  URL  that  is requested, you can do
              something like this

                Control {
                  Alias /foo
                  Location http://www.an.example/foo.html
                  PathArgs On
                }

              In the above example, a request for, say,  /foo/index.html  will
              be  redirected to http://www.an.example/foo.html. In fact, *any*
              request that starts with /foo/ will be redirected  to  the  same
              URL.  If the PathArgs were omitted a request for /foo/index.html
              would be redirected to http://www.an.example/foo.html/index.html
              (which does not make much sense of course.)

              The  PathArgs  keyword was originally created to solve a problem
              related to hit metering. If you have a website, but  no  control
              over  its  logfiles,  you  can create hidden images on your site
              that link to a statistics gathering site. This is  a  well-known
              process  of  course. If the statistics-gathering runs mathopd it
              can be set up something like this:-

                Control {
                  Alias /
                  Location /usr/local/www/tiny-image.png
                  PathArgs On
                }

              This way, every request will return the same  response,  namely,
              the  contents  of tiny-image.png. If the two websites cooperate,
              the request-URI that appears in the log file  on  the  gathering
              website  can  then  be used to collect hit-metering data for the
              original site.

       PathInfo
              · Where:   Control
              · Type:    Flag
              · Default: On

              Normally   mathopd   allows    requests    for    things    like
              /script.cgi/args,  where  /args  is passed as ’path info’ to the
              script.cgi program. This  works  by  mathopd  chopping  off  all
              trailing  path  components until a file is found. This operation
              can be quite expensive and  in  most  circumstances  it  is  not
              needed.  Worse  yet,  a  request for, say, /a/b/c/d/e/f/g/h will
              result in eight system calls.

              To turn the ’chopping’ behaviour off, set the value of  PathInfo
              to Off.

              Note that PathInfo defaults to On for backwards compatibility.

       Port
              · Where:   Server
              · Type:    Integer
              · Default: 80

              If  you want Mathopd to run a server on a different port, rather
              than the default  for  http,  which  is  port  80,  use  a  Port
              declaration.  Example:

                Server {
                  Port 8080
                }

       PutEnv
              · Where:   Control
              · Type:    Block

              This  is  like Export, except that environment variables defined
              here must accompanied by a value.  Example: (rather silly)

                Control {
                  PutEnv {
                    MATHOPD_INVOKED=1
                  }
                }

              There must be no  space  between  the  name  of  an  environment
              variable,  the equals sign, and its value. If the value contains
              space characters the entire name=value bit must be  enclosed  in
              double quotes.

       QueryString
              · Where:   LogFormat

              The  query string (the part that follows the ’?’ in the request-
              URI) if present.

       Realm
              · Where:   Control
              · Type:    String

              If this keyword is present in a control block, resources in that
              block  are  protected  using username-password combinations. The
              Realm keyword must be accompanied by  a  UserFile  keyword.  The
              value of the Realm keyword is transmitted to the client in ’401’
              error responses. Its value may be displayed by a web browser  in
              a login dialog.

       Referer
              · Where:   LogFormat

              The value of the ’Referer:’ header sent by the client. Sometimes
              this refers to a  URL  that  contains  a  link  to  the  current
              request.

       RemoteAddress
              · Where:   LogFormat

              The Internet Address of the client.

       RemotePort
              · Where:   LogFormat

              The  port  number  at  the client’s end of its connection to the
              server.

       RemoteUser
              · Where:   LogFormat

              The username sent  by  the  client  for  a  request  that  needs
              authorization and has successfully authenticated.

       RootDirectory
              · Where:   Global
              · Type:    String

              If  this  keyword is present, mathopd will perform a chroot() to
              the specified directory before startup.  The  chroot()  is  done
              right after the configuration file is read. Obviously the server
              must be started as root for this to work. Some additional  files
              may  be  required  in  the  new  root,  like  a  (stripped down)
              /etc/passwd and so on.

       RunScriptsAsOwner
              · Where:   Control
              · Type:    Flag
              · Default: Off

              Normally, if the server is started as root and the StayRoot flag
              is  set,  child  processes  are  run  as a certain user (see the
              StayRoot and ScriptUser keywords.)  It is possible  to  run  CGI
              scripts   as   the   user   that   owns   them  by  setting  the
              RunScriptsAsOwner flag.  This is not recommended,  since  it  is
              possible to trick mathopd using symbolic links.

       SanitizePath
              · Where:   Control
              · Type:    Flag
              · Default: Off

              If this flag is set for a virtual server, Mathop will filter out
              all ’//’, ’/./’ and ’/../’ components of a URL.  For example,  a
              request for

                /foo/bar/../baz/./watnou//weer

              would be treated as if it really had been for

                /foo/baz/watnou/weer

              Note  that  the presense of this flag in a virtual directory has
              no effect. It only works at server level.

              Also note that URLs of the form

                /some/dir/.
                /some/dir/..

              that is, URLs that end with /. or /.. are illegal and return  an
              error, irrespective of the SanitizePath setting.

       ScriptBufSize
              · Where:   Tuning
              · Type:    Integer
              · Default: 4096

              The  server  uses two buffers for CGI scripts: one for data that
              is passed to a script, and another  for  data  arriving  from  a
              script.   It  is  recommended  that ScriptBufSize be equal to or
              greater than InputBufSize. Also the ScriptBufSize should  be  at
              least  sixteen  bytes  less  than  BufSize, to leave room in the
              output buffer for "chunk" delimiters.

       ScriptTimeout
              · Where:   Tuning
              · Type:    Integer
              · Default: 60

              This timeout determines how long, measured in  seconds,  scripts
              can run without generating any output.

       ScriptUser
              · Where:   Control
              · Type:    String

              If  a  CGI  or external program is executed, Mathopd will change
              its identity to make sure that such  programs  cannot  do  silly
              things  like  kill  the  web  server  process  and  so  on.  The
              recommended way to set the user for child processes is with  the
              ScriptUser  keyword.  Its  argument  is a user name that will be
              looked up in the system password file right before execution  of
              each  program.  The user specified by ScriptUser must be someone
              else than the ’global’ user, i.e. the user specified by the User
              keyword.   Note  that  in order to get CGI to work if mathopd is
              started by root, the StayRoot flag MUST be set to ’On’.

              See also: StayRoot.

       Server
              · Where:   Global
              · Type:    Block

              The Server keyword sets up a physical server,  that  is,  a  TCP
              socket. Some TCP parameters may be tuned (see Address and Port.)
              Inside a server block one can then  declare  ’virtual’  servers,
              which is where all action occurs.

       ServerName
              · Where:   LogFormat

              The  value  of  the  ’Host:’  header sent by the client (more or
              less.)

       Specials
              · Where:   Control
              · Type:    Block

              Some file extensions can be treated specially if  they  are  put
              into a ’Specials’ block. There are four specialties:

                CGI
                Imagemap
                Redirect
                Dump

              If  a  specialty  is  defined with a name that is not one of the
              above four, a file that matches that specialty is treated as  if
              it did not exist. (See the ’Dummy’ example in the description of
              the ExactMatch keyword.)

              A very brief description of the four specialties follows.

              For a description of CGI, see cgi.txt.  An imagemap is a  fairly
              ancient concept. It is generally not used anymore but it is kept
              around for historical reasons.  A redirect file simply redirects
              the  client  to  a  URL  that  is  contained in the file. A Dump
              displays  some  mildly  interesting  server  statistics  but  is
              otherwise not very useful.

              Example:

                Control {
                  Specials {
                    CGI { cgi }
                    Imagemap { map }
                  }
                }

       Status
              · Where:   LogFormat

              The three-digit HTTP status code for this request.

       StayRoot
              · Where:   Global
              · Type:    Flag
              · Default: Off

              Mathopd,  if  it is started by root, will change its identity to
              that of a nonprivileged user  (see  the  User  keyword.)  It  is
              sometimes  desirable to retain some root privileges, for example
              when external processes are started. One does  not  really  want
              those  child  processes  to be able to interfere with the server
              process itself, therefore these processes must be  run  under  a
              different  identity.  In  order  to  accomplish  this,  set  the
              StayRoot flag.

       Timeout
              · Where:   Tuning
              · Type:    Integer
              · Default: 60

              Connections that are idle for too long are aborted  by  Mathopd.
              Idle  in  this case meaning ’receiving or transmitting no data.’
              It is possible to increase or decrease the timeout by  adding  a
              Timeout keyword. The unit of the timeout value is seconds.

              See also: ScriptTimeout and Wait.

       TimeTaken
              · Where:   LogFormat

              The  time  it  has  taken  for  the request to complete. Time is
              measured from  the  first  meaningful  byte  received  from  the
              client, or the time the client connected.

       Tuning
              · Where:   Global
              · Type:    Block

              Some  items  that  control  general  tuning of the server can be
              specified here.

       Types
              · Where:   Control
              · Type:    Block

              All served content  must  be  accompanied  by  a  ’Content-Type’
              header  that  indicates  the kind of content. Historically, HTTP
              servers have used the extension of a filename to  determine  its
              content.   For  example  a  file  whose name ends with ’html’ is
              likely to contain HTML, a file with a name ending with ’png’  is
              probably a PNG image, and so on. Mathopd follows this behaviour.
              File extensions are mapped to media types (values  of  ’Content-
              Type’  that  web browsers understand) using the ’Types’ keyword.
              Example:

                Control {
                  Types {
                    text/html { html htm }
                    text/plain { txt }
                    image/jpeg { jpg }
                    application/octet-stream { * }
                  }
                }

              As you can see, the  media  type  is  followed  by  a  group  of
              extensions  that  will  be  mapped  to  that  type.  The special
              extension ’*’ is used to indicate a default: if a  filename  has
              an  extension  that  does  not  occur  in  any  of the Types (or
              Specials or External), then the type for ’*’ (if it is  defined)
              is used.

              Note  that  for  Mathopd,  ’extension’  really  means just ‘last
              part’.  For example, a  file  that  is  called  ’flubrdhtml’  is
              deemed  to be a HTML file even though it does not really have an
              extension.  This is a bit of a misfeature, but it does  no  real
              harm in practice.

       Umask
              · Where:   Global
              · Type:    Integer
              · Default: 022

              Mathopd  will  create log files with certain permissions.  These
              permissions are determined by what is called in Unix  lingo  the
              ’umask’. A umask of 022 (the default) will create files that are
              readable by everyone but writeable only by the  user  that  runs
              the  server process. More restricted umasks are 026 or even 066.
              (The 0 at the beginning is not optional!)

              Note: the umask is inherited by child processes.

       Uri
              · Where:   LogFormat

              The  URI  requested  by  the  client  (minus  query  string,  if
              present.)

       User
              · Where:   Global
              · Type:    String

              If  Mathopd is started by root it must change its identity. This
              is done for security reasons: you do not want the web server  to
              be  able  to  read all files. The new identity is defined by the
              value of the User keyword. The user name is  looked  up  in  the
              password  file  (this  is  done  before  a possible chroot!) and
              Mathopd then changes its effective user id (and real user id  as
              well,  depending on whether StayRoot is off or on). In addition,
              Mathopd will perform a setgroups() call to  clear  its  list  of
              supplementary group ids.

              Note:  Mathopd will create log files, etc. with an owner that is
              equal to the value of the User keyword. The *group* owner of the
              log  file  may differ between operating systems. For example, on
              BSD, the group owner of a file is set to the group owner of  the
              directory  in  which  it  is  created.  Other  systems  may have
              different semantics.

       UserAgent
              · Where:   LogFormat

              The value of the ’User-Agent:’ header sent by the  client.  This
              may,  or  may  not,  contain  a  string  that can identify a web
              browser.

       UserDirectory
              · Where:   Control
              · Type:    Flag

              To allow each user to put up his or her personal pages, use  the
              UserDirectory kyeword.  Example:

                Control {
                  Alias /users
                  Location public_html
                  UserDirectory On
                }

              In  this  example,  a  request for /users/boland/index.html will
              result in a password lookup for user ’boland’. Assume  the  home
              directory  for  this  user is /home/boland. Then the file served
              will be /home/boland/public_html/index.html.

              Note: the ’~’ character, when used as the last character  in  an
              alias is treated specially. For example:

                Control {
                  Alias /~
                  Location public_html
                  UserDirectory On
                }

              With   this  setting,  /~boland/index.html  will  be  mapped  to
              /home/boland/public_html/index.html, like  before.  This  is  to
              allow  some sort of compatibilty to the often used custom to use
              ’~username’ for user pages.

       UserFile
              · Where:   Control
              · Type:    String

              Control blocks that are ’protected’ by a Realm  keyword  need  a
              UserFile  keyword as well. The user file contains all username /
              password combinations that are valid for  that  specific  realm.
              The user file should contain lines that look like

                username:password

              (with  username  and  password  replaced  by a real username and
              password of course.) A user can be entered more than  once  with
              different passwords. The user file has no relation whatsoever to
              the system  password  file.  Passwords  can  be  encrypted,  but
              Mathopd  needs  to  be  told  that they are encrypted, using the
              EncryptedUserFile keyword.

       Version
              · Where:   LogFormat

              The HTTP version requested by the client.

       Virtual
              · Where:   Server, Global
              · Type:    Block

              The ’Virtual’ keyword starts a virtual  server  block.   Virtual
              blocks  can  be  declared  globally  or  inside  a server block.
              Global virtual blocks are inherited by all servers that  follow.

       Wait
              · Where:   Tuning
              · Type:    Integer
              · Default: 60

              The  value  of ’Wait’ represents the amount of time, in seconds,
              the server will wait for a request from the client.

AUTHOR

       Mathopd was written and is copyright by Michiel Boland.

       This manual page was produced from the authors  text  documentation  by
       Juergen Daubert for the CRUX Linux system, but may be used by others.

SEE ALSO

       mathopd (8)