Sparrow Web™ Installation Guide
XEROX CORPORATION
PALO ALTO RESEARCH CENTER
Copyright © 2000-2001 XEROX CORPORATION. All Rights reserved.
Sparrow Web™ is a trademark of Xerox Corporation.
Copyright ©1999 The Apache Software Foundation. All rights reserved.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/)
Copyright © 2001 by Jason Hunter <jhunter@servlets.com>. All rights reserved.
Copyright © 1995-2001 Sun Microsystems, Inc.
Sun, Sun Microsystems, Solaris, SPARCstation, Java, Java Runtime Environment, Software Development
Kit are trademarks or registered trademarks of Sun Microsystems, Inc.
Copyright © 2001 Microsoft Corporation. All rights reserved.
Microsoft, Windows, Windows2000, and WindowsNT are registered trademarks of Microsoft Corp.
All other product names mentioned herein are trademarks of their respective owners.
Installing Sparrow Web
This document is a step-by-step, cookbook recipe for installing Sparrow Web™. It will
lead you through all the steps to acquire, install, and configure each of the components
needed to become a Sparrow Web website and to make you the Sparrow Webmaster.
Even if you don’t have deep technical knowledge about your computer or operating
system, it has been shown that by carefully following these instructions in detail you can
successfully bring Sparrow Web up on the machine that will become your Sparrow Web
server.
A Sparrow Web installation has three components: a Java 2 SDK (Software Development
Kit), a “Tomcat” web server, and Sparrow Web itself, which is implemented as a Java
servlet. You will first download a Java 2 SDK from JavaSoft, then the Tomcat web
server from the Apache-Jakarta project, then Sparrow Web itself from Xerox (unless you
have a Sparrow Web CD-ROM).
Sparrow Web has been developed and tested on Sun SPARCstation Solaris Versions 2.62.8 and on Windows NT4/2000 platforms; it also runs on Linux. To install on Linux,
follow the directions for the Solaris installation. The default configuration makes use of
port 8080 as the HTTP listening port.
If you already have Sparrow Web installed at your site, you can skip to Step 3. There are
no “patches” or “upgrade” releases; instead, a new release will carefully overwrite your
existing installation (and NOT overwrite any Sparrow Web pages that you have created)
unless you explicitly unpack it in a separate directory subtree or copy your old release to
save it before installing the latest code. After unpacking, you run the installation scripts
to perform the upgrade.
NOTE: throughout this document, items in italics are placeholders that you will have to
replace with your site-specific information such as domain names, server names, and
directory/file paths.
NOTE: THE INSTALLATION SCRIPTS DO NOT HANDLE FILE PATHS THAT CONTAIN
SPACES OR ODD PUNCTUATION. Do not install any of these components in a directory
whose path contains spaces or odd punctuation. In particular do not install components
to C:\Program Files\… . Punctuation characters dot (.), dash (-), and underline (_) are
fine, as in jakarta-tomcat-3.2.3, but please avoid spaces, apostrophe, and all manner of
quotes.
Step 0: A user named sparrow
Sparrow Web is a Web-based system that writes HTML files as well as reading them.
This has important implications with respect to the underlying file system protections at
your site. A traditional website need grant only read access to the web server that fetches
pages and sends them to the browser; the Sparrow Web server will need write access as
well, because the whole purpose of Sparrow Web is to quickly modify web pages in place
via the web browser.
2
For the moment, you can download and install Sparrow Web using your own user
account and user name. If you decide to deploy Sparrow, we strongly recommend that
you create a user account named sparrow that is NOT a privileged user such as UNIX
root or Windows administrator. Then, whenever you login to do work on your Sparrow
Web installation, you login as user sparrow. This includes installation and maintenance.
When you start or restart the Tomcat server you should be logged in as user sparrow. If
you are on a UNIX system, you will have to place user sparrow in UNIX protection
groups that have write access to your Sparrow Web files. If you are on a Windows
system, you may have to give user sparrow permission to write Sparrow Web files in the
NT file space.
Step 1: Java Software Development Kit
Your Sparrow Web server machine must have a Java 2 Software Development Kit on it,
version 1.2.2 or later. If you have other Java applications running on your machine you
may already have a JDK-1.2.2 or J2SDK-1.3.x on your Sparrow Web server machine; if
so you do not have to download a separate one, but you will have to know the Java 2
SDK installation directory to configure Sparrow Web. If not, you will download a recent
version of the J2SDK. Note: a Java Runtime Environment (JRE) is no longer sufficient.
You need an SDK.
For J2SDK version 1.3.x, Solaris: find download instructions at JAVA(TM) J2SDK
Standard Edition Download for SPARC
Be sure to download the version of Solaris for SPARC and NOT for Intel
x86.
For J2SDK version 1.3.x, Windows: find download instructions at JAVA(TM)
J2SDKStandard Edition Download for Windows
Extract/unpack the package, remembering to put it into a directory path that has no
spaces or punctuation in it. The full path to the directory into which you extract this
package (or the full path to your existing Java 2 SDK installation) will be called the
JAVA_HOME directory for the purpose of configuring Sparrow Web in these
instructions.
There is no installation script to run after the download. Further information and help
about Java can be found at http://www.javasoft.com.
Step 2: Apache-Jakarta Tomcat 3.2.3 web server
The Apache-Jarkata Tomcat web server is written in Java and serves Java servlets, JSP
pages, and HTML pages. This is the web server that will run the Sparrow Web servlet on
your server machine and will be the HTML page server for your Sparrow Web
installation. You must download this server and it should work with its default
configuration- there is no installer to run after you have unpacked the Tomcat archive
file. Tomcat 3.2.3 introduces security features that you may wish to use if your Sparrow
Web site is not inside a firewall or otherwise needs protection. See the Appendix entitled
3
Setting Up Security with Tomcat 3.2.3 for instructions on how to use Tomcat security
features.
For version 3.2.3, Solaris: download the package at Jakarta-Tomcat 3.2.3 release, GZ
format (Tomcat 3.2.3 is no longer provided in .Z format).
For version 3.2.3, Windows: download the package at Jakarta-Tomcat 3.2.3 release, ZIP
format
Extract/unpack the package, remembering to put it into a directory path that has no
spaces or punctuation in it. The full path to the directory into which you extract this
package will be called the TOMCAT_HOME directory for the purpose of configuring
Sparrow Web in these instructions.
There is no installation script to run after the download. Further information and help
about Tomcat can be found at the Tomcat home page.
Step 2.1: fix tomcat.bat. DO NOT SKIP THIS STEP.
On Windows: tomcat.bat expects the environment variable JAVA_HOME to be
available in its environment. The easiest and surest way to make that happen is to add a
line to tomcat.bat that sets JAVA_HOME. The other way is to use Windows User
Environment setup to set JAVA_HOME.
To add the line, open TOMCAT_HOME\bin\tomcat.bat in a plaintext editor. Find the
line:
set _CLASSPATH=%CLASSPATH%
and insert a line of the form:
set JAVA_HOME=JAVA_HOME
substituting your value for JAVA_HOME, after the set _CLASSPATH line. Save the file
as plaintext.
For example, if you installed Java at C:\java\j2sdk1.3.1, then the line would read:
set JAVA_HOME=C:\java\j2sdk1.3.1
Note: there is NO whitespace in JAVA_HOME=C:\java\j2sdk1.3.1 .
Step 2.2: startup Tomcat 3.2.3 web server. DO NOT SKIP THIS STEP.
The Tomcat installation is not complete until the server is started.
Complete the installation of Apache Tomcat by ascertaining that the Servlet Examples
that are included in the Tomcat package execute correctly. Start the Tomcat server:
On Solaris: execute the script TOMCAT_HOME/bin/startup.sh. NOTE: you may need
to do a “chmod a+x” to all of the .sh files in that directory.
On Windows: execute the script TOMCAT_HOME\bin\startup.bat.
The server should start and print some initial configuration messages. Then point a Web
browser at your Tomcat server home page; the URL has the form:
http://YOURMACHINE.YOURDOMAIN:8080
and access the Tomcat homepage on your machine. For example, if you are installing
Sparrow Web on a machine named foobar and your domain is baz.org, then the URL for
4
the Tomcat server home page is http://foobar.baz.org:8080. On that page, click on
Servlet Examples and run the test servlets. Refer to the Tomcat installation
documentation to resolve any problems.
Step 3: Sparrow Web 2.0 community shared web pages
Sparrow Web itself shares characteristics with Web servers and needs to be downloaded,
unpacked, configured, and installed. We will guide you through the process, but if you
have questions you may wish to consult an experienced colleague or message us at
sparrowavenue@parc.xerox.com
Step 3.1: Get a copy of the Sparrow Web 2.0 release file
If you already have an archive file (.Z or .zip file) that you have downloaded:
Proceed to step 3.2.
If you have Sparrow Web on a CD-ROM
Put the CD-ROM in your CD drive.
On Solaris: mount the CD-ROM drive. On the mounted drive, find the file with a name
like "Sparrow_2.0.x.tar.Z". Copy this file to your hard drive.
On Windows: find the drive letter that corresponds to your CD drive (e.g., D:, E:, F:, or
G:). Browse the CD-ROM and find the file with a name like "Sparrow_2.0.x.zip".
Double click on this file. Proceed to step 3.2.
If you don't have a CD-ROM but you have access to the PARC web site
On Solaris: Click on the following link and save the resulting file to your hard drive:
download latest Sparrow 2.0 release, Z format
On Windows: Click on the following link. If WinZip starts up, proceed to step 3.2.
Otherwise, save the file to your hard drive. Then, find the file on your hard drive and
double-click on it. WinZip should start up. Proceed to step 3.2. download latest
Sparrow 2.0 release, ZIP format
NOTE: the latest version of Sparrow_2.0 will be downloaded (e.g. Sparrow_2.0.9aA) but
it will unpack itself into any existing installation subtree rooted at sparrow_2.0.
Step 3.2: unpack Sparrow Web 2.0
On Solaris, look for the directory that Tomcat uses as its root directory for web
applications at TOMCAT_HOME/webapps/ROOT.
NOTE: If there is no directory named ROOT under TOMCAT_HOME/webapps then you
did not complete Step 2.1 successfully. Do not make a directory named ROOT and
continue; go back and find the problem in step 2.1.
Next: cd to TOMCAT_HOME/webapps/ROOT, then execute:
% uncompress .…/Sparrow_2.0.x.tar.Z (using the .Z file downloaded in step 3.1).
% tar xpf Sparrow_2.0.x.tar
which will create directory sparrow_2.0 under ROOT and unpack the Sparrow Web
distribution.
The full path to this directory (TOMCAT_HOME/webapps/ROOT/sparrow_2.0) is the
SPARROW_HOME directory for later use in configuring Sparrow Web.
5
On Windows, use WinZIP or similar tool to unpack the ZIP file from step 3.1 and extract
it. Look for the directory that Tomcat uses as its root directory for web applications at
TOMCAT_HOME\webapps\ROOT.
NOTE: If there is no directory named ROOT under TOMCAT_HOME\webapps then you
did not complete Step 2.1 successfully. Do not make a directory named ROOT and
continue; go back and find the problem in step 2.1.
Extract the ZIP file into TOMCAT_HOME\webapps\ROOT. It will create directory
sparrow_2.0 under ROOT and unpack the Sparrow Web distribution.
The full path to this directory (TOMCAT_HOME\webapps\ROOT\sparrow_2.0) is the
SPARROW_HOME directory for later use in configuring Sparrow Web.
Step 3.3: configure Sparrow Web 2.0
On Solaris, if necessary, set the DISPLAY environment variable to the X server from
which you are doing the installation. Change directory (cd) to the SPARROW_HOME
directory and execute ./configure.csh. You may have to execute "chmod a+x *.csh" in
this directory in order to run the CShell scripts within it.
An editing window will open on file SPARROW_HOME/install_data.txt and may open on
SPARROW_HOME/install_data.txt.template (if install_data.txt already exists from a
previous install.)
On Windows, double click on SPARROW_HOME\configure.bat or open a Command
Tool, cd to the SPARROW_HOME directory, and execute configure.bat.
A Notepad window will open on file SPARROW_HOME\install_data.txt and a second
Notepad window may open on SPARROW_HOME\install_data.txt.template (if
install_data.txt already exists from a previous install.)
NOTE: the two instances of Notepad may be exactly on top of one another.
Move one of them.
NOTE: when you are installing on the Windows platform, you must type
DOUBLE BACKSLASH (\\) wherever a single backslash (\) would appear in a
Windows path. For example, if you installed Tomcat at C:\mystuff\, your
SPARROW_HOME directory would be entered into install_data.txt as
C:\\mystuff\\jakarta-tomcat-3.2.3\\webapps\\ROOT\\sparrow_2.0.
install_data.txt contains instructions for editing itself to match the Sparrow Web
configuration on your server machine. Follow the instructions in install_data.txt and fill
in the values that correspond to your Sparrow Web installation. Save the file to itself,
and be sure to save it as plaintext.
If you are doing an upgrade or patch, you already have a customized install_data.txt from
a previous installation. Compare it to the latest version of install_data.txt.template to see
if any new attributes have been added to Sparrow Web and need to be customized for
your site.
6
Step 3.3.1: acquire mail.jar and activation.jar (optional)
Due to licensing restrictions we cannot distribute two Java archive files for this
installation, mail.jar and activation.jar. They are only needed if you use the mail
notification feature of Sparrow Web.
To get mail.jar and activation.jar:
Go to download Java mail, follow the instructions, and when the ZIP file javamail1_2.zip is unpacked, find only the file named mail.jar.
Go to download activation framework, follow the instructions, and when the ZIP file
jaf1_0_1.zip is unpacked, find only the file named activation.jar.
On Solaris: put mail.jar and activation.jar into your SPARROW_HOME/classes
subdirectory, and make a backup copy somewhere else in case you have to redo this step.
On Windows: put mail.jar and activation.jar into your SPARROW_HOME\classes
subdirectory, and make a backup copy somewhere else in case you have to redo this step.
Step 3.4: install Sparrow Web 2.0
Once you have completed Step 3.3 and install_data.txt has been customized for your
Sparrow Web installation, you are ready to do the actual installation step.
On Solaris, change directory (cd) to the SPARROW_HOME directory and execute
./install.csh.
On Windows, double click on SPARROW_HOME\install.bat or open a Command Tool,
cd to the SPARROW_HOME directory, and execute install.bat.
The first part of the installation produces routine messages in a shell typescript.
Ordinarily you will not have to concern yourself with those messages unless this step
goes seriously wrong. Once the shell portion is completed, the installation progress is
logged to file install.log. File install.log will be opened in a text editor when the install
script finishes. Text in install.log will indicate progress through the installation. Most of
the text will be about “redirecting” HTML files, but the topmost lines of the log are more
informative. If you don't see text about redirecting HTML files, then the installation was
aborted and you may have to look in the shell typescript to find out why. Both the shell
and install.log will remain visible until you quit the editor window after viewing
install.log. Be sure to quit the editor after viewing install.log.
You may have to look at the text that appears in install.log to see if the installation is
correct. If things go wrong it may be due to typographic errors or missing entries that
you made in step 3.3. You may retry steps 3.3 and 3.4 until the results are satisfactory:
On Solaris: To be certain you are starting from scratch, execute file ./reinstall.csh instead
of ./install.csh. The reinstall scripts will delete any files that are created by the install
scripts and then run the install scripts.
On Windows: To be certain you are starting from scratch, execute file reinstall.bat
instead of install.bat. The reinstall scripts will delete any files that are created by the
install scripts and then run the install scripts.
NOTE: in order to better secure the installation, Sparrow Web install scripts move
important files out of the ROOT/sparrow_2.0 tree to
7
TOMCAT_HOME/webapps/sparrow/classes. There you should find JAR files,
sparrow.conf, servermap.xml, sparrowacl.xml, and log-config.xml files, which are not
accessible and should not be accessible via a browser.
Troubleshooting the installation
If the installation has gone seriously wrong, you can backup to unpacking the archive (Z
or zip file) directly over the sparrow_2.0 directory, which will restore the initial files
from the archive but keep your install_data.txt intact. Then open up install_data.txt and
look really carefully at each and every entry to make sure it is complete and correct- use
the examples above each entry to guide you. Then run reinstall.bat|csh to start over. If
all else fails, delete the sparrow_2.0 directory and backup to Step 3.2. Finally, help is
available- message sparrowavenue@parc.xerox.com. We want this to work for you.
Step 3.5: run Apache Tomcat with Sparrow Web 2.0
Finally you are ready to restart the Tomcat server and make the Sparrow Web servlet
known to it. If the Tomcat server (started in section 2.1) is not running for some reason,
a Java error message and stack trace will appear in the typescript after the words
“Stopping tomcat,” which may be ignored.
On Solaris: cd to the SPARROW_HOME directory and execute ./sparrow.csh which was
created as part of the install step 3.4. This will (re)start the Tomcat server. You may also
run ./sparrow.csh to restart the Tomcat server and Sparrow Web at any time, such as after
your server machine has restarted for any reason or after you have changed sparrow.conf
or the mapping files or any of the user and security-related files, described below.
On Windows: double click on file sparrow.bat or open a Command Tool, cd to the
SPARROW_HOME directory, and execute sparrow.bat, which was created as part of the
install step 3.4. This will (re)start the Tomcat server.
HINT: If you don’t see sparrow.bat in the file browser window, click on the
window to select it and type the F5 key to cause the browser to refresh itself.
sparrow.bat should appear.
You may also run sparrow.bat to restart the Tomcat server and Sparrow Web at any time,
such as after your server machine has restarted for any reason or after you have changed
sparrow.conf or the mapping files or any of the user and security-related files, described
below.
Step 3.6: test your Sparrow Web 2.0 installation
In a Web browser, get
http://YOURMACHINE.YOURDOMAIN:8080/sparrow_2.0/verify.html. Be sure to get
verify.html via HTTP to your server, not by a file:// URL or by drag-and-drop. This page
has a single link on it labeled Verify Sparrow. Click on the link to run a set of sanity
checks on your installation and deliver the result to your browser. Review the result for
accuracy. If everything reports as “GOOD” don’t sweat the small stuff at the end of the
report, which is just FYI.
If problems are reported, look for typos and other errors such as file paths in your
install_data.txt file. Fix as needed, and then redo Steps 3.4 and 3.5: if this is a first time
8
installation you will want to use the reinstall scripts (viz. 3.4) and be sure to restart the
server (viz. 3.5). If this is a patch or update install, delete file sparrow.conf so that it gets
recreated from the data in install_data.txt. Depending on what went wrong, file
sparrow.conf could be in one of several places in the file tree, so search for and delete all
instances of it and the run the install script again.
Step 3.7: use your Sparrow Web 2.0 installation
Get the Sparrow Web home page from your installation into your Web browser. Its URL
should be http://YOURMACHINE.YOURDOMAIN:8080/sparrow_2.0/sparrowhome.html.
It contains the Sparrow Web Page Factory, with samples of several types of useful
Sparrow Web pages and links to create your own copies of these pages as jumping off
points for using Sparrow Web. Try each of the links to an example of a Sparrow Web
page and then use the “Make a new …” links to create new Sparrow Web pages in your
installation. Those pages should be fully functional. Try them out.
Windows NOTE: if you run a Netscape browser on the same Windows machine as your
Sparrow Web server and use it to execute Sparrow Web operations it will appear that
Sparrow Web runs extremely slowly. This is not due to Sparrow Web: it is due to the
fact that Netscape uses more than 95% of the available CPU in a busy loop waiting for
the (Tomcat) server to respond, which of course it cannot do very quickly with only 5%
of the CPU left to it. There are several workarounds, including:
 stop Netscape and use IE to access the Sparrow Web pages;
 access the Sparrow Web pages from a different machine with either Netscape or
