Environment
Retain 3 and 4 Moving from Linux to Windows
Situation
How do you move Retain on Linux to a new server on Windows?
Resolution
DISCLAIMER:
This knowledge base (KB) article is provided for informational purposes only and as a courtesy service to you, our customer. GWAVA Technical Support does not have any database administration (DBA) expertise, nor does it provide DBA services or support. GWAVA is not responsible for the results of implementing any of the concepts contained in this KB article. Implementation of any of the concepts suggested in this KB article shall be done entirely at your own and sole risk, and GWAVA does not provide any kind of warranties whatsoever resulting from your decision of implementing any of the KB article’s concepts. It is up to you to do any research and to ensure yourself that any implementation and setup of any of the KB article’s concepts in your database system is correctly and properly executed. It is imperative that you have backups of your database system and storage directory before making any implementation. If you don’t have any DBA expertise, you should consult with a DBA expert before any implementation of the KB article’s concepts. Under no circumstances, shall GWAVA, or any of its employees, be liable, in contract, tort, delict or otherwise, whether negligence is provable or not, for any direct, indirect, incidental, special, punitive, consequential or other damages, loss, cost or liability whatsoever that would result from or are related to the implementation of any of the concepts suggested in the KB article.
To the extent permitted by applicable law, GWAVA shall not be liable to you for any special, consequential, direct, indirect or similar damages, including any loss of data, arising out from migrating any type of messages, attachments, database, metadata in your Retain system to another server and/or location.
Resolution:
The easiest method is to re-install everything to the new server and then copy over the archive and configuration files.
These instructions are for moving Retain and maintaining its current version. If your current version of Retain is 2.x and you wish to upgrade afterwards (highly recommended), follow the instructions in the KB article, "Upgrade: Retain 2.x to Retain 3.x (Windows)".
Synopsis
In order to move Retain there are 3 things that are not optional that MUST be moved. These will be discussed in further detail in the rest of the article:
1. Configuration files.
Move the ASConfig.cfg, which is stored in a directory off of your Retain installation:
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg
Indexer configuration files (the entire directory's contents):
Linux default: /opt/beginfinite/retain/RetainServer/WEB-INF/solrweb/WEB-INF/cfg
Windows default: [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\solrweb\WEB-INF\cfg
2. Database.
Unless it's on a separate server from the Retain server and you are not wanting to move it.
3. Storage.
In summary, here are the storage directories to be copied:
- archive (required)
- backup (optional, although we recommend you skip this since having it on the old server is backup enough until the next Retain maintenance performs a backup on he new server)
- ebdb (optional)
- export (optional)
- index (required f Retain 4, recommended for Retain 3)
- license (optional)
- xml (optional)
*Note: If you've added storage partitions in the Retain admin web interface, you will need to make sure all of those are copied correctly, too.
Preparation
1. Make a note of where your Retain storage directory is located.
To determine what that directory is, log into the RetainServer web interface and click on Server Configuration | Storage. The "Base Storage path" is your Retain storage directory.
2. Download Retain to the new server and prepare it for the installation.
a. Prepare the download directory.
We recommend creating a directory called Software on the root of the drive. It is not required and you may store the installation files wherever you desire, but if you do not have a strong preference, storing it at [drive]:\Software makes it easier to find later, especially for technical support.
b. Download the latest version of Retain on the new server. For Retain 2.x customers, you'll first want to migrate your data to Retain 3.x format first; then proceed with moving Retain.
c. Unzip the file, allowing Windows to create a new subdirectory off of "Software" with the same name as the zip file.
For example, if the zip file were named, "Retain4031ga_48.zip", Windows - by default - will create a subdirectory called "Retain4031ga_48", so that the full path to the installation files becomes [drive]:\Software\Retain4031ga_48.
3. (Optional) Configure NFS Services on the new Windows server if you want to use Support's Retain Auxilliary Tool Set utility to copy your Retain storage to your new server.
4. Install/Configure IIS on the new server.
5. (Optional) If you have edited the default properties files under the Retain Worker directory(ies) (.../RetainWorker/classes/config) such as attachment.properties or errors.properties, you may want to back up those files to restore them after the final step of the move.
Moving Retain
1. Disable archive all archive jobs, and if applicable, deletion jobs on the old server.
2. For good measure, shut down Tomcat on the old server.
3. Move the database if it resides on the Retain server; otherwise, proceed to step #4.
For customers using MySQL, reference "Moving MySQL Database to Another Server".
4. Copy the Retain storage directory from the old server to the new server (see step #1 under the "Preparation" section for the location of this directory). WARNING: This step can take days or weeks depending on volume.
Because the Windows server is using NTFS as the disk format and Linux something different (ext3, xfs, etc), you'll need to employ an approach where the data on these two distinct disk formats can be read from and written to by the same process.
We recommend that you install NFS services on the new Windows server, share the new storage directories, and mount from the old Linux server to the new shared storage directories.
Once that is done, you can now use rsync to copy the files from Retain storage directory on LInux to the new Windows server. To help with this process, you may download and install Support's utility for copying the archive directory.
5. Install Retain on the new server.
*DO NOT log into the WEB UI at this point, you could damage the database data that you've just moved.
6. Shut down Tomcat on the new server.
7. Copy the configuration files from the old server to the new server and edit the paths referenced in those files to reflect their new locations:
a. ASConfig.cfg, located in [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg.
b. Edit the ASConfig.cfg and change several parameters to reflect the storage paths on the new server. Or, you can start tomcat, logon to the Retain Server web admin console, and change the paths under Server Configuration | Storage. If editing the ASConfig.cfg directly, look for these parameters for the storage paths:
- <basepath>
- <archivePath>
- <xmlPath>
- <indexPath>
- <backupPath>
- <licensePath>
- <EBDBPath>
- <exportPath>
c. RETAIN 4 ONLY:
1) Edit the path the index directory to reflect its new loation by opening the zoo.cfg file in ...\index\solrhome\
2) Copy everything from [drive]:\RetainServer\WEB-INF\solrweb\WEBINF\cfg.
8. Start Tomcat on the new server.
9. Login to the Retain Server web admin console.
10. Replace the existing Worker object. This is for systems where the Worker is on the Retain server or for situations where jobs won't start after moving Retain:
a. Create a new worker object.
b. Download the bootstrap file.
c. Edit all jobs assigned to the old worker and re-assign them to the new one.
e. Delete the old worker object.
f. Restart tomcat.
g. From a web browser, go to the RetainWorker and upload the new bootstrap.
http://[Retain server IP]/RetainWorker
11. If you backed up any of the Retain Worker properties files (see step #5 under the Preparation section), restore those to their respective directories. This does not apply to most customers - this is very rarely done.