Oracle Cloud Infrastructure Documentation

Using the Command Line Interface with a Roving Edge Infrastructure Device

Describes how to use the Command Line Interface to access a a Roving Edge Infrastructure device.

The Oracle Cloud Infrastructure Command Line Interface (CLI) provides a set of commands for configuring and running Roving Edge Infrastructure tasks. Use the CLI as an alternative to running commands from the Device Console. Sometimes you must use the CLI to complete certain tasks where no Device Console equivalent is available.

Use CLIs to perform Roving Edge Infrastructure service tasks within the Oracle Cloud Infrastructure cloud. These tasks can include requesting nodes, and running tasks directly on device nodes. Install the CLI separately on each device. CLIs installed on devices run locally within your environment and don't require internet access.

Minimum Required CLI Version

The minimum CLI version required for Roving Edge Infrastructure is 2.12.1.

Determining CLI Versions

Access the following URL to see the currently available version of the CLI:

https://github.com/oracle/oci-cli/blob/master/CHANGELOG.rst

Enter the following command at the prompt to see the version of the CLI currently installed on your machine:

oci --version

If you have a version on your machine older than the version currently available, install the latest version.

Note

Always update to the latest version of the CLI. The CLI is not updated automatically, and you can only access new or updated CLI features by installing the current version.

Updating Your Hosts File

Open your /etc/hosts file and add an ip_address host_name entry for your RED.

Where ip_address is the IP address of the Roving Edge Infrastructure device, and host_name is the name of the Roving Edge Infrastructure host on which you are running the CLI.

For example:

10.0.1.8 rover.mycompany.com

Access the hostname by running the following commands:

  • Download the redroot.pem certificate:

    echo -n | openssl s_client -showcerts -connect ip_address:8015 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > redroot.pem

  • Then display the DNS hostnames:

    openssl x509 -in redroot.pem -text -noout | grep DNS

In the command's return, the following appears:

  • DNS:*.certcommonname.com: This indicates a wildcard certificate. Prefix the certificate with the subdomain of your choice "ex: rover" and open your /etc/hosts file and add a line with the following:

    10.145.140.5 rover.certcommonname.com

  • DNS:rover-install-red-1, DNS:…,: Choose any of the DNS outputs and add the following line to your /etc/hosts file:

    10.145.140.5 rover-install-red-1

Open your /etc/hosts file and add a line with the following:

10.145.140.5 rover.mycompany.com otec-console-local rover-install-red-1

If the required parameter value is listed as a variable, for example name, then you must provide a value. Enter the command as it appears in the documentation.

The inclusion of [OPTIONS] in the command syntax indicates optional parameters. Access the CLI's online help for a list of optional parameters and their usage.

Installing the CLI

Installation and configuration of the CLIs is described in detail in Command Line Interface (CLI) topic in the Oracle Cloud Infrastructure documentation.

Setting Up the Config File

Before setting up the config file, you need to gather the following information:

  • Roving Edge Infrastructure tenancy OCID. Obtain the tenancy OCID using the following command:

    curl -k https://ip_address:12060/v1/tenants/orei

    where ip_address is the IP address of the Roving Edge Infrastructure device. The tenancy OCID is contained in the return, for example:

    {
  "id" : "ocid1.tenancy.orei..uniqueID",
  "name" : "orei"
}

    Alternatively, enter the following URL into your Device Console web browser: 

    https://ip_address:12060/v1/tenants/orei

    The tenancy OCID is returned in your web browser.

  • Roving Edge Infrastructure user Identity and Access Management (IAM) OCID. Obtain the tenancy OCID using the following steps:

    1. Access the Device Console for your device node.

    2. Open the navigation menu and select Identity Management > Users.

      The Users page appears. All users are listed in tabular form.

    3. Click the user whose details you want to get. The user's Details page appears.

    4. Find the OCID line under User Information in the Details page and copy link and save this information.

      Keep the IAM User web page open as you need it to upload the public key in PEM format.

    5. Create an .oci directory in the home directory on the host where you have OCI CLI installed. For example:

      • Linux and Macintosh:

        cd $HOME
