Xitami Xitami 1.3c

| iMatix home page | Xitami home page | << | < | > | >>

Configuration

Xitami will run straight out of the box with no configuration. However, advanced users may want to modify Xitami's behaviour with respect to security, CGI, logging, etc. Xitami reads a configuration file, xitami.cfg to get information such as the logfile name and MIME types. This is how the configuration files work:

Configuration File Syntax

A configuration file defines a series of sections, each containing options. Comments are indicated by '#' at any point in the line. Blank lines are ignored. Each option takes this form: 

name = value

The option name is case insensitive. You can use '-' and '_' interchangeably. You can put spaces around the '=' if wanted. The option value is case-sensitive and may be enclosed in double quotes if necessary. To specify an empty value, use "". For example: 

form-prefix=""

The [Version] Section

This section defines the configuration file as valid for the iMatix web server. You should not delete or modify this section.

The [Server] Section

This section defines general parameters for the web server:

hostname
Specifies your fully-qualified domain name for the server. This name is used whenever the server needs to redirect a request (e.g. for image maps). You may want to provide this when configuring a virtual host. It is not usually necessary on single-hosted systems.
Default: the system hostname.
customise
Specifies a second configuration file for customised options. Anything in the customisation file replaces or adds to that defined in xitami.cfg.
Default: custom.cfg
portbase
Defines the IP port base for the server. Add 80 to this to calculate the actual port used for the HTTP service. For example, to run the server on port 6080, define portbase as 6000. We use a portbase in place of an absolute address so that multiple protocols (e.g. an ftp server embedded into Xitami) can be managed as one unit.
Default: 0 (zero)
portbasen
Specifies one or more alternate portbases; if the primary HTTP port is unavailable, will try portbase1, portbase2, etc. until a free port is found, or no further alternate portbases are found.
Default: no default.
background
If 1, the server runs as a background process, on operating systems that support this functionality. If 0, the server runs as a foreground process. Background processes are detached from their controlling terminal and must be halted by a system 'kill process' request. Foreground processes send their output to the controlling terminal and can be halted by an interrupt key (e.g. Ctrl-C).
Default: 0 (foreground)
refresh
Specifies the delay in seconds between each server refresh. At each refresh, the server does a number of administrative tasks: reload the configuration file if changed; reopen the file xitami.aut in any case; cycle the log files if necessary. The refresh rate has a minimum of 10 seconds.
Default: 15 seconds
cgi-url
Specifies the string that Xitami uses to detect that a URL is to be treated as a CGI. This value must start with '/', and can consist of one or more paths. For instance: '/cgi', '/script', '/scripts/cgi'. This string does not actually refer to a real disk directory; it is translated into a real filename using the cgi-bin option, and a heuristic - see CGI directories.
Default: /cgi-bin.
cgi-bin
Specifies the directory where CGI programs are located. This can be an absolute directory (starting with '/') or a relative directory (not starting with '/'). See the section on CGI directories for more details.
Default: cgi-bin (a subdirectory of the server working directory)
webpages
Specifies the directory root where web pages are located. This can be an absolute directory or a relative directory.
Default: webpages (a subdirectory of the server working directory)
defaultn
Specifies the default files. Up to 32 default files can be specified. When the user specifies a URL without filename, the server searches the directory for the default files, in order, from default1 to default32, until a matching file is found or the default sequence ends.
Default: default1=index.htm default2=index.html default3=default.htm default4=default.html
keep-alive
If 1, Xitami will allow browsers that support the Keep-Alive protocol to carry-out multiple requests on a single connection. This can improve performance, especially on pages with very many small files. If 0, the browser creates a new connection for each HTTP request.
Default: 0
keep-alive-max
A number greater than 1; Xitami will allow this many requests on an 'alive' connection before closing it. Setting this to 1 has the same effect as setting keep-alive to 0.
Default: 50
timeout
A 'kept-alive' connection will last this long before Xitami closes it. The timeout is specified in seconds. You can actually put this value quite high if wanted: the cost of an open connection is low and does not degrade the server performance. Anything more than a minute or so is probably not worth it.
Default: 30 seconds
error-header
Specifies the text used to preface an HTTP error message. The text may either be HTML, or a filename prefaced by '@'. If the text comes from a file, Xitami will re-read this file each time it sends an error response.
Default: <HTML><TITLE>Error</TITLE> <BODY><H1><B>
error-footer
Specifies the text used to end an HTTP error message. The text may either be HTML, or a filename prefaced by '@'. If the text comes from a file, Xitami will re-read this file each time it sends an error response.
Default:</B></H1></BODY></HTML>
translate
If 1, redirected requests are specified using a textual host name. If 0, IP numbers are used. Redirected requests are used in two specific cases: directory listings and image maps. In either case the server may return a HTTP code 302 and a URL indicating the file that the browser should retrieve. When the URL contains a host name (translate=1), the host name must be something that the browser can translate into an IP address. When DNS translation is not working (typically on a PPP connection) this won't work. When translate=0, the server uses the numeric IP address (xxx.xxx.xxx.xxx).
Default:1
debug
If 1, the server creates various debugging log files.
Default:0 (zero)

The [Alias] Section

This section lets you define multiple document roots. Each alias specifies a name and a path. For example: 

[Alias]
cdrom=G:\html

The alias name may not contain '/'. In a URL, the alias comes at the start, e.g.: 

http://127.0.0.1/cdrom/index.htm

There is no fixed limit to the number of aliases you can define.

The [Virtual-Hosts] Section

This section lets you define virtual hosts. A virtual host can be specified in two ways: by IP address (if your system has multiple IP addresses) or by name (if your system has multiple names). Each entry in the [Virtual-Hosts] section defines one virtual host, like this: 

