This tutorial will walk through the whole Jigsaw configuration process. It only assumes that you have unpacked the distribution, it will then take you through the following steps:
It is recommended, however, that before reading this tutorial, you read the brief overview of Jigsaw architecture.
Jigsaw distribution comes with a sample root directory. The very first thing to do, is to check that it runs properly in this directory, for this purpose, just run the following command (it should work on any platform that supports Java):
java w3c.jigsaw.httpd.http -host host -port port -root root
You should substitute (see Jigsaw command line page for more informations):
.../Jigsaw/Jigsaw
)
If everything runs smoothly, then Jigsaw will print the following message:
loading properties from: /afs/w3.org/usr/abaird/Jigsaw/config/httpd.props [httpd]: listening at:http://www24.w3.org:8888
Meaning that the server is ready, and listening at the given URL. If things do not run as nicely, here are a list of possible hints:
w3c.jigsaw.http.httpd
, this means that your CLASSPATH environment
variable is not set correctly. Be sure to include in this variable the
.../Jigsaw/src/classes
directory (were the ...
stands for the absolute path of the directory in which you have unpacked
the distribution).
-root
command line toggle.
We are now assuming that Jigsaw is running in its sample root directory. If you want to run Jigsaw in some other place then its sample root directory, you just need to copy it to the appropriate location (using a recursive copy program, so that you get the sub-directories too).
The sample root directory provides a set of resources (located in the
Admin
directory) that allows you to configure entierly the server.
As this directory doesn't come protected by default, you should continue
to read this tutorial until you have protected it (you can jump directly
to the authentication section, but it is
recommended that you keep reading until reaching it).
Tired of writing all these command line arguments when running Jigsaw ? In this section, we will explain how to edit the server global configuration, which will allow you to save your default settings.
Point your favorite browser to /Admin/PropertiesEditor
. This
brings up a form, containing a number of fields. Below are three more links:
Connections, Logging, Shuffler, which respectively allows
you to customize connection parameters, logging parameters and the (optional)
native data shuffler. For each of the field, you can follow the link to get
some documentation about its semantics.
At this stage, the first thing you want to do, is to save the actual settings:
the command line flags all end up modifying the properties, so what you see
is the correct set of properties (since you have provided the appropriate
command line flags, e.g. -host
, -port
, etc.), but
these are not consistent with the default property files. Save the properties
by clicking the Save button. You can now play around, and change your
settings as needed.
Note that some settings require a server restart (e.g. changing the server's port number). In such cases, you will be notified of the need of a server restart through an appropriate message. You need not (and shouldn't) save the properties before restarting the server (so that you can check them before actually saving them), however, once the server has restarted, and if you find these settings convenient, then you should save them by going back to the properties editor, and clicking the Save button.
Let's say, for example, that you want to turn the server in trace mode. You will first modify the server's trace flag to true, then go to the connections parameter, and turn the connection trace flag to true too. Don't save the properties yet, but restart the server. During its restart the server will first emit a message saying that it has shutdown itself, and then emit a second message saying that it has initialized itself. The server now runs in trace mode (i.e. it will display requests and replies). If you want this change to be persistent (i.e. always run the server in trace mode), then go back to the properties editor, and Save the properties.
In some cases, after you change some properties, the server won't be able to restart (because the new settings are inconsistent). In this case, just restart the server manually (through the command line): this will make it read its settings from the unchanged properties.
At this point, Jigsaw should be running, and its global configuration
should be up to date. You may want to check that everything is fine by visiting
some of the documents under the Jigsaw space directory (the
WWW
directory by default). You can read the documentation, for
example, starting from /User/Overview.html
.
This section will explain how you can declare
new file extensions (the usual AddType
directive of servers),
and how you can create directory templates
.
To export any piece of information, Jigsaw wraps it into an HTTPResource object (see Jigsaw resource factory documentation for more informations on this). This resource factory maintains a database to keep track of how files should be wrapped into resources. This database, known as the extensions database describe, for each extension, a (optional) mapping to some resource class, along with a set of default attribute values for the newly created resource that will encapsulate the file.
Let's say we want all files having the png
extension, to be
exported by a
FileResource
instance (the FileResource class is the class that knows how to send back
files as reply to requests). We also want to state that the
content-type
attribute value for these file resources should
be image/x-png. We first point our favorite browser to
/Admin/Extensions
, this displays the sorted list of registered
extensions. What we want to do is to add a new extension, so we click on
the AddExtension link. This brings up a new form, asking us for an
extension name, and for an (optional) class. We fill in the name of the extension
(png
, without the leading dot), and the extension class
(w3c.jigsaw.resources.FileResource
), and then press the
OK button. This brings up yet another form, which allows us to enter
default attribute values for resources that will be created through this
extension. We want to specify the content-type
, so we fill this
field with image/x-png, and - just for fun - we may want the default
icon for theses resources to be image.gif, so we fill in this field
too. We then press the OK button, which brings us back to the list
of extensions (in which the new png
extension has been inserted).
If you have a .png
file under Jigsaw space directory,
you can now query it: the resource factory will now how to wrap into a
FileResource, and will send it back to you properly.
In some cases, you may just want to state that for all files having a particular
extensions, some specific attribute should default to some specific value.
A typicall example of this is to state that files having the .fr
extension have been written in french. To handle such a case, we just follow
the above procedure: we follow the AddExtension link, and fill in
the name of the extension (fr
here), however, this time, we
will leave the class name empty. This means that by itself, the
fr
extension will not cause a file to be exported, but if
a file having the fr
extension is to be exported (because, for
example, it has both the fr
and html
extensions),
then we are willing to provide some default values for some of its generic
attributes. We press the OK button to register the extension, this
brings up a form containing the generic attributes (i.e. attribute tha apply
to all
HTTPResource
instances). We just fill in the content-language
field, stating
that its value should be fr, then we press the OK button, which
brings us back to the list of registered extensions (in which fr
has been inserted).
You should now be able to register as many extensions as you want. You should also check that the default extensions meet your expectations, by carefully viewing them. You may also want to remove some of the default extensions, or the one we have created above. To delete an extension, go to the page displaying the list of registered extensions, mark the ones you want to unregister by clicking on the checkbox at their right, and press the OK button.
At this point, you might be surprised that we haven't save any of
our changes. Jigsaw uses a complex caching scheme, and it decides
itself when it is best to save changes to disk. However, you should remember
that because of this, the server should be killed only by getting
the /Admin/Exit
resource (which will shutdown the server properly,
saving to disk what needs to be saved at this point).
The previous section has explained how to map files to resources based on their extensions. This section now explains how to map directories to resources.
As for files, mapping directories to resources is done by the resource factory, however the mapping is done per directories name, rather then per extensions. Directory templates are records that described how directories of a given name should be mapped to resource instances. The first rule to be aware of, is that if no directory templates is available for a specific directory, the file-system directory will be exported through a simple DirectoryResource instance.
Back to directory templates. Directory templates associate a directory name
with a resource class along with a set of default attribute values for the
directory. Directory templates may be of two kinds: they can be
generic or normal (depending on the value of their
generic
attribute). Generic directory templates apply to all
directories having, as part of their path, the directory template name, while
normal directory templates apply only to directory whose last name is the
template name. Generic directory templates allows you to use some specific
directory resource to export a whole hierarchy of information.
To access the directory templates database, point your favorite browser to
/Admin/DirectoryTemplates
. This will list the currently defined
directory templates. Let's add a new directory template, for all
CVS
directories, which we want to export through the
CvsDirectoryResource
(this resource provides a form-based interface to CVS). To do this, we follow
the AddDirectory link, which brings up a form that prompts us for
a directory name and a directory class. We want this directory template to
apply to all CVS
directory, so the name is just
CVS
, and we want these directories to be exported through a
w3c.jigsaw.cvs.CvsDirectoryResource
instance. We fill in the
fields, and press the OK button, this brings up a new form, with the
templates attribute themselves. We don't want this directory template to
be generic, so we leave these fields alone. The ShadowedAttributes
link brings up a form to edit the default attribute values for the resource
to be created. The fields in this form depends on the class you have given
when you created the directory template. In the case of the
CvsDirectoryResource,
none of these attributes need default values, so we just skip them. We are
all set, now when the resource factory will be queried to wrap a directory
whose name is CVS
, instead of creating a directory resource,
it will create a resource that will allow you to control the cvs status of
the files in the directory, neat isn't it ?
Another typical usage of directory templates, is to use them to provide writable
areas. The
PutableDirectory
class extends the basic
DirectoryResource
class with the ability to create new resources to handle the HTTP PUT
method (a bunch of browsers now support this PUT method, you can try for
example Amaya, or
GNN). Let's define
a directory template for some directory named Writable
and all
its children directories. As before, we click on the AddDirectory
link, the name of our directory template is simply Writable
and its associated class is
w3c.jigsaw.resources.PutableDirectory
. We press the OK
button, and this time, we state that the template is generic, by setting
the generic attribute to true. This time we want to edit the
ShadowedAttributes so we follow the link. The first thing we may want
to do is to provide a fancy default icon, so that putable directories can
be distinguished from the others, lets' use burst.gif
, then
if using GNN, you might want to turn the browsable
attribute
to true. This will make the resource handles the GNN specific
BROWSE method. We press the OK button, and we are done. Don't
forget to read the authentication section, that will explain how to setup
authentication for these kinds of directories.
At some point, you may want to delete directory templates. In this case,
go to the /Admin/DirectoryTemplates
location, and mark each
of the templates you want to delete by clicking on the checkbox to the right
of their names. Then press the OK button, you are done.
At this point, you should be able to run Jigsaw, to configure its properties and to edit the resource factory configuration databases. In this section, we will concentrate on Jigsaw's ability to edit existing resources.
In some circumstances, you may want to customize a single resource of your whole information space. This may be because you want it to have a specific icon, or because it's a special resource that needs some specific configuration, etc.
Just for fun, let's say that although the document
/User/Overview.html
has the html
extension, we
want its content type to be advertized as text. To do this, what is needed
is to edit the content-type
attribute of the appropriate resource
in order to change it into text/plain. Jigsaw comes
with a generic resource editor (which is itself a resource), that allows
you to edit any specific resource exported by the server. To edit a resource,
we just append its path to the /Admin/Editor
resource. So, to
edit our /User/Overview.html
resource, we just point our browser
to /Admin/Editor/User/Overview.html
. This brings up a form
containing the specific attributes of the resource. The one we are interested
in, here, is its content-type
that we change to
text/plain. We press the OK button, et voila ! Try loading
/User/Overview.html
: instead of displaying the HTML document
itself, your browser should now display the HTML text making the document.
Enough fun, let's turn the resource content-type
to
text/html, and check that the resource is back to normal...good !
All resources are editable in the same way, again for fun only, let's say
we want to add the
ThreadStat
resource (which display the threads running in the server) into the
/User
directory resource. To do this, we launch the generic
editor on the /User
directory, by pointing our browser to
/Admin/Editor/User
location. This brings up a form with one
field per directory resource attribute. This time, what we want to do is
to add a resource, so we go straight down the page, and follow the
AddingResource link. We are prompted for a resource name, and a resource
class. The name of the resource is the name under which it will be retreived
from its directory, let's use threads
. The full class name of
the ThreadStat resource is w3c.jigsaw.status.ThhreadStat
. We
fill in the two fields, and press the OK button. Then we follow the
ExistingResources link. This shows up a sorted list of all the resources
contained by the /User
directory resource, among which is the
threads
resource. Follow threads link, this pops up an
editor to edit the ThreadStat resource attributes. You may want to change
the refresh rate, by changing the value of the refresh
attribute
(which gives the refresh period in seconds). Press the OK button.
Now point your browser to /User/threads
, and you will see the
threads that the server is running.
Now that we got all this fun, its time to do some clean-up, let's remove
the threads
resource from the /User
directory resource.
Point your browser to the /Admin/Editor/User
location. Mark
the threads
resource by clicking on the checkbox right to its
name, select the Remove
command and press the OK
button. By the way, the Reindex
button here, will reindex the
marked resources (this is usefull if you change your resource factory
configuration), and the Update
button will update any of the
resource attributes that is computed.
At this point, you nearly knows everything about Jigsaw. This section will provide you wit ha basic explanation of filters, and how to use them to setup authentication.
Resource filters are attached to specific resources in order to filter accesses to them. These filters are called once at lookup time, and once at reply time. On the way in (lookup time), they allow you to manipulate the request before the target resource handles it, and on the way out, they allow you to manipulate the target's reply before it is emited back to the browser.
Although Jigsaw provides a number of filters, we will focus here on the authentication filter, that authenticate requests before thy are handled by their appropriate target resources. The GenericAuthFilter is currently the only available authentication filter.
To illustrate its usage, we will go through the steps required to protect
the /Admin
directory. The first thing you want to do, is to
define an authentication realm. An authentication realm is a database
that will contain the description of a set of users, along with their passwords
and/or IP adresses. Let's first define an admin
authentication
realm, describing all the users allowed to access the /Admin
resources.For this we point our favorite browser to
/Admin/Realms
. This display the set of authentication realms
the server knows about (this will be empty at this time). Let's create our
realm: we click on the AddRealm link, which brings up a form prompting
us for the realm name (the server wide identifier for the realm), and the
realm repository. Let's fill in the realm name with
admin
. The realm repository is the name of the file that the
server will use to store the users database for the realm, it's good practice
to put these files under the config/auth
directory of
Jigsaw. So we fill in the repository field with
.../config/auth/admin.db
(were ...
is to be substituted
by the absolute path of the root directory of the server). Once both fields
are filled in, we press the OK button to create the realm. This brings
up a form containing the list of users defined in the realm (which is, of
course, initially empty). We follow the AddUser link, which prompts
us for a user name. Let's say that admin
is the user we want
to describe. We fill in the name, and press the OK button, this again
brings up new form, prompting us for a bunch of informations about the
admin
user. The email address is currently unused (but it might
be used in the future for email notification), you can iethre fill it of
leave it empty. You can type in any comments in the comments field which
is used only for informational purposes. The ipaddress field allows you to
state from which machine the user is allowed to connect. This field is not
mandatory: if left blank, only the password will be used for authentication
(be warned that the password authentication scheme used by HTTP is very weak,
for protecting such a critic space as the Admin
space, you should
always specify both a password and some IP addresses). If you decide to fill
in the ipaddress field, you can enter multiple addresses for the same user
(one per line). In my case, I fill it with my office IP address and my home
IP address, so I enter the following two lines of text:
18.52.0.144 18.23.1.195
You can also use * in the ip address field, meaning that any user
connecting from the given set of IP addresses is to be authentified as the
admin
user. We then enter some password, and any optional groups
we want the user to belong to (groups are a way of tagging a set of users
belonging to the same realm, we will see some sample usage of groups below).
Once all the fields are filled-in, we press the OK button: the
admin
user is now registered as part of the admin
realm. You can define as much users as you want, by following these same
instructions.
Once you are satisfied with your realm, it is time to actually protect the
/Admin
directory. For this purpose we launch the generic resource
editor on the /Admin
resource by pointing our browser to
/Admin/Editor/Admin
location. What we want to do is add the
authentication filter as one of the filters for the /Admin
resource:
we click on the AddFilter link, and enter the following filter class:
w3c.jigsaw.auth.GenericAuthFilter
. We press the OK button
to register the filter, this add two new links to the editor: let's follow
the w3c.jigsaw.auth.GenericAuthFilter link. This pops up a form-based
editor to edit the filter's attributes. The first identifier field need not
be filled in, you can just skip it. The method field allow you to describe
what methods are to be protected. As the /Admin
is such a critic
resource, we want to protect it against any method, which is the default
when the field is left blank (otherwise, we would specify one method per
line). The realm name field must be filled in: it should give the identifier
of the realm we want to use for authenticating the /Admin
space.
We use here the realm that we have created above: admin
. The
users field allows you to restrict access further to only a set of users
in the realm, and the group field allows you to restrict access to a set
of groups of the realm. In both cases you should enter one user name (or
group name) per line. If left blank, all users within the realm will be allowed
in (which is what we want since we have defined a specific realm to describe
the users that are allowed to configure the server). We can now press on
the OK button: the /Admin
directory is now protected.
To check this, just point your browser to /Admin
, this should
now prompt you for a user name, and a password.
You are now all set: Jigsaw is configured, enjoy !
Anselm Baird-Smith
$Id: configuration.html,v 1.1 1996/04/17 22:49:35 abaird Exp $