Fedora™ Migration Utility Guide

Fedora™ Development Team

$Id: migration.dbx,v 1.0 2003/12/21 17:48:31 payette Exp $


Table of Contents

Introduction
Using Migration Utility to Upgrade from a Previous Version of Fedora:
Custom Migration: Export and Ingest via Command Line Utilities and API-M

Introduction

As of Fedora 1.2, a new utility for migrating objects is provided with the Fedora distribution package. This utility can be used to migrate digital objects from one Fedora repository to another. The migration utility has two functions: (1) migrating objects from an old repository to a new repository during the process of upgrading from a previous version of Fedora, and (2) moving and copying objects among Fedora repositories for other administrative purposes.

Using Migration Utility to Upgrade from a Previous Version of Fedora:

Although Fedora 1.2 is backward compatible with previous versions of Fedora at the interface definition level, there are changes to the underlying database schema that require digital objects to be migrated from an old Fedora installation to the new Fedora installation.

Upgrading is an easy task using the Migration Utility. The migration utility will export objects from an old Fedora repository and ingest them into the new Fedora repository. After migration, both the old and the new repositories will have copies of the objects. The migration utility does not purge objects from the old repository. It is up to the Fedora administrator to either purge objects from the old repository, or shut down the old Fedora repository after migration.

Note that the migration utility works with Fedora 1.1 and 1.1.1 repositories. If you are running Fedora 1.0 or earlier, you must first upgrade to Fedora 1.1 to be able to run the migration utility.

The steps for using the migration utility for a Fedora upgrade are:

1. Install Fedora 1.2.

The new Fedora release must be installed in a new location. See the Fedora Installation Guide for specific instructions.

