Table of Contents

  1. Introduction
  2. fedora-rebuild
  3. fedora-reload-policies
  4. validate-policy

Introduction

The Fedora server distribution comes with several useful command-line utilities. A description and usage instructions for each follows.

The scripts are located in FEDORA_HOME/server/bin/. In Windows, these commands resolve to batch files (.bat); in Unix, they resolve to shell scripts (.sh).

This guide assumes you have correctly installed the Fedora server distribution as per the install guide, including having set up your PATH and FEDORA_HOME appropriately.


NOTE: Currently, if you are running Fedora with a servlet container other than Tomcat, these scripts will need to be manually modified for your environment to pick up the paths to the Fedora classes and required libraries from a location other than CATALINA_HOME.


fedora-rebuild

Reconstitutes Fedora's indexes (the Resource Index and/or the SQL database) from the FOXML and datastream files on disk.

In case of corruption or failure of the repository, the Fedora Rebuild utility can completely rebuild the repository by crawling the digital object XML source files that are stored on disk.

The fedora-rebuild command launches the interactive Fedora Rebuild utility that restores the repository if it somehow became corrupted. Symptoms of repository corruption include underlying indexes or registries becoming unusable, or the server refusing to start. The components of the repository that can become corrupted are the SQL relational database and the RDF triplestore that underlie the Fedora repository service. The SQL database (e.g., MySQL, McKoi, or Oracle) contains a set of registries, as well as metadata to enable simple searching of the repository, and a cache of digital object profiles to speed up API-A access to the repository. The triplestore contains RDF triples for key properties of digital objects, datastreams, disseminations, and relationships to create an RDF-based index of the repository (used for more advanced RDF-based searching).

In prior versions of Fedora, under some circumstances the SQL relational database component could become corrupt, which would then require the entire repository to be deleted and all of the digital objects in the repository to be manually re-ingested. The Fedora Rebuild utility allows the repository administrator to merely purge the database used by the Fedora server, and re-configure the database (using either mysql-config or mckoi-init) and then run the Fedora Rebuild utility to restore the repository to a rational, usable state. Additionally, if the administrator wants to change the underlying database system (e.g., change from McKoi to MySQL database, or MySQL to Oracle), the existing database can be purged, the Fedora Configuration File (fedora.fcfg) can be edited, and the Fedora Rebuild utility can then be run to correctly populate the tables in the new database system.

Similarly, if the Resource Index becomes corrupted or the Resource Index triplestore files are deleted from disk, then the Fedora Rebuild utility can be used to completely rebuild the Resource Index and bring it back to its desired state. The Fedora Rebuild utility can also be used to rebuild the Resource Index whenever the indexing level is changed in the Fedora Server Configuration file (see: fedora.fcfg). A rebuild of the Resource Index will recreate the triplestore itself, and also populate utility tables in the SQL database component of Fedora.


NOTE: There are some circumstances in which both an SQL rebuild and a Resource Index rebuild must be run.


Although the Resource Index is primarily stored in the triplestore that configured with Fedora, it also stores some information in relational database tables (in the same SQL database used by the rest of the Fedora server). For example, if the SQL database becomes severely corrupted such that the entire database needs to be deleted, or if the Fedora administrator plans to switch from using one database system to another, the Fedora Rebuild utility will have to be run twice. Once for an SQL Rebuild to recreate and repopulate the tables in the SQL database used by the main portion of the Fedora server. Then a second time as a Resource Index rebuild to recreate the triplestore and repopulate the SQL tables used by the Resource Index.

When you run the Fedora Rebuild utility, a text menu appears, allowing you to specify whether you need to rebuild the SQL database or rebuild the resource index files. See below for step-by-step descriptions of how to use the rebuild tool in the various instances when it might be needed:

SQL Rebuild: If the tables in the SQL database used by the Fedora server are corrupted:

  1. Stop the Fedora server (if using Tomcat, this can be done with the shutdown.bat or shutdown.sh command)
  2. Run fedora-rebuild to re-populate SQL database tables used by the Fedora server with the correct information (select menu option '2')
  3. Restart the Fedora server (if using Tomcat, this can be done with the startup.bat or startup.sh command)

Resource Index Rebuild: If the Resource Index level is changed, or if the Resource Index is corrupted:

  1. Stop the Fedora server (if using Tomcat, this can be done with the shutdown.bat or shutdown.sh command)
  2. Run fedora-rebuild to re-construct the Resource Index files and the Resource Index tables in the SQL database (select menu option '1')
  3. Restart the Fedora server (if using Tomcat, this can be done with the startup.bat or startup.sh command)

Both: If SQL database becomes severely corrupted such that database is completely unusable, or if a different SQL database program or version is to be used.

  1. Stop the Fedora server (if using Tomcat, this can be done with the shutdown.bat or shutdown.sh command)
  2. Re-install or initialize the database as per the instructions in the Installation and Configuration Guide.
  3. Run fedora-rebuild to re-populate SQL database tables used by the Fedora server with the correct information (select menu option '2')
  4. Run fedora-rebuild again to re-construct the Resource Index files and the Resource Index tables in the SQL database (select menu option '1')
  5. Restart the Fedora server (if using Tomcat, this can be done with the startup.bat or startup.sh command)

fedora-reload-policies

Where:

Causes any new or changed repository-wide policies to take effect immediately on the running Fedora server.

As described in the document, Fedora Authorization with XACML Policy Enforcement, Fedora can be configured to enforce a variety of access policies. Many of these XACML policies are applied for all actions and access attempts peformed on the repository as a whole. These "repository-wide" XACML policies are automatically loaded at the time the Fedora server is started. If the Fedora server administrator needs to change one or more of these repository-wide policies, this command can be used to tell the running Fedora server to reload the policies. The alternative to using this command is to stop the Fedora server and restart it.

validate-policy

Where:

Schema-validates a XACML policy file.

If the Fedora server administrator creates or modifies an existing repository-wide XACML policy, the new policy should be run through this program to ensure that it is well-formed before attempting to install it in the Fedora server. Validating a policy in this way will ensure that it is well-formed XML and can follows the XACML XML schema.