Configuration settings for Stunnix Perl Web Server

When SPWS is started and no configuration file was specified via commandline option '--cfgfile', then 'httpd.conf' file is read from the directory where script is located. It's possible to request SPWS to read several configuration files at startup by using commandline options, and passing configuration file statements directly via commandline is also possible - see more information in supported commandline options.

The syntax of configuration files resembles syntax of famous and most widely-spread Apache web server:

Here is a sample configuration file:

#global settings
Port 8002 		#port to listen on for http connections
host		#IP address to listen on
Portctl 8001		#port to listen on for control connections from slaves

MaxSlaves 1		#number of slave processes for execution of (x)CGI 
ErrorLog logs/error_log		#location for error log file
AccessLog logs/access_log	#location for access log file
DontLog 1		#whether not to log anything at all

DocRoot /var/www/html	#Path to the WWW document root

#builtin types are reasonable, but if you need, specify filename here
MimeTypesSource /dev/null #'/dev/null' is treated special and means
                        # "don't read from any file, use internal defaults"

#note: to get name of the module, mod_xcgi => ws::mod::xcgi
HandleTypes mod_xcgi    script/xcgi	#treat as XCGI script
HandleTypes mod_cgi     script/cgi	#treat as CGI script
HandleTypes mod_cgi_pl  script/cgi-perl #treat as perl CGI script
HandleTypes mod_ssi     sendfile/ssi	#process Server Side Includes
HandleTypes mod_asis    sendfile/asis	#send file as is

#All supported settings that can be specified on per-location basis are below.
#All supported settings that must be specified global-wise (not inside any
#Location section) are above.
<Location />
DirectoryIndex index.shtml index.shtm index.html index.htm #order in which
		    #to lookup documents when document with path that 
		    #corresponds to the directory is requested

AddHandler script/xcgi xcgi xpl #handle .xpl and .xcgi files using mod_xcgi
AddHandler script/cgi-perl cgi 
AddHandler script/cgi exe
AddHandler sendfile/ssi shtml
AddHandler sendfile/asis DEFAULT 	#special kind of extensions - 'DEFAULT' 
					#means "any other extension"

#example of setting headers for a given location:
Set 	Header Expires "1 jan 2010"  #set value of http-header 'Expires'
		#to "1 jan 2010", signaling the browser not to refetch anything
		#loaded below "/".
UnSet 	Header Blah  	#Don't set http header named "Blah". Useful for
		#making exceptions for e.g. (X)CGI scripts

#example of setting environment variables for a given location
Set  	Env MyVar "blah1"
		#Note:value is always in double quotes, even if value doesn't
		#contain spaces..
Unset 	Env MyVar2 #Unset variable named MyVar2 for this location


#example of setting header for particular script. Since this Location section
#is after the all-catching section for Location "/", the settings below will
#override settings set in  section for Location "/".
<Location /scripts/login.xpl >
Set 	Header Expires "1 jan 1970"  
		#set value of http-header 'Expires' to 
		#date in the past, forcing browser to refetch the resource
		#and not to store it in its internal cache

#example of setting header for files with names matching specific Perl regular
#expression. Regular expression has to be enclosed in double quotes!
<LocationMatch "\.css$" >
Set 	Option handleby "/themer.xpl"  
	    #filename of handler has to be enclosed in double quotes!

	    #Make all .css files to be transparently generated by a
	    #script - e.g. to allow themeing

Some settings can be specific to some site location, some settings are global (like Port to listen on). If one wants to make group of settings specific to some location of the site, one has to enclose that group of settings into a section starting with <Location, then listing name of location (relative to site root), then appending > and newline, and ending group of settings with </Location> on a separate line; see example above for illustration. Also it's possible to apply settings to resources with URI matching some specific Perl regular expression by the use of LocationMatch, see example above for more information.

Names of settings are case-insensitive.

Global settings

These settings can't be specified inside section specific to some location (grouped by their purpose):

Settings that can be specified on per-location basis

These settings can be specified inside section specific to some location (listed grouped by their purpose):

Description of global settings


Specify IP address to open listening socket on. In most cases is the best choice.


Port to listen for incoming http connections.


Port number for communication with slaves.


Root of the site. Should end with '/'!


Maximum number of slave processes to start. CGI and XCGI scripts are executed by or inside slave processes, so the value effectively limits number of CGI or XCGI scripts that can be executed at any single moment of time. Even when all slaves are busy executing CGI or XCGI, SPWS can serve static content. Default value is 1.


Whether log files are not produced at all. Default value is 1.


Name of file to save log of all accesses to. Logfile has format similar to apache, but not fully compatible with Apache logfile format (since some fields are meaningless). Default value is logs/access_log.


Name of file to save log of all errors to. Default value is logs/error_log.


Specifies file name to parse for mime type mapping. SPWS already has entries for most typically used extensions, so there is no need to extend it. In case one will need to add additional mappings, then the file referenced by this directive should contain lines looking like this:

video/mpeg mpeg mpe mpg

- i.e. mime-type name, and list of file extensions, without dots.


This directive specifies mapping between SPWS module name and a tag, that can be later used in AddHandler for specifying how to handle files of a given extension. E.g. sample line

HandleTypes mod_xcgi    script/xcgi     

specifies that extensions tagged with script/xcgi are to be handled by mod_xcgi. Later you can add the following lines to specify set of extensions to be handled by mod_xcgi:
AddHandler script/xcgi xcgi xpl 

That tag can be arbitrary string. The module name can be one of the following:

Description of settings that can be specified on per-location basis


This directive specifies space-separated list of filenames to try to find in the directory when the resource that maps to directory is requested. Example:

DirectoryIndex index.shtml index.shtm index.html index.htm 

E.g. for this sample line if request for /foo/ is arrived, and there is a directory named 'foo' below document root, SPWS will try to load foo/index.shtml, in case of absence of it SPWS will try to load foo/index.shtm, and so on. In case entire list was tried but file not found, SPWS will return an error. Serving directory indexes (as apache's mod_autoindex does) is not and won't be supported by SPWS.


This directive specifies tag to bind to a space-separated list of dot-less file extensions. Sample:

AddHandler script/xcgi xcgi xpl 

The tag (script/xcgi here) should be bound to some SPWS module using HandleTypes directive.

Set Header

This directive sets the value of a specified HTTP header to a specified value. In the following example:

Set     Header Expires "1 jan 2010"

the header 'Expires' is assigned a value of "1 jan 2010". The value should always be in quotes.

UnSet Header

This directive unsets the specified HTTP header. Example:

UnSet   Header X-Blah

This unsets HTTP header X-Blah.

Set Env

This directive sets value of specified environment variable to the specified value. In the following example:

Set     Env DBNAME "empdb"

the environment variable 'DBNAME' is assigned a value of "empdb". The value should always be in quotes.

The variables set this way are accessible by the SSI directives and CGI and XCGI scripts. This is a handy way of passing some pieces of configuration information to them.

UnSet Env

This directive unsets the specified environment variable. Example:


Set Option

This directive sets value of specified option variable to the specified value. In the following example:

Set     Option handleby "/themer.xpl"

the option 'handleby' is assigned a value of "/themer.xpl". The value should always be in double quotes.

The only option supported so far is 'handleby'.

UnSet Option

This directive unsets the specified option. Example:

UnSet Option handlebby