Managing relay server disk space and databases involves various tasks, some of which are performed automatically by the relay server, while others are administrative tasks involv-ing the use of specific tools or database utilities. The followinvolv-ing sections provide back-ground information about relay server databases and instructions for database
management tasks that involve administrative input:
• About Relay Server Databases
• Purging Queues of Old Messages
• Migrating Relay Server Data
• Moving Queue Store Directories to Another Location About Relay Server Databases
The Groove Relay Server contains a transactional database system that stores queues of Groove client device-targeted messages (updates to Groove workspaces), queues of iden-tity-targeted messages Groove (instant messages and invitations), and basic user informa-tion (including authenticainforma-tion keys and identity informainforma-tion).
Two main databases in the relay server installation directory store this information as fol-lows:
• FFQ - As of ERS 3.0, contains bulk client message data, separated into files (called extents) which reside in unique directories in the FFQ queue store. The relay server pre-allocates a number of these extents at start-up for subsequent use by the queue store.
• RQS - Contains client meta data (including identity, device, and account information). The relay server creates this database at startup, if it is not already present.
The database system also creates transaction log files that can be used to maintain the integrity of the relay server databases in the event of system failure. Transaction log files have sequenced names (such as log.0000000001, log.0000000002, etc) and reside in the RQS\Logfiles subdirectory of the relay server’s installation directory. The relay server depends on these log files to maintain consistency among the message queues and other related databases when restarting after an outage. The relay server clears transaction logs automatically. Periodically (every 5 minutes), the relay server writes a checkpoint record to the current transaction log, then checks for transaction logs that are no longer needed for recovery operations, and deletes them. This process of clearing transaction logs typi-cally completes in a few seconds.
Several database utilities that support relay database management reside in the DbUtilities subdirectory of the relay server installation directory. Only run those utilities specifically mentioned in this guide or when directed to do so by a Groove Support representative.
Running certain utilities while the relay service is started, or running them with incorrect arguments, could permanently damage the relay queue store and require the removal of queue database files to make the service operational again.
Note: If your database directories become full, you may need to move them to another volume for storage. For information about moving database directories to another volume, see “Moving Queue Store Directories to Another Location” below.
Purging Queues of Old Messages
The relay server automatically purges queues that have exceeded their defined retention time (holding period). Automatic purge support is enabled by default, so that once a day (at 11 PM local time on the server platform), the relay server automatically purges relay queues of old messages.
The relay server FFQ database maintains two types of message queues, with default mes-sage retention times as follows:
• Device-targeted message queues - updates that target a triplet of device-identity-workspace URLs, such as updates generated from device-identity-workspaces. The default retention time for these messages is 30 days. The relay server marks targeted messages older than 30 days for deletion. Note that even after old device-targeted messages are deleted, the Groove Dynamics Manager component on the Groove client can recover them if necessary to update a workspace.
• Identity-targeted message queues - instant messages and Groove client invitations for an identity URL. The default retention time for these messages is 90 days. The relay server marks identity-targeted messages older than 90 days for deletion. The longer holding period is allowed because identity-targeted queues cannot be recovered after deletion.
Domain Administrator’s Guide for information about these capabilities.
You can change the automatic purge interval by setting a Windows registry value, or you can trigger purges manually as needed from the relay server administrative Web pages, as described in the following sections:
• Scheduling Purges
• Manually Purging Queues
Note that management server administrators can change the relay message retention time for device-targeted and identity-targeted messages by using the management server administrative Web interface. This interface also allows administrators to purge queues for individual users. See the Groove Management Server Domain Administrator’s Guide for information about purging individual user queues.
Scheduling Purges
To change the automatic purge time, do the following:
1. Set the hour at which to start the purge by defining the following value in the Windows registry (in Hex by default):
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Groove Relay\Parameters
“AdminPurgeProcessStartHour”=dword:<xxxxxxxx>
where xxxxxxxx is the desired start hour plus 1. For example, setting the value dword:00000009 starts the purge at 8 AM.
2. If necessary, set the number of minutes after the hour at which to start the purge by defining the following registry value:
“AdminPurgeProcessStartMinute”=dword:<xxxxxxxx>
where xxxxxxxx is the desired number of minutes. For example, setting this value to 00000005, starts the purge at 5 minutes past the specified hour.
3. To change daily purges (the default condition) to weekly purges on a specific day, specify the day by defining the following registry value:
“AdminPurgeProcessStartDay”=dword:<xxxxxxxx>
where xxxxxxxx is the desired numeric day (0 = daily, 1= Sunday, 2 = Monday and so on). For example, setting this value to 00000004, starts the purge on Wednesday at the specified hour.
4. Restart the relay server to implement your changes. Remember that the relay server must be running in order for queue purges to occur.
To disable the integrated purge support, do the following:
1. Set the following value in the Windows registry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Groove Relay\Parameters
“AdminPurgeEnable”=dword:00000000
2. Restart the relay server so that your changes will take effect.
3. To view purge progress at any time, click the Purge Status link from the relay server administrative Web pages. The status displays data on each queue purged as described in the section, “Monitoring Database Purges”, in the Monitoring a Relay Server section of this guide.
Manually Purging Queues
To purge of old messages from queues, do the following:
1. Open a browser and go to the relay server administrative Web pages.
2. To start the purge/compress cycle, click the Maintenance link, then click the ‘Purge all queues to the configured purge interval’ link. This begins a purge/compress cycle immediately, displaying a status page with the number of bytes purged and compressed. The page refreshes every 5 seconds.
To manually purge a specific queue, click the Queues link, click a queue in the list, then click the Purge button.
3. To view purge progress at any time, click the Purge Status link. The status displays data on the progress of the purge as described in the section, “Monitoring Database Purges”, in the Monitoring a Relay Server section of this guide.
4. To cancel the purge if necessary, click Cancel.
Migrating Relay Server Data
The RQExport, and RQImport utilities are available to migrate Groove data in and out of relay databases, most typically as part of a relay server upgrade, as described in “Upgrad-ing/Re-installing a Relay Server”.
The RQExport utility collects client queue and message information into a single binary export file with a configurable name. If this file reaches a specified size limit, the file closes and the utility creates a new file to continue the export. The initial file name has a .0 extension; the extension increments by 1 for each subsequent file.
RQExport also creates a tab-delimited ASCII index file, with one line of information for each queue exported. This information includes the queue name and the number of mes-sages and bytes exported for each queue. The index file name is as follows: <export file name>.QueueIndex.0. This file is for information only (not used by RQImport).
The RQImport utility reads messages from the binary export file created by the RQExport process and queues those messages in new databases once the old ones have been emptied and removed. Use this utility only when the relay server is NOT running.
You can expedite operations by limiting RQExport and RQImport to operate only on spe-cific message types, such as identity-targeted messages (Groove instant messages and invitations) only. Restricting export/import operations to instant messages is the most practical filtering method because these identity-targeted queues cannot be recovered after deletion.
To view valid RQExport/Import options, enter either of the following from a command line at the relay server installation directory:
RQExport.exe -?
RQImport.exe -?
The sections below provide instructions for using the data export and import utilities pro-vided:
• Using RQExport/RQImport to Rebuild Databases in Default Mode
• Customizing RQExport/RQImport
Using RQExport/RQImport to Rebuild Databases in Default Mode
To use the default mode of RQExport and RQImport to rebuild your RQS databases, do the following:
1. Shutdown the relay server using the Windows service manager.
2. If the RQExport subdirectory exists in the relay installation directory from a prior RQExport run, delete it.
3. Run RQExport.exe by opening a command window from the relay installation directory and entering the following:
RQExport -f <directory path>\<filename>
where
<directory path> is an administrator-specified directory (or drive) name where the exported files will reside.
<filename> is an administrator-specified prefix for the export file, to which the extension .0 is added to the initial file (and increments for successive files).
For example:
RQExport -f export\relayexport OR
RQExport -f X:\RemoteServer\export\relayexport
This copies all message data into one or more export files for use by the RQImport utility.
4. Remove (or move to another location) all the files in the FFQ and RQS subdirectories of the relay installation directory so that a new database can be created (in the next step).
5. Run RQImport.exe from a command line in the relay installation directory, as shown below. This creates new FFQ and RQS directories, populated with the messages found in the export file created in step 3.
RQImport -f <filename>
6. Restart the relay server.
You can now safely delete the RQExport subdirectory created in step 3.
7. To view queue database activity reports, see “Generating and Viewing Database Queue Reports” in the Monitoring a Relay Server section of this guide.
Customizing RQExport/RQImport
To customize the export/import process to collect messages into a single file and to oper-ate only on identity-targeted messages, follow the above procedure for rebuilding your databases in default mode, but modify the RQExport and RQImport commands as fol-lows:
• In the RQExport command line, include the -n, -f, -D options, in wild mat format, as shown in this example:
RQExport -n -f export/IM-dd-mm-yy -D "?*"
• In the RQImport command line, include the -n and -f, options, citing the export file, as shown in this example:
RQImport -n -f export/IM-dd-mm-yy
where:
-n = New export format
-f = Filename and directory that will hold the export or import data
-D“?*” = Device-targeted message (workspace updates) filter. Excludes all queues with device URLs that match wildmat definition "?*" (effectively excluding non-null Device URLs from the export).
IM-dd-mm-yy = export file
Moving Queue Store Directories to Another Location
If your FFQ, RQS Home, Database, or Log file directories approach volume capacity, you may need to move a directory to another volume.
To move a directory to another volume, follow these steps:
1. Stop the relay service using the Windows service control manager.
2. Copy the FFQ, RQS, Database, or Log Files directory using the Windows Explorer or any common file moving utility to another volume. Allow enough time for the file copy to complete.
3. Update the registry setting which control the location of the queue store for each directory that you want to move, listed in the following table:
4. Restart the relay service.
5. Verify that the service has started and is operating correctly. Then you can delete the old copies of the RQS, Database, and/or Log File directories from their original directories.