34.2 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, a Linux 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.

Select the Target Service Agent appropriate for your operating system:

34.2.1 GroupWise Target Service Agent (GWTSA) for NetWare 5.1

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

IMPORTANT:Unless you are running GroupWise on NetWare 5.1, do not use GWTSA. Use TSAFS and TSAFSGW for superior performance.

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.

Table 34-5 Files and Directories 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 webac70a 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 7 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 Environment Options: Cleanup 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 Section 34.3, GroupWise Time Stamp Utility.

Running GWTSA

GWTSA should be used on NetWare 5.1 only. The gwtsa.nlm program file is automatically installed along with the GroupWise agents (POA and MTA).

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

NOTE:The example is formatted for readability. In the gwtsa.ncf file, the command is a single line of text.

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

NOTE:The example is formatted for readability. In the gwtsa.ncf file, the command is a single line of text.

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. This minimizes the time that the backup process locks the live GroupWise databases so that the GroupWise agents continue to run smoothly during the backup. 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:

  1. Run the gwtsa.ncf file at the NetWare server console.

To start GWTSA automatically each time you restart the server:

  1. 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™ (SMS), as described in Backup and Restore Services (Storage Management Services) on the NetWare 5.1 Documentation Web site, and compatible backup software, as listed in the Partner Product Guide.

Backing Up Remote Domains and Post Offices If the domains and post offices to back up are located on a different server from where the GroupWise agents run, you must copy GWTSA (gwtsa.nlm), along with the GroupWise agent engine (gwenn5.nlm), to the server where the data resides and run it there.

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.

Example: /home-sys:\gwsystem\dev

/ll

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

Example: /ll-v

/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.

Example: /log

/tempdir

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

Example: /tempdir-vol1:\temp

/vserver

Specifies the name of a virtual server in a NetWare cluster. See Backing Up a GroupWise System in a NetWare Cluster in Novell Cluster Services on NetWare in the GroupWise 7 Interoperability Guide.

34.2.2 GroupWise Target Service Agent for File Systems (TSAFSGW) for NetWare 6.x/OES and Linux

The GroupWise Target Service Agent for File Systems (TSAFSGW) builds on the standard capabilities of the Target Service Agent for File Systems (TSAFS) to provide robust GroupWise backup capabilities. It functions like a GroupWise-specific translator between the standard capabilities of TSAFS and the standard capabilities of your backup software of choice.

System Requirements

TSAFS and TSAFSGW are available on NetWare 6.x and Novell Open Enterprise Server (OES) NetWare. They are also available with the Storage Management Services (SMS) package on SUSE® Linux Enterprise Server (SLES) 9 and OES Linux.

TSAFS Functionality

The latest version of 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 (userxxx.db), so that the Allow Purge of Items Not Backed Up option described in Environment Options: Cleanup 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 TSAFS, user databases must be time-stamped as a separate process after you run your backups in order for the Allow Purge of Items Not Backed Up option described in Environment Options: Cleanup to work properly. For instructions, see Section 34.3, GroupWise Time Stamp Utility.

  • Supports backups of clustered servers so that the backup job continues on failover

  • Uses a read-ahead, data caching mechanism to improve backup performance

Make sure you have the latest version of TSAFS for your operating system.

NetWare:

The latest version of TSAFS ships with NetWare and its Support Packs. Updates to SMS and TSAFS that occur between NetWare Support Packs can be downloaded from the Novell Support Web site. Search for tsa5up??.exe to find the latest version.

Linux:

The latest version of TSAFS ships with OES Linux and GroupWise 7.x.

For complete details about TSAFS on NetWare and Linux, see the Storage Management Services Administration Guide on the Novell Open Enterprise Server Documentation Web site. You can use TSAFS as it ships with your operating system to back up GroupWise data, or you can enhance its functionality by using TSAFSGW along with it.

TSAFSGW Functionality

TSAFS for GroupWise (TSAFSGW) works with TSAFS and other backup software on NetWare and Linux. For a complete and current list of compatible backup software, use the Partner Product Guide.

Like TSAFS, TSAFSGW 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, TSAFSGW 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 TSAFSGW. If TSAFS is not already running when you start TSAFSGW, TSAFSGW starts it for you.

