Accessing Roving Edge Infrastructure

Describes the different methods for accessing Roving Edge Infrastructure.

Access Roving Edge Infrastructure features and functionality using the following methods.

Note

Use only ASCII text for all inputs to Roving Edge Infrastructure and Roving Edge Infrastructuredevices. This requirement applies to the browser-based Consoles, CLIs, and APIs.

Oracle Cloud Infrastructure Console

You can create and manage your Roving Edge Infrastructure device-based nodes and clusters using the Oracle Cloud Infrastructure Console. Here is where you also specify the workloads that determine the provision of these devices.

Note

You must have internet access to access the Oracle Cloud Infrastructure Console.

Roving Edge Device Console

Use the browser-based Roving Edge Device (RED) Console to manage your workloads, perform tasks, and monitor your system health. No internet access is required to access the Device Console. You can synchronize your object storage data using a connection to your home region.

The Device Console retains the look and feel of the Oracle Cloud Infrastructure Console, and allows you to manage and control the on-box services on your RED.

Access the Device Console with a host name by using one or both the following methods:

  • Add a DNS entry for the device that matches the name in the SSL certificate. Obtain the SSL certificate device name using the following command:

    echo quit | openssl s_client -connect IP_address:8015 -showcerts 2>/dev/null|(sleep .1; cat )|sed '/s:\/C/,/END/!d'|grep s:/C=|awk -F= '{print $NF}'
  • Add the host name and IP address to the hosts file on your local system.

Certificate Requirements

Download a root CA certificate from each Roving Edge Infrastructure device and import it to your Device Console host to gain access to that device. The following sections describe this process for different operating systems.

Linux and Mac OS

Linux and Mac OS: Use the following command to download the root CA certificate from a Roving Edge Infrastructure device:

echo quit | openssl s_client -connect ip_address:8015 -showcerts |perl -ne '$k++ if /BEGIN/;if(/BEGIN/ .. /END CERT/){print if $k==2}' >redroot.pem

where ip_address is the IP address of the Roving Edge Infrastructure device.

The root CA certificate is saved in the current directory in the redroot.pem file.

If you are using a Mac OS system on a Safari or Chrome browser, use the MacOS Keychain. Open the Finder and look for the redroot.pem file. Double-click the file and install the certificate.

If you are using a Mac OS or Linux system on a Firefox browser, go to Firefox Settings (or Preferences) > Privacy & Security > View Certificates > Authorities tab > Import and select the redroot.pem file. If a pop-up appears about trust settings, check both boxes regarding ability to identify websites and identify mail users.

If you are using a Linux system on a Chrome browser, go to Chrome Settings (or Preferences) > Security and Privacy > Security> Manage certificates > Authorities tab > Import > Browse and choose the redroot.pem file in the location where you created it. Next, click Open and select the Trust this certificate for identifying websites option. The certificate appears in the list of certificate authorities.

Now you can securely access the Device Console with your browser.

Windows

As a prerequisite, download and use the pre-built openssl binaries from the following sites:

Next, obtain the Roving Edge Infrastructure device's Root CA and Intermediate CA using SSL by running the following command:

execute command - openssl.exe s_client -connect device_id_address:8015 -showcerts 

For example:

D:\temp\openssl-3.0.0-win64-mingw\bin>openssl.exe s_client -connect 10.145.140.57:8015 -showcerts
CONNECTED(00000130)
Can't use SSL_get_servername
depth=2 C = US, ST = CA, O = Oracle Corporation, OU = Oracle Roving Edge Infra, CN = lab-17-red-1-root-CA
verify error:num=19:self-signed certificate in certificate chain
verify return:1
depth=2 C = US, ST = CA, O = Oracle Corporation, OU = Oracle Roving Edge Infra, CN = lab-17-red-1-root-CA
verify return:1
depth=1 C = US, ST = CA, O = Oracle Corporation, OU = Oracle Roving Edge Infra, CN = lab-17-red-1-intermediate-CA
verify return:1
depth=0 C = US, ST = CA, O = Oracle Corporation, OU = Oracle Roving Edge Infra, CN = lab-17-red-1
verify return:1

Obtain the certificate by pointing your browser at the Roving Edge Infrastructure device and clicking the NET-ERR_CERT_AUTHORITY_INVALID error message that appears.

