Table of Contents

  1. Introduction
  2. fedora-setup
  3. fedora-start
  4. fedora-stop
  5. fedora-rebuild
  6. fedora-reload-policies
  7. validate-policy
  8. mckoi-init
  9. mckoi-start
  10. mckoi-stop
  11. mysql-config
  12. mysql-drop-db

Introduction

The Fedora server distribution comes with several command-line utilities that can be used to start and stop the Fedora server and to control the operation of that server. Some of these will be used by a site's repository administrator fairly regularly, while others may only rarely or never be needed. A description and usage instructions for each follows.

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. Additionally there are many other issues involved in initially setting up a Fedora repository these are explained in the command-line 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).

 


fedora-setup

Before the Fedora server is started you must run the Fedora setup utility to put a security configuration in place.  See the guide for Securing Your Fedora Repository for a full discussion of the four configuration options.   To select your base security configuration, run the "fedora-setup" command-line utility.  This utility requires a single argument which is the name of the base security configuration you wish to use.

 

 Under Windows:

    %FEDORA_HOME%\server\bin\fedora-setup configuration-name

 

 Under Unix:

    $FEDORA_HOME/server/bin/fedora-setup configuration-name

 

The valid values for configuration-name include:

The fedora-setup utility initializes one of the four base security configurations by copying a set of configuration files into the distribution tree.  The contents of these configuration files will vary depending on the base security configuration selected.  The resultant functionalities of the four possible base security configurations are described in more detail below.   You can rerun the Fedora setup utility at any time to change your repository configuration.   Just stop the server, run fedora-setup, and restart the server.   The setup utility automatically puts an appropriate version of the three necessary Fedora configuration files into play:

 

fedora.fcfg - Fedora server configuration file

web.xml - Fedora Tomcat web application configuration file; controls whether basic authentication and SSL are enabled for API-M and API-A

beSecurity.xml - Fedora backend services configuration file; controls security for services calling back to Fedora (see beSecurity Configuration document for details)



fedora-start

fedora-start

or

fedora-start mckoi

or

fedora-start oracle

Where:

Example:

fedora-start

Note: Before starting the Fedora server, a decision about what security configuration to use needs to be made (see fedora-setup) and several decisions need to be made pertaining to the overall setup of the fedora-server need to be made, (see the Fedora Installation and Configuration Guide) and the database that is to be used in conjunction with the Fedora server (either MySql or McKoi or some other custom solution) needs to be started and initialized.




fedora-stop

fedora-stop

This command is used to cleanly stop the Fedora server. This might need to be done when the configuration of the server is changed or to prevent all access to the repository while certain systems administration tasks are performed, or to run the program fedora-rebuild listed below.




fedora-rebuild

fedora-rebuild

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 it is running) using fedora-stop.
  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. (using fedora-start)


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

  1. Stop the Fedora server (if it is running) using fedora-stop.
  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. (using fedora-start)
     

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 it is running) using fedora-stop.
  2. Delete the existing MySQL database used by Fedora. (using the mysql-drop-db command).
  3. Re-configure the database for Fedora (using mysql-config)
  4. Run fedora-rebuild to re-populate SQL database tables used by the Fedora server with the correct information (select menu option '2')
  5. Run fedora-rebuild again to re-construct the Resource Index files and the Resource Index tables in the SQL database (select menu option '1')
  6. Restart the Fedora server. (using fedora-start)





fedora-reload-policies

fedora-reload-policies

One of the main features added to version 2.1 of Fedora is improvements in access security (as described in the document [link to Bill's doc]) This access security is specified using XACML files which detail what persons or groups are allowed to perform various actions to the repository. 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 only 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 all of the repository-wide policies. The alternative to using this command is to stop the Fedora server, and restart it.




validate-policy

validate-policy [policyFilename]

Where:

One of the main features added to version 2.1 of Fedora is improvements in access security (as described in the document [link to Bill's doc]) This access security is specified using XACML files which detail what persons or groups are allowed to perform various given actions to the repository. If the Fedora server administrator creates a new XACML policy to broaden the existing access policies or to more tightly restrict access, the newly created policy should be run through this program to ensure that the XACML policy is well-formed before attempting to install it in the Fedora server.





mckoi-init

mckoi-init [fedoraDBUser] [fedoraDBPass]

Where:

Example:

mckoi-init fedoraAdmin fedoraAdmin

Initializes the McKoi database so that it can be used by the Fedora server. After it is initialized (which generally only needs to be done once) you will need to start the McKoi database with the mckoi-start command listed below.




mckoi-start

mckoi-start

The mckoi-start command is used to start the McKoi database, after it has been initialized via the mckoi-init command. Note that if you are using the McKoi database this command must be performed before the Fedora server is started. Also note that if you choose to use the MySQL database, or any other database system, this command is not needed.




mckoi-stop

mckoi-stop [fedoraDBUser] [fedoraDBPass]

Where:

The mckoi-stop command is used to stop the McKoi database, after it has been started via the mckoi-start command. Note that if you are using the McKoi database this command must be performed after the Fedora server is stopped. Also note that if you choose to use the MySQL database, or any other database system, this command is not needed.





mysql-config

mysql-config [installDir] [dbaUser] [dbaPass] [fedoraDBUser] [fedoraDBPass] [dbName] [mysql41_flag]

Where:

The mysql-config command line builds all of the necessary tables within the MySQL database so that the Fedora server can be run using MySQL as its backing store. If you plan to use the McKoi database, this command is not necessary.




mysql-drop-db

mysql-drop-db [installDir] [dbaUser] [dbaPass] [dbName]

Where:

This command can be used to delete all of the database tables used by the Fedora server. It might be needed if the database gets corrupted, as described above for the command fedora-rebuild.