Tutorial on Basic Usage of onbar in GBase 8s Database

Data backup and recovery are critical for ensuring data security and business continuity. Onbar, a scalable backup product for the GBase 8s database, offers a comprehensive data protection solution. Unlike ontape, onbar requires integration with a storage manager and involves a series of configuration steps. This article will detail the configuration, backup, recovery, and monitoring processes of onbar to help GBase database administrators develop data backup and recovery plans.

Before using onbar, users need to perform the following configuration steps:

1. Configure the storage manager
2. Set appropriate ONCONFIG parameters for onbar
3. Determine the logical log backup strategy

1. Configuring Storage Manager and onbar

Onbar and the storage manager are connected via the XBSA (X/Open Backup Services) interface, allowing onbar to work with any storage manager that complies with XBSA. GBase 8s also comes with a built-in storage manager, PSM (Primary Storage Manager), whose interface library is located at $GBASEDBTDIR/lib/libbsapsm.so.

[root@gbase ~]# ll $GBASEDBTDIR/lib/libbsapsm.so
-r-xr-xr-x 1 gbasedbt gbasedbt 1920732 Mar 23  2021 /home/hdr/lib/libbsapsm.so

Modifying the onbar Configuration File

To use onbar, some simple configuration is required. The configuration parameters are as follows:

Parameter	Description
BAR_BSALIB_PATH	Specifies the location of the XBSA library
BAR_MAX_BACKUP	Maximum number of parallel processes
LTAPEDEV	Logical log backup directory

These parameters can be viewed and modified by editing the file $GBASEDBTDIR/etc/$ONCONFIG or using the online mode commands onstat -c | grep BAR_BSALIB_PATH and onmode -wf BAR_BSALIB_PATH=$GBASEDBTDIR/lib/libbsapsm.so.

Generally, the parameters can be set as follows:

Parameter	Setting
BAR_BSALIB_PATH	$GBASEDBTDIR/lib/libbsapsm.so
BAR_MAX_BACKUP	0
LTAPEDEV	$GBASEDBTDIR/backups

Here, BAR_MAX_BACKUP can be adjusted based on actual performance needs, and LTAPEDEV is a parameter from ontape. When using onbar, this parameter should not be /dev/null. A temporary directory can be set, but in practice, logical logs are not stored in this directory.

[root@gbase ~]# onmode -wf BAR_BSALIB_PATH=$GBASEDBTDIR/lib/libbsapsm.so
Your evaluation license will expire on 2024-10-18 00:00:00
Current value for BAR_BSALIB_PATH (/home/hdr/lib/libbsapsm.so) was saved in config file.
[root@gbase ~]# onmode -wf BAR_MAX_BACKUP=0
Your evaluation license will expire on 2024-10-18 00:00:00
Current value for BAR_MAX_BACKUP (0) was saved in config file.
[root@gbase ~]# onmode -wf LTAPEDEV=$GBASEDBTDIR/backups
Your evaluation license will expire on 2024-10-18 00:00:00
Current value for LTAPEDEV (/home/hdr/backups) was saved in config file.

[root@gbase ~]# onstat -c | grep BAR_BSALIB_PATH
Your evaluation license will expire on 2024-10-18 00:00:00
# BAR_BSALIB_PATH     - The shared library for ON-Bar and the
BAR_BSALIB_PATH /home/hdr/lib/libbsapsm.so
[root@gbase ~]# onstat -c | grep BAR_MAX_BACKUP
Your evaluation license will expire on 2024-10-18 00:00:00
# BAR_MAX_BACKUP      - The number of backup threads used in a
BAR_MAX_BACKUP  0
[root@gbase ~]# onstat -c | grep LTAPEDEV
Your evaluation license will expire on 2024-10-18 00:00:00
# LTAPEDEV     - The tape device path for logical logs
LTAPEDEV        /home/hdr/backups

Enabling and Configuring PSM Device

Initialize the catalog using onpsm -C init.

[root@gbase /]# ll $GBASEDBTDIR/etc/psm
ls: cannot access /home/hdr/etc/psm: No such file or directory
[root@gbase /]# onpsm -C init
 The __PSM__ catalog is not present in the '/home/hdr/etc/psm/' directory.
The system will try to create it.
 __PSM__ catalog creation in the '/home/hdr/etc/psm/' directory succeeded.