The root CA certificate is the last (or third) certificate in the chain shown by Edge and Chrome browsers, or the middle (or second) certificate in Firefox browsers. Copy and paste the root CA certificate from the browser to Notepad and save the file with the filename redroot.cer. The certificate starts with a line containing: BEGIN CERTIFICATE and end with the line containing: END CERTIFICATE

If you are using an Edge and Chrome browser, add the certificate to the trust store by opening the File Explorer and double-clicking the redroot.cer file. Install the certificate. Place all certificates in the Trusted Root Certificate Authorities folder.

If you are using a Firefox browser, import the redroot.cer file into Firefox. Go to Firefox Settings > Privacy & Security > View Certificates > Authorities tab > Import, and choose the redroot.cer file. If a pop-up appears about trust settings, check both boxes regarding ability to identify websites and identify mail users.

Now you can securely access the Device Console with your browser.

Command Line Interface

The Oracle Cloud Infrastructure Command Line Interface (CLI) provides a set of command line-based tools 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 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 clusters, and running tasks directly on REDs. Install the CLI separately on each RED. CLIs installed on REDs run locally within your environment and do not 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

The host_name must match the issuer. You can access the issuer by running the following command:

echo -n | openssl s_client -showcerts -connect ip_address:8015 2> /dev/null|grep issuer|awk -F= '{print $3}'

In the return of this command, the issuer is displayed before -intermediate. For example, in the following return:

rover-install-red-1-intermediate-CA/C

the issuer is 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. Sometimes, the required parameter is a fixed default value, such as compartment-id orei. 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://id_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 your Device Console web browser.

    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 Details dialog box appears.

    4. Find the OCID line under User Information in the Details dialog box 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 or cluster) needs its own profile. You can use a base name and increment the number for each device or cluster. 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 are 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 or cluster requires its own profile. Pick a base name such as ROVINGEDGE and increment the number for each device or cluster. 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
Note

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.

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 are 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

Note

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.

The following command to create a transfer job shows a typical CLI command construct.

oci os bucket create --name MyBucket --endpoint https://otec-console-local:8019 --compartment-id ocid1.tenancy.orei..uniqueID --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 create --name MyBucket --endpoint https://otec-console-local:8019 --compartment-id ocid1.tenancy.orei..uniqueID --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

  • create is an example of an action

  • Other strings are options

The following command line example shows a typical CLI command construct for creating a bucket:

oci os bucket create --name MyBucket

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 create --name MyBucket --endpoint https://otec-console-local:8019 --compartment-id ocid1.tenancy.orei..uniqueID --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. Sometimes, the required parameter is a fixed default value, such as compartment-id orei. 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 CLI and Utilities on a VM Instance

Follow these guidelines for running CLIs and OCI utilities 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.

  • If you want to use the Linux-based OCI utilities described in OCI Utilities, perform the following tasks on a Roving Edge Infrastructure device-hosted instance:

    1. Go to the /etc/oci-utils.conf.d directory and make a backup copy of the 00-oci-utils.conf file.

    2. Open the 00-oci-utils.conf file and uncomment the following line:

      ;oci_sdk_user = opc
    3. Set the user to the Linux username with the default config and oci_cli_rc files:

      ;oci_sdk_user = username
    4. Run the following command as root (or use sudo):

      systemctl enable --now ocid.service
    5. Run the following command as root (or use sudo):

      iptables -I OUTPUT -d 169.254.169.254/32 -p tcp -m tcp --dport 8019 -j ACCEPT 

Unsupported OCI CLI and Utility 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
  • OCI Utilities:oci-public-ip

    The oci-public-ip OCI utility command gets the public IP address of a Compute instance. This utility depends on the oci compute instance list-vnics CLI command, which not currently supported in Roving Edge Infrastructure. To get the public IP address associated with a VNIC attached to a compute node, use the same workaround for oci compute instance list-vnics

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

API

Roving Edge Infrastructure provides REST APIs for most of its supported features and functionality. API Reference and Endpoints provides endpoint details and links to the available API reference documents. For general information about using the API, see REST APIs in the Oracle Cloud Infrastructure documentation.

Note

You must have an internet connection to access the API documentation residing on Oracle Cloud Infrastructure.