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.
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=NUMSets 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.
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> |
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.