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 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):
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
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/xcgispecifies 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 xplThat 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.htmE.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 xplThe 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-BlahThis 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