OCI User Guide PDF

User Guide
4/17/2018
Copyright © 2016, 2018, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as
expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform,
publish, or display any part, in any form, or by any means. Reverse engineering,
disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to
be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or

anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system,
integrated software, any programs installed on the hardware, and/or documentation,
delivered to U.S. Government end users are "commercial computer software" pursuant to the
applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, use, duplication, disclosure, modification, and adaptation of the programs, including any
operating system, integrated software, any programs installed on the hardware, and/or
documentation, shall be subject to license terms and license restrictions applicable to the
programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information

management applications. It is not developed or intended for use in any inherently dangerous
applications, including applications that may create a risk of personal injury. If you use this
software or hardware in dangerous applications, then you shall be responsible to take all
appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle
Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may
be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The
Open Group.
This software or hardware and documentation may provide access to or information about
content, products, and services from third parties. Oracle Corporation and its affiliates are not
responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement
between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any
loss, costs, or damages incurred due to your access to or use of third-party content, products,
or services, except as set forth in an applicable agreement between you and Oracle.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Oracle customers that have purchased support have access to electronic support through My
Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
CONTENTS
CHAPTER 1 About Oracle Cloud Infrastructure 11

Prefer Online Help? 12
Need API Documentation? 12
CHAPTER 2 Service Essentials 13

Security Credentials 14
Regions and Availability Domains 16
Resource Identifiers 19
Resource Tags 22
Service Limits 26
Prerequisites for Oracle Platform Services on Oracle Cloud Infrastructure 39
Console Cookies and Local Storage 49
CHAPTER 3 Archive Storage 53

Overview of Archive Storage 53
CHAPTER 4 Audit 58
Overview of Audit 58
Contents of an Audit Log Event 59
Viewing Audit Log Events 66
Setting Audit Log Retention Period 71
CHAPTER 5 Block Volume 73

Overview of Block Volume 73
Oracle Cloud Infrastructure User Guide 4

Table of Contents
Boot Volumes 78
iSCSI Commands and Information 82
Creating a Volume 84
Attaching a Volume 85
Attaching a Boot Volume 89
Connecting to a Volume 91
Listing Volumes 95
Listing Boot Volumes 97
Listing Volume Attachments 98
Listing Boot Volume Attachments 99
Renaming a Volume 100
Overview of Block Volume Backups 101
Backing Up a Volume 104
Policy-Based Backups 106
Restoring a Backup to a New Volume 109
Cloning a Volume 111
Disconnecting From a Volume 113
Detaching a Volume 114
Detaching a Boot Volume 116
Deleting a Volume 117
Deleting a Boot Volume 118
Block Volume Performance 120
CHAPTER 6 Compute 130

Overview of the Compute Service 130
Best Practices for Your Compute Instance 138
Protecting Data on NVMe Devices 147
Oracle-Provided Images 160
Installing and Running Oracle Ksplice 197
Managing Custom Images 199
Image Import/Export 209
Bring Your Own Image 215

Table of Contents
OS Kernel Updates 229

Managing Key Pairs on Linux Instances 232
Launching an Instance 237
Connecting to an Instance 257
Instance Console Connections 261
Adding Users on an Instance 271
Displaying the Console for an Instance 274
Getting Instance Metadata 275
Renaming an Instance 277
Stopping and Starting an Instance 278
Terminating an Instance 281
Compute Performance 283
CHAPTER 7 Data Transfer 287

Overview of Data Transfer 287
Preparing for Data Transfers 294
Managing HDD Data Transfers 296
CHAPTER 8 Database 319

Overview of the Database Service 319
Exadata DB Systems 322
Bare Metal and Virtual Machine DB Systems 398
Migrating Databases to the Cloud 620
Troubleshooting 674
CHAPTER 9 DNS 675

Overview of the DNS Service 675
Managing DNS Service Zones 677
Supported DNS Resource Record Types 685
CHAPTER 10 Email Delivery 690

Overview of the Email Delivery Service 690
Generate SMTP Credentials for a User 693

Table of Contents
Managing Approved Senders 695

Configure SPF 696
Configure SMTP Connection 697
Managing the Suppression List 698
Deliverability Best Practices 700
CHAPTER 11 File Storage 706

Overview of File Storage 706
About Security 712
Creating File Systems 713
Managing File Systems 725
Mounting File Systems 738
Paths in File Systems 744
Troubleshooting Your File System 745
CHAPTER 12 IAM 753

Overview of IAM 753
Getting Started with Policies 769
How Policies Work 772
Common Policies 782
Advanced Policy Features 790
Policy Syntax 796
Policy Reference 801
User Credentials 908
Identity Providers and Federation 911
Calling Services from an Instance 949
Managing Users 956
Managing Groups 963
Managing Dynamic Groups 968
Managing Compartments 974
Managing Tags and Tag Namespaces 978
Managing Regions 992

Table of Contents
Managing Policies 997

Managing User Credentials 1004
CHAPTER 13 Load Balancing 1017

Overview of Load Balancing 1017
How Load Balancing Policies Work 1029
Connection Management 1031
HTTP "X-" Headers 1033
Session Persistence 1035
Managing a Load Balancer 1037
Managing Backend Sets 1045
Managing Backend Servers 1052
Managing Load Balancer Listeners 1058
Managing Request Routing 1062
Managing SSL Certificates 1072
Editing Health Check Policies 1078
Viewing the State of a Work Request 1085
CHAPTER 14 Networking 1088

Overview of Networking 1088
Scenario A: Public Subnets 1103
Scenario B: Private Subnets with a VPN 1107
Scenario C: Public and Private Subnets with a VPN 1119
VCNs and Subnets 1134
Access and Security 1143
Virtual Network Interface Cards (VNICs) 1165
Private IP Addresses 1175
Public IP Addresses 1192
DNS in Your Virtual Cloud Network 1203
Internet Intelligence Overview 1212
Route Tables 1218
DHCP Options 1228

Table of Contents
Connectivity to the Internet 1234

VCN Peering 1239
Local VCN Peering (Within Region) 1243
Remote VCN Peering (Across Regions) 1260
Dynamic Routing Gateways (DRGs) 1276
IPSec VPNs 1282
Configuring Your On-Premises Router for an IPSec VPN 1319
FastConnect Overview 1417
FastConnect: With an Oracle Provider 1431
FastConnect: Colocation with Oracle 1454
Network Performance 1479
Troubleshooting 1481
CHAPTER 15 Object Storage 1493

Overview of Object Storage 1493
Understanding Object Storage Namespaces 1498
Managing Buckets 1500
Managing Objects 1515
Using Pre-Authenticated Requests 1533
Using Multipart Uploads 1541
Hadoop Support 1546
Designating Compartments for the Amazon S3 Compatibility and Swift APIs 1547
Amazon S3 Compatibility API 1550
CHAPTER 16 Developer Tools 1555

Command Line Interface (CLI) 1555
Data Transfer Utility 1593
SDKs and Other Tools 1600
SDK and Tool Configuration 1643
Required Keys and OCIDs 1646
About the API 1650
API Reference and Endpoints 1655

Table of Contents
API Errors 1660
Request Signatures 1663
GLOSSARY 1709
RELEASE NOTES 1724

CHAPTER 1 About Oracle Cloud Infrastructure
Oracle Cloud Infrastructure provides bare metal cloud infrastructure that lets you create
networking, compute, and storage resources for your enterprise workloads.
If you're new to Oracle Cloud Infrastructure and would like to learn some key concepts and
take a quick tutorial, see the Oracle Cloud Infrastructure Getting Started Guide.
If you're ready to create cloud resources such as users, access controls, cloud networks,
instances, and storage volumes, this guide is right for you. It provides the following
information about using Oracle Cloud Infrastructure:
Service What's Covered Chapter
Archive Storage Preserving cold data. Archive Storage
Audit Logging activity in your cloud. Audit
Block Volume Adding storage capacity to instances. Block Volume
Compute Launching compute instances and Compute

connecting to them by using an SSH key
pair.
Data Transfer Migrating large volumes of data. Data Transfer
Database Launching DB Systems and managing Database

Oracle databases.
DNS Creating and managing DNS zones. DNS
Email Delivery Sending large volume email. Email Delivery
File Storage Managing shared file systems, mount File Storage

targets, and snapshots.

CHAPTER 1 About Oracle Cloud Infrastructure
Service What's Covered Chapter
IAM Setting up administrators, users, and IAM

groups and specifying their permissions
to access to cloud resources.
Load Balancing Setting up load balancers, listeners, Load Balancing

backend sets, certificate bundles, and
managing health check policies.
Networking Setting up cloud networks, subnets, Networking

gateways, route tables, and security
lists.
Object Storage Creating and managing buckets to store Object Storage

objects, and uploading and accessing
data files.
For a description of the terminology used throughout this guide, see the GLOSSARY.
Prefer Online Help?

The information in this guide and the Getting Started Guide is also available in the online help
at https://docs.us-phoenix-1.oraclecloud.com/#dochome.htm.
Need API Documentation?
For general information, see About the API. For links to the detailed service
API documentation, see the online help at https://docs.us-phoenix-
1.oraclecloud.com/#dochome.htm.

CHAPTER 2 Service Essentials
The following topics provide essential information that applies across Oracle Cloud
Infrastructure.
Security Credentials
The types of credentials you'll use when working with Oracle Cloud Infrastructure.
Regions and Availability Domains

An introduction to the concepts of regions and availability domains.
Resource Identifiers
A description of the different ways your Oracle Cloud Infrastructure resources are identified.
Resource Tags
Information about Oracle Cloud Infrastructure tags and how to apply them to your resources.
Service Limits
A list of the default limits applied to your cloud resources and how to request an increase.
Prerequisites for Oracle Platform Services on Oracle Cloud

Infrastructure
Instructions for setting up the resources required when running an Oracle Platform Service on
Oracle Cloud Infrastructure.

Security Credentials
This section describes the types of credentials you'll use when working with Oracle Cloud
Infrastructure.
Console Password
l What it's for: Using the Console.
l Format: Typical password text string.
l How to get one: An administrator will provide you with a one-time password.
l How to use it: Sign in to the Console the first time with the one-time password, and
then change it when prompted. Requirements for the password are displayed there. The
one-time password expires in seven days. If you want to change the password later,
see To change your Console password. Also, you or an administrator can reset the
password in the Console or with the API (see To create or reset a user's Console
password). Resetting the password creates a new one-time password that you'll be
prompted to change the next time you sign in to the Console. If you're blocked from
signing in to the Console because you've tried 10 times in a row unsuccessfully, contact
your administrator.
API Signing Key

l What it's for: Using the API (see SDKs and Other Tools and Request Signatures).
l Format: RSA key pair in PEM format (minimum 2048 bits required).
l How to get one: See Required Keys and OCIDs.
l How to use it: In the Console, copy and paste the contents of the PEM public key file
from the key pair (see How to Upload the Public Key). Then use the private key with the
SDK or with your own client to sign your API requests. Note that after you've uploaded
your first API key in the Console, you can use the API to upload any additional ones you
want to use. If you provide the wrong kind of key (for example, your instance SSH key,
or a key that isn't at least 2048 bits), you'll get an InvalidKey error.

l Example: The PEM public key looks something like this:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
...
-----END PUBLIC KEY——
Instance SSH Key

l What it's for: Accessing a compute instance.
l Format: For RSA, DSS, or DSA: minimum 2048 bits recommended. For ECDSA:
minimum 128 bits recommended.
l How to get one: See Creating a Key Pair.
l How to use it: When you launch an instance, provide the public key from the key pair.
l Example: An RSA public key looks something like this:
ssh-rsa AAAAB3BzaC1yc2EAAAADAQABAAABAQD9BRwrUiLDki6P0+jZhwsjS2muM...
... john.smith@example.com
Swift Password
l What it's for: Using a Swift client to access Object Storage for the purposes of backing
up an Oracle Database System (DB System) database.
l Format: Typical password text string.
l How to get one: See Working with Swift Passwords.
l How to use it: Sign in to your Swift client with your Oracle Cloud Infrastructure
Console login, your Swift password provided by Oracle, and your organization's Oracle
tenant name.


Oracle Cloud Infrastructure is hosted in regions and availability domains. A region is a
localized geographic area, and an availability domain is one or more data centers located
within a region. A region is composed of several availability domains. Most Oracle Cloud
Infrastructure resources are either region-specific, such as a virtual cloud network, or
availability domain-specific, such as a compute instance.
Availability domains are isolated from each other, fault tolerant, and very unlikely to fail
simultaneously. Because availability domains do not share infrastructure such as power or
cooling, or the internal availability domain network, a failure at one availability domain is
unlikely to impact the availability of the others.
All the availability domains in a region are connected to each other by a low latency, high
bandwidth network, which makes it possible for you to provide high-availability connectivity
to the Internet and customer premises, and to build replicated systems in multiple availability
domains for both high-availability and disaster recovery.
Regions are completely independent of other regions and can be separated by vast
distances—across countries or even continents. Generally, you would deploy an application in
the region where it is most heavily used, since using nearby resources is faster than using
distant resources. However, you can also deploy applications in different regions to:
l mitigate the risk of region-wide events, such as large weather systems or earthquakes
l meet varying requirements for legal jurisdictions, tax domains, and other business or
social criteria
Region Location Region Name Region Key
Phoenix, AZ metropolitan area us-phoenix-1 PHX
Ashburn, VA us-ashburn-1 IAD
Frankfurt, Germany eu-frankfurt-1 FRA
London, United Kingdom uk-london-1 LHR
To subscribe to a region, see Managing Regions.

Note
Your Tenancy's Availability Domain Names
Oracle Cloud Infrastructure randomizes the availability

domains by tenancy to help balance capacity in the data
centers. For example, the availability domain labeled
PHX-AD-1 for tenancyA may be a different data center
than the one labeled PHX-AD-1 for tenancyB. To keep
track of which availability domain corresponds to which
data center for each tenancy, Oracle Cloud
Infrastructure uses tenancy-specific prefixes for the
availability domain names. For example: the
availability domains for your tenancy are something like
Uocm:PHX-AD-1, Uocm:PHX-AD-2, and so on.
To get the specific names of your tenancy's availability

domains, use the ListAvailabilityDomains operation,
which is available in the IAM API. You can also see the
names when you use the Console to launch an instance
and choose which availability domain to launch the
instance into.
Resource Availability
The following sections list the resource types based on their availability: global across
regions, within a single region, or within a single availability domain.

Tip
In general: IAM resources are global. DB Systems,

instances, volumes, and subnets are specific to an
availability domain. Everything else is regional.
Global Resources
l API signing keys

l compartments
l dynamic groups
l federation resources
l groups
l policies
l tag namespaces
l tag keys
l users
Regional Resources
l buckets: Although buckets are regional resources, they can be accessed from any
location if you use the correct region-specific Object Storage URL for the API calls.
l customer-premises equipment (CPE)
l DHCP options sets
l dynamic routing gateways (DRGs)
l images
l internet gateways
l load balancers

l local peering gateways (LPGs)

l reserved public IPs
l route tables
l security lists
l virtual cloud networks (VCNs)
l volume backups: They can be restored as new volumes to any availability domain
within the same region in which they are stored.
Availability Domain-Specific Resources
l DB Systems
l ephemeral public IPs
l instances: They can be attached only to volumes in the same availability domain.
l subnets
l volumes: They can be attached only to an instance in the same availability domain.
This chapter describes the different ways your Oracle Cloud Infrastructure resources are
identified.
Oracle Cloud IDs (OCIDs)

Every Oracle Cloud Infrastructure resource has an Oracle-assigned unique ID called an Oracle
Cloud Identifier (OCID). It's included as part of the resource's information in both the Console
and API.

Important
If you use the API, you'll need the OCID for your
tenancy. For information about where to find it, see the
next section. When you create any other resource, you
can find its OCID in the response. You can also retrieve
a resource's OCID by using a "List" API operation on
that resource type, or by viewing the resource in the
Console.
The OCID uses this syntax:

ocid1.<RESOURCE TYPE>.<REALM>.[REGION][.FUTURE USE].<UNIQUE ID>
l ocid1: The literal string indicating the version of the OCID.

l resource type: The type of resource (for example, instance, volume, vcn, subnet,
user, group, and so on).
l realm: The realm the resource is in. A realm is a set of regions that share entities. The
only possible value is oc1.
l region: The region the resource is in (for example, phx, iad, eu-frankfurt-1). With
the introduction of the Frankfurt region, the format switched from a three-character
code to a longer string. This part is present in the OCID only for regional resources or
those specific to a single availability domain. If the region is not applicable to the
resource, this part might be blank (see the example tenancy ID below).
l future use: Reserved for future use; currently blank.
l unique ID: The unique portion of the ID. The format may vary depending on the type of
resource or service.
Example OCIDs
Tenancy:
ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq
Instance:

ocid1.instance.oc1.phx.abuw4ljrlsfiqw6vzzxb43vyypt4pkodawglp3wqxjqofakrwvou52gb6s5a
Where to Find Your Tenancy's OCID

If you use the Oracle Cloud Infrastructure API, you'll need your tenancy's OCID in order to
sign the API requests. You'll also use the tenancy ID in some of the IAM API operations.
You can find your tenancy's OCID in the Console, in the footer at the bottom of the page. The
tenancy OCID looks something like this (notice the word "tenancy" in it):
ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq
Name and Description (IAM Only)

The IAM service requires you to assign a unique, unchangeable name to each of your IAM
resources (users, groups, policies, and compartments). The name must be unique within the
scope of the type of resource (for example, you can only have one user with the name
BobSmith). Notice that this requirement is specific to IAM and not the other services.
The name you assign to a user at creation is their login for the Console.
You can use these names instead of the OCID when writing a policy (for example, Allow
group <GROUP NAME> to manage all-resources in compartment <COMPARTMENT NAME>).
In addition to the name, you must also assign a description to each of your IAM resources
(although it can be an empty string). It can be a friendly description or other information that
helps you easily identify the resource. The description does not have to be unique, and you
can change it whenever you like. For example, you might want to use the description to store
the user's email address if you're not already using the email address as the user's unique
name.
Display Name
For most of the Oracle Cloud Infrastructure resources you create (other than those in IAM),
you can optionally assign a display name. It can be a friendly description or other information
that helps you easily identify the resource. The display name does not have to be unique, and

you can change it whenever you like. The Console shows the resource's display name along
with its OCID.
Resource Tags
When you have many resources (for example, instances, VCNs, load balancers, and block
volumes) across multiple compartments in your tenancy, it can become difficult to track
resources used for specific purposes, or to aggregate them, report on them, or take bulk
actions on them. Tagging allows you to define keys and values and associate them with
resources. You can then use the tags to help you organize and list resources based on your
business needs.
There are two types of tags:
Defined tags are set up in your tenancy by an administrator. Only users granted permission
to work with the defined tags can apply them to resources.
Free-form tags can be applied by any user with permissions on the resource.
For more detailed information about tags and their features, see Overview of Tags.
Tip
Watch a video to introduce you to the concepts and

features of tagging: Introduction to Tagging.
Working with Resource Tags

Not all resources support tags. See Taggable Resources for the list of resources that support
tags.
To add a defined tag to an existing resource

To apply a defined tag, you must have permission to use the namespace.

1. Open the Console, go to the details page of the resource you want to tag.
For example, to tag a compute instance: Click Compute to see the list of instances in
your current compartment. Find the instance that you want to tag, and click its name to
view its details page.
2. Click Apply Tags.
3. In the Apply Tags to the Resource dialog:
a. Select the Tag Namespace.
b. Select the Tag Key.
c. Enter a Value.
d. To apply another tag, click +.
e. When finished adding tags, click Apply Tag(s).
To add a free-form tag to an existing resource

1. Open the Console, go to the details page of the resource you want to tag.
For example, to tag a compute instance: Click Compute to see the list of instances in
your current compartment. Find the instance that you want to tag, and click its name to
view its details page.
2. Click Apply Tags.
a. Select None (apply a free-form tag).
b. Enter the Tag Key.
c. Enter a Value.
e. When finished adding tags, click Apply Tag(s).

To add a tag during resource creation

You can apply tags during resource creation. The location of the Apply Tag(s) option in the
dialog varies by resource. The general steps are:
1. In the resource Create dialog, click Apply Tags.

a. Select the Tag Namespace, or select None to apply a free-form tag.
b. Select or enter the Tag Key.
c. Enter a Value.
e. Click Apply Tag(s).
To filter a list of resources by a tag

Open the Console, click the service name and then click the resource you want to view. The
left side of the page shows all the filters currently applied to the list.
For example, to view compute instances: Click Compute and then click Instances, to see
the list of instances in your current compartment.
To filter a list of resources by a defined tag

1. Next to Tag Filters, click add.
2. In the Apply a Tag Filter dialog, enter the following:
a. With Tag Type: Select Defined Tag.
b. In Namespace: Select the tag namespace.
c. With Key: Select a specific key.

d. With Value: Select from the following:

l Any - returns all resources tagged with the selected namespace and key,
regardless of the tag value.
l Equal to - returns resources with the tag value you enter in the text box.
Enter a single value in the text box. To specify multiple values for the same
namespace and key, click OR to display another text box. Enter one value
per text box.
To filter a list of resources by a free-form tag

1. Next to Tag Filters, click add.
2. In the Apply a Tag Filter dialog, enter the following:
a. With Tag Type: Select Free-form Tag.
b. With Key: Enter the tag key.
c. With Value: Select from the following:
l Any - returns all resources tagged with the selected free-form tag key,
regardless of the tag value.
l Equal to - returns resources with the tag value you enter in the text box.
Enter a single value in the text box. To specify multiple values for the same
key, click OR to display another text box. Enter one value per text box.
To update a tag applied to a resource

1. Open the Console, click the service name and then click the resource you want to view.
For example, to view compute instances: Click Compute and then click Instances, to
see the list of instances in your current compartment.
2. Click Tags.
The list of tags applied to the resource is displayed.
3. Find the tag you want to update and click the pencil icon next to it.

4. Enter the new value.

5. Click Save.
To remove a tag from a resource

1. Open the Console, click the service name and then click the resource you want to view.
For example, to view compute instances: Click Compute and then click Instances, to
see the list of instances in your current compartment.
2. Click Tags.
The list of tags applied to the resource is displayed.
3. Find the tag you want to remove and click the pencil icon next to it.
4. Click Remove Tag.
Using the API

For information about using the API and signing requests, see About the API and Security
Credentials. For information about SDKs, see SDKs and Other Tools.
To apply a tag to a resource using the API, use the appropriate resource's create or update
operation.
Service Limits
This topic describes the service limits for Oracle Cloud Infrastructure and the process for
requesting a service limit increase.
About Service Limits and Usage

When you sign up for Oracle Cloud Infrastructure, a set of service limits are configured for
your tenancy. The service limit is the quota or allowance set on a resource. For example, your
tenancy is allowed a maximum number of compute instances per availability domain. These
limits are generally established with your Oracle sales representative when you purchase

Oracle Cloud Infrastructure. If you did not establish limits with your Oracle sales
representative, or, if you signed up through the Oracle Store, default or trial limits are set for
your tenancy. You can request to have a service limit raised.
You can view your tenancy's limits and usage by region in the Console. Be aware that:
l The Console may not yet display limits and usage information for all of the Oracle Cloud
Infrastructure services or resources.
l The usage level listed for a given resource type could be greater than the limit if the
limit was reduced after the resources were created.
l If all the resource limits are listed as 0, this means your account has been suspended.
For help, contact Oracle Support.
If you don't yet have a tenancy or a user login for the Console, or if you don't find a particular
limit listed in the Console, see Limits by Service for the default tenancy limits.
To view your tenancy's limits and usage (by region)
Note
Required Permission
If you're in the Administrators group, you have

permission to view the limits and usage. If you're not,
here's an example IAM policy that grants the required
permission to users in a group called
LimitsAndUsageViewers:
Allow group LimitsAndUsageViewers to inspect limits in tenancy
1. Open the Console, and then click the name of your tenancy in the top-left corner of the
page.
2. Click Service Limits on the left side of the page.

Your resource limits and usage for the specific region are displayed, broken out by service. If
a given resource type has limits per availability domain, the limit and usage for each
availability domain is displayed.
When You Reach a Service Limit

When you reach the service limit for a resource, you receive an error when you try to create a
new resource of that type. You cannot create a new resource until you are granted an increase
to your service limit or you terminate an existing resource. Note that service limits apply to a
specific scope, and when the service limit in one scope is reached you may still have
resources available to you in other scopes (for example, other availability domains).
Requesting a Service Limit Increase

You can use My Oracle Support to file a service request to increase a service limit for your
tenancy. Please note that the service limit request is not immediate and can take a couple of
days to become effective.
To request a service limit increase

1. Go to My Oracle Support and sign in.
If you are not signed in directly to Oracle Cloud Support, click Switch to Cloud
Support at the top of the page.
2. Click Create Service Request.
3. Select the following from the displayed menus:
l Service Type: Select Oracle Cloud Infrastructure.
l Service Name: Select the appropriate option for your organization.
l Problem Type: Select OCI Limit Increase Request, and then select Request
limit increase.
4. Enter your contact information.

5. Enter a Description, and then enter the following specific information:

l Tenancy OCID
Where is my Tenancy OCID?

Your Tenancy OCID can be found at the bottom of the Console as shown in the
following figure:
l The service or resource that you are requesting the service limit increase for.
For example: Request increase in limit for 256 GB block volumes.
l Requested limit increase.
For example: Increase the service limit to 10 volumes.
l Reason for the request. Describe what you are trying to accomplish with the
increase.

Limits by Service
The following tables list the default limits for each service. Note the scope that each limit
applies to (for example, per availability domain, per region, per tenant, etc.).
Block Volume Limits

Limits apply to each availability domain. There are three availability domains per region.
Resource Monthly Universal Pay-as-You-Go or

Credits Promo
Block Volumes aggregated 60 TB 30 TB

size
Backups 1000 500
Compute Limits
Limits apply to each availability domain, unless otherwise noted. There are three availability
domains per region.
Bare Metal Servers
Resource Monthly Universal Credits Pay-as-You-Go or Promo
BM.Standard1.36 2 (72 cores) Contact Us
BM.HighIO1.36 2 (72 cores) Contact Us
BM.DenseIO1.36 2 (72 cores) Contact Us
BM.Standard2.52 1 (52 cores) Contact Us

BM.DenseIO2.52 1 (52 cores) Contact Us
BM.GPU2.2 1 (28 cores) Contact Us
Custom Images 100 per region 25 per region
Virtual Machines
VM.Standard1.1 5 3
VM.Standard1.2 5 3
VM.Standard1.4 5 Contact Us
VM.DenseIO1.4 5 1
VMDenseIO1.8 5 Contact Us
VM.Standard2.1 1 1
VM.Standard2.2 1 1

Data Transfer Service Limits

Data Transfer Service limits are regional.
Resource Monthly Universal Credits Pay-As-You-Go
Transfer job 0 transfer jobs per OCI tenancy 0 per OCI tenancy
Transfer 0 transfer packages per transfer 0 transfer packages per transfer

packages job job
Transfer 0 transfer devices per transfer 0 transfer devices per transfer

devices package package
Contact My Oracle Support to file a service request to increase the service limits for Data
Transfer service. See Requesting a Service Limit Increase for details.
Database Limits
Database limits are per availability domain. There are three availability domains per region.

Resources Monthly Universal Pay-as-You-Go or

Credits Promo
VM.Standard1 -Total OCPUs 10 (cores) 2 (cores)
VM.Standard2 -Total OCPUs 10 (cores) 2 (cores)
BM.DenseIO1.36 1 instance 1 instance
BM.DenseIO2.52 1 instance 1 instance
Exadata.Quarter1.84 Contact Us Contact Us
Exadata.Half1.168 Contact Us Contact Us
Exadata.Full1.336 Contact Us Contact Us
DNS Limits
DNS limits are global.
Resources Monthly Universal Credits Pay-as-You-Go or Promo
Zones 1,000 zones 1,000 zones
Records 25,000 per zone 25,000 per zone

Email Delivery Limits

Limits apply to each tenant or availability domain, as specified. There are three availability
domains per region.
Resource Monthly Flex Pay-As-You-Go
Email volume 2,000 emails per day 2,000 emails per day
Message size Up to 2 MB Up to 2 MB
Maximum approved senders 2,000 2,000
SMTP credentials 2 per user 2 per user
Sending rate 5 messages per second 5 messages per second
Attachments Inline only Inline only
File Storage Limits

Limits apply to each tenant or availability domain, as specified. There are three availability
domains per region.
Resource Pre-Paid Pay-As-You-Go
File systems 100 per tenant 100 per tenant
Mount targets 2 per availability domain 2 per availability domain
Maximum file system size 8 exabytes 8 exabytes
IAM Limits
IAM limits are global.

Resource Monthly Universal Pay-as-You-Go or

Credits Promo
Users in a tenancy 100 100
Groups in a tenancy 50 50
Compartments in a tenancy 50 50
Policies in a tenancy 100 100
Statements in a policy 50 50
Users per group in a tenancy 100 100
Groups per user in a tenancy 50 50
Identity providers in a tenancy 3 3
Group mappings for an identity 50 50

provider
Load Balancing Limits

Load Balancing limits are regional.
LB-Capacity-100Mbps 3 Load Balancers 1 Load Balancer
LB-Capacity-400Mbps 3 Load Balancers 1 Load Balancer
LB-Capacity-8000Mbps Contact Us Contact Us

Networking Limits
Networking service limits apply to different scopes, depending on the resource.
VCN and Subnet Limits
Resource Scope Monthly Universal Credits Pay-as-You-Go or Promo
VCN Region 10 10
Subnets VCN 300 300
Gateway Limits
Resource Scope Monthly Universal Pay-as-You-Go or

Credits Promo
Dynamic routing gateways Region 2 Contact Us

(DRGs)
Internet gateways VCN 1* 1*
* Limit for this resource cannot be increased

IP Address Limits

Credits Promo
Reserved public IPs Region 50 50
Ephemeral public Instance 2 per VM instance 2 per VM instance

IPs
16 per bare metal instance 16 per bare metal instance
DHCP Option Limits
DHCP options VCN 300 300
Route Table Limits
Route tables VCN 300 300
Route rules Route table 100* 100*

Security List Limits

Credits Promo
Security lists VCN 300 300
Security lists Subnet 5* 5*
Inbound or outbound Security 100 ingress rules* 100 ingress rules*

rules list
100 egress rules* 100 egress rules*
IPSec VPN Connection Limits

Credits Promo
IPSec VPN connections Region 2 Contact Us
Customer-premises equipment Region 2 Contact Us

objects (CPEs)
FastConnect Limits
Cross-connects Region Contact Us Contact Us
Virtual circuits Region Contact Us Contact Us

Object Storage and Archive Storage Limits

Object Storage and Archive Storage limits are regional.
Buckets 1000 per compartment 1000 per compartment
Objects per bucket Unlimited Unlimited
Maximum object size 10 TiB 10 TiB
Maximum object part size 50 GiB 50 GiB
Prerequisites for Oracle Platform Services on Oracle Cloud

Infrastructure
This topic describes how to set up the required resources in Oracle Cloud Infrastructure before
launching an Oracle Platform Service on Oracle Cloud Infrastructure. For a list of services
supported on Oracle Cloud Infrastructure, see Information About Supported Platform
Services.
Accessing Oracle Cloud Infrastructure

Oracle Cloud Infrastructure has a different interface and credential set than your Oracle
Platform Services. You can access Oracle Cloud Infrastructure using the Console (a browser-
based interface) or the REST API. Instructions for the Console and API are included in topics
throughout this guide. For a list of available SDKs, see SDKs and Other Tools.
To access the Console, you must use a supported browser (Oracle Cloud Infrastructure
supports the latest desktop versions of Google Chrome, Microsoft Edge, Internet Explorer 11,
Firefox, and Firefox ESR. Note that private browsing mode is not supported for Firefox,
Internet Explorer, or Edge. Mobile browsers are not supported.

Required Identity and Access Management (IAM) Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy
written by an administrator, whether you're using the Console or the REST API with an SDK,
CLI, or other tool. If you try to perform an action and get a message that you don’t have
permission or are unauthorized, confirm with your administrator the type of access you've
been granted and which compartment you should work in.
See Common Policies for more information and examples.
Resources Created in Your Tenancy by Oracle

Oracle creates a compartment in your tenancy for Oracle Platform Services. This
compartment is specially configured by Oracle for the Oracle Cloud Infrastructure resources
that you create through the Platform Services. You can't choose another compartment for
Oracle to use.
Along with this compartment, Oracle creates the IAM policies to allow Oracle Platform
Services access to the resources.
The compartment that Oracle creates for Oracle Platform Services is named:
ManagedCompartmentForPaaS
The polices that Oracle creates for Oracle Platform Services are:
l PSM-root-policy
This policy is attached to the root compartment of your tenancy.
l PSM-mgd-comp-policy
This policy is attached to the ManagedCompartmentForPaaS compartment.
Warning
Do not make any changes to these resources. Editing or

renaming the policies or the compartment can result in
loss of functionality.

Prerequisites for Oracle Platform Services

Before you can create instances of an Oracle Platform Service on Oracle Cloud Infrastructure,
you need to have the following resources in your Oracle Cloud Infrastructure tenancy:
l A compartment for your resources

l A virtual cloud network (VCN) with at least one public subnet
l An Object Storage bucket
l IAM policies to allow Oracle Platform Services to access the VCN
l Credentials to use with Object Storage
Note that if you already have a VCN you still must create the IAM policies to allow Oracle
Platform Services access to the resources.
Setting Up the Prerequisites

Following are two scenarios with procedure sets. If you need to set up all the required
resources, follow Scenario 1. If you already have a VCN in your Oracle Cloud Infrastructure
tenancy that you want to use for Oracle Platform Services, follow Scenario 2.
To follow a tutorial on how to set up the prerequisites for Scenario 1, see Creating the
Infrastructure Resources Required for Oracle Platform Services.
Scenario 1: I need to create all the prerequisite resources
Create a compartment
Important
You cannot use the ManagedCompartmentForPaaS for

your VCN and bucket.

1. In the Oracle Cloud Infrastructure Console, click Identity, and then click
Compartments.
A list of the existing compartments in your tenancy is displayed.
2. Click Create Compartment.
3. Enter the following:
l Name: For example, PaaSResources. Restrictions for compartment names are:

Maximum 100 characters, including letters, numbers, periods, hyphens, and
underscores. The name must be unique across all the compartments in your
tenancy
l Description: A friendly description.
Set up your virtual cloud network

This procedure creates a VCN with these characteristics:
l A VCN with CIDR 10.0.0.0/16.

l Three public subnets (10.0.0.0/24, 10.0.1.0/24, and 10.0.2.0/24) each using the VCN's
default security list, default route table, and default DHCP options.
l An internet gateway, with the required route rule in the default route table.
l Use of the Internet and VCN Resolver for DNS, so your instances can use their
hostnames instead of their private IP addresses to communicate with each other.

Tip
This Quick VCN procedure is useful for getting started

and trying out Oracle Platform Services on Oracle Cloud
Infrastructure. For production, use the procedure in
VCNs and Subnets. That topic explains features such as
how to specify the CIDR ranges for your VCN and
subnets, and how to secure your network. When you use
the advanced procedure, remember that the VCN that
you create must have a public subnet for Oracle
Platform Services to use.
1. From the Region drop-down list, select the region in which you want to create the
Oracle PaaS service instance.
Select a region that's within the default data region of your account. If your default data
region is EMEA, then select eu-frankfurt-1 or uk-london-1. If your default data region is
North America, then select us-ashburn-1 or us-phoenix-1.
2. From the Compartment list, select the compartment you created.
3. Click Networking.
4. Click Create Virtual Cloud Network.
5. In Create in Compartment, leave the default value (the compartment you're
currently working in).
6. Enter a friendly name for the cloud network, for example: PaaSVCN. It doesn't have to
be unique, and it cannot be changed later in the Console (but you can change it with the
API).
7. Select Create Virtual Cloud Network Plus Related Resources.
8. Scroll down to the bottom of the dialog box and click Create Virtual Cloud Network.

Permit Oracle Platform Services to create instances in your VCN

1. In the Console, navigate to the root compartment of your tenancy by clicking your
tenancy name in the Compartment list.
2. Click Identity, and then click Policies.
3. Click Create Policy.
l Name: A unique name for the policy. The name must be unique across all policies
in your tenancy. You cannot change this later.
l Description: A friendly description. You can change this later if you want to.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in format
YYYY-MM-DD format. For more information, see Policy Language Version.
l Statement: To allow Oracle Platform Services access to use the network in your
compartment, enter the following policy statements. Replace <compartment_
name> with your compartment name. Click + after each statement to add
another.
Allow service PSM to inspect vcns in compartment <compartment_name>
Allow service PSM to use subnets in compartment <compartment_name>
Allow service PSM to use vnics in compartment <compartment_name>
Allow service PSM to manage security-lists in compartment
<compartment_name>
For more information about policies, see Policy Basics and also Policy Syntax.
5. Click Create.

Create a bucket
2. In the Oracle Cloud Infrastructure Console, click Storage, and then click Object
Storage.
3. Choose the compartment you created.
4. Click Create Bucket.
5. In the Create Bucket dialog, enter a bucket name, for example: PaasBucket.
Make a note of the name you enter. You will need it when you create an instance for
your Oracle Platform Service later.
Set up credentials to use with Object Storage

For Big Data Cloud, set up an API signing key:
Set up an API signing key

Follow the instructions in this topic: Required Keys and OCIDs.
For all other services, create a Swift password:
Create a Swift password

1. View the user's details:

l If you're creating a Swift password for yourself: In the top-right corner of the
Console, click your user's name, and then click User Settings to view the
details.
l If you're an administrator creating a Swift password for another user: In the
Console, click Identity, and then click Users. Locate the user in the list, and then
click the user's name to view the details.
2. On the left side of the page, click Swift Passwords.
3. Click Generate Password.
4. Enter a friendly description for the password and click Generate Password.
The new Swift password is displayed.
5. Copy the Swift password immediately, because you can't retrieve it again after closing
the dialog box. Also, make sure you have this password available when you create your
Oracle Platform Services instance.
Scenario 2: I have an existing VCN in Oracle Cloud Infrastructure that I want to

use for my Oracle Platform Services instance
You can use an existing VCN. The VCN must have at least one public subnet. Perform these
tasks to complete the prerequisites:
Permit Oracle Platform Services to create instances in your VCN

1. In the Console, navigate to the root compartment of your tenancy by clicking your
tenancy name in the Compartment list.
2. Click Identity, and then click Policies.

current on a specific date, select Use Version Date and enter that date in YYYY-
MM-DD format. For more information, see Policy Language Version.
l Statement: To allow Oracle Platform Services access to use the network, enter
the following policy. Click + after each statement to add another. In each
statement, replace <compartment_name> with the name of the compartment
where your VCN resides.
Allow service PSM to inspect vcns in compartment <compartment_name>
Allow service PSM to use subnets in compartment <compartment_name>
Allow service PSM to use vnics in compartment <compartment_name>
Allow service PSM to manage security-lists in compartment
<compartment_name>
For more information about policies, see Policy Basics and also Policy Syntax.
5. Click Create.
Create a bucket
2. In the Oracle Cloud Infrastructure Console, click Storage, and then click Object
Storage.
3. Choose the compartment you want to create the bucket in.

5. In the Create Bucket dialog, enter a bucket name, for example: PaasBucket. Make a
note of the name you enter. You will need it when you create an instance for your Oracle
Platform Service later.
Set up credentials to use with Object Storage

For Big Data Cloud, set up an API signing key:
Set up an API signing key

Follow the instructions in this topic: Required Keys and OCIDs.
For all other services, create a Swift password:
Create a Swift password

details.

the dialog box. Also, make sure you have this password available when you create your
Oracle Platform Services instance.
Information About Supported Platform Services

The following table lists the services supported on Oracle Cloud Infrastructure and links to
more information about using those services on Oracle Cloud Infrastructure:
Service Documentation
Database Cloud About Database Deployments in Oracle Cloud Infrastructure

Service
Java Cloud About Java Cloud Service Instances in Oracle Cloud Infrastructure
Service
MySQL Cloud About MySQL Cloud Service Deployments

Service
Event Hub Cloud About Oracle Event Hub Cloud Service - Dedicated instances in Oracle
Service Cloud Infrastructure
Data Hub Cloud About Oracle Data Hub Cloud Service Clusters in Oracle Cloud
Service Infrastructure
Big Data Cloud About Big Data Cloud Clusters in Oracle Cloud Infrastructure
Oracle SOA About SOA Cloud Service Instances in Oracle Cloud Infrastructure
Cloud Service Classic and Oracle Cloud Infrastructure
Console Cookies and Local Storage

The Oracle Cloud Infrastructure console uses browser cookies and local storage as detailed
below.

Oracle Cloud Infrastructure Console Login Page Cookies
Name Purpose Duration Impact of Disabling
bmc_ Tracks the default 30 days The last-used tenancy is not tracked, and
tenancy tenancy for the OCI users are asked to specify a tenancy when
Console login page logging into the OCI Console
Oracle Cloud Infrastructure Console Local Storage
hg-session- UI State information, includes Never Console UI may not work

<userid> selected region, active expires optimally
:<session> compartment and other UI state
recorded- Temporary cache of console Never Console usage not recorded

events usage data. Does not include any expires for analysis and product
sensitive information. improvement purposes
recorded- Temporary cache of console Never Console metrics not

metrics metrics (for example, page load expires recorded for analysis and
time) product improvement
purposes

Oracle Cloud Infrastructure Console Cookies
s_fid Adobe Analytics unique visitor 2 years Cannot track users across different
information, anonymous Oracle products (OCI, Cloud
Marketplace)
s_nr Adobe Analytics unique visitor 2 years Cannot track users across different
information, anonymous Oracle products (OCI, Cloud
Marketplace)
gpw_ Records and saves the Never Console metrics not recorded for
e24 previously accessed URL expires analysis and product improvement
(anonymous) purposes
Oracle Cloud Infrastructure Console Local Storage - Indexed DB
Table Field Purpose
duplo - activeCompartmentId Stores the compartment a user has selected in

<tenancy ocid> the UI
duplo - activeRegionId Stores the region a user has selected in the UI

<tenancy ocid>
duplo - selectedLocale Stores the user’s current locale

<tenancy ocid>

Table Field Purpose
opc-key-store key Signed ID token (carries user identity

information) and a signed security token (carries
transient user public key as a JSON Web Key)
used for signed request calls to API end points.
The security token expires after 24 hours, at
which point the user will be prompted to log in
again.
opc-key-store- key Signed ID token (carries user identity

v2 information) and a signed security token (carries
transient user public key as a JSON Web Key)
used for Signed Request calls to API end points.
The security token expires after 24 hours, at
which point the user will be prompted to log in
again.

CHAPTER 3 Archive Storage
This chapter explains how to upload, manage, and access data using Archive Storage.
Overview of Archive Storage

Oracle Cloud Infrastructure offers two distinct storage class tiers to address the need for both
performant, frequently accessed "hot" storage, as well as less frequently accessed "cold"
storage. Storage tiers help you maximize performance where appropriate and minimize costs
where possible.
l Use Archive Storage for data to which you seldom or rarely access, but that must be
retained and preserved for long periods of time. The cost efficiency of the Archive
Storage offsets the long lead time required to access the data.
l Use Object Storage for data to which you need fast, immediate, and frequent access.
Data accessibility and performance justifies a higher price point to store data in the
Object Storage. For more information, see Overview of Object Storage.
About Archive Storage

Archive Storage is ideal for storing data that is accessed infrequently and requires long
retention periods. Archive Storage is more cost effective than Object Storage for preserving
cold data for:
l Compliance and audit mandates

l Retroactively analyzing log data to determine usage pattern or debug problems
l Historical or infrequently accessed content repository data
l Application generated data that requires archival for future analysis or legal purposes
Unlike Object Storage, Archive Storage data retrieval is not instantaneous.

Using Archive Storage
Important
You interact with the data stored in the Archive Storage

using the same resources and management interfaces
that you use for data stored in Object Storage.
The following summarizes the Object Storage resources you use to store and manage Archive
Storage data:
Buckets
Buckets are logical containers for storing objects. A bucket is associated with a single
compartment that has policies that determine what actions a user can perform on a bucket
and on all the objects in the bucket.
You decide which storage tier (Archive Storage or Object Storage) is appropriate for your data
when you initially create the bucket container for your data. The storage tier is expressed as a
property of the bucket. Once set, however, you cannot change the storage tier property for a
bucket:
l An existing Object Storage bucket cannot be downgraded to an Archive Storage bucket.

l An Archive Storage bucket cannot be upgraded to an Object Storage bucket.
In addition to the inability to change the storage tier designation, there are other reasons why
storage tier selection requires careful consideration:
l The minimum retention requirement for Archive Storage is 90 days. If you delete data
from Archive Storage before the minimum retention requirements are met, you are
charged a deletion penalty. The deletion penalty is the prorated cost of storing the data
for the full 90 days.
l While Archive Storage is more cost effective than Object Storage for cold storage,
understand that when you restore objects, you are returning those objects to Object

Storage. You are billed for that storage service class while the objects reside in that
tier.
See Managing Buckets for detailed instructions on creating an Archive Storage bucket.
Objects
Any type of data, regardless of content type, is stored as an object. The object is composed of
the object itself and metadata about the object. Each object is stored in a bucket.
You upload objects to an Archive Storage bucket the same way you upload objects to a
standard Object Storage bucket. The difference is that when you upload an object to an
Archive Storage bucket, the object is immediately archived. You must first restore the object
before you can download it.
Archived objects are displayed in the object listing of a bucket. You can also display the
details of each object.
See Managing Objects for detailed instructions on uploading objects to an Archive Storage
bucket.
Restoring and Downloading Objects
To download an object from Archive Storage, you must first restore the object. Restoration
takes about four hours from the time an Archive Storage restore request is made, to the time
the first byte of data is retrieved. The retrieval time metric is measured by Time To First Byte
(TTFB). How long the full restoration takes, depends on the size of the object. You can
determine the status of the restoration by looking at the object Details. Once the status
shows as Restored, you can then download the object.
After an object is restored, you have a window of time to download the object. By default, you
have 24 hours to download an object, but you can alternatively specify a time from 1 to 240
hours. You can find out how much of the download time is remaining by looking at Available
for Download in object Details. After the allotted download time expires, the object returns
to Archive Storage. You always have access to the metadata for an object, regardless of
whether the object is in an archived or restored state.

See Managing Objects for detailed instructions on restoring, checking status of, and
downloading Archive Storage objects.
Ways to Access Archive Storage

Archive Storage and Object Storage share the same management interfaces:
l The Console is an easy-to-use, browser-based interface.

After signing into the Console, click Storage, and then click Object Storage. A list of
the buckets in the compartment you're viewing is displayed. If you don’t see the one
you're looking for, verify that you’re viewing the correct compartment (select from the
list on the left side of the page). Find the particular Archive Storage tier bucket you
want to manage.
l The command line interface (CLI) provides both quick access and full functionality
without the need for programming. For more information, see Command Line Interface
(CLI).
The syntax for the CLI commands include specifying a service. You will use the Object
Storage service designation: oci os to manage Archive Storage using the CLI.
l The REST API provides the most functionality, but requires programming expertise. API
Reference and Endpoints provides endpoint details and links to the available API
reference documents. For general information about using the API, see About the API.
l The Oracle Cloud Infrastructure SDKs offer tools to interact with Object Storage and
Archive Storage without having to create a framework. For general information about
using the SDKs, see SDKs and Other Tools.
Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see

Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
WORM Compliance
You can achieve WORM compliance with Archive Storage by applying IAM policy permissions
so that data once written, cannot be overwritten.
For administrators: There is not a direct way to disallow OBJECT_OVERWRITE. To achieve

WORM compliance, you must specifically grant groups OBJECT_CREATE, OBJECT_READ, and
OBJECT_INSPECT permissions to keep the data from being overwritten. For example, you can
allow groups to inspect objects using a policy like the following:
Allow group <group_name> to inspect in compartment <compartment_name>
See for more information. If you are new to policies, see Getting Started with Policies and
Common Policies.
Limits on Archive Storage Resources

See Service Limits for a list of applicable limits and instructions for requesting a limit
increase.
Additional limits include:
l Number of namespaces per root compartment: 1

l Maximum size of object metadata: 2 K

CHAPTER 4 Audit
This chapter explains how to work with audit logs.
Overview of Audit
The Oracle Cloud Infrastructure Audit service automatically records calls to all supported
Oracle Cloud Infrastructure public application programming interface (API) endpoints as log
events. Currently, all services support logging by Audit. Object Storage service supports
logging for bucket-related events, but not for object-related events. Log events recorded by
the Audit service include API calls made by the Oracle Cloud Infrastructure Console,
Command Line Interface (CLI), Software Development Kits (SDK), your own custom clients,
or other Oracle Cloud Infrastructure services. Information in the logs shows what time API
activity occurred, the source of the activity, the target of the activity, what the action was,
and what the response was.
Each log event includes a header ID, target resource(s), time stamp of the recorded event,
request parameters, and response parameters. You can view events logged by the Audit
service by using the Console, API, or the Java SDK. You can view events, copy the details of
individual events, as well as analyze events or store them separately. Data from events can
be used to perform diagnostics, track resource usage, monitor compliance, and collect
security-related events.
Ways to Access Oracle Cloud Infrastructure

You can access Oracle Cloud Infrastructure using the Console (a browser-based interface) or
the REST API. Instructions for the Console and API are included in topics throughout this
guide. For a list of available SDKs, see SDKs and Other Tools.
To access the Console, you must use a supported browser. Oracle Cloud Infrastructure
For general information about using the API, see About the API.

CHAPTER 4 Audit

using.
Contents of an Audit Log Event

The following explains the contents of a log event. The table does not include request headers
that are specific to an Internet browser or other client.
Property Description
compartmentId The Oracle Cloud Identifier (OCID) of the compartment.
credentialId The credential ID of the user. This value is extracted from

the HTTP 'Authorization' request header. It consists of the
tenantId, userId, and user fingerprint, all delimited by
a slash (/).
eventId The global unique identifier (GUID) of the event.
eventSource The source of the event.

CHAPTER 4 Audit
Property Description
eventTime The time the event occurred, expressed in RFC 3339

timestamp format.
eventType The type of the event. (Currently, Audit supports only API
activities.)
principalId The OCID of the user whose action triggered the event.
requestAction The HTTP method of the request.
requestAgent The user agent of the client that made the request.
requestHeaders The HTTP header fields and values in the request.
requestId The opc-request-id of the request. An opc-request-id is a

unique Oracle-assigned identifier for the request. If you
need to contact Oracle about a particular request, please
provide the request ID.
requestOrigin The IP address of the source of the request.
requestParameters The query parameter fields and values for the request.
responsePayload Metadata of interest from the response payload. For

example, the OCID of a resource.
requestResource The resource targeted by the request.
responseHeaders The headers of the response.
responseStatus The status code of the response.
responseTime The time of the response to the audited request,

expressed in RFC 3339 timestamp format.
tenantId The OCID of the tenant.

CHAPTER 4 Audit
Each Oracle Cloud Infrastructure resource has a unique, Oracle-assigned identifier called an
Oracle Cloud ID (OCID). For information about the OCID format and other ways to identify
your resources, see Resource Identifiers.
Example Log Events

The following is an array of example log events recorded by the Audit service. The example
log events represent the creation of a new instance, but are excerpted for brevity.
[
{
"requestAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"credentialId": "<tenant_id/user_id/fingerprint>",
"responseTime": "2017-01-06T02:44:47.673Z",
"eventType": "ServiceApi",
"requestHeaders": {
"origin": [
"https://console.us-phoenix-1.oraclecloud.com"
],
"Authorization": [
"<authorization_string>"
],
"X-Real-IP": [
"192.0.2.0"
],
"User-Agent": [
"Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0"
],
"Accept-Encoding": [
"gzip, deflate"
],
"Opc-Client-Info": [
"Oracle-HgConsole/0.0.1"
],
"Accept-Language": [
"en-US,en;q=0.5"
],
"X-Forwarded-Port": [

CHAPTER 4 Audit
"443"
],
"X-Forwarded-For": [
"192.0.2.0"
],
"Opc-Request-Id": [
"0e1e3938-681a-4195-cvb7-35c84311f2ad"
],
"X-Forwarded-Proto": [
"https"
],
"Accept": [
"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
],
"X-Date": [
"Fri, 06 Jan 2017 02:44:46 GMT"
],
"Referer": [
"https://console.us-phoenix-1.oraclecloud.com/"
]
},
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca",
"requestId": "0e1e3938-681a-4195-cvb7-
35c84311/4237AD7DCD5647AA9781193B76910E62/C719042D251B473D929928AE903AB5C9",
"eventSource": "CoreServicesPublicApi",
"responseStatus": "200",
"requestParameters": {
"compartmentId": [
"ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca"
]
},
"requestAction": "GET",
"tenantId": "ocidv1:tenancy:oc1:phx:1457636318783:aaaaaaaacvbgrhwsljxg6mk55eo2tfvxwy",
"responseHeaders": {
"Access-Control-Expose-Headers": [
"opc-previous-page,opc-next-page,opc-client-info,ETag,opc-request-id,Location"
],
"Access-Control-Allow-Origin": [
],

CHAPTER 4 Audit
"Access-Control-Allow-Credentials": [
"true"
],
"Content-Encoding": [
"gzip"
],
"Vary": [
"Accept-Encoding"
],
"opc-request-id": [
"0e1e3938-681a-4195-cvb7-
35c84311/4237AD7DCD5647AA9781193B76910E62/C719042D251B473D929928AE903AB5C9"
],
"Date": [
"Fri, 06 Jan 2017 02:44:47 GMT"
],
"Content-Type": [
"application/json"
]
},
"principalId": "ocid1.user.oc1..aaaaaaaavephoacvbfuxmqlwb4t7dvik5m2ibuokweo6oadif5pda7nxv2nwp3a",
"requestOrigin": "192.0.2.0",
"eventTime": "2017-01-06T02:44:47.599Z",
"eventId": "d30040ae-1b7c-cvbb-97d2-37da42ea6caf",
"requestResource": "/20160918/instances/"
},
...
{
"requestAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"credentialId": "<tenant_id/user_id/fingerprint>",
"responseTime": "2017-01-06T02:45:27.918Z",
"eventType": "ServiceApi",
"requestHeaders": {
"origin": [
],
"Authorization": [
"<authorization_string>"
],
"X-Real-IP": [

CHAPTER 4 Audit
"192.0.2.0"
],
"User-Agent": [
"Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0"
],
"Accept-Encoding": [
"gzip, deflate"
],
"Opc-Client-Info": [
"Oracle-HgConsole/0.0.1"
],
"Accept-Language": [
"en-US,en;q=0.5"
],
"X-Forwarded-Port": [
"443"
],
"X-Forwarded-For": [
"192.0.2.0"
],
"Opc-Request-Id": [
"34b5ac1a-e9ee-4c8c-cvb7-be74f6d4fd07"
],
"X-Forwarded-Proto": [
"https"
],
"Accept": [
"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
],
"X-Date": [
"Fri, 06 Jan 2017 02:45:27 GMT"
],
"Referer": [
"https://console.us-phoenix-1.oraclecloud.com/"
],
"Host": [
"iaas.us-phoenix-1.oraclecloud.com"
]
},
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca",
"requestId": "34b5ac1a-e9ee-4c8c-cvb7-

CHAPTER 4 Audit
be74f6d4/77C6104EA72B47BFB39ED6D88AFFB067/0A4B35F3E09C474A96C3EB4C0DCD6BF1",
"eventSource": "CoreServicesPublicApi",
"responseStatus": "200",
"requestParameters": {
"compartmentId": [
"ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca"
]
},
"requestAction": "GET",
"tenantId": "ocidv1:tenancy:oc1:phx:1457636318783:aaaaaaaacvbgrhwsljxg6mk55eo2tfvxwy",
"responseHeaders": {
"Access-Control-Expose-Headers": [
"opc-previous-page,opc-next-page,opc-client-info,ETag,opc-request-id,Location"
],
"Access-Control-Allow-Origin": [
],
"Access-Control-Allow-Credentials": [
"true"
],
"Content-Encoding": [
"gzip"
],
"Vary": [
"Accept-Encoding"
],
"opc-request-id": [
"34b5ac1a-e9ee-4c8c-cvb7-
be74f6d4/77C6104EA72B47BFB39ED6D88AFFB067/0A4B35F3E09C474A96C3EB4C0DCD6BF1"
],
"Date": [
"Fri, 06 Jan 2017 02:45:27 GMT"
],
"Content-Type": [
"application/json"
]
},
"principalId": "ocid1.user.oc1..aaaaaaaavephoacvbfuxmqlwb4t7dvik5m2ibuokweo6oadif5pda7nxv2nwp3a",
"requestOrigin": "192.0.2.0",
"eventTime": "2017-01-06T02:45:27.816Z",
"eventId": "51bfd56b-9574-4ea4-cvbb-536c584792e1",
"requestResource": "/20160918/instances/"

CHAPTER 4 Audit
}
]
Viewing Audit Log Events

The Audit provides records of API operations performed against supported services as a list of
log events. The service logs events at both the tenant and compartment level. By default,
audit logs are maintained for 90 days. You can configure audit log retention for up to 365
days. Log events are preserved in JavaScript Object Notation (JSON) format and can be
analyzed using standard log analysis tools. To programmatically download logged events, use
the Java SDK. For more information about using the Java SDK, see Getting Started with the
Java SDK.
When viewing events logged by the Audit, you might be interested in specific activities that
happened in the tenancy or compartment and who was responsible for the activity. You will
need to know the approximate time and date something happened and the compartment in
which it happened to display a list of log events that includes the activity in question. List log
events by specifying a time range on the 24-hour clock in Greenwich Mean Time (GMT),
calculating the offset for your local time zone, as appropriate. New activity is appended to the
existing list, usually within 15 minutes of the API call, though processing time can vary.
Required IAM Policy

For administrators: The following policy statement gives the specified group (Auditors) the
ability to view all the Audit event logs in the tenancy:
Allow group Auditors to read audit-events in tenancy
To give the group access to the Audit event logs in a specific compartment only (Project-A),
write a policy like the following:
Allow group Auditors to read audit-events in compartment Project-A

CHAPTER 4 Audit
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for the Audit, see Details for the Audit Service.
Searching and Filtering in the Console

Each log event contains similar fields. To help you search for a specific event in the Console,
the Audit highlights which key-value pairs are shared across events displayed on the same
page. The list of common key-value pairs updates as you paginate through the results.
Depending on what you already know about the activity you want to investigate, different
fields will be useful to search on. To get a better understanding of what values to expect in
each field for a particular activity, see Contents of an Audit Log Event.
In general, the following fields can help you search for a specific event if you know what time
the activity occurred:
l eventTime
l responseTime
For example, a user might report that their attempts to log in began failing at a certain time.
You can search for corresponding operations to confirm the failure and others preceding that
operation to correlate with a reason why.
Note
The service logs events at the time they are processed.

There can be a delay between the time an operation
occurs and when it is processed.
If you have information about what specific actions occurred in your environment, you can
filter according to one of the following fields:
l requestAction
l requestParameters

CHAPTER 4 Audit
l requestResource
l responseStatus
For example, when an instance is deleted, you can search for the instance ID in the
requestResource field along with a DELETE operation in the requestAction field.
Or, if you know who performed the actions in question, you might be interested in the values
in one or more of the following fields:
l principalId
l requestAgent
l compartmentId
The principalId shows the unique Oracle-assigned identifier (OCID) of the user making the
call. If you want to know what activities a specific user has been performing, search for
events where their OCID appears in the principalId field.
Using the Console
To view log events

1. Open the Console, and then click Audit.
2. Click one of the compartments under Compartment.
3. Next to Display Audit Events collected between:, click the first box to display the
date and time editor.
4. Click a date to choose the start date for the range of results you want to see. You can
click the arrows on either side of the month to go backward or forward.
5. Next, click Time (GMT), and then specify a start time by typing a number or pressing
the up and down arrow keys on your keyboard. The service uses a 24-hour clock, so you
must provide a number between 0 and 23 for the hour. Also remember to calculate the
offset between Greenwich Mean Time (GMT) and your local time. When you are ready,
click Done.

CHAPTER 4 Audit
6. Repeat steps 2 through 4 for the second box to choose an end date and time.
Note
The age of the results available can be between 90 and

365 days, depending on your tenancy's setting for audit
log retention period.
The list is updated to include only log events that were processed within the time range you
specified. If an event occurred in the recent past, you might have to wait to see it in the list.
The service typically requires up to 15 minutes for processing. If there are more than 20
results for the specified time range, you can click the right arrow next to the page number to
advance to the next page of log events.
If you want to view all the key-value pairs in a log event, see To view the details of a log
event.
To view the details of a log event

The following assumes you are already viewing a list of log events.
l In the log event row, click the Actions ( ) icon, and then click Details.
To filter log events

In the Console, you can filter log events to view a more focused set of results.
1. Open the Console, and then click Audit.

2. Click one of the compartments under Compartments.
3. Follow steps 3 through 6 in To view log events to set a date and time range.
4. Click the Filter events by text box, and then type the exact text you want to find, and
then press ENTER. You can perform a full or partial search of text on the page, but the

CHAPTER 4 Audit
text must match exactly.
Note
If you want to find log events with a specific status

code, include quotes (") around the code to avoid
results that have those numbers embedded in a
longer string.
To copy the details of a log event

The following assumes you are already viewing a list of events in the log stream.
l In the log event row, click the Actions ( ) icon, and then click Copy.
The log event is copied to your clipboard. The Audit logs events in JSON format. You can paste
the log event details into a text editor to save and review later or to use with standard log
analysis tools.
Using the API
Note
This is a query API. Do not use this API for bulk-export

operations.
Use the following operation to manage log events:
l ListEvents

CHAPTER 4 Audit
Setting Audit Log Retention Period

By default, Audit logs are retained for 90 days. You can configure log retention for up to 365
days. You can edit the log retention period in the Manage Regions page.
Retention period is a tenancy-level setting. The value of the retention period setting affects all
regions and all compartments. You can't set different retention periods for different regions or
compartments.
Required IAM Policy

To modify the Audit log retention period, you must be a member of the Administrators group.
See The Administrators Group and Policy
Using the Console
To modify the Audit log retention period

1. Open the Console, click the Region menu, and then click Manage Regions.
The tenancy details are displayed. The Audit Retention Period is displayed with the
information at the top of the page.
2. Click Edit Audit Retention Policy. Enter the number of days you want to retain the
audit logs for. The minimum you can set the value to is 90 and the maximum is 365.
This value is enforced for all regions and all compartments in the tenancy.
3. Click Submit.
Note
You won't see the new value immediately
It may take several minutes for the new setting to

display in the Console.

CHAPTER 4 Audit
Using the API

Use the following operations to manage the log retention period configuration:
l GetConfiguration
l UpdateConfiguration

CHAPTER 5 Block Volume
This chapter explains how to create storage volumes and attach them to instances.
Overview of Block Volume

The Oracle Cloud Infrastructure Block Volume service lets you dynamically provision and
manage block storage volumes. You can create, attach, connect and move volumes as needed
to meet your storage and application requirements. Once attached and connected to an
instance, you can use a volume like a regular hard drive. Volumes can also be disconnected
and attached to another instance without the loss of data.
The components required to create a volume and attach it to an instance are briefly described
below.
l Instance: A bare metal or virtual machine (VM) host running in the cloud.
l Volume attachment: There are two types of volume attachments:
o iSCSI: A TCP/IP-based standard used for communication between a volume and
attached instance.
o Paravirtualized: A virtualized attachment available for VMs.
l Volume: There are two types of volumes:
Block volume: A detachable block storage device that allows you to dynamically
expand the storage capacity of an instance.
o
Boot volume: A detachable boot volume device that contains the image used to
boot a Compute instance. See Boot Volumes for more information.
o
For additional Oracle Cloud Infrastructure terms, see the Glossary.

Typical Block Volume Scenarios
Scenario A: Expand an Instance's Storage
A common usage of Block Volume is adding storage capacity to an Oracle Cloud Infrastructure
instance. Once you have launched an instance and set up your cloud network, you can create a
block storage volume through the Console or API. Once created, you attach the volume to an
instance using a volume attachment. Once attached, you connect to the volume from your
instance's guest OS using iSCSI. The volume can then be mounted and used by your instance.
Scenario B: Persistent and Durable Storage
A Block Volume volume can be detached from an instance and moved to a different instance
without loss of data. This data persistence allows you to easily migrate data between
instances and ensures that your data is safely stored, even when it is not connected to an
instance. Any data will remain intact until you reformat or delete the volume.
To move your volume to another instance, unmount the drive from the initial instance,
terminate the iSCSI connection, and attach it to the second instance. From there, you simply
connect and mount the drive from that instance's guest OS to instantly have access to all of
your data.
Additionally, Block Volume volumes offer a high level of data durability compared to standard,
attached drives. All volumes are automatically replicated for you, helping to protect against
data loss.
Scenario C: Instance Scaling
When you terminate an instance, you can keep the associated boot volume and use it to
launch a new instance using a different instance type or shape. See Launching an Instance for
how to launch an instance based on a boot volume. This allows you to easily switch from a
bare metal instance to a VM instance and vice versa, or scale up or down the number of cores
for an instance.

Volume Attachment Types

When you attach a block volume to a VM instance, you have two options for attachment type,
iSCSI or paravirtualized. Paravirtualized attachments simplify the process of configuring your
block storage by removing the extra commands required before connecting to an iSCSI-
attached volume. The trade-off is that IOPS performance for iSCSI attachments is greater
than that for paravirtualized attachments, so you need to consider your requirements when
selecting a volume's attachment type.
iSCSI
iSCSI attachments are the only option when connecting block volumes to bare metal
instances, VM instances based on Windows images published prior to February 2018, or VM
instances based on Linux images published prior to December 2017. Once the volume is
attached, you need to log in to the instance and use the iscsiadm command-line tool to
configure the iSCSI connection. For more information about the additional configuration steps
required for iSCSI attachments, see iSCSI Commands and Information, Connecting to a
Volume, and Disconnecting From a Volume.
IOPS performance is better with iSCSI attachments compared to paravirtualized attachments,

for more information about iSCSI-attached volume performance, see Block Volume
Performance.
Paravirtualized
Paravirtualized attachments are now an option when attaching volumes to VM instances. For
VM instances launched from Oracle-Provided Images, you can select this option for Linux-
based images published December 2017 or later, and Windows images published February
2018 or later. For VM instances launched from custom images, the volume attachment type is
based on the volume attachment type from the VM the custom image was created from. Once
you attach a volume using the paravirtualized attachment type, it is ready to use, you do not
need to run any additional commands. However, due to the overhead of virtualization, this
reduces the maximum IOPS performance for larger block volumes, see Paravirtualized
Attachment Performance for more information.

Volume Access Types

When you attach a block volume, you can specify one of the following options for access type:
l Read/write: This is the default option for volume attachments. With this option, an
instance can read and write data to the volume.
l Read-only: With this option, an instance can only read data on the volume, it cannot
update data on the volume. Specify this option to safeguard data against accidental or
malicious modifications.
To change the access type for a block volume, you need to detach the volume and specify the
new access type when you re-attach the volume. For more information, see Detaching a
Volume and Attaching a Volume.
The access type for boot volumes is always read/write. If you want to change the access type,
you need to stop the instance and detach the boot volume. You can then re-attach it to another
instance as a block volume, with read-only specified as the access type. For more
information, see Detaching a Boot Volume and Attaching a Boot Volume.

Volumes are only accessible to instances in the same availability domain . You cannot move a
volume between availability domains or regions.
For more information, see Regions and Availability Domains.

Ways to Access Block Volume


using.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.

Encryption
Block Volume uses the Advanced Encryption Standard (AES) algorithm with 256 bit key for
encryption. Block volumes are encrypted at rest. Backups are also encrypted.
Block Volume Capabilities and Limits

Block Volume volumes can be created in sizes ranging from 50 GB to 16 TB in 1 GB
increments. By default, Block Volume volumes are 1 TB.
Block Volume volume performance varies with volume size.
increase.
l Volumes per instance: 32

l Number of backups
o Monthly universal credits: 1000
o Pay-as-you-go: 500
Boot Volumes
When you launch a virtual machine (VM) or bare metal instance based on an Oracle-provided
image or custom image, a new boot volume for the instance is created in the same
compartment. That boot volume is associated with that instance until you terminate the
instance. When you terminate the instance, you can preserve the boot volume and its data,
see Terminating an Instance. This feature gives you more control and management options
for your compute instance boot volumes, and enables:
l Instance scaling: When you terminate your instance, you can keep the associated
boot volume and use it to launch a new instance using a different instance type or
shape. See Launching an Instance for how to launch an instance based on a boot
volume. This allows you to switch easily from a bare metal instance to a VM instance

and vice versa, or scale up or down the number of cores for an instance.
l Troubleshooting and repair: If you think a boot volume issue is causing a compute
instance problem, you can stop the instance and detach the boot volume. Then you can
attach it to another instance as a data volume to troubleshoot it. After resolving the
issue, you can then reattach it to the original instance or use it to launch a new instance.
Boot volumes are encrypted by default, the same as other block storage volumes. For more
information, see Overview of Block Volume.
For more information about the Block Volume service and boot volumes, see the Block
Volume FAQ.
Custom Boot Volume Sizes

When you launch an instance you can specify whether to use the selected image's default boot
volume size, or you can specify a custom size up to 16 TB. This capability is available for the
following image source options:
l Oracle-provided image
l Custom image
l Image OCID
See Launching an Instance for more information.
The specified size must be larger than the image's default boot volume size or 50 GB,
whichever is higher. Once you've launched the instance, you can't change the boot volume
size.
If you specify a custom boot volume size, you need to extend the volume to take advantage of
the larger size, see Extending a Root or System Partition.
Required IAM Service Policy


For administrators: The policy in Let users launch instances includes the ability to list boot
volumes. The policy in Let volume admins manage block volumes and backups lets the
specified group do everything with block volumes, boot volumes, and backups, but not launch
instances.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for instances, cloud networks, or other Core Services API
resources, see Details for the Core Services.
Using the Console

To access the Console, you must use a supported browser.
See the following tasks for managing boot volumes:
l Listing Boot Volumes

l Attaching a Boot Volume
l Detaching a Boot Volume
l Listing Boot Volume Attachments
l Deleting a Boot Volume
Using the API

Use these API operations to manage boot volumes:
l BootVolume
l ListBootVolumes
l GetBootVolume

l UpdateBootVolume
l DetachBootVolume
l DeleteVolume
l BootVolumeAttachment
l AttachBootVolume
l GetBootVolumeAttachment
l ListBootVolumeAttachments
Extending a Root or System Partition

When you launch a virtual machine (VM) or bare metal instance based on an Oracle-provided
image or custom image, you have the option of specifying a custom boot volume size. In
order to take advantage of the larger size, you must first extend the root (Linux-based
images) or system (Windows-based images) partition.
Required IAM Policy
Extending a partition on an instance does not require a specific IAM policy. However, you may
need permission to run the necessary commands on the instance's guest OS. Contact your
system administrator for more information.
Prerequisites
You must first create the instance, specifying a custom boot volume size. For more
information, see Launching an Instance. You then need to log on to the instance to extend the
partition.
Extending the Root Partition on a Linux Instance

1. Use SSH to connect to your instance.
2. Resize the partition using a partitioning tool like growpart, gdisk, parted, or fdisk.

3. Grow the file system using a file system utility like xfs_growfs or resize2fs,
depending on the image's file system type.
Note
Ubuntu Images
These steps are not required for instances based on

Ubuntu images.
Extending the System Partition on a Windows Instance

1. Open Disk Management on the instance.
2. Right-click Disk 0 and select Extend Volume.
3. Follow the on-screen instructions, and then click Finish.
iSCSI Commands and Information

Block volumes attached with the iSCSI attachment type use the iSCSI protocol to connect a
volume to an instance. See Volume Attachment Types for more information about volume
attachment options.
Once the volume is attached, you need to log on to the instance and use the iscsiadm
command-line tool to configure the iSCSI connection. After you configure the volume, you can
mount it and use it like a normal hard drive.
To enhance security, Oracle enforces an iSCSI security protocol called CHAP that provides
authentication between the instance and volume.
Accessing a Volume's iSCSI Information

When you successfully attach a volume to an instance, Block Volume provides a list of iSCSI
information. You need the following information from the list when you connect the instance to

the volume.
l IP address
l Port
l CHAP user name and password (if enabled)
l IQN
Note
The CHAP credentials are auto-generated by the system

and cannot be changed. They are also unique to their
assigned volume/instance pair and cannot be used to
authenticated another volume/instance pair.
The Console provides this information on the details page of the volume's attached instance.
Click the Actions icon ( ) on your volume's row, and then click iSCSI Information. The
system also returns this information when the AttachVolume API operation completes
successfully. You can re-run the operation with the same parameter values to review the
information.
See Attaching a Volume and Connecting to a Volume for step-by-step instructions.
Additional Reading
There is a wealth of information on the internet about iSCSI and CHAP. If you need more
information on these topics, try the following pages:
l What is iSCSI?
l Oracle Linux Administrator's Guide for Release 7 - About iSCSI Storage
l Oracle Linux Administrator's Guide for Release 6 - About iSCSI Storage
l Troubleshooting iSCSI Configuration Problems
l iscsiadm Basics

Creating a Volume
You can create a volume using Block Volume.
Required IAM Policy

For administrators: The policy in Let volume admins manage block volumes and backups lets
the specified group do everything with block volumes and backups.
Tagging Resources
Using the Console

1. In the Console, click Storage.
2. Click Create Block Volume.
3. Fill in the required volume information:
l Name: A user-friendly name or description.
l Domain: Must be in the same availability domain as the instance.

l Size: Must be between 50 GB and 16 TB. You can choose in 1 GB increments

within this range. The default is 1024 GB. If you choose a size outside of your
service limit, you may be prompted to request an increase. For more information,
see Service Limits.
l Backup Policy: Select the appropriate backup policy for your requirements. See
Policy-Based Backups for more information about backup policies. If you only
require on-demand manual backups, select None.
l Tags: Optionally, you can apply tags. If you have permissions to create a
resource, you also have permissions to apply free-form tags to that resource. To
apply a defined tag, you must have permissions to use the tag namespace. For
more information about tagging, see Resource Tags. If you are not sure if you
should apply tags, skip this option (you can apply tags later) or ask your
administrator.
4. Click Create.
The volume will be ready to attach once its icon no longer lists it as PROVISIONING in
the volume list. For more information, see Attaching a Volume.
Using the API

To create a volume, use the following operation:
l CreateVolume
Attaching a Volume
You can attach a volume to an instance in order to expand the available storage on the
instance. If you specify iSCSI as the volume attachment type, you must still connect and
mount the volume from the instance for the volume to be usable. For more information, see
Volume Attachment Types and Connecting to a Volume.

Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block volumes
and backups lets the specified group do everything with block volumes and backups, but not
launch instances.
Using the Console

1. In the Console, click Compute.
2. In the Instances list, select the instance you want to attach to the volume.
3. Click the name of the instance to display the instance details.
4. In the Resources section on the Instance Details page, click Attached Block
Volumes.
5. Click Attach Block Volume.
6. Select the volume attachment type, iSCSI or PARAVIRTUALIZED.
For more information, see Volume Attachment Types.
7. Select the compartment from the Block Volume Compartment drop-down menu.
8. Select the access type, READ/WRITE or READ-ONLY.
For more information, see Volume Access Types.
9. Select the volume you want from the Volume drop-down menu.
10. Click Attach.

Once the volume's icon no longer lists it as Attaching, you can use the volume if the
attachment type is Paravirtualized. If the attachment type is iSCSI, you need to connect
to the volume first. For more information, see Connecting to a Volume.
Using the API

To attach a volume to an instance, use the following operation:
l AttachVolume
/etc/fstab Options
Block volumes on Oracle Cloud Infrastructure use iSCSI to connect to instances. On Linux
instances, if you want to mount automatically the iSCSI volumes on instance boot, you need
to set some specific options in the /etc/fstab file, or the instance may fail to launch. The
launch failure can occur because the operating system tries to mount the volume before the
iSCSI initiator has started. This topic covers the options to use.
Volume UUIDs
On Linux operating systems, the order in which iSCSI volumes are attached is non-
deterministic, so it can change with each reboot. If you refer to a volume using the device
name, such as /dev/sdb, and you have more than one non-root iSCSI volume, you can't
guarantee that the volume you intend to mount for a specific device name will be the volume
mounted.
To prevent this issue, specify the volume UUID in the /etc/fstab file instead of the device
name. When you use the UUID, the mount process matches the UUID in the superblock with
the mount point specified in the /etc/fstab file. This process guarantees that the same
volume is always mounted to the same mount point.

DETERMINING THE UUID FOR A VOLUME
1. Follow the steps outlined in Attaching a Volume and Connecting to a Volume.

2. Once the volumes are connected, create the file system of your choice on each volume
using standard Linux tools.
The remaining steps assume that three volumes were connected, and that an XFS file
system was created on each volume.
3. Run the following command to use the blkid utility to get the UUIDs for the volumes:
sudo blkid
The output will look similar to the following:
{{ /dev/sda3: UUID="1701c7e0-7527-4338-ae9f-672fd8d24ec7" TYPE="xfs" PARTUUID="82d2ba4e-4d6e-

4a33-9c4d-ba52db57ea61"}}
{{ /dev/sda1: UUID="5750-10A1" TYPE="vfat" PARTLABEL="EFI System Partition" PARTUUID="082c26fd-
85f5-4db2-9f4e-9288a3f3e784"}}
{{ /dev/sda2: UUID="1aad7aca-689d-4f4f-aff0-e0d46fc1b89f" TYPE="swap" PARTUUID="94ee5675-a805-
49b2-aaf5-2fa15aade8d5"}}
{{ /dev/sdb: UUID="699a776a-3d8d-4c88-8f46-209101f318b6" TYPE="xfs"}}
{{ /dev/sdd: UUID="85566369-7148-4ffc-bf97-50954cae7854" TYPE="xfs"}}
{{ /dev/sdc: UUID="ba0ac1d3-58cf-4ff0-bd28-f2df532f7de9" TYPE="xfs"}}
The root volume in this output is /dev/sda*. The additional remote iSCSI volumes are:
l /dev/sdb
l /dev/sdc
l /dev/sdd
4. To automatically attach the volumes at /mnt/vol1, /mnt/vol2, and /mnt/vol3

respectively, create the three directories using the following commands:
bash-4.2$ sudo mkdir /mnt/vol1
{{ bash-4.2$ sudo mkdir /mnt/vol2}}
{{ bash-4.2$ sudo mkdir /mnt/vol3}}

Use the _netdev and nofail Options
By default, the /etc/fstab file is processed before the iSCSI initiator starts. To configure the
mount process to initiates iSCSI before the volumes are mounted, specify the _netdev option
on each line of the /etc/fstab file.
When you create a custom image of an instance where the volumes, excluding the root
volume, are listed in the /etc/fstab file, instances will fail to launch from the custom image.
Specify the nofail option in the /etc/fstab file to prevent this issue.
In the example scenario with three volumes, the /etc/fstab file entries for the volumes with
the _netdev and nofail options are as follows:
UUID=699a776a-3d8d-4c88-8f46-209101f318b6 /mnt/vol1 xfs defaults,_netdev,nofail 0 2
UUID=ba0ac1d3-58cf-4ff0-bd28-f2df532f7de9 /mnt/vol2 xfs defaults,_netdev,nofail 0 2
UUID=85566369-7148-4ffc-bf97-50954cae7854 /mnt/vol3 xfs defaults,_netdev,nofail 0 2
Once you have updated the /etc/fstab file, use the following command to mount the
volumes:
bash-4.2$ sudo mount -a
Reboot the instance to that confirm the volumes are mounted properly on reboot with the
following command:
bash-4.2$ sudo reboot
Troubleshooting Issues with the /etc/fstab File
If the instance fails to reboot after you update the /etc/fstab file, you may need to undo the
changes to the /etc/fstab file. To update the file, connect to the serial console for the
instance using the steps described in Instance Console Connections. Once you have access to
the instance using the serial console connection, you can remove, comment out, or fix the
changes you made to the /etc/fstab file.
Attaching a Boot Volume

If a boot volume has been detached from the associated instance, or if the instance is stopped
or terminated, you can attach it to another instance as a data volume. The steps are the same

as the steps for attaching a block volume, see Attaching a Volume.
You can also reattach a boot volume to the associated instance. If you want to restart an
instance with a detached boot volume, you must reattach the boot volume using the steps
described in this topic.
Required IAM Policy

launch instances.
Using the Console

2. Choose your Compartment.
3. In the Instances list, select the instance you want to attach the boot volume to.
5. In the Resources, click Boot Volume.
6. Click the Actions icon ( ) for the boot volume.
7. Click Attach and confirm the selection when prompted.

You can start the instance once the boot volume's icon no longer lists it as ATTACHING.
For more information, see Stopping and Starting an Instance.
Using the API

To attach a volume to an instance, use the following operation:
l AttachBootVolume
Connecting to a Volume
For volumes attached with iSCSI as the volume attachment type, you need to connect and
mount the volume from the instance for the volume to be usable. For more information about
attachment type options, see Volume Attachment Types. In order to connect the volume, you
must first attach the volume to the instance, see Attaching a Volume.
Important
Connecting with iSCSI on Linux Instances
On Linux instances, for block volumes that use iSCSI to

attach to instances, if you want to automatically mount
these volumes on instance boot, you need to use some
specific options in the /etc/fstab file, or the instance
may fail to launch. This can occur because the operating
system tries to mount the volume before the iSCSI
initiator has started. See /etc/fstab Options for the
options to use in the /etc/fstab file.

Required IAM Policy

Connecting a volume to an instance does not require a specific IAM policy. However, you may
need permission to run the necessary commands on the instance's guest OS. Contact your
system administrator for more information.
Prerequisites
You must attach the volume to the instance before you can connect the volume to the
instance's guest OS. For details, see Attaching a Volume.
To connect the volume, you need the following information:
l iSCSI IP Address
l iSCSI Port numbers
l CHAP credentials (if you enabled CHAP)
l IQN
The Console provides the commands required to configure, authenticate, and log on to iSCSI.
Connecting to a Volume on a Linux Instance

1. Use the Console to obtain the iSCSI data you need to connect the volume:
a. Log on to Oracle Cloud Infrastructure.
b. Click Compute, and then click Instances to find your instance.
c. Click the name of the instance to display the instance details.
d. In the Resources section on the Instance Details page, click Attached Block
Volumes to view the attached block volume.
e. Click the Actions icon ( ) next to the volume you are interested in, and then
click iSCSI Commands and Information.

The iSCSI Commands and Information dialog box displays specific identifying

information about your volume and the iSCSI commands you'll need. The
commands are ready to use with the appropriate information included. You can
copy and paste the commands into your instance session window for each of the
following steps.
2. Log on to your instance's guest OS.
3. Register the volume with the iscsiadm tool.
iscsiadm -m node -o new -T <volume IQN> -p <iSCSI IP address>:<iSCSI port>
A successful registration response resembles the following:

New iSCSI node [tcp:[hw=,ip=,net_if=,iscsi_if=default] 169.254.0.2,3260,-1 iqn.2015-
12.us.oracle.com:c6acda73-90b4-4bbb-9a75-faux09015418] added
4. Configure iSCSI to automatically connect to the authenticated block storage volumes

after a reboot:
iscsiadm -m node -T <volume IQN> -o update -n node.startup -v automatic
Note: All command arguments are essential. Success returns no response.

5. Skip this step if CHAP is not enabled. If you enabled CHAP when you attached the
volume, authenticate the iSCSI connection by providing the volume's CHAP credentials
as follows:
iscsiadm -m node -T <volume IQN> -p <iSCSI IP address>:<iSCSI port> -o update -n
node.session.auth.authmethod -v CHAP
iscsiadm -m node -T <volume IQN> -p <iSCSI IP address>:<iSCSI port> -o update -n

node.session.auth.username -v <CHAP user name>
iscsiadm -m node -T <volume's IQN> -p <iSCSI IP address>:<iSCSI port> -o update -n

node.session.auth.password -v <CHAP password>
Success returns no response.

6. Log in to iSCSI:
iscsiadm -m node -T <volume's IQN> -p <iSCSI IP Address>:<iSCSI port> -l
A successful login response resembles the following:

Logging in to [iface: default, target: iqn.2015-12.us.oracle.com:c6acda73-90b4-4bbb-9a75-

faux09015418, portal: 169.254.0.2,3260] (multiple)
Login to [iface: default, target: iqn.2015-12.us.oracle.com:c6acda73-90b4-4bbb-9a75-faux09015418,
portal: 169.254.0.2,3260] successful.
7. You can now format (if needed) and mount the volume. To get a list of mountable iSCSI
devices on the instance, run the following command:
fdisk -l
The connected volume listing resembles the following:

Disk /dev/sdb: 274.9 GB, 274877906944 bytes, 536870912 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Tip
If you have multiple volumes that do not have

CHAP enabled, you can log in to them all at once by
using the following commands:
iscsiadm -m discovery -t sendtargets -p <iSCSI IP
address>:<iSCSI port>
iscsiadm -m node –l
Connecting to a Volume on a Windows Instance

1. Use the Console to obtain the iSCSI data you need to connect the volume:
a. Log on to Oracle Cloud Infrastructure.
b. Click Compute, and then click Instances to find your instance.
c. Click your instance's name to display the instance details.
d. In the Resources section on the Instance Details page, click Attached Block
Volumes to view the attached block volume.

e. Click the Actions icon ( ) next to the volume you are interested in, and then
click iSCSI Commands and Information.
The iSCSI Commands and Information dialog box displays your volume’s IP
address and port, which you’ll need to know later in this procedure.
2. Log in to your instance using a Remote Desktop client.
3. Open Server Manager, click Tools, and then select iSCSI Initiator.
The iSCSI Initiator Properties dialog opens.
4. Click the Discovery tab, and then click Discover Portal.
5. Enter the block volume IP Address and Port, and then click OK.
6. Click the Targets tab.
7. Under Discovered targets, select the volume IQN.
8. Click Connect.
9. Make sure that the Add this connection to the list of favorite targets check box
is selected, and then click OK.
10. You can now format (if needed) and mount the volume. To view a list of mountable
iSCSI devices on your instance, in Server Manager, click File and Storage
Services, and then click Disks.
The disk is displayed in the list.
Listing Volumes
You can list all Block Volume volumes in a specific compartment, as well as detailed
information on a single volume.


For administrators: The policy in Let users launch instances includes the ability to list
specified group do everything with block volumes and backups, but not launch instances.
Using the Console

In the Console, click Storage. A detailed list of volumes in your current compartment is
displayed.
l To view the volumes in a different compartment, change the compartment in the

Compartment drop-down menu.
Using the API

List Volumes:
Get a list of volumes within a compartment.
l ListVolumes
Get a Single Volume:
Get detailed information on a single volume:
l GetVolume

Listing Boot Volumes

You can list all boot volumes in a specific compartment, or detailed information on a single
boot volume.

For administrators: The policy in Let users launch instances includes the ability to list
Using the Console

1. In the Console, click Storage, and then click Boot Volumes.
A detailed list of volumes in the current compartment is displayed. To see detailed

information for a specific volume, click the boot volume name.
The instance associated with the boot volume is listed in the Attached Instance field. If the
value for this field displays:
None in this Compartment.
the boot volume has been detached from the associated instance, or the instance has been
terminated while the boot volume was preserved.

To view the volumes in a different compartment, change the compartment in the

Compartment drop-down menu.
Using the API

List Boot Volumes:
Get a list of boot volumes within a compartment.
l ListBootVolumes
Get a Single Boot Volume:
Get detailed information on a single boot volume:
l GetBootVolume
Listing Volume Attachments

You can use the API to list all Block Volume volume attachments in a specific compartment, as
well as detailed information on a single volume attachment.
Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to list volume
attachments. The policy in Let volume admins manage block volumes and backups lets the

Using the API

List Attachments:
Get information on all volume attachments in a specific compartment.
l ListVolumeAttachments
Get a Single Attachment:
Get detailed information on a single attachment.
l GetVolumeAttachment
Listing Boot Volume Attachments

You can use the API to list all the boot volume attachments in a specific compartment. You can
also use the API to retrieve detailed information on a single boot volume attachment.
Required IAM Policy


For administrators: The policy in Let users launch instances includes the ability to list volume
attachments. The policy in Let volume admins manage block volumes and backups lets the
Using the API

List Boot Volume Attachments:
Get information on all boot volume attachments in a specific compartment.
l ListBootVolumeAttachments
Get a Single Boot Volume Attachment:
Get detailed information on a single boot volume attachment.
l GetBootVolumeAttachment
Renaming a Volume
You can use the API to change the display name of a Block Volume volume.
Required IAM Policy


For administrators: The policy in Let users launch instances includes the ability to rename
block volumes. The policy in Let volume admins manage block volumes and backups lets the
Using the API

To update a volume's display name, use the following operation:
l UpdateVolume
Overview of Block Volume Backups

The backups feature of the Oracle Cloud Infrastructure Block Volume service lets you make a
point-in-time backup of data on a block volume. These backups can then be restored to new
volumes either immediately after a backup or at a later time that you choose. Backups are
encrypted and stored in Oracle Cloud Infrastructure Object Storage, and can be restored as
new volumes to any availability domain within the same region they are stored. This
capability provides you with a spare copy of a volume and gives you the ability to successfully
complete disaster recovery within the same region.
There are two ways you can initiate a backup, either by manually starting the backup, or by
assigning a policy which defines a set backup schedule.
Manual Backups
These are on-demand one-off backups that you can launch immediately by following the steps
described in Backing Up a Volume. When launching a manual backup, you can specify whether
an incremental or full backup should be performed. See Volume Backup Types for more
information about backup types.

Policy-Based Backups
These are automated scheduled backups. Each backup policy has a set backup frequency and
retention period. There are three predefined policies, Bronze, Silver, and Gold.
See Policy-Based Backups for more information.
Volume Backup Types

There are two backup types available in the Block Volume service:
l Incremental: This backup type includes only the changes since the last backup.
l Full: This backup type includes all changes since the volume was created.
Note
Backup Details
Backups are not an identical copy of the volume being

backed up. For incremental backups, they are a record
of all the changes since the last backup. For full
backups, they are a record of all the changes since the
volume was created. For example, in a scenario where
you create a 16 TB block volume, modify 40 GB on the
volume, and then launch a full backup, upon completion
the volume backup size is 40 GB.
Planning Your Backup

The primary use of backups is to support business continuity, disaster recovery, and long-
term archiving. When determining a backup schedule, your backup plan and goals should
consider the following:

l Frequency: How often you want to back up your data.

l Recovery time: How long you can wait for a backup to be restored and accessible to
your applications that use it. The time for a backup to complete varies on several
factors, but it will generally take a few minutes or longer, depending on the size of your
data being backed up and the amount of data that has changed since your last backup.
l Number of stored backups: How many backups you need to keep available and the
deletion schedule for those you no longer need. You can only create one backup at a
time, so if a backup is underway, it will need to complete before you can create another
one. For details about the number of backups you can store, see Block Volume
Capabilities and Limits.
The common use cases for using backups are:
l Creating multiple copies of the same volume. Backups are highly useful in cases where
you need to create many instances with many volumes that need to have the same data
formation.
l Taking a snapshot of your work that you can restore to a new volume at a later time.
l Ensuring you have a spare copy of your volume in case something goes wrong with your
primary copy.
Best Practices When Creating Block Volume Backups

When creating and restoring from backups, keep in mind the following:
l Before creating a backup, you should ensure that the data is consistent: Sync the file
system, unmount the file system if possible, and save your application data. Only the
data on the disk will be backed up. When creating a backup, once the backup state
changes from REQUEST_RECEIVED to CREATING, you can return to writing data to the
volume. While a backup is in progress, the volume that is being backed up cannot be
deleted.
l If you want to attach a restored volume that has the original volume attached, be aware
that some operating systems do not allow you to restore identical volumes. To resolve
this, you should change the partition IDs before restoring the volume. How to change an

operating system's partition ID varies by operating system; for instructions, see your
operating system's documentation.
l You should not delete the original volume until you have verified that the backup you
created of it completed successfully.
See Backing Up a Volume and Restoring a Backup to a New Volume for more information.
Backing Up a Volume
You can create a backup of a volume using Block Volume.
Required IAM Policy

the specified group do everything with block volumes and backups. The policy in Let volume
backup admins manage only backups further restricts access to just creating and managing
backups.
Tip
When users create a backup from a volume or restore a

volume from a backup, the volume and backup don't
have to be in the same compartment. However, users
must have access to both compartments.

Using the Console

2. Click Block Volumes.
3. Click the block volume for which you want to create a backup.
4. Click Create Manual Backup.
5. Enter a name for the backup.
6. Select the backup type, either incremental or full. See Volume Backup Types for
information about backup types.
7. Optionally, you can apply tags. If you have permissions to create a resource, you also
have permissions to apply free-form tags to that resource. To apply a defined tag, you
must have permissions to use the tag namespace. For more information about tagging,
see Resource Tags. If you are not sure if you should apply tags, skip this option (you
can apply tags later) or ask your administrator.
8. Click Create Backup.
The backup will be completed once its icon no longer lists it as CREATING in the
volume list.
Using the API

To back up a volume, use the following operation:
l CreateVolumeBackup
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.

Policy-Based Backups
The Oracle Cloud Infrastructure Block Volume service provides you with the capability to
perform volume backups automatically on a schedule and retain them based on the selected
backup policy. This allows you to adhere to your data compliance and regulatory
requirements.
Warning
Deleting Block Volumes with Policy-Based Backups
All policy-based backups will eventually expire, so if

you want to keep a volume backup indefinitely, you
need to create a manual backup.
Volume Backup Policies

There are three predefined backup policies, Bronze, Silver, and Gold. Each backup policy has
a set backup frequency and retention period.
Bronze Policy
The bronze policy includes monthly incremental backups, run on the first day of the month.
These backups are retained for twelve months. This policy also includes a full backup, run
yearly on January 1st. Full backups are retained for five years.
Silver Policy
The silver policy includes weekly incremental backups that run on Sunday. These backups are
retained for four weeks. This policy also includes monthly incremental backups, run on the
first day of the month and are retained for twelve months. Also includes a full backup, run
yearly on January 1st. Full backups are retained for five years.

Gold Policy
The gold policy includes daily incremental backups. These backups are retained for seven
days. This policy also includes weekly incremental backups that run on Sunday and are
retained for four weeks. Also includes monthly incremental backups, run on the first day of
the month, retained for twelve months, and a full backup, run yearly on January 1st. Full
backups are retained for five years.
Assigning a Backup Policy to Volumes

When you create a new volume on Oracle Cloud Infrastructure you can select the appropriate
backup policy at that time, for more information, see Creating a Volume.
If your requirements change, you can adjust the schedule and retention period by selecting a
different backup policy or by removing it all together. You can also assign a backup policy to
an existing volume. See Using the Console.
Required IAM Policy

the specified group do everything with block volumes and backups. The policy in Let volume
backup admins manage only backups further restricts access to just creating and managing
backups.

Tip

Using the Console

You can use the Console to assign or change the backup policy for an existing volume.
To assign a backup policy

3. Click the volume for which you want to assign a backup policy to.
4. Click Assign Backup Policy.
5. Select the appropriate backup policy for your requirements.
To remove a backup policy

3. Click the volume for which you want to remove the backup policy for.

4. Click Remove Backup Policy.

5. Click OK to confirm the backup policy removal.
To change a backup policy

3. Click the volume for which you want to change the backup policy for.
4. Click Remove Backup Policy.
5. Click OK to confirm the backup policy removal.
7. Select the backup policy you want to switch to.
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.
Restoring a Backup to a New Volume

You can restore a backup of a volume as a new volume using Block Volume.
Required IAM Policy


Tip

Using the Console

1. In the Console, click Storage, and then click Backups.
A list of the block volumes in the compartment you're viewing is displayed. If you don’t
see the one you're looking for, make sure you’re viewing the correct compartment
(select from the list on the left side of the page).
2. Select the block volume backup you want to restore.
3. Click Create Block Volume.
4. Enter a name for the block volume and choose the availability domain in which you want
to restore it.
5. Click Create.
The volume will be ready to attach once its icon no longer lists it as PROVISIONING in
the volume list. For more information, see Attaching a Volume.

Warning
If you want to attach a restored volume that has the

original volume attached, be aware that some operating
systems do not allow you to restore identical volumes.
To resolve this, you should change the partition IDs
before restoring the volume. How to change an
operating system's partition ID varies by operating
system; for instructions, see your operating system's
documentation.
Using the API

The API used to restore a backup is CreateVolume. The API has an optional volumeBackupId
parameter that you can use to define the backup from which the data should be restored on
the newly created volume. For details, see CreateVolumeDetails Reference.
For more information about backups, see Overview of Block Volume Backups and Backing Up
a Volume.
Cloning a Volume
You can create a clone from a volume using the Block Volume service. Cloning enables you to
make a copy of an existing block volume without needing to go through the backup and
restore process. For more information about volume backups, see Overview of Block Volume
Backups and Backing Up a Volume. For more information about the Block Volume service and
cloned volumes, see the Block Volume FAQ.
A cloned volume is a point-in-time direct disk-to-disk deep copy of the source volume, so all
the data that is in the source volume when the clone is created is copied to the clone volume.
Any subsequent changes to the data on the source volume are not copied to the clone. Since

the clone is a copy of the source volume, you cannot change the size, it will be the same size
as the source volume.
The clone operation occurs immediately, and you can attach and use the cloned volume as a
regular volume as soon as the state changes to available. At this point, the volume data is
being copied in the background, and can take up to thirty minutes depending on the size of the
volume.
There is a single point-in-time reference for a source volume while it is being cloned, so if the
source volume is attached when a clone is created, you need to wait for the first clone
operation to complete from the source volume before creating additional clones. If the source
volume is detached, you can create up to ten clones from the same source volume
simultaneously.
You can only create a clone for a volume within the same region, availability domain and
tenant. You can create a clone for a volume between compartments as long as you have the
required access permissions for the operation.
Using the Console

2. In the Volumes list, click the volume you want to clone.
3. In Resources, click Clones.
4. Click Create Clone.
The volume is ready use once its icon lists it as AVAILABLE in the volume list. At this point,
you can perform various actions on the volume such as creating a clone from the volume,
attaching it to an instance, or deleting the volume.
Using the API


To create a clone from a volume, use the CreateVolume operation and specify
VolumeSourceFromVolumeDetails for CreateVolumeDetails.
Disconnecting From a Volume

For volumes attached with iSCSI as the volume attachment type you need to disconnect the
volume from an instance before you detach the volume. For more information about
attachment type options, see Volume Attachment Types.
Required IAM Policy

Disconnecting a volume from an instance does not require a specific IAM policy. Don't confuse
this with detaching a volume (see Detaching a Volume).
Disconnecting from a Volume on a Linux Instance
Warning
Oracle recommends that you unmount and disconnect

the volume from the instance using iscsiadm before
you detach the volume. Failure to do so may lead to loss
of data.
1. Log on to your instance's guest OS and unmount the volume.

2. Run the following command to disconnect the instance from the volume:
iscsiadm -m node -T <IQN> -p <iSCSI IP ADDRESS>:<iSCSI PORT> -u
A successful logout response resembles the following:

Logging out of session [sid: 2, target: iqn.2015-12.us.oracle.com:c6acda73-90b4-4bbb-9a75-
faux09015418, portal: 169.254.0.2,3260]
Logout of [sid: 2, target: iqn.2015-12.us.oracle.com:c6acda73-90b4-4bbb-9a75-faux09015418,
portal: 169.254.0.2,3260] successful.

3. You can now detach the volume without the risk of losing data.
Disconnecting from a Volume on a Windows Instance

1. Use a Remote Desktop client to log on to your Windows instance, and then open Disk
Management.
2. Right-click the volume you want to disconnect, and then click Offline.
3. Open iSCSI Initiator, select the target, and then click Disconnect.
4. Confirm the session termination. The status should show as Inactive.
5. In iSCSI Initiator, click the Favorite Targets tab, select the target you are
disconnecting, and then click Remove.
6. Click the Volumes and Devices tab, select the volume from the Volume List, and
then click Remove.
7. You can now detach the volume without the risk of losing data.
Detaching a Volume
When an instance no longer needs access to a volume, you can detach the volume from the
instance without affecting the volume's data.
Required IAM Policy

launch instances.

Using the Console
Warning
For volumes attached using iSCSI Oracle recommends

that you unmount and disconnect the volume from the
instance using iscsiadm before you detach the volume.
Failure to do so may lead to loss of data. See
Disconnecting From a Volume for more information.

2. In the Instance list locate the instance. Click its name to display the instance details.
3. In the Resources section on the Instance Details page, click Attached Block
Volumes
4. Click Detach next to the volume you want to detach and confirm the selection when
prompted.
Using the API

To delete an attachment, use the following operation:
l DetachVolume

Detaching a Boot Volume

If you think a boot volume issue is causing a compute instance problem, you can stop the
instance and detach the boot volume using the steps described in this topic. Then you can
attach it to another instance as a data volume to troubleshoot it.
Required IAM Policy

launch instances.
Using the Console

You can only detach a boot volume from an instance when the instance is stopped. See
Stopping and Starting an Instance for more information about managing an instance's state.

3. In the Instances list, select the instance you want to attach the boot volume to.
5. In the Resources, click Boot Volume.

6. Click the Actions icon ( ), for the boot volume.

7. Click Detach and confirm the selection when prompted.
You can now attach the boot volume to another instance, for more information see Attaching a
Volume.
Using the API

To delete an attachment, use the following operation:
l DetachBootVolume
Deleting a Volume
You can delete a volume that is no longer needed.
Warning
l You cannot undo this operation. Any data on a

volume will be permanently deleted once the
volume is deleted.
l All policy-based backups will eventually expire, so
if you want to keep a volume backup indefinitely,
you need to create a manual backup. See
Overview of Block Volume Backups for
information about policy-based and manual
backups.

Required IAM Policy

Using the Console

2. In the Volumes list, find the volume you want to delete.
3. Click Terminate next to the volume you want to delete and confirm the selection when
prompted.
Using the API

To delete a volume, use the following operation:
l DeleteVolume
Deleting a Boot Volume

When you terminate an instance, you choose to delete or preserve the associated boot
volume. For more information, see Terminating an Instance. You can also delete a boot

volume if it has been detached from the associated instance. See Detaching a Boot Volume for
how to detach a boot volume.
Warning
You cannot undo this operation. Any data on a volume

will be permanently deleted once the volume is deleted.
You will also not be able to restart the associated
instance.
Required IAM Policy

Using the Console

1. In the Console, click Storage, and then click Boot Volumes.
3. In the Boot Volumes list, find the volume you want to delete.
4. Click the Actions icon ( ) for the boot volume.
5. Click Terminate and confirm the selection when prompted.

Using the API

Use the DeleteBootVolume operation to delete a boot volume.
Block Volume Performance

The content in the sections below apply to Category 7 and Section 3.b of the Oracle PaaS
and IaaS Public Cloud Services Pillar documentation.
Warning
l Before running any tests, protect your data by

making a backup of your data and operating
system environment to prevent any data loss.
l Do not run FIO tests directly against a device that
is already in use, such as /dev/sdX. If it is in use
as a formatted disk and there is data on it,
running FIO with a write workload (readwrite,
randrw, write, trimwrite) will overwrite the data
on the disk, and cause data corruption. Run FIO
only on unformatted raw devices that are not in
use.
The Oracle Cloud Infrastructure Block Volume service lets you dynamically provision and
manage block storage volumes. You can create, attach, connect and move volumes as needed
to meet your storage and application requirements. The Block Volume service uses NVMe-
based storage infrastructure, and is designed for consistency. You just need to provision the
capacity needed and performance scales linearly per GB volume size up to the service
maximums. The following table describes the performance characteristics of the service.

Note
Paravirtualized Attachment Performance
The IOPS performance characteristics described in this

topic are for volumes with iSCSI attachments. Block
Volume performance SLA for IOPS per volume and IOPS
per instance applies to iSCSI volume attachments only,
not to paravirtualized attachments.
Paravirtualized attachments simplify the process of

configuring your block storage by removing the extra
commands needed before accessing a volume.
However, due to the overhead of virtualization, this
reduces the maximum IOPS performance for larger
block volumes. If storage IOPS performance is of
paramount importance for your workloads, you can
continue to experience the guaranteed performance
Oracle Cloud Infrastructure Block Volume offers by
using iSCSI attachments.
Metric Characteristic
Volume Size 50 GB to 16 TB, in 1 GB increments
IOPS 60 IOPS/GB , up to 25,000 IOPS
Throughput 480 KBPS/GB, up to 320 MBPS
Latency Sub-millisecond latencies.
Per-instance Limits 32 attachments per instance, up to 512 TB.
Up to 400K or more IOPS, near line rate throughout.

Testing Methodology and Performance

This section describes the setup of the test environments, the methodology, and the observed
performance. Some of the sample volume sizes tested were:
l 50 GB volume - 3,000 IOPS @ 4K

l 1 TB volume - 25,000 IOPS @ 4K
l Host maximum, Ashburn (IAD) region, twenty 1 TB volumes - 400,000 IOPS @ 4K
These tests used a wide range of volume sizes and the most common read and write patterns
and were generated with the Gartner Cloud Harmony test suite. To show the throughput
performance limits, 256k or larger block sizes should be used. For most environments, 4K,
8K, or 16K blocks are common depending on the application workload, and these are used
specifically for IOPS measurements.
In the observed performance images in this section, the X axis represents the volume size
tested, ranging from 4KB to 1MB. The Y axis represents the IOPS delivered. The Z axis
represents the read/write mix tested, ranging from 100% read to 100% write.
Note
Performance Notes for Instance Types
l The throughput performance results are for bare

metal instances. Throughput performance on VM
instances is dependent on the network bandwidth
that is available to the instance, and further
limited by that bandwidth for the volume.
l IOPS performance is independent of the instance
type or shape, so is applicable to all bare metal
and VM shapes, for iSCSI attached volumes. For
VM shapes with paravirtualized attached volumes,
see Paravirtualized Attachment Performance.

1 TB Block Volume
A 1 TB volume was mounted to a bare metal instance running in the Phoenix region. The
instance shape was dense, workload was direct I/O with 10GB working set. The following
command was run for the Gartner Cloud Harmony test suite:
~/block-storage/run.sh --nopurge --noprecondition --fio_direct\=1 --fio_size=10g --target /dev/sdb --
test iops --skip_blocksize 512b
The results showed that for 1 TB, the bandwidth limit for the larger block size test occurs at
320MBS.
The following images show the observed performance for 1 TB:


50 GB Block Volume
A 50 GB volume was mounted to a bare metal instance running in the Phoenix region. The
instance shape was dense, workload was direct I/O with 10GB working set. The following
~/block-storage/run.sh --nopurge --noprecondition --fio_direct=1 --fio_size=10g --target /dev/sdb --test
iops --skip_blocksize 512b
The results showed that for the 50 GB volume, the bandwidth limit is confirmed as 24,000
KBPS for the larger block size tests (256 KB or larger block sizes), and the maximum of 3,000
IOPS at 4K block size is delivered. For small volumes, a 4K block size is common.
The following images show the observed performance for 50 GB:


Host Maximum - Twenty 1 TB Volumes
Twenty 1 TB volumes were mounted to a bare metal instance running in the Ashburn region.
The instance shape was dense, workload was direct I/O with 10GB working set. The following
~/block-storage/run.sh --nopurge --noprecondition --fio_direct=1 --fio_size=10g --target
/dev/sdb,/dev/sdc,/dev/sdd,/dev/sde,/dev/sdf,/dev/sdg,/dev/sdh,/dev/sdi,/dev/sdj,/dev/sdk,/dev/sdl,/dev
/sdm,/dev/sdn,/dev/sdo,/dev/sdp,/dev/sdq,/dev/sdr,/dev/sds,/dev/sdt,/dev/sdu --test iops --skip_
blocksize 512b
The results showed that for the host maximum test of twenty 1 TB volumes, the average is
2.1GBPS, and 400,000 IOPS to the host for the 50/50 read/write pattern.
The following images show the observed performance for 50 GB:



CHAPTER 6 Compute
This chapter explains how to launch, access, rename, and terminate compute instances.
Overview of the Compute Service

Oracle Cloud Infrastructure Compute lets you provision and manage compute hosts, known as
instances. You can launch instances as needed to meet your compute and application
requirements. After you launch an instance, you can access it securely from your computer,
restart it, attach and detach volumes, and terminate it when you're done with it. Any changes
made to the instance's local drives are lost when you terminate it. Any saved changes to
volumes attached to the instance are retained.
Oracle Cloud Infrastructure offers both Bare Metal and Virtual Machine instances:
l Bare Metal - A bare metal compute instance gives you dedicated physical server
access for highest performance and strong isolation.
l Virtual Machine - A Virtual Machine (VM) is an independent computing environment
that runs on top of physical bare metal hardware. The virtualization makes it possible to
run multiple VMs that are isolated from each other. VMs are ideal for running
applications that do not require the performance and resources (CPU, memory, network
bandwidth, storage) of an entire physical machine.
An Oracle Cloud Infrastructure VM compute instance runs on the same hardware as a

Bare Metal instance, leveraging the same cloud-optimized hardware, firmware,
software stack, and networking infrastructure.
Be sure to review Best Practices for Your Compute Instance for important information about
working with your Oracle Cloud Infrastructure Compute instance.

CHAPTER 6 Compute
Components for Launching Instances

The components required to launch an instance are:
AVAILABILITY DOMAIN
The Oracle Cloud Infrastructure data center within your geographical region that hosts
cloud resources, including your instances. You can place instances in the same or different
availability domains, depending on your performance and redundancy requirements. For
more information, see Regions and Availability Domains.
VIRTUAL CLOUD NETWORK
A virtual version of a traditional network—including subnets, route tables, and gateways—

on which your instance runs. At least one cloud network has to be set up before you launch
instances. For information about setting up cloud networks, see Overview of Networking.
KEY PAIR (FOR LINUX INSTANCES )

A security mechanism required for Secure Shell (SSH) access to an instance. Before you
launch an instance, you’ll need at least one key pair. For more information, see Managing
Key Pairs on Linux Instances.
TAGS
You can apply tags to your resources to help you organize them according to your
business needs. You can apply tags at the time you create a resource, or you can update
the resource later with the desired tags. For general information about applying tags, see
Resource Tags.
PASSWORD (FOR WINDOWS INSTANCES )

A security mechanism required to access an instance that uses an Oracle-provided
Windows image. The first time you launch an instance using a Windows image, Oracle
Cloud Infrastructure will generate an initial, one-time password that you can retrieve
using the console or API. This password must be changed after you initially log on.

CHAPTER 6 Compute
IMAGE
A template of a virtual hard drive that determines the operating system and other
software for an instance. For details about images, see Oracle-Provided Images. You can
also launch instances from custom images or bring your own image.
SHAPE
A template that determines the number of CPUs, amount of memory, and other resources
allocated to a newly created instance. You choose the most appropriate shape when you
launch an instance. The following tables list the available Bare Metal and VM shapes:
Bare Metal Shapes
Shape Instance OCPU Memory Local Network Maximum

Type (GB) Disk Bandwidth VNICs
(TB) 1 Total 2
BM.Standard1.36 Standard 36 256 Block 10 Gbps 16

compute storage
capacity only
BM.HighIO1.36 High I/O 36 512 12.8TB 10 Gbps 16

compute NVMe
capacity SSD
BM.DenseIO1.36 Dense I/O 36 512 28.8TB 10 Gbps 16

compute NVMe
capacity SSD
BM.Standard2.52 X7-based 52 768 Block 2 x 25 Gbps 24 total

standard storage (12 per
compute only physical
capacity NIC)

CHAPTER 6 Compute
Shape Instance OCPU Memory Local Network Maximum

Type (GB) Disk Bandwidth VNICs
(TB) 1 Total 2
BM.DenseO2.52 X7-based 52 768 51.2TB 2 x 25 Gbps 24 total

dense I/O NVMe (12 per
compute SSD physical
capacity NIC)
BM.GPU2.2 X7-based 28 192 Block 2 x 25 Gbps 24 total

GPU: 2 storage (12 per
P100 only physical
NVIDIA NIC)
GPUs
1: Network bandwidth is based on expected bandwidth for traffic within a VCN.
2: Windows bare metal instances support only one VNIC.
VM Shapes
VMs are an option that provides flexibility in compute power, memory capability, and
network resources for lighter applications. You can use Block Volume to add network-
attached block storage as needed.
Shape OCPU Memory Local Disk Network Maximum

(GB) (TB) Bandwidth1 VNICs Total 2
VM.Standard1.1 1 7 Block Up to 600 2

Storage Mbps
only
VM.Standard1.2 2 14 Block Up to 1.2 Gbps 2

Storage
only

CHAPTER 6 Compute

VM.Standard1.4 4 28 Block 1.2 Gbps 2

Storage
only

Storage
only

Storage
only
VM.DenseIO1.4 4 60 3.2 TB 1.2 Gbps 2

NVMe SSD

NVMe SSD

NVMe SSD
VM.Standard2.1 1 15 Block 1 Gbps 2

Storage
only

Storage
only

CHAPTER 6 Compute


Storage
only

Storage
only

Storage
only
VM.Standard.2.24 24 320 Block 24.6 Gbps 12

Storage
only

NVMe SSD

NVMe SSD

NVMe SSD
2: Windows VM instances support only one VNIC.

CHAPTER 6 Compute
Note
X7 Shapes Availability
The X7 shape BM.GPU2.2 is not available in the

Phoenix region.
You can optionally attach volumes to an instance. For more information, see Overview of
Block Volume.



CHAPTER 6 Compute
using.
Limits on Compute Resources

increase.
l To attach a volume to an instance, both the instance and volume must be within the
same availability domain.
l Many Compute operations are subject to throttling.
Metadata Key Limits
Custom metadata keys (any key you define that is not ssh_authorized_keys or user_data)
have the following limits:
l Max number of metadata keys: 128

l Max size of key name: 255 characters
l Max size of key value: 255 characters
ssh_authorized_keys is a special key that does not have these limits, but its value is
validated to conform to a public key in the OpenSSH format.

CHAPTER 6 Compute
user_data has a maximum size of 16KB. For Linux instances with cloud-init configured, you
can populate the user_data field with a Base64-encoded string of cloud-init user data. For
more information on formats that cloud-init accepts, see cloud-init formats. On Windows
instances, the user_data field can be provided but isn't used by Oracle-provided images.
Best Practices for Your Compute Instance

Oracle Cloud Infrastructure Compute provides bare metal compute capacity that delivers
performance, flexibility, and control without compromise. It is powered by Oracle’s next
generation, internet-scale infrastructure designed to help you develop and run your most
demanding applications and workloads in the cloud.
You can provision compute capacity through an easy-to-use web console or an API. The bare
metal compute instance, once provisioned, provides you with access to the host. This gives
you complete control of your instance.
While you have full management authority for your instance, Oracle recommends a variety of
best practices to ensure system availability and top performance.
IP Addresses Reserved for Use by Oracle

The following IP addresses are reserved for Oracle Cloud Infrastructure use:
169.254.0.2, 169.254.2.2-169.254.2.254
For iSCSI connections to the boot and block volumes.
169.254.0.3
For uploads relating to kernel updates. See OS Kernel Updates for more information.
169.254.169.254
For DNS (port 53) and Metadata (port 80) services. See Getting Instance Metadata for more
information.
169.254.169.253
For Windows instances to activate with Microsoft Key Management Service (KMS).

CHAPTER 6 Compute
THREE IP ADDRESSES IN EACH SUBNET

The first two IP addresses and the last one in each subnet's CIDR are reserved.
Essential Firewall Rules
Warning
Windows 2008 Server R2 images do not support

restricting certain firewall rules for local principals,
such as "Administrators", so any authenticated user on
an instance can make outgoing connections to the iSCSI
network endpoints (169.254.0.2:3260,
169.254.2.0/24:3260) that serve the instance's boot and
block volumes.
All Oracle-provided images include rules that allow only "root" on Linux instances or
"Administrators" on Windows Server 2012 R2 and Windows Server 2016 instances to make
outgoing connections to the iSCSI network endpoints (169.254.0.2:3260,
169.254.2.0/24:3260) that serve the instance's boot and block volumes.
l Oracle recommends that you do not reconfigure the firewall on your instance to remove
these rules. Removing these rules allows non-root users or non-administrators to
access the instance’s boot disk volume.
l Oracle recommends that you do not create custom images without these rules unless
you understand the security risks.

CHAPTER 6 Compute
System Resilience
Oracle Cloud Infrastructure runs on Oracle's high quality Sun servers. However, any hardware
can experience a failure. Follow industry-wide hardware failure best practices to ensure the
resilience of your solution. Some best practices include:
l Design your system with redundant compute nodes in different availability domains to
support fail-over capability.
l Create a custom image of your system drive each time you change the image.
l Back up your data drives, or sync to spare drives, regularly.
If you experience a hardware failure and have followed these practices, you can terminate the
failed instance, launch your custom image to create a new instance, and then apply the
backup data.
Uninterrupted Access to the Instance

Make sure to keep the DHCP client running so you can always access the instance. If you stop
the DHCP client manually or disable NetworkManager (which stops the DHCP client on Linux
instances), the instance can't renew its DHCP lease and will become inaccessible when the
lease expires (typically within 24 hours). Do not disable NetworkManager unless you use
another method to ensure renewal of the lease.
Stopping the DHCP client might remove the host route table when the lease expires. Also, loss
of network connectivity to your iSCSI connections might result in loss of the boot drive.
User Access
If you created your instance using an Oracle-provided Linux image, you can use SSH to access
your instance from a remote host as the opc user. After logging in, you can add users on your
instance.
If you do not want to share SSH keys, you can create additional SSH-enabled users.

CHAPTER 6 Compute
If you created your instance using an Oracle-provided Windows image, you can access your
instance using a Remote Desktop client as the opc user. After logging in, you can add users on
your instance.
For more information about user access, see Adding Users on an Instance.
NTP Server
Oracle Cloud Infrastructure offers a fully managed, secure, and highly available NTP server
that you can use to set the date and time of your Compute and Database instances from within
your virtual cloud network (VCN). Oracle recommends that you configure your instances to
use the Oracle Cloud Infrastructure NTP server. For information about how to configure
instances to use this NTP server, see Configuring the Oracle Cloud Infrastructure NTP Server
for an Instance.
Configuring the Oracle Cloud Infrastructure NTP Server for an Instance

Oracle Cloud Infrastructure offers a fully managed, secure, and highly available NTP server
that you can use to set the date and time of your Compute and Database instances from within
your virtual cloud network (VCN). This topic describes how to configure Compute instances to
use this NTP server.
You can also choose to configure your instance to use a public NTP server or use FastConnect
to leverage an on-premises NTP server.
Oracle Linux 6.x

Use the following steps to configure your Oracle Linux 6.x instances to use the Oracle Cloud
Infrastructure NTP server.
1. Configure IPtables to allow connections to the Oracle Cloud Infrastructure NTP server,
using the following commands:
sudo iptables -I BareMetalInstanceServices 8 -d 169.254.169.254/32 -p udp -m udp --dport 123 -m
comment --comment "Allow access to OCI local NTP service" -j ACCEPT

CHAPTER 6 Compute
sudo service iptables save
2. Install the NTP service with the following command:

sudo yum install ntp
3. Set the date of your instance with the following command:

sudo ntpdate 169.254.169.254
4. Configure the instance to use the Oracle Cloud Infrastructure NTP server for iburst. To
configure, modify the /etc/ntp.conf file as follows:
a. In the server section, comment out the lines specifying the RHEL servers:
#server 0.rhel.pool.ntp.org iburst
b. Add an entry for the Oracle Cloud Infrastructure NTP server:

server 169.254.169.254 iburst
The modified server section now contains the following:

# Please consider joining the pool (http://www.pool.ntp.org/join.html).
5. Set the NTP service to launch automatically when the instance boots with the following
command:
sudo chkconfig ntpd on
6. Start the NTP service with the following command:

sudo /etc/init.d/ntpd start
7. Confirm that the NTP service is configured correctly with the following command:
ntpq -p

CHAPTER 6 Compute
The output will be similar to the following:

remote refid st t when poll reach delay offset jitter
==============================================================================
169.254.169.254 192.168.32.3 2 u 2 64 1 0.338 0.278 0.187
Oracle Linux 7.x

Use the following steps to configure your Oracle Linux 7.x instances to use the Oracle Cloud
1. Run commands in this section as root with the following command:

sudo su -
2. Install the NTP service with the following command:

yum -y install ntp
3. Change the firewall rules to allow inbound and outbound traffic with the Oracle Cloud
Infrastructure NTP server, at 169.254.169.254, on UDP port 123 with the following
command:
awk -v n=13 -v s=' <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p udp -m udp --dport
123 -m comment --comment "Allow access to OCI local NTP service" -j ACCEPT </passthrough>' 'NR ==
n {print s} {print}' /etc/firewalld/direct.xml > tmp && mv tmp /etc/firewalld/direct.xml
At the prompt:
mv: overwrite ‘/etc/firewalld/direct.xml’?
enter y
4. Restart the firewall with the following command:
service firewalld restart
5. Set the date of your instance with the following command:

ntpdate 169.254.169.254
6. Configure the instance to use the Oracle Cloud Infrastructure NTP server for iburst. To

CHAPTER 6 Compute
configure, modify the /etc/ntp.conf file as follows:

a. In the server section comment out the lines specifying the RHEL servers:
b. Add an entry for the Oracle Cloud Infrastructure NTP server:

The modified server section should now contain the following:

# Please consider joining the pool (http://www.pool.ntp.org/join.html).
7. Start and enable the NTP service with the following commands:
systemctl start ntpd
systemctl enable ntpd
You also need disable the chrony NTP client to ensure that the NTP service starts
automatically after a reboot, using the following commands:
systemctl stop chronyd
systemctl disable chronyd
8. Confirm that the NTP service is configured correctly with the following command:
ntpq -p

remote refid st t when poll reach delay offset jitter
==============================================================================
169.254.169.254 192.168.32.3 2 u 2 64 1 0.338 0.278 0.187

CHAPTER 6 Compute
Windows Server 2016, Windows Server 2012 R2 and Windows Server 2008 R2
Use the following steps to configure your Windows Server instances to use the Oracle Cloud
1. Change the server type to NTP:

a. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\
b. Click Type.
c. Change the value to NTP and click OK.
2. Configure the Windows Time service to enable the Timeserv_Announce_Yes and
Reliable_Timeserv_Announce_Auto flags.
To configure, set the AnnounceFlags parameter to 5:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
b. Click AnnounceFlags.
c. Change the value to 5 and click OK.
3. Enable the NTP server:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\TimeProviders\NtpServer\
b. Click Enabled.
c. Change the value to 1 and click OK.
4. Set the time sources:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\

CHAPTER 6 Compute
b. Click NtpServer.
c. Change the value to 169.254.169.254,0x9 and click OK.
5. Set the poll interval:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\TimeProviders\NtpClient\
b. Click SpecialPollInterval.
c. Set the value to the interval that you want the time service to synchronize on. The
value is in seconds. To set it for 15 minutes, set the value to 900, and click OK.
6. Set the phase correction limit settings to restrict the time sample boundaries:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
b. Click MaxPosPhaseCorrection.
c. Set the value to the maximum time offset in the future for time samples. The
value is in seconds. To set it for 30 minutes, set the value to 1800 and click OK.
d. Click MaxNegPhaseCorrection.
e. Set the value to the maximum time offset in the past for time samples. The value
is in seconds. To set it for 30 minutes, set the value to 1800 and click OK.
7. Restart the time service by running the following command from a command prompt:
net stop w32time && net start w32time
8. Test the connection to the NTP server by running the following command from a
command prompt:
w32tm /query /peers

#Peer: 1
Peer: 169.254.169.254,0x9
State: Active

CHAPTER 6 Compute
Time Remaining: 22.1901786s

Mode: 3 (Client)
Stratum: 0 (unspecified)
PeerPoll Interval: 10 (1024s)
HostPoll Interval: 10 (1024s)
After the time specified in the poll interval has elapsed, State will change from Pending
to Active.
Protecting Data on NVMe Devices

Some instance shapes in Oracle Cloud Infrastructure include locally attached NVMe devices.
These devices provide extremely low latency, high performance block storage that is ideal for
big data, OLTP, and any other workload that can benefit from high-performance block storage.
Note that these devices are not protected in any way; they are individual devices locally
installed on your instance. Oracle Cloud Infrastructure does not take images, back up, or use
RAID or any other methods to protect the data on NVMe devices. It is your responsibility to
protect and manage the durability the data on these devices.
Oracle Cloud Infrastructure offers high-performance remote block (iSCSI) LUNs that are
redundant and can be backed up using an API call. See Overview of Block Volume for more
information.
The following instance types support local NVMe storage:
Instance Supported NVMe Devices
BM.HighIO1.36 4 - 3.2TB NVMe devices (12.8TB raw)
BM.DenseIO1.36 9 - 3.2TB NVMe devices (28.8TB raw)
Finding the NVMe devices on your instance

You can identify the NVMe devices by using the lsblk command. The response returns a list.
NVMe devices begin with "nvme", as shown in the following example for a BM.DenseIO1.36
instance:

CHAPTER 6 Compute
[opc@somehost ~]$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 46.6G 0 disk
├─sda1 8:1 0 512M 0 part /boot/efi
├─sda2 8:2 0 8G 0 part [SWAP]
└─sda3 8:3 0 38G 0 part /
nvme0n1 259:6 0 2.9T 0 disk
nvme1n1 259:8 0 2.9T 0 disk
nvme2n1 259:0 0 2.9T 0 disk
nvme3n1 259:1 0 2.9T 0 disk
nvme4n1 259:7 0 2.9T 0 disk
nvme5n1 259:4 0 2.9T 0 disk
nvme6n1 259:5 0 2.9T 0 disk
nvme7n1 259:2 0 2.9T 0 disk
nvme8n1 259:3 0 2.9T 0 disk
[opc@somehost ~]$
Failure Modes and How to Protect Against Them

There are three primary failure modes you should plan for:
l Protecting against the failure of an NVMe device

l Protecting Against the Loss of the Instance or Availability Domain
l Protecting Against Data Corruption or Loss from Application or User Error
Protecting against the failure of an NVMe device
A protected RAID array is the most recommended way to protect against an NVMe device
failure. There are three RAID levels that can be used for the majority of workloads:

CHAPTER 6 Compute
l RAID 1: An exact copy (or mirror) of a set of data on two or more disks; a classic
RAID 1 mirrored pair contains two disks, as shown:
l RAID 10: Stripes data across multiple mirrored pairs. As long as one disk in each
mirrored pair is functional, data can be retrieved, as shown:

CHAPTER 6 Compute
l RAID 6: Block-level striping with two parity blocks distributed across all member disks,
as shown.

CHAPTER 6 Compute
For more information about RAID and RAID levels, see RAID.
Because the appropriate RAID level is a function of the number of available drives, the
number of individual LUNs needed, the amount of space needed, and the performance
requirements, there isn't one correct choice. You must understand your workload and design
accordingly.
OPTIONS FOR USING A BM.HIGHIO1.36 S HAPE
There are three recommended options for BM.HighIO1.36 instances:
Create a single RAID 10 device across all four devices. This array provides redundancy by
surviving the failure of any single device and possibly surviving the failure of two devices,

CHAPTER 6 Compute
depending on which devices fail. It would be exposed as a single device with about 6.4TB of
usable space.
Use the following commands to create a single RAID 10 device across four devices:
$ sudo yum install mdadm -y
$ sudo mdadm --create /dev/md0 --raid-devices=4 --level=10 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1

/dev/nvme3n1
$ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null
Create two physically independent RAID 1 arrays. These arrays are exposed as two different
LUNs to your applications. This is a recommended choice when you need to isolate one type of
I/O from another, such as data files and log files. These arrays can survive the failure of any
single device and might survive the failure of two devices, depending on which devices fail.
The usable space for these arrays is about 6.4TB.
Use the following commands to create two physically independent RAID 1 arrays:
$ sudo mdadm --create /dev/md0 --raid-devices=2 --level=1 /dev/nvme0n1 /dev/nvme1n1
$ sudo mdadm --create /dev/md1 --raid-devices=2 --level=1 /dev/nvme2n1 /dev/nvme3n1
Create a RAID 6 array across all four devices. This array has the same amount of space as the
options previously described (about 6.4TB), but its performance will be slower. In exchange
for the slight reduction in performance, you gain additional durability because the array can
survive the failure of any two devices.
Use the following commands to create a RAID 6 across all four devices:

/dev/nvme3n1
OPTIONS FOR USING A BM.DENSE IO1.36 S HAPE
There are several options for BM.DenseIO1.36 instances with nine NVMe devices:

CHAPTER 6 Compute
Create a single RAID 6 device across all nine devices. This array is redundant, performs well,
will survive the failure of any two devices, and will be exposed as a single LUN with about
23.8TB of usable space.
Use the following commands to create a single RAID 6 device across all nine devices:

/dev/nvme3n1 /dev/nvme4n1 /dev/nvme5n1 /dev/nvme6n1 /dev/nvme7n1 /dev/nvme8n1
Create a four device RAID 10 and a five device RAID 6 array. These arrays would be exposed
as two different LUNs to your applications. This is a recommended choice when you need to
isolate one type of I/O from another, such as log and data files. In this example, your RAID 10
array would have about 6.4TB of usable space and the RAID 6 array would have about 9.6TB
of usable space.
Use the following commands to create a four-device RAID 10 and a five-device RAID 6 array:

/dev/nvme8n1

/dev/nvme3n1 /dev/nvme4n1
If you need the best possible performance and can sacrifice some of your available space,
then an eight-device RAID 10 array is an option. Because RAID 10 requires an even number of
devices, the ninth device is left out of the array and serves as a hot spare in case another
device fails. This creates a single LUN with about 12.8 TB of usable space.
Use the following commands to create an eight-device RAID 10 array:


/dev/nvme3n1 /dev/nvme4n1 /dev/nvme5n1 /dev/nvme6n1 /dev/nvme7n1
The following command adds /dev/nvme8n as a hot spare for the /dev/md0 array:
$ sudo mdadm /dev/md0 --add /dev/nvme8n1

CHAPTER 6 Compute
For the best possible performance and I/O isolation across LUNs, create two four-device RAID
10 arrays. Because RAID 10 requires an even number of devices, the ninth device is left out of
the arrays and serves as a global hot spare in case another device in either array fails. This
creates two LUNS, each with about 6.4 TB of usable space.
Use the following commands to create two four-device RAID 10 arrays with a global hot
spare:

/dev/nvme7n1

/dev/nvme3n1
Creating a global hot spare requires the following two steps:
1. Add the spare to either array (it does not matter which one) by running these
commands:
2. Edit /etc/mdadm to put both arrays in the same spare-group. Add spare-group=global
to the end of the line that starts with ARRAY, as follows:
$ sudo vi /etc/mdadm.conf
ARRAY /dev/md0 metadata=1.2 spares=1 name=mdadm.localdomain:0

UUID=43f93ce6:4a19d07b:51762f1b:250e2327 spare-group=global
ARRAY /dev/md1 metadata=1.2 name=mdadm.localdomain:1 UUID=7521e51a:83999f00:99459a19:0c836693

spare-group=global
Monitoring Your Array
It's important for you to be notified if a device in one of your arrays fails. Mdadm has built-in
tools that can be utilized for monitoring, and there are two options you can use:

CHAPTER 6 Compute
l Set the MAILADDR option in /etc/mdadm.conf and then run the mdadm monitor as a
daemon
l Run an external script when mdadm detects a failure
S ET THE MAILADDR OPTION IN /ETC/MDADM.CONF AND RUN THE MDADM MONITOR AS A DAEMON
The simplest method is to set the MAILADDR option in /etc/mdadm.conf, and then run the
mdadm monitor as a daemon, as follows:
1. The DEVICE partitions line is required for MAILADDR to work; if it is missing, you must
add it, as follows:
DEVICE partitions
ARRAY /dev/md0 level=raid1 UUID=1b70e34a:2930b5a6:016we78d:eese14532
MAILADDR <my.name@oracle.com>
2. Run the monitor using the following command:

$ sudo nohup mdadm –-monitor –-scan –-daemonize &
3. To verify that the monitor runs at startup, run the following commands:
$ sudo chmod +x /etc/rc.d/rc.local
$ sudo vi /etc/rc.local
Add the following line to the end of /etc/rc.local:

nohup mdadm –-monitor –-scan –-daemonize &
4. To verify that the email and monitor are both working run the following command:
$ sudo mdadm --monitor --scan --test -1
Note that these emails will likely be marked as spam. The PROGRAM option, described
later in this topic, allows for more sophisticated alerting and messaging.
RUN AN EXTERNAL SCRIPT WHEN A FAILURE IS DETECTED
A more advanced option is to create an external script that would run if the mdadm monitor
detects a failure. You would integrate this type of script with your existing monitoring

CHAPTER 6 Compute
solution. The following is an example of this type of script:

$ sudo vi /etc/mdadm.events
#!/bin/bash
event=$1
device=$2
if [ $event == "Fail" ]
then
<"do something">
else
if [ $event == "FailSpare" ]
then
<"do something else">
else
if [ $event == "DegradedArray" ]
then
<"do something else else">
else
if [ $event == "TestMessage" ]
then
<"do something else else else">
fi
fi
fi
fi
$ sudo chmod +x /etc/mdadm.events
Next, add the PROGRAM option to /etc/mdadm.conf, as shown in the following example:
1. The DEVICE partitions line is required for MAILADDR to work; if it is missing, you must
add it, as follows:
DEVICE partitions
ARRAY /dev/md0 level=raid1 UUID=1b70e34a:2930b5a6:016we78d:eese14532
MAILADDR <my.name@oracle.com>
PROGRAM /etc/mdadm.events

CHAPTER 6 Compute
2. Run the monitor using the following command:

$ sudo nohup mdadm –-monitor –-scan –-daemonize &
3. To verify that the monitor runs at startup, run the following commands:
$ sudo chmod +x /etc/rc.d/rc.local
$ sudo vi /etc/rc.local
Add the following line to the end of /etc/rc.local:

nohup mdadm –-monitor –-scan –-daemonize &
4. To verify that the email and monitor are both working run the following command:
$ sudo mdadm --monitor --scan --test -1
Note that these emails will likely be marked as spam. The PROGRAM option, described
later in this topic, allows for more sophisticated alerting and messaging.
S IMULATE THE FAILURE OF A DEVICE
You can use mdadm to manually cause a failure of a device to see whether your RAID array can
survive the failure, as well as test the alerts you have set up.
1. Mark a device in the array as failed by running the following command:

$ sudo mdadm /dev/md0 --fail /dev/nvme0n1
2. Recover the device or your array might not be protected. Use the following command:
Your array will automatically rebuild in order to use the "new" device. Performance will
be decreased during this process.
3. You can monitor the rebuild status by running the following command:
$ sudo mdadm --detail /dev/md0
What To Do When an NVMe Device Fails
Compute resources in the cloud are designed to be temporary and fungible. If an NVMe device
fails while the instance is in service, you should start another instance with the same amount
of storage or more, and then copy the data onto the new instance, replacing the old instance.

CHAPTER 6 Compute
There are multiple toolsets for copying large amounts of data, with rsync being the most
popular. Since the connectivity between instances is a full 10Gb/sec, copying data should be
quick. Remember that with a failed device, your array may no longer be protected, so you
should copy the data off of the impacted instance as quickly as possible.
Using the Linux Logical Volume Manager
The Linux Logical Volume Manager (LVM) provides a rich set of features for managing
volumes. If you need these features, we strongly recommend that you use mdadm as described
in preceding sections of this topic to create the RAID arrays, and then use LVM's pvcreate,
vgcreate, and lvcreate commands to create volumes on the mdadm LUNs. You should not use
LVM directly against your NVMe devices.
Protecting Against the Loss of the Instance or Availability Domain
Once your data is protected against the loss of a NVMe device, you need to protect it against
the loss of an instance or the loss of the availability domain. This type of protection is typically
done by replicating your data to another availability domain or backing up your data to
another location. The method you choose depends on your objectives. For details, see
Recovery Time Objective (RTO) and Recovery Point Objective (RPO).
REPLICATION
Replicating your data from one instance in one availability domain to another has the lowest
RTO and RPO at a significantly higher cost than backups; for every instance in one availability
domain, you must have another instance in a different availability domain.
For Oracle database workloads, you should use the built-in Oracle Data Guard functionality to
replicate your databases. Oracle Cloud Infrastructure availability domains are each close
enough to each other to support high performance, synchronous replication. Asynchronous
replication is also an option.
For general-purpose block replication, DRBD is the recommended option. You can configure
DRBD to replicate, synchronously or asynchronously, every write in one availability domain to
another availability domain.

CHAPTER 6 Compute
BACKUPS
Traditional backups are another way to protect data. All commercial backup products are fully
supported on Oracle Cloud Infrastructure. If you use backups, the RTO and RPO are
significantly higher than using replication because you must recreate the compute resources
that failed and then restore the most recent backup. Costs are significantly lower because you
don't need to maintain a second instance. Do not store your backups in the same availability
domain as their original instance.
Protecting Against Data Corruption or Loss from Application or User Error
The two recommended ways of protecting against data corruption or loss from application or
user error are regularly taking snapshots or creating backups.
S NAPSHOTS
The two easiest ways to maintain snapshots are to either use a file system that supports
snapshots, such as ZFS, or use LVM to create and manage the snapshots. Because of the way
LVM has implemented copy-on-write (COW), performance may significantly decrease when a
snapshot is taken using LVM.
BACKUPS
All commercial backup products are fully supported on Oracle Cloud Infrastructure. Make sure
that your backups are not stored in the same availability domain as their original instance.

CHAPTER 6 Compute
Oracle-Provided Images
An image is a template of a virtual hard drive. The image determines the operating system
and other software for an instance. The following table lists the images that are available in
Oracle Cloud Infrastructure. For specific image and kernel version details, along with changes
between versions, see Oracle-Provided Image Release Notes.
Image Name Description
Oracle Linux 7 Oracle-Linux-7.x- The Unbreakable Enterprise Kernel (UEK) is

Unbreakable <date>-<number> Oracle's optimized operating system kernel for
Enterprise demanding Oracle workloads.
Kernel Release
GPU shapes are supported with this image.
4
Oracle Linux 6 Oracle-Linux-6.x- The Unbreakable Enterprise Kernel (UEK) is

Unbreakable <date>-<number> Oracle's optimized operating system kernel for
Enterprise demanding Oracle workloads.
Kernel Release
4
CentOS 7 CentOS-7-<date>- CentOS is a free, open-source Linux distribution

<number> suitable for use in enterprise cloud environments.
For more information, see
https://www.centos.org/.
X7 shapes are not supported with this image.
CentOS 6 CentOS-6.x-<date>- CentOS is a free, open-source Linux distribution

<number> that is suitable for use in enterprise cloud
environments. For more information, see
https://www.centos.org/.
X7 shapes are not supported with this image.

CHAPTER 6 Compute
Image Name Description
Ubuntu 16.04 Canonical-Ubuntu- Ubuntu is a free, open-source Linux distribution

LTS 16.04-<date>- that is suitable for use in the cloud. For more
<number> information, see https://www.ubuntu.com.
Ubuntu 14.04 Canonical-Ubuntu- Ubuntu is a free, open-source Linux distribution

LTS 14.04-<date>- that is suitable for use in the cloud. For more
<number> information, see https://www.ubuntu.com.
Windows Server Windows-Server- Windows Server 2016 supports running

2016 2016-Datacenter- production Windows workloads on Oracle Cloud
Edition- Infrastructure.
Gen2.<date>-
Bare metal shapes are supported with this image.
<number>
Virtual machine (VM) and GPU shapes are not
supported with this image.
Windows Server Windows-Server- Windows Server 2012 R2 supports running

2012 R2 2012-R2-<edition>- production Windows workloads on Oracle Cloud
<gen>.<date>- Infrastructure.
<number>
Windows Server Windows-Server- Windows Server 2008 R2 Enterprise Edition

2008 R2 - 2008-R2-Enterprise- supports running production Windows workloads
Virtual Machine Edition-VM-<date>- on Oracle Cloud Infrastructure.
(VM) <number>
You also can create custom images of your boot disk OS and software configuration for
launching new instances.

CHAPTER 6 Compute
Warning
Windows 2008 Server R2 images do not support

restricting certain firewall rules for local principals,
such as "Administrators", so any authenticated user on
an instance can make outgoing connections to the iSCSI
network endpoints (169.254.0.2:3260,
169.254.2.0/24:3260) that serve the instance's boot and
block volumes.
All Oracle-provided images include rules that allow only "root" on Linux instances or
"Administrators" on Windows Server 2012 R2 and Windows Server 2016 instances to make
outgoing connections to the iSCSI network endpoints (169.254.0.2:3260,
169.254.2.0/24:3260) that serve the instance's boot and block volumes.
l Oracle recommends that you do not reconfigure the firewall on your instance to remove
these rules. Removing these rules allows non-root users or non-administrators to
access the instance’s boot disk volume.
l Oracle recommends that you do not create custom images without these rules unless
you understand the security risks.
OS Updates for Linux Images

Oracle Linux and CentOS images are preconfigured to let you install and update packages
from the repositories on the Oracle public Yum server. The repository configuration file is in
the /etc/yum.repos.d directory on your instance. You can install, update, and remove
packages by using the Yum utility.

CHAPTER 6 Compute
Note
OS Security Updates for Oracle Linux and CentOS images
Oracle Linux and CentOS images are updated regularly

with the necessary patches, but after you launch an
instance using these images, you are responsible for
applying the required OS security updates published
through the Oracle public Yum server. For more
information, see Installing and Using the Yum Security
Plugin.
The Ubuntu image is preconfigured with suitable repositories to allow you to install, update,
and remove packages.
Note
OS Security Updates for the Ubuntu image
After you launch an instance using the Ubuntu image,

you are responsible for applying the required OS
security updates using the sudo apt-get upgrade
command.
Linux Kernel Updates
Oracle Linux images on Oracle Cloud Infrastructure include Oracle Linux Premier Support at
no extra cost. This gives you all the services included with Premier Support including Oracle
Ksplice. Ksplice enables you to apply important security and other critical kernel updates
without a reboot. For more information, see About Oracle Ksplice and Ksplice Overview.
Ksplice is only available for Linux instances launched on or after February 15, 2017. For
instances launched prior to August 25, 2017, you must install it prior to running it. See
Installing and Running Oracle Ksplice for more information.

CHAPTER 6 Compute
Note
Ksplice Support
Oracle Ksplice is not supported for CentOS and Ubuntu

images, or on Linux images launched prior to February
15 2017.
Linux Image Details
Users
For instances created using Oracle Linux and CentOS images, the user name opc is created
automatically. The opc user has sudo privileges and is configured for remote access over the
SSH v2 protocol using RSA keys. The SSH public keys that you specify while creating
instances are added to the /home/opc/.ssh/authorized_keys file.
For instances created using the Ubuntu image, the user name ubuntu is created
automatically. The ubuntu user has sudo privileges and is configured for remote access over
the SSH v2 protocol using RSA keys. The SSH public keys that you specify while creating
instances are added to the /home/ubuntu/.ssh/authorized_keys file.
Note that root login is disabled.
Remote Access
Access to the instance is permitted only over the SSH v2 protocol. All other remote access
services are disabled.
Firewall Rules
Instances created using Oracle-provided images have a default set of firewall rules which
allow only SSH access. Instance owners can modify those rules as needed, but must not

CHAPTER 6 Compute
restrict link local traffic to address 169.254.0.2 in accordance with the warning at the top of
this page.
Be aware that Networking uses security lists to control packet-level traffic in and out of the
instance. When troubleshooting access to an instance, make sure both the security lists
associated with the instance's subnet and the instance's firewall rules are set correctly.
Cloud-init Compatibility
Instances created using Oracle-provided images are compatible with Cloud-init. When
launching an instance with the Core Services API, you can pass Cloud-init directives with the
metadata parameter. For more information, see LaunchInstance.
Windows OS Updates for Windows Images

Windows images include the Windows Update utility, which you can run to get the latest
Windows updates from Microsoft. You have to configure the security list on the subnet on
which the instance is running to allow instances to access Windows update servers.
Windows Image Details
Users
For instances created using Oracle-provided Windows images, the user name opc is created
automatically. When you launch an instance using the Windows image, Oracle Cloud
Infrastructure will generate an initial, one-time password that you can retrieve using the
console or API. This password must be changed after you initially log on.
Remote Access
Access to the instance is permitted only through a Remote Desktop connection.

CHAPTER 6 Compute
Firewall Rules
Instances created using the Windows image have a default set of firewall rules which allow
Remote Desktop protocol or RDP access on port 3389. Instance owners can modify these rules
as needed, but must not restrict link local traffic to 169.254.169.253 for the instance to
activate with Microsoft Key Management Service (KMS). This is how the instance stays active
and licensed.
Be aware that Networking uses security lists to control packet-level traffic in and out of the
instance. When troubleshooting access to an instance, make sure both the security lists
associated with the instance's subnet and the instance's firewall rules are set correctly.
Oracle-Provided Image Release Notes

The following tables list changes to images available in Oracle Cloud Infrastructure.
Oracle Linux
Oracle 6.x
ORACLE -LINUX-6.9-2018.02.21-1
Kernel Version: 4.1.12-112.14.15.el6uek.x86_64
Notes:
l Security configuration updated to remove access policies added to image released on

December 18, 2017.
Download: Image OCID List
ORACLE -LINUX-6.9-2018.02.21-0

CHAPTER 6 Compute
ORACLE -LINUX-6.9-2018.01.20-0
Notes:
l Includes fix for issue where virtual machines (VMs) may have network interface
cards (NICs) with the MTU set to 1500 instead of 9000.
ORACLE -LINUX-6.9-2018.01.11-0
Notes:
l Includes patches for the following ELSAs that address CVE-2017-5754, CVE-2017-
5715, and CVE-2017-5753:
o ELBA-2018-4009 - microcode_ctl bug fix update
o ELSA-2018-4006 - Unbreakable Enterprise kernel security update
See Doc 2348448.1 for more information on Oracle Linux patches for these issues.
l Includes a fix to address the issue described in ELBA-2018-4002 - dracut bug fix
update.
ORACLE -LINUX-6.9-2017.12.18-0
Notes:
l Includes fix for character encoding issue in /etc/fstab.

l This image supports X7 hosts.

CHAPTER 6 Compute
l This image implements stricter access policies, outlined below. See Security
Configurations Require Credential Rotation after 90 days for how to modify these
policies.
Access Policies
The security configuration for this image includes the following account access and
password requirements:
o Prevents log in with an empty password.
o The maximum password age is 90 days.
o The account expires after of 90 days of inactivity.
o Accounts are locked out for 30 minutes after five unsuccessful log in attempts.
o New passwords cannot be the same as the previous four passwords.
o Passwords must be at least eight characters, and contain at least one of each
of the following:
n lowercase character.
n uppercase character.
n special character.
o Passwords must not be the same as the user name or user ID.
o Passwords must not be dictionary words.
o Passwords must not be commonly used patterns or combinations such as
"welcome1", "guest2", "oracle1", "password5", "12345678", "qwerty".
ORACLE -LINUX-6.9-2017.11.15-0
Notes:

CHAPTER 6 Compute
ORACLE -LINUX-6.9-2017.10.25-0
Notes:
ORACLE -LINUX-6.9-2017.09.29-0
Notes:
l Includes a fix to address issue where updated hostname was not persisted across an
instance reboot.
l NetworkManager is disabled by default.
l Configured to use the OCI NTP server by default. See Configuring the Oracle Cloud
Infrastructure NTP Server for an Instance.
l Preview, developer, and developer_epel yum channels are enabled by default.
ORACLE -LINUX-6.9-2017.08.25-0
Notes:
l Includes a fix to address issue where 'hostname -f' was not working with hostname
resolution.

CHAPTER 6 Compute
ORACLE -LINUX-6.9-2017.07.17-0
Notes:
l Includes fixes to improve iSCSI attachment stability.

l Transparent hugepages are disabled by default.
l Regression: /etc/resolv.conf is not updated with the correct search domain and name
servers.
ORACLE -LINUX-6.9-2017.06.14-0
Notes:

l Uses biosdevname naming convention for all network devices.
servers.
ORACLE -LINUX-6.9-2017.05.25-0
Notes:

CHAPTER 6 Compute
ORACLE -LINUX-6.8-2017.03.02-0
ORACLE -LINUX-6.8-2017.01.09-0
Oracle 7.x
ORACLE -LINUX-7.4-GEN2-GPU-2018.02.21-1
CUDA Version: 9.1
cuDNN Version: 7.0.03
Notes:

December 18, 2017.
ORACLE -LINUX-7.4-2018.02.14-1
Kernel Version:4.1.12-112.14.15.el7uek.x86_64
Notes:

December 18, 2017.
CUDA Version: 9.1

CHAPTER 6 Compute
ORACLE -LINUX-7.4-2018.02.14-0
Kernel Version:4.1.12-112.14.15.el7uek.x86_64
CUDA Version: 8.0.61
ORACLE -LINUX-7.4-2018.01.20-0
Notes:
l Includes fix for issue where virtual machines (VMs) may have network interface
cards (NICs) with the MTU set to 1500 instead of 9000.
Notes:

CHAPTER 6 Compute
5715, and CVE-2017-5753:
l Includes a fix to address the issue described in ELBA-2018-4005 - rhn-client-tools
bug fix update.
l Includes a fix to address a GRUB boot order issue that could cause the image to boot
by default into an older version of the kernel after updates.
ORACLE -LINUX-7.4-2018.01.10-0
Notes:
5715, and CVE-2017-5753:
l Includes a fix to address the issue described in ELBA-2018-4005 - rhn-client-tools
bug fix update.
l Includes a fix to address a GRUB boot order issue that could cause the image to boot

CHAPTER 6 Compute
by default into an older version of the kernel after updates.

ORACLE -LINUX7.4-GEN2-GPU-2017.12.18-0
Notes:

l This image contains a regression that impacts the boot order when kernels are
updated. When doing kernel updates, you need to update GRUB to grub2-2.02-
0.65.0.4.el7_4.2 or higher. If you update the kernel without updating GRUB, GRUB
could cause an older version of the kernel to boot by default.
policies.
Access Policies

CHAPTER 6 Compute

of the following:
ORACLE -LINUX-7.4-2017.12.18-0
Notes:

l This image contains a regression that impacts the boot order when kernels are
updated. When doing kernel updates, you need to update GRUB to grub2-2.02-
0.65.0.4.el7_4.2 or higher. If you update the kernel without updating GRUB, GRUB
could cause an older version of the kernel to boot by default.
policies.

CHAPTER 6 Compute
Access Policies
of the following:
Notes:

CHAPTER 6 Compute
ORACLE -LINUX-7.4-2017.11.15-0
Notes:
Notes:
ORACLE -LINUX-7.4-2017.10.25-0
Kernel Version: 4.1.12-103.7.3
Notes:
ORACLE -LINUX-7.4-2017.09.29-0
Notes:

CHAPTER 6 Compute
l Includes a fix to address issue where updated hostname was not persisted across an
instance reboot.
l Preview, developer, and developer_epel yum channels are enabled by default.
ORACLE -LINUX-7.4-2017.08.25-1
Notes:
l Grub menu timeout is set to 5 seconds.

l Includes a fix to address incorrect entry in the /etc/hosts file that can occur after
creating a custom image from this image.
ORACLE -LINUX-7.4-2017.08.25-0
Notes:

resolution.
l Regression: Grub menu timeout is set to 0 seconds, causing the grub menu to not
display.

CHAPTER 6 Compute
ORACLE -LINUX-7.3-2017.07.17-1
Notes:
l Consistent image versions between the Phoenix (PHX) and Ashburn (IAD) regions.
ORACLE -LINUX-7.3-2017.07.17-0
Kernel Version:
l PHX: 4.1.12-94.3.6.el7uek.x86_64
l IAD: 4.1.12-94.3.8.el7uek.x86_64
PHX Notes:
resolution.
IAD Notes:

ORACLE -LINUX-7.3-2017.05.23-0
Notes:


CHAPTER 6 Compute
ORACLE -LINUX-7.3-2017.04.18-0
Notes:

l Includes performance improvements related to power management.
ORACLE -LINUX-7.3-2017.03.03-0
CentOS
CentOS 6.x
CENT OS-6.9-2018.02.16-0
Kernel Version: 2.6.32-696.20.1.el6.x86_64
Notes:
l Includes the Oracle Cloud Infrastructure NTP server configured and enabled.
CENT OS-6.9-2018.01.05-0
Notes:
l Includes CESA-2018:0008 Important CentOS 6 kernel Security Update.


CHAPTER 6 Compute
CENT OS-6.9-2017.09.14-0
Notes:
resolution.
CENT OS-6.9-2017.07.17-0
Notes:

servers.
CENT OS-6.9-2017.06.13-0
Notes:

l Uses biosdevname naming convention for all network devices.
servers.

CHAPTER 6 Compute
CENT OS-6.8-2017.02.03-0
CentOS 7.x
CENT OS-7-2018.02.21-0
Notes:
l Includes the Oracle Cloud Infrastructure NTP server configured and enabled.
CENT OS-7-2018.01.04-0
Notes:
l Includes CESA-2018:0007 Important CentOS 7 kernel Security Update.

CENT OS-7-2017.10.19-0
Notes:
l Includes updated version of Dnsmasq to address issues described in RHSA-

2017:2836 - Security Advisory.

CHAPTER 6 Compute
CENT OS-7-2017.09.14-0
Notes:
resolution.
CENT OS-7-2017.07.17-0
Notes:

CENT OS-7-2017.04.18-0
Notes:
CENT OS-7-2017.02.02-2

CHAPTER 6 Compute
Ubuntu
Ubuntu 14.04
CANONICAL-UBUNTU-14.04-2018.01.11-0
Kernel Version: 4.4.0-98-generic
Notes:
l Includes kernel fixes described in Ubuntu Security Notice USN-3522-2.

Notes:

CHAPTER 6 Compute
Ubuntu 16.04
CANONICAL-UBUNTU-16.04-GEN2-GPU-2018.01.11-0
CUDA Version: 9.0
Notes:

Notes:

CANONICAL-UBUNTU-16.04-GEN2-GPU-2017.11.21-0
Notes:

CHAPTER 6 Compute
l Includes fixes for issues described in CVE-2017-14177 and CVE-2017-14180.

Notes:
l Includes fixes for issues described in CVE-2017-14177 and CVE-2017-14180.

CANONICAL-UBUNTU-GEN2-GPU-16.04-2017.10.25-0
Notes:
Notes:

CHAPTER 6 Compute
Windows
Windows Server 2008 R2
W INDOWS-S ERVER -2008-R2-ENTERPRISE -EDITION-VM-GEN2-2018.03.15-0
Notes:
W INDOWS-S ERVER -2008-R2-ENTERPRISE -EDITION-VM-2018.02.09-0
Notes:
l Includes Windows Server 2008 R2 Service Pack 1 (KB976932).
W INDOWS-S ERVER -2008-R2-S TANDARD-EDITION-VM-2018.01.11-0
Notes:

CHAPTER 6 Compute
l Includes security fixes described in January 3, 2018—KB4056897 (Security-only

update).
l Includes Windows Server 2008 R2 Service Pack 1 (KB976932).
l Default drive size has been updated from 46 GB to 256 GB.
Windows Server 2012 R2 VM
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-VM-GEN2-2018.04.06-0
Notes:

CHAPTER 6 Compute

update).
Notes:

update).
Notes:
l This image supports the VM.DenseIO1.16 shape.

l Includes updated NVMe drivers.
Notes:

CHAPTER 6 Compute
Windows Server 2012 R2 BM
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-GPU-2018.01.14-0
Notes:

update).
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-2018.01.13-0
Notes:

update).
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-DENSE IO-2018.01.14-0
Notes:

update).

CHAPTER 6 Compute
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-GPU-2017.11.29-0
Notes:
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-2017.10.31-0
Notes:
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-GEN2-DENSE IO-2017.10.31-0
Notes:
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-2017.07.25-0
W INDOWS-S ERVER -2012-R2-S TANDARD-EDITION-BM-2017.04.13-0
Windows Server 2016 VM
W INDOWS-S ERVER -2016-S TANDARD-EDITION-VM-GEN2-2018.04.09-0
Notes:

CHAPTER 6 Compute
l First image release for Windows Server 2016 Standard, includes all updates up to
February 2018.
Windows Server 2016 BM
W INDOWS-S ERVER -2016-DATACENTER -EDITION-BM-GEN2-2018.02.28-0
Notes:
l First image release for Windows Server 2016 Datacenter, includes all updates up to
February 2018.
W INDOWS-S ERVER -2016-DATACENTER -EDITION-BM-GEN2-DENSE IO-2018.02.28-0
Notes:
l First image release for Windows Server 2016 Datacenter, includes all updates up to
February 2018.
Using NVIDIA GPU Cloud with Oracle Cloud Infrastructure
NVIDIA GPU Cloud (NGC) is a GPU-accelerated cloud platform optimized for deep learning and
scientific computing. This topic provides an overview of how to use NGC with Oracle Cloud
Infrastructure.
NVIDIA makes available on Oracle Cloud Infrastructure a customized Compute image

optimized for the NVIDIA® Tesla Volta™ and Pascal™ GPUs . Running NGC containers on this
instance provides optimum performance for deep learning jobs.
For those familiar with Oracle Cloud Infrastructure, to use NGC, you need to log into the
Console, configure the settings as needed, and then create an instance based on the NGC
image by specifying the image OCID. After launching the instance, you can SSH into the

CHAPTER 6 Compute
instance and start running deep learning jobs using framework containers from the NGC
container registry.
PREREQUISITES
l An Oracle Cloud Infrastructure tenancy. For more information, see Signing Up for
l A cloud network to launch the instance into. For information about setting up cloud
networks, see Using the Console in VCNs and Subnets.
l A key pair, to use for connecting to the instance via SSH. For information about
generating a key pair, see Managing Key Pairs on Linux Instances.
l Security group and policy configured for the File Storage service. For more information,
see Managing Groups, Getting Started with Policies, and Details for the File Storage
Service.
l An NGC API key for authenticating with the NGC service.
To generate your NGC API key

1. Log into the NGC website.
2. On the NGC Registry page, click Get API Key.
3. Click Generate API Key and then click Confirm to generate the key. If you have an
existing API key it will become invalid once you generate a new key.
LAUNCHING AN INSTANCE BASED ON THE NGC IMAGE
USING THE CONSOLE
1. Open the Console, see Signing In to the Console for steps on how to do this.
2. Click Compute, choose a compartment you have permission to work in, and then click
Create Instance.
3. In the Create Instance dialog box, specify the instance name, and select the
availability domain for the instance.

CHAPTER 6 Compute
4. Select Image OCID for Boot Volume.

5. Specify the image OCID applicable to your region as the Image OCID.
Region Image OCID
us- ocid1.image.oc1.iad.aaaaaaaaikn6ub6heefqxbe5fkiv4otbfe6ivza6y7di5khn
ashbur kxkyvf2bkdta
n-1
eu- ocid1.image.oc1.eu-frankfurt-
frankfu 1.aaaaaaaayqvmnezqsrzwwdimzmvmt3w3ncqri4gce7qazfaapwpa53c3d7v
rt-1
6. Select Bare Metal Machine for Shape Type.

7. Select the shape you want to use for Shape.
8. For SSH Keys, click Choose SSH Key File, navigate to the location where you saved
the public key portion (.pub) of the SSH key file you created, select the file and click
Open.
9. Select a virtual cloud network, and then click Create Instance.
You should now see the NGC instance with the status of Provisioning. Once the status has
changed to Running, you can connect to the instance. For general information about
launching Compute instances, see Launching an Instance.
See the following topics for accessing and working with the instance:
l Connecting to an Instance
l Stopping and Starting an Instance
l Terminating an Instance
When you connect to the instance using SSH you will be prompted for the NGC API key. If you
supply the API key at the prompt, the instance will automatically log you into the NGC
container registry so that you can run containers from the registry. You can choose not to
supply the API key at the prompt and still log in to the instance. You can then log in later to the
NGC container registry, see Logging in to the NGC Container Registry for more information.

CHAPTER 6 Compute
USING THE CLI
Oracle Cloud Infrastructure provides a Command Line Interface (CLI) you can use to complete
tasks. For more information, see Installing the CLI and Configuring the CLI. Use the launch
command to create an instance, specifying image for sourceType and the applicable image
OCID from the table below for imageId in InstanceSourceDetails for
LaunchInstanceDetails.
Region Image OCID
us- ocid1.image.oc1.iad.aaaaaaaaikn6ub6heefqxbe5fkiv4otbfe6ivza6y7di5khnkxkyv
ashburn- f2bkdta
1
eu- FRA - ocid1.image.oc1.eu-frankfurt-

frankfur 1.aaaaaaaayqvmnezqsrzwwdimzmvmt3w3ncqri4gce7qazfaapwpa53c3d7v
t-1
To start and stop the instance with the CLI, use the action command. Use the terminate
command to terminate the instance.
USING THE FILE S TORAGE S ERVICE FOR PERSISTENT DATA S TORAGE
You can use the Overview of File Storage for data storage when working with NGC. See the
following tasks for creating and working with the File Storage service:
l Creating File Systems

l Using the Console
l Using the Console
l Managing File Systems
l Using the Command Line Interface (CLI)
USING THE BLOCK VOLUME S ERVICE FOR PERSISTENT DATA S TORAGE
You can use the Block Volume service for data storage when working with NGC. For more
information, see Overview of Block Volume. See the following tasks for creating and working

CHAPTER 6 Compute
with the Block Volume service:
l Creating a Volume
l Attaching a Volume
l Connecting to a Volume
You can also use the CLI to manage block volumes, see the volume commands.
EXAMPLES OF RUNNING CONTAINERS
You first need to log into the NGC container registry. You can skip this section if you provided
your API key when logging into the instance via SSH. If you did not provide your API key when
connecting to your instance, then you must perform this step.
To log into the NGC container registry

1. Run the following Docker command:
docker login nvcr.io
2. When prompted for a username, enter $oauthtoken.

3. When prompted for a password enter your NGC API key.
At this point you can run Docker commands and access the NGC container registry from the
instance.
Example: MNIST Training Run Using PyTorch Container

This sample demonstrates running the MNIST example under PyTorch. This example
downloads the MNIST dataset from the web.
1. Pull and run the PyTorch container with the following Docker commands:
docker pull nvcr.io/nvidia/pytorch:17.10
nvidia-docker run --rm -it nvcr.io/nvidia/pytorch:17.10
2. Run the MNIST example with the following commands:

CHAPTER 6 Compute
cd /opt/pytorch/examples/mnist
python main.py
Example: MNIST Training Run Using TensorFlow Container

This sample demonstrates running the MNIST example under TensorFlow. This example
downloads the MNIST dataset from the web.
1. Pull and run the TensorFlow container with the following Docker commands:
nvcr.io/nvidia/tensorflow:17.10
nvidia-docker run --rm -it nvcr.io/nvidia/tensorflow:17.10
2. Run the MNIST_with_summaries example with the following commands:

cd /opt/tensorflow/tensorflow/examples/tutorials/mnist
python mnist_with_summaries.py
Installing and Running Oracle Ksplice

Oracle Ksplice enables you to apply important security and other critical kernel updates
without a reboot. For more information, see About Oracle Ksplice and Ksplice Overview.
This topic describes how to install and configure Ksplice. Ksplice is only available for Oracle
Linux instances launched on or after February 15, 2017. It is installed on instances launched
on or after August 25, 2017, so you just need to run it on these instances to install the
available Ksplice patches. For instances launched prior to August 25, 2017, you must install it
prior to running it.
Installing Ksplice on instances launched prior to August 25 2017

To install Ksplice you need to connect to your Linux instance by using a Secure Shell (SSH).
See Connecting to an Instance for more information.
1. Use the following SSH command to access the instance.

ssh –l opc@<public-ip-address>

CHAPTER 6 Compute
<public-ip-address> is your instance IP address that you retrieved from the Console,
see Getting the Instance Public IP Address.
2. Run the following SSH commands to sudo to the root:
sudo bash
3. Download the Ksplice installation script with the following SSH command:
wget -N https://www.ksplice.com/uptrack/install-uptrack-oc
4. Once the script is downloaded, use the following SSH command to install Ksplice:
sh install-uptrack-oc
Running Ksplice
To run Ksplice you need to connect to your Linux instance by using a Secure Shell (SSH). See
Connecting to an Instance for more information.

ssh –l opc <public-ip-address>
<public-ip-address> is your instance IP address that you retrieved from the Console,
see Getting the Instance Public IP Address.
2. Run the following SSH commands to sudo to the root:
sudo bash
cd
3. To install available Ksplice patches, run the following SSH command:

uptrack-upgrade
Automatic Updates
You can configure automatic updates by setting the value of autoinstall to yes in
/etc/uptrack/uptrack.conf.

CHAPTER 6 Compute
Note
OS Security Updates for Oracle Linux images
Oracle Linux images are updated regularly with the

necessary patches, but after you launch an instance
using these images, you are responsible for applying
the required OS security updates published through the
Oracle public Yum server. For more information, see
Installing and Using the Yum Security Plugin.
Managing Custom Images

Oracle Cloud Infrastructure uses images to launch instances. You specify an image to use
when you launch an instance.
You can create a custom image of a Bare Metal instance's boot disk and use it to launch other
instances. Instances you launch from your image include the customizations, configuration,
and software installed when you created the image.
For details on Windows images, see Creating Windows Custom Images.
Custom images do not include the data from any attached block volumes. For information
about backing up volumes, see Backing Up a Volume.

CHAPTER 6 Compute
Tip
Oracle Cloud Infrastructure runs on Oracle's high quality

Sun servers. However, any hardware can experience a
failure. Follow industry-wide hardware failure best
practices to ensure the resilience of your solution. Some
best practices include:
l Design your system with redundant compute

nodes in different availability domains to support
fail-over capability.
l Create a custom image of your system drive each
time you change the image.
l Back up your data drives, or sync to spare drives,
regularly.
If you experience a hardware failure and have followed

these practices, you can terminate the failed instance,
launch your custom image to create a new instance, and
then apply the backup data.
Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to create and
manage images. If the specified group doesn't need to launch instances or attach volumes,

CHAPTER 6 Compute
you could simplify that policy to include only manage instance-family, and remove the
statements involving volume-family and virtual-network-family.
Tip
When users create a custom image from an instance or

launch an instance from a custom image, the instance
and image don't have to be in the same compartment.
However, users must have access to both
compartments.
Limitations and Considerations

l The following IP addresses are reserved for Oracle Cloud Infrastructure use:
169.254.0.2, 169.254.2.2-169.254.2.254
169.254.0.3
169.254.169.254
For DNS (port 53) and Metadata (port 80) services. See Getting Instance Metadata for
more information.
169.254.169.253

CHAPTER 6 Compute

l When you create an image of a running instance, the instance shuts down and remains
unavailable for several minutes. When the process completes, the instance restarts.
l You cannot create a new custom image if that instance is already engaged in the image
creation process. When you start to create a custom image, the system implements a
20 minute timeout, during which you cannot create another image of the same instance.
You can, however, create images of multiple instances at the same time.
l Custom images are available to all users authorized for the compartment in which the
image was created.
l A custom image cannot exceed 50 GB.
l You can create a maximum of 25 custom images per region per root compartment.
l You cannot create an image of an Oracle Database instance.
l Windows custom images cannot be exported or downloaded.
l If you use a custom image and update the OS kernel on your instance, you must also
upload the update to the network drive. See OS Kernel Updates for more information.
See Bring Your Own Image for information on how to deploy any version of any operating
system that is supported by the Oracle Cloud Infrastructure hardware.
X5 and X7 Compatibility for Custom Images

Oracle X5 and X7 servers have different host hardware. As a result, using an X5 image on an
X7 bare metal or virtual machine (VM) instance may not work without additional
modifications. Oracle Cloud Infrastructure recommends for X7 hosts that you use the Oracle-
provided images for X7. See Oracle-Provided Image Release Notes for more information
about which images support X7. These images have been explicitly created and tested with
the new hardware.
If you do attempt to use an existing X5 image on X7 hardware, note that Ubuntu 14.04 and all
Windows and CentOS versions are not cross-compatible.

CHAPTER 6 Compute
Oracle Linux and Ubuntu 16.04 are cross-compatible, however you need to update the kernel
to the most recent version to install the latest device drivers. To do so, run the following
commands from a terminal session:
l Oracle Linux
yum update
l Ubuntu 16.04
apt-get update
apt-get dist-upgrade
The primary device drivers that are different between X5 and X7 hosts are:
l Network device drivers

l NVMe drive device drivers
l GPU device drivers
Additional updates may be required depending on how you have customized the image.
Using the Console

To access the Console, you must use a supported browser.
To create a custom image

1. In the Console, click Compute, and then choose your Compartment.
2. Click Instances, if necessary, and find the instance you want to use as the basis for an
image.
3. Click the Actions icon ( ), and then click Create Custom Image.
4. Enter a name for the image, and then click Create Custom Image. You can use the
API to change the name later, if needed. You cannot use an Oracle-provided image
name as a custom image name.

CHAPTER 6 Compute
Note
Limits
If you see a message indicating you are at the limit for

custom images, you must delete at least one image
before you can create another or request a limit
increase.
To launch an instance from a custom image

2. Click Custom Images and find the custom image you want to use.
3. Click the Actions icon ( ), and then click Launch Instance.
4. Provide additional launch options as described in Launching an Instance.
To edit custom image details

2. Click Custom Images and then click the custom image you want to edit.
3. Click Edit
4. From the Edit Image Details dialog box, you can change the name, or add and
remove compatible shapes for the custom image.
5. After you have finished editing the details, click Save to save your changes and close
the dialog box.

CHAPTER 6 Compute
To manage tags for a custom image

2. Click Custom Images and then click the custom image you want to manage the tags
for.
3. Click the Tags tab to view or edit the existing tags. Or click Apply tag(s) to add new
ones.
For more information, see Resource Tags.
To delete a custom image

2. Click Custom Images and find the custom image you want to delete.
3. Click the Actions icon ( ), and then click Delete.
4. Confirm when prompted.
To review existing custom images using the Console, click Compute, choose your
Compartment, and then click Custom Images.
Using the API

Use the following operations to manage custom images:
l DeleteImage
l GetImage
l ListImages
l CreateImage
l UpdateImage

CHAPTER 6 Compute
l AddImageShapeCompatibilityEntry
l RemoveImageShapeCompatibilityEntry
Creating Windows Custom Images

You can create a Windows custom image of a bare metal or VM instance's boot disk and use it
to launch other instances. Instances you launch from your image include the customizations,
configuration, and software installed when you created the image. For information about
using the Console to manage custom images, see Managing Custom Images.
Windows supports two kinds of images: generalized and specialized. Generalized images are
images that have been cleaned of instance-specific information. Specialized images are point-
in-time snapshots of the boot disk of a running instance, and are useful for creating backups
of an instance. Oracle Cloud Infrastructure supports bare metal and VM instances launched
from both generalized and specialized custom Windows images.
Generalized images
A generalized image has a generalized OS disk, cleaned of computer-specific information. The

images are generalized using Sysprep. Generalized images can be useful in scenarios such as
quickly scaling an environment. Generalized images can be configured to preserve the
existing opc user's account, including the password, at the time the image is created, or
configured to recreate the opc user account, including generating a new, random password
that you retrieve using the API.
Specialized images
A specialized image has an OS disk that is already fully installed, and is essentially a copy of
the original bare metal or VM instance. Specialized images are intended to be used for
backups so that you can recover from a failure. Specialized images are useful when you are
testing a task and may need to roll back to known good configuration. Specialized images are
not recommended for cloning multiple identical Bare Metal instances or VMs in the same
network because of issues with multiple computers having the same computer name and ID.
When creating a specialized image, you must remember the opc user's password; a new
password is not generated when the instance launches, and it cannot be retrieved from the
console or API.

CHAPTER 6 Compute
Creating a Generalized Image
Warning
Creating a generalized image from an instance will

render the instance non-functional, so you should first
create a custom image from the instance, and then
launch a new instance from the custom image. Steps 1 -
2 describe how to do this. This is the instance that you'll
generalize. Alternatively, you can make a backup image
of the instance that you can use to launch a replacement
instance if needed.
1. Create the new image using To create a custom image.

2. Launch an instance from the new image using To launch an instance from a custom
image.
3. Connect to the instance using a Remote Desktop client.
4. Go to Windows Generalized Image Support Files and download to the instance the file
matching the Windows version for the instance.
For X7 instances:
l Windows Server 2016 Datacenter and Windows Server 2012 Standard
R2: Oracle Cloud Infrastructure - Windows Server Generalize-2018-02-28-
Gen2.SED.EXE
For X5 instances:
l Windows Server 2012 Standard R2: Oracle Cloud Infrastrucure - Windows
2012 R2 Generalize-2017-04-12.SED.EXE
l Windows Server 2008 R2: Oracle Cloud Infrastructure - Windows 2008 R2
Generalize-2017-08-03.SED.EXE
5. Right-click the file, and then click Run as administrator.

CHAPTER 6 Compute
6. Extract the files to C:\Windows\Panther. The following files are extracted into the
Panther folder for all Windows Server versions:
l Generalize.cmd
l Specialize.cmd
l unattend.xml
l Post-Generalize.ps1
For Windows Server 2008, the following file is also extracted into the Panther folder:
l Windows2008-SnapshotUtilities.ps1
7. Optional: If you want to preserve the opc user account, edit C:\Program
Files\oci\imageType.json and change the imageTypesetting to custom. A new
password is not created and the password is not retrievable from the console or API.
If you want to configure the generalized image to recreate the opc user account when a
new instance is launched from the image, leave the imageType setting defaulted to
general. The new account's password can be retrieved through the API using
GetWindowsInstanceInitialCredentials.
8. Right-click Generalize.cmd, and then click Run as administrator. Keep in mind the
following outcomes of running this command:
l Your connection to the Remote Desktop client may immediately be turned off and
you will be logged out of the instance. If this does not occur, you should log out of
the instance yourself.
l Because sysprep generalize turns off Remote Desktop, you won't be able to log
in to the instance again.
l Creating a generalized image essentially destroys the instance's functionality.
You should wait for a few minutes before proceeding to step 9 to ensure the
generalization process has completed.
9. Create the new image using To create a custom image.
10. After you create an image from an instance that has been generalized, Oracle
recommends that you terminate that instance. Although it may appear to be running, it
won't be fully operable.

CHAPTER 6 Compute
Creating a Specialized Image
Important
When creating a specialized image, you must remember

the opc user's password. It cannot be retrieved from
the Console or API.
You create a specialized image the same way you create other custom images. For step-by-
step instructions, see Managing Custom Images.
Image Import/Export
Oracle Cloud Infrastructure Compute enables you to share custom images across tenancies
and regions using image import/export. You can only import custom images that have been
exported from Oracle Cloud Infrastructure, so you first need to export an image before you
can import it.
The following Oracle Cloud Infrastructure operating systems support image import/export:
l Oracle Linux 6, Oracle Linux 7

l CentOS 6, CentOS 7
l Ubuntu 16.04, Ubuntu 14.04
For more information about these images, see Oracle-Provided Images.

CHAPTER 6 Compute
Note
Exporting Windows Images
Image export is not supported for Oracle-provided

Windows images. You can only export Windows images
that have been created using the BYOI scenario
import/export process.
Bring Your Own Image Scenarios
You can also use image import/export to share custom images from Bring Your Own Image
scenarios across tenancies and regions, so you don't need to re-create the image manually in
each region. You need to go through the steps required to manually create the image in one of
the regions, but once this is done, you can export the image, making it available for import in
additional tenants and regions. The exported image format is QCOW2.
Important
When importing custom Windows images, you need to

make sure the version you select matches up with the
Windows image that you imported. Failure to provide
the correct version and SKU information could be a
violation of your Microsoft Licensing Agreement. See
Bring Your Own Custom Image for Emulation Mode
Virtual Machines for the Windows operating systems
supported for custom image import.
Object Storage Service URLs

When you import or export custom images using the Console, you may need to specify the
Object Storage URL pointing to the location to import the image from or export the image to.

CHAPTER 6 Compute
Object Storage URLs are structured as follows:

https://<host_name>/n/<namespace_name>/b/<bucket_name>/o/<object_name>
For example:
https://objectstorage.us-phoenix-1.oraclecloud.com/n/MyNamespace/b/MyBucket/o/MyCustomImage.qcow2
Pre-Authenticated Requests
When using import/export across tenants and regions you need to use . See for instructions on
creating a pre-authenticated request. When you go through these instructions, after you click
Create Pre-Authenticated Request, the Pre-Authenticated Request Details dialog
opens. You need to make a copy of the pre-authenticated request URL displayed here, as this
is the only time this will be displayed. This is the Object Storage URL you specify for
import/export.
Note
Pre-authenticated requests for a bucket
With image export, if you create the pre-authenticated

request for a bucket, you will need to append the object
name to the generated URL, for example:
/o/MyCustomImage.qcow2
Exporting an Image
You can use the console or API to export images, and the exported images are stored in the
Oracle Cloud Infrastructure Object Storage service. To perform an image export, you need
write access to the Object Storage bucket for the image. For more information, see Overview
of Object Storage and Let users write objects to Object Storage buckets.

CHAPTER 6 Compute
To export an image using the Console

2. Click Custom Images and find the custom image you want to export.
3. Click the Actions icon ( ), and then click Export Custom Image.
4. In the Export Image dialog box, you specify the Object Storage location to export the
image to. You have two options here: You can select a compartment and bucket, and
then enter a name for the exported image, or you can enter the Object Storage URL.
5. Click Export Image.
Once you click Export Image, the image status changes to EXPORTING. You can still launch
instances while the image is exporting, but you can't delete the image until the export has
finished. Once the export is complete, the image status changes to AVAILABLE. If the image
status changes to AVAILABLE, but you don't see the exported image in the Object Storage
location you specified, the export failed, and you will need to go through the steps again to
export the image.
Importing an Image
You can use the console or API to import exported images from Object Storage. To import an
image, you need read access to the Object Storage object containing the image. For more
information, see Let users download objects from Object Storage buckets.
To import an image using the Console

2. Click Custom Images and then click Import Exported Image.
3. Select the compartment name you want to import the image to.
4. Enter a name for the image.
5. Specify the Object Storage URL where the image is stored. When importing across
regions or tenancies, you need to specify a pre-authenticated request URL.

CHAPTER 6 Compute
7. Click Import Exported Image.
Once you click Import Exported Image, you'll see the imported image in the Custom
Images list for the compartment, with a status of IMPORTING. Once the import completes
successfully, the status will change to AVAILABLE. If the status does not change, or no entry
appears in the Custom Images list, the import failed. If the import failed, make sure you
have read access to the Object Storage object, and that the object contains a supported
image.
Editing Image Details

You can edit the details of custom images, such as the image name and compatible shapes for
the image. For more information, see To edit custom image details in Managing Custom
Images.
Managing Tags for an Image

You can apply tags to your resources, such images, to help you organize them according to
your business needs. You can apply tags at the time you import an image, or you can update
the image later with the desired tags.
To manage tags for an image

In the Console, click Compute, and then click Images.
1.
2. Click the image you're interested in.

CHAPTER 6 Compute
ones.
Using the API

Use the following API operations for custom image import/export.
l ExportImage: Exports a custom image to Object Storage.

l CreateImage: To import an exported image, specify ImageSourceDetails in the request
body.
l AddImageShapeCompatibilityEntry: Adds a shape to the compatible shapes list for the
image.
l RemoveImageShapeCompatibilityEntry: Removes a shape from the compatible shapes
list for the image.
X5 and X7 Compatibility for Image Import/Export

Oracle X5 and X7 servers have different host hardware. As a result, using an X5 image on an
X7 bare metal or virtual machine (VM) instance may not work without additional
modifications. Oracle Cloud Infrastructure recommends for X7 hosts that you use the Oracle-
provided images for X7. See Oracle-Provided Image Release Notes for more information
about which images support X7. These images have been explicitly created and tested with
the new hardware.
If you do attempt to use an existing X5 image on X7 hardware, note that Ubuntu 14.04 and all
Windows and CentOS versions are not cross-compatible.
Oracle Linux and Ubuntu 16.04 are cross-compatible, however you need to update the kernel
to the most recent version to install the latest device drivers. To do so, run the following
commands from a terminal session:

CHAPTER 6 Compute
l Oracle Linux
yum update
l Ubuntu 16.04
apt-get update
apt-get dist-upgrade
The primary device drivers that are different between X5 and X7 hosts are:
l Network device drivers

l NVMe drive device drivers
l GPU device drivers
Additional updates may be required depending on how you have customized the image.
Bring Your Own Image

The Oracle Cloud Infrastructure enables you to bring versions of operating system (OS) to the
cloud as long as the underlying hardware supports it. The services do not depend on the OS
you run. The Bring Your Own Image (BYOI) feature:
l Enables lift-and-shift cloud migration projects.

l Supports both older and cutting edge operating systems.
l Encourages experimentation.
l Increases infrastructure flexibility.
Note
Licensing Requirements
You must comply with all licensing requirements when

you upload and start instances based on OS images you
supply.

CHAPTER 6 Compute
Bring Your Own Image Scenarios

The Bring Your Own Image scenarios supported in Oracle Cloud Infrastructure include
scenarios based on new operating system images and scenarios based on existing operating
system images.
Building new operating system images
l Oracle-provided images: Oracle provides several pre-built images for Oracle Linux,
Microsoft Windows, Ubuntu and CentOS. For the complete list of images, see Oracle-
Provided Images.
l RHEL 7.4 images: You can build new RHEL 7.4 images for bare metal and VM
instances using a terraform template, see Terraform Provider for RHEL 7.4.
Bringing existing operating system images
l Importing custom images for emulation mode: You can import existing operating
system images using either the VMDK or QCOW2 formats, to run in emulation mode
VMs. For more information, see Bring Your Own Custom Image for Emulation Mode
Virtual Machines.
l Bring Your Own KVM: You can bring your own operating system images or older
operating systems such as Ubuntu 6.x, RHEL 3.x, CentOS 5.4 using KVM on bare metal
instances. For more information, see Installing and Configuring KVM on Bare Metal
Instances with Multi-VNIC.
l Bring Your Own OVM: You can bring your Oracle VM workload to Oracle Cloud
Infrastructure, for more information, see Installing and Configuring Oracle VM on
l Bring Your Own Hyper-V: You can bring your own operating system images or older
operating systems such as Windows Server 2003, Windows Server 2008, as well as
older Linux -based operating systems using Hyper-V on bare metal instances. For a full
list of supported Hyper-V guests, see Supported Windows guest operating systems for
Hyper-V on Windows Server 2016 and Supported Linux and FreeBSD virtual machines
for Hyper-V on Windows. See Deploying Hyper-V with Routing for more information.

CHAPTER 6 Compute
Bring Your Own Custom Image for Emulation Mode Virtual Machines
The Oracle Cloud Infrastructure Compute service enables you to import your older operating
systems to Oracle Cloud Infrastructure. You can import a wide range of new and legacy
production operating systems, using the QCOW2 or VMDK formats, and then run them on
Compute virtual machines (VMs) using emulated hardware. The following table lists the
operating systems that are supported for emulation mode VMs:
Image Name Supported Versions
RHEL 4.5, 5.11, 6.9, 7.4
CentOS 4.0, 4.8, 5.11, 6.9, 7.x
Oracle Linux 4.5, 4.8, 5.11, 6.9, 7.4
Ubuntu 12.04, 14.04, 16.04
Windows Server 2008 R2 Standard, Enterprise, Datacenter
2012 Standard, Datacenter
2012 R2 Standard, Datacenter
2016 Standard, Datacenter
Custom Image Requirements
Linux-based and Windows-based custom images imported for emulation mode VMs must meet
the following requirements:
l The image must be set up for BIOS boot.

l The maximum image size is 300 GB.
l Only one disk is supported, and it must be the boot drive with a valid MBR and boot
loader. You can migrate additional data volumes after the image's boot volume has
been imported.

CHAPTER 6 Compute
l The boot process must not require additional data volumes to be present for a
successful boot.
l The disk image cannot be encrypted.
l The disk image must be a VMDK or QCOW2 file. VMDK files must be either the "single
growable" (monolithicSparse) type or the "stream optimized" (streamOptimized) type,
both of which will consist of a single VMDK file. All other VMDK formats such as those
that use multiple files, split volumes, or contain snapshots, are not supported.
l Existing network interfaces will not be recreated. Instead, a single network interface
will be created after the import process is complete. You should use DHCP on this
interface to discover the network settings.
REQUIREMENTS S PECIFIC TO LINUX-BASED CUSTOM I MAGES
The following requirements are only applicable to Linux-based custom images:
l The boot loader should use LVM or UUID to locate the boot volume.
l The network configuration should not hardcode the MAC address for the network
interface.
For Linux-based instances, we recommend that you enable certificate-based SSH, however
this is optional. If you want your image to automatically use ssh keys supplied from the User
Data field when you launch an instance, you can install Cloud-Init when preparing the image.
See Launching an Instance for more information about the User Data field.
Custom Image Import Process
The following is a high-level outline of the steps required to import custom images for
emulation mode VMs.
1. Prepare the image for import. This includes enabling serial console access for all Linux-
based custom images and configuring a network interface without a static MAC address
and to support DHCP. For more information, see Preparing a Custom Linux Image for
Emulation Mode and Preparing a Custom Windows Image for Emulation Mode.
2. Export the image as VMDK or QCOW2 format using existing virtualization tools. See the

CHAPTER 6 Compute
tools documentation for your virtualization environment.

3. Upload the image to Oracle Cloud Infrastructure Object Storage. See Managing Objects
and Overview of Object Storage for more information.
4. Import the image. See Importing Custom Images for Emulation Mode.
Preparing a Custom Linux Image for Emulation Mode
Oracle Cloud Infrastructure enables you to import a custom Linux image and then use the
custom image to launch virtual machine (VM) instances in emulation mode. Before you can
import the custom image, you need to prepare the custom image to ensure that instances
launched from the custom image can boot correctly and that network connections will work.
This topic describes the steps to prepare custom Linux images for import.
ENABLING S ERIAL CONSOLE ACCESS
The most important step to prepare your custom image for import is to configure it to support
connections using the serial console feature in the Compute service. For more information
about this feature, see Instance Console Connections for troubleshooting steps if your image
has network connectivity issues once launched.
The serial console connection in Oracle Cloud Infrastructure uses the first serial port, ttyS0,
on the VM. The boot loader and the operating system should be configured to use ttyS0 as a
console terminal for both input and output.
CONFIGURING THE BOOT LOADER
The steps to configure the boot loader to use ttyS0 as a console terminal for both input and
output depend on the GRUB version. Run the following command on the operating systemto
determine the GRUB version:
grub install --version
If the version number returned is 2.* use the steps for GRUB 2. For earlier versions, use the
steps for GRUB.

CHAPTER 6 Compute
To configure GRUB
1. Run the following command to modify the GRUB configuration file:
sudo vi /boot/grub/grub.conf
2. Add following after the line containing timeout:

serial --unit=0 --speed=115200
terminal --timeout=5 serial console
3. Append the following to each kernel line:

console=tty1 console=ttyS0,115200
To configure GRUB2
1. Run the following command to modify the GRUB configuration file:
sudo vi /etc/default/grub
2. Confirm that the configuration file contains the following:

GRUB_SERIAL_COMMAND="serial --unit=0 --speed=115200"
GRUB_TERMINAL="serial console"
3. Append to the end of the line GRUB_CMDLINE_LINUX:

console=tty1 console=ttyS0,115200
If GRUB_CMDLINE_LINUX does not exist, create this line, using GRUB_CMDLINE_OUTPUT as

a template.
4. Regenerate the GRUB2 configuration using the following command:
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
If you have a beta version of GRUB 2, use this command instead:

sudo grub-mkconfig -o /boot/grub/grub.cfg

CHAPTER 6 Compute
CONFIGURING THE OPERATING SYSTEM
The operating system may already be configured to use ttyS0 as a console terminal for both
input and output. To verify, run the following command:
sudo vi /etc/securetty
Check the file for ttyS0. If you don't see it, append ttyS0 to the end of the file.
VALIDATING S ERIAL CONSOLE ACCESS
After completing the steps to enable serial console access to the image, you should validate
that serial console access is working by testing the image with serial console in your
virtualization environment. Consult the documentation for your virtualization environment on
how to do this. Verify that the boot output is showing up in the serial console output and that
there is interactive input available once the image has booted.
TROUBLESHOOTING THE SERIAL CONSOLE
If no output is displayed on the serial console, verify in the configuration for your
virtualization environment that the serial console device is attached to the first serial port.
If the serial console is displaying output, but there is no interactive input available, check that
there is a terminal process listening on the ttyS0 port. To do this, run the following command:
ps aux | grep ttyS0
This command should output a terminal process that is listening on the ttyS0 port. For
example, if your system is using getty, you will see the following output:
/sbin/getty ttyS0
If you don't see this output, it is likely that a login process is not configured for the serial
console connection. To resolve this, enable the init settings, so that a terminal process is
listening on the ttyS0 at startup.
For example, if your system is using getty, add the following command to the the init settings
to run on system startup:
getty -L 9600 ttyS0 vt102

CHAPTER 6 Compute
The steps to do this will vary depending on the operating system, so consult the
documentation for the image's operating system.
NETWORK CONFIGURATION
Once a custom image is imported into Oracle Cloud Infrastructure, all existing NICs are
replaced with a single NIC. You will need to configure the NIC to access to the internet. You
need to ensure that DHCP is enabled on the NIC and that the MAC and IP addresses are not
hardcoded. You can configure the NIC during the image preparation process or after the
image has been imported to Oracle Cloud Infrastructure using serial console access to the
instance. Consult your system documentation on how to perform network configuration for
your system, and see Instance Console Connections.
Once the instance has been launched, you can attach and configure additional VNICs. See
Virtual Network Interface Cards (VNICs) for more information.
Preparing a Custom Windows Image for Emulation Mode
Oracle Cloud Infrastructure enables you to import a custom Windows image and then use the
custom image to launch virtual machine (VM) instances in emulation mode. Before you can
import the custom image, you need to prepare the custom image to ensure that instances
launched from the custom image can boot correctly and that network connections will work.
This topic describes the steps to prepare custom Windows images for import.
You can perform the tasks describe in this topic on the running source system. If you have
concerns about modifying the live source system, you can export the image as-is, import it
into Oracle Cloud Infrastructure, and then launch an instance based on the custom image. You
can then connect to the instance using the VNC console and perform the preparation steps. For
more information, see Connecting to the VNC Console.

CHAPTER 6 Compute
Important
The system drive where Windows is installed will be

imported to Oracle Cloud Infrastructure. All partitions
on the drive will follow through the imported image. Any
other drives will not be imported and they need to be
re-created on the instance after import. You'll then need
to manually move the data on the non-system drives
manually.
S ECURITY
Follow your organization's security guidelines to make sure the Windows system is secured.
This can include, but is not limited to the following tasks:
l Install the latest security updates for the operating system and installed applications.
l Enable the firewall, and configure it so that you only enable the rules which are needed.
l Disable unnecessary privileged accounts.
l Use strong password for all accounts.
REMOTE DESKTOP
You connect to Windows instances running in Oracle Cloud Infrastructure by using a Remote
Desktop connection. For more information see Connecting to a Windows Instance and To
enable RDP access. You need to make sure that Remote Desktop connections are enabled on
the Windows system. For more information see Remote Desktop Client FAQ - Setting Up.
LOAD IDE DRIVER AT BOOT TIME - W INDOWS S ERVER 2008 R2
Emulated instances have an emulated IDE boot drive, which requires that Windows have the
IDE driver loaded by default at boot time. You need to perform the following steps for
Windows Server 2008 R2 systems before exporting the image, otherwise the image will boot
into recovery mode in Oracle Cloud Infrastructure.

CHAPTER 6 Compute
Note
These steps only apply to Windows Server 2008 R2

images, Windows Server 2012 and newer images do not
require these steps.
To load the IDE driver at boot time

1. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\intelide
2. Change the value of Start to 0.
Setting the Start key to 0 specifies that the kernel should load the driver at boot time. For
more information, see What Determines When a Driver Is Loaded.
If this has not been configured before you export the image, and an instance launched from
the image boots into recovery mode in Oracle Cloud Infrastructure, you can configure this in
recovery mode.
To configure the image to load the IDE driver at boot time from recovery
mode
1. From a command prompt, type and run:
regedit
2. Click Local Machines.

3. From the File menu, click Load Hive.
4. Navigate to:
<system_drive>:\Windows\System32\config
5. Select the file named system, and specify a name. The name is temporary, and you

CHAPTER 6 Compute
can specify any string. This step loads the HKLM hive under the specified name.
6. Within this hive, navigate to:
SYSTEM\CurrentControlSet\services\intelide
7. Change the value of Start to 0.
I MAGE GENERALIZATION
Unless the imported image will only be launched on one VM instance, you should create a
generalized image, which is an image cleaned of computer-specific information. The
generalization process removes unique identifiers from the image, so when instances are
created from the image, those unique identifiers will be re-generated. If not done, two
instances launched from same image will collide on those identifiers. See Creating a
Generalized Image for a step-by-step walkthrough of this process and Sysprep (Generalize) a
Windows installation for general information.
You should perform this step prior to importing the image to Oracle Cloud Infrastructure. If
this is not an option, you could perform this step on an instance created from a specialized
image, and create a custom image based on this instance which you could then create a
generalized image from.
Importing Custom Images for Emulation Mode
Oracle Cloud Infrastructure enables you to import a custom image and then use the custom
image to launch virtual machine (VM) instances in emulation mode. For more information
about supported images and image requirements, see Bring Your Own Custom Image for
Emulation Mode Virtual Machines. This topic walks through the custom image import process.
You need to prepare the image prior to importing, see Preparing a Custom Linux Image for
Emulation Mode and Preparing a Custom Windows Image for Emulation Mode for more
information.
PREREQUISITES
Prior to importing a custom image, you need to:

CHAPTER 6 Compute
l Prepare the image prior to importing it. See Preparing a Custom Linux Image for
Emulation Mode and Preparing a Custom Windows Image for Emulation Mode for more
information.
l Upload the image to Object Storage. See Overview of Object Storage for more
information.
TO IMPORT A CUSTOM LINUX-BASED IMAGE USING THE CONSOLE

2. Click Images and then click Import Image.
5. Specify the Object Storage URL where the image is stored. You need to specify a pre-
authenticated request URL.
6. Select the image format.
7. Select EMULATED MODE for LAUNCH MODE.
9. Click Import Image.
Once you click Import Image, you'll see the imported image in the Custom Images list for
the compartment, with a status of IMPORTING. Once the import completes successfully, the
status will change to AVAILABLE. If the status does not change, or no entry appears in the
Custom Images list, the import failed. If the import failed, make sure you have read access
to the Object Storage object, and that the object contains a supported image.
NEXT STEPS
After importing the custom Linux-based image, the next steps are:

CHAPTER 6 Compute
1. Launch an instance based on the custom image. See Launching an Instance for more
information. To select a custom image, choose CUSTOM IMAGE as the Image
Source. You can then select the imported custom image from the Images list.
2. Create a serial console connection to the instance. See Instance Console Connections
for more information.
See Compute Known Issues for current issues and workarounds for imported custom images.
TO IMPORT A CUSTOM W INDOWS-BASED IMAGE USING THE CONSOLE

2. Click Images and then click Import Image.
5. Select Windows as the OPERATING SYSTEM, and then select the applicable version
from the OPERATING SYSTEM VERSION dropdown.
6. Once you have confirmed that you've selected the operating system version that
complies with your Microsoft licensing agreement, check the compliance checkbox.
Important
Failure to provide the correct version and SKU

information could be a violation of your Microsoft
Licensing Agreement.
7. Specify the Object Storage URL where the image is stored. You need to specify a pre-
authenticated request URL.
8. Select the image format your image is saved as.
9. Select EMULATED MODE for LAUNCH MODE.

CHAPTER 6 Compute
11. Check View detail page after this image is imported.
12. Click Import Image.
The Image Details page will be displayed with the image lifecycle state as IMPORTING.
Once the import has completed successfully, the lifecycle state will change to AVAILABLE.
If the status does not change, or no entry appears in the Custom Images list, the import
failed. If the import failed, make sure you have read access to the Object Storage object, and
that the object contains a supported image.
NEXT STEPS
After importing the custom Windows-based image, the next steps are:
1. Launch an instance based on the custom image. See Launching an Instance for more
information. To select a custom image, choose CUSTOM IMAGE as the Image
Source. You can then select the imported custom image from the Images list. You also
need to enable RDP access for the instance, see To enable RDP access for more
information.
2. Configure the instance to use the Oracle-provided Key Management Service (KMS)
server for activation.
To configure the instance to use the Oracle-provided KMS server
Important
You should perform this task after the custom

image is imported into Oracle Cloud Infrastructure.

CHAPTER 6 Compute
a. Connect to the instance from Remote Desktop using the public IP address
for the instance, displayed in the Instance Details page of the Console.
b. Open a Windows command line or PowerShell, running as Administrator.
c. Run the following command to set the KMS endpoint:
slmgr /skms 169.254.169.253:1688
d. Register the Windows system with the KMS client key. For details, see .
e. Run the following command to activate Windows:
slmgr /ato
f. From Windows PowerShell, run the following command to verify your license
status:
Get-CimInstance -ClassName SoftwareLicensingProduct | where {$_.PartialProductKey} |
select Description, LicenseStatus
OS Kernel Updates
Note
This topic applies only to Linux instances that were

launched before February 15, 2017. Linux instances
launched on or after February 15, 2017 boot directly
from the image and do not require further action for
kernel updates.
Oracle Cloud Infrastructure boots each instance from a network drive. This configuration
requires additional actions when you update the OS kernel.
Oracle Cloud Infrastructure uses Unified Extensible Firmware Interface (UEFI) firmware and a
Preboot eXecution Environment (PXE) interface on the host server to load iPXE from a Trivial
File Transfer Protocol (TFTP) server. The iPXE implementation runs a script to boot Oracle
Linux. During the boot process, the system downloads the kernel, the initrd file, and the

CHAPTER 6 Compute
kernel boot parameters from the network. The instance does not use the host's GRUB boot
loader.
Normally, the yum update kernel-uek command edits the GRUB configuration file, either
grub.cfg or grub.conf, to configure the next boot. Since bare metal instances do not use the
GRUB boot loader, changes to the GRUB configuration file are not implemented. When you
update the kernel on your instance, you also must upload the update to the network to ensure
a successful boot process. The following approaches address this need:
l Instances launched from an Oracle-provided image include an Oracle yum plug-in that
seamlessly handles the upload when you run the yum update kernel-uek command.
l If you use a custom image based on an Oracle-provided image, the included yum plug-
in will continue to work, barring extraordinary changes.
l If you install your own package manager, you must either write your own plug-in or
upload the kernel, initrd, and kernel boot parameters manually.
Oracle Yum Plug-in

On instances launched with an Oracle-provided image, you can find the Oracle yum plug-in at:
/usr/share/yum-plugins/kernel-update-handler.py
The plug-in configuration is at:
/etc/yum/pluginconf.d
The plug-in looks for two variables in the /etc/sysconfig/kernel file, UPDATEDEFAULT
and DEFAULTKERNEL . It picks up the updates only when the first variable is set to "yes"
and the DEFAULTKERNEL value matches the kernel being updated. For example:
# UPDATEDEFAULT specifies if new-kernel-pkg should make
# new kernels the default
UPDATEDEFAULT=yes
# DEFAULTKERNEL specifies the default kernel package type

DEFAULTKERNEL=kernel-uek

CHAPTER 6 Compute
Oracle-provided images incorporate the Unbreakable Enterprise Kernel (UEK). If you want to
switch to a non-UEK kernel, you must update the DEFAULTKERNEL value to "kernel" before
you run yum update kernel.
Manual Updates
Tip
Oracle recommends using the Oracle yum plug-in to

update the kernel.
If you manually upload the updates, there are four relevant URLs:
http://169.254.0.3/kernel
http://169.254.0.3/initrd
http://169.254.0.3/cmdline
http://169.254.0.3/activate
The first three URLs are for uploading files (HTTP request type PUT). The fourth URL is for
activating the uploaded files (HTTP request type POST). The system discards the uploaded
files if they are not activated before the host restarts.
The kernel and initrd are simple file uploads. The cmdline upload must contain the kernel boot
parameters found in the grub.cfg or grub.conf file, depending on the Linux version. The
following example is an entry from the /boot/efi/EFI/redhat/grub.cfg file in Red Hat
Linux 7. The highlighted text represents the parameters to upload.
kernel /boot/vmlinuz-4.1.12-37.5.1.el6uek.x86_64 ro root=UUID=8079e287-53d7-4b3d-b708-c519cf6829c8 rd_
NO_LUKS KEYBOARDTYPE=pc KEYTABLE=us netroot=iscsi:@169.254.0.2::3260:iface1:eth0::iqn.2015-
02.oracle.boot:uefi rd_NO_MD SYSFONT=latarcyrheb-sun16 ifname=eth0:90:e2:ba:a2:e3:80 crashkernel=auto
iscsi_initiator=iqn.2015-02. rd_NO_LVM ip=eth0:dhcp rd_NO_DM LANG=en_US.UTF-8 console=tty0
console=ttyS0,9600 iommu=on
The following command returns what is being uploaded to the cmdline file.
cat /tmp/cmdline

CHAPTER 6 Compute
A typical response resembles the following.

ro root=UUID=8079e287-53d7-4b3d-b708-c519cf6829c8 rd_NO_LUKS KEYBOARDTYPE=pc KEYTABLE=us
netroot=iscsi:@169.254.0.2::3260:iface1:eth0::iqn.2015-02.oracle.boot:uefi rd_NO_MD SYSFONT=latarcyrheb-
sun16 ifname=eth0:90:e2:ba:a2:e3:80 crashkernel=auto iscsi_initiator=iqn.2015-02. rd_NO_LVM ip=eth0:dhcp
rd_NO_DM LANG=en_US.UTF-8 console=tty0 console=ttyS0,9600 iommu=on
The following commands update the cmdline and initrd files, and then activate the changes.
CKSUM=`md5sum /tmp/cmdline | cut -d ' ' -f 1`
sudo curl -X PUT --data-binary @/tmp/cmdline -H "Content-MD5: $CKSUM" http://169.254.0.3/cmdline
CKSUM=`md5sum /boot/initramfs-3.8.13-118.8.1.el7uek.x86_64.img | cut -d ' ' -f 1`
sudo curl -X PUT --data-binary @/boot/initramfs-3.8.13-118.8.1.el7uek.x86_64.img -H "Content-MD5:

$CKSUM" http://169.254.0.3/initrd
sudo curl -X POST http://169.254.0.3/activate
Managing Key Pairs on Linux Instances

Instances launched using Oracle Linux, CentOS, or Ubuntu images use an SSH key pair
instead of a password to authenticate a remote user (see Security Credentials). A key pair
consists of a private key and public key. You keep the private key on your computer and
provide the public key every time you launch an instance.
When you connect to an instance using SSH, you provide the path to the key pair file in the
SSH command. You can have as many key pairs as you want, or you can keep it simple and
use one key pair for all or several of your instances.
To create key pairs, you can use a third-party tool such as OpenSSH on UNIX-style systems
(including Linux, Solaris, BSD, and OS X) or PuTTY Key Generator on Windows.
Prerequisites
If you're using a UNIX-style system, you probably already have the ssh-keygen utility
installed. To determine if it's installed, type ssh-keygen on the command line. If it's not
installed, you can download OpenSSH for UNIX from http://www.openssh.com/portable.html
and install it.

CHAPTER 6 Compute
If you're using a Windows operating system you will need PuTTY and the PuTTY Key
Generator. Download PuTTY and PuTTYgen from http://www.putty.org and install them.
Creating an SSH Key Pair on the Command Line

1. Open a shell or terminal for entering the commands.
2. At the prompt, enter ssh-keygen and provide a name and passphrase when prompted.
The keys will be created with the default values: RSA keys of 2048 bits.
Alternatively, you can type a complete ssh-keygen command, for example:

ssh-keygen -t rsa -N "" -b 2048 -C "<key_name>" -f <path/root_name>
The command arguments are shown in the following table:
Argument Description
-t rsa Use the RSA algorithm.
-N "<passphrase>" A passphrase to protect the use of the key (like a password).

If you don't want to set a passphrase, don't enter anything
between the quotes.
A passphrase is not required. You can specify one as a

security measure to protect the private key from
unauthorized use.
-b 2048 Generate a 2048-bit key. You don't have to set this if 2048 is
acceptable, as 2048 is the default.
A minimum of 2048 bits is recommended for SSH-2 RSA.
-C "<key_name>" A name to identify the key.
-f <path/root_name> The location where the key pair will be saved and the root
name for the files.

CHAPTER 6 Compute
Creating an SSH Key Pair Using PuTTY Key Generator

1. Find puttygen.exe in the PuTTY folder on your computer, for example, C:\Program
Files (x86)\PuTTY. Double-click puttygen.exe to open it.
2. Accept the default key type of SSH-2 RSA and set the Number of bits in a
generated key to 2048 if it is not already set.
3. Click Generate.

CHAPTER 6 Compute
4. Move your mouse around the blank area to generate random data in the key, as shown
below.
(The red line in the following image is for illustration purposes only. It doesn't appear in
the generator pane as you move the mouse.)

CHAPTER 6 Compute
5. The generated key appears under Public key for pasting into OpenSSH
authorized_keys file.
6. The Key comment is generated for you, including the date and time stamp. You can
keep the generated key comment or overtype it with your own more descriptive
comment.
7. Leave the Key passphrase field blank.

CHAPTER 6 Compute
8. Click Save private key and then click Yes in the prompt about saving the key without
a passphrase.
The key pair is saved in the PuTTY Private Key (PPK) format, which is a proprietary
format that works only with the PuTTY tool set.
You can call the key anything you want, but use the ppk file extension, for example,
mykey.ppk.
9. Select all of the generated key that appears under Public key for pasting into
OpenSSH authorized_keys file, copy it using Ctrl + C, paste it into a text file, and
then save the file in the same location as the private key.
(Do not use Save public key because it does not save the key in the OpenSSH format.)
You can call the key anything you want, but for consistency, use the same name as the
private key and a file extension of pub, for example, mykey.pub.
10. Write down the names and location of your public and private key files. You will need
the public key when launching an instance. You will need the private key to access the
instance via SSH.
Now that you have a key pair, you're ready to launch instances as described in Launching an
Instance.
Launching an Instance
You can launch an instance using the Console or API. When you launch an instance, it is
automatically attached to a Virtual Network Interface Card (VNIC) in the cloud network's
subnet and given a private IP address from the subnet's CIDR. You can either let the address
be automatically assigned, or specify a particular address of your choice. The private
IP address lets instances within the cloud network communicate with each other. They can
instead use fully qualified domain names (FQDNs) if you've set up the cloud network for DNS
(see DNS in Your Virtual Cloud Network).
You have the option to assign the instance a public IP address if the subnet is public. A public
IP address is required to communicate with the instance over the Internet, and to establish a
Secure Shell (SSH) or RDP connection to the instance from outside the cloud network. For
more information, see Internet Access.

CHAPTER 6 Compute
Tip
If this is your first time launching an instance, consider

following the Getting Started Tutorial for a guided
workflow through the steps required to launch an
instance.
Required IAM Policy

Tip
When you launch an instance, several other resources

are involved (e.g., an image, a cloud network, a subnet,
etc.). Those other resources can be in the same
compartment with the instance or in other
compartments. You must have the required level of
access to each of the compartments involved in order to
launch the instance. This is also true when you attach a
volume to an instance; they don't have to be in the
same compartment, but if they're not, you need the
required level of access to each of the compartments.
For administrators: The simplest policy to enable users to launch instances is listed in Let
users launch instances. It gives the specified group general access to managing instances and
images, along with the required level of access to attach existing block volumes to the

CHAPTER 6 Compute
instances. If the group needs to create block volumes, they'll need the ability to manage block
volumes (see Let volume admins manage block volumes and backups).
Using the Console to Launch an Instance

To launch a Linux or Windows instance, see the corresponding section that follows:
Launching a Linux Instance
Prerequisites
To launch a Linux instance, you'll need:
networks, see Overview of Networking.
l The public key, in OpenSSH format, from the key pair that you plan to use for
connecting to the instance via SSH. The following sample public key is abbreviated for
readability:
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAA....lo/gKMLVM2xzc1xJr/Hc26biw3TXWGEakrK1OQ== rsa-key-20160304
For information about generating a key pair, see Managing Key Pairs on Linux
Instances.
To launch a Linux instance using the Console:
1. Open the Console, click Compute, choose a Compartment you have permission to
work in, and then click Launch Instance.
2. In the Launch Instance dialog box, you specify the resources to use for your instance.
By default, your instance launches in, and the resources you choose come from, your
current compartment. Click the click here link in the dialog box if you want to enable

CHAPTER 6 Compute
compartment selection for the instance's image, cloud network, or subnet resources.
You can also choose a different compartment in which to launch your instance.
In the Launch Instance dialog box, you can specify the following:
l Launch in Compartment: The compartment in which you want to launch the
instance.
l Name: The name for the instance. You can add or change the name later. The
name doesn't need to be unique; an Oracle Cloud Identifier (OCID) uniquely
identifies the instance.
l Availability Domain: The availability domain in which you want to run the
instance.
l Image Compartment: The compartment from which to select the image.
l Image Source: The source of the image to use for booting the instance. The
following options are available:
o ORACLE-PROVIDED OS IMAGE: If you select this option, the IMAGE
OPERATING SYSTEM drop-down appears, and you can select one of the
images that are available in Oracle Cloud Infrastructure. See Oracle-
Provided Images for a list of these images.
o CUSTOM IMAGE: If you select this option, the IMAGE drop-down appears,
listing all of the custom images available in the current or selected
compartment. See Managing Custom Images for more information about
custom images.
o BOOT VOLUME: Select this option to launch an instance based on an
existing boot volume. If you select this option, the BOOT VOLUME drop-
down appears, listing all of the available boot volumes in the current or
selected compartment. You can only launch an instance using a boot volume
where the associated instance has been terminated. See Boot Volumes for
more information.
o IMAGE OCID: Select this option to specify the image OCID for a specific

CHAPTER 6 Compute
image to use to launch the instance. See Oracle-Provided Image Release

Notes to determine the image OCID for Oracle-provided images.
l Shape Type: Select VIRTUAL MACHINE or BARE METAL MACHINE.
l Shape: A template that determines the number of CPUs, amount of memory, and
other resources allocated to a newly created instance. The SHAPE drop-down is
populated with the list of available VM or bare metal shapes based on what you
selected for shape type. Incompatible shapes in the list are grayed out and you
will not be able to select them. The following table lists the available bare metal
and VM shapes:
Bare Metal Shapes
Shape Instanc OCP Memor Local Network Maximu

e Type U y (GB) Disk Bandwidt m VNICs
(TB) h1 Total 2
BM.Standard1. Standard 36 256 Block 10 Gbps 16

36 compute storag
capacity e only

compute NVMe
capacity SSD
BM.DenseIO1.3 Dense 36 512 28.8TB 10 Gbps 16

6 I/O NVMe
compute SSD
capacity

CHAPTER 6 Compute

(TB) h1 Total 2
BM.Standard2. X7- 52 768 Block 2 x 25 24 total

52 based storag Gbps (12 per
standard e only physical
compute NIC)
capacity
BM.DenseO2.52 X7- 52 768 51.2TB 2 x 25 24 total

based NVMe Gbps (12 per
dense SSD physical
I/O NIC)
compute
capacity
BM.GPU2.2 X7- 28 192 Block 2 x 25 24 total

based storag Gbps (12 per
GPU: 2 e only physical
P100 NIC)
NVIDIA
GPUs

VM Shapes
VMs are an option that provides flexibility in compute power, memory capability,
and network resources for lighter applications. You can use Block Volume to add
network-attached block storage as needed.

CHAPTER 6 Compute
Shape OCPU Memory Local Network Maximum

(GB) Disk Bandwidth VNICs
(TB) 1 Total 2

Storage Mbps
only
VM.Standard1.2 2 14 Block Up to 1.2 2

Storage Gbps
only

Storage
only

Storage
only

Storage
only

NVMe
SSD

NVMe
SSD

CHAPTER 6 Compute

(TB) 1 Total 2

NVMe
SSD

Storage
only

Storage
only

Storage
only

Storage
only

Storage
only

Storage
only

CHAPTER 6 Compute

(TB) 1 Total 2

NVMe
SSD

NVMe
SSD

NVMe
SSD

Note

Phoenix region.
l Image Build: The build version to use for Oracle-provided images. We

recommend that you select the latest version. For specific build details, see
Oracle-Provided Image Release Notes.
l Boot Volume Size: The size of the selected image's boot volume. Select
Custom Boot Volume Size to specify a custom size up to from 50 GB to 16 TB.

CHAPTER 6 Compute
The specified size must be larger than the selected image's default boot volume
size. See Custom Boot Volume Sizes for more information.
l Virtual Cloud Network Compartment: The compartment containing the
network in which to launch the instance.
l Virtual Cloud Network: The network in which to launch the instance.
l Subnet Compartment: The compartment containing a subnet within the cloud
network to attach the instance to.
l Subnet: A subnet within the cloud network to attach the instance to. The subnets
are either public or private. Private means the instances in that subnet can't have
public IP addresses. For more information, see Internet Access.
l Private IP Address: Optional. An available private IP address of your choice
from the subnet's CIDR (otherwise the private IP address is automatically
assigned).
l Assign public IP address: Whether to assign the instance a public IP address.
Available only if the subnet is public. For more information, see Internet Access.
l Hostname: Optional. A hostname to be used for DNS within the cloud network.
Available only if the VCN and subnet both have DNS labels. For more information,
see DNS in Your Virtual Cloud Network.
l SSH Keys: The public key portion of the key pair you want to use for SSH access
to the instance. You can drag and drop single key files into the box. To provide
multiple keys, click Browse, then press and hold down the Command key (on
Mac) or the CTRL key (on Windows) while selecting files.
l User Data: Data to be used by Cloud-Init to run custom scripts or provide custom
Cloud-Init configuration. Click Show Advanced Options, and then click Browse
to select the script file, or paste the script into the text box. The file or script does
not need to be base64-encoded, as the Console performs this encoding when the
information is submitted. For information about how to take advantage of user
data, see the Cloud-Init Documentation.

CHAPTER 6 Compute
administrator.
3. Click Launch Instance.
After the instance is provisioned, details about it appear in the instance list. To view additional
details, including IP addresses, click the instance name.
When the instance is fully provisioned and running, you can connect to it using SSH as
described in Connecting to an Instance.
You also can attach a volume to the instance, provided the volume is in the same availability
domain.
Launching a Windows Instance
Prerequisites
To launch an Windows instance, you'll need:
networks, see Overview of Networking.
l A security list that enables Remote Desktop Protocol (RDP) access so you can connect to
your instance. Specifically, you need a stateful ingress rule for TCP traffic on destination
port 3389 from source 0.0.0.0/0 and any source port. For more information, see
Security Lists.
To enable RDP access
1. In the Console, click Networking, and then click Virtual Cloud Networks.
2. Click the cloud network you're interested in.

CHAPTER 6 Compute
3. Click Security Lists, and then click the security list you're interested in.
4. Click Edit Rules.
5. Under Allow Rules for Ingress, click Add Rule.
6. Enter the following for your new rule:
a. Source CIDR: 0.0.0.0/0
b. IP Protocol: TCP
c. Source Port Range: All
d. Destination Port Range: 3389
7. When done, click Save Security List Rules.
The following screenshot shows the settings for the new rule:
To launch a Windows instance using the Console:

CHAPTER 6 Compute
1. Open the Console, click Compute, choose a Compartment you have permission to
work in, and then click Launch Instance.
2. In the Launch Instance dialog box, you specify the resources to use for your instance.
By default, your instance launches in, and the resources you choose come from, your
current compartment. Click the click here link in the dialog box if you want to enable
compartment selection for the instance's image, cloud network, or subnet resources.
You can also choose a different compartment in which to launch your instance.
In the Launch Instance dialog box, you can specify the following:
l Launch in Compartment: The compartment in which you want to launch the
instance.
l Name: The name for the instance. You can add or change the name later. The
name doesn't need to be unique; an Oracle Cloud Identifier (OCID) uniquely
identifies the instance.
l Availability Domain: The availability domain in which you want to run the
instance.
l Image Compartment: The compartment from which to select the image.
l Image Source: The source of the image to use for booting the instance. The
following options are available:
o ORACLE-PROVIDED OS IMAGE: If you select this option, the IMAGE
OPERATING SYSTEM drop-down appears, and you can select one of the
images that are available in Oracle Cloud Infrastructure. See Oracle-
Provided Images for a list of these images.
o CUSTOM IMAGE: If you select this option, the IMAGE drop-down appears,
listing all of the custom images available in the current or selected
compartment. See Managing Custom Images for more information about
custom images.
o BOOT VOLUME: Select this option to launch an instance based on an
existing boot volume. If you select this option, the BOOT VOLUME drop-
down appears, listing all of the available boot volumes in the current or

CHAPTER 6 Compute
selected compartment. You can only launch an instance using a boot volume
where the associated instance has been terminated. See Boot Volumes for
more information.
o IMAGE OCID: Select this option to specify the image OCID for a specific
image to use to launch the instance. See Oracle-Provided Image Release
Notes to determine the image OCID for Oracle-provided images
l Shape Type: Select VIRTUAL MACHINE or BARE METAL MACHINE.
l Shape: A template that determines the number of CPUs, amount of memory, and
other resources allocated to a newly created instance.The SHAPE drop-down is
populated with the list of available VM or bare metal shapes based on what you
selected for shape type. Incompatible shapes in the list are grayed out and you
will not be able to select them. The following table lists the available bare metal
and VM shapes:
Bare Metal Shapes

(TB) h1 Total 2
BM.Standard1. Standard 36 256 Block 10 Gbps 16

36 compute storag
capacity e only

compute NVMe
capacity SSD
BM.DenseIO1.3 Dense 36 512 28.8TB 10 Gbps 16

6 I/O NVMe
compute SSD
capacity

CHAPTER 6 Compute

(TB) h1 Total 2
BM.Standard2. X7- 52 768 Block 2 x 25 24 total

52 based storag Gbps (12 per
standard e only physical
compute NIC)
capacity
BM.DenseO2.52 X7- 52 768 51.2TB 2 x 25 24 total

based NVMe Gbps (12 per
dense SSD physical
I/O NIC)
compute
capacity
BM.GPU2.2 X7- 28 192 Block 2 x 25 24 total

based storag Gbps (12 per
GPU: 2 e only physical
P100 NIC)
NVIDIA
GPUs

VM Shapes
VMs are an option that provides flexibility in compute power, memory capability,
and network resources for lighter applications. You can use Block Volume to add
network-attached block storage as needed.

CHAPTER 6 Compute

(TB) 1 Total 2

Storage Mbps
only
VM.Standard1.2 2 14 Block Up to 1.2 2

Storage Gbps
only

Storage
only

Storage
only

Storage
only

NVMe
SSD

NVMe
SSD

CHAPTER 6 Compute

(TB) 1 Total 2

NVMe
SSD

Storage
only

Storage
only

Storage
only

Storage
only

Storage
only

Storage
only

CHAPTER 6 Compute

(TB) 1 Total 2

NVMe
SSD

NVMe
SSD

NVMe
SSD

Note

Phoenix region.
l Image Build: The build version to use for Oracle-provided images. We

recommend that you select the latest version. For specific build details, see
Oracle-Provided Image Release Notes.
l Boot Volume Size: The size of the selected image's boot volume. Select
Custom Boot Volume Size to specify a custom size up to from 50 GB to 16 TB.

CHAPTER 6 Compute
The specified size must be larger than the selected image's default boot volume
size. See Custom Boot Volume Sizes for more information.
l Virtual Cloud Network Compartment: The compartment containing the
network in which to launch the instance.
l Virtual Cloud Network: The network in which to launch the instance.
l Subnet Compartment: The compartment containing a subnet within the cloud
network to attach the instance to.
l Subnet: A subnet within the cloud network to attach the instance to. The subnets
are either public or private. Private means the instances in that subnet can't have
public IP addresses. For more information, see Internet Access.
assigned).
l Assign public IP address: Whether to assign the instance a public IP address.
Available only if the subnet is public. For more information, see Internet Access.
administrator.
3. Read the Partner Terms of Use. If you accept them, click I accept the Partner
Terms of Use.
4. Click Launch Instance.

CHAPTER 6 Compute
Managing Tags for an Instance

You can apply tags to your resources, such instances, to help you organize them according to
your business needs. You can apply tags at the time you create an instance, or you can update
the instance later with the desired tags.
To manage tags for an instance

In the Console, click Compute, and then click Instances.
1.
2. Click the instance you're interested in.
ones.
Using the API

Use these API operations to manage instances:
l ListInstances
l LaunchInstance
l GetInstance
l UpdateInstance
l TerminateInstance
l GetWindowsInstanceInitialCredentials

CHAPTER 6 Compute
Connecting to an Instance
You can connect to a running instance by using a Secure Shell (SSH) or Remote Desktop
connection. Most UNIX-style systems include an SSH client by default. To connect to a Linux
instance from a Windows system, you can download a free SSH client called PuTTY from
http://www.putty.org.
Required IAM Policy

To connect to a running instance with SSH, you don't need an IAM policy to grant you access.
However, to SSH you need the public IP address of the instance (see Prerequisites below). If
there's a policy that lets you launch an instance, that policy probably also lets you get the
instance's IP address. The simplest policy that does both is listed in Let users launch
instances.
For administrators: Here's a more restrictive policy that lets the specified group get the IP
address of existing instances and use power actions on the instances (e.g., stop, start, etc.),
but not launch or terminate instances. The policy assumes the instances and the cloud
network are together in a single compartment (XYZ):
Allow group InstanceUsers to read virtual-network-family in compartment XYZ
Allow group InstanceUsers to use instance-family in compartment XYZ
Prerequisites
You'll need the following information to connect to the instance:
l For Linux Instances: The full path to the key pair that you used when you launched the
instance. For information about generating key pairs, see Managing Key Pairs on Linux
Instances.

CHAPTER 6 Compute
l The default user name for the instance. If you used an Oracle-provided Linux, CentOS or
Windows image to launch the instance, the user name is opc. If you used the Ubuntu
image to launch the instance, the user name is ubuntu.
l The public IP address of the instance. You can get the address from the list of instances
in the Console. Click Compute, choose your Compartment, and then find your
instance in the list. Alternatively, you can use the Core Services API
ListVnicAttachments and GetVnic operations.
Connecting to a Linux Instance

Log in to your instance using SSH.
Connecting to Your Linux Instance from a Unix-style System

1. Use the following command to set the file permissions so that only you can read the file:
$ chmod 400 <private_key>
<private_key> is the full path and name of the file that contains the private key
associated with the instance you want to access.
$ ssh –i <private_key> <username>@<public-ip-address>
<private_key> is the full path and name of the file that contains the private key
associated with the instance you want to access.
<username> is the default name for the instance. For Oracle Linux and CentOS images,
the default user name is opc. For the Ubuntu image, the default name is ubuntu.
<public-ip-address> is your instance IP address that you retrieved from the Console.
Connecting to Your Linux Instance from a Windows System
1. Open putty.exe.
2. In the Category pane, select Window, and then select Translation.

CHAPTER 6 Compute
3. In the Remote character set drop down, select UTF-8. The default locale setting on
Linux-based instances is UTF-8, and this configures PuTTY to use the same locale.
4. In the Category pane, select Session and enter the following:
l Host Name (or IP address):
<username>@<public-ip-address>
<username> is the default name for the instance. For Oracle Linux and CentOS
images, the default user name is opc. For the Ubuntu image, the default name is
ubuntu.
<public-ip-address> is your instance public IP address that you retrieved from
the Console
l Connection type: SSH
l Port:22
5. In the Category pane, expand Connection, expand SSH, and then click Auth.
6. Click Browse to select your private key.
7. Click Open to start the session.
Connecting to a Windows Instance

You can connect to a Windows instance by using a Remote Desktop connection. Most Windows
systems include a Remote Desktop client by default.
To enable Remote Desktop Protocol (RDP) access to the Windows instance, you need to add a
stateful ingress rule for TCP traffic on destination port 3389 from source 0.0.0.0/0 and any
source port.
To enable RDP access


CHAPTER 6 Compute
3. Click Security Lists, and then click the security list you're interested in.
5. Under Allow Rules for Ingress, click Add Rule.
6. Enter the following for your new rule:
a. Source CIDR: 0.0.0.0/0
b. IP Protocol: TCP
c. Source Port Range: All
d. Destination Port Range: 3389
7. When done, click Save Security List Rules.
The following screenshot shows the settings for the new rule:

CHAPTER 6 Compute
Connecting to Your Windows Instance from a Remote Desktop Client

1. Open the Remote Desktop client.
2. In the Computer field, enter the public IP address of the instance you want to connect
to. Your public IP is the instance address you get from the Console.
3. The User name is opc. Depending on the Remote Desktop client you are using, you
might have to connect to the instance before you can enter this credential.
4. Click Connect to start the session.
5. Accept the certificate if you are prompted to do so.
6. If you are connecting to the instance for the first time, enter the initial password that
was provided to you by Oracle Cloud Infrastructurewhen you launched the instance. You
will be prompted to change the password as soon as you log in. Your new password
must be at least 12 characters long and must comply with Microsoft's password policy.
Otherwise, enter the password you created. If you are using a custom image, you may
need to know the password for the instance the image was created from. For details
about Windows custom images, see Creating Windows Custom Images.
7. Press Enter.
Instance Console Connections

The Oracle Cloud Infrastructure Compute service provides console connections that enable
you to remotely troubleshoot malfunctioning instances, such as:
l An imported or customized image that does not complete a successful boot.

l A previously working instance that stops responding.
There are two types of instance console connections:
l Serial console connections

l VNC console connections

CHAPTER 6 Compute
Creating the Instance Console Connection

Before you can connect to the serial console or VNC console, you need to create the instance
console connection.
To create the console connection for an instance

1. In the Console, click Compute, choose your Compartment, and then click Instances.
2. In the list of instances, find the instance you want to access the serial console for, and
then click the instance name.
3. In the Resources section on the Instance Details page, click Console Connections,
and then click Create Console Connection.
4. Specify the public key portion for the SSH key, either by browsing and selecting a public
key file, for example id_rsa.pub, or by pasting your public key into the text box, and
then click Create Console Connection.
Once the console connection has been created and is available, the status changes to ACTIVE.
Connecting to the Serial Console

Once you have created the console connection for the instance, you can then connect to the
serial console by using a Secure Shell (SSH) connection. Once you are finished with the serial
console and have terminated the SSH connection, you should delete the serial console
connection. If you do not disconnect from the session, Oracle Cloud Infrastructure will
terminate the serial console session after 24 hours and you will need to re-authenticate to
connect again.

CHAPTER 6 Compute
Note
Serial console connections for VM instances launched prior to

September 2017
Serial console connections only work for VM instances

launched in September 2017 or later.
Note
Serial console connections for bare metal instances launched

prior to November 2017
Serial console connections only work for Bare Metal

instances launched in November 2017 or later.
Connecting from Mac OS X and Linux Operating Systems
You connect to the serial console by using an SSH client. Mac OS X and most Linux
distributions by default include the SSH client OpenSSH.
To connect to the serial console for an instance using OpenSSH on Mac OS X or

Linux
1. In the Console, on the Instances Details page, in the Resources section, click
Console Connections.
2. Click the Actions icon ( ), and then click Connect with SSH.
3. Select LINUX/MAC OS for PLATFORM.
4. Click Copy to copy the string to the clipboard.
5. Paste the connection string copied from the previous step to a terminal window on a Mac
OS X or Linux system, and hit enter to connect to the console.

CHAPTER 6 Compute
If you are not using the default SSH key or ssh-agent, you can modify the serial console
connection string to include the identity file flag, -i to specify the SSH key to use. You
need to specify this for both the SSH connection and the SSH ProxyCommand, as shown
in the following line:
ssh -i /<path>/<ssh_key> -o ProxyCommand='ssh -i /<path>/<ssh_key> -W %h:%p -p 443...
6. Hit enter again to activate the console.
Connecting from Windows Operating Systems
Windows does not include an SSH client by default, so you need to install one. You can use
PuTTY, or there are options that include a version of OpenSSH such as:
l git tools for Windows

l Windows Subsystem for Linux
Note that the steps to connect to the serial console from the PuTTY client will be different than
the steps for OpenSSH.
To connect to the serial console for an instance on Microsoft Windows

2. Click the Actions icon ( ), and then click Connect with SSH.
3. If you are using PuTTY, select WINDOWS for PLATFORM.
If you are using OpenSSH select LINUX/MAC OS for PLATFORM.
5. Paste the connection string copied from the previous step to PuTTY or your OpenSSH
client and hit enter to connect to the console.
6. Hit enter again to activate the console.

CHAPTER 6 Compute
Connecting to the VNC Console
Warning
The VNC console connection uses SSH port forwarding

to create a secure connection from your local system to
the VNC server attached to your instance's console.
While this is a secure way to use VNC over the internet,
owners of multiuser systems should be aware that
opening a port on the local system makes it available to
all of the users on that system until a VNC client
connects. For this reason, we don't recommend using
this product on a multiuser system unless you take
proper actions to secure the port or you isolate the VNC
client by running it in a virtual environment, such as
Oracle VM VirtualBox.
Once you have created the console connection for the instance, you need to set up a secure
tunnel to the VNC server on the instance, and then you can connect with a VNC client.
Note
VNC console connections for VM instances launched prior to

October 13th, 2017
VNC console connections only work for VM instances

launched on October 13th, 2017 or later.

CHAPTER 6 Compute
Note
VNC console connections for bare metal instances
VNC console connections are not supported on bare

metal instances.
To set up a secure tunnel to the VNC server on the instance using OpenSSH on
Mac OS X or Linux
2. Click the Actions icon ( ), and then click Connect with VNC.
3. Select LINUX/MAC OS for PLATFORM.
5. Paste the connection string copied from the previous step to a terminal window on a Mac
OS X or Linux system, and hit enter to set up the secure connection.
6. Once the connection has been established, open your VNC client and specify localhost
as the host to connect to and 5900 as the port to use.
Note
Mac OS X Screen Sharing.app Not Compatible with VNC Console

Connections
The Mac OS X built-in VNC client, Screen Sharing.app

does not work with VNC console connections in Oracle
Cloud Infrastructure. Use another VNC client, such as
Real VNC Viewer or Chicken.

CHAPTER 6 Compute
To set up a secure tunnel to the VNC server on the instance using PowerShell
on Windows
2. Click the Actions icon ( ), and then click Connect with VNC.
3. Select WINDOWS for PLATFORM.
5. Paste the connection string copied from the previous step to Windows Powershell and hit
enter to set up the secure connection.
6. Once the connection has been established, open your VNC client and specify localhost
as the host to connect to and 5900 as the port to use.
Note
Secure Connection Warning
When you connect, you may see a warning from the

VNC client that the connection is not encrypted. Since
you are connecting through SSH, the connection is
secure, so this is not an issue.
Troubleshooting Instances from Instance Console Connections

Once you are connected with an instance console connection, you can perform various tasks,
such as:
l Edit system configuration files.

l Add or reset the SSH keys for the opc user.
Both of these tasks require you to boot into a bash shell, in maintenance mode.

CHAPTER 6 Compute
Note
The following tasks describe steps specific to instances

running Oracle Linux 7, connecting from OpenSSH.
Other OS versions and SSH clients may require different
steps.
To boot into maintenance mode

1. Reboot the instance from the Console
l In the Console, on the Instances Details page, click Reboot.
2. Once the reboot process starts, switch back to the terminal window, and you see
Console messages start to appear in the window. As soon as you see the GRUB boot
menu appear, use the up/down arrow key to stop the automatic boot process, enabling
you to use the boot menu.
3. In the boot menu, highlight the top item in the menu, and type e to edit the boot entry.
4. In edit mode, use the down arrow key to scroll down through the entries until you reach
the line that starts with either linuxefi for instances running Oracle Linux 7.x, or
kernel for instances running Oracle Linux 6.x.
5. At the end of that line, add the following:
init=/bin/bash
6. Reboot the instance from the terminal window by entering the keyboard shortcut
CTRL+x.
Once the instance has rebooted, you'll see the Bash shell command-line prompt, and you can
proceed with either of the following procedures.

CHAPTER 6 Compute
To edit the system configuration files

1. From the Bash shell, run the following command to load the SELinux policies to preserve
the context of the files you are modifying:
/usr/sbin/load_policy -i
2. Run the following command to remount the root partition with read/write permissions:
/bin/mount -o remount, rw /
3. Edit the configuration files as needed to try to recover the instance.

4. Once you have finished editing the configuration files, to start the instance from the
existing shell, run the following command:
exec /usr/lib/systemd/systemd
Alternatively, to reboot the instance, run the following command:

/usr/sbin/reboot -f
To add or reset the SSH key for the opc user

1. From the Bash shell, run the following command to load the SELinux policies to preserve
the context of the files you are modifying:
/usr/sbin/load_policy -i
2. Run the following command to remount the root partition with read/write permissions:
/bin/mount -o remount, rw /
3. From the Bash shell, run the following command to change to the SSH key directory for
the opc user:
cd ~opc/.ssh
4. Rename the existing authorized keys file with the following command:
mv authorized_keys authorized_keys.old
5. Replace the contents of the public key file with the new public key file with the following
command:

CHAPTER 6 Compute
echo '<contents of .pub key file>' >> authorized_keys
6. Restart the instance by running the following command:

/usr/sbin/reboot -f
Exiting the Instance Console Connection
To exit the serial console connection

When using SSH, the ~ character at the beginning of a new line is used as an escape
character.
l To exit the serial console, enter:

~.
l To suspend the SSH session, enter:

~^z
The ^ character represents the CTRL key

l To see all the SSH escape commands, enter:
~?
To exit the VNC console connection

1. Close the VNC client.
2. In the Terminal or Powershell window, type CTRL C
Once you are finished using the console connection, delete the connection for the instance.
To delete the console connection for an instance


CHAPTER 6 Compute
2. Click the Actions icon ( ), click Delete, and then click OK to confirm.
Adding Users on an Instance

If you created your instance using an Oracle-provided Linux or CentOS image, you can use
SSH to access your instance from a remote host as the opc user. If you created your instance
using the Ubuntu image, you can use SSH to access your instance from a remote host as the
ubuntu user. After logging in, you can add users on your instance.
If you created your instance using an Oracle-provided Windows image, you can create new
users after you log on to the instance through a Remote Desktop client.
Creating Additional SSH-Enabled Users on Linux Instances

If you do not want to share your SSH key, you can create additional SSH-enabled users:
l Generate SSH key pairs for the users offline.

l Add the new users.
l Append a public key to the ~/.ssh/authorized_keys file for each new user.

CHAPTER 6 Compute
Tip
If you re-create an instance from an Oracle-provided

image, users and SSH public keys that you added or
edited manually (that is, users that weren’t defined in
the machine image) must be added again.
If you need to edit the ~/.ssh/authorized_keys file of

a user on your instance, start a second SSH session
before you make any changes to the file and ensure that
it remains connected while you edit the file. If the
~/.ssh/authorized_keys file becomes corrupted or
you inadvertently make changes that lock you out of the
instance, you can use the backup SSH session to fix or
revert the changes. Before closing the backup SSH
session, test all changes you made by logging in with
the new or updated SSH key.
The new users then can SSH to the instance using the appropriate private keys.
To create an additional SSH-enabled user:
1. Generate an SSH key pair for the new user. See Managing Key Pairs on Linux Instances.
2. Copy the public key value to a text file for use later in this procedure.
3. Log in to your instance. See Connecting to an Instance.
4. Become the root user:
sudo su
5. Create the new user:

useradd <new_user>
6. Create a .ssh directory in the new user’s home directory:

mkdir /home/<new_user>/.ssh

CHAPTER 6 Compute
7. Copy the SSH public key that you saved to a text file into the /home/new_
user/.ssh/authorized_keys file:
echo <public_key> > /home/<new_user>/.ssh/authorized_keys
8. Change the owner and group of the /home/username/.ssh directory to the new user:
chown -R <new_user>:<group> /home/<new_user>/.ssh
9. To enable sudo privileges for the new user, run the visudo command and edit the
/etc/sudoers file as follows:
a. In /etc/sudoers, look for:
%<username> ALL=(ALL) NOPASSWD: ALL
b. Add the following line immediately after the preceding line:

%<group> ALL=(ALL) NOPASSWD: ALL
You can now log in as the new user.

CHAPTER 6 Compute
Creating Additional Users on a Windows Instance

To create a new user on a Windows Instance:
1. Log in to your instance using a Remote Desktop client.

2. On the Start menu, click Control Panel.
3. Click User Accounts, and then click User Accounts again.
4. Click Manage User Accounts.
5. Click Manage Another Account.
6. Click Add User Account.
7. Enter a User name and Password.
8. Confirm the password, and then create a Password hint.
9. Click Next.
10. Verify the account, and then click Finish.
You can now log in as the new user.
Displaying the Console for an Instance

You can capture and display the serial console data for an instance. The data includes
configuration messages that occur when the instance boots, such as kernel and BIOS
messages, and is useful for checking the status of the instance or diagnosing problems. Note
that the raw console data, including multi-byte characters, is captured.
Required IAM Policy


CHAPTER 6 Compute
For administrators: The policy in Let users launch instances includes the ability to manage
console history data. If the specified group doesn't need to launch instances or attach
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
Using the API

For information about using the API and signing requests, see About the API.
Use these API operations to manage the serial console logs:
l CaptureConsoleHistory
l DeleteConsoleHistory
l GetConsoleHistory
l GetConsoleHistoryContent
l ListConsoleHistories
Getting Instance Metadata

The metadata for an instance includes its OCID, display name, compartment, shape, region,
availability domain, creation date, state, image, and any custom metadata that you provide,
such as an SSH public key.
You can find some of this information in the Console on the Compute page, or you can get all
of it by logging in to the instance and using the metadata service. The service runs on every
instance and is an HTTP endpoint listening on 169.254.169.254.
Required IAM Policy

No IAM policy is required if you're logged in to the instance and using Curl to get the metadata
(see below).
For administrators: Users can also get instance metadata through the Compute API (e.g., with
GetInstance). The policy in Let users launch instances covers that ability. If the specified

CHAPTER 6 Compute
group doesn't need to launch instances or attach volumes, you could simplify that policy to
include only manage instance-family, and remove the statements involving volume-family
and virtual-network-family.
Accessing Instance Metadata on Oracle-Provided Images

You can get instance metadata on Oracle-provided images by using curl on Linux instances or
using an Internet browser for Windows instances.
Using Curl to Get Linux Instance Metadata

After you connect to an instance using SSH, issue any of the following GET requests. You'll get
back a response that includes all of the instance information, only the custom metadata, or
only the custom metadata for the specified key name, respectively.
curl http://169.254.169.254/opc/v1/instance/
curl http://169.254.169.254/opc/v1/instance/metadata/
curl http://169.254.169.254/opc/v1/instance/metadata/<key-name>
In the example <key-name>, is ssh_authorized_keys, user_data, or any custom key name

that you provided when you launched the instance. (For information about using the Core
Services API to provide user_data to Cloud-Init, see LaunchInstanceDetails.)
The following example shows all of the information for an instance.

{
"id" : "ocid1.instance.oc1.phx.abyhqljrkfpg67546xizk4welg3n4yft4hkud6hrdj5tietdnt7s4inffjoq",
"displayName" : "rprods",
"compartmentId" : "ocidv1:compartment:oc1:phx:1458865867564:aaaaaaaaatlpj4o3buxcblh2ou6e7izfgm",
"shape" : "x5-2.36.512",
"region" : "phx",
"availabilityDomain" : "cumS:PHX-AD-1",
"timeCreated" : "2016-04-18T20:02:38.383+0000",

CHAPTER 6 Compute
"state" : "RUNNING",
"image" : null,
"metadata": {
"ssh_authorized_keys" : "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCZ06fccNTQfq+JNL
xubFlJ5ZR3kt+uzspdH9tXL+lAejSM1NXPMZKQEo73rKpUUkN121BqL46yTI2JjfFwjJWMJlTkFo
M+CFZev7MIxfEjas06y80ZBZ7DUTQO0GxJPeD8NCOb1VorF8M4xuLwrmzRtkoZzU16umt4y1W0Q4
ifdp3IiiU0U8/WxczSXcUVZOLqkz5dc6oMHdMVpkimietWzGZ4LBBsH/LjEVY7E0V+a0sNchlVDI
Zcm7ErReBLcdTGDq0uLBiuChyl6RUkX1PNhusquTGwK7zc8OBXkRuubn5UKXhI3Ul9Nyk4XESkVW
IGNKmw8mSpoJSjR8P9ZjRmcZVo8S+x4KVPMZKQEo73rKpUUkN121BqL46yTI2JjfFwjJWMJlTkFo
EjRVJ/jf4IythUnkW5RA/2mgu79kbwqPM90J8pRKyjWehl8VsN5wUY+mZQ3jzIfeC9qNKjn5e976
4DFhvw35JHh5sHyzyLVuyLe3teZ6kRUKyQqA9Oy4DMctmbD1uDAz73tWbvdz7SmfWJ5QZ7/Aod0a
Gce6FJS/srWfB+7f/+SX+fu926LqlJa/3r/AGS4IvDfEKvtZCWgTPVrEHVSTuEiDzG9yBuJLZ95J
2AMmeKhnFOKpAsoWVN5kV55RmmQVJaozQHr7V+FaGc8IHDs95vgz4F3AJTi+xl3cvr+6vlfDJNse
c/jRx/+XZynrpltFGvTAUaqXJFowow== it.helps@company.com",
"user_data" : "SWYgeW91IGNhbiBzZWUgdGhpcywgdGhlbiBZdCB3b3JrZWQgbWF5YmUuCg=="
}
Using an Internet Browser to Get Windows Instance Metadata

After you connect to a Windows instance, you can open an Internet browser such as Microsoft
Edge or Internet Explorer, Google Chrome, or Mozilla Firefox, and then navigate to the
following URLs:
l http://169.254.169.254/opc/v1/instance/
l http://169.254.169.254/opc/v1/instance/metadata/
l http://169.254.169.254/opc/v1/instance/metadata/<key-name>
In the example <key-name>, is user_data or any custom key name that you provided when
you launched the instance.
Renaming an Instance
You can rename an instance without changing its Oracle Cloud Identifier (OCID).

CHAPTER 6 Compute
Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to rename an
instance. If the specified group doesn't need to launch instances or attach volumes, you could
simplify that policy to include only manage instance-family, and remove the statements
involving volume-family and virtual-network-family.
Using the API

Use the UpdateInstance operation to change the name of an instance.
Stopping and Starting an Instance

You can stop and start an instance as needed to update software or resolve error conditions.

CHAPTER 6 Compute
Tip
Oracle recommends that you run a Network Time

Protocol (NTP) daemon to keep system clocks stable
during rebooting. If you need information about an NTP
daemon, see Setting Up “NTP (Network Time Protocol)
Server” in RHEL/CentOS 7.
Stopping or Restarting an Instance From Within the Instance

In addition to using the API and Console, you can stop and restart instances using the
commands available in the operating system when you are logged in to the instance. Be
aware of the following caveats before stopping or restarting an instance from within the
instance:
l You should never shut down a VM instance from within the instance (for example,
running shutdown -h now while logged in to the instance). You will not be able to
restart it, even using the API or the Console.
l The stop and restart actions that you perform within the instance are not reflected in the
instance state in the API or Console.
Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to stop or start
an existing instance. If the specified group doesn't need to launch instances or attach

CHAPTER 6 Compute
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
Using the Console

1. Open the Console, click Compute, choose your Compartment, and then click
Instances (if necessary).
2. In the list of instances, find the instance you want to stop or start, and then click the
instance name to display the instance details.
3. Click one of the following actions:
START
Restarts a stopped instance. After the instance is restarted, the Stop action is
enabled.
STOP
Shuts down the instance. After the instance is powered off, the Start action is
enabled.
REBOOT
Shuts down the instance, and then restarts it.

CHAPTER 6 Compute
Note
Resource Billing
For standard VM and BM instances, stopping an

instance pauses billing for that instance. However,
these instances continue to count toward any
relevant quotas.
Billing continues for high I/O BM instances and
dense I/O BM and VM instances that you stop, and
related resources continue to apply against any
relevant quotas. You must terminate these
instances to remove their resources from billing
and quotas. See Terminating an Instance.
Using the API

Use the InstanceAction operation to restart an instance.
Terminating an Instance
You can permanently terminate (delete) instances that you no longer need. Any attached
VNICs and volumes are automatically detached when the instance terminates. Eventually, the
instance's public and private IP addresses are released and become available for other
instances. By default, the instance's boot volume is deleted when you terminate the instance,
however you can preserve the boot volume associated with the instance, so that you can
attach it to a different instance as a data volume, or use it to launch a new instance.

CHAPTER 6 Compute
Warning
If your instance has NVMe storage, terminating it

securely erases the NVMe drives and the data that was
on those drives becomes completely unrecoverable.
Make sure you back up important data before
terminating an instance. For more information, see
Protecting Data on NVMe Devices.
Required IAM Policy

For administrators: The policy in Let users launch instances includes the ability to terminate
an instance (with or without an attached block volume).
Using the Console

1. Open the Console, click Compute, and then choose your Compartment.
2. In the list of instances, find the instance you want to terminate.
3. Click the highlighted name of the instance to display the instance details.

CHAPTER 6 Compute
4. Click Terminate, and then respond to the confirmation prompt.

If you want to preserve the boot volume associated with the instance, uncheck
Permanently delete the attached Boot Volume.
Terminated instances temporarily remain in the list of instances with the status
Terminated.
Using the API

Use the TerminateInstance operation to terminate an instance.
Compute Performance
The content in the sections below apply to Category 7 and Section 3.a of the Oracle PaaS
Oracle Cloud Infrastructure provides a variety of instance configurations in both bare metal
and virtual machine (VM) shapes. Each shape varies on multiple dimensions including
memory, CPU cores, network bandwidth, and the option of local NVMe SSD storage found in
DenseIO shapes.
Oracle Cloud Infrastructure provides a service-level agreement (SLA) for NVMe performance.
Measuring performance is complex and open to variability.
A NVMe drive also has non-uniform drive performance over the period of drive usage. A NVMe
drive performs differently when tested brand new compared to when tested in a steady-state
after some duration of usage. New drives have not incurred many write/erase cycles and the
inline garbage collection has not had a significant impact on IOPS performance. To achieve
the goal of reproducibility and reduced variability, our testing focuses on the steady-state
duration of the NVMe drive’s operation.

CHAPTER 6 Compute
Testing Methodology
Warning
Before running any tests, protect your data by making a

backup of your data and operating system environment
to prevent any data loss. The tests described in this
document will overwrite the data on the disk, and cause
data corruption.
Summary: To capture the IOPS measure, first provision a shape such as the new
BM.DenseIO2.52, and then use the Gartner Cloud Harmony test suite to run tests on an
instance running the latest supported Oracle Linux image for each NVMe drive target.
Instructions:
1.
Launch an instance based on the latest supported Oracle Linux image and select a shape
such as the new BM.DenseIO2.52. For launch instructions, see Launching an Instance.
2. Run the Gartner Cloud Harmony test suite tests on the instance for each NVMe drive
target. The following is an example of a command that will work for all shapes and
drives on the shape:
sudo ./run.sh `ls /dev/nvme[0-9]n1 | sed -e 's/\//\--target=\//'`
--nopurge –noprecondition --fio_direct=1 --fio_size=10g --test=iops
--skip_blocksize=512b --skip_blocksize=8k --skip_blocksize=16k
--skip_blocksize=32k --skip_blocksize=64k --skip_blocksize=128k
--skip_blocksize=1m
The SLA for NVMe drive performance is measured against 4k block sizes with 100% random
write workload on DenseIO shapes where the drive is in a steady-state of operation.

CHAPTER 6 Compute
Performance Benchmarks
The following table lists the minimum IOPS for the specified shape to meet the SLA, given the
testing methodology with 4k block sizes for 100% random write tests using the tests
described in the previous section.
Shape Minimum Supported IOPS
VM.DenseIO1.4 200k
VM.DenseIO1.8 250k
VM.DenseIO1.16 400k
BM.DenseIO1.36 2.5MM
VM.DenseIO2.8 250k
VM.DenseIO2.16 400k
VM.DenseIO2.24 800k
BM.DenseIO2.52 3.0MM
While the NVMe drives are capable of higher IOPS, Oracle Cloud Infrastructure currently
guarantee this minimum level of IOPS performance.
Frequently Asked Questions

Q: I suspect a slowdown in my NVMe drive performance. Is there a SLA violation?
A: We test hosts on a regular basis to ensure that are our low-level software updates do not
regress performance. In the event you have reproduced the testing methodology and your
drive’s performance does not meet the terms in the SLA please contact your Oracle sales
team.

CHAPTER 6 Compute
Q: Why does the testing methodology not represent a diversity of IO workloads such as
random reads and writes to reflect real world IO?
A: We focused on reproducibility and we believe the tests provide a significant indicator of

overall drive performance.
Q: Will Oracle Cloud Infrastructure change the tests in this document?
A: We will make changes to provide greater customer value through better guarantees and
improved reproducibility.

CHAPTER 7 Data Transfer
This chapter explains how to migrate data to Oracle Cloud Infrastructure using Data Transfer
service.
Overview of Data Transfer

Data Transfer service is an offline data transfer solution that lets you migrate large volumes
of data to Oracle Cloud Infrastructure. Moving a large amount of data over the wire is not
always feasible due to poor or unreliable network connectivity or the length of time it would
take to move the data into the cloud. The Data Transfer service is a simple and secure
solution that overcomes these challenges. You can transfer hundreds of TB of data on
commodity hard disk drives (HDDs) and ship these drives to an Oracle transfer site. Oracle
operators then upload your data into your Oracle Cloud Infrastructure tenancy. Data Transfer
service provides significantly faster data upload compared to over-the-wire data transfer.
Data Transfer Concepts

The following concepts are essential to understanding Data Transfer service.
TRANSFER DEVICE
A transfer device is your HDD that is specially prepared to copy and upload data to Oracle
Cloud Infrastructure. You copy your data onto one or more of these devices and ship them in
a parcel to Oracle to upload.
The HDD can be one the following:
l An internal SATA II/III 2.5" or 3.5" drive

l An external USB 2.0/3.0 HDD
TRANSFER PACKAGE
A transfer package is the logical representation of the parcel containing the HDD transfer
devices that you ship to Oracle to upload to Oracle Cloud Infrastructure.

TRANSFER JOB
A transfer job is the logical representation of a data migration to Oracle Cloud

Infrastructure. A transfer job consists of one or more transfer packages that each contain
one or more transfer devices.
DATA TRANSFER UTILITY

The Data Transfer Utility is the software Oracle provides for you to prepare transfer
devices for shipment to Oracle. In addition, you can use this software to manage transfer
jobs and packages.
HOST
The computer at your site on which you download the Data Transfer Utility to prepare your
transfer devices.
BUCKET
The logical container in Oracle Cloud Infrastructure Object Storage where Oracle
operators will upload your data. A bucket is associated with a single compartment in your
tenancy that has policies that determine what actions a user can perform on a bucket and
on all the objects in the bucket.
DATA TRANSFER ADMINISTRATOR
A new or existing IAM user that has the authorization and permissions to create and
manage transfer jobs. See Authentication and Authorization later in this topic.
DATA TRANSFER UPLOAD USER
A temporary IAM user that grants Oracle personnel the authorization and permissions to
upload the data from your transfer devices to your designated Oracle Cloud Infrastructure
Object Storage bucket. You should delete this temporary user once you data is uploaded
to Oracle Cloud Infrastructure. See Authentication and Authorization later in this topic.
Task Flow for Data Transfer Service

Here is a high-level overview of the tasks involved in transferring data to Oracle Cloud
Infrastructure. These tasks are covered in greater detail in Preparing for Data Transfers and

Managing HDD Data Transfers.
Performing prerequisite tasks in preparation for transfer data:
1. Create or designate a bucket in your tenancy to upload the transferred data.

2. Create or use an existing IAM group for data transfer administrators with the
authorization and permissions to create and manage transfer jobs and manage objects
in Oracle Cloud Infrastructure Object Storage.
3. Create or use an existing IAM data transfer administrator user and add that user to the
data transfer administrators group.
4. Create or use an existing IAM group for data transfer upload users with the
authorization and permissions to upload data to Oracle Cloud Infrastructure Object
Storage.
5. Create a temporary IAM data transfer upload user and add that user to data transfer
upload user group.
6. Write the authorization policies to allow the data transfer administrator and upload user
groups to perform the required data transfer tasks.
Important
For security reasons, we recommend that you create a

unique IAM data transfer upload user for each transfer
job and then delete that user once your data is uploaded
to Oracle Cloud Infrastructure.
Preparing for and copying your data:
1. Install the Data Transfer Utility on your host machine.

2. Create a transfer job using the Console or the Data Transfer Utility.
3. Attach HDDs to your host machine.
4. Create transfer devices using the Data Transfer Utility.
5. Copy your data to the transfer devices.

Finalizing the transfer devices in preparation for shipment:
1. Generate a manifest for each transfer device using the Data Transfer Utility.
2. Generate the "dry run" report for each transfer device using the Data Transfer Utility.
3. Lock each transfer device using the Data Transfer Utility.
Preparing and shipping the package:
1. Create one or more transfer packages using the Console or the Data Transfer Utility.
2. Attach the transfer devices to the transfer packages using the Console or the Data
Transfer Utility.
3. Get the shipping address for the transfer packages using the Console or the Data
Transfer Utility.
4. Package the transfer devices into a box, and ship the box using an approved shipping
vendor.
Secure Data Transfer to Oracle Cloud Infrastructure

This section highlights the security details of the data transfer process.
l The Data Transfer Utility uses the standard Linux dm-crypt and LUKS utilities to encrypt
block devices.
l The dm-crypt software generates a master AES-256 bit encryption key that it uses for
all data written to or read from the device. That key is protected by an encryption
passphrase that the user must know to access the encrypted data.
l When the data transfer administrator uses the Data Transfer Utility to create devices,
Oracle Cloud Infrastructure creates a very strong encryption passphrase that is
displayed to the user and passed to dm-crypt. The passphrase is displayed to standard
output only once and cannot be retrieved again. Copy this passphrase to a durable,
secure location for future reference.
l All network communication between the Data Transfer Utility and Oracle Cloud
Infrastructure is encrypted in-transit using Transport Layer Security (TLS).

l After copying your data to the transfer devices, you generate a manifest file for each
device using the Data Transfer Utility. The manifest contains an index of all of the
copied files, as well as generated data integrity hashes. The Data Transfer Utility also
encrypts and copies the config_upload_user configuration file to each transfer device.
This configuration file describes the temporary IAM data transfer upload user you create
in step 5 of the "Performing prerequisite tasks in preparation for transfer data" section.
Oracle uses the credentials and entries defined in the config_upload_user file when
processing the transfer device to upload files from the HDD to Oracle Cloud
Infrastructure Object Storage. Oracle cannot upload data from the transfer devices
without the correct credentials defined in this configuration file. See Data Transfer
Utility for detailed information about the required configuration files.
l After copying your data to a transfer device, you need to generate a manifest file using
the Data Transfer Utility. The manifest contains an index of all of the copied files, as
well as generated data integrity hashes. The Data Transfer Utility also encrypts and
copies the config_upload_user configuration file to the transfer device. This
configuration file describes the temporary IAMdata transfer upload user you create in
step 5 of the "Performing prerequisite tasks in preparation for transfer data" section.
Oracle uses the credentials and entries defined in the config_upload_user file when
processing the transfer device to upload files from the HDD to Oracle Cloud
Infrastructure Object Storage.

Note
Data Transfer Service Does Not Support Passphrases on

Private Keys
While we recommend encrypting a private key with

a passphrase when generating API signing keys,
Data Transfer service does not support passphrases
on the key file required for the config_upload_user.
If you use a passphrase, Oracle personnel will not
be able to upload your data.
Oracle cannot upload data from the transfer devices without the correct credentials
defined in this configuration file. See Data Transfer Utility for more information about
the required configuration files.
l When you disconnect or lock a transfer device using the Data Transfer Utility, the
original encryption passphrase is required to once again access the device. If the
encryption passphrase is not known or lost, you cannot access the data on the transfer
device. To reuse a transfer device, you must reformat the device and any data on that
device will be lost.
l Oracle retrieves the encryption passphrase for a transfer device from Oracle Cloud
Infrastructure. Oracle uses the passphrase to decrypt, mount the transfer device, and
upload the data to the designated bucket in the tenancy.
l After processing a transfer package, Oracle returns all transfer devices attached to the
transfer package using the return shipping label you provide. Oracle returns the transfer
devices in the same encrypted condition that they were received.

Ways to Manage Data Transfer

We provide two ways to manage data transfers:
l The Data Transfer Utility is a full-featured command-line tool. For more information and
installation instructions, see Data Transfer Utility.
l The Console is an easy-to-use, partial-featured browser-based interface. For more
information, see Signing In to the Console.
Note
Using the Management Interfaces
You can perform many data transfer tasks using either

the Console or the Data Transfer Utility. However, there
are some tasks you can only perform using the Data
Transfer Utility (for example, creating and locking
transfer devices). Managing HDD Data Transfers
describes the management tasks in detail and guides
you to the appropriate management interface to use for
each task

authorization.

See Preparing for Data Transfers for specific information about the policies required for data
transfer. If you're new to policies, see Getting Started with Policies and Common Policies.
Limits on Data Transfer Resources

increase.
Using Data Transfer

If you are ready to transfer data, you can find more information in the following topics:
l For information about installing and using the Data Transfer Utility, see Data Transfer
Utility.
l For information on performing prerequisite tasks for data transfer, see Preparing for
Data Transfers.
l For task documentation related to HDD data transfer, see Managing HDD Data
Transfers.
l For instructions on how to create a bucket, see "Putting Data into Object Storage" in the
Oracle Cloud Infrastructure Getting Started Guide.
Preparing for Data Transfers

An Oracle Cloud Infrastructure administrator must perform prerequisite tasks in preparation
for data transfer. If you are new to Oracle Cloud Infrastructure, we recommend that you read
Setting Up Your Tenancy.
Creating the Required IAM Users, Groups, and Policies


Access to resources is provided to groups using policies and then inherited by the users that
are assigned to those groups. Data transfer requires the creation of two distinct groups. One
group is for data transfer administrators who can create and manage transfer jobs. Another
group is for data transfer upload users who can upload data to Object Storage. For details on
creating groups, see Managing Groups.
An administrator creates these groups with the following policies:
l The data transfer administrator group requires an authorization policy that includes the
following:
Allow group <group_name> to manage data-transfer-jobs in compartment <compartment_name>
Allow group <group_name> to manage objects in compartment <compartment_name>
l The data transfer upload user group requires an authorization policy that includes the
following:
Allow group <group_name> to manage buckets in compartment <compartment_name> where all {
request.permission='BUCKET_READ' }
Allow group <group_name> to manage objects in compartment <compartment_name> where any {

request.permission='OBJECT_CREATE' , request.permission='OBJECT_OVERWRITE' ,
request.permission='OBJECT_INSPECT' }
Important
For security reasons, we recommend that you create a

unique IAM data transfer upload user for each transfer
job and then delete that user once your data is uploaded
to Oracle Cloud Infrastructure.
The Oracle Cloud Infrastructure administrator then adds a user to each of the data transfer
groups created. For details on creating users, see Managing Users.

Creating the Required Object Storage Bucket

The Object Storage service is used to upload your data to Oracle Cloud Infrastructure. Object
Storage stores objects in a container called a bucket within a compartment in your tenancy.
For details on creating the bucket to store uploaded data, see Managing Buckets.
Installing the Data Transfer Utility

The Data Transfer Utility is a command-line utility that you install on your host machine. The
utility lets you perform all data transfer-related tasks, including creating and managing
transfer jobs, transfer devices, and transfer packages. This utility is required to perform
certain data transfer tasks that cannot be performed using the Console. See Data Transfer
Utility for detailed installation and configuration instructions.
Managing HDD Data Transfers

The Data Transfer service uses commodity hard disk drives (HDDs) to transfer data. You send
your data as files on encrypted HDDs to an Oracle transfer site. Operators at the Oracle
transfer site upload the files into your designated Object Storage bucket in your tenancy. You
are then free to move the uploaded data to other Oracle Cloud Infrastructure services as
needed. In preparation for data migration, an IAM user that has administrative authorization
and permissions must perform the prerequisite tasks described in Preparing for Data
Transfers.
Many data transfer tasks can be performed either using the Console or using the Data
Transfer Utility. However, some data transfer tasks can only be performed using the Data
Transfer Utility. This document guides you to the appropriate management interface to use for
each task.
The Data Transfer Utility must be run as the root user because this utility formats, encrypts,
and mounts HDDs.

Creating a Transfer Job
Tip
You can use the Console or the Data Transfer Utility to

create a transfer job.
A transfer job represents the collection of files that you want to transfer and signals the
intention to upload those files to Oracle Cloud Infrastructure. A transfer job combines at least
one transfer device with a transfer package. You must know which compartment and Object
Storage bucket the data will be uploaded to. You must also create the transfer job in the same
compartment as the upload bucket and supply a human-readable name for the transfer job.
Avoid entering confidential information when providing job names.
Creating a transfer job returns a job ID that you will use in other transfer tasks. For example:
ocid1.datatransferjob.region1.phx.aaaaaaaag3maq2ufbygw243vw5hkz7mnayyt2zb6v6y5weidmpjhha5e26va
To create a transfer job using the Console

1. Open the Console, click Storage, and then click Data Transfer.
2. Select a compartment from the drop-down list.
A list of transfer jobs that have already been created is displayed.
3. Click Create Transfer Job.
4. In the Create Transfer Job dialog, enter the Job Name and select the Upload
Bucket from the drop-down list.
Avoid entering confidential information in the job name.
5. Click Create Transfer Job.
To create a transfer job using the Data Transfer Utility

At the command prompt on the host, run dts job create to create a transfer job.

dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name>
Where <display_name> is the name of the transfer job. Avoid entering confidential
information in the job name.
Performing Other Transfer Job Tasks
Tip

perform other transfer job-related tasks.
Displaying the List of Transfer Jobs
To display the list of transfer jobs using the Console

Open the Console, click Storage, and then click Data Transfer to display the list of transfer
jobs.
To display the list of transfer jobs using the Data Transfer Utility
At the command prompt on the host, run dts job list to display the list of transfer jobs.
dts job list --compartment-id <compartment_id>
Displaying the Details of a Transfer Job
To display the details of a transfer job using the Console

2. Find the transfer job for which you want to display the details.

3. Click the Actions icon ( ), and then click View Details.
To display the details of a transfer job using the Data Transfer Utility
At the command prompt on the host, run dts job show to display the details of a transfer
job.
dts job show --job-id <job_id>
Editing a Transfer Job
To edit the name of a transfer job using the Console

2. Find the data transfer job that you want to edit.
3. Click the Actions icon ( ), and then click Edit.
4. Edit the name of the transfer job. Avoid entering confidential information.
5. Click Save.
To edit the name of a transfer job using the Data Transfer Utility
At the command prompt on the host, run dts job update to edit the name (--display-name)
of a transfer job.
dts job update --job-id <job_id> --display-name <display_name>
Avoid entering confidential information in the job name.
Deleting a Transfer Job
Typically, you would delete a transfer job early in the transfer process and before you create
any transfer packages or devices. For example, you initiated the data transfer by creating a
transfer job, but changed your mind. If you want to delete a transfer job later in the transfer

process, you must first delete all transfer packages and devices associated with the transfer
job.
To delete a transfer job using the Console

2. Find the data transfer job that you want to delete.
Alternatively, you can delete a transfer job from the View Details page.
4. Confirm the deletion when prompted.
To delete a transfer job using the Data Transfer Utility

At the command prompt on the host, run dts job delete to delete a transfer job.
dts job delete --job-id <job_id>
Attaching HDDs to the Host Machine

Before creating a transfer device from an attached HDD, remove all partitions and any file
systems. To prevent the accidental deletion of data, the Data Transfer Utility will not work
with HDDs that already have partitions or file systems on them. HDDs are visible to the host
as block devices and must provide a valid response to the hdparm -I <device> Linux
command.
A device can be attached to one package, detached, and then attached to another package.

Creating a Transfer Device
Tip
You can only use the Data Transfer Utility to create a

transfer device.
When you create a transfer device, the Data Transfer Utility:
l Sets up the HDD for encryption using the passphrase

l Creates a file system on the HDD
l Mounts the file system at /mnt/orcdts_<device_label>
For example:
/mnt/orcdts_DJZNWK3ET
Registering a transfer device encrypts the HDD and generates a strong encryption
passphrase. The encryption passphase is displayed to standard output to the data transfer
administrator user and cannot be retrieved again. Create a local, secure copy of the
encryption passphrase, if you need to reference the passphrase again.
Creating a transfer device requires the job ID returned from when you created the transfer
job and the path to the attached HDD (for example, /dev/sdb).
To create a transfer device using the Data Transfer Utility

At the command prompt on the host, run dts device create to create a transfer device.
dts device create --job-id <job_id> --block-device <block_device>

Performing Other Transfer Device Tasks
Tip
You can only use the Data Transfer Utility to delete or

cancel a transfer device.
Deleting a Transfer Device
Typically, you would delete a transfer device during the device preparation process. You
created, attached, and/or copied data to the transfer device, but have changed your mind
about shipping the device. If you want to reuse the device, remove all file systems and create
the device again.
To delete a transfer device using the Data Transfer Utility

At the command prompt on the host, run dts device delete to delete a transfer device.
dts device delete --job-id <job_id> --device-label <device_label>
Canceling a Transfer Device
You would cancel a transfer device if you shipped this device to Oracle, but have changed your
mind about uploading the files. You can cancel a device in a transfer package, while allowing
the file upload from other devices.
Oracle cannot process canceled transfer devices. Oracle returns canceled transfer devices to
the sender.
To cancel a transfer device using the Data Transfer Utility

At the command prompt on the host, run dts device cancel to cancel a transfer device.
dts device cancel --job-id <job_id> --device-label <device_label>

Copying Data to the Transfer Device

Attach the HDDs to the host machine and copy files to the mount point created by the Data
Transfer Utility.
You can only copy regular files to transfer devices. Special files (links, sockets, pipes, etc.)
cannot be copied directly. If you need to transfer special files, create a tar archive of the files
and copy the tar archive to the transfer device.
Note
Copy all Files Before Disconnecting a Transfer Device
Do not disconnect a transfer device until you copy all

files from the host and generate the manifest file. If you
accidentally disconnect the transfer device before
copying all files, you must unlock the device using the
encryption passphrase. The encryption passphrase was
generated and displayed when you created the transfer
device. If the generated encryption passphrase is not
available, you must delete the transfer device from the
transfer job and re-create the device. All data
previously copied to that transfer device is lost.

Generating a Manifest File
Tip
You can only use the Data Transfer Utility to generate a

manifest file.
The time it takes to generate the manifest file depends
on the size of the upload files, disk speed, and available
processing power.
After copying your data to a transfer device, you need to generate a manifest file using the
Data Transfer Utility. The manifest contains an index of all of the copied files, as well as
generated data integrity hashes. The Data Transfer Utility also encrypts and copies the
config_upload_user configuration file to the transfer device. This configuration file
describes the temporary IAMdata transfer upload user you create in step 5 of the "Performing
prerequisite tasks in preparation for transfer data" section. Oracle uses the credentials and
entries defined in the config_upload_user file when processing the transfer device to upload
files from the HDD to Oracle Cloud Infrastructure Object Storage.
Note
Data Transfer Service Does Not Support Passphrases on Private

Keys
While we recommend encrypting a private key with a

passphrase when generating API signing keys, Data
Transfer service does not support passphrases on the
key file required for the config_upload_user. If you use
a passphrase, Oracle personnel will not be able to
upload your data.

Oracle cannot upload data from the transfer devices without the correct credentials defined in
this configuration file. See Data Transfer Utility for more information about the required
configuration files.
To create a manifest file using the Data Transfer Utility

At the command prompt on the host, run dts device create to create a transfer device.
dts device manifest --job-id <job_id> --device-label <device_label> [--object-name-prefix <object_
name_prefix>]
Note
Do You Need to Regenerate the Manifest File?
If you modify an HDD after the manifest file is

generated, you must regenerate the manifest again or
Oracle will not be able to upload the HDD.
Generating a Dry-Run Report of the Transfer
Tip
You can only use the Data Transfer Utility to generate a

dry-run report.
You can generate a dry-run report to review the transfer results before the actual data upload.
The report compares the contents of the generated manifest file with the contents of the
target bucket. This report can help determine if you have duplicate files or naming collision
issues.

Note
Do You Need to Regenerate the Manifest File?
If you review the dry-run report and add, remove, or

modify any files on the HDD, you must regenerate the
manifest file or Oracle will not be able to upload the
HDD.
To generate a dry-run report

At the command prompt on the host, run dts device dry-run to generate a dry-run report of
the transfer device.
dts device dry-run --job-id <job_id> --device-label <device_label>
Locking a Transfer Device
Tip
You can only use the Data Transfer Utility to lock a

transfer device.
Locking a transfer device safely unmounts the HDD and removes the encryption passphrase
from the host. You will be prompted for the encryption passphrase when you lock the transfer
device.
If you need to unlock the transfer device again, you need the encryption passphrase that was
generated when you created the transfer device.

To lock a transfer device using the Data Transfer Utility

At the command prompt on the host, run dts device lock to create a transfer device.
dts device lock --job-id <job_id> --device-label <device_label> --block-device <block_device>
Creating a Transfer Package
Tip

create a transfer package.
Creating a transfer package initiates the paperwork required for shipping the HDDs to Oracle
and tracks the associated transfer devices and shipment information.
Creating a transfer package requires the job ID returned from when you created the transfer
job. For example:
ocid1.datatransferjob.region1.phx.aaaaaaaag3maq2ufbygw243vw5hkz7mnayyt2zb6v6y5weidmpjhha5e26va
To create a transfer package using the Console

2. Find the transfer job for which you want to create a transfer package.
Alternatively, click on the hyper-linked name of the transfer job.
A list of transfer packages that have already been created is displayed.
4. Click Create Transfer Package.
5. In the Create Transfer Package dialog, choose the Vendor.
6. Click Create Transfer Package.

To create a transfer package using the Data Transfer Utility

At the command prompt on the host, run dts package create to create a transfer package.
dts package create --job-id <job_id>
Performing Other Transfer Package Tasks
Tip

perform other transfer package-related tasks.
Displaying the Details of a Transfer Package
To display the details of a transfer package using the Console

2. Find the transfer job for which you want to see the details.
To display the details of a transfer package using the Data Transfer Utility
At the command prompt on the host, run dts package show to display the details of a
transfer package.
dts package show --job-id <job_id> --package-label <package_label>

Editing a Transfer Package
You will need to edit the transfer package and supply the tracking information when you ship
the package.
To edit a transfer package using the Console

2. Find the transfer job for which you want to see the associated transfer packages.
4. Find the transfer package that you want to edit.
6. Click Edit.
Change the vendor and supply the tracking information as needed.
7. Click Edit Transfer Package.
To edit a transfer package using the Data Transfer Utility

At the command prompt on the host, run dts package update to edit the details of a transfer
package.
dts package update --job-id <job_id> --package-label <package_label> [--package-vendor <vendor_name>]
[--tracking-number <tracking_number>] [--return-tracking-number <return_tracking_number>]
Deleting a Transfer Package
Typically, you would delete a transfer package early in the transfer process and before you
created any transfer devices. You initiated the transfer job and package, but have changed
your mind. If you delete a transfer package later in the transfer process, you must first delete
all associated transfer devices. You cannot delete a transfer package once the package has
been shipped to Oracle.

To delete a transfer package using the Console

6. Click Edit.
Change the vendor and supply the tracking information as needed.
To delete a transfer package using the Data Transfer Utility

At the command prompt on the host, run dts package delete to delete a transfer package.
dts package delete --job-id <job_id> --package-label <package_label>
Canceling a Transfer Package
You would cancel a transfer package if you have shipped the transfer package, but have
changed your mind. You must cancel all transfer devices associated with the transfer package
before you can cancel the transfer package. Oracle cannot process canceled transfer
packages. Oracle returns canceled transfer packages to the sender.
To cancel a transfer package using the Console

2. Find the transfer job for which you want to see associated transfer packages.
4. Find the transfer package that you want to cancel.

6. Click Cancel Transfer Package.
To cancel a transfer package using the Data Transfer Utility

At the command prompt on the host, run dts package cancel to cancel a transfer package.
dts package cancel --job-id <job_id> --package-label <package_label>
Attaching Transfer Devices to a Transfer Package
Tip

attach a transfer device to a transfer package.
You attach a transfer device to a transfer package after you have copied your data onto the
device, generated the required manifest file, run and reviewed the dry-run report, and then
locked the transfer device in preparation for shipment.
To attach a transfer device to a transfer package using the Console

2. Find the transfer job associated with the transfer package that you want to attach a
device to.
A list of transfer packages is displayed.
4. Find the transfer package that you want to attach a device to.
Alternatively, click on the hyper-linked name of the transfer package.
A list of transfer devices is displayed.

6. Click Attach Transfer Devices.

7. Click Attach Transfer Devices.
8. In the Attach Transfer Device dialog, select the Transfer Devices that you want to
attach to the transfer package.
9. Click Attach.
To attach a transfer device to a transfer package using the Data Transfer

Utility
At the command prompt on the host, run dts device attach to attach a device to a transfer
package.
dts device attach --job-id <job_id> --package-label <package_label> --device-label <device_label>
You have attached a transfer device to a transfer package, but have changed your mind about
shipping that device with the transfer package. You can also detach a transfer device from one
transfer package and attach that device to a different transfer package.
To detach a transfer device to a transfer package using the Console

2. Find the transfer package for which you want to detach a transfer device.
Alternatively, click on the hyper-linked name of the transfer package.
A list of transfer devices that have already been attached is displayed.
4. Find the transfer device that you want to detach.
Alternatively, click on the hyper-linked name of the transfer device.
6. Click Detach Transfer Device.

To detach a transfer device to a transfer package using the Data Transfer

Utility
At the command prompt on the host, run dts device attach to attach a device to a transfer
package.
dts device attach --job-id <job_id> --package-label <package_label> --device-label <device_label>
Getting the Shipping Address for the Transfer Package
Tip

get the shipping address for a transfer package.
You can find the shipping address in the transfer package details.
To get the shipping address for a transfer package using the Console
2. Find the transfer job for which you want to see the details.
4. Find the transfer package for which you want to see the details.

To get the shipping address for a transfer package using the Data Transfer
Utility
At the command prompt on the host, run dts package show to get the shipping address for a
transfer package.
dts package show --job-id <job_id> --package-label <package_label>
Packaging and Shipping Transfer Devices

Ensure that the transfer job and transfer package label are clearly readable on the outside of
the box containing the transfer devices.
Include the required return shipping label in the box when packaging transfer devices for
shipment.
Note
Return Shipment Label Requirement
Oracle cannot process the transfer package if there is

no return label included the transfer package.
Updating the Transfer Package With Tracking Information
Tip

update the transfer package with tracking information.
After delivering the transfer package to the shipping vendor, update the transfer package with
the tracking information.

To update the transfer package with tracking information using the Console
6. Click Edit.
7. Enter the Tracking ID and the Return Tracking ID.
To update the transfer package with tracking information using the Data
Transfer Utility
At the command prompt on the host, run dts package ship to update the transfer package
tracking information.
dts package ship --job-id <job_id> --package-label <package_label> --package-vendor <vendor_name> --
tracking-number <tracking_number> --return-tracking-number <return_tracking_number>
Checking the Transfer Package Status
Tip

check the status of a transfer package.
When Oracle has processed the transfer devices associated with a transfer package, the
status of the transfer package changes to Processed. When Oracle has shipped the transfer

devices associated with a transfer package, the status of the transfer package changes to
Returned.
To check the status of a transfer package using the Console

2. Choose the data transfer package for which you want to display the details.
4. Look at the Status.
To check the status of a transfer package using the Data Transfer Utility
At the command prompt on the host, run dts package show to show the status of a transfer
package.
dts package show --job-id <job_id> --package-label <package_label> --device-label <device_label>
Reviewing the Log Files for Each Transfer Device

Oracle creates log files for each transfer device uploaded. The logs are placed in the bucket
where the transfer device data was uploaded. The log files compares the transfer device's
manifest file to the contents of the target Oracle Cloud Infrastructure Object Storage bucket
after file upload.
The top of the log report summarizes the overall file processing status:
P - Present: The file is present in both the device and the target bucket
M - Missing: The file is present in the device but not the target bucket. It was likely uploaded and
then deleted by another user before the summary was generated.
C - Name Collision: The file is present in the manifest but a file with the same name but different
contents is present in the target bucket.
U - Unreadable: The file is not readable from the disk
N - Name Too Long: The file name on disk is too long and could not be uploaded
Complete file upload details follow the summary.

Closing a Transfer Job
Tip

close a transfer job.
Typically, you would close a transfer job when no further transfer job activity is required or
possible. Closing a transfer job requires that the status of all associated transfer packages be
returned, canceled, or deleted. In addition, the status of all associated transfer devices must
be complete, in error, missing, canceled, or deleted.
To close a transfer job using the Console

2. Find the data transfer package for which you want to display the details.
4. Click Close Transfer Job.
To close a transfer job using the Data Transfer Utility

At the command prompt on the host, run dts job close to close a transfer job.

dts job close --job-id <job_id>

CHAPTER 8 Database
This chapter explains how to launch a DB System and manage databases on DB Systems.
Overview of the Database Service

The Database service lets you quickly launch an Oracle Database System (DB System) and
create one or more databases on it. You have full access to the features and operations
available with Oracle Database, but Oracle owns and manages the infrastructure.
The Database service supports several types of DB Systems, ranging in size, price, and
performance. For details about each type of system, start with the following topics.
l Exadata DB Systems
l Bare Metal and Virtual Machine DB Systems
The following sections apply to all types of DB Systems.
License Types
Oracle Cloud Infrastructure supports a licensing model with two license types. With License
included, the cost of the cloud service includes a license for the Database service. With
Bring Your Own License (BYOL), Oracle Database customers with an Unlimited License
Agreement or Non-Unlimited License Agreement can use their license with Oracle Cloud
Infrastructure. You do not need separate on-premises licenses and cloud licenses. BYOL DB
instances support all advanced Database service manageability functionality, including
backing up and restoring a DB system, patching, and Oracle Data Guard.
You can enable BYOL when you launch a DB system. Enabling BYOL impacts how the usage
data for the instance is metered and subsequent billing. For all database versions, the
Database service supports BYOL for the following shapes and editions:
l Bare Metal Shapes: BM.DenseIO1.36 and BM.DenseIO2.52

l Virtual Machine Shapes:

CHAPTER 8 Database
o VM.Standard1 (X5 with remote storage): 1, 2, 4, 8, and 16 core

o VM.Standard2 (X7 with remote storage): 1, 2, 4, 8, 16, and 24 core
l Exadata X6: Quarter, Half, and Full racks
Some restrictions apply:
l If you enable BYOL, you cannot switch between the BYOL and license-included licensing
model on the same instance. Instead, you have to terminate and then recreate the
instance.
l The Database service supports BYOL only for customers who use the Universal Credit
Plan. Non-metered customers cannot use BYOL. Existing customers can migrate from a
non-metered model to a Universal Credit Plan.
l You can only use the options you purchased as part of your ULA.
l If you have Standard or Enterprise Licenses with additional options, you need to use a
Standard Edition or Enterprise Edition license.
l If you have any additional database option other than RAC, Active Data Guard, Database
In-Memory, or Multitenant, you need to use Enterprise Edition - High Performance.
l If you have Active Data Guard, Database In-Memory, or Multitenant, you need to use
Enterprise Edition - Extreme Performance. If you choose the Extreme Performance
edition for a 2-node RAC on virtual machine configuration, then the additional OCPUs
will be charged at the RAC OCPU pricing.
For detailed information about pricing, see https://cloud.oracle.com/en_

US/infrastructure/database/pricing.

CHAPTER 8 Database

For more information on tenancies and compartments, see "Key Concepts and Terminology"
in the Oracle Cloud Infrastructure Getting Started Guide. For general information about using
the API, see About the API.

using.
Limits on the Database Service

increase.

CHAPTER 8 Database
Many Database API operations are subject to throttling.
Exadata DB Systems
Exadata DB Systems allow you to leverage the power of Exadata within the Oracle Cloud
Infrastructure. An Exadata DB System consists of a quarter rack, half rack, or full rack of
compute nodes and storage servers, tied together by a high-speed, low-latency InfiniBand
network and intelligent Exadata software. You can configure automatic backups, optimize for
different workloads, and scale up the system to meet increased demands.
Supported Database Edition and Versions

Exadata DB Systems require Enterprise Edition - Extreme Performance. This edition provides
all the features of Oracle Database Enterprise Edition, plus all the database enterprise
management packs and all the Enterprise Edition options, such as Oracle Database In-Memory
and Oracle Real Application Clusters (RAC).
Exadata DB Systems support the following software releases:
l Oracle Database 12c Release 2 (12.2)

l Oracle Database 11g Release 2 (11.2)
Subscription Types
You have a choice of subscription types for Exadata DB Systems:
l Non-metered Subscription: A non-metered subscription is an agreement to purchase

a specific number of service units over a specific term. Consequently, the charge for a
non-metered subscription is not related to actual service usage. Non-metered
subscriptions are also referred to as standard subscriptions.
l Metered Subscription: With a metered subscription, you are charged based on your
service usage. Two varieties exist:

CHAPTER 8 Database
o Pre-Paid: With a pre-paid subscription you pay an up-front amount to establish

an account that is consumed as you use a service.
o Pay As You Go: With a pay as you go subscription you do not pay an up-front
amount and are billed periodically for your actual service usage.
Metering Frequency
Monthly metering is the only available option. You are billed for each Exadata DB System that
you use, and not for each database deployment that you use.
Scaling an Exadata DB System

Two kinds of scaling operations are supported for an Exadata DB System:
l Scaling within an Exadata DB System lets you modify compute node processing power
within the system.
l Scaling across Exadata DB System configurations lets you move to a different
configuration, for example, from a quarter rack to a half rack.
Scaling Within an Exadata System
If an Exadata DB System requires more compute node processing power, you can scale up the
number of enabled CPU cores in the system. For a non-metered Exadata DB System, you can
temporarily modify the compute node processing power (bursting) or add compute node
processing power on a more permanent basis. For a metered Exadata DB System, you can
simply modify the number of enabled CPU cores.
For information on CPU cores per configuration, see System Configuration. For information on
scaling a system, see To scale an Exadata DB system.
Scaling Across Exadata DB System Configurations
Scaling across Exadata DB System configurations enables you to move to a different system
configuration. This is useful when a database deployment requires:

CHAPTER 8 Database
l Processing power that is beyond the capacity of the current system configuration.
l Storage capacity that is beyond the capacity of the current system configuration.
l A performance boost that can be delivered by increasing the number of available
compute nodes.
l A performance boost that can be delivered by increasing the number of available
Exadata Storage Servers.
Scaling from a quarter rack to a half rack, or from a half rack to a full rack, requires that the
data associated with your database deployment is backed up and restored on a different
Exadata DB System, which requires planning and coordination between you and Oracle. To
start the process, submit a service request to Oracle.
System Configuration
Exadata DB Systems are offered in quarter rack, half rack or full rack configurations, and
each configuration consists of compute nodes and storage servers. The compute nodes are
each configured with a Virtual Machine (VM). You have root privilege for the compute node
VMs, so you can load and run additional software on them. However, you do not have
administrative access to the Exadata infrastructure components, including the physical
compute node hardware, network switches, power distribution units (PDUs), integrated lights-
out management (ILOM) interfaces, or the Exadata Storage Servers, which are all
administered by Oracle.
You have full administrative privileges for your databases, and you can connect to your
databases by using Oracle Net Services from outside the Oracle Cloud Infrastructure. You are
responsible for database administration tasks such as creating tablespaces and managing
database users. You can also customize the default automated maintenance set up, and you
control the recovery process in the event of a database failure.
The following table outlines the vital statistics for each system configuration.

CHAPTER 8 Database
Statistic Quarter Half Full

Rack Rack Rack
Number of Compute Nodes 2 4 8
Total Minimum (Default) Number of Enabled CPU 22 44 88

Cores
Total Maximum Number of Enabled CPU Cores 84 168 336
Total RAM Capacity 1440 GB 2880 GB 5760 GB
Number of Exadata Storage Servers 3 6 12
Total Raw Flash Storage Capacity 38.4 TB 76.8 TB 153.6 TB
Total Raw Disk Storage Capacity 288 TB 576 TB 1152 TB
Total Usable Storage Capacity 84 TB 168 TB 336 TB
Storage Configuration
When you launch an Exadata DB System, the storage space inside the Exadata Storage
Servers is configured for use by Oracle Automatic Storage Management (ASM). By default,
the following ASM disk groups are created:
l The DATA disk group is intended for the storage of Oracle Database data files.
l The RECO disk group is primarily used for storing the Fast Recovery Area (FRA), which
is an area of storage where Oracle Database can create and manage various files
related to backup and recovery, such as RMAN backups and archived redo log files.
l The DBFS and ACFS disk groups are system disk groups that support various
operational purposes. The DBFS disk group is primarily used to store the shared
clusterware files (Oracle Cluster Registry and voting disks), while the ACFS disk groups
are primarily used to store Oracle Database binaries. Compared to the DATA and RECO
disk groups, the system disk groups are so small that they are typically ignored when

CHAPTER 8 Database
discussing the overall storage capacity. You should not store Oracle Database data files
or backups inside the system disk groups.
The disk group names contain a short identifier string that is associated with your Exadata
Database Machine environment. For example, the identifier could be C2, in which case the
DATA disk group would be named DATAC2, the RECO disk group would be named RECOC2, and
so on.
Impact of Backups on Storage
If you choose to perform database backups to the Exadata storage, your choice profoundly
affects how storage space in the Exadata Storage Servers is allocated to the ASM disk groups.
If you choose to provision for backups on Exadata storage, approximately 40% of the
available storage space is allocated to the DATA disk group and approximately 60% is
allocated to the RECO disk group. If you choose not to provision for backups on Exadata
storage, approximately 80% of the available storage space is allocated to the DATA disk
group and approximately 20% is allocated to the RECO disk group. After the storage is
configured, the only way to adjust the allocation without reconfiguring the whole environment
is by submitting a service request to Oracle. For details, see My Oracle Support Note
2007530.1.
The following table shows how the usable storage capacity is allocated to the DATA and RECO
disk groups for each configuration option. The usable storage capacity is the storage that's
available for Oracle Database files after taking into account high-redundancy ASM mirroring
(triple mirroring), which is used to provide highly resilient database storage on all Exadata
DB Systems. The usable storage capacity does not factor in the effects of Exadata
compression capabilities, which can be used to increase the effective storage capacity.

CHAPTER 8 Database
Usable Storage Statistic Quarter Half Rack Full Rack

Rack
Total Usable Storage Capacity 84 TB 168 TB 336 TB
Allocation when Database Backups on Exadata DATA: DATA: DATA:

Storage are provisioned 33.6 TB 67.2 TB 134.4 TB
RECO: RECO: RECO:

50.4 TB 100.8 TB 201.6 TB
Allocation when Database Backups on Exadata DATA: DATA: DATA:

Storage are not provisioned 67.2 TB 134.4 TB 268.8 TB
RECO: RECO: RECO:

16.8 T 33.6 TB 67.2 TB
Managing Exadata DB Systems

This topic explains how to launch, start, stop, terminate, scale, manage licenses for, and
check the status of an Exadata DB system. It also describes how to configure required access
to the Oracle Cloud Infrastructure Object Storage service and set up DNS.
When you launch an Exadata DB system using the Console or the API, the system is
provisioned to support Oracle databases. The service creates an initial database based on the
options you provide and some default options described later in this topic.
Required IAM Policy
For administrators: The policy in Let database admins manage database systems lets the
specified group do everything with databases and related Database resources.

CHAPTER 8 Database
to dig deeper into writing policies for databases, see Details for the Database Service.
Prerequisites
connecting to the DB System via SSH. A sample public key, abbreviated for readability,
is shown below.
For more information, see Managing Key Pairs on Linux Instances.

l The name of a virtual cloud network (VCN) to launch the DB System in. For information
about setting up cloud networks, see Overview of Networking. See the additional
requirements below.
l Exadata DB systems require two separate VCN subnets: a client subnet for user data
and a backup subnet for backup traffic.
l Do not use a subnet that overlaps with 192.168.128.0/20. This restriction applies to both
the client subnet and backup subnet.
l You can define the client subnet as either a private subnet or a public subnet. However,
you must define the backup subnet as a public subnet to back up the database to Object
Storage.
l Oracle requires that you use a VCN Resolver for DNS name resolution for the client
subnet. It automatically resolves the Swift endpoints required for backing up databases,
patching, and updating the cloud tooling on an Exadata DB system.
For more information, see DNS in Your Virtual Cloud Network.
l Important! Properly configure the security list ingress and egress rules. The client
subnet must allow TCP and ICMP traffic between all nodes and all ports in the respective
subnet. If TCP connectivity fails across nodes, the Exadata DB system fails to provision.
For example, if the client subnet uses the source CIDR 10.0.5.0/24, create rules as
shown in the following example.
Ingress Rules:

CHAPTER 8 Database
Source: 10.0.5.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: All
Allows: TCP traffic for ports: all
Source: 10.0.5.0/24
IP Protocol: ICMP
Type and Code: All
Allows: ICMP traffic for: all types and codes
Egress Rules:
Destination: 10.0.5.0/24
IP Protocol: TCP
Destination Port Range: All
Allows: TCP traffic for ports: all
IP Protocol: ICMP
Type and Code: All
Allows: ICMP traffic for: all types and codes
For information about creating and editing rules, see Security Lists.
For the backup subnet, you'll need to configure only an egress rule to allow HTTPS
access to Object Storage. For details, see Backing Up an Exadata Database.
Default Options for the Initial Database
To simplify launching a DB system in the Console and when using the API, the following
default options are used for the initial database.
l Console Enabled: False

l Create Container Database: False for version 11.2.0.4 databases. Otherwise, true.
l Create Instance Only (for standby and migration): False
l Database Home ID: Creates a database home
l Database Language: AMERICAN

CHAPTER 8 Database
l Database Sizing Template: odb2

l Database Storage: ACFS for version 11.2.0.4 databases. Otherwise, ASM.
l Database Territory: AMERICA
l Database Unique Name: The user-specified database name and a system-generated
suffix, for example, dbtst_phx1cs.
l PDB Admin Name: pdbuser (Not applicable for version 11.2.0.4 databases.)
For a list of the database options that you can set in the Console, see To launch an Exadata DB
system.
Using the Console
To launch an Exadata DB system

1. Open the Console, click Database, choose your Compartment, and then click Launch
DB System.
2. In the Launch DB System dialog, enter the following:
Option Description
DB System Information
Compartment By default, the DB system launches in your current compartment

and you can use the network resources in that compartment. Click
the click here link in the dialog box if you want to enable
compartment selection for the DB system, network, and subnet
resources.
Display A friendly, display name for the DB system. The name doesn't need
Name to be unique. An Oracle Cloud Identifier (OCID) will uniquely
identify the DB system.

CHAPTER 8 Database
Option Description
Availability The availability domain in which the DB system resides.

Domain

CHAPTER 8 Database
Option Description
Shape The shape to use to launch the DB system. The shape determines
the type of DB system and the resources allocated to the system.
Bare metal shapes:
l BM.DenseIO1.36: Provides a 1-node DB system (one bare
metal server), with up to 36 CPU cores, 512 GB memory, and
nine 3.2 TB locally attached NVMe drives (28.8 TB total) to the
DB system.
eight 6.4 TB locally attached NVMe drives (51.2 TB total) to
the DB system.
Exadata shapes:
l Exadata.Quarter1.84: Provides a 2-node Exadata
DB System with 22 enabled CPU cores, with up to 62
additional CPU cores, 720 GB RAM per node, 288 TB of raw
storage, 84 TB of usable storage, and unlimited I/O. This
shape supports only the Enterprise Edition - Extreme
Performance.
l Exadata.Half1.168: Provides a 4-node Exadata DB System
with 44 enabled CPU cores, with up to 124 additional CPU
cores, 720 GB RAM per node, 576 TB raw storage, 168 TB of
usable storage, and unlimited I/O. This shape supports only
the Enterprise Edition - Extreme Performance.
l Exadata.Full1.336: Provides an 8-node Exadata DB System

CHAPTER 8 Database
Option Description

Virtual machine shapes (X5):
l VM.Standard1.1: Provides a 1-node DB system with 1 core.
l VM.Standard1.2: Provides a 1- or 2-node DB system with 2
cores.
cores.
cores.
l VM.Standard1.16: Provides a 1- or 2-node DB system with
16 cores.
cores.
cores.
cores.
16 cores.
24 cores.

CHAPTER 8 Database
Option Description
Cluster Name A unique cluster name for a multi-node DB system. The name must
begin with a letter and contain only letters (a-z and A-Z), numbers
(0-9) and hyphens (-). The cluster name can be no longer than 11
characters and is not case sensitive.
Total Node The number of nodes in the DB system. The number depends on the
Count shape you select. You can specify 1 or 2 nodes for virtual machine
DB systems except for VM.Standard1.1, which is a single-node DB
system.
Oracle The database edition supported by the DB system. You can mix
Database supported database versions on the DB system, but not editions.
Software (The database edition cannot be changed and applies to all the
Edition databases in this DB system.)
CPU Core The number of CPU cores for the DB system. Displays only if you
Count select a shape that allows you to configure the number of cores. The
text below the field indicates the acceptable values for that shape.
For a multi-node DB system, the core count is evenly divided across
the nodes.
Bare metal DB systems only: You can increase the CPU cores to
accommodate increased demand after you launch the DB system.

CHAPTER 8 Database
Option Description
License Type The type of license you want to use for the DB system. Your choice
affects metering for billing.
License included means the cost of the cloud service includes a
license for the Database service.
Bring Your Own License (BYOL) means you are an Oracle
Database customer with an Unlimited License Agreement or Non-
Unlimited License Agreement and want to use your license with
Oracle Cloud Infrastructure. This removes the need for separate on-
premises licenses and cloud licenses.
SSH Public The public key portion of the key pair you want to use for SSH
Key access to the DB system. To provide multiple keys, paste each key
on a new line. Make sure each key is on a single, continuous line.
The length of the combined keys cannot exceed 10,000 characters.
Data Storage The percentage (40% or 80%) assigned to DATA storage (user data
Percentage and database files). The remaining percentage is assigned to RECO
storage (database redo logs, archive logs, and recovery manager
backups).
Disk The type of redundancy configured for the DB system.

Redundancy Normal is 2-way mirroring, recommended for test and
development systems.
High is 3-way mirroring, recommended for production systems.
Network Information
Virtual Cloud The compartment containing the network in which to launch the DB
Network system.
Compartment

CHAPTER 8 Database
Option Description
Virtual Cloud The VCN in which to launch the DB system.

Network
Subnet The compartment containing a subnet within the cloud network to

Compartment attach the DB system to.
Client Subnet The subnet to which the DB system should attach.

For Exadata DB systems: Do not use a subnet that overlaps with
192.168.128.0/20. This restriction applies to both the client subnet
and backup subnet.
For 1- and 2-node RAC DB systems: You must use a public subnet.
Do not use a subnet that overlaps with 192.168.16.16/28, which is
used by the Oracle Clusterware private interconnect on the
database instance. Specifying an overlapping subnet will cause the
private interconnect to malfunction.
Backup For Exadata DB systems only. The subnet to use for the backup
Subnet network , which is typically used to transport backup information to
and from Oracle Cloud Infrastructure Object Storage, and for Data
Guard replication.
Do not use a subnet that overlaps with 192.168.128.0/20. This
restriction applies to both the client subnet and backup subnet.
If you plan to back up databases to Object Storage, see the network
prerequisites in Backing Up an Exadata Database.

CHAPTER 8 Database
Option Description
Hostname Your choice of host name for the DB system. The host name must
Prefix begin with an alphabetic character and can contain a maximum of
30 alphanumeric characters, including hyphens (-).
Note: The host name must be unique within the subnet. If it is not
unique, the DB system will fail to provision.
Host Domain The domain name for the DB system. If the selected subnet uses the
Name Oracle-provided Internet and VCN Resolver for DNS name
resolution, this field displays the domain name for the subnet and it
can't be changed. Otherwise, you can provide your choice of a
domain name. Hyphens (-) are not permitted.
For Exadata DB systems, if you plan to store database backups in
Object Storage, Oracle recommends using a VCN Resolver for DNS
name resolution for the client subnet as it automatically resolves
the Swift endpoints used for backups.
Host and Combines the host and domain names to display the fully qualified
Domain URL domain name (FQDN) for the database. The maximum length is 64
characters.
Database Information
Database The name for the database. The database name must begin with an
Name alphabetic character and can contain a maximum of eight
alphanumeric characters. Special characters are not permitted.

CHAPTER 8 Database
Option Description
Database The version of the initial database created on the DB system when it
Version is launched. After the DB system is active, you can create additional
databases by using the command line interface available on the DB
system. You can mix database versions on the DB system, but not
editions.
PDB Name Not applicable to version 11.2.0.4. The name of the pluggable
database. The PDB name must begin with an alphabetic character
and can contain a maximum of 30 alphanumeric characters. The
only special character permitted is the underscore ( _).
Database A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin.
Admin The password must be nine to thirty characters and contain at least
Password two uppercase, two lowercase, two numeric, and two special
characters. The special characters must be _, #, or -.
Confirm The same as above.

Database
Admin
Password
Automatic Check the check box to enable automatic incremental backups for
Backup: this database.

CHAPTER 8 Database
Option Description
Database Select the workload type that best suits your application.
Workload Online Transactional Processing (OLTP) configures the
database for a transactional workload, with a bias towards high
volumes of random data access.
Decision Support System (DSS) configures the database for a
decision support or data warehouse workload, with a bias towards
large data scanning operations.
Character The character set for the database. The default is AL32UTF8.
Set
National The national character set for the database. The default is
Character AL16UTF16.
Set
Tags Optionally, you can apply tags. If you have permissions to create a
resource, you also have permissions to apply free-form tags to that
resource. To apply a defined tag, you must have permissions to use
the tag namespace. For more information about tagging, see
Resource Tags. If you are not sure if you should apply tags, skip this
option (you can apply tags later) or ask your administrator.
3. Click Launch DB System.

The DB system appears in the list with a status of Provisioning. The DB system's icon
changes from yellow to green (or red to indicate errors).
4. Wait for the DB system's icon to turn green, with a status of Available, and then click
the highlighted DB system name.
Details about the DB system are displayed.
5. Note the IP addresses. You need the private or public IP address, depending on network
configuration, to connect to the DB system.

CHAPTER 8 Database
To check the status of an Exadata DB system

1. Open the Console, click Database, and then choose your Compartment.
2. In the list of DB systems, find the system you're interested in and check its icon. The
color of the icon and the text below it indicates the status of the system.
l Provisioning: Yellow icon. Resources are being reserved for the DB system, the
system is booting, and the initial database is being created. Provisioning can take
several minutes. The system is not ready to use yet.
l Available: Green icon. The DB system was successfully provisioned. A few
minutes after the system enters this state, you can SSH to it and begin using it.
l Starting: Yellow icon. The DB system is being powered on by the start or reboot
action in the Console or API.
l Stopping: Yellow icon. The DB system is being powered off by the stop or reboot
l Stopped: Yellow icon. The DB system was powered off by the stop action in the
Console or API.
l Terminating: Gray icon. The DB system is being deleted by the terminate action
in the Console or API.
l Terminated: Gray icon. The DB system has been deleted and is no longer
available.
l Failed: Red icon. An error condition prevented the provisioning or continued
operation of the DB system.
You can also check the status of DB systems and database nodes using the ListDbSystems or
ListDbNodes API operations, which return the lifecycleState attribute.
To start, stop, or reboot an Exadata DB system

1. Open the Console, click Database and then choose your Compartment.
2. In the list of DB systems, find the DB system you want to stop or start, and then click its
name to display details about it.

CHAPTER 8 Database
3. In the list of nodes, click the Actions icon ( ) for a node and then click one of the
following actions:
l Start: Restarts a stopped node. After the node is restarted, the Stop action is
enabled.
l Stop: Shuts down the node. After the node is powered off, the Start action is
enabled.
l Reboot: Shuts down the node, and then restarts it.
Note
For billing purposes, the Stop state has no effect on

the resources you consume. Billing continues for
nodes that you stop, and related resources continue
to apply against any relevant quotas. You must
Terminate a DB system to remove its resources
from billing and quotas.
To scale an Exadata DB system

If an Exadata DB system requires more compute node processing power, you can scale up
(burst) the number of enabled CPU cores in the system.
2. In the list of DB systems, find the system you want to scale and click its highlighted
name.
The system details are displayed.
3. Click Scale Up/Down and then change the number in Total CPU Core Count. The
text below the field indicates the acceptable values, based on the shape used when the
DB system was launched.
4. Click Scale Up/Down DB System.

CHAPTER 8 Database
To terminate an Exadata DB system

Terminating a DB system permanently deletes it and any databases running on it.
Note
The database data is local to the DB system and is lost

when the system is terminated. Oracle recommends
that you back up any data in the DB system before
terminating it.
A list of DB systems is displayed.
2. For the DB system you want to terminate, click the Actions icon ( ), and then click
Terminate.
The DB system's icon indicates Terminating.
At this point, you cannot connect to the system and any open connections are terminated.
To manage your BYOL database licenses

If you want to control the number of database licenses that you run at any given time, you can
scale up or down the number of OCPUs on the instance. These additional licenses are metered
separately.
name.
3. Click Scale Up/Down OCPU and then change the number.

CHAPTER 8 Database
To manage tags for your DB systems and database resources

2. Find the DB system or database resource you're interested in, and click the name.
tags.
l For more information, see Resource Tags.
Using the API
Use these API operations to manage DB system components.
DB systems:
l GetDbSystem
l LaunchDbSystem
l ListDbSystems
l TerminateDbSystem
Database homes:
l GetDbHome
l ListDbHomes
Databases:
l GetDatabase
l ListDatabases
Nodes:

CHAPTER 8 Database
l DbNodeAction: Use this operation to power cycle a node in the DB system.

l ListDbNodes
l GetDbNode
Shapes and database versions:
l ListDbSystemShapes
l ListDbVersions
Configuring a Static Route for Accessing the Object Store
All the traffic in an Exadata DB system is, by default, routed through the data network. To
route backup traffic to the backup interface (BONDETH1), you need to configure a static route
on each of the compute nodes in the cluster.
Before you configure a static route on the compute nodes, keep the following in mind:
l The Exadata DB system's cloud network (VCN) must be configured with an internet
gateway. Add a route table rule to open the access to the Object Storage Service Swift
endpoint on CIDR 0.0.0.0/0. For more information, see Route Tables.
l Oracle recommends that you update the backup subnet's security list to disallow any
access from outside the subnet and allow egress traffic for TCP port 443 (https) on CIDR
Ranges 129.146.0.0/16 (Phoenix region), 129.213.0.0/16 (Ashburn region),
130.61.0.0/16 (Frankfurt region), and 132.145.0.0/16 (London region). For more
information, see Security Lists.
l The network traffic between the system and Object Storage does not leave the cloud
and never reaches the public internet. For more information, see Connectivity to the
Internet.

CHAPTER 8 Database
Note
The following procedure is required and must be

performed on every compute node in an Exadata DB
system. Access to the Oracle Cloud Infrastructure
Object Storage service is required for backing up
databases, patching, and updating the cloud tooling on
an Exadata DB system.
1. SSH to a compute node in the Exadata DB system.

ssh -i <private_key_path> opc@<node_ip_address>
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile.
login as: opc
[opc@dbsys ~]$ sudo su -
3. Identify the gateway configured for the BONDETH1 interface.

[root@dbsys ~]# grep GATEWAY /etc/sysconfig/network-scripts/ifcfg-bondeth1 |awk -F"=" '{print
$2}'
10.0.4.1
4. Add the following static rule for BONDETH1 to the /etc/sysconfig/network-

scripts/route-bondeth1 file, based on your region:
Ashburn (IAD) region
10.0.X.0/XX dev bondeth1 table 211
default via <gateway> dev bondeth1 table 211
129.213.0.0/16 via <gateway_from_previous_step> dev bondeth1
Frankfurt (FRA) region

CHAPTER 8 Database

London (LHR) region

Phoenix (PHX) region

5. Restart the interface.

[root@dbsys ~]# ifdown bondeth1; ifup bondeth1;
The file changes from the previous step take effect immediately after the ifdown and
ifup commands run.
6. Repeat the preceding steps on each compute node in the Exadata DB system.
Important
This procedure must be completed on each compute

node in the Exadata DB system. Otherwise,
attempts to back up databases, patch, or update
tooling on the system might fail.
Setting up DNS for a DB System
DNS lets you use host names instead of IP addresses to communicate with a DB system. You
can use the Internet and VCN Resolver (the DNS capability built into the VCN) as described in
DNS in Your Virtual Cloud Network. Oracle recommends using a VCN Resolver for DNS name
resolution for the client subnet. It automatically resolves the Swift endpoints required for
backing up databases, patching, and updating the cloud tooling on an Exadata DB system.

CHAPTER 8 Database
Connecting to an Exadata DB System

This topic explains how to connect to an Exadata DB System using SSH or SQL Developer.
How you connect depends on how your cloud network is set up. You can find information on
various networking scenarios in Overview of Networking, but for specific recommendations on
how you should connect to a database in the cloud, contact your network security
administrator.
Prerequisites
For SSH access to a compute node in an Exadata DB System, you'll need the following:
l The full path to the file that contains the private key associated with the public key used
when the system was launched.
l The public or private IP address of the DB System. Use the private IP address to
connect to the DB System from your on-premises VPN, or from within the virtual cloud
network (VCN). This includes connecting from a host located on-premises connecting
through a VPN to your VCN, or from another host in the same VCN. Use the DB System's
public IP address to connect to the system from outside the cloud (with no VPN). You
can find the IP addresses in the Oracle Cloud Infrastructure Console on the Database
page.
Connecting to a Compute Node with SSH
You can connect to the compute nodes in an Exadata DB System by using a Secure Shell (SSH)
connection. Most UNIX-style systems (including Linux, Solaris, BSD, and OS X) include an
SSH client by default. For Windows, you can download a free SSH client called PuTTY from
http://www.putty.org.
To connect from a UNIX-style system

Use the following SSH command to access a compute node:
$ ssh –i <private key> opc@<DB System IP address>

CHAPTER 8 Database
<private key> is the full path and name of the file that contains the private key associated
with the Exadata DB System you want to access.
Use the private or public IP address depending on your network configuration. For more
information, see Prerequisites.
To connect from a Windows system

1. Open putty.exe.
2. In the Category pane, select Session and enter the following fields:
l Host Name (or IP address): opc@<ip_address>
Use the compute node's private or public IP address depending on your network
configuration. For more information, see Prerequisites.
l Port: 22
3. In the Category pane, expand Connection, expand SSH, and then click Auth, and
browse to select your private key.
4. Optionally, return to the Session category screen and save this session information for
reuse later.
To access a database after you connect to the compute node

1. Log in as opc and then sudo to the root user.
login as: opc
[opc@ed1db01 ~]$ sudo su -
2. Set the environment to the ASM instance. Depending on which node you are connecting
to, the ASM instance ID will vary, for example, +ASM1 , +ASM2, and so on.

CHAPTER 8 Database
[root@ed1db01 ]# . oraenv
ORACLE_SID = [root] ? +ASM1
The Oracle base has been set to /u01/app/grid
3. List the databases on the system.

root@ed1db01 ]# srvctl config database -v
cdbm01 /u02/app/oracle/product/12.1.0/dbhome_2 12.1.0.2.0

exadb /u02/app/oracle/product/11.2.0/dbhome_2 11.2.0.4.0
mmdb /u02/app/oracle/product/12.1.0/dbhome_3 12.1.0.2.0
4. Connect as the oracle user and get the details about one of the databases using srvctl
command.
[root@ed1db01 ~]# su - oracle
[oracle@ed1db01 ~]$ . oraenv
ORACLE_SID = [oracle] ? cdbm01
The Oracle base has been set to /u02/app/oracle
[oracle@ed1db01 ~]$ srvctl config database -d cdbm01
Database unique name: cdbm01 <<== DB unique name
Database name:
Oracle home: /u02/app/oracle/product/12.1.0/dbhome_2
Oracle user: oracle
Spfile: +DATAC1/cdbm01/spfilecdbm01.ora
Password file: +DATAC1/cdbm01/PASSWORD/passwd
Domain: data.customer1.oraclevcn.com
Start options: open
Stop options: immediate
Database role: PRIMARY
Management policy: AUTOMATIC
Server pools:
Disk Groups: DATAC1,RECOC1
Mount point paths:
Services:
Type: RAC
Start concurrency:
Stop concurrency:
OSDBA group: dba
OSOPER group: racoper
Database instances: cdbm011,cdbm012 <<== SID

CHAPTER 8 Database
Configured nodes: ed1db01,ed1db02

Database is administrator managed
Connecting to a Database with SQL Developer
You can connect to a database with SQL Developer by using one of the following methods:
l Create a temporary SSH tunnel from your computer to the database. This method
provides access only for the duration of the tunnel. (When you are done using the
database, be sure to close the SSH tunnel by exiting the SSH session.)
l Open port 1521 for the Oracle default listener by updating the security list used for the
DB System. This method provides more durable access to the database. For more
information, see Updating the Security List.
After you've created an SSH tunnel or opened port 1521 as described above, you can connect
to a Exadata DB System using SCAN IP addresses or public IP addresses, depending on how
your network is set up and where you are connecting from. You can find the IP addresses in
the Console, in the Database details page.
To connect using SCAN IP addresses

You can connect to the database using the SCAN IP addresses if your client is on-premises and
you are connecting using a FastConnect or VPN connection. You have the following options:
l Use the private SCAN IP addresses, as shown in the following tnsnames.ora example:
testdb=
(DESCRIPTION =
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP1>)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP2>)(PORT = 1521)))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>)
)
)

CHAPTER 8 Database
l Define an external SCAN name in your on-premises DNS server. Your application can
resolve this external SCAN name to the DB System's private SCAN IP addresses, and
then the application can use a connection string that includes the external SCAN name.
In the following tnsnames.ora example, extscanname.example.com is defined in the
on-premises DNS server.
testdb =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = <extscanname.example.com>)(PORT = 1521))
(CONNECT_DATA =
)
)
To connect using public IP addresses

You can use the node's public IP address to connect to the database if the client and database
are in different VCNs, or if the database is on a VCN that has an internet gateway. However,
there are important implications to consider:
l When the client uses the public IP address, the client bypasses the SCAN listener and
reaches the node listener, so server side load balancing is not available.
l When the client uses the public IP address, it cannot take advantage of the VIP failover
feature. If a node becomes unavailable, new connection attempts to the node will hang
until a TCP/IP timeout occurs. You can set client side sqlnet parameters to limit the
TCP/IP timeout.
The following tnsnames.ora example shows a connection string that includes the CONNECT_
TIMEOUT parameter to avoid TCP/IP timeouts.
test=
(DESCRIPTION =
(CONNECT_TIMEOUT=60)
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <publicIP1>)(PORT = 1521))

CHAPTER 8 Database

)
(CONNECT_DATA =
)
)
Updating an Exadata DB System

This topic covers how to update the operating system and the tooling on the database server
nodes (also known as "compute nodes") of an Exadata DB system. Review the information
carefully before you begin the updates.
OS Updates
You update the operating systems of Exadata compute nodes by using the patchmgr tool. This
utility manages the entire update of one or more compute nodes remotely, including running
pre-reboot, reboot, and post-reboot steps. You can run the utility from either an Exadata
compute node or a non-Exadata server running Oracle Linux. The server on which you run the
utility is known as the "driving system." You cannot use the driving system to update itself.
Therefore, if the driving system is one of the Exadata compute nodes on a system you are
updating, you must run a separate operation on a different driving system to update that
server.
The following two scenarios describe typical ways of performing the updates:
Scenario 1: Non-Exadata Driving System
The simplest way to run the update the Exadata system is to use a separate Oracle Linux
server to update all Exadata compute nodes in the system.
Scenario 2: Exadata Node Driving System
You can use one Exadata compute node to drive the updates for the rest of the compute nodes
in the system, and then use one of the updated nodes to drive the update on the original
Exadata driver node.

CHAPTER 8 Database
For example: You are updating a half rack Exadata system, which has four compute nodes -
node1, node2, node3, and node4. First, use node1 to drive the updates of node2, node3, and
node4. Then, use node2 to drive the update of node1.
The driving system requires root user SSH access to each compute node the utility will update.
YUM REPOSITORIES
Some steps in the update process require you to specify a yum repository. The following yum
repositories are available in all regions of Oracle Cloud Infrastructure:
l http://<region>/repo/EngineeredSystems/exadata/dbserver/12.1.2.3.7/base/x86_64
The region URLs are as follows:
l Ashburn (IAD) region : yum-ash.oracle.com

l Frankfurt (FRA) region : yum-fra.oracle.com
l London (LHR) region: yum-lhr.oracle.com
l Phoenix (PHX) region : yum-phx.oracle.com
Use the applicable region for your Exadata DB system. For example, if the system is in the
Phoenix (PHX) region, your yum repository URL should be http://yum-
phx.oracle.com/repo/EngineeredSystems/exadata/dbserver/18.1.4.0.0/base/x86_64
To update the OS on all compute nodes of an Exadata DB system

This example procedure assumes the following:

CHAPTER 8 Database
l The system has two compute nodes, node1 and node2.

l The target version is 18.1.4.0.0.180125.3.
l Each of the two nodes is used as the driving system for the update on the other one.
1. Gather the environment details.

a. SSH to node1 as root and run the following command to determine the version of
Exadata:
[root@node1]# imageinfo -ver
12.2.1.1.4.171128
b. Switch to the grid user, and identify all computes in the cluster.
[root@node1]# su - grid
[grid@node1]$ olsnodes
node1
node1
2. Configure the driving system.

a. Switch back to the root user on node1, check whether a root ssh key pair (id_rsa
and id_rsa.pub) already exists. If not, then generate it.
[root@node1 .ssh]# ls /root/.ssh/id_rsa*
ls: cannot access /root/.ssh/id_rsa*: No such file or directory
[root@node1 .ssh]# ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
93:47:b0:83:75:f2:3e:e6:23:b3:0a:06:ed:00:20:a5
root@node1.fraad1client.exadataclientne.oraclevcn.com
The key's randomart image is:
+--[ RSA 2048]----+
|o.. + . |
|o. o * |
|E . o o |

CHAPTER 8 Database
| . . = |
| o . S = |
| + = . |
| + o o |
| . . + . |
| ... |
+-----------------+
b. Distribute the public key to the target nodes, and verify this step. In this example,
the only target node is node2.
[root@node1 .ssh]# scp -i ~opc/.ssh/id_rsa ~root/.ssh/id_rsa.pub opc@node2:/tmp/id_
rsa.node1.pub
id_rsa.pub
[root@node2 ~]# ls -al /tmp/id_rsa.node1.pub

-rw-r--r-- 1 opc opc 442 Feb 28 03:33 /tmp/id_rsa.node1.pub
[root@node2 ~]# date
Wed Feb 28 03:33:45 UTC 2018
c. On the target node (node2, in this example), add the root public key of node1 to
the root authorized_keys file.
[root@node2 ~]# cat /tmp/id_rsa.node1.pub >> ~root/.ssh/authorized_keys
d. Download dbserver.patch.zip as p21634633_12*_Linux-x86-64.zip onto the

driving system (node1, in this example), and unzip it. See dbnodeupdate.sh and
dbserver.patch.zip: Updating Exadata Database Server Software using the
DBNodeUpdate Utility and patchmgr (Doc ID 1553103.1) for information about the
files in this .zip.
[root@node1 patch]# mkdir /root/patch
[root@node1 patch]# cd /root/patch
[root@node1 patch]# unzip p21634633_181400_Linux-x86-64.zip
Archive: p21634633_181400_Linux-x86-64.zip creating: dbserver_patch_5.180228.2/
creating: dbserver_patch_5.180228.2/ibdiagtools/
inflating: dbserver_patch_5.180228.2/ibdiagtools/cable_check.pl
inflating: dbserver_patch_5.180228.2/ibdiagtools/setup-ssh
inflating: dbserver_patch_5.180228.2/ibdiagtools/VERSION_FILE
extracting: dbserver_patch_5.180228.2/ibdiagtools/xmonib.sh
inflating: dbserver_patch_5.180228.2/ibdiagtools/monitord

CHAPTER 8 Database
inflating: dbserver_patch_5.180228.2/ibdiagtools/checkbadlinks.pl
creating: dbserver_patch_5.180228.2/ibdiagtools/topologies/
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/VerifyTopologyUtility.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/verifylib.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/Node.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/Rack.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/Group.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topologies/Switch.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/topology-zfs
inflating: dbserver_patch_5.180228.2/ibdiagtools/dcli
creating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/remoteScriptGenerator.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/CommonUtils.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/SolarisAdapter.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/LinuxAdapter.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/remoteLauncher.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/remoteConfig.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/spawnProc.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/runDiagnostics.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/netcheck/OSAdapter.pm
inflating: dbserver_patch_5.180228.2/ibdiagtools/SampleOutputs.txt
inflating: dbserver_patch_5.180228.2/ibdiagtools/infinicheck
inflating: dbserver_patch_5.180228.2/ibdiagtools/ibping_test
inflating: dbserver_patch_5.180228.2/ibdiagtools/tar_ibdiagtools
inflating: dbserver_patch_5.180228.2/ibdiagtools/verify-topology
inflating: dbserver_patch_5.180228.2/installfw_exadata_ssh
creating: dbserver_patch_5.180228.2/linux.db.rpms/
inflating: dbserver_patch_5.180228.2/md5sum_files.lst
inflating: dbserver_patch_5.180228.2/patchmgr
inflating: dbserver_patch_5.180228.2/xcp
inflating: dbserver_patch_5.180228.2/ExadataSendNotification.pm
inflating: dbserver_patch_5.180228.2/ExadataImageNotification.pl
inflating: dbserver_patch_5.180228.2/kernelupgrade_oldbios.sh
inflating: dbserver_patch_5.180228.2/cellboot_usb_pci_path
inflating: dbserver_patch_5.180228.2/exadata.img.env
inflating: dbserver_patch_5.180228.2/README.txt
inflating: dbserver_patch_5.180228.2/exadataLogger.pm
inflating: dbserver_patch_5.180228.2/patch_bug_26678971
inflating: dbserver_patch_5.180228.2/dcli

CHAPTER 8 Database
inflating: dbserver_patch_5.180228.2/patchReport.py
extracting: dbserver_patch_5.180228.2/dbnodeupdate.zip
creating: dbserver_patch_5.180228.2/plugins/
inflating: dbserver_patch_5.180228.2/plugins/010-check_17854520.sh
inflating: dbserver_patch_5.180228.2/plugins/000-check_dummy_bash
inflating: dbserver_patch_5.180228.2/plugins/000-check_dummy_perl
inflating: dbserver_patch_5.180228.2/patchmgr_functions
inflating: dbserver_patch_5.180228.2/exadata.img.hw
inflating: dbserver_patch_5.180228.2/libxcp.so.1
inflating: dbserver_patch_5.180228.2/imageLogger
inflating: dbserver_patch_5.180228.2/ExaXMLNode.pm
inflating: dbserver_patch_5.180228.2/fwverify
e. Create the dbs_group file that contains the list of compute nodes to update.
Include the nodes listed after running the olsnodes command in step 1 except for
the driving system node. In this example, dbs_group should include only node2.
[root@node1 patch]# cd /root/patch/dbserver_patch_5.180228
[root@node1 dbserver_patch_5.180228]# cat dbs_group
node2
3. Run a patching precheck operation.

patchmgr -dbnodes dbs_group -precheck -yum_repo <yum_repository> -target_version <target_version>
-nomodify_at_prereq

CHAPTER 8 Database
Important
You must run the precheck operation with the -

nomodify_at_prereq option to prevent any
changes to the system that could impact the backup
you take in the next step. Otherwise, the backup
might not be able to roll back the system to its
original state, should that be necessary.
The output should look like the following example:

[root@node1 dbserver_patch_5.180228]# ./patchmgr -dbnodes dbs_group -precheck -yum_repo
http://yum-phx.oracle.com/repo/EngineeredSystems/exadata/dbserver/18.1.4.0.0/base/x86_64 -target_
version 18.1.4.0.0.180125.3 -nomodify_at_prereq
*************************************************************************************************
***********
NOTE patchmgr release: 5.180228 (always check MOS 1553103.1 for the latest release of
dbserver.patch.zip)
NOTE
WARNING Do not interrupt the patchmgr session.
WARNING Do not resize the screen. It may disturb the screen layout.
WARNING Do not reboot database nodes during update or rollback.
WARNING Do not open logfiles in write mode and do not try to alter them.
*************************************************************************************************
***********
2018-02-28 21:22:45 +0000 :Working: DO: Initiate precheck on 1 node(s)
2018-02-28 21:24:57 +0000 :Working: DO: Check free space and verify SSH equivalence for
the root user to node2
2018-02-28 21:26:15 +0000 :SUCCESS: DONE: Check free space and verify SSH equivalence for
2018-02-28 21:26:47 +0000 :Working: DO: dbnodeupdate.sh running a precheck on node(s).
2018-02-28 21:28:23 +0000 :SUCCESS: DONE: Initiate precheck on node(s).
4. Back up the current system.

CHAPTER 8 Database
patchmgr -dbnodes dbs_group -backup -yum_repo <yum_repository> -target_version <target_version>

-allow_active_network_mounts
Important
This is the proper stage to take the backup, before

any modifications are made to the system.

[root@node1 dbserver_patch_5.180228]# ./patchmgr -dbnodes dbs_group -backup -yum_repo
http://yum-phx.oracle.com/repo/EngineeredSystems/exadata/dbserver/18.1.4.0.0/base/x86_64 -target_
version 18.1.4.0.0.180125.3 -allow_active_network_mounts
*************************************************************************************************
***********
dbserver.patch.zip)
NOTE
*************************************************************************************************
***********
2018-02-28 21:29:00 +0000 :Working: DO: Initiate backup on 1 node(s).
2018-02-28 21:29:00 +0000 :Working: DO: Initiate backup on node(s)
2018-02-28 21:30:51 +0000 :Working: DO: dbnodeupdate.sh running a backup on node(s).
2018-02-28 21:35:50 +0000 :SUCCESS: DONE: Initiate backup on node(s).
2018-02-28 21:35:50 +0000 :SUCCESS: DONE: Initiate backup on 1 node(s).
5. Remove all custom RPMs from the target compute nodes that will be updated. Custom
RPMs are reported in precheck results. They include RPMs that were manually installed

CHAPTER 8 Database
after the system was provisioned.
Note
l If you are updating the system from version

12.1.2.3.4.170111, and the precheck results
include krb5-workstation-1.10.3-
57.el6.x86_64, remove it. (This item is
considered a custom RPM for this version.)
l Do not remove exadata-sun-vm-
computenode-exact or oracle-ofed-
release-guest. These two RPMs are handled
automatically during the update process.
6. Run the nohup command to perform the update.

nohup patchmgr -dbnodes dbs_group -upgrade -nobackup -yum_repo <yum_repository> -target_version
<target_version> -allow_active_network_mounts &

[root@node1 dbserver_patch_5.180228]# nohup ./patchmgr -dbnodes dbs_group -upgrade -nobackup -
yum_repo http://yum-phx.oracle.com/repo/EngineeredSystems/exadata/dbserver/18.1.4.0.0/base/x86_
64 -target_version 18.1.4.0.0.180125.3 -allow_active_network_mounts &
*************************************************************************************************
***********
dbserver.patch.zip)
NOTE
NOTE Database nodes will reboot during the update process.
NOTE

CHAPTER 8 Database
*************************************************************************************************
********
2018-02-28 21:36:26 +0000 :Working: DO: Initiate prepare steps on node(s).

2018-02-28 21:38:43 +0000 :SUCCESS: DONE: Initiate prepare steps on node(s).
2018-02-28 21:38:43 +0000 :Working: DO: Initiate update on 1 node(s).
2018-02-28 21:38:43 +0000 :Working: DO: Initiate update on node(s)
2018-02-28 21:38:49 +0000 :Working: DO: Get information about any required OS upgrades
from node(s).
2018-02-28 21:38:59 +0000 :SUCCESS: DONE: Get information about any required OS upgrades
from node(s).
2018-02-28 21:38:59 +0000 :Working: DO: dbnodeupdate.sh running an update step on all
nodes.
2018-02-28 21:48:41 +0000 :INFO : node2 is ready to reboot.
2018-02-28 21:48:41 +0000 :SUCCESS: DONE: dbnodeupdate.sh running an update step on all
nodes.
2018-02-28 21:48:41 +0000 :Working: DO: Initiate reboot on node(s)
2018-02-28 21:48:57 +0000 :SUCCESS: DONE: Initiate reboot on node(s)
2018-02-28 21:48:57 +0000 :Working: DO: Waiting to ensure node2 is down before reboot.
2018-02-28 21:56:18 +0000 :Working: DO: Initiate prepare steps on node(s).
2018-02-28 21:57:42 +0000 :SEEMS ALREADY UP TO DATE: node2
2018-02-28 21:57:43 +0000 :SUCCESS: DONE: Initiate update on node(s)
7. After the update operation completes, verify the version of the kernel on the compute
node that was updated.
[root@node2 ~]# imageinfo -ver
18.1.4.0.0.180125.3
8. If the driving system is a compute node that needs to be updated (as in this example),
repeat steps 2 through 7 of this procedure using an updated compute node as the driving

CHAPTER 8 Database
system to update the remaining compute node. In this example update, you would use
node2 to update node1.
Updating Tooling on an Exadata DB System
You can update the cloud-specific tooling included on an Exadata DB system compute node by
downloading and applying an RPM file containing the latest version of the tools.
Note
Oracle highly recommends that you maintain the same

version of cloud tooling across your Exadata DB system
environment. Perform the following procedure on every
compute node in the Exadata DB system.
PREREQUISITE
The compute nodes in the Exadata DB system must be configured to access the Oracle Cloud
Infrastructure Object Storage service. For more information, see Configuring a Static Route
for Accessing the Object Store.
UPDATING THE CLOUD TOOLING ON EACH COMPUTE NODE
The method for updating the tooling depends on the tooling release that is currently installed
on the compute node. Regardless of the method you use, be sure to repeat the update process
on each compute node in the cluster.
To check the installed tooling release

1. Connect to the compute node as the opc user.
2. Start a root-user command shell.
$ sudo -s
#

CHAPTER 8 Database
3. Use the following command to display information about the installed cloud tooling and
note the release label, shown in red below.
# rpm -qa|grep -i dbaastools_exa
dbaastools_exa-1.0-1+17.2.4.0.0BM_170508.0954.x86_64
To update the tooling if the release label is 17430 or lower

1. Download the RPM file.
l For Ashburn (IAD) region:
wget https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/exadata/patches/dbaas_
patch/dbaastools_exa.rpm
l For Frankfurt (FRA) region:

wget https://swiftobjectstorage.eu-frankfurt-1.oraclecloud.com/v1/exadata/patches/dbaas_
l For Phoenix (PHX) region:

wget https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/exadata/patches/dbaas_
2. Apply the RPM file.

# rpm -ev dbaastools_exa
# rpm -ivh dbaastools_exa.rpm
3. Repeat the previous steps on each compute node in the Exadata DB system.
To update the tooling if the release label is higher than 17430

1. Check whether any cloud tooling updates are available.
# /var/opt/oracle/exapatch/exadbcpatchsm -list_tools
2. Examine the command response and determine the patch ID of the available cloud
tooling update.

CHAPTER 8 Database
The patch ID is listed in the patches group as the patchid value.

Cloud tooling updates are cumulative. So if multiple updates are available, you can
simply install the latest update. There is no need to install all of the updates in order.
3. If the available patch is newer than the currently installed tools, download and apply the
patch containing the cloud tooling update.
# /var/opt/oracle/exapatch/exadbcpatchsm -toolsinst_async <patchid>
where patchid is the patch ID that you located in the previous step.
4. Repeat the previous steps on each compute node in the Exadata DB system.
Note
The exadbcpatchsm utility runs as a background

process which outputs a transaction ID and immediately
returns control to the user. Command output is written
to a log file. You can monitor the progress of operations
by executing:
# /var/opt/oracle/exapatch/exadbcpatchsm -get_
status transactionid
Patching an Exadata DB System

This topic explains how to use the exadbcpatchmulti utility to perform patching operations
for Oracle Grid Infrastructure and Oracle Database on an Exadata DB System. The
exadbcpatchmulti utility is located in /var/opt/oracle/exapatch on every compute node.
The utility requires root administration privileges.

CHAPTER 8 Database
Note
You must update the cloud specific tooling on all the

compute nodes in your Exadata DB System before
performing the following procedures. For more
information, see Updating an Exadata DB System.
Prerequisites
l Patches are stored in the Oracle Cloud Infrastructure Object Storage service, so the
Exadata DB System requires access the object store. For more information, see
Configuring a Static Route for Accessing the Object Store. Either the client subnet or the
backup subnet can be configured to access the object store.
l The Exadata DB System's cloud network (VCN) must be configured with an internet
Oracle recommends that you update the backup subnet's security list to disallow any
129.146.0.0/16. For more information, see Security Lists.
Note that the network traffic between the DB System and Object Storage does not leave
the cloud and never reaches the public internet. For more information, see Connectivity
to the Internet.
Managing Patches
To list available patches

You can produce a list of available patches using the exadbcpatchmulti command:

For detailed instructions, see Connecting to an Exadata DB System.

CHAPTER 8 Database
2. Start a root-user command shell:

$ sudo -s
#
3. Execute the exadbcpatchmulti command with the -list_patches action:

# /var/opt/oracle/exapatch/exadbcpatchmulti -list_patches
-sshkey=sshkey_file -oh=hostname:oracle_home
where:
l -sshkey specifies the location of the SSH private key of the opc user, which is
used to connect to compute nodes in the cluster. This is an optional parameter.
-oh specifies a compute node and Oracle home directory for which you want to
list the available patches. In this context, an Oracle home directory may be an
Oracle Database home directory or the Oracle Grid Infrastructure home directory.
For example:
# /var/opt/oracle/exapatch/exadbcpatchmulti -list_patches -oh=exaverify-
73z1v1:/u02/app/oracle/product/12.1.0/dbhome_2 -sshkey=/root/y.priv
INFO: non async case
INFO: cmd is: /var/opt/oracle/exapatch/exadbcpatchsm -list_patches -
oh=/u02/app/oracle/product/12.1.0/dbhome_2
INFO: non async case
INFO: cmd is: /var/opt/oracle/exapatch/exadbcpatch -list_patches -patch_
homes=/u02/app/oracle/product/12.1.0/dbhome_2
Starting EXADBCPATCH
Logfile is /var/opt/oracle/log/exadbcpatch/exadbcpatch_2017-07-03_19:40:49.log
Config file is /var/opt/oracle/exapatch/exadbcpatch.cfg
INFO: dbversion detected : 12102
INFO: patching type : psu
INFO: using default values for oci_user
INFO: using default value for oci_passwd
INFO: images available for patching
12.1.0.2.170117, ee
$VAR1 = {
'last_async_precheck_txn_id' => ' ',
'last_async_apply_txn_id' => ' ',
'errmsg' => 'no applicable patches found',
'err' => '-1',

CHAPTER 8 Database
'current_version' => '12.1.0.2.170117',

'last_async_precheck_patch_id' => '',
'current_patch' => '24968615',
'last_async_apply_patch_id' => '',
'patches' => []
};
<json begin>{"last_async_precheck_txn_id":" ","last_async_apply_txn_id":" ","err":"-
1","errmsg":"no applicable patches found","current_version":"12.1.0.2.170117","last_async_
precheck_patch_id":"","current_patch":"24968615","last_async_apply_patch_id":"","patches":
[]}<json end>
Note
The list of available patches is determined by

interrogating the database to establish the patches
that have already been applied. When a patch is
applied, the corresponding database entry is made
as part of the SQL patching operation, which is
executed at the end of the patch workflow.
Therefore, the list of available patches may include
partially applied patches along with patches that are
currently being applied.
4. Exit the root-user command shell.

# exit
$
To check prerequisites before applying a patch

You can perform the prerequisites-checking operation using the exadbcpatchmulti command
as follows:


CHAPTER 8 Database
$ sudo -s
#
3. Execute the exadbcpatchmulti command with the -precheck_async action:

# /var/opt/oracle/exapatch/exadbcpatchmulti -precheck_async patchid
-sshkey=sshkey_file
-instance1=hostname:oracle_home1[,oracle_home2 ...]
[-instance2=hostname:oracle_home1[,oracle_home2 ...] ...]
where:
l patchid identifies the patch to be pre-checked.
used to connect to compute nodes in the cluster.
l -instanceN specifies a compute node and one or more Oracle home directories
that are subject to the patching operation. In this context, an Oracle home
directory may be an Oracle Database home directory or the Oracle Grid
Infrastructure home directory.
For example:
# /var/opt/oracle/exapatch/exadbcpatchmulti -precheck_async 12345678
-sshkey=/home/opc/.ssh/id_rsa
-instance1=hostname1:/u01/app/12.1.0.2/grid,/u01/app/oracle/product/12.1.0.2/dbhome_1
4. Exit the root-user command shell:

# exit
$
To apply a patch
You can apply a patch by using the exadbcpatchmulti command.
The patching operation:
l Can be used to patch some or all of your compute nodes using one command.
l Coordinates multi-node patching in a rolling manner.

CHAPTER 8 Database
l Can execute patch-related SQL after patching all the compute nodes in the cluster.
You can perform a patching operation using the exadbcpatchmulti command as follows:

$ sudo -s
#
3. Execute the exadbcpatchmulti command with the -apply_async action:

# /var/opt/oracle/exapatch/exadbcpatchmulti -apply_async patchid
-sshkey=sshkey_file
-instance1=hostname:oracle_home1 [, oracle_home2 ...]
[-instance2=hostname:oracle_home1 [,oracle_home2 ...] ...]
[-run_datasql=1]
where:
l patchid identifies the patch to be applied.
that are subject to the patching operation. In this context, an Oracle home
l -run_datasql=1 instructs the exadbcpatchmulti command to execute patch-
related SQL commands.

CHAPTER 8 Database
Note
l Patch-related SQL should only be

executed after all of the compute nodes
are patched. Therefore, take care not to
specify this argument if you are patching
a subset of nodes and further nodes
remain to be patched.
l This argument can only be specified in
conjunction with a patching operation on
a set of compute nodes. Therefore, if you
have patched all of your nodes and you
did not specify this argument, you will
need to manually execute the SQL
commands associated with the patch.
Refer to the patch documentation for
further details.
For example:
# /var/opt/oracle/exapatch/exadbcpatchmulti -apply_async 23456789
-instance1=hostname1:/u01/app/oracle/product/12.1.0.2/dbhome_1
-instance2=hostname2:/u01/app/oracle/product/12.1.0.2/dbhome_1
-run_datasql=1

# exit
$
To list applied patches

You can produce a list of applied patches to determine which patches have been applied.

CHAPTER 8 Database
You can use the opatch utility to determine the patches that have been applied to an Oracle
Database or Grid Infrastructure installation.
To produce a list of applied patches for an Oracle Database installation:
1. Connect to a compute node as the oracle user.

2. Set the ORACLE_HOME variable to the location of the Oracle Database installation you
wish to examine. For example:
$ export ORACLE_HOME=/u01/app/oracle/product/12.1.0.2/dbhome_1
3. Execute the opatch command with the lspatches option:

$ $ORACLE_HOME/OPatch/opatch lspatches
To produce a list of applied patches for Oracle Grid Infrastructure:
1. Connect to a compute node as the opc user.

2. Become the grid user:
$ sudo -s
# su - grid
3. Execute the opatch command with the lspatches option:

$ $ORACLE_HOME/OPatch/opatch lspatches
To roll back a patch

You can roll back a patch or failed patch attempt on a by using the exadbcpatchmulti
command.
The patch rollback operation:
l Can be used to roll back a patch on some or all of your compute nodes using one
command.
l Coordinates multi-node operations in a rolling manner.

CHAPTER 8 Database
l Can execute rollback-related SQL after rolling back the patch on all the compute nodes
in the cluster.
You can perform a patch rollback operation using the exadbcpatchmulti command as
follows:

$ sudo -s
#
3. Execute the exadbcpatchmulti command with the -rollback_async action:

# /var/opt/oracle/exapatch/exadbcpatchmulti -rollback_async patchid
-sshkey=sshkey_file
-instance1=hostname:oracle_home1[,oracle_home2 ...]
[-instance2=hostname:oracle_home1[,oracle_home2 ...] ...]
[-run_datasql=1]
where:
l patchid identifies the patch to be rolled back.
that are subject to the rollback operation. In this context, an Oracle home
l -run_datasql=1 instructs the exadbcpatchmulti command to execute rollback-
related SQL commands.

CHAPTER 8 Database
Note
l Rollback-related SQL should only be

executed after all of the compute nodes
are rolled back. Therefore, take care not
to specify this argument if you are rolling
back a subset of nodes and further nodes
remain to be rolled back.
l This argument can only be specified in
conjunction with a rollback operation on a
set of compute nodes. Therefore, if you
have rolled back all of your nodes and
you did not specify this argument, you
will need to manually execute the SQL
commands associated with the rollback
operation. Refer to the patch
documentation for further details.
For example:
# /var/opt/oracle/exapatch/exadbcpatchmulti -rollback_async 34567890
-instance1=hostname1:/u01/app/12.1.0.2/grid
-instance2=hostname2:/u01/app/12.1.0.2/grid
-run_datasql=1

# exit
$
Monitoring a Database on an Exadata DB System

This topic explains how to access Enterprise Manager Database Express and Enterprise
Manager Database Control, which are web-based tools for managing Oracle Database.

CHAPTER 8 Database
Accessing Enterprise Manager Database Express 12c
Enterprise Manager Database Express 12c (EM Express) is available on Exadata DB system
database deployments created using Oracle Database 12c Release 1 (12.1) or later.
How you access EM Express depends on whether you want to manage a CDB or PDB.
l To manage the CDB. When a database deployment is created, Database

automatically sets port 5500 on the deployment’s compute nodes for EM Express access
to the CDB.
l To manage a PDB. For an Oracle Database 12.2 or later deployment, a single port
(known as the global port) is automatically set on the deployment's compute nodes. The
global port lets you use EM Express to connect to all of the PDBs in the CDB using the
HTTPS port for the CDB.
For an Oracle Database 12.1 deployment, you must manually set a port on the
deployment's compute nodes for each PDB you want to manage using EM Express.
For both CDBs and PDBs, you must add the port to a security list as described in Updating the
Security List.
To confirm the port that is in use for a specific database, connect to the database as a
database administrator and execute the query shown in the following example:
SQL> select dbms_xdb_config.getHttpsPort() from dual;
DBMS_XDB_CONFIG.GETHTTPSPORT()
------------------------------
5502
S ETTING THE PORT FOR EM EXPRESS TO MANAGE A PDB (ORACLE DATABASE 12.1 ONLY)
In Oracle Database 12c Release 1, a unique HTTPS port must be configured for the root
container (CDB) and each PDB that you manage using EM Express.
To configure a HTTPS port so that you can manage a PDB with EM Express:
1. Invoke SQL*Plus and log in to the PDB as the SYS user with SYSDBA privileges.
2. Execute the DBMS_XDB_CONFIG.SETHTTPSPORT procedure.

CHAPTER 8 Database
SQL> exec dbms_xdb_config.sethttpsport(port-number)
ACCESSING EM EXPRESS
Before you access EM Express, add the port to the security list. See Updating the Security List.
After you update the security list, you can access EM Express by directing your browser to the
URL https://<node-ip-address>:<port>/em, where node-ip-address is the public IP
address of the compute node hosting EM Express, and port is the EM Express port used by the
database.
Accessing Enterprise Manager 11g Database Control
Enterprise Manager 11g Database Control (Database Control) is available on Exadata DB

system database deployments created using Oracle Database 11g Release 2. Database
Control is allocated a unique port number for each database deployment. By default, access to
Database Control is provided using port 1158 for the first deployment. Subsequent
deployments are allocated ports in a range starting with 5500, 5501, 5502, and so on.
You can confirm the Database Control port for a database by searching for REPOSITORY_URL in
the $ORACLE_HOME/host_sid/sysman/config/emd.properties file.
Before you access Database Control, add the port for the database to the security list
associated with the Exadata DB system's client subnet. For more information, see Updating
the Security List.
After you update the security list, you can access Database Control by directing your browser
to the URL https://<node-ip-address>:<port>/em, where node-ip-address is the public
IP address of the compute node hosting Database Control, and port is the Database Control
port used by the database.
Updating the Security List
Before you can access EM Express or Database Control, you must add the port for the
database to the security list associated with the Exadata DB system's data (client) subnet. To
update an existing security list:

CHAPTER 8 Database
1. In the Console, click Database and locate the DB system in the list.
2. Note the DB system's Client Subnet name and click its Virtual Cloud Network.
3. Locate the subnet in the list, and then click its security list under Security Lists.
4. Click Edit All Rules and add an ingress rule with source CIDR=<source CIDR>,
protocol=TCP, and port=<port number or port range>.
The source CIDR should be the CIDR block that includes the ports you open for the client
connection.
For detailed information about creating or updating a security list, see Security Lists.
Managing Databases on Exadata DB Systems

You can use the dbaasapi command line utility to create and delete databases on an Exadata
DB System. The utility operates like a REST API. It reads a JSON request body and produces a
JSON response body in an output file.
The utility is located in the /var/opt/oracle/dbaasapi/ directory on the compute nodes and
must be run as the root user.
Note

Only one dbaasapi operation can execute at a given

time. Oracle recommends that you check the status of
an operation to ensure it completed before you run
another operation.

CHAPTER 8 Database
Prerequisites
The following are prerequisites if you plan to create a database and store backups in the
Oracle Cloud Infrastructure Object Storage.
l The Exadata DB System requires access the object store. For more information, see
Configuring a Static Route for Accessing the Object Store.
l The DB System's cloud network (VCN) must be configured with an internet gateway.
Add a route table rule to open the access to the Object Storage Service Swift endpoint
on CIDR 0.0.0.0/0. For more information, see Route Tables.
129.146.0.0/16. For more information, see Security Lists.
Note that the network traffic between the DB System and Object Storage does not leave
the cloud and never reaches the public internet. For more information, see Connectivity
to the Internet.
l An existing Object Storage bucket to use as the backup destination. You can use the
Console or the Object Storage API to create the bucket. For more information, see
Managing Buckets.
l A Swift password generated by Oracle Cloud Infrastructure. You can use the Console or
the IAM API to generate the password. For more information, see Working with Swift
Passwords.
l The user name specified in the backup configuration file must have tenancy-level access
to Object Storage. An easy way to do this is to add the user name to the Administrators
group. However, that allows access to all of the cloud services. Instead, an
administrator can create a policy that allows tenancy-level access to just Object
Storage. The following is an example of such a policy.
Allow group DBAdmins to manage buckets in tenancy
Allow group DBAdmins to manage objects in tenancy
For more information about adding a user to a group, see Managing Groups. For more
information about policies, see Getting Started with Policies.

CHAPTER 8 Database
Creating a Database
The following procedure creates directory called dbinput, a sample input file called
myinput.json, and a sample output file called createdb.out.
1. SSH to a compute node in the Exadata DB System.


login as: opc
3. Make a directory for the input file and change to the directory.
[root@dbsys ~]# mkdir –p /home/oracle/dbinput
# cd /home/oracle/dbinput
4. Create the input file in the directory. The following sample file will create a database
configured to store backups in an existing bucket in Object Storage. For parameter
descriptions, see Create Database Parameters.
{
"object": "db",
"action": "start",
"operation": "createdb",
"params": {
"nodelist": "",
"dbname": "exadb",
"edition": "EE_EP",
"version": "12.1.0.2",
"adminPassword": "WElcome#123_",
"sid": "exadb",
"pdbName": "PDB1",
"charset": "AL32UTF8",
"ncharset": "AL16UTF16",
"backupDestination": "OSS",
"cloudStorageContainer":
"https://swiftobjectstorage.<region>.oraclecloud.com/v1/mycompany/DBBackups",
"cloudStorageUser": "jsmith@mycompany.com",

CHAPTER 8 Database
"cloudStoragePwd": "1cnk!d0++ptETd&C;tHR"
},
"outputfile": "/home/oracle/createdb.out",
"FLAGS": ""
}
5. Run the utility and specify the input file.

[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i myinput.json
6. Check the output file and note the ID.

[root@dbsys ~]# cat /home/oracle/createdb.out
{
"msg" : "",
"object" : "db",
"status" : "Starting",
"errmsg" : "",
"outputfile" : "/home/oracle/createdb.out",
"action" : "start",
"id" : "170",
"operation" : "createdb",
"logfile" : "/var/opt/oracle/log/gsa1/dbaasapi/db/createdb/1.log"
}
7. Create a JSON file to check the database creation status. Note the action of "status".
Replace the ID and the dbname with the values from the previous steps.
{
"object": "db",
"action": "status",
"operation": "createdb",
"id": 170,
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/createdb.out",
"FLAGS": ""
}
8. Run the utility with the status file as input and then check the utility output.
Rerun the status action regularly until the response indicates that the operation
succeeded or failed.

CHAPTER 8 Database
[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i db_status.json
[root@dbsys ~]# cat /home/oracle/createdb.out
{
"msg" : "Sync sqlnet file...[done]\\n##Done executing tde\\nWARN: Could not register elogger_
parameters: elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking
assistant bkup\\nUsing cmd : /var/opt/oracle/ocde/assistants/bkup/bkup -out
/var/opt/oracle/ocde/res/bkup.out -sid=\"exadb1\" -reco_grp=\"RECOC1\" -
hostname=\"ed1db01.data.customer1.oraclevcn.com\" -oracle_
home=\"/u02/app/oracle/product/12.1.0/dbhome_5\" -dbname=\"exadb\" -dbtype=\"exarac\" -
exabm=\"yes\" -edition=\"enterprise\" -bkup_cfg_files=\"no\" -acfs_vol_
dir=\"/var/opt/oracle/dbaas_acfs\" -bkup_oss_url=\"bkup_oss_url\" -bkup_oss_user=\"bkup_oss_
user\" -version=\"12102\" -oracle_base=\"/u02/app/oracle\" -firstrun=\"no\" -action=\"config\" -
bkup_oss=\"no\" -bkup_disk=\"no\" -data_grp=\"DATAC1\" -action=config \\n\\n##Done executing
bkup\\nWARN: Could not register elogger_parameters: elogger.pm::_init: /var/opt/oracle/dbaas_
acfs/events does not existRemoved all entries from creg file : /var/opt/oracle/creg/exadb.ini
matching passwd or decrypt_key\\n\\n#### Completed OCDE Successfully ####\\nWARN: Could not
register elogger_parameters: elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not
exist",
"object" : "db",
"status" : "Success",
"errmsg" : "",
"outputfile" : "/home/oracle/createdb_exadb.out",
"action" : "start",
"id" : "170",
"operation" : "createdb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/createdb/170.log"
}
CREATE DATABASE PARAMETERS
Use the following parameters to create a database.
Parameter Description
object The value "db".
action The value "start".

CHAPTER 8 Database
operation The value "createdb".
nodelist The value "" (an empty string). The database will be created
across all nodes in the cluster.
dbname The database name, in quotes.
edition The value "EE_EP". (Only Enterprise Edition - Extreme

Performance is supported .)
version The database version as 12.2.0.1, 12.1.0.2, or 11.2.0.4, in

quotes.
adminPassword The administrator (SYS and SYSTEM) password to use for the
new database, in quotes. The password must be nine to thirty
characters and contain at least two uppercase, two lowercase,
two numeric, and two special characters. The special characters
must be _, #, or -.
sid The SID of the database, in quotes.
pdbName The name of the pluggable database, in quotes.

CHAPTER 8 Database
charset The database character set, in quotes.
Allowed values
AL32UTF8, AR8ADOS710, AR8ADOS720, AR8APTEC715,
AR8ARABICMACS, AR8ASMO8X, AR8ISO8859P6, AR8MSWIN1256,
AR8MUSSAD768, AR8NAFITHA711, AR8NAFITHA721,
AR8SAKHR706, AR8SAKHR707, AZ8ISO8859P9E, BG8MSWIN,
BG8PC437S, BLT8CP921, BLT8ISO8859P13, BLT8MSWIN1257,
BLT8PC775, BN8BSCII, CDN8PC863, CEL8ISO8859P14,
CL8ISO8859P5, CL8ISOIR111, CL8KOI8R, CL8KOI8U,
CL8MACCYRILLICS, CL8MSWIN1251, EE8ISO8859P2,
EE8MACCES, EE8MACCROATIANS, EE8MSWIN1250, EE8PC852,
EL8DEC, EL8ISO8859P7, EL8MACGREEKS, EL8MSWIN1253,
EL8PC437S, EL8PC851, EL8PC869, ET8MSWIN923, HU8ABMOD,
HU8CWI2, IN8ISCII, IS8PC861, IW8ISO8859P8,
IW8MACHEBREWS, IW8MSWIN1255, IW8PC1507, JA16EUC,
JA16EUCTILDE, JA16SJIS, JA16SJISTILDE, JA16VMS,
KO16KSCCS, KO16MSWIN949, LA8ISO6937, LA8PASSPORT,
LT8MSWIN921, LT8PC772, LT8PC774, LV8PC1117, LV8PC8LR,
LV8RST104090, N8PC865, NE8ISO8859P10, NEE8ISO8859P4,
RU8BESTA, RU8PC855, RU8PC866, SE8ISO8859P3,
TH8MACTHAIS, TH8TISASCII, TR8DEC, TR8MACTURKISHS,
TR8MSWIN1254, TR8PC857, US7ASCII, US8PC437, UTF8,
VN8MSWIN1258, VN8VN3, WE8DEC, WE8DG, WE8ISO8859P15,
WE8ISO8859P9, WE8MACROMAN8S, WE8MSWIN1252, WE8NCR4970,
WE8NEXTSTEP, WE8PC850, WE8PC858, WE8PC860, WE8ROMAN8,
ZHS16CGB231280, ZHS16GBK, ZHT16BIG5, ZHT16CCDC,
ZHT16DBT, ZHT16HKSCS, ZHT16MSWIN950, ZHT32EUC,
ZHT32SOPS, ZHT32TRIS

CHAPTER 8 Database
ncharset The database national character set. The value AL16UTF16 or

UTF8, in quotes.
backupDestination The database backup destination, in quotes. You can configure

the following backup destinations.
NONE No backup destination is configured.
DISK Configure database backups to the local disk Fast Recovery

Area.
OSS Configure database backups to an existing bucket in the

Oracle Cloud Infrastructure Object Storage service. You must
specify all the cloudStorage parameters.
BOTH Configure database backups to both local disk and an

existing bucket in Object Storage. You must specify all the
cloudStorage parameters.
For example:
"backupDestination":"BOTH"

CHAPTER 8 Database
cloudStorageContainer= Required if you specify a backup destination of OSS or BOTH. The

<swift_url> Object Storage URL, your Oracle Cloud Infrastructure tenant, and
an existing bucket in the object store to use as the backup
destination, in the following format.
https://
swiftobjectstorage
.<region>.oraclecloud.com/v1/<tenant>/<bucket>
For example:
"cloudStorageContainer":"https://
swiftobjectstorage
.<region>.oraclecloud.com/v1/mycompany/DBBackups"
cloudStorageUser= Required if you specify a backup destination of OSS or BOTH. The

<user_name> user name for the Oracle Cloud Infrastructure user account, for
example:
"cloudStorageUser":"jsmith@mycompany.com"
This is the user name you use to sign in to the Console. The user
name must be a member of the Administrators group, as
described in Prerequisites.
cloudStoragePwd= Required if you specify a backup destination of OSS or BOTH. The

<swift-password> Swift password generated by using the Console or IAM API, in
single quotes, for example:
"cloudStoragePwd":"1cnk!d0++ptETd&C;tHR"
For more information, see Managing User Credentials.
This is not the password for the Oracle Cloud Infrastructure

user.

CHAPTER 8 Database
outputfile The absolute path for the output of the request, for example,
"outputfile":"/home/oracle/createdb.out".
FLAGS The value "" (an empty string).
Deleting a Database
1. SSH to a compute node in the Exadata DB System.


login as: opc
3. Make a directory for the input file and change to the directory.
[root@dbsys ~]# mkdir –p /home/oracle/dbinput
# cd /home/oracle/dbinput
4. Create the input file in the directory and specify the database name to delete and an
output file. For more information, see Delete Database Parameters .
{
"object": "db",
"action": "start",
"operation": "deletedb",
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/delete_exadb.out",
"FLAGS": ""
}
5. Run the utility and specify the input file.

CHAPTER 8 Database
[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i myinput.json
6. Check the output file and note the ID.

[root@ed1db01 ~]# cat /home/oracle/delete_exadb.out
{
"msg" : "",
"object" : "db",
"status" : "Starting",
"errmsg" : "",
"outputfile" : "/home/oracle/deletedb.out",
"action" : "start",
"id" : "17",
"operation" : "deletedb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/deletedb/17.log"
}
7. Create a JSON file to check the database deletion status. Note the action of "status" in
the sample file below. Replace the ID and the dbname with the values from the previous
steps.
{
"object": "db",
"action": "status",
"operation": "deletedb",
"id": 17,
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/deletedb.out",
"FLAGS": ""
}
8. Run the utility with the status file as input and then check the utility output.
Rerun the status action regularly until the response indicates that the operation
succeeded.
[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i db_status.json
[root@dbsys ~]# cat /home/oracle/deletedb.out

CHAPTER 8 Database
{
"msg" : "Using cmd : su - root -c \"/var/opt/oracle/ocde/assistants/dg/dgcc -dbname exadb -
action delete\" \\n\\n##Done executing dg\\nWARN: Could not register elogger_parameters:
elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking assistant
bkup\\nUsing cmd : /var/opt/oracle/ocde/assistants/bkup/bkup -out
/var/opt/oracle/ocde/res/bkup.out -bkup_oss_url=\"bkup_oss_url\" -bkup_daily_time=\"0:13\" -bkup_
oss_user=\"bkup_oss_user\" -dbname=\"exadb\" -dbtype=\"exarac\" -exabm=\"yes\" -firstrun=\"no\" -
action=\"delete\" -bkup_cfg_files=\"no\" -bkup_oss=\"no\" -bkup_disk=\"no\" -action=delete
\\n\\n##Done executing bkup\\nWARN: Could not register elogger_parameters: elogger.pm::_init:
/var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking assistant dbda\\nUsing cmd :
/var/opt/oracle/ocde/assistants/dbda/dbda -out /var/opt/oracle/ocde/res/dbda.out -em=\"no\" -pga_
target=\"2000\" -dbtype=\"exarac\" -sga_target=\"2800\" -action=\"delete\" -build=\"no\" -
nid=\"no\" -dbname=\"exadb\" -action=delete \\n",
"object" : "db",
"status" : "InProgress",
"errmsg" : "",
"outputfile" : "/home/oracle/deletedb.out",
"action" : "start",
"id" : "17",
"operation" : "deletedb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/deletedb/17.log"
}
DELETE DATABASE PARAMETERS
Use the following parameters to delete a database.
object The value "db".
action The value "start".
operation The value "deletedb".
dbname The database name, in quotes.

CHAPTER 8 Database
outputfile The absolute path for the output of the request, for example,
"/home/oracle/deletedb.out".
FLAGS The value "" (an empty string).
Backing Up an Exadata Database

You can back up databases on an Exadata DB System to an existing bucket in the Oracle Cloud
Infrastructure Object Storage service and to the local disk Fast Recovery Area.
This topic explains how to:
l Create a backup configuration file that indicates the backup destination, when the
backup should run, and how long backups are retained. If the backup destination is
Object Storage, the file also contains the credentials to access the service.
l Associate the backup configuration file with a database. The database will be backed up
as scheduled, or you can create an on-demand backup.
Note

Prerequisites
l The Exadata DB System requires access the Oracle Cloud Infrastructure Object Storage
service. For more information, see Configuring a Static Route for Accessing the Object
Store.

CHAPTER 8 Database
l The Exadata DB System's cloud network (VCN) must be configured with an internet
Ranges 129.146.0.0/16 (Phoenix region) 129.213.0.0/16 (Ashburn region),
130.61.0.0/16 (Frankfurt region), and 132.145.0.0/16 (London region). For more
Note that the network traffic between the system and Object Storage does not leave the
cloud and never reaches the public internet. For more information, see Connectivity to
the Internet.
l An existing Object Storage bucket to use as the backup destination. You can use the
Console or the Object Storage API to create the bucket. For more information, see
Managing Buckets.
l A Swift password generated by Oracle Cloud Infrastructure. You can use the Console or
the IAM API to generate the password. For more information, see Working with Swift
Passwords.
l The user name specified in the backup configuration file must have tenancy-level access
to Object Storage. An easy way to do this is to add the user name to the Administrators
group. However, that allows access to all of the cloud services. Instead, an
administrator can create a policy that allows tenancy-level access to just Object
For more information about adding a user to a group, see Managing Groups. For more
information about policies, see Getting Started with Policies.
Default Backup Configuration
The backup configuration follows a set of Oracle best-practice guidelines:

CHAPTER 8 Database
l Full (level 0) backup of the database followed by rolling incremental (level 1) backups
on a seven-day cycle (a 30-day cycle for the Object Storage destination).
l Full backup of selected system files.
l Automatic backups daily at a specific time set during the database deployment creation
process.
Retention period:
l Both Object Storage and local storage: 30 days, with the 7 most recent days' backups
available on local storage.
l Object Storage only: 30 days.
l Local storage only: 7 days.
Encryption:
l Both Object Storage and local storage: All backups to cloud storage are encrypted.
l Object Storage only: All backups to cloud storage are encrypted.
Managing Backups
To create a backup configuration file
Important
The following procedure must be performed on the first

compute node in the Exadata DB System. To determine
the first compute node, connect to any compute node as
the grid user and execute the following command:
$ $ORACLE_HOME/bin/olsnodes -n
The first node has the number 1 listed beside the node
name.

CHAPTER 8 Database
1. SSH to the first compute node in the Exadata DB System.

ssh -i <private_key_path> opc@<node_1_ip_address>

login as: opc
3. Create a new backup configuration file in /var/opt/oracle/ocde/assistants/bkup/

as shown in the sample configuration file below. This example uses the file name
bkup.cfg, but you can provide your own file name. The following file schedules a
backup to both local storage and an existing bucket in Object Storage.
The parameters are described below this procedure.
[root@dbsys ~]# cd /var/opt/oracle/ocde/assistants/bkup/
vi bkup.cfg
bkup_disk=yes
bkup_oss=yes
bkup_oss_url=https://swiftobjectstorage.<region>.oraclecloud.com/v1/companyabc/DBBackups
bkup_oss_user=jsmith@mycompany.com
bkup_oss_passwd=1cnk!d0++ptETd&C;tHR
bkup_oss_recovery_window=7
bkup_daily_time=06:45
4. Change the permissions of the file.

[root@dbsys bkup]# chmod 600 bkup.cfg
5. Use the following command to install the backup configuration, configure the
credentials, schedule the backup, and associate the configuration with a database
name.
[root@dbsys bkup]# ./bkup -cfg bkup.cfg -dbname=<database_name>
The backup is scheduled via cron and can be viewed at /etc/crontab.
When the scheduled backup runs, you can check its progress with the following command.
[root@dbsys bkup]# /var/opt/oracle/bkup_api/bkup_api bkup_status

CHAPTER 8 Database
The backup configuration file parameters are described below.
bkup_disk=[yes|no] Whether to back up locally

to disk (Fast Recovery
Area).
bkup_oss=[yes|no] Whether to back up to

Object Storage. If yes, you
must also provide the
parameters bkup_oss_url,
bkup_oss_user, bkup_oss_
passwd, and bkup_oss_
recovery_window.

CHAPTER 8 Database
bkup_oss_url=<swift_url> Required if bkup_oss=yes.
The Object Storage URL

including the tenant and
bucket you want to use. The
URL is:
https://
swiftobjectstorage
.
<region>
.
oraclecloud
.
com
/v1/<tenant>/<bucket>
where <tenant> is the

lowercase tenant name
(even if it contains
uppercase characters) that
you specify when signing in
to the Console and
<bucket> is the name of
the existing bucket you
want to use for backups.

CHAPTER 8 Database
bkup_oss_user=<oci_user_ Required if bkup_oss=yes.

name>
The user name for the
Oracle Cloud Infrastructure
user account, for example
jsmith@mycompany.com.
The user must be a member
of the Administrators group,
as described in
Prerequisites.
This is the user name you

use to sign in to the
Console.
bkup_oss_passwd=<swift_ Required if bkup_oss=yes.

password>
The Swift password
generated by using the
Console or IAM API, as
described in Prerequisites.
This is not the password for

the Oracle Cloud
Infrastructure user.

CHAPTER 8 Database
bkup_oss_recovery_window=n Required if bkup_oss=yes.
The number of days for

which backups and archived
redo logs are maintained in
the Object Storage bucket.
Specify 1 to 30 days.
bkup_daily_time=hh:mm The time at which the daily

backup is scheduled,
specified in hours and
minutes (hh:mm), in 24-
hour format.
To create an on-demand backup

You can use the bkup_api utility to create an on-demand backup of a database.
1. SSH to the first compute node in the Exadata DB System.

ssh -i <private_key_path> opc@<node_1_ip_address>
To determine the first compute node, connect to any compute node as the grid user and
execute the following command:
The first node has the number 1 listed beside the node name.
login as: opc
3. You can let the backup follow the current retention policy, or you can create a long-term

CHAPTER 8 Database
backup that persists until you delete it:

l To create a backup that follows the current retention policy, enter the following
command:
# /var/opt/oracle/bkup_api/bkup_api bkup_start --dbname=<database_name>
l To create a long-term backup, enter the following command:

# /var/opt/oracle/bkup_api/bkup_api bkup_start --keep --dbname=<database_name>
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
By default, the backup is given a timestamp-based tag. To specify a custom backup tag, add
the --tag option to the bkup_api command; for example, to create a long-term backup with
the tag "monthly", enter the following command:
# /var/opt/oracle/bkup_api/bkup_api bkup_start --keep --tag=monthly
After you enter a bkup_api bkup_start command, the bkup_api utility starts the backup
process, which runs in the background. To check the progress of the backup process, enter the
following command:
# /var/opt/oracle/bkup_api/bkup_api bkup_status --dbname=<database_name>
To remove the backup configuration

A backup configuration can contain the credentials to access the Object Storage bucket. For
this reason, you might want to remove the file after successfully configuring the backup.
[root@dbsys bkup]# rm bkup.cfg
To delete a local backup

To delete a backup of a database deployment on the Exadata DB System, use the bkup_api
utility.

CHAPTER 8 Database
1. Connect to the first compute node in your Exadata DB System as the opc user.
To determine the first compute node, connect to any compute node as the grid user and
execute the following command:
The first node has the number 1 listed beside the node name.
$ sudo -s#
3. List the available backups:

# >/var/opt/oracle/bkup_api/bkup_api recover_list --dbname=<database_name>
where dbname is the database name for the database that you want to act on.
A list of available backups is displayed.
4. Delete the backup you want:
# /var/opt/oracle/bkup_api/bkup_api bkup_delete --bkup=<backup-tag> --dbname=<database_name>
where backup-tag is the tag of the backup you want to delete.

# exit$
To delete a backup in Object Storage

Use the RMAN delete backup command to delete a backup from the Object Store.
WHAT NEXT?
If you used Object Storage as a backup destination, you can display the backup files in your
bucket in the Console on the Storage page, by selecting Object Storage.
You can manually restore a database backup by using the RMAN utility. For information about
using RMAN, see the Oracle Database Backup and Recovery User's Guide for Release 18.1,
12.2, 12.1, or 11.2.

CHAPTER 8 Database
Recovering an Exadata Database

Exadata DB Systems provide a backup feature that backs up the Oracle database associated
with a database deployment. This feature is built over Oracle Recovery Manager (RMAN).
You can manually restore a database backup by using the RMAN utility. For information about
using RMAN, see the Oracle Database Backup and Recovery User's Guide for Release 12.2,
12.1, or 11.2.
Bare Metal and Virtual Machine DB Systems

Oracle Cloud Infrastructure offers 1-node DB systems on either bare metal or virtual
machines, and 2-node RAC DB systems on virtual machines.
You can manage these systems by using the Console, the API, the Oracle Cloud Infrastructure
CLI, the Database CLI (DBCLI), Enterprise Manager, Enterprise Manager Express, or
SQL Developer.
Note
This documentation is intended for Oracle database

administrators and assumes familiarity with Oracle
databases and tools. If you need additional information,
see the product documentation available at
http://docs.oracle.com/en/database/.
Supported Database Editions and Versions

All 1- and 2-node RAC DB systems support the following Oracle Database editions:
l Standard Edition
l Enterprise Edition

CHAPTER 8 Database
l Enterprise Edition - High Performance

l Enterprise Edition - Extreme Performance (required for 2-node RAC DB systems)
The supported database versions are:

l Oracle Database 11g Release 2 (11.2)
Bare Metal DB Systems

Bare metal DB systems consist of a single bare metal server running Oracle Linux 6.8, with
locally attached NVMe storage. If the node fails, you can simply launch another system and
restore the databases from current backups.
When you launch a bare metal DB system, you select a single Oracle Database Edition that
applies to all the databases on that DB system. The selected edition cannot be changed. Each
DB system can have multiple database homes, which can be different versions. Each database
home can have only one database, which is the same version as the database home.
Shapes for Bare Metal DB Systems
When you launch a DB system, you choose a shape, which determines the resources allocated
to the DB system. The available shapes for a bare metal DB system are:
l BM.DenseIO1.36: Provides a 1-node DB system (one bare metal server), with up to 36

CPU cores, 512 GB memory, and nine 3.2 TB locally attached NVMe drives (28.8 TB
total) to the DB system.
l BM.DenseIO2.52: Provides a 1-node DB system (one bare metal server), with up to 52
CPU cores, 768 GB memory, and eight 6.4 TB locally attached NVMe drives (51.2 TB
total) to the DB system.

CHAPTER 8 Database
Storage Considerations
The shape you choose for a bare metal DB system determines its total raw storage, but other
options, like 2- or 3-way mirroring and the space allocated for data files, affect the amount of
usable storage on the system. The following table shows how various configurations affect the
usable storage for bare metal DB systems.
Shape Raw Usable Storage with Usable Storage with High

Storage Normal Redundancy (2- Redundancy (3-way
way Mirroring) Mirroring)
BM.DenseIO1.36 28.8 DATA 9.4 TB DATA 5.4 TB

TB NVMe
RECO 1.7 TB RECO 1 TB
BM.DenseIO2.52 51.2 DATA 16 TB DATA 9 TB

TB NVMe
RECO 4 TB RECO 2.3 TB
Virtual Machine DB Systems

There are two types of DB systems on virtual machines:
l A 1-node virtual machine DB system consists of one virtual machine.

l A 2-node virtual machine DB system consists of two virtual machines.
When you launch a virtual machine DB system, you select the Oracle Database Edition that
applies to the database on that DB system. The selected edition cannot be changed. Unlike a
bare metal DB system, a virtual machine DB system can have only a single database home.
The database home will have a single database, which will be the same version as the
database home.
Virtual machine DB systems also differ from bare metal DB systems in the following ways:
l A virtual machine DB system database uses Oracle Cloud Infrastructure block storage
instead of local storage. You specify a storage size when you launch the DB system, and

CHAPTER 8 Database
you can scale up the storage as needed at any time.

l The number of CPU cores on an existing virtual machine DB system cannot be changed.
Shapes for Virtual Machine DB Systems
When you launch a DB system, you choose a shape, which determines the resources allocated
to the DB system.
The following table shows the available shapes for a virtual machine DB system on X5.
Shape CPU Cores Memory
VM.Standard1.1 1 7 GB
The following table shows the available shapes for a virtual machine DB system on X7.
Shape CPU Cores Memory

CHAPTER 8 Database
Storage Options for Virtual Machine DB Systems
Virtual machine DB systems use Oracle Cloud Infrastructure block storage. The following
table shows details of the storage options for a virtual machine DB system. Total storage
includes available storage plus recovery logs.
Available Storage (GB) Total Storage (GB)
256 712
512 968
1024 1480
2048 2656
4096 5116
6144 7572
8192 10032
10240 12488
12288 14944
14336 17404
16384 19860
18432 22320
20480 24776
22528 27232
24576 29692
26624 32148

CHAPTER 8 Database
Available Storage (GB) Total Storage (GB)
28672 34608
30720 37064
32768 39520
34816 41980
36864 44436
38912 46896
40960 49352
For 2-node RAC virtual machine DB systems, storage capacity is shared between the nodes.
Managing DB Systems
This topic explains how to launch, start, stop, terminate, scale, manage licenses for, and
check the status of a bare metal and virtual machine DB system, and set up DNS for a 1-node
or 2-node RAC DB system.
When you launch a DB system using the Console, the API, or the CLI, the system is
provisioned to support Oracle databases and an initial database is created based on the
options you provide and some default options described later in this topic.
Required IAM Policy

CHAPTER 8 Database
Prerequisites
You'll need the following items to launch any DB system.
connecting to the DB System via SSH. A sample public key, abbreviated for readability,
is shown below.
For more information, see Managing Key Pairs on Linux Instances.

l The name of a virtual cloud network (VCN) to launch the DB System in. For information
about setting up cloud networks, see Overview of Networking. See the additional
requirements below.
l You must use a public subnet. Do not use a subnet that overlaps with 192.168.16.16/28,
which is used by the Oracle Clusterware private interconnect on the database instance.
Specifying an overlapping subnet will cause the private interconnect to malfunction.
l For a 2-node RAC DB system, the subnet must have at least six available IP addresses.
Three of each subnet's IP addresses are reserved, so the minimum allowed subnet size
is /28. For more information, see Allowed VCN Size and Address Ranges.
l If you plan to back up your DB system to Object Storage, the VCN must have an enabled
internet gateway and a corresponding route rule for it. For more information, see
Backing Up to Oracle Cloud Infrastructure Object Storage and Connectivity to the
Internet.
l Each VCN subnet has a default security list that contains a rule to allow TCP traffic on
destination port 22 (SSH) from source 0.0.0.0/0 and any source port. You can update
the default security list or create new lists to allow other types of access, but this can be

CHAPTER 8 Database
done before or after you launch the DB system. For more information, see Security
Lists.
l For a 2-node RAC DB system, make sure port 22 is open for both ingress and egress on
the subnet, otherwise, the DB system might fail to provision successfully.
l If you need DNS name resolution for the system, decide whether to use a Custom
Resolver (your choice of DNS server) or the Internet and VCN Resolver (the
DNS capability built in to the VCN). For more information, see DNS in Your Virtual Cloud
Network.
Default Options for the Initial Database
To simplify launching a DB system in the Console and when using the API, the following
default options are used for the initial database and for any additional databases that you
create. (Several advanced options such as Time Zone can be set when you can use the dbcli
command line interface to create databases.)
l Console Enabled: False

l Create Container Database: False for version 11.2.0.4 databases. Otherwise, true.
l Create Instance Only (for standby and migration): False
l Database Home ID: Creates a new database home
l Database Language: AMERICAN
l Database Sizing Template: odb2
l Database Storage: ACFS for version 11.2.0.4 databases. Otherwise, ASM.
l Database Territory: AMERICA
l Database Unique Name: The user-specified database name and a system-generated
suffix, for example, dbtst_phx1cs.
l PDB Admin Name: pdbuser (Not applicable for version 11.2.0.4 databases.)
For a list of the database options that you can set, see To launch a DB system.

CHAPTER 8 Database
Using the Console
To launch a DB system
1. Open the Console, click Database, choose your Compartment, and then click Launch
DB System.
2. In the Launch DB System dialog, enter the following:
Option Description
DB System Information
Compartment By default, the DB system launches in your current compartment

and you can use the network resources in that compartment. Click
the click here link in the dialog box if you want to enable
compartment selection for the DB system, network, and subnet
resources.
Display A friendly, display name for the DB system. The name doesn't need
Name to be unique. An Oracle Cloud Identifier (OCID) will uniquely
identify the DB system.
Availability The availability domain in which the DB system resides.

Domain

CHAPTER 8 Database
Option Description
Shape The shape to use to launch the DB system. The shape determines
the type of DB system and the resources allocated to the system.
Bare metal shapes:
nine 3.2 TB locally attached NVMe drives (28.8 TB total) to the
DB system.
eight 6.4 TB locally attached NVMe drives (51.2 TB total) to
the DB system.
Exadata shapes:
l Exadata.Quarter1.84: Provides a 2-node Exadata
DB System with 22 enabled CPU cores, with up to 62
additional CPU cores, 720 GB RAM per node, 288 TB of raw
storage, 84 TB of usable storage, and unlimited I/O. This
shape supports only the Enterprise Edition - Extreme
Performance.
l Exadata.Half1.168: Provides a 4-node Exadata DB System
l Exadata.Full1.336: Provides an 8-node Exadata DB System

CHAPTER 8 Database
Option Description

cores.
cores.
cores.
16 cores.
cores.
cores.
cores.
16 cores.
24 cores.

CHAPTER 8 Database
Option Description
Cluster Name A unique cluster name for a multi-node DB system. The name must
begin with a letter and contain only letters (a-z and A-Z), numbers
(0-9) and hyphens (-). The cluster name can be no longer than 11
characters and is not case sensitive.
Total Node The number of nodes in the DB system. The number depends on the
Count shape you select. You can specify 1 or 2 nodes for virtual machine
DB systems except for VM.Standard1.1, which is a single-node DB
system.
Oracle The database edition supported by the DB system. You can mix
Database supported database versions on the DB system, but not editions.
Software (The database edition cannot be changed and applies to all the
Edition databases in this DB system.)
CPU Core The number of CPU cores for the DB system. Displays only if you
Count select a shape that allows you to configure the number of cores. The
text below the field indicates the acceptable values for that shape.
For a multi-node DB system, the core count is evenly divided across
the nodes.
Bare metal DB systems only: You can increase the CPU cores to
accommodate increased demand after you launch the DB system.

CHAPTER 8 Database
Option Description
License Type The type of license you want to use for the DB system. Your choice
affects metering for billing.
License included means the cost of the cloud service includes a
license for the Database service.
Bring Your Own License (BYOL) means you are an Oracle
Database customer with an Unlimited License Agreement or Non-
Unlimited License Agreement and want to use your license with
Oracle Cloud Infrastructure. This removes the need for separate on-
premises licenses and cloud licenses.
SSH Public The public key portion of the key pair you want to use for SSH
Key access to the DB system. To provide multiple keys, paste each key
on a new line. Make sure each key is on a single, continuous line.
The length of the combined keys cannot exceed 10,000 characters.
Data Storage The percentage (40% or 80%) assigned to DATA storage (user data
Percentage and database files). The remaining percentage is assigned to RECO
storage (database redo logs, archive logs, and recovery manager
backups).
Disk The type of redundancy configured for the DB system.

Redundancy Normal is 2-way mirroring, recommended for test and
development systems.
High is 3-way mirroring, recommended for production systems.
Network Information
Virtual Cloud The compartment containing the network in which to launch the DB
Network system.
Compartment

CHAPTER 8 Database
Option Description
Virtual Cloud The VCN in which to launch the DB system.

Network
Subnet The compartment containing a subnet within the cloud network to

Compartment attach the DB system to.
Client Subnet The subnet to which the DB system should attach.

For Exadata DB systems: Do not use a subnet that overlaps with
192.168.128.0/20. This restriction applies to both the client subnet
and backup subnet.
For 1- and 2-node RAC DB systems: You must use a public subnet.
Do not use a subnet that overlaps with 192.168.16.16/28, which is
used by the Oracle Clusterware private interconnect on the
database instance. Specifying an overlapping subnet will cause the
private interconnect to malfunction.
Backup For Exadata DB systems only. The subnet to use for the backup
Subnet network , which is typically used to transport backup information to
and from Oracle Cloud Infrastructure Object Storage, and for Data
Guard replication.
Do not use a subnet that overlaps with 192.168.128.0/20. This
restriction applies to both the client subnet and backup subnet.
If you plan to back up databases to Object Storage, see the network
prerequisites in Backing Up an Exadata Database.

CHAPTER 8 Database
Option Description
Hostname Your choice of host name for the DB system. The host name must
Prefix begin with an alphabetic character and can contain a maximum of
30 alphanumeric characters, including hyphens (-).
Note: The host name must be unique within the subnet. If it is not
unique, the DB system will fail to provision.
Host Domain The domain name for the DB system. If the selected subnet uses the
Name Oracle-provided Internet and VCN Resolver for DNS name
resolution, this field displays the domain name for the subnet and it
can't be changed. Otherwise, you can provide your choice of a
domain name. Hyphens (-) are not permitted.
For Exadata DB systems, if you plan to store database backups in
Object Storage, Oracle recommends using a VCN Resolver for DNS
name resolution for the client subnet as it automatically resolves
the Swift endpoints used for backups.
Host and Combines the host and domain names to display the fully qualified
Domain URL domain name (FQDN) for the database. The maximum length is 64
characters.
Database Information
Database The name for the database. The database name must begin with an
Name alphabetic character and can contain a maximum of eight
alphanumeric characters. Special characters are not permitted.

CHAPTER 8 Database
Option Description
Database The version of the initial database created on the DB system when it
Version is launched. After the DB system is active, you can create additional
databases by using the command line interface available on the DB
system. You can mix database versions on the DB system, but not
editions.
PDB Name Not applicable to version 11.2.0.4. The name of the pluggable
database. The PDB name must begin with an alphabetic character
and can contain a maximum of 30 alphanumeric characters. The
only special character permitted is the underscore ( _).
Database A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin.
Admin The password must be nine to thirty characters and contain at least
Password two uppercase, two lowercase, two numeric, and two special
characters. The special characters must be _, #, or -.
Confirm The same as above.

Database
Admin
Password
Automatic Check the check box to enable automatic incremental backups for
Backup: this database.

CHAPTER 8 Database
Option Description
Database Select the workload type that best suits your application.
Workload Online Transactional Processing (OLTP) configures the
database for a transactional workload, with a bias towards high
volumes of random data access.
Decision Support System (DSS) configures the database for a
decision support or data warehouse workload, with a bias towards
large data scanning operations.
Character The character set for the database. The default is AL32UTF8.
Set
National The national character set for the database. The default is
Character AL16UTF16.
Set
Tags Optionally, you can apply tags. If you have permissions to create a
resource. To apply a defined tag, you must have permissions to use
the tag namespace. For more information about tagging, see
Resource Tags. If you are not sure if you should apply tags, skip this
option (you can apply tags later) or ask your administrator.
3. Click Launch DB System.

The DB system appears in the list with a status of Provisioning. The DB system's icon
changes from yellow to green (or red to indicate errors).
4. Wait for the DB system's icon to turn green, with a status of Available, and then click
the highlighted DB system name.
Details about the DB system are displayed.
5. Note the IP addresses; you'll need the private or public IP address, depending on
network configuration, to connect to the DB system.

CHAPTER 8 Database
To check the status of a DB system

2. In the list of DB systems, find the system you're interested in and check its icon. The
color of the icon and the text below it indicates the status of the system.
l Provisioning: Yellow icon. Resources are being reserved for the DB system, the
system is booting, and the initial database is being created. Provisioning can take
several minutes. The system is not ready to use yet.
l Available: Green icon. The DB system was successfully provisioned. A few
minutes after the system enters this state, you can SSH to it and begin using it.
l Starting: Yellow icon. The DB system is being powered on by the start or reboot
l Stopping: Yellow icon. The DB system is being powered off by the stop or reboot
l Stopped: Yellow icon. The DB system was powered off by the stop action in the
Console or API.
l Terminating: Gray icon. The DB system is being deleted by the terminate action
l Terminated: Gray icon. The DB system has been deleted and is no longer
available.
l Failed: Red icon. An error condition prevented the provisioning or continued
operation of the DB system.
You can also check the status of DB systems and database nodes by using the ListDbSystems
or ListDbNodes API operations, which return the lifecycleState attribute.

CHAPTER 8 Database
To start, stop, or reboot a DB system
Tip
Oracle recommends that you run a Network Time

Protocol (NTP) daemon to keep system clocks stable
during rebooting. If you need information about an NTP
daemon, see Setting Up “NTP (Network Time Protocol)
Server” in RHEL/CentOS 7.
2. In the list of DB systems, find the DB system you want to stop or start, and then click its
3. In the list of nodes, click the Actions icon ( ) for a node and then click one of the
following actions:
l Start: Restarts a stopped node. After the node is restarted, the Stop action is
enabled.
l Stop: Shuts down the node. After the node is powered off, the Start action is
enabled.
l Reboot: Shuts down the node, and then restarts it.

CHAPTER 8 Database
Note
Resource billing differs between bare metal

and virtual machine DB systems as follows:
l Bare metal DB systems - The Stop state has
no effect on the resources you consume.
Billing continues for nodes that you stop, and
related resources continue to apply against
any relevant quotas. You must Terminate a
DB system to remove its resources from
billing and quotas.
l Virtual machine DB systems - Stopping a
node stops billing for all OCPUs associated
with that node. Billing resumes if you restart
the node.
To scale the CPU cores for a bare metal DB system

If a multi-node DB system requires more compute node processing power, you can scale up
(burst) the number of enabled CPU cores in the system.
Note
You cannot change the number of CPU cores for a virtual

machine DB system.
name.

CHAPTER 8 Database

3. Click Scale Up/Down and then change the number in Total CPU Core Count. The
text below the field indicates the acceptable values, based on the shape used when the
DB system was launched.
4. Click Scale Up/Down DB System.
To scale up the storage for a virtual machine DB system

If a virtual machine DB system requires more block storage, you can increase the storage at
any time without impacting the system.
Note
This procedure does not apply to bare metal DB

systems.
2. In the list of DB systems, find the system you want to scale up and click its highlighted
name.
3. Click Scale Storage Up, and then select the new storage size from the drop-down list.
4. Click Scale Storage Up.
To terminate a DB system
Terminating a DB system permanently deletes it and any databases running on it.

CHAPTER 8 Database
Note
The database data is local to the DB system and will be

lost when the system is terminated. Oracle
recommends that you back up any data in the DB
system prior to terminating it.
Terminating a DB system removes all automatic

incremental backups of all databases in the DB system
from Oracle Cloud Infrastructure Object Storage. Full
backups remain in Object Storage as standalone
backups which you can use to create a new database.
See To create a database from a standalone backup.
2. For the DB system you want to terminate, click the Actions icon ( ) and then click
Terminate.
The DB system's icon indicates Terminating.
At this point, you cannot connect to the system and any open connections will be terminated.
To manage your BYOL database licenses

If you want to control the number of database licenses that you run at any given time, you can
scale up or down the number of OCPUs on the instance. These additional licenses are metered
separately.
name.

CHAPTER 8 Database

3. Click Scale Up/Down OCPU, and then change the number.
To manage tags for your DB systems and database resources

2. Find the DB system or database resource you're interested in, and click the name.
3. Click the Tags tab to view or edit the existing tags. Or click Apply tags(s) to add new
ones.
Using the API
Use these API operations to manage DB system components.
DB systems:
l GetDbSystem
l LaunchDbSystem
l ListDbSystems
l TerminateDbSystem
Database homes:
l GetDbHome
l ListDbHomes
Databases:
l GetDatabase
l ListDatabases

CHAPTER 8 Database
Nodes:
l DbNodeAction: Use this operation to power cycle a node in the DB system.

l ListDbNodes
l GetDbNode
Shapes and database versions:
l ListDbSystemShapes
l ListDbVersions
For the complete list of APIs for the Database service, see Database Service API.
Setting up DNS for a DB System
DNS lets you use host names instead of IP addresses to communicate with a DB system. You
can use the Internet and VCN Resolver (the DNS capability built into the VCN) as described in
DNS in Your Virtual Cloud Network.
Alternatively, you can use your choice of DNS server. You associate the host name and
domain name to the public or private IP address of the DB system. You can find the host and
domain names and IP addresses for the DB system in the Oracle Cloud Infrastructure Console
on the Database page.
To associate the host name to the DB system's public or private IP address, contact your
DNS administrator and request a custom DNS record for the DB system’s IP address. For
example, if your domain is example.com and you want to use clouddb1 as the host name, you
would request a DNS record that associates clouddb1.example.com to your DB system's IP
address.
If you provide the public IP address to your DNS administrator as described above, you should
also associate a custom domain name to the DB system's public IP address:
1. Register your domain name through a third-party domain registration vendor, such as
register.com.

CHAPTER 8 Database
2. Resolve your domain name to the DB system's public IP address, using the third-party
domain registration vendor console. For more information, refer to the third-party
domain registration documentation.
Connecting to a DB System
This topic explains how to connect to an active DB System using SSH or SQL Developer. How
you connect depends on how your cloud network is set up. You can find information on various
networking scenarios in Overview of Networking, but for specific recommendations on how
you should connect to a database in the cloud, contact your network security administrator.
Prerequisites
For SSH access to the DB System, you'll need the following:
l The full path to the file that contains the private key associated with the public key used
when the DB System was launched.
l The public or private IP address of the DB System. Use the private IP address to
network (VCN). This includes connecting from a host located on-premises connecting
through a VPN to your VCN, or from another host in the same VCN. Use the DB System's
public IP address to connect to the system from outside the cloud (with no VPN). You
can find the IP addresses in the Oracle Cloud Infrastructure Console on the Database
page.
If you have problems connecting, see Troubleshooting Connection Issues.
Connecting to a DB System with SSH
You can connect to a DB System by using a Secure Shell (SSH) connection. Most UNIX-style
systems (including Linux, Solaris, BSD, and OS X) include an SSH client by default. For
Windows, you can download a free SSH client called PuTTY from http://www.putty.org.
When connecting to a multi-node DB System, you'll SSH to each individual node in the cluster.

CHAPTER 8 Database
To connect from a UNIX-style system

Use the following SSH command to access the DB System:
$ ssh –i <private key> opc@<DB System IP address>
<private key> is the full path and name of the file that contains the private key associated
with the DB System you want to access.
Use the DB System's private or public IP address depending on your network configuration.
For more information, see Prerequisites.
To connect from a Windows system

1. Open putty.exe.
2. In the Category pane, select Session and enter the following fields:
l Host Name (or IP address): opc@<DB System IP address>
Use the DB System's private or public IP address depending on your network
configuration. For more information, see Prerequisites.
l Port: 22
3. In the Category pane, expand Connection, expand SSH, and then click Auth, and
browse to select your private key.
4. Optionally, return to the Session category screen and save this session information for
reuse later.
To access a database after you connect


CHAPTER 8 Database
login as: opc
[opc@ed1db01 ~]$ sudo su -
2. Set the environment to the ASM instance. Depending on which node you are connecting
to, the ASM instance ID will vary, for example, +ASM1 , +ASM2, and so on.
[root@ed1db01 ]# . oraenv
ORACLE_SID = [root] ? +ASM1
3. List all the databases on the system.

root@ed1db01 ]# srvctl config database -v
cdbm01 /u02/app/oracle/product/12.1.0/dbhome_2 12.1.0.2.0

exadb /u02/app/oracle/product/11.2.0/dbhome_2 11.2.0.4.0
mmdb /u02/app/oracle/product/12.1.0/dbhome_3 12.1.0.2.0
4. Connect as the oracle user and get the details about one of the databases using srvctl
command.
[root@ed1db01 ~]# su - oracle
[oracle@ed1db01 ~]$ . oraenv
ORACLE_SID = [oracle] ? cdbm01
The Oracle base has been set to /u02/app/oracle
[oracle@ed1db01 ~]$ srvctl config database -d cdbm01
Database unique name: cdbm01 <<== DB unique name
Database name:
Oracle home: /u02/app/oracle/product/12.1.0/dbhome_2
Oracle user: oracle
Spfile: +DATAC1/cdbm01/spfilecdbm01.ora
Password file: +DATAC1/cdbm01/PASSWORD/passwd
Domain: data.customer1.oraclevcn.com
Start options: open
Stop options: immediate
Database role: PRIMARY
Management policy: AUTOMATIC
Server pools:
Disk Groups: DATAC1,RECOC1
Mount point paths:
Services:

CHAPTER 8 Database
Type: RAC
Start concurrency:
Stop concurrency:
OSDBA group: dba
OSOPER group: racoper
Database instances: cdbm011,cdbm012 <<== SID
Configured nodes: ed1db01,ed1db02
Database is administrator managed
5. (Skip this step for Exadata DB Systems.) Set the ORACLE_SID and ORACLE_UNIQUE_
NAME using the values from the previous step.
[oracle@ed1db01 ~]$ export ORACLE_UNIQUE_NAME=cdbm01
[oracle@ed1db01 ~]$ export ORACLE_SID=cdbm011
[oracle@ed1db01 ~]$ sqlplus / as sysdba
SQL*Plus: Release 12.1.0.2.0 Production on Wed Apr 19 04:10:12 2017
Copyright (c) 1982, 2014, Oracle. All rights reserved.
Connected to:
Oracle Database 12c EE Extreme Perf Release 12.1.0.2.0 - 64bit Production
With the Partitioning, Real Application Clusters, Automatic Storage Management, Oracle Label
Security,
OLAP, Advanced Analytics and Real Application Testing options
Connecting to a Database with SQL Developer
You can connect to a database with SQL Developer by using one of the following methods:
l Create a temporary SSH tunnel from your computer to the database. This method
provides access only for the duration of the tunnel. (When you are done using the
database, be sure to close the SSH tunnel by exiting the SSH session.)
l Open port 1521 for the Oracle default listener by updating the security list used for the
DB System. This method provides more durable access to the database. For more
information, see Updating the Security List for the DB System.

CHAPTER 8 Database
CONNECTING TO A DATABASE ON A 1-NODE DB S YSTEM
After you've created an SSH tunnel or opened port 1521 as described above, start your SQL
Developer client and create a connection using the following connection details:
l Username: sys as sysdba

l Password: The Database Admin Password that was specified in the Launch DB
System dialog in the Console.
l Hostname: localhost if using an SSH tunnel, or the public IP address of the DB System
if not using a tunnel.
l Port: 9999 (or the port of your choice) if using an SSH tunnel, or 1521 if not using a
tunnel.
l Service name: The concatenated Database Unique Name and Host Domain
Name, for example, db1_phx1tv.mycompany.com. You can find both these names in
the Console by clicking Database and then clicking the DB System name for details.
CONNECTING TO A DATABASE ON A MULTI-NODE DB S YSTEM
After you've created an SSH tunnel or opened port 1521 as described above, you can connect
to a multi-node DB System using SCAN IP addresses or public IP addresses, depending on
how your network is set up and where you are connecting from. You can find the IP addresses
in the Console, in the Database details page.
To connect using SCAN IP addresses

You can connect to the database using the SCAN IP addresses if your client is on-premises and
you are connecting using a FastConnect or VPN connection. You have the following options:
l Use the private SCAN IP addresses, as shown in the following tnsnames.ora example:
testdb=
(DESCRIPTION =
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP1>)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP2>)(PORT = 1521)))

CHAPTER 8 Database
(CONNECT_DATA =
)
)
l Define an external SCAN name in your on-premises DNS server. Your application can
resolve this external SCAN name to the DB System's private SCAN IP addresses, and
then the application can use a connection string that includes the external SCAN name.
In the following tnsnames.ora example, extscanname.example.com is defined in the
on-premises DNS server.
testdb =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = <extscanname.example.com>)(PORT = 1521))
(CONNECT_DATA =
)
)
To connect using public IP addresses

You can use the node's public IP address to connect to the database if the client and database
are in different VCNs, or if the database is on a VCN that has an internet gateway. However,
there are important implications to consider:
l When the client uses the public IP address, the client bypasses the SCAN listener and
reaches the node listener, so server side load balancing is not available.
l When the client uses the public IP address, it cannot take advantage of the VIP failover
feature. If a node becomes unavailable, new connection attempts to the node will hang
until a TCP/IP timeout occurs. You can set client side sqlnet parameters to limit the
TCP/IP timeout.
The following tnsnames.ora example shows a connection string that includes the CONNECT_
TIMEOUT parameter to avoid TCP/IP timeouts.

CHAPTER 8 Database
test=
(DESCRIPTION =
(CONNECT_TIMEOUT=60)
(ADDRESS_LIST=
)
(CONNECT_DATA =
)
)
Troubleshooting Connection Issues
The following issues might occur when connecting to a DB System or database.
ORA-28365: W ALLET IS NOT OPEN ERROR
For a 1-node DB System or 2-node RAC DB System, regardless of how you connect to the DB
System, before you use OS authentication to connect to a database (for example, sqlplus /
as sysdba) be sure to set the ORACLE_UNQNAME variable. Otherwise, commands that
require the TDE wallet will result in the error ORA-28365: wallet is not open.
Note that this is not an issue when using a TNS connection because ORACLE_UNQNAME is
automatically set in the database CRS resource.
SSH ACCESS S TOPS W ORKING
If the DB System’s root volume becomes full, you might lose the ability to SSH to the system
(the SSH command will fail with permission denied errors). Before you copy a large amount
of data to the root volume, for example, to migrate a database, use the dbcli create-
dbstorage command to set up storage on the system’s NVMe drives and then copy the
database files to that storage. For more information, see Setting Up Storage on the
DB System.
WHAT NEXT?
Before you begin updating your DB System, review the information in Updating a DB System.

CHAPTER 8 Database
For information about setting up an Enterprise Manager console to monitor your databases,
see Monitoring a Database.
Updating a DB System
Note
This topic is not applicable to Exadata DB systems. For

information on how to update an Exadata DB system,
see Updating an Exadata DB System
This topic includes information and instructions on how to update the OS of a bare metal or
virtual machine DB system. Review all of the information before you begin updating the
system.
Bash Profile Updates
Do not add interactive commands such as oraenv, or commands that might return an error or
warning message, to the .bash_profile file for the grid or oracle users. Adding such
commands can prevent Database service operations from functioning properly.
For a 1-node DB system or 2-node RAC DB system, do not remove or modify the following
firewall rules in /etc/sysconfig/iptables:
l The firewall rules for ports 1521, 7070, and 7060 allow the Database service to manage
the DB system. Removing or modifying them can result in the Database Service no
longer operating properly.
l The firewall rules for 169.254.0.2:3260 and 169.254.0.3:80 prevent non-root users from
escalating privileges and tampering with the system’s boot volume and boot process.
Removing or modifying these rules can allow non-root users to modify the system's
boot volume.

CHAPTER 8 Database
OS Updates
Important
l Do not remove packages from a DB system.

However, you might have to remove custom RPMs
(packages that were installed after the system
was provisioned) for the update to complete
successfully.
l Oracle recommends that you test any updates
thoroughly before updating a production system.
l The image used to launch a DB system is updated
regularly with the necessary patches. After you
launch a DB system, you are responsible for
applying the required OS security updates
published through the Oracle public Yum server.
l The DB system's VCN must be configured with an
internet gateway to apply updates.
To update the DB system OS
Note
You can update the OS on 2-node RAC virtual machine

DB systems in a rolling fashion. Ensure that you bring
down the clusterware cleanly before starting the update
process.

CHAPTER 8 Database
1. Log on to the DB system host as opc, and then sudo to the root user.
login as: opc
2. Identify the host region by running the following command:

# curl -s http://169.254.169.254/opc/v1/instance/ |grep region
3. With the region you noted from the previous step, determine the region name, and
perform the following two steps.
See Regions and Availability Domains to look up the region name.
a. Download the repo.
# wget https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/oci_dbaas_ol6repo -O /tmp/oci_
dbaas_ol6repo
This example output assumes the region is Phoenix (PHX).

# wget https://swiftobjectstorage.us-phoenix-
1.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/oci_dbaas_ol6repo -O /tmp/oci_dbaas_
ol6repo
--2018-03-16 10:40:42-- https://swiftobjectstorage.us-phoenix-
1.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/oci_dbaas_ol6repo
Resolving swiftobjectstorage.us-phoenix-1.oraclecloud.com... 129.146.13.177,
129.146.13.180, 129.146.12.235, ...
Connecting to swiftobjectstorage.us-phoenix-1.oraclecloud.com|129.146.13.177|:443...
connected.
HTTP request sent, awaiting response... 200 OK
Length: 1394 (1.4K) [binary/octet-stream]
Saving to: `/tmp/oci_dbaas_ol6repo'
100%
[=========================================================================================
==========================================================================================
===================================================>] 1,394 --.-K/s in 0s
2018-03-16 10:40:42 (34.5 MB/s) - `/tmp/oci_dbaas_ol6repo' saved [1394/1394]
b. Download the version lock files.

CHAPTER 8 Database
# wget https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/versionlock.list_180209 -O
/tmp/versionlock.list_180209
This example output assumes the region is Phoenix (PHX).

# wget https://swiftobjectstorage.us-phoenix-
1.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/versionlock.list_180209 -O
/tmp/versionlock.list_180209
--2018-03-16 10:41:38-- https://swiftobjectstorage.us-phoenix-
1.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/versionlock.list_180209
Resolving swiftobjectstorage.us-phoenix-1.oraclecloud.com... 129.146.12.224,
129.146.12.164, 129.146.14.172, ...
Connecting to swiftobjectstorage.us-phoenix-1.oraclecloud.com|129.146.12.224|:443...
connected.
HTTP request sent, awaiting response... 200 OK
Length: 15769 (15K) [binary/octet-stream]
Saving to: `/tmp/versionlock.list_180209'
100%
[=========================================================================================
==========================================================================================
===================================================>] 15,769 --.-K/s in 0.1s
2018-03-16 10:41:39 (123 KB/s) - `/tmp/versionlock.list_180209' saved [15769/15769]
4. Enable the repo for your region.

a. Copy the repo file to the /etc/yum.repos.d directory.
cp /tmp/oci_dbaas_ol6repo /etc/yum.repos.d/ol6.repo
b. Modify the ol6.repo file to enable the repo for your region.
vi /etc/yum.repos.d/ol6.repo
[ol6_latest_PHX]
name=Oracle Linux $releasever Latest ($basearch)
baseurl=http://yum-phx.oracle.com/repo/OracleLinux/OL6/latest/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
gpgcheck=1
enabled=1 <= Enabled.

CHAPTER 8 Database
[ol6_UEKR4_PHX]
name=Latest Unbreakable Enterprise Kernel Release 4 for Oracle Linux $releasever
($basearch)
baseurl=http://yum-phx.oracle.com/repo/OracleLinux/OL6/UEKR4/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
gpgcheck=1
enabled=1 <= Enabled.
5. Install yum-plugin-versionlock.
$ sudo su -
# yum repolist
Loaded plugins: kernel-update-handler, security, ulninfo
ol6_UEKR4
| 1.2 kB 00:00
ol6_UEKR4/primary
| 29 MB 00:00
ol6_UEKR4
588/588
ol6_latest
| 1.4 kB 00:00
ol6_latest/primary
| 67 MB 00:00
ol6_latest
39825/39825
repo id repo name
status
ol6_UEKR4 Latest Unbreakable Enterprise Kernel Release 4 for Oracle
Linux 6Server (x86_64) 588
ol6_latest Oracle Linux 6Server Latest (x86_64)
39825
repolist: 40413
[root@jigsosupg ~]# yum install yum-plugin-versionlock
Loaded plugins: kernel-update-handler, security, ulninfo
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package yum-plugin-versionlock.noarch 0:1.1.30-40.0.1.el6 will be installed
--> Finished Dependency Resolution
Dependencies Resolved

CHAPTER 8 Database
=================================================================================================
=====================================================
Package Arch Version
Repository Size
=================================================================================================
=====================================================
Installing:
yum-plugin-versionlock noarch 1.1.30-40.0.1.el6
ol6_latest 32 k
Transaction Summary
=================================================================================================
=====================================================
Install 1 Package(s)
Total download size: 32 k

Installed size: 43 k
Is this ok [y/N]: y
Downloading Packages:
yum-plugin-versionlock-1.1.30-40.0.1.el6.noarch.rpm
| 32 kB 00:00
warning: rpmts_HdrFromFdno: Header V3 RSA/SHA256 Signature, key ID ec551f03: NOKEY
Retrieving key from file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
Importing GPG key 0xEC551F03:
Userid : Oracle OSS group (Open Source Software group) <build@oss.oracle.com>
Package: 6:oraclelinux-release-6Server-8.0.3.x86_64 (@odadom1)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
Is this ok [y/N]: y
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Warning: RPMDB altered outside of yum.
** Found 4 pre-existing rpmdb problem(s), 'yum check' output follows:
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of
/usr/local/bin/perl

CHAPTER 8 Database
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of libnfsodm12.so()

(64bit)
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of perl
(GridDefParams)
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of perl(s_GridSteps)
Installing : yum-plugin-versionlock-1.1.30-40.0.1.el6.noarch
1/1
Verifying : yum-plugin-versionlock-1.1.30-40.0.1.el6.noarch
1/1
Installed:
yum-plugin-versionlock.noarch 0:1.1.30-40.0.1.el6
Complete!
Note
Ignore the RPMDB warning messages that refer to

oda-hw-mgmt.
6. Copy and overwrite the existing version lock file.

cp /etc/yum/pluginconf.d/versionlock.list /etc/yum/pluginconf.d/versionlock.list-`date +%Y%m%d`
cp /tmp/versionlock.list_180209 /etc/yum/pluginconf.d/versionlock.list
The initial version lock file should be empty. However, it is a good practice to back it up
in case it is not and you need to refer to it later.
7. Run the update command.
# yum update
Loaded plugins: kernel-update-handler, security, ulninfo, versionlock
Setting up Update Process
Resolving Dependencies
--> Running transaction check
---> Package kernel-uek.x86_64 0:4.1.12-112.14.13.el6uek will be installed
---> Package kernel-uek-firmware.noarch 0:4.1.12-112.14.13.el6uek will be installed
---> Package linux-firmware.noarch 0:20160616-44.git43e96a1e.0.12.el6 will be updated
---> Package linux-firmware.noarch 0:20171128-56.git17e62881.0.2.el6 will be an update

CHAPTER 8 Database
--> Finished Dependency Resolution
Dependencies Resolved
=================================================================================================
=====================================================
Package Arch Version
Repository Size
=================================================================================================
=====================================================
Installing:
kernel-uek x86_64 4.1.12-112.14.13.el6uek
ol6_UEKR4 51 M
kernel-uek-firmware noarch 4.1.12-112.14.13.el6uek
ol6_UEKR4 2.4 M
Updating:
linux-firmware noarch 20171128-56.git17e62881.0.2.el6
ol6_UEKR4 74 M
Transaction Summary
=================================================================================================
=====================================================
Install 2 Package(s)
Upgrade 1 Package(s)
Total download size: 128 M

Is this ok [y/N]:y
Downloading Packages:
(1/3): kernel-uek-4.1.12-112.14.13.el6uek.x86_64.rpm
| 51 MB 00:00
(2/3): kernel-uek-firmware-4.1.12-112.14.13.el6uek.noarch.rpm
| 2.4 MB 00:00
(3/3): linux-firmware-20171128-56.git17e62881.0.2.el6.noarch.rpm
| 74 MB 00:00
-------------------------------------------------------------------------------------------------
-----------------------------------------------------
Total

CHAPTER 8 Database
214 MB/s | 128 MB 00:00

Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : kernel-uek-firmware-4.1.12-112.14.13.el6uek.noarch
1/4
Updating : linux-firmware-20171128-56.git17e62881.0.2.el6.noarch
2/4
Installing : kernel-uek-4.1.12-112.14.13.el6uek.x86_64
3/4
Cleanup : linux-firmware-20160616-44.git43e96a1e.0.12.el6.noarch
4/4
ol6_UEKR4/filelists
| 18 MB 00:00
Uploading /boot/vmlinuz-4.1.12-112.14.13.el6uek.x86_64 to http://169.254.0.3/kernel
Uploading /boot/initramfs-4.1.12-112.14.13.el6uek.x86_64.img to http://169.254.0.3/initrd
Uploading /tmp/tmp5HjrRUcmdline to http://169.254.0.3/cmdline
Error activating kernel/initrd/cmdline: 502 - <html>

<head><title>502 Bad Gateway</title></head>
<body bgcolor="white">
<center><h1>502 Bad Gateway</h1></center>
</body>
</html>
Note
Ignore the error activating message that results

from running the update.
8. Restart the system.

$ sudo su -
# reboot
9. Run the following command to validate the update:

CHAPTER 8 Database
# uname -r
4.1.12-112.14.13
In this example, then new kernel version is 4.1.12-112.14.13.
For information about applying Oracle database patches to a DB system, see Patching a DB
System.
Configuring a DB System
This topic provides information to help you configure your DB System.
Network Time Protocol
Oracle recommends that you run a Network Time Protocol (NTP) daemon on your 1-node
DB Systems to keep system clocks stable during rebooting. If you need information about an
NTP daemon, see Setting Up “NTP (Network Time Protocol) Server” in RHEL/CentOS 7.
Oracle recommends that you configure NTP on both nodes in a 2-node RAC DB System to
synchronize time across the nodes. If you do not configure NTP, then Oracle Clusterware
configures and uses the Cluster Time Synchronization Service (CTSS), and the cluster time
might be out-of-sync with applications that use NTP for time synchronization.
For information about configuring NTP on a version 12c database, see Setting Network Time
Protocol for Cluster Time Synchronization. For a version 11g database, see Network Time
Protocol Setting.
Transparent Data Encryption
All user-created tablespaces in a DB System database are encrypted by default, using

Transparent Data Encryption (TDE).
l For version 12c databases, if you don’t want your tablespaces encrypted, you can set
the ENCRYPT_NEW_TABLESPACES database initialization parameter to DDL.
l On a 1- or 2-node RAC DB System, you can use the dbcli update-tdekey command to
update the master encryption key for a database.

CHAPTER 8 Database
l You must create and activate a master encryption key for any PDBs that you create.
After creating or plugging in a new PDB on a 1- or 2-node RAC DB System, use the
dbcli update-tdekey command to create and activate a master encryption key for the
PDB. Otherwise, you might encounter the error ORA-28374: typed master key not
found in wallet when attempting to create tablespaces in the PDB. In a multitenant
environment, each PDB has its own master encryption key which is stored in a single
keystore used by all containers. For more information, see "Overview of Managing a
Multitenant Environment" in the Oracle Database Administrator’s Guide.
l For information about encryption on Exadata DB Systems, see Using Tablespace
Encryption in Exadata Cloud Service.
For detailed information about database encryption, see the Oracle Database Security White
Papers.
Patching a DB System
Note
This topic is not applicable to Exadata DB systems.
This topic explains how to perform patching operations on DB systems and database homes by
using the Console, API, or the database CLI (DBCLI).
Currently, the following patches are available:
Version DB System Patch Database Patch
12.2.0.1 January 2018 January 2018, October 2017, August 2017
12.1.0.2 January 2018 January 2018, October 2017, August 2017
11.2.0.4 Not applicable January 2018, October 2017, August 2017
For information about operating system updates, see OS Updates.

CHAPTER 8 Database
Required IAM Policy
Before You Begin
l Ensure that the DB system's cloud network (VCN) is configured with an internet
gateway. Note that the network traffic between the DB system and Object Storage does
not leave the cloud and never reaches the public internet. For more information, see
Connectivity to the Internet.
l Because patching a system requires a reboot, plan to run the operations at a time when
they will have minimal impact on users. To avoid system interruption, consider
implementing a high availability strategy such as Oracle Data Guard. For more
information, see Using Oracle Data Guard with the Database CLI.
l Oracle recommends that you back up your database and test the patch on a test system
before you apply the patch. For information about backing up the databases, see
Backing Up a Database.
l If a patch operation fails, you can view details about the operation by accessing the logs
on a host. For help with troubleshooting a failed operation, contact Oracle Support. See
Contacting Support.
l You must patch a DB system before you patch the databases within that system.

CHAPTER 8 Database
Using the Console
You can use the Console to view the history of patch operations on a DB system or an
individual database, apply patches, and monitor the status of an operation.
You can also use the pre-check action to ensure your DB system or database home has met
the requirements for the patch you want to apply.
PERFORMING PATCH OPERATIONS
To perform a patch operation on a DB system

2. Find the DB system on which you want to perform a patch operation, and click its name
to display details about it.
3. Under Resources, click Patches.
4. Review the list of patches.
5. Click the Actions icon ( ) for the patch you are interested in, and then click one of
the following actions:
l Pre-check: Check for any prerequisites to make sure that the patch can be
successfully applied.
l Apply: Performs the pre-check, and then applies the patch.
7. In the list of patches, click the patch name to display its patch request and monitor the
progress of the patch operation.
While a patch is being applied, the patch's status displays as Applying and the DB
system's status displays as Updating. If the operation completes successfully, the
patch's status changes to Applied and the DB system's status changes to Available.

CHAPTER 8 Database
To perform a patch operation on a database

2. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
3. Find the database on which you want to perform the patch operation, and click its name
to display details about it.
4. Under Resources, click Patches.
5. Review the list of patches.
6. Click the Actions icon ( ) for the patch you are interested in, and then click one of
the following actions:
l Pre-check: Check for any prerequisites to make sure that the patch can be
successfully applied.
l Apply: Performs the pre-check, and then applies the patch.
8. In the list of patches, click the patch name to display its patch request and monitor the
progress of the patch operation.
While a patch is being applied, the patch's status displays as Applying and the
database's status displays as Updating. If the operation completes successfully, the
patch's status changes to Applied and the database's status changes to Available.
VIEWING PATCH HISTORY
Each patch history entry represents an attempted patch operation and indicates whether the
operation was successful or failed. You can retry a failed patch operation. Repeating an
operation results in a new patch history entry.
Patch history views in the Console do not show patches that were applied by using command
line tools like DBCLI or the Opatch utility.

CHAPTER 8 Database
To view the patch history of a DB system

2. Find the DB system you are interested in, and click the system name to display details
about it.
3. Under Resources, click Patch History.
The history of patch operations for that DB system is displayed.
To view the patch history of a database

2. Find the DB system where the database is located, and click the system name to display
details about it.
3. Find the database you are interested in, and click its name to display details about it.
4. Under Resources, click Patch History.
The history of patch operations for that database is displayed.
Using the API
Use these API operations to manage patching DB systems and databases.
DB systems:
l ListDbSystemPatches
l ListDbSystemPatchHistoryEntries
l GetDbSystemPatch

CHAPTER 8 Database
l GetDbSystemPatchHistoryEntry
l UpdateDbSystem
Databases:
l ListDbHomePatches
l ListDbHomePatchHistoryEntries
l GetDbHomePatch
l GetDbHomePatchHistoryEntry
l UpdateDbHome
Using the Database CLI
This topic explains how to use the command line interface on the DB system to patch a DB
system. Patches are available from the Oracle Cloud Infrastructure Object Storage service.
You'll use the dbcli commands to download and apply patches to some or all of the
components in your system.
PREREQUISITES
For connecting to the DB system via SSH, you'll need the path to private key associated with
the public key used when the DB system was launched.
You also need the public or private IP address of the DB system. Use the private IP address to
network (VCN). This includes connecting from a host located on-premises connecting through
a VPN to your VCN, or from another host in the same VCN. Use the DB System's public IP
address to connect to the system from outside the cloud (with no VPN). You can find the IP
addresses in the Oracle Cloud Infrastructure Console on the Database page.
To update the CLI with the latest commands

Update the CLI to ensure you have the latest patching commands (older DB systems might not

CHAPTER 8 Database
include them).
1. SSH to the DB System.

ssh -i <private_key_path> opc@<db_system_ip_address>
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. Update the CLI by using the cliadm update-dbcli command.

[root@dbsys ~]# cliadm update-dbcli
{
"jobId" : "dc9ce73d-ed71-4473-99cd-9663b9d79bfd",
"status" : "Created",
"message" : "Dcs cli will be updated",
"reports" : [ ],
"createTimestamp" : "January 18, 2017 10:19:34 AM PST",
"resourceList" : [ ],
"description" : "dbcli patching",
"updatedTime" : "January 18, 2017 10:19:34 AM PST"
}
4. Wait for the update job to complete successfully. Check the status of the job by using
the dbcli list-jobs command.
[root@dbsys ~]# dbcli list-jobs
ID Description Created
Status
---------------------------------------- ------------------------------ -------------------------
---------- ----------
dc9ce73d-ed71-4473-99cd-9663b9d79bfd dbcli patching January 18, 2017 10:19:34
AM PST Success

CHAPTER 8 Database
To check for installed and available patches

login as: opc
3. Display the installed patch versions by using the dbcli describe-component command. If
the Available Version column indicates a version number for a component, you should
update the component.
[root@dbsys ~]# dbcli describe-component
System Version
---------------
12.1.2.10.0
Component Name Installed Version Available Version

---------------------------------------- -------------------- --------------------
OAK 12.1.2.10.0 up-to-date
GI 12.1.0.2.161018 up-to-date
ORADB12102_HOME1 12.1.0.2.160719 12.1.0.2.161018
4. Display the latest patch versions available in Object Storage by using the dbcli describe-
latestpatch command.
[root@dbsys ~]# dbcli describe-latestpatch
componentType availableVersion
--------------- --------------------
gi 12.1.0.2.161018
db 11.2.0.4.161018
db 12.1.0.2.161018
oak 12.1.2.10.0

CHAPTER 8 Database
To patch server components

You can patch the Grid Infrastructure (GI) and storage management kit (OAK) server
components.

login as: opc
3. Update the server components by using the dbcli update-server command.

[root@dbsys ~]# dbcli update-server
{
"jobId" : "9a02d111-e902-4e94-bc6b-9b820ddf6ed8",
"reports" : [ ],
"description" : "Server Patching",
}
Note the job ID above.

4. Check the job output by using the dbcli describe-job command with the job ID.
[root@dbsys ~]# dbcli describe-job -i 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Job details
----------------------------------------------------------------
ID: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Description: Server Patching
Status: Running
Created: January 19, 2017 9:37:11 AM PST

CHAPTER 8 Database
Message:
Task Name Start Time End Time

Status
---------------------------------------- ----------------------------------- --------------------
--------------- ----------
Create Patching Repository Directories January 19, 2017 9:37:11 AM PST January 19, 2017
9:37:11 AM PST Success
Download latest patch metadata January 19, 2017 9:37:11 AM PST January 19, 2017
Update System version January 19, 2017 9:37:11 AM PST January 19, 2017
Update Patching Repository January 19, 2017 9:37:11 AM PST January 19, 2017
oda-hw-mgmt upgrade January 19, 2017 9:38:35 AM PST January 19, 2017
Opatch updation January 19, 2017 9:38:58 AM PST January 19, 2017
Patch conflict check January 19, 2017 9:38:58 AM PST January 19, 2017
Apply clusterware patch January 19, 2017 9:42:06 AM PST January 19, 2017
Updating GiHome version January 19, 2017 10:02:32 AM PST January 19, 2017
5. Verify that the server components were updated successfully by using the dbcli
describe-component command. The Available Version column should indicate
update-to-date.
To patch database home components


CHAPTER 8 Database
login as: opc
3. Get the ID of the database home by using the dbcli list-dbhomes command.
[root@dbsys ~]# dbcli list-dbhomes
ID Name DB Version Home Location
------------------------------------ ----------------- ---------- ------------------------------
------------
b727bf80-c99e-4846-ac1f-28a81a725df6 OraDB12102_home1 12.1.0.2
/u01/app/orauser/product/12.1.0.2/dbhome_1
4. Update the database home components by using the dbcli update-dbhome command
and providing the ID from the previous step.
[root@dbsys ~]# dbcli update-dbhome -i b727bf80-c99e-4846-ac1f-28a81a725df6
{
"jobId" : "31b38f67-f993-4f2e-b7eb-5bccda9901ae",
"message" : null,
"reports" : [ ],
"description" : "DB Home Patching: Home Id is 52e2e799-946a-4339-964b-c203dee35328",
}
Note the job ID above.

5. Check the job output by using the dbcli describe-job command with the job ID.
[root@dbsys ~]# dbcli describe-job -i 31b38f67-f993-4f2e-b7eb-5bccda9901ae
Job details
----------------------------------------------------------------
ID: 31b38f67-f993-4f2e-b7eb-5bccda9901ae
Description: DB Home Patching: Home Id is b727bf80-c99e-4846-ac1f-28a81a725df6
Status: Success
Message:

CHAPTER 8 Database
Status
---------------------------------------- ----------------------------------- --------------------
--------------- ----------
Create Patching Repository Directories January 20, 2017 10:08:49 AM PST January 20, 2017
Download latest patch metadata January 20, 2017 10:08:49 AM PST January 20, 2017
Update System version January 20, 2017 10:08:49 AM PST January 20, 2017
Update Patching Repository January 20, 2017 10:08:49 AM PST January 20, 2017
Opatch updation January 20, 2017 10:08:58 AM PST January 20, 2017
Patch conflict check January 20, 2017 10:08:58 AM PST January 20, 2017
db upgrade January 20, 2017 10:12:00 AM PST January 20, 2017
6. Verify that the database home components were updated successfully by using the dbcli
describe-component command. The Available Version column should indicate
update-to-date.
Applying Interim Patches
Note
This topic applies only to database homes in 1-node and

2-node RAC DB systems.
If you are required to apply an interim patch (previously known as a "one-off" patch) to fix a
specific defect, follow the procedure in this section. You use the Opatch utility to apply an
interim patch to a database home.
In the procedure example, the database home directory is

/u02/app/oracle/product/12.1.0.2/dbhome_1 and the patch number is 26543344.

CHAPTER 8 Database
To apply an interim patch to a database home

1. Obtain the applicable interim patch from My Oracle Support.
2. Review the information in the patch README.txt file. This file might contain additional
and/or custom instructions to follow to apply the patch successfully.
3. Use SCP or SFTP to place the patch on your target database.
4. Shut down each database that is running in the database home.
srvctl stop database -db <db name> -stopoption immediate -verbose
5. Set the Oracle home environment variable to point to the target Oracle home.
sudo su - oracle
export ORACLE_HOME=/u02/app/oracle/product/12.1.0.2/dbhome_1
6. Change to the directory where you placed the patch, and unzip the patch.
cd <work_dir_where_opatch_is stored>
unzip p26543344_122010_Linux-x86-64.zip
7. Change to the directory with the unzipped patch, and check for conflicts.
cd 26543344
$ORACLE_HOME/OPatch/opatch prereq CheckConflictAgainstOHWithDetail -ph ./
8. Apply the patch.

$ORACLE_HOME/OPatch/opatch apply
9. Verify the patch was applied successfully.

$ORACLE_HOME/OPatch/opatch lsinventory -detail -oh $ORACLE_HOME
10. If the database home contains databases, restart them.

$ORACLE_HOME/bin/srvctl start database -db <db_name>
Otherwise, run the following command as root user.

# /u01/app/<db_version>/grid/bin/setasmgidwrap o=/u01/app/oracle/product/<db_version>/dbhome_
1/bin/oracle

CHAPTER 8 Database
11. If the readme indicates that the patch has a sqlpatch component, run the datapatch
command against each database.
Before you run datapatch, ensure that all pluggable databases (PDBs) are open. To open
a PDB, you can use SQL*Plus to execute "ALTER PLUGGABLE DATABASE <pdb_name>
OPEN READ WRITE;" against the PDB.
$ORACLE_HOME/OPatch/datapatch
Creating a Database
Note
This topic is not applicable to Virtual Machine DB

systems.
When you launch a bare metal DB system, an initial database is created in that system. You
can create additional databases in that DB system at any time by using the Console or the API.
You can create an empty database or reproduce a database by using a standalone backup. A
standalone backup is a full backup from a database that's been terminated. See Recovering a
Database from Object Storage.
The database edition will be the edition supported by the DB system in which the database is
created, and each new database is created in a separate database home.
Required IAM Policy

CHAPTER 8 Database
Using the Console
To create a new database in an existing DB system
Note
The database that you create will be the same edition as

the initial database in the DB system.
2. In the list of DB systems, find the DB system in which you want to create the database,
and then click its name to display details about it.
3. Click Create Database.
4. In the Create Database dialog, enter the following:
l Database Name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database Version: The version of the database. You can mix database versions
on the DB system, but not editions.
l Admin Password: A strong password for SYS, SYSTEM, TDE wallet, and PDB
Admin. The password must be nine to thirty characters and contain at least two
uppercase, two lowercase, two numeric, and two special characters. The special
characters must be _, #, or -.
l Confirm Admin Password: Re-enter the database admin password.
l Automatic Backup: Check the check box to enable automatic incremental
backups for this database.

CHAPTER 8 Database
l Database Workload: Select the workload type that best suits your application.
o Online Transactional Processing (OLTP) configures the database for a
transactional workload, with a bias towards high volumes of random data
access.
o Decision Support System (DSS) configures the database for a decision
support or data warehouse workload, with a bias towards large data
scanning operations.
5. Optionally, you can specify the character set and/or national character set for this
database. Click Show Advanced Options to set these parameters. The defaults are
AL32UTF8 and AL16UTF16, respectively.
7. Click Create Database.
When the database creation is complete, the status changes from Provisioning to Available.
To terminate a database
You'll get the chance to back up the database prior to terminating it. This creates a standalone
backup that can be used to create a database later. Oracle recommends that you create this
final backup for any production (non-test) database.

CHAPTER 8 Database
Note
Terminating a database removes all automatic

incremental backups of the database from Oracle Cloud
Infrastructure Object Storage. However, all full backups
that were created on demand, including your final
backup, will persist as standalone backups.
You cannot terminate a database that is assuming the primary role in a Data Guard
association. To terminate it, you can switch it over to the standby role.
2. In the list of DB Systems, find the DB System that contains the database you want to
terminate, and then click its name to display details about it.
3. In the list of databases, find the database, click the Actions icon ( ) and then click
Terminate.
4. In the confirmation dialog, indicate whether you want to back up the database before
terminating it, and type the name of the database to confirm the termination.
5. Click Terminate Database.
The database's status indicates Terminating.
Using the API
Use these API operations to manage databases:
l GetDbHome
l CreateDbHome
l DeleteDbHome

CHAPTER 8 Database
Monitoring a Database
This topic explains how to set up an:
l Enterprise Manager Express console to monitor a version 12.1.0.2 or later database

l Enterprise Manager Database Control console to monitor a version 11.2.0.4 database
Each console is a web-based database management tool inside the Oracle database. You can
use the console to perform basic administrative tasks such as managing user security,
memory, and storage, and view performance information.
Required IAM Policy
Some of the procedures below require permission to create or update security lists. For more
information about security list policies, see Security Lists.
Monitoring a Database with Enterprise Manager Express
On 1- and 2-node RAC DB Systems, by default, the EM Express console is not enabled on

version 18.1.0.0, 12.2.0.1, and 12.1.0.2 databases. You can enable it for an existing database
as described below, or you can enable it when you create a database by using the dbcli
create-database command with the -co parameter.
You must also update the security list and iptables for the DB system as described later in this
topic.
When you enable the console, you'll set the port for the console. The procedure below uses
port 5500, but each additional console enabled on the same DB system will have a different
port.
To enable the EM Express console and determine its port number

1. SSH to the DB system, log in as opc, sudo to the oracle user, and log in to the database
as SYS.

CHAPTER 8 Database
sudo su - oracle
. oraenv
<provide the database SID at the prompt>
sqlplus / as sysdba
2. Do one of the following:

l To enable the console and set its port, use the following command.
exec DBMS_XDB_CONFIG.SETHTTPSPORT(<port>);
For example:
SQL> exec DBMS_XDB_CONFIG.SETHTTPSPORT(5500);
PL/SQL procedure successfully completed.
l To determine the port for a previously enabled console, use the following
command.
select dbms_xdb_config.getHttpsPort() from dual;
For example:
SQL> select dbms_xdb_config.getHttpsPort() from dual;
DBMS_XDB_CONFIG.GETHTTPSPORT()
------------------------------
5500
3. Return to the operating system by typing exit and then confirm that the listener is
listening on the port:
lsnrctl status | grep HTTP
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=xxx.us.oracle.com)(PORT=5500))(Security=(my_wallet_
directory=/u01/app/oracle/admin/prod/xdb_wallet))(Presentation=HTTP)(Session=RAW))
4. If you're using a 2-node RAC DB system, see To set the required permissions on a 2-
node RAC DB system.
5. Open the console's port as described in Opening Ports on the DB System.

CHAPTER 8 Database
6. Update the security list for the console's port as described in Updating the Security List
for the DB System.
To set the required permissions on a 2-node RAC DB system

If you're using a 2-node RAC DB system, you'll need to add read permissions for the
asmadmin group on the wallet directory on both nodes in the system.
1. SSH to one of the nodes in the DB system, log in as opc, sudo to the grid user.
[opc@dbsysHost1 ~]$ sudo su - grid
[grid@dbsysHost1 ~]$ . oraenv
ORACLE_SID = [+ASM1] ?
2. Get the location of the wallet directory, shown in red below in the command output.
[grid@dbsysHost1 ~]$ lsnrctl status | grep xdb_wallet
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=dbsysHost1.sub04061528182.dbsysapril6.oraclevcn.com)
(PORT=5500))(Security=(my_wallet_directory=/u01/app/oracle/admin/dbsys12_phx3wm/xdb_wallet))
(Presentation=HTTP)(Session=RAW))
3. Return to the opc user, switch to the oracle user, and change to the wallet directory.
[opc@dbsysHost1 ~]$ sudo su - oracle
[oracle@dbsysHost1 ~]$ cd /u01/app/oracle/admin/dbsys12_phx3wm/xdb_wallet
4. List the directory contents and note the permissions.

[oracle@dbsysHost1 xdb_wallet]$ ls -ltr
total 8
-rw------- 1 oracle asmadmin 3881 Apr 6 16:32 ewallet.p12
-rw------- 1 oracle asmadmin 3926 Apr 6 16:32 cwallet.sso
5. Change the permissions:

[oracle@dbsysHost1 xdb_wallet]$ chmod 640 /u01/app/oracle/admin/dbsys12_phx3wm/xdb_wallet/*
6. Verify that read permissions were added.

[oracle@dbsysHost1 xdb_wallet]$ ls -ltr
total 8

CHAPTER 8 Database
-rw-r----- 1 oracle asmadmin 3881 Apr 6 16:32 ewallet.p12

-rw-r----- 1 oracle asmadmin 3926 Apr 6 16:32 cwallet.sso
7. Important! Repeat the steps above on the other node in the cluster.
To connect to the EM Express console

After you've enabled the console and opened its port in the security list and iptables, you can
connect as follows:
1. From a web browser, connect to the console using the following URL format:
https://<ip_address:<port>/em
For example, https://129.145.0.164:5500/em

Use the DB system's private or public IP address depending on your network
configuration.
Use the private IP address to connect to the DB System from your on-premises VPN, or
from within the virtual cloud network (VCN). This includes connecting from a host
located on-premises connecting through a VPN to your VCN, or from another host in the
same VCN.
Use the DB System's public IP address to connect to the system from outside the cloud
(with no VPN).
You can find the IP addresses in the Oracle Cloud Infrastructure Console on the
Database page.
2. A login page is displayed and you can log in with any valid database credentials.

CHAPTER 8 Database
The Database Home page is displayed.

CHAPTER 8 Database
To learn more about EM Express, see Introduction to Oracle Enterprise Manager Database
Express.
Note
If you're using a 1-node DB system, and you are unable

to connect to the EM Express console, see Database
Known Issues.

CHAPTER 8 Database
Monitoring a Database with Enterprise Manager Database Control
By default, the Enterprise Manager Database Control console is not enabled on version
11.2.0.4 databases. You can enable the console:
l when you create a database by using the dbcli create-database with the -co parameter
l for an existing database as described here.
Port 1158 is the default port used for the first console enabled on the DB system, but each
additional console enabled on the DB system will have a different port.
Note
For a version 11.2.0.4 database on a 2-node RAC DB

system, see To enable the console for a version
11.2.0.4 database on a multi-node DB system .
To determine the port for the Enterprise Manager Database Control console
1. SSH to the DB system, log in as opc, and sudo to the oracle user.
sudo su - oracle
. oraenv
<provide the database SID at the prompt>
2. Use the following command to get the port number.

emctl status dbconsole
The port is in the URL, as shown in the following example:

[oracle@dbsys ~]$ emctl status dbconsole
Oracle Enterprise Manager 11g Database Control Release 11.2.0.4.0
Copyright (c) 1996, 2013 Oracle Corporation. All rights reserved.
https://dbprod:1158/em/console/aboutApplication
Oracle Enterprise Manager 11g is running.
------------------------------------------------------------------

CHAPTER 8 Database
Logs are generated in directory /u01/app/oracle/product/11.2.0.4/dbhome_2/dbprod_db11/sysman/log
3. Open the console's port as described in Opening Ports on the DB System.

for the DB System.
To connect to the Enterprise Manager Database Control console

After you've enabled the console and opened its port in the security list and iptables, you can
connect as follows:
1. From a web browser, connect to the console using the following URL format:
https://<ip_address>:<port>/em
For example, https://129.145.0.164:1158/em

Use the DB system's private or public IP address depending on your network
configuration.
Use the private IP address to connect to the DB System from your on-premises VPN, or
from within the virtual cloud network (VCN). This includes connecting from a host
located on-premises connecting through a VPN to your VCN, or from another host in the
same VCN.
Use the DB System's public IP address to connect to the system from outside the cloud
(with no VPN).
You can find the IP addresses in the Oracle Cloud Infrastructure Console on the
Database page.
2. A login page will be displayed and you can log in with any valid database credentials.
To learn more about Enterprise Manager Database Control, see Introduction to Oracle
Enterprise Manager Database Control.
To enable the console for a version 11.2.0.4 database on a multi-node DB

system
A few extra steps are required to enable the console for a version 11.2.0.4 database on a

CHAPTER 8 Database
multi-node DB system.
Configure SSH Equivalency Between the Two Nodes
You'll create SSH keys on each node and copy the key to the other node, so that each node
has the keys for both nodes. The following procedure uses the sample names node1 and
node2.
1. SSH to node1, log in as opc, and sudo to the oracle user.

sudo su - oracle
2. Create a directory called .ssh, set its permissions, create an RSA key, and add the
public key to the authorized_keys file.
mkdir .ssh
chmod 755 .ssh
ssh-keygen -t rsa
cat id_rsa.pub > authorized_keys
3. Repeat the previous steps on the other node in the cluster.

4. On each node, add the id_rsa.pub key for the other node to the authorized_keys file.
When you're done, you should see both keys in authorized_keys on each node.
5. On node1, create the known_hosts file by doing the following:
l SSH to node1 and reply yes to the authentication prompt.
6. On node2, create the known_hosts file by doing the following:
7. On node1, verify that SSH equivalency is now configured by using the following Cluster
Verification Utility (CVU) command.
cluvfy stage -pre crsinst -n all -verbose
Configure the Console

CHAPTER 8 Database
1. On node1, create a file called emca.rsp with the following entries.

DB_UNIQUE_NAME=<pdb_unique_name>
SERVICE_NAME=<db_unique_name>.<db_domain>
PORT=<scan listener port>
LISTENER_OH=$GI_HOME
SYS_PWD=<admin password>
DBSNMP_PWD=<admin password>
SYSMAN_PWD=<admin password>
CLUSTER_NAME=<cluster name> <=== to get the cluster name, run: $GI_HOME/bin/cemutlo -n
ASM_OH=$GI_HOME
ASM_SID=+ASM1
ASM_PORT=<asm listener port>
ASM_USER_NAME=ASMSNMP
ASM_USER_PWD=<admin password>
2. On node1, run Enterprise Manager Configuration Assistant (EMCA) using the emca.rsp
file as input.
$ORACLE_HOME/bin/emca -config dbcontrol db -repos create -cluster -silent -respFile <location of
response file above>
3. On node2, configure the console so the agent in node1 reports to the console in node1,
and the agent in node2 reports to the console in node2.
$ORACLE_HOME/bin/emca -reconfig dbcontrol -silent -cluster -EM_NODE <node2 host> -EM_NODE_LIST
<node2 host> -DB_UNIQUE_NAME <db_unique_name>
-SERVICE_NAME <db_unique_name>.<db_domain>
4. On each node, verify that console is working properly.

$ export ORACLE_UNQNAME=<db_unique_name>
$ emctl status agent

Oracle Enterprise Manager 11g Database Control Release 11.2.0.4.0
Copyright (c) 1996, 2013 Oracle Corporation. All rights reserved.
---------------------------------------------------------------
Agent Version : 10.2.0.4.5
OMS Version : 10.2.0.4.5
Protocol Version : 10.2.0.4.5
Agent Home : /u01/app/oracle/product/11.2.0.4/dbhome_x/<host>_<db_unique_name>
Agent binaries : /u01/app/oracle/product/11.2.0.4/dbhome_x

CHAPTER 8 Database
Agent Process ID : 26194

Parent Process ID : 25835
Agent URL : https://<node host>:1831/emd/main
Repository URL : https://<node host>:5501/em/upload/
Started at : 2017-03-15 20:20:34
Started by user : oracle
Last Reload : 2017-03-15 20:27:00
Last successful upload : 2017-03-15 21:06:36
Total Megabytes of XML files uploaded so far : 22.25
Number of XML files pending upload : 0 <=== should be zero
Size of XML files pending upload(MB) : 0.00
Available disk space on upload filesystem : 42.75%
Data channel upload directory : /u01/app/oracle/product/11.2.0.4/dbhome_x/<host>_
<db_unique_name>/sysman/recv
Last successful heartbeat to OMS : 2017-03-15 21:08:45
---------------------------------------------------------------
Update iptables and Security List
1. On each node, edit iptables to open the console's port as described in Opening Ports on
the DB System.
for the DB System.
Opening Ports on the DB System
Open the following ports as needed on the DB system:
l 6200 - For Oracle Notification Service (ONS).

l 5500 - For EM Express. 5500 is the default port, but each additional EM Express console
enabled on the DB system will have a different port. If you're not sure which port to
open for a particular console, see Monitoring a Database with Enterprise Manager
Express.
l 1158 - For Enterprise Manager Database Control. 1158 is the default port, but each
additional console enabled on the DB system will have a different port. If you're not
sure which port to open for a particular console, see Monitoring a Database with
Enterprise Manager Database Control.

CHAPTER 8 Database
For important information about critical firewall rules, see Essential Firewall Rules.
To open ports on the DB system


login as: opc
3. Save a copy of iptables as a backup.

[root@dbsys ~]# iptables-save > /tmp/iptables.orig
(If necessary, you can restore the original file by using the command iptables-
restore < /tmp/iptables.orig.)
4. Dynamically add a rule to iptables to allow inbound traffic on the console port, as shown
in the following sample. Change the port number and comment as needed.
[root@dbsys ~]# iptables -I INPUT 8 -p tcp -m state --state NEW -m tcp --dport 5500 -j ACCEPT -m
comment --comment "Required for EM Express.”
5. Make sure the rule was added.

[root@dbsys ~]# service iptables status
6. Save the updated file to /etc/sysconfig/iptables.

[root@dbsys ~]# /sbin/service iptables save
The change takes effect immediately and will remain in effect when the node is
rebooted.
7. Update the DB system's security list as described in Updating the Security List for the
DB System.

CHAPTER 8 Database
Updating the Security List for the DB System
Review the list of ports in Opening Ports on the DB System and for every port you open in
iptables, update the security list used for the DB system, or create a new security list.
Note that port 1521 for the Oracle default listener is included in iptables, but should also be
added to the security list.
To update an existing security list

1. In the Console, click Database and locate the DB system in the list.
2. Note the DB system's Subnet name and click its Virtual Cloud Network.
3. Locate the subnet in the list, and then click its security list under Security Lists.
4. Click Edit All Rules and add an ingress rule with source CIDR=<source CIDR>,
protocol=TCP, and port=<port number or port range>.
The source CIDR should be the CIDR block that includes the ports you open for the client
connection.
For detailed information about creating or updating a security list, see Security Lists.
Backing Up a Database
Backing up your DB System is a key aspect of any Oracle database environment. You can
store backups in the cloud or in local storage. Each backup destination has advantages,
disadvantages, and requirements that you should consider, as described below.
Object Storage (Recommended)
l Backups are stored in the Oracle Cloud Infrastructure Object Storage.

l Durability: High
l Availability: High
l Back Up and Recovery Rate: Medium
l Advantages: High durability, performance, and availability.

CHAPTER 8 Database
l Disadvantages: The DB System's cloud network must be configured with an internet

gateway. Before deciding on this option, find out if your network administrator will
allow an internet gateway.
Local Storage
l Backups are stored locally in the Fast Recovery Area of the DB System.
l Durability: Low
l Availability: Medium
l Back Up and Recovery Rate: High
l Advantages: Optimized back up and fast point-in-time recovery.
l An internet gateway is not required.
l Disadvantages: If the DB System becomes unavailable, the backup is also unavailable.
Currently, Oracle Cloud Infrastructure does not provide the ability to attach block storage
volumes to a DB System, so you cannot back up to network attached volumes.
For 1- and 2-node RAC DB Systems, see:
l Backing Up to Oracle Cloud Infrastructure Object Storage

l Backing Up to Local Storage Using the Database CLI
Backing Up to Oracle Cloud Infrastructure Object Storage
Note
This topic is not applicable to Exadata DB Systems. For

Exadata DB Systems, see Backing Up an Exadata
Database.
This topic explains how to work with backups managed by Oracle Cloud Infrastructure. You do
this by using the Console or the API. (For unmanaged backups, you can use RMAN or dbcli,

CHAPTER 8 Database
and you must create and manage your own Object Storage buckets for backups. See Backing
Up to Object Storage Using RMAN.)
Warning
If you previously used RMAN or dbcli to configure

backups and then you switch to using the Console or the
API for backups, a new backup configuration is created
and associated with your database. This means that you
can no longer rely on your previously configured
unmanaged backups to work.
REQUIRED IAM POLICY
If you're new to policies, see Getting Started with Policies and Common Policies.
PREREQUISITES
The DB System's cloud network (VCN) must be configured with an internet gateway.
Oracle recommends that you update the backup subnet's security list to disallow any access
from outside the subnet and allow egress traffic for TCP port 443 (https) on CIDR Ranges
129.146.0.0/16 (Phoenix region) 129.213.0.0/16 (Ashburn region), and 130.61.0.0/16
(Frankfurt region). For more information, see Security Lists.
Note that the network traffic between the DB System and Object Storage does not leave the
cloud and never reaches the public internet. For more information, see Connectivity to the
Internet.

CHAPTER 8 Database
Your DB System must have connectivity to the applicable Swift endpoint for Object Storage.
See https://cloud.oracle.com/infrastructure/storage/object-storage/faq for information about
the Swift endpoints to use.
Important
In addition to the prerequisites listed, ensure that the

following conditions are met to avoid backup failures:
l The database's archiving mode is set to

ARCHIVELOG (the default).
l The /u01 directory on the database host file
system has sufficient free space for the execution
of backup processes.
l The .bash_profile file for the oracle user does not
include any interactive commands (such as
oraenv or one that could generate an error or
warning message).
l (For automatic backups) No changes were made
to the default WALLET_LOCATION entry in the
slqnet.ora file.
l No changes were made to RMAN backup settings
by using standard RMAN commands.
See Backup Failures for details on problems that can

result from not following these guidelines.
USING THE CONSOLE
You can use the Console to enable automatic incremental backups, create full backups on
demand, and view the list of managed backups for a database. The Console also allows you to
delete full backups.

CHAPTER 8 Database
Note
The list of backups you see in the Console does not

include any unmanaged backups (backups created
directly by using RMAN or dbcli).
All backups are encrypted with the same master key

used for Transparent Data Encryption (TDE) wallet
encryption.
The database and DB System must be in an “Available” state for a backup operation to run
successfully. Oracle recommends that you avoid performing actions that could interfere with
availability (such as patching and Data Guard operations) while a backup operation is in
progress. If an automatic backup operation fails, the Database service retries the operation
during the next day’s backup window. If an on-demand full backup fails, you can try the
operation again when the DB System and database availability is restored.
Automatic Incremental Backups
When you enable the Automatic Backup feature, the service creates daily incremental
backups of the database to Object Storage. The first backup created is a level 0 backup. Then,
level 1 backups are created every day until the next weekend. Every weekend, the cycle
repeats, starting with a new level 0 backup. The automatic backup process can run at any
time within the daily backup window (between midnight and 6:00 am UTC). Automatic
incremental backups are retained in Object Storage for 30 days, after which time, they are
automatically deleted.

CHAPTER 8 Database
Note
You can enable the Automatic Backup feature on a

database with the standby role in a Data Guard
association. However, automatic backups for that
database will not be created until it assumes the
primary role.
On-Demand Full Backups
You can create a full backup of your database at any time unless your database is assuming
the standby role in a Data Guard association.
Standalone Backups
When you terminate a DB System or a database, all of its resources are deleted, along with
any automatic backups. Full backups remain in Object Storage as standalone backups. You
can use a standalone backup to create a new database.
To enable or disable automatic backups for a database

When you launch a DB System, you have the option to enable automatic backups for the initial
database. Use this procedure to enable or disable automatic backups after the database is
created.
A list of DB Systems is displayed.
2. Find the DB System where the database is located, and click the system name to display
details about it.

CHAPTER 8 Database
3. Find the database for which you want to enable or disable automatic backups, and click
its name to display details about it. The details indicate whether automatic backups are
enabled.
4. Under Resources, click Backups.
A list of backups is displayed.
5. Click Enable Automatic Backup or Disable Automatic Backup, as applicable.
To create an on-demand full backup of a database

details about it.
3. Find the database for which you want to create an on-demand full backup, and click its
5. Click the Create Backup.
To delete full backups from Object Storage
Note
You cannot explicitly delete automatic backups. Unless

you terminate the database, automatic backups remain

CHAPTER 8 Database
in Object Storage for 30 days, after which time they are

automatically deleted.
details about it.
3. Find the database you are interested in, and click its name to display details about it.
5. Click the Actions icon ( ) for the backup you are interested in, and then click
Delete.
USING THE API
Use these API operations to manage database backups:
l ListBackups
l GetBackup
l CreateBackup
l DeleteBackup
l UpdateDatabase - To enable and disable automatic backups.
WH AT'S NEXT?
See Recovering a Database from Object Storage.

CHAPTER 8 Database
Backing Up to Local Storage Using the Database CLI
Note
This topic is not applicable to virtual machine DB

systems because they have no local storage. For
Exadata DB systems, see Backing Up an Exadata
Database.
This topic explains how to back up to the local Fast Recovery Area on a bare metal DB system
by using the database CLI (dbcli). Some sample dbcli commands are provided below. For
complete command syntax, see the Oracle Database CLI Reference.
Note
Backing up to local storage is fast and provides for fast

point-in-time recovery, however, if the DB system
becomes unavailable, the backup also becomes
unavailable. For information about more durable backup
destinations, see Backing Up a Database.
BACKING UP THE DATABASE TO LOCAL S TORAGE
You'll use the dbcli commands to create a backup configuration, associate the backup
configuration with the database, initiate the backup operation, and then review the backup
job.


CHAPTER 8 Database
login as: opc
3. Create a backup configuration by using the dbcli update-backupconfig command and

specify local disk storage as the backup destination.
The following example creates a backup configuration named prodbackup and specifies
a disk backup destination and a disk recovery window of 5 (backups and archived redo
logs will be maintained in local storage for 5 days).
[root@dbsys ~]# dbcli create-backupconfig --name prodbackup --backupdestination disk --
recoverywindow 5
{
"jobId" : "e7050756-0d83-48ce-9336-86592be59827",
"message" : null,
"reports" : [ {
"taskId" : "TaskParallel_471",
"taskName" : "persisting backup config metadata",
"taskResult" : "Success",
"startTime" : 1467774813141,
"endTime" : 1467774813207,
"taskDescription" : null,
"parentTaskId" : "TaskSequential_467",
"jobId" : "e7050756-0d83-48ce-9336-86592be59827",
"reportLevel" : "Info",
"updatedTime" : 1467774813207
} ],
"createTimestamp" : 1467774781851,
"description" : "create backup config:prodbackup",
"updatedTime" : 1467774813236
}
The example above uses full parameter names for demonstration purposes, but you can
abbreviate the parameters like this:
dbcli create-backupconfig -n prodbackup -d disk -w 5
4. Get the ID of the database you want to back up by using the dbcli list-databases
command.

CHAPTER 8 Database
[root@dbsys ~]# dbcli list-databases
ID DB Name DB Version CDB Class Shape

Storage Status
---------------------------------------- ---------- ---------- ---------- -------- -------- -----
----- ----------
71ec8335-113a-46e3-b81f-235f4d1b6fde prod 12.1.0.2 true OLTP odb1 ACFS
Configured
5. Get the ID of the backup configuration by using the dbcli list-backupconfigs command.
[root@dbbackup backup]# /opt/oracle/dcs/bin/dbcli list-backupconfigs
ID Name DiskRecoveryWindow
BackupDestination createTime
---------------------------------------- -------------------- ----- ------ ----------------------
-------------
78a2a5f0-72b1-448f-bd86-cf41b30b64ee prodbackup 5 Disk July 6, 2016 3:13:01

AM UTC
6. Associate the backup configuration ID with the database ID by using the dbcli update-
database command.
[root@dbsys ~]# dbcli update-database --backupconfigid 78a2a5f0-72b1-448f-bd86-cf41b30b64ee --
dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde
{
"jobId" : "2b104028-a0a4-4855-b32a-b97a37f5f9c5",
"message" : null,
"reports" : [ ],
"description" : "update database id:71ec8335-113a-46e3-b81f-235f4d1b6fde",
"updatedTime" : 1467775842978
}
You can view details about the update job by using the dbcli describe-job command and
specifying the job ID from the dbcli update-database command output, for example:
dbcli describe-job --jobid 2b104028-a0a4-4855-b32a-b97a37f5f9c5
7. Initiate the database backup by using the dbcli create-backup command. The backup
operation is performed immediately.

CHAPTER 8 Database
The following example creates a backup of the specified database.

[root@dbsys ~]# dbcli create-backup --dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde
{
"createTimestamp": 1467792576854,
"description": "Backup service creation with db name: prod",
"jobId": "d6c9edaa-fc80-40a9-bcdd-056430cdc56c",
"message": null,
"reports": [],
"status": "Created",
"updatedTime": 1467792576855
}
Or you can abbreviate the command parameters like this:

dbcli create-backup -i 71ec8335-113a-46e3-b81f-235f4d1b6fde
You can view details about the back up job by using the dbcli describe-job command and
specifying the job ID from the dbcli create-backup command output, for example:
dbcli describe-job --jobid d6c9edaa-fc80-40a9-bcdd-056430cdc56c
8. Important! Manually back up any TDE password-based wallets to your choice of a safe

location, preferably not on the DB system. The wallets are required to restore the
backup to a new host.
9. Optionally, you can review the backup report. Use the dbcli create-backupreport
command to create a report, then use dbcli list-backupreports to get the report ID, and
then use dbcli describe-backupreport with the report ID to get the report location, as
shown in the following example.
[root@dbsys ~]# dbcli create-backupreport --dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde --
reporttype summary
{
"jobId" : "65ce79fe-4ef4-4d7d-8020-e56a5390026d",
"message" : null,
"reports" : [ ],
"createTimestamp" : "July 6, 2016 23:06:11 PM UTC",
"description" : "Creating a report for database 71ec8335-113a-46e3-b81f-235f4d1b6fde",
"updatedTime" : "July 6, 2016 23:06:11 PM UTC"

CHAPTER 8 Database
[root@dbsys ~]# dbcli list-backupreports
ID Name ReportType DbId

createTime updatedTime
---------------------------------------- -------------------- ---------- ------------------------
---------------- ----------------------------------- -----------------------------------
c0e0a16a-485f-4176-ab73-5b30ccf5c560 summary 71ec8335-113a-46e3-b81f-
235f4d1b6fde July 6, 2016 11:04:05 PM UTC July 6, 2016 11:04:17 PM UTC
[root@dbsys ~]# dbcli describe-backupreport --id c0e0a16a-485f-4176-ab73-5b30ccf5c560
Backup Report details

----------------------------------------------------------------
ID: ed67a2cf-fe63-4755-a5d6-7eda5b669837
Name:
Report Type: summary
Location:
/opt/oracle/dcs/log/LrbvevghazqOGpbatvbpMRZJeVCzaW/rman/bkup/hhUiFnBz/rman_list_backup_
summary/2016-07-06/rman_list_backup_summary_2016-07-06_09-49-20.0832.log
Database ID: 71ec8335-113a-46e3-b81f-235f4d1b6fde
CreatedTime: July 6, 2016 3:49:12 AM UTC
UpdatedTime: July 6, 2016 3:49:24 AM UTC
After the backup command completes, the database backup files are available in the Fast
Recovery Area on the DB system.
WH AT'S NEXT?
See Recovering a Database from a CLI Backup.
Recovering a Database
For information on restoring a database on a bare metal or virtual machine DB system, see
the following topics:
l Recovering a Database from Object Storage

l Recovering a Database from a CLI Backup

CHAPTER 8 Database
l Recovering a Database from the Oracle Cloud Infrastructure Classic Object Store
Recovering a Database from Object Storage
Note
This topic is not applicable to Exadata DB Systems.
This topic explains how to recover a database from a backup stored in Object Storage. The
service is a secure, scalable, on-demand storage solution in Oracle Cloud Infrastructure. For
information on using Object Storage as a backup destination, see Backing Up to Oracle Cloud
Infrastructure Object Storage.
You can recover a database using the Console, API, or by using RMAN.
PREREQUISITES
The DB System's cloud network (VCN) must be configured with an internet gateway. Note that
the network traffic between the DB System and Object Storage does not leave the cloud and
never reaches the public internet. For more information, see Connectivity to the Internet.
USING THE CONSOLE
You can use the Console to restore the database from a backup in the Object Storage that was
created by using the Console or the API. You can restore to the last known good state of the
database, or you can specify a point in time or an existing System Change Number (SCN).

CHAPTER 8 Database
Note
The list of backups you see in the Console does not

include any unmanaged backups (backups created
directly by using RMAN or dbcli).
Restoring a database with Data Guard enabled is not

supported. You must first remove the Data Guard
association by terminating the standby database before
you can restore the database.
For Bare Metal DB Systems, you can also create a new database by using a standalone
backup.
To restore a database
details about it.
3. Find the database you want to restore, and click its name to display details about it.
4. Click Restore.
Restore.
6. Select one of the following options, and click Restore Database:
l Restore to the latest: Restores the database to the last known good state with
the least possible data loss.
l Restore to the timestamp: Restores the database to the timestamp specified.

CHAPTER 8 Database
l Restore to SCN: Restores the database using the SCN specified. This SCN must
be valid.
Tip
You can determine the SCN number to use

either by accessing and querying your database
host, or by accessing any online or archived
logs.

If the restore operation fails, the database will be in a "Restore Failed" state. You can
try restoring again using a different restore option. However, Oracle recommends that
you review the RMAN logs on the host and fix any issues before reattempting to restore
the database.
To create a database from a standalone backup
Note
This procedure applies only to Bare Metal DB Systems.

You cannot create a Virtual Machine DB System
database from a standalone backup.
Before You Begin
l When you create a database from a standalone backup, you can choose a different DB
System and compartment. However, the availability domain must be the same as
where the backup is hosted.

CHAPTER 8 Database
l The target DB System must already exist. The process does not automatically create
one for you.
l The database you create must be the same database type as the database from which
the backup was taken. For example, if you are using a backup of a 1-node database,
then the DB System you select as your target must also be a 1-node DB System.
l The version of the target DB System must be the same or higher than the version of the
standalone backup.
1. Open the Console, click Database, and then click Standalone Backups.
2. In the list of standalone backups, find the backup you want to use to create the
database.
Create Database.
4. In the Create Database dialog, enter the following:
l DB System: The DB System in which you want to create the database.
Note
You can’t create a new database in the same DB

System in which the database used to create
the backup resides unless that database has
been successfully terminated.
l Database Admin Password: A strong password for SYS, SYSTEM, PDB Admin,
and TDE wallet for the new database. The password must be nine to thirty
characters and contain at least two uppercase, two lowercase, two numeric, and
two special characters. The special characters must be _, #, or -.
l Confirm Database Admin Password: Re-enter the database admin password.

CHAPTER 8 Database
l Password for Transparent Data Encryption (TDE) Wallet or RMAN

Encryption: Enter either the TDE wallet password or the RMAN encryption
password for decrypting the backup, whichever is applicable.
5. Click Create Database from Backup.
USING THE API
Use these API operations to recover a database:
l ListBackups
l GetBackup
l RestoreDatabase
l CreateDbHome - For creating a Bare Metal DB System database from a standalone
backup.
USING AN RMAN BACKUP
This topic explains how to recover a Recovery Manager (RMAN) backup stored in Object
Storage.
PREREQUISITES
You'll need the following:
l A new DB System to restore the database to (see assumptions below). For more
information, see Managing DB Systems.
l The Oracle Database Cloud Backup Module must be installed on the DB System. For
more information, see Installing the Backup Module on the DB System.
ASSUMPTIONS
The procedures below assume the following:

CHAPTER 8 Database
l A new DB System has been created to host the restored database and no other database
exists on the new DB System. It is possible to restore to a DB System that has existing
databases, but that is beyond the scope of this topic.
l The original DB System is lost and all that remains is the latest RMAN backup.
Warning
Any data not included in the most recent backup will

be lost.
l The Oracle Wallet and/or encryption keys used by the original database at the time of
the last backup is available.
l The RMAN backup contains a copy of the control file and spfile as of the most recent
backup as well as all of the datafile and archivelog backups needed to perform a
complete database recovery.
l An RMAN catalog will not be used during the restore.
SETTING UP STORAGE ON THE DB SYSTEM

login as: opc
3. You can use an existing empty database home or create a new one for the restore. Use
the applicable commands to help you complete this step.
If you will be using an existing database home:

CHAPTER 8 Database
l Use the dbcli list-dbhomes command to list the database homes.

---------------------------------------- -------------------- ---------- -----------------
----------------------------
2e743050-b41d-4283-988f-f33d7b082bda OraDB12102_home1 12.1.0.2
/u01/app/oracle/product/12.1.0.2/dbhome_1
l Use the dbcli list-databases command to ensure the database home is not
associated with any database.
If necessary, use the dbcli create-dbhome command to create a database home for the
restore.
4. Use the dbcli create-dbstorage to set up directories for DATA, RECO, and REDO storage.
The following example creates 10GB of ACFS storage for the rectest database.
[root@dbsys ~]# dbcli create-dbstorage --dbname rectest --dataSize 10 --dbstorage ACFS
Note
When restoring a version 11.2 database,

ACFS storage must be specified.
PERFORMING THE DATABASE RESTORE AND RECOVERY
1. SSH to the DB System, log in as opc, and then become the oracle user.
sudo su - oracle
2. Create an entry in /etc/oratab for the database. Use the same SID as the original
database.
db1:/u01/app/oracle/product/12.1.0.2/dbhome_1:N
3. Set the ORACLE_HOME and ORACLE_SID environment variables using the oraenv utility.
. oraenv
4. Obtain the DBID of the original database. This can be obtained from the file name of the

CHAPTER 8 Database
controlfile autobackup on the backup media. The file name will include a string that
contains the DBID. The typical format of the string is c-DDDDDDDDDDDD-YYYYMMDD-NN
where DDDDDDDDDDDD is the DBID, YYYYMMDD is the date the backup was created, and NN
is a sequence number to make the file name unique. The DBID in the following
examples is 1508405000. Your DBID will be different.
Use the following curl syntax to perform a general query of Object Storage. The
parameters in red are the same parameters you specified when installing the backup
module as described in Installing the Backup Module on the DB System.
curl -u '<user_ID>.com:<swift_password>' -v
https://swiftobjectstorage.<region>.oraclecloud.com/v1/<tenant_name>
For example:
curl -u 'djones@mycompany.com:1cnk!d0++ptETd&C;tHR' -v
https://swiftobjectstorage.<region>.oraclecloud.com/v1/mycompany
To get the DBID from the control file name, use the following syntax:
curl -u '<user_id>.com:<swift_password>' -v
https://swiftobjectstorage.<region>.oraclecloud.com/v1/<tenant_name>/<bucket_name>?prefix=sbt_
catalog/c-
For example:
curl -u 'djones@mycompany.com:1cnk!d0++ptETd&C;tHR' -v
https://swiftobjectstorage.<region>.oraclecloud.com/v1/mycompany/dbbackups/?prefix=sbt_catalog/c-
In the sample output below, 1508405000 is the DBID.

{
"bytes": 1732,
"content_type": "binary/octet-stream",
"hash": "f1b61f08892734ed7af4f1ddaabae317",
"last_modified": "2016-08-11T20:28:34.438000",
"name": "sbt_catalog/c-1508405000-20160811-00/metadata.xml"
}
5. Run RMAN and connect to the target database. There is no need to create a pfile or
spfile or use a backup controlfile. These will be restored in the following steps.
Note that the target database is (not started). This is normal and expected at this

CHAPTER 8 Database
point.
rman target /
Recovery Manager: Release 12.1.0.2.0 - Production on Wed Jun 22 18:36:40 2016
Copyright (c) 1982, 2014, Oracle and/or its affiliates. All rights reserved.
connected to target database (not started)
6. Set the DBID using the value obtained above.

RMAN> set dbid 1508405000;
executing command: SET DBID
7. Run the STARTUP NOMOUNT command. If the server parameter file is not available,
RMAN attempts to start the instance with a dummy server parameter file. The ORA-
01078 and LRM-00109 errors are normal and can be ignored.
RMAN> STARTUP NOMOUNT
startup failed: ORA-01078: failure in processing system parameters

LRM-00109: could not open parameter file '/u01/app/oracle/product/12.1.0.2/dbhome_
1/dbs/initdb1.ora'
starting Oracle instance without parameter file for retrieval of spfile

Oracle instance started
Total System Global Area 2147483648 bytes
Fixed Size 2944952 bytes

Variable Size 847249480 bytes
Database Buffers 1254096896 bytes
Redo Buffers 43192320 bytes
8. Restore the server parameter file from autobackup.

The SBT_LIBRARY is the same library specified with the -libDir parameter when the
Backup Module was installed, for example /home/oracle/lib/.
The OPC_PFILE is the same file specified with the -configfile parameter when the
Backup Module was installed, for example /home/oracle/config.

CHAPTER 8 Database
set controlfile autobackup format for device type sbt to '%F';

run {
allocate channel c1 device type sbt PARMS 'SBT_LIBRARY=/home/oracle/lib/libopc.so, SBT_PARMS=
(OPC_PFILE=/home/oracle/config)';
restore spfile from autobackup;
}
9. Create the directory for audit_file_dest. The default is

/u01/app/oracle/admin/$ORACLE_SID/adump. You can see the setting used by the
original database by searching the spfile for the string, audit_file_dest.
strings ${ORACLE_HOME}/dbs/spfile${ORACLE_SID}.ora | grep audit_file_dest
*.audit_file_dest='/u01/app/oracle/admin/db1/adump'
mkdir -p /u01/app/oracle/admin/db1/adump
10. If block change tracking was enabled on the original database, create the directory for
the block change tracking file. This will be a directory under db_create_file_dest.
Search the spfile for the name of the directory.
strings ${ORACLE_HOME}/dbs/spfile${ORACLE_SID}.ora | grep db_create_file_dest
*.db_create_file_dest='/u02/app/oracle/oradata/db1'
mkdir -p /u02/app/oracle/oradata/db1/<$ORA_UNQNAME if available or database name>/changetracking
11. Restart the instance with the restored server parameter file.
STARTUP FORCE NOMOUNT;
12. Restore the controlfile from the RMAN autobackup and mount the database.
set controlfile autobackup format for device type sbt to '%F';
run {
allocate channel c1 device type sbt PARMS 'SBT_LIBRARY=/home/oracle/lib/libopc.so, SBT_PARMS=
(OPC_PFILE=/home/oracle/config)';
restore controlfile from autobackup;
alter database mount;
}
13. Restore and recover the database.

RESTORE DATABASE;
RECOVER DATABASE;

CHAPTER 8 Database
14. RMAN will recover using archived redo logs until it can't find any more. It is normal for
an error similar to the one below to occur when RMAN has applied the last archived redo
log in the backup and can't find any more logs.
unable to find archived log
archived log thread=1 sequence=29
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03002: failure of recover command at 06/28/2016 00:57:35
RMAN-06054: media recovery requesting unknown archived log for thread 1 with sequence 29 and
starting SCN of 2349563
15. Open the database with resetlogs.

ALTER DATABASE OPEN RESETLOGS;
The recovery is complete. The database will have all of the committed transactions as of the
last backed up archived redo log.
Recovering a Database from a CLI Backup
Note
This topic is not applicable to Exadata DB Systems.
This topic explains how to perform a complete or point-in-time recovery of an existing

database from a backup created with the dbcli create-backup command. The backup resides
in the local Fast Recovery Area on the DB System.
To initiate the recovery, you'll use the dbcli create-recovery command and specify the
recovery type parameter (either --recoverytype or just -t). You can specify the following
types of recovery:
l -t Latest for a complete recovery

l -t SCN -s <scn> for a recovery using a system change number (SCN) as the end point
of the recovery

CHAPTER 8 Database
l -t PITR <mm/dd/yyyy hh:mm:ss> for a database point-in-time (incomplete) recovery

based on a time stamp
The dbcli create-recovery attempts to perform a full recovery of the database. For
information on performing a partial recovery (datafile, tablespace and PDB), see the Oracle
Database Backup Recovery Guide for version 18.1, 12.2, 12.1, or 11.2.
PREREQUISITES
l The backup must have been created with the dbcli create-backup command.
l If the database is configured with Transparent Data Encryption (TDE), make sure the
password-based and autologin TDE wallets are present in the following location:
/opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>
RECOVERING THE DATABASE

login as: opc
3. Find the ID of database you want to recover by using the dbcli list-databases command.
You'll need the ID for the following step.
Storage Status
---------------------------------------- ---------- ---------- ---------- -------- -------- -----
----- ----------
5a3e980b-e0fe-4909-9628-fcefe43b3326 prod 12.1.0.2 true OLTP odb1 ACFS
Configured
4. Initiate the recovery by using the dbcli create-recovery command and specifying the

CHAPTER 8 Database
database ID, recovery type parameter (-t), and any parameter required for the
recover type, like the time stamp or system change number.
The following example initiates a complete recovery.
[root@dbsys ~]# dbcli create-recovery --dbid 5a3e980b-e0fe-4909-9628-fcefe43b3326 --recoverytype
Latest
{
"jobId" : "c9f81228-2ce9-43b4-88f6-b260d398cf06",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 18:20:47 PM UTC",
"description" : "Create recovery for database id :5a3e980b-e0fe-4909-9628-fcefe43b3326",
"updatedTime" : "August 08, 2016 18:20:47 PM UTC"
}
The following example initiates a point-in-time recovery of the specified database:

[root@dbsys ~]# dbcli create-recovery --dbid d4733796-dbea-4155-8606-24a85d64bd74 --recoverytype
PITR --recoveryTimeStamp 08/09/2016 5:12:15
Note the job ID in the command output.

5. Check the status of the recovery by using the dbcli describe-job command with the job
ID from the previous step.
[root@dbsys ~]# dbcli describe-job -i c9f81228-2ce9-43b4-88f6-b260d398cf06
Job details
----------------------------------------------------------------
ID: c9f81228-2ce9-43b4-88f6-b260d398cf06
Description: Create recovery for database id :5a3e980b-e0fe-4909-9628-fcefe43b3326
Status: Success
Created: August 8, 2016 6:20:47 PM UTC
Message:

Status
---------------------------------------- ----------------------------------- --------------------
--------------- ----------
Database recovery validation August 8, 2016 6:20:47 PM UTC August 8, 2016

CHAPTER 8 Database
6:21:07 PM UTC Success

Database recovery August 8, 2016 6:21:07 PM UTC August 8, 2016
enable block change tracking August 8, 2016 6:22:34 PM UTC August 8, 2016
Open database August 8, 2016 6:22:35 PM UTC August 8, 2016
Restart database August 8, 2016 6:22:44 PM UTC August 8, 2016
Persist Recovery Metadata August 8, 2016 6:23:41 PM UTC August 8, 2016
You can also check the database restore report logs on the DB System at:
/opt/oracle/dcs/log/<nodename>/rman/bkup/<db_unique_name>
Recovering a Database from the Oracle Cloud Infrastructure Classic Object Store
Note
This topic explains how to recover a database using a backup created by the Oracle Database
Backup Module and stored in Oracle Cloud Infrastructure Object Storage Classic.
The following terms are used throughout this topic:
l Source database: The database backup in Object Storage Classic.

l Target database: The new database on a DB system in Oracle Cloud Infrastructure.
PREREQUISITES
You'll need the following:
l The service name, identity name, container, user name, and password for Oracle Cloud
Infrastructure Object Storage Classic.

CHAPTER 8 Database
l The backup password if password-based encryption was used when backing up to Object
Storage Classic.
l The source database ID, database name, database unique name (required for setting up
storage).
l If the source database is configured with Transparent Data Encryption (TDE), you'll
need a backup of the wallet and the wallet password.
l Tnsnames to setup for any database links.
l The output of Opatch lsinventory for the source database Oracle_home, for reference.
l A copy of the sqlpatch directory from the source database home. This is required for
rollback in case the target database does not include these patches.
S ETTING UP S TORAGE ON THE DB S YSTEM

login as: opc
The following example creates 10GB of ACFS storage for the tdetest database.
[root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS
Note
When migrating a version 11.2 database,

4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the

CHAPTER 8 Database
next step.
[root@dbsys ~]# dbcli list-dbstorages
ID Type DBUnique Name Status
---------------------------------------- ------ -------------------- ----------
9dcdfb8e-e589-4d5f-861a-e5ba981616ed Acfs tdetest Configured
5. Use the dbcli describe-dbstorage command with the storage ID from the previous step
to list the DATA, RECO and REDO locations.
[root@dbsys ~]# dbcli describe-dbstorage --id 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DBStorage details
----------------------------------------------------------------
ID: 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DB Name: tdetest
DBUnique Name: tdetest
DB Resource ID:
Storage Type: Acfs
DATA Location: /u02/app/oracle/oradata/tdetest
RECO Location: /u03/app/oracle/fast_recovery_area/
REDO Location: /u03/app/oracle/redo/
State: ResourceState(status=Configured)
UpdatedTime: August 24, 2016 5:25:53 PM UTC
6. Note the DATA, RECO and REDO locations. You'll need them later to set the db_create_
file_dest, db_create_online_log_dest, and db_recovery_file_dest parameters
for the database.
CHOOSING AN ORACLE_HOME
Decide which ORACLE_HOME to use for the database restore and then switch to that home
with the correct ORACLE_BASE, ORACLE_HOME, and PATH settings. The ORACLE_HOME must
not already be associated with a database.
To get a list of existing ORACLE_HOMEs and to ensure that the ORACLE_HOME is empty, use
the dbcli list-dbhomes and the dbcli list-databases commands, respectively. To create a new
ORACLE_HOME, use the dbcli create-dbhome command.
COPYING THE S OURCE DATABASE W ALLETS
Skip this section if the source database is not configured with TDE.

CHAPTER 8 Database
1. On the DB system, become the oracle user:

sudo su - oracle
2. Create the following directory, if it does not already exist:

mkdir /opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>
3. Copy the ewallet.p12 file from the source database to the directory you created in the
previous step.
4. On the target host, make sure that $ORACLE_HOME/network/admin/sqlnet.ora
contains the following line:
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=
(DIRECTORY=/opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME)))
Add the line if it doesn't exist in the file. (The line might not be there if this is a new
home and no database has been created yet on this host.)
5. Create the autologin wallet from the password-based wallet to allow auto-open of the
wallet during restore and recovery operations.
For a version 12.1 or later database, use the ADMINISTER KEY MANAGEMENT command:
$cat create_autologin_12.sh
#!/bin/sh
if [ $# -lt 2 ]; then
echo "Usage: $0 <dbuniquename><remotewalletlocation>"
exit 1;
fi
mkdir /opt/oracle/dcs/commonstore/wallets/tde/$1
cp $2/ewallet.p12* /opt/oracle/dcs/commonstore/wallets/tde/$1
rm -f autokey.ora
echo "db_name=$1" > autokey.ora
autokeystoreLog="autologinKeystore_`date +%Y%m%d_%H%M%S_%N`.log"
echo "Enter Keystore Password:"
read -s keystorePassword
echo "Creating AutoLoginKeystore -> "
sqlplus "/as sysdba" <<EOF
spool $autokeystoreLog
set echo on

CHAPTER 8 Database
startup nomount pfile=autokey.ora

ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE
FROM KEYSTORE '/opt/oracle/dcs/commonstore/wallets/tde/$1' -- Keystore location
IDENTIFIED BY "$keystorePassword";
shutdown immediate;
EOF
Adjust the cwallet.sso permissions from oracle:asmadmin to oracle:oinstall.

$ ls -ltr /opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>
total 20
-rw-r--r-- 1 oracle oinstall 5680 Jul 6 11:39 ewallet.p12
-rw-r--r-- 1 oracle asmadmin 5725 Jul 6 11:39 cwallet.sso
For a version 11.2 database, use the orapki command:

orapki wallet create -wallet wallet_location -auto_login [-pwd password]
I NSTALLING THE ORACLE DATABASE BACKUP MODULE
The backup module JAR file is included on the DB system but you need to install it.
1. SSH to the DB system, log in as opc, and then become the oracle user.
ssh -i <path to SSH key used when launching the DB System> opc@<DB System IP address or hostname>
sudo su - oracle
2. Change to the directory that contains the backup module opc_install.jar file.
cd /opt/oracle/oak/pkgrepos/orapkgs/oss/<version>/
3. Use the command syntax described in Installing the Oracle Database Cloud Backup
Module to install the backup module.
S ETTING ENVIRONMENT VARIABLES
Set the following environment variables for the RMAN and SQL*Plus sessions for the
database:
ORACLE_HOME=<path of Oracle Home where the database is to be restored>
ORACLE_SID=<database instance name>

CHAPTER 8 Database
ORACLE_UNQNAME=<db_unique_name in lower case>

NLS_DATE_FORMAT="mm/dd/yyyy hh24:mi:ss"
ALLOCATING AN RMAN SBT CHANNEL
For each restore operation, allocate an SBT channel and set the SBT_LIBRARY parameter to
the location of the libopc.so file and the OPC_FILE parameter to the location of the opc_
sbt.ora file, for example:
ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/<ORACLE_HOME>/dbs/opc_sbt.ora)';
(For more information about these files, see Files Created When the Backup Module is
Installed.)
ENSURING DECRYPTION IS TURNED ON
Make sure that decryption is turned on for all the RMAN restore sessions.
set decryption wallet open identified by <keystore password>;
For more information, see Providing Password Required to Decrypt Encrypted Backups.
RESTORING S PFILE
The following sample shell script restores the spfile. Set the $dbID variable to the dbid of the
database being restored. By default, spfile is restored to $ORACLE_
HOME/dbs/spfile<sid>.ora.
rman target / <<EOF
spool log to "`date +%Y%m%d_%H%M%S_%N`_dbid_${dbID}_restore_spfile.log"

startup nomount
set echo on
run {
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)';
SET DBID=$dbID;
RESTORE SPFILE FROM AUTOBACKUP;
shutdown immediate;
EOF

CHAPTER 8 Database
S ETTING THE DATABASE PARAMETERS
1. Start the database in nomount mode.

startup nomount
2. Update spfile and modify the following parameters.

l If the database storage type is ACFS, use the DATA, RECO, and REDO locations
obtained from the dbcli describe-dbstorage command output, as described in
Setting Up Storage on the DB System:
alter system set db_create_file_dest='/u02/app/oracle/oradata/' scope = spfile;
alter system set db_create_online_log_dest_1='/u03/app/oracle/redo' scope = spfile;
alter system set db_recovery_file_dest='/u03/app/oracle/fast_recovery_area' scope =
spfile;
l If the database storage type is ASM:

alter system set db_create_file_dest='+DATA' scope = spfile;
alter system set db_create_online_log_dest_1='+RECO' scope = spfile;
alter system set db_recovery_file_dest='+RECO' scope = spfile;
l Set db_recovery_file_dest_size is not set or is set incorrectly:

alter system set db_recovery_file_dest_size=<sizeG> scope=spfile;
l Set audit_file_dest to the correct value:

alter system set audit_file_dest=/u01/app/oracle/admin/<db_unique_name in lower
case>/adump
3. Remove the control_files parameter. The Oracle Managed Files (OMF) parameters
will be used to create the control file.
alter system reset control_files scope=spfile;
4. Restart the database in nomount mode using the newly added parameters.
shutdown immediate
startup nomount
RESTORING THE CONTROL FILE
Modify the following sample shell script for your environment to restore the control file. Set
the $dbID variable to the dbid of the database being restored. Set SBT_LIBRARY to the

CHAPTER 8 Database
location specified in the -libDir parameter when you installed the Backup Module. Set OPC-
PFILE to the location specified in the -configFile parameter, which defaults to ORACLE_
HOME/dbs/opcSID.ora.
rman target / <<EOF
spool log to "`date +%Y%m%d_%H%M%S_%N`_dbid_${dbID}_restore_controlfile.log"

set echo on
run {
ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_LIBRARY=/<Backup
Module libDir>/libopc.so ENV=(OPC_PFILE=/<Backup Module configFile>/opcSID.ora)';
SET DBID=$dbID;
RESTORE CONTROLFILE FROM AUTOBACKUP;
alter database mount;
}
exit;
EOF
RESTORING THE DATABASE
1. Preview and validate the backup. The database is now mounted and RMAN should be
able to locate the backup from the restored controlfile. This step helps ensure that the
list of archivelogs is present and that the backup components can be restored .
In the following examples, modify SBT_LIBRARY and OPC_PFILE as needed for your
environment.
rman target / <<EOF
spool log to "`date +%Y%m%d_%H%M%S_%N`_restore_database_preview.log"

set echo on
run {
restore database validate header preview;
}

CHAPTER 8 Database
Review the output and if there are error messages, investigate the cause of the
problem.
2. Redirect the restore using set newname to restore the data files in OMF format and use
switch datafile all to allow the control file to update with the new data file copies.
rman target / <<EOF
spool log to "`date +%Y%m%d_%H%M%S_%N`_restore_database_preview.log"

set echo on
run {
set newname for database to new;
restore database;
switch datafile all;
switch tempfile all;
recover database;
}
This recovery will attempt to use the last available archive log backup and then fail with
an error, for example:
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03002: failure of recover command at 07/20/2016 12:09:02
RMAN-06054: media recovery requesting unknown archived log for thread 1 with sequence 22 and
starting SCN of 878327
3. To complete the incomplete recovery, run a recovery using the sequence number and
thread number shown in the RMAN-06054 message, for example:
Recover database until sequence 22 thread 1;
RESETTING THE LOGS
Reset the logs.

alter database open resetlogs;

CHAPTER 8 Database
PREPARING TO REGISTER THE DATABASE
Before you register the database:
1. Make sure the database COMPATIBLE parameter value is acceptable. If the value is less
than the minimum, the database cannot be registered until you upgrade the database
compatibility.
The minimum compatibility values are as follows:
l For a version 18.1 database - 18.0.0.0
l For a version 12.2 or 12.1 database - 12.1.0.2
l For a version 11.2 database - 11.2.0.4
2. Verify that the database has registered with the listener and the service name.
lsnrctl services
3. Make sure the password file was restored or created for the new database.
ls -ltr $ORACLE_HOME/dbs/orapw<oracle sid>
If the file does not exist, create it using the orapwd utility.
orapwd file=<$ORACLE_HOME/dbs/orapw<$ORACLE_SID>> password=<sys password>
4. Make sure the restored database if open in read write mode.

select open_mode from v$database;
The command output should indicate read write mode. The dbcli register-database
command will attempt to run datapatch, which requires read write mode. If there are
PDBs, they should also be in read write mode to ensure that datapatch runs on them.
5. From oracle home on the restored database, use the following command verify the
connection to SYS:
conn sys/<password>@//<hostname>:1521/<database service name>
This connection is required to register the database later. Fix any connection issues
before continuing.
6. Make sure the database is running on spfile by using the SQL*Plus command.
SHOW PARAMETERS SPFILE

CHAPTER 8 Database
7. (Optional) If you would like to manage the database backup with the dbcli command line
interface, you can associate a new or existing backup configuration with the migrated
database when you register it or after you register it. A backup configuration defines the
backup destination and recovery window for the database. Use the following commands
to create, list, and display backup configurations:
l dbcli update-backupconfig
l dbcli list-backupconfigs
l dbcli describe-backupconfig
8. Copy the folder $ORACLE_HOME/sqlpatch from source database to the target database.
This will enable the dbcli register-database command to roll back any conflicting
patches.
Note
If you are migrating a version 11.2 database,

additional steps are required after you register the
database. For more information, see Rolling Back
Patches on a Version 11.2 Database.
REGISTERING THE DATABASE ON THE DB S YSTEM
The dbcli register-database command registers the restored database to the dcs-agent so it
can be managed by the dcs-agent stack.
Note
The dbcli register-database command is not

available on 2-node RAC DB systems.
As the root user, use the dbcli register-database command to register the database on
the DB system, for example:

CHAPTER 8 Database
[root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename tdetest --
syspassword
Password for SYS:
{
"jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 05:55:49 AM EDT",
"description" : "Database service registration with db service name: tdetest",
"updatedTime" : "August 08, 2016 05:55:49 AM EDT"
}
UPDATING TNSNAMES.ORA
Check the tnsnames.ora in the backup location, check the database links used in the cloned
database, and then add any relevant connection strings to the cloned database file at
$ORACLE_HOME/network/admin/tnsnames.ora.
ROLLING BACK PATCHES ON A VERSION 11.2 DATABASE
For version 11.2 databases, the sqlpatch application is not automated, so any interim patches
(previously known as a "one-off" patches) applied to the source database that are not part of
the installed PSU must be rolled back manually in the target database. After registering the
database, execute the catbundle.sql script and then the postinstall.sql script with the
corresponding PSU patch (or the overlay patch on top of the PSU patch), as described below.
Tip
Some interim patches may include files written to the

$ORACLE_HOME/rdbms/admin directory as well as the
$ORACLE_HOME/sqlpatch directory. Oracle
recommends that you roll back these patches in the
source database using the instructions in the patch
read-me prior to migrating the database to OCI
environment. Contact Oracle Support if you need
assistance with rolling back these patches.

CHAPTER 8 Database
1. On the DB System, use the dbcli list-dbhomes command to find the PSU patch
number for the version 11.2 database home. In the following sample command output,
the PSU patch number is the second number in the DB Version column:
ID Name DB Version
Home Location Status
------------------------------------ ----------------- ------------------------------------- --
--------------------------------------- ----------
59d9bc6f-3880-4d4f-b5a6-c140f16f8c64 OraDB11204_home1 11.2.0.4.160719 (23054319, 23054359)
/u01/app/oracle/product/11.2.0.4/dbhome_1 Configured
(The first patch number, 23054319 in the example above, is for the OCW component in
the database home.)
2. Find the overlay patch, if any, by using the lsinventory command. In the following
example, patch number 24460960 is the overlay patch on top of the 23054359 PSU
patch.
$ $ORACLE_HOME/OPatch/opatch lsinventory
...
Installed Top-level Products (1):
Oracle Database 11g 11.2.0.4.0

There are 1 products installed in this Oracle Home.
Interim patches (5) :
Patch 24460960 : applied on Fri Sep 02 15:28:17 UTC 2016

Unique Patch ID: 20539912
Created on 31 Aug 2016, 02:46:31 hrs PST8PDT
Bugs fixed:
23513711, 23065323, 21281607, 24006821, 23315889, 22551446, 21174504
This patch overlays patches:
23054359
This patch needs patches:
23054359
as prerequisites

CHAPTER 8 Database
3. Start SQL*Plus and execute the catbundle.sql script, for example:

SQL> startup
SQL> connect / as sysdba
SQL> @$ORACLE_HOME/rdbms/admin/catbundle.sql psu apply
exit
4. Apply the sqlpatch, using the overlay patch number from the previous step, for
example:
SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql
exit
Note
If the source database has one-off patches installed

and those patches are not part of the installed PSU
in the cloud environment, then the SQL changes that
correspond to those one-off patches need to be
rolled back. To rollback the SQL changes, copy the
$ORACLE_
HOME/sqlpatch/<patch#>/postdeinstall.sql
script from the source environment to the cloud
environment and execute the postdeinstall.sql
script.
POST RESTORE CHECKLIST
After the database is restored and registered on the DB system, use the following checklist to
verify the results and perform any post-restore customizations.
1. Make sure the database files were restored in OMF format.

2. Make sure the database is listed in the dbcli list-databases command output.
3. Check for the following external references in the database and update them if
necessary:

CHAPTER 8 Database
l External tables: If the source database uses external tables, back up that data
and migrate it to the target host.
l Directories: Customize the default directories as needed for the restored
database.
l Database links: Make sure all the required TNS entries are updated in the
tnsnames.ora file in ORACLE_HOME.
l Email and URLs: Make sure any email addresses and URLs used in the database
are still accessible from the DB system.
l Scheduled jobs: Review the jobs scheduled in source database and schedule
similar jobs as needed in the restored database.
4. If you associated a backup configuration when you registered the database, run a test
back up using the dbcli create-backup command.
5. If the restored database contains a CDB and PDBs, verify that patches have been
applied to all PDBs.
Using Oracle Data Guard
Note

Systems or Exadata DB Systems.
This topic explains how to use the Console to manage Data Guard associations in your DB
System. To configure a Data Guard system across regions or between on-premises and OCI
DB Systems, you must access the database host directly and use the DGMGRL utility.
For complete information on Oracle Data Guard, see the Data Guard Concepts and
Administration documentation on the Oracle Document Portal.

CHAPTER 8 Database
Prerequisites
A Data Guard implementation requires two DB Systems, one containing the primary database
and one containing the standby database.
Tip
A Data Guard configuration on the Oracle Cloud

Infrastructure is limited to one standby database per
primary database.
Requirement details are as follows:
l Both DB Systems must be in the same compartment, and they must be the same shape.
l The database versions and editions must be identical. Data Guard does not support
Standard Edition. (Active Data Guard requires Enterprise Edition - Extreme
Performance.)
l Both DB Systems must use the same VCN, and port 1521 must be open.
l Important! Properly configure the security list ingress and egress rules for the subnets
of both DB Systems in the Data Guard association to allow TCP traffic to flow between
the applicable ports.
For example, if the subnet of the primary DB System uses the source CIDR 10.0.0.0/24
and the subnet of the failover DB System uses the source CIDR 10.0.1.0/24, create
rules as shown in the following example.

CHAPTER 8 Database
Note
The egress rules in the example show how to enable

TCP traffic only for port 1521, which is a minimum
requirement for Data Guard to work. If TCP traffic
is already enabled on all of your outgoing ports
(0.0.0.0/0), then you need not explicitly add these
specific egress rules.
Security List for Primary DB System's Subnet

Ingress Rules:
Source: 10.0.1.0/24
IP Protocol: TCP
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Egress Rules:
IP Protocol: TCP
Security List for Standby DB System's Subnet

Ingress Rules:
Source: 10.0.0.0/24
IP Protocol: TCP
Egress Rules:

CHAPTER 8 Database
IP Protocol: TCP
For information about creating and editing rules, see Security Lists.
Oracle recommends that the DB System of the standby database be in a different availability
domain from the DB System of the primary database to improve availability and disaster
recovery.
If you don't already have DB Systems with the databases that will assume the primary and
standby roles, create them as described in Managing DB Systems. A new DB System includes
an initial database.
Working with Data Guard
Oracle Data Guard ensures high availability, data protection, and disaster recovery for
enterprise data. The Oracle Cloud Infrastructure Database Data Guard implementation
requires two databases, one in a primary role and one in a standby role. The two databases
compose a Data Guard association. Most of your applications access the primary database.
The standby database is a transactionally consistent copy of the primary database.
Data Guard maintains the standby database by transmitting and applying redo data from the
primary database. If the primary database becomes unavailable, you can use Data Guard to
switch the standby database to the primary role.
Tip
The standby databases in Oracle Cloud Infrastructure

Database are physical standbys.

CHAPTER 8 Database
S WITCHOVER
A switchover reverses the primary and standby database roles. Each database continues to
participate in the Data Guard association in its new role. A switchover ensures no data loss.
You can use a switchover before you perform planned maintenance on the primary database.
FAILOVER
A failover transitions the standby database into the primary role after the existing primary
database fails or becomes unreachable. A failover might result in some data loss when you
use Maximum Performance protection mode.
REINSTATE
Reinstates a database into the standby role in a Data Guard association. You can use the
reinstate command to return a failed database into service after correcting the cause of
failure.
Note
You can't terminate a primary database that has a Data

Guard association with a peer (standby) database.
Delete the standby database first. Alternatively, you can
perform a switchover to the standby database, and then
terminate the primary database.
You can't terminate a DB System that includes Data

Guard enabled databases. To remove the Data Guard
association, terminate the standby database.
Using the Console
The Console allows you to enable a Data Guard association between existing databases,
change the role of a database in a Data Guard association using either a switchover or a
failover operation, and reinstate a failed database that has been repaired.

CHAPTER 8 Database
To enable Data Guard

When you enable Data Guard, a separate Data Guard association is created for the primary
and the standby database.
1. Open the Console, click Database, and then click DB Systems.

2. Choose the Compartment that contains the DB System with the database for which you
want to enable Data Guard.
3. Click the name of the DB System that contains the database you want to assume the
primary role, and then click the name of that database.
Tip
If Data Guard is already enabled, a shield icon

appears next to the database name.
4. Under Resources, click Data Guard Associations.

5. Click Enable Data Guard.
6. In the Enable Data Guard dialog box, configure your Data Guard association.
l Peer DB System: Select the DB System that will contain the peer (standby)
database.
l Protection Mode: The protection mode used for this Data Guard association. The
Console supports only Maximum Performance.
l Transport Type: The redo transport type used for this Data Guard association.
The Console supports only Async.
l Database Admin Password: Enter the primary database admin password.
The same password is used for the standby database.
7. Click Enable.

CHAPTER 8 Database
When the association is created, a shield icon appears next to the name of this database
and its peer, and their respective roles (primary or standby) are displayed.
To perform a database switchover

You initiate a switchover operation by using the Data Guard association of the primary
database.

2. Choose the Compartment that contains the DB System with the primary database you
want to switch over.
3. Click the DB System name, and then click the name of the primary database.
5. For the Data Guard association on which you want to perform a switchover, click the
Actions icon ( ), and then click Switchover.
6. In the Switchover Database dialog box, enter the database admin password, and
then click OK.
This database should now assume the role of the standby, and the standby should
assume the role of the primary in the Data Guard association.
To perform a database failover

You initiate a failover operation by using the Data Guard association of the standby database.

2. Choose the Compartment that contains the DB System with the primary database's
peer standby you want to fail over to.
3. Click the DB System name, and then click the name of the standby database.
5. For the Data Guard association on which you want to perform a failover, click Failover.

CHAPTER 8 Database
6. In the Failover Database dialog box, enter the database admin password, and then
click OK.
This database should now assume the role of the primary, and the old primary's role
should display as Disabled Standby.
To reinstate a database
After you fail over a primary database to its standby, the standby assumes the primary role
and the old primary is identified as a disabled standby. After you correct the cause of failure,
you can reinstate the failed database as a functioning standby for the current primary by using
its Data Guard association.
Note
Before you can reinstate a version 12.2 database, you

must perform some steps on the database host to stop
the database or start it in MOUNT mode.
Set your ORACLE_UNQNAME environment variable to

the value of the Database Unique Name (as seen in the
Console), and then run these commands:
srvctl stop database -d db-unique-name -o abort
srvctl start database -d db-unique-name -o mount

2. Choose the Compartment that contains the DB System with the failed database you
want to reinstate.
3. Click the DB System name, and then click the database name.
5. For the Data Guard association on which you want to reinstate this database, click the
Actions icon ( ), and then click Reinstate.

CHAPTER 8 Database
6. In the Reinstate Database dialog box, enter the database admin password, and then
click OK.
This database should now be reinstated as the standby in the Data Guard association.
To terminate a Data Guard association

To remove a Data Guard association, terminate the standby database:

2. Choose the Compartment that contains the DB System that includes the standby
database you want to terminate.
3. Click the DB System name.
4. For the standby database you want to terminate, click the Actions icon ( ), and then
click Terminate.
5. In the Terminate Database dialog box, enter the name of the database, and then click
OK.
Using the API
Use these API operations to manage Data Guard associations:
l CreateDataGuardAssociation
l GetDataGuardAssociation
l ListDataGuardAssociations
l SwitchoverDataGuardAssociation
l FailoverDataGuardAssociation
l ReinstateDataGuardAssociation

CHAPTER 8 Database
Using Oracle Data Guard with the Database CLI

Oracle recommends that you use the Console instead of the database CLI to set up and work
with Data Guard in Oracle Cloud Infrastructure. See Using Oracle Data Guard for information
and instructions.
Note

Systems or Exadata DB Systems. You can manually
configure Data Guard on Exadata DB Systems using
native Oracle Database utilities and commands,
however this topic explains how set up primary and
standby databases using the dbcli CLI, which is not
available on Exadata DB Systems. For more
information, see Data Guard Concepts and
Administration for version 18.1, 12.2, 12.1, or 11.2.
This topic explains how to use the database CLI to set up Data Guard with Fast-Start Failover
(FSFO) in Oracle Cloud Infrastructure. The following sections explain how to prepare the
primary and standby databases, and then configure Data Guard to transmit redo data from the
primary database and apply it to the standby database.
Note
This topic assumes that you are familiar with Data

Guard and FSFO. To learn more about them, see
documentation at the Oracle Document Portal.

CHAPTER 8 Database
Prerequisites
To perform the procedures in this topic, you'll need the following information for the primary
and standby databases.
l db_name (or oracle_sid)

l db_unique_name
l oracle home directory (or database home)
To find the database information

After you've launched the primary and standby DB Systems and created databases as
described later in this topic, you can use the CLI on those systems to find the needed database
information.

login as: opc
3. To find the db_name (or oracle_sid) and db_uniqueName, run the dbcli list-
databases -j command.
[root@dbsys ~]# dbcli list-databases -j
[ {
"id" : "80ad855a-5145-4f8f-a08f-406c5e4684ff",
"name" : "dbtst",
"dbName" : "dbtst",
"databaseUniqueName" : "dbtst_phx1cs",
"dbVersion" : "12.1.0.2",
"dbHomeId" : "2efe7af7-0b70-4e9b-ba8b-71f11c6fe287",

CHAPTER 8 Database
"instanceOnly" : false,
.
.
.
4. To find the oracle home directory (or database home), run the dbcli list-dbhomes
command. If there are multiple database homes on the DB system, use the one that
matches the "dbHomeId" in the dbcli list-databases -j command output shown
above.
[root@dbtst ~]# dbcli list-dbhomes
ID Name DB Version
---------------------------------------- -------------------- -----------------------------------
----- --------------------------------------------- ----------
2efe7af7-0b70-4e9b-ba8b-71f11c6fe287 OraDB12102_home1 12.1.0.2.160719 (23739960,
23144544) /u01/app/oracle/product/12.1.0.2/dbhome_1 Configured
33ae99fe-5413-4392-88da-997f3cd24c0f OraDB11204_home1 11.2.0.4.160719 (23054319,
23054359) /u01/app/oracle/product/11.2.0.4/dbhome_1 Configured
Creating a Primary DB System
If you don't already have a primary DB system, create one as described in Managing DB
Systems. The DB system will include an initial database. You can create additional databases
by using the dbcli create-database command available on the DB system.

CHAPTER 8 Database
Creating a Standby DB System
Note
The standby database must have the same db_name as

the primary database, but it must have a different db_
unique_name. If you use the same database name for
the standby and primary, you will have to delete the
database from the standby DB system by using the
dbcli delete-database command before you can run
the dbcli create-database command described
below. Deleting and creating the database will take
several minutes to complete. The dbcli commands
must be run as the root user.
1. Create a standby DB system as described in Managing DB Systems and wait for the DB
system to finish provisioning and become available.
You can create the standby DB system in a different availability domain from the
primary DB system for availability and disaster recovery purposes (this is strongly
recommended). You can create the standby DB system in the primary DB system's
cloud network so that both systems are in a single, routable network.
login as: opc
4. The DB system will include an initial database, but you'll need to create a standby
database by using the dbcli create-database command with the --instanceonly

CHAPTER 8 Database
parameter. This parameter creates only the database storage structure and starts the
database in nomount mode (no other database files are created).
When using --instanceonly, both the --dbname and --adminpassword parameters are
required and they should match the dbname and admin password of the primary
database to avoid confusion.
The following sample command prompts for the admin password and then creates a
storage structure for a database named dbname.
[root@dbsys ~]# dbcli create-database --dbname <same as primary dbname> --databaseUniqueName
<different from primary uniquename> --instanceonly --adminpassword
If you are using pluggable databases, also specify the --cdb parameter.
For complete command syntax, see dbcli create-database.
5. Wait a few minutes for the dbcli create-database command to create the standby
database.
You can use the dbcli list-jobs command to verify that the creation job ran
successfully, and then the dbcli list-databases command verify that the database is
configured.
Preparing the Primary DB System
To prepare the primary DB system, you'll need to configure static listeners, update
tnsnames.ora, and configure some database settings and parameters.
CONFIGURING THE S TATIC LISTENERS
Create static listeners to be used by RMAN and Data Guard Broker.
1. SSH to the primary DB system, log in as the opc or root user, and sudo to the grid
OS user.
sudo su - grid
2. Edit /u01/app/<version>/grid/network/admin/listener.ora and add the following

content to it. The first static listener shown here is optional. The second DGMGRL static
listener is optional for version 12.1 or later databases, but required for version 11.2
databases.

CHAPTER 8 Database
SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <primary_db_unique_name>.<primary_db_domain>)
(SID_NAME = <primary_oracle_sid>)
(ORACLE_HOME=<oracle_home_directory>)
(ENVS="TNS_ADMIN=<oracle_home_directory>/network/admin")
)
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <primary_db_unique_name>_DGMGRL.<primary_db_domain>)
(SID_NAME = <primary_oracle_sid>)
(ORACLE_HOME=<oracle_home_directory>)
(ENVS="TNS_ADMIN=<oracle_home_directory>/network/admin")
)
)
3. Save your changes and then restart the listener.

$ srvctl stop listener
$ srvctl start listener
ADDING NET S ERVICE NAMES TO TNSNAMES.ORA
As the oracle user, edit $ORACLE_HOME/network/admin/tnsnames.ora and add the standby

database net service name to it.
<standby db_unique_name> =
(DESCRIPTION =
(SDU=65535)
(ADDRESS = (PROTOCOL = TCP)(HOST = <standby_server>.<domain>) (PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = <standby db_unique_name>.<standby db_domain>)
)
)
The sample above assumes that name resolution is working and that the <standby_
server>.<domain> is resolvable at the primary database. You can also use the private IP
address of the standby server if the IP addresses are routable within a single cloud network
(VCN).

CHAPTER 8 Database
CONFIGURING PRIMARY DATABASE PARAMETERS
Tip
If the primary and standby hosts have different

directory structures, you might need to set additional
parameters that are not discussed here, such as the
log_file_name_convert parameter. See the
RMAN documentation for more information about how to
create standbys for hosts with different directory
structures.
1. As the oracle user, enable automatic standby file management.

SQL> alter system set standby_file_management=AUTO;
2. Identify the Broker configuration file names and locations. The commands used for this
depend on the type of database storage. If you're not sure of the database storage type,
use the dbcli list-databases command on the DB system.
For ACFS database storage, use the following commands to set the Broker configuration
files.
SQL> alter system set dg_broker_config_file1='/u02/app/oracle/oradata/<Primary db_unique_
name>/dbs/dr1<Primary db_unique_name>.dat';
SQL> alter system set dg_broker_config_file2='/u02/app/oracle/oradata/<Primary db_unique_
name>/dbs/dr2<Primary db_unique_name>.dat';
For ASM database storage, use the following commands to set the Broker configuration
files.
SQL> alter system set dg_broker_config_file1='+DATA/<Primary db_unique_name>/dr1<db_unique_
name>.dat';
SQL> alter system set dg_broker_config_file2='+DATA/<Primary db_unique_name>/dr2<db_unique_
name>.dat';
3. Enable Broker DMON process for the database.

SQL> alter system set dg_broker_start=true;

CHAPTER 8 Database
4. Force database logging for all database transactions.

SQL> alter database force logging ;
5. Add Standby Redo Logs (SRLs), based on the Online Redo Logs (ORLs). On a newly
launched DB system, there will be three ORLs of size 1073741824, so create four SRLs
of the same size.
You can use the query below to determine the number and size (in bytes) of the ORLs.
SQL> select group#, bytes from v$log;
GROUP# BYTES
---------- ----------
1 1073741824
2 1073741824
3 1073741824
All of the ORLs must be the same size.

The SRLs must be the same size as the ORLs, but there must be at least one more SRL
than the ORLs. In the example above, there are three ORLs, so four SRLs are required.
So specify the current redo logs plus one, and use the same size as the redo logs.
SQL> alter database add standby logfile thread 1 size <size>;
There should be only one member in the SRL group (by default, a DB system is created
with only one member per SRL group). To ensure this, you can name the file with the
following syntax.
alter database add standby logfile thread 1 group 4 (<logfile name with full path>) size
1073741824, group 5(<logfile name with full path>) size 1073741824 ...
For ASM/OMF configurations, the above command uses the diskgroup instead of <logfile
name with full path>.
alter database add standby logfile thread 1 group 4 (+RECO) size 1073741824, group 5(+RECO) size
1073741824 ...

CHAPTER 8 Database
Tip
ORLs and SRLs should be sized so that log switches

do not occur more frequently than every 10
minutes. This requires knowledge of the application
and may need to be adjusted after deployment. For
more information, see Use Standby Redo Logs and
Configure Size Appropriately.
6. Verify that you created the correct number of SRLs.

SQL> select group#, bytes from v$standby_log;
7. Make sure the database is in ARCHIVELOG mode.

SQL> archive log list
8. Enable database FLASHBACK. The minimum recommended value for db_flashback_

retention_target is 120 minutes.
SQL> alter database flashback on ;
SQL> alter system set db_flashback_retention_target=120;
9. Perform a single switch redo log to activate archiving if database is newly created. (At
least one log must be archived prior to running the RMAN duplicate.)
SQL> alter system switch logfile;
Preparing the Standby Database
Before you prepare the standby database, make sure the database home on the standby is the
same version as on the primary. (If the primary and standby databases are both newly
created with the same database version, the database homes will be the same.) If it is not,
create a database home that is the same version. You can use the dbcli list-dbhomes
command to verify the versions and the dbcli create-dbhome command to create a new
database home as needed.

CHAPTER 8 Database
To prepare the standby DB system, you'll need to configure static listeners, update
tnsnames.ora, configure TDE Wallet, create a temporary password file, verify connectivity,
run RMAN DUPLICATE, enable FLASHBACK, and then create the database service.
CONFIGURING THE S TATIC LISTENERS
Create static listeners to be used by RMAN and Data Guard Broker.
1. SSH to the standby DB system, log in as the opc or root user, and sudo to the grid
OS user.
sudo su - grid
2. Append the following content to /u01/app/<db_

version>/grid/network/admin/listener.ora.
The first static listener shown below is required for RMAN DUPLICATE. The second
DGMGRL static listener is optional for database versions 12.2.0.1 and 12.1.0.2, but
required for database version 11.2.0.4.
SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <standby db_unique_name>.<standby db_domain>)
(SID_NAME = <standby oracle_sid>)
(ORACLE_HOME=<oracle home directory>)
(ENVS="TNS_ADMIN=<oracle home directory>/network/admin")
)
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <standby db_unique_name>_DGMGRL.<standby db_domain>)
(SID_NAME = <standby oracle_sid>)
(ORACLE_HOME=<oracle home directory>)
(ENVS="TNS_ADMIN=<oracle home directory>/network/admin")
)
)
3. Restart the listener.

$ srvctl stop listener
$ srvctl start listener

CHAPTER 8 Database
4. Verify that the static listeners are available. The sample output below is for database
version 12.1.0.2. Note that the ...status UNKNOWN messages are expected at this
point.
$ lsnrctl status
LSNRCTL for Linux: Version 12.1.0.2.0 - Production on 29-SEP-2016 21:09:25
Copyright (c) 1991, 2014, Oracle. All rights reserved.
Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=LISTENER)))
STATUS of the LISTENER
------------------------
Alias LISTENER
Version TNSLSNR for Linux: Version 12.1.0.2.0 - Production
Start Date 29-SEP-2016 21:09:19
Uptime 0 days 0 hr. 0 min. 5 sec
Trace Level off
Security ON: Local OS Authentication
SNMP OFF
Listener Parameter File /u01/app/12.1.0.2/grid/network/admin/listener.ora
Listener Log File /u01/app/grid/diag/tnslsnr/dg2/listener/alert/log.xml
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=LISTENER)))
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=10.0.1.24)(PORT=1521)))
Services Summary...
Service "dg2_phx2hx.oratst.org" has 1 instance(s).
Instance "dg2", status UNKNOWN, has 1 handler(s) for this service...
Service "dg2_phx2hx_DGMGRL.oratst.org" has 1 instance(s).
Instance "dg2", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully
ADDING NET S ERVICE NAMES TO TNSNAMES.ORA
As the oracle user, add the standby database net service name to $ORACLE_
HOME/network/admin/tnsnames.ora. $ORACLE_HOME is the database home where the
standby database is running.
<Primary db_unique_name> =
(DESCRIPTION =
(SDU=65535)
(ADDRESS = (PROTOCOL = TCP)(HOST = <primary_server>.<domain>) (PORT = 1521))

CHAPTER 8 Database
(CONNECT_DATA =
(SERVICE_NAME = <primary db_unique_name).<primary db_domain>)
)
)
<Standby db_unique_name> =
(DESCRIPTION =
(SDU=65535)
(ADDRESS = (PROTOCOL = TCP)(HOST = <standby_server>.<domain>) (PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = <standby db_unique_name>.<db_domain>)
)
)
COPYING THE TDE W ALLETS TO THE S TANDBY S YSTEM
Copy the TDE wallet files from the primary DB system to standby DB system using SCP. The
following sample command assumes the SCP command is being run by the oracle OS user and
that the private key for oracle has been created and exists on the host where SCP is being run.
$ scp -i <private key> primary_server:/opt/oracle/dcs/commonstore/wallets/tde/<primary db_unique_name>/*
standby_server:/opt/oracle/dcs/commonstore/wallets/tde/<standby db_unique_name>
S ETTING UP THE S TANDBY S YSTEM CONFIGURATION
As the oracle user, create the following directory for database version 11.2.0.4. This step is
optional for version 12.2.0.1 and version 12.1.0.2.
[oracle@dbsys ~]$ mkdir -pv /u03/app/oracle/redo/<standby db_unique_name uppercase>/controlfile
CREATING THE AUDIT FILE DESTINATION
As the oracle user, create the following directory to use as the audit file destination.
[oracle@dbsys ~]$ mkdir -p /u01/app/oracle/admin/<db_name>/adump
Otherwise, the RMAN duplicate command used later will fail.
CREATING A TEMPORARY PASSWORD FILE
As the oracle user, create a temporary password file.

CHAPTER 8 Database
[oracle@dbsys ~]$ orapwd file=$ORACLE_HOME/dbs/orapw<standby oracle_sid> password=<admin password for

primary> entries=5
The password must be the same as the admin password of the primary database. Otherwise,
the RMAN duplicate step below will fail with: RMAN-05614: Passwords for target and
auxiliary connections must be the same when using active duplicate.
VERIFYING THE S TANDBY DATABASE IS AVAILABLE
1. As the oracle user, set the environment variables.

[oracle@dbsys ~]$ . oraenv
<enter the db_name>
2. Replace $ORACLE_HOME/dbs/init<standby sid_name>.ora with the following content.

db_name=<Primary db_name>
db_unique_name=<standby db_unique_name>
db_domain=<standby db_domain>
3. Remove the spfile from the standby:

/u02/app/oracle/oradata/<standby db_unique_name>/dbs/spfile$ORACLE_SID.ora
The database needs to be started in nomount mode with no spfile specified, but the
original init file contains an spfile parameter which will prevent the RMAN duplicate step
from working.
4. The dbcli create-database --instanceonly command used earlier opens the
standby database as a primary in read/write mode, so the database needs to be brought
down before proceeding to the nomount step below.
$ sqlplus / as sysdba
SQL> shutdown immediate
5. Start the database in nomount mode.

SQL> startup nomount
VERIFYING THE DATABASE CONNECTIONS
Verify the connection between the primary and standby databases.

CHAPTER 8 Database
1. Make sure that the listener port 1521 is open in the security list(s) used for the primary
and standby DB Systems. For more information, see Updating the Security List for the
DB System.
2. From the primary database, connect to standby database.
$ sqlplus sys/<password>@<standby net service name> as sysdba
3. From standby database, connect to primary database.

$ sqlplus sys/<password>@<primary net service name> as sysdba
RUNNING THE RMAN DUPLICATE COMMAND
Run the RMAN DUPLICATE command on the standby DB system, as the oracle user.
If the primary database is large, you can allocate additional channels to improve
performance. For a newly installed database, one channel typically runs the database
duplication in a couple of minutes.
Make sure that there are no errors generated by the RMAN DUPLICATE command. If errors
occur, restart the database using the init.ora file (not spfile) in case it is generated under
$ORACLE_HOME/dbs as part of RMAN DUPLICATE.
In the following examples, use lowercase for the <Standby db_unique_name> unless
otherwise specified.
For ACFS storage layout, run the following commands.

$ rman target sys/<password>@<primary alias> auxiliary sys/<password>@<standby alias> log=rman.out
RMAN> run { allocate channel prim1 type disk;

allocate auxiliary channel sby type disk;
duplicate target database for standby from active database
dorecover
spfile
parameter_value_convert '/<Primary db_unique_name>/','/<Standby db_unique_name>/','/<Primary
db_unique_name uppercase>/','/<Standby db_unique_name uppercase >/'
set db_unique_name='<Standby db_unique_name>'
set db_create_file_dest='/u02/app/oracle/oradata/<Standby db_unique_name>'
set dg_broker_config_file1='/u02/app/oracle/oradata/<Standby db_unique_name>/dbs/dr1<Standby
db_unique_name>.dat'
set dg_broker_config_file2='/u02/app/oracle/oradata/<Standby db_unique_name>/dbs/dr2<Standby

CHAPTER 8 Database
db_unique_name>.dat'
set dispatchers ='(PROTOCOL=TCP) (SERVICE=<Standby db_unique_name>XDB)'
set instance_name='<Standby db_unique_name>'
;
}
For ASM storage layout, run the following commands.

$ rman target sys/<password>@<primary alias> auxiliary sys/<password>@<standby alias> log=rman.out
RMAN> run { allocate channel prim1 type disk;

allocate auxiliary channel sby type disk;
duplicate target database for standby from active database
dorecover
spfile
parameter_value_convert '/<Primary db_unique_name>/','/<Standby db_unique_name>/','/<Primary
db_unique_name uppercase>/','/<Standby db_unique_name uppercase>/'
set db_unique_name='<Standby db_unique_name>'
set dg_broker_config_file1='+DATA/<Standby db_unique_name>/dr1<Standby db_unique_name>.dat'
set dg_broker_config_file2='+DATA/<Standby db_unique_name>/dr2<Standby db_unique_name>.dat'
set dispatchers ='(PROTOCOL=TCP) (SERVICE=<Standby db_unique_name>XDB)'
set instance_name='<Standby db_unique_name>'
;
}
ENABLING DATABASE FLASHBACK
1. As a Data Guard best practice, enable flashback and set db_flashback_retention_

target to at least 120 minutes on both the primary and standby databases.
SQL> alter database flashback on;
SQL> alter system set db_flashback_retention_target=120;
2. Verify that the standby database is created properly.

SQL> select FORCE_LOGGING, FLASHBACK_ON, OPEN_MODE, DATABASE_ROLE,SWITCHOVER_STATUS, DATAGUARD_
BROKER, PROTECTION_MODE from v$database ;
CREATING A DATABASE S ERVICE
Oracle recommends creating a database service for the standby database by using srvctl.
For ACFS storage layout.

CHAPTER 8 Database
1. Create a shared directory and copy the spfile file to it.

$ mkdir -pv /u02/app/oracle/oradata/<Standby db_unique_name>/dbs
$ cp $ORACLE_HOME/dbs/spfile<standby oracle_sid>.ora /u02/app/oracle/oradata/<Standby db_unique_
name>/dbs
2. Stop and remove the existing database service.

$ srvctl stop database -d <standby db_unique_name>
$ srvctl remove database -d <standby db_unique_name>
3. Create the database service.

$ srvctl add database -d <standby db_unique_name> -n <standby db_name> -o $ORACLE_HOME -c SINGLE
-p '/u02/app/oracle/oradata/<standby db_unique_name>/dbs/spfile<standby db_name>.ora'
-x <standby hostname> -s "READ ONLY" -r PHYSICAL_STANDBY -i <db_name>
$ srvctl setenv database -d <standby db_unique_name> -t "ORACLE_
UNQNAME=<standby db_unique_name>"
$ srvctl config database -d <standby db_unique_name>
4. Start the database service.

$ srvctl start database -d <standby db_unique_name>
5. Clean up the files from $ORACLE_HOME/dbs.

$ rm $ORACLE_HOME/dbs/spfile<standby oracle_sid>.ora
$ rm $ORACLE_HOME/dbs/init<standby oracle_sid>.ora
6. Create the $ORACLE_HOME/dbs/init<standby oracle_sid>.ora file to reference the

new location of the spfile file.
SPFILE='/u02/app/oracle/oradata/<standby db_unique_name>/dbs/spfile<standby db_name>.ora'
7. Stop the standby database and then start it by using srvctl.

srvctl stop database -d <standby db_unique_name>
srvctl start database -d <standby db_unique_name>
For ASM storage layout.
1. Consider generating the spfile file under +DATA.

SQL> create pfile='init<standby oracle_sid>.ora' from spfile ;
SQL> create spfile='+DATA' from pfile='init<standby oracle_sid>.ora' ;

CHAPTER 8 Database
2. Stop and remove the existing database service.

$ srvctl stop database -d <standby db_unique_name>
$ srvctl remove database -d <standby db_unique_name>
3. Create the database service.

$ srvctl add database -d <standby db_unique_name> -n <standby db_name> -o $ORACLE_HOME -c
SINGLE -p '+DATA/<standby db_unique_name>/PARAMETERFILE/spfile.xxx.xxxxxx'
-x <standby hostname> -s "READ ONLY" -r PHYSICAL_STANDBY -i <db_name>
$ srvctl setenv database -d <standby db_unique_name> -t "ORACLE_UNQNAME=<standby db_unique_name>"
$ srvctl config database -d <standby db_unique_name>
4. Start the database service.

5. Clean up the files from $ORACLE_HOME/dbs.

$ rm $ORACLE_HOME/dbs/init<standby oracle_sid>.ora
$ rm $ORACLE_HOME/dbs/spfile<standby oracle_sid>.ora
6. Create $ORACLE_HOME/dbs/init<standby oracle_sid>.ora file to reference the new

location of the spfile file.
SPFILE='+DATA/<standby db_unique_name>/PARAMETERFILE/spfile.xxx.xxxxxx'
7. Stop the database and start the standby database by using srvctl.
Configuring Data Guard
Perform the following steps to complete the configuration of Data Guard and enable redo
transport from the primary database and redo apply in the standby database.
1. Run the dgmgrl command line utility from either the primary or standby DB system and
connect to the primary database using sys credentials.
DGMGRL> connect sys/<sys password>@<primary tns alias>
2. Create the Data Guard configuration and identify for the primary and standby
databases.

CHAPTER 8 Database
DGMGRL> create configuration mystby as primary database is <primary db_unique_name> connect

identifier is <primary tns alias>;
add database <standby db_unique_name> as connect identifier is <standby tns alias> maintained
as physical;
3. Enable Data Guard configuration.

DGMGRL> enable configuration;
4. Verify that Data Guard setup was done properly. Run the following SQL in both the
primary and standby databases.
SQL> select FORCE_LOGGING, FLASHBACK_ON, OPEN_MODE, DATABASE_ROLE, SWITCHOVER_STATUS, DATAGUARD_
BROKER, PROTECTION_MODE from v$database;
5. Verify that Data Guard processes are initiated in the standby database.
SQL> select PROCESS,PID,DELAY_MINS from V$MANAGED_STANDBY;
6. Verify parameter configuration on primary and standby.

SQL> show parameter log_archive_dest_
SQL> show parameter log_archive_config
SQL> show parameter fal_server
SQL> show parameter log_archive_format
7. Verify that the Data Guard configuration is working. Specifically, make sure redo
shipping and redo apply are working and that the standby is not unreasonably lagging
behind the primary.
DGMGRL> show configuration verbose
DGMGRL> show database verbose <standby db_unique_name>
DGMGRL> show database verbose <primary db_unique_name>
Any discrepancies, errors, or warnings should be resolved. You can also run a
transaction on the primary and verify that it's visible in the standby.
8. Verify that the Data Guard configuration is functioning as expected by performing
switchover and failover in both directions. Run show configuration after each
operation and make sure there are no errors or warnings.

CHAPTER 8 Database
Warning
This step is optional, based on your discretion. If for

any reason the configuration is not valid, the
switchover and/or failover will fail and it might be
difficult or impossible to start the primary
database. A recovery of the primary might be
required, which will affect availability.
DGMGRL> switchover to <standby db_unique_name>

DGMGRL> switchover to <primary db_unique_name>
#connect to standby before failover:
DGMGRL> connect sys/<sys password>@<standby db_unique_name>

DGMGRL> failover to <standby db_unique_name>
DGMGRL> reinstate database <primary db_unique_name>
#connect to primary before failover:
DGMGRL> connect sys/<sys password>@<primary db_unique_name>

DGMGRL> failover to <primary db_unique_name>
DGMGRL> reinstate database <standby db_unique_name>
Configuring Observer (Optional)
The best practice for high availability and durability is to run the primary, standby, and
observer in separate availability domains. The observer determines whether or not to failover
to a specific target standby database. The server used for observer requires the Oracle Client
Administrator software, which includes the Oracle SQL NET and Broker.
1. Configure TNS alias names for both the primary and standby databases as described
previously, and verify the connection to both databases.
2. Change protection mode to either maxavailability or maxperformance (maxprotection is
not supported for FSFO).

CHAPTER 8 Database
To enable maxavailability:
DGMGRL> edit database <standby db_unique_name> set property 'logXptMode'='SYNC';
DGMGRL> edit database <primary db_unique_name> set property 'logXptMode'='SYNC';
DGMGRL> edit configuration set protection mode as maxavailability;
To enable maxperformance:
DGMGRL> edit configuration set protection mode as maxperformance;
DGMGRL> edit database <standby db_unique_name> set property 'logXptMode'='ASYNC';
DGMGRL> edit database <primary db_unique_name> set property 'logXptMode'='ASYNC';
For maxperformance, the FastStartFailoverLaglimit property limits the maximum

amount of permitted data loss to 30 seconds by default.
3. The following properties should also be considered. Run show configuration verbose
to see their current values.
l FastStartFailoverPmyShutdown
l FastStartFailoverThreshold
l FastStartFailoverTarget
l FastStartFailoverAutoReinstate
(Running show configuration will result in the following error until the observer is
started: Warning : ORA-16819: fast-start failover observer not started.)
4. Enable fast-start failover from Broker:
DGMGRL> Enable fast_start failover
5. Verify the fast-start failover and associated settings.

DGMGRL> show fast_start failover
6. Start the observer from Broker (it will run in the foreground, but can also be run in the
background).
DGMGRL> start observer
7. Verify fast-start failover is enabled and without errors or warnings.

DGMGRL> show configuration verbose
8. Always test failover in both directions to ensure that everything is working as expected.

CHAPTER 8 Database
Verify that FSFO is running properly by performing a shutdown abort of the primary
database.
The observer should start the failover to the standby database. If protection mode is set
to maxprotection, some loss of data can occur, based on the FastStartFailoverLaglimit
value.
Oracle Database CLI Reference
Note
The database command line interface (CLI) is available on 1-node and 2-node
RAC DB systems. After you connect to the DB system, you can use the database CLI to
perform tasks such as creating Oracle database homes and databases.

CHAPTER 8 Database
Note
On April 20, 2017, the odacli CLI was renamed to

dbcli and the odadmcli administrative CLI was
renamed to dbadmcli. DB systems launched on or after
that date will include the renamed CLIs.
For DB systems launched before April 20, 2017:
l Use the cliadm update-dbcli command to get

the dbcli.
l Use the dbcli update-server command to get
the dbadmcli.
The odacli and odadmcli CLIs will remain available on

older DB systems for a while to ensure backward
compatibility. However, those CLIs are no longer
supported and you should begin using the newer CLIs.
Operational Notes
l The dbcli commands must be run as the root user.

l The dbcli is in the following directory:
/opt/oracle/dcs/bin/
The directory is included in the path for the root user's environment.
l Oracle Database maintains logs of the dbcli command output in the dcscli.log and
dcs-agent.log files in the following directory:
/opt/oracle/dcs/log/
l The CLI commands and most parameters are case sensitive and should be typed as
shown. A few parameters are not case sensitive, as indicated in the parameter
descriptions, and can be typed in uppercase or lowercase.

CHAPTER 8 Database
Syntax
The database CLI commands use the following syntax:

dbcli command [parameters]
where:
l command is a verb-object combination such as create-database.

l parameters include additional options for the command. Most parameter names are
preceded with two dashes, for example, --help. Abbreviated parameter names are
preceded with one dash, for example, -h.
l User-specified parameter values are shown in red text within angle brackets, for
example, <db_home_id>. Omit the angle brackets when specifying these values.
l The help parameter is available with every command.
The remainder of this topic contains syntax and other details about the commands.
CLI Update Command
Occasionally, new commands are added to the database CLI and other commands are updated
to support new features. You can use the following command to update the database CLI:
CLIADM UPDATE -DBCLI
Use the cliadm update-dbcli command to update the database CLI with the latest new and
updated commands.
Note
The cliadm update-dbcli command is not available on

SYNTAX
cliadm update-dbcli [-h] [-j]

CHAPTER 8 Database
PARAMETERS
Parameter Full Name Description
-h --help (Optional) Displays help for using the command.
-j --json (Optional) Displays JSON output.
E XAMPLE
The following command updates the dbcli:

[root@dbsys ~]# cliadm update-dbcli
{
"jobId" : "dc9ce73d-ed71-4473-99cd-9663b9d79bfd",
"message" : "Dcs cli will be updated",
"reports" : [ ],
"description" : "dbcli patching",
}
Backup Command
Before you can back up a database by using the dbcli create-backup command, you'll need to:
1. Create a backup configuration by using the dbcli create-backupconfig command.

2. Associate the backup configuration to the database by using the dbcli update-database
command.
Once a database is associated with a backup configuration, you can use the database's default
backup schedule to run back up jobs automatically. For more information, see Schedule
Commands.
DBCLI CREATE -BACKUP
Use the dbcli create-backup command to create a backup of a database.

CHAPTER 8 Database
SYNTAX
dbcli create-backup -i <db_id> [-h] [-j]
PARAMETERS
-i --dbid The ID of the database to back up. Use the dbcli list-
databases command to get the database's ID.
E XAMPLE
The following command creates a backup of the specified database.

[root@dbsys ~]# dbcli create-backup -i 573cadb2-0cc2-4c1c-9c31-595ab8963d5b
Backupconfig Commands
A backup configuration determines the backup destination and recovery window for database
backups. You create the backup configuration and then associate it to a database by using the
dbcli update-database command.
Once a database is associated with a backup configuration, you can use the database's default
backup schedule to run back up jobs automatically. For more information, see Schedule
Commands.
The following commands are available to manage backup configurations:
l dbcli create-backupconfig
l dbcli delete-backupconfig

CHAPTER 8 Database
DBCLI CREATE -BACKUPCONFIG
Use the dbcli create-backupconfig command to create a backup configuration that defines
the backup destination and recovery windows.
SYNTAX
dbcli create-backupconfig -d {DISK|OBJECTSTORE|NONE} -c <bucket> -o <object_store_swift_id> -w <n> -n

<name> [-h] [-j]
PARAMETERS
-c --container The name of an existing bucket in the Oracle Cloud

Infrastructure Object Storage service. You can use the
Console or the Object Storage API to create the bucket.
For more information, see Managing Buckets.
You must also specify --backupdestination

objectstore and the --objectstoreswiftId
parameter.
-d -- The backup destination as one of the following (these

backupdestination values are not case sensitive):
DISK - The local Fast Recovery Area.
OBJECTSTORE - The Oracle Cloud Infrastructure Object

Storage service. You must also specify the --container
and --objectstoreswiftId parameters.
The OBJECTSTORE destination is not available for 2-node

RAC DB systems.
NONE - Disables the backup.

CHAPTER 8 Database
-n --name The name of the backup configuration.
-o -- The ID of the object store that contains the endpoint and
objectstoreswiftId credentials for the Oracle Cloud Infrastructure Object
Storage service. Use the dbcli list-objectstoreswifts
command to get the object store ID. Use the dbcli
create-objectstoreswift command to create an object
store.

objectstore and the --container parameter.
-w --recoverywindow The number of days for which backups and archived redo
logs are maintained. The interval always ends with the
current time and extends back in time for the number of
days specified.
For a DISK backup destination, specify 1 to 14 days.
For an OBJECTSTORE backup destination, specify 1 to 30

days.
E XAMPLE
The following command creates a backup configuration named dbbkcfg1:

[root@dbsys ~]# dbcli create-backupconfig -d Disk -w 7 -n dbbkcfg1
{
"jobId" : "4e0e6011-db53-4142-82ef-eb561658a0a9",
"message" : null,
"reports" : [ {
"taskId" : "TaskParallel_919",
"taskName" : "persisting backup config metadata",
"taskResult" : "Success",
"startTime" : "November 18, 2016 20:21:25 PM UTC",

CHAPTER 8 Database
"endTime" : "November 18, 2016 20:21:25 PM UTC",

"taskDescription" : null,
"parentTaskId" : "TaskSequential_915",
"jobId" : "4e0e6011-db53-4142-82ef-eb561658a0a9",
"tags" : [ ],
"reportLevel" : "Info",
"updatedTime" : "November 18, 2016 20:21:25 PM UTC"
} ],
"createTimestamp" : "November 18, 2016 20:21:25 PM UTC",
"description" : "create backup config:dbbkcfg1",
}
DBCLI LIST -BACKUPCONFIGS
Use the dbcli list-backupconfigs command to list all the backup configurations in the DB
system.
SYNTAX
dbcli list-backupconfigs [-h] [-j]
PARAMETERS
E XAMPLE
The following command lists a backup configuration:

[root@dbsys ~]# dbcli list-backupconfigs
ID Name RecoveryWindow BackupDestination

CreateTime
---------------------------------------- -------------------- ------------------ ----------------- -----
------------------------

CHAPTER 8 Database
ccdd56fe-a40b-4e82-b38d-5f76c265282d dbbkcfg1 7 Disk July

10, 2016 12:24:08 PM UTC
DBCLI DESCRIBE -BACKUPCONFIG
Use the dbcli describe-backupconfig command to show details about a specific backup
configuration.
SYNTAX
dbcli describe-backupconfig -i <id> [-h] [-j]
PARAMETERS
-i -- The backup configuration ID. Use the dbcli list-

backupconfigid backupconfigs command to get the ID.
E XAMPLE
The following command displays details about a backup configuration:

[root@dbsys ~]# dbcli describe-backupconfig -i ccdd56fe-a40b-4e82-b38d-5f76c265282d
Backup Config details

----------------------------------------------------------------
ID: ccdd56fe-a40b-4e82-b38d-5f76c265282d
Name: dbbkcfg1
RecoveryWindow: 7
BackupDestination: Disk
CreatedTime: July 10, 2016 12:24:08 PM UTC
UpdatedTime: July 10, 2016 12:24:08 PM UTC
DBCLI UPDATE -BACKUPCONFIG
Use the dbcli update-backupconfig command to update an existing backup configuration.

CHAPTER 8 Database
SYNTAX
dbcli update-backupconfig -i <id> -w <n> -d {DISK|OBJECTSTORE|NONE} -c <bucket> -o <object_store_swift_

id> [-h] [-j]
PARAMETERS
-c --container The name of an existing bucket in the Oracle Cloud

Infrastructure Object Storage service. You can use the
Console or the Object Storage API to create the bucket.
For more information, see Managing Buckets.

objectstore and the --objectstoreswiftId
parameter.
-d -- The new backup destination, (these values are not case

backupdestination sensitive):
DISK - The local Fast Recovery Area.
OBJECTSTORE - The Oracle Cloud Infrastructure Object

Storage service. You must also specify the --container
and --objectstoreswiftId parameters. The
OBJECTSTORE destination is not available for 2-node
RAC DB systems.
NONE - Disables the backup.
-i --backupconfigid The ID of the backup configuration to update. Use the

dbcli list-backupconfigs command to get the ID.

CHAPTER 8 Database
-o -- The ID of the object store that contains the endpoint and
objectstoreswiftId credentials for the Oracle Cloud Infrastructure Object
Storage service. Use the dbcli list-objectstoreswifts
command to get the object store ID. Use the dbcli
create-objectstoreswift command to create an object
store.

objectstore and the --container parameter.
-w --recoverywindow The new disk recovery window.
For a DISK backup destination, specify 1 to 14 days.
For an OBJECTSTORE backup destination, specify 1 to 30

days.
E XAMPLE
The following command updates the recovery window for a backup configuration:
[root@dbsys ~]# dbcli update-backupconfig -i ccdd56fe-a40b-4e82-b38d-5f76c265282d -w 5
{
"jobId" : "0e849291-e1e1-4c7a-8dd2-62b522b9b807",
"message" : null,
"reports" : [ ],
"description" : "update backup config: dbbkcfg1",
"updatedTime" : 1468153731700
}
DBCLI DELETE -BACKUPCONFIG
Use the dbcli delete-backupconfig command to delete a backup configuration.
SYNTAX
dbcli delete-backupconfig -i <id> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-i --id The backup configuration ID to delete. Use the dbcli list-
backupconfigs command to get the ID.
E XAMPLE
The following command deletes the specified backup configuration:

[root@dbsys ~]# dbcli delete-backupconfig -i ccdd56fe-a40b-4e82-b38d-5f76c265282d
Backupreport Commands
The following commands are available to manage backup reports:
l dbcli create-backupreport
l dbcli list-backupreports
l dbcli delete-backupreport
l dbcli describe-backupreport
DBCLI CREATE -BACKUPREPORT
Use the dbcli create-backupreport command to create a back up report for a database.
SYNTAX
dbcli create-backupreport -i <db_id> -w {summary|detailed} [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-i --dbid The ID of the database to create the report for. This ID is
different from the DBID. Use the dbcli list-databases
command to get the database ID.
-w -- The level of detail in the back up report as either summary or

reporttype detailed.
E XAMPLE
The following command create a detailed backup report for the specified database:
[root@dbsys ~]# dbcli create-backupreport -i a892ced1-be04-436e-8e82-bf0a89109164 -w detailed
DBCLI LIST -BACKUPREPORTS
Use the dbcli list-backupreports command to list backup reports.
SYNTAX
dbcli list-backupreports -i <db_id> [-h] [-j]
PARAMETERS
-i --dbid (Optional) Displays the backup reports for the specified

database ID. Use the dbcli list-databases command to get
the database ID.

CHAPTER 8 Database
E XAMPLE
The following command lists the back up reports:

[root@dbsys ~]# dbcli list-backupreports
DBCLI DELETE -BACKUPREPORT
Use the dbcli delete-backupreport command to permanently delete one or more backup
reports.
SYNTAX
dbcli delete-backupreport -i <report_id> -d <db_id> -n <number> [-h] [-j]
PARAMETERS
-d --dbid (Optional) The ID of the database for which you want to delete
backup reports. This ID is different from the DBID. Use the
dbcli list-databases command to get the database ID.
Requires the --numofday parameter.
-i --reportid The ID of a specific backup report to delete. Use the dbcli
list-backupreports command to get the ID.
-n -- (Optional) Deletes backup reports that are older than the

numofday specified number of days, for the specified database. Requires
the --dbid parameter.
E XAMPLE
The following command delete the specified backup report:

[root@dbsys ~]# dbcli delete-backupreport -i a892ced1-be04-436e-8e82-bf0a89109164

CHAPTER 8 Database
DBCLI DESCRIBE -BACKUPREPORT
Use the dbcli describe-backupreport command to display details about a backup report.
SYNTAX
dbcli describe-backupreport -i <report_id> [-h] [-j]
PARAMETERS
-i --id The ID of the backup report. Use the dbcli list-
backupreports command to get the ID.
E XAMPLE
The following command displays the specified backup report:

[root@dbsys ~]# dbcli describe-backupreport -i d7e5c172-a2cc-48a0-8ff3-93ed618645d9
Backup Report details
----------------------------------------------------------------
ID: d7e5c172-a2cc-48a0-8ff3-93ed618645d9
Name:
Report Type: detailed
Location: /opt/oracle/dcs/log/dbtst/rman/bkup/dbtst_phx1cs/rman_list_backup_detail/2016-
11-18/rman_list_backup_detail_2016-11-18_20-41-50.0348.log
Database ID: 80ad855a-5145-4f8f-a08f-406c5e4684ff
CreatedTime: November 18, 2016 8:41:39 PM UTC
UpdatedTime: November 18, 2016 8:41:53 PM UTC
Bmccredential Commands
The following commands are available to manage credentials configurations, which are
required for downloading DB system patches from the Oracle Cloud Infrastructure Object
Storage service. For more information, see Patching a DB System.

CHAPTER 8 Database
l dbcli create-bmccredential
l dbcli list-bmccredentials
l dbcli describe-bmccredential
l dbcli delete-bmccredential
l dbcli update-bmccredential
Note
The bmccredential commands are not available on 2-

node RAC DB systems.
DBCLI CREATE -BMCCREDENTIAL
Use the dbcli create-bmccredential command to create a credentials configuration.
PREREQUISITES
Before you can create a credentials configuration, you'll need these items:
l An RSA key pair in PEM format (minimum 2048 bits). See How to Generate an API
Signing Key.
l The fingerprint of the public key. See How to Get the Key's Fingerprint.
l Your tenancy's OCID and user name's OCID. See Where to Get the Tenancy's OCID and
User's OCID.
Then you'll need to upload the public key in the Console. See How to Upload the Public Key.
SYNTAX
dbcli create-bmccredential -c [backup|patching|other] -t <tenant_ocid> -u <user_ocid> -f <fingerprint>

-k <private_key_path> -p <passphrase> [-e <object_store_url>] [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-c -- The type of Object Storage credentials configuration to

credentialsType create (these values are not case sensitive):
BACKUP - Reserved for the future use.
PATCHING - For downloading patches from the service.
OTHER - Reserved for the future use.
-e -- (Optional) The Object Storage endpoint URL.

objectStoreUrl
Omit this parameter when --credentialsType PATCHING
is specified. The following URL is assumed:
https://objectstorage.<region>.oraclecloud.com
-f --fingerPrint The public key fingerprint. You can find the fingerprint in
the Console by clicking your user name in the upper right
corner and then clicking User Settings. The fingerprint
looks something like this:
-f 61:9e:52:26:4b:dd:46:dc:8c:a8:05:6b:9f:0a:30:d2
-k --privateKey The path to the private key file in PEM format, for example:
-k /root/.ssh/privkey
-n --name (Optional) The name for the new credentials configuration.

The name is useful for tracking the configuration.

CHAPTER 8 Database
-p --passPhrase The passphrase for the public/private key pair, if you

specified one when creating the key pair.
-hp
Specify -p (with no passphrase) to be prompted.
Specify -hp <passphrase> to provide the passphrase in

the command.
-t --tenantOcid Your tenancy OCID. You can find the OCID in the Console,
in the footer at the bottom of any page. The tenancy OCID
looks something like this:
ocid1
.
tenancy
.
oc1..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq
-u --userOcid The user name OCID for your Oracle Cloud Infrastructure

user account. You can find the OCID in the Console by
clicking your user name in the upper right corner and then
clicking User Settings. The user name OCID looks
something like this:
ocidv1
:user:oc1:phx:14587519377:aaaaaaaari4zv5jhf3ohezt7w7c5dgc2wa
E XAMPLE
The following command creates a credentials configuration:

[root@dbsys ~]# dbcli create-bmccredential -c patching -hp mypass -t
ocidv1:tenancy:oc1:phx:1458318978360:aaaaaaaak7jvpjfwrnskt4f3ll2p3jkpra -u
ocid1.user.oc1..aaaaaaaalhdxviuxqi7xevqsksccl6edokgldvuf6raskcioq4x2z7watsfa -f
60:9e:56:26:4b:dd:46:dc:8c:a8:05:6d:9f:0a:30:d2 -k /root/.ssh/privkey
{
"jobId" : "f8c80510-b717-4ee2-a47e-cd380480b28b",

CHAPTER 8 Database
"message" : null,
"reports" : [ ],
"createTimestamp" : "December 26, 2016 22:46:38 PM PST",
"description" : "BMC Credentials Creation",
"updatedTime" : "December 26, 2016 22:46:38 PM PST"
}
DBCLI LIST -BMCCREDENTIALS
Use the dbcli list-bmccredentials command to list the credentials configurations on the
DB system.
SYNTAX
dbcli list-bmccredentials [-h] [-j]
PARAMETERS
E XAMPLE
The following command lists the credentials configurations on the DB system:

[root@dbsys ~]# dbcli list-bmccredentials
ID Name Type End Point
Status
---------------------------------------- ------------- ---------- ------------------------------
----------------------------- ----------
f19d7c8b-d0d5-4jhf-852b-eb2a81cb7ce5 patch1 Patching https://objectstorage.us-
phoenix-1.oraclecloud.com Configured
f1a8741c-b0c4-4jhf-239b-ab2a81jhfde4 patch2 Patching https://objectstorage.us-
phoenix-1.oraclecloud.com Configured

CHAPTER 8 Database
DBCLI DESCRIBE -BMCCREDENTIAL
Use the dbcli describe-bmccredential command to display details about a credentials

configuration.
SYNTAX
dbcli describe-bmccredential -i <credentials_id> [-h] [-j]
PARAMETERS
-i --id The ID for the credentials configuration. Use the dbcli list-
bmccredentials command to get the ID.
E XAMPLE
The following command displays details about the specified credentials configuration:
[root@dbsys ~]# dbcli describe-bmccredential -i 09f9988e-eed5-4dde-8814-890828d1c763
BMC Credentials details

----------------------------------------------------------------
ID: 09f9988e-eed5-4dde-8814-890678d1c763
Name: patch23
Tenant OCID: ocidv1:tenancy:oc1:phx:1458318978360:aaaaaaaak7jhfjfwrnskt4f3ll2p3jkpra
User OCID: ocid1.user.oc1..aaaaaaaalhjhfiuxqi7xevqsksccl6edokgldvuf6raskcioq4x2z7watjhf
Credentials Type: Patching
objectStore URL: https://objectstorage.us-phoenix-1.oraclecloud.com
Status: Configured
UpdatedTime: January 9, 2017 1:41:46 AM PST
DBCLI DELETE -BMCCREDENTIAL
Use the dbcli delete-bmccredential command to delete a credentials configuration.

CHAPTER 8 Database
SYNTAX
dbcli delete-bmccredential -i <credentials_id> [-h] [-j]
PARAMETERS
E XAMPLE
The following command deletes the specified credentials configuration:

[root@dbsys ~]# dbcli delete-bmccredential -i f19d7c8b-d0d5-4jhf-852b-eb2a81cb7ce5
DBCLI UPDATE -BMCCREDENTIAL
Use the dbcli update-bmccredential command to update a credentials configuration.
SYNTAX
dbcli update-bmccredential -i <credentials_id> -c [backup|patching|other] -p <passphrase> -t <tenant_

ocid> -u <user_ocid> -f <fingerprint> -privateKey <private_key_path> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-c -- The type of Object Storage credentials configuration (these

credentialsType values are not case sensitive):
BACKUP - Reserved for the future use.
PATCHING - For downloading patches from the service.
OTHER - Reserved for the future use.
-f --fingerPrint The public key fingerprint, for example:

-f 61:9e:52:26:4b:dd:46:dc:8c:a8:05:6b:9f:0a:30:d2
-k --privateKey The path to the private key file in PEM format, for example:
-k /root/.ssh/privkey
-p --passPhrase The passphrase for the public/private key pair, if you

specified one when creating the key pair.
-hp
Specify -p (with no passphrase) to be prompted.
Specify -hp <passphrase> to provide the passphrase in

the command.
E XAMPLE
The following command updates a credentials configuration:

[root@dbsys ~]# dbcli update-bmccredential -c OTHER -i 6f921b29-61b6-56f4-889a-ce9270621956
{

CHAPTER 8 Database
"jobId" : "6e95a69e-cf73-4e51-a444-c7e4b9631c27",
"message" : null,
"reports" : [ ],
"createTimestamp" : "January 19, 2017 12:01:10 PM PST",
"description" : "Update BMC Credentials of object 6f921b29-61b6-48f4-889a-ce9270621945",
"updatedTime" : "January 19, 2017 12:01:10 PM PST"
Component Command
DBCLI DESCRIBE -COMPONENT
Tip
Your DB system might not include this newer command.

If you have trouble running the command, use the
cliadm update-dbcli command to update the database
CLI and then retry the command.
Note
The dbcli describe-component command is not

available on 2-node RAC DB systems. Patching 2-node
systems from Object Storage is not supported.
Use the dbcli describe-component command to show the installed and available patch
versions for the server, storage, and/or database home components in the DB system.
This command requires a valid Object Storage credentials configuration. Use the dbcli create-
bmccredential command to create the configuration if you haven't already done so. If the

CHAPTER 8 Database
configuration is missing or invalid, the command fails with the error: Failed to connect to
the object store. Please provide valid details.
For more information about updating the CLI, creating the credentials configuration, and
applying patches, see Patching a DB System.
SYNTAX
dbcli describe-component [-s <server_group>] [-d <db_group>] [-h] [-j]
PARAMETERS
-d --dbhomes (Optional) Lists the installed and available patch versions for
only the database home components.
-s --server (Optional) Lists the installed and available patch versions for
only the server components.
E XAMPLE
The following command to show the current component versions and the available patch
versions in the object store:
[root@dbsys ~]# dbcli describe-component
System Version
---------------
12.1.2.10.0
Component Name Installed Version Available Version

---------------------------------------- -------------------- --------------------
OAK 12.1.2.10.0 up-to-date
GI 12.1.0.2.161018 up-to-date
ORADB12102_HOME1 12.1.0.2.160719 12.1.0.2.161018

CHAPTER 8 Database
Database Commands
The following commands are available to manage databases:
l dbcli create-database
l dbcli delete-database
l dbcli describe-database
l dbcli list-databases
l dbcli register-database
l dbcli update-database
DBCLI CREATE -DATABASE
Use the dbcli create-database command to create a new database. You can create a
database with a new or existing Oracle Database Home.
It takes a few minutes to create the database. After you run the dbcli create-database
command, you can use the dbcli list-jobs command to check the status of the database
creation job.
Tip
Wait for the database creation job to complete before

you attempt to create another database. Running
multiple dbcli create-database commands at the
same time can result in some of the creation jobs not
completing.
Once the database is created, you can use the dbcli list-databases -j command to see
additional information about the database.

CHAPTER 8 Database
Note
You must create and activate a master encryption key

for any PDBs that you create. After creating or plugging
in a new PDB on a 1- or 2-node RAC DB System, use the
dbcli update-tdekey command to create and activate
a master encryption key for the PDB. Otherwise, you
might encounter the error ORA-28374: typed master
key not found in wallet when attempting to create
tablespaces in the PDB. In a multitenant environment,
each PDB has its own master encryption key which is
stored in a single keystore used by all containers. For
more information, see "Overview of Managing a
Multitenant Environment" in the Oracle Database
Administrator’s Guide.
SYNTAX
dbcli create-database -dh <db_home_id> -cl {OLTP|DSS|IMDB} -n <db_name> -u <unique_name> -bi <bkup_
config_id> -m -s <db_shape> -r {ACFS|ASM} -y {SI|RAC|RACOne} -io -d <pdb_admin_user> -p <pdb> -g n -
ns <nlcharset> -cs <charset> -l <language> -dt<territory> -v <version> [-co|-no-co] [-h] [-j]
PARAMETERS
-bi --backupconfigid Defines the backup configuration identifier for future

use. Use the dbcli list-backupconfigs command
to get the ID.
-c --cdb (Optional) Indicates whether to create a Container

Database. If omitted, a Container Database is not
-no-c --no-cdb
created.

CHAPTER 8 Database
-cs --characterset (Optional) Defines the character set for the database.
The default is AL32UTF8.
-cl --dbclass Defines the database class. The options are OLTP,
DSS, or IMDB. The default is OLTP. For Enterprise
Editions, all three classes are supported. For
Standard Edition, only OLTP is supported.
-co --dbconsole (Optional) Indicates whether the Database Console is

enabled. If omitted, the console is not enabled.
-no-co --no-dbconsole
This parameter is not available for a version 11.2.0.4
database on a 2-node RAC DB system. For more
information, see To enable the console for a version
11.2.0.4 database on a multi-node DB system .
-d --pdbadmin Defines the name of the Pluggable Database (PDB)

Admin User. The default value is pdbadmin.
-l --dblanguage (Optional) Defines the language for the database. The

default is AMERICAN.
-dt --dbterritory (Optional) Defines the territory for the database. The
default is AMERICA.
-dh --dbhomeid Identifies a new or existing Database Home ID. To

create a database with an existing db home, specify
the db home id. Use the dbcli list dbhomes
command to get the DB Home ID.
If this parameter is omitted, the database is created

with a new oracle home.
-h --help (Optional) Displays help for the command.

CHAPTER 8 Database
-io --instanceonly If this option is specified, it creates only the database

storage structure and starts the database in nomount
mode. No other database files are created. This is
useful for database migration or creating a standby
database.
-m --adminpassword A strong password for SYS, SYSTEM, TDE wallet, and

PDB Admin. The password must be nine to thirty
-hm
characters and contain at least two uppercase, two
lowercase, two numeric, and two special characters.
The special characters must be _, #, or -.
Specify -m (with no password) to be prompted for the

password.
Specify -hm <password> to provide the password in

the command.
-n --dbname Defines the name given to the new database. The

database name must begin with an alphabetic
character and can contain a maximum of eight
alphanumeric characters. Special characters are not
permitted.
-ns --nlscharacterset (Optional) Defines the national character set for the
database. The default is AL16UTF16.

CHAPTER 8 Database
-p --pdbname (Optional) Defines a unique name for the PDB. The

PDB name must begin with an alphabetic character
and can contain a maximum of 30 alphanumeric
characters. The only special character permitted is
the underscore ( _). The default value is pdb1.
PDB names must be unique within a CDB and within

the listener to which they are registered. Make sure
the PDB name is unique on the system. To ensure
uniqueness, do not use the default name value
(pdb1).
-r --dbstorage Defines the database storage, either ACFS or ASM.

The default value is ACFS.
See Usage Notes for more information.
-s --dbshape Identifies the database sizing template to use for the

database. For example, odb1, odb2, or odb3. The
default is odb1. For more information, see Database
Sizing Templates.
-u -- Defines a unique name for the database to ensure

databaseUniqueName uniqueness within an Oracle Data Guard group (a
primary database and its standby databases). The
unique name can contain only alphanumeric and
underscore (_) characters. The unique name cannot
be changed. The unique name defaults to the name
specified in the --dbname parameter.

CHAPTER 8 Database
-v --version Defines the database version as one of the following:
l 18.1.0.0
l 12.2.0.1
l 12.1.0.2 (the default)
l 11.2.0.4
-y --dbtype Defines the database type. Specify SI for a 1-node

instance, RAC for a 2-node cluster, or RACOne for 1-
node instance with a second node in cold standby
mode. The default value is RAC. These values are not
case sensitive.
USAGE NOTES
l You cannot mix Oracle Database Standard Edition and Enterprise Edition databases on
the same DB system. (You can mix supported database versions on the DB system, but
not editions.)
l When --dbhomeid is not provided, the dbcli create-database command will create a
new Oracle Database Home.
l When --dbhomeid is provided, the dbcli create-database command creates the
database using the existing Oracle Home. Use the dbcli list-dbhomes command to
get the dbhomeid.
l Oracle Database 12.1 or later databases are supported on both Oracle Automatic
Storage Management (ASM) and Oracle ASM Cluster file system (ACFS). The default is
Oracle ACFS. Reviewers: Is the default for 12.1 or later ACFS or ASM?
l Oracle Database 11.2 is supported on Oracle ACFS.
l Each database is configured with its own Oracle ACFS file system for the datafiles and
uses the following naming convention: /u02/app/db user/oradata/db name. The
default size of this mount point is 100G.

CHAPTER 8 Database
l Online logs are stored in the /u03/app/db user/redo/ directory.

l The Oracle Fast Recovery Area (FRA) is located in the /u03/app/db user/fast_
recovery_area directory.
E XAMPLES
To create database and be prompted for the password interactively:

[root@dbsys ~]# dbcli create-database -n hrdb -c -m -cl OLTP -s odb2 -p pdb1
Password for SYS,SYSTEM and PDB Admin:

{
"jobId" : "f12485f2-dcbe-4ddf-aee1-de24d37037b6",
"message" : null,
"reports" : [ ],
"description" : "Database service creation with db name: hrdb",
}
To create database non-interactively, providing the password on the command line:

[root@dbsys ~]# dbcli create-database -n crmdb -hm WelCome#12 -cl OLTP -s odb2
{
"jobId" : "30b5e2a6-493b-4461-98b8-78e9a15f8cdd",
"message" : null,
"reports" : [ ],
"description" : "Database service creation with db name: crmdb",
}
DBCLI DELETE -DATABASE
Use the dbcli delete-database command to delete a database.
SYNTAX
dbcli delete-database -i <db_id> [-j] [-h]

CHAPTER 8 Database
PARAMETERS
-i --dbid Identifies the database ID to display. Use the dbcli list-

databases command to get the database ID.
E XAMPLE
The following command deletes the database named 625d9b8a-baea-4994-94e7-

4c4a857a17f9:
[root@dbsys ~]# dbcli delete-database -i 625d9b8a-baea-4994-94e7-4c4a857a17f9
DBCLI DESCRIBE -DATABASE
Use the dbcli describe-database command to display database details.
SYNTAX
dbcli describe-database -i <db_id> [-h] [-j]
PARAMETERS
-i --dbid Identifies the database ID to display. Use the dbcli list-

databases command to get the database ID.
E XAMPLE
The following command displays information for a database named b727bf80-c99e-4846-ac1f-

28a81a725df6:

CHAPTER 8 Database
[root@dbsys ~]# dbcli describe-dbhome -i b727bf80-c99e-4846-ac1f-28a81a725df6
DB Home details
----------------------------------------------------------------
ID: b727bf80-c99e-4846-ac1f-28a81a725df6
Name: OraDB12102_home1
Version: 12.1.0.2
Home Location: /u01/app/orauser/product/12.1.0.2/dbhome_1
Created: Jun 2, 2016 10:19:23 AM
DBCLI LIST -DATABASES
Use the dbcli list-databases command to list all databases on the DB system.
SYNTAX
dbcli list-databases [-h] [-j]
PARAMETERS
E XAMPLE
The following command displays a list of databases:


Storage Status
---------------------------------------- ---------- -------------------- ---------- -------- -------- --
-------- ----------
80ad855a-5145-4f8f-a08f-406c5e4684ff dbst 12.1.0.2 true OLTP odb2
ACFS Configured
6f4e36ae-120b-4436-b0bf-d0c4aef9f7c9 db11tsta 11.2.0.4 false OLTP odb1
ACFS Configured
d8e31790-84e6-479c-beb0-ef97207091a2 db11tstb 11.2.0.4 false OLTP odb1
ACFS Configured

CHAPTER 8 Database
cce096c7-737b-447a-baa1-f4c2a330c030 pdbtst 12.1.0.2 true OLTP odb1

ACFS Configured
The following command displays the JSON output for a database:

[root@dbsys ~]# dbcli list-databases -j
[ {
"id" : "80ad855a-5145-4f8f-a08f-406c5e4684ff",
"name" : "dbtst",
"dbName" : "dbtst",
"databaseUniqueName" : "dbtst_phx1cs",
"dbVersion" : "12.1.0.2",
"dbHomeId" : "2efe7af7-0b70-4e9b-ba8b-71f11c6fe287",
"instanceOnly" : false,
"registerOnly" : false,
"dbId" : "167525515",
"isCdb" : true,
"pdBName" : "pdb1",
"pdbAdminUserName" : "pdbuser",
"enableTDE" : true,
"dbType" : "SI",
"dbTargetNodeNumber" : "0",
"dbClass" : "OLTP",
"dbShape" : "odb2",
"dbStorage" : "ACFS",
"dbCharacterSet" : {
"characterSet" : "US7ASCII",
"nlsCharacterset" : "AL16UTF16",
"dbTerritory" : "AMERICA",
"dbLanguage" : "AMERICAN"
},
"dbConsoleEnable" : false,
"backupConfigId" : null,
"backupDestination" : "NONE",
"cloudStorageContainer" : null,
"state" : {
"status" : "CONFIGURED"
},
"createTime" : "November 09, 2016 17:23:05 PM UTC",
}

CHAPTER 8 Database
DBCLI REGISTER -DATABASE
Use the dbcli register-database command to register a database that has been migrated
to Oracle Cloud Infrastructure. The command registers the database to the dcs-agent so it can
be managed by the dcs-agent stack.
Note

available on 2-node RAC DB systems.
SYNTAX
dbcli register-database -bi <bkup_config_id> -c {OLTP|DSS|IMDB} [-co|-no-co] -s {odb1|odb2|...} -t SI

-o <db_host_name> -sn <service_name> -p [-h] [-j]
PARAMETERS
-bi -- Defines the backup configuration ID. Use the dbcli list-
-c --dbclass Defines the database class. The options are OLTP, DSS, or
IMDB. The default is OLTP. For Enterprise Editions, all three
classes are supported. For Standard Edition, only OLTP is
supported.
-co --dbconsole (Optional) Indicates whether the Database Console is

enabled or not. If omitted, the console is not enabled.
-no-co --no-
dbconsole

CHAPTER 8 Database
-o --hostname (Optional) Defines the database host name. The default is

Local host name.
-p --syspassword Defines a strong password for SYS. Specify -p with no

password. You will be prompted for the password.
If you must provide the password in the command, for

example in a script, use -hp <password> instead of -p.
-s --dbshape Defines the database sizing template to use for the

database. For example, odb1, odb2, and odb3. For more
information, see Database Sizing Templates.
-sn --servicename Defines the database service name used to build the
EZCONNECT string for connecting to the database. The
connect string format is hostname:port/servicename.
-t --dbtype (Optional) Defines the Database Type as single node (SI).

The default value is SI.
E XAMPLE
The following command registers the database with the specified database class, service
name, and database sizing template.
[root@dbsys ~]# dbcli register-database -c OLTP -s odb1 -sn crmdb.example.com -p
Password for SYS:
{
"message" : null,
"reports" : [ ],
"description" : "Database service registration with db service name: crmdb.example.com",
}

CHAPTER 8 Database
DBCLI UPDATE -DATABASE
Use the dbcli update-database command to associate a backup configuration with a

database.
SYNTAX
dbcli update-database -i <db_id> -bi <bkup_config_id> [-h] [-j]
PARAMETERS
-bi -- Defines the backup configuration ID. Use the dbcli list-
-i --dbid Defines the database ID to be updated. Use the dbcli

list-databases command to get the database ID.
E XAMPLE
The following command associates a backup configuration file with a database:

[root@dbsys ~]# dbcli update-database -bi 78a2a5f0-72b1-448f-bd86-cf41b30b64ee -i 71ec8335-113a-46e3-
b81f-235f4d1b6fde
{
"jobId" : "2b104028-a0a4-4855-b32a-b97a37f5f9c5",
"message" : null,
"reports" : [ ],
"description" : "update database id:71ec8335-113a-46e3-b81f-235f4d1b6fde",
"updatedTime" : 1467775842978
}
Dbhome Commands
The following commands are available to manage database homes:

CHAPTER 8 Database
l dbcli create-dbhome
l dbcli describe-dbhome
l dbcli delete-dbhome
l dbcli list-dbhomes
l dbcli update-dbhome
DBCLI CREATE -DBHOME
Use the dbcli create-dbhome command to create an Oracle Database Home.
SYNTAX
dbcli create-dbhome -v <version> [-h] [-j]
PARAMETERS
Parameter Full Description

Name
-v --version Defines the Database Home version. Specify one of the

supported versions:
l 18.1.0.0
l 12.2.0.1
l 12.1.0.2
l 11.2.0.4
E XAMPLE
The following command creates an Oracle Database Home version 12.1.0.2:

[root@dbsys ~]# dbcli create-dbhome -v 12.1.0.2

CHAPTER 8 Database
DBCLI DESCRIBE -DBHOME
Use the dbcli describe-dbhome command to display Oracle Database Home details.
SYNTAX
dbcli describe-dbhome -i <db_home_id> [-h] [-j]
PARAMETERS
-i -- Identifies the database home ID. Use the dbcli list-dbhomes

dbhomeid command to get the ID.
E XAMPLE
The following output is an example of using the display Oracle Database Home details
command.
[root@dbsys ~]# dbcli describe-dbhome -i 52850389-228d-4397-bbe6-102fda65922b
DB Home details
----------------------------------------------------------------
ID: 52850389-228d-4397-bbe6-102fda65922b
Name: OraDB12102_home1
Version: 12.1.0.2
Home Location: /u01/app/oracle/product/12.1.0.2/dbhome_1
Created: June 29, 2016 4:36:31 AM UTC
DBCLI DELETE -DBHOME
Use the dbcli delete-dbhome command to delete a database home from the DB system.
SYNTAX
dbcli delete-dbhome -i <db_home_id> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-i -- Identifies the database home ID to be deleted. Use the dbcli

dbhomeid list-dbhomes command to get the ID.
DBCLI LIST -DBHOMES
Use the dbcli list-dbhomes command to display a list of Oracle Home directories.
SYNTAX
dbcli list-dbhomes [-h] [-j]
PARAMETER
E XAMPLE
The following command displays a list of Oracle Home directories.

------------------------------------ ----------------- ---------- -------------------------------------
-----
b727bf80-c99e-4846-ac1f-28a81a725df6 OraDB12102_home1 12.1.0.2
/u01/app/orauser/product/12.1.0.2/dbhome_1

CHAPTER 8 Database
DBCLI UPDATE -DBHOME
Tip

Use the dbcli update-dbhome command to apply the DBBP bundle patch to a database home.
For more information about applying patches, see Patching a DB System.
SYNTAX
dbcli update-dbhome -i <db_home_id> [-h] [-j]
PARAMETERS
-i -- The ID of the database home. Use the dbcli list-dbhomes

dbhomeid command to get the ID.
E XAMPLE
The following commands update the database home and show the output from the update job:
[root@dbsys ~]# dbcli update-dbhome -i e1877dac-a69a-40a1-b65a-d5e190e671e6
{
"jobId" : "493e703b-46ef-4a3f-909d-bbd123469bea",
"message" : null,
"reports" : [ ],

CHAPTER 8 Database
"description" : "DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6",
}
# dbcli describe-job -i 493e703b-46ef-4a3f-909d-bbd123469bea
Job details
----------------------------------------------------------------
ID: 493e703b-46ef-4a3f-909d-bbd123469bea
Description: DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6
Status: Running
Message:

Status
---------------------------------------- ----------------------------------- ---------------------------
-------- ----------
Create Patching Repository Directories January 19, 2017 10:03:21 AM PST January 19, 2017 10:03:21
AM PST Success
Download latest patch metadata January 19, 2017 10:03:21 AM PST January 19, 2017 10:03:21
AM PST Success
Update System version January 19, 2017 10:03:21 AM PST January 19, 2017 10:03:21
AM PST Success
Update Patching Repository January 19, 2017 10:03:21 AM PST January 19, 2017 10:03:31
AM PST Success
Opatch updation January 19, 2017 10:03:31 AM PST January 19, 2017 10:03:31
AM PST Success
Patch conflict check January 19, 2017 10:03:31 AM PST January 19, 2017 10:03:31
AM PST Running
Dbstorage Commands
The following commands are available to manage database storage:
l dbcli list-dbstorages
l dbcli describe-dbstorage
l dbcli create-dbstorage
l dbcli delete-dbstorage

CHAPTER 8 Database
DBCLI LIST -DBSTORAGES
Use the dbcli list-dbstorages command to list the database storage in the DB system.
SYNTAX
dbcli list-dbstorages [-h] [-j]
PARAMETERS
E XAMPLE
The following command displays details about database storage:


---------------------------------------- ------ -------------------- ----------
afb4a1ce-d54d-4993-a149-0f28c9fb33a4 Acfs db1_2e56b3a9b815 Configured
d81e8013-4551-4d10-880b-d1a796bca1bc Acfs db11xp Configured
DBCLI DESCRIBE -DBSTORAGE
Use the dbcli describe-dbstorage command to show detailed information about a specific
database storage resource.
SYNTAX
dbcli describe-dbstorage -i <db_storage_id> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-i --id Defines the database storage ID. Use the dbcli list-
dbstorages command to get the database storage ID.
E XAMPLE
The following command displays the database storage details for 105a2db2-625a-45ba-8bdd-
ee46da0fd83a:
[root@dbsys ~]# dbcli describe-dbstorage -i 105a2db2-625a-45ba-8bdd-ee46da0fd83a
DBStorage details
----------------------------------------------------------------
ID: 105a2db2-625a-45ba-8bdd-ee46da0fd83a
DB Name: db1
DBUnique Name: db1
DB Resource ID: 439e7bd7-f717-447a-8046-08b5f6493df0
Storage Type:
DATA Location: /u02/app/oracle/oradata/db1
Created: July 3, 2016 4:19:21 AM UTC
UpdatedTime: July 3, 2016 4:41:29 AM UTC
DBCLI CREATE -DBSTORAGE
Use the dbcli create-dbstorage command to create the database storage layout without
creating the complete database. This is useful for database migration and standby database
creation.
SYNTAX
dbcli create-dbstorage -n <db_name> -u <db_unique_name> -r {ACFS|ASM} -s <datasize> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-n --dbname Defines the database name. The database name must

begin with an alphabetic character and can contain a
maximum of eight alphanumeric characters. Special
characters are not permitted.
-r --dbstorage (Optional) Defines the type of database storage as

ACFS or ASM. The default is ACFS.
-s --dataSize (Optional) Defines the data size in GBs. The minimum

size is 10GB. The default size is 100GB.
-u -- (Optional) Defines the unique name for the database.

databaseUniqueName The default is the database name specified in --
dbname.
E XAMPLE
The following command creates database storage with a storage type of ACFS:
[root@dbsys ~]# dbcli create-dbstorage -r ACFS -n testdb -u testdbname
{
"jobId" : "5884a77a-0577-414f-8c36-1e9d8a1e9cee",
"message" : null,
"reports" : [ ],
"description" : "Database storage service creation with db name: testdb",
"updatedTime" : 1467952215103
}

CHAPTER 8 Database
DBCLI DELETE -DBSTORAGE
Use the dbcli delete-dbstorage command to delete database storage that is not being used
by the database. A error occurs if the resource is in use.
SYNTAX
dbcli delete-dbstorage -i <dbstorageID> [-h] [-j]
PARAMETERS
Parameter Parameter Description
-i --id The database storage ID to delete. Use the dbcli list-
dbstorages command to get the database storage ID.
E XAMPLE
The following command deletes the specified database storage:

[root@dbsys ~]# dbcli delete-dbstorage -i f444dd87-86c9-4969-a72c-fb2026e7384b
{
"jobId" : "467c9388-18c6-4e1a-8655-2fd3603856ef",
"status" : "Running",
"message" : null,
"reports" : [ ],
"description" : "Database storage service deletion with id: f444dd87-86c9-4969-a72c-fb2026e7384b",
"updatedTime" : 1467952336856
}

CHAPTER 8 Database
Dbsystem Command
DBCLI DESCRIBE -DBSYSTEM
Use the dbcli describe-dbsystem command to display details about the DB system. On a 2-
node RAC DB system, the command provides information about the local node.
SYNTAX
dbcli describe-dbsystem [-d] [-h] [-j]
PARAMETERS
-d --details Displays additional information about the DB system, including

dcs CLI and agent version information.
E XAMPLE
The following command displays detailed information about the DB system:

[root@dbsys ~]# dbcli describe-dbsystem -d
Appliance Information
----------------------------------------------------------------
ID: a083a81b-d204-4aae-a891-31eccaa92be6
Platform: BmIaaSSi
Data Disk Count: 4
CPU Core Count: 36
Created: September 2, 2016 4:03:47 PM UTC
System Information
----------------------------------------------------------------
Name: wdcxgd5a
Domain Name: asdfasdfasdf.asdfdfasdfasdfasdf.fasdisdfkkfasd.com
Time Zone: UTC
DB Edition: SE

CHAPTER 8 Database
DNS Servers:
NTP Servers:
Disk Group Information

----------------------------------------------------------------
DG Name Redundancy Percentage
------------------------- ------------------------- ------------
Data High 70
Reco High 30
DcsCli Details
----------------------------------------------------------------
Implementation-Version: jenkins-dcs-cli-350
Archiver-Version: Plexus Archiver
Built-By: aime
Created-By: Apache Maven 3.3.9
Build-Jdk: 1.8.0_92
Implementation-Id: b5413850b54fdf330231c0ae4b761fa4c364c5bc
Manifest-Version: 1.0
Main-Class: com.oracle.oda.dcscli.DcsCli
DcsAgent Details
----------------------------------------------------------------
Version: 1.0-SNAPSHOT
BuildNumber: jenkins-dcs-agent-426
GitNumber: 366ec7fd136670781ea5e8345cc2f5272474deef
BuildTime: 2016-09-02_1627 UTC
Job Commands
The following commands are available to manage jobs:
l dbcli describe-job
l dbcli list-jobs
DBCLI DESCRIBE -JOB
Use the dbcli describe-job command to display details about a specific job.

CHAPTER 8 Database
SYNTAX
dbcli describe-job -i <job_id> [-h] [-j]
PARAMETERS
-i --jobid Identifies the job. Use the dbcli list-jobs command to get
the jobid.
E XAMPLE
The following command displays details about the specified job ID:
[root@dbsys ~]# dbcli describe-job -i 74731897-fb6b-4379-9a37-246912025c17
Job details
----------------------------------------------------------------
ID: 74731897-fb6b-4379-9a37-246912025c17
Description: Backup service creation with db name: dbtst
Status: Success
Created: November 18, 2016 8:33:04 PM UTC
Message:

Status
---------------------------------------- ----------------------------------- ---------------------------
-------- ----------
Backup Validations November 18, 2016 8:33:04 PM UTC November 18, 2016 8:33:13
PM UTC Success
validate recovery window November 18, 2016 8:33:13 PM UTC November 18, 2016 8:33:17
PM UTC Success
Db cross check November 18, 2016 8:33:17 PM UTC November 18, 2016 8:33:23
PM UTC Success
Database Backup November 18, 2016 8:33:23 PM UTC November 18, 2016 8:34:22
PM UTC Success

CHAPTER 8 Database
Backup metadata November 18, 2016 8:34:22 PM UTC November 18, 2016 8:34:22
PM UTC Success
DBCLI LIST -JOBS
Use the dbcli list-jobs command to display a list of jobs, including the job IDs, status, and
the job
created date and time stamp.
SYNTAX
dbcli list-jobs [-h] [-j]
PARAMETERS
E XAMPLE
The following command displays a list of jobs:

[root@dbsys ~]# dbcli list-jobs
ID Description
Created Status
---------------------------------------- ---------------------------------------------------------------
------------ ----------------------------------- ----------
0a362dac-0339-41b5-9c9c-4d229e363eaa Database service creation with db name: db11
November 10, 2016 11:37:54 AM UTC Success
9157cc78-b487-4ee9-9f46-0159f10236e4 Database service creation with db name: jhfpdb
November 17, 2016 7:19:59 PM UTC Success
013c408d-37ca-4f58-a053-02d4efdc42d0 create backup config:myBackupConfig
921a54e3-c359-4aea-9efc-6ae7346cb0c2 update database id:80ad855a-5145-4f8f-a08f-406c5e4684ff
74731897-fb6b-4379-9a37-246912025c17 Backup service creation with db name: dbtst

CHAPTER 8 Database
40a227b1-8c47-46b9-a116-48cc1476fc12 Creating a report for database 80ad855a-5145-4f8f-a08f-

406c5e4684ff November 18, 2016 8:41:39 PM UTC Success
Latestpatch Command
DBCLI DESCRIBE -LATESTPATCH
Tip

Note
The dbcli describe-latestpatch command is not

available on 2-node RAC DB systems. Patching 2-node
systems from Object Storage is not supported.
Use the dbcli describe-latestpatch command show the latest patches applicable to the
DB system and available in Oracle Cloud Infrastructure Object Storage.
This command requires a valid Object Storage credentials configuration. Use the dbcli create-
bmccredential command to create the configuration if you haven't already done so. If the
configuration is missing or invalid, the command fails with the error: Failed to connect to
the object store. Please provide valid details.
For more information about updating the CLI, creating the credentials configuration, and
applying patches, see Patching a DB System.
SYNTAX
dbcli describe-latestpatch [-h] [-j]

CHAPTER 8 Database
PARAMETERS
E XAMPLE
The following command displays patches available in the object store:

[root@dbsys ~]# dbcli describe-latestpatch
componentType availableVersion
--------------- --------------------
gi 12.1.0.2.161018
db 11.2.0.4.161018
db 12.1.0.2.161018
oak 12.1.2.10.0
Netsecurity Commands
The following commands are available to manage network encryption on the DB system:
l dbcli describe-netsecurity
l dbcli update-netsecurity
DBCLI DESCRIBE -NETSECURITY
Use the dbcli describe-netsecurity command to display the current network encryption
setting for a database home.
SYNTAX
dbcli describe-netsecurity -H <db_home_id> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-H -- Defines the database home ID. Use the dbcli list-dbhomes

dbHomeId command to get the dbhomeid.
E XAMPLE
The following command displays the encryption setting for specified database home:
[root@dbsys ~]# dbcli describe-netsecurity -H 16c96a9c-f579-4a4c-a645-8d4d22d6889d
NetSecurity Rules
----------------------------------------------------------------
DatabaseHomeID: 16c96a9c-f579-4a4c-a645-8d4d22d6889d
Role: Server
EncryptionAlgorithms: AES256 AES192 AES128
IntegrityAlgorithms: SHA1
ConnectionType: Required
Role: Client
EncryptionAlgorithms: AES256 AES192 AES128
IntegrityAlgorithms: SHA1
ConnectionType: Required
DBCLI UPDATE -NETSECURITY
Use the dbcli update-netsecurity command to update the Oracle Net security
configuration on the DB system.
SYNTAX
dbcli update-netsecurity {-c|-s} -t {REJECTED|ACCEPTED|REQUESTED|REQUIRED} -H db_home_id> -e

{AES256|AES192|AES128} -i {SHA1|SHA512|SHA384|SHA256} [-h] [-j]

CHAPTER 8 Database
PARAMETERS
Parame Full Name Description

ter
-c --client Indicates that the specified data encryption or data integrity

configuration is for the client. (--client and --server are
mutually exclusive.)
-e -- Defines the algorithm to be used for encryption. Specify

encryptionAlgorit either AES256, AES192, or AES128.
hms
-H --dbHomeId Defines the database home ID. Use the dbcli list-
dbhomes command to get the dbHomeId.
-i -- Defines the algorithm to be used for integrity. Specify either

integrityAlgorith SHA1, SHA512, SHA384, or SHA256. For Oracle Database
ms 11g, the only accepted value is SHA1.

CHAPTER 8 Database
Parame Full Name Description

ter
-s --server Indicates that the specified data encryption or data integrity

configuration is for the server. (--client and --server are
mutually exclusive.)
-t -- Specifies how Oracle Net Services data encryption or data

connectionType integrity is negotiated with clients. The following values are
listed in the order of increasing security:
REJECTED - Do not enable data encryption or data integrity,

even if required by the client.
ACCEPTED - Enable data encryption or data integrity if

required or requested by the client.
REQUESTED - Enable data encryption or data integrity if the

client permits it.
REQUIRED - Enable data encryption or data integrity or

preclude the connection.
For detailed information about network data encryption and

integrity, see
https://docs.oracle.com/database/121/DBSEG/asoconfg.ht
m#DBSEG1047.
E XAMPLE
The following command updates the connection type to ACCEPTED:

[root@dbsys ~]# dbcli update-netsecurity -H a2ffbb07-c9c0-4467-a458-bce4d3b76cd5 -t ACCEPTED
Objectstoreswift Commands
You can back up a database to an existing bucket in the Oracle Cloud Infrastructure Object
Storage service by using the dbcli create-backup command, but first you'll need to:

CHAPTER 8 Database
1. Create an object store on the DB system, which contains the endpoint and credentials to
access Object Storage, by using the dbcli create-objectstoreswift command.
2. Create a backup configuration that refers to the object store ID and the bucket name by
using the dbcli create-backupconfig command.
3. Associate the backup configuration to the database by using the dbcli update-database
command.
The following commands are available to manage object stores.
l dbcli create-objectstoreswift
l dbcli describe-objectstoreswift
l dbcli list-objectstoreswifts
Note
The objectstoreswift commands are not available on

DBCLI CREATE -OBJECTSTORESWIFT
Use the dbcli create-objectstoreswift command to create an object store.
SYNTAX
dbcli create-objectstoreswift -n <object_store_name> -t <tenant_name> -u <user_name> -e

https://swiftobjectstorage.<region>.oraclecloud.com/v1 -p [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-e --endpoint The following endpoint URL.
https://
swiftobjectstorage.<region>.oraclecloud.com/v1
-n --name The name for the object store to be created.
-p -- The Swift password that you generated by using the Console

swiftpassword or IAM API. For information about generating a Swift
password, see Managing User Credentials.
This is not the password for the Oracle Cloud Infrastructure

user.
Specify -p (with no password) to be prompted.
Specify -hp "<password> " in quotes to provide the

password in the command.

CHAPTER 8 Database
-t --tenantname The case-sensitive tenant name that you specify when

signing in to the Console.
-u --username The user name for the Oracle Cloud Infrastructure user
account, for example:
-u djones@mycompany.com
This is the user name you use to sign in to the Console.
The user name must have tenancy-level access to the Object

Storage. An easy way to do this is to add the user name to
the Administrators group. However, that allows access to all
of the cloud services. Instead, an administrator can create a
policy that allows tenancy-level access to just Object
For more information about adding a user to a group, see

Managing Groups. For more information about policies, see
Getting Started with Policies.
E XAMPLE
The following command creates an object store and prompts for the Swift password:
[root@dbsys ~]# dbcli create-objectstoreswift -n r2swift -t CompanyABC -u djones@mycompany.com -e
https://swiftobjectstorage.<region>.oraclecloud.com/v1 -p
Password for Swift:
{
"jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7",
"message" : "Create object store swift",
"reports" : [ ],
"resourceList" : [ {

CHAPTER 8 Database
"resourceId" : "8a0fe039-f5d4-426a-8707-256c612b3a30",
"resourceType" : "ObjectStoreSwift",
"jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7",
} ],
"description" : "create object store:biyanr2swift",
}
DBCLI DESCRIBE -OBJECTSTORESWIFT
Use the dbcli describe-objectstoreswift command to display details about an object

store.
SYNTAX
dbcli describe-objectstoreswift -i <object_store_swift_id> [-h] [-j]
PARAMETERS
-i -- The object store ID. Use the dbcli list-

objectstoreswiftid objectstoreswifts command to get the ID.
E XAMPLE
The following command displays details about an object store:

[root@dbsys ~]# dbcli describe-objectstoreswift -i 910e9e2d-25b4-49b4-b88e-ff0332f7df87
Object Store details
----------------------------------------------------------------
ID: 910e9e2d-25b4-49b4-b88e-ff0332f7df87
Name: objstrswift15
UserName: djones@mycompany.com
TenantName: CompanyABC
endpoint URL: https://swiftobjectstorage.<region>.oraclecloud.com/v1

CHAPTER 8 Database
CreatedTime: November 16, 2016 11:25:34 PM UTC

UpdatedTime: November 16, 2016 11:25:34 PM UTC
DBCLI LIST -OBJECTSTORESWIFTS
Use the dbcli list-objectstoreswifts command to list the object stores on a DB system.
SYNTAX
dbcli list-objectstoreswifts [-h] [-j]
PARAMETERS
E XAMPLE
The following command lists the object stores on the DB system:

[root@dbsys ~]# dbcli list-objectstoreswifts
ID Name UserName TenantName Url

createTime
---------------------------------------- -------------------- -------------------- -------------- -----
- ---------------------------------------------------- -----------------------------------
2915bc6a-6866-436a-a38c-32302c7c4d8b swiftobjstr1 djones@mycompany.com CompanyABC
https://swiftobjectstorage.<region>.oraclecloud.com/v1 November 10, 2016 8:42:18 PM UTC
910e9e2d-25b4-49b4-b88e-ff0332f7df87 objstrswift15 djones@mycompany.com CompanyABC
https://swiftobjectstorage.<region>.oraclecloud.com/v1 November 16, 2016 11:25:34 PM UTC
Recovery Commands
The following commands are available to initiate a database recovery and list recovery jobs:
l dbcli create-recovery
l dbcli list-recovery

CHAPTER 8 Database
DBCLI CREATE -RECOVERY
Use the dbcli create-recovery command to initiate database recovery.
SYNTAX
dbcli create-recovery -i <db_id> -r <timestamp> -t {Latest|PITR|SCN} -s <scn> [-h] [-j]
PARAMETERS
-i --dbid Defines the ID of the database to recover. Use the

dbcli list-databases command to get the
database's ID.
-r -- Defines the time for the end point of the recovery. The
recoveryTimeStamp format is MM/DD/YYYY HH24:MI:SS, for example,
08/09/2016 05:12:15.
-s -scn Defines the system change number (SCN) for the end
point of the recovery, when the specified recovery
type is SCN.
-t --recoverytype Defines the type of recovery to be performed:
PITR - Indicates that a database point-in-time

(incomplete) recovery should be performed. The
recovery end point is specified by the -s or -r option.
Latest - Indicates that a complete database recovery

should be performed.
SCN - Indicates that the recovery is based on the

system change number.

CHAPTER 8 Database
E XAMPLE
The following command initiates a complete recovery of the specified database:

[root@dbsys ~]# dbcli create-recovery -i 5a3e980b-e0fe-4909-9628-fcefe43b3326 -t Latest
{
"jobId" : "c9f81228-2ce9-43b4-88f6-b260d398cf06",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 18:20:47 PM UTC",
"description" : "Create recovery for database id :5a3e980b-e0fe-4909-9628-fcefe43b3326",
"updatedTime" : "August 08, 2016 18:20:47 PM UTC"
}
The following command initiates a point-in-time recovery of the specified database:

dbcli create-recovery -i d4733796-dbea-4155-8606-24a85d64bd74 -t PITR -r 08/09/2016 5:12:15
DBCLI LIST -RECOVERY
Use the dbcli list-recovery command to see information about recovery jobs.
SYNTAX
dbcli list-recovery [-h] [-j]
PARAMETERS
E XAMPLE
The following command displays information about the recovery jobs:

[root@dbsys ~]# dbcli list-recovery

CHAPTER 8 Database
Schedule Commands
You can run back up jobs automatically by using backup schedules. A default backup schedule
is automatically created for every database that is associated with a backup configuration.
The backup configuration controls the backup destination and recovery window. The schedule
uses a cron expression to control when and how often the back up job runs. The default cron
expression is 0 2 4 1/1 * ? *, so the back up job is scheduled to run daily at 4:02 AM. You
can update the cron expression as needed using the dbcli update-schedule command. You
can use a cron utility such as the CronMaker utility to help build expressions. For more
information, see http://www.cronmaker.com.
Note
Each database also has a metastore maintenance

backup schedule. This schedule is used internally by the
DB system and must not be updated.
The following commands are available to manage backup schedules:
l dbcli list-schedules
l dbcli describe-schedule
l dbcli update-schedule
l dbcli list-scheduledExecutions
DBCLI LIST -SCHEDULES
Use the dbcli list-schedules command to list backup schedules.
SYNTAX
dbcli list-schedules [-h] [-j]

CHAPTER 8 Database
PARAMETERS
E XAMPLE
The following command displays backup schedules:

[root@dbsys ~]# dbcli list-schedules
ID Name Description
CronExpression
---------------------------------------- ------------------------- -------------------------------------

------------- ------------------------------
fe46697b-128e-43b4-9f7a-8e4a5f16e88c metastore maintenance internal metastore maintenance
0 0 0 1/1 * ? *
481856f9-2cdd-45f8-b0b0-11cc8c48970a database backup backup databases

0 9 13 1/1 * ? *
DBCLI DESCRIBE -SCHEDULE
Use the dbcli describe-schedule command to list information about a schedule.
SYNTAX
dbcli describe-schedule -i <schedule_id> [-h] [-j]
PARAMETERS

CHAPTER 8 Database
-i -- The schedule ID. Use the dbcli list-schedules command to

scheduleid get the ID.
E XAMPLE
The following command describes a backup schedule:

[root@dbsys ~]# dbcli describe-schedule -i 481856f9-2cdd-45f8-b0b0-11cc8c48970a
Job Schedule details

----------------------------------------------------------------
ID: 481856f9-2cdd-45f8-b0b0-11cc8c48970a
JobName: database backup
JobGroup: backups
CronExpression: 0 9 13 1/1 * ? *
JobClass: com.oracle.dcs.agent.schedule.AutoBackupJob
UpdatedTime: September 1, 2016 9:22:50 PM UTC
Description: backup databases
Disable: false
DBCLI UPDATE -SCHEDULE
Use the dbcli update-schedule command to enable or disable a schedule, or update the
cron expression that controls when and how frequently the job is scheduled. You can use the
CronMaker utility to help build cron expressions. For more information, see
http://www.cronmaker.com.
Note
Do not update the metastore maintenance schedule.

This schedule is used internally by the DB system.
SYNTAX
dbcli update-schedule -i <schedule_id> -x '<cron_expression>' -t <description> [-d|-e] [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-d --disable Indicates whether the schedule is disabled or enabled.
-e --enable
-i --scheduleid The schedule ID. Use the dbcli list-schedules command

to get the ID.
-t --description A description of the schedule.
-x -- The cron expression, in single quotes, used by the schedule.

cronExpression
E XAMPLE
The following command updates the backup schedule to run daily at 12:00 by updating the
cron expression to '0 0 12 1/1 * ? *'.
[root@dbsys ~]# dbcli update-schedule -i 481856f9-2cdd-45f8-b0b0-11cc8c48970a -x '0 0 12 1/1 * ? *'
Update job schedule success
You can use the dbcli describe-schedule command to get more information about the
update.
DBCLI LIST -SCHEDULEDEXECUTIONS
Use the dbcli list-scheduledExecutions command to list the jobs that have been
executed by existing schedules.
SYNTAX
dbcli list-scheduledExecutions -i <schedule_id> -e <execution_id> [-h] [-j]

CHAPTER 8 Database
PARAMETERS
-e -- (Optional) An execution ID.

executionid
-i -- (Optional) The schedule ID. Use the dbcli list-schedules

scheduleid command to get the ID.
E XAMPLE
The following command lists all the jobs executed for all schedules:
[root@dbsys ~]# dbcli list-scheduledExecutions
ID ScheduledId JobId
Status Executed Time
-------------------------------------- -------------------------------------- --------------------------
------------ --------- -------------------------------
23691445-9120-4a34-9bcd-dcbd382dc455 22fbd334-ebbd-40f4-af79-9eb2360cfb77 c7f32a6c-f835-45f8-a5ef-
ff04473d3a73 Executed September 5, 2016 8:52:00 PM UTC
54071c4e-98db-41c8-92b6-b5f92ca11631 a7623340-ece7-4618-a7d9-8efb353378b4 b663fb73-e531-43bf-9939-
0b404b62e8ce Executed September 6, 2016 12:00:00 AM UTC
Note the JobID in the command output. You can use the dbcli describe-job with the JobID
to get more information about the job.

CHAPTER 8 Database
Server Command
DBCLI UPDATE -SERVER
Tip

Use the dbcli update-server command to apply patches to the server components in the DB
system. For more information about applying patches, see Patching a DB System.
Note
The dbcli update-server command is not available on

SYNTAX
dbcli update-server [-h] [-j]
PARAMETERS
E XAMPLE
The following commands update the server and show the output from the update job:

CHAPTER 8 Database
[root@dbsys ~]# dbcli update-server

{
"jobId" : "9a02d111-e902-4e94-bc6b-9b820ddf6ed8",
"reports" : [ ],
"description" : "Server Patching",
}
# dbcli describe-job -i 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Job details
----------------------------------------------------------------
ID: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Description: Server Patching
Status: Running
Message:

Status
---------------------------------------- ----------------------------------- ---------------------------
-------- ----------
Create Patching Repository Directories January 19, 2017 9:37:11 AM PST January 19, 2017 9:37:11 AM
PST Success
Download latest patch metadata January 19, 2017 9:37:11 AM PST January 19, 2017 9:37:11 AM
PST Success
Update System version January 19, 2017 9:37:11 AM PST January 19, 2017 9:37:11 AM
PST Success
Update Patching Repository January 19, 2017 9:37:11 AM PST January 19, 2017 9:38:35 AM
PST Success
oda-hw-mgmt upgrade January 19, 2017 9:38:35 AM PST January 19, 2017 9:38:58 AM
PST Success
Opatch updation January 19, 2017 9:38:58 AM PST January 19, 2017 9:38:58 AM
PST Success
Patch conflict check January 19, 2017 9:38:58 AM PST January 19, 2017 9:42:06 AM
PST Success
apply clusterware patch January 19, 2017 9:42:06 AM PST January 19, 2017 10:02:32
AM PST Success
Updating GiHome version January 19, 2017 10:02:32 AM PST January 19, 2017 10:02:38

CHAPTER 8 Database
AM PST Success
TDE Command
DBCLI UPDATE -TDEKEY
Use the dbcli update-tdekey command to update the TDE encryption key inside the TDE
wallet. You can update the encryption key for Pluggable Databases (if -pdbNames are
specified), and/or the Container Database (if -rootDatabase is specified).
SYNTAX
dbcli update-tdekey -i <db_id> -p -n <pdbname1,pdbname2> [-r|-no-r] -t <tag_name> [-h] [-j]
PARAMETERS
-i --dbid Defines the database ID for which to update the key.
-p --password Defines the TDE Admin wallet password. Specify -p with no

password. You will be prompted for the password.
If you must provide the password in the command, for

example in a script, use -hp <password> instead of -p.
-n --pdbNames Defines the PDB names to be rotated.
-r -- Indicates whether to rotate the key for the root database if it

rootDatabase is a container database.
-no-r
--no-
rootDatabase
-t -tagName Defines the TagName used to backup the wallet. The default
is OdaRotateKey.

CHAPTER 8 Database
E XAMPLE
The following command updates the key for pdb1 and pdb2 only:
[root@dbsys ~]# dbcli update-tdekey -dbid ee3eaab6-a45b-4e61-a218-c4ba665503d9 -p -n pdb1,pdb2
TDE Admin wallet password:

{
"jobId" : "08e5edb1-42e1-4d16-a47f-783c0afa4778",
"message" : null,
"reports" : [ ],
"description" : "TDE update",
"updatedTime" : 1467876407035
}
The following command updates pdb1, pdb2, and the container database:
[root@dbsys ~]# dbcli update-tdekey -dbid ee3eaab6-a45b-4e61-a218-c4ba665503d9 -p -n pdb1,pdb2 -r
TDE Admin wallet password:

{
"jobId" : "c72385f0-cd81-42df-a8e8-3a1e7cab1278",
"message" : null,
"reports" : [ ],
"description" : "TDE update",
"updatedTime" : 1467876433783
}
Admin Commands
The following commands are to perform administrative actions on the DB system:
l dbadmcli manage diagcollect

l dbadmcli power
l dbadmcli power disk status
l dbadmcli show controller

CHAPTER 8 Database
l dbadmcli show disk

l dbadmcli show diskgroup
l dbadmcli show env_hw (environment type and hardware version)
l dbadmcli show fs (file system details)
l dbadmcli show storage
l dbadmcli stordiag
DBADMCLI MANAGE DIAGCOLLECT
Use the dbadmcli manage diagcollect command to collect diagnostic information about a
DB system for troubleshooting purposes, and for working with Oracle Support Services.
SYNTAX
dbadmcli manage diagcollect --storage
PARAMETERS
-h (Optional) Displays help for using the command.
--storage Collects all of the logs for any storage issues.
E XAMPLE
[root@dbsys ~]# dbadmcli manage diagcollect --storage

Collecting storage log data. It will take a while, please wait...
Collecting oak data. It will take a while, please wait...
tar: Removing leading `/' from member names
tar: /opt/oracle/oak/onecmd/tmp/OakCli-Command-Output.log: file changed as we read it
Logs are collected to : /opt/oracle/oak/log/dbsys/oakdiag/oakStorage-dbsys-20161118_2101.tar.gz
DBADMCLI POWER
Use the dbadmcli power command to power a disk on or off.

CHAPTER 8 Database
Note
The dbadmcli power command is not available on 2-

node RAC DB systems.
SYNTAX
dbadmcli power {-on|-off} <name> [-h]
PARAMETERS
name Defines the disk resource name. The resource name format is pd_[0..3]. Use
the dbadmcli show disk command to get the disk resource name.
-off Powers off the disk.
-on Powers on the disk.
DBADMCLI POWER DISK STATUS
Use the dbadmcli power disk status command to display the current power status of a
disk.
SYNTAX
dbadmcli power disk status <name>

CHAPTER 8 Database
PARAMETERS
name Identifies a specific disk resource name. The resource name format is pd_
[0..3]. For example, pd_01.
E XAMPLE
[root@dbsys ~]# dbadmcli power disk status pd_00
The disk is powered ON
DBADMCLI SHOW CONTROLLER
Use the dbadmcli show controller command to display details of the controller.
SYNTAX
dbadmcli show controller <controller_id> [-h]
PARAMETER
controller_ The ID number of the controller. Use the dbadmcli show storage command
id to get the ID.
DBADMCLI SHOW DISK
Use the dbadmcli show disk command to display the status of a single disk or all disks on
the DB system.
SYNTAX
dbadmcli show disk <name> [-shared] [-all] [-getlog]

CHAPTER 8 Database
PARAMETERS
-all (Optional) Displays detailed information for the named disk.
-getlog (Optional) Displays all the SMART log entries for an NVMe disk.
name (Optional) Identifies a specific disk resource name. The resource name
format is pd_[0..3]. If omitted, the command displays information about all
disks on the system.
-shared (Optional) Displays all the shared disks.
E XAMPLES
To display the status of all the disks on the system:

[root@dbsys ~]# dbadmcli show disk
NAME PATH TYPE STATE STATE_DETAILS
pd_00 /dev/nvme2n1 NVD ONLINE Good

To display the status of a disk named pd_00:

[root@dbsys ~]# dbadmcli show disk pd_00
The Resource is : pd_00
ActionTimeout : 1500
ActivePath : /dev/nvme2n1
AsmDiskList : |data_00||reco_00|
AutoDiscovery : 1
AutoDiscoveryHi : |data:70:NVD||reco:30:NVD|
CheckInterval : 300
ColNum : 0
CriticalWarning : 0
DependListOpr : add
Dependency : |0|

CHAPTER 8 Database
DiskId : 360025380144d5332
DiskType : NVD
Enabled : 1
ExpNum : 29
HbaPortNum : 10
IState : 0
Initialized : 0
IsConfigDepende : false
ModelNum : MS1PC2DD3ORA3.2T
MonitorFlag : 1
MultiPathList : |/dev/nvme2n1|
Name : pd_00
NewPartAddr : 0
OSUserType : |userType:Multiuser|
PlatformName : X5_2_LITE_IAAS
PrevState : Invalid
PrevUsrDevName :
SectorSize : 512
SerialNum : S2LHNAAH502855
Size : 3200631791616
SlotNum : 0
SmartDiskWarnin : 0
SmartTemperatur : 32
State : Online
StateChangeTs : 1467176081
StateDetails : Good
TotalSectors : 6251233968
TypeName : 0
UsrDevName : NVD_S00_S2LHNAAH502855
VendorName : Samsung
gid : 0
mode : 660
uid : 0
To display the SMART logs for an NVMe disk:

[root@dbsys ~]# dbadmcli show disk pd_00 -getlog
SMART / Health Information :
----------------------------
Critical Warning : Available Spare below Threshold : FALSE
Critical Warning : Temperature above Threshold : FALSE
Critical Warning : Reliability Degraded : FALSE
Critical Warning : Read-Only Mode : FALSE

CHAPTER 8 Database
Critical Warning : Volatile Memory Backup Device Failure : FALSE

Temperature : 32 degree
Celsius
Available Spare : 100%
Available Spare Threshold : 10%
Device Life Used : 0%
Data Units Read (in 512k byte data unit) : 89493
Data Units Written (in 512k byte data unit) : 270387
Number of Host Read Commands : 4588381
Number of Host Write Commands : 6237344
Controller Busy Time : 3 minutes
Number of Power Cycles : 227
Number of Power On Hours : 1115
Number of Unsafe Shutdowns : 218
Number of Media Errors : 0
Number of Error Info Log Entries : 0
DBADMCLI SHOW DISKGROUP
Use the dbadmcli show diskgroup command to list configured diskgroups or display a
specific diskgroup configuration.
SYNTAX
To list configured diskgroups:

dbadmcli show diskgroup [-h]
To display DATA configurations:

dbadmcli show diskgroup [DATA] [-h]
To display RECO configurations:

dbadmcli show diskgroup [RECO] [-h]

CHAPTER 8 Database
PARAMETERS
DATA (Optional) Displays the DATA diskgroup configurations.
RECO (Optional) Displays the RECO diskgroup configurations.
E XAMPLES
To list all diskgroups:

[root@dbsys ~]# dbadmcli show diskgroup
DiskGroups
----------
DATA
RECO
To display DATA configurations:

[root@dbsys ~]# dbadmcli show diskgroup DATA
ASM_DISK PATH DISK STATE STATE_DETAILS

data_00 /dev/NVD_S00_S2LHNAAH101026p1 pd_00 ONLINE Good
data_01 /dev/NVD_S01_S2LHNAAH101008p1 pd_01 ONLINE Good
DBADMCLI SHOW ENV_ HW
Use the dbadmcli show env_hw command to display the environment type and hardware
version of the current DB system.
SYNTAX
dbadmcli show env_hw [-h]
PARAMETER

CHAPTER 8 Database
DBADMCLI SHOW FS
Use the dbadmcli show fs command to display file system details.
SYNTAX
dbadmcli show fs [-h]
PARAMETER
DBADMCLI SHOW STORAGE
Use the dbadmcli show storage command to show the storage controllers, expanders, and
disks.
SYNTAX
dbadmcli show storage [-h]
To show storage errors:

dbadmcli show storage -errors [-h]
PARAMETERS
-errors (Optional) Shows storage errors.
E XAMPLE
To display storage devices:

[root@dbsys ~]# dbadmcli show storage
==== BEGIN STORAGE DUMP ========
Host Description: Oracle Corporation:ORACLE SERVER X5-2
Total number of controllers: 5

CHAPTER 8 Database
Id = 4
Pci Slot = -1
Serial Num =
Vendor =
Model =
FwVers =
strId = iscsi_tcp:00:00.0
Pci Address = 00:00.0
Id = 0
Pci Slot = 13
Serial Num = S2LHNAAH504431
Vendor = Samsung
Model = MS1PC2DD3ORA3.2T
FwVers = KPYA8R3Q
strId = nvme:25:00.00
Id = 1
Pci Slot = 12
Vendor = Samsung
FwVers = KPYA8R3Q
Id = 2
Pci Slot = 10
Vendor = Samsung
FwVers = KPYA8R3Q
Id = 3
Pci Slot = 11
Vendor = Samsung
FwVers = KPYA8R3Q

CHAPTER 8 Database
strId = nvme:2b:00.00
Pci Address = 2b:00.0
Total number of expanders: 0

Total number of PDs: 4
/dev/nvme2n1 Samsung NVD 3200gb slot: 0 pci : 29
==== END STORAGE DUMP =========
DBADMCLI STORDIAG
Use the dbadmcli stordiag command to collect detailed information for each disk or NVM
Express (NVMe).
SYNTAX
dbadmcli stordiag <name> [-h]
PARAMETERS
name Defines the disk resource name. The resource name format is pd_[0..3].
E XAMPLE
To display detailed information for NVMe pd_00:

[root@dbsys ~]# dbadmcli stordiag pd_0
Database Sizing Templates

When you create a database using the dbcli create-database command, you can specify a
database sizing template with the --dbshape parameter. The sizing templates are configured
for different types of database workloads. Choose the template that best matches the most
common workload your database performs:

CHAPTER 8 Database
l Use the OLTP templates if your database workload is primarily online transaction
processing (OLTP).
l Use the DSS templates if your database workload is primarily decision support (DSS) or
data warehousing.
l Use the in-memory (IMDB) templates if your database workload can fit in memory, and
can benefit from in-memory performance capabilities.
The following tables describe the templates for each type of workload.
OLTP DATABASE S IZING TEMPLATES
Template CPU SGA PGA Flash Processes Redo Log File Log
Cores (GB) (GB) (GB) Size (GB) Buffer
(MB)
odb1s 1 2 1 6 200 1 16
odb1 1 4 2 12 200 1 16
odb2 2 8 4 24 400 1 16
odb4 4 16 8 48 800 1 32
odb6 6 24 12 72 1200 2 64
odb8 8 32 16 n/a 1600 2 64
odb10 10 40 20 n/a 2000 2 64
odb12 12 48 24 144 2400 4 64
odb16 16 64 32 192 3200 4 64
odb20 20 80 40 n/a 4000 4 64
odb24 24 96 48 192 4800 4 64

CHAPTER 8 Database
Template CPU SGA PGA Flash Processes Redo Log File Log
Cores (GB) (GB) (GB) Size (GB) Buffer
(MB)
odb32 32 128 64 256 6400 4 64
odb36 36 128 64 256 7200 4 64
DSS DATABASE S IZING TEMPLATES
Template CPU SGA PGA Processes Redo Log File Log Buffer
Cores (GB) (GB) Size (GB) (MB)
odb1s 1 1 2 200 1 16
odb1 1 2 4 200 1 16
odb2 2 4 8 400 1 16
odb4 4 8 16 800 1 32
odb6 6 12 24 1200 2 64
odb8 8 16 32 1600 2 64
odb10 10 20 40 2000 2 64
odb12 12 24 48 2400 4 64
odb16 16 32 64 3200 4 64
odb20 20 40 80 4000 4 64
odb24 24 48 96 4800 4 64
odb32 32 64 128 6400 4 64
odb36 36 64 128 7200 4 64

CHAPTER 8 Database
I N-MEMORY DATABASE S IZING TEMPLATES
Template CPU SGA PGA In- Processes Redo Log Log

Cores (GB) (GB) Memory Lile Size Buffer
(GB) (GB) (MB)
odb1s 1 2 1 1 200 1 16
odb1 1 4 2 2 200 1 16
odb2 2 8 4 4 400 1 16
odb4 4 16 8 8 800 1 32
odb6 6 24 12 12 1200 2 64
odb8 8 32 16 16 1600 2 64
odb10 10 40 20 20 2000 2 64
odb12 12 48 24 24 2400 4 64
odb16 16 64 32 32 3200 4 64
odb20 20 80 40 40 4000 4 64
odb24 24 96 48 48 4800 4 64
odb32 32 128 64 64 6400 4 64
odb36 36 128 64 64 7200 4 64
Migrating Databases to the Cloud

You can migrate your on-premises Oracle Database to an Oracle Cloud Infrastructure
Database service database using a number of different methods that use several different
tools. The method that applies to a given migration scenario depends on several factors,

CHAPTER 8 Database
including the version, character set, and platform endian format of the source and target
databases.
Choosing a Migration Method

Not all migration methods apply to all migration scenarios. Many of the migration methods
apply only if specific characteristics of the source and destination databases match or are
compatible. Moreover, additional factors can affect which method you choose for your
migration from among the methods that are technically applicable to your migration scenario.
Some of the characteristics and factors to consider when choosing a migration method are:
l On-premises database version

l Database service database version
l On-premises host operating system and version
l On-premises database character set
l Quantity of data, including indexes
l Data types used in the on-premises database
l Storage for data staging
l Acceptable length of system outage
l Network bandwidth
To determine which migration methods are applicable to your migration scenario, gather the
following information.
1. Database version of your on-premises database:

l Oracle Database 12c Release 2 version 12.2.0.1
l Oracle Database 12c Release 1 version 12.1.0.2 or higher
l Oracle Database 12c Release 1 version lower than 12.1.0.2
l Oracle Database 11g Release 2 version 11.2.0.3 or higher
l Oracle Database 11g Release 2 version lower than 11.2.0.3

CHAPTER 8 Database
2. For on-premises Oracle Database 12c Release 2 and Oracle Database 12c Release 1
databases, the architecture of the database:
l Multitenant container database (CDB)
l Non-CDB
3. Endian format (byte ordering) of your on-premises database’s host platform
Some platforms are little endian and others are big endian. Query V$TRANSPORTABLE_
PLATFORM to identify the endian format, and to determine whether cross-platform
tablespace transport is supported.
The Oracle Cloud Infrastructure Database uses the Linux platform, which is little endian.
4. Database character set of your on-premises database and the Oracle Cloud
Infrastructure Database database.
Some migration methods require that the source and target databases use compatible
database character sets.
5. Database version of the Oracle Cloud Infrastructure Database database you are
migrating to:
l Oracle Database 12c Release 2
l Oracle Database 12c Release 1
l Oracle Database 11g Release 2
Oracle Database 12c Release 2 and Oracle Database 12c Release 1 databases created
on the Database service use CDB architecture. Databases created using the Enterprise
Edition software edition are single-tenant, and databases created using the High
Performance or Extreme Performance software editions are multitenant.
After gathering this information, use the “source” and “destination” database versions as your
guide to see which migration methods apply to your migration scenario:
l Migrating from Oracle Database 11g to Oracle Database 11g in the Cloud
l Migrating from Oracle Database 11g to Oracle Database 12c in the Cloud
l Migrating from Oracle Database 12c CDB to Oracle Database 12c in the Cloud
l Migrating from Oracle Database 12c Non-CDB to Oracle Database 12c in the Cloud

CHAPTER 8 Database
Migration Connectivity Options

You have several connectivity options when migrating your on-premises databases to the
Oracle Cloud Infrastructure. The options are listed below in order of preference.
1. FastConnect: Provides a secure connection between your existing network and your
virtual cloud network (VCN) over a private physical network instead of the internet. For
more information, see FastConnect Overview.
2. IPSec VPN: Provides a secure connection between a dynamic routing gateway (DRG)
and customer-premise equipment (CPE), consisting of multiple IPSec tunnels. The IPSec
connection is one of the components forming a site-to-site VPN between a VCN and your
on-premises network. For more information, see IPSec VPNs.
3. Internet gateway: Provides a path for network traffic between your VCN and the
internet. For more information, see Connectivity to the Internet.
Migration Methods
Many methods exist to migrate Oracle databases to the Oracle Cloud Infrastructure Database
service. Which of these methods apply to a given migration scenario depends on several
factors, including the version, character set, and platform endian format of the source and
target databases.
l Data Pump Conventional Export/Import

l Data Pump Full Transportable
l Data Pump Transportable Tablespace
l Remote Cloning a PDB
l Remote Cloning Non-CDB
l RMAN Cross-Platform Transportable PDB
l RMAN Cross-Platform Transportable Tablespace Backup Sets
l RMAN Transportable Tablespace with Data Pump
l RMAN DUPLICATE from an Active Database

CHAPTER 8 Database
l RMAN CONVERT Transportable Tablespace with Data Pump

l SQL Developer and INSERT Statements to Migrate Selected Objects
l SQL Developer and SQL*Loader to Migrate Selected Objects
l Unplugging/Plugging a PDB
l Unplugging/Plugging Non-CDB
Migrating from Oracle Database 11g to Oracle Database 11g in the

Cloud
You can migrate Oracle Database 11g databases from on-premises to Oracle Database 11g
databases in the Database service using several different methods.
The applicability of some of the migration methods depends on the on-premises database’s
character set and platform endian format.
If you have not already done so, determine the database character set of your on-premises
database, and determine the endian format of the platform your on-premises database
resides on. Use this information to help you choose an appropriate method.

This method can be used regardless of the endian format and database character set of
the on-premises database.
For the steps this method entails, see Data Pump Conventional Export/Import.
This method can be used only if the on-premises platform is little endian, and the
database character sets of your on-premises database and the Oracle Cloud
Infrastructure Database database are compatible.
For the steps this method entails, see Data Pump Transportable Tablespace.
Infrastructure Database database are compatible.

CHAPTER 8 Database
For the steps this method entails, see RMAN Transportable Tablespace with Data Pump.
This method can be used only if the database character sets of your on-premises
database and the Oracle Cloud Infrastructure Database database are compatible.
This method is similar to the Data Pump Transportable Tablespace method, with the
addition of the RMAN CONVERT command to enable transport between platforms with
different endianness. Query V$TRANSPORTABLE_PLATFORM to determine if the on-
premises database platform supports cross-platform tablespace transport and to
determine the endian format of the platform. The Database service platform is little-
endian format.
For the steps this method entails, see RMAN CONVERT Transportable Tablespace with
Data Pump.
Migrating from Oracle Database 11g to Oracle Database 12c in the Cloud
You can migrate Oracle Database 11g databases from on-premises to Oracle Database 12c
databases in the Database service using several different methods.
version, database character set and platform endian format.
If you have not already done so, determine the database version and database character set
of your on-premises database, and determine the endian format of the platform your on-
premises database resides on. Use this information to help you choose an appropriate
method.


CHAPTER 8 Database
database character sets of your on-premises database and the Databaseservice
database are compatible.
database character sets of your on-premises database and the Database service
database and the Database service database are compatible.
endian format.
Data Pump.
This method can be used only if the source database release version is 11.2.0.3 or later,
and the database character sets of your on-premises database and the Database service
For the steps this method entails, see Data Pump Full Transportable.
Migrating from Oracle Database 12c CDB to Oracle Database 12c in the
Cloud
You can migrate Oracle Database 12c CDB databases from on-premises to Oracle Database
12c databases in the Oracle Cloud Infrastructure Database service using several different
methods.

CHAPTER 8 Database

database character sets of your on-premises database and the Database database are
compatible.
Infrastructure Database service database are compatible.
database and the Database database are compatible.
endian format.
Data Pump.

CHAPTER 8 Database

For the steps this method entails, see RMAN Cross-Platform Transportable Tablespace
Backup Sets.
l Unplugging/Plugging (CDB)
This method can be used only if the on-premises platform is little endian, and the on-
premises database and Database database have compatible database character sets
and national character sets.
For the steps this method entails, see Unplugging/Plugging a PDB.
l Remote Cloning (CDB)
This method can be used only if the on-premises platform is little endian, the on-
premises database release is 12.1.0.2 or higher, and the on-premises database and
Database service database have compatible database character sets and national
character sets.
For the steps this method entails, see Remote Cloning a PDB.
l RMAN Cross-Platform Transportable PDB
For the steps this method entails, see RMAN Cross-Platform Transportable PDB.
You can use SQL Developer to create a cart into which you add selected objects to be
loaded into your Oracle Database 12c database on the cloud. In this method, you use
SQL*Loader to load the data into your cloud database.

CHAPTER 8 Database
For the steps this method entails, see SQL Developer and SQL*Loader to Migrate
Selected Objects.
SQL INSERT statements to load the data into your cloud database.
For the steps this method entails, see SQL Developer and INSERT Statements to Migrate
Selected Objects.
Migrating from Oracle Database 12c Non-CDB to Oracle Database 12c in

the Cloud
You can migrate Oracle Database 12c non-CDB databases from on-premises to Oracle
Database 12c databases in Oracle Cloud Infrastructure Database service using several
different methods.

database character sets of your on-premises database and the Database database are
compatible.

CHAPTER 8 Database
endian format.
Data Pump.
database and the Database database are compatible.
For the steps this method entails, see RMAN Cross-Platform Transportable Tablespace
Backup Sets.
l Unplugging/Plugging (non-CDB)
This method can be used only if the on-premises platform is little endian, and the on-
premises database and Database service database have compatible database character
sets and national character sets.
You can use the unplug/plug method to migrate an Oracle Database 12c non-CDB
database to Oracle Database 12c in the cloud. This method provides a way to

CHAPTER 8 Database
consolidate several non-CDB databases into a single Oracle Database 12c CDB on the
cloud.
For the steps this method entails, see Unplugging/Plugging Non-CDB.
l Remote Cloning (non-CDB)
This method can be used only if the on-premises platform is little endian, the on-
premises database release is 12.1.0.2 or higher, and the on-premises database and
Database service database have compatible database character sets and national
character sets.
You can use the remote cloning method to copy an Oracle Database 12c non-CDB on-
premises database to your Oracle Database 12c database in the cloud.
For the steps this method entails, see Remote Cloning Non-CDB.
SQL*Loader to load the data into your cloud database.
For the steps this method entails, see SQL Developer and SQL*Loader to Migrate
Selected Objects.
SQL INSERT statements to load the data into your cloud database.
For the steps this method entails, see SQL Developer and INSERT Statements to Migrate
Selected Objects.
Data Pump Conventional Export/Import

You can use this method regardless of the endian format and database character set of the on-
premises database.
To migrate an on-premises source database, tablespace, schema, or table to the database on

a Database service database deployment using Data Pump Export and Import, you perform
these tasks:

CHAPTER 8 Database
1. On the on-premises database host, invoke Data Pump Export and export the on-
premises database.
2. Use a secure copy utility to transfer the dump file to the Database service compute
node.
3. On the Database service compute node, invoke Data Pump Import and import the data
into the database.
4. After verifying that the data has been imported successfully, you can delete the dump
file.
For information about Data Pump Import and Export, see these topics:
l "Data Pump Export Modes" in Oracle Database Utilities for Release 12.2, 12.1 or 11.2.
l "Data Pump Import Modes" in Oracle Database Utilities for Release 12.2, 12.1 or 11.2.
Data Pump Conventional Export/Import: Example
This example provides a step-by-step demonstration of the tasks required to migrate a

schema from an on-premises Oracle database to a Database service database.
This example illustrates a schema mode export and import. The same general procedure
applies for a full database, tablespace, or table export and import.
In this example, the on-premises database is on a Linux host.
1. On the on-premises database host, invoke Data Pump Export to export the schemas.
a. On the on-premises database host, create an operating system directory to use
for the on-premises database export files.
$ mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the on-premises database host, invoke SQL*Plus and log in to the on-premises
database as the SYSTEM user.
$ sqlplus system
Enter password: <enter the password for the SYSTEM user>
c. Create a directory object in the on-premises database to reference the operating

CHAPTER 8 Database
system directory.
SQL> CREATE DIRECTORY dp_for_cloud AS '/u01/app/oracle/admin/orcl/dpdump/for_cloud';
d. Exit from SQL*Plus.

e. On the on-premises database host, invoke Data Pump Export as the SYSTEM user
or another user with the DATAPUMP_EXP_FULL_DATABASE role and export the on-
premises schemas. Provide the password for the user when prompted.
$ expdp system SCHEMAS=fsowner DIRECTORY=dp_for_cloud
2. Use a secure copy utility to transfer the dump file to the Database service compute
node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Database service compute node, create a directory for the dump file.
$ mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp command to copy the export dump file, make sure the SSH
private key that provides access to the Database service compute node is
available on your on-premises host.
c. On the on-premises database host, use the SCP utility to transfer the dump file to
the Databaseservice compute node.
$ scp –i private_key_file \
/u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \
oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem
3. On the Database service compute node, invoke Data Pump Import and import the data
into the database.
a. On the Database service compute node, invoke SQL*Plus and log in to the
$ sqlplus system
b. Create a directory object in the Database service database.

CHAPTER 8 Database
SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem';
c. If they do not exist, create the tablespace(s) for the objects that will be imported.
d. Exit from SQL*Plus.
e. On the Database service compute node, invoke Data Pump Import and connect to
the database. Import the data into the database.
impdp system SCHEMAS=fsowner DIRECTORY=dp_from_onprem
4. After verifying that the data has been imported successfully, you can delete the
expdat.dmp file.
Data Pump Full Transportable

You can use this method only if the source database release version is 11.2.0.3 or later, and
the database character sets of your on-premises database and the Oracle Cloud Infrastructure
Database service database are compatible.
You can use the Data Pump full transportable method to copy an entire database from your
on-premises host to the database on a Database service database deployment.
To migrate an Oracle Database 11g on-premises database to the Oracle Database 12c
database on a Database service database deployment using the Data Pump full transportable
method, you perform these tasks:
1. On the on-premises database host, prepare the database for the Data Pump full
transportable export by placing the user-defined tablespaces in READ ONLY mode.
2. On the on-premises database host, invoke Data Pump Export to perform the full
transportable export.
3. Use a secure copy utility to transfer the Data Pump Export dump file and the datafiles
for all of the user-defined tablespaces to the Database service compute node.
4. Set the on-premises tablespaces back to READ WRITE.
5. On the Database service compute node, prepare the database for the tablespace import.
6. On the Database service compute node, invoke Data Pump Import and connect to the

CHAPTER 8 Database
database.
file.
Data Pump Full Transportable: Example
This example provides a step-by-step demonstration of the tasks required to migrate an

Oracle Database 11g database to a Database service 12c database.
In this example, the source database is on a Linux host.
1. On the source database host, prepare the database for the Data Pump full transportable
export.
a. On the source database host, create a directory in the operating system to use for
the source export.
$ mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the source database host, invoke SQL*Plus and log in to the source database
as the SYSTEM user.
$ sqlplus system
c. Create a directory object in the source database to reference the operating

system directory.
d. Determine the name(s) of the tablespaces and data files that belong to the user-
defined tablespaces by querying DBA_DATA_FILES. These files will also be listed in
the export output.
SQL> SELECT tablespace_name, file_name FROM dba_data_files;
TABLESPACE_NAME FILE_NAME
--------------- --------------------------------------------------
USERS /u01/app/oracle/oradata/orcl/users01.dbf
UNDOTBS1 /u01/app/oracle/oradata/orcl/undotbs01.dbf
SYSAUX /u01/app/oracle/oradata/orcl/sysaux01.dbf
SYSTEM /u01/app/oracle/oradata/orcl/system01.dbf

CHAPTER 8 Database
EXAMPLE /u01/app/oracle/oradata/orcl/example01.dbf
FSDATA /u01/app/oracle/oradata/orcl/fsdata01.dbf
FSINDEX /u01/app/oracle/oradata/orcl/fsindex01.dbf
SQL>
e. On the source database host, set all tablespaces that will be transported (the
transportable set) to READ ONLY mode.
SQL> ALTER TABLESPACE example READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE fsindex READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE fsdata READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE users READ ONLY;
Tablespace altered.
SQL>
f. Exit from SQL*Plus.

2. On the source database host, invoke Data Pump Export to perform the full transportable
export. Specify FULL=y and TRANSPORTABLE=always. Because this is an Oracle
Database 11g database and full transportable is an Oracle Database 12c feature, specify
VERSION=12. Provide the password for the SYSTEM user when prompted.
$ expdp system FULL=y TRANSPORTABLE=always VERSION=12 DUMPFILE=expdat.dmp DIRECTORY=dp_for_cloud
3. Use a secure copy utility to transfer the Data Pump Export dump file and the datafiles
for all of the user-defined tablespaces to the Database service compute node.
$ mkdir /u01/app/oracle/admin/ORCL/dpdump/from_source
b. Before using the scp utility to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your source
host.
c. On the source database host, use the scp utility to transfer the dump file and all

CHAPTER 8 Database
datafiles of the transportable set to the Database service compute node.

$ scp -i private_key_file \
oracle@compute_node_IP_address:/u01/app/oracle/admin/ORCL/dpdump/from_source
/u01/app/oracle/oradata/orcl/example01.dbf \
oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2
/u01/app/oracle/oradata/orcl/fsdata01.dbf \
/u01/app/oracle/oradata/orcl/fsindex01.dbf \
/u01/app/oracle/oradata/orcl/users01.dbf \
4. Set the source tablespaces back to READ WRITE.

a. Invoke SQL*Plus and log in as the SYSTEM user.
b. Set the user-defined tablespaces back to READ WRITE mode.
SQL> ALTER TABLESPACE example READ WRITE;
Tablespace altered.
SQL> ALTER TABLESPACE fsdata READ WRITE;
Tablespace altered.
SQL> ALTER TABLESPACE fsindex READ WRITE;
Tablespace altered.
SQL> ALTER TABLESPACE users READ WRITE;
Tablespace altered.
c. Exit from SQL*Plus.

5. On the Database service compute node, prepare the PDB for the tablespace import.
a. On the Database service compute node, invoke SQL*Plus and log in to the PDB as
the SYSTEM user.

CHAPTER 8 Database
b. Create a directory object in the PDB.

SQL> CREATE DIRECTORY dp_from_source AS '/u01/app/oracle/admin/ORCL/dpdump/from_source';
PDB.
Import the data into the database using the TRANSPORT_DATAFILES option.
$ impdp system@PDB2 FULL=y DIRECTORY=dp_from_source \
TRANSPORT_
DATAFILES='/u02/app/oracle/oradata/ORCL/PDB2/example01.dbf',\
'/u02/app/oracle/oradata/ORCL/PDB2/fsdata01.dbf',\
'/u02/app/oracle/oradata/ORCL/PDB2/fsindex01.dbf,'\
'/u02/app/oracle/oradata/ORCL/PDB2/users01.dbf'
expdat.dmp dump file.
Data Pump Transportable Tablespace

You can use this method only if the on-premises platform is little endian, and the database
character sets of your on-premises database and the Oracle Cloud Infrastructure Database
service database are compatible.
The Transportable Tablespace method is generally much faster than a conventional

export/import of the same data because the data files containing all of the actual data are
simply copied to the destination location. You use Data Pump to transfer only the metadata of
the tablespace objects to the new database.
To migrate an on-premises source database to the database deployment on the Database

service using the Data Pump Transportable Tablespace method, you perform these tasks:
1. On the on-premises database host, prepare the database for the Data Pump
transportable tablespace export.
2. On the on-premises database host, invoke Data Pump Export to perform the
3. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace
datafiles to the Database service compute node.

CHAPTER 8 Database

5. On the Databaseservice compute node, prepare the database for the tablespace import.
database.
7. Set the tablespaces on the Database service database to READ WRITE mode.
file.
Data Pump Transportable Tablespace: Example
This example provides a step-by-step demonstration of the tasks required to migrate

tablespaces in an on-premises Oracle database to a Database service database.
This example performs a migration of the FSDATA and FSINDEX tablespaces.
a. On the on-premises database host, create a directory in the operating system to
use for the on-premises export.
mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
sqlplus system

system directory.
d. Determine the name(s) of the datafiles that belong to the FSDATA and FSINDEX
tablespaces by querying DBA_DATA_FILES. These files will also be listed in the

CHAPTER 8 Database
export output.
SQL> SELECT file_name FROM dba_data_files
2 WHERE tablespace_name = 'FSDATA';
FILE_NAME
-----------------------------------------------------------------
/u01/app/oracle/oradata/orcl/fsdata01.dbf
SQL> SELECT file_name FROM dba_data_files

2 WHERE tablespace_name = 'FSINDEX';
FILE_NAME
-----------------------------------------------------------------
/u01/app/oracle/oradata/orcl/fsindex01.dbf
e. On the on-premises database host, set all tablespaces that will be transported
(the transportable set) to READ ONLY mode.
Tablespace altered.
Tablespace altered.
f. Exit from SQL*Plus.

On the on-premises database host, invoke Data Pump Export and connect to the on-
premises database. Export the on-premises tablespaces using the TRANSPORT_
TABLESPACES option. Provide the password for the SYSTEM user when prompted.
expdp system TRANSPORT_TABLESPACES=fsdata,fsindex TRANSPORT_FULL_CHECK=YES DIRECTORY=dp_for_cloud

CHAPTER 8 Database
mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp utility to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your on-
premises host.
c. On the on-premises database host, use the scp utility to transfer the dump file
and all datafiles of the transportable set to the Database service compute node.
scp -i private_key_file \
$ scp -i private_key_file \/u01/app/oracle/oradata/orcl/fsdata01.dbf \

oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL
$ scp -i private_key_file \/u01/app/oracle/oradata/orcl/fsindex01.dbf \


b. Set the FSDATA and FSINDEX tablespaces back to READ WRITE mode.
Tablespace altered.
Tablespace altered.


CHAPTER 8 Database
c. If the owners of the objects that will be imported do not exist in the database,
create them before performing the import. The transportable tablespace mode of
import does not create the users.
SQL> CREATE USER fsowner
2 PROFILE default
3 IDENTIFIED BY fspass
4 TEMPORARY TABLESPACE temp
5 ACCOUNT UNLOCK;
database.
impdp system DIRECTORY=dp_from_onprem \
TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \
'/u02/app/oracle/oradata/ORCL/fsindex01.dbf'
7. Set the tablespaces on the Database service database to READ WRITE mode.
b. Set the FSDATA and FSINDEX tablespaces to READ WRITE mode.
Tablespace altered.
Tablespace altered.

Remote Cloning a PDB

You can use this method only if the on-premises platform is little endian, the on-premises
database release is 12.1.0.2 or higher, and the on-premises database and Database service
database have compatible database character sets and national character sets.

CHAPTER 8 Database
You can use the remote cloning method to copy a PDB from your on-premises Oracle
Database 12c database to a PDB in an Oracle Database 12c database on the Database service.
Migration Tasks
To migrate an Oracle Database 12c PDB to a PDB in a Database service database deployment
using the remote cloning method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB and
then reopen it in READ ONLY mode.
2. On the Database service compute node, invoke SQL*Plus and create a database link that
enables a connection to the on-premises database.
3. On the Database service compute node, execute the CREATE PLUGGABLE DATABASE
command to clone the on-premises PDB.
4. On the Database compute node, open the new PDB by executing the ALTER PLUGGABLE
DATABASE OPEN command.
5. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises
PDB back to READ WRITE mode.
For more information, see "Cloning a Remote PDB or Non-CDB" in Oracle Database
Administrator's Guide for Release 12.2 or 12.1.
Remote Cloning Non-CDB

You can use this method only if the on-premises platform is little endian, the on-premises
database release is 12.1.0.2 or higher, and the on-premises database and Database service
database have compatible database character sets and national character sets.
You can use the remote cloning method to copy an Oracle Database 12c non-CDB on-premises
database to a PDB in an Oracle Database 12c database on the Databaseservice.

CHAPTER 8 Database
Migration Tasks
To migrate an Oracle Database 12c non-CDB database to a Database service database

deployment using the remote cloning method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and set the on-premises database
to READ ONLY mode.
2. On the Database service compute node, invoke SQL*Plus and create a database link that
enables a connection to the on-premises database.
3. On the Database service compute node, execute the CREATE PLUGGABLE DATABASE
command to clone the on-premises non-CDB database.
4. On the Database service compute node, execute the $ORACLE_
HOME/rdbms/admin/noncdb_to_pdb.sql script.
5. On the Database service compute node, open the new PDB by executing the ALTER
PLUGGABLE DATABASE OPEN command.
database back to READ WRITE mode.
For more information, see "Cloning a Remote PDB or Non-CDB" in Oracle Database
RMAN Cross-Platform Transportable PDB

This method can be used only if the on-premises platform is little endian, and the database
character sets of your on-premises database and the Database service database are
compatible.
To migrate an Oracle Database 12c PDB to a PDB in an Oracle Database 12c database on a
Database service deployment using the RMAN cross-platform transportable PDB method, you
perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB.
2. On the on-premises database host, execute the ALTER PLUGGABLE DATABASE UNPLUG
command to generate an XML file containing the list of datafiles that will be plugged in

CHAPTER 8 Database
on the cloud database.

3. On the on-premises database host, invoke RMAN and connect to the root. Execute the
BACKUP FOR TRANSPORT PLUGGABLE DATABASE command.
4. Use a secure copy utility to transfer the XML file and the backup set to the Database
service compute node.
5. On the Database service compute node, invoke RMAN and connect to the root. Execute
the RESTORE ALL FOREIGN DATAFILES command.
6. the Database service compute node, invoke SQL*Plus and connect to the root. Execute
the CREATE PLUGGABLE DATABASE command.
7. the Database service compute node, execute the ALTER PLUGGABLE DATABASE OPEN
command.
For more information, see " Performing Cross-Platform Data Transport in CDBs and PDBs" in
Oracle Database Backup and Recovery User's Guide for Release 12.2 or 12.1.
RMAN Cross-Platform Transportable Tablespace Backup Sets

You can use this method only if the database character sets of your on-premises database and
the Database service database are compatible.
Note
For detailed information on a similar method that

enables you to perform a cross-platform transport of an
entire database, see the Oracle Database 12c Backup
and Recovery User's Guide for Release 12.2 or 12.1 .
When you transport an entire database to a different
platform, the source platform and the destination
platform must use the same endian format.

CHAPTER 8 Database
To migrate Oracle Database 12c on-premises tablespaces to an Oracle Database 12c database
on a Database service deployment using the RMAN cross-platform transportable backup sets
1. On the on-premises database host, prepare the database by placing the user-defined
tablespaces that you intend to transport in READ ONLY mode.
2. On the on-premises database host, invoke RMAN and use the BACKUP command with the
TO PLATFORM or FOR TRANSPORT clause and the DATAPUMP clause to create a backup set
for cross-platform transport. See in "BACKUP" in Oracle Database Backup and Recovery
Reference for Release 12.2 or 12.1 for more information on the BACKUP command.
3. Use a secure copy utility to transfer the backup sets, including the Data Pump export
dump file, to the Database service compute node.
5. On the Database service compute node, prepare the database by creating the required
schemas.
6. On the Database service compute node, invoke RMAN and use the RESTORE command
with the foreignFileSpec subclause to restore the cross-platform backup.
7. On the Database service compute node, set the tablespaces on the database to READ
WRITE mode.
For more information, see "Overview of Cross-Platform Data Transport Using Backup Sets" in
Oracle Database Backup and Recovery User’s Guide for Release 12.2 or 12.1.
RMAN Cross-Platform Transportable Tablespace Backup Sets: Example

tablespaces in an Oracle Database PDB to a Database service database.
1. On the on-premises database host, prepare the database by creating a directory for the
export dump file and placing the user-defined tablespaces that you intend to transport in

CHAPTER 8 Database
READ ONLY mode..

use for the export dump.
b. On the on-premises data host, invoke SQL*Plus and log in to the PDB as the
SYSTEM user..
sqlplus system@pdb_servicename
Enter password: enter the password for the SYSTEM user

system directory.
d. On the on-premises database host, set all tablespaces that will be transported
e. Exit from SQL*Plus.

2. On the on-premises database host, invoke RMAN and use the BACKUP command with the
TO PLATFORM or FOR TRANSPORT clause and the DATAPUMP clause to create a backup set
for cross-platform transport.
a. On the on-premises database host, create an operating system directory for the
datafiles.
mkdir /u01/app/oracle/admin/orcl/rman_transdest
b. Invoke RMAN and log in as a user that has been granted the SYSDBA or SYSBACKUP
privilege.
rman target username@pdb_servicename
c. Execute the BACKUP command.

RMAN> BACKUP FOR TRANSPORT
2> FORMAT '/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.bck'

CHAPTER 8 Database
3> TABLESPACE fsdata,fsindex

4> DATAPUMP FORMAT '/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.dmp';
d. Log out of RMAN.

e. Optionally, navigate to the directory you specified in the BACKUP command to view
the files that were created.
cd /u01/app/oracle/admin/orcl/rman_transdest
$ ls
fs_tbs.bck fs_tbs.dmp
3. Use a secure copy utility to transfer the backup set, including the Data Pump export
dump file, to the Database service compute node.
a. On the Database service compute node, create a directory for the backup set and
dump file.
mkdir /tmp/from_onprem
b. Before using the scp command to copy files, make sure the SSH private key that
premises host.
c. On the on-premises database host, use the SCP utility to transfer the backup set
and the dump file to the Database service compute node.
/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.bck \
oracle@IP_address_DBaaS_VM:/tmp/from_onprem
/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.dmp \
oracle@IP_address_DBaaS_VM:/tmp/from_onprem

a. Invoke SQL*Plus and log in to the PDB as the SYSTEM user.

CHAPTER 8 Database


5. On the Database service compute node, prepare the database by creating the required
schemas.
a. On the Database service compute node, invoke SQL*Plus and log in to the PDB as
the SYSTEM user.
b. If the owners of the objects that will be imported do not exist in the database,
create them before performing the RESTORE.
2 PROFILE default
5 ACCOUNT UNLOCK;
6. On the Database service compute node, invoke RMAN and use the RESTORE command
with the foreignFileSpec subclause to restore the cross-platform backup.
a. Create an operating system directory for the Data Pump Dump file.
mkdir /tmp/from_onprem
b. Invoke RMAN and log in to the PDB as a user that has been granted the SYSDBA or
SYSBACKUP privilege.
rman target username@pdb_servicename
c. Execute the RESTORE command.

RMAN> RESTORE FOREIGN TABLESPACE fsdata,fsindex TO NEW
2> FROM BACKUPSET '/tmp/from_onprem/fs_tbs.bck'
3> DUMP FILE DATAPUMP DESTINATION '/tmp/datapump'
4> FROM BACKUPSET '/tmp/from_onprem/fs_tbs.dmp';
d. Exit from RMAN.

7. On the Database service compute node, set the tablespaces to READ WRITE mode.

CHAPTER 8 Database
a. Invoke SQL*Plus and log in to the PDB as the SYSTEM user.

b. Set the FSDATA and FSINDEX tablespaces to READ WRITE.

8. After verifying that the data has been imported successfully, you can delete the backup
set files that were transported from the on-premises host.
RMAN Transportable Tablespace with Data Pump

You can use this method only if the on-premises platform is little endian, and the database
character sets of your on-premises database and the Databaseservice database are
compatible.
You can use this method to eliminate placing the tablespaces in READ ONLY mode, as required
by the Data Pump Transportable Tablespace method.
To migrate an on-premises source database to a database deployment on the Database

service using the RMAN Transportable Tablespace with Data Pump method, you perform these
tasks:
1. On the on-premises database host, invoke RMAN and create the transportable
tablespace set.
database. Import the data into the database using the TRANSPORT_DATAFILES option.
file.

CHAPTER 8 Database
RMAN Transportable Tablespace with Data Pump: Example

1. On the on-premises database host, invoke RMAN and create the transportable
tablespace set.
a. On the on-premises database host, create an operating system directory for the
datafiles.
mkdir /u01/app/oracle/admin/orcl/rman_transdest
b. On the on-premises data host, create an operating system directory for the RMAN
auxiliary instance files.
mkdir /u01/app/oracle/admin/orcl/rman_auxdest
c. Invoke RMAN and log in as the SYSTEM user. Enter the password for the SYSTEM
user when prompted.
rman target system
d. Execute the TRANSPORT TABLESPACE command.

RMAN> TRANSPORT TABLESPACE fsdata, fsindex
2> TABLESPACE DESTINATION '/u01/app/oracle/admin/orcl/rman_transdest'
3> AUXILIARY DESTINATION '/u01/app/oracle/admin/orcl/rman_auxdest';
e. Log out of RMAN.

f. Optionally, navigate to the directory you specified for the TABLESPACE
DESTINATION and view the files that were created by the TRANSPORT TABLESPACE
operation.
cd /u01/app/oracle/admin/orcl/rman_transdest
$ ls
dmpfile.dmp fsdata01.dbf fsindex01.dbf impscrpt.sql

CHAPTER 8 Database

premises host.
c. On the on-premises database host, use the SCP utility to transfer the dump file
and all datafiles of the transportable set to the Database service compute node.
/u01/app/oracle/admin/orcl/rman_transdest/dmpfile.dmp \
/u01/app/oracle/admin/orcl/rman_transdest/fsdata01.dbf \
/u01/app/oracle/admin/orcl/rman_transdest/fsindex01.dbf \

CHAPTER 8 Database

2 PROFILE default
5 ACCOUNT UNLOCK;
database.
impdp system DIRECTORY=dp_from_onprem DUMPFILE='dmpfile.dmp' \
dmpfile.dmp dump file.
RMAN CONVERT Transportable Tablespace with Data Pump

You can use this method only if the database character sets of your on-premises database and
the Database service database are compatible.
This method is similar to the Data Pump Transportable Tablespace method, with the addition
of the RMAN CONVERT command to enable transport between platforms with different
endianness. Query V$TRANSPORTABLE_PLATFORM to determine if the on-premises database
platform supports cross-platform tablespace transport and to determine the endian format of
the platform. The Database service platform is little-endian format.
To migrate tablespaces from your on-premises Oracle database to a database deployment on

the Database service using RMAN, you perform these tasks:
3. On the on-premises database host, invoke RMAN and use the CONVERT TABLESPACE
command to convert the tablespace datafile to the Database service platform format.

CHAPTER 8 Database
Refer to the Oracle Database Backup and Recovery Reference for more information on
the CONVERT command.
4. Use a secure copy utility to transfer the Data Pump Export dump file and the converted
tablespace datafiles to the Database service compute node.
database.
8. On the Database service compute node, set the tablespaces in the database to READ
WRITE mode.
file.
RMAN CONVERT Transportable Tablespace with Data Pump: Example

use for the on-premises export.
sqlplus system

CHAPTER 8 Database
system directory.
d. On the on-premises database host, set all tablespaces that will be transported
Tablespace altered.
Tablespace altered.
e. Exit from SQL*Plus.

On the on-premises database host, invoke Data Pump Export and connect to the on-
premises database. Export the on-premises tablespaces using the TRANSPORT_
TABLESPACES option. Provide the password for the SYSTEM user when prompted.
expdp system TRANSPORT_TABLESPACES=fsdata,fsindex TRANSPORT_FULL_CHECK=YES DIRECTORY=dp_for_cloud
3. On the on-premises database host, invoke RMAN and use the CONVERT TABLESPACE
command to convert the tablespace datafile to the Database service platform format.
a. Invoke RMAN.
rman target /
b. Execute the RMAN CONVERT TABLESPACE command to convert the datafiles and
store the converted files in a temporary location on the on-premises database
host.
RMAN> CONVERT TABLESPACE fsdata, fsindex
2> TO PLATFORM 'Linux x86 64-bit'
3> FORMAT '/tmp/%U ';
…
input datafile file number=00006 name=/u01/app/oracle/oradata/orcl/fsdata01.dbf
converted datafile=/tmp/data_D-ORCL_I-1410251631_TS-FSDATA_FNO-6_0aqc9un3
…
input datafile file number=00007 name=/u01/app/oracle/oradata/orcl/fsindex01.dbf

CHAPTER 8 Database
converted datafile=/tmp/data_D-ORCL_I-1410251631_TS-FSINDEX_FNO-7_0bqc9un6
…
c. Take note of the names of the converted files. You will copy these files to the
Database service compute node in the next step.
d. Exit RMAN.
4. Use a secure copy utility to transfer the Data Pump Export dump file and the converted
tablespace datafiles to the Database service compute node.
a. On the Databaseservice compute node, create a directory for the dump file.
premises host.
c. On the on-premises database host, use the scp utility to transfer the dump file
and all data files of the transportable set to the Database service compute node.
/tmp/data_D-ORCL_I-1410251631_TS-FSDATA_FNO-6_0aqc9un3 \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsdata01.dbf
/tmp/data_D-ORCL_I-1410251631_TS-FSINDEX_FNO-7_0bqc9un6 \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsindex01.dbf


CHAPTER 8 Database

Tablespace altered.
Tablespace altered.

2 PROFILE default
5 ACCOUNT UNLOCK;
database.
Import the data into the Database service database using the TRANSPORT_DATAFILES
option
impdp system DIRECTORY=dp_from_onprem \
8. On the Database service compute node, set the tablespaces in the database to READ
WRITE mode.
b. Set the FSDATA and FSINDEX tablespaces to READ WRITE mode.

CHAPTER 8 Database

Tablespace altered.
Tablespace altered.

RMAN DUPLICATE from an Active Database

This topic explains how to migrate an entire, active container database (CDB) or non-CDB
database to Oracle Cloud Infrastructure by using RMAN Active Duplication. The database to be
migrated can reside on-premises or in Oracle Cloud Infrastructure Classic. This topic does not
cover duplicating a pluggable database, or migrating a pluggable database or non-CDB to a
CDB in the cloud.
The following terms are used throughout this topic:
l Source database: The active database to be migrated.

l Target database: The new database (duplicated from the source database) on a
DB system in the Oracle Cloud Infrastructure.
Note
Version 11.2.0.4 databases will be migrated to a DB

system using a ACFS storage.
Prerequisites
For the source database to be migrated, you'll need:
l The source database name, database unique name, listener port, service name,
database home patch level, and the password for SYS.

CHAPTER 8 Database
l A copy of the sqlpatch directory from the source database home. This is required for
rollback in case the target DB system does not include these patches.
l If the source database is configured with Transparent Data Encryption (TDE), you'll
need a backup of the wallet and the wallet password to allow duplication of a database
with encrypted data.
When migrating a source database to an existing target database, Oracle recommends that
you patch the source environment to the same database bundle patch level as the target
database home. If the source environment has an interim patch (previously known as a "one-
off" patch) that includes a sqlpatch component, and that sqlpatch is missing from the target
environment (or a different cumulative patch is applied), the interim patch should be rolled
back in the source environment before the migration, if possible.
Tip
To check for interim patches installed on the source or

target database, use the $ORACLE_HOME/OPatch/opatch
lspatches command. To roll back SQL changes in the
target database, copy the $ORACLE_
HOME/sqlpatch/<patch#>/postdeinstall.sql
script from the source environment to the cloud
environment and execute the postdeinstall.sql
script.
For the target database, you'll need:
l A target DB system that supports the same database edition as the source database
edition. When you launch a DB system, an initial database is created on it. If necessary,
you can delete that database and create a new one by using the dbcli command line
interface. For more information on creating a DB system, see Managing DB Systems.
For information about creating a database with the DBCLI, see Database Commands.
l The target database name, database unique name, auxiliary service name, and

CHAPTER 8 Database
database home patch level.

l A free TCP port in the target database to setup the auxiliary instance.
If you need to roll back interim patches in the target environment so that the patch level
matches that of the source environment, copy the source DB $ORACLE_
HOME/sqlpatch/<patch_number> directory to the target database home.
Migrating Source Databases That Include Patch Set Updates (PSUs)
In Oracle Cloud Infrastructure DB systems, the database home includes an installation of

Database Proactive Bundle Patches. If the source DB uses Patch Set Updates (PSUs), follow
the instructions in MOS Note:1962125.1 (Oracle Database - Overview of Database Patch
Delivery Methods) for migrating the DB into Oracle Cloud Infrastructure.
Verifying the Environment
Perform the following steps before you begin the migration:
1. Make sure the source DB system is reachable from the target DB system. You should be
able to SSH between the two hosts.
2. On the target host, use the TNSPING utility to make sure the source host listener port
works. For example:
tnsping <source host>:1521
3. On the target host, use Easy Connect to verify the connection to the source database:
<host>:<port>/<servicename>
For example:
sqlplus system@129.145.0.164:1521/proddb
Make sure the connection string does not exceed 64 characters.

4. Copy the required sqlpatch files (for rollback) from the source database home to the
target database.
5. Make sure at least one archivelog has been created on the source database, otherwise,
the RMAN duplication will fail with an error.

CHAPTER 8 Database
6. If the source database uses wallets, back up the password-based wallet and copy it to
the standard location in the DB system:
/opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>/
7. Make sure the compatibility parameters in the source database are set to at least:
l 18.0.0.0.0 for an 18.1.0.0 database
l 12.1.0.2.0 for a 12.1.0.2 or a 12.2.0.1 database
l 11.2.0.4.0 for an 11.2.0.4 database
Setting Up Storage on the DB System

login as: opc
The following example creates 10GB of ACFS storage for the tdetest database.
[root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS
Note
When migrating a version 11.2 database,

4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the
next step.

CHAPTER 8 Database
---------------------------------------- ------ -------------------- ----------

9dcdfb8e-e589-4d5f-861a-e5ba981616ed Acfs tdetest Configured
5. Use the dbcli describe-dbstorage command with the storage ID from the previous step
to list the DATA, RECO and REDO locations.
[root@dbsys ~]# dbcli describe-dbstorage --id 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DBStorage details
----------------------------------------------------------------
ID: 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DB Name: tdetest
DBUnique Name: tdetest
DB Resource ID:
Storage Type: Acfs
DATA Location: /u02/app/oracle/oradata/tdetest
UpdatedTime: August 24, 2016 5:25:53 PM UTC
Note the locations. You'll use them later to set the db_create_file_dest, db_create_
online_log_dest, and db_recovery_file_dest parameters for the database.
Choosing an ORACLE_HOME
Decide which ORACLE_HOME to use for the database restore and then switch to that home
with the correct ORACLE_BASE, ORACLE_HOME, and PATH settings.
To get a list of existing ORACLE_HOMEs, use the dbcli list-dbhomes command. To create a
new ORACLE_HOME, use the dbcli create-dbhome command.
Copying the Source Database Wallets
Skip this section if the source database is not configured with TDE.
1. On the DB system, become the oracle user:

sudo su - oracle
2. Create the following directory if it does not already exist:

CHAPTER 8 Database
mkdir /opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>
3. Copy the ewallet.p12 file from the source database to the directory you created in the
previous step.
4. On the target host, make sure that $ORACLE_HOME/network/admin/sqlnet.ora
contains the following line:
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=
(DIRECTORY=/opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME)))
Add the line if it doesn't exist in the file. (The line might not be there if this is a new
home and no database has been created yet on this host.)
5. Create the autologin wallet from the password-based wallet to allow auto-open of the
wallet during restore and recovery operations.
For version 12c, use the ADMINISTER KEY MANAGEMENT command:
$cat create_autologin_12.sh
#!/bin/sh
if [ $# -lt 2 ]; then
echo "Usage: $0 <dbuniquename> <remotewalletlocation>"
exit 1;
fi
mkdir /opt/oracle/dcs/commonstore/wallets/tde/$1
cp $2/ewallet.p12* /opt/oracle/dcs/commonstore/wallets/tde/$1
rm -f autokey.ora
echo "db_name=$1" > autokey.ora
autokeystoreLog="autologinKeystore_`date +%Y%m%d_%H%M%S_%N`.log"
echo "Enter Keystore Password:"
read -s keystorePassword
echo "Creating AutoLoginKeystore -> "
sqlplus "/as sysdba" <<EOF
spool $autokeystoreLog
set echo on
startup nomount pfile=autokey.ora
ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE
FROM KEYSTORE '/opt/oracle/dcs/commonstore/wallets/tde/$1' -- Keystore location
IDENTIFIED BY "$keystorePassword";

CHAPTER 8 Database
shutdown immediate;
EOF
For version 11g, use the orapki command:

orapki wallet create -wallet wallet_location -auto_login [-pwd password]
Setting Up the Static Listener
Set up the static listener for the auxiliary instance for RMAN duplication.
1. On the DB system, create $ORACLE_HOME/network/admin/listener.ora and add the

following content to it.
LISTENER_aux_<db_unique_name>=
(DESCRIPTION=
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=TCP)(HOST=<hostname> or <ipaddress>)(PORT=<Available TCP Port>))
)
)
SID_LIST_LISTENER_aux_<db_unique_name>=
(SID_LIST=
(SID_DESC=
(GLOBAL_DBNAME=<auxServiceName with domain>)
(ORACLE_HOME=<Oraclehome for target database>)
(SID_NAME=<database name>))
)
2. Make sure the port specified in (PORT=<Available TCP Port>) is open in the DB
system's iptables and in the DB system's cloud network Security List.
Using the RMAN Duplicate Command to Migrate the Database
1. Set the following environment variables for RMAN and SQL Plus sessions for the
database:
ORACLE_HOME=<path of Oracle Home where the database is to be restored>
ORACLE_SID=<database name>
ORACLE_UNQNAME=<db_unique_name in lower case>
NLS_DATE_FORMAT="mm/dd/yyyy hh24:mi:ss"
2. Start the listener:

CHAPTER 8 Database
lsnrctl start listener_aux_<db_unique_name>
3. Create an init.ora file with the minimal required parameters as described in Creating
an Initialization Parameter File and Starting the Auxiliary Instance and use it for the
auxiliary instance.
4. Start the auxiliary instance in nomount mode:
startup nomount
5. Run the following commands to duplicate the database. Note that the example below
uses variables to indicate the values to be specified:
rman target sys/$sourceSysPassword@$sourceNode:$sourceListenerPort/$sourceDb auxiliary
sys/$auxSysPassword@$targetNode:$targetListenerPort/$auxService<<EOF
spool log to "`date +%Y%m%d_%H%M%S_%N`_duplicate_${targetDbUniqueName}_from_${sourceDb}.log"

set echo on
duplicate target database to $targetDb from active database

password file
spfile
PARAMETER_VALUE_CONVERT $sourceDb $targetDb $sourceDbUniqueNameCaps $targetDbUniqueNameCaps
set cluster_database='false'
set db_name='$targetDb'
set db_unique_name='$targetDbUniqueName'
set db_create_file_dest='$dataLoc'
set db_create_online_log_dest_1='$redoLoc'
set db_recovery_file_dest='$recoLoc'
set audit_file_dest = '$auditFileDest'
reset control_files
nofilenamecheck
;
EOF
Preparing to Register the Database
Before you register the database:
1. Make sure the database COMPATIBLE parameter value is acceptable.

For a 11.2 database, the minimum compatibility value is 11.2.0.4.

CHAPTER 8 Database
For a 12c database, the minimum compatibility value is 12.1.0.2.

If the value is less than the minimum, the database cannot be registered until you
upgrade the database compatibility.
2. Use the following command to verify that the database has registered with the local
listener and service name.
lsnrctl services
3. Use the following command to verify that the password file was restored or created for
a new database.
ls -ltr $ORACLE_HOME/dbs/orapw<$ORACLE_SID>
If the file does not exist, create it using the orapwd command.
orapwd file=<$ORACLE_HOME/dbs/orapw<$ORACLE_SID>> password=<sys password>
4. Use the following command to verify that the restored database is open in read write
mode.
select open_mode from v$database;
Read write mode is required to register the database later. Any PDBs must also be in
read write mode.
5. From oracle home on the migrated database host, use the following command verify the
connection to SYS.
conn sys/<Password>@<ServiceName> as sysdba
This connection is required to register the database later. Fix any connection issues
before continuing.
6. Copy the folder $ORACLE_HOME/sqlpatch from source database to the target database.
This will enable the dbcli register-database command to rollback any conflicting
patches.

CHAPTER 8 Database
Note
If you are migrating a version 11.2 database,

additional steps are required after you register the
database. For more information, see Rolling Back
Patches on a Version 11.2 Database.
7. Use the following SQL*Plus command to make sure the database is using the spfile.
SHOW PARAMETERS SPFILE
Registering the Database on the DB System
The dbcli register-database command registers the migrated database to the dcs-agent so it
can be managed by the dcs-agent stack.
Note

available on 2-node RAC DB Systems.
As the root user, use the dbcli register-database command to register the database on
the DB system, for example:
[root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename crmdb.example.com --
syspassword
Password for SYS:
{
"message" : null,
"reports" : [ ],
"description" : "Database service registration with db service name: crmdb.example.com",
}

CHAPTER 8 Database
Migrating a Version 12.1 or Later Database That Includes SQL Patch Components
For a 1-node DB system at version 12.1 or higher, the dbcli register-database command
automates the datapatch execution. Before executing the dbcli register-database
command, open all PDBs in read-write mode. If you have already run the dbcli register-
database command and did not open all PDBs, or did not copy the $ORACLE_HOME/sqlpatch
directory from the source database home, manually rerun the datapatch utility to configure
the SQL portion of existing interim patches. This can be done by executing the command
$ORACLE_HOME/OPatch/opatch datapatch.
Tip
If the source database includes patch 23170620 and the

target database is running with the October 2017 patch
or a later one, the $ORACLE_HOME/sqlpatch directory
does not need to be copied to the target database,
because the contents of the patch are already installed
in the target database.
Rolling Back Patches on a Version 11.2 Database
For version 11.2 databases, the sqlpatch application is not automated, so any interim patches
(previously known as a "one-off" patches) applied to the source database that are not part of
the installed PSU must be rolled back manually in the target database. After registering the
database, execute the catbundle.sql script and then the postinstall.sql script with the
corresponding PSU patch (or the overlay patch on top of the PSU patch), as described below.

CHAPTER 8 Database
Tip
Some interim patches may include files written to the

$ORACLE_HOME/rdbms/admin directory as well as the
$ORACLE_HOME/sqlpatch directory. Oracle
recommends that you roll back these patches in the
source database using the instructions in the patch
read-me prior to migrating the database to OCI
environment. Contact Oracle Support if you need
assistance with rolling back these patches.
1. On the DB System, use the dbcli list-dbhomes command to find the PSU patch
number for the version 11.2 database home. In the following sample command output,
the PSU patch number is the second number in the DB Version column:
ID Name DB Version
------------------------------------ ----------------- ------------------------------------- --
--------------------------------------- ----------
59d9bc6f-3880-4d4f-b5a6-c140f16f8c64 OraDB11204_home1 11.2.0.4.160719 (23054319, 23054359)
/u01/app/oracle/product/11.2.0.4/dbhome_1 Configured
(The first patch number, 23054319 in the example above, is for the OCW component in
the database home.)
2. Find the overlay patch, if any, by using the lsinventory command. In the following
example, patch number 24460960 is the overlay patch on top of the 23054359 PSU
patch.
$ $ORACLE_HOME/OPatch/opatch lsinventory
...
Installed Top-level Products (1):
Oracle Database 11g 11.2.0.4.0

There are 1 products installed in this Oracle Home.

CHAPTER 8 Database
Interim patches (5) :
Patch 24460960 : applied on Fri Sep 02 15:28:17 UTC 2016

Unique Patch ID: 20539912
Created on 31 Aug 2016, 02:46:31 hrs PST8PDT
Bugs fixed:
23513711, 23065323, 21281607, 24006821, 23315889, 22551446, 21174504
This patch overlays patches:
23054359
This patch needs patches:
23054359
as prerequisites
3. Start SQL*Plus and execute the catbundle.sql script, for example:

SQL> startup
SQL> @$ORACLE_HOME/rdbms/admin/catbundle.sql psu apply
exit
4. Apply the sqlpatch, using the overlay patch number from the previous step, for
example:
SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql
exit
Creating a Backup Configuration (Optional)
If you would like to manage the database backup with the dbcli command line interface, you
can associate a new or existing backup configuration with the migrated database when you
register it or after you register it. A backup configuration defines the backup destination and
recovery window for the database. As the root user, use the following commands to create,
list, and display backup configurations:

CHAPTER 8 Database
Post Migration Checklist
After the database is migrated and registered on the DB system, use the following checklist to
verify the results of the migration and perform any post-migration customizations.
1. Make sure the database files were restored in OMF format.

2. Make sure the database is listed in the dbcli list-databases command output.
3. Check for the following external references in the database and update them if
necessary:
l External tables: If the source database uses external tables, back up that data
and migrate it to the target host.
l Directories: Customize the default directories as needed for the migrated
database.
l Database links: Make sure all the required TNS entries are updated in the
tnsnames.ora file in ORACLE_HOME.
l Email and URLs: Make sure any email addresses and URLs used in the database
are still accessible from the DB system.
l Scheduled jobs: Review the jobs scheduled in source database and schedule
similar jobs as needed in the migrated database.
4. If you associated a backup configuration when you registered the database, run a test
back up using the dbcli create-backup command.
5. Verify that patches have been applied to all PDBs if the migrated database contains CDB
and PDBs.
6. Validate the database performance by using Database Replay and SQL Performance
Analyzer for SQL. For more information, see the Database Testing Guide.
SQL Developer and INSERT Statements to Migrate Selected Objects

You can use SQL Developer to create a cart into which you add selected objects to be loaded
into an Oracle Database 12c database in the Oracle Cloud Infrastructure Database service.
In this method, you use SQL INSERT statements to load the data into your cloud database.

CHAPTER 8 Database
To migrate selected objects to an Oracle Database 12c database in a Database service

deployment using SQL Developer and INSERT statements, you perform these tasks:
1. Launch SQL Developer, connect to your on-premises database and create a cart
containing the objects you want to migrate.
2. In SQL Developer, click the Export Cart icon and select “Insert” in the Format menu.
3. In SQL Developer, open a connection to the Oracle Database 12c database in the
Database service and execute the generated script to create the database objects.
4. In SQL Developer, open a connection to the Oracle Database 12c database in the
Database service and run the generated script to create the objects and load the data.
SQL Developer and SQL*Loader to Migrate Selected Objects

You can use SQL Developer to create a cart into which you add selected objects to be loaded
into an Oracle Database 12c database in the Oracle Cloud Infrastructure Database.
In this method, you use SQL*Loader to load the data into your cloud database.
To migrate selected objects to an Oracle Database 12c database in the Database service
deployment using SQL Developer and SQL*Loader, you perform these tasks:
1. Launch SQL Developer, connect to your on-premises database and create a cart
containing the objects you want to load into your cloud database.
2. In SQL Developer, click the Export Cart icon and select “loader” in the Format menu.
3. In SQL Developer, open a connection to the Oracle Database 12c database on the
Database service and execute the generated script to create the database objects.
4. Use a secure copy utility to transfer the SQL*Loader control files and the SQL*Loader
data files to the the Database service compute node.
5. On the the Database service compute node, invoke SQL*Loader to load the data using
the SQL*Loader control files and data files for each object.

CHAPTER 8 Database
Unplugging/Plugging a PDB
You can use this method only if the on-premises platform is little endian, and the on-premises
database and the Oracle Cloud Infrastructure Database service database have compatible
database character sets and national character sets.
You can use the unplug/plug method to migrate an Oracle Database 12c PDB to a PDB in an
Oracle Database 12c database on a Database service database deployment.
To migrate an Oracle Database 12c PDB to a PDB in the Oracle Database 12c database on an
Oracle Cloud Infrastructure Database service database deployment using the plug/unplug
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB.
2. On the on-premises database host, execute the ALTER PLUGGABLE DATABASE UNPLUG
command to generate an XML file containing the list of datafiles that will be plugged in
to the database on the Database service.
3. Use a secure copy utility to transfer the XML file and the datafiles to the
Databaseservice compute node.
4. On the Database service compute node, invoke SQL*Plus and execute the CREATE
PLUGGABLE DATABASE command to plug the database into the CDB.
For more information, see "Creating a PDB by Plugging an Unplugged PDB into a CDB" in
Oracle Database Administrator's Guide for Release 12.2 or 12.1.
Unplugging/Plugging Non-CDB
You can use this method only if the on-premises platform is little endian, and the on-premises
database and the Oracle Cloud Infrastructure Database database have compatible database
character sets and national character sets.
You can use the unplug/plug method to migrate an Oracle Database 12c non-CDB database to
a PDB in an Oracle Database 12c database on a Database service database deployment. This

CHAPTER 8 Database
method provides a way to consolidate several non-CDB databases into a single Oracle
Database 12c multitenant database on the Database service.
To migrate an Oracle Database 12c non-CDB database to the Oracle Database 12c database on
a Database service deployment using the plug/unplug method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and set the on-premises database
to READ ONLY mode.
2. On the on-premises database host, execute the DBMS_PDB.DESCRIBE procedure to
generate an XML file containing the list of datafiles that will be plugged in on the cloud
database.
3. Use a secure copy utility to transfer the XML file and the datafiles to the Database
service compute node.
4. On the Database service compute node, invoke SQL*Plus and execute the CREATE
PLUGGABLE DATABASE command to plug the database into the CDB.
5. On the Database service compute node, execute the $ORACLE_
HOME/rdbms/admin/noncdb_to_pdb.sql script to delete unnecessary metadata from
the SYSTEM tablespace of the new PDB.
database back to READ WRITE mode.
For more information, see "Creating a PDB Using a Non-CDB" in Oracle Database
Troubleshooting
These topics cover some common issues you might run into and how to address them.
Backup Failures

CHAPTER 9 DNS
This chapter explains how to create and manage DNS zones.
Overview of the DNS Service

The Oracle Cloud Infrastructure Domain Name System (DNS) service lets you create and
manage your DNS zones. You can create zones, add records to zones, and allow Oracle Cloud
Infrastructure's edge network to handle your domain's DNS queries. You can also view query
reports for your zones with varying degrees of granularity.
See Supported DNS Resource Record Types for additional information.
DNS Service Components

The following list describes the components used to build a DNS zone and make it accessible
from the internet.
DOMAIN
Domain names identify a specific location or group of locations on the Internet as a whole.
A common definition of "domain" is the complete portion of the DNS tree that has been
delegated to a user's control. For example, example.com or oracle.com.
ZONE
A zone is a portion of the DNS namespace. A Start of Authority record (SOA) defines a
zone. A zone contains all labels underneath itself in the tree, unless otherwise specified.
LABEL
Labels are prepended to the zone name, separated by a period, to form the name of a
subdomain. For example, the "www" section of www.example.com or the "docs" and "us-
ashburn-1" sections of docs.us-ashburn-1.oraclecloud.com are labels. Records are
associated with these domains.

CHAPTER 9 DNS
CHILD ZONE
Child zones are independent subdomains with their own Start of Authority and Name
Server (NS) records. The parent zone of a child zone must contain NS records that refer
DNS queries to the name servers responsible for the child zone. Each subsequent child
zone creates another link in the delegation chain.
RESOURCE RECORDS
A record contains specific domain information for a zone. Each record type contains
information called record data (RDATA). For example, the RDATA of an A or AAAA record
contains an IP address for a domain name, while MX records contain information about
the mail server for a domain.
DELEGATION
The name servers where your DNS is hosted and managed.
Ways to Access the DNS Service

guide.
To access the Console, you must use a supported browser. You can use the Console link at the
top of this page to go to the sign-in page. Enter your tenancy, user name, and your password.


CHAPTER 9 DNS
using.
DNS Service Capabilities and Limits

The Oracle Cloud Infrastructure DNS service is limited to 1000 zones per account and 25,000
records per zone. No SDK or CLI is available for the Oracle Cloud Infrastructure DNS service
currently.

details about policies for DNS, see Details for the DNS Service.
Managing DNS Service Zones

The Oracle Cloud Infrastructure DNS service enables you to manage zones and view zone
reports within the Console.

CHAPTER 9 DNS
Using the Console
Managing Zones and Zone Records
To add a zone
1. Open the Console, click Networking, and then click DNS.
2. Click Add Zone.
3. In the Add Zone dialog box, choose one of the following methods:
l Manual - Enter the following:
o Zone Name: Enter the name of a zone you want to create.
o Zone Type: If you want to control the zone contents directly within OCI,
select Primary. If you want OCI to pull zone contents from an external
server, select Secondary and enter your Zone Master Server IP
address.
l Import - Drag and drop, select, or paste a valid zone file into the Import Zone
File window. The zone is imported as a Primary zone.
4. Click Continue.
5. Click Publish Changes.
6. In the confirmation dialog box, click OK.
The system creates and publishes the zone, complete with the necessary SOA and NS records.
For more information on adding a record to your zone, see Add a Zone Record.
To update a secondary zone


CHAPTER 9 DNS
2. Click the Actions icon ( ) for the secondary zone you want to update.
Tip
You can use the Sort By list to sort zone names

alphanumerically in ascending or descending order.
3. Click Manage Master Servers. A list of Master Server IPs for the zone appears.
4. Click the Actions icon ( ) for the Master Server IP you want to update, and then
click Edit.
5. Make the needed changes, and then click Update.
6. (Optional) Click Add Master Server to add another Master Server IP address.
Tip
For OCI to transfer data from your zone, your

nameservers must be able to accept a transfer
request from the following IP addresses:
208.78.68.65, 204.13.249.65, 2600:2001:0:1::65,
2600:2003:0:1::65
To delete a zone
Warning
Deletion permanently removes a zone from your DNS

CHAPTER 9 DNS
service.

2. Click the Actions icon ( ) for the zone you want to delete.
3. Click Delete.
4. Click OK when prompted. The zone is staged for deletion.
5. Click Publish Changes to delete the zone.
To add a zone record
Tip
There are many record types you can add to your zone,
depending on your goals for the zone and its DNS
management.

2. Click the Actions icon ( ) for the zone in which you want to add a record.
Tip

3. Click Manage Records. A list of records for the zone appears.

4. Click Add Record.

CHAPTER 9 DNS
5. In the Add Record dialog box, select a record type from the drop-down list, and then
enter the information for the record. For more information about record types, see
Supported DNS Resource Record Types.
6. (Optional) Click the Add Another Record check box to add multiple records in
succession.
7. Click Add.
8. Once your records have been added, click Publish Changes.
To update a zone record
Note
Protected Records
You can change various components of the records

within your zones, such as time-to-live (TTL) and
relevant RDATA. However, some records contain
information that cannot be changed. A lock symbol
indicates a protected record. You can attempt changes
to such records through the Actions menu, but the
system might not permit updates to some fields.

CHAPTER 9 DNS

2. Click the Actions icon ( ) for the zone in which you want to update a record.
Tip


4. To help find a record, you can use the following filter options:
l Enter the name of the record's domain in the Search Records field.
l To find unpublished records, select the Staged check box.
l To find published records, select the Not Staged check box.
l Select the record type from the Record Type drop-down list.
5. Click the Actions icon ( ) for the record you want to update, and then click Edit.
6. Make the needed changes, and then click Update.
Reverting Changes Before Publishing
You can revert records to their current published state before you publish changes. Once a
record has been published, it cannot be reverted.
1. Click the Actions icon ( ) for the record you want to revert, and then click Revert.
A confirmation message shows the changes to discard.
2. Click Discard to discard the changes.

CHAPTER 9 DNS
To delete a zone record

2. Click the Actions icon ( ) for the zone from which you want to delete a record.
Tip


4. Click the Actions icon ( ) for the record you want to delete, and then click Delete
Record.
5. Click OK when prompted.
To delegate a zone
To make your Oracle Cloud Infrastructure hosted zone accessible through the internet, you
must delegate your domain with your domain's registrar.

2. Click the Actions icon ( ) for the zone you want to delegate.
4. Use the Record Type filter to locate the NS records for your zone.
5. Note the name servers in the RDATA field within each NS record.
6. You can use the noted name servers to change your domain's DNS delegation. Refer to
your registrar's documentation for instructions.

CHAPTER 9 DNS
Using the API

Use the following operations to manage your DNS zones:
l GetZone
l ListZones
l CreateZone
l UpdateZone
l DeleteZone
l PatchZoneRecords (add or delete records)
l UpdateZoneRecords
Viewing DNS Reports
DNS Reports show how much DNS traffic your zones have received for up to the past 90 days.
Use DNS query counts by zone to understand the distribution of queries or ensure that new
zones and configurations work correctly. DNS query counts include the last 30 days by
default. Use the Date Range option to view query counts for different periods of time.
To view DNS reports, open the Console, click Networking, and then click DNS Reporting.
DNS Reports provide the following information:
l Total Queries - The sum of all queries across all zones for the selected date range.
l Zone Name - The name of the zone that received queries in the selected date range.
l Query Count - The number of DNS queries received by your zones.
l Query Percentage (%) - The percentage of total queries for each zone.

CHAPTER 9 DNS
To view DNS Reports data for a specific date or range, select a date option from the Time
Range drop-down list. Options include:
l Last 30 Days - (Default) Displays data for the last 30 days.

l Single Day - Select a date from the calendar, and the click Apply.
l Custom Date Range - Select a start date and an end date within the past 90 days, and
then click Apply. Calendar dates are based on Coordinated Universal Time (UTC).
Supported DNS Resource Record Types

The Oracle Cloud Infrastructure DNS service supports many resource record types. The
following list provides a brief explanation of the purpose of each supported record type. The
RFC links direct you to further information about the record types and data structure.
A
An address record used to point a hostname to an IPv4 address. For more information
about A records, see RFC 1035.
AAAA
An address record used point a hostname at an IPv6 address. For more information about
AAAA records, see RFC 3596.
ALIAS
A private pseudo-record that allows CNAME functionality at the apex of a zone. You can
view and read ALIAS records in Oracle Cloud Infrastructure DNS, but you cannot create
them.
CAA
A Certification Authority Authorization record allows a domain name holder to specify one
or more Certification Authorities authorized to issue certificates for that domain. For more
information about CAA records, see RFC 6844.

CHAPTER 9 DNS
CDNSKEY
A Child DNSKEY moves a CDNSSEC key from a child zone to a parent zone. The
information provided in this record must match the CDNSKEY information for your domain
at your other DNS provider. This record is automatically created if you enable DNSSEC on
a primary zone in Oracle Cloud Infrastructure DNS. For more information about CDNSKEY,
see RFC 7344.
CDS
A Child Delegation Signer record is a child copy of a DS record, for transfer to a parent
zone. For more information about CDS records, see RFC 7344.
CERT
A Certificate record stores public key certificates and related certificate revocation lists in
the DNS. For more information about CERT records, see RFC 2538 and RFC 4398.
CNAME
A Canonical Name record identifies the canonical name for a domain. For more
information about CNAME records, see RFC 1035.
CSYNC
A Child-to-Parent Synchronization record syncs records from a child zone to a parent
zone. For more information about CNAME records, see RFC 7477.
DHCID
A DHCP identifier record provides a way to store DHCP client identifiers in the DNS to
eliminate potential hostname conflicts within a zone. For more information about DHCID,
see RFC 4701.
DKIM
A Domain Keys Identified Mail is a special TXT record set up specifically to supply a public
key used to authenticate arriving mail for a domain. For more information about DKIM
records, see RFC 6376.

CHAPTER 9 DNS
DNAME
A Delegation Name record has similar behavior to a CNAME record, but allows you to map
an entire subtree beneath a label to another domain. For more information about DNAME
records, see RFC 6672.
DNSKEY
A DNS Key record documents public keys used for DNSSEC. The information in this record
must match the DNSKEY information for your domain at your other DNS provider. For
more information about DNSKEY records, see RFC 4034.
DS
A Delegation Signer record resides at the top-level domain and points to a child zone's
DNSKEY record. DS records are created when DNSSEC security authentication is added to
the zone. For more information about DS records, see RFC 4034.
IPSECKEY
An IPSec Key record stores public keys for a host, network, or application to connect to IP
security (IPSec) systems. For more information on IPSECKEY records, see RFC 4025.
KEY
A Key record stores a public key that is associated with a domain name. Currently only
used by SIG and TKEY records. IPSECKEY and DNSKEY have replaced key for use in IPSec
and DNSSEC, respectively. For more information about KEY records, see RFC 4025.
KX
A Key Exchanger record identifies a key management agent for the associated domain
name with some cryptographic systems (not including DNSSEC). For more information
about KX records, see RFC 2230.
LOC
A Location record stores geographic location data of computers, subnets, and networks
within the DNS. For more information about LOC records, see RFC 1876.

CHAPTER 9 DNS
MX
A Mail Exchanger record defines the mail server accepting mail for a domain. MX records
must not point to a CNAME or IP address. For more information about MX records, see
RFC 1035.
NS
A Nameserver record lists the authoritative nameservers for a zone. Oracle Cloud
Infrastructure DNS automatically generates NS records at the apex of each new primary
zone. For more information about NS records, see RFC 1035.
PTR
A Pointer record reverse maps an IP address to a hostname. This behavior is the opposite
of an A Record, which forward maps a hostname to an IP address. PTR records are
commonly found in reverse DNS zones. For more information about PTR records, see RFC
1035.
PX
A resource record used in X.400 mapping protocols. For more information about PX
records, see RFC 822 and RFC 2163.
SOA
A Start of Authority record specifies authoritative information about a DNS zone,

including:
l The primary nameserver.

l The email of the domain administrator.
l The domain serial number.
l Several timers relating to refreshing the zone.
The Oracle Cloud Infrastructure DNS automatically generates an SOA record when a zone
is created. For more information about SOA records, see RFC 1035.

CHAPTER 9 DNS
SPF
A Sender Policy Framework record is a special TXT record used to store data designed to
detect email spoofing. For more information about SPF records, see RFC 4408.
SRV
A Service Locator record allows administrators to use several servers for a single domain.
For more information about SRV records, see RFC 2782.
SSHFP
An SSH Public Key Fingerprint record publishes SSH public host key fingerprints using the
DNS. For more information about SSHFP records, see RFC 6594.
TLSA
A Transport Layer Security Authentication record associates a TLS server certificate, or
public key, with the domain name where the record is found. This relationship is called a
TLSA certificate association. For more information about TLSA records, see RFC 6698.
TXT
A Text record holds descriptive, human readable text, and can also include non-human
readable content for specific uses. It is commonly used for SPF records and DKIM records
that require non-human readable text items. For more information about TXT records, see
RFC 1035.

CHAPTER 10 Email Delivery
This chapter explains how to send large volume email.
Overview of the Email Delivery Service

Oracle Cloud Infrastructure Email Delivery is an email sending service that provides a fast
and reliable managed solution for sending high-volume emails that need to reach your
recipients' inbox. Email Delivery provides the tools necessary to send application-generated
email for mission-critical communications such as receipts, fraud detection alerts, multi-
factor identity verification, and password resets.
Oracle Cloud Infrastructure's Email Deliverability team manages the platform using key
deliverability metrics to ensure the best sending reputation possible for your emails.
The following items are provided to you when you send email using the Email Delivery
service:
l Unique mailbox provider SMTP configurations

l Bounce collection
l User complaint collection
l Email authentication standards
l Deliverability performance
Email Delivery Service Components

Email Delivery uses the components described in this section.
APPROVED SENDERS
An Approved Sender is a resource that enables Email Delivery to send email with a
matching "From" address. An approved sender is associated with a compartment and only
exists in the region where the approved sender was configured. For example, if you

create an approved sender in the Phoenix (PHX) region, you cannot send email through
the Ashburn (IAD) region.
SUPPRESSION LIST
The Suppression List is included on your Email Delivery console user interface and from
the API. Email Delivery automatically adds email addresses with bounce codes showing
permanent failures or user complaints to the suppression list to protect your sender
reputation. Email Delivery will not send any messages to these recipients in the future.
Reasons for suppression currently include:
Complaints
Hard bounces
Repetitive soft bounces
Manual entries
List-unsubscribe requests
SPF AUTHENTICATION
Sender Policy Framework (SPF) is used by email receivers to detect email spoofing. Using
SPF, an email receiver can check if the Internet Protocol (IP) is explicitly authorized to
send for that domain.
SPF is implemented by publishing a special TXT record to a domain's DNS records. The
TXT record declares which hosts are allowed to send mail on behalf of this domain.
Receiving mail servers check the SPF records of sending domains to verify that the
email's source IP address is authorized to send from that domain. Without SPF, a spam or
phishing email can be “spoofed” to appear that the email comes from a legitimate domain.
Domains that implement SPF are much more likely to block emails attempting to spoof
your domain.
For an overview of how SPF works, see Sender Policy Framework. For details on SPF
record syntax, see SPF Record Syntax.


top of this page to go to the sign-in page. You are prompted to enter your cloud tenant, your
user name, and your password. For general information about using the API, see About the
API.

using.
Email Delivery Service Capabilities and Limits

New accounts are limited to:
l A volume of 2,000 emails a day.

l Messages up to 2 MB, inclusive of message headers, body, and attachments.
l 2,000 approved senders.

l Each user is limited to a maximum of two SMTP credentials.

l Sending rates are limited to five messages per second.
l Inline attachments.
Contact Oracle Support if limit adjustments are needed.

details about policies for Email Delivery, see Details for the Email Service.
Getting Started with Email Delivery

The Oracle Cloud Infrastructure enables you to set up the Email Delivery service within the
Console.
To begin sending email with Email Delivery, complete the following steps:
1. Generate SMTP credentials for a user.

2. Create an approved sender.
3. Configure SPF.
4. Configure the SMTP connection.
Generate SMTP Credentials for a User

Simple Mail Transfer Protocol (SMTP) credentials are necessary to send email through Email
Delivery. Each user is limited to a maximum of two SMTP credentials. If more than two are

required, SMTP credentials must be generated on other existing users or more users must be
created.
A security best practice is to generate SMTP credentials for a new user instead of your
Console user that already has permissions assigned to it. For detailed instructions on creating
a user, see Adding Users. The new user must be assigned to a group with permissions to
manage approved-senders and suppressions. For example:
Allow group <group name> to use approved-senders in compartment <compartment name>
Using the Console
To generate SMTP credentials for a user

1. Open the Console, click Identity, and then click Users. Locate the user in the list that
has permissions to manage email, and then click the user's name to view the details.
Tip
If your user does not have permissions to view or

create users, you can create SMTP credentials
under your user. In the top-right corner of the
Console, click your user's name, and then click
User Settings.
2. Click SMTP Credentials.

3. Click Generate SMTP Credentials.
4. Enter a Description of the SMTP Credentials in the dialog box.
5. Click Generate SMTP Credentials. A user name and password is displayed.
6. Copy the user name and password for your records and click Close.

Managing Approved Senders

You must set up an approved sender for all “From:” addresses sending mail via Oracle Cloud
Infrastructure or mail will be rejected. An approved sender is associated with a compartment
and only exists in the region where the approved sender was configured. That is, if you create
an approved sender in the Phoenix (PHX) region, you cannot send email through the Ashburn
(IAD) region.
Using the Console
To create an approved sender

1. Open the Console and then click Email. Ensure that you are in the correct compartment.
Your user must be in a group with permissions to manage approved-senders in this
compartment.
2. Click Create Approved Sender within the Approved Senders view.
3. Enter the email address you want to list as an approved sender in the Add Sender
dialog box.
4. Click Add. The email address is added to your Approved Senders list.
Tip
Approved senders are unique to tenancies. If an attempt

is made to create a duplicate approved sender within a
tenancy, the service will return a 409 Conflict error.
To delete an approved sender

1. Open the Console and then click Email.
2. Select the checkbox for the approved sender you want to delete and then click Delete.

3. In the confirmation dialog box, click OK. The email address is removed from the
Approved Senders list.
Using the API

Use the following operations to manage your approved senders:
l CreateSender
l GetSender
l ListSenders
l DeleteSender
Configure SPF
The Approved Senders section within the Console provides validation of an SPF record for
each of your approved senders.
Using the Console
To configure SPF
1. Open the Console and then click Email.
2. Select the checkbox for the approved sender you want to view SPF details for and click
View SPF.

Tip
You can search for an approved sender by using the

Search field. Addresses can be sorted
alphanumerically or by creation date in ascending
or descending order.
3. The Manage SPF dialog box appears indicating whether an SPF record for the approved
sender exists.
l If your domain does not currently have an SPF record, the information necessary
to add an SPF record in your DNS setup is displayed. See Managing DNS Service
Zones for instructions on adding a zone record in Oracle Cloud Infrastructure. If
your DNS setup resides with another provider, please reference their
documentation for adding a TXT record to your domain.
o In your DNS setup, create a TXT record and paste the following information
from the dialog box into the record: v=spf1
include:spf.oracleemaildelivery.com -all
l If your domain currently has an SPF record, add the following information to the
record to add Oracle Cloud Infrastructure Email Delivery:
include:spf.oracleemaildelivery.com
Configure SMTP Connection

Set up and test your SMTP connection using an SMTP library or product such as Postfix or
SendMail to send email through Oracle Cloud Infrastructure Email Delivery.
To access SMTP sending information to configure the connection in your system, open the
Console, click Email, and then click Configurations. The following information is displayed:
l Manage SMTP Credentials: Access your user credentials. Use the SMTP user
credentials (in plain text) when validating your connection.
l Server Name: The Email Delivery service hostname.

l Port: Email Delivery supports TLS on port 25 or 587.

l Use Transport Layer Security (TLS): This field indicates if TLS, the standard means
of performing encryption in transit for email, is being used. Customers must encrypt
email while it is in transit to the Oracle Cloud Infrastructure Email Delivery service.
Encrypted emails are protected from being read during transit.
Managing the Suppression List

Manually add an email address to the suppression list to prevent it from being part of your
sending list.
Users are required to have correct permissions to manage the suppression list. Currently,
identity policies for suppression must be at the tenant level (not at the compartment level).
The following is an example of the permission policy statement.
Allow group <group name> to manage suppressions in tenancy
Suppressions are stored at the tenancy level. Therefore any request requiring a
compartmentId must provide the tenancyId as the compartmentId. For example:
Allow group <ordinary users> to inspect approved-senders in tenancy
Allow group <power users> to read approved-senders in tenancy
Allow group <sender admins> to manage approved-senders in tenancy
Allow user <mail user> to use approved-senders in tenancy where target.approved-sender.senderId =
<senderId>
Allow group <ordinary users> to inspect suppressions in tenancy

Allow group <power users> to read suppressions in tenancy
Allow group <sender admins> to manage suppressions in tenancy
Using the Console
To manually add an email address to the suppression list

1. Open the Console, click Email, and then click Suppression List.
2. Click Add Suppression.

3. In the Add Suppression dialog box, enter the email address.

4. Click Add. The email address is added to the Suppression List.
To delete an email address from the suppression list

1. Open the Console, click Email, and then click Suppression List.
2. Select the checkbox for the email address you want to delete and then click Delete.
Tip
You can search for an email address by using the

Search field. Addresses can be sorted
alphanumerically or by creation date in ascending
or descending order.
3. In the confirmation dialog box, click OK. The email address is removed from the
Suppression List.
Using the API

Use the following operations to manage your suppressions:
l CreateSuppression
l GetSuppression
l ListSuppressions
l DeleteSuppression

Deliverability Best Practices

Deliverability Best Practices help you to learn and manage the habits that affect your sending
reputation. These six recommendations can help lower your email bounce rate, stay off
blacklists, lower your complaint rate, and improve your email sender reputation.
Implement an Opt-in Process

An opt-in process is a method for your users to subscribe to your mailing list, which gives you
permission to send messages. Only send messages to subscribers who have opted-in to your
mailing list. There are two types of opt-in procedures.
l Single opt-in (unconfirmed): A user provides their email address and gives
permission to receive relevant messages. Once the address is provided, messages can
be sent without confirming the email address belongs to the user who provided it.
l Double opt-in (confirmed): A user provides their email address, but before the first
mailing, a confirmation email is sent to the account owner. The email requires action
from the account owner to confirm that future messages are wanted. An account can be
verified by having the owner click a link for reply to the email. The confirmation email
ensures that the address was not added to a third-party mailing list without consent.
Purge Unengaged Users

Remove unengaged users by implementing a process. If a recipient is not engaging with your
mail by either opening or clicking the email, this might be an indication that the email account
is not in use or that the recipient is no longer interested in your content. If the recipient does
not use the email account, eventually the mailbox provider terminates the account or
transforms the account into a spam trap. Remove recipients who have not engaged with your
email in a time frame defined by your business model. Purging unengaged users helps your
deliverability by increasing your user engagement rate.
Review Your Subscriber List

When reviewing your subscriber list, keep these things in mind:

l Eliminate duplicate addresses before sending. If addresses that do not exist are mailed
to multiple times, your hard bounce rate could be inflated.
l Ensure that a previous suppression list (possibly from another email service provider)
was not accidentally included.
l Verify that subscribers have opted-in. Do not send to an old list that you found.
l Restrict users from uploading their email client’s contact list in a “select all” fashion.
Forcing users to select addresses individually prevents users from accidentally including
potentially out of date or expired addresses.
Evaluate Your Sending Frequency

Sending too many emails in a short time might aggravate recipients, causing the recipients to
mark your messages as spam. This is called list fatigue. Ensure that your message cadence
aligns with the expected frequency of your content. Reducing frequency might reduce spam
complaints. Ensure that your content is relevant to your subscribers. Keep your email
messages consistent to your audience. A person who subscribed to a list for coupon updates
might not want regular emails about auto loan finance rates. These unexpected messages are
likely to be marked as spam, which decreases your sender reputation.
Easily Accessible Unsubscribe URL

Unsubscribing helps your inbox success by sending only to recipients that engage by opening
or clicking. When people complain, your sending reputation is harmed. Make it easy for
recipients to be removed from the list. Do not hide the unsubscribe URL at the bottom of the
message. A small percentage of users scroll to the bottom of the email and search for a small
URL. Most users mark the email as spam.
Canadian Anti-Spam Law (CASL) Guide

Canada's Anti-Spam Law (CASL) is one of the best guides to ensuring your compliance with
the law, users’ desire, and the intended filtering that most mailbox providers use. If you are a
Canadian email sender or you send email to Canadian residents, you must comply with CASL.
The following information is intended to help provide you with some guidance for complying

with CASL. This article does not constitute legal advice, nor is it intended supplement or
otherwise affect your rights or obligations under your service agreement with Oracle,
including your obligations under Oracle’s Acceptable Use Policy. If you have questions about
CASL or the legality of your sending practices, we encourage you to speak with an attorney
who specializes in that subject matter.
What is covered by CASL?
CASL and its related regulations apply to any “commercial electronic message” sent from or
to Canadian computers and devices in Canada. Electronic messages that are merely routed
through Canadian computer systems are not subject to CASL.
A “commercial electronic message” is any message that:
l Is in an electronic format, including emails, instant messages, text messages, and

some social media communications.
l Is sent to an electronic address, including email addresses, instant message accounts,
phone accounts, and social media accounts; and
l Contains a message encouraging recipients to take part in some type of commercial
activity, including the promotion of products, services, people/personas, companies, or
organizations.
Are there any types of messages that are exempt from CASL?
These types of electronic messages are exempt from CASL for various reasons.
l Messages to family or a person with established personal relationship.

l Messages to an employee, consultant, or person associated with your business.
l Responses to a current customer, or someone who has inquired in the last six months.
l Messages that will be opened or accessed in a foreign country, including the U.S.,
China, and most of Europe.
l Messages sent on behalf of a charity or political organization for the purposes of raising
funds or soliciting contributions.
l Messages attempting to enforce a legal right or court order.

l Messages that provide warranty, recall, safety, or security information about a product
or service purchased by the recipient.
l Messages that provide information about a purchase, subscription, membership,
account, loan, or other ongoing relationship, including delivery of product updates or
upgrades.
l A single message to a recipient without an existing relationship based on a referral. The
full name of the referring person must be disclosed in the message. The referrer might
be family or have another relationship with the person to whom you are sending.
If your message does not meet one of these criteria, consent is required under CASL. Not all
of the previous messages listed are permitted under the Oracle Cloud Hosting and Delivery
Policy.
What is “express consent”?
Under CASL, “express consent” means a written or oral agreement to receive specific types of
messages. For example, “You want to receive monthly newsletters and weekly discount
notifications from Oracle”.
Express consent is only valid if your request for consent clearly and simply describes the
following information:
l Your purpose in obtaining consent.

l A description of messages you will be sending.
l The name and contact information (physical mailing address and telephone number,
email address, or website URL) of the requestor.
l A statement that the recipient can unsubscribe at any time.
The requestor can be you or someone for whom you are asking. If you are requesting consent
on behalf of a client, the name and contact information of the client must be included with the
consent request.
What is “implied consent”?
Under CASL, you can only obtain implied consent when certain circumstances exist, including
when:

l A recipient has purchased a product, service or made another business deal, contract,
or membership with your organization in the last 24 months.
l You are a registered charity or political organization, and the recipient has made a
donation or gift, has volunteered, or attended a meeting organized by you.
l A professional message is sent to someone whose email address was given to you, or is
conspicuously published, and who has not published or told you that unsolicited
messages are not wanted.
What type of consent is required?
After July 1, 2017, you can only send to recipients with express consent or whose implied
consent is valid under CASL.
Some additional requirements
In addition to understanding what qualifies as CASL-regulated message, and what type of

consent is needed, there are a few other details to keep in mind.
l Retention of a record of consent confirmations is required.

l When requesting consent, checkboxes cannot be pre-filled to suggest consent. Each
subscriber must check the box themselves for consent to be valid.
l All messages sent must include the following:
o your name
o the person on whose behalf you are sending (if any)
o your physical mailing address and telephone number
o your email address or website URL
l All messages sent after consent must also include an unsubscribe mechanism, and
unsubscribes must be processed within ten days.
Where can I find more information on CASL?
The full text of the law can be found on the website for the Canadian Justice Department. The
Canadian Radio and Telecommunications Commission has also set up an FAQ page and some
guidelines for obtaining consent. If you have any questions, we encourage you to contact an
attorney who is familiar with the law.

Oracle Cloud Hosting and Delivery Policy
Often, the Oracle Cloud Hosting and Delivery Policy is more stringent than CASL
requirements. It is important that you review Oracle policies before using the service.

CHAPTER 11 File Storage

This chapter explains how to create file systems, how to manage them, and how to mount
them to write files.
Overview of File Storage

Oracle Cloud Infrastructure File Storage Service provides a durable, scalable, distributed,
enterprise-grade network file system. You can connect to a File Storage Service file system
from any bare metal, virtual machine, or container instance in your Virtual Cloud Network
(VCN). You can also access a file system from outside the VCN using Oracle Cloud
Infrastructure FastConnect and Internet Protocol security (IPSec) virtual private network
(VPN).
Large Compute clusters of thousands of instances can use File Storage Service for high-
performance shared storage. Storage provisioning is fully managed and automatic as your
use scales from a single byte to exabytes without upfront provisioning. You have redundant
storage for resilient data protection.
File Storage Service supports the Network File System version 3.0 (NFSv3) protocol. The
service supports the Network Lock Manager (NLM) protocol for file locking functionality.
Use File Storage Service when your application or workload includes big data and analytics,
media processing, or content management, and you require Portable Operating System
Interface (POSIX)-compliant file system access semantics and concurrently-accessible
storage. File Storage Service is designed to meet the needs of applications and users that
need an enterprise file system across a wide range of use cases, including the following:
l Enterprise applications that need shared files, such as Oracle E-Business Suite (EBS)
l Any Oracle application that uses NFSv3 protocol, including EBS, and others
l Analytic applications and Hadoop environments, where you currently use a local NFS
file system

l Microservices-based architectures, where you need persistent storage for container

environments
l Transactional file workloads, databases, scale-out file workloads, and high-
performance computing (HPC)
l Graphics, where you process video data and use a file system to store transcoded data
or stream data
l General purpose file systems, for storing unstructured and structured data
File Systems Concepts

File Storage Service requires an understanding of the following concepts, including some that
pertain to Oracle Cloud Infrastructure Networking:
MOUNT TARGET
An NFS endpoint that lives in a subnet of your choice and is highly available. It provides
the IP address or DNS name that is used in the mount command when connecting NFS
clients to File Storage Service. By default, you can create two mount targets per account
per availability domain, but you can request an increase. See Service Limits for a list of
applicable limits and instructions for requesting a limit increase.
EXPORT PATH
A path that is specified when a file system is associated with a mount target. It uniquely
identifies the file system within the mount target, letting you associate up to 100 file
systems to a single mount target. It is appended to the mount target IP address, and used
to mount the file system. This path is unrelated to any path within the file system itself, or
the client mount point path.
In the following mount command example,
10.0.0.6 is the mount target IP address.
/example/path is the export path that was specified when the file system was associated
with a mount target at creation.

/mnt/mountpointA is a path to a locally accessible directory on which the external file

system is logically attached (mounted).
sudo mount 10.0.0.6:/example/path /mnt/mountpointA
File Storage System adds an export that pairs the file system's Oracle Cloud Identifier
(OCID) and path.
See Paths in File Systems for more information.
Note
To simplify file system management, exports and

export sets are managed through the Console by File
Storage Service. More advanced configuration options
for exports and export sets are available in the
Command Line Interface (CLI) and API.
VIRTUAL CLOUD NETWORK (VCN)

A private network that you set up in the Oracle data centers, with firewall rules and
specific types of communication gateways that you can choose to use. A VCN covers a
single, contiguous IPv4 CIDR block of your choice. For more information about VCNs, see
VCNs and Subnets in the Oracle Cloud Infrastructure Networking documentation.
SUBNETS
Subdivisions you define in a VCN (for example, 10.0.0.0/24 and 10.0.1.0/24). Subnets
contain virtual network interface cards (VNICs), which attach to instances. Each subnet
exists in a single availability domain and consists of a contiguous range of IP addresses
that do not overlap with other subnets in the VCN. Each mount target has an address on a
subnet of your choice. For more information about subnets, see VCNs and Subnets in the
Oracle Cloud Infrastructure Networking documentation.

SECURITY LISTS
Virtual firewall rules for your VCN. Your VCN comes with a default security list, and you
can add more. These security lists provide ingress and egress rules that specify the types
of traffic allowed in and out of the instances. You can choose whether a given rule is
stateful or stateless. Security list rules must be set up so that clients can connect to file
system mount targets. For more information about security lists, see Security Lists in the
the Oracle Cloud Infrastructure Networking documentation. See About Security for more
information on how different types of security work together in your file system.
SNAPSHOTS
Snapshots provide a consistent, point-in-time view of your file system, and you can take
as many snapshots as you need. You pay only for the storage used by your data and
metadata, including storage capacity used by snapshots. Each snapshot reflects only data
that changed from the previous snapshot
Encryption
File Storage Service uses AES-128 encryption to encrypt all file systems by default.
Encryption happens at the file level. Data and metadata are encrypted at rest rather than
while in transit. You cannot turn off encryption.
File Storage Service's key management system relies on one master key for each availability
domain which rotates periodically. The service also uses one file system master key for each
file system which is generated when it creates the file system. Lastly, the service generates a
file key when a file is added to the file system.
Data Transfers
FastConnect offers you the ability to accelerate data transfers. You can leverage the
integration between FastConnect and File Storage Service to perform initial data migration,
workflow data transfers for large files, and disaster recovery scenarios between two regions,
among other things.

How File Storage Permissions Work

File Storage Service resources include file systems, mount targets, and export sets.
UNIX user group and permission checking is performed at the file system layer. You use
Oracle Cloud Infrastructure Identity and Access Management (IAM) policy language to define
access to Oracle Cloud Infrastructure resources. You can consider exports and snapshots
subsidiary resources of export sets and file systems, respectively. As such, they do not need
their own permissions. Related resources include Oracle Cloud Infrastructure Compute
instances and Oracle Cloud Infrastructure Networking virtual cloud networks (VCNs).
Oracle Cloud Infrastructure users require resource permissions to create, delete, and manage
resources. Without the appropriate IAM permissions, you cannot export a file system through
a mount target. Until a file system has been exported, Compute instances can't mount it. For
more information about creating an IAM policy, see Let users create, manage, and delete file
systems.
If you have successfully exported a file system on a subnet, then you use Networking security
lists to control traffic to and from the subnet and, therefore, the mount target. Security lists
act as a virtual firewall, allowing only the network traffic you specify to and from the IP
addresses and port ranges configured in your ingress and egress rules. The security list you
create for the subnet lets hosts send and receive packets and mount the file system. If you
have firewalls on individual instances, use FastConnect, or use a virtual private network
(VPN), the settings for those might also impact security at the networking layer. For more
information about creating a security list for File Storage Service, see Managing File Systems.
See About Security for more information on how different types of security work together in
your file system.

You can use File Storage Service in all regions. For a list of supported regions, see Regions
and Availability Domains.
When you create a mount target for a file system, you can share it among local bare metal
and virtual Compute resources within a region. The service runs locally within each
availability domain. When you create a file system or mount target, you specify the

availability domain it is created in. Within an availability domain, File Storage Service uses
synchronous replication and high availability failover to keep your data safe and available.



using.
Limits on Your File Storage Components

increase.
About Security
There are three distinct and separate layers of security to consider when using OCI File
Storage service. Each layer has its own authorization entities and methods which are separate
from the other layers.
The Unix Authentication layer controls what users can do on the instance, such as installing
applications, creating directories, mounting external file systems to a local mount point, and
reading and writing files.
The IP Networking layer controls which instance IP Addresses or CIDR blocks can connect
to a host file system. It uses VCN security list rules to allow or deny traffic to the mount
target, and therefore access to any associated file system.
The OCI Policy layer uses policies to control what users can do within OCI, such as creating
instances, a VCN and its security rules, mount targets, and file systems.
This security Uses these... To control actions like...

layer...
Unix Unix users, file Mounting file systems, reading and writing files,
Authentication mode bits
IP Networking IP addresses, CIDR Connecting the client instance to the mount

blocks, security lists target.
Oracle Cloud OCI Users and Creating instances and VCNs. Creating, listing,
Infrastructure policies and associating file systems and mount targets.
(OCI)

Remember that users in UNIX aren’t the same as users in OCI - they’re not linked or
associated in any way. The OCI resource security layer doesn’t govern anything that happens
inside the file system, the UNIX security layer does. Conversely, the UNIX security layer
doesn’t govern creating file systems or mount targets in OCI.
IP networking allows you to use VCN security rules to block the appropriate ports from
specific IP addresses and CIDR blocks and restrict host access. However, this is on an ‘all or
nothing’ basis - the client either can or cannot access the mount target, and therefore all file
systems associated with it.
Creating File Systems

You can create a shared file system in the cloud using File Storage Service. When you use the
Console, creating a file system also creates a mount target that your Compute instances use
to access and write to the file system. Once a mount target is created, multiple file systems
can be associated with it. Using the API or the Command Line Interface (CLI), you can create
file systems and mount targets independently of each other.

For administrators: The policy in Let users create, manage, and delete file systems allows
users to create file systems.
Using the Console

Before you create a file system, you need at least one Virtual Cloud Network (VCN) in the
compartment. For more information, see VCNs and Subnets. You must configure security list

rules for the VCN subnet in which you are planning to create the file system mount target.
To configure security list rules for mount target traffic

Security list rules specify what type of traffic can enter and exit a mount target. You configure
security lists at the subnet level, but rules are enforced at the instance level. File systems
require you to configure rules for each port range they use. Therefore, you must set up a
stateful rule for each port range destination.
Create stateful ingress rules for TCP traffic associated with the following:
l Open Network Computing Remote Procedure Call (ONC RPC) rpcbind utility

l Network File System (NFS) protocol
l Network File System (MOUNT) protocol
l Network Lock Manager (NLM) protocol
1. Open the Console, click Networking, and then click Virtual Cloud Networks.
2. In the left-hand navigation, in the List Scope section, under Compartment, select the
compartment that contains the subnet to be associated with your file system.
3. Find the cloud network to be associated with your file system.
4. On the details page for the cloud network, click Security Lists, and then find the
security list used by the subnet to be associated with your file system.
5. On the details page of the security list, click Edit All Rules.
6. Add the following ingress rule for access of NFS and NLM traffic:
a. Specify that it's a stateful rule by leaving the checkbox clear. (For more
information about stateful and stateless rules, see Stateful vs. Stateless Rules).
By default, rules are stateful unless you specify otherwise.
b. To allow traffic from the subnet of the cloud network, click Source CIDR, and
then enter the CIDR block for the subnet.
c. Click IP Protocol, and then click TCP.

d. For ingress of NFS and NLM traffic, click Destination Port Range, and then
enter 2048-2050.
7. Click + Add Rule to add more rules. Make sure to delete any partially completed rules
by clicking the X next to the rule.
8. Repeat step 6 to create a second ingress rule allowing traffic to a Destination Port
Range of 111 for the NFS rpcbind utility.
9. When you're done, click Save Security List Rules.
Next, create the file system.
To create a file system

1. Open the Console, click Storage, and then click File Systems.
2. In the left-hand navigation, in the List Scope section, under Compartment, select a
compartment.
The Console displays a list of file systems that have already been created in the
compartment, if any.
3. Click Create File System.
4. In the Create File System dialog, under File System Information, click Name, and
then type a name for the file system.
5. In Availability Domain, click the name of the availability domain where you want to
create the file system, and then click Next.
Note
File systems are encrypted by default. You cannot

turn off encryption.

6. If you want to associate the file system with a mount target you already created, under
Mount Target Information, choose Select an Existing Mount Target. Choose the
Compartment and Mount Target from the list.
7. If you want to create a new mount target associated with this file system, choose
Create a New Mount Target.
Note
The mount target must be in the same availability

domain as the file system. You cannot change the
availability domain.
8. Click Virtual Cloud Network, and then select the VCN where you want to create the
mount target.
9. Click Subnet, and then select a subnet for the mount target.
Warning
Each mount target requires three internal IP

addresses in the subnet to function. Do not use /30
or smaller subnets for mount target creation
because they do not have sufficient available IP
addresses. Two of the IP addresses are used during
mount target creation. The third IP address must
remain available for the mount target to use for
high availability failover.
10. Optionally, to assign an IP address to the mount target, click IP Address and then
specify an unused, local, private IP address between 10.0.0.2 and 10.0.0.254.
11. Optionally, click Hostname and then specify a hostname you want to assign to the

mount target.
Note
File Storage Service constructs a fully qualified

domain name (FQDN) based on the hostname you
provide. You cannot change the FQDN in this dialog.
12. If you want to change the default path for the file system, click Path Name and specify
a new path name, including the forward slash (/). For example, /fss. This specifies the
mount path to the file system (relative to the mount target’s IP address or hostname).

Note
The path must start with a slash (/) followed by a

sequence of zero or more slash-separated
elements. For multiple file systems associated with
a single mount target, the path sequence for the
first file system cannot contain the complete path
element sequence of the second file system path
sequence. Paths cannot end in a slash. No path
element can be a period (.) or two periods in
sequence (..). Lastly, no path can exceed 255 bytes.
For example:
Examples:
Acceptable:
/example and /path
/example and /example2
Not Acceptable:
/example and /example/path
/ and /example
/example/
/example/path/../example1
13. Optionally, to specify the maximum free space reported to applications by the File
Storage Service, in Maximum Free Space (in GiB) choose Recommended Size or
Custom Size. Choose or enter the maximum free space amount.

Note
By default, File Storage Service currently reports 8

exabytes of available capacity for each file system
exported through the mount target. Some
applications fail to install because a capacity check
reports too much available capacity. Setting the
Maximum Free Space reported as available to a
value acceptable by your application prevents this
issue. Setting the maximum free space does
not limit the amount of data you can store.
14. Click Create File System.
The File Storage Service typically creates the file system within seconds. You can add files to
a file system immediately after it is created.
To add more file systems to a mount target

You can associate multiple file systems with a single mount target. Mount targets are only
accessible in the Console if they are associated with a file system. If you don't have a file
system, create one using the steps in To create a file system
compartment.
3. Find the file system you created, click the Actions icon ( ), and then click View
File System Details.
4. In Resources, click Mount Targets.

5. Click the name of the mount target you created.

6. Click Add File System.
7. If you want to associate this mount target with a file system you already created,
choose Select an Existing File System. Choose the Compartment and File
System from the list.
8. If you want to create a file system associated with this mount target, choose Create
File System. Choose the Compartment and enter a File System Name.
9. If you want to change the default path for the file system, click Path Name and specify
a new path name, including the forward slash (/). For example, /fss. This specifies the
mount path to the file system (relative to the mount target’s IP address or hostname).

Note

sequence of zero or more slash-separated
elements. For multiple file systems associated with
a single mount target, the path sequence for the
first file system cannot contain the complete path
element sequence of the second file system path
sequence. Paths cannot end in a slash. No path
element can be a period (.) or two periods in
sequence (..). Lastly, no path can exceed 255 bytes.
For example:
Examples:
Acceptable:
/example and /path
Not Acceptable:
/ and /example
/example/
10. Optionally, to specify the maximum free space reported to applications by File Storage
Service, in Maximum Free Space (in GiB) choose Recommended Size or Custom
Size. Choose or enter the maximum free space amount.

Note
By default, File Storage Service currently reports 8

exabytes of available capacity for each file system
exported through the mount target. Some
applications fail to install because a capacity check
reports too much available capacity. Setting the
Maximum Free Space reported as available to a
value acceptable by your application prevents this
issue. Setting the maximum free space does
not limit the amount of data you can store.
11. Click Add File System.
The file system is associated with the mount target.
Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI).
To create a file system

Open a command prompt and run oci fs file-system create to create a file system. For
example:
oci fs file-system create -availabilty-domain target_availability_domain --display-name "My File System"
--compartment-id target_compartment_id
The file system is created.
To create a mount target

You can create a mount target for file systems in a specified compartment and subnet. A file

system can only be associated with a mount target in the same availability domain.
Warning
Each mount target requires three internal IP addresses

in the subnet to function. Do not use /30 or smaller
subnets for mount target creation because they do not
have sufficient available IP addresses. Two of the IP
addresses are used during mount target creation. The
third IP address must remain available for the mount
target to use for high availability failover.
Open a command prompt and run oci fs mount-target create to create a mount target.
For example:
oci fs mount-target create --availabilty-domain target_availability domain --compartment-id target_
compartment_id --subnet-id subnet_OCID --display-name “My Mount Target”
To create an export
An export is a file system together with the path that can be used to mount it. Each export
resource belongs to one export set.
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set.
For example:
oci fs export create --export-set-id export_set_OCID --file-system-id file_system_OCID --path
"/pathname"

Note

sequence of zero or more slash-separated elements.
For any two export resources associated with the same
export set, the path sequence for the first export
resource can’t contain the complete path element
sequence of the second export sequence. Paths can't
end in a slash. No path element can be a period (.) or
two periods in sequence (..). Lastly, no path can exceed
255 bytes.
Examples:
Acceptable:
/example and /path
Not Acceptable:
/ and /example
/example/
Using the API

Use the following operations to create file systems:

l CreateFileSystem
l CreateMountTarget
l CreateExport
Managing File Systems

In File Storage Service, file systems are associated with a single compartment. When you
select a compartment, the Console displays all file systems in the compartment. You can also
see mount targets and snapshots associated with each file system. Mount targets are
associated with a Virtual Cloud Network (VCN) and represent the network access point for
Compute instances. You can access one file system through different mount targets.
Snapshots are a consistent, point-in-time view of your file systems. You can take as many
snapshots as you need. The compartment has policies that indicate what actions a user can
perform on a file system. UNIX permissions control what actions a user can take on the files
stored in the file system.
Actions you can take to manage a file system include:
l Viewing file system details

l Editing file system settings
l Deleting a file system
l Creating a snapshot
You can perform most administrative tasks for your file systems and mount targets using the
Console, Command Line Interface (CLI), or API. You can use the Console to list mount targets
exporting a specific file system. Use the API or CLI if you want to list all mount targets in a
compartment.
To mount a file system to write files, use a command window on Ubuntu and Linux systems.
For more information, see Mounting File Systems.


users to delete file systems.
Using the Console
To view file system details

File Storage Service displays a list of file systems in each compartment.
compartment.
3. To view information about a file system, find the file system, click the Actions icon (
), and then click View File System Details.
The Console displays metadata for the file system, mount targets associated with the
file system, and status for the file system and all mount targets.
To view mount target details

Each mount target associated with a file system has a details page where you can view and
edit information, including the maximum free space reported to applications.

compartment.
3. Find the file system associated to the mount target, click the Actions icon ( ), and
then click View File System Details.
5. Click the name of the mount target.
To delete a file system

You can permanently delete a file system.
Warning
You cannot undo this operation. Any data in a file

system will be permanently deleted with the file
system. You cannot recover a deleted file system.
compartment.
3. Find the file system you want to delete.
4. Click the Actions icon ( ), and then click View File System Details.
5. In Mount Targets, for each mount target listed, click the Actions icon ( ), and
then click Detach.
6. Click Delete.

The file system is deleted immediately.
Note
Deleting your last file system can result in an

"orphaned" mount target which is not easily visible in
the Console, and not accessible for deletion because it is
not associated with any file system.
To avoid this, delete mount targets before deleting the

last file system.
If you accidentally create an orphaned mount target,

see To delete an "orphan" mount target for more
information on how to delete these.
To delete a mount target

Mount targets are accessible for deletion in the Console only if they are associated with a file
system.
compartment.
3. Find a file system that is associated with the mount target you want to delete.
5. In Mount Targets, click the name of the mount target you want to delete.
6. Click Delete.

Note
If the mount target is not associated with a file system,

it cannot be deleted in the Console. Use one of the
following options:
l Associate the mount target with a file system,

then delete it. See the troubleshooting topic To
delete an "orphan" mount target for more
information.
l Delete the mount target Using the Command Line
Interface (CLI).
l Delete the mount target using the API.
To create a snapshot
compartment.
4. In Resources, click Snapshots.
5. Click Create Snapshot.
6. Fill out the required information:
l Name: Enter a name for the snapshot. It must be unique among all other
snapshots for this file system. The name can't be changed.
7. Click Create Snapshot.
The snapshot is accessible under the root directory of the file system at
.snapshot/name.

To restore a snapshot
Snapshots are created under the root folder of your file system, in a hidden directory named
.snapshot.
You can restore a file within the snapshot, or an entire snapshot using the cp command. Use
the -r option when restoring a snapshot that contains subdirectories.
For example:
cp -r .snapshot/snapshot_name/* destination_directory_name
Optionally, you can use rsync, tar, or another third-party tool that supports NFSv3 to copy
your data to another remote location.

For information about using the CLI, see Command Line Interface (CLI).
To list file systems

Open a command prompt and run oci fs file-system list to list all the file systems in a
specified availability domain and compartment.
For example:
oci fs file-system list --availabilty-domain target_availability_domain --compartment-id target_
compartment_id
To get a specific file system

Open a command prompt and run oci fs file-system get to retrieve information about a
specific file system.
For example:
oci fs file-system get --file-system-id file_system_OCID

To update a file system

Open a command prompt and run oci fs file-system update to update a specific file
system's information.
For example:
oci fs file-system update --file-system-id file_system_OCID --display-name "New File System Name"
To delete a file system

You can delete a file system that isn't referenced by any non-deleted export resources.
Deleting a file system also deletes all its snapshots.
Open a command prompt and run oci fs file-system delete to delete a file system.
For example:
oci fs file-system delete --file-system-id file_system_OCID
To create an export
An export is a file system together with the path that can be used to mount it. Each export
resource belongs to one export set.
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set.
For example:
oci fs export create --export-set-id export_set_OCID --file-system-id file_system_
OCID --path "/pathname"

Note
Export Path Names

sequence of zero or more slash-separated elements.
For any two export resources associated with the same
export set, the path sequence for the first export
resource can’t contain the complete path element
sequence of the second export sequence. Paths can't
end in a slash. No path element can be a period (.) or
two periods in sequence (..). Lastly, no path can exceed
255 bytes.
Examples:
Acceptable:
/example and /path
/example1 and /example2
Not Acceptable:
/ and /example
/example/
To list exports
Open a command prompt and run oci fs export list to list all exports in a specified
compartment.

For example:
oci fs export list --compartment-id target_compartment_id
To get a specific export

Open a command prompt and run oci fs export get to retrieve information about a specific
export.
For example:
oci fs export get --export-id export_OCID
To delete an export
Open a command prompt and run oci fs export delete to delete an export.
For example:
oci fs export delete --export-id export_OCID
Warning
When you delete an export, any file system referenced

by the export will no longer be accessible through its
associated mount target.
To list export sets

Open a command prompt and run oci fs export-set list to list all export sets in a
For example:
oci fs export-set list --availability-domain target_availability_domain --compartment-id target_
compartment_id

To get a specific export set

Open a command prompt and run oci fs export-set get to retrieve information about a
specific export set.
For example:
oci fs export-set get --export-set-id export_set_OCID
To update an export set

Open a command prompt and run oci fs export-set update to update a specific export
set's information.
For example:
oci fs export-set update --export-set-id export_set_OCID --display-name "New Export Set Name"
To create a mount target

You can create a mount target for file systems in a specified compartment and subnet. A file
system can only be associated with a mount target in the same availability domain.
Warning
Each mount target requires three internal IP addresses

in the subnet to function. Do not use /30 or smaller
subnets for mount target creation because they do not
have sufficient available IP addresses. Two of the IP
addresses are used during mount target creation. The
third IP address must remain available for the mount
target to use for high availability failover.
Open a command prompt and run oci fs mount-target create to create a mount target.
For example:

oci fs mount-target create --availabilty-domain target_availability domain --compartment-id target_

compartment_id --subnet-id subnet_OCID --display-name “My Mount Target”
To list mount targets

You cannot use the Console to list mount targets. Use the command-line interface or the API
from a host machine running a UNIX-style operating system.
Open a command prompt and run oci fs mount-target list to list all mount targets in a
For example:
oci fs mount-target list --availabilty-domain target_availability domain --compartment-id target_
compartment_id
To get a specific mount target

Open a command prompt and run oci fs mount-target get to retrieve information about a
specific mount target.
For example:
oci fs mount-target get --mount-target-id mount_target_OCID
To update a mount target

Open a command prompt and run oci fs mount-target update to update a specific mount
target's information.
For example:
oci fs mount-target update --mount-target-id mount_target_OCID --display-name "New Mount Target Name"
To delete a mount target

Open a command prompt and run oci fs mount-target delete to delete a mount target.

Deleting a mount target also deletes the mount target's VNICs.
For example:
oci fs mount-target delete --mount-target-id mount_target_OCID
Warning
Deleting a mount target can cause any clients that have

mounted an associated file system to hang. Be sure to
have all clients unmount the file systems before
deleting the mount target.
To create a snapshot
You can create a snapshot of a file system. A snapshot is a point-in-time view of the file
system. The snapshot is accessible at ./shapshot/name.
Open a command prompt and run oci fs snapshot create to create a snapshot of a file
system.
For example:
oci fs snapshot create --file-system-id file_system_OCID --name "January1"
To list snapshots
Open a command prompt and run oci fs snapshot create to list all snapshots associated
with a specific file system.
For example:
oci fs snapshot list --file-system-id file_system_OCID

To get a specific snapshot

Open a command prompt and run oci fs snapshot get to retrieve information about a
specific snapshot.
For example:
oci fs snapshot get --snapshot-id snapshot_OCID
To delete a snapshot
Open a command prompt and run oci fs snapshot delete to delete a snapshot.
For example:
oci fs snapshot delete --snapshot-id snapshot_OCID
Using the API

Use the following operations to manage file systems:
l CreateExport
l CreateMountTarget
l CreateSnapshot
l DeleteExport
l DeleteFileSystem
l DeleteMountTarget
l DeleteSnapshot
l GetExport
l GetExportSet
l GetFileSystem

l GetMountTarget
l GetSnapshot
l ListFileSystems
l ListExports
l ListExportSets
l ListMountTargets
l ListSnapshots
l UpdateExportSet
l UpdateFileSystem
l UpdateMountTarget
Mounting File Systems

Users of Ubuntu and Linux operating systems can use the command line to connect to a file
system and write files. Mount targets serve as file system network access points. After your
mount target is assigned an IP address, you can use it to mount the file system. On the
instance from which you want to mount the file system, you need to install an NFS client and
create a mount point. When you mount the file system, the mount point effectively represents
the root directory of the File Storage file system, allowing you to write files to the file system
from the instance.
You can connect a file system to an Oracle Cloud Infrastructure Database VM instance. The
mount procedure for Oracle Linux DB instances is managed differently than for Oracle Linux
Compute instances. For more information on Oracle Database VM instance configuration, see
Virtual Machine DB Systems.


users to create file systems.
Note
Mounting file systems using the following command line

instructions does not require IAM access permissions.
However, if you want to use the Console to get mount

command samples, you need the required IAM access
permissions.
See About Security for more information.
Using the Console
To get mount command samples

You can use the Console to get mount command samples that include all the information for a
specific mount target and file system. Samples are available for the following operating
system images:
l Oracle Linux
l CentOS
l Debian
l Red Hat Linux
l Ubuntu

compartment.
3. Find the file system you want to mount, click the Actions icon ( ), and then click
View File System Details.
5. Find the mount target you want to use, click the Actions icon ( ), and then click
Mount Commands.
6. In Image, choose the image of the Compute instance you want to mount the file system
to.
7. Click the Copy link to copy the commands.
Next, mount the file system.
Using the Command Line
To mount a file system from Ubuntu or Debian

You can use the following instructions to construct your mount commands, or use the Console
to get mount command samples that include all the information for a specific mount target
and file system. For more information, see To get mount command samples.
1. Open a command window. Then, get the NFS client by copying and pasting the Install
Command from the Console or type the following:
sudo apt-get install nfs-common
2. Create a mount point by copying and pasting the Create Mount Point Command from
the Console or type the following, replacing yourmountpoint with the local directory
from which you want to access your file system.

sudo mkdir -p /mnt/yourmountpoint
3. Mount the file system by copying and pasting the Mount Command from the Console
or type the following. Replace 10.x.x.x: with the local subnet IP address assigned to
your mount target, fs-export-path with the export path you specified when
associating the file system with the mount target, and yourmountpoint with the path to
the local mount point. The export path is the path to the file system (relative to the
mount target’s IP address or hostname). If you did not specify a path when you
associated the file system and mount target, then 10.x.x.x:/ represents the full extent
of the mount target.
sudo mount 10.x.x.x:/fs-export-path /mnt/yourmountpoint
4. View the file system.

df -h
5. Write a file to the file system by typing the following. Replace yourmountpoint with the
path to the local mount point and helloworld with your file name.
sudo touch /mnt/yourmountpoint/helloworld
6. Verify that you can view the file by typing the following. Replace yourmountpoint with
the path to the local mount point.
cd /mnt/yourmountpoint
ls
To mount a file system from Linux, Red Hat, or CentOS

You can use the following instructions to construct your mount commands, or use the Console
to get mount command samples that include all the information for a specific mount target
and file system. For more information, see To get mount command samples.
1. Open a command window. Then, get the NFS client by copying and pasting the Install
Command from the Console or typing the following:
sudo yum install nfs-utils

2. Create a mount point by copying and pasting the Create Mount Point Command from
the Console or type the following, replacing yourmountpoint with the local directory
from which you want to access your file system.
3. Mount the file system by copying and pasting the Mount Command from the Console
or type the following. Replace 10.x.x.x: with the local subnet IP address assigned to
your mount target, fs-export-path with the export path you specified when
associating the file system with the mount target, and yourmountpoint with the path to
the local mount point. The export path is the path to the file system (relative to the
mount target’s IP address or hostname). If you did not specify a path when you
associated the file system and mount target, then 10.x.x.x:/ represents the full extent
of the mount target.
sudo mount 10.x.x.x:/fs-export-path /mnt/yourmountpoint
4. View the file system.

df -h
5. Write a file to the file system by typing the following. Replace yourmountpoint with the
path to the local mount point and helloworld with your file name.
sudo touch /mnt/yourmountpoint/helloworld
6. Verify that you can view the file by typing the following. Replace yourmountpoint with
the path to the local mount point.
cd /mnt/yourmountpoint
ls
To mount a file system from a Database VM instance

Database VM instances are built on Oracle Linux 6.8, unlike Oracle Linux Compute instances,
which run on version 7.4. The NFS Utilities package is pre-installed on DB instances, but the
Open Network Computing Remote Procedure Call (ONC RPC) rpcbind utility is disabled by

default. Oracle Linux 6.8 does not have systemd, so DB instances are managed differently
than OL compute instances. An Oracle DB instance comes with a set of iptables rules that
exclude any non-database ports and need to be updated to allow mount target traffic.
1. SSH to the DB system.

2. Start the rpcbind service by typing the following:

sudo service rpcbind start
3. Use the chkconfig command to enable starting rpcbind service at system startup.
sudo chkconfig rpcbind on
4. Change the default configuration of iptables to include the mount target IP address and
allow traffic by typing the following. Replace 10.x.x.x with the local subnet address
assigned to the mount target for the file system. Save the new iptables entries.
sudo iptables -A INPUT -p tcp -s 10.x.x.x -j ACCEPT
sudo iptables -A OUTPUT -p tcp -s 10.x.x.x -j ACCEPT
sudo service iptables save
5. Create a mount point by typing the following, replacing yourmountpoint with the local
directory from which you want to access your file system.
6. Mount the file system by typing the following. Replace 10.x.x.x: with the local subnet
IP address assigned to your mount target, fs-export-path with the export path you
specified when associating the file system with the mount target, and yourmountpoint
with an absolute path to a local mount point. The export path is the path to the file
system (relative to the mount target’s IP address or hostname). If you did not specify a
path when you associated the file system and mount target, then 10.x.x.x:/
represents the full extent of the mount target.
sudo mount -t nfs -o tcp,vers=3 10.x.x.x:/fs-export-path /mnt/yourmountpoint

To auto-mount a shared file system

Auto-mount will ensure that a file system will automatically be re-mounted on an instance if it
is rebooted.
1. Open a command window. Then, mount the file system using the steps described in the
previous section.
2. Type the following command to get the file system entry point:
sudo cat /etc/mtab |grep -i nfs
3. Copy the file system entry point, and open the /etc/fstab file:
cd /etc
vi fstab
4. Add the following line to the fstab file:

<file_system_ip_address>:<file_system_path_name> <your_local_mount_point> nfs defaults,nofail 0 0
5. Save the fstab file.
Paths in File Systems

There are three kinds of paths that are used in File Storage service:
1. Export Paths are specified when a file system is associated with a mount target. It
uniquely identifies the file system within the mount target, letting you associate up to
100 file systems behind a single mount target. The export path is appended to the
mount target IP address, and used to mount (logically attach) to the file system. This
path is unrelated to any path within the file system or the client instance. It exists solely
as a way to distinguish one file system from another within a single mount target.
In this mount command example, 10.0.0.6 is the mount target IP
address./example/path is the unique export path that was specified when the file
system was associated with a mount target during creation.

Remember when specifying export paths that no two file systems associated with the
same mount target can have an export path that contains a complete path of the other.
For example,
/example and /path is OK.
/example and /example/path is not OK.
For more information on path name requirements, click here.
2. Mount Point Paths are paths within a client instance to a locally accessible directory
to which the remote file system is mounted.
In this mount command example, /mnt/mountpointA is the path to the directory on the
client instance on which the external file system is mounted.
3. File System Paths are paths to directories within the file system, and contain the
contents of the file system. When the file system is mounted, you can create any
directory structure within it you like. Snapshots of the file system can be accessed using
the file system path, under the file system's root directory at .snapshot/name.
The following example shows the path to a snapshot called 'January 1' when navigating
from the instance:
/mountpointA/.snapshot/January1
Troubleshooting Your File System

These topics cover some common issues you may run into and how to address them:
l Application Installation Fails Due to Too Much Available Capacity

l Application Performance is Not as Expected
l Cannot Delete Snapshot
l Cannot Delete VCN - Mount Target VNIC Still Attached and Not Accessible for Deletion
l Mount Command Fails
l Mount Target Creation Fails
l Removing File Locks from a Host That is No Longer Available
l Symbolic Links (Symlinks) Produce Errors

Application Installation Fails Due to Too Much Available Capacity

Some existing application installers perform a capacity check prior to running an installation
process. Sometimes an installation fails due to too much available capacity. File Storage
Service currently reports 8 exabytes of available capacity by default.
Customers can define how much free capacity is reported as available to the operating system
using the Console or the API .
To set the reported free capacity in the Console

You can set the reported free capacity during file system creation. See To create a file system
for more information.
You can also set the reported free capacity in the file system's mount target details page:
compartment.
3. Find the file system you created, click the Actions icon ( ), and then click View
File System Details.
5. Click the name of the mount target.
6. Click the Maximum Free Space (in GiB) Edit icon.
7. Enter the maximum free space in gibibytes you want File Storage Service to report for
the mount target.
8. Click the Save icon.
To set the reported free capacity in the API

You can use the UpdateExportSet operation to update the MaxFsStatBytes.

See About the API for more information.
Application Performance is Not as Expected

Several factors can impact application performance:
l Available bandwidth
We recommend that you use bare metal Compute instances because instance bandwidth
scales with the number of oCPU's. Bare metal Compute instances provide the greatest
bandwidth. Virtual machines (VMs) are bandwidth limited based upon the number of
CPU’s consumed. Single oCPU VM Compute instances provide the least bandwidth.
l Latency
Accessing File Storage Service from an instance running in the same availability domain
minimizes latency.
l Mount options
By not providing explicit values for mount options such as rsize and wsize, the client and
server can negotiate the window size for read and write operations that provide the best
performance.
Cannot Delete Snapshot

File Storage Service supports deleting snapshots from any file system. Customers can delete
a snapshot using the API or the Command Line Interface (CLI)
Open a command prompt and type the following command:

oci fs snapshot delete --snapshot-id snapshot_OCID
To delete a snapshot in the API, use the DeleteSnapshot operation.
See About the API for more information.

Cannot Delete VCN- Mount Target VNIC Still Attached and Not

Accessible for Deletion
An "orphan" mount target is defined as a mount target that is not associated with any file
system, and not accessible for deletion in the Console. Orphan mount targets are not easily
visible in the Console, and can be overlooked.
Orphan mount targets that remain in your system can cause issues such as:
l They can prevent you from deleting a VCN. Mount target VNICs that remain in the
VCN must be deleted before you can delete the VCN.
l They can prevent you from creating new mount targets. Orphan mount targets
can cause you to exceed your limit without realizing it.
increase.
To delete an "orphan" mount target
1. Associate the orphan mount target with a file system. The file system must be in the
same availability domain as the subnet containing the orphan mount target.
l If you already have a file system in the correct availability domain, associate it
with the orphan mount target:
o Use the steps in To view file system details to navigate to the File System
Details page.
o Click Add Mount Target, and then Select an existing mount target.
Select the orphan mount target from the list to associate it with the file
system.
o Click Add Mount Target.
l If you don't have a file system in the correct availability domain:
o Use the steps found in To create a file system to create one in the correct
availability domain.

o Choose Select an Existing Mount Target, and select the orphan mount
target from the list to associate it with the new file system.
o Click Create File System.
2. Now that the mount target is associated with a file system, you can delete the mount
target.
3. If you wish, delete the new file system.
4. If you wish, delete the VCN. For more information, see VCNs and Subnets.
Mount Command Fails

The export path of a file system must be correctly represented in your mount command, or
the mount will fail.
The export path is specified when a file system is associated with a mount target. It uniquely
identifies the file system within the mount target, letting you associate multiple systems to a
single mount target. The export path is appended to the mount target IP address, and used to
mount the file system.
In this example, 10.0.0.6: is the mount target IP address, and /example/path is the export
path. /mnt/mountpointA is the path to the directory on the client instance on which the
external file system is mounted.
Tip
To see the file system's export path for each of its

mount targets, go to the file system's Details page.
Each mount target that the file system is associated
with appears in the Mount Targets list, along with file
system export path information.
We recommend that you specify an export path for each file system for the following reasons:

l If you do not specify a file path, then '/' represents the extent of the default file path.
This can cause confusion when creating a mount command.
l If one file system associated with a mount target uses an export path of '/' , it will
prevent you from associating more file systems with that mount target. No two file
systems associated with the same mount target can have an export path that contains a
complete path of the other. For more information on path name requirements, click
here.
To simplify file system management, exports and export sets are managed through the
Console by File Storage service. If you want more advanced export and export set
configuration options, you can use the Command Line Interface (CLI) or API.
See Paths in File Systems for more information.
Mount Target Creation Fails

Mount target creation can fail for various reasons:
l You've exceeded your mount target limit.

Each availability domain is limited to two mount targets by default. If you create both a
file system and a mount target at the same time, it is possible for the file system to be
successfully created but the mount target creation to fail because of this limitation.
You can associate the new file system with a previously created mount target. For more
information, see To add more file systems to a mount target.
increase.
l You have "orphan" mount targets that have been overlooked, and they've
caused you to exceed your mount target limit. An "orphan" mount target is
defined as a mount target that is not associated with any file system, and not easily
visible in the Console, or accessible for deletion.
See To delete an "orphan" mount target for more information.
l There aren't enough available IP addresses in your subnet.

Each mount target requires three internal IP addresses in the subnet to function. Two of
the IP addresses are used during mount target creation. The third IP address must
remain available for the mount target to use for high availability failover.
Do not use /30 or smaller subnets for mount target creation because they do not have
sufficient available IP addresses for mount target creation.
File Storage service doesn't "reserve" the third IP address required for high availability
failover, so use care when designing your subnets and file systems to ensure that
sufficient IP addresses remain available for your mount targets in the future.
Removing File Locks from a Host That is No Longer Available

File Storage Service supports the removal of file locks from any file system. To request the
removal of file locks on a file system:
1. Go to My Oracle Support and sign in.

If you are not signed in directly to Oracle Cloud Support, click Switch to Cloud
Support at the top of the page.
2. Click Service Requests.
3. Click Create Service Request.
4. Select the following:
l Service Type: Oracle Compute Cloud Service Bare Metal
l Service Name: IAASMB IAASMB
l Problem Type: FSS File System Lock Removal Request
5. Enter your contact information.
6. Enter a Description, and then enter the following specific information:
l Tenancy OCID
l File System OCID
l Mount Target OCID
l Host IP Address

Each Oracle Cloud Infrastructure resource has a unique, Oracle-assigned

identifier called an Oracle Cloud ID (OCID). For information about the OCID
format and other ways to identify your resources, see Resource Identifiers.
Symbolic Links (Symlinks) Produce Errors

File Storage Service fully supports the use of symbolic links. However, symbolic links are
interpreted by the client and symlinks that point outside of the mounted File Storage system
may be interpreted differently by each client and lead to unexpected results, such as broken
links or pointing to the wrong file. Symbolic link targets that work on one client might be
broken on another due to differences in file system layout or because clients mounted the file
system using different mount targets.
Snapshots can also break symbolic links that point to a target outside the file system’s root
directory. This is because when you create a snapshot of a file system, it becomes available
as a subdirectory of the .snapshot directory.
To minimize these potential issues, use a relative path as the target path when creating a
symbolic link to a file in the network file system. Also, ensure that relative paths do not point
to a target path outside the File Storage Service root directory except when the target is on
the local machine. If you must use a symbolic link that points to a target path outside the file
system, use an absolute path starting with the client’s root directory.
For example:
l Pointing to "/user/bin/example" works.

l Pointing to "/yourmountpoint/..." does not work.
l Pointing to "/home/user/yourmountpoint/..." does not work.

CHAPTER 12 IAM
This chapter explains how to set up administrators, users, and groups and specify their
permissions.
Overview of IAM
Oracle Cloud Infrastructure Identity and Access Management (IAM) lets you control who has
access to your cloud resources. You can control what type of access a group of users have and
to which specific resources. This section gives you an overview of IAM components and an
example scenario to help you understand how they work together.
Note
This document uses the term "you" broadly to mean any

administrator in your company who has access to work
with IAM.
Components of IAM
IAM uses the components described in this section. To better understand how the components
fit together, see Example Scenario.
RESOURCE
The cloud objects that your company's employees create and use when interacting with
Oracle Cloud Infrastructure. For example: compute instances, block storage volumes,
virtual cloud networks (VCNs), subnets, route tables, etc.
USER
An individual employee or system that needs to manage or use your company's Oracle
Cloud Infrastructure resources. Users might need to launch instances, manage remote

CHAPTER 12 IAM
disks, work with your virtual cloud network, etc. End users of your application are not
typically IAM users. Users have one or more IAM credentials (see User Credentials).
GROUP
A collection of users who all need the same type of access to a particular set of resources
or compartment.
COMPARTMENT
A collection of related resources. Compartments are a fundamental component of Oracle

Cloud Infrastructure for organizing and isolating your cloud resources. You use them to
clearly separate resources for the purposes of measuring usage and billing, access
(through the use of policies), and isolation (separating the resources for one project or
business unit from another). A common approach is to create a compartment for each
major part of your organization. For more information, see "Setting Up Your Tenancy" in
the Oracle Cloud Infrastructure Getting Started Guide.
TENANCY
The root compartment that contains all of your organization's Oracle Cloud Infrastructure
resources. Oracle automatically creates your company's tenancy for you. Directly within
the tenancy are your IAM entities (users, groups, compartments, and some policies; you
can also put policies into compartments inside the tenancy). You place the other types of
cloud resources (e.g., instances, virtual networks, block storage volumes, etc.) inside the
compartments that you create.
POLICY
A document that specifies who can access which resources, and how. Access is granted at
the group and compartment level, which means you can write a policy that gives a group a
specific type of access within a specific compartment, or to the tenancy itself. If you give
a group access to the tenancy, the group automatically gets the same type of access to all
the compartments inside the tenancy. For more information, see Example Scenario and
How Policies Work. The word "policy" is used by people in different ways: to mean an
individual statement written in the policy language; to mean a collection of statements in
a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it);

CHAPTER 12 IAM
and to mean the overall body of policies your organization uses to control access to
resources.
HOME REGION
The region where your IAM resources reside. All IAM resources are global and available
across all regions, but the master set of definitions reside in a single region, the home
region. You must make changes to your IAM resources in your home region. The changes
will be automatically propagated to all regions. For more information, see Managing
Regions.
Services You Can Control Access To

You can write policies to control access to all of the services within Oracle Cloud
Infrastructure. That includes:
l Audit Service
l Core Services (includes Networking, Compute, and Block Volume)
l Database
l DNS
l Email Delivery
l File Storage
l IAM
l Load Balancing
l Object Storage
The Administrators Group and Policy

When your company signs up for an Oracle account and Identity Domain, Oracle sets up a
default administrator for the account. This person will be the first IAM user for your company
and will be responsible for initially setting up additional administrators. Your tenancy comes
with a group called Administrators, and the default administrator automatically belongs in this
group. You can't delete this group, and there must always be at least one user in it.

CHAPTER 12 IAM
Your tenancy also automatically has a policy that gives the Administrators group access to all
of the Oracle Cloud Infrastructure API operations and all of the cloud resources in your
tenancy. You can neither change nor delete this policy. Any other users you put into the
Administrators group will have full access to all of the services. This means they can create
and manage IAM users, groups, policies, and compartments. And they can create and manage
the cloud resources such as virtual cloud networks (VCNs), instances, block storage volumes,
and any other new types of Oracle Cloud Infrastructure resources that become available in the
future.
Example Scenario
The goal of this scenario is to show how the different IAM components work together, and
basic features of policies.
In this scenario Acme Company has two teams that will be using Oracle Cloud Infrastructure
resources for infrastructure: Project A and Project B. In reality, your company may have
many more.
Acme Company plans to use a single virtual cloud network (VCN) for both teams, and wants a
network administrator to manage the VCN.
Acme Company also wants the Project A team and Project B team to each have their own set
of instances and block storage volumes. The Project A team shouldn't be able to use the
Project B team's instances, and vice versa. These two teams also shouldn't be allowed to
change anything about the VCN set up by the network administrator. Acme Company wants
each team to have administrators for that team's resources. The administrators for the
Project A team can decide who can use the Project A cloud resources, and how. Same for the
Project B team.
Acme Company Gets Started with Oracle Cloud Infrastructure
Acme Company signs up to use Oracle Cloud Infrastructure and tells Oracle that an employee
named Wenpei will be the default administrator. In response, Oracle:
l Creates a tenancy for Acme Company (see the following diagram).

l Creates an IAM user account for Wenpei in the tenancy.

CHAPTER 12 IAM
l Creates the Administrators group in the tenancy and places Wenpei in that group.
l Creates a policy in Acme Company's tenancy that gives the Administrators group access
to manage all of the resources in the tenancy. Here's that policy:
Allow group Administrators to manage all-resources in tenancy
The Default Administrator Creates Some Groups and Another Administrator
Wenpei next creates several groups and users (see the following diagram). She:
l Creates groups called NetworkAdmins, A-Admins, and B-Admins (these last two are for
Project A and Project B within the company)
l Creates a user called Alex and puts him in the Administrators group.
l Leaves the new groups empty.
To learn how to create groups, see Working with Groups. To learn how to create users and
put them in groups, see Working with Users.

CHAPTER 12 IAM
The Default Administrator Creates Some Compartments and Policies
Wenpei next creates compartments to group resources together (see the following diagram).
She:
l Creates a compartment called Networks to control access to the Acme Company's VCN,
subnets, IPSec VPN, and other components from Networking.
l Creates a compartment called Project-A to organize Project A team's cloud resources
and control access to them.
l Creates a compartment called Project-B to organize Project B team's cloud resources
and control access to them.
To learn how to manage compartments, see Working with Compartments.
Wenpei then creates a policy to give the administrators for each compartment their required
level of access. She attaches the policy to the tenancy, which means that only users with
access to manage policies in the tenancy can later update or delete the policy. In this
scenario, that is only the Administrators group. The policy includes multiple statements that:

CHAPTER 12 IAM
l Give the NetworkAdmins group access to manage networks and instances (for the
purposes of easily testing the network) in the Networks compartment
l Give both the A-Admins and B-Admins groups access to use the networks in the
Networks compartment (so they can launch instances into the network).
l Give the A-Admins group access to manage all resources in the Project-A compartment.
l Give the B-Admins group access to manage all resources in the Project-B compartment.
Here's what that policy looks like (notice it has multiple statements in it):
Allow group NetworkAdmins to manage virtual-network-family in compartment Networks
Allow group NetworkAdmins to manage instance-family in compartment Networks
Allow group A-Admins,B-Admins to use virtual-network-family in compartment Networks
Allow group A-Admins to manage all-resources in compartment Project-A
Allow group B-Admins to manage all-resources in compartment Project-B
Notice the difference in the verbs (manage, use, inspect), as well as the resources
(virtual-network-family, instance-family, all-resources). For more information
about them, see Verbs and Resource-Types.To learn how to create policies, see To create a
policy.
Acme Company wants to let the administrators of the Project-A and Project-B compartments
decide which users can use the resources in those compartments. So Wenpei creates two
more groups: A-Users and B-Users. She then adds six more statements that give the
compartment admins the required access they need in order to add and remove users from
those groups:
Allow group A-Admins to use users in tenancy where target.group.name='A-Users'
Allow group A-Admins to use groups in tenancy where target.group.name='A-Users'
Allow group B-Admins to use users in tenancy where target.group.name='B-Users'

Allow group B-Admins to use groups in tenancy where target.group.name='B-Users'
Allow group A-Admins,B-Admins to inspect users in tenancy

Allow group A-Admins,B-Admins to inspect groups in tenancy

CHAPTER 12 IAM
Notice that this policy doesn't let the project admins create new users or manage credentials
for the users. It lets them decide which existing users can be in the A-Users and B-Users
groups. The last two statements are necessary for A-Admins and B-Admins to list all the users
and groups, and confirm which users are in which groups.

CHAPTER 12 IAM

CHAPTER 12 IAM
An Administrator Creates New Users
At this point, Alex is in the Administrators group and now has access to create new users. So
he provisions users named Leslie, Jorge, and Cheri and places them in the NetworkAdmins, A-
Admins, and B-Admins groups, respectively. Alex also creates other users who will eventually
be put in the A-Users and B-Users groups by the admins for Project A and Project B.

CHAPTER 12 IAM

CHAPTER 12 IAM
The Network Admin Sets Up the Network
Leslie (in the NetworkAdmins group) has access to manage virtual-network-family and
instance-family in the Networks compartment. She creates a virtual cloud network (VCN)
with a single subnet in that compartment. She also sets up an Internet gateway for the VCN,
and updates the VCN's route table to allow traffic via that gateway. To test the VCN's
connectivity to the on-premises network, she launches an instance in the subnet in the VCN.
As part of the launch request, she must specify which compartment the instance should reside
in. She specifies the Networks compartment, which is the only one she has access to. She
then confirms connectivity from the on-premises network to the VCN by logging in to the
instance via SSH from the on-premises network.
Leslie terminates her test instance and lets Jorge and Cheri know that the VCN is up and
running and ready to try out. She lets them know that their compartments are named Project-
A and Project-B respectively. For more information about setting up a cloud network, see
Overview of Networking. For information about launching instances into the network, see
Overview of the Compute Service.
Compartment Admins Set Up Their Compartments
Jorge and Cheri now need to set up their respective compartments. Each admin needs to do
the following:
l Launch instances in their own compartment

l Put users in their "users" group (e.g., A-Users)
l Decide the type of access to give those users, and accordingly attach a policy to their
compartment
Jorge and Cheri both launch instances into the subnet in the VCN, into their respective team's
compartments. They create and attach block volumes to the instances. Only the compartment
admins can launch/terminate instances or attach/detach block olumes in their respective
team's compartments.

CHAPTER 12 IAM
Important
Network Topology and Compartment Access Are Different

Concepts
It's important to understand the difference between the

network topology of the VCN and the access control that
the compartments provide. The instances Jorge
launched reside in the VCN from a network topology
standpoint. But from an access standpoint, they're in
the Project-A compartment, not the Networks
compartment where the VCN is. Leslie (the Networks
admin) can't terminate or reboot Jorge's instances, or
launch new ones into the Project-A compartment. But
Leslie controls the instances' network, so she controls
what traffic will be routed to them. If Jorge had
specified the Networks compartment instead of the
Project-A compartment when launching his instances,
his request would have been denied. The story is similar
for Cheri and the Project-B compartment.
But it's also important to note that Wenpei and Alex in

the Administrators group do have access to the
resources inside the compartments, because they have
access to manage all kinds of resources in the tenancy.
Compartments inherit any policies attached to their
parent compartment (the tenancy), so the
Administrators access also applies to all compartments
within the tenancy.
Next, Jorge puts several of the users that Alex created into the A-Users group. Cheri does the
same for B-Users.

CHAPTER 12 IAM
Then Jorge writes a policy that gives users the level of access they need in the Project-A
compartment.
Allow group A-Users to use instance-family in compartment Project-A
Allow group A-Users to use volume-family in compartment Project-A
Allow group A-Users to inspect virtual-network-family in compartment Networks
This lets them use existing instances (with attached block volumes) that the compartment
admins already launched in the compartment, and stop/start/reboot them. It does not let A-
Users create/delete or attach/detach any volumes. To give that ability, the policy would need
to include manage volume-family.
Jorge attaches this policy to the Project-A compartment. Anyone with the ability to manage
policies in the compartment can now modify or delete this policy. Right now, that is only the
A-Admins group (and the Administrators group, which can do anything throughout the
tenancy).
Cheri creates and attaches her own policy to the Project-B compartment, similar to Jorge's
policy:
Allow group B-Users to use instance-family in compartment Project-B
Allow group B-Users to use volume-family in compartment Project-B
Allow group B-Users to inspect virtual-network-family in compartment Networks
Now the A-Users and B-Users can work with the existing instances and attached volumes in
the Project-A and Project-B compartments, respectively. Here's what the layout looks like:

CHAPTER 12 IAM

CHAPTER 12 IAM
For more information about basic and advanced features of policies, see How Policies Work.
For examples of other typical policies your organization might use, see Common Policies.
Viewing Resources by Compartment in the Console

In the Console, you view your cloud resources by compartment. This means that after you
sign in to the Console, you'll choose which compartment to work in (there's a list to choose
from on the left side of the page). The page will update to show that compartment's resources
that are within the current region. If there are none or you don't have access to that
compartment, you'll see a message.
This experience is different when you're viewing the lists of users, groups, and
compartments. Those reside in the tenancy itself (the root compartment), not in an individual
compartment.
As for policies, they can reside in either the tenancy or a compartment, depending on where
the policy is attached. Where it's attached controls who has access to modify or delete it. For
more information, see Policy Attachment.
The Scope of IAM Resources

Oracle Cloud Infrastructure uses the concepts of regions and availability domains (see
Regions and Availability Domains). Some resources are available regionally, whereas others
are available only within a certain availability domain. IAM resources (users, groups,
compartments, and policies) are global and available across all regions. See Managing
Regions.

CHAPTER 12 IAM

Limits on IAM Resources

increase.
Getting Started with Policies

If you're new to Oracle Cloud Infrastructure Identity and Access Management (IAM) policies,
this topic gives guidance on how to proceed.
If You're Doing a Proof-of-Concept

If you're just trying out Oracle Cloud Infrastructure or doing a proof-of-concept project with
infrastructure resources, you may not need more than a few administrators with full access to
everything. In that case, you can simply create any new users you need and add them to the
Administrators group. The users will be able to do anything with any kind of resource. And you
can create all your resources directly in the tenancy (the root compartment). You don't need
to create any compartments yet, or any other policies beyond the Tenant Admin Policy, which
automatically comes with your tenancy and can't be changed.

CHAPTER 12 IAM
Note
Don't forget to add your new users to the Administrators

group; it's easy to forget to do that after creating them.
If You're Past the Proof-of-Concept Phase

If you're past the proof-of-concept phase and want to restrict access to your resources, first:
l Make sure you're familiar with the basic IAM components, and read through the
example scenario: Overview of IAM
l Think about how to organize your resources into compartments: See "Setting Up Your
Tenancy" in the Oracle Cloud Infrastructure Getting Started Guide
l Learn the basics of how policies work: How Policies Work
l Check out some typical policies: Common Policies
l Read the FAQs below
Policy FAQs
Which of the services within Oracle Cloud Infrastructure can I control access to
through policies?
All of them, including IAM itself. You can find specific details for writing policies for each
service in the Policy Reference.
Can users do anything without an administrator writing a policy for them?

Yes. All users can automatically do these things without an explicit policy:

CHAPTER 12 IAM
l Change or reset their own Console password, and manage their own API signing keys
and Swift passwords (see Security Credentials).
l Get a list of all the compartments in the tenancy (root compartment), regardless of
whether the user has access to the contents of any of the compartments.
The second item above enables basic navigation within the Console for all users. If the user
tries to view the contents of a compartment they don't have access to, they'll receive an
error.
Why should I separate resources by compartment? Couldn't I just put all the
resources into one compartment and then use policies to control who has
access to what?
You could put all your resources into a single compartment and use policies to control access,
but then you would lose the benefits of measuring usage and billing by compartment, simple
policy administration at the compartment level, and clear separation of resources between
projects or business units.
Can I control or deny access to an individual user?

Yes. However, there are a couple things to know first:
l Enterprise companies typically have multiple users that need similar permissions, so
policies are designed to give access to groups of users, not individual users. A user
gains access by being in a group.
l Policies are designed to allow access; there's no explicit "deny" when you write a policy.
If you need to restrict a particular user's access, you can:
l Remove the user from the particular group of interest

l Delete the user entirely from IAM (you have to remove the user from all groups first)

CHAPTER 12 IAM
How do I delete a user?

First ensure the user isn't in any groups. Only then can you delete the user.
How do I delete a compartment?

Compartments cannot be deleted. If you have a compartment you no longer want to use,
terminate/delete all resources in it, and delete any policies or policy statements that refer to
it. You can rename the compartment to change its location in the list.
How can I tell which policies apply to a particular group or user?

You need to look at the individual statements in all your policies to see which statements
apply to which group. There's not currently an easy way to get this information.
How can I tell which policies apply to a particular compartment?

You need to look at the individual statements in all the policies in the tenancy to see if any
apply to the particular compartment. You also need to look at any policies in the compartment
itself. Policies in any of the sibling compartments cannot refer to the compartment of interest,
so you don't need to check those policies.
How Policies Work

This topic describes how policies work and the basic features.
Overview of Policies
A policy is a document that specifies who can access which Oracle Cloud Infrastructure
resources that your company has, and how. A policy simply allows a group to work in certain
ways with specific types of resources in a particular compartment. If you're not familiar with
users, groups, or compartments, see Overview of IAM.
In general, here’s the process an IAM administrator in your organization needs to follow:

CHAPTER 12 IAM
1. Define users, groups, and one or more compartments to hold the cloud resources for
your organization.
2. Create one or more policies, each written in the policy language. See Common Policies.
3. Place users into the appropriate groups depending on the compartments and resources
they need to work with.
4. Provide the users with the one-time passwords that they need in order to access the
Console and work with the compartments. For more information, see User Credentials.
After the administrator completes these steps, the users can access the Console, change their
one-time passwords, and work with specific cloud resources as stated in the policies.
Policy Basics
To govern control of your resources, your company will have at least one policy. Each policy
consists of one or more policy statements that follow this basic syntax:
Allow group <group_name> to <verb> <resource-type> in compartment <compartment_name>
Notice that the statements always begin with the word Allow. Policies only allow access; they
cannot deny it. Instead there's an implicit deny, which means by default, users can do nothing
and have to be granted access through policies. (There's one exception to this rule; see Can
users do anything without an administrator writing a policy for them?)
An administrator in your organization defines the groups and compartments in your tenancy.
Oracle defines the possible verbs and resource-types you can use in policies (see Verbs and
Resource-Types).
In some cases you'll want the policy to apply to the tenancy and not a compartment inside the
tenancy. In that case, change the end of the policy statement like so:
Allow group <group_name> to <verb> <resource-type> in tenancy
For more details about the syntax, see Policy Syntax.
For information about how many policies you can have, see Service Limits.

CHAPTER 12 IAM
A Few Examples
Let's say your administrator creates a group called HelpDesk whose job is to manage users
and their credentials. Here is a policy that enables that:
Allow group HelpDesk to manage users in tenancy
Notice that because users reside in the tenancy (the root compartment), the policy simply
states the word tenancy, without the word compartment in front of it.
Next, let's say you have a compartment called Project-A, and a group called A-Admins whose
job is to manage all of the Oracle Cloud Infrastructure resources in the compartment. Here's
an example policy that enables that:
Be aware that the policy directly above includes the ability to write policies for that
compartment, which means A-Admins can control access to the compartment's resources. For
more information, see Policy Attachment.
If you wanted to limit A-Admins' access to only launching and managing compute instances
and block storage volumes (both the volumes and their backups) in the Project-A
compartment, but the network itself lives in the Networks compartment, then the policy could
instead be:
Allow group A-Admins to manage instance-family in compartment Project-A
Allow group A-Admins to manage volume-family in compartment Project-A
Allow group A-Admins to use virtual-network-family in compartment Networks
The third statement with the virtual-network-family resource-type enables the instance
launch process, because the cloud network is involved. Specifically, the launch process
creates a new VNIC and attaches it to the subnet where the instance resides.
For additional examples, see Common Policies.
Details about Specifying Groups and Compartments
Typically you'll specify a group or compartment by name in the policy. However, you can use
the OCID instead. Just make sure to add "id" before the OCID. For example:

CHAPTER 12 IAM
Allow group
id ocid1.group.oc1..aaaaaaaaqjihfhvxmumrl3isyrjw3n6c4rzwskaawuc7i5xwe6s7qmnsbc6a
to manage instance-family in compartment Project-A
You can specify multiple groups separated by commas:

Allow group A-Admins, B-Admins to manage instance-family in compartment Projects-A-and-B
Verbs
Oracle defines the possible verbs you can use in your policies. Here's a summary of the verbs,
from least amount of access to the most:
Verb Types of Access Covered Target User
inspect Ability to list resources, without access to any confidential Third-party

information or user-specified metadata that may be part of auditors
that resource.
Important: The operation to list policies includes the
contents of the policies themselves, and the list operations
for the Networking resource-types return all the information
(e.g., the contents of security lists and route tables).
read Includes inspect plus the ability to get user-specified Internal

metadata and the actual resource itself. auditors

CHAPTER 12 IAM
use Includes read plus the ability to work with existing resources Day-to-day
(the actions vary by resource type). Includes the ability to end users of
update the resource, except for resource-types where the resources
"update" operation has the same effective impact as the
"create" operation (e.g., UpdatePolicy,
UpdateSecurityList, etc.), in which case the "update"
ability is available only with the manage verb. In general, this
verb does not include the ability to create or delete that type
of resource.
manage Includes all permissions for the resource. Administrators
The verb gives a certain general type of access (e.g., inspect lets you list and get
resources). When you then join that type of access with a particular resource-type in a policy
(e.g., Allow group XYZ to inspect compartments in the tenancy), then you give that
group access to a specific set of permissions and API operations (e.g., ListCompartments,
GetCompartment). For more examples, see Details for Verbs + Resource-Type Combinations.
The Policy Reference includes a similar table for each service, giving you a list of exactly
which API operations are covered for each combination of verb and resource-type.
There are some special exceptions or nuances for certain resource-types.
Users: Access to both manage users and manage groups lets you do anything with users and
groups, including creating and deleting users and groups, and adding/removing users from
groups. To add/remove users from groups without access to creating and deleting users and
groups, only both use users and use groups are required. See Common Policies.
Policies: The ability to update a policy is available only with manage policies, not use
policies, because updating a policy is similar in effect to creating a new policy (you can
overwrite the existing policy statements). In addition, inspect policies lets you get the full
contents of the policies.

CHAPTER 12 IAM
Object Storage objects: inspect objects lets you list all the objects in a bucket and do a
HEAD operation for a particular object. In comparison, read objects lets you download the
object itself.
Load Balancing resources: Be aware that inspect load-balancers lets you get all
information about your load balancers and related components (backend sets, etc.).
Networking resources:
Be aware that the inspect verb not only returns general information about the cloud
network's components (for example, the name and OCID of a security list, or of a route
table). It also includes the contents of the component (for example, the actual rules in the
security list, the routes in the route table, and so on).
Also, the following types of abilities are available only with the manage verb, not the use verb:
l Update (enable/disable) internet-gateways

l Update security-lists
l Update route-tables
l Update dhcp-options
l Attach a dynamic routing gateway (DRG) to a virtual cloud network (VCN)
l Create an IPSec connection between a DRG and customer-premises equipment (CPE)

CHAPTER 12 IAM
Important
Each VCN has various components that directly affect

the behavior of the network (route tables, security lists,
DHCP options, Internet Gateway, and so on). When you
create one of these components, you establish a
relationship between that component and the VCN,
which means you must be allowed in a policy to both
create the component and manage the VCN itself.
However, the ability to update that component (to
change the route rules, security list rules, and so on)
does NOT require permission to manage the VCN itself,
even though changing that component can directly
affect the behavior of the network. This discrepancy is
designed to give you flexibility in granting least
privilege to users, and not require you to grant
excessive access to the VCN just so the user can
manage other components of the network. Be aware
that by giving someone the ability to update a particular
type of component, you're implicitly trusting them with
controlling the network's behavior.
Resource-Types
Oracle also defines the resource-types you can use in your policies. First, there are individual
types. Each individual type represents a specific type of resource. For example, the vcns
resource-type is specifically for virtual cloud networks (VCNs).
To make policy writing easier, there are family types that include multiple individual
resource-types that are often managed together. For example, the virtual-network-family
type brings together a variety of types related to the management of VCNs (e.g., vcns,
subnets, route-tables, security-lists, etc.). If you need to write a more granular policy

CHAPTER 12 IAM
that gives access to only an individual resource-type, you can. But you can also easily write a
policy to give access to a broader range of resources.
In another example: Block Volume has volumes, volume-attachments, and volume-backups.

If you need to give access to only making backups of volumes, you can specify the volume-
backups resource-type in your policy. But if you need to give broad access to all of the Block
Volume resources, you can specify the family type called volume-family. For a full list of the
resource-types, see Resource-Types.
Important
If a service introduces new individual resource-types,

they will typically be included in the family type for that
service. For example, if Networking introduces a new
individual resource-type, it will be automatically
included in the definition of the virtual-network-
family resource type. For more information about
future changes to the definitions of resource-types, see
Policies and Service Updates.
Note that there are other ways to make policies more granular, such as the ability to specify
conditions under which the access is granted. For more information, see Advanced Policy
Features.
Access that Requires Multiple Resource-Types
Some API operations require access to multiple resource-types. For example,

LaunchInstance requires the ability to create instances and work with a cloud network. The
CreateVolumeBackup operation requires access to both the volume and the volume backup.
That means you'll have separate statements to give access to each resource-type (for an
example, see Let volume backup admins manage only backups). These individual statements
do not have to be in the same policy. And a user can gain the required access from being in
different groups. For example, George could be in one group that gives the required level of
access to the volumes resource-type, and in another group that gives the required access to

CHAPTER 12 IAM
the volume-backups resource-type. The sum of the individual statements, regardless of their
location in the overall set of policies, gives George access to CreateVolumeBackup.
Policy Inheritance
A basic feature of policies is the concept of inheritance: Compartments inherit any policies
that apply to their parent (i.e., the root compartment). The simplest example is the
Administrators group, which automatically comes with your tenancy (see The Administrators
Group and Policy): There's a built-in policy that enables the Administrators group to do
anything in the tenancy:
Allow group Administrators to manage all-resources in tenancy
Because of policy inheritance, the Administrators group can also do anything in any of the
compartments in the tenancy.
Policy Attachment
Another basic feature of policies is the concept of attachment. When you create a policy you
must attach it to a compartment (or the tenancy, which is the root compartment). Where
you attach it controls who can then modify it or delete it. If you attach it to the
tenancy (in other words, if the policy is in the tenancy), then anyone with access to manage
policies in the tenancy can then change or delete it. Typically that's the Administrators group
or any similar group you create and give broad access to. Anyone with access only to a child
compartment cannot modify or delete that policy.
If you instead attach the policy to a child compartment, then anyone with access to manage
the policies in that compartment can change or delete it. In practical terms, this means it's
easy to give compartment administrators (i.e., a group with access to manage all-
resources in the compartment) access to manage their own compartment's policies, without
giving them broader access to manage policies that reside in the tenancy. For an example that
uses this kind of compartment administrator design, see Example Scenario. (Recall that
because of policy inheritance, users with access to manage policies in the tenancy
automatically have the ability to manage policies in compartments inside the tenancy.)
When you write a policy, you can indicate directly in the statement which compartment it
applies to. Alternatively, you can indicate the intended compartment by attaching the policy to

CHAPTER 12 IAM
that compartment. If you attach the policy, you don't need to specify the compartment in the
policy statement itself—you can omit the portion of the statement that says in compartment
COMPARTMENT_NAME (or in tenancy). This means you can write a general policy template that
you can then easily use with a number of compartments (existing ones or perhaps future ones
your organization will need later). For example, let's say you have a centralized
VolumeBackupAdmins group. You could have a policy that gives the group the type of access
they need to back up block storage volumes, and then attach the policy to each compartment.
In the future, if you need to create a new compartment, you simply attach the policy to it. The
policy ensures that volume backups can be created only in compartments (not the tenancy),
and only by the centralized VolumeBackupAdmins group
Allow group VolumeBackupAdmins to use volumes
Allow group VolumeBackupAdmins to manage volume-backups
Note
If you have compartment admins that can manage all

resources in the compartment, then they would also be
able to create volume backups in the compartment
(along with group VolumeBackupAdmins). The
compartment admins would also be able to change or
delete the policy.
The process of attaching the policy is easy (whether attaching to a compartment or the
tenancy): If you're using the Console, when you add the policy to IAM, simply make sure
you're in the desired compartment when you create the policy. If you're using the API, you
specify the OCID of the desired compartment (either the tenancy or other compartment) as
part of the request to create the policy.
If the policy does explicitly state a compartment, you'll get an error if you try to attach the
policy to a different compartment. Notice that attachment occurs during policy creation, which
means a policy can be attached to only one compartment. To learn how to attach a policy to a
compartment, see To create a policy.

CHAPTER 12 IAM
Policies and Service Updates
It's possible that the definition of a verb or resource-type could change in the future. For
example, let's say that the virtual-network-family resource-type changes to include a new
kind of resource that's been added to Networking. By default, your policies automatically stay
current with any changes in service definition, so any policy you have that gives access to
virtual-network-family would automatically include access to the newly added resource. If
you'd prefer a different behavior, see Policy Language Version.
Writing Policies for Each Service
The Policy Reference includes details of the specific resource-types for each service, and
which verb + resource-type combination gives access to which API operations. Here are links
to the specific sections:
l Details for the Audit Service

l Details for the Core Services (this includes Networking, Compute, and Block Volume,
which are closely related)
l Details for the Database Service
l Details for IAM
l Details for Load Balancing
l Details for Object Storage
Common Policies
This section includes some common policies you might want to use in your organization.

CHAPTER 12 IAM
Note
These policies use example group and compartment

names. Make sure to replace them with your own
names.
Let the Help Desk manage users

Type of access: Ability to create, update, and delete users and their credentials. It does not
include the ability to put users in groups (see Let group admins manage group membership).
Where to create the policy: In the tenancy, because users reside in the tenancy.
Let auditors inspect your resources

Type of access: Ability to list the resources in all compartments. Be aware that:
l The operation to list IAM policies includes the contents of the policies themselves
l The list operations for Networking resource-types return all the information (for
example, the contents of security lists and route tables)
l The operation to list instances requires the read verb instead of inspect, and the
contents include the user-provided metadata.
l The operation to view Audit service events requires the read verb instead of inspect.
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
auditors can then inspect both the tenancy and all compartments beneath it. Or you could
choose to give auditors access to only specific compartments if they don't need access to the
entire tenancy.
Allow group Auditors to inspect all-resources in tenancy
Allow group Auditors to read instances in tenancy

CHAPTER 12 IAM
Allow group Auditors to read audit-events in tenancy
Let network admins manage a cloud network

Type of access: Ability to manage all components in Networking. This includes cloud
networks, subnets, gateways, virtual circuits, security lists, route tables, and so on. If the
network admins need to launch instances to test network connectivity, see Let users launch
instances on this page.
NetworkAdmins can then manage a cloud network in any compartment. To reduce the scope
of access to a particular compartment, specify that compartment instead of the tenancy.
Allow group NetworkAdmins to manage virtual-network-family in tenancy
Let network admins manage load balancers

Type of access: Ability to manage all components in Load Balancing. If the group needs to
launch instances, see Let users launch instances on this page.
NetworkAdmins can then manage load balancers in any compartment. To reduce the scope of
access to a particular compartment, specify that compartment instead of the tenancy.
Allow group NetworkAdmins to manage load-balancers in tenancy
If a particular group needs to update existing load balancers (for example, modify the
backend set) but not create or delete them, use this statement:
Allow group LBUsers to use load-balancers in tenancy
Let users launch instances

Type of access: Ability to do everything with instances launched into the cloud network and
subnets in compartment XYZ, and attach/detach any existing volumes that already exist in

CHAPTER 12 IAM
compartment ABC. The first statement also lets the group create and manage instance images
in compartment ABC. If the group doesn't need to attach/detach volumes, you can delete the
second statement.
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartments (ABC and XYZ) to have control over the
individual policy statements for their compartments, see Policy Attachment.
Allow group InstanceLaunchers to manage instance-family in compartment ABC
Allow group InstanceLaunchers to use volume-family in compartment ABC
Allow group InstanceLaunchers to use virtual-network-family in compartment XYZ
Let volume admins manage block volumes and backups

Type of access: Ability to do all things with block storage volumes and volume backups in all
compartments. This makes sense if you want to have a single set of volume admins manage
all the volumes and volume backups in all the compartments. The second statement is
required in order to attach/detach the volumes from instances.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
volumes/backups and instances in a particular compartment, specify that compartment
instead of the tenancy.
Allow group VolumeAdmins to manage volume-family in tenancy
Allow group VolumeAdmins to use instance-family in tenancy
Let volume backup admins manage only backups

Type of access: Ability to do all things with volume backups, but not create and manage
volumes themselves. This makes sense if you want to have a single set of volume backup
admins manage all the volume backups in all the compartments. The first statement gives the
required access to the volume that is being backed up; the second statement enables creation

CHAPTER 12 IAM
of the backup (and the ability to delete backups).
compartments by way of policy inheritance. To reduce the scope of access to just the volumes
and backups in a particular compartment, specify that compartment instead of the tenancy.
Allow group VolumeBackupAdmins to use volumes in tenancy
Allow group VolumeBackupAdmins to manage volume-backups in tenancy
If the group will be using the Console, the following policy gives a better user experience:
Allow group VolumeBackupAdmins to use volumes in tenancy
Allow group VolumeBackupAdmins to manage volume-backups in tenancy
Allow group VolumeBackupAdmins to inspect volume-attachments in tenancy
Allow group VolumeBackupAdmins to inspect instances in tenancy
The last two statements are not necessary in order to manage volume backups. However,
they enable the Console to display all the information about a particular volume.
Let users create, manage, and delete file systems

Type of access: Ability to create, manage, or delete a file system. Administrative functions
for a file system include the ability to rename or delete it or disconnect from it.
Where to create the policy: In the tenancy, so that the ability to create, manage, or delete
a file system is easily granted to all compartments by way of policy inheritance. To reduce the
scope of these administrative functions to file systems in a particular compartment, specify
that compartment instead of the tenancy.
Allow group StorageAdmins to manage file-family in tenancy
Allow group StorageAdmins to manage file-family in compartment ABC

CHAPTER 12 IAM
Let Object Storage admins manage buckets and objects

Type of access: Ability to do all things with Object Storage buckets and objects in all
compartments.
compartments by way of policy inheritance. To reduce the scope of access to just the buckets
and objects in a particular compartment, specify that compartment instead of the tenancy.
Allow group ObjectAdmins to manage buckets in tenancy
Allow group ObjectAdmins to manage objects in tenancy
Let users write objects to Object Storage buckets

Type of access: Ability to write objects to any Object Storage bucket in compartment ABC
(imagine a situation where a client needs to regularly write log files to a bucket). This consists
of the ability to list the buckets in the compartment, list the objects in a bucket, and create a
new object in a bucket. Although the second statement gives broad access with the manage
verb, that access is then scoped down to only the OBJECT_INSPECT and OBJECT_CREATE
permissions with the condition at the end of the statement.
want the admins of compartment ABC to have control over the policy, see Policy Attachment.
Allow group ObjectWriters to read buckets in compartment ABC
Allow group ObjectWriters to manage objects in compartment ABC where any {request.permission='OBJECT_
CREATE', request.permission='OBJECT_INSPECT'}
Access limited to a specific bucket: To limit access to a specific bucket in a particular

compartment, add the condition where target.bucket.name='<bucket_name>'. The
following policy allows the user to list all the buckets in a particular compartment, but they
can only list the objects in and upload objects to BucketA:
Allow group ObjectWriters to read buckets in compartment ABC
Allow group ObjectWriters to manage objects in compartment ABC where all {target.bucket.name='BucketA',
any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT'}}

CHAPTER 12 IAM
For more information about using conditions, see Advanced Policy Features.
Let users download objects from Object Storage buckets

Type of access: Ability to download objects from any Object Storage bucket in compartment
ABC. This consists of the ability to list the buckets in the compartment, list the objects in a
bucket, and read existing objects in a bucket.
want the admins of compartment ABC to have control over the policy, see Policy Attachment.
Allow group ObjectReaders to read buckets in compartment ABC
Allow group ObjectReaders to read objects in compartment ABC
Access limited to a specific bucket: To limit access to a specific bucket in a particular

compartment, add the condition where target.bucket.name='<bucket_name>'. The
following policy allows the user to list all buckets in a particular compartment, but they can
only read the objects in and download from BucketA:
Allow group ObjectReaders to read buckets in compartment ABC
Allow group ObjectReaders to read objects in compartment ABC where target.bucket.name='BucketA'
For more information about using conditions, see Advanced Policy Features.
Let database admins manage database systems

Type of access: Ability to do all things with the Database service in all compartments. This
makes sense if you want to have a single set of database admins manage all the database
systems in all the compartments.
compartments by way of policy inheritance. To reduce the scope of access to just the
database systems in a particular compartment, specify that compartment instead of the
tenancy.
Allow group DatabaseAdmins to manage database-family in tenancy

CHAPTER 12 IAM
Let group admins manage group membership

Type of access: Ability to manage the membership of a group. Does not include the ability
to create or delete users, or manage their credentials (see Let the Help Desk manage users).
The first two statements let GroupAdmins list all the users and groups in the tenancy, list
which users are in a particular group, and list what groups a particular user is in.
The last two statements together let GroupAdmins change a group's membership. The
condition at the end of the last two statements lets GroupAdmins manage membership to all
groups except the Administrators group (see The Administrators Group and Policy). You
should protect membership to that group because it has power to do anything throughout the
tenancy.
It might seem that the last two statements should also cover the basic listing functionality that
the first two statements enable. To better understand how conditions work and why you also
need the first two statements, see Variables that Aren't Applicable to a Request Result in a
Declined Request.
Where to create the policy: In the tenancy, because users and groups reside in the
tenancy.
Allow group GroupAdmins to inspect users in tenancy
Allow group GroupAdmins to inspect groups in tenancy
Allow group GroupAdmins to use users in tenancy where target.group.name != 'Administrators'
Allow group GroupAdmins to use groups in tenancy where target.group.name != 'Administrators'
Let users manage their own passwords and credentials

No policy is required to let users manage their own credentials. All users have the ability to
change and reset their own passwords, manage their own API keys, and manage their own
Swift passwords. For more information, see User Credentials.

CHAPTER 12 IAM
Let a compartment admin manage the compartment

Type of access: Ability to manage all aspects of a particular compartment. For example, a
group called A-Admins could manage all aspects of a compartment called Project-A, including
writing additional policies that affect the compartment. For more information, see Policy
Attachment. For an example of this kind of setup and additional policies that are useful, see
Example Scenario.
Where to create the policy: In the tenancy.

Restrict admin access to a specific region

Type of access: Ability to manage resources in a specific region. Remember that IAM
resources must be managed in the home region. If the specified region is not the home
region, then the Admin will not be able to manage IAM resources. For more information about
the home region, see Managing Regions.
Where to create the policy: In the tenancy.

Allow group Phoenix-Admins to manage all-resources in tenancy where request.region='phx'
The preceding policy allows Phoenix-Admins to manage all aspects of all resources in the
Phoenix (PHX) region.
Members of the Phoenix-Admins group can only manage IAM resources if the tenancy's home
region is Phoenix.
Advanced Policy Features

This section describes policy language features that let you grant more granular access.
Conditions
As part of a policy statement, you can specify one or more conditions that must be met in
order for access to be granted. For a simple example, see Let group admins manage group

CHAPTER 12 IAM
membership.
Each condition consists of one or more predefined variables that you specify values for in the
policy statement. Later, when someone requests access to the resource in question, if the
condition in the policy is met, it evaluates to true and the request is allowed. If the condition is
not met, it evaluates to false and the request is not allowed.
There are two types of variables: those that are relevant to the request itself, and those
relevant to the resource(s) being acted upon in the request, also known as the target. The
name of the variable is prefixed accordingly with either request or target followed by a
period. For example, there's a request variable called request.operation to represent the
API operation being requested. This variable lets you write a broad policy statement, but add
a condition based on the specific API operation. For an example, see Let users write objects to
Object Storage buckets.
Note
Variables that Aren't Applicable to a Request Result in a

Declined Request
If the variable is not applicable to the incoming request,

the condition evaluates to false and the request is
declined. For example, here are the basic policy
statements that together let someone add or remove
users from any group except Administrators:
Allow group GroupAdmins to use users in

tenancy where target.group.name !=
'Administrators'
Allow group GroupAdmins to use groups in

tenancy where target.group.name !=
'Administrators'

CHAPTER 12 IAM
Given the above policy, if GroupAdmins tried to call a

general API operation for users such as ListUsers or
UpdateUser (which lets you change the user's
description), the request would be declined, even
though those API operations are covered by use
users.This is because the above policy statement for
use users also includes the target.group.name
variable, but the ListUsers or UpdateUser request
doesn't involve specifying a group. There is no
target.group.name for those requests, so the request
is declined.
If you want to also grant access to general user API

operations that don't involve a particular group, you
would need an additional statement that gives the level
of access you want to grant, but without the condition.
For example, if you want to grant access to ListUsers,
you need this additional statement:
Allow group GroupAdmins to inspect users in
tenancy
Or if you want to grant access to UpdateUser, you need

this additional statement (which also covers ListUsers
because the use verb includes the capabilities of the
inspect verb):
Allow group GroupAdmins to use users in
tenancy
This general concept also applies to groups (e.g.,

ListGroups and UpdateGroup), and any other resource
type with target variables.
For more information about the syntax of conditions, see Conditions. For a list of all the
variables you can use in policies, see the tables in the Policy Reference.

CHAPTER 12 IAM
Permissions
Permissions are the atomic units of authorization that control a user's ability to perform
operations on resources. Oracle defines all the permissions in the policy language. When you
write a policy giving a group access to a particular verb and resource-type, you're actually
giving that group access to one or more predefined permissions. The purposes of verbs is to
simplify the process of granting multiple related permissions that cover a broad set of access
or a particular operational scenario. The next sections give more details and examples.
Relation to Verbs
To understand the relationship between permissions and verbs, let's look at an example. A
policy statement that allows a group to inspect volumes actually gives the group access to a
permission called VOLUME_INSPECT (permissions are always written with all capital letters
and underscores). In general, that permission enables the user to get information about block
volumes.
As you go from inspect > read > use > manage, the level of access generally increases, and
the permissions granted are cumulative. The following table shows the permissions included
with each verb for the volumes resource-type. Notice that no additional permissions are
granted going from inspect to read.
Inspect Volumes Read Volumes Use Volumes Manage Volumes
VOLUME_INSPECT VOLUME_INSPECT VOLUME_INSPECT VOLUME_INSPECT
VOLUME_UPDATE VOLUME_UPDATE
VOLUME_WRITE VOLUME_WRITE
VOLUME_CREATE
VOLUME_DELETE
The policy reference lists the permissions covered by each verb for each given resource-type.
For example, for block volumes and other resources covered by the Core Services, see the
tables in Details for Verb + Resource-Type Combinations. The left column of each of those

CHAPTER 12 IAM
tables lists the permissions covered by each verb. The other sections of the policy reference
include the same kind of information for the other services.
Relation to API Operations
Each API operation requires the caller to have access to one or more permissions. For
example, to use either ListVolumes or GetVolume, you must have access to a single
permission: VOLUME_INSPECT. To attach a volume to an instance, you must have access to
multiple permissions, some of which are related to the volumes resource-type, some to the
volume-attachments resource-type, and some related to the instances resource-type:
l VOLUME_WRITE
l VOLUME_ATTACHMENT_CREATE
l INSTANCE_ATTACH_VOLUME
The policy reference lists which permissions are required for each API operation. For
example, for the Core Services API operations, see the table in Permissions Required for Each
API Operation.
Understanding a User's Access
The policy language is designed to let you write simple statements involving only verbs and
resource-types, without having to state the desired permissions in the statement. However,
there may be situations where a security team member or auditor wants to understand the
specific permissions a particular user has. The tables in the policy reference show each verb
and the associated permissions. You can look at the groups the user is in and the policies
applicable to those groups, and from there compile a list of the permissions granted.
However, having a list of the permissions isn't the complete picture. Conditions in a policy
statement can scope a user's access beyond individual permissions (see the next section).
Also, each policy statement specifies a particular compartment and can have conditions that
further scope the access to only certain resources in that compartment.

CHAPTER 12 IAM
Scoping Access with Permissions or API Operations
In a policy statement, you can use conditions combined with permissions or API operations to
reduce the scope of access granted by a particular verb.
For example, let's say you want group XYZ to be able to list, get, create, or update groups
(i.e., change their description), but not delete them. To list, get, create, and update groups,
you need a policy with manage groups as the verb and resource-type. According to the table
in Details for Verbs + Resource-Type Combinations, the permissions covered are:
l GROUP_INSPECT
l GROUP_UPDATE
l GROUP_CREATE
l GROUP_DELETE
To restrict access to only the desired permissions, you could add a condition that explicitly
states the permissions you want to allow:
Allow group XYZ to manage groups in tenancy
where any {request.permission='GROUP_INSPECT',

request.permission='GROUP_CREATE',
request.permission='GROUP_UPDATE'}
An alternative would be a policy that allows all permissions except GROUP_DELETE:

Allow group XYZ to manage groups in tenancy where request.permission != 'GROUP_DELETE'
However, with this approach, be aware that any new permissions the service might add in the
future would automatically be granted to group XYZ. Only GROUP_DELETE would be omitted.
Another alternative would be to write a condition based on the specific API operations. Notice
that according to the table in Permissions Required for Each API Operation, both ListGroups
and GetGroup require only the GROUP_INSPECT permission. Here's the policy:
where any {request.operation='ListGroups',

request.operation='GetGroup',
request.operation='CreateGroup',
request.operation='UpdateGroup'}

CHAPTER 12 IAM
It can be beneficial to use permissions instead of API operations in conditions. In the future, if
a new API operation is added that requires one of the permissions listed in the permissions-
based policy above, that policy will already control XYZ group's access to that new API
operation.
But notice that you can further scope a user's access to a permission by also specifying a
condition based on API operation. For example, you could give a user access to GROUP_
INSPECT, but then only to ListGroups.
where all {request.permission='GROUP_INSPECT',

request.operation='ListGroups'}
Policy Language Version

As mentioned in Policies and Service Updates, by default your policies stay current with any
changes to the definitions of verbs and resources as the services change. If you'd prefer to
limit access according to the definitions that were current on a specific date, you can do that.
When creating a policy, you can specify a date, and that is considered its "version". You can
also update the version for an existing policy. For more information, see To create a policy
and also To update the version date for an existing policy.
Policy Syntax
The overall syntax of a policy statement is as follows:
Allow <subject> to <verb> <resource-type> in <location> where <conditions>
Spare spaces or line breaks in the statement have no effect.
For limits on the number of policies and statements, see Service Limits.
Subject
Specify one or more comma-separated groups by name or OCID. Or specify any-user to
cover all users in the tenancy.

CHAPTER 12 IAM
Syntax: group <group_name> | group id <group_ocid> | any-user
Examples:
l To specify a single group by name:

l To specify multiple groups by name (a space after the comma is optional):

Allow group A-Admins, B-Admins to manage all-resources in compartment Projects-A-and-B
l To specify a single group by OCID (the OCID is shortened for brevity):

Allow group
id ocid1.group.oc1..aaaaaaaaqjihfhvxmum...awuc7i5xwe6s7qmnsbc6a
to manage all-resources in compartment Project-A
l To specify multiple groups by OCID (the OCIDs are shortened for brevity):
Allow group
id ocid1.group.oc1..aaaaaaaaqjihfhvxmumrl...wuc7i5xwe6s7qmnsbc6a,
id ocid1.group.oc1..aaaaaaaavhea5mellwzb...66yfxvl462tdgx2oecyq
to manage all-resources in compartment Projects-A-and-B
l To specify any user in the tenancy:

Allow any-user to inspect users in tenancy
Verb
Specify a single verb. For a list of verbs, see Verbs. Example:
Resource-Type
Specify a single resource-type, which can be one of the following:

CHAPTER 12 IAM
l An individual resource-type (e.g., vcns, subnets, instances, volumes, etc.)

l A family resource-type (e.g., virtual-network-family, instance-family, volume-
family, etc.)
l all-resources: Covers all resources in the compartment (or tenancy).
A family resource-type covers a variety of components that are typically used together. This
makes it easier to write a policy that gives someone access to work with various aspects of
your cloud network.
For a list of the available resource-types, see Resource-Types.
Syntax: <resource_type> | all-resources
Examples:
l To specify a single resource-type:

l To specify multiple resource-types, use separate statements:

Allow group A-Users to manage instance-family in compartment Project-A
Allow group A-Users to manage volume-family in compartment Project-A
l To specify all resources in the compartment (or tenancy):

Location
Specify a single compartment by name or OCID. Or simply specify tenancy to cover the
entire tenancy. Remember that users, groups, and compartments reside in the tenancy.
Policies can reside in (i.e., be attached to) either the tenancy or a child compartment.

CHAPTER 12 IAM
Note
Granting Access to Specific Regions or Availability Domains
To create a policy that gives access to a specific region

or availability domain, use the request.region or
request.ad variable with a condition. See Conditions.
The location is optional in the statement. If you omit it, the statement applies to the
compartment (or tenancy) that the policy is attached to. For more information, see Policy
Attachment.
Syntax: [ tenancy | compartment <compartment_name> | compartment id

<compartment_ocid> ]
Examples:
l To specify a compartment by name:

l To specify a compartment by OCID:

Allow group
id ocid1.group.oc1..aaaaaaaavhea5mellwzbmplwrpum46xfc73sb4rm66yfxvl462tdgx2oecyq
to manage all-resources in compartment

id ocid1.compartment.oc1..aaaaaaaayzfq...4fmameqh7lcdlihrvur7xq
l To specify multiple compartments, use separate statements:

Allow group InstanceAdmins to manage instance-family in compartment Project-A
Allow group InstanceAdmins to manage instance-family in compartment Project-B
l To specify multiple compartments by OCID, use separate statements:

Allow group id
ocd1.group.oc1..aaaaaaaavhea5mell...b4rm66yfxvl462tdgx2oecyq
to manage all-resources in compartment id
ocid1.compartment.oc1..aaaaaaaayzfqei...ameq4h7lcdlihrvur7xq

CHAPTER 12 IAM
Allow group id
ocd1.group.oc1..aaaaaaaavhea5mell...b4rm66yfxvl462tdgx2oecyq
to manage all-resources in compartment id
ocid1.compartment.oc1..aaaaaaaaphfjutov5s...vyypllbtctehnqg756a
Conditions
Specify one or more conditions. Use any or all with multiple conditions for a logical OR or
AND, respectively.
Syntax for a single condition: variable =|!= value
Syntax for multiple conditions: any|all {<condition>,<condition>,...}
For a list of variables supported by all the services, see General Variables for All Requests.
Also see the details for each service in the Policy Reference. Here are the types of values you
can use in conditions:
Type Examples
String 'johnsmith@example.com'
'ocid1.compartment.oc1..aaaaaaaaph...ctehnqg756a'
(single quotation marks are required around the value)
Pattern /HR*/ (matches strings that start with "HR")
/*HR/ (matches strings that end with "HR")
/*HR*/ (matches strings that contain "HR")
Examples:
l A single condition.
The following policy enables the GroupAdmins group to create, update, or delete any
groups with names that start with "A-Users-":
Allow group GroupAdmins to manage groups in tenancy where target.group.name = /A-Users-*/

CHAPTER 12 IAM
The following policy enables the GroupAdmins group to manage the membership of any
group besides the Administrators group:
Allow group GroupAdmins to use users in tenancy where target.group.name != 'Administrators'
Allow group GroupAdmins to use groups in tenancy where target.group.name != 'Administrators'
The following policy enables the NetworkAdmins group to manage cloud networks in any
compartment except the one specified:
Allow group NetworkAdmins to manage virtual-network-family in tenancy where target.compartment.id
!= 'ocid1.compartment.oc1..aaaaaaaayzfqeibduyox6icmdol6zyar3ugly4fmameq4h7lcdlihrvur7xq'
l Multiple conditions.
The following policy lets A-Admins create, update, or delete any groups whose names
start with "A-", except for the A-Admins group itself:
Allow group GroupAdmins to manage groups in tenancy where
all {target.group.name=/A-*/,target.group.name!='A-Admins'}
Note that in the above policies, the statements do not let GroupAdmins actually list all the
users and groups. To understand why not, see Variables that Aren't Applicable to a Request
Result in a Declined Request.
Policy Reference
This reference includes:
l Verbs: A list of the available actions to pair with a resource-type

l Resource-Types: A list of the main resource-types
l General Variables for All Requests: Variables you can use when writing policies for any
resource-type
l Details for the Audit Service
l Details for the Core Services (this includes Networking, Compute, and Block Volume)
l Details for the Database Service
l Details for the DNS Service

CHAPTER 12 IAM
l Details for the Email Service

l Details for the File Storage Service
l Details for IAM
l Details for Load Balancing
l Details for Object Storage
For instructions on how to create and manage policies using the Console or API, see Managing
Policies.
Verbs
The verbs are listed in order of least amount of ability to most. The exact meaning of a each
verb depends on which resource-type it's paired with. The tables later in this section show the
API operations covered by each combination of verb and resource-type.
inspect Ability to list resources, without access to any confidential Third-party

information or user-specified metadata that may be part of auditors
that resource.
Important: The operation to list policies includes the
contents of the policies themselves, and the list operations
for the Networking resource-types return all the information
(e.g., the contents of security lists and route tables).
read Includes inspect plus the ability to get user-specified Internal

metadata and the actual resource itself. auditors

CHAPTER 12 IAM
use Includes read plus the ability to work with existing resources Day-to-day
(the actions vary by resource type). Includes the ability to end users of
update the resource, except for resource-types where the resources
"update" operation has the same effective impact as the
"create" operation (e.g., UpdatePolicy,
UpdateSecurityList, etc.), in which case the "update"
ability is available only with the manage verb. In general, this
verb does not include the ability to create or delete that type
of resource.
manage Includes all permissions for the resource. Administrators
Resource-Types
The family resource-types are listed below. For the individual resource-types that make up
each family, follow the links.
l all-resources: All Oracle Cloud Infrastructure resource-types

l database-family: See Details for the Database Service
l instance-family: See Details for the Core Services
l object-family: See Details for Object Storage
l virtual-network-family: See Details for the Core Services
l volume-family: See Details for the Core Services
IAM has no family resource-type, only individual ones. See Details for IAM.
General Variables for All Requests

You use variables when adding conditions to a policy. For more information, see Conditions.
Here are the general variables applicable to all requests.

CHAPTER 12 IAM
Name Type Description
request.user.id Entity (OCID) The OCID of the requesting user.
request.groups.id List of The OCIDs of the groups the requesting user is

entities in.
(OCIDs)
target.compartment.id Entity (OCID) The OCID of the compartment containing the

primary resource.
Note: target.compartment.id and

target.compartment.name cannot be used
with a "List" API operation to filter the list
based on the requesting user's access to the
compartment.
target String The name of the compartment specified in

.compartment.name target.compartment.id.
request.operation String The API operation name being requested (e.g.,

ListUsers).
request.permission String The underlying permission(s) being requested

(see Permissions).

CHAPTER 12 IAM
Name Type Description
request.region String The key of the region the request is made in.
Allowed values are:
l phx
l iad
l fra
l lhr
request.ad String The name of the availability domain the

request is made in. To get a list of availability
domain names, use the ListAvailabilityDomains
operation.
Details for the Audit Service

This topic covers details for writing policies to control access to the Audit service.
Resource-Types
audit-events
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
Details for Verb + Resource-Type Combinations
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.

CHAPTER 12 IAM
For example, the use and manage verbs for the audit-events resource-type cover no extra
permissions or API operations compared to the read verb.
AUDIT -EVENTS
INSPECT
Permissions APIs Fully Covered APIs Partially Covered
none none none
READ
AUDIT_EVENT_READ ListAuditEvents none
USE
no extra no extra none
MANAGE
Permissions Required for Each API Operation
The following table lists the API operations in a logical order, grouped by resource type.
For information about permissions, see Permissions.
API Operation Permissions Required to Use the Operation
ListAuditEvents AUDIT_EVENT_READ

CHAPTER 12 IAM
Details for the Core Services

This topic covers details for writing policies to control access to the Core Services
(Networking, Compute, and Block Volume).
Resource-Types
Networking
AGGREGATE RESOURCE-TYPE
virtual-network-family
INDIVIDUAL RESOURCE-TYPES
vcns
subnets
route-tables
security-lists
dhcp-options
private-ips
public-ips
internet-gateways
local-peering-gateways (which includes local-peering-from, and local-peering-

to)
remote-peering-connections (which includes remote-peering-from, and remote-

peering-to)
drgs
drg-attachments

CHAPTER 12 IAM
cpes
ipsec-connections
cross-connects
cross-connect-groups
virtual-circuits
vnics
vnic-attachments
COMMENTS
A policy that uses <verb> virtual-network-family is equivalent to writing one with a

separate <verb> <individual resource-type> statement for each of the individual
resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in virtual-
network-family.
Compute
instance-family
console-histories
instance-console-connection
instance-images
instances

CHAPTER 12 IAM
volume-attachments (includes only the permissions required for attaching volumes to

instances)
COMMENTS
A policy that uses <verb> instance-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-
types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of
the API operations covered by each verb, for each individual resource-type included in
virtual-network-family.
Block Volume
volume-family
volumes
volume-attachments
volume-backups
COMMENTS
A policy that uses <verb> volume-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-
types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of
the API operations covered by each verb, for each individual resource-type included in
volume-family.

CHAPTER 12 IAM
Supported Variables
For example, the read and use verbs for the vcns resource-type cover no extra permissions
or API operations compared to the inspect verb. However, the manage verb includes several
extra permissions and API operations.
FOR VIRTUAL-NETWORK-FAMILY RESOURCE TYPES
vcns
INSPECT
VCN_READ ListVcns none
GetVcn
READ
USE

CHAPTER 12 IAM
MANAGE

CHAPTER 12 IAM
USE + USE + CreateSubnet, DeleteSubnet (both
also need manage route-tables and

VCN_ATTACH CreateVcn
manage-security-lists and
VCN_DETACH UpdateVcn manage-dhcp-options)
VCN_UPDATE DeleteVcn CreateRouteTable,
DeleteRouteTable (also need manage

VCN_CREATE
route-tables, manage internet-
VCN_DELETE gateways, manage drgs, and
manage private-ips)
CreateInternetGateway,
DeleteInternetGateway (also need
manage internet-gateways)
CreateLocalPeeringGateway,
DeleteLocalPeeringGateway (also
need manage local-peering-
gateways)
CreateSecurityList,
DeleteSecurityList (also need
manage security-lists)
CreateDhcpOptions,
DeleteDhcpOptions (also need manage
dhcp-options)
CreateDrgAttachment,
DeleteDrgAttachment (also need
manage drgs)
Note: The operations above are totally
covered with just manage virtual-
network-family.

CHAPTER 12 IAM
subnets
INSPECT
SUBNET_READ ListSubnets none
GetSubnet
READ
USE
READ + no extra LaunchInstance (also need manage
instance-family)
SUBNET_ATTACH
TerminateInstance (also need manage

SUBNET_DETACH
instance-family, and use volumes if
a volume is attached)
AttachVnic (also need manage
instances and either use vnics or use
instance-family)
DetachVnic (also need manage
instances and either use vnics or use
instance-family)
CreatePrivateIp, DeletePrivateIp
(both also need use private-ips and
use vnics)

CHAPTER 12 IAM
MANAGE
USE + USE + USE +
SUBNET_CREATE UpdateSubnet CreateSubnet, DeleteSubnet (both
also need manage vcns, manage

SUBNET_UPDATE
route-tables, manage security-
SUBNET_DELETE lists, manage dhcp-options)
Note: The above operations in this cell
are covered with just manage virtual-
network-family.
route-tables
INSPECT
ROUTE_TABLE_READ ListRouteTables none
GetRouteTable
READ
USE

CHAPTER 12 IAM
MANAGE
USE + no extra CreateRouteTable (also need manage
vcns, manage internet-gateways,

ROUTE_TABLE_ATTACH
manage drgs, and manage private-
ROUTE_TABLE_DETACH ips)
ROUTE_TABLE_UPDATE UpdateRouteTable (also need manage
internet-gateways, manage drgs,

ROUTE_TABLE_CREATE
manage private-ips, and manage
ROUTE_TABLE_DELETE local-peering-gateways)
DeleteRouteTable (also need manage
vcns)
CreateSubnet, DeleteSubnet (both
also need manage vcns, manage
subnets, manage security-lists,
manage dhcp-options)
Note: All of the above operations in this
cell are totally covered with just manage
security-lists
INSPECT
SECURITY_LIST_READ ListSecurityLists none
GetSecurityList

CHAPTER 12 IAM
READ
USE
MANAGE
USE + USE + CreateSecurityList,
DeleteSecurityList (both also need

SECURITY_LIST_ATTACH UpdateSecurityList
manage vcns)
SECURITY_LIST_DETACH Note: Ability to update a security list is

CreateSubnet, DeleteSubnet (both
available only with the manage verb, not
SECURITY_LIST_UPDATE also need manage vcns, manage
the use verb.
subnets, manage route-tables,
SECURITY_LIST_CREATE
manage dhcp-options)
SECURITY_LIST_DELETE
dhcp-options
INSPECT
DHCP_READ ListDhcpOptions none
GetDhcpOptions

CHAPTER 12 IAM
READ
USE
MANAGE
USE + USE + USE +
DHCP_ATTACH UpdateDhcpOptions CreateDhcpOptions,
DeleteDhcpOptions (both also need

DHCP_DETACH Note: Ability to update a set of DHCP
manage vcns)
options is available only with the manage
DHCP_UPDATE
verb, not the use verb. CreateSubnet, DeleteSubnet (also
DHCP_CREATE need manage vcns, manage
subnets, manage route-tables,

DHCP_DELETE
manage security-lists)

CHAPTER 12 IAM
private-ips
INSPECT
PRIVATE_IP_READ ListPrivateIps none
GetPrivateIp
For ephemeral public IPs only:
ListPublicIps,
GetPublicIpByPrivateIpId,
GetPublicIpByIpAddress
READ
USE
READ + READ + CreatePrivateIp, DeletePrivateIp
(both also need use subnets and use

PRIVATE_IP_UPDATE UpdatePrivateIp
vnics)
PRIVATE_IP_ASSIGN For ephemeral public IPs:

For reserved public IPs:
UpdatePublicIp, CreatePublicIp,
PRIVATE_IP_UNASSIGN UpdatePublicIp, CreatePublicIp,
DeletePublicIp
DeletePublicIp (all also need manage
PRIVATE_IP_CREATE
public-ips)
PRIVATE_IP_DELETE
PRIVATE_IP_ASSIGN_PUBLIC_IP are totally covered with just use
PRIVATE_IP_UNASSIGN_PUBLIC_IP

CHAPTER 12 IAM
MANAGE
USE + no extra USE +
PRIVATE_IP_ROUTE_TABLE_ATTACH CreateRouteTable (also need manage
vcns, manage internet-gateways,

PRIVATE_IP_ROUTE_TABLE_DETACH
manage drgs, and manage route-
tables)
UpdateRouteTable (also need manage
internet-gateways, manage drgs,
and manage route-tables)
are totally covered with just manage
public-ips
INSPECT
none none none
READ
PUBLIC_IP_READ For reserved public IPs only: none
ListPublicIps,
GetPublicIpByPrivateIpId,
GetPublicIpByIpAddress
Permissions for listing/getting
ephemeral public IPs are part of the
private-ip permissions.

CHAPTER 12 IAM
USE
READ + no extra For ephemeral private IPs:
PUBLIC_IP_ASSIGN_PRIVATE_IP
(both also need use private-ips)
PUBLIC_IP_UNASSIGN_PRIVATE_IP
are totally covered with just use
MANAGE
PUBLIC_IP_UPDATE For reserved public IPs:
UpdatePrivateIp,
PUBLIC_IP_CREATE
PUBLIC_IP_DELETE (all of these also need use private-
ips)
internet-gateways
INSPECT
INTERNET_GATEWAY_READ ListInternetGateways none
GetInternetGateway

CHAPTER 12 IAM
READ
USE
MANAGE
USE + USE + CreateInternetGateway,
DeleteInternetGateway (both also

INTERNET_GATEWAY_ATTACH UpdateInternetGateway
need manage vcns)
INTERNET_GATEWAY_DETACH Note: Ability to update a an internet

CreateRouteTable (also need manage
gateway is available only with the
INTERNET_GATEWAY_UPDATE route-tables, manage vcns,
manage verb, not the use verb.
manage drgs, and manage private-
INTERNET_GATEWAY_CREATE
ips)
INTERNET_GATEWAY_DELETE
route-tables, manage drgs, and
manage private-ips)

CHAPTER 12 IAM
local-peering-gateways
INSPECT
LOCAL_PEERING_GATEWAY_READ ListLocalPeeringGateways none
GetLocalPeeringGateway
READ
USE
MANAGE
USE + USE + CreateLocalPeeringGateway,
DeleteLocalPeeringGateway (both
LOCAL_PEERING_GATEWAY_UPDATE UpdateLocalPeeringGateway
also need manage vcns)
LOCAL_PEERING_GATEWAY_ATTACH
LOCAL_PEERING_GATEWAY_DETACH route-tables)
LOCAL_PEERING_GATEWAY_CREATE Note: The above operations in this cell

LOCAL_PEERING_GATEWAY_DELETE

CHAPTER 12 IAM
local-peering-from
INSPECT
LOCAL_PEERING_GATEWAY_READ none none
READ
no extra none none
USE
no extra none none
MANAGE
USE + no extra ConnectLocalPeeringGateways
(acceptor in the peering relationship

LOCAL_PEERING_GATEWAY_CONNECT_
must also grant the requestor manage
FROM
local-peering-to in the compartment
where the acceptor's LPG resides. See
Local VCN Peering (Within Region).)
Note: The above operation in this cell is
totally covered with just manage

CHAPTER 12 IAM
local-peering-to
INSPECT
LOCAL_PEERING_GATEWAY_READ none none
READ
no extra none none
USE
no extra none none
MANAGE
USE + no extra ConnectLocalPeeringGateways
(requestor in the peering relationship

LOCAL_PEERING_GATEWAY_CONNECT_
must also have manage local-
TO
peering-from in the compartment
where the requestor's LPG resides. See
Local VCN Peering (Within Region).)

CHAPTER 12 IAM
remote-peering-connections
INSPECT
REMOTE_PEERING_CONNECTION_ ListRemotePeeringConnections none
READ
GetRemotePeeringConnection
READ
USE
MANAGE
USE + UpdateRemotePeeringConnection CreateRemotePeeringConnection,
DeleteRemotePeeringConnection
REMOTE_PEERING_CONNECTION_
(both also need manage drgs)
UPDATE

CREATE
DELETE

CHAPTER 12 IAM
remote-peering-from
INSPECT
REMOTE_PEERING_CONNECTION_ none none
READ
READ
no extra none none
USE
no extra none none
MANAGE
USE + no extra ConnectRemotePeeringConnections
(acceptor in the peering relationship

must also grant the requestor manage
CONNECT_FROM
remote-peering-to in the
compartment where the acceptor's RPC
resides. See Remote VCN Peering
(Across Regions).)

CHAPTER 12 IAM
remote-peering-to
INSPECT
REMOTE_PEERING_CONNECTION_ none none
READ
READ
no extra none none
USE
no extra none none
MANAGE
USE + no extra ConnectRemotePeeringConnections
(requestor in the peering relationship

must also have manage remote-
CONNECT_TO
peering-from in the compartment
where the requestor's RPC resides. See
Remote VCN Peering (Across Regions).)

CHAPTER 12 IAM
drgs
INSPECT
DRG_READ ListDrgs none
DRG_ATTACHMENT_READ GetDrg
ListDrgAttachments
READ
USE

CHAPTER 12 IAM
MANAGE

CHAPTER 12 IAM
Permissions APIs Fully Covered
USE + USE +
DRG_ATTACH CreateDrg
DRG_DETACH UpdateDrg
DRG_UPDATE DeleteDrg
DRG_ATTACHMENT_UPDATE UpdateDrgAttachment
DRG_CREATE
DRG_DELETE

CHAPTER 12 IAM
APIs Partially Covered
CreateDrgAttachment, DeleteDrgAttachment (both

cpes
also need manage vcns)
INSPECT
CreateRouteTable (also need manage route-tables,
manage vcns, manage internet-gateways, and Permissions APIs Fully Covered
manage private-ips) ListCpes

CPE_READ
UpdateRouteTable (also need manage route-tables, GetCpe

manage internet-gateways, and manage private-
APIs Partially Covered
ips)
none
UpdateVirtualCircuit (also need use virtual-
circuits, and if you're also changing which cross-
connect or cross-connect group the virtual circuit uses,
also need manage cross-connects)
CreateVirtualCircuit, DeleteVirtualCircuit
(also need manage virtual-circuits, and if you're
also adding or removing the virtual circuit to/from a cross-
connect or cross-connect group, also need manage
cross-connects)
CreateRemotePeeringConnection,
DeleteRemotePeeringConnection (both also need
manage remote-peering-connections)
Note: All of the above operations in this cell are totally
covered with just manage virtual-network-family.
READ

CHAPTER 12 IAM
USE
MANAGE
USE + USE + CreateIPSecConnection,
DeleteIPSecConnection (both also

CPE_ATTACH CreateCpe
need manage ipsec-connections and
CPE_DETACH UpdateCpe manage drgs)
CPE_UPDATE DeleteCpe Note: All of the above operations in this

CPE_CREATE
CPE_DELETE
ipsec
INSPECT
IPSEC_CONNECTION_READ ListIPSecConnections none
GetIPSecConnection
GetIPSecConnectionStatus
READ
INSPECT + INSPECT + none
IPSEC_CONNECTION_DEVICE_CONFIG_ GetIPSecConnectionDeviceConfig
READ

CHAPTER 12 IAM
USE
MANAGE
USE + USE + CreateIPSecConnection,
DeleteIPSecConnection (both also

IPSEC_CONNECTION_CREATE UpdateIPSecConnection
need manage cpes and manage drgs)
IPSEC_CONNECTION_UPDATE
IPSEC_CONNECTION_DELETE cell are totally covered with just manage
cross-connects
INSPECT
CROSS_CONNECT_READ ListCrossConnects none
GetCrossConnect
READ
USE
no extra no extra no extra

CHAPTER 12 IAM
MANAGE
USE + UpdateCrossConnect UpdateVirtualCircuit (also need use
virtual-circuits)
CROSS_CONNECT_UPDATE CreateCrossConnect
CreateVirtualCircuit,
CROSS_CONNECT_CREATE DeleteCrossConnect
DeleteVirtualCircuit (also need
CROSS_CONNECT_DELETE manage virtual-circuits)
CROSS_CONNECT_ATTACH
CROSS_CONNECT_DETACH
cross-connect-groups
INSPECT
CROSS_CONNECT_GROUP_READ ListCrossConnectGroups none
GetCrossConnectGroup
READ
USE

CHAPTER 12 IAM
MANAGE
USE + UpdateCrossConnectGroup no extra
CROSS_CONNECT_GROUP_UPDATE CreateCrossConnectGroup
CROSS_CONNECT_GROUP_CREATE DeleteCrossConnectGroup
CROSS_CONNECT_GROUP_DELETE
virtual-circuits
INSPECT
VIRTUAL_CIRCUIT_READ ListVirtualCircuits none
GetVirtualCircuit
READ
USE
READ + no extra UpdateVirtualCircuit (also need
manage drgs,and if you're also

VIRTUAL_CIRCUIT_UPDATE
changing which cross-connect or cross-
connect group the virtual circuit uses,
also need manage cross-connects)

CHAPTER 12 IAM
MANAGE
VIRTUAL_CIRCUIT_CREATE CreateVirtualCircuit,
DeleteVirtualCircuit (both also

VIRTUAL_CIRCUIT_DELETE
need manage drgs, and if you're also
creating/deleting the virtual circuit with a
mapping to a specific cross-connect or
cross-connect group, also need manage
cross-connects)
vnics
INSPECT
VNIC_READ GetVnic none
READ

CHAPTER 12 IAM
USE
READ + UpdateVnic LaunchInstance (also need use
subnets and manage instance-

VNIC_ATTACH
family)
VNIC_DETACH
AttachVnic (also need manage
VNIC_CREATE instances and use subnets)
VNIC_DELETE DetachVnic (also need manage
instances and use subnets)

VNIC_UPDATE
(both also need use subnets and use
private-ips)
MANAGE
vnic-attachments
INSPECT
VNIC_ATTACHMENT_READ GetVnicAttachment ListVnicAttachments (also need
inspect instances)
READ
no extra none no extra

CHAPTER 12 IAM
USE
MANAGE
FOR INSTANCE -FAMILY RESOURCE TYPES
The instance-family includes extra permissions beyond the sum of the permissions for the
individual resource-types included in instance-family. For example: It includes a few
permissions for vnics and volumes, even though those resource-types aren't generally
considered part of the instance-family. Why are there extras included? So you can write
fewer policy statements to cover general use cases, like working with an instance that has an
attached block volume. You can instead write a statement for instance-family instead of
multiple ones covering instances, vnics, and volumes.
Here's a list of the extra permissions:
For inspect instance-family:
l VNIC_READ
l VNIC_ATTACHMENT_READ
l VOLUME_ATTACHMENT_INSPECT
For read instance-family:
l VOLUME_ATTACHMENT_READ
For use instance-family:
l VNIC_ATTACH
l VNIC_DETACH
l VOLUME_ATTACHMENT_UPDATE

CHAPTER 12 IAM
For manage instance-family:
l VOLUME_ATTACHMENT_CREATE
l VOLUME_ATTACHMENT_DELETE
The following tables list the permissions and API operations covered by each of the individual
resource-types included in instance-family.
instances
INSPECT
INSTANCE_INSPECT none GetConsoleHistory,
ListConsoleHistories (both also
need inspect console-histories)
ListVnicAttachments (also need
inspect vnic-attachments)
ListVolumeAttachments (also need
inspect volumes and inspect
volume-attachments)
GetVolumeAttachments (also need
volume-attachments)

CHAPTER 12 IAM
READ
INSPECT + ListInstances INSPECT +
INSTANCE_READ GetInstance CaptureConsoleHistory (also need
manage console-histories and read

Note: ListInstances and
instance-images)
GetInstance include any user-provided
metadata added to the instance ShowConsoleHistoryData (also need
read console-histories and read
instance-images)
USE
READ + READ + READ +
INSTANCE_UPDATE UpdateInstance CreateImage (also need manage
instance-images)
INSTANCE_CREATE_IMAGE InstanceAction
AttachVolume (also need manage

INSTANCE_POWER_ACTIONS
volume-attachments and use
INSTANCE_ATTACH_VOLUME volumes)
INSTANCE_DETACH_VOLUME DetachVolume (also need manage
volume-attachments and use
volumes)

CHAPTER 12 IAM
MANAGE
INSTANCE_CREATE LaunchInstance (also need read
instance-images and use vnics and

INSTANCE_DELETE
use subnets)
INSTANCE_ATTACH_SECONDARY_VNIC
TerminateInstance (also need use
INSTANCE_DETACH_SECONDARY_VNIC vnics and use subnets; also need
manage volume-attachments and use
volumes if a volume is attached)
AttachVnic (also need use subnets
and either use vnics or use instance-
family)
DetachVnic (also need use subnets
and either use vnics or use instance-
family)
console-histories
INSPECT
CONSOLE_HISTORY_INSPECT none ListConsoleHistories,
GetConsoleHistory (both also need
inspect instances)

CHAPTER 12 IAM
READ
INSPECT + none INSPECT +
CONSOLE_HISTORY_READ ShowConsoleHistoryData (also need
read instances and read instance-
images)
USE
MANAGE
USE + DeleteConsoleHistory USE +
CONSOLE_HISTORY_CREATE CaptureConsoleHistory (also need
read instances and read instance-

CONSOLE_HISTORY_DELETE
images)
instance-console-connection
INSPECT
INSTANCE_CONSOLE_CONNECTION_ none ListInstanceConsoleConnections
INSPECT (also need inspect instances and
read instances)

CHAPTER 12 IAM
READ
INSTANCE_CONSOLE_CONNECTION_ GetInstanceConsoleConnection
READ (also need read instances)
USE
READ + none no extra
MANAGE
USE + DeleteInstanceConsoleConnection CreateInstanceConsoleConnection
(also need read instances)

INSTANCE_CONSOLE_CONNECTION_
CREATE
INSTANCE_CONSOLE_CONNECTION_
DELETE
instance-images
INSPECT
INSTANCE_IMAGE_INSPECT ListImages none
GetImage

CHAPTER 12 IAM
READ
INSPECT + no extra INSPECT +
INSTANCE_IMAGE_READ LaunchInstance (also need manage
instances, use vnics, and use
subnets)
CaptureConsoleHistory (also need
read instances and manage
console-histories)
ShowConsoleHistoryData (also need
read instances and read console-
histories)
USE
READ + UpdateImage no extra
INSTANCE_IMAGE_UPDATE
MANAGE
USE + DeleteImage USE +
INSTANCE_IMAGE_CREATE CreateImage (also need use
instances)
INSTANCE_IMAGE_DELETE
FOR VOLUME -FAMILY RESOURCE TYPES
The following table lists the permissions and API operations covered by each of the individual
resource-types included in volume-family.

CHAPTER 12 IAM
volumes
INSPECT
VOLUME_INSPECT ListVolumes ListVolumeBackups,
GetVolumeBackup, (these also need

GetVolume
inspect volume-backups)
UpdateVolumeBackup (also need read
volume-backups)
DeleteVolumeBackup (also need
manage volume-backups)
GetVolumeAttachment (also need
inspect instances and inspect
volume-attachments). If you need to
get the CHAP secret if it exists, read
volume-attachments is required.
READ

CHAPTER 12 IAM
USE
READ + no extra READ +
VOLUME_UPDATE AttachVolume and DetachVolume
(both also need manage volume-

VOLUME_WRITE
attachments, use instances)
CreateVolumeBackup (also need
manage volume-backups)
MANAGE
USE + USE + USE +
VOLUME_CREATE CreateVolume If creating a volume from a backup, also
need read volume-backups.

VOLUME_DELETE DeleteVolume
volume-attachments
INSPECT
VOLUME_ATTACHMENT_INSPECT ListVolumeAttachments GetVolumeAttachment (also need
instances)
Note: The CHAP secret (if it exists) is
NOT included with inspect volume-
attachments.

CHAPTER 12 IAM
READ
INSPECT + no extra Same as for inspect volume-
attachments, except that

VOLUME_ATTACHMENT_READ
GetVolumeAttachment also includes
the CHAP secret, if it exists.
USE
READ + no extra no extra
VOLUME_ATTACHMENT_UPDATE
MANAGE
VOLUME_ATTACHMENT_CREATE AttachVolume, DetachVolume (both
also need use volumes and use

VOLUME_ATTACHMENT_DELETE
instances)
volume-backups
INSPECT
VOLUME_BACKUP_INSPECT none ListVolumeBackups,
GetVolumeBackup (both also need
inspect volumes)

CHAPTER 12 IAM
READ
VOLUME_BACKUP_READ CreateVolume when creating volume
from an backup (also need manage
volumes)
USE
READ + none READ +
VOLUME_BACKUP_UPDATE UpdateVolumeBackup (also need
inspect volumes)
MANAGE
USE + none USE +
VOLUME_BACKUP_CREATE CreateVolumeBackup (also need use
volumes)
VOLUME_BACKUP_DELETE
DeleteVolumeBackup (also need
inspect volumes)
The following table lists the Core Services API operations grouped by resource type, which are
listed in alphabetical order.

CHAPTER 12 IAM
ListConsoleHistories CONSOLE_HISTORY_READ and INSTANCE_INSPECT
GetConsoleHistory CONSOLE_HISTORY_READ and INSTANCE_INSPECT
ShowConsoleHistoryData CONSOLE_HISTORY_READ and INSTANCE_READ

and INSTANCE_IMAGE_READ
CaptureConsoleHistory CONSOLE_HISTORY_CREATE and INSTANCE_READ

and INSTANCE_IMAGE_READ
DeleteConsoleHistory CONSOLE_HISTORY_DELETE
ListCpes CPE_READ
GetCpe CPE_READ
UpdateCpe CPE_UPDATE
CreateCpe CPE_CREATE
DeleteCpe CPE_DELETE
ListCrossConnects CROSS_CONNECT_READ
GetCrossConnect CROSS_CONNECT_READ
UpdateCrossConnect CROSS_CONNECT_UPDATE
CreateCrossConnect CROSS_CONNECT_CREATE if not creating cross-

connect in a cross-connect group.
If creating the cross-connect in a cross-connect

group, also need CROSS_CONNECT_CREATE and
CROSS_CONNECT_ATTACH

CHAPTER 12 IAM
DeleteCrossConnect CROSS_CONNECT_DELETE if cross-connect is not in

a cross-connect group.
If the cross-connect is in a cross-connect group,

also need CROSS_CONNECT_DELETE and CROSS_
CONNECT_DETACH
ListCrossConnectGroups CROSS_CONNECT_GROUP_READ
GetCrossConnectGroup CROSS_CONNECT_GROUP_READ
UpdateCrossConnectGroup CROSS_CONNECT_GROUP_UPDATE
CreateCrossConnectGroup CROSS_CONNECT_GROUP_CREATE
DeleteCrossConnectGroup CROSS_CONNECT_GROUP_DELETE
ListDhcpOptions DHCP_READ
GetDhcpOptions DHCP_READ
UpdateDhcpOptions DHCP_UPDATE
CreateDhcpOptions DHCP_CREATE and VCN_ATTACH
DeleteDhcpOptions DHCP_DELETE and VCN_DETACH
ListDrgs DRG_READ
GetDrg DRG_READ
UpdateDrg DRG_UPDATE
CreateDrg DRG_CREATE
DeleteDrg DRG_DELETE

CHAPTER 12 IAM
ListDrgAttachments DRG_ATTACHMENT_READ
GetDrgAttachment DRG_ATTACHMENT_READ
UpdateDrgAttachment DRG_ATTACHMENT_UPDATE
CreateDrgAttachment DRG_ATTACH and VCN_ATTACH
DeleteDrgAttachment DRG_DETACH and VCN_DETACH
CreateInstanceConsoleConnection INSTANCE_CONSOLE_CONNECTION_CREATE and

INSTANCE_READ
DeleteInstanceConsoleConnection INSTANCE_CONSOLE_CONNECTION_DELETE
GetInstanceConsoleConnection INSTANCE_CONSOLE_CONNECTION_READ and

INSTANCE_READ
ListInstanceConsoleConnections INSTANCE_CONSOLE_CONNECTION_INSPECT and

INSTANCE_INSPECT and INSTANCE_READ
ListImages INSTANCE_IMAGE_READ
GetImage INSTANCE_IMAGE_READ
UpdateImage INSTANCE_IMAGE_UPDATE
CreateImage INSTANCE_IMAGE_CREATE and INSTANCE_

CREATE_IMAGE
The first permission is related to the instance-

image; the second is related to the instance.
DeleteImage INSTANCE_IMAGE_DELETE
ListInstances INSTANCE_GET

CHAPTER 12 IAM
GetInstance INSTANCE_GET
LaunchInstance INSTANCE_CREATE and IMAGE_READ and VNIC_

CREATE and VNIC_ATTACH and SUBNET_ATTACH
UpdateInstance INSTANCE_UPDATE
InstanceAction INSTANCE_POWER_ACTIONS
TerminateInstance INSTANCE_DELETE and VNIC_DELETE and SUBNET_

DETACH
ListInternetGateways INTERNET_GATEWAY_READ
GetInternetGateway INTERNET_GATEWAY_READ
UpdateInternetGateway INTERNET_GATEWAY_UPDATE
CreateInternetGateway INTERNET_GATEWAY_CREATE and VCN_ATTACH
DeleteInternetGateway INTERNET_GATEWAY_DELETE and VCN_DETACH
ListIPSecConnections IPSEC_CONNECTION_READ
GetIPSecConnection IPSEC_CONNECTION_READ
UpdateIpSecConnection IPSEC_CONNECTION_UPDATE
CreateIPSecConnection DRG_ATTACH and CPE_ATTACH and IPSEC_

CONNECTION_CREATE
DeleteIPSecConnection DRG_DETACH and CPE_DETACH and IPSEC_

CONNECTION_DELETE
GetIPSecConnectionDeviceConfig IPSEC_CONNECTION_CONFIDENTIAL_READ

CHAPTER 12 IAM
GetIPSecConnectionDeviceStatus IPSEC_CONNECTION_READ
ListLocalPeeringGateways LOCAL_PEERING_GATEWAY_READ
GetLocalPeeringGateway LOCAL_PEERING_GATEWAY_READ
UpdateLocalPeeringGateway LOCAL_PEERING_GATEWAY_UPDATE
CreateLocalPeeringGateway LOCAL_PEERING_GATEWAY_CREATE and VCN_

ATTACH
DeleteLocalPeeringGateway LOCAL_PEERING_GATEWAY_DELETE and VCN_

DETACH
ConnectLocalPeeringGateway LOCAL_PEERING_GATEWAY_CONNECT_FROM and
LOCAL_PEERING_GATEWAY_CONNECT_TO
ListPrivateIps PRIVATE_IP_READ
GetPrivateIp PRIVATE_IP_READ
UpdatePrivateIp PRIVATE_IP_UPDATE
CreatePrivateIp PRIVATE_IP_CREATE and PRIVATE_IP_ASSIGN and

VNIC_ASSIGN and SUBNET_ATTACH
DeletePrivateIp PRIVATE_IP_DELETE and PRIVATE_IP_UNASSIGN

and VNIC_UNASSIGN and SUBNET_DETACH
ListRemotePeeringConnections REMOTE_PEERING_CONNECTION_READ
GetRemotePeeringConnection REMOTE_PEERING_CONNECTION_READ
UpdateRemotePeeringConnection REMOTE_PEERING_CONNECTION_UPDATE

CHAPTER 12 IAM
CreateRemotePeeringConnection REMOTE_PEERING_CONNECTION_CREATE and

DRG_ATTACH
DeleteRemotePeeringConnection REMOTE_PEERING_CONNECTION_DELETE and DRG_

DETACH
ConnectRemotePeeringConnections REMOTE_PEERING_CONNECTION_CONNECT_FROM
and
REMOTE_PEERING_CONNECTION_CONNECT_TO
ListRouteTables ROUTE_TABLE_READ
GetRouteTable ROUTE_TABLE_READ
ListPublicIps For ephemeral public IPs: PRIVATE_IP_READ
For reserved public IPs: PUBLIC_IP_READ
GetPublicIp For ephemeral public IPs: PRIVATE_IP_READ
GetPublicIpByPrivateIpId For ephemeral public IPs: PRIVATE_IP_READ
GetPublicIpByIpAddress For ephemeral public IPs: PRIVATE_IP_READ
UpdatePublicIP For ephemeral public IPs: PRIVATE_IP_UPDATE
For reserved public IPs: PUBLIC_IP_UPDATE and

PRIVATE_IP_ASSIGN_PUBLIC_IP and PUBLIC_IP_
ASSIGN_PRIVATE_IP and PRIVATE_IP_UNASSIGN_
PUBLIC_IP and PUBLIC_IP_UNASSIGN_PRIVATE_IP

CHAPTER 12 IAM
CreatePublicIp For ephemeral public IPs: PRIVATE_IP_ASSIGN_

PUBLIC_IP
For reserved public IPs: PUBLIC_IP_CREATE and

PUBLIC_IP_ASSIGN_PRIVATE_IP and PRIVATE_IP_
ASSIGN_PUBLIC_IP
DeletePublicIp For ephemeral public IPs: PRIVATE_IP_UNASSIGN_

PUBLIC_IP
For reserved public IPs: PUBLIC_IP_DELETE and

PUBLIC_IP_UNASSIGN_PRIVATE_IP and PRIVATE_
IP_UNASSIGN_PUBLIC_IP

CHAPTER 12 IAM
UpdateRouteTable ROUTE_TABLE_UPDATE and
INTERNET_GATEWAY_ATTACH (if creating a route

rule that uses an internet gateway as a target) and
INTERNET_GATEWAY_DETACH (if deleting a route

DRG_ATTACH (if creating a route rule that uses a

DRG as a target) and
DRG_DETACH (if deleting a route rule that uses a

PRIVATE_IP_ROUTE_TABLE_ATTACH (if creating a

route rule that uses a private IP as a target) and
PRIVATE_IP_ROUTE_TABLE_DETACH (if deleting a

route rule that uses a private IP as a target) and
LOCAL_PEERING_GATEWAY_ATTACH (if creating a

route rule that uses an LPG as a target) and
LOCAL_PEERING_GATEWAY_DETACH (if deleting a

route rule that uses an LPG as a target)
CreateRouteTable ROUTE_TABLE_CREATE and VCN_ATTACH and
INTERNET_GATEWAY_ATTACH (if creating a route

DRG_ATTACH (if creating a route rule that uses a

PRIVATE_IP_ROUTE_TABLE_ATTACH (if creating a

route rule that uses a private IP as a target)

CHAPTER 12 IAM
DeleteRouteTable ROUTE_TABLE_DELETE and VCN_DETACH
ListSecurityLists SECURITY_LIST_READ
GetSecurityList SECURITY_LIST_READ
UpdateSecurityList SECURITY_LIST_UPDATE
CreateSecurityList SECURITY_LIST_CREATE and VCN_ATTACH
DeleteSecurityList SECURITY_LIST_DELETE and VCN_DETACH
ListShapes MACHINE_SHAPE_READ
ListSubnets SUBNET_READ
GetSubnet SUBNET_READ
UpdateSubnet SUBNET_UPDATE
CreateSubnet SUBNET_CREATE and VCN_ATTACH and ROUTE_

TABLE_ATTACH and SECURITY_LIST_ATTACH and
DHCP_ATTACH
DeleteSubnet SUBNET_DELETE and VCN_DETACH and ROUTE_

TABLE_DETACH and SECURITY_LIST_DETACH and
DHCP_DETACH
ListVcns VCN_READ
GetVcn VCN_READ
UpdateVcn VCN_UPDATE
CreateVcn VCN_CREATE

CHAPTER 12 IAM
DeleteVcn VCN_DELETE
ListVirtualCircuits VIRTUAL_CIRCUIT_READ
GetVirtualCircuit VIRTUAL_CIRCUIT_READ
UpdateVirtualCircuit VIRTUAL_CIRCUIT_UPDATE and DRG_ATTACH and

DRG_DETACH
If updating which cross-connect or cross-connect

group the virtual circuit is using, also need CROSS_
CONNECT_DETACH and CROSS_CONNECT_ATTACH
CreateVirtualCircuit VIRTUAL_CIRCUIT_CREATE and DRG_ATTACH
If creating the virtual circuit with a mapping to a

specific cross-connect or cross-connect group, also
need CROSS_CONNECT_ATTACH
DeleteVirtualCircuit VIRTUAL_CIRCUIT_DELETE and DRG_DETACH
If deleting a virtual circuit that's currently using a

cross-connect or cross-connect group, also need
CROSS_CONNECT_DETACH
GetVnic VNIC_READ
AttachVnic INSTANCE_ATTACH_SECONDARY_VNIC and VNIC_

ATTACH and VNIC_CREATE and SUBNET_ATTACH
DetachVnic INSTANCE_DETACH_SECONDARY_VNIC and VNIC_

DETACH and VNIC_DELETE and SUBNET_DETACH
UpdateVnic VNIC_UPDATE
ListVnicAttachments VNIC_ATTACHMENT_READ and INSTANCE_INSPECT

CHAPTER 12 IAM
GetVnicAttachment VNIC_ATTACHMENT_READ
ListVolumes VOLUME_INSPECT
GetVolume VOLUME_INSPECT
UpdateVolume VOLUME_UPDATE
CreateVolume VOLUME_CREATE (and VOLUME_BACKUP_READ if

creating volume from a backup)
DeleteVolume VOLUME_DELETE
ListVolumeAttachments VOLUME_ATTACHMENT_INSPECT and VOLUME_

INSPECT and INSTANCE_INSPECT
GetVolumeAttachment VOLUME_ATTACHMENT_INSPECT and VOLUME_

INSPECT and INSTANCE_INSPECT
Note: To also get the CHAP secret for the volume,

then VOLUME_ATTACHMENT_READ is required
instead of VOLUME_ATTACHMENT_INSPECT
AttachVolume VOLUME_ATTACHMENT_CREATE and VOLUME_

WRITE and INSTANCE_ATTACH_VOLUME
DetachVolume VOLUME_ATTACHMENT_DELETE and VOLUME_

WRITE and INSTANCE_DETACH_VOLUME
ListVolumeBackups VOLUME_BACKUP_INSPECT and VOLUME_INSPECT
GetVolumeBackup VOLUME_BACKUP_INSPECT and VOLUME_INSPECT
UpdateVolumeBackup VOLUME_BACKUP_UPDATE and VOLUME_INSPECT

CHAPTER 12 IAM
CreateVolumeBackup VOLUME_BACKUP_CREATE and VOLUME_WRITE
DeleteVolumeBackup VOLUME_BACKUP_DELETE and VOLUME_INSPECT
Details for the Database Service

This topic covers details for writing policies to control access to the Database service.
Resource-Types
database-family, which covers these individual resource-types:
db-systems
db-nodes
db-homes
databases
backups
Supported Variables
For example, the read and use verbs for the db-systems resource-type cover no extra
permissions or API operations compared to the inspect verb. However, the manage verb
includes two more permissions and partially covers two more API operations.

CHAPTER 12 IAM
FOR DATABASE -FAMILY RESOURCE TYPES
db-systems
INSPECT
DB_SYSTEM_INSPECT ListDbSystems none
GetDbSystem
ListDbSystemPatches
ListDbSystemPatchHistoryEntries
GetDbSystemPatch
GetDbSystemPatchHistoryEntry
READ
USE
MANAGE
USE + UpdateDBSystem LaunchDBSystem,
TerminateDbSystem (both also need

DB_SYSTEM_UPDATE
manage db-homes, manage
DB_SYSTEM_CREATE databases, use vnics, and use
subnets)
DB_SYSTEM_DELETE

CHAPTER 12 IAM
db-nodes
INSPECT
DB_NODE_INSPECT GetDbNode none
READ
USE
MANAGE
USE + USE + none
DB_NODE_POWER_ACTIONS DbNodeAction

CHAPTER 12 IAM
db-homes
INSPECT
DB_HOME_INSPECT ListDBHome none
GetDBHome
ListDbHomePatches
ListDbHomePatchHistoryEntries
GetDbHomePatch
GetDbHomePatchHistoryEntry
READ
USE
MANAGE
USE + UpdateDBHome LaunchDBSystem,

DB_HOME_CREATE
manage db-systems, manage
DB_HOME_UPDATE databases, use vnics, and use
subnets)
DB_HOME_DELETE

CHAPTER 12 IAM
databases
INSPECT
DATABASE_INSPECT ListDatabases none
GetDatabase
ListDataGuardAssociations
GetDataGuardAssociation
READ
USE
MANAGE
USE + no extra LaunchDBSystem,

DATABASE_CREATE
manage db-systems, manage db-
DATABASE_DELETE homes, use vnics, and use
subnets)

CHAPTER 12 IAM
ListDbSystems DB_SYSTEM_INSPECT
GetDbSystem DB_SYSTEM_INSPECT
LaunchDbSystem DB_SYSTEM_CREATE and DB_HOME_CREATE and

DATABASE_CREATE and VNIC_CREATE and VNIC_
ATTACH and SUBNET_ATTACH
To enable automatic backups for the initial

database, also need DB_BACKUP_CREATE and
DATABASE_CONTENT_READ
UpdateDbSystem DB_SYSTEM_INSPECT and DB_SYSTEM_UPDATE
ListDbSystemPatches DB_SYSTEM_INSPECT
ListDbSystemPatchHistoryEntries DB_SYSTEM_INSPECT
GetDbSystemPatch DB_SYSTEM_INSPECT
GetDbSystemPatchHistoryEntry DB_SYSTEM_INSPECT
TerminateDbSystem DB_SYSTEM_DELETE and DB_HOME_DELETE and

DATABASE_DELETE and VNIC_DETACH and VNIC_
DELETE and SUBNET_DETACH
If automatic backups are enabled for any database

in the DB System, also need DELETE_BACKUP
GetDbNode DB_NODE_INSPECT
DbNodeAction DB_NODE_POWER_ACTIONS
ListDbHomes DB_HOME_INSPECT
GetDbHome DB_HOME_INSPECT

CHAPTER 12 IAM
ListDbHomePatches DB_HOME_INSPECT
ListDbHomePatchHistoryEntries DB_HOME_INSPECT
GetDbHomePatch DB_HOME_INSPECT
GetDbHomePatchHistoryEntry DB_HOME_INSPECT
CreateDbHome DB_SYSTEM_INSPECT and DB_SYSTEM_UPDATE

and DB_HOME_CREATE and DATABASE_CREATE
To enable automatic backups for the database, also

need DB_BACKUP_CREATE and DATABASE_
CONTENT_READ
UpdateDbHome DB_HOME_UPDATE
DeleteDbHome DB_SYSTEM_UPDATE and DB_HOME_DELETE and

DATABASE_DELETE
If automatic backups are enabled, also need

DELETE_BACKUP
If performing a final backup on termination, also

need DB_BACKUP_CREATE and DATABASE_
CONTENT_READ
ListDatabases DATABASE_INSPECT
GetDatabase DATABASE_INSPECT
UpdateDatabase DATABASE_UPDATE
To enable automatic backups, also need DB_

BACKUP_CREATE and DATABASE_CONTENT_READ

CHAPTER 12 IAM
ListDbSystemShapes (no permissions required; available to anyone)
ListDbVersions (no permissions required; available to anyone)
GetDataGuardAssociation DATABASE_INSPECT
ListDataGuardAssociations DATABASE_INSPECT
CreateDataGuardAssociation DB_SYSTEM_UPDATE and DB_HOME_CREATE and

DB_HOME_UPDATE and DATABASE_CREATE and
DATABASE_UPDATE
SwitchoverDataGuardAssociation DATABASE_UPDATE
FailoverDataGuardAssociation DATABASE_UPDATE
ReinstateDataGuardAssociation DATABASE_UPDATE
GetBackup DB_BACKUP_INSPECT
ListBackups DB_BACKUP_INSPECT
CreateBackup DB_BACKUP_CREATE and DATABASE_CONTENT_

READ
DeleteBackup DB_BACKUP_DELETE and DB_BACKUP_INSPECT
RestoreDatabase DB_BACKUP_INSPECT and DB_BACKUP_CONTENT_

READ and DATABASE_CONTENT_WRITE
Details for the DNS Service

This topic covers details for writing policies to control access to the DNS service.

CHAPTER 12 IAM
Aggregate Resource-Type
dns
Individual Resource-Types
dns-zones
dns-records
dns-traffic
COMMENTS
A policy that uses <verb> dns is equivalent to writing one with a separate <verb>
<individual resource-type> statement for each of the individual resource-types.
API operations covered by each verb, for each individual resource-type included in dns.
Supported Variables
The DNS Service supports all the general variables (see General Variables for All Requests),
plus the ones listed here.
The dns-zones resource type can use the following variables:
Variable Variable Comments

Type
target.dns- Entity Use this variable to control access to specific DNS

zone.id (OCID) zones by OCID.
target.dns- String Use this variable to control access to specific DNS

zone.name zones by name.
The dns-records resource type can use the following variables:

CHAPTER 12 IAM

Type
target.dns- Entity Use this variable to control access to specific DNS zones
zone.id (OCID) by OCID.
target.dns- String Use this variable to control access to specific DNS zones
zone.name by name.
target.dns- String Valid values are "public" and "private".

zone.scope
target.dns- List Use this variable to control access to specific DNS

record.type (String) records by type. Valid values in the last can be any
supported DNS resource type. For example, "A",
"AAAA", "TXT", and so on. See .
target.dns- List Use this variable to control access to specific domain

domain.name (String) names. Applicable to the following API operations:
l GetDomainRecords
l PatchDomainRecords
l UpdateDomainRecords
l DeleteRRSet
l GetRRSet
l PatchRRSet
l UpdateRRSet

CHAPTER 12 IAM
For example, the use and manage verbs for the dns-traffic resource-type cover no extra
permissions or API operations compared to the read verb.
dns-zones
INSPECT
DNS_ZONE_INSPECT ListZones none
READ
INSPECT + GetZone GetZoneRecords
DNS_ZONE_READ
USE
READ + UpdateZone UpdateZoneRecords
DNS_ZONE_UPDATE PatchZoneRecords
MANAGE
UPDATE + CreateZone none
DNS_ZONE_CREATE DeleteZone
DNS_ZONE_DELETE
dns-records
INSPECT

CHAPTER 12 IAM
DNS_RECORD_INSPECT none none
READ
INSPECT + GetDomainRecords GetZoneRecords
DNS_RECORD_READ GetRRSet
USE
READ + PatchDomainRecords UpdateZoneRecords
DNS_RECORD_UPDATE UpdateDomainRecords PatchZoneRecords
DeleteRRSet
PatchRRSet
UpdateRRSet
MANAGE
UPDATE + no extra none
DNS_RECORD_CREATE
DNS_RECORD_DELETE
dns-traffic
INSPECT
none none none

CHAPTER 12 IAM
READ
INSPECT + GetDNSTrafficCounts none
DNS_TRAFFIC_READ
USE
MANAGE
ListZones DNS_ZONE_INSPECT
CreateZone DNS_ZONE_CREATE
DeleteZone DNS_ZONE_DELETE
GetZone DNS_ZONE_READ
UpdateZone DNS_ZONE_UPDATE
GetZoneRecords DNS_ZONE_READ and DNS_RECORD_READ
PatchZoneRecords DNS_ZONE_UPDATE and DNS_RECORD_UPDATE

CHAPTER 12 IAM
UpdateZoneRecords DNS_ZONE_UPDATE and DNS_RECORD_UPDATE
GetDomainRecords DNS_RECORD_READ
PatchDomainRecords DNS_RECORD_UPDATE
UpdateDomainRecords DNS_RECORD_UPDATE
DeleteRRSet DNS_RECORD_UPDATE
GetRRSet DNS_RECORD_READ
PatchRRSet DNS_RECORD_UPDATE
UpdateRRSet DNS_RECORD_UPDATE
GetDNSTrafficCounts DNS_TRAFFIC_READ
Details for the Email Service

This topic covers details for writing policies to control access to the Email service.
Resource-Types
approved-senders
suppressions
Supported Variables
The Email Service supports all the general variables (see General Variables for All Requests),
plus the ones listed here.
The approved-senders resource type can use the following variables:

CHAPTER 12 IAM

Type
target.approved- Entity (OCID)

sender.id
target.approved- String Use this variable with the APPROVED_SENDER_

sender.emailaddress USE permissions only.
For example, the use verb for the suppressions resource-type covers no extra permissions
or API operations compared to the read verb.
approved-senders
INSPECT
APPROVED_SENDER_INSPECT ListZones none
READ
INSPECT + GetSender None
APPROVED_SENDER_READ

CHAPTER 12 IAM
USE
READ + SmtpSend None
APPROVED_SENDER_USE
MANAGE
USE + CreateSender none
APPROVED_SENDER_CREATE DeleteSender
APPROVED_SENDER_DELETE
suppressions
INSPECT
SUPPRESSION_INSPECT ListSuppression none
READ
INSPECT + GetSuppression None
SUPPRESSION_READ
USE
No extra None
None

CHAPTER 12 IAM
MANAGE
USE + CreateSuppression none
SUPPRESSION_CREATE DeleteSuppression
SUPPRESSION_DELETE
ListSenders APPROVED_SENDER_INSPECT
GetSender APPROVED_SENDER_READ
CreateSender APPROVED_SENDER_CREATE
DeleteSender APPROVED_SENDER_DELETE
SmtpSend APPROVED_SENDER_USE
ListSuppression SUPPRESSION_INSPECT
GetSuppression SUPPRESSION_READ
CreateSuppression SUPPRESSION_CREATE
DeleteSuppression SUPPRESSION_DELETE
Details for the File Storage Service

This topic covers details for writing policies to control access to the File Storage Service.

CHAPTER 12 IAM
Aggregate Resource-Type
l file-family
Individual Resource-Types
l file-systems
l mount-targets
l export-sets
COMMENTS
A policy that uses <verb> file-family is equivalent to writing one with a separate <verb>
<individual resource-type> statement for each of the individual resource-types.
API operations covered by each verb, for each individual resource-type included in file-
family.
Supported Variables
extra" indicates no incremental access..
For example, the read verb for the file-systems resource-type includes the same
permissions and API operations as the inspect verb, plus the FILE_SYSTEM_READ permission
and a number of API operations (e.g., GetFileSystem, ListMountTargets, etc.). The use
verb covers still another permission and set of API operations compared to read. Lastly,
manage covers two more permissions and operations compared to use.

CHAPTER 12 IAM
export-sets
INSPECT
EXPORT_SET_INSPECT ListExportSets none
READ
EXPORT_SET_READ GetExport
GetExportSet
ListExports
USE
READ + READ + none
EXPORT_SET_UPDATE UpdateExportSet
MANAGE
USE + USE + none
EXPORT_SET_CREATE CreateExportSet
EXPORT_SET_DELETE DeleteExportSet
EXPORT_SET_UPDATE + FILE_SYSTEM_ CreateExport
NFSv3_EXPORT
DeleteExport
EXPORT_SET_UPDATE + FILE_SYSTEM_
NFSv3_EXPORT

CHAPTER 12 IAM
file-systems
INSPECT
FILE_SYSTEM_INSPECT ListFileSystems none
READ
FILE_SYSTEM_READ GetFileSystem
USE
READ + READ + none
FILE_SYSTEM_UPDATE UpdateFileSystem
MANAGE
USE + USE + none
FILE_SYSTEM_CREATE CreateFileSystem
FILE_SYSTEM_DELETE DeleteF
mount-targets
INSPECT
MOUNT_TARGET_INSPECT ListMountTargets none

CHAPTER 12 IAM
READ
MOUNT_TARGET_READ GetMountTarget
USE
READ + READ + none
MOUNT_TARGET_UPDATE UpdateMountTarget
MANAGE
USE + USE + none
MOUNT_TARGET_CREATE + VNIC_ CreateMountTarget
CREATE(vnicCompartment) + SUBNET_
DeleteMountTarget
ATTACH
(subnetCompartment) + PRIVATE_
DNS_ZONE_ATTACH
(privateDnsZoneCompartment)
MOUNT_TARGET_DELETE + VNIC_
DELETE(vnicCompartment) + SUBNET_
DETACH(subnetCompartment)
+ PRIVATE_DNS_ZONE_ATTACH
(privateDnsZoneCompartment)

CHAPTER 12 IAM
ListExports EXPORT_SET_READ
CreateExport EXPORT_SET_UPDATE + FILE_SYSTEM_NFSv3_EXPORT
GetExport EXPORT_SET_READ
DeleteExport EXPORT_SET_UPDATE + FILE_SYSTEM_NFSv3_UNEXPORT +

EXPORT_SET_READ
ListExportSets EXPORT_SET_INSPECT
CreateExportSet EXPORT_SET_CREATE
GetExportSet EXPORT_SET_READ
UpdateExportSet EXPORT_SET_UPDATE
DeleteExportSet EXPORT_SET_DELETE
ListFileSystems FILE_SYSTEM_INSPECT
CreateFileSystem FILE_SYSTEM_CREATE
GetFileSystem FILE_SYSTEM_READ
UpdateFileSystem FILE_SYSTEM_UPDATE
DeleteFileSystem FILE_SYSTEM_DELETE
ListMountTargets MOUNT_TARGET_INSPECT
CreateMountTarget MOUNT_TARGET_CREATE + VNIC_CREATE(vnicCompartment)

+ SUBNET_ATTACH(subnetCompartment) + PRIVATE_DNS_ZONE_
ATTACH(privateDnsZoneCompartment)
GetMountTarget MOUNT_TARGET_READ

CHAPTER 12 IAM
UpdateMountTarget MOUNT_TARGET_UPDATE
DeleteMountTarget MOUNT_TARGET_DELETE
Details for IAM

This topic covers details for writing policies to control access to IAM.
Resource-Types
compartments
users
groups
dynamic-groups
policies
identity-providers
tenancy
tag-namespaces
tag-definitions
Supported Variables
IAM supports all the general variables (see General Variables for All Requests), plus
additional ones listed here:

CHAPTER 12 IAM
Operations Can Use Variable Comments

for This These Type
Resource- Variables...
Type...
users target Entity Not available to use with CreateUser.

.user.id (OCID)
target String
.user.name
groups target Entity Not available to use with CreateGroup.

.group.id (OCID)
target String
.group.name
target Boolean True if request.user is a member of

. target.group.
group
.member
policies target Entity Not available to use with CreatePolicy.

.policy.id (OCID)
target String
.
policy.name
target Boolean Whether the policy being acted upon uses "Keep
. policy current" as its version date (i.e., either
policy null or an empty string for the versionDate
.autoupdate parameter in CreatePolicy and UpdatePolicy).

CHAPTER 12 IAM
Operations Can Use Variable Comments

for This These Type
Resource- Variables...
Type...
compartments target. Entity For CreateCompartment, this will be the value

compartment (OCID) of the parent compartment (e.g., the root
.id compartment).
This is a universal variable available to use with

any request across all services (see General
Variables for All Requests).
target. String
compartment
.name
tag- target.tag- Entity Not available to use with CreateTagNamespace.

namespaces namespace (OCID)
.id
target.tag- String
namespace
.name
Details for Verbs + Resource-Type Combinations
For example, the read verb for compartments covers no extra permissions or API operations
compared to the inspect verb. The use verb includes the same ones as the read verb, plus
the COMPARTMENT_UPDATE permission and UpdateCompartment API operation. The manage
verb includes the same permissions and API operations as the use verb, plus the

CHAPTER 12 IAM
COMPARTMENT_CREATE permission and two API operations: CreateCompartment and

DeleteCompartment
compartments
INSPECT
COMPARTMENT_INSPECT ListCompartments none
GetCompartment
READ
USE
READ + READ + none
COMPARTMENT_UPDATE UpdateCompartment
MANAGE
USE + USE + none
COMPARTMENT_CREATE CreateCompartment
DeleteCompartment

CHAPTER 12 IAM
users
INSPECT
USER_INSPECT ListUsers GetUserGroupMembership (also need
inspect groups)
GetUser
READ
INSPECT + INSPECT + no extra
USER_READ ListApiKeys
ListSwiftPasswords
ListCustomerSecretKeys
USE
USER_UPDATE UpdateUser AddUserToGroup (also need use
groups)
RemoveUserFromGroup (also need use
groups)

CHAPTER 12 IAM
MANAGE
USE + USE + no extra
USER_CREATE UpdateUserState
USER_DELETE CreateUser
USER_UNBLOCK DeleteUser
USER_APIKEY_ADD UploadApiKey
USER_APIKEY_REMOVE DeleteApiKey
USER_UIPASS_SET CreateOrResetUIPassword
USER_UIPASS_RESET UpdateSwiftPassword
USER_SWIFTPASS_SET CreateSwiftPassword
USER_SWIFTPASS_RESET DeleteSwiftPassword
USER_SWIFTPASS_REMOVE CreateSecretKey
USER_SECRETKEY_ADD UpdateCustomerSecretKey
USER_SECRETKEY_UPDATE DeleteCustomerSecretKey
USER_SECRETKEY_REMOVE

CHAPTER 12 IAM
groups
INSPECT
GROUP_INSPECT ListGroups GetUserGroupMembership (also need
inspect users)
GetGroup
ListIdpGroupMappings,
GetIdpGroupMapping (both also need
inspect identity-providers)
READ
USE
GROUP_UPDATE UpdateGroup AddUserToGroup (also need use
users)
RemoveUserFromGroup (also need use
users)
AddIdpGroupMapping,
DeleteIdpGroupMapping (both also
need manage identity-providers)

CHAPTER 12 IAM
MANAGE
GROUP_CREATE CreateGroup
GROUP_DELETE DeleteGroup
dynamic-groups
INSPECT
DYNAMIC_GROUP_INSPECT ListDynamicGroups No extra
GetDynamicGroup
READ
USE
READ + READ + No extra
DYNAMIC_GROUP_UPDATE UpdateDynamicGroup
MANAGE
DYNAMIC_GROUP_CREATE CreateDynamicGroup
DYNAMIC_GROUP_DELETE DeleteDynamicGroup

CHAPTER 12 IAM
policies
INSPECT
POLICY_READ ListPolicies none
GetPolicy
READ
USE
Note: The ability to update policies is
available only with manage policies.
MANAGE
USE + USE + none
POLICY_UPDATE UpdatePolicy
POLICY_CREATE CreatePolicy
POLICY_DELETE DeletePolicy

CHAPTER 12 IAM
identity-providers
INSPECT
IDENTITY_PROVIDER_INSPECT ListIdentityProviders ListIdpGroupMappings,
GetIdpGroupMapping (both also need

GetIdentityProvider
inspect groups)
READ
USE
MANAGE
USE + USE + USE +
IDENTITY_PROVIDER_UPDATE UpdateIdentityProvider AddIdpGroupMapping,
DeleteIdpGroupMapping (both also

IDENTITY_PROVIDER_CREATE CreateIdentityProvider
need use groups)
IDENTITY_PROVIDER_DELETE DeleteIdentityProvider

CHAPTER 12 IAM
tenancy
INSPECT
TENANCY_INSPECT ListRegionSubscriptions none
GetTenancy
ListRegions
READ
USE
READ + no extra none
TENANCY_UPDATE
MANAGE
USE + USE + none
TENANCY_UPDATE CreateRegionSubscription

CHAPTER 12 IAM
tag-namespaces
INSPECT
TAG_NAMESPACE_INSPECT ListTagNamespaces none
GetTagNamespace
READ
USE
READ + READ + none
TAG_NAMESPACE_UPDATE UpdateTagNamespace
MANAGE
USE + USE + none
TAG_NAMESPACE_CREATE CreateTagNamespace

CHAPTER 12 IAM
tag-definitions
INSPECT
TAG_DEFINITION_INSPECT ListTagDefinitions none
GetTagDefinition
READ
USE
READ + READ + none
TAG_DEFINITION_UPDATE UpdateTagDefinition
MANAGE
USE + USE + none
TAG_DEFINITION_CREATE CreateTagDefinition

CHAPTER 12 IAM
ListRegions TENANCY_INSPECT
ListRegionSubscriptions TENANCY_INSPECT
CreateRegionSubscription TENANCY_UPDATE
GetTenancy TENANCY_INSPECT
ListAvailabilityDomains COMPARTMENT_INSPECT
ListCompartments COMPARTMENT_INSPECT
GetCompartment COMPARTMENT_INSPECT
UpdateCompartment COMPARTMENT_UPDATE
CreateCompartment COMPARTMENT_CREATE
ListUsers USER_INSPECT
GetUser USER_INSPECT
UpdateUser USER_UPDATE
UpdateUserState USER_UPDATE and USER_UNBLOCK
CreateUser USER_CREATE
DeleteUser USER_DELETE
CreateOrResetUIPassword USER_UPDATE and USER_UIPASS_RESET
ListApiKeys USER_READ
UploadApiKey USER_UPDATE and USER_APIKEY_ADD
DeleteApiKey USER_UPDATE and USER_APIKEY_REMOVE

CHAPTER 12 IAM
ListSwiftPasswords USER_READ
UpdateSwiftPassword USER_UPDATE and USER_SWIFTPASS_RESET
CreateSwiftPassword USER_UPDATE and USER_SWIFTPASS_SET
DeleteSwiftPassword USER_UPDATE and USER_SWIFTPASS_REMOVE
ListCustomerSecretKeys USER_READ
CreateSecretKey USER_UPDATE and USER_SECRETKEY_ADD
UpdateCustomerSecretKey USER_UPDATE and USER_SECRETKEY_UPDATE
DeleteCustomerSecretKey USER_UPDATE and USER_SECRETKEY_REMOVE
ListUserGroupMemberships GROUP_INSPECT and USER_INSPECT
GetUserGroupMembership USER_INSPECT and GROUP_INSPECT
AddUserToGroup GROUP_UPDATE and USER_UPDATE
RemoveUserFromGroup GROUP_UPDATE and USER_UPDATE
ListGroups GROUP_INSPECT
GetGroup GROUP_INSPECT
UpdateGroup GROUP_UPDATE
CreateGroup GROUP_CREATE
DeleteGroup GROUP_DELETE
ListDynamicGroups DYNAMIC_GROUP_INSPECT
GetDynamicGroup DYNAMIC_GROUP_INSPECT

CHAPTER 12 IAM
UpdateDynamicGroup DYNAMIC_GROUP_UPDATE
CreateDynamicGroup DYNAMIC_GROUP_CREATE
DeleteDynamicGroup DYNAMIC_GROUP_DELETE
ListPolicies POLICY_READ
GetPolicy POLICY_READ
UpdatePolicy POLICY_UPDATE
CreatePolicy POLICY_CREATE
DeletePolicy POLICY_DELETE
ListIdentityProviders IDENTITY_PROVIDER_INSPECT
GetIdentityProvider IDENTITY_PROVIDER_INSPECT
UpdateIdentityProvider IDENTITY_PROVIDER_UPDATE
CreateIdentityProvider IDENTITY_PROVIDER_CREATE
DeleteIdentityProvider IDENTITY_PROVIDER_DELETE
ListIdpGroupMappings IDENTITY_PROVIDER_INSPECT and GROUP_INSPECT
GetIdpGroupMapping IDENTITY_PROVIDER_INSPECT and GROUP_INSPECT
AddIdpGroupMapping IDENTITY_PROVIDER_UPDATE and GROUP_UPDATE
DeleteIdpGroupMapping IDENTITY_PROVIDER_UPDATE and GROUP_UPDATE
ListTagNamespaces TAG_NAMESPACE_INSPECT
GetTagNamespace TAG_NAMESPACE_INSPECT

CHAPTER 12 IAM
CreateTagNamespace TAG_NAMESPACE_CREATE
UpdateTagNamespace TAG_NAMESPACE_UPDATE
ListTagDefinitions TAG_DEFINITION_INSPECT
GetTagDefinition TAG_DEFINITION_INSPECT
CreateTagDefinition TAG_DEFINITION_CREATE
UpdateTagDefinition TAG_DEFINITION_UPDATE
Details for Load Balancing

This topic covers details for writing policies to control access to the Load Balancing service.
Resource-Types
load-balancers
Supported Variables
extra" indicates no incremental access..
For example, the read verb for load-balancers includes the same permissions and API
operations as the inspect verb, plus the LOAD_BALANCER_READ permission and a number of
API operations (e.g., GetLoadBalancer, ListWorkRequests, etc.). The use verb covers still

CHAPTER 12 IAM
another permission and set of API operations compared to read. And manage covers two more
permissions and operations compared to use.
LOAD-BALANCERS
INSPECT
LOAD_BALANCER_INSPECT ListLoadBalancers none
ListShapes
ListPolicies
ListProtocols
READ
LOAD_BALANCER_READ GetLoadBalancer
ListWorkRequests
GetWorkRequest
ListBackendSets
GetBackendSet
ListBackends
GetBackend
GetHealthChecker
ListCertificates

CHAPTER 12 IAM
USE
READ + READ + none
LOAD_BALANCER_UPDATE UpdateLoadBalancer
UpdateBackendSet
CreateBackendSet
DeleteBackendSet
UpdateBackend
CreateBackend
DeleteBackend
UpdateHealthChecker
CreateCertificate
DeleteCertificate
UpdateListener
CreateListener
DeleteListener
MANAGE
USE + USE + none
LOAD_BALANCER_CREATE CreateLoadBalancer
LOAD_BALANCER_DELETE DeleteLoadBalancer

CHAPTER 12 IAM
ListLoadBalancers LOAD_BALANCER_INSPECT
GetLoadBalancer LOAD_BALANCER_READ
UpdateLoadBalancer LOAD_BALANCER_UPDATE
CreateLoadBalancer LOAD_BALANCER_CREATE
DeleteLoadBalancer LOAD_BALANCER_DELETE
ListShapes LOAD_BALANCER_INSPECT
ListWorkRequests LOAD_BALANCER_READ
GetWorkRequest LOAD_BALANCER_READ
ListBackendSets LOAD_BALANCER_READ
GetBackendSet LOAD_BALANCER_READ
UpdateBackendSet LOAD_BALANCER_UPDATE
CreateBackendSet LOAD_BALANCER_UPDATE
DeleteBackendSet LOAD_BALANCER_UPDATE
ListBackends LOAD_BALANCER_READ
GetBackend LOAD_BALANCER_READ
UpdateBackend LOAD_BALANCER_UPDATE
CreateBackend LOAD_BALANCER_UPDATE
DeleteBackend LOAD_BALANCER_UPDATE

CHAPTER 12 IAM
GetHealthChecker LOAD_BALANCER_READ
UpdateHealthChecker LOAD_BALANCER_UPDATE
ListCertificates LOAD_BALANCER_READ
CreateCertificate LOAD_BALANCER_UPDATE
DeleteCertificate LOAD_BALANCER_UPDATE
UpdateListener LOAD_BALANCER_UPDATE
CreateListener LOAD_BALANCER_UPDATE
DeleteListener LOAD_BALANCER_UPDATE
ListPolicies LOAD_BALANCER_INSPECT
ListProtocols LOAD_BALANCER_INSPECT
Details for Object Storage

This topic covers details for writing policies to control access to Object Storage.
Resource-Types
object-family, which covers these individual resource-types:
buckets
objects
Supported Variables
Object Storage supports all the general variables (see General Variables for All Requests),
plus the one listed here:

CHAPTER 12 IAM
Operations Can Use This Variable Comments

for This Variable Type
Resource-
Type...
buckets target.bucket.name String Use this variable to control access to

specific buckets. For an example
policy, see Let users write objects to
Object Storage buckets.
For example, the read verb for buckets includes the same permissions and API operations as
the inspect verb, plus the BUCKET_READ permission and GetBucket API operation. The use
verb covers still another permission and API operation compared to read. And manage covers
two more permissions and operations compared to use.
FOR OBJECT -FAMILY RESOURCE TYPES
buckets
INSPECT
BUCKET_INSPECT HeadBucket none
ListBuckets

CHAPTER 12 IAM
READ
BUCKET_READ GetBucket
ListMultipartUploads
USE
READ + READ + none
BUCKET_UPDATE UpdateBucket
MANAGE
USE + USE + none
BUCKET_CREATE CreateBucket
BUCKET_DELETE DeleteBucket
PAR_MANAGE CreatePar
GetPar
ListPar
DeletePar

CHAPTER 12 IAM
objects
INSPECT
OBJECT_INSPECT HeadObject none
ListObjects
ListMultipartUploadParts
READ
OBJECT_READ GetObject
USE
OBJECT_OVERWRITE OverwriteObject CreateMultipartUpload,
UploadPart, CommitMultipartUpload
(all also need manage objects)

CHAPTER 12 IAM
MANAGE
USE + USE + none
OBJECT_CREATE CreateObject
OBJECT_DELETE DeleteObject
CreateMultipartUpload
UploadPart
CommitMultipartUpload
AbortMultipartUpload
CreateBucket BUCKET_CREATE
UpdateBucket BUCKET_UPDATE
GetBucket BUCKET_READ
HeadBucket BUCKET_INSPECT
ListBuckets BUCKET_INSPECT
DeleteBucket BUCKET_DELETE
CreateObject OBJECT_CREATE

CHAPTER 12 IAM
OverwriteObject OBJECT_OVERWRITE
GetObject OBJECT_READ
HeadObject OBJECT_READ or OBJECT_INSPECT
DeleteObject OBJECT_DELETE
ListObjects OBJECT_INSPECT
CreateMultipartUpload OBJECT_CREATE and OBJECT_OVERWRITE
UploadPart OBJECT_CREATE and OBJECT_OVERWRITE
CommitMultipartUpload OBJECT_CREATE and OBJECT_OVERWRITE
ListMultipartUploadParts OBJECT_INSPECT
ListMultipartUploads BUCKET_READ
AbortMultipartUpload OBJECT_DELETE
CreatePar PAR_MANAGE
GetPar PAR_MANAGE
ListPar PAR_MANAGE
DeletePar PAR_MANAGE

CHAPTER 12 IAM
User Credentials
There are several types of credentials that you manage with Oracle Cloud Infrastructure
Identity and Access Management (IAM):
l Console password: For signing in to the Console, the user interface for interacting
with Oracle Cloud Infrastructure.
l API signing key (in PEM format): For sending API requests, which require
authentication.
l Swift password: For using a Swift client with Recovery Manager (RMAN) to back up an
Oracle Database System (DB System) database to Object Storage.
l Amazon S3 Compatibility API Keys - For using the Amazon S3 Compatibility API
with Object Storage. See Amazon S3 Compatibility API .
l SMTP Credentials - For using the Email Delivery service.
Important
API signing keys are different from the SSH keys you
use to access a compute instance (see Security
Credentials). For more information about API signing
keys, see Required Keys and OCIDs. For more
information about instance SSH keys, see Managing Key
Pairs.
User Password
The administrator who creates a new user in IAM also needs to generate a one-time Console
password for the user (see To create or reset a user's Console password). The administrator
needs to securely deliver the password to the user by providing it verbally, printing it out, or
sending it through a secure email service.

CHAPTER 12 IAM
When the user signs in to the Console the first time, they'll be immediately prompted to
change the password. If the user waits more than 7 days to initially sign in and change the
password, it will expire and an administrator will need to create a new one-time password for
the user.
Once the user successfully signs in to the Console, they can use Oracle Cloud Infrastructure
resources according to permissions they've been granted through policies.
Note
A user automatically has the ability to change their

password in the Console. An administrator does not
need to create a policy to give a user that ability.
Changing a Password
If a user wants to change their own password sometime after they change their initial one-
time password, they can do it in the Console. Remember that a user can automatically change
their own password; an administrator does not need to create a policy to give the user that
ability.
For more information, see To change your Console password.
If a User Needs Their Console Password Reset
If a user forgets their Console password and also has no access to the API, they need to ask
an administrator to reset their password for them. All administrators (and anyone else who
has permission to the tenancy) can reset Console passwords. The process of resetting the
password generates a new one-time password that the administrator needs to deliver to the
user. The user will need to change their password the next time they sign in to the Console.
If you're an administrator who needs to reset a user's Console password, see To create or
reset a user's Console password.

CHAPTER 12 IAM
If a User Is Blocked from Signing In to the Console
If a user tries 10 times in a row to sign in to the Console unsuccessfully, they will be
automatically blocked from further attempts. They'll need to contact an administrator to get
unblocked (see To unblock a user).
API Signing Keys

A user who needs to make API requests must upload an RSA public key in PEM format
(minimum 2048 bits) to IAM and sign the API requests with the corresponding private key
(see Required Keys and OCIDs).
Important
A user automatically has the ability to upload and

manage their own API keys in the Console or API. An
administrator does not need to write a policy to give the
user that ability. Remember that a user can't use the
API to change or delete their own credentials until they
themselves upload a key in the Console, or an
administrator uploads a key for that user in the Console
or the API.
If you have a non-human system that needs to make API requests, an administrator needs to
create a user for that system and then upload a public key to the IAM service for the system.
There's no need to generate a Console password for the user.
For instructions on uploading an API key, see To upload an API signing key.
Swift Passwords
Swift is the OpenStack object store service. If you already have an existing Swift client, you
can use it with the Recovery Manager (RMAN) to back up an Oracle Database System (DB

CHAPTER 12 IAM
System) database to Object Storage. You will need to get a Swift-specific password to do so.
For more information, see Working with Swift Passwords.
Identity Providers and Federation

This topic describes how to federate with a supported identity provider. Oracle Cloud
Infrastructure supports federation with Oracle Identity Cloud Service and Microsoft Active
Directory (via Active Directory Federation Services (AD FS)), using the Security Assertion
Markup Language (SAML) 2.0 protocol.
Overview
Enterprise companies commonly use an identity provider (IdP) to manage user
login/passwords and to authenticate users for access to secure websites, services, and
resources.
When someone in your company wants to use Oracle Cloud Infrastructure resources in the
Console, they must sign in with a user login and password. Your administrators can federate
with a supported IdP so that each employee can use an existing login and password and not
have to create a new set to use Oracle Cloud Infrastructure resources.
To federate, an administrator goes through a short process to set up a relationship between

the IdP and Oracle Cloud Infrastructure (commonly referred to as a federation trust). After an
administrator sets up that relationship, any person in your company who goes to the Oracle
Cloud Infrastructure Console is prompted with a "single sign-on" experience provided by the
IdP. The user signs in with the login/password that they've already set up with the IdP and use
elsewhere. The IdP authenticates the user, and then that user can access Oracle Cloud
Infrastructure.
When working with your IdP, your administrator defines groups and assigns each user to one
or more groups according to the type of access the user needs. Oracle Cloud Infrastructure
also uses the concept of groups (in conjunction with IAM policies) to define the type of access
a user has. As part of setting up the relationship with the IdP, your administrator can map
each IdP group to a similarly defined IAM group, so that your company can re-use the IdP

CHAPTER 12 IAM
group definitions when authorizing user access to Oracle Cloud Infrastructure resources.
Here's a screenshot from that process:
For information about the number of federations and group mappings you can have, see
Service Limits. There's no limit on the number of federated users.
Note
Any users who are in more than 50 IdP groups cannot be

authenticated to use the Oracle Cloud Infrastructure
Console.
General Concepts
Here's a list of the basic concepts you need to be familiar with.
IDP
IdP is short for identity provider, which is a service that provides identifying credentials
and authentication for users. Oracle Cloud Infrastructure supports identity federation with
Oracle Identity Cloud Service.

CHAPTER 12 IAM
SERVICE PROVIDER (SP)

A service (such as an application, website, etc.) that calls upon an IdP to authenticate
users. In this case, Oracle Cloud Infrastructure is the SP.
FEDERATION TRUST
A relationship that an administrator configures between an IdP and SP. You can use the
Oracle Cloud Infrastructure Console or API to set up that relationship. Then, the specific
IdP is "federated" to that SP. In the Console and API, the process of federating is thought
of as adding an identity provider to the tenancy.
SAML METADATA DOCUMENT
An IdP-provided XML-based document that provides the required information to an SP to

federate with that IdP. Oracle Cloud Infrastructure supports the SAML 2.0 protocol, which
is an XML-based standard for sharing required information between the IdP and SP.
Depending on which idP you are federating with, you must either provide the metadata
URL (see below) to this document or upload the document to Oracle Cloud Infrastructure.
METADATA URL
An IdP-provided URL that enables an SP to get required information to federate with that
IdP. Oracle Cloud Infrastructure supports the SAML 2.0 protocol, which is an XML-based
standard for sharing required information between the IdP and SP. The metadata URL
points to the SAML metadata document the SP needs.
FEDERATED USER
Someone who signs in to use the Oracle Cloud Infrastructure Console by way of a
federated IdP.
ORACLE CLOUD INFRASTRUCTURE USER

A non-federated user. In other words, someone who signs in to use the Oracle Cloud
Infrastructure Console with a login and password created in Oracle Cloud Infrastructure.
GROUP MAPPING
A mapping between an IdP group and an Oracle Cloud Infrastructure group, used for the
purposes of user authorization.

CHAPTER 12 IAM
Experience for Federated Users

Federated users can use the Console to access Oracle Cloud Infrastructure (according to IAM
policies for the groups the users are in).
They'll be prompted to enter their Oracle Cloud Infrastructure tenant (e.g., ABCCorp).
They then see a page with two sets of sign-in instructions: one for federated users and one for
non-federated (Oracle Cloud Infrastructure) users. See the following screenshot.
The tenant is shown on the left. Directly below is the sign-in area for federated users. On the
right is the sign-in area for non-federated users.
Federated users choose which identity provider to use for sign-in, and then they're redirected
to that identity provider's sign-in experience for authentication. After entering their login and

CHAPTER 12 IAM
password, they are authenticated by the IdP and redirected back to the Oracle Cloud
Infrastructure Console.
Unlike Oracle Cloud Infrastructure users, federated users cannot access the "User Settings"
page in the Console. This page is where a user can change or reset their Console password
and manage other Oracle Cloud Infrastructure credentials such as API signing keys and Swift
passwords.
Required IAM Policy

To add and manage identity providers in your tenancy, you must be authorized by an IAM
policy. If you're in the Administrators group, then you have the required access.
Here's a more limited policy that restricts access to only the resources related to identity
providers and group mappings:
Allow group IdPAdmins to manage identity-providers in tenancy
Allow group IdPAdmins to manage groups in tenancy
to dig deeper into writing policies for groups or other IAM components, see Details for IAM.
Supported Identity Providers

For instructions for federating with Oracle Identity Cloud Service, see Federating with Oracle
Identity Cloud Service.
For instructions for federating with Microsoft Active Directory, see Federating with Microsoft
Active Directory.
Federating with Oracle Identity Cloud Service

This topic describes how to federate Oracle Cloud Infrastructure with Oracle Identity Cloud
Service, using the Security Assertion Markup Language (SAML) 2.0 protocol.

CHAPTER 12 IAM
Note
Before following the steps in this topic, see Identity

Providers and Federation to ensure that you understand
general federation concepts.
About Federating with Oracle Identity Cloud Service
Your organization can have multiple Oracle Identity Cloud Service accounts (e.g., one for each
division of the organization). You can federate multiple Identity Cloud Service accounts with
Oracle Cloud Infrastructure, but each federation trust that you set up must be for a single
Identity Cloud Service account.
W EB APPLICATION AND CLIENT CREDENTIALS
For each trust, you must set up a web application in Oracle Identity Cloud Service (also called
a trusted application); instructions are in Instructions for Federating. The resulting application
has a set of client credentials (a client ID and client secret). When you federate your Identity
Cloud Service account with Oracle Cloud Infrastructure, you must provide these credentials. If
you need to later update the group mappings, you'll have to provide the credentials again.
REQUIRED URLS
The easiest way to federate with Oracle Identity Cloud Service is through the Oracle Cloud
Infrastructure Console, although you could do it programmatically with the API. If you're
using the Console, you're asked to provide a base URL instead of the metadata URL. The base
URL is the left-most part of the URL in the browser window when you're signed in to the
Identity Cloud Service console:
l Base URL: <Identity Cloud Service account name>.identity.oraclecloud.com
If you're using the API to federate, you need to provide the metadata URL, which is the base
URL with /fed/v1/metadata appended, like so:

CHAPTER 12 IAM
l Metadata URL: <Identity Cloud Service account

name>.identity.oraclecloud.com/fed/v1/metadata
The metadata URL links directly to the IdP-provided XML required to federate. If you're using
the API, you need to provide both the metadata URL and the metadata itself when federating.
For more information, see Managing Identity Providers in the API.
BMCS-SAML-APP
When you federate an Oracle Identity Cloud Service account with Oracle Cloud Infrastructure,
a new SAML application called BMCS-SAML-App-<your_OCI_tenancy> is automatically
created in that Oracle Identity Cloud Service account (see the following screenshot). If you
later need to delete the Oracle Identity Cloud Service identity provider from your Oracle Cloud
Infrastructure tenancy, make sure to also delete the BMCS-SAML-App-<your_OCI_tenancy>
from Oracle Identity Cloud Service. If you don't, and you later try to federate the same Oracle
Identity Cloud Service account again, you'll get a 409 error saying that an application with the
same name already exists (i.e., BMCS-SAML-App-<your_OCI_tenancy>).
Instructions for Federating
Following is the general process an administrator goes through to set up the identity provider,
and below are instructions for each step. It's assumed that the administrator is an Oracle
Cloud Infrastructure user with the required credentials and access.
1. Get required information from the IdP.

2. Federate the IdP with Oracle Cloud Infrastructure:
a. Add the identity provider to your tenancy and provide information you got from
the IdP.

CHAPTER 12 IAM
b. Map the IdP's groups to IAM groups.

3. Make sure you have IAM policies set up for the groups so you can control users' access
to Oracle Cloud Infrastructure resources.
4. Inform your users of the name of your Oracle Cloud Infrastructure tenant and the URL
for the Console (for example, https://console.us-ashburn-1.oraclecloud.com).
Step 1: Get required information from the IdP

Summary: Go to the IdP's website and get the information that Oracle needs. For Oracle
Identity Cloud Service, you need to create a web application (also referred to as a trusted
application) with particular properties described in the following instructions. For the general
Oracle Identity Cloud Service documentation, see Adding a Trusted Application.
Instructions for Oracle Identity Cloud Service:
1. Go to the Oracle Identity Cloud Service console and sign in to the account you want to
federate. Make sure you're viewing the Admin Console.
2. Add a web (or trusted) application, which enables secure, programmatic interaction
between Oracle Cloud Infrastructure and Oracle Identity Cloud Service. Specify these
items when setting up the application:
a. On the first page:
i. Enter an application a name (e.g., Oracle Cloud Infrastructure Federation).
ii. Leave other fields empty or unselected.
b. On the next page:
i. Select Configure this application as a client now.
ii. For the Allowed Grant Types, select the check box for Client
Credentials.
iii. Leave other fields empty.

CHAPTER 12 IAM
iv. At the bottom of the page, select the check box for Grant the client
access to Identity Cloud Service Admin APIs, and then select
Identity Domain Administrator from the list of roles.
c. On the next page, leave any fields empty or unselected and continue until you
click Finish.
d. Copy and paste the displayed client credentials so you can later give them to
Oracle Cloud Infrastructure when federating. You can view the application's client
credentials any time in the Oracle Identity Cloud Service console. They look
similar to this:
l Client ID: de06b81cb45a45a8acdcde923402a9389d8
l Client Secret: 8a297afd-66df-49ee-c67d-39fcdf3d1c31
3. Record the Oracle Identity Cloud Service base URL, which you'll need when federating.
See About Federating with Oracle Identity Cloud Service.
4. Activate the application.
Step 2: Federate the IdP with Oracle Cloud Infrastructure

Summary: Add the identity provider to your tenancy. You can set up the group mappings at
the same time, or set them up later.
Instructions for Oracle Identity Cloud Service:
1. Go to the Console and sign in with your Oracle Cloud Infrastructure login and password.
2. Click Identity, and then click Federation.
3. Click Add identity provider.
a. Name: A unique name for this federation trust (e.g., ABCCorp_IDCS in the
screenshot in Experience for Federated Users). This is the name federated users
see when choosing which identity provider to use when signing in to the Console.
The name must be unique across all identity providers you add to the tenancy.

CHAPTER 12 IAM
You cannot change this later.

b. Description: A friendly description.
c. IDCS Base URL: See About Federating with Oracle Identity Cloud Service.
d. Client ID: From Step 1: Get required information from the IdP.
e. Client secret: From Step 1: Get required information from the IdP.
5. Click Continue.
6. Set up the mappings between Oracle Identity Cloud Service groups and IAM groups in
Oracle Cloud Infrastructure. A given Oracle Identity Cloud Service group can be mapped
to zero, one, or multiple IAM Service groups, and vice versa. However, each individual
mapping is between only a single Oracle Identity Cloud Service group and a single IAM
group. Changes to group mappings take effect typically within seconds.
Note
If you don't want to set up the group mappings now,

you can simply click Create and come back to add
the mappings later. When you return later to add
the mappings or any time you edit them, you'll be
prompted to provide the client ID and client secret
for your Oracle Identity Cloud Service application
again.
To create a group mapping:

a. Select the Oracle Identity Cloud Service group from the list under Identity
Provider Group.
b. Select the IAM group you want to map from the list under Oracle Cloud
Infrastructure Group. If you instead want to create a new IAM group, select
New OCI Group and enter the name of the new group in New OCI Group
Name. The new group will be automatically created in IAM and mapped to the

CHAPTER 12 IAM
Oracle Identity Cloud Service group. It will also automatically be given this
description, which you can't change: "Group created during federation".
Tip
Requirements for IAM group name: No spaces.

Allowed characters: letters, numerals,
hyphens, periods, underscores, and plus signs
(+). The name cannot be changed later.
c. Repeat the above sub-steps for each mapping you want to create, and then click
Create.
The identity provider is now added to your tenancy and appears in the list on the Federation
page. Click the identity provider to view its details and the group mappings you just set up.
Oracle assigns the identity provider and each group mapping a unique ID called an Oracle
Cloud ID (OCID). For more information, see Resource Identifiers.
In the future, come to the Federation page if you want to edit the group mappings or delete
the identity provider from your tenancy.
Step 3: Set up IAM policies for the groups

If you haven't already, set up IAM policies to control the access the federated users have to
your organization's Oracle Cloud Infrastructure resources. For more information, see Getting
Started with Policies and Common Policies.
Step 4: Give your federated users the name of the tenant and URL to sign in
The federated users need the URL for the Oracle Cloud Infrastructure Console (for example,
https://console.us-ashburn-1.oraclecloud.com) and the name of your tenant. They'll be
prompted to provide the tenant name when they sign in to the Console.

CHAPTER 12 IAM
Managing Identity Providers in the Console
To add an identity provider

See Instructions for Federating.
To delete an identity provider

All the group mappings for the identity provider will also be deleted.
1. Delete the identity provider from your tenancy:

a. Open the Console, click Identity, and then click Federation.
A list of the identity providers in your tenancy is displayed.
b. Click the identity provider to view its details.
c. Click Delete.
d. Confirm when prompted.
2. Delete the BMCS-SAML-App from your Oracle Identity Cloud Service account:
a. Go to Oracle Identity Cloud Service and sign in to the federated account.
b. Click Applications. The list of applications is displayed.
c. Locate the BMCS-SAML-App-<your_OCI_tenancy> and click its name to view its
details page.
d. In the upper right of the page, click Deactivate. Confirm when prompted.
e. Click Remove. Confirm when prompted.
To add group mappings for an identity provider

1. Open the Console, click Identity, and then click Federation.
2. Click the identity provider to view its details.

CHAPTER 12 IAM
3. Click Edit Mapping.

4. When prompted, provide the client ID and client secret for the Oracle Identity Cloud
Service application, and then click Continue.
5. Add at least one mapping:
a. Click + Add Mapping.
b. Select the Oracle Identity Cloud Service group from the list under Identity
Provider Group.
c. Select the IAM group you want to map from the list under Oracle Cloud
Oracle Identity Cloud Service group. It will also automatically be given this
description, which you can't change: "Group created during federation".
d. Repeat the above sub-steps for each mapping you want to create, and then click
Submit.
Your changes take effect typically within seconds in your home region. Wait several more
minutes for changes to propagate to all regions
To update a group mapping

Service application, and then click Continue.
5. Update the mappings (or click the X to delete a mapping), and then click Submit.

CHAPTER 12 IAM
minutes for changes to propagate to all regions
To delete a group mapping

3. For the mapping you want to delete, click Delete next to it.
minutes for changes to propagate to all regions.
Managing Identity Providers in the API
Use these API operations:
Identity providers:
l CreateIdentityProvider
l ListIdentityProviders
l GetIdentityProvider
l UpdateIdentityProvider
l DeleteIdentityProvider: Before you can use this operation, you must first use
DeleteIdpGroupMapping to remove all the group mappings for the identity provider.
Group mappings:
l CreateIdpGroupMapping: Each group mapping is a separate entity with its own OCID.
l ListIdpGroupMappings

CHAPTER 12 IAM
l GetIdpGroupMapping
l UpdateIdpGroupMapping
l DeleteIdpGroupMapping
Adding Groups and Users for Tenancies Federated with Oracle Identity
Cloud Service
This topic describes how to add groups and users for Oracle Cloud Infrastructure through the
Oracle Identity Cloud Service.
When your tenancy is federated with Oracle Identity Cloud Service, you must perform
administrative tasks for your users and groups in both Oracle Identity Cloud Service and
In Oracle Identity Cloud Service you manage groups and users.
In Oracle Cloud Infrastructure, you create policies to grant members of the groups access to
the Oracle Cloud Infrastructure resources.
Each group you create in Oracle Identity Cloud Service must be mapped to a group in Oracle
Cloud Infrastructure. Before you set up any new groups in Oracle Identity Cloud Service,
ensure that you understand how to assign permissions to groups in Oracle Cloud
Infrastructure. See Overview of IAM.

CHAPTER 12 IAM
Adding Groups in Oracle Identity Cloud Service

CHAPTER 12 IAM

CHAPTER 12 IAM
TASKS TO PERFORM IN THE I DENTITY CLOUD S ERVICE CONSOLE
Add a new group in Oracle Identity Cloud Service

To add a group in Oracle Identity Cloud Service:
1. Sign in to the Oracle Identity Cloud Service console through My Services.

2. Click Users.
3. In the Identity Cloud Service console, on the Groups tile, click the Add a Group icon.
4. In the Add Group dialog, enter a Name and Description for the group.
5. If you already have users set up that you want to add to this group, click Next.
Otherwise, click Finish.
l If you clicked Next, select the check box for each user account that you want to
assign to the group, and then click Finish.
Your group is created and its details are displayed.
Assign the OCI Integration application to the group

To assign the OCI Integration application to the group:
1. On your group's details page, click Access.

2. Click Assign.
3. On the Assign Applications dialog, select OCI Integration.
4. Click OK.
Record the Client ID and Client Secret

To edit mappings of your user groups in Oracle Identity Cloud Service to user groups in Oracle
Cloud Infrastructure, you'll need to supply the client ID and client secret. The client ID and
client secret are stored in Oracle Identity Cloud Service. To get this information:

CHAPTER 12 IAM

2. In the Identity Cloud Service console, click Applications. The list of trusted
applications is displayed.
3. Click COMPUTEBAREMETAL.
4. Click Configuration.
5. Expand General Information. The client ID is displayed. Click Show Secret to
display the client secret.

CHAPTER 12 IAM
TASKS TO PERFORM IN THE ORACLE CLOUD I NFRASTRUCTURE CONSOLE
Add a New Group in the Oracle Cloud Infrastructure Console

To add a new group:
1. Open the Console, click Identity, and then click Groups.

A list of the groups in your tenancy is displayed.
2. Click Create Group.
l Name: A unique name for the group. The name must be unique across all groups
administrator.
Map the IDCS Group to the OCI Group

The groups you create in Oracle Identity Cloud Service get access through groups you define
in Oracle Cloud Infrastructure. Before your Oracle Identity Cloud Service groups can get
access, you must create groups in Oracle Cloud Infrastructure with the desired permissions
and then map your Oracle Identity Cloud Service groups to these. You can add permissions to
the Oracle Cloud Infrastructure groups before or after you complete the mapping.
Before you start this procedure, ensure that you have your client ID and client secret from the
Oracle Identity Cloud Service console.

CHAPTER 12 IAM
How do I find the client ID and client secret?

1. Open the Oracle Cloud Infrastructure Console, click Identity, and then click
Federation.

CHAPTER 12 IAM
2. On the list of identity providers, click OracleIdentityCloudService.

Service application, and then click Continue. The Edit Identity Provider dialog
displays any existing mappings.
5. Click + Add Mapping.
6. Select the Oracle Identity Cloud Service group from the list under Identity Provider
Group.
7. Select the IAM group you want to map from the list under Oracle Cloud
Infrastructure Group.
8. Repeat the + Add Mapping steps for each mapping you want to create, and then click
Submit.
Create a Policy to Grant the Group Permissions on OCI Resources

The group you created in Oracle Identity Cloud Service gets permissions to access resources
in Oracle Cloud Infrastructure through the policy you assign to the Oracle Cloud Infrastructure
group. Before you complete this step, you need to decide what permissions you want to give
your new group. For more information, see Getting Started with Policies and Common
Policies.
Prerequisite: The group and compartment that you're writing the policy for must already
exist.
1. Open the Console, click Identity, and then click Policies.

A list of the policies in the compartment you're viewing is displayed.
2. If you want to attach the policy to a compartment other than the one you're viewing,
select the desired compartment from the list on the left. Where the policy is attached
controls who can later modify or delete it (see Policy Attachment).

CHAPTER 12 IAM
l Statement: A policy statement. For the correct format to use, see Policy Basics
and also Policy Syntax. If you want to add more than one statement, click +.
For example:
To allow your group to manage all resources within a specified compartment
enter a statement like the following:
Allow group <OCI_group_name> to manage all-resources in compartment <compartment_name>
For more policy examples, see Common Policies.

l Tags:Optionally, you can apply tags. If you have permissions to create a
administrator.
5. Click Create.
Adding Users
To add a user in Oracle Identity Cloud Service:

2. Click Users and then click Add.

CHAPTER 12 IAM
3. Enter the user’s information and click Next.

4. In the Assign User to Groups step, select the check boxes for the groups you want to
add the user to.
Important
For the user to have permissions in Oracle Cloud

Infrastructure, you must assign the user to a group
that is assigned to the OCI Integration application.
Tip
The OCI_Administrators group is set up by Oracle

and configured with Administrator permissions in
Oracle Cloud Infrastructure. To give a user
administrator permissions, assign them to the OCI_
Administrators group.
5. Click Finish.
Frequently Asked Questions for Oracle Identity Cloud Service Federated

Users
This topic answers some frequently asked questions for customers federated with Oracle
Identity Cloud Service.
Why is my account federated with Oracle Identity Cloud Service?

Oracle My Services links to multiple Oracle services, and so uses an Oracle-wide identity
solution. Your tenant administrator account is automatically federated with Oracle Identity
Cloud Service, the identity provider for many Oracle services. Federating Oracle Cloud

CHAPTER 12 IAM
Infrastructure with Oracle Identity Cloud Service allows you to have a seamless connection
between services, without having to create a separate username and password for each one.
How do I know if I am signed in through Oracle Identity Cloud Service?

Look at your username in the upper right of the Console page. Users signed in through an
identity provider will see their username prefaced with their identity provider name, for
example, oracleidentitycloudservice/user@example.com. This is how it shows in the Console:
How do I add a user to Oracle Identity Cloud Service (a federated user)?

See Adding Groups and Users for Tenancies Federated with Oracle Identity Cloud Service.
Can I add a user just for Oracle Cloud Infrastructure?

Yes. If the new user does not need access to other Oracle services, you can add a user
directly to the Oracle Cloud Infrastructure IAM service. See Adding Users. Using this
procedure, you can create users who can sign in directly to the Oracle Cloud Infrastructure
Console. Users created with this procedure do not have access to any other Oracle services.
How do I manage groups?

In short, managing groups requires actions in both Oracle Identity Cloud Service and Oracle
Cloud Infrastructure. Groups you create in Oracle Identity Cloud Service have no privileges in

CHAPTER 12 IAM
Oracle Cloud Infrastructure until you map them to a group in Oracle Cloud Infrastructure. You
define the policies that permit access to Oracle Cloud Infrastructure resources in the IAM
service in Oracle Cloud Infrastructure. For more information, see Adding Groups and Users
for Tenancies Federated with Oracle Identity Cloud Service.
How do I find the client ID and client secret?

To edit mappings of your user groups in Oracle Identity Cloud Service to user groups in Oracle
Cloud Infrastructure, you'll need to supply the client ID and client secret. The client ID and
client secret are stored in Oracle Identity Cloud Service. To get this information:


CHAPTER 12 IAM
How do I sign out from a single sign-on session?

When you click Sign Out from the Oracle Cloud Infrastructure Console, you are not signed out
of your federated identity provider (Oracle Identity Cloud Service, in this case). To sign out of
Oracle Identity Cloud Service, you need to go to your My Services console or to the Oracle
Identity Cloud Service console and click Sign Out from there
If I delete the federation, can I later recreate it?

Yes. To recreate the federation with Oracle Identity Cloud Service, follow the instructions in

CHAPTER 12 IAM
the topic Federating with Oracle Identity Cloud Service.
Federating with Microsoft Active Directory

This topic describes how to federate with Microsoft Active Directory using Microsoft Active
Federation Services (AD FS).
Note
Before following the steps in this topic, see Identity

Providers and Federation to ensure that you understand
general federation concepts.
About Federating with Microsoft Active Directory
Your organization can have multiple Active Directory accounts (e.g., one for each division of
the organization). You can federate multiple Active Directory accounts with Oracle Cloud
Infrastructure, but each federation trust that you set up must be for a single Active Directory
account.
To federate with Active Directory, you set up a trust between Active Directory and Oracle
Cloud Infrastructure. To set up this trust, you perform some steps in the Oracle Cloud
Infrastructure Console and some steps in Active Directory Federation Services.
Following is the general process an administrator goes through to set up federation with
Active Directory. Details for each step are given in the sections below.
1. Get required information from Active Directory Federation Services.

2. Federate Active Directory with Oracle Cloud Infrastructure:
a. Add the identity provider (AD FS) to your tenancy and provide the required
information.
b. Map Active Directory groups to IAM groups.

CHAPTER 12 IAM
3. In Active Directory Federation Services, add Oracle Cloud Infrastructure as a trusted,

relying party.
4. In Active Directory Federation Services, add the claim rules required in the
authentication response by Oracle Cloud Infrastructure.
5. Test your configuration by logging in to Oracle Cloud Infrastructure with your Active
Directory credentials.
Federating with Active Directory
Prerequisites
You have installed and configured Microsoft Active Directory Federation Services for your
organization.
You have set up groups in Active Directory to map to groups in Oracle Cloud Infrastructure.
Tip
Consider naming Active Directory groups that you

intend to map to Oracle Cloud Infrastructure groups
with a common prefix, to make it easy to apply a filter
rule. For example, OCI_Administrators, OCI_
NetworkAdmins, OCI_InstanceLaunchers.
S TEP 1: GET REQUIRED INFORMATION FROM ACTIVE DIRECTORY FEDERATION S ERVICES
Summary: Get the SAML metadata document and the names of the Active Directory groups
that you want to map to Oracle Cloud Infrastructure Identity and Access Management groups.
1. Locate the SAML metadata document for your AD FS federation server. By default, it is
located at this URL:
https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml

CHAPTER 12 IAM
Download this document and make a note of where you save it. You will upload this
document to the Console in the next step.
2. Note all the Active Directory groups that you want to map to Oracle Cloud Infrastructure
IAM groups. You will need to enter these in the Console in the next step.
S TEP 2: ADD ACTIVE DIRECTORY AS AN IDENTITY PROVIDER IN ORACLE CLOUD I NFRASTRUCTURE
Summary: Add the identity provider to your tenancy. You can set up the group mappings at
the same time, or set them up later.
1. Go to the Console and sign in with your Oracle Cloud Infrastructure login and password.
2. Click Identity, and then click Federation.
3. Click Add identity provider.
a. Display Name: A unique name for this federation trust. This is the name
federated users see when choosing which identity provider to use when signing in
to the Console (e.g., ABCCorp_ADFS shown in the screenshot in Experience for
Federated Users). The name must be unique across all identity providers you add
to the tenancy. You cannot change this later.
b. Description: A friendly description.
c. Type: Select Active Directory Federation Services.
d. XML: Upload the FederationMetadata.xml file you downloaded in Step 1.
5. Click Continue.
6. Set up the mappings between Active Directory groups and IAM groups in Oracle Cloud
Infrastructure. A given Active Directory group can be mapped to zero, one, or multiple
IAM Service groups, and vice versa. However, each individual mapping is between only
a single Active Directory group and a single IAM group. Changes to group mappings take
effect typically within seconds in your home region, but may take several minutes to
propagate to all regions.

CHAPTER 12 IAM
Note
If you don't want to set up the group mappings now,

you can simply click Create and come back to add
the mappings later.
To create a group mapping:

a. Under Identity Provider Group, enter the Active Directory group name. You
must enter the name exactly, including the correct case.
Select the IAM group you want to map from the list under Oracle Cloud
Active Directory group. It will also automatically be given this description, which
you can't change: "Group created during federation".
Tip
Requirements for IAM group name: No spaces.

Allowed characters: letters, numerals,
hyphens, periods, underscores, and plus signs
(+). The name cannot be changed later.
b. Repeat the above sub-steps for each mapping you want to create, and then click
Create.
The identity provider is now added to your tenancy and appears in the list on the Federation
page. Click the identity provider to view its details and the group mappings you just set up.
Oracle assigns the identity provider and each group mapping a unique ID called an Oracle

CHAPTER 12 IAM
In the future, come to the Federation page if you want to edit the group mappings or delete
the identity provider from your tenancy.
S TEP 3: COPY THE URL FOR THE ORACLE CLOUD I NFRASTRUCTURE FEDERATION METADATA DOCUMENT
Summary: The Federation page displays a link to the Oracle Cloud Infrastructure Federation
Metadata document. Before you move on to configuring Active Directory Federation Services,
you need to copy the URL.
1. On the Federation page, click Download this document.

2. Copy the URL. The URL looks similar to:
https://auth.r2.oracleiaas.com/v1/saml/ocid1.tenancy.oc1..aaaaaaaaqdt2tvdmhsa3jmvc5dzulgs3pcv6imf
wfgdya4aq/metadata.xml
S TEP 4: I N ACTIVE DIRECTORY FEDERATION S ERVICES, ADD ORACLE CLOUD I NFRASTRUCTURE AS A
TRUSTED RELYING PARTY
1. Go to the AD FS Management Console and sign in to the account you want to federate.
2. Add Oracle Cloud Infrastructure as a trusted relying party:
a. From the AD FS Management Console, right-click AD FS and select Add Relying
Party Trust.
b. In the Add Relying Party Trust Wizard, click Start.
c. Select Import data about the relying party published online or on a local
network.
Paste the Oracle Cloud Infrastructure Federation Metadata URL that you copied in
Step 3. Click Next.
AD FS will connect to the URL. If you get an error during the attempt to read the
federation metadata, you can alternatively upload the Oracle Cloud Infrastructure
Federation Metadata XML document.
To upload the federation metadata document

i. In a web browser, paste the Oracle Cloud Infrastructure Federation
Metadata URL in the address bar.

CHAPTER 12 IAM
ii. Save the XML document to a location that is accessible by your AD FS

Management Console.
iii. In the Select Data Source step of the Add Relying Party Trust
Wizard, select Import data about the relying party from a file.
iv. Click Browse and select the metadata.xml file that you saved.
v. Click Next.
d. Set the display name for the relying party (e.g., Oracle Cloud Infrastructure) and
then click Next.
e. Select I do not want to configure multi-factor authentication settings for
this relying party trust at this time.
f. Choose the appropriate Issuance Authorization Rules to either permit or deny all
users access to the relying party. Note that if you choose "Deny", then you must
later add the authorization rules to enable access for the appropriate users.
Click Next.
g. Review the settings and click Next.
h. Check Open the Edit Claim Rules dialog for this relying part trust when the
wizard closes and then click Close.
S TEP 5: ADD THE CLAIM RULES FOR THE ORACLE CLOUD I NFRASTRUCTURE RELYING PARTY
Summary: Add the claim rules so that the elements that Oracle Cloud Infrastructure requires
(Name ID and groups) are added to the SAML authentication response.
Add the Name ID rule:
1. In the Add Transform Claim Rule Wizard, select Transform an Incoming Claim,
and click Next.
l Claim rule name: Enter a name for this rule, e.g., nameid.
l Incoming claim type: Select Windows account name.
l Outgoing claim type: Select Name ID.

CHAPTER 12 IAM
l Outgoing name ID format: Select Persistent Identifier.

l Select Pass through all claim value.
l Click Finish.
3. The rule is displayed in the rules list. Click Add Rule.
Add the groups rule:
Important
Any users who are in more than 50 IdP groups cannot be

authenticated to use the Oracle Cloud
InfrastructureConsole. To enable authentication, apply a
filter to the groups rule, as described below.
If your Active Directory users are in fewer than 50 groups

Add the groups rule:
1. Under Claim rule template, select Send Claims Using a Custom Rule. Click Next.
2. In the Add Transform Claim Rule Wizard, enter the following:
a. Claim rule name: Enter groups.
b. Custom rule: Enter the following custom rule:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types =
("https://auth.oraclecloud.com/saml/claims/groupName"), query = ";tokenGroups;{0}", param
= c.Value);
c. Click Finish.
If your Active Directory users are in more than 50 groups

Add the groups rule with a filter:

CHAPTER 12 IAM
To limit the groups sent to Oracle Cloud Infrastructure, create two custom claim rules. The
first one retrieves all groups the user belongs to directly and indirectly. The second rule
applies a filter to limit the groups passed to the service provider to only those that match the
filter criteria.
Add the first rule:
1. In the Edit Claim Rules dialog, click Add Rule.

2. Under Claim rule template, select Send Claims Using a Custom Rule. Click Next.
3. In the Add Transform Claim Rule Wizard, enter the following:
a. Claim rule name: Enter a name, for example, groups.
b. Custom rule: Enter the following custom rule:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types =
("https://auth.oraclecloud.com/saml/claims/groupName"), query = ";tokenGroups;{0}", param
= c.Value);
Note that in this custom rule you use add instead of issue. This command passes
the results of the rule to the next rule, instead of sending the results to the service
provider.
c. Click Finish.
4. Now add the filter rule.
a. In the Edit Claim Rules dialog, click Add Rule.
b. Under Claim rule template, select Send Claims Using a Custom Rule. Click
Next.
c. In the Add Transform Claim Rule Wizard, enter the following:
a. Claim rule name: Enter groups.
b. Custom rule: Enter an appropriate filter rule. For example to send only
groups that begin with the string "OCI", enter the following:
c:[Type == "http://schemas.xmlsoap.org/claims/Group", Value =~ "(?i)OCI"] => issue
(claim = c);

CHAPTER 12 IAM
This rule filters the list from the first rule to only those groups that begin
with the string OCI. The issue command, sends the results of the rule to the
service provider.
You can create filters with the appropriate criteria for your organization.
For information on AD FS syntax for custom rules, see the Microsoft
document: Understanding Claim Rule Language in AD FS 2.0 and Higher.
c. Click Finish.
S TEP 6: S ET UP IAM POLICIES FOR THE GROUPS
If you haven't already, set up IAM policies to control the access the federated users have to
your organization's Oracle Cloud Infrastructure resources. For more information, see Getting
Started with Policies and Common Policies.
S TEP 7: GIVE YOUR FEDERATED USERS THE NAME OF THE TENANT AND URL TO SIGN IN
The federated users need the URL for the Oracle Cloud Infrastructure Console (for example,
https://console.us-ashburn-1.oraclecloud.com) and the name of your tenant. They'll be
prompted to provide the tenant name when they sign in to the Console.
Managing Identity Providers in the Console
To add an identity provider

See Federating with Microsoft Active Directory.
To delete an identity provider

All the group mappings for the identity provider will also be deleted.
1. Delete the identity provider from your tenancy:

a. Open the Console, click Identity, and then click Federation.

CHAPTER 12 IAM
b. Click the identity provider to view its details.

c. Click Delete.
d. Confirm when prompted.
To add group mappings for an identity provider

4. Add at least one mapping:
a. Click + Add Mapping.
b. Under Identity Provider Group, enter the Active Directory group name. The
name you enter here must match exactly the name in Active Directory.
c. Select the IAM group you want to map from the list under Oracle Cloud
Active Directory group. It will also automatically be given this description, which
you can't change: "Group created during federation".
d. Repeat the above sub-steps for each mapping you want to create, and then click
Submit.
Your changes take effect typically within seconds.
To update a group mapping


CHAPTER 12 IAM

4. Update the mappings (or click the X to delete a mapping), and then click Submit.
To delete a group mapping

3. For the mapping you want to delete, click Delete next to it.
Managing Identity Providers in the API
Use these API operations:
Identity providers:
l CreateIdentityProvider
l ListIdentityProviders
l GetIdentityProvider
l UpdateIdentityProvider
l DeleteIdentityProvider: Before you can use this operation, you must first use
DeleteIdpGroupMapping to remove all the group mappings for the identity provider.
Group mappings:

CHAPTER 12 IAM
l CreateIdpGroupMapping: Each group mapping is a separate entity with its own OCID.
l ListIdpGroupMappings
l GetIdpGroupMapping
l UpdateIdpGroupMapping
l DeleteIdpGroupMapping
Calling Services from an Instance

This topic describes how you can authorize instances to call services in Oracle Cloud
Infrastructure.
Introduction
This procedure describes how you can authorize an instance to make API calls in Oracle Cloud
Infrastructure services. After you set up the required resources and policies, an application
running on an instance can call Oracle Cloud Infrastructure public services, removing the need
to configure user credentials or a configuration file.
Concepts
DYNAMIC GROUP
Dynamic groups allow you to group Oracle Cloud Infrastructure instances as principal
actors, similar to user groups. You can then create policies to permit instances in these
groups to make API calls against Oracle Cloud Infrastructure services. Membership in the
group is determined by a set of criteria you define, called matching rules.
MATCHING RULE
When you set up a dynamic group, you also define the rules for membership in the group.
Resources that match the rule criteria are members of the dynamic group. Matching rules
have a specific syntax you follow. See Writing Matching Rules to Define Dynamic Groups.

CHAPTER 12 IAM
INSTANCE PRINCIPALS
The IAM service feature that enables instances to be authorized actors (or principals) to
perform actions on service resources. Each compute instance has its own identity, and it
authenticates using the certificates that are added to it. These certificates are
automatically created, assigned to instances and rotated, preventing the need for you to
distribute credentials to your hosts and rotate them.
Services That Support Access by Instances

The following services support access by instances:
l Compute
l Block Volume
l Networking
l Load Balancing
l Object Storage
Security Considerations
Any user who has access to the instance (who can SSH to the instance), automatically inherits
the privileges granted to the instance. Before you grant permissions to an instance using this
procedure, ensure that you know who can access it, and that they should be authorized with
the permissions you are granting to the instance.
Process Overview
The following steps summarize the process flow for setting up and using instances as
principals. The subsequent sections provide more details.
1. Create a dynamic group. In the dynamic group definition, you provide the matching
rules to specify which instances you want to allow to make API calls against services.
2. Create a policy granting permissions to the dynamic group to access services in your

CHAPTER 12 IAM
tenancy (or compartment).

3. A developer in your organization configures the application built using the Oracle Cloud
Infrastructure SDK to authenticate using the instance principals provider. The developer
deploys the application and the SDK to all the instances that belong to the dynamic
group.
4. The deployed SDK makes calls to Oracle Cloud Infrastructure APIs as allowed by the
policy (without needing to configure API credentials).
5. For each API call made by an instance, the Audit service logs the event, recording the
OCID of the instance as the value of principalId in the event log.
Steps to Enable Instances to Call Services

Perform these tasks to enable an instance to call services:
Create a Dynamic Group and Matching Rules
Write Policies for Dynamic Groups
Configure the SDK, CLI, or Terraform
Creating a Dynamic Group and Matching Rules
See Managing Dynamic Groups.
Writing Policies for Dynamic Groups
After you have created a dynamic group, you need to create policies to permit the dynamic
groups to access Oracle Cloud Infrastructure services.
Policy for dynamic groups follows the syntax described in How Policies Work. Review that
topic to understand basic policy features.
The syntax to permit a dynamic group access to resources in a compartment is:

Allow dynamic-group <dynamic-group_name> to <verb> <resource-type> in compartment <compartment_name>
The syntax to permit a dynamic group access to a tenancy is:

Allow dynamic-group <dynamic-group_name> to <verb> <resource-type> in tenancy

CHAPTER 12 IAM
Here are a few example policies:
To allow a dynamic group (FrontEnd) to use a load balancer in a specific compartment

(ProjectA):
Allow dynamic-group FrontEnd to use load-balancers in compartment ProjectA
To allow a dynamic group to launch instances in a specific compartment:

Allow dynamic-group FrontEnd to manage instance-family in compartment ProjectA
Allow dynamic-group FrontEnd to use volume-family in compartment ProjectA
Allow dynamic-group FrontEnd to use virtual-network-family in compartment ProjectA
For more sample policies, see Common Policies.
Configuring the SDK, CLI, or Terraform

For information about SDKs, see SDKs and Other Tools.
For the Java SDK:
In your Java SDK, create an InstancePrincipalsAuthenticationDetailsProvider object.

For example:
public static void main(String[] args) throws Exception {
InstancePrincipalsAuthenticationDetailsProvider provider =
InstancePrincipalsAuthenticationDetailsProvider.builder().build();
IdentityClient identityClient = new IdentityClient(provider);
...
For the Python SDK:
In your Python SDK, create an

oci.auth.signers.InstancePrincipalsSecurityTokenSigner object. For example:
# By default this will hit the auth service in the region returned by
http://169.254.169.254/opc/v1/instance/region on the instance. To customize
# which auth service endpoint gets hit (e.g. in R1), you can provide an explicit federation_endpoint
when creating the object. For example:
#
# oci.auth.signers.InstancePrincipalsSecurityTokenSigner(federation_endpoint='<my auth service
endpoint>')
signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()

CHAPTER 12 IAM
# In the base case, configuration does not need to be provided as the region and tenancy are obtained
from the InstancePrincipalsSecurityTokenSigner
identity_client = oci.identity.IdentityClient(config={}, signer=signer)
...
Enabling Instance Principal Authorization for the CLI
To enable instance principal authorization from the CLI, you can set the authorization option
(--auth) for a command. For example:
oci os ns get --auth instance_principal
Alternatively, you can set the following environment variable:

OCI_CLI_AUTH=instance_principal
Note that if both are set, the value set for --auth takes precedence over the environment
variable.
For information about using the CLI, see Getting Started with the Command Line Interface.
Enabling Instance Principal Authorization for Terraform
To enable instance principal authorization in Terraform, you can set the auth attribute to
"InstancePrincipal" in the provider definition as shown in the following sample:
variable "region" {}
provider "oci" {
auth = "InstancePrincipal"
region = "${var.region}"
Note that when you use instance principal authorization you do not need to include the
tenancy_ocid, user_ocid, fingerprint, and private_key_path attributes.

CHAPTER 12 IAM
FAQs
How do I query the instance metadata service to query the certificate on the
instance?
Use this curl command: curl http://169.254.169.254/opc/v1/identity/cert.pem
How frequently is the certificate rotated on each instance?

The certificate is rotated multiple times each day.
What happens if I try to use an expired certificate?

You will get a 401-Not Authenticated error.
Can I change the frequency at which the certificate is rotated?

No. You can't change the frequency at which the certificate is rotated. However, you can
change the policy on the dynamic group. If you think an instance has been compromised, you
can either change the policy on the dynamic group to revoke permissions for all members of
the group, or you can remove the instance from the dynamic group. See Can I remove an
instance from a dynamic group?
What happens if the certificate is rotated in the middle of a long running

operation?
The token expiration is independent of the certificate expiration period. And, it also depends
on the application you are interacting with. For example, if Object Storage does not have a
multipart PUT operation, then it does not matter how long the operation runs.

CHAPTER 12 IAM
Are the certificates accessible for all users on an instance?

Yes. Ensure that only users who should be granted the access that you have granted to the
dynamic group, have access to the instance.
Are dynamic groups created at the tenancy level?

Yes.
Can I remove an instance from a dynamic group?

Yes. You can remove it by modifying the matching rule to exclude it. See below for an
example.
Can I exclude specific instances in a compartment from the dynamic group?

Yes. For example, assume you want to exclude two specific instances in a compartment from
the dynamic group. Write a matching rule like this:
All {instance.compartment.id = '<compartment_ocid>',
instance.id != '<instance1_to_exclude_ocid>', instance.id != '<instance2_to_exclude_ocid>'}
The above rule includes all instances in the compartment except those with the OCIDs
specified.

CHAPTER 12 IAM
Managing Users
This topic describes the basics of working with users.
Important
If your tenancy is federated with Oracle Identity Cloud

Service, see Adding Groups and Users for Tenancies
Federated with Oracle Identity Cloud Service to manage
users.
Required IAM Policy

If you're in the Administrators group, then you have the required access for managing users.
You can create a policy that gives someone power to create new users and credentials, but not
control which groups those users are in. See Let the Help Desk manage users.
For the reverse: You can create a policy that gives someone power to determine what groups
users are in, but not create or delete users. See Let group admins manage group
membership.
to dig deeper into writing policies for users or other IAM components, see Details for IAM.
Tagging Resources

CHAPTER 12 IAM
Working with Users

When creating a user, you must provide a unique, unchangeable name for the user. The name
must be unique across all users within your tenancy. It will be the user's login to the Console.
You might want to use a name that's already in use by your company's own identity system
(e.g., Active Directory, LDAP, etc.). You must also provide the user with a description
(although it can be an empty string), which is a non-unique, changeable description for the
user. This could be the user's full name, a nickname, or other descriptive information. Oracle
will also assign the user a unique ID called an Oracle Cloud ID (OCID). For more information,
see Resource Identifiers.
Note
If you delete a user and then create a new user with the
same name, they'll be considered different users
because they'll have different OCIDs.
A new user has no permissions until you place the user in one or more groups, and there's at
least one policy that gives that group permission to either the tenancy or a compartment.
Exception: each user can manage their own credentials. An administrator does not need to
create a policy to give a user that ability. For more information, see User Credentials.
Important
After creating a new user and putting them in a group,

make sure to let them know which compartment(s) they
have access to.
You also need to give the new user some credentials so they can access Oracle Cloud
Infrastructure. A user can have one or both of the following credentials, depending on the type

CHAPTER 12 IAM
of access they need: A password for using the Console, and an API signing key for using the
API. For information about working with user credentials, see Managing User Credentials.
If a user tries 10 times in a row to sign in to the Console unsuccessfully, they will be
automatically blocked from further sign-in attempts. An administrator can unblock the user in
the Console (see To unblock a user) or with the UpdateUserState API operation.
You can delete a user, but only if the user is not a member of any groups.
For information about the number of users you can have, see Service Limits.
Using the Console
To create a user
1. Open the Console, click Identity, and then click Users.
A list of the users in your tenancy is displayed.
2. Click Create User.
l Name: A unique name or email address for the user (for tips on what value to
use, see Working with Users). The name must be unique across all users in your
tenancy. You cannot change this later.
l Description: This could be the user's full name, a nickname, or other descriptive
information. You can change this later if you want to.
administrator.
4. Click Create.

CHAPTER 12 IAM
Next, you need to give the user permissions by adding them to at least one group. You also
need to give the user the credentials they need (see Managing User Credentials).
To add a user to a group

2. Locate the user in the list.
3. Click the user.
Its details are displayed.
4. Click Groups.
5. Click Add User to Group.
6. Select the group from the drop-down list, and then click Add.
Make sure to let the user know which compartment(s) they have access to.
To remove a user from a group

3. Click the user.
4. Click Groups.
5. Click the Actions icon ( ) and then click Remove.

CHAPTER 12 IAM
To delete a user
Prerequisite: To delete a user, the user must not be in any groups.

2. For the user you want to delete, click Delete.
To unblock a user
If you're an administrator, you can use the following procedure to unblock a user who has
tried 10 times in a row to sign in to the Console unsuccessfully.

2. Click the user.
Its details are displayed, including the current status.
3. Click Unblock.
To change a user's description

2. Click the user you want to update.
The user's details are displayed. The description is displayed under the user's login.
3. Click the pencil next to the description.
4. Edit the description and save it.

CHAPTER 12 IAM
To apply tags to a user

For instructions, see Resource Tags.
For information about managing user credentials in the Console, see Managing User
Credentials.
Using the API

Note
Updates Are Not Immediate Across All Regions
Your IAM resources reside in your home region. To

enforce policy across all regions, the IAM service
replicates your resources in each region. Whenever you
create or change a policy, user, or group, the changes
take effect first in the home region, and then are
propagated out to your other regions. It can take
several minutes for changes to take effect in all regions.
For example, assume you have a group with
permissions to launch instances in the tenancy. If you
add UserA to this group, UserA will be able to launch
instances in your home region within a minute.
However, UserA will not be able to launch instances in
other regions until the replication process is complete.
This process can take up to several minutes. If UserA
tries to launch an instance before replication is
complete, they will get a not authorized error.

CHAPTER 12 IAM
Use these API operations to manage users:
l CreateUser
l ListUsers
l GetUser
l UpdateUserState: Unblocks a user who has tried to sign in 10 times in a row
unsuccessfully.
l UpdateUser: You can update only the user's description.
l DeleteUser
l ListUserGroupMemberships: Use this operation to get a list of which users are in a
group, or which groups a user is in.
l AddUserToGroup: This operation results in a UserGroupMembership object with its own
OCID.
l GetUserGroupMembership
l RemoveUserFromGroup: This operation deletes a UserGroupMembership object.
For information about the API operations for managing user credentials, see Managing User
Credentials.

CHAPTER 12 IAM
Managing Groups
This topic describes the basics of working with groups.
Important
If your tenancy is federated with Oracle Identity Cloud

Service, see Adding Groups and Users for Tenancies
Federated with Oracle Identity Cloud Service to manage
groups.
Required IAM Policy

If you're in the Administrators group, then you have the required access for managing groups.
For a policy that only gives someone power to determine what groups users are in, see Let
group admins manage group membership.
Tagging Resources
Working with Groups

When creating a group, you must provide a unique, unchangeable name for the group. The
name must be unique across all groups within your tenancy. You must also provide the group
with a description (although it can be an empty string), which is a non-unique, changeable

CHAPTER 12 IAM
description for the group. Oracle will also assign the group a unique ID called an Oracle Cloud
ID (OCID). For more information, see Resource Identifiers.
Note
If you delete a group and then create a new group with

the same name, they'll be considered different groups
A group has no permissions until you write at least one policy that gives that group permission
to either the tenancy or a compartment. When writing the policy, you can specify the group by
using either the unique name or the group's OCID. Per the preceding note, even if you specify
the group name in the policy, IAM internally uses the OCID to determine the group. For
information about writing policies, see Managing Policies.
You can delete a group, but only if the group is empty.
For information about the number of groups you can have, see Service Limits.
If you're federating with an identity provider, you'll create mappings between the identity
provider's groups and your IAM groups. For more information, see Identity Providers and
Federation.
Using the Console
To create a group

CHAPTER 12 IAM
administrator.
Next, you might want to add users to the group, or write a policy for the group. See To create
a policy.
To add a user to a group

2. Locate the group in the list.
3. Click the group.
Its details are displayed
4. Click Add User to Group.
5. Select the user from the drop-down list, and then click Add User.
To remove a user from a group


CHAPTER 12 IAM

3. Click the group to display its details.
A list of users in the group is displayed.
5. For the user you want to remove, click Remove.
To delete a group
Prerequisite: To delete a group, it must not have any users in it.

3. For the group you want to delete, click Delete.
To update a group's description

This is available only through the API. If you don't have access to the API and need to update
a group's description, contact Oracle Support.
To apply tags to a group

Using the API


CHAPTER 12 IAM
Note

Use these API operations to manage groups:
l CreateGroup
l ListGroups
l GetGroup
l UpdateGroup: You can update only the group's description.
l DeleteGroup
l ListUserGroupMemberships: Use to get a list of which users are in a group, or which
groups a user is in.

CHAPTER 12 IAM
l AddUserToGroup: This operation results in a UserGroupMembership object with its own

OCID.
l GetUserGroupMembership
l RemoveUserFromGroup: This operation deletes a UserGroupMembership object.
For API operations related to group mappings for identity providers, see Identity Providers
and Federation.
Managing Dynamic Groups

This topic describes the basics of working with dynamic groups.
About Dynamic Groups

Dynamic groups allow you to group Oracle Cloud Infrastructure computer instances as
"principal" actors (similar to user groups). You can then create policies to permit instances to
make API calls against Oracle Cloud Infrastructure services. When you create a dynamic
group, rather than adding members explicitly to the group, you instead define a set of
"matching rules" to define the group members. For example, a rule could specify that all
instances in a particular compartment are members of the dynamic group. The members can
change dynamically as instances are launched and terminated in that compartment.
Required IAM Policy

If you're in the Administrators group, then you have the required access for managing
dynamic groups.
to dig deeper into writing policies for dynamic groups or other IAM components, see Details
for IAM.

CHAPTER 12 IAM
Working with Dynamic Groups

When creating a dynamic group, you must provide a unique, unchangeable name for the
dynamic group. The name must be unique across all groups within your tenancy. You must
also provide the dynamic group with a description (although it can be an empty string), which
is a non-unique, changeable description for the group. Oracle will also assign the group a
unique ID called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers.
Note
If you delete a dynamic group and then create a new

dynamic group with the same name, they'll be
considered different groups because they'll have
different OCIDs.
A dynamic group has no permissions until you write at least one policy that gives that dynamic
group permission to either the tenancy or a compartment. When writing the policy, you can
specify the dynamic group by using either the unique name or the dynamic group's OCID. Per
the preceding note, even if you specify the dynamic group name in the policy, IAM internally
uses the OCID to determine the dynamic group. For information about writing policies, see
Managing Policies.
You can delete a dynamic group, but only if the group is empty.
For information about the number of dynamic groups you can have, see Service Limits.
Using the Console
To create a dynamic group

1. Open the Console, click Identity, and then click Dynamic Groups.
A list of the dynamic groups in your tenancy is displayed.

CHAPTER 12 IAM
2. Click Create Dynamic Group.

in your tenancy (dynamic groups and user groups). You can't change this later.
l Description: A friendly description. You can't change this in the Console, but you
can change it Using the API.
4. Enter the Matching Rules. Resources that meet the rule criteria are members of the
group.
l Rule 1: Enter a rule following the guidelines in Writing Matching Rules to Define
Dynamic Groups. You can manually enter the rule in the text box or launch the
rule builder.
l Enter additional rules as needed. To add a rule, click +Additional Rule.
5. Click Create Dynamic Group.
The matching rule syntax is verified, but the OCIDs are not. Be sure that the OCIDs you
enter are correct.
Next, to give the dynamic group permissions, you need to write a policy. See Writing Policies
for Dynamic Groups.
To delete a dynamic group

1. Open the Console, click Identity, and then click Dynamic Groups.
A list of the dynamic groups in your tenancy is displayed.
2. Locate the dynamic group in the list.
3. For the dynamic group you want to delete, click Delete.

CHAPTER 12 IAM
To update a dynamic group's description

This is available only through the API. If you don't have access to the API and need to update
a dynamic group's description, contact Oracle Support.
Writing Matching Rules to Define Dynamic Groups

Matching rules define the resources that belong to the dynamic group. In the Console, you can
either enter they rule in the provided text box, or use the rule builder.
A matching rule has the following syntax:
For a single condition:

variable =|!= value
For multiple conditions:

any|all {<condition>,<condition>,...}
Supported variables are:
l instance.compartment.id - the OCID of the compartment where the instance resides

l instance.id - the OCID of the instance
Here are some examples:
Include All Instances in a Specific Compartment in the Dynamic Group
To include all instances that are in a specific compartment, add a rule with the following
syntax:
instance.compartment.id = '<compartment_ocid>'
You can add that rule either directly in the text box, or you can use the rule builder.
Example entry in text box:

instance.compartment.id = 'ocidv1:compartment:oc1:phx:1457972483881:aaaaaa6q6igvfauxmima74jv2umircgsua'

CHAPTER 12 IAM
Example entries in the Console rule builder:
l Select ALL.
l Attribute: Select in Compartment ID.
l Value: Enter
ocidv1:compartment:oc1:phx:1457972483881:aaaaaa6q6igvfauxmima74jv2umircg
sua
All instances that currently exist or get created in the compartment (identified by the OCID)
are members of this group.
Include All Instances in Any of Two or More Compartments
To include all instances that reside in any of two (or more) compartments, add a rule with the
following syntax:
Any {instance.compartment.id = '<compartment_ocid>', instance.compartment.id = '<compartment_ocid>'}
You can add that rule either directly in the text box, or you can use the rule builder.
Example entry in the text box:

Any {instance.compartment.id =
'ocidv1:compartment:oc1:phx:1457972483881:aaaaaa6q6igvfauxmima74jv2umircgsua', instance.compartment.id =
'ocidv1:compartment:oc1:phx:1457972483881:aaaaaa25dkdleis85faux266ssoid22sso'}
Example entries in the Console rule builder:
1. Select ANY.
2. Enter:
l Value: Enter
ocidv1:compartment:oc1:phx:1457972483881:aaaaaa6q6igvfauxmima74jv2u
mircgsua

CHAPTER 12 IAM
3. Click +Additional Line. Enter the following on the second line:

l Value: Enter
ocidv1:compartment:oc1:phx:1457972483881:aaaaaa25dkdleis85faux266ss
oid22sso
Instances that currently exist or get created in either of the specified compartments are
members of this group.
Using the API

Use these API operations to manage dynamic groups:
l CreateDynamicGroup
l ListDynamicGroups
l GetDynamicGroup
l UpdateDynamicGroup
l DeleteDynamicGroup

CHAPTER 12 IAM
Managing Compartments
This topic describes the basics of working with compartments.
Required IAM Policy

compartments.
For an additional policy related to compartment management, see Let a compartment admin
manage the compartment.
to dig deeper into writing policies for compartments or other IAM components, see Details for
IAM.
Tagging Resources
Working with Compartments

When you first start working with Oracle Cloud Infrastructure, you need to think carefully
about how you want to use compartments to organize and isolate your cloud resources.
Compartments are fundamental to that process. Once you create a compartment, it can't be
deleted, so it's important to think through your compartment design for your organization up
front, before implementing anything. For more information, see "Setting Up Your Tenancy" in
the Oracle Cloud Infrastructure Getting Started Guide.
The Console is designed to display your resources by compartment within the current region.
When you work with your resources in the Console, you must choose which compartment to
work in from a list on the left side of the page. That list includes all compartments in the

CHAPTER 12 IAM
tenancy (including the tenancy, which is the root compartment), regardless of whether you
have permission to work with the resources inside that compartment. If you're an
administrator, you'll have permission to work with any compartment's resources, but if you're
a user with limited access, you probably won't. If a user tries to access a compartment they
don't have permission for, they'll get an error.
When creating a new compartment, you must provide a unique name for it (maximum 100
characters, including letters, numbers, periods, hyphens, and underscores). The name must
be unique across all compartments in your tenancy. You must also provide a description
compartment. Oracle will also assign the compartment a unique ID called an Oracle Cloud ID.
For more information, see Resource Identifiers.
After creating a compartment, you need to write at least one policy for it, otherwise no one
can access it (except administrators who have permission to the tenancy). When creating the
policy, you need to specify which compartment to attach it to. This controls who can later
modify or delete the policy. Depending on how you've designed your compartments, you
might attach it to the tenancy, or to the specific compartment itself. For more information,
see Policy Attachment.
To place a new resource in a compartment, you simply specify that compartment when
creating the resource (the compartment is one of the required pieces of information to create
a resource). If you're working in the Console, you just make sure you're first viewing the
compartment where you want to create the resource. Keep in mind that most IAM resources
reside in the tenancy (this includes users, groups, compartments, and any policies attached to
the tenancy). Notice that you can't move a resource from one compartment to another.
It's not possible to get a list of all the resources in a compartment by using a single API call.
Instead you can list all the resources of a given type in the compartment (e.g., all the
instances, all the block storage volumes, etc.).
Compartments cannot be deleted. If you no longer need to use a particular compartment, you
may remove all the resources from it, and modify or delete all policies that refer to it so that
it cannot be used. You can also rename it to change its position in the list.
For information about the number of compartments you can have, see Service Limits.

CHAPTER 12 IAM
Using the Console
To create a compartment
Remember: Compartments can't be deleted.
1. Open the Console, click Identity, and then click Compartments.

A list of the compartments in your tenancy is displayed.
l Name: A unique name for the compartment (maximum 100 characters, including
letters, numbers, periods, hyphens, and underscores). The name must be unique
across all the compartments in your tenancy. Avoid entering confidential
information.
Avoid entering confidential information.
administrator.
Next, you might want to write a policy for the compartment. See To create a policy.
To update a compartment's name

1. In the Console, click Identity, and then click Compartments.

CHAPTER 12 IAM
2. For the compartment you want to rename, click the Actions icon ( ), and then click
Rename Compartment.
Tip
You can't change the name of your root

compartment.
3. Enter the new Name. The name must be unique across all the compartments in your
tenancy. The name can have a maximum of 100 characters, including letters, numbers,
periods, hyphens, and underscores. Avoid entering confidential information.
4. Click Rename Compartment.
To update a compartment's description

1. In the Console, click Identity, and then click Compartments.
2. For the compartment you want to update, click the Actions icon ( ), and then click
Edit Compartment Description.
3. Enter the new description. Avoid entering confidential information.
4. Click Save.
To view the contents of a compartment

1. Open the Console,
2. Select the type of resource you want to view. For example, click Compute to view all
your Compute resources.
3. Choose the compartment from the list on the left side of the page.
The page updates to show only the resources in that compartment.

CHAPTER 12 IAM
Remember that most IAM resources reside in the tenancy (this includes users, groups, and
compartments). Policies can reside in either the tenancy (root compartment) or other
compartments.
To apply tags to a compartment

Using the API

Use these API operations to manage compartments:
l CreateCompartment
l ListCompartments
l GetCompartment: Returns the metadata for the compartment, not its contents.
l UpdateCompartment: You can update the compartment's name, description, and tags.
Compartments cannot be deleted.
You can retrieve the contents of a compartment only by resource type. There's no API call that
lists all resources in the compartment. For example, to list all the instances in a
compartment, call the Core Services API ListInstances operation and specify the compartment
ID as a query parameter.
Managing Tags and Tag Namespaces

When you have many resources (for example, instances, VCNs, load balancers, and block
volumes) across multiple compartments in your tenancy, it can become difficult to track
resources used for specific purposes, or to aggregate them, report on them, or take bulk
actions on them. Tagging allows you to define keys and values and associate them with

CHAPTER 12 IAM
resources. You can then use the tags to help you organize and list resources based on your
business needs.
Required IAM Policy

If you're in the Administrators group, then you have the required access for managing tag
namespaces and tags.
Overview of Tags
Oracle Cloud Infrastructure supports two kinds of tags: free-form tags and defined tags.
Tip
Watch a video to introduce you to the concepts and

features of tagging: Introduction to Tagging.
Free-form Tags
Free-form tags consist simply of a key and a value, for example:
Environment: Production
where "Environment" is the key and "Production" is the value.
You can apply multiple free-form tags to a single resource (up to the limit).

CHAPTER 12 IAM
Because free-from tags are limited in functionality, Oracle recommends you only use them
when you are first getting started with tagging, to try out the tagging feature in your system.
For more information about the features and limitations of free-form tags, see Working with
Free-form Tags.
Defined Tags
Defined tags provide more features and control than free-form tags. Before you create a
defined tag key, you first set up a tag namespace for it. You can think of the tag namespace as
a container for a set of tag keys. Defined tags support policy to allow you to control who can
apply your defined tags. The tag namespace is the entity to which you can apply policy.
To apply a defined tag to a resource, a user first selects the tag namespace, then the tag key
within the namespace, and then they can assign the value. Administrators can control which
groups of users are allowed to use each namespace.
The following diagrams illustrate defined tags. Two tag namespaces are set up: Operations
and HumanResources. The tag keys are defined in the namespaces. Within each namespace,
the tag keys must be unique, but a tag key name can be repeated across namespaces. In the
example, both namespaces include a key named "Environment".

CHAPTER 12 IAM
The first instance is tagged with two tags from the Operations tag namespace, indicating that
it belongs to the Operations production environment and the Operations project "Alpha". The
second instance is tagged with tags from both the HumanResources tag namespace and the
Operations tag namespace, indicating that it belongs to the HumanResources "Production"
environment, the HumanResources cost center "42", and also the Operations project "Beta".
Tagging Concepts
Here's a list of the basic tagging concepts:

CHAPTER 12 IAM
TAG NAMESPACE
You can think of a tag namespace as a container for your tag keys. It consists of a name,
and zero or more tag key definitions. Tag namespaces are not case sensitive, and must be
unique across the tenancy. The namespace is also a natural grouping to which
administrators can apply policy. One policy on the tag namespace applies to all the tag
definitions contained in it.
KEY
The name you use to refer to the tag. Tag keys are case insensitive (for example,"
mytagkey" duplicates "MyTagKey"). Tag keys for defined tags must be created in a
namespace. A tag key must be unique within a namespace.
TAG VALUE TYPE

The tag value type specifies the data type allowed for the value. Currently the only data
type supported is string.
KEY DEFINITION
A key definition defines the schema of a tag and includes a namespace, tag key, and tag
value type.
TAG VALUE
The tag value is the value you give to the tag key. In the example:
Operations.CostCenter="42"
Operations is the namespace, CostCenter is the tag key, and 42 is the tag value. A tag
value is optional. Tag values only support the string data type.
TAG (OR DEFINED TAG)

A tag is the instance of a key definition that is applied to a resource. It consists of a
namespace, a key and a value. "Tag" is used generically to refer to defined tags.
FREE-FORM TAG
A basic metadata association that consists of a key and a value only. Free-form tags have
limited functionality. See Working with Free-form Tags.

CHAPTER 12 IAM
RETIRE
You can't delete a tag key definition or a tag namespace. Instead, you retire them. Retired
tag namespaces and key definitions can no longer be applied to resources. However, retired
tags are not removed from the resources to which they have already been applied. You can
still specify retired tags when searching, filtering, reporting, and so on.
REACTIVATE
You can reactivate a tag namespace or tag key definition that has been retired to reinstate
its usage in your tenancy.
Taggable Resources
The following table lists resources that support tagging. This table will be updated as tagging
support is added for more resources.
Service Taggable Resource Types
Block Volume volumes
volume_backups
Compute instance
instance-image
instanceconsoleconnections
Database db-systems
databases

CHAPTER 12 IAM
Service Taggable Resource Types
IAM groups
users
compartments
tenancy (root compartment)
policies
tag-namespaces
tag-definitions (API only)
identity-providers
Networking vcns
route-tables
security-lists
dhcp-options
subnets
private-ips
internet-gateways
drgs
cpes
ipsec-connections
local-peering-gateways
Object Storage and Archive Storage buckets

CHAPTER 12 IAM
Working with Free-form Tags

Free-form tags consist simply of a key-value pair. Free-form tags have limited features. To
experience the full feature set of tagging, use defined tags.
Features of free-form tags include:
l Consist of a key and a value. Free-form tags do not belong to a namespace.

l You can apply free-form tags during resource creation or to an existing resource.
l Free-form tag keys are case sensitive. For example, "Project" and "project" are distinct
keys.
l Free-form tag values are case sensitive. For example, "alpha" and "Alpha" are distinct
values.
Limitations of free-form tags include:
l When applying a free-form tag, you can't see a list of existing free-form tags, so you
don't know what tags and values have already been used.
l You can't see a list of existing free-form tags in your tenancy.
l You can't use free-form tags to control access to resources (that is, you can't include
free-form tags in IAM policies).
Who Can Use Free-form Tags
The use permission for a resource grants permissions to apply tags, update tags, and delete
free-form tags for that resource. For example, users who can use instances in
CompartmentA, can also apply, update, or delete free-form tags on instances in
CompartmentA.
The inspect permission for a resource grants permissions to view free-form tags for that
resource. So users who can view instances in CompartmentA can also view any free-form
tags applied to the instance.

CHAPTER 12 IAM
Working with Defined Tags

You must set up the tag namespace and tag keys in your tenancy before users can apply a
defined tag to a resource. As part of the set up process, you must also grant permissions to
the user groups that will need to use the namespace.
Features of defined tags include:
l Consist of a tag namespace, a key, and a value.

l The tag namespace and tag key definition must be set up in your tenancy before you can
apply a defined tag to a resource.
l When applying a defined tag, you select from the list of defined tag keys.
l You can apply a defined tag during resource creation or to an existing resource.
l Defined tag keys are case insensitive.
l Defined tag values are case sensitive. For example, "alpha" and "Alpha" are distinct
values.
Who Can Use Defined Tags
To apply, update, or delete defined tags for a resource, a user must be granted permissions
on the resource and permissions to use the tag namespace.
Users must be granted the use permission on the defined tag's namespace to apply, update,
or delete the defined tag for a resource. The user must also have the use permission for the
resource.
The inspect permission for a resource grants permissions to view defined tags for that
resource. For example, users who can view instances can also view any defined tags applied
to the instance.
Example Scenario
Your company has an Operations department. Within the Operations department are several
cost centers. You want to be able to tag resources that belong to the Operations department

CHAPTER 12 IAM
with the appropriate cost center.
1. Create a tag namespace definition called Operations.

2. In the Operations namespace, create a tag key definition called CostCenter.
Alice already belongs to the group InstanceLaunchers. Alice can manage instances in
CompartmentA. You want Alice and other members of the InstanceLaunchers group to be able
to apply the Operations.CostCenter tag to instances in CompartmentA.
To grant the InstanceLaunchers group access to the Operations tag namespace, add the
following statements to the InstanceLaunchers policy:
Allow group InstanceLaunchers to use tag-namespaces in CompartmentA where target.tag-
namespace.name="Operations"
Alice can now apply the Operations.CostCenter tag to resources in CompartmentA.
Retiring Key Definitions and Namespace Definitions

You can't delete a tag key definition or a tag namespace definition. Instead, you can retire
them.
When you retire a tag key definition, you can no longer apply it to resources. However, the
tag is not removed from the resources that it was applied to. The tag still exists as metadata
on those resources and you can still call the retired tag in operations (such as listing, sorting,
or reporting).
When you retire a tag namespace, all the tag keys in the tag namespace are retired. As
described above, this means that all tags in the tag namespace can no longer be applied to
resources, though existing tags are not removed. No new keys can be created in the retired
tag namespace.
Reactivating Tag Key Definitions and Namespace Definitions

You can reactivate retired tag key definitions and tag namespace definitions.
When you reactivate a tag key, it is again available for you to apply to resources.

CHAPTER 12 IAM
When you reactivate a tag namespace, you can once again create tag key definitions in the
namespace. However, if you want to use any of the tag key definitions that were retired with
the namespace, you must explicitly reactivate each tag key definition.
Limits on Tags
increase.
Tags per resource: 10 free-form and 64 defined
Tag key name length: 100 ASCII characters
Tag value length: 256 unicode characters
Tag namespace length: 100 ASCII characters or 5K (JSON)
Managing Tag Namespaces
To create a tag namespace

1. Open the Console, click Identity, and then click Tag Namespaces.
A list of the tag namespaces in your current compartment is displayed.
2. Click Create Namespace Definition.
l Create in Compartment: The compartment in which you want to create the

namespace definition.
l Namespace Definition Name: A unique name for this set of tags. The name
must be unique within your tenancy. Tag namespace is case insensitive. You
cannot change this later.
4. Click Create Namespace Definition.

CHAPTER 12 IAM
To retire a tag namespace

1. In the Console, click Identity, and then click Tag Namespaces.
2. Click the tag namespace you want to retire.
The namespace's details are displayed.
3. Click Retire Namespace.
To reactivate a tag namespace

2. Click the tag namespace you want to reactivate.
The namespace's details are displayed.
3. Click Reactivate Namespace.
To delete a tag namespace

You can't delete a tag namespace. To prevent its further use and the further use of all the tag
keys that belong to it, you can retire it.
Managing Key Definitions
To create a key definition

1. Open the Console, click Identity, and then click Tag Namespaces.

CHAPTER 12 IAM

2. Click the tag namespace you want to add the tag key definition to.
A list of the tag key definitions that belong to the namespace is displayed.
3. Click Create Tag Key Definition.
l Tag Key: Enter the key. The key can be up to 100 characters in length. Tag keys
are case insensitive and must be unique within the tag namespace.
l Description: Enter a friendly description.
5. Click Create Tag Key Definition.
To update a tag key definition's description

2. Click the tag namespace that includes the tag key definition you want to update.
A list of the tag key definitions is displayed.
3. Click the tag key definition you want to update.
The key definition's details are displayed. The description is displayed under the key
definition's name.
4. Click the pencil next to the description.
5. Edit the description and save it.
To retire a tag key definition

2. Click the tag namespace that includes the tag key definition you want to retire.

CHAPTER 12 IAM
3. Click the tag key definition you want to retire.

The tag key definition's details are displayed.
4. Click Retire Tag Key Definition.
To reactivate a tag key definition

1. In the Console, click Identity, and then click Tag Namepsaces.
2. Click the tag namespace that includes the tag key definition you want to reactivate.
3. Click the tag key definition you want to reactivate.
The tag key definition's details are displayed.
4. Click Reactivate Tag Key Definition.
To delete a tag key definition

You can't delete a tag key definition. To prevent its further use, you can retire it.
Using the API

Use these API operations to manage tag namespaces:
l GetTagNamespace
l ListTagNamespaces

CHAPTER 12 IAM
l CreateTagNamespace
l UpdateTagNamespace - use to retire or reactivate a tag namespace
Use these API operations to manage tag key definitions:
l GetTag - gets the tag key definition

l ListTags - lists tag key definitions
l CreateTag - creates a tag key definition
l UpdateTag - updates the tag key definition (use this operation to retire or reactivate a
tag key)
Managing Regions
This topic describes the basics of managing your region subscriptions. For more information
about regions in Oracle Cloud Infrastructure, see Regions and Availability Domains.
Required IAM Policy

If you're in the Administrators group, then you have the required access to manage region
subscriptions.
to dig deeper into writing policies for managing regions or other IAM components, see Details
for IAM.
The Home Region

When you sign up for Oracle Cloud Infrastructure, Oracle creates a tenancy for you in one
region. This is your home region. Your home region is where your IAM resources are defined.
When you subscribe to another region, your IAM resources are available in the new region,
however, the master definitions reside in your home region and can only be changed there.
Resources that you can create and update only in the home region are:

CHAPTER 12 IAM
l Users
l Groups
l Policies
l Compartments
l Dynamic groups
l Federation resources
l Tag namespaces
l Tag keys
When you use the API to update your IAM resources, you must use the endpoint for your home
region. IAM automatically propagates the updates to all regions in your tenancy.
When you use the Console to update your IAM resources, the Console sends the requests to
the home region for you. You don't need to switch to your home region first. IAM then
automatically propagates the updates to all regions in your tenancy.
When you subscribe your tenancy to a new region, all the policies from your home region are
enforced in the new region. If you want to limit access for groups of users to specific regions,
you can write policies to grant access to specific regions only. For an example policy, see
Restrict admin access to a specific region.
Note
IAM Updates Are Not Immediate Across All Regions
When you create or update an IAM resource, be aware

that you need to allow up to several minutes for the
changes in your home region to become available in all
regions.

CHAPTER 12 IAM
Using the Console
To view the list of regions

Open the Console, click the Region menu, and then click Manage Regions.
A list of the regions offered by Oracle Cloud Infrastructure is displayed. Regions that you
have not subscribed to provide a button to create a subscription.
To subscribe to a region
1. Open the Console, click the Region menu, and then click Manage Regions.
The list of regions offered by Oracle Cloud Infrastructure is displayed. Your home
region is labeled.
2. Locate the region you want to subscribe to and click Subscribe to Region.
Note that it could take several minutes to activate your tenancy in the new region.
Remember, your IAM resources are global, so when the subscription becomes active,
all your existing policies are enforced in the new region.
To switch to the new region, use the region selector in the Console. See Switching
Regions for more information.
You cannot unsubscribe from a region.
Using the API

Use these API operations to manage regions:
l GetTenancy
l ListRegions: Returns a list of regions offered by Oracle Cloud Infrastructure.

CHAPTER 12 IAM
l CreateRegionSubscription
l ListRegionSubscriptions
You cannot unsubscribe from a region.
Region FAQs
Can an individual user subscribe to a region?

A region subscription is at the tenancy level. An administrator can subscribe the tenancy to a
region. All IAM polices are enforced in the new region, so all users in the tenancy will have the
same access and permissions in the new region.
Can I see my existing resources in the new region?

When you select a region in the Console, you are shown a view of the resources in your
selected region. Most cloud resources (instances, VCNs, buckets, etc.) exist only in a specific
region, so you only see them when you select the region where they were created. The
exception is IAM resources: compartments, users, groups, and policies are global across all
regions. See also Working in Multiple Regions.
How do my service limits apply to the new region?

Service limits can be scoped to the tenant level, the region level, or the availability domain
level. When you subscribe to a new region, you get access to the region and its three
availability domains. Service limits apply accordingly. The service limits page lists the scope
of each resource limit.
Can I restrict access to a specific region?

Yes. You can write policies that grant permissions in a specified region only. For an example
policy, see Restrict admin access to a specific region.

CHAPTER 12 IAM
Can I change my home region?

No. Oracle assigns your home region and you can't change it.

CHAPTER 12 IAM
Managing Policies
This topic describes the basics of working with policies.
Required IAM Policy

policies.
to dig deeper into writing policies to control who else can write policies or manage other IAM
components, see Let a compartment admin manage the compartment, and also Details for
IAM.
Tagging Resources
Working with Policies

If you haven't already, make sure to read How Policies Work to understand the basics of how
policies work.
When creating a policy, you must specify the compartment where it should be attached, which
is either the tenancy (the root compartment) or another compartment. Where it's attached
governs who can later modify or delete it. For more information, see Policy Attachment. When
creating the policy in the Console, you attach the policy to the desired compartment by
creating the policy while viewing that compartment. If you're using the API, you specify the
identifier of the desired compartment in the CreatePolicy request.
Also when creating a policy, you can specify its version date. For more information, see Policy
Language Version. You can change the version date later if you like.

CHAPTER 12 IAM
When creating a policy, you must also provide a unique, non-changeable name for it. The
name must be unique across all policies in your tenancy. You must also provide a description
policy. Oracle will also assign the policy a unique ID called an Oracle Cloud ID. For more
information, see Resource Identifiers.
Note
If you delete a policy and then create a new policy with

the same name, they'll be considered different policies
For information about how to write a policy, see How Policies Work and Policy Syntax.
When you create a policy, make changes to an existing policy, or delete a policy, your
changes go into effect typically within 10 seconds.
You can view a list of your policies in the Console or with the API. In the Console, the list is
automatically filtered to show only the policies attached to the compartment you're viewing.
To determine which policies apply to a particular group, you must view the individual
statements inside all your policies. There isn't a way to automatically obtain that information
For information about the number of policies you can have, see Service Limits.
Using the Console
To create a policy
Prerequisite: The group and compartment that you're writing the policy for must already
exist.

A list of the policies in the compartment you're viewing is displayed.

CHAPTER 12 IAM
2. If you want to attach the policy to a compartment other than the one you're viewing,
select the desired compartment from the list on the left. Where the policy is attached
controls who can later modify or delete it (see Policy Attachment).
l Statement: A policy statement. For the correct format to use, see Policy Basics
and also Policy Syntax. If you want to add more than one statement, click +.
administrator.
5. Click Create.
The new policy will go into effect typically within 10 seconds.
To get a list of your policies

Open the Console, click Identity, and then click Policies. A list of the policies in the
compartment you're currently viewing is displayed. If you want to view policies attached to a
different compartment, select that compartment from the list on the left. You can't get a

CHAPTER 12 IAM
single list of all policies; they're always displayed by compartment.
To determine which policies apply to a particular group, you must view the individual
statements inside all your policies. There isn't a way to automatically obtain that information
in the Console.
To update the description for an existing policy

This is available only through the API. A workaround is to create a new policy with the new
description and delete the old policy.
To update the statements in an existing policy

A list of the policies in the compartment you're viewing is displayed. If you don’t see
the one you're looking for, verify that you’re viewing the correct compartment (select
from the list on the left side of the page).
2. Click the policy you want to update.
The policy's details and statements are displayed.
3. Either delete or add new statements (for the required format for statements, see Policy
Basics and Policy Syntax). If you want to update an existing statement, create a new
one with your desired changes and then delete the old one.
Your changes will go into effect typically within 10 seconds.
To update the version date for an existing policy

A list of the policies in the compartment you're currently viewing is displayed. If you
don't see the policy you're looking for, make sure you're viewing the correct
compartment (select from the list on the left side of the page).

CHAPTER 12 IAM
2. Click the policy you want to update.

The policy's details, version date, and statements are displayed.
3. Click Update Version Date.
4. Select Keep Policy Current if you'd like the policy to stay current with any future
changes to the service's definitions of verbs and resources. Or if you'd prefer to limit
access according to the definitions that were current on a specific date, select Use
Version Date and enter that date in format YYYY-MM-DD format. For more
information, see Policy Language Version.
5. Click Update Version Date.
To delete a policy
Tip
Remember that if you delete a policy and then create a

new one with the same name, they'll be considered
different policies because they'll have different OCIDs.

A list of the policies in the compartment you're viewing is displayed. If you don’t see
2. For the policy you want to delete, click Delete.

CHAPTER 12 IAM
To apply tags to a policy

Using the API

Note

Use these API operations to manage policies:

CHAPTER 12 IAM
l CreatePolicy
l ListPolicies
l GetPolicy
l UpdatePolicy
l DeletePolicy

CHAPTER 12 IAM
Managing User Credentials

This topic describes the basics of working with Oracle Cloud Infrastructure Identity and Access
Management (IAM) user credentials. If you're not already familiar with the available
credentials, see User Credentials.
Working with Console Passwords and API Keys

Each user automatically has the ability to change or reset their own Console password, as well
as manage their own API keys. An administrator does not need to create a policy to give a
user those abilities.
To manage credentials for users other than yourself, you must be in the Administrators group
or some other group that has permission to work with the tenancy. Having permission to work
with a compartment within the tenancy is not sufficient. For more information, see The
Administrators Group and Policy.
IAM administrators (or anyone with permission to the tenancy) can use either the Console or
the API to manage all aspects of both types of credentials, for themselves and all other users.
This includes creating an initial one-time password for a new user, resetting a password,
uploading API keys, and deleting API keys.
Users who are not administrators can manage their own credentials. In the Console, users
can:
l Change or reset their own password.

l Upload an API key in the Console for their own use (and also delete their own API keys).
And with the API, users can:
l Reset their own password with CreateOrResetUIPassword.

l Upload an additional API key to the IAM service for their own use with UploadApiKey
(and also delete their own API keys with DeleteApiKey). Remember that a user can't
use the API to change or delete their own credentials until they themselves upload a key
in the Console, or an administrator uploads a key for that user in the Console or the API.

CHAPTER 12 IAM
A user can have a maximum of three API keys at a time.
Working with Swift Passwords

Swift is the OpenStack object store service. If you already have an existing Swift client, you
can use it with the Recovery Manager (RMAN) to back up an Oracle Database System (DB
System) database to Object Storage. You will need to get a Swift-specific password. This is a
special password that Oracle provides and is associated with your Console user login. When
you sign in to your Swift client, you provide the following:
l Your Oracle Cloud Infrastructure Console user login

l Your Swift-specific password, provided by Oracle
l Your organization's Oracle tenant name
Note
You cannot change your Swift password to a string of

your own choice. The password is always an Oracle-
generated string.
Each user automatically has the ability to create, update, and delete their own Swift
passwords in the Console or the API. An administrator does not need to create a policy to give
a user those abilities. Administrators (or anyone with permission to the tenancy) also have
the ability to manage Swift passwords for other users.
Any user of a Swift client that integrates with Object Storage needs permission to work with
the service. If you're not sure if you have permission, contact your administrator. For
information about policies, see How Policies Work. For basic policies that enable use of Object
Storage, see Common Policies.
Swift passwords do not expire. Each user can have up to two Swift passwords at a time. To
get a Swift password in the Console, see To create a Swift password.

CHAPTER 12 IAM
Working with Amazon S3 Compatibility API Keys

Object Storage provides an API to enable interoperability with Amazon S3. To use this
Amazon S3 Compatibility API, you need to generate the signing key required to authenticate
with Amazon S3. This special signing key is an Access Key/Secret Key pair. Oracle provides
the Access Key that is associated with your Console user login. You or your administrator
generates the Secret Key to pair with the Access Key.
Each user automatically has the ability to create, update, and delete their own Amazon S3
Compatibility API keys in the Console or the API. An administrator does not need to create a
policy to give a user those abilities. Administrators (or anyone with permission to the
tenancy) also have the ability to manage Amazon S3 Compatibility API keys for other users.
Any user of the Amazon S3 Compatibility API with Object Storage needs permission to work
with the service. If you're not sure if you have permission, contact your administrator. For
information about policies, see How Policies Work. For basic policies that enable use of Object
Storage, see Common Policies.
Amazon S3 Compatibility API keys do not expire. Each user can have up to two Amazon S3
Compatibility API keys at a time. To create an Amazon S3 Compatibility API key using the
Console, see To create an Amazon S3 Compatibility API Key.
Working with SMTP Credentials

Simple Mail Transfer Protocol (SMTP) credentials are needed in order to send email through
the Email Delivery service. Each user is limited to a maximum of two SMTP credentials. If
more than two are required, they must be generated on other existing users or additional
users must be created.

CHAPTER 12 IAM
Note
You cannot change your SMTP username or password to

a string of your own choice. The credentials are always
Oracle-generated strings.
Each user automatically has the ability to create and delete their own SMTP credentials in the
Console or the API. An administrator does not need to create a policy to give a user those
abilities. Administrators (or anyone with permission to the tenancy) also have the ability to
manage SMTP credentials for other users.
Tip
Although each user can create and delete their own

credentials, it is a security best practice to create a new
user and generate SMTP credentials on this user rather
than generating SMTP credentials on your Console user
that already has permissions assigned to it.
SMTP credentials do not expire. Each user can have up to two credentials at a time. To get
SMTP credentials in the Console, see To generate SMTP credentials.
For information about using the Email Delivery service, see Overview of the Email Delivery
Service.
Using the Console
To change your Console password

You're prompted to change your initial one-time password the first time you sign in to the
Console. The following procedure is for changing your password again later.

CHAPTER 12 IAM
Note
For Federated Users
If your company uses an identity provider to manage

user logins and passwords, you can't use the Console to
update your password. You do that with your identity
provider.
1. In the top-right corner of the Console, click your user's name, and then click Change
Password.
2. Enter the current password and the new password, and then click Save New
Password.
To create or reset a user's Console password

If you're an administrator, you can use the following procedure to create or reset a user's
password. And any user (administrator or not) can use the procedure to reset their own
password. The procedure generates a new one-time password that the user must change the
next time they sign in to the Console.

l If you're resetting your own password: In the top-right corner of the Console,
click your user's name, and then click User Settings to view the details.
l If you're an administrator creating or resetting another user's password: In the
2. Click Create/Reset Password.
The new one-time password is displayed. If you're an administrator performing the task
for another user, you need to securely deliver the new password to the user. The user
will be prompted to change their password the next time they sign in to the Console. If

CHAPTER 12 IAM
they don't change it within 7 days, the password will expire and you'll need to create a
new one-time password for the user.
To unblock a user
If you're an administrator, you can unblock a user who has tried 10 times in a row to sign in to
the Console unsuccessfully. See To unblock a user.
To upload an API signing key

The following procedure works for a regular user or an administrator. Administrators can
upload an API key for either another user or themselves.
Important
The API key must be an RSA key in PEM format

(minimum 2048 bits). The PEM format looks
something like this:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
...
-----END PUBLIC KEY——
For more information about generating a public PEM

key, see Required Keys and OCIDs.

l If you're uploading an API key for yourself: In the top-right corner of the Console,

CHAPTER 12 IAM
l If you're an administrator uploading an API key for another user: In the Console,
click Identity, and then click Users. Locate the user in the list, and then click the
user's name to view the details.
2. Click Add Public Key.
3. Paste the key's value into the window and click Add.
The key is added and its fingerprint is displayed (example fingerprint:
d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:13).
Note
When making API requests, you'll need the key's

fingerprint, along with your tenancy's OCID and user
OCID. See Required Keys and OCIDs.
To delete an API signing key

delete an API key for either another user or themselves.

l If you're deleting an API key for yourself: In the top-right corner of the Console,
l If you're an administrator deleting an API key for another user: In the Console,
click Identity, and then click Users. Locate the user in the list, and then click the
user's name to view the details.
2. For the API key you want to delete, click Delete.
The API key is no longer valid for sending API requests.

CHAPTER 12 IAM
To create a Swift password

details.
the dialog box.
If you're an administrator creating a Swift password for another user, you need to securely
deliver it to the user by providing it verbally, printing it out, or sending it through a secure
email service.
To delete a Swift password

delete a Swift password for either another user or themselves.

l If you're deleting a Swift password for yourself: In the top-right corner of the
details.

CHAPTER 12 IAM
l If you're an administrator deleting a Swift password for another user: In the

3. For the Swift password you want to delete, click Delete.
The Swift password is no longer valid for accessing Object Storage.
To create an Amazon S3 Compatibility API Key

l If you're creating an Amazon S3 Compatibility API key for yourself: In the top-
right corner of the Console, click your user's name, and then click User Settings
to view the details.
l If you're an administrator creating an Amazon S3 Compatibility API key for
another user: In the Console, click Identity, and then click Users. Locate the
user in the list, and then click the user's name to view the details.
2. On the left side of the page, click Amazon S3 Compatibility API Keys.
An Amazon S3 Compatibility API key consists of an Access Key/Secret Key pair. Oracle
automatically generates the Access Key when you or your administrator generates the
Secret Key to create the Amazon S3 Compatibility API key.
3. Click Generate Secret Key.
4. Enter a friendly description for the key and click Generate Secret Key.
The generated Secret Key is displayed in the Generate Secret Key dialog box. At the
same time, Oracle generates the Access Key that is paired with the Secret Key. The
newly generated Amazon S3 Compatibility API key is added to the list of Amazon S3
Compatibility API Keys.
5. Copy the Secret Key immediately, because you can't retrieve the Secret Key again
after closing the dialog box for security reasons.

CHAPTER 12 IAM
If you're an administrator creating a Secret Key for another user, you need to securely
deliver it to the user by providing it verbally, printing it out, or sending it through a
secure email service.
6. Click Close.
7. To show or copy the Access Key, click the Show or Copy action to the left of the
Name of a particular Amazon S3 Compatibility API key.
To delete an Amazon S3 Compatibility API key

delete an Amazon S3 Compatibility API key for either another user or themselves.

l If you're deleting an Amazon S3 Compatibility API key for yourself: In the top-
right corner of the Console, click your user's name, and then click User Settings
to view the details.
l If you're an administrator deleting an Amazon S3 Compatibility API key for
another user: In the Console, click Identity, and then click Users. Locate the
user in the list, and then click the user's name to view the details.
2. On the left side of the page, click Amazon S3 Compatibility API Keys.
3. For the Amazon S3 Compatibility API key you want to delete, click Delete.
The Amazon S3 Compatibility API key is no longer available to use with the Amazon S3
Compatibility API.
To generate SMTP credentials


CHAPTER 12 IAM
l If you're generating SMTP credentials for yourself: In the top-right corner of the
details.
l If you're an administrator generating SMTP credentials for another user: In the
2. Click SMTP Credentials.
3. Click Generate SMTP Credentials.
4. Enter a Description of the SMTP Credentials in the dialog box.
5. Click Generate SMTP Credentials. A user name and password is displayed.
6. Copy the user name and password for your records and click Close. Copy the
credentials immediately, because you can't retrieve the password again after closing
the dialog box for security reasons.
If you're an administrator creating the credential set for another user, you need to
securely deliver it to the user by providing it verbally, printing it out, or sending it
through a secure email service.
To delete SMTP credentials
delete SMTP credentials for either another user or themselves.

l If you're deleting SMTP credentials for yourself: In the top-right corner of the
details.
l If you're an administrator deleting SMTP credentials for another user: In the

CHAPTER 12 IAM
2. On the left side of the page, click SMTP Credentials.

3. For the SMTP credentials you want to delete, click Delete.
The SMTP credentials are no longer available to use with the Email Delivery service.
Using the API

Use this API operation to manage Console passwords and access:
l CreateOrResetUIPassword: This generates a new one-time Console password for the

user. The next time the user signs in to the Console, they'll be prompted to change the
password.
l UpdateUserState: Unblocks a user who has tried to sign in 10 times in a row
unsuccessfully.
Use these API operations to manage API signing keys:
l ListApiKeys
l UploadApiKey
l DeleteApiKey
Use these API operations to manage Swift passwords:
l CreateSwiftPassword
l UpdateSwiftPassword: You can only update the Swift password's description, not
change the password string itself.
l ListSwiftPasswords
l DeleteSwiftPassword
Use these API operations to manage Amazon S3 Compatibility API keys:

CHAPTER 12 IAM
l CreateCustomerSecretKey
l UpdateCustomerSecretKey: You can only update the secret key's description, not
change the key itself.
l ListCustomerSecretKeys
l DeleteCustomerSecretKey
Use these API operations to manage SMTP credentials:
l CreateSmtpCredential
l UpdateSmtpCredential: You can only update the description.
l ListSmtpCredentials
l DeleteSmtpCredential

CHAPTER 13 Load Balancing
This chapter explains how to set up a load balancer.
Overview of Load Balancing

The Oracle Cloud Infrastructure Load Balancing service provides automated traffic distribution
from one entry point to multiple servers reachable from your virtual cloud network (VCN).
The service offers a load balancer with your choice of a public or private IP address, and
provisioned bandwidth.
A load balancer improves resource utilization, facilitates scaling, and helps ensure high
availability. You can configure multiple load balancing policies and application-specific health
checks to ensure that the load balancer directs traffic only to healthy instances. The load
balancer can reduce your maintenance window by draining traffic from an unhealthy
application server before you remove it from service for maintenance.
How Load Balancing Works

The Load Balancing service enables you to create a public or private load balancer within your
VCN. A public load balancer has a public IP address that is accessible from the internet. A
private load balancer has an IP address from the hosting subnet, which is visible only within
your VCN. You can configure multiple listeners for an IP address to load balance transport
Layer 4 and Layer 7 (TCP and HTTP) traffic. Both public and private load balancers can route
data traffic to any backend server that is reachable from the VCN.
Public Load Balancer
To accept traffic from the internet, you create a public load balancer. The service assigns it a
public IP address that serves as the entry point for incoming traffic. You can associate the
public IP address with a friendly DNS name through any DNS vendor.
A public load balancer is regional in scope and requires two subnets, each in a separate
availability domain. One subnet hosts the primary load balancer and the other hosts a standby

load balancer to ensure accessibility even during an availability domain outage. Each load
balancer requires one private IP address from its host subnet. The Load Balancing service
attaches a floating public IP address to one of the specified subnets. (The floating public IP
address does not come from your backend subnets.) If there is a failure in that subnet's
availability domain, the load balancer and public IP address switch to the other subnet. The
service treats the two load balancer subnets as equivalent and you cannot denote one as
"primary".
Warning
You cannot specify a private subnet for your public load

balancer.
Private Load Balancer
To isolate your load balancer from the internet and simplify your security posture, you can
create a private load balancer. The Load Balancing service assigns it a private IP address that
serves as the entry point for incoming traffic.
When you create a private load balancer, the service requires only one subnet to host both the
primary and standby load balancers. The assigned floating private IP address is local to the
specified subnet. The load balancer is accessible only from within the VCN that contains the
associated subnet, or as further restricted by your security list rules.
A private load balancer is local to the availability domain that contains the hosting subnet. The
primary and standby load balancers each require a private IP address from that subnet, in
addition to the assigned floating private IP address. If there is an availability domain outage,
the load balancer has no failover.

All Load Balancers
Your load balancer has a backend set to route incoming traffic to your Compute instances. The
backend set is a logical entity that includes:
l A list of backend servers.

l A load balancing policy.
l A health check policy.
l Optional SSL handling.
l Optional session persistence configuration.
The backend servers (Compute instances) associated with a backend set can exist anywhere,
as long as the associated security lists and route tables allow the intended traffic flow.
Every subnet within your VCN has security lists and a route table. Rules within the security
lists determine whether a subnet can accept data traffic from the internet or from another
subnet. When you add backend servers to a backend set, the Load Balancing service can
suggest appropriate security list rules, or you can configure them yourself through the
Networking service. See Security Lists for more information.
Oracle recommends that you distribute your backend servers across all availability domains
within the region.
To create a minimal system with a functioning load balancer, you must:
l Create a VCN with an internet gateway and at least two public subnets for a public load
balancer. Each subnet must reside in a separate availability domain.
Warning
You cannot specify a private subnet for your public

load balancer.
l Create a VCN with at least one subnet for a private load balancer.
l Create at least two Compute instances, each in a separate availability domain.

l Create a load balancer.

l Create a backend set with a health check policy.
l Add backend servers (Compute instances) to the backend set.
l Create a listener, with optional SSL handling.
l Update the load balancer subnet security list so it allows the intended traffic.
Note
Private IP Address Consumption
A public load balancer consumes two private IP

addresses, one from each host subnet.
A private load balancer created in a single subnet

consumes three private IP addresses from the host
subnet.

The following diagram provides a high-level view of a simple public load balancing system
configuration. Far more sophisticated and complex configurations are common.

Load Balancing Concepts

The following concepts are essential to working with Load Balancing.
BACKEND SERVER
An application server responsible for generating content in reply to the incoming TCP or
HTTP traffic. You typically identify application servers with a unique combination of
overlay (private) IPv4 address and port, for example, 10.10.10.1:8080 and
10.10.10.2:8080.
For more information, see Managing Backend Servers.
BACKEND SET
A logical entity defined by a list of backend servers, a load balancing policy, and a health
check policy. SSL configuration is optional. The backend set determines how the load
balancer directs traffic to the collection of backend servers.
For more information, see Managing Backend Sets.
CERTIFICATES
If you use HTTPS or SSL for your listener, you must associate an SSL server certificate
(X.509) with your load balancer. A certificate enables the load balancer to terminate the
connection and decrypt incoming requests before passing them to the backend servers.
For more information, see Managing SSL Certificates.

HEALTH CHECK
A test to confirm the availability of backend servers. A health check can be a request or a
connection attempt. Based on a time-interval you specify, the load balancer applies the
health check policy to continuously monitor backend servers. If a server fails the health
check, the load balancer takes the server temporarily out of rotation. If the server
subsequently passes the health check, the load balancer returns it to the rotation.
You configure your health check policy when you create a backend set. You can configure
TCP-level or HTTP-level health checks for your backend servers.
l TCP-level health checks attempt to make a TCP connection with the backend servers
and validate the response based on the connection status.
l HTTP-level health checks send requests to the backend servers at a specific URI and
validate the response based on the status code or entity data (body) returned.
The service provides application-specific health check capabilities to help you increase
availability and reduce your application maintenance window.
For more information on health check configuration, see Editing Health Check Policies.
HEALTH STATUS
An indicator that reports the general health of your load balancers and their components.
For more information, see the Health Status section of Editing Health Check Policies.
LISTENER
A logical entity that checks for incoming traffic on the load balancer's IP address. You
configure a listener's protocol and port number, and the optional SSL settings. To handle
TCP, HTTP, and HTTPS traffic, you must configure multiple listeners.
Supported protocols include:
l TCP
l HTTP/1.0

l HTTP/1.1
l HTTP/2
l WebSocket
For more information, see Managing Load Balancer Listeners.
LOAD BALANCING POLICY
A load balancing policy tells the load balancer how to distribute incoming traffic to the
backend servers. Common load balancer policies include:
l Round robin
l Least connections
l IP hash
For more information, see How Load Balancing Policies Work.
PATH ROUTE SET
A set of path route rules to route traffic to the correct backend set without using multiple
listeners or load balancers.
For more information, see Managing Request Routing.
REGIONS AND AVAILABILITY DOMAINS
The Load Balancing service manages application traffic across availability domains within
a region. A region is a localized geographic area, and an availability domain is one or
more data centers located within a region. A region is composed of several availability
domains.
For more information, see Regions and Availability Domains.
SESSION PERSISTENCE
A method to direct all requests originating from a single logical client to a single backend
web server.
For more information, see Session Persistence.

SHAPE
A template that determines the load balancer's total pre-provisioned maximum capacity
(bandwidth) for ingress plus egress traffic. Available shapes include 100 Mbps, 400 Mbps,
and 8000 Mbps.
Tip
Pre-provisioned maximum capacity applies to

aggregated connections, not to a single client
attempting to use the full bandwidth.
SSL
Secure Sockets Layer (SSL) is a security technology for establishing an encrypted link
between a client and a server. You can apply the following SSL configurations to your load
balancer:
SSL TERMINATION
The load balancer handles incoming SSL traffic and passes the unencrypted request to
a backend server.
END TO END SSL
The load balancer terminates the SSL connection with an incoming traffic client, and
then initiates an SSL connection to a backend server.
SSL TUNNELING
If you configure the load balancer's listener for TCP traffic, the load balancer tunnels
incoming SSL connections to your application servers.
Load Balancing supports the TLS 1.2 protocol with a default setting of strong cipher
strength. The default supported ciphers include:
l ECDHE-RSA-AES256-GCM-SHA384

l ECDHE-RSA-AES256-SHA384
l ECDHE-RSA-AES128-GCM-SHA256
l ECDHE-RSA-AES128-SHA256
l DHE-RSA-AES256-GCM-SHA384
l DHE-RSA-AES256-SHA256
l DHE-RSA-AES128-GCM-SHA256
l DHE-RSA-AES128-SHA256
For more information, see Managing SSL Certificates.
SUBNET
A subdivision you define in a VCN, such as 10.0.0.0/24 and 10.0.1.0/24. Each subnet
exists in a single availability domain. A subnet consists of a contiguous range of IP
addresses that do not overlap with other subnets in the VCN. For each subnet, you specify
the routing rules and security lists that apply to it.
You must have at least two public subnets, in separate availability domains, within your
VCN to create a public load balancer. You cannot specify a private subnet for your public
load balancer. A private load balancer requires only one subnet.
For more information on subnets, see VCNs and Subnets and Public vs. Private Subnets.
VIRTUAL HOSTNAME
A virtual server name applied to a listener to enhance request routing.
For more information, see Managing Request Routing.

single, contiguous IPv4 CIDR block of your choice in the allowed IP address ranges.
You need at least one virtual cloud network before you launch a load balancer.
For information about setting up virtual cloud networks, see Overview of Networking.

VISIBILITY
Specifies whether your load balancer is public or private. A public load balancer has a
public IP address that clients can access from the internet. A private load balancer has a
private IP address, from a VCN local subnet, that clients can access only from within your
VCN.
For more information, see Managing a Load Balancer.
WORK REQUEST
An object that reports on the current state of a Load Balancing request.
The Load Balancing service handles requests asynchronously. Each request returns a work
request ID (OCID) as the response. You can view the work request item to see the status
of the request.
For more information, see Viewing the State of a Work Request.



using.
Limits on Load Balancing Resources

increase.
Other limits include:
l You cannot dynamically change the load balancer shape to handle more incoming
traffic. You can use the API or Console to create a load balancer with the new shape
information.
l The Load Balancing service does not support IPv6 addresses.
l The maximum number of concurrent connections is limited when you use stateful
security list rules for your load balancer subnets. In contrast, there is no theoretical
limit on concurrent connections if you use stateless security list rules. There are,
however, practical limitations that depend on various factors. The larger your load
balancer shape, the greater the connection capacity. Other considerations include
system memory, TCP timeout periods, TCP connection state, and so forth.

Tip
To accommodate high-volume traffic, Oracle

strongly recommends that you use stateless
security list rules for your load balancer subnets.
l Each load balancer has the following configuration limits:

o One IP address
o 16 backend sets
o 512 backend servers per backend set
o 1024 backend servers total
o 16 listeners
How Load Balancing Policies Work

After you create a load balancer, you can apply policies to control traffic distribution to your
backend servers. The Load Balancing service supports three primary policy types:
l Round Robin
l Least Connections
l IP Hash
When processing load or capacity varies among backend servers, you can refine each of these
policy types with backend server weighting. Weighting affects the proportion of requests
directed to each server. For example, a server weighted '3' receives three times the number
of connections as a server weighted '1'. You assign weights based on criteria of your choosing,
such as each server's traffic-handling capacity.

Load balancer policy decisions apply differently to TCP load balancers, cookie-based session
persistent HTTP requests (sticky requests), and non-sticky HTTP requests.
l A TCP load balancer considers policy and weight criteria to direct an initial incoming
request to a backend server. All subsequent packets on this connection go to the same
endpoint.
l An HTTP load balancer configured to handle cookie-based session persistence forwards
requests to the backend server specified by the cookie's session information.
l For non-sticky HTTP requests, the load balancer applies policy and weight criteria to
every incoming request and determines an appropriate backend server. Multiple
requests from the same client could be directed to different servers.
Round Robin
Round Robin is the default load balancer policy. This policy distributes incoming traffic
sequentially to each server in a backend set list. After each server has received a connection,
the load balancer repeats the list in the same order.
Round Robin is a simple load balancing algorithm. It works best when all the backend servers
have similar capacity and the processing load required by each request does not vary
significantly.
Least Connections
The Least Connections policy routes incoming non-sticky request traffic to the backend server
with the fewest active connections. This policy helps you maintain an equal distribution of
active connections with backend servers. As with the round robin policy, you can assign a
weight to each backend server and further control traffic distribution.

Tip
In TCP use cases, a connection can be active but have

no current traffic. Such connections do not serve as a
good load metric.
IP Hash
The IP Hash policy uses an incoming request's source IP address as a hashing key to route
non-sticky traffic to the same backend server. The load balancer routes requests from the
same client to the same backend server as long as that server is available. This policy honors
server weight settings when establishing the initial connection.
IP Hash ensures that requests from a particular client are always directed to the same
backend server, as long as it is available.
Warning
Multiple clients that connect to the load balancer

through a proxy or NAT router appear to have the same
IP address. If you apply the IP Hash policy to your
backend set, the load balancer routes traffic based on
the incoming IP address and sends these proxied client
requests to the same backend server. If the proxied
client pool is large, the requests could flood a backend
server.
Connection Management
After your load balancer connects a client to a backend server, the connection can be closed
due to inactivity. The Load Balancing service honors your backend server keep-alive settings.

Also, you can configure load balancer listeners to control the maximum idle time allowed
during each TCP connection or HTTP request and response pair.
Keep-Alive Settings
For HTTP connections, your load balancer honors backend server keep-alive settings. The load
balancer inspects the Connection: header in backend server responses to determine
connection handling. For example, a backend server has a keep-alive request maximum of
100 and a keep-alive timeout of 60 seconds. The system maintains the connection for 100
transactions or until it has been idle for 60 seconds, whichever limit occurs first.
The keep-alive connection pool can grow, depending on the load balancer and backend server
load level. Your load balancer can close keep-alive connections that are not used for an
extended period. If you set the HTTP keep-alive timeout to a value that is higher than the
listener's timeout value, the listener's setting governs connection timeouts during each
request and response exchange. The keep-alive timeout still applies to idle time between a
completed response and any subsequent request.
Connection Configuration
When you create a TCP or HTTP listener, you can specify the maximum idle time in seconds.
This setting applies to the time allowed between two successive receive or two successive
send operations. If the configured timeout has elapsed with no packets sent or received, the
client's connection is closed. For HTTP and WebSocket connections, a send operation does not
reset the timer for receive operations and a receive operation does not reset the timer for
send operations.
Tip
This timeout setting does not apply to idle time between

a completed response and a subsequent HTTP request.
Your keep-alive timeout setting governs that interval.
The default timeout values are:

l 300 seconds for TCP listeners.

l 60 seconds for HTTP listeners.
Modify the timeout parameter if either the client or the backend server requires more time to
transmit data. Some examples include:
l The client sends a database query to the backend server and the database takes over
300 seconds to execute. Therefore, the backend server does not transmit any data
within 300 seconds.
l The client uploads data using the HTTP protocol. During the upload, the backend does
not transmit any data to the client for more than 60 seconds.
l The client downloads data using the HTTP protocol. After the initial request, it stops
transmitting data to the backend server for more than 60 seconds.
l The client starts transmitting data after establishing a WebSocket connection, but the
backend server does not transmit data for more than 60 seconds.
l The backend server starts transmitting data after establishing a WebSocket connection,
but the client does not transmit data for more than 60 seconds.
The maximum timeout value is 7200 seconds. Contact My Oracle Support to file a service
request if you want to increase this limit for your tenancy. For more information, see Service
Limits.
HTTP "X-" Headers

HTTP requests and responses often include header fields that provide contextual information
about the message. RFC 2616 defines a standard set of HTTP header fields. Some non-
standard header fields, which begin with X-, are common. The Load Balancing service adds or
modifies the following X- headers when it passes requests to your servers.
X-Forwarded-For
Provides a list of connection IP addresses.

The load balancer appends the last remote peer address to the X-Forwarded-For field from
the incoming request. A comma and space precede the appended address. If the client
request header does not include an X-Forwarded-For field, this value is equal to the X-Real-
IP value. The original requesting client is the first (left-most) IP address in the list, assuming
that the incoming field content is trustworthy. The last address is the last (most recent) peer,
that is, the machine from which the load balancer received the request. The format is:
X-Forwarded-For: <original_client>, <proxy1>, <proxy2>
Example incoming field:

X-Forwarded-For: 202.1.112.187
Example field with appended proxy IP address:

X-Forwarded-For: 202.1.112.187, 192.168.0.10
X-Forwarded-Host
Identifies the original host and port requested by the client in the Host HTTP request header.
This header helps you determine the original host, since the hostname or port of the reverse
proxy (load balancer) might differ from the original server handling the request.
X-Forwarded-Host: www.oracle.com:8080
X-Forwarded-Port
Identifies the listener port number that the client used to connect to the load balancer. For
example:
X-Forwarded-Port: 443
X-Forwarded-Proto
Identifies the protocol that the client used to connect to the load balancer, either http or
https. For example:
X-Forwarded-Proto: https

X-Real-IP
Identifies the client's IP address. For the Load Balancing service, the "client" is the last
remote peer.
Your load balancer intercepts traffic between the client and your server. Your server's access
logs, therefore, include only the load balancer's IP address. The X-Real-IP header provides
the client's IP address. For example:
X-Real-IP: 192.168.0.10
Session Persistence
Session persistence is a method to direct all requests originating from a single logical client to
a single backend web server. Backend servers that use caching to improve performance, or to
enable log-in sessions or shopping carts, can benefit from session persistence.
Your load balancer must operate in HTTP mode to support server side, cookie-driven session
persistence. You can enable the session persistence feature when you create a backend set.
To configure session persistence, you specify a cookie name and decide whether to disable
fallback for unavailable servers. You can edit an existing backend set to change the session
persistence configuration.
Cookies
The Load Balancing service activates session persistence when a backend server sends a Set-
Cookie response header containing a recognized cookie name. The cookie name must match
the name specified in the backend set configuration. If the configuration specifies a match-all
pattern, '*', any cookie set by the server activates session persistence. Unless a backend
server activates session persistence, the service follows the load balancing policy specified
when you created the load balancer.
The client computer must accept cookies for Load Balancing session persistence feature to
work.
The Load Balancing service calculates a hash of the configured cookie and other request
parameters, and sends that value to the client in a cookie. The value stored in the cookie

enables the service to route subsequent client requests to the correct backend server. If your
backend servers change any of the defined cookies, the service recomputes the cookie's value
and resends it to the client.
Warning
Oracle recommends that you treat cookie data as an

opaque entity. Do not use it in your applications.
To stop session persistence, the backend server must delete the session persistence cookie. If
you used the match-all pattern, it must delete all cookies. You can delete cookies by sending a
Set-Cookie response header with a past expiration date. The Load Balancing service routes
subsequent requests using the configured load balancing policy.
Note
IP Address-driven Session Persistence
Some products offer session persistence support

without cookies. These products depend on the IP
address of the incoming request. ISP proxies and
company exit gateways can issue many requests from a
single IP address. In this case, a single backend server
can be subject to high traffic volumes. Your backend
fleet can become overwhelmed, one server at a time,
even though effective load balancing is possible.
Another weakness of IP address-driven session

persistence is that the originating IP address can
change. In this case, session persistence can be lost or
the request redirected to the wrong backend server.

Fallback
By default, the Load Balancing service directs traffic from a persistent session client to a
different backend server when the original server is unavailable. You can configure the
backend set to disable this fallback behavior. When you disable fallback, the load balancer
fails the request and returns an HTTP 502 code. The service continues to return an HTTP 502
until the client no longer presents a persistent session cookie.
Warning
If fallback is disabled, cookies with a distant future

expiration date can cause a client outage.
The Load Balancing service considers a server marked drain available for existing persisted
sessions. New requests that are not part of an existing persisted session are not sent to that
server.
Managing a Load Balancer

This topic describes how to create or delete a load balancer on your system.
Required IAM Policy

For administrators: For a typical policy that gives access to load balancers and their
components, see Let network admins manage load balancers.

Also, be aware that a policy statement with inspect load-balancers gives the specified
group the ability to see all information about the load balancers. For more information, see
Details for Load Balancing.
Prerequisites
Before you can implement a working load balancer, you need:
l A VCN with at least two public subnets for a public load balancer. Each subnet must
reside in a separate availability domain. For more information on subnets, See VCNs
and Subnets and Public vs. Private Subnets.
Warning
You cannot specify a private subnet for your public

load balancer.
l A VCN with at least one subnet for a private load balancer.

l Two or more backend servers (Compute instances) running your applications. For more
information on Compute instances, see Launching an Instance.
l A listener to detect incoming traffic.

Note
Private IP Address Consumption
A public load balancer requires two subnets. The

primary and secondary load balancers reside within
different subnets. Each load balancer requires one
private IP address from its host subnet. The Load
Balancing service assigns a floating public IP address,
which does not come from your backend subnets. A
public load balancer consumes two private IP
addresses, one from each host subnet.
A private load balancer requires only one subnet. The

primary and secondary load balancers reside within the
same subnet. Each load balancer requires a private
IP address from that subnet. Also, the floating private
IP address comes from the same subnet. A private load
balancer created in a single subnet consumes three
private IP addresses from the host subnet.
Working with Load Balancers

For background information on Oracle Cloud Infrastructure Load Balancing, see Overview of
Load Balancing.
For the purposes of access control, you must specify the compartment where you want the
load balancer to reside. Consult an administrator in your organization if you're not sure which
compartment to use. For information about compartments and access control, see Overview
of IAM.
When you create a load balancer within your VCN, you get a public or private IP address, and
provisioned total bandwidth. If you need another IP address, you can create another load
balancer.

A public load balancer requires two subnets to host the active load balancer and a standby.
Each subnet must reside in a separate availability domain and must be publicly accessible. For
more information on VCNs and subnets, see Overview of Networking. You can associate a
public IPv4 address with a DNS name from any vendor. You can use the public IP address as a
front end for incoming traffic. The load balancer can route data traffic to any backend server
that is reachable from the VCN.
A private load balancer requires only one subnet to host the active load balancer and a
standby. The private IP address is local to the subnet. The load balancer is accessible only
from within the VCN that contains the associated subnet, or as further restricted by your
security list rules. The load balancer can route data traffic to any backend server that is
reachable from the VCN.
The essential components for load balancing include:
l A load balancer with pre-provisioned bandwidth.

l A backend set with a health check policy. See Managing Backend Sets.
l Backend servers for your backend set. See Managing Backend Servers.
l One or more listeners. See Managing Load Balancer Listeners.
l Load balancer subnet security list rules to allow the intended traffic. To learn more
about these rules, see Parts of a Security List Rule.
Tip
To accommodate high-volume traffic, Oracle

strongly recommends that you use stateless
security list rules for your load balancer subnets.
Optionally, you can associate your listeners with SSL server certificates to manage how your
system handles SSL traffic. See Managing SSL Certificates.
For information about the number of load balancers you can have, see Service Limits.

Configuration Changes and Service Disruption
For a running load balancer, some configuration changes lead to service disruptions. The
following guidelines help you understand the effect of changes to your load balancer.
l Operations that add, remove, or modify a backend server create no disruptions to the
Load Balancing service.
l Operations that edit an existing health check policy create no disruptions to the Load
Balancing service.
l Operations that trigger a load balancer reconfiguration can produce a brief service
disruption with the possibility of some terminated connections.
Health Status
The Load Balancing service provides health status indicators that use your health check
policies to report on the general health of your load balancers and their components. You can
see health status indicators on the Console List and Details pages for load balancers, backend
sets, and backend servers. You also can use the Load Balancing API to retrieve this
information.
For general information about health status indicators, see Editing Health Check Policies.
Load Balancer Health Summary
The Console list of load balancers provides health status summaries that indicate the overall
health of each load balancer. There are four levels of health status indicators. The meaning of
each level is:
l OK: All backend sets associated with the load balancer return a status of OK.
l WARNING: All the following conditions are true:
o At least one backend set associated with the load balancer returns a status of
WARNING or UNKNOWN.

o No backend sets return a status of CRITICAL.

o The load balancer life cycle state is ACTIVE.
l CRITICAL: At least one backend set associated with the load balancer returns a status
of CRITICAL.
l UNKNOWN: Any one of the following conditions is true:
o The load balancer life cycle state is not ACTIVE.
o No backend sets are defined for the load balancer.
o All the following conditions are true:
n More than half of the backend sets associated with the load balancer return
a status of UNKNOWN.
n None of the backend sets return a status of WARNING or CRITICAL.
n The load balancer life cycle state is ACTIVE.
o The system could not retrieve metrics for any reason.
Load Balancer Health Details
The load balancer Details page provides the same Overall Health status indicator found in
the list of load balancers. It also includes counters for the Backend Set Health status values
reported by the load balancer's child backend sets.
The health status counter badges indicate the following:
l The number of child entities reporting the indicated health status level.
l If a counter corresponds to the overall health, the badge has a fill color.
l If a counter has a zero value, the badge has a light gray outline and no fill color.

Using the Console
To create a load balancer

1. Open the Console, click Networking, and then click Load Balancers.
2. Choose a Compartment you have permission to work in, and then click Create Load
Balancer.
3. In the Create Load Balancer dialog box, configure your load balancer.
l Name: Required. Specify a friendly name for the load balancer. It does not have
to be unique, but it cannot be changed in the Console. (You can, however, change
it with the API.) Avoid entering confidential information.
l Shape: Required. Specify a shape to provision the maximum total bandwidth
(ingress plus egress) for your load balancer. Available shapes include:
o 100 Mbps
o 400 Mbps
o 8000 Mbps
Tip
After you create a load balancer, you cannot

change the shape. You can create another load
balancer with the new shape.
l Virtual Cloud Network Compartment: Required, when this option appears.

Specify the compartment from which to select your VCN resources.
By default, the Console shows a list of VCNs in the compartment you’re currently
working in. Use the click here link to select a VCN in a different compartment.
l Virtual Cloud Network: Required. Specify a VCN for the load balancer.
l Visibility: Specify whether your load balancer is public or private.

o Create Public Load Balancer: Choose this option to create a public load
balancer. You can use the assigned public IP address as a front end for
incoming traffic and to balance that traffic across all backend servers.
o Create Private Load Balancer: Choose this option to create a private
load balancer. You can use the assigned private IP address as a front end
for incoming internal VCN traffic and to balance that traffic across all
backend servers.
l Subnet Compartment: Required, when this option appears. Specify the
compartment from which to select your subnets.
By default, the Console shows a list of subnets in the compartment you’re
currently working in. Use the click here link to select a subnet in a different
compartment.
l Subnet (1 of 2): Required. Select an available subnet. For a public load
balancer, it must be a public subnet.
l Subnet (2 of 2): Required for a public load balancer. Select a second public
subnet. The second subnet must reside in a separate availability domain from the
first subnet.
4. Click Create.
After the system provisions the load balancer, details appear in the load balancer list. To view
more details, click the load balancer name.
After your load balancer is provisioned, you must create at least one backend set and at least
one listener for it.
To delete a load balancer

2. Choose the Compartment that contains the load balancer you want to delete.
3. For the load balancer you want to delete, click the Actions icon ( ), and then click
Delete.

Using the API

Use these API operations to manage load balancers:
l CreateLoadBalancer
l DeleteLoadBalancer
l GetLoadBalancer
l GetLoadBalancerHealth
l ListLoadBalancers
l ListLoadBalancerHealths
l UpdateLoadBalancer: You can update the load balancer's display name.
Managing Backend Sets

This topic describes how to create and delete backend sets for use with a load balancer. For
information about managing load balancers, see Managing a Load Balancer.
Required IAM Policy


Working with Backend Sets

A backend set is a logical entity defined by a load balancing policy, a health check policy, and
a list of backend servers. To create a backend set, you must specify a load balancing policy
and health check script, and then add a list of backend servers (Compute instances). SSL and
session persistence configuration is optional. A backend set must be associated with one or
more listeners for the load balancer to work.
You cannot delete a backend set used by an active listener.
Changing the load balancing policy of a backend set temporarily interrupts traffic and can drop
active connections.
For background information on the Oracle Cloud Infrastructure Load Balancing, see Overview
of Load Balancing.
Health Status
information.
Backend Set Health Summary
The Console list of a load balancer's backend sets provides health status summaries that
indicate the overall health of each backend set. There are four levels of health status

indicators. The meaning of each level is:
l OK: All backend servers in the backend set return a status of OK.
l WARNING: Both of the following conditions are true:
o Half or more of the backend set's backend servers return a status of OK.
o At least one backend server returns a status of WARNING, CRITICAL, or
UNKNOWN.
l CRITICAL: Fewer than half of the backend set's backend servers return a status of OK.
l UNKNOWN: At least one of the following conditions is true:
o More than half of the backend set's backend servers return a status of UNKNOWN.
o The system could not retrieve metrics for any reason.
o The backend set does not have a listener attached.
Backend Set Health Details
The backend set Details page provides the same Overall Health status indicator found in the
load balancer's list of backend sets. It also includes counters for the Backend Health status
values reported by the backend set's child backend servers.
The health status counter badges indicate the following:
l The number of child entities reporting the indicated health status level.
l If a counter corresponds to the overall health, the badge has a fill color.
l If a counter has a zero value, the badge has a light gray outline and no fill color.
Using the Console
To create a backend set


2. Click the name of the Compartment that contains the load balancer you want to
modify, and then click the load balancer's name.
3. In the Resources menu, click Backend Sets (if necessary), and then click Create
Backend Set.
4. In the Create Backend Set dialog box, enter the following:
l Name: Required. Specify a friendly name for the backend set. It must be unique
within the load balancer, and it cannot be changed.
Valid backend set names include only alphanumeric characters, dashes, and
underscores. Backend set names cannot contain spaces. Avoid entering
confidential information.
l Policy: Required. Choose the load balancer policy for the backend set. The
available options are:
o IP Hash
o Least Connections
o Weighted Round Robin
For more information on these policies, see How Load Balancing Policies Work.
l Use SSL: Optional. Check this box to associate an SSL certificate bundle with the
backend set. The following settings are required to enable SSL handling. See
Managing SSL Certificates for more information.
o Certificate Name: Required. The friendly name of the SSL certificate to
use. See Managing SSL Certificates for more information.
o Verify Peer Certificate: Optional. Select this option to enable peer
certificate verification.
o Verify Depth: Optional. Specify the maximum depth for certificate chain
verification.

l Use Session Persistence: Optional. Check this box to enable persistent

sessions from a single logical client to a single backend web server. The following
settings configure session persistence. See Session Persistence for more
information.
o Cookie Name: The cookie name used to enable session persistence.
Specify '*' to match any cookie name.
o Disable Fallback: Check this box to disable fallback when the original
server is unavailable.
l Health Check: Required. Specify the test parameters to confirm the health of
backend servers.
o Protocol: Required. Specify the protocol to use, either HTTP or TCP.
o Port: Required. Specify the backend server port against which to run the
health check.
Tip
You can enter the value '0' to have the

health check use the backend server's
traffic port.
o Interval in ms: Optional. Specify how frequently to run the health check,
in milliseconds. The default is 10000 (10 seconds).
o Timeout in ms: Optional. Specify the maximum time in milliseconds to
wait for a reply to a health check. A health check is successful only if a reply
returns within this timeout period. The default is 3000 (3 seconds).
o Number of retries: Optional. Specify the number of retries to attempt
before a backend server is considered "unhealthy". The default is '3'.
o URL Path (URI): (HTTP only) Required. Specify a URL endpoint against
which to run the health check.

o Status Code: (HTTP only) Optional. Specify the status code a healthy
backend server must return.
o Response Body Regex: (HTTP only) Optional. Provide a regular
expression for parsing the response body from the backend server.
5. Click Create.
After your backend set is provisioned, you must specify backend servers for the set. See
Managing Backend Servers for more information.
To edit a backend set
Warning
Updating the backend set temporarily interrupts traffic

and can drop active connections.
When you edit a backed set, you can choose a new load balancing policy and modify the SSL
configuration.
3. In the Resources menu, click Backend Sets (if necessary).
4. Click the name of the backend set you want to edit.
5. Click Edit Backend Set.
6. Make the configuration changes you need, and then click Submit.
If you want to modify the backend set's health check policy, see Editing Health Check Policies.
If you want to add or remove backend servers from the backend set, see Managing Backend
Servers.

To delete a backend set
Tip
You cannot delete a backend set used by an active

listener. First, remove any backend sets you want to
delete from the associated listeners.
4. For the backend set you want to delete, click the Actions icon ( ), and then click
Delete.
Using the API

Use these API operations to manage load balancer backend sets:
l CreateBackendSet
l DeleteBackendSet
l GetBackendSet
l GetBackendSetHealth
l ListBackendSets
l UpdateBackendSet

Managing Backend Servers

This topic describes how to manage backend servers for use with a load balancer. For
information about managing load balancers, see Managing a Load Balancer.
Required IAM Policy

Working with Backend Servers

When you implement a load balancer, you must specify the backend servers (Compute
instances) to include in each backend set. The load balancer routes incoming traffic to these
backend servers based on the policies you specified for the backend set. You can use the
Console to add and remove backend servers in a backend set.
To route traffic to a backend server, Load Balancing requires the IP address of the compute
instance and the relevant application port. If the backend server resides within the same VCN
as the load balancer, Oracle recommends that you specify the compute instance's private IP
address. If the backend server resides within a different VCN, you must specify the public IP
address of the compute instance. You also must ensure that the VCN's security list rules allow
Internet traffic.

Warning
When you add backend servers to a backend set, you

specify either the instance OCID or an IP address for the
server to add. An instance with multiple VNICs attached
can have multiple IP addresses pointing to it.
l If you identify a backend server by OCID, Load

Balancing uses the primary VNIC's primary
private IP address.
l If you identify the backend servers to add to a
backend set by their IP addresses, it is possible to
point to the same instance more than once.
To enable backend traffic, your backend server subnets must have appropriate ingress and
egress rules in their security lists. When you add backend servers to a backend set, the Load
Balancing service Console can suggest rules for you, or you can create your own rules using
the Networking service. To learn more about these rules, see Parts of a Security List Rule.
Tip
To accommodate high-volume traffic, Oracle strongly

recommends that you use stateless security list rules
for your load balancer subnets.
You can add and remove backend servers without disrupting traffic.
Health Status

information.
Backend Server Health Summary
The Console list of a backend set's backend servers provides health status summaries that
indicate the overall health of each backend server. The primary and standby load balancers
both provide health check results that contribute to the health status. There are four levels of
health status indicators. The meaning of each level is:
l OK: The primary and standby load balancer health checks both return a status of OK.
l WARNING: One health check returned a status of OK and one did not.
l CRITICAL: Neither health check returned a status of OK.
l UNKNOWN: One or both health checks returned a status of UNKNOWN or the system
was unable to retrieve metrics.
To view the health status details for a specific backend server, click its IP Address.
Backend Server Health Details
The Details page for a backend set provides the same Overall Health status indicator found
in the backend set's list of backend servers. It also reports the following data for the two
health checks performed against each backend server:
IP ADDRESS
The IP address of the health check status report provider, which is a Compute instance
managed by the Load Balancing service. This identifier helps you differentiate same-
subnet (private) load balancers that report health check status.
The Load Balancing service ensures high availability by providing one active and one
standby load balancer. For a public load balancer, each load balancer instance resides in a
different subnet. For a private load balancer, both load balancers reside in the same

subnet. To diagnose a backend server issue, you must know the source of the health
check report. For example, a misconfigured security list might cause a load balancer
instance to report that a backend server is healthy. The other load balancer instance
might return an unhealthy status. In this case, one of the two load balancer instances
cannot communicate with the backend server. Reconfigure the security list to restore the
backend server's health status.
STATUS
The status returned by the health check. Possible values include:
l OK
The backend server's response satisfied the health check policy requirements.
l INVALID_STATUS_CODE
The HTTP response status code did not match the expected status code specified by
the health policy.
l TIMED_OUT
The backend server did not respond within the timeout interval specified by the
health policy.
l REGEX_MISMATCH
The backend server response did not satisfy the regular expression specified by the
health policy.
l CONNECT_FAILED
The health check server could not connect to the backend server.
l IO_ERROR
An input or output communication error occurred while reading or writing a
response or request to the backend server.
l OFFLINE
The backend server is set to offline, so health checks are not run.
l UNKNOWN
Health check status is not available.

LAST CHECKED
The date and time of the most recent health check.
Health status is updated every three minutes. No finer granularity is available.
Using the Console
To add one or more servers to a backend set

3. In the Resources menu, click Backend Sets if necessary. Click the name of the
backend set to which you want to add one or more backend servers.
Tip
If the load balancer has no backend sets, you must

create one before you can specify a backend
server.
4. Click Edit Backends.

5. In the Edit Backends dialog box, enter the following:
l Help me create proper security list rules: Select this check box if you want
the Load Balancing service to suggest basic security list rules to enable traffic for
this backend server.
l Instance OCID / IP Address: Required. Specify either the OCID or IP address
of the backend server (Compute instance) to add.
If you chose to have the service help you create security list rules, you must
specify the OCID. If you do not know the instance OCID, click View Instances to

open the Instances page of the Compute service. There you can find the instance
you want and copy its OCID.
l Port: Required. Specify the server port to which the load balancer must direct
traffic.
l Weight: Optional. Specify the weight to apply to this server. For more
information, see How Load Balancing Policies Work.
6. Click Submit. If you did not choose to have the service create security list rules for
you, the specified servers are added.
If you chose to have the service create security list rules for you, continue with the next
step.
7. Review the suggested rules to be added to the security list rules for the indicated
subnets. To add the rules, click Add All Security Rules.
To remove a server from a backend set

3. In the Resources menu, click Backend Sets if necessary. Click the name of the
backend set from which you want to remove a backend server.
4. Click Edit Backends.
5. In the Edit Backends dialog box, click the red box to remove the corresponding server
from the backend set.
6. Click Submit.
Using the API


The API enables you to mark a backend server in the following ways:
BACKUP
The load balancer forwards ingress traffic to this backend server only when all other
backend servers not marked as "backup" fail the health check policy. This configuration is
useful for handling disaster recovery scenarios.
DRAIN
The load balancer stops forwarding new TCP connections and new non-sticky HTTP
requests to this backend server so an administrator can take the server out of rotation for
maintenance purposes.
OFFLINE
The load balance forwards no ingress traffic to this backend server.
You also can use the API to specify a server's load balancing policy weight. For more
information on load balancing policies, see How Load Balancing Policies Work.
Use these API operations to manage the backend servers in a backend set:
l CreateBackend
l DeleteBackend
l GetBackend
l GetBackendHealth
l ListBackends
l UpdateBackend
Managing Load Balancer Listeners

This topic is part of the setup and maintenance of a load balancer. For more information about
managing load balancers, see Managing a Load Balancer.

Required IAM Policy

Working with Listeners

A listener is a logical entity that checks for incoming traffic on the load balancer's IP address.
To handle TCP, HTTP, and HTTPS traffic, you must configure at least one listener per traffic
type.
When you create a listener, you must ensure that your VCN's security list rules allow the
listener to accept traffic.
Tip
To accommodate high-volume traffic, Oracle strongly

recommends that you use stateless security list rules
for your load balancer subnets.
You can have one SSL certificate bundle per listener. You can configure two listeners, one
each for ports 443 and 8443, and associate SSL certificate bundles with each listener. For
more information about SSL certificates for load balancers, see Managing SSL Certificates.

Using the Console
To create a listener
2. Choose the Compartment that contains the load balancer you want to modify, and then
click the load balancer's name.
3. In the Resources menu, click Listeners (if necessary), and then click Create
Listener.
4. In the Create Listener dialog box, enter the following:
l Name: Required. Specify a friendly name for the listener. It must be unique, and
it cannot be changed. Avoid entering confidential information.
l Hostname: Optional. Specify a virtual hostname for this listener.
l Protocol: Required. Specify the protocol to use, either HTTP or TCP.
l Port: Required. Specify the port on which to listen for incoming traffic.
l Use SSL: Optional. Check this box to associate an SSL certificate bundle with the
listener. The following settings are required to enable SSL handling. See Managing
SSL Certificates for more information.
o Certificate Name: Required. The friendly name of the SSL certificate to
use.
o Verify Peer Certificate: Optional. Select this option to enable peer
certificate verification.
o Verify Depth: Optional. Specify the maximum depth for certificate chain
verification.
l Backend Set: Required. Specify the default backend set to which the listener
routes traffic.
l Timeout in seconds: Optional. Specify the maximum idle time in seconds. This
setting is the time allowed between two successive receive or two successive

send operations between the client and backend servers.
Tip
The maximum value is 7200 seconds. For more

information, see Connection Management.
l Path Route Set: Optional. Specify the name of the set of path-based routing
rules that applies to this listener's traffic.
Tip
A path route set must be a part of the load

balancer's configuration before you can apply it
to a listener.
5. Click Create.
When you create a listener, you must also update your VCN's security list rules to allow traffic
to that listener.
To edit a listener
3. In the Resources menu, click Listeners (if necessary).
4. For the listener you want to edit, click the Actions icon ( ), and then click Edit
Listener.
5. Make the configuration changes you need, and then click Submit.

To delete a listener
3. In the Resources menu, click Listeners (if necessary).
4. For the listener you want to delete, click Delete.
Using the API

Use these API operations to manage listeners:
l CreateListener
l DeleteListener
l UpdateListener
Managing Request Routing

This topic describes how to manage your load balancer's request routing. For information
about managing load balancers, see Managing a Load Balancer.
Required IAM Policy


Routing Incoming Requests

The Load Balancing service enables you to route incoming requests to various backend sets.
You can:
l Assign a virtual hostname to a listener.

l Create path route rules.
l Combine these techniques.
Virtual Hostnames
You can assign a virtual hostname to any listener you create for your load balancer. Each
hostname can correspond to an application served from your backend. Some advantages of
virtual hostnames include:
l A single associated IP address. Multiple hostnames, backed by DNS entries, can point to
the same load balancer IP address.
l A single load balancer. You do not need a separate load balancer for each application.
l A single load balancer shape. Running multiple applications behind a single load
balancer helps you manage aggregate bandwidth demands and optimize utilization.
l Simpler backend set management. Managing a set of backend servers under a single
resource simplifies network configuration and administration.

You can define an exact virtual hostname, such as "app.example.com", or you can use a
wildcard name. A wildcard name includes an asterisk (*) in place of the first or last part of the
name. When searching for a virtual server name, the service chooses the first matching
variant in the following priority order:
1. Exact name match (no asterisk), such as app.example.com.

2. Longest wildcard name that begins with an asterisk, such as *.example.com.
Tip
Prefix wildcard names might require a wildcard

certificate for HTTPS sites.
3. Longest wildcard name that ends with an asterisk, such as app.example.*.
Tip
Suffix wildcard names might require a multi-

domain Subject Alternative Name (SAN) certificate
for HTTPS sites.
You do not need to specify the matching pattern to apply. It is inherent in the asterisk
position, that is, starting, ending, or none.
The following considerations apply to virtual hostnames:
l You cannot use regular expressions.

l Virtual hostname selection priority is not related to the listener's configuration order.
l The number of virtual hostnames you can specify for a load balancer is limited by the
maximum number of listeners.

Tip
The virtual hostnames feature supports HTTP and HTTPS

listeners only. It does not support TCP listeners.
Note
Default Listener
If a listener has no virtual hostname specified, it is the

default listener for the assigned port.
If all listeners on a port have virtual hostnames, the

first virtual hostname configured for that port serves as
the default listener.
Path Route Rules
Some applications have multiple endpoints or content types, each distinguished by a unique
URI path. For example, /admin, /data, or /video, or /cgi. You can use path route rules to
route traffic to the correct backend set without using multiple listeners or load balancers.
A path route is a string that the Load Balancing service matches against an incoming URI to
determine the appropriate destination backend set.
l You cannot use asterisks in path route strings.

l You cannot use regular expressions.
l Path route strings are case-insensitive.
A path route rule consists of a path route string and a pattern match type.

l Specify the pattern match type for each path route rule. Match types include:
o EXACT_MATCH
o FORCE_LONGEST_PREFIX_MATCH
o PREFIX_MATCH
o SUFFIX_MATCH
l Path route rules apply only to HTTP and HTTPS requests. They have no effect on TCP
requests.
A path route set includes all path route strings and matching rules that define the data routing
for a particular listener.
l You can specify up to 20 path routes per path route set.

l You can have one path route set per listener. The maximum number of listeners limits
the number of path route sets you can specify for a load balancer.
The system applies the following priorities, based on match type, to the path route rules
within a set:
l For one path route rule that specifies the EXACT_MATCH type, there is no cascade of
priorities. The listener looks for an exact match only.
l For two path route rules, one that specifies the EXACT_MATCH type and one that
specifies any other match type, the exact match rule is evaluated first. If no match is
found, then the system looks for the second match type.
l For multiple path route rules specifying various match types, the system applies the
following cascade:
1. EXACT_MATCH.
2. FORCE_LONGEST_PREFIX_MATCH.
3. PREFIX_MATCH or SUFFIX_MATCH.
l The order of the rules within the path route set does not matter for EXACT_MATCH and
FORCE_LONGEST_PREFIX_MATCH. The system applies its priority cascade no matter
where these match types appear in the path route set.

l If matching cascades down to prefix or suffix matching, the order of the rules within the
path route set DOES matter. The system chooses the first prefix or suffix rule that
matches the incoming URI path.
Virtual Hostname and Path Route Rules Combinations
Virtual hostnames and path route rules route requests to backend sets. Listeners with a virtual
hostname receive priority over the default (no hostname) listener. The following example
shows the results of a simple routing interaction.
The example system includes three listeners and one path route set:
Listener 1
l Virtual hostname: none

l Default backend set: A
l Path route set: PathRouteSet1
Listener 2
l Virtual hostname: captive.com

l Default backend set: B
Listener 3
l Virtual hostname: wild.com

l Default backend set: C
Path Route Set
l Path route set name: PathRouteSet1

o Exact match on path string /tame routes to backend set B.
o Exact match on path string /feral routes to backend set C.

The example configuration routes incoming URLs as follows:
URL Routed to
http://animals.com A
http://animals.com/tame B
http://animals.com/feral C
http://captive.com B
http://captive.com/tame B
http://captive.com/feral C
http://wild.com C
http://wild.com/tame B
http://wild.com/feral C
Using the Console

You specify a virtual hostname when you create or update a listener.
To apply path route rules to a listener, you first create a path route set that contains the rules.
The path route set becomes a part of the load balancer's configuration. You then specify the
path route set to use when you create or update a listener for the load balancer.
To create a path route set


3. In the Resources menu, click Path Route Sets (if necessary), and then click Create
Path Route Set.
4. In the Create Path Route Set dialog box, enter the following:
l Name: Required. Specify a friendly name for the path route set. It must be
unique, and it cannot be changed. Avoid entering confidential information.
l Path route rules
o Order: (Optional) If you have multiple path route rules, you can click the up
or down arrows to move the corresponding rule.
Tip
The order of the rules within the path route

set does not matter in most cases.
However, if matching cascades down to
prefix or suffix matching, the system
chooses the first prefix or suffix rule that
matches the incoming URI path.
o Match Type: The type of matching to apply to incoming URIs.

o URL String: The path string to match against the incoming URI path, for
example /admin.
o Backend Set Name: The name of the target backend set for requests
where the incoming URI matches the specified path.
5. (Optional) Click Add Line to create another path route rule or click the red box to delete
an existing rule. You can have up to 20 path route rules in a set.
6. Click Create.
After you create a path route set, it becomes available for use with the associated load
balance. Create or update a listener to apply the path route set.

To update a path route set

3. In the Resources menu, click Path Route Sets (if necessary).
4. Click the name of the path route set you want to update, and then click Edit Path
Route Rules.
5. In the Edit Path Route Rules dialog box, edit the following as needed for each rule
you want to change:
l Order: (Optional) If you have multiple path route rules, you can click the up or
down arrows to move the corresponding rule.
Tip
The order of the rules within the path route set

does not matter in most cases. However, if
matching cascades down to prefix or suffix
matching, the system chooses the first prefix or
suffix rule that matches the incoming URI path.
l Match Type: The type of matching to apply to incoming URIs.

l URL String: The path string to match against the incoming URI path, for example
/admin.
l Backend Set Name: The name of the target backend set for requests where the
incoming URI matches the specified path.
6. (Optional) Click Add Line to create another path route rule or click the red box to delete
an existing rule. You can have up to 20 path route rules in a set.
7. Click Save.

To update a single path route rule

3. In the Resources menu, click Path Route Sets (if necessary).
4. Click the name of the path route set you want to update.
5. For the path route rule you want to edit, click the Actions icon ( ), and then click
Edit Path Route.
6. In the Edit Path Route Rule dialog box, edit the following as needed for each rule you
want to change:
l Order: (Optional) If you have multiple path route rules, you can click the up or
down arrows to move the corresponding rule.
Tip
The order of the rules within the path route set

does not matter in most cases. However, if
matching cascades down to prefix or suffix
matching, the system chooses the first prefix or
suffix rule that matches the incoming URI path.
l Match Type: The type of matching to apply to incoming URIs.

l URL String: The path string to match against the incoming URI path, for example
/admin.
l Backend Set Name: The name of the target backend set for requests where the
incoming URI matches the specified path.
7. Click Save.

Using the API

Use these API operations to manage request routing:
l CreateListener
l CreatePathRouteSet
l DeleteListener
l DeletePathRouteSet
l GetPathRouteSet
l ListPathRouteSets
l UpdateListener
l UpdatePathRouteSet
Managing SSL Certificates

This topic is part of the setup and maintenance of a load balancer. For more information about
managing load balancers, see Managing a Load Balancer.
Required IAM Policy


Working with SSL Certificates

To use SSL with your load balancer, you must add one or more certificate bundles to your
system. The certificate bundle you upload includes the public certificate, the corresponding
private key, and any associated Certificate Authority (CA) certificates.
Tip
Upload the certificate bundles you want to use before

you create the listeners or backend sets you want to
associate them with.
Oracle Cloud Infrastructure accepts x.509 type certificates in PEM format only. The following
is an example PEM encoded certificate:
-----BEGIN CERTIFICATE-----
<Base64_encoded_certificate>
-----END CERTIFICATE-----
Converting to PEM format
If you receive your certificates and keys in formats other than PEM, you must convert them
before you can upload them to the system. You can use OpenSSL to convert certificates and
keys to PEM format. The following example commands provide guidance.
CERTIFICATE OR CERTIFICATE CHAIN FROM DER TO PEM
openssl x509 -inform DER -in <certificate_name>.der -outform PEM -out <certificate_name>.pem

PRIVATE KEY FROM DER TO PEM
openssl rsa -inform DER -in <private_key_name>.der -outform PEM -out <private_key_name>.pem
CERTIFICATE BUNDLE FROM PKCS#12 (PFX) TO PEM
openssl pkcs12 -in <certificate_bundle_name>.p12 -out <certificate_bundle_name>.pem -nodes
CERTIFICATE BUNDLE FROM PKCS#7 TO PEM
openssl pkcs7 -in <certificate_bundle_name>.p7b -print_certs -out <certificate_bundle_name>.pem
Uploading Certificate Chains
If you have multiple certificates that form a single certification chain, you must include all
relevant certificates in one file before you upload them to the system. The following example
of a certificate chain file includes four certificates:
Submitting Private Keys
Tip
Oracle recommends a minimum length of 2048 bits for

your RSA private key.

If your private key submission returns an error, the three most common reasons are:
l You provided an incorrect passphrase.

l Your private key is malformed.
l The system does not recognize the encryption method used for your key.
PRIVATE KEY CONSISTENCY
If you receive an error related to the private key, you can use OpenSSL to check its
consistency:
openssl rsa -check -in <private_key>.pem
This command verifies that the key is intact, the passphrase is correct, and the file contains a
valid RSA private key.
DECRYPTING A PRIVATE KEY
If the system does not recognize the encryption technology used for your private key, decrypt
the key. Upload the unencrypted version of the key with your certificate bundle. You can use
OpenSSL to decrypt a private key:
openssl rsa -in <private_key>.pem -out <decrypted_private_key>.pem
Updating an Expiring Certificate
To ensure consistent service, you must update expiring certificates:
1. Create and upload a new SSL certificate bundle.

2. Edit listeners and backend sets (if needed) to use the new certificate bundle.
3. Remove the expiring SSL certificate bundle.
Configuring SSL Handling

With Oracle Cloud Infrastructure Load Balancing, you can:

l Terminate SSL at the load balancer. This configuration is frontend SSL. Your load
balancer can accept encrypted traffic from a client. There is no encryption of traffic
between the load balancer and the backend servers.
l Implement SSL between the load balancer and your backend servers. This configuration
is backend SSL. Your load balancer does not accept encrypted traffic from client
servers. Traffic between the load balancer and the backend servers is encrypted.
l Implement end to end SSL. Your load balancer can accept SSL encrypted traffic from
clients and encrypts traffic to the backend servers.
Terminating SSL at the Load Balancer
To terminate SSL at the load balancer, you must create a listener at a port such as 443, and
then associate an uploaded certificate bundle with the listener.
Implementing Backend SSL
To implement SSL between the load balancer and your backend servers, you must associate
an uploaded certificate bundle with the backend set.
Tip
l If you want to have more than one backend

server in the backend set, sign your backend
servers with an intermediate CA certificate. The
intermediate CA certificate must be included as
part of the certificate bundle.
l Your backend services must be able to accept and
terminate SSL.

Implementing End to End SSL
To implement end to end SSL, you must associate uploaded certificate bundles with both the
listener and the backend set.
Using the Console
To upload an SSL certificate bundle to your load balancing system

3. Click the load balancer you want to configure.
4. In the Resources menu, click Certificates, and then click Add Certificate.
5. In the Add Certificate dialog box, enter the following:
l Certificate Name: Required. Specify a friendly name for the certificate bundle.
It must be unique within the load balancer, and it cannot be changed in the
Console. (It can be changed using the API.) Avoid entering confidential
information.
l Certificate: Optional. (Required for SSL termination.) Paste the certificate, in
PEM format, in this field.
l CA Certificate: Optional. (Recommended for backend SSL termination
configurations.) Paste the Certificate Authority certificate (root CA certificate) in
this field.
l Private Key: Optional. (Required for SSL termination.) Paste the private key for
the certificate in this field.
l Passphrase: Optional. Specify a passphrase.
6. Click Add Certificate.

To delete an SSL certificate bundle from your load balancing system

You cannot delete an SSL certificate bundle that is associated with a listener or backend set.
Remove the bundle from any listeners or backend sets before deleting.
3. Click the load balancer you want to configure.
4. In the Resources menu, click Certificates.
5. For the certificate you want to delete, click the Actions icon ( ), and then click
Delete.
Using the API

Use these API operations to manage load balancer certificates:
l CreateCertificate
l DeleteCertificate
l ListCertificates
Editing Health Check Policies

This topic describes how to modify health check policies for a backend set.
Required IAM Policy


Working with Health Check Policies

A health check is a test to confirm the availability of backend servers. A health check can be a
request or a connection attempt. Based on a time-interval you specify, the load balancer
applies the health check policy to continuously monitor backend servers. If a server fails the
health check, the load balancer takes the server temporarily out of rotation. If the server
subsequently passes the health check, the load balancer returns it to the rotation.
You configure your health check policy when you create a backend set. You can configure TCP-
level or HTTP-level health checks for your backend servers.
l TCP-level health checks attempt to make a TCP connection with the backend servers
and validate the response based on the connection status.
l HTTP-level health checks send requests to the backend servers at a specific URI and
validate the response based on the status code or entity data (body) returned.
The service provides application-specific health check capabilities to help you increase
availability and reduce your application maintenance window.
Health Status

information.
There are four levels of health status indicators. The general meaning of each level is:
OK (GREEN)
No attention required.
The resource is functioning as expected.
WARNING (YELLOW)
Some reporting entities require attention.
The resource is not functioning at peak efficiency or the resource is incomplete and
requires further work.
CRITICAL (RED)
Some or all reporting entities require immediate attention.
The resource is not functioning or unexpected failure is imminent.
UNKNOWN (GREY)
Health status cannot be determined.
The resource is not responding or is in transition and might resolve to another status over
time.
The precise meaning of each level differs among the following components:
l Load balancers
l Backend sets
l Backend servers

Using Health Status
At the highest level, load balancer health reflects the health of its components. The health
status indicators provide information you might need to drill down and investigate an existing
issue. Some common issues that the health status indicators can help you detect and correct
include:
A HEALTH CHECK IS MISCONFIGURED.
In this case, all the backend servers for one or more of the affected listeners report as
unhealthy. If your investigation finds that the backend servers do not have problems, then
a backend set probably includes a misconfigured health check.
A LISTENER IS MISCONFIGURED.
All the backend server health status indicators report OK, but the load balancer does not
pass traffic on a listener.
The listener might be configured to:
l Listen on the wrong port.

l Use the wrong protocol.
l Use the wrong policy.
If your investigation shows that the listener is not at fault, check the security list
configuration.
A SECURITY LIST IS MISCONFIGURED.
Health status indicators help you diagnose two cases of misconfigured security lists:
l All entity health status indicators report OK, but traffic does not flow (as with
misconfigured listeners). If the listener is not at fault, check the security list
configuration.
l All entity health statuses report as unhealthy. You have checked your health check
configuration and your services run properly on your backend servers.

In this case, your security lists might not include the IP range for the source of the
health check requests. You can find the health check source IP on the Details page
for each backend server. You can also use the API to find the IP in the
sourceIpAddress field of the HealthCheckResult object.
Note
Source IP
The source IP for health check requests comes

from a Compute instance managed by the Load
Balancing service.
ONE OR MORE OF THE BACKEND SERVERS REPORTS AS UNHEALTHY.
A backend server might be unhealthy or the health check might be misconfigured. To see
the corresponding error code, check the status field on the backend server's Details page.
You can also use the API to find the error code in the healthCheckStatus field of the
HealthCheckResult object.
OTHER CASES IN WHICH HEALTH STATUS MIGHT PROVE HELPFUL INCLUDE :
l VCN security lists block traffic.

l Compute instances have misconfigured route tables.
Health Status Limitations
Health status is updated every three minutes. No finer granularity is available.
Health status does not provide historical health data.
Using the Console

You create your health check tests when you create a backend set.

To edit an existing health check policy

4. For the backend set you want to modify, click the Actions icon ( ), and then click
View Backend Set Details.
5. Click Update Health Check.
6. In the Health Check section, specify the test parameters to confirm the health of
backend servers.
Tip
All parameters are required when updating an

existing health check policy.
l Protocol: Required. Specify the protocol to use, either HTTP or TCP.

l Port: Required. Specify the backend server port against which to run the health
check.
Tip
You can enter the value '0' to have the health

check use the backend server's traffic port.
l URL Path (URI): (HTTP only) Required. Specify a URL endpoint against which to
run the health check.

l Interval in ms: Required. Specify how frequently to run the health check, in
milliseconds.
l Timeout in ms: Required. Specify the maximum time in milliseconds to wait for
a reply to a health check. A health check is successful only if a reply returns
within this timeout period.
l Number of retries: Required. Specify the number of retries to attempt before a
backend server is considered "unhealthy".
l Status Code: (HTTP only) Required. Specify the status code a healthy backend
server must return.
l Response Body Regex: (HTTP only) Required. Provide a regular expression for
parsing the response body from the backend server.
Tip
Health checks require all fields to match. Your

status code and response body both must
match, as specified.
7. Click Save.
Using the API

Use this API operation to edit a backend set's health check policy:
UpdateBackendSet

Use these API operations to retrieve health status information:
l GetBackendHealth
l GetBackendSetHealth
l GetLoadBalancerHealth
l ListLoadBalancerHealths
Viewing the State of a Work Request

This topic describes how to view the state of work requests associated with a given load
balancer.
Required IAM Policy

Monitoring Work Requests

Many of the Oracle Cloud Infrastructure Load Balancing service requests do not take effect
immediately. In these cases, the request spawns an asynchronous workflow for fulfillment. To
provide visibility for in-progress workflows, the Load Balancing service creates a work
request object. Because some operations depend on the completion of other operations, you

must monitor each operation’s work request and confirm it has succeeded before proceeding
to the next operation. For example, if you want to create a backend set and add a backend
server to the new set, you first must create the backend set. After that operation completes,
you can add the backend server. If you try to add a backend server before the backend set
creation completes, the system cannot ensure that the request to add the server succeeds.
You can monitor the request to add a backend set to determine when that workflow is
complete, and then add the backend server.
The work request states are:
ACCEPTED
The request is in the work request queue to be processed.
IN PROGRESS
A work request record exists for the specified request, but there is no associated WORK_
COMPLETED record.
SUCCEEDED
A work request record exists for this request and an associated WORK_COMPLETED record
has the state SUCCEEDED.
FAILED
A work request record exists for this request and an associated WORK_COMPLETED record
has the state FAILED.
Using the Console

The Oracle Cloud Infrastructure Console consumes the REST API and is subject to the same
considerations as any Oracle Cloud Infrastructure client. You can view the state of a load
balancing work request in the Console:
review, and then click the load balancer's name.

3. In the Resources menu, click Work Requests. The status of all work requests
appears on the page.
Using the API

Use these operations to monitor the state of work requests:
l ListWorkRequests
l GetWorkRequest

CHAPTER 14 Networking
This chapter explains how to set up cloud networks.
Overview of Networking
When you work with Oracle Cloud Infrastructure, one of the first steps is to set up a virtual
cloud network (VCN) for your cloud resources. This topic gives you an overview of Oracle
Cloud Infrastructure Networking components and typical scenarios for using a VCN.
Networking Components
The Networking service uses virtual versions of traditional network components you might
already be familiar with:

single, contiguous IPv4 CIDR block of your choice. See Default Components that Come
With Your VCN. The terms virtual cloud network, VCN, and cloud network are used
interchangeably in this documentation. For more information, see VCNs and Subnets.
SUBNETS
Subdivisions you define in a VCN (for example, 10.0.0.0/24 and 10.0.1.0/24). Subnets
contain virtual network interface cards (VNICs), which attach to instances. Each subnet
exists in a single availability domain and consists of a contiguous range of IP addresses
that do not overlap with other subnets in the VCN. Subnets act as a unit of configuration
within the VCN: All VNICs in a given subnet use the same route table, security lists, and
DHCP options (see the definitions that follow). You can designate a subnet as private when
you create it, which means VNICs in the subnet can't have public IP addresses. See
Internet Access.

VNIC
A virtual network interface card (VNIC), which attaches to an instance and resides in a
subnet to enable a connection to the subnet's VCN. The VNIC determines how the instance
connects with endpoints inside and outside the VCN. Each instance has a primary VNIC
that's created during instance launch and cannot be removed. You can add secondary
VNICs to an existing instance (in the same availability domain as the primary VNIC), and
remove them as you like. For more information, see Virtual Network Interface Cards
(VNICs).
PRIVATE IP
A private IP address and related information for addressing an instance (for example, a
hostname for DNS). Each VNIC has a primary private IP, and you can add and remove
secondary private IPs. For more information, see Private IP Addresses.
PUBLIC IP
A public IP address and related information. You can optionally assign a public IP to your
instances or other resources that have a private IP. Public IPs can be either ephemeral or
reserved. For more information, see Public IP Addresses.
INTERNET GATEWAY
An optional virtual router that you can add to your VCN. It provides a path for network
traffic between your VCN and the internet. For more information, see Internet Access and
also Typical Networking Scenarios.
DYNAMIC ROUTING GATEWAY (DRG)

Another optional virtual router that you can add to your VCN. It provides a path for private
network traffic between your VCN and on-premises network. You can use it with other
Networking components and a router in your on-premises network to establish a
connection via IPSec VPN or Oracle Cloud Infrastructure FastConnect. It can also provide
a path for private network traffic between your VCN and another VCN in a different region.
For more information, see Connection to Your On-Premises Network, Dynamic Routing
Gateways (DRGs), and Remote VCN Peering (Across Regions).

LOCAL PEERING GATEWAY (LPG)

Another optional virtual router that you can add to your VCN. It provides a path for private
network traffic between your VCN and another VCN in the same region. For more
information, see Local VCN Peering (Within Region).
REMOTE PEERING CONNECTION (RPC)

A component that you can add to a DRG. It provides a path for private network traffic
between your VCN and another VCN in a different region. For more information, see
Remote VCN Peering (Across Regions).
ROUTE TABLES
Virtual route tables for your VCN. Your VCN comes with a default route table, and you can
add more. These route tables provide mapping for the traffic from subnets via gateways
or specially configured instances to destinations outside the VCN. For more information,
see Route Tables.
SECURITY LISTS
Virtual firewall rules for your VCN. Your VCN comes with a default security list, and you
can add more. These security lists provide ingress and egress rules that specify the types
of traffic allowed in and out of the instances. You can choose whether a given rule is
stateful or stateless. For more information, see Security Lists.
DHCP OPTIONS
Configuration information that is automatically provided to the instances when they boot
up. For more information, see DHCP Options.
Allowed VCN Size and Address Ranges

A VCN covers a single, contiguous IPv4 CIDR block of your choice. The allowable VCN size
range is /16 to /30. Example: 10.0.0.0/16. The Networking service reserves the first two IP
addresses and the last one in each subnet's CIDR. After you've created a VCN or subnet, you
can't change its size, so it's important to think about the size of VCN and subnets you need
before creating them.

For your VCN, Oracle recommends using one of the private IP address ranges specified in RFC
1918 (10.0.0.0/8, 172.16/12, and 192.168/16). However, you can use a publicly routable
range. Regardless, this documentation uses the term private IP address when referring to IP
addresses in your VCN's CIDR.
The VCN's CIDR must not overlap with your on-premises network or another VCN you peer
with. The subnets in a given VCN must not overlap with each other. For reference, here's a
CIDR calculator.
Default Components that Come With Your VCN

Your VCN automatically comes with some default components (default route table, default
security list, default set of DHCP options). You can’t delete these default components.
However, you can change their contents (for example, the individual route rules). And you can
create more of each kind of component in your cloud network (additional route tables).
When you create a new subnet, you can associate a route table with it. If you don’t, the
default route table is automatically associated with the subnet. The same is true for security
lists and sets of DHCP options. After you associate a particular route table, security list, or set
of DHCP options with a subnet (whether it’s the default or not), you can’t change that
association. But as mentioned before, you can change the contents of the component.
For more information, see Route Tables, Security Lists, and DHCP Options.
Connectivity Choices
You can control whether subnets are public or private, and whether instances get public IP
addresses. You can set up your VCN to have access to the internet if you like. You can also
privately connect your VCN to your on-premises network and to another VCN.
Public vs. Private Subnets
When you create a subnet, by default it's considered public, which means instances in that
subnet are allowed to have public IP addresses. Whoever launches the instance chooses
whether it will have a public IP address. You can override that behavior when creating the
subnet and request that it be private, which means instances launched in the subnet are

prohibited from having public IP addresses. Network administrators can therefore ensure that
instances in the subnet have no internet access, even if the VCN has a working internet
gateway, and security lists and firewall rules allow the traffic.
How IP Addresses Are Assigned
Each instance has a primary VNIC that's created during instance launch and cannot be
removed. You can add secondary VNICs to an existing instance (in the same availability
domain as the primary VNIC) and remove them as you like.
Every VNIC has a private IP address from the associated subnet's CIDR. You can choose the
particular IP address (during instance launch or secondary VNIC creation), or Oracle can
choose it for you. You can also add secondary private IPs to a VNIC.
If the VNIC is in a public subnet, then each private IP on that VNIC can have a public IP
assigned to it at your discretion. Oracle chooses the particular IP address. There are two
types of public IPs: ephemeral and reserved. An ephemeral public IP exists only for the
lifetime of the private IP it's assigned to. In contrast, a reserved public IP exists as long as
you want it to. You maintain a pool of reserved public IPs and allocate them to your instances
at your discretion. You can move them from resource to resource in a region as you need to.
Internet Access
For an instance in a given subnet to have direct access to the internet:
l The VCN must have an internet gateway that is enabled.

l The subnet must be public.
l The subnet must have a route rule that directs traffic to the internet gateway.
l The subnet must have security list rules that allow the traffic (and each instance's
firewall must allow the traffic).
l The instance must have a public IP address.

Tip
For your instances to have access to any public IP

addresses outside the VCN, an internet gateway and the
other components mentioned above are required.
However, when an internet gateway receives traffic
from your VCN destined for a public IP address that is
part of Oracle Cloud Infrastructure (such as Object
Storage), the internet gateway routes the traffic to the
destination without sending the traffic over the internet.
Instances without public IP addresses or access to an internet gateway cannot access the
internet directly. However, you can configure a subnet to access the internet indirectly by
either:
l Setting up an instance in your VCN to perform Network Address Translation (NAT). For
information about routing subnet traffic to an instance, see Using a Private IP as a Route
Target.
l Connecting your VCN to your on-premises network via a DRG and then routing your
internet traffic to your on-premises network. Your on-premises network must be
configured to route traffic to the internet. For more information, see Connection to Your
On-Premises Network.
Connection to Your On-Premises Network
There are two ways to connect your on-premises network to Oracle Cloud Infrastructure:
l IPSec VPN: Offers multiple IPSec tunnels between your existing network's edge and
your VCN, by way of a DRG that you create and attach to your VCN.
l Oracle Cloud Infrastructure FastConnect: Offers a private connection between your
existing network's edge and Oracle Cloud Infrastructure. Traffic does not traverse the
internet. Both private peering and public peering are supported. That means you can

access private IPv4 addresses in your VCN as well as regional public IPv4 addresses in
Oracle Cloud Infrastructure (for example, Object Storage or public load balancers in
your VCN).
You can use one or both types of the preceding connections. If using both, you can use them
simultaneously, or in a redundant configuration.
Connection to Another VCN
You can connect your VCN to another VCN over a private connection that doesn't require the
traffic to traverse the internet. In general, this type of connection is referred to as VCN
peering. Each VCN must have specific components to enable peering. The VCNs must also
have specific IAM policies, route rules, and security lists that permit the connection to be
made and the desired network traffic to flow over the connection. For more information, see
VCN Peering.
Typical Networking Scenarios

This section describes several typical scenarios for using a VCN.
Scenario A: Public Subnets
This is the fastest way to try out Networking. The following figure illustrates the scenario. You
set up a VCN with:
l One public subnet per availability domain

l An internet gateway
l A corresponding route rule in the default route table
l The default security list
l The default set of DHCP options
You then launch one or more compute instances in one of the subnets. In this scenario, each
instance gets both a public and private IP address. You can then communicate with the
instances via the public IP address over the internet from your on-premises network.

For instructions on using the Console or API to set up a VCN with public subnets, see Scenario
A: Public Subnets.

Scenario B: Private Subnets with an IPSec VPN
In this scenario you set up a VCN with:
l Two private subnets in separate availability domains (to illustrate redundancy)

l A virtual private network connection (IPSec VPN) to provide private communication with
your on-premises network
l A corresponding route rule in the default route table
l A modified default security list, with additional rules to allow these additional types of
traffic:
o Stateful ingress rule for traffic from anywhere on TCP port 80 (HTTP)
o Stateful ingress rule for traffic from anywhere on TCP port 443 (HTTPS)
o Stateful ingress rule for traffic from anywhere on TCP port 1521 (for Oracle
databases)
Tip
For additional security, you could modify all the security

list ingress rules to allow traffic only from within your
VCN and your on-premises network.

The following figure illustrates the general layout. To use this scenario, you must have a
network administrator configure the router at your end of the IPSec VPN. You can then launch
an instance in your VCN and communicate with it using its private IP address from your on-
premises network.

You might use this scenario, for example, if you want to extend your private database servers
in your on-premises network into the cloud.
For instructions on using the Console or API to set up a VCN with private subnets and IPSec
VPN, see Scenario B: Private Subnets with a VPN.
Scenario C: Public and Private Subnets
In this scenario you set up a VCN with:
l Both a public subnet and a private subnet in a single availability domain

l Similar subnets in a second availability domain for redundancy
l An internet gateway so the instances in the public subnets can communicate with the
internet using their public IP addresses
l An IPSec VPN so the instances in the private subnets can communicate securely with
your on-premises network using their private IP addresses
l Two route tables to direct traffic out of the VCN—one for traffic to the internet and one
for traffic to your on-premises network
l A modified default security list, where you change all the existing stateful ingress rules
to allow traffic only from your on-premises network's CIDR block
l A separate security list just for the public subnets, with these rules:
o Stateful ingress rule for traffic from anywhere, on TCP ports 80 (HTTP) and 443
(HTTPS)
o Stateful egress rule for any traffic to the private subnets on TCP port 1521 (for
Oracle databases)
l A separate security list just for the private subnets, with these rules:
o Stateful ingress rule for any traffic from the public subnets, on TCP port 1521 (for
Oracle databases)
o Stateful ingress rule for any traffic in the private subnets, on TCP port 1521 (for
Oracle databases)

o Stateful egress rule for any traffic in the private subnets on TCP port 1521 (for
Oracle databases)
Notice that the public subnet would use both the default security list and the public subnet
security list. Likewise, the private subnet would use both the default security list and the
private subnet security list. The default security list contains a core set of stateful rules that
all subnets in the scenario need to use.
The following figure illustrates the general layout. To use this scenario, you must have a
network administrator configure the router at your end of the IPSec VPN.

You might use this scenario to host a cloud-based website that's connected to a database. The
web servers reside in the public subnet and are thus reachable from the internet. The
database servers reside in the private subnet.
For instructions on using the Console or API to set up a VCN with public and private subnets,
see Scenario C: Public and Private Subnets with a VPN.

Your VCN resides in a single Oracle Cloud Infrastructure region. Each subnet resides in a
single availability domain (AD). Availability domains are designed to provide isolation and
redundancy in your VCN, as illustrated in Scenario B and C earlier. For example, you could set
up your primary set of subnets in a single AD, and then set up a duplicate set of subnets in a
secondary AD. The two ADs are isolated from each other in the Oracle data centers, so if one
fails, you can easily switch over to the other AD. For more information, see Regions and
Availability Domains.
Public IP Addresses for Oracle Data Centers

The Oracle Cloud Infrastructure data centers use the following CIDR blocks for public IP
addresses. You should whitelist these on your on-premises network.
Ashburn (IAD) region

l 129.213.8.0/21
l 129.213.16.0/20
l 129.213.32.0/19
l 129.213.64.0/18
Frankfurt (FRA) region
l 130.61.8.0/21

l 130.61.16.0/20
l 130.61.32.0/19
l 130.61.64.0/19
London (LHR) region
l 132.145.8.0/21
l 132.145.16.0/20
l 132.145.32.0/19
Phoenix (PHX) region

l 129.146.0.0/21
l 129.146.8.0/22
l 129.146.16.0/20
l 129.146.32.0/21
l 129.146.40.0/22
l 129.146.64.0/18
l 129.146.128.0/19
IP Addresses Reserved for Use by Oracle

The following IP addresses are reserved for Oracle Cloud Infrastructure use:
169.254.0.2, 169.254.2.2-169.254.2.254
169.254.0.3

169.254.169.254
For DNS (port 53) and Metadata (port 80) services. See Getting Instance Metadata for more
information.
169.254.169.253




using.
Limits on Your Networking Components

increase.
Scenario A: Public Subnets

This topic explains how to set up Scenario A, which consists of a virtual cloud network (VCN)
and public subnets. See the following figure. For more information, see Typical Networking
Scenarios.

Required IAM Policy


If you're a member of the Administrators group, you already have the required access to
execute Scenario A. Otherwise, you need access to Networking, and you need the ability to
launch instances. See IAM Policies for Networking.
Setting Up Scenario A
Setup is easy in the Console. Alternatively, you can use the Oracle Cloud Infrastructure API,
which lets you execute the individual operations yourself.
Using the Console
1. Open the Console, and then click Networking.

2. Choose a compartment you have permission to work in (on the left side of the page).
The page updates to display only the resources in that compartment. If you're not sure
which compartment to use, contact an administrator. For more information, see Access
Control.
4. In Create in Compartment, leave the default value (the compartment you're
5. Enter a friendly name for the cloud network. It doesn't have to be unique, and it cannot
be changed later in the Console (but you can change it with the API).
6. Select Create Virtual Cloud Network Plus Related Resources.
This option is the quickest way to get a working cloud network in the fewest steps.
Oracle then automatically creates a VCN for you with CIDR block 10.0.0.0/16, an internet
gateway, a route rule to enable traffic to and from the internet gateway, the Default Security
List, the default set of DHCP options, and one public subnet per availability domain. The VCN
will automatically use the Internet and VCN Resolver for DNS.

Note
Security List Rule for Windows Instances
If you're going to launch Windows instances, you need

to add a security list rule to enable Remote Desktop
Protocol (RDP) access. Specifically, you need a stateful
ingress rule for TCP traffic on destination port 3389
from source 0.0.0.0/0 and any source port. For more
Your next step is to launch an instance into one of the subnets and then communicate with it
(for example, via SSH or RDP). For more information, see Launching an Instance.
Using the API
Use the following operations:
1. CreateVcn: Make sure to include a DNS label if you want the VCN to use the built-in DNS
capability (see DNS in Your Virtual Cloud Network).
2. CreateSubnet: To match the scenario described above, create one public subnet per
availability domain. Include a DNS label for each subnet if you want the VCN Resolver to
resolve hostnames for instances in the subnet. Use the default route table, default
security list, and default set of DHCP options.
3. CreateInternetGateway
4. UpdateRouteTable: To enable communication via the internet gateway, update the
default route table to include this route rule: 0.0.0.0/0 > internet gateway.
You now have a working cloud network (VCN) with an internet gateway, the Default Security
List, the default set of DHCP options, and at least one public subnet.

Note
Security List Rule for Windows Instances
If you're going to launch Windows instances, you need

to add a security list rule to enable Remote Desktop
Protocol (RDP) access. Specifically, you need a stateful
ingress rule for TCP traffic on destination port 3389
from source 0.0.0.0/0 and any source port. For more
Your next step is to launch an instance into a subnet in the VCN and then communicate with it
(for example, via SSH or RDP). For more information, see Launching an Instance.
Scenario B: Private Subnets with a VPN

This topic explains how to set up Scenario B, which consists of a virtual cloud network (VCN)
with two private subnets in different availability domains (to illustrate redundancy) and an
IPSec VPN. See the following figure. For more information, see Typical Networking Scenarios.


Tip
The scenarios uses an IPSec VPN for connectivity;

however, you could instead use Oracle Cloud
Infrastructure FastConnect.
Prerequisites
To set up the VPN in this scenario, you need to get the following information from a network
administrator:
l IP address of the on-premises router at your end of the VPN

l Static routes for your on-premises network
You will provide Oracle this information and in return receive the information your network
administrator needs in order to configure the on-premises router at your end of the VPN.
Required IAM Policy
execute Scenario B. Otherwise, you need access to Networking, and you need the ability to
Setting Up Scenario B

Important
Most of this process involves working with the Console

or API (whichever you choose) for a short period to set
up the desired Networking components. But there's also
a critical step that requires a network administrator in
your organization to take information you receive from
setting up the components and use it to configure the
on-premises router at your end of the VPN. Therefore
you can't complete this process in one short session.
You'll need to break for an unknown period of time while
the network administrator completes the configuration
and then return afterward to confirm communication
with your instances over the VPN.
Using the Console
To create the cloud network and subnets

1. Create the cloud network:
a. Open the Console, and then click Networking.
b. Choose a compartment you have permission to work in (on the left side of the
page). The page updates to display only the resources in that compartment. If
you're not sure which compartment to use, contact an administrator. For more
information, see Access Control.
c. Click Create Virtual Cloud Network.
d. For Create in Compartment, leave the default value (the compartment you're

e. Enter a friendly name for the cloud network. It doesn't have to be unique, and it
cannot be changed later in the Console (but you can change it with the API).
f. Make sure Create Virtual Cloud Network Only is selected.
g. For the CIDR Block, enter a single, contiguous CIDR block for the cloud network.
For example: 10.0.0.0/16. You cannot change this value later. For reference,
here's a CIDR calculator.
h. If you want the instances in the VCN to have DNS hostnames (which can be used
with the Internet and VCN Resolver, a built-in DNS capability in the VCN), select
the Use DNS Hostnames in this VCN checkbox. Then you can specify a DNS
label for the VCN, or the Console will generate one for you. The dialog box
automatically displays the corresponding DNS Domain Name for the VCN (<VCN
DNS label>.oraclevcn.com). For more information, see DNS in Your Virtual
Cloud Network.
i. Tags: Leave as is. You can add tags later if you want. For more information, see
Resource Tags.
j. Click Create Virtual Cloud Network.
The cloud network is then created and listed on the page.
2. Create the subnets in the cloud network:
a. On the Virtual Cloud Networks page, click the cloud network you just created.
b. Click Subnets.
c. Click Create Subnet.
d. Enter the following:
l Name: A friendly name for the first subnet (for example, Subnet1). It
doesn't have to be unique, and it cannot be changed later in the Console
(but you can change it with the API).
l Availability Domain: Choose one of the availability domains.

l CIDR Block: A single, contiguous CIDR block within the VCN's CIDR block.
For example: 10.0.1.0/24. You cannot change this value later. For
reference, here's a CIDR calculator.
l Route Table: Select the default route table.
l Private orpublic subnet: Select Private Subnet, which means VNICs in
the subnet cannot have public IP addresses. For more information, see
Internet Access.
l Use DNS Hostnames in this Subnet:This option is available only if you
provided a DNS label for the VCN during creation. If you want this subnet's
instances to have DNS hostnames (which can be used by the Internet and
VCN Resolver for DNS), select the check box for Use DNS Hostnames in
this Subnet. Then you may specify a DNS label for the subnet, or the
Console will generate one for you. The dialog box will automatically display
the corresponding DNS Domain Name for the subnet (<subnet DNS
label>.<VCN DNS label>.oraclevcn.com). For more information, see
l DHCP Options: Select the default set of DHCP options.
l Security Lists: Select the default security list.
l Tags: Leave as is. You can add tags later if you want. For more
information, see Resource Tags.
e. Click Create.
The first subnet is then created and displayed on the Subnets page.
f. Repeat the preceding steps to create the second subnet (for example, Subnet2
with CIDR block 10.0.2.0/24), but place it in a different availability domain than
the first subnet.
3. Update the default security list to include the rules described below:
a. While still on the page displaying your cloud network's subnets, click Security
Lists, and then click the default security list.

b. Click Edit Rules.

c. Add the following rules to the existing set:
l Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source
port = all, destination port=80 (for HTTP).
port = all, destination port=443 (for HTTPS).
port = all, destination port=1521 (for Oracle databases).
port=all, destination port=3389 (for RDP; required only if using Windows
instances).
d. When done, click Save Security List Rules.
Tip
For additional security, you could modify all the stateful

ingress rules to allow traffic only from within your VCN
and your on-premises network. You would need to
create separate rules for each, one with the VCN's CIDR
as the source, and one with the on-premises network's
CIDR as the source.
You could now launch one or more instances into the subnets (see Launching an Instance).
However, you wouldn't be able to communicate with them because there's no gateway
connecting the cloud network to your on-premises network. The next procedure walks you
through creating a VPN connection to enable that communication.

To add a VPN to your cloud network

1. Create a customer-premises equipment object:
a. In the Console, click Networking, and then click Customer-Premises
Equipment.
b. Click Create Customer-Premises Equipment.
c. Enter the following:
l Create in Compartment: Leave the default value (the compartment
you're currently working in).
l Name: A friendly name for the customer-premises equipment object. It
l IP Address: The public IP address of the on-premises router at your end of
the VPN (see Prerequisites).
d. Click Create.
The customer-premises equipment object will be in the "Provisioning" state for a short
period.
2. Create a dynamic routing gateway:
a. Click Networking, and then click Dynamic Routing Gateways.
b. Click Create Dynamic Routing Gateway.
c. For Create in Compartment: Leave the default value (the compartment you're
d. Enter a friendly name for the dynamic routing gateway. It doesn't have to be
unique, and it cannot be changed later in the Console (but you can change it with
the API).
e. Click Create.

The dynamic routing gateway will be in the "Provisioning" state for a short period. Make
sure it is done being provisioned before continuing.
3. Attach the dynamic routing gateway to your cloud network:
a. Click the dynamic routing gateway that you just created.
b. On the left side of the page, click Virtual Cloud Networks.
c. Click Attach to Virtual Cloud Network.
d. Select the cloud network you want to attach to the dynamic routing gateway, and
then click Attach to Virtual Cloud Network.
The attachment will be in the "Attaching" state for a short period before it's ready.
4. Update the default route table:
a. Click Networking, click Virtual Cloud Networks, and then click your cloud
network.
b. Click Route Tables, and then click the default route table.
c. Click Edit Route Rules.
d. Click + Another Route Rule.
e. Enter the following:
l Destination CIDR Block: 0.0.0.0/0 (which means that all non-intra-VCN
traffic that is not already covered by other rules in the route table will go to
the target specified in this rule).
l Target Type: Dynamic Routing Gateway.
l Compartment: Leave as is.
l Target: The dynamic routing gateway you created earlier.
f. Click Save.
The cloud network's default route table now directs outbound traffic to the
dynamic routing gateway and ultimately to your on-premises network.
5. Create an IPSec Connection:


b. Click the dynamic routing gateway you created earlier.
c. Click Create IPSec Connection.
l Name: Enter a friendly name for the IPSec connection. It doesn't have to
be unique, and it cannot be changed later in the Console (but you can
change it with the API).
l Customer-Premises Equipment: Select the customer-premises
equipment object you created earlier.
l Static Route CIDR: The CIDR block for a static route (see Prerequisites).
If you need to add another, click Add Static Route.
e. Click Create IPSec Connection.
The IPSec connection will be in the "Provisioning" state for a short period.
f. Click the Actions icon ( ), and then click Tunnel Information.
The configuration information for each tunnel is displayed (the IP address of the
VPN headend and the shared secret). Also, the tunnel's status is displayed (either
"Available" or "Down").
g. Copy the information for each of the tunnels into an email or other location so you
can deliver it to the network administrator who will configure the on-premises
router.
For more information, see Configuring Your On-Premises Router for an IPSec
VPN. You can view this tunnel information here in the Console at any time.
h. Click Close.
You have now created all the components required for the VPN. But your network
administrator must configure the on-premises router before network traffic can flow between
your on-premises network and cloud network.

To configure your on-premises router

These instructions are for the network administrator.
1. Make sure you have the tunnel configuration information that Oracle provided during
VPN setup. See To add a VPN to your cloud network.
2. Configure your on-premises router according to the information in Configuring Your On-
Premises Router for an IPSec VPN.
If there are already instances in one of the subnets, you can confirm the IPSec connection is
up and running by pinging the instances from your on-premises network.
Using the API
1. CreateVcn: Make sure to include a DNS label if you want the VCN to use the VCN
Resolver (see DNS in Your Virtual Cloud Network).
2. CreateSubnet: Call it twice, once for each subnet in the scenario. Set each subnet to be
private (that is, prohibit public IP addresses on the VNICs in the subnet). Include a DNS
label for each subnet if you want the VCN Resolver to resolve hostnames for VNICs in
the subnet. Use the default route table, default security list, and default set of DHCP
options.
3. CreateDrg: This creates a new dynamic routing gateway (DRG)
4. CreateDrgAttachment: This attaches the DRG to the VCN.
5. CreateCpe: Here you'll provide the IP address of the on-premises router at your end of
the VPN (see Prerequisites).
6. CreateIPSecConnection: Here you'll provide the static routes for your on-premises
network (see Prerequisites). In return, you'll receive the configuration information your
network administrator needs in order to configure your on-premises router. If you need
that information later, you can get it with GetIPSecConnectionDeviceConfig. For more

information about the configuration, see Configuring Your On-Premises Router for an
IPSec VPN.
7. UpdateRouteTable: To enable communication via the VPN, update the default route
table to include this route: 0.0.0.0/0 > DRG you created earlier.
8. First call GetSecurityList to get the default security list, and then call UpdateSecurityList
to add these additional rules to that list (be aware that UpdateSecurityList overwrites
the entire set of rules):
l Stateful ingress: Source CIDR=0.0.0.0/0, protocol=TCP, source port = all,
destination port=80 (for HTTP).
destination port=443 (for HTTPS).
destination port=1521 (for Oracle databases).
l Stateful ingress: Source CIDR=0.0.0.0/0, protocol=TCP, source port=all,
destination port=3389 (for RDP; required only if using Windows instances).
Tip
For additional security, you could modify all the

stateful ingress rules to allow traffic only from
within your VCN and your on-premises network.
You would need to create separate rules for each,
one with the VCN's CIDR as the source, and one
with the on-premises network's CIDR as the source.
9. LaunchInstance: Launch at least one instance in each subnet. For more information, see
Launching an Instance.

Important
Although you can launch instances into your subnets,

you won't be able to communicate with them from your
on-premises network until your network administrator
configures your on-premises router (see Configuring
Your On-Premises Router for an IPSec VPN). After that,
your IPSec connection should be up and running. You
can confirm its status by using
GetIPSecConnectionDeviceStatus. You can also confirm
the IPSec connection is up by pinging the instances from
your on-premises network.
Scenario C: Public and Private Subnets with a VPN

This topic explains how to set up Scenario C, which consists of a virtual cloud network (VCN)
with a public subnet, an internet gateway, a private subnet, and an IPSec VPN. See the
following figure. For more information, see Typical Networking Scenarios.

Tip
The scenarios uses an IPSec VPN for connectivity;

however, you could instead use Oracle Cloud

Prerequisites
To set up the VPN in this scenario, you need to get the following information from a network
administrator:
l IP address of the on-premises router at your end of the VPN

l Static routes for your on-premises network
You will provide Oracle this information and in return receive the information your network
administrator needs in order to configure the on-premises router at your end of the VPN.
Required IAM Policy
execute Scenario C. Otherwise, you need access to Networking, and you need the ability to
Setting Up Scenario C

Important
Most of this process involves working with the Console

or API (whichever you choose) for a short period to set
up the desired Networking components. But there's also
a critical step that requires a network administrator in
your organization to take information you receive from
setting up the components and use it to configure the
on-premises router at your end of the VPN. Therefore
you can't complete this process in one short session.
You'll need to break for an unknown period of time while
the network administrator completes the configuration
and then return afterward to confirm communication
with your instances over the VPN.
Using the Console
To create the cloud network and subnets

1. Create the cloud network:
a. Open the Console, and then click Networking.
b. Choose a compartment you have permission to work in (on the left side of the
page). The page updates to display only the resources in that compartment. If
you're not sure which compartment to use, contact an administrator. For more
information, see Access Control.
c. Click Create Virtual Cloud Network.

e. Enter a friendly name for the cloud network. It doesn't have to be unique, and it
f. Make sure Create Virtual Cloud Network Only is selected.
g. For the CIDR Block, enter a single, contiguous CIDR block for the cloud network.
For example: 10.0.0.0/16. You cannot change this value later. For reference,
here's a CIDR calculator.
h. If you want the instances in the VCN to have DNS hostnames (which can be used
with the Internet and VCN Resolver, a built-in DNS capability in the VCN), select
the Use DNS Hostnames in this VCN checkbox. Then you can specify a DNS
label for the VCN, or the Console will generate one for you. The dialog box
automatically displays the corresponding DNS Domain Name for the VCN (<VCN
DNS label>.oraclevcn.com). For more information, see DNS in Your Virtual
Cloud Network.
i. Tags: Leave as is. You can add tags later if you want. For more information, see
Resource Tags.
j. Click Create Virtual Cloud Network.
The cloud network is then created and listed on the page.
2. Create an internet gateway for your cloud network:
a. Click the cloud network you just created.
b. Click Internet Gateways.
c. Click Create Internet Gateway.
e. Enter a name for the internet gateway. It doesn't have to be unique, and it cannot
f. Click Create.
The internet gateway is then created and listed on the page.
3. Create two route tables (one for each subnet you'll later create):

a. Click Route Tables.

b. Click Create Route Table.
l Name: A friendly name for the first route table (for example, Public Subnet
Route Table). It doesn't have to be unique, and it cannot be changed later in
the Console (but you can change it with the API).
l Destination CIDR Block: 0.0.0.0/0 (which means that all non-intra-VCN
the target specified in this rule).
l Target Type: Internet Gateway.
l Compartment: Leave as is.
l Target: The internet gateway you just created.
d. Tags: Leave as is. You can add tags later if you want. For more information, see
Resource Tags.
e. Click Create Route Table.
The route table is then created and listed on the page.
f. Repeat the preceding steps to create the second route table (for example, with
name Private Subnet Route Table). Later on after you've set up the VPN, you'll
update the Private Subnet Route Table so its default route is directed toward the
dynamic routing gateway and thus to the VPN.
4. Modify the default security list:
a. Click Security Lists.
b. Click the default security list.

c. Click Edit Rules and:

l Change all of the existing stateful ingress rules so that the Source CIDR is
the CIDR for your on-premises network and not 0.0.0.0/0.
l If you plan to launch Windows instances, add a stateful ingress rule with
source CIDR=your on-premises network, protocol=TCP, source port = all,
destination port=3389 (for RDP access).
d. Click Save Security List Rules.
5. Create a security list for the public subnets:
a. Return to the page that shows your cloud network's details, and then click
Security Lists.
b. Click Create Security List.
d. In the Security List Name field, enter a friendly name for the list (for example,
Public Subnet Security List). It doesn't have to be unique, and it cannot be
changed later in the Console (but you can change it with the API).
e. Add the following ingress rules:
port = all, destination port=80 (for HTTP).
port = all, destination port=443 (for HTTPS).
f. Add the following egress rules:
l Stateful egress rule with destination CIDR=CIDR for your first private
subnet, protocol=TCP, source port = all, destination port=1521 (for Oracle
databases).
l Stateful egress rule with destination CIDR=CIDR for your second private
subnet, protocol=TCP, source port = all, destination port=1521 (for Oracle
databases).

g. Click Create Security List.

The public subnet security list is then created and listed on the page.
6. Create a security list for the private subnets:
a. Click Create Security List.
b. For Create in Compartment: Leave the default value (the compartment you're
c. In the Security List Name field, enter a friendly name for the list (for example,
Private Subnet Security List). It doesn't have to be unique, and it cannot be
changed later in the Console (but you can change it with the API).
d. Add the following ingress rules:
l Stateful ingress rule with source CIDR=CIDR for public subnet #1,
protocol=TCP, source port = all, destination port=1521 (for Oracle
databases).
l Stateful ingress rule with source CIDR=CIDR for public subnet #2,
databases).
l Stateful ingress rule with source CIDR=CIDR for your private subnet #1,
databases).
l Stateful ingress rule with source CIDR=CIDR for your private subnet #2,
databases).
e. Add the following egress rules:
l Stateful egress rule with destination CIDR=CIDR for private subnet #1,
databases).

l Stateful egress rule with destination CIDR=CIDR for private subnet #2,
databases).
f. Click Create Security List.
The private subnet security list is then created and listed on the page.
7. Create the subnets in the cloud network:
a. Return to the page that shows your cloud network's details, and click Subnets.
b. Click Create Subnet.
l Name: A friendly name for the first subnet (for example, Public Subnet 1).
It doesn't have to be unique, and it cannot be changed later in the Console
l Availability Domain: Choose one of the availability domains.
l CIDR Block: A single, contiguous CIDR block within the VCN's CIDR block.
For example: 10.0.1.0/24. You cannot change this value later. For
reference, here's a CIDR calculator.
l Route Table: Select the Public Subnet Route Table you created earlier.
l Private orpublic subnet: Select Public Subnet, which means VNICs in
the subnet are allowed to have public IP addresses. For more information,
see Internet Access.
l Use DNS Hostnames in this Subnet:This option is available only if you
instances to have DNS hostnames (which can be used by the Internet and
VCN Resolver for DNS), select the check box for Use DNS Hostnames in
this Subnet. Then you may specify a DNS label for the subnet, or the
Console will generate one for you. The dialog box will automatically display
the corresponding DNS Domain Name for the subnet (<subnet DNS
label>.<VCN DNS label>.oraclevcn.com). For more information, see

l DHCP Options: Select the default set of DHCP options.

l Security Lists: Select two security lists: Both the default security list and
the Public Subnet Security List you created earlier.
d. Click Create.
The public subnet is then created and displayed on the Subnets page.
e. Repeat the preceding steps a-d to create another subnet in the same availability
domain, but make this one a private subnet. In other words, use a name such as
Private Subnet 1, select Private Subnet instead of Public Subnet, use the
Private Subnet Route Table, and use both the default security list and Private
Subnet Security List you created earlier.
f. Now repeat the preceding steps a-e, but name the subnets Public Subnet 2 and
Private Subnet 2, and create the subnets in a different availability domain from
the original two subnets. For Public Subnet 2, set it up to use the Public Subnet
Route Table, and both the default security list and the Public Subnet Security List.
And set up Private Subnet 2 to use the Private Subnet Route Table, and both the
default security list and Private Subnet Security List. This design illustrates
redundancy for your subnets across availability domains.
You could now launch one or more instances into the subnets. However, you still need to
set up the VPN connection to your cloud network.
To add a VPN to your cloud network

1. Create a customer-premises equipment object:
a. In the Console, click Networking, and then click Customer-Premises
Equipment.
b. Click Create Customer-Premises Equipment.

l Name: A friendly name for the customer-premises equipment object. It

l IP Address: The IP address of the on-premises router at your end of the
VPN (see Prerequisites).
d. Click Create.
The customer-premises equipment object will be in the "Provisioning" state for a short
period.
2. Create a dynamic routing gateway:
b. Click Create Dynamic Routing Gateway.
d. Enter a friendly name for the dynamic routing gateway. It doesn't have to be
unique, and it cannot be changed later in the Console (but you can change it with
the API).
e. Click Create.
The dynamic routing gateway will be in the "Provisioning" state for a short period. Make
sure it is done being provisioned before continuing.
3. Attach the dynamic routing gateway to your cloud network:
a. Click the dynamic routing gateway that you just created.
Its details are displayed. You initially see the tab showing the IPSec connections
associated with the dynamic routing gateway. Instead, you want to view the tab
that shows the cloud network associated with this dynamic routing gateway.
b. Click Virtual Cloud Networks.
c. Click Attach to Virtual Cloud Network.

d. Select the cloud network you want to attach the dynamic routing gateway to and
click Attach to Virtual Cloud Network.
4. Update the private subnet's route table:
a. Click Networking, click Virtual Cloud Networks, and then click your cloud
network.
b. Click Route Tables, and then click the Private Subnet Route Table you created
earlier.
d. For the existing rule, change the Target Type to Dynamic Routing Gateway, and
for the Target, select the dynamic routing gateway you created earlier.:
e. Click Save.
The rule is updated to direct the traffic from the private subnet in the cloud
network to the dynamic routing gateway and ultimately to your on-premises
network.
5. Create an IPSec Connection:
b. Click the dynamic routing gateway you created earlier.
c. Click Create IPSec Connection.
l Name: Enter a friendly name for the IPSec connection. It doesn't have to
be unique, and it cannot be changed later in the Console (but you can

l Customer-Premises Equipment: Select the customer-premises

equipment object you created earlier.
l Static Route CIDR: The CIDR block for a static route (see Prerequisites).
If you need to add another, click Add Static Route.
e. Click Create IPSec Connection.
The IPSec connection will be in the "Provisioning" state for a short period.
f. Click the Actions icon ( ), and then click Tunnel Information.
The configuration information for each tunnel is displayed (the IP address of the
VPN headend and the shared secret). Also, the tunnel's status is displayed (either
"Available" or "Down").
g. Copy the information for each of the tunnels into an email or other location so you
can deliver it to the network administrator who will configure the on-premises
router.
For more information, see Configuring Your On-Premises Router for an IPSec
VPN. You can view this tunnel information here in the Console at any time.
h. Click Close.
You have now created all the components required for the VPN. But your network
administrator must configure the on-premises router before network traffic can flow between
your on-premises network and cloud network.
To configure your on-premises router

These instructions are for the network administrator.
1. Make sure you have the tunnel configuration information that Oracle provided during
VPN setup. See To add a VPN to your cloud network.
2. Configure your on-premises router according to the information in Configuring Your On-
If there already instances in one of the subnets, you can confirm the IPSec connection is up
and running by pinging the instances from your on-premises network.

Using the API
1. CreateVcn: Make sure to include a DNS label if you want the VCN to use the VCN
Resolver (see DNS in Your Virtual Cloud Network).
2. CreateInternetGateway
3. CreateRouteTable: Call it twice, once to create the Public Subnet Route Table and once
to create the Private Subnet Route Table. To enable communication via the internet
gateway, include this route: 0.0.0.0/0 > internet gateway.
4. First call GetSecurityList to get the default security list, and then call
UpdateSecurityList:
l Change the existing stateful ingress rules to use your on-premises network's
CIDR as the source CIDR, instead of 0.0.0.0/0.
l If you plan to launch Windows instances, add this stateful ingress rule: Source
CIDR = your on-premises network on TCP, source port = all, destination port =
3389 (for RDP).
5. CreateSecurityList: Call it to create the Public Subnet Security List with these rules:
l Stateful ingress: Source 0.0.0.0/0 on TCP, source port = all, destination port = 80
(HTTP)
l Stateful ingress: Source 0.0.0.0/0 on TCP, source port = all, destination port =
443 (HTTPS)
l Stateful egress: Destination CIDR blocks of private subnets on TCP, source port =
all, destination port = 1521 (for Oracle databases)
6. CreateSecurityList: Call it again to create the Private Subnet Security List with these
rules:
l Stateful ingress: Source CIDR blocks of public subnets on TCP, source port = all,
destination port = 1521 (for Oracle databases)

l Stateful ingress: Source CIDR blocks of private subnets on TCP, source port = all,
destination port = 1521 (for Oracle databases)
l Stateful egress: Destination CIDR blocks of private subnets on TCP, source port =
all, destination port = 1521 (for Oracle databases)
7. CreateSubnet: Call it four times, once each for Public Subnet 1 and Private Subnet 1 in
the first availability domain, and then once each for Public Subnet 2 and Private Subnet
2 in a second availability domain. For the two private subnets, set the flag to prohibit
public IP addresses on the VNICs in the subnet. Include a DNS label for each subnet if
you want the VCN Resolver to resolve hostnames for VNICs in the subnet. For the public
subnets, make sure to specify both the default security list and the Public Subnet
Security List that you created earlier. Likewise, for the private subnets, make sure to
specify both the default security list and the Private Subnet Security List that you
created earlier. Use the default set of DHCP options.
8. CreateDrg: This creates a new dynamic routing gateway (DRG).
9. CreateDrgAttachment: This attaches the DRG to the VCN.
10. CreateCpe: Here you'll provide the IP address of the router at your end of the VPN (see
Prerequisites).
11. CreateIPSecConnection: Here you'll provide the static routes for your on-premises
network (see Prerequisites). In return, you'll receive the configuration information your
network administrator needs in order to configure your router. If you need that
information later, you can get it with GetIPSecConnectionDeviceConfig. For more
information about the configuration, see Configuring Your On-Premises Router for an
IPSec VPN.
12. UpdateRouteTable: To enable communication via the VPN, update the Private Subnet
Route Table to include this route: 0.0.0.0/0 > dynamic routing gateway.
13. LaunchInstance: Launch at least one instance in each subnet. By default, the instances
in the public subnets will be assigned public IP addresses. For more information, see
You can now communicate from your on-premises network with the instances in the public
subnets over the internet gateway.

Important
Although you can launch instances into the private

subnets, you won't be able to communicate with them
from your on-premises network until your network
administrator configures your on-premises router (see
Configuring Your On-Premises Router for an IPSec
VPN). After that, your IPSec connection should be up
and running. You can confirm its status by using
GetIPSecConnectionDeviceStatus. You can also confirm
the IPSec connection is up by pinging the instances from
your on-premises network.
VCNs and Subnets

This topic describes how to manage virtual cloud networks (VCNs) and the subnets in them.
This topic uses the terms virtual cloud network, VCN, and cloud network interchangeably. The
Console uses the term Virtual Cloud Network, whereas for brevity the API uses VCN.
Working with VCNs and Subnets

A cloud network is a software-defined network that you set up in Oracle data centers. A
subnet is a subdivision of a cloud network. For an overview of VCNs, allowed size, default VCN
components, and scenarios for using your VCN, see Overview of Networking.
You can privately connect a VCN to another VCN in the same region so that the traffic does not
traverse the internet. The CIDRs for the two VCNs must not overlap. For more information,
see VCN Peering.
Each subnet in a VCN exists in a single availability domain and consists of a contiguous range
of IP addresses that do not overlap with other subnets in the cloud network. Example:
172.16.1.0/24. The first two IP addresses and the last in the subnet's CIDR are reserved by
the Networking service. You can't change the size of the subnet after creation, so it's

important to think about the size of subnets you need before creating them. Also, the subnet
acts as a unit of configuration: all instances in a given subnet use the same route table,
security lists, and DHCP options.
Subnets can be either public or private (see Public vs. Private Subnets). You choose this
during subnet creation, and you can't change it later.
You can think of each Compute instance as residing in a subnet. But to be precise, each
instance is actually attached to a virtual network interface card (VNIC), which in turn resides
in the subnet and enables a network connection for that instance.
cloud network and subnets to reside. Consult an administrator in your organization if you're
not sure which compartment to use. For more information, see Access Control.
You may optionally assign friendly names to the cloud network and its subnets. The names
don't have to be unique, and you can change them later. Oracle will automatically assign each
resource a unique identifier called an Oracle Cloud ID (OCID). For more information, see
Resource Identifiers.
You can also add a DNS label for the VCN and each subnet, which are required if you want the
instances to use the Internet and VCN Resolver feature for DNS in the VCN. For more
information, see DNS in Your Virtual Cloud Network.
You may optionally specify a route table for each subnet. If you don't, the cloud network's
default route table is associated with the subnet. After creating the subnet, you can't change
which route table is associated with it, but you can change the route rules in the table. For
more information about route tables, see Route Tables.
You may optionally specify one or more security lists for the subnet (up to five). If you don't
specify any, the cloud network's default security list is associated with the subnet. After
creating the subnet, you can't change which security lists are associated with it, but you can
change the rules in the lists. Remember that the security list rules are enforced at the
instance level, even though the list is associated at the subnet level. For more information,
see Security Lists.
Similarly, you may also optionally associate a set of DHCP options with the subnet during
creation. All instances in the subnet will receive the configuration specified in that set of DHCP

options. If you don't specify a set, the cloud network's set of default DHCP options is
associated with the subnet. After creating the subnet, you can't change which set of DHCP
options are associated with it, but you can change the values for the options. For more
information, see DHCP Options.
To delete a subnet, it must contain no instances, load balancers, or DB systems. For more
details, see Subnet Deletion.
To delete a cloud network, its subnets must be empty (contain no instances, load balancers,
or DB systems). Also, the cloud network must have no attached gateways. If you're using the
Console, there's a "Delete All" process you can use after first ensuring the subnets are empty.
See To delete a cloud network.
For information about the number of cloud networks and subnets you can have, see Service
Limits.
Required IAM Policy

For administrators: see IAM Policies for Networking.
Tagging Resources

Using the Console
To create a cloud network
Note
The following procedure creates a cloud network

without any subnets or gateways for access. You must
manually create the subnets and other resources before
you can use the cloud network. For a quick procedure
that creates a cloud network you can try out
immediately (that is, with subnets and an internet
gateway), see Scenario A: Public Subnets.
1. In the Console, click Networking.

Control.
a. Create in Compartment: Leave as is.
b. Name: A friendly name for the cloud network. It doesn't have to be unique, and it
c. Create Virtual Cloud Network Only: Make sure this radio button is selected.
d. CIDR Block: A single, contiguous CIDR block for the cloud network. For
example: 172.16.0.0/16. You cannot change this value later. See Allowed VCN
Size and Address Ranges. For reference, here's a CIDR calculator.

e. Use DNS Hostnames in this VCN: If you want the instances in the VCN to have
DNS hostnames (which can be used with the Internet and VCN Resolver, a built-in
DNS capability in the VCN), select the Use DNS Hostnames in this VCN
checkbox. Then you can specify a DNS label for the VCN, or the Console will
generate one for you. The dialog box automatically displays the corresponding
DNS Domain Name for the VCN (<VCN DNS label>.oraclevcn.com). For more
information, see DNS in Your Virtual Cloud Network.
f. Tags: Optionally, you can apply tags. If you have permissions to create a
administrator.
The cloud network is then created and displayed on the Virtual Cloud Networks page in the
compartment you chose. Next you'll typically want to create one or more subnets in the cloud
network.
To create a subnet
1. Confirm you're viewing the compartment that contains the cloud network that you want
to add the subnet to. If you've just created the cloud network, you should still be
viewing the same compartment. If you click Networking and then click Virtual Cloud
Networks, you should see the cloud network. For information about compartments and
access control, see Access Control.
2. On the Virtual Cloud Networks page, click the cloud network you're interested in.
3. Click Create Subnet.
4. In the Create Subnet dialog box, you specify the resources to associate with the
subnet (for example, a route table, and so on). By default, the subnet will be created in
the current compartment, and you'll choose the resources from the same compartment.

Click the click here link in the dialog box if you want to enable compartment selection
for the subnet and each of those resources.
Enter the following:
l Create in Compartment: If you've enabled compartment selection, specify the
compartment where you want to put the subnet.
l Name: A friendly name for the subnet. It doesn't have to be unique, and it cannot
l Availability Domain: The availability domain for the subnet. Any instances you
later launch into this subnet will also go into this availability domain.
l CIDR Block: A single, contiguous CIDR block for the subnet (for example,
172.16.0.0/24). Make sure it's within the cloud network's CIDR block and doesn't
overlap with any other subnets. You cannot change this value later. See Allowed
VCN Size and Address Ranges. For reference, here's a CIDR calculator.
l Route Table: The route table to associate with the subnet. If you've enabled
compartment selection, under Route Table Compartment, you must specify
the compartment that contains the route table.
l Private or public subnet: Whether VNICs in the subnet can have public IP
addresses. For more information, see Internet Access.
l Use DNS Hostnames in this Subnet: This option is available only if you
instances to have DNS hostnames (which can be used by the Internet and VCN
Resolver for DNS), select the check box for Use DNS Hostnames in this
Subnet. Then you may specify a DNS label for the subnet, or the Console will
generate one for you. The dialog box will automatically display the corresponding
DNS Domain Name for the subnet (<subnet DNS label>.<VCN DNS
label>.oraclevcn.com). For more information, see DNS in Your Virtual Cloud
Network.

l DHCP Options: The set of DHCP options to associate with the subnet. If you've
enabled compartment selection, under DHCP Options Compartment, you must
specify the compartment that contains the set of DHCP options.
l Security Lists: One or more security lists to associate with the subnet. If you've
enabled compartment selection, you must specify the compartment that contains
the security list.
administrator.
5. Click Create.
The subnet is then created and displayed on the Subnets page in the compartment you
chose.
To delete a subnet
Prerequisite: The subnet must have no instances, load balancers, or DB systems in it. For
more information, see Subnet Deletion.
A list of the cloud networks in the compartment you're viewing is displayed. If you don’t
see the one you're looking for, verify that you’re viewing the correct compartment
2. Click Subnets.
3. For the subnet you want to delete, click Terminate.

If the subnet is empty, its state changes to TERMINATING briefly and then TERMINATED. If
the subnet is not empty, you get an error indicating that there are still instances or load
balancers that you must delete first.
To delete a cloud network
Important
The Console has an easy "Delete all" process that

deletes a VCN and its related Networking resources
(subnets, route tables, security lists, sets of DHCP
options, internet gateway, and so on). If the VCN is
attached to a Dynamic Routing Gateway (DRG), the
attachment is deleted, but the DRG remains.
The "Delete All" process deletes one resource at a time

and takes a minute or two. A progress report is
displayed to show you what's been deleted so far.
Before using the "Delete All" process, make sure there

are no instances, load balancers, or DB systems in any
of the subnets. For more information, see Subnet
Deletion.
If there are still resources in any subnet, or if you don't

have permission to delete a particular Networking
resource, the "Delete All" process stops and an error
message is displayed. Any resources deleted up to that
point cannot be restored. You might need to contact
your tenancy administrator to help you delete any
remaining resources.

2. For the cloud network you want to delete, click the Actions icon ( ), and then click
Terminate.
The resulting dialog box displays a list of the resources to be deleted. The list doesn't
include the default components that come with the VCN, but they will be deleted along
with the VCN.
3. Click Delete All.
The process begins. The progress is displayed as each resource is deleted.
4. When the process is complete, click Close.
To manage tags for a VCN

2. Click the VCN you're interested in.
ones.
To manage tags for a subnet


3. For the subnet you're interested in, click the Actions icon ( ), and then click View
Tags. From there you can view the existing tags, edit them, and apply new ones.
Using the API

To manage your VCNs, use these operations:
l ListVcns
l CreateVcn
l GetVcn
l UpdateVcn
l DeleteVcn: Deletes only the VCN and not its related resources. Note that the Console
offers a "Delete All" process that makes it easy to delete the VCN and its related
resources. See To delete a cloud network.
To manage a VCN's subnets, use these operations:
l ListSubnets
l CreateSubnet
l GetSubnet
l UpdateSubnet: You can update only the subnet's name and tags.
l DeleteSubnet
Access and Security

See these topics for more information about access and security in your cloud network:

l Ways to Secure Your Network

l Access Control
l Security Lists
Ways to Secure Your Network

There are several ways you can control security for your cloud network and compute
instances:
l Public vs. private subnets: You can designate a subnet to be private, which means
instances in the subnet cannot have public IP addresses. For more information, see
Public vs. Private Subnets.
l Security lists: To control packet-level traffic in/out of an instance. You configure
security lists in the Oracle Cloud Infrastructure API or Console. For more information
about security lists, see Security Lists.
l Firewall rules: To control packet-level traffic in/out of an instance. You configure
firewall rules directly on the instance itself. Notice that Oracle Cloud Infrastructure
images that run Oracle Linux automatically include default rules that allow ingress on
TCP port 22 for SSH traffic. Also, the Windows images include default rules that allow
ingress on TCP port 3389 for Remote Desktop access. For more information, see Oracle-
Provided Images.

Important
Firewall rules and security lists both operate at the

instance level. However, you configure security
lists at the subnet level, which means all instances
in a given subnet have the same set of security list
rules. Keep this in mind when setting up security for
your cloud network and instances. When
troubleshooting access to an instance, make sure
both the security lists associated with the instance's
subnet and the instance's firewall rules are set
correctly.
If your instance is running Oracle Linux 7, you need
to use firewalld to interact with the iptables rules.
For your reference, here are commands for opening
a port (1521 in this example):
sudo firewall-cmd --zone=public --permanent --add-
port=1521/tcp
sudo firewall-cmd --reload
l Gateways and route tables: To control general traffic flow from your cloud network
to outside destinations (the internet, your on-premises network, or another VCN). You
configure your cloud network's gateways and route tables in the Oracle Cloud
Infrastructure API or Console. For more information about the gateways, see
Networking Components. For more information about route tables, see Route Tables.
l IAM policies: To control who has access to the Oracle Cloud Infrastructure API or
Console itself. You can control the type of access, and which cloud resources can be
accessed. For example, you can control who can set up your network and subnets, or
who can update route tables or security lists. You configure policies in the Oracle Cloud
Infrastructure API or Console. For more information, see Access Control.

Access Control
This topic gives basic information about using compartments and IAM policies to control
access to your cloud network.
Compartments and Your Cloud Network
Anytime you create a cloud resource such as a virtual cloud network (VCN) or compute
instance, you must specify which IAM compartment you want the resource in. A compartment
is a collection of related resources that can be accessed only by certain groups that have been
given permission by an administrator in your organization. The administrator will create
compartments and corresponding IAM policies to control which users in your organization
have access to which compartments. Ultimately, the goal is to ensure that each person has
access to only the resources they need.
If your company is starting to try out Oracle Cloud Infrastructure, only a few people need to
create and manage the VCN and its components, launch instances into the VCN, and attach
block storage volumes to those instances. Those few people need access to all these
resources, so all those resources could be in the same compartment.
In an enterprise production environment with a VCN, your company will want to use multiple
compartments to make it easier to control access to certain types of resources. For example,
your administrator could create Compartment_A for your VCN and other networking
components. The administrator could then create Compartment_B for all the compute
instances and block storage volumes that the HR organization uses, and Compartment_C for
all the instances and block storage volumes that the Marketing organization uses. The
administrator would then create IAM policies that give users only the level of access they
need in each compartment. For example, the HR instance administrator is not entitled to
modify the existing cloud network. So they would have full permissions for Compartment_B,
but limited access to Compartment_A (just what's required to launch instances into the
network). If they tried to modify other resources in Compartment_A, the request would be
denied.
For more information about compartments and how to control access to your cloud resources,
see "Setting Up Your Tenancy" in the Oracle Cloud Infrastructure Getting Started Guide and
Overview of IAM.

IAM Policies for Networking
The simplest approach to granting access to Networking is the policy listed in Let network
admins manage a cloud network. It covers the cloud network and all the other Networking
components (subnets, security lists, route tables, gateways, and so on). To also give network
admins the ability to launch instances (to test network connectivity), see Let users launch
instances.
For reference material for writing more detailed policies for Networking, see Details for the
Core Services.
I NDIVIDUAL RESOURCE -TYPES
If you'd like, you can write policies that focus on individual resource-types (for example, just
security lists) instead of the broader virtual-network-family. Be aware that the instance-
family resource-type also includes several permissions for VNICs, which reside in a subnet
but attach to an instance. For more information, see For instance-family Resource Types and
Virtual Network Interface Cards (VNICs).
There's a resource-type called local-peering-gateways that is included within virtual-

network-family and includes two other resource-types related to local VCN peering:
l local-peering-from
l local-peering-to
The local-peering-gateways resource-type covers all permissions related to local peering

gateways (LPGs).
The local-peering-from and local-peering-to resource-types are for granting permission

to connect two LPGs and form a peering relationship. For more information, see VCN Peering.
NUANCES OF DIFFERENT VERBS
If you'd like, you can write policies that limit the level of access by using a different policy
verb ( manage vs. use, and so on). If you do, there are some nuances to understand about the
policy verbs for Networking.

Be aware that the inspect verb not only returns general information about the cloud
network's components (for example, the name and OCID of a security list, or of a route
table). It also includes the contents of the component (for example, the actual rules in the
security list, the routes in the route table, and so on).
Also, the following types of abilities are available only with the manage verb, not the use verb:
l Update (enable/disable) internet-gateways

l Update security-lists
l Update route-tables
l Update dhcp-options
l Attach a dynamic routing gateway (DRG) to a virtual cloud network (VCN)
l Create an IPSec connection between a DRG and customer-premises equipment (CPE)

Important
Each VCN has various components that directly affect

the behavior of the network (route tables, security lists,
DHCP options, Internet Gateway, and so on). When you
create one of these components, you establish a
relationship between that component and the VCN,
which means you must be allowed in a policy to both
create the component and manage the VCN itself.
However, the ability to update that component (to
change the route rules, security list rules, and so on)
does NOT require permission to manage the VCN itself,
even though changing that component can directly
affect the behavior of the network. This discrepancy is
designed to give you flexibility in granting least
privilege to users, and not require you to grant
excessive access to the VCN just so the user can
manage other components of the network. Be aware
that by giving someone the ability to update a particular
type of component, you're implicitly trusting them with
controlling the network's behavior.
For more information about policy verbs, see Verbs.
Security Lists
In addition to using IAM policies to control who can manipulate your VCN (for example, add an
internet gateway, change route table rules), you can use security lists to control traffic at the
packet level.

Overview of Security Lists
A security list provides a virtual firewall for an instance, with ingress and egress rules that
specify the types of traffic allowed in and out. Each security list is enforced at the instance
level. However, you configure your security lists at the subnet level, which means that all
instances in a given subnet are subject to the same set of rules. The security lists apply to a
given instance whether it's talking with another instance in the VCN or a host outside the VCN.
Each subnet can have multiple security lists associated with it, and each list can have multiple
rules (for the maximum number, see Service Limits). A packet in question is allowed if any
rule in any of the lists allows the traffic (or if the traffic is part of an existing connection being
tracked). There's a caveat if the lists happen to contain both stateful and stateless rules that
cover the same traffic. For more information, see Stateful vs. Stateless Rules.
Important
Your instances running Oracle-provided Linux images or

Windows images also have firewall rules that control
access to the instance. When troubleshooting access to
an instance, make sure both the security lists
associated with the instance's subnet and the instance's
firewall rules are set correctly. For more information,
see Oracle-Provided Images.
If your instance is running Oracle Linux 7, you need to

use firewalld to interact with the iptables rules. For your
reference, here are commands for opening a port (1521
in this example):
port=1521/tcp
Security lists are regional entities. For the limit on the number of security lists you can have
in a VCN, see Service Limits.

Note
Security lists are not enforced for traffic involving the

169.254.0.0/16 CIDR block, which includes services
such as iSCSI and instance metadata.
Stateful vs. Stateless Rules
When you create a security list rule, you choose whether it's stateful or stateless. The
difference is described below. The default is stateful. Stateless rules are recommended if you
have a high-volume internet-facing website (for the HTTP/HTTPS traffic).
S TATEFUL RULES
If you add a stateful rule to a security list, that indicates that you want to use connection
tracking for any traffic that matches that rule (for instances in the subnet the security list is
associated with). This means that when an instance receives traffic matching the stateful
ingress rule, the response is tracked and automatically allowed back to the originating host,
regardless of any egress rules applicable to the instance. And when an instance sends traffic
that matches a stateful egress rule, the incoming response is automatically allowed,
regardless of any ingress rules. For more details, see Connection Tracking Details for Stateful
Rules.

The figure below illustrates a stateful ingress rule for an instance that needs to receive and
respond to HTTP traffic. Instance A and Host B are communicating (Host B could be any host,
whether an instance or not). The stateful ingress rule allows traffic from any source IP
address (0.0.0.0/0) to destination port 80 only (TCP protocol). No egress rule is required to
allow the response traffic.
S TATELESS RULES
If you add a stateless rule to a security list, that indicates that you do NOT want to use
connection tracking for any traffic that matches that rule (for instances in the subnet the
security list is associated with). This means that response traffic is not automatically allowed.
To allow the response traffic for a stateless ingress rule, you must create a corresponding
stateless egress rule.
The next figure shows Instance A and Host B as before, but now with stateless security list
rules. As with the stateful rule above, the stateless ingress rule allows traffic from all IP
addresses and any ports, on destination port 80 only (using the TCP protocol). To allow the
response traffic, there needs to be a corresponding stateless egress rule that allows traffic to

any destination IP address (0.0.0.0/0) and any ports, from source port 80 only (using the TCP
protocol).

If Instance A needs instead to initiate HTTP traffic and get the response, then a different set of
stateless rules are required. As the next figure shows, the egress rule would have source port
= all and destination port = 80 (HTTP). The ingress rule would then have source port 80 and
destination port = all.
If you were to use port binding on Instance A to specify exactly which port the HTTP traffic
would come from, you could specify that as the source port in the egress rule and the
destination port in the ingress rule.

Note
If for some reason your security lists contain both

stateful and stateless rules, and there's traffic that
matches both a stateful and stateless rule in a particular
direction (for example, ingress), the stateless rule
takes precedence and the connection is not tracked. You
would need a corresponding rule in the other direction
(for example, egress, either stateless or stateful) in
order for the response traffic to be allowed.
ENABLING PATH MTU DISCOVERY MESSAGES FOR S TATELESS RULES
If you decide to use stateless security list rules to allow traffic to/from endpoints outside the
VCN, it's important to add a security list rule that allows ingress ICMP traffic type 3 code 4
from source 0.0.0.0/0 and any source port. This rule enables your instances to receive Path
MTU Discovery fragmentation messages. This rule is critical for establishing a connection to
your instances. Without it, you can experience connectivity issues. For more information, see
Hanging Connection.
Default Security List
Each cloud network has a default security list. A given subnet automatically has the default
security list associated with it if you don't specify one or more other security lists during
subnet creation. After you create a subnet, you can't change which security lists are
associated with it. However, you can change the rules in the lists.
Unlike other security lists, the default security list comes with an initial set of stateful rules,
which you can change:
l Stateful ingress: Allow TCP traffic on destination port 22 (SSH) from source 0.0.0.0/0
and any source port. This rule makes it easy for you to create a new cloud network and
public subnet, launch a Linux instance, and then immediately connect via SSH to that

instance without needing to write any security list rules yourself.
Important
The default security list does not include a rule to

allow Remote Desktop Protocol (RDP) access. If
you're using Windows images, make sure to add a
stateful ingress rule for TCP traffic on destination
port 3389 from source 0.0.0.0/0 and any source
port.
See To enable RDP access for more information.
l Stateful ingress: Allow ICMP traffic type 3 code 4 from source 0.0.0.0/0 and any
source port. This rule enables your instances to receive Path MTU Discovery
fragmentation messages.
l Stateful ingress: Allow ICMP traffic type 3 (all codes) from source = your VCN's CIDR
and any source port. This rule makes it easy for your instances to receive connectivity
error messages from other instances within the VCN.
l Stateful egress: Allow all traffic. This allows instances to initiate traffic of any kind to
any destination. Notice that this means the instances can talk to any internet IP address
if the cloud network has an internet gateway. And because stateful security rules use
connection tracking, the response traffic is automatically allowed regardless of any
ingress rules. For more information, see Connection Tracking Details for Stateful Rules.
The default security list comes with no stateless rules. However, you can add or remove rules
from the default security list as you like.
Parts of a Security List Rule
Each security list can contain one or more rules, and each rule allows either ingress or
egress traffic. You choose whether the rule is stateful or stateless. For examples of rules, see
Stateful vs. Stateless Rules, and see Typical Networking Scenarios. For the limit on the
number of rules you can have in a security list, see Service Limits.

Each ingress rule specifies the following:
l Stateful or stateless: If stateful, connection tracking is used for traffic matching the
rule. If stateless, no connection tracking is used. See Stateful vs. Stateless Rules.
l Protocol: Either a single IPv4 protocol or "all" to cover all protocols.
l Source CIDR: A CIDR block where the traffic originates from. Use 0.0.0.0/0 to indicate
all IP addresses. The prefix is required (for example, include the /32 if specifying an
individual IP address).
l Source port: The port where the traffic originates from. For TCP or UDP, you can
specify all source ports, or optionally specify a single source port number, or a range.
l Destination port: The port where the traffic is destined to. For TCP or UDP, you can
specify all destination ports, or optionally specify a single destination port number, or a
range.
l ICMP type and code: For ICMP, you can specify all types and codes, or optionally
specify a single type with an optional code. If the type has multiple codes, create a
separate rule for each code you want to allow.
Each egress rule specifies the following:
l Stateful or stateless: Whether connection tracking is used for the traffic matching the
rule. See Stateful vs. Stateless Rules.
l Protocol: Either a single IPv4 protocol or "all" to cover all protocols.
l Destination CIDR: A CIDR block where the traffic is destined to. Use 0.0.0.0/0 to
indicate all IP addresses. The prefix is required (for example, include the /32 if
specifying an individual IP address).
l Source port: The port where the traffic originates from. For TCP or UDP, you can
specify all source ports, or optionally specify a single source port number, or a range.
l Destination port: The port where the traffic is destined to. For TCP or UDP, you can
specify all destination ports, or optionally specify a single destination port number, or a
range.

l ICMP type and code: For ICMP, you can specify all types and codes, or optionally
specify a single type with an optional code. If the type has multiple codes, create a
separate rule for each code you want to allow.
For instructions on working with security lists and rules, see the sections that follow.
Connection Tracking Details for Stateful Rules
Oracle uses connection tracking to allow responses for traffic that matches stateful rules (see
Stateful vs. Stateless Rules). Each instance has a maximum number of concurrent
connections that can be tracked, based on the instance's shape.
To determine response traffic for TCP, UDP, and ICMP, Oracle performs connection tracking
on these items for the packet:
l Protocol
l Source and destination IP addresses
l Source and destination ports (for TCP and UDP only)
Note
For other protocols, Oracle tracks only the protocol and

IP addresses, and not the ports. This means that when
an instance initiates traffic to another host and that
traffic is allowed by egress security list rules, any traffic
that the instance subsequently receives from that host
for a period is considered response traffic and is
allowed.
Rules to Handle Fragmented UDP Packets
Instances can send or receive UDP traffic. If a UDP packet is too large for the connection, it is
fragmented. However, only the first fragment from the packet contains the protocol and port
information. If the security list rules that allow this ingress or egress traffic specify a

particular port number (source or destination), the fragments after the first one are dropped.
If you expect your instances to send or receive large UDP packets, set both the source and
destination ports for the applicable security list rules to ALL (instead of a particular port
number).
Required IAM Policy
For administrators: The policy in Let network admins manage a cloud network covers
management of all Networking components, including security lists.
If you have security admins who need to manage security lists but not other components in
Networking, you could write a more restrictive policy:
Allow group SecListAdmins to manage security-lists in tenancy
Allow group SecListAdmins to manage vcns in tenancy
Both statements are needed because the creation of a security list affects the VCN the
security list is in. The second statement also allows the SecListAdmins group to create new
VCNs, but not create subnets or manage any other components related to any of those VCNs,
except for the security lists. The group also can't delete any existing VCNs that already have
subnets in them.
For more information, see IAM Policies for Networking.
Working with Security Lists
When you create a new subnet, you must associate at least one security list with it. It can be
either the cloud network's default security list or one or more other security lists that you've
created (for the maximum number, see Service Limits). After creating the subnet, you can't
change which security lists are associated with it, so make sure to create your desired

security list before creating the subnet. However, remember that you can change a security
list's rules at any time.
You may optionally assign a friendly name to the security list during creation. It doesn't have
to be unique, and you can change it later. Oracle will automatically assign the security list a
unique identifier called an Oracle Cloud ID (OCID). For more information, see Resource
Identifiers.
security list to reside. Consult an administrator in your organization if you're not sure which
compartment to use. For more information, see Access Control.
You can add and remove rules from the security list, but notice that when you update a
security list in the API, the new set of rules replaces the entire existing set of rules.
To delete a security list, it must not be associated with a subnet yet. You can't delete a cloud
network's default security list.
Tagging Resources
Using the Console
To view a cloud network's default security list

1. In the Console, click Networking, and then click Virtual Cloud Networks
The details are displayed.
3. Click Security Lists.

The default security list is listed on the page.

4. Click the name of the security list to view its details.
On the left side of the page, click Ingress Rules or Egress Rules to switch between
the different types of rules.
To update an existing security list
Important
When updating the default security list, be aware of the

default rules, the purpose each serves, and the
consequences of deleting them. For example, deleting
the existing ICMP type 3 code 4 rule can cause problems
when you connect to your instances. For more
information, see Hanging Connection.
4. Click the security list you're interested in.
6. Make one or more of these changes:
l Change an existing rule in the list.
l Add a new rule (see details of adding a rule in To create a new security list).
l Delete an existing rule by clicking the X next to the rule.

7. When you're done, click Save Security List Rules.
To create a new security list

to add the security list to. If you've just created the cloud network, you should still be
4. Click Create Security List.
a. Create in Compartment: The compartment where you want to create the
security list, if different from the compartment you're currently working in.
b. Security List Name: A friendly name for the security list. The name doesn't
have to be unique, and it cannot be changed later in the Console (but you can
6. Add at least one ingress or egress rule (for examples of rules, see the scenarios in
Typical Networking Scenarios):
a. Choose whether it's a stateful or stateless rule (see Stateful vs. Stateless Rules).
By default, rules are stateful unless you specify otherwise.
b. Enter either the source CIDR (for ingress) or destination CIDR (for egress). For
example, use 0.0.0.0/0 to indicate all IP addresses. Other typical CIDRs you
might specify in a rule are the CIDR block for your on-premises network, or for a
particular subnet.
c. Select the protocol (for example, TCP, UDP, ICMP, "All protocols", and so on).

d. Enter further details depending on the protocol:

l If you chose TCP or UDP, enter a source port range and destination port
range. You can enter "All" to cover all ports. If you want to allow a specific
port, enter the port number (for example, 22 for SSH or 3389 for RDP) or a
port range (for example, 20-22).
l If you chose ICMP, you can enter "All" to cover all types and codes. If you
want to allow a specific ICMP type, enter the type and an optional code
separated by a comma (for example, 3,4). If the type has multiple codes
you want to allow, create a separate rule for each code.
7. Click + Add Rule to add additional rules. Make sure to delete any partially completed
rules by clicking the X next to the rule.
8. Tags: Optionally, you can apply tags. If you have permissions to create a resource, you
also have permissions to apply free-form tags to that resource. To apply a defined tag,
you must have permissions to use the tag namespace. For more information about
tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option
(you can apply tags later) or ask your administrator.
9. When you're done, click Create Security List.
The security list is created and then displayed on the Security Lists page in the compartment
you chose. You can now specify this security list when creating a new subnet. Notice that any
stateless rules in the list are shown above any stateful rules. Stateless rules in the list take
precedence over stateful rules. In other words: If there's traffic that matches both a stateless
rule and a stateful rule across all the security lists associated with the subnet, the stateless
rule takes precedence and the connection is not tracked.
To delete a security list

Prerequisite: To delete a security list, it must not be associated with a subnet yet. You can't
delete the default security list in a cloud network.
1. In the Console, click Networking, and then click Cloud Networks.


4. For the security list you want to delete, click the Actions icon ( ), and then click
Terminate.
To manage tags for a security list

4. Click the security list you're interested in.
ones.
Using the API
To manage a VCN's security lists, use these operations:
l ListSecurityLists
l GetSecurityList
l UpdateSecurityList

l CreateSecurityList
l DeleteSecurityList
Virtual Network Interface Cards (VNICs)

This topic describes how to manage the virtual network interface cards (VNICs) in a virtual
cloud network (VCN).
Overview of VNICs and Physical NICs

The servers in Oracle Cloud Infrastructure data centers have physical network interface cards
(NICs). When you launch an instance on one of these servers, the instance communicates
using Networking service virtual NICs (VNICs) associated with the physical NICs. The next
sections talk about VNICs and NICs, and how they're related.
About VNICs
A VNIC enables an instance to connect to a VCN and determines how the instance connects
with endpoints inside and outside the VCN. Each VNIC resides in a subnet in a VCN and
includes these items:
l One primary private IPv4 address from the subnet the VNIC is in, chosen by either you
or Oracle.
l Up to 31 optional secondary private IPv4 addresses from the same subnet the VNIC is
in, chosen by either you or Oracle.
l An optional public IPv4 address for each private IP, chosen by Oracle but assigned by
you at your discretion.
l An optional hostname for DNS for each private IP address (see DNS in Your Virtual
Cloud Network).
l A MAC address.
l A VLAN tag assigned by Oracle and available when attachment of the VNIC to the
instance is complete (relevant only for bare metal instances).

l A flag to enable or disable the source/destination check on the VNIC's network traffic
(see Source/Destination Check).
Each VNIC also has a friendly name you can assign, and an Oracle-assigned OCID (see
Resource Identifiers).
Each instance has a primary VNIC that is automatically created and attached during launch.
That VNIC resides in the subnet you specify during launch. The primary VNIC cannot be
removed from the instance.
How VNICs and Physical NICs Are Related
This section is relevant to bare metal instances.
The OS on a bare metal instance recognizes two physical network devices and configures
them as two physical NICs, 0 and 1. Whether they're both active depends on the underlying
hardware:
l Oracle X5 servers (also called first-generation): Only NIC 0 is active.

l Oracle X7 servers (also called second-generation): Both NIC 0 and NIC 1 are
active. Each physical NIC has 25 Gbps bandwidth.
NIC 0 is automatically configured with the primary VNIC's IP configuration (the IP addresses,
DNS hostname, and so on).
If you add a secondary VNIC to a second-generation instance, you must specify which
physical NIC the secondary VNIC should use. You must also configure the OS so that the
physical NIC has the secondary VNIC's IP configuration. See Configuration Script for Either
Linux VM Instances or Linux Bare Metal Instances.
About Secondary VNICs
You can add secondary VNICs to an instance after it's launched. The secondary VNIC can be in
a subnet in the same VCN as the primary VNIC or a different VCN. However, all the VNICs
must be in subnets in the same availability domain as the instance.

Here are a few reasons why you might use secondary VNICs:
l Use your own hypervisor on a bare metal instance: The virtual machines on the
bare metal instance each have their own secondary VNIC, giving direct connectivity to
other instances and services in the VNIC's VCN. For more information, see Installing
and Configuring KVM on Bare Metal Instances with Multi-VNIC.
l Connect an instance to multiple subnets in a VCN: For example, you might have
a network appliance to monitor traffic between subnets, so the instance needs to
connect to multiple subnets in the VCN.
l Connect an instance to multiple VCNs: For example, you might have resources that
need to be shared between two teams that each have their own VCN.
Here are more details about secondary VNICs:
l They're supported only for Linux instances (both VM and bare metal). Also see Linux:
Configuring the OS for Secondary VNICs .
l There's a limit to how many VNICs can be attached to an instance, and it varies by
shape. For those limits, see the tables in shape.
l They can be added only after the instance is launched.
l They must always be attached to an instance and cannot be moved. The process of
creating a secondary VNIC automatically attaches it to the instance. The process of
detaching a secondary VNIC automatically deletes it.
l They are automatically detached and deleted when you terminate the instance.
l The instance's bandwidth is fixed regardless of the number of VNICs attached. You can't
specify a bandwidth limit for a particular VNIC on an instance.
l Attaching multiple VNICs from the same subnet CIDR block to an instance can introduce
asymmetric routing, especially on instances using a variant of Linux. If you need this
type of configuration, Oracle recommends assigning multiple private IP addresses to
one VNIC, or using policy-based routing as shown in the script later in this topic.

Source/Destination Check
By default, every VNIC performs the source/destination check on its network traffic. The VNIC
looks at the source and destination listed in the header of each network packet. If the VNIC is
not the source or destination, then the packet is dropped.
If the VNIC needs to forward traffic (for example, if it needs to perform Network Address
Translation (NAT)), you must disable the source/destination check on the VNIC. For
instructions, see To update an existing VNIC. For information about the general scenario, see
Using a Private IP as a Route Target.
VNIC Information in the Instance Metadata
The instance metadata includes information about the VNICs at this URL:
http://169.254.169.254/opc/v1/vnics/
Here's an example response:

[ {
"vnicId" : "ocid1.vnic.oc1.sea.abzwkljrg5dtso233awvq7kncmdtfr23dznohdkd2cywjcem3srgi3eg3dxa",
"privateIp" : "10.0.3.6",
"vlanTag" : 11,
"macAddr" : "02:00:17:00:12:D3",
"virtualRouterIp" : "10.0.3.1",
"subnetCidrBlock" : "10.0.3.0/24",
"nicIndex" : 0
}, {
"vnicId" : "ocid1.vnic.oc1.sea.abzwkljrum3czakvqjfzo2dfslcmdyepqc73ntv25ft3rqxsooplb4l2zg7q",
"privateIp" : "10.0.4.3",
"vlanTag" : 12,
"macAddr" : "02:00:17:00:13:13",
"virtualRouterIp" : "10.0.4.1",
"subnetCidrBlock" : "10.0.4.0/24",
"nicIndex" : 0
} ]

Required IAM Policy

Using the Console
To view an instance's VNICs

1. Confirm you're viewing the compartment that contains the instance you're interested in.
2. Click Compute, and then click Instances.
3. Click the instance to view its details.
4. Click Attached VNICs.
The primary VNIC and any secondary VNICs attached to the instance are displayed. If
the instance has two active physical NICs, the VNICs are grouped by NIC 0 and NIC 1.
To create and attach a secondary VNIC

The primary VNIC and any secondary VNICs attached to the instance are displayed.
5. Click Create VNIC.

6. In the Create VNIC dialog box, you specify which subnet to put the VNIC in (and thus
you must first specify which VCN). By default, the VNIC will be created in the current
compartment, and you'll choose the VCN and subnet from the same compartment. Click
the click here link in the dialog box if you want to enable compartment selection and
choose a VCN or subnet in a different compartment.
Enter the following:
l Name: A friendly name for the secondary VNIC. The name doesn't have to be
unique, and you can change it later. Avoid entering confidential information.
l Virtual Cloud Network Compartment: The compartment that contains the
VCN that in turn contains the subnet of interest.
l Virtual Cloud Network: The VCN that contains the subnet of interest.
l Subnet Compartment: The compartment that contains the subnet of interest.
l Subnet: The subnet of interest. The list includes only the subnets in the same
availability domain as the primary VNIC's subnet.
l Physical NIC: Only relevant if this is a bare metal instance with two active
physical NICs. Select which one you want the secondary VNIC to use. When you
later view the instance's details and the list of VNICs attached to the instance,
they'll be grouped by NIC 0 and NIC 1.
l Skip Source/Destination Check: By default, this checkbox is NOT checked,
which means the VNIC performs the source/destination check. Only check this
checkbox if you want the VNIC to be able to forward traffic. See
Source/Destination Check.
assigned).
l Assign public IP address: Whether to assign an ephemeral public IP address to
the VNIC's primary private IP. Available only if the subnet is public. For more
information, see Public IP Addresses.

7. Click Create VNIC.
The secondary VNIC is created and then displayed on the Attached VNICs page for the
instance. It can take several seconds before the secondary VNIC appears on the page.
8. Configure the OS to use the VNIC. See Linux: Configuring the OS for Secondary VNICs .
To update an existing VNIC

You can update the VNIC's friendly name or hostname, or whether the VNIC performs the
source/destination check.
5. For the VNIC you want to edit, click the Actions icon ( ), and then click Edit VNIC.
6. Make your changes and click Update VNIC.
To delete a secondary VNIC
Warning
If the VNIC has a private IP that is the target of a route

rule, deleting the VNIC causes the route rule to
blackhole and traffic will be dropped.

5. For the VNIC you want to delete, click the Actions icon ( ), and then click Delete.
It takes typically a few seconds before the VNIC is deleted.
If you then run the provided script in Linux: Configuring the OS for Secondary VNICs , it
removes the secondary VNIC from the OS configuration.
Using the API

To manage VNICs on an instance, use these operations:
l ListVnicAttachments: Use this to list the VNICs attached to an instance.

l GetVnicAttachment: Use this to get the VNIC's VLAN tag and other properties.
l GetVnic: Use this to get the VNIC's private IP address, MAC address, optional public IP
address, optional DNS hostname, and other properties.
l AttachVnic
l DetachVnic
l UpdateVnic
Linux: Configuring the OS for Secondary VNICs

This section gives details about OS configuration that is required for secondary VNICs on
instances that run a variant of Linux.

At the end is a script that you can use to configure secondary VNICs on either VM instances or
bare metal instances.
Linux VM Instances
When you add a secondary VNIC to a Linux VM instance, a new interface (that is, an Ethernet
device) is added to the instance and automatically recognized by the OS. However, DHCP is
not active for the secondary VNIC, and you must configure the interface with the static IP
address and default route. The script provided here handles that configuration for you.
Linux Bare Metal Instances
When you add a secondary VNIC to a Linux bare metal instance, the OS does not
automatically recognize the secondary VNIC, so you must configure it in the OS. Depending on
your requirements, you can configure it as either:
l An SR-IOV virtual function (see Installing and Configuring KVM on Bare Metal Instances
with Multi-VNIC).
l A VLAN-tagged interface (see the script in the following section).
Configuration Script for Either Linux VM Instances or Linux Bare Metal Instances
The following script works for both VM instances and bare metal instances. It looks at the
secondary VNIC information in the instance metadata and configures the OS accordingly. You
could run the script periodically to bring the OS configuration up to date with the instance
metadata.
For VM instances in particular, the OS automatically recognizes the secondary VNIC's

interface, and the script just needs to configure the static IP address and default route.
For bare metal instances in particular, the script creates the interface for the secondary VNIC
and configures it with the relevant information. If the instance has two active physical NICs
(an X7/second-generation shape with NIC 0 and NIC 1), the script configures the secondary
VNIC to use whichever physical NIC you chose when you added the VNIC to the instance. Note
that for NIC 1, if a secondary VNIC has VLAN tag 0, it uses the NIC's interface. The script
doesn't create an interface for that secondary VNIC.

Here are some additional notes about how the script works for both VM instances and bare
metal instances:
l Default namespace and policy-based routing: By default, this script configures the
secondary VNIC in the default namespace and with policy-based routing so applications
can communicate through the VNIC with hosts outside the VNIC's subnet. This policy-
based routing has effect only if the packets are sourced from the IP address
of the secondary VNIC. The ability to bind to a specific source IP address or source
interface exists in most tools (such as ssh, ping, and wget) and libraries that initiate
connections. For example, the ssh -b option lets you bind to the private IP address of
the secondary VNIC:
ssh -b <secondary_VNIC_IP_address> <destination_IP_address>
Be aware that if traffic comes in to a service on the instance through a secondary

VNIC's interface and the service replies, the reply packets automatically have the
VNIC's interface IP address as the source IP address. Policy-based routing is required
for that reply to go back out on the same interface and find the correct default gateway.
l A separate namespace: If you're familiar with namespaces, you can instead
configure the secondary VNIC in another namespace of your choice by running the script
with the -n option. A separate namespace is required when an instance has secondary
VNICs that are attached to subnets in different VCNs, and those subnets have
overlapping CIDR blocks.
l Secondary private IPs: The instance metadata does not include information about
any secondary private IPs assigned to the instance. To include that as part of the
script's OS configuration, you must provide the secondary private IP address and OCID
at the command line when you run the script.
l Removal of a secondary VNIC: After deleting a secondary VNIC from an instance,
running the script removes the VNIC's information from the OS configuration.

Important
The script uses a simple configuration process that does

not persist if you reboot the instance. If you use the
script, make sure to rerun it after each reboot.
Here are basic examples of how to run the script:
l <script_name> -c: Configure (adds or deletes) secondary VNIC host IP configuration

l <script_name> -c -n: Same but uses separate namespaces
l <script_name> -d: Force removes all secondary VNIC host IP configuration
See the script's help for more information.
Tip
Download the script from the online version of this user

guide at https://docs.us-phoenix-
1.oraclecloud.com/Content/Network/Tasks/managingV
NICs.htm#linux.
Private IP Addresses
This topic describes how to manage the IP addresses assigned to an instance in a virtual cloud
network (VCN).
Overview of IP Addresses
Instances use IP addresses for communication. Each instance has at least one private IP
address and at least one optional public IP address. A private IP address enables the instance
to communicate with other instances inside the VCN, or with hosts in your on-premises
network (via an IPSec VPN or Oracle Cloud Infrastructure FastConnect). A public IP address

enables the instance to communicate with hosts on the internet. For more information, see
these related topics:
l Public vs. Private Subnets

l How IP Addresses Are Assigned
l Public IP Addresses
About the Private IP Object
The Networking service defines an object called a private IP, which consists of:
l Private IPv4 address, assigned by either you or Oracle.

l Optional hostname for DNS (see DNS in Your Virtual Cloud Network).
Each private IP object has an Oracle-assigned OCID (see Resource Identifiers). If you're using
the API, you can also assign each private IP object a friendly name.
Each instance receives a primary private IP object during launch. The primary private IP
cannot be removed from the instance. It's automatically terminated when the instance is
terminated.
If an instance has any secondary VNICs attached, each of those VNICs also has a primary
private IP.
A private IP can have a public IP assigned to it at your discretion.
A private IP can be the target of a route rule in your VCN. For more information, see Using a
Private IP as a Route Target.
About Secondary Private IP Addresses
You can add a secondary private IP to an instance after it's launched. You can add it to either
the primary VNIC or a secondary VNIC on the instance. The secondary private IP address
must come from the CIDR of the VNIC's subnet. You can move a secondary private IP from a
VNIC on one instance to a VNIC on another instance if both VNICs belong to the same subnet.

Here are a few reasons why you might use secondary private IPs:
l Instance failover: You assign a secondary private IP to an instance. Then if the

instance has problems, you can easily reassign that secondary private IP to a standby
instance in the same subnet. If the secondary private IP has a public IP assigned to it,
that public IP moves along with the private IP.
l Run multiple services or endpoints on a single instance: For example, you could
have multiple container pods running on a single instance, and each uses an IP address
from the VCN's CIDR. The containers have direct connectivity to other instances and
services in the VCN. Another example: you could run multiple SSL websites with each
one using its own IP address.
Here are more details about secondary private IP addresses:
l They're supported for all shapes and OS types, for both bare metal and VM instances.
l A VNIC can have a maximum of 31 secondary private IPs.
l They can be assigned only after the instance is launched (or the secondary VNIC is
created/attached).
l Unassigning a secondary IP from a VNIC returns the address to the pool of available
addresses in the subnet.
l They are automatically unassigned when you terminate the instance (or detach/delete
the secondary VNIC).
l The instance's bandwidth is fixed regardless of the number of private IP addresses
attached. You can't specify a bandwidth limit for a particular IP address on an instance.
l A secondary private IP can have a reserved public IP assigned to it at your discretion.
Required IAM Policy


Tagging Resources
Using the Console
To view an instance's private IPs

The primary VNIC and any secondary VNICs assigned to the instance are displayed.
5. Click the VNIC you're interested in.
The primary private IP and any secondary private IPs assigned to the VNIC are displayed.
To assign a new secondary private IP to a VNIC

4. Click Attached VNICs, and then click the VNIC you're interested in.
5. Click Assign IP Address.

l IP Address: Optional. An available private IP address of your choice from the

subnet's CIDR (otherwise the private IP address is automatically assigned).
l Unassign if already assigned to another VNIC: Check this checkbox to force
reassignment of the IP address if it's already assigned to another VNIC in the
subnet. Relevant only if you specify a private IP address in the preceding field.
Available only if the VCN and subnet both have DNS labels. See DNS in Your
Virtual Cloud Network.
administrator.
7. Click Assign.
The secondary private IP is created and then displayed on the IP Addresses page for
the VNIC.
8. Configure the IP address:
l For instances running a variant of Linux, see Linux: Details about Secondary IP
Addresses.
l For Windows instances, see Windows: Details about Secondary IP Addresses.
To move a secondary private IP to another VNIC in the same subnet

4. Click Attached VNICs, and then click the VNIC you want to move the secondary
private IP to.

5. Click Assign IP Address.

6. Enter the following
l IP Address: The secondary private IP address you want to move.
l Unassign if already assigned to another VNIC: Check this checkbox to move
the secondary IP address from the VNIC it's currently assigned to.
l Hostname: Optional. The hostname to be used for DNS within the cloud network.
Available only if the VCN and subnet both have DNS labels. See DNS in Your
administrator.
7. Click Assign.
The private IP address is moved from the original VNIC to the new VNIC.
To update the hostname for an existing private IP

5. For the IP address you're interested in, click the Actions icon ( ), and then click Edit
IP Address.
6. Make your changes and click Update IP Address.

To unassign a secondary private IP from a VNIC
Warning
If the private IP is the target of a route rule,

unassigning it from the VNIC causes the route rule to
blackhole and the traffic will be dropped.
Prerequisite: Oracle recommends removing the IP address from the OS configuration before
deleting it from the Networking. See Linux: Details about Secondary IP Addresses or
Windows: Details about Secondary IP Addresses.
5. For the IP address you want to unassign, click the Actions icon ( ), and then click
Unassign.
The private IP address is returned to the pool of available addresses in the subnet.
To manage tags for a private IP

5. For the private IP you're interested in, click the Actions icon ( ), and then click View
Tags. From there you can view the existing tags, edit them, and apply new ones.

Using the API

To manage private IPs on a VNIC, use these operations:
l GetPrivateIp: Use this to get a single privateIp object by specifying its OCID.
l ListPrivateIps: Use this to get a single privateIp object by specifying the private IP
address (for example, 10.0.3.3) and the subnet's OCID. Or you can list all the
privateIp objects in a given subnet, or just the ones assigned to a given VNIC.
l CreatePrivateIp: Use this to assign a new secondary private IP to a VNIC.
l UpdatePrivateIp: Use this to reassign a secondary private IP to a different VNIC in the
same subnet, or to update the hostname or display name of a secondary private IP.
l DeletePrivateIp: Use this to remove a secondary private IP from a VNIC. The private IP
address is returned to the subnet's pool of available addresses.
Linux: Details about Secondary IP Addresses

After assigning a secondary private IP to a VNIC, you must configure the OS to use it.
Basic Commands (Not Persistent Through a Reboot)
On the instance, run the following command. It works on all variants of Linux, for both bare
metal and VM instances:
ip addr add <address>/<subnet_prefix_len> dev <phys_dev> label <phys_dev>:<addr_seq_num>

where:
l <address>: The secondary private IP address.

l <subnet_prefix_len>: The subnet's prefix length. For example, if the subnet is
192.168.20.0/24, the subnet prefix length is 24.
l <phys_dev>: The interface to add the address to (for example, ens2f0).
l <addr_seq_num>: The sequential number in the stack of addresses on the device (for
example, 0).
For example:
ip addr add 192.168.20.50/24 dev ens2f0 label ens2f0:0
Later if you want to delete the address, you can use:

ip addr del 192.168.20.50/24 dev ens2f0:0
Also make sure to unassign the secondary IP from the VNIC. You can do that before or after
executing the above command to delete the address from the OS configuration.
Note
If you've assigned a secondary IP to a secondary VNIC,

and you're using policy-based routing for the secondary
VNIC, make sure to configure the route rules to look up
the same route table for the secondary IP address.
Configuration File (Persistent Through a Reboot)
You can make the configuration persistent through a reboot by adding the information to a
configuration file.
For Oracle Linux and CentOS

Create an ifcfg file named /etc/sysconfig/network-scripts/ifcfg-<phys_dev>:<addr_

seq_num>. To continue with the preceding example, the file name would be
/etc/sysconfig/network-scripts/ifcfg-ens2f0:0, and the contents would be:
DEVICE="ens2f0:0"
BOOTPROTO=static
IPADDR=192.168.20.50
NETMASK=255.255.255.0
ONBOOT=yes
Note

For Ubuntu
Add the following information to the end of the /etc/network/interfaces file:
auto <phys_dev>:<addr_seq_num>
iface <phys_dev>:<addr_seq_num> inet static
address <address>
netmask <address_netmask>
Where the netmask is not the prefix but the 255.255.x.x. address.
To continue with the earlier example:

auto ens2f0:0
iface ens2f0:0 inet static
address 192.168.20.50
netmask 255.255.255.0

Note

Windows: Details about Secondary IP Addresses

After assigning a secondary private IP to a VNIC, you must configure the OS to use it. Here
are instructions for using a PowerShell script or the Network and Sharing Center UI.
Using a PowerShell Script

You must run PowerShell as an administrator. The script configures two things: static IP
addressing on the instance and the secondary private IP. The configuration persists through a
reboot of the instance.
1. In your browser, go to the Console, and note the secondary private IP address that you
want to configure on the instance.
2. Connect to the instance, and run the following command at a command prompt:
ipconfig /all
3. Note the values for the following items so you can enter them into the script in the next
step:
l Default Gateway
l DNS Servers
4. Replace the variables in the following PowerShell script with your own values:
netadapter = Get-NetAdapter -Name Ethernet
$netadapter | Set-NetIPInterface -DHCP Disabled
$netadapter | New-NetIPAddress -AddressFamily IPv4 -IPAddress <secondary_IP_address> -

PrefixLength <subnet_prefix_length> -Type Unicast -DefaultGateway <default_gateway>

Set-DnsClientServerAddress -InterfaceAlias Ethernet -ServerAddresses <DNS_server>
For example:
netadapter = Get-NetAdapter -Name Ethernet
$netadapter | Set-NetIPInterface -DHCP Disabled
$netadapter | New-NetIPAddress -AddressFamily IPv4 -IPAddress 192.168.11.14 -PrefixLength 24 -
Type Unicast -DefaultGateway 192.168.11.1
Set-DnsClientServerAddress -InterfaceAlias Ethernet -ServerAddresses 169.254.169.254
5. Save the script with the name of your choice and a .ps1 extension, and run it on the
instance.
If you run ipconfig /all again, you'll see that DHCP has been disabled and the
secondary private IP address is included in the list of IP addresses.
Later if you want to delete the address, you can use this command:
Remove-NetIPAddress -IPAddress 192.168.11.14 -InterfaceAlias Ethernet

Also make sure to unassign the secondary IP from the VNIC. You can do that before or after
executing the above command to delete the address from the OS configuration.
Using the Network and Sharing Center UI

The following instructions configure two things: static IP addressing on the instance and the
secondary private IP. The configuration persists through a reboot of the instance.
1. In your browser, go to the Console, and note the secondary private IP address that you
want to configure on the instance.
2. Connect to the instance, and run the following command at a command prompt:
ipconfig /all
3. Note the values for the following items so you can enter them elsewhere in a later step:

l IPv4 Address
l Subnet Mask
l Default Gateway
l DNS Servers
4. In the instance's Control Panel, open the Network and Sharing Center (see the
image below for the set of dialog boxes you'll see in these steps).
5. For the active networks, click the connection (Ethernet).
6. Click Properties.
7. Click Internet Protocol Version 4 (TCP/IPv4), and then click Properties.
8. Select the radio button for Use the following IP address, and then enter the values
you noted earlier for the IP address, subnet mask, default gateway, and DNS servers.

9. Click Advanced....
10. Under IP addresses, click Add....

11. Enter the secondary private IP address and the subnet mask you used earlier and click
Add.
12. Click OK until the Network and Sharing Center is closed.

13. Verify the changes by returning to the command prompt and running ipconfig /all.

You should now see that DHCP is disabled (static IP addressing is enabled), and the
secondary private IP address is in the list of addresses displayed. The address is now
configured on the instance and available to use.
Note
You might not see the primary private IP address

when you again view the properties for Internet
Protocol Version 4 (TCP/IPv4) in the Network and
Sharing Center UI. The best way to confirm your
changes is to use ipconfig /all at the command
line.

Public IP Addresses
This topic describes how to manage public IP addresses on instances in a virtual cloud
network (VCN).
Overview of Public IP Addresses

A public IP address is an IPv4 address that is reachable from the internet. You can assign a
public IP address to a resource (such as an instance) to enable communication with the
internet. The resource is assigned a public IP address from the Oracle Cloud Infrastructure
address pool.
The assignment is actually to a private IP object on the resource. The VNIC that the private IP
is assigned to must be in a public subnet. A given resource can have multiple secondary
VNICs. And a given VNIC can have multiple secondary private IPs. So you can assign a given
resource multiple public IPs across one or more VNICs if you like.
For a public IP address to be reachable over the internet, the VCN it's in must have an internet
gateway, and the public subnet must have route tables and security lists configured
accordingly.
Tip
Oracle Cloud Infrastructure FastConnect public peering

lets your on-premises network access the public IP
addresses of resources in Oracle Cloud Infrastructure
without the traffic traversing the internet. For more
information, see FastConnect Overview.
The Public IP Object
The Networking service defines an object called a public IP, which consists of:

l Public IPv4 address (chosen by Oracle)

l Properties that further define the public IP's type and behavior
Each public IP object has an Oracle-assigned OCID (see Resource Identifiers). If you're using
the API, you can also assign each public IP object a friendly name.
Types of Public IPs
There are two types of public IPs:
l Ephemeral: Think of it as temporary and existing for the lifetime of the instance.
l Reserved: Think of it as persistent and existing beyond the lifetime of the instance it's
assigned to. You can unassign it and then reassign it to another instance whenever you
like.
The following table summarizes the differences between the two types.
Characteristic Ephemeral Public IPs Reserved Public IPs
Allowed To a VNIC's primary private IP only To either a primary or secondary

assignment private IP
Limits:
Limit: 32 per VNIC
l One per VNIC
l Two per VM instance, and 16
per bare metal instance
Creation Optionally created and assigned You create one at any time. You
during instance launch or secondary can then assign it when you like.
VNIC creation. You can create and
Limit: You can create 50 per
assign one later if the VNIC doesn't
region
already have one.

Unassignment You can unassign it at any time, You can unassign it at any time,
which deletes it. You might do this if which returns it to your tenancy's
whoever launched the instance pool of reserved public IPs.
included a public IP, but you don't
want the instance to have one.
When you stop an instance, its

ephemeral public IPs remain
assigned to the instance.
Moving to a If assigned to a secondary private If assigned to a secondary private

different IP: If you move the private IP to a IP: If you move the private IP to
resource different VNIC (must be in the same a different VNIC (must be in the
subnet), the ephemeral public IP same subnet), the reserved public
goes with it. IP goes with it.
You cannot move an ephemeral You can move it (unassign and

public IP to a different private IP. then reassign it) at any time to
another private IP in the same
region. Can be in a different VCN
or availability domain.
Automatic Its lifetime is tied to the private IP's Never. Exists until you delete it.
deletion lifetime. Automatically unassigned
and deleted when:
l Its private IP is deleted

l Its VNIC is detached or
terminated
l Its instance is terminated

Scope Availability domain Regional (can be assigned to a

private IP in any availability
domain in the region)
Compartment Same as the private IP's Can be different from the private
and IP's
availability
domain
When you launch an instance in a public subnet, by default, the instance gets a public IP
unless you say otherwise. See To choose whether an ephemeral public IP is assigned when
launching an instance.
After you create a given public IP, you can't change which type it is. For example, if you
launch an instance that is assigned an ephemeral public IP with address 129.146.1.9, you
can't convert the ephemeral public IP to a reserved public IP with address 129.146.1.9.
The preceding table notes the public IPs limits per VNIC and instance. If you try to perform
any operation that assigns or moves a public IP to a VNIC or instance that has already
reached its public IP limit, an error is returned. The operations include:
l Assigning a public IP
l Creating a new secondary VNIC with a public IP
l Moving a private IP with a public IP to another VNIC
l Moving a public IP to another private IP
Required IAM Policy


Ephemeral Public IPs: Using the Console
To choose whether an ephemeral public IP is assigned when launching an

instance
When you launch an instance into a public subnet, there's an Assign public IP address
checkbox in the Launch Instance dialog box. By default, the checkbox is checked, which
means the instance gets an ephemeral public IP.
If you do NOT want an ephemeral public IP assigned, you can either:
l Uncheck the Assign public IP address checkbox

l Delete the ephemeral public IP after instance launch
To assign an ephemeral public IP when creating a secondary VNIC

When you add a secondary VNIC to an instance, you choose whether the primary private IP on
the new VNIC gets an ephemeral public IP. This choice is available only if the secondary VNIC
is in a public subnet.
In the Create VNIC dialog box, there's an Assign public IP address checkbox. By default,
the checkbox is NOT checked, which means the secondary VNIC does not get an ephemeral
public IP. You must check the checkbox.
For instructions, see To create and attach a secondary VNIC.
To assign an ephemeral public IP to an existing primary private IP

Prerequisite: The primary private IP must not have a reserved or ephemeral public IP already
assigned to it. If it does, first delete the ephemeral public IP, or unassign the reserved public
IP.

The VNIC's primary private IP and any secondary private IPs are displayed.
6. For the VNIC's primary private IP, click the Actions icon ( ), and then click Edit.
7. In the Public IP Address section, for Public IP type, select the radio button for
Ephemeral Public IP.
8. In the Ephemeral Public IP Name field, enter an optional friendly name for the
public IP. The name doesn't have to be unique, and you can change it later. Avoid
entering confidential information.
9. Click Update.
To delete an ephemeral public IP from an instance

Deleting an ephemeral public IP automatically unassigns it from its private IP.

7. In the Public IP Address section, for Public IP Type, select the radio button for No
Public IP.
8. Click Update.
To change the display name for an ephemeral public IP

7. In the Public IP Address section, edit the Ephemeral Public IP Name. The name
doesn't have to be unique, and you can change it later. Avoid entering confidential
information.
8. Click Update.
Reserved Public IPs: Using the Console
To view your reserved public IPs

1. Confirm you're viewing the region and compartment you're interested in.
2. Click Networking, and then click Public IPs.
The reserved public IPs in the selected region and compartment are displayed. The status of
each is shown (whether assigned or available). You can click and view a particular reserved

public IP's information. If the reserved public IP is assigned, the information includes links to
the relevant instance and VNIC.
To create a new reserved public IP in your pool

1. Confirm you're viewing the region and compartment where you want to create the
reserved public IP.
3. Click Create Reserved Public IP.
a. Compartment: Leave as is
b. Reserved Public IP Name: An optional friendly name for the reserved public
IP. The name doesn't have to be unique, and you can change it later. Avoid
5. Click Create Reserved Public IP.
The new reserved public IP is created and displayed on the page. You can now assign it to an
existing private IP if you like.
To delete a reserved public IP from your pool

The reserved public IP can be in the "Assigned" state. Deleting a reserved public IP
automatically unassigns it from its private IP.
1. Confirm you're viewing the region and compartment that contains the reserved public
IP.
3. For the reserved public IP you want to delete, click the Actions icon ( ), and then
click Delete.

After a few seconds, the reserved public IP is unassigned (if it was assigned) and deleted from
your pool.
To assign a reserved public IP to a private IP

Prerequisite: The private IP must not have an ephemeral or reserved public IP already
assigned to it. If it does, first delete the ephemeral public IP, or unassign the reserved public
IP.
1. Confirm you're viewing the compartment that contains the instance with the private IP
you're interested in.
6. For the private IP you're interested in, click the Actions icon ( ), and then click Edit.
7. In the Public IP Address section, for Public IP Type, select the radio button for
Reserved Public IP.
l Compartment: The compartment that contains the reserved public IP you want
to assign.
l Reserved Public IP: The reserved public IP you want to assign. You have three
choices:
o Create a new reserved public IP. You may optionally provide a friendly
name for it. The name doesn't have to be unique, and you can change it
later. Avoid entering confidential information.

o Assign a reserved public IP that is currently unassigned.

o Move a reserved public IP from a nother private IP.
9. Click Update.
To unassign a reserved public IP and return it to the pool

1. Confirm you're viewing the compartment that contains the instance with the reserved
public IP you're interested in.
6. For the private IP you're interested in, click the Actions icon ( ), and then click Edit.
7. In the Public IP Address section, for Public IP Type, select the radio button for No
Public IP.
8. Click Update.
The reserved public IP is unassigned and returned to your pool.
To move a reserved public IP from one private IP to another

Let's say you want to move a reserved public IP from private IP 1 to private IP 2. In
summary: Make sure private IP 2 doesn't have a public IP already assigned to it. Then assign
the reserved public IP to private IP 2. It will be automatically unassigned from private IP 1
first. Detailed instructions:
1. Confirm you're viewing the compartment that contains the instance with private IP 2.


6. For private IP 2, click the Actions icon ( ), and then click Edit.
7. If private IP 2 already has a public IP assigned to it:
a. In the Public IP Address section, select the radio button for No Public IP.
b. Click Update.
c. Again for private IP 2, click the Actions icon ( ), and then click Edit.
8. In the Public IP Address section, select the radio button for Reserved Public IP.
l Compartment: The compartment that contains the reserved public IP you want
to assign.
l Reserved Public IP: The reserved public IP you want to assign. It will be moved
from the public IP it's currently assigned to.
10. Click Update.
To change the display name for a reserved public IP

1. Confirm you're viewing the region and compartment that contains the reserved public
IP.
3. For the reserved public IP you want to edit, click the Actions icon ( ), and then click
Edit.
4. Make your changes to the friendly name. The name doesn't have to be unique, and you
can change it later. Avoid entering confidential information.

5. Click Save.
Using the API

To manage public IPs, use these operations:
l GetPublicIp: Use this to get a publicIp object by specifying its OCID.

l GetPublicIpByIpAddress: Use this to get a publicIp object by specifying its public IP
address.
l GetPublicIpByPrivateIpId: Use this to get a publicIp object by specifying the OCID of
the private IP it's assigned to.
l ListPublicIps: Use this to list either your ephemeral or reserved publicIp objects.
l CreatePublicIp: Use this to create a new reserved public IP in your pool.
l UpdatePublicIp: Use this to assign, reassign, or unassign a reserved public IP, or to
update the display name of an ephemeral or reserved public IP.
l DeletePublicIp: Use this to delete an ephemeral public IP from its private IP, or delete a
reserved public IP from your pool. The operation first unassigns the public IP.
DNS in Your Virtual Cloud Network

The Domain Name System (DNS) lets computers use hostnames instead of IP addresses to
communicate with each other.
Choices for DNS in Your VCN

Following are the choices for DNS name resolution for the instances in your cloud network.
You make this choice for each subnet in the cloud network, using DHCP options. This is similar
to how you configure which route table and security lists are associated with each subnet. For
more information, see DHCP Options.

Note
You use the Domain Name Server DHCP option to

specify the DNS Type for the associated subnet. If you
change the option's value, either restart the DHCP client
on the instance or reboot the instance. Otherwise, the
change does not get picked up until the DHCP client
refreshes the lease (within 24 hours).
DEFAULT CHOICE: INTERNET AND VCN RESOLVER
This is an Oracle-provided option that includes two parts:
l Internet Resolver: Lets instances use hostnames that are publicly published on
the internet. The instances do not need to have internet access by way of either an
internet gateway or an IPSec VPN connection (via a DRG).
l VCN Resolver: Lets instances use hostnames (which you can assign) to
communicate with other instances in the VCN. For more information, see About the
DNS Domains and Hostnames.
By default, new VCNs you create use the Internet and VCN Resolver. If you're using the
Networking API, this choice refers to the VcnLocalPlusInternet enum in the
DhcpDnsOption object.
Note
The Internet and VCN Resolver does not let instances

resolve the hostnames of hosts in your on-premises
network connected to your VCN by IPSec VPN
connection. Use your own custom DNS resolver to
enable that.

CUSTOM RESOLVER
Use your own DNS servers (maximum three). They could be DNS servers that are:
l Available through the internet. For example, 216.146.35.35 for Dyn's Internet Guide.
l In your VCN.
l In your on-premises network, which is connected to your VCN by way of an IPSec VPN
connection or FastConnect (through a DRG).
About the DNS Domains and Hostnames

When you initially create a VCN and subnets, you may specify DNS labels for each. The labels,
along with the parent domain of oraclevcn.com form the VCN domain name and subnet
domain name:
l VCN domain name: <VCN DNS label>.oraclevcn.com

l Subnet domain name: <subnet DNS label>.<VCN DNS label>.oraclevcn.com
When you then launch an instance, you may assign a hostname. It's assigned to the VNIC
that's automatically created during instance launch (that is, the primary VNIC). Along with the
subnet domain name, the hostname forms the instance's fully qualified domain name (FQDN):
l Instance FQDN: <hostname>.<subnet DNS label>.<VCN DNS

label>.oraclevcn.com
For example: database1.privatesubnet1.abccorpvcn1.oraclevcn.com.
The FQDN resolves to the instance's private IP address. The Internet and VCN Resolver also
enables reverse DNS lookup, which lets you determine the hostname corresponding to the
private IP address.
If you add a secondary VNIC to the instance, you can specify a hostname. The resulting FQDN
resolves to the VNIC's private IP address (that is, the primary private IP).
If you add a secondary private IP to a VNIC, you can specify a hostname. The resulting FQDN
resolves to that private IP address.

Requirements for DNS Labels and Hostnames
l VCN and subnet labels: Max 15 alphanumeric characters and must start with a letter.
Cannot be changed later.
l Hostnames: Max 63 characters and must be compliant with RFCs 952 and 1123. Can be
changed later.
Important
The Networking service allows hostnames up to 63

characters. However, some older operating systems
enforce shorter hostnames. In Linux, here's how to
determine the maximum allowed hostname length:
getconf HOST_NAME_MAX
If an instance has a hostname longer than the OS-

specific maximum, the instance's FQDN is not
resolvable within the VCN. You can use the Networking
service to update the VNIC and change the hostname to
a shorter value.
Uniqueness:
l VCN DNS label should be unique across your VCNs (not required, but a best practice)
l Subnet DNS labels must be unique within the VCN
l Hostnames must be unique within the subnet
Tip
Don't confuse the DNS label or hostname with the

friendly name you can assign to the object (that is, the
display name), which doesn't have to be unique.

Validation and Generation of the Hostname
If you've set DNS labels for the VCN and subnets, Oracle validates the hostname for DNS
compliance and uniqueness during instance launch. If either of these requirements isn't met,
the launch request fails.
If you don't specify a hostname during instance launch, Oracle tries to use the instance's
display name as the hostname. If the display name does not pass the validation, Oracle
automatically generates a DNS-compliant hostname that's unique across the subnet. You can
see the generated hostname on the instance's page in the Console. In the API, the hostname
is part of the VNIC object.
If you don't provide a hostname or display name during instance launch, Oracle automatically
generates a display name but NOT a hostname. This means the instance won't be resolvable
using the Internet and VCN Resolver.
Note
The Linux OS hostname on the instance is automatically

set to the hostname you set during instance launch (or
the one generated by Oracle). If you change the
hostname directly on the instance, the FQDN of the
instance does not get updated.
If you add a secondary VNIC to an instance, or add a secondary private IP to a VNIC, Oracle
never tries to generate a hostname. Provide a valid hostname if you want the private IP
address to be resolvable using the Internet and VCN Resolver.
DHCP Options for DNS
There are two DHCP options related to DNS in your VCN:
l Domain Name Server: To specify your choice for DNS type (either Internet and VCN
Resolver, or Custom Resolver).

o Default value in the default set of DHCP options: Internet and VCN
Resolver
l Search Domain: To specify a single search domain. When resolving a DNS query, the
OS appends this search domain to the value being queried.
o Default value in the default set of DHCP options: The VCN domain (<VCN
DNS label>.oraclevcn.com), if you specified a DNS label for the VCN during
creation. If you didn't, the default set of DHCP options does not include a Search
Domain option.
The default set of DHCP options that you can associate with all the subnets in the VCN
automatically uses the default values. This means you can simply use the
<hostname>.<subnet DNS label> to communicate with any of the instances in the VCN. If
the VCN uses a set of DHCP options that does not contain a Search Domain option, the
instances must use the entire FQDN to communicate.
How to Enable DNS Hostnames in Your VCN
Only new VCNs created after the release of the Internet and VCN Resolver feature have
automatic access to it. How to enable DNS hostnames for a new VCN depends on which
interface you're using.
If you create a new VCN and subnets with the Console

1. When creating the VCN:
l Check the checkbox for Use DNS Hostnames in this VCN
l Specify a DNS label of your choice for the VCN. If you check the checkbox but
don't specify a DNS label, the Console assumes that you want to use the Internet
and VCN Resolver in your VCN and automatically generates a DNS label for the
VCN. The Console takes the VCN name you provided, removes non-alphanumeric
characters, ensures that the first character is a letter, and truncates the label to
15 characters. The Console displays the result, and if you don't like it, you can

instead enter your own value in the DNS Label field. See Requirements for DNS
Labels and Hostnames.
2. When creating the subnets:
l Again, check the checkbox for Use DNS Hostnames in this Subnet
l Specify a DNS label of your choice for each subnet. If you check the checkbox but
don't specify the DNS label for a given subnet, the Console assumes you want to
use the Internet and VCN Resolver for the subnet and automatically generates a
DNS label for the subnet. The Console takes the subnet name you provided,
removes non-alphanumeric characters, ensures that the first character is a letter,
and truncates the label to 15 characters. The Console displays the result, and if
you don't like it, you can instead enter your own value in the DNS Label field.
See Requirements for DNS Labels and Hostnames.
l Associate any set of DHCP options that has DNS type = Internet and VCN
Resolver. The default set of DHCP options in the VCN uses the Internet and VCN
Resolver by default.
3. When launching instances:
l Specify a hostname (or at least a display name) for each instance. For more
information, see Validation and Generation of the Hostname.
If you don't check the checkbox for Use DNS Hostnames in this VCN when creating the
VCN, you can't set the DNS label for the VCN or subnets, and you can't specify a hostname
during instance launch.

Note
The above procedure assumes you create the VCN and

subnets one at a time in the Console. The Console has a
feature that automatically creates a VCN with subnets
and an internet gateway all at the same time. If you use
that feature to create the VCN and subnets, the Console
automatically generates DNS labels for them.
If you create a new VCN and subnets with the API

1. When creating the VCN:
l Specify a DNS label for the VCN. See Requirements for DNS Labels and
Hostnames. If you don't set a value (if it's null), Oracle assumes you don't want to
use the Internet and VCN Resolver, even if the DHCP options have DhcpDnsOption
serverType = VcnLocalPlusInternet.
2. When creating the subnets:
l Specify a DNS label for each subnet. See Requirements for DNS Labels and
Hostnames. If you specified a DNS label for the VCN, but you don't specify a DNS
label for the subnet, Oracle assumes you don't want the instances in the subnet to
use the Internet and VCN Resolver. They will not be able to use hostnames to
communicate with instances in the VCN.
l Associate any set of DHCP options that has DhcpDnsOptionserverType =
VcnLocalPlusInternet. The default set of DHCP options in the VCN uses this by
default.
3. When launching instances:
l Specify a hostname (or at least a display name) for each instance. For more
information, see Validation and Generation of the Hostname.

If you don't specify a DNS label when creating the VCN, you can't set the DNS label for the
subnets (the CreateSubnet call will fail), nor specify a hostname during instance launch (the
LaunchInstance call will fail). You also cannot assign a hostname to a secondary VNIC or a
secondary private IP.
Scenario 1: Use Internet and VCN Resolver with DNS Hostnames Across the VCN
The typical scenario is to enable the Internet and VCN Resolver across your entire VCN. This
means all instances in the VCN can communicate with each other without knowing their IP
addresses. To do that, follow the instructions for creating a new VCN in How to Enable DNS
Hostnames in Your VCN, and make sure to assign a DNS label to the VCN and every subnet.
Then make sure to assign every instance a hostname (or at least a display name) at launch. If
you add a secondary VNIC or secondary private IP, also assign it a hostname. The instances
can then communicate with each other using FQDNs instead of IP addresses. If you also set
the Search Domain DHCP option to the VCN domain name (<VCN DNS
label>.oraclevcn.com), the instances can then communicate with each other using just
<hostname>.<subnet DNS label> instead of the FQDN.
Scenario 2: Use Custom DNS Servers to Resolve DNS Hostnames
You can set up an instance to be a custom DNS server within your VCN and configure it to
resolve the hostnames that you set when launching the instances. You must configure the
servers to use 169.254.169.254 as the forwarder for the VCN domain (that is, <VCN DNS
label>.oraclevcn.com).
Note
The custom DNS servers must be located in a subnet

that uses Internet and VCN Resolver for DNS.
For an example of an implementation of this scenario with the Oracle Terraform provider, see
Hybrid DNS Configuration.

Scenario 3: Use Different DHCP Options Per Subnet
Scenario 1 assumes you want to use the Internet and VCN Resolver the same way across all
subnets, and thus all instances in the VCN. You could, however, configure different DNS
settings for each subnet, because the DHCP options are configured at the subnet level. The
important thing to understand is this: The subnet where you want to generate the DNS query
is where you need to configure the corresponding Internet and VCN Resolver settings.
For example, if you want instance A in subnet A to resolve the hostname of instance B in
subnet B, you must configure subnet A to use the Internet and VCN Resolver. Conversely, if
you want instance B to resolve the hostname of instance A, you must configure subnet B to
use the Internet and VCN Resolver.
You can configure a different set of DHCP options for each subnet. For example, you could set
subnet A's Search Domain to subnet-a.vcn-1.oraclevcn.com, which means all instances in
subnet A could use just hostnames to communicate with each other. You could similarly set
subnet B's Search domain to subnet-b.vcn-1.oraclevcn.com to enable Subnet B's instances
to communicate with each other with just hostnames. But that means any instances in a given
subnet would need to use FQDNs to communicate with instances in other subnets.
Internet Intelligence Overview

Oracle Cloud Infrastructure Internet Intelligence provides internet analytics capabilities with
OCI Market Performance and IP Troubleshooting tools. These features give you insight into
the performance of OCI regions to markets and providers around the globe, for both long-
term strategy and operational troubleshooting.
OCI Market Performance
OCI Market Performance provides interactive visualization tools showing performance metrics
to key global market cities and providers from each OCI region. The OCI Market Performance
page includes aggregated data views for the previous day, seven days, one month, and three
months. This data is based on latency measurements and performance across the public
internet. The data does not contain any information specific to a customer.

IP Troubleshooting
IP Troubleshooting provides network reachability tools that utilize external global vantage
points to help users quickly assess the availability and performance of any externally facing
endpoints. IP Troubleshooting enables operations and support teams the ability to diagnose
performance and availability issues for any endpoint IP address on the internet.

You can access Oracle Cloud Infrastructure using the Console (a browser-based interface).
Instructions for the Console are included in topics throughout this guide. No REST API is
available for the Internet Intelligence service.
top of this page to go to the sign-in page. Enter your tenancy, user name, and your password.
Internet Intelligence Service Components

VANTAGE POINT
Software deployed into an OCI region and availability domain that measures latency and
connectivity to markets and providers, globally.
TRACEROUTE
A diagnostic tool for displaying the route (path) and measuring transit delays of a packet
sent across the internet. Traceroutes provide round-trip times (RTT) to each hop taken on
the path to the target IP address.
PROVIDER
A Network Service Provider (NSP) or Internet service Provider (ISP) that provides
commercial internet access to other organizations.
MARKET
A key global region of commerce that can be identified as a geographic city. Within
markets, Internet Intelligence identifies the main providers delivering internet connectivity.

ASN
Autonomous System Number. ASNs are a collection of IP routing prefixes under the control
of one or more network operators on behalf of a single administrative entity or domain that
presents a common, clearly defined routing policy to the internet.
IP ADDRESS
The numerical label assigned to each device connected to a computer network. Using the IP
Troubleshooting service, you can check the connectivity of public addresses from Oracle
Cloud Infrastructure vantage points around the world.

using.
OCI Market Performance

OCI Market Performance provides users with insight into performance from Oracle Cloud
Infrastructure availability domains (AD) to global markets and the top providers within those
markets. OCI Market Performance allows users to select a single Oracle Cloud Infrastructure
AD or to select multiple ADs to compare performance in a market.

Using the Console
To view performance from OCI region ADs to market cities
1. Open the Console and select Internet Intelligence from the Networking menu.
2. Click Explore Performance.
A map showing latency to key markets appears with your default OCI region AD
selected. Each colored dot represents aggregated latency measurements from the OCI
region AD. The latencies are grouped into several ranges to help you match the latency
requirements of your hosted service. Use the legend at the bottom of the map to
decipher the latency ranges between the colored dots.
To identify performance to a market
Select one or more OCI region ADs from the OCI Region AD list and select one or more
markets from the Market list. The map is updated to show aggregated performance data to
the selected market, colored by latency.
To view performance to the top-ranked providers in the market
Click on a market city on the map. The market city details window appears. To see latencies
to each of the top-ranked providers in detail, click + to expand the window.
Filtering the Displayed Measurements
Filters include:
l Time Range - To view OCI region data for a specific time range, select an option from
the Time Range drop-down list. Days are defined as 12:00:00 AM to 11:59:59 PM UTC.
Options include:
o 1d – Displays data from the previous day.
o 7d – (Default) Displays data from the last seven days.
o 1m – Displays data from the last 30 days.
o 3m – Displays data from the last 90 days.
l OCI Region AD(s) - To view performance from one or more OCI region ADs, select an
OCI Region ADfrom the drop-down list.

l Market(s) - To view performance to one or more markets, select a Market from the
drop-down list.
l Latency Bands – To remove a latency band from the map, uncheck an item in the
Latency Bands filter to remove that category from the map. Check an unchecked item
to return that information to the map. All categories are shown by default.
IP Troubleshooting
IP Troubleshooting performs on-demand tests from a set of global vantage points to a user-
specified IP target. Using traceroute diagnostics launched from OCI's global vantage points,
users can view the availability, latency, network path, and the providers the network packets
traversed from each vantage point.
Tip
The target must be responsive to ICMP pings for this

tool to be fully effective. In the absence of a responsive
endpoint IP address, the availability of the path to the
target is confirmed.
Using the Console
Run a live connectivity and performance test from Oracle Cloud Infrastructure’s global
vantage points to your asset.
To diagnose performance availability issues for an endpoint IP address
1. Open the Console and select Internet Intelligence from the Networking menu.
2. Enter an IP address in the IP Address field and click Run Test.
Once the connectivity test is complete, the following information is displayed:

l Target IP Address Details - This section displays the target IP address and provider,
location, and network routing information.
l Global Connectivity - A map that shows latencies and availability from a set of key
global cities in customer markets. This map is linked to the Traceroute Details chart and
the Summarized Traceroute Paths sunburst diagram. When you select a vantage point
on the map, chart, or diagram, the other tabs align their display with the selection.
Colored dots appear in the Global Connectivity map for each vantage point as test
results arrive. Each colored dot represents the latency measurement from the vantage
point, or indicates no response by the target. Use the legend at the bottom of the map to
understand the difference among the colored dots. The results can be displayed using
the following filters:
o Vantage Point - Select a Vantage Point from the drop-down menu to view a
specific traceroute from a chosen vantage point to the IP address.
o Latency Bands - Uncheck an item in the Latency Bands filter to remove that
category from the map. Check an unchecked item to return that information to the
map. All categories are shown by default.
l Traceroute Details - A chart that breaks down the path traversed from a selected
vantage point to the specific target IP address.
o To view individual traceroutes information, click the Traceroute Details tab.
o To view a specific traceroute from a chosen vantage point to the IP address,
select a Vantage Point from the drop-down menu.
Each hop in the traceroute shows router information (Autonomous System
Number (ASN), location, IP address), and the latency time from the vantage point
to that hop.
o To view additional information about the router, click +.
o The length of the horizontal line is relative to the round trip time (RTT) taken to
reach that hop, providing you with an indication of long latency hops in each path.
l Summarized Traceroute Paths - A summary view of traceroute paths to the target
IP address, identifying the key providers and shared infrastructure in reaching this IP

address.
o To view traceroute paths and top providers, click the Summarized Traceroute
Paths tab. The sunburst diagram provides a combined view of all traceroutes,
where each angular slice represents a router through which one or more of the
traceroutes traveled. The center of the sunburst represents the target IP address
and each outer edge is one of OCI's starting vantage points.
o To see router information, hover your cursor over a slice in the sunburst diagram
to see router information. The most observed providers are displayed in ranking
order along with the percentage of traceroutes traversing the provider. Providers
are color coded to match their usage in the sunburst diagram.
Route Tables
This topic describes how to manage the route tables in a virtual cloud network (VCN).
Working with Route Tables

Your cloud network uses virtual route tables to send traffic out of the VCN (for example, to the
Internet or to your on-premises network). These virtual route tables have rules that look and
act like traditional network route rules you might already be familiar with. Each rule specifies
a destination CIDR block and the target (the next hop) for any traffic that matches that CIDR.

Note
When routing traffic, Oracle uses a subnet's route table

only if the destination IP address is not within the VCN's
CIDR block. No route rules are required in order to
enable traffic within the VCN itself.
If a route table has overlapping rules, Oracle uses the

most specific rule in the table to route the traffic (that
is, the rule with the longest prefix match).
If there is no route rule that matches the network traffic

you intend to route outside the VCN, it will be dropped
(blackholed).
Here are the allowed types of targets for a route rule:
l internet gateway: Use this target with a public subnet that needs access to the internet.
l dynamic routing gateway (DRG): Use this target with any subnet that needs private
access to networks connected to your VCN (for example, over an IPSec VPN or
FastConnect).
l local peering gateway (LPG): Use this target with any subnet that needs access to a
peered VCN in the same region.
l private IP: Use this target with any subnet that needs to route traffic to an instance in
the VCN. For more information, see Using a Private IP as a Route Target.
Each VCN automatically comes with a default route table that has no rules. If you don't specify
otherwise, every subnet uses the VCN's default route table. When you add route rules to your
VCN, you can simply add them to the default table if that suits your needs. However, if you
need both a public subnet and a private subnet (for example, see Scenario C: Public and
Private Subnets with a VPN), you instead create a separate route table for each subnet.
Each subnet in a VCN uses a single route table. When you create the subnet, you specify which
one to use. You can't change which route table a subnet uses after the subnet is created, so

make sure to create the route table before creating the subnet. However, remember that you
can also change a table's rules.
You may optionally assign a friendly name to the route table during creation. It doesn't have
to be unique, and you can change it later. Oracle automatically assigns the route table a
Identifiers.
When adding a route rule to a route table, you provide the destination CIDR block and target
(plus the compartment where the target resides). If you misconfigure a rule (for example,
enter the wrong CIDR block), the network traffic you intended to route will be dropped
(blackholed) if there's no other rule in the table that matches that trafic.
To delete a route table, it must not be associated with a subnet yet. You can't delete a VCN's
default route table.
For information about the maximum number of route tables and route rules, see Service
Limits.
Using a Private IP as a Route Target

If you're not familiar with the definition of a private IP, see Private IP Addresses. In short: a
private IP is an object that contains a private IP address and related properties and has its
own OCID.
General Use Cases
You can use a private IP as the target of a route rule in situations where you want to route a
subnet's traffic to another instance. Here are a few reasons you might do this:
l To implement Network Address Translation (NAT) in the VCN, which enables outbound
internet access for instances that don't have direct internet connectivity.
l To implement a virtual network function (such as a firewall or intrusion detection) that
filters outgoing traffic from instances.
l To manage an overlay network on the VCN, which lets you run container orchestration
workloads.

To implement these use cases, there's more to do than simply route traffic to the instance.
There's also configuration required on the instance itself.
Tip
You can enable high availability of the private IP route

target by using a secondary private IP address. In the
event of a failure, you can move the secondary private
IP from an existing VNIC to another VNIC in the same
subnet. See To move a secondary private IP to another
VNIC in the same subnet (Console instructions) and
UpdatePrivateIp (API instructions).
Requirements for Using a Private IP as a Target
l The private IP must be in the same VCN as the route table.

l The private IP's VNIC must be configured to skip the source/destination check so that
the VNIC can forward traffic. By default, VNICs are configured to perform the check.
For more information, see Source/Destination Check.
l The route rule must specify the OCID of the private IP as the target, and not the IP
address itself. Exception: If you use the Console, you can instead specify the private IP
address itself as the target, and the Console determines and uses the corresponding
OCID in the rule.

Important
A route rule with a private IP target can result in

blackholing in these cases:
o The instance the private IP is assigned to is
stopped or terminated
o The VNIC the private IP is assigned to is
updated to enable the source/destination
check or is deleted
o The private IP is unassigned from the VNIC
When a target private IP is terminated, in the
Console, the route rule displays a note that the
target OCID no longer exists.
For failover: If your target instance is terminated
before you can move the secondary private IP to a
standby, you must update the route rule to use the
OCID of the new target private IP on the standby.
The rule uses the target's OCID and not the private
IP address itself.
General Setup Process
1. Determine which instance will receive and forward the traffic (the NAT instance, for
example).
2. Choose a private IP on the instance (can be on the instance's primary VNIC or a
secondary VNIC). If you want to implement failover, set up a secondary private IP on
one of the VNICs on the instance.
3. Disable the source/destination check on the private IP's VNIC. See Source/Destination
Check.

4. Get the OCID for the private IP. If you're using the Console, you can get either the OCID
or the private IP address itself, along with the name of the private IP's compartment.
5. For the subnet that needs to route traffic to the private IP, view the subnet's route table.
If the table already has a rule with the same destination CIDR but a different target,
delete that rule.
6. Add a route rule with the following:
l Destination CIDR block: If all traffic leaving the subnet needs to go to the
private IP, use 0.0.0.0/0.
l Target type: Private IP.
l Compartment: The compartment of the private IP.
l Target: The OCID of the private IP. If you're using the Console and instead enter
the private IP address itself, the Console determines the corresponding OCID and
uses it as the target for the route rule.
You must configure the instance itself to forward packets. For more information, see NAT
Instance Configuration.
Required IAM Policy

Tagging Resources

Using the Console
To view a cloud network's default route table

3. Click Route Tables.
The default route table is displayed in the list of tables.
To update a route table

You can add, edit, or delete rules.
4. Click the route table you're interested in.
5. Click Edit Route Rules.
6. If you want to create a new route rule, click + Another Route Rule and enter the
following:
l Destination CIDR Block: The destination CIDR block for the traffic. A value of
0.0.0.0/0 means that all non-intra-VCN traffic that is not already covered by other
rules in the route table will go to the target specified in this rule.

l Target Type: See the list of target types in Working with Route Tables. If you
choose a private IP for the target, make sure you've first disabled the
source/destination check on the private IP's VNIC. For more information, see
l Compartment: The compartment where the target is located.
l Target: The target. If the target is a private IP, enter its OCID. Or you can enter
the private IP address itself, in which case the Console determines the
corresponding OCID and uses it as the target for the route rule.
7. If you want to delete an existing route rule, click the X next to the rule.
8. If you wanted to edit an existing rule, make your changes to the rule.
9. Click Save.
To create a route table

to add the route table to. If you've just created the cloud network, you should still be
4. Click Create Route Table.
l Create in Compartment: The compartment where you want to create the route
table, if different from the compartment you're currently working in.
l Name: A friendly name for the route table. The name doesn't have to be unique,
and it cannot be changed later in the Console (but you can change it with the API).
6. Add at least one route rule with the following information:

l Destination CIDR Block: The destination CIDR block for the traffic. A value of
0.0.0.0/0 means that all non-intra-VCN traffic that is not already covered by other
rules in the route table will go to the target specified in this rule.
l Target Type: See the list of target types in Working with Route Tables. If you
choose a private IP for the target, make sure you've first disabled the
source/destination check on the private IP's VNIC. For more information, see
l Compartment: The compartment where the target is located.
l Target: The target. If the target is a private IP, enter its OCID. Or you can enter
the private IP address itself, in which case the Console determines the
corresponding OCID and uses it as the target for the route rule.
7. Tags: Optionally, you can apply tags. If you have permissions to create a resource, you
also have permissions to apply free-form tags to that resource. To apply a defined tag,
you must have permissions to use the tag namespace. For more information about
tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option
(you can apply tags later) or ask your administrator.
The route table is created and then displayed on the Route Tables page in the
compartment you chose. You can now specify this route table when creating a subnet.
To delete a route table

Prerequisite: To delete a route table, it must not be associated with a subnet yet. You can't
delete the default route table in a cloud network.

4. For the route table you want to delete, click the Actions icon ( ), and then click
Terminate.
To manage tags for a route table

4. Click the route table you're interested in.
ones.
Using the API

To manage a VCN's route tables, use these operations:
l ListRouteTables
l GetRouteTable
l UpdateRouteTable
l CreateRouteTable
l DeleteRouteTable

DHCP Options
This topic describes how to manage the Dynamic Host Configuration Protocol (DHCP) options
in a virtual cloud network (VCN).
Working with DHCP Options

Your cloud network uses DHCP options to automatically provide configuration information to
the instances when they boot up. Each cloud network comes with a default set of DHCP options
with an initial value that you can change. If you don't specify otherwise, every subnet will use
the VCN's default set of DHCP options. The following table lists the available DHCP options and
the initial value for each in the default set of DHCP options.
DHCP Initial Value in the Default DHCP Options

Option
Domain DNS Type: Internet and VCN resolver. For more information, see DNS in Your
Name Virtual Cloud Network.
Server
Search This option is present in the default set of DHCP options only if you specify a DNS
Domain label for the VCN during creation. In that case, the option's default value is the
VCN domain name (<VCN DNS label>.oraclevcn.com). For more information,
see About the DNS Domains and Hostnames.
Each subnet in a VCN can have a single set of DHCP options associated with it. That set of
options applies to all instances in the subnet. When you create the subnet, you specify which
set to associate with the subnet. If you don't, the default set of DHCP options for the VCN is
used. You can't change which set of DHCP options is associated with a subnet after the subnet
is created. If you don't want to use the default set, make sure to create your desired set of
DHCP options before creating the subnet. However, remember that you can also change the
values for the options.
When creating a new set of DHCP options, you may optionally assign it a friendly name. It
doesn't have to be unique, and you can change it later. Oracle will automatically assign the set

of options a unique identifier called an Oracle Cloud ID (OCID). For more information, see
Important
Whenever you change the value of one of the DHCP

options, you need to do one of the following for the
change to take effect on existing instances in the
subnets associated with that set of DHCP options: either
restart the DHCP client on the instance, or reboot the
instance.
Make sure to keep the DHCP client running so you can

always access the instance. If you stop the DHCP client
manually or disable NetworkManager (which stops the
DHCP client on Linux instances), the instance can't
renew its DHCP lease and will become inaccessible
when the lease expires (typically within 24 hours). Do
not disable NetworkManager unless you use another
method to ensure renewal of the lease.
Stopping the DHCP client might remove the host route

table when the lease expires. Also, loss of network
connectivity to your iSCSI connections might result in
loss of the boot drive.
You can change the values of an individual DHCP option in a set, but notice that when you
update a single option in a set via the API, the new set of options replaces the entire existing
set.
To delete a set of DHCP options, it must not be associated with a subnet yet. You can't delete a
cloud network's default set of DHCP options.
For information about the maximum number of DHCP options allowed, see Service Limits.

Note
Overwriting hosts and resolv.conf Files
The DHCP options overwrite the hosts and

resolve.conf files on the instance. If you add your own
entries to those files, your changes will be lost if you
don't persist your copy of the files. For example, on
Oracle Linux, you can persist your copy by adding the
following line to /etc/oci-hostname.conf:
PRESERVE_HOSTINFO=2
Required IAM Policy

Tagging Resources

Using the Console
To view a cloud network's set of default DHCP options

3. Click DHCP Options.
4. Click it to view the specific options.
To update an existing set of DHCP options

4. Click the set you're interested in.
5. Click Edit DHCP Options:
l For DNS Type: If want instances in the subnet to resolve internet hostnames and
hostnames of instances in the VCN, select Internet and VCN Resolver. Or to
use a DNS server of your choice, select Custom Resolver and then enter the
server's IP address (three servers maximum). For more information, see DNS in
Your Virtual Cloud Network.
l For Search Domain: If you want instances in the subnet to append a particular
search domain when resolving DNS queries, enter it here. If you set a DNS label
for the VCN during creation, the default search domain in the default set of DHCP
options is the VCN's domain name (that is, <VCN DNS label>.oraclevcn.com).
6. When you're done, click Save DHCP Options.
7. If you have any existing instances in a subnet that uses this set of DHCP options, make
sure to restart the DHCP client on each affected instance, or reboot the instance itself so
that it picks up the new setting.

To create a new set of DHCP options

to add the DHCP options to. If you've just created the cloud network, you should still be
4. Click Create DHCP Options.
l Create in Compartment: The compartment where you want to create the set of
DHCP options, if different from the compartment you're currently working in.
l Name: A friendly name for the set of options. It doesn't have to be unique, and
you can change it later.
l DNS Type: If want instances in the subnet to resolve internet hostnames and
hostnames of instances in the VCN, select Internet and VCN Resolver. Or to
use a DNS server of your choice, select Custom Resolver and then enter the
server's IP address (three servers maximum). For more information, see DNS in
Your Virtual Cloud Network.
l Search Domain: If you want instances in the subnet to append a particular
search domain when resolving DNS queries, enter it here. If you set a DNS label
for the VCN during creation, the default search domain in the default set of DHCP
options is the VCN's domain name (that is, <VCN DNS label>.oraclevcn.com).

administrator.
6. When you're done, click Create DHCP Options.
The set of options is created and then displayed on the DHCP Options page of the
compartment you chose. You can now specify this set of options when creating a new subnet.
To delete a set of DHCP options

Prerequisite: To delete a set of DHCP options, it must not be associated with a subnet yet. You
can't delete the default set of DHCP options in a cloud network.

4. For the set you want to delete, click the Actions icon ( ) and then click Delete.
To manage tags for a set of DHCP options

4. Click the set you're interested in.
ones.

Using the API

To manage a VCN's DHCP options, use these operations:
l ListDhcpOptions
l GetDhcpOptions
l UpdateDhcpOptions
l CreateDhcpOptions
l DeleteDhcpOptions
Connectivity to the Internet

This topic describes how to set up and manage an internet gateway to give your VCN access to
the internet.
Working with Internet Gateways

Before continuing, make sure you've read Internet Access.
You can think of an internet gateway as a router connecting the edge of the cloud network with
the internet. Traffic that originates in your VCN and is destined for a public IP address outside
the VCN goes through the internet gateway.
Tip
When an internet gateway receives traffic from your

VCN destined for a public IP address that is part of
Oracle Cloud Infrastructure (such as Object Storage),
the internet gateway routes the traffic to the destination
without sending the traffic over the internet.

For some simple scenarios that use an internet gateway, see Typical Networking Scenarios.
You create an internet gateway in the context of a specific cloud network. In other words, the
internet gateway is automatically attached to a cloud network. However, you can disable and
re-enable the internet gateway at any time. Compare this with a Dynamic Routing Gateway,
which you create as a standalone object that you then attach to a particular cloud network.
Dynamic Routing Gateways use a different model because they're intended to be modular
building blocks for privately connecting cloud networks to your on-premises network.
For traffic to flow between a subnet and an internet gateway, you must create a route rule
accordingly in the subnet's route table (for example, 0.0.0.0/0 > internet gateway). If the
internet gateway is disabled, that means no traffic will flow to/from the Internet even if
there's a route rule that enables that traffic. For more information, see Route Tables.
internet gateway to reside. If you're not sure which compartment to use, put the internet
gateway in the same compartment as the cloud network. For more information, see Access
Control.
You may optionally assign a friendly name to the internet gateway. It doesn't have to be
unique, and you can change it later. Oracle will automatically assign the internet gateway a
Identifiers.
To delete an internet gateway, it does not have to be disabled, but there must not be a route
table that lists it as a target.
Required IAM Policy


Tagging Resources
Using the Console
To create an internet gateway

1. Create the internet gateway:
a. Confirm you're viewing the compartment that contains the cloud network that you
want to add the internet gateway to. If you've just created the cloud network, you
should still be viewing the same compartment. If you click Networking and then
click Virtual Cloud Networks, you should see the cloud network. For
information about compartments and access control, see Access Control.
b. On the Virtual Cloud Networks page, click the cloud network you're interested
in.
c. Click Internet Gateways.
d. Click Create Internet Gateway.
l Create in Compartment: The compartment where you want to create the
internet gateway, if different from the compartment you're currently
working in.
l Name: A friendly name for the internet gateway. It doesn't have to be
unique, and it cannot be changed later in the Console (but you can change it
with the API).

resource. To apply a defined tag, you must have permissions to use the tag
namespace. For more information about tagging, see Resource Tags. If you
are not sure if you should apply tags, skip this option (you can apply tags
later) or ask your administrator.
f. Click Create.
Your internet gateway is created and displayed on the Internet Gateways page
of the compartment you chose. It's already enabled, but you still need to add a
route rule that allows traffic to flow to the gateway.
2. For any subnet that needs to use the internet gateway, update the subnet's route table:
a. While viewing the VCN's details, click Route Tables.
b. Click the route table of interest to view its details.
d. Click + Another Route Rule.
l Destination CIDR block: 0.0.0.0/0 (which means that all non-intra-VCN
the target specified in this rule)
l Target Type: Internet Gateway
l Compartment: The compartment where the internet gateway is located.
l Target: The internet gateway you just created.
f. Click Save.
An internet gateway is now enabled and working for your cloud network.
To disable/enable an internet gateway

This is available only through the API. If you don't have access to the API and need to disable
or enable an internet gateway, contact Oracle Support. You can also easily delete and
recreate the internet gateway. Just make sure to update any route tables that refer to the

internet gateway.
To delete an internet gateway

Prerequisite: The internet gateway does not have to be disabled, but there must not be a route
table that lists it as a target.
3. Click Internet Gateways.
4. Click Terminate for the internet gateway.
To manage tags for an internet gateway

3. Click Internet Gateways.
4. Click the Actions icon ( ) for the internet gateway, and then click View Tags. From
there you can view the existing tags, edit them, and apply new ones.
Using the API

To manage your internet gateways, use these operations:
l ListInternetGateways
l CreateInternetGateway

l GetInternetGatway
l UpdateInternetGateway: You can disable/enable the gateway or change the gateway's
name.
l DeleteInternetGateway
VCN Peering
VCN peering is the process of connecting multiple virtual cloud networks (VCNs). There are
two types of VCN peering:
l Local VCN peering (within region)

l Remote VCN peering (across regions)
You can use VCN peering to divide your network into multiple VCNs (for example, based on
departments or lines of business), with each VCN having direct, private access to the others.
There's no need for traffic to flow through your on-premises network by way of an IPSec VPN
or Oracle Cloud Infrastructure FastConnect. You can also place shared resources into a single
VCN that all the other VCNs can access privately.
Because remote VCN peering crosses regions, you can use it (for example) to mirror or back
up your databases in one region to another.
Local VCN peering is supported in all Oracle Cloud Infrastructure regions.
Remote VCN peering is supported between these regions:
l Phoenix (PHX) region

l Ashburn (IAD) region
Important Implications of Peering

This section summarizes some access control, security, and performance implications for
peered VCNs. In general, you can control access and traffic between two peered VCNs by
using IAM policies, route tables in each VCN, and security lists in each VCN.

Controlling the Establishment of Peerings
With IAM policies, you can control:
l Who can subscribe your tenancy to another region (required for remote VCN peering).
l Who in your organization has the authority to establish VCN peerings (for example, see
the IAM policies in Setting Up a Local Peering and Setting Up a Remote Peering). Be
aware that deletion of these IAM policies does not affect any existing peerings, only the
ability for future peerings to be created.
l Who can manage route tables and security lists.
Controlling Traffic Flow Over the Connection
Even if a peering connection has been established between your VCN and another, you can
control the packet flow over the connection with route tables in your VCN. For example, you
can restrict traffic to only specific subnets in the other VCN.
Without terminating the peering, you can stop traffic flow to the other VCN by simply
removing route rules that direct traffic from your VCN to the other VCN. You can also
effectively stop the traffic by removing any security list rules that enable ingress or egress
traffic with the other VCN. This doesn't stop traffic flowing over the peering connection, but
stops it at the VNIC level.
For more information about the routing and security lists, see the discussions in these
sections:
Local VCN peering:
l Important Local Peering Concepts

l Task E: Configure the route tables
l Task F: Configure the security lists
Remote VCN peering:
l Important Remote Peering Concepts

l Task E: Configure the route tables

l Task F: Configure the security lists
Controlling the Specific Types of Traffic Allowed
It's important that each VCN administrator ensure that all outbound and inbound traffic with
the other VCN is intended/expected and well defined. In practice, this means implementing
security list rules that explicitly state the types of traffic your VCN can send to the other and
accept from the other.
Important
Your instances running Oracle-provided Linux images or

Windows images also have firewall rules that control
access to the instance. When troubleshooting access to
an instance, make sure both the security lists
associated with the instance's subnet and the instance's
firewall rules are set correctly. For more information,
see Oracle-Provided Images.
If your instance is running Oracle Linux 7, you need to

use firewalld to interact with the iptables rules. For your
reference, here are commands for opening a port (1521
in this example):
port=1521/tcp
In addition to security lists and firewalls, you should evaluate other OS-based configuration on
the instances in your VCN. There could be default configurations that don't apply to your own
VCN's CIDR, but inadvertently apply to the other VCN's CIDR.

Using Default Security List Rules
If your VCN's subnets use the default security list with the default rules it comes with, be
aware that there are two rules that allow ingress traffic from anywhere (that is, 0.0.0.0/0,
and thus the other VCN):
l Stateful ingress rule that allows TCP port 22 (SSH) traffic from 0.0.0.0/0 and any source
port
l Stateful ingress rule that allows ICMP type 3, code 4 traffic from 0.0.0.0/0 and any
source port
Make sure to evaluate these rules and whether you want to keep or update them. As stated
earlier, you should ensure that all inbound or outbound traffic that you permit is
intended/expected and well defined.
Preparing for Performance Impact and Security Risks
In general, you should prepare your VCN for the ways it could be affected by the other VCN.
For example, the load on your VCN or its instances could increase. Or your VCN could
experience a malicious attack directly from or by way of the other VCN.
Regarding performance: If your VCN is providing a service to another, be prepared to scale up

your service to accommodate the demands of the other VCN. This might mean being prepared
to launch additional instances as necessary. Or if you're concerned about high levels of
network traffic coming to your VCN, consider using stateless security list rules to limit the
level of connection tracking your VCN must perform. Stateless security list rules can also help
slow the impact of a denial-of-service (DoS) attack.
Regarding security risks: You can't necessarily control whether the other VCN is connected to
the internet. If it is, be aware that your VCN can be exposed to bounce attacks in which a
malicious host on the internet can send traffic to your VCN but make it look like it's coming
from the VCN you're peered with. To guard against this, as mentioned earlier, use your
security lists to carefully limit the inbound traffic from the other VCN to expected and well-
defined traffic.

Local VCN Peering (Within Region)

This topic is about local VCN peering. In this case, local means that the VCNs reside in the
same region. If the VCNs are in different regions, see Remote VCN Peering (Across Regions).
Overview of Local VCN Peering

Local VCN peering is the process of connecting two VCNs in the same region and tenancy so
that their resources can communicate using private IP addresses without routing the traffic
over the internet or through your on-premises network. Without peering, a given VCN would
need an internet gateway and public IP addresses for the instances that need to communicate
with another VCN.
For more information, see VCN Peering.
Summary of Networking Components for Peering
At a high level, the Networking service components required for a local peering include:
l Two VCNs with non-overlapping CIDRs, in the same region

l A local peering gateway (LPG) on each VCN in the peering relationship.
l A connection between those two LPGs.
l Supporting route rules to enable traffic to flow over the connection, and only to/from
select subnets in the respective VCNs (if desired).
l Supporting security list rules to control the types of traffic allowed to/from the instances
in the subnets that need to communicate with the other VCN.
The following diagram illustrates the components.

Note
A given VCN can use the peered LPGs to reach only

VNICs in the other VCN, and not destinations outside of
the VCNs (such as the internet or your on-premises
network). For example, if VCN-1 in the preceding
diagram were to have an internet gateway, the
instances in VCN-2 could NOT use it to send traffic to
endpoints on the internet. However, be aware that VCN-
2 could receive traffic from the internet by way of VCN-
1. For more information, see Important Implications of
VCN Peering.
Explicit Agreement Required from Both Sides
Peering involves two VCNs that might be owned by the same party or two different ones. The
two parties might both be in your company but in different departments.
Peering between two VCNs requires explicit agreement from both parties in the form of Oracle
Cloud Infrastructure Identity and Access Management policies that each party implements for
their own VCN's compartment.

Important Local Peering Concepts

The following concepts help you understand the basics of VCN peering and how to establish a
local peering.
PEERING
A peering is a single peering relationship between two VCNs. Example: If VCN-1 peers
with three other VCNs, then there are three peerings. The local part of local peering
indicates that the VCNs are in the same region. A given VCN can have a maximum of 10
local peerings at a time.
Warning
The two VCNs in the peering relationship must not

have overlapping CIDRs. However, if VCN-1 is peered
with three other VCNs, those three VCNs can have
overlapping CIDRs with each other. You would set up
the subnets in VCN-1 to have route rules that direct
traffic to the targeted peered VCN.
VCN ADMINISTRATORS
In general, VCN peering can occur only if both of the VCN administrators agree to it. In
practice, this means that the two administrators must:
l Share some basic information with each other.

l Coordinate to set up the required Oracle Cloud Infrastructure Identity and Access
Management policies to enable the peering.
l Configure their VCNs for the peering.
Depending on the situation, a single administrator might be responsible for both VCNs and
the related policies.

For more information about the required policies and VCN configuration, see Setting Up a
Local Peering.
ACCEPTOR AND REQUESTOR
To implement the IAM policies required for peering, the two VCN administrators must
designate one administrator as the requestor and the other as the acceptor. The requestor
must be the one to initiate the request to connect the two LPGs. In turn, the acceptor must
create a particular IAM policy that gives the requestor permission to connect to LPGs in
the acceptor's compartment. Without that policy, the requestor's request to connect fails.
LOCAL PEERING GATEWAY (LPG)

A local peering gateway (LPG) is a component on a VCN for routing traffic to a locally
peered VCN. As part of configuring the VCNs, each administrator must create an LPG for
their VCN. A given VCN must have a separate LPG for each local peering it establishes
(maximum 10 LPGs per VCN). To continue with the previous example: VCN-1 would have
three LPGs to peer with three other VCNs. In the API, a LocalPeeringGateway is an object
that contains information about the peering. You can't reuse an LPG to later establish
another peering with it.
PEERING CONNECTION
When the requestor initiates the request to peer (in the Console or API), they're
effectively asking to connect the two LPGs. This means the requestor must have
information to identify each LPG (such as the LPG's compartment and name).
Either VCN administrator can terminate a peering by deleting their LPG. In that case, the
other LPG's status switches to REVOKED. The administrator could instead render the
connection non-functional by removing the route rules or security lists that enable traffic
to flow across the connection (see the next sections).
ROUTING TO THE LPG
As part of configuring the VCNs, each administrator must update the VCN's routing to
enable traffic to flow between the VCNs. In practice, this looks just like routing you set up
for any gateway (such as an internet gateway or dynamic routing gateway). For each
subnet that needs to communicate with the other VCN, you update the subnet's route

table. The route rule specifies the destination traffic's CIDR and your LPG as the target.
Your LPG routes traffic that matches that rule to the other LPG, which in turn routes the
traffic to the next hop in the other VCN.
In the following diagram, VCN-1 and VCN-2 are peered. Traffic from an instance in Subnet
A (10.0.0.15) that is destined for an instance in VCN-2 (192.168.0.15) is routed to LPG-1
based on the rule in Subnet A's route table. From there the traffic is routed to LPG-2, and
then from there, on to its destination in Subnet X.

Note
As mentioned earlier, a given VCN can use the

peered LPGs to reach only VNICs in the other VCN,

and not destinations outside of the VCNs (such as the

internet or your on-premises network). For example,
in the preceding diagram, VCN-2 cannot use the
internet gateway or dynamic routing gateway (DRG)
attached to VCN-1.
SECURITY LIST RULES
Each subnet in a VCN has one or more security lists that control traffic in and out of the
subnet's VNICs at the packet level. You can use security lists to control the type of traffic
allowed with the other VCN. As part of configuring the VCNs, each administrator must
determine which subnets in their own VCN need to communicate with VNICs in the other
VCN and update their subnet's security lists accordingly.
Important Implications of VCN Peering

If you haven't yet, read Important Implications of Peering to understand important access
control, security, and performance implications for peered VCNs.
Setting Up a Local Peering

Here's the general process for setting up a peering between two VCNs in the same region:
A. Create the LPGs: Each VCN administrator creates an LPG for their own VCN.
B. Share information: The administrators share the basic required information.
C. Set up the required IAM policies for the connection: The administrators set up
IAM policies to enable the connection to be established.
D. Establish the connection: The requestor connects the two LPGs.
E. Update route tables: Each administrator updates their VCN's route tables to enable
traffic between the peered VCNs as desired.
F. Update security lists: Each administrator updates their VCN's security lists to enable

If desired, the administrators can perform tasks E and F before establishing the connection.
Each administrator needs to know the CIDR block or specific subnets from the other's VCN and
share that in task B. Note that after the connection is established, you can also get the CIDR
block of the other VCN by viewing your own LPG's details in the Console. Look for Peer
Advertised CIDR. Or if you're using the API, see the peerAdvertisedCidr parameter.
Task A: Create the LPGs

Each administrator creates an LPG for their own VCN. "You" in the following procedure means
an administrator (either the acceptor or requestor).
Note
Required IAM Policy to Create LPGs
If the administrators already have broad network

administrator permissions (see Let network admins
manage a cloud network), then they have permission to
create, update, and delete LPGs. Otherwise, here's an
example policy giving the necessary permissions to a
group called LPGAdmins. The second statement is
required because creating an LPG affects the VCN it
belongs to, so the administrator must have permission
to manage VCNs.
Allow group LPGAdmins to manage local-peering-gateways in
tenancy
Allow group LPGAdmins to manage vcns in tenancy
1. In the Console, confirm you're viewing the compartment that contains the VCN that you
want to add the LPG to. If you've just created the VCN, you should still be viewing the
same compartment. If you click Networking and then click Virtual Cloud Networks,
you should see the VCN. For information about compartments and access control, see
Access Control.

2. On the Virtual Cloud Networks page, click the VCN you're interested in.
3. Click Create Local Peering Gateway.
l Name: A friendly name for the LPG. It doesn't have to be unique, and it cannot be
changed later in the Console (but you can change it with the API). Avoid entering
l Create in compartment: The compartment where you want to create the LPG,
if different from the compartment you're currently working in.
administrator.
5. Click Create.
The LPG is then created and displayed on the Local Peering Gateways page in the
compartment you chose.
6. If you're the acceptor, record the compartment name, LPG name, and LPG OCID to later
give to the requestor.
Task B: Share information

l If you're the acceptor, give this information to the requestor (for example, by email or
other out-of-band method):
o VCN's name and compartment.
o LPG's name, OCID, and compartment.
l If you're the requestor, give this information to the acceptor:
o Name of the IAM group that should be granted permission to create a connection
in the acceptor's compartment (in the example in the next task, the group is

RequestorGrp).
Task C: Set up the IAM policies

Both the requestor and acceptor must ensure the right policies are in place. These consist of:
l Policy R (implemented by the requestor):

Allow group RequestorGrp to manage local-peering-from in compartment RequestorComp
The requestor is in an IAM group called RequestorGrp. This policy lets anyone in the
group initiate a connection from any LPG in the requestor's compartment
(RequestorComp). Policy R can be attached to either the tenancy (root compartment) or
to RequestorComp. For information about why you would attach it to one versus the
other, see Policy Attachment.
l Policy A (implemented by the acceptor):
Allow group RequestorGrp to manage local-peering-to in compartment AcceptorComp
Allow group RequestorGrp to inspect vcns in compartment AcceptorComp

Allow group RequestorGrp to inspect local-peering-gateways in compartment AcceptorComp
The first statement in the policy lets the requestor connect to any LPG in the acceptor's
compartment (AcceptorComp). This statement reflects the required agreement from the
acceptor for the peering to be established. Policy A can be attached to either the
tenancy (root compartment) or to AcceptorComp.

Tip
The second and third statements in Policy A let the

requestor list the VCNs and LPGs in AcceptorComp.
The statements are required for the requestor to
use the Console UI to select from a list of VCNs and
LPGs in AcceptorComp and establish the connection.
The following diagram focuses only on the first
statement, which is the critical one that permits the
connection.

Both Policy R and Policy A give RequestorGrp access. However, Policy R has a resource-type
called local-peering-from, and Policy A has a resource-type called local-peering-to. Together,
these policies let someone in RequestorGrp establish the connection from an LPG in the
requestor's compartment to an LPG in the acceptor's compartment. The API call to actually
create the connection specifies which two LPGs.
Tip
The permission granted by Policy R might already be in

place if the requestor has permission in another policy
to manage all of the Networking components in
RequesterComp. For example, there might be a general
Network Admin policy like this: Allow group
NetworkAdmin to manage virtual-network-family
in compartment RequestorComp. If the requestor is in
the NetworkAdmin group, then they already have the
required permissions covered in Policy R (the virtual-
network-family includes LPGs). And further, if the policy
is instead written to cover the entire tenancy (Allow
group NetworkAdmin to manage virtual-network-
family in tenancy), then the requestor already has
all the required permissions in both compartments to
establish the connection. In that case, policy A is not
required.
Task D: Establish the connection

The requestor must perform this task.
Prerequisite: The requestor must have:
l The name and compartment of the acceptor's LPG

1. In the Console, view the details for the requestor LPG that you want to connect to the
acceptor LPG.
2. Click Establish Connection.
The resulting dialog box lets you choose the VCN and LPG you want to peer with. They
each might be in a different compartment than the one you're currently working in.
3. Select values for the following:
l Virtual Cloud Network Compartment: The compartment that contains the
VCN you want to peer with.
l Virtual Cloud Network: The VCN you want to peer with.
l Local Peering Gateway Compartment: The compartment that contains the
LPG you want to establish the connection with.
l Unpeered Peer Gateway: The LPG you want to establish the connection with.
4. Click Establish Peering Connection.
The connection is established and the LPG's state changes to PEERED.
At this point, the details of each LPG update to show the Peer VCN CIDR Block for the other
VCN. This is the CIDR of the other VCN across the peering from the LPG. Each administrator
can use this information to update the route tables and security lists for their own VCN.
Task E: Configure the route tables

As mentioned earlier, each administrator can do this task before or after the connection is
established.
Prerequisite: Each administrator must have the CIDR block or specific subnets for the other
VCN. If the connection is already established, look at the Peer VCN CIDR Block for your
LPG in the Console. Otherwise, get the information from the other administrator by email or
other method.
For your own VCN:

1. Determine which subnets in your VCN need to communicate with the other VCN.
2. Update the route table for each of those subnets to include a new rule that directs traffic
destined for the other VCN's CIDR to your LPG:
a. In the Console, click Networking, and then click Virtual Cloud Networks.
b. Click the VCN you're interested in.
c. Click Route Tables.
d. Click the route table you're interested in.
e. Click Edit Route Rules.
f. Click + Another Route Rule and enter the following:
l Destination CIDR Block: The other VCN's CIDR block. If you want, you
can specify a subnet or particular subset of the peered VCN's CIDR.
l Target Type: Local Peering Gateway.
l Target Compartment: The compartment where the LPG is located, if not
the current compartment.
l Target: The LPG.
g. Click Save.
Any subnet traffic with a destination that matches the rule is routed to your LPG. For more
information about setting up route rules, see Route Tables.
Later, if you no longer need the peering and want to delete your LPG, you must first delete all
the route rules in your VCN that specify the LPG as the target.

Tip
Without the required routing, traffic doesn't flow

between the peered LPGs. If a situation occurs where
you need to temporarily stop the peering, you can
simply remove the route rules that enable traffic. You
don't need to delete the LPGs.
Task F: Configure the security lists

established.
VCN. In general, you should use the same CIDR block you used in the route table rule in Task
E: Configure the route tables.
What rules should you add?
l Ingress rules for the types of traffic you want to allow from the other VCN, specifically
from the VCN's CIDR or specific subnets.
l Egress rule to allow outgoing traffic from your VCN to the other VCN. If the subnet
already has a broad egress rule for all types of protocols to all destinations (0.0.0.0/0),
then you don't need to add a special one for the other VCN.
For your own VCN:
2. Update the security list for each of those subnets to include rules to allow the desired
egress or ingress traffic specifically with the CIDR block or subnet of the other VCN:
a. In the Console, while viewing the VCN you're interested in, click Security Lists.
b. Click the security list you're interested in.

c. Click Edit All Rules and create one or more rules, each for the specific type of
traffic you want to allow. See the example that follows for more details.
d. Click Save Security List Rules at the bottom of the dialog box.
Example: Let's say you want to add a stateful rule that enables ingress HTTPS (port 443)
traffic from the other VCN's CIDR. Here are the basic steps you take when adding a rule:
i. In the Allow Rules for Ingress section, click +Add Rule.

ii. Leave the Stateless checkbox unchecked.
iii. Source CIDR: Enter the same CIDR block that the route rules use (see Task E:
Configure the route tables).
iv. IP Protocol: Leave as TCP.
v. Source Port Range: Leave as All.
vi. Destination Port Range: Enter 443.
For more information about setting up security list rules, see Security Lists.
Using the Console
To create a local peering gateway

See the instructions in Task A: Create the LPGs.
To delete a local peering gateway

Prerequisite: You must first delete all the route rules in your VCN that specify the LPG as the
target. Deleting those rules stops the routing in your VCN to the LPG. However, the LPG's state
may still be PEERED if the other LPG still exists. Whenever an LPG is deleted, the LPG at the
other side of the peering changes to the REVOKED state.

3. Click Local Peering Gateways.
4. For the LPG you want to delete, click the Actions icon ( ), and then click Terminate.
Note
After deleting an LPG (and thus terminating a peering),

it's recommended you review your security lists to
remove any rules that enabled traffic with the other
VCN.
To manage tags for a local peering gateway

3. Click Local Peering Gateways.
4. Click the LPG you're interested in.
ones.
Using the API

To manage your LPGs and create connections, use these operations:

l ListLocalPeeringGateways
l CreateLocalPeeringGateway
l GetLocalPeeringGateway
l UpdateLocalPeeringGateway
l DeleteLocalPeeringGateway
l ConnectLocalPeeringGateways
Remote VCN Peering (Across Regions)

This topic is about remote VCN peering. In this case, remote means that the VCNs reside in
different regions. If the VCNs you want to connect are in the same region, see Local VCN
Peering (Within Region).
Overview of Remote VCN Peering

Remote VCN peering is the process of connecting two VCNs in different regions (but the same
tenancy). The peering allows the VCNs' resources to communicate using private IP addresses
without routing the traffic over the internet or through your on-premises network. Without
peering, a given VCN would need an internet gateway and public IP addresses for the
instances that need to communicate with another VCN in a different region.
Remote VCN peering is supported between these regions:
l Phoenix (PHX) region

l Ashburn (IAD) region
Summary of Networking Components for Remote Peering
At a high level, the Networking service components required for a remote peering include:
l Two VCNs with non-overlapping CIDRs, in different regions that support remote
peering.

Note
All VCN CIDRs Must Not Overlap
The two VCNs in the peering relationship must not

have overlapping CIDRs. Also, if a particular VCN
has multiple peering relationships, those other
VCNs must not have overlapping CIDRs with each
other. For example, if VCN-1 is peered with VCN-2
and also VCN-3, then VCN-2 and VCN-3 must not
have overlapping CIDRs.
l A dynamic routing gateway (DRG) attached to each VCN in the peering relationship.
Your VCN already has a DRG if you're using an IPSec VPN or an Oracle Cloud
Infrastructure FastConnect private virtual circuit.
l A remote peering connection (RPC) on each DRG in the peering relationship.
l A connection between those two RPCs.
l Supporting route rules to enable traffic to flow over the connection, and only to/from
select subnets in the respective VCNs (if desired).
l Supporting security list rules to control the types of traffic allowed to/from the instances
in the subnets that need to communicate with the other VCN.
The following diagram illustrates the components.

Note
A given VCN can use the connected RPCs to reach only

VNICs in the other VCN, and not destinations outside of
the VCNs (such as the internet or your on-premises
network). For example, if VCN-1 in the preceding
diagram were to have an internet gateway, the
instances in VCN-2 could NOT use it to send traffic to
endpoints on the internet. However, be aware that VCN-
2 could receive traffic from the internet via VCN-1. For
more information, see Important Implications of
Peering.
Explicit Agreement Required from Both Sides
Peering involves two VCNs that might be owned by the same party or two different ones. The
two parties might both be in your company but in different departments.
Peering between two VCNs requires explicit agreement from both parties in the form of Oracle
Cloud Infrastructure Identity and Access Management policies that each party implements for
their own VCN's compartment.

Important Remote Peering Concepts

The following concepts help you understand the basics of VCN peering and how to establish a
remote peering.
PEERING
A peering is a single peering relationship between two VCNs. Example: If VCN-1 peers
with two other VCNs, then there are two peerings. The remote part of remote peering
indicates that the VCNs are in a different regions.
VCN ADMINISTRATORS
In general, VCN peering can occur only if both of the VCN administrators agree to it. In
practice, this means that the two administrators must:
l Share some basic information with each other.

l Coordinate to set up the required Oracle Cloud Infrastructure Identity and Access
Management policies to enable the peering.
l Configure their VCNs for the peering.
Depending on the situation, a single administrator might be responsible for both VCNs and
the related policies.
For more information about the required policies and VCN configuration, see Setting Up a
Remote Peering.
ACCEPTOR AND REQUESTOR
To implement the IAM policies required for peering, the two VCN administrators must
designate one administrator as the requestor and the other as the acceptor. The requestor
must be the one to initiate the request to connect the two RPCs. In turn, the acceptor must
create a particular IAM policy that gives the requestor permission to connect to RPCs in
the acceptor's compartment. Without that policy, the requestor's request to connect fails.
REGION SUBSCRIPTION
To peer with a VCN in another region, your tenancy must first be subscribed to that
region. For information about subscribing, see Managing Regions.

REMOTE PEERING CONNECTION (RPC)

A remote peering connection (RPC) is a component you create on the DRG attached to
your VCN. The RPC's job is to act as a connection point for a remotely peered VCN. As part
of configuring the VCNs, each administrator must create an RPC for the DRG on their VCN.
A given DRG must have a separate RPC for each remote peering it establishes for the VCN
(maximum 10 RPCs per tenancy). To continue with the previous example: the DRG on
VCN-1 would have two RPCs to peer with two other VCNs. In the API, a
RemotePeeringConnection is an object that contains information about the peering. You
can't reuse an RPC to later establish another peering with it.
CONNECTION BETWEEN TWO RPCS
When the requestor initiates the request to peer (in the Console or API), they're
effectively asking to connect the two RPCs. This means the requestor must have
information to identify each RPC (such as the RPC's region and OCID).
Either VCN administrator can terminate a peering by deleting their RPC. In that case, the
other RPC's status switches to REVOKED. The administrator could instead render the
connection non-functional by removing the route rules or security lists that enable traffic
to flow across the connection (see the next sections).
ROUTING TO THE DRG
As part of configuring the VCNs, each administrator must update the VCN's routing to
enable traffic to flow between the VCNs. For each subnet that needs to communicate with
the other VCN, you update the subnet's route table. The route rule specifies the
destination traffic's CIDR and your DRG as the target. Your DRG routes traffic that
matches that rule to the other DRG, which in turn routes the traffic to the next hop in the
other VCN.
In the following diagram, VCN-1 and VCN-2 are peered. Traffic from an instance in Subnet
A (10.0.0.15) that is destined for an instance in VCN-2 (192.168.0.15) is routed to DRG-1
based on the rule in Subnet A's route table. From there the traffic is routed through the
RPCs to DRG-2, and then from there, on to the destination in Subnet X.

Note
As mentioned earlier, a given VCN can use the

connected RPCs to reach only VNICs in the other
VCN, and not destinations outside of the VCNs (such
as the internet or your on-premises network). For

example, in the preceding diagram, VCN-2 cannot

use the internet gateway attached to VCN-1.
SECURITY LIST RULES
Each subnet in a VCN has one or more security lists that control traffic in and out of the
subnet's VNICs at the packet level. You can use security lists to control the type of traffic
allowed with the other VCN. As part of configuring the VCNs, each administrator must
determine which subnets in their own VCN need to communicate with VNICs in the other
VCN and update their subnet's security lists accordingly.
Important Implications of Peering

If you haven't yet, read Important Implications of Peering to understand important access
control, security, and performance implications for peered VCNs.
Setting Up a Remote Peering

This section covers the general process for setting up a peering between two VCNs in different
regions.
Important
The following procedure assumes that:
l Your tenancy is subscribed to the other VCN's

region. If it's not, see Managing Regions.
l You already have a DRG attached to your VCN. If
you don't, see Dynamic Routing Gateways
(DRGs).

A. Create the RPCs: Each VCN administrator creates an RPC for their own VCN's DRG.
B. Share information: The administrators share the basic required information.
C. Set up the required IAM policies for the connection: The administrators set up
IAM policies to enable the connection to be established.
D. Establish the connection: The requestor connects the two RPCs.
E. Update route tables: Each administrator updates their VCN's route tables to enable
F. Update security lists: Each administrator updates their VCN's security lists to enable
If desired, the administrators can perform tasks E and F before establishing the connection.
Each administrator needs to know the CIDR block or specific subnets from the other's VCN and
share that in task B.
Task A: Create the RPCs

Each administrator creates an RPC for their own VCN's DRG. "You" in the following procedure
means an administrator (either the acceptor or requestor).

Note
Required IAM Policy to Create RPCs
If the administrators already have broad network

administrator permissions (see Let network admins
manage a cloud network), then they have permission to
create, update, and delete RPCs. Otherwise, here's an
example policy giving the necessary permissions to a
group called RPCAdmins. The second statement is
required because creating an RPC affects the DRG it
belongs to, so the administrator must have permission
to manage DRGs.
Allow group RPCAdmins to manage remote-peering-connections in
tenancy
Allow group RPCAdmins to manage drgs in tenancy
1. In the Console, confirm you're viewing the compartment that contains the DRG that you
want to add the RPC to. If you've just created the DRG, you should still be viewing the
same compartment. If you click Networking and then click Dynamic Routing
Gateways, you should see the DRG. For information about compartments and access
control, see Access Control.
2. On the Dynamic Routing Gateways page, click the DRG you're interested in.
3. Click Remote Peering Connections.
4. Click Create Remote Peering Connection.
l Name: A friendly name for the RPC. It doesn't have to be unique, and it cannot be
changed later in the Console (but you can change it with the API). Avoid entering
l Create in compartment: The compartment where you want to create the RPC,

6. Click Create Remote Peering Connection.

The RPC is then created and displayed on the Remote Peering Connections page in
the compartment you chose.
7. If you're the acceptor, record the RPC's region and OCID to later give to the requestor.
Task B: Share information

l If you're the acceptor, give this information to the requestor (for example, by email or
other out-of-band method):
o The region your VCN is in (the requestor's tenancy must be subscribed to this
region).
o Your RPC's OCID.
o The CIDR blocks for subnets in your VCN that should be available to the other
VCN. The requestor needs this information when setting up routing for the
requestor VCN.
l If you're the requestor, give this information to the acceptor:
o The region your VCN is in (the acceptor's tenancy must be subscribed to this
region).
o The name of the IAM group that should be granted permission to create a
connection in the acceptor's compartment (in the example in the next task, the
group is RequestorGrp).
o The CIDR blocks for subnets in your VCN that should be available to the other
VCN. The acceptor needs this information when setting up routing for the acceptor
VCN.
Task C: Set up the IAM policies

Both the requestor and acceptor must ensure the right policies are in place. These consist of:

l Policy R (implemented by the requestor):

Allow group RequestorGrp to manage remote-peering-from in compartment RequestorComp
The requestor is in an IAM group called RequestorGrp. This policy lets anyone in the
group initiate a connection from any RPC in the requestor's compartment
(RequestorComp). Policy R can be attached to either the tenancy (root compartment) or
to RequestorComp. For information about why you would attach it to one versus the
other, see Policy Attachment.
l Policy A (implemented by the acceptor):
Allow group RequestorGrp to manage remote-peering-to in compartment AcceptorComp
This policy lets the requestor connect to any RPC in the acceptor's compartment
(AcceptorComp). This statement reflects the required agreement from the acceptor for
the peering to be established. Policy A can be attached to either the tenancy (root
compartment) or to AcceptorComp.

Both Policy R and Policy A give RequestorGrp access. However, Policy R has a resource-type
called remote-peering-from, and Policy A has a resource-type called remote-peering-to.
Together, these policies let someone in RequestorGrp establish the connection from an RPC in
the requestor's compartment to an RPC in the acceptor's compartment. The API call to
actually create the connection specifies which two RPCs.
Tip
The permission granted by Policy R might already be in

place if the requestor has permission in another policy
to manage all of the Networking components in
RequesterComp. For example, there might be a general
Network Admin policy like this: Allow group
NetworkAdmin to manage virtual-network-family
in compartment RequestorComp. If the requestor is in
the NetworkAdmin group, then they already have the
required permissions covered in Policy R (the virtual-
network-family includes RPCs). And further, if the policy
is instead written to cover the entire tenancy (Allow
group NetworkAdmin to manage virtual-network-
family in tenancy), then the requestor already has
all the required permissions in both compartments to
establish the connection. In that case, policy A is not
required.
Task D: Establish the connection

The requestor must perform this task.
Prerequisite: The requestor must have:

l The region the acceptor's VCN is in (the requestor's tenancy must be subscribed to the
region).
l The OCID of the acceptor's RPC.
1. In the Console, view the details for the requestor RPC that you want to connect to the
acceptor RPC.
l Region: The region that contains the acceptor's VCN. The drop-down list includes
only those regions that both support remote VCN peering and your tenancy is
subscribed to.
l Remote Peering Connection ID: The OCID of the acceptor's RPC.
The connection is established and the RPC's state changes to PEERED.
Task E: Configure the route tables

established.
VCN.
For your own VCN:
2. Update the route table for each of those subnets to include a new rule that directs traffic
destined for the other VCN to your DRG:
a. In the Console, click Networking, and then click Virtual Cloud Networks.
b. Click the VCN you're interested in.

c. Click Route Tables.

d. Click the route table you're interested in.
e. Click Edit Route Rules.
f. Click + Another Route Rule and enter the following:
l Destination CIDR Block: The other VCN's CIDR block. If you want, you
can specify a subnet or particular subset of the peered VCN's CIDR.
l Compartment: The compartment where the DRG is located.
l Target: The DRG.
g. Click Save.
Any subnet traffic with a destination that matches the rule is routed to your DRG. For more
information about setting up route rules, see Route Tables.
Tip
Without the required routing, traffic doesn't flow

between the peered DRGs. If a situation occurs where
you need to temporarily stop the peering, you can
simply remove the route rules that enable traffic. You
don't need to delete the RPCs.
Task F: Configure the security lists

established.
VCN. In general, you should use the same CIDR block you used in the route table rule in Task
E: Configure the route tables.

What rules should you add?
l Ingress rules for the types of traffic you want to allow from the other VCN, specifically
from the VCN's CIDR or specific subnets.
l Egress rule to allow outgoing traffic from your VCN to the other VCN. If the subnet
already has a broad egress rule for all types of protocols to all destinations (0.0.0.0/0),
then you don't need to add a special one for the other VCN.
For your own VCN:
2. Update the security list for each of those subnets to include rules to allow the desired
egress or ingress traffic specifically with the CIDR block or subnet of the other VCN:
a. In the Console, while viewing the VCN you're interested in, click Security Lists.
b. Click the security list you're interested in.
c. Click Edit All Rules and create one or more rules, each for the specific type of
traffic you want to allow. See the example that follows for more details.
d. Click Save Security List Rules at the bottom of the dialog box.
Example: Let's say you want to add a stateful rule that enables ingress HTTPS (port 443)
traffic from the other VCN's CIDR. Here are the basic steps you take when adding a rule:
i. In the Allow Rules for Ingress section, click +Add Rule.

ii. Leave the Stateless checkbox unchecked.
iii. Source CIDR: Enter the same CIDR block that the route rules use (see Task E:
Configure the route tables).
iv. IP Protocol: Leave as TCP.
v. Source Port Range: Leave as All.
vi. Destination Port Range: Enter 443.
For more information about setting up security list rules, see Security Lists.

Using the Console
To create a remote peering connection

See the instructions in Task A: Create the RPCs.
To delete a remote peering connection

Deleting an RPC terminates the peering. The RPC at the other side of the peering changes to
the REVOKED state.
1. In the Console, click Networking, and then click Dynamic Routing Gateways.
2. Click the DRG you're interested in.
3. Click Remote Peering Connections.
4. For the RPC you want to delete, click the Actions icon ( ), and then click Terminate.
Note
After deleting an RPC (and thus terminating a peering),

it's recommended you review your route tables and
security lists to remove any rules that enabled traffic
with the other VCN.
Using the API

To manage your RPCs and create connections, use these operations:

l ListAllowedPeerRegionsForRemotePeering
l ListRemotePeeringConnections
l CreateRemotePeeringConnection
l GetRemotePeeringConnection
l UpdateRemotePeeringConnection
l DeleteRemotePeeringConnection
l ConnectRemotePeeringConnections
Dynamic Routing Gateways (DRGs)

This topic describes how to manage a dynamic routing gateway (DRG). This topic uses the
terms dynamic routing gateway and DRG interchangeably. The Console uses the term
Dynamic Routing Gateway, whereas for brevity the API uses DRG.
You use a DRG when connecting your existing on-premises network to your virtual cloud
network (VCN) with one (or both) of these:
l IPSec VPN
l Oracle Cloud Infrastructure FastConnect
You also use a DRG when peering a VCN with a VCN in a different region:
l Remote VCN Peering (Across Regions)
Working with Dynamic Routing Gateways

You can think of a DRG as a virtual router that provides a path for private traffic (that is,
traffic that uses private IPv4 addresses) between your VCN and destinations other than the
internet. For example, if you use an IPSec VPN or Oracle Cloud Infrastructure FastConnect (or
both) to connect your on-premises network to your VCN, that private IPv4 address traffic goes
through a DRG that you create and attach to your VCN. Also, if you decide to peer that VCN
with a VCN in another region, your VCN's DRG routes traffic to the other VCN over a private
backbone that connects the regions (without traffic traversing the internet). Be aware that the

DRG must exist before you create the connection to the other network. For scenarios for using
a DRG to connect a VCN to your on-premises network, see Overview of Networking. For
information about connecting VCNs in different regions, see Remote VCN Peering (Across
Regions).
For the purposes of access control, when creating a DRG, you must specify the compartment
where you want the DRG to reside. If you're not sure which compartment to use, put the DRG
in the same compartment as the cloud network. For more information, see Access Control.
You may optionally assign a friendly name to the DRG . It doesn't have to be unique, and you
can change it later. Oracle automatically assigns the DRG a unique identifier called an Oracle
A DRG is a standalone object. To use it, you must attach it to a cloud network. A cloud network
can be attached to only one DRG at a time, and a DRG can be attached to only one VCN at a
time. You can detach a DRG and reattach it at any time. In the API, the process of attaching
creates a DrgAttachment object with its own OCID. To detach the DRG, you delete that
attachment object.
After attaching a DRG, you must update the routing in your cloud network to use the DRG.
Otherwise, traffic from your cloud network will not flow to the DRG. For more information,
see Route Tables.
To delete a DRG, it must not be attached to a cloud network or connected to another network
by way of IPSec VPN, Oracle Cloud Infrastructure FastConnect, or remote VCN peering. Also,
there must not be a route table that lists that DRG as a target.
For information about the number of DRGs you can have, see Service Limits.
Required IAM Policy


Tagging Resources
Using the Console

In general, to use a DRG, you must complete these steps:
1. Create the DRG.

2. Attach the DRG to your VCN.
3. Add a route rule for the DRG to the route table. Do this for the route table used by each
subnet that must send traffic to the DRG. If all the subnets use the VCN's default route
table, you must only update that one table.
To create a dynamic routing gateway

1. Open the Console, click Networking, and then click Dynamic Routing Gateways.
Control.
3. Click Create Dynamic Routing Gateway.
l Create in Compartment: The compartment where you want to create the DRG,
l Name: A friendly name for the DRG. It doesn't have to be unique, and it cannot

administrator.
The resource is created and then displayed on the Dynamic Routing Gateways page of the
compartment you chose. It will be in the "Provisioning" state for a short period. You can
connect it to other parts of your network only after provisioning is complete.
To attach a dynamic routing gateway to a cloud network

Note: A cloud network can be attached to only one DRG at a time, and a DRG can be attached
to only one cloud network at a time. The attachment is automatically created in the
compartment that holds the cloud network.
The following instructions have you navigate to the DRG and then choose which cloud network
to attach. You could instead navigate to the cloud network and then choose which DRG to
attach.
A list of the DRGs in the compartment you're viewing is displayed. If you don’t see the
one you're looking for, verify that you’re viewing the correct compartment (select from
the list on the left side of the page).
2. Click the DRG you want to attach.
3. On the left side of the page, click Virtual Cloud Networks. If you want to attach the
DRG to a cloud network in a different compartment than the one you're working in,
choose that compartment from the list on the left side of the page.
4. Click Attach to Virtual Cloud Network.
5. Select the cloud network you want to attach to the DRG, and then click Attach to

After it's ready, make sure to create a route rule that directs traffic to this DRG. See To add a
route rule for a dynamic routing gateway.
To add a route rule for a dynamic routing gateway

For each subnet that must send traffic to the DRG, you must add a route rule to the route table
associated with that subnet. If all the subnets in the VCN use the default route table, you must
add a rule to only that one table.
If all non-intra-VCN traffic that's not covered by another rule in the table must be routed to
the DRG, then this is the new rule to add:
l Destination CIDR Block = 0.0.0.0/0. If you want to limit the rule to a specific
network (for example, your on-premises network), then use that network's CIDR
instead of 0.0.0.0/0.
l Target Compartment: The compartment where the DRG resides.
l Target = the DRG.
For step-by-step instructions, see To update a route table.
To detach a dynamic routing gateway from a cloud network

Note: You do not need to remove the route rule that routes traffic to the DRG before you
detach the DRG from the cloud network.
2. Click the DRG you want to detach.

3. On the left side of the page, click Virtual Cloud Networks to see the cloud network
the DRG is attached to. If the cloud network is in a different compartment than the one
you're working in, choose that compartment from the list on the left side of the page.
4. Click the Actions icon ( ), and then click Detach.
The attachment will be in the "Detaching" state for a short period.
To delete a dynamic routing gateway

Prerequisites: The DRG must not be attached to a cloud network. It must also not be
connected to another network with an IPSec VPN, with Oracle Cloud Infrastructure
FastConnect, or through remote VCN peering. Finally, there must not be a route table that
lists the DRG as a target.
2. Click Delete for the DRG you want to delete.
The DRG will be in the "Terminating" state for a short period while it's being deleted.
To manage tags for a dynamic routing gateway

1. In the Console, click Networking, and then click Dynamic Routing Gateways.
2. Click the DRG you're interested in.
ones.

Using the API

To manage your DRGs, use these operations:
l ListDrgs
l CreateDrg
l GetDrg
l UpdateDrg
l DeleteDrg
l ListDrgAttachments
l CreateDrgAttachment: This attaches a DRG to a VCN and results in a DrgAttachment
object with its own OCID.
l GetDrgAttachment
l UpdateDrgAttachment: You can update only the name of the DrgAttachment.
l DeleteDrgAttachment: This detaches a DRG from a VCN by deleting the DrgAttachment.
For information about route table operations, see Route Tables.
IPSec VPNs
One way to connect your on-premises network and your virtual cloud network (VCN) is to use
an IPSec VPN. IPSec stands for Internet Protocol Security or IP Security. IPSec is a protocol
suite that encrypts the entire IP traffic before the packets are transferred from the source to
the destination.

This topic gives instructions for setting up and managing an IPSec VPN for your VCN. For
scenarios that include an IPSec VPN, see Scenario B: Private Subnets with a VPN and Scenario
C: Public and Private Subnets with a VPN.
Required Personnel and Knowledge

Typically the following types of personnel are involved in setting up an IPSec VPN with Oracle
Cloud Infrastructure:
l Dev Ops team member (or similar function) who uses the Oracle Cloud
InfrastructureConsole to set up the cloud components required for the virtual network
and IPSec VPN.
l Network engineer (or similar function) who configures the on-premises router with
information provided by the Dev Ops team member.
Tip
The Dev Ops team member must have the required

permission to create and manage the cloud
components. If the person is the default administrator
for your Oracle Cloud Infrastructure tenancy or a
member of the Administrators group, then they have
the required permission. For information about
restricting access to your networking components, see
Access Control.
The personnel should be familiar with the following concepts and definitions:
l The fundamentals of Oracle Cloud Infrastructure

l The basic Networking service components
l General IPSec VPN tunnel functionality

CLOUD RESOURCES
Anything you provision on a cloud platform. For example, with Oracle Cloud
Infrastructure, a cloud resource can refer to a VCN, compute instance, user,
compartment, load balancer, or any other service component on the platform.
ON-PREMISES
A widely used term in cloud technologies that refers to your traditional data center
environments. On-premises can refer to a colocation scenario, a dedicated floor space, a
dedicated data center building, or a desktop running under your desk.
ORACLE CLOUD IDENTIFIER (OCID)

A unique identifier assigned to each resource that you provision on Oracle Cloud
Infrastructure. The OCID is a long string that Oracle automatically generates. You can't
choose the value for an OCID or change a resource's OCID. For more information, see
About the Oracle IPSec VPN

In general, IPSec can be configured in the following modes:
l Transport mode: IPSec encrypts and authenticates only the actual payload of the
packet, and the header information stays intact.
l Tunnel mode (supported by Oracle): IPSec encrypts and authenticates the entire
packet. After encryption, the packet is then encapsulated to form a new IP packet that
has different header information.
Oracle Cloud Infrastructure supports only the tunnel mode for IPSec VPNs.
Each Oracle IPSec VPN consists of multiple redundant IPSec tunnels that use static routes to
route traffic. Border Gateway Protocol (BGP) is not supported for the Oracle IPSec VPN.

Important
Oracle uses asymmetric routing across the multiple

tunnels that make up the IPSec VPN connection. Even if
you configure one tunnel as primary and another as
backup, traffic from your VCN to your on-premises
network can use any tunnel that is "up" on your device.
Configure your firewalls accordingly. Otherwise, ping
tests or application traffic across the connection will not
reliably work.
IPSec VPN site-to-site tunnels offer the following advantages:
l Public telecommunication lines are used to transmit data, so dedicated, expensive lease
lines from one site to another aren't necessary.
l The internal IP addresses of the participating networks and nodes are hidden from
external users.
l The entire communication between the source and destination sites is encrypted,
significantly lowering the chances of information theft.
Overview of the IPSec VPN Components
If you're not already familiar with the basic Networking service components, see Overview of
Networking before proceeding.

When you set up an IPSec VPN for your VCN, you must create several Networking
components. You can create the components with either the Console or the API. See the
following diagram and description of the components.
CPE OBJECT
At your end of the IPSec VPN is the actual router in your on-premises network (whether
hardware or software). The term customer-premises equipment (CPE) is commonly used
in some industries to refer to this type of on-premises equipment. When setting up the

VPN, you must create a virtual representation of the router. Oracle calls the virtual
representation a CPE, but this documentation typically uses the term CPE object to help
distinguish the virtual representation from the actual on-premises router. The CPE object
contains basic information about your router that Oracle needs.

At Oracle's end of the IPSec VPN is a virtual router called a dynamic routing gateway,
which is the gateway into your VCN from your on-premises network. Whether you're using
an IPSec VPN or Oracle Cloud Infrastructure FastConnect private virtual circuits to
connect your on-premises network and VCN, the traffic goes through the DRG. For more
information, see Dynamic Routing Gateways (DRGs).
A network engineer might think of the DRG as the VPN headend. After creating a DRG, you
must attach it to your VCN, using either the Console or API. You must also add one or
more route rules that route traffic from the VCN to the DRG. Without that DRG attachment
and the route rules, traffic will not flow between your VCN and on-premises network. At
any time, you can detach the DRG from your VCN but maintain all the remaining VPN
components. You can then reattach the DRG, or attach it to another VCN.
IPSEC CONNECTION
After creating the CPE object and DRG, you connect them by creating an IPSec connection,
which results in multiple redundant IPSec tunnels. Oracle recommends that you configure
your on-premises router to support all the tunnels in case one fails or Oracle takes one
offline for maintenance. Each tunnel has configuration information that your network
engineer needs when configuring your on-premises router (an IP address and secret key).
Access Control for the Components
For the purposes of access control, when you set up the IPSec VPN, you must specify the
compartment where you want each of the components to reside. If you're not sure which
compartment to use, put all the components in the same compartment as the VCN. For
information about compartments and restricting access to your networking components, see
Access Control.

Component Names and Identifiers
You can optionally assign a descriptive name to each of the components when you create
them. These names don't have to be unique, although it's a best practice to use unique names
across your tenancy. Avoid including confidential information in the names. Oracle
automatically assigns each component an OCID. For more information, see Resource
Identifiers.
About the Static Routes
When you create the IPSec connection for your VPN, you must specify one or more static
routes. For example, you could specify the CIDR for your on-premises network, or the specific
subnets within your network that need to communicate with your VCN. This section has
suggestions for how to specify your static routes.
Important
After you set up the IPSec VPN, you can't edit or expand
the list of static routes associated with the tunnels.
To change the static routes would require you to delete

the IPSec connection, re-create it, and then reconfigure
your router.
l For a proof of concept (POC): If you're just doing a simple POC with a single on-
premises router, then having only a single static route of either 0.0.0.0/0 or the CIDR of
your on-premises network is sufficient. See Example: Setting Up a Proof of Concept
IPSec VPN.
l For a production network: Because you can't edit or expand the list of static routes
associated with the tunnels, Oracle recommends including a 0.0.0.0/0 static route in the
list when you create your IPSec connection. That way you can later change or expand
your on-premises network without touching your existing IPSec VPN, because you only
need to update the VCN's route rules, which you can do at any time. The 0.0.0.0/0 static
route can be in lieu of or in addition to a static route for your overall on-premises

network's CIDR (or a static route for each subnet that needs to communicate with your
VCN). See Example Layout with Multiple Geographic Areas.
l For port address translation (PAT): If you're doing PAT between your on-premises
router and VCN, the static route for the IPSec connection is the PAT IP address. See
Example Layout with PAT.
If You Use Both an IPSec VPN and FastConnect
If you set up both an IPSec VPN and a FastConnect private virtual circuit to the same DRG,
consider that the IPSec VPN uses static routes but FastConnect uses BGP. Also consider the
following points:
l Oracle advertises a route for each of your VCN’s subnets over the FastConnect virtual
circuit BGP session.
l Oracle overrides the default route selection behavior to prefer BGP routes over static
routes if a static route overlaps with a route advertised by your on-premises network.

Before You Get Started

To prepare, do these things first:
l Answer these questions:
Question Answer
What is your VCN's CIDR?
What is the public IP address of your on-premises router? If you have

multiple routers for redundancy, get the IP address for each.
Will you be doing port address translation (PAT) between each on-premises
router and your VCN?
What are the static routes for the IPSec connection? See About the Static
Routes
l Draw a diagram of your network layout similar to the one in the preceding section.
Think about which parts of your on-premises network need to communicate with your
VCN, and the reverse. Map out the routing and security lists that you need for your VCN.
l If you're using your credit card to "Pay-as-You-Go" or you've signed up for a free
promotion, request an account limit increase for CPE objects, DRGs, and IPSec
connections. By default, these limits are initially set to 0 for your kind of account, and a
request to create one of these resources will fail. For instructions, see Requesting a
Service Limit Increase. Make sure to indicate the region where you need the resources.
It can take a couple of business days for the limit increase to take effect.
Overall Process
Here's the overall process for setting up an IPSec VPN:

1. Complete the tasks listed in Before You Get Started.

2. Set up the IPSec VPN components (instructions in Example: Setting Up a Proof of
Concept IPSec VPN):
a. Create your VCN.
b. Create a DRG.
c. Attach the DRG to your VCN.
d. Create a route table and route rule for the DRG.
e. Create a security list and required rules.
f. Create a subnet in the VCN.
g. Create a CPE object and provide your router's public IP address.
h. From your DRG, create an IPSec connection to the CPE object and provide your
static routes.
3. Have your network engineer configure your CPE router: Your network engineer
must configure your on-premises router with information that Oracle provides during
the previous steps. There is general information about the VCN, and specific information
for each IPSec tunnel. This is the only part of the setup that you can't execute by using
the Console or API. Without this configuration, traffic will not flow between your
VCN and on-premises network. For more information, see Configuring Your On-
4. Validate connectivity.
Example: Setting Up a Proof of Concept IPSec VPN

This example scenario shows how to set up a single IPSec VPN with a simple layout that you
might use for a proof of concept (POC). It follows tasks 1 and 2 in Overall Process and shows
each component in the layout being created. For each task, there's a corresponding
screenshot from the Console to help you understand what information is needed where. For
more complex layouts, see Example Layout with Multiple Geographic Areas or Example Layout
with PAT.

Task 1: Gather information
Question Answer
What is your VCN's CIDR? 172.16.0.0/16
What is the public IP address of your on-premises router? If you have 142.34.145.37
multiple routers for redundancy, get the IP address for each.
Will you be doing port address translation (PAT) between each on- No
premises router and your VCN?
What are the static routes for the IPSec connection? See About the Only 10.0.0.0/16
Static Routes. for a simple POC.
Diagram drawn in task 1:
Task 2a: Create the VCN

If you already have a VCN, skip to the next task.

Tip
When you use the Console to create a VCN, you can

create only the VCN, or you can create the VCN with
several related resources. This task creates only the
VCN, and the subsequent tasks create the other
required resources.

1. In the Console, click Networking.

Control.
4. Enter the following values:
l Create in Compartment: Leave as is.
l Name: A descriptive name for the cloud network. It doesn't have to be unique,
and it can't be changed later in the Console (but you can change it with the API).
l Create Virtual Cloud Network Only: Select this option.
l CIDR Block: A single, contiguous CIDR block for the cloud network (for example,
172.16.0.0/16). You can't change this value later. See Allowed VCN Size and
Address Ranges. For reference, use a CIDR calculator.
5. You can provide values for the rest of the options, or you can ignore them:
l DNS Resolution: If you want the instances in the VCN to have DNS hostnames
(which can be used with the Internet and VCN Resolver, a built-in DNS capability
in the VCN), select the Use DNS Hostnames in this VCN checkbox. Then you
can specify a DNS label for the VCN, or the Console will generate one for you. The
dialog box automatically displays the corresponding DNS Domain Name for the
VCN (<VCN DNS label>.oraclevcn.com). For more information, see DNS in Your
administrator.

The VCN is created and displayed on the page. Ensure that it's done being provisioned before
continuing.
Task 2b: Create the DRG
1. Click Networking, and then click Dynamic Routing Gateways.

l Create in Compartment: Leave as is (the VCN's compartment).
l Name: A descriptive name for the DRG. It doesn't have to be unique, and it
cannot be changed later in the Console (but you can change it with the API). Avoid

administrator.
The DRG is created and displayed on the page. Ensure that it's done being provisioned before
continuing.
Tip
You could also use this DRG as the gateway for Oracle
Cloud Infrastructure FastConnect, which is an
alternative way to connect your on-premises network to
your VCN.

Task 2c: Attach the DRG to the VCN
1. Click the name of the DRG that you just created.

2. On the left side of the page, click Virtual Cloud Networks.
3. Click Attach to Virtual Cloud Network.
4. Select the VCN that you created earlier, and then click Attach to Virtual Cloud
Network.
The attachment will be in the Attaching state for a short period before it's ready.
Task 2d: Create a route table and route rule for the DRG
Although the VCN comes with a default route table (without any rules), in this task you create
a new route table with a route rule for the DRG. In this example, your on-premises network is
10.0.0.0/16. You create a route rule that takes any traffic destined for 10.0.0.0/16 and routes
it to the DRG. When you create a subnet in task 2f, you associate this route table with the
subnet.

Tip
If you already have an existing VCN with a subnet, you

don't need to create a new route table or subnet.
Instead you can update the existing subnet's route table
to include the route rule for the DRG.
1. Click Networking, click Virtual Cloud Networks, and then click the name of your
VCN.
2. Click Route Tables to see your VCN's route tables.

l Create in compartment: Leave as is.

l Name: A descriptive name for the route table (for example,
MyExampleRouteTable). The name doesn't have to be unique, and it can't be
changed later in the Console (but you can change it in the API). Avoid entering
l Destination CIDR Block: The CIDR for your on-premises network (10.0.0.0/16
in this example).
l Target Compartment: Leave as is.
l Target: The DRG that you created earlier.
l Tags: Leave the tag information as is.
The route table is created and displayed on the page. However, the route table doesn't do
anything unless you associate it with a subnet during subnet creation (see task 2f).
Task 2e: Create a security list

By default, incoming traffic to the instances in your VCN is set to DENY on all ports and all
protocols. In this task, you set up two ingress rules and one egress rule to allow basic
required network traffic. Although your VCN comes with a default security list with a set of
default rules, in this task you create a new security list with a more restrictive set of rules
focused on traffic with your on-premises network. When you create a subnet in task 2f, you
associate this security list with the subnet.

Important
In the following procedure, ensure that the on-premises

CIDR that you specify in the security list rules is the
same (or smaller) than the CIDR that you specified in
the route rule in the preceding task. Otherwise, traffic
will be blocked by the security lists.
1. While still viewing your VCN, click Security Lists on the left side of the page.
l Create in compartment: Leave as is.
l Security List Name: A descriptive name for the security list. The name doesn't
have to be unique, and it cannot be changed later in the Console (but you can
change it in the API). Avoid entering confidential information.

4. In the Allowed Rule for Ingress section, enter the following values for the first
ingress rule, which allows incoming SSH on TCP port 22 from your on-premises
network:
l Source CIDR: The CIDR for your on-premises network (10.0.0.0/16 in this
example)
l IP Protocol: TCP.
l Source Port Range: Leave as is (the default All).
l Destination Port Range: 22 (for SSH traffic).
5. In the Allowed Rule for Egress section, enter the following values for the egress
rule, which allows outgoing TCP traffic on all ports to your on-premises network:
l Destination CIDR: The CIDR for your on-premises network (10.0.0.0/16 in this
example).
l IP Protocol: TCP.
l Source Port Range: Leave as is (the default All).
l Destination Port Range: Leave as is (the default All).
6. Leave the tag information as is.
The security list is created and displayed on the page. However, the security list doesn't do
anything unless you associate it with a subnet during subnet creation (see task 2f).
Task 2f: Create a subnet

In this task, you create a subnet in the VCN. Typically a subnet has a CIDR block smaller than
the VCN's CIDR. Any instances that you launch into this subnet have access to your on-
premises network. A subnet is specific to a particular availability domain, which means that
all the private IP addresses within a subnet belong to a single availability domain.

1. While still viewing your VCN, click Subnets on the left side of the page.
2. Click Create Subnet.
l Name: A descriptive name for the subnet. It doesn't have to be unique, and it
can't be changed later in the Console (but you can change it with the API). Avoid
l Availability Domain: The availability domain that you want to use for the
subnet (for example: PHX-AD-1). Any instances that you later launch into this
subnet must also go into this availability domain. For more information, see
Regions and Availability Domains.
l CIDR Block: A single, contiguous CIDR block for the subnet (for example,
172.16.0.0/24). It must be within the cloud network's CIDR block and can't

overlap with any other subnets. You can't change this value later. See Allowed
VCN Size and Address Ranges. For reference, use a CIDR calculator.
l Route Table: The route table that you created earlier.
l Private Subnet: Select this option. For more information, see Internet Access.
l Use DNS Hostnames in this Subnet: Leave as is (selected).
l DHCP Options: The set of DHCP options to associate with the subnet. Select the
default set of DHCP options for the VCN.
l Security Lists: The security list that you created earlier.
l Tags: Leave the tag information as is.
4. Click Create.
The subnet is created and displayed on the page. The basic VCN in this example is now set up,
and you're ready to create the remaining components for the IPSec VPN.
Task 2g: Create a CPE object and provide your router's public IP address
In this task, you create the CPE object, which is a logical representation of your on-premises
router.

1. Click Networking, and then click Customer-Premises Equipment.

2. Click Create Customer-Premises Equipment.
l Name: A descriptive name for the CPE object. It doesn't have to be unique, and it
cannot be changed later in the Console (but you can change it with the API). Avoid
l IP Address: The IP address of the on-premises router at your end of the VPN
(see the list of information to gather in Before You Get Started).

administrator.
4. Click Create.
The CPE object is created and displayed on the page.
Task 2h: From your DRG, create an IPSec connection to the CPE object and
provide your static routes
In this task, you create the IPSec tunnels.

1. Click Networking, and then click Dynamic Routing Gateways.

2. Click the DRG that you created earlier.
3. Click Create IPSec Connection.
l Name: Enter a descriptive name for the IPSec connection. It doesn't have to be
unique, and it can't be changed later in the Console (but you can change it with the
API). Avoid entering confidential information.
l Customer-Premises Equipment Compartment: Leave as is (the VCN's
compartment).
l Customer-Premises Equipment: Select the CPE object that you created
earlier.
l Static Route CIDR: The CIDR block for a static route (see the list of information
to gather in Before You Get Started). For this example, enter 10.0.0.0/16. You
can't change this value later. If you want to change the static routes later, you
must delete these tunnels and then create and configure new ones.
administrator.
5. Click Create IPSec Connection.
The IPSec connection is created and displayed on the page. It will be in the Provisioning
state for a short period.
6. Click the Actions icon ( ), and then click Tunnel Information.
The configuration information for each tunnel is displayed (the IP address of the VPN
headend and the shared secret). Also, the tunnel's status is displayed (possible values
are Available and Down). At this point, the status is Down.

7. Copy the information for each of the tunnels into an email or other location so you can
deliver it to the network engineer who will configure the on-premises router.

For more information, see Configuring Your On-Premises Router for an IPSec VPN. You
can view this tunnel information here in the Console at any time.
8. Click Close.
Important
In the preceding screenshot, one of the tunnels is down

for maintenance. Be sure to configure your on-premises
router to support all of the tunnels in case one fails or
Oracle takes one down for maintenance. Also consider
that Oracle uses asymmetric routing across the tunnels,
so make sure to configure your firewalls accordingly.
You have now created all the components required for the IPSec VPN. But your network
engineer must configure the on-premises router before network traffic can flow between your
on-premises network and VCN.
Task 3: Have your network engineer configure your CPE router

Provide your network engineer with the tunnel information that you gathered in task 2h, and
other relevant information about your network. See Configuring Your On-Premises Router for
an IPSec VPN.
Task 4: Validate connectivity

After the network engineer configures your on-premises router, you can confirm that the
tunnel state is Up and green. Next, you can launch a Linux instance into the subnet in your
VCN. You should then be able to use SSH to connect to the instance's private IP address from
a host in your on-premises network. For more information, see Launching an Instance.

Example Layout with Multiple Geographic Areas

The following diagram shows an example with this configuration:
l Two networks in separate geographical areas that each connect to your VCN
l A single on-premises router in each area
l Two IPSec VPNs (one for each on-premises router)
Notice that each IPSec VPN has two static routes associated with it: one for the CIDR of the
particular geographical area, and a broad 0.0.0.0/0 static route. To understand why, see
About the Static Routes.
Following are some examples of situations in which the 0.0.0.0/0 static route can provide
flexibility:
l Assume that the CPE 1 router goes down (see the next diagram). If Subnet 1 and Subnet
2 can communicate with each other, your VCN could still reach the systems in Subnet 1
because of the 0.0.0.0/0 static route that goes to CPE 2.

l Assume that your organization adds a new geographical area with Subnet 3 and initially
just connects it to Subnet 2 (see the next diagram). If you added a route rule to your
VCN's route table for Subnet 3, the VCN could reach systems in Subnet 3 because of the
0.0.0.0/0 static route that goes to CPE 2.

Example Layout with PAT

The following diagram shows an example with this configuration:
l Two networks in separate geographical areas that each connect to your VCN
l Redundant on-premises routers (two in each geographical area)
l Four IPSec VPNs (one for each on-premises router)
l Port address translation (PAT) for each on-premises router

When you create each of the four IPSec connections, the static route that you specify is the
PAT IP address for the specific on-premises router. When you set up the route rules for the
VCN, you specify a rule for each PAT IP address (or an aggregate CIDR that covers them all)
with your DRG as the rule's target.
Working with IPSec VPNs

This section contains some details about working with IPSec VPNs and their components.
Tunnel Configuration and Status
When you successfully create the IPSec connection, Oracle produces important configuration
information for each of the resulting IPSec tunnels. For example, see task 2h. You can view
that information and the status of the tunnels at any time.

To get the status and configuration information for the IPSec tunnels
A list of the DRGs in the compartment that you're viewing is displayed. If you don’t see
2. Click the DRG that the IPSec tunnels are connected to.
The gateway's details are displayed, including the IPSec connection itself.
3. Click the Actions icon ( ), and then click Tunnel Information.
The configuration information for each tunnel is displayed (the IP address of the VPN headend
and the shared secret). Also, the tunnel's status is displayed (either Available or Down).
Disabling or Terminating the IPSec VPN
If you want to disable the IPSec VPN between your on-premises network and VCN, you can
simply detach the DRG from the VCN instead of deleting the IPSec connection. If you're also
using the DRG with FastConnect, detaching the DRG would also interrupt the flow of traffic
over FastConnect.
You can delete the IPSec connection. However, if you later want to re-establish it, your
network engineer would have to configure your on-premises router again with a new set of
tunnel configuration information from Oracle.
If you want to permanently delete the entire IPSec VPN, you must first terminate the IPSec
connection. Then you can delete the CPE object. If you're not using the DRG for another
connection to your on-premises network, you can detach it from the VCN and then delete it.
To delete an IPSec connection


3. For the IPSec connection you want to delete, click the Actions icon ( ), and then click
Terminate.
The IPSec connection will be in the Terminating state for a short period while it's being
deleted.
To delete a CPE object

Prerequisite: There must not be an IPSec connection between the CPE object and a DRG.
1. Open the Console, click Networking, and then click Customer-Premises

Equipment.
A list of the CPE objects in the compartment you're viewing is displayed. If you don’t
2. For the CPE object that you want to delete, click the Actions icon ( ), and then click
Delete.
The object will be in the Terminating state for a short period while it's being deleted.
Managing Tags for an IPSec Connection or CPE Object

To manage tags for an IPSec connection

3. For the IPSec connection you're interested in, click the Actions icon ( ), and then
click View Tags. From there you can view the existing tags, edit them, and apply new
ones.
To manage tags for a CPE object

1. Open the Console, click Networking, and then click Customer-Premises
Equipment.
A list of the CPE objects in the compartment you're viewing is displayed. If you don’t
2. Click the CPE object you're interested in.
ones.
Managing Your DRG
For tasks related to DRGs, see Dynamic Routing Gateways (DRGs).
Using the API


To manage your VCN and subnets, use these operations:
l ListVcns
l CreateVcn
l GetVcn
l UpdateVcn
l DeleteVcn
l ListSubnets
l CreateSubnet
l GetSubnet
l UpdateSubnet
l DeleteSubnet
To manage your DRG, use these operations:
l ListDrgs
l CreateDrg
l GetDrg
l UpdateDrg
l DeleteDrg
l ListDrgAttachments
l CreateDrgAttachment: This operation attaches a DRG to a VCN and results in a
DrgAttachment object with its own OCID.
l GetDrgAttachment
l UpdateDrgAttachment
l DeleteDrgAttachment: This operation detaches a DRG from a VCN by deleting the
DrgAttachment object.
To manage routing for your VCN, use these operations:

l ListRouteTables
l GetRouteTable
l UpdateRouteTable
l CreateRouteTable
l DeleteRouteTable
To manage security lists for your VCN, use these operations:
l ListSecurityLists
l GetSecurityList
l UpdateSecurityList
l CreateSecurityList
l DeleteSecurityList
To manage your CPEs, use these operations:
l ListCpes
l CreateCpe
l GetCpe
l UpdateCpe
l DeleteCpe
To manage your IPSec connections, use these operations:
l ListIPSecConnections
l CreateIPSecConnection: Use this operation to get the configuration information for each
tunnel, including the IP address of the DRG (the VPN headend) and the shared secret.
See Configuring Your On-Premises Router for an IPSec VPN.
l GetIPSecConnection
l UpdateIPSecConnection
l DeleteIPSecConnection

l GetIPSecConnectionDeviceStatus: Use this operation to determine the status of the

IPSec tunnels (up or down).
l GetIPSecConnectionDeviceConfig: Use this operation to get the configuration
information for each tunnel.

Configuring Your On-Premises Router for an IPSec VPN

This topic is for network engineers. It explains how to configure the on-premises router at
your end of the IPSec VPN so traffic can flow between your on-premises network and virtual
cloud network (VCN). See these related topics:
l Overview of Networking: For general information about the parts of a VCN

l IPSec VPNs: For information about how to set up an IPSec VPN
The following figure shows the basic layout of the IPSec VPN connection.
Requirements and Prerequisites

There are several requirements and prerequisites to be aware of before moving forward.
Asymmetric Routing
Oracle uses asymmetric routing across the multiple tunnels that make up the IPSec VPN
connection. Even if you configure one tunnel as primary and another as backup, traffic from

your VCN to your on-premises network can use any tunnel that is "up" on your device.
Configure your firewalls accordingly. Otherwise, ping tests or application traffic across the
connection will not reliably work.
Exception: Cisco ASA policy-based configuration, which uses a single tunnel.
Creation of Cloud Network Components
You or someone in your organization must have already used Networking to create a VCN and
an IPSec connection, which consists of multiple IPSec tunnels for redundancy. You must
gather the following information about those components:
l VCN ID: The VCN ID has a UUID at the end. You can use this UUID, or any other string
that helps you identify this VCN in the device configuration and doesn't conflict with
other object-group or access-list names.
l VCN CIDR
l VCN CIDR subnet mask
l For each IPSec tunnel:
o The IP address of the Oracle IPSec tunnel endpoint (the VPN headend)
o The pre-shared key (PSK)
Information about Your On-Premises Router
You also need some basic information about the inside and outside interfaces of your on-
premises router. For more information, see the configuration topic for your type of router.
IPSec VPN Best Practices

l Configure all tunnels for every IPSec connection: Oracle deploys multiple IPSec
headends for all your connections to provide high availability for your mission-critical
workloads. Configuring all the available tunnels is a key part of the "Design for Failure"
philosophy. (Exception: Cisco ASA policy-based configuration, which uses a single
tunnel.)

l Have redundant CPEs in your customer premise locations: Each of your sites
that connects via IPSec to Oracle Cloud Infrastructure should have redundant CPE
devices. If you add each CPE to the Oracle Cloud Infrastructure Console and create an
IPSec connection between your dynamic routing gateway (DRG) and each CPE, Oracle
will provision a full mesh of tunnel endpoints on the Oracle IPSec headends to your
CPEs. The Oracle network dynamically learns which tunnels are up and uses the optimal
one based on tunnel state and location.
l Consider backup aggregate routes: If you have multiple sites connected via IPSec
VPNs to Oracle Cloud Infrastructure, and those sites are connected to your on-premises
backbone routers, consider configuring your IPSec connection routes with both the local
site aggregate route as well as a default route.
Note that the DRG routes learned from the IPSec connections are only used by traffic
you route from your VCN to your DRG. The default route will only be used by traffic sent
to your DRG whose destination IP address does not match the more specific routes of
any of your tunnels.
Confirming the Status of the Connection

After you configure the IPSec connection, you can test the connection by launching an instance
into the VCN and then pinging it from your on-premises network. For information about
launching an instance, see Launching an Instance.
You can get the status of the IPSec tunnels in the API or Console. For instructions, see To get
the status and configuration information for the IPSec tunnels.
Device Configurations
l Generic CPE Configuration Information
l Check Point
l Cisco ASA: Policy-Based Configuration
l Cisco ASA: Route-Based Configuration
l Cisco IOS

l Fortigate
l Juniper MX
l Juniper SRX
l Palo Alto
Generic CPE Configuration Information

Oracle Cloud Infrastructure VPN service uses standards-based IPSec encryption. If your CPE
device is not one that already has configuration information (see Device Configurations), use
the information here to configure your device.
Important

reliably work.
ISAKMP Policy Options
l ISAKMP Protocol version 1

l Exchange type: Main mode
l Authentication method: pre-shared-keys
l Encryption: AES-128-cbc, AES-192-cbc, AES-256-cbc
l Authentication algorithm: SHA-256, SHA-384

l Diffie-Hellman group: group 1, group 2, group 5

l IKE session key lifetime: 28800 seconds (8 hours)
IPSec Policy Options
l IPSec protocol: ESP, tunnel-mode

l Encryption: AES-128-cbc, AES-192-cbc, AES-256-cbc
l Authentication algorithm: HMAC-SHA1-96
l IPSec session key lifetime: 3600 seconds (1 hour)
l Perfect Forward Secrecy (PFS): enabled, group 5
Security Parameter Index
The Oracle Cloud Infrastructure VPN headends use next-hop-based tunnels. When you create
a new IPSec connection, you specify a list of IPv4 networks that should be routed from your
dynamic routing gateway (DRG) through the IPSec tunnel to your CPE.
ORACLE IPS EC PROXYIDS
l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any
Check Point
This section includes two different sets of instructions: for domain-based tunnel configuration
and VPN tunnel interface (VTI) configuration.
This configuration was validated using a Check Point 2200.

Important

reliably work.
Parameters from API or Console
Get the following parameters from the Oracle Cloud Infrastructure Console or API.
${ipAddress#}
l Oracle VPN headend IPSec tunnel endpoints. There is one value for each tunnel.
l Example value: 129.146.12.52
${sharedSecret#}
l The IPSec IKE pre-shared-key. There is one value for each tunnel.
l Example value: EXAMPLEDPfAMkD7nTH3SWr6OFabdT6exXn6enSlsKbE
Additional Configuration Parameters
The Check Point config requires the following additional variables:
${cpePublicInterface}
l The name of the Interface where the CPE's public IP address is configured.
l Example Value: eth1
${VcnCidrBlock}

l When creating the VCN, your company selected this CIDR to represent the IP aggregate
network for all VCN hosts.
l Example Value: 10.0.0.0/16
${VcnCidrNetwork} and ${VcnCidrNetmask}
l These are the base address and netmask for the ${VcnCidrBlock}
l For more information, see: Wikipedia reference for finding CidrNetmask
l Values based on the example ${VcnCidrBlock} shown above:
o ${VcnCidrNetwork}: 10.0.0.0
o ${VcnCidrNetmask}: 255.255.0.0
Config Template Parameter Summary
Each region has multiple Oracle IPSec headends. The template below will allow setting up
multiple tunnels on your CPE, each to a corresponding headend. In the table below, "User" is
you/your company.
Parameter Source Example Value
${ipAddress1} Console/API 129.146.12.52
${sharedSecret1} Console/API (long string)
${cpePublicInterface} User eth1
${VcnCidrNetwork} User 10.0.0.0
${VcnCidrNetmask} User 255.255.0.0

Parameter Recommended Value
ISAKMP protocol version Version 1
Exchange type Main mode
Authentication method Pre-shared keys
Encryption AES-256-cbc
Authentication algorithm SHA-384
Diffie-Hellman Group Group 5
IKE session key lifetime 28800 seconds (8 hours)
IPSec protocol ESP, tunnel-mode
Authentication algorithm HMAC-SHA1-96
Perfect Forward Secrecy Enabled
IPSec session key lifetime 3600 seconds (1 hour)

Important
Oracle uses route-based tunnels. The proxy IDs on

Oracle's side are set as follows, and you must configure
them identically on your side:
l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any
If these values do not match on both ends, you'll have

connectivity issues.
Domain-Based Tunnel Configuration
CHECK POINT S MART DASHBOARD CONFIGURATION
l In SmartDashboard, under the "Networks" section, create new networks to represent

the subnets inside your local internal network and the subnets in your Oracle Cloud
Infrastructure cloud network (VPC).



l In SmartDashboard, under the groups section, create groups (Simple groups) to

represent your and your peer's VPN domain. Groups are required when multiple subnets
need to be reachable over the VPN tunnel. In this example you're adding only one
network object to the group, but you can add multiple according to your network’s
topology. Check Point recommends not adding a group as a part of another group
because performance can be impacted.

l In SmartDashboard, create a new Network Object, "Interoperable Device...", one per

tunnel.
o Name: Unique name per tunnel
o IPv4 Address: ${ipAddress#}


In this device’s Topology tab, under the VPN domain, select "manually defined", and
then select the group that you created in the previous steps that represents the remote
side (Oracle/VPC side) domain.

l Open your local device and go to the topology tab. Under the VPN domain, select
"manually defined", and then select the group that you created in the previous steps
that represents your internal domain.

l Open IPsec VPN tab "Communities" and create new "Star Community".
o Add your gateway or cluster as the Center Gateway.
o Add new Interoperable Devices as Satellite Gateways.


l Open the "Encryption" tab > Encryption Method, select "IKEv1" and under Encryption
Suite select "Custom". Select the following parameters for custom encryption suite:
o ISAKMP Phase 1: IKE SA
n AES-256
n SHA-384
o ISAKMP Phase 2: IPSec SA
n AES-256
n SHA1
Note
Use of SHA-1 is recommended because there

are issues setting up the IPSec tunnels if you're
using older versions of Check Point software
(before R77.30) with SHA-384. For more
information, see VPN tunnel can not be
established / no traffic passes when SHA-384 is
configured for data integrity.


l Under "Advanced Settings" > "Shared Secret", configure pre-shared keys.

o For each Peer, there is a unique ${sharedSecret#}

l Under "Advanced Settings" > "Advanced VPN Properties":

o IKE (Phase 1):

n Use Diffie-Hellman group: Group 5
n Renegotiate IKE security associations every: 480 minutes
n Uncheck "Use aggressive mode"
o IPsec (Phase 2):
n Check "Use Perfect Forward Secrecy"
n Renegotiate IPsec security associations every: 3600 seconds


l Under "Tunnel Management", under "VPN Tunnel Sharing", select "One VPN tunnel per
Gateway pair".

Important
You can select Tunnel Management parameters

under both "VPN community" and "Security
Gateway Object". Make sure you select "One
VPN tunnel per Gateway pair" under both of
these sections, or else you may have
connectivity issues due to conflicting
settings.
More details: If there's a conflict between the
tunnel properties of a VPN community and a
Security Gateway object that is a member of that
same community, the stricter setting is followed.
For example, a Security Gateway set to "One VPN
Tunnel per each pair of hosts" and a community set
to "One VPN Tunnel per Gateway pair" would follow
"One VPN Tunnel per each pair of hosts".
l Create Firewall Rules: Open Global Properties > VPN > Advanced.

o Check "Enable VPN Directional Match"

o For any firewall rule that matches VPN traffic, add match rules for each direction.
o Install firewall policy

Note
Redundant tunnel configuration is not recommended

because the tunnel failover will not work due to
absence of an IP address (numbered VTIs or BGP
IPSec) that can be used to ping the peer for DPD
and failover. If you need redundant tunnels, please
contact your Oracle representative.
VPN Tunnel Interface (VTI) Configuration
CHECK POINT GAIA PORTAL CONFIGURATION
l Under "Network Interfaces" tab, create one new "VPN Tunnel" interface per IPSec
connection tunnel.
o VPN Tunnel ID: Select a unique number
o Peer: Unique name for tunnel
o VPN Tunnel Type: Unnumbered
o Physical Device: ${cpePublicInterface}


l Under the "IPv4 Static Routes" tab, define VPN static routes, one per tunnel.
o Destination: ${VcnCidrNetwork}
o Subnet Mask: ${VcnCidrNetmask}
o Gateway: Interface - One per VPN tunnel

l In SmartDashboard, create a new Network Object, "Interoperable Device...", one per

tunnel.
o Name: Unique name per tunnel
o IPv4 Address: ${ipAddress#}


l In SmartDashboard, create a new group, "Simple Group..."
l Open your gateway/cluster and navigate to the "Topology" tab, choose "Manually
defined", and select new Simple Group.
l Open IPsec VPN tab "Communities" and create new "Star Community".
o Add your gateway or cluster as the Center Gateway.
o Add new Interoperable Devices as Satellite Gateways.


l Open the "Encryption" tab > Encryption Method, select "IKEv1" and under Encryption
Suite select "Custom". Select the following parameters for custom encryption suite:
o ISAKMP Phase 1: IKE SA
n AES-256
n SHA-384
o ISAKMP Phase 2: IPSec SA
n AES-256
n SHA1
Note
Use of SHA-1 is recommended because there

are issues setting up the IPSec tunnels if you're
using older versions of Check Point software
(before R77.30) with SHA-384. For more
information, see VPN tunnel can not be
established / no traffic passes when SHA-384 is
configured for data integrity.


l Under Advanced Settings > Shared Secret, configure pre-shared keys.

o For each Peer, there is a unique ${sharedSecret#}

l Under Advanced Settings > Advanced VPN Properties:

o IKE (Phase 1):

n Renegotiate IKE security associations every: 480 minutes
n Uncheck "Use aggressive mode"
o IPsec (Phase 2)
n Check "Use Perfect Forward Secrecy"
n Renegotiate IPsec security associations every: 3600 seconds


l Under "Tunnel Management", under "VPN Tunnel Sharing", select "One VPN tunnel per
Gateway pair".

Important
You can select Tunnel Management parameters

under both "VPN community" and "Security
Gateway Object". Make sure you select "One
VPN tunnel per Gateway pair" under both of
these sections, or else you may have
connectivity issues due to conflicting
settings.
More details: If there's a conflict between the
tunnel properties of a VPN community and a
Security Gateway object that is a member of that
same community, the stricter setting is followed.
For example, a Security Gateway set to "One VPN
Tunnel per each pair of hosts" and a community set
to "One VPN Tunnel per Gateway pair" would follow
"One VPN Tunnel per each pair of hosts".
l Create Firewall Rules: Open Global Properties > VPN > Advanced.

o Check "Enable VPN Directional Match"

o For any firewall rule that matches VPN traffic, add match rules for each direction.
o Install firewall policy

Note
Redundant tunnel configuration is not recommended

because the tunnel failover will not work due to
absence of an IP address (numbered VTIs or BGP
IPSec) that can be used to ping the peer for DPD
and failover. If you need redundant tunnels, please
contact your Oracle representative.
Cisco ASA: Policy-Based Configuration
Tip
Cisco ASA versions 9.7.1 and newer support route-

based configuration, which is the recommended method
to avoid interoperability issues.
The following policy-based configuration was validated using a Cisco ASA 5505.
${ipAddress#}
${sharedSecret#}

${cpePublicIpAddress}
l The public IP address for the CPE (previously made available to Oracle via the Console).
This is the IP address of your outside interface.
l Example Value: 1.2.3.4
The Cisco ASA config requires the following additional variables:
${vcnID}
l A UUID string used to uniquely name some access-lists and object-groups (can also use
any other string that does not create a name that conflicts with an existing object-group
or access-list).
l Example: oracle-vcn-1
${VcnCidrBlock}
list(${custCIDR},${custMask}) Customer Premise Networks
l In order to disable NAT between your VCN and your on-premises network, you need to
define the source IP addresses for packets going through your CPE into the IPSec

tunnels.
l Example Value: [ (10.0.0.0, 255.0.0.0), (172.16.0.0, 255.240.0.0), (192.168.0.0,
255.255.0.0) ]
Parameters Discovered from CPE Configuration
The following parameters are based on your current CPE Configuration.
Sample Router Config:

interface Vlan100
nameif outside
ip address 192.0.2.1 255.255.255.0
!
interface Vlan101
nameif inside
access-group outbound-acl out interface Vlan101
access-group inbound-acl in interface Vlan100
${insideInterface} and ${outsideInterface}
l These are the interfaces that face the inside and outside of your CPE.
l The outside interface should be able to ping the Oracle VPN headend IPs.
l The inside interface is the one facing your customer premise infrastructure.
l Values based on Sample Router Config above:
o ${insideInterface}: Vlan100
o ${outsideInterface}: Vlan101
${insideInterfaceName} and ${outsideInterfaceName}
l These are the "nameif" values for the inside and outside interfaces.
o ${insideInterfaceName}: inside
o ${outsideInterfaceName}: outside
${inboundAclName} and ${outboundAclName}

l You likely also have access-lists configured to control traffic in and out of your inside
and outside interfaces.
o ${inboundAclName}: inbound-acl
o ${outboundAclName}: outbound-acl
you/your company.
${cpePublicIpAddress} User 1.2.3.4
${vcnID} Console/API/User 1
${VcnCidrBlock} User 10.0.0.0/16
${VcnHostIp} User IP address of a host inside your VCN.

Preferably this host can reply to ICMP
Echo requests. Example: 10.0.2.7

list(${custCIDR}, User (0.0.0.0, 0.0.0.0), (10.128.0.0,

${custMask}) 255.255.0.0)
${insideInterface} User CPE Vlan100
${outsideInterface} User CPE Vlan101
${insideInterfaceName} User CPE inside
${outsideInterfaceName} User CPE outside
${inboundAclName} User CPE inbound-acl
${outboundAclName} User CPE outbound-acl
${cryptoMapAclName} User CPE orcl-acl
${vpnFilterAclName} User CPE orcl-filter

IPSec session key lifetime 300 seconds (5 minutes)
CPE Configuration
NETWORK OBJECT DEFINITION
The ASA uses configuration objects to identify IP networks that are used in mulitple locations.
DEFINE OBJECT THAT REPRESENTS YOUR ORACLE VCN
This object group is used by the IPSec policies to understand what IP addresses belong to your
Oracle VCN, so that they can be encrypted and sent inside the correct IPSec tunnel.
object network oracle-vcn-${vcnID}
subnet ${VcnCidrNetwork} ${VcnCidrNetmask}
DEFINE OBJECT THAT REPRESENTS YOUR CUSTOMER PREMISE NETWORK
This object may already be present on your ASA. A common name would match the interface
name of your "inside" interface. You might have multiple "subnet" entries in this object-group.
One for each aggregagte subnet you want to allow this IPSec tunnel to be used for traffic to
and from your Oracle VCN.
object network ${insideInterfaceName}
subnet ${custCIDR} ${custMask}

DISABLE NAT FOR VPN TRAFFIC
If you are using NAT for traffic between your inside and outside interfaces, you might need to
disable NAT for traffic between your on-premises network and the Oracle VCN.
nat (${insideInterfaceName},${outsideInterfaceName}) source static ${insideInterfaceName}
${insideInterfaceName} destination static oracle-vcn-${vcnID} oracle-vcn-${vcnID}
PERMIT TRAFFIC BETWEEN YOUR CPE AND YOUR ORACLE VCN
Assuming there is an access-list controlling traffic in and out of your Internet facing interface,
you will need to permit traffic between your CPE and the Oracle VPN headend.
WARNING: The new ACL entry you add to permit the traffic between your CPE and VPN
headend needs to be above any deny statements you might have in your existing access-list:
access-list ${outboundAclName} extended permit ip host ${ipAddress1} host ${cpePublicIpAddress}
access-list ${outboundAclName} extended permit ip host ${ipAddress2} host ${cpePublicIpAddress}
NOTE: You can be more restrictive in your ACL if you wish by only permitting the following:
l udp port 500 : isakmp

l esp : ipsec encapsulated secure payload
ADDITIONAL ACL CONFIGURATION
The following access list "orcl-acl" will be associated with the IPSec security association using
the "crypto-map" command.
access-list ${cryptoMapAclName} extended permit ip any ${VcnCidrNetwork} ${VcnCidrNetmask}
The following ACL will be used in the VPN filter to restrict the actual traffic that will be
permitted through the tunnels. See Base VPN Policy Configuration for details.
access-list ${vpnFilterAclName} extended permit ip ${VcnCidrNetwork} ${VcnCidrNetmask} ${custCIDR}
${custMask}
ISAKMP POLICY CONFIGURATION
See the ASA Command Reference.

crypto ikev1 enable ${outsideInterfaceName}
crypto ikev1 policy 1
authentication pre-share

encryption aes-256
hash sha
group 5
lifetime 28800
BASE VPN POLICY CONFIGURATION
This configuration sets the base values for the IPSec tunnels.
It also restricts what traffic will be allowed over the tunnels via the "vpn filter" command. By
default all traffic is denied by the filter.
group-policy oracle-vcn-vpn-policy internal
group-policy oracle-vcn-vpn-policy attributes
vpn-idle-timeout none
vpn-session-timeout none
vpn-tunnel-protocol ikev1
vpn-filter value ${vpnFilterAclName}
See the relevant Cisco documentation:
l group-policy
l VPN filter
IPS EC CONFIGURATION
See the relevant Cisco reference documentation.
WARNING: Make sure your crypto map sequence numbers do not overlap with existing
crypto maps.
crypto ipsec ikev1 transform-set oracle-vcn-transform esp-aes-256 esp-sha-hmac
crypto map oracle-${ipAddress1}-map-v1 1 match address ${cryptoMapAclName}
crypto map oracle-${ipAddress1}-map-v1 1 set pfs group5
crypto map oracle-${ipAddress1}-map-v1 1 set connection-type originate-only
crypto map oracle-${ipAddress1}-map-v1 1 set peer ${ipAddress1}
crypto map oracle-${ipAddress1}-map-v1 1 set ikev1 transform-set oracle-vcn-transform
crypto map oracle-${ipAddress1}-map-v1 1 set security-association lifetime seconds 300
crypto map oracle-${ipAddress1}-map-v1 interface outside
crypto map oracle-${ipAddress2}-map-v1 2 match address ${cryptoMapAclName}

crypto map oracle-${ipAddress2}-map-v1 2 set pfs group5
crypto map oracle-${ipAddress1}-map-v1 2 set connection-type originate-only

crypto map oracle-${ipAddress2}-map-v1 2 set peer ${ipAddress2}

crypto map oracle-${ipAddress2}-map-v1 2 set ikev1 transform-set oracle-vcn-transform
crypto map oracle-${ipAddress2}-map-v1 2 set security-association lifetime seconds 300
crypto map oracle-${ipAddress2}-map-v1 interface outside
Important
You must set the connection-type to "originate-only"

and set the phase-2 lifetime to 300 seconds to avoid
connectivity issues caused by incompatibilities between
Cisco ASA and the Oracle hardware.
PER TUNNEL IPS EC CONFIGURATION
This configuration matches the group policy with an Oracle VPN headend endpoint.
tunnel-group ${ipAddress1} type ipsec-l2l
tunnel-group ${ipAddress1} general-attributes
default-group-policy oracle-vcn-vpn-policy
tunnel-group ${ipAddress1} ipsec-attributes
ikev1 pre-shared-key ${sharedSecret1}

tunnel-group ${ipAddress2} general-attributes
default-group-policy oracle-vcn-vpn-policy
SLA MONITORING CONFIGURATION
The Cisco ASA device doesn't establish a tunnel if there's no interesting traffic trying to pass
through the tunnel. You must configure SLA monitoring on your device so that the tunnel
remains up at all times. You must allow ICMP on the outside interface. Make sure that the SLA
monitor number is unique.
sla monitor 1
type echo protocol ipIcmpEcho ${VcnHostIp} interface outside
frequency 5
sla monitor schedule 1 life forever start-time now
icmp permit any ${outsideInterface}

OPTIONAL CONFIG W HERE VPN TRAFFIC MIGHT ENTER ONE TUNNEL AND EXIT ANOTHER
If the VPN traffic enters an interface with the same security level as an interface towards the
packets next-hop, you will need to allow that traffic. By default, the packets between
interfaces with identical security levels on your ASA will be dropped.
See the relevant Cisco reference documentation.

same-security-traffic permit inter-interface
DEALING WITH TUNNEL MTU AND PATH MTU DISCOVERY
OPTION 1 - TCP MSS ADJUST
Because the maximum transmission unit (packet size) through the IPSec tunnel is less than
1500 bytes, we need to either fragment packets that are too big to fit through the tunnel or we
need to signal back to the hosts communicating through the tunnel that they need to send
smaller packets.
You can configure the Cisco ASA to change the maximum segment size (MSS) for any new TCP
flows through the tunnel. The ASA will look at any TCP packets where the SYN flag is set and
change the MSS value to the configured value. This might help new TCP flows avoid having to
use path maximum transmission unit discovery (pmtud).
sysopt connection tcpmss 1387
References:
l RFC 1191
l Relevant Cisco reference documentation
OPTION 2 - CLEAR/SET DON'T FRAGMENT BIT
Path MTU Discovery requires that all TCP packets have the Don't Fragment (DF) bit set. When
the packet arrives on the ASA, if it is too big to go through the tunnel and the DF bit is set, the
ASA will drop the packet and send an ICMP packet back to the sender indicating that the
packet was too big to fit through the tunnel. There are three options on the ASA for how to
handle the DF bit (pick one of the options):

l Set the DF bit: If the DF bit is not already set and the packet is too big, will set the DF
bit, causing the ASA to drop the the packet and send an ICMP error message back to the
sender. (Recommended)
crypto ipsec df-bit set-df ${outsideInterfaceName}
l Clear the DF bit: Will allow the ASA to fragment the packet and send it to the end host in
Oracle Cloud Infrastructure to reassemble the packet.
crypto ipsec df-bit clear-df ${outsideInterfaceName}
l Ignore (copy) the DF bit: If the packet is too big, and the DF bit is set, will drop the
packet and send error message to sender, if the DF bit is not set, will fragment the
packet and send to Oracle Cloud Infrastructure.
crypto ipsec df-bit copy-df ${outsideInterfaceName}
References:
l Path MTU Discovery on Wikipedia

l Relevant Cisco reference documentation
Cisco ASA: Route-Based Configuration

Cisco ASA versions 9.7.1 and newer support route-based configuration, which is the
recommended method to avoid interoperability issues. If you have an earlier version of
software, see Cisco ASA: Policy-Based Configuration.

Important

reliably work.
${ipAddress#}
${sharedSecret#}
This is the IP address of your outside interface.
l Example Value: 1.2.3.4
The Cisco ASA config requires the following additional variables:
${vcnID}

or access-list).
${VcnCidrBlock}
list(${custCIDR},${custMask}) Customer Premise Networks
l In order to disable NAT between your VCN and your on-premises network, you need to
define the source IP addresses for packets going through your CPE into the IPSec
tunnels.
l Example Value: [ (10.0.0.0, 255.0.0.0), (172.16.0.0, 255.240.0.0), (192.168.0.0,
255.255.0.0) ]
The following parameters are based on your current CPE Configuration.
${outsideInterface}
l This is the interface that faces outside of your CPE.

l The outside interface should be able to ping the Oracle VPN headend IPs.

${internalIpAddress}
l The IP address for the tunnel interface. You have one per tunnel you configure (for
example, ${internalIpAddress1}, ${internalIpAddress2}, and so on).
l The address can be any one that is not used in your network.
you/your company.
Parameter Source Example

Value
${vcnID} Console/API/User 1
${outsideInterface} User CPE Vlan101
${outsideInterfaceName} User CPE outside
${internalIpAddress1} User CPE 192.168.1.1

Parameter Source Example

Value
${internalIpAddress2} User CPE 192.168.1.2
${tunnelInterfaceName1} User CPE tunnel1
${tunnelInterfaceName2} User CPE tunnel2

CPE Configuration
IKE AND IPS EC POLICY CONFIGURATION
crypto ikev1 enable ${outsideInterface}
crypto ikev1 policy 1

encryption aes-256
hash sha
group 5
lifetime 28800
crypto ipsec ikev1 transform-set oracle-vcn-transform esp-aes-256 esp-sha-hmac
crypto ipsec profile oracle-vcn-vpn-policy

set ikev1 transform-set oracle-vcn-transform
set pfs group5
set security-association lifetime seconds 3600
TUNNEL GROUP CONFIGURATION



VTI I NTERFACE CONFIGURATION
interface ${tunnelInterfaceName1}
nameif ORACLE-VPN1
ip address ${internalIpAddress1} 255.255.255.252
tunnel source interface ${outsideInterfaceName}
tunnel destination ${ipAddress1}
tunnel mode ipsec ipv4
tunnel protection ipsec profile oracle-vcn-vpn-policy
interface ${tunnelInterfaceName2}
nameif ORACLE-VPN2
ip address ${internalIpAddress2} 255.255.255.252
tunnel source interface ${outsideInterfaceName}
tunnel protection ipsec profile oracle-vcn-vpn-policy
S TATIC ROUTE CONFIGURATION
route ORACLE1 ${VcnCidrNetwork} ${VcnCidrNetmask} ${tunnelInterfaceName1} 1 track

route ORACLE2 ${VcnCidrNetwork} ${VcnCidrNetmask} ${tunnelInterfaceName2} 100
CONFIGURATION FOR TUNNEL FAILOVER
sla monitor 10
type echo protocol ipIcmpEcho ${ipAddress1}interface outside
frequency 5
sla monitor schedule 10 life forever start-time now
track 1 rtr 10 reachability
Other Important Device Configuration
l Ensure NAT is disabled for VPN traffic.

l Ensure access-lists on the ASA are configured correctly.
l If you have multiple tunnels up simultaneously, ensure your ASA is configured to handle
traffic coming from your VCN/Oracle on any of the tunnels, even if one is active and the
other is backup. For example, you need to disable ICMP inspection, configure TCP state

bypass, and so on. For more details about the appropriate configuration, contact Cisco
support.
Cisco IOS
This configuration was validated using a Cisco 2921 running Cisco IOS Version 15.4(3)M3.
Important

reliably work.
${ipAddress#}
${sharedSecret#}

${VcnCidrBlock}
Parameters Based on Current CPE Configuration and State
The following parameters need to be discovered by examining your CPE's current

configuration and finding valid parameter values that do not overlap with the current CPE
configuration.
${tunnelNumber#} - one per tunnel
l The Cisco IOS uses the Tunnel interfaces for "Virtual Tunnel Interfaces" (vti) IPSec
tunnels.
l Command to find value: show run | inc interface Tunnel
l You will need one unused unit number per tunnel.
l Example Values: 1, 2
you/your company.

${tunnelNumber1} User 1
${tunnelNumber2} User 2

Important

l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any

CPE Configuration
PRE -SHARED-KEY CONFIGURATION
Add the pre-shared-keys to your configuration:

crypto keyring oracle-vpn-${ipAddress1}
local-address ${cpePublicIpAddress}
pre-shared-key address ${ipAddress1} key ${sharedSecret1}
crypto keyring oracle-vpn-${ipAddress2}
local-address ${cpePublicIpAddress}
pre-shared-key address ${ipAddress2} key ${sharedSecret2}
CONFIGURE BASIC ISAKMP OPTIONS
These are optional configuration options:

crypto logging session

crypto isakmp fragmentation
crypto isakmp keepalive 10 10
crypto ipsec df-bit clear
crypto ipsec security-association replay window-size 128
CONFIGURE BASE ISAKMP AND IPS EC POLICIES
crypto isakmp policy 1

encr aes 256
hash sha384
group 5
lifetime 28800
crypto ipsec transform-set oracle_vpn_transform esp-aes 256 esp-sha-hmac
mode tunnel
crypto ipsec profile oracle_vpn
set security-association dfbit clear
set transform-set oracle_vpn_transform
set pfs group5
CONFIGURE ISAKMP AND IPS EC PEERS
crypto isakmp profile oracle_vpn_${ipAddress1}

keyring oracle-vpn-${ipAddress1}
self-identity address
match identity address ${ipAddress1} 255.255.255.255
keepalive 10 retry 10
crypto isakmp profile oracle_vpn_${ipAddress2}
keyring oracle-vpn-${ipAddress2}
self-identity address
match identity address ${ipAddress2} 255.255.255.255
keepalive 10 retry 10
CONFIGURE VIRTUAL TUNNEL I NTERFACES
interface Tunnel${tunnelNumber1}
ip tcp adjust-mss 1387
tunnel source ${cpePublicIpAddress}
tunnel protection ipsec profile oracle_vpn_${ipAddress1}
!

interface Tunnel${tunnelNumber2}
tunnel source ${cpePublicIpAddress}
tunnel protection ipsec profile oracle_vpn_${ipAddress2}
UPDATE ANY I NTERNET FACING ACCESS LIST TO ALLOW IPS EC AND ISAKMP PACKETS
In order for the tunnels to come up, you need to open up udp port 500 and protocol esp to the
interface with your CPE Public IP Address. Example:
interface GigabitEthernet0/1
description INTERNET
ip address ${cpePublicIpAddress} 255.255.255.252
ip access-group INTERNET-INGRESS in
duplex auto
speed auto
!
ip access-list extended INTERNET-INGRESS

permit udp host ${ipAddress1} host ${cpePublicIpAddress} eq isakmp
permit esp host ${ipAddress1} host ${cpePublicIpAddress}
permit udp host ${ipAddress2} host ${cpePublicIpAddress} eq isakmp
permit esp host ${ipAddress2} host ${cpePublicIpAddress}
permit icmp any any echo
permit icmp any any echo-reply
permit icmp any any unreachable
CPE TO VCN S TATIC ROUTES
The IPSec tunnels require static routes to get traffic to go through them. The routes are
configured to point down the tunnel interfaces. If the IPSec tunnel is down, the Cisco router
will stop using that route. You should redistribute these routes into your customer premise
network.
ip route ${vcnCidrBlock} 255.0.0.0 Tunnel${tunnelNumber1}
ip route ${vcnCidrBlock} 255.0.0.0 Tunnel${tunnelNumber2}
Fortigate
This configuration was validated using a Fortigate VM running v5.4.1,build1064 (GA).

Important

reliably work.
${ipAddress#}
${sharedSecret#}
${VcnCidrBlock}


configuration.
l The name of the Fortigate interface where the CPE IP address is configured.
l Example value: ge-0/0/1.0
${policyId#}
l Index integers, must be unique per rule.

l Requires two per IPSecConnection tunnel.
l Example below for two tunnels requires four unique policyId numbers.
l Example value: 101
The Fortinet config requires the following additional variables:
${vcnID}
or access-list).
l These are the base address and netmask of your VCN Cidr Block

you/your company.
${cpePublicInterface} User CPE port1
${policyId1} User CPE 101
${VcnId} User/Console myVCN1


Important

l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any

CPE Configuration
FIREWALL CONFIGURATION
The configuration example below would allow all traffic from your VCN to any host on your
network.
config firewall address
edit any_ipv4
next
edit OracleVcn-${VcnId}_remote_subnet
set subnet ${VcnCidrNetwork} ${VcnCidrNetmask}
next
end
config firewall addrgrp

edit OracleVcn-${VcnId}_local
set member any_ipv4
next
edit OracleVcn-${VcnId}_remote
set member OracleVcn-${VcnId}_remote_subnet
next
end
config firewall policy

edit ${policyId1}
set name vpn_${ipAddress1}_local
set srcintf ${cpePublicInterface}
set dstintf ${ipAddress1}
set srcaddr OracleVcn-${VcnId}_local
set dstaddr OracleVcn-${VcnId}_remote
set action accept
set schedule always
set service ALL
set comments "VPN: Oracle ${ipAddress1}"
next
edit ${policyId2}
set name vpn_${ipAddress1}_remote
set srcintf {ipAddress1}
set dstintf ${cpePublicInterface}
set srcaddr OracleVcn-${VcnId}_remote
set dstaddr OracleVcn-${VcnId}_local
set action accept
set schedule always
set service ALL
next
edit ${policyId3}
set name vpn_${ipAddress2}_local
set srcintf ${cpePublicInterface}
set dstintf ${ipAddress2}
set srcaddr OracleVcn-${VcnId}_local
set dstaddr OracleVcn-${VcnId}_remote
set action accept
set schedule always
set service ALL
next
edit ${policyId4}
set name vpn_${ipAddress2}_remote
set srcintf ${ipAddress2}
set dstintf ${cpePublicInterface}
set srcaddr OracleVcn-${VcnId}_remote
set dstaddr OracleVcn-${VcnId}_local
set action accept
set schedule always
set service ALL


next
end
CONFIGURE ISAKMP PHASE 1
config vpn ipsec phase1-interface

edit ${ipAddress1}
set interface ${cpePublicInterface}
set keylife 28800
set proposal aes256-sha384 aes256-sha256
set dhgrp 5
set remote-gw ${ipAddress1}
set psksecret ${sharedSecret1}
next
edit ${ipAddress2}
set interface ${cpePublicInterface}
set keylife 28800
set proposal aes256-sha384 aes256-sha256
set dhgrp 5
set remote-gw ${ipAddress2}
set psksecret ${sharedSecret2}
next
end
CONFIGURE IPS EC - ISAKMP PHASE 2
config vpn ipsec phase2-interface

edit ${ipAddress1}
set phase1name ${ipAddress1}
set proposal aes256-sha1
set dhgrp 5
set replay disable
set auto-negotiate enable
set keylifeseconds 3600
next
edit ${ipAddress2}
set phase1name ${ipAddress2}
set proposal aes256-sha1
set dhgrp 5

set replay disable

set auto-negotiate enable
set keylifeseconds 3600
next
end
CONFIGURE S TATIC ROUTES TO YOUR VCN
config router static

edit 1
set dst ${VcnCidrNetwork} ${VcnCidrNetmask}
set device ${ipAddress1}
set comment "Oracle VPN-${ipAddress1}"
next
edit 2
set dst ${VcnCidrNetwork} ${VcnCidrNetmask}
set device ${ipAddress2}
set comment "Oracle VPN-${ipAddress2}"
next
end
Juniper MX
This configuration was validated using a Juniper MX 240 running Junos 15.1.
Important

reliably work.

${ipAddress#}
${sharedSecret#}
${VcnCidrBlock}

configuration.
l The name of the Juniper interface where the CPE IP address is configured.
${msInterface#} - one per tunnel
l These interfaces correspond to one of the four encryption ASICs on the MS-MPC card.
l You can distribute load across the ASICs by spreading your tunnels across them.

l Example values: ms-2/3/0, ms-2/3/1
${insideMsUnit1} and ${outsideMsUnit1} - one pair per tunnel
l For every tunnel, you will need an ms-mpc interface pair of units.
l One represents the outside of the IPSec tunnel.
l The other the inside of the tunnel.
l The router forwards packets from your on-premises network to your VCN into the inside
unit.
o The encryption ASIC then encrypts the packets based on the rules and policies.
o Then, the encrypted packet egresses out the outside unit as an ESP packet, ready
to be forwarded to Oracle's VPN headend routers.
l There are a little over 16,000 possible values for unit numbers.
o One way to allocate the units is to offset them by 8,000.
o You can pick values between 0 - 7999 for insideMsUnits and 8000-15999 for
outsideMsUnits.
you/your company.

${msInterface1} User ms-2/3/0
${msInterface2} User ms-2/3/1
${insideMsUnit1} User 101
${insideMsUnit2} User 102
${outsideMsUnit1} User 8101
${outsideMsUnit2} User 8102

Important

l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any

CPE Configuration
Note on routing-instances: If you are using routing-instances on your CPE, you need to
make sure you account for them in your configuration. The main configuration template below
does not account for routing-instances, so you would need to merge the following config
excerpt into the non-routing-instance templates.

routing-instances {
${customer premise routing instance} {
interface ${msInterface1}.${insideMsUnit1};
routing-options {
static {
route ${vcnCidrBlock} next-hop [ ${msInterface1}.${insideMsUnit1}
${msInterface2}.${insideMsUnit2} ]
}
}
}
${internet-routing-instance} {
}
}
services {
service-set oracle-vpn-tunnel-${ipAddress1} {
ipsec-vpn-options {
local-gateway ${cpePublicIpAddress} routing-instance ${internet-routing-instance};
}
}
ipsec-vpn-options {
}
}
ipsec-vpn-options {
}
}
}
TUNNEL I NTERFACE CONFIGURATION
This configures the Juniper MX interfaces that represent the "inside" and "outside" of the
IPSec tunnels. There is one pair of interface/units per tunnel. The unit numbers must be
unique on your router.
interfaces {
${msInterface1} {

unit ${insideMsUnit1} {
description oracle-vpn-tunnel-${ipAddress1}-INSIDE;
family inet;
service-domain inside;
}
unit ${outsideMsUnit1} {
description oracle-vpn-tunnel-${ipAddress1}-OUTSIDE;
family inet;
service-domain outside;
}
}
${msInterface2} {
unit ${insideMsUnit2} {
description oracle-vpn-tunnel-${ipAddress2}-INSIDE;
family inet;
service-domain inside;
}
unit ${outsideMsUnit2} {
description oracle-vpn-tunnel-${ipAddress2}-OUTSIDE;
family inet;
service-domain outside;
}
}
}
configured to point down the tunnel interfaces. If the IPSec tunnel is down, the Juniper MX will
stop using that route. You should redistribute these routes into your customer premise
network.
routing-options {
static {
route ${vcnCidrBlock} next-hop [ ${msInterface1}.${insideMsUnit1}
${msInterface2}.${insideMsUnit2} ]
}
}
S ERVICES CONFIGURATION
The IPSec tunnels are configured in this section.

services {
next-hop-service {
inside-service-interface ${msInterface1}.${insideMsUnit1};
outside-service-interface ${msInterface1}.${outsideMsUnit1};
}
ipsec-vpn-options {
local-gateway ${cpePublicIpAddress}
}
ipsec-vpn-rules oracle-vpn-tunnel-${ipAddress1};
}
next-hop-service {
inside-service-interface ${msInterface2}.${insideMsUnit2};
outside-service-interface ${msInterface2}.${outsideMsUnit2};
}
ipsec-vpn-options {
local-gateway ${cpePublicIpAddress}
}
ipsec-vpn-rules oracle-vpn-tunnel-${ipAddress2};
}
ipsec-vpn {
rule oracle-vpn-tunnel-${ipAddress1} {
term 1 {
from {
ipsec-inside-interface ${msInterface1}.${insideMsUnit1};
}
then {
remote-gateway ${ipAddress1};
dynamic {
ike-policy ike-policy-${ipAddress1};
ipsec-policy oracle-ike-policy;
}
tunnel-mtu 1420;
initiate-dead-peer-detection;
dead-peer-detection {
interval 5;
threshold 4;
}
}
}
match-direction input;

}
rule oracle-vpn-tunnel-${ipAddress2} {
term 1 {
from {
ipsec-inside-interface ${msInterface2}.${insideMsUnit2};
}
then {
remote-gateway ${ipAddress2};
dynamic {
ike-policy ike-policy-${ipAddress2};
ipsec-policy oracle-ike-policy;
}
tunnel-mtu 1420;
initiate-dead-peer-detection;
dead-peer-detection {
interval 5;
threshold 4;
}
}
}
match-direction input;
}
ipsec {
proposal esp-aes256-sha1 {
protocol esp;
authentication-algorithm hmac-sha1-96;
encryption-algorithm aes-256-cbc;
lifetime-seconds 3600;
}
policy oracle-ipsec-policy {
perfect-forward-secrecy {
keys group5;
}
proposals [ esp-aes256-sha1 ];
}
}
ike {
proposal aes256-sha384-group5 {
authentication-method pre-shared-keys;
dh-group group5;
authentication-algorithm sha-384;

}
policy oracle-ike-policy-${ipAddress1} {
mode main;
version 1;
proposals [ aes256-sha384-group5 ];
local-id ipv4_addr ${cpePublicIpAddress};
remote-id ipv4_addr ${ipAddress1};
pre-shared-key ascii-text ${sharedSecret1};
}
policy oracle-ike-policy-${ipAddress2} {
mode main;
version 1;
proposals [ aes256-sha384-group5 ];
local-id ipv4_addr ${cpePublicIpAddress};
remote-id ipv4_addr ${ipAddress2};
pre-shared-key ascii-text ${sharedSecret2};
}
}
}
}
Juniper SRX
This configuration was validated using a Juniper SRX 240 running 12.1X44-D35.5.
Important

reliably work.

${ipAddress#}
${sharedSecret#}
${VcnCidrBlock}

configuration.
l The name of the Juniper interface where the CPE IP address is configured.
${tunnelUnit#} - one per tunnel
l You will need multiple tunnel unit numbers per IPSec connection.
l One per IPSec tunnel.

l Oracle recommends setting up all Oracle configured tunnels for maximum redundancy.
l The Juniper SRX uses the st0 interface for IPSec tunnels.
l Example values: 1, 2
JUNIPER S ECURITY ZONES
l Juniper SRX has the concept of "security zones".

l You will need two different security zones for your VPN.
${InsideZoneName}
l This zone contains the interfaces that are part of your internal network that need to
reach resources in your Oracle VCN.
${OracleVpnZoneName}
l This zone contains the interfaces that are part of the Oracle Cloud Infrastructure
network.
l This includes the inside of the IPSec tunnel interfaces.
${InternetSecurityZoneName}
l This is the zone that includes your ${cpePublicInterface}.
you/your company.

${cpePublicInterface} User ge-0/0/1.0
${tunnelUnit1} User 1
${tunnelUnit2} User 2
${OracleVpnZoneName} User oracle-vpn
${InternetSecurityZoneName} User INTERNET

Important

l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any

CPE Configuration
TUNNEL I NTERFACE CONFIGURATION
This configures the Juniper SRX interfaces that represent the "inside" of the IPSec tunnels.
There is one interface/unit per tunnel.

interfaces {
st0 {
unit ${tunnelUnit1} {
family inet;
}
unit ${tunnelUnit2} {
family inet;
}
}
}
configured to point down the tunnel interfaces. If the IPSec tunnel is down, the Juniper SRX
will stop using that route. You should redistribute these routes into your customer premise
network.
routing-options {
static {
route ${VcnCidrBlock} next-hop [ st0.${tunnelUnit1} st0.${tunnelUnit2} ];
}
}
S ECURITY POLICY
The security policy consists of four sections:
l ike: IKE policy parameters.

l ipsec: IPSec policy parameters.
l zones: Defines Juniper zones and place interfaces into logical zones.
l policies: Defines what traffic is permitted in and out of and between zones.
security {
ike {
proposal oracle-ike-proposal {
authentication-method pre-shared-keys;
dh-group group5;
authentication-algorithm sha-384;

}
policy ike_pol_oracle-vpn-${ipAddress1} {
mode main;
proposals oracle-ike-proposal;
pre-shared-key ascii-text ${sharedSecret1}
}
policy ike_pol_oracle-vpn-${ipAddress2} {
mode main;
proposals oracle-ike-proposal;
pre-shared-key ascii-text ${sharedSecret2}
}
gateway gw_oracle-${ipAddress1} {
ike-policy ike_pol_oracle-vpn-${ipAddress1};
address ${ipAddress1};
dead-peer-detection;
external-interface ${cpePublicInterface};
}
gateway gw_oracle-${ipAddress2} {
ike-policy ike_pol_oracle-vpn-${ipAddress2};
address ${ipAddress2};
dead-peer-detection;
external-interface ${cpePublicInterface};
}
}
ipsec {
vpn-monitor-options;
proposal oracle-ipsec-proposal {
protocol esp;
authentication-algorithm hmac-sha1-96;
}
policy ipsec_pol_oracle-vpn {
perfect-forward-secrecy {
keys group5;
}
proposals oracle-ipsec-proposal;
}
vpn oracle-vpn-${ipAddress1} {
bind-interface st0.${tunnelUnit1};
vpn-monitor;
ike {

gateway gw_oracle-${ipAddress1};
ipsec-policy ipsec_pol_oracle-vpn;
}
establish-tunnels immediately;
}
vpn oracle-vpn-${ipAddress2} {
bind-interface st0.${tunnelUnit2};
vpn-monitor;
ike {
gateway gw_oracle-${ipAddress2};
ipsec-policy ipsec_pol_oracle-vpn;
}
establish-tunnels immediately;
}
}
policies {
from-zone ${InsideZoneName} to-zone ${OracleVpnZoneName} {
policy new_vpn-out {
match {
source-address any-ipv4;
destination-address any-ipv4;
application any;
source-identity any;
}
then {
permit;
}
}
policy vpn-out {
match {
source-address any-ipv4;
destination-address any-ipv4;
application any;
source-identity any;
}
then {
permit;
}
}
}
}
zones {

security-zone ${OracleVpnZoneName} {
interfaces {
st0.${tunnelUnit1} {
host-inbound-traffic {
protocols {
bgp;
}
}
}
st0.${tunnelUnit2} {
protocols {
bgp;
}
}
}
}
}
security-zone ${InternetSecurityZoneName} {
interfaces {
${cpePublicInterface} {
system-services {
ike;
ping;
}
}
}
}
}
}
}
Palo Alto
This configuration was validated using a PA-500 running PanOS version 6.0.6.

Important

reliably work.
${ipAddress#}
${sharedSecret#}
${cpeInterfaceName}
l The name of the CPE interface where the CPE IP address is configured.
l Example Value: ethernet1/1
${VcnCidrBlock}

The following parameters are based on your current CPE configuration.
${tunnelUnit#}
l Each tunnel needs a unit number that identifies that tunnel.

l Example: 10, where 10 is the tunnelUnit for interface tunnel.10
${oracleSecurityZoneName}
l The tunnels need to be placed inside a security zone that defines their access profile.
l Example: "Oracle Cloud Infrastructure"
l Note: The value must be enclosed in quotation marks.
${CpeVirtualRouterName}
l The tunnels terminate into a virtual router in the Palo Alto. You can either terminate
them into an existing virtual router, or configure a new virtual router.
l Example Value: Oracle-virtual-router

Important

l local=0.0.0.0/0
l remote=0.0.0.0/0
l service=any

Common ISAKMP and IPSec Profile Configuration

set network ike crypto-profiles ike-crypto-profiles oracle-bare-metal-cloud-ike encryption aes256
set network ike crypto-profiles ike-crypto-profiles oracle-bare-metal-cloud-ike hash sha384
set network ike crypto-profiles ike-crypto-profiles oracle-bare-metal-cloud-ike dh-group group5
set network ike crypto-profiles ike-crypto-profiles oracle-bare-metal-cloud-ike lifetime hours 8
set network ike crypto-profiles ipsec-crypto-profiles oracle-bare-metal-cloud-ipsec esp encryption

aes256
set network ike crypto-profiles ipsec-crypto-profiles oracle-bare-metal-cloud-ipsec esp authentication
sha1
set network ike crypto-profiles ipsec-crypto-profiles oracle-bare-metal-cloud-ipsec dh-group group5
set network ike crypto-profiles ipsec-crypto-profiles oracle-bare-metal-cloud-ipsec lifetime hours 1
ISAKMP Gateway Configuration

set network ike gateway oracle-gateway-${ipAddress1} authentication pre-shared-key key ${sharedSecret1}
set network ike gateway oracle-gateway-${ipAddress1} protocol-common nat-traversal enable no
set network ike gateway oracle-gateway-${ipAddress1} local-address interface ${cpeInterfaceName}
set network ike gateway oracle-gateway-${ipAddress1} peer-address ip ${ipAddress1}
set network ike gateway oracle-gateway-${ipAddress1} protocol ikev1 ike-crypto-profile oracle-bare-
metal-cloud-ike
set network ike gateway oracle-gateway-${ipAddress2} authentication pre-shared-key key ${sharedSecret2}

set network ike gateway oracle-gateway-${ipAddress2} protocol-common nat-traversal enable no
set network ike gateway oracle-gateway-${ipAddress2} local-address interface ${cpeInterfaceName}
set network ike gateway oracle-gateway-${ipAddress2} peer-address ip ${ipAddress2}
set network ike gateway oracle-gateway-${ipAddress2} protocol ikev1 ike-crypto-profile oracle-bare-
metal-cloud-ike
IPSec Configuration
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress1} auto-key ike-gateway oracle-gateway-
${ipAddress1}
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress1} auto-key ipsec-crypto-profile oracle-bare-metal-
cloud-ipsec
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress1} tunnel-monitor enable no
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress1} tunnel-interface tunnel.${tunnelUnit1}
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress2} auto-key ike-gateway oracle-gateway-

${ipAddress2}
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress2} auto-key ipsec-crypto-profile oracle-bare-metal-
cloud-ipsec
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress2} tunnel-monitor enable no
set network tunnel ipsec oracle-ipsec-vpn-${ipAddress2} tunnel-interface tunnel.${tunnelUnit2}
Virtual Router Configuration
Newer versions of PanOS support Equal-cost multipath routing (ECMP).

set network virtual-router ${CpeVirtualRouterName} interface [ tunnel.101 tunnel.102 ]

set network virtual-router ${CpeVirtualRouterName} routing-table ip static-route oracle-vpn-
${ipAddress1} destination ${VcnCidrBlock}
${ipAddress1} interface tunnel.${tunnelUnit1}
${ipAddress1} metric 10
${ipAddress2} destination ${VcnCidrBlock}
${ipAddress2} interface tunnel.${tunnelUnit2}
${ipAddress2} metric 11
Security Zone Configuration

set zone ${oracleSecurityZoneName} network layer3 [ tunnel.101 tunnel.102 ]
FastConnect Overview
Oracle Cloud Infrastructure FastConnect provides an easy way to create a dedicated, private
connection between your data center and Oracle Cloud Infrastructure. FastConnect provides
higher-bandwith options, and a more reliable and consistent networking experience compared
to internet-based connections.
Uses for FastConnect

With FastConnect, you can choose to use private peering, public peering, or both.
l Private peering: To extend your existing infrastructure into a virtual cloud network
(VCN) in Oracle Cloud Infrastructure (for example, to implement a hybrid cloud, or a lift
and shift scenario). Communication across the connection is with IPv4 private
addresses (typically RFC 1918).
l Public peering: To access public services in Oracle Cloud Infrastructure without using
the internet. For example, Object Storage, the Oracle Cloud Infrastructure Console and
APIs, or public load balancers in your VCN. Communication across the connection is with
IPv4 public IP addresses. Without FastConnect, the traffic destined for public IP

addresses would be routed over the internet. With FastConnect, that traffic goes over
your private physical connection.
In general it's assumed you'll use private peering, and you might also use public peering.
Most of this documentation is relevant to both, with specific details called out for private
versus public.
How and Where to Connect

With FastConnect, you can establish a connection by colocating with Oracle or by using an
Oracle provider.
Colocation with Oracle in an Oracle Cloud Infrastructure FastConnect Location
l List of Oracle Cloud Infrastructure FastConnect locations (see the FAQ for specific
addresses)
l Port speed of 10 Gbps per cross-connect
l Instructions for integrating: FastConnect: Colocation with Oracle
Oracle Provider
l List of Oracle Cloud Infrastructure FastConnect providers

l Port speeds in 1-Gbps and 10-Gbps increments
l Instructions for integrating: FastConnect: With an Oracle Provider
Concepts
Here are some important concepts to understand (also see the following diagrams):
FASTCONNECT
The general concept of a connection between your existing network and Oracle Cloud
Infrastructure over a private physical network instead of the internet.

FASTCONNECT LOCATION
A specific Oracle data center where you can connect with Oracle Cloud Infrastructure.
METRO AREA
A geographical area (for example, Ashburn) with multiple FastConnect locations. All
locations in a metro area connect to the same set of availability domains for resiliency in
case of failure in a single location.
COLOCATION
The situation where your equipment is deployed into a FastConnect location. If your
network service provider is not on the list of Oracle providers in How and Where to
Connect, you must colocate.
CROSS -CONNECT
In a colocation scenario, this is the physical cable connecting your existing network to
Oracle in the FastConnect location.
CROSS -CONNECT GROUP
In a colocation scenario, this is a link aggregation group (LAG) that contains at least one
cross-connect. You can add additional cross-connects to a cross-connect group as your
bandwidth needs increase. This is applicable only for colocation.
ORACLE PROVIDER
A network service provider with a physical connection to the Oracle Cloud Infrastructure
network in a FastConnect location. See the list of the Oracle providers in How and Where
to Connect. If your provider is in the list, you can use FastConnect through the provider.
Otherwise, you must colocate with Oracle in a FastConnect location.
THIRD-PARTY PROVIDER
A network service provider that is NOT on the list of Oracle providers in How and Where to
Connect. If you have a third-party provider and want to use FastConnect, you must
colocate with Oracle in a FastConnect location.


Your virtual network in Oracle Cloud Infrastructure. You can use a VCN to extend your
infrastructure into the cloud. For more information, see VCNs and Subnets.

A virtual edge router attached to your VCN. Necessary for private peering. The DRG is a
single point of entry for private traffic coming in to your VCN, whether it's over
FastConnect or an IPSec VPN. After creating the DRG, you must attach it to your VCN and
add a route for the DRG in the VCN's route table to enable traffic flow. Instructions for
everything are included in the sections that follow.
VIRTUAL CIRCUIT
An isolated network path that runs over one or more physical network connections to
provide a single, logical connection between the edge of your existing network and Oracle
Cloud Infrastructure. Private virtual circuits support private peering, and public virtual
circuits support public peering (see Uses for FastConnect). Each virtual circuit is made up
of information shared between you and Oracle, as well as a provider (if you're connecting
through an Oracle provider). You could have multiple private virtual circuits, for example,
to isolate traffic from different parts of your organization (one virtual circuit for
10.0.1.0/24; another for 172.16.0.0/16), or to provide redundancy.
Basic Network Diagrams

The diagrams in this section introduce the basic logical and physical connections involved in
FastConnect. Details specific to private versus public peering are called out.

General Concept of FastConnect
The following diagram illustrates the two ways to connect to Oracle with FastConnect: either
through colocation with Oracle in the FastConnect location, or through an Oracle provider. In
both cases, the connection goes between the edge of your existing network and Oracle.
Physical Connection
The next two diagrams give more detail about the physical connections. They also show the
metro area that contains the FastConnect location, and a VCN within an Oracle Cloud

Infrastructure region.
The first diagram shows the colocation scenario, with your physical connection to Oracle
within the FastConnect location.

The next diagram shows a scenario with an Oracle provider, with your physical connection to
the provider, and the provider's physical connection to Oracle within the FastConnect location.
Logical Connection: Private Virtual Circuit
The next two diagrams show a private virtual circuit, which is a single, logical connection
between your edge and Oracle Cloud Infrastructure by way of your DRG. Traffic is destined for
private IP addresses in your VCN.

The first diagram shows the colocation scenario.

The next diagram shows the scenario with an Oracle provider.
Logical Connection: Public Virtual Circuit
A public virtual circuit gives your existing network access to regional public IPv4 addresses in
Oracle Cloud Infrastructure. For example, Object Storage, the Oracle Cloud Infrastructure
Console and APIs, and public load balancers in your VCN. All communication across a public
virtual circuit uses public IP addresses.

The first diagram shows the colocation scenario with both a private virtual circuit and a public
virtual circuit. Notice that the DRG is not involved with the public virtual circuit, only the
private virtual circuit.

The next diagram shows the scenario with an Oracle provider.
Here are a few basics to know about public virtual circuits:
l You choose which of your organization's public IP prefixes you want to use with the
virtual circuit. Each prefix must be /24 or less specific. Oracle verifies your
organization's ownership of each prefix before sending any traffic for it across the
connection. Oracle's verification for a given prefix can take up to three business days.
You can get the status of the verification of each prefix in the Oracle Console or API.
Oracle begins advertising the Oracle Cloud Infrastructure public IP
addresses across the connection only after successfully verifying at least
one of your public prefixes.
l Your existing network will receive Oracle's public IP addresses through both
FastConnect and your Internet Service Provider (ISP). When configuring your edge,
make sure to give higher preference to FastConnect over your ISP, or you will not
receive the benefits of FastConnect.

l You must configure your firewall rules to allow the desired traffic coming from the
Oracle public IP addresses.
l Oracle prefers the most specific route when routing traffic from Oracle Cloud
Infrastructure to other destinations. This means that when Oracle replies to traffic
coming from one of your verified public prefixes, the reply travels over the FastConnect
public virtual circuit, even if you have an internet gateway on your VCN. Replies to
traffic from any public prefixes that are not on your list or not yet verified by Oracle still
go through the internet gateway. For reference, this diagram shows the private and
public virtual circuits as well as an internet gateway on the VCN:
l You can add or remove public IP prefixes at any time by editing the virtual circuit. If you
add a new prefix, Oracle first verifies your company's ownership before advertising it
across the connection. If you remove a prefix, Oracle stops advertising the prefix within
a few minutes of your editing the virtual circuit.

Provider Scenario: BGP Session to Either Oracle or the Provider
This section is applicable if you're using FastConnect through an Oracle provider. A Border
Gateway Protocol (BGP) session is established from your edge, but where it goes to depends
on which Oracle provider you use.
Tip
For simplicity, the following diagrams show only a

private virtual circuit. However, the location of the BGP
session is the same for a public virtual circuit.
To Oracle: With some of the Oracle providers, the BGP session goes from your edge to
Oracle, as shown in the following diagram. When setting up the virtual circuit with Oracle, you
are asked to provide basic BGP peering information (see General Requirements).

To the Oracle provider: With other Oracle providers, your BGP session goes from your
edge to the provider's, as shown in the following diagram. When setting up the virtual circuit
with Oracle, you are NOT asked for any BGP session information. Instead, you share BGP
information with your Oracle provider. Notice that there's a separate BGP session that the
provider establishes with Oracle.
General Requirements
Before getting started with FastConnect, make sure you meet the following requirements:
l Oracle Cloud Infrastructure account, with at least one user with appropriate Oracle
Cloud Infrastructure Identity and Access Management (IAM) permissions (for example,
a user in the Administrators group).
l Network equipment that supports Layer 3 routing using BGP.

l For colocation with Oracle: Ability to connect using single mode fiber in your selected
FastConnect location. Also see Hardware and Routing Requirements for Colocation.
l For connection to an Oracle provider: At least one physical network connection with the
provider. Also see Routing Requirements.
l For private peering only: At least one existing DRG set up for your VCN.
l For public peering only: The list of public IP address prefixes that you want to use with
the connection. Oracle will validate your ownership of each prefix.
Important
You must ask Oracle to increase your account limits for

virtual circuits and cross-connects (if you're colocating
with Oracle). By default, these limits are initially set to
0, and a request to create one of these resources will
fail. For instructions, see Requesting a Service Limit
Increase. In your request, make sure to indicate the
region where you need the resources. It can take a
couple of business days for the limit increase to take
effect.
What's Next?
See these topics to get started:
l Colocation: By colocating with Oracle in a FastConnect location

l Provider: By connecting to an Oracle provider
FastConnect: With an Oracle Provider

This topic is for customers who want to use Oracle Cloud Infrastructure FastConnect by
connecting to an Oracle provider. For general information about FastConnect, see FastConnect

Overview. If you instead want to use FastConnect by colocating with Oracle, FastConnect:
Colocation with Oracle.
Before Getting Started: Learn and Plan

Here are basic things you need to do before getting started with FastConnect:
l FastConnect concepts: Make sure you're familiar with the basic concepts covered in
FastConnect Overview.
l Limits increase: You must ask Oracle to increase your account limits for virtual
circuits. By default, these limits are initially set to 0, and a request to create a virtual
circuit will fail. For instructions, see Requesting a Service Limit Increase. In your
request, make sure to indicate the region where you need the resources. It can take a
couple of business days for the limit increase to take effect.
l Routing requirements: Review the Routing Requirements, which are particularly
relevant if your BGP session is between your edge and Oracle.
l Tenancy setup and compartment design: If you haven't yet, set up your tenancy.
Think about who needs access to Oracle Cloud Infrastructure and how. For more
information, see "Setting Up Your Tenancy" in the Oracle Cloud Infrastructure Getting
Started Guide. Specifically for FastConnect, see Required IAM Policy to understand the
policy required to work with FastConnect components.
l Cloud network design: Design your virtual cloud network (VCN), including how you
want to allocate your VCN's subnets, define security list rules, define route rules, set up
load balancers, and so on. For more information, see Overview of Networking.
l Redundancy: Think through your overall redundancy model to ensure your network
can handle planned maintenance by Oracle or your organization, and unexpected
failures of the various components. See Network Design for Redundancy.
l Public IP prefixes: If you plan to set up a public virtual circuit, get the list of the
public IP prefixes that you want to use with the connection. Oracle must validate your
organization's ownership of each of the prefixes before advertising each one over the
connection.

l Cloud network setup: Set up your VCN, subnets, DRG, security lists, IAM policies,
and so on, according to your design. For instructions on how to set up the connection
between your VCN and existing network, see Getting Started with FastConnect.
Routing Requirements
Here are general routing requirements for FastConnect.
l IP addressing supported: IPv4

l P2P IP addresses:
o For public virtual circuits, Oracle specifies the IP addresses.
o For private virtual circuits where your BGP session is between your edge and
Oracle, you specify these addresses (/30 or /31, and one pair per virtual circuit).
If you set up multiple private virtual circuits that go to the same DRG, you must
use a different address on your edge router for each virtual circuit.
l Maximum IP MTU: 9000
l Routing protocol: BGPv4
l BGP prefix limit: For public virtual circuits: 200 prefixes. For private virtual circuits:
2000 prefixes.
l BGP ASN: 2-byte ASN. Public virtual circuits require a public ASN. Oracle's BGP ASN is
31898.
l BGP keep-alive interval: 60s
l BGP hold-time interval: 180s

Tip
By default, Oracle uses the default BGP timers of 60

seconds for keep-alive and 180 seconds for hold-time.
If you need fast BGP convergence, you can use any
value in these supported ranges: 6-60 seconds for keep-
alive, and 18-180 seconds for hold-time.
Required IAM Policy

To work with Networking resources such as dynamic routing gateways (DRGs), VCNs, and
virtual circuits, you need to have a user login to the Console, and your user needs sufficient
authority (by way of an IAM policy) to perform all the instructions below. If your user is in the
Administrators group, you have the required authority.
If your user is not, then a policy like this would generally cover all the Networking resources:
To only create and manage a virtual circuit, you would need a policy like this:
Allow group VirtualCircuitAdmins to manage drgs in tenancy
Allow group VirtualCircuitAdmins to manage virtual-circuits in tenancy
The first statement (to manage DRGs) is necessary only for private virtual circuits.
For more information, see Getting Started with Policies and Common Policies.
Network Design for Redundancy

This section gives guidelines on how to design your network for redundancy so that it meets
requirements for the Oracle Cloud Infrastructure FastConnect Service-Level Agreement
(SLA).

In general, you should design your network with both of these in mind:
l Regularly scheduled maintenance by Oracle, your provider, or your own organization.

l Unexpected failures on the part of Oracle, your provider, or you own networking
components. Failures are rare but need to be planned for.
For redundancy, Oracle provides:
l Multiple FastConnect locations within each metro area

l Multiple routers in each FastConnect location
l Multiple physical circuits in each FastConnect location
Oracle handles redundancy of the routers and physical circuits in the FastConnect locations.
You should then handle redundancy of the physical connection between your existing network
and the Oracle provider. To do that, create two virtual circuits. Ensure that each runs on a
different physical network connection to the provider, and goes to a different FastConnect
location in the same metro area. Both virtual circuits go to the same DRG (if they're private
virtual circuits). You'll have two separate BGP sessions from your edge to Oracle (one per
virtual circuit). See the following diagram. An active/active configuration for routing traffic
across the two connections is recommended and supported by Oracle.


Getting Started with FastConnect

The following flow chart shows the overall process of setting up FastConnect.
Also see the sequence diagram in To get the status of your virtual circuit.
Task 1: Learn and plan

If you haven't yet, walk through the planning in Before Getting Started: Learn and Plan. Also

see Network Design for Redundancy.
Task 2: Set up connection to the Oracle provider

If you haven't already, start the process of ordering the connection from the Oracle provider,
setting it up, and then testing it with the provider. It can take some time, depending on the
provider.
Task 3: Set up a DRG (private peering only)

Summary: If you plan to use a private virtual circuit, you need a DRG. If you haven't already,
use the Oracle Cloud Infrastructure Console at https://console.us-ashburn-1.oraclecloud.com
to set up a DRG, attach it to your VCN, and update routing in your VCN to include a route rule
to send traffic to the DRG. It's easy to forget to update the route table. Without the route rule,
no traffic flows.
Instructions:
l To create a dynamic routing gateway

l To attach a dynamic routing gateway to a cloud network
l To update a route table
Task 4: Set up your virtual circuit(s)

Summary: Create a virtual circuit in the Oracle Console. If your network design includes
more than one virtual circuit, complete the following steps for each one.
Instructions:
Repeat the following steps for each virtual circuit you want to create.
1. In the Console, confirm you're viewing the compartment that you want to work in. If
you're not sure which one, use the compartment that contains the DRG that you'll

connect to (for a private virtual circuit). This choice of compartment, in conjunction with
a corresponding IAM policy, controls who has access to the virtual circuit you're about
to create.
2. Click Networking, and then click FastConnect.
The resulting FastConnect page is where you'll create a new connection and later
return to when you need to manage the connection.
3. Click Create Connection.
4. Select Connect via provider and choose the provider from the list.
The resulting dialog box shows the information required to set up the virtual circuit.
5. Enter the following for your virtual circuit:
l Name: A friendly name that helps you keep track of your virtual circuits. The
value does not need to be unique across your virtual circuits, and you can change
it later. Avoid entering confidential information.
l Create in Compartment: Leave as is (the compartment you're currently
working in).
6. Choose the virtual circuit type (private or public). A private virtual circuit is for private
peering (where your existing network receives your VCN's private IP addresses). A
public virtual circuit is for public peering (where your existing network receives the
Oracle Cloud Infrastructure regional public IP addresses). Also see Uses for
FastConnect.
l For a private virtual circuit, enter the following:
o Dynamic Routing Gateway Compartment: Select the compartment
where the DRG resides (it should already be selected).
o Dynamic Routing Gateway: Select the DRG to route the FastConnect
traffic to.
o Provisioned Bandwidth: Choose your desired value. If your bandwidth
needs increase later, you can update the virtual circuit to use a different
value (see To edit a virtual circuit).

If your BGP session goes to Oracle (see Provider Scenario: BGP Session to Either
Oracle or the Provider), the dialog box includes additional fields for the BGP
session:
o Customer BGP IP Address: The BGP peering IP address for your edge
router, with either a /30 or /31 subnet mask.
o Oracle BGP IP Address: The BGP peering IP address you want to use for
the DRG, with either a /30 or /31 subnet mask.
o Customer BGP ASN: The public or private ASN for your network.
l For a public virtual circuit, enter the following:
o Customer BGP ASN: The public ASN for your network. Present only if your
BGP session goes to Oracle (see Provider Scenario: BGP Session to Either
Oracle or the Provider). Note that Oracle specifies the BGP IP addresses for
a public virtual circuit.
o Public IP Prefixes: The public IP prefixes that you want Oracle to receive
over the connection (each one must be /24 or less specific). You can enter a
comma-separated list of prefixes, or one per line.
7. Click Continue.
The virtual circuit is created. Its OCID and a link to the provider's portal are displayed in
the resulting confirmation dialog box. The OCID is also available on the main
FastConnect page and with the other virtual circuit details.
8. Copy and paste the OCID to another location. You give it to your provider in the next
task.
9. Click Close.

The virtual circuit is listed on the FastConnect page. You can click the virtual circuit to see the
full set of details. These items indicate the status of the connection:
l Provider State: Whether the provider is aware of your request to create a virtual
circuit and is provisioning it from their end. At this point, the value is INACTIVE.
l Lifecycle State: The current status of the virtual circuit during the time it's being set
up. At this point, the value is PENDING_PROVIDER.
l Large "VC" icon: While the virtual circuit is still being set up, this large, colored icon
also indicates the Lifecycle State (for example, PENDING_PROVIDER). After the
Lifecycle State switches to PROVISIONED, this icon switches to indicate the state of the
virtual circuit's BGP session (either green/UP or red/DOWN).
Tip
For a virtual circuit where your BGP session goes to the

Oracle provider, the BGP session state icon for the
virtual circuit reflects the status of the separate BGP
session between the Oracle provider and Oracle. For
reference, see Provider Scenario: BGP Session to Either
Oracle or the Provider.

Also see the diagram in To get the status of your virtual circuit.
Task 5: Give the provider information about the virtual circuit(s)

Summary: Provide the OCID of each virtual circuit you created, along with any other
information the provider requests. The provider configures each virtual circuit on their end to
complete the connectivity.
Instructions for AT&T

You don't need to provide AT&T the OCID of your virtual circuit. Instead, AT&T and Oracle use
other information to coordinate the provisioning of the virtual circuit. Follow these steps:
1. Work with your AT&T account team to sign up for NetBond for Cloud services.
In return, you receive a welcome letter with credentials for the AT&T Cloud Services
Portal.
2. Sign in to the AT&T Cloud Services portal and create one Virtual Network Connection
(VNC). You must provide these items: name of AT&T MPLS VPN, region, free-form name
for the VNC, and a minimum bandwidth commitment.

3. Inside the VNC, create a VLAN. You must provide a /29 address space and free-form
name.
In return, you receive a Service Key for AT&T NetBond for Cloud.
4. Give Oracle the Service Key you received in the preceding step. To do this, create a
service request at My Oracle Support.
Oracle uses the Service Key that you provided to provision the virtual circuit(s). The process
takes typically 1-2 business days. During that time, the virtual circuit's Provider State
changes to ACTIVE, and the Lifecycle State changes to PROVISIONING. When the virtual
circuit is completely set up, the Lifecycle State switches to PROVISIONED.
Instructions for BT Cloud Connect

1. Contact your BT account manager to order Oracle Cloud Infrastructure FastConnect.
2. Provide the OCID of your virtual circuit.
BT contacts Oracle, and together they provision the virtual circuit. During that time, the
virtual circuit's Provider State changes to ACTIVE, and the Lifecycle State changes to
PROVISIONING. When the virtual circuit is completely set up, the Lifecycle State switches
to PROVISIONED.
Instructions for Equinix Cloud Exchange

1. Go to the Equinix Cloud Exchange portal and sign in.
2. Click the Create Connection tab and select the following:
l Metro: Your desired location (for example, Ashburn).
l Service: Oracle FastConnect - Oracle Cloud Infrastructure (Layer 2 Connection)
3. In the Buyer-side VLAN and Port section, enter a friendly name for the connection,
the physical connection you want to use (the Buyer-side Port), and the VLAN ID.

4. In the Additional Buyer-side Information section, enter your ASN and the IP
address you specified for Oracle's side of the BGP peering session.
5. In the Seller-side Information section, enter the OCID for the virtual circuit.
6. Choose a speed for the connection.
7. Enter the requested email address and click Create Connections.
If your network design includes a second physical connection and virtual circuit for
redundancy, repeat the steps above with the second port you've set up with Equinix Cloud
exchange and the second virtual circuit.
Oracle receives an email and then provisions the virtual circuit(s). The process takes typically
1-2 business days. During that time, the virtual circuit's Provider State changes to ACTIVE,
and the Lifecycle State changes to PROVISIONING. When the virtual circuit is completely
set up, the Lifecycle State switches to PROVISIONED.
Instructions for Interxion CloudConnect

1. Go to the Interxion portal and sign in.
2. Create a new Cloud Connect.
3. Fill in the requested contact information.
4. For the Cloud Service Details, enter the following:
l Cloud Service Provider: Oracle
l Cloud Service Offer: Oracle FastConnect
l Cloud Service Location: Where you're connecting
l Bandwidth: Your desired bandwidth
l OCID: The OCID for the virtual circuit
5. Select a Cloud Access Port to use for the virtual circuit, and fill in the details for your
Cloud Access Port.
6. Accept and confirm your order. You'll get a confirmation email.

If your network design includes a second Cloud Access Port and virtual circuit for redundancy,
repeat the preceding steps with the second Cloud Access Port you've set up with Interxion and
the second virtual circuit.
On the Oracle Console, you will soon see the virtual circuit's Provider State change to
ACTIVE. The Lifecycle State will also change to PROVISIONING. Oracle's system will then
complete the virtual circuit setup, and the Lifecycle State will shortly switch to
PROVISIONED. For more information, see the diagram in To get the status of your virtual
circuit.
Instructions for Megaport

1. Go to the Megaport console and sign in.
2. Locate your existing Megaport and click + Connection to add a connection. If you
haven't begun the process of setting up a Megaport yet, you need to start that first and
then add the connection to it.
3. Click VXC to Cloud and click the icon for Oracle.
4. Enter the OCID for the virtual circuit and choose which Oracle CloudTarget Port (that is,
which building) to use for the virtual circuit.
If your network design includes a second Megaport and virtual circuit for redundancy, repeat
the preceding steps with the second Megaport you've set up and the second virtual circuit.
Make sure to choose the other building when specifying the Oracle CloudTarget Port for the
virtual circuit.
On the Oracle Console, you will soon see the virtual circuit's Provider State change to
ACTIVE. The Lifecycle State will also change to PROVISIONING. Oracle's system will then
complete the virtual circuit setup, and the Lifecycle State will shortly switch to
PROVISIONED. For more information, see the diagram in To get the status of your virtual
circuit.

Instructions for Orange Business Services Business VPN Galerie

1. Contact your Orange Business Services account manager to order Oracle Cloud
Orange Business Services contacts Oracle, and together they provision the virtual circuit.
During that time, the virtual circuit's Provider State changes to ACTIVE, and the Lifecycle
State changes to PROVISIONING. When the virtual circuit is completely set up, the Lifecycle
State switches to PROVISIONED.
Instructions for Tata IZO Private Connect

1. Contact your Tata account manager to order Oracle Cloud Infrastructure FastConnect.
Tata contacts Oracle, and together they provision the virtual circuit. During that time, the
virtual circuit's Provider State changes to ACTIVE, and the Lifecycle State changes to
PROVISIONING. When the virtual circuit is completely set up, the Lifecycle State switches
to PROVISIONED.
Instructions for Verizon SCI

1. Contact your Verizon account manager to order Verizon SCI Connectivity for Oracle
Cloud Infrastructure: FastConnect. If you need help finding your Verizon account
manager, see http://www.verizonenterprise.com/Support/contact.
2. Provide the following information to Verizon:
l The location where Oracle FastConnect is provisioned (for example, IAD)
l The OCID for your virtual circuit
l FastConnect OCI: Private Peering as the SCI Partner Service Description

Verizon then works with you to determine the best time to activate the service. At the
designated time, your Verizon account manager provisions the service with the OCID of
your virtual circuit and verifies the service has been provisioned. You then receive an
email from Verizon with network configuration information.
3. If setting up FastConnect in the London (LHR) region: Give Oracle the network
configuration information you received. To do this, create a service request at My
Oracle Support.
Oracle uses the network configuration information to provision the virtual circuit(s). The
process takes typically 1-2 business days. During that time, the virtual circuit's Provider
State changes to ACTIVE, and the Lifecycle State changes to PROVISIONING. When the
virtual circuit is completely set up, the Lifecycle State switches to PROVISIONED.
Task 6: Configure your edge

If your BGP session goes to Oracle: (see Provider Scenario: BGP Session to Either Oracle
or the Provider), configure your edge router(s) to use the BGP peering information (see
General Requirements). Oracle's BGP ASN is 31898. By default, Oracle uses the default BGP
timers of 60 seconds for keep-alive and 180 seconds for hold-time. If you need fast BGP
convergence, you can use any value in these supported ranges: 6-60 seconds for keep-alive,
and 18-180 seconds for hold-time. Also configure the router(s) for redundancy according to
the network design you decided on earlier (see Network Design for Redundancy). After you
successfully configure the BGP session, the virtual circuit's BGP session state switches to UP.
If your BGP session instead goes to the Oracle provider: You still need to configure
your router(s) if you haven't already. You may need to contact your provider to get the
required BGP peering information. This BGP session must be up and running for FastConnect
to work. Also configure your edge router(s) for redundancy according to the network design
you decided on earlier (see Network Design for Redundancy).

Important
If this is a public virtual circuit, Oracle's public IP

addresses are advertised over both FastConnect and
your connection with your Internet Service Provider
(ISP). Make sure to give higher preference to
FastConnect over your ISP.
Task 7: Check light levels

Confirm the light levels are good for each of your physical network connections to the
provider. Don't proceed until they are.
Task 8: Confirm your interfaces are up

Confirm your side of the interfaces for the connections to the provider are up. Don't proceed
until they are.
BGP Session Goes to Oracle
Task 9a: Ping the Oracle BGP IP address

For each virtual circuit, ping the Oracle BGP IP address assigned to the virtual circuit. Check
the error counters and look for any dropped packets. Don't proceed until you can successfully
ping this IP address without errors.
Task 9b: Confirm the BGP session is established

For each virtual circuit, confirm the BGP session is in an established state. When it is, the
connection is ready to test (see Task 11: Test the connection).

BGP Session Goes to the Provider
Task 10a: Ping the provider's edge

For each virtual circuit, ping the provider's edge. Check the error counters and look for any
dropped packets. Don't proceed until you can successfully ping the provider's edge without
errors.
Task 10b: Confirm the BGP session is established

Confirm the BGP session you have with the provider is in an established state. Don't proceed
until it is.
Task 10c: Ping the Oracle BGP IP address

For each virtual circuit, ping the Oracle BGP IP address (which you can get from the provider).
Check the error counters and look for any dropped packets. When you can successfully ping
this IP address without errors, the connection is ready to test.
Task 11: Test the connection

For a private virtual circuit: You should be able to launch an instance in your VCN and
access it (for example, with SSH) from a host in your existing private network. See Launching
an Instance. If you can, your FastConnect private virtual circuit is ready to use.
For a public virtual circuit:
1. Make sure that Oracle has successfully verified at least one of the public prefixes you've
submitted. You can see the status of each prefix by viewing the virtual circuit's details in
the Console. When one of the prefixes has been validated, Oracle starts advertising the
regional OCI public addresses over the connection.
2. Launch an instance with a public IP address.

3. Ping the public IP address from a host in your existing private network. You should see
the packet on the FastConnect interface on the virtual circuit. If you do, your
FastConnect public virtual circuit is ready to use. However, remember that only the
public prefixes that Oracle has successfully verified so far are advertised on the
connection.
Managing Your Virtual Circuit
To get the status of your virtual circuit

1. In the Console, go to Networking, and then click FastConnect to view your list of
connections.
2. Click the virtual circuit you're interested in to view its details.
The following diagram shows the different states of the virtual circuit when you're setting it
up.


To edit a virtual circuit

You can change these items for a virtual circuit:
l The name
l The bandwidth
l Which DRG it uses (for a private virtual circuit)
l The public IP prefixes (for a public virtual circuit)
l Depending on the situation, you might also have access to the BGP session information
for the virtual circuit and thus can change it.
Important
If your virtual circuit is working and in the

PROVISIONED state before you edit it, be aware that
changing any of the properties besides the name,
bandwith, and public prefixes (for a public virtual
circuit) causes the virtual circuit's state to switch to
PROVISIONING and may cause the related BGP
session to go down. After Oracle re-provisions the
virtual circuit, its state returns to PROVISIONED. Make
sure you confirm that the associated BGP session is
back up.
If you change the public IP prefixes for a public virtual

circuit, the BGP session and virtual circuit status is
unaffected. However, the overall FastConnect status
may change to IP CHECK IN PROGRESS or IP CHECK
FAILED. Oracle begins advertising a new IP prefix over
the connection only after verifying your ownership of it.

connections.
2. Select the compartment where the connection resides, and then click the connection to
view its details.
3. Click the virtual circuit to view its details.
4. Click Edit and make your changes.
5. Click Save.
To terminate a virtual circuit
Important
Also terminate the connection with the provider, or else

the provider may continue to bill you.
connections.
view its details.
3. Click the virtual circuit to view its details.
4. Click Delete.
The virtual circuit's Lifecycle State changes to TERMINATING and then to TERMINATED.
To manage public IP prefixes for a public virtual circuit

For general information about the prefixes, see Logical Connection: Public Virtual Circuit.

You can specify your public IP prefixes when you create the virtual circuit. See Task 4: Set up
your virtual circuit(s).
You can add or remove public IP prefixes later after creating the virtual circuit. See To edit a
virtual circuit. If you add a new prefix, Oracle first verifies your company's ownership before
advertising it across the connection. If you remove a prefix, Oracle stops advertising the
prefix within a few minutes of your editing the virtual circuit.
You can view the state of Oracle's verification of a given public prefix by viewing the virtual
circuit's details in the Console. Here are the possible values:
l IP CHECK IN PROGRESS: Oracle is in the process of verifying your organization's

ownership of the prefix.
l IP CHECK FAILED: Oracle could not verify your organization's ownership. Oracle will not
advertise the prefix over the virtual circuit.
l IP CHECK COMPLETED: Oracle successfully verified your organization's ownership.
Oracle is advertising the prefix over the virtual circuit.
FastConnect: Colocation with Oracle

This topic is for customers who are colocated with Oracle in a FastConnect location. For
general information about FastConnect, see FastConnect Overview. If you instead have a
relationship with an Oracle provider, see FastConnect: With an Oracle Provider.
Before Getting Started: Learn and Plan

Here are basic things you need to do before getting started with FastConnect:
l FastConnect concepts: Make sure you're familiar with the basic concepts covered in
FastConnect Overview.
l Limits increase: You must ask Oracle to increase your account limits for cross-
connects and virtual circuits. By default, these limits are initially set to 0, and a request
to create one of these resources will fail. For instructions, see Requesting a Service

Limit Increase. In your request, make sure to indicate the region where you need the
resources. It can take a couple of business days for the limit increase to take effect.
l Requirements: Review the hardware and routing requirements.
l Tenancy setup and compartment design: If you haven't yet, set up your tenancy.
Think about who needs access to Oracle Cloud Infrastructure and how. For more
information, see "Setting Up Your Tenancy" in the Oracle Cloud Infrastructure Getting
Started Guide. Specifically for FastConnect, see Required IAM Policy to understand the
policy required to work with FastConnect components.
l Cloud network design: Design your virtual cloud network (VCN), including how you
want to allocate your VCN's subnets, define security list rules, define route rules, set up
load balancers, and so on. For more information, see Overview of Networking.
l Redundancy: Think through your overall redundancy model to ensure your network
can handle planned maintenance by Oracle or your organization, and unexpected
failures of the various components.
l Public IP prefixes: If you plan to set up a public virtual circuit, get the list of the
public IP prefixes that you want to use with the connection. Oracle must validate your
organization's ownership of each of the prefixes before advertising each one over the
connection.
l Cloud network setup: Set up your VCN, subnets, DRG, security lists, IAM policies,
and so on, according to your design. For instructions on how to set up the connection
between your VCN and existing network, see Getting Started with FastConnect.
Hardware and Routing Requirements for Colocation

For the cross-connect group and cross-connects:
l Ethernet: 10 GbE
l Fiber type: 1310 NM Single Mode
l Signal loss: <-12 dB
l Optics: 10G LR
l Fiber redundancy: Multiple 10GE with device-level redundancy

l Minimum capacity: 2 x 10 GbE

l LAG protocol: LACP with short timers (3 @ 1s)
l VLAN tagging: 802.1q (single tag)
l VLAN range: 100-4094 (VLANs are assigned by you)
l Maximum interface MTU: 9196 (include 4-byte FCS trailer)
For routing:
l IP addressing supported: IPv4

l P2P IP addresses:
o For public virtual circuits, Oracle specifies the IP addresses.
o For private virtual circuits, you specify the addresses (a /30 or /31). You need one
pair of IP addresses per private virtual circuit. If you set up multiple private
virtual circuits that go to the same DRG, you must use a different address on your
edge router for each virtual circuit.
l Maximum IP MTU: 9000
l Routing protocol: BGPv4
l BGP prefix limit: For public virtual circuits: 200 prefixes. For private virtual circuits:
2000 prefixes.
l BGP ASN: 2-byte ASN. Public virtual circuits require a public ASN. Oracle's BGP ASN is
31898.
l BGP keep-alive interval: 60s
l BGP hold-time interval: 180s

Tip
By default, Oracle uses the default BGP timers of 60

seconds for keep-alive and 180 seconds for hold-time.
If you need fast BGP convergence, you can use any
value in these supported ranges: 6-60 seconds for keep-
alive, and 18-180 seconds for hold-time.
Required IAM Policy

To work with Networking resources such as dynamic routing gateways (DRGs), VCNs, virtual
circuits, and cross-connects, you need to have a user login to the Console, and your user
needs sufficient authority (by way of an IAM policy) to perform all the instructions that follow.
If your user is in the Administrators group, you have the required authority.
If your user is not, then a policy like this would generally cover all the Networking resources:
To only create and manage cross-connects, cross-connect groups, and virtual circuits, you
would need a policy like this:
Allow group FastConnectAdmins to manage drgs in tenancy
Allow group FastConnectAdmins to manage cross-connects in tenancy
Allow group FastConnectAdmins to manage cross-connect-groups in tenancy
Allow group FastConnectAdmins to manage virtual-circuits in tenancy
The first statement (to manage DRGs) is necessary only for private virtual circuits.
For more information, see Getting Started with Policies and Common Policies.

Getting Started with FastConnect

The following flow chart shows the overall process of setting up FastConnect.

Task 1: Learn and plan

If you haven't yet, walk through the planning in Before Getting Started: Learn and Plan.
Task 2: Set up a DRG (private peering only)

Summary: If you plan to use a private virtual circuit, you need a DRG. If you haven't already,
use the Oracle Cloud Infrastructure Console at https://console.us-ashburn-1.oraclecloud.com
to set up a DRG, attach it to your VCN, and update routing in your VCN to include a route rule
to send traffic to the DRG. It's easy to forget to update the route table. Without the route rule,
no traffic will flow.
Instructions:
l To create a dynamic routing gateway

l To attach a dynamic routing gateway to a cloud network
l To update a route table
Task 3: Set up your cross-connect group and cross-connect(s)

Summary: Create a connection in the Console, which consists of a cross-connect group that
contains at least one cross-connect.
Instructions:
1. In the Console, confirm you're viewing the compartment that you want to work in. If
you're not sure which one, use the compartment that contains the DRG that you'll
connect to (for a private virtual circuit). This choice of compartment, in conjunction with
a corresponding IAM policy, controls who has access to the cross-connect group and
cross-connect(s) you're about to create.
2. Click Networking, and then click FastConnect.
The resulting FastConnect page is where you'll create a new connection and later
return to when you need to manage the connection and its components.

3. Click Create Connection.

4. Select the radio button for Colocate with Oracle and click Continue.
In the resulting dialog box, you'll create a cross-connect group with up to three cross-
connects in it. If you need more cross-connects in the group, you can add them later.
You can have a maximum of eight cross-connects in a group.
l Name: A friendly name that helps you keep track of this connection. The cross-
connect group will use this name. Each cross-connect in this group will also use
this name, but with a hyphen and number appended (for example, MyName-1,
MyName-2, and so on). You can't change the name later. Avoid entering
l Create in Compartment: Leave as is (the compartment you're currently
working in).
l Number of cross-connects: Select the number of individual cross-connects to
create in the cross-connect group. In the Console, you can create three. If you
need more, you can add more cross-connects later (total eight in a cross-connect
group).
l Port speed: All cross-connects must use a 10 Gbps port speed.
l Physical location: Select the FastConnect location for this cross-connect group.
l Cross-Connect Group Proximity: Appears only if you have one or more
existing cross-connect groups in this FastConnect location. Here you may
optionally specify whether you want the new cross-connect group to be on the
same or different router than one of your other cross-connect groups.

6. Click Continue.
The new connection is created and listed on the FastConnect page. Click it to see the
connection details, which includes the status of each of the components (the cross-
connect group, cross-connect(s), and later the virtual circuit(s)). The following
screenshot shows the connection details:
7. Click each cross-connect to view its details (MyConnection-1 in the preceding

screenshot), and then view and print the cross-connect's Letter of Authorization (LOA).
You need to submit it with your cabling request at the FastConnect location in the next
step.

Summary of status icons:
l FastConnect (FC) icon: The large icon in the top-left corner. It shows the general
status of the overall FastConnect connection and whether you need to take action. At
this point, the FC status will be ACTION REQUIRED (see the next task).
l Cross-connect group (CCG) icon: The icon near the middle of the page. It shows the
status of the cross-connect group itself. At this point, the CCG status will be PENDING
PROVISIONING.
l Cross-connect (CC) icon: The icon on the right side of the page. It shows the status
of a given cross-connect. At this point, the CC status will be PENDING CUSTOMER.
Later, when you add a virtual circuit to your provisioned cross-connect group, under the CCG
icon there will be a VC icon that shows the status of the virtual circuit.
Task 4: Set up cabling in the FastConnect location

Submit the LOA(s) from the preceding task and request cabling at the FastConnect location.
Each LOA is valid for a limited time. The details are printed on the LOA.

Task 5: Check light levels

Confirm from your side that the light levels for each physical connection (cross-connect) are
good (> -15 dBm). Don't proceed until they are.
In the Console, you can see the light levels that Oracle detects by viewing the details of the
cross-connect and clicking Light Levels, as shown in the following screenshot:
Task 6: Confirm your interfaces are up

Confirm your side of the interfaces for each physical connection (cross-connect) are up. Don't
proceed until they are.
In the Console, you can see the status of Oracle's side of the interfaces (up or down) by
viewing the details of the cross-connect and clicking Light Levels.
Task 7: Activate the cross-connect(s)

Summary: When your physical connection(s) in the FastConnect location are set up and
ready to use, return to the Oracle Console and activate the cross-connect(s) that you set up
earlier. This task informs Oracle that your physical network connection is ready. Oracle will

then complete the router configuration for each cross-connect.
Instructions:
1. In the Console, click Networking, and then click FastConnect.

view its details. The FC icon is ACTION REQUIRED.
3. Click the cross-connect to view its details, and then click Activate.
If you have other cross-connects in this group that are ready to use, wait for the first to be
provisioned, and then activate the next one. Only one cross-connect can be activated and then
provisioned in a group at a time.

l FastConnect (FC) icon: The FC status remains as ACTION REQUIRED to indicate that
you have another action to take (see the next task).
l Cross-connect group (CCG) icon: The CCG status switches to PROVISIONED to
indicate that the cross-connect group is ready to use.
l Cross-connect (CC) icon: The CC status switches to PROVISIONING and then changes
to PROVISIONED (typically within one minute).
Task 8: Set up your virtual circuit(s)

Summary: Create one or more virtual circuits for your cross-connect group in the Oracle
Console. The cross-connect group must be in the PROVISIONED state.
Instructions:
1. In the Console, return to the connection you created earlier, and click the Virtual
Circuits tab on the left side of the page.
2. Click Create Virtual Circuit.
In the resulting dialog box, you can add one or more virtual circuits to run on the cross-
connect group.
3. Enter the following for your virtual circuit:
l Name: A friendly name that helps you keep track of your virtual circuits. The
value does not need to be unique across your virtual circuits, and you can change
it later. Avoid entering confidential information.
l Create in Compartment: Select the compartment where you want to create the
virtual circuit. If you're not sure, select the current compartment (where the DRG
resides). This choice of compartment, in conjunction with a corresponding IAM
policy, controls who has access to the virtual circuit.
4. Choose the virtual circuit type (private or public). A private virtual circuit is for private
peering (where your existing network receives your VCN's private IP addresses). A
public virtual circuit is for public peering (where your existing network receives the

Oracle Cloud Infrastructure regional public IP addresses). Also see Uses for
FastConnect.
l For a private virtual circuit, enter the following:
o Dynamic Routing Gateway Compartment: Select the compartment
where the DRG resides (it should already be selected).
o Dynamic Routing Gateway: Select the DRG to route the FastConnect
traffic to.
o Customer BGP ASN: The public or private ASN for your network.
o VLAN: The number of the VLAN to use for this virtual circuit. It must be a
VLAN that is not already assigned to another virtual circuit.
o Customer BGP IP Address: The BGP peering IP address for your edge,
with either a /30 or /31 subnet mask.
o Oracle BGP IP Address: The BGP peering IP address you want to use for
the Oracle edge, with either a /30 or /31 subnet mask.
l For a public virtual circuit, enter the following:
o Customer BGP ASN: The public ASN for your network. Note that Oracle
specifies the BGP IP addresses for a public virtual circuit.
o VLAN: The number of the VLAN to use for this virtual circuit. It must be a
VLAN that is not already assigned to another virtual circuit.
o Public IP Prefixes: The public IP prefixes that you want Oracle to receive
over the connection (each one must be /24 or less specific). You can enter a
comma-separated list of prefixes, or one per line.

5. Click Create.
The virtual circuit is created. Its status is now included on the main connection's details.
l FastConnect (FC) icon: The FC status switches to PROVISIONING briefly while

Oracle's system provisions the virtual circuit. The status then switches to ACTION
REQUIRED if the BGP session between your edge router and DRG is not yet correctly
configured (see the next task), if the VLAN isn't configured correctly, or if there any
other problems.
l Cross-connect group (CCG) icon: The CCG status remains as PROVISIONED.
l Cross-connect (CC) icon: The CC status remains as PROVISIONED.
l Virtual circuit (VC) icon: The virtual circuit's status is PROVISIONING briefly while
Oracle's system provisions the virtual circuit. The status then switches to DOWN if the
BGP session between your edge and Oracle's edge is not yet correctly configured, if the

VLAN isn't configured correctly, or if there any other problems. Otherwise the status
switches to UP.
Task 9: Configure your edge

Configure your edge router(s) to use the BGP information and VLAN for the virtual circuit.
Oracle's BGP ASN is 31898. By default, Oracle uses the default BGP timers of 60 seconds for
keep-alive and 180 seconds for hold-time. If you need fast BGP convergence, you can use any
value in these supported ranges: 6-60 seconds for keep-alive, and 18-180 seconds for hold-
time.
Important
If this is a public virtual circuit, Oracle's public IP

addresses are advertised over both FastConnect and
your connection with your Internet Service Provider
(ISP). Make sure to give higher preference to
FastConnect over your ISP.
Also configure the router for redundancy according to the network design you decided on
earlier. After you successfully configure BGP and the VLAN, the virtual circuit's status will
switch to UP.
l FastConnect (FC) icon: The FC status switches to PROVISIONED when the BGP
session is established. For a public virtual circuit, instead of switching to PROVISIONED,
the status may switch to either IP CHECK IN PROGRESS or IP CHECK FAILED (if one of
your public prefixes failed Oracle's verification). When Oracle successfully verifies all
the prefixes, the FC status switches to PROVISIONED.
l Cross-connect group (CCG) icon: The CCG status remains as PROVISIONED.
l Cross-connect (CC) icon:The CC status remains as PROVISIONED.

l Virtual circuit (VC) icon: The virtual circuit's status switches to UP when the BGP
session is established.
Task 10: Ping the Oracle BGP IP address

Ping the Oracle BGP IP address assigned to the virtual circuit. Check the error counters and
look for any dropped packets. Don't proceed until you can successfully ping this IP address
without errors.
Task 11: Confirm the BGP session is established

For each virtual circuit you set up, confirm the BGP session is in an established state on your
side of the connection.
Task 12: Test the connection

For a private virtual circuit: You should be able to launch an instance in your VCN and
access it (for example, with SSH) from a host in your existing private network. See Launching
an Instance. If you can, your FastConnect private virtual circuit is ready to use.
For a public virtual circuit:
1. Make sure that Oracle has successfully verified at least one of the public prefixes you've
submitted. You can see the status of each prefix by viewing the virtual circuit's details in
the Console. When one of the prefixes has been validated, Oracle starts advertising the
regional OCI public addresses over the connection.
2. Launch an instance with a public IP address.
3. Ping the public IP address from a host in your existing private network. You should see
the packet on the FastConnect interface on the virtual circuit. If you do, your
FastConnect public virtual circuit is ready to use. However, remember that only the
public prefixes that Oracle has successfully verified so far are advertised on the
connection.

Managing Your Connection
To get the status of your connection

connections.
2. Click the connection you're interested in to view its details.
The following screenshot shows an example of the connection details, after you create the
cross-connect group with a single cross-connect:
Here are reasons for particular status values for the overall connection:

ACTION REQUIRED:
l You need to request cabling at the FastConnect location for the cross-connect group you
just created.
l Or, you need to activate a cross-connect (make sure it's ready to use first).
l Or, you need to set up at least one virtual circuit on your cross-connect group to
complete setup for FastConnect.
DOWN:
In general this means you've created a virtual circuit, but configuration is incomplete or
incorrect:
l You need to configure your edge.

l Or, you've configured BGP or the VLAN incorrectly on your edge (make sure to configure
the router to use the BGP and VLAN values assigned to the virtual circuit).
IP CHECK IN PROGRESS:
For public virtual circuits only. This status means Oracle is in the process of verifying the
public prefixes you've submitted. This status is shown if verification of at least one prefix is
still in progress, and no prefixes have failed verification. You can get the status of each
individual prefix you submitted by viewing the virtual circuit's details.
IP CHECK FAILED:
For public virtual circuits only. This means at least one of the public prefixes you've submitted
failed Oracle's verification. That means Oracle will not advertise that prefix over the virtual
circuit.

The following table summarizes the different states of each component involved in the
connection at different points during setup:
Task in Setup FC Icon (overall CCG Icon CC Icon VC Icon

Process connection)
Task 3: Set up ACTION REQUIRED PENDING PENDING N/A

your cross- PROVISIONING CUSTOMER
connect group
and cross-
connect(s)
Task 7: ACTION REQUIRED PROVISIONED PROVISIONED N/A

Activate the
cross-connect
(s)

Task in Setup FC Icon (overall CCG Icon CC Icon VC Icon

Process connection)
Task 8: Set up PROVISIONING > PROVISIONED PROVISIONED PROVISIONING

your virtual PROVISIONED or > DOWN
circuit(s) DOWN
Task 9: DOWN > PROVISIONED PROVISIONED DOWN > UP

Configure your PROVISIONED
edge
For public virtual
circuits, other
possible values
besides
PROVISIONED:
l ACTION
REQUIRED (if
you haven't yet
submitted any
prefixes to
Oracle)
l IP CHECK IN
PROGRESS (if
at least one
prefix is still
being
validated)
l IP CHECK
FAILED (if at
least one prefix
failed)

To add a new cross-connect to an existing cross-connect group

When you first create a cross-connect group in the Console, you're allowed to create three
cross-connects in the group. You can later add more to increase the bandwidth and resiliency
of the group. The total allowed number is eight.
1. Create the new cross-connect in the existing cross-connect group:

a. In the Console, go to Networking, and then click FastConnect.
b. Select the compartment where the connection resides, and then click the
connection to view its details.
c. Click the cross-connect group to view its details.
d. Click Add Cross-Connect to Group.
e. For the Name, enter a friendly name that helps you keep track of this cross-
connect. The value does not need to be unique across your cross-connects. You
cannot change this later in the Console. However, you can change it if you're
using the API.
f. Click Create.
The cross-connect is created. The resulting dialog box has a link to the Letter of
Authorization (LOA). You can get to the LOA again later by viewing the details of
the cross-connect.
g. Click the LOA link and print the LOA. You will need to submit it with your cabling
order in the next step.
h. Click Close.
The overall status of the connection changes to ACTION REQUIRED to indicate that
you have more work to do.
2. Perform tasks 4-7 in Getting Started with FastConnect. In summary, you need to have
the cabling set up for the new cross-connect, validate the light levels and interfaces are
good, and then activate the cross-connect.

After you activate the cross-connect, the status of the overall connection will be
PROVISIONING until Oracle's system provisions the new cross-connect. Then the status will
switch to PROVISIONED.
To edit a virtual circuit

You can change these items for a virtual circuit:
l The name
l The bandwidth
l Which DRG it uses (for a private virtual circuit)
l Which VLAN it uses
l The BGP session information
l The public IP prefixes (for a public virtual circuit)

Important
Notes About Editing a Virtual Circuit
If your virtual circuit is working and in the

PROVISIONED state before you edit it, be aware that
changing any of the properties besides the name,
bandwith, and public prefixes (for a public virtual
circuit) causes the virtual circuit's state to switch to
PROVISIONING and may cause the related BGP
session to go down. After Oracle re-provisions the
virtual circuit, its state returns to PROVISIONED. Make
sure you confirm that the associated BGP session is
back up.
If you change the public IP prefixes for a public virtual

circuit, the BGP session and virtual circuit status is
unaffected. However, the overall FastConnect status
may change to IP CHECK IN PROGRESS or IP CHECK
FAILED. Oracle begins advertising a new IP prefix over
the connection only after verifying your ownership of it.
connections.
view its details.
3. Click Virtual Circuits, and then click the virtual circuit to view its details.
4. Click Edit and make your changes.
5. Click Save.

To terminate a connection, or part of it

To stop being billed for a connection, you must terminate the virtual circuit, cross-connect(s),
and cross-connect group associated with the connection (in that order).
To terminate a virtual circuit

connections.
view its details.
3. Click Virtual Circuits, and then click the virtual circuit to view its details.
4. Click Delete.
The virtual circuit's status changes to TERMINATING and then to TERMINATED.
To terminate a cross-connect
If you have multiple cross-connects to delete in a cross-connect group, wait until the state of
the first one changes to TERMINATED before deleting the next one. Also, you can't delete a
cross-connect if it's the last provisioned cross-connect in a cross-connect group that's being
used by a provisioned virtual circuit.
connections.
view its details.
3. Click the cross-connect you want to delete.

4. Click Delete.
The cross-connect's status changes to TERMINATING and then to TERMINATED.
To terminate a cross-connect group

Prerequisite: The cross-connect group must have no virtual circuits running on it and contain
no cross-connects.
connections.
view its details.
3. Click Cross-Connect Groups, and then click the cross-connect group to view its
details.
4. Click Delete.
The cross-connect group's status changes to TERMINATING and then to TERMINATED.
To manage public IP prefixes for a public virtual circuit

For general information about the prefixes, see Logical Connection: Public Virtual Circuit.
You can specify your public IP prefixes when you create the virtual circuit. See Task 8: Set up
your virtual circuit(s).
You can add or remove public IP prefixes later after creating the virtual circuit. See To edit a
virtual circuit. If you add a new prefix, Oracle first verifies your company's ownership before
advertising it across the connection. If you remove a prefix, Oracle stops advertising the
prefix within a few minutes of your editing the virtual circuit.

You can view the state of Oracle's verification of a given public prefix by viewing the virtual
circuit's details in the Console. Here are the possible values:
l IP CHECK IN PROGRESS: Oracle is in the process of verifying your organization's

ownership of the prefix.
l IP CHECK FAILED: Oracle could not verify your organization's ownership. Oracle will not
advertise the prefix over the virtual circuit.
l IP CHECK COMPLETED: Oracle successfully verified your organization's ownership.
Oracle is advertising the prefix over the virtual circuit.
Network Performance
The content in the sections below apply to Category 7 and Section 3.c of the Oracle PaaS
Oracle Cloud Infrastructure provides a service-level agreement (SLA) for network throughput
between instances in the same availability domain in a virtual cloud network (VCN).
Important
This SLA applies only to bare metal instances.
To meet the SLA, the network throughput for instances within the same availability domain
and VCN must be at least 90% of the stated maximum for at least 99.9% of the billing month.
Network throughput is measured in megabits per second (Mbps) or gigabits per second
(Gbps).
For the stated maximum bandwidth by instance shape, see the "Network Bandwidth" column
in the "Shape" tables.
Testing Methodology
Summary: Launch two bare metal instances in the same availability domain and VCN. Install
and run the iperf3 utility, with one instance as server and the other as client. Look at the

iperf3 bandwidth results to determine your VCN's network throughput.
Instructions:
1. Launch two bare metal instances in the same availability domain in a single VCN.
Designate one as the server and the other as the client. For launch instructions, see
2. Install iperf3 on both instances. Example Linux command:
sudo yum install -y iperf3
3. Enable communication to the server instance on TCP port 5201 (for iperf3):
a. For the subnet that the server instance is in, add a rule to the subnet's security list
to allow stateless ingress traffic on TCP port 5201 from any source IP address
(0.0.0.0/0) and any source port. For instructions, see To update an existing
security list.
b. On the instance itself, open the firewall to allow iperf3 traffic. Example Linux
commands:
sudo firewall-cmd --zone=public --permanent --add-port 5201/tcp
4. Start the iperf3 test:

a. On the server instance, run iperf3 in server mode. Example Linux command:
iperf3 -s
b. On the client instance, run iperf3 in client mode and specify the private IP
address of the server instance. Example Linux command:
iperf3 -c <server_instance_private_ip_address>
5. Look at the iperf3 results on the client instance. The network throughput between the
two instances is shown under "Bandwidth" in the last five lines of the client's iperf3
test output. For example:
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval Transfer Bandwidth Retr
[ 4] 0.00-10.00 sec XX.YY GBytes NN.NN Gbits/sec 752 sender

[ 4] 0.00-10.00 sec XX.YY GBytes NN.NN Gbits/sec receiver
iperf Done.
Frequently Asked Questions

Q: My VCN isn't meeting the bandwidth SLA. What should I do?
A: Make sure that the CPU on the instance isn't loaded heavily with other services or
applications. Confirm this with a utility such as top to look at the average CPU utilization. It
should be less than one.
Troubleshooting
These topics cover some common issues you might run into and how to address them:
l Hanging Connection
l Subnet Deletion
Hanging Connection
This topic covers one of the most common issues seen with communications between your
cloud network and on-premises network: a hanging connection, even though you can ping
hosts across the connection.
Summary of Problem and Solutions
Symptom: Your virtual cloud network (VCN) is connected to your existing on-premises
network via an IPSec VPN, or Oracle Cloud Infrastructure FastConnect. Hosts on one side of
the connection can ping hosts on the other side, but the connection hangs. For example:
l You can SSH to a host across the connection, but after you log in to the host, the
connection hangs.
l You can start a Virtual Networking Computing (VNC) connection, but the session hangs.
l You can start an SFTP download, but the download hangs.

General problem: Path Maximum Transmission Unit Discovery (PMTUD) is probably not
working on one or both sides of the connection. It must be working on both sides of the
connection so that both sides can know if they're trying to send packets that are too large for
the connection and adjust accordingly. For a brief overview of Maximum Transmission Unit
(MTU) and PMTUD, see Overview of MTU and Overview of PMTUD.
Solutions for fixing PMTUD:
1. Make sure your hosts are configured to use PMTUD: If the hosts in your on-
premises network don't use PMTUD (that is, if they don't set the Don't Fragment flag in
the packets), they have no way to discover if they're sending packets that are too large
for the connection. Your instances on the Oracle side of the connection use PMTUD by
default. Do not change that configuration on the instances.
2. Make sure both the VCN security lists and the instance firewalls allow ICMP
type 3 code 4 messages: When PMTUD is in use, the sending hosts receive a special
ICMP message if they send packets that are too large for the connection. Upon receipt
of the message, the host can dynamically update the size of the packets to fit the
connection. However, your instances can't receive these important ICMP messages if
the security lists for the subnet in the VCN and/or the instance firewalls aren't
configured to accept them.

Tip
If you're using stateful security list rules, you don't

need to ensure that your security list has a rule to
allow ICMP type 3 code 4 messages. With stateful
rules, the Networking service tracks the
connections and automatically allows corresponding
ICMP type 3 code 4 messages without needing an
explicit rule to allow them. Only if you're using
stateless rules must you have an explicit ingress
security list rule for ICMP type 3 code 4 messages.
You must also confirm the instance firewalls are set
up correctly.
To check to see if a host is receiving the messages, see Finding Where PMTUD Is
Broken.
3. Make sure your router honors the Don't Fragment flag: If the router doesn't
honor the flag and thus ignores the use of PMTUD, it sends fragmented packets to the
instances in the VCN, which is bad (see Why Avoid Fragmentation?). The VCN's security
lists are most likely configured in such a way that they recognize only the initial
fragment, and the remaining ones are dropped, causing the connection to hang.
Instead, your router should use PMTUD and honor the Don't Fragment flag to determine
the correct size of unfragmented packets to send through the connection.

The parts of the solution are numbered and called out in red italics in the following diagram. It
shows an example scenario with your on-premises network connected to your VCN over an
IPSec VPN.
Keep reading for a brief overview of MTU and PMTUD, and how to check if PMTUD is working
on both sides of the network connection.
Why Avoid Fragmentation?
You may be wondering why you want to avoid fragmentation. First, it adversely affects the
performance of your application. Fragmentation requires reassembly of the fragments and
retransmission if fragments are lost. Reassembly and retransmission require time and CPU
resources.
Second, only the first fragment contains the source and destination port information. This
means the other packets will probably be dropped by firewalls or your VCN's security lists,
which are typically configured to evaluate the port information. For fragmentation to work

with your firewalls and security lists, you would have to configure them to be more
permissive than usual, which is not desirable.
Overview of MTU
The communications between any two hosts across an Internet Protocol (IP) network use
packets. Each packet has a source and destination IP address and a payload of data. Every
network segment between the two hosts has a Maximum Transmission Unit (MTU) that
represents the number of bytes that a single packet can carry.
Across the internet, the MTU is 1500 bytes. This is also true for most home networks and
many corporate networks (and their Wi-Fi networks). Some data centers, including those for
Oracle Cloud Infrastructure, have a larger MTU. The Compute instances use an MTU of 9000
by default. On a Linux host, you can use the ifconfig command to display the MTU of the
host's network connection. For example, here's the ifconfig output from an Ubuntu instance
(the MTU is highlighted in red italics):
ifconfig
ens3 Link encap:Ethernet HWaddr 00:00:17:01:17:83
inet addr:10.0.6.9 Bcast:10.0.6.31 Mask:255.255.255.224
inet6 addr: fe80::200:17ff:fe01:1783/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:9000 Metric:1
For comparison, here's the output from a machine connected to a corporate network:
ifconfig
en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST>
mtu 1500
Notice that its MTU is the more typical 1500 bytes.
If the host is connected through a corporate VPN, the MTU is even smaller, because the VPN
tunnel must encapsulate the traffic inside an IPSec packet and send it across the local
network. For example:
ifconfig
utun0: flags=81d1<UP,POINTOPOINT,RUNNING,NOARP,PROMISC,MULTICAST>
mtu 1300
How do the two hosts figure out how large of a packet they can send to each other? For many
types of network traffic, such as HTTP, SSH, and FTP, the hosts use the Transmission Control

Protocol (TCP) to establish new connections. During the initial three-way handshake between
two hosts, they each send the Maximum Segment Size (MSS) for how large their payload can
be. This is smaller than the MTU. (TCP runs inside the Internet Protocol (IP), which is why it's
referred to as TCP/IP. Segments are to TCP what packets are to IP.)
Using the tcpdump application, you can see the MSS value shared during the handshake.
Here's an example from tcpdump (with the MSS highlighted in red italics):
12:11:58.846890 IP 129.146.27.25.22 > 10.197.176.19.58824: Flags [S.], seq
2799552952, ack 2580095593, win 26844, options [mss 1260,sackOK,TS val
44858491 ecr 1321638674,nop,wscale 7], length 0
The preceding packet is from an SSH connection to an instance from a laptop connected to a
corporate VPN. The local network the laptop uses for its internet connection has an MTU of
1500 bytes. The VPN tunnel enforces an MTU of 1300 bytes. Then when the SSH connection is
attempted, TCP (running inside the IP connection) tells the Oracle Cloud Infrastructure
instance that it supports TCP segments that are less than or equal to 1260 bytes. With a
corporate VPN connection, the laptop connected to the VPN typically has the smallest MTU and
MSS compared to anything it's communicating with across the internet.
A more complex case is when the two hosts have a larger MTU than some network link
between them that is not directly connected to either of them. The following diagram
illustrates an example.

In this example, there are two servers, each directly connected to its own routed network that
supports a 9000-byte MTU. The servers are in different data centers. Each data center is
connected to the internet, which supports a 1500-byte MTU. There is an IPSec VPN tunnel
between the two data centers. That tunnel crosses the internet, so the inside of the tunnel has
a smaller MTU than the internet. In this diagram, the MTU is 1380 bytes.
If the two servers try to communicate (with SSH, for example), during the three-way
handshake, they agree on an MSS around 8960. The initial SSH connection might succeed,
because the maximum packet sizes during the initial SSH connection setup are usually less
than 1380 bytes. When one side tries to send a packet larger than the smallest link between
the two endpoints, Path MTU Discovery (PMTUD) becomes critical.
Overview of PMTUD
Path MTU Discovery is defined in RFC 1191. It works by requiring the two communicating
hosts to set a Don't Fragment flag in the packets they each send. If a packet from one of these
hosts reaches a router where the egress (or outbound) interface has an MTU smaller than the
packet length, the router drops that packet. The router also returns an ICMP type 3 code 4
message to the host. This message specifically says "Destination Unreachable, Fragmentation
Needed and Don't Fragment Was Set" (defined in RFC 792). Effectively the router tells the
host: "You told me not to fragment packets that are too large, and this one's too large. I'm not
sending it." The router also tells the host the maximum size packets allowed through that
egress interface. The sending host then adjusts the size of its outbound packets so they're
smaller than the value the router provided in the message.
Here's an example that shows the results when an instance tries to ping a host (8.8.8.8) over
the internet with an 8000-byte packet and the Don't Fragment flag set (that is, with PMTUD in
use). The returned ICMP message is highlighted in red italics:
ping 8.8.8.8 -M do -s 8000
PING 8.8.8.8 (8.8.8.8) 8000(8028) bytes of data.
From 4.16.139.250 icmp_seq=1 Frag needed and DF set (mtu = 1500)
The response is exactly what's expected. The destination host is across the internet, which
has an MTU of 1500 bytes. Even though the sending host's local network connection has an
MTU of 9000 bytes, the host can't reach the destination host with the 8000-byte packet and
gets an ICMP message accordingly. PMTUD is working correctly.

For comparison, here's the same ping, but the destination host is across an IPSec VPN tunnel:
ping 192.168.6.130 -M do -s 8000
Here the VPN router sees that to send this packet to its destination, the outbound interface is a
VPN tunnel. That tunnel goes across the internet, so the tunnel must fit inside the internet's
1500-byte MTU link. The result is that the inside of the tunnel only allows packets up to 1360
bytes (which the router then lowered to 1358, which can make things more confusing).
Finding Where PMTUD Is Broken
If PMTUD isn't working somewhere along the connection, you need to figure out why and
where. Typically it's because the ICMP type 3 code 4 packet (from the router with the
constrained link that can't fit the packet) never gets back to the sending host. This can happen
if there's something blocking that kind of traffic between the host and the router. And it can
happen on either side of the VPN tunnel (or other constrained MTU link).
TRY PINGING FROM EACH S IDE OF THE CONNECTION
To troubleshoot the broken PMTUD, you must determine if PMTUD is working on each side of
the connection. In this scenario, let's assume the connection is an IPSec VPN.
How to ping: Like in Overview of PMTUD, ping a host on the other side of the connection with
a packet that you know is too large to fit through the VPN tunnel (for example, 1500 bytes or
larger). Depending on which operating system the sending host uses, you might need to
format the ping command slightly different to ensure the Don't Fragment flag is set. For both
Ubuntu and Oracle Linux, you use the -M flag with the ping command.
Here's information about the -M flag:

-M pmtudisc_opt
Select Path MTU Discovery strategy. pmtudisc_option may be either do
(prohibit fragmentation, even local one), want (do PMTU discovery, fragment
locally when packet size is large), or dont (do not set DF flag).

Here's an example ping (with the -M flag and the resulting ICMP message highlighted in red
italics)
ping -M do -s 1500 192.168.6.130
Good: PMTUD is working

If the result includes the line "From x.x.x.x icmp_seq=1 Frag needed and DF set (mtu =
xxxx)", then PMTUD is working on that side of the tunnel. Note that the source address of the
ICMP message is the public IP address of the tunnel the traffic is trying to go out (for example
129.146.13.49 in the preceding Ubuntu example).
Make sure to also ping from the other side of the connection to confirm PMTUD is working
from that side. Both sides of the connection must recognize that there is a tunnel between
them that can't fit the large packets.
Bad: If you're testing your side of the connection and the ping succeeds
If you're sending the ping from a host in your on-premises network, and the ping succeeds,
that probably means your edge router is not honoring the Don't Fragment flag. Instead the
router is fragmenting the large packet. The first fragment reaches the destination host, so the
ping succeeds, which is misleading. If you try to do more than just ping, the fragments after
the first get dropped, and the connection will hang.
Make sure to configure your router to honor the Don't Fragment flag. The router's
default configuration is to honor it, but someone might have changed the default.
Bad: If you're testing the VCN side of the connection and you don't see the
ICMP message
When testing from the VCN side of the connection, if you don't see the ICMP message in the
response, there is probably something dropping the ICMP packet before it reaches your
instance.

There could be two issues:
l Security list: The Networking security list could be missing an ingress rule that allows
ICMP type 3 code 4 messages to reach the instance. This is an issue only if you're using
stateless security list rules. If you're using stateful rules, your connections are tracked
and the ICMP message is automatically allowed without needing a specific security list
rule to allow it. If you're using stateless rules, make sure that the subnet the
instance is in has a security list with an ingress rule that allows ICMP traffic
type 3 code 4 from source 0.0.0.0/0 and any source port. For more information,
see Security Lists, and specifically To update an existing security list.
l Instance firewall: The instance's firewall rules (set in the OS) could be missing a rule
that allows ICMP type 3 code 4 messages to reach the instance. Specifically for a Linux
instance, make sure that iptables or firewalld is configured to allow the ICMP type 3
code 4 messages.
Avoiding the Need for PMTUD
Oracle recommends using PMTUD. However, in some situations it's possible to configure
servers so they don't need to rely on it. Consider the case of the instances in your VCN
communicating across an IPSec VPN to hosts in your on-premises network. You know the
range of IP addresses for your on-premises network. You can add a special route to your
instances that specifies the maximum MTU to use when communicating with hosts in that
address range. The instance-to-instance communication within the VCN still uses an MTU of
9000 bytes.
The following information shows how to set that route on a Linux instance.
The default route table on the instance typically has two routes: the default route (for the
default gateway), and a local route (for the local subnet). For example:
ip route show
default via 10.0.6.1 dev ens3
10.0.6.0/27 dev ens3 proto kernel scope link src 10.0.6.9
You can add another route that points to the same default gateway, but with the address range
of the on-premises network and a smaller MTU. For example, in the following command, the

on-premises network is 1.0.0.0/8, the default gateway is 10.0.6.1, and the maximum MTU
size is 1300 for packets being sent to the on-premises network.
ip route add 1.0.0.0/8 via 10.0.6.1 mtu 1300
The updated route table looks like this:

ip route show
default via 10.0.6.1 dev ens3
1.0.0.0/8 via 10.0.6.1 dev ens3 mtu 1300
10.0.6.0/27 dev ens3 proto kernel scope link src 10.0.6.9
Within the VCN, the instance-to-instance communication continues to use 9000 MTU.
However, communication to the on-premises network uses a maximum of 1300. This example
assumes there's no part of the connection between the on-premises network and VCN that
uses an MTU smaller than 1300.
Important
The preceding commands do not persist if you reboot

the instance. You can make the route permanent by
adding it to a configuration file in the OS. For example,
for Oracle Linux, it's an interface-specific file called
/etc/sysconfig/network-scripts/route-
<interface>. For more information, see the
documentation for your variant of Linux.
Subnet Deletion
A subnet must be empty in order to delete it. In other words, it must contain no instances,
load balancers, or DB systems. You might not be able to see all the resources in a subnet. This
is because subnets can contain resources in multiple compartments, and you might not have
access to all the compartments. For example, the subnet might contain instances that your
team manages but also DB systems that another team manages.

Before you can delete a subnet, you must delete all the instances, load balancers, and DB
systems in the subnet. You might need to contact your tenancy administrator to help you
determine who owns the resources in the subnet.
If the subnet is empty when you try to delete it, its state changes to TERMINATING briefly and
then to TERMINATED. If it's not empty, you instead get an error indicating that there are still
resources that you must delete first.

CHAPTER 15 Object Storage
This chapter explains how to upload, manage, and access data using Object Storage.
Overview of Object Storage

Oracle Cloud Infrastructure offers two distinct storage class tiers to address the need for both
performant, frequently accessed "hot" storage, as well as less frequently accessed "cold"
storage. Storage tiers help you maximize performance where appropriate and minimize costs
where possible.
l Use Object Storage for data to which you need fast, immediate, and frequent access.
Data accessibility and performance justifies a higher price point to store data in the
Object Storage tier.
l Use Archive Storage for data to which you seldom or rarely access, but that must be
retained and preserved for long periods of time. The cost efficiency of the Archive
Storage tier offsets the long lead time required to access the data. For more
information, see Overview of Archive Storage.
About Object Storage

The Oracle Cloud Infrastructure Object Storage service is an internet-scale, high-performance
storage platform that offers reliable and cost-efficient data durability. The Object Storage
service can store an unlimited amount of unstructured data of any content type, including
analytic data and rich content, like images and videos.
With Object Storage, you can safely and securely store or retrieve data directly from the
internet or from within the cloud platform. Object Storage offers multiple management
interfaces that let you easily manage storage at scale. The elasticity of the platform lets you
start small and scale seamlessly, without experiencing any degradation in performance or
service reliability.
Object Storage is a regional service and is not tied to any specific compute instance. You can
access data from anywhere inside or outside the context of the Oracle Cloud Infrastructure, as

long you have internet connectivity and can access one of the Object Storage endpoints.
Authorization and resource limits are discussed later in this topic.
The following list summarizes some of the ways that you can use Object Storage.
BIG DATA/HADOOP SUPPORT
You can use Object Storage as the primary data repository for big data. Object Storage
offers a scalable storage platform that lets you store large data sets and operate
seamlessly on those data sets. The HDFS connector provides connectivity to various big
data analytic engines like Apache Spark and MapReduce. This connectivity enables the
analytics engines to work directly with data stored in Object Storage. For more
information, see Hadoop Support.
BACKUP/ARCHIVE
You can use Object Storage to preserve backup and archive data that must be stored for
an extended duration to adhere to various compliance mandates.
CONTENT REPOSITORY
You can use Object Storage as your primary content repository for data, images, logs, and
video. You can reliably store and preserve this data for a long time, as well as serve this
content directly from Object Storage. The storage scales as your data storage needs
scale.
LOG DATA
You can use Object Storage to preserve application log data so that you can retroactively
analyze this data to determine usage pattern and/or debug issues.
VERY LARGE DATA SETS
You can use Object Storage to store generated application data that needs to be preserved
for future use. Pharmaceutical trials data, genome data, and Internet of Things (IoT) data
are examples of generated application data that you can preserve using Object Storage.

Object Storage Resources

The following summarizes the Object Storage resources. Authorization and resource limits are
discussed later in this topic.
OBJECT
Any type of data, regardless of content type, is stored as an object. The object is
composed of the object itself and metadata about the object. Each object is stored in a
bucket.
BUCKET
A logical container for storing objects. Users or systems create buckets as needed. A
bucket is associated with a single compartment that has policies that determine what
actions a user can perform on a bucket and on all the objects in the bucket.
NAMESPACE
A logical entity that serves as a top-level container for all buckets and objects, allowing
you to control bucket naming within your tenancy. Each tenancy is provided one unique
and uneditable Object Storage namespace that is global, spanning all compartments and
regions. Bucket names must be unique within your tenancy, but the use of a bucket name
by another tenant does not restrict your ability to use the same bucket name within your
tenancy. Within an Object Storage namespace, buckets and objects exist in flat hierarchy,
but you can simulate a directory structure to help navigate a large set of objects (for
example, guitars/fender/stratocaster.jpg, guitars/gibson/lespaul.jpg).
Tip
Note that if your namespace was created based on

your tenancy name, your namespace uses all lower-
case letters (regardless of the presence of capital
letters in your tenancy name). When using the API,
CLI, or SDKs, do not use capital letters in your
namespace string.

COMPARTMENT
A collection of related resources that can be accessed only by those who are explicitly
granted access permission by an administrator. Compartments help you organize
resources and make it easier to control the access to those resources. Object Storage
automatically creates a root compartment when a compartment is provisioned. An
administrator can then create additional compartments within the root compartment and
add access rules for those compartments. A bucket can only exist in one compartment.
Object Storage Features

Object Storage provides the following features:
STRONG CONSISTENCY
When a read request is made, Object Storage always serves the most recent copy of the
data that was written to the system.
DURABILITY
Object Storage is a regional service and is available across all the availability domains
within a region. Data is stored redundantly across multiple storage servers and across
multiple availability domains. Object Storage actively monitors data integrity using
checksums and automatically detects and repairs corrupt data. Object Storage actively
monitors and ensures data redundancy. If a redundancy loss is detected, Object Storage
automatically creates additional data copies.
CUSTOM METADATA
You can define your own extensive metadata as key-value pairs for any purpose. For
example, you can create descriptive tags for objects, retrieve those tags, and sort
through the data.
ENCRYPTION
Object Storage employs 256-bit Advanced Encryption Standard (AES-256) to encrypt

object data on the server. Each object is encrypted with its own key. Object keys are
encrypted with a master encryption key that is frequently rotated. Encryption is enabled
by default and cannot be turned off.

Ways to Access Object Storage

You can access Object Storage using any of the following options, based on your preference
and its suitability for the task you want to complete:
l The Console is an easy-to-use, browser-based interface. When you sign up to use

Oracle Cloud Infrastructure, you receive a customized URL for your organization. For
example, https://console.us-ashburn-1.oraclecloud.com?tenant=CompanyABC. If you
instead use the base URL, you are prompted to specify your tenant (for example,
CompanyABC) on the sign-in page, along with your user name and password.
l The command line interface (CLI) provides both quick access and full functionality
without the need for programming. For more information, see Command Line Interface
(CLI).
l The REST API provides the most functionality, but requires programming expertise. API
Reference and Endpoints provides endpoint details and links to the available API
reference documents. For general information about using the API, see About the API.
l The Oracle Cloud Infrastructure SDKs offer tools to interact with Object Storage without
having to create a framework. For general information about using the SDKs, see SDKs
and Other Tools.
Using Object Storage

If you are ready to use Object Storage, you can find more information in the following topics:
l For instructions on how to create a bucket and store an object in the bucket, see
"Putting Data into Object Storage" in the Oracle Cloud Infrastructure Getting Started
Guide.
l For task documentation related to buckets, see Managing Buckets.
l For task documentation related to objects, see Managing Objects.
l For API reference documentation, see Object Storage Service API.

l For SDK and CLI information, see SDKs and Other Tools.
l For more information about using Archive Storage, see Overview of Archive Storage.

using.
Limits on Object Storage Resources

increase.
l Number of Object Storage namespaces per root compartment: 1

l Maximum size of object metadata: 2 K
Understanding Object Storage Namespaces

Each Oracle Cloud Infrastructure tenant is assigned one unique and uneditable Object Storage
namespace that is global (spanning all regions and compartments). The Object Storage
namespace serves as a top-level container for all buckets and objects and allows you to

control bucket naming within your tenancy. While bucket names must be unique within your
tenancy, your tenancy's bucket names can duplicate the bucket names chosen by other
tenants. The Object Storage namespace is a system-generated string assigned during account
creation. Note that for some older tenancies, the namespace string may be the tenancy name
in all lower-case letters.
The namespace metadata stores the default compartment assignments for the Amazon S3
Compatibility API and the Swift API. For more information, see Viewing and Specifying
Designated Compartments.
Using the Console

To view your Object Storage namespace string, open the Console, and then click the name of
your tenancy in the top-left corner of the page. Your namespace string is listed under Object
Storage Settings.
Note
Object Storage Namespace Is Not Editable
While the Object Storage namespace string is displayed

under Object Storage Settings, you cannot edit the
namespace string. The namespace string appears here
for information only.

Open a command prompt and run the following command to get your Object Storage
namespace:
oci os ns get

Tip
You can use -ns, --namespace, or --namespace-name

for options that require you to specify the Object
Storage namespace string.
For information about using the CLI, see Command Line Interface (CLI). For a complete list of
flags and options available for CLI commands, see CLI Help.
Using the API

Use the GetNamespace operation to get your Object Storage namespace string.
Managing Buckets
In the Oracle Cloud Infrastructure Object Storage service, a bucket is a container for storing
objects in a compartment within an Object Storage namespace. A bucket is associated with a
single compartment. The compartment has policies that indicate what actions a user can
perform on a bucket and all the objects in the bucket.
You cannot nest buckets—a bucket cannot contain other buckets.
Required IAM Policy


Tip
For administrators:
l The policy Let Object Storage admins manage

buckets and objects lets the specified group do
everything with buckets and their associated
objects.
l If you need to write more restrictive policies for
buckets, see Details for Object Storage.
Pre-authenticated requests provides a way to let users access a bucket or an object without
having their own credentials. For example, you can create a request that lets a user upload
backups to a bucket without owning API keys. See Using Pre-Authenticated Requests for
details.
Tagging Resources
Object Storage currently supports applying tags to buckets.
Bucket Names
Unlike other resources, buckets do not have assigned Oracle Cloud Identifiers (OCIDs).
Instead, users define a bucket name when they create a bucket.
Use the following guidelines when naming a bucket:

l Use from 1 to 256 characters.

l Valid characters are letters (upper or lower case), numbers, hyphens, underscores, and
periods.
l Do not include confidential information.
l Make the name unique within the Object Storage namespace.
Object Storage prepends the Object Storage namespace string to the bucket name:
n/<object_storage_namespace>/b/<bucket>
For example: n/ansh8lvru1zp/b/event-photos
Storage Tiers
When you create a bucket, you also decide which tier is appropriate for object storage:
l Use the standard Object Storage tier for data to which you need fast, immediate, and
frequent access. For more information, see Overview of Object Storage.
l Use the Archive Storage tier for data to which you seldom or rarely access, but that
must be retained and preserved for long periods of time. For more information, see
Overview of Archive Storage.
Important
Once set, you cannot change the storage tier in which a

bucket resides.
Public Buckets
When you create a bucket, the bucket is considered a private bucket and the access to the
bucket and its contents requires authentication and authorization. However, Object Storage
supports anonymous, unauthenticated access to a bucket. You make a bucket public by
enabling read access to the bucket.

Important
Carefully assess the business requirement for public

access to a bucket. When you enable anonymous access
to a bucket, users can obtain object metadata,
download bucket objects, and optionally list bucket
contents.
Required Permissions
The following permissions are required to configure a public bucket:
l To enable public access when creating a bucket, use permission BUCKET_CREATE.

l To enable public access for an existing bucket, use permission BUCKET_UPDATE.
Options
When creating a public bucket, you have the following options:
l You can configure the access to allow listing and downloading bucket objects. List and
download access is the default.
l You can configure the access to allow downloading bucket objects only. Users would not
be able to list bucket contents.
Scope and Constraints
Understand the following scope and constraints regarding public access:
l Changing the type of access is bi-directional. You can change a bucket's access from
public to private or from private to public.
l Changing the type of access doesn't affect existing pre-authenticated requests. Existing
pre-authenticated requests still work.

You can enable anonymous public access for new or existing buckets using the Console, CLI,
or an SDK to access the API.
Using the Console
To get a list of buckets

Open the Console, click Storage, and then click Object Storage.
A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one
you're looking for, verify that you’re viewing the correct compartment (select from the list on
the left side of the page).
To create a bucket
1. Open the Console, click Storage, and then click Object Storage.
A list of the buckets in the compartment you're viewing is displayed. If you don’t see the
2. Choose the compartment you want to a create bucket in.
A list of buckets that have already been created is displayed.
4. In the Create Bucket dialog, specify the attributes of the bucket:
l Name: Required. A user-friendly name or description. Avoid entering confidential
information.
l Storage Tier: Select the tier in which you want to store your data. Available tiers
include:
o Standard is the primary default Object Storage tier for storing data to
which you need fast, immediate, and frequent access.

o Archive is a special tier for storing data that is accessed infrequently and
requires long retention periods. For more information, see "Overview of
Archive Storage" in the Oracle Cloud Infrastructure User Guide.
l Tags:Optionally, you can apply tags. If you have permissions to create a
administrator.
The bucket is created immediately and you can add objects to it. Objects added to archive
buckets are immediately archived and must be restored before they are available for
download.
To move a bucket to a different compartment

2. Choose the compartment where the bucket is and find the bucket you want to move to a
different compartment.
3. Click the Actions icon ( ), and then click Change Compartment.
To delete a bucket
You can permanently delete an empty bucket. The bucket cannot contain any objects. For
information on deleting objects from a bucket, see To delete an object from a bucket.
Warning
You cannot recover a deleted bucket.

2. Find the bucket that you want to delete.
To manage tags for a bucket

2. Click the bucket for which you want to manage tags.
ones.
To make a bucket private or public

2. Choose the compartment where the bucket is.
3. Click the Bucket name to see the Bucket Details.
Visibility: shows the current bucket setting, which is Private by default.
4. Click Update Visibility.
5. Select the Visibility you want for the bucket.

6. If you select Public to enable public access, decide if you want to let users list the
bucket contents.
7. Click Save.

To get a list of buckets

Open a command prompt and run oci os bucket list to list buckets in a compartment:
oci os bucket list -ns <object_storage_namespace> --compartment-id <target_compartment_id>
For example:
oci os bucket list -ns ansh8tvru7zp -c
ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz
{
"data": [
{
"compartment-id":
"ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz",
"created-by": "ocid1.user.oc1..example1example2vv7jl3q2lqddxuim7gcidigcnvzz5sfhf4erv5aozzq",
"defined-tags": null,
"etag": "3f06cb1d-2a95-40e3-afa8-example28553",
"freeform-tags": null,
"name": "example_bucket_name",
"namespace": "ansh8tvru7zp",
"time-created": "2018-02-15T23:32:44.147000+00:00"
}
]
}
To include resource tag data, use the --fields tags option:

oci os bucket list -ns <object_storage_namespace> --compartment-id <target_compartment_id> --fields

tags
For example:
oci os bucket list -ns ansh8tvru7zp -c
ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --fields tags
{
"data": [
{
"compartment-id":
"ocid1.compartment.oc1..aaaaaaaahbidr7zkfgqrdgy7uowyar52jpcynooyolyhozwqnkwkmx4g62dq",
"created-by": "ocid1.user.oc1..aaaaaaaaxcg5ztny6vv7jl3q2lqddxuim7gcidigcnvzm5sfhf4erv5aolrq",
"defined-tags": {
"example_tag_namespace_Financials": {
"production": "Unit 5"
},
"example_tag_namespace_Operations": {
"costcenter": "85"
}
},
"etag": "48af18cf-1edd-4b05-9f36-a629d5032260",
"freeform-tags": {
"Project": "prototype 3"
},
"name": "example_bucket_name",
"namespace": "ansh8tvru7zp",
"time-created": "2018-02-27T18:52:16.951000+00:00"
}
]
}

Tip
Note that if a bucket has freeform or defined resource

tags and you do not use the --fields tags option when
performing the bucket list operation, the system returns
null as the value for both freeform and defined tags in
the list representation of the bucket.
To create a standard Object Storage tier bucket

Open a command prompt and run oci os bucket create to create a bucket:
oci os bucket create -ns <object_storage_namespace> --name <bucket_name> --compartment-id <target_
compartment_id>
By default, a bucket is created in the standard Object Storage tier. You can set --storage-
tier explicitly, though it is not required.
Warning
Avoid entering confidential information in bucket name.
A Standard tier bucket is created immediately and you can add objects to it.
To create an Archive tier bucket

Open a command prompt and run oci os bucket create to create a bucket.
To create an Archive tier bucket, you must explicitly set --storage-tier. For example:
oci os bucket create -ns <object_storage_namespace> --name <archivebucket_name> --compartment-id
<target_compartment_id> --storage-tier Archive

Warning
An Archive Storage bucket is created and you can add objects to it. Objects added to Archive
Storage buckets are immediately archived and must be restored before they are available for
download.
To make a bucket private or public

oci os bucket update -ns <object_storage_namespace> --name <bucket_name> --public-access-type
<visibility_setting>
Where <visibility_setting> is "NoPublicAccess", "ObjectReadWithoutList", or "ObjectRead"

and represents the new setting for the bucket.
To create a public bucket that allows listing and downloading bucket objects
oci os bucket create -ns <object_storage_namespace> --name <bucket_name> --public-access-type
ObjectRead -c <compartment_ocid>
Where <compartment_ocid> is a value like:

ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q65flzp3pp2jojdc6rck6copzqck3ukcypxfga
To create a public bucket that allows downloading bucket objects only

oci os bucket create -ns <object_storage_namespace> --name <bucket_name> --public-access-type
ObjectReadWithoutList -c <compartment_ocid>
Where <compartment_ocid> is a value like:

ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q65flzp3pp2jojdc6rck6copzqck3ukcypxfga

To create a bucket with resource tags

You can create standard Object Storage tier or Archive tier buckets with resource tags.
To add resource tags when creating a bucket, open a command prompt and run oci os
bucket create with one or both of the --defined-tags and --freeform-tags options.
The following example syntax creates a standard Object Storage tier bucket with a defined
tag:
compartment_id> --defined-tags <JSON_formatted_defined_tag>
The following example syntax creates a Standard tier bucket with a free-form tag:
compartment_id> --freeform-tags <JSON_formatted_free-form_tag>
Tip
The defined-tags and --freeform-tags options

require that the input be a complex type formatted in
valid JSON. See Passing Complex Input and Using a
JSON File for Complex Input for information JSON
formatting.
Examples of defined tag formatting:

'{"Logistics": {"Procurement": "Madrid Center"}}'
'{"Operations": {"CostCenter": "42"},"Financials":{"Production": "Unit 5"}}'
Examples of free-form tag formatting:

'{"Chicago Team": "marketing videos"}'
'{"Project": "prototype 3","Manager": "Meadows"}'

If you are using a Windows CLI, you may need to use the backslash (\) character to escape
the strings containing the tag values. For example, a single defined tag is formatted as
follows:
'{\"Logistics\": {\"Procurement\": \"Madrid Center\"}}'
Warning
To move a bucket to a different compartment

Open a command prompt and run oci os bucket update to move a bucket to a different
compartment.
oci os bucket update -ns <object_storage_namespace> --name <bucket_name> --compartment-id <new_target_
compartment_id>
To delete a bucket
You can permanently delete an empty bucket. The bucket cannot contain any objects. For
information on deleting objects, see To delete an object from a bucket.
Open a command prompt and run oci os bucket delete to delete a bucket. For example:
oci os bucket delete -ns <object_storage_namespace> --name <bucket_name>
Warning
You cannot recover a deleted bucket.

To get bucket metadata

You can get bucket metadata using the CLI. This includes the information that is displayed in
the Bucket Details tab when viewing a bucket in the Console.
Open a command prompt and run oci os bucket get to get information about an individual
bucket. For example:
oci os bucket get -ns <object_storage_namespace> --name <bucket_name>
The command returns the following information:
l Bucket visibility (private or public)

l Bucket name
l Compartment ID
l Entity tag (ETag)
l Custom metadata key-value pairs
l Namespace of the bucket
l Storage tier of the bucket
l Timestamp for bucket creation
l User OCID for the bucket creator
To add custom metadata key-value pairs to a bucket

Open a command prompt and run oci os bucket update with the --metadata option to add
key-value pairs to a bucket:
oci os bucket update -ns <object_storage_namespace> --name <bucket_name> --metadata <json_formatted_
key-value_pairs>

Tip
The --metadata option requires that the input be a

complex type formatted in valid JSON. See Passing
Complex Input and Using a JSON File for Complex Input
for information JSON formatting. You can add up to 4KB
of key-value metadata to a bucket.
To add resource tags to a bucket

To add defined resource tags to a bucket, open a command prompt and run oci os bucket
update with the --defined-tags option:
oci os bucket update -ns <object_storage_namespace> --name <bucket_name> --defined-tags <JSON_
formatted_defined_tag>
To add free-form resource tags to a bucket, open a command prompt and run oci os bucket
update with the --freeform-tags option:
oci os bucket update -ns <object_storage_namespace> --name <bucket_name> --freeform-tags <JSON_
formatted_free-form_tag>
Tip
The defined-tags and --freeform-tags options

require that the input be a complex type formatted in
valid JSON. For examples of JSON-formatted resource
tags, see To create a Standard or Archive tier bucket
with resource tags. See Passing Complex Input and
Using a JSON File for Complex Input for information
JSON formatting.

Using the API

Use the following operations to manage buckets:
l CreateBucket (publicAccessType property controls whether the bucket is private or

public and limits the capability to list public bucket contents)
l DeleteBucket
l GetBucket
l HeadBucket
l ListBuckets
l UpdateBucket
Managing Objects
In the Oracle Cloud Infrastructure Object Storage service, an object is a file or unstructured
data you upload to a bucket within a compartment within an Object Storage namespace. The
object can be any type of data, for example, multimedia files, data backups, static web
content, or logs. You can store objects up to 10 TiB in size. Objects are processed as a single
entity. You can't edit or append data to an object, but you can replace the entire object. This
topic describes how to manage objects.

Tip
The size of the object determines the appropriate

management interface to use to upload objects to
Oracle Cloud Infrastructure Object Storage:
l You can use the Console to upload objects up to 5

GiB in size.
l You can use the CLI or API to upload objects up to
10 TiB in size.
l You can use the multipart upload API to upload
objects larger than 100 MiB (recommended). See
Using Multipart Uploads for details.
Required IAM Policy


Tip
l For administrators: The policy Let Object Storage

admins manage buckets and objects lets the
specified group do everything with buckets and
objects. Objects always reside in the same
compartment as the bucket.
l If you need to write a more restrictive policy for
objects, the inspect objects lets you list all the
objects in a bucket and do a HEAD operation for a
particular object. In comparison, read objects
lets you download the object itself. See Details for
Object Storage.
Pre-authenticated requests provide a way to let users access a bucket or object without
having their own credentials. For example, you can create a request that lets a user upload
backups to a bucket without owning API keys. See Using Pre-Authenticated Requests for
details.
Object Names
Unlike other resources, objects do not have Oracle Cloud Identifiers (OCIDs). Instead, users
define an object name when they upload an object.
Use the following guidelines when naming an object:
l Use from 1 to 1024 characters.

l Valid characters are letters (upper or lower case), numbers, and characters other than
linefeed, newline, NULL, #, and ?.

l Use only Unicode characters for which the UTF-8 encoding does not exceed 1024 bytes.
Clients are responsible for URL-encoding characters.
l Do not include confidential information.
l Make the name unique within the bucket. Do not use the name of an existing object
within the bucket when naming an object unless you intend to overwrite the existing
object with the contents of the new or renamed object.
Object Storage prepends the Object Storage namespace string and bucket name to the object
name:
/n/<object_storage_namespace>/b/<bucket>/o/<object_name>
The object name is everything after the /o/.
For example: /n/ansh8lvru1zp/b/accessories/o/backpack_75.jpg
Tip
Object names can include one or more forward slash (/)

characters in the name string that follows the /o/
delimiter. See Object Naming Using Prefixes and
Hierarchies for more information on using the forward
slash in object names to create hierarchies.
Object Naming Using Prefixes and Hierarchies

Within an Object Storage namespace, buckets and objects exist in a flat hierarchy, but you
can simulate a directory structure using a prefix string that includes the forward slash (/) to
add hierarchy to an object name. Doing so lets you list one directory at a time, which is
helpful when navigating a large set of objects.
For example:
/n/ansh8tvru7zp/b/event_photos/o/marathon/finish_line.jpg
/n/ansh8tvru7zp/b/event_photos/o/marathon/participants/p_21.jpg

If you named your objects so that they exist in Object Storage as a hierarchy, you can use the
Command Line Interface (CLI) to perform bulk downloads and bulk deletes of all objects at a
specified level of the hierarchy, without affecting objects in levels above or below. In the
example above, you can use the CLI to download or delete all objects at the marathon/ level
without downloading or deleting objects at the marathon/participants/ sublevel.
When naming objects, you can also use prefix strings without a delimiter so that certain bulk
operations can be performed in the CLI by matching on the prefix portion of the object name.
For example, in the object names below, the string gloves_27_ can serve as a prefix for
matching purposes when performing bulk downloads or deletions:
/n/ansh8tvru7zp/b/apparel/o/gloves_27_dark_green.jpg
/n/ansh8tvru7zp/b/apparel/o/gloves_27_light_blue.jpg
When you perform bulk uploads with the CLI, you can prepend a prefix string to the names of
the files you are uploading.
Using the Console
To upload an object to a bucket

2. Choose the compartment your bucket is in.
A list of buckets is displayed.
3. Click the bucket name.
A list of objects in the bucket is displayed.
4. Click Upload Object.
5. Click Browse, navigate to and select the file you want to upload, and then click Open.
Alternatively, you can drag and drop a file in the Drop files here section.
6. If you want to change the name of the object, edit the name in the Object Name field.
7. Click Upload Object.
The object is uploaded and displayed in the list of objects.

To download an object from a bucket

2. Choose the compartment that contains the bucket that contains your object.
3. Click the bucket name that contains your object.
4. For the object you want to download, click the Actions icon ( ), and then click
Download.
To view object details

4. For the object you want to view the details of, click the Actions icon ( ), and then
click Details. Object Storage displays object details including the following:
l ETag (entity tag)
l Storage tier
l MD5 hash
To rename an object


4. For the object you want to edit, click the Actions icon ( ), and then click Edit.
5. In the Edit Object dialog, provide the new name for the object and an optional
delimited directory structure prefix. For example, p_94.jpg or
/marathon/participants/p_94.jpg.
Avoid entering confidential information in object name.
Warning
Buckets cannot store two objects that use identical

names. If you choose to rename an object using the
name of another object in the same bucket, the
object that originally used the name is overwritten.
To restore an object from an Archive Storage tier bucket
Tip
You need OBJECT_RESTORE permissions to restore

Archive Storage objects.
3. Click the bucket name that contains the object that you want to restore.
4. Click the Actions icon ( ) to the right of the object you want to restore, then click

Restore Object.
5. Optionally, specify the Time Available for Download in Hours.
By default, you have 24 hours to download an object after restoration. However you can
alternatively specify a download time of from 1 to 240 hours. You can find out how much
download time is remaining by looking at Available for Download in object Details
or by looking at the Actions ( ) menu to the right of Download. Refresh the
browser to obtain up-to-date remaining download time information.
After the allotted download time expires, the object returns to Archive Storage.
6. Click Restore Object.
Depending on the size of the object, it can take 4 or more hours to restore an object from
Archive Storage. You cannot download an item until the item is fully restored.
To check the status of an Archive Storage object restoration

3. Click the Archive Storage bucket name that contains the object for which you want to
check the restoration or download status of.
4. Click the Actions icon ( ) to the right of the object you want to check the restoration
or down load status of, then click Details.
5. Check the Status.
Status displays one of the following:
l Archived
l Restoring
l Restored

To delete an object from a bucket

You can permanently delete an object from a bucket. There is no way to recover a deleted
object.
3. Find the bucket that contains the object you want to delete and click the bucket name.
4. For the object you want to delete, click the Actions icon ( ), and then click Delete.

To upload an object to a bucket

Open a command prompt and run oci os object put to upload an object:
oci os object put -ns <object_storage_namespace> -bn <bucket_name> --file <file_location> --name
<object_name> --no-multipart
Where <file_location> refers to a directory path like "C:\workspace\myfile.txt". If you wish

to use the filename as the uploaded object's name, you can omit the --name flag. The
resulting object name does not include the path information (for example, "C:\workspace\").
To add custom metadata key-value pairs, use the --metadata flag:

<object_name> --metadata <json_formatted_key-value_pairs> --no-multipart

Tip
The --metadata flag requires that the input be a

for information JSON formatting.
Note that an object can be uploaded as a single part or as multiple parts. Here we describe a
single part upload. For information on multipart uploads, see Using Multipart Uploads
To bulk upload objects to a bucket

Open a command prompt and run oci os object bulk-upload to upload all files in a given
directory (including files in subdirectories):
oci os object bulk-upload -ns <object_storage_namespace> -bn <bucket_name> --src-dir <source_
directory_location> --no-multipart
Where <source_directory_location> refers to a directory path like "C:\workspace\files_to_

upload\". Note that if your source directory has subdirectories, the subdirectoriy names will
be prepended to the names of the files stored in those subdirectories, delimited with a
forward slash (/) character. For example, if a file named "maple.jpg" is stored in the
subdirectory "trees", when the file is uploaded, Object Storage assigns the name
"trees/maple.jpg" to the resulting object.
To append a prefix string to the object names created by your uploads, use the --object-
prefix flag:
directory_location> --object-prefix <object_name_prefix_string> --no-multipart
For example:
oci os object bulk-upload -ns ansh8tvru7zp -bn apparel --src-dir C:\workspace\new_
items\bicycling\gloves\ --object-prefix /bicycling/gloves/ --no-multipart
To add custom metadata key-value pairs, use the --metadata flag:


directory_location> --metadata <json_formatted_key-value_pairs> --no-multipart
Tip
The --metadata flag requires that the input be a

for information JSON formatting.
To download an object from a bucket

Open a command prompt and run oci os object get to download an object:
oci os object get -ns <object_storage_namespace> -bn <bucket_name> --name <object_name> --file <file_
location>
Where <file_location> refers to a directory path like "C:\workspace\myfile.txt ".
To bulk download all objects within a bucket

Open a command prompt and run oci os object bulk-download to download all the objects
in a bucket:
oci os object bulk-download -ns <object_storage_namespace> -bn <bucket_name> --download-dir <download_
directory_location>
Where <download_directory_location> refers to a directory path like

"C:\workspace\objects\" where downloaded objects are saved. Object Storage creates this
directory if it does not exist.
For a complete list of object bulk download options, see CLI Help.
To bulk download objects by object name prefix string

If you have named your objects with prefix strings, you can bulk download those objects in a

bucket that match a specified prefix string. Open a command prompt and run oci os object
bulk-download command with the --prefix flag:
directory_location> --prefix <prefix_string>

"C:\workspace\objects\" where downloaded objects are saved. Object Storage creates this
directory if it does not exist.
For example:
oci os object bulk-download -ns ansh8tvru7zp -bn apparel --download-dir C:\objects\ --prefix gloves_27
In the example above, an object named "gloves_27_A.jpg" is downloaded, while an object

named "gloves_31_A.jpg" is not downloaded.
If you have named your objects so that they exist in Object Storage as a hierarchy, you can
download objects at a given level and all sublevels by specifying the prefix that matches the
level of your choosing:
directory_location> --prefix <level_1/level_2/>
The command above downloads the following files:
l level_1/level_2/object_name
l level_1/level_2/level_3/object_name
l level_1/level_2/level_3/level_4/object_name
To download only those objects at a given hierarchy level (and not objects in levels above or
below), see To bulk download objects at a specified hierarchy level.
To bulk download objects at a specified hierarchy level

bulk download all the objects in a bucket at a specified hierarchy level (and not objects in
levels above or below). Open a command prompt and run oci os object bulk-download

command with the --prefix and --delimiter flags:

directory_location> --prefix <level_1/level_2/> --delimiter /

"C:\workspace\objects\" where files downloaded objects are saved. Object Storage creates
this directory if it does not exist.
Tip
Note that the forward slash (/) is currently the only

supported delimiter for the --delimiter flag.
The command above downloads all objects at "level_2" of the hierarchy. For example, the
following object is downloaded:
level_1/level_2/object_name
The command above does not download objects in levels above or below "level_2". For
example, the following objects are not downloaded by the command above:
l level_1/object_name
To download objects at a given hierarchy level along with all objects in the associated
hierarchy sublevels, see To bulk download objects by object name prefix string.
To rename an object
Open a command prompt and run oci os object rename to rename an object:
oci os object rename -ns <object_storage_namespace> -bn <bucket_name> --name <object_original_name> --
new-name <object_new_name>

Warning
Avoid entering confidential information in object name.
For example:
oci os object rename -ns ansh8tvru7zp -bn photo_collection --name /marathon/participants/p_93.jpg --new-
name /marathon/participants/p_94.jpg
To make the rename operation dependent on the object having a specific entity tag, use the -
-src-obj-if-match-e-tag option:
oci os object rename -ns <object_storage_namespace> -bn <bucket_name>--name <object_original_name> --
new-name <object_new_name> --src-obj-if-match-e-tag <etag_required_for_object_rename>
For example:
oci os object rename -ns ansh8lvru1zp -bn my_bucket --name my_object.jpg --new-name my_renamed_
object.jpg --src-obj-if-match-e-tag 6672BECB67CCFFBCE0530292F20ZBACE
For object rename operations where you intend to overwrite one object in a bucket with
another, you can make the renaming dependent on the object that is being overwritten having
a specific entity tag. To do so, use the --new-obj-if-match-e-tag option:
oci os object rename -ns <object_storage_namespace> -bn <bucket_name> --name <source_object_name> --
new-name <name_of_object_to_be_overwritten> --new-obj-if-match-e-tag <etag_of_object_to_be_
overwritten>
For example:
object.jpg --new-obj-if-match-e-tag 6672BECB67CCFFBCE0530292F20ZBACE
When renaming an object, you can prevent the system from overwriting another object in the
same bucket by using the --new-obj-if-none-match-e-tag * option. This option prevents
the renaming operation from completing if the system finds that an object already exists with
the --new-name value specified in the rename request and the entity tag of the source object.
oci os object rename -ns <object_storage_namespace> -bn <bucket_name> --name <source_object_name> --
new-name <new_name_for_object> --new-obj-if-none-match-e-tag *
For example:

object.jpg --new-obj-if-none-match-e-tag *
To restore an Archive Storage tier object
Tip
You need OBJECT_RESTORE permissions to restore

Archive Storage objects.
Open a command prompt and run oci os object restore to restore an object from Archive
Storage:
oci os object restore -ns <object_storage_namespace> -bn <archive_bucket_name> --name <archived_
object_name>
Use the oci os object restore-status command to check the status of restore request.
After the file is restored, you have 24 hours to download the file.
To check the status of an Archive Storage object restoration

Open a command prompt and run oci os object restore-status to check the status of
restoring an object from Archive Storage:
oci os object restore-status -ns <object_storage_namespace> -bn <archive_bucket_name> --name
<archived_object_name>
To delete an object
You can permanently delete an object. Open a command prompt and run oci os object
delete to delete an object:
oci os object delete -ns <object_storage_namespace> -bn <bucket_name> --name <object_name>

To bulk delete all objects within a bucket

Open a command prompt and run oci os object bulk-delete to delete all the objects in a
bucket:
oci os object bulk-delete -ns <object_storage_namespace> -bn <bucket_name>
Tip
To see a list of the files that are deleted by any bulk

delete command without actually deleting the files, use
the --dry-run flag.
To bulk delete objects by object name prefix string

If you have named your objects with prefix strings, you can bulk delete those objects in a
given bucket that match a given prefix. Open a command prompt and run oci os object
bulk-delete command with the --prefix flag:
oci os object bulk-delete -ns <object_storage_namespace> -bn <bucket_name> --prefix <prefix_string>
For example:
oci os object bulk-delete -ns ansh8tvru7zp -bn apparel --prefix gloves_27
In the example above, an object named "gloves_27_A.jpg" is deleted, while an object named
"gloves_31_A.jpg" is not deleted.
delete objects at a given level and all sublevels by specifying the prefix that matches the level
of your choosing:
oci os object bulk-delete -ns <object_storage_namespace>-bn <bucket_name>--prefix <level_1/level_2/>
The command above deletes the following files:

l level_1/level_2/object_name
To delete only those objects at a given hierarchy level (and not objects in levels above or
below), see To bulk delete objects at a specified hierarchy level.
Tip

the --dry-run flag.
To bulk delete objects at a specified hierarchy level

bulk delete only those objects at a given hierarchy level (and not objects in levels above or
below). To do this, open a command prompt and run the oci os object bulk-delete
command with the --prefix and --delimiter flags:
oci os object bulk-delete -ns <object_storage_namespace> -bn <bucket_name> --prefix <level_1/level_2/>
--delimiter /
Tip
Note that the forward slash (/) is currently the only

supported delimiter for the --delimiter flag.
The command above deletes the following object:
level_1/level_2/object_name

The command above does not delete objects in levels above or below "level_2". For example,
the following objects are not deleted by the command above:
l level_1/object_name
To delete objects at a given hierarchy level along with all objects in the associated hierarchy
sublevels, see To bulk delete objects by object name prefix string.
Tip

the --dry-run flag.
To list objects in a bucket

Open a command prompt and run oci os object list to get a list of the objects in a bucket:
oci os object list -ns <object_storage_namespace> -bn <bucket_name>
By default, the system returns the following details for each object:
l Name
l Object size
l "Last Modified" time stamp
l MD5 hash
To get object details

Open a command prompt and run oci os object head to get object details:

oci os object head -ns <object_storage_namespace> -bn <bucket_name> --name <object_name>
The system output includes the following object details:
l ETag (entity tag)

l Content length (object body size)
l Storage tier
l MD5 hash
l Archival state
Using the API

Use the following operations to manage objects:
l DeleteObject
l GetObject
l HeadObject
l ListObjects
l PutObject
l RenameObject
l RestoreObjects
Using Pre-Authenticated Requests

Pre-authenticated requests provide a way to let users access a bucket or an object without
having their own credentials, as long as the request creator has permissions to access those
objects. For example, you can create a request that lets an operations support user upload

backups to a bucket without owning API keys. Or, you can create a request that lets a
business partner update shared data in a bucket without owning API keys.
When you create a pre-authenticated request, a unique URL is generated. Users in your
organization, partners, or third parties can use this URL to access the Object Storage resource
target identified in the pre-authenticated request.
Important
Carefully assess the business requirement for and the

security ramifications of pre-authenticated access to a
bucket or objects.
A pre-authenticated request URL gives anyone who has

the URL access to the targets identified in the request
for as long as the request is active. In addition to
considering the operational needs of pre-authenticated
access, it is equally important to manage its
distribution.
Required Permissions
You need PAR_MANAGE permission access to the target bucket or object to create or manage
pre-authenticated requests.
You also need permission to perform the action the pre-authenticated request is permitting.
For example, if you are creating a pre-authenticated request for uploading an object, you
must have both the PAR_MANAGE and the OBJECT_CREATE permissions in the target
compartment.

Important
If the user who creates a pre-authenticated request

loses the OBJECT_CREATE permission after they created
the request, then the request no longer works.
Options
When creating a pre-authenticated request, you have the following options:
l You can configure the name of a specific bucket that a user has write access to and can
upload one or more objects to.
l You can configure the name of a specific object that a user can read from, write to, or
read from and write to.
l You can configure the expiration date for the request.
Scope and Constraints

Understand the following scope and constraints regarding pre-authenticated requests:
l Users can't list bucket contents.

l There is no hard limit on the number of pre-authenticated requests that you can create.
l You can't edit a pre-authenticated request. If you want to change user access options in
response to changing requirements, you need to create a new pre-authenticated
request.
l The target and actions for a pre-authenticated request are based on its creator's
permissions. The request is not, however, bound to the creator's account login
credentials. A pre-authenticated request is not affected if the creator's login credentials
change.

Working with Pre-Authenticated Requests

You can create, delete, or list pre-authenticated requests using the Console, using the CLI, or
by using an SDK to access the API.
Important
The unique URL provided by the system when you

create a pre-authenticated request is the only way a
user can access the bucket or object specified as the
request target. Copy the URL to durable storage. The
URL is displayed only at the time of creation and cannot
be retrieved later.
Using the Console
To create a pre-authenticated request for a bucket

increase.
4. Click Pre-Authenticated Requests under Resources to display the list of pre-
authenticated requests.
5. Click Create Pre-Authenticated Request.
6. Provide the following information:
l Name: Type a name for the request, for example: bucketPAR. Avoid entering

l Pre-Authenticated Request Target: Pick Bucket.

l Access Type: By default this request permits writes to the bucket.
l Expiration Date/Time: Use the date and time editor to pick an expiration date
and time.
7. Click Create Pre-Authenticated Request.
After a request is created, the Pre-Authenticated Request Details dialog displays
the URL used to access the bucket.
8. Click Copy to copy the URL for future reference.
Note

user can access the bucket or object specified as
the request target. Copy the URL to durable
storage. The URL is displayed only at the time of
creation and cannot be retrieved later.
9. Click Close.
To create a pre-authenticated request for an object

4. Click Objects under Resources to display the list of objects.
5. For the object you want to create a pre-authenticated request, click the Actions icon (
), and then click Create Pre-Authenticated Request.

6. Provide the following information:

l Name: Type a name for the request, for example: objectPAR. Avoid entering
l Pre-Authenticated Request Target: Pick Object. The object name that you
launched the Create Pre-Authenticated Request is prepopulated under
Object, however, you can enter a different object name.
l Access Type: Pick one of the following:
o Permit reads on the object
o Permit writes to the object
o Permit reads to and writes from the object
l Expiration Date/Time: Use the date and time editor to pick an expiration date
and time.
7. a. Click Create Pre-Authenticated Request.
After a request is created, the Pre-Authenticated Request Details dialog
displays the URL used to access the object.
8. Click Copy to copy the URL for future reference.
Note

user can access the bucket or object specified as
the request target. Copy the URL to durable
storage. The URL is displayed only at the time of
creation and cannot be retrieved later.
9. Click Close.


To create a pre-authenticated request for a bucket

oci os preauth-request create -ns <object_storage_namespace> -bn <bucket_name> --name
<preauthenticated_request_name> --access-type AnyObjectWrite --time-expires <timestamp>
Note the following:
l You must use the AnyObjectWrite enum value with the --access-type flag. Pre-
authenticated requests for buckets permit writes to the bucket by default.
l The <timestamp> value must be an RFC 3339 time stamp. For example: 2017-09-
01T00:09:51.000+02:00.
Note

be retrieved later.
To create a pre-authenticated request for an object

oci os preauth-request create -ns <object_storage_namespace> -bn <bucket_name> --name
<preauthenticated_request_name> --access-type <enum_value> --time-expires <timestamp> -on <object_
name_or_null>
Where <enum_value> is one of the following:

l ObjectRead
l ObjectWrite
l ObjectReadWrite
l AnyObjectWrite
Note that the <timestamp> value must be an RFC 3339 time stamp. For example: 2017-09-
01T00:09:51.000+02:00.
Avoid entering confidential information in the pre-authenticated request name.
Note

be retrieved later.
To list a pre-authenticated request

oci os preauth-request list -ns <object_storage_namespace> -bn <bucket_name>
To get a pre-authenticated request

oci os preauth-request get -ns <object_storage_namespace> -bn <bucket_name> --par-id
<preauthenticated_request_id>
To delete a pre-authenticated request

oci os preauth-request delete -ns <object_storage_namespace> -bn <bucket_name> --par-id
<preauthenticated_request_id>

Using the API

Use the following operations to work with pre-authenticated requests:
l CreatePreauthenticatedRequest
l DeletePreauthenticatedRequest
l GetPreauthenticatedRequest
l ListPreauthenticatedRequests
Using Multipart Uploads

The Oracle Cloud Infrastructure Object Storage service supports multipart uploads for more
efficient and resilient uploads, especially for large objects. You can perform multipart uploads
using the API, the Java Software Development Kit (SDK), or the Command Line Interface
(CLI), but not the Console. With multipart uploads, individual parts of an object can be
uploaded in parallel to reduce the amount of time you spend uploading. Multipart uploads
performed through the API can also minimize the impact of network failures by letting you
retry a failed part upload instead of requiring you to retry an entire object upload.
Multipart uploads can accommodate objects that are too large for a single upload operation.
Oracle recommends that you perform a multipart upload to upload objects larger than 100
MiB. The maximum size for an uploaded object is 10 TiB. Object parts must be no larger than
50 GiB. For very large uploads performed through the API, you have the flexibility of pausing
between the uploads of individual parts, and resuming the upload as your schedule and
resources allow.
Required IAM Policy


For administrators: The policy in Let Object Storage admins manage buckets and objects lets
the specified group do everything with buckets and objects.
If you are new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for Object Storage, see Details for Object Storage.
Using the Multipart Upload API

A multipart upload performed using the API consists of the following steps:
1. Initiating an upload
2. Uploading object parts
3. Committing the upload
Before you use the multipart upload API, you are responsible for creating the parts to upload.
Object Storage Provides API operations for the remaining steps. The service also provides API
operations for listing in-progress multipart uploads, listing the object parts in an in-progress
multipart upload, and aborting in-progress multipart uploads initiated through the API.
Here we describe the API steps at a high level, but you can refer to the API Reference for
specifics about supported API calls.
Creating Object Parts
With multipart upload, you split the object you want to upload into individual parts. Individual
parts can be as large as 50 GiB or as small as 10 MB. (Object Storage waives the minimum
part size restriction for the last uploaded part.) Decide what part number you want to use for
each part. Part numbers can range from 1 to 10,000. You do not need to assign contiguous
numbers, but Object Storage constructs the object by ordering part numbers in ascending
order.

Initiating an Upload
After you finish creating object parts, initiate a multipart upload by making a
CreateMultipartUpload REST API call. Provide the object name and any object metadata.
Object Storage Responds with a unique upload ID that you must include in any requests
related to this multipart upload. Object Storage also marks the upload as active. The upload
remains active until you explicitly commit it or abort it.
Uploading Object Parts
Make an UploadPart request for each object part upload. In the request parameters, provide
the Object Storage namespace, bucket name, upload ID, and part number. In the request
body, include the object part. Object parts can be uploaded in parallel and in any order. When
you commit the upload, Object Storage uses the part numbers to sequence object parts. Part
numbers do not have to be contiguous. If multiple object parts are uploaded using the same
upload ID and part number, the last upload overwrites the part and is committed when you
call the CommitMultipartUpload API.
Object Storage returns an ETag (entity tag) value for each part uploaded. You need both the
part number and corresponding ETag value for each part when you commit the upload.
If you have network issues, you can restart a failed upload for an individual part. You do not
need to restart the entire upload. If, for some reason, you cannot perform an upload all at
once, multipart upload lets you continue uploading parts at your own pace. While a multipart
upload is still active, you can keep adding parts as long as the total number is less than
10,000.
You can check on an active multipart upload by listing all parts that have been uploaded. (You
cannot list information for an individual object part in an active multipart upload.) The
ListMultipartUploadParts operation requires the Object Storage namespace, bucket name, and
upload ID. Object Storage responds with information about the parts associated with the
specified upload ID. Parts information includes the part number, ETag value, MD5 hash, and
part size (in bytes).
Similarly, if you have multiple multipart uploads occurring simultaneously, you can see what
uploads are in-progress. Make an ListMultipartUploads API call to list active multipart uploads
in the specified Object Storage namespace and bucket.

Charges for parts storage begin accruing when you upload data.
Committing the Upload
When you have uploaded all object parts, complete the multipart upload by committing it. Use
the CommitMultipartUpload request parameters to specify the Object Storage namespace,
bucket name, and upload ID. Include the part number and corresponding ETag value for each
part in the body of the request. When you commit the upload, Object Storage constructs the
object from its constituent parts. The object is stored in the specified bucket and Object
Storage namespace. You can treat it like you would any other object. Garbage collection
releases storage space occupied by any part numbers you uploaded, but did not include in the
CommitMultipartUpload request.
You cannot list or retrieve parts from a completed upload. You cannot append or remove parts
from the completed upload either. If you want, you can replace the object by initiating a new
upload.
If you decide to abort a multipart upload instead of committing it, wait for in-progress part
uploads to complete and then use the AbortMultipartUpload operation. If you abort an upload
while part uploads are still in progress anyway, Object Storage cleans up both completed and
in-progress parts. Upload IDs from aborted multipart uploads cannot be reused.
API Documentation
Use the following operations to manage multipart uploads:
l AbortMultipartUpload
l CommitMultipartUpload
l CreateMultipartUpload
l ListMultipartUploadParts
l ListMultipartUploads
l UploadPart

Using the CLI

When you perform a multipart upload using the CLI, you do not need to split the object into
parts as you are required to do by the API. Instead, you specify the part size of your choice,
and Object Storage splits the object into parts and performs the upload of all parts
automatically. You can choose to set the maximum number of parts that can be uploaded in
parallel. By default, the CLI limits the number of parts that can be uploaded in parallel to
three. When using the CLI, you do not have to perform a commit when the upload is complete.
You can also use the CLI to list in-progress multipart uploads, and to abort multipart uploads
initiated through the API.
To perform a multipart upload using the CLI

Open a command prompt and run oci os object put with the --part-size flag to upload an
object. The --part-size value represents the size each part in Mebibytes (MiB). Object
Storage waives the minimum part size restriction for the last uploaded part. The --part-size
value must be an integer.
Optionally, you can use the --parallel-upload-count flag to set the maximum number of
parallel uploads allowed.
<object_name> --part-size <upload_part_size_in_MB> --parallel-upload-count <maximum_number_parallel_
uploads>
For more information on the oci os object put command, see To upload an object to a
bucket.
To list in-progress multipart uploads for a bucket

Open a command prompt and run oci os multipart list to list all in-progress multipart
uploads for a bucket:

oci os multipart list -ns <object_storage_namespace> -bn <bucket_name>
Tip
See CLI Help for command options to control the

pagination of the list output.
To abort an uncommitted multipart upload initiated through the API

Open a command prompt and run oci os multipart abort to abort an in-progress multipart
upload initiated through the API:
oci os multipart list -ns <object_storage_namespace> -bn <bucket_name> --object-name <object_name> --
upload-id <upload_ID>
Tip
The CLI interface asks you to confirm the deletion

request. To abort without the confirmation prompt, use
the --force flag.
Hadoop Support
Using the HDFS connector, you can run Hadoop or Spark jobs against data in the Oracle Cloud
Infrastructure Object Storage service. The connector has the following features:
l Supports read and write data stored in Object Storage

l Is compatible with existing buckets of data
l Is compatible with Hadoop 2.7.2
For information about downloading, configuring, and using the HDFS connector, see HDFS
Connector for Object Storage.

Designating Compartments for the Amazon S3

Compatibility and Swift APIs
In the Oracle Cloud Infrastructure Object Storage service, a bucket is a container for storing
objects in a compartment within an Object Storage namespace. A bucket is associated with a
single compartment and data is stored as objects in buckets.
In addition to the native Object Storage APIs, Object Storage provides API support for both
Amazon S3 Compatibility API and Swift API. However these APIs do not understand the Oracle
Cloud Infrastructure concept of a compartment. By default, buckets created using the Amazon
S3 Compatibility API or the Swift API are created in the root compartment of the Oracle Cloud
Infrastructure tenancy. Instead, you can designate a different compartment for the Amazon
S3 Compatibility API or Swift API to create buckets in.
When you designate a different compartment to use for the Amazon S3 Compatibility API or
Swift API, any new buckets you create using the Amazon S3 Compatibility API or the Swift API
are created in this newly designated compartment. Buckets previously created in a different
compartment are not automatically moved to the newly designated compartment. See
Managing Buckets if you want to move previously created buckets to this newly designated
compartment.
Required IAM Policy

Compartments have policies that indicate what actions a user can perform on a bucket and all
the objects in the bucket.
For administrators:
l To change the default compartments for Amazon S3 Compatibility API and Swift API, a
user must belong to a group with NAMESPACE_UPDATE permissions.

l To see the current default compartments for Amazon S3 Compatibility API and Swift
API, a user must belong to a group with NAMESPACE_READ permissions.
l To move a bucket to a different compartment, a user must belong to a group with
BUCKET_UPDATE and BUCKET_CREATE permissions in the source compartment, and
BUCKET_CREATE permissions in the target compartment.
to dig deeper into writing policies for buckets and objects, see Details for Object Storage.
Viewing and Specifying Designated Compartments

You can view the current default compartment designations for Amazon S3 Compatibility API
and Swift API data. If your permissions allow, you can also change the Amazon S3
Compatibility API and Swift API compartment designations.
Designated compartment names:
l Must be unique across all the compartments in your tenancy.

l Can be from 1 to 100 characters in length.
l Must not contain confidential information.
l Valid are letters (upper or lower case), numbers, hyphens, and underscore.
Using the Console
To view your Amazon S3 Compatibility API and Swift API compartment

designations
Open the Console, and then click the name of your tenancy in the top-left corner of the page.
Your default compartment designations for the APIs are listed under Object Storage
Settings.

To edit your tenancy's Amazon S3 Compatibility API and Swift API

compartment designations
1. Open the Console, and then click the name of your tenancy in the top-left corner of the
page.
2. Click Edit Object Storage Settings.
3. In the Edit Object Storage Settings dialog:
l Select the compartment that you want for the Amazon S3 Compatibility API
Designated Compartment from the drop-down menu.
l Select the compartment that you want for the Swift API Designated
Compartment from the drop-down menu.
4. Click Save.
The new Object Storage Settings are displayed.

To get your tenancy's Amazon S3 Compatibility API and Swift API

compartment designations
Open a command prompt and run oci os ns get-metadata to get your compartment
designations.
For example:
oci os ns get-metadata --namespace <object_storage_namespace>
To update your tenancy's Amazon S3 Compatibility API compartment

designation
Open a command prompt and run oci os ns update-metadata to update your compartment

designation for Amazon S3 Compatibility API.
For example:
oci os ns update-metadata --namespace <object_storage_namespace> --default-s3-compartment-id <your_
oci_compartment_id>
Where <your_oci_compartment_id> specifies a compartment that is not the root

compartment of your tenancy.
To update your tenancy's Swift API compartment designations

Open a command prompt and run oci os ns update-metadata to update your compartment
designation for Swift API.
For example:
oci os ns update-metadata --namespace <object_storage_namespace> --default-swift-compartment-id <your_
oci_compartment_id>
Where <your_oci_compartment_id> specifies a compartment that is not the root

compartment of your tenancy.
Using the API

Use the following operation to get your default Amazon S3 Compatibility API and Swift API
compartment designations, and change those compartment designations:
l GetNamespaceMetadata
l UpdateNamespaceMetadata
Amazon S3 Compatibility API

Using the Amazon S3 Compatibility API, customers can continue to use their existing Amazon
S3 tools (for example, SDK clients) and partners can make minimal changes to their

applications to work with Object Storage. The Amazon S3 Compatibility API and Object
Storage data sets are congruent. If data is written to the Object Storage using the Amazon S3
Compatibility API, the data can be read back using the native Object Storage API and vice
versa.
Differences between the Object Storage API and the Amazon S3

Compatibility API
The Object Storage Service provided by Oracle Cloud Infrastructure and Amazon S3 use
similar concepts and terminology. In both cases, data is stored as objects in buckets. The
differences are in the implementation of features and tools for working with objects.
The following highlights the differences between the two storage technologies:
l Compartments
Although Amazon S3 doesn't use compartments, any buckets created using the Amazon
S3 Compatibility API are created in the root compartment of the Oracle Cloud
Infrastructure tenancy.
l Global bucket namespace
Object Storage doesn't use a global bucket namespace. Bucket names must be unique
within the context of a namespace, but bucket names can be repeated across
namespaces. Each tenant is associated with one default namespace that spans all
compartments.
l Encryption
The Oracle Cloud Infrastructure Object Storage service encrypts all data at rest by
default. Encryption can't be turned on or off using the API.
l Object Level Access Control Lists (ACLs)
Oracle Cloud Infrastructure does not use ACLs for objects. Instead, IAM policies are
used to manage access to compartments, buckets, and objects.
For more information, see Overview of the Object Storage Service.

Amazon S3 Compatibility API Support

Amazon S3 Compatibility API support is provided at the bucket level and object level.
Bucket APIs
The following bucket APIs are supported:
l DeleteBucket
l GetLocation
l HeadBucket
l ListObjects
l PutBucket
Object APIs
The following object APIs are supported:
l DeleteObject
l GetObject
l HeadObject
l PutObject
Tagging APIs
The following tagging APIs are supported:
l DeleteBucketTagging
l GetBucketTagging
l PutBucketTagging
Enabling Application Access to Object Storage

To enable application access from Amazon S3 to Object Storage, you need to set up access to
Oracle Cloud Infrastructure and modify your application.

Setting up access to Oracle Cloud Infrastructure:
l Create a Oracle Cloud Infrastructure tenant. See Signing Up for Oracle Cloud
Infrastructure.
l Create an Amazon S3 Compatibility API key. An Amazon S3 Compatibility API key
consists of an Access Key/Secret Key pair.
Modifying your application:
l Configure a new endpoint for the application. For example ,

"mynamespace.compat.objectstorage.us-phoenix-1.oraclecloud.com".
l Set the target region as one of the Oracle Cloud Infrastructure regions.
l Configure the application to use the Amazon S3 Compatibility API key.
l Make sure that you aren't using the virtual-hosted style URL, which is not supported.
At this point, you can start accessing Object Storage.
Supported Amazon S3 Clients

Qualified support is provided for the AWS SDK for Java client.
Here is an example of configuring the AWS Java SDK

(https://aws.amazon.com/documentation/sdk-for-java/) to talk to Object Storage's Amazon
S3-compatible endpoints:
// Get S3 credentials from the console and put them here
AWSCredentialsProvider credentials = new AWSStaticCredentialsProvider(new BasicAWSCredentials(
"ocid1.credential.oc1..anEXAMPLE",
"anEXAMPLE="));
// The name of your tenancy

String tenancy = "tenancy";
// The region to connect to

String region = "us-ashburn-1";
// Create an S3 client pointing at the region

String endpoint = String.format("%s.compat.objectstorage.%s.oraclecloud.com",tenancy,region);
AwsClientBuilder.EndpointConfiguration endpointConfiguration = new
AwsClientBuilder.EndpointConfiguration(endpoint, region);
AmazonS3 client = AmazonS3Client.builder()
.standard()
.withCredentials(credentials)
.withEndpointConfiguration(endpointConfiguration)
.disableChunkedEncoding()

.enablePathStyleAccess()
.build();
Amazon S3 Compatibility API Requirement

Before you can use the Amazon S3 Compatibility API, you must create an Amazon S3
Compatibility API key.
After you've generated the necessary key, you can use the Amazon S3 Compatibility API to
access Object Storage in Oracle Cloud Infrastructure. For more information, see the API
Reference.

CHAPTER 16 Developer Tools
This chapter includes general information about using the Oracle Cloud Infrastructure REST
API and developer tools.
Command Line Interface (CLI)

The command line interface (CLI) is a tool that enables you to work with Oracle Cloud
Infrastructure objects and services.
Overview of the CLI

The CLI is a small footprint tool that you can use by itself, or with the Console to complete
Oracle Cloud Infrastructure tasks. The CLI provides much the same functionality as the
Console and includes additional advanced commands. Some of these commands, such as the
ability to run scripts, extend the Console's functionality.
CLI Architecture
The CLI is built on Python (version 2.7.5 or 3.5 or later), running on Mac, Windows, or Linux.
The Python code makes calls to Oracle Cloud Infrastructure APIs to provide the functionality
implemented for the various services.
Note
Oracle Cloud Infrastructure APIs
These APIs are typical REST APIs that use HTTPS

requests and responses. For more information, see
About the API

CLI Help
The command line help is derived from the APIs and help text in the Python source code. You
can get help for a specific command on the command line, or view the command line help.
Supported Services and Licensing

The following Oracle Cloud Infrastructure services and licensing information apply to the CLI.
l Services supported:
o Audit
o Core Services (Networking, Compute, Block Volume)
o Database
o IAM
o Object Storage
o Load Balancing
o DNS
o File Storage
o Email Delivery
l Licensing: This CLI and sample is dual licensed under the Universal Permissive License
1.0 and the Apache License 2.0; third-party content is separately licensed as described
in the code.
Installing the CLI

This topic describes the installation options and the steps to install the CLI and required
software.
Requirements and Installation Options
Before you install the CLI, review the following requirements.

REQUIREMENTS
To install and use the CLI, you must have:
l An Oracle Cloud Infrastructure account

l A user created in that account, in a group with a policy that grants the desired
permissions. This account user can be you, another person, or a system that calls the
API. For an example of how to set up a new user, group, compartment, and policy, see
Adding Users. For a list of other typical Oracle Cloud Infrastructure policies, see
Common Policies.
l A keypair used for signing API requests, with the public key uploaded to Oracle. Only
the user calling the API should possess the private key. See Configuring the CLI.
l Python version 2.7.5 or 3.5 or later, running on Mac, Windows, or Linux. Note that if you
use the CLI Installer and do not have Python on your machine, the Installer offers to
automatically install Python for you. If you already have Python installed on your
machine, you can use the python --version command to find out which version is
installed.
I NSTALLATION OPTIONS
There are two ways to install the CLI and you can use the one that is best suited for your
environment. Use either of the following options:
l Automatically installing the CLI and dependencies with the CLI installer
l Manually installing the CLI and dependencies
Using the CLI Installer
The installer uses a script to install the CLI and programs that are required. You can use the
installer to eliminate most of the manual steps to install the CLI. The installer script:
l Installs Python
o During installation, you are prompted to provide a location for installing the
binaries and executables. If Python is not installed on your computer, or the
installed version of Python is incompatible with the CLI, you are prompted to

install Python.
o The installer doesn't try to install Python on a MacOS computer. However, the
script notifies you if the version of Python on the computer is too old or
incompatible.
l Installs virtualenv and creates a virtual environment
l Installs the latest version of the CLI
o The installer overwrites an existing installation if you chose to do so. Respond
with Y when prompted to upgrade the CLI to the newest version.
o During the installation, you are asked if you want to update your PATH. Updating
the PATH adds the CLI executable ("oci.exe") to your PATH. Adding oci.exe to the
PATH lets you invoke the CLI without providing the full path to the executable. If
you want to update your PATH, respond with Y when prompted. You are notified
when to close and restart the terminal session.
To Install the CLI on a Windows Computer

1. Open the PowerShell console using the Run as Administrator option.
2. The installer enables auto-complete by installing and running a script. To allow this
script to run, you must enable the RemoteSigned execution policy.
To configure the remote execution policy for PowerShell, run the following command.
Set-ExecutionPolicy RemoteSigned
3. To run the installer script, run the following command.

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object
System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-
cli/master/scripts/install/install.ps1'))"
4. Respond to the installer's prompts.
To Install the CLI on any Computer with Bash

1. Open a terminal.

2. To run the installer script, run the following command.

bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-
cli/master/scripts/install/install.sh)"
3. Respond to the installer's prompts.
Manually Installing the CLI
This section describes how to install the CLI by following the sequence of steps that are
provided.
INSTALLING PYTHON
Python installation instructions vary for each operating system.
Windows and Windows Server 2008 R2
W INDOWS
Install Python from the Python Windows downloads page. During installation, choose to add
Python to the PATH and/or environment variables (depending on the prompt).
WINDOWS SERVER 2008 R2
To install Python on this version of Windows Server you must install Python 2.7, or install
Windows 2008 R2 Service Pack 1 (SP1) to the instance before installing later versions of
Python.
Oracle Linux 7.3 and Oracle Linux 6
ORACLE LINUX
Some versions of Oracle Linux come with incompatible versions of Python, and may require
additional components to install the CLI.

ORACLE LINUX 7.3
Before you install the CLI, run the following command on a new Oracle Linux 7.3 image.
sudo yum install gcc libffi-devel python-devel openssl-devel
sudo easy_install pip
ORACLE LINUX 6
On Oracle Linux 6, a newer version of Python is usually required. You can install a newer
version alongside the existing version by downloading from Python, and then install the CLI in
a virtual environment that uses the new version. To install the new version of Python, run the
following commands.
curl -O https://www.python.org/ftp/python/3.6.0/Python-3.6.0.tgz
tar -xvzf Python-3.6.0.tgz
cd Python-3.6.0
./configure
make
sudo make install
CentOS 6 and CentOS 7
CENT OS 6 AND CENT OS 7
Before you install the CLI, run the following commands on a new CentOS image.
Ubuntu 14.04 and Ubuntu 16.04
UBUNTU 14.04 AND UBUNTU 16.04
Python should come installed. However, if you need to install Python, use the OS's normal
package manager.

To install the additional required components, run the following commands.

sudo apt-get update
sudo apt-get install build-essential libssl-dev libffi-dev python-dev
sudo apt-get install python3-pippip3 install --upgrade pip
I NSTALLING AND CONFIGURING VIRTUALENV
Running the CLI in a virtual environment is optional. However, Oracle recommends running
the CLI in a virtualenv environment to isolate Python dependencies. If you want to run the
CLI in a virtual environment, use the following installation sequence:
l Install virtualenv and then create the environment

l Activate the virtualenv environment
l Run pip install oci-cli
If you don’t create a virtualenv environment first, you have to run sudo pip install oci_
cli. This is required to avoid permissions errors caused by trying to update packages in the
system python installation.
THE VIRTUALENV SOFTWARE
virtualenv is a virtual environment builder that lets you create isolated Python
environments. First, you have to download and install virtualenv and then install the CLI in
the virtual environment. (For Linux users, virtualenv is usually in a separate package from
the main Python package.)
Download the software and documentation from:
l Software: GitHub or PyPI.

l Documentation: Docs Virtualenv
INSTALLING AND CONFIGURING VIRTUALENV
After Python is installed, install and configure virtualenv.

To Install and Configure virtualenv

1. To set up the environment for Python 2, use the following command.
pip install virtualenv
2. To set up the environment for Python 3, use the following command.

pip3 install virtualenv
virtualenv typically installs to your Python directory. For example:

/usr/local/share/python3/virtualenv
3. (Optional) To create a directory for storing your virtual environments, run the following
command.
mkdir -p myvirtualspaces/virtualenvs
4. To create a new virtual environment without any packages, run the following command.
virtualenv myvirtualspaces/virtualenvs/cli-testing --no-site-packages
If you're installing a newer version of Python to run alongside an existing version, you can
create a virtual environment that uses the new version.
To reference the new version of Python, run the following command with the -p parameter.
virtualenv -p /usr/local/bin/python3.6 cli-testing
I NSTALLING THE COMMAND LINE I NTERFACE
Use the following steps to install the CLI in a virtual environment or on a standard system.
You can download the CLI from GitHub or install the package from Python Package Index
(PyPI).
To install using the GitHub download:
l To download the file, click oci-cli.zip.

l Unzip the file and then run the following command.
pip install oci_cli-*-py2.py3-none-any.whl
To install using PyPI, run the following command.

pip install oci-cli
S TARTING THE CLI IN A VIRTUAL ENVIRONMENT
Your operating system determines which commands are used to start a CLI session in a
virtual environment.
MacOS, Linux, and Unix Users

To start a CLI session, run the following commands.
1. Open a terminal.
2. Change the working directory.
cd myvirtualspaces/virtualenvs/cli-testing/bin
3. Run the activate batch file.

source activate
To stop using the CLI, run the following command in a terminal.

deactivate
Windows Users
To start a CLI session, run the following commands.
1. Open the Command Prompt using the Run as administrator option.

2. Change the working directory.
cd myvirtualspaces/virtualenvs/cli-testing/Scripts
3. Run the activate batch file.

activate
To stop using the CLI, run the following command from the command line.
deactivate

Configuring the CLI

This topic describes the required configuration for the CLI and includes optional configurations
that enable you to extend CLI functionality. This topic assumes that you installed the CLI and
are ready to configure it for your environment.
Setting up the Config File
Before using the CLI, you have to create a config file that contains the required credentials for
working with Oracle Cloud Infrastructure. You can create this file using a setup dialog or
manually, using a text editor.
USE THE S ETUP DIALOG
To have the CLI walk you through the first-time setup process, step by step, use the oci
setup config command. The command prompts you for the information required for the
config file and the API public/private keys. The setup dialog generates an API key pair and
creates the config file.
MANUAL S ETUP
If you want to set up the API public/private keys yourself, and write your own config file, see
SDK and Tool Configuration.
Tip
Use the oci setup keys command to generate a key

pair to include in the config file.
Using a File for CLI Configurations
The CLI supports using a file for CLI-specific configurations. You can:

l Specify a default profile.

l Set default values for command options so you don't have to type them into the
command line.
l Define aliases for commands. For example, using "ls" as an alias for list.
l Define aliases for options. For example, using "--ad" as an alias for --availability-
domain.
l Define named queries that are passed to the --query option instead of typing a
JMESPath expression on the command line.
The default location and file name is ~/.oci/oci_cli_rc. You can also explicitly specify this
file with the --cli-rc-file option or by with the legacy --defaults-file option. For
example:
# Uses the file from ~/.oci/oci_cli_rc
oci os bucket list
# Uses a custom file

oci os bucket list --cli-rc-file path/to/my/cli/rc/file
Setting up an oci-cli-rc File
To set up an oci-cli-rc file, run the following command.

oci setup oci-cli-rc path/to/target/file
The preceding command creates the file you specify that includes examples of default
command aliases, parameter aliases, and named queries.
S PECIFYING A DEFAULT PROFILE
Specify a default profile in the OCI_CLI_SETTINGS section of the CLI configuration file. The
next example shows how to specify a default profile named IAD. The CLI looks for a profile
named IAD in your ~/.oci/config file, or any other file that you specify using the --config-
file option.
[OCI_CLI_SETTINGS]
default_profile=IAD

You can also specify a default value for the --profile option using the OCI_CLI_PROFILE
environment variable.
If a default profile value has been specified in multiple locations, the order of precedence is:
1. The value specified in the --profile option.

2. The value specified in the OCI_CLI_PROFILE environment variable.
3. The value specified in the default_profile field in the OCI_CLI_SETTINGS section of
the CLI configuration file.
S PECIFYING DEFAULT VALUES
The CLI supports using a default values file so that you don't have to keep typing them into the
command line. For example, instead of typing in a --compartment-id on each launch
instance command or having to keep specifying the --namespace when using Object Storage
commands. You can put this information in a default values file.
Default values can be applied at different levels, from general to specific:
l Globally, across all the CLI commands.

l To a particular service, such as Compute or Object Storage.
l To a specific group, such as commands related to exporting images.
l To a specific command.
Default values are treated hierarchically, with specific values having a higher order of
precedence than general values. For example, if there is a globally defined value for
compartment-id and a specific compartment-id defined for the compute instance launch
command, the CLI uses the value for the compute instance launch instead of the global
default.
DEFAULT VALUES FILE NAME AND LOCATION
When you start the CLI, the program looks for the default values file in ~/.oci/oci_cli_rc.
You can also specify a different file and location by using the --cli-rc-file option, as
illustrated by the following:

# Uses the default values file from ~/.oci/oci_cli_rc

oci os bucket list
# Uses a custom default values file

oci os bucket list --cli-rc-file path/to/my/cli/custom-oci-cli-rc-file
COMMAND VALUE PRIORITY
If a value is provided on the command line also exists in --cli-rc-file, the value from the
command line has priority. For a command with options that take multiple values, the values
are taken entirely from the command line or from --cli-rc-file. The 2 sources aren't
merged.
DEFAULTS VALUE FILE SYNTAX
The --cli-rc-file file can be divided into different sections with one or more keys per
section.
S ECTIONS
In the next example, the file has two sections, with a key in each section. To specify which
section to use, you use the --profile option in the CLI.
[DEFAULT]
compartment-id = ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa
[ANOTHER_SECTION]
compartment-id = ocid1.compartment.oc1..aaaaaaaal3gzieyqdrggnx7xil26astxxhqol2pgjjdlieqeyg35nz5znhwa
KEYS
Keys are named after command line options, but do not use a leading double hyphen (--). For
example, the key for --image-id is image-id. You can specify keys for single values,
multiple values, and flags.
l Keys for Single Values. The next example shows how to specify key values at different
levels, and with different scope.
[DEFAULT]
# Defines a global default for bucket-name
bucket-name = my-global-default-bucket-name

# Defines a default for bucket-name, which applies to all 'compute' commands

compute.bucket-name = bucket-name-for-image-import-export
# Defines a default for bucket-name, which applies to all 'os object' commands (e.g., os object
get)
os.object.bucket-name = bucket-name-for-object-commands
# Defines a default for bucket-name, for the 'os object multipart list' command
os.object.multipart.list.bucket-name = bucket-name-for-multipart-list
l Keys for Multiple Values. Some options, such as --include and --exclude on the oci
os object bulk-upload command can be specified more than once. For example:
oci os object bulk-upload -ns my-namespace -bn my-bucket --src-dir my-directory --include *.txt -
-include *.png
The next example shows how you would enter the --include values in the --cli-rc-
file file
[DEFAULT]
os.object.bulk-upload.include =
*.txt
*.png
In the previous example, one value is given for each line and each line must be indented
underneath its key. You can use tabs or spaces and the amount of indentation doesn't
matter. You can also put a value on the same line as the key, add more values on the
following lines, and use a path statement for a value. For example:
[DEFAULT]
os.object.bulk-upload.include = *.pdf
*.txt
*.png
my-subfolder/*.tiff
l Keys for Flags. Some command options are flags, like --force, which uses a Boolean
value. To set a flag for the --force option, use the following command.
os.object.delete.force=true

S PECIFYING COMMAND ALIASES
Specify named queries in the OCI_CLI_COMMAND_ALIASES section of the CLI configuration

file. There are two types of aliases, global aliases and command sequence aliases. The
following example shows each type of alias.
[OCI_CLI_COMMAND_ALIASES]
# This is a global alias that lets you use "ls" instead of "list" for any list command in the CLI.
#
ls = list
# Command examples:
# oci os object ls or oci os compute ls
# This is a command sequence alias that lets you use "oci os object rm" instead of "oci os
# object delete".
# <alias> = <dot-separated sequence of groups and sub-groups>.<command or group to alias>
#
rm = os.object.delete
# Command example:
# <alias> = rm, <sequence of groups and sub-groups> = os object, <command or group to alias> = delete
If you want to define default values for options in your CLI configuration file, you can use the
alias names you have defined. For example, if you have -ls as an alias for --list, you can
define a default for an availability domain when listing instances by using the following
command.
[DEFAULT]
compute.instance.ls.compartment-
id=ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa
S PECIFYING OPTION ALIASES
Specify option aliases in the OCI_CLI_PARAM_ALIASES section of the CLI configuration file.
Option aliases are applied globally. The following example shows some aliases for command
options.
[OCI_CLI_PARAM_ALIASES]
# Option aliases either start with a double hyphen (--) or are a single hyphen (-) followed by a #
single letter. For example: --example-alias, -e

#
--ad = --availability-domain
--dn = --display-name
--egress-rules = --egress-security-rules
--ingress-rules = --ingress-security-rules
If you want to define default values for options in your CLI configuration file, you can use the
alias names you have defined. For example, if you have -ad as an alias for --availability-
domain, you can define a default for an availability domain when listing instances by using the
following command.
[DEFAULT]
compute.instance.list.ad=xyx:PHX-AD-1
S PECIFYING NAMED QUERIES
If you use the --query parameter to filter or manipulate output, you can define named
queries instead of using a JMESPath expression on the command line.
Specify named queries in the OCI_CLI_CANNED_QUERIES section of the CLI configuration file.
Examples of Named Queries

[OCI_CLI_CANNED_QUERIES]
# For list results, this gets the ID and display-name of each item in the list.
# Note that when the names of attributes have dashes in them they need to be surrounded
# with double quotes. This query knows to look for a list because of the [*] syntax
get_id_and_display_name_from_list=data[*].{id: id, "display-name": "display-name"}
get_id_and_display_name_from_single_result=data.{id: id, "display-name": "display-name"}
# Retrieves a comma separated string, for example:

# ocid1.instance.oc1.phx.xyz....,cli_test_instance_675195,RUNNING
#
get_id_display_name_and_lifecycle_state_from_single_result_as_csv=data.[id, "display-name", "lifecycle-
state"] | join(`,`, @)
# Retrieves comma separated strings from a list of results

#
get_id_display_name_and_lifecycle_state_from_list_as_csv=data[*].[join(`,`, [id, "display-name",

"lifecycle-state"])][]
# Filters where the display name contains some text

#
filter_by_display_name_contains_text=data[?contains("display-name", `your_text_here`)]
# Filters where the display name contains some text and pull out certain attributes(id and time-
created)
#
filter_by_display_name_contains_text_and_get_attributes=data[?contains("display-name", `your_text_
here`)].{id: id, timeCreated: "time-created"}
# Get the top 5 results from a list operation

#
get_top_5_results=data[:5]
# Get the last 2 results from a list operation

#
get_last_2_results=data[-2:]
You can reference any of these queries using this syntax: query://<query name>.
For example, to get id and display name from a list, run the following command.
oci compute instance list -c $C --query query://get_id_and_display_name_from_list
Enabling Auto-complete
If you used the CLI installer, you don't have to configure auto-complete because it's enabled
automatically.
To enable auto-complete (tab completion) for a manual CLI installation, run the following
command.
oci setup autocomplete
To enable auto-complete on a session by session basis, run the following command.

eval "$(_OCI_COMPLETE=source oci)"

Note
Support for Auto-complete on Windows
Auto-complete on Windows is only supported if you're

using PowerShell. A script runs to enable this feature.
However, you must change the PowerShell execution
policy to RemoteSigned. To configure this policy, run
the following command at the PowerShell command
line.
Set-ExecutionPolicy RemoteSigned
Using the CLI

This topic describes how to use the CLI to access Oracle Cloud Infrastructure and carry out
service-related tasks. This topic assumes that you have configured the CLI and are ready to
start using it.
Tip
CLI Getting Started Guide
Getting Started with the Command Line Interface

provides an end-to-end walk-through of using the CLI to
launch an instance.
Basic Operations and Examples
This section provides information about command syntax, getting help, and managing input or
output.

COMMAND LINE S YNTAX
Most commands must specify a service, followed by a resource type and then an action. The
basic command line syntax is:
oci <service> <type> <action> <options>
For example, this syntax is applied as follows:
l compute is the <service>

l instance is the resource <type>
l launch is the <action>, and
l the rest of the command string consists of <options>.
The following command to launch an instance shows a typical command line construct.
oci compute instance launch --availability-domain "EMIr:PHX-AD-1" -c
ocid1.compartment.oc1..aaaaaaaal3gzijdlieqeyg35nz5zxil26astxxhqol2pgeyqdrggnx7jnhwa --shape
"VM.Standard1.1" --display-name "Instance 1 for sandbox" --image-id
ocid1.image.oc1.phx.aaaaaaaaqutj4qjxihpl4mboabsa27mrpusygv6gurp47kat5z7vljmq3puq --subnet-id
ocid1.subnet.oc1.phx.aaaaaaaaypsr25bzjmjyn6xwgkcrgxd3dbhiha6lodzus3gafscirbhj5bpa
Warning
In the previous example, you can provide a friendly

name for the instance using the --display-name
option. Avoid entering confidential information when
providing resource names or descriptions.
GETTING HELP WITH COMMANDS
You can get help for any command using --help, -h, or -?. For example:
oci --help
oci os bucket -h
oci os bucket create -?

VIEWING ALL THE CLI HELP
You can view the command line help.
FINDING OUT THE I NSTALLED VERSION OF THE CLI
To get the installed version of the CLI, run the following command.
oci --version
USING DATES AND TIMES IN CLI COMMANDS
The CLI supports the following accepted date formats.
l UTC with milliseconds

Format: YYYY-MM-DDTHH:mm:ss.sssTZD, Example: 2017-09-15T20:30:00.123Z
l UTC without milliseconds

Format: YYYY-MM-DDTHH:mm:ssTZD, Example: 2017-09-15T20:30:00Z
l UTC with minute precision

Format: YYYY-MM-DDTHH:mmTZD, Example: 2017-09-15T20:30Z
l Timezone with milliseconds

Format: YYYY-MM-DDTHH:mm:ss.sssTZD, Example: 2017-09-15T12:30:00.456-08:00
l Timezone without milliseconds

Format: YYYY-MM-DDTHH:mm:ssTZD, Example: 2017-09-15T12:30:00-08:00
l Timezone with offset with minute precision

Format: YYYY-MM-DDTHH:mmTZD, Example: 2017-09-15T12:35-08:00
l Date Only (This date will be taken as midnight UTC of that day)
Format: YYYY-MM-DD, Example: 2017-09-15
l Epoch seconds
Example: 1412195400

Note that In our datetime formats the T can be replaced with a space (for example, 2017-09-
15 20:30:00.123Z and 2017-09-15 20:30:00.123Z are both acceptable), and we support
time zones with and without the colon (for example, +10:00 and +1000 are both acceptable)
MANAGING CLI I NPUT AND OUTPUT
The CLI provides several options for managing command input and output.
PASSING COMPLEX INPUT
Complex input, such as arrays and objects with more than one value, are passed in JSON
format and can be provided as a string at the command line, as a file, or as a command line
string and as a file.
The following command, run on a MacOS or Linux machine, shows 2 values getting passed for
the --metadata object.
oci os bucket create -ns mynamespace --name mybucket --metadata '{"key1":"value1","key2":"value2"}' --
compartment-id ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga
On a Windows machine, you can also pass complex input as a JSON string, but you must
escape any strings within the JSON string. In the next example, backslash (\) characters are
used to escape the strings containing the metadata values.
oci os bucket create -ns mynamespace --name mybucket --metadata '
{\"key1\":\"value1\",\"key2\":\"value2\"}' --compartment-id
ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga
Note
JSON Errors
The error message "Parameter '<PARAMETER NAME>'

must be in JSON format." indicates that the value you
passed for the parameter with name "PARAMETER
NAME" was not valid JSON. This error is typically a
result of the JSON string not being escaped correctly.
For more information about using JSON strings, see Advanced JSON Options

FORMAT OUTPUT AS A TABLE
By default, all responses to a command are returned in JSON format. For example, the
following response is returned when you issue the command to get a list of regions.
{
"data": [
{
"key": "FRA",
"name": "eu-frankfurt-1"
},
{
"key": "IAD",
"name": "us-ashburn-1"
},
{
"key": "PHX",
"name": "us-phoenix-1"
}
{
"key": "LHR",
"name": "uk-london-1"
}
]
}
In some cases, readability can become an issue, which is easily resolved by formatting a
response as a table. To get a response to a command formatted as a table, run the following
command.
oci iam region list --output table
The following list of regions is returned as a two column table.

+-----+----------------+
| key | name |
+-----+----------------+
| FRA | eu-frankfurt-1 |
| IAD | us-ashburn-1 |
| PHX | us-phoenix-1 |
| LHR | uk-london-1 |
+-----+----------------+

FILTER OUTPUT
You can filter output using the JMESPath query option for JSON. Filtering is very useful when
dealing with large amounts of output. For example, run the following command with the
output table option to get a list of images.
oci compute image list -c
ocid1.compartment.oc1..aaaaaaaapxgklgmujxjzx2ypptfjrcieq7rrob2u2zbesh3wlafsgthhqtea --output table
The image information is returned in table format, but too much data is returned, which
overflows the width of the terminal. In addition, you may not need all the information that's
returned.
| base-image-id | compartment-id | create-image-allowed | display-name
| id | lifecycle-state | operating-system | operating-system-version | time-created
|
+---------------+----------------+----------------------+-----------------------------------------------
----------+----------------------------------------------------------------------------------+----------
-------+------------------+--------------------------+----------------------------------+| None
| None | True | Windows-Server-2012-R2-Standard-Edition-VM-2017.07.25-0 | ocid
1.image.oc1.phx.aaaaaaaab2xgy6bijtudhsgsbgns6zwfqnkdb2bp4l4qap7e4mehv6bv3qca | AVAILABLE | Windows
| Serv
er 2012 R2 Standard | 2017-07-25T23:59:59.311000+00:00 |
| None | None | True | Windows-Server-2012-R2-Standard-Edition-VM-
2017.04.03-0 | ocid
1.image.oc1.phx.aaaaaaaa53cliasgvqmutflwqkafbro2y4ywjebci5szc4eus5byy2e2b7ua | AVAILABLE | Windows
| Serv
er 2012 R2 Standard | 2017-04-03T19:42:22.938000+00:00 |
| None | None | True | Windows-Server-2012-R2-Standard-Edition-BM-
2017.07.25-0 | ocid
1.image.oc1.phx.aaaaaaaadcegaay43eux6uap55fhp6lqaqh37xgocscktwm2yr7ql4pcykxq | AVAILABLE | Windows
| Serv
er 2012 R2 Standard | 2017-07-25T20:55:37.937000+00:00 |
| None | None | True | Windows-Server-2012-R2-Standard-Edition-BM-
2017.04.13-0 | ocid1.image.oc1.phx.aaaaaaaa7xgecq2kt7tikqfrmshu6gwukoc3lcnf2iqtwmjyarlprp6j6lna |
AVAILABLE | Windows | Serv
er 2012 R2 Standard | 2017-04-13T17:36:50.840000+00:00 |
| None | None | True | Windows-Server-2008-R2-Standard-Edition-VM-
2017.08.03-0 | ocid
1.image.oc1.phx.aaaaaaaaejmyrf52wf2blf7jd7y2dcrjvg6dyulfyp7d3r3oarc5ayka5liq | AVAILABLE | Windows
| Serv
er 2008 R2 Standard | 2017-07-27T18:19:06.976000+00:00 |

| None | None | True | Oracle-Linux-7.4-2017.09.29-0

| ocid
1.image.oc1.phx.aaaaaaaa3g2xpzlbrrdknqcjtzv2tvxcofjc55vdcmpxdlbohmtt7encpana | AVAILABLE | Oracle
Linux | 7.4
| 2017-10-05T22:36:17.246000+00:00 |
| ocid
1.image.oc1.phx.aaaaaaaajan2cd2g65tphpaiegiz4lbs422rdc73okcu7dt2uya6p5szywsa | AVAILABLE | Oracle
Linux | 7.4
| 2017-09-11T23:12:18.644000+00:00 |
| ocid
1.image.oc1.phx.aaaaaaaabifl2bmaygtu4riw3vcuowl5cqwdzdqzwndqneoybcfcn2pgyc6a | AVAILABLE | Oracle
Linux | 7.4| 2017-08-25T01:21:37.176000+00:00 |
You can limit the amount of data returned by combining the --query option with --output
table to get the information you want from a command.
To get filtered image information returned in a table format, run the following command.
oci compute image list -c
ocid1.compartment.oc1..aaaaaaaapxgklgmujxjzx2ypptfjrcieq7rrob2u2zbesh3wlafsgthhqtea --output table --
query "data [*].{ImageName:\"display-name\", OCID:id}"
The previous command returns the following image information, formatted as a two column
table.
+---------------------------------------------------------+---------------------------------------------
-------------------------------------+
| ImageName | OCID
|
+---------------------------------------------------------+---------------------------------------------
-------------------------------------+
| Windows-Server-2012-R2-Standard-Edition-VM-2017.07.25-0 |
ocid1.image.oc1.phx.aaaaaaaab2xgy6bijtudhsgsbgns6zwfqnkdb2bp4l4qap7e4mehv6bv3qca |
ocid1.image.oc1.phx.aaaaaaaa53cliasgvqmutflwqkafbro2y4ywjebci5szc4eus5byy2e2b7ua |
| Windows-Server-2012-R2-Standard-Edition-BM-2017.07.25-0 |
ocid1.image.oc1.phx.aaaaaaaadcegaay43eux6uap55fhp6lqaqh37xgocscktwm2yr7ql4pcykxq |
| Windows-Server-2012-R2-Standard-Edition-BM-2017.04.13-0 |
ocid1.image.oc1.phx.aaaaaaaa7xgecq2kt7tikqfrmshu6gwukoc3lcnf2iqtwmjyarlprp6j6lna |
ocid1.image.oc1.phx.aaaaaaaaejmyrf52wf2blf7jd7y2dcrjvg6dyulfyp7d3r3oarc5ayka5liq |

| Oracle-Linux-7.4-2017.09.29-0 |
ocid1.image.oc1.phx.aaaaaaaa3g2xpzlbrrdknqcjtzv2tvxcofjc55vdcmpxdlbohmtt7encpana |
| Oracle-Linux-7.4-2017.08.25-1 |
ocid1.image.oc1.phx.aaaaaaaajan2cd2g65tphpaiegiz4lbs422rdc73okcu7dt2uya6p5szywsa |
| Oracle-Linux-7.4-2017.08.25-0 |
ocid1.image.oc1.phx.aaaaaaaabifl2bmaygtu4riw3vcuowl5cqwdzdqzwndqneoybcfcn2pgyc6a |
| Oracle-Linux-7.3-2017.07.17-1 |
ocid1.image.oc1.phx.aaaaaaaa7jvfm572d4ehcgh3ijapvhrt52voel33ispumnygi3kl7mph55ha |
| Oracle-Linux-7.3-2017.07.17-0 |
ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa |
| Oracle-Linux-6.9-2017.09.29-0 |
ocid1.image.oc1.phx.aaaaaaaa2d243dmn6mj53zieyap5bdvtq7xfmr5kg5xulrldbjzdavaaoj6a |
| Oracle-Linux-6.9-2017.08.25-0 |
ocid1.image.oc1.phx.aaaaaaaavlwrtcgz2mx6c4q4qg4gwvibx6g7xqkowe3tbbwjnifybwmexpnq |
| Oracle-Linux-6.9-2017.07.17-0 |
ocid1.image.oc1.phx.aaaaaaaa3s4v5eamndtyghbo4bj2mhobkwjwbz3eowyy5cebmrsoxvoopixa |
| CentOS-7-2017.09.14-0 |
ocid1.image.oc1.phx.aaaaaaaauqtvzhqplzuyesb5tctig6qrwoavpnfiwdkvuynu7z646z72ahcq |
| CentOS-7-2017.07.17-0 |
ocid1.image.oc1.phx.aaaaaaaahmts5c5nktcnqsu6ppom72d7dnvkmqsoaavpsiklamn7qd3a7szq |
| CentOS-7-2017.04.18-0 |
ocid1.image.oc1.phx.aaaaaaaaamx6ta37uxltor6n5lxfgd5lkb3lwmoqurlpn2x4dz5ockekiuea |
| CentOS-6.9-2017.09.14-0 |
ocid1.image.oc1.phx.aaaaaaaagedr7qsbpxjylieetj7dy2r4xoq6p65v3i6y4simkhgyww2ibzxq |
| CentOS-6.9-2017.07.17-0 |
ocid1.image.oc1.phx.aaaaaaaalm3mr4lpsnzjev2nzmmkhpiy7yxu3456qyg7r4nvjieslp4yngtq |
| CentOS-6.8-2017.06.13-0 |
ocid1.image.oc1.phx.aaaaaaaauk5k4km4epm7fxj5ifuylvnyjfklmukqcg25clayx3ucuqizjbia |
| Canonical-Ubuntu-16.04-2017.08.22-0 |
ocid1.image.oc1.phx.aaaaaaaalzhdvphf77qgvqo2apmve7o4s4jo77rluaf456qdzrtwmkq2xhra |
ocid1.image.oc1.phx.aaaaaaaak2idogwetkehtdvo7m673ojuucpfxhybd3ehun7izzgjqi4c4gga |
ocid1.image.oc1.phx.aaaaaaaae3a3oedsmmwsqu4dsrzntekefgq7vosngn4r6u6n5mis7dwpxxpa |
ocid1.image.oc1.phx.aaaaaaaa2wjumduuoq6rqprrsmgu53eeyzp47vjztn355tkvsr3m2p57woqq |
ocid1.image.oc1.phx.aaaaaaaaelnit3ag2zy3u5664shbjqgl6c33g2i436wix6xb5tqcsa7klnoa |
+---------------------------------------------------------+---------------------------------------------
-------------------------------------+
For more information about the JMESPath query language for JSON, see JMESPath.

EXAMPLES
This section provides examples of basic operations using the CLI.
Note
Using Environment Variables for OCIDs
Several of the CLI examples use environment variables

for OCIDs, such as:
l $T for a tenancy OCID

l $C for a compartment OCID
For example:
T=ocid1.tenancy.oc1..aaaaaaaaba3pv6wm2ytdrwrx32uzr4h25vkcr4jqa
e5f15p2b2qstifsfdsq
C=ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3
ukc5fldrwpp2jojdcypxfga
To get a namespace, run the following command.

oci os ns get
To list compartments, run the following command.

oci iam compartment list -c $T
To get a list of buckets, run the following command.

oci os bucket list -ns mynamespace --compartment-id $C
To list users and limit the output, run the following command.
oci iam user list --compartment-id $T --limit 5
To add a user to a group, run the following command.

oci iam group add-user --user-id
ocid1.user.oc1..aaabcaaaxkkhhtmghvqqq7rgvzwuj3drwmtlsgz6sbfo7y4uc5sprzli377q --group-id
ocid1.group.oc1..aaabcaaa66plootq6uuwwxhfdw2lsdqtgeb6l4pjsv5eeuenxrauujj35b7b

Advanced Operations and Examples
The CLI provides command options that support advanced input and output operations.
ADVANCED JSON OPTIONS
You can get the correct JSON format for command options and commands.
l For a command option, use --generate-param-json-input and specify the command

option that you want to get the JSON for. To generate the JSON for creating or updating
a security rule, run the following command.
oci network security-list create --generate-param-json-input ingress-security-rules
Response from the Command

[
{
"icmpOptions": {
"code": 0,
"type": 0
},
"isStateless": true,
"protocol": "string",
"source": "string",
"tcpOptions": {
"destinationPortRange": {
"max": 0,
"min": 0
},
"sourcePortRange": {
"max": 0,
"min": 0
}
},
"udpOptions": {
"max": 0,
"min": 0
},

"max": 0,
"min": 0
}
}
},
{
"icmpOptions": {
"code": 0,
"type": 0
},
"isStateless": true,
"protocol": "string",
"source": "string",
"tcpOptions": {
"max": 0,
"min": 0
},
"max": 0,
"min": 0
}
},
"udpOptions": {
"max": 0,
"min": 0
},
"max": 0,
"min": 0
}
}
}
]
l For an entire command, use --generate-full-command-json-input. To generate the

JSON for launching an instance, run the following command.
oci compute instance launch --generate-full-command-json-input

Response from the Command

{
"assignPublicIp": true,
"availabilityDomain": "string",
"compartmentId": "string",
"displayName": "string",
"extendedMetadata": {
"string1": {
"string1": "string",
"string2": "string"
},
"string2": {
"string2": "string"
}
},
"hostnameLabel": "string",
"imageId": "string",
"metadata": {
"string2": "string"
},
"privateIp": "string",
"shape": "string",
"skipSourceDestCheck": true,
"subnetId": "string",
"vnicDisplayName": "string"
}
ORDER OF PRECEDENCE FOR JSON INPUT
The CLI supports combining arguments on the command line with file input. However, if the
same values are provided in a file and on the command line, the command line takes
precedence.
USING A JSON FILE FOR COMPLEX INPUT
You can pass complex input from a file by referencing it from the command line. For Windows
users, this removes the requirement of having to escape JSON text. You provide a path to the
file using the file:// prefix.

PATH TYPES
Using testfile.json as an example, the following types of paths are supported.
l Relative paths from the same directory, for example: file://testfile.json and
file://relative/path/to/testfile.json
l Absolute paths on Linux, MacOS or Unix, for example:

file:///absolute/path/to/testfile.json
l Full file paths on Windows, for example: file://C:\path\to\testfile.json
Note
File Path Expansions
File path expansions, such as "~/", "./", and "../", are

supported. On Windows, the "~/" expression expands to
your user directory, which is stored in the
%USERPROFILE% environment variable. Using
environment variables in paths is also supported.
FILE LOCATIONS
The following file locations are supported.
l Your home directory.

oci os bucket create -ns mynamespace --name mybucket --compartment-id
ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga --metadata
file://~/testfile.json
l The current directory.

file://testfile.json
l The /tmp directory (Linux, Unix, or MacOS).


file:///tmp/testfile.json
l The C:\temp directory (Windows).

file://C:\temp\testfile.json
E XAMPLES OF USING A JSON FILE AS INPUT
The examples in this section use JSON that's generated for a command option and an entire
command. The JSON is saved in a file, edited, and then used as command line input.
USE FILE I NPUT FOR A COMMAND OPTION
This end-to-end example shows how to generate the JSON for a security list id option used to
create a subnet. The JSON is saved in a file, edited, and then used as command line input.
Use a JSON File as Input for a Security List Option

1. To generate the JSON for the security-list-ids option, run the following command.
oci network subnet create --generate-param-json-input security-list-ids
2. Create a file and add the following content, which was returned in step 1. This content
doesn't have to be escaped or on a single line, it just has to contain valid JSON.
[
"string",
"string"
]
3. Edit the file and replace the "string" values with values, as shown in the following
example.
[
"ocid1.securitylist.oc1.phx.aaaaaaaaw7c62ybv4676muq5tdrwup3v2maiquhbkbh4sf75tjcf5dm6kvlq",
"ocid1.securitylist.oc1.phx.aaaaaaaa7snx4jh5drwo2h33rwcdqev6elir55hnrhi2yfndjfons5rcqk4q"
]

4. Save the file as "security-list.json".

5. To create the subnet using "security-list.json" as input, run the following command.
oci network subnet create --vcn-id
ocid1.vcn.oc1.phx.aaaaaaaa6wmuahgxejkv7ukyruqdrwlmrumtl6vyisxxxavagiqw2eeet2sa -c
ocid1.compartment.oc1..aaaaaaaal3gzijdliedxxhqol2rggndrwyg35nz5zxil26astpgeyq7jnhwa --
availability-domain "EMIr:PHX-AD-1" --display-name TESTSUB --dns-label "testinstances" --cidr-
block "10.0.0.0/16" --security-list-ids file://security-list.json
USE FILE I NPUT FOR AN ENTIRE COMMAND
This end-to-end example shows how to generate the JSON to create a virtual cloud network
(VCN). The JSON is saved in a file, edited, and then used as command line input.
Use a JSON File as Input to Create a VCN

1. To generate the JSON needed to create a VCN, run the following command.
oci network vcn create --generate-full-command-json-input
2. Create a file and add the following content, which was returned in step 1. This content
doesn't have to be escaped or on a single line, it just has to contain valid JSON.
{
"cidrBlock": "string",
"compartmentId": "string",
"displayName": "string",
"dnsLabel": "string"
}
3. Edit the file and replace the "string" values with values, as shown in the following
example.
{
"cidrBlock": "10.0.0.0/16",
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaal3gzijdliedxxhqol2rggndrwyg35nz5zxil26astpgeyq7jnhwa",
"displayName": "TestVCN",
"dnsLabel": "testdns"
}

4. Save the file and name it "create-vcn.json"

5. To create the VCN using "create-vcn.json" as input, run the following command.
oci network vcn create --from-json file://create-vcn.json
EXAMPLES
The following examples show how you can use the CLI to complete complex tasks in Oracle
Cloud Infrastructure.
WORKING WITH OBJECT STORAGE
You can use the CLI for several object operations with the Object Storage service.
UPLOADING AND DOWNLOADING FILES
Objects can be uploaded from a file or from the command line (STDIN), and can be
downloaded to a file or to the command line (STDOUT).
Upload an object:
oci os object put -ns mynamespace -bn mybucket --name myfile.txt --file /Users/me/myfile.txt --metadata
'{"key1":"value1","key2":"value2"}'
Upload object contents from the command line (STDIN):

oci os object put -ns mynamespace -bn mybucket --name myfile.txt --file <--'object content'
Download an object:
oci os object get -ns mynamespace -bn mybucket --name myfile.txt --file /Users/me/myfile.txt
Print object contents to the command line (STDOUT):

oci os object get -ns mynamespace -bn mybucket --name myfile.txt --file -
BULK OPERATIONS IN OBJECT S TORAGE
The CLI supports the following bulk operations in Object Storage:

l Uploading files in a directory and all its subdirectories to a bucket

# Upload all the files in a directory.
oci os object bulk-upload -ns mynamespace -bn mybucket --src-dir path/to/upload/directory
l Downloading all objects, or all the objects that match a specified prefix, in a bucket
# Download all the objects.
oci os object bulk-download -ns mynamespace -bn mybucket --download-dir
path/to/download/directory
# Download all the objects that match the specified prefix.

oci os object bulk-download -ns mynamespace -bn mybucket --download-dir
path/to/download/directory --prefix myprefix
l Deleting all objects, or all the objects that match a specified prefix, in a bucket
# Delete all the objects.
oci os object bulk-delete -ns mynamespace -bn mybucket
# Delete objects that match the specified prefix.

oci os object bulk-delete -ns mynamespace -bn mybucket --prefix myprefix
Bulk operations support several options that let you:
l Overwrite or skip files/objects using --overwrite or --no-overwrite. (Note: If you

pass neither of these options you are prompted for confirmation every time there is
something to overwrite.)
l Limit delete, upload, or download operations using --prefix and/or --delimiter
l Preview a bulk deletion with --dry-run
To get more information about the commands for bulk operations, run the following help
commands:
# bulk-upload
oci os object bulk-upload -h
# bulk-download
oci os object bulk-download -h
# bulk-delete
oci os object bulk-delete -h

MULTIPART OPERATIONS IN OBJECT S TORAGE
Multipart operations for Object Storage include object uploads and downloads.
Multipart Uploads
Large files can be uploaded to Object Storage in multiple parts to speed up the upload. By
default, files larger than 128 MiB are uploaded using multipart operations. You can override
this default by using the --no-multipart option.
You can configure the following options for the oci os object put command:
l --no-multipart overrides an automatic multipart upload if the object is larger than

128 MiB. The object is uploaded as a single part, regardless of size.
l --part-size in MiB, to use in a multipart operation. The default part size is 128 MiB and
a part size that you specify must be greater than 10 MiB. If the object is larger than the
--part-size, it is uploaded in multiple parts.
l --parallel-upload-count, to specify the number of parallel operations to perform.
You can use this value to balance resources and upload times. A higher value may
improve times but consume more system resources and network bandwidth. The
default value is 10.
l --resume-put command lets you resume a large file upload if it was interrupted.
Note
Multipart Uploads from STDIN
Objects uploaded from STDIN are uploaded in multiple

parts. If the object content is smaller than 10 MiB, the
upload is only 1 part, and the MultipartUpload API is
used for the upload. Specifying --no-multipart when
uploading from STDIN will result in an error.
The following example shows the command for a multipart upload if the object is larger than
200 MiB.

oci os object put -ns my-namespace -bn my-bucket --file path/to/large/file --part-size 200
For more information about multipart uploads, see Using Multipart Uploads.
Multipart Downloads
Large files can be downloaded from Object Storage in multiple parts to speed up the
download.
You can configure the following options for the oci os object get command:
l --multipart-download-threshold lets you specify the size, in MiB at which an object

should be downloaded in multiple parts. This size must be at least 128 MiB.
l --part-size, in MiB, to use for a download part. This gives you the flexibility to use
more (smaller size) or fewer (larger size) parts as appropriate for your requirements.
For example, compute power and network bandwidth. The default minimum part size is
120 MiB.
l --parallel-download-count lets you specify how many parts are downloaded at the
same time. A higher value may improve times but consume more system resources and
network bandwidth. The default value is 10.
The following example shows the command to download any object with a size greater than
500 MiB. The object is downloaded in 128 MiB parts.
oci os object get -ns my-namespace -bn my-bucket --name my-large-object --multipart-download-threshold
500 --part-size 128
Upgrading the CLI

This topic describes the processes to upgrade or remove the CLI.
Upgrading the CLI
If you installed the CLI manually, use one of the following commands to upgrade the CLI.
l To upgrade a standard installation, run the following command.

pip install oci-cli --upgrade

l To upgrade a standard virtualenv installation, run the following command.

cli-testing/bin/pip install oci-cli --upgrade
If you installed the CLI using the install script, use the following process to upgrade the CLI:
l Run the install script and specify the same install directory.
l When prompted, reply Y to overwrite the existing installation.
Uninstalling the CLI
To uninstall the CLI on a physical machine, run the following command.

pip uninstall oci-cli
To uninstall the CLI running in virtualenv, run the following command.

cli-testing/bin/pip uninstall oci-cli
Troubleshooting the CLI

This topic describes how to resolve issues that you might encounter when installing Python or
the CLI, or when using the CLI.
Service Errors
Any operation resulting in a service error causes an error of type "ServiceError" to be

returned by the CLI. For information about common service errors that Oracle Cloud
Infrastructure returns, see API Errors.
Oracle Linux Permissions Issues
On Oracle Linux 7.3, if you encounter permission issues when running pip install, you
might need to use sudo.
oci Command Not Found
If the oci command isn't found, this can be caused by one of the following reasons:

l pip installed the package to a different virtual environment than your active one.
l You switched to a different active virtual environment after you installed the CLI.
To determine where the CLI is installed, run the which pip and which oci commands.
Wheel File Won't Install
If the wheel file won't install, verify that pip is up to date. To update pip, run the pip install
-U pip command. Try to install the wheel again.
Windows Issues
If the oci command isn't found, make sure that the oci.exe location is in your path (for
example, the Scripts directory in your Python installation).
Contact Information
If you want to contribute ideas, report a bug, get notified about updates, have questions, or
want to give feedback, use one of the following links.
CONTRIBUTIONS
Got a fix for a bug, or a new feature you'd like to contribute? The CLI is open source and
accepting pull requests on GitHub.
NOTIFICATIONS
To be notified when a new version of the CLI is released, subscribe to the Atom feed.
QUESTIONS OR FEEDBACK
Ways to get in touch:
l GitHub: To file bugs and feature requests only.

l Stack Overflow: Use the oracle-cloud-infrastructure and oci-cli tags in your post.
l Developer Tools section of the Oracle Cloud forums
l My Oracle Support

Data Transfer Utility

This topic describes how to install and configure the Data Transfer Utility. In addition, this
topic describes the syntax for the Data Transfer Utility commands and its output.
o Object Storage
o Archive Storage
o Data Transfer Service
l Licensing: The Data Transfer Utility is licensed under the Universal Permissive License
1.0 and the Apache License 2.0. Third-party content is separately licensed as described
in the code.
l Downloading:
o Download the .deb file to install on Debian or Ubuntu
o Download the .rpm file to install on Oracle Linux or Red Hat Linux
For details about performing specific data transfer tasks using the Data Transfer Utility, see
Managing HDD Data Transfers.
Prerequisites
To install and use the Data Transfer Utility, you must:
l Have an Oracle Cloud Infrastructure account

l Create the required users and groups with the required IAM policies:
See Preparing for Data Transfers for details.
l Have a host machine with the following installed:

o Oracle Linux 6 or greater, Ubuntu 14.04 or greater, or SUSE 11 or greater
o Cryptsetup 1.0.3 or greater

o hdparm 9.0 or later

o Java 1.7 or greater
l Have access to the public Internet for the Data Transfer Utility to communicate with the
Data Transfer Service in the specified OCI region. If your environment requires
Internet-aware applications to use network proxies, you can configure the Data
Transfer Utility to use your environment's network proxies by setting the standard Linux
environment variables on your host machine:
export https_proxy=http://www-proxy.example.com:80
l One or more transfer devices that meet the following requirements:

o SATA II/III 2.5" or 3.5" HDDs
o External USB 2.0/3.0 HDDs
o HDDs must have all partitions and file systems removed
o HDDs must provide a valid response to the hdparm -I <device> Linux command
Installing the Data Transfer Utility

Download and install the Data Transfer Utility installer that corresponds to your host
machine's operating system.
To install the Data Transfer Utility on Debian or Ubuntu

1. If you have not done so already, download the .deb file.
2. Issue the apt install command as the root user that has write permissions to the
/opt directory.
sudo apt install ./dts-X.Y.Z.x86_64.deb
Where X.Y.Z are the version numbers that match the installer you downloaded.
3. Confirm that the Data Transfer Utility installed successfully.
sudo dts --help

To install the Data Transfer Utility on Oracle Linux or Red Hat Linux
1. If you have not done so already, download the .rpm file.
2. Issue the yum install command as the root user.
sudo yum localinstall ./dts-X.Y.Z.x86_64.rpm
Where X.Y.Z are the version numbers that match the installer you downloaded.
3. Confirm that the Data Transfer Utility installed successfully.
sudo dts --help
Configuring the Data Transfer Utility

Before using the Data Transfer Utility, you must create two configuration files with the
required credentials. One configuration file is for the data transfer administrator (the IAM
user with the authorization and permissions to create and manage transfer jobs) and the other
is for the data transfer upload user (the temporary IAM user that Oracle uses to upload your
data on your behalf).
Configuration File for the Data Transfer Administrator
The data transfer administrator /root/.oci/config configuration file requires the following
structure:
[DEFAULT]
user=<The OCID for the data transfer administrator>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are: us-phoenix-1 and
us-ashburn-1>
For example:
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazravan2fktvutqp3bpmzlfl7nlsdtvzexnaxiuz7mbxuexxxxxx
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=~/.oci/ocid1.user.oc1..aaaaaaaazravan2fktvutqp3bpmzlfl7nlsdtvzexnaxiuz7mbxuefievzzq.pem

tenancy=ocid1.tenancy.oc1..aaaaaaaa6cdze5nyyxtk3exdy4ynrk3uvin3ewi6iu7pswba7nh4dx6qrzcq
region=us-phoenix-1
For the data transfer administrator, you can create a single configuration file that contains
different profile sections with the credentials for multiple users, and then use the --profile
option to specify which profile to use in the command. Here is an example of a data transfer
administrator configuration file with different profile sections:
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazravan2fktvutqp3bpmzlfl7nlsdtvzexnaxiuz7mbxuexxxxxx
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..bbbbbbbzravan2fktvutqp3bpmzlfl7nlsdtvzexnaxiuz7mbxueyyyyyyy
region=us-ashburn-1
By default, dts job create uses the DEFAULT profile.

dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name>
Use the following command to specify a different profile:

dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name> --
profile <profile_name>
Configuration File for the Data Transfer Upload User
The data transfer upload user /root/.oci/config_upload_user configuration file requires

the following structure:
[DEFAULT]
user=<The OCID for the data transfer upload user>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are: us-phoenix-1 and
us-ashburn-1>
For example:

[DEFAULT]
user=ocid1.user.oc1..ccccccccczravan2fktvutqp3bpmzlfl7nlsdtvzexnaxiuz7mbxuezzzzzz
region=us-phoenix-1
Configuration File Entries
The following table lists the basic entries that are required for each configuration file and
where to get the information for each entry.
Note
Data Transfer Service Does Not Support Passphrases on Private

Keys
While we recommend encrypting a private key with a

passphrase when generating API signing keys, Data
Transfer service does not support passphrases on the
key file required for the config_upload_user. If you use
a passphrase, Oracle personnel will not be able to
upload your data.
Entry Description and Where to Get the Value Required?
user OCID of the data transfer administrator or the Yes

data transfer upload user, depending on
which profile you are creating. To get the
value, see Required Keys and OCIDs.
fingerprint Fingerprint for the key pair being used. To get Yes
the value, see Required Keys and OCIDs.

key_file Full path and filename of the private key. Yes
Important: The key pair must be in PEM

format. For instructions on generating a key
pair in PEM format, see Required Keys and
OCIDs.
tenancy OCID of your tenancy. To get the value, see Yes

Required Keys and OCIDs.
region An Oracle Cloud Infrastructure region. See Yes

Regions and Availability Domains.
Data transfer is currently supported in us-

ashburn-1 and us-phoenix-1.
You can verify the data transfer upload user credentials using the following command:
dts job verify-upload-user-credentials --bucket <bucket_name>
Configuration File Location
The location of the configuration files is /root/.oci/config.
Using the Data Transfer Utility

This section provides an overview of the syntax for the Data Transfer Utility.
Syntax
The basic Data Transfer Utility syntax is:

dts <resource> <action> <options>
This syntax is applied, as follows:

l dts is the shortened utility command name

l job is a resource <resource>
l create is an <action>, and
l the rest of the utility strings <options>.
The following command to create a transfer job shows a typical Data Transfer Utility
construct.
dts job create --compartment-id
ocid1.compartment.oc1..aaaaaaaamnk2ilreg5fkgu7rarfbbhdv3a5ji4eixxgkl4uprbqk6aefv5sq --bucket mybucket --
display-name "mycompany transfer1"
Warning
In the previous example, provide a friendly name for

the transfer job using the --display-name option.
Avoid entering confidential information when providing
resource names or descriptions.
Getting Help with Commands
You can get help using --help, -h, or -?. For example:
dts --help
Finding Out the Installed Version of the Data Transfer Utility
To get the installed version of the Data Transfer Utility, run the following command:
dts --version
What's Next
You are now ready to perform data transfer-related tasks. See Managing HDD Data Transfers.

SDKs and Other Tools

This page lists the SDKs and other tools available for using Oracle Cloud Infrastructure
resources programmatically or from a command line.
l Java SDK
l Python SDK
l Ruby SDK
l Go SDK
l Chef Knife Plugin
l Oracle Cloud Infrastructure Compute Jenkins Plugin
l Hadoop Distributed File System (HDFS) for Object Storage
l Terraform Provider
See these related topics:
l Required Keys and OCIDs

l SDK and Tool Configuration
l API Errors
Java SDK
This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Java
SDK.
o Audit
o Database
o IAM

o Load Balancing
o Object Storage
o DNS
o File Storage
o Email Delivery
l Licensing: This SDK and sample is dual licensed under the Universal Permissive
License 1.0 and the Apache License 2.0; third-party content is separately licensed as
described in the code.
l Download: GitHub
l API reference documentation: Java SDK API Reference
Requirements
To use the Java SDK, you must have:
l An Oracle Cloud Infrastructure account.

permissions. This can be a user for yourself, or another person/system that needs to
call the API. For an example of how to set up a new user, group, compartment, and
policy, see Adding Users. For a list of typical policies you may want to use, see
Common Policies.
l A key pair used for signing API requests, with the public key uploaded to Oracle. Only
the user calling the API should be in possession of the private key. See Configuring the
SDK below.
l Java 8 (for Java 7, see Java 7 Compatibility).
l A TTL value of 60. For more information, see Configuring JVM TTL for DNS Name
Lookups.
JAVA 7 COMPATIBILITY
To use Java 7, you must have a version that supports TLS 1.2.
For more information, see:

l https://blogs.oracle.com/java-platform-group/entry/java_8_will_use_tls
l http://bugs.java.com/view_bug.do?bug_id=6916074
l https://blogs.oracle.com/java-platform-group/entry/diagnosing_tls_ssl_and_https
CONFIGURING JVM TTL FOR DNS NAME LOOKUPS
The Java Virtual Machine (JVM) caches DNS responses from lookups for a set amount of time,
called time-to-live (TTL). This ensures faster response time in code that requires frequent
name resolution.
The JVM uses the networkaddress.cache.ttl property to specify the caching policy for DNS
name lookups. The value is an integer that represents the number of seconds to cache the
successful lookup. The default value for many JVMs, -1, indicates that the lookup should be
cached forever.
Because resources in Oracle Cloud Infrastructure use DNS names that can change, we
recommend that you change the the TTL value to 60 seconds. This ensures that the new IP
address for the resource is returned on next DNS query. You can change this value globally or
specifically for your application:
l To set TTL globally for all applications using the JVM, add the following in the $JAVA_
HOME/jre/lib/security/java.security file:
networkaddress.cache.ttl=60
l To set TTL only for your application, set the following in your application's initialization
code:
java.security.Security.setProperty("networkaddress.cache.ttl" , "60");
Downloading the SDK
You can download the Java SDK as a zip archive from GitHub. It contains the SDK, all of its
dependencies, documentation, and examples. For best compatibility and to avoid issues, use
the version of the dependencies included in the archive. Some notable issues are:
l Bouncy Castle: The SDK bundles 1.52, which is required if you use encrypted PEM keys
for authentication. If you don't use encrypted PEM keys, you can use a newer version.

l Jax-RS API: The SDK bundles 2.0.1 of the spec. Older versions will cause issues.
l Jersey Core and Client: The SDK bundles 2.24.1, which is required to support large
object uploads to Object Storage. Older versions will not support uploads greater than
~2.1 GB.
Configuring the SDK
The SDK services need two types of configuration: credentials and client-side HTTP settings.
CONFIGURING CREDENTIALS
First, you need to set up your credentials and config file. For instructions, see SDK and Tool
Configuration.
Next you need to set up the client to use the credentials. The credentials are abstracted
through an AuthenticationDetailsProvider interface. Clients can implement this however
you choose. We have included a simple POJO/builder class to help with this task
(SimpleAuthenticationDetailsProvider).
l You can load a config with or without a profile:

ConfigFile config
= ConfigFileReader.parse("~/.oci/config");
ConfigFile configWithProfile
= ConfigFileReader.parse("~/.oci/config", "DEFAULT");
l The private key supplier can be created with the file path directly, or using the config
file:
Supplier<InputStream> privateKeySupplier
= new SimplePrivateKeySupplier("~/.oci/oci_api_key.pem");
Supplier<InputStream> privateKeySupplierFromConfigEntry
= new SimplePrivateKeySupplier(config.get("key_file"));
l To create an auth provider using the builder:

AuthenticationDetailsProvider provider
= SimpleAuthenticationDetailsProvider.builder()
.tenantId("myTenantId")
.userId("myUserId")

.fingerprint("myFingerprint")
.privateKeySupplier(privateKeySupplier)
.build();
l To create an auth provider using the builder with a config file:

= SimpleAuthenticationDetailsProvider.builder()
.tenantId(config.get("tenancy"))
.userId(config.get("user"))
.fingerprint(config.get("fingerprint"))
.privateKeySupplier(privateKeySupplier)
.build();
l Finally, if you use standard config file keys and the standard config file location, you can
simplify this further by using ConfigFileAuthenticationDetailsProvider:
= new ConfigFileAuthenticationDetailsProvider("ADMIN_USER");
CONFIGURING CLIENT -SIDE OPTIONS
Create a client-side configuration through the ClientConfiguration class. If you do not

provide your own configuration, the Java SDK uses a default configuration. To provide your
own configuration, use the following:
ClientConfiguration clientConfig
= ClientConfiguration.builder()
.connectionTimeoutMillis(3000)
.readTimeoutMillis(60000)
.build();
After you have both a credential configuration and the optional client configuration, you can
start creating service instances.
CONFIGURING CUSTOM OPTIONS
In the config file, you can insert custom key-value pairs that you define, and then reference
them as necessary. For example, you could specify a frequently used compartment ID in the
config file like so (highlighted in red italics):
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcmdy5eqbb6qt2jvpkanghtgdaqedqw3rynjq

fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2bcmdyt2j6rx32uzr4h25vqstifsfdsq
custom_compartment_
id=ocid1.compartment.oc1..aaaaaaaayzfqeibduyox6iib3olcmdar3ugly4fmameq4h7lcdlihrvur7xq
Then you can retrieve the value like so:

ConfigFile config
= ConfigFileReader.parse("~/.oci/config");
String compartmentId = config.get("custom_compartment_id");
Raw Requests
Raw requests are useful, and in some cases necessary. Typical use cases are: when using
your own HTTP client, making a OCI-authenticated request to an alternate endpoint, and
making a request to a OCI API that is not currently supported in the SDK. The Java SDK
exposes the DefaultRequestSigner class that you can use to create a RequestSigner
instance for non-standard requests.
The Raw Request example on GitHub shows how to:
l create an authentication provider and request signer

l integrate with an HTTP client (Jersey in this example) to authenticate requests
Setting the Endpoints
Service endpoints can be set in one of two ways.
l Call setEndpoint() on the service instance. This lets you specify a full host name (for
example, https://www.example.com).
l Call setRegion() on the service instance. This selects the appropriate host name for
the service for the given region. However, if the service is not supported in the region
you set, the Java SDK returns an error.
Note that a service instance cannot be used to communicate with different regions. If you
need to make requests to different regions, create multiple service instances.

Forward Compatibility
Some response fields are enum-typed. In the future, individual services may return values
not covered by existing enums for that field. To address this possibility, every enum-type
response field has an additional value named "UnknownEnumValue". If a service returns a
value that is not recognized by your version of the SDK, then the response field will be set to
this value. Please ensure that your code handles the "UnknownEnumValue" case if you have
conditional logic based on an enum-typed field.
Making Synchronous Calls
To make synchronous calls, create an instance of the synchronous client. The general pattern
for synchronous clients is that for a service named Example, there will be an interface named
ExampleService, and the synchronous client implementation will be called
ExampleServiceClient. Here's an example of creating an Object Storage client:
AuthenticationDetailsProvider provider = ...;
ObjectStorage clientWithDefaultClientConfig = new ObjectStorageClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
ClientConfiguration clientConfig = ...;

ObjectStorage clientWithExplicitClientConfig = new ObjectStorageClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);
Synchronous calls will block until the response is available. All SDK APIs return a response
object (regardless of whether or not the API sends any content back). The response object
typically contains at least a request ID that you can use when contacting Oracle support for
help on a particular request.
ObjectStorage client = ...;
GetBucketResponse response = client.getBucket(
GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
String requestId = response.getOpcRequestId();
Bucket bucket = response.getBucket();
System.out.println(requestId);
System.out.println(bucket.getName());

Making Asynchronous Calls
To make asynchronous calls, create an instance of the asynchronous client. The general
pattern for asynchronous clients is that for a service named Example, there will be an
interface named ExampleServiceAsync, and the asynchronous client implementation will be
called ExampleServiceAsyncClient. Here's an example of creating an Object Storage client:
AuthenticationDetailsProvider provider = ...;
ObjectStorageAsync clientWithDefaultClientConfig = new ObjectStorageAsyncClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
ClientConfiguration clientConfig = ...;

ObjectStorageAsync clientWithExplicitClientConfig = new ObjectStorageAsyncClient(provider,
clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);
Asynchronous calls will return immediately. You need to provide an AsyncHandler that will be
invoked after the call completes either successfully or unsuccessfully:
ObjectStorageAsync client = ...;
AsyncHandler<GetBucketRequest, GetBucketResponse> handler = new AsyncHandler<GetBucketRequest,

GetBucketResponse>() {
@Override
public void onSuccess(GetBucketRequest request, GetBucketResponse response) {
Bucket bucket = response.getBucket();
System.out.println(bucket.getName());
}
@Override
public void onError(GetBucketRequest request, Throwable error) {
error.printStackTrace();
}
};
Future<GetBucketResponse> future = client.getBucket(

GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build(),
handler);

Paginated Responses
Some APIs return paginated result sets. The Response objects will contain a method to fetch
the next page token. If the token is null, there are no more items. If it is not null, you can
make an additional request (setting the token on the Request object) to get the next page of
responses. Note, some APIs may return a token even if there are no more results, so it's
important to also check whether any items were returned and stop if there are none. Here's
an example in the Object Storage API:
ListBucketsRequest.Builder builder =
ListBucketsRequest.builder().namespaceName(namespace);
String nextPageToken = null;
do {
builder.page(nextPageToken);
ListBucketsResponse listResponse = client.listBuckets(builder.build());
List<Bucket> buckets = listResponse.getItems();
// handle buckets
nextPageToken = listResponse.getOpcNextPage();
} while (nextPageToken != null);
In addition to working with page tokens manually, each service client exposes a
getPaginators() method. ThegetPaginators() method returns a Paginator object, which
contains methods that return objects of type Iterable, which abstracts away the need to
manually deal with page tokens.
We support two approaches to using iterable:
l You can iterate over the Response objects that are returned by the list operation. These
are referred to as ResponseIterators, and their methods are suffixed with
"ResponseIterator," for example, listUsersResponseIterator.
l You can iterate over the resources/records that are listed. These are referred to as
RecordIterator, and their methods are suffixed with "RecordIterator," for example,
listUsersRecordIterator.
Following are examples that illustrate both styles of using the iterator:

/// Response iterator

Iterable<ListUsersResponse> responseIterator = identityClient.getPaginators().listUsersResponseIterator
(request);
for (ListUsersResponse response : responseIterator) {
for (User user : response.getItems()) {
System.out.println(user);
}
}
/// Record iterator

Iterable<User> recordIterator = identityClient.getPaginators().listUsersRecordIterator(request);
for (User user : recordIterator) {
System.out.println(user);
}
Exception Handling
Exceptions are runtime exceptions (unchecked), so they do not show up in method signatures.
All APIs can throw a BmcException. The exception will contain information about the
underlying HTTP request (i.e., status code or timeout). BmcException also contains a
getOpcRequestId method that you can use to obtain the request ID to provide when
contacting support.
try {
GetBucketResponse response = client.getBucket(
GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
} catch (BmcException e) {
String requestId = e.getOpcRequestId();
e.printStackTrace();
}
Polling with Waiters
The SDK offers waiters that allow your code to wait until a specific resource reaches a desired
state. A waiter can be invoked in both a blocking or a non-blocking (with asychronous
callback) manner, and will wait until either the desired state is reached or a timeout is

exceeded. Waiters abstract the polling logic you would otherwise have to write into an easy-
to-use single method call.
Waiters are obtained through the service client (client.getWaiters()). Both a

Get<Resource>Request and the desired lifecycle state are passed in to the
waiters.for<Resource> method. For example:
public static Instance waitForInstanceProvisioningToComplete( ComputeClient computeClient, String
instanceId) throws Exception {
ComputeWaiters waiters = computeClient.getWaiters();

GetInstanceResponse response = waiters.forInstance(
GetInstanceRequest.builder().instanceId(instanceId).build(),
Instance.LifecycleState.Running)
.execute();
return response.getInstance();
}
Each waiters.for<Resource> method has two versions:
l One version uses the default polling values. For example:

waiters.forInstance(GetInstanceRequest, LifecycleState)
l The other version gives you full control over how long to wait and how much time
between polling attempts. For example:
waiters.forInstance(GetInstanceRequest, LifecycleState, TerminationStrategy, DelayStrategy)
Logging
Logging in the SDK is done through SLF4J. SLF4J is a logging abstraction that allows the use of
a user-supplied logging library (e.g., log4j). For more information, see the SLF4J manual.
The following is an example that enables basic logging to standard out. More advanced logging
options can be configured by using the log4j binding.
1. Download the SLF4J Simple binding jar: SLF4J Simple Binding

2. Add the jar to your classpath (e.g., add it to the /third-party/lib directory of the SDK
download)

3. Add the following VM arg to enable debug level logging (by default, info level is used): -
Dorg.slf4j.simpleLogger.defaultLogLevel=debug
Uploading Large Objects
The Object Storage service supports multipart uploads to make large object uploads easier by
splitting the large object into parts. The Java SDK supports raw multipart upload operations
for advanced use cases, as well as a higher level upload class that uses the multipart upload
APIs. Managing Multipart Uploads provides links to the APIs used for multipart upload
operations. Higher level multipart uploads are implemented using the UploadManager, which
will: split a large object into parts for you, upload the parts in parallel, and then recombine
and commit the parts as a single object in storage.
The UploadObject example shows how to use the UploadManager to automatically split an
object into parts for upload to simplify interaction with the Object Storage service.
Examples
Examples of SDK usage can be found on GitHub, including:
l Example: Synchronous Object Storage

l Example: Asynchronous Object Storage
l Example: Create an instance
l Example: Get an instance's public IP address
The examples are also in the downloadable .zip file for the SDK. Examples for older versions
of the SDK are in the downloadable .zip for the specific version, available on GitHub.
If you'd like to see another example not already covered, file a GitHub issue.
Putting It All Together
1. Download the SDK to a directory named oci. See GitHub for the download.
2. Unzip the SDK into the oci directory. For example: tar -xf oci-java-sdk-full.zip

3. Create your configuration file in your home directory (~/.oci/config). See Configuring
the SDK.
4. Use javac to compile one of the previous example classes from the examples directory,
ex:
javac -cp lib/oci-java-sdk-full-<version>.jar:third-party/lib/*
examples/ObjectStorageSyncExample.java
5. You should now have a class file in the examples directory. Run the example:
java -cp examples:lib/oci-java-sdk-full-<version>.jar:third-party/lib/* ObjectStorageSyncExample
THIRD-PARTY DEPENDENCIES AND S HADING
The SDK requires a number of third-party dependencies, which are available in the third-
party/lib directory. To use the SDK library lib/oci-java-sdk-full-<version>.jar, all of
the third-party dependencies in third-party/lib have to be on the class path.
The SDK also includes a second version of the SDK library, shaded/lib/oci-java-sdk-full-
shaded-<version>.jar, which contains most of the third-party dependencies already. Only a
few more third-party libraries in shaded/third-party/lib have to be on the class path when
you use this version of the SDK library.
These two versions of the SDK library are functionally the same, however the second version,
shaded/lib/oci-java-sdk-full-shaded-<version>.jar can simplify dealing with different
versions of third-party dependencies. This is because all the dependencies that are included in
shaded/lib/oci-java-sdk-full-shaded-<version>.jar were shaded, which means they
will not interfere with other versions of themselves you may want to include along with this
SDK.
You can use either lib/oci-java-sdk-full-<version>.jar or shaded/lib/oci-java-sdk-

full-shaded-<version>.jar, but not both. When using lib/oci-java-sdk-full-
<version>.jar, use all the third-party libraries in third-party/lib. When using
shaded/lib/oci-java-sdk-full-shaded-<version>.jar, use all the third-party libraries in
shaded/third-party/lib.
To use the shaded version of the SDK in the Putting It All Together example, replace the javac
commands in steps 4 and 5 with the following:

l Step 4:
javac -cp shaded/lib/oci-java-sdk-full-shaded-<version>.jar:shaded/third-party/lib/*
examples/ObjectStorageSyncExample.java
l Step 5:
java -cp examples:shaded/lib/oci-java-sdk-full-shaded-<version>.jar:shaded/third-party/lib/*
ObjectStorageSyncExample
Troubleshooting
This section contains troubleshooting information for the Java SDK.
OBJECT S TORAGE CLIENT DOES NOT CLOSE CONNECTIONS WHEN CLIENT IS CLOSED.
Too many file descriptors are opened up, and it takes too long to close existing ones. An
exception may look like this:
Caused by: java.io.FileNotFoundException: classes/caspertest.pem (Too many open files)
at java.io.FileInputStream.open0(Native Method)
at java.io.FileInputStream.open(FileInputStream.java:195)
at java.io.FileInputStream.<init>(FileInputStream.java:138)
Use one of the following workarounds to fix this issue.
l Make this call before creating a client: System.setProperty("http.keepAlive",

"false");
l Use this command line argument when running Java: -Dhttp.keepAlive=false
ENCRYPTION KEY SIZE ERRORS
By default, the Java SDK can only handle keys of 128 bit or lower key length. Users get
"Invalid Key Exception" and "Illegal key size" errors when they use longer keys, such as
AES256.
Use one of the following workarounds to fix this issue.
l Use a 128 bit key, such as AES128.

l Install the appropriate Java Cryptography Extension (JCE) Unlimited Strength

Jurisdiction from one of the following locations:

o For Java 7: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-
download-432124.html
o For Java 8: http://www.oracle.com/technetwork/java/javase/downloads/jce8-
TROUBLESHOOTING S ERVICE ERRORS
Any operation resulting in a service error will cause an exception of type

com.oracle.bmc.model.BmcException to be thrown by the SDK. For information about
common service errors returned by OCI, see API Errors.
Contributions
Got a fix for a bug, or a new feature you'd like to contribute? The SDK is open source and
Notifications
To be notified when a new version of the Java SDK is released, subscribe to the Atom feed.
Questions or Feedback
l GitHub: To file bugs and feature requests only

l Stack Overflow: Please use the oracle-cloud-infrastructure and oci-java-sdk tags in
your post
l My Oracle Support
Python SDK
General information about the Python SDK:

o Audit
o Database
o IAM
o Load Balancing
o Object Storage
o DNS
o File Storage
o Email Delivery
l Download: Download the SDK from GitHub or get the package from the Python
Package Index (PyPi).
l Documentation: Python SDK documentation.
Ruby SDK
Version 2.1.0
General information about the Ruby SDK:
l What's new in this version:

o Added support for remote VCN peering across regions. See the examples/ folder
in the Ruby SDK download for a sample.
o Added support for calling Oracle Cloud Infrastructure services in the London
(LHR) region.
o Improved exception handling to correctly throw ServiceErrors where

applicable. This addresses an issue that caused head_object and head_bucket to

throw a NetworkError when a ServiceError should have been thrown in the
Object Storage service.
o Added support for username and password protected proxies.
o Audit
o Database
o IAM
o Load Balancing
o Object Storage
o DNS
o File Storage
o Email Delivery
l Download: Download the SDK or install it from RubyGems.
l Documentation: Ruby SDK documentation.
Go SDK
General information about the Go SDK.
o Audit

o Database
o IAM
o Load Balancing
o Object Storage
o DNS
o File Storage
o Email Delivery
l Download: Download the SDK from GitHub.
l Documentation: Go SDK documentation.
HDFS Connector for Object Storage

The HDFS connector lets your Apache Hadoop application read and write data to and from the
Oracle Cloud Infrastructure Object Storage service.
l Services supported: Object Storage

l Download: Download the HDFS Connector
l API reference documentation: HDFS Connector API Reference
HDFS Connector Requirements
To use the HDFS connector, you must have:

l An Oracle Cloud Infrastructure account.

permissions for any bucket you want to use. This can be a user for yourself, or another
person/system that needs to call the API. For an example of how to set up a new user,
group, compartment, and policy, see Adding Users. For a basic Object Storage policy,
see Let Object Storage admins manage buckets and objects.
l Java 8 (for Java 7, see Java 7 Compatibility).
l A TTL value of 60. For more information, see Configuring JVM TTL for DNS Name
Lookups.
CREDENTIALS AND PASSWORDS
If you use an encrypted PEM file for credentials, the passphrase will be read from
configuration using the getPassword Hadoop Configuration method. The getPassword option
checks for a password in a registered security provider. If the security provider doesn't
contain the requested key, it will fallback to reading the plaintext passphrase directly from the
configuration file.
JAVA 7 COMPATIBILITY
To use Java 7, you must have a version that supports TLS 1.2.
For more information, see:
l https://blogs.oracle.com/java-platform-group/entry/java_8_will_use_tls
l http://bugs.java.com/view_bug.do?bug_id=6916074
l https://blogs.oracle.com/java-platform-group/entry/diagnosing_tls_ssl_and_https
CONFIGURING JVM TTL FOR DNS NAME LOOKUPS
The Java Virtual Machine (JVM) caches DNS responses from lookups for a set amount of time,
called time-to-live (TTL). This ensures faster response time in code that requires frequent
name resolution.
The JVM uses the networkaddress.cache.ttl property to specify the caching policy for DNS
name lookups. The value is an integer that represents the number of seconds to cache the

successful lookup. The default value for many JVMs, -1, indicates that the lookup should be
cached forever.
Because resources in Oracle Cloud Infrastructure use DNS names that can change, we
recommend that you change the the TTL value to 60 seconds. This ensures that the new IP
address for the resource is returned on next DNS query. You can change this value globally or
specifically for your application:
l To set TTL globally for all applications using the JVM, add the following in the $JAVA_
HOME/jre/lib/security/java.security file:
networkaddress.cache.ttl=60
l To set TTL only for your application, set the following in your application's initialization
code:
java.security.Security.setProperty("networkaddress.cache.ttl" , "60");
HDFS Connector Properties
You can set the following HDFS Connector properties in the core-site.xml file. The
BmcProperties page lists additional properties that you can configure for a connection to OCI
Object Storage.
HOSTNAME ( FS.OCI.CLIENT .HOSTNAME )
Host endpoint for . For example, https://www.foo.com.
l Type: String
l Required: Yes
TENANT I D ( FS.OCI.CLIENT.AUTH.TENANTID)
OCID of your tenancy. To get the value, see Required Keys and OCIDs.
l Type: String
l Required: Yes, unless you provide a custom authenticator
USER I D ( FS.OCI.CLIENT.AUTH.USERID)
OCID of the user calling the API. To get the value, see Required Keys and OCIDs.

l Type: String
FINGERPRINT ( FS.OCI.CLIENT.AUTH.FINGERPRINT)
Fingerprint for the key pair being used. To get the value, see Required Keys and OCIDs.
l Type: Sting
l Required: Yes, unless you provide a custom authenticator.
PEMFILEPATH ( FS.OCI.CLIENT.AUTH.PEMFILEPATH)
Full path and file name of the private key used for authentication. The file should be on the
local file system.
l Type: String
PASSPHRASE ( FS.OCI.CLIENT.AUTH.PASSPHRASE)
Passphrase used for the key, if it is encrypted.
l Type: String
l Required: Only if your key is encrypted
You can specify that a property value applies to a specific bucket by appending .<bucket_
name>.<namespace_name> to the property name.
This example shows how properties can be configured in a core-site.xml file (the OCIDs are
shortened for brevity):
<configuration>
...
<property>
<name>fs.oci.client.hostname</name>
<value>https://objectstorage.us-ashburn-1.oraclecloud.com</value>
</property>
<property>

<name>fs.oci.client.hostname.myBucket.myNamespace</name>
<value>https://objectstorage.phoenix-1.oraclecloud.com</value>
</property>
<property>
<name>fs.oci.client.auth.tenantId</name>
<value>ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4j...stifsfdsq</value>
</property>
<property>
<name>fs.oci.client.auth.userId</name>
<value>ocid1.user.oc1..aaaaaaaat5nvwcnazjc...aqw3rynjq</value>
</property>
<property>
<name>fs.oci.client.auth.fingerprint</name>
<value>20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34</value>
</property>
<property>
<name>fs.oci.client.auth.pemfilepath</name>
<value>~/.oci/oci_api_key.pem</value>
</property>
...
</configuration>
Using Instance Principals for Authentication
Oracle provides instance principals so that you no longer need to configure user credentials or
provide PEM files on services running on instances. Each of these instances has its own
identity and authenticates by using certificates added to the instance by instance principals.
To use instance principals authentication with the HDFS connector, simply provide the
property fs.oci.client.custom.authenticator and set the value to
com.oracle.bmc.hdfs.auth.InstancePrincipalsCustomAuthenticator.
Because using instance principals provides your instance with a custom authenticator, it is no
long necessary to configure the following properties:
l fs.oci.client.auth.tenantId
l fs.oci.client.auth.userId
l fs.oci.client.auth.fingerprint

l fs.oci.client.auth.pemfilepath
l fs.oci.client.auth.passphrase
The following example code illustrates using instance principals for authentication with the
HDFS connector:
<?xml version="1.0"?>
<configuration>
<property>
<name>fs.oci.client.hostname</name>
<value>https://objectstorage.us-phoenix-1.oraclecloud.com</value>
</property>
<property>
<name>fs.oci.client.custom.authenticator</name>
<value>com.oracle.bmc.hdfs.auth.InstancePrincipalsCustomAuthenticator</value>
</property>
</configuration>
For more information about instance principals, see Announcing Instance Principals for
Identity and Access Management.
Large Object Uploads
Large objects are uploaded to Object Storage using multipart uploads. The file is split into
smaller parts that are uploaded in parallel, which reduces upload times. This also enables the
HDFS connector to retry uploads of failed parts instead of failing the entire upload. However,
uploads may transiently fail, and the connector will attempt to abort partially uploaded files.
Because these files accumulate (and you will be charged for storage), list the uploads
periodically and then after a certain number of days abort them manually using the Java SDK.
Information about using the Object Storage API for managing multipart uploads can be found
in API Documentation.
Note: If you prefer not to use multipart uploads at all, you can disable them using the
Hadoop configuration ‘fs.oci.client.multipart.allowed’, and setting it to ‘false’.
Best Practices
The following sections contain best practices to optimize usage and performance.

DIRECTORY NAMES
There are no actual directories in Object Storage. Directory grouping is a function of naming
convention, where objects use / delimiters in their names. For example, an object named
a/example.json implies there is a directory named a. However, if that object is deleted, the
a directory is also deleted implicitly. To preserve filesystem semantics where the directory
can exist without the presence of any files, the HDFS connector creates an actual object
whose name ends in / with a path that represents the directory, (e.g., create an object named
a/). Now, deleting a/example.json doesn't affect the existence of the a directory, because
the a/ object maintains its presence. However, it's entirely possible that somebody could
delete that a/ object without deleting the files/directories beneath it. The HDFS connector will
only delete the folder object if there are no objects beneath that path. The folder object itself
is zero bytes.
JAVA SDK AND MAVEN ARTIFACTS
Building an HDFS connector relies on Maven artifacts that are provided by the Java SDK. To
obtain the artifacts, you must download the Java SDK and build it locally. You can then build
the HDFS connector.
Important
The Java SDK file version that you download from the
Oracle Releases page must match the HDFS connector
version, which you can find in the hdfs-
connector/pom.xml file in the dependency tag block
that has the groupId attribute.
I NCONSISTENT FILESYSTEM
Deleting a directory means deleting all objects that start with the prefix representing that
directory. HDFS allows you to query for the file status of a file or a directory. The file status of
a directory is implemented by verifying that the folder object for that directory exists.
However, it's possible that the folder object has been deleted, but some of the objects with
that prefix still exist. For example, in a situation with these objects:

l a/b/example.json
l a/b/file.json
l a/b/
HDFS would know that directory /a/b/ exists and is a directory, and scanning it would result
in example.json and file.json. However, if object a/b/ was deleted, the filesystem would
appear to be in an inconsistent state. You could query it for all files in directory /a/b/ and find
the two entries, but querying for the status of the actual /a/b/ directory would result in an
exception because the directory doesn't exist. The HDFS connector does not attempt to fix up
the state of the filesystem.
FILE CREATION
Object Storage supports objects that can be many gigabytes in size. Creating files will
normally be done by writing to a temp file and then uploading the contents of the file when the
stream is closed. The temp space must be large enough to handle multiple uploads. The temp
directory used is controlled by the hadoop.tmp.dir configuration property.
READ/S EEK S UPPORT
When in-memory buffers are enabled (fs.oci.io.read.inmemory), seek is fully supported

because the entire file is buffered into a byte array. When in-memory buffer is not enabled
(likely because object sizes are large), seek is implemented by closing the stream and
making a new range request starting at the specified offset.
DIRECTORY LISTING
Listing a directory is essentially a List bucket operation with a prefix and delimiter specified.
To create an HDFS FileStatus instance for each key, the connector performs an additional
HEAD request to get ObjectMetadata for each individual key. This will be required until Object
Storage supports richer list operation data.
URI Format for Filesystems and Files
HDFS filesystems and files are referenced through URIs. The scheme specifies the type of
filesystem, and the remaining part of the URI is largely free for the filesystem

implementation to interpret as it wants.
Because Object Storage is an object store, its ability to name objects as if they were files in a
filesystem is used to mimic an actual filesystem.
ROOT
The root of Object Storage filesystem is denoted by a path where the authority component
includes the bucket and the namespace:
oci://bucket@namespace/
This is always the root of the filesystem. The reason for using authority for both bucket and
namespace is that HDFS only allows the authority portion to determine where the filesystem
is; the path portion denotes just the path to the resource (so "oci//namespace/bucket" won't
work, for example). Note that the @ character is not a valid character for buckets or
namespaces, and should allow the authority to be parsed correctly.
S UB-DIRECTORIES
Sub-directories do not actually exist, but can be mimicked by creating objects with /
characters. For example, two files named a/b/c/example.json and a/b/d/path.json would
appear as if they were in a common directory a/b. This would be achieved by using the Object
Storage prefix- and delimiter-based querying. In the given example, referencing a sub-
directory as a URI would be:
oci://bucket@namespace/a/b/
OBJECTS/FILES
An object named a/b/c/example.json is referenced as:
oci://bucket@namespace/a/b/c/example.json

Logging
Logging in the connector is done through SLF4J. SLF4J is a logging abstraction that allows the
use of a user-supplied logging library (e.g., log4j). For more information, see, the SLF4J
manual.
The following example shows how to enable basic logging to standard output.
1. Download the SLF4J Simple binding jar: SLF4J Simple Binding

2. Add the jar to your classpath
3. Add the following VM arg to enable debug level logging (by default, info level is used): -
Dorg.slf4j.simpleLogger.defaultLogLevel=debug
You can configure more advanced logging options by using the log4j binding.
Sample Hadoop Job
View the Hadoop sample in full screen for easier reading:

package com.oracle.oci.hadoop.example;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import org.apache.commons.io.IOUtils;
import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.fs.FSDataInputStream;
import org.apache.hadoop.fs.FSDataOutputStream;
import org.apache.hadoop.fs.Path;
import org.apache.hadoop.io.IntWritable;
import org.apache.hadoop.io.Text;
import org.apache.hadoop.mapreduce.Job;
import org.apache.hadoop.mapreduce.lib.input.FileInputFormat;
import org.apache.hadoop.mapreduce.lib.output.FileOutputFormat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.oracle.oci.hdfs.BmcFilesystem;

import lombok.RequiredArgsConstructor;
@RequiredArgsConstructor
public class SampleOracleBmcHadoopJob
{
private static final String SAMPLE_JOB_PATH = "/samplehadoopjob";
private static final String INPUT_FILE = SAMPLE_JOB_PATH + "/input.dat";
private static final String OUTPUT_DIR = SAMPLE_JOB_PATH + "/output";
// non-static since this is the runner class it needs to initialize after we set the properties
private final Logger log = LoggerFactory.getLogger(SampleOracleBmcHadoopJob.class);
/**
* Runner for sample hadoop job. This expects 3 args: path to configuration file, Object Store
namespace, Object
* Store bucket. To run this, you must:
*{@code
*
Create a standard hadoop configuration file
*
Create the bucket ahead of time.
*}
* This runner will create a test input file in a file '/samplehadoopjob/input.dat', and job results
will be written
* to '/samplehadoopjob/output'.
*
* @param args
* 1) path to configuration file, 2) namespace, 3) bucket
* @throws Exception
*/
public static void main(final String[] args) throws Exception
{
if (args.length != 3)
{
throw new IllegalArgumentException(
"Must have 3 args: 1) path to config file, 2) object storage namespace, 3) object

storage bucket");
}
// redirect all logs to sysout

System.setProperty("org.slf4j.simpleLogger.logFile", "System.out");
System.setProperty("org.slf4j.simpleLogger.defaultLogLevel", "debug");
final SampleOracleBmcHadoopJob job = new SampleOracleBmcHadoopJob(args[0], args[1], args[2]);

System.exit(job.execute());
}
private final String configurationFilePath;

private final String namespace;
private final String bucket;
public int execute() throws IOException, ClassNotFoundException, InterruptedException,

URISyntaxException
{
log.info("Creating hadoop configuration");
final Configuration configuration = this.createConfiguration(this.configurationFilePath);
final String authority = this.bucket + "@" + this.namespace;

final String uri = "oci://" + authority;
log.info("Using uri: {}", uri);
log.info("Creating job inputs");

this.setup(uri, configuration);
log.info("Creating job");
final Job job = this.createJob(configuration);
final String in = uri + INPUT_FILE;

final String out = uri + OUTPUT_DIR;
log.info("Using input: {}", in);
log.info("Using output: {}", out);
FileInputFormat.addInputPath(job, new Path(in));

FileOutputFormat.setOutputPath(job, new Path(out));
log.info("Executing job...");
final int response = job.waitForCompletion(true) ? 0 : 1;

log.info("Attempting to read job results");

this.tryReadResult(uri, configuration);
return response;
}
private Configuration createConfiguration(final String configFilePath)

{
final Configuration configuration = new Configuration();
configuration.addResource(new Path(configFilePath));
return configuration;
}
private void setup(final String uri, final Configuration configuration) throws IOException,
URISyntaxException
{
try (final BmcFilesystem fs = new BmcFilesystem())
{
fs.initialize(new URI(uri), configuration);
fs.delete(new Path(SAMPLE_JOB_PATH), true);
final FSDataOutputStream output = fs.create(new Path(INPUT_FILE));
output.writeChars("example\npath\ngak\ntest\nexample\ngak\n\ngak");
output.close();
}
}
private Job createJob(final Configuration configuration) throws IOException

{
final Job job = Job.getInstance(configuration, "word count");
job.setJarByClass(SampleOracleBmcHadoopJob.class);
job.setMapperClass(SimpleMapper.class);
job.setCombinerClass(SimpleReducer.class);
job.setReducerClass(SimpleReducer.class);
job.setOutputKeyClass(Text.class);
job.setOutputValueClass(IntWritable.class);
return job;
}
private void tryReadResult(final String uri, final Configuration configuration)

throws IOException, URISyntaxException
{
try (final BmcFilesystem fs = new BmcFilesystem())
{

fs.initialize(new URI(uri), configuration);

// this should be the output file name, but that could change
final FSDataInputStream input = fs.open(new Path(OUTPUT_DIR + "/part-r-00000"));
final ByteArrayOutputStream baos = new ByteArrayOutputStream();

IOUtils.copy(input, baos);
log.info("\n=====\n" + baos.toString() + "=====");
input.close();
}
}
}
import java.util.StringTokenizer;
import org.apache.hadoop.mapreduce.Mapper;
public class SimpleMapper extends Mapper

{
private final static IntWritable one = new IntWritable(1);
private final Text word = new Text();
@Override
public void map(final Object key, final Text value, final Context context) throws IOException,
InterruptedException
{
final StringTokenizer itr = new StringTokenizer(value.toString());
while (itr.hasMoreTokens())
{
this.word.set(itr.nextToken());
context.write(this.word, one);
}
}
}

import org.apache.hadoop.mapreduce.Reducer;
public class SimpleReducer extends Reducer

{
private final IntWritable result = new IntWritable();
@Override
public void reduce(final Text key, final Iterable values, final Context context)
throws IOException, InterruptedException
{
int sum = 0;
for (final IntWritable val : values)
{
sum += val.get();
}
this.result.set(sum);
context.write(key, this.result);
}
}
Troubleshooting
This section contains troubleshooting information for the HDFS Connector.
TROUBLESHOOTING S ERVICE ERRORS
Any operation resulting in a service error will cause an exception of type

com.oracle.bmc.model.BmcException to be thrown by the HDFS Connector. For information
about common service errors returned by OCI, see API Errors.
JAVA ENCRYPTION KEY S IZE ERRORS
The HDFS Connector can only handle keys of 128 bit or lower key length. Users get "Invalid
Key Exception" and "Illegal key size" errors when they use longer keys, such as AES256. Use
one of the following workarounds to fix this issue:

l Use a 128 bit key, such as AES128.

l Install the appropriate Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction from one of the following locations:
o For Java 7: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-
o For Java 8: http://www.oracle.com/technetwork/java/javase/downloads/jce8-
Contributions
Got a fix for a bug, or a new feature you'd like to contribute? The SDK is open source and
Notifications
If you wish to be notified when a new version of the HDFS connector is released, subscribe to
the Atom feed.
l To file bugs and make feature requests: GitHub

l Stack Overflow: Please use the oracle-cloud-infrastructure and oci-hdfs-connector tags
in your post
l My Oracle Support

Using the HDFS Connector with Spark
Introduction
This article provides a walkthrough that illustrates using the HDFS connector with the Spark
application framework. For the walkthrough, we use the Oracle Linux 7.4 operating system,
and we run Spark as a standalone on a single computer.
PREREQUISITES
Following are prerequisites for completing the walkthrough:
l You must have permission to launch a Compute instance. For guidance, see Launching
an Instance.
l You must be able to connect to the service instance that you've launched. For guidance,
see Connecting to an Instance.
l You must have the appropriate OCID, fingerprint, and private key for the Identity and
Access Management (IAM) user that you will use to interact with an Object Storage. For
guidance, see SDK and Tool Configuration; see also Resource Identifiers.
l You must have an Object Storage bucket that you can connect to.
l The IAM user must be able to read and write to that bucket using the Console.
Using Spark
I NSTALL S PARK AND DEPENDENCIES
Note
For the purpose of this example, install Spark into the

current user's home directory. Note that for production
scenarios, you would not do this.

1. Launch an instance of your Compute service. For guidance, see Launching an Instance.
2. Ensure that your service instance has a public IP address so that you can connect using
a Secure Shell (SSH) connection. For guidance, see Instance Console Connections.
3. Connect to your service instance using an SSH connection.
4. Install Spark and its dependencies, Java and Scala, by using the code examples that
follow.
# We'll use wget to download some of the artifacts that need to be installed
sudo yum install wget
# First install Java

sudo yum install java-1.8.0-openjdk.x86_64
export JAVA_HOME=/usr/lib/jvm/jre-1.8.0-openjdk
# Should be something like: OpenJDK Runtime Environment (build 1.8.0_161-b14)
java -version
# Then install Scala

wget https://downloads.lightbend.com/scala/2.12.4/scala-2.12.4.rpm
sudo yum install scala-2.12.4.rpm
# Should be something like: Scala code runner version 2.12.4 -- Copyright 2002-2017, LAMP/EPFL and
Lightbend, Inc.
scala -version
# Then download Spark

wget https://archive.apache.org/dist/spark/spark-2.2.1/spark-2.2.1-bin-hadoop2.7.tgz
tar xvf spark-2.2.1-bin-hadoop2.7.tgz
export SPARK_HOME=$HOME/spark-2.2.1-bin-hadoop2.7
export PATH=$PATH:$SPARK_HOME/bin
# Start a Spark master

cd $SPARK_HOME
./sbin/start-master.sh

DOWNLOAD THE HDFS CONNECTOR AND CREATE CONFIGURATION FILES
Note
For the purposes of this example, place the JAR and key
files in the current user's home directory. For
production scenarios you would instead put these files in
a common place that enforces the appropriate
permissions (that is, readable by the user under which
Spark and Hive are running).
Download the HDFS connector to the service instance and add the relevant configuration files
by using the following code example. For additional information, see HDFS Connector for
Object Storage.
wget https://docs.us-phoenix-1.oraclecloud.com/tools/hdfs/latest/download/oci-hdfs.zip
unzip oci-hdfs.zip -d oci-hdfs
cd $HOME
mkdir .oci
# Create or copy your API key into the $HOME/.oci directory
cd $SPARK_HOME/conf
# Create a core-site.xml (e.g. by transferring one you have, using vi etc.). Consult
# https://docs.us-phoenix-1.oraclecloud.com/Content/API/SDKDocs/hdfsconnector.htm#two
# for what this should look like
# Create a spark-defaults.conf file from the template

cp spark-defaults.conf.template spark-defaults.conf
In the spark-defaults.conf file, add the following at the bottom:
spark.sql.hive.metastore.sharedPrefixes= shaded.oracle,com.oracle.bmc
PREPARE DATA
For testing data, we will use the MovieLens data set.

1. Download the latest data set at https://grouplens.org/datasets/movielens/latest/. Be

sure to download the "Small" data set.
2. Unzip the download file.
3. Upload the movies.csv file to your Object Storage bucket.
TEST USING THE S PARK S HELL
With the data ready, we can now launch the Spark shell and test it using a sample command:
cd $SPARK_HOME
./bin/spark-shell
scala> sc.wholeTextFiles("oci://PipedUploadTest@internalbriangustafson/")
java.io.IOException: No FileSystem for scheme: oci
You receive an error at this point because the oci:// file system schema is not available. We
need to reference the JAR file before starting the Spark shell. Here's an example for doing so:
./bin/spark-shell --jars $HOME/oci-hdfs/lib/oci-hdfs-full-1.2.7.jar
scala> sc.wholeTextFiles("oci://PipedUploadTest@internalbriangustafson/")
res0: org.apache.spark.rdd.RDD[(String, String)] = oci://PipedUploadTest@internalbriangustafson/
MapPartitionsRDD[1] at wholeTextFiles at <console>:25
scala> sc.textFile("oci://PipedUploadTest@internalbriangustafson/movies.csv").take(20).foreach
(println)
movieId,title,genres
1,Toy Story (1995),Adventure|Animation|Children|Comedy|Fantasy
2,Jumanji (1995),Adventure|Children|Fantasy
3,Grumpier Old Men (1995),Comedy|Romance
4,Waiting to Exhale (1995),Comedy|Drama|Romance
5,Father of the Bride Part II (1995),Comedy
6,Heat (1995),Action|Crime|Thriller
7,Sabrina (1995),Comedy|Romance
8,Tom and Huck (1995),Adventure|Children
9,Sudden Death (1995),Action
10,GoldenEye (1995),Action|Adventure|Thriller
11,"American President, The (1995)",Comedy|Drama|Romance
12,Dracula: Dead and Loving It (1995),Comedy|Horror
13,Balto (1995),Adventure|Animation|Children
14,Nixon (1995),Drama
15,Cutthroat Island (1995),Action|Adventure|Romance

16,Casino (1995),Crime|Drama
17,Sense and Sensibility (1995),Drama|Romance
18,Four Rooms (1995),Comedy
19,Ace Ventura: When Nature Calls (1995),Comedy
The command is successful so we are able to connect to Object Storage. Note that if you do
not wish to pass the --jars argument each time the command executes, you can instead copy
the oci-hdfs-full JAR file into the $SPARK_HOME/jars directory.
S TART THE S PARK THRIFT S ERVER
Start the Spark Thrift Server on port 10015 and use the Beeline command line tool to establish
a JDBC connection and then run a basic query, as shown here:
cd $SPARK_HOME
./sbin/start-thriftserver.sh --hiveconf hive.server2.thrift.port=10015
Once the Spark server is running, we can launch Beeline, as shown here:
cd $SPARK_HOME
./bin/beeline
Beeline version 1.2.1.spark2 by Apache Hive
beeline>
Next, connect to the server, as shown here:
Note
For the purposes of this example, we have not

configured any security, so any user name and
password will be accepted. For production scenarios you
would not do this.
beeline> !connect jdbc:hive2://localhost:10015 testuser testpass

Connecting to jdbc:hive2://localhost:10015
log4j:WARN No appenders could be found for logger (org.apache.hive.jdbc.Utils).
log4j:WARN Please initialize the log4j system properly.
log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
Connected to: Spark SQL (version 2.2.1)
Driver: Hive JDBC (version 1.2.1.spark2)

Transaction isolation: TRANSACTION_REPEATABLE_READ

0: jdbc:hive2://localhost:10015>
If we now check to see what tables exist, we see the following:

0: jdbc:hive2://localhost:10015> show tables;
+-----------+------------+--------------+--+
| database | tableName | isTemporary |
+-----------+------------+--------------+--+
+-----------+------------+--------------+--+
No rows selected (0.724 seconds)
None exist presently; however, we can create a talbe and link it to the movies.csv file that
we downloaded and placed in the Object Storage bucket, as shown here:
0: jdbc:hive2://localhost:10015> create table test_table (movieId integer, title string, genres
string) using csv options (path "oci://myBucket@myTenant/movies.csv", header "true", delimiter ",");
0: jdbc:hive2://localhost:10015> describe formatted test_table;

+-------------------------------+------------------------------------------------------------+------
----+--+
| col_name | data_type |
comment |
+-------------------------------+------------------------------------------------------------+------
----+--+
| movieId | int | NULL
|
| title | string | NULL
|
| genres | string | NULL
|
| | |
|
| # Detailed Table Information | |
|
| Database | default |
|
| Table | test_table |
|
| Owner | opc |
|
| Created | Thu Mar 01 20:45:18 GMT 2018 |
|

| Last Access | Thu Jan 01 00:00:00 GMT 1970 |

|
| Type | EXTERNAL |
|
| Provider | csv |
|
| Table Properties | [transient_lastDdlTime=1519937118] |
|
| Location | oci://PipedUploadTest@internalbriangustafson/movies.csv |
|
| Serde Library | org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe |
|
| InputFormat | org.apache.hadoop.mapred.SequenceFileInputFormat |
|
| OutputFormat | org.apache.hadoop.hive.ql.io.HiveSequenceFileOutputFormat |
|
| Storage Properties | [delimiter=,, header=true, serialization.format=1] |
|
+-------------------------------+------------------------------------------------------------+------
----+--+
Note that the table stores its data externally in Object Storage and the data can be accessed
using the HDFS connector (the oci:// file system scheme). Now that we have a table, we can
query it:
0: jdbc:hive2://localhost:10015> select * from test_table limit 10;
+----------+-------------------------------------+----------------------------------------------+--+
| movieId | title | genres |
+----------+-------------------------------------+----------------------------------------------+--+
| 1 | Toy Story (1995) | Adventure|Animation|Children|Comedy|Fantasy |
| 2 | Jumanji (1995) | Adventure|Children|Fantasy |
| 3 | Grumpier Old Men (1995) | Comedy|Romance |
| 4 | Waiting to Exhale (1995) | Comedy|Drama|Romance |
| 5 | Father of the Bride Part II (1995) | Comedy |
| 6 | Heat (1995) | Action|Crime|Thriller |
| 7 | Sabrina (1995) | Comedy|Romance |
| 8 | Tom and Huck (1995) | Adventure|Children |
| 9 | Sudden Death (1995) | Action |
| 10 | GoldenEye (1995) | Action|Adventure|Thriller |
+----------+-------------------------------------+----------------------------------------------+--+

For more information
l HDFS Connector for Object Storage

l Overview of Object Storage
l Apache Spark
Chef Knife Plugin

This topic provides information about installing, configuring, and using the Chef Knife Plugin
for Oracle Cloud Infrastructure.
l Licensing: This provider and sample is licensed under the Mozilla Public License 2.0;
third-party content is separately licensed as described in the code.
l Download: GitHub
l Documentation: README
Contributions
Got a fix for a bug, or a new feature you'd like to contribute? The Chef Knife Plugin for Oracle
Cloud Infrastructure is open source and accepting pull requests on GitHub.
Notifications
To be notified when a new version of the Chef Knife Plugin for Oracle Cloud Infrastructure is
released, subscribe to the Atom feed.

l Stack Overflow: Please use the oracle-cloud-infrastructure tag in your post.
l My Oracle Support

Oracle Cloud Infrastructure Compute Jenkins Plugin

This topic provides information about installing, configuring, and using the Oracle Cloud
Infrastructure Compute Jenkins plugin.
l Licensing: The Oracle Cloud Infrastructure Compute Jenkins plugin is dual-licensed

under the Universal Permissive License (UPL) and the Apache License 2.0; third-party
content is separately licensed as described in the code.
l Download: GitHub
l Documentation: Oracle Cloud Infrastructure Compute Plugin - Jenkins Wiki
Contributions
Got a fix for a bug, or a new feature you'd like to contribute? The Oracle Cloud Infrastructure
Compute Jenkins plugin is open source and accepting pull requests on GitHub.
Notifications
To be notified when a new version of the Oracle Cloud Infrastructure Compute Jenkins plugin
is released, subscribe to the Atom feed.

l Stack Overflow: Please use the oracle-cloud-infrastructure tag in your post.
l My Oracle Support
Terraform Provider
This topic provides information about installing, configuring, and using the Terraform provider
with the Terraform orchestration tool.

o Database
o File Storage
o IAM
o Load Balancing
o Object Storage
o DNS Service
l Licensing: This provider and sample is licensed under the Mozilla Public License 2.0;
third-party content is separately licensed as described in the code.
l Download: GitHub
l Documentation: README
Requirements
To use the Terraform provider, you must have:
l An Oracle Cloud Infrastructure account

permissions for working with resources in those compartments.
l The necessary credentials and OCID information.
l The Terraform binary for your operating system.
l The Oracle Cloud Infrastructure Terraform provider.
Contributions
Got a fix for a bug, or a new feature you'd like to contribute? The Terraform provider is open
source and accepting pull requests on GitHub.

Notifications
To be notified when a new version of the Terraform provider is released, subscribe to the
Atom feed.
l GitHub: To file bugs and feature requests only

l Stack Overflow: Please use the oci-terraform and oracle-cloud-infrastructure tags in
your post
SDK and Tool Configuration

Basic configuration information (for example, user credentials and tenancy OCID) is required
in order for the Command Line Interface (CLI) and the SDKs to work. You can provide this
information by:
l using a configuration file (required for the CLI, optional for SDKs)
l declaring a configuration at runtime (supported for all SDK configuration fields, limited
to the region field for the CLI)
l using a configuration file and declaring a configuration at runtime
SDK Configuration Information

A configuration file is optional for the SDKs listed in SDKs and Other Tools You can provide all
the required information programmatically using a config object in the SDK code.

Important
If you provide information in a configuration file and a

config object, the object is used and the configuration
file is ignored.
Refer to the documentation for each SDK for information about the config object and any
exceptions when using a configuration file. For example, the Java SDK supports but does not
require region value in a configuration file.
CLI Configuration Information

You must use a configuration file for the CLI. The only configuration value that can be passed
as a parameter for a CLI operation is --region. This section provides information about
creating a configuration file.
Configuration File Name and Location
The default configuration file name and location is ~/.oci/config.
Windows Users
Because Windows File Explorer doesn't support folder names that start with a period you have
to use PowerShell to create the folder. Open the PowerShell console and type: mkdir ~/.oci.
Configuration File Entries
The following table lists the basic entries that are required for the config file, as well as where
to get the information for each entry.

Note
If you use a configuration with an SDK, check the SDK

documentation to see if there are any SDK-specific
configuration entries required.
user OCID of the user calling the API. To get the value, see Yes
Example:
ocid1.user.oc1..aaaaaaaa65vwl75tewwm32rgqvm6i34unq
(shortened for brevity)
fingerprint Fingerprint for the key pair being used. To get the value, see Yes
Example:
20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file Full path and filename of the private key. Yes
Important: The key pair must be in PEM format. For

instructions on generating a key pair in PEM format, see
If you encrypted the key with a passphrase, you must also

include the pass_phrase entry in the config file.
Example: ~/.oci/oci_api_key.pem
pass_phrase Passphrase used for the key, if it is encrypted. If key is

encrypted
Example: examplephrase

tenancy OCID of your tenancy. To get the value, see Required Keys and Yes
OCIDs.
Example:
ocid1.tenancy.oc1..aaaaaaaaba3pv6wuzr4h25vqstifsfdsq
(shortened for brevity)
region An Oracle Cloud Infrastructure region. See Regions and Yes

Availability Domains.
Example: us-ashburn-1
The following example shows key values in a config file. This example has a DEFAULT profile
and an additional profile, ADMIN_USER. Any value that isn't explicitly defined for the ADMIN_
USER profile (or any other profiles you add to the config file) is inherited from the DEFAULT
profile.
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq
fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq
region=us-ashburn-1
[ADMIN_USER]
# Subsequent profiles inherit unspecified values from DEFAULT.
user=ocid1.user.oc1..aaaaaaaa65vwl7zut55hiavppn4nbfwyccuecuch5tewwm32rgqvm6i34unq
fingerprint=72:00:22:7f:d3:8b:47:a4:58:05:b8:95:84:31:dd:0e
key_file=keys/admin_key.pem
pass_phrase=mysecretphrase
Required Keys and OCIDs

Whether you're using an Oracle client (see SDKs and Other Tools) or a client you built
yourself, you need to do the following:

1. Create a user in IAM for the person or system who will be calling the API, and put that
user in at least one IAM group with any desired permissions. See "Adding Users" in the
Oracle Cloud Infrastructure Getting Started Guide. You can skip this if the user exists
already.
2. Get these items:
l RSA key pair in PEM format (minimum 2048 bits). See How to Generate an API
Signing Key.
l Fingerprint of the public key. See How to Get the Key's Fingerprint.
l Tenancy's OCID and user's OCID. See Where to Get the Tenancy's OCID and
User's OCID.
3. Upload the public key from the key pair in the Console. See How to Upload the Public
Key.
4. If you're using one of the Oracle SDKs or tools, supply the required credentials listed
above in either a configuration file or a config object in the code. See SDK and Tool
Configuration. If you're instead building your own client, see Request Signatures.
Important
This key pair is not the SSH key that you use to access
compute instances. See Security Credentials.
Both the private key and public key must be in PEM

format (not SSH-RSA format). The public key in PEM
format looks something like this:
MIIBIjANBgkqhkiG9w0BAQE...
...
-----END PUBLIC KEY-----

How to Generate an API Signing Key

You can use the following OpenSSL commands to generate the key pair in the required PEM
format. If you're using Windows, you'll need to install Git Bash for Windows and run the
commands with that tool.
1. If you haven't already, create a .oci directory to store the credentials:

mkdir ~/.oci
2. Generate the private key with one of the following commands.

l Recommended: To generate the key, encrypted with a passphrase you provide
when prompted:
openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048
Note: For Windows, you may need to insert -passout stdin to be prompted for
a passphrase. The prompt will just be the blinking cursor, with no text.
openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 -passout stdin 2048
l To generate the key with no passphrase:

openssl genrsa -out ~/.oci/oci_api_key.pem 2048
3. Ensure that only you can read the private key file:
chmod go-rwx ~/.oci/oci_api_key.pem
4. Generate the public key:

openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
Note: For Windows, if you generated the private key with a passphrase, you may need
to insert -passin stdin to be prompted for the passphrase. The prompt will just be the
blinking cursor, with no text.
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem -passin stdin
5. Copy the contents of the public key to the clipboard using pbcopy, xclip or a similar tool
(you'll need to paste the value into the Console later). For example:
cat ~/.oci/oci_api_key_public.pem | pbcopy

Your API requests will be signed with your private key, and Oracle will use the public key to
verify the authenticity of the request. You must upload the public key to IAM (instructions
below).
How to Get the Key's Fingerprint

You can get the key's fingerprint with the following OpenSSL command. If you're using
Windows, you'll need to install Git Bash for Windows and run the command with that tool.
openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c
When you upload the public key in the Console, the fingerprint is also automatically displayed
there. It looks something like this: 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
Where to Get the Tenancy's OCID and User's OCID

Both OCIDs are in the Console, which is located at https://console.us-ashburn-
1.oraclecloud.com. If you don't have a login and password for the Console, contact an
administrator.
l Tenancy's OCID: At the bottom of the Console pages.

l User's OCID: In the Console on the page showing the user's details. To get to that
page:
o If you're signed in as the user, click your username in the top-right corner of the
Console, and then click User Settings.
o If you're an administrator doing this for another user, instead click Identity, click
Users, and then select the user from the list.
If you're not familiar with OCIDs, see Resource Identifiers.
How to Upload the Public Key

You can upload the PEM public key in the Console, located at https://console.us-ashburn-
1.oraclecloud.com. If you don't have a login and password for the Console, contact an
administrator.

1. Open the Console, and sign in.

2. View the details for the user who will be calling the API with the key pair:
l If you're signed in as this user, click your username in the top-right corner of the
Console, and then click User Settings.
l If you're an administrator doing this for another user, instead click Identity, click
Users, and then select the user from the list.
3. Click Add Public Key.
4. Paste the contents of the PEM public key in the dialog box and click Add.
The key's fingerprint is displayed (for example,

12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef).
Notice that after you've uploaded your first public key, you can also use the UploadApiKey API
operation to upload additional keys. You can have up to three API key pairs per user. In an
API request, you specify the key's fingerprint to indicate which key you're using to sign the
request.
About the API

The Oracle Cloud Infrastructure APIs are typical REST APIs that use HTTPS requests and
responses. This topic describes basic information about using the APIs.
API Reference and Endpoints

For links to the Oracle Cloud Infrastructure API reference and a list of the regional API
endpoints, see API Reference and Endpoints.
API Version
The base path of the endpoint includes the desired API version (for example, 20160918).
Here's an example for a POST request to create a new VCN in the Ashburn region:
POST https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns

Request Signing Required

All Oracle Cloud Infrastructure API requests must be signed for authentication purposes. For
information about the required credentials and how to sign the requests, see Request
Signatures.
HTTPS and TLS 1.2 Required

All Oracle Cloud Infrastructure API requests must support HTTPS and SSL protocol TLS 1.2.
Maximum Allowed Client Clock Skew

HTTP status code 401 (NotAuthenticated) is returned if the client's clock is skewed more than
5 minutes from the server's. To determine the server's clock time, use this curl command
with the API endpoint:
curl -s --head <endpoint> | grep Date
For example:
curl -s --head https://iaas.us-phoenix-1.oraclecloud.com | grep Date
Request and Response Format

The Oracle Cloud Infrastructure APIs use standard HTTP requests and responses. Each may
contain Oracle-specific headers for pagination, entity tags (ETags), and so on as described
elsewhere in this topic and in the API documentation.
Each response includes a unique Oracle-assigned request ID (for example, bb3f3275-f356-

462a-93c4-bf40fb82bb02) in the opc-request-id response header. If you need to contact
Oracle about a particular request, please provide this request ID.
Many of the API operations require JSON in the request body or return JSON in the response
body. The specific contents of the JSON are described in the API documentation for the
individual operation. Notice that the JSON is not wrapped or labeled according to the
operation's name or the object's name or type.

Note
Make sure to set the Content-Type header to

application/json in your POST and PUT requests that
contain JSON in the body.
Example CreateVcn Request

POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/vcns
host: iaas.us-phoenix-1.oraclecloud.com
opc-retry-token: 239787fs987
Content-Type: application/json
HTTP headers required for authentication
Other HTTP request headers per the HTTP spec
{
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
"displayName": "Apex Virtual Cloud Network",
"cidrBlock": "172.16.0.0/16"
}
Example CreateVcn Response

200 OK
opc-request-id: 6c4d01a6-f764-4325-a3f8-720c8b5cae7b
{
"id": "ocid1.vcn.oc1.phx.aaaaaaaa4ex5pqjtkjhdb4h4gcnko7vx5uto5puj5noa5awznsqpwjt3pqyq",
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
"displayName": "Apex Virtual Cloud Network",
"cidrBlock": "172.16.0.0/16"
"defaultRouteTableId":
"ocid1.routetable.oc1.phx.aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
"defaultSecurityListId":
"ocid1.securitylist.oc1.phx.aaaaaaaac6h4ckr3ncbxmvwinfvzxjbr7owu5hfzbvtu33kfe7hgscs5fjaq"
"defaultDhcpOptionsId":

"ocid1.dhcpoptions.oc1.phx.aaaaaaaawglzn7s5sogyfznl25a4vxgu76c2hrgvzcd3psn6vcx33lzmu2xa"
"state": "PROVISIONING",
"timeCreated": "2016-07-22T17:43:01.389+0000"
}
Error Format
If a request results in an error, the response contains a standard HTTP response code with 4xx
for client errors and 5xx for server errors. The body also includes JSON with an error code
and a description of the error. For example:
{
"code": "InvalidParameter",
"message": "Description may not be empty; description size must be between 1 and 400"
}
For a list of common errors across all services, see API Errors.
Request Throttling
Oracle Cloud Infrastructure applies throttling to many API requests to prevent accidental or
abusive use of resources. If you make too many requests too quickly, you might see some
succeed and others fail. Oracle recommends that you implement an exponential back-off,
starting from a few seconds to a maximum of 60 seconds. When a request fails due to
throttling, the system returns response code 429 and the following error code and description:
{
"code": "TooManyRequests",
"message": "User-rate limit exceeded."
}
Polling for Resource Status

Most Oracle Cloud Infrastructure resources, such as compute instances, have lifecycles. In
many cases, you want your code to wait until a resource or work request reaches a specific
state, or a timeout is exceeded, before taking further action.

You can poll a resource to determine its state. For example, when you call GetInstance, the
response body contains an instance resource that includes the lifecycleState attribute. You
might want your code to wait until the instance's lifecycleState is RUNNING before
proceeding.
Different resources take different amounts of time to transition between states. Therefore,
the optimal frequency and duration parameters for a polling strategy can vary among
resources. The Oracle Cloud Infrastructure SDK waiters use the following default strategy:
l Use an exponential back-off, starting from a few seconds to a maximum of 30 seconds

between poll attempts.
l Poll up to 20 minutes, and then stop.
Or more information on waiters, see:
l Java SDK waiters documentation

l Ruby SDK waiters documentation
Where to Find Your Tenancy's OCID

If you use the API, you'll need your tenancy's OCID in order to sign the requests (see Request
Signatures). You'll also need it for some of the IAM API operations. An OCID is an Oracle
Cloud ID (see Resource Identifiers).
You can find your tenancy's OCID in the Console, in the footer at the bottom of the page. The
tenancy OCID looks something like this (notice the word "tenancy" in it):
ocid1.
tenancy.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq.
List Pagination
When you call a "List" operation (for example, ListInstances), you can paginate the results
and limit the response to only one page of results. To do this, in the GET request, set the
limit to the number of items you want returned in the response. The opc-next-page header
will then appear in the response if there could be items left to get. Include the header's value

as the page parameter in the subsequent GET request. Repeat this process until you page
forward through the entire list.
Retry Token
For some operations you can provide a unique retry token (opc-retry-token) so the request
can be retried in case of a timeout or server error without the risk of executing that same
action again. The token expires after 24 hours, but can be invalidated before then due to
conflicting operations (for example, if a resource has been deleted and purged from the
system, then a retry of the original creation request may be rejected).
ETags for Optimistic Concurrency Control

The API supports etags for the purposes of optimistic concurrency control. The GET and POST
calls return an etag response header with a value you should store. When you later want to
update or delete the resource, set the if-match header to the ETag you received for the
resource. The resource will then be updated or deleted only if the ETag you provide matches
the current value of that resource's ETag.
Null vs. Empty Strings for Optional Parameters

If you send an empty string ("") as the value of an optional parameter, the API validates the
value as normal (for example, checks against minimum and maximum allowed length, and so
on). Often the minimum allowed length is 1, so an error would be returned. If you don't set
the value (it's null), the API performs no validation, and some other action may occur. For
example: if you don't set a value for the displayName when creating a new VCN object, the
service will auto-generate a value.
API Reference and Endpoints

Oracle Cloud Infrastructure has these APIs and corresponding regional endpoints:

Audit API
API reference
l https://audit.us-ashburn-1.oraclecloud.com
l https://audit.us-phoenix-1.oraclecloud.com
l https://audit.eu-frankfurt-1.oraclecloud.com
l https://audit.uk-london-1.oraclecloud.com
Core Services API (covering Networking, Compute, and Block Volume)

API reference
l https://iaas.us-ashburn-1.oraclecloud.com
l https://iaas.us-phoenix-1.oraclecloud.com
l https://iaas.eu-frankfurt-1.oraclecloud.com
l https://iaas.uk-london-1.oraclecloud.com
Database API
API reference
l https://database.us-ashburn-1.oraclecloud.com
l https://database.us-phoenix-1.oraclecloud.com
l https://database.eu-frankfurt-1.oraclecloud.com
l https://database.uk-london-1.oraclecloud.com
DNS API
API reference

l https://dns.us-ashburn-1.oraclecloud.com
l https://dns.us-phoenix-1.oraclecloud.com
l https://dns.eu-frankfurt-1.oraclecloud.com
l https://dns.uk-london-1.oraclecloud.com
Email Delivery API

API reference
l https://email.us-phoenix-1.oraclecloud.com
File Storage API

API reference
l https://filestorage.us-ashburn-1.oraclecloud.com
l https://filestorage.us-phoenix-1.oraclecloud.com
l https://filestorage.us-frankfurt-1.oraclecloud.com
l https://filestorage.uk-london-1.oraclecloud.com
IAM API
API reference
l https://identity.us-ashburn-1.oraclecloud.com
l https://identity.us-phoenix-1.oraclecloud.com
l https://identity.eu-frankfurt-1.oraclecloud.com
l https://identity.uk-london-1.oraclecloud.com

Note
Use the Endpoint of Your Home Region for All IAM API Calls
When you sign up for Oracle Cloud Infrastructure,

Oracle creates a tenancy for you in one region. This is
your home region. Your home region is where your IAM
resources are defined. When you subscribe to a new
region, your IAM resources are replicated in the new
region, however, the master definitions reside in your
home region and can only be changed there. Make all
IAM API calls against your home region endpoint. The
changes automatically replicate to all regions. If you try
to make an IAM API call against a region that is not your
home region, you will receive an error.
Load Balancing API

API reference
l https://iaas.us-ashburn-1.oraclecloud.com
l https://iaas.us-phoenix-1.oraclecloud.com
l https://iaas.eu-frankfurt-1.oraclecloud.com
l https://iaas.uk-london-1.oraclecloud.com
Object Storage and Archive Storage

Both Object Storage and Archive Storage are accessible with the following APIs:

Object Storage API

API reference
l https://objectstorage.us-ashburn-1.oraclecloud.com
l https://objectstorage.us-phoenix-1.oraclecloud.com
l https://objectstorage.eu-frankfurt-1.oraclecloud.com
l https://objectstorage.uk-london-1.oraclecloud.com
Amazon S3 Compatibility API

API reference
l https://<object_storage_namespace>.compat.objectstorage.us-phoenix-
1.oraclecloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-ashburn-
1.oraclecloud.com
l https://<object_storage_namespace>.compat.objectstorage.eu-frankfurt-
1.oraclecloud.com
l https://<object_storage_namespace>.compat.objectstorage.uk-london-
1.oraclecloud.com
Tip
See Understanding Object Storage Namespaces for

information regarding how to find your Object Storage
namespace.

Swift API (only for use with Oracle RMAN)

l https://swiftobjectstorage.us-phoenix-1.oraclecloud.com
l https://swiftobjectstorage.us-ashburn-1.oraclecloud.com
l https://swiftobjectstorage.eu-frankfurt-1.oraclecloud.com
l https://swiftobjectstorage.uk-london-1.oraclecloud.com
API Errors
Common Errors Returned by All Services

The following table lists the common errors returned by all the services for Oracle Cloud
Infrastructure.
HTTP Error Code Description Retry

Status
Code
400 CannotParseRequest The request is incorrectly formatted. No.
400 InvalidParameter A parameter is invalid or incorrectly No.

formatted.
400 LimitExceeded Fulfilling this request exceeds the Oracle- No.

defined limit for this tenancy for this
resource type.
400 MissingParameter A required parameter is missing. No.
400 QuotaExceeded Fulfilling this request exceeds the No.

administrator-defined quota for this
compartment for this resource.


Status
Code
400 RelatedResourceNot A resource specified in the body of the Yes,

AuthorizedOrNotFound request was not found, or you do not have with
authorization to access that resource. backoff.
401 NotAuthenticated The required authentication information Yes,

was not provided or was incorrect. There with
are other reasons why this error code is backoff.
generated. For more information, see
HTML Status Code 401.
402 SignUpRequired This operation requires opt-in before it No.

may be called.
404 NotAuthorizedOr A resource specified via the URI (path or Yes,

NotFound query parameters) of the request was not with
found, or you do not have authorization to backoff.
access that resource. For more
information, see HTML Status Code 404.
404 NotFound There is no operation supported at the No.

URI path and HTTP method you specified
in the request.
409 IncorrectState The requested state for the resource Yes,

conflicts with its current state. with
backoff.


Status
Code
409 InvalidatedRetryToken The provided retry token was used in an No.

earlier request that resulted in a system
update, but a subsequent operation
invalidated the token. This can happen,
for example, in cases where an entity
created with the same token has since
been deleted. If the system state change
that is associated with this request should
be performed again, retry it using a
different token.
409 NotAuthorizedOr You do not have authorization to perform Yes,

ResourceAlreadyExists this request, or the resource you are with
attempting to create already exists. This backoff.
error code is returned only from create
operations, where it is returned instead of
the more general
NotAuthorizedOrNotFound error
code.”
412 NoEtagMatch The ETag specified in the request does not No.
match the ETag for the resource.
429 TooManyRequests You have issued too many requests to the Yes,
Oracle Cloud Infrastructure APIs in too with
short of an amount of time. backoff.
500 InternalServerError An internal server error occurred. Yes,

with
backoff.

Error Details and Troubleshooting

HTTP STATUS CODE: 401
l Missing or incorrect authentication information. Verify that all the required

information (tenant OCID, user OCID, fingerprint, and private key) is provided and
accurate. Verify that the public key corresponding to the fingerprint has been
uploaded for the user. For more information, see Required Keys and OCIDs.
l Clock skew. This status code is returned if the client's clock is skewed more than
five (5) minutes from the server's clock. For more information, see Maximum
Allowed Client Clock Skew.
l API request signature error. This status code is returned if a required header is
missing from a signing string. For more information, see Request Signatures.
ERROR CODES : NOTAUTHORIZEDORNOTFOUND,

RELATEDRESOURCENOTAUTHORIZEDORNOTFOUND ,
NOTAUTHORIZEDORRESOURCEALREADYEXISTS
l Authorization error. Verify that the user is in a group that has the permissions to
work with resources in a compartment.
l Compartment or resource not found. Verify that the compartment or resource
exist and is referenced correctly. For example, this status code is returned for
either of the following errors:
o CompartmentNotFound if a compartment doesn't exist
o VolumeNotFound if a volume doesn't exist
Request Signatures
This topic describes how to sign Oracle Cloud Infrastructure API requests.
Signing samples are included for the following:
l Bash
l C#

l Java
l NodeJS
l Perl
l PHP
l Python
l Ruby
Signature Version 1
The signature described here is version 1 of the Oracle Cloud Infrastructure API signature. In
the future, if Oracle modifies the method for signing requests, the version number will be
incremented and your company will be notified.
Required Credentials and OCIDs

You need an API signing key in the correct format. See Required Keys and OCIDs.
Warning
Client Clock Skew
If the client's clock is skewed more than 5 minutes, a

401 (NotAuthenticated) HTTP status code is returned.
This will affect your API requests. For more
information, see Maximum Allowed Client Clock Skew.
You also need the OCIDs for your tenancy and user. See Where to Get the Tenancy's OCID and
User's OCID.
Summary of Signing Steps

In general, these are the steps required to sign a request:

1. Form the HTTPS request (SSL protocol TLS 1.2 is required).

2. Create the signing string, which is based on parts of the request.
3. Create the signature from the signing string, using your private key and the RSA-
SHA256 algorithm.
4. Add the resulting signature and other required information to the Authorization
header in the request.
See the remaining sections in this topic for details about these steps.
Specification You Need to Be Familiar With

To learn how to perform steps 2-4 in the process above, refer to draft-cavage-http-
signatures-08. It's a draft specification that forms the basis for how Oracle handles request
signatures. It describes generally how to form the signing string, how to create the signature,
and how to add the signature and required information to the request. The remaining sections
in this topic assume you're familiar with it. Important details of the Oracle Cloud
Infrastructure implementation of the reference are listed in the next section.
Special Implementation Details

The following sections describe important items to note about the Oracle Cloud Infrastructure
implementation of the spec.
Authorization Header
The Oracle Cloud Infrastructure signature uses the "Signature" Authentication scheme (with
an Authorization header), and not the Signature HTTP header.
Required Headers
This section describes the headers that must be included in the signing string.

Note
Error if Required Header is Missing
If a required header is missing, your client will receive

a 401 "Unauthorized" response.
For GET and DELETE requests (when there's no content in the request body), the signing string
must include at least these headers:
l (request-target) (as described in draft-cavage-http-signatures-08)

l host
l date or x-date (if both are included, Oracle uses x-date)
For PUT and POST requests (when there's content in the request body), the signing string
must include at least these headers:
l (request-target)
l host

l x-content-sha256 (except for Object Storage PUT requests; see the next section)
l content-type
l content-length

Warning
For PUT and POST requests, your client must compute

the x-content-sha256 and include it in the request and
signing string, even if the body is an empty string. Also,
the content-length is always required in the request
and signing string, even if the body is empty. Some
HTTP clients will not send the content-length if the
body is empty, so you must explicitly ensure your client
sends it. If date and x-date are both included, Oracle
uses x-date. The x-date is used to protect against the
reuse of the signed portion of the request (replay
attacks).
The one exception is for Object Storage PUT requests on

objects (see the next section).
Special Instructions for Object Storage PUT
For Object Storage PUT requests, the signing string must include at least these headers:
l (request-target)
l host
If the request also includes any of the other headers that are normally required for PUT
requests (see the list above), then those headers must also be included in the signing string.
Case and Order of Headers
The headers must be all lowercase in the signing string.

The order of the headers in the signing string does not matter. Just make sure to specify the
order in the headers parameter in the Authorization header, as described in the draft-
cavage-http-signatures-05.
Warning
The (request-target) includes the path and query

string from the request. Oracle expects that you will
create the signing string with the query parameters in
the same order as they appear in the request. If the
request query parameters change order after signing
occurs, authentication will fail.
URL Encoding of Path and Query String
When forming the signing string, you must URL encode all parameters in the path and query
string (but not the headers) according to RFC 3986.
Key Identifier
You must set keyId="<TENANCY OCID>/<USER OCID>/<KEY FINGERPRINT>" in the

Authorization header that you add to the request. To get those values, see Where to Get the
Tenancy's OCID and User's OCID. An example keyId looks like this (wrapped to better fit the
page):
ocid1.tenancy.oc1..exampleuwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq/ocid1.user.oc1..exampleb
a3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq/40:a4:f8:a0:40:4f:a3:2f:e0:fd:4e:b9:25:72:81:5f
Signing Algorithm
The signing algorithm must be RSA-SHA256, and you must set algorithm="rsa-sha256" in
the Authorization header (notice the quotation marks).

Signature Version
You should include version="1" in the Authorization header (notice the quotation marks).
If you do not, it's assumed that you're using whatever the current version is (which is version
1 at this time).
Example Header
Here's an example of the general syntax of the Authorization header (for a request with
content in the body):
Authorization: Signature version="1",keyId="<tenancy_ocid>/<user_ocid>/<key_
fingerprint>",algorithm="rsa-sha256",headers="(request-target) date x-content-sha256 content-type
content-length",signature="Base64(RSA-SHA256(<signing_string>))"
Test Values
Here's an example key pair, two example requests, and the resulting Authorization header
for each.
Warning
The example signatures use the RSA 2048-bit keys

below. Use these keys only for testing your signing
code, not for sending production requests.

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3
6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6
Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw
oYi+1hqp1fIekaxsyQIDAQAB
-----END PUBLIC KEY-----
-----BEGIN RSA PRIVATE KEY-----

MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF
NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F
UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB
AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA

QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK
kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg
f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u
412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc
mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7
kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA
gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW
G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI
7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA==
-----END RSA PRIVATE KEY-----
The public key is stored under keyId:
ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/ocid1.user.oc1..aaaaaaa
at5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/73:61:a2:21:67:e0:df:be:7e:4b:93:1e:15:98:a5:b7
For the following GET request (line breaks inserted between query parameters for easier reading; also
notice the URL encoding as mentioned earlier):
GET https://iaas.us-phoenix-1.oraclecloud.com/20160918/instances
?availabilityDomain=Pjwf%3A%20PHX-AD-1
&compartmentId=ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa
&displayName=TeamXInstances
&volumeId=ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q
Date: Thu, 05 Jan 2014 21:31:40 GMT
The signing string would be (line breaks inserted into the (request-target) header for easier reading):
date: Thu, 05 Jan 2014 21:31:40 GMT

(request-target): get /20160918/instances?availabilityDomain=Pjwf%3A%20PH
X-AD-1&compartmentId=ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2i
dnccdflvjsnog7mlr6rtdb25gilchfeyjxa&displayName=TeamXInstances&
volumeId=ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h
4lgvyndsdsnoiwr5q
The Authorization header would be:

Signature version="1",headers="date (request-target) host",keyId="ocid1.t

enancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/
ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3ryn
jq/73:61:a2:21:67:e0:df:be:7e:4b:93:1e:15:98:a5:b7",algorithm="rsa-sha256
",signature="GBas7grhyrhSKHP6AVIj/h5/Vp8bd/peM79H9Wv8kjoaCivujVXlpbKLjMPe
DUhxkFIWtTtLBj3sUzaFj34XE6YZAHc9r2DmE4pMwOAy/kiITcZxa1oHPOeRheC0jP2dqbTll
8fmTZVwKZOKHYPtrLJIJQHJjNvxFWeHQjMaR7M="
For the following POST request:
POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/volumeAttachments
Date: Thu, 05 Jan 2014 21:31:40 GMT
{
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa",
"instanceId": "ocid1.instance.oc1.phx.abuw4ljrlsfiqw6vzzxb43vyypt4pkodawglp3wqxjqofakrwvou52gb6s5a",
"volumeId": "ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q"
}
The signing string would be:
date: Thu, 05 Jan 2014 21:31:40 GMT

(request-target): post /20160918/volumeAttachments
content-length: 316
content-type: application/json
x-content-sha256: V9Z20UJTvkvpJ50flBzKE32+6m2zJjweHpDMX/U4Uy0=
The Authorization header would be:
Signature version="1",headers="date (request-target) host content-length c

ontent-type x-content-sha256",keyId="ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr
4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/ocid1.user.oc1..aaaaaaaat5nvwcn
a5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/73:61:a2:21:67:e0:df:be:7e:4b
:93:1e:15:98:a5:b7",algorithm="rsa-sha256",signature="Mje8vIDPlwIHmD/cTDwR
xE7HaAvBg16JnVcsuqaNRim23fFPgQfLoOOxae6WqKb1uPjYEl0qIdazWaBy/Ml8DRhqlocMwo
SXv0fbukP8J5N80LCmzT/FFBvIvTB91XuXI3hYfP9Zt1l7S6ieVadHUfqBedWH0itrtPJBgKmrWso="
Sample Code
This section shows the basic code for signing API requests.

Bash
.
# Version: 1.0.1
# Usage:
# oci-curl <host> <method> [file-to-send-as-body] <request-target> [extra-curl-args]
#
# ex:
# oci-curl iaas.us-ashburn-1.oraclecloud.com get "/20160918/instances?compartmentId=some-compartment-
ocid"
# oci-curl iaas.us-ashburn-1.oraclecloud.com post ./request.json "/20160918/vcns"
function oci-curl {
# TODO: update these values to your own
local tenancyId="ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq";
local authUserId="ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq";
local keyFingerprint="20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34";
local privateKeyPath="/Users/someuser/.oci/oci_api_key.pem";
local alg=rsa-sha256
local sigVersion="1"
local now="$(LC_ALL=C \date -u "+%a, %d %h %Y %H:%M:%S GMT")"
local host=$1
local method=$2
local extra_args
local keyId="$tenancyId/$authUserId/$keyFingerprint"
case $method in
"get" | "GET")
local target=$3
extra_args=("${@: 4}")
local curl_method="GET";
local request_method="get";
;;
"delete" | "DELETE")
local target=$3
local curl_method="DELETE";
local request_method="delete";
;;

"head" | "HEAD")
local target=$3
local curl_method="HEAD";
local request_method="head";
;;
"post" | "POST")
local body=$3
local target=$4
local curl_method="POST";
local request_method="post";
local content_sha256="$(openssl dgst -binary -sha256 < $body | openssl enc -e -base64)";
local content_type="application/json";
local content_length="$(wc -c < $body | xargs)";
;;
"put" | "PUT")
local body=$3
local target=$4
local curl_method="PUT"
local request_method="put"
local content_sha256="$(openssl dgst -binary -sha256 < $body | openssl enc -e -base64)";
local content_type="application/json";
local content_length="$(wc -c < $body | xargs)";
;;
*) echo "invalid method"; return;;

esac
# This line will url encode all special characters in the request target except "/", "?", "=", and "&",
since those characters are used
# in the request target to indicate path and query string structure. If you need to encode any of "/",
"?", "=", or "&", such as when
# used as part of a path value or query string key or value, you will need to do that yourself in the
request target you pass in.
local escaped_target="$(echo $( rawurlencode "$target" ))"

local request_target="(request-target): $request_method $escaped_target"

local date_header="date: $now"

local host_header="host: $host"
local content_sha256_header="x-content-sha256: $content_sha256"
local content_type_header="content-type: $content_type"
local content_length_header="content-length: $content_length"
local signing_string="$request_target\n$date_header\n$host_header"
local headers="(request-target) date host"
local curl_header_args
curl_header_args=(-H "$date_header")
local body_arg
body_arg=()
if [ "$curl_method" = "PUT" -o "$curl_method" = "POST" ]; then

signing_string="$signing_string\n$content_sha256_header\n$content_type_header\n$content_length_header"
headers=$headers" x-content-sha256 content-type content-length"
curl_header_args=("${curl_header_args[@]}" -H "$content_sha256_header" -H "$content_type_header" -H
"$content_length_header")
body_arg=(--data-binary @${body})
fi
local sig=$(printf '%b' "$signing_string" | \

openssl dgst -sha256 -sign $privateKeyPath | \
openssl enc -e -base64 | tr -d '\n')
curl "${extra_args[@]}" "${body_arg[@]}" -X $curl_method -sS https://${host}${escaped_target} "${curl_

header_args[@]}" \
-H "Authorization: Signature
version=\"$sigVersion\",keyId=\"$keyId\",algorithm=\"$alg\",headers=\"${headers}\",signature=\"$sig\""
}
# url encode all special characters except "/", "?", "=", and "&"
function rawurlencode {
local string="${1}"
local strlen=${#string}
local encoded=""
local pos c o
for (( pos=0 ; pos<strlen ; pos++ )); do

c=${string:$pos:1}
case "$c" in
[-_.~a-zA-Z0-9] | "/" | "?" | "=" | "&" ) o="${c}" ;;
* ) printf -v o '%%%02x' "'$c"
esac

encoded+="${o}"
done
echo "${encoded}"
}
An example of a request.json file that could be used with the preceding Bash code is shown
next:
{
"compartmentId": "some-compartment-id",
"displayName": "some-vcn-display-name",
"cidrBlock": "10.0.0.0/16"
}
C#
.
// Version 1.0.1
namespace Oracle.Oci
{
using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;
//
// Nuget Package Manager Console: Install-Package BouncyCastle
// Nuget CLI: nuget install BouncyCastle
//
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.OpenSsl;
using Org.BouncyCastle.Security;
public class Signing

{
public static void Main(string[] args)
{
var tenancyId =

"ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq";
var compartmentId =
"ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa";
var userId = "ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq";
var fingerprint = "20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34";
var privateKeyPath = "private.pem";
var privateKeyPassphrase = "password";
var signer = new RequestSigner(tenancyId, userId, fingerprint, privateKeyPath,

privateKeyPassphrase);
// OCI APIs require TLS 1.2

// uncomment the line below if targeting < .NET Framework 4.6 (HttpWebRequest does not
enable Tls 1.2 by default in earlier versions)
// ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
// GET with query parameters (gets user)

var uri = new Uri($"https://identity.us-ashburn-1.oraclecloud.com/20160918/users/{userId}");
var request = (HttpWebRequest)WebRequest.Create(uri);
request.Method = "GET";
request.Accept = "application/json";
signer.SignRequest(request);
Console.WriteLine($"Authorization header: {request.Headers["authorization"]}");
ExecuteRequest(request);
// POST with body (creates a VCN)

uri = new Uri($"https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns");
var body = string.Format(@"{{""cidrBlock"" : ""10.0.0.0/16"",""compartmentId"" : ""
{0}"",""displayName"" : ""MyVcn""}}", compartmentId);
var bytes = Encoding.UTF8.GetBytes(body);
request = (HttpWebRequest)WebRequest.Create(uri);
request.Method = "POST";
request.Accept = "application/json";
request.ContentType = "application/json";
request.Headers["x-content-sha256"] = Convert.ToBase64String(SHA256.Create().ComputeHash
(bytes));
using (var stream = request.GetRequestStream())

{
stream.Write(bytes, 0, bytes.Length);
}
signer.SignRequest(request);
Console.WriteLine($"Authorization header: {request.Headers["authorization"]}");
ExecuteRequest(request);
}
private static void ExecuteRequest(HttpWebRequest request)

{
try
{
var webResponse = (HttpWebResponse)request.GetResponse();
var response = new StreamReader(webResponse.GetResponseStream()).ReadToEnd();
Console.WriteLine($"Response: {response}");
}
catch (WebException e)
{
Console.WriteLine($"Exception occurred: {e.Message}");
Console.WriteLine($"Response: {new StreamReader(e.Response.GetResponseStream
()).ReadToEnd()}");
}
}
public class RequestSigner

{
private static readonly IDictionary<string, List<string>> RequiredHeaders = new
Dictionary<string, List<string>>
{
{ "GET", new List<string>{"date", "(request-target)", "host" }},
{ "HEAD", new List<string>{"date", "(request-target)", "host" }},
{ "DELETE", new List<string>{"date", "(request-target)", "host" }},
{ "PUT", new List<string>{"date", "(request-target)", "host", "content-length",
"content-type", "x-content-sha256" }},
{ "POST", new List<string>{"date", "(request-target)", "host", "content-length",
"content-type", "x-content-sha256" }}
};
private readonly string keyId;

private readonly ISigner signer;
/// <summary>
/// Adds the necessary authorization header for signed requests to OCI services.
/// Documentation for request signatures can be found here: https://docs.us-phoenix-
1.oraclecloud.com/Content/API/Concepts/signingrequests.htm
/// </summary>
/// <param name="tenancyId">The tenancy OCID</param>
/// <param name="userId">The user OCID</param>
/// <param name="fingerprint">The fingerprint corresponding to the provided key</param>
/// <param name="privateKeyPath">Path to a PEM file containing a private key</param>
/// <param name="privateKeyPassphrase">An optional passphrase for the private key</param>
public RequestSigner(string tenancyId, string userId, string fingerprint, string
privateKeyPath, string privateKeyPassphrase="")
{
// This is the keyId for a key uploaded through the console
this.keyId = $"{tenancyId}/{userId}/{fingerprint}";
AsymmetricCipherKeyPair keyPair;
using (var fileStream = File.OpenText(privateKeyPath))
{
try {
keyPair = (AsymmetricCipherKeyPair)new PemReader(fileStream, new Password
(privateKeyPassphrase.ToCharArray())).ReadObject(); }
catch (InvalidCipherTextException) {
throw new ArgumentException("Incorrect passphrase for private key");
}
}
RsaKeyParameters privateKeyParams = (RsaKeyParameters)keyPair.Private;

this.signer = SignerUtilities.GetSigner("SHA-256withRSA");
this.signer.Init(true, privateKeyParams);
}
public void SignRequest(HttpWebRequest request)

{
if (request == null) { throw new ArgumentNullException(nameof(request)); }
// By default, request.Date is DateTime.MinValue, so override to DateTime.UtcNow, but

preserve the value if caller has already set the Date
if (request.Date == DateTime.MinValue) { request.Date = DateTime.UtcNow; }

var requestMethodUpper = request.Method.ToUpperInvariant();

List<string> headers;
if (!RequiredHeaders.TryGetValue(requestMethodUpper, out headers)) {
throw new ArgumentException($"Don't know how to sign method: {request.Method}");
}
// for PUT and POST, if the body is empty we still must explicitly set content-length =
0 and x-content-sha256
// the caller may already do this, but we shouldn't require it since we can determine it
here
if (request.ContentLength <= 0 && (string.Equals(requestMethodUpper, "POST") ||
string.Equals(requestMethodUpper, "PUT")))
{
request.ContentLength = 0;
request.Headers["x-content-sha256"] = Convert.ToBase64String(SHA256.Create
().ComputeHash(new byte[0]));
}
var signingStringBuilder = new StringBuilder();

var newline = string.Empty;
foreach (var headerName in headers)
{
string value = null;
switch (headerName)
{
case "(request-target)":
value = buildRequestTarget(request);
break;
case "host":
value = request.Host;
break;
case "content-length":
value = request.ContentLength.ToString();
break;
default:
value = request.Headers[headerName];
break;
}
if (value == null) { throw new ArgumentException($"Request did not contain required

header: {headerName}"); }
signingStringBuilder.Append(newline).Append($"{headerName}: {value}");

newline = "\n";
}
// generate signature using the private key

var bytes = Encoding.UTF8.GetBytes(signingStringBuilder.ToString());
this.signer.BlockUpdate(bytes, 0, bytes.Length);
var signature = Convert.ToBase64String(this.signer.GenerateSignature());
var authorization = $@"Signature version=""1"",headers=""{string.Join(" ",
headers)}"",keyId=""{keyId}"",algorithm=""rsa-sha256"",signature=""{signature}""";
request.Headers["authorization"] = authorization;
}
private static string buildRequestTarget(HttpWebRequest request)

{
// ex. get /20160918/instances
return $"{request.Method.ToLowerInvariant()} {request.RequestUri.PathAndQuery}";
}
}
/// <summary>
/// Implements Bouncy Castle's IPasswordFinder interface to allow opening password protected
private keys.
/// </summary>
public class Password : IPasswordFinder
{
private readonly char[] password;
public Password(char[] password) { this.password = password; }
public char[] GetPassword() { return (char[])password.Clone(); }

}
}
}
Java
This sample omits the optional version field in the Authorization header.
/*
* @version 1.0.1
*
<dependency>

<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>19.0</version>
</dependency>
*/
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.hash.Hashing;
/*
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
</dependency>
*/
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.HttpEntityEnclosingRequestBase;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpRequestBase;
import org.apache.http.entity.ByteArrayEntity;
/*
<dependency>
<groupId>org.tomitribe</groupId>
<artifactId>tomitribe-http-signatures</artifactId>
</dependency>
*/
import org.apache.http.entity.StringEntity;
import org.tomitribe.auth.signatures.MissingRequiredHeaderException;
import org.tomitribe.auth.signatures.PEM;
import org.tomitribe.auth.signatures.Signature;
import org.tomitribe.auth.signatures.Signer;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;

import java.nio.file.Paths;
import java.security.Key;
import java.security.PrivateKey;
import java.security.spec.InvalidKeySpecException;
import java.text.SimpleDateFormat;
import java.util.*;
import java.util.stream.Collectors;
/**
* This example creates a {@link RequestSigner}, then prints out the Authorization header
* that is inserted into the HttpGet object.
*
* <p>
* apiKey is the identifier for a key uploaded through the console.
* privateKeyFilename is the location of your private key (that matches the uploaded public key for
apiKey).
* </p>
*
* The signed HttpGet request is not executed, since instanceId does not map to a real instance.
*/
public class Signing {
public static void main(String[] args) throws UnsupportedEncodingException {
HttpRequestBase request;
// This is the keyId for a key uploaded through the console

String apiKey =
("ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/"
+
"ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/"
+ "20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34");
String privateKeyFilename = "../sample-private-key";
PrivateKey privateKey = loadPrivateKey(privateKeyFilename);
RequestSigner signer = new RequestSigner(apiKey, privateKey);
// GET with query parameters

String uri = "https://iaas.us-ashburn-
1.oraclecloud.com/20160918/instances?availabilityDomain=%s&compartmentId=%s&displayName=%s&volumeId=%s";
uri = String.format(uri,
"Pjwf%3A%20PHX-AD-1",
// Older ocid formats included ":" which must be escaped
"ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa".replace(":",

"%3A"),
"TeamXInstances",
"ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q".replace(":", "%3A")
);
request = new HttpGet(uri);

// Uncomment to use a fixed date
// request.setHeader("Date", "Thu, 05 Jan 2014 21:31:40 GMT");
signer.signRequest(request);
System.out.println(uri);
System.out.println(request.getFirstHeader("Authorization"));
// POST with body

uri = "https://iaas.us-ashburn-1.oraclecloud.com/20160918/volumeAttachments";
request = new HttpPost(uri);
// Uncomment to use a fixed date
// request.setHeader("Date", "Thu, 05 Jan 2014 21:31:40 GMT");
HttpEntity entity = new StringEntity("{\n" +
" \"compartmentId\":
\"ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa\",\n" +
" \"instanceId\":
\"ocid1.instance.oc1.phx.abuw4ljrlsfiqw6vzzxb43vyypt4pkodawglp3wqxjqofakrwvou52gb6s5a\",\n" +
" \"volumeId\":
\"ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q\"\n" +
"}");
((HttpPost)request).setEntity(entity);
signer.signRequest(request);
System.out.println("\n" + uri);
System.out.println(request.getFirstHeader("Authorization"));
/**
* Load a {@link PrivateKey} from a file.
*/
private static PrivateKey loadPrivateKey(String privateKeyFilename) {
try (InputStream privateKeyStream = Files.newInputStream(Paths.get(privateKeyFilename))){
return PEM.readPrivateKey(privateKeyStream);

} catch (InvalidKeySpecException e) {
throw new RuntimeException("Invalid format for private key");
} catch (IOException e) {
throw new RuntimeException("Failed to load private key");
}
}
/**
* A light wrapper around https://github.com/tomitribe/http-signatures-java
*/
public static class RequestSigner {
private static final SimpleDateFormat DATE_FORMAT;
private static final String SIGNATURE_ALGORITHM = "rsa-sha256";
private static final Map<String, List<String>> REQUIRED_HEADERS;
static {
DATE_FORMAT = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US);
DATE_FORMAT.setTimeZone(TimeZone.getTimeZone("GMT"));
REQUIRED_HEADERS = ImmutableMap.<String, List<String>>builder()
.put("get", ImmutableList.of("date", "(request-target)", "host"))
.put("head", ImmutableList.of("date", "(request-target)", "host"))
.put("delete", ImmutableList.of("date", "(request-target)", "host"))
.put("put", ImmutableList.of("date", "(request-target)", "host", "content-length",
"content-type", "x-content-sha256"))
.put("post", ImmutableList.of("date", "(request-target)", "host", "content-length",
"content-type", "x-content-sha256"))
.build();
}
private final Map<String, Signer> signers;
/**
* @param apiKey The identifier for a key uploaded through the console.
* @param privateKey The private key that matches the uploaded public key for the given apiKey.
*/
public RequestSigner(String apiKey, Key privateKey) {
this.signers = REQUIRED_HEADERS
.entrySet().stream()
.collect(Collectors.toMap(
entry -> entry.getKey(),
entry -> buildSigner(apiKey, privateKey, entry.getKey())));
}
/**

* Create a {@link Signer} that expects the headers for a given method.
* @param apiKey The identifier for a key uploaded through the console.
* @param privateKey The private key that matches the uploaded public key for the given apiKey.
* @param method HTTP verb for this signer
* @return
*/
protected Signer buildSigner(String apiKey, Key privateKey, String method) {
final Signature signature = new Signature(
apiKey, SIGNATURE_ALGORITHM, null, REQUIRED_HEADERS.get(method.toLowerCase()));
return new Signer(privateKey, signature);
}
/**
* Sign a request, optionally including additional headers in the signature.
*
* <ol>
* <li>If missing, insert the Date header (RFC 2822).</li>
* <li>If PUT or POST, insert any missing content-type, content-length, x-content-sha256</li>
* <li>Verify that all headers to be signed are present.</li>
* <li>Set the request's Authorization header to the computed signature.</li>
* </ol>
*
* @param request The request to sign
*/
public void signRequest(HttpRequestBase request) {
final String method = request.getMethod().toLowerCase();
// nothing to sign for options
if (method.equals("options")) {
return;
}
final String path = extractPath(request.getURI());
// supply date if missing

if (!request.containsHeader("date")) {
request.addHeader("date", DATE_FORMAT.format(new Date()));
}
// supply host if mossing

if (!request.containsHeader("host")) {
request.addHeader("host", request.getURI().getHost());
}

// supply content-type, content-length, and x-content-sha256 if missing (PUT and POST only)
if (method.equals("put") || method.equals("post")) {
if (!request.containsHeader("content-type")) {
request.addHeader("content-type", "application/json");
}
if (!request.containsHeader("content-length") || !request.containsHeader("x-content-
sha256")) {
byte[] body = getRequestBody((HttpEntityEnclosingRequestBase) request);
if (!request.containsHeader("content-length")) {
request.addHeader("content-length", Integer.toString(body.length));
}
if (!request.containsHeader("x-content-sha256")) {
request.addHeader("x-content-sha256", calculateSHA256(body));
}
}
}
final Map<String, String> headers = extractHeadersToSign(request);

final String signature = this.calculateSignature(method, path, headers);
request.setHeader("Authorization", signature);
}
/**
* Extract path and query string to build the (request-target) pseudo-header.
* For the URI "http://www.host.com/somePath?example=path" return "/somePath?example=path"
*/
private static String extractPath(URI uri) {
String path = uri.getRawPath();
String query = uri.getRawQuery();
if (query != null && !query.trim().isEmpty()) {
path = path + "?" + query;
}
return path;
}
/**
* Extract the headers required for signing from a {@link HttpRequestBase}, into a Map
* that can be passed to {@link RequestSigner#calculateSignature}.
*
* <p>
* Throws if a required header is missing, or if there are multiple values for a single header.

* </p>
*
* @param request The request to extract headers from.
*/
private static Map<String, String> extractHeadersToSign(HttpRequestBase request) {
List<String> headersToSign = REQUIRED_HEADERS.get(request.getMethod().toLowerCase());
if (headersToSign == null) {
throw new RuntimeException("Don't know how to sign method " + request.getMethod());
}
return headersToSign.stream()
// (request-target) is a pseudo-header
.filter(header -> !header.toLowerCase().equals("(request-target)"))
.collect(Collectors.toMap(
header -> header,
header -> {
if (!request.containsHeader(header)) {
throw new MissingRequiredHeaderException(header);
}
if (request.getHeaders(header).length > 1) {
throw new RuntimeException(
String.format("Expected one value for header %s", header));
}
return request.getFirstHeader(header).getValue();
}));
}
/**
* Wrapper around {@link Signer#sign}, returns the {@link Signature} as a String.
*
* @param method Request method (GET, POST, ...)
* @param path The path + query string for forming the (request-target) pseudo-header
* @param headers Headers to include in the signature.
*/
private String calculateSignature(String method, String path, Map<String, String> headers) {
Signer signer = this.signers.get(method);
if (signer == null) {
throw new RuntimeException("Don't know how to sign method " + method);
}
try {
return signer.sign(method, path, headers).toString();
throw new RuntimeException("Failed to generate signature", e);

}
}
/**
* Calculate the Base64-encoded string representing the SHA256 of a request body
* @param body The request body to hash
*/
private String calculateSHA256(byte[] body) {
byte[] hash = Hashing.sha256().hashBytes(body).asBytes();
return Base64.getEncoder().encodeToString(hash);
}
/**
* Helper to safely extract a request body. Because an {@link HttpEntity} may not be
repeatable,
* this function ensures the entity is reset after reading. Null entities are treated as an
empty string.
*
* @param request A request with a (possibly null) {@link HttpEntity}
*/
private byte[] getRequestBody(HttpEntityEnclosingRequestBase request) {
HttpEntity entity = request.getEntity();
// null body is equivalent to an empty string
if (entity == null) {
return "".getBytes(StandardCharsets.UTF_8);
}
// May need to replace the request entity after consuming
boolean consumed = !entity.isRepeatable();
ByteArrayOutputStream content = new ByteArrayOutputStream();
try {
entity.writeTo(content);
throw new RuntimeException("Failed to copy request body", e);
}
// Replace the now-consumed body with a copy of the content stream
byte[] body = content.toByteArray();
if (consumed) {
request.setEntity(new ByteArrayEntity(body));
}
return body;
}
}

NodeJS
/*
Version 1.0.1
Before running this example, install necessary dependencies by running:
npm install http-signature jssha
*/
var fs = require('fs');
var https = require('https');
var os = require('os');
var httpSignature = require('http-signature');
var jsSHA = require("jssha");
// TODO: update these values to your own

var tenancyId = "ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq";
var authUserId = "ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq";
var keyFingerprint = "20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34";
var privateKeyPath = "~/.oci/oci_api_key.pem";
var identityDomain = "identity.us-ashburn-1.oraclecloud.com";

var coreServicesDomain = "iaas.us-ashburn-1.oraclecloud.com";
if(privateKeyPath.indexOf("~/") === 0) {
privateKeyPath = privateKeyPath.replace("~", os.homedir())
}
var privateKey = fs.readFileSync(privateKeyPath, 'ascii');
// signing function as described at https://docs.us-phoenix-

1.oraclecloud.com/Content/API/Concepts/signingrequests.htm
function sign(request, options) {
var apiKeyId = options.tenancyId + "/" + options.userId + "/" + options.keyFingerprint;
var headersToSign = [
"host",

"date",
"(request-target)"
];
var methodsThatRequireExtraHeaders = ["POST", "PUT"];
if(methodsThatRequireExtraHeaders.indexOf(request.method.toUpperCase()) !== -1) {

options.body = options.body || "";
var shaObj = new jsSHA("SHA-256", "TEXT");

shaObj.update(options.body);
request.setHeader("Content-Length", options.body.length);
request.setHeader("x-content-sha256", shaObj.getHash('B64'));
headersToSign = headersToSign.concat([
"content-type",
"content-length",
"x-content-sha256"
]);
}
httpSignature.sign(request, {
key: options.privateKey,
keyId: apiKeyId,
headers: headersToSign
});
var newAuthHeaderValue = request.getHeader("Authorization").replace("Signature ", "Signature

version=\"1\",");
request.setHeader("Authorization", newAuthHeaderValue);
}
// generates a function to handle the https.request response object

function handleRequest(callback) {
return function(response) {
var responseBody = "";
response.on('data', function(chunk) {
responseBody += chunk;
});

response.on('end', function() {
callback(JSON.parse(responseBody));
});
}
}
// gets the OCI user with the specified id

function getUser(userId, callback) {
var options = {
host: identityDomain,
path: "/20160918/users/" + encodeURIComponent(userId),
};
var request = https.request(options, handleRequest(callback));
sign(request, {
privateKey: privateKey,
keyFingerprint: keyFingerprint,
tenancyId: tenancyId,
userId: authUserId
});
request.end();
};
// creates a OCI VCN in the specified compartment

function createVCN(compartmentId, displayName, cidrBlock, callback) {
var body = JSON.stringify({

compartmentId: compartmentId,
displayName: displayName,
cidrBlock: cidrBlock
});
var options = {
host: coreServicesDomain,
path: '/20160918/vcns',
method: 'POST',
headers: {
"Content-Type": "application/json",

}
};
var request = https.request(options, handleRequest(callback));
sign(request, {
body: body,
privateKey: privateKey,
keyFingerprint: keyFingerprint,
tenancyId: tenancyId,
userId: authUserId
});
request.end(body);
};
// test the above functions

console.log("GET USER:");
getUser(authUserId, function(data) {
console.log(data);
console.log("\nCREATING VCN:");
// TODO: replace this with a compartment you have access to

var compartmentIdToCreateVcnIn = tenancyId;
createVCN(compartmentIdToCreateVcnIn, "Test-VCN", "10.0.0.0/16", function(data) {

console.log(data);
});
});
Perl
#!/usr/bin/perl
# Version 1.0.1
# Need the following:
# Modules - Authen::HTTP::Signature, DateTime, DateTime::Format::HTTP, Mozilla::CA, File::Slurp,
LWP::UserAgent, LWP::Protocol::https
# LWP::UserAgent and LWP::Protoco::https >= 6.06

# OpenSSL >= 1.0.1
use strict;
use warnings;
{
package OCISigner;
use Authen::HTTP::Signature;
use Digest::SHA qw(sha256_base64);
use DateTime;
use DateTime::Format::HTTP;
my @generic_headers = (
'date', '(request-target)', 'host'
);
my @body_headers = (
'content-length', 'content-type', 'x-content-sha256'
);
my @all_headers = (@generic_headers, @body_headers);
my %required_headers = (
get => \@generic_headers,
delete => \@generic_headers,
head => \@generic_headers,
post => \@all_headers,
put => \@all_headers
);
sub new {
my ( $class, $api_key, $private_key) = @_;
my $self = {
_api_key => $api_key,
_private_key => $private_key
};
bless $self, $class;
return $self;
}
sub sign_request {
my ( $self, $request ) = @_;
my $verb = lc($request->method);
my $sign_body = grep(/^$verb$/, ('post', 'put'));

$self->inject_missing_headers($request, $sign_body);
my $headers = $required_headers{$verb};
my $all_auth = Authen::HTTP::Signature->new(
key => $self->{_private_key},
request => $request,
key_id => $self->{_api_key},
headers => $headers,
);
$all_auth->sign();
}
sub inject_missing_headers {
my ( $self, $request, $sign_body ) = @_;
$request->header('content-type', 'application/json') unless $request->header('content-type');
$request->header('accept', '*/*') unless $request->header('accept');
my $class = 'DateTime::Format::HTTP';
$request->header('date', $class->format_datetime(DateTime->now)) unless $request->header('date');
$request->header('host', $request->uri->host) unless $request->header('host');

if ($sign_body) {
$request->content('') unless $request->content;
$request->header('content-length', length($request->content)) unless $request->header('content-
length');
$request->header('x-content-sha256', $self->compute_sha256($request->content)) unless $request-
>header('x-content-sha256');
}
}
sub compute_sha256 {
my ( $self, $content ) = @_;
my $digest = sha256_base64($content);
while (length($digest) % 4) {
$digest .= '=';
}
return $digest;
}
} # OCISigner
{
package OCIClient;

use LWP::UserAgent;
use Mozilla::CA;
sub new {
my ( $class, $api_key, $private_key ) = @_;
my $ua = LWP::UserAgent->new;
$ua->ssl_opts(
verify_hostname => 1,
SSL_ca_file => Mozilla::CA::SSL_ca_file()
);
my $self = {
_signer => OCISigner->new($api_key, $private_key),
_ua => $ua
};
bless $self, $class;
return $self;
}
sub make_request {
my ( $self, $request ) = @_;
print "Sending request\n";
$self->{_signer}->sign_request($request);
my $response = $self->{_ua}->request($request);
if ($response->is_success) {
my $message = $response->decoded_content;
print "Received reply: $message\n";
}
else {
print "HTTP GET error code: ", $response->code, "\n";
print "HTTP GET error message: ", $response->message, "\n";
}
}
} # OCIClient
use File::Slurp qw(read_file);
my $api_key = "ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/" .
"ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/" .
"20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34";
my $private_key = read_file('../sample-private-key') or die $!;

my $client = OCIClient->new($api_key, $private_key);
# Uncomment to use a fixed date

#my $fixed_date = 'Thu, 05 Jan 2014 21:31:40 GMT';
my $fixed_date;
# GET with query parameters

# Note: Older ocid formats included ":" which must be escaped
my %query_args = (
availability_domain => "Pjwf%3A%20PHX-AD-1",
compartment_id =>
display_name => "TeamXInstances",
volume_id => "ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q"
);
my $uri = "https://iaas.us-phoenix-1.oraclecloud.com/20160918/instances?availabilityDomain=" .
$query_args{availability_domain} .
"&compartmentId=" .
$query_args{compartment_id} .
"&displayName=" .
$query_args{display_name} .
"&volumeId=" .
$query_args{volume_id};
my $request = HTTP::Request->new(GET => $uri);
$request->header('date', $fixed_date) if $fixed_date;
$client->make_request($request);
# POST with body

$uri = "https://iaas.us-ashburn-1.oraclecloud.com/20160918/volumeAttachments";
my $body = q|{
"compartmentId":
}|;
$request = HTTP::Request->new(POST => $uri);
$request->header('date', $fixed_date) if $fixed_date;
$request->content($body);
$client->make_request($request);

PHP
.
<? php
// Version 1.0.0
//
// Dependencies:
// - PHP curl extension
// - Guzzle (composer require guzzlehttp/guzzle)
//
require 'vendor/autoload.php';
use Psr\Http\Message\RequestInterface;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;
use GuzzleHttp\Middleware;
// TODO: Update these for your tenancy

$tenancy_id = 'ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq';
$user_id = 'ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq';
$thumbprint = '20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34';
$region = 'us-phoenix-1';
$key_location = 'file://private.pem';
$key_passphrase = 'password';
$namespace = 'MyNamespace';
$bucket_name = 'MyBucket';
$file_to_upload = 'myfile.txt';
$key_id = "$tenancy_id/$user_id/$thumbprint";
function sign_string($data, $key_path, $passphrase){

$pkeyid = openssl_pkey_get_private($key_path, $passphrase);
if (!$pkeyid) {
exit('Error reading private key');
}
openssl_sign($data, $signature, $pkeyid, OPENSSL_ALGO_SHA256);

// free the key from memory

openssl_free_key($pkeyid);
return base64_encode($signature);
}
function oci_signer_middleware(RequestInterface $request) {

global $key_id;
global $key_location;
global $key_passphrase;
// headers required for all HTTP verbs

$headers = "date (request-target) host";
// example: Thu, 05 Jan 2014 21:31:40 GMT

$date=gmdate("D, d M Y H:i:s T", time());
$method = strtolower($request->getMethod());
$request_target = $request->getRequestTarget();
$host = $request->getHeader('Host')[0];
$request = $request->withHeader('Date', $date);
$signing_string = "date: $date\n(request-target): $method $request_target\nhost: $host";
// additional required headers for POST and PUT requests

if ($method == 'post' || $method == 'put') {
$content_length = $request->getHeader('Content-Length')[0];
// if content length is 0 we still need to explicitly send the Content-Length header

if (!$content_length){
$content_length = 0;
$request = $request->withHeader('Content-Length', 0);
}
$content_type = $request->getHeader('Content-Type')[0];
$content_sha256 = base64_encode(hex2bin(hash("sha256", $request->getBody())));
$request = $request->withHeader('x-content-sha256', $content_sha256);
$headers = $headers . " content-length content-type x-content-sha256";

$signing_string = $signing_string . "\ncontent-length: $content_length\ncontent-type: $content_
type\nx-content-sha256: $content_sha256";

echo "Signing string:\n$signing_string".PHP_EOL;
$signature = sign_string($signing_string, $key_location, $key_passphrase);
$authorization_header = "Signature version=\"1\",keyId=\"$key_id\",algorithm=\"rsa-

sha256\",headers=\"$headers\",signature=\"$signature\"";
$request = $request->withHeader('Authorization', $authorization_header);
echo "\nRequest headers:".PHP_EOL;

foreach ($request->getHeaders() as $name => $values) {
echo $name . ': ' . implode(', ', $values) . "\n";
}
return $request;
}
// EXAMPLE REQUESTS
$handler = new CurlHandler();
$stack = HandlerStack::create($handler);
// place signing middleware after prepare-body so it can access Content-Length header

$stack->after('prepare_body', Middleware::mapRequest('oci_signer_middleware'));
$client = new Client([

'handler' => $stack
]);
// GET current user

echo "************************************".PHP_EOL;
echo "Getting user: $user_id...".PHP_EOL;
echo "************************************".PHP_EOL;
$response = $client->get("https://identity.$region.oraclecloud.com/20160918/users/$user_id");
echo "\nResponse:\n";
echo $response->getStatusCode().PHP_EOL;
echo $response->getBody().PHP_EOL.PHP_EOL;
// Create a VCN
echo "************************************".PHP_EOL;
echo "Creating VCN...".PHP_EOL;
echo "************************************".PHP_EOL;

$body = "{\"cidrBlock\" : \"10.0.0.0/16\",\"compartmentId\" : \"$tenancy_id\",\"displayName\" :

\"MyPhpVcn\"}";
$response = $client->post("https://iaas.$region.oraclecloud.com/20160918/vcns", [ "body" => $body,
'headers' => ['Content-Type' => 'application/json']]);
echo "\nResponse:".PHP_EOL;
echo $response->getBody().PHP_EOL.PHP_EOL;
// PUT object with no content

echo "************************************".PHP_EOL;
echo "Putting object 'NewObject'...".PHP_EOL;
echo "************************************".PHP_EOL;
$body = '';
$response = $client->put("https://objectstorage.$region.oraclecloud.com/n/$namespace/b/$bucket_
name/o/NewObject", [ "body" => $body, 'headers' => ['Content-Type' => 'application/json']]);
echo $response->getBody().PHP_EOL;
// PUT object with content

echo "************************************".PHP_EOL;
echo "Putting object 'NewObject2'...".PHP_EOL;
echo "************************************".PHP_EOL;
$file_handle = fopen($file_to_upload, "rb");

$body = "";
while (!feof($file_handle)) {
$body = $body . fgets($file_handle);
}
fclose($file_handle);
$response = $client->put("https://objectstorage.$region.oraclecloud.com/n/$namespace/b/$bucket_
name/o/NewObject2", [ "body" => $body, 'headers' => ['Content-Type' => 'application/octet-stream']]);
echo $response->getBody().PHP_EOL;
?>
Python

Important
This Python sample code requires TLS 1.2, which is not

included with the default Python on Mac OS X.
import base64
import email.utils
import hashlib
# pip install httpsig_cffi requests six

import httpsig_cffi.sign
import requests
import six
# Version 1.0.1
class SignedRequestAuth(requests.auth.AuthBase):
"""A requests auth instance that can be reused across requests"""
generic_headers = [
"date",
"(request-target)",
"host"
]
body_headers = [
"content-length",
"content-type",
"x-content-sha256",
]
required_headers = {
"get": generic_headers,
"head": generic_headers,
"delete": generic_headers,
"put": generic_headers + body_headers,
"post": generic_headers + body_headers
}
def __init__(self, key_id, private_key):

# Build a httpsig_cffi.requests_auth.HTTPSignatureAuth for each
# HTTP method's required headers
self.signers = {}
for method, headers in six.iteritems(self.required_headers):

signer = httpsig_cffi.sign.HeaderSigner(
key_id=key_id, secret=private_key,
algorithm="rsa-sha256", headers=headers[:])
use_host = "host" in headers
self.signers[method] = (signer, use_host)
def inject_missing_headers(self, request, sign_body):

# Inject date, content-type, and host if missing
request.headers.setdefault(
"date", email.utils.formatdate(usegmt=True))
request.headers.setdefault("content-type", "application/json")
request.headers.setdefault(
"host", six.moves.urllib.parse.urlparse(request.url).netloc)
# Requests with a body need to send content-type,

# content-length, and x-content-sha256
if sign_body:
body = request.body or ""
if "x-content-sha256" not in request.headers:
m = hashlib.sha256(body.encode("utf-8"))
base64digest = base64.b64encode(m.digest())
base64string = base64digest.decode("utf-8")
request.headers["x-content-sha256"] = base64string
request.headers.setdefault("content-length", len(body))
def __call__(self, request):

verb = request.method.lower()
# nothing to sign for options
if verb == "options":
return request
signer, use_host = self.signers.get(verb, (None, None))
if signer is None:
raise ValueError(
"Don't know how to sign request verb {}".format(verb))
# Inject body headers for put/post requests, date for all requests
sign_body = verb in ["put", "post"]
self.inject_missing_headers(request, sign_body=sign_body)
if use_host:
host = six.moves.urllib.parse.urlparse(request.url).netloc
else:

host = None
signed_headers = signer.sign(
request.headers, host=host,
method=request.method, path=request.path_url)
request.headers.update(signed_headers)
return request
# -----BEGIN RSA PRIVATE KEY-----

# ...
# -----END RSA PRIVATE KEY-----
with open("../sample-private-key") as f:
private_key = f.read().strip()
# This is the keyId for a key uploaded through the console

api_key = "/".join([
"ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
"ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq",
"20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34"
])
auth = SignedRequestAuth(api_key, private_key)
headers = {
"content-type": "application/json",
"date": email.utils.formatdate(usegmt=True),
# "date": "Thu, 05 Jan 2014 21:31:40 GMT"
}

uri = "https://iaas.us-ashburn-1.oraclecloud.com/20160918/instances?availabilityDomain={availability_
domain}&compartmentId={compartment_id}&displayName={display_name}&volumeId={volume_id}"
uri = uri.format(
availability_domain="Pjwf%3A%20PHX-AD-1",
# Older ocid formats included ":" which must be escaped
compartment_
id="ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa".replace(":",
"%3A"),
display_name="TeamXInstances",

volume_
id="ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q".replace(":",
"%3A")
)
response = requests.get(uri, auth=auth, headers=headers)
print(uri)
print(response.request.headers["Authorization"])
# POST with body

uri = "https://iaas.us-ashburn-1.oraclecloud.com/20160918/volumeAttachments"
body = """{
"compartmentId":
}"""
response = requests.post(uri, auth=auth, headers=headers, data=body)
print("\n" + uri)
print(response.request.headers["Authorization"])
Ruby
require 'base64'
require 'digest'
require 'openssl'
require 'time'
require 'uri'
# gem 'httparty', '~> 0.13.0'

require 'httparty'
# Version 1.0.1
class Client
include HTTParty
attr_reader :signer
def initialize(key_id, private_key)

@signer = Signer.new(key_id, private_key)
end
# nothing to sign for :options

[:get, :head, :delete].each do |method|

define_method(method) do |uri, headers: {}|
self.signer.sign(method, uri, headers, body: nil)
self.class.send(method, uri, :headers => headers)
end
end
[:put, :post].each do |method|

define_method(method) do |uri, headers: {}, body: ""|
self.signer.sign(method, uri, headers, body)
self.class.send(method, uri, :headers => headers, :body => body)
end
end
end
class Signer
class << self
attr_reader :headers
end
attr_reader :key_id, :private_key
generic_headers = [:"date", :"(request-target)", :"host"]

body_headers = [
:"content-length", :"content-type", :"x-content-sha256"]
@headers = {
get: generic_headers,
head: generic_headers,
delete: generic_headers,
put: generic_headers + body_headers,
post: generic_headers + body_headers
}
def initialize(key_id, private_key)

@key_id = key_id
@private_key = private_key
end
def sign(method, uri, headers, body)

uri = URI(uri)

path = uri.query.nil? ? uri.path : "#{uri.path}?#{uri.query}"

self.inject_missing_headers(headers, method, body, uri)
signature = self.compute_signature(headers, method, path)
unless signature.nil?
self.inject_authorization_header(headers, method, signature)
end
end
def inject_missing_headers(headers, method, body, uri)

headers["content-type"] ||= "application/json"
headers["date"] ||= Time.now.utc.httpdate
headers["accept"] ||= "*/*"
headers["host"] ||= uri.host
if method == :put or method == :post
body ||= ""
headers["content-length"] ||= body.length.to_s
headers["x-content-sha256"] ||= Digest::SHA256.base64digest(body)
end
end
def inject_authorization_header(headers, method, signature)

signed_headers = self.class.headers[method].map(&:to_s).join(" ")
headers["authorization"] = [
%(Signature version="1"),
%(headers="#{signed_headers}"),
%(keyId="#{self.key_id}"),
%(algorithm="rsa-sha256"),
%(signature="#{signature}")
].join(",")
end
def compute_signature(headers, method, path)

return if self.class.headers[method].empty?
signing_string = self.class.headers[method].map do |header|
if header == :"(request-target)"
"#{header}: #{method.downcase} #{path}"
else
"#{header}: #{headers[header.to_s]}"
end
end.join("\n")
signature = self.private_key.sign(
OpenSSL::Digest::SHA256.new,

signing_string.encode("ascii"))
Base64.strict_encode64(signature)
end
end
api_key = [
"ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
"ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq",
"20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34"
].join("/")
private_key = OpenSSL::PKey::RSA.new(File.read("../sample-private-key"))
client = Client.new(api_key, private_key)
headers = {
# "date" => "Thu, 05 Jan 2014 21:31:40 GMT"
}

uri = "https://iaas.us-ashburn-1.oraclecloud.com/20160918/instances?availabilityDomain=%{availability_
domain}&compartmentId=%{compartment_id}&displayName=%{display_name}&volumeId=%{volume_id}"
uri = uri % {
:availability_domain => "Pjwf%3A%20PHX-AD-1",
# Older ocid formats included ":" which must be escaped
:compartment_id =>
"ocid1.compartment.oc1..aaaaaaaam3we6vgnherjq5q2idnccdflvjsnog7mlr6rtdb25gilchfeyjxa".sub(":", "%3A"),
:display_name => "TeamXInstances",
:volume_id =>
"ocid1.volume.oc1.phx.abyhqljrgvttnlx73nmrwfaux7kcvzfs3s66izvxf2h4lgvyndsdsnoiwr5q".sub(":", "%3A")
}
response = client.get(uri, headers: headers)
puts uri
puts response.request.options[:headers]["authorization"]
puts response.response
# POST with body

uri = "https://iaas.us-ashburn.oraclecloud.com/20160918/volumeAttachments"
body = %q({
"compartmentId":

})
response = client.post(uri, headers: headers, body: body)
puts "\n" + uri
puts response.request.options[:headers]["authorization"]
puts response.response

GLOSSARY
API key
A credential for securing requests to the Oracle Cloud Infrastructure REST API.
attach
Link a volume and instance together. Allows an instance to connect and mount the volume as a
hard drive.
availability domain
One or more isolated, fault-tolerant Oracle data centers that host cloud resources such as
instances, volumes, and subnets. A region contains several availability domains.
backend set
A logical entity defined by a list of backend servers, a load balancing policy, and a health check
policy.

Glossary
bare metal IaaS
A cloud infrastructure that allows you to utilize hosted physical hardware, as opposed to
traditional software-based virtual machines, ensuring a high level of security and performance.
block storage volume
A virtual disk that provides persistent storage space for instances in the cloud.
bucket
A logical container for storing objects.
CHAP
Stands for Challenge-Handshake-Authentication-Protocol. It is a security protocol used by iSCSI

for authentication between a volume and an instance.
Cloud Block Storage
A service that allows you to add block storage volumes to an instance in order to expand the
available storage on that resource.
cloud network
A virtual version of a traditional network—including CIDRs, subnets, route tables, and gateways—
on which your instance runs.
compartment
A collection of related resources that can be accessed only by certain groups that have been given
permission by an administrator in your organization.

Glossary
Compute
A service that lets you provision and manage compute hosts, known as instances.
connect
Make an attached volume usable by an instance's guest OS.
CPE
A virtual representation of the edge router at your end of an IPSec VPN that connects your VCN
and on-premises network.
cross-connect
Used with Oracle Cloud Infrastructure FastConnect. In a colocation scenario, this is the physical
cable connecting your existing network to Oracle in the FastConnect location.
cross-connect group
Used with Oracle Cloud Infrastructure FastConnect. In a colocation scenario, this is a link
aggregation group (LAG) that contains at least one cross-connect.
customer-premises equipment
A virtual representation of the edge router at your end of an IPSec VPN that connects your VCN
and on-premises network.
DB System
A dedicated bare metal instance running Oracle Linux, optimized for running one or more Oracle
databases. A DB System is a Database Service resource.

Glossary
DHCP options
Configuration information that is automatically provided to the instances when they boot up.
display name
A friendly name or description that helps you easily identify the resource.
DRG
An optional virtual router that you can add to your VCN to provide a path for private network
traffic between your VCN and on-premises network.
dynamic routing gateway
An optional virtual router that you can add to your VCN to provide a path for private network
traffic between your VCN and on-premises network.
ephemeral public IP
A public IP address (and related properties) that is temporary and exists for the life of the instance
it's assigned to. It can be assigned only to the primary private IP on a VNIC. Compare with
reserved public IP.
File System
An organized system of directories and folders where data is stored.

Glossary
group
A collection of users who all need a particular type of access to a set of resources or compartment.
guest operating system
An operating system installed on a cloud instance.
guest OS
An operating system installed on a cloud instance.
health check
A test to confirm the availability of backend servers.
IaaS
A service that allows customers to rapidly scale up or down their computer infrastructure
(computing, storage, or network).
IAM
The service for controlling authentication and authorization of users who need to use your cloud
resources. Also called "IAM".

Glossary
Identity and Access Management Service
The service for controlling authentication and authorization of users who need to use your cloud
resources. Also called "IAM".
identity provider
A service that provides identifying credentials and authentication for federated users.
IdP
Short for "identity provider", which is a service that provides identifying credentials and
authentication for federated users.
image
A template of a virtual hard drive that determines the operating system and other software for an
instance.
Infrastructure-as-a-Service
A service that allows customers to rapidly scale up or down their computer infrastructure
(computing, storage, or network).
instance
A Bare Metal Cloud compute host. The image used to launch the instance determines its operating
system and other software. The shape specified during the launch process determines the
number of CPUs and memory allocated to the instance.
internet gateway
An optional virtual router that you can add to your VCN. It provides a path for network traffic
between your VCN and the Internet.

Glossary
IPSec connection
The secure connection between a dynamic routing gateway (DRG) and customer-premises
equipment (CPE), consisting of multiple IPSec tunnels. The IPSec connection is one of the
components forming a site-to-site VPN between a virtual cloud network (VCN) and your on-
premises network.
IQN
A unique ID assigned to an iSCSI device. Used when connecting a volume to an instance.
iSCSI
A TCP/IP based standard used for communication between a volume and attached instance.
iSCSI Qualified Name
A unique ID assigned to an iSCSI device. Used when connecting a volume to an instance.
key pair
A security mechanism consisting of a public key and a private key. Required (for example) for
Secure Shell (SSH) access to an instance.
listener
An entity that checks for incoming traffic on the load balancer's public floating IP address.

Glossary
local peering gateway
A component on a VCN for routing traffic to a locally peered VCN. "Local" peering means the two
VCNs are in the same region. Compare with a remote peering connection.
local VCN peering
The process of connecting two VCNs in the same region so that their resources can communicate
without routing the traffic over the internet or through your on-premises network.
LPG
A component on a VCN for routing traffic to a locally peered VCN. "Local" peering means the two
VCNs are in the same region. Compare with a remote peering connection.
Mount Point
A directory from which a client may access a remote File Storage Service file system.
Mount Target
An NFS endpoint that allows a file system to be accessed by clients.
namespace
The logical entity that lets you own your personal bucket names. Bucket names need to be unique
within the context of a namespace, but bucket names can be repeated across namespaces.

Glossary
object
Any type of data, regardless of content type, is stored as an object. The object is composed of the
object itself and metadata about the object. Each object is stored in a bucket.
OCID
An Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). This ID is included as part
of the resource's information in both the Console and API.
one-time password
A single-use Console password that Oracle assigns to a new user, or to an existing user who
requested a password reset.
Oracle Cloud Identifier
An Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). This ID is included as part
of the resource's information in both the Console and API.
OTP
A single-use Console password that Oracle assigns to a new user, or to an existing user who
requested a password reset.
policy
A document in the IAM that specifies who has what type of access to your resources. It is used in
different ways: to mean an individual statement written in the policy language; to mean a
collection of statements in a single, named "policy" document (which has an Oracle Cloud ID

Glossary
(OCID) assigned to it); and to mean the overall body of policies your organization uses to control
access to resources.
policy statement
Policies can contain one or more individual statements. Each statement gives a group a certain
type of access to certain resources in a particular compartment.
primary IP
The private IP that is automatically created and assigned to a VNIC during creation.
primary VNIC
The VNIC that is automatically created and attached to an instance during launch.
private IP
An object that contains a private IP address and related properties such as a hostname for DNS.
Each instance automatically comes with a primary private IP, and you can add secondary ones.
private subnet
A subnet in which instances are not allowed to have public IP addresses
public IP
An object that contains a public IP address and related properties. You control whether each
private IP on an instance has an assigned public IP. There are two types: reserved public IPs and
ephemeral public IPs.
public subnet
A subnet in which instances are allowed to have public IP addresses. When you launch an
instance in a public subnet, you specify whether the instance should have a public IP address.

Glossary
region
A collection of availability domains located in a single geographic location.
remote peering connection
A component on a dynamic routing gateway (DRG) for routing traffic to a remotely peered VCN.
"Remote" peering means the two VCNs are in different regions. Compare with a local peering
gateway.
remote VCN peering
The process of connecting two VCNs in different regions so that their resources can communicate
without routing their traffic over the internet or through your on-premises network.
reserved public IP
A public IP address (and related properties) that you create in your tenancy and assign to your
instances in a given region as you like. It persists in your tenancy until you delete it. It can be
assigned to any private IP on a given VNIC, not just the primary private IP. Compare with
ephemeral private IP.
resource
The cloud objects that your company's employees create and use when interacting with Oracle
Cloud Infrastructure.
route table
Virtual route table for your VCN that provides mapping for the traffic from subnets via gateways to
external destinations.

Glossary
RPC
A component on a dynamic routing gateway (DRG) for routing traffic to a remotely peered VCN.
"Remote" peering means the two VCNs are in different regions. Compare with a local peering
gateway.
secondary IP address
An additional private IP you've added to a VNIC on an instance. Each VNIC automatically comes
with a primary private IP that cannot be removed.
secondary VNIC
An additional VNIC you've added to an instance. Each instance automatically comes with a
primary VNIC that cannot be removed.
security list
Virtual firewall rules for your VCN.
shape
A template that determines the number of CPUs and the amount of memory allocated to a newly
created instance.
statement
Policies can contain one or more individual statements. Each statement gives a group a certain
type of access to certain resources in a particular compartment.

Glossary
subnet
Subdivision of your VCN used to separate your network into multiple smaller, distinct networks.
Swift password
Swift is the OpenStack object store service. A Swift password enables you to use an existing Swift
client with Oracle Cloud Infrastructure Object Storage.
tenancy
The root compartment that contains all of your organization's compartments and other Oracle
Cloud Infrastructure cloud resources.
tenant
The name assigned to a particular company's or organization's overall environment. Users provide
their tenant when signing in to the Console.
user
An individual employee or system that needs to manage or use your company's Oracle Cloud
Infrastructure resources.
VCN

Glossary
virtual circuit
Used with Oracle Cloud Infrastructure FastConnect. An isolated network path that runs over one
or more physical network connections to provide a single, logical connection between the edge of
your existing network and Oracle Cloud Infrastructure.
virtual cloud network
virtual machine
A software-based emulation of a full computer that runs within a physical host computer.
virtual network interface card
A VNIC enables an instance to connect to a VCN and determines how the instance connects with
endpoints inside and outside the VCN. Each instance automatically comes with a primary VNIC,
and you can add secondary ones.
VM
A software-based emulation of a full computer that runs within a physical host computer.
VNIC
A VNIC enables an instance to connect to a VCN and determines how the instance connects with
endpoints inside and outside the VCN. Each instance automatically comes with a primary VNIC,
and you can add secondary ones.

Glossary
volume
A detachable block storage device that allows you to dynamically expand the storage capacity of
an instance.
work request
An object that reports on the current state of an asynchronous service request.

RELEASE NOTES
You can find the Oracle Cloud Infrastructure Release Notes online.

OCI User Guide PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OCI User Guide PDF

Uploaded by

Copyright:

Available Formats

User Guide

If this is software or related documentation that is delivered to the U.S. Government or

This software or hardware is developed for general use in a variety of information

CHAPTER 1 About Oracle Cloud Infrastructure 11

CHAPTER 2 Service Essentials 13

CHAPTER 3 Archive Storage 53

CHAPTER 5 Block Volume 73

Oracle Cloud Infrastructure User Guide 4

CHAPTER 6 Compute 130

Oracle Cloud Infrastructure User Guide 5

OS Kernel Updates 229

CHAPTER 7 Data Transfer 287

CHAPTER 8 Database 319

CHAPTER 9 DNS 675

CHAPTER 10 Email Delivery 690

Oracle Cloud Infrastructure User Guide 6

Managing Approved Senders 695

CHAPTER 11 File Storage 706

CHAPTER 12 IAM 753

Oracle Cloud Infrastructure User Guide 7

Managing Policies 997

CHAPTER 13 Load Balancing 1017

CHAPTER 14 Networking 1088

Oracle Cloud Infrastructure User Guide 8

Connectivity to the Internet 1234

CHAPTER 15 Object Storage 1493

CHAPTER 16 Developer Tools 1555

Oracle Cloud Infrastructure User Guide 9

Oracle Cloud Infrastructure User Guide 10

Service What's Covered Chapter

Archive Storage Preserving cold data. Archive Storage

Audit Logging activity in your cloud. Audit

Block Volume Adding storage capacity to instances. Block Volume

Compute Launching compute instances and Compute

Data Transfer Migrating large volumes of data. Data Transfer

Database Launching DB Systems and managing Database

DNS Creating and managing DNS zones. DNS

Email Delivery Sending large volume email. Email Delivery

File Storage Managing shared file systems, mount File Storage

Oracle Cloud Infrastructure User Guide 11

Service What's Covered Chapter

IAM Setting up administrators, users, and IAM

Load Balancing Setting up load balancers, listeners, Load Balancing

Networking Setting up cloud networks, subnets, Networking

Object Storage Creating and managing buckets to store Object Storage

Prefer Online Help?

Oracle Cloud Infrastructure User Guide 12

Regions and Availability Domains

Prerequisites for Oracle Platform Services on Oracle Cloud

Oracle Cloud Infrastructure User Guide 13

API Signing Key

Oracle Cloud Infrastructure User Guide 14

l Example: The PEM public key looks something like this:

-----END PUBLIC KEY——

Instance SSH Key

Oracle Cloud Infrastructure User Guide 15

Regions and Availability Domains

Region Location Region Name Region Key

Phoenix, AZ metropolitan area us-phoenix-1 PHX

Ashburn, VA us-ashburn-1 IAD

Frankfurt, Germany eu-frankfurt-1 FRA

London, United Kingdom uk-london-1 LHR

To subscribe to a region, see Managing Regions.