TSAFSGW backs up all directories and files at the locations you specify using the /home switch when you start TSAFSGW. The table below lists the standard GroupWise directories and files that you want to have backed up by TSAFSGW.

Table 34-6 Files and Directories Backed Up by TSAFSGW

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 webac70a 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 7 Troubleshooting 3: Message Flow and Directory Structure.

To to keep unnecessary files from being backed up, you should configure your backup software to exclude the following file types from the backup:

  • Agent log files (for example, ????mta.??? to exclude files such as 0518mta.001 and ????poa.??? to exclude files such as 0518poa.001)

  • Timing files used by the Internet Agent (proc and pulse.tmp)

  • Attachments that are being written during the backup (locked files under the offiles directory in the post office cannot be excluded but error messages generated by them can be ignored)

NetWare: Running TSAFS and TSAFSGW

Running TSAFS on NetWare

To run TSAFS with GroupWise functionality:

  1. At your NetWare server console, unload TSAFS.

  2. Use the following command to start TSAFS with GroupWise functionality:

    load tsafs /EnableGW=True
    

    The switch setting is saved in a configuration file (sys:\etc\sms\tsa.cfg), so that you do not need to include the switch when you load tsafs.nlm in the future.

    If you need to run TSAFS without GroupWise functionality in the future, unload TSAFS, then reload using:

    load tsafs /EnableGW=False
    
  3. To verify that TSAFS is running with GroupWise functionality, use the following command:

    tsafs
    
  4. Scroll down to the /EnableGW entry and look for a value of True.

  5. If you want to start TSAFS automatically each time you restart the server, load tsafs.nlm in the autoexec.ncf file.

    NOTE:Starting with NetWare 6.5 Support Pack 4, GroupWise functionality is always enabled and you do not need to use the /EnableGW switch.

  6. Continue with Running TSAFSGW on NetWare.

Running TSAFSGW on NetWare

The tsafsgw.nlm program file is automatically installed along with the GroupWise agents (POA and MTA). During agent installation, a tsafsgw.ncf file is created in the directory where you installed the agents. By default, it loads tsafsgw.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\tsafsgw /home-domain_directory
                         /home-post_office_directory
Example:
load sys:\system\tsafsgw /home-sys:\gwsystem\provo1 
                         /home-sys:\gwsystem\dev

NOTE:The example is formatted for readability. In the tsafsgw.ncf file, the command is a single line of text.

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

Syntax:
load sys:\system\tsafsgw /home-domain_directory
                         /home-domain_directory
                         /home-post_office_directory
                         /home-post_office_directory
                         /home-post_office_directory
Example:
load sys:\system\tsafsgw /home-sys:\gwsystem\provo1 
                         /home-sys:\gwsystem\provo2
                         /home-sys:\gwsystem\dev 
                         /home-sys:\gwsystem\sales
                         /home-sys:\gwsystem\research

NOTE:The example is formatted for readability. In the tsafsgw.ncf file, the command is a single line of text.

For each /home switch that specifies a GroupWise domain or post office directory, TSAFSGW can determine what types of GroupWise objects are available at that location. TSAFSGW recognizes four GroupWise object types:

  • Domain [DOM]

  • Post office [PO]

  • Library [DMS] (for “document management services”)

  • Remote document storage area [BLB] (for “blob,” meaning a compressed document file)

For example, if you provide a /home switch pointing to a directory that contains a post office named Development, and if this post office has two libraries named Design (located in the lib0001 subdirectory of the post office) and Training (located in the lib0002 subdirectory of the post office), and if the libraries store documents in storage areas at \gwdms\design_store and \gwdms\training_store, TSAFSGW can provide the following list of directory names to your backup program for display:

[PO] development
[DMS] lib0001
[BLB] design_store
[DMS] lib0002
[BLB] training_store

You can then easily select what you want to back up.

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, TSAFSGW copies each database to back up into the sys:\system\tsa\temp directory during the backup process. Because it takes less time to copy each database than it does to transfer it to the backup medium, this procedure minimizes the time that the backup process locks each live GroupWise database. Therefore, the GroupWise agents can continue to run smoothly during the backup. If necessary, use the /tempdir switch to specify an alternate location where more disk space is available. You need sufficient disk space to accommodate the largest database, but not the entire domain or post office.

