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) 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.
In this document, configuration options are specified using the notation
section:keyword, for instance 'server:debug=1' for the file example
above.
The URL '/admin' will launch the WBA. This URL is password protected so
that it is inaccessible until you have specified a new password. To enable
the WBA 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.
The WBA 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 WBA, remove the xiadmin entry from the [WSX] section in
the xitami.cfg and default.cfg files.
The URL '/setup' launches the virtual host WBA. This works like the
standard WBA, but only lets you configure the look and feel for one virtual
host. Xitami automatically launches the virtual host WBA for the correct
configuration file when you access the /setup URL through a virtual host.
The virtual host WBA does not let you change directories, define aliases, or
FTP options, and all options that impact the whole server are not shown.
This tool is designed for commercial hosting sites, and allows clients to
customise their website from a distance. You can change the URL used to
access the virtual host WBA, in the WSX configuration section.
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 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 nested.
Prior to version 2.4, Xitami used "_" and "-" interchangeably in the
config files; this is no longer the case, and Xitami uses "-" in all keys.
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.
- cgi-bin
- Specifies the directory where CGI programs are located. This can be an
absolute directory (starting with '/' or '\', if you prefer) or a relative
directory (not starting with '/' or '\').
More information is available.
- Default: ./cgi-bin.
- 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.
More information is available.
- 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.
- 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.
- 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.
- log-dir
- Specifies the directory for log files. This option applies to all log files that
Xitami creates, except debug log files. You can leave this option empty, and
specify a full path name for each log file: this allows you to put different log
files where you like.
- Default: ./logs.
- header-dir
- Specifies the directory for header files. Header files contain custom HTTP
headers, used for all files of some type. For instance, you can ask Xitami to
output the HTTP header 'Cache-Control: no-cache' for all files with the
extension '.txt' by creating a file called 'header.txt' in this directory, and
containing the HTTP header line. Each header file matches all files with the
same extension.
- Default: ./headers.
- 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: 0.
- pipe
- Specifies the HTTP throttle pipe. With a throttle pipe you can restrict the
throughput of a website to some fixed maximum, e.g. 64Kbps. This can be
useful if several websites share a single line, and you need to share this
on a quality-of-service basis. The HTTP throttle pipe is applied to all
download and upload requests to the website. You can apply a throttle pipe
to the entire HTTP server or to specific virtual hosts. Pipes are defined in the XML file 'pipedef.xml'. You can edit this file to
add new pipes; Xitami reloads this automatically after a short delay. Each
pipe is defined as several 'instances', which are simply individual pipes
that share the same characteristics. For example, the default pipedef.xml
file defines several pipes with a 64Kbps throughput. These are individual
instances of a 64Kpbs pipe. All transfers that use a specific pipe
instance share the bandwidth of that pipe instance.
- Default: .
- pipedef
- Specifies the throttle pipe definition file. This is an XML file that
follows a specific format - look at pipedef.xml for an explanation. If you
define your own throttle pipes, it's a good idea to copy pipedef.xml to
something else (e.g. 'mypipes.xml') and then change that. This avoids
unpleasant surprises when you upgrade your Xitami version. Note that we
may change the format of the pipe definition file in the future.
- Default: pipedef.xml.
- 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.
- 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, mostly because
this is the only platform that actually needs it.
- Default: 0.
- recover
- If 1, the server will try to recover from fatal errors using an internal crash
recovery system. This currently only works under Windows. When this option is 0,
Xitami will show a fatal error message and (under Windows) allow the web
administrator to continue.
- Default: 0.
- dirsort
- Specifies the sort order for directory listings. You can sort by file name, extension, size, or modification date/time using any
combination of the letters 'n', 'x', 's', and 't'. For instance, dirsort=xnt
will sort by extension, then name, then time. To sort in reverse order, use
capital letters. For instance to show the most recent files first, use
dirsort=T.
- Default: n.
- dir-script
- Specifies the GSL script that is used to format HTTP directory listings. GSL is a scripting language used by the iMatix GSLgen tool, incorporated into
Xitami. A GSL script is a flexible way to format output texts - see the supplied
script for more information. It's a good idea, if you change this script, to
copy it and change the copy. Otherwise your changes will probably be lost
when/if you ever upgrade your Xitami installation.
- Default: templates/httpdir.gsl.
- supervisor
- Enables or disables the supervisor agent. When enabled, the supervisor
agent will regularly check for old log files and temporary files, and remove
these. Temporary files are deleted when they are over one day old, and log
files are deleted when they are more than two weeks old.
- Default: 0.
- keep-alive-max
- A number greater than 1; Xitami will allow this many requests
on a persistent connection before closing it. Setting this to 1 has
the same effect as disabling persistent connections (not recommended).
- Default: 50.
- timeout
- A persistent 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.
- default1
- 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. Note that Xitami
automatically looks for .html extensions if a .htm file is not found.
- Default: index.htm.
- default2
- 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. Note that Xitami
automatically looks for .html extensions if a .htm file is not found.
- Default: default.htm.
- 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.
To fix this disable this option and Xitami will never cache defaults pages.
- Default: 1.
- use-error-script
- Specifies whether you want to use an error script or not. When enabled, Xitami
will pass all HTTP errors to the specified GSL script for processing. This is
an easy and powerful way to customise error messages in a single place. By
default this is disabled, for compatability with earlier releases of Xitami, but
an error script is supplied as standard, and used if you enable this option.
- Default: 0.
- error-script
- Specifies the GSL script that is used to format HTTP error messages. If you use
this option, Xitami ignores error-header, text-xxx, and error-footer options. GSL is a scripting language used by the iMatix GSLgen tool, incorporated into
Xitami. A GSL script is a flexible way to format output texts - see the supplied
script for more information. It's a good idea, if you change this script, to
copy it and change the copy. Otherwise your changes will probably be lost
when/if you ever upgrade your Xitami installation.
- Default: templates/errors.gsl.
- 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: @errors/header.htm.
- 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: @errors/footer.htm.
- text-400
- Specifies the text used for the HTTP error 'Bad request'. This text can
either be HTML, or be a filename prefaced by '@'. The text is always
prefixed by the error header and suffixed by the error footer.
- Default: @errors/text-400.htm.
- text-401
- Specifies the text used for the HTTP error 'Unauthorized'.
- Default: @errors/text-401.htm.
- text-402
- Specifies the text used for the HTTP error 'Payment required'.
- Default: @errors/text-402.htm.
- text-403
- Specifies the text used for the HTTP error 'Forbidden'.
- Default: @errors/text-403.htm.
- text-404
- Specifies the text used for the HTTP error 'Not found'.
- Default: @errors/text-404.htm.
- text-412
- Specifies the text used for the HTTP error 'Precondition failed'.
- Default: @errors/text-412.htm.
- text-413
- Specifies the text used for the HTTP error 'Request entity too large'.
- Default: @errors/text-413.htm.
- text-500
- Specifies the text used for the HTTP error 'Internal error'.
- Default: @errors/text-500.htm.
- text-501
- Specifies the text used for the HTTP error 'Not implemented'.
- Default: @errors/text-501.htm.
- text-502
- Specifies the text used for the HTTP error 'Service temporarily overloaded'.
- Default: @errors/text-502.htm.
- 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.
- Default: 1.
- ipaddress
- Specifies the IP address on which Xitami should open its HTTP
connection. If this is *, 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 IP-based virtual hosting.
- Default: *.
- 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. the FTP server embedded into Xitami)
can be managed as one unit.
- Default: 0.
- 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.
- 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. The default for this value is
the system host name, or virtual host name for virtual hosts.
- Default: .
- 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 HTTP aliases. An alias is a virtual directory that
points to some arbitrary directory on the server computer. This can be outside
the normal webpages directory, e.g. on another drive. Aliases can be structured
into multiple levels, e.g. /pub and /pub/documents can both be defined as
individual aliases. HTTP aliases always come at the start of the URL. An HTTP
alias can also refer to a complete filename, in which case that file will act as
the default file for the alias. To define an alias, specify the alias name and
the directory it refers to.
This is an example of enties in the [Alias] section:
[Alias]
cdrom=G:\html
private/pub=i:\pub
private/doc=i:\docs\current
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). To define a virtual host, specify the
virtual IP address or host name and the name of a configuration file .
This is an example of enties in the [Virtual-Hosts] section:
[Virtual-Hosts]
www.rnd.imatix.com=research.cfg
253.112.23.51=home.cfg
More information is available.
This section lets you define filter programs. To define a filter, specify a file
extension with a leading dot and the filter command. The command may be with a
full path, or without, if the program is on the PATH.
This is an example of enties in the [Filter] section:
[Filter]
.php=c:\php3\php.exe
More information is available.
This section controls the CGI protocol.
- enabled
- Allows you to disable CGI handling in one stroke. If this is 1, URLs
that translate to a CGI are allowed. If this is 0, URLs that translate to a
CGI are rejected with a code 501 (Not implemented).
- Default: 1.
- 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.) This option applies to filters too.
- Default: -.
- wildcard
- Defines whether the CGI URL indicator ('/cgi-bin') is allowed anywhere
in the URL, or only at the start. If 1, it is allowed anywhere in the URL.
If 0, it may come only at the start of the URL. Note that setting this to
1 opens a significant security hole, if you also allow people to FTP files
into the HTTP area. As soon as someone creates a directory called /cgi-bin,
they can upload, and execute, CGI programs. In some configurations this is
desirable. In other configurations (e.g. if you allow your users to upload
CGI scripts, or if you do not do FTP uploads into the HTTP space) it can be
desirable.
- Default: 0.
- 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.) If you set this to zero, Xitami lets CGIs run for
an arbitrarily long time (actually one hour) before killing them.
- 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.
- 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: 0.
- 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.
- 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.
- Default: 1.
- 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.
- 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: cgierr.log.
- 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.
- passargs
- If 1, the server will pass URL arguments (?arg1+arg2+...)to CGI programs.
If 0, these are not passed. Under some systems, this can pose a security
problem if devious hackers manage to pass arguments to shell scripts that are
interpreted as commands or filters. In any case, Xitami replaces these
'dangerous' characters: |, >, < by spaces.
- Default: 0.
- http-fields
- Defines whether the HTTP request header fields are passed to the CGI
program or not.
- Default: 1.
- http-prefix
- Defines whether the HTTP request header fields are passed to the CGI
program or not.
- 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-prefix
- 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: 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.
This section lets you define specific CGI environment variables. Each definition
is taken literally and passed to the CGI program. This can be useful when using
virtual hosts.
This is an example of enties in the [Cgi-Environment] section:
[CGI-Environment]
HOSTNAME=sales
This section lets you define CGI aliases. A CGI alias is a virtual directory
that points to some arbitrary directory on the server computer and contains CGI
scripts or programs. This combines the functions of the CGI url '/cgi-bin' and
an HTTP alias. To define a CGI alias, specify the alias name and the directory
it refers to.
This is an example of enties in the [Cgi-Alias] section:
[CGI-Alias]
demos=G:\site\demos
This section controls Xitami's built-in server-side includes (SSI) handling.
More information is available.
- enabled
- Lets you enable/disable SSI handling.
- Default: 1.
- timefmt
- Specifies the format for times shown by SSI pages.
- Default: %A, %d-%b-%y %H:%M:%S %Z.
- sizefmt
- Specifies whether size should be shown as bytes or as abbreviations (Kb,
Mg). Anything other than the string "bytes" is taken to mean that sizes are
shown as abbreviations.
- Default: bytes.
- timeout
- The timeout for CGI programs called from the SSI agent.
- Default: 30.
- errmsg
- Error message shown when an SSI command fails. The %s symbol is replaced
by the cause of the problem.
- Default:
[xitami SSI: %s].
- exec
- If 1, allows CGIs to be executed using the #exec command. Since this is
a security weakness, this option is switched-off by default.
- Default: 0.
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.
- 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. If the directory URL is followed by '?sort=', then the
following string is used to sort the directory, and override the dirsort option.
For instance: 'http://www.imatix.com/pub/xitami/?sort=T'.
- Default: 1.
- admin
- If 1, the server will allow access to the web-based administration pages
(WBA). If 0, the WBA agent will not be started. This is a safe way to
disable WBA access, for sites where this is not needed and poses a potential
security hole.
- Default: 1.
- 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. It does not override the
webmask for the entire server.
- Default: .
- safepaths
- If 1, the server will refuse access to 'unsafe' URLs, which is a notion
that Microsoft invented when they allowed the same file to have a short and
a long filename. When this is enabled, Xitami rejects any URLs that contain
a directory name which can be translated to a different long name and the
user receives a 403 error message. If 0, this check is not done.
- Default: 1.
- webmask
- Limits the set of clients that can connect to the HTTP server. This provides
an easy way of creating an extranet web service - you can put your server on the
Internet, but allow access to a fixed set of IP addresses. Use 'webmask=local' to specify just local addresses, or 'webmask=item,item,...'
to specify one or more types of access. Each item allows or excludes some IP
address(es): '250.12.13.*' allows matching addresses, '!250.12.13.*' excludes
matching addresses (but does not allow others). '!250.12.13.*,*' excludes one
set of addresses and allows all others. 'webmask=@iplist.txt' reads the list of
webmasks from a text file.
More information is available.
- Default: *.
- setuid
- Specifies whether the server switches to a safe user id and group at startup.
This only works under Unix systems. When you use this option, you can be certain
that the server runs with the minimum necessary privileges.
- Default: 0.
- setuid-user
- When the security:setuid option is enabled, switches to this user id after
opening its HTTP and FTP ports. You should ensure that the user id exists and
has suitable authority to write to log files, etc.
- Default: nobody.
- setuid-group
- When the security:setuid option is enabled, switches to this group id after
opening its HTTP and FTP ports. You should ensure that the group id exists and
has suitable authority to write to log files, etc. If you set this option to an
empty value, e.g. "", Xitami does not change the group id.
- Default: nogroup.
- cgi-username
- Specifies the username under which CGIs will be run. If blank, runs under the
same user id as started Xitami.
- Default: .
- cgi-password
- Specifies a password to start CGIs under the specified user id. This is
required under Windows only.
- Default: .
- cgi-groupname
- Specifies a password to start CGIs under the specified user id. This is
required under Windows only.
- Default: .
This section controls the server error and information log.
- enabled
- Specifies whether server logging is enabled or not.
- Default: 1.
- filename
- Specifies the name of the server log file.
- Default: xitami.log.
- cycle
- Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
- Default: daily.
- cycle-how
- Specifies how to cycle the log file.
- Default: rename.
- cycle-time
- Specifies the time of day, or minute past the hour, that the log file is cycled.
- Default: 00:00.
- cycle-day
- Specifies the day of the week or month that the log file is cycled.
- Default: 0.
- cycle-size
- Specifies the maximum size in Kbytes for the log file; after that it is cycled.
- Default: 0.
- cycle-lines
- Specifies the maximum size in lines for the log file; after that it is cycled.
- Default: 0.
- cycle-arg
- Specifies an argument used for the various cycle-how options. When renaming a
file or concatenating it onto another, Xitami uses the argument as a time-stamped
filename. When moving the file, Xitami uses the argument as a time-stamped
directory name. When processing the file through an arbitrary command, it uses
the argument as a time-stamped command string. Xitami does not use the argument
when deleting log files. Format this argument from any of the following
timestamp fiels, mixed with other text.
- Default: xi%yy%mm%dd.log.
This section controls the server access log, recording HTTP hits.
- enabled
- Specifies whether logging is enabled or not.
- Default: 1.
- filename
- Specifies the name of the log file.
- Default: access.log.
- local
- Specifies whether to include local addresses or not.
- Default: 1.
- format
- Specifies the log file format. The log file format you use needs to be
compatible with whatever tool you use to analyze log files and build statistics.
The most common tools work with an extended form of the NCSA log file format,
also called 'common log file format'. We call this "CLFX". An other
commonly-used format is that produced by Microsoft web servers. Xitami also
creates log files in two XML formats, which you can easily process using GSLgen
to you create arbitrary reports, statistics, and HTML analyses. Lastly, you can
create your own format, for specific purposes.
- Default: CLFX.
- custom
- Custom log file format. This is an arbitrary text string that contains symbols
as listed below. Symbols are enclosed by $( and ) in the string.
- Default: .
- translate
- Specifies whether to do reverse-DNS translations of the logged IP addresses, or
not. Reverse-DNS translation can take some time, and if you need log file data
quickly, leave this disabled. Enabling reverse-DNS translations will not slow-
down Xitami.
- Default: 0.
- header
- Specifies one or more lines of text that will be copied into new log files
as they are created during server startup or log file cycling.
- Default: .
- cycle
- Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
- Default: daily.
- cycle-how
- Specifies how to cycle the log file.
- Default: rename.
- cycle-time
- Specifies the time of day, or minute past the hour, that the log file is cycled.
- Default: 00:00.
- cycle-day
- Specifies the day of the week or month that the log file is cycled.
- Default: 0.
- cycle-size
- Specifies the maximum size in Kbytes for the log file; after that it is cycled.
- Default: 0.
- cycle-lines
- Specifies the maximum size in lines for the log file; after that it is cycled.
- Default: 0.
- cycle-arg
- Specifies an argument used for the various cycle-how options. When renaming a
file or concatenating it onto another, Xitami uses the argument as a time-stamped
filename. When moving the file, Xitami uses the argument as a time-stamped
directory name. When processing the file through an arbitrary command, it uses
the argument as a time-stamped command string. Xitami does not use the argument
when deleting log files. Format this argument from any of the following
timestamp fiels, mixed with other text.
- Default: ac%yy%mm%dd.log.
This section controls the server error log, recording HTTP errors.
- enabled
- Specifies whether logging is enabled or not.
- Default: 1.
- filename
- Specifies the name of the log file.
- Default: errors.log.
- local
- Specifies whether to include local addresses or not.
- Default: 1.
- format
- Specifies the log file format. The log file format you use needs to be
compatible with whatever tool you use to analyze log files and build statistics.
The most common tools work with an extended form of the NCSA log file format,
also called 'common log file format'. We call this "CLFX". An other
commonly-used format is that produced by Microsoft web servers. Xitami also
creates log files in two XML formats, which you can easily process using GSLgen
to you create arbitrary reports, statistics, and HTML analyses. Lastly, you can
create your own format, for specific purposes.
- Default: CLFX.
- custom
- Custom log file format. This is an arbitrary text string that contains symbols
as listed below. Symbols are enclosed by $( and ) in the string.
- Default: .
- translate
- Specifies whether to do reverse-DNS translations of the logged IP addresses, or
not. Reverse-DNS translation can take some time, and if you need log file data
quickly, leave this disabled. Enabling reverse-DNS translations will not slow-
down Xitami.
- Default: 0.
- header
- Specifies one or more lines of text that will be copied into new log files
as they are created during server startup or log file cycling.
- Default: .
- cycle
- Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
- Default: daily.
- cycle-how
- Specifies how to cycle the log file.
- Default: rename.
- cycle-time
- Specifies the time of day, or minute past the hour, that the log file is cycled.
- Default: 00:00.
- cycle-day
- Specifies the day of the week or month that the log file is cycled.
- Default: 0.
- cycle-size
- Specifies the maximum size in Kbytes for the log file; after that it is cycled.
- Default: 0.
- cycle-lines
- Specifies the maximum size in lines for the log file; after that it is cycled.
- Default: 0.
- cycle-arg
- Specifies an argument used for the various cycle-how options. When renaming a
file or concatenating it onto another, Xitami uses the argument as a time-stamped
filename. When moving the file, Xitami uses the argument as a time-stamped
directory name. When processing the file through an arbitrary command, it uses
the argument as a time-stamped command string. Xitami does not use the argument
when deleting log files. Format this argument from any of the following
timestamp fiels, mixed with other text.
- Default: er%yy%mm%dd.log.
This section configures the Xitami dynamic DNS (DDNS) client. You can define
multiple DDNS registrations by duplicating this section of the configuration
file and naming the extra sections [Ddns1], [Ddns2], etc. Xitami looks for
these in order, and stops when it can't find one.
This is an example of enties in the [Ddns] section:
[Ddns]
enabled=1
refresh=3600
service=localhost
domain=my.ddns.test
username=me@localhost
password=FurkYFurt
[Ddns1]
enabled=1
service=xitami.net
domain=myhost.xitami.net
username=joe23@aol.com
password=TZO-xxxx-xxxx-xxxx-xxxx
More information is available.
- enabled
- Tells Xitami whether to sign-on to the DDNS service at start-up or not.
This is normally switched off when you don't use DDNS and switched on when
you do.
- Default: 0.
- filename
- Specifies the DDNS definition file. This is an XML file that follows a
specific format - look at ddnsdef.xml for an explanation. If you define
your own customised DDNS services, it's a good idea to copy ddnsdef.xml to
something else (e.g. 'myddnss.xml') and then change that. This avoids
unpleasant surprises when you upgrade your Xitami version. Note that we may
change the format of the DDNS definition file in the future.
- Default: ddnsdef.xml.
- refresh
- Xitami will automatically refresh its DDNS connections if you set this to a
non-zero value. This delay is measured in seconds.
- Default: 3600.
- service
- Defines the DDNS service to use.
- Default: localhost.
- domain
- Defines the dynamic domain name you are using. This must be the
complete domain name, for instance 'myhost.xitami.net'.
- Default: -.
- username
- Defines your username. Usually you define this when you register your
DDNS name. For Xitami.Net and tzo.com, it is an e-mail address.
- Default: -.
- password
- Defines your password. Usually you define this when you register your
DDNS name. For Xitami.Net and tzo.com, this is a key of the form
"TZO-xxxx-xxxx-xxxx-xxxx". For ns1.net, the password is sent to you when
you register.
- Default: -.
This section defines the configuration of the reverse-DNS lookups used by
Xitami to translate IP addresses for its access log files.
- primary-server
- Defines the primary DNS server used for lookups. This value is mandatory for
RDNS lookups. Specify it as an dotted IP address.
- Default: 127.0.0.1.
- secondary-server
- Defines a secondary DNS server, if one is available. This will provide a backup
RDNS server if the primary server does not respond. Specify it as an dotted IP
address.
- Default: .
- recurse-lookups
- Specifies whether Xitami uses recursive lookups or not. Depending on the DNS
configuration, this can be faster or slower than non-recursive lookups.
- Default: 1.
- debug
- Specifies whether Xitami should output trace entries for its RDNS work.
If 1, each RDNS lookup sends trace information to debug.log. Use this if
you are having problems getting reverse-DNS lookups to work.
- Default: 0.
This section lets you define MIME types. A MIME type is information sent to the
browser with each file, telling the browser how to handle the file. Specify each
MIME type as a file extension and the corresponding MIME type. Note that a large
set of MIME types are loaded as standard. The MIME type 'default' is used for
file extensions that don't match anything else. The file extension and MIME type
must be specified in lowercase. To specify a MIME type for files with no
extension, use ".=xxx/xxx".
This is an example of enties in the [Mime] section:
[Mime]
default=*/* # Default MIME type
htm=text/html
html=text/html
.=text/plain # Files with no extension
gif=image/gif
jpeg=image/jpeg
jpg=image/jpeg
doc=application/msword
These entries are loaded by default:
| Entry: | Definition |
|---|
| Default MIME type |
| default | */* |
| Text MIME types |
| . | text/plain |
| etx | text/x-setext |
| htm | text/html |
| html | text/html |
| htp | text/html |
| rtx | text/richtext |
| tsv | text/tab-separated-values |
| txt | text/plain |
| Image MIME types |
| fh | image/x-freehand |
| fh4 | image/x-freehand |
| fh5 | image/x-freehand |
| fh7 | image/x-freehand |
| fhc | image/x-freehand |
| gif | image/gif |
| ief | image/ief |
| jpe | image/jpeg |
| jpeg | image/jpeg |
| jpg | image/jpeg |
| pbm | image/x-portable-bitmap |
| pgm | image/x-portable-graymap |
| png | image/png |
| pnm | image/x-portable-anymap |
| ppm | image/x-portable-pixmap |
| ras | image/x-cmu-raster |
| rgb | image/x-rgb |
| tif | image/tiff |
| tiff | image/tiff |
| xbm | image/x-xbitmap |
| xpm | image/x-xpixmap |
| xwd | image/x-xwindowdump |
| Video MIME types |
| avi | video/msvideo |
| mov | video/quicktime |
| movie | video/x-sgi-movie |
| mpe | video/mpeg |
| mpeg | video/mpeg |
| mpg | video/mpeg |
| qt | video/quicktime |
| qtv | video/quicktime |
| Audio MIME types |
| aif | audio/x-aiff |
| aifc | audio/x-aiff |
| aiff | audio/x-aiff |
| au | audio/basic |
| m3u | audio/mpegurl |
| mid | audio/midi |
| mp3 | audio/mpeg |
| mp3url | audio/mpegurl |
| ra | audio/x-realaudio |
| ram | audio/x-pn-realaudio |
| rm | audio/x-pn-realaudio |
| rmi | audio/midi |
| rpm | audio/x-pn-realaudio-plugin |
| snd | audio/basic |
| wav | audio/wav |
| Application MIME types |
| aab | application/x-authorware-bin |
| aam | application/x-authorware-map |
| aas | application/x-authorware-seg |
| ai | application/postscript |
| bcpio | application/x-bcpio |
| bin | application/octet-stream |
| cdf | application/x-netcdf |
| cpio | application/x-cpio |
| csh | application/x-csh |
| dcr | application/x-director |
| dir | application/x-director |
| doc | application/msword |
| dvi | application/x-dvi |
| dxr | application/x-director |
| eps | application/postscript |
| exe | application/octet-stream |
| gtar | application/x-gtar |
| gz | application/x-gzip |
| hdf | application/x-hdf |
| jar | application/java-archive |
| js | application/x-javascript |
| latex | application/x-latex |
| ltx | application/x-latex |
| lzh | application/x-lzh |
| man | application/x-troff-man |
| me | application/x-troff-me |
| ms | application/x-troff-ms |
| nc | application/x-netcdf |
| oda | application/oda |
| pdf | application/pdf |
| ps | application/postscript |
| roff | application/x-troff |
| rtf | application/rtf |
| sh | application/x-sh |
| shar | application/x-shar |
| spl | application/futuresplash |
| src | application/x-wais-source |
| sv4cpio | application/x-sv4cpio |
| sv4crc | application/x-sv4crc |
| swf | application/x-shockwave-flash |
| t | application/x-troff |
| tar | application/tar |
| tcl | application/x-tcl |
| tex | application/x-tex |
| texi | application/x-texinfo |
| texinfo | application/x-texinfo |
| tgz | application/x-gzip |
| tr | application/x-troff |
| txi | application/x-texinfo |
| ustar | application/x-ustar |
| zip | application/zip |
| VRML MIME types |
| wrl | x-world/x-vrml |
| wrz | x-world/x-vrml |
This section controls the browser-based admin screens.
- startup
- Specifies the initial screen to show; the values for this option
are deliberately not documented. Change this option only using the WBA.
- Default: 1.
- 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. On most modern browsers, the refresh option causes warning messages.
- Default: 0.
- rate
- Specifies the rate at which the refresh occurs, in seconds.
- Default: 10.
- capture
- Specifies whether console output is sent to a file or not.
- Default: 1.
- 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.
- javascript
- If 1, the WBA 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. In general enabling JavaScript
will give better results.
- Default: 1.
- large-icons
- If 1, the WBA screens will show large icons on the icon bar. If 0, they will
show small icons with only images, no text labels.
- Default: 1.
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: 0.
- 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 WBA control panel.
- Default: 0.
- service-name
- This option is used under Windows NT for the NT service version of Xitami. You
can only change this by manually editing defaults.cfg; it is not shown in the
WBA. Change this before installing xiwinnt. You can use this option to install
multiple instances of Xitami each with a different service name and title (as
defined by the win32:service-text option). You will need a separate working
directory for each such Xitami service that you start.
- Default: Xitami.
- service-text
- This option is used under Windows NT for the NT service version of Xitami. You
can only change this by manually editing defaults.cfg; it is not shown in the
WBA. To enable the change, run 'xiwinnt -u', then 'xiwinnt -i'.
- Default: Xitami Web Server.
This section lets you define web server extension (WSX) agents. An example of a
WSX agent is the WBA agent. Each entry in this section defines a URL prefix and
an agent name. The prefix identifies all URLs passed to this agent, and consists
of one or more directory names separated by '/'. To disable a preloaded WSX
agent, clear the agent name.
This is an example of enties in the [Wsx] section:
[WSX]
admin=xiadmin # Web-based administration agent "/admin"
error="" # Error simulation agent disabled
More information is available.
These entries are loaded by default:
| Entry: | Definition |
|---|
| Preloaded WSX agents |
| .gsl | xixxml |
| .map | xiimap |
| .shtm | xixssi |
| .shtml | xixssi |
| .ssi | xixssi |
| .xml | xixxml |
| admin | xiadmin |
| error | xierror |
This section controls Xitami's FTP service.
- enabled
- Specifies whether the FTP service is enabled or not. If you change this, restart
Xitami for the changes to take effect.
- Default: 1.
- root
- Specifies the root directory for FTP logins, unless a specific directory is
defined for the current user.
- Default: ./ftproot.
- port
- Specifies the FTP connection port. The port is shifted by the portbase specified
for the main HTTP service. For instance if you specify a port 21, and a portbase
of 8000, your server will accept FTP connections on port 8021 and HTTP
connections on port 8080.
- Default: 21.
- timeout
- Specifies the time in seconds after which inactive control connections are
closed. An FTP session requires one control connection, plus one data connection
during file transfers. You should tune this timeout to suit the requirements of
your system. For instance, under an OS like Windows 95, sockets are a limited
resource, so a shorter timeout is a good idea. For sites with a small user
group, you can use high timeouts, which users generally prefer.
- Default: 300.
- limit
- Specifies the maximum number of users that may login at once. On systems that
can handle lots of open sockets (e.g. Unix, OS/2, WinNT, Win98), you may want to
increase this. Xitami does not impose any fixed limit. If you set this value to
0, it means 'no limit'.
- Default: 25.
- pipe
- Specifies the default FTP throttle pipe. With a throttle pipe you can
restrict the throughput of a FTP site to some fixed maximum, e.g. 64Kbps.
This can be useful if several FTP sites share a single line, and you need
to share this on a quality-of-service basis. The FTP throttle pipe is used
for uploads and downloads for the FTP service, except where the profile for
a user specifies a different throttle pipe. Pipes are defined in the XML file 'pipedef.xml'. You can edit this file to
add new pipes; Xitami reloads this automatically after a short delay. Each
pipe is defined as several 'instances', which are simply individual pipes
that share the same characteristics. For example, the default pipedef.xml
file defines several pipes with a 64Kbps throughput. These are individual
instances of a 64Kpbs pipe. All transfers that use a specific pipe
instance share the bandwidth of that pipe instance.
- Default: .
- user-file
- Specifies the name of the FTP user definition file.
- Default: ftpusers.aut.
- directory-file
- Specifies the name of the directory definition file.
- Default: ftpdirs.aut.
- dirsort
- Specifies the sort order for directory listings. You can sort by file name, extension, size, or modification date/time using any
combination of the letters 'n', 'x', 's', and 't'. For instance, dirsort=xnt
will sort by extension, then name, then time. To sort in reverse order, use
capital letters. For instance to show the most recent files first, use
dirsort=T.
- Default: n.
- message-script
- Specifies the GSL script that is used to format FTP messages. If you use this
option, Xitami ignores the welcome, signoff, and login-text options. GSL is a scripting language used by the iMatix GSLgen tool, incorporated into
Xitami. A GSL script is a flexible way to format output texts - see the supplied
script for more information. It's a good idea, if you change this script, to
copy it and change the copy. Otherwise your changes will probably be lost
when/if you ever upgrade your Xitami installation.
- Default: templates/ftpmesg.gsl.
- welcome
- Specifies a text to be shown when a user connects to the FTP server. This can be
literal text, or the name of a file, preceded by '@'. The file can contain up to
2000 characters. Any lines that start with '#' are ignored as comments. If you
modify this file, it is safest to make a copy (call it welcome.txt or something)
and change this option to refer to the changed file. This avoids unpleasant
surprises when you reinstall the next latest greatest version of Xitami.
- Default: @ftphello.txt.
- signoff
- Specifies a text to be shown when a user ends the FTP session. This can be
literal text, or the name of a file, preceded by '@'. The file can contain up to
2000 characters. Any lines that start with '#' are ignored as comments. If you
modify this file, it is safest to make a copy (call it goodbye.txt or something)
and change this option to refer to the changed file. This avoids unpleasant
surprises when you reinstall the next latest greatest version of Xitami.
- Default: @ftpadios.txt.
- login-text
- Specifies a text to be shown when a user logs-in to the FTP server. This can be
literal text, or the name of a file, preceded by '@'. The file can contain up to
2000 characters. Any lines that start with '#' are ignored as comments. If you
modify this file, it is safest to make a copy (call it login.txt or something)
and change this option to refer to the changed file. Xitami will search for this
file first in the user's login directory, then in the main Xitami directory.
- Default: @ftplogin.txt.
- user-at-host
- This flag controls whether Xitami allows virtual hosts using the syntax
'username@hostname'. This syntax is supported by some FTP clients, and allows
you to use multiple FTP virtual hosts on a single IP address.
- Default: 1.
- email-check
- If 1, the FTP server will check that the e-mail address supplied for anonymous
logins is a valid address. The nature of the check is not documented (it may
just look for an '@' in the address).
- Default: 0.
- http-aliases
- Specifies whether the HTTP [Alias] section should be used by the FTP service.
This can be useful in configurations where you want to share the same data
between services, but it can be a security risk if you want to use FTP aliases
to access directories outside the HTTP space.
- Default: 0.
- soft-quota
- Specifies the default soft quota for FTP users who are subject to a quota. You
can also specify quota values for individual users. This value is specified in
megabytes, as a decimal number (using a decimal point, not comma, even in
Europe). When a user exceeds their soft quota, they start getting warning
messages.
- Default: 2.5.
- hard-quota
- Specifies the default hard quota for FTP users who are subject to a quota. You
can also specify quota values for individual users. This value is specified in
megabytes, as a decimal number. When a user exceeds their hard quota, they
cannot upload new files.
- Default: 5.
- webmask
- Specifies the set of clients that can connect to the FTP server. Use 'webmask=local' to specify just local addresses, or 'webmask=item,item,...'
to specify one or more types of access. Each item allows or excludes some IP
address(es): '250.12.13.*' allows matching addresses, '!250.12.13.*' excludes
matching addresses (but does not allow others). '!250.12.13.*,*' excludes one
set of addresses and allows all others. 'webmask=@iplist.txt' reads the list of
webmasks from a text file.
More information is available.
- Default: *.
- password-case
- If 1, FTP 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 only
lower-case passwords in the password file.
- Default: 1.
- ipaddress
- The IP address used for FTP connections.
- Default: *.
- data-port
- Specifies the port at which data connections will be made. Xitami scans for free
ports, so this is simply the start of a range of ports. The port is shifted by
whatever value was used for the server portbase.
- Default: 20.
- force-ip
- Indicates whether passive connections must be forced to the IP address specified
in the 'passiveip' option.
- Default: 0.
- passiveip
- The IP address used for passive FTP data connections. This can be set to the
external network address for a server that is placed behind a firewall.
- Default: main IP address.
This section lets you define FTP aliases. An FTP alias looks like a root
directory for ftp users, and point to some arbitrary directory on the server.+
The alias name itself may not contain '/'. It is not case sensitive. FTP aliases
are only shown to 'root' users, i.e. those with an empty root value, or those
who have the 'aliases=1' option defined. Aliases are shown only if the user has
GET access, and if the specified user's root directory actually exists.
This is an example of enties in the [Ftp-Alias] section:
[FTP-Alias]
demos=G:\site\demos
This section controls the server access log, recording FTP hits.
- enabled
- Specifies whether logging is enabled or not.
- Default: 1.
- filename
- Specifies the name of the log file.
- Default: access.log.
- local
- Specifies whether to include local addresses or not.
- Default: 1.
- format
- Specifies the log file format. The log file format you use needs to be
compatible with whatever tool you use to analyze log files and build statistics.
The most common tools work with an extended form of the NCSA log file format,
also called 'common log file format'. We call this "CLFX". An other
commonly-used format is that produced by Microsoft web servers. Xitami also
creates log files in two XML formats, which you can easily process using GSLgen
to you create arbitrary reports, statistics, and HTML analyses. Lastly, you can
create your own format, for specific purposes.
- Default: CLFX.
- custom
- Custom log file format. This is an arbitrary text string that contains symbols
as listed below. Symbols are enclosed by $( and ) in the string.
- Default: .
- translate
- Specifies whether to do reverse-DNS translations of the logged IP addresses, or
not. Reverse-DNS translation can take some time, and if you need log file data
quickly, leave this disabled. Enabling reverse-DNS translations will not slow-
down Xitami.
- Default: 0.
- header
- Specifies one or more lines of text that will be copied into new log files
as they are created during server startup or log file cycling.
- Default: .
- cycle
- Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
- Default: daily.
- cycle-how
- Specifies how to cycle the log file.
- Default: rename.
- cycle-time
- Specifies the time of day, or minute past the hour, that the log file is cycled.
- Default: 00:00.
- cycle-day
- Specifies the day of the week or month that the log file is cycled.
- Default: 0.
- cycle-size
- Specifies the maximum size in Kbytes for the log file; after that it is cycled.
- Default: 0.
- cycle-lines
- Specifies the maximum size in lines for the log file; after that it is cycled.
- Default: 0.
- cycle-arg
- Specifies an argument used for the various cycle-how options. When renaming a
file or concatenating it onto another, Xitami uses the argument as a time-stamped
filename. When moving the file, Xitami uses the argument as a time-stamped
directory name. When processing the file through an arbitrary command, it uses
the argument as a time-stamped command string. Xitami does not use the argument
when deleting log files. Format this argument from any of the following
timestamp fiels, mixed with other text.
- Default: ac%yy%mm%dd.log.
This section controls the FTP error log.
- enabled
- Specifies whether logging is enabled or not.
- Default: 1.
- filename
- Specifies the name of the log file.
- Default: errors.log.
- local
- Specifies whether to include local addresses or not.
- Default: 1.
- format
- Specifies the log file format. The log file format you use needs to be
compatible with whatever tool you use to analyze log files and build statistics.
The most common tools work with an extended form of the NCSA log file format,
also called 'common log file format'. We call this "CLFX". An other
commonly-used format is that produced by Microsoft web servers. Xitami also
creates log files in two XML formats, which you can easily process using GSLgen
to you create arbitrary reports, statistics, and HTML analyses. Lastly, you can
create your own format, for specific purposes.
- Default: CLFX.
- custom
- Custom log file format. This is an arbitrary text string that contains symbols
as listed below. Symbols are enclosed by $( and ) in the string.
- Default: .
- translate
- Specifies whether to do reverse-DNS translations of the logged IP addresses, or
not. Reverse-DNS translation can take some time, and if you need log file data
quickly, leave this disabled. Enabling reverse-DNS translations will not slow-
down Xitami.
- Default: 0.
- header
- Specifies one or more lines of text that will be copied into new log files
as they are created during server startup or log file cycling.
- Default: .
- cycle
- Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
- Default: daily.
- cycle-how
- Specifies how to cycle the log file.
- Default: rename.
- cycle-time
- Specifies the time of day, or minute past the hour, that the log file is cycled.
- Default: 00:00.
- cycle-day
- Specifies the day of the week or month that the log file is cycled.
- Default: 0.
- cycle-size
- Specifies the maximum size in Kbytes for the log file; after that it is cycled.
- Default: 0.
- cycle-lines
- Specifies the maximum size in lines for the log file; after that it is cycled.
- Default: 0.
- cycle-arg
- Specifies an argument used for the various cycle-how options. When renaming a
file or concatenating it onto another, Xitami uses the argument as a time-stamped
filename. When moving the file, Xitami uses the argument as a time-stamped
directory name. When processing the file through an arbitrary command, it uses
the argument as a time-stamped command string. Xitami does not use the argument
when deleting log files. Format this argument from any of the following
timestamp fiels, mixed with other text.
- Default: er%yy%mm%dd.log.
This section controls the LRWP (long-running web process) protocol.
More information is available.
- enabled
- Specifies whether the LRWP agent is enabled or not.
- Default: 1.
- port
- Specifies the port on which the LRWP agent accepts connections.
- Default: 81.
- webmask
- Specifies the webmask for LRWP clients. Normally this is restricted to local
LRWP clients, but you can also construct LRWP networks from multiple servers. Use 'webmask=local' to specify just local addresses, or 'webmask=item,item,...'
to specify one or more types of access. Each item allows or excludes some IP
address(es): '250.12.13.*' allows matching addresses, '!250.12.13.*' excludes
matching addresses (but does not allow others). '!250.12.13.*,*' excludes one
set of addresses and allows all others. 'webmask=@iplist.txt' reads the list of
webmasks from a text file.
More information is available.
- Default: local.
- allow-all
- Allows all LRWP clients to connect. If this is set to 1, any LRWP
application will be allowed to connect. Otherwise the LRWP-Application
section must be used to authorise specific applications, and optionally
specify a password to use during the authentication stage.
- Default: 1.
This section consists of one entry per application name (either URL prefix,
or a URL "extension" name). The entry should either to be set to "*" to
indicate the application is allowed without authentication, or to a
password/phrase that is used in LRWP 2.0 authentication with that
application. If a password/phrase is specified, then LRWP 1.0 clients will
not be allowed to connect with that name (as they cannot perform the
required authentication).
This is an example of enties in the [Lrwp-Application] section:
[LRWP-Application]
testapp=* # Connect without any password
secureapp=funky161 # Connect using secure password
This section controls the interface between Xitami and the SSL (secure socket
layer) agent. The SSL agent is active in Xitami/Pro, the professional version
of Xitami.
- enabled
- Specifies whether the SSL interface is enabled or not.
- Default: 1.
- config-file
- Specifies the SSL configuration filename.
- Default: sslhttp.cfs.
These options occur in several sections and are selected from a list of
possible values.
Specifies the log file format. The log file format you use needs to be
compatible with whatever tool you use to analyze log files and build statistics.
The most common tools work with an extended form of the NCSA log file format,
also called 'common log file format'. We call this "CLFX". An other
commonly-used format is that produced by Microsoft web servers. Xitami also
creates log files in two XML formats, which you can easily process using GSLgen
to you create arbitrary reports, statistics, and HTML analyses. Lastly, you can
create your own format, for specific purposes.
These are the possible values for the log file format:
| Value: | Has this meaning: |
|---|
| clf | Common-log format, as used by the NCSA httpd server.
Defined as: '$(client) - $(user) [$(datetime)] "$(request)" $(status)
$(sent)'
|
| clfx | Extended CLF, as used by Apache and Xitami. Defined as:
'$(client) - $(user) [$(datetime)] "$(request)" $(status) $(sent)
"$(referer)" "$(agent)"'
|
| ms | Microsoft format as used by IIS. Defined as: '$(client),
$(user), $(mon)/$(day)/$(year), $(hh):$(mm):$(ss), $(service), Xitami,
$(ipsrv), $(stime), $(recd), $(sent), $(status), 0, $(method), $(file)'
|
| lml | iMatix Logfile Markup Language, an XML format. Defined as:
''
|
| xlml | iMatix Extended LML, a richer XML format. Defined as:
''
|
| custom | User defined format, specified in custom field, and built
from any combination of log format specifiers mixed with other text.
|
Specifies when to cycle the log file. When Xitami cycles a log file, it
first moves or copies the existing data to another file, then creates a new,
empty log file.
These are the possible values for the log file cycle option:
| Value: | Has this meaning: |
|---|
| startup | When the server starts |
| hourly | Each hour at some specified time |
| daily | Each day at some specified time |
| weekly | Each week at some specified day and time |
| monthly | Each month at some specified day and time |
| manual | Manually only |
| size | When the log file gets larger than some specified size
in Kbytes. |
| lines | When the log file gets larger than some specified size
in lines. |
Specifies how to cycle the log file.
These are the possible values for the log file cycle-how option:
| Value: | Has this meaning: |
|---|
| rename | Rename the old log file, and create a new file. |
| delete | Delete the old log file, and create a new file. |
| move | Move the old log file to some directory, and create a
new file. |
| concat | Append the old log file to some file, and create a new
file. |
| process | Run an arbitrary command to process the file, then create
a new file. |
Xitami uses 'webmasks' to allow or deny access to resources. The
simplest webmask is:
webmask=*
which allows all IP addresses. The '*' matches part or all of an IP
address, in this case, all addresses.
To restrict accesses to local IP connections (i.e. originating from the
same system), use the form:
webmask=local
More complex webmasks consist of several terms, separated by commas. For
example:
webmask=192.*,!221.201.*,1.233.12.*
To see whether the IP address of a client is allowed or rejected by a
webmask, Xitami starts with the first term, and looks at each term to see
whether it explicitly allows or denies the client IP address. The order of
the terms is very important. For example:
webmask=!192.*,*
First rejects any addresses that start with '192.', and then allows all
(other) addresses. A client connecting from '192.1.1.1' will be rejected by
the first term.
However, the same two terms, exchanged, have a different effect:
webmask=*,!192.*
Here, all clients are allowed by the first term, '*', and Xitami will not
even look at the second term.
Lastly, you can put webmask information into a text file. Use this form:
webmask=@filename
Enter the webmask terms in the specified file, using whitespace or blank
lines freely. If the webmask file is not present, Xitami displays an error
message in its log files, and acts as if the webmask was not defined at all.
Xitami lets you simulate a specific HTTP error, useful if you've defined
customised error messages. Use the special URL 'error?xxx' where 'xxx' is
the 3-digit HTTP error code you want to simulate. For instance, to simulate
a 402 error (Payment Required), use a URL like this:
http://localhost/error?402. You can simulate a 302 error (temporary
redirection) using a URL like this:
http://localhost/error?302:/somedir/somepage.htm.
Xitami