Provided by: mathopd_1.5p6-1.1_amd64 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)