Open in app

Sign in

Write

Sign in

Al’s Simple Oracle OCI CLI Setup

The Essential Oracle Cloud Toolbox

Alan Higginson
7 min readMay 27, 2020
Photo by Barn Images on Unsplash

Introduction

Setting up the Oracle command line interface (CLI) from your laptop to interact with Oracle Cloud Infrastructure (OCI) is an important first step for interacting with Oracle Cloud. Even if you don’t use the actual OCI CLI, the process creates a configuration file that can be used for other Oracle cloud services like Oracle Kubernetes and Oracle Streaming.

You can follow the documentation, but often it provides options that can be confusing for a beginner. I will show how to install it in a straight forward manner.

The steps below assume you already have an Oracle OCI Tenancy, but if not, you can start with a ‘free tier’ tenancy from here: oracle.com. If struggling to create your free tier tenancy for whatever reason then contact Oracle Support.

Getting Started

Laptop

We need to configure both our laptop and the Oracle Cloud Infrastructure (OCI) Console to allow them both to talk to each other. The examples below assume you are on a Mac laptop, but I’ve provided alternative links to where Linux or Windows commands are provided.

To start with, on the laptop, create a public/private key. This is described in more detail and for different operating systems at: oracle.com but on a Mac simply open a terminal and type the following commands:

mkdir ~/.oci

Create the private key:

openssl genrsa -out ~/.oci/oci_api_key.pem 2048

Restrict permissions on the private key:

sudo chmod go-rwx ~/.oci/oci_api_key.pem

Create the public key:

openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem

Once you’ve generated the public key, you need to add it to the OCI Console.

On OCI Console

Login to the OCI console at cloud.oracle.com and go through the following steps:

  • From the menu on the top left of the screen, select: Identity — Users:
  • Select your user, eg: oracleidentitycloudservice/joe.bloggs@yourdomain.com which takes you to this screen:
  • Where it says ‘OCID’, click on ‘Copy’ and then paste somewhere on your local laptop, like the ‘TextEdit’ app or Notepad, because you’re going to need it later. This is the Oracle cloud identifier or OCID for this user, for example: ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2j3h2j3h
  • Click on ‘Add Public Key’ and click on ‘select one’ to prompt for the file location of your generated public key in PEM format:
  • Select the file at: ~/.oci/oci_api_key_public.pem
  • Now click on the silhouette on the top right of the screen and click on ‘Tenancy’:
  • This takes you here:
  • Click on ‘Copy’ and again paste it somewhere (like TextEdit/Notepad) because you’ll also need this later. This is your unique identifier for your cloud tenancy, for example: ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fda..

We’ve finished with the OCI Console, so next it’s back to our laptop.

Laptop

We should have something like TextEdit or Notepad on our laptop with two things like this (although you’ll have your own values of course):

User OCID: ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2
Tenancy OCID: ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fdafd98fd

We also need to decide which region we want our CLI to access. See here for information about available regions: docs.cloud.oracle.com. As an example, I’ll start with Phoenix in the USA, which is given the identifier: ‘us-phoenix-1’, so maybe add this to your TextEdit/Notepad.

region: us-phoenix-1

We can now install the OCI CLI. The instructions to install the OCI CLI are from here: oracle.com. If you can install it on Linux/Mac, I’ve pulled out the key instructions below (although your directories may differ). Open a terminal and type:

sudo bash -c “$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

This returns this dialog, prompting for options. You can just press ‘Enter’ for all options to take the defaults:

