man mathopd.conf (5): 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'.

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.

DESCRIPTION

OPTIONS

AUTHOR

LAST SEARCHED