This documentation refers to an earlier version of Islandora. is current.

This chapter will show you how to install and configure the Islandora module and servlet filter.

Pre-installation software checklist

The Islandora framework relies upon a number of other open source applications. Before beginning the installation of any Islandora modules, ensure:

1. You have Drupal installed and properly configured with:

  • Clean URLs enabled
  • The Drupal file system set to public*
    *Note: Currently, only Drupal 6.xx is supported by Islandora and it must be running on PHP 5.2 at a minimum.

2. You have Fedora installed and properly configured:

  • Ensure you can use the admin tools in Fedora to ingest and purge (e.g. http://localhost:8080/fedora/admin).
  • A requirement for collection objects: To make the module more flexible and useful we have also made some specific decisions regarding our Fedora objects. For the module to be able to browse collections, your collection objects must have a hasModel entry in the RELS-EXT Datastream that points to islandora:collectionCModel. This lets the module know that the object represents a collection and it will then query for objects that are members of this collection.

3. Other requirements beyond what is needed by Fedora and Drupal include:

  • PHP5-curl
  • PHP-soap
  • PHP5-xsl

You will also need to install any dependencies that are needed for the Solution Packs you are using.

To take full advantage of the module you will need to enable the Fedora Resource Index in the Fedora config file.  You should also have Fedora GSearch installed, although this step does not need to be completed prior to installing the Module and Servlet Filter. Fedora GSearch includes Lucene and enables full text searching.

At the end of this installation, you will be ready to populate your site with digital assets and be capable of accepting Solution Packs.

Drupal Servlet Filter

The Drupal Servlet Filter allows the Fedora Repository to use Drupal’s database for authentication, including integration with Drupal user roles.

1. Download the Latest Version of the Drupal Servlet Filter

Download the Drupal Filter files from the Release Notes and Downloads page. Extract the contents of the archive, and make sure you choose the correct JAR file for a) your version of Fedora and b) your authentication type (FeSL or legacy).

 This is a choice that you made during the Fedora installation checklist. If you have used the default config and installation file provided in in our Installing Fedora page, you are using legacy authentication.

Place the JAR file in $FEDORA_HOME/tomcat/webapps/fedora/WEB-INF/lib

.  Note: This directory will not exist on your system until Fedora has been run at least once.

If your Drupal and Fedora installations use different database types, Fedora will require the Drupal database driver's jar file in this directory as well. For instance, if Fedora uses PostgreSQL and Drupal uses MySQL, Fedora will require the MySQL jar file for the Drupal Servlet Filter in order to connect to the Drupal database.

For Fedora 3.6.x, try this filter provided by Peter Murray

2. Make the Fedora Repository Aware of the New Filter

Follow the instructions for either a) Legacy Authentication, or b) FeSL Authentication:

a. If using Legacy Authentication

New XML elements must be added in order to configure Fedora's servlet filtering.

Edit the web.xml file located in $FEDORA_HOME/tomcat/webapps/fedora/WEB-INF/ to include a reference to the Drupal Servlet Filter. Immediately after the <filter> element named XmlUserfileFilter, insert the following:


Then, immediately after the <filter-mapping> element named XmlUserfileFilter, insert the following:


b. If using FeSL Authentication

Edit the file jaas.conf located in $FEDORA_HOME/server/config/ to allow the Drupal Servlet Filter to authenticate against Drupal’s database. 

Insert the following reference to the DrupalServlet filters class files:

