SEP sesam extension for Informix

From SEPsesam
Jump to: navigation, search

Copyright © SEP AG 1999-2018. All rights reserved.

Any form of reproduction of the contents or parts of this manual is allowed only with the express written permission from SEP AG. When compiling and designing user documentation SEP AG uses great diligence and attempts to deliver accurate and correct information. However, SEP AG cannot issue a guarantee for the contents of this manual.


Introduction

SEP sesam online backup for Informix (sib) provides a XBSA interface between Informix and SEP sesam for saving data of Informix databases to SEP sesam Server. XBSA API specifies the access from Informix onbar utility to a backup application. SEP sesam will manage the whole backup media handling like loading the correct tapes, whereas ONBAR decides which data has to be saved or recovered. This document provides information about the sesam specific parts of Informix backups. It's not an Informix/ONBAR administration guide. Please read Informix documentation of ONBAR to get familiar with Informix's backup and recovery concepts and tools.

System requirements

Installation

Installation on Linux or Unix

The SIB packet includes only one shared library which Informix server loads dynamically during backup or restore. The library has to be copied to Informix server and the full path to it has to be specified under BAR_BSALIB_PATH in the ONBAR configuration file.

For installation we assume the following environment. Please adjust the paths and variables according to your needs.

  • INFORMIXDIR=/opt/informix
  • ONCONFIG=/opt/informix/etc/onconfig

Installation steps:

  • First verify that the standard SEP sesam Backup Client is already installed
  • File system backup should work with this SEP sesam Client
  • Login as informix user
  • Create a new directory sib in \$INFORMIXDIR
  • Unpack the file <OS>_ssib_x.x.x.x.tgz there
  • Create a symbolic link in \$INFORMIXDIR/lib to the unpacked library file ibsad001.so. If file already exists, rename it first.
 informix@linux:~> cd $INFORMIXDIR
 informix@linux:/opt/informix> mkdir sib
 informix@linux:/opt/informix> cd sib
 informix@linux:/opt/informix/sib> tar xzf /tmp/linux_sib.2.3.1.1.tgz
 informix@linux:/opt/informix> cd ../lib
 informix@linux:/opt/informix/lib> ln -s ../sib/ibsad001.so
  • PATH environment variable should include \$INFORMIXDIR/bin
  • Check the backup/restore specific entries in the ONCONFIG file:

BAR_BSALIB_PATH Path to installed SEP sesam library

Example (Linux):

 ...
 # Backup/Restore variables
 BAR_ACT_LOG             /opt/informix/log/bar_act.log
 #BAR_MAX_BACKUP         0
 BAR_MAX_BACKUP          4
 #BAR_RETRY              3
 BAR_RETRY               2
 BAR_NB_XPORT_COUNT      10
 BAR_XFER_BUF_SIZE       31
 BAR_BSALIB_PATH /opt/informix/lib/ibsad001.so
 BAR_DEBUG       3
 BAR_DEBUG_LOG   /opt/informix/log/xbsa.log
 ....

Installation on Windows

Installation steps:

  • First verify that the standard Windows SEP sesam Backup Client (x64 or x86) is already installed
  • File system backup should work with this SEP sesam Client
  • Login as informix user
  • Extract the appropriate libbsa.dll from SEP download SEP sesam Extension for Informix - Windows (ZIP archive) - either x64 or x86 and copy it into SEP sesam gv_ro_bin:bin\sesam directory.
  • Edit the instance specific onconfig file and set the BAR_BSALIB_PATH to the libbsa.dll.
Attention

The path to libbsa.dll must use the short notation if SEP sesam is installed in a path with blanks, e.g. 'C:\Program Files\SEPsesam\bin\sesam'. dir /X C: may be used to get the short name notation!

Example (Windows):

  • INFORMIXDIR=C:\PROGRA~1\IBM\Informix\11.70
  • ONCONFIG=%INFORMIXDIR%\etc\ONCONFIG.ol_myinst
 ...
 # Backup/Restore variables
 BAR_ACT_LOG		C:\PROGRA~1\IBM\Informix\11.70\bar_ol_myinst.log	#Path of log file for onbar.exe
 BAR_DEBUG_LOG		C:\PROGRA~1\IBM\Informix\11.70\bar_ol_myinst.log	#Path of the debug log for onbar.exe
 BAR_DEBUG 0
 #BAR_MAX_BACKUP         0
 BAR_MAX_BACKUP          2
 #BAR_RETRY              1
 BAR_RETRY               2
 BAR_NB_XPORT_COUNT 20
 BAR_XFER_BUF_SIZE 15
 RESTARTABLE_RESTORE ON
 BAR_PROGRESS_FREQ 0
 BAR_BSALIB_PATH	C:\PROGRA~1\SEPsesam\bin\sesam\libbsa.dll	# Location of SEP sesam LIBBSA DLL
 BACKUP_FILTER
 RESTORE_FILTER
 BAR_PERFORMANCE 0
 BAR_CKPTSEC_TIMEOUT 15
 ...

Common Installation Steps

Attention

In the instance specific ONCONFIG file the BAR_MAX_BACKUP gives the number of parallel backup sessions. BAR_MAX_BACKUP must be set at least to '2'. Otherwise a restores will NOT work!

To set the version of XBSA specification SEP sesam supports, the following entry has to be inserted in table bar_version on sysutils database.


bar_version
bsa_version
bar_sm
sm_version
1
1.0.1
sesam
1

Instead of inserting this entry into database you can also adopt the INFORMIX template file.

  • Copy template file \$INFORMIDIR/etc/sm_versions.std to \$INFORMIXDIR/etc/sm_versions
  • Add the following line 1|1.0.1|sesam|1|
informix@linux:/opt/informix/> cd $INFORMIDIR/etc>
informix@linux:/opt/informix/etc> cp sm_versions.std sm_versions
informix@linux:/opt/informix/etc> vi sm_versions
informix@linux:/opt/informix/etc> cat sm_versions
#1|1.0.1|ism|1|
1|1.0.1|sesam|1|
informix@linux:/opt/informix/etc>
Info

For the usage of SEP sesam command events, the login scripts of the Informix users should not expect any inputs!

Configuration on SEP sesam Server

Create a new backup task for the Informix server. For backup source you must specify the Informix Instance. The instance should map to the instance which is used during ONBAR backup command. By selecting the source, the task type and task name are set automatically.

Configuration on Informix server

To give ONBAR the necessary information to connect to SEP sesam, the following environment variables have to be set.

Mandatory parameters

  • INFORMIXDIR (set by Informix installation).
  • SESAM_SERVER=<Name of SEP sesam Server>
  • SESAM_JOB=<Jobname of Informix backup> # Name of an already configured task on SEP sesam Server with task type Informix
  • SESAM_POOL=<Media pool name> # Name of an already configured media pool on SEP sesam Server

Optional parameters

  • XBSA_TRACE=<Trace level> (0|1|2) (if set with +10000000 then process logs to STDERR, e.g. 'set XBSA_TRACE=10000002')
  • XBSA_LOGFILE=<Name of trace file>

Although XBSA_TRACE XBSA_LOGFILE are not mandatory, they should be set to get information in case of a problem during backup or restore. For a restore only SESAM_SERVER and SESAM_JOB are mandatory.

ONBAR Backup Configuration

The following examples show, how backup or restores can be started on Informix server. They do not cover all functions of ONBAR, but should give some hints for using ONBAR and SEP sesam together.

Attention

The return code of onbar always has to be checked, because onbar writes no error messages to STDERR! The meaning of the return codes can be found in the Informix Backup and Restore Guide under Appendix A: ON-Bar Messages and Return Codes. You have to be informix or root to use onbar.

  • Backup of tablespace dbspace01
informix@linux:/opt/informix/> export SESAM_SERVER=backupsrv
informix@linux:/opt/informix/> export SESAM_JOB=informix_ts
informix@linux:/opt/informix/> export SESAM_POOL=DISK
informix@linux:/opt/informix/> onbar -b -L 0 dbspace01
informix@linux:/opt/informix/> echo $?
0
informix@linux:/opt/informix/>

The commands shown in the following example:

Perform a level 0 backup of "'dbspace01"' on an Online Dynamic Server instance named venus. Backup all logical log files associated with dbspace01, close and backup the current logical log

