===========================================================
=     ARKEIA V4 TO V5 MIGRATION PROCEDURE READ ME         =
=                                                         =
=     This file is the READ ME for the migration          =
=     procedure from Arkeia v4.2.x to Arkeia v5.          =
=                                                         =
=     Version 0.2B        released on 2002-09-10          =
=                                                         =
=     Copyright (c) 2002 by Arkeia Corporation,           =
=                 All Rights Reserved.                    =
=                                                         =
===========================================================


===========================================================
=                       WARNING!!                         =
===========================================================
= PLEASE NOTE:                                            =
=                                                         =
= While Arkeia Corporation has tried to provide a         =
= complete and fairly "safe" migration procedure for its  =
= products, the reader should be aware that this          =
= procedure can have potentially very destructive effects =
= on existing Arkeia v4.2.x servers.                      =
=                                                         =
= ARKEIA CORPORATION RECOMMENDS THAT THIS FILE IS READ    =
= AND FULLY UNDERSTOOD BEFORE ATTEMPTING THE MIGRATION    =
= PROCEDURE ITSELF.                                       =
=                                                         =
= FURTHERMORE, ARKEIA CORPORATION DISCLAIM ANY LIABILITY  =
= FOR THE LOSS OF DATA RESULTING FROM THE USE OF THIS     =
= PROCEDURE.  EXCEPT WHEN OTHERWISE STATED IN WRITING     =
= ARKEIA CORP AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS= 
= IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR   =
= IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED     =
= WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A         =
= PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY   =
= AND PERFORMANCE OF THE PROGRAM IS WITH YOU.             =
===========================================================
=                       WARNING!!                         =
===========================================================



TABLE OF CONTENTS
=================

	1.	What is the migration procedure?
	2.	Obtaining the migration procedure.
	3.	Running the migration procedure on a server.

		3.0	Keep a copy of the v4.0 configuration.
		3.1	Required operations before migration.
		3.2	Install Arkeia version 5.
		3.3	Running the migration.
		3.4	Tasks performed by the migration.
		3.5	Required operations after migration.
		3.6	Testing the migrated information.

	4.	Running the migration procedure on a client.

	5.	Known problems and issues.

	6.	How to obtain help on the migration procedure.


1. What is the migration procedure?
===================================

The Arkeia migration procedure is designed to ease the transition
from Arkeia 4 to Arkeia 5.

This procedure is designed to transfer as many information and
configuration parameters as possible, in order to allow all system
administrators to transfer their existing v4.2.x configuration to
the new architecture of Arkeia v5.

Applying the migration procedure to an existing Arkeia v4.2.x
server allows the administrator to transfer the following
information to the Arkeia v5 server:

	-- Tape and Tape Pool configuration.

	-- Backup device (drive/library) configuration.

	-- User configuration.

	-- Backup information (EXCEPT "Periodic" backups).

	-- Database, backup history and index.
	   (These items are necessary for restorations).

	-- Partial network configuration.

PLEASE NOTE:

As was briefly noted above, the migration procedure detailed
above applies only to Arkeia servers. For more information on
the best way to transfer a v4.2.x client machine to Arkeia v5,
please read the section 4 (below) of this document.

PLEASE NOTE (2):