This option deletes the __PSM__ catalogs.
Are you sure you want to delete these items? (y/n) n
[root@gbase /]# ll $GBASEDBTDIR/etc/psm
total 60
-rw-rw-r-- 1 gbasedbt root 1024 Aug 18 15:50 device.dat
-rw-rw-r-- 1 gbasedbt root 5120 Aug 18 15:50 device.idx
-rw-rw-r-- 1 gbasedbt root 1024 Aug 18 15:50 lock.dat
-rw-rw-r-- 1 gbasedbt root 2048 Aug 18 15:50 lock.idx
-rw-rw-r-- 1 gbasedbt root    0 Aug 18 15:50 object.dat
-rw-rw-r-- 1 gbasedbt root    0 Aug 18 15:50 object_detail.dat
-rw-rw-r-- 1 gbasedbt root 3072 Aug 18 15:50 object_detail.idx
-rw-rw-r-- 1 gbasedbt root 4096 Aug 18 15:50 object.idx
-rw-rw-r-- 1 gbasedbt root    0 Aug 18 15:50 pool.dat
-rw-rw-r-- 1 gbasedbt root 4096 Aug 18 15:50 pool.idx
-rw-rw-r-- 1 gbasedbt root 1024 Aug 18 15:50 serial.dat
-rw-rw-r-- 1 gbasedbt root 2048 Aug 18 15:50 serial.idx
-rw-rw-r-- 1 gbasedbt root 1024 Aug 18 15:50 session.dat
-rw-rw-r-- 1 gbasedbt root 3072 Aug 18 15:50 session.idx
-rw-rw-r-- 1 gbasedbt root 1024 Aug 18 15:50 volume.dat
-rw-rw-r-- 1 gbasedbt root 5120 Aug 18 15:50 volume.idx

View backup directory information and customize it to other directories.

[root@gbase hdr]# onpsm -D list

__PSM__ Device List

Type    Prio     Block/Size (MB)  Pool Name     Device Name
FILE    LOW          --/--        DBSPOOL       /home/hdr/backups

FILE    LOW          --/--        LOGPOOL       /home/hdr/backups

[root@gbase hdr]# onpsm -D add $GBASEDBTDIR/dbspool -g DBSPOOL -p HIGHEST -t FILE
[root@gbase hdr]# onpsm -D add $GBASEDBTDIR/logpool -g LOGPOOL -p HIGHEST -t FILE
[root@gbase hdr]# onpsm -D del $GBASEDBTDIR/backups -d
Delete the device from ALL pools and DELETE ALL backup objects stored in
FILE devices? (y/n) y
[root@gbase hdr]# onpsm -D list

__PSM__ Device List

Type    Prio     Block/Size (MB)  Pool Name     Device Name
FILE    HIGHEST      --/--        DBSPOOL       /home/hdr/dbspool

FILE    HIGHEST      --/--        LOGPOOL       /home/hdr/logpool

2. Detailed onbar Backup Commands

Backup & Verification

-b [-p] [-L <level>] [-w | -f <filename> | <spaces>] [-O] [-cf yes | no | only]
-b -F
-b -l [-c | -C | -s] [-O]
-v [-w] [-p] [-t <time>] [-f <filename> | <spaces>]

• -b: Initiates the backup process.
• -c: Backs up the current logical logs.
• -C: Starts continuous logical log backups.
• -cf: Backs up critical files.
• -f: Specifies the path and filename of the file containing the storage space list.
• -F: Performs a simulation backup (does not actually write backup data).
• -l: Backs up only the complete logical logs (excludes storage spaces).
• -L: Sets the backup level to 0, 1, or 2, with 0 as the default.
• -O: Overrides internal error checks and enforces execution.
• -p: Backs up only the storage spaces (excludes logs).
• -s: Recovers logs (possibly recovering from a failure).
• -t: Specifies the time point for consistency verification.
• -v: Verifies the consistency of the specified backup.
• -w: Performs a full system backup.
• <spaces>: Specifies the storage spaces to be backed up, separated by spaces.

RESTORE

-r [-e] [-O | {rename-chunk-syntax}] [-w] [-p] [-cf yes|no|only]
    [-t "<time>" | -n <log>] [-f <filename> | <spaces>]
