From the 1.0alpha5 release of Jigsaw, the best way to configure the server is to use the graphical application named JigAdmin. The form-based configuration is still here but is no longer maintained.

This document has the following sections:

• How to start JigAdmin
• Security considerations
• Resources & Frames
• Indexers
• Filters
• Deletion and reindexation

How to start JigAdmin

For a quickstart, you should read this little Howto. The main command top start JigAdmin is:

    java org.w3c.jigadm.Main -root INSTDIR/Jigsaw/Jigsaw

(change the '/' in '\' for Windows boxes)

Security considerations

By default, Jigsaw comes with predefined usernames/password (admin/admin) for the administration server, and no protection on the Admin directory of the http server. If you care a little about your site, you must do the following:

1. Change the password of the administration server.
2. Put an authentification filter on the Admin directory of each server managed by the admin server.
   • Create an admin realm, if not already present.
     • Click on the "realm" leaf
     • Add a realm
     • Open the "realm" node
     • Click on the realm node you just created
     • Add one user and change its password (by default, there is no password)
   • Open the "space" node of the server
   • Click on the "Admin" directory
   • Click on the "Add an AuthFilter" icon
   • Set the realm of the filter to the realm you created
3. Save everything
   • Click on each "control" node
   • Click on the save button

If you really care about security, you can add IP filters to the AuthFilters set, you can do it in the attributes of the user entries in the administration realms.

On Unix, the best way is to run Jigsaw as root in a chrooted environment. Read the FAQ entry on chroot.

Resources & Frames

The Resources are the object exported by Jigsaw to the outside world. It can be the raw object, like text files or image files, or objects created on the fly, like servlets, cgi scripts, filtered resources. In Jigsaw-1.0, the resource was in charge of handling the HTTP requests, so the Resource has all the knowledge needed by HTTP. Since Jigsaw-2.0, the Resources are very basic and contains only the intrinsic knowledge of this resource. For file, you have the size, last modification date... The 2.0 Resources have protocol frames. Those frames are handling the different protocols used to fetch this particular resource.

There are two ways of configuring the resources, by adding directly a specific resource at a specific place, or by letting the indexers create the resource in the server hierarchy. Of course the manual tune can be used along with the indexers. That is the most common way to configure Jigsaw.

Indexers

An indexers, placed on a Container, will be in charge of creating its sons resources. It will create Resource of a special kind depending, for example, on the extension of the filename ("html" for an html page, "png" for a PNG image file....). Or place a specific indexer for cgi on a directory named "cgi-bin". In Jigsaw-2.0, the indexer is not only in charge of creating the resource, it has also to put the right protocol frames (and other frames if necessary) on the created resource.

An indexer have two main part:

1. The Directories.
2. The Extensions.

In the Directories, you have to specify how to index directories with a specific name. The default name is "*default*", in the default indexer the resource created is a DirectoryResource. In the 2.0 version, it creates a DirectoryResource with a default HTTPFrame.

In the extensions, you have to specify how to index files or leaf Resources. The default extension are mapped to FileResource, html, gif, png, txt... In the 2.0 version, an HTTPFrame is added to the Resource.

A tutorial about the setup of indexers is available, it helps understanding how it works.

Filters

The filters alters the resources, by requesting authentification for example. The filters are attached to the resource. In the 2.0 version the filters are atteched to the protocol frame of the resource rather than to the resource itself because many filtering scheme depends on the protocol used, the authentification in HTTP is very specific to HTTP  and can't be used in other protocols. The filters are called before and after serving the resource. You may have filters that are called only before the resource is served, like an authentification filter, or after, like a "find and replace" filter.

Deletion and reindexation

In the 1.0 versions of Jigsaw, the reindexation was not present, the only way to force it was to delete the resource. Of course, if there was a specific configuration (e.g, "hand-modified" Resources), it was lost. The 2.0 version solves this problem.

In the 2.0 version of JigAdmin, you will find, close to the "Delete Resource" button, a "Reindex Children" button. By doing this, it will verufy/create/delete all its children resources. It will save your special configurations and update and propagate the other changes.