To start TSAFSGW immediately:

  1. Run the tsafsgw.ncf file at the NetWare server console.

To start TSAFSGW automatically each time you restart the server:

  1. Add a tsafsgw.ncf line to the autoexec.ncf file.

With TSAFSGW running, you are ready to back up GroupWise data with Novell Storage Management Services (SMS), as described in Storage Management Services Administration Guide on the Novell Open Enterprise Server Documentation Web site, and compatible backup software, as listed in Partner Product Guide.

Backing up Remote Domains and Post Offices

If the domains and post offices to back up are located on a different server from where the GroupWise agents run, you must copy TSAFSGW (tsafsgw.nlm), along with the GroupWise agent engine (gwenn5.nlm), to the server where the data resides and run it there.

Linux: Running TSAFS and TSAFSGW

Running TSAFS on Linux

TSAFS might already be available on your Linux server.

  • If you are running OES Linux, TSAFS was installed along with the novell-sms package when you installed OES Linux.

  • If you are running SLES 9, you can copy the novell-sms RPM from the agents/linux directory of the GroupWise 7 Administrator for Linux CD or from the GroupWise software distribution directory to the server where you want to set up backups, then use the following command to install it on SLES 9:

    rpm -ivh novell-sms-1.0.0-nn.i586.rpm
    

    After the novell-sms package is installed, use the following command to start the smdr daemon:

    /etc/init.d/novell-smdrd start
    

    To verify that the daemon is running, use the following command:

    /opt/novell/sms/bin/smsconfig -t
    

    When you install the novell-sms package, your system is configured to start the smdr daemon automatically each time your system restarts.

To run TSAFS with GroupWise functionality:

  1. Make sure you are logged in as root.

  2. Change to the directory where the SMS executables are located.

    cd /opt/novell/sms/bin
    
  3. Stop TSAFS.

    ./smsconfig -u tsafs

  4. Start TSAFS with GroupWise functionality.

    ./smsconfig -l tsafs --EnableGW
    
  5. To verify that TSAFS is running with GroupWise functionality, use:

    ./smsconfig -t
    

    Results should include:

    The loaded TSAs are:
    tsafs --EnableGW
    

    NOTE:On the latest version of Novell Open Enterprise Server, GroupWise functionality is always enabled and you do not need to use the --EnableGW switch.

  6. To make GroupWise functionality the default, modify the SMS configuration file:

    1. Change to the directory where the SMS configuration file is located.

      cd /etc/opt/novell/sms
      
    2. In a text editor, open the smdrd.conf file.

    3. Change the following line:

      autoload: tsafs
      

      to:

      autoload: tsafs --EnableGW
      
    4. Save the file and exit.

  7. Continue with Running TSAFSGW on Linux.

Running TSAFSGW on Linux

