Administration

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

Xitami
Version 2.5b4

The Windows version of Xitami provides a simple control panel that lets you start, stop, and monitor the web server. The service version is easily installed as an NT service, or can be run as a command-line program. It then accepts the command-line switches described later.

Xitami Under UNIX

Under UNIX, Xitami can run as a foreground process or a daemon. You can run it interactively to test your configuration, and then configure your system inittab or start-up scripts to run it automatically.

This is the command-line syntax for Xitami:

Syntax: xitami [options...]
Options:
  -r directory     Root directory for web pages (webpages).
  -c directory     Directory for CGI programs (cgi-bin).
  -b portbase      Shift HTTP port 80 by this value.  E.g. to run
                   Xitami on port 7080, do 'xitami -b 7000'.
  -l filename      Log file for output (xitami.log).
  -a filename      Authentication file (xitami.aut).
  -q               Quite mode: no messages or log.
  -s               Server mode: run as background job.
  -t               Trace all socket i/o operations to log file.
  -v               Show Xitami version information.
  -h               Show summary of command-line options.

The -s option has no effect on Windows systems; under UNIX it does the following: Xitami recreates itself as a background process, ignoring the SIGHUP signal.

Testing Xitami

Run Xitami as described in the installation section. Connect with a browser to the URL: http://hostname/ or http://hostname:5080/. If Xitami is correctly installed, you should see a page entitled: "Welcome To Xitami". Please read this page and try the various links and buttons to ensure that Xitami is working correctly. If you install your own web pages, you can still access the Xitami Welcome page by using the URL: http://hostname/default.htm.

Using Xitami

Xitami assumes that all web pages are in a subdirectory called 'webpages'.
CGI scripts and programs are in a subdirectory called 'cgi-bin'.
Directories can be protected by editing the file 'xitami.aut'.
Logging information is stored in two files: 'xitami.log' logs information and error messages; 'access.log' logs HTTP requests.

These options can be changed. The webpages directory can be any relative (depending on the directory where Xitami is run) or absolute directory (with a full path name).

The cgi-bin directory can be specified in various ways - see the section on CGI programming in Xitami.

Xitami will negotiate with the web browser to find a file when the URL does not specify a filename. It will search for an HTML file called index.htm, index.html, default.htm, or default.html, in that order. If none of these files are found, Xitami returns the directory listing, formatted as an HTML page. Note that Xitami automatically looks for files with an extension .html if a file with the .htm extension could not be found, and vice-versa.

You should install a file called 'index.htm' in the webpages directory, to override the 'default.htm' file used by Xitami.

User Authentication

Xitami supports the HTTP/1.0 Basic Authentication protocol. This is a minimalistic security approach that is quick and supported by all browsers, but which should not be used for very sensitive data, since the user name and password can be extracted from the TCP/IP packets sent by the browser.

The xitami.aut file holds the authentication information. This file is not encoded, but is not accessible by browsers unless you place it in the webpages directory. You can modify this file on the fly; Xitami will reload it after a short delay (the server:refresh option).

Protection is applied to directories or individual URLs. This is what an authentication file looks like:

#  Authorization file for XITAMI
#  Each [Entry] defines a protected URL or directory.
#  The directory name is followed by user=password pairs
#
[/Admin]
    admin=top secret
    realm=On-Line Administration
[stats/index.htm]
    root=PakYupTon
    admin=QzeCat96
    webmask=local
[/private]
    jacky="funny;password"
    sarah=arabica
    jonas=realtime

Each section name specifies an URI or a directory name; the leading slash is optional. When checking a resource called "/pub/mypages/file", Xitami will look for entries in this order:

[/pub/mypages/file]
[pub/mypages/file]
[/pub/mypages]
[pub/mypages]
[/pub]
[pub]
[/]

The directory or URL name is not case-sensitive; Xitami always treats it as lower-case. On systems where filenames are case-sensitive, "PRIVATE" and "private" are treated as equal by Xitami, and are both handled by the authentication data for [Private]. The user name is also case-insensitive. The password is case-insensitive if the option security:password-case is set to 0.

Passwords can contain any printable character except ' and ". If you edit or create the password file by hand or using scripts, use double quotes around passwords to make sure that special characters like ; and # (which indicate comments) are treated as part of the password.

The entry 'webmask=' is treated in a special manner; this defines the set of valid IP addresses for clients trying to access the directory. The section on webmasks provides more details. If you define an entry consisting only of 'webmask=', Xitami will treat this as a resource that is protected (has an entry) but has no valid users.

