3. Configuration File

3.1. Overview

phhttpd uses an XML config file format to express how it should behave while running. More information on XML may be found near http://www.w3.org/XML/

phhttpd's configuration centers around the concept of virtual servers. For us, a virtual server may be thought of as the merging of a document tree and the actions phhttpd takes while serving that content.

phhttpd.conf may be thought of as having two main sections. The global section, which defines properties that are consistent across the entire running phhttpd server, and multiple virtual sections that describe properties of that only apply to a virtual server. There will only be one global section while multiple virtual sections are allowed.

3.2. Global Config Section

The global section defines properties of the running server that don't apply to a single virtual server. It should be enclosed in

Global config entities

cache max=NUM

Sets the maximum number of cached responses that will be held in memory. Each cached responses holds a minimal amount of memory. More importantly, each cached response holds an open file descriptor to the file with real content and an mmap()ed region of that content. phhttpd will start pruning the cache when it notices either of these two resources coming under pressure, but has no way to easily deduce that its running low on memory. The administrator may set this value to set an upper bound on the number of responses to keep in memory.

control file=PATH

This specifies the file that will be used to talk with phhttpd_ctl.

globallog file=PATH

This specifies the file to which global messages will be logged.

mime file=PATH

This specifies the file that contains the mapping of file extensions to MIME types. It should be of the form:

text/sgml                       sgml sgm

video/mpeg                      mpeg mpg mpe

timeout inactivity=NUM

Controls various network connection timeouts. 'inactivity' sets the amount of time that a connection can be idle before phhttpd will forcibly disconnect it. inactivity defaults to 0, which lets the connections idle until TCP timeouts take effect.

sendfile

Enabling this option tells phhttpd to use sendfile() rather than write()ing from an mmap()ed region. Avoiding calling mmap() will shorten the amount of time it takes to build cached responses.

3.3. Virtual Servers

A Virtual Server can be thought of as the abstraction serving up a content tree ( "docroot" in Apache speak). There are a set of attributes that are used to define a virtual server. These attributes are used to decide which virtual server will process a client's request. Then there are attributes which define how the content is served.

A virtual server must have a docroot. The virtual tag in the config file has a docroot attribute that must be set.

<virtual docroot=PATH>

	...

</virtual>

There can be as many virtual sections in the configuration file as one likes.

Global Config Entities

md5: This enables the generation of the Content-MD5: header. This greatly increases the cost of creating a cached response for this virtual, because the MD5 function must be applied to the entire content of the response. Once the response is created, though, there is no per-request overhead.
prepop: This will cause phhttpd to traverse the entire docroot at initialization time and prepare cached responses for all the files it finds. This happens in the back ground during normal operation, so there is no dramatic increase in the time it takes for phhttpd to start serving connections.
name: This tag surrounds the string that will be used to identify the server. This string will be compared to the Host: header given in the request from the client, or will be compared to the 'host part' of the full URL if that was given. This will be used in combination with the network address and port pair to determine if a request should be served by a virtual server.
listen v4=DOT.TED.QU.AD port=PORT: This virtual server will be chosen to serve an incoming request if that request was made to the network address specified in this entity. There can be as many of these as one likes in a given virtual server, and '*' may be specified for either parameter to indicate that all addresses or ports should match.
logs: The logs section of the virtual server define the per virtual log files that should be written to during operation. See the following section on logging.