Retain Storage Disk Full - Using Storage Manager

  • 7019248
  • 17-Sep-2013
  • 07-Aug-2017

Environment


Retain all versions (although specific menu instructions were created from Retain 3.x)

Situation


Customer's disk is almost full to which the Retain storage points (Server Configuration | Storage).

Resolution


Before going into the solution, it's first important to understand some basic Retain storage concepts.


CONCEPTS

The base storage directory has several subdirectories:

  • archive - this is where the actual archive files are stored (messages, attachments, and message metadata).
  • backup - this is where Retain keeps a backup of your indexes. 
  • ebdb - this is a legacy directory going back to Retain 1.x where the "Derby" database (configuration) was stored - it is not used in Retain 2.x/3.x
  • export - this is where exported PDFs are stored when the "Export to PDF" feature is used in the Retain mailbox.
  • index - this is where the Lucene indexes are stored.  These index files are used when a user searches for messages in the Retain mailbox.  The index directory contents grow with each archive job.
  • license - this is where the licenses are stored when added through the RetainServer web UI.
  • xml -this is where xml mappings are stored (using the mailbox mapping feature).

When your base storage location has run out of disk space, this becomes problematic.  As this article will discuss, you can create a new Retain storage partition using the Storage Manager, but all this does is instruct Retain to begin storing all newly archived messages in the new partition.  All that new partition will have is a new "archive" directory.  It does not move or create the other storage directories (backup, ebdb, export, index, license, xml); thus, this does not take in consideration that your indexes will continue to grow, that users will create PDF exports, etc.

So, even if you create a new Retain storage partition, you still need to do something about the other critical Retain files stored on the disk that has run out of space.  Plan to have a separate disk volume also created to store - at minimum - your index, backup, and export directory.  Retain 1.x customers should also store the ebdb directory on this new disk.

OPTIONS

There are a couple of ways to handle this after adding a new volume:

1.  Move the entire Retain storage directory contents to a new and larger disk.

2.  Create a new Retain storage partition and move the backup, index, and export directories.  This involves adding two new disks.

  • One will contain the backup, index, and export directories (and ebdb for Retain 1.x customers)
  • The other will contain all newly archive files. 


OPTION #1:  MOVE THE ENTIRE RETAIN STORAGE DIRECTORY

Before starting, this assumes that you have added the new/larger disk to your Retain server.

1.  Ensure no archive jobs are currently running and then stop tomcat.

2.  Copy the retain directory and all of its subdirectories to the new disk.

Note for Linux Customers:

When copying files on Linux, be sure that whatever method you use copies over the permissions and ownerships.  Rsync is perfect for this:  rsync -rav -- progress [source directory - omitting the ending "/"] [IP address of new host]:/[destination path].

-r = recursive
-a = archive (retains permissions, ownership, and timestamps)
-v = verbose (provides verbose copy progress)
-- progress = shows the progress of the copy

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 storage directory]
chmod –R 744[full path to storage directory]

This could take hours 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.

3.  Start Tomcat

4.  Log in to the Retain server web interface.

5.  Go to Configuration | Server Configuration | Storage.

6.  Click on the "Advanced Settings" link.  It is barely noticeable, but it is found below the "Base Storage path" field.

7.  Uncheck the option, "Derive all file locations from above base path?"

This will cause seven fields to display.

8.  Change those paths to the new storage area.

9.  Restart tomcat.


OPTION #2:  CREATE NEW RETAIN STORAGE PARTITION

1.  Login to the Retain server web interface.

2.  Ensure no archive jobs are running and disable them from the core settings tab in the module configuration (uncheck "Enable Jobs" and save the change).

3.  Go to Configuration | Storage Manager.

4.  In the "Standard Engine" section, click on the "'partitions" here link where it reads, "In addition, if desired, you may define and remove "partitions" here.

This is found under the "Enable file consolidation?" checkbox (and, by the way, Support strongly recommends NOT using the file consolidation feature).

5.  Complete the fields:  "New Partition Name" and "New Partition Path".

6.  Save the changes.

This only affects the storage of the archive files themselves (message metadata, message body, attachments). 

All items archived prior to this new partition creation continued to be accessed from the original archive path.  Those items do not get moved to the new partition.  This only affects new items archived after its creation; thus, your archives will now be stored in two locations: all old items in the original path and all new items in the new partition.

7.  Go to Configuration | Server Configuration | Storage.

8.  Click on the "Advanced Settings" link. 

It is barely noticeable, but it is found below the "Base Storage path" field.

9.  Uncheck the option, "Derive all file locations from above base path?"

This will cause seven fields to display.

10.  At minimum, change the path to the index, backup, and export directories to the new disk volume previously discussed in the "Concepts" section of this document. 

Retain 1.x customers should also include the ebdb directory.

Do not change the attachments path!  All existing attachments will remain at this path and Retain needs to know how to access them.  All new attachments will be stored in the new partition and Retain knows how to access by the partition information you provided in step #4.

11.  Save your changes.

12.  Copy all the files in the paths you changed in step #8 over to the new location.

Note for Linux Customers:

When copying files on Linux, be sure that whatever method you use copies over the permissions and ownerships.  Rsync is perfect for this:  rsync -rav -- progress [source directory - omitting the ending "/"] [IP address of new host]:/[destination path].

-r = recursive
-a = archive (retains permissions, ownership, and timestamps)
-v = verbose (provides verbose copy progress)
-- progress = shows the progress of the copy

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 storage directory]
chmod –R 744[full path to storage directory]

This could take hours 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.

13. Restart Tomcat

14.  After an archive job runs, go to the new storage path specified in your new Retain partition and verify that the two-digit directories exist.  This will tell you that the new Retain partition has taken effect.

Additional Information

This article was originally published in the GWAVA knowledgebase as article ID 2206.