Do not install Fedora 1.2 on top of your pre-existing Fedora installation. If you are installing Fedora 1.2 on the same machine as your pre-existing Fedora installation, make sure that the following configuration variables for the new Fedora 1.2 installation are different from those of the pre-existing installation:

  • $FEDORA_HOME environment variable: install Fedora 1.2 into a different directory than the previous installation

  • Initialize a new database: In Fedora 1.2 the database configuration scripts are set up with new defaults so you will create a new Fedora 1.2 database. If using MySQL, run mysql-config.bat (.sh for unix) with the new default database name of “fedora12” (or your own new database name that differs from the name used in your pre-existing Fedora installation. For McKoi, run the mkoi-init.bat (.sh for unix) which has a new default port number for Fedora 1.2.

  • fedoraServerPort: set a different port for Fedora 1.2 in the Fedora server configuation file (fedora.fcfg)

  • fedoraShutdownPort: set a different shutdown port for Fedora 1.2

  • fedoraRedirectPort: set a different redirect port for Fedora 1.2 in the Fedora server configuation file (fedora.fcfg)

  • object_store_base: set a different storage path for digital objects in the Fedora server configuation file (fedora.fcfg)

  • datastream_store_base: set a different storage path for datastreams in the Fedora server configuation file (fedora.fcfg)

  • temp_store_base: set a different storage path for temporary files in the Fedora server configuation file (fedora.fcfg)

  • retainPIDs: to set the Fedora 1.2 repository to accept PIDs from the old repository, modify retainPIDs in Fedora server configuration file (fedora.fcfg) to include the PID namepace(s) of the old repository

  • if the OLD Fedora installation is running on a different machine, modify the Fedora serverconfiguration file of the OLD Fedora installation to allow requests to be made by the new Fedora 1.2 repository (i.e, add the IP address of the new Fedora 1.2 repository to allowHosts.)

2. Start the new Fedora 1.2 repository.

Make sure you have set the retainPIDs variable in the Fedora server configuration file to contain the PID namespace(s) used in the old repository. This will tell the Fedora 1.2 repository to accept the pre-existing PIDs of the objects in your pre-existing Fedora repository. If you do not set retainPIDs with the old repository namespace(s), the new Fedora 1.2 repository will assign NEW PIDs to the migrated objects.

3. Run the Migration Utility.

The migration utility is launched via the File/Ingest menu. Within this menu there are options to ingest “From Repository.” This is where the migration utility functionality gets kicked off. When Ingesting “From Repository” the Fedora Adminstrator client will connect to the old repository you specify, initiate an export of objects from that repository, and ingest the objects into the new repository. A status report will be displayed when the task is complete.

  • Start the Fedora Administrator client for Fedora 1.2.

    navigate to the $FEDORA_HOME/client/bin directory

    fedora-admin [hostname] [port] [user] [pass]

    For example, fedora-admin localhost 8080 fedoraAdmin fedoraAdmin will start the GUI for a server running on the local machine, port 8080, where "fedoraAdmin"has been used both as the name and password of the server administrator.

    New to the 1.2 release of Fedora is the authentication dialog. When you start Fedora Administrator, you will be asked to choose the server to which you wish to connect and your username and password. The server and username fields are pre-populated and the password is validated using values from fedora.fcfg

  • File/Ingest/One_Object/From_Repository…

    To migrate a single object from an old repository, select the File/Ingest/One_Object/From_Repository menu item.

    You will be presented with a dialog box to enter the host and port of the source repository from which you want to migrate objects (i.e., your old Fedora installation). Enter the information to establish a connection to the source repository. Enter the hostname:port, username, and password.

    When a connection has been established to the old Fedora repository, you will be prompted to enter the PID of the object you wish to migrate from the old repository to the new repository. Click OK, and the object will be migrated.

  • File/Ingest/Objects_By_Type/From_Repository…

    To migrate all objects or a group of objects from an old repository, select the File/Ingest/Objects_By_Type/From_Repository menu item.

    When this menu item is selected, you will mass-migrate objects from the old repository to the new repository. You are provided the option to migrate objects by the three type of Fedora digital object (data objects, behavior definition objects, and behavior mechanism objects). You can select all types, or specific types to be migrated.

    First, you will be presented with a dialog box to enter the host and port of the source repository from which you want to migrate objects (i.e., your old Fedora installation). Enter the information to establish a connection to the source repository. Enter the hostname:port, username, and password.

    When a connection has been established to the old Fedora repository, you will be presented with a dialog box to select the types of objects you want to migrate into the new repository. Check all or some of the types. If your intent is to migrate all the objects from your old repository, SELECT ALL THREE TYPES to be sure that you migrate the behavior definition and behavior mechanism objects that your data objects are dependent on!!Clicking OK initiates migration of all objects of that type from the source repository into the new repository. You will see a status report when the process is complete.

4. Confirm Status.

When the migration process is complete, objects will still exist in the source repository (i.e., your old repository), and you will have ingested new copies of the objects into your new repository. If you configured your new repository to accept the PIDs of the old repository, objects in the new repository will have their original PIDs. Otherwise, they will have been assigned new PIDs when they were ingested into the new repository.

Be sure to review the status report after migration. The report will list the number of objects ingested (migrated) and will report the PIDs of any objects that failed.

5. Shutdown Old Repository.

To complete the migration task, you should shut down your old Fedora repository. If you plan to permanently disable the old repository, you can drop the SQL database for the old repository, and delete the directories that store the XML files for the old repository (the paths are defined in the variables object_store_base, datastreams_store_base, and temp_store_base in the Fedora server configuration file for the old repository).

6. Update Host and Port of New Repository.

To maintain persistence of the base URL for your Fedora repository, you should change the new repository configuration to use the hostname and port number that the old repository was running on. To do this, stop the new Fedora 1.2 server. Modify fedoraServerHost and fedoraServerPort in the Fedora server configuration file (fedora.fcfg) to the values that were configured in the old repository. Then, re-start the Fedora 1.2 repository. This will prevent breakage of URLs that were established during the tenure of the old repository.

Custom Migration: Export and Ingest via Command Line Utilities and API-M

It is possible to build your own migration utilities using command line utilities provided with Fedora, or by writing clients that make calls via API-M. There are two command line utilities that can be used together to perform migration tasks: fedora-export and fedora-ingest. Please refer to the Fedora Command Line Utilities Guide for instructions on how to use these command line functions. Also, refer to the API-M interface definition (WSDL) for the binding syntax for invoking the Export and Ingest operations via SOAP.