dmk_rman.{ksh|cmd}

This chapter presents the RMAN wrapper script dmk_rman{ksh|cmd}.

All scripts have a detailed synopsis. Please check the option “-h” or “--help”.

dmk_rman.ksh and dmk_rman.cmd are OS-specific wrapper scripts to call the platform-independent dmk_rman.pl script.

🪟 for both cmd.exe and powershell: the dmk_rman.cmd script can be used.

The execution of dmk_rman.{ksh|cmd} requires a configuration file. See the template dmk_dbbackup/templates/rman.cfg. Per default, the script looks in ${DMK_ORA_ADMIN_SID}/etc/rman.cfg. If not found, it must be specified with parameter -t <path>/<file>

The script requires command lines argument(s) in addition to the configuration file. Some of the configuration file parameters are also available in command-line. The parameters given in command line are from higher priority compared to their configuration values. Which allows different behave using the same configuration file.

Example:

  • The default configuration parameter BackupType is bck_inc0.rcv, so the below command start an full incremental database backup level 0.

dmk_rman.ksh –s ${ORACLE_SID}

  • To launch an Archivelog Backup using the same configuration as above launch the script as follows

dmk_rman.ksh –s ${ORACLE_SID} –t bck_arc.rcv

Once all parameters have been computed dmk_rman starts to look at the specified RMAN rcv script and replace the placeholders with the value of the below parameters. In addition, some parameters are automatically generated by dmk_rman like the placeholder <START_DATE>.

Scheduling

DOS batch scripts can then be executed through the Windows Task Scheduler.

Example of Windows Task Scheduler configuration :

Getting started with “dmk_rman.{ksh|ps1}” requires to copy the template RCV scripts provided:

Please refer to the Appendix chapter, paragraph 9.4 Templates RCV for details.

⚠️Oracle 18c and 19c databases will be considered as been part of the oracle 12c family and therefore oracle12 rcv files will be used. Make sure to copy the appropriate needed rcv file into ${DMK_DBBACKUP}/rcv/oracle12.

