WARNING: This version of the DB Cloud Backup Module for OCI supports archiving 
on the Linux Platform only. Do not use "enableArchiving True" on other platforms.

Backup on the Oracle Cloud Infrastructure - Using the Oracle Database
Cloud Backup Module

This is the README file for installing, configuring, and using the
Oracle Database Cloud Backup Module to back up an Oracle database to
Oracle Cloud Infrastructure (OCI).

--------------------------------------------------------------------
I. What you need to have before starting the installation

Using this service requires an Oracle Cloud Infrastructure account, and the
software library and associated files. Before you run the installer, verify
that you have:

1. Your Oracle Cloud Infrastructure API signing keys, tenant OCID and user OCID

   Please refer to the following document on how to obtain the above items:
      https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm

2. The installer: oci_install.jar

   The installer will download the library appropriate to the
   platform it is running on. It will also create the library
   configuration file and the Oracle Wallet where the credentials
   are stored.

   The installer jar file is included in the same zip file as this
   README file.

4. Java 1.7 on the computer where the installer will run.
   The installer requires Java 1.7 to run. 

5. Database Version Support: The Oracle Database Cloud Backup Module
   can be used to backup the following supported versions of Oracle
   Database: Oracle Database 10g Release 2 or higher.


--------------------------------------------------------------------
II. Installing the Library

Execute the installer supplying all the mandatory parameters in one
line, each hyphen-preceded label followed by its value.

First run the installer without any parameters:

 % java -jar oci_install.jar

to get a usage message, whose parameters are explained below. From
the preceding section, you should have the values for all the
mandatory parameters.  Check the optional parameters; for example,
you may need to know the proxy name and credentials in your
installation.  Ensure you have Java 1.7 and $ORACLE_HOME is
correctly defined.  Note: in this readme we use "/orclhome" as the
value of $ORACLE_HOME to reduce clutter. In your installation your
value may be something like /u01/oracle/product/11.2.0, for example.

   -host:           Host name for the Oracle Cloud Infrastructure account.
    
   -pvtKeyFile:     Private key used to sign OCI API requests.
                    The key file must be in PEM format.

Note that your private key used for OCI API request authentication is never
transmitted outside of the computer where the install utility is running.

   -pubFingerPrint: Finger print of the public key paired with the
                    specified private key. The finger print tells OCI
                    which private and public key pair is used to
                    authenticate the API requests.

   -tOCID:          The tenancy OCID for the Oracle Cloud Infrastructure
                    account.
 
   -uOCID:          The user OCID for the Oracle Cloud Infrastructure account.

   -bucket:         The name of the bucket where the backup will go.

Note that the install tool will create the specified bucket if it
does not exist. If the parameter is not specified, RMAN interface library
will automatically create a bucket to store backups.

   -cOCID:          The resource comparment ID for the Oracle Cloud
                    Infrastructure account. The default value is the
                    tenancy OCID if not specified.

   -newRSAKeyPair:  Set up a new pair of public and private RSA keys
                    for authentication. If specified, the install tool
                    will generate a random RSA private and public key
                    pair of 2048 bits and outputs them in the specified
                    Oracle Wallet directory.

   -enableArchiving:  Enable archival. If specified the value should
                      be either TRUE/true OR FALSE/false. By default the
                      archival is disabled.

   -archiveAfterBackup: The timeline after which backups from a
                        container would be archived.
                        This parameter is only effective when the
                        enableArchiving parameter is specified. This should
                        be specified as [timeAmount timeUnit] such as
                        "4 days", "52 years". By default this value
                        will be set to 0 days.

   -retainAfterRestore: The number of hours after which backups
                        from a container would be sent back to archival
                        storage once it is restored on to standard storage.
                        This parameter is only effective when the
                        enableArchiving parameter is specified. This should
                        be specified as [timeAmount timeUnit] such as
                        "24 hours", "48 hours". By default the number
                        of hours will be set to 48.
                        It is recommended to keep this considerably large
                        so that the restored data from archival storage
                        is retained in standard storage till the actual
                        restore is completed. There is a risk of data
                        resent back to archival storage if the value is
                        low. Recommended setting is 48 hours.

   -displayBucketAttrs: Display storage bucket properties
                        Not recommended to be used while creating bucket.

   -trace :         Enable Tracing

   -walletDir:      Directory to store wallet.

