Backup on the Cloud - Using the OSB Cloud Module
This is the README file for installing, configuring, and using the
Oracle Secure Backup Cloud module to back up an Oracle database to
Amazon's 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
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 "Account", then clicking the link
labeled "Security Credentials".
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.
The installer jar file is included in the same zip file as this
README file.
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.7 on the computer where the installer will run.
The installer requires Java 1.7 to run.
5. Database Version Support: The Oracle Secure Backup Cloud Module
can 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.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.
-AWSID: AWS Access Key ID
-AWSKey: AWS Secret Access Key
The credentials for Amazon Web Services.
-IAMRole: AWS IAM role name
-IAMRoleMetaUri: Metadata URI for the specified IAM role
The AWS IAM role name to be assumed and the metadata URI where
temporary credentials for the IAM role are stored. The assumed
role must be assigned the appropriate privilege to access your
S3 account.
Either both -AWSID and -AWSKey or -IAMRole is required. For Amazon
EC2 users, -IAMRoleMetaUri is not mandatory, and the temporary
credentials would be retrieved from the instance metadata if
not specified.
-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.
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 OSB Cloud 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, hpux_ia64.
-awsEndPoint: Host name to which backups to be sent. If not specified
backups will be stored in default host (s3.amazonaws.com).
-location: The Amazon S3 location where you wish to store your
backups. The value must match the location of the
specified -awsEndPoint. See the Amazon S3 documentation
for a list of valid pairs of endpoints and locations:
http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
The installer could automatically determine the location if the value
of -awsEndPoint is in one of the following regions:
us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1,
ap-northeast-1, ap-northeast-2, ap-southeast-1, ap-southeast-2,
sa-east-1, cn-north-1, us-gov-west-1.
If the specified -awsEndPoint is not in the above regions, this
parameter is mandatory.
-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.
-awsPort: non-default HTTP/HTTPS connection port.
-useHttps: Setup HTTPS connection.
-trustedCerts: List of SSL certificate to be imported into wallet.
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 S3
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=libosbws.so,
SBT_PARMS=(OSB_WS_PFILE=/orclhome/dbs/osbwst1.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. 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.
IV.5 S3 Bucket Usage
S3 Cloud Backup creates a bucket called data bucket.
The data bucket will usually be named oracle-data-<username>-1. All
backups are stored in the data bucket. No external permissions are
granted to the data bucket or to any of the objects created in the
data bucket.
--------------------------------------------------------------------
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
Then we invoke the installer with the parameters;
% java -jar osbws_install.jar -AWSID 1CKUTEGEM4BT0U21FQ01 -AWSKey <secret key> -walletDir $ORACLE_HOME/dbs/osbws_wallet -libDir $ORACLE_HOME/lib/ -proxyHost www-proxy.smallcompany.com -proxyPort 80
AWS credentials are valid.
Oracle Secure Backup Web Service wallet created in directory /orclhome/dbs/osbws_wallet.
Oracle Secure Backup Web Service 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/libosbws.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/libosbws.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