Because TSAFSGW depends on SMS, you use the smsconfig command in the /opt/novell/sms/bin directory, along with one or more --home switches, to specify the domains and post offices to back up.

  1. Make sure you are logged in as root.

  2. Change to the directory where the SMS executables are located:

    cd /opt/novell/sms/bin
    
  3. Use the following command to specify GroupWise locations to back up:

    Syntax:
    ./smsconfig -l tsafsgw --home /domain_directory
                           --home /post_office_directory
    
    Example:
    ./smsconfig -l tsafsgw --home /gwsystem/provo1 
                           --home /gwsystem/dev
    

    NOTE:The example is formatted for readability. The command is a single line of text.

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

    Syntax:
    ./smsconfig -l tsafsgw --home /domain_directory
                           --home /domain_directory
                           --home /post_office_directory
                           --home /post_office_directory
                           --home /post_office_directory
    
    Example:
    ./smsconfig -l tsafsgw --home /gwsystem/provo1 
                           --home /gwsystem/provo2
                           --home /gwsystem/dev 
                           --home /gwsystem/sales
                           --home /gwsystem/research
    

    NOTE:The example is formatted for readability. The command is a single line of text.

    For each --home switch that specifies a GroupWise domain or post office directory, TSAFSGW can determine what types of GroupWise objects are available at that location. TSAFSGW recognizes four GroupWise object types:

    • Domain [DOM]

    • Post office [PO]

    • Library [DMS] (for “document management services”)

    • Remote document storage area [BLB] (for “blob,” meaning a compressed document file)

    For example, if you provide a --home switch pointing to a directory that contains a post office named Development, and if this post office has two libraries named Design (located in the lib0001 subdirectory of the post office) and Training (located in the lib0002 subdirectory of the post office), and if the libraries store documents in storage areas at /gwdms/design_store and /gwdms/training_store, TSAFSGW can provide the following list to your backup program for display:

    [PO] Development
    [DMS] LIB0001
    [BLB] DESIGN_STORE
    [DMS] LIB0002
    [BLB] TRAINING_STORE
    

    NOTE:For libraries and document storage areas, TSAFSGW provides the directory name rather than the object name.

    You can then easily select what you want to back up.

    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, TSAFSGW places each database to back up in the /tmp directory during the backup process. Because it takes less time to copy each database than it does to transfer it to the backup medium, this procedure minimizes the time that the backup process locks each live GroupWise database. Therefore, the GroupWise agents continue to run smoothly during the backup. If necessary, use the --tempdir switch to specify an alternate location where more disk space is available. You need sufficient disk space to accommodate the largest database, but not the entire domain or post office.

  4. To verify what TSAs are currently running, use the following command:

    ./smsconfig -t
    

    Results should include:

    The loaded TSAs are:
    tsafs --EnableGW
    tsafsgw --home /domain_directory --home /post_office_directory
    
  5. To establish the specified GroupWise locations as defaults for automatic backups in the future, modify the SMS configuration file:

    1. Change to the directory where the SMS configuration file is located.

      cd /etc/opt/novell/sms
      
    2. In a text editor, open the smdrd.conf file.

    3. Locate the following line:

      autoload: tsafs --EnableGW
      
    4. Add another line beneath it for TSAFSGW:

      autoload: tsafsgw --home /domain_directory
                        --home /post_office_directory
      

      NOTE:The example is formatted for readability. The entry is a single line of text.

    5. Save the file and exit.

With TSAFSGW running, you are ready to back up GroupWise data with Novell Storage Management Services (SMS), as described in Storage Management Services Administration Guide on the Novell Open Enterprise Server Documentation Web site, and compatible backup software, as listed in Partner Product Guide.

Backing Up Remote Domains and Post Offices If the domains and post offices to back up are located on a different server from where the agents are installed, that target server must meet the following requirements in order for successful backups to take place:

  • The novell-sms package must be installed and running on the target server, as described in Running TSAFS on Linux.

  • The libtsafsgw.so.version_number file that is installed with the agents to /opt/novell/groupwise/agents/lib must be copied to /opt/novell/lib on the target server.

  • A symbolic link must be created from libtsafsgw.so to libtsafsgw.so.version_number on the target server. You can use the following command in the /opt/novell/lib directory to create the symbolic link:

    ln -s libtsafsgw.so.version_number libtsafsgw.so
    

After these requirements are met on the target server where a domain or post office is located but no agents are installed, you can follow the instructions in Running TSAFSGW on Linux to back up the domain or post office.

TSAFSGW Startup Switches

The following startup switches can be used with TSAFSGW on NetWare and Linux:

NetWare TSAFSGW

Linux TSAFSGW

/home

--home

/tempdir

--tempdir

To tune backup performance, use the startup switches provided for TSAFS as described in Storage Management Services Administration Guide on the Novell Open Enterprise Server Documentation Web site.

/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.

NetWare TSAFSGW

Linux TSAFSGW

Syntax:

/home- path

--home path

For example, to back up a domain and a post office, you would use:

NetWare

/home-sys:\gwsystem\provo1 /home-sys:\gwsystem\dev

Linux

--home /gwsystem/provo1 --home /gwsystem/dev

/tempdir

Specifies where TSAFSGW places files during the backup process. You need sufficient disk space to accommodate the largest database, but not the entire domain or post office. The default locations are platform specific:

NetWare:

sys:\system\tsa\temp

Linux:

/tmp

NetWare TSAFSGW

Linux TSAFSGW

Syntax:

/tempdir- path

--tempdir path

For example, to change the temporary directory, you would use:

NetWare:

/tempdir-vol1:\temp

Linux:

--tempdir /gw/temp