mkdir .oci
cd .oci

      • Windows PowerShell:

        mkdir %HOMEDRIVE%%HOMEPATH%\.oci
cd ~
cd .oci

  • RSA Key Pair in PEM format: In a Linux or Macintosh terminal, or Windows PowerShell window, switch to the .oci directory and run:

    oci setup keys

    The command creates the following files in the .oci directory:

    • oci_api_key_public.pem

    • oci_api_key.pem

    Return to Device Console and go to the IAM User Details page. Click API Keys on the left side of the window, then click Add Public Key and select the oci_api_key_public.pem file for upload.

    After uploading the key, record the Fingerprint value as you will need it later for updating the configuration file.

    In the .oci directory, create the config file and populate it with the following:

    [DEFAULT]
user=user_ocid_from_RED_console
fingerprint=your_fingerprint_generated_after_uploading_the_public_key
key_file=path_to_home_directory/.oci/oci_api_key.pem
tenancy=tenancy_ocid_from_curl_command_or_web_browser
region=region_name
 
Example:
[DEFAULT]
user=ocid1.user.orei..uniqueID
fingerprint=10:00:00:db:dd:c4:de:71:a1:01:10:88:f9:95:1e:23
tenancy=ocid1.tenancy.orei..uniqueID
region=us-ashburn-1
key_file=/Users/username/.oci/oci_api_key.pem

If you included a passphrase when creating the PEM key, add a line with: 

pass_phrase=your_passphrase
Note

Roving Edge Infrastructure OCIDs, such as for user and tenancy, contain orei in the values.

If you already have a config file with a DEFAULT profile, you can create more entries with a profile with the name of your choice.

Each Roving Edge Infrastructure tenancy (device) needs its own profile. You can use a base name and increment the number for each device. The following example uses the profile name ROVINGEDGE1 from the base name ROVINGEDGE:

The following example uses the profile ROVINGEDGE1:

[DEFAULT]
user=user_ocid
fingerprint=your_fingerprint
key_file=path_to_home_directory/.oci/oci_api_key.pem
tenancy=tenancy_ocid
region=region_name
[ROVINGEDGE1]
user=user_ocid_from_RED_console_UI
fingerprint=your_fingerprint_generated_after_uploading_the_public_key
key_file=path_to_home_directory/.oci/oci_api_key.pem
tenancy=tenancy_ocid_from_curl_command_or_web_browser
region=region_name
 
Example:
[DEFAULT]
user=ocid1.user.oc1..uniqueID
fingerprint=10:00:00:db:dd:c4:de:71:a1:01:10:88:f9:95:1e:23
tenancy=ocid1.tenancy.oc1..uniqueID
region=us-ashburn-1
key_file=/Users/username/.oci/oci_api_key.pem
[ROVINGEDGE1]
user=ocid1.user.orei..uniqueID
fingerprint=10:00:00:db:dd:c4:de:71:a1:01:10:88:f9:95:1e:23
tenancy=ocid1.tenancy.orei..uniqueID
region=us-ashburn-1
key_file=/Users/username/.oci/oci_api_key.pem
Note

All Roving Edge Infrastructure OCIDS contain the string orei.

If you're using a non-default profile name, include the --profile profile_name option in all CLI commands. For this example, using the ROVINGEDGE1 profile requires you include --profile ROVINGEDGE1 in your CLI syntax. The following section "Setting Up the OCI CLI RC File" describes an optional method of eliminating this requirement.

Each Roving Edge Infrastructuredevice requires its own profile. Pick a base name such as ROVINGEDGE and increment the number for each device. For example: ROVINGEDGE1.

Setting Up the OCI CLI RC File

Oracle strongly recommends setting up an optional OCI CLI RC file when using Roving Edge Infrastructure devices. Setting up an OCI CLI RC file makes running CLI commands easier by eliminating the need to include the --profile profile_name option in all CLI commands.

