A short introduction to Oracle's bkup_api utility. Directory structure is based on an Oracle DBaaS Classic VM 12.2.2

A Short Primer to the Oracle bkup_api Utility.md

A Short Primer to Using the bkup_api Utility

If you are using Oracle Cloud you should be using the PSM for all of your Object Storage Container ( OSS ) and DBaaS Instance for all your backup needs. You should submit a support request before troubleshooting any of these issues, especially if you don't have a dev instance. The absolute path's I use in here are based off how a PSM provisioned instance of Oacle Cloud's DBaaS 12.2 Single Instance installed on Oracle Linux.

Path and Structure

The bkup_api is located in the /var/opt/oracle/bkup_api directory. If you intend to learn this utility on a development VM I suggest the first command you run is sudo -s. You will need to be root for the entirety of this post. You can run an ls -ltra to see the directory structure, but the only pertinent files/directories

• drwxr-x---. 2 root root 4096 Mar 26 2019 log
• -r-xr-xr-x. 1 oracle oinstall 1148 Oct 3 21:45 README
• -r-xr-xr-x. 1 oracle oinstall 42710 Oct 3 21:45 bkup_api
• drwxr-xr-x. 2 oracle oinstall 4096 Oct 21 06:22 cfg
• drwxr-xr-x. 2 oracle oinstall 4096 Oct 28 19:26 lib
• -rw-rw----. 1 root root 189132 Nov 10 03:20 sqlplus.log
• -rw-rw----. 1 root root 9878 Nov 10 03:20 backups.rec
• drwx------. 2 root root 4096 Nov 11 02:31 tmpl
• drwxrwxrwx. 2 root root 4096 Nov 11 02:31 db

The directories are mostly self explanatory.

