Configuring "phttpd.conf"

The "phttpd.conf" file (normally located in /opt/phttpd/etc/) contains some settings that affect the global state of the server. Most of these settings can normally be ignored since they are automatically given reasonable defaults. However, there are a couple of important ones that you probably must and should modify.

First there are some general remarks about the server. phttpd can run in several modes:

  1. Single Standalone Server, which may bind to one or all of you network interfaces. This is the default mode of operation.
  2. phttpd support multihoming in a very nice and low-resource mode. The mode is called "rkmultimode" in the global configuration file. This requiers the server to listen on ALL of your network interfaces, and the server has a sperate document root and configurable modules with different options each for every interface you have.
  3. phttpd support "software virtual servers", as specified in HTTP/1.1 and also this mode of operation in the HTTP/1.0 emulation mode. This work with most of the modern browsers, e.g. NetScape 3.x and above. There is a different document root for every virtual server and there may also be different modules loaded for each virtual server.
  4. In addition, modes 2 and 3 can be combined. Thus giving you the option of running a bunch of different software virtual servers on each network interface. A network interface may also be a virtual interface. How to set up a virtual interface on Solaris 2.5+ is documentet in man ifconfig.
The first one is the logical name of the server, which unless modified, defaults to the hostname of the machine the server is run on. For example:
        server-name = www.some.where
The next one is the WebMaster contact information, which is included into error messages generated by the server. For example:
        web-admin-name  = Foo Barson
        web-admin-home  = http://www.some.where/~foo/
        web-admin-email = foo@some.where

Configuration options:

server-name (string)
The full DNS name of the server that you want it to be known as. Defaults to the hostname of the machine.
server-addr (string)
The DNS name or IP number of the local interface to bind the server to. Defaults to "*" which causes it to bind to all local interfaces. In case you want to use rkmultimode, you must set this to "*" !
server-port (string)
The service name or number of the TCP port to bind the server to. Defaults to port 80 (the standard WWW port).
server-user (string)
The user name or number that the server should execute as. This will also cause the server-group option to be set to the group number defined in the password database for the specific user.
server-group (string)
The group name or number that the server should execute as.
rkmultimode (boolean)
This enables the use of different document roots for every networkinterface. To make this work you must also set server-addr to "*". The documentroots are automatically defined by the database-dir(see below) and the IP-number of the interface in hexadecimal notation ! By default this option is off.Let me give you an example: If you have the network interfaces 192.168.10.12 and 192.168.10.15 on your machine and you database-dir is /home/www/pages, the document roots will be: If you are working with cgi's or checking the logfile, phttpd will internally handle those requests by expanding the requested URL with that hexadecimal number as a prefix. So if you ask for the URL http://192.168.10.12/demo/index.hml the server will handle this as a request to /c0a80a0c/demo/index.html
You will also see that URL in you logfile. To split that log into seperate logs, issue the following shell command:
grep c0a80a0c your-logfile | sed s/'\/c0a80a0c// > log.192.168.10.12
Note: A future release will allow you to use hostnames instead of ip numbers.
software-virtual-server (boolean)
This enables the use of software virtual servers as defined in HTTP/1.1. In principal this means, that you have several DNS-entries point to the same IP-address and depending on the query, the server will use a different document root for all those entries. This works the same way as rkmultimode, but the hostname in lowercase is sent to phttpd is prefixed to the URL. For proper work, this may requiere some symbolic link, if you want to have more names to the same server of qualified and unqualified named pointing to the same data. This applies to the modules as well.
This mode can be combined with rkmultimode. The rkmultimode comes FIRST !.
The internal representation then is something like: /c0a80a0c/myhostname/demo/index.html for a query
GET http://myhostname/demo/index.html HTTP/1.1
web-admin-name (string)
Full name of the server administrator.
web-admin-home (string)
URL to the server administrators home page.
web-admin-email (string)
Email address to the server administrator.
url-rewrites (table)
A list of rewriting rules for incoming URLs.
url-redirects (table)
A list of temporarily redirected URLs.
url-permanent-redirects (table)
A list of permanently redirected URLs.
url-access (table)
A list of host access control rules.
read-authenticate (table)
A list of user/password authentication rules for get/post/head requests.
write-authenticate (table)
A list of user/password authentication rules for HTTP-put requests (like http-publish).
write-needs-auth (boolean)
Defaults to yes. This forces all HTTP-put requests to be authentificated.
url-handlers (table)
A list of Phttpd Modules to be invoked for various URLs.
database-dir (string)
The directory where the global HTML documents are located. Defaults to the directory "/opt/phttpd/db".
modules-dir (string)
The directory where the Phttpd Modules are located. Defaults to the directory "/opt/phttpd/modules".
user-dir (string)
The subdirectory in the user's home directory where their HTML documents are located. Defaults to ".public".
logging-file (string)
Path to the request logging file. This file is written in the CERN Common Log format. Defaults to "/var/log/phttpd/requests".
counting-file (string)
Path to the request counting file. This file is written in a NDBM format for speedy access. Defaults to "/var/log/phttpd/counts".
pid-file (string)
Path to a file containing the process ID of the Phttpd daemon.
stderr-file (string)
Path to a file containing all stderr output from CGI scripts.
concurrency (number)
A number specifying the desired thread concurrency level.
listen-backlog (number)
A number specifying the desired TCP/IP new connection requests backlog limit.
socket-sndbuf (number)
The size of the transmit buffer for each request.
socket-rcvbuf (number)
The size of the receive buffer for each request.
gc-time (number)
The maximum time a request may be idle.
gc-sleep (number)
The time between each request garbage collect run.
select-timeout (number)
The maximum time to wait for incoming data.
stack-size (number)
The size of the stack for each thread.
fscache-refresh (number)
fscache-ttl (number)
fscache-gc-interval (number)
Controls how long entries live in the FileSystem cache.
urlcache-refresh (number)
urlcache-ttl (number)
urlcache-gc-interval (number)
Controls how long entries live in the URL lookup cache.
server-processes (number)
The number of parallell server processes doing accept() concurrently.