The OCI CLI RC file needs to match the profile set in the config file. If you are using a DEFAULT profile in the config file, the OCI CLI RC file also uses DEFAULT. If you created a profile with another name, such as ROVINGEDGE1, use ROVINGEDGE1 profile for the OCI CLI RC file.

Before setting up the OCI CLI RC file, perform the following tasks to get the following information:

  • Create a cert bundle:

    Return to where you generated your PEM keys and run the following command:

    echo -n | openssl s_client -showcerts -connect ip_address:8015|sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > bundle.pem

    A file with three certificates is created in the .oci directory. Record the path for future use.

  • Create a file called oci_cli_rc in the .oci directory with the following contents:

    [DEFAULT]
# Specifies cert bundle to use
cert-bundle = path_to_bundle/.oci/bundle.pem
# Specifies default compartment id so it doesn't have to be set as env variable or on CLI
compartment-id = tenancy_ocid_used_in_config_file
# Defines endpoint to use for compute
compute.endpoint = https://otec-console-local:19060
# Defines endpoint to use for object storage
os.endpoint = https://otec-console-local:8019
# Defines namespace
os.namespace = rover-namespace
# Defines endpoint to use for IAM
iam.endpoint = https://otec-console-local:12050
# Defined endpoint for block
bv.endpoint = https://otec-console-local:5012
# Defined endpoint for VCN 18336
network.endpoint = https://otec-console-local:18336

If you already have an oci_cli_rc file configured with a DEFAULT entry, match the name used in the config file. If you use another profile name (for example, ROVINGEDGE1), the oci_cli_rc file includes that name. For example:

[DEFAULT]
# Defines OCI Tenancy object namespace
os.namespace = idbcq3arv1py
[ROVINGEDGE1]
# Specifies cert bundle to use
cert-bundle = /Users/username/.oci/bundle.pem
# Specifies default compartment id so it doesn't have to be set as env variable or on CLI
compartment-id = ocid1.tenancy.orei..uniqueID
# Defines Roving Edge endpoint to use for compute
compute.endpoint = https://otec-console-local:19060
# Defines Roving Edge endpoint to use for object storage
os.endpoint = https://otec-console-local:8019
# Defines Roving Edge object namespace
os.namespace = rover-namespace
# Defines Roving Edge endpoint to use for IAM
iam.endpoint = https://otec-console-local:12050
# Defined Roving Edge endpoint for block
bv.endpoint = https://otec-console-local:5012
# Defined Roving Edge endpoint for VCN 18336
network.endpoint = https://otec-console-local:18336

Using the CLI

You can specify CLI options using the following commands:

  • --option value

    or

  • --option=value

Not using the OCI CLI RC File

If you're not using an oci_cli_rc file, the basic CLI syntax for Roving Edge Infrastructure is:

oci resource action options --endpoint resource_endpoint --compartment-id Roving_Edge_tenancy_ocid_used_in_config_file --cert-bundle path_to_cert bundle

This syntax is applied to the following:

  • oci is the shortened CLI command name

  • os bucket is an example of a resource

  • create is an example of an action

  • Other strings are options

Resource endpoints are:

  • Object Storage: https://otec-console-local:8019

    Object Storage commands also need to include the --namespace rover-namespace option.

  • Compute: https://otec-console-local:19060

  • Block Storage: https://otec-console-local:5012

  • IAM: https://otec-console-local:12050

  • Network: https://otec-console-local:18336

  • Data Sync: https://otec-console-local:21060

  • System Upgrade: https://otec-console-local:23060

  • Events: https://otec-console-local:18000
  • Monitoring: https://otec-console-local:22060
  • Diagnostic Tooling: https://otec-console-local:31060

Include the value otec-console-local for the IP address line entry in the /etc/hosts file to use the oci_cli_rc file functionality.

If you're using an Oracle Cloud Infrastructure certificate, resource endpoints are:

Ex: DNS:*.commonname.com

  • Object Storage: https://rover.commonname.com:8019

    Object Storage commands also need to include the --namespace rover-namespace option.

  • Compute: https://rover.commonname.com:19060

  • Block Storage: https://rover.commonname.com:5012

  • IAM: https://rover.commonname.com:12050

  • Network: https://rover.commonname.com:18336

  • Data Sync: https://rover.commonname.com:21060

  • System Upgrade: https://rover.commonname.com:23060

  • Events: https://rover.commonname.com:18000

  • Monitoring: https://rover.commonname.com:22060

  • Diagnostic Tooling: https://rover.commonname.com:31060

Note

If the device certificate is self-signed, Include the value otec-console-local for the IP address line entry in the /etc/hosts file to use the oci_cli_rc file functionality.

This is an example of a CLI command:

oci os bucket list --compartment-id ocid1.tenancy.orei..uniqueID --endpoint https://otec-console-local:8019 --cert-bundle /Users/username/.oci/bundle.pem

If your config file entry for the Roving Edge Infrastructure environment is not DEFAULT, include the --profile profile_name option in your CLI syntax. For example:

oci os bucket list --compartment-id ocid1.tenancy.orei..uniqueID --endpoint https://otec-console-local:8019 --cert-bundle /Users/username/.oci/bundle.pem --profile ROVINGEDGE1
Note

Avoid entering confidential information as part of the display name.

Using the OCI CLI RC File

If you are using the oci_cli_rc file, the basic CLI syntax for Roving Edge Infrastructure is:

oci resource action options

This syntax is applied to the following:

  • oci is the shortened CLI command name

  • os bucket is an example of a resource

  • list is an example of an action

  • Other strings are options

The following command line example shows a typical CLI command construct for listing the buckets in a specified compartment:

oci os bucket list --compartment-id ocid1.tenancy.orei..uniqueID

If your config file entry for the Roving Edge Infrastructure environment is not DEFAULT, you must also include the --profile profile_name option in your CLI syntax. For example:

oci os bucket list --compartment-id ocid1.tenancy.orei..uniqueID --endpoint https://otec-console-local:8019 --cert-bundle /Users/username/.oci/bundle.pem --profile ROVINGEDGE1

Required and Optional Parameters

Most command line utilities have both required and optional parameters that are included with the command. Required parameters are included in the command's syntax, for example:

oci os bucket create --name name [OPTIONS]

If the required parameter value is listed as a variable, for example name, then you must provide a value. Enter the command as it appears in the documentation.

The inclusion of [OPTIONS] in the command syntax indicates optional parameters. Access the CLI's online help for a list of optional parameters and their usage.

Running CLIs on a VM Instance

Follow these guidelines for running CLIs on compute instances hosted by Roving Edge Infrastructure devices.

Note

The instructions in this topic are for Oracle Linux host computers.

  • Have the VM go through the following local IP:

    169.254.169.254

  • Have the VM refer to the Roving Edge Infrastructure device as otec-console-local.

  • Employ the following IP Tables rules:

    { for i in 19060 8019 12050 21060 22060 23060 22060 12060;do iptables -I 
BareMetalInstanceServices -d 169.254.169.254/32 -p tcp -m tcp --dport $i -m 
comment --comment "Rover service access port" -j ACCEPT;done }

    See Service Ports for a list of available ports.

Unsupported CLI Commands

