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.
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 theget_config
action command to as a location on the file system to store the response of the underline http call (it's eithertext/plain-text
orapplication/json
) backup of the current configurations. This file that gets created is often the source ofconfiguration changes using theset_config
action 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 PSMdb
directory an anapi.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 abkup_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.
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
andset_config
can be issued asget config
andset 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 whenget_config
is invoked, so uncomment to change. I personally comment out all the properties im not changing when Iset_config
.
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.
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.
sudo /var/opt/oracle/bkup_api/bkup_api bkup_status
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.
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
TODO -
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 becauseORACLE_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.
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
view /u01/data/domain/<servername>_domain/ua_logs