At the time of this writing, the migration procedure has been
tested on Linux ONLY. We are currently testing a migration 
procedure for Sun Solaris. A migration procedure for other
UNIX (and non-UNIX) operating systems should appear shortly.
Please refer to the Arkeia Corp. web site (http://www.arkeia.com)
for more information on the availability of these procedures.


2. Obtaining the migration procedure.
=====================================

It is possible to obtain the Arkeia migration procedure 
from the following sources:

	The Arkeia Corporation web site, at the following
	URL:

	http://www.arkeia.com

	The Arkeia v5 CD-ROM distribution also contains
	the migration procedure. It can be found in the
	following directory:
	
	/opt/arkeia/bin/migration
	
	This procedure is installed by default along with
	the Arkeia server.
	
	For more information, please refer to the rest of
	this document.

PLEASE NOTE:

The Arkeia v4.2 license should be upgraded to an Arkeia
v5.0 license or the migration procedure will not be able
to work properly. Please contact the Arkeia Sales Team
for more information.


3. Running the migration procedure on an Arkeia server.
=======================================================

3.0 Keep a copy of the Arkeia v4.2 configuration

If you have made some changes to the configuration of
your Arkeia v4.2 machine, make sure you keep a copy
of these modifications!

Some modifications may not be taken into account by the
migration procedure from the v4.2 to Arkeia v5.

3.1 Required operations before the migration.

The following operations should ALWAYS performed BEFORE
attempting the migration of an Arkeia v4.2.x server to an
Arkeia v5:

* Stop all the Arkeia v4.2.x processes:

	(a) Stop all backup/restore operations.

	(b) Stop the "mdl" library processes.

	(c) Quit the Arkeia v4.2.x GUI. (No "odts" processes
	    should be left running)

	(d) Stop the "nlservd" process by entering
	    the command "NLSERVD stop".

	(e) Remove the "ARKPER" entry in the root crontab.

* Rename the Arkeia directory and make a backup:

	(a) The Arkeia v4.2.x directory should be renamed from:

		/usr/knox

	    to (for instance):

	    	/usr/knox-4.2

	(b) Make a complete backup of this directory to a tape
	    in order to keep a copy of the Arkeia database and
	    index, if necessary.
	    
PLEASE NOTE:

Performing these operations BEFORE the migration procedure
itself is launched is absolutely CRUCIAL to the success of
the overall migration. IF YOU DO NOT PERFORM THESE STEPS,
THE MIGRATION PROCEDURE MAY FAIL AND ALL YOUR PREVIOUS
BACKUP DATA COULD BE LOST!!

* Un-install Arkeia v4.2.x (RPM ONLY):

If you have used RPM packages to install Arkeia v4.2.x,
please un-install Arkeia version 4.x with the following
commands (entered as root):

	rpm -e --justdb arkeia-server
	rpm -e --justdb arkeia-client
	rpm -e --justdb arkeia-gui
	rpm -e --justdb arkeia-arkc

PLEASE NOTE (2):

If you have installed the Arkeia v4.2.x using the "tar.gz"
package, you can safely disregard the above note. HOWEVER,
if you have used an RPM package, using the commands indicated
above is MANDATORY. Any other "rpm" command may well fail
or delete important files that are required by the migration

3.2 Install Arkeia v5 (RPM ONLY):

Install the Arkeia v5 software by entering the following
command as root:

	rpm -Uvh arkeia-5.0.2-1.i386.rpm

PLEASE NOTE (3):

The exact name of the RPM file to be installed may be
different from the example given above. If you are 
using the "tar.gz" package, just install Arkeia by
using the procedure detailed in the Arkeia v5 PDF
documentation.

Once the installation has been completed on your system,
don't forget the step indicated below!

* Stop Arkeia v5:

Arkeia version 5 must be stopped BEFORE the migration
procedure can be started. To do this, enter the command
indicated below as root:

	/opt/arkeia/bin/arkboot stop

Check that all the Arkeia processes have been stopped
by entering the following command as root:

	ps -faxuw | grep ark

3.3 Running the migration procedure.

To run the migration procedure, simply enter the following
command as root:

	/opt/arkeia/bin/migration/arkmigrate

The following options must be supplied on the command line:

	--oldname [VALUE]	Arkeia v4.2.x server name.

	--fqdn    [VALUE]	Arkeia v5 FQDN server name.

	--path42  [VALUE]	Arkeia v4.2.x root directory.
				(For instance: /usr/knox).
	--path50  [VALUE]	Arkeia v5 root directory.
				(For instance: /opt/arkeia).

For instance, the following command, entered as root, would
perform a valid migration from the Arkeia v4.2.x "foobar" to the
new Arkeia v5 "foobar.acme.com":

	/opt/arkeia/bin/migration/arkmigrate
	--oldname foobar --fqdn foobar.acme.com
	--path42 /usr/knox-4.2
	--path50 /opt/arkeia

(For readability reasons, the options appear on different
lines -- they should, of course, be entered on the same 
line as the command itself).

The migration procedure performs automatically.
Follow the instructions printed on the screen to complete
the migration.

3.4 Tasks performed by the migration procedure.

The "arkmigrate" procedure does the following:

	-- Make a backup copy of the v5 database directory
	   for reference.

	-- Copy and change the v4.2 /usr/knox/nlp configuration
	   files in the appropriate v5 directory (/opt/arkeia/arkeiad).

	-- Copy and change the Arkeia v4.2.x dbase/f3 directories
	   (EXCEPT for the Periodic backup configuration).

	-- Copy and rename the Arkeia journal.

	-- Change the backup server name to its FQDN value.
	   For instance: server "foobar" becomes "foobar.acme.com".

	-- Migrate the v4.2.x index to reflect the v5 structure.

PLEASE NOTE: 

The Arkeia v5 index is actually a symbolic link to the v4.2.x
index, which is kept in its original directory (Please
refer to section 3.1, above, for more information). A
backup copy of the v4.2.x index should be made BEFORE launching
the arkmigrate procedure, since it will deeply modify the
index to put it into the v5 index format.

Keeping a backup of the original allows you to roll back
the v5 installation to the previous v4.2.x installation if
need be.

Arkeia Corporation recommends you to test the Arkeia v5
server using the migrated information (see section 3.6
below). If the server seems to be working correctly, the
converted index can be moved and the symbolic link:

	/opt/arkeia/server/dbase/o3dbtree

should be updated to reflect this change.	

PLEASE NOTE (2):

A complete log of the operations of the arkmigrate procedure
is kept in the following file:

	/opt/arkeia/log/arkmigrate.log

If, for any reason, the migration procedure fails to perform
correctly, it should be restarted from the very beginning,
meaning a backup of the v4.2.x index and a new installation of
Arkeia version 5. If the migration procedure fails, please
contact the Arkeia Technical Support for more information.
(Refer to section 6, below, for more information).

3.5 Tasks to be performed after the migration:

Do not forget to install the v5 license using the Arkeia
GUI (Graphical User Interface).

As noted above, the Arkeia v5 should be restarted and tested
thoroughly. The index, if correct, can then be moved from its
original directory to another location IF the symbolic link is
updated accordingly.

The entire Periodic Backup configuration should be done again,
but the Arkeia v5 GUI makes this operation much easier.

3.6 Testing the migrated information.

Arkeia Corporation recommends to test the Arkeia v5 server
using the migrated information. To do this, follow the 
steps below:

	-- Library inventory:

	   Exchange two tapes within a library, then stop and
	   restart the library processes and check that Arkeia
	   v5 reflects the changes you have just made.

	-- Restoration from v4.2 tapes:

	   Check that you can restore files from tapes that were
	   created with Arkeia version 4.2.

	-- New backup/restore using the Arkeia v5 server:

	   Perform a small backup and restoration operation using
	   the migrated Arkeia version 5 backup server.


4. Running the migration procedure on a client machine.
=======================================================

There is no need to migrate immediately the client to Arkeia
version 5: an Arkeia version 5 server is backward-compatible
and can backup and restore data to v4.2.x clients.

However, it is recommended to migrate the clients to version
5 as soon as possible.

To do this:

	-- Stop Arkeia v4.2.x on the client machines.
	
	-- Make a backup copy of the configuration files.
	
	-- Un-install Arkeia v4.2.x.
	
	-- Install Arkeia v5.

	-- Make sure that the admin.cfg file contains the
	   FQDN name of the backup server.
	
	-- Restart Arkeia ("arkeiad" on UNIX machines,
	   or "Arkeia Service" on Windows machines).

	-- On the Arkeia server, stop the library processes
	   with the following commands (entered as root):

	   /opt/arkeia/bin/arkboot stop

	-- Once the library processes are stopped on the
	   Arkeia server, make sure the FQDN names for
	   the upgraded clients is correct by entering
	   the following command as root:

	   /opt/arkeia/bin/migration/arkmvhost --allhosts
	   (to upgrade ALL modified clients)

	   /opt/arkeia/bin/migration/arkmvhost --host old_name --newhost new_name

	   (to upgrade the client "old_name" to "new_name")

	-- Once the FQDN name has been verified, restart
	   the library processes on the Arkeia server,
	   with:

	   /opt/arkeia/bin/arkboot start

PLEASE NOTE:

You will find a complete description of the arkmvhost command
in the Arkeia User Manual. Typing this command without arguments
displays the 0 options that it can accept.


5. Known problems and issues.
=============================

The following problems and issues are known to exist with
the current version of the migration procedure:

"arkmigrate" does not take into account the configuration
of the Periodic backups. Arkeia Corporation recommends to
re-configure the Periodic backups under Arkeia version 5,
and to start a new cycle of Periodic backups with a new
"Total" backup. Please refer to the Arkeia version 5
documentation for more information.

In the case of Windows or Novell clients, "arkmigrate"
only takes into account the "normal" files, and not 
special files such as the Novell NDS or the Windows
Registry. It is possible to backup these files through
the Arkeia v5 plug-ins. Please contact Arkeia Corp.
for more information.

Special network configurations for the v4.2.x version, 
such as:

	-- Arkeia servers with several network cards.

	-- Backups through firewalls.

	-- Backups through proxies.

are NOT migrated by "arkmigrate". These configurations
should be completely re-done. Please contact the Arkeia
Technical Support Team for more information.

At the time of this writing, the Arkeia v5.0.3 GUI does
NOT support the "roles" configuration. This could be a
problem if several different users and roles have been
defined on (migrated) Arkeia v4.2.x server.

PLEASE NOTE:

The tape types should not be modified, UNLESS these
modifications have been specifically recommended by
the Arkeia Technical Support Team. You'll find below
a short list of all the tape changes recommended by
the Technical Support for Arkeia version 4.2:

	-- In the file named "f3drv/drvtypes.lst":

	   AIT-2 drive: variable tape block size.
	   LTO drive: 1024 tape block size (This value is
	   the new default for Arkeia version 5).

	-- In the file named "f3tape/tptypes.lst":

	   AIT-2 drive: enter the property "USE_CAPACITY".
	   Create a new "FILE" tape type with a size of 1000MB.

	-- In the file named "f3lib/libtypes":

	   Enter the property "LOCK_STK" to prevent inventory 
	   problems with some Autoloaders.

	   Increase the number of slots in the "FILE" library.

If you have ANY problem with the configurations detailed
above, please contact the Arkeia Technical Support Team.


6. Obtaining help on the migration procedure.
=============================================

For any and all problems and issues regarding the migration
procedure from Arkeia v4.2.x to Arkeia v5, please contact the
Arkeia Technical Support Team. The web page for the Technical
Support Team is:

http://www.arkeia.com/support.html

Thank you for using Arkeia version 5. We hope this migration
procedure will be useful to you!


						Arkeia Corp.

