Using GNU-Paperclips

GNU-Paperclips is a versatile piece of software. We have tried to include here as much information as possible, inevitably there will be bugs we have missed and features that we've forgotten.
 

    Running Paperclips
    Using the Admin Tool
    Adding a servlet to the engine
    Administering a servlet
    Serializing the engine
    Restore the engine
    Using an AuthenticationProvider
    Console Logging

Running Paperclips

<Top
 

Using the built in Administration Servlet

By default the admin tool is bound to the uri-path: /paperclips

If you request the admin tool page from GNU-Paperclips you will get the GNU-Paperclips copy-left statement along with some other information. This info is held within the GNU-Paperclips Java classes and changes only with releases.

If you make a request for the admin page followed by the path /resourcelist (eg: /paperclips/resourcelist) you will get the main administration page which might look like this:
 
 
 
 
 

<Top
 

Adding a Servlet

Here are the steps to add a new servlet to GNU-Paperclips:

1. Start the server with the correct classpath

- the CLASSPATH variable in the shell will allow you to specify a classpath to the Java VM that runs GNU-Paperclips
2. Visit the administration page
   - use the browser to open the following URL on the GNU-Paperclips host: /paperclips/resourcelist
3. Enter the path you wish to bind the servlet against
   - for file based servlets you enter the do and then the file postfix eg: for a JSP servlet you might enter .jsp
   - for a path based servlet you enter the full path which the servlet will be bound to: eg: /somepath
4. Click on the Create button to view the resource configuration form
5. Enter the Filterpath if you require one (see Filters for more information)
6. Enter in the Servlet field the classname of the servlet you wish to use.
7. Enter in the New-parameter-name and New-parameter-value fields the name and value of any servlet init parameter that you wish to supply to the servlet.
   - if a servlet requires init parameters it will tell you in the documentation, for example GNUJSP requires a parameter named scratchdir.
8. Press the Save button
   - this will save the existing parameters, you will see that any init parameter values that you have entered will appear in the list of parameters as a single name:value field, rather than being assigned to the New-parameter-name and New-parameter-value fields.
9. Enter further init parameters by adding the names and value to New-parameter-name and New-parameter-value, then clicking on Save, until you have added all the init parameters you need to supply to the servlet.
10. Click on Load and the servlet will be loaded and bound to the specified resource path.

Administering a Servlet

Reloading

Changing parameters

Setting the filter

<Top
 

Serializing the engine

This serialization is a complete serialization, any servlets loaded in the engine will have their full state serialized.

To serliaze your configuration for future reload.....

Note: information about the server environment is NOT saved. Specifically the number of threads the server is using and the TCP port it is running on are not saved. This is so that when the information is restored the server need not be shut down.

<Top
 

Restore the engine

<Top
 

Using an AuthenticationProvider

GNU-Paperclips has a concept of authentication providers. These are filters that can be used to provide authentication for other servlets. When the authentication provider has been added as a filter to a servlet the servlet can only be accessed by people in the desired role.
 

Ensuring you have an authentication provider loaded

However, if a filter is written to wrap up the authentication system for a parituclar provider then any servlet can be given authentication by adding the filter to the servlet.

GNU-Paperclips comes with a basic authentication filter called BasicAuthentServlet. If this servlet has a mapping in your engine's resources list then it is loaded and can be used to filter other servlets.

Setting an authentication provider filter for a Servlet

By default BasicAuthentServlet is mapped to the path /auth so we will use that as an example.

1. For the servlet you want select the servlet's administration page from the resourcelist.
2. change the servlet's filter to /auth?Realm=realmadmin
3. click on reload

Adding users on the BasicAuthenticator

role: realmadmin
user: admin
password: secret

If the servlet is mapped to the default path of /auth then either open the web page:

http://servlet-engine-host-address/auth

This will display a list of users in realmadmin, clicking on any one of the users allows you to add a new user or update or delete the user you have clicked on.

The checkbox realmadmin shown on the user screen is a realm checkbox.

One of these should appear for every realm on your system (see next section).
 

Adding a role on the BasicAuthenticator

Serialisation and AuthenticationProviders

This allows developers to do deliver servlets with little or no security restrictions or hardcoded info and for engine administrators to add the information when needed.

The only trouble is that when the servlet engine code is updated it will be impossible to get back the servlet engine registry. We are currently trying to work out ways in which the Authentication Provider stuff could be pulled out and stored in a seperate file for later import into any version of GNU-Paperclips.

<Top
 

Console Logging

<Top