{ required
ca.upei.roblib.fedora.servletfilter.DrupalAuthModule required

3. Configure the Drupal Servlet Filter

Create the file filter-drupal.xml in $FEDORA_HOME/server/config. Copy the following text as a template, then modify the attributes of the <connection>  tag to match the server, port, database name, username and password of your site's Drupal database.

Fedora requires a separate <connection> entry for each connecting Drupal site.

<?xml version="1.0" encoding="UTF-8"?>
<!--File to hold drupal connection info for the FilterDrupal servlet filter.  For multisite drupal installs you can include multiple
connection elements.  We will query all the databases and assume any user in any drupal db with the same username and password are the same
user.  We will gather all roles for that user from all databases.  This is a potential security risk if a user in one drupal db has the same
username and password as another user in a separate drupaldb.  We are also assuming all drupal dbs to be mysql.  This file should be located
in the same directory as the fedora.cfcg file-->

  <connection server="localhost" dbname="drupaldb" user="dbuser" password="password" port="3306">
                  <!--Different sql statement for each connection.  This is for drupal multisites that are setup using one database with
                  table prefixes.  We don't do this but some people might.-->
                  SELECT DISTINCT u.uid AS userid, AS Name, u.pass AS Pass, AS Role FROM (users u LEFT JOIN users_roles ON
                  u.uid=users_roles.uid) LEFT JOIN role r ON r.rid=users_roles.rid WHERE AND u.pass=?;

If you use the Drupal servlet filter to connect to multiple Drupal databases there is potential for users with the same username in each database to access each others private objects. To avoid this, use the Drupal LDAP module. A Drupal multi-site environment utilizing the LDAP module for all sites ensures a unique username/site configuration.

The Drupal Filter does not currently escape the database url before attempting to connect to the Mysql database, which can cause problems if the user name or password has '%' symbol within it.

4. Stop and Restart Fedora

This will enable the Drupal Servlet Filter.

5. Test the Drupal Servlet Filter

Access your Fedora Admin client ( using your Drupal login credentials (the username and password you would use to log into your Drpual site as a user).

In the Fedora log in, you will need to offer the MD5 hash of your Drupal user's password (rather than the plaintext password). You can use the following Linux command to get this MD5 hash:

echo -n "yourpassword" | md5sum

The Islandora Module

The Islandora module is a Drupal module written to allow the Drupal content management system to act as a front end to a Fedora Digital Repository. The module enables viewing and management of Fedora objects. This includes ingest, purge, add Datastream, searching and browsing by collection. This version of the module does not store any data regarding any of the Fedora Objects in the Drupal database. The only data stored in Drupal is the configuration data telling Drupal how to connect to Fedora.

How to Install the Islandora Module

  1. Download the latest versions of the following required modules and place the uncompressed contents of the module in your sites/all/modules or the sites/default/modules directory. For multi-site Drupal environments, refer to the instructions:
    1. From
      1. ImageAPI
      2. jQuery Update
      3. jQuery UI
    2. From Islandora:
      1. Content Model Forms
      2. Objective Forms
      3. PHP Lib
      4. Tabs
      5. XML Forms (Package includes the following modules)
        • XML Form API
        • XML Form Builder
        • XML Form Elements
        • XML Schema API
  2. Download the latest version of the Islandora module and place the uncompressed contents of the module in your sites/all/modules or the sites/default/modules directory.
  3. Enable the module by logging in to Drupal and navigating to Administer > Modules. Locate and enable the Islandora Repository module. 
  4. Navigate to 'Islandora Configure' under Administer > Site Configuration.
  5. Click the 'Install' button under 'Islandora Core' to create the islandora:root and islandora:collectionCModel Fedora objects. 

You have now enabled the Islandora module. Navigate to your newly created Digital Repository menu item to view the objects from your Fedora Repository through your web site.

How to Configure the Islandora Module

Major configuration options for the Islandora module are available on the Islandora Configuration page under Administer > Site configuration > Islandora Configure (/admin/settings/fedora_repository)

Tabs Configuration

Allows you to customize the tabs available when viewing Fedora objects, and how they will display.

  1. Determine whether or not to allow users (with proper permissions) to view the Object Details tab (containing datastreams for that object.)
  2. Configure how objects details will be displayed. Please note that as a nested scheme, MODS does not display well in a Table format.

Advanced configuration options

Additional options for advanced users. More most installations the default settings do not need to be altered.

Troubleshooting Configuration

If you encounter problems with your Islandora configuration, check the following:

  1. Your Fedora connection information is correct: The Fedora URLs in the Islandora Configure panel  should point to your Fedora server's IP or domain name. Note: You may experience connection issues if you specify 'localhost' instead of the IP address of your Fedora server. Therefore, we recommend using the actual IP address of the server.
  2. You have the appropriate user permissions to determine who can do what to Fedora objects from within Drupal.
  3. Your Lucene index is set to the index name configured in GSearch, if GSearch has been installed and enabled. 

If you specify an IP address other than localhost in your Islandora configuration you will need to delete the following Fedora policies:

  • deny-apim-if-not-localhost.xml 
  • deny-reloadPolicies-if-not-localhost.xml

These policies can usually be found in /usr/local/fedora/data/fedora-xacml-policies/repository-policies/default

The Fedora Default Display Object PID and Fedora Datastream ID are the defaults used by Drupal when it can't find a PID/Datastream.  Ensure these point to an object/Datastream that is known to exist in your Fedora repository. So, for example, you could use an image that will communicate to your users that the object they are looking for was not found, or is not available. Remember that only the PID namespaces permitted in the Islandora module's config pages will be visible to users of a given site. 

Developer Tip: You can always retrieve the most up-to-date information via our git repository at However, the most stable release of Islandora will always be available at
  • No labels


  1. When testing the Drupal filter by attempting to login to the Fedora Administrator interface using your Drupal credentials, I believe you need to offer the MD5 hash of your Drupal user's password rather than the plaintext password itself.  

    1. Thanks for pointing this out, Zachary.

      If you're on Linux, you can get the md5 hash for your Drupal password with this command:

      echo "yourpassword" | md5sum
      Such a hash will only work until Islandora is based on Drupal 6, as Drupal 7 uses a different hash generation mechanism.

      1. I have updated this page with a note regarding the MD5 hash. Thanks!

        1. Turns out echo "yourpassword" | md5sum doesn't work because it pipes a

          "trailing newline" to md5sum.

          The correct command is echo -n "yourpassword" | md5sum

          1. Thanks, Bhaskar - I've made the change.

  2. The package for soap on ubuntu is actually php-soap, not php5-soap

    1. Thanks Jonathan - I've updated the list of requirements.

  3. The Link for the Drupal Servlet Filters (e.g. seems to deliver corrupt jar files. After some googling I found via\!msg/islandora/pNUOjeHdmCg/bdUheqFzMzwJ an alternative link at, which seems to work.

    1. The link you posted ( is not a download link for the JAR file; rather it is a link to the GitHub page for fcrepo-drupalauthfilter-3.4.2.jar. From there you can click the 'raw' link to get the file itself. This is the same link you posted at the end of your message (

      So if you right-clicked the first link and downloaded it you would just get a bunch of HTML (which would result in a corrupt JAR file as you reported). This is a bit confusing, so I will update the documentation to be more specific about how to download the JAR file.

  4. Re "*Note: Currently, only Drupal 6.xx is supported by Islandora and it must be running on PHP 5.2 at a minimum." :

    Debian 5's repositories come with PHP5.2.6 (

    However, this version causes a very nasty "Namespace error", when creating new objects from Islandora. The only place this issue seems to be mentioned is

    Debian Lenny users can retrieve newer PHP packages (v 5.3.9) from

    Instructions at:

  5. Since paste cannot be used to enter the password into the Fedora Admin interface, is there another option aside from manually entering the output of md5sum to test authn configuration?

    1. I tried pasting a password into the Fedora Admin interface and it worked. Can you test again to see if it will work for you? If not, please post your OS and browser name/version and I'll test using the same configuration.

      1. Accessing fedora/admin with Firefox through X Window (remotely from my Mac) at localhost on a vm running Red Hat 6.1. Thanks.

  6. The logrotate file in this directory implements log rotation for Tomcat, Fedora, FedoraGsearch and Djatoka(if logging to Fedora's log dir):

  7. Perhaps the suggestion to have GSearch installed is a bit premature? It's mentioned in the pre-installation checklist. I admit, I'm a n00b at this, but I wasted considerable time struggling to install it (the wrong version, naturally), not realizing the installation/config directions are on the next page. I suspect others might make the same mistake. 

  8. Where this page discusses editing the web.xml file to add a <filter-mapping> for DrupalFilter, it states:

    "Then, immediately after the <filter-mapping> element named XmlUserfileFilter, insert the following:"

    Unfortunately, my copy of web.xml does not have a <filter-mapping> element named XMLUserfileFilter.

    So instead, I just found where the other <filter-mapping> elements are and added the DrupalFilter mapping at the beginning of the list. If that doesn't work, I'll try putting it somewhere else.

    The instructions may need to be revised.