[Virtual-Hosts]
www.rnd.imatix.com=research.cfg
253.112.23.51=home.cfg

See the section on virtual hosts for more details.

The [Mime] Section

This section defines additional MIME file types; the following MIME types are defined by default:

txt
Defines MIME type for files with extension .txt.
Default: text/plain
htm
Defines MIME type for files with extension .htm.
Default: text/html
html
Defines MIME type for files with extension .html.
Default: text/html
jpg
Defines MIME type for files with extension .jpg.
Default: image/jpeg
jpeg
Defines MIME type for files with extension .jpeg.
Default: image/jpeg
gif
Defines MIME type for files with extension .gif.
Default: image/gif
doc
Defines MIME type for files with extension .doc.
Default: application/msword

You can add to, and modify, these definitions. Note that the extension and MIME type must be specified in lowercase.

The [CGI] Section

This section controls the CGI protocol:

workdir
Defines the directory where CGI programs will run. The web server must have write access to this directory. You can tell Xitami to always use the script directory by specifying "-". (This is useful if you put scripts in various subdirectories,)
Default: . (server working directory)
environment
If 1, the CGI program gets the full web server environment, including values such as PATH. If 0, does not have access to such data. The environment data can assist a hostile attack on the host system.
Default: 1 (server environment is supplied)
http-fields
Defines whether the HTTP request header fields are passed to the CGI program or not.
Default: 1 (HTTP header fields are supplied)
http-prefix
Specifies the prefix used to identify HTTP header fields in the CGI program environment. Note that this should be different from the form_prefix, so that there is no chance of an overlap in field names. To specify 'no prefix', use http-prefix="".
Default: HTTP_
form-fields
If 1, the form data (coming from a GET or POST method) is supplied as environment variables. This can be required by some CGI programs. However, when large forms are used, this may cause the environment to be over-filled. Since the form data is also available to the CGI program on its standard input device, it can be useful to set this option to 0.
Default: 1 (form data is included in environment)
form-prefix
Specifies the prefix used to identify form data fields in the CGI program environment. To specify 'no prefix', use form-prefix="".
Default: FORM_
form-query
If 1, the form data (coming from a POST method) is supplied as the environment variable QUERY_STRING. If 0, this data is supplied as separate environment variables, and on the standard input device but not as a QUERY_STRING environment variable. Some CGI products (we know of Progress Webspeed) will barf if this is turned-on, since they do not expect input in both this string and on stdin.
Default: 1 (form data is included in QUERY_STRING)
mixed-url
If 1, allows images, HTML, and other files in the cgi-bin directory. The CGI program can refer to these using relative addressing. If 0, such files are not permitted. Note that in any case, executable files (such as Perl scripts) are always executed, never downloaded.
Default: 1 (non-executable files may be placed in /cgi-bin)
errlog
Specifies a filename for output of CGI program errors. A CGI program can send error messages to the stderr stream; these are captured in this log file.
Default: Empty (no logging of CGI errors)
timeout
The maximum time, in seconds, that a CGI program may run. This option prevents looping CGI programs from blocking the server system for more than a short period. However, you will want to tune it if you run exceptionally slow CGIs, e.g. large database searches. (Which we do not recommend; you should always aim for a response time of less than 2 seconds, and 5 seconds for 'heavy' processing.)
Default: 60
monitor
The frequency, in milliseconds, at which Xitami monitors the progress of CGI programs. If you raise this time to 500, for example, Xitami will check the CGI program's progress every 1/2 second. Anything less than 100 is not a good idea, probably, since it will slow-down the server.
Default: 200
exit-ok
If 1, CGI programs must exit with a return code of 0. On most systems this indicates that the program completed without errors. If the program exits with another return code, Xitami will show an error 501. Some languages do not let you set the return code; you can set exit-ok to 0 to remove this check.
Default: 1
debug
If 1, the server creates files containing the CGI input and output streams, called tmpxxxxx.cgi and tmpxxxxx.cgo. You can use these to debug CGI programs' output.
Default:0 (no debugging output)

The [CGI-Environment] Section

This section is used to define specific CGI environment variables. Each definition is taken literally and passed to the CGI program. This can be useful when using virtual hosts. For example: 

[CGI-Environment]
HOSTNAME=sales

The [Security] Section

This section defines server security options:

filename
Specifies the Basic Authentication file.
Default: xitami.aut
dirlist
If 1, the server will generate a directory listing for any URL that refers to a directory not containing a default file. If 0, such accesses result in a 403 Forbidden response.
Default: 1 (listings are allowed)
dynamic
If 1, the server will reopen its authentication file at each refresh. If 0, it will not. This is normally left as 1, so that you can change the authentication file without needing to stop and start the server. There is very little penalty for this reopen operation unless the file is on a very slow disk.
Default: 1 (dynamic refresh enabled)
webmask
Specifies the set of clients that can connect to the server. This is meant to provide an easy way of creating an internal web service. The webmask consists of a fixed portion, followed by '*'. For instance, to allow only clients with IP addresses in the subnet '250.12.13', specify the webmask as '250.12.13.*'.
Default: '*'; all clients.

The [ServerLog] Section

This section controls the server error and information log:

filename
Specifies the name of the server log file. If this value is "NULL" (spelling is important) then no log files are produced at all. This is equivalent to running Xitami in console mode with the -q option.
Default: xitami.log
cycle
Can be one of:
Default: never

The [AccessLog] Section

This section controls the server access log:

filename
Specifies the name of the access log file.
Default: access.log
cycle
Can be one of:
Default: never

| << | < | > | >>
| Contents | Installation | Administration | Configuration | Using CGI | Image Maps | Virtual Hosting | A Beginner's Guide | FAQ | Technical Implementation | Getting Support | Release History | License Agreement

iMatix Designed by Pieter Hintjens © 1997 iMatix