ℹ️ The dmk_dbbackup result codes are :

  • OK : Prescript, rman backup, postscript are all OK

  • WARNING : rman backup is ok, but there is an error on either the prescript or the postscript

  • ERROR : There is an error with the rman backup (connection failure, backup, any RMAN-XXXXX errors.

Parameters

A hyphen character prefixes the command line parameters as they are be used within a shell.

–h or –help

Display the Synopsis.

–s or -–sid

The target database on which, the Oracle RMAN operation should be launched. This parameter is always required.

–u or –-usecatalog

With this option, there is now 2 ways left for doing backup with the catalog :

  • None

  • Always (default)

  • resync_only (has been deprecated)

Using this parameter is only possible with the CLI.

⚠️In case there is no catalog connection added into the rman configuration file, the backup will be done without catalog and this --usecatalog option will be ignored.

none option

When using “none” option, the catalog will not be used at all even if configured in the rman configuration file (default rman.cfg).

always option

When using “always” option, the catalog will be used during the whole backup process. A connection is made immediately at the beginning before doing the backup commands. This is the default option when usecatalog is not mentioned in the CLI and a catalog connection is configured in the configuration file (rman.cfg).

usecatalog always is the default option:

usecatalog always can still be used in the CLI:

In case the always option is enforced in the CLI albeit there is no catalog entry in the configuration file, the program will exit with an error 5026 - CLI use catalog value is always and there is no catalog configured. Exiting.

-usecatalog_continue_on_errors

A new parameter, --usecatalog_continue_on_errors, has been introduced and is only taken in account with the always option case. This parameter is only usable with command line (CLI). When added to the CLI, the backup will still move forward even if connection with the catalog is failing. The backup will move forward with the control_file as backup metadata, and will be usable.

ℹ️In case a backup script should not be completed without an available catalog connection as backup deletion for example, do not use --usecatalog_continue_on_errors option. The backup script will stop immediately on catalog connection error, will fail and no operation will be further performed. The backup result code is 1 (ERROR).

In case a backup script still needs to move forward even if the catalog is not available, as archive log backups for example, in order to avoid FRA management problem, add the --usecatalog_continue_on_errors option in the CLI. The backup script will generate an error on the catalog connection but will still move forward and be executed. The global backup dmk_dbbackup script result code will still be 1 (ERROR) due to the catalog connection issue but will be usable.

In case the --usecatalog_continue_on_errors is used and there is a catalog connection issue, the global dmk_dbbackup script will end with an error code even if the backup is successfully completed. Solving the catalog connection issue is still mandatory and still need high attention.

⚠️ Reminder about the dmk_dbbackup return codes :

  • OK : Prescript, rman backup, postscript are all OK

  • WARNING : rman backup is ok, but there is an error on either the prescript or the postscript

  • ERROR : There is an error with the rman backup (connection failure, backup, any RMAN-XXXXX errors.

use catalog always option without continue on errors:

use catalog always option with continue on errors:

In case of RMAN catalog failure and --usecatalog_continue_on_errors is not activated, the backup will fail and stop immediately:

In case of failure with the RMAN catalog and --usecatalog_continue_on_errors is activated, the backup will move forward as seen in the following log file. The backup will still end with a return code of 1 on a RMAN error to alert on the catalog problem which needs to be solved as soon as possible:

resync_only option

When using “resync_only”, the backup will be done without a catalog connection. The metadata will be stored in the control files and a resync between the control files and the catalog will be performed at the end, after the backup is completed. So 2 return codes will be seen in the log file. The first one for the backup and the second one for the resync. If the catalog is not available, the return code for the resync will show failure, but the backup could still be successful and usable.

Please note that this option has been deprecated and kept only for backwards compatibility. In case resync_only is used, a warning will now be displayed in the console. A warning note will also be added to the email body and will be sent according to the email configuration policy.

–c or –-configfile

The dbi services best practice consist of saving the configuration file under the database admin directory which makes the command-line parameter “ConfigFile” useless

Otherwise the command-line parameter becomes mandatory

Catalog

Target

–d or --channeltype

–n or --channelnbr

–p or –-channelparms

–t or –-backuptype

RetPolicy

Per default, an RMAN recovery window of 4 Days is set by DMK_DBBACKUP. This parameter can be set to a value less than the default if desired.

ArchDelPolicy

Per default, the RMAN ARCHIVELOG DELETION POLICY is set to “NONE”. This parameter can be set to a different value if required.

ArchDelPolicySTD

Per default, the RMAN ARCHIVELOG DELETION POLICY for the Standby is set to “APPLIED ON ALL STANDBY”. This parameter can be set to a different value if required.

Bck_Path

If the backup directory doesn’t exist, the RMAN operation will abort!

Fully qualified path without variable is expected if not taking default location.

BlckChangePath

Path used to store the block change tracking file. This parameter is used with the following rcv files:

bck_inc0_no_arc_del_blck_chg_trk.rcv

bck_inc1_blck_chg_trk.rcv

If BlckChangePath is configured and existing, let to the user the opportunity to put the block change tracking file in the desired destination folder If no BlckChangePath configured or not existing, default is to use the datafiles directory, which is the recommendation If none existing as last chance goes to backup path.

File name will be non omf but will be in the right datafile folder. If user really want OMF file naming he needs to change the rcv templates and remove using file option from the command.

NFSTimeout

With this parameter we can handle the NFS stalled problem, the process do exit if the timeout is reached!

Log_Path

If the log file directory doesn’t exist it will be automatically created, a warning message announce this operation.

Fully qualified path without variable is expected if not taking default location.

Nbr_Files_per_Set

Nbr_Files_per_Arc_set

Section_Size

–z or --compress

PreScript

This gives the possibility for the user to execute a batch script (windows) or a shell script (linux) before executing the backup.

⚠️If no full qualified path is given, but only the script name preceded by ./ for linux, dmk_rman is expected to be run in the current directory where the script is located. Otherwise, the user needs to give the full qualified path without using variables.

ℹ️DMK_DBBACKUP considers only the return code of the script to check whether the execution was successful or not.

PostScript

This gives the possibility for the user to execute a batch script (windows) or a shell script (linux) after executing the backup.

⚠️If no full qualified path is given, but only the script name preceded by ./ for linux, dmk_rman is expected to be run in the current directory where the script is located. Otherwise, the user needs to give the full qualified path without using variables.

ℹ️ DMK_DBBACKUP considers only the return code of the script to check whether the execution was successful or not.

Customer

-nosuccessmail

MailRecipients

SmtpServer

MailFrom

A hyphen character prefixes the command line parameters as they are being used within a shell.

Each parameter defined within the configuration file is automatically parsed at runtime and environment variables defined as values implicitly expanded. Syntax:

Real dbbackup implementation case example

This chapter is only intended to give an overview of an example of a dbbackup implementation during a consulting project. There is no intention to say it is the only way to perform an installation and all projects are different.

This installation applies to a configuration where:

  • Data Guard is in used

  • The system is composed with a primary (vmtestoradg1) and a least one standby (vmtestoradg2) database servers

  • The archive logs are stored in the FRA. Archive logs will not be deleted during the backup script, and we will rely on oracle to remove the archive logs made reclaimable if place is needed.

  • The backups are executed through the linux crontab.

  • We would like to run

    • at 22:00 every day an inc0 backup

    • every 4 hours an archived log backup.

    • every day at 06:00 a backup deletion

    • every 4 hours an archive log deletion policy changes on the standby to ensure the policy is set accordingly in case there were a recent switchover. No other backup script will be run on the standby database.

As we are using a configuration with 2 servers one for the primary and one for the standby we expect both servers to be configured the same way. Each server can one time hold either the primary database or the standby database.

Our instance is called DB19C. Our primary db_unique_name is DB19C_SITE1 when the standby db_unique_name is DB19C_SITE2. Our database version is 19c, therefore we will use the rcv template from the oracle12 folder. Reminder, all versions up to 12c use the rcv files from the oracle12 folder.

Archive log deletion policy

The archive log deletion policy will define when oracle will be able to setup an archive log as reclaimable in order to delete it if space is needed (more than 80% of the FRA is in used).

In our case, the archive log deletion policy will have to be configured as following:

  • “APPLIED ON ALL STANDBY BACKED UP 1 TIMES TO DISK” when the database is primary

  • “APPLIED ON ALL STANDBY” when the database is standby

Configure rman.cfg file

We will consider that the following directories were already created for the specific instance on both primary and standby servers:

We will then first copy the rman.cfg template which we will adapt as needed:

Backup path location

We will consider that the backups will be recorded in the default backup location (u01/app/oracle/admin/DB19C/backup). A symbolic link could be created in order to have the backup recorded in another file system, or the additional file system could be mounted as default backup location.

In that case we will not configure the BckPath parameter and leave it empty. In case we use a NFS shared drive, this parameter will need to be updated with the NFS mount point.

catalog

Recommendation is to use a catalog and have a catalog already deployed.

The catalog parameter will need to be updated as following in case of no catalog:

The catalog parameter will need to be updated as following in case a catalog is used:

Retention policy

Backup retention policy needs to be configured accordingly to the need. In our case we will keep the default 4 days value.

Channels

Knowing we are using EE Edition, we will configure disk channel type with 4 parallel channels (this is just an example, and would need to be adapted to the customer environment and requirements).

Default backup type

By default, if not mentioned in the dmk_rman.ksh command, we would like to run an inc0 backup. Therefore we will configure the appropriate script as been the default one.

Archive log deletion policy

We will configure the archive log deletion policy as mentioned in the 6.2.1 part.

ArchDelPolicy parameter is used for the primary database when ArchDelPolicySTD is used for the standby database.

Additional parameters

The following additional parameters need to be configured according to the customer environment.

The rman.cfg will have to be copied with the scp command to the standby server as well.

rcv script files

We now need to copy the rcv script files we will use from the template directory. We are running database version 19c, so we will use the templates from the oracle12 directory and copy them into the appropriate running rcv directory. This rcv scripts have the needed variable in relation to the rman.cfg file.

For our implementation we will use following rcv templates:

  • bck_inc0_no_arc_del.rcv

  • bck_arc_no_arc_del.rcv

  • change_arc_del_policy.rcv

  • mnt_obs.rcv

We need to copy the same file into the standby server.

Setup crontab

We will use both check_primary.ksh and check_standby.ksh scripts from the dmk_ha plugin in order to have both servers configured the same way and to execute the appropriate scripts in relation to the current databases role.

Test the backups

On the primary server

Inc0 backup:

Archive log backup:

Backup deletion:

On the standby server

Change archive log deletion policy on standby:

PreviousStructureNextdmk_dtpump.{ksh|cmd}

Last updated