IE;
 use the Windows Task Manager to set the process priority of netscape.exe to very
low. This is not really a good idea but will let you test the initial installation.
Sparrow Web file versions and backup
Sparrow Web keeps a specified (in the install_data.txt installation file) number of old
versions of a Sparrow Web page in the file system at any given time. A new version is
created, and old versions are trimmed to the specified number of versions, whenever a
Sparrow Web page is modified (edited, added to, archived from, etc.) unless the new
version is too new, where the minimum amount of elapsed time between versions is also
specified in the install_data.txt installation file. This odd method of not making a new
version if the minimum amount of time has not elapsed is designed to purposefully keep
older versions in case either the code or the user clobbers a Sparrow Web page and the
user attempts to use Sparrow Web itself to rectify the situation and fails. If a new version
was created every time a page changed, the user could quickly clobber all of the old
versions and have no chance to recover the page.
The default values in sparrow.conf are 5 minutes (300 seconds) for the minimum time
between new versions and a total of four versions for each file:
# Backup version properties:
# minimum number of seconds between versions
VERSION_INTERVAL = 300
9
# maximum number of versions
VERSION_COUNT = 4
File versions are indicated by appending a tilde (~) followed by a version number to the
name of each Sparrow Web file. For example, if the user makes a Sparrow Web file
called my_list.html and edits it three times over the course of a day, the file system will
contain files named:
my_list.html
my_list.html~1
my_list.html~2
my_list.html~3
my_list.html~4
After two more edits spaced by at least the minimum version interval, the file system will
contain files:
my_list.html
my_list.html~3
my_list.html~4
my_list.html~5
my_list.html~6
A user interface to the backup system is available near the bottom of the Control Panel.
A pulldown menu offers all of the available backup versions, and a Preview button
displays the selected backup version along with buttons to rollback to that backup version
or Cancel and return to the current version. Users may go Back in their browser to select
other backup versions for Preview and possible rollback operations.
Troubleshooting
There are a number of things that might go wrong. If they do, carefully verify the format
and content of install_data.txt and, if needed, correct the entries and return to the Step 3.4
reinstall procedure. Also, remember that the Sparrow Web servlet writes web pages as
well as reads them, so it is necessary for the “user” who executes the Sparrow Web
servlet to have write permissions to the places in the file system where those pages are
stored.
If you get as far as fetching a Sparrow Web page and clicking on an editing image or
button and the browser displays a mapping error, this is due to missing or incorrect
information in file TOMCAT_HOME/webapps/sparrow/classes/servermap.xml. Look
carefully at the typescript in which the Tomcat server is running and see if there are error
messages about the format or content of servermap.xml. servermap.xml contains its own
documentation, so open it up and see if you can find a problem in the format or content of
the data.
Another configuration file, TOMCAT_HOME/webapps/sparrow/classes/sparrow.conf,
was written during the installation process. You might want to open and verify the
contents of that file, although it is automatically generated from install_data.txt and
should be correct.
10
Installation alternatives
There are a number of alternative ways to configure Sparrow Web. The default HTTP
port can be changed for the Tomcat server by modifying its configuration file server.xml.
File server.xml contains many other installation parameters that we have never changed.
It is possible to have other HTTP servers serve Sparrow Web pages, which are ordinary
HTML pages as far as a browser and HTTP server are concerned, either instead of or in
addition to the Tomcat server. We refer to such servers as companion servers. The
companion server mapping information must be entered into the servermap.xml file; see
servermap.xml for instruction on how to do that. The tricky bit is that the Tomcat server
must be able to access any page that uses the Sparrow Web servlet as an ordinary file for
reading and writing- that is exactly what the mapping information is used for.
It is possible to configure Sparrow Web to use another servlet server such as Apache
JServ. We have an existence proof that we can configure Apache JServ to run Sparrow
Web, but we had to make changes to the JServ configuration files to do that. If you
already have a servlet server running at your site, consult with your site administrator
regarding installing the Sparrow Web servlet files need to run Sparrow Web on the
existing server.
We have also had two successful installations on Debian Linux.
When all else fails, and you’ve read the directions, message
sparrowavenue@parc.xerox.com
Appendix A: Basic Security with Tomcat 3.2.3
Tomcat 3.2.3 provides HTTP Basic Authentication and Form Authentication; e.g. you
can protect access to your Sparrow Web site or to particular documents on your Sparrow
Web site by modifying the XML files that the server uses. The following specifies how
to use Tomcat security to password-protect your Sparrow Web site and to tell Sparrow
Web to refuse to display the contents of file directories within your Sparrow Web site.
We strongly recommend that you use protection, but if you are in a safe place such as
behind a firewall you may not wish to password-protect the Sparrow Web site.
In addition, Sparrow Web augments the Tomcat-supplied authentication and access
control with its own access control mechanism, called TopGun, for specifying which
users can be writers and/or managers of Sparrow Web pages. Instructions for using
TopGun follow in Appendix B. However, getting Basic Authentication working is a
good first step towards a TopGun-controlled site.
These instructions are for Tomcat on either platform; Windows users should substitute
Windows-style file paths for the UNIX paths here.
NOTE: whenever any change is made to files tomcat-users.xml or web.xml or
server.xml, the changes will not take effect until you restart the Tomcat server by
11
executing SPARROW_HOME/sparrow.csh or SPARROW_HOME/sparrow.bat on the
corresponding platform.
Step A-1: tomcat-users.xml
Find the file tomcat-users.xml in your TOMCAT_HOME/conf/ directory.
On Windows: read tomcat-users.xml into WordPad to edit it. This file has UNIXstyle line endings that do not work on Windows. WordPad is smart enough to read the
file properly and fix the line endings when you save the file.
First, remove the default user names, passwords, and roles. This is a classic security
hole- hackers will simply try to login with the default user names and passwords that are
known to the public. Get rid of them.
Add appropriate usernames, passwords, and roles (e.g. <user name="MySparrow"
password="yourgood password" roles="MySparrow" /> ). Unfortunately the basic
tomcat setup requires you to store the password in the clear. Be sure there is at least one
role for each user name that is the same string as the user name. Substitute strings of
your choice for name and password and role. Save the file as plaintext.
See the administrators guide for more information about tomcat-users.xml.
Step A-2: web.xml
Find the file web.xml in your TOMCAT_HOME /webapps/ROOT/WEB-INF/ directory.
There are multiple web.xml files scattered about, so be sure to find this exact one.
On Windows: read web.xml into WordPad to edit it. This file has UNIX-style line
endings that do not work on Windows. WordPad is smart enough to read the file
properly and fix the line endings when you save the file.
Edit it to look as follows, making the appropriate substitutions for your site; save it as
plaintext:
-----------------START PASTE--------------------<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
[
<!ENTITY mimetypes SYSTEM "mimetypes.xml">
]
>
<web-app>
<security-constraint>
<web-resource-collection>
<web-resource-name>Sparrow Protected Area</web-resource-name>
<!-- Define the context-relative URL(s) to be protected -->
<url-pattern>/sparrow_2.0/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<!-- Anyone with one of the listed roles may access this area -->
<role-name>MySparrow</role-name>
12
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>YourRealmName</realm-name>
</login-config>
<!-- include file mimetypes.xml -->
&mimetypes;
</web-app>
-----------------END PASTE----------------As shown, these entries will require anyone accessing any file on the server to
authenticate as MySparrow with the appropriate password as entered into tomcatusers.xml. By adding additional <security-constraint>s and <url-pattern>s you can
protect different areas of the file system differently, though you have to be careful about
your use of url-patterns, as you can accidentally override settings for different areas. See
Appendix B, step B-1, for more information on web.xml.
You may also find more information about web.xml in the Sparrow Web administrators
guide.
A detailed specification for what may appear in web.xml may be downloaded and
extracted from the Java Servlet 2.3 Specification.
Step A-3: server.xml
Find the file server.xml in your TOMCAT_HOME/conf/ directory.
On Windows: read server.xml into WordPad to edit it. This file has UNIX-style line
endings that do not work on Windows. WordPad is smart enough to read the file
properly and fix the line endings when you save the file.
Open the file in a plaintext editor, and find the section that contains:
<!-- "default" handler - static files and dirs. Set the
"suppress" property to "true" to suppress directory listings
when no welcome file is present.
NOTE: This setting applies to *all* web applications that
are running in this instance of Tomcat.
-->
<RequestInterceptor
className="org.apache.tomcat.request.StaticInterceptor"
debug="0" suppress="false" />
Changing the value for suppress from "false" to "true" will suppress exposure of your
installation directories. In any directory, a file called index.html may be installed to serve
as the default file; on UNIX, a symbolic link named index.html to an HTML file will
work as well. Save server.xml as plaintext. If you set suppress to true it will not be
possible for your users to see directory listings of the examples, apps, doc, and img
13
subdirectories which may contain useful information for your users, which may be
inconvenient.
Step A-4: restart
After you are done with these changes restart the Sparrow Web installation by executing
sparrow.bat in your SPARROW_HOME directory and the BASIC authentication should
be in effect.
Appendix B: TopGun Security with Tomcat 3.2.3
NOTE: TopGun is under development and is incomplete at this time. The following
instructions require hand editing of XML files. In a future release, the user interface for
TopGun permissions management, accessed via the Sparrow Web Control Panel
Permissions button, will also manage file web.xml. Remember to restart your server after
changing these web.xml or tomcat_users.xml.
NOTE: if you attempt to use TopGun security without first configuring web.xml to use
FORM based authentication (Step B-1, below), you will get HTTP 404 errors (page not
found) for page "j_security_check". Be advised.
First, there is a property in install_data.txt that governs TopGun security:
TOMCAT_SECURITY = enabled to turn on TopGun security;
TOMCAT_SECURITY = none
to turn off TopGun security.
Unfortunately, this is a misnomer, and should be TOPGUN_SECURITY, but it isn't. The
only way to defeat true Tomcat security is to edit the web.xml file to remove security
constraints.
Step B-1: web.xml
For TopGun, the first thing to do is to change the aforementioned web.xml (in your
TOMCAT_HOME /webapps/ROOT/WEB-INF/ directory, which you should have already
fixed up by editing it in WordPad) to look something like the following, substituting
your own role names for your site:
-----------------START PASTE--------------------<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
[
<!ENTITY mimetypes SYSTEM "mimetypes.xml">
]
>
<web-app>
<security-constraint>
<web-resource-collection>
14
<web-resource-name>Sparrow Protected Area</web-resource-name>
<!-- Define the context-relative URL(s) to be protected -->
<!-- DO NOT USE /* to protect everything, use /sparrow_2.0/* ->
<url-pattern>/sparrow_2.0/*</url-pattern>
<!-- add other url-pattern entries as needed to tighten down access -->
</web-resource-collection>
<auth-constraint>
<!-- Anyone with one of the listed roles may access this area -->
<role-name>tomcat</role-name>
<role-name>role1</role-name>
</auth-constraint>
</security-constraint>
<!-- add other security constraints as needed to define access regions
-->
<login-config>
<auth-method>FORM</auth-method>
<realm-name>Sparrow Authentication</realm-name>
<form-login-config>
<form-login-page>/login/login.jsp</form-login-page>
<form-error-page>/login/error.jsp</form-error-page>
</form-login-config>
</login-config>
<!-- include file mimetypes.xml -->
&mimetypes;
</web-app>
-----------------END PASTE----------------Note that the new value of <login-config> in web.xml changes the login configuration
from BASIC to FORM, and jsp files that have been copied into
TOMCAT_HOME/webapps/ROOT/login will be presented to the user as needed.
A detailed specification for what may appear in web.xml may be downloaded and
extracted from the Java Servlet 2.3 Specification.
Refer to the <web-app> above. In brief, you may use a <url-pattern> to define an area of
the application tree. Sets of url-patterns make up a named <web-resource-collection>.
An authorization constraint <auth-constraint> may be associated with a <web-resourcecollection> to form a <security-constraint>, and several security-constraints may appear
within a <web-app>. Within an authorization constraint, a list of <role-name> entries
specifies the set of roles that are authorized to read the associated <web-resourcecollection>. These roles are defined in file tomcat-users.xml. Finally, <login-config>, as
shown, specifies the use of HTTP Form Authentication and associates JSP pages that,
when presented to the user in the browser, allow the user to enter name and password
authentication information. In Tomcat, authentication occurs only when the user invokes
a URL that has been specified to require authorization; that is, there is no login page per
se.
Note that this level of security is native to the Tomcat server and controls read access to
web pages. Sparrow Web has implemented an extended form of security that we call
15
TopGun. TopGun allows access control to Sparrow Web pages at two additional levels:
writer and manager. TopGun configuration is held in file sparrowacl.xml
Step B-3: sparrowacl.xml
See the Sparrow Web administrators guide for information on sparrowacl.xml. In brief, it
is maintained by the Sparrow Web Permissions interface and should not under ordinary
conditions be edited by hand. However, in this version of Sparrow Web the administrator
must be concerned about keeping consistency between the web.xml-specified read
permissions and the (automatically maintained) sparrowacl.xml for writer/manager
permissions. It is possible for users to assign writer/manager permissions that are
inconsistent with reader permissions. In a future version of Sparrow Web we intend to
integrate all permissions within the Permissions interface.
Step B-4: restart
After you are done with these changes restart the Sparrow Web installation and the
FORM authentication should be in effect. With an empty sparrowacl.xml, the difference
you will see is that forms rather than pop-up windows will be presented for login. If you
augment sparrowacl.xml with real data via the Permissions interface in the Sparrow Web
Control Panel, authorization forms will appear in the browser whenever writer/manager
actions, such as editing an item on a controlled page, require user authentication.
16