The following CLI commands are currently not supported. Workarounds are provided where available.

  • Object Storage CLIs: oci os list

    You can only use the oci os list command when you include the --fields option. For example:

    # oci os object list --bucket-name generic-image --fields name,size,timeCreated,md5,etag
{
"data": [
{
"archival-state": null,
"etag": "b2c123ff0f1231c4c7f41ff92294e4a0-32",
"md5": "ssYx/w8SUcTH9B/5IpTkoA==-32",
"name": "exported-image",
"size": 2132357120,
"storage-tier": null,
"time-created": "2022-03-01T19:50:03.076000+00:00",
"time-modified": null
},    {
      "archival-state": null,
      "etag": "fe5e3c12e12e31de65b86722a6fe29e7-32",
      "md5": "/l48AOleMd5luGcipv4p5w==-32",
      "name": "imported-image-20210830-1542_ocid1.image.oc1.iad..uniqueID.oci",
      "size": 2132224000,
      "storage-tier": null,
      "time-created": "2022-03-01T19:50:59.968000+00:00",
      "time-modified": null
    }
  ],
  "prefixes": []
}

  • Compute CLIs: oci compute instance list-vnics

    The oci compute instance list-vnics command lists the VNICs that are attached to the specified instance and is often used to get the public IP for a compute node. This CLI is not currently supported in Roving Edge Infrastructure. You can get VNIC information, including IP address associated with a VNIC attached to a compute node, using any of the following methods:

    • Device Console: Go to the following location:

      Compute > Instances > Instance Details > Attached VNICs

      The IP addresses for the VNICs are listed in the dialog box that appears.

    • CLI: oci compute instance list-vnics

      First, run the following command to list all the VNIC's attachments:

      oci compute vnic-attachment list --instance-id <> --all

      Next, run the following command for the specific VNIC for which you want to get details:

      oci network vnic get --vnic-id <>

      The following example shows these two commands run together with their respective returns:

      # oci compute vnic-attachment list --instance-id ocid1.instance.orei.orei-1..uniqueID --all
{
  "data": [
    {
      "availability-domain": "orei-1-ad-1",
      "compartment-id": "ocid1.tenancy.orei..uniqueID",
      "display-name": null,
      "id": "ocid1.vnicattachment.orei.orei-1..uniqueID",
      "instance-id": "ocid1.instance.orei.orei-1..uniqueID",
      "lifecycle-state": "ATTACHED",
      "nic-index": 0,
      "subnet-id": "ocid1.subnet.orei.orei-1..uniqueID",
      "time-created": "2022-03-01T21:07:00.937000+00:00",
      "vlan-id": null,
      "vlan-tag": 1,
      "vnic-id": "ocid1.vnic.orei.orei-1..uniqueID"
    }
  ]
}

# oci network vnic get --vnic-id ocid1.vnic.orei.orei-1..uniqueID
{
  "data": {
    "availability-domain": "orei-1-ad-1",
    "compartment-id": "ocid1.tenancy.orei..uniqueID",
    "defined-tags": {},
    "display-name": "test-instance",
    "freeform-tags": {},
    "hostname-label": "test-instance",
    "id": "ocid1.vnic.orei.orei-1..uniqueID",
    "is-primary": true,
    "lifecycle-state": "AVAILABLE",
    "mac-address": "02:00:17:00:04:00",
    "nsg-ids": [],
    "private-ip": "10.0.0.2",
    "public-ip": "10.145.142.128",
    "skip-source-dest-check": false,
    "subnet-id": "ocid1.subnet.orei.orei-1..",
    "time-created": "2022-03-01T21:07:00.155000+00:00",
    "vlan-id": null
  },
  "etag": "2c082d1c"
}

      If only one VNIC is attached, you can combine these CLI commands with other Linux tools to limit the output to just the public IP address using the following command:

      oci compute vnic-attachment list --instance-id <> --all|grep -m 1 vnic-id|awk -F'"' '{print $4}'|xargs -I{} oci network vnic get --vnic-id {}|grep public-ip|awk -F'"' '{print $4}'

      For example:

      # oci compute vnic-attachment list --instance-id ocid1.instance.orei.orei-1..uniqueID --all|grep -m 1 vnic-id|awk -F'"' '{print $4}'|xargs -I{} oci network vnic get --vnic-id {}|grep public-ip|awk -F'"' '{print $4}'
10.145.142.128

Accessing Command Line Interface Help

All CLI help commands have an associated help component you can access from the command line. To view the help, enter any command followed by the --help or -h option. For example:

oci os bucket --help