-r -l [-C | -X | -t "<time>" | -n <log>]
-RESTART
rename-chunk-syntax:
{-rename -f <filename> | -p <old_path> -o <old_offset> -n <new_path> -o <new_offset>...}

• -r: Initiates the restore process.
• -C: Starts/restarts continuous log recovery (puts the server in fast recovery mode when logs are exhausted).
• -cf: Restores critical files (during cold recovery).
• -e: Performs external recovery.
• -f: Specifies the path and filename of the file containing the list of storage spaces to be restored.
• -l: Restores only the logical logs (excludes storage spaces).
• -n: Restores to the specified logical log.
• -O: Overrides internal error checks and forces recovery operations blocked by errors.
• -p: Restores only the physical space (excludes or rescues logs).
• -t: Restores to the specified time point, enclosed in quotes.
• -w: Restores the full system backup.
• -X: Stops continuous logical log recovery and puts the server in quiescent mode.
• -RESTART: Restarts an interrupted recovery process.
• -rename: Renames the specified chunks during cold recovery. The chunk information options can be repeated.
• <spaces>: Specifies the storage spaces to be restored, separated by spaces.

RECENT ACTIVITY

-m [<lines>] [-r [<seconds>]]

• -m: Displays the last specified number of lines from the onbar activity log file, with a default of 20 lines.
• -r: Repeats the command every specified number of seconds, with a default of 5 seconds.

LOGICAL-LOG DISPLAY

-P {-n <log unique identifier> | -n <starting log unique identifier> - <ending log unique identifier>}

• -P: Displays logical log information.
• -n: Specifies the unique identifier of the logical log to display, or a range of logical log unique identifiers.

3. Basic onbar Usage Practice

To perform a level 0 backup of the database using onbar -b -L 0, you can use tail -f $GBASEDBTDIR/tmp/bar_act.log to monitor the backup logs in real-time.

[root@gbase hdr]# onbar -b -L 0
Your evaluation license will expire on 2024-10-18 00:00:00

Viewing Backup Directories dbspool and logpool

[root@gbase gbase002]# cd $GBASEDBTDIR/dbspool
[root@gbase dbspool]# ll
total 0
drwxr-x--- 8 gbasedbt gbasedbt 105 Aug 18 14:58 gbase002
[root@gbase dbspool]# ll gbase002/
total 0
drwxr-x--- 6 gbasedbt gbasedbt 64 Aug 18 14:58 critical_files
drwxr-x--- 3 gbasedbt gbasedbt 15 Aug 18 14:58 datadbs1
drwxr-x--- 3 gbasedbt gbasedbt 15 Aug 18 14:58 llogdbs
drwxr-x--- 3 gbasedbt gbasedbt 15 Aug 18 14:58 plogdbs
drwxr-x--- 3 gbasedbt gbasedbt 15 Aug 18 14:58 rootdbs
drwxr-x--- 3 gbasedbt gbasedbt 15 Aug 18 14:58 sbspace1
[root@gbase dbspool]# cd $GBASEDBTDIR/logpool
[root@gbase logpool]# ll
total 0
drwxr-x--- 3 gbasedbt gbasedbt 17 Aug 18 14:58 gbase002

You can also view this using onpsm -O list.

[root@gbase logpool]# onpsm -O list
__PSM__ Object List
Object ID            Date Created         Size (MB) Logical path (name.version)
1                    2024-08-18 14:58:14       20.0 /gbase002/rootdbs/0/gbase002.1
2                    2024-08-18 14:58:15        0.1 /gbase002/sbspace1/0/gbase002.1
3                    2024-08-18 14:58:16        0.1 /gbase002/llogdbs/0/gbase002.1
4                    2024-08-18 14:58:16        8.5 /gbase002/datadbs1/0/gbase002.1
5                    2024-08-18 14:58:17        0.1 /gbase002/plogdbs/0/gbase002.1
6                    2024-08-18 14:58:17      128.5 /gbase002/199/7/gbase002.1
7                    2024-08-18 14:58:18        0.0 /gbase002/critical_files/ixbar/gbase002.1
8                    2024-08-18 14:58:18        0.0 /gbase002/critical_files/oncfg/gbase002.1
9                    2024-08-18 14:58:18        0.1 /gbase002/critical_files/onconfig/gbase002.1
10                   2024-08-18 14:58:18        0.0 /gbase002/critical_files/sqlhosts/gbase002.1