The location for the Oracle Wallet used to store account credentials is
mandatory.

Suggested Unix location:    $ORACLE_HOME/dbs/opc_wallet
Suggested Windows location: $ORACLE_HOME\database\opc_wallet

   -trustedCerts: File names of SSL certificates to be imported to the wallet.

This parameter enables manually adding SSL certificates to the wallet. The
only reason to use this parameter is if the install tool fails to retrieve
the required certificates for SSL connection from local Java truststore.
Each SSL certificate must be in the PEM format. File names need to be
separated by comma to specify multiple certificates.

   -import-all-trustcerts:
                  Import all X509 certificates from Java truststore.

   -configFile:   File name of config file

The location where the configuration file will reside. If omitted, the
installer will create the configuration file and place it in a
default system-dependent location. Optional.

Default Unix location:    $ORACLE_HOME/dbs/opc<ORACLE_SID>.ora
Default Windows location: $ORACLE_HOME\database\opc<ORACLE_SID>.ora

   -libDir:      Directory to store library

The location where the library will be placed. If this parameter is
omitted, the installer does not download the library. Optional.
Usually you would want to download the library. The only reason
to omit downloading the library is if you are using the install
tool to regenerate the wallet and configuration file in an Oracle
Home where the Oracle Database Cloud Backup Module has previously
been installed.

Suggested Unix location:    $ORACLE_HOME/lib
Suggested Windows location: $ORACLE_HOME\bin

    -libPlatform:   The desired platform for the library

The install tool will usually be able to determine the correct
platform automatically by examining the system where it is
running.

The only reason to use this parameter is if the install tool
complains that it can't identify your system (in which case
you should also let Oracle know so we can fix the install tool),
or if you need to download the library for use on a different
system.

In this version the supported values for the parameter are:
linux64, windows64, solaris_sparc64, solaris_x64, zlinux64,
hpux_ia64, aix_ppc64.

   -lib-download-only: Download only the RMAN interface library.

The install tool would only download the library when this parameter is
specified. This parameter enables updating the library without making
changes to the config file and the wallet.

   -proxyHost:   HTTP proxy server
   -proxyPort:   HTTP proxy server port
   -proxyID:     HTTP proxy server username
   -proxyPass:   HTTP proxy server password

The name and port of the HTTP proxy server, if required. If the proxy
server is specified, the username and password, if required. Optional.

   -argFile: Reads the remainder of the command-line arguments from
             the specified file. Specify filename as "-" to read arguments from
             standard input.

Now you are ready to execute the installer. Compose an invocation
populating the parameters you obtained earlier.  Either all of the
parameters must be on the same invocation line, or use the -argFile
option to read the parameters from a file.  When the installer
completes, verify that you have three items on your system: the
library, the config file, and the wallet. See Sample Installation
Run, below.


--------------------------------------------------------------------
III. Using the library: your first backup to Oracle Cloud Infrastructure

Using RMAN, connect to your target database, and configure an RMAN
channel, specifying the library and the configuration file.

For example:

configure channel device type sbt
   parms='SBT_LIBRARY=libopc.so,
   SBT_PARMS=(OPC_PFILE=/orclhome/dbs/opct1.ora)';

Now you can issue all of your usual RMAN backup/restore commands.

You can run a quick test by doing a controlfile backup:

backup device type sbt current controlfile;

--------------------------------------------------------------------
IV. The Installer and the Library need your OCI API signing keys 

The installer requires OCI API signing keys to create the wallet and other
installation operations. Only the OCI API signing keys are retained when
the installer has finished, and they are stored only in the Oracle Wallet.
The OCI API sigining keys are only used to authenticate the library's
interactions with Oracle Cloud Infrastructure; they are never sent anywhere
else.

--------------------------------------------------------------------
V. Sample Installation Run

The following shows a sample run of the installer under Linux. 

First we ensure we have Java 1.7 and that ORACLE_HOME is defined:

% java -version
java version "1.7.0"
Java(TM) SE Runtime Environment (build 1.7.0-b147)
Java HotSpot(TM) 64-Bit Server VM (build 21.0-b17, mixed mode)
% echo $ORACLE_HOME
/orclhome

