Novell Documentation: GroupWise 6.5 - Target Service Agents

Target Service Agents

A Target Service Agent (TSA) helps generic backup software back up specialized data located on any "target." A target is a specific location where data is stored, such as a NetWare file system, an eDirectory database, or a collection of GroupWise databases. A target could also be an application that provides data to be backed up. A TSA is specialized to scan, read, and write the specific types of data available at the target. A TSA serves as an intermediary between specific data types and a general backup engine.

The GroupWise Target Service Agent (GWTSA) has long been included with GroupWise and can back up GroupWise data stored on NetWare 4.2, 5.1, and 6.x servers. It is specialized to back up specific GroupWise data types, such as domains and post offices.

The NetWare Target Service Agent for File Systems (TSAFS), available on NetWare 6.x (but not on earlier versions of NetWare), includes a startup option enabling it to handle GroupWise data. TSAFS includes file system backup enhancements that GWTSA does not provide.

For optimum backups on NetWare, select the Target Service Agent appropriate for your version of NetWare and GroupWise:

GroupWise Target Service Agent

The GroupWise Target Service Agent (GWTSA) provides reliable backups of a running GroupWise system on NetWare by successfully backing up open files and locked files, rather than skipping them.

GWTSA Functionality

The GroupWise Target Service Agent (GWTSA) works with other backup software on NetWare. For a complete and current list of compatible backup software, use the Partner Product Guide.

GWTSA has no user interface of its own, but its presence running along with other backup software provides GroupWise options in the backup software that would not otherwise be available. As a Target Service Agent, GWTSA supports any feature that your backup software supports. So if your backup software supports full, incremental, and differential backups or working set and copy jobs, so does GWTSA.

GWTSA backs up standard GroupWise directories and files; extra directories and files that appear within a standard GroupWise directory structure are not backed up by GWTSA. The table below lists the directories and files that are backed up by GWTSA.

GroupWise Location	Directories	Subdirectories/Files Backed Up
Domain	domain_directory	wpdomain.db wpdomain.dc wphost.dc gwdom.dc gwpo.dc mtaname
	domain_directory\wpgate	async gwia webac60a etc.
Post Office	post_office_directory	wphost.db ngwguard.db ngwguard.dc ngwguard.rfl ngwguard.fbk ngwcheck.db ngwcheck.log gwpo.dc
	post_office_directory\gwdms	dmsh.db
	post_office_directory\gwdms\library_directory	.db archive\.* docs\.
	post_office_directory\offiles	.
	post_office_directory\ofmsg	.
	post_office_directory\ofmsg\guardbak	ngwguard.fbk
	post_office_directory\ofuser	userxxx.db
	post_office_directory\ofuser\index	.idx .inc
	post_office_directory\ofviews\win	.vew .ini
Library (Document Storage Area)	library_directory	.db archive\.* docs\.

To see directory structure diagrams showing where the files are located, see "Domain Directory" and "Post Office Directory" in GroupWise 6.5 Troubleshooting 3: Message Flow and Directory Structure.

GWTSA automatically time-stamps all backed-up user databases (userxxx.db), so that the Allow Purge of Items Not Backed Up option described in Modifying Environment Options can function to safeguard users' deleted items against being purged from your GroupWise system before they have been backed up.

IMPORTANT: If you decide not to use GWTSA, user databases must be time-stamped as a separate process in order for the purge control environment option to work properly. For instructions, see GroupWise Time Stamp Utility.

Running GWTSA

GWTSA is available for use on NetWare 4.2, 5.1, and 6.x. The gwtsa.nlm program file is automatically installed along with the GroupWise agents (POA and MTA). If the domains and post offices to back up are located on a different server from where the agents run, you must copy GWTSA (gwtsa.nlm), along with the agent engine (gwenn4.nlm), to the server where the data resides and run it there.