The entry 'realm=' is also treated in a special manner; this defines the 'Realm' for the authentication. The realm is returned to the browser, and is the basis upon which it will remember user names and passwords. If you use the same realm for several directories or URLs, make sure that the user names and passwords also match. If no realm is defined, Xitami returns the [Entry] name as the realm.

The entry 'http-update=' is used to determine whether the HTTP PUT, COPY, MOVE, and DELETE methods are allowed for the URL. By default these are not permitted. To allow them, add 'http-update=1' to the authorisation file.

A password "-" is treated as meaning 'not allowed' for that user. If there is only one user defined, the resource will be inaccessible. This is used, for example, in the default xitami.aut file to indicate that the administration URL '/admin' is not accessibly until a non-default password has been entered. An empty password is treated as meaning 'non required' for that user.

The entry 'all=*' allows access to all users without a user id/password check. You can combine this with the webmask option to restrict access by webmask without requiring user id/password entry at the same time.

When using Xitami/Pro's SSL connection, you can allow access to a protected resource to users who have a valid certificate. Certified users will bypass the 'user/password' prompt, and access the protected resource directly. For this to work, you must define the password for each such user as '*SSL'. This is taken to mean: allow this user access if they have a valid certificate.

Xitami Log Files

The Xitami Server Log File

Xitami logs errors and information to the file 'xitami.log'. This file is always opened in append mode. It looks something like this:

96/12/05 20:19:41: I: OPEN port=80
96/12/06 07:22:03: I: OPEN port=80

To configure the server log, see the [Serverlog] configuration entry.

By default, Xitami logs all HTTP requests to the file 'access.log', which follows the common CERN/NCSA standard for web server log files. The log file format consists of lines in this format:

host - user [DD/Mon/YYYY:hh:mm:ss] "request" ddd bbbb "referer" "agent"

This field:	Has this purpose:
host	IP number of requesting host
user	Userid sent for authentication, or -
request	HTTP request sent by client
ddd	Status code returned by server
bbbb	Size of data sent, excluding HTTP header
referer	Referer document, or ""
agent	User agent (browser), or ""

The access log files are automatically cycled: when Xitami starts, it will save any existing file before starting a new access log. The old access log file is given a name based on the date when it was last modified.

Extended Logging

Xitami has an extended logging function that is much richer than the standard access logging function. The extended logging function gives you more control over the way that log files are cycled, over the log file names, and over the log file format. The extended logging function also does reverse-DNS translation of IP addresses. The extended logging function works with access logs and error logs, and is controlled by a number of additional configuration options in the [ServerLog], [AccessLog], [ErrorLog], [FTPLog], and [FTPErrLog] sections:

format

Specifies the log file format. You can use one of a number of predefined formats, or build your own format using any of these symbols:

Symbol:	Expands to give:
$(client)	client address, as translated string
$(ipcli)	client address, as dotted number
$(ipsrv)	server address, as dotted number
$(request)	request line (HTTP only)
$(query)	query string, if any (HTTP only)
$(method)	HTTP method or FTP command
$(status)	response code, 3 digits
$(recd)	request size, in bytes
$(sent)	response size, in bytes
$(time_ms)	request duration, in msecs
$(time_s)	request duration, in seconds (n.nnn)
$(file)	filename to which request was translated
$(agent)	HTTP user agent (browser name)
$(referer)	HTTP referer field
$(user)	user name, if any, else -
$(service)	name of service (HTTP, FTP)
$(vhost)	virtual host name, if any, else -
$(datetime)	date/time in NCSA format
$(yy)	year as two digits
$(year)	year as four digits
$(mon)	month
$(day)	day
$(hh)	hour, using 24-hour clock
$(mm)	minutes
$(ss)	seconds
$(XXX)	environment variable XXX (XXX is in uppercase)

Xitami has these built-in formats:

