SYNTAX OF THE MATHOPD 1.3pl7 CONFIGURATION FILE
***********************************************

Reverse engineered by : Erik Devriendt 
                        Erik.Devriendt@siemens.be
Date : 18/03/2002

DISCLAIMER
==========
This file is the result of reverse engineering.
The author does not guarantee the correctness or completeness
of its contents.
USE IT AT YOUR OWN RISK.


GENERAL
=======

Mathopd reads its configuration from stdin.

The configuration has following structure :

It starts with a <Global Part>. Then a sequence of one or more
<Control> or  <Server> declarations follow.

So we have :

	<config> = <Global Part> (<Control> | <Server> )*

Blank lines are ignored.
Comments start with '#' and run upto the end of the line.

The Global Part :
-----------------

	RootDirectory <string>
	CoreDirectory <string>
	DefaultName <FQDN>
	Umask <int>
	StayRoot <On/Off>
	User <string>
	PIDFile <string>
	Log <string> 
	ErrorLog <string>
	
	Tuning
		{
			Timeout <int>
			BufSize <int>
			InputBufSize <int>
			NumConnections <int>
			AcceptMulti <On/Off>
		}


A <Control> declaration :
-------------------------

	Control
		{
			Location <string> 
			Alias <string> 
			Symlinks <On/Off>
			PathArgs <On/Off>
			IndexNames { <string> ... }
			Access { Allow <a.b.c.d/mm>
			         Deny  <a.b.c.d/mm>
			         ... }
			Clients { Apply   <a.b.c.d/mm>
			          NoApply <a.b.c.d/mm>
			          ... }
			Types { <string> { * | <ext> ... }  }
			Specials { <string> { * | <ext> ... }  }
			External { <string> { * | <ext> ... }  }
			Admin <string>
			Refresh <int>
			Realm <string>
			UserFile <string>
			Error401File <string>
			Error403File <string>
			Error404File <string>
			EncryptedUserFile <On/Off>
			ChildLog <string>
			DNSLevel <int>
			Export { <string> ... }
			ExactMatch <On/Off>
		}

A <Server> declaration :
-------------------------

A Server declaration can contain zero or more Virtual declarations.
A Server declaration can contain zero or more Control declarations.

A Virtual declaration can contain zero or more Control declarations.

	Server
		{
			Port <int>
			Name <hostname>
			Address <a.b.c.d>
			Virtual
				{
					Host <string>
					NoHost 
					Control
						{
						... see Control declaration ...
						}
					...
				}
			...
			Control
				{
				... see Control declaration ...
				}
			...
		}


KEYWORD EXPLANATION
===================	
GENERAL
-------

RootDirectory <string>

	mathopd does chroot(<string>)

CoreDirectory <string>

	If set mathopd does chdir(<string>) and prepares to create a core file
        overthere if necessary, else chdir("/") and no core file will be produced.
	This is all relative to RootDirectory.


DefaultName <FQDN>

	Default for Server.Name
	
Umask <int>

	general umask.

StayRoot <On/Off>

	<to be described>
	
User <string>

	mathopd runs as user <string>

PIDFile <string>

	 PID file pathname, relative to CoreDirectory

Log <string> 

	Log file pathname, relative to CoreDirectory.
	Can contain formatting characters of strftime()

ErrorLog <string> 

	Error log file pathname, relative to CoreDirectory.
	Can contain formatting characters of strftime()


TUNING
------

Timeout <int>

	Maximum time (in secs) that an open connection can stay idle before it gets closed.

BufSize <int>

	Output buffer size in bytes (default 12KB)

InputBufSize <int>
	
	Input buffer size in bytes (default 2KB)

NumConnections <int>

	Maximum number of simultaneous connections (default 64).

AcceptMulti <On/Off>

	Do as many accept() as possible, before processing the requests.


CONTROL
-------
Note : Control sections are used in reverse order (bottom up in the config file).

Alias <string>

	Path part of the URL for which this Control section is valid.

Location <string>

	1. Absolute pathname of the local file or directory corresponding to the given Alias.
        2. Relocation URL (http error 302)

	You can put more than one Location entry in a Control. They will be used in a round robin
	fashion.