===> In what directory would you like to place the install? (leave blank to use '~/lib/oracle-cli'):
-- Creating directory '~/lib/oracle-cli'.
-- We will install at '~/lib/oracle-cli'.
===> In what directory would you like to place the 'oci' executable? (leave blank to use '~/bin'):
-- Creating directory '~/bin'.
-- The executable will be in '~/bin'.
===> In what directory would you like to place the OCI scripts? (leave blank to use '~/bin/oci-cli-scripts'):
-- Creating directory '~/bin/oci-cli-scripts'.
-- The scripts will be in '~/bin/oci-cli-scripts'.
===> Currently supported optional packages are: ['db (will install cx_Oracle)']
What optional CLI packages would you like to be installed (comma separated names; press enter if you don't need any optional packages)?:

As it’s installing, it tells me:

Already using interpreter /bin/python
New python executable in /home/opc/ocicli/bin/python
Installing setuptools, pip, wheel…done.

Then when it’s finished it says:

===> Modify profile to update your $PATH and enable shell/tab completion now? (Y/n): Y
 — Installation successful.
 — Run the CLI with ~/bin/oci — help

Next we need to configure the CLI. To setup the configuration to your cloud, type in the following command and follow the dialogs:

oci setup config

Which returns:

This command provides a walkthrough of creating a valid CLI config file. The following links explain where to find the information required by this script: 
User API Signing Key, OCID and Tenancy OCID: https://docs.cloud.oracle.com/Content/API/Concepts/apisigningkey.htm#Other
Region:
https://docs.cloud.oracle.com/Content/General/Concepts/regions.htm
General config documentation:
https://docs.cloud.oracle.com/Content/API/Concepts/sdkconfig.htm

Then it prompts you for information which you’ve made a note of in TextEdit/Notepad:

Enter a location for your config [~/.oci/config]:
Enter a user OCID: ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2
Enter a tenancy OCID: ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fdafd98fd
Enter a region (e.g. ap-hyderabad-1, ap-melbourne-1, ap-mumbai-1, ap-osaka-1, ap-seoul-1, ap-sydney-1, ap-tokyo-1, ca-montreal-1, ca-toronto-1, eu-amsterdam-1, eu-frankfurt-1, eu-zurich-1, me-jeddah-1, sa-saopaulo-1, uk-gov-london-1, uk-london-1, us-ashburn-1, us-gov-ashburn-1, us-gov-chicago-1, us-gov-phoenix-1, us-langley-1, us-luke-1, us-phoenix-1): us-phoenix-1
Do you want to generate a new API Signing RSA key pair? (If you decline you will be asked to supply the path to an existing key.) [Y/n]: n
Enter the location of your API Signing private key file: ~/.oci/oci_api_key.pem

This then returns:

Fingerprint: 54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa
Config written to ~/.oci/config
If you haven’t already uploaded your API Signing public key through the console, follow the instructions on the page linked below in the section ‘How to upload the public key’: https://docs.cloud.oracle.com/Content/API/Concepts/apisigningkey.htm#How2

So that is the installation and configuration finished.

To then to test to ensure it’s working ok, we can run this command to get a list of users in your tenancy:

oci iam user list

Which should return some information; for me it returned:

oci iam user list{
  "data": [
    {
      {
      "capabilities": {
        "can-use-api-keys": true,
        "can-use-auth-tokens": true,
        "can-use-console-password": false,
        "can-use-customer-secret-keys": true,
        "can-use-o-auth2-client-credentials": true,
        "can-use-smtp-credentials": true
      },
      "compartment-id": "ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fdafd343",
      "defined-tags": {},
      "description": "joe.bloggs@yourdomain.com",
      "email": null,
      "external-identifier": "58fjghjhj3h2j3",
      "freeform-tags": {},
      "id": "ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2",
      "identity-provider-id": "ocid1.saml2idp.oc1..58fjghjhj3h2j3487535332234243",
      "inactive-status": null,
      "is-mfa-activated": false,
      "lifecycle-state": "ACTIVE",
      "name": "oracleidentitycloudservice/joe.bloggs@yourdomain.com",
      "time-created": "2019-02-28T09:45:26.876000+00:00"
    }
  ]
}

Your OCI CLI should now be ready to use.

Optional Information On The ‘Config’ File

After you’ve run the oci setup configcommand, it stores your user information in ~/.oci/config. The information you’ve stored in ~/.oci/config can be used to access other Oracle cloud services like Oracle Streaming or Oracle Kubernetes. For me it looks like this:

cat ~/.oci/config[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2
fingerprint=54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fdafd98fd
region=us-phoenix-1

We could create a different user in a different tenancy and simply store the new tenancy information in this file by manually amending it. For example, I might have a tenancy that has a home region in Tokyo, so the region is ap-tokyo-1. I would collect the user OCID and Tenancy OCID information for the new tenancy in the same way we did earlier.

I would also need to get the fingerprint of my public key, which I can get after uploading my public key to the new tenancy using this screen as shown earlier:

And when you’ve uploaded it, it creates the fingerprint and you can copy the fingerprint from here:

Alternatively you could run this in a terminal to get the fingerprint:

openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c

Which returns:

writing RSA key
(stdin)= 54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa

Then we could copy this fingerprint 54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa and manually amend ~/.oci/config by creating another entry using a text editor like this:

cat ~/.oci/config
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazsd438958fjghjhj3h2j3h2j3h2
fingerprint=54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaat7gdsdf9s8fdafd98fd
region=us-phoenix-1
[alstokyo]
user=ocid1.user.oc1..aaaaaaaazsd438958fjg5353559593599394
fingerprint=54:76:23:54:54:dd:23:f4:ef:3e:43:55:23:b3:5c:fa
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaaaffdrerereeer
region=ap-tokyo-1

And then if you want to use the OCI CLI to pickup this alternative profile, or sometimes called ‘context’, you could type:

oci --profile alstokyo iam user list

-note it has two dashes before ‘profile’. So I can switch between the different tenancies as required.

Oracle Cloud

--

--

Alan Higginson

Written by Alan Higginson

6 Followers

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams