Home Products Services Store Support Contact About Us

Support → Documentation → Stunnix Perl Web Server

Configuration settings

When SPWS is started and no configuration file was specified via commandline option '--cfgfile', then 'httpd.conf' file is read from the directory where srvrun.pl 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:

Each setting occupies exactly one line
Empty lines are ignored
Everything after a hash sign ('#') is ignored on each line
Later setting overrides previous one

Here is a sample configuration file:

#global settings
Port 8002 		#port to listen on for http connections
host 127.0.0.1		#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 
			#scripts
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

</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
</Location>

#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
</LocationMatch>

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):

Host
Port
Portctl
DocRoot
MaxSlaves
DontLog
AccessLog
ErrorLog
MimeTypesSource
HandleTypes

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):

DirectoryIndex
AddHandler
Set Header
UnSet Header
Set Env
UnSet Env
Set Option
UnSet Option

Description of global settings

Host

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

Port

Port to listen for incoming http connections.

PortCtl

Port number for communication with slaves.

DocRoot

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

MaxSlaves

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.

DontLog

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

AccessLog

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.

ErrorLog

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

MimeTypesSource

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.

HandleTypes

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:

mod_xcgi - treat file as XCGI script
mod_cgi - treat file as CGI script. For Perl scripts, use mod_cgi_pl module since it turns on special support like correctly passing name of interpreter, avoiding console window on Windows9x, etc.
mod_cgi_pl - treat file as CGI script written in Perl (and thus requiring Perl interpreter to execute). For Perl scripts, use mod_cgi_pl module since it turns on special support like correctly passing name of interpreter, avoiding console window on Windows9x, etc.
mod_ssi - enable Server Side Includes in the served content.
mod_asis - deliver content as-is.

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

DirectoryIndex

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.

AddHandler

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:

UnSet Env DBNAME

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

Signup for newsletter | Feedback | Affiliate!