• cfg directory contains a configuration file ( one of multiple ways to configure your OSS container endpoint, authorize, and access it ).
• tmpl directory is used by the get_config action command to as a location on the file system to store the response of the underline http call (it's either text/plain-text or application/json) backup of the current configurations. This file that gets created is often the source ofconfiguration changes using the set_configaction command.
• backup.rec is new line row delimited, comma separated line delimited record of each time the utility has ran. Eech line contains the process id, the RMAN tag, and a date/time stamp,. respectively.
• lib contains the type of python files you end in .py. In other words, by convention ( on Oracle Linux ) a utility will not contain an extentions even if it is perl, python, etc script. However, the utility is usually just contains a main method that then uses the python depedencies in the lib folder to componentize the application.
• log contains the log, except the ../sqllog.log file which I believe is written to by RMAN during a backup process issued from the PSM
• db directory an an api.db file that is likely a sqllite file ( feel free to open it an issue a pull to this doc! ).
• sqlplus.log is a log file written when the bkuo_api utility is executed by the RMAN and SQLPLUS utilities.
• README is a useless file written by someone who was over-worked and late on 5 projects. Basically the file tells you that the log directory contains a log file, and mentions a bkup_api_testing.py file for unit testing that doesn't exist. It then mentiones config options for a completely different utility and finishes with a section about the unit test script that is non existant.

Get and Set Utilities Configuration

Get Configurations

Before running the utilities core action commands you must first confgiure a variety of properties inclduing your OSS endpoint, the credentials for a user with at least write access set in the Oracle Cloud's Admin Console. Additionally you can configure storage policies and other Ops related settings. This must be before using the utility, and is also used for making periodic changes.

The best practice for configuring this utility is not to use the cfg file. This is strictly for security reasons, as you would be required to save your clear text password in a text file if you went the cfg route. However, with that said, if there is a particular need to utilize then mileage may vary.

Before we can execute the utility we must first configure the required fields: host, username, passsword aand may wish to configure the non require fields. To get the configuration file run the folloiwing command

sudo /var/opt/oracle/bkup_api/bkup_api get_config

Both get_config and set_config can be issued as get config and set config, respectively. Additionally, by default the file exports as a plain text key/value pair file, however there are command line arguments that allow you to specify json instead.

Executing the get_config t a few lines to stdout, append the log, and create a ./tmpl/bkup-ORCL-\d\d\d\d\-\d\d\d.cfg. The exact location of this file is written to stdout. We must modify this file to set our configurations. Open it in vim and modify accordingly. I have posted suggested modifications, leaving out system variables to be filled in by you

 bkup_cron_entry=yes
 bkup_cfg_files=yes
 bkup_daily_time=2:59
 bkup_disk=yes
 bkup_disk_recovery_window=7 
 bkup_oss=yes
 bkup_oss_l0_day=Sun
 bkup_oss_recovery_window=30
 bkup_oss_url=https://lathamoic.us.storage.oraclecloud.com/v1/Storage-lathamoic/dbcs-serivceinstancename-usually
 bkup_oss_user=
 bkup_oss_passwd=

The file is basically a key/value pair of configurations. For anything marked yes also accepts no, the bkup_disk_recovery_window key allows values [7, 14] ( set notation ). bkup_disk_recovery_window takes in the ISO abbreviation for day. As part of automated backups a level 0 database copy ( not incremental ) is created and uploaded to OSS every [1, 30] days. The plain text file has the bkup_oss_passwd key commented out when get_config is invoked, so uncomment to change. I personally comment out all the properties im not changing when I set_config.

Set Configurations

Now that we have set our key/value pairs, we can fianlize the setup by issuing the set_config action with the new configurations.

To update the configurations I usually cd ./tmpl and then run

sudo /var/opt/oracle/bkup_api/bkup_api set_config -i bkup-ORCL-\d\d\d\d\-\d\d\d.cfg

You can check that the configurations are well formed by using the bkup_chkcfg command.

sudo /var/opt/oracle/bkup_api/bkup_api bkup_chkcfg

If you attempt to set invalid configurations using set_config you will get an error thrown in stdout as well as the log, so this action is used more when bkup_api is used as part of a larger solution.

Functionality After Configuration

Status and More

The first thing I recommend is to always check the status of a backup ( to see if one is running or not ). Two possbile solutions listed below: the first utilizes the bkup_api utility, and the second checks the truthfulness of the utility.

1. sudo /var/opt/oracle/bkup_api/bkup_api bkup_status
2. sudo ps aux | grep bkup_api

By executing the help you will get an unordered list of the utilities actions sudo /var/opt/oracle/bkup_api/bkup_api help

• list
• bkup_start, bkup_chgcfg, bkup_chkcfg, bkup_delete
• set config
• get config
• reval_start
• archreval_start
• recover_start
• update_wallet
• update_wallet_status
• bkup_status (Compatibility mode v1)
• recover_status (Compatibility mode v1)
• --rargs (Compatibility mode v1)

To start a backup to the OSS container as specified in the config file or CLI flags ( I don't know the precedence ) run the following command sudo /var/opt/oracle/bkup_api/bkup_api bkup_start

You can add a --keep flag to for JAAS forever backup, but the dbaasapi and bkup_api do not work with

The output of this utility writes to obkup.log and other files in ./logs directory. For example, you can tail the log.

tail -n 1000 -f /var/opt/oracle/bkup_api/logs/log.out

As mentioned, after starting a process you can check it's status by grepping ps and running the bkup_status command.

Failure

As always, any failed action will have a signature in the log. You will first want to check if your application is still up and running correctly. If you ran an action command that broke the application, and the log does not indicate anything else, you can attemtp to recover the latest back from your storage container using the following command

sudo /var/opt/oracle/bkup_api/bkup_api recover_start --latest

Depnding on your version this may require an additional --dbname parameter. If it does, specify the appropriate database name. You also have the option to recover the last confg file by adding a --config flag.

In Oracle Integration Cloud, there is generally only one Plugable Database ( PDB ) privisoned for single instance achitectures, and by default it's named PDB1. The MDS, SOAINFRA, OPSS, and many other very important schemas belong to PDB1. Therefore, and optional --pdb flag is also available. Depending on the specific issue, a recover action may be isseud with all these flags as seen below.

sudo /var/opt/oracle/bkup_api/bkup_api recover_start --latest --dbname=ORCL --pdb=PDB1

Wallets

TODO -

Tooling

You will find most of these utilities in /var/opt/oracle. Most of the tools are simply Oracle Linux utilities, scripted to send HTTP requests and print the results to standard out. A similar utility is dbaasapi, 'oss', 'dbaascli, and also contains the an very important .ini file in the ./creg directory. Generally the absolute path to the file is var/opt/oracle/creg/ORCL.ini. However, if during provisioning you gave the database a different unique name, you would neeed to

/var/opt/oracle/creg/'printenv ORACLE_UNQNAME`.ini

You may need to use the ORACLE_SID1 environment variable because ORACLE_UNQNAME was added

I mention this file because it contains, among other things, around 15 key/value pairs that may or may not affect the bkup_api depending on specific configuration parameters and precedence of those parameters.

Backup Logs

cd /u01/data/backup view LastOperation.log view LastOperation.log.history

Additionally you should see a zip file in the following format MM-DD-YY.zip

Upgrade Logs

view /u01/data/domain/<servername>_domain/ua_logs