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:
- If no configuration file is present, Xitami will use internal
defaults for most values, including some basic MIME types. However
a fuller list of MIME types can come only from the config file.
- The configuration file must be in the current directory, or on the
PATH.
- You can either modify the xitami.cfg file directly (not recommended
any longer) or create a second file, defaults.cfg, and place
modified values there. This is an example of a defaults.cfg file:
[Server]
debug=1
- The name 'defaults.cfg' can itself be modified in xitami.cfg.
- Since the defaults.cfg file is not included in the Xitami
distribution, you will no longer lose customised configurations when
you re-install the web server.
- If you change the defaults.cfg file it will be automatically reloaded
by the server after a short delay (usually 60 seconds). If you did not
create defaults.cfg, Xitami will auto-reload the xitami.cfg file.
- Any command-line options (or control panel options for the GUI
versions of Xitami) override the options set in the
configuration files.
The URL '/admin' will launch the BBA. This URL is password protected so
that it is inaccessible until you have specified a new password. To enable
BBA you should modify xitami.aut and set a password for the [/admin] URL.
Note that xitami.aut is re-installed with each new version, so the better
long-term approach is to define a [Security]filename= option in
defaults.cfg.
BBA can be used in conjunction with this HTML-based help text, as regards
the various config options. At any time you can, of course, modify the
config files by hand.
To disable the BBA, remove the xiadmin entry from the [Wsx] section in
the xitami.cfg and default.cfg files.
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=""
You can put references to environment variables in the configuration file
values using this syntax: $(NAME). Note that the name must be in uppercase,
and that such references cannot be embedded.
This section defines the configuration file as valid for Xitami. You
should not delete or modify this section.
This section defines general parameters for the web server:
- 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)
- 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)
- 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.
- 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, unless it is set to
0 in which case no refresh occurs at all. (This can be used to
determine if the refresh is causing sporadic problems.)
- Default: 60 seconds
- debug
- If 1, the server creates various debugging log files. The file
request.log contains every incoming request. The file 'debug.log' in
particular logs the processing of the requests. The file 'header.log'
contains every response sent back to the browser. Use this to debug a
virtual host configuration that gives problems, or to determine the cause of
a recurrent problem.
- Default:0 (zero)
- debug-dir
- Specifies a directory for debug log files.
Xitami interprets this value as an environment variable if possible,
else as a literal directory name. If you want it to refer only to a
directory name, end it in '/'.
- Default: debug.
- temp-dir
- Specifies a directory for temporary files. The server creates these to
pass information to and from CGI programs, and if debugging is enabled, you
may find that these accumulate. Xitami interprets this value as an
environment variable if possible, else as a literal directory name. If
you want it to refer only to a directory name, end it in '/'.
- Default: temp.
- limit
- Specifies the maximum number of concurrent HTTP connections. On
systems that can handle lots of open sockets (e.g. Unix, OS/2, WinNT,
Win98), you may want to set this high. Xitami does not impose any
fixed limit. If you set this value to 0, it means 'no limit'.
- Default: 20 connections for Windows systems, no limit on others.
- 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). Currently, only implemented on UNIX systems.
- Default: 0 (foreground)
- autostart
- If 1, the server will run even if it cannot open the HTTP port.
It will retry every 5 seconds until you stop the server (which must
be done manually if the HTTP service cannot start). The autostart
option applies both to the HTTP and the FTP service. This option
is useful for systems where the network is not initially active, but
comes 'up' after some action (e.g. dialing-up). Currently it is
implemented only in the 32-bit Windows version of Xitami, partly for
various boring technical reasons, but mostly because this is the only
platform that actually needs it.
- Default: 1 (will wait until it can open its HTTP port).
- 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
- 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
- cache-defaults
- Normally, defaults pages are cached like any other. This means that if
the browser has already loaded the page, it will add a HTTP request header
'If-Modified-Since'. Xitami uses this date to determine whether to send the
page or not. In most cases, it is appropriate to leave this option enabled.
However, if you are developing several sites, you may find that the browser
shows the default page from one site when you look at another. You can
clear the browser cache and reload, but this is usually pretty tiresome.
So, disable this option, and Xitami will never cache defaults pages.
- 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>
- text-xxx
- Specifies the text used for a specific HTTP error code. 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.
The text is always prefixed by the error header and suffixed by the error
footer. You can use this for error codes 4xx and 5xx. 2xx codes are not
errors, and 3xx codes are handled by the browser without displaying any text
that the server might send. To test a specific error, you can use the
special URL 'error_test?xxx'. For instance, to simulate a 402 error (Payment
Required), use a URL like this: 'http://127.0.0.1/error_test?402'. The error
codes returned by Xitami are:
200 | Ok
|
201 | Created
|
202 | Accepted
|
203 | Partial information
|
204 | No response
|
301 | Moved
|
302 | Found
|
303 | Method
|
304 | Not modified
|
400 | Bad request
|
401 | Unauthorized
|
402 | Payment required
|
403 | Forbidden
|
404 | Not found
|
413 | Request entity too large
|
500 | Internal error
|
501 | Not implemented
|
502 | Service temporarily overloaded
|
- Default:HTTP/1.0 XXX:error text
- priority
- Specifies the server priority, on systems where this is possible
(currently only Windows NT and 95). 1=normal, 2=low, 3=high. You can set
the priority to 'low' for systems where the server should not interfere with
other processes. You can set the priority to 'high' for systems where the
server is the main process.
- ipaddress
- Specifies the IP address on which Xitami should open its HTTP
connection. If this is 0, Xitami will open its connection on all available
IP addresses. This is normally a Good Idea, since it makes configuration
much simpler on a multihomed system, and is completely correct on a
single-homed system (i.e. a system with just one IP address, which is pretty
common). If you have multiple IP addresses and want to run Xitami on just
one of these, you can specify it here using the standard dotted network
address format. This will effectively disable virtual hosting.
- Default: 0 (take any available IP address).
- 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.
- base-host
- Specifies the name of the configuration file used for the base
virtual host. You may need this option when you have virtual hosts
that all inherit values from defaults.cfg, but where the base host
needs different values.
- Default: basehost.cfg
- 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
- 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.
- defaults
- Specifies the name of the local configuration file. This file
provides the defaults that are used for all virtual hosts. Anything
in the defaults file overrides the contents of xitami.cfg.
- Default: defaults.cfg
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 '/'. It is not case sensitive.
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.
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.
This section is used to define filter programs. Filters are
programs that are run with the (usually) HTML file as input. You
can write filters in Perl, Awk, C, Rexx, or any other language that
can handle standard input/output streams. Filters are a little
like CGI programs, except that they are invoked whenever a certain
type of file is requested.
Each definition in this section consists of a file extension and
a command. The command may be with a full path, or without, if the
program is on the PATH. Xitami lets you run scripts directly under
OS/2 and Windows 95/NT, if you respect the header conventions noted
in the CGI section.
You can pass any type of input file to a filter program, with the
restriction that it must be a text file. Binary files will probably
not work under MS-DOS-like file systems. Under Unix there is no
difference between text and binary files.
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: cgi-bin (CGI-BIN script directory)
- 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
- dirlist
- If 1, the server will generate a directory listing for any
URL that refers to a CGI directory not containing a default file.
If 0, such accesses result in a 403 Forbidden response.
- Default: 0 (listings are allowed)
- msdos-style
- If 1, CGI programs and scripts get all filenames passed through the
environment and on the command line in MS-DOS format (using backslashes);
otherwise they get filenames in Unix format (using forward slashes).
Default is 0.
- 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: 0 (CGI program exit code is not checked)
- 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)
- stdio
- If 1, the server uses standard input/output streams to pass
CGI input and output data. This is suitable for languages such as
C, Perl, etc. that have access to stdin and stdout streams. When
using languages that cannot read from stdin or write to stdout,
you must set this value to 0, and refer to the CGI_STDIN and
CGI_STDOUT environment variables.
- 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)
- 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: 0 (form data is not included in QUERY_STRING)
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
This section lets you define multiple CGI program roots. Each
alias specifies a name and a path. For example:
[CGI-Alias]
demos=G:\site\demos
The alias name may not contain '/'. It is not case sensitive.
In A URL, the alias comes at the start, e.g.:
http://127.0.0.1/demos/calendar
This section defines HTTP server security options:
- filename
- Specifies the Basic Authentication file.
- Default: xitami.aut
- password-case
- If 1, passwords are case-sensitive. If 0, passwords are
always converted to lower-case before validation. If you set
this to 0, be sure to use lower-case passwords in the password
file.
- Default: 1 (case-sensitive)
- 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)
- admin
- If 1, the server will allow access to the browser-based admin pages
(BBA). If 0, the BBA agent will not be started. This is a safe way to
disable BBA access, for sites where this is not needed and poses a potential
security hole.
- Default: 1 (BBA is enabled)
- superuser
- Specifies the Superuser password. If this is "" or "-",
no superuser access is allowed. Anything else is accepted as a
password for all protected resources, including the online
administration functions. This password overrides the webmask
for any resource. So, be really careful. Okay, I
warned you. (It does not override the webmask for the entire
server.)
- Default: "" (disabled)
- webmask
- Limits 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 web mask is
one or more patterns, each of which specifies some valid or excluded
addresses. A pattern is some IP address in string format, possibly with '*'
replacing part of the end of address. For instance, the pattern
'250.12.13.*' restricts access to clients with IP addresses starting with
'250.12.13'. If you start a pattern with '!', the pattern excludes all
clients with matching addresses. A pattern '*' matches all addresses. Use
spaces and/or commas to separate patterns. The webmask 'local' has special
meaning: it restricts access to the local system, whatever its IP address
(you cannot use the word 'local' in a list of webmasks). If you want to
use the same webmask set in a number of places, or if you have a long list
of addresses, you can use '@filename' as the webmask. Enter the webmasks
in the specified file, using whitespace or blank lines freely.
Some examples:
webmask=local # grant access to local browsers only
webmask=192.* # grant access to addresses 192.* only
webmask=192.*,127.0.0.1 # 192.* and local host
webmask=!192.*,* # deny access to 192.* addresses
webmask=@iplist.txt # read webmask from a text file
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:
- startup - cycle log when the server is starts;
- hourly - cycle log each hour;
- daily - cycle log each day;
- weekly - cycle log each week;
- monthly - cycle log each month, or
- never - never cycle the log file.
- Default: never
This section controls the server access log:
- filename
- Specifies the name of the access log file.
- Default: access.log
- cycle
- Can be one of:
- startup - cycle log when the server is starts;
- hourly - cycle log each hour;
- daily - cycle log each day;
- weekly - cycle log each week;
- monthly - cycle log each month, or
- never - never cycle the log file.
- Default: never
This section defines additional MIME file types; the following
MIME types are defined by default (if xitami.cfg is not present):
- default
- Defines default MIME type for file extensions that are not
otherwise defined.
- 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. To specify a MIME type for
files with no extension, use ".=xxx/xxx".
This section controls the browser-based admin screens.
- startup
- Specifies the initial screen to show; the values for this option
are deliberately not documented.
- Default: 1 (main page).
- refresh
- Specifies whether the console information screens should refresh
automatically or not. This only works with browsers that support the
<META HTTP-EQUIV="REFRESH"> tag.
- Default: 1 (refresh on).
- rate
- Specifies the rate at which the refresh occurs, in seconds.
- Default: 10 seconds.
- capture
- Specifies whether console output is sent to a file or not.
- Default: 1 (console output is captured).
- filename
- If the capture option is set, this option specifies a filename.
- Default: console.log.
- append
- if the capture option is set, this option controls whether the
console log is cleared each time the server is started, or not.
- Default: 0 (console.log is cleared each time).
- javascript
- If 1, the BBA screens will use small amounts of JavaScript to
improve the user-interface; for instance placing the cursor on the
first input field automatically. If 0, JavaScript will not be used.
- Default: 0 (no JavaScript).
This section controls options specific to the 32-bit Windows
versions of Xitami.
- 16bit-cgi
- Defines whether 16-bit CGIs are supported or not. If they
are, all CGIs are run in a separate virtual machine. This is
safe but slow. If you use only 32-bit CGIs, you can run CGIs
faster by setting this option to 0.
- Default: 1 (support 16-bit CGIs)
- secure
- If 1, the 'Stop', 'Start', and 'Terminate' buttons on the Xitami Windows
control panel are disabled. This is intended for configurations where the
server may only be halted by an authorised administrator, using the BBA
control panel.
- Default: 0 (control panel is fully enabled)
This section is used to define web server extension (WSX) agents. A WSX
agent is written using the SMT toolkit. An example of a WSX agent is the
on-line administration agent. See the section on WSX development for
details. Each entry in this section defines a URL prefix and an agent name.
The prefix is a single word that idientifies all URLs passed to this agent.
These are the standard WSX agents that Xitami defines:
[WSX]
admin=xiadmin # Web-based administration agent "/admin"
error=xierror # Error simulation agent "/error?xxx"
You can modify this section if you want to add your own WSX
agents, or disable one of the standard agents. For example, to
disable the on-line administration feature, modify the above
entry as follows:
[WSX]
admin=""