Environment
Moving from Windows to Linux
Situation
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 in 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. Create the download directory.
- Make the directory for holding the software: md /software
- Change to that directory: cd /software
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
NOTE: You can use the wget command to download the software to the Linux server by changing into the software directory you created in step 2.a and running this command: wget '[url]'
1) Get the URL of the most current version of Retain from http://download.gwava.com/download.php?product=Retain&version=versions
2) Now use that URL with the wget command on the Linux server inside the software directory you created.
EXAMPLE: wget 'http://download.gwava.com/retain/Retain3510ga_362.zip'
c. Unzip the file and make the script files (.sh) executable.
1) unzip [retain zip file] -d [retain zip filename, excluding the ".zip" at the end]
Example: unzip Retain3510ga_262.zip -d retain3510ga262
The "-d" option causes it to create Note how we kept the "r" in lowercase follwing the "-d" option since Linux is case sensitive when changing directories.
2) chmod +x *.sh
3. Install Apache2 to the new server.
a. Launch YaST | Software Management.
b. In the search window, type: Apache2.
c. Click on Apache2 (only), click on the Accept button, and accept the defaults.
4. (Optional) If you have edited the default properties files under the .../RetainWorker/WEB-INF/classes/config, you may want to back up those files to restore them after the final step of the move. However, you could always access them from the original Retain server if needed.
Moving Retain
1. Disable 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 MySQL database if it resides on the Retain server; otherwise, proceed to step #4.
See: "Moving MySQL Database to Another Server".
4. Install Retain on the new server.
a. Change to your Retain software installation directory (i.e., /software/retain3510ga_262)
b. Execute the installation script: ./RetainInstall.sh
*****************************IMPORTANT**********************************
At a certain point of the installation, you will be presented the following prompt:
Will MySQL be running on the same server as Retain?
1) Yes
2) No <---- Select this option even if MySQL is running on the same server
Even if MySQL is running on the same server as Retain, type "2" for "No"; otherwise, it will attempt to install and configure MySQL. At this point, you have already installed MySQL and moved your MySQL database to this new server, so selecting option 1 will cause problems.
*DO NOT log into the WEB UI at this point, you could damage the database data that you've just moved.
c. Shut down Tomcat on the new server.
5. Copy the Retain storage directories 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.
One approach is to create a CIFS mount from the Linux box to the Windows server. This requires that you first share the parent directory of the "archive" directory on your Windows server housing Retain. Another approach would be to 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 Windows to the new Linux server. To help with this process, you may download and install Support's utility for copying the files/directories.
Change to the new archive directory. It should have 256 subdirectories (00 - FF). All those subdirectories must have the ownership of tomcat tomcat.
Windows does not have a file ownership scheme similar to Linux, so once you've copied the storage directories over, you'll need to set the directory/file ownership and permissions. That process can take almost as much time as copying the directories did but it must be done in order for Retain to be able to read from and write to them. To do this, type: chown -R tomcat:tomcat [directory].
EXAMPLE: chown -R tomcat:tomcat archive (performed from the base storage path containing the archive, index, and other Retain storage directories)
6. 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.
7. Start Tomcat on the new server.
8. Login to the Retain Server web admin console.
9. 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
10. 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.