If we do not possess a pair of Oracle Cloud Infrastructure API signing keys,
we may invoke the installer to generate an RSA key pair:

% java -jar oci_install.jar -newrsakeypair 
  -walletDir $ORACLE_HOME/dbs/opc_wallet
Oracle Database Cloud Backup Module Install Tool, build 2017-04-11
OCI API signing keys are created:
  PRIVATE KEY --> /orclhome/dbs/opc_wallet/oci_pvt
  PUBLIC  KEY --> /orclhome/dbs/opc_wallet/oci_pub
Please upload the public key in the OCI console.

After uploading the public key to the OCI console, we invoke the installer
with the parameters;

% java -jar oci_install.jar -host https://objectstorage.us-phoenix-1.oraclecloud.com
  -pvtKeyFile $ORACLE_HOME/dbs/opc_wallet/oci_pvt
  -pubFingerPrint 40:a4:f8:a0:40:4f:a3:2f:e0:fd:4e:b9:25:72:81:5f
  -tOCID ocid1.tenancy.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq
  -uOCID ocid1.tenancy.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq
  -libDir $ORACLE_HOME/lib
  -walletDir $ORACLE_HOME/dbs/opc_wallet
  -proxyHost www-proxy.smallcompany.com -proxyPort 80
Oracle Database Cloud Backup Module Install Tool, build 2017-04-11
Oracle Database Cloud Backup Module credentials are valid.
Oracle Database Cloud Backup Module wallet created in directory /orclhome/dbs/opc_wallet.
Oracle Database Cloud Backup Module initialization file /orclhome/dbs/opct1.ora created.
Downloading Oracle Database Cloud Backup Module Software Library from file
opc_linux64.zip.
Downloaded 13165919 bytes in 204 seconds. Transfer rate was 64538 bytes/second.
Download complete.
Extracted file /orclhome/lib/libopc.so

--------------------------------------------------------------------
VI. Encrypting Backup

Oracle Database Cloud Backup Module enforces RMAN encryption and will not let
the backups to happen if the backup is not encrypted. For eg, if the backup is
not encrypted, an error message similar to the one shown below is returned.

RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03009: failure of backup command on ORA_SBT_TAPE_1 channel at 02/14/2014 14:00:43
ORA-27030: skgfwrt: sbtwrite2 returned error
ORA-19511: non RMAN, but media manager or vendor specific failure, error text:
   KBHS-01602: backup piece 14p0jso8_1_1 is not encrypted

User has to configure encrypted backups in order to do send backups to Oracle
Database Backup Service. RMAN supports two methods of Backup Encryption:
   1) Transparent Data Encryption(TDE)
   2) Password Encryption.
Please refer manual on how to setup Backup Encryption.

For example, password encryption can be done using
  RMAN> set encryption on identified by "myPassw0rd" only;
  RMAN> backup device type sbt database;

During restore, you need to remember the password and supply it by following
command.
  set decryption identified by "myPassw0rd";

--------------------------------------------------------------------
VII. Encrypting Backup Via Enterprise Manager

Due to a bug, you may encounter the following error message while trying to
run an encrypted backup through Enterprise Manager:

"Encryption is only supported when backing up to disk, or when backing up to tape
 using Oracle SBT library like (Oracle Database Cloud Backup Module).
 Please specify a different backup destination"

On Linux, You can get around this problem by creating the following symbolic links: 

% ln -s <libDir/libopc.so> $ORACLE_HOME/lib/libobk.so  
% ln -s <configFile> $ORACLE_HOME/dbs/opc<ORACLE_SID>.ora  

Where

libDir : Directory to store library
configFile : File name of config file 

--------------------------------------------------------------------
VIII. Behaviour of restore preview and restore preview recall for
archival storage and OCI_ARCHIVAL_SUPPORT.

For the rman linux client older than 20.1 we have same behaviour for
RESTORE PREVIEW AND RESTORE PREVIEW RECALL which is they both show
the remote files and initiates recall for the remote files.
To get the new behaviour of RMAN client  please request for the patch for 
BUG#30432410 for older clients.
Currently the OCI_ARCHIVAL support is only linux platforms.