During agent installation, a gwtsa.ncf file is created in the directory where you installed the agents. By default, it loads gwtsa.nlm and provides a /home switch for each domain and post office you selected to be serviced by the MTA and POA. For example:

Syntax:
load sys:\system\gwtsa /home-domain_directory
/home-post_office_directory

Example:
load sys:\system\gwtsa /home-sys:\gwsystem\provo1
/home-sys:\gwsystem\dev

You can add additional instances of the /home switch to back up more domains and post offices.

Syntax:
load sys:\system\gwtsa /home-domain_directory
                       /home-domain_directory
                       /home-post_office_directory
                       /home-post_office_directory
                       /home-post_office_directory

Example:
load sys:\system\gwtsa /home-sys:\gwsystem\provo1
                       /home-sys:\gwsystem\provo2
                       /home-sys:\gwsystem\dev
                       /home-sys:\gwsystem\sales
                       /home-sys:\gwsystem\research

You can also add instances of the /home switch to point to restore areas for post offices or to other temporary locations where you want to restore data.

By default, GWTSA places temporary files in the sys:\system\temp directory during the backup process. If necessary, use the /tempdir switch to specify an alternate location where more disk space is available for temporary files. Additional configuration of GWTSA can be done using other startup switches. See GWTSA Startup Switches for a complete list.

To start GWTSA immediately, run the gwtsa.ncf file at the NetWare server console. To start GWTSA automatically each time you restart the server, add a gwtsa.ncf line to the autoexec.ncf file. With GWTSA running, you are ready to back up GroupWise data with Novell Storage Management Services or other compatible backup software.

Using GWTSA with Your Backup Software

The GWTSA adds GroupWise options to your backup software. This section uses Novell Storage Management Services (SMS) and the NetWare Backup utility (nwback32.exe) as an example of how to integrate GWTSA into your backup software. Similar steps are necessary to integrate GWTSA with other backup software.

If you plan to use GWTSA with SMS, this section assumes that SMS has been installed and configured and is running properly. If you need assistance with SMS, refer to Backup and Restore Services (Storage Management Services) on the NetWare 6.5 Documentation Web site.

NOTE: If you are using Veritas Backup Exec 9 for NetWare, be sure to deselect Delete Existing Trustees on the Backup Exec NetWare tab when you are creating a restore job. If you do not deselect Delete Existing Trustees, GWTSA cannot restore any file that has a .db extension. All GroupWise databases have a .db extension.

Backing Up GroupWise Data with SMS

To back up GroupWise data using SMS with GWTSA running:

Start nwback32.exe from the sys:\public directory of your NetWare server.

You can also use sbcon.nlm at the NetWare server console to perform the backup.
In the Quick Access dialog box, click Backup.
Expand the WHAT TO BACKUP object.

A GROUPWISE DATABASE object has been added to the list of things you can back up.
Expand the GROUPWISE DATABASE object to list GroupWise domains, post offices, and libraries that are available for backup.
After selecting the GroupWise data to back up, continue using SMS as you usually would to perform the backup.

Restoring GroupWise Data with SMS

To restore GroupWise data using SMS with GWTSA running:

Start nwback32.exe from the sys:\public directory of your NetWare server.

You can also use sbcon.nlm at the NetWare server console to restore GroupWise data.
In the Quick Access dialog box, click Restore.
Expand the WHAT TO RESTORE object, then select your backup device.
Expand the WHERE TO RESTORE object.

A GROUPWISE DATABASE object appears on the list of things you can restore.
Expand the GROUPWISE DATABASE object to list GroupWise domains, post offices, libraries, and restore areas where data can be restored.
After selecting the GroupWise data to restore, continue using SMS as you usually would to restore data.

If you need to restore GroupWise data to an existing domain, post office, or library, make sure your backup software is configured to overwrite newer files than those that are being restored.

If you are restoring GroupWise data to a temporary location, make sure you have sufficient free disk space to accommodate the files that are being restored.

GWTSA Startup Switches

