=========================================================== = 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.