setenv SESAM_SERVER jupiter 
setenv INFORMIXDIR /usr/informix 
setenv INFORMIXSQLHOSTS \$INFORMIXDIR/etc/sqlhosts 
setenv ONCONFIG onconfig.std
onbar -b -L 0 dbspace01 
onbar -b -l -c
Info
The SEP sesam Extension for Informix - Windows ZIP archive contains the sbc_onbar.cmd which is suitable to backup Informix instances via SEP Sesam Command Events by adapting INFORMIX_... and SESAM_... values.
The given arguments are passed to onbar command, so typical calls are "sbc_onbar.cmd -b -L 0", or "sbc_onbar.cmd -v".

ONBAR Restore Configuration

ONBAR commands to restore data backed up. The shared XBSA library translates Informix names passed by ONBAR into SESAM server save set (a set of files) for retrieval from the SESAM server's database and restoration to Informix.


Physical Restore:

setenv SESAM_SERVER jupiter 
setenv INFORMIXDIR /usr/informix 
setenv INFORMIXSQLHOSTS \$INFORMIXDIR/etc/sqlhosts 
setenv ONCONFIG onconfig.std
onbar -r -p

Physical restores replace lost or corrupted storage spaces from SESAM backup media.

If a critical storage space is damaged because of a disk failure or corrupted data, Dynamic Server goes off-line.

If a disk failure or the corruption of data does not cause the database server to go to off-line mode you can restore any noncritical storage spaces.


Logical Restore:

SESAM_SERVER=jupiter 
export SESAM_SERVER
onbar -r -1

Logical restores recover the server transactions made since the last storage space backup, followed by a rolling forward of the logical logs backed up for the storage space. If different backup sessions are involved, the log rolls forward transactions made since the backup time recorded for each storage space are restored.


Combined Restore:

SESAM_SERVER=jupiter 
export SESAM_SERVER
onbar -r

Combined restores allow you to issue a single command to perform a physical restore immediately followed by a logical restore. For finer control, use the onbar -b -l -s command to salvage the logs, then the onbar -r -p command to perform only a physical restore, and then the onbar -r -l command to perform only a logical restore.


Point-in-time Restore:

setenv SESAM_SERVER jupiter
onbar -r -t time -w -p

Point-in-time restores involve performing a whole-system, physical restore of Informix data from a whole-system-backup to a specified time instead of the default, which is time of the last Informix backup.

There are two different kinds of restore you can perform in dependence of Informix Dynamic Server current mode. If the server is in quiescent mode or is on-line, you can perform a warm restore (Use the -O option to restore an on-line storage space). Otherwise, if server resides in off-line mode, the restore operation is called a cold restore.

For example Logical Log:

onbar -l -L 0 dbspace01

Backup and Restore Overview

Here the commands are given for the following scenarios.


Backup of database

Complete backup of database (if necessary start the database with oninit -v)

onbar -b -w  [-L n]
n - Backup Level (0, 1, 2), default is 0.

Backup of a single dbspace

onbar -b [-L n] 
n - Backup Level (0, 1, 2), default is 0.
dbspace_name - Name of the Informix dbspace instance

Logical Logfiles Backup

onbar -b -l     - Backup of all full logical logfiles
onbar -b -l -c  - Backup of the actual logical logfiles and switch to the next logical logfile.
onbar -b -l -s  - Backup of all logical logs, which reside on the hard disk after a crash of the database.


Database Restore

Restore of the whole database (cold restore)

onmode -ky   - Shutdown of the database
onbar -r -w  - Restore of all data 

Restore of the down dbspaces and corresponding logical logs (cold)

onbar -r

Restore of the down dbspaces without logical logs (cold)

onbar -r -p

Restore of single dbspaces

onbar -r <dbspace_name_1> <dbspace_name_2> 

Restore of the logical logs (for dbspaces, wich have been restored physically)

onbar -r -l
Info

If chunk areas have been deleted the option -O should be used, this could eventually restore the chunk areas:

onbar -r ... -O

Occasionally no checkpoint is written because of the missing chunk. This situation can be avoided with:

onmode -O

or by shutting down the database with a following cold restore.

Troubleshooting

For troubleshooting Informix issues, see Troubleshooting Informix.

Further Links/Literature