-
FTP access - .endif
Worldwide Mirror Sites
Click on the image that displays first:
Current Release - $(version)
.file_table %(vxi) $(xisite)Previous Release - 2.4d3
.file_table 24d3 $(xiprev) .define kit_win16 $(xisite)/bw16%(vxi).exe .define kit_win32 $(xisite)/bw32%(vxi).exe .define kit_win32_console $(xisite)/bc32%(vxi).exe .define kit_win32_service $(xisite)/bs32%(vxi).exe .define kit_win32_src $(xisite)/swin%(vxi).zip .define kit_os2 $(xisite)/bos2%(vxi).zip .define kit_unix $(xisite)/suni%(vxi).tgz.build anchor win32
GUI Version for Windows 95/98 or NT
Download and run the $(*kit_win32=32-bit_Windows_package). The installation Wizard will prompt you for an installation directory, and will build a program group and icons to run Xitami. To run the installation Wizard without the iMatix logo display, pass is "-nologo" on the command line.
You can uninstall Xitami by double-clicking the Uninstall icon. Under Windows 95 and NT 4.x you can also select the 'Add/Remove Programs' option in the control panel. Xitami maintains various items in the Windows registry which the uninstall script should remove.
When you have installed Xitami, run it, then connect with any web browser. You should see the "Welcome To Xitami" test page. If Xitami cannot run on its normal port (80), it shows an error message: this can happen if another server is using port 80. You can use an alternative HTTP port such as 5080. You then connect using the URL http://localhost:5080/.
You can also download the $(*kit_win32_src=source_package) for Windows. This compiles under MSVC 4.x or 5.x, and is necessary if you want to extend the server using the WSX add-on protocol. To build from the source package, unzip it into a directory (e.g. c:\xitami\src) and double click on the xitami.mdp file. This launches MSVC. Click on the 'Build' button, wait until everything compiles, then click on 'Run'. Note that this source package contains the console (DOS box) version of Xitami. The project contains definitions for the GUI versions too, but these won't build unless you've purchased the Windows GUI source code from us.
If you use Windows 95, be aware that the earlier versions of this OS can get into serious problems when heavily loaded with TCP/IP connections. While Win95 is adequate for testing and for small sites, we cannot really recommend it for serious sites - use NT or Linux. If you find that your Win95 system shows the classic 'Blue Screen of Death' when the server is heavily loaded, consider installing the various patches and upgrades that are supplied on the Microsoft site.
.build anchor win32_console
Console Version for Windows 95/98 and NT
The console version of Xitami runs in a DOS box. Unlike the Windows GUI version, it does not provide a control panel, so you stop the server using Ctrl-C. The advantage of the console version is that messages are shown on the screen directly, so it's a little easier to use when you're debugging a difficult configuration. Otherwise, it's exactly the same Xitami. Download and run the $(*kit_win32_console=32-bit_Windows_console_package). The installation program will prompt you for an installation directory, and will build a program group and icons to run Xitami.
Some users of Windows 98 have reported that the console version of Xitami runs more stably than the graphic version. This may be due to the MSVC runtime, but in any case: if your GUI version of Xitami crashes after heavy use under Win98, try using the console version.
When you have installed Xitami, run xidos32, then connect with any web browser. You should see the "Welcome To Xitami" test page. If Xitami cannot run on its normal port (80), it shows an error message: this can happen if another server is using port 80. To use an alternative HTTP port, use the '-b' option. This shifts the standard HTTP and FTP ports by some 'base'. For example, '-b 5000' runs the Xitami HTTP service on port 5080 and the FTP service on port 5021. You would then connect using http://localhost:5080/.
To halt Xitami, press Ctrl-C. This shuts-down the server cleanly.
You can uninstall Xitami by double-clicking the Uninstall icon. Under Windows 95 and NT 4.x you can also select the 'Add/Remove Programs' option in the control panel.
Using Xitami as a Service Under Windows 95
You can also install the console version as a service under Windows 95/98. This is a little-known ability of Win95/98, and it allows you to automatically run Xitami when the computer boots, rather than when a user logs in. The Xitami console version installation package asks whether you want to install it as a Win95 service. If you choose this option, it creates a small dispatcher, called "C:\Service.bat" which simply changes to the Xitami directory and then runs Xitami.
To start the dispatcher, the installation script adds an entry to the registry, under "SOFTWARE\Microsoft\Windows\CurrentVersion\RunServices". You can delete this entry at any time. You can also edit service.bat to remove the call to xidos32.exe.
.build anchor win32_service
Xitami Service for Windows NT
Download and run the $(*kit_win32_service=NT_service_package). The installation program will prompt you for an installation directory, and will install Xitami as an NT service. You can start and stop the service using the Service Control Manager or the Xitami control panel (in the Control Panel window).
We recommend that you log-on as administrator before you install Xitami. If you install Xitami in a directory that contains a space, you will find that the service does not start correctly. You can fix this by editing the registry (ugh!) to put quotes around the filename $(*start_service=as described in the faq) or by installing in Progra~1 instead of in 'Program Files'.
The Xitami Service version accepts various command-line arguments when run in a Dos window:
| Argument: | Has this purpose: |
|---|---|
| -i | Installs Xitami as a service. |
| -u | Uninstalls the Xitami service. |
| -d | Run Xitami as a console program. |
| -d -h | Show help for command-line arguments. |
You can pass any command-line arguments except -i, -u, and -d in the 'Startup Parameters' field in the Service Control Manager. When you run the Xitami service as a command-line program, it acts identically to the vanilla console version. You can use the service version on Windows 95, although the -i and -u switches will not work.
The Xitami service version has the same performance as the normal 32-bits version, but will continue to work after you log off. Xitami runs on NT 3.51 and later versions.
Under Windows NT 4.0 and later you can select the 'Add/Remove Programs' option in the control panel to de-install Xitami. A bug in NT means that the control panel itself (xiwinntc.cpl) will not be deleted. Xitami maintains various items in the Windows registry, but these can be removed at any time without affecting the server.
Manual Installation Of The Xitami NT Service
On some (broken) NT systems that have problems running 16-bit code, the self-installing .exe file may cause an error. In such a case you can install the NT service by hand. Unzip the .exe install file (use WinZip or similar) into a directory like C:\Program Files\Xitami.
In a DOS box, in the Xitami directory, run 'xiwinnt -i' to install the Xitami service. Then copy xiwinntc.cpl to the Windows NT system32 directory. You can check that this works by using the NT service manager to stop/start Xitami, and using the Xitami Control Panel.
.build anchor win16
Xitami for Windows 3.1 or 3.11
To run Xitami on a Windows 3.x PC you must have a 386 or higher processor. Xitami will run on a modest system; 4Mb RAM is enough if you do not run any large applications.
Download and run the $(*kit_win16=16-bit_Windows_package). The installation program will prompt you for an installation directory, and will build a program group and icons to run Xitami. To uninstall Xitami, double-click the Uninstall icon. Xitami does not create any files in the Windows directories.
When you have installed Xitami, run it, then connect with any web browser. You should see the "Welcome To Xitami" test page. If another web server is already using port 80, Xitami will not start. In that case, you can choose a new port (e.g. 5080) and then connect using the URL http://localhost:5080/.
We have tested Xitami with some 16-bit Winsock libraries, but these are notoriously unstable. Our best recommendation are the Microsoft winsock libraries, supplied with recent 16-bit versions Explorer. Windows 3.11 is also reasonably robust.
The limitations of 16-bit Windows mean that Xitami does not support CGI programs under Windows 3.x. If someone tries to run a CGI program, Xitami will show an error page.
You can also run the $(*kit_win32_console=32-bit_console_version) of Xitami if you install Win32s. This version has all the functionality of the Windows 95 and NT versions (including FTP and browser-based admin) except CGI. This configuration lets you build web applications using the LRWP protocol.
.build anchor os2 .pipe os2-readme.htm=Xitami installation for OS/2
Xitami for OS/2
The OS/2 version of Xitami was built using GCC 2.7.2.1 and runs with the
EMX 0.9c environment. The EMX DLLs will be required, and are available from
fine FTP sites everywhere (e.g. ftp.leo.org, ftp.cdrom.com,
hobbes.nmsu.edu). Compiled with assertions and gdb debugging information
disabled. The OS/2 version of Xitami was built by Ewen McNeill
The current distribution of Xitami for OS/2 was built for EMX 0.9c fix 2,
and will work with releases up to EMX 0.9c fix 4.
Download the $(*kit_os2=OS/2_binary_package) -- you'll need an
$(*info-zip=unzip) tool to extract the archive. You can also build the
server from the $(*kit_win32_src=Windows source package), using the supplied
xibuild.cmd file.
To install an Desktop icon for Xitami, run install.cmd.
When you have installed Xitami, run xitami.exe, then connect with any web
browser. You should see the "Welcome To Xitami" test page. If Xitami cannot
run on its normal port (80), it shows an error message: this can happen if
another server is using port 80. To use an alternative HTTP port, use the
'-b' option. This shifts the standard HTTP and FTP ports by some 'base'. For
example, '-b 5000' runs the Xitami HTTP service on port 5080 and the FTP
service on port 5021. You would then connect using
http://localhost:5080/.
To halt Xitami, press Ctrl-C. This shuts-down the server cleanly.
In all cases where TCP/IP is bundled with OS/2, it is an installation
option. Obviously the TCP/IP software must be installed to use TCP/IP-based
programs like Xitami.
As far as we know, OS/2 can be used without a nameserver available (we
use a Linux machine as the nameserver for our network), if a 'hosts' file is
set up in the %ETC% directory (i.e. the directory pointed at by the ETC
environment variable. This directory is typically d:\tcpip\etc, or
d:\mptn\etc, where d: is the boot drive). The 'hosts' file should contain
the normal host information, i.e. the IP address, and then the name
associated with that IP address, on the same line separated by (one or more)
spaces. OS/2 can be told to use the hosts file before checking DNS by
setting the environment variable; set this line in config.sys and reboot:
The default number of file handles for an EMX is around 20-40. This is
too little for a heavily-used server, and you may get errors logged as "out
of file handles".
The number of file handles available in programs that use EMX can be
controlled via a runtime settable environment variable, EMXOPT.
From the EMX runtime documentation (emxrt.doc):
For a busy web server, a good value would be 120:
With the EMX development system (including the GNU C compiler) you can
rebuild Xitami on your OS/2 system. You must have installed EMX (we
recommend version 0.9c) including these packages: emxrt.zip, bsddev.zip,
gnudev1.zip, gnudev2.zip, emxdev1.zip, emxdev2.zip.
To rebuild Xitami, first unzip the source package in a suitable
directory, e.g. C:\Xitami. This creates a source tree and also installs the
various files and subdirectories that are needed for running Xitami. The
sources are in src\sfl and src\smt. You can build the executable using the
command file 'xibuild'. If this fails, for some reason, you must build SFL
and SMT manually, but this is fairly simple:
With an ANSI C compiler, you can rebuild Xitami on your system. Note that
the Xitami sources are ANSI C/POSIX compatible, and should build cleanly on
the majority of UNIX systems. We and other people have tested Xitami on
these systems:
To install the source kit you need about 15Mb of disk space. You can
download the Xitami sources as a compressed tar file (.tgz). To unpack
a tgz file you need GNU gunzip. Download the
$(*kit_unix=suni%(vxi).tgz) source kit. To unpack the compressed file,
give these commands:
The resulting directory structure includes the full sources for Xitami
(basically the $(*sfl=SFL) and $(*smt=SMT) packages), plus a build script,
xibuild, plus the directories and web pages you need to get started
with Xitami.
The xibuild script compiles Xitami and installs the executable
program in the top directory (where xibuild is located). To run
xibuild, give these commands:
When you have built Xitami, run xitami, then connect with any web
browser. You should see the "Welcome To Xitami" test page. If Xitami cannot
run on its normal port (80), it shows an error message: this can happen if
another server is using port 80. To use an alternative HTTP port, use the
'-b' option. This shifts the standard HTTP and FTP ports by some 'base'. For
example, '-b 5000' runs the Xitami HTTP service on port 5080 and the FTP
service on port 5021. You would then connect using
http://localhost:5080/.
If Xitami does not build cleanly on your system, the problem will usually
lie in non-standard code in the SFL library upon which Xitami is based. It's
possible that your system (or compiler) does not do what SFL expects. In
general the only file which you may need to change is the prelude.h file in
the SFL directory. Read the SFL doc if you think you want to make changes to
this library (it's pretty simple, really, and many people done this).
.endpipe
With UCX and Vax C or Dec C, you can rebuild Xitami on your OpenVMS
system. OpenVMS 6.1 or prior may not work correctly. Note that the Xitami
sources are ANSI C/POSIX compatible, and depend on support from the OpenVMS
system libraries to some extent. These were not fully POSIX in OpenVMS prior
to 7.0, through Xitami (actually, SFL, which provides the portability layer)
gets around the most blatant differences.
The section on building Xitami must still be completed. However, the
process is fairly simple:
Xitami runs fully, except for a couple of restrictions. The directory
list functions do not (yet) work. To run a CGI program you must define an
external command before starting the server. This is necessary so that
Xitami can pass arguments to the program. For example:
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.
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.
.build anchor syntax
This is the command-line syntax for Xitami:
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.
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.
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 $(*cgidir=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.
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:
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:
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 logs errors and information to the file 'xitami.log'. This file is
always opened in append mode. It looks something like this:
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:
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.
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:
.macro item 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.
.item cycle
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":
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.
.-----------------------------------------------------------------
.page Configuration
.build anchor config_main
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:
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:
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: 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.
.include ../xiconfig.htp
.build anchor webmasks
Xitami uses 'webmasks' to allow or deny access to resources. The
simplest webmask is:
To restrict accesses to local IP connections (i.e. originating from the
same system), use the form:
More complex webmasks consist of several terms, separated by commas. For
example:
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:
However, the same two terms, exchanged, have a different effect:
Lastly, you can put webmask information into a text file. Use this form:
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.
.-----------------------------------------------------------------
.page Using The Common Gateway Interface (CGI)
Xitami supports CGI programs in Perl, C, or any other language
that your system supports. In general, CGI program written for
web servers such as Apache and NCSA httpd will run unchanged with
Xitami.
A 'CGI' program is considered to be any URL with '/cgi-bin'
somewhere in the path name. These are all examples of valid
CGI program URLs:
Xitami defines these CGI environment variables:
A CGI program can get arguments from a number of places, depending on how
Xitami is configured and how the HTTP request is made.
The 16-bit Windows version of Xitami does not support CGI.
Under Windows 95 and NT, you can run different types of CGI programs:
.com files should run correctly under 32-bit Windows. We recommend that
you use 32-bit executable programs, also called 'console programs'. The
Windows 32-bit interface is more robust and controlled than the 16-bit
interface. One example: if a CGI program loops, Xitami will kill it after a
timeout. But: a 16-bit DOS program will not respond to a kill request, and
will eventually bring the system down.
Under UNIX you can run any file that UNIX recognizes as an executable
file. This includes linked files, Perl scripts, shell scripts, etc.
Under OS/2, you can run different types of CGI programs:
Optionally you can specify a different interpreter for the script by
using either:
Remember the REXX scripts are identified by the "/*" comment in their
first line. The full-path-to-interpreter should specify the full filename
(drive (if it is not on the same drive as everything else), path, and
filename) of the interpreter to use.
When searching for a CGI program to run, if the program specified has no
extension Xitami for OS/2 first tries adding a ".exe" extension, then if
that fails it tries adding a ".cmd;" extension. If both of those fail, or
the program name already has an extension, the name is tried as is; it will
be considered executable if it has a ".exe" extension, a ".cmd" extension or
the file starts with a "#!" comment line. (REXX scripts and CMD scripts must
be stored in files with a ".cmd" extension because that is all the command
interpter (CMD.EXE) will accept.)
It is not possible to run DOS executables (".exe" or ".com") or DOS batch
files (".bat") under Xitami for OS/2. Nor is it possible to run PM-based
programs as CGI programs.
.build anchor cgidir
You can specify an alternate CGI directory. By default, Xitami will
search a subdirectory called 'cgi-bin'. This is how Xitami translates a URL
into an absolute file path, when looking for the CGI program:
This translation works as follows:
Only one of these translations can be done. By consequence,
any value you specify for the 'cgi-bin' option is ignored if you
place the '/cgi-bin' directory at some deeper level in the URL.
This is useful if you intend to mix CGI programs with your HTML
files, as complete directories.
Xitami tries to explain why a CGI program fails; these are the different
messages you may see for a 500 error, with an explanation for each.
There is not enough memory available. This is a bad sign; it means
that the virtual memory available to Xitami is all full. Stop the
web server, modify your systems' virtual memory settings, and start it
up again. This problem is very rare, really, especially since Xitami
is a tiny piece of software.
The CGI URL argument (text following a '?' after the URL) was too
long. Whatever you are trying to do, stop it. (Actually, since release
1.2a, Xitami allocates such buffers dynamically, so this error will not
occur, and it is now rather difficult to hack Xitami by using buffer
overruns.)
Xitami communicates with CGI processes using simple text files; if
the file it wants to use already exists and is unavailable to Xitami, it
will not be able to run the CGI process. Cure: make sure that you only
run one instance of Xitami from one directory. Delete any files called
'tmp...'. Make sure no CGI process is still hanging around, looping but
unkillable (typically under Windows 95 or NT with 16-bit CGIs).
The CGI program exists (otherwise you get a 402 Not Found), but could
not be started correctly. The most common cause of this error is a Perl
script which has a misformed magic header line. Make sure that the Perl
script starts with "#! perlpath" where perlpath is the full
path name of the Perl executable, e.g. "C:\Perl\Perl.exe".
The CGI program ran, but returned an error code. Most servers ignore
this, but Xitami treats this as an error. Cure: make sure your CGI
programs end correctly with a 'return (0)' or equivalent. If you cannot
do this, set the configuration option cgi:exit-ok to 0.
Someone or something interrupted the CGI process before it ended.
This can happen when a CGI process takes too long to run, and the system
administrator decides that enough is enough, and kills it. Cure: ask
your sysadmin to be nice, or write faster CGIs.
Something unexpected happened inside Xitami's guts when it tried to
run your CGI. Aaaagh! What did you do?! If this happens, let us know
how to reproduce it.
Something else happened. Cure: tell us about it.
.-----------------------------------------------------------------
.page Server-Side Includes (SSI)
.build anchor using_ssi
SSI (server-side includes) is a fairly standard syntax which you can read
about on the $(*ssi=NCSA_site). By default, Xitami parses any document with
extension '.ssi', '.shtm', or '.shtml' as an SSI document. This is defined
in the $(*config_wsx=[WSX]) section of the configuration files, where the
SSI WSX agent is xixssi. You can add SSI support to other file types, e.g.
for .html files. SSI documents are placed in the normal web pages directory,
and are recognised purely by their extension, not the path.
Xitami supports these SSI tags:
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 with a
leading dot 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.
Xitami supports filter programs in Perl, C, or any other language that
your system supports. A filter program runs when the HTML page is displayed,
unlike a CGI program, which runs when the user posts data from a HTML form.
An example of a filter program is PHP 3.0, which Xitami supports.
To add your own filter programs, you add an entry in the [Filter] section
of the config file. A filter program is invoked whenever a file with the
appropriate extension is displayed.
Filter programs need to respect the rules for CGI programs. That is, they
should generate the same type of header (Content-Type: text/html). Filter
programs also get the standard CGI environment, and are subject to the CGI
timeouts and other constraints set in the [CGI] section.
When you POST to a filter program, the form data is supplied on the
standard input as for CGI programs. When you use the GET method, the file
that is being filtered is provided on the standard input.
.-----------------------------------------------------------------
.page Server-Side XML Processing
.build anchor using_xml
XML is a data-definition language, used more and more to describe data
coming from databases and other places. Xitami can produce XML logfiles,
and uses XML in other places.
With server-side XML processing, you can display XML files as HTML
quickly and easily, with full control over the HTML that is produced.
Xitami's XML processing is simpler and more powerful than stylesheets or
other ways of processing XML.
Server-side XML processing is an excellent way to show data coming from
databases, other applications, spreadsheets, and so on. All you need to do
is to create the data in an XML format and write a GSL script that processes
it (as described below).
Xitami uses the GSL language to describe how an XML file is shown. GSL
is iMatix's Open Source template-based code-generation language. The GSLgen
engine is built-in to Xitami, and GSLgen is also provided as a seperate
command-line tool with Xitami.
If you want to use server-side XML processing, you should download the
$(*gsl=GSLgen) tool from imatix.com, and study the GSL language. It's
quite simple. This is an example GSL script, provided as an example in
the webpages directory:
By default, Xitami uses a script with the same name as the XML file (but
with the extension .gsl). You can use a specific script by adding an
attribute 'script' to the root item, e.g.:
This is useful if you process several XML files through the same script.
One handy way to use XML files is in combination with CGIs. Your CGI
program can create an XML file, then use the 302 HTTP code to redirect the
request to the XML file.
As well as the standard attributes (date, time, filename, script), the
GSL script can access all the environment variables normally passed to a
CGI program, such as REMOTE_USER.
You can pass arguments to the the XML file processor by using the
query string syntax:
This is useful to override attributes like 'script'. All arguments
passed in the query string are defined in the XML root item.
.-----------------------------------------------------------------
.page Server-Side GSL Scripting
.build anchor using_gsl
GSL is the iMatix code generation language. You can use GSL to do
fast server-side scripting, using an approach similar server-side includes
(SSI). GSL supports many commands including XML-driven output.
Server-side GSL scripting is similar to $(*using_xml=XML processing),
but the GSL script invoked directly (e.g. http://hostname/somefile.gsl)
instead indirectly through an XML file. GSL files must have the extension
'.gsl'.
For many cases, GSL scripting is faster and simpler than SSI or CGI.
A GSL script can load and manipulate arbitrarily-complex XML data, and
convert this into usable HTML using a simple but powerful template
language. GSL is several years ahead of similar approaches like XSLT
(the XML Stylesheet Language Transformation language), and works today
directly from your Xitami web server.
As well as the standard attributes (date, time, filename, script), the
GSL script can access all the environment variables normally passed to a
CGI program, such as REMOTE_USER. These are defined as attributes of the
root item, as well as 'argument' items attached to the root item.
You can pass arguments to the the GSL script by using the
query string syntax:
All arguments passed in the query string are defined as attributes
of the XML root item.
.-----------------------------------------------------------------
.page Image Maps
Xitami supports NCSA-type clickable image maps. When an image
has the ISMAP attribute, Xitami will search for and use an image
map file if the browser cooperates. An image map file has the name
of the image, the extension .map, and this syntax:
The URL can be any Internet URL, either an absolute image map,
or a relative image map. Xitami will recognise and handle these
types of URLs:
You can use these elements types in the image map:
There are many freely-available tools to help you create
image maps. Xitami is compatible with these tools, so long as
you create the image map in NSCA format.
.-----------------------------------------------------------------
.page Virtual Hosts
.build anchor vhosts
Virtual hosts means running multiple virtual web sites on
one system. This is commonly used by web site providers, but can be
useful in all kinds of organisations. There are two ways to configure
your IP system to permit virtual hosting:
Xitami can work with both these mechanisms for HTTP and FTP connections.
It handles multiple IP addresses automatically: if you ask it to run on
port 80, it will accept connections on any IP address, on port 80. You do
not need to configure this (although you can restrict it to run on one
specific address). This means that you do not need to specify on which IP
address Xitami should accept connections - if a system has ten IP
addresses, Xitami will accept connections on all ten.
A multihomed virtual host is identified by its IP address. A DNS-based
virtual host is identified by its name:
DNS-based virtual hosting requires a DNS server or something similar. The
mechanisms for setting-up both multiple IP addresses and multiple domain
names are system-specific; you should have access to technical documentation
for your TCP/IP configuration or good technical support. DNS-based virtual
hosting uses a HTTP/1.1 feature called the 'Host:' header, and an FTP feature
whereby the user name is specified as 'user@hostname'. Most modern
browsers support this; if you are building an intranet it is quite easy to
be sure that all browsers will work correctly with DNS-based virtual
hosting. On the Internet you can catch browsers that do not send a valid
Host: header, and show some specific pages.
The SSL protocol used in Xitami/Pro cannot work with DNS-based
virtual hosts, so to use SSL virtual hosts you must have a unique IP address
for each host.
When you set-up a virtual host, you will generally want to use a specific
directory for the web pages, CGI scripts, password file, and log files. (You
can also share these in any way you need to.) You can also configure options
such as the HTTP error messages, timeouts, security, and so on.
To define these, you specify a configuration file per virtual host. The
virtual host configuration inherits all definitions from defaults.cfg (and
xitami.cfg). You need only define those options that are specific to the
virtual host. If the HTTP request refers to a host name or IP address that
has not been configured as a virtual host, the request is handled by the
base host. To configure the base host, create a file called
'basehost.cfg'. You can change this name in the defaults.cfg file
server:base-host option.
This is a typical configuration for a site with several virtual hosts:
Some of the options in the [Server] apply to the entire server globally,
and are not taken from the virtual host configuration file: background,
customise, debug, limit, portbase, and refresh.
When you define a multihomed virtual host, you must specify a
server:hostname value. This should be a host name that translates back into
the correct IP address. The server:hostname option is used whenever Xitami
has to return a 'redirected' URL; for image maps, incomplete URL, and
directory listings. If you do not define server:hostname, or define it
wrongly, these functions may not work.
When you define a DNS-based virtual host, Xitami takes the name as a
default value for the server:hostname option. This usually works correctly,
but you can override it if necessary by adding the server:hostname option
explicitly. To avoid confusion, make sure your DNS server is correctly
configured. You normally use 'ping' to test that this works.
The virtual host configuration files, must exist when the server
starts-up. You can modify the virtual host configurations on-the-fly, as for
the normal configuration files, but if you want to add or remove a virtual
host you must stop and restart the server (for instance using the WBA
control panel.)
Since virtual hosting means playing with a lot of config files,
this can quickly become confusing if you don't take some basic care
and precautions. We advise you to:
If you have 'not found' errors that you can't explain, set the
server:debug option to 1 and recreate the error. Then, the log files
'debug.log' contains detailled information about the URL translation. You
can look at this file, or in serious cases, send it to us and we'll try to
help.
.-----------------------------------------------------------------
.page The FTP Service
Xitami supports the FTP (file transfer) protocol. The FTP service was
designed to be simple and easy to administer, while providing the security
and speed necessary for a web site. You can administer the FTP service from
the WBA screens, in the same way as you administer the rest of Xitami.
The current implementation of FTP does not support virtual hosts, so the
FTP configuration applies to all virtual hosts defined for a web site.
The FTP service recognises these commands, and handles those not marked
by '*':
The configuration of the FTP service is handled by specific
sections in the standard configuration file.
.build anchor config_ftp
This section controls the FTP service.
This section controls the FTP access log.
This section lets you define multiple FTP file roots. Each alias
alias specifies a name and a path. For example:
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 (see below). Like HTTP
aliases, the FTP alias is always the first component of a filename (e.g.
/volume-c/somefile). Aliases are shown only if the user has no GET access,
and if the specified user's root directory actually exists.
.build anchor config_ftperrlog
This section controls the FTP error log.
The FTP user file defines all users that may log-in to the FTP
server. This is a typical user file:
The user name is specified like this: [Admin]. User names are
not case-sensitive. The password may be any text. The password
may be one of these special values:
The access rights are any combination of:
The 'root' option defines where the user can work. If this is not
specified, the user can work anywhere below the FTP root directory. You can
also specify a full path, for instance:
The 'aliases' option defines whether or not a user has access to the
FTP aliases. By default this is true for all 'root' users, i.e. those
with an empty root value. You can override this default by specifying
an explicit value for the aliases option.
Note that put-only directories should be treated as special cases, and
used only as a user's root directory. You cannot 'chdir' to a put-only
directory.
You can enable/disable quotas per user. We defined a 'soft quota' and a
'hard quota'. Above the soft quota, the user gets warning messages. Above
the hard limit, uploads are refused, and warnings are sent to the web
server console. The quota is calculated quite simply: it is the limit for
all files in the user's login directory and subdirectories. You can
therefore share a quota between users, or allocate a quota to individual
users. The site administrator can decide whether log files are part of the
quota or not, by putting them into the user's space, or into separate
(non-quota) directories. For quotas to work, keep a user limited to the
login subtree. I.e. do not allow writeable aliases. Quotas are managed by
the three configuration keys: use-quota, soft-quota, and hard-quota.
The 'pipe' option lets you specify a $(*pipes=throttle pipe) for this
account. You can define a default pipe for the entire FTP server. To
specify that an account uses no pipe (runs at full speed) while a default
pipe is defined for the server, specify the pipe name "-".
The FTP directory file defines access rights per user for specific
directories. Each section is a directory name; either an absolute directory
(e.g. [/pub]) or a child of the ftproot directory (specified without a
leading slash: [pub]). To define rights for an alias directory, you must
use the child's root directory plus the alias directory. For instance if
you define an aliase like 'info' which maps to a CD-ROM drive, protection
for a user 'guest' who's initial root directory is 'guest' looks like this:
For instance, if the guest user has access to aliases, but you want to
disable access to the 'info' alias, you could use an entry like this:
A directory entry covers all child directories, unless a more
specific directory is defined for that user. Directory names are not
case significant.
Each entry specifies access rights for a user; the user must have
been defined in the FTP users file. The same access right codes are
used.
This material for this section was provided by Paul C. Fretz,
<pcfretz@mha.shalom.k12.pa.us>.
Install Xitami in its own directory. Have your web pages in a
separate directory such as c:\webpages
Setup 'defaults.cfg' to include:
Setup 'ftpulist.aut' to include:
There are several things to keep in mind:
Setup 'password.aut' as follows if you want to password protect the same
subdirectories for browsing:
Dynamic DNS is a way of registering your computer on the Internet
domain-name system (DNS) even when you have a dial-up line or cable modem,
with an IP address that changes each time you connect. Without a DDNS
service, people using your server must know and type its IP number. With a
DDNS service, they can use the domain name.
Dynamic DNS services vary a lot in qualty. Free services, like the now
defunct Monolith service, are often heavily loaded and can be slow to
update. Commercial services cost from $25 upwards per year, and offer two
main advantages over free services. Firstly, generally better performance
and secondly, a commercial DDNS service has more incentive to continue than
a free service, so your domain name has a long-term security. We work with
one DDNS provider, tzo.com, to provide dynamic domains under the
<.linkto xitami.net> domain.
A DDNS service works as follows: when you've connected to the Internet,
you need to run some client software that talks to the DDNS server, and
tells it your current IP address. The DDNS server updates its own DNS
tables and broadcasts update records to other DNS servers on the Internet,
so that your users can eventually use this information to find your server.
For most DDNS services, some client software is available, either as a
Windows program, a Perl script, or a Unix shell script.
Xitami contains all the code needed to act as a DDNS client for the most
popular DDNS services, including Xitami.Net, tzo.com, dyndns.org, ns1.net,
yi.org, and PengiunPowered.com (surprise, it's intended for Linux owners.
But Xitami lets you use it on any platform). Furthermore, you can add
support for new DDNS services by editing the file 'ddnsdef.xml', an XML
configuration file. The file contains its own comments. If you add DDNS
services, let us know the details so we can provide them as standard.
As delivered, Xitami supports: localhost, <.linkto xitami.net>,
<.linkto tzo.com>, This file, supplied with Xitami, defines the various DDNS services and
the client protocols needed to register and unregister from them.
The XML structure of this file is:
The SERVICE item has these attributes:
SIGNON and SIGNOFF have these attributes:
In the SEND string, you can use these symbols:
The send and expect strings can contain the escaped characters \\n and
\\r. The expect string is matched against the SERVICE response, if any. The
wildcard character ? matches any character in the response string and the
wildcard character * matches the remainder of the response string.
.-----------------------------------------------------------------
.page Throttle Pipes
.build anchor pipes
One problem with web and FTP sites is that they can consume a large
amount of bandwidth. If your site suddenly becomes popular, it can
disturb other traffic that needs to work on the same line.
For people who use Xitami to do virtual hosting, it's useful to be able
to balance the needs of the different web sites, possibly to provide
different qualities of service to different clients.
Xitami lets you send output (and get input) through named 'throttle
pipes', which you can visualise as pipes with a specific maximum capacity.
For example, a 64Kb pipe will allow 65536 bytes to pass through every
second.
By default, Xitami web sites and FTP sites do not use throttle pipes,
and run at full speed. You can choose a throttle pipe for a specific web
site (virtual host), and for an FTP service. You can also specify the
throttle pipe for individual FTP users. All connections that pass through
the same throttle pipe share its capacity. So, when you specify the same
throttle pipe for five FTP users, these will share its capacity. If you
want to give each user the full capacity, you need to define five throttle
pipes.
The predefined throttle pipes are in the file pipedef.xml. This XML
file specifies each throttle pipe as an 'instance' of a general pipe
definition. So, for instance, it may define two instances of a 64k pipe.
Each instance is a real, usable throttle pipe.
You can edit the pipedef.xml file directly, but it's a better idea to
copy it, and edit the copy. Change the server:pipedef option to indicate
the new file name.
When you edit the pipedef file, be sure to read the comments at the
beginning. These explain the XML syntax that you can use. The XML file is
case-sensitive.
Xitami defines pipes in terms of bytes per second, not bits per second
(unlike most Internet connections).
.-----------------------------------------------------------------
.page A Beginner's Guide
.build anchor beginners
Xitami does the same work as any other web server (only faster and more
reliably), so this section covers general information that you can probably
find on the Net, in a hundred books, and in documentation for other web
servers. Since you chose to look here, we'll feel free to mix our opinions
with our advice.
You must of course have a good idea of 'Why?' before you start building a
web site. Who is going to access it, how often, and to get what information?
A web site is basically an exercise in publishing. So be prepared to spend a
lot of time writing and editing material. Web sites that look like video
games may be fun to build, but are usually painfully slow to work with, and
don't necessarily add any value to the information you're presenting.
There are many tools that help with the process of building and managing
the many HTML files you will need. However, there is no substitute for a
good knowledge of HTML (which is a simple language) and for some
skill in managing complexity. The shareware HTMLib library is an excellent
reference for the HTML language. (Htmlib is written by Stephen le Hunte: to
find it, search $(*altavista) or any of the other big search engines.)
You may find that a tool like MS FrontPage is ideal for managing this
problem. You may alternatively prefer a more mechanical solution, such as
the $(*htmlpp) preprocessor that we use for our web site. Of course, we
recommend htmlpp. It's simply more open and flexible than any do-it-all
environment like FrontPage. Whatever choice you make, these are some of the
issues you will have to manage when you start producing dozens, then hundreds
of HTML files:
Xitami is quite simple to set-up -- basically it runs with no
configuration at all -- but your TCP/IP set-up must work first. You can
start by making a stand-alone site (a browser talking to Xitami on the
same machine), then connect your system to a network and let other
people access your pages. This is a checklist of things to do:
This section describes how to make your web site available to other
people. The problems involved in connecting on an internal network are
a little different from connecting to the Internet itself.
So long as you have TCP/IP installed and running you can use
127.0.0.1 and 'localhost' (which both mean the same normally)
and which TCP/IP interprets as the 'loopback address', i.e. the
current machine.
When you want to talk to other computers you need to know their IP
address. Correspondingly your system also needs an IP address. And
your address has to be unique, network-wide. When the network is the
Internet, this means world-wide. There are two ways to get such a
unique address. One, you ask/pay someone for a fixed address. Two,
you work with an ISP that owns a pool of addresses. This is
typically how dial-up PPP connections work: the ISP will lend you an
address for the duration of the connection.
Now, if you dial-up on a PPP line, and you do 'ping xxxx' where
'xxxx' is the name of your system, ping will tell you your current IP
address. Other people can, then, connect to that address and access
your web pages. This works. But they have to type the literal
address: 'xxx.xxx.xxx.xxx'.
TCP/IP uses a system called DNS to translate a name like 'imatix.com'
into an address. DNS uses a network of servers that are able to
translate names into addresses. So when you use Netscape to access
imatix.com, your local TCP/IP interface asks its local DNS server to
translate the name. This goes off, and after several hops comes back
with the address, and then you can connect.
The system name must of course be unique, within the network, or
world-wide on the Internet. Again, you can get unique names in
several ways. You can extend an existing domain name
(research.imatix.com) or invent a new domain name (some-thing.com).
Domain names must be registered with the Internic. This costs $70
for 2 years and $35 per year after that. You can do this directly or
via your ISP. It's quite a fast process; the only problem is finding
a good domain name that's not already used.
In general, you'll find that a dial-up PPP connection is not much use
for a web server, since your IP address changes each time you dial-in to
your ISP. (Ignoring the fact that local phone calls still cost quite a
lot in many parts of the world.) There are some interesting sites that
help get around this problem by acting as DNS/proxy servers for such
connections. If you want to do this kind of thing, you'll have to
investigate yourself -- we're getting too deep for a beginner's guide.
See your network administrator to get an IP address. Then,
configure your TCP/IP software so that your computer is reachable from
others on the network. Generally you'll already have got TCP/IP working
even to run Xitami on a stand-alone system. What changes with respect
to an intranet is that you need an IP address, and it can't be the same
as any other IP address on the network.
When TCP/IP is working correctly (even before you start Xitami) you
can use the 'ping' command from other machines to check that your
machine is addressable. Type ping like this:
Where 'xxx.xxx.xxx.xxx' is the IP address of your machine. If this
works, then you can start Xitami and access it from a browser using the
URL http://xxx.xxx.xxx.xxx/.
The next step is to get your system known by the DNS (domain name
system). An intranet usually has one or two domain name servers,
although it's not mandatory. If DNS is working, you can configure your
TCP/IP to talk to the DNS server - then other PCs will be able to refer
to your system by name, not IP address.
If you do not have a DNS server, you can generally use the 'hosts'
file (in Windows this sites in C:\Windows) to translate IP addresses
into names and vice versa. Each computer that want to access your web
site needs to put a line in its hosts file. This is a bit tedious,
which is why DNS exists.
Getting your site onto the web involves cooperation from a commercial
provider of some sorts. You can get help from:
A good solution for a small web site is to pay for a fixed line. There
are various technologies; ISDN, ASDL, POTS (plain old telephone something)
... Check-out the capacity of the line and shop-around for the best deal.
This gives you the most flexibility and control of your system, but may be
limited when handling large volumes. The most interesting type of connection
may be the kind offered by TV cable companies: in some cities this is a very
cheap way to get high-speed IP connections. However, check the rate at which
you can send data out from your server - this is sometimes quite low.
The actual steps involved in setting-up an Internet host are (and
feel free to correct me on this; this is coming from long-unused memory
cells):
This is a lot of fuss for normal people, and an ISP can usually do the
whole job for you, though they will charge something extra.
You can also become your own ISP by setting-up a pool of modems, and
arranging for dial-up accounts into an internal intranet. This can be very
effective for networks with a specific set of clients - for instance,
salesmen who travel a lot. It can also work in regions where real Internet
connections are expensive or not available. If you want to do this you
should find someone who knows about such things.
Virtual Hosts are a useful way to manage independent and separate web
sites on a single system, with one copy of Xitami running on the main HTTP
port 80. The user sees separate web sites - you need only manage one server.
This is of most use when you want to host several sites but only manage a
single web server. You can also run one copy of Xitami per site. Since
Xitami is small and does not use much memory both approaches are practical.
The $(*vhosts=virtual_hosts_section) gives a detailed explanation of what
virtual hosts are and how to set them up. We'll cover some more introductory
topics here.
When you define virtual hosts, each virtual host can have its own
webpages directory, CGI directory, log files, error messages, password file,
timeouts, etc. In fact, almost all Xitami options except those that affect
the whole server (such as the port) can be specific to the virtual host.
To define a virtual host you define a specific config file - this
contains all the options that are specific to that virtual host; other
options are then inherited from the xitami.cfg and defaults.cfg files.
To create virtual hosts, you must be able to define new entries in the
domain name system (DNS) or be able to define multiple IP addresses on your
system. Neither of these are jobs for beginners, so if you've not done it
before, get competent advice.
It's a good idea to work with a 'test site'. This is simply a directory
on your PC where you install and test the HTML files, images, CGI scripts,
and other resources before you install them on your public web site. For
instance, the iMatix site is built on its own disk partition, where each
directory matches that on our web site.
We do not generally work directly on the files in the test site. Rather,
we build a package of HTML files, images, whatever, then install them into
the test site. This lets different people manage different sections of the
site. It's also a natural way to work when one uses tools like htmlpp.
There are basically two ways to update a web site: the 'dribble' and the
'stomp'. Dribbling means updating it in small pieces; a few files here and
there. This is typically how people work when they don't use a test site.
Stomping means shoving several tons of stuff onto the site at once, so that
everything is updated together. Dribble works for spot updates, bug fixes,
and such. But it is not a good way to work in the long term: stomping is
safer and not much slower.
We stomp our site using a couple of Perl scripts that find all files
changed since the last stomp; these files are compressed into a zip file,
which is sent by file transfer to the web site. There we decompress it. It's
a lot faster to do this than to transfer the individual files one by one
(firstly, zip files are compressed by about 75% unless you are already
handling compressed data, and secondly, it takes a second or two to
negotiate a file transfer, which is slow when you transfer dozens of small
files).
There are of course many free and shareware tools (such as Netload)
available to do this kind of thing, but none that we know of will use a
zip-style compression to save upload time.
Xitami produces standard NCSA-style log files that can be read and
analysed by most log file analysers. People often misuse the term 'hits' to
imply that one hit is one person visting the site. This is not true. For
instance, the iMatix web site has 250,000 hits in a typical month, but about
15,000 actual visitors, or whom perhaps 2,500 stay long enough on the main
page to trigger the page counter. Each page has several images as well as
the HTML text, and people will read several pages.
To accurately count the number of visitors to your site, you can count
the number of hits to the main page. If you encourage people to always visit
your site's main page (publish just that URL), then your statistics will be
more accurate.
This section still needs to be completed.
This section still needs to be completed.
.-----------------------------------------------------------------
.page Writing Web Server Extension (WSX) Agents
.build anchor wsx
WSX is the Xitami equivalent of protocols like ASAPI, ISAPI, etc. A WSX
program is always written as a multithreaded SMT agent, and is linked into
the server executable. Unlike the xxAPI protocols, WSX agents are not
loaded at runtime from dynamic link libraries, but are bound into the Xitami
executable. This is done mainly to keep things simple, but also because SMT
does not support dynamically-loaded agents.
A WSX agent handles some specific type of URL, based on the name of the
URL. For example, Xitami comes with two standard WSX agents - xiadmin and
xierror - which handle URLs starting with "/admin" and "/error"
respectively.
Writing WSX agents is not trivial, but it's worth it for certain kinds of
work. If you want to write WSX agents, you should take a good look at the
SMT documentation, and study the standard WSX agents. WSX is not a
'fast CGI' protocol. A WSX agent is tightly-bound into the web server,
while a CGI program is most definitely not. I'll summarise the differences
between a CGI program and a WSX agent:
A WSX agent talks to the web server (actually, the smthttp agent) using a
set of messages. When a user asks for a URL that matches WSX agent, smthttp
sends the agent a WSX_REQUEST or WSX_REQBIN message. The WSX agent processes
the request (which can be a HTTP GET or POST), and replies with a WSX_OK,
WSX_MULTIPART, WSX_BIN, WSX_MBIN, WSX_ERROR, WSX_REDIRECT, WSX_RESTART, or
WSX_KILL message.
The WSX agent gets a bunch of things from the web server: the URL that
was asked for, any arguments, the current HTTP symbol table, and the posted
data, if any. In return, it provides either the HTML data to show (for
WSX_OK, WSX_MULTIPART, WSX_BIN, or WSX_MBIN), a HTTP error code (for
WSX_ERROR), a redirected URL (for WSX_REDIRECT), or nothing (for the other
messages).
Like all SMT agents, a WSX agent is either single-threaded or
multithreaded. A single-threaded agent is simpler to write than a
multithreaded agent, but is more limited in what it can do. The two WSX
agents provided with Xitami are both single-threaded. More complex WSX
agents, such as the xilrwp agent, are multithreaded.
The main difference is this: a single-threaded agent can only handle one
request at a time. A multithreaded agent can handle dozens or hundreds.
If the agent can answer a request with little work, a single-thread can
be sufficient. If a request implies some 'slow' work, such as making a
connection to another process or computer, or sending some message to another
agent and waiting for a reply, a multithreaded agent is better.
In terms of programming, a single-threaded agent needs to use some
specific SMT notation (such as setting the SINGLE_THREADED macro to TRUE)
and does not handle any thread context. A multithreaded agent in contrast
works with a thread context block that contains all data for the thread.
You'll find details of this in the SMT documentation, as well as examples of
both types of agent in the SMT source code. For example, smthttp itself is
a multithreaded agent, while smtsock is single-threaded.
There are two broad classes of WSX agent: those which have to handle
session context, and those that do not. Examples of agents that require
session context are:
Examples of agents that do not require session context are:
HTTP is often described as a 'stateless protocol', but there are in fact
several ways to implement state. We can define state as a set of variables
that the server (or the WSX agent) needs to distinguish one user from
another, and to tell what state the user was in. I generally call this the
'context' for a session. Context is necessary if you want a decent level of
security, complexity, and ease of use. One commonly-used way to implement
context is cookies. These have a bad press: cookies are too often
abused to keep track of users' activity on a website. Another method is to
encode the context in the URLs used in the form. For instance, each submit
button or URL will invoke the same URL, but with an argument (?xxx) that
contains the context data. This has several disadvantages: sensitive
information that should be kept internally on the server may be sent to the
browser; the HTML stream can become very large; and the arguments sent back
to the server can also become very large. It has an advantages too: there is
no need to save any kind of data in the server.
My preferred technique is to save the context in allocated memory, and
then to encode a key in the URL, using the ?xxx technique. When
the WSX agent receives the request, it checks whether the key is present and
valid, and if so, continues the session with that data. If not, it can
choose to show an error screen or reinitialise the session. The HTML stream
is not affected by the size of the context, since all that is transmitted is
the session context key.
If you encode session in this way, you need to do a few things if you are
building a serious server:
One troublesome problem is the browser Back action. There is no way to
disable this, and HTTP/1.1 specifically states that there is no way to
change the behaviour of a browser's history (which is what this is). The
problem arises because when a user uses the Back action, they can resubmit a
form that is no longer meaningful in the current context. One solution that
we have used in this situation is to refresh the current form when we detect
that the user has a valid session key but an invalid 'step' (i.e. has used
the Back action). Another solution is to simply redisplay the main form
when this happens. In any case, it's worth educating the user -- if only
with a small message on the main form -- that the Back action is not a good
idea within these forms.
A WSX agent talks to smthttp. The protocol is strictly binary: smthttp
sends a WSX_REQUEST or WSX_REQBIN message to the agent; the agent processes
this and sends back a reply. Each request has exactly one reply.
The smtmsg.h and smtmsg.c modules provide functions to send and decode
WSX messages (as well as all the other SMT messages). These macros are used
to send a message to a WSX agent. Normally only smthttp does this, but you
may want to chain WSX agents so that one sends messages to another:
The request URL is an alias used to indicate what URLs the WSX
processes. You can use '/' to indicate all URLs for a website or virtual
host.
The HTTP symbol table is prepared as for a CGI process. That is, it
contains the same CGI fields, and the HTTP header fields under the same
conditions. Symbol names are converted to uppercase, with hyphens replaced
by underlines. For instance, the 'Content-Type:' header value is held as a
symbol called 'CONTENT_TYPE'. This block is stored as a table of strings of
the format "name=value" and a single null. The table ends with a null string
(two nulls in a row). To convert this block back into a usable symbol table
you can use the SFL descr2symb() function (from sflsymb.c). To use this you
must first prepare a DESCR block (which holds the size and data in a single
structure) as follows:
The virtual_host field is NULL if the request was made to the default
host; if the request was made to a virtual host, this field contains the
name or ip address of the virtual host as defined in the main config file
under the [Virtual-Host] section.
The post_data field contains the POSTed HTTP data, if any. In some cases
this data may be placed in a temporary file; in this case the post_data
field contains '@filename'. The WSX agent should read the data from
this file. It does not need to delete the file: this is done by Xitami
automatically.
This is the structure of a WSX request:
To unpack a WSX_REQUEST message into this structure, use this function:
For example:
When you've finished with a request, you must deallocate it as follows:
This is the structure of a WSX binary request:
To unpack a WSX_REQBIN message into this structure, use this function:
The WSX agent can reply to a WSX_REQUEST or WSX_REQBIN with one of these
messages:
The following macros prepare and send reply messages:
Note that the 'to' argument in these calls is the queue id of the smthttp
agent, which sent the original WSX_REQUEST or WSX_REQBIN message.
The code for unpacking these messages (if you're calling a WSX agent) is
similar to that described above for WSX_REQUEST and WSX_REQBIN. You can see
the details in smtmsg.h.
The WSX_OK, WSX_MULTIPART, WSX_RESTART, and WSX_KILL messages send
'html_data' to the web server. This data should respect the rules for CGI
output. Normally it would be a HTML page, e.g.:
You can also start the data with your own HTTP header fields if necessary,
using the traditional blank line to separate the header from the body, e.g.:
This argument must be a string, so to transfer binary data, Xitami also
understands the syntax '@filename', where filename refers to a
temporary file that Xitami will parse, send, then delete. The file
should start with a 'Content-Type: some/type' header, followed by a blank
line, and the file data. A WSX_BIN or WSX_MBIN message is probably more
efficient for transferring binary data, unless you already have a temporary
file sitting around.
The WSX_BIN and WSX_MBIN messages send a binary block of data back to the
web server. This should be formatted with a Content-Type: header, a blank
line, and the binary data as follows:
If you start writing a new WSX program, start from a skeleton. The
xierror program is a simple example of a single-threaded, context-free WSX
agent. This is pretty much the simplest example you can make. You should
start by copying xierror.l and xierror.c to new files (keep these
extensions).
Like any SMT agent, you start the design phase in the dialog (.l file).
Look at the dialog file, either using a text editor, or using the Libero
tool (which is amply documented in the Libero documentation from the iMatix
web site). You'll need to install Libero to make any changes to the agent.
Before you can test a WSX agent you must install it into the server
main() function. This is how the xierror agent is defined in the Xitami
program (xitami.c). First, we define a prototype near the start of the
program:
Then we initialise the xierror agent before starting the main HTTP agent.
Here is the code which initialises all the WSX agents, then the main smthttp
agent:
The order of these initialisation functions can be important. For
example, if you want to install dynamic WSX aliases (see below) when your
agent initialises, you must add the xxxx_init() call after the call
to smthttp_init(). This provides smthttp the opportunity to create its
main thread.
The Windows 95 and Windows NT source code is available for individual
developers and companies at various prices - contact us for details. You can
purchase this if you want to make OEM versions of the Windows servers.
The OS/2, UNIX, and OpenVMS source code is supplied with the Xitami source
package.
To install a 'static' WSX agent you have to change the config files for
the server; add an entry to the [WSX] section like this:
It is also possible to add and remove paths at runtime. There are two
macros that do this:
Note that the 'to' argument in these calls is the queue id of the smthttp
agent. You should use the following style of code to identify this queue id:
The vhost argument tells the smthttp agent what virtual hosts the WSX
agent should be accessible to. If this argument is NULL, the agent will be
accessible to all virtual hosts. If the argument is a virtual host name or
ip address as defined in the [Virtual-Hosts] section of the config file, the
agent will be invisible to other virtual hosts. Note that you can send
several WSX_INSTALL messages, for different virtual hosts, if required.
The best way to test and debug a WSX agent (as for any SMT program) is to
use the Libero animator. This is a simple code-generation option (-anim)
which causes the agent to display every step it goes through to handle the
request. Animation output is sent to the console or to one of the log
files, depending on the way you set-up the server.
Since the effects of a bug in a WSX agent will show-up as browser error
messages, or other funny reactions, you can also set the server:debug option
on. This causes all headers to be logged - a useful way of seeing what is
actually being sent back to the browser.
The basic rules of multithreaded SMT programming apply. Your program
should not block. For example, it'd be a bad idea to try to access a
relational database and execute some SQL code. The entire web server would
block while the SQL request was being satisfied.
If you need to do database access, there are other, more efficient ways
to do this. The best way we know is to work with more than one process; the
web server passes requests (transactions) to a second process that handles
them one by one. You can scale this model up to very large systems handling
tens of transactions per second. This is the type of approach that is well-
implemented using a WSX agent.
.-----------------------------------------------------------------
.page Extending Xitami with External Peer Processes
.build anchor lrwp
By Robin Dunn Any serious web-based application relies, possibly quite heavily, on
dynamic content. In other words, dynamically generated pages.
To facilitate the need for dynamic content, CGI was invented back in the
dark-ages of the Web (just a few years ago.) While CGI provides the ability
to do dynamic generation of web pages as well as quite an elegant and
flexible interface, it also has a very big wart. It is too slow for
serious work. The basic model that CGI follows is:
Unfortunately, each time the CGI process is started, it can be several
seconds before it is able to even begin processing the request. Depending on
the OS there may be a large amount of overhead in creating a new process.
There may be a Perl or other language interpreter to load and initialize,
followed by loading and parsing the CGI script itself. Database connections
may have to be made, files opened, etc.
Because of the shortcomings of CGI, server extension APIs were created by
the various web server vendors. For example, Netscape provides NSAPI,
Microsoft ISAPI, Apache ASAPI, and even Xitami has WSX. (Isn't it refreshing
to not have "SAPI" at the end?)
While these extension APIs do away with the overhead of process creation
they introduce a few warts of their own:
There have been several alternatives that combine the ease of use and
flexibility of CGI with the efficiency of Server extension APIs. One of the
most popular of these is called FastCGI
developed by Open Market, Inc.
FastCGI or other persistent CGI alternatives are, as the name suggests, a CGI
type of interface that is Faster than CGI. It could potentially be up to 20
times faster, or more, depending on what kind of startup/initialization
overhead the script has. It does this phenomenal feat by allowing the CGI
process to handle more than a single request each time it starts up. The web
server communicates with the running persistent CGI process via a socket and
sends the appropriate data to the persistent CGI process when the reqest is
made. The persistent CGI process does its thing, generates an html page or
other response and sends it back over the socket and then instead of
terminating, it waits for the next request.
Begining with version 2.2a, Xitami includes a persistent CGI extension
called LRWP, (which stands for Long Running Web Process.) LRWP is written as
a WSX agent which implements a simple protocol for communicating with external
processes called Peers. The peer process simply waits for the requests to
come from Xitami and then responds with a valid http response, just like a
CGI program. The main difference is that like other persistent CGI
solutions, the LRWP peer waits around for another HTTP request instead of
terminating.
LRWP is not FastCGI, but it is very similar. The protocol between Xitami
and the LRWP Peer is much simpler than the FastCGI protocol, and therefore
less prone to implementation differences or errors. However, given the right
circumstances it is possible to run the same program as both a LRWP Peer and
a FastCGI Peer with only minor differences in the startup code.
As mentioned above, the communications protocol between the LRWP Peer and
the LRWP Agent within Xitami is quite simple.
If multiple peers connect with the same alias name, then multiple
simultaneous requests will be able to be handled. If there are more
simultaneous requests then there are peers to handle them, then the
LRWP Agent in Xitami will queue up the requests and wait for a peer
to complete its current request.
Each component of the startup string is separated by a character with
an ASCII value of 255.
The content returned to the server will be treated just like the
output from CGI programs, so content-type and other headers are
significant.
There may be situations where this is a highly desirable feature, for
example if you are running a contest and only want to collect 100
entries, the peer could exit after collecting the desired amount and
then Xitami will fall-back to a static document at the same URI that
explains that the contest is now closed.
Another reason to exit is to ensure that any memory leaks in your
program or the interpreter it is built upon are released. In order for
this to be effective you probably will want to have the ability to
automatically restart your peer processes. (UPM is currently being
modified to allow this type of functionality.) For example, I know
people with scripts running in the FastCGI environment that only allow
the processes to handle 50 requests and then they exit and get restarted
by an external process monitor.
LRWP programs receive the same environment variables as a CGI program.
If you're in doubt as to which ones these are, either read this manual again
or run the testcgi program supplied with Xitami.
Included with Xitami is a small library of C functions to assist
in writing LRWP Peers. The source files are lrwplib.h and lrwplib.c and
contain the following functions:
Returns NULL on success and a pointer to an error message otherwise.
Returns 0 on success and -1 otherwise.
Returns 0 on success and -1 otherwise.
Returns 0 on success and -1 otherwise.
Returns 0 on success and -1 otherwise.
Returns 0 on success and -1 otherwise.
$+ -
$\(count_$1): $+\ -
.build anchor $1_$\(count_$1)=$+
.macro -noquote FAQ -
$(*faqlink=[Top]) $\(count_$1): $+\ -
.build anchor $1_$\(count_$1)=$+
.FAQ_TABLE i Installing and Configuring Xitami
.FAQ_TABLE 3 Windows 3.x Questions
.FAQ_TABLE w Windows 95/98 Questions
.FAQ_TABLE n Windows NT Questions
.FAQ_TABLE u UNIX Questions
.FAQ_TABLE o OS/2 Questions
.FAQ_TABLE c CGI and SSI questions
.FAQ_TABLE v Multihosting/Virtual Hosting
.FAQ_TABLE f FTP Questions
.FAQ_TABLE l Log File Questions
.FAQ_TABLE m Miscellaneous Questions
Create two files:
Xitami uses two separate user/password systems, one for web pages and
one for FTP access. To start with, create the defaults.cfg and defaults.aut
file as described above. Then, for each webpage directory you want to
protect, add an entry in defaults.aut. Enter the URL directory with or
without a leading '/' - it does not matter. Add each user with their
password. For instance, to say that only 'John' and 'Janet' can get at
webpages starting with '/personal', you write something this:
For FTP access, you need to define each FTP user separately. First, add
these lines to defaults.cfg:
A fairly classic setup is to define a personal web space for each user
which they can update using FTP. Be careful with this, since it's possible
to set things up so that any user can run a CGI program (unsafe on Windows
systems). However, this is how you do it:
Yes. For example, if you defined the variable WEBROOT to specify the
webpages location, use $\(WEBROOT) in the webpages setting. Note that
environment variables are set in your startup script at the operating
system level (e.g. .profile under Unix, autoexec.bat under Windows 95).
.build anchor reset-default
.FAQ i I've screwed-up my installation and nothing works - Help!
If you edited xitami.cfg, you have to get the original version back out
of the Xitami zip file or installation package. Under Windows you can use
Winzip or unzip to extract files from the .exe packages. If you only worked
through the WBA, you can delete defaults.cfg. See the previous question for
defining a new admin user and password.
.FAQ i I installed Xitami two days ago, and now I can't connect to it!
You probably set the server IP address to something. Delete the line
ipaddress=xxx in the defaults.cfg file. If you really grok it, delete
defaults.cfg. See the previous question.
.FAQ i What is a 'HTTP port', actually?
It is a TCP/IP port that is used for HTTP. (HTTP being the HyperText
Transfer Protocol, the means by which web pages, etc, get transfered around
(usually).)
.FAQ i Why do web servers want to use port 80 by default?
In order to contact a program running on another computer via TCP/IP
(such as, say, a web server), you need to know two things: the IP address of
the other computer, and the TCP/IP port on which it is listening for
requests. The URL always includes the name of the other system (or its IP
address), from which you can get the IP address that you need. The TCP/IP
port canbe included in the URL, but usually isn't. So you need
another way to find out the URL. Of the various ways that this could be done
(ask someone/another computer, guess, etc), the one chosen for most TCP/IP
services is "you just know what it is". That is, there is a "Well Known"
port number for most TCP/IP services including HTTP, which "everyone knows",
and if nothing else is specified then that is the one that is used. The
"Well Known" port number for HTTP is 80. So the servers want to use it by
default so that everyone will know where to find them by default.
.FAQ i Is there some way to disable the WBA completely?
Yes, set the security:admin option to 0.
.FAQ How do I know that my personal config 'xxx.cfg' is being loaded?
Edit the config file and add a line '! Loading xxx.cfg'. Now, enable
server debugging, and when you start Xitami, this message is output to the
debug.log file.
.FAQ i Why does the installation replace my xitami.cfg and .aut files?
It has to do this, since new versions of Xitami may depend on updated
\.cfg and \.aut files. The important thing is to make all changes in
defaults.cfg, and this includes defining your own .aut file, so that the two
standard files can be reinstalled at any time.
The installation will not override other files, except those provided as
standard in the install package (e.g. default.htm). So, as a general rule,
do not modify anything that was supplied as standard, and if you're really
paranoid, make a backup before you re-install Xitami.
.FAQ i How do I install a new version of Xitami without losing my config?
Firstly, make sure you did not change either xitami.cfg or xitami.aut.
If you did change these, put your changes into defaults.cfg and
defaults.aut, and add this to defaults.cfg:
If you are already running a server on port 80, you must configure Xitami
to run on some other port. Change or create defaults.cfg:
You can shift the HTTP port between 80 and 100 while leaving the FTP port
at 21. Set the server portbase to a value between 1 and 20, and subtract
this from the FTP port setting. So, to move the HTTP port to 90, set the
portbase to 10, and the FTP port to 11.
.FAQ i When I'm not connected to the network, Xitami is VERY slow!
Under Windows 95 and NT, your network configuration must match what's
really going on. For instance, if your TCP/IP configuration specifies a
particular gateway or DHCP server that is not available (because you are not
physically connected). Check that the host and domain info in the DNS tab of
the TCP/IP properties in the network control panel matches the info in the
identification tab of the network control panel.
One typical symptom is that when you click on the Xitami icon in the
taskbar, it takes a minute or two before the Xitami window appears. You may
also get error messages when trying to point your browser to 127.0.0.1. The
bottom line is this: if you want to run your PC off-line from the network,
you must ensure that your PC's network configuration matches. There are
various shareware tools that help you to manage multiple network
configurations, for example NetSwitcher.
.FAQ i 'ping 127.0.0.1' works but I can't connect to http://127.0.0.1/
There are many possible causes of this problem. The ones we know:
There are many possible causes of this problem. The ones we know:
The problem is that if 127.0.0.1 is passed to the proxy server, it can't
resolve that back to your local machine. You can configure your browser so
that certain addresses (127.0.0.1) are not passed to the proxy. This is
actually the browser being really silly, because this address never means
anything else than 'this machine'.
.FAQ i Why does my server address switch between 127.0.0.1 and 253.239.42.1?
127.0.0.1 is always available (it's the local loopback address); the
other address is available when you're online and connected to the outside
world.
.FAQ i I want to test a site but my browser can't find 'www.myhost.com'
Edit the 'hosts' file (in the Windows directory, and you may want to
rename 'hosts.sam' to 'hosts'), and point the your site name to 127.0.0.1.
.FAQ i What's the 'document root'?
The document root is the directory where the main files are. For example
if someone asks for a file "http://somehost/index.htm", this is taken to
mean 'index.htm in the document root'. This is usually the directory called
'webpages' in the Xitami directory. So if you installed Xitami in c:\xitami,
the index.htm file would actually be in c:\xitami\webpages\index.htm. This
webpages directory can itself contain subdirectories, of course.
.FAQ i Do I need two computers to use Xitami?
You can use one computer as a server, and one as a client if you like,
but you can also use the same computer as client and server. Xitami is so
small and fast that you can develop Java or CGI programs on the same system
you test them on, and you will not notice any slow-down. This is also a
simpler way of working than always copying your webstuff to another machine.
Just set your Xitami cgi-bin option to point to the directory where you
build your executables, or the webpages directory to your HTML directory
root.
.FAQ i Can I run Xitami on stand-alone machine?
You can certainly run Xitami on a stand-alone system. It is a Good Idea
to have TCP/IP networking installed (on a PC, go for Win95, OS/2, or Linux,
which have TCP/IP built-in, instead of Win3.1 which is crippled in this
area). You must install TCP/IP correctly and at least have a dial-up adaptor
(software) configured. The 'ping localhost' command must work. Under Windows
the winsock library may want to dial-up when you initialise it (e.g.
connect from your browser), but this can be configured (in the browser or
Internet control panel) to not be necessary.
.FAQ i Can I run Xitami under DOS?
Which version of DOS? We've not tested Xitami on a pure-DOS system, but
it does run in the DOS box of Windows 95. If you're looking for something
that will run on a PC without Windows, you could consider OS/2 or Linux:
both run Xitami very well and with minimum hardware.
.FAQ i Can I use Xitami over an ISDN or dial-in connection?
Yes, if TCP/IP works and the 'ping' command does something useful. The
Same goes for X.25, frame-relay, carrier-pigeon, and telephone drums.
.FAQ i How do I change my IP address?
By default, Xitami accepts connections on any available IP address.
If you have multiple IP addresses, Xitami accepts connections on all of
them. More usually under Windows you have only one network card, only
one IP address (though with a dial-up connection you have two interfaces
and two addresses). You can also configure Xitami to accept connections
on a specific address only.
.FAQ i Xitami is reporting the wrong server address!
Xitami gets its name from the operating system. Check the TCP/IP
configuration and especially the computer name. You should be able to
test this using the 'ping' command in a DOS box. Eg. 'ping mysystem'.
.FAQ i How do I tell Xitami to use my domain name?
Xitami works with any of the IP addresses available on the system. It
does not care what the domain name is, and there is no way to define this
within Xitami. (When you use virtual hosts the situation changes a little:
there the domain name is used as a key to chose which virtual host to work
with.)
.FAQ i How do I move my web site to an Internet domain name?
See the $(*beginners=Beginner's Guide) section. You have to do two main
things:
This is usually only worth doing if you have your own system, permanently
connected to the Internet, or you want to rent a 'virtual host' on someone
else's system. In the first case, your ISP can usually help set things up.
In the second case, the virtual host provider will be able to help.
.FAQ i Can I set my hostname in xitami.cfg or defaults.cfg?
You cannot set your system hostname here. You have to get this working at
the level of TCP/IP itself, e.g. by using the hosts file or a domain name
server (DNS). However, you can specify the hostname that's used in
redirected URLs, and this is important for virtual hosts.
.FAQ i My server keeps starting on port 160, why?
Set server:portbase to 0, or remove the line. The HTTP port is at
portbase+80, and the FTP port at portbase+21.
.FAQ i Why does 'http://address/directory' does not work?
This should work. Set server:debug to 1 and see what's going on in
debug.log. If you're on a PPP connection try setting server:translate to 0.
.FAQ i My images don't load, and various links give 'Not found'
You can switch off image loading in the browser, but I doubt this is the
problem. More likely, you're using references that are incorrect for the
configuration you're using. Look at the HTML pages, and check the <A
HREF> tags. These must be valid. For example if they refer to some
hostname which is not accessible, the images won't load.
.FAQ i Why do my aliases not work?
Set server:debug to 1 and see what's going on in debug.log. The WBA pages
provide a 'test' facility where you can type an URL, and Xitami tells you
what disk file it would be translated to.
.FAQ i How can I change the error 404 message in Xitami?
Edit the file errors/text-404.
.FAQ i What's 'Vanilla' Xitami?
This is just name for the portable, command-line version of Xitami.
Usually we use this term in contrast to the Windows GUI versions of the web
servers, which provide a graphical control panel for the web server.
.FAQ i Why is Xitami.aut not encoded?
This is a temporary situation: we plan to release an update in 1998 that
uses encoded (hashed) passwords for better security. The password file
itself is not accessible to browsers, unless you specify the Xitami root
directory as its webpage directory, which would not really be a good idea.
There are also advantages to plain-text password files: it is simple to
manage these using scripts.
.FAQ i After running a script that modifies defaults.aut, how do I get -
the same script to restart the server?
You don't need to, since Xitami will automatically reload its config,
including any modified password files, after a timeout that you can set as
required (the server:refresh option).
.FAQ i Can I use 'home.html' instead of 'default.htm'?
Change the defaults.cfg file server:defaultn options. You can specify
anything you like: begin with 'default1'.
.FAQ i What is defaults.cfg? I can't find it anywhere!
Up to v1.3a, people had to modify the pre-supplied xitami.cfg file. This
worked fine until they installed a new version, at which point they could
start again. Defaults.cfg is not supplied with the server - you just copy
the part of xitami.cfg you want to modify. Eg.
The webmask is a bit pedantic. This mask forbids all hosts in a certain
domain, but does not allow other hosts. Follow it by ',*' to allow
all other hosts: webmask=!xx.xx.*,*
.FAQ i How do I make my server run faster?
Make sure the server:keep-alive option is enabled. Add lots of RAM to
your system and make sure this is available to your operating system disk
cache. Put your web site onto a RAM disk. Don't use lazy, slow CGIs,
especially ones that search large databases. Change the priority under
Windows NT to 'High'. Raise the keep alive limit to 100 or more under
Windows NT, or Unix (not under Win95 or your system will have problems).
.FAQ i How do I make my server secure?
Firstly, consider buying Xitami/Pro which includes support for SSL/2,
SSL/3, and TLS.
Then, understand that there are several standard ways to compromise a
system via a web server:
The main protection is to run Xitami on a system that has no basic
security problems (i.e. Linux v.s NT), and to run it under a user id that
has minimum privileges (so that even through a buffer-overflow attack, the
hacker cannot do much damage). Disabling CGI is also a good idea. FTP does
not pose much risk either way, if you disallow uploading, which allows a DoS
attack (fill-up the hard disk).
Here is Brian Westric's checklist for securing Xitami under Windows NT:
You do not need aliases. Simply assign each user a subdirectory of
the webpages directory, then specify this directory as their FTP home
directory (using a full path).
You can also do it using aliases: create HTTP aliases which point into
the FTP space. So, user Joe gets a FTP directory: 'ftproot/joe'. Then
define a HTTP alias:
The ~username syntax is a UNIX thing; the UNIX shell translates ~username
into the home directory for a user. Xitami does not yet support this
automatically. However you can get much the same effect by creating a
subdirectory for each user underneath the webpages directory, called
'~username'.
.FAQ i In FTP, 'ls' fails from a remote system (it works locally)
This is probably due to the remote machine being hidden by a router or
firewall which prevents return connections from the FTP server to the
client. You should use passive mode for such connections. The next release
of Xitami handles this situation better, but the basic problem is
unsolvable; if the client is behind a firewall or router that does not allow
reverse connections (i.e. server to client) then the default FTP protocol
does not work correctly.
.FAQ i No-one can get to my server. I can get in, but no-one else can
From Paul S R Chisholm and others...
The 'ping' command (from the client to the server) is the simplest way
to make sure that there is a TCP/IP connection actually established.
However, because of "ping of death" attacks that have become popular over
the past year or so, a lot of routers have been shutting off ICMP. Thus,
ping doesn't work. traceroute (a.k.a. tracert) doesn't work either. This
last one really hurts, in my experience. There are other things to try:
You can still try ping and traceroute/tracert, but their failure may not
mean anything. (Their *success* is encouraging.)
Another possible problem is that your server is behind a firewall or
proxy server which is preventing HTTP access (it may even allow ping to
work.) If this is the case, see your network administrator for help.
.FAQ i No-one can connect to my server through the firewall!
In some networks, your server may not even be addressable from beyond the
firewall. In this case you cannot do much. In other cases, the server is
addressable, but the firewall may be blocking some combination of ports and
protocols and addresses. If this is the case you may be able to convince the
network administrators to open-up access to your server on port 80.
.FAQ i Why does the Restart function not work?
Some functions are not affected by the Restart function. You cannot
modify the HTTP port through this function. If you find that the Restart
function has no effect on the configuration change you made, you will
need to stop and restart the server program fully.
.FAQ i The browser is not showing my new pages
There are various reasons why a browser will cache out-of-date pages.
These are the most common ones:
If you load a default page, the browser caches it under a URL name with
no filename, e.g. 'http://localhost/'. If you then switch to another
webpages root and request the same URL, the browser will compare dates and
load the current default page only if it's more recent. You'll often find
that requesting the full filename will work correctly. This problem can
occur if you upgrade to a new release of Xitami, then take a look at the
'Welcome to Xitami' default page. If you then switch to your own config,
the browser won't show your default page. This problem can also happen if
you run Xitami with different webpage roots, for instance to test different
sites. The solution to the first case is to flush the browser cache. In
the second case, disable the server:cache-defaults option.
.FAQ i I want several 'sites' on the same IP address, on different ports
You can run several copies of Xitami, each in a different directory, and
each on a different port. Xitami is small enough that this will not slow
down the system. In each directory, create a suitable defaults.cfg file
with the server:portbase set to a different value.
.FAQ i How do I use Xitami on several different web projects?
It's common to use Xitami to test different web projects on the same
system. Generally we create a suitable root directory with the
defaults.cfg, authorisation, and other site-specific files, then run Xitami
in that directory. Put the Xitami executable on the path. You can also run
the Xitami command-line program (For Windows, xidos32.exe) with command-line
options to set the webpages, CGI, and FTP directories (-r, -c, -f). It's a
good idea to set the server:cache-defaults option to 0 if you use this kind
of setup, so that default pages are always loaded correctly.
.FAQ i How does Xitami work with subdomains?
Let's say you have a domain, like imatix.com, with a fixed IP address
(207.92.100.8 or something like that). The domain-name servers provided by
our web site providers (azc.com), handle the translation from imatix.com to
a numeric address. For fun, we defined www.imatix.com and ftp.imatix.com to
point to the same address, i.e. the same network card on the same system.
It'd be quite possible to define further subdomains, all ending in
imatix.com, and all pointing to the same system. We call these 'virtual
hosts' since each apparently distinct system, or host, actually comes back
to the same thing. Xitami lets you define a specific profile for each
virtual host, which you can create using the WBA virtual host wizard.
All this works under the same single registered domain.
.FAQ i Where can I get (just) primary & secondary DNS hosting for cheap?
Try the public DNS service at http://soa.granitecanyon.com/. It's free.
You can also try using a .nu domain instead of a .com one. Go to
http://www.nunames.nu for info. They also link to a service that does the
full DNS service for $49.95/year. nunames updates your DNS info with an
interactive program right on their web site and it's effective within 24-48
hours. Similar services are available at www.tonic.to.
You need a TCP/IP winsock.dll. And it has to work. And it has to be
configured correctly. If you have any kind of difficulty running Xitami
or connecting to it, use the PING command to debug your TCP/IP
configuration. First, use 'ping 127.0.0.1' to check that TCP/IP is
working. Then, use 'ping localhost' to check that winsock.dll is
working. Next try ping with the system name that Xitami displays.
Then, try this command from another system. All these must work before
you can use Xitami.
.FAQ 3 'Could not open HTTP port 80 - Protocol not known'
Your TCP/IP protocol is not correctly installed. Ping must work!
This is typically caused by inadequate winsock dialers that have incomplete
support for server applications. Try Trumpet winsock, which we've been
told works.
.FAQ 3 Are there still plans to introduce CGI for Win 3.x?
No. We are moving off this platform in the long term. You'll find that
the 32-bit console version of Xitami runs pretty well under Win32s, although
CGI does not work due to filesystem incompatibilities. You can
write LRWP programs under Win32s.
.FAQ 3 When will FTP work in the Win 3.x version?
This will never work, due to memory limitations. We've had reasonably
good results running the 32-bit console version on top of Win32s, and we
recommend you try this if you really need the FTP and other features (such
as WBA and LRWP) which are missing from the 16-bit version.
.FAQ 3 Why does xiwin16.exe use all my CPU?
When idling, xiwin16.exe spends most of its time waiting for incoming
socket events. Under Windows 95 or NT, a 16-bit program that is waiting for
socket events looks like it is sitting on the entire CPU. Maybe it is.
Anything can happen in this business. However, as far as we can tell, the
program really is idling, and does not slow-down the system. If this bothers
you, move to Windows 95, and run the 32-bit version of Xitami. This uses
Windows threads (as well as its own internal multithreading) to reduce CPU
consumption to 1% or less when idling.
A decent web server like Xitami does not need large amounts of memory or
a blazing CPU. You can happily serve a group of several hundred users from a
486 PC with 16Mb memory. If you want to run heavy CGI programs, you'll need
a faster system. Also, a fast hard disk is a good idea. And of course, any
server is limited to the speed of the network. Given a fast hard disk and a
fast network, Xitami will be able to handle several hits per second even on
a slow 486 PC, and dozens of hits per second on a fast Pentium. (One hit per
second is equivalent to about 20 users actively browsing, at the rate of a
page per minute where a page requires about 3 accesses. If an average user
browses for an hour a day, one hit per second thus translates into 100-150
users.) Note that the earlier releases of Win95 are not really too stable.
Note also that Win95 and Win98 appear to be unstable when they are very
heavily loaded; this does not happen with WinNT, and we assume this is done
deliberately, since in principle the TCP/IP code is shared between these
systems (at least the later Win95 releases). Windows 95/98 leak memory when
the TCP/IP stack is heavily used. If you want to run a web server on a
small cheap system, use Linux.
.FAQ w Can I use ASP (Active Server Pages) with Xitami?
If you have Visual Basic 5.0, you can convert your ASP pages with the VB
conversion module provided in the server pack. You will need to make some
modifications to the ASP code. You can then compile it as an executable
program, and run it as a normal CGI program.
.FAQ w 'Could not open HTTP port 80 - Protocol not known'
Your TCP/IP protocol is not correctly installed. Try these steps:
You are running another web server (perhaps MS PWS) - remove it then
run Xitami. In some cases you may have to edit the registry; look for
a key 'Runservices' and delete any references to previous web servers.
You can also run Xitami on another port by changing the server:portbase
option, e.g.:
Using regedit, edit your registry:
Check you're not using a Wingate proxy server or something similar on
Xitami's port. If you are, switch Wingate to port 90.
.FAQ w How can I tell what TCP/IP ports are assigned?
You can find out which TCP/IP ports are being used with:
When you use a URL starting with file://, this is not handled by Xitami
at all, but by the browser which picks-up the file from the local system.
Xitami can handle URLs starting with http: and ftp:.
.FAQ w Tips for using Xitami with dynamic IP addresses
From Alex Feinerg a.k.a Yoonicks@EFNet and others...
Ping is a good test to see if your computer name can be translated
correctly. If you're on the Internet, you need to ask your Internet service
provider to make the necessary DNS entries. On your own PC, you can edit the
'hosts' file in the Windows directory. The file 'hosts.sam' is a sample that
you can rename to 'hosts'. Then, add your machine name and 127.0.0.1. This
may not always work; address translation may require that you are actually
on-line. For instance, I can 'ping 127.0.0.1' at any time. When I try to
'ping localhost', I get the TCP/IP dial-up dialog. I can Cancel this, and
then 'ping localhost' works. But to ping my machine name, I must be online.
.FAQ w How do I debug my Windows network connection?
Windows 95 includes two tools besides ping to test TCP/IP connections:
tracerout and winipcfg. With tracert, you can follow the route for a TCP/IP
connection. Open a DOS prompt and type the command: tracert
somehost.com. The program shows the route to the host, up to 30 hops.
Type tracert with no arguments to get help. Winipcfg shows you your IP
address(es) and some more information about your network. Just type
winipcfg; it's a Windows program.
.FAQ w Xitami just sits there blinking between 'Running' and 'Suspended'
The server is trying to start up, but there is a problem with the TCP/IP
connection. Its default reaction prior to release 2.3c was to wait and try
again, it blinks between 'Running' and 'Suspended'. You can edit the
defaults.cfg file to include these lines:
For security, Xitami does not allow access through short filenames when a
long filename is defined. Without this check, it's possible to bypass
user/password authentication by using the shortened name for a long name, or
vice-versa. When you get this error, the xitami.log file will say '- request
refers to an illegal filename'. One consequence of this security check is
that if you use short filenames in your alias or webpages definition, all
requests through to those files will be rejected with a 403 error (not
authorized). Use the full long filenames in alias or webpages definitions,
or if the security issue does not bother you, set the security:safepaths
option to 0.
.FAQ w I get 'Not authorized to access this resource' on other URLs
There are a number of specific reasons why Xitami may return this:
In most of these cases, the reason for the error will be logged when you
enable server debugging.
.FAQ w How do I change my 'web server address'?
Xitami gets its host name from the operating system - i.e. Windows. Your
IP address is not something that Xitami can change or choose. Check your
network configuration and if neccessary, ask your network administrator. The
same applies to the hostname that Xitami displays. This is the name of the
system as supplied by Windows. You can change this in the network control
panel.
.FAQ w My web server address is 'http://default/' - why?
Check the TCP/IP configuration; your system is probably called 'default'.
.FAQ w Can I run RealServer on the same system as Xitami?
Yes, but change RealServer's port from 80 to something else (e.g. 1024).
.FAQ w My 16-bit CGI program does not output anything
You cannot correctly run a 16-bit CGI program that is on a path with
'long filenames'. For instance, if you installed Xitami in 'C:\Program
Files\Xitami', then put a 16-bit CGI into the cgi-bin subdirectory, it will
run, but its output is lost, and the browser will eventually time out and
show a message like 'Document contains no data'. The fix is to either move
Xitami to a directory like 'C:\Xitami' or create a CGI alias and put the CGI
programs elsewhere than under the Xitami root.
.FAQ w How do I use the FrontPage extensions with Xitami?
The FrontPage server extensions are not documented and as far as we have
been able to test, they do not work with Xitami under UNIX or under Windows
NT. Support for specific servers appears to be added at the whim of
Microsoft, so you may want to try writing Bill Gates a sweet letter. We're
not in the business of reverse-engineering Microsoft software.
.FAQ w Win95 crashes with a GPF in VxD IFSMGR(01)
Upgrade to a more recent version of Windows 95. There are several known
problems with the winsock library and Win95 kernel in pre-1998 releases of
Win95. See the question below on miscellaneous Win95 crashes.
.FAQ w Win95 crashes with a GPF in WINMM.DLL
Check whether you are running Win95 with service pack 1 (also called
OSR-2.1). In 'My Computer', select Properties, and you'll see the version
number. If you have 950a (service pack 1), you need to upgrade to 950b.
As far as we know this is only available as an OEM CD-ROM.
.FAQ w Win95 gives me an error 10055 - Out of buffer space
This can happen when you load the TCP/IP system heavily by running lots
of servers. There is no cure except to switch to WinNT, OS/2, or Linux.
.FAQ w Win95 still gives me errors when I use Xitami
Apply the various Windows 95 'service packs' and updates. This is our
list as of August 1998:
Check your clock; Xitami is known to crash if the clock is set to later
than the year 2038.
.FAQ w When I access my local site, it takes 3-4 minutes to load!
Change the Internet Control Panel not to autodial. (In MSIE3, choose
View, Options, Connection, and clear the option 'Connect to the Internet as
needed'; for MSIE4, tell it you have a LAN connection, not a modem
connection).
.FAQ w Why does Xitami use all my CPU?
You probably set the priority to 'High'. This is excellent if you do not
use the system for anything else, but is not a good idea if Xitami shares
the system with other users. At high priority, Xitami will consume most of
the CPU time during large downloads. We do recomment High priority for a
dedicated web server, and 'Normal' for a mixed-use system.
.FAQ w When I run a CGI, I get a blank screen for several seconds
Check that you've not configured your MS-DOS command window to appear
full-screen. When the Xitami web server launches the CGI program, it does so
in a way that says don't create a console window for the application.
However, if the command window agent is configured for full screen, it
switches first to full screen before making the test for putting up a
console window which causes the blank screen to appear (sometimes with a
blinking cursor). There doesn't appear to be a way of preventing this
behaviour programmatically.
Use unzip (WinZip, etc.) on the installation .exe file. This file is
compatible with the zip format.
.FAQ w Xitami is reporting errors on its control panel
Xitami reports 'Not Found', and any other 3xx, 4xx, or 5xx return
code as an error on its control panel.
.FAQ w Can I run multiple instances under Windows?
You can run multiple instances of xiwin32.exe or xidos32.exe in separate
directories (each with its own web space, config files, etc) and specify the
portbase either on the command line or in the defaults.cfg file.
.FAQ w IE sometimes fails with multiframe documents
Microsoft IE 3.0 has occasional problems mixing keep-alive connections
with highly-framed documents. The symptoms are that the last frames will not
display. IE opens a connection, asks for a document, but prematurely closes
the frame. Workarounds: use Navigator, a more recent version of IE (we
assume the problem may be fixed), or switch-off keep-alive if you are using
heavily-framed documents.
.FAQ w Windows says 'URL.DLL not found' when I choose 'Setup'
URL.DLL is a Windows DLL that is installed as part of TCP/IP networking,
and allows you to double-click a .htm file to launch a browsers. Xitami uses
this technique to launch a browser when you click on the 'Setup' button. You
can either try installing TCP/IP networking (again) or start a browser and
enter the URL 'http://127.0.0.1/admin' yourself. This file may only be on
the OSR/1 release of Windows, or may be supplied with MSIE or Navigator 4.
.FAQ w Why is Windows ignoring my changes to the hosts.sam file?
This file must be called "hosts", without an extension.
.FAQ w What's CGI/Win?
The CGI/Win protocol (which Xitami does not support) uses a mechanism for
transferring the stdin/stdout and environment data that is different from
the normal CGI manner. It's meant to support languages like Visual Basic
that do not have access to stdin/stdout streams.
.FAQ w Do you know of a good free proxy server for Windows?
Louis C. Lupin says: VSocks is a freeware Socks 4 proxy. It's easy to set-up
and use. See http://www.pscs.co.uk/software/support/vsockslight.html.
.FAQ w Do you know of a good free e-mail server for Windows?
Thomas Schroeter says: On www.freeware.com, I found a very good server
(VPOP3) which includes POP 3, SMTP, finger connections, forwarding accounts
and autoresponders. The program has a lot of settings (user accounts,
headers, listserver, logging, error reporting, ...). It runs with Windows 95
and it's very fast. Now, I'm using Xitami and VPOP3 together - both programs
are working very well in my local network.
Justin Scott says: Try the freeware version of SLMail .. it supports
upto 6 users, and an autoresponder. It's a commercial-grade e-mail server
for Win95/NT. If you want more than the 6 users available in the freeware
version, you'll have to get the standard edition for win95 (SLMail v2.6),
which runs for about $200 (go with the freeware). It is available from
Seattle Labs at www.seattlelab.com. Hope you find it useful (I know I do :).
Ian Hayes says: For Win95/NT you can get a nice little SMTP server called
JSMail at http://j-bg.demon.co.uk It does SMTP, POP3, finger, autoresponders
and you can reject mail based on Received: lines, source or subject words.
Reverse DNS, anti-relay, and RBL support (for those interested). Of course,
you'll still need a domain, and when mailing to certian domains, an MX
record. Monolith provides both for free. You can run it as a service or from
the command line. Takes up very little resources.
.FAQ w Do you know of a mail client for Windows?
Mailto is a small,
free, and simple mail client by Scott Beasley, author of the SFL sflmail
module. This program lets you send e-mails from within CGI programs, with
attachments. Mailto.exe even runs as a configurable CGI mail form program.
This package is only about 35K.
.FAQ w Any hints for boosting Xitami's performance?
Xitami installs this batch file when you install the Xitami Console
version as a Windows 95 service. The service.bat file simply sets the
correct working directory, then starts Xitami. To disable this, you can edit
service.bat to remove the call to xidos32.exe. You can also remove the entry
for service.bat in the registry; run regedit and find the key
SOFTWARE\Microsoft\Windows\CurrentVersion\RunServices. You'll see a
definition for service.bat, which you can delete.
.FAQ w I installed MSIE 5 and uninstalled it, and now Xitami crashes -
whenever I try to start it up.
Yes, indeed. Well, what do you expect when you install and then remove
half of your operating system? Probably the only cure is to format the hard
drive, and install a clean copy of Windows 95 or 98. Maybe reinstalling
MSIE 5 will help.
.FAQ w I'd like to run an abitrary Windows program from a browser
Okay, but be warned that this opens your system to arbitrary abuse. You
cannot launch a Windows program directly, since a CGI program runs as a
hidden console (DOS) process. However, it's trivial via a small batch file,
which itself starts the Windows program. For instance, here's a batch file
that starts any program at all using the CGI argument, e.g.
"/cgi-bin/run?notepad", where run.bat contains just 3 characters: "@%1".
.FAQ w Can I stop Xitami from the command line or a batch script?
You can use the wmkill.exe program supplied with Xitami. Wmps.c and
wmkill.exe were written by Thomas Grobicki of Avilar Technologies to perform
the functions of the Unix ps and kill commands for Windows 95/98 and NT. To
kill Xitami, use this command:
Under Windows NT, you cannot run 16-bit CGIs at all, due to a limitation
of the Windows 32-16 bit interface. A simple workaround is to use a batch
file like this:
The problem is one of security; the service runs under the account
'system' by default, and this may not have access to your network drive. In
the Services control panel, you can change the start-up options for the
Xitami service so that it logs-on as a user with the necessary privileges.
.FAQ n The Xitami service fails to start, saying 'Access is denied'.
You should install Xitami when logged-on as administrator. You can fix
this quite simply. In a DOS box, go to the Xitami directory and type
'xiwinnt -u' to uninstall the service. Now log-on as administrator and use
'xiwinnt -i' to re-install the service. If you still have the problem,
de-install Xitami completely, and re-install after logging-on as
administrator.
.build anchor start_service
.FAQ n The Xitami service still fails to start!
Search for the string "xiwinnt.exe", which may appear as follows:
When you installed the Xitami service, it installed the Xitami control
panel file in the Windows System directory. Delete the file called
'xiwinntc.cpl'. If you install and uninstall the NT service version, this
file gets left behind due to an access conflict (which we have not
figured-out how to resolve). (Details: if you use the 'Add/remove software
components' control panel option, then the Xitami CPL is loaded, and can't
be deleted...)
.FAQ n I defined a new VH and now my NT service won't run
Check that the specified .aut file exists, even if it's just empty. Check
the Xitami log files for error messages. If in doubt, run the console
version to see what error message is being produced.
.FAQ n When I try to install Xitami on NT 4 I get a dialog box that says -
"Corrupt installation detected"
Could be that the install .exe has indeed been corrupted. Try downloading
it again and trying again. If this fails you could be seeing a problem with
the 16-bit subsystem in NT. Did you install any service packs? (I think SP2
or 3 fixed this problem...) In any case you can easily install from the .zip
file; if you're using the service version, install it by copying the .cpl
file to the Windows system directory, and run 'xiwinnt -i'.
.FAQ n Can I use 'srvany' with Xitami?
Yes, this is a good way to run the console version as a service. You can
get srvany from the NT resource kit, or you can download it from MSDN (the
Microsoft Developer Network web site). The following tips were provided by
Ignacio "Iggie" Bustamante.
Xitami should build on: IBM AIX, Digital UNIX, HP/UX, Sun Solaris, SCO
OpenUNIX, SCO OpenServer, FreeBSD, NetBSD, Sinix, and of course Linux.
Anything else is unexplored territory, and that includes the future, since
some of these systems are starting to come without an ANSI C compiler as
standard.
.FAQ u I need to search /usr/src/linux/include/ at build time
The Xitami build uses a script, 'c', that lets you specify additional
compiler options by setting the CCDEFINES variable. So, to specify an
additional include directory, use shell commands like this before starting
xibuild:
Yes, if you have access to an ANSI C compiler. Build Xitami as usual, and
run it with a command like this: 'xitami -b 5000 -s'. Avoid port 8080 which
is often used for proxies. You may also find that the ISP kill all
long-running processes at regular intervals (e.g. midnight). The -s switch
runs Xitami in the background; it's a bit cleaner than using 'nohup'.
.FAQ u Does Xitami support .htaccess with per-directory access control?
No, Xitami uses its own .aut files for access control.
.FAQ u How can I run Xitami and have it listen on port 80 under Unix?
Under Unix, only processes that are running as root are able to listen
for new connections to TCP/IP ports less than 1024, including the well
known HTTP port 80. So for Xitami to listen for connections on port 80
it needs to be run as root. And of course there must not be another web
server running that is already listening for connections to port 80.
There are three ways that you could do this:
iMatix does not recommend setting Xitami "setuid root" except in
situations where only people who can be trusted to run any program as root
have access to log in to the machine, such as a personal Unix box. Even in
this situation the use of a program like "sudo" should be investigated as a
possible alternative. Please also take a look at the next question
concerning security aspects.
.FAQ u What are the security implications of running Xitami as root?
From Xitami 2.4b onwards it has been possible to request Xitami to change
to a different user id and group id from the one that it was started in, for
most of the time it is running. To do this in the [Security] section of
defaults.cfg put:
When [Security] setuid=1 is used Xitami changes the effective user id and
group id to the ones specified. However it also retains the privileges with
which it was started (commonly in this situation root privileges), in order
to be able to reopen the TCP/IP port it is listening on and so on.
Currently Xitami runs cgi-bin programs with the same privileges as it is
running itself. This means that when [security] setuid=1 is used, cgi-bin
programs will be started with the effective user and group set as
configured in the [security] section, but still with the user id with
which it was started saved away (typically the "root" user id).
If Xitami is started as root (or has been "setuid root" (see above)),
and using [security] setuid=1 a malicious cgi-bin program could recover
the saved root privileges and then do nasty things. It also means that
if someone finds an exploitable bug in your cgi-bin program, they might
be able to trick the program into recovering the root privileges and
running a program as root. All of this means that, as always, you need
to be especially careful about checking cgi-bin programs for security
issues.
Work is under way adding the ability for Xitami to run cgi-bin programs
with different privileges from the ones which it is running as, including
permanently discarding any saved privileges, which will further reduce this
risk. This enhanced version will also include the ability to run the cgi-bin
program with a different "root directory" from the one that Xitami is using,
for additional security.
.FAQ u What's the best Linux operating system? RedHat, Debian, FreeBSD...?
Ewen McNeill says: Firstly, FreeBSD isn't a Linux operating system; it's
a BSD-derived operating system. I haven't used it myself, but a number of
large sites do use it and seem to be quite happy with it (eg, cdrom.com).
Earlier versions of Xitami compiled and run under FreeBSD, but I'm not sure
if anyone has tried with recent versions -- it should either run or be
pretty simple to fix so it'll run.
Of the rest (RedHat, Debian, OpenLinux) I wouldn't expect much difference
between them in terms of ability to handle load, etc. (Same for Slackware,
Suse, etc as well.) They're all based around the same Linux kernels, and
that (along with the web server) are the main things that'll affect
stability, speed, etc (given the same hardware).
The main reason for choosing between the difference Linux distributions
is the packaging of software they give you. Both RedHat (which uses RPM) and
Debian (which uses .deb packages) have flexible package managers which will
let you automatically install pre-compiled software, and make sure that any
other programs that are needed to use them get installed too. RedHat has
more GUI administration tools, but I've heard that it's more fussy about you
using them too (that is, editing files by hand doesn't work so wel). Debian
mostly has command line admin tools, which is good if you're used to that
sort of thing (I like it). OpenLinux, Suse, etc, I don't know that much
about -- but Suse is apparently very popular in Europe, and LinuxJournal are
offering a copy of it with new subscriptions at present (at least they were
in July). (I've installed some Slackware systems in the past and having
tried Debian wouldn't switch back. Slackware seems to handle the basic
install okay, but it's not so good on helping you keep your system up to
date; Debian is very good at helping you keep your system up to date.
Personally my systems are all Debian systems -- but I like the command
line tools, and the (dpkg) package manager, and tend to install systems
without X.
.FAQ u Why does the documentation always use DOS-style slashes?
All recent versions of Xitami treat \ and / as identical, so the
distinction is purely for the benefit of the server administrator. (Actually
there is one exception, which is the \\ used to identify a remote file
system under Windows. This must be entered as \\, not //.) We generally aim
the documentation at Windows users, since these make-up the large majority
of our user base. We also expect that Unix users are able to make the mental
translation from \ to /. Use / on Unix and either / or \ on Windows.
Check the interfaces and routing with "netstat -r"; a "127.0.0.1"
host with the interf(ace) of "lo" ought to be present if it is going
to work. The following command ought to establish a loopback
connection: "ifconfig lo 127.0.0.1 up".
.FAQ o Xitami reports 'too many open files'
Add this environment variable definition 'SET EMXOPT=-h120' to your
config.sys. However, note the following point.
.FAQ o Xitami aborts when my site is very heavily used
EMX has a default limit of 20-40 open sockets; when you hit this,
programs start to abort or freeze. Check the $(*emx=section) on configuring
EMX.
There must be hundreds of places to get a good answer to this question.
Look at the example programs in the cgi-src directory.
.FAQ c What's a good source for CGI programs?
Try www.cgi-resources.com.
.FAQ c When I run a CGI program, I don't get any response
Run your CGI in a DOS box and check first that it actually runs without
errors. Then, check that whether it prints a first line starting with
'HTTP/'. If it does this, it must also generate a correct 'Content-Length'
header. This is vital if the server uses Keep-Alive connections, which is
the default configuration. You can disable Keep-Alive, but this makes
things work slower. The best solution is to not produce neither the
'HTTP/' first line, nor the 'Content-Length' line. These just cause
problems.
.FAQ c I can't get PHP to run with Xitami!
This is a step-by-step guide to installing and using PHP 3 with Xitami under
Windows. Under Unix, the issue is probably similar, but we've not tested
it.
We support WSX and LRWP directly, and ISAPI through an LRWP add-on. WSX
lets you build plugins that are linked into the server; LRWP lets you build
external peer processes that handle specific URLs. WSX programs are written
using the iMatix SMT library, in C. LRWP programs can be written in C, Java,
Python, Perl, or any other language that supports sockets.
.FAQ c Would you recommend CGI or WSX for a simple e-mail application?
CGI is much simpler. There is lots of information about CGI on the Net.
.FAQ c How do I tell Xitami which files are CGI programs?
With some servers you have to configure the server to recognise executable
files. For instance with Apache, one uses the AddHandler directive to say
that a filename extension should be treated as a CGI script. For example
"AddHandler cgi-script .cgi".
Xitami, in contrast, will execute anything it considers executable and
which is in a CGI binary directory. Special directives are not needed. Under
Windows, files with extension .exe or .com or .bat are executable by
default. Otherwise, files that start with #! and the name of an interpreter
are executable through the interpreter (typical example: Perl scripts).
Otherwise, files starting with the magic letters 'MZ' are also considered to
be executable. Under Unix, executable files are de-facto marked by a
protection bit, which makes things a lot simpler.
You can add support for special kinds of CGIs by using the [Filter]
configuration section: this allows you to execute a file by passing it to
some interpreter.
.FAQ c How do I debug CGI programs?
In many cases you can run the CGI program from the command-line,
providing test data to the program using the '<' redirector. It's also
possible to use a debugger. For example, under Windows I use the MSVC
compiler for C CGI programs. To set a debug breakpoint I insert a call to
DebugBreak() at some appropriate point in the program. This launches the
debugger and I can then step through the code. If you use this technique, be
sure to set the cgi:timeout high enough so that Xitami does not think your
CGI program has started to loop (it will then kill the process, and leave
you with a very confused debugger).
.FAQ c Can you give me a checklist for installing Perl for Windows?
Okay, here goes:
This is a check list that may help you.
Here's a handy Perl snippet. It will dump the values of all environment
variables. Use it after you have output the usual http/html document
headers.
This question was posed to Gurusami Sarathy, and he most graciously
offered the following reply:
"The answer should be simple: just don't use Windows 95 if you want
security. I'd recommend some OS that understands users, permissions, etc.
Try Linux (I won't recommend NT, because NT makes for a rather inefficient
webserver). That said, you may be able to disallow operators of your
choosing with the Safe module. But its usage is not for inexperienced
users."
.FAQ c Every time my SSI page uses #exec, Xitami scans the floppy drive!
This can be caused by virus-checking programs. Disable floppy scans in
the virus-checker setup and check that the A: drive is not in your path.
.FAQ c When I try to run a Perl CGI, my browser says 'Save to disk?'
You must let Xitami know that the script is executable, rather than a
text file to be sent to the browser. Make sure the script starts with
the magic '#! perl' line.
.FAQ c A require() or use() command in my Perl CGI script fails
This is a problem caused by the working directory used by the Perl
interpreter. First-off, make sure the CGI working directory is "-" (which
means the script's current working directory). If this still does not work,
you have to modify the CGI script to explicitly set the correct working
directory. Issue the following command, once, near the beginning of the
main Perl function and be any "require()" or "use()" commands:
Use an absolute path, and substitute your own path, of course.
.FAQ c I get "Can't locate ./lib/cgi-lib.pl in @INC at C:\Program
Files\Xitami\cgi-bin\test\hello.cgi line 3."
You have probably a problem with the PERLLIB setting. It must include
the directories where require'd files are found. Alternatively, you may be
able to fix this by running the script in the correct directory (set the CGI
workdir to "-"). To sort this problem out, make a CGI script that creates a
small file, then look for the file (this tells you where the script is
running). E.g.:
This message generally means "the Perl script didn't compile", which
in turn means there was a bug in your script. Two things that might help:
Xitami creates temporary files called 'pipe' something, and connects
these to the stdin and stdout streams for the CGI subprocess. If there is
something crooked in the subprocess itself, these can get lost. For instance
if it's a 16-bit program under NT. The CGI_STDIN and CGI_STDOUT environment
variables are provided for languages like BASIC which really can't access
the stdio. Then it's possible to switch-off Xitami's piping (set cgi:stdio
to 0), and in the program, read and write the stdin and stdout files
directly.
.FAQ c Why does my Perl 'flush' command not work under Xitami?
This command is a simple "$| = 1;" issued somewhere at the beginning of
the script, and is supposed to send (flush) to the browser any and all
output (print statements) as they are being issued. Because Xitami does not
work with streaming output, for now. It buffers all CGI output until the CGI
ends, then sends it to the browser. We're considering alternatives to this
model to allow streaming output.
.FAQ c My BASIC .exe CGI does not work
Some languages do not write their output to the stdout device, but
directly to the BIOS. Try 'myprog > xxx' and if the output is still being
sent to the screen, consult your documentation. At a pinch, use the
CGI_STDOUT environment variable to determine the name of the expected output
file, and write directly to that file. If you do this, makes sure you set
cgi:stdio to 0.
.FAQ c Why do I get 'HTTP/1.0 502: Service temporarily overloaded'?
Increase the cgi:timeout value. Your CGI is taking so long that Xitami
reckons it's looping with intent, and kills it (after giving it the
customary fair trial, of course). ('Looping with intent' is a Legal Term
that means almost exactly, but not quite totally, the opposite.)
.FAQ c Why is the REMOTE_USER not correctly filled-in?
Make sure your directory is password-protected. You can put the CGI
script at any level under a directory like 'private', so long as the URL
contains '/cgi-bin' somewhere. If you access a CGI without an
authentication check, the REMOTE_USER will contain arbitrary junk; typically
the last user id that was used to access a protected resource.
.FAQ c Why is the HTTP_REFERER not correctly filled-in?
Variables starting with HTTP_ come from the browser (unless you changed
something you were not supposed to). For instance, the browser will usually
provide its own name rank and serial number in 'HTTP_USER_AGENT'.
HTTP_REFERER is filled-in if you choose a URL from another page, but not if
you type it by hand.
.FAQ c When I generate images in my CGI program, LF becomes CRLF!
By default the stdout for a program is handled as a text stream. This
is easy to change. First write the HTTP header, then (in C):
You can redefine this by changing the server:cgi-url option. As
usual, modify this in defaults.cfg, not xitami.cfg.
.FAQ c I want to put some CGIs in another directory, e.g. /htdocs/myscripts
Define a $(*config_cgi_alias=CGI alias).
.FAQ c How do I use a CGI program as a default page?
Use a web site counter like
this one for
Windows 95.
.FAQ c How do I make a CGI file executable for DOS?
There is no equivalent to the UNIX 'chmod' command under DOS/Windows.
After considering various techniques (e.g. looking at the extension), we
decided that the UNIX execve technique was the simplest; i.e. the script
specifies what interpreter to use. Actually if you want to see the code that
decides this, look at the SFL code in sflfile.c -- file_is_executable ().
The UNIX technique works for Perl, Awk and presumably shell scripts, and
with a little tweaking, for Rexx too. Finally, we take a peek at the file
contents if necessary. Under MS-DOS & Windows, a real executable starts with
'MZ'. That's sufficient for Xitami to try to run the thing. Conclusion:
executable files can take any extension and work with pretty much any
processor/interpreter.
.FAQ c I tried compiling testcgi.c but it wants sfl.h?
The example CGI programs in C use the iMatix SFL library. This is
included in the Xitami source kit (since Xitami also uses it). You can
download it from our site.
.FAQ c How do I use an URL like '/cgi/script'?
You can set this option in the [Server] section of custom.cfg, in
the cgi-url option. Try this:
If you use /cgi-bin in the URL below the top level, you must enable the
cgi:wildcard option.
.FAQ c Can I redirect users to different pages using the .aut file?
No, not without CGI programming. But it's quite simple to do in Perl or
C: you test the user name (forget the password - it's already been
validated) and return a header that redirects the browser to the actual
page: "Location: /somedir/somefile.htm". Use the environment variable
REMOTE_USER, which contains the user id.
.FAQ c Can I trap the user id to subset data?
In a CGI you can use the user name to subset data: you could issue a
redirection to the appropriate file, e.g: Location: filename.htm depending
on the value of the REMOTE_USER environment variable, or use this variable
to determine what data to read from a database.
.FAQ c I want to limit CGIs, but not HTML pages, to certain IP addresses
Add this to the authentication file:
Set the server:cgi-url option to "/", and the server:cgi-bin option to
the same as the server:webpages option. Make sure cgi:mixed-url is 1.
.FAQ c How do I write a shopping-card CGI program?
You should ask this kind of question on CGI or HTTP newsgroups, and
research the Internet for answers. The simplest way to do this is to use
cookies, or to use URL arguments (?xxxx) to know the 'state' for each user.
If you want to maintain long-term state for users, it's best to force them
to logon (and thus identify themselves) each time they come back to the
site. See the question on $(*user_authentication=CGI user authentication).
.FAQ c How do I access ODBC databases under Windows?
From Perl, you can use Win32::ODBC, ActivePerl for Win95, and the DCOM
driver. One report: "It worked very well - I was able to duplicate in a
matter of hours what my buddy took almost a week to do with MS software, and
the result was faster and looks better!"
.FAQ c My CGI program can't connect to ODBC under Windows NT; it works -
from the command line
Under NT, each login ID has its own set of ODBC definitions. The reason
your program works from the command line is that it runs under your current
login ID, which apparently has a proper ODBC definition to utilize. The
Xitami web server runs as an NT service and does not use your login ID by
default. Xitami and all CGI programs launched from within it assume the
login ID assigned to Xitami at start up. This can either be a system ID,
which is typical, or a specified user ID, which requires extra configuration
by an NT administrator.
The solution is to have an NT login created specifically for Xitami. It
need only have the standard User privileges (assuming your NT environment
uses the default definition of "User"). After this login is established, one
must use it to login and then define a proper ODBC connection. Next, Xitami
must be made to start as NT service using this new login instead of a system
ID. Since this new login ID does not (or at least should not) have
administrative rights, one will have to logout and log back in as an
administrator to change this setting, which is made from the Services
component of the Control Panel. Now when CGI programs run, they will do so
under the new login ID, and will consequently have access to the new ODBC
definition.
.FAQ c When I run a heavy ODBC CGI program, I get "Server Overloaded"
Your problem is that the CGI program runs 'too long' and is then
killed by Xitami. Increase the CGI timeout (which is specified in
seconds).
.FAQ c My images don't load when my CGI uses extra PATH_INFO
When you run a CGI that contains extra path information (the PATH_INFO
environment variable), images on pages generated by the CGI will fail to
load if they're referred-to by relative URLs. For example, if the CGI URL
is http://my_domain/cgi-bin/my_prog.cgi/extra-blah, and you refer to an
image "pic.gif", the browser will ask for a URL called:
http://my_domain/cgi-bin/my_prog.cgi/extra-blah/pic.gif, which presumably
won't work. You can check this by enabling server debugging and looking at
debug.log. There are two solutions:
Find the Internet document RFC1867. This is the kind of FORM code you
need:
Form-based file uploads do not work in IE3.x and earlier, and we have
reports that it fails with some IE4 configurations. Netscape 3.x and later
work fine. Opera 3.x does not handle this. Therefore, we recommend that
you use this carefully and probably best within an intranet setting where
you can be sure of the type and version of browser used.
.FAQ c My SSI page says '#exec command not permitted for security reasons'
To enable the #exec command, set the ssi:exec option.
.FAQ c Can I use Java servlets with Xitami?
Takyiu Liu says: I have used servlets with Xitami with an unconventional
way. I use servletrunner (or Jrun if you prefer a 3rd party servlet engine)
and point it to the servlet classes I have written (I have the servlet
connected to a SQL Anywhere DB on request). I then use Xitami to serve the
web pages, with form actions pointing at something like:
Jrun is meant to be a servlet engine but in 2.2 they added primitive http
support. By default, it comes up on port 8000 and a typical location to put
the web pages is:
You can use the sneaky parallel-server approach suggested by Takyiu Liu
for running servlets: run Xitami beside the other web server on another port,
just for the benefit of LRWP.
.FAQ c What plans do you have for server-side JavaScript?
Xitami does not support server-size JavaScript and we do not have such
plans.
.FAQ c I've discovered a limit of 252 LRWP servers under Unix
This is a problem with some Unix systems, caused by a limit on the number
of open file handles. You can link Xitami with AT&T's "SFIO" library
(available from http://www.research.att.com/sw/tools/sfio/ ). No source
modification is required: just copy libstdio.a and libsfio.a from the SFIO
distribution to ./src/smt/ and modify one line in "./src/smt/c" script from:
When a browser requests a page which Xitami considers 'protected', i.e.
which is defined in defaults.aut, it fills-in a request header like like
this:
The strange thing at the end is the sequence "username:password" encoded
using base-64, as defined in the Basic Authentication Scheme in RFC2068.
Xitami provides the encoded string in the HTTP_AUTHORIZATION environment
variable. You can decode this using a fairly simple function - see the SFL
sflmime module for an example in C.
It's also possible to tell the browser to ask for a password, if none is
supplied, by generating a WWW-authenticate header. For example:
For the main configuration you have xitami.cfg+defaults.cfg. For each
virtual host you have some XXXXX.cfg. For unresolved virtual hosts you have
basehost.cfg. Use the WBA virtual host wizard to define new virtual hosts.
.FAQ v How do I set-up a virtual host on another port?
You can do this quite simply by starting two copies of Xitami. We do this
quite often; the advantage is that you can get the effect of multiple hosts
(different document roots) without playing with the DNS system. Otherwise,
you have to define DNS entries that map several different names
'www1.here.com', 'www2.here.com' to the same IP address, then base the
virtual hosting on the different names. Either way is okay; Xitami is so
small that running two or even a dozen copies will not stress a system.
.FAQ v How do I provide space for individual users on my system?
Let's say you installed Xitami in c:\servers\xitami. Then, the main
webpage directory will be c:\servers\xitami\webpages. An URL like
'http://dynamic210.adelphia.net/Joe' is taken to mean something like:
'http://dynamic210.adelphia.net/Joe/index.htm', which would be a file:
'c:\servers\xitami\webpages\joe\index.htm'. You can also use
default.htm, and you can change the main webpages directory to be
somewhere else if you want. Under Windows 95 and NT you can make each
subdirectory shareable separately, so that users can update their pages
but not mess with other files. You can also use aliases, especially if
users' pages are on different disks.
.FAQ v And how about their CGI scripts?
Any URL containing /cgi-bin/ is treated as a CGI directory. So, Joe
can put his web pages in "c:\servers\xitami\webpages\joe\" and his CGI
programs in "c:\servers\xitami\webpages\joe\cgi-bin\".
.FAQ v Can I run two versions of Xitami, e.g. on ports 80 and 1010?
It should work okay, providing you stop the two Xitami's from stepping on
each others toes (eg, different home directories). If you want to run on
port 1010 you'll have to give Xitami a carefully calculated base value (base
(1010-80)=930; 1080 would be easier (base 1000).
.FAQ v My virtual host setup does not work - what can I try?
This is a typical problem caused by the way FTP works. If there is a
firewall (some some kinds of router are the same) which does not allow
connections from the server to the client, file transfers (including
directory listings) will fail. You should tell your users to use 'passive'
connections.
.FAQ f How do I use my D: drive for additional FTP space?
You can move the entire FTP root anywhere you like - this is one way. You
can also define any number of FTP aliases, which point to different file
systems, CD-ROMs, etc. You can also put different FTP users' directories on
different disks. For instance if I log in to 'anonymous', you could set my
home directory to d:\anon\.
.FAQ f When exactly does Xitami read the FTP user file?
Xitami reads this when it starts up, when you restart it, or after the
refresh timeout (30 seconds by default).
.FAQ f If I give a user only 'P' access to a directory they can't list it
Normally you'd use 'P' by itself for a directory meant purely for
uploads. I.e. a userid 'uploads' with a dedicated write-only directory.
If you use 'P' by itself on a subdirectory, the user will not be able to
'cd' into it.
.FAQ f I'm having problems getting my FTP permissions right
The FTP permissions definitions are quite complex and it's easy to get
these wrong. The most common mistake is when you define directory-level
protections. For instance, if the ftproot is in 'ftproot', and a user
'guest' connects to 'guest' (a subdirectory of ftproot), then how do you
specify the protection for a subdirectory 'guest/pub'? The correct form is:
To debug this kind of problem, enable server debugging, then check
debug.log. It'll indicate the actual permissions that were used to access
the directory. Make sure you read the comments in ftpdirs.aut to see how
FTP authentication works.
.FAQ f How do I create an alias under the /pub directory?
This is not possible at present.
.FAQ f Helloftp.txt does not show up under web-based FTP access
This depends entirely on your browser: some show it, some don't.
.FAQ f FTP aliases don't show-up when I do a browser directory listing
Aliases don't show-up in HTTP directory listings. They do show up in
FTP listings. This is just the way things work.
.FAQ f How do I set-up FTP virtual hosts?
Do this the same way as for normal HTTP virtual hosts. Note that the
normal FTP protocol does not handle DNS-based virtual hosts. Xitami, and
some FTP clients, allow this by using the convention 'user@hostname' during
the connection process.
.FAQ f Can I remotely browse my hard drives using Xitami?
You can define an FTP alias to C:\, for instance, and manage this using a
remote FTP client. Make sure you use a secure user id and password.
There are many freeware and commercial logfile analysers; the Xitami
access logfiles are NCSA/HTTPd compatible and thus compatible with most
logfile analysers. The Xitami.log file is used for server messages and
thus not suitable for analysis.
.FAQ l Does the FTP server log logins, uploads, and downloads?
The FTP server logs uploads and downloads in the Xitami access log file,
by default. To separate the FTP access log into a separate file, change
the Ftplog:filename configuration option. This also applies to the error
log, specified by ftperrlog:filename.
.FAQ l Why does access.log contain only numeric addresses?
You should configure and enable the reverse-DNS translation function.
.FAQ l Can I use Microsoft's WINS protocol for analysing my log files?
Yes. This is extracted from Microsoft's documentation: "In Windows NT
4.0, Microsoft's implementation of DNS is tightly integrated with WINS. This
allows non-WINS clients to resolve NetBIOS names by querying a DNS server.
Administrators can now remove any static entries for Microsoft-based clients
in legacy DNS server zone files in favor of the dynamic WINS/DNS
integration. For example, if a non-Microsoft-based client wants to get to a
Web page on an HTTP server that is DHCP/WINS enabled, the client can query
the DNS server, the DNS server can query WINS and the name can be resolved
and returned to the client. Previous to the WINS integration, there was no
way to reliably resolve the name because of the dynamic IP addressing.
Please see the 'DNS and Microsoft Windows NT 4.0' white paper for details on
the WINS/DNS integration." The upshot of this is that xixlat will work with
WINS if you have a WinNT 4.0 DNS server.
.FAQ l My log file has this strange URL: webpages/http://hostname/file.htm
This is caused by the browser (usually MSIE4) sending a HTTP1/1 proxy
request. Xitami can not (yet) handle these. This usually indicates that
someone has defined your web server as a proxy server.
.FAQ l I can't access the log files while Xitami is writing to them!
This is normal behaviour under Windows. Under Unix and OS/2 you may
have more luck.
.FAQ l My log files do not get updated until Xitami is restarted
This happens (on several operating systems) because the OS may not show
changes to a file until the file is closed by the process writing to it.
When you do a restart, Xitami closes its log files, and then you see all the
entries. At a guess the log files are being block buffered, which means that
they'll only be written out to the file once a block is full (probably
somewhere between 2K and 8K at a guess). This is a function of the way that
the runtime library handles file I/O.
.FAQ l My computer crashed and now my log files are full of junk
When the computer crashes, for whatever reason, it can leave open files
in an incomplete state. One symptom is that allocated blocks can contain
garbage from previous files, allocated to the new file, but not yet written
with data. This is probably what happened to your log file. In other words,
the junk is probably not what caused the crash, just random data that
happened to be on the hard disk when Xitami was writing to its log file.
Just say 'iMatix' backwards -- it's simple! Okay, to be more precise...
There are two basic ways to pronounce this name; you can aspirate the 'X' as
'Sh', or you can keep it hard, as 'Ks'. In either case the accent is on the
second syllable.
.FAQ m What are the main problems with Xitami today?
People also often ask for FrontPage support. Besides the fact
that FrontPage uses an undocumented server interface, we think that if you
want to be tied to a single platform (Windows in this case) you can use the
platform-specific server (IIS in this case). Xitami offers a long-term
approach, robust enough to survive several OS changes.
.FAQH m Can you recommend a search engine for Xitami?
We've tried a few; there is a free engine available from www.excite.com, and we've also tested the free
Swish engine, which works well with Xitami. You can get Wim Niemans' port of
this for Windows 95/98/NT from the $(*swish=iMatix website).
.FAQ m Why is the Xitami mailing list not a newsgroup?
We are well aware of the advantages and disadvantages of newsgroups
vs. mailing lists. Each has their strong points, but in general a mailing
list is accessible to more people than a newsgroup. We're looking for ways
to provide transparent merging of the two techniques, so that people can
use the mailing list either as a newsgroup or a list. Until that date,
we will stick with a mailing list.
.FAQ m Why do I get errors on 'robots.txt'? What is this?
The various search engines (like AltaVista) use a 'web spider' or 'robot'
to scan and index websites. This often includes large amounts of junk that
make the resulting searches pretty useless. So, a standard mechanism has
evolved to make this work better. The 'Robot Exclusion Standard' specifies
that a file called 'robots.txt' in the home directory will indicate which
pages or directories should be ignored. This is not meant as any kind of
security device, just a 'hint'. So, most robots will ask for this file. If
the errors in the log files bother you, create an empty file in the webpages
directory called 'robot.txt'. To ask all robots to skip your site, use
this:
No, not in this version.
.FAQ m Why is the password file not encrypted?
In general if access to your server is secure, then the lack of
encryption is not a problem. If someone can read the Xitami directory on
your system, they can see the passwords. Note that even if you use a hashed
password file, it is often trivial to discover passwords using a
dictionary-based attack. It's therefore much better to concentrate on hiding
the password file than on encrypting it. At some future date, Xitami will
support encrypted (hashed) passwords.
.FAQ m Do I need a special license to use/sell/modify Xitami at work?
No, none. Read the $(*license=Xitami_license).
.FAQ m I want to write a great Xitami addon...
Excellent news! Xitami is an Open Source project, and has benefitted
from many contributions, including people who ported the SFL library, wrote
plugs like the LRWP agent, wrote documentation, tested it, and so on. You
will want to learn how to use our great tools - Libero, SFL, SMT.
.FAQ m How do I rebuild the SFL under Windows using MSVC?
The simplest check-list is:
If you try to mix Xitami with MFC, you'll get a server that stops running
after 60 seconds, or whatever you set the server:refresh interval to. This
is because MFC traps the timer signal Xitami uses, and handles it as an
abort. There may be workarounds for this, depending on how well you know
MFC.
.FAQ m How do I rebuild Xitami under Windows using lcc-win32?
If you want to compile under Windows, you should download the Windows
source kit, not the Unix one - this will give you files with the correct
line endings (CRLF not LF). Then, you should set the environment variable
CCNAME to lcc and CCDIR to the lcc-win32 directory. Try the c.bat file on
one source, e.g. sflbits to make sure it works correctly, then run build.bat
in src/sfl. Copy sfl.h and libsfl.lib to src/smt, and run build.bat there
too. Lastly, when Xitami is built, be prepared to throw it away, since at
the time of writing, lcc-win32 had a bug which causes Xitami to halt when it
gets a timer signal -- see the following question.
.FAQ m I compiled Xitami with lcc-win32 but it always aborts
Lcc is a wonderful little compiler but its runtime has a problem with
certain interrupts. Basically, when Xitami receives a timer signal, it
aborts. This hits after the refresh timeout, and when running CGIs. We have
notified the author of lcc, and provided a small test program that shows
this behaviour. It's quite clearly a bug in lcc. Apart from this problem,
we've found lcc to be fast, reliable, and in fact it's supported fully by
the SFL. I can recommend it for CGI programming (oh, one more caveat - no
support for ODBC as far as I could see).
.FAQ m Why are there bugs in Xitami?
Any complex software is filled with bugs. Xitami is pretty good in this
respect, we reckon. Our policy is to fix those we can identify and localise,
depending on the severity of the problem. A bug that causes the server to
crash will make us run around a lot faster than a bug which causes some
obscure feature to work otherwise than documented. Large amounts of money
will also tend to focus our attention.
.FAQ m Why is Xitami free, and will it remain this way?
Xitami is a product that we developed to demonstrate the quality of our
technology and to introduce people to iMatix Corporation. This web server
will remain free software, and as the kernel for our commercial web server
products, will continue to be ported, improved, and maintained.
.FAQ m Where can I get older versions of Xitami?
We keep one back version but not older ones. You may be able to find
a specific version by searching through an FTP search engine like the
one at http://ftpsearch.ntnu.no.
.FAQ m Do you have any plans to incorporate SSL into Xitami?
Xitami/Pro supports this. E-mail us for details and prices.
.FAQ m What is the future for Xitami?
Xitami will continue to be improved and extended, while keeping it a
server that you can install and set-up within minutes. For professional
users, Xitami/Pro offers more sophisticated functions but these also take
more time to learn and configure. Xitami will remain free software.
.FAQ m Is Xitami year 2000 compatible?
Yes.
$(*faqlink=Go back to FAQ index)
.-----------------------------------------------------------------
.page Getting Support
.build anchor getting_support
Xitami is a free product, and well-documented. Before you email us with
questions, make sure you read the documentation and especially the
$(*faqlink=FAQ). Bug reports are always welcome, if you can tell us what to
do to make the problem happen. E-mails like 'Xitami crashed' are not very
useful. When you report a problem, tell us:
Xitami includes a debugging option (the server:debug option) which
generates various trace files. Use this feature to get information about a
problem before you mail us. Often the trace files (debug.log, header.log,
and request.log) will contain very useful information.
.build anchor group
For help about using, configuring, or extending Xitami, use the Xitami
discussion group. This is a mailing list kindly hosted by Scott Drake. The
Xitami group generates 10-30 messages a day, and has an
$(*archlist=on-line_archive) which you can search by going to
http://xitami.isonline.com/ and clicking on Search.
To subscribe, send a $(*mailist=message) with the following command in
the body of the message: subscribe xitami.
Registered Xitami users get automatic news about updates, bugs, special
offers, and other items of interest. Registration is free. To register, send
a $(*register=message) with your comments in the body of the text. We will
sometimes use your comments (with permission) on our web site. In any case,
if you mail us with any question regarding Xitami, you are automatically
registered.
Technical support licenses for Xitami and other iMatix products are
available from iMatix Corporation at reasonable prices. Contact
$(*sales=sales@imatix.com) for information. Commercial clients should
use the priority support facilities noted in their license.
For regular information on iMatix - our products, our future, and our
opinions - you can subscribe to Liberetto, the monthly iMatix newsletter.
Send a mail to $(*liberetto=liberetto@imatix.com) with 'subscribe' in the
message subject or message body.
.-----------------------------------------------------------------
.page Credits
Xitami was never meant to be the world success it is today. Heck, we
released version 1.0 just to demonstrate how internet servers *should* be
written. Unfortunately for our private lives, a screaming horde of people
dragged poor little Xitami out of the door, into the bright light of day,
and insisted that we beat it into the shape of a real web server.
Let's make it clear: the main motivating forces behind Xitami (at least
as far as our team was concerned) were laziness and hubris. Larry Wall got
this exactly right. Frankly, we were too lazy to install Apache, and
arrogant enough to think we could do better than Microsoft on their own
systems.
From the first release of Xitami, the majority of changes, improvements,
and fixes were provoked by its users. Xitami consists of a small group of
programmers surrounded by hundreds of vocal, and supportive users. It's a
great mix.
Our dream was to show the world that large, slow, and complex software
is a deception. Xitami does its job with a minimalistic grace, smoothly
directing the traffic streaming through its arms. No waste, no haste.
Where other servers are traffic lights, Xitami is a round-about.
We built Xitami from the ground-up using an approach that should delight
any student of engineering, software or otherwise. First step - ask the
question: 'what are the real problems a web server has to solve?'. Step two
- answer these problems. The real problems are, as far as we could see,
ease of use, performance, stability, and portability. Basically, we wanted
something that would install in a minute, always run fast, never crash, and
run on every machine on our rather mixed-up network. This is what we made,
more or less. In some situations, Xitami does crash, but it's quite rare.
A perfectionist design like this can't succeed without some kind of
discipline and formality. This is one of the basic debates in programming.
Is programming a science or an art? Do you use a free-wheeling, organic
approach, or an organised, formalised approach? This is like the debate
about heredity against environment. You need both to succeed. Xitami was
built using a tightly-defined method, but allowing any and all creativity
on top of that.
To write a Xitami agent, like the LRWP agent that Robin Dunn wrote in
1997, you need to learn: the C programming language, the Libero tool, the
SFL library, the SMT kernel, and something about the HTTP protocol. This
is a fair challenge. However, when you've absorbed this knowledge, the
program you write runs on Windows 95, Windows NT, OS/2, Linux, and just
about every other modern machine out there. For a programmer, being able
to write a truly portable program is akin to the promise of immortality.
Certainly it drives thousands to learn languages like Java, putting-up with
all the problems that young languages bring with them.
Xitami will run on every capable machine in existence for the next
fifty years without significant difficulty at all.
A day will come when the use of C will look dated. For a long time we
built tools using COBOL 74, a language that does not know about pointers,
and dynamic allocation, or even lowercase letters. The tools we built were
excellent, widely-used, and long-lasting. Linked-lists, recursive
algorithms, virtual memory management, we did all of this in a language
designed for writing accounting systems. This taught us that the choice of
language is not as important as people often believe. But it can make your
life easier or harder, and you can't produce better code than the compiler
generates. Some COBOL compilers are attrociously bad. On the AS/400, the
generated code for a statement like 'ADD 1 TO A' consists of about ten
instructions: take A, convert to floating point, take 1, convert to
floating point, add to A, round the result to N digits, convert from
floating point, store back in A. The machine supports an instruction
'increment' which would do the job in one step.
Most operating systems are written in C, and on modern systems, the C
compiler is the most stable, optimised, and standardised available. This
is borne-out by our experience: we have found very few compiler errors
despite running Xitami on a couple of dozen different C compilers.
If you look at the sources for Xitami, you'll see various references to
something called 'Libero'. This simple but magical tool is our most
elementary weapon in the battle to render complex problems simple. Libero
is not dedicated to any single type of work - it's been used in many
different domains. When it comes to writing an Internet server, however,
it's hard to imagine a better start.
There is a handy trick that you can use to understand and describe
certain kinds of system. Let's call this 'an event-driven approach'.
Many problems (including many types of program) suddenly become much easier
to understand and describe when you look at them in this way. It's just a
trick, because of course the real problem is unchanged. But a good
programmer, being lazy, will use any trick that makes life easier. In a
classic program, the programmer says 'okay, we do this, then this, then
that'. In an event-driven program, one says 'when this happens, do that.
When that happens, do thus'. It's strange at first, but quickly makes
sense. Libero takes this approach and turns it into actual code. Suddenly
we have a way to describe complex systems and produce the code that
makes them work. In the same breath.
By exceedingly good chance, servers, including web servers, fall smack
bang into this category of problem. When you look at the Libero
description of the Xitami web service, you see on a couple of pages the
complete logic of a web server. This is stunningly simple compared to
trying to read the Apache source code.
The main technical challenge behind any web server, however it's
written, is performance. Writing a program that will answer one HTTP
request is almost trivial. Writing a program that can answer several
hundred in a few seconds is something else. Most existing web servers have
tried to evolve from the first case to the second. Under Unix, they start
dozens or hundreds of processes. Under Windows, they start dozens or
hundreds of threads. Either way, each process or thread handles one single
user request. The Windows threads approach is fast, but totally specific to
one operating system. The Unix process approach is fast once it's started.
But it takes ages to start and stop a server like this, and the web server
inevitably takes over the entire system. There are 'portable' thread
libraries, but frankly: writing real multi-threading code is like walking
on eggshells. We're too lazy to learn to do this.
The basic problem with a web server is that you have to handle many
short-lived connections. When the cost of creating and eventually killing a
process or thread is significant compared to the cost of handling the
request, the server is not efficient.
Building on Libero's event-driven approach, we built a solution to this
problem, with the catchy name 'SMT'. SMT dispenses with all the stress of
creating processes and threads by handling everything in one single
process. We call this 'multi-threading', but that's marketing. In fact SMT
enforces an event-driven model onto the programs, and simulates a kind of
event-driven thread. It's like writing Quicksort algorithms in COBOL. You
don't need recursion built-in to the language to implement a recursive
algorithm. Bizarrely enough, simulated recursion is often faster than the
real thing. The same thing goes for SMT's event-driven threads. An SMT
thread needs none of the adminstrative baggage of a normal multi-threaded
program - locks, semaphores, and so on. It just handles the events it gets
in its queue, and sends out events to other threads. A thread always runs
exclusively, with SMT switching to another thread only between the major
steps of the Libero 'dialog'.
SMT seems to be a perfect approach for Internet servers of all kinds. If
there are flaws in it, we've not seen them yet.
It's pretty pointless building the perfect web server if it only runs on
one operating system. This is like writing haiku in sand on the beach. The
point of software, like art, is to reach a public. Unfortunately, the
public for software is a moving target. Operating systems last a few years,
and non-portable software dies with them when they go. There are different
tactics to portability. Microsoft try 'portability by exclusion'. If
everyone runs Windows, portability is easier (ignoring that new version of
Windows coming up fast behind you). Java and Posix define 'portability by
decree'. Presumably in the hope that people like Microsoft will tamely go
along with the idea. Many projects do 'portability by patching', which
means patching the software each time it is ported, leading to masses of
'#ifdefs' throughout the programs.
At iMatix, we chose 'portability by paranoia'. A library, the SFL,
provides all the functions our programs need that are not 100% portable. A
program that uses SFL correctly is fully portable. The approach works
because we're not dependent on the goodwill of other people. If some
operating system decides to implement sockets in some bizarre way, we just
add support in SFL. Xitami's portability is the flying carpet that takes it
into the future.
Of course, we cheated a couple of times. To run Xitami under Windows,
we built a native Windows console program that lets a user manage the
server. It's not portable, but it does turn Xitami into a neat little
Windows program. Apart from that, the entire Xitami source code is
fully portable.
The Xitami team itself consists of Pascal Antonnaux, Ewen McNeill,
Jonathan Schultz, with Pieter Hintjens doing the co-ordination and
production. The Xitami team has been working together since the first
release of Xitami, in January 1997.
Thanks to the folk at iMatix for providing technical support, coffee,
and most of the finance for this project. iMatix does not make a profit on
Xitami, but it's become a kind of company mascot.
Providing the first buffer between ourselves and our users is the Xitami
discussion list. This is run by Scott Drake, who took over in October 1997
when the original list, run by Martyn Drake (no relation), lost its home.
We owe a great deal to Scott, and his company, isonline.com. Thanks also
to Ewen McNeill for his clear and concise answers to many hundreds of
questions on the list, and the many other people who have contributed
information to the list.
We were lucky to find ourselves surrounded by a number of people, Xitami
users with apparently infinite patience and tolerance for disasters, who
adopted Xitami and regularly send us their comments and ideas. Some of
these have built ISP businesses using Xitami, others use Xitami in their
companies. Thanks to Ben Tremblay, Bruce Walter, Fabian Bess, Glenn
Williams, Ignacio Bustamente, James Beasley, Jayson Minard, Jeff Wolkove,
Jimi Joergensen, Josh Lydolph, Istvan Kovacs, Leif Svalgaard, Patrick
Bedert, Paul Richards, Peter D'Hoye, Rob Judd, Thomas Grobicki, Wim
Niemans, Dan, who's full name we never knew, and the many others who took
time to send us their ideas, comments, and bug reports.
Thanks to Diego Antona, Wim Niemans, Robert White, and Taweewit Pensawat
for providing Xitami mirror sites.
Thanks to DeXin and Chin Fang for providing an excellent home for Xitami
on imatix.com, and a big "thanks" to Jayson Minard of OpenAvenue.com for
giving a new home at OpenAvenue.com for xitami.com, finally allowing us to
run xitami.com on a Xitami server.
Thanks to Mohammed Aziz and Rick Caccia of NetDynamics for including
Xitami in their NetDynamics package in early 1997, proving that Xitami was
up to scratch. As far as we know, Sun still includes Xitami in NetDynamics.
Thanks to Dr Dobb's Journal (and especially Eugene Eric Kim) for
publishing our initial articles on Libero and Xitami.
Thanks to Robin Dunn for writing the LRWP agent, a great piece of work,
and a great asset to Xitami, and to Scott Beasley for providing the mailto
program. Thanks to Thomas Schroeter for supporting and managing xitami.de,
the German Xitami site. Since day one, about 8% of all Xitami users are
from Germany.
Thanks to the several thousand of you who have emailed and registered,
telling us what you thought about Xitami, being liberal with your criticism
and compliments alike.
Finally, thanks to the literally hundreds of thousands of people who use
Xitami every day without sending us emails. We appreciate it more than you
know!
.-----------------------------------------------------------------
.page Release History
.build anchor history
These are the release notes for the latest major version of
Xitami, since the last release of the previous major release.
Summary release notes for every release since 1.0a come afterwards.
The built-in log file formats are:
LML and XLML are intended to simplify log-file post-processing via an
XML-capable tool like GSLgen. You can also define custom log file formats
using any combination of text, delimiters, and logging data fields.
The logging agent performs reverse-DNS translations on the fly, note
that you must define the RDNS configuration before this will work.
You can cycle log files hourly, daily, weekly, or monthly. You can cycle
the log files when the server starts-up, when they exceed some size in
kilobytes, or when they exceed some size in lines.
You can specify the exact day and/or time a log file must be cycled.
When cycling a log file, you can rename the old file, delete the old
file, move the old file to some directory, append the old data to some
file, or run an arbitrary command against the old log file.
You can decide how to name old log files using a mask built from the
current day, time, and other information or text.
Each virtual host can have independent settings for its HTTP and FTP log
files.
Using TCP/IP With OS/2
ifconfig lo 127.0.0.1 up
USE_HOSTS_FIRST=1
.build anchor emx
Configuring The EMX System
7 emx options
=============
You can customize emx by setting the EMXOPT environment variable. This
environment variable contains a list of options, similar to command line
options. The options must be separated by at least one blank. Example:
set emxopt=-c -h40
7.1 emx options (OS/2)
----------------------
-c Disable core dumps caused by signals and exceptions
-h# Set OS/2 file handle limit to #. The number # must be between
10 and 65536
[...]
set EMXOPT=-h120
Source Installation For OS/2
.endpipe
.build anchor unix
.pipe unix-readme.htm=Xitami installation for UNIX
Source Installation For UNIX
gunzip suni%(vxi).tgz
tar -xvf suni%(vxi).tar
chmod +x xibuild
\./xibuild
.build anchor vms
Source Installation For OpenVMS
$ xitami :== $disk_whatever:[root.install.dir]xitami.exe
$ testcgi :== $DKA300:[.cgi-bin]testcgi.exe
$ xitami -b 5000
.-----------------------------------------------------------------
.page Administration
$(TITLE)
Xitami Under Windows
Xitami Under UNIX
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.
Testing Xitami
Using Xitami
User Authentication
# 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
[/pub/mypages/file]
[pub/mypages/file]
[/pub/mypages]
[pub/mypages]
[/pub]
[pub]
[/]
Xitami Log Files
The Xitami Server Log File
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 $(*config_serverlog=[Serverlog])
configuration entry.
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 ""
Extended Logging
.item format
Xitami has these built-in formats:
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)
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)" />
The time-stamping function expands symbols in the argument as follows:
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.
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.
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 %
Building Multilanguage Web Sites
$(TITLE)
[Server]
debug=1
Web-Based Administration (WBA) Interface
Configuration File Syntax
name=value
form-prefix=""
Using Webmasks
webmask=*
which allows all IP addresses. The '*' matches part or all of an IP
address, in this case, all addresses.
webmask=local
webmask=192.*,!221.201.*,1.233.12.*
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.
webmask=*,!192.*
Here, all clients are allowed by the first term, '*', and Xitami will not
even look at the second term.
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.
Using the Error Simulation Function
$(TITLE)
http://localhost/cgi-bin/myprog
http://localhost/cgi-bin/myprog.pl
http://localhost/products/install/cgi-bin/myprog
http://hostname/cgi-bin/someprog?var1=value1&var2=value2...
http://hostname/cgi-bin/someprog?arg1+arg2+arg3...
CGI Programs Under 16-bit Windows
CGI Programs Under 32-bit Windows
#! c:\tools\perl
You can use '\' or '/' in the path name. The Perl script should be
fully specified; Xitami does not assume any kind of extension. Perl
programs sometimes end in '.pl'; we recommend you use no extension.
To provide compatibility with Perl scripts coming from UNIX, Xitami
will handle a path like '/usr/bin/perl' by removing '/usr/bin/' and
looking for PERL.EXE on the PATH, if /usr/bin/perl does not actually
exist as a file.
You can increase the speed of Perl CGI programs under Windows 95
by adding this definition to your system.ini file (this may also work
under NT; we've not tested it):
[NonWindowsApp]
CommandEnvSize=4096
This reserves memory for DOS applications, and you should make this
setting higher if you have plenty of RAM.
CGI Programs Under UNIX
CGI Programs Under OS/2
d:\os2\cmd.exe /c scriptname
EXTPROC full-path-to-interpreter flags
in the first line of the script file (Xitami will accept flags at
the end of the EXTPROC line by some other programs may not; test
carefully); or
/*! full-path-to-interpreter flags */
in the first line of the script file. You can use the standard OS/2
command interpreter (CMD.EXE) as the interpreter for REXX, but if you
do then you must specify "/c" as one of the flags to ensure
the command interpreter exits as soon as the CGI script finishes
running.
#! c:\tools\perl.exe
or
#! c:\tools\perl
You can use '\' or '/' in the path name. The programs are best stored in a
file without an extension, or in a file with a ".cmd" extension; if you use
another extension you will need to specify the whole filename (including the
extension) in the URL. Perl must be installed on your system. Perl 5.004 is
recommended. If your perl script uses special features make sure you are
running the correct perl executable (check the Perl 5.004 for OS/2
documentation) for the features you require.
CGI Directories
'cgi-bin' option:
URL:
Final pathname:
Default
/cgi-bin/myprog
./cgi-bin/myprog
Default
/cgi-bin/products/myprog
./cgi-bin/products/myprog
Default
/products/cgi-bin/myprog
./webpages/products/cgi-bin/myprog
/web/cgibin
/cgi-bin/myprog
/web/cgibin/myprog
/web/cgibin
/cgi-bin/products/myprog
/web/cgibin/products/myprog
/web/cgibin
/products/cgi-bin/myprog
./webpages/products/cgi-bin/myprog
.
/cgi-bin/myprog
./myprog
.
/cgi-bin/products/myprog
./products/myprog
.
/products/cgi-bin/myprog
./webpages/products/cgi-bin/myprog
CGI Error Messages
Insufficient resources to run this CGI program
CGI arguments are too long - request was refused
Cannot create stdin stream for CGI
Cannot create CGI process - program not found
CGI process ended with an error status
CGI process was interrupted before ending
Internal server error while running CGI
Undetermined error
$(TITLE)
.-----------------------------------------------------------------
.page Using Filters
.build anchor filters
Element syntax: Effect:
#config errmsg="text"
Specify the SSI error message.
#config sizefmt="format"
Specify whether file sizes are shown in full, or abbreviated. Use
the format 'abbrev' to show abbreviated sizes.
#config timefmt="format"
Specify the format used for file times. By default this is:
"%A, %d-%b-%y %H:%M:%S %Z".
#echo var="variable"
Output the value of the specified variable. Xitami recognises these
variables: DOCUMENT_NAME, DOCUMENT_URI, DATE_GMT, DATE_LOCAL,
LAST_MODIFIED, and any environment variable (including the standard CGI
environment variables).
#exec cgi="pathname"
Outputs the result of the CGI program, which must be in the CGI
binary directory (it cannot be on a CGI alias directory). Note that the
CGI program runs in the main Xitami directory.
#exec cmd="command"
Executes a native command and includes the output of this command.
Note that the command runs in the main Xitami directory. This SSI
command - which is a potential security risk for your system - is only
accepted if the ssi:exec configuration option is enabled.
#include virtual="filename"
Includes the contents of the specified URI, which is assumed to be
within the webpages root.
#include file="filename"
Includes the contents of the specified file, which may be anywhere
in the file system space.
#flastmod {virtual|file}="filename"
Outputs the time that the specified file was last modified. The
file can be a URI within the webpages root, or an absolute filename,
depending on whether 'virtual' or 'file' is specified.
#fsize {virtual|file}="filename"
Outputs the size of the specified URL or file, using the sizefmt.
$(TITLE)
$(TITLE)
The GSL Language
<HTML><BODY><CENTER>
<H1>Client Summary</H1>
<P>At $\(date) $\(time)
\.for client
<H3>$(name:)</H3>
<P>$\(address:)
<TABLE WIDTH="50%">
<TR><TD>Date:</TD><TD>Quantity:</TD><TD>Delivered:</TD></TR>
\.define total = 0
\.for order
<TR><TD>$\(date:)</TD><TD>$\(quantity:)</TD><TD>$\(delivered:)</TD></TR>
\.define total = total + quantity
\.endfor
</TABLE>
<P>Total ordered: $\(total)
\.endfor
</CENTER></BODY></HTML>
<data script = "testxml.gsl" >
Preparing Output From CGIs
Predefined Attributes
Passing Arguments to The XML File
http://xx.xx.xx.xx/myfile.xml?arg=value;arg=value;...
$(TITLE)
Why use GSL Scripts?
Predefined Attributes
Passing Arguments to The GSL Script
http://xx.xx.xx.xx/myfile.xml?arg=value;arg=value;...
$(TITLE)
Element syntax:
Effect:
default url
Defines the default URL for the image.
rect url x1,y1
x2,y2
Defines a rectangle between the two corner points
specified. Assumes x2 >= x1, y2 >= y1.
circle url x1,y1
x2,y2
Defines a circle where (x1,y1) is the circle's
center, and (x2,y2) is any point on its circumference.
point url x,y
Defines a point. Accepts a click within about 3
pixels of the point.
poly url x,y...
Defines a polygon, where (x1,y1)..(xn,yn) defines
the perimeter of the polygon. You can specify up to 100
points.
$(TITLE)
Setting-up A Virtual Host
[Virtual-Hosts]
xxx.xxx.xxx.xxx=filename.cfg # A multihomed host
www.some.domain=filename.cfg # A DNS-based virtual host
[Server]
webpages=websites/hostx/webpages
cgi-bin=websites/hostx/cgi-bin
Debugging Virtual Hosts
$(TITLE)
Overview
USER PASV STOU* MAIL* ALLO* CWD PWD XMKD
PASS TYPE SYST MSND* REST CDUP RMD XRMD
ACCT* STRU XSYS* MSOM* RNFR XCWD SITE* XPWD
REIN MODE PASV MSAM* RNTO LIST STAT* XCUP*
QUIT RETR APPE MRSQ* ABOR MKD HELP XEXC*
PORT STOR MLFL* MRCP* DELE NLST NOOP SIZE
FTP Configuration Options
The [FTP] Section
.item enabled
.item user-file
The [FTPLog] Section
.item enabled
.build anchor config_ftp_alias
The [FTP-Alias] Section
[FTP-Alias]
volume-c=C:\
The [FTPErrLog] Section
.item enabled
.build anchor config_ftp_users
FTP User File Syntax
[Admin]
Access=*
Password=-
Root=""
Aliases=1 # Will have access to aliases
[Anonymous]
Access=G
Password=*
Root=pub
[Guest]
Access=G
Root=c:\public\guest
[Upload]
Access=P
Password=upload
Root=/tempfiles/upload
Use-quotas=1
Soft-quota=10
Hard-quota=12
root=/home/users/guest
FTP Directory File Syntax
[guest/info]
[guest/info]
guest=-
An Example FTP Configuration
[Server]
Webpages=c:\webpages
[Ftp]
Root=c:\webpages
welcome="Welcome" # text or @filename
login-text="Login" # text or @filename
user-file=ftpulist.aut # Users authorization file
[Security]
password-case=1 # Case-sensitive passwords
filename=password.aut # Authorization file
[Anonymous]
Access=G
Password=*
Root=AnonFTP
[WEBRoot]
Access=G
Password=123456
Root=""
[U101]
Access=GPDMR
Password=123101
Root=User/U101
[U102]
Access=GPDMR
Password=123102
Root=User/U102
c:\webpages
|-AnonFTP
|-User
|-U101
|-U102
|-...
[/admin]
Admin=- # By default, admin access is disabled
Webmask=local # <== when 'local', remote access is not allowed
[User/U101]
U101=123101
[User/U102]
U102=123102
.-----------------------------------------------------------------
.page The Dynamic DNS Feature
.build anchor ddns
$(TITLE)
What is Dynamic DNS?
The Xitami Dynamic DDNS Client
The ddnsdef.xml Definition File
DDNS
SERVICE
[SIGNON]
[SIGNOFF]
$(TITLE)
What are Throttle Pipes?
Predefined Throttle Pipes
Defining New Throttle Pipes
$(TITLE)
Setting-up a Web Site
General Remarks
Top Ten Things To Do
Things To Avoid Like The Plague
Installing Xitami
Getting Yourself Connected
How Do Domain Names Work?
On An Intranet (LAN)
ping xxx.xxx.xxx.xxx
On The Big Wide World Wide Web
On a private dial-up network
Using Virtual Hosts
Managing Your Web Site
Updating The Site
Counting Hits
Using The Log Files
Using Password Protection
$(TITLE)
What is WSX?
Writing WSX Programs
Single-threaded or Multithreaded?
Managing Session Context
Messages From smthttp
send_wsx_request (
QID *to, /* Destination thread queue */
char *request_url, /* URL for WSX request */
char *arguments, /* URL arguments, if any */
char *virtual_host, /* Virtual host, if any */
char *filename, /* Physical filename for URL */
char *post_data, /* POSTed data, if any */
word symbols_size, /* HTTP symbol table size */
byte *symbols_data, /* HTTP symbol table data */
word config_size, /* HTTP config table size */
byte *config_data); /* HTTP config table data */
);
send_wsx_reqbin (
QID *to, /* Destination thread queue */
char *request_url, /* URL for WSX request */
char *arguments, /* URL arguments, if any */
char *virtual_host, /* Virtual host, if any */
word post_size, /* POSTed data size */
char *filename, /* Physical filename for URL */
byte *post_data, /* POSTed data */
word symbols_size, /* HTTP symbol table size */
byte *symbols_data, /* HTTP symbol table data */
word config_size, /* HTTP config table size */
byte *config_data); /* HTTP config table data */
);
DESCR symbols;
SYMTAB *symtab;
symbols.size = request-> symbols_size;
symbols.data = request-> symbols_data;
symtab = descr2symb (&symbols);
See below for an explanation of how to get the 'request' structure used in
this example.
typedef struct {
char *request_url; /* URL for WSX request */
char *arguments; /* URL arguments, if any */
char *virtual_host; /* Virtual host, if any */
char *filename; /* Physical filename for URL */
char *post_data; /* POSTed data, if any */
word symbols_size; /* HTTP symbol table size */
byte *symbols_data; /* HTTP symbol table data */
word config_size; /* HTTP config table size */
byte *config_data; /* HTTP config table data */
} struct_smt_wsx_request;
typedef struct_smt_wsx_request WSXREQ;
int get_smt_wsx_request (byte *buffer, struct_smt_wsx_request *request);
struct_smt_wsx_request
*request = NULL; /* Incoming smt_wsx request */
/* Decode the WSX request using this standard function call */
get_smt_wsx_request (thread-> event-> body, &request);
if (request)
the_next_event = ok_event;
else
{
/* The request can only be null if there is no memory left */
send_wsx_error (&thread-> event-> sender, HTTP_RESPONSE_OVERLOADED);
the_next_event = exception_event;
}
/* We're finished with the request structure - deallocate it */
free_smt_wsx_request (&request);
typedef struct {
char *request_url; /* URL for WSX request */
char *arguments; /* URL arguments, if any */
char *virtual_host; /* Virtual host, if any */
word post_size; /* POSTed data size */
char *filename; /* Physical filename for URL */
byte *post_data; /* POSTed data */
word symbols_size; /* HTTP symbol table size */
byte *symbols_data; /* HTTP symbol table data */
word config_size; /* HTTP config table size */
byte *config_data; /* HTTP config table data */
} struct_smt_wsx_request;
int get_smt_wsx_reqbin (byte *buffer, struct_smt_wsx_request *request);
Messages Back To smthttp
send_wsx_ok (QID *to, char *html_data);
send_wsx_multipart (QID *to, char *html_data);
send_wsx_bin (QID *to, qbyte html_size, byte *html_data);
send_wsx_mbin (QID *to, qbyte html_size, byte *html_data);
send_wsx_error (QID *to, dbyte error_code);
send_wsx_redirect (QID *to, char *new_url);
send_wsx_restart (QID *to, char *html_data);
send_wsx_kill (QID *to, char *html_data);
<HTML><BODY>
<P>Hello World!
</BODY></HTML>
Cache-control: no-cache
<HTML><BODY>
<P>Hello World!
</HTML></BODY>
Content-Type: xxxx/yyyy
..binary data..
Starting From A Skeleton Program
Modifying The Server main() Function
int xierror_init (void); /* Xitami error simulation agent */
xiadmin_init (); /* Xitami administration agent */
xierror_init (); /* Xitami error simulation agent */
smthttp_init (rootdir, cgidir);
Modifying The Server Config Files
[WSX]
path=agent
Where 'path' is a single word that identifies all URLs passed to this WSX
agent, and 'agent' is the agent name (as defined internally in the agent).
You can define a different path per virtual host, or organise your site so
that specific WSX agents are only available on specific virtual hosts.
send_wsx_install (QID *to, char *vhost, char *path, char *agent);
send_wsx_cancel (QID *to, char *vhost, char *path);
THREAD *http_thread;
/* Find 'main' thread in smthttp agent */
http_thread = thread_lookup (SMT_HTTP, "main");
ASSERT (http_thread);
send_wsx_install (&http_thread-> queue-> qid, NULL, pattern, AGENT_NAME);
Testing And Debugging The WSX Agent
Writing Efficient WSX Agents
$(TITLE)
Introduction
CGI
Server Extensions
Persistent CGI
LRWP
The LRWP protocol
ENV size
ENV data as a series of name=value pairs
POST size
POST data, if any
LRWP Environment Variables
The LRWP Library
char* lrwp_connect(LRWP* lrwp, /* pointer to UNCONNECTED LRWP object */
char* appname, /* Name or alias of Peer app */
char* host, /* hostname/IP address to connect to */
char* port, /* string containing port number */
char* vhost) /* optional virtual hostname */
Connects to the LRWP agent running in Xitami on host and port. Sends
the given appname to use as the URI alias that will trigger requests to
be sent to this peer. If vhost is given, this peer will only be sent
requests origininating from that virtual host. This function assumes
that the LRWP structure is uninitialized and clears it before use.
int lrwp_accept_request(LRWP* lrwp) /* pointer to CONNECTED LRWP object */
This funation waits for and recieves a request from the LRWP agent, and
populates the LRWP structure with the request data.
int lrwp_send_string(LRWP* lrwp, /* pointer to CONNECTED LRWP object */
char* st) /* an ouput string */
This function appends a string to the response buffer.
lrwp_finish_request() must be called to send the response back to Xitami.
int lrwp_send_data(LRWP* lrwp, /* pointer to CONNECTED LRWP object */
void* data, /* pointer to a data buffer */
size_t len) /* size of the data buffer */
Appends a buffer of (possibly binary) data of the specified size to
the response buffer. lrwp_finish_request() must be called to send the
response back to Xitami.
int lrwp_finish_request(LRWP* lrwp) /* pointer to CONNECTED LRWP object */
Completes the request by sending the response buffer back to Xitami
and prepares the lwrp structure to receive another request.
int lrwp_close(LRWP* lrwp) /* pointer to CONNECTED LRWP object */
Closes the connection to Xitami.
A Simple Example Using C
#include "sfl.h"
#include "lrwplib.h"
void main()
{
LRWP lrwp;
int count = 0;
int err;
char* errMsg;
char buf[256];
sock_init();
errMsg = lrwp_connect(&lrwp, "hello", "localhost", "81", "");
if (errMsg) {
fprintf(stderr, "%s\n", errMsg);
exit(1);
}
/* only handle 5 reqests, then exit */
while (count < 5 && lrwp_accept_request(&lrwp) != -1) {
count += 1;
lrwp_send_string(&lrwp, "Content-type: text/html\r\n\r\n");
lrwp_send_string(&lrwp,
"<HTML><HEAD><TITLE>hello</TITLE></HEAD>\n<BOD
sprintf(buf, "<H2>Hello from LRWP</H2>\nCount = %d", count);
lrwp_send_string(&lrwp, buf);
lrwp_send_string(&lrwp, "\n</BODY></HTML>\n");
lrwp_finish_request(&lrwp);
}
lrwp_close(&lrwp);
sock_term();
}
A Simple Example Using Python
from lrwplib import LRWP
def main():
lrwp = LRWP('hello', 'localhost', 81)
lrwp.connect()
count = 0
while count < 5: # exit after servicing 5 requests
count = count + 1
req = lrwp.acceptRequest()
req.out.write('Content-type: text/html\r\n\r\n')
req.out.write('<HTML><HEAD><TITLE>hello</TITLE><')
req.out.write('</HEAD>\n')
req.out.write('<H2>Hello from LRWP</H2>\nCount = ' + str(count))
req.out.write('\n</BODY></HTML>\n')
req.finish()
lrwp.close()
if __name__ == '__main__':
main()
.-----------------------------------------------------------------
.page FAQ
.build anchor faqlink
$(TITLE)
.macro FAQ_TABLE -
.if $\(PASS) == 1 -
.FAQ_TABLE $* -
.else -
.define skip $1 -
-
.for nbr from 1 to $\(count_$1) -
-
.define count_$1 = 0 -
.endif
.macro -noquote FAQH -
.define count_$1 = $\(count_$1?0) + 1 -
-
.define count_$1 = $\(count_$1?0) + 1 -
Installing and Configuring Xitami
.FAQH i When I try to use the /admin setup, Xitami asks for a password!
Now use userid 'admin' and password 'verysecret' to access the WBA.
.FAQ i Help - I don't understand how to define users and passwords!
[Security]
filename=defaults.aut
[/Admin]
admin=verysecret
[/personal]
john=Go96xas883
janet=Yhs7gsr73
(I'm inventing silly passwords here.)
[Ftp]
Directory-file=ftpdloc.aut
User-file=ftplocal.aut
Now you can edit ftplocal.aut to define users. The file ftpusers.aut shows
what's allowed. For example, to define an 'anonymous' user, who connects to
the ftproot/pub directory with read access only, write this in ftplocal.aut:
[Anonymous]
Access=G
Password=*
Root=/pub
.FAQ i Can I refer to an environment variable in the webpages setting?
[Alias]
john=ftproot/john
[/John]
john=Gsh65sgs12
[Security]
filename=defaults.aut
In principle you can now re-install Xitami safely. The installation will
not overwrite anything else you modified, including log files, web pages,
CGIs, etc. However, for safety, make a zip of the whole Xitami root before
re-installing, just in case. You should do this regularly anyhow.
.FAQ i Can I install Xitami on a system that already has a web server?
[server]
portbase=1000
will run Xitami on port 1080. The portbase is also added to the standard
FTP port of 21 to give, in this case, 1021.
.FAQ i How do I change the HTTP port but leave the FTP port at 21?
.FAQ i I can connect to http://127.0.0.1/ but not http://127.0.0.1/admin
.FAQ i Why does 127.0.0.1 not work with proxy servers?
[CGI]
debug=1
.FAQ i Why does my webmask (!xx.xx.*) not work?
.FAQ i I want each user to have FTP access to their personal web pages
[Aliases]
joe=ftproot/joe
Which points all URLs starting with '/joe' into this directory.
.FAQ i Does Xitami support http://ipaddress/~username?
.FAQ i I get the wrong default page, even if I change the webpages root!
Windows 3.x Questions
.FAQH 3 Xitami does not work - why not?
Windows 95/98 Questions
.FAQH w Can I use my Win95 system as a real server?
.FAQ w 'Port is already used by another server (WSEADDRINUSE)'
[Server]
portbase=1000
To run the HTTP service on port 1080 and the FTP service on port 1021.
.FAQ w 'How do I run PWS and Xitami on the same system?'
HKEY_LOCAL_MACHINE/
System/
CurrentControlSet/
Control/
ServiceProvider/
ServiceType/
W3SVC/
TcpPort will be set at 50 (hex), value must be changed to 901f (hex) for
port 8080. Reboot your system. If you're running FrontPage, FP Ext's must
be uninstalled and reinstalled again.
.FAQ w 'Your browser sent a malformed request'
netstat -a
or "netstat -na" if you don't have good DNS access. But this won't tell you
what programs are using them. Under some Unixes you can use something like
lsof (list open files) to find out the program using them; but I'm not aware
of any equivalent for Windows 95. With Xitami stopped, try running the
netstat command and look for a line with ":80" in it (or ":http") in the
local address part; which indicates that something is using port 80. If
there is, you'll have to dig around and see if you can find what it is.
.FAQ w My URLs starting with file:// don't work across the network
.FAQ w Tips for using a dial-up IP connection
.FAQ w Ping will find 127.0.0.1 but not myhost.com
[server]
autostart=0
which disables the autostart function. You can also check the xitami.log
file to see what error messages Xitami has logged. If you get a message
like 'Port is already used', check that no other web server is already
running.
.FAQ w I get 'Not authorized to access this resource' on aliases
.FAQ w Xitami crashes as soon as I try to start it
.FAQ w How do I reinstall just one file from the Xitami kit?
.FAQ w Why does Win95 insist on running 'service.bat'?
DEVICEHIGH=C:\WINDOWS\RAMDRIVE.SYS 1200 512 /E
where 1200 is the size and 512 is the sector size. Windows will attach the
next available free drive letter to it (e.g. 'R:'). If you want to load Perl
onto the RAM disk automatically, at boot time, add some commands to your
autoexec.bat:
md r:\perl
xcopy32 e:\perl\bin\perl*.* r:\perl
xcopy32 e:\perl\bin\cmd*.* r:\perl
PATH %PATH%;R:\PERL
set PERLLIB=E:\PERL\LIB
This assumes that you leave the Perl libraries on the hard disk (here, E:).
If you want a full-blown Perl on a RAM disk, you'll need about 6Mb of space.
wmkill -exact -titles -icons "Xitami Web Server"
To see the syntax for wmkill or wmps, type 'wmkill -help' or 'wmps -help'.
Windows NT Questions
.FAQH n My 16-bit CGI program does not output anything
@echo off
mycgi.exe > temp.tmp
type temp.tmp
.FAQ n The Xitami service can't access a network drive
KEY VALUE
ImagePath c:\program files\xitami\xiwinnt.exe
The space in 'program files' is what's bothering NT. Change the key data to
this:
KEY VALUE
ImagePath "c:\program files\xitami\xiwinnt.exe"
.FAQ n Can I restart the Xitami service from a batch file?
net stop xitami
net start xitami
.FAQ n How do I remove the Xitami icon in my control panel area?
This should do it. Note that NT will report that the service was started
successfully even if there was an error. Always test Xitami after changing
its configuration by running it as a console program (with the service
stopped). When the service has started, test the server and check its log
files for possible errors.
instsrv Xitamiweb c:\winnt\System32\srvany.exe
This will set the preliminary entries for a service named "Xitami" (choose
your own name).
DependOnService: REG_MULTI_SZ Tcpip Afd
You will be presented with a multi-entry screen. Just hit [Enter] after
each entry. You can add other services here if you wish.
Application: REG_SZ: C:\Xitami\Xiwin32.exe
AppDirectory: REG_SZ: C:\Xitami
UNIX Questions
.FAQH u Xitami does not build on my XXXX system
# CCDEFINES="-I/usr/src/linux/include"
# export CCDEFINES
# ./xibuild
.FAQ u Can I run Xitami from my ISP telnet account?
Which is best? It depends. (In the real world the answer is always "it
depends"; why do they never accept that in exams?)
To make Xitami "setuid root" after compiling it:
% su
# chown root xitami
# chgrp www xitami
# chmod 4770 xitami
# exit
%
where "www" is a Unix group that contains the users that should be able to
start Xitami. Then the users that can run Xitami will be able to start it
running as root, just by running it. If you do decide to set Xitami "setuid
root" beware that this is a potiental security risk, because it means that
users without the root password can start the server running, and if they
discover a bug in Xitami or a program run by Xitami they may be able to get
root access to other things on the machine.
[Security]
setuid=1
setuid-user=www
setuid-group=www
assuming you have a "www" user and a "www" group (this is a common setup for
Web Servers, but not universal). The default for setuid-user is "nobody" and
the default for setuid-group is "nogroup", but using "www" for user and
group is better if you have them available (or can add them). The user and
group privileges you choose will have to be sufficient to allow Xitami to
write to all the log files it needs, and run the programs it needs (eg,
cgi-bin programs).
OS/2 Questions
.FAQH o Xitami does not start, and 'ping 127.0.0.1' does not work
Application Programming Questions
.FAQH c How do I write CGIs?
.FAQ c Does Xitami have an API like ISAPI or NSAPI?
c:\php\php webpages\test.php
.FAQ c Why does my Perl CGI not run?
.FAQ c How can I find-out what directory a script is called from?
#! perl
print "Hello World!";
print map("<pre>$_ = $ENV{$_}\n</pre>", sort keys %ENV);
You'll find the values quite instructional, and you may even find a
variable that you can use to solve your problem.
.FAQ c Can I restrict the commands that a Perl CGI uses?
chdir ("c:/Xitami/cgi-bin/my_perl_script_dir");
open (FILE, ">myhint");
print FILE "This is my working directory";
close (FILE);
.FAQ c I get "Document contains no data" when running a Perl CGI
You can also try putting "warn" messages in your Perl script, eg:
warn "About to try ... \n";
and they'll appear in the CGI error log, so long as the script compiles and
runs up to that line.
.FAQ c How does Xitami handle its CGI stdio?
setmode (fileno (stdout), O_BINARY);
In Perl, this should work:
open (BLOCK, '>'.$ENV {'CGI_STDOUT'});
binmode BLOCK;
print BLOCK $binbuffer;
close BLOCK;
.FAQ c Must I use /cgi-bin in CGI URLs?
.FAQ c How do I set-up a web site counter?
[Server]
cgi-url=/cgi
.FAQ c My CGI '/somedir/cgi-bin/script' does not work
[/cgi-bin]
webmask=..whatever...
.FAQ c How do I allow CGIs in any regular HTML directory?
.FAQ c How do I do file uploads through CGI?
<BASE href="http://my-domain/cgi-bin/">
<FORM ENCTYPE="multipart/form-data" ACTION="_URL_" METHOD=POST>
File to process: <INPUT NAME="userfile1" TYPE="file">
<INPUT TYPE="submit" VALUE="Send File">
</FORM>
You can test this quite simply by using ACTION="cgi-bin/testcgi.exe" and
enabling CGI debugging ([cgi]debug=1) to see what the stdin stream looks
like. To decode the file upload data you could use the functions in
sflhttp.c.
<FORM ACTION="http://53pc2951:8000/servlet/DBQuery" METHOD="POST">
On any platform where the servletrunner is not available, one can use the
(undocumented) approach:
java sun.servlet.http.HttpServer -d your_servlet_directory
In other words, so long as a platform has a JDK 1.1 JVM, you can run servlets
with just a copy of jsdk.jar.
\Program Files\Live Software\JRun\2.2\jsm-default\services\jws\htdocs
I think it is modelled after Sun's Java Web Server. The default path for the
servlet classes is:
\Program Files\Live Software\JRun\2.2\jsm-default\services\jse\servlets.
I also believe Jrun's http capability comes from ACME's server API, and
so is very primitive compared with Xitami. It is great to be able to combine
Xitami's http capability and Jrun (or servletrunner)'s servlet capability.
.FAQ c Can I use LRWP peers with another web server?
LIBLIST="$LIBLIST $CCLIBS"
to
LIBLIST="$LIBLIST $CCLIBS libstdio.a libsfio.a"
.build anchor user_authentication
.FAQ c How do I do user authentication in a CGI script?
Authorization: Basic dXNlcm5hbWU6MTIzNDU2Nzg=
if not VariableSet( HTTP_AUTHORIZATION )
{
HeaderLine( 'HTTP/1.0 401 Unauthorized' );
HeaderLine( 'WWW-authenticate: basic realm="UserArea"' );
echo 'Text to send if user hits Cancel button';
exit;
}
else
HeaderLine( 'Location: http://anHost/users/userCode/userPage.html' );
An entry like the following should exist in the defaults.aut file:
[/users]
realm="UserArea"
UserName1="UserPassword1"
UserName2="UserPassword2"
...
Multihosting/Virtual Hosting
.FAQH v What exactly do I need to define for a Virtual Host?
! Loading somehost config
FTP Questions
.FAQH f People can't transfer files or see directories on my FTP server
[pub]
guest=..flags..
and not [guest/pub], [/pub], [/guest/pub] or any other combination. The key
is that you have to look at the protected directory name from the point of
view of the logged-on user. The user's home directory is []; the pub
subdirectory is [pub].
Log File Questions
.FAQH l How do I use the Xitami log files?
Miscellaneous Questions
.FAQH m How do you pronounce Xitami?
# robots.txt
User-Agent: *
Disallow: /
.FAQ m Can I customise the directory listings?
For SMT, you can do the same, but there are some sources you want to leave
out: smttst*.c and smtschm.c.
.FAQ m I'm building a Windows app based on Xitami, but it aborts
$(TITLE)
For Technical Support
For Regular Information
$(TITLE)
The Dream
The Machine
Thanks
$(TITLE)
Release Notes for Xitami 2.5
To re-enable use of the perlssi filter, remove references to xixssi in
xitami.cfg, and add the [Filter] definition for perlssi.
enabled=1/0 Enable or disable SSI, enabled by default
timeout=30 Timeout for CGI programs called from the SSI agent
exec=0 Enable/disable the #exec command, a potential security hole.
The SSI_INSECURE environment variable is no longer used.
[Ddns]
Domain = "black.xitami.net"
Enabled = "1"
Password = "TZO-xxxx-xxxx-xxxx-xxxx"
Service = "tzo.com"
Username = "admin@xitami.com"
Summary Release Notes for All Versions
.-----------------------------------------------------------------
.page license.htm=License Agreement
.build anchor license
$(TITLE)
LICENSE AGREEMENT
This license agreement covers your use of the iMatix Corporation XITAMI WEB
SERVER, its source code, documentation, and executable files, hereinafter
referred to as "the Product".
The Product is Copyright (c) 1991-2003 iMatix Corporation. You may use it and
distribute it according to this following License Agreement. If you do not
agree with these terms, please remove the Product from your system. By
incorporating the Product in your work or distributing the Product to others
you implicitly agree to these license terms.
This License Agreement covers the current version of The Product. iMatix
Corporation reserves the right to modify the terms of this License Agreement
at any moment, and without prior notification, in future releases of The
Product.
STATEMENT OF COPYRIGHT
The Product is, and remains, copyright 1991-99 iMatix Corporation, with
exception of specific copyrights as noted in the individual source files.
GENERAL CONDITIONS
The Product is provided in two forms: as a ready-to-run installation kit
consisting of executable programs, help files, etc. (the "Product
Executable") and as a package of source files, the "Product Sources".
You may freely use and distribute the Product Executable so long as you
provide the complete and unmodified original Product Executable installation
kit as supplied by iMatix Corporation.
The Product Sources fall under the License Agreement for the iMatix SMT
product. The applicable terms and conditions are repeated here.
CONDITIONS OF USE FOR PRODUCT SOURCES
You do not need to provide the source code for the Product as part of your
product. However, you must do one of these things to comply with the Product
License Agreement:
1. Provide the source code for Product modules that you use, and include
this License Agreement, or
2. Make your product freely available according to a license similar to
the GNU General Public License, or the Perl Artistic License, or this
License Agreement, or
3. Add this phrase to the documentation for your product: "This product
uses parts of the SMT Kernel, Copyright (c) 1991-2003 iMatix Corporation
<http://www.imatix.com>".
RIGHTS OF USAGE
You may freely and at no cost use the Product in any project, commercial,
academic, military, or private, so long as you respect the License
Agreement. The License Agreement does not affect any software except the
Product. In particular, any application that uses the Product does not
itself fall under the License Agreement.
You may modify any part of the Product, including sources and documentation,
except this License Agreement, which you may not modify.
You must clearly indicate any modifications at the start of each source
file. The user of any modified Product code must know that the source file
is not original.
At your discretion, you may rewrite or reuse any part of the Product so that
your derived code is not obviously part of the Product. This derived code
does not fall under the Product License Agreement directly, but you must
include a credit at the start of each source file indicating the original
authorship and source of the code, and a statement of copyright as follows:
"Parts copyright (c) 1991-99 iMatix Corporation"
RIGHTS OF DISTRIBUTION
You may freely distribute the Product, or any subset of the Product, by any
means. This covers, but is not limited to, distribution of binaries built
from original or modified copies of the product source code. The License, in
the form of the file called "LICENSE.TXT" must accompany any such
distribution.
You may charge a fee for distributing the Product, for providing a warranty
on the Product, for making modifications to the Product, or for any other
service provided in relation to the Product. You are not required to ask our
permission for any of these activities.
At no time will iMatix Corporation associate itself with any distribution of
the Product except that supplied from the iMatix Corporation Internet site
http://www.imatix.com.
DISCLAIMER OF WARRANTY
The Product is provided as free software, in the hope that it will be
useful. It is provided "as-is", without warranty of any kind, either
expressed or implied, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose. The entire risk as
to determining the suitability, quality and performance of the Product is
with you. Should the Product prove defective, the full cost of repair,
servicing, or correction lies with you.
TECHNICAL SUPPORT
Limited technical support can be had from support@imatix.com. Full
guaranteed technical support is subject to an iMatix Corporation support
license: current prices and commercial conditions can be had on request from
sales@imatix.com.
Published by iMatix Corporation
http://www.imatix.com
5 October, 1999