Now, suppose the database has been corrupted. Here, we simulate the deletion of dbspace files.

[root@gbase logpool]# cd $GBASEDBTDIR/gbase001_dbs
[root@gbase gbase001_dbs]# ll
total 24944548
-rw-rw---- 1 gbasedbt gbasedbt   104857600 Aug 18 14:27 datadbs1_1
-rw-rw---- 1 gbasedbt gbasedbt 10485760000 Aug 18 15:12 llogdbs
-rw-rw---- 1 gbasedbt gbasedbt 10485760000 Aug 18 15:12 plogdbs
-rw-rw---- 1 gbasedbt gbasedbt   209715200 Aug 18 15:12 rootdbs
-rw-rw---- 1 gbasedbt gbasedbt  2128609280 Aug 18 14:26 sbspace1
-rw-rw---- 1 gbasedbt gbasedbt  2128609280 Aug 18 15:00 tmpdbs1
[root@gbase gbase001_dbs]# rm -rf *
[root@gbase gbase001_dbs]# ll
total 0

In this situation, since we deleted system files, we need to manually recreate the deleted files and set the correct permissions.

[root@gbase gbase001_dbs]# touch datadbs1_1 llogdbs plogdbs rootdbs sbspace1 tmpdbs1
[root@gbase gbase001_dbs]# ll
total 0
-rw-r--r-- 1 root root 0 Aug 18 15:23 datadbs1_1
-rw-r--r-- 1 root root 0 Aug 18 15:23 llogdbs
-rw-r--r-- 1 root root 0 Aug 18 15:23 plogdbs
-rw-r--r-- 1 root root 0 Aug 18 15:23 rootdbs
-rw-r--r-- 1 root root 0 Aug 18 15:23 sbspace1
-rw-r--r-- 1 root root 0 Aug 18 15:23 tmpdbs1
[root@gbase gbase001_dbs]# chown gbasedbt:gbasedbt *
[root@gbase gbase001_dbs]# ll
total 0
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 datadbs1_1
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 llogdbs
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 plogdbs
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 rootdbs
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 sbspace1
-rw-r--r-- 1 gbasedbt gbasedbt 0 Aug 18 15:23 tmpdbs1
[root@gbase gbase001_dbs]# chmod 660 *
[root@gbase gbase001_dbs]# ll
total 0
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 datadbs1_1
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 llogdbs
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 plogdbs
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 rootdbs
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 sbspace1
-rw-rw---- 1 gbasedbt gbasedbt 0 Aug 18 15:23 tmpdbs1

Execute the recovery command:

[root@gbase gbase001_dbs]# onbar -r
Your evaluation license will expire on 2024-10-18 00:00:00
Your evaluation license will expire on 2024-10-18 00:00:00

At this point, you can see that the dbspace file sizes have been restored:

[root@gbase gbase001_dbs]# ll
total 24944552
-rw-rw---- 1 gbasedbt gbasedbt   104857600 Aug 18 15:38 datadbs1_1
-rw-rw---- 1 gbasedbt gbasedbt 10485760000 Aug 18 15:38 llogdbs
-rw-rw---- 1 gbasedbt gbasedbt 10485760000 Aug 18 15:38 plogdbs
-rw-rw---- 1 gbasedbt gbasedbt   209715200 Aug 18 15:38 rootdbs
-rw-rw---- 1 gbasedbt gbasedbt  2128609280 Aug 18 15:38 sbspace1
-rw-rw---- 1 gbasedbt gbasedbt  2128609280 Aug 18 15:38 tmpdbs1

After the recovery is complete, the database will enter Quiescent mode. Use onmode -m to switch to online mode.

[root@gbase201 /]# onstat -
Your evaluation license will expire on 2024-10-18 00:00:00
Quiescent -- Up 00:24:14 -- 57688756 Kbytes

[root@gbase201 /]# onmode -m
Your evaluation license will expire on 2024-10-18 00:00:00
[root@gbase201 /]# onstat -
Your evaluation license will expire on 2024-10-18 00:00:00
On-Line -- Up 00:24:23 -- 57688756 Kbytes

At this point, the database recovery is complete.

Through this detailed introduction, we hope to help database administrators better understand and use onbar, thereby providing a solid guarantee for the data security and business continuity of enterprises. Thank you for reading.