Warning: This does NOT work reliably under Solaris 2.4
accept-threads (number)
The number of threads concurrently waiting for incoming connections.

Boolean variables

bound-threads (boolean)
If set to "true", use bound threads instead of unbound threads.
hostname-lookups (boolean)
If set to "true", do hostname lookups for each incoming connection.

/opt/phttpd/etc/phttpd.conf sample configuration

# /opt/phttpd/etc/phttpd.conf
#
# Sample configuration for PHTTPD 1.0x
# 

# web-admin-name = Foo Barson
# web-admin-home = http://www.xx.yy/~fubar/
# web-admin-email = fubar@xx.yy

database-dir   = /opt/phttpd/db
# user-dir       = pub
# user-basedir   = [null]
#
# fscache-refresh = 10
# fscache-ttl    = 60
# fscache-gc-interval = 60
#
# urlcache-refresh = 120
# urlcache-ttl   = 120
# urlcache-gc-interval = 600
#
# accept-threads = 1
# server-name    = www.ifm.liu.se
server-port    = 80
server-addr    = *
#modules-dir    = /opt/phttpd/modules
# server-user    = www
# server-group   = nobody
# concurrency    = 64
# socket-sndbuf  = 64K
# socket-rcvbuf  = 64K
# gc-time        = 120
# gc-sleep       = 60
# select-timeout = 120
# stack-size     = 2M
# logging-file   = /var/log/phttpd/requests
# stderr-file   = /var/log/phttpd/stderr
# pid-file       = /var/log/phttpd/pid

### Max length of input URL. 0 == unlimited
# max-url-size   = 256K

### Multiserver support, added by Roland Kaltefleiter, which requiers
### only ONE Proceess, set this to on, to enable, default is no.
### This option requirs a bind to ANY (server-addr = * )
### The files for the virtual servers will be put below 
### database-dir/HEX-IP/, that means the IP-Number of each interface
### will be added to the pathname, (using %lx format).
#
# rkmultimode = no

### Software virtual servers as defined in HTTP/1.1
### If you use this, you need to take real care if you use some of
### the proxy code, since a local request might be 'GET http://host/path HTTP/1.0'
### The virtualhostname is put behind the Server root.
### In combination with 'rkmultimode', rkmultimode comes first, and then
### software-virtual-server. So a documentroot will then be like:
### /home/www/docs/c1626e12/www.netuse.de/
### Warning: software-virtual-server is verified for the modules:
### dir.so file.so cgi.so map.so
### Wont'work: All proxy code AND ncsa-html.so.
### All others: Should work, but I did not have time to verify....
#
# software-virtual-server = no