The following startup switches can be used with GWTSA:

/home
Specifies the GroupWise location to back up or restore to. Multiple instances of the /home switch are typical. Use a /home switch for each domain and post office to back up. Also use a /home switch for each post office restore area and any other temporary location to which you want to restore GroupWise data outside the standard GroupWise directory structure.

/tempdir
Specifies where GWTSA places its temporary files during the backup process. The default is the sys:\system\tsa\temp directory.

/log
Turns on logging and displays a logging screen. By default, logging is turned off. When you turn logging on, a gwtsa.log file is created in the sys:\system\tsa directory.

/ll
Sets the log level to determine how much information is written to GWTSA log file. Use n for Normal and v for Verbose.

NetWare Target Service Agent for File Systems

The Target Service Agent for File Systems (TSAFS) is available on NetWare 6.0 and later.

IMPORTANT: If you are using GroupWise 6.5 Support Pack 3 or later, TSAFS can time-stamp GroupWise databases as part of the backup process. If you are using an earlier version of GroupWise, time stamping must be performed as a separate process, as described in GroupWise Time Stamp Utility.

TSAFS Functionality

The Target Service Agent for File Systems (TSAFS) includes enhancements that earlier versions of TSAFS did not include:

Supports GroupWise database lock/backup/unlock functionality so that you can back up a running GroupWise system
Provides time stamping of GroupWise 6.5.3 and later user databases so that the Allow Purge of Items Not Backed Up option described in Modifying Environment Options can function to safeguard users' deleted items against being purged from your GroupWise system before they have been backed up
Supports backups of clustered servers so that the backup job continues on failover
Uses a read-ahead, data caching mechanism to improve backup performance

For complete details about the TSAFS, see the NetWare 6.5 Storage Management Services Administration Guide on the NetWare 6.5 Documentation page.

Running TSAFS

At your NetWare server console, unload TSAFS, then use the following command to start TSAFS with GroupWise functionality:

load tsafs /EnableGW=True

The switch setting is saved in a configuration file, so that you do not need to include the switch when you load tsafs.nlm in the future.

To start TSAFS automatically each time you restart the server, load tsafs.nlm in the autoexec.ncf file.

To run TSAFS without GroupWise functionality, unload TSAFS, then reload using:

load tsafs /EnableGW=False

To determine whether or not TSAFS is running with GroupWise functionality, use:

tsafs

Scroll down to the /EnableGW entry and look for a value of True or False.

Using TSAFS with Novell Storage Management Service (SMS)

After TSASF is running on the NetWare server, start the NetWare Backup utility (nwbackup32.exe) on a Windows machine.

You can also use sbcon.nlm at the NetWare server console to perform the backup.
In the Quick Access dialog box, click Backup, then expand WHAT TO BACKUP.

The GROUPWISE DATABASES item is listed if you have been using the GroupWise Target Service Agent (GWTSA). Do not use it with TSAFS.
Expand NETWARE SERVERS, then browse to and select directories where GroupWise domains, post offices, and document storage areas are located.

For background information about GroupWise directory structures, see "Domain Directory" and "Post Office Directory" in "Directory Structure Diagrams" in GroupWise 6.5 Troubleshooting 3: Message Flow and Directory Structure.
Configure the backup job as needed, as described in NetWare 6.5 Storage Management Services Administration Guide on the NetWare 6.5 Documentation page.

To avoid error messages caused by open files that do not need to be backed up, some files can be excluded from the backup, for example:
- Agent log files (mmddpoa.nnn, mmddmta.nnn, mmddgwia.nnn, and mmddweb.nnn)
- Internet Agent lock and cycle files (proc and pulse.tmp)
- Transitory xNStore files used briefly by the agents in the message queues
When you have finished configuring the backup job, click Backup > Submit the Job.

If you need to restore GroupWise data, be sure to run GroupWise Check (GWCheck) as described in Restoring GroupWise Databases from Backup.