This is the README file for installing, configuring, and using the
Oracle Secure Backup Cloud module to back up an Oracle database to Amazon
Simple Storage Service (S3).

I. What you need to have before starting the installation

Using Cloud Backup on S3 requires an OTN account, an
Amazon Web Services account, and the software library and associated
files. Before you run the installer, verify that you have:

1. Your OTN account’s username and password.
You may register for a free OTN account at http://otn.oracle.com.

2. Your AWS Access Key ID and Secret Access Key.
You obtain these two credentials at http://aws.amazon.com by
clicking on the button labeled "Your Web Services Account", and
choosing "AWS Access Identifiers". Protect these credentials as
they authorize charges on all Amazon Web Services.
(See below how to create an Amazon account.)

3. The S3 backup installer osbws_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 S3 credentials are stored.

If you are using Oracle-provided Amazon Machine Images (AMIs) to run Oracle
Database on Amazon Elastic Compute Cloud (EC2), this file is already downloaded
for you and can be found in /home/oracle/scripts directory.

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

5. Database Version Support: The Oracle Secure Backup Cloud Program can or may be
used to backup the following supported versions of Oracle Database:
Oracle Database 9i 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 osbws_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.5 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 will be something
like /usr/oracle/product/9.2.0 (Unix).

-AWSID: AWS Access Key ID
-AWSKey: AWS Secret Access Key
The credentials for Amazon Web Services. Mandatory.

-otnUser: OTN Username
-otnPass: OTN Password
The credentials for Oracle Technology Network, which the installer
uses to identify the customer. Mandatory.

-walletDir: Directory to store wallet
The location for the Oracle Wallet used to store S3 credentials and
proxy information (if specified, see below). Mandatory.
Suggested Unix location: $ORACLE_HOME/dbs/osbws_wallet
Suggested Windows location: $ORACLE_HOME\database\osbws_wallet

-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/osbsws<ORACLE_SID>.ora
Default Windows location: $ORACLE_HOME\database\osbsws<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.
Suggested Unix location: $ORACLE_HOME/lib/
Suggested Windows location: $ORACLE_HOME\bin\

-libPlatform: The desired platform for the library
The install tool will determine the platform automatically by
examining the system where it is running. This parameter allows
specifying it explicitly. Optional. In this version the supported
values for the parameter are: linux32, linux64, windows32.

-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.

Now you are ready to execute the installer. Compose a one-line
invocation populating the parameters you obtained earlier. 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 S3

Using RMAN, connect to your target database, and configure an RMAN
channel, specifying the library and the configuration file. For example,
configure and RMAN channel as follows:

RMAN> run {
allocate channel dev1 type sbt parms='SBT_LIBRARY=libosbws11.so,
SBT_PARMS=(OSB_WS_PFILE=/orclhome/dbs/osbwst1.ora)';
}

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

IV. Other Notes

IV.1 About System Time

The authentication method used by S3 relies on the current time at the
client (i.e., your computer, where the library runs) being accurate.
Thus, you must ensure that your system’s UTC time is within a few
minutes of the S3 time.

IV.2 The Installer and the Library need your AWS Credentials

The installer requires both the OTN and AWS credentials to create the
wallet and other installation operations. Only your AWS credentials
are retained when the installer has finished, and they are stored only
in the Oracle Wallet. The AWS credentials are only used to
authenticate the library’s interactions with S3; they are never sent
anywhere else.

IV.3 Getting AWS Credentials

The instructions above assume that you already have AWS Developer
Credentials. These are not the same as a retail customer Amazon
account (e.g., the account one would use to buy a book at Amazon).

First, if you do not already have a retail Amazon account, open one
at http://www.amazon.com, via the link "New Customer? Start here."
The retail Amazon account requires that you provide a means of
payment, against which Amazon will later charge your AWS S3 usage.

Second, to obtain AWS credentials, go to http://aws.amazon.com,
find the "Sign Up for AWS" box, and click on the link. You will be
prompted to log on with your retail Amazon account, and agree to the
terms of service.

IV.4 Browsing S3

You can issue the usual RMAN commands to restore, validate, etc. You
may use a third-party tool to browse the contents of your S3
account. You will find buckets with a meaningful name containing your
backups and their metadata. You should NEVER alter the metadata or
content of the buckets, as that can render your backups useless.

V. Sample Installation Run

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

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

% java -version
java version "1.5.0_11"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_11-b03)
Java HotSpot(TM) Client VM (build 1.5.0_11-b03, mixed mode)
% echo $ORACLE_HOME
/orclhome

Then we invoke the installer with the parameters; the installer's
response starts on the second line, beginning "OTN userid is valid":

% java -jar osbws_install.jar -AWSID 1CKUTEGEM4BT0U21FQ01 -AWSKey <secret key> -otnUser jane.doe@smallcompany.com -otnPass <password for OTN> -walletDir $ORACLE_HOME/dbs/osbws_wallet -libDir $ORACLE_HOME/lib/ -proxyHost www-proxy.smallcompany.com
OTN userid is valid.
AWS credentials are valid.
Creating new registration for this S3 user.
Created new log bucket.
Registration ID: 0f0a8aac-dad0-6254-7d70-be4ac4f112c4
S3 Logging Bucket: oracle-log-jane-doe-1
Create credential oracle.security.client.connect_string1
OSB web-services wallet created in directory /orclhome/dbs/osbws_wallet.OSB web-services initialization file /orclhome/dbs/osbwst1.ora created.
Downloading OSB Web Services Software Library.
Downloaded 13165919 bytes in 204 seconds. Transfer rate was 64538 bytes/second.
Download complete.
Extracted file /orclhome/lib/libosbws11.so

VI. 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 Secure Backup. Please specify a different backup destination"

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

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

Where

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