### You may wanna disable this if you have problems with small files
### and images (<60 bytes) and Netscape 2.0b (there are bugs in NS2's
### handling of Keep-Alive connections and small objects).
#
# keepalive-connections = yes

### By enabling "extended-logging" you will get two extra fields in the
### requests log file, "Referer" and "User-Agent".
#
# extended-logging = yes

### Add the received and send bytes of the query and the mime-header to
### the volume written to the logging-file. Old default was NOT to add.
### The incoming header is always added (if logheadervolume==yes).
### The outgoing mimeheader is added only by the modules file and cgi.
### Other modules are in work.....
#
# logheadervolume = yes

### This will enable IP# -> Hostname lookups. This can cause a performance
### penalty even though Phttpd tries to limit the effects of it by doing
### extensive cacheing
#
# hostname-lookups = yes

### This will enable IDENT (RFC1413) queries for every incoming request.
### WARNING: This will cause a big performance penalty, even though Phttpd
### does the lookup in the background to try to limit the effects.
#
# ident-lookups = no

### (See the INSTALL file for more information about this parameter if you
###  want to set this value to anything above 5 (which you want) _and_ have
###  the OS use it! It won't hurt to have it set to this though...)
#
# listen-backlog = 1024


#
# List of global modules to load at startup
#
#global-modules = {
#	extra_lib1.so
#	extra_lib2.so
#	/usr/lib/libresolv.so
#}


#
# List of language content type declarations
#
#content-language = {
#	/hr/*		hr
#	*.hr.html	hr
#	*.hr.shtml	hr
#	/en/*		en
#	*.en.html	en
#	*.en.shtml	en
#}

#
# List of URL data handler modules
#
url-handlers = {
 	/cgi-bin/*	cgi.so
#	http:*		http_proxy.so
#	gopher:*	gopher_proxy.so
#
# The "next_proxy" relays hands over all Proxy traffic to some
# other Proxy server exactly as the data is sent to Phttpd from the client.
#	http:*		next_proxy.so
#	gopher:*	next_proxy.so
#	ftp:*		next_proxy.so
#	file:*		next_proxy.so
#	wais:*		next_proxy.so
#
	*.map		map.so
#	*.var		var.so
	*.shtml		ncsa-html.so
	*.mbox		mbox.so
	*.cgi		cgi.so
	*.nph		cgi.so
	*.asis		asis.so
	*.cgi/*		cgi.so
	*.nph/*		cgi.so
	/phttpd/config	config.so
	*/		dir.so
	*		file.so
}


#
# List of modules handling user/password authentication requests
# The first token is the "Domain" (wildcards are allowed) from the
# Authenticate header (see "read-authenticate" and "write-authenticate" below).
#
auth-handlers = {
	File*		auth_file.so
	[passwd]	auth_syspwd.so
}


## Syntax is: URL-pattern   Rewriting-Rule
#
# url-rewrites = {
#	/htbin/htimage/*	/%{2-}
# 	/cgi-bin/imagemap/*	/%{2-}
# }


## Syntax is: URL-pattern   ACL-file
#
# host-access = {
#	/Access/*	Access/.acl
# }


## Syntax is: URL-pattern   Password-Source   Security-Realm
## Where '[passwd]' == System password database
#
# read-authenticate = {
#	/Auth/*			[passwd]	System Password
#	/Secret/*		File2		Secret PassPhrase
#	/TopSecret/*		File1		TopSecret Sentence
# }
#
#
# This is default, you may want to set this to no to debug !
# write-needs-auth = yes
#
# write-authenticate = {
#	/Auth/*			[passwd]	System Password
#	/Secret/*		File2		Secret PassPhrase
#	/TopSecret/*		File1		TopSecret Sentence
# }


## Syntax is: URL-pattern   Rewriting-Rule
#
# url-redirects = {
#  	/Lysator/*	http://www.lysator.liu.se/%{1-}
# }


## Syntax is: URL-pattern   Rewriting-Rule
#
# url-permanent-redirects = {
#	/Ifm/*	http://www.ifm.liu.se/%{1-}
# }


## Syntax is: Error code	URL
## Defaults to builting pages.
#
# error-pages = {
#	403	http://www.not-found.com/
#	404	http://www.access-denied.com/
#	*	http://www.catch-all.com/
# }