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.
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:
-
Access the Device Console for your device node.
-
Open the navigation menu and select Identity Management > Users.
The Users page appears. All users are listed in tabular form.
-
Click the user whose details you want to get. The user's Details page appears.
-
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.
-
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 theconfig
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
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
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 aresource
-
create
is an example of anaction
-
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
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
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 aresource
-
list
is an example of anaction
-
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.
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