Format:	Description:
CLF	Common-log format, as used by the NCSA httpd server. $(client) - $(user) [$(datetime)] "$(request)" $(status) $(sent)
CLFX	Extended CLF, as used by Apache and Xitami. $(client) - $(user) [$(datetime)] "$(request)" $(status) $(sent) "$(referer)" "$(agent)"
MS	Microsoft IIS format. $(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. <LOG DATE="$(datetime)" CLIENT="$(client)" REQUEST="$(request)" METHOD="$(method)" STATUS="$(status)" SENT="$(sent)" FILENAME="$(file)" USERNAME="$(user)" SERVICE="$(service)" />
XLML	iMatix Extended LML, a richer XML format. <LOG DATE="$(datetime)" CLIENT="$(client)" CLIENTIP="$(ipcli)" SERVERIP="$(ipsrv)" REQUEST="$(request)" METHOD="$(method)" STATUS="$(status)" RECEIVED="$(recd)" SENT="$(sent)" DURATION="$(time_ms)" FILENAME="$(file)" USERAGENT="$(agent)" REFERER="$(referer)" USERNAME="$(user)" SERVICE="$(service)" VHOST="$(vhost)" />

Default: CLFX (compatible with standard Xitami).

Note that the XML-based format are easy to work with using iMatix's GSLgen tool. GSLgen lets you create arbitrary reports, statistics, and HTML analyses of access log data.

cycle

Specifies when to cycle the log file. Can be one of:

startup, or 0 - cycle log when the server is starts;
hourly, or 1 - cycle log each hour
daily, or 2 - cycle log each day
weekly, or 3 - cycle log each week
monthly, or 4 - cycle log each month
manual, or 5 - manual cycling only
size, or 6 - cycle the log file when it exceeds some size in Kbytes
lines, or 7 - cycle the log file when it exceeds some size in lines

Default: daily.

cycle-how

Specifies how to cycle the log file. Can be one of:

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.

Default: rename.

cycle-time

Specifies what time to cycle the log file. This is used for the 'hourly', 'daily', 'weekly', and 'monthly' cycle options. It can specify a number of minutes (past the hour), or a time in hours and minutes formatted like this: 'hh:mm'. For instance, if this is set to '03:30' and the cycle option is 'daily', then the log file will be cycled at 3.30am each day.

Default: 00:00 (cycle at midnight).

cycle-day

Specifies the day of the week (for cycle=weekly) or the day of the month (for cycle=monthly) to cycle the log file. 0 is Sunday, 1 is Monday, etc.

Default: 0.

cycle-size

Specifies the limit, in whole Kbytes, for the cycle=size option. When the log file exceeds this size, it will be cycled.

Default: 0.

cycle-lines

Specifies the limit, in lines, for the cycle=lines option. When the log file exceeds this size, it will be cycled.

Default:

cycle-arg

Specifies an argument used for the various cycle-how options:

Cycle-how:	Uses argument like this:
Rename	As time-stamped filename.
Delete	Does not use argument.
Move	As target directory name.
Concat	As time-stamped filename.
Process	As time-stamped command to execute.

The time-stamping function expands symbols in the argument as follows:

Symbol:	Expands to give this:
%y	day of year, 001-366
%yy	year 2 digits, 00-99
%yyyy	year 4 digits, 0100-9999
%mm	month, 01-12
%mmm	month, Jan
%mmmm	month, January
%MMM	month, JAN
%MMMM	month, JANUARY
%dd	day, 01-31
%ddd	day of week, Sun
%dddd	day of week, Sunday
%DDD	day of week, SUN
%DDDD	day of week, SUNDAY
%w	day of week, 1-7 (1=Sunday)
%ww	week of year, 01-53
%q	year quarter, 1-4
%h	hour, 00-23
%m	minute, 00-59
%s	second, 00-59
%c	centisecond, 00-99
%%	literal character %

Additionally, when used for cycle-how=process, the argument can also contain '%f', which is expanded to give the name of the old log file.

Default: ac%yy%mm%dd.log for the access log and er%yy%mm%dd.log for the error log.

translate

Specifies whether the log file IP addresses are translated or not. This can slow-down the server, especially if reverse-DNS lookups are not working correctly, so always test this carefully before using it. Note that if translation is enabled, that you must configure the RDNS setup as described in the section on RDNS configuration.

Default: 0 (not enabled).

Building Multilanguage Web Sites

Xitami accepts the HTTP Accept-Language field and tries to do something useful with it. Not all browsers let you set this field, but some do. This field lets users specify their preferences for particular versions of documents. For instance, if a user specifies that they prefer documents in French, then English, the Accept-Language field will contain "fr, en". Xitami handles this as follows, for a document URL "file.htm":

If the file "file.htm" exists and is readable, Xitami returns it to the browser as usual.
If the file does not exist, Xitami will search for "file.html", "file.htm.fr", "file.htm_fr", "file.html.fr", "file.html_fr", "file.htm.en", "file.htm_en", "file.html.en", and "file.html_en" in that order.
If the file is still not found, Xitami returns a 404 error status.

The same applies to default pages and to CGI scripts, and filters. Note that Xitami will only do the extra checking for alternative htm/html files for .htm and .html files.