Sparrow Web™ Administrators Guide
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 F
oundation. All rights reserved.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/)
Copyright © 2001 by Jason Hunter <email@example.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, Windo
ws2000, and WindowsNT are registered trademarks of Microsoft Corp.
All other product names mentioned herein are trademarks of their respective owners.
This manual is for administrators who install, develop, and maintain a Sparrow Web™
prerequisite for this manual is the
. Even if you did not
actually perform the installation, go back and read the installation guide for background
File paths in this document use the
UNIX forward slash (/) notation; substituting the
Windows back slash convention (
) will yield correct Windows paths.
After installation, administrators will be concerned with understanding and using the
several configuration files within the installatio
n, and with the authorization and access
control features provided by Tomcat and additionally by Sparrow.
TopGun, the Sparrow Web security system
The Sparrow Websecurity system is designed to be integrated with Tomcat and
Docushare security. Login names a
nd passwords are shared with the underlying server,
and in the case of Tomcat, the actual login is also shared; a user only needs to login once
during a Sparrow Web session unless assuming the authorization of another user name is
required in order to comp
lete some Sparrow Web editing operations.
The style of the Sparrow Web security access control lists is very similar to security in
the Java Servlet API specification. If you have configured security with web.xml before,
the Sparrow Web security system s
hould seem familiar.
Although the Sparrow Websecurity system is designed to work with Tomcat's security,
the user interface is currently not fully integrated. If you wish to control read access for a
page, you must edit your web.xml file manually. Also,
Tomcat requires that you restart
the server after adding or editing any read permissions. In future versions of Sparrow
Web, we are planning to provide further integration so that you will be able to set the
read permissions for a page from the Permission
s Panel (for more about the Permissions
Panel, see the Permissions button documentation in the Sparrow Web
Sparrow Web provides two levels of specifying access control: direc
tory and file. File
access controls apply to a specific file only. Directory access controls are more powerful
and allow you, the administrator, to quickly configure security on a site. However, as
access controls are very powerful, you must also be ver
y careful while setting them.
Directory access controls are similar to using a web.xml url
pattern with a '*' (e.g.
/directory/*). The permissions specified by a directory access control apply to all files
and subdirectories, unless specifically overridd
en. Directory access controls are
overridden by file access controls and directory access controls for subdirectories. For
example, if you specify directory access controls for /directory/, then those access
controls apply to /directory/page.html as well
However, if you set directory access controls for /directory/subdirectory/, then the access
controls for /directory/ will not apply.
Sparrow Web also provides two types of access control: writer and manager. Writer
access control specifies who can add and edit content on the Sparrow Web page. A user
with writer access will be able to modify content, but will not be able to modify the actual
structure of the page via the Control Panel. A user with manager access has
over the Sparrow Web page, including all of buttons on the Sparrow Web Control Panel.
First, there is a property in install_data.txt that governs TopGun security:
TOMCAT_SECURITY = enabled
to turn on TopGun security;
CURITY = 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
File level access control
o set the permissions for a Sparrow Web page, first load the Control Panel for that page,
then click on the button labelled 'Permissions.' This will load the Sparrow Web
Permissions Panel for that page. There are many ways in which you might wish to
gure a page:
Anybody can add/edit content and manage the page:
If you wish to allow full access to the Sparrow Web page to anyone, then delete
any permissions that appear on the page. Once you have deleted them all, the
page should state that both Write a
ccess and Manager access are 'unprotected,'
and that there are currently no permissions for the file.
Anybody can add/edit content on the page, protect manager
If you wish to only restrict manager
level access, then click on 'Add a user/group
select a user/group, and check only the 'Manager' checkbox. After you click 'OK,'
then that user will be the only user/group that will be allowed to manage the page.
If you continue to edit the permissions for this page, you will be asked to login (if
you are not already logged in as that user/group). The page should state that
Writer access is 'unprotected' and Manager access is 'protected.' You may add
additional users and groups (roles) to be managers of the page.
Fully protected access:
If you wi
sh to restrict all writer and manager accesses to a page, then make sure
that you have added user/groups, such that there is at least one 'Writer' and one
'Manager.' This can be the same user/group. Once you have done this, the
Sparrow Web Permissions Pan
el should state that both Writer access and
Manager access are 'protected.' You may add additional users and groups (roles)
to be writers and/or managers of the page.
Directory level access control
Directory access controls are configured first by loading
the Sparrow Web Permissions
Panel for a Sparrow Web page within that directory. Once you have loaded the panel,
click on the 'Up Level' button, which will take you to the Sparrow Web Permissions
Panel for that directory. From there you can either navigat
e further up the directory
hierarchy, or specify writer and manager access controls for that directory. Once those
permissions are set, they will be inherited by all subdirectories and files for which there is
no explicit setting of permissions.
An administrator needs to be familiar with the following configuration files. A
configuration file is any file that is customized to tailor the behavior of a particular
Sparrow Web site, not simply files whose extension is .conf.
ation files are:
web.xml and mimetypes.xml
The first group, comprising install_data.txt.template, install_data.txt, and sparrow.conf
are used to install or reinstal
l a Sparrow Web site. The use of these is described in
3.3 of the installation guide
. In brief:
install_data.txt.template is a human
readable file which is cus
tomized by the
administrator as the first step of the Sparrow Web installation. The file is self
documenting; each entry that needs a value from the administrator explains the
meaning of the value and gives sample values for each of the supported platform
install_data.txt is the file to which the customized version of
install_data.txt.template is saved after customization by the administrator. It is
specific customization of install_data.txt.template. Once install
exists, it will never be overwritten by subsequent installs or upgrades. However,
if additions or changes to install_data.txt.template occur in subsequent installs or
upgrades, install_data.txt will have to be edited by the administrator to refl
additions or changes.
sparrow.conf is a configuration file that is automatically generated when the
actual installation script, install.csh|bat, is executed. The installer reads
, along with other information it derives such as a hostname,
emits sparrow.conf. Although it is possible to edit sparrow.conf directly, as it is
also a human
readable file, we urge administrators not to do that. Instead,
changes to sparrow.conf are made
by editing install_data.txt and then executing
the reinstall.csh|bat script, which deletes any existing sparrow.conf and reruns the
core installation script.
The second group, comprising server.xml, tomcat_users.xml, web.xml are XML files that
the Tomcat web server and are used to customize server behavior and to setup
and administer user names, passwords, and user groups, called
mimetypes.xml is an auxilliary XML file supplied with Sparrow Webfor use within
ges to any of this group of files do not take effect until the Tomcat server is
There are many customizations possible within server.xml; we use only two, and
the defaults are acceptable. However, you may change:
Interceptor which may be used to suppress directory listings when no welcome
file is present:
==================== Interceptors ====================
static files and dirs. Set the
erty 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.
debug="0" suppress="false" />
and a Connector that changes the HTTP port on which the server listens:
==================== Connectors ====================
If you choose to run on a different HTTP port, you must edit install_data.txt to
reflect the changed port number. The port number should be 8000 or greater so
that the server may be run by an ordi
nary user. The server should not run as
UNIX ROOT or as a Windows Administrator.
See Appendix A: Basic Security with Tomcat 3.2.3,
3, in the installation
for details on editing server.x
tomcat_users.xml is an XML file in which user names, passwords, and groups,
called roles, are kept. The default content of tomcat_users.xml is:
<user name="tomcat" password="tomcat" roles="tomcat" />
<user name="role1" password="tomcat" roles="role1" />
<user name="both" password="tomcat" roles="tomcat,role1" />
If your Sparrow Web site is to have no authorization, e.g. no user names or
passwords, you can ignore this file. Howev
er, if you want to enforce
authorization and/or access control to Sparrow Web pages you use
tomcat_users.xml to create user names. Note that by convention each user name
is also a role with the same name, but you could have multiple users in one role:
user name="test1" password="tester1" roles="test1,testers" />
<user name="test2" password="tester2" roles="test2,testers" />
There are two drawbacks to the way this works: (1) passwords are stored in the
clear. This may be replaced by MD5 hash codin
g of passwords in subsequent
releases, and (2) the administrator must restart the server whenever this file is
See Appendix A: Basic Security with Tomcat 3.2.3,
1, in the install
for details on editing tomcat_users.xml.
INF/web.xml and mimetypes.xml
: there is a file named web.xml in each of several branches of the
Tomcat file tree. Since we install Sparrow Web under ROOT, the corre
web.xml to use is the one at
INF/web.xml. It’s default content is:
<?xml version="1.0" encoding="ISO
//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
However, when the Sparrow Web installation script is run for the first time, we
substitute the following content:
<?xml version="1.0" encoding="ISO
, Inc.//DTD Web Application 2.2//EN"
<!ENTITY mimetypes SYSTEM "mimetypes.xml">
include file mimetypes.xml
This directs web.xml to include mimetypes.xml w
ithin itself. mimetypes.xml is
an auxilliary XML file that contains the correspondences between MIME types
and document extensions, such as:
<extension> doc </extension>
type> application/msword </mime
<extension> ai </extension>
<extension> eps </extension>
<extension> ps </extension>
type> application/postscript </mime
You may add additional MIME types if needed. This file is needed because
particularly browsers on the Macintosh, do not have their own
MIME type information and must accept that information from the server. The
mimetypes.xml file allows Tomcat to provide that information to browsers by
keying on the extension of the file that
is being downloaded.
However, that is not the primary purpose of web.xml. web.xml holds the
authorization information that controls logging in and reading web files using the
See Appendix A: Basic Security with Tomcat 3.2.3,
2, in the installation
, for details on editing web.xml for Basic Authentication, and Appendix B:
TopGun Security with Tomcat 3.2.3,
1, in the ins
, for details
on editing web.xml for more sophisticated security.
The third group, comprising sparrowacl.xml and servermap.xml, are XML files that are
created during the initial installation of Sparrow. sparrowacl.xml extends the native
Tomcat authorization and access control for reading pages to authorization and access
control for writing and managing Sparrow Web pages; we call this extension the TopGun
TopGun uses a fi
le called sparrowacl.xml for specifying writer and manager
privileges for directories and files. File sparrowacl.xml must be located in the
same file directory as sparrow.conf; i.e.
The very first time you install Spar
row, a default sparrowacl.xml will be created
with content like:
Sparrow Access Control file
Modifying this file while Tomcat and Sparrow Web are running
may lead to lost changes. Please use the provided
user interfaces if possibl
The sparrowacl.xml file is read and modified by the permissions interface that
appears behind the Permissions button in the Control Panel of Sparrow Web
pages. Ordinarily, it should not be modified by hand. The Permissio
is documented in the Sparrow Web authors guide. In brief, there are three levels
of permission that may be assigned to a page or to a directory; the levels are
reader, writer, and manager. sparrowacl.xml controls only writer and manager
issions; the native reader control that comes with the Tomcat server and is
specified in file web.xml controls reading permissions. At the moment, the
Permissions interface only modifies the writer and manager permission levels that
appear in sparrowacl.x
ml. In a future release, managing web.xml for reading
permissions will also be done via the interface.
Here are some sample sparrowacl.xml entries that might go between the
test1, test2, testgroup, and manager3 are roles as defined in fi
The sparrowacl.xml file controls only writer and manager permissions.
INF/web.xml, described earlier,
is the standard Tomcat server authorization file for readers.
rver name="yourserver" domain="your.domain.name" port="8080">
Sparrow needs to both read and write HTML files
in that respect, it differs from
all other web servers that only read HTML files. servermap.xml tells the Sparrow
ystem how to convert URLs that reference Sparrow Web pages into file
names on the local/transparent file system on which the Sparrow Web server is
The very first time you install Sparrow Web a default servermap.xml will be
created, and automatica
lly generated entries for the Tomcat server will be entered
into the file. If you have no other web servers that will read Sparrow Web pages
into a browser at your site, the automatically generated file is all you need.
However, if you plan to have other
web servers, such as an Apache web server,
deliver Sparrow Web pages to your browser, then the Tomcat server must have
entries for all such servers in servermap.xml. servermap.xml contains its own
documentation describing the form and content of mapping
A default entry would look something like:
<server name="somename" domain="your.domain" type="tomcat" port="8080">
files names="index.html, index.htm, index.jsp"/>
map url="/" path="/opt/local/sparrow/jakarta
If you had a DocuShare server holding Sparrow Web pages, it would not have url
map entries but would look like:
<server name="comet" domain="parc.xerox.com" type="docushare"
config.xml must be located in the same file directory as sparrow.conf; i.e.
Sparrow uses a logging package called log4j. log
config.xml is a configuration
the log4j system. It needs to be present but should not need to be