Symlinks <On/Off>

	Allow or disallow symbolic links in the pathname after Alias to Location substitution.
	'On' makes mathopd faster.


PathArgs <On/Off>

	Allow or disallow URLS with path-like script arguments:
		http://www.here.org/file.html/patharg1/partarg2
	Default Off.

IndexNames { <string> ... }

	List of default index files.
	When an URL ends up referring to a directory, mathopd will search for the given
	index files in that directory. Mathopd traverses the given list in reverse order.

Access { Allow <a.b.c.d/mm>
         Deny  <a.b.c.d/mm>
	 ... }

	Allows or denies requests originating from IP addresses matching
        the first <mm> bits of the numerical IP address a.b.c.d .


Clients { Apply   <a.b.c.d/mm>
	NoApply <a.b.c.d/mm>
	... }

	This Control applies or does not apply for clients matching the given IP address/mask.
	If this Control does not apply, it is treated as if it was not present.


Types { <string> { * | <ext> ... }  }

	<string> is the mime-type name for files with given extension <ext>.
	Extension '*' matches any extension.

Specials { <string> { * | <ext> ... }  }

	<string> must be one of :
		CGI      : files with given extensions <ext> are CGI scripts.
		Imagemap : files with given extensions <ext> are image maps.
		Redirect : files with given extensions <ext> are contain a target URL for a redirection.
		Dump     : for debugging purposes (see dump.c)

External { <string> { * | <ext> ... }  }

	<string> is the absolute pathname of a program that will handle files with the given
	extensions <ext>.

Admin <string>

	<string> is the e-mail address of the Site Administrator, and is used in error pages.

Refresh <int>

	Requests the browser to do an automatic refresh after <int> seconds.

Realm <string>

	Used in conjunction with UserFile.
	<string> is the realm of the Authentication zone.

UserFile <string>

	<string> is the absolute pathname of the file containing the valid user records.
	A user record consists of a line containing two fields separated by a ':'.
	The first field is the username, the second the password.
	The password is in cleartext, unless EncryptedUserFile is On.

Error401File <string>
Error403File <string>
Error404File <string>

	Alternative error HTML files. <string> is an absolute pathname.

EncryptedUserFile <On/Off>

	Used in conjunction with UserFile.
	'On' means that the password in the file is encrypted using the
        the standard UNIX crypt() function.
	'Off' means that the passords are in cleartext.

ChildLog <string>

	<string> is the log file pathname of the child process created at the occasion of
	the execution of a CGI script or External program.

DNSLevel <int>

	For CGI scripts and External program invocation.
	0  : do not look up the hostname of the clients IP address
	1  : look up the hostname of he clients IP address, and pass it to the CGI via the REMOTE_HOST
	     environment variable.
	>1 : look up the hostname and verify that the given IP address belongs to that hostname.
	     Pass it to the CGI via the REMOTE_HOST environment variable. 

Export { <string> ... }

	<string> is the name of an environment variable to be passed on to the CGI script or External
	program.


ExactMatch <On/Off>

	Used in conjunction with Alias.
	'On' means that the path in the request URL must match the Alias exactly.
	'Off' means that only the head of the path in the request URL must match the Alias.
	Default is 'Off'.

SERVER
------
Port <int>

	The Server listens on TCP port <int>.
	Default : 80.

Name <hostname>

	Name of the Server. Must be a valid hostname.
	To be used for multihomed servers.
	Default : the value of DefaultName, but then the Server will bind to
	all interfaces.
	Cannot be used in conjunction with Address.

Address <a.b.c.d>

	IP address of the Server. To be used for multihomed servers.
	Cannot be used in conjunction with Name.


Virtual
.......

These are the descriptions of the virtual hosts served by the Server.

Host <string>

	The name of the virtual host.
	Default : Name of Server

NoHost

	Equivalent to absence of Host.

Control { ... }

	The Control sections in a Virtual have precedence over the Server Control sections.


Control
.......

The Control sections in a Server have precedence over the globally declared Control sections.