Download Oracle Bare Metal Cloud User Guide

User Guide 6/15/2017 Copyright © 2016, 2017, 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 Bare Metal Cloud Services Prefer Online Help? Need API Documentation? CHAPTER 2 Service Essentials Security Credentials Regions and Availability Domains Resource Identifiers Service Limits CHAPTER 3 Audit Service Overview of the Audit Service Contents of an Audit Log Event Viewing Audit Log Events CHAPTER 4 Block Volume Service Overview of Block Volume Service iSCSI Commands and Information Creating a Volume Attaching a Volume Connecting to a Volume Listing Volumes Listing Volume Attachments Renaming a Volume Overview of Block Volume Service Backups Backing Up a Volume Oracle Bare Metal Cloud Services User Guide 7 8 8 9 9 11 13 15 24 24 25 32 36 36 38 39 41 42 45 46 47 48 50 3 Table of Contents Restoring a Backup to a New Volume Disconnecting From a Volume Detaching a Volume Deleting a Volume CHAPTER 5 Compute Service Overview of the Compute Service Best Practices for Your Compute Instance Protecting Data on NVMe Devices Oracle-Provided Images Managing Custom Images Bring Your Own Image OS Kernel Updates Managing Key Pairs on Linux Instances Launching an Instance Connecting to an Instance Adding Users on an Instance Displaying the Console for an Instance Getting Instance Metadata Renaming an Instance Stopping and Starting an Instance Terminating an Instance 51 52 53 54 56 56 60 62 75 78 84 104 107 112 119 122 124 125 128 128 130 CHAPTER 6 Database Service 132 Overview of the Database Service Exadata DB Systems Bare Metal DB Systems Migrating Databases to the Cloud 132 133 185 359 CHAPTER 7 IAM Service 406 Overview of the IAM Service Getting Started with Policies How Policies Work Common Policies Advanced Policy Features Policy Syntax Policy Reference 406 420 422 430 437 442 446 Oracle Bare Metal Cloud Services User Guide 4 Table of Contents User Credentials Identity Providers and Federation Managing Users Managing Groups Managing Compartments 509 511 523 528 532 Managing Regions Managing Policies Managing User Credentials 534 538 542 CHAPTER 8 Load Balancing Service Overview of the Load Balancing Service How Load Balancing Policies Work Session Persistence Managing a Load Balancer Managing Backend Sets Managing Backend Servers Managing Load Balancer Listeners Managing SSL Certificates Editing Health Check Policies Viewing the State of a Work Request CHAPTER 9 Networking Service Overview of the Networking Service Access and Security DNS in Your Virtual Cloud Network FastConnect Overview MTU and Jumbo Frames Scenario A - Public Subnets Scenario B - Private Subnets with a VPN Scenario C - Public and Private Subnets with a VPN Managing Virtual Cloud Networks (VCNs) Managing Route Tables Managing Security Lists Managing DHCP Options Managing Subnets Managing Internet Gateways Managing Dynamic Routing Gateways (DRGs) Oracle Bare Metal Cloud Services User Guide 548 548 557 559 560 565 569 572 574 577 579 581 581 591 602 607 644 645 649 658 670 673 676 682 687 691 694 5 Table of Contents Managing IPSec VPNs Configuring Your On-Premises Router for an IPSec VPN 698 708 CHAPTER 10 Object Storage Service 792 Overview of the Object Storage Service Managing Buckets 792 796 Managing Objects Managing Multipart Uploads Hadoop Support 800 803 807 CHAPTER 11 Using the API 808 SDKs and Other Tools SDK and Tool Configuration Required Keys and OCIDs About the API Request Signatures API Errors API Reference 808 842 845 848 853 894 896 GLOSSARY 897 RELEASE NOTES 908 Oracle Bare Metal Cloud Services User Guide 6 CHAPTER 1 About Oracle Bare Metal Cloud Services Oracle Bare Metal Cloud Services provides bare metal cloud infrastructure that lets you create networking, compute, and storage resources for your enterprise workloads. If you're new to Oracle Bare Metal Cloud Services and would like to learn some key concepts and take a quick tutorial, see the Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services: Service What's Covered Chapter Audit Service Logging activity in your cloud. Audit Service Block Volume Service Adding storage capacity to instances. Block Volume Service Compute Service Launching compute instances and connecting to them by using an SSH key pair. Compute Service Database Service Launching DB Systems and managing Oracle databases. Database Service IAM Service Setting up administrators, users, and groups and specifying their permissions to access to cloud resources. IAM Service Load Balancing Service Setting up load balancers, listeners, backend sets, certificate bundles, and managing health check policies. Load Balancing Service Networking Service Setting up cloud networks, subnets, gateways, route tables, and security lists. Networking Service Object Storage Service Creating and managing buckets to store objects, and uploading and accessing data files. Object Storage Service For a description of the terminology used throughout this guide, see the GLOSSARY. Oracle Bare Metal Cloud Services User Guide 7 CHAPTER 1 About Oracle Bare Metal Cloud Services Prefer Online Help? The information in this guide and the Getting Started Guide is also available in the online help at https://docs.usphoenix-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. Oracle Bare Metal Cloud Services User Guide 8 CHAPTER 2 Service Essentials The following topics provide essential information that applies across Oracle Bare Metal Cloud Services. Security Credentials The types of credentials you'll use when working with Oracle Bare Metal Cloud Services. Regions and Availability Domains An introduction to the concepts of regions and Availability Domains. Resource Identifiers A description of the different ways your Oracle Bare Metal Cloud Services resources are identified. Service Limits A list of the default limits applied to your cloud resources and the procedure you can use to request an increase. Security Credentials This section describes the types of credentials you'll use when working with Oracle Bare Metal Cloud Services. 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 Oracle Bare Metal Cloud Services User Guide 9 CHAPTER 2 Service Essentials 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 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 (e.g., your instance SSH key, or a key that isn't at least 2048 bits), you'll get an InvalidKey error. Example: The PEM public key looks something like this: -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF... ... -----END PUBLIC KEY—— Instance SSH Key l l What it's for: Accessing a compute instance. 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... ... [email protected] Oracle Bare Metal Cloud Services User Guide 10 CHAPTER 2 Service Essentials Swift Password l What it's for: Using a Swift client to access Object Storage Service 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 Bare Metal Cloud Services Console login, your Swift password provided by Oracle, and your organization's Oracle tenant name. Regions and Availability Domains Oracle Bare Metal Cloud Services 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 bare metal 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 To subscribe to another region, see Managing Regions. Oracle Bare Metal Cloud Services User Guide 11 CHAPTER 2 Service Essentials Note: The names of the Availability Domains have a prefix that is specific to your tenancy. To get a list of the Availability Domains, use the ListAvailabilityDomains operation, which is available in the IAM Service API. Resource Locations The following table shows the scope of each type of resource: available globally across regions, throughout a single region, or within a single Availability Domain. Resource Location API signing keys Global Buckets Region Compartments Global CustomerPremises Equipment (CPE) Region DB Systems Availability Domain DHCP options Region Dynamic Routing Gateways (DRGs) Region Groups Global Images Region Instances Availability Domain Oracle Bare Metal Cloud Services User Guide Notes Although a bucket is a regional resource, it can be accessed from any location as long as you use the correct regionspecific Object Storage URL for the API calls. Instances can be attached only to volumes in the same Availability Domain. 12 CHAPTER 2 Service Essentials Resource Location Notes Internet Gateways Region Load Balancers Region Policies Global Route tables Region Security lists Region Subnets Availability Domain Users Global Virtual Cloud Networks (VCNs) Region Volumes Availability Domain Volumes can be attached only to an instance in the same Availability Domain. Volume backups Region Volume backups can be restored as new volumes to any Availability Domain within the same region they are stored. Resource Identifiers This chapter describes the different ways your Oracle Bare Metal Cloud Services resources are identified. Oracle Cloud IDs (OCIDs) Every Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 13 CHAPTER 2 Service Essentials 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 (e.g., instance, volume, vcn, subnet, user, group, etc.). l l l l realm: The realm the resource is in. A realm is a set of regions that share entities. The only possible value is oc1. region: The key of the region the resource is in (e.g., phx or iad). 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). future use: Reserved for future use; currently blank. unique ID: The unique portion of the ID. The format may vary depending on the type of resource or service. Example OCIDs l l tenancy: ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq instance: ocid1.instance.oc1.phx.abuw4ljrlsfiqw6vzzxb43vyypt4pkodawglp3wqxjqofakrwvou52gb6s 5a Where to Find Your Tenancy's OCID If you use the Oracle Bare Metal Cloud Services 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 Service API operations. Oracle Bare Metal Cloud Services User Guide 14 CHAPTER 2 Service Essentials 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 Service Only) The IAM Service requires you to assign a unique, unchangeable name to each of your IAM Service resources (users, groups, policies, and compartments). The name must be unique within the scope of the type of resource (e.g., you can only have one user with the name BobSmith). Notice that this requirement is specific to the IAM Service 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 (e.g., 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 Service 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 Bare Metal Cloud Services resources you create (other than those in the IAM Service), 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. Service Limits This topic describes the service limits for Oracle Bare Metal Cloud Services and the process for requesting a service limit increase. About Service Limits When you sign up for Oracle Bare Metal Cloud Services, 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 Oracle Bare Metal Cloud Services User Guide 15 CHAPTER 2 Service Essentials number of compute instances per Availability Domain. These limits are generally established with your Oracle sales representative when you purchase Oracle Bare Metal Cloud Services. 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. What Happens When I Reach a Service Limit? When you reach the service limit for a resource, you will 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 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: Request limit increase 5. Enter your contact information. Oracle Bare Metal Cloud Services User Guide 16 CHAPTER 2 Service Essentials 6. 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 l 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. Requested limit increase. For example: Increase the service limit to 10 volumes. 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.). Oracle Bare Metal Cloud Services User Guide 17 CHAPTER 2 Service Essentials Block Volume Service Limits Limits apply to each Availability Domain. There are three Availability Domains per region. Resource Pre-Paid Pay-As-You-Go Block Volumes aggregated size 1024 GiB 3072 GiB Backups 100 20 Compute Service Limits Limits apply to each Availability Domain, unless otherwise noted. There are three Availability Domains per region. Bare Metal Servers Resource Pre-Paid Pay-As-You-Go BM.Standard1.36 2 (72 cores) 1 (36 cores) BM.HighIO1.36 2 (72 cores) Contact Us BM.DenseIO1.36 2 (72 cores) Contact Us Custom Images 100 per region 25 per region Virtual Machines Resource Pre-Paid Pay-As-You-Go VM.Standard1.1 5 1 VM.Standard1.2 5 1 VM.Standard1.4 5 1 VM.Standard1.8 4 1 Oracle Bare Metal Cloud Services User Guide 18 CHAPTER 2 Service Essentials Resource Pre-Paid Pay-As-You-Go VM.Standard1.16 2 1 VM.DenseIO1.4 2 1 VMDenseIO1.8 2 Contact Us VMDenseIO1.16 2 Contact Us Database Service Limits Database Service limits are per Availability Domain. There are three Availability Domains per region. Resources Pre-Paid Pay-As-You-Go BM.HighIO1.36 1 instance Contact Us BM.DenseIO1.36 1 instance 1 instance BM.RACLocalStorage1.72 Contact Us Contact Us Exadata.Quarter1.84 Contact Us Contact Us Exadata.Half1.168 Contact Us Contact Us Exadata.Full1.336 Contact Us Contact Us IAM Service Limits IAM Service limits are global. Resource Pre-Paid Pay-As-You-Go Users in a tenancy 100 100 Groups in a tenancy 50 50 Oracle Bare Metal Cloud Services User Guide 19 CHAPTER 2 Service Essentials Resource Pre-Paid Pay-As-You-Go 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 provider 50 50 Load Balancing Service Limits Load Balancing Service limits are regional. Resource Pre-Paid Pay-As-You-Go 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 Oracle Bare Metal Cloud Services User Guide 20 CHAPTER 2 Service Essentials Networking Service Limits Networking Service service limits apply to different scopes, depending on the resource. VCN and Subnet Limits Resource Scope Pre-Paid Pay-As-YouGo VCN Tenant 10 10 Subnets VCN 300 300 Resource Scope Pre-Paid Pay-As-YouGo Internet Gateway VCN 1 1 Dynamic Routing Gateway (DRG) Tenant 2 Contact Us Resource Scope Pre-Paid Pay-As-YouGo Route Tables VCN 300 300 Route Rules Route Table 10 10 Gateway Limits Route Table Limits Oracle Bare Metal Cloud Services User Guide 21 CHAPTER 2 Service Essentials Security List Limits Resource Scope Pre-Paid Pay-As-YouGo Security Lists VCN 300 300 Security Lists Subnet 5 5 Inbound or outbound rules Security List 50 ingress rules 50 ingress rules 50 egress rules 50 egress rules IPSec VPN Connection Limits Resource Scope Pre-Paid Pay-As-YouGo IPSec VPN Connection Tenant 2 Contact Us Customer-Premises Equipment Tenant 2 Contact Us Resource Scope Pre-Paid Pay-As-YouGo DHCP Option VCN 300 300 DHCP Option Limits Oracle Bare Metal Cloud Services User Guide 22 CHAPTER 2 Service Essentials Object Storage Service Limits Object Storage Service limits are regional. Resource Pre-Paid Pay-As-You-Go 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 Oracle Bare Metal Cloud Services User Guide 23 CHAPTER 3 Audit Service This chapter explains how to work with audit logs. Overview of the Audit Service The Oracle Bare Metal Cloud Audit Service automatically records calls to all supported Oracle Bare Metal Cloud Services public application programming interface (API) endpoints as log events. Currently, all services support logging by the Audit Service except the Object Storage Service. Log events recorded by the Audit Service include API calls made by the Oracle Bare Metal Cloud Services Console, Command Line Interface (CLI), Software Development Kits (SDK), your own custom clients, or other Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.us-phoenix-1.oraclecloud.com.When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. For general information about using the API, see About the API. Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API). Oracle Bare Metal Cloud Services User Guide 24 CHAPTER 3 Audit Service 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 Bare Metal Cloud Services 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. 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. eventTime The time the event occurred, expressed in RFC 3339 timestamp format. eventType The type of the event. (Currently, the Audit Service 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. Oracle Bare Metal Cloud Services User Guide 25 CHAPTER 3 Audit Service Property Description 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. 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. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 26 CHAPTER 3 Audit Service [ { "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": [ "443" ], "X-Forwarded-For": [ "192.0.2.0" ], "Opc-Request-Id": [ "0e1e3938-681a-4195-cvb7-35c84311f2ad" ], "X-Forwarded-Proto": [ "https" ], "Accept": [ Oracle Bare Metal Cloud Services User Guide 27 CHAPTER 3 Audit Service "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/" ], "Host": [ "iaas.us-phoenix-1.oraclecloud.com" ] }, "compartmentId": "ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca", "requestId": "0e1e3938-681a-4195-cvb735c84311/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": [ "https://console.us-phoenix-1.oraclecloud.com" ], "Access-Control-Allow-Credentials": [ "true" ], "Content-Encoding": [ "gzip" ], "Vary": [ "Accept-Encoding" ], Oracle Bare Metal Cloud Services User Guide 28 CHAPTER 3 Audit Service "opc-request-id": [ "0e1e3938-681a-4195-cvb735c84311/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": [ "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" ], Oracle Bare Metal Cloud Services User Guide 29 CHAPTER 3 Audit Service "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-cvb7be74f6d4/77C6104EA72B47BFB39ED6D88AFFB067/0A4B35F3E09C474A96C3EB4C0DCD6BF1", "eventSource": "CoreServicesPublicApi", "responseStatus": "200", "requestParameters": { "compartmentId": [ "ocid1.compartment.oc1..aaaaaaaacvb24qzjpmwdmt33f3zz5kdh2jpvzm52n5spet3nndh3diys7pca" ] Oracle Bare Metal Cloud Services User Guide 30 CHAPTER 3 Audit Service }, "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": [ "https://console.us-phoenix-1.oraclecloud.com" ], "Access-Control-Allow-Credentials": [ "true" ], "Content-Encoding": [ "gzip" ], "Vary": [ "Accept-Encoding" ], "opc-request-id": [ "34b5ac1a-e9ee-4c8c-cvb7be74f6d4/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/" } ] Oracle Bare Metal Cloud Services User Guide 31 CHAPTER 3 Audit Service Viewing Audit Log Events The Audit Service 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 and maintains logs for up to 90 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 Service, 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The following policy statement gives the specified group the ability to view all the Audit Service event logs in the tenancy: Allow group Auditors to read audit-events in tenancy If you're new to policies, see Getting Started with Policies and Common Policies. For more details about policies for the Audit Service, 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 Service highlights which key-value pairs are shared across events displayed on the same page. The list of common keyvalue 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: Oracle Bare Metal Cloud Services User Guide 32 CHAPTER 3 Audit Service 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 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. Oracle Bare Metal Cloud Services User Guide 33 CHAPTER 3 Audit Service 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. 6. Repeat steps 2 through 4 for the second box to choose an end date and time. Note: You cannot view results older than 90 days in the past. 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. Oracle Bare Metal Cloud Services User Guide 34 CHAPTER 3 Audit Service 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 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 Service 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. 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. Use the following operation to manage log events: l ListEvents Oracle Bare Metal Cloud Services User Guide 35 CHAPTER 4 Block Volume Service This chapter explains how to create storage volumes and attach them to instances. Overview of Block Volume Service The Oracle Bare Metal Cloud 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. Block Volume Service Components The components required to create a volume and attach it to an instance are briefly described below. l l l Instance: A bare metal compute host running in the cloud. iSCSI: A TCP/IP-based standard used for communication between a volume and attached instance. See iSCSI Commands and Information for more information. Volume: A detachable block storage device that allows you to dynamically expand the storage capacity of an instance. For additional Oracle Bare Metal Cloud Services terms, see the Glossary. Typical Block Volume Service Scenarios Scenario A: Expand an Instance's Storage A common usage of Block Volume Service is adding storage capacity to an Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 36 CHAPTER 4 Block Volume Service Scenario B: Persistent and Durable Storage A Block Volume Service 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 Service 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. Regions and Availability Domains 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. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access the Block Volume Service You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. Oracle Bare Metal Cloud Services User Guide 37 CHAPTER 4 Block Volume Service For general information about using the API, see About the API. Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service 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 Bare Metal Cloud Services 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. Block Volume Service Capabilities and Limits Block Volume Service volumes can be created in sizes ranging from 50 GB to 2 TB in 1 GB increments. By default, Block Volume Service volumes are 1 TB. See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Additional limits include: l Volumes per instance: 32 l Number of backups: 20 per root compartment iSCSI Commands and Information You use the iSCSI protocol to connect a Block Volume Service volume to an instance. Once the volume is attached, you 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. Oracle Bare Metal Cloud Services User Guide 38 CHAPTER 4 Block Volume Service Accessing a Volume's iSCSI Information When you successfully attach a volume to an instance, the Block Volume Service 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 - About iSCSI Storage l Troubleshooting iSCSI Configuration Problems l iscsiadm Basics Creating a Volume You can create a volume using the Block Volume Service. Oracle Bare Metal Cloud Services User Guide 39 CHAPTER 4 Block Volume Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Volume Admins Manage Block Volumes and Backups lets the specified group do everything with block volumes and backups. 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 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 2 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. 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 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. Oracle Bare Metal Cloud Services User Guide 40 CHAPTER 4 Block Volume Service Attaching a Volume You can attach a volume to an instance in order to expand the available storage on the instance. Once attached, you must still connect and mount the volume from the instance for the volume to be usable. For more information, see Connecting to a Volume. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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. 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 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. Click Attach Volume and select the volume you want from the Volume drop-down menu. 5. Click Attach. You can connect to the volume once the volume's icon no longer lists it as Attaching. For more information, see Connecting to a Volume. Using the API To attach a volume to an instance, use the following operation: l AttachVolume Oracle Bare Metal Cloud Services User Guide 41 CHAPTER 4 Block Volume Service 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. Connecting to a Volume You can connect a volume to an instance's guest OS. In order to connect the volume, you must first attach the volume to the instance. For additional information, see Attaching a Volume. Important Note About Connecting with iSCSI on Linux Instances Block volumes on Oracle Bare Metal Cloud Services use iSCSI to connect to instances. On Linux instances, it’s important to include the _ netdev and nofail options on every non-root block volume in /etc/fstab or the instance may fail to launch as the OS tries to mount the volume(s) before the iSCSI initiator has started. For example, a single volume in /etc/fstab might look like this: /dev/sdb 0 /data1 2 /dev/sdb 0 /data1 ext4 ext4 defaults,noatime,_netdev defaults,noatime,_netdev,nofail 2 If you reboot without these options in fstab, the instance will fail to start after the next reboot. Instances in this state are not recoverable. Required IAM Service Policy Connecting a volume to an instance does not require a specific IAM Service 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: Oracle Bare Metal Cloud Services User Guide 42 CHAPTER 4 Block Volume Service 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 Bare Metal Cloud Services. b. Click Compute, and then click Instances to find your instance. c. Click your instance's name to view the attached storage volume. d. 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:c6acda7390b4-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: Oracle Bare Metal Cloud Services User Guide 43 CHAPTER 4 Block Volume Service 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 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: Oracle Bare Metal Cloud Services User Guide 44 CHAPTER 4 Block Volume Service a. Log on to Oracle Bare Metal Cloud Services. b. Click Compute, and then click Instances to find your instance. c. Click your instance's name to view the attached storage volume. d. 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 256 GB disk is displayed in the list. Listing Volumes You can list all Block Volume Service volumes in a specific compartment, as well as detailed information on a single volume. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. Oracle Bare Metal Cloud Services User Guide 45 CHAPTER 4 Block Volume Service For administrators: The policy in Let Users Launch Instances includes the ability to list 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. 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 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 dropdown menu. 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. 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 Volume Attachments You can use the API to list all Block Volume Service volume attachments in a specific compartment, as well as detailed information on a single volume attachment. Oracle Bare Metal Cloud Services User Guide 46 CHAPTER 4 Block Volume Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 specified group do everything with block 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 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. 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 Renaming a Volume You can use the API to change the display name of a Block Volume Service volume. Oracle Bare Metal Cloud Services User Guide 47 CHAPTER 4 Block Volume Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 specified group do everything with block 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 API To update a volume's display name, use the following operation: l UpdateVolume 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. Overview of Block Volume Service Backups The backups feature of the Oracle Bare Metal Cloud Block Volume Service lets you take point-in-time, complete images of all of the data on a block volume. These images 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 the Oracle Bare Metal Cloud Object Storage Service, 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. 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: Oracle Bare Metal Cloud Services User Guide 48 CHAPTER 4 Block Volume Service l l l Frequency: How often you want to back up your data. 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. 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 Service 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 l 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. 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. 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. Oracle Bare Metal Cloud Services User Guide 49 CHAPTER 4 Block Volume Service Backing Up a Volume You can create a backup of a volume using the Block Volume Service. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Volume Admins Manage Block Volumes and Backups lets 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. 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. 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 1. In the Console, click Storage. 2. Click Backups. 3. Click the block volume for which you want to create a backup. 4. Click Create Backup. 5. Enter a name for the backup, and then 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: Oracle Bare Metal Cloud Services User Guide 50 CHAPTER 4 Block Volume Service l CreateVolumeBackup 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. For more information about backups, see Overview of Block Volume Service 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 the Block Volume Service. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Volume Admins Manage Block Volumes and Backups lets the specified group do everything with block volumes and backups. 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. 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 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. Oracle Bare Metal Cloud Services User Guide 51 CHAPTER 4 Block Volume Service 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. 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 information about using the API and signing requests, see About the API and Security Credentials. For information about SDKs, see SDKs and Other Tools. For more information about backups, see Overview of Block Volume Service Backups and Backing Up a Volume. Disconnecting From a Volume You can disconnect a Block Volume Service volume from an instance when it is no longer needed. Required IAM Service Policy Disconnecting a volume from an instance does not require a specific IAM Service policy. Don't confuse this with detaching a volume (see Detaching a Volume). Disconnecting from a Volume on a Linux Instance Oracle recommends that you unmount and disconnect the volume from Oracle Bare Metal Cloud Services User Guide 52 CHAPTER 4 Block Volume Service 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. Oracle Bare Metal Cloud Services User Guide 53 CHAPTER 4 Block Volume Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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. 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 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. 1. In the Console, click Compute. 2. In the Instance list and locate the instance. Click its name to display the instance details. 3. 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 request: l DetachVolume 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. Deleting a Volume You can delete a volume that is no longer needed. Oracle Bare Metal Cloud Services User Guide 54 CHAPTER 4 Block Volume Service You cannot undo this operation. Any data on a volume will be permanently deleted once the volume is deleted. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Volume Admins Manage Block Volumes and Backups lets the specified group do everything with block volumes and backups. 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 1. In the Console, click Storage. 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 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. Oracle Bare Metal Cloud Services User Guide 55 CHAPTER 5 Compute Service This chapter explains how to launch, access, rename, and terminate compute instances. Overview of the Compute Service The Oracle Bare Metal Cloud Compute Service 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 Bare Metal Cloud Services offers both Bare Metal and Virtual Machine instances: l l Bare Metal - A bare metal compute instance gives you dedicated physical server access for highest performance and strong isolation. 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 Bare Metal Cloud Services 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 Bare Metal Cloud Compute Service instance. Components for Launching Instances The components required to launch an instance are: Availability Domain The Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 56 CHAPTER 5 Compute Service 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 the Networking Service. 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. 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 Bare Metal Cloud Services 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. 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 Type OCPU Memory (GB) Local Disk (TB) BM.Standard1.36 Standard compute capacity 36 256 Block storage only BM.HighIO1.36 High I/O compute capacity 36 512 12.8TB NVMe SSD BM.DenseIO1.36 Dense I/O compute capacity 36 512 28.8TB NVMe SSD VM Shapes VMs are an option that provides flexibility in compute power, memory capability, and network resources for lighter applications. You can use the Block Volume Service to add network-attached block storage as needed. Oracle Bare Metal Cloud Services User Guide 57 CHAPTER 5 Compute Service Shape Instance Type OCPU Memory (GB) Local Disk (TB) VM.Standard1.1 Standard 1 7 Block Storage only VM.Standard1.2 Standard 2 14 Block Storage only VM.Standard1.4 Standard 4 28 Block Storage only VM.Standard1.8 Standard 8 56 Block Storage only VM.Standard1.16 Standard 16 112 Block Storage only VM.DenseIO1.4 Standard 4 60 3.2 TB NVMe SSD VM.DenseIO1.8 Standard 8 120 6.4 TB NVMe SSD VM.DenseIO1.16 Standard 16 240 12.8 TB NVMe SSD You can optionally attach volumes to an instance. For more information, see Overview of Block Volume Service. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access Oracle Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. For general information about using the API, see About the API. Oracle Bare Metal Cloud Services User Guide 58 CHAPTER 5 Compute Service Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service 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 Bare Metal Cloud Services 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. Limits on Compute Service Resources See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Additional limits include: l l To attach a volume to an instance, both the instance and volume must be within the same Availability Domain. 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. 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 Oracle Bare Metal Cloud Services User Guide 59 CHAPTER 5 Compute Service 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 The Oracle Bare Metal Cloud Compute Service 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. Reserved IP Addresses The following IP addresses are reserved for Oracle Bare Metal Cloud Services 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). Three IP addresses in each subnet The first two IP addresses and the last one in each subnet's CIDR are reserved. Oracle Bare Metal Cloud Services User Guide 60 CHAPTER 5 Compute Service Essential Firewall Rules All Oracle-provided images include rules that allow only "root" on Linux instances or "Administrators" on Windows 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 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. Oracle recommends that you do not create custom images without these rules unless you understand the security risks. System Resilience Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 61 CHAPTER 5 Compute Service 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. 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. Protecting Data on NVMe Devices Some instance shapes in Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services offers high-performance remote block (iSCSI) LUNs that are redundant and can be backed up using an API call. See Overview of Block Volume Service for more information. The following instance types support local NVMe storage: Instance Supported NVMe Devices BM.HighIO1.512 4 - 3.2TB NVMe devices (12.8TB raw) BM.DenseIO1.512 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.512 instance: [opc@somehost ~]$ lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT Oracle Bare Metal Cloud Services User Guide 62 CHAPTER 5 Compute Service sda 8:0 0 46.6G 0 disk ├─sda1 8:1 0 512M 0 part /boot/efi ├─sda2 8:2 0 8G └─sda3 8:3 0 38G 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 0 part [SWAP] 0 part / [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: 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: Oracle Bare Metal Cloud Services User Guide 63 CHAPTER 5 Compute Service 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: Oracle Bare Metal Cloud Services User Guide 64 CHAPTER 5 Compute Service l RAID 6: Block-level striping with two parity blocks distributed across all member disks, as shown. Oracle Bare Metal Cloud Services User Guide 65 CHAPTER 5 Compute Service 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.512 Shape There are three recommended options for BM.HighIO1.512 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, 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 Oracle Bare Metal Cloud Services User Guide 66 CHAPTER 5 Compute Service $ 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 yum install mdadm -y $ 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 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null 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: $ sudo yum install mdadm -y $ sudo mdadm --create /dev/md0 --raid-devices=4 --level=6 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /dev/nvme3n1 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null Options for Using a BM.DenseIO1.512 Shape There are several options for BM.DenseIO1.512 instances with nine NVMe devices: 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: $ sudo yum install mdadm -y $ sudo mdadm --create /dev/md0 --raid-devices=9 --level=6 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /dev/nvme3n1 /dev/nvme4n1 /dev/nvme5n1 /dev/nvme6n1 /dev/nvme7n1 /dev/nvme8n1 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null Oracle Bare Metal Cloud Services User Guide 67 CHAPTER 5 Compute Service 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: $ sudo yum install mdadm -y $ sudo mdadm --create /dev/md0 --raid-devices=4 --level=10 /dev/nvme5n1 /dev/nvme6n1 /dev/nvme7n1 /dev/nvme8n1 $ sudo mdadm --create /dev/md1 --raid-devices=5 --level=6 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /dev/nvme3n1 /dev/nvme4n1 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null 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: $ sudo yum install mdadm -y $ sudo mdadm --create /dev/md0 --raid-devices=8 --level=10 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /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 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null 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: $ sudo yum install mdadm -y $ sudo mdadm --create /dev/md0 --raid-devices=4 --level=10 /dev/nvme4n1 /dev/nvme5n1 /dev/nvme6n1 /dev/nvme7n1 Oracle Bare Metal Cloud Services User Guide 68 CHAPTER 5 Compute Service $ sudo mdadm --create /dev/md1 --raid-devices=4 --level=10 /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /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: $ sudo mdadm /dev/md0 --add /dev/nvme8n1 $ sudo mdadm --detail --scan | sudo tee -a /etc/mdadm.conf >> /dev/null 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: 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 Set 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: $ sudo vi /etc/mdadm.conf DEVICE partitions ARRAY /dev/md0 level=raid1 UUID=1b70e34a:2930b5a6:016we78d:eese14532 MAILADDR <[email protected]> Oracle Bare Metal Cloud Services User Guide 69 CHAPTER 5 Compute Service 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 solution. The following is an example of this type of script: Oracle Bare Metal Cloud Services User Guide 70 CHAPTER 5 Compute Service $ 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: $ sudo vi /etc/mdadm.conf DEVICE partitions ARRAY /dev/md0 level=raid1 UUID=1b70e34a:2930b5a6:016we78d:eese14532 MAILADDR <[email protected]> PROGRAM /etc/mdadm.events 2. Run the monitor using the following command: Oracle Bare Metal Cloud Services User Guide 71 CHAPTER 5 Compute Service $ 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. Simulate 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: $ sudo mdadm /dev/md0 --add /dev/nvme0n1 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. 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. Oracle Bare Metal Cloud Services User Guide 72 CHAPTER 5 Compute Service 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 Bare Metal Cloud Services 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. Backups Traditional backups are another way to protect data. All commercial backup products are fully supported on Oracle Bare Metal Cloud Services. 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. Oracle Bare Metal Cloud Services User Guide 73 CHAPTER 5 Compute Service Snapshots 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 Bare Metal Cloud Services. Make sure that your backups are not stored in the same Availability Domain as their original instance. Oracle Bare Metal Cloud Services User Guide 74 CHAPTER 5 Compute Service 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 images are available in Oracle Bare Metal Cloud Services: Image Name Description Oracle Linux 7 Unbreakable Enterprise Kernel Release 4 Oracle-Linux-7.x<date>-<number> The Unbreakable Enterprise Kernel (UEK) is Oracle's optimized operating system kernel for demanding Oracle workloads. Oracle Linux 6 Unbreakable Enterprise Kernel Release 4 Oracle-Linux-6.x<date>-<number> The Unbreakable Enterprise Kernel (UEK) is Oracle's optimized operating system kernel for demanding Oracle workloads. CentOS 7 CentOS-7-<date><number> CentOS is a free, open-source Linux distribution suitable for use in enterprise cloud environments. For more information, see https://www.centos.org/. CentOS 6 CentOS-6.x-<date><number> CentOS is a free, open-source Linux distribution that is suitable for use in enterprise cloud environments. For more information, see https://www.centos.org/. Ubuntu 16.04 LTS Canonical-Ubuntu-16.x<date>-<number> Ubuntu is a free, open-source Linux distribution that is suitable for use in the cloud. For more information, see https://www.ubuntu.com. Windows Server 2012 R2 – Bare Metal (BM) Windows-Server-2012R2-Standard-EditionBM-<date>-<number> Windows Server 2012 R2 Standard Edition supports running production Windows workloads on Oracle Bare Metal Cloud Services. Windows Server 2012 R2 - Virtual Machine (VM) Windows-Server-2012R2-Standard-EditionVM-<date>-<number> Windows Server 2012 R2 Standard Edition supports running production Windows workloads on Oracle Bare Metal Cloud Services. You also can create custom images of your boot disk OS and software configuration for launching new instances. Oracle Bare Metal Cloud Services User Guide 75 CHAPTER 5 Compute Service All Oracle-provided images include rules that allow only "root" on Linux instances or "Administrators" on Windows 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 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. 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. 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. 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. Oracle Bare Metal Cloud Services User Guide 76 CHAPTER 5 Compute Service 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 restrict link local traffic to address 169.254.0.2 in accordance with the warning at the top of this page. Be aware that the Networking Service 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. Oracle Bare Metal Cloud Services User Guide 77 CHAPTER 5 Compute Service 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 Bare Metal Cloud Services 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. 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 the Networking Service 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. Managing Custom Images Oracle Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 78 CHAPTER 5 Compute Service Custom images do not include the data from any attached block volumes. For information about backing up volumes, see Backing Up a Volume. Oracle Bare Metal Cloud Services 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 l l Design your system with redundant compute nodes in different Availability Domains to support fail-over capability. Create a custom image of your system drive each time you change the image. 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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, you could simplify that policy to include only manage instance-family, and remove the statements involving volume-family and virtualnetwork-family. 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. 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. Oracle Bare Metal Cloud Services User Guide 79 CHAPTER 5 Compute Service Limitations and Considerations l The following IP addresses are reserved for Oracle Bare Metal Cloud Services 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). Three IP addresses in each subnet The first two IP addresses and the last one in each subnet's CIDR are reserved. l l 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. 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. 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 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 Bare Metal Cloud Services hardware. Oracle Bare Metal Cloud Services User Guide 80 CHAPTER 5 Compute Service 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. 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 1. In the Console, click Compute, and then choose your Compartment. 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 delete a custom image 1. In the Console, click Compute, and then choose your Compartment. 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. Oracle Bare Metal Cloud Services User Guide 81 CHAPTER 5 Compute Service 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. Use the following operations to manage custom images: l DeleteImage l GetImage l ListImages l CreateImage l UpdateImage 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 Bare Metal Cloud Services 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 Oracle Bare Metal Cloud Services User Guide 82 CHAPTER 5 Compute Service 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. Creating a Generalized Image 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 the following file to your instance: Oracle BMCS - Windows Generalize-<date>.SED.EXE. 5. Right-click the file, and then click Run as administrator. 6. Extract the files to C:\Windows\Panther. The following files are extracted into the Panther folder: l Generalize.cmd l Specialize.cmd l unattend.xml l Post-Generalize.ps1 7. Optional: If you want to preserve the opc user account, edit C:\Program Files\bmcs\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: Oracle Bare Metal Cloud Services User Guide 83 CHAPTER 5 Compute Service l l l Your connection to your Remote Desktop client will immediately be turned off and you will be logged out of the instance. Because sysprep generalize turns off Remote Desktop, you won't be able to log in to the instance again. Creating a generalized image essentially destroys the instance's functionality. 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. 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. Bring Your Own Image The Oracle Bare Metal Cloud Services enable you to bring any version of any 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 feature: l Enables lift-and-shift cloud migration projects. l Supports both older and cutting edge OSes. l Encourages experimentation. l Increases infrastructure flexibility. Licensing Requirements You must comply with all licensing requirements when you upload and start instances based on OS images you supply. Oracle Bare Metal Cloud Services User Guide 84 CHAPTER 5 Compute Service Concepts Custom Image A custom image is a clone of the root volume of a compute instance that you can use to launch any number of new virtual or bare metal instances. You can use the API, CLI, or Console to create custom images. Customer OS A customer OS is the operating system you want to use for a custom image. It can be a new installation straight from the publisher, a new installation you customize during the installation, or an image of a running OS from your datacenter. Sacrificial Image, OS, and Instance During the image creation process, you launch a Compute instance and install the customer OS on the root volume, overwriting the sacrificial OS. This instance only runs long enough to install the new operating system, apply customizations, and create an image. The Compute Service provides an image designed to be a sacrificial instance. PXE Boot Instance A Preboot eXecution Environment (PXE) boot instance is an instance that runs an HTTP service from which iPXE obtains the customer OS. iPXE The Oracle Bare Metal Cloud Services use iPXE, an open source version of the PXE toolset, to support the Bring Your Own Image feature. You must be familiar with iPXE before you create your first image. For more information, see: l iPXE Quick Start l iPXE Documentation iPXE Boot Script Delivery The Oracle Bare Metal Cloud Services implementation of iPXE delivers the boot script via the ipxeScript attribute of the LaunchInstance API call. This behavior is an important difference from the typical onpremises iPXE process, which delivers the path to the iPXE boot script via DHCP. Oracle Bare Metal Cloud Services User Guide 85 CHAPTER 5 Compute Service Process The following is a high-level outline of the Bring Your Own Image process. See Setting Up an iPXE Boot Instance and Bringing Your Own RHEL or Derivative Image for more detailed instructions. 1. Create a VCN, subnets, a bastion host, and an iPXE boot server. 2. Set up the document root of the PXE boot instance to boot and install the customer OS over iPXE. This process varies by OS. 3. Launch a sacrificial instance with the ipxeScript attribute of the LaunchInstance API call. 4. Wait for the customer OS to install on the instance. (This process usually requires less than 15 minutes.) 5. (Optional) Log on to the sacrificial instance to customize it. 6. Create a custom image of the sacrificial instance. 7. Use the custom image to launch new instances as needed. Custom Image Tenancy Be sure to launch the PXE boot and sacrificial instances within the tenancy in which you want the new custom image to reside. Images cannot be copied between tenancies. Best Practices for Cloud Images You must configure the images you create for use in the cloud. The requirements are different for each OS. Linux l If you want your OS to pick up user data, including the public half of an SSH key injected at launch, install and configure cloud-init on your image. The Oracle Bare Metal Cloud Services host a metadata service that is compatible with the cloud-init package. You can find the service at http://169.254.169.254/opc/v1/instance/. l Disable password-based or root user logins via SSH. l Lock the root user account. l Do not configure any users with a password. Oracle Bare Metal Cloud Services User Guide 86 CHAPTER 5 Compute Service l Limit metadata service access to the root user. l Ensure that the host firewall is running and properly configured. Considerations Specific to Oracle Bare Metal Cloud Services The following considerations apply to all iPXE installation and configuration processes on Oracle Bare Metal Cloud Services: l l l l The compute hardware is Oracle X5. For more information, see Supported Operating Systems in the Oracle Server X5-2 Product Notes. The root volume is ~46 GiB. The root volume is an iSCSI device. Set the netroot and iscsi_initiator kernel boot options appropriately: o netroot=iscsi:@169.254.0.2::::iqn.2015-02.oracle.boot:uefi o iscsi_initiator=iqn.2015-02.oracle.boot:instance Configure GRUB so you can access the console log of your instance: o l To ensure that your image is portable across VM and BM shapes, include the following network device drivers in the initrd file: o o l GRUB_TERMINAL="console" ixgbe ixgbevf To take advantage of multi-vNIC support, enable 16 virtual functions by adding the following line to your kernel boot options: o ixgbe.max_vfs=16 Troubleshooting Oracle recommends that you view the Apache access log to help with troubleshooting. You can find it at /var/log/httpd/access_log. Oracle Bare Metal Cloud Services User Guide 87 CHAPTER 5 Compute Service l The first files iPXE accesses are vmlinuz* and initrd*. If you do not seem them in the log, there are two probable causes: o o l A security list or host firewall is blocking port 80 between the sacrificial instance and the PXE boot instance. To fix it: n Launch the sacrificial instance and the PXE boot instance within the same subnet. n Check the host firewall. The IP address in the iPXE script, which you PUT using the ipxeScript attribute, is wrong. Make sure it matches the RFC1918 IP of the PXE boot instance. To make finding useful log entries easier, erase the access logs between each image creation. To retrieve the Console output of the sacrificial instance using the ConsoleHistory API: l Capture the Console history with CaptureConsoleHistory. l List the Console histories with ListConsoleHistories, and then find the relevant Console history ID. l Retrieve the Console history with GetConsoleHistoryContent. See the ConsoleHistory API documentation for more information. Setting Up an iPXE Boot Instance An iPXE boot instance is a Compute Service instance with Apache installed. This topic describes how to set up an iPXE boot instance. It also explains how to create a Virtual Cloud Network (VCN) and a bastion host that isolates the subnet in which we build the custom OS. The following instructions assume that you are familiar with essential Oracle Bare Metal Cloud Services tasks, such as: l Creating a VCN. l Creating a security list. l Creating an Internet Gateway. l Updating route tables. l Creating subnets. l Launching an instance. Oracle Bare Metal Cloud Services User Guide 88 CHAPTER 5 Compute Service Step 1: Configure the Network In this step, you ensure that the environment used to build new images is isolated from ingress traffic. To allow egress traffic to repositories and update servers, you build a VCN with a bastion subnet and a build subnet. The bastion subnet allows incoming traffic from the internet on port 22. The build subnet allows no incoming traffic, but does allow outgoing traffic. Both subnets allow any internal traffic between each other on RFC 1918 IPs. 1. Create a VCN called iPXE with a CIDR of 10.0.0.0/16. 2. Create a security list called build with the following rules: l l Allow Rules for Ingress o Source CIDR: 10.0.0.0/16 o IP Protocol: All protocols Allow Rules for Egress o Destination CIDR: 0.0.0.0/0 o IP Protocol: TCP o Source Port Range: All o Destination Port Range: All 3. Create a security list called bastion with the following rules: l l Allow Rules for Ingress o Source CIDR: 0.0.0.0/0 o IP Protocol: TCP o Source Port Range: All o Destination Port Range: 22 Allow Rules for Ingress o Source CIDR: 10.0.0.0/16 o IP Protocol: All protocols Oracle Bare Metal Cloud Services User Guide 89 CHAPTER 5 Compute Service l Allow Rules for Egress o Destination CIDR: 0.0.0.0/0 o IP Protocol: TCP o Source Port Range: All o Destination Port Range: All 4. Create an Internet Gateway. 5. Update the VCN's default route table: l l CIDR Block: 0.0.0.0/0 Target: Internet Gateway 6. Create two subnets, both in the same Availability Domain: l l Name: build CIDR Block: 10.0.1.0/24 Security List: build Name: bastion CIDR Block: 10.0.2.0/24 Security List: bastion Step 2: Launch the Bastion Instance This setup does not allow ingress from the internet to the iPXE boot and sacrificial instance subnet (the build subnet). Therefore, you must create a bastion instance to forward SSH connections. 1. Launch an instance with the following properties: l Name: iPXE Bastion l Image: Use the most recent Oracle Linux image. l Shape: VM.Standard1.1 l Availability Domain: Specify the Availability Domain in which you created your subnets. l VCN: iPXE l Subnet: bastion 2. Record the public IP address assigned to your bastion instance. Oracle Bare Metal Cloud Services User Guide 90 CHAPTER 5 Compute Service Step 3: Launch the iPXE Boot Instance 1. Launch an instance with the following properties: l Name: iPXE Boot l Image: Your image choice depends on the custom image you want to build. l Shape: VM.Standard1.4 l Availability Domain: Specify the Availability Domain in which you created your subnets. l VCN: iPXE l Subnet: build 2. Record the private IP address assigned to your iPXE boot instance. Step 4: Configure the iPXE Boot Instance To make the bastion instance transparent, edit the SSH config file on your local client: 1. Open the ~/.ssh/config file and add the following lines: Host ipxe_boot Hostname <private IP of the iPXE boot instance> User opc IdentityFile <private key> ProxyCommand ssh -i <private key> opc@<bastion public IP> -W %h:%p %r 2. Connect directly to the iPXE boot instance: $ ssh ipxe_boot 3. Configure the instance: $ sudo yum -y update $ sudo yum -y install httpd rsync lzma gcc libffi-devel python-devel openssl-devel unzip $ sudo easy_install pip $ pip install oraclebmc-cli $ sudo firewall-cmd --permanent --add-rich-rule 'rule family="ipv4" source address="10.0.0.0/16" service name="http" accept' $ sudo firewall-cmd --reload $ sudo systemctl start httpd Once you have completed these steps, your build environment, which includes an internet isolated subnet, bastion host, and iPXE server, is ready. Oracle Bare Metal Cloud Services User Guide 91 CHAPTER 5 Compute Service Bringing Your Own RHEL or Derivative Image This topic describes how to bring your own RHEL 6 or RHEL 7 image. It also applies to CentOS, Oracle Linux, Fedora, Scientific Linux, and other compatible OSes derived from RHEL 6 or RHEL 7. Prerequisites l l A working instance of the Oracle Bare Metal Cloud Services CLI. The CLI can be installed locally or on the iPXE boot instance. For more information, see Command Line Interface (CLI). A running iPXE instance. For more information, see Setting Up an iPXE Boot Instance. The following instructions assume that you are familiar with essential Oracle Bare Metal Cloud Services tasks, such as: l Creating a custom image. l Launching an instance using a custom image. Step 1: Get the Operating System This example uses CentOS 7 as the customer OS. 1. SSH to the iPXE boot instance. 2. Download the OS: $ cd /var/www/html/ $ sudo curl -O https://buildlogs.centos.org/rolling/7/isos/x86_64/CentOS-7-x86_64-Minimal.iso 3. Verify the hash of the downloaded OS image. a. Get the hashes: $ sudo curl -O https://buildlogs.centos.org/rolling/7/isos/x86_64/sha256sum.txt.asc b. Check the download against the hash. $ sha256sum CentOS-7-x86_64-Minimal.iso $ cat sha256sum.txt.asc | grep CentOS-7-x86_64-Minima The last hash must match. Oracle Bare Metal Cloud Services User Guide 92 CHAPTER 5 Compute Service Step 2: Build the PXE Boot Structure 1. Mount the temporary ISO image: $ sudo mkdir /var/www/html/tmp $ sudo mount -o loop /var/www/html/CentOS-7-x86_64-Minimal.iso /var/www/html/tmp 2. Copy the OS to ./Centos7: $ sudo mkdir /var/www/html/CentOS7 $ sudo cp -v -r /var/www/html/tmp/* /var/www/html/CentOS7/ 3. Remove the temporary work files: $ sudo umount /var/www/html/tmp $ sudo rmdir /var/www/html/tmp $ sudo rm CentOS-7-x86_64-Minimal.iso $ sudo rm sha256sum.txt.asc Step 3: Copy Files to the iPXE Boot Instance Copy the configuration files and script to the instance you set up: 1. Create a folder for the files: $ sudo mkdir /var/www/html/CentOS7/addons 2. Copy the following files into the folder: l Copy the direct.xml file to /var/www/html/CentOS7/addons/direct.xml. l Copy the cloud.cfg file to /var/www/html/CentOS7/addons/cloud.cfg. l Copy the ks.cfg file to /var/www/html/CentOS7/addons/ks.cfg. l Copy the ipxescript file to /var/www/html/CentOS7/addons/ipxescript. l Copy the repack.sh script to /var/www/html/CentOS7/addons/repack.sh. For more information and example files, see Bring Your Own Image Support Files. Step 4: Create the Boot Image 1. Update the local IP in the ks.cfg and ipxescript files: Oracle Bare Metal Cloud Services User Guide 93 CHAPTER 5 Compute Service $ cd /var/www/html/CentOS7/addons/ $ ip=`ip addr | grep 'state UP' -A2 | tail -n1 | awk '{print $2}' | cut -f1 -d'/'`;for file in `find -O1 . -type f`; do sudo sed -i "s/<IP>/$ip/g" $file ; done 2. (Optional) Edit the cloud.cfg and ks.cfg files to reflect the final state you want. The example Kickstart file gets the cloud-init package from the CentOS repos. Update that source as needed. 3. Run the repack.sh script to rebuild the PXE boot initrd file and kernel. $ cd /var/www/html/CentOS7/addons/ # path to initrd.img must be absolute $ sudo chmod +x repack.sh $ sudo ./repack.sh -i /var/www/html/CentOS7/images/pxeboot/initrd.img $ sudo rm -rf repack Step 5: Launch a Sacrificial Instance from the Boot Image 1. Launch the instance with the iPXE-script-file boot parameter within the same VCN (iPXE) and subnet (build) as the iPXE boot instance. $ bmcs compute instance launch --availability-domain '<AD>' --compartment-id <compartment OCID> --image-id 'ocid1.image.oc1.phx.aaaaaaaay27pdopotkapf2ahjlsn2wxndui5hn5w37hd2wss4ses4ol5xs6a' --shape 'BM.Standard1.36' --subnet-id '<subnet OCID>' --display-name 'sacrifice' --metadata '{"ssh_ authorized_keys": "<public half of keypair>"}' --ipxe-script-file 'path to ipxescript' 2. Get the public IP address of the sacrificial instance: a. In the Console, click Compute, and then choose your Compartment. b. Click Instances, if necessary, and find the sacrificial instance. c. Note the Public IP Address that appears in the instance's descriptive data. Step 6: Customize the OS 1. SSH to the sacrificial instance. It can take up to 15 minutes after launch before you can SSH into the instance. 2. Make all the changes that you want to include in the image. Oracle Bare Metal Cloud Services User Guide 94 CHAPTER 5 Compute Service Step 7: Create a Custom Image 1. Use the sacrificial instance to create an image. 2. Launch an instance using the custom image and ensure that everything works as expected. Bring Your Own Image Support Files This topic shows you the content of each file used in the Bringing Your Own RHEL or Derivative Image example. You must customize these files as described in the Bringing Your Own RHEL or Derivative Image topic. The support files include: cloud.cfg The cloud.cfg file configures cloud-init with the Oracle Bare Metal Cloud Services defaults. Create the /var/www/html/CentOS7/addons/cloud.cfg file with the following content: Oracle Bare Metal Cloud Services User Guide 95 CHAPTER 5 Compute Service users: - default disable_root: 1 ssh_pwauth: 0 mount_default_fields: [~, ~, 'auto', 'defaults,nofail', '0', '2'] resize_rootfs_tmp: /dev ssh_deletekeys: 0 ssh_genkeytypes: ~ syslog_fix_perms: ~ datasource_list: ['OpenStack'] datasource: OpenStack: metadata_urls: ['http://169.254.169.254'] timeout: 10 max_wait: 20 cloud_init_modules: - migrator - bootcmd - write-files - growpart - resizefs - set_hostname - update_hostname - update_etc_hosts - rsyslog - users-groups - ssh cloud_config_modules: - mounts - locale - set-passwords - yum-add-repo - package-update-upgrade-install - timezone - puppet Oracle Bare Metal Cloud Services User Guide 96 CHAPTER 5 Compute Service - chef - salt-minion - mcollective - disable-ec2-metadata - runcmd cloud_final_modules: - rightscale_userdata - scripts-per-once - scripts-per-boot - scripts-per-instance - scripts-user - ssh-authkey-fingerprints - keys-to-console - phone-home - final-message system_info: default_user: name: opc lock_passwd: true gecos: Oracle Public Cloud User groups: [wheel, adm, systemd-journal] sudo: ["ALL=(ALL) NOPASSWD:ALL"] shell: /bin/bash distro: rhel paths: cloud_dir: /var/lib/cloud templates_dir: /etc/cloud/templates ssh_svcname: sshd # vim:syntax=yaml direct.xml The direct.xml file limits access to the meta-data service. Create /var/www/html/CentOS7/addons/direct.xml file with the following content: Oracle Bare Metal Cloud Services User Guide 97 CHAPTER 5 Compute Service <?xml version="1.0" encoding="utf-8"?> <direct> <passthrough ipv="ipv4">-A OUTPUT -m state --state RELATED,ESTABLISHED -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.2/32 -p tcp -m owner --uid-owner root -m tcp --dport 3260 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.2.0/24 -p tcp -m owner --uid-owner root -m tcp --dport 3260 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.2/32 -p tcp -m tcp --dport 80 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p udp -m udp --dport 53 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p tcp -m tcp --dport 53 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.3/32 -p tcp -m owner --uid-owner root -m tcp --dport 80 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.4/32 -p tcp -m tcp --dport 80 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p tcp -m tcp --dport 80 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p udp -m udp --dport 67 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p udp -m udp --dport 69 -m -j ACCEPT</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.0/16 -p tcp -m tcp -m -j REJECT --reject-with tcpreset</passthrough> <passthrough ipv="ipv4">-A OUTPUT -d 169.254.0.0/16 -p udp -m udp -m -j REJECT --reject-with icmpport-unreachable</passthrough> </direct> ipxescript The ipxescript file is the iPXE boot script. Create the /var/www/html/CentOS7/addons/ipxescript with the following content: Oracle Bare Metal Cloud Services User Guide 98 CHAPTER 5 Compute Service #!ipxe set keep-san 1 set target-iqn iqn.2015-02.oracle.boot:uefi set root-path iscsi:169.254.0.2::::${target-iqn} sanhook ${root-path} || echo could not attach ${root-path} set uefi-filename \EFI\centos\grubx64.efi #CHANGE IP BELOW TO PXE BOOT SERVER IP sanboot || set url http://<IP> kernel ${url}/CentOS7/images/pxeboot/vmlinuz initrd=initrd.img vmlinuxconsole=tty0 console=ttyS0,9600 netroot=iscsi:@169.254.0.2::::iqn.2015-02.oracle.boot:uefi iscsi_initiator=iqn.201502.oracle.boot:instance ip=dhcp ks=http://<IP>/CentOS7/addons/ks.cfg initrd ${url}/CentOS7/images/pxeboot/initrd.img boot ks.cfg The kickstart file is the guided installation file. Create the /var/www/html/CentOS7/addons/ks.cfg file with the following content: Oracle Bare Metal Cloud Services User Guide 99 CHAPTER 5 Compute Service # Install in a completely non-interactive mode cmdline # Let's get a closer look at the install, optional, for troubleshooting #logging --host=<IP> --port=514 --level=debug # Use network installation url --url="http://<IP>/CentOS7/" # System authorization information auth --enableshadow --passalgo=sha512 # Root account will be locked and password erased further down # Password is only set as it's required here... # Root password is generated using the following python command # python -c 'import crypt; print(crypt.crypt("<root_password>", crypt.mksalt(crypt.METHOD_SHA512)))' rootpw --iscrypted $6$jSnNgCkcv0/1T6Ge$q6E/UFiIgIwXuwZ9jcnOUkMXYEWTiBttqJkro6o/jCBTxsb/Jk9/Ak7RoQyRq3C97xuXii3J5b6tVyPmE TOnJ1 # Keyboard layouts keyboard --vckeymap=us --xlayouts='us' # System language lang en_US.UTF-8 # System bootloader configuration bootloader --location=mbr --boot-drive=sda # Clear the Master Boot Record zerombr # Erase all paritions on all drives clearpart --all --initlabel # Partition the disk # Disk size is about 46.5 GiB, allocate: # 0.5 GiB for ESP # 8.0 GiB for swap # rest for root partition (~38 GiB) Oracle Bare Metal Cloud Services User Guide 100 CHAPTER 5 Compute Service # Do not try to allocate precisely, as anaconda adjusts the sizes and that can fail install part /boot/efi --fstype="efi" part swap --fstype="swap" part / --fstype="xfs" --fsoptions="umask=0077,shortname=winnt,_netdev" --size=512 --size=8192 --fsoptions="defaults,_netdev" --grow # System timezone timezone --utc America/Los_Angeles %packages iscsi-initiator-utils kexec-tools %end %addon com_redhat_kdump --enable %end # Reboot after the installation is successfully completed # Kickstart typically waits for us to press a key before rebooting. reboot %post --log=/root/ks-post.log # yum update yum -y update # Modify kernel arguments to add netroot and remove serial terminal cat /etc/default/grub | grep -v 'GRUB_SERIAL_COMMAND\|GRUB_TERMINAL\|GRUB_CMDLINE_LINUX' > /tmp/grub echo 'GRUB_TERMINAL="console"' >> /tmp/grub echo 'GRUB_CMDLINE_LINUX="crashkernel=auto ip=dhcp LANG=en_US.UTF-8 console=tty0 console=ttyS0,9600 iommu=on systemd.log_level=debug systemd.log_target=kmsg log_buf_len=5M netroot=iscsi:@169.254.0.2::::iqn.2015-02.oracle.boot:uefi iscsi_initiator=iqn.201502.oracle.boot:instance"' >> /tmp/grub cp /tmp/grub /etc/default/grub grub2-mkconfig -o /etc/grub2-efi.cfg # Dracut to add network drivers for VMs for file in $(find /boot -name "vmlinuz-*" -and -not -name "vmlinuz-*rescue*") ; do dracut --force --no-hostonly /boot/initramfs-${file:14}.img ${file:14} ; done # Lock root account passwd -l root Oracle Bare Metal Cloud Services User Guide 101 CHAPTER 5 Compute Service # Remove root password sed -i 's/^root:[^:]*:/root:*:/' /etc/shadow # Increase iSCSI timeout interval sed -i 's/node.session.timeo.replacement_timeout.*/node.session.timeo.replacement_timeout = 6000/' /etc/iscsi/iscsid.conf # Install cloud-init yum -y install cloud-init # Copy firewall rules and cloud.cfg curl http://<IP>/extras/direct.xml -o /etc/firewalld/direct.xml curl http://<IP>/CentOS7/addons/cloud.cfg -o /etc/cloud/cloud.cfg # Make sure sshd is running systemctl enable cloud-init #services --enabled=NetworkManager,sshd %end repack.sh The repack.sh file fixes a bug with the RHEL 6 & 7 initrd file. For more information, see the following discussion on the iPXE forum: Booting CentOS 7 via iPXE on UEFI (HP G9) Create the /var/www/html/CentOS7/addons/repack.sh file with the following content: Oracle Bare Metal Cloud Services User Guide 102 CHAPTER 5 Compute Service #!/bin/bash -e # Kernel that's provided for pxeboot has a bug that prevents it from loading when using iPXE on UEFI systems # Bug Fix: http://git.kernel.org/cgit/linux/kernel/git/stable/linuxstable.git/commit/?id=819ab9941c98f18b0f8c7ffb815e4f07186d2a5f # The fix is available in newer kernels. So, we'll download a new elrepo kernel # and repack the initrd, based on instructions at the link below. # source: http://forum.ipxe.org/showthread.php?tid=7813&pid=12480#pid12480 # This is not robust by any means and just a quick/dirty way that demonstrates what is required while getopts "i:" OPT; do case $OPT in i) INITRD_PATH=$OPTARG;; *) exit 1;; esac done echo "Working..." # make folder where we'll unpack and repack mkdir -p repack cd repack # create folders to unpack kernel and initrd mkdir -p kernel initrd ELREPO="http://elrepo.org/linux/kernel/el7/x86_64/RPMS/" KERNEL_FILE=`curl -s ${ELREPO} | egrep -o ">kernel-ml-[0-9].*rpm" | tail -1` KERNEL_FILE=${KERNEL_FILE:1} KERNEL_VERSION=${KERNEL_FILE:10} KERNEL_VERSION=${KERNEL_VERSION%.rpm} OLD_KERNEL_VERSION=`lsinitrd ${INITRD_PATH} | egrep -o "modules/[^/]*/kernel$"` OLD_KERNEL_VERSION=${OLD_KERNEL_VERSION:8} OLD_KERNEL_VERSION=${OLD_KERNEL_VERSION%/kernel} echo "Old kernel version: ${OLD_KERNEL_VERSION}" echo "New kernel version: ${KERNEL_VERSION}" echo "Downloading ${KERNEL_FILE} from ${ELREPO} ..." curl -s -O http://elrepo.org/linux/kernel/el7/x86_64/RPMS/${KERNEL_FILE} # unpack kernel (cd kernel && rpm2cpio ../${KERNEL_FILE}| cpio -idum) Oracle Bare Metal Cloud Services User Guide 103 CHAPTER 5 Compute Service # unpack initrd and delete old modules (cd initrd && xzcat "$INITRD_PATH" | cpio -idum) rm -fr initrd/lib/modules/${OLD_KERNEL_VERSION} # copy modules from new kernel rsync -a kernel/lib/modules/${KERNEL_VERSION} initrd/lib/modules # build dependency information depmod -a -b initrd ${KERNEL_VERSION} # Refer notes at "source" link listed above mkdir -p initrd/etc/modules-load.d echo "loop" > initrd/etc/modules-load.d/loop.conf echo -e "libcrc32c\nxfs" > initrd/etc/modules-load.d/xfs.conf echo -e "fat\nvfat" > initrd/etc/modules-load.d/fat.conf # requires lzma package (cd initrd && find . | cpio --create --format='newc' | lzma > ../initrd-${KERNEL_VERSION}.img) cp kernel/boot/vmlinuz-${KERNEL_VERSION} . echo "Success!! initrd and the kernel have been built." echo "Backing up original initrd and vmlinuz." (mv /var/www/html/CentOS7/images/pxeboot/initrd.img /var/www/html/CentOS7/images/pxeboot/initrd.img.bak) (mv /var/www/html/CentOS7/images/pxeboot/vmlinuz /var/www/html/CentOS7/images/pxeboot/vmlinuz.bak) echo "Copying to new files .../pxeboot/..." (cp /var/www/html/CentOS7/addons/repack/vmlinuz-${KERNEL_VERSION} /var/www/html/CentOS7/images/pxeboot/vmlinuz) (cp /var/www/html/CentOS7/addons/repack/initrd-${KERNEL_VERSION}.img /var/www/html/CentOS7/images/pxeboot/initrd.img) echo "Done!" 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 Bare Metal Cloud Services User Guide 104 CHAPTER 5 Compute Service Oracle Bare Metal Cloud Services boots each instance from a network drive. This configuration requires additional actions when you update the OS kernel. Oracle Bare Metal Cloud Services 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 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 l 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. If you use a custom image based on an Oracle-provided image, the included yum plug-in will continue to work, barring extraordinary changes. 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 Oracle Bare Metal Cloud Services User Guide 105 CHAPTER 5 Compute Service Oracle-provided images incorporate the Unbreakable Enterprise Kernel (UEK). If you want to switch to a nonUEK kernel, you must update the DEFAULTKERNEL value to "kernel" before you run yum update kernel. Manual Updates 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-b708c519cf6829c8 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 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 Oracle Bare Metal Cloud Services User Guide 106 CHAPTER 5 Compute Service 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. 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. Oracle Bare Metal Cloud Services User Guide 107 CHAPTER 5 Compute Service 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. 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. Oracle Bare Metal Cloud Services User Guide 108 CHAPTER 5 Compute Service 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. Oracle Bare Metal Cloud Services User Guide 109 CHAPTER 5 Compute Service 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.) Oracle Bare Metal Cloud Services User Guide 110 CHAPTER 5 Compute Service 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. 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. Oracle Bare Metal Cloud Services User Guide 111 CHAPTER 5 Compute Service 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 for Your VCN. 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. Oracle Bare Metal Cloud Services User Guide 112 CHAPTER 5 Compute Service 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 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). 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 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: l l A cloud network to launch the instance into. For information about setting up cloud networks, see Overview of the Networking Service. 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: Oracle Bare Metal Cloud Services User Guide 113 CHAPTER 5 Compute Service 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 l l l l Launch in Compartment: The compartment in which you want to launch the instance. Name: Optional. 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. Image Compartment: The compartment from which to select the image. Image: The image to use for booting the instance. The image determines the operating system and other software for the instance. For more information, see Oracle-Provided Images and Managing Custom Images. Shape: A template that determines the number of CPUs, amount of memory, and other resources allocated to a newly created instance. Choose one of the following Bare Metal or VM shapes: Bare Metal Shapes Shape Instance Type OCPU Memory (GB) Local Disk (TB) BM.Standard1.36 Standard compute capacity 36 256 Block storage only BM.HighIO1.36 High I/O compute capacity 36 512 12.8TB NVMe SSD BM.DenseIO1.36 Dense I/O compute capacity 36 512 28.8TB NVMe SSD VM Shapes VMs are an option that provides flexibility in compute power, memory capability, and network resources for lighter applications. You can use the Block Volume Service to add network-attached block storage as needed. Oracle Bare Metal Cloud Services User Guide 114 CHAPTER 5 Compute Service l l l l l l l l Shape Instance Type OCPU Memory (GB) Local Disk (TB) VM.Standard1.1 Standard 1 7 Block Storage only VM.Standard1.2 Standard 2 14 Block Storage only VM.Standard1.4 Standard 4 28 Block Storage only VM.Standard1.8 Standard 8 56 Block Storage only VM.Standard1.16 Standard 16 112 Block Storage only VM.DenseIO1.4 Standard 4 60 3.2 TB NVMe SSD VM.DenseIO1.8 Standard 8 120 6.4 TB NVMe SSD VM.DenseIO1.16 Standard 16 240 12.8 TB NVMe SSD Availability Domain: The Availability Domain in which you want to run the instance. Virtual Cloud Network Compartment: The compartment containing the network in which to launch the instance. Virtual Cloud Network: The network in which to launch the instance. Subnet Compartment: The compartment containing a subnet within the cloud network to attach the instance to. 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 for Your VCN. 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). 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 for Your VCN. 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. Oracle Bare Metal Cloud Services User Guide 115 CHAPTER 5 Compute Service 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. 3. Read the Partner Terms of Use. If you accept them, click I accept the Partner Terms of Use 4. 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: l l A cloud network to launch the instance into. For information about setting up cloud networks, see Overview of the Networking Service. A security list that enables 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 Managing Security Lists. To launch a Windows 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 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: Oracle Bare Metal Cloud Services User Guide 116 CHAPTER 5 Compute Service l l l l l Launch in Compartment: The compartment in which you want to launch the instance. Name: Optional. 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. Image Compartment: The compartment from which to select the image. Image: The image to use for booting the instance. The image determines the operating system and other software for the instance. For more information, see Oracle-Provided Images and Managing Custom Images. Shape: A template that determines the number of CPUs, amount of memory, and other resources allocated to a newly created instance. Choose one of the following Bare Metal or VM shapes: Bare Metal Shapes Shape Instance Type OCPU Memory (GB) Local Disk (TB) BM.Standard1.36 Standard compute capacity 36 256 Block storage only BM.HighIO1.36 High I/O compute capacity 36 512 12.8TB NVMe SSD BM.DenseIO1.36 Dense I/O compute capacity 36 512 28.8TB NVMe SSD VM Shapes VMs are an option that provides flexibility in compute power, memory capability, and network resources for lighter applications. You can use the Block Volume Service to add network-attached block storage as needed. Shape Instance Type OCPU Memory (GB) Local Disk (TB) VM.Standard1.1 Standard 1 7 Block Storage only VM.Standard1.2 Standard 2 14 Block Storage only VM.Standard1.4 Standard 4 28 Block Storage only VM.Standard1.8 Standard 8 56 Block Storage only Oracle Bare Metal Cloud Services User Guide 117 CHAPTER 5 Compute Service l l l l l l l l Shape Instance Type OCPU Memory (GB) Local Disk (TB) VM.Standard1.16 Standard 16 112 Block Storage only VM.DenseIO1.4 Standard 4 60 3.2 TB NVMe SSD VM.DenseIO1.8 Standard 8 120 6.4 TB NVMe SSD VM.DenseIO1.16 Standard 16 240 12.8 TB NVMe SSD Availability Domain: The Availability Domain in which you want to run the instance. Virtual Cloud Network Compartment: The compartment containing the network in which to launch the instance. Virtual Cloud Network: The network in which to launch the instance. Subnet Compartment: The compartment containing a subnet within the cloud network to attach the instance to. 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 for Your VCN. 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). 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 for Your VCN. 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. 3. Read the Partner Terms of Use. If you accept them, click I accept the Partner Terms of Use. 4. Click Launch Instance. 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. Oracle Bare Metal Cloud Services User Guide 118 CHAPTER 5 Compute Service Use these API operations to manage instances: l ListInstances l LaunchInstance l GetInstance l UpdateInstance l TerminateInstance l GetWindowsInstanceInitialCredentials 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 Service Policy To connect to a running instance with SSH, you don't need an IAM Service 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 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. Oracle Bare Metal Cloud Services User Guide 119 CHAPTER 5 Compute Service Prerequisites You'll need the following information to connect to the instance: l l 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. 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. 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. 2. Use the following SSH command to access the instance. $ 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 Session and enter the following: Oracle Bare Metal Cloud Services User Guide 120 CHAPTER 5 Compute Service 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 3. In the Category pane, expand Connection, expand SSH, and then click Auth. 4. Click Browse to select your private key. 5. 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. 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 Bare Metal Cloud Services when 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. Oracle Bare Metal Cloud Services User Guide 121 CHAPTER 5 Compute Service 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. 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. Oracle Bare Metal Cloud Services User Guide 122 CHAPTER 5 Compute Service 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 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. Oracle Bare Metal Cloud Services User Guide 123 CHAPTER 5 Compute Service 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 124 CHAPTER 5 Compute Service 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 Service Policy No IAM Service 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 Service API (e.g., with GetInstance). The policy in Let Users Launch Instances covers that ability. 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. 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. Oracle Bare Metal Cloud Services User Guide 125 CHAPTER 5 Compute Service 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.) Oracle Bare Metal Cloud Services User Guide 126 CHAPTER 5 Compute Service 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", "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== [email protected]", "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. Oracle Bare Metal Cloud Services User Guide 127 CHAPTER 5 Compute Service Renaming an Instance You can rename an instance without changing its Oracle Cloud Identifier (OCID). Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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-networkfamily. 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 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. 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. 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. Oracle Bare Metal Cloud Services User Guide 128 CHAPTER 5 Compute Service 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 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. 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 volumes, you could simplify that policy to include only manage instance-family, and remove the statements involving volume-family and virtual-network-family. 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 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. Oracle Bare Metal Cloud Services User Guide 129 CHAPTER 5 Compute Service Reboot Shuts down the instance, and then restarts it. Resource Billing The Stop state has no effect on the resources you consume. Billing continues for instances that you stop, and related resources continue to apply against any relevant quotas. You must Terminate an instance to remove its resources from billing and quotas. 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. 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. 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. Oracle Bare Metal Cloud Services User Guide 130 CHAPTER 5 Compute Service For administrators: The policy in Let Users Launch Instances includes the ability to terminate an instance (with or without an attached block volume). 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 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. 4. Click Terminate, and then respond to the confirmation prompt. Terminated instances temporarily remain in the list of instances with the status Terminated. 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. Use the TerminateInstance operation to terminate an instance. Oracle Bare Metal Cloud Services User Guide 131 CHAPTER 6 Database Service 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 DB Systems The following sections apply to all types of DB Systems. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access Oracle Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. Oracle Bare Metal Cloud Services User Guide 132 CHAPTER 6 Database Service For more information, see Compartments and Tenancy. For general information about using the API, see About the API. Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service 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 Bare Metal Cloud Services 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. Limits on Resource Database Service See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Many Database Service API operations are subject to throttling. Exadata DB Systems Exadata DB Systems let you to leverage the power of Exadata within the Oracle Bare Metal Cloud Services. 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: Oracle Bare Metal Cloud Services User Guide 133 CHAPTER 6 Database Service l Oracle Database 11g Release 2 l Oracle Database 12c Release 1 l Oracle Database 12c Release 2 Subscription Types You have a choice of subscription types for Exadata DB Systems: l 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. Metered Subscription: With a metered subscription, you are charged based on your service usage. Two varieties exist: 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 l Scaling within an Exadata DB System lets you modify compute node processing power within the system. 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 Oracle Bare Metal Cloud Services User Guide 134 CHAPTER 6 Database Service 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: 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 Bare Metal Cloud Services. 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. Oracle Bare Metal Cloud Services User Guide 135 CHAPTER 6 Database Service Statistic Quarter Rack Half Rack Full Rack Number of Compute Nodes 2 4 8 Total Minimum (Default) Number of Enabled CPU Cores 22 44 88 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 l l The DATA disk group is intended for the storage of Oracle Database data files. 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. 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 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. Oracle Bare Metal Cloud Services User Guide 136 CHAPTER 6 Database Service 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. Usable Storage Statistic Quarter Rack Half Rack Full Rack Total Usable Storage Capacity 84 TB 168 TB 336 TB Allocation when Database Backups on Exadata Storage are provisioned DATA: 33.6 TB DATA: 67.2 TB DATA: 134.4 TB RECO: 50.4 TB RECO: 100.8 TB RECO: 201.6 TB DATA: 67.2 TB DATA: 134.4 TB DATA: 268.8 TB RECO: 16.8 T RECO: 33.6 TB RECO: 67.2 TB Allocation when Database Backups on Exadata Storage are not provisioned Managing Exadata DB Systems This topic explains how to launch, start, stop, terminate, scale, and check the status of an Exadata DB System, configure required access to the Oracle Bare Metal Cloud Object Storage Service, and set up DNS. Oracle Bare Metal Cloud Services User Guide 137 CHAPTER 6 Database Service When you launch a Exadata DB System using the Console or the API, 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Database Admins Manage Database Systems lets the specified group do everything with databases and related Database Service resources. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for databases, see Details for the Database Service. Prerequisites l The public key, in OpenSSH format, from the key pair that you plan to use for connecting to the DB System via SSH. A sample public key, abbreviated for readability, is shown below. ssh-rsa AAAAB3NzaC1yc2EAAAABJQAA....lo/gKMLVM2xzc1xJr/Hc26biw3TXWGEakrK1OQ== rsa-key-20160304 For more information, see Managing Key Pairs on Linux Instances. l l l 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 the Networking Service. See the additional requirements below. Exadata DB Systems require two separate VCN subnets: a client subnet for user data and a backup subnet for backup traffic. Do not use a subnet that overlaps with 192.168.132.0/22 or 192.168.136.0/21. This restriction applies to both the client subnet and backup subnet. 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). Oracle recommends using a VCN Resolver for DNS name resolution for the client subnet because 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. Oracle Bare Metal Cloud Services User Guide 138 CHAPTER 6 Database Service l 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. For more information, see Managing Security Lists. Important! Make sure the security list ingress and egress rules for both the client subnet and backup subnet are configured to allow TCP and ICMP traffic between all nodes and all ports in the respective subnet. The Exadata DB System will fail to provision if TCP connectivity fails across nodes. For example, if the client subnet uses the source CIDR 10.0.5.0/24, create rules as shown below, and then create similar rules for the backup subnet. Ingress Rules: 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 Source Port Range: All Destination Port Range: All Allows: TCP traffic for ports: all Destination: 10.0.5.0/24 IP Protocol: ICMP Type and Code: All Allows: ICMP traffic for: all types and codes For information about creating and editing rules, see Managing Security Lists. 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. Oracle Bare Metal Cloud Services User Guide 139 CHAPTER 6 Database Service l l Console Enabled: False Create Container Database: True for version 12.2.0.1 and 12.1.0.2 databases. False for version 11.2.0.4 databases. 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: ASM l Database Territory: AMERICA l l Database Unique Name: The user-specified database name and a system-generated suffix, for example, dbtst_phx1cs. 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 Name A friendly, display name for the DB System. The name doesn't need to be unique. An Oracle Cloud Identifier (OCID) will uniquely identify the DB System. Oracle Bare Metal Cloud Services User Guide 140 CHAPTER 6 Database Service Option Description Availability Domain The Availability Domain in which the DB System resides. 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. l l l l l l Cluster Name BM.HighIO1.36: Provides a 1-node DB System (one bare metal server), with up to 36 CPU cores, 512 GB memory, and four 3.2 TB locally attached NVMe drives (12.8 TB total) to the DB System. 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. BM.RACLocalStorage1.72: Provides a 2-node RAC DB System (two bare metal servers), with up to 36 CPU cores on each node (72 total per cluster), 512 GB memory, direct attached shared storage with twenty 1.2 TB SSD drives (24 TB total). 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. 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. Exadata.Full1.336: Provides an 8-node Exadata DB System with 88 enabled CPU cores, with up to 248 additional CPU cores, 720 GB RAM per node, 1152 TB raw storage, 336 TB of usable storage, and unlimited I/O. This shape supports only the Enterprise Edition - Extreme Performance. 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. Oracle Bare Metal Cloud Services User Guide 141 CHAPTER 6 Database Service Option Description Total Number of Nodes Displayed only if you selected a multi-node shape. Indicates the number nodes in the cluster. Oracle Database Software Edition The database edition supported by the DB System. You can mix supported database versions on the DB System, but not editions. (The database edition cannot be changed and applies to all the databases in this DB System.) CPU Core Count The number of CPU cores for the DB System. The text below the field indicates the acceptable values, based on the shape you selected. For a multi-node DB System, the core count is evenly divided across the nodes. You can increase the CPU cores to accommodate increased demand after you launch a DB System. See Database Service Known Issues for a core count issue that affects Exadata DB Systems. SSH Public Key The public key portion of the key pair you want to use for SSH 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 Percentage The percentage (40% or 80%) assigned to DATA storage (user data and database files). The remaining percentage is assigned to RECO storage (database redo logs, archive logs, and recovery manager backups). Disk Redundancy The type of redundancy configured for the DB System. Normal is 2-way mirroring, recommended for test and development systems. High is 3-way mirroring, recommended for production systems. Network Information Virtual Cloud Network Compartment The compartment containing the network in which to launch the DB System. Oracle Bare Metal Cloud Services User Guide 142 CHAPTER 6 Database Service Option Description Virtual Cloud Network The VCN in which to launch the DB System. Subnet Compartment The compartment containing a subnet within the cloud network to 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.132.0/22 or 192.168.136.0/21. This restriction applies to both the client subnet and backup subnet. For 1- and 2-node RAC DB Systems: 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 Subnet For Exadata DB Systems only. The subnet to use for the backup network , which is typically used to transport backup information to and from the Oracle Bare Metal Cloud Object Storage Service, and for Data Guard replication. Do not use a subnet that overlaps with 192.168.132.0/22 or 192.168.136.0/21. This restriction applies to both the client subnet and backup subnet. If you plan to back up databases to the Object Storage Service, see the network prerequisites in Backing Up an Exadata Database. Hostname Prefix Your choice of host name for the DB System. The host name must 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. Oracle Bare Metal Cloud Services User Guide 143 CHAPTER 6 Database Service Option Description Host Domain Name The domain name for the DB System. If the selected subnet uses the Oracleprovided 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 the Object Storage Service, 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 Domain URL Combines the host and domain names to display the fully qualified domain name (FQDN) for the database. The maximum length is 64 characters. Database Information 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. Database Version The version of the initial database created on the DB System when it 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 Admin Password A strong password for SYS, SYSTEM, 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 -. Oracle Bare Metal Cloud Services User Guide 144 CHAPTER 6 Database Service Option Description Confirm Database Admin Password The same as above. Database Workload Select the workload type that best suits your application. 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 Set The character set for the database. The default is AL32UTF8. National Character Set The national character set for the database. The default is AL16UTF16. 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. 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 Oracle Bare Metal Cloud Services User Guide 145 CHAPTER 6 Database Service system is not ready to use yet. l l l l l l 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. Starting: Yellow icon. The DB System is being powered on by the start or reboot action in the Console or API. Stopping: Yellow icon. The DB System is being powered off by the stop or reboot action in the Console or API. Stopped: Yellow icon. The DB System was powered off by the stop action in the Console or API. Terminating: Gray icon. The DB System is being deleted by the terminate action in the Console or API. Terminated: Gray icon. The DB System has been deleted and is no longer available. 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. 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. 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. Resource Billing 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. Oracle Bare Metal Cloud Services User Guide 146 CHAPTER 6 Database Service 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. 1. Open the Console, click Database, and then choose your Compartment. 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. 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 will be lost when the system is terminated. Oracle recommends that you back up any data in the DB System prior to terminating it. 1. Open the Console, click Database, and then choose your Compartment. A list of DB Systems is displayed. 2. For the DB System you want to terminate, click the Actions icon ( ) and then click Terminate. 3. Confirm when prompted. The DB System's icon indicates Terminating. At this point, you cannot connect to the system and any open connections will be terminated. 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. Use these API operations to manage DB System components. DB Systems: Oracle Bare Metal Cloud Services User Guide 147 CHAPTER 6 Database Service l GetDbSystem l LaunchDbSystem l ListDbSystems l TerminateDbSystem Database homes: l GetDbHomes l ListDbHomes Databases: l GetDatabase l ListDatabases 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 Configuring a Static Route for Accessing the Object Store Note The following procedure is required and must be performed on every compute node in an Exadata DB System. Access to the Oracle Bare Metal Cloud Object Storage Service is required for backing up databases, patching, and updating the cloud tooling on an Exadata DB System. Oracle Bare Metal Cloud Services User Guide 148 CHAPTER 6 Database Service 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. 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. Create a new static rule for BONDETH1. Replace the file /etc/sysconfig/network-scripts/routebondeth1 with the following entries. ADDRESS0=129.146.0.0 NETMASK0=255.255.0.0 GATEWAY0=<gateway_from_previous_step> 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 steps above 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. Oracle Bare Metal Cloud Services User Guide 149 CHAPTER 6 Database Service 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 because it automatically resolves the Swift endpoints required for backing up databases, patching, and updating the cloud tooling on an Exadata DB System. 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 Bare Metal Cloud ServicesConsole 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. 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 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 the Networking Service, 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 l The full path to the file that contains the private key associated with the public key used when the system was launched. 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 Oracle Bare Metal Cloud Services User Guide 150 CHAPTER 6 Database Service 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 Bare Metal Cloud ServicesConsole 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> <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 Connection type: SSH 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. 5. Click Open to start the session. Oracle Bare Metal Cloud Services User Guide 151 CHAPTER 6 Database Service 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. [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. Oracle Bare Metal Cloud Services User Guide 152 CHAPTER 6 Database Service [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 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 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.) 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 Oracle Bare Metal Cloud Services User Guide 153 CHAPTER 6 Database Service 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>) ) ) 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 = (SERVER = DEDICATED) (SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>) ) ) 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: Oracle Bare Metal Cloud Services User Guide 154 CHAPTER 6 Database Service l 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. 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)) (ADDRESS = (PROTOCOL = TCP)(HOST = <publicIP2>)(PORT = 1521)) ) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>) ) ) 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 Bare Metal Cloud Object Storage Service. For more information, see Configuring a Static Route for Accessing the Object Store. Oracle Bare Metal Cloud Services User Guide 155 CHAPTER 6 Database Service 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 # 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 lower than 17430 If the release label is lower than 170430, use the following procedure to update the tooling. 1. Download the RPM file by using the following curl command. # curl -u 'public-read-only:XAQV$;abnLiM8c&r]Gqx' -o dbaastools_exa.rpm -X GET "https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/exadata/patches/dbaas_ patch/dbaastools_exa.rpm" 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 17430 or higher If the release label is 170430 or higher, use the following procedure to update the tooling. Oracle Bare Metal Cloud Services User Guide 156 CHAPTER 6 Database Service 1. Check whether any cloud tooling updates are available. # /var/opt/oracle/exapatch/exadbcpatch -list_tools 2. Examine the command response and determine the patch ID of the available cloud tooling update. 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/exadbcpatch -toolsinst -rpmversion=<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 exadbcpatch utility runs as a foreground process and does not return control to the user until it completes. Alternatively, you can use exadbcpatchsm, which executes as a background process. Both utilities accept the same arguments and perform the same operations. However, when you use exadbcpatchsm the utility 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. Oracle Bare Metal Cloud Services User Guide 157 CHAPTER 6 Database Service 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 Tooling on an Exadata DB System. Prerequisites l l Patches are stored in the Oracle Bare Metal Cloud 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. 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 Managing Route Tables. 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 129.146.0.0/16. For more information, see Managing Security Lists. Note that the network traffic between the DB System and Object Storage Service does not leave the cloud and never reaches the public internet. For more information, see Managing Internet Gateways. Managing Patches To check prerequisites before applying a patch You can perform the prerequisites-checking operation using the exadbcpatchmulti command as follows: 1. Connect to the compute node as the opc user. 2. Start a root-user command shell: $ 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 ...] ...] Oracle Bare Metal Cloud Services User Guide 158 CHAPTER 6 Database Service where: l l l patchid identifies the patch to be pre-checked. -sshkey specifies the location of the SSH private key of the opc user, which is used to connect to compute nodes in the cluster. -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. 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: 1. Connect to the compute node as the opc user. 2. Start a root-user command shell: $ sudo -s # 3. Execute the exadbcpatchmulti command with the -apply_async action: Oracle Bare Metal Cloud Services User Guide 159 CHAPTER 6 Database Service # /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 l l l patchid identifies the patch to be applied. -sshkey specifies the location of the SSH private key of the opc user, which is used to connect to compute nodes in the cluster. -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. -run_datasql=1 instructs the exadbcpatchmulti command to execute patch-related SQL commands. Notes o 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. o 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: Oracle Bare Metal Cloud Services User Guide 160 CHAPTER 6 Database Service # /var/opt/oracle/exapatch/exadbcpatchmulti -apply_async 23456789 -sshkey=/home/opc/.ssh/id_rsa -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 4. Exit the root-user command shell: # exit $ To list applied patches You can produce a list of applied patches to determine which patches have been applied. 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 Oracle Bare Metal Cloud Services User Guide 161 CHAPTER 6 Database Service 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. 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: 1. Connect to the compute node as the opc user. 2. Start a root-user command shell: $ 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 l l l patchid identifies the patch to be rolled back. -sshkey specifies the location of the SSH private key of the opc user, which is used to connect to compute nodes in the cluster. -instanceN specifies a compute node and one or more Oracle home directories that are subject to the rollback operation. In this context, an Oracle home directory may be an Oracle Database home directory or the Oracle Grid Infrastructure home directory. -run_datasql=1 instructs the exadbcpatchmulti command to execute rollback-related SQL commands. Oracle Bare Metal Cloud Services User Guide 162 CHAPTER 6 Database Service Notes o 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. o 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 -sshkey=/home/opc/.ssh/id_rsa -instance1=hostname1:/u01/app/12.1.0.2/grid -instance2=hostname2:/u01/app/12.1.0.2/grid -run_datasql=1 4. Exit the root-user command shell: # 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. 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 Oracle Database 12c Release 2 (12.2). How you access EM Express depends on whether you want to manage a CDB or PDB. Oracle Bare Metal Cloud Services User Guide 163 CHAPTER 6 Database Service l l To manage the CDB. When a database deployment is created, the Database Service automatically sets port 5500 on the deployment’s compute nodes for EM Express access to the CDB. To manage a PDB. 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 an Oracle Database 12.2 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 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 Setting 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. 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. Oracle Bare Metal Cloud Services User Guide 164 CHAPTER 6 Database Service 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: 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=0.0.0.0/0, protocol=TCP, and port=<port number or port range>. For detailed information about creating or updating a security list, see Managing 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. Oracle Bare Metal Cloud Services User Guide 165 CHAPTER 6 Database Service 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 Tooling on an Exadata DB System. Prerequisites The following are prerequisites if you plan to create a database and store backups in the Oracle Bare Metal Cloud Object Storage Service. l l l l l The Exadata DB System requires access the object store. For more information, see Configuring a Static Route for Accessing the Object Store. 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 Managing Route Tables. 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 129.146.0.0/16. For more information, see Managing Security Lists. Note that the network traffic between the DB System and Object Storage Service does not leave the cloud and never reaches the public internet. For more information, see Managing Internet Gateways. An existing Object Storage Service bucket to use as the backup destination. You can use the Console or the Object Storage Service API to create the bucket. For more information, see Managing Buckets. A Swift password generated by Oracle Bare Metal Cloud Services. You can use the Console or the IAM Service API to generate the password. For more information, see Working with Swift Passwords. The user name specified in the backup configuration file must have tenancy-level access to the Object Storage Service. 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 the Object Storage Service. 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. Oracle Bare Metal Cloud Services User Guide 166 CHAPTER 6 Database Service 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. ssh -i <private_key_path> opc@<node_ip_address> 2. Log in as opc and then sudo to the root user. login as: opc [opc@dbsys ~]$ sudo su - 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 the Object Storage Service. For parameter descriptions, see Create Database Parameters. Oracle Bare Metal Cloud Services User Guide 167 CHAPTER 6 Database Service { "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.us-phoenix1.oraclecloud.com/v1/mycompany/DBBackups", "cloudStorageUser": "[email protected]", "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. Oracle Bare Metal Cloud Services User Guide 168 CHAPTER 6 Database Service [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. Oracle Bare Metal Cloud Services User Guide 169 CHAPTER 6 Database Service [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". Oracle Bare Metal Cloud Services User Guide 170 CHAPTER 6 Database Service Parameter Description 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.1.0.2, 12.2.0.1, 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. Oracle Bare Metal Cloud Services User Guide 171 CHAPTER 6 Database Service Parameter Description 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 ncharset The database national character set. The value AL16UTF16 or UTF8, in quotes. Oracle Bare Metal Cloud Services User Guide 172 CHAPTER 6 Database Service Parameter Description 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 Bare Metal Cloud Object Storage Service. You must specify all the cloudStorage parameters. BOTH Configure database backups to both local disk and an existing bucket in the Object Storage Service. You must specify all the cloudStorage parameters. For example: "backupDestination":"BOTH" cloudStorageContainer= <swift_url> Required if you specify a backup destination of OSS or BOTH. The Object Storage Service URL, your Oracle Bare Metal Cloud Services tenant, and an existing bucket in the object store to use as the backup destination, in the following format. https://swiftobjectstorage.us-phoenix1.oraclecloud.com/v1/<tenant>/<bucket> For example: "cloudStorageContainer":"https://swiftobjectstorage.us-phoenix1.oraclecloud.com/v1/mycompany/DBBackups" cloudStorageUser= <user_name> Required if you specify a backup destination of OSS or BOTH. The user name for the Oracle Bare Metal Cloud Services user account, for example: "cloudStorageUser":"[email protected]" 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. Oracle Bare Metal Cloud Services User Guide 173 CHAPTER 6 Database Service Parameter Description cloudStoragePwd= <swift-password> Required if you specify a backup destination of OSS or BOTH. The Swift password generated by using the Console or IAM Service 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 Bare Metal Cloud Services user. 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. ssh -i <private_key_path> opc@<node_ip_address> 2. Log in as opc and then sudo to the root user. login as: opc [opc@dbsys ~]$ sudo su - 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 . Oracle Bare Metal Cloud Services User Guide 174 CHAPTER 6 Database Service { "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. [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. Oracle Bare Metal Cloud Services User Guide 175 CHAPTER 6 Database Service { "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. Oracle Bare Metal Cloud Services User Guide 176 CHAPTER 6 Database Service [root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i db_status.json [root@dbsys ~]# cat /home/oracle/deletedb.out { "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. Parameter Description object The value "db". action The value "start". operation The value "deletedb". Oracle Bare Metal Cloud Services User Guide 177 CHAPTER 6 Database Service Parameter Description dbname The database name, in quotes. 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 Bare Metal Cloud Object Storage Service and to the local disk Fast Recovery Area. This topic explains how to: l 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 the Object Storage Service, the file also contains the credentials to access the service. 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 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 Tooling on an Exadata DB System. Prerequisites l l The Exadata DB System requires access the Oracle Bare Metal Cloud Object Storage Service. For more information, see Configuring a Static Route for Accessing the Object Store. 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 Managing Route Tables. Oracle Bare Metal Cloud Services User Guide 178 CHAPTER 6 Database Service 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 129.146.0.0/16. For more information, see Managing Security Lists. Note that the network traffic between the system and Object Storage Service does not leave the cloud and never reaches the public internet. For more information, see Managing Internet Gateways. l l l An existing Object Storage Service bucket to use as the backup destination. You can use the Console or the Object Storage Service API to create the bucket. For more information, see Managing Buckets. A Swift password generated by Oracle Bare Metal Cloud Services. You can use the Console or the IAM Service API to generate the password. For more information, see Working with Swift Passwords. The user name specified in the backup configuration file must have tenancy-level access to the Object Storage Service. 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 the Object Storage Service. 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. Default Backup Configuration The backup configuration follows a set of Oracle best-practice guidelines: 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 Service 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 Service and local storage: 30 days, with the 7 most recent days' backups available on local storage. l Object Storage Service only: 30 days. l Local storage only: 7 days. Encryption: Oracle Bare Metal Cloud Services User Guide 179 CHAPTER 6 Database Service l Both Object Storage Service and local storage: All backups to cloud storage are encrypted. l Object Storage Service 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. 1. SSH to the first compute node in the Exadata DB System. ssh -i <private_key_path> opc@<node_1_ip_address> 2. Log in as opc and then sudo to the root user. login as: opc [opc@dbsys ~]$ sudo su - 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 the Object Storage Service. The parameters are described below this procedure. Oracle Bare Metal Cloud Services User Guide 180 CHAPTER 6 Database Service [root@dbsys ~]# cd /var/opt/oracle/ocde/assistants/bkup/ [root@dbsys bkup]# mv bkup.cfg bkup.cfg.old vi bkup.cfg bkup_disk=yes bkup_oss=yes bkup_oss_url=https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/companyabc/DBBackups [email protected] 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 The backup configuration file parameters are described below. Parameter Description bkup_disk=[yes|no] Whether to back up locally to disk (Fast Recovery Area). bkup_oss=[yes|no] Whether to back up to the Object Storage Service. If yes, you must also provide the parameters bkup_oss_url, bkup_oss_user, bkup_oss_passwd, and bkup_oss_recovery_ window. Oracle Bare Metal Cloud Services User Guide 181 CHAPTER 6 Database Service Parameter Description bkup_oss_url=<swift_url> Required if bkup_oss=yes. The Object Storage Service URL including the tenant and bucket you want to use. The URL is: https://swiftobjectstorage.usphoenix1.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. bkup_oss_user=<bmcs_user_name> Required if bkup_oss=yes. The user name for the Oracle Bare Metal Cloud Services user account, for example [email protected]. 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. Oracle Bare Metal Cloud Services User Guide 182 CHAPTER 6 Database Service Parameter Description bkup_oss_passwd=<swift_password> Required if bkup_oss=yes. The Swift password generated by using the Console or IAM Service API, as described in Prerequisites. This is not the password for the Oracle Bare Metal Cloud Services user. 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 Service 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: $ $ORACLE_HOME/bin/olsnodes -n The first node has the number 1 listed beside the node name. 2. Log in as opc and then sudo to the root user. login as: opc [opc@dbsys ~]$ sudo su - Oracle Bare Metal Cloud Services User Guide 183 CHAPTER 6 Database Service 3. You can let the backup follow the current retention policy, or you can create a long-term 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 Service 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. 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: $ $ORACLE_HOME/bin/olsnodes -n The first node has the number 1 listed beside the node name. Oracle Bare Metal Cloud Services User Guide 184 CHAPTER 6 Database Service 2. Start a root-user command shell: $ 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. 5. Exit the root-user command shell: # exit$ To delete a backup in the Object Storage Service Use the RMAN delete backup command to delete a backup from the Object Store. What Next? If you used the Object Storage Service 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 12.2, 12.1, or 11.2. 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 DB Systems There are two types of bare metal DB Systems: Oracle Bare Metal Cloud Services User Guide 185 CHAPTER 6 Database Service l l 1-node DB Systems consist of a single bare metal server running Oracle Linux 6.8, with locally attached NVMe storage. This is the least expensive type of system and is recommended for test and development environments. If the node fails, you can simply launch another system and restore databases from current backups. 2-Node RAC DB Systems consist of two bare metal server running Oracle Linux 6.8, in a RAC configuration, with direct-attached shared storage. The cluster provides automatic failover. This system supports only Enterprise Edition - Extreme Performance and is recommended for production applications. You can manage these systems by using the Console, API, Enterprise Manager, Enterprise Manager Express, SQL Developer, and the dbcli CLI. 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 1- and 2-node RAC DB Systems support the following Oracle Database editions. l Standard Edition l Enterprise Edition 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 l Oracle Database 12c Release 1 When you launch a 1- or 2-node RAC 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 have multiple databases within them. All the databases within a database home will have the same version, but each home can have a different version. Oracle Bare Metal Cloud Services User Guide 186 CHAPTER 6 Database Service Shapes for 1- and 2-Node RAC DB Systems When you launch a DB System, you choose a shape, which determines the resources allocated to the DB System. The available shapes are: l l l BM.HighIO1.36: Provides a 1-node DB System (one bare metal server), with up to 36 CPU cores, 512 GB memory, and four 3.2 TB locally attached NVMe drives (12.8 TB total) to the DB System. 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. BM.RACLocalStorage1.72: Provides a 2-node RAC DB System (two bare metal servers), with up to 36 CPU cores on each node (72 total per cluster), 512 GB memory, direct attached shared storage with twenty 1.2 TB SSD drives (24 TB total). Storage Considerations The shape you choose for a 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 1- and 2-node RAC DB Systems. Shape Raw Storage Usable Storage with Normal Redundancy (2-way Mirroring) Usable Storage with High Redundancy (3-way Mirroring) BM.HighIO1.36 12.8 TB NVMe DATA 3.5 TB DATA 2.3 TB RECO 740 GB RECO 440 GB 28.8 TB NVMe DATA 9.4 TB DATA 5.4 TB RECO 1.7 TB RECO 1 TB 24 TB SSD DATA 8.6 TB DATA 5.4 TB RECO 1.6 TB RECO 1 TB BM.DenseIO1.36 BM.RACLocalStorage1.72 Managing Bare Metal DB Systems This topic explains how to launch, start, stop, terminate, scale, and check the status of a DB System, and set up DNS for 1- and 2-node RAC DB Systems. Oracle Bare Metal Cloud Services User Guide 187 CHAPTER 6 Database Service When you launch a DB System using the Console or the API, 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: The policy in Let Database Admins Manage Database Systems lets the specified group do everything with databases and related Database Service resources. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for databases, see Details for the Database Service. Prerequisites You'll need the following items to launch any DB System. l The public key, in OpenSSH format, from the key pair that you plan to use for connecting to the DB System via SSH. A sample public key, abbreviated for readability, is shown below. ssh-rsa AAAAB3NzaC1yc2EAAAABJQAA....lo/gKMLVM2xzc1xJr/Hc26biw3TXWGEakrK1OQ== rsa-key-20160304 For more information, see Managing Key Pairs on Linux Instances. l l l 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 the Networking Service. See the additional requirements below. 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. 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 Reserved IP Addresses. If you plan to back up your DB System to the Object Storage Service, the VCN must have an enabled Internet Gateway and a corresponding route rule for it. For more information, see Backing Up to the Object Storage Service and Managing Internet Gateways. Oracle Bare Metal Cloud Services User Guide 188 CHAPTER 6 Database Service l l 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 done before or after you launch the DB System. For more information, see Managing Security Lists. 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. 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. You can use the dbcli command line interface to create additional databases and set these options as needed. l Console Enabled: False l Create Container Database: True for version 12.1.0.2 databases. False for version 11.2.0.4 databases. 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 l Database Territory: AMERICA l l Database Unique Name: The user-specified database name and a system-generated suffix, for example, dbtst_phx1cs. 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. Using the Console To launch a DB System 1. Open the Console, click Database, choose your Compartment, and then click Launch DB System. Oracle Bare Metal Cloud Services User Guide 189 CHAPTER 6 Database Service 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 Name A friendly, display name for the DB System. The name doesn't need to be unique. An Oracle Cloud Identifier (OCID) will uniquely identify the DB System. Availability Domain The Availability Domain in which the DB System resides. Oracle Bare Metal Cloud Services User Guide 190 CHAPTER 6 Database Service 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. l l l l l l BM.HighIO1.36: Provides a 1-node DB System (one bare metal server), with up to 36 CPU cores, 512 GB memory, and four 3.2 TB locally attached NVMe drives (12.8 TB total) to the DB System. 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. BM.RACLocalStorage1.72: Provides a 2-node RAC DB System (two bare metal servers), with up to 36 CPU cores on each node (72 total per cluster), 512 GB memory, direct attached shared storage with twenty 1.2 TB SSD drives (24 TB total). 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. 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. Exadata.Full1.336: Provides an 8-node Exadata DB System with 88 enabled CPU cores, with up to 248 additional CPU cores, 720 GB RAM per node, 1152 TB raw storage, 336 TB of usable storage, and unlimited I/O. This shape supports only the Enterprise Edition - Extreme Performance. 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 Number of Nodes Displayed only if you selected a multi-node shape. Indicates the number nodes in the cluster. Oracle Bare Metal Cloud Services User Guide 191 CHAPTER 6 Database Service Option Description Oracle Database Software Edition The database edition supported by the DB System. You can mix supported database versions on the DB System, but not editions. (The database edition cannot be changed and applies to all the databases in this DB System.) CPU Core Count The number of CPU cores for the DB System. The text below the field indicates the acceptable values, based on the shape you selected. For a multi-node DB System, the core count is evenly divided across the nodes. You can increase the CPU cores to accommodate increased demand after you launch a DB System. See Database Service Known Issues for a core count issue that affects Exadata DB Systems. SSH Public Key The public key portion of the key pair you want to use for SSH 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 Percentage The percentage (40% or 80%) assigned to DATA storage (user data and database files). The remaining percentage is assigned to RECO storage (database redo logs, archive logs, and recovery manager backups). Disk Redundancy The type of redundancy configured for the DB System. Normal is 2-way mirroring, recommended for test and development systems. High is 3-way mirroring, recommended for production systems. Network Information Virtual Cloud Network Compartment The compartment containing the network in which to launch the DB System. Virtual Cloud Network The VCN in which to launch the DB System. Oracle Bare Metal Cloud Services User Guide 192 CHAPTER 6 Database Service Option Description Subnet Compartment The compartment containing a subnet within the cloud network to 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.132.0/22 or 192.168.136.0/21. This restriction applies to both the client subnet and backup subnet. For 1- and 2-node RAC DB Systems: 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 Subnet For Exadata DB Systems only. The subnet to use for the backup network , which is typically used to transport backup information to and from the Oracle Bare Metal Cloud Object Storage Service, and for Data Guard replication. Do not use a subnet that overlaps with 192.168.132.0/22 or 192.168.136.0/21. This restriction applies to both the client subnet and backup subnet. If you plan to back up databases to the Object Storage Service, see the network prerequisites in Backing Up an Exadata Database. Hostname Prefix Your choice of host name for the DB System. The host name must 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. Oracle Bare Metal Cloud Services User Guide 193 CHAPTER 6 Database Service Option Description Host Domain Name The domain name for the DB System. If the selected subnet uses the Oracleprovided 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 the Object Storage Service, 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 Domain URL Combines the host and domain names to display the fully qualified domain name (FQDN) for the database. The maximum length is 64 characters. Database Information 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. Database Version The version of the initial database created on the DB System when it 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 Admin Password A strong password for SYS, SYSTEM, 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 -. Oracle Bare Metal Cloud Services User Guide 194 CHAPTER 6 Database Service Option Description Confirm Database Admin Password The same as above. Database Workload Select the workload type that best suits your application. 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 Set The character set for the database. The default is AL32UTF8. National Character Set The national character set for the database. The default is AL16UTF16. 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. To check the status of a 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 Oracle Bare Metal Cloud Services User Guide 195 CHAPTER 6 Database Service system is not ready to use yet. l l l l l l 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. Starting: Yellow icon. The DB System is being powered on by the start or reboot action in the Console or API. Stopping: Yellow icon. The DB System is being powered off by the stop or reboot action in the Console or API. Stopped: Yellow icon. The DB System was powered off by the stop action in the Console or API. Terminating: Gray icon. The DB System is being deleted by the terminate action in the Console or API. Terminated: Gray icon. The DB System has been deleted and is no longer available. 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. To start, stop, or reboot a DB System 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. 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. 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. Oracle Bare Metal Cloud Services User Guide 196 CHAPTER 6 Database Service Resource Billing 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 a 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. 1. Open the Console, click Database, and then choose your Compartment. 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. To terminate a 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 will be lost when the system is terminated. Oracle recommends that you back up any data in the DB System prior to terminating it. 1. Open the Console, click Database, and then choose your Compartment. A list of DB Systems is displayed. 2. For the DB System you want to terminate, click the Actions icon ( ) and then click Terminate. 3. Confirm when prompted. The DB System's icon indicates Terminating. Oracle Bare Metal Cloud Services User Guide 197 CHAPTER 6 Database Service At this point, you cannot connect to the system and any open connections will be terminated. 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. Use these API operations to manage DB System components. DB Systems: l GetDbSystem l LaunchDbSystem l ListDbSystems l TerminateDbSystem Database homes: l GetDbHomes l ListDbHomes Databases: l GetDatabase l ListDatabases 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 Oracle Bare Metal Cloud Services User Guide 198 CHAPTER 6 Database Service 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 Bare Metal Cloud Services 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. 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 the Networking Service, 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 l The full path to the file that contains the private key associated with the public key used when the DB System was launched. 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 Oracle Bare Metal Cloud Services User Guide 199 CHAPTER 6 Database Service (with no VPN). You can find the IP addresses in the Oracle Bare Metal Cloud ServicesConsole 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. 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 Connection type: SSH 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. 5. Click Open to start the session. Oracle Bare Metal Cloud Services User Guide 200 CHAPTER 6 Database Service To access a database after you connect 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. [root@ed1db01 ]# . oraenv ORACLE_SID = [root] ? +ASM1 The Oracle base has been set to /u01/app/grid 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. Oracle Bare Metal Cloud Services User Guide 201 CHAPTER 6 Database Service [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 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 Bare Metal Cloud Services User Guide 202 CHAPTER 6 Database Service [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 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.) 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. Connecting to a Database on a 1-Node DB System 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 l l Username: sys as sysdba Password: The Database Admin Password that was specified in the Launch DB System dialog in the Console. 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_ Oracle Bare Metal Cloud Services User Guide 203 CHAPTER 6 Database Service 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 System 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))) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>) ) ) 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 = (SERVER = DEDICATED) (SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>) ) ) Oracle Bare Metal Cloud Services User Guide 204 CHAPTER 6 Database Service 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 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. 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)) (ADDRESS = (PROTOCOL = TCP)(HOST = <publicIP2>)(PORT = 1521)) ) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>) ) ) Troubleshooting Connection Issues The following issues might occur when connecting to a DB System or database. ORA-28365: Wallet 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 ORA28365: 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. Oracle Bare Metal Cloud Services User Guide 205 CHAPTER 6 Database Service SSH Access Stops Working 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. For information about setting up an Enterprise Manager console to monitor your databases, see Monitoring a Database. Updating a DB System Review the following information before you begin updating a DB System. Bash Profile Updates Do not add any interactive commands such as oraenv to the .bash_profile file for the grid or oracle users. Adding interactive commands can prevent Database Service operations from functioning properly. Essential Firewall Rules 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 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. 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 will allow non-root users to modify the system's boot volume. OS Updates For customers with Oracle Linux Premier Support, Oracle recommends that you register with the Unbreakable Linux Network (ULN) and use the ULN Yum repositories and Oracle Ksplice to apply updates, including Oracle Bare Metal Cloud Services User Guide 206 CHAPTER 6 Database Service OS security updates. For more information, see Ksplice and About Ksplice Uptrack. For customers without Oracle Linux Premier Support, DB Systems include the Oracle Yum repository files, but all channels are disabled. You can enable specific channels, for example, public_ol6_latest, and then use the Oracle Yum security plug-in to apply OS security updates. For more information, see Downloading the Oracle Public Yum Repository Files and Installing and Using the Yum Security Plugin. Important! l l l l Do not remove packages from a DB System. Oracle recommends that you test any updates thoroughly before updating a production system. The image used to launch a DB System is updated regularly with the necessary patches, but after you launch a DB System, you are responsible for applying the required OS security updates published through the Oracle public Yum server. The DB System's VCN must be configured with an Internet Gateway to apply updates. For information about applying Oracle database patches to a 1-node DB System, see Patching a DB System. OS Kernel Updates A DB System boots from a network drive, which requires additional actions when you update the OS kernel. For more information, see OS Kernel Updates. 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 Oracle Bare Metal Cloud Services User Guide 207 CHAPTER 6 Database Service 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 l l 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. 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. 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 ORA28374: 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. 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 2-node RAC DB Systems or Exadata DB Systems. 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 Bare Metal Cloud Object Storage Service. You'll use the dbcli commands to Oracle Bare Metal Cloud Services User Guide 208 CHAPTER 6 Database Service configure credentials for the service, and then download and apply patches to some or all of the components in your system. (For information about operating system updates, see OS Updates.) Prerequisites l l l 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 Service does not leave the cloud and never reaches the public internet. For more information, see Managing Internet Gateways. 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 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 Bare Metal Cloud ServicesConsole on the Database page. For creating the Object Storage Service credentials configuration, you'll need an RSA key pair in PEM format (minimum 2048 bits), the fingerprint of the public key, your tenancy's OCID and user name's OCID, and the public key uploaded in the Console. For more information, see Required Keys and OCIDs. Create a User for Patching Consider creating an Oracle Bare Metal Cloud Services user with minimal or no permissions in a tenancy, and then provide that user's and tenancy's OCIDs when configuring the Object Storage Service credentials configuration. The patching user doesn't require any additional permissions in the cloud to download patches from Object Storage Service. To update the CLI with the latest commands Update the CLI to ensure you have the latest patching commands (older DB Systems might not include them). 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). Oracle Bare Metal Cloud Services User Guide 209 CHAPTER 6 Database Service login as: opc [opc@dbsys ~]$ sudo su - 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 10:19:34 AM PST dbcli patching January 18, 2017 Success Next, configure your credentials for the Object Storage Service if you have not done so already. To configure the Object Storage Service credentials 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). Oracle Bare Metal Cloud Services User Guide 210 CHAPTER 6 Database Service login as: opc [opc@dbsys ~]$ sudo su - 3. Collect the items listed in Prerequisites and create a credentials configuration by using the dbcli createbmccredential command. The --passPhrase option is required if you assigned a passphrase to your private key. (The example below uses the longer version of the command options and shows them on new lines to make it easier to read.) [root@dbsys ~]# dbcli create-bmccredential --credentialsType patch --name patch1 --tenantOcid ocidv1:tenancy:oc1:phx:1458318978360:aaaaaaaak7j2pjfwrnskt4f3ll2p3jkpra --userOcid ocid1.user.oc1..aaaaaaaalhdxviuxqi7xevqsksccl6e3okgld9uf6raskcioq4x2z7watsfa --fingerPrint 60:9e:56:26:4b:dd:46:dc:8c:a8:05:6d:9f:0a:30:d2 --privateKey /root/.ssh/privkey --passPhrase mypass { "jobId" : "f8c80510-b717-4ee2-a47e-cd380480b28b", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "December 26, 2016 22:46:38 PM PST", "resourceList" : [ ], "description" : "BMC Credentials Creation", "updatedTime" : "December 26, 2016 22:46:38 PM PST" } If the command fails with the error: Failed to connect to the object store. Please provide valid details, verify that you've provided the correct information in the command. Note the job ID above. 4. Wait for the job to complete successfully. Check the job output by using the dbcli describe-job command with the job ID. [root@dbsys ~]# # dbcli describe-job -i f8c80510-b717-4ee2-a47e-cd380480b28b 5. After the job completes successfully, you can use the dbcli list-bmccredentials. The command output should indicate a status of Configured. Oracle Bare Metal Cloud Services User Guide 211 CHAPTER 6 Database Service [root@dbsys ~]# # dbcli list-bmccredentials ID Name Type End Point ---------- -------------------- Status ---------------------------------------- --------------------------------------------------- ---------f1a8741c-b0c4-4jhf-239b-ab2a81jhfde4 patch1 https://objectstorage.us-phoenix-1.oraclecloud.com Patching Configured To check for installed and available patches 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 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 the Object Storage Service by using the dbcli describelatestpatch command. Oracle Bare Metal Cloud Services User Guide 212 CHAPTER 6 Database Service [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 To patch server components You can patch the Grid Infrastructure (GI) and storage management kit (OAK) server components. 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 3. Update the server components by using the dbcli update-server command. [root@dbsys ~]# dbcli update-server { "jobId" : "9a02d111-e902-4e94-bc6b-9b820ddf6ed8", "status" : "Created", "reports" : [ ], "createTimestamp" : "January 19, 2017 09:37:11 AM PST", "resourceList" : [ ], "description" : "Server Patching", "updatedTime" : "January 19, 2017 09:37:11 AM PST" } Note the job ID above. 4. Check the job output by using the dbcli describe-job command with the job ID. Oracle Bare Metal Cloud Services User Guide 213 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-job -i 9a02d111-e902-4e94-bc6b-9b820ddf6ed8 Job details ---------------------------------------------------------------ID: Description: Status: Created: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8 Server Patching Running January 19, 2017 9:37:11 AM PST Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Create Patching Repository Directories 9:37:11 AM PST Download latest patch metadata 9:37:11 AM PST January 19, 2017 January 19, 2017 9:38:35 AM PST January 19, 2017 January 19, 2017 9:38:58 AM PST January 19, 2017 January 19, 2017 9:38:58 AM PST January 19, 2017 January 19, 2017 9:42:06 AM PST January 19, 2017 January 19, 2017 10:02:32 AM PST January 19, 2017 Success Updating GiHome version 10:02:38 AM PST January 19, 2017 9:37:11 AM PST Success Apply clusterware patch 10:02:32 AM PST January 19, 2017 Success Patch conflict check 9:42:06 AM PST January 19, 2017 9:37:11 AM PST Success Opatch updation 9:38:58 AM PST January 19, 2017 Success oda-hw-mgmt upgrade 9:38:58 AM PST January 19, 2017 9:37:11 AM PST Success Update Patching Repository 9:38:35 AM PST January 19, 2017 Success Update System version 9:37:11 AM PST January 19, 2017 9:37:11 AM PST Success Success 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 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_ip_address> Oracle Bare Metal Cloud Services User Guide 214 CHAPTER 6 Database Service 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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "January 20, 2017 10:08:48 AM PST", "resourceList" : [ ], "description" : "DB Home Patching: Home Id is 52e2e799-946a-4339-964b-c203dee35328", "updatedTime" : "January 20, 2017 10:08:48 AM PST" } Note the job ID above. 5. Check the job output by using the dbcli describe-job command with the job ID. Oracle Bare Metal Cloud Services User Guide 215 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-job -i 31b38f67-f993-4f2e-b7eb-5bccda9901ae Job details ---------------------------------------------------------------ID: Description: Status: Created: 31b38f67-f993-4f2e-b7eb-5bccda9901ae DB Home Patching: Home Id is b727bf80-c99e-4846-ac1f-28a81a725df6 Success January 20, 2017 10:08:48 AM PST Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Create Patching Repository Directories 10:08:49 AM PST Download latest patch metadata 10:08:49 AM PST January 20, 2017 January 20, 2017 10:08:49 AM PST January 20, 2017 January 20, 2017 10:08:58 AM PST January 20, 2017 January 20, 2017 10:08:58 AM PST January 20, 2017 January 20, 2017 10:12:00 AM PST January 20, 2017 Success db upgrade 10:22:17 AM PST January 20, 2017 10:08:49 AM PST Success Patch conflict check 10:12:00 AM PST January 20, 2017 Success Opatch updation 10:08:58 AM PST January 20, 2017 10:08:49 AM PST Success Update Patching Repository 10:08:58 AM PST January 20, 2017 Success Update System version 10:08:49 AM PST January 20, 2017 10:08:49 AM PST Success Success 6. Verify that the database home components were updated successfully by using the dbcli describecomponent command. The Available Version column should indicate update-to-date. Monitoring a Database This topic explains how to set up an: l Enterprise Manager Express console to monitor a version 12.1.0.2 database l Enterprise Manager Database Control console to monitor a version 11.2.0.4 database Oracle Bare Metal Cloud Services User Guide 216 CHAPTER 6 Database Service 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 Service Policy Some of the procedures below require permission to create or update security lists. For more information about security list policies, see Managing Security Lists. Monitoring a Database with Enterprise Manager Express On Exadata DB Systems, the Enterprise Manager Database Express (EM Express) console is automatically enabled for a 12.1.0.2 and 12.2.01 databases, but you will still need to open ports for the console in iptables and a security list, as described later in this topic. On 1- and 2-node RAC DB Systems, by default, the EM Express console is not enabled on version 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. 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. Oracle Bare Metal Cloud Services User Guide 217 CHAPTER 6 Database Service 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. 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] ? The Oracle base has been set to /u01/app/grid 2. Get the location of the wallet directory, shown in red below in the command output. Oracle Bare Metal Cloud Services User Guide 218 CHAPTER 6 Database Service [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 -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. 8. Open the console's port as described in Opening Ports on the DB System. 9. Update the security list for the console's port as described in Updating the Security List for the DB System. 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 Oracle Bare Metal Cloud Services User Guide 219 CHAPTER 6 Database Service 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 Bare Metal Cloud ServicesConsole on the Database page. 2. A login page is displayed and you can log in with any valid database credentials. The Database Home page is displayed. Oracle Bare Metal Cloud Services User Guide 220 CHAPTER 6 Database Service To learn more about EM Express, see Introduction to Oracle Enterprise Manager Database Express. 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. Oracle Bare Metal Cloud Services User Guide 221 CHAPTER 6 Database Service 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. -----------------------------------------------------------------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. 4. Update the security list for the console's port as described in Updating the Security List 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 Oracle Bare Metal Cloud Services User Guide 222 CHAPTER 6 Database Service 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 Bare Metal Cloud ServicesConsole 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 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. l SSH to node2 and reply yes to the authentication prompt. Oracle Bare Metal Cloud Services User Guide 223 CHAPTER 6 Database Service 6. On node2, create the known_hosts file by doing the following: l SSH to node2 and reply yes to the authentication prompt. l SSH to node1 and reply yes to the authentication prompt. 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 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. Oracle Bare Metal Cloud Services User Guide 224 CHAPTER 6 Database Service $ 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 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 : Number of XML files pending upload : 22.25 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. 2. Update the security list for the console's port as described in Updating the Security List for the DB System. Opening Ports on the DB System Open the following ports as needed on the DB System: Oracle Bare Metal Cloud Services User Guide 225 CHAPTER 6 Database Service l l l 6200 - For Oracle Notification Service (ONS). 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. 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. For important information about critical firewall rules, see Essential Firewall Rules. To open ports on the DB System 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_ip_address> 2. Log in as opc and then sudo to the root user. login as: opc [opc@dbsys ~]$ sudo su - 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. Oracle Bare Metal Cloud Services User Guide 226 CHAPTER 6 Database Service 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=0.0.0.0/0, protocol=TCP, and port=<port number or port range>. For detailed information about creating or updating a security list, see Managing 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 Service (Recommended) l Backups are stored in the Oracle Bare Metal Cloud Services Object Storage Service. l Durability: High l Availability: High l Back Up and Recovery Rate: Medium l Advantages: High durability, performance, and availability. 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. Oracle Bare Metal Cloud Services User Guide 227 CHAPTER 6 Database Service 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 Bare Metal Cloud Services 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 the Object Storage Service l Backing Up to Local Storage Using the CLI Backing Up to the Object Storage Service Note This topic is not applicable to Exadata DB Systems. See Backing Up an Exadata Database. This topic explains how to use Recovery Manager (RMAN) to back up a DB System database to the Object Storage Service. The service is a secure, scalable, on-demand storage solution in Oracle Bare Metal Cloud Services. To back up to the service you'll need to create an Object Storage Service bucket for the backups, generate a password for the service, install the Oracle Database Cloud Backup Module, and then configure RMAN to send backups to the service. The backup module is a system backup to tape (SBT) interface that’s tightly integrated with RMAN, so you can use familiar RMAN commands to perform backup and recovery operations. You'll notice Swift mentioned in the Console and in the endpoint URL for the service. That's because the backup module is typically used to back up to the Oracle Database Backup Cloud Service, which is an OpenStack Swift object store. Oracle Bare Metal Cloud Services User Guide 228 CHAPTER 6 Database Service CLI Alternative Instead of installing the backup module and using RMAN for backups on a 1-node DB System, you can use the dbcli command line interface to back up to the Object Storage Service. For more information, see Objectstoreswift Commands. The commands are not available for a 2node RAC DB System. Prerequisites You'll need the following: l l l l l A DB System and a database to back up. For more information, see Managing Bare Metal DB Systems. 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 Service does not leave the cloud and never reaches the public internet. For more information, see Managing Internet Gateways. An existing Object Storage Service bucket to use as the backup destination. You can use the Console or the Object Storage Service API to create the bucket. For more information, see Managing Buckets. A Swift password generated by Oracle Bare Metal Cloud Services. You can use the Console or the IAM Service API to generate the password. For more information, see Working with Swift Passwords. The user name (specified when you install and use the backup module) must have tenancy-level access to the Object Storage Service. 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 the Object Storage Service. 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. Installing the Backup Module on the DB System 1. SSH to the DB System, log in as opc, and sudo to the oracle user. ssh -i <SSH key used when launching the DB System> opc@<DB System IP address or hostname> login as: opc sudo su - oracle Oracle Bare Metal Cloud Services User Guide 229 CHAPTER 6 Database Service 2. Change to the directory that contains the backup module opc_install.jar file. cd /opt/oracle/oak/pkgrepos/orapkgs/oss/161007/ Note that 161007 is the version number of the JAR file and subject to change. 3. Use the following command syntax to install the backup module. java -jar opc_install.jar -opcId <user_id> -opcPass '<Swift_password>' -container <bucket_ name> -walletDir ~/hsbtwallet/ -libDir ~/lib/ -configfile ~/config -host https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/<tenant> The parameters are: Parameter Description -opcId The user name for the Oracle Bare Metal Cloud Services user account, for example: -opcId [email protected] 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. You can also specify the user name in single quotes. This might be necessary if the name contains special characters, for example: -opcId '[email protected]' Make sure to use straight single quotes and not slanted apostrophes. -opcPass The Swift password generated by using the Console or IAM Service API, in single quotes, for example: -opcPass '1cnk!d0++ptETd&C;tHR' Make sure to use straight single quotes and not slanted apostrophes. For more information, see Managing User Credentials. This is not the password for the Oracle Bare Metal Cloud Services user. -container The name of an existing bucket in the Object Storage Service to use as the backup destination, for example: -container DBBackups Oracle Bare Metal Cloud Services User Guide 230 CHAPTER 6 Database Service Parameter Description -walletDir The directory where the install tool will create an Oracle Wallet containing the Oracle Bare Metal Cloud Services user name and Swift password. -walletDir ~/hsbtwallet creates the wallet in the current user (oracle) home directory. -libDir The directory where the SBT library is stored. The directory must already exist before you run the command. This parameter causes the latest SBT library to be downloaded. -libDir ~/lib/ downloads the libopc.so file to the current user's home directory, for example, /home/oracle/lib/libopc.so. -configfile The name of the initialization parameter file that will be created by the install tool. This file will be referenced by your RMAN jobs. -configfile ~/config creates the file in the current user's home directory, for example, /home/oracle/config. -host The endpoint URL to which backups are to be sent: https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/<tenant> where <tenant> is the lowercase tenant name (even if it contains uppercase characters) that you specify when signing in to the Console, for example: https://swiftobjectstorage.us-phoenix1.oraclecloud.com/v1/companyabc Do not add a slash after the tenant name. Configuring RMAN This section describes how to configure RMAN to use the bucket as the default backup destination. The following assumes you are still logged in to the DB System. 1. On the DB System, set the ORACLE_HOME and ORACLE_SID environment variables using the oraenv utility. . oraenv 2. Connect to the database using RMAN. rman target / 3. Configure RMAN to use the SBT device and point to the config file that was created when you installed the backup module. A sample command for a version 12 database is shown here. Oracle Bare Metal Cloud Services User Guide 231 CHAPTER 6 Database Service RMAN> CONFIGURE CHANNEL DEVICE TYPE 'SBT_TAPE' PARMS 'SBT_LIBRARY=/home/oracle/lib/libopc.so, SBT_PARMS=(OPC_PFILE=/home/oracle/config)'; 4. Configure RMAN to use SBT_TAPE by default. The following sample enables the controlfile and spfile autobackup to SBT_TAPE and configures encryption (recommended). There are other settings that may apply to your installation such as compression, number of backup and recovery channels to use, backup retention policy, archived log deletion policy, and more. See the Oracle Backup and Recovery documentation for your version of Oracle for more information on choosing the appropriate settings. RMAN> CONFIGURE DEFAULT DEVICE TYPE TO SBT_TAPE; RMAN> CONFIGURE BACKUP OPTIMIZATION ON; RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON; RMAN> CONFIGURE CONTROLFILE AUTOBACKUP FORMAT FOR DEVICE TYPE SBT_TAPE TO '%F'; RMAN> CONFIGURE ENCRYPTION FOR DATABASE ON; Once the RMAN configuration is complete, you can use the same RMAN commands that you regularly use for tape backups. Backing up the Database This section provides examples of commonly used backup commands. 1. Set the database encryption: RMAN> SET ENCRYPTION IDENTIFIED BY "password" ONLY; Note that this setting is not permanent; you must set it for each new RMAN session. 2. Back up the database and archivelogs. Below are some example commands. See the Oracle Backup and Recovery documentation for your version of Oracle for more information about choosing a back up procedure that meets your needs. Be sure to back up regularly to minimize potential data loss and always include a copy of the spfile and controlfile. Note that the example below uses multi-section incremental backups, which is a feature introduced in 12c. When using 11g, omit the section size clause. RMAN> BACKUP INCREMENTAL LEVEL 0 SECTION SIZE 512M DATABASE PLUS ARCHIVELOG; RMAN> BACKUP INCREMENTAL LEVEL 1 SECTION SIZE 512M DATABASE PLUS ARCHIVELOG; RMAN> BACKUP INCREMENTAL LEVEL 1 CUMULATIVE SECTION SIZE 512M DATABASE PLUS ARCHIVELOG; 3. Backup archivelogs frequently to minimize potential data loss, and keep multiple backup copies as a precaution. RMAN> BACKUP ARCHIVELOG ALL NOT BACKED UP 2 TIMES; Oracle Bare Metal Cloud Services User Guide 232 CHAPTER 6 Database Service When the backup job completes, you can display the backup files in your bucket in the Console on the Storage page, by selecting Object Storage. What Next? See Recovering a Database from the Object Storage Service. Backing Up to Local Storage Using the CLI Note This topic is not applicable to Exadata DB Systems. See Backing Up an Exadata Database. This topic explains how to back up to the local Fast Recovery Area on a DB System by using the dbcli command line interface that's available on 1- and 2-node DB Systems. 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 Storage You'll use the dbcli commands to create a backup configuration; associate the backup configuration with the database; initiate the back up; and then review the backup job. 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - Oracle Bare Metal Cloud Services User Guide 233 CHAPTER 6 Database Service 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", "status" : "Success", "message" : null, "reports" : [ { "taskId" : "TaskParallel_471", "taskName" : "persisting backup config metadata", "taskResult" : "Success", "startTime" : 1467774813141, "endTime" : 1467774813207, "status" : "Success", "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. Oracle Bare Metal Cloud Services User Guide 234 CHAPTER 6 Database Service [root@dbsys ~]# dbcli list-databases ID DB Name Storage DB Version CDB Class Shape Status ---------------------------------------- ---------- ---------- ---------- -------- -------- --------- ---------71ec8335-113a-46e3-b81f-235f4d1b6fde ACFS prod 12.1.0.2 true OLTP odb1 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 to 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467775842977, "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 back up is performed immediately. The following example creates a backup of the specified database. Oracle Bare Metal Cloud Services User Guide 235 CHAPTER 6 Database Service [root@dbsys ~]# dbcli create-backup --databaseid 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. Oracle Bare Metal Cloud Services User Guide 236 CHAPTER 6 Database Service [root@dbsys ~]# dbcli create-backupreport --dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde -reporttype summary { "jobId" : "65ce79fe-4ef4-4d7d-8020-e56a5390026d", "status" : "Created", "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" } [root@dbsys ~]# dbcli list-backupreports ID Name createTime ReportType DbId updatedTime ---------------------------------------- -------------------- ---------- --------------------------------------- ----------------------------------- ----------------------------------c0e0a16a-485f-4176-ab73-5b30ccf5c560 b81f-235f4d1b6fde July 6, 2016 11:04:05 PM UTC summary 71ec8335-113a-46e3- 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. What Next? See Recovering a Database from a CLI Backup. Oracle Bare Metal Cloud Services User Guide 237 CHAPTER 6 Database Service Recovering a Database For information on restoring a database on a 1- or 2-node RAC DB System, see the following topics: l Recovering a Database from the Object Storage Service l Recovering a Database from a CLI Backup l Recovering a Database from the OPC Object Store Recovering a Database from the Object Storage Service Note This topic is not applicable to Exadata DB Systems. This topic explains how to recover a Recovery Manager (RMAN) backup stored in the Object Storage Service. The service is a secure, scalable, on-demand storage solution in Oracle Bare Metal Cloud Services. For information on using Object Storage as a backup destination, see Backing Up to the Object Storage Service. Prerequisites You'll need the following: l l A new DB System to restore the database to (see assumptions below). For more information, see Managing Bare Metal DB Systems. 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: l 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. The original DB System is lost and all that remains is the latest RMAN backup. Any data not included in the most recent backup will be lost. Oracle Bare Metal Cloud Services User Guide 238 CHAPTER 6 Database Service l l l The Oracle Wallet and/or encryption keys used by the original database at the time of the last backup is available. 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. An RMAN catalog will not be used during the restore. Setting Up Storage on the DB System 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 3. You can use an existing database home or create a new one for the restore. Use the dbcli list-dbhomes command to list the database homes. [root@dbsys ~]# dbcli list-dbhomes ID Name DB Version Home Location ---------------------------------------- -------------------- ---------- -------------------------------------------2e743050-b41d-4283-988f-f33d7b082bda OraDB12102_home1 12.1.0.2 /u01/app/oracle/product/12.1.0.2/dbhome_1 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. Oracle Bare Metal Cloud Services User Guide 239 CHAPTER 6 Database Service 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 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 the Object Storage Service. 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.us-phoenix1.oraclecloud.com/v1/<tenant_name> For example: curl -u '[email protected]:1cnk!d0++ptETd&C;tHR' -v https://swiftobjectstorage.us-phoenix1.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.us-phoenix1.oraclecloud.com/v1/<tenant_name>/<bucket_name>?prefix=sbt_catalog/c- For example: curl -u '[email protected]:1cnk!d0++ptETd&C;tHR' -v https://swiftobjectstorage.us-phoenix1.oraclecloud.com/v1/mycompany/dbbackups/?prefix=sbt_catalog/c- In the sample output below, 1508405000 is the DBID. Oracle Bare Metal Cloud Services User Guide 240 CHAPTER 6 Database Service { "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 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. Oracle Bare Metal Cloud Services User Guide 241 CHAPTER 6 Database Service 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 Fixed Size Variable Size Database Buffers Redo Buffers 2147483648 bytes 2944952 bytes 847249480 bytes 1254096896 bytes 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. 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. Oracle Bare Metal Cloud Services User Guide 242 CHAPTER 6 Database Service 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; 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. Oracle Bare Metal Cloud Services User Guide 243 CHAPTER 6 Database Service 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 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 12.1 or 11.2. Prerequisites l l The backup must have been created with the dbcli create-backup command. 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 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). Oracle Bare Metal Cloud Services User Guide 244 CHAPTER 6 Database Service login as: opc [opc@dbsys ~]$ sudo su - 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. [root@dbsys ~]# dbcli list-databases ID DB Name Storage DB Version CDB Class Shape Status ---------------------------------------- ---------- ---------- ---------- -------- -------- --------- ---------5a3e980b-e0fe-4909-9628-fcefe43b3326 ACFS prod 12.1.0.2 true OLTP odb1 Configured 4. Initiate the recovery by using the dbcli create-recovery command and specifying the 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 --databaseid 5a3e980b-e0fe-4909-9628-fcefe43b3326 -recoverytype Latest { "jobId" : "c9f81228-2ce9-43b4-88f6-b260d398cf06", "status" : "Created", "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 --databaseid 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. Oracle Bare Metal Cloud Services User Guide 245 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-job -i c9f81228-2ce9-43b4-88f6-b260d398cf06 Job details ---------------------------------------------------------------ID: Description: c9f81228-2ce9-43b4-88f6-b260d398cf06 Create recovery for database id :5a3e980b-e0fe-4909-9628- fcefe43b3326 Status: Created: Success August 8, 2016 6:20:47 PM UTC Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Database recovery validation 6:21:07 PM UTC Database recovery 6:22:34 PM UTC August 8, 2016 6:22:34 PM UTC August 8, 2016 August 8, 2016 6:22:35 PM UTC August 8, 2016 August 8, 2016 6:22:44 PM UTC August 8, 2016 August 8, 2016 6:23:41 PM UTC August 8, 2016 Success Persist Recovery Metadata 6:23:41 PM UTC August 8, 2016 Success Restart database 6:23:41 PM UTC August 8, 2016 6:21:07 PM UTC Success Open database 6:22:44 PM UTC August 8, 2016 Success enable block change tracking 6:22:35 PM UTC August 8, 2016 6:20:47 PM UTC Success Success 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 OPC Object Store Note This topic is not applicable to Exadata DB Systems. Oracle Bare Metal Cloud Services User Guide 246 CHAPTER 6 Database Service This topic explains how to recover a database using a backup created by the Oracle Database Backup Module and stored in the Oracle Public Cloud Object Store. The following terms are used throughout this topic: l Source database: The database backup in the Oracle Object Store. l Target database: The new database on a DB System in the Oracle Bare Metal Cloud Services. Prerequisites You'll need the following: l The service name, identity name, container, user name, and password for Oracle Public Cloud Object Store. l The backup password if password-based encryption was used when backing up to Oracle Object store. 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. Setting Up Storage on the DB System 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 3. 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 tdetest database. [root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS Oracle Bare Metal Cloud Services User Guide 247 CHAPTER 6 Database Service Note When migrating a version 11.2 database, ACFS storage must be specified. 4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the 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) Created: August 24, 2016 5:25:38 PM UTC 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. 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. Oracle Bare Metal Cloud Services User Guide 248 CHAPTER 6 Database Service 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: 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: Oracle Bare Metal Cloud Services User Guide 249 CHAPTER 6 Database Service $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"; 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 version 11g, use the orapki command: orapki wallet create -wallet wallet_location -auto_login [-pwd password] Installing the Oracle Database Backup Module The backup module JAR file is included on the DB System but you need to install it. Oracle Bare Metal Cloud Services User Guide 250 CHAPTER 6 Database Service 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. Setting 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> 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 Spfile 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. Oracle Bare Metal Cloud Services User Guide 251 CHAPTER 6 Database Service 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 { ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; SET DBID=$dbID; RESTORE SPFILE FROM AUTOBACKUP; shutdown immediate; EOF Setting 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 Oracle Bare Metal Cloud Services User Guide 252 CHAPTER 6 Database Service 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 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. Oracle Bare Metal Cloud Services User Guide 253 CHAPTER 6 Database Service rman target / <<EOF spool log to "`date +%Y%m%d_%H%M%S_%N`_restore_database_preview.log" set echo on run { ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; ALLOCATE CHANNEL c2 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; ALLOCATE CHANNEL c3 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; restore database validate header preview; } 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 { ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; ALLOCATE CHANNEL c2 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; ALLOCATE CHANNEL c3 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_ LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)'; 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: Oracle Bare Metal Cloud Services User Guide 254 CHAPTER 6 Database Service 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; 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. 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. 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. Oracle Bare Metal Cloud Services User Guide 255 CHAPTER 6 Database Service 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 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 rollback 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 System 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: Oracle Bare Metal Cloud Services User Guide 256 CHAPTER 6 Database Service [root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename tdetest -syspassword Password for SYS: { "jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2", "status" : "Created", "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 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. 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: [root@dbsys ~]# dbcli list-dbhomes ID Home Location Name DB Version 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 Oracle Bare Metal Cloud Services User Guide 257 CHAPTER 6 Database Service 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 Unique Patch ID: : applied on Fri Sep 02 15:28:17 UTC 2016 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> 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> connect / as sysdba SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql exit Oracle Bare Metal Cloud Services User Guide 258 CHAPTER 6 Database Service 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: l l l l l External tables: If the source database uses external tables, back up that data and migrate it to the target host. Directories: Customize the default directories as needed for the restored database. Database links: Make sure all the required TNS entries are updated in the tnsnames.ora file in ORACLE_HOME. Email and URLs: Make sure any email addresses and URLs used in the database are still accessible from the DB System. 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. Verify that patches have been applied to all PDBs if the restored database contains CDB and PDBs. Oracle Bare Metal Cloud Services User Guide 259 CHAPTER 6 Database Service Using Oracle Data Guard Note This topic is not applicable to 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 12.2, 12.1, or 11.2. Oracle Data Guard ensures high availability, data protection, and disaster recovery for enterprise data. This topic explains how to set up Data Guard with Fast-Start Failover (FSFO) in Oracle Bare Metal Cloud Services. 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. 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. Oracle Bare Metal Cloud Services User Guide 260 CHAPTER 6 Database Service 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 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", "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 Home Location DB Version Status ---------------------------------------- -------------------- --------------------------------------- --------------------------------------------- ---------2efe7af7-0b70-4e9b-ba8b-71f11c6fe287 23144544) 33ae99fe-5413-4392-88da-997f3cd24c0f 23054359) OraDB12102_home1 /u01/app/oracle/product/12.1.0.2/dbhome_1 OraDB11204_home1 /u01/app/oracle/product/11.2.0.4/dbhome_1 Oracle Bare Metal Cloud Services User Guide 12.1.0.2.160719 (23739960, Configured 11.2.0.4.160719 (23054319, Configured 261 CHAPTER 6 Database Service Creating a Primary DB System If you don't already have a primary DB System, create one as described in Managing Bare Metal DB Systems. The DB System will include an initial database. You can create additional databases by using the dbcli createdatabase command available on the DB System. 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 createdatabase 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 Bare Metal 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. 2. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_ip_address> 3. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the root user's profile, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 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 parameter. This parameter creates only the database storage structure and starts the database in nomount mode (no other database files are Oracle Bare Metal Cloud Services User Guide 262 CHAPTER 6 Database Service 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 version 12c 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 Static 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/12.1.0.2/grid/network/admin/listener.ora and add the following content to it. The first static listener shown below is optional. The second DGMGRL static listener is optional for database version 12.1.0.2, but required for version 11.2.0.4. Oracle Bare Metal Cloud Services User Guide 263 CHAPTER 6 Database Service 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 Service 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 = (SERVER = DEDICATED) (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). Oracle Bare Metal Cloud Services User Guide 264 CHAPTER 6 Database Service Configuring Primary Database Parameters 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; 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. Oracle Bare Metal Cloud Services User Guide 265 CHAPTER 6 Database Service 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 ... 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. Oracle Bare Metal Cloud Services User Guide 266 CHAPTER 6 Database Service 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. 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 Static 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/12.1.0.2/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 version 12.1.0.2, but required for version 11.2.0.4. Oracle Bare Metal Cloud Services User Guide 267 CHAPTER 6 Database Service 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 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. Oracle Bare Metal Cloud Services User Guide 268 CHAPTER 6 Database Service $ 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 Service 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. Oracle Bare Metal Cloud Services User Guide 269 CHAPTER 6 Database Service <Primary db_unique_name> = (DESCRIPTION = (SDU=65535) (ADDRESS = (PROTOCOL = TCP)(HOST = <primary_server>.<domain>) (PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (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 = (SERVER = DEDICATED) (SERVICE_NAME = <standby db_unique_name>.<db_domain>) ) ) Copying the TDE Wallets to the Standby System 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> Setting Up the Standby System Configuration As the oracle user, create the following directory for database version 11.2.0.4. This step is optional for 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. Oracle Bare Metal Cloud Services User Guide 270 CHAPTER 6 Database Service Creating a Temporary Password File As the oracle user, create a temporary password file. [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 Standby 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. Oracle Bare Metal Cloud Services User Guide 271 CHAPTER 6 Database Service 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 db_unique_name>.dat' set dispatchers ='(PROTOCOL=TCP) (SERVICE=<Standby db_unique_name>XDB)' set instance_name='<Standby db_unique_name>' ; } Oracle Bare Metal Cloud Services User Guide 272 CHAPTER 6 Database Service 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 Service Oracle recommends creating a database service for the standby database by using srvctl. For ACFS storage layout. Oracle Bare Metal Cloud Services User Guide 273 CHAPTER 6 Database Service 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' ; 2. Stop and remove the existing database service. Oracle Bare Metal Cloud Services User Guide 274 CHAPTER 6 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> SINGLE -o $ORACLE_HOME -c -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. $ srvctl start database -d <standby db_unique_name> 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. $ srvctl start database -d <standby db_unique_name> 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. 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; Oracle Bare Metal Cloud Services User Guide 275 CHAPTER 6 Database Service 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. 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. Oracle Bare Metal Cloud Services User Guide 276 CHAPTER 6 Database Service 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). 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 Oracle Bare Metal Cloud Services User Guide 277 CHAPTER 6 Database Service 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. 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 This topic is not applicable to Exadata DB Systems. The dbcli 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 CLI to perform tasks such as creating Oracle database homes and databases. Oracle Bare Metal Cloud Services User Guide 278 CHAPTER 6 Database Service Renamed CLIs 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, use the: l cliadm update-dbcli command to get the dbcli CLI l dbcli update-server command to get the dbadmcli CLI 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 l The dbcli commands must be run as the root user. The CLI is in the following directory: /opt/oracle/dcs/bin/ The directory is included in the path for the root user's environment. l 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/ 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. Syntax The dbcli commands use the following syntax: dbcli command [parameters] where: Oracle Bare Metal Cloud Services User Guide 279 CHAPTER 6 Database Service l l l l command is a verb-object combination such as create-database. 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. 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. 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 dbcli CLI and other commands are updated to support new features. You can use the following command to update the CLI. cliadm update-dbcli Use the cliadm update-dbcli command to update the dbcli CLI with the latest new and updated commands. Note The cliadm update-dbcli command is not available on 2-node RAC DB Systems. Syntax cliadm update-dbcli [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command updates the dbcli CLI: Oracle Bare Metal Cloud Services User Guide 280 CHAPTER 6 Database Service [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" } 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. Syntax dbcli create-backup -i <db_id> [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -databaseid The database ID to back up. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. Example The following command creates a backup of the specified database. Oracle Bare Metal Cloud Services User Guide 281 CHAPTER 6 Database Service [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 list-backupconfigs l dbcli describe-backupconfig l dbcli update-backupconfig l dbcli delete-backupconfig 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] Oracle Bare Metal Cloud Services User Guide 282 CHAPTER 6 Database Service Parameters Parameter Full Name Description -c --container The name of an existing bucket in the Oracle Bare Metal Cloud Object Storage Service. You can use the Console or the Object Storage Service API to create the bucket. For more information, see Managing Buckets. You must also specify --backupdestination objectstore and the -objectstoreswiftId parameter. -d -backupdestination The backup destination as one of the following (these values are not case sensitive): DISK - The local Fast Recovery Area. OBJECTSTORE - The Oracle Bare Metal Cloud 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. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -n --name The name of the backup configuration. Oracle Bare Metal Cloud Services User Guide 283 CHAPTER 6 Database Service Parameter Full Name Description -o -objectstoreswiftId The ID of the object store that contains the endpoint and credentials for the Oracle Bare Metal Cloud Object Storage Service. Use the dbcli listobjectstoreswifts command to get the object store ID. Use the dbcli createobjectstoreswift command to create an object store. You must also specify --backupdestination 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. Example The following command creates a backup configuration named dbbkcfg1: Oracle Bare Metal Cloud Services User Guide 284 CHAPTER 6 Database Service [root@dbsys ~]# dbcli create-backupconfig -d Disk -w 7 -n dbbkcfg1 { "jobId" : "4e0e6011-db53-4142-82ef-eb561658a0a9", "status" : "Success", "message" : null, "reports" : [ { "taskId" : "TaskParallel_919", "taskName" : "persisting backup config metadata", "taskResult" : "Success", "startTime" : "November 18, 2016 20:21:25 PM UTC", "endTime" : "November 18, 2016 20:21:25 PM UTC", "status" : "Success", "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", "updatedTime" : "November 18, 2016 20:21:25 PM UTC" } 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command lists a backup configuration: Oracle Bare Metal Cloud Services User Guide 285 CHAPTER 6 Database Service [root@dbsys ~]# dbcli list-backupconfigs ID Name RecoveryWindow BackupDestination CreateTime ---------------------------------------- -------------------- ------------------ ----------------- ---------------------------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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -backupconfigid The backup configuration ID. Use the dbcli list-backupconfigs command to get the ID. -j --json (Optional) Displays JSON output. Example 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 Oracle Bare Metal Cloud Services User Guide 286 CHAPTER 6 Database Service dbcli update-backupconfig Use the dbcli update-backupconfig command to update an existing backup configuration. Syntax dbcli update-backupconfig -i <id> -w <n> -d {DISK|OBJECTSTORE|NONE} -c <bucket> -o <object_store_ swift_id> [-h] [-j] Parameters Parameter Full Name Description -c --container The name of an existing bucket in the Oracle Bare Metal Cloud Object Storage Service. You can use the Console or the Object Storage Service API to create the bucket. For more information, see Managing Buckets. You must also specify --backupdestination objectstore and the -objectstoreswiftId parameter. -d -backupdestination The new backup destination, (these values are not case sensitive): DISK - The local Fast Recovery Area. OBJECTSTORE - The Oracle Bare Metal Cloud 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. -h --help (Optional) Displays help for using the command. -i --backupconfigid The ID of the backup configuration to update. Use the dbcli listbackupconfigs command to get the ID. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 287 CHAPTER 6 Database Service Parameter Full Name Description -o -objectstoreswiftId The ID of the object store that contains the endpoint and credentials for the Oracle Bare Metal Cloud Object Storage Service. Use the dbcli listobjectstoreswifts command to get the object store ID. Use the dbcli createobjectstoreswift command to create an object store. You must also specify --backupdestination 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. Example 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1468153731699, "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] Oracle Bare Metal Cloud Services User Guide 288 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --id The backup configuration ID to delete. Use the dbcli list-backupconfigs command to get the ID. -j --json (Optional) Displays JSON output. Example 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] Oracle Bare Metal Cloud Services User Guide 289 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -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. -j --json (Optional) Displays JSON output. -w -reporttype The level of detail in the back up report as either summary or detailed. Example 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --dbid (Optional) Displays the backup reports for the specified database ID. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. Example The following command lists the back up reports: [root@dbsys ~]# dbcli list-backupreports Oracle Bare Metal Cloud Services User Guide 290 CHAPTER 6 Database Service 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 Parameter Full Name Description -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. -h --help (Optional) Displays help for using the command. -i --reportid The ID of a specific backup report to delete. Use the dbcli listbackupreports command to get the ID. -j --json (Optional) Displays JSON output. -n -numofday (Optional) Deletes backup reports that are older than the specified number of days, for the specified database. Requires the --dbid parameter. Example The following command delete the specified backup report: [root@dbsys ~]# dbcli delete-backupreport -i a892ced1-be04-436e-8e82-bf0a89109164 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] Oracle Bare Metal Cloud Services User Guide 291 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --id The ID of the backup report. Use the dbcli list-backupreports command to get the ID. -j --json (Optional) Displays JSON output. Example 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 Bare Metal Cloud Object Storage Service. For more information, see Patching a DB System. l dbcli create-bmccredential l dbcli list-bmccredentials l dbcli describe-bmccredential l dbcli delete-bmccredential l dbcli update-bmccredential Oracle Bare Metal Cloud Services User Guide 292 CHAPTER 6 Database Service 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] Oracle Bare Metal Cloud Services User Guide 293 CHAPTER 6 Database Service Parameters Parame ter Full Name Description -c -credentialsT ype The type of Object Storage Service credentials configuration to 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 -objectStore Url (Optional) The Object Storage Service endpoint URL. Omit this parameter when --credentialsType PATCHING is specified. The following URL is assumed: https://objectstorage.us-phoenix-1.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 -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -n --name (Optional) The name for the new credentials configuration. The name is useful for tracking the configuration. -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. Oracle Bare Metal Cloud Services User Guide 294 CHAPTER 6 Database Service Parame ter Full Name Description -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..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr 4h25vqstifsfdsq -u --userOcid The user name OCID for your Oracle Bare Metal Cloud Services 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:aaaaaaaari4zv5jhf3ohezt7w7c5dgc2 wa Example 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "December 26, 2016 22:46:38 PM PST", "resourceList" : [ ], "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] Oracle Bare Metal Cloud Services User Guide 295 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command lists the credentials configurations on the DB System: [root@dbsys ~]# dbcli list-bmccredentials ID Name Type End Point ---------- --------------------------- Patching https://objectstorage.us- Patching https://objectstorage.us- Status ---------------------------------------- -------------------------------------------- ---------f19d7c8b-d0d5-4jhf-852b-eb2a81cb7ce5 phoenix-1.oraclecloud.com patch1 Configured f1a8741c-b0c4-4jhf-239b-ab2a81jhfde4 phoenix-1.oraclecloud.com patch2 Configured 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --id The ID for the credentials configuration. Use the dbcli list-bmccredentials command to get the ID. -j --json (Optional) Displays JSON output. Example The following command displays details about the specified credentials configuration: Oracle Bare Metal Cloud Services User Guide 296 CHAPTER 6 Database Service [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 Created: January 9, 2017 1:19:11 AM PST UpdatedTime: January 9, 2017 1:41:46 AM PST dbcli delete-bmccredential Use the dbcli delete-bmccredential command to delete a credentials configuration. Syntax dbcli delete-bmccredential -i <credentials_id> [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --id The ID for the credentials configuration. Use the dbcli list-bmccredentials command to get the ID. -j --json (Optional) Displays JSON output. Example 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. Oracle Bare Metal Cloud Services User Guide 297 CHAPTER 6 Database Service 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] Parameters Parameter Full Name Description -c -credentialsType The type of Object Storage Service credentials configuration (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. -i --id The ID for the credentials configuration. Use the dbcli list-bmccredentials command to get the ID. -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 -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -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. Example The following command updates a credentials configuration: Oracle Bare Metal Cloud Services User Guide 298 CHAPTER 6 Database Service [root@dbsys ~]# dbcli update-bmccredential -c OTHER -i 6f921b29-61b6-56f4-889a-ce9270621956 { "jobId" : "6e95a69e-cf73-4e51-a444-c7e4b9631c27", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "January 19, 2017 12:01:10 PM PST", "resourceList" : [ ], "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 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 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 the Object Storage Service 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 Service credentials configuration. Use the dbcli createbmccredential 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-component [-s <server_group>] [-d <db_group>] [-h] [-j] Oracle Bare Metal Cloud Services User Guide 299 CHAPTER 6 Database Service Parameters Parameter Full Name Description -d -dbhomes (Optional) Lists the installed and available patch versions for only the database home components. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -s --server (Optional) Lists the installed and available patch versions for only the server components. Example 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 Cpucore Commands The following commands are available to manage CPU cores: l dbcli list-cpucores l dbcli describe-cpucore l dbcli update-cpucore dbcli list-cpucores Use the dbcli list-cpucores command to display the CPU core update history on the local node. Oracle Bare Metal Cloud Services User Guide 300 CHAPTER 6 Database Service Syntax dbcli list-cpucores [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays the CPU core update history on the local node: [root@dbsys ~]# dbcli list-cpucores Node Cores Modified Job Status ----- ------ ------------------------------ --------------0 36 July 3, 2016 4:19:17 AM UTC Configured 0 18 July 3, 2016 5:19:35 AM UTC Configured dbcli describe-cpucore Use the dbcli describe-cpucore command to list the current core count on the local node. Syntax dbcli describe-cpucore [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays the current CPU core count on the local node: Oracle Bare Metal Cloud Services User Guide 301 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-cpucore Node Cores Modified Job Status ----- ------ ------------------------------ --------------0 18 July 3, 2016 5:19:35 AM UTC Configured dbcli update-cpucore Use the dbcli update-cpucore command to enable additional CPU cores. Note To enable cores on a 2-node RAC DB System, run the dbcli updatecpucore command on each node. For example, to enable 20 cores on the DB System, run dbcli update-cpucore -c 10 on each node. If the nodes have a different number of cores enabled, you will be billed for twice the higher number. Syntax dbcli update-cpucore -c <n> [-h] [-j] Parameters Parameter Full Name Description -c --cores The number of CPU cores to enable. The number must be a multiple of 2, up to 36. The maximum number of cores available for the DB System is determined by the shape that was used when launching the system. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command enables 24 cores: Oracle Bare Metal Cloud Services User Guide 302 CHAPTER 6 Database Service [root@dbsys ~]# dbcli update-cpucore -c 24 { "jobId" : "cf9ba39c-fd5d-47b0-b60d-8338e8b87e0d", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467954691791, "description" : "CPU cores service update", "updatedTime" : 1467954691791 } 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. 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. Oracle Bare Metal Cloud Services User Guide 303 CHAPTER 6 Database Service 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> config_id> -m -s <db_shape> -cl {OLTP|DSS|IMDB} -r {ACFS|ASM} -n <db_name> -u <unique_name> -bi <bkup_ -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 Parameter Full Name Description -bi --backupconfigid Defines the backup configuration identifier for future use. Use the dbcli list-backupconfigs command to get the ID. -c --cdb -no-c --no-cdb (Optional) Indicates whether to create a Container Database. If omitted, a Container Database is not created. -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. Oracle Bare Metal Cloud Services User Guide 304 CHAPTER 6 Database Service Parameter Full Name Description -co --dbconsole -no-co --no-dbconsole (Optional) Indicates whether the Database Console is enabled. If omitted, the console is not enabled. This parameter is not available for a version 11.2.0.4 database on a 2node 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. -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. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 305 CHAPTER 6 Database Service Parameter Full Name Description -m --adminpassword A strong password for SYS, SYSTEM, 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 -. -hm 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. -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. Oracle Bare Metal Cloud Services User Guide 306 CHAPTER 6 Database Service Parameter Full Name Description -u -databaseUniqueName Defines a unique name for the database to ensure 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. -v --version Defines the database version as either 11.2.0.4 or 12.1.0.2. The default version is 12.1.0.2. -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 l l l l l l 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.) When --dbhomeid is not provided, the dbcli create-database command will create a new Oracle Database Home. 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. Oracle Database 12.1 is supported on both Oracle Automatic Storage Management (ASM) and Oracle ASM Cluster file system (ACFS). The default is Oracle ACFS. Oracle Database 11.2 is supported on Oracle ACFS. 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. Online logs are stored in the /u03/app/db user/redo/ directory. The Oracle Fast Recovery Area (FRA) is located in the /u03/app/db user/fast_recovery_area directory. Examples To create database and be prompted for the password interactively: Oracle Bare Metal Cloud Services User Guide 307 CHAPTER 6 Database Service [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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "August 08, 2016 03:54:03 AM EDT", "description" : "Database service creation with db name: hrdb", "updatedTime" : "August 08, 2016 03:54:03 AM EDT" } 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "August 08, 2016 03:59:22 AM EDT", "description" : "Database service creation with db name: crmdb", "updatedTime" : "August 08, 2016 03:59:22 AM EDT" } dbcli delete-database Use the dbcli delete-database command to delete a database. Syntax dbcli delete-database -i <db_id> [-j] [-h] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --dbid Identifies the database ID to display. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 308 CHAPTER 6 Database Service Example 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --dbid Identifies the database ID to display. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. Example The following command displays information for a database named b727bf80-c99e-4846-ac1f-28a81a725df6: [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] Oracle Bare Metal Cloud Services User Guide 309 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays a list of databases: [root@dbsys ~]# dbcli list-databases ID Storage DB Name DB Version CDB Class Shape Status ---------------------------------------- ---------- -------------------- ---------- -------- ----------------- ---------80ad855a-5145-4f8f-a08f-406c5e4684ff ACFS 6f4e36ae-120b-4436-b0bf-d0c4aef9f7c9 ACFS true OLTP odb2 db11tsta 11.2.0.4 false OLTP odb1 db11tstb 11.2.0.4 false OLTP odb1 pdbtst 12.1.0.2 true OLTP odb1 Configured cce096c7-737b-447a-baa1-f4c2a330c030 ACFS 12.1.0.2 Configured d8e31790-84e6-479c-beb0-ef97207091a2 ACFS dbst Configured Configured The following command displays the JSON output for a database: Oracle Bare Metal Cloud Services User Guide 310 CHAPTER 6 Database Service [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", "updatedTime" : "November 09, 2016 18:00:47 PM UTC" } dbcli register-database Use the dbcli register-database command to register a database that has been migrated to Oracle Bare Metal Cloud Services. The command registers the database to the dcs-agent so it can be managed by the dcsagent stack. Oracle Bare Metal Cloud Services User Guide 311 CHAPTER 6 Database Service Note The dbcli register-database command is not available on 2-node RAC DB Systems. Syntax dbcli register-database -bi <bkup_config_id> -c {OLTP|DSS|IMDB} SI -o <db_host_name> [-co|-no-co] -s {odb1|odb2|...} -t -sn <service_name> -p [-h] [-j] Parameters Parameter Full Name Description -bi -backupconfigid Defines the backup configuration ID. Use the dbcli list-backupconfigs command to get the ID. -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 -no-co --no-dbconsole (Optional) Indicates whether the Database Console is enabled or not. If omitted, the console is not enabled. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -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. Oracle Bare Metal Cloud Services User Guide 312 CHAPTER 6 Database Service Parameter Full Name Description -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. Example 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: { "jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "August 08, 2016 05:55:49 AM EDT", "description" : "Database service registration with db service name: crmdb.example.com", "updatedTime" : "August 08, 2016 05:55:49 AM EDT" } 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] Oracle Bare Metal Cloud Services User Guide 313 CHAPTER 6 Database Service Parameters Parameter Full Name Description -bi -backupconfigid Defines the backup configuration ID. Use the dbcli list-backupconfigs command to get the ID. -h --help (Optional) Displays help for using the command. -i --dbid Defines the database ID to be updated. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. Example 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-46e3b81f-235f4d1b6fde { "jobId" : "2b104028-a0a4-4855-b32a-b97a37f5f9c5", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467775842977, "description" : "update database id:71ec8335-113a-46e3-b81f-235f4d1b6fde", "updatedTime" : 1467775842978 } Dbhome Commands The following commands are available to manage database homes: l dbcli create-dbhome l dbcli describe-dbhome l dbcli delete-dbhome l dbcli list-dbhomes l dbcli update-dbhome Oracle Bare Metal Cloud Services User Guide 314 CHAPTER 6 Database Service 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 Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -v --version Defines the Database Home Version. Specify one of the supported versions: 11.2.0.4 or 12.1.0.2. Example The following command creates an Oracle Database Home version 12.1.0.2: [root@dbsys ~]# dbcli create-dbhome -v 12.1.0.2 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -dbhomeid Identifies the database home ID. Use the dbcli list-dbhomes command to get the ID. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 315 CHAPTER 6 Database Service Example 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] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -dbhomeid Identifies the database home ID to be deleted. Use the dbcli list-dbhomes command to get the ID. -j --json (Optional) Displays JSON output. dbcli list-dbhomes Use the dbcli list-dbhomes command to display a list of Oracle Home directories. Syntax dbcli list-dbhomes [-h] [-j] Oracle Bare Metal Cloud Services User Guide 316 CHAPTER 6 Database Service Parameter Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays a list of Oracle Home directories. [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 dbcli update-dbhome 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 CLI and then retry the command. 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -dbhomeid The ID of the database home. Use the dbcli list-dbhomes command to get the ID. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 317 CHAPTER 6 Database Service Example 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "January 19, 2017 10:03:21 AM PST", "resourceList" : [ ], "description" : "DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6", "updatedTime" : "January 19, 2017 10:03:21 AM PST" } # dbcli describe-job -i 493e703b-46ef-4a3f-909d-bbd123469bea Job details ---------------------------------------------------------------ID: Description: Status: Created: 493e703b-46ef-4a3f-909d-bbd123469bea DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6 Running January 19, 2017 10:03:21 AM PST Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Create Patching Repository Directories 10:03:21 AM PST Download latest patch metadata 10:03:21 AM PST January 19, 2017 10:03:21 AM PST January 19, 2017 January 19, 2017 10:03:21 AM PST January 19, 2017 January 19, 2017 10:03:31 AM PST January 19, 2017 January 19, 2017 10:03:31 AM PST January 19, 2017 Success Patch conflict check 10:03:31 AM PST January 19, 2017 Success Opatch updation 10:03:31 AM PST January 19, 2017 10:03:21 AM PST Success Update Patching Repository 10:03:31 AM PST January 19, 2017 Success Update System version 10:03:21 AM PST January 19, 2017 10:03:21 AM PST Success Running Oracle Bare Metal Cloud Services User Guide 318 CHAPTER 6 Database Service 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 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays details about database storage: [root@dbsys ~]# dbcli list-dbstorages ID Type DBUnique Name Status ---------------------------------------- ------ -------------------- ---------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] Oracle Bare Metal Cloud Services User Guide 319 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --id Defines the database storage ID. Use the dbcli list-dbstorages command to get the database storage ID. -j --json (Optional) Displays JSON output. Example 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 RECO Location: /u03/app/oracle/fast_recovery_area/ REDO Location: /u03/app/oracle/redo/ State: ResourceState(status=Configured) 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] Oracle Bare Metal Cloud Services User Guide 320 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -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 -databaseUniqueName (Optional) Defines the unique name for the database. The default is the database name specified in --dbname. Example 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", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467952215102, "description" : "Database storage service creation with db name: testdb", "updatedTime" : 1467952215103 } 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. Oracle Bare Metal Cloud Services User Guide 321 CHAPTER 6 Database Service Syntax dbcli delete-dbstorage -i <dbstorageID> [-h] [-j] Parameters Parameter Parameter Description -h --help (Optional) Displays help for using the command. -i --id The database storage ID to delete. Use the dbcli list-dbstorages command to get the database storage ID. -j --json (Optional) Displays JSON output. Example 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" : [ ], "createTimestamp" : 1467952336843, "description" : "Database storage service deletion with id: f444dd87-86c9-4969-a72c-fb2026e7384b", "updatedTime" : 1467952336856 } 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] Oracle Bare Metal Cloud Services User Guide 322 CHAPTER 6 Database Service Parameters Parameter Full Name Description -d --details Displays additional information about the DB System, including dcs CLI and agent version information. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays detailed information about the DB System: Oracle Bare Metal Cloud Services User Guide 323 CHAPTER 6 Database Service [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 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 Oracle Bare Metal Cloud Services User Guide 324 CHAPTER 6 Database Service 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. Syntax dbcli describe-job -i <job_id> [-h] [-j] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --jobid Identifies the job. Use the dbcli list-jobs command to get the jobid. -j --json (Optional) Displays JSON output. Example The following command displays details about the specified job ID: Oracle Bare Metal Cloud Services User Guide 325 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-job -i 74731897-fb6b-4379-9a37-246912025c17 Job details ---------------------------------------------------------------ID: Description: Status: Created: 74731897-fb6b-4379-9a37-246912025c17 Backup service creation with db name: dbtst Success November 18, 2016 8:33:04 PM UTC Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Backup Validations 8:33:13 PM UTC validate recovery window 8:33:17 PM UTC November 18, 2016 November 18, 2016 8:33:17 PM UTC November 18, 2016 November 18, 2016 8:33:23 PM UTC November 18, 2016 November 18, 2016 8:34:22 PM UTC November 18, 2016 Success Backup metadata 8:34:22 PM UTC November 18, 2016 8:33:13 PM UTC Success Database Backup 8:34:22 PM UTC November 18, 2016 Success Db cross check 8:33:23 PM UTC November 18, 2016 8:33:04 PM UTC Success 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 326 CHAPTER 6 Database Service Example 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 9157cc78-b487-4ee9-9f46-0159f10236e4 November 17, 2016 7:19:59 PM UTC 013c408d-37ca-4f58-a053-02d4efdc42d0 406c5e4684ff Success Backup service creation with db name: dbtst November 18, 2016 8:33:04 PM UTC 40a227b1-8c47-46b9-a116-48cc1476fc12 Success update database id:80ad855a-5145-4f8f-a08f-406c5e4684ff November 18, 2016 8:32:16 PM UTC 74731897-fb6b-4379-9a37-246912025c17 Success create backup config:myBackupConfig November 18, 2016 8:28:14 PM UTC 921a54e3-c359-4aea-9efc-6ae7346cb0c2 Success Database service creation with db name: jhfpdb Success Creating a report for database 80ad855a-5145-4f8f-a08f- November 18, 2016 8:41:39 PM UTC Success Latestpatch Command dbcli describe-latestpatch 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 CLI and then retry the command. Note The dbcli describe-latestpatch command is not available on 2node RAC DB Systems. Patching 2-node systems from the Object Storage Service is not supported. Use the dbcli describe-latestpatch command show the latest patches applicable to the DB System and available in Oracle Bare Metal Cloud Object Storage Service. Oracle Bare Metal Cloud Services User Guide 327 CHAPTER 6 Database Service This command requires a valid Object Storage Service credentials configuration. Use the dbcli createbmccredential 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] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example 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 Oracle Bare Metal Cloud Services User Guide 328 CHAPTER 6 Database Service 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] Parameters Parameter Full Name Description -H -dbHomeId Defines the database home ID. Use the dbcli list-dbhomes command to get the dbhomeid. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example 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. Oracle Bare Metal Cloud Services User Guide 329 CHAPTER 6 Database Service 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] Parameters Paramete r Full Name Description -c --client Indicates that the specified data encryption or data integrity configuration is for the client. (--client and --server are mutually exclusive.) -e -encryptionAlgorithm s Defines the algorithm to be used for encryption. Specify either AES256, AES192, or AES128. -H --dbHomeId Defines the database home ID. Use the dbcli list-dbhomes command to get the dbHomeId. -h --help (Optional) Displays help for using the command. -i --integrityAlgorithms Defines the algorithm to be used for integrity. Specify either SHA1, SHA512, SHA384, or SHA256. For Oracle Database 11g, the only accepted value is SHA1. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 330 CHAPTER 6 Database Service Paramete r Full Name Description -s --server Indicates that the specified data encryption or data integrity configuration is for the server. (--client and --server are mutually exclusive.) -t --connectionType Specifies how Oracle Net Services data encryption or data 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.htm#DBSEG10 47. Example 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 Bare Metal Cloud Object Storage Service by using the dbcli create-backup command, but first you'll need to: 1. Create an object store on the DB System, which contains the endpoint and credentials to access the Object Storage Service, 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 Oracle Bare Metal Cloud Services User Guide 331 CHAPTER 6 Database Service 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 2-node RAC DB Systems. 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.us-phoenix-1.oraclecloud.com/v1 -p [-h] [-j] Parameters Parameter Full Name Description -e --endpoint The following endpoint URL. https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1 -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -n --name The name for the object store to be created. Oracle Bare Metal Cloud Services User Guide 332 CHAPTER 6 Database Service Parameter Full Name Description -p -swiftpassword The Swift password that you generated by using the Console or IAM Service API. For information about generating a Swift password, see Managing User Credentials. This is not the password for the Oracle Bare Metal Cloud Services user. Specify -p (with no password) to be prompted. Specify -hp "<password> " in quotes to provide the password in the command. -t --tenantname The case-sensitive tenant name that you specify when signing in to the Console. -u --username The user name for the Oracle Bare Metal Cloud Services user account, for example: -u [email protected] 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 Service. 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 the Object Storage Service. 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. Example The following command creates an object store and prompts for the Swift password: Oracle Bare Metal Cloud Services User Guide 333 CHAPTER 6 Database Service [root@dbsys ~]# dbcli create-objectstoreswift -n r2swift -t CompanyABC -u [email protected] -e https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1 -p Password for Swift: { "jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7", "status" : "Created", "message" : "Create object store swift", "reports" : [ ], "createTimestamp" : "January 19, 2017 11:11:33 AM PST", "resourceList" : [ { "resourceId" : "8a0fe039-f5d4-426a-8707-256c612b3a30", "resourceType" : "ObjectStoreSwift", "jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7", "updatedTime" : "January 19, 2017 11:11:33 AM PST" } ], "description" : "create object store:biyanr2swift", "updatedTime" : "January 19, 2017 11:11:33 AM PST" } 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i -objectstoreswiftid The object store ID. Use the dbcli list-objectstoreswifts command to get the ID. -j --json (Optional) Displays JSON output. Example The following command displays details about an object store: Oracle Bare Metal Cloud Services User Guide 334 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-objectstoreswift -i 910e9e2d-25b4-49b4-b88e-ff0332f7df87 Object Store details ---------------------------------------------------------------ID: 910e9e2d-25b4-49b4-b88e-ff0332f7df87 Name: objstrswift15 UserName: [email protected] TenantName: CompanyABC endpoint URL: https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command lists the object stores on the DB System: [root@dbsys ~]# dbcli list-objectstoreswifts ID Name Url UserName TenantName createTime ---------------------------------------- -------------------- -------------------- -------------- -- ---- ---------------------------------------------------- ----------------------------------2915bc6a-6866-436a-a38c-32302c7c4d8b swiftobjstr1 [email protected] CompanyABC https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1 November 10, 2016 8:42:18 PM UTC 910e9e2d-25b4-49b4-b88e-ff0332f7df87 objstrswift15 [email protected] CompanyABC https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1 November 16, 2016 11:25:34 PM UTC Oracle Bare Metal Cloud Services User Guide 335 CHAPTER 6 Database Service Recovery Commands The following commands are available to initiate a database recovery and list recovery jobs: l dbcli create-recovery l dbcli list-recovery 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -i --databaseid Defines the ID of the database to recover. This ID is different from the DBID. Use the dbcli list-databases command to get the database ID. -j --json (Optional) Displays JSON output. -r -recoveryTimeStamp Defines the time for the end point of the recovery. The 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. Oracle Bare Metal Cloud Services User Guide 336 CHAPTER 6 Database Service Example 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", "status" : "Created", "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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays information about the recovery jobs: [root@dbsys ~]# dbcli list-recovery 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 Oracle Bare Metal Cloud Services User Guide 337 CHAPTER 6 Database Service 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] Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command displays backup schedules: Oracle Bare Metal Cloud Services User Guide 338 CHAPTER 6 Database Service [root@dbsys ~]# dbcli list-schedules ID Name Description CronExpression ---------------------------------------- ------------------------- ------------------------------------------------- -----------------------------fe46697b-128e-43b4-9f7a-8e4a5f16e88c metastore maintenance internal metastore maintenance database backup backup databases 0 0 0 1/1 * ? * 481856f9-2cdd-45f8-b0b0-11cc8c48970a 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 Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. -i --scheduleid The schedule ID. Use the dbcli list-schedules command to get the ID. Example The following command describes a backup schedule: Oracle Bare Metal Cloud Services User Guide 339 CHAPTER 6 Database Service [root@dbsys ~]# dbcli describe-schedule -i 481856f9-2cdd-45f8-b0b0-11cc8c48970a Job Schedule details ---------------------------------------------------------------ID: JobName: JobGroup: CronExpression: JobClass: 481856f9-2cdd-45f8-b0b0-11cc8c48970a database backup backups 0 9 13 1/1 * ? * 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] Parameters Parameter Full Name Description -d --disable Indicates whether the schedule is disabled or enabled. -e --enable -h --help (Optional) Displays help for using the command. -i --scheduleid The schedule ID. Use the dbcli list-schedules command to get the ID. -j --json (Optional) Displays JSON output. Oracle Bare Metal Cloud Services User Guide 340 CHAPTER 6 Database Service Parameter Full Name Description -t --description A description of the schedule. -x --cronExpression The cron expression, in single quotes, used by the schedule. Example 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] Parameters Parameter Full Name Description -e -executionid (Optional) An execution ID. -h --help (Optional) Displays help for using the command. -i -scheduleid (Optional) The schedule ID. Use the dbcli list-schedules command to get the ID. -j --json (Optional) Displays JSON output. Example The following command lists all the jobs executed for all schedules: Oracle Bare Metal Cloud Services User Guide 341 CHAPTER 6 Database Service [root@dbsys ~]# dbcli list-scheduledExecutions ID ScheduledId Status JobId Executed Time -------------------------------------- -------------------------------------- ------------------------------------- --------- ------------------------------23691445-9120-4a34-9bcd-dcbd382dc455 a5ef-ff04473d3a73 Executed 54071c4e-98db-41c8-92b6-b5f92ca11631 9939-0b404b62e8ce Executed 22fbd334-ebbd-40f4-af79-9eb2360cfb77 c7f32a6c-f835-45f8- September 5, 2016 8:52:00 PM UTC a7623340-ece7-4618-a7d9-8efb353378b4 b663fb73-e531-43bf- 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. Server Command dbcli update-server 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 CLI and then retry the command. 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 2-node RAC DB Systems. Syntax dbcli update-server [-h] [-j] Oracle Bare Metal Cloud Services User Guide 342 CHAPTER 6 Database Service Parameters Parameter Full Name Description -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following commands update the server and show the output from the update job: Oracle Bare Metal Cloud Services User Guide 343 CHAPTER 6 Database Service [root@dbsys ~]# dbcli update-server { "jobId" : "9a02d111-e902-4e94-bc6b-9b820ddf6ed8", "status" : "Created", "reports" : [ ], "createTimestamp" : "January 19, 2017 09:37:11 AM PST", "resourceList" : [ ], "description" : "Server Patching", "updatedTime" : "January 19, 2017 09:37:11 AM PST" } # dbcli describe-job -i 9a02d111-e902-4e94-bc6b-9b820ddf6ed8 Job details ---------------------------------------------------------------ID: Description: Status: Created: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8 Server Patching Running January 19, 2017 9:37:11 AM PST Message: Task Name Start Time End Time Status ---------------------------------------- ----------------------------------- ---------------------------------- ---------Create Patching Repository Directories AM PST Download latest patch metadata AM PST January 19, 2017 9:37:11 January 19, 2017 9:37:11 AM PST January 19, 2017 9:38:35 January 19, 2017 9:38:35 AM PST January 19, 2017 9:38:58 January 19, 2017 9:38:58 AM PST January 19, 2017 9:38:58 January 19, 2017 9:38:58 AM PST January 19, 2017 9:42:06 January 19, 2017 9:42:06 AM PST January 19, 2017 Success Patch conflict check AM PST January 19, 2017 9:37:11 AM PST Success Opatch updation AM PST January 19, 2017 9:37:11 Success oda-hw-mgmt upgrade AM PST January 19, 2017 9:37:11 AM PST Success Update Patching Repository AM PST January 19, 2017 9:37:11 Success Update System version AM PST January 19, 2017 9:37:11 AM PST Success Success apply clusterware patch 10:02:32 AM PST Success Oracle Bare Metal Cloud Services User Guide 344 CHAPTER 6 Database Service Updating GiHome version 10:02:38 AM PST January 19, 2017 10:02:32 AM PST January 19, 2017 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), or/and Container Databases (if -rootDatabase is specified). Syntax dbcli update-tdekey -i <db_id> -p -n <pdbname1,pdbname2> [-r|-no-r] -t <tag_name> [-h] [-j] Parameters Parameter Full Name Description -i --databaseId Defines the database ID for which the key is to be rotated. -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 -rootDatabase Indicates whether to rotate the key for the root database if it is a container database. -no-r --norootDatabase -t -tagName Defines the TagName used to backup the wallet. The default is OdaRotateKey. -h --help (Optional) Displays help for using the command. -j --json (Optional) Displays JSON output. Example The following command updates the key for pdb1 and pdb2 only: Oracle Bare Metal Cloud Services User Guide 345 CHAPTER 6 Database Service [root@dbsys ~]# dbcli update-tdekey -databaseId ee3eaab6-a45b-4e61-a218-c4ba665503d9 -p -n pdb1,pdb2 TDE Admin wallet password: { "jobId" : "08e5edb1-42e1-4d16-a47f-783c0afa4778", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467876407035, "description" : "TDE update", "updatedTime" : 1467876407035 } The following command updates pdb1, pdb2, and the container database: [root@dbsys ~]# dbcli update-tdekey -databaseId ee3eaab6-a45b-4e61-a218-c4ba665503d9 -p -n pdb1,pdb2 -r TDE Admin wallet password: { "jobId" : "c72385f0-cd81-42df-a8e8-3a1e7cab1278", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : 1467876433783, "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 l dbadmcli show disk l dbadmcli show diskgroup Oracle Bare Metal Cloud Services User Guide 346 CHAPTER 6 Database Service 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 Parameter Description -h (Optional) Displays help for using the command. --storage Collects all of the logs for any storage issues. Example [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. Note The dbadmcli power command is not available on 2-node RAC DB Systems. Oracle Bare Metal Cloud Services User Guide 347 CHAPTER 6 Database Service Syntax dbadmcli power {-on|-off} <name> [-h] Parameters Parameter Description -h (Optional) Displays help for using the command. 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> Parameters Parameter Description -h (Optional) Displays help for using the command. name Identifies a specific disk resource name. The resource name format is pd_[0..3]. For example, pd_01. Example [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. Oracle Bare Metal Cloud Services User Guide 348 CHAPTER 6 Database Service Syntax dbadmcli show controller <controller_id> [-h] Parameter Parameter Description controller_id The ID number of the controller. Use the dbadmcli show storage command to get the ID. -h (Optional) Displays help for using the command. 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] Parameters Parameter Description -all (Optional) Displays detailed information for the named disk. -h (Optional) Displays help for using the command. -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. Examples To display the status of all the disks on the system: Oracle Bare Metal Cloud Services User Guide 349 CHAPTER 6 Database Service [root@dbsys ~]# dbadmcli show disk NAME PATH TYPE STATE STATE_DETAILS pd_00 /dev/nvme2n1 NVD ONLINE Good pd_01 /dev/nvme3n1 NVD ONLINE Good pd_02 /dev/nvme1n1 NVD ONLINE Good pd_03 /dev/nvme0n1 NVD ONLINE Good To display the status of a disk named pd_00: Oracle Bare Metal Cloud Services User Guide 350 CHAPTER 6 Database Service [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| 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 Oracle Bare Metal Cloud Services User Guide 351 CHAPTER 6 Database Service 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 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] Oracle Bare Metal Cloud Services User Guide 352 CHAPTER 6 Database Service To display RECO configurations: dbadmcli show diskgroup [RECO] [-h] Parameters Parameter Description DATA (Optional) Displays the DATA diskgroup configurations. -h (Optional) Displays help for using the command. RECO (Optional) Displays the RECO diskgroup configurations. Examples 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] Oracle Bare Metal Cloud Services User Guide 353 CHAPTER 6 Database Service Parameter Parameter Description -h (Optional) Displays help for using the command. dbadmcli show fs Use the dbadmcli show fs command to display file system details. Syntax dbadmcli show fs [-h] Parameter Parameter Description -h (Optional) Displays help for using the command. 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 Parameter Description -errors (Optional) Shows storage errors. -h (Optional) Displays help for using the command. Example To display storage devices: Oracle Bare Metal Cloud Services User Guide 354 CHAPTER 6 Database Service [root@dbsys ~]# dbadmcli show storage ==== BEGIN STORAGE DUMP ======== Host Description: Oracle Corporation:ORACLE SERVER X5-2 Total number of controllers: 5 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 Pci Address = 25:00.0 Id = 1 Pci Slot = 12 Serial Num = S2LHNAAH505449 Vendor = Samsung Model = MS1PC2DD3ORA3.2T FwVers = KPYA8R3Q strId = nvme:27:00.00 Pci Address = 27:00.0 Id = 2 Pci Slot = 10 Serial Num = S2LHNAAH503573 Vendor = Samsung Model = MS1PC2DD3ORA3.2T FwVers = KPYA8R3Q strId = nvme:29:00.00 Pci Address = 29:00.0 Id = 3 Oracle Bare Metal Cloud Services User Guide 355 CHAPTER 6 Database Service Pci Slot = 11 Serial Num = S2LHNAAH503538 Vendor = Samsung Model = MS1PC2DD3ORA3.2T FwVers = KPYA8R3Q 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 /dev/nvme3n1 Samsung NVD 3200gb slot: 1 pci : /dev/nvme1n1 Samsung NVD 3200gb slot: 2 pci : 27 /dev/nvme0n1 Samsung NVD 3200gb slot: 3 pci : 25 2 ==== 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 Parameter Description name Defines the disk resource name. The resource name format is pd_[0..3]. -h (Optional) Displays help for using the command. Example 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: Oracle Bare Metal Cloud Services User Guide 356 CHAPTER 6 Database Service l l l Use the OLTP templates if your database workload is primarily online transaction processing (OLTP). Use the DSS templates if your database workload is primarily decision support (DSS) or data warehousing. 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 Sizing Templates Template CPU Cores SGA (GB) PGA (GB) Flash (GB) Processes Redo Log File Size (GB) Log 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 odb32 32 128 64 256 6400 4 64 odb36 36 128 64 256 7200 4 64 Oracle Bare Metal Cloud Services User Guide 357 CHAPTER 6 Database Service DSS Database Sizing Templates Template CPU Cores SGA (GB) PGA (GB) Processes Redo Log File Size (GB) Log Buffer (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 Oracle Bare Metal Cloud Services User Guide 358 CHAPTER 6 Database Service In-Memory Database Sizing Templates Template CPU Cores SGA (GB) PGA (GB) In-Memory (GB) Processes Redo Log Lile Size (GB) Log Buffer (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 Bare Metal Cloud 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, including the version, character set, and platform endian format of the source and target databases. Oracle Bare Metal Cloud Services User Guide 359 CHAPTER 6 Database Service 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 11g Release 2 version lower than 11.2.0.3 l Oracle Database 11g Release 2 version 11.2.0.3 or higher l Oracle Database 12c Release 1 version lower than 12.1.0.2 l Oracle Database 12c Release 1 version 12.1.0.2 or higher 2. For on-premises 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. Oracle Bare Metal Cloud Services User Guide 360 CHAPTER 6 Database Service The Database Service uses the Linux platform, which is little endian. 4. Database character set of your on-premises database and the Database Service database. Some migration methods require that the source and target databases use compatible database character sets. 5. Database version of the Database Service database you are migrating to l Oracle Database 11g Release 2 l Oracle Database 12c Release 1 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 Migration Connectivity Options You have several connectivity options when migrating your on-premises databases to the Oracle Bare Metal Cloud Services. The options are listed below in order of preference. 1. Fast Connect: 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 customerpremise 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 Managing IPSec VPNs. 3. Internet Gateway: Provides a path for network traffic between your VCN and the internet. For more information, see Managing Internet Gateways. Oracle Bare Metal Cloud Services User Guide 361 CHAPTER 6 Database Service Migration Methods Many methods exist to migrate Oracle databases to the 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 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 database 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. Oracle Bare Metal Cloud Services User Guide 362 CHAPTER 6 Database Service l l l l Data Pump Conventional Export/Import 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. Data Pump Transportable Tablespace 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. For the steps this method entails, see Data Pump Transportable Tablespace. RMAN Transportable Tablespace with Data Pump 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. For the steps this method entails, see RMAN Transportable Tablespace with Data Pump. RMAN CONVERT Transportable Tablespace with Data Pump This method can be used 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 crossplatform 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. The applicability of some of the migration methods depends on the on-premises database’s database 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 onpremises 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. l Data Pump Conventional Export/Import This method can be used regardless of the endian format and database character set of the on-premises database. Oracle Bare Metal Cloud Services User Guide 363 CHAPTER 6 Database Service For the steps this method entails, see Data Pump Conventional Export/Import. l l l l Data Pump Transportable Tablespace 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. For the steps this method entails, see Data Pump Transportable Tablespace. RMAN Transportable Tablespace with Data Pump 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. For the steps this method entails, see RMAN Transportable Tablespace with Data Pump. RMAN CONVERT Transportable Tablespace with Data Pump This method can be used 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 crossplatform 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. Data Pump Full Transportable 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 database are compatible. 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 Database Service using several different methods. The applicability of some of the migration methods depends on the on-premises database’s database 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. Oracle Bare Metal Cloud Services User Guide 364 CHAPTER 6 Database Service l l l l l l l l Data Pump Conventional Export/Import 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. Data Pump Transportable Tablespace 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. For the steps this method entails, see Data Pump Transportable Tablespace. RMAN Transportable Tablespace with Data Pump 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. For the steps this method entails, see RMAN Transportable Tablespace with Data Pump. RMAN CONVERT Transportable Tablespace with Data Pump This method can be used 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 crossplatform 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. RMAN Cross-Platform Transportable Tablespace Backup Sets This method can be used only if the database character sets of your on-premises database and the Database Service database are compatible. For the steps this method entails, see RMAN Cross-Platform Transportable Tablespace Backup Sets. Data Pump Full Transportable This method can be used only if the database character sets of your on-premises database and the Database Service database are compatible. For the steps this method entails, see Data Pump Full Transportable. Unplugging/Plugging (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. For the steps this method entails, see Unplugging/Plugging a PDB. Remote Cloning (CDB) Oracle Bare Metal Cloud Services User Guide 365 CHAPTER 6 Database Service 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 l l 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. For the steps this method entails, see RMAN Cross-Platform Transportable PDB. 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 your Oracle Database 12c database on the cloud. In this method, you use 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 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 your Oracle Database 12c database on the cloud. In this method, you use 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 the Database Service using several different methods. The applicability of some of the migration methods depends on the on-premises database’s database 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. l l Data Pump Conventional Export/Import 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. Data Pump Transportable Tablespace Oracle Bare Metal Cloud Services User Guide 366 CHAPTER 6 Database Service 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. For the steps this method entails, see Data Pump Transportable Tablespace. l RMAN Transportable Tablespace with Data Pump 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. For the steps this method entails, see RMAN Transportable Tablespace with Data Pump. l l l l l RMAN CONVERT Transportable Tablespace with Data Pump This method can be used 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 crossplatform 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. RMAN Cross-Platform Transportable Tablespace Backup Sets This method can be used only if the database character sets of your on-premises database and the Database Service database are compatible. For the steps this method entails, see RMAN Cross-Platform Transportable Tablespace Backup Sets. Data Pump Full Transportable This method can be used only if the database character sets of your on-premises database and the Database Service database are compatible. For the steps this method entails, see Data Pump Full Transportable. 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 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. Remote Cloning (non-CDB) Oracle Bare Metal Cloud Services User Guide 367 CHAPTER 6 Database Service 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. l l 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 your Oracle Database 12c database on the cloud. In this method, you use 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 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 your Oracle Database 12c database on the cloud. In this method, you use 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: 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. Oracle Bare Metal Cloud Services User Guide 368 CHAPTER 6 Database Service Data Pump Conventional Export/Import: Example This example provides a step-by-step demonstration of the tasks required to migrate a schema from an onpremises 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 onpremises 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 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 Database Oracle Bare Metal Cloud Services User Guide 369 CHAPTER 6 Database Service Service 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 database as the SYSTEM user. $ sqlplus system Enter password: <enter the password for the SYSTEM user> b. Create a directory object in the Database Service 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 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. Oracle Bare Metal Cloud Services User Guide 370 CHAPTER 6 Database Service 3. Use a secure copy utility to transfer the Data Pump Export dump file and the datafiles for all of the userdefined 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 database. 7. After verifying that the data has been imported successfully, you can delete the dump 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 Enter password: <enter the password for the SYSTEM user> c. Create a directory object in the source database to reference the operating system directory. SQL> CREATE DIRECTORY dp_for_cloud AS '/u01/app/oracle/admin/orcl/dpdump/for_cloud'; 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. Oracle Bare Metal Cloud Services User Guide 371 CHAPTER 6 Database Service 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 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 userdefined tablespaces 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_source Oracle Bare Metal Cloud Services User Guide 372 CHAPTER 6 Database Service 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 datafiles of the transportable set to the Database Service compute node. $ scp -i private_key_file \ /u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \ oracle@compute_node_IP_address:/u01/app/oracle/admin/ORCL/dpdump/from_source $ scp -i private_key_file \ /u01/app/oracle/oradata/orcl/example01.dbf \ oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2 $ scp -i private_key_file \ /u01/app/oracle/oradata/orcl/fsdata01.dbf \ oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2 $ scp -i private_key_file \ /u01/app/oracle/oradata/orcl/fsindex01.dbf \ oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2 $ scp -i private_key_file \ /u01/app/oracle/oradata/orcl/users01.dbf \ oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2 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. Oracle Bare Metal Cloud Services User Guide 373 CHAPTER 6 Database Service 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. b. Create a directory object in the PDB. SQL> CREATE DIRECTORY dp_from_source AS '/u01/app/oracle/admin/ORCL/dpdump/from_source'; 6. On the Database Service compute node, invoke Data Pump Import and connect to the 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' 7. After verifying that the data has been imported successfully, you can delete the 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 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 transportable tablespace export. 3. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace datafiles 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. Oracle Bare Metal Cloud Services User Guide 374 CHAPTER 6 Database Service 6. On the Database Service compute node, invoke Data Pump Import and connect to the database. 7. Set the tablespaces on the Database Service database to READ WRITE mode. 8. After verifying that the data has been imported successfully, you can delete the dump file. Data Pump Transportable Tablespace: Example This example provides a step-by-step demonstration of the tasks required to migrate tablespaces in an onpremises Oracle database to a Database Service database. This example performs a migration of the FSDATA and FSINDEX tablespaces. In this example, the on-premises database is on a Linux host. 1. On the on-premises database host, prepare the database for the Data Pump transportable tablespace export. a. On the on-premises database host, create a directory in the operating system to use for the onpremises export. 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 system directory. SQL> CREATE DIRECTORY dp_for_cloud AS '/u01/app/oracle/admin/orcl/dpdump/for_cloud'; 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 export output. Oracle Bare Metal Cloud Services User Guide 375 CHAPTER 6 Database Service 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. SQL> ALTER TABLESPACE fsindex READ ONLY; Tablespace altered. SQL> ALTER TABLESPACE fsdata READ ONLY; Tablespace altered. f. Exit from SQL*Plus. 2. On the on-premises database host, invoke Data Pump Export to perform the transportable tablespace export. 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. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace datafiles 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 utility to copy files, make sure the SSH private key that provides access to Oracle Bare Metal Cloud Services User Guide 376 CHAPTER 6 Database Service 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 \ /u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \ oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem $ 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 \ oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL 4. Set the on-premises tablespaces back to READ WRITE. a. Invoke SQL*Plus and log in as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces back to READ WRITE mode. SQL> ALTER TABLESPACE fsdata READ WRITE; Tablespace altered. SQL> ALTER TABLESPACE fsindex READ WRITE; Tablespace altered. c. Exit from SQL*Plus. 5. On the Database Service compute node, prepare the database for the tablespace import. a. On the Database Service compute node, invoke SQL*Plus and log in to the database as the SYSTEM user. b. Create a directory object in the Database Service database. SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem'; 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; Oracle Bare Metal Cloud Services User Guide 377 CHAPTER 6 Database Service 6. On the Database Service compute node, invoke Data Pump Import and connect to the database. Import the data into the database using the TRANSPORT_DATAFILES option. 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. a. Invoke SQL*Plus and log in as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces to READ WRITE mode. SQL> ALTER TABLESPACE fsdata READ WRITE; Tablespace altered. SQL> ALTER TABLESPACE fsindex READ WRITE; Tablespace altered. c. Exit from SQL*Plus. 8. After verifying that the data has been imported successfully, you can delete the expdat.dmp dump file. 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. 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 Oracle Bare Metal Cloud Services User Guide 378 CHAPTER 6 Database Service the on-premises PDB. 4. On the Database Service 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 Database Service. 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. 6. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises database back to READ WRITE mode. Oracle Bare Metal Cloud Services User Guide 379 CHAPTER 6 Database Service For more information, see "Cloning a Remote PDB or Non-CDB" in Oracle Database Administrator's Guide for Release 12.2 or 12.1. 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 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. Oracle Bare Metal Cloud Services User Guide 380 CHAPTER 6 Database Service 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. 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 method, you perform these tasks: 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. 4. Set the on-premises tablespaces back to READ WRITE. 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 This example provides a step-by-step demonstration of the tasks required to migrate tablespaces in an Oracle Database PDB to a Database Service database. This example performs a migration of the FSDATA and FSINDEX tablespaces. In this example, the on-premises database is on a Linux host. Oracle Bare Metal Cloud Services User Guide 381 CHAPTER 6 Database Service 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 READ ONLY mode.. a. On the on-premises database host, create a directory in the operating system to use for the export dump. mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud 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 c. Create a directory object in the on-premises database to reference the operating system directory. SQL> CREATE DIRECTORY dp_for_cloud AS '/u01/app/oracle/admin/orcl/dpdump/for_cloud'; d. On the on-premises database host, set all tablespaces that will be transported (the transportable set) to READ ONLY mode. SQL> ALTER TABLESPACE fsindex READ ONLY; SQL> ALTER TABLESPACE fsdata READ ONLY; 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' 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. Oracle Bare Metal Cloud Services User Guide 382 CHAPTER 6 Database Service 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 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 backup set and the dump file to the Database Service compute node. scp -i private_key_file \ /u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.bck \ oracle@IP_address_DBaaS_VM:/tmp/from_onprem $ scp -i private_key_file \ /u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.dmp \ oracle@IP_address_DBaaS_VM:/tmp/from_onprem $ 4. Set the on-premises tablespaces back to READ WRITE. a. Invoke SQL*Plus and log in to the PDB as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces back to READ WRITE mode. SQL> ALTER TABLESPACE fsdata READ WRITE; SQL> ALTER TABLESPACE fsindex READ WRITE; c. Exit from SQL*Plus. 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. Oracle Bare Metal Cloud Services User Guide 383 CHAPTER 6 Database Service SQL> CREATE USER fsowner 2 PROFILE default 3 IDENTIFIED BY fspass 4 TEMPORARY TABLESPACE temp 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. a. Invoke SQL*Plus and log in to the PDB as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces to READ WRITE. SQL> ALTER TABLESPACE fsdata READ WRITE; SQL> ALTER TABLESPACE fsindex READ WRITE; c. Exit from SQL*Plus. 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 Database Service database are compatible. Oracle Bare Metal Cloud Services User Guide 384 CHAPTER 6 Database Service 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. 2. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace datafiles to the Database Service compute node. 3. On the Database Service compute node, prepare the database for the tablespace import. 4. On the Database Service compute node, invoke Data Pump Import and connect to the database. Import the data into the database using the TRANSPORT_DATAFILES option. 5. After verifying that the data has been imported successfully, you can delete the dump file. RMAN Transportable Tablespace with Data Pump: Example This example provides a step-by-step demonstration of the tasks required to migrate tablespaces in an onpremises Oracle database to a Database Service database. This example performs a migration of the FSDATA and FSINDEX tablespaces. In this example, the on-premises database is on a Linux host. 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. Oracle Bare Metal Cloud Services User Guide 385 CHAPTER 6 Database Service 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 2. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace datafiles 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 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 \ /u01/app/oracle/admin/orcl/rman_transdest/dmpfile.dmp \ oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem $ scp -i private_key_file \ /u01/app/oracle/admin/orcl/rman_transdest/fsdata01.dbf \ oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL $ scp -i private_key_file \ /u01/app/oracle/admin/orcl/rman_transdest/fsindex01.dbf \ oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL 3. On the Database Service compute node, prepare the database for the tablespace import. a. On the Database Service compute node, invoke SQL*Plus and log in to the database as the SYSTEM user. Oracle Bare Metal Cloud Services User Guide 386 CHAPTER 6 Database Service b. Create a directory object in the Database Service database. SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem'; 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; 4. On the Database Service compute node, invoke Data Pump Import and connect to the database. Import the data into the database using the TRANSPORT_DATAFILES option. impdp system DIRECTORY=dp_from_onprem DUMPFILE='dmpfile.dmp' \ TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \ '/u02/app/oracle/oradata/ORCL/fsindex01.dbf' 5. After verifying that the data has been imported successfully, you can delete the 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 Database Service using RMAN, 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 transportable tablespace export. 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. Refer to the Oracle Database Backup and Recovery Reference for more information on the CONVERT command. Oracle Bare Metal Cloud Services User Guide 387 CHAPTER 6 Database Service 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. 5. Set the on-premises tablespaces back to READ WRITE. 6. On the Database Service compute node, prepare the database for the tablespace import. 7. On the Database Service compute node, invoke Data Pump Import and connect to the database. 8. On the Database Service compute node, set the tablespaces in the database to READ WRITE mode. 9. After verifying that the data has been imported successfully, you can delete the dump file. RMAN CONVERT Transportable Tablespace with Data Pump: Example This example provides a step-by-step demonstration of the tasks required to migrate tablespaces in an onpremises Oracle database to a Database Service database. In this example, the on-premises database is on a Linux host. 1. On the on-premises database host, prepare the database for the Data Pump transportable tablespace export. a. On the on-premises database host, create a directory in the operating system to use for the onpremises export. 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 system directory. SQL> CREATE DIRECTORY dp_for_cloud AS '/u01/app/oracle/admin/orcl/dpdump/for_cloud'; d. On the on-premises database host, set all tablespaces that will be transported (the transportable set) to READ ONLY mode. SQL> ALTER TABLESPACE fsindex READ ONLY; Tablespace altered. SQL> ALTER TABLESPACE fsdata READ ONLY; Oracle Bare Metal Cloud Services User Guide 388 CHAPTER 6 Database Service Tablespace altered. e. Exit from SQL*Plus. 2. On the on-premises database host, invoke Data Pump Export to perform the transportable tablespace export. 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 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. 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. Oracle Bare Metal Cloud Services User Guide 389 CHAPTER 6 Database Service 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 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 \ /u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \ oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem $ scp -i private_key_file \ /tmp/data_D-ORCL_I-1410251631_TS-FSDATA_FNO-6_0aqc9un3 \ oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsdata01.dbf $ scp -i private_key_file \ /tmp/data_D-ORCL_I-1410251631_TS-FSINDEX_FNO-7_0bqc9un6 \ oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsindex01.dbf 5. Set the on-premises tablespaces back to READ WRITE. a. Invoke SQL*Plus and log in as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces back to READ WRITE mode. SQL> ALTER TABLESPACE fsdata READ WRITE; Tablespace altered. SQL> ALTER TABLESPACE fsindex READ WRITE; Tablespace altered. c. Exit from SQL*Plus. 6. On the Database Service compute node, prepare the database for the tablespace import. a. On the Database Service compute node, invoke SQL*Plus and log in to the database as the SYSTEM user. b. Create a directory object in the Database Service database. SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem'; 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. Oracle Bare Metal Cloud Services User Guide 390 CHAPTER 6 Database Service SQL> CREATE USER fsowner 2 PROFILE default 3 IDENTIFIED BY fspass 4 TEMPORARY TABLESPACE temp 5 ACCOUNT UNLOCK; 7. On the Database Service compute node, invoke Data Pump Import and connect to the database. Import the data into the DBaaS database using the TRANSPORT_DATAFILES option impdp system DIRECTORY=dp_from_onprem \ TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \ '/u02/app/oracle/oradata/ORCL/fsindex01.dbf' 8. On the Database Service compute node, set the tablespaces in the database to READ WRITE mode. a. Invoke SQL*Plus and log in as the SYSTEM user. b. Set the FSDATA and FSINDEX tablespaces to READ WRITE mode. SQL> ALTER TABLESPACE fsdata READ WRITE; Tablespace altered. SQL> ALTER TABLESPACE fsindex READ WRITE; Tablespace altered. c. Exit from SQL*Plus. 9. After verifying that the data has been imported successfully, you can delete the expdat.dmp dump file. RMAN DUPLICATE from an Active Database This topic explains how to migrate an entire, active container database (CDB) or non-CDB database to Oracle Bare Metal Cloud Services by using RMAN Active Duplication. The database to be migrated can reside onpremises or in the Oracle Public Cloud. (This topic does not cover duplicating a pluggable database (PDB) or plugging a PDB or non-CDB to a CDB in the cloud.) The following terms are used throughout this topic: l l Source database: The active database to be migrated. Target database: The new database (duplicated from the source database) on a DB System in the Oracle Bare Metal Cloud Services. Oracle Bare Metal Cloud Services User Guide 391 CHAPTER 6 Database Service 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 l l The source database name, database unique name, listener port, service name, database home patch level, and the password for SYS. 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. 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. For the target database, you'll need: l l 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 creating a DB System, see Managing Bare Metal DB Systems. For information about creating a database with the CLI, see Database Commands. The target database name, database unique name, auxiliary service name, and database home patch level. A free TCP port in the target database to setup the auxiliary instance. 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 Oracle Bare Metal Cloud Services User Guide 392 CHAPTER 6 Database Service 3. On the target host, use Easy Connect to verify the connection to the source database: <host>:<port>/<servicename> For example: sqlplus [email protected]: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. 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 11.2.0.4.0 for an 11.2.0.4 database and at least 12.1.0.2.0 for a 12.1.0.2 database. Setting Up Storage on the DB System 1. SSH to the DB System. ssh -i <private_key_path> opc@<db_system_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, which will set the PATH to the dbcli directory (/opt/oracle/dcs/bin). login as: opc [opc@dbsys ~]$ sudo su - 3. 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 tdetest database. [root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS Note When migrating a version 11.2 database, ACFS storage must be specified. Oracle Bare Metal Cloud Services User Guide 393 CHAPTER 6 Database Service 4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the 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) Created: August 24, 2016 5:25:38 PM UTC 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. Oracle Bare Metal Cloud Services User Guide 394 CHAPTER 6 Database Service 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 version 12c, use the ADMINISTER KEY MANAGEMENT command: Oracle Bare Metal Cloud Services User Guide 395 CHAPTER 6 Database Service $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"; 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. Oracle Bare Metal Cloud Services User Guide 396 CHAPTER 6 Database Service 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: 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: Oracle Bare Metal Cloud Services User Guide 397 CHAPTER 6 Database Service 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. 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. Oracle Bare Metal Cloud Services User Guide 398 CHAPTER 6 Database Service 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. 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 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: Oracle Bare Metal Cloud Services User Guide 399 CHAPTER 6 Database Service [root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename crmdb.example.com --syspassword Password for SYS: { "jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2", "status" : "Created", "message" : null, "reports" : [ ], "createTimestamp" : "August 08, 2016 05:55:49 AM EDT", "description" : "Database service registration with db service name: crmdb.example.com", "updatedTime" : "August 08, 2016 05:55:49 AM EDT" } Rolling Back Patches on a Version 11.2 Database For version 11.2 databases, the sqlpatch application is not automated, so any 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. 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: [root@dbsys ~]# dbcli list-dbhomes ID Home Location Name DB Version 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 Bare Metal Cloud Services User Guide 400 CHAPTER 6 Database Service $ $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 Unique Patch ID: : applied on Fri Sep 02 15:28:17 UTC 2016 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> 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> connect / as sysdba SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql exit Oracle Bare Metal Cloud Services User Guide 401 CHAPTER 6 Database Service 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. 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: l dbcli update-backupconfig l dbcli list-backupconfigs l dbcli describe-backupconfig 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 l l External tables: If the source database uses external tables, back up that data and migrate it to the target host. Directories: Customize the default directories as needed for the migrated database. Database links: Make sure all the required TNS entries are updated in the tnsnames.ora file in ORACLE_HOME. Oracle Bare Metal Cloud Services User Guide 402 CHAPTER 6 Database Service l l Email and URLs: Make sure any email addresses and URLs used in the database are still accessible from the DB System. 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 Database Service. In this method, you use SQL INSERT statements 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 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 on the Database Service. 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 on the Database Service deployment using SQL Developer and SQL*Loader, you perform these tasks: Oracle Bare Metal Cloud Services User Guide 403 CHAPTER 6 Database Service 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. 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 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 a Database Service database deployment using the plug/unplug 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 to the database on the Database Service. 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, open the new PDB by executing the ALTER PLUGGABLE DATABASE OPEN command. 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. Oracle Bare Metal Cloud Services User Guide 404 CHAPTER 6 Database Service 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 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 a PDB in an Oracle Database 12c database on a Database Service database deployment. This 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 database 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. 6. On the Database Service compute node, open the new PDB by executing the ALTER PLUGGABLE DATABASE OPEN command. 7. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises database back to READ WRITE mode. For more information, see "Creating a PDB Using a Non-CDB" in Oracle Database Administrator's Guide for Release 12.2 or 12.1. Oracle Bare Metal Cloud Services User Guide 405 CHAPTER 7 IAM Service This chapter explains how to set up administrators, users, and groups and specify their permissions. Overview of the IAM Service The Oracle Bare Metal Cloud Identity and Access Management Service (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 the IAM Service 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 the IAM Service. Components of the IAM Service The IAM Service 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 Bare Metal Cloud Services. 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 Bare Metal Cloud Services resources. Users might need to launch instances, manage remote disks, work with your Virtual Cloud Network, etc. End users of your application are not typically IAM Service users. Users have one or more IAM Service 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 Bare Metal Cloud Services 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 Oracle Bare Metal Cloud Services User Guide 406 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services Getting Started Guide. Tenancy The root compartment that contains all of your organization's Oracle Bare Metal Cloud Services resources. Oracle automatically creates your company's tenancy for you. Directly within the tenancy are your IAM Service 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); and to mean the overall body of policies your organization uses to control access to resources. Home Region The region where your IAM Service resources reside. All IAM Service 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 Service 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 Bare Metal Cloud Services. That includes: l Audit Service l Core Services (includes Networking Service, Compute Service, and Block Volume Service) l Database Service l IAM Service l Load Balancing Service l Object Storage Service Oracle Bare Metal Cloud Services User Guide 407 CHAPTER 7 IAM Service 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 Service 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. Your tenancy also automatically has a policy that gives the Administrators group access to all of the Oracle Bare Metal Cloud Services 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 Service 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 Bare Metal Cloud Services resources that become available in the future. Example Scenario The goal of this scenario is to show how the different IAM Service components work together, and basic features of policies. In this scenario Acme Company has two teams that will be using Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services Acme Company signs up to use Oracle Bare Metal Cloud Services and tells Oracle that an employee named Wenpei will be the default administrator. In response, Oracle: Oracle Bare Metal Cloud Services User Guide 408 CHAPTER 7 IAM Service l Creates a tenancy for Acme Company (see the following diagram). l Creates an IAM Service user account for Wenpei in the tenancy. 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. Oracle Bare Metal Cloud Services User Guide 409 CHAPTER 7 IAM Service The Default Administrator Creates Some Compartments and Policies Wenpei next creates compartments to group resources together (see the following diagram). She: l l l Creates a compartment called Networks to control access to the Acme Company's VCN, subnets, IPSec VPN, and other components from the Networking Service. Creates a compartment called Project-A to organize Project A team's cloud resources and control access to them. 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: l Give the NetworkAdmins group access to manage networks and instances (for the purposes of easily testing the network) in the Networks compartment Oracle Bare Metal Cloud Services User Guide 410 CHAPTER 7 IAM Service 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-networkfamily, instance-family, all-resources). For more information about them, see Verbs and ResourceTypes.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 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. Oracle Bare Metal Cloud Services User Guide 411 CHAPTER 7 IAM Service Oracle Bare Metal Cloud Services User Guide 412 CHAPTER 7 IAM Service 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. Oracle Bare Metal Cloud Services User Guide 413 CHAPTER 7 IAM Service Oracle Bare Metal Cloud Services User Guide 414 CHAPTER 7 IAM Service The Network Admin Sets Up the Network Leslie (in the NetworkAdmins group) has access to manage virtual-network-family and instancefamily 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 onpremises 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 the Networking Service. 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. Oracle Bare Metal Cloud Services User Guide 415 CHAPTER 7 IAM Service 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. 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: Oracle Bare Metal Cloud Services User Guide 416 CHAPTER 7 IAM Service 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: Oracle Bare Metal Cloud Services User Guide 417 CHAPTER 7 IAM Service Oracle Bare Metal Cloud Services User Guide 418 CHAPTER 7 IAM Service 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 Service Resources Oracle Bare Metal Cloud Services 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 Service resources (users, groups, compartments, and policies) are global and available across all regions. See Managing Regions. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access Oracle Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. Oracle Bare Metal Cloud Services User Guide 419 CHAPTER 7 IAM Service When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. For general information about using the API, see About the API. Limits on IAM Service Resources See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Getting Started with Policies If you're new to Oracle Bare Metal Cloud Identity and Access Management Service (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 Bare Metal Cloud Services 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. 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 l Make sure you're familiar with the basic IAM Service components, and read through the example scenario: Overview of the IAM Service Think about how to organize your resources into compartments: See "Setting Up Your Tenancy" in the Oracle Bare Metal Cloud Services Getting Started Guide Oracle Bare Metal Cloud Services User Guide 420 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services can I control access to through policies? All of them, including the IAM Service 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: l l Change or reset their own Console password, and manage their own API signing keys and Swift passwords (see Security Credentials). 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 Oracle Bare Metal Cloud Services User Guide 421 CHAPTER 7 IAM Service 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 the IAM Service (you have to remove the user from all groups first) 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 rename or delete a compartment? Compartments cannot be renamed or 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. 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 Bare Metal Cloud Services 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 the IAM Service. Oracle Bare Metal Cloud Services User Guide 422 CHAPTER 7 IAM Service In general, here’s the process an IAM Service administrator in your organization needs to follow: 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. 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 Oracle Bare Metal Cloud Services User Guide 423 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services resources in the compartment. Here's an example policy that enables that: Allow group A-Admins to manage all-resources in compartment Project-A Be aware that the policy directly above includes the ability to write policies for that compartment, which means AAdmins 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: 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 Oracle Bare Metal Cloud Services User Guide 424 CHAPTER 7 IAM Service 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 information or user-specified metadata that may be part of that resource. Important: The operation to list policies includes the contents of the policies themselves, and the list operations for the Networking Service resourcetypes return all the information (e.g., the contents of security lists and route tables). Third-party auditors read Includes inspect plus the ability to get user-specified metadata and the actual resource itself. Internal auditors use Includes read plus the ability to work with existing resources (the actions vary by resource type). Includes the ability to update the resource, except for resource-types where the "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. Day-to-day end users of resources 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. Oracle Bare Metal Cloud Services User Guide 425 CHAPTER 7 IAM Service 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. Object Storage Service 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 Service resources: Be aware that inspect load-balancers lets you get all information about your load balancers and related components (backend sets, etc.). Networking Service resources: Be aware that the inspect verb not only returns general information about the cloud network's components (e.g., the name and OCID of a security list, or of a route table). It also includes the contents of the component (e.g., the actual rules in the security list, the routes in the route table, etc.). 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) Oracle Bare Metal Cloud Services User Guide 426 CHAPTER 7 IAM Service Important: Each VCN has various components that directly affect the behavior of the network (route tables, security lists, DHCP options, Internet Gateway, etc.). 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, etc.) 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 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: The Block Volume Service 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 resourcetype in your policy. But if you need to give broad access to all of the Block Volume Service resources, you can specify the family type called volume-family. For a full list of the resource-types, see Resource-Types. Oracle Bare Metal Cloud Services User Guide 427 CHAPTER 7 IAM Service Important: If a service introduces new individual resource-types, they will typically be included in the family type for that service. For example, if the Networking Service introduces a new individual resource-type, it will be automatically included in the definition of the virtual-networkfamily 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 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 Oracle Bare Metal Cloud Services User Guide 428 CHAPTER 7 IAM Service 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 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 the IAM Service, 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. Oracle Bare Metal Cloud Services User Guide 429 CHAPTER 7 IAM Service 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. 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 the Networking Service. 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 l Details for the Audit Service Details for the Core Services (this includes Networking Service, Compute Service, and Block Volume Service, which are closely related) l Details for the Database Service l Details for the IAM Service l Details for the Load Balancing Service l Details for the Object Storage Service Common Policies This section includes some common policies you might want to use in your organization. Note: These policies use example group and compartment names. Oracle Bare Metal Cloud Services User Guide 430 CHAPTER 7 IAM Service 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. Allow group HelpDesk to manage users in tenancy Let Auditors Inspect Your Resources Type of access: Ability to list the resources in all compartments. Be aware that: l l l l The operation to list IAM Service policies includes the contents of the policies themselves The list operations for the Networking Service resource-types return all the information (e.g., the contents of security lists and route tables) The operation to list instances requires the read verb instead of inspect, and the contents include the user-provided metadata. 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 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 the Networking Service. This includes cloud networks, subnets, gateways, virtual circuits, security lists, route tables, etc. If the network admins need to launch instances to test network connectivity, see Let Users Launch Instances below. Where to create the policy: In the tenancy. Because of the concept of policy inheritance, 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 Oracle Bare Metal Cloud Services User Guide 431 CHAPTER 7 IAM Service Let Network Admins Manage Load Balancers Type of access: Ability to manage all components in the Load Balancing Service. If the group needs to launch instances, see Let Users Launch Instances below. Where to create the policy: In the tenancy. Because of the concept of policy inheritance, 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 (e.g., 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 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. Oracle Bare Metal Cloud Services User Guide 432 CHAPTER 7 IAM Service 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 of the backup (and the ability to delete backups). 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 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 Object Storage Service Admins Manage Buckets and Objects Type of access: Ability to do all things with Object Storage Service buckets and objects in all compartments. Oracle Bare Metal Cloud Services User Guide 433 CHAPTER 7 IAM Service 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 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 Service Buckets Type of access: Ability to write objects to any Object Storage Service 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. Where to create the policy: The easiest approach is to put this policy in the tenancy. If you 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'} Limit Access 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'}} For more information about using conditions, see Advanced Policy Features. Oracle Bare Metal Cloud Services User Guide 434 CHAPTER 7 IAM Service Let Users Download Objects from Object Storage Service Buckets Type of access: Ability to download objects from any Object Storage Service 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. Where to create the policy: The easiest approach is to put this policy in the tenancy. If you 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 Limit access 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. 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 database systems in a particular compartment, specify that compartment instead of the tenancy. Allow group DatabaseAdmins to manage database-family in tenancy 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). Oracle Bare Metal Cloud Services User Guide 435 CHAPTER 7 IAM Service 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. Let a Compartment Admin Manage the Compartment Type of access: Ability to manage all aspects of a particular compartment. For example, a group called AAdmins 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. Allow group A-Admins to manage all-resources in compartment Project-A Oracle Bare Metal Cloud Services User Guide 436 CHAPTER 7 IAM Service Restrict Admin Access to a Specific Region Type of access: Ability to manage all resources in a specific region only. Remember that IAM Service 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 Service resources. For more information about the home region, see Managing Regions. Where to create the policy: In the tenancy. Allow group IAD-Admins to manage all-resources in tenancy where request.region='iad' The preceding policy allows IAD-Admins to manage all aspects of all resources in the Ashburn (IAD) region. Assuming this tenancy's home region is Phoenix (PHX), then this policy does not allow IAD-Admins to manage IAM Service resources. 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 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 Service Buckets. Oracle Bare Metal Cloud Services User Guide 437 CHAPTER 7 IAM Service 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' 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. Oracle Bare Metal Cloud Services User Guide 438 CHAPTER 7 IAM Service 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 + ResourceType Combinations. The left column of each of those 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 Oracle Bare Metal Cloud Services User Guide 439 CHAPTER 7 IAM Service resource-type, some to the volume-attachments resource-type, and some related to the instances resourcetype: 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. 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: Oracle Bare Metal Cloud Services User Guide 440 CHAPTER 7 IAM Service 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: Allow group XYZ to manage groups in tenancy where any {request.operation='ListGroups', request.operation='GetGroup', request.operation='CreateGroup', request.operation='UpdateGroup'} 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. Allow group XYZ to manage groups in tenancy 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. Oracle Bare Metal Cloud Services User Guide 441 CHAPTER 7 IAM Service 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. Syntax: group <group_name> | group id <group_ocid> | any-user Examples: l To specify a single group by name: Allow group A-Admins to manage all-resources in compartment Project-A 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-Aand-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 Oracle Bare Metal Cloud Services User Guide 442 CHAPTER 7 IAM Service 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: Allow group A-Admins to manage all-resources in compartment Project-A Resource-Type Specify a single resource-type, which can be one of the following: 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: Allow group HelpDesk to manage users in tenancy 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): Allow group A-Admins to manage all-resources in compartment Project-A Oracle Bare Metal Cloud Services User Guide 443 CHAPTER 7 IAM Service 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. 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: Allow group A-Admins to manage all-resources in compartment Project-A 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 Oracle Bare Metal Cloud Services User Guide 444 CHAPTER 7 IAM Service 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 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 '[email protected]' '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: Oracle Bare Metal Cloud Services User Guide 445 CHAPTER 7 IAM Service 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-*/ 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 Service, Compute Service, and Block Volume Service) Oracle Bare Metal Cloud Services User Guide 446 CHAPTER 7 IAM Service l Details for the Database Service l Details for the IAM Service l Details for the Load Balancing Service l Details for the Object Storage Service 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. Verb Types of Access Covered Target User inspect Ability to list resources, without access to any confidential information or user-specified metadata that may be part of that resource. Important: The operation to list policies includes the contents of the policies themselves, and the list operations for the Networking Service resourcetypes return all the information (e.g., the contents of security lists and route tables). Third-party auditors read Includes inspect plus the ability to get user-specified metadata and the actual resource itself. Internal auditors use Includes read plus the ability to work with existing resources (the actions vary by resource type). Includes the ability to update the resource, except for resource-types where the "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. Day-to-day end users of resources manage Includes all permissions for the resource. Administrators Oracle Bare Metal Cloud Services User Guide 447 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services 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 the Object Storage Service l virtual-network-family: See Details for the Core Services l volume-family: See Details for the Core Services The IAM Service has no family resource-type, only individual ones. See Details for the IAM Service. 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. Name Type Description request.user.id Entity (OCID) The OCID of the requesting user. request.groups.id List of entities (OCIDs) The OCIDs of the groups the requesting user is in. 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.compartment.name String Oracle Bare Metal Cloud Services User Guide The name of the compartment specified in target.compartment.id. 448 CHAPTER 7 IAM Service Name Type Description request.operation String The API operation name being requested (e.g., ListUsers). request.permission String The underlying permission(s) being requested (see Permissions). request.region String The key of the region the request is made in. Allowed values are: request.ad String l phx l iad 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 l 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. 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. Oracle Bare Metal Cloud Services User Guide 449 CHAPTER 7 IAM Service audit-events INSPECT Permissions APIs Fully Covered APIs Partially Covered none none none Permissions APIs Fully Covered APIs Partially Covered AUDIT_EVENT_READ ListAuditEvents none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none READ USE 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 Details for the Core Services This topic covers details for writing policies to control access to the Core Services (Networking Service, Compute Service, and Block Volume Service). Oracle Bare Metal Cloud Services User Guide 450 CHAPTER 7 IAM Service Resource-Types Oracle Bare Metal Cloud Services User Guide 451 CHAPTER 7 IAM Service Aggregate Resource-Type Individual ResourceTypes Comments Networking Service and Load Balancing Service: Networking Service and Load Balancing Service: 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 in the column to the left. l virtualnetworkfamily l vcns l subnets l route-tables l security-lists l dhcp-options l internetgateways l drgs l drgattachments l cpes l ipsecconnections l cross-connects l cross-connectgroups l virtualcircuits l vnics l vnicattachments Oracle Bare Metal Cloud Services User Guide 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. 452 CHAPTER 7 IAM Service Aggregate Resource-Type Individual ResourceTypes Comments Compute Service: Compute Service 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 in the column to the left. l instancefamily Block Volume Service: l volumefamily l consolehistories l instanceimages l instances l volumeattachments (includes only the permissions required for attaching volumes to instances) l volumes l volumeattachments l volume-backups 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 instance-family. 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 in the column to the left. 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. 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. Oracle Bare Metal Cloud Services User Guide 453 CHAPTER 7 IAM Service 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 Permissions APIs Fully Covered APIs Partially Covered VCN_READ ListVcns none GetVcn READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none USE Oracle Bare Metal Cloud Services User Guide 454 CHAPTER 7 IAM Service MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + VCN_ATTACH CreateVcn VCN_DETACH UpdateVcn VCN_UPDATE DeleteVcn CreateSubnet, DeleteSubnet (both also need manage routetables and managesecurity-lists and manage-dhcp-options) VCN_CREATE CreateRouteTable (also need manage routetables) VCN_DELETE CreateInternetGateway (also need manage internet-gateways) CreateSecurityList (also need manage securitylists) CreateDhcpOptions (also need manage dhcpoptions) CreateDrgAttachment (also need manage drgs) Note: The operations above are totally covered with just manage virtualnetwork-family. subnets INSPECT Permissions APIs Fully Covered APIs Partially Covered SUBNET_READ ListSubnets none GetSubnet Oracle Bare Metal Cloud Services User Guide 455 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered READ + no extra LaunchInstance (also need manage instancefamily) USE SUBNET_ATTACH SUBNET_DETACH TerminateInstance (also need manage instancefamily, and use volumes if a volume is attached) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + USE + SUBNET_CREATE UpdateSubnet CreateSubnet, DeleteSubnet (both also need manage vcns, manage route-tables, manage security-lists, manage dhcp-options) SUBNET_UPDATE SUBNET_DELETE Note: The above operations in this cell are covered with just manage virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 456 CHAPTER 7 IAM Service route-tables INSPECT Permissions APIs Fully Covered APIs Partially Covered ROUTE_TABLE_READ ListRouteTables none GetRouteTable READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + UpdateRouteTable ROUTE_TABLE_ATTACH Note: Ability to update a route table is available only with the manage verb, not the use verb CreateRouteTable, DeleteRouteTable (both also need manage vcns) USE MANAGE ROUTE_TABLE_DETACH ROUTE_TABLE_UPDATE ROUTE_TABLE_CREATE ROUTE_TABLE_DELETE 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 virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 457 CHAPTER 7 IAM Service security-lists INSPECT Permissions APIs Fully Covered APIs Partially Covered SECURITY_LIST_READ ListSecurityLists none GetSecurityList READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + SECURITY_LIST_ATTACH UpdateSecurityList SECURITY_LIST_DETACH Note: Ability to update a security list is available only with the manage verb, not the use verb. CreateSecurityList, DeleteSecurityList (both also need manage vcns) USE MANAGE SECURITY_LIST_UPDATE SECURITY_LIST_CREATE SECURITY_LIST_DELETE CreateSubnet, DeleteSubnet (both also need manage vcns, manage subnets, manage route-tables, manage dhcp-options) Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 458 CHAPTER 7 IAM Service dhcp-options INSPECT Permissions APIs Fully Covered APIs Partially Covered DHCP_READ ListDhcpOptions none GetDhcpOptions READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + DHCP_ATTACH UpdateDhcpOptions CreateDhcpOptions, DeleteDhcpOptions (both also need manage vcns) DHCP_DETACH Note: Ability to update a set of DHCP options is available only with the manage verb, not the use verb. USE MANAGE DHCP_UPDATE DHCP_CREATE DHCP_DELETE CreateSubnet, DeleteSubnet (also need manage vcns, manage subnets, manage routetables, manage security-lists) Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 459 CHAPTER 7 IAM Service internet-gateways INSPECT Permissions APIs Fully Covered APIs Partially Covered INTERNET_GATEWAY_ READ ListInternetGateways none GetInternetGateway READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + INTERNET_GATEWAY_ ATTACH UpdateInternetGateway CreateInternetGateway, DeleteInternetGateway (both also need manage vcns) USE MANAGE INTERNET_GATEWAY_ DETACH INTERNET_GATEWAY_ UPDATE Note: Ability to update a an Internet Gateway is available only with the manage verb, not the use verb. INTERNET_GATEWAY_ CREATE Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. INTERNET_GATEWAY_ DELETE Oracle Bare Metal Cloud Services User Guide 460 CHAPTER 7 IAM Service drgs INSPECT Permissions APIs Fully Covered APIs Partially Covered DRG_READ ListDrgs none DRG_ATTACHMENT_ READ GetDrg ListDrgAttachments READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none USE Oracle Bare Metal Cloud Services User Guide 461 CHAPTER 7 IAM Service MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + DRG_ATTACH CreateDrg DRG_DETACH UpdateDrg CreateDrgAttachment, DeleteDrgAttachment (both also need manage vcns) DRG_UPDATE DeleteDrg DRG_ATTACHMENT_ UPDATE UpdateDrgAttachment DRG_CREATE DRG_DELETE UpdateVirtualCircuit (also need use virtualcircuits, and if you're also changing which crossconnect or cross-connect group the virtual circuit uses, also need manage crossconnects) 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 crossconnects) Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 462 CHAPTER 7 IAM Service cpes INSPECT Permissions APIs Fully Covered APIs Partially Covered CPE_READ ListCpes none GetCpe READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + CPE_ATTACH CreateCpe CPE_DETACH UpdateCpe CPE_UPDATE DeleteCpe CreateIPSecConnection, DeleteIPSecConnection (both also need manage ipsec-connections and manage drgs) USE MANAGE CPE_CREATE CPE_DELETE Oracle Bare Metal Cloud Services User Guide Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. 463 CHAPTER 7 IAM Service ipsec INSPECT Permissions APIs Fully Covered APIs Partially Covered IPSEC_CONNECTION_ READ ListIPSecConnections none GetIPSecConnection GetIPSecConnectionStat us READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + INSPECT + none IPSEC_CONNECTION_ DEVICE_CONFIG_READ GetIPSecConnectionDevi ceConfig USE Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + IPSEC_CONNECTION_ CREATE UpdateIPSecConnection CreateIPSecConnection, DeleteIPSecConnection (both also need manage cpes and manage drgs) MANAGE IPSEC_CONNECTION_ UPDATE IPSEC_CONNECTION_ DELETE Oracle Bare Metal Cloud Services User Guide Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. 464 CHAPTER 7 IAM Service cross-connects INSPECT Permissions APIs Fully Covered APIs Partially Covered CROSS_CONNECT_READ ListCrossConnects none GetCrossConnect READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered USE + UpdateCrossConnect CROSS_CONNECT_ UPDATE CreateCrossConnect UpdateVirtualCircuit (also need use virtualcircuits) USE MANAGE DeleteCrossConnect CROSS_CONNECT_ CREATE CROSS_CONNECT_ DELETE CreateVirtualCircuit, DeleteVirtualCircuit (also need manage virtual-circuits) CROSS_CONNECT_ ATTACH CROSS_CONNECT_ DETACH Oracle Bare Metal Cloud Services User Guide 465 CHAPTER 7 IAM Service cross-connect-groups INSPECT Permissions APIs Fully Covered APIs Partially Covered CROSS_CONNECT_ GROUP_READ ListCrossConnectGroups none GetCrossConnectGroup READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered USE + UpdateCrossConnectGrou p no extra USE MANAGE CROSS_CONNECT_ GROUP_UPDATE CROSS_CONNECT_ GROUP_CREATE CROSS_CONNECT_ GROUP_DELETE CreateCrossConnectGrou p DeleteCrossConnectGrou p virtual-circuits INSPECT Permissions APIs Fully Covered APIs Partially Covered VIRTUAL_CIRCUIT_READ ListVirtualCircuits none GetVirtualCircuit Oracle Bare Metal Cloud Services User Guide 466 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered READ + no extra READ + USE VIRTUAL_CIRCUIT_ UPDATE UpdateVirtualCircuit (also need manage drgs,and if you're also changing which crossconnect or cross-connect group the virtual circuit uses, also need manage crossconnects) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + no extra USE + VIRTUAL_CIRCUIT_ CREATE VIRTUAL_CIRCUIT_ DELETE CreateVirtualCircuit, DeleteVirtualCircuit (both also 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 crossconnects) Note: All of the above operations in this cell are totally covered with just manage virtualnetwork-family. Oracle Bare Metal Cloud Services User Guide 467 CHAPTER 7 IAM Service vnics INSPECT Permissions APIs Fully Covered APIs Partially Covered VNIC_READ GetVnic none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered READ + no extra none READ USE VNIC_ATTACH LaunchInstance (also need use subnets and manage instancefamily) VNIC_DETACH VNIC_CREATE VNIC_DELETE MANAGE Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered VNIC_ATTACHMENT_ READ none ListVnicAttachments (also need inspect instances) vnic-attachments INSPECT Oracle Bare Metal Cloud Services User Guide 468 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered no extra none no extra Permissions APIs Fully Covered APIs Partially Covered no extra none no extra Permissions APIs Fully Covered APIs Partially Covered no extra none no extra 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 Oracle Bare Metal Cloud Services User Guide 469 CHAPTER 7 IAM Service l VOLUME_ATTACHMENT_UPDATE 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 Permissions APIs Fully Covered APIs Partially Covered INSTANCE_INSPECT none GetConsoleHistory, ListConsoleHistories (both also need inspect console-histories) ListVnicAttachments (also need inspect vnicattachments) ListVolumeAttachments (also need inspect volumes and inspect volume-attachments) GetVolumeAttachments (also need inspect volumes and inspect volume-attachments) Oracle Bare Metal Cloud Services User Guide 470 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + ListInstances INSPECT + INSTANCE_READ GetInstance CaptureConsoleHistory (also need manage console-histories and read instance-images) Note: ListInstances and GetInstance include any user-provided metadata added to the instance ShowConsoleHistoryData (also need read consolehistories and read instance-images) USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + READ + INSTANCE_UPDATE UpdateInstance INSTANCE_CREATE_ IMAGE InstanceAction CreateImage (also need manage instanceimages) INSTANCE_POWER_ ACTIONS INSTANCE_ATTACH_ VOLUME INSTANCE_DETACH_ VOLUME Oracle Bare Metal Cloud Services User Guide AttachVolume (also need manage volumeattachments and use volumes) DetachVolume (also need manage volumeattachments and use volumes) 471 CHAPTER 7 IAM Service MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + no extra USE + INSTANCE_CREATE LaunchInstance (also need read instanceimages and use vnics and use subnets) INSTANCE_DELETE TerminateInstance (also need use vnics and use subnets; also need manage volume-attachments and use volumes if a volume is attached) console-histories INSPECT Permissions APIs Fully Covered APIs Partially Covered CONSOLE_HISTORY_ INSPECT none ListConsoleHistories, GetConsoleHistory (both also need inspect instances) Permissions APIs Fully Covered APIs Partially Covered INSPECT + none INSPECT + READ CONSOLE_HISTORY_ READ ShowConsoleHistoryData (also need read instances and read instance-images) USE Permissions APIs Fully Covered APIs Partially Covered no extra none no extra Oracle Bare Metal Cloud Services User Guide 472 CHAPTER 7 IAM Service MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + DeleteConsoleHistory USE + CONSOLE_HISTORY_ CREATE CaptureConsoleHistory (also need read instances and read instance-images) CONSOLE_HISTORY_ DELETE instance-images INSPECT Permissions APIs Fully Covered APIs Partially Covered INSTANCE_IMAGE_ INSPECT ListImages none GetImage READ Permissions APIs Fully Covered APIs Partially Covered 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) Oracle Bare Metal Cloud Services User Guide 473 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + UpdateImage no extra Permissions APIs Fully Covered APIs Partially Covered USE + DeleteImage USE + INSTANCE_IMAGE_ UPDATE MANAGE 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. Oracle Bare Metal Cloud Services User Guide 474 CHAPTER 7 IAM Service volumes INSPECT Permissions APIs Fully Covered APIs Partially Covered VOLUME_INSPECT ListVolumes ListVolumeBackups, GetVolumeBackup, (these also need inspect volume-backups) GetVolume UpdateVolumeBackup (also need read volumebackups) DeleteVolumeBackup (also need manage volumebackups) 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 Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Oracle Bare Metal Cloud Services User Guide 475 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + no extra READ + VOLUME_UPDATE AttachVolume and DetachVolume (both also need manage volumeattachments, use instances) VOLUME_WRITE CreateVolumeBackup (also need manage volumebackups) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + USE + VOLUME_CREATE CreateVolume VOLUME_DELETE DeleteVolume If creating a volume from a backup, also need read volume-backups. volume-attachments INSPECT Permissions APIs Fully Covered APIs Partially Covered VOLUME_ATTACHMENT_ INSPECT ListVolumeAttachments GetVolumeAttachment (also need inspect volumes and inspect instances) Note: The CHAP secret (if it exists) is NOT included with inspect volumeattachments. Oracle Bare Metal Cloud Services User Guide 476 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + no extra Same as for inspect volume-attachments, except that GetVolumeAttachment also includes the CHAP secret, if it exists. Permissions APIs Fully Covered APIs Partially Covered READ + no extra no extra Permissions APIs Fully Covered APIs Partially Covered USE + no extra USE + VOLUME_ATTACHMENT_ READ USE VOLUME_ATTACHMENT_ UPDATE MANAGE VOLUME_ATTACHMENT_ CREATE AttachVolume, DetachVolume (both also need use volumes and use instances) VOLUME_ATTACHMENT_ DELETE volume-backups INSPECT Permissions APIs Fully Covered APIs Partially Covered VOLUME_BACKUP_ INSPECT none ListVolumeBackups, GetVolumeBackup (both also need inspect volumes) Oracle Bare Metal Cloud Services User Guide 477 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + none INSPECT + VOLUME_BACKUP_READ CreateVolume when creating volume from an backup (also need manage volumes) USE Permissions APIs Fully Covered APIs Partially Covered READ + none READ + VOLUME_BACKUP_ UPDATE UpdateVolumeBackup (also need inspect volumes) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + none USE + VOLUME_BACKUP_ CREATE CreateVolumeBackup (also need use volumes) VOLUME_BACKUP_ DELETE DeleteVolumeBackup (also need inspect volumes) Permissions Required for Each API Operation The following table lists the Core Services API operations grouped by resource type, which are listed in alphabetical order. For information about permissions, see Permissions. Oracle Bare Metal Cloud Services User Guide 478 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 DeleteCrossConnect CROSS_CONNECT_DELETE if cross-connect is not in a crossconnect group. If the cross-connect is in a cross-connect group, also need CROSS_ CONNECT_DELETE and CROSS_CONNECT_DETACH Oracle Bare Metal Cloud Services User Guide 479 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 ListDrgAttachments DRG_ATTACHMENT_READ GetDrgAttachment DRG_ATTACHMENT_READ UpdateDrgAttachment DRG_ATTACHMENT_UPDATE CreateDrgAttachment DRG_ATTACH and VCN_ATTACH DeleteDrgAttachment DRG_DETACH and VCN_DETACH Oracle Bare Metal Cloud Services User Guide 480 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 GetInstance INSTANCE_GET LaunchInstance INSTANCE_CREATE and IMAGE_READ and VNIC_CREATE 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 Oracle Bare Metal Cloud Services User Guide 481 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 GetIPSecConnectionDeviceStatus IPSEC_CONNECTION_READ ListRouteTables ROUTE_TABLE_READ GetRouteTable ROUTE_TABLE_READ UpdateRouteTable ROUTE_TABLE_UPDATE CreateRouteTable ROUTE_TABLE_CREATE and VCN_ATTACH 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 Oracle Bare Metal Cloud Services User Guide 482 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 CreateVcn VCN_CREATE 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 crossconnect 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 ListVnicAttachments VNIC_ATTACHMENT_READ and INSTANCE_INSPECT Oracle Bare Metal Cloud Services User Guide 483 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 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. Oracle Bare Metal Cloud Services User Guide 484 CHAPTER 7 IAM Service Resource-Types l database-family, which covers these individual resource-types: o db-systems o db-nodes o db-homes o databases 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. 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. For database-family Resource Types db-systems INSPECT Permissions APIs Fully Covered APIs Partially Covered DB_SYSTEM_INSPECT ListDbSystems none GetDbSystem READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Oracle Bare Metal Cloud Services User Guide 485 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + no extra LaunchDBSystem, TerminateDbSystem (both also need manage dbhomes, manage databases, use vnics, and use subnets) Permissions APIs Fully Covered APIs Partially Covered DB_NODE_INSPECT GetDbNode none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + none DB_NODE_POWER_ ACTIONS DbNodeAction MANAGE DB_SYSTEM_CREATE DB_SYSTEM_DELETE db-nodes INSPECT READ USE MANAGE Oracle Bare Metal Cloud Services User Guide 486 CHAPTER 7 IAM Service db-homes INSPECT Permissions APIs Fully Covered APIs Partially Covered DB_HOME_INSPECT ListDBHome none GetDBHome READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + no extra LaunchDBSystem, TerminateDbSystem (both also need manage dbsystems, manage databases, use vnics, and use subnets) Permissions APIs Fully Covered APIs Partially Covered DATABASE_INSPECT ListDatabases none USE MANAGE DB_HOME_CREATE DB_HOME_DELETE databases INSPECT GetDatabase Oracle Bare Metal Cloud Services User Guide 487 CHAPTER 7 IAM Service READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered USE + no extra LaunchDBSystem, TerminateDbSystem (both also need manage dbsystems, manage dbhomes, use vnics, and use subnets) USE MANAGE DATABASE_CREATE DATABASE_DELETE 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 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 TerminateDbSystem DB_SYSTEM_DELETE and DB_HOME_DELETE and DATABASE_DELETE and VNIC_DETACH and VNIC_DELETE and SUBNET_DETACH GetDbNode DB_NODE_INSPECT Oracle Bare Metal Cloud Services User Guide 488 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation DbNodeAction DB_NODE_POWER_ACTIONS ListDbHomes DB_HOME_INSPECT GetDbHome DB_HOME_INSPECT ListDatabases DATABASE_INSPECT GetDatabase DATABASE_INSPECT ListDbSystemShapes (no permissions required; available to anyone) ListDbVersions (no permissions required; available to anyone) Details for the IAM Service This topic covers details for writing policies to control access to the IAM Service. Resource-Types l compartments l users l groups l policies l identity-providers l tenancy Supported Variables The IAM Service supports all the general variables (see General Variables for All Requests), plus additional ones listed here: Oracle Bare Metal Cloud Services User Guide 489 CHAPTER 7 IAM Service Operations for This ResourceType... Can Use These Variables... Variable Type Comments users target .user.id Entity (OCID) Not available to use with CreateUser. target .user.name String target .group.id Entity (OCID) target .group.name String target . group .member Boolean True if request.user is a member of target.group. target .policy.id Entity (OCID) Not available to use with CreatePolicy. target . policy.name String target . policy .autoupdate Boolean groups policies Oracle Bare Metal Cloud Services User Guide Not available to use with CreateGroup. Whether the policy being acted upon uses "Keep policy current" as its version date (i.e., either null or an empty string for the versionDate parameter in CreatePolicy and UpdatePolicy). 490 CHAPTER 7 IAM Service Operations for This ResourceType... Can Use These Variables... Variable Type Comments compartments target. compartment .id Entity (OCID) For CreateCompartment, this will be the value of the parent compartment (e.g., the root compartment). target. compartment .name String This is a universal variable available to use with any request across all services (see General Variables for All Requests). Details for Verbs + 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. 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 COMPARTMENT_CREATE permission and two API operations: CreateCompartment and DeleteCompartment compartments INSPECT Permissions APIs Fully Covered APIs Partially Covered COMPARTMENT_INSPECT ListCompartments none GetCompartment READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Oracle Bare Metal Cloud Services User Guide 491 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + none COMPARTMENT_UPDATE UpdateCompartment MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + none COMPARTMENT_CREATE CreateCompartment DeleteCompartment users INSPECT Permissions APIs Fully Covered APIs Partially Covered USER_INSPECT ListUsers GetUserGroupMembership (also need inspect groups) GetUser READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + INSPECT + no extra USER_READ ListApiKeys ListSwiftPasswords Oracle Bare Metal Cloud Services User Guide 492 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + READ + USER_UPDATE UpdateUser AddUserToGroup (also need use groups) RemoveUserFromGroup (also need use groups) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + no extra USER_CREATE UpdateUserState USER_DELETE CreateUser USER_UNBLOCK DeleteUser USER_APIKEY_ADD UploadApiKey USER_APIKEY_REMOVE DeleteApiKey USER_UIPASS_SET CreateOrResetUIPasswor d USER_UIPASS_RESET USER_SWIFTPASS_SET USER_SWIFTPASS_RESET USER_SWIFTPASS_ REMOVE UpdateSwiftPassword CreateSwiftPassword DeleteSwiftPassword Oracle Bare Metal Cloud Services User Guide 493 CHAPTER 7 IAM Service groups INSPECT Permissions APIs Fully Covered APIs Partially Covered GROUP_INSPECT ListGroups GetUserGroupMembership (also need inspect users) GetGroup ListIdpGroupMappings, GetIdpGroupMapping (both also need inspect identity-providers) READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered READ + READ + READ + GROUP_UPDATE UpdateGroup AddUserToGroup (also need use users) USE RemoveUserFromGroup (also need use users) AddIdpGroupMapping, DeleteIdpGroupMapping (both also need manage identity-providers) MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + no extra GROUP_CREATE CreateGroup GROUP_DELETE DeleteGroup Oracle Bare Metal Cloud Services User Guide 494 CHAPTER 7 IAM Service policies INSPECT Permissions APIs Fully Covered APIs Partially Covered POLICY_READ ListPolicies none GetPolicy READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered no extra no extra none USE Note: The ability to update policies is available only with manage policies. MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + none POLICY_UPDATE UpdatePolicy POLICY_CREATE CreatePolicy POLICY_DELETE DeletePolicy Oracle Bare Metal Cloud Services User Guide 495 CHAPTER 7 IAM Service identity-providers INSPECT Permissions APIs Fully Covered APIs Partially Covered IDENTITY_PROVIDER_ INSPECT ListIdentityProviders GetIdentityProvider ListIdpGroupMappings, GetIdpGroupMapping (both also need inspect groups) Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered no extra no extra no extra Permissions APIs Fully Covered APIs Partially Covered USE + USE + USE + IDENTITY_PROVIDER_ UPDATE UpdateIdentityProvider AddIdpGroupMapping, DeleteIdpGroupMapping (both also need use groups) READ USE MANAGE IDENTITY_PROVIDER_ CREATE CreateIdentityProvider DeleteIdentityProvider IDENTITY_PROVIDER_ DELETE Oracle Bare Metal Cloud Services User Guide 496 CHAPTER 7 IAM Service tenancy INSPECT Permissions APIs Fully Covered APIs Partially Covered TENANCY_INSPECT ListRegionSubscription s none GetTenancy ListRegions READ Permissions APIs Fully Covered APIs Partially Covered no extra no extra none Permissions APIs Fully Covered APIs Partially Covered READ + no extra none Permissions APIs Fully Covered APIs Partially Covered USE + USE + none TENANCY_UPDATE CreateRegionSubscripti on USE TENANCY_UPDATE 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. Oracle Bare Metal Cloud Services User Guide 497 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 ListSwiftPasswords USER_READ Oracle Bare Metal Cloud Services User Guide 498 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation UpdateSwiftPassword USER_UPDATE and USER_SWIFTPASS_RESET CreateSwiftPassword USER_UPDATE and USER_SWIFTPASS_SET DeleteSwiftPassword USER_UPDATE and USER_SWIFTPASS_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 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 Oracle Bare Metal Cloud Services User Guide 499 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 Details for the Load Balancing Service This topic covers details for writing policies to control access to the Load Balancing Service. Resource-Types l load-balancers 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.. 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 another permission and set of API operations compared to read. And manage covers two more permissions and operations compared to use. Oracle Bare Metal Cloud Services User Guide 500 CHAPTER 7 IAM Service load-balancers INSPECT Permissions APIs Fully Covered APIs Partially Covered LOAD_BALANCER_ INSPECT ListLoadBalancers none ListShapes ListPolicies ListProtocols READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + INSPECT + none LOAD_BALANCER_READ GetLoadBalancer ListWorkRequests GetWorkRequest ListBackendSets GetBackendSet ListBackends GetBackend GetHealthChecker ListCertificates Oracle Bare Metal Cloud Services User Guide 501 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + none LOAD_BALANCER_ UPDATE UpdateLoadBalancer UpdateBackendSet CreateBackendSet DeleteBackendSet UpdateBackend CreateBackend DeleteBackend UpdateHealthChecker CreateCertificate DeleteCertificate UpdateListener CreateListener DeleteListener MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + none LOAD_BALANCER_ CREATE CreateLoadBalancer DeleteLoadBalancer LOAD_BALANCER_ DELETE 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. Oracle Bare Metal Cloud Services User Guide 502 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 GetHealthChecker LOAD_BALANCER_READ UpdateHealthChecker LOAD_BALANCER_UPDATE Oracle Bare Metal Cloud Services User Guide 503 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation 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 the Object Storage Service This topic covers details for writing policies to control access to the Object Storage Service. Resource-Types l object-family, which covers these individual resource-types: o buckets o objects Supported Variables The Object Storage Service supports all the general variables (see General Variables for All Requests), plus the one listed here: Oracle Bare Metal Cloud Services User Guide 504 CHAPTER 7 IAM Service Operations for This ResourceType... Can Use This Variable Variable Type Comments 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 Service Buckets. 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. 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 Permissions APIs Fully Covered APIs Partially Covered BUCKET_INSPECT HeadBucket none ListBuckets READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + INSPECT + none BUCKET_READ GetBucket ListMultipartUploads Oracle Bare Metal Cloud Services User Guide 505 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + none BUCKET_UPDATE UpdateBucket MANAGE Permissions APIs Fully Covered APIs Partially Covered USE + USE + none BUCKET_CREATE CreateBucket BUCKET_DELETE DeleteBucket PAR_MANAGE CreatePar GetPar ListPar DeletePar objects INSPECT Permissions APIs Fully Covered APIs Partially Covered OBJECT_INSPECT HeadObject none ListObjects ListMultipartUploadPar ts READ Permissions APIs Fully Covered APIs Partially Covered INSPECT + INSPECT + none OBJECT_READ GetObject Oracle Bare Metal Cloud Services User Guide 506 CHAPTER 7 IAM Service USE Permissions APIs Fully Covered APIs Partially Covered READ + READ + READ + OBJECT_OVERWRITE OverwriteObject CreateMultipartUpload, UploadPart, CommitMultipartUpload (all also need manage objects) Permissions APIs Fully Covered APIs Partially Covered USE + USE + none OBJECT_CREATE CreateObject OBJECT_DELETE DeleteObject MANAGE CreateMultipartUpload UploadPart CommitMultipartUpload AbortMultipartUpload 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 CreateBucket BUCKET_CREATE UpdateBucket BUCKET_UPDATE GetBucket BUCKET_READ Oracle Bare Metal Cloud Services User Guide 507 CHAPTER 7 IAM Service API Operation Permissions Required to Use the Operation HeadBucket BUCKET_INSPECT ListBuckets BUCKET_INSPECT DeleteBucket BUCKET_DELETE CreateObject OBJECT_CREATE 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 Oracle Bare Metal Cloud Services User Guide 508 CHAPTER 7 IAM Service User Credentials There are three types of credentials that you manage with the Oracle Bare Metal Cloud Identity and Access Management Service (IAM): l l l Console password: For signing in to the Console, the user interface for interacting with Oracle Bare Metal Cloud Services API signing key (in PEM format): For sending API requests, which require authentication Swift password: For using a Swift client with Recovery Manager (RMAN) to back up an Oracle Database System (DB System) database to the Object Storage 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 the IAM Service 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. 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 Bare Metal Cloud Services 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. Oracle Bare Metal Cloud Services User Guide 509 CHAPTER 7 IAM Service 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. 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 the IAM Service 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. Oracle Bare Metal Cloud Services User Guide 510 CHAPTER 7 IAM Service 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 System) database to the Object Storage Service. 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 Bare Metal Cloud Services supports federation with Oracle Identity Cloud Service as the provider, 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services resources. To federate, an administrator goes through a short process to set up a relationship between the IdP and Oracle Bare Metal Cloud Services (commonly referred to as a federation trust). After an administrator sets up that relationship, any person in your company who goes to the Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services. 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 Bare Metal Cloud Services also uses the concept of groups (in conjunction with IAM Service policies) to define the type of access a user has. As part of setting up the Oracle Bare Metal Cloud Services User Guide 511 CHAPTER 7 IAM Service relationship with the IdP, your administrator can map each IdP group to a similarly defined IAM Service group, so that your company can re-use the IdP group definitions when authorizing user access to Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services supports identity federation with Oracle Identity Cloud Service. Service provider (SP) A service (such as an application, website, etc.) that calls upon an IdP to authenticate users. In this case, Oracle Bare Metal Cloud Services is the SP. Federation trust A relationship that an administrator configures between an IdP and SP. You can use the Oracle Bare Metal Oracle Bare Metal Cloud Services User Guide 512 CHAPTER 7 IAM Service Cloud Services 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. Metadata URL An IdP-provided URL that enables an SP to get required information to federate with that IdP. Oracle Bare Metal Cloud Services 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 set of XML the SP needs. Federated user Someone who signs in to use the Oracle Bare Metal Cloud Services Console by way of a federated IdP. Oracle BMCS user A non-federated user. In other words, someone who signs in to use the Oracle Bare Metal Cloud Services Console with a login and password created in Oracle Bare Metal Cloud Services. Group mapping A mapping between an IdP group and an Oracle Bare Metal Cloud Services group, used for the purposes of user authorization. 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 Bare Metal Cloud Services, but each federation trust that you set up must be for a single Identity Cloud Service account. Web 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 Bare Metal Cloud Services, 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 Bare Metal Cloud Services 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: Oracle Bare Metal Cloud Services User Guide 513 CHAPTER 7 IAM Service 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: 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 Bare Metal Cloud Services, a new SAML application called BMCS-SAML-App 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 Bare Metal Cloud Services tenancy, make sure to also delete the BMCS-SAML-App 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-SAMLApp). Experience for Federated Users Federated users can use the Console to access Oracle Bare Metal Cloud Services (according to the IAM Service policies for the groups the users are in). The URL where they sign in is https://console.us-phoenix-1.oraclecloud.com. Oracle Bare Metal Cloud Services User Guide 514 CHAPTER 7 IAM Service They'll be prompted to enter their Oracle Bare Metal Cloud Services 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 BMCS) 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 password, they are authenticated by the IdP and redirected back to the Oracle Bare Metal Cloud Services Console. Unlike Oracle BMCS 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 Bare Metal Cloud Services credentials such as API signing keys and Swift passwords. Oracle Bare Metal Cloud Services User Guide 515 CHAPTER 7 IAM Service Required IAM Service Policy To add and manage identity providers in your tenancy, you must be authorized by an IAM Service 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 If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for groups or other IAM Service components, see Details for the IAM Service. 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 Bare Metal Cloud user with the required credentials and access. 1. Get required information from the IdP. 2. Federate the IdP with Oracle Bare Metal Cloud Services: a. Add the identity provider to your tenancy and provide information you got from the IdP. b. Map the IdP's groups to IAM Service groups. 3. Make sure you have IAM Service policies set up for the groups so you can control users' access to Oracle Bare Metal Cloud Services resources. 4. Inform your users of the name of your Oracle Bare Metal Cloud Services tenant and the URL for the Console (https://console.us-phoenix-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. Oracle Bare Metal Cloud Services User Guide 516 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services 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. 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services Summary: Add the identity provider to your tenancy. You can set up the group mappings at the same time, or set them up later. Oracle Bare Metal Cloud Services User Guide 517 CHAPTER 7 IAM Service Instructions for Oracle Identity Cloud Service: 1. Go to the Console at https://console.us-phoenix-1.oraclecloud.com and sign in with your Oracle Bare Metal Cloud Services login and password. 2. Click Identity, and then click Federation. 3. Click Add identity provider. 4. Enter the following: 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. 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 Service groups in Oracle Bare Metal Cloud Services. 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 Service 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 Service group you want to map from the list under Oracle BMCS Group. If you instead want to create a new IAM Service group, select New BMCS Group and enter the name of Oracle Bare Metal Cloud Services User Guide 518 CHAPTER 7 IAM Service the new group in New BMCS Group Name. The new group will be automatically created in the IAM Service and mapped to the Oracle Identity Cloud Service group. It will also automatically be given this description, which you can't change: "Group created during federation". Requirements for the IAM Service 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 Service policies for the groups If you haven't already, set up IAM Service policies to control the access the federated users have to your organization's Oracle Bare Metal Cloud Services 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 Bare Metal Cloud Services Console (https://console.usphoenix-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 Instructions for Federating. Oracle Bare Metal Cloud Services User Guide 519 CHAPTER 7 IAM Service 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. Locate the BMCS-SAML-App and click X Remove. To add group mappings for an identity provider 1. Open the Console, click Identity, and then click Federation. A list of the identity providers in your tenancy is displayed. 2. Click the identity provider to view its details. 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 Service group you want to map from the list under Oracle BMCS Group. If you instead want to create a new IAM Service group, select New BMCS Group and enter the name of the new group in New BMCS Group Name. The new group will be automatically created in the IAM Service and mapped to the 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. Oracle Bare Metal Cloud Services User Guide 520 CHAPTER 7 IAM Service 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 1. Open the Console, click Identity, and then click Federation. A list of the identity providers in your tenancy is displayed. 2. Click the identity provider to view its details. 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. Update the mappings (or click the X to delete a mapping), 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 delete a group mapping 1. Open the Console, click Identity, and then click Federation. A list of the identity providers in your tenancy is displayed. 2. Click the identity provider to view its details. 3. For the mapping you want to delete, click Delete next to it. 4. Confirm when prompted. Your changes take effect typically within seconds in your home region. Wait several more minutes for changes to propagate to all regions. Managing Identity Providers in 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. Use these API operations: Identity providers: Oracle Bare Metal Cloud Services User Guide 521 CHAPTER 7 IAM Service 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 l GetIdpGroupMapping l UpdateIdpGroupMapping l DeleteIdpGroupMapping Oracle Bare Metal Cloud Services User Guide 522 CHAPTER 7 IAM Service Managing Users This topic describes the basics of working with users. Required IAM Service 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. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for users or other IAM Service components, see Details for the IAM Service. 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. Oracle Bare Metal Cloud Services User Guide 523 CHAPTER 7 IAM Service 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 Bare Metal Cloud Services. A user can have one or both of the following credentials, depending on the type 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. 3. Enter the following: l 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. Description: This could be the user's full name, a nickname, or other descriptive information. You can change this later if you want to. 4. Click Create. 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). Oracle Bare Metal Cloud Services User Guide 524 CHAPTER 7 IAM Service To add a user to a group 1. Open the Console, click Identity, and then click Users. A list of the users in your tenancy is displayed. 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 1. Open the Console, click Identity, and then click Users. A list of the users in your tenancy is displayed. 2. Locate the user in the list. 3. Click the user. Its details are displayed. 4. Click Groups. 5. Click the Actions icon ( ) and then click Remove. 6. Confirm when prompted. To delete a user Prerequisite: To delete a user, the user must not be in any groups. 1. Open the Console, click Identity, and then click Users. A list of the users in your tenancy is displayed. 2. For the user you want to delete, click Delete. 3. Confirm when prompted. Oracle Bare Metal Cloud Services User Guide 525 CHAPTER 7 IAM Service 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. 1. Open the Console, click Identity, and then click Users. A list of the users in your tenancy is displayed. 2. Click the user. Its details are displayed, including the current status. 3. Click Unblock. 4. Confirm when prompted. To change a user's description 1. Open the Console, click Identity, and then click Users. A list of the users in your tenancy is displayed. 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. For information about managing user credentials in the Console, see Managing User Credentials. 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. 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. Oracle Bare Metal Cloud Services User Guide 526 CHAPTER 7 IAM Service l l DeleteUser 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. Oracle Bare Metal Cloud Services User Guide 527 CHAPTER 7 IAM Service Managing Groups This topic describes the basics of working with groups. Required IAM Service 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. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for groups or other IAM Service components, see Details for the IAM Service. 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 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 because they'll have different OCIDs. 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, the IAM Service 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 Service groups. For more information, see Identity Providers and Federation. Oracle Bare Metal Cloud Services User Guide 528 CHAPTER 7 IAM Service Using the Console To create a 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. 3. Enter the following: l l Name: A unique name for the group. The name must be unique across all groups in your tenancy. You cannot change this later. Description: A friendly description. You can change this later if you want to. 4. Click Create Group. 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 1. Open the Console, click Identity, and then click Groups. A list of the groups in your tenancy is displayed. 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 1. Open the Console, click Identity, and then click Groups. A list of the groups in your tenancy is displayed. 2. Locate the group in the list. 3. Click the group to display its details. A list of users in the group is displayed. 4. Locate the user in the list. Oracle Bare Metal Cloud Services User Guide 529 CHAPTER 7 IAM Service 5. For the user you want to remove, click Remove. 6. Confirm when prompted. To delete a group Prerequisite: To delete a group, it must not have any users in it. 1. Open the Console, click Identity, and then click Groups. A list of the groups in your tenancy is displayed. 2. Locate the group in the list. 3. For the group you want to delete, click Delete. 4. Confirm when prompted. 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. 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. 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. l AddUserToGroup: This operation results in a UserGroupMembership object with its own OCID. l GetUserGroupMembership l RemoveUserFromGroup: This operation deletes a UserGroupMembership object. Oracle Bare Metal Cloud Services User Guide 530 CHAPTER 7 IAM Service For API operations related to group mappings for identity providers, see Identity Providers and Federation. Oracle Bare Metal Cloud Services User Guide 531 CHAPTER 7 IAM Service Managing Compartments This topic describes the basics of working with compartments. Required IAM Service Policy If you're in the Administrators group, then you have the required access for managing compartments. For an additional policy related to compartment management, see Let a Compartment Admin Manage the Compartment. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for compartments or other IAM Service components, see Details for the IAM Service. Working with Compartments When you first start working with Oracle Bare Metal Cloud Services, 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 or renamed, 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 Bare Metal Cloud Services 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 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, non-changeable 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 (although it can be an empty string), which is a non-unique, changeable description for the 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 Oracle Bare Metal Cloud Services User Guide 532 CHAPTER 7 IAM Service 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 Service 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. For information about the number of compartments you can have, see Service Limits. Using the Console To create a compartment Remember: Compartments can't be renamed or deleted. 1. Open the Console, click Identity, and then click Compartments. A list of the compartments in your tenancy is displayed. 2. Click Create Compartment. 3. Enter the following: l 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. Description: A friendly description. You can change this later if you want to. 4. Click Create Compartment. Next, you might want to write a policy for the compartment. See To create a policy. To update a compartment's description This is available only through the API. If you don't have access to the API and need to update a compartment's Oracle Bare Metal Cloud Services User Guide 533 CHAPTER 7 IAM Service description, contact Oracle Support. 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 Service 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. Remember that most IAM Service resources reside in the tenancy (this includes users, groups, and compartments). Policies can reside in either the tenancy (root compartment) or other compartments. 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. 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 only the compartment's description. 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 Regions This topic describes the basics of managing your region subscriptions. For more information about regions in Oracle Bare Metal Cloud Services, see Regions and Availability Domains. Oracle Bare Metal Cloud Services User Guide 534 CHAPTER 7 IAM Service Required IAM Service Policy If you're in the Administrators group, then you have the required access to manage region subscriptions. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for managing regions or other IAM Service components, see Details for the IAM Service. The Home Region When you sign up for Oracle Bare Metal Cloud Services, Oracle creates a tenancy for you in the PHX (Phoenix, AZ) region. This is your home region. Your home region is where your IAM Service resources are defined. When you subscribe to a new region, your IAM Service 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 or update only in the home region are: l Users l Groups l Policies l Compartments l Federation resources When you use the API to update your IAM Service resources, you must use the endpoint for your home region. The IAM Service automatically propagates the updates to all regions in your tenancy. When you use the Console to update your IAM Service resources, the Console sends the requests to the home region for you. You don't need to switch to your home region first. The IAM Service then automatically propagates the updates to all regions in your tenancy. When you subscribe 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. Oracle Bare Metal Cloud Services User Guide 535 CHAPTER 7 IAM Service Updates Are Not Immediate Across All Regions When you create or update an IAM Service 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. 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 Bare Metal Cloud Services 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 Bare Metal Cloud Services is displayed. 2. Locate the region you want to subscribe to and click Subscribe to Region. Note that it may take several minutes to activate your tenancy in the new region. Remember, your IAM Service 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 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. Use these API operations to manage regions: l GetTenancy l ListRegions: Returns a list of regions offered by Oracle Bare Metal Cloud Services. Oracle Bare Metal Cloud Services User Guide 536 CHAPTER 7 IAM Service 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 Service polices are enforced in the new region, so all users in the tenancy will have the same access and permissions in the new region as soon as the region subscription becomes active. 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 Service 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 at 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. For example, if your limit for the VM.Standard1.1 shape is five per Availability Domain, you get five for each Availability Domain in the new region (in addition to the five for each Availability Domain in your existing region). 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. Can I change my home region? No. Phoenix is the home region for all tenancies. Oracle Bare Metal Cloud Services User Guide 537 CHAPTER 7 IAM Service Managing Policies This topic describes the basics of working with policies. Required IAM Service Policy If you're in the Administrators group, then you have the required access for managing policies. If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies to control who else can write policies or manage other IAM Service components, see Let a Compartment Admin Manage the Compartment, and also Details for the IAM Service. 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 must specify its version date. For more information, see Policy Language Version. You can change the version date later if you like. 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 (although it can be an empty string), which is a non-unique, changeable description for the 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 because they'll have different OCIDs. 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. Oracle Bare Metal Cloud Services User Guide 538 CHAPTER 7 IAM Service 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 in the Console or API. 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. 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). 3. Click Create Policy. 4. Enter the following: l l l l Name: A unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later. Description: A friendly description. You can change this later if you want to. 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. 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 +. 5. Click Create. The new policy will go into effect typically within 10 seconds. Oracle Bare Metal Cloud Services User Guide 539 CHAPTER 7 IAM Service 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 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 1. Open the Console, click Identity, and then click Policies. A list of the policies 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. 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 1. 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 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). 2. Click the policy you want to update. The policy's details, version date, and statements are displayed. 3. Click Update Version Date. Oracle Bare Metal Cloud Services User Guide 540 CHAPTER 7 IAM Service 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. Your changes will go into effect typically within 10 seconds. To delete a policy 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. 1. Open the Console, click Identity, and then click Policies. A list of the policies 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. For the policy you want to delete, click Delete. 3. Confirm when prompted. Your changes will go into effect typically within 10 seconds. 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. Use these API operations to manage policies: l CreatePolicy l ListPolicies l GetPolicy l UpdatePolicy l DeletePolicy Oracle Bare Metal Cloud Services User Guide 541 CHAPTER 7 IAM Service Managing User Credentials This topic describes the basics of working with Oracle Bare Metal Cloud Identity and Access Management Service (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 and Swift passwords. 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 Service 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 l Reset their own password with CreateOrResetUIPassword. 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. A user can have a maximum of three API keys at a time. Oracle Bare Metal Cloud Services User Guide 542 CHAPTER 7 IAM Service 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 the Object Storage Service. 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 Bare Metal Cloud Services 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 the Object Storage Service 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 the Object Storage Service, 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. 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. Oracle Bare Metal Cloud Services User Guide 543 CHAPTER 7 IAM Service 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. 1. View the user's details: l 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. If you're an administrator creating or resetting another user's password: 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 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 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. Oracle Bare Metal Cloud Services User Guide 544 CHAPTER 7 IAM Service Important: The API key must be an RSA key in PEM format (minimum 2048 bits). The PEM format looks something like this: -----BEGIN PUBLIC KEY----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF... ... -----END PUBLIC KEY—— For more information about generating a public PEM key, see Required Keys and OCIDs. 1. View the user's details: l l If you're uploading an 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. 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 The following procedure works for a regular user or an administrator. Administrators can delete an API key for either another user or themselves. 1. View the user's details: l If you're deleting an 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. Oracle Bare Metal Cloud Services User Guide 545 CHAPTER 7 IAM Service 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. 3. Confirm when prompted. The API key is no longer valid for sending API requests. To create a Swift password 1. View the user's details: l 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. 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. 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 The following procedure works for a regular user or an administrator. Administrators can delete a Swift password for either another user or themselves. 1. View the user's details: l l If you're deleting 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. If you're an administrator deleting 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. Oracle Bare Metal Cloud Services User Guide 546 CHAPTER 7 IAM Service 3. For the Swift password you want to delete, click Delete. 4. Confirm when prompted. The Swift password is no longer valid for accessing Object Storage Service. 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. Use this API operation to manage Console passwords and access: l 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. 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 l CreateSwiftPassword UpdateSwiftPassword: You can only update the Swift password's description, not change the password string itself. l ListSwiftPasswords l DeleteSwiftPassword Oracle Bare Metal Cloud Services User Guide 547 CHAPTER 8 Load Balancing Service This chapter explains how to set up a load balancer. Overview of the Load Balancing Service The Oracle Bare Metal Cloud 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 the Load Balancing Service 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 stand-by load balancer to ensure accessibility even during an Availability Domain outage. The load balancer attaches a public IP address to one of the specified subnets. If there is a failure in that subnet's Availability Domain, the load balancer and IP address switch to the other subnet. The service treats the two load balancer subnets as equivalent and you cannot denote one as "primary". You cannot specify a private subnet for your public load balancer. Oracle Bare Metal Cloud Services User Guide 548 CHAPTER 8 Load Balancing Service Private Load Balancer To isolate your load balancer from the internet and simplify your security posture, you 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 stand-by load balancers. The assigned 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. The primary and stand-by load balancers exist within the same subnet. 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 Managing 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. Oracle Bare Metal Cloud Services User Guide 549 CHAPTER 8 Load Balancing Service 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. Oracle Bare Metal Cloud Services User Guide 550 CHAPTER 8 Load Balancing Service The following diagram provides a high-level view of a simple public load balancing system configuration. Far more sophisticated and complex configurations are common. Oracle Bare Metal Cloud Services User Guide 551 CHAPTER 8 Load Balancing Service Load Balancing Concepts The following concepts are essential to working with the Load Balancing Service. 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. 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. Oracle Bare Metal Cloud Services User Guide 552 CHAPTER 8 Load Balancing Service 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 HTTPlevel health checks for your backend servers. l l TCP-level health checks attempt to make a TCP connection with the backend servers and validate the response based on the connection status. 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 application availability and reduce your application maintenance window. For more information, see Editing Health Check Policies. Listener An 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 For more information, see Managing Load Balancer Listeners. Oracle Bare Metal Cloud Services User Guide 553 CHAPTER 8 Load Balancing Service 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. 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. 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. The Load Balancing Service 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 Oracle Bare Metal Cloud Services User Guide 554 CHAPTER 8 Load Balancing Service l DHE-RSA-AES256-SHA256 l DHE-RSA-AES128-GCM-SHA256 l DHE-RSA-AES128-SHA256 For more information, see Managing SSL Certificates. 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. 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 and 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. For more information on subnets, See Managing Subnets and Public and Private Subnets. 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 in the private IP address ranges specified in RFC 1918 (10.0.0.0/8, 172.16/12, and 192.168/16). 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 the Networking Service. 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 Service 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. Oracle Bare Metal Cloud Services User Guide 555 CHAPTER 8 Load Balancing Service Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access Oracle Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. For general information about using the API, see About the API. Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service 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 Bare Metal Cloud Services 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. Limits on Load Balancing Service Resources See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Oracle Bare Metal Cloud Services User Guide 556 CHAPTER 8 Load Balancing Service 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 load balancer is limited to 100,000 concurrent connections. l Outbound traffic to the internet is limited to 2 Gbps. 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. Oracle Bare Metal Cloud Services User Guide 557 CHAPTER 8 Load Balancing Service Load balancer policy decisions apply differently to TCP load balancers, cookie-based session persistent HTTP requests (sticky requests), and non-sticky HTTP requests. l l 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. An HTTP load balancer configured to handle cookie-based session persistence forwards requests to the backend server specified by the cookie's session information. 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. 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. Oracle Bare Metal Cloud Services User Guide 558 CHAPTER 8 Load Balancing Service IP Hash ensures that requests from a particular client are always directed to the same backend server, as long as it is available. 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. 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 the Load Balancing Service 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. Oracle recommends that you treat cookie data as an opaque entity. Do not use it in your applications. Oracle Bare Metal Cloud Services User Guide 559 CHAPTER 8 Load Balancing Service 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. IP Address-driven Session Persistence Some products offer session persistence support without cookies by depending 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. 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. Oracle Bare Metal Cloud Services User Guide 560 CHAPTER 8 Load Balancing Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. Prerequisites Before you can implement a working Load Balancing Service, 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 Managing Subnets and Public and Private Subnets. You cannot specify a private subnet for your public load balancer. l l l A VCN with at least one subnet for a private load balancer. Two or more backend servers (Compute instances) running your applications. For more information on Compute instances, see Launching an Instance. A listener to detect incoming traffic. Working with Load Balancers For background information on the Oracle Bare Metal Cloud Load Balancing Service, see Overview of the Load Balancing Service. 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 the IAM Service. Oracle Bare Metal Cloud Services User Guide 561 CHAPTER 8 Load Balancing Service 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 stand-by. Each subnet must reside in a separate Availability Domain and must be publicly accessible. For more information on VCNs and subnets, see Overview of the Networking Service. 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 stand-by. 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. High-Volume Traffic Applications 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. Oracle Bare Metal Cloud Services User Guide 562 CHAPTER 8 Load Balancing Service 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 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.) 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 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. l 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. Subnet Compartment: Required, when this option appears. Specify the compartment from which to select your subnets. Oracle Bare Metal Cloud Services User Guide 563 CHAPTER 8 Load Balancing Service 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 l Subnet (1 of 2): Required. Select an available subnet. For a public load balancer, it must be a public subnet. 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 1. Open the Console, click Networking, and then click Load Balancers. 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. 4. Confirm when prompted. 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. Use these API operations to manage load balancers: l CreateLoadBalancer l DeleteLoadBalancer l DrainLoadBalancer l GetLoadBalancer l ListLoadBalancers l UpdateLoadBalancer: You can update the load balancer's display name. Oracle Bare Metal Cloud Services User Guide 564 CHAPTER 8 Load Balancing Service 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. 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 Bare Metal Cloud Load Balancing Service, see Overview of the Load Balancing Service. Oracle Bare Metal Cloud Services User Guide 565 CHAPTER 8 Load Balancing Service Using the Console To create a backend set 1. Open the Console, click Networking, and then click Load Balancers. 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 l Name: Required. Specify a friendly name for the backend set. It must be unique within the load balancer, and it cannot be changed. 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 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. 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. Oracle Bare Metal Cloud Services User Guide 566 CHAPTER 8 Load Balancing Service 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. 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. o Timeout in ms: Optional. Specify the maximum timeout in milliseconds before a retry. o Number of retries: Optional. Specify the number of retries to attempt before a backend server is considered "unhealthy". 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 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. 1. Open the Console, click Networking, and then click Load Balancers. 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). 4. Click the name of the backend set you want to edit. Oracle Bare Metal Cloud Services User Guide 567 CHAPTER 8 Load Balancing Service 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 You cannot delete a backend set used by an active listener. First, remove any backend sets you want to delete from the associated listeners. 1. Open the Console, click Networking, and then click Load Balancers. 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). 4. For the backend set you want to delete, click the Actions icon ( ), and then click Delete. 5. Confirm when prompted. 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. Use these API operations to manage load balancer backend sets: l CreateBackendSet l DeleteBackendSet l GetBackendSet l ListBackendSets l UpdateBackendSet Oracle Bare Metal Cloud Services User Guide 568 CHAPTER 8 Load Balancing Service 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. 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, the Load Balancing Service 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. 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. Oracle Bare Metal Cloud Services User Guide 569 CHAPTER 8 Load Balancing Service High-Volume Traffic Applications 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. Using the Console To add one or more servers to a backend set 1. Open the Console, click Networking, and then click Load Balancers. 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. Click the name of the backend set to which you want to add one or more backend servers. 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 l l 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. 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. Port: Required. Specify the server port to which the load balancer must direct traffic. 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. Oracle Bare Metal Cloud Services User Guide 570 CHAPTER 8 Load Balancing Service 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 1. Open the Console, click Networking, and then click Load Balancers. 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. 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 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. 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. Oracle Bare Metal Cloud Services User Guide 571 CHAPTER 8 Load Balancing Service 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 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. Working with Listeners A listener is an 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. Oracle Bare Metal Cloud Services User Guide 572 CHAPTER 8 Load Balancing Service High-Volume Traffic Applications 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 per listener. You can configure two listeners, one each for ports 443 and 8443, and associate SSL certificates with each listener. For more information about SSL certificates for load balancers, see Managing SSL Certificates. Using the Console To create a listener 1. Open the Console, click Networking, and then click Load Balancers. 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 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. 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 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. Backend Set: Required. Specify the backend set to which the listener applies. 5. Click Create. When you create a listener, you must also update your VCN's security list rules to allow traffic to that listener. Oracle Bare Metal Cloud Services User Guide 573 CHAPTER 8 Load Balancing Service To edit a listener 1. Open the Console, click Networking, and then click Load Balancers. 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 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 1. Open the Console, click Networking, and then click Load Balancers. 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 Listeners (if necessary). 4. For the listener you want to delete, click Delete. 5. Confirm when prompted. 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. Use these API operations to manage listeners: l CreateListener l DeleteListener l UpdateListener 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. Oracle Bare Metal Cloud Services User Guide 574 CHAPTER 8 Load Balancing Service Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. Working with SSL Certificates With the Oracle Bare Metal Cloud Load Balancing Service, you can optionally terminate SSL at the load balancer or implement end to end SSL. 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 certificates. l l To terminate SSL at the load balancer, you must create a listener at a default port such as 443, and then associate an uploaded certificate bundle with the listener. For end to end SSL, you must associate uploaded certificate bundles with both the listener and the backend set. Upload the certificate bundles you want to use before you create the listeners or backend sets you want to associate them with. Using the Console To upload an SSL certificate bundle to your load balancing system 1. Open the Console, click Networking, and then click Load Balancers. 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. Click the load balancer you want to configure. Oracle Bare Metal Cloud Services User Guide 575 CHAPTER 8 Load Balancing Service 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.) l Certificate: Required. Paste the certificate, in PEM format, in this field. l CA Certificate: Optional. Paste the Certificate Authority certificate (root CA certificate) in this field. l Private Key: Required. Paste the private key for the certificate in this field. l Passphrase: Required only if your private key is encrypted. Specify a passphrase. 6. Click Add Certificate. To delete an SSL certificate bundle from your load balancing system 1. Open the Console, click Networking, and then click Load Balancers. 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. 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. 6. Confirm when prompted. 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. Use these API operations to manage load balancer certificates: l CreateCertificate l DeleteCertificate l ListCertificates Oracle Bare Metal Cloud Services User Guide 576 CHAPTER 8 Load Balancing Service Editing Health Check Policies This topic describes how to modify health check policies for a backend set. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. 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 HTTPlevel health checks for your backend servers. l l TCP-level health checks attempt to make a TCP connection with the backend servers and validate the response based on the connection status. 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 application availability and reduce your application maintenance window. Oracle Bare Metal Cloud Services User Guide 577 CHAPTER 8 Load Balancing Service Using the Console You create your health check tests when you create a backend set. To edit an existing health check policy 1. Open the Console, click Networking, and then click Load Balancers. 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). 4. For the backend set you want to modify, click the Actions icon ( Details. ), and then click View Backend Set 5. Click Update Health Check. 6. In the Health Check section, specify the test parameters to confirm the health of backend servers. 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. 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: Optional. Specify how frequently to run the health check. l Timeout in ms: Optional. Specify the maximum timeout in milliseconds before a retry. l l l Number of retries: Optional. Specify the number of retries to attempt before a backend server is considered "unhealthy". Status Code: (HTTP only) Optional. Specify the status code a healthy backend server must return. Response Body Regex: (HTTP only) Optional. Provide a regular expression for parsing the response body from the backend server. Health checks require all fields to match. Your status code and response body both must match, as specified. Oracle Bare Metal Cloud Services User Guide 578 CHAPTER 8 Load Balancing Service 7. Click Save. 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. Use the UpdateBackendSet operation to modify the health check settings of an existing backend set. 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. 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 the Load Balancing Service. If you're new to policies, see Getting Started with Policies and Common Policies. Monitoring Work Requests Many of the Oracle Bare Metal Cloud 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 Oracle Bare Metal Cloud Services User Guide 579 CHAPTER 8 Load Balancing Service 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 Bare Metal Cloud Services Console consumes the REST API and is subject to the same considerations as any OBMCS client. You can view the state of a load balancing work request in the Console: 1. Open the Console, click Networking, and then click Load Balancers. 2. Click the name of the Compartment that contains the load balancer you want to 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 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. Use these operations to monitor the state of work requests: l ListWorkRequests l GetWorkRequest Oracle Bare Metal Cloud Services User Guide 580 CHAPTER 9 Networking Service This chapter explains how to set up cloud networks. Overview of the Networking Service When you work with Oracle Bare Metal Cloud Services, 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 the Oracle Bare Metal Cloud Networking Service components and typical scenarios for using a VCN. Networking Service Components The Networking Service uses virtual versions of traditional network components you might already be familiar with: 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 in the private IP address ranges specified in RFC 1918 (10.0.0.0/8, 172.16/12, and 192.168/16). The allowable VCN size range is /16 to /30. Example: 10.0.0.0/16. The terms Virtual Cloud Network, VCN, and cloud network are used interchangeably in this documentation. Subnets Subdivisions you define in a VCN (for example, 10.0.0.0/24 and 10.0.1.0/24). All instances are attached to a subnet. 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 instances 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 any instances launched into the subnet can't have public IP addresses. See Internet Access for Your VCN. 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 for Your VCN and also Typical Networking Service 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 Service components and a Oracle Bare Metal Cloud Services User Guide 581 CHAPTER 9 Networking Service router in your on-premises network to establish a connection via IPSec VPN or Oracle Bare Metal Cloud Services FastConnect. For more information, see Connectivity Choices. 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 to destinations outside the VCN. 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. 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 Managing Route Tables, Security Lists, and Managing DHCP Options. Internet Access for Your VCN For instances 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 have a route rule that directs traffic to the gateway l l The subnet must have security list rules that allow the traffic (and each instance's firewall must allow the traffic) Each instance must have a public IP address (see the next section) Oracle Bare Metal Cloud Services User Guide 582 CHAPTER 9 Networking Service 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 setting up an internet proxy in your onpremises network and then connecting that network to your VCN via a DRG (see Connectivity Choices). How IP Addresses Are Assigned During instance launch, the Networking Service assigns a private IP address from the available pool in the subnet's CIDR. You can override that behavior during instance launch and specify a particular private IP address of your choice from the subnet's available pool. If the address is already in use, the launch request will fail. During instance launch, the Networking Service also assigns a public IP address. You can override that behavior during instance launch and request to have no public IP address assigned. 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. Connectivity Choices There are two ways to connect your on-premises network to your VCN: l l IPSec VPN: Offers multiple IPSec tunnels between your existing network's edge router and the DRG that you create and attach to your VCN. Oracle Bare Metal Cloud Services FastConnect: Offers a private connection between your existing network's edge router and your DRG. Traffic does not traverse the internet. All connections come to your VCN via a single DRG that you create and attach to your VCN, using either the Console or API. Without that DRG attachment, 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 components that form the rest of the connection. You could then reattach the DRG again, or attach it to another VCN. For more information about IPSec VPNs, see Managing IPSec VPNs. For more information about Oracle Bare Metal Cloud Services FastConnect, see FastConnect Overview. Typical Networking Service Scenarios This section describes several typical scenarios for using a VCN. Oracle Bare Metal Cloud Services User Guide 583 CHAPTER 9 Networking Service Scenario A: Public Subnets This is the fastest way to try out the Networking Service. 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 (see Default Security List) l The default set of DHCP options You then launch one or more compute instances in one of the subnets. Each instance automatically 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. Oracle Bare Metal Cloud Services User Guide 584 CHAPTER 9 Networking Service 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 l l Two private subnets in separate Availability Domains (to illustrate redundancy) A virtual private network connection (IPSec VPN) to provide private communication with your onpremises network A corresponding route rule in the default route table Oracle Bare Metal Cloud Services User Guide 585 CHAPTER 9 Networking Service l l A modified default security list (see 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) The default set of DHCP options 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. Oracle Bare Metal Cloud Services User Guide 586 CHAPTER 9 Networking Service You might use this scenario, for example, if you want to extend your private database servers in your onpremises 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 Oracle Bare Metal Cloud Services User Guide 587 CHAPTER 9 Networking Service l l l l l l l An Internet Gateway so the instances in the public subnets can communicate with the internet using their public IP addresses An IPSec VPN so the instances in the private subnets can communicate securely with your on-premises network using their private IP addresses Two route tables to direct traffic out of the VCN—one for traffic to the internet and one for traffic to your onpremises network A modified default security list (see Default Security List), where you change all the existing stateful ingress rules to allow traffic only from your on-premises network's CIDR block 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) 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) The default set of DHCP options 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. Oracle Bare Metal Cloud Services User Guide 588 CHAPTER 9 Networking Service 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. Regions and Availability Domains Your VCN resides in a single Oracle Bare Metal Cloud Services 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 Oracle Bare Metal Cloud Services User Guide 589 CHAPTER 9 Networking Service 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 data centers use these public API addresses, which you should whitelist on your on-premises network: 129.146.0.0/20. Reserved IP Addresses The following IP addresses are reserved for Oracle Bare Metal Cloud Services 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). Three IP addresses in each subnet The first two IP addresses and the last one in each subnet's CIDR are reserved. Resource Identifiers Each Oracle Bare Metal Cloud Services 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. Ways to Access Oracle Bare Metal Cloud Services You can access Oracle Bare Metal Cloud Services 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. The base URL for the Console is https://console.usphoenix-1.oraclecloud.com. Oracle Bare Metal Cloud Services User Guide 590 CHAPTER 9 Networking Service When you sign up to use Oracle Bare Metal Cloud Services, you receive a customized URL for your organization. For example, https://console.us-phoenix-1.oraclecloud.com?tenant=CompanyABC. If you instead use the base URL, you’ll be prompted to specify your tenant (e.g., CompanyABC) on the sign-in page, along with your login and password. For general information about using the API, see About the API. Authentication and Authorization Each service in Oracle Bare Metal Cloud Services integrates with the IAM Service 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 Bare Metal Cloud Services 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. Limits on Your Networking Service Components See Service Limits for a list of applicable limits and instructions for requesting a limit increase. Each VCN and subnet must be in the private IP address ranges specified in RFC 1918 (10.0.0.0/8, 172.16/12, and 192.168/16). The allowable VCN size range is /16 to /30. The VCN must not overlap with your on-premises network. The subnets must not overlap with each other. After you've created a VCN or subnet, you can't change its size. 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 Oracle Bare Metal Cloud Services User Guide 591 CHAPTER 9 Networking Service Ways to Secure Your Network There are several ways you can control security for your cloud network and compute instances: l l 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 Internet Access for Your VCN. Security lists: To control packet-level traffic in/out of an instance. You configure security lists in the Oracle Bare Metal Cloud Services API or Console. For more information about security lists, see Security Lists. Firewall rules: To control packet-level traffic in/out of an instance. You configure firewall rules directly on the instance itself. Notice that Oracle Bare Metal Cloud Services 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 --addport=1521/tcp sudo firewall-cmd --reload l l Gateways and route tables: To control general traffic flow from your cloud network to outside destinations (the Internet and your on-premises network). You configure your cloud network's gateways and route tables in the Oracle Bare Metal Cloud Services API or Console. For more information about the gateways, see Networking Service Components. For more information about route tables, see Managing Route Tables. IAM Service policies: To control who has access to the Oracle Bare Metal Cloud Services API or Console itself. You can control the type of access, and which cloud resources can be accessed. For Oracle Bare Metal Cloud Services User Guide 592 CHAPTER 9 Networking Service 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 Bare Metal Cloud Services API or Console. For more information, see Access Control. Access Control This topic gives basic information about using compartments and IAM Service 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 Service 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 Service 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 just starting to try out Oracle Bare Metal Cloud Services, then perhaps only one or two people may be responsible for creating and managing the VCN and its components, launching instances into the VCN, and attaching block storage volumes to those instances. Those few people need access to all of these resources, so all of 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, 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 Service 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 very 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 Bare Metal Cloud Services Getting Started Guide and Overview of the IAM Service. IAM Service Policies for the Networking Service The simplest approach to granting access to the Networking Service is the policy listed in Let Network Admins Manage a Cloud Network. It covers the cloud network and all the other Networking Service components Oracle Bare Metal Cloud Services User Guide 593 CHAPTER 9 Networking Service (subnets, security lists, route tables, gateways, etc.). To also give network admins the ability to launch instances (to test network connectivity), see Let Users Launch Instances. If you're new to policies, see Getting Started with Policies and Common Policies. If you'd like, you can write policies that focus on individual resource-types (e.g., just security lists) instead of the broader virtual-network-family. Or you can write policies that limit the level of access by using a different policy verb ( manage vs. use, etc.). If you do, there are some nuances you need to understand about the policy verbs for the Networking Service. Be aware that the inspect verb not only returns general information about the cloud network's components (e.g., the name and OCID of a security list, or of a route table). It also includes the contents of the component (e.g., the actual rules in the security list, the routes in the route table, etc.). 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, etc.). 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, etc.) 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. Oracle Bare Metal Cloud Services User Guide 594 CHAPTER 9 Networking Service For reference material for writing more detailed policies for the Networking Service, see Details for the Core Services. Security Lists In addition to using IAM Service policies to control who can manipulate your VCN (e.g., 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 (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 OracleProvided 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): sudo firewall-cmd --zone=public --permanent --addport=1521/tcp sudo firewall-cmd --reload Security lists are regional entities. For the limit on the number of security lists you can have in a VCN, see Service Limits. Oracle Bare Metal Cloud Services User Guide 595 CHAPTER 9 Networking Service 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). Stateful: 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. Oracle Bare Metal Cloud Services User Guide 596 CHAPTER 9 Networking Service Stateless: 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). Oracle Bare Metal Cloud Services User Guide 597 CHAPTER 9 Networking Service 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. Oracle Bare Metal Cloud Services User Guide 598 CHAPTER 9 Networking Service 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 (e.g., ingress), the stateless rule takes precedence and the connection is not tracked. You would need a corresponding rule in the other direction (e.g., egress, either stateless or stateful) in order for the response traffic to be allowed. 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. Oracle Bare Metal Cloud Services User Guide 599 CHAPTER 9 Networking Service 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. l l l Stateful ingress: Allow ICMP traffic type 3 code 4 from source 0.0.0.0/0 and any source port. This rule makes it easy to receive Path MTU Discovery fragmentation messages if you're using jumbo frames. 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. 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 Service 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. Oracle Bare Metal Cloud Services User Guide 600 CHAPTER 9 Networking Service l l l l l Protocol: Either a single IPv4 protocol or "all" to cover all protocols. 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 (e.g., include the /32 if specifying an individual IP address). 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. 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. 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 l l l l l Stateful or stateless: Whether connection tracking is used for the traffic matching the rule. See Stateful vs. Stateless Rules. Protocol: Either a single IPv4 protocol or "all" to cover all protocols. 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 (e.g., include the /32 if specifying an individual IP address). 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. 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. 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 Managing Security Lists. Connection Tracking Details for Stateful Rules Oracle uses connection tracking to allow responses for traffic that matches stateful rules (see Stateful vs. Stateless Rules). To determine response traffic for TCP, UDP, and ICMP, Oracle performs connection tracking on these items for the packet: Oracle Bare Metal Cloud Services User Guide 601 CHAPTER 9 Networking Service 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. 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 Below 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 Managing 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, you need to either restart the DHCP client on the instance or reboot the instance. Otherwise, the change will 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). Oracle Bare Metal Cloud Services User Guide 602 CHAPTER 9 Networking Service 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 Service 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. You need to use your own custom DNS resolver to enable that. Custom Resolver Use your own DNS servers (maximum three). These could be internet IP addresses (e.g., 216.146.35.35 for Dyn's Internet Guide), DNS servers in your VCN, or DNS servers in your on-premises network, which is connected to your VCN by way of an IPSec VPN connection (via a DRG). About the DNS Domains and Hostnames When you initially create a VCN and subnets, you may specify DNS labels for each. These, 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. Along with the subnet doman 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. Requirements for DNS Labels and Hostnames l VCN and subnet labels: Max 15 alphanumeric characters and must start with a letter l Hostnames: Max 63 characters and must be compliant with RFCs 952 and 1123 Oracle Bare Metal Cloud Services User Guide 603 CHAPTER 9 Networking Service l Labels and hostnames cannot be changed later 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 Don't confuse the DNS label or hostname with the friendly name you can assign to the object (i.e., 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 will validate the hostname for DNS compliance and uniqueness during instance launch. If either of these requirements isn't met, the launch request will fail. 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. 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). Oracle Bare Metal Cloud Services User Guide 604 CHAPTER 9 Networking Service o l Default value in the default set of DHCP options: Internet and VCN Resolver Search Domain: To specify a single search domain. When resolving a DNS query, the OS will append 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 listed above. 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 l Select the check box for Use DNS Hostnames in this VCN Specify a DNS label for the VCN. If you select the check box but don't specify a DNS label, the Console assumes you want to use the Internet and VCN Resolver in your VCN and automatically generates a DNS label for the VCN. 2. When creating the subnets: l l l Again, select the check box for Use DNS Hostnames in this Subnet Specify a DNS label for each subnet. If you select the check box 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. 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. Oracle Bare Metal Cloud Services User Guide 605 CHAPTER 9 Networking Service If you don't select the check box 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. If you don't (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 l Specify a DNS label for each subnet. 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. Associate any set of DHCP options that has DhcpDnsOption serverType = 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). 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 Oracle Bare Metal Cloud Services User Guide 606 CHAPTER 9 Networking Service least a display name) at launch. 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 (i.e., <VCN DNS label>.oraclevcn.com). Note: The custom DNS servers must be located in a subnet that uses Internet and VCN Resolver for DNS. Scenario 3: Use Different DHCP Options Per Subnet Scenario 1: Use Internet and VCN Resolver with DNS Hostnames Across the VCN 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 subnetb.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. FastConnect Overview Oracle Bare Metal Cloud Services FastConnect provides an easy way to create a dedicated, private connection between your data center and Oracle Bare Metal Cloud Services. With FastConnect, you establish a private connection between your existing physical network and your Virtual Cloud Network (VCN), and access your Oracle Bare Metal Cloud Services User Guide 607 CHAPTER 9 Networking Service VCN using private IP addresses (RFC 1918). FastConnect provides higher-bandwith options, and a more reliable and consistent networking experience compared to internet-based connections. You can connect at your closest FastConnect locations at port speeds in 1-Gbps and 10-Gbps increments. With FastConnect, you can establish a connection in one of these ways: l Colocation: By colocating with Oracle in a FastConnect location l Provider: By connecting to a FastConnect provider The following table lists the FastConnect locations. Region Colocation with Oracle Provider Phoenix, AZ (PHX) Century Link, DC8, Phoenix, AZ Megaport: Cyrus One Data Hall 35, Chandler, AZ Cyrus One Data Hall 35 Cyrus One Data Hall 50 Ashburn, VA (IAD) Equinix DC6, Ashburn, VA Equinix Cloud Exchange: CoreSite, Reston, VA Multiple locations Megaport: Equinix DC6, Ashburn, VA CoreSite, Reston, VA 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 your VCN over a private physical network instead of the internet. FastConnect location A specific Oracle data center where you can connect with Oracle Bare Metal Cloud Services. metro area A geographical area (e.g., Phoenix) 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. Oracle Bare Metal Cloud Services User Guide 608 CHAPTER 9 Networking Service 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 if your network is colocated with Oracle. provider In a provider scenario, this is the network service provider with a physical connection to the Oracle Bare Metal Cloud Services network in a FastConnect location. Dynamic Routing Gateway (DRG) The virtual edge router attached to your VCN. The DRG is a single point of entry for private traffic coming in to your VCN. 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 router on the edge of your existing network and your DRG. Each virtual circuit is made up of information shared between you and Oracle, as well as a provider (if you're connecting via a provider). You could have multiple 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 following diagram illustrates the two ways to connect to Oracle with FastConnect: either through colocation with Oracle in the FastConnect location, or via a provider. In both cases, the connection goes between the router at the edge of your existing network and Oracle (your DRG). Oracle Bare Metal Cloud Services User Guide 609 CHAPTER 9 Networking Service 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 Bare Metal Cloud Services region. The first diagram shows the colocation scenario, with your physical connection to Oracle within the FastConnect location. Oracle Bare Metal Cloud Services User Guide 610 CHAPTER 9 Networking Service The next diagram shows the provider scenario, with your physical connection to the provider, and the provider's physical connection to Oracle within the FastConnect location. Oracle Bare Metal Cloud Services User Guide 611 CHAPTER 9 Networking Service The next two diagrams add the virtual circuit, which is a single, logical connection between your edge router and DRG. The first diagram shows the colocation scenario. The second diagram shows the provider scenario. Oracle Bare Metal Cloud Services User Guide 612 CHAPTER 9 Networking Service Oracle Bare Metal Cloud Services User Guide 613 CHAPTER 9 Networking Service BGP Session to Either Oracle or the Provider This section is applicable if you're connecting via a provider. A Border Gateway Protocol (BGP) session is established from your edge router, but where it goes to depends on which provider you use. To Oracle: With some providers (e.g., Megaport), the BGP session goes from your edge router to Oracle (your DRG), as shown in the following diagram. When setting up the virtual circuit with Oracle, you'll be asked to provide basic BGP peering information (see General Requirements). Oracle Bare Metal Cloud Services User Guide 614 CHAPTER 9 Networking Service To the provider: With other providers, your BGP session goes from your edge router to the provider's, as shown in the following diagram. When setting up the virtual circuit with Oracle, you will not be asked for any BGP session information. Instead, you'll share BGP information with the provider. Notice that there's a separate BGP session that the provider establishes with Oracle. Oracle Bare Metal Cloud Services User Guide 615 CHAPTER 9 Networking Service General Requirements Before getting started, make sure you meet the following requirements and have the necessary BGP peering information. General requirements for Oracle Bare Metal Cloud Services: l l Oracle Bare Metal Cloud Services account, with at least one user with appropriate Oracle Bare Metal Cloud Identity and Access Management Service (IAM) permissions (e.g., a user in the Administrators group) At least one existing DRG (instructions below) Networking requirements: l For colocation with Oracle: Ability to connect via single mode fiber in your selected FastConnect location. l For connection to a provider: At least one physical network connection with the provider. l Network equipment that supports Layer 3 routing using BGP. l BGP peering information: o A public or private BGP ASN for your network. Oracle's BGP ASN is 31898. Oracle Bare Metal Cloud Services User Guide 616 CHAPTER 9 Networking Service o A pair of /30 or /31 private IP addresses. You'll need a separate pair of IP addresses for each virtual circuit you set up. o Timer settings for Oracle's routers: 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. You'll need the BGP peering information to configure your edge routers. Depending on the situation, either you will specify the peering IP addresses or a provider will. Just make sure you have the values on hand in case Oracle or the provider requests them. What's Next? See these topics to get started: l Colocation: By colocating with Oracle in a FastConnect location l Provider: By connecting to a FastConnect provider 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're not colocated and want to use FastConnect with a provider, see FastConnect: Via Provider. Before Getting Started: Learn and Plan Here are basic things you need to do before you get started with FastConnect: l l l FastConnect concepts: Make sure you're familiar with the basic concepts and requirements covered in FastConnect Overview. Tenancy setup and compartment design: If you haven't yet, set up your tenancy. Think about who needs access to Oracle Bare Metal Cloud Services and how. For more information, see "Setting Up Your Tenancy" in the Oracle Bare Metal Cloud Services Getting Started Guide. Specifically for FastConnect, see Required IAM Service Policy to understand the policy required to work with FastConnect components. 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, etc. For more information, see Overview of the Networking Service. Oracle Bare Metal Cloud Services User Guide 617 CHAPTER 9 Networking Service l l 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. BGP peering information: Gather the following information, which you'll need when setting up your FastConnect virtual circuit(s) and configuring your edge router: o The public or private Border Gateway Protocol Autonomous System Number (BGP ASN) for your network. Oracle's BGP ASN is 31898. o A pair of /30 or /31 private IP addresses. You'll need a separate pair of IP addresses for each virtual circuit you set up. Cloud network setup: Set up your VCN, subnets, security lists, IAM Service policies, etc., according to your design. For instructions on how to set up the connection between your VCN and existing network, see Getting Started with FastConnect. Required IAM Service Policy To work with Networking Service 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 Service 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 Service resources: Allow group NetworkAdmins to manage virtual-network-family in tenancy 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 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. Oracle Bare Metal Cloud Services User Guide 618 CHAPTER 9 Networking Service Oracle Bare Metal Cloud Services User Guide 619 CHAPTER 9 Networking Service Step 1: Learn and Plan If you haven't yet, walk through the planning in Before Getting Started: Learn and Plan. Step 2: Set up a DRG Summary: If you haven't already, use the Oracle Bare Metal Cloud Services Console at https://console.usphoenix-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 an existing route table Step 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: a. In the Console, confirm you're viewing the compartment that contains the DRG that you'll connect to. b. 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. c. Click Create Connection. d. 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 crossconnects in a group. e. Enter the following: 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 (e.g., MyName-1, MyName-2, etc.). You can't change the name later. Oracle Bare Metal Cloud Services User Guide 620 CHAPTER 9 Networking Service l l Create in Compartment: Select the compartment where you want to create the cross-connect group and cross-connect(s). If you're not sure, select the current compartment (where the DRG resides). This choice of compartment, in conjunction with a corresponding IAM Service policy, controls who has access to the cross-connect group and cross-connect(s). 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. f. Click Continue. The cross-connect group and cross-connect(s) are created. The resulting dialog box has a link to the Letter of Authority (LOA) for each cross-connect. 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 request at the FastConnect location in the next step. h. Click Close. The new connection is 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: Oracle Bare Metal Cloud Services User Guide 621 CHAPTER 9 Networking Service Summary of status icons: l l 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 step). Cross-connect group (CCG) icon: The icon near the middle of the page. It shows the status of the crossconnect group itself. At this point, the CCG status will be PENDING PROVISIONING. Cross-connect (CC) icon: The icon on the right side of the page. It shows the status of a given crossconnect. 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. Step 4: Set up cabling in the FastConnect location Submit the LOA(s) from the preceding step and request cabling at the FastConnect location. Each LOA is valid for a limited time. The details are printed on the LOA. Oracle Bare Metal Cloud Services User Guide 622 CHAPTER 9 Networking Service Step 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 level that Oracle detects by viewing the details of the cross-connect and clicking Light Levels, as shown in the following screenshot: Step 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. Step 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 step informs Oracle that your physical network connection is ready. Oracle will then complete the router configuration for each cross-connect. Instructions: a. In the Console, click Networking, and then click FastConnect. b. Select the compartment where the connection resides, and then click the connection to view its details. The FC icon will read ACTION REQUIRED. Oracle Bare Metal Cloud Services User Guide 623 CHAPTER 9 Networking Service c. Click the cross-connect to view its details, and then click Activate. d. Confirm when prompted. 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. Summary of status icons: l l l FastConnect (FC) icon: The FC status will remain as ACTION REQUIRED to indicate that you have another action to take (see the next step). Cross-connect group (CCG) icon: The CCG status will switch to PROVISIONED to indicate that the cross-connect group is ready to use. Cross-connect (CC) icon: The CC status will switch to PROVISIONING and then change to PROVISIONED (typically within one minute). Step 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- Oracle Bare Metal Cloud Services User Guide 624 CHAPTER 9 Networking Service connect group must be in the PROVISIONED state. Instructions: a. In the Console, return to the connection you created earlier, and click the Virtual Circuits tab on the left side of the page. b. Click Create Virtual Circuit. In the resulting dialog box, you can add one or more virtual circuits to run on the cross-connect group. c. Enter the following: l l l l l l l l 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. 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 Service policy, controls who has access to the virtual circuit. Dynamic Routing Gateway Compartment: Select the compartment where the DRG resides (it should already be selected). Dynamic Routing Gateway: Select the DRG to route the FastConnect traffic to. 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 add a new cross-connect to an existing cross-connect group). Customer BGP ASN: The public or private ASN for your network. 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. Customer BGP IP Address: The BGP peering IP address for your edge router, with either a /30 or /31 subnet mask. Oracle BGP IP Address: The BGP peering IP address you want to use for the DRG, with either a /30 or /31 subnet mask. d. Click Create. Oracle Bare Metal Cloud Services User Guide 625 CHAPTER 9 Networking Service The virtual circuit is created. Its status is now included on the main connection's details. Summary of status icons: l FastConnect (FC) icon: The FC status will switch to PROVISIONING briefly while Oracle's system provisions the virtual circuit. The status will then switch to ACTION REQUIRED if the BGP session between your edge router and DRG is not yet correctly configured (see the next step), if the VLAN isn't configured correctly, or if there any other problems. Otherwise, this status will switch to PROVISIONED. l Cross-connect group (CCG) icon: The CCG status will remain as PROVISIONED. l Cross-connect (CC) icon: The CC status will remain as PROVISIONED. l Virtual circuit (VC) icon: The virtual circuit's status will be PROVISIONING briefly while Oracle's system provisions the virtual circuit. The status will then switch to DOWN if the BGP session between your edge router and DRG is not yet correctly configured, if the VLAN isn't configured correctly, or if there any other problems. Otherwise the status will switch to UP. Step 9: Configure your edge router Configure your edge router(s) to use the BGP information and VLAN you specified when setting up the virtual Oracle Bare Metal Cloud Services User Guide 626 CHAPTER 9 Networking Service 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. 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. Summary of status icons: l FastConnect (FC) icon: The FC status will switch to PROVISIONED when the BGP session is established. l Cross-connect group (CCG) icon: The CCG status will switch to PROVISIONED. l Cross-connect (CC) icon: The CC status will remain as PROVISIONED. l Virtual circuit (VC) icon: The virtual circuit's status will switch to BGP UP when the BGP session is established. Step 10: Ping the DRG Ping the DRG at the Oracle BGP IP address you provided when setting up the virtual circuit. Check the error counters and look for any dropped packets. Don't proceed until you can successfully ping the DRG without errors. Step 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. When it is, the connection is ready to use. You should now be able to launch an instance in your cloud network and access it (i.e., via SSH) from your existing private network. See Launching an Instance. Managing Your Connection To get the status of your connection 1. In the Console, go to Networking, and then click FastConnect to view your list of 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: Oracle Bare Metal Cloud Services User Guide 627 CHAPTER 9 Networking Service 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 l You need to configure your edge router Or, you've configured BGP or the VLAN incorrectly on your edge router (make sure to configure the router to use the BGP and VLAN values you specified when creating the virtual circuit) Oracle Bare Metal Cloud Services User Guide 628 CHAPTER 9 Networking Service The following table summarizes the different states of each component involved in the connection at different points during setup: Step in Setup Process FC Icon (overall connection) CCG Icon CC Icon VC Icon Step 3: Set up your cross-connect group and cross-connect(s) ACTION REQUIRED PENDING PENDING N/A PROVISIONING CUSTOMER Step 7: Activate the cross-connect (s) ACTION REQUIRED PROVISIONED PROVISIONED Step 8: Set up your virtual circuit (s) PROVISIONING > PROVISIONED PROVISIONED PROVISIONED or PROVISIONING > DOWN DOWN Step 9: Configure your edge router DOWN > UP PROVISIONED PROVISIONED DOWN > UP 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. Oracle Bare Metal Cloud Services User Guide 629 CHAPTER 9 Networking Service The cross-connect is created. The resulting dialog box has a link to the Letter of Authority (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 steps 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 crossconnect. 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 of will switch to PROVISIONED. To edit a virtual circuit You can change these items for a virtual circuit: l The name l Bandwidth l Which DRG it uses l Which VLAN it uses l The BGP session information Important: If the virtual circuit is working and in the PROVISIONED state before you edit it, be aware that changing any of the properties besides the name will cause the virtual circuit's state to switch to PROVISIONING and the related BGP session to go down. After Oracle re-provisions the virtual circuit, its state will return to PROVISIONED. Make sure you confirm that the associated BGP session is back up. 1. In the Console, go to Networking, and then click FastConnect to view your list of connections. 2. Select the compartment where the connection resides, and then click the connection to view its details. 3. Click Virtual Circuits, and then click the virtual circuit to view its details. Oracle Bare Metal Cloud Services User Guide 630 CHAPTER 9 Networking Service 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 1. In the Console, go to Networking, and then click FastConnect to view your list of connections. 2. Select the compartment where the connection resides, and then click the connection to view its details. 3. Click Virtual Circuits, and then click the virtual circuit to view its details. 4. Click Delete. 5. Confirm when prompted. The virtual circuit's status will change 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. 1. In the Console, go to Networking, and then click FastConnect to view your list of connections. 2. Select the compartment where the connection resides, and then click the connection to view its details. 3. Click the cross-connect you want to delete. 4. Click Delete. 5. Confirm when prompted. The cross-connect's status will change 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. Oracle Bare Metal Cloud Services User Guide 631 CHAPTER 9 Networking Service 1. In the Console, go to Networking, and then click FastConnect to view your list of connections. 2. Select the compartment where the connection resides, and then click the connection to view its details. 3. Click Cross-Connect Groups, and then click the cross-connect group to view its details. 4. Click Delete. 5. Confirm when prompted. The cross-connect group's status will change to TERMINATING and then to TERMINATED. FastConnect: Via Provider This topic is for customers who will use Oracle Bare Metal Cloud Services FastConnect by connecting to a 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 you get started with FastConnect: l l l l l FastConnect concepts: Make sure you're familiar with the basic concepts and requirements covered in FastConnect Overview. Tenancy setup and compartment design: If you haven't yet, set up your tenancy. Think about who needs access to Oracle Bare Metal Cloud Services and how. For more information, see "Setting Up Your Tenancy" in the Oracle Bare Metal Cloud Services Getting Started Guide. Specifically for FastConnect, see Required IAM Service Policy to understand the policy required to work with FastConnect components. 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, etc. For more information, see Overview of the Networking Service. 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. BGP peering information: Gather the following information, but only if you'll have a BGP session from your edge router to Oracle): Oracle Bare Metal Cloud Services User Guide 632 CHAPTER 9 Networking Service l o The public or private Border Gateway Protocol Autonomous System Number (BGP ASN) for your network. Oracle's BGP ASN is 31898. o A pair of /30 or /31 private IP addresses. You'll need a separate pair of IP addresses for each virtual circuit you set up. Cloud network setup: Set up your VCN, subnets, security lists, IAM Service policies, etc., according to your design. For instructions on how to set up the connection between your VCN and existing network, see Getting Started with FastConnect. Required IAM Service Policy To work with Networking Service 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 Service 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 Service resources: Allow group NetworkAdmins to manage virtual-network-family in tenancy 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 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 Bare Metal Cloud Services FastConnect Service-Level Agreement (SLA). In general, you should design your network with both of these in mind: l l Regularly scheduled maintenance by Oracle, your provider, or your own organization. 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: Oracle Bare Metal Cloud Services User Guide 633 CHAPTER 9 Networking Service 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 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. You'll have two separate BGP sessions from your edge router to your DRG; one per virtual circuit. See the following diagram. An active/active configuration for routing traffic across the two connections is recommended and supported by your DRG. Getting Started with FastConnect The following flow chart shows the overall steps in the process. Oracle Bare Metal Cloud Services User Guide 634 CHAPTER 9 Networking Service Also see the sequence diagram in To get the status of your virtual circuit. Step 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. Step 2: Set up connection to the provider If you haven't already, start the process of ordering the connection from the provider, setting it up, and then testing it with the provider. It can take some time, depending on the provider. Oracle Bare Metal Cloud Services User Guide 635 CHAPTER 9 Networking Service Step 3: Set up a DRG Summary: If you haven't already, use the Oracle Bare Metal Cloud Services Console at https://console.usphoenix-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 an existing route table Step 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. a. In the Console, confirm you're viewing the compartment that contains the DRG that you'll connect to. b. 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. c. Click Create Connection. d. 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. e. Enter the following: l 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. 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 Service policy, controls who has access to the virtual circuit. Oracle Bare Metal Cloud Services User Guide 636 CHAPTER 9 Networking Service l l l Dynamic Routing Gateway Compartment: Select the compartment where the DRG resides (it should already be selected). Dynamic Routing Gateway: Select the DRG to route the FastConnect traffic to. 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 BGP Session to Either Oracle or the Provider), the dialog box will include additional fields for the BGP session: l l l Customer BGP IP Address: The BGP peering IP address for your edge router, with either a /30 or /31 subnet mask. Oracle BGP IP Address: The BGP peering IP address you want to use for the DRG, with either a /30 or /31 subnet mask. Customer BGP ASN: The public or private ASN for your network. f. 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. g. Copy and paste the OCID to another location. You will need to give it to your provider in the next step. h. 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 l 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 will be INACTIVE. Lifecycle State: The current status of the virtual circuit during the time it's being set up. At this point, the value will be PENDING_PROVIDER. Large "VC" icon: While the virtual circuit is still being set up, this large, colored icon will also indicate the Lifecycle State (e.g., PENDING_PROVIDER). After the Lifecycle State switches to PROVISIONED, this icon will switch to indicate the state of the virtual circuit's BGP session (either green/UP or red/DOWN). Oracle Bare Metal Cloud Services User Guide 637 CHAPTER 9 Networking Service Also see the diagram in To get the status of your virtual circuit. Step 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 will configure each virtual circuit on their end to complete the connectivity. Instructions for Equinix Cloud Exchange a. Go to the Equinix Cloud Exchange portal and sign in. b. Click the Create Connection tab and select the following: l Metro: Ashburn l Service: Oracle FastConnect - Bare Metal Cloud Services (Layer 2 Connection) c. 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. d. 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. e. In the Seller-side Information section, enter the OCID for the virtual circuit. f. Choose a speed for the connection. Oracle Bare Metal Cloud Services User Guide 638 CHAPTER 9 Networking Service g. 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 will receive an email and then provision the virtual circuit(s). Be aware that the process takes typically 1-2 business days. During that time, the virtual circuit's Provider State will change to ACTIVE, and the Lifecycle State will change to PROVISIONING. When the virtual circuit is completely set up, the Lifecycle State will switch to PROVISIONED. Instructions for Megaport a. Go to the Megaport console and sign in. b. 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'll need to start that first and then add the connection to it. c. Click VXC to Cloud and click the icon for Oracle. d. Enter the OCID for the virtual circuit and choose which Oracle CloudTarget Port (i.e., building) to use for the virtual circuit. If your network design includes a second Megaport and virtual circuit for redundancy, repeat the steps above 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. Step 6: Configure your edge router If your BGP session goes to Oracle, (see 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 will switch to UP. Oracle Bare Metal Cloud Services User Guide 639 CHAPTER 9 Networking Service If your BGP session instead goes to the 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). Step 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. Step 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 Step 9a: Ping the DRG For each virtual circuit, ping the DRG at the Oracle BGP IP address you provided when setting up the virtual circuit. Check the error counters and look for any dropped packets. Don't proceed until you can successfully ping the DRG without errors. Step 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 use. You should now be able to launch an instance in your cloud network and access it (i.e. via SSH) from your existing private network. See Launching an Instance. BGP Session Goes to the Provider Step 10a: Ping the provider's edge router For each virtual circuit, ping the provider's edge router. Check the error counters and look for any dropped packets. Don't proceed until you can successfully ping the provider without errors. Step 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. Step 10c: Ping the DRG For each virtual circuit, ping the DRG at the Oracle BGP IP address (which you can get from the provider). Check Oracle Bare Metal Cloud Services User Guide 640 CHAPTER 9 Networking Service the error counters and look for any dropped packets. When you can successfully ping the DRG without errors, the connection is ready to use. You should now be able to launch an instance in your cloud network and access it (i.e. via SSH) from your existing private network. See Launching an Instance. 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. Oracle Bare Metal Cloud Services User Guide 641 CHAPTER 9 Networking Service Oracle Bare Metal Cloud Services User Guide 642 CHAPTER 9 Networking Service To edit a virtual circuit You can change the name, bandwidth, and which DRG is used. 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 the virtual circuit is working and in the PROVISIONED state before you edit it, be aware that changing any of the properties besides the name will cause the virtual circuit's state to switch to PROVISIONING and the related BGP session to go down. After Oracle re-provisions the virtual circuit, its state will return to PROVISIONED. Make sure you confirm that the associated BGP session is back up. See the connectivity testing steps in Getting Started with FastConnect. 1. In the Console, go to Networking, and then click FastConnect to view your list of 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. 1. In the Console, go to Networking, and then click FastConnect to view your list of 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 Delete. 5. Confirm when prompted. The virtual circuit's Lifecycle State will change to TERMINATING and then to TERMINATED. Oracle Bare Metal Cloud Services User Guide 643 CHAPTER 9 Networking Service MTU and Jumbo Frames The maximum transmission unit (MTU) is the largest packet size (or frame) that can be sent over the network. Oracle Bare Metal Cloud Services support MTU sizes up to 9000 (i.e., jumbo frames). All instances are configured with a default MTU of 9000. You can use the following command to change the MTU size on an instance: sudo nmcli con modify ens2f0 ethernet.mtu <MTU_size> Important: If you change the network configuration, be careful to not disrupt access to the instance. For more information, see Uninterrupted Access to the Instance. Applicable Security List Rules If an instance sends a packet that is too large for the network, an ICMP message of type 3 code 4 will be returned to the instance ("Fragmentation Needed and Don't Fragment was Set"). The default security list that comes with each VCN has ingress rules that allow those particular ICMP messages from both outside the VCN and from other instances within the VCN. If you choose not to associate the default security list with the subnets in your VCN, but want the instances to receive those ICMP messages, make sure to add the corresponding ingress rules to at least one of the security lists associated with each subnet. Oracle Bare Metal Cloud Services User Guide 644 CHAPTER 9 Networking Service 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 Service Scenarios. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 or other tool. If you try to perform Oracle Bare Metal Cloud Services User Guide 645 CHAPTER 9 Networking Service 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. If you're a member of the Administrators group, you already have the required access to execute Scenario A. Otherwise, you need access to the Networking Service, and you need the ability to launch instances. See IAM Service Policies for the Networking Service. Setting Up Scenario A Setup is easy in the Console. Alternatively, you can use the Oracle Bare Metal Cloud Services 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 will update 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. 3. Click Create Virtual Cloud Network. 4. In Create in Compartment, leave the default value (the compartment you're currently working in). 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. 7. Click Create Virtual Cloud Network. 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. Oracle Bare Metal Cloud Services User Guide 646 CHAPTER 9 Networking Service 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 information, see Managing Security Lists. Your next step is to launch an instance into one of the subnets and then communicate with it (e.g., via SSH or RDP). For more information, see Launching an Instance. 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. 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. 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 information, see Managing Security Lists. Oracle Bare Metal Cloud Services User Guide 647 CHAPTER 9 Networking Service Your next step is to launch an instance into a subnet in the VCN and then communicate with it (e.g., via SSH). For more information, see Launching an Instance. Oracle Bare Metal Cloud Services User Guide 648 CHAPTER 9 Networking Service 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 Service Scenarios. The scenarios uses an IPSec VPN for connectivity; however, you could instead use Oracle Bare Metal Cloud Services FastConnect. Oracle Bare Metal Cloud Services User Guide 649 CHAPTER 9 Networking Service 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. If you're a member of the Administrators group, you already have the required access to execute Scenario B. Otherwise, you need access to the Networking Service, and you need the ability to launch instances. See IAM Service Policies for the Networking Service. Setting Up Scenario B Setup is easy in the Console. Alternatively, you can use the Oracle Bare Metal Cloud Services API, which lets you execute the individual operations yourself. 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 Service 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. Oracle Bare Metal Cloud Services User Guide 650 CHAPTER 9 Networking Service 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 will update 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 currently working in). 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. 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 check box for Use DNS Hostnames in this VCN. Then you may specify a DNS label for the VCN, or the Console will generate one for you. The dialog box will automatically display the corresponding DNS Domain Name for the VCN (<VCN DNS label>.oraclevcn.com). For more information, see DNS in Your Virtual Cloud Network. i. 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. Its details are displayed. b. Click Subnets. c. Click Create Subnet. Oracle Bare Metal Cloud Services User Guide 651 CHAPTER 9 Networking Service d. Enter the following: l l l l l l Name: A friendly name for the first subnet (e.g., 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). Availability Domain: Choose one of the Availability Domains. 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. Route Table: Select the default route table. Private or public subnet: Select Private Subnet, which means instances in the subnet cannot have public IP addresses. For more information, see Internet Access for Your VCN. 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 DNS in Your Virtual Cloud Network. l DHCP Options: Select the default set of DHCP options. l Security Lists: Select the default security list. 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 (e.g., 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. Its details are displayed. b. Click Edit Rules. c. Add the following rules to the existing set: a. Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=80 (for HTTP). Oracle Bare Metal Cloud Services User Guide 652 CHAPTER 9 Networking Service b. Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=443 (for HTTPS). c. Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). d. Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port=all, destination port=3389 (for RDP; required only if using Windows instances). d. When done, click Save Security List Rules. 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 l l Create in Compartment: Leave the default value (the compartment you're currently working in). Name: A friendly name for the Customer-Premises Equipment 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). IP Address: The public IP address of the on-premises router at your end of the VPN (see Prerequisites). d. Click Create. Oracle Bare Metal Cloud Services User Guide 653 CHAPTER 9 Networking Service 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 currently working in). 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. Its details are displayed. b. Click Route Tables, and then click the default route table. Its details are displayed. c. Click Create Route Rule. d. Enter the following: l l CIDR: 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). Target: The Dynamic Routing Gateway you created earlier. Oracle Bare Metal Cloud Services User Guide 654 CHAPTER 9 Networking Service e. Click Create. 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: a. Click Networking, and then click Dynamic Routing Gateways. b. Click the Dynamic Routing Gateway you created earlier. Its details are displayed. c. Click Create IPSec Connection. d. Enter the following: l l l l Create in Compartment: Leave the default value (the compartment you're currently working in). 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). Customer-Premises Equipment: Select the Customer-Premises Equipment object you created earlier. Static Route CIDR: The CIDR block for a static route (e.g., 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. Oracle Bare Metal Cloud Services User Guide 655 CHAPTER 9 Networking Service 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 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. Use the following operations: 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 (i.e., 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 instances 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. Oracle Bare Metal Cloud Services User Guide 656 CHAPTER 9 Networking Service 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 l l l Stateful ingress: Source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=80 (for HTTP). Stateful ingress: Source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=443 (for HTTPS). Stateful ingress: Source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). 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). For additional security, you could modify all the stateful ingress rules to allow traffic only from within your VCN and your onpremises network. You would need to create separate rules for each, one with the VCN's CIDR as the source, and one with the onpremises 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. Oracle Bare Metal Cloud Services User Guide 657 CHAPTER 9 Networking Service 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 Service Scenarios. The scenarios uses an IPSec VPN for connectivity; however, you could instead use Oracle Bare Metal Cloud Services FastConnect. Oracle Bare Metal Cloud Services User Guide 658 CHAPTER 9 Networking Service 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 Service Policy To use Oracle Bare Metal Cloud Services, 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 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. If you're a member of the Administrators group, you already have the required access to execute Scenario C. Otherwise, you need access to the Networking Service, and you need the ability to launch instances. See IAM Service Policies for the Networking Service. Setting Up Scenario C Setup is easy in the Console. Alternatively, you can use the Oracle Bare Metal Cloud Services API, which lets you execute the individual operations yourself. 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 Service 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. Oracle Bare Metal Cloud Services User Guide 659 CHAPTER 9 Networking Service 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 will update 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 currently working in). 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. 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 check box for Use DNS Hostnames in this VCN. Then you may specify a DNS label for the VCN, or the Console will generate one for you. The dialog box will automatically display the corresponding DNS Domain Name for the VCN (<VCN DNS label>.oraclevcn.com). For more information, see DNS in Your Virtual Cloud Network. i. 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. Its details are displayed. b. Click Internet Gateways. c. Click Create Internet Gateway. d. For Create in Compartment, leave the default value (the compartment you're currently working in). Oracle Bare Metal Cloud Services User Guide 660 CHAPTER 9 Networking Service e. Enter a 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). 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. c. Enter the following: l l l l Create in Compartment: Leave the default value (the compartment you're currently working in). Name: A friendly name for the first route table (e.g., 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). 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) Target: The Internet Gateway you just created. d. Click Create. The route table is then created and listed on the page. e. Repeat the preceding steps to create the second route table (e.g., 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. Its details are displayed. 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. Oracle Bare Metal Cloud Services User Guide 661 CHAPTER 9 Networking Service 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. c. For Create in Compartment: Leave the default value (the compartment you're currently working in). d. In the Security List Name field, enter a friendly name for the list (e.g., 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: l l Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=80 (for HTTP). Stateful ingress rule with source CIDR=0.0.0.0/0, protocol=TCP, source port = all, destination port=443 (for HTTPS). f. Add the following egress rules: l l Stateful egress rule with destination CIDR=CIDR for your first private subnet, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). 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 currently working in). Oracle Bare Metal Cloud Services User Guide 662 CHAPTER 9 Networking Service c. In the Security List Name field, enter a friendly name for the list (e.g., 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 l l l Stateful ingress rule with source CIDR=CIDR for public subnet #1, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). Stateful ingress rule with source CIDR=CIDR for public subnet #2, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). Stateful ingress rule with source CIDR=CIDR for your private subnet #1, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). Stateful ingress rule with source CIDR=CIDR for your private subnet #2, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). e. Add the following egress rules: l l Stateful egress rule with destination CIDR=CIDR for private subnet #1, protocol=TCP, source port = all, destination port=1521 (for Oracle databases). Stateful egress rule with destination CIDR=CIDR for private subnet #2, protocol=TCP, source port = all, destination port=1521 (for Oracle 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. c. Enter the following: l l l l Name: A friendly name for the first subnet (e.g., Public Subnet 1). It doesn't have to be unique, and it cannot be changed later in the Console (but you can change it with the API). Availability Domain: Choose one of the Availability Domains. 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. Route Table: Select the Public Subnet Route Table you created earlier. Oracle Bare Metal Cloud Services User Guide 663 CHAPTER 9 Networking Service l l l l Private or public subnet: Select Public Subnet, which means instances in the subnet are allowed to have public IP addresses. For more information, see Internet Access for Your VCN. 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 DNS in Your Virtual Cloud Network. DHCP Options: Select the default set of DHCP options. 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: Oracle Bare Metal Cloud Services User Guide 664 CHAPTER 9 Networking Service a. In the Console, click Networking, and then click Customer-Premises Equipment. b. Click Create Customer-Premises Equipment. c. Enter the following: l l l Create in Compartment: Leave the default value (the compartment you're currently working in). Name: A friendly name for the Customer-Premises Equipment 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). 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: 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 currently working in). 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. Oracle Bare Metal Cloud Services User Guide 665 CHAPTER 9 Networking Service d. Select the cloud network you want to attach the Dynamic Routing Gateway to and 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 private subnet's route table: a. Click Networking, click Virtual Cloud Networks, and then click your cloud network. Its details are displayed. b. Click Route Tables, and then click the Private Subnet Route Table you created earlier. Its details are displayed. c. Click Create Route Rule. d. Enter the following: a. Create in Compartment: Leave the default value (the compartment you're currently working in). b. 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) c. Target: The Dynamic Routing Gateway you created earlier. e. Click Create. The new rule directs the traffic from the subnets in the cloud network to the Dynamic Routing Gateway and ultimately to your on-premises network. 5. Create an IPSec Connection: a. Click Networking, and then click Dynamic Routing Gateways. b. Click the Dynamic Routing Gateway you created earlier. Its details are displayed. c. Click Create IPSec Connection. d. Enter the following: l l l Create in Compartment: Leave the default value (the compartment you're currently working in). 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). Customer-Premises Equipment: Select the Customer-Premises Equipment object you created earlier. Oracle Bare Metal Cloud Services User Guide 666 CHAPTER 9 Networking Service l Static Route CIDR: The CIDR block for a static route (e.g., 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 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 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. Use the following operations: 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). Oracle Bare Metal Cloud Services User Guide 667 CHAPTER 9 Networking Service 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 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. If you plan to launch Windows instances, add this stateful ingress rule: Source CIDR = your onpremises 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 l l Stateful ingress: Source CIDR blocks of public subnets on TCP, source port = all, destination port = 1521 (for Oracle databases) Stateful ingress: Source CIDR blocks of private subnets on TCP, source port = all, destination port = 1521 (for Oracle databases) 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 instances 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). Oracle Bare Metal Cloud Services User Guide 668 CHAPTER 9 Networking Service 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 Launching an Instance. 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. Oracle Bare Metal Cloud Services User Guide 669 CHAPTER 9 Networking Service Managing Virtual Cloud Networks (VCNs) This topic describes how to manage Virtual Cloud Networks (VCNs). 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. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: see IAM Service Policies for the Networking Service. Working with Cloud Networks For an overview of cloud networks and scenarios for using them, see Overview of the Networking Service. For the purposes of access control, you must specify the compartment where you want the cloud network to reside. Consult an administrator in your organization if you're not sure which compartment to use. For more information, see Access Control. For the cloud network you must specify a single, contiguous IPv4 CIDR block in the private IP address ranges specified in RFC 1918 (10.0.0.0/8, 172.16/12, and 192.168/16). Example: 172.16.0.0/16. The cloud network can range from /16 to /30 and must not overlap with your on-premises network. You can't change the size of the cloud network after creation. You may optionally assign a friendly name to the cloud network. It doesn't have to be unique, and you can change it later. Oracle will automatically assign the cloud network 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, which is 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. To delete a cloud network, it must be empty and have no attached gateways. For information about the number of cloud networks you can have, see Service Limits. Oracle Bare Metal Cloud Services User Guide 670 CHAPTER 9 Networking Service Using the Console To create a cloud network 1. In the Console, click Networking. 2. Choose a compartment you have permission to work in (on the left side of the page). The page will update 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. 3. Click Create Virtual Cloud Network. 4. Enter the following: a. Create in Compartment: The compartment where you want to create the cloud network, if different from the compartment you're currently working in. b. Name: 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). 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: 10.0.0.0/16. You cannot change this value later. 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 check box for Use DNS Hostnames in this VCN. Then you may specify a DNS label for the VCN, or the Console will generate one for you. The dialog box will automatically display the corresponding DNS Domain Name for the VCN (<VCN DNS label>.oraclevcn.com). For more information, see DNS in Your Virtual Cloud Network. 5. Click Create Virtual Cloud Network. 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. See Managing Subnets. To delete a cloud network Prerequisite: The cloud network must be empty and have no attached gateways. 1. In the Console, click Networking, and then click Virtual Cloud Networks. A list of the cloud networks in the compartment you're viewing is displayed. If you don’t see the one you're Oracle Bare Metal Cloud Services User Guide 671 CHAPTER 9 Networking Service looking for, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. For the cloud network you want to delete, click the Actions icon ( ), and then click Terminate. 3. Confirm when prompted. 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 manage your VCNs, use these operations: l ListVcns l CreateVcn l GetVcn l UpdateVcn l DeleteVcn Oracle Bare Metal Cloud Services User Guide 672 CHAPTER 9 Networking Service Managing Route Tables This topic describes how to manage the route tables in a Virtual Cloud Network (VCN). Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: see IAM Service Policies for the Networking Service. Working with Route Tables Your cloud network uses virtual route tables to send traffic out of the VCN (e.g., to the Internet or to your onpremises network). Each VCN automatically comes with a default route table. If you don't specify otherwise, every subnet will use the VCN's default route table. When you add an Internet Gateway or Dynamic Routing Gateway (DRG) to your VCN, you can simply update the routes in the default table if that suits your needs. However, if you need both a public subnet and a private subnet as in Scenario C - Public and Private Subnets with a VPN, you can 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 routes. Notice that no route rules are required in order to enable traffic within the VCN itself. 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 will automatically assign the route table a unique identifier called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers. When adding a route rule to a route table, you provide the CIDR block and target (e.g., an Internet Gateway that you've added to the cloud network). If you misconfigure a rule (e.g., enter the wrong CIDR block), the network traffic for that target will be dropped (i.e., black holed). You can update and delete the rules in a table, but notice that when you update a route table in the API, the new set of route rules replaces the entire existing set of rules. To delete a route table, it must not be associated with a subnet yet. You can't delete a cloud network's default route table. For information about the maximum number of route tables and route rules, see Service Limits. Oracle Bare Metal Cloud Services User Guide 673 CHAPTER 9 Networking Service Notes about Routing When routing traffic, Oracle uses a subnet's route table only if the destination IP address is not within the VCN's CIDR block. 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). Using the Console To view a cloud network's default route table 1. In the Console, click Networking, and then click Virtual Cloud Networks. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. The details are displayed. 3. Click Route Tables. The default route table is displayed in the list of tables. To update an existing route table 1. In the Console, click Networking, and then click Virtual Cloud Networks. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. Its details are displayed. 3. Click Route Tables. A list of the route tables in the cloud network is displayed. 4. Click the route table you're interested in. The details are displayed. Oracle Bare Metal Cloud Services User Guide 674 CHAPTER 9 Networking Service 5. Use one of these options: l l To create a new route rule: Click Create Route Rule and enter the new rule. A common rule has CIDR Block = 0.0.0.0/0, and the Target = a gateway you recently created. The 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. To delete an existing route rule: For the rule, click Delete. To create a new route table 1. Confirm you're viewing the compartment that contains the cloud network that you want to add the route table 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. Its details are displayed. 3. Click Route Tables. A list of the route tables in the cloud network is displayed. 4. Click Create Route Table. 5. Enter the following: a. Create in Compartment: The compartment where you want to create the route table, if different from the compartment you're currently working in. b. 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. A common rule has CIDR Block = 0.0.0.0/0, and the Target = a gateway you recently created. The 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. 7. Click Create Route Table. 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 new 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 Oracle Bare Metal Cloud Services User Guide 675 CHAPTER 9 Networking Service route table in a cloud network. 1. In the Console, click Networking, and then click Virtual Cloud Networks. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. The details are displayed. 3. Click Route Tables. A list of the route tables in the cloud network is displayed 4. For the route table you want to delete, click the Actions icon ( ), and then click Terminate. 5. Confirm when prompted. 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 manage a VCN's route tables, use these operations: l ListRouteTables l GetRouteTable l UpdateRouteTable: You can update the route rules and the route table's name. l CreateRouteTable l DeleteRouteTable Managing Security Lists This topic describes how to manage the security lists in a Virtual Cloud Network (VCN). Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 or other tool. If you try to perform Oracle Bare Metal Cloud Services User Guide 676 CHAPTER 9 Networking Service 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. For administrators: The policy in Let Network Admins Manage a Cloud Network covers management of all Networking Service components, including security lists. If you have security admins who need to manage security lists but not other components in the Networking Service, 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 Service Policies for the Networking Service. Working with Security Lists For an overview of security lists, stateful vs. stateless rules, and the basics of ingress and egress rules, see 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. Oracle Bare Metal Cloud Services User Guide 677 CHAPTER 9 Networking Service 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 OracleProvided 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): sudo firewall-cmd --zone=public --permanent --addport=1521/tcp sudo firewall-cmd --reload 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. For the purposes of access control, you must specify the compartment where you want the 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. For information about the maximum number of security lists and rules, see Service Limits. Using the Console To view a cloud network's default security list 1. In the Console, click Networking, and then click Virtual Cloud Networks Oracle Bare Metal Cloud Services User Guide 678 CHAPTER 9 Networking Service 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. 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 1. In the Console, click Networking, and then click Virtual Cloud Networks. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. Its details are displayed. 3. Click Security Lists. A list of the security lists in the cloud network is displayed. 4. Click the security list you're interested in. The details are displayed. 5. Click Edit Rules. 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. Oracle Bare Metal Cloud Services User Guide 679 CHAPTER 9 Networking Service To create a new security list 1. Confirm you're viewing the compartment that contains the cloud network that you want to add the security list 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. Its details are displayed. 3. Click Security Lists. A list of the security lists in the cloud network is displayed. 4. Click Create Security List. 5. Enter the following: 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 change it with the API). 6. Add at least one ingress or egress rule (for examples of rules, see the scenarios in Typical Networking Service 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 (e.g., TCP, UDP, ICMP, "All protocols", etc.). d. Enter further details depending on the protocol: l 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 (e.g., 22 for SSH or 3389 for RDP) or a port range (e.g., 20-22). 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 (e.g., 3,4). If the type has multiple codes you want to allow, create a separate rule for each code. Oracle Bare Metal Cloud Services User Guide 680 CHAPTER 9 Networking Service 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. 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. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the page). 2. Click the cloud network you're interested in. The details are displayed. 3. Click Security Lists. A list of the security lists in the cloud network is displayed 4. For the security list you want to delete, click the Actions icon ( ), and then click Terminate. 5. Confirm when prompted. 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 manage a VCN's security lists, use these operations: l ListSecurityLists l GetSecurityList l UpdateSecurityList: You can update the rules and the security list's name. Oracle Bare Metal Cloud Services User Guide 681 CHAPTER 9 Networking Service l CreateSecurityList l DeleteSecurityList Managing DHCP Options This topic describes how to manage the Dynamic Host Configuration Protocol (DHCP) options in a Virtual Cloud Network (VCN). Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: see IAM Service Policies for the Networking Service. 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 Option Initial Value in the Default DHCP Options Domain Name Server DNS Type: Internet and VCN resolver. For more information, see DNS in Your Virtual Cloud Network. Search Domain This option is present in the default set of DHCP options only if you specify a DNS 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 Oracle Bare Metal Cloud Services User Guide 682 CHAPTER 9 Networking Service 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 Resource Identifiers. 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. Using the Console To view a cloud network's set of default DHCP options 1. In the Console, click Networking, and then click Virtual Cloud Networks. A list of the cloud networks is displayed. Oracle Bare Metal Cloud Services User Guide 683 CHAPTER 9 Networking Service 2. Click the cloud network you're interested in. The details are displayed. 3. Click DHCP Options. The default set of DHCP options is listed on the page. 4. Click it to view the specific options. To update an existing set of DHCP options 1. In the Console, click Networking, and then click Virtual Cloud Networks. A list of the cloud networks is displayed. 2. Click the cloud network you're interested in. Its details are displayed. 3. Click DHCP Options. The sets of DHCP options in the cloud network are displayed. 4. Click the set you're interested in. The details are displayed. 5. Click Edit for the particular DHCP option you want to change: l 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. 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 (i.e., <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 1. Confirm you're viewing the compartment that contains the cloud network that you want to add the DHCP options to. If you've just created the cloud network, you should still be viewing the same compartment. If Oracle Bare Metal Cloud Services User Guide 684 CHAPTER 9 Networking Service 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. Its details are displayed. 3. Click DHCP Options. A list of the sets of DHCP options in the cloud network is displayed. 4. Click Create DHCP Options. 5. Enter the following: l l l 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. Name: A friendly name for the set of options. It doesn't have to be unique, and you can change it later. 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. 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 (i.e., <VCN DNS label>.oraclevcn.com). 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. 1. In the Console, click Networking, and then click Cloud Networks. A list of the cloud networks is displayed. 2. Click the cloud network you're interested in. The details are displayed. Oracle Bare Metal Cloud Services User Guide 685 CHAPTER 9 Networking Service 3. Click DHCP Options. A list of the sets of options in the cloud network is displayed 4. For the set you want to delete, click the Actions icon ( ) and then click Delete. 5. Confirm when prompted. 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 manage a VCN's DHCP options, use these operations: l ListDhcpOptions l GetDhcpOptions l UpdateDhcpOptions l CreateDhcpOptions l DeleteDhcpOptions Oracle Bare Metal Cloud Services User Guide 686 CHAPTER 9 Networking Service Managing Subnets This topic describes how to manage subnets in a Virtual Cloud Network (VCN). Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: see IAM Service Policies for the Networking Service. Working with Subnets For an overview of subnets and scenarios for using them, see Overview of the Networking Service. A subnet is a subdivision of a cloud network. All instances are attached to a subnet. 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 cloud network. Example: 172.16.1.0/24. 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, subnets can be either public or private (see Internet Access for Your VCN). You choose this during subnet creation; you can't change it later. The subnet acts as a unit of configuration: all instances in a given subnet use the same route table, security lists, and DHCP options. For the purposes of access control, you must specify the compartment where you want the subnet to reside. If you're not sure which compartment to use, put the subnet in the same compartment as the cloud network. For more information, see Access Control. You may optionally assign a friendly name to the subnet. It doesn't have to be unique, and you can change it later. Oracle will automatically assign the subnet a unique identifier called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers. You can also add a DNS label for the subnet, which is required if you want the subnet's instances to use the Internet and VCN Resolver feature for DNS. For more information, see DNS in Your Virtual Cloud Network. You may optionally specify a route table for the 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 Oracle Bare Metal Cloud Services User Guide 687 CHAPTER 9 Networking Service you can change the route rules in the table. For more information about route tables, see Managing 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 and Managing 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 Managing DHCP Options. To delete a subnet, it must contain no instances. For information about the number of subnets you can have, see Service Limits. Using the Console 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. Its details are displayed. 3. Click Create Subnet. 4. In the Create Subnet dialog box, you specify the resources to associate with the subnet (e.g., route table, etc.). 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. Oracle Bare Metal Cloud Services User Guide 688 CHAPTER 9 Networking Service l l l l l l l l Name: A friendly name for the subnet. It doesn't have to be unique, and it cannot be changed later in the Console (but you can change it with the API). Availability Domain: The Availability Domain for the subnet. Any instances you later launch into this subnet will also go into this Availability Domain. CIDR Block: A single, contiguous CIDR block for the subnet (e.g,. 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. For reference, here's a CIDR calculator. 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. Private or public subnet: Whether instances in the subnet can have public IP addresses. For more information, see Internet Access for Your VCN. 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 DNS in Your Virtual Cloud Network. 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. 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. 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 in it. 1. In the Console, click Networking, and then click Virtual Cloud Networks. 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, make sure you’re viewing the correct compartment (select from the list on the left side of the Oracle Bare Metal Cloud Services User Guide 689 CHAPTER 9 Networking Service page). 2. Click Subnets. A list of subnets in the cloud network is displayed. 3. For the subnet you want to delete, click Terminate. 4. Confirm when prompted. 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 manage a VCN's subnets, use these operations: l ListSubnets l CreateSubnet l GetSubnet l UpdateSubnet: You can update only the subnet's name. l DeleteSubnet Oracle Bare Metal Cloud Services User Guide 690 CHAPTER 9 Networking Service Managing Internet Gateways This topic describes how to manage Internet Gateways. Required IAM Service Policy To use Oracle Bare Metal Cloud Services, 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 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. For administrators: see IAM Service Policies for the Networking Service. Working with Internet Gateways You can think of an Internet Gateway as a router connecting the edge of the cloud network with the Internet. For scenarios using an Internet Gateway, see Overview of the Networking Service. Also see Internet Access for Your VCN. 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 (e.g., 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 Managing Route Tables. For the purposes of access control, you must specify the compartment where you want the 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 unique identifier called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers. Oracle Bare Metal Cloud Services User Guide 691 CHAPTER 9 Networking Service 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. Using the Console To create an Internet Gateway 1. 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. 2. On the Virtual Cloud Networks page, click the cloud network you're interested in. Its details are displayed. 3. Click Internet Gateways. 4. Click Create Internet Gateway. 5. Enter the following: a. Create in Compartment: The compartment where you want to create the Internet Gateway, if different from the compartment you're currently working in. b. 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). 6. 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. 7. Click Route Tables in the compartment where the cloud network resides. The cloud network's route tables are displayed. Let's assume you want to update the default route table. 8. Click the default route table in the list. Its details are displayed. 9. Click Create Route Rule. 10. Enter the following: l l 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) Target: Select the Internet Gateway you just created Oracle Bare Metal Cloud Services User Guide 692 CHAPTER 9 Networking Service 11. Click Create Route Table. 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. 1. In the Console, click Networking, and then click Vi

Top subcategories

Top subcategories

Top subcategories

Top subcategories

Top subcategories

Top subcategories

Top subcategories

Top subcategories

Download Oracle Bare Metal Cloud User Guide