Moving Retain To New Server (Linux to Linux)

How do you move Retain on Linux to a new server on Linux?

DISCLAIMER:
This knowledgebase (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.  The ASConfig.cfg 
2.  The Database (unless it's on a separate server in which case it can stay there.  That part is up to you.)
3.  The archive files.  It is recommended that you also copy the indexes.  It would be more work not to and would be disruptive to searching.

Everything else can be re-created but can also be copied if you wish.  In summary, here are the storage directories to be copied:

• archive (required)
• backup (optional)
• ebdb (optional)
• export (optional)
• index (recommended)
• license (optional)
• xml (optional)

4.  For Retain 4 only:

• .../index/solrhome/zoo.cfg
• .../RetainServer/WEB-INF/solrweb/WEB-INF/cfg

*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 major Retain version you are currently using into the software directory you created on the new server. 

If Retain 2.x, download that version.  It could be a newer build of that same major version.  What you want to avoid is downloading Retain 2.x when your old system is Retain 1.x or downloading Retain 3.x when your old system is Retain 2.x.

Download the same major version of Retain that your are currently using, going with the latest build of that major version (where "major version" is 2.x, 3.x, 4.x, etc): 
http://download.gwava.com/download.php?product=Retain&version=versions

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]'

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.

"Making the Move"

1.  Disable all archive and deletion jobs on the old server.

2.  For good measure, stop Tomcat on the old server. 

3.  Move the MySQL database if it resides on the Retain server. 

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. Now is probably the best time to Stop Retain.

5.  Manually copy your storage directory contents from the existing server to the new server.

a.  Connect the existing server's storage directory to the new server; or, rsync will support addressing the DNS hostname or IP address of the destination server if you wish to do it that way.

If you decide to mount the new server's storage directory, one way to do this is to create an "export" of the existing server's storage directory and create an NFS mount to a drive from the new server over to the exported drive on the existing server.  For sample instructions on how to create an export and how to mount to it, see "How to 'Map' (Mount) Another Server's Linux Directory to Your Server".

b.  Change the tomcat userid on the new server to match the tomcat userid on the old server (if necessary).  

File ownership and permissions are tied to a userid, not a user name; thus, if tomcat on server A has a userid assignment of 110 and tomcat on new server B has 107, then the files that get copied over come over as being owned by userid 110, not "tomcat".  As the files get stored on server B, it looks up userid 110 on its system.  If that ID is assigned to another process, say "Puppet", then the files will have that program as their owner, not tomcat.  So, you must check what the tomcat userid is on source server A and and on destination server B and make them match by changing the userid, if necessary, on destination server B.

1)  On the old server, type: cat /etc/passwd

This will list out all the user accounts on the server, showing their userids and group IDs.  In the list in the screenshot, tomcat is listed last and its userid is 110 and its group ID is 1000.

2)  Do this same procedure on the new server. 

If the userids match for tomcat on both servers, consider yourself fortunate and you are ready for the next step "c"; otherwise, proceed to sub-step "3)".

3)  Look at the new server's userid list you obtained. 

Determine whether another process on the new server is using the same userid assigned to Tomcat on the old server.

If so, you'll need to change that processes' userid to an unused userid by following the same steps outlined in the following sub-step "4)" for Tomcat's userid change.  Then, follow sub-step "4)" to change Tomcat's userid.

4)  Change a userid by typing this command:  usermod -u [new userid assignment] [username getting the new userid]

 

You can also use vi to edit /etc/passwd and manually change the userids; whichever is easier for you.

c.  Change to the main Retain storage directory and copy it from the old server to the new server.

We recommend using rsync.  Regardless, when copying files on Linux, be sure that whatever method you use copies over the permissions and ownerships. 

NOTE:  This should carry over the tomcat ownership and proper file permissions; however, if they are not preserved during the copy process for some reason, you need to set them:

chown –R tomcat:tomcat [full path to new storage directory]

chmod –R 744 [full path to new storage directory]

This could take days or weeks to complete since the storage's archive directory contains over 16M subdirectories; thus, it is much better if the permissions/ownership are preserved during the copy process.

6.  Shut down Tomcat on the new server if you haven't already.

7.  Copy Retain configuration file(s):

Again, copy in such a way that you maintain its file permissions and ownership (tomcat:tomcat); otherwise, remember to set the file ownership and permissions afterwards..

a)  Copy the /opt/beginfinite/retain/RetainServer/WEB-INF/cfg/ASConfig.cfg

NOTE:  If the storage directory on the new server is different from the old server, you will need to open ASConfig.cfg and change several parameters to reflect the storage paths on the new server:

• <basepath>
• <archivePath>
• <xmlPath>
• <indexPath>
• <backupPath>
• <licensePath>
• <EBDBPath>
• <exportPath>

b)   If this is a Retain 4 system: 

1.  Copy the .../index/solrhome/zoo.cfg and edit the path the index directory if it has changed.

2.  Copy everything from .../RetainServer/WEB-INF/solrweb/WEBINF/cfg.

8.  Start Tomcat on the new server.

9.  Login to the RetainServer web interface.

10.  For systems where the Worker is on the Retain server, create a new worker object in the RetainServer web interface to replace the old one:

a)  Create a new worker.

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.

f)   Restart tomcat.

g)  From a web browser, go to the RetainWorker and upload the new bootstrap.

[Retain server IP]/RetainWorker

11.  If you backed up any of the RetainWorker properties files (see step #4 under the Preparation section), restore those to their respective directories.  This does not apply to most customers - this is very rarely done.

This article was originally published in the GWAVA knowledgebase article ID 743.