synbackup utility

WSupported on Windows
USupported on Unix

 

NSupported in Synergy .NET

Today’s 24/7 customer environments require that backups must be able to occur without having to shut down applications. The synbackup utility provides a means for all cooperating processes to freeze I/O during a Synergy system backup.

Note

A cooperating process is defined as any Synergy program (dbr, dbs, rsynd, isutl -r, fconvert, and any programs that use them) that is started after the backup mode feature is enabled. Therefore, make sure you start any other Synergy products (such as xfServer or xfODBC) after you configure the backup feature. See Configuring the backup mode feature on Windows and Configuring the backup mode feature on Unix for configuration instructions.

For general information on backups and how synbackup fits into system resiliency planning, see Configuring for resiliency.

The SynergyVSSWriter service turns synbackup on automatically when a Windows system backup begins and turns it off when the backup is finished. See SynergyVSSWriter service for details.

Important

We strongly recommend using SynergyVSSWriter when automating backup processes on Windows.

This topic includes the following: 

How is synbackup used?

The primary use of synbackup is to ensure that ISAM files (each made up of two files) are correctly synchronized. The most common problem that can plague an ISAM file is index corruption, where the index file (.ism) and data file (.is1) are not in sync. Copying an ISAM file while it’s performing an update operation is almost certain to make a copy that’s out of sync. Synbackup can help prevent this problem.

Synbackup has four backup modes:

You can use synbackup in several different ways:

The following synbackup sequence of events is typical in a backup scenario:

1. Put synbackup into a Pending state (synbackup -b) for a short period of time prior to performing a backup.
2. Freeze Synergy updates by setting the backup mode to On (synbackup -s) until the backup is complete.
3. Unfreeze Synergy updates by setting the backup mode to Off (synbackup -x).

When the backup mode is Pending or On, DELETEs, STOREs, and WRITEs operations are frozen, and isutl -r and fconvert operations are not allowed. You can change the way your application handles the freezing of update operations using the %SYN_SETSTATE function. (See %SYN_SETSTATE and %SYN_GETSTATE.) The default behavior is to suspend application execution.

To reduce the stoppage time that an application may wait for a backup to occur, consider copying the data files to another location first, which is faster than actually backing them up to a tape device. Then, after restoring updates with synbackup, the backup to tape can be done on the copies.

To display usage information (or help) for synbackup, run it without any options.

Two synbackup modes of operation are supported. If the data files are on the same machine as the user applications, synbackup is administered from that machine. If the data is located on a data server, synbackup is administered from the server and any remote applications must use xfServer.

Note

Synbackup cannot be run from a Synergy/DE Client installation. If it is, a “Backup feature not allowed across network drive” error will be generated. The backup mode feature also is not supported on systems running multiple versions of Synergy.

Synbackup on Windows

You must be a member of the Administrators or Backup operators group to run synbackup. Synbackup only works with data on a file server using xfServer or with local data accessed via clients using Terminal Services.

Synbackup has the following syntax:

synbackup [-c] [-b|-s|-x [-w seconds]] [-d] [-q] [-?|-h]

-c

Create the file C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg. The backup mode is set to Off initially. (Only a member of the Administrators group can use this option.)

-b

Set backup mode to Pending, which means that synbackup will next be run with the -s option. Pending mode gives applications an opportunity to defer update operations until the pending backup is complete.

-s

Set backup mode to On, which freezes all requests for update operations.

-w seconds

Specify the maximum number of seconds to wait for an active isutl –r or fconvert to complete before setting the backup mode. A value of -1 tells synbackup to wait indefinitely until the backup can be performed. The -w option can only be specified in conjunction with -b or -s.

-x

Set backup mode to Off, which unfreezes any requests for update operations.

-d

Delete the C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg file (in other words, disable the backup mode feature). (Only a member of the Administrators group can use this option.)

-q

Display the current backup mode.

-? or -h

Display synbackup command line option help.

A file mapping of a physical file (C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg) is created that contains the backup mode (Pending, On, Off, or Not Allowed). Only cooperating processes that are local to that file are affected. The backup mode feature is disabled when C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg does not exist.

Configuring the backup mode feature on Windows

Synbackup on Unix

Only a system administrator whose effective user ID is root can use synbackup to create or change the backup mode. Otherwise, an error is generated. Any user is allowed to display the current backup mode using the -q option.

Synbackup has the following syntax:

synbackup [-c] [-b|-s|-x [-w seconds]] [-d] [-q] [-?|-h]

-c

Create the shared memory segment for all cooperating processes. The backup mode is set to Off initially.

-b

Set backup mode to Pending, which means that synbackup will next be run with the -s option. Pending mode gives applications an opportunity to defer update operations until the pending backup is complete.

-s

Set backup mode to On, which freezes all requests for update operations.

-w seconds

Specify the maximum number of seconds to wait for an active isutl –r or fconvert to complete before setting the backup mode. A value of -1 tells synbackup to wait indefinitely until the backup can be performed. The -w option can only be specified in conjunction with -b or -s.

-x

Set backup mode to Off, which unfreezes any requests for update operations.

-d

Disable synbackup by removing the synbackup.cfg file and releasing shared memory.

-q

Display the current backup mode as well as the number of current processes that are using synbackup.

-? or -h

Display synbackup command line option help.

The current backup mode (Pending, On, Off, or Not Allowed) is maintained in a shared memory segment on the system. The synbackup utility is used to initialize and maintain this shared memory segment, as well as to set the backup mode to Pending, On, or Off. The base address of this memory segment is stored in the file DBLDIR:synbackup.cfg. So that the runtime does not have to repeatedly open this file, it first checks the SYNBACKUP environment variable. If SYNBACKUP is set, the runtime opens the synbackup.cfg file to retrieve the base address. If SYNBACKUP is not set, the backup mode feature is disabled.

See Synergex KnowledgeBase article 2357 and Files_for_synbackup_for_Unix in Synergy CodeExchange for more information and scripts to help you automate the process.

Configuring the backup mode feature on Unix

1. Uncomment the SYNBACKUP=1 line in the distributed setsde script.
2. Run synbackup -c to initialize the shared memory segment.
Important

This shared memory segment should be reinitialized on every system reboot. You can accomplish this using a /rc script.

3. Ensure that all processes wishing to cooperate source the setsde script so the uncommented SYNBACKUP line is honored. (This includes rsynd.)