Oracle Cloud Infrastructure Documentation

OCI Utilities

Instances using Oracle Linux platform images include a set of utilities (oci-utils) that allow the instance to access information about infrastructure resources. These utilities consist of a service component and command line tools that help automatically discover or provision resources.

Installing the OCI Utilities

Instances launched with Oracle Linux 7 or later automatically include the Oracle Cloud Infrastructure (OCI) utilities (oci-utils) package installed. The utilities aren't available on other distributions.

To use the OCI utilities, you must meet the following prerequisites:

  • Ensure that the oci_included repository is enabled. This repository is enabled by default in Oracle Linux platform images. This repository contains all package dependencies, including the required OCI SDK and Python packages. All required packages are installed with the oci-utils package.
  • Ensure that the OCI utilities have sufficient permissions to access Oracle Cloud Infrastructure by doing one of the following:
    • Create the SDK configuration file for the host. For more information, see SDK and CLI Configuration File.
      Note

      You might need to install the CLI for your environment before running the oci setup config command to create the SDK configuration file. For more information, see Installing the CLI.
    • Use instance principals by adding the instance to a dynamic group that was granted access to Oracle Cloud Infrastructure services. For more information, see Managing Dynamic Groups.
    • Configure oci-utils to allow root to use a non-privileged user's Oracle Cloud Infrastructure configuration files. For more information, see the configuration file located in the /etc/oci-utils.conf.d directory of the instance.
  • Choose the method to access the utilities, and perform any setup procedures for that method, as needed:

For a video on how to install and set up the OCI utilities, see Enabling OCI Utilities in Oracle Linux on Oracle Cloud Infrastructure Instances in the Oracle Linux Training Station.

Updating the OCI Utilities

To update to the latest version of oci-utils:

sudo yum update oci-utils

Using the ocid Daemon

The ocid daemon is the service component of the oci-utils. It monitors for changes in the VNIC and iSCSI configuration of the instance and tries to automatically attach or detach devices as they appear or disappear - for example, when they're created or deleted using the Oracle Cloud Infrastructure Console, CLI, or the API.

To start the ocid daemon using systemd and set the ocid service to start automatically during system boot:

sudo systemctl enable --now ocid.service

To confirm that the service is active (running):

sudo service ocid status

For example:

$ sudo service ocid status
Redirecting to /bin/systemctl status ocid.service
  ocid.service - Oracle Cloud Infrastructure utilities daemon
   Loaded: loaded (/etc/systemd/system/ocid.service; enabled; vendor preset: enabled)
   Active: active (running) since Thu 2021-02-04 18:01:25 GMT; 1min 42s ago
 Main PID: 16630 (python3)
   CGroup: /system.slice/ocid.service
           └─16630 /usr/bin/python3 /usr/lib/python3.6/site-packages/oci_util...

Feb 04 18:01:23 mor-demoinst-10 systemd[1]: Starting Oracle Cloud Infrastruc....
Feb 04 18:01:24 mor-demoinst-10 sudo[16705]:     root : TTY=unknown ; PWD=/ ...w
Feb 04 18:01:25 mor-demoinst-10 systemd[1]: Started Oracle Cloud Infrastruct....
Hint: Some lines were ellipsized, use -l to show in full.

OCI Utilities Reference

Learn more details about each utility including a description, usage examples, and options.

Managing Volumes

Managing Networking

Viewing Configuration Information

Configuring Notifications

Converting the Oracle Linux Minimal Image

You can also view OCI utility option and detailed information by accessing the OCI utility man pages. For information about how to access OCI utility man pages, see Common OCI Utility Options.

oci-compartmentid

Use the oci-compartmentid utility to display the Oracle Cloud Identifier (OCID) of the compartment where the instance is running.

Usage

oci-compartmentid [-h | --help]

To view the compartment OCID of the instance:

sudo oci-compartmentid

For example:

$ sudo oci-compartmentid
ocid1.compartment1.oc1..OCID

For information about the oci-compartmentid utility option, see Common OCI Utility Options.

oci-growfs

If you expand the boot volume of an Oracle Cloud Infrastructure (OCI) Linux-based instance, you can then use the oci-growfs utility to expand the root partition of the instance. This lets you fully use the newly expanded boot volume.

Note

Only XFS and ext4 file systems are supported.

By default, a Linux-based instance doesn't automatically use the entire boot volume if the boot volume is larger than or equal to 50 GB. If the boot volume attached to the instance is less than 50 GB, no changes are made to the system when using the oci-growfs utility.

Usage

/usr/libexec/oci-growfs [-y] [-n] [-h | --help]

Expanding the Root Partition of an Instance

To expand the root partition of the instance:

  1. Use the lsblk command to confirm the OS has identified the new size of the boot volume.

    For example:

    lsblk
NAME               MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda                  8:0    0  100G  0 disk
├─sda1               8:1    0  100M  0 part /boot/efi
├─sda2               8:2    0    1G  0 part /boot
└─sda3               8:3    0 98.9G  0 part
  ├─ocivolume-root 252:0    0 88.9G  0 lvm  /
  └─ocivolume-oled 252:1    0   10G  0 lvm  /var/oled
sdb                  8:16   0   70G  0 disk

    If the disk volume isn't the expected size, run the commands to rescan the boot volume. See Rescanning the Disk for Volumes Attached to Linux-Based Instances.

  2. Run the oci-growfs utility with the y option to answer "yes" to all prompts. 

    sudo /usr/libexec/oci-growfs -y

    For example:

    $ sudo /usr/libexec/oci-growfs -y
Volume Group: ocivolume 
Mountpoint Data

---------------

mountpoint: /

source: /dev/mapper/ocivolume-root

filesystem type: xfs

source size: 58.9G

type: lvm

size: 58.9G

physical devices: ['/dev/sda3']

physical volumes: ['/dev/sda', '/dev/sda']

partition number: ['3']

volume group name: ocivolume

volume group path: /dev/ocivolume/root

Partition dry run expansion "/dev/sda3" succeeded.

CHANGE: partition=3 start=2304000 old: size=144496607 end=146800606 new: size=207411167 end=209715166 

Partition expand expansion "/dev/sda3" succeeded.
update-partition set to true
FLOCK: try exec open fd 9, on failure exec exits this program
FLOCK: /dev/sda: obtained exclusive lock
resizing 3 on /dev/sda using resize_sfdisk_gpt
209715200 sectors of 512. total size=107374182400 bytes
## sfdisk --unit=S --dump /dev/sda
label: gpt
label-id: DEC7F1D7-BEBD-4622-9B47-8ADF594E82FD
device: /dev/sda
unit: sectors
first-lba: 34
last-lba: 209715166

/dev/sda1 : start=        2048, size=      204800, type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B, uuid=CEB6C9AA-4543-4CBF-A44E-D75D7BDDC644, name="EFI System Partition"
/dev/sda2 : start=      206848, size=     2097152, type=0FC63DAF-8483-4772-8E79-3D69D8477DE4, uuid=340A48CC-18ED-4C1A-AAD7-90CDB8E0B600
/dev/sda3 : start=     2304000, size=   144496607, type=E6D6D379-F507-44C2-A23C-238F2A3DF928, uuid=8BB84AB7-F5DF-47F1-B630-21442C9102C1
padding 33 sectors for gpt secondary header
max_end=209715166 tot=209715200 pt_end=146800606 pt_start=2304000 pt_size=144496607
resize of /dev/sda returned 0.
FLOCK: /dev/sda: releasing exclusive lock

CHANGED: partition=3 start=2304000 old: size=144496607 end=146800606 new: size=207411167 end=209715166

Extending /dev/sda3 succeeded.
Device /dev/sda3 extended successfully.
Logical volume /dev/ocivolume/root extended successfully.

For information about the oci-growfs utility options, see Common OCI Utility Options.

oci-image-expand

Use the oci-image-expand utility to convert the Oracle Linux Minimal instance to add services and packages of a standard Oracle Linux platform image. With this utility, the minimal instance can restore nearly the same functionality as a standard Oracle Linux platform image.

For information about the latest Oracle Linux Minimal image, see Oracle Linux 9.x Images.

The oci-image-expand utility requires root privileges.

Prerequisite

Install the OCI Utilities on the minimal instance. For more information, see Installing the OCI Utilities.

Conversion Types

The oci-image-expand utility provides two types of Oracle Linux Minimal instance conversions:

  • Default: Restores default Oracle Linux platform systemd services, diagnostic packages, cloud configuration settings, and configures and enables swap on the instance. Restoring default platform functionality doesn't increase instance boot time. This conversion type is always applied by the oci-image-expand utility.

  • Reboot Required: Restores default Oracle Linux platform functionality, as described in the Default conversion type, and restores one or more of the following user-selectable features: Choosing any of these selectable features increases instance boot time and requires a reboot to take effect.
Note

Running the oci-instance-expand utility affects user-configured settings on the instance. For example, the utility restores cloud-init config to default Oracle Linux platform image settings, thus overwriting any user-configured cloud-config changes. Also, if you choose to restore Ksplice, the utility reinstalls the oci-linux-config package so that the new access key is stored in the proper configuration file. Don't run the utility on instances other than minimal instances.

The oci-image-expand utility log files are located at: /var/log/oci-image-expand.log

Usage

oci-image-expand [-h | --help]

Restoring Default Platform Image Functionality

To restore default Oracle Linux platform image functionality to the Oracle Linux Minimal instance:

Run the oci-image-expand utility and press Enter at the prompt, without making any selections.

For example:

$ /usr/libexec/oci-image-expand
Please select the set of reboot required functions, if any
Selecting a function transitions from not selected [ ] to selected [+] or vice versa
 
[ ] 0) All reboot options

[ ] 1) Enable SELinux

[ ] 2) Enable Kdump

[ ] 3) Enable Ksplice
  
Select the desired options using their number (again to uncheck, ENTER when done):
ENTER

Restoring Reboot Required Platform Image Functionality

To restore Oracle Linux platform image functionality that requires an instance reboot to take effect:

  1. Run the oci-image-expand utility. 

    /usr/libexec/oci-image-expand

  2. At the prompt, do one of the following, and then press Enter:

    • Enter zero to restore all features in the list (SELinux, Kdump, and Ksplice).
    • Enter a single number, between one and three, to restore one of the features in the list.
    • Enter two numbers, between one and three, to restore two of the features in the list.

    For example, to restore the SELinux and Ksplice functionality on the Oracle Linux Minimal instance:

    $ /usr/libexec/oci-image-expand
Please select the set of reboot required functions, if any
Selecting a function transitions from not selected [ ] to selected [+] or vice versa
 
[ ] 0) All reboot options

[+] 1) Enable SELinux

[ ] 2) Enable Kdump

[+] 3) Enable Ksplice
  
Select the desired options using their number (again to uncheck, ENTER when done):
 1 3
The following options were selected:
    Enable SELinux
    Enable Ksplice
The chosen options will now be applied. Press any key to continue (within 10 seconds)
    Note

    If you change your mind about a feature you have selected, type the number again before pressing Enter to deselect the feature. If you already pressed Enter, press Ctrl+C to cancel the operation.

  3. At the prompt, enter y to reboot the instance.
    A reboot is required to enable and activate all restored services. 
Do you wish to reboot now? (y/n)y

For information about the oci-image-expand utility option, see Common OCI Utility Options.

oci-instanceid

Use the oci-instanceid utility to display the Oracle Cloud Identifier (OCID) of the instance.

Usage

oci-instanceid [-h | --help]

To view the OCID of the compute instance:

sudo oci-instanceid

For example:

$ sudo oci-instanceid
ocid1.instance1.oc1.iad1.OCID

For information about the oci-instanceid utility option, see Common OCI Utility Options.

oci-iscsi-config

Use the oci-iscsi-config utility to list and configure iSCSI devices attached to an Oracle Cloud Infrastructure (OCI) Linux-based instance. When run without any command line options, oci-iscsi-config lists devices that need attention.

Caution

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Console, API, or CLI.

Usage

oci-iscsi-config [subcommand] [-h | --help]

Subcommands

The oci-iscsi-config utility has the following subcommands.

oci-iscsi-config Utility Subcommands

Subcommand

For more information, see...

show

Displaying iSCSI Configurations

sync

Synchronizing a Volume

create

Creating and Attaching a New Volume

attach

Attaching an Existing Volume

detach

Detaching a Volume

destroy

Deleting a Volume

For a training video that shows how to use the oci-iscsi-config utility, see Using OCI Utilities for Managing iSCSI Storage for Oracle Cloud Infrastructure Instances in the Oracle Linux Training Station.

For information about the oci-iscsi-config utility option, see Common OCI Utility Options.

Displaying iSCSI Configurations

The oci-iscsi-config show subcommand lists the iSCSI devices and iSCSI information for the instance. This subcommand works with the ocid daemon to monitor device creation and deletion through the Console, CLI, or the API, and automatically discovers those changes.

If the ocid daemon isn't running, the subcommand requires root privileges.

Usage

oci-iscsi-config show [-C | --compartments name] [-A | --all] [--output-mode mode] [--details] [--no-truncate] [-h | --help]

To display a list of all devices attached to the instance:

  1. Run the oci-iscsi-config show subcommand.

    sudo oci-iscsi-config show

    For example: 

    $ sudo oci-iscsi-config show
Currently attached iSCSI devices:
          Volume name           |Attached device| Size |
--------------------------------------------------------
         mor-demo-bv20          |      sdb      | 50G  |
Block volumes information:
              Name              | Size |          Attached to           |              OCID              |
----------------------------------------------------------------------------------------------------------
         mor-demo-bv30          | 50GB |               -                |ocid1.volume.oc1.OCID|

  2. Optionally use the --details and --no-truncate options with the oci-iscsi-config show subcommand to display more detailed information that isn't shortened in the output:

    sudo oci-iscsi-config show --details --no-truncate

    For example:

    $ sudo oci-iscsi-config show --details --no-truncate
Currently attached iSCSI devices:
             Target                       |          Volume name           |          Volume OCID                       | Persistent portal  |   Current portal   |Session State|Attached device| Size |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
iqn.2015-12.com.oracleiaas:exampleuniqueID|         mor-demo-bv20          |ocid1.volume.oc1.iad.OCID  |  172.16.10.4:3260  |  172.16.10.4:3260  |  LOGGED_IN  |      sdb      | 50G  |

Block volumes information:
              Name              | Size |          Attached to           |              OCID                        |     IQN      | Compartment |Availability domain|
------------------------------------------------------------------------------------------------------------------------------------------------------------
         mor-demo-bv30          | 50GB |               -                |ocid1.volume.oc1.iad.OCID|      -       | virtdoc.dev  |DSdu:US-ASHBURN-AD-3|

  3. Optionally change the output presentation to be more readable by using the --output-mode option with the oci-iscsi-config show subcommand:

    sudo oci-iscsi-config show --output-mode mode

    For example, to display the output presentation in text mode: 

    $ sudo oci-iscsi-config show --output-mode text
Currently attached iSCSI devices
Volume name: mor-demo-bv20
Attached device: sdb
Size: 50G

Block volumes information
Name: mor-demo-bv30
Size: 50GB
Attached to: -
OCID: ocid1.volume.oc1.iad..OCID

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config show Option Details

Option

Description

-A | --all

Displays all iSCSI devices. By default, only devices that aren't attached to an instance are listed.

-C | --compartments name

Displays iSCSI devices in the given compartment or all compartments (if all is specified for name).

Creating and Attaching a New Volume

Use the oci-iscsi-config create subcommand to create and attach a block volume to an instance. This subcommand requires the OCI SDK for Python to be installed and configured. For more information about the OCI SDK, see Software Development Kits and Command Line Interface.

This subcommand requires root privileges.

Usage

oci-iscsi-config create [-S | --size size] [-v | --volume-name name] [--attach-volume] [-c | --chap] [-h | --help]

To create and attach a volume, use the oci-iscsi-config create utility with the -S, --volume-name, and --attach-volume options:

sudo oci-iscsi-config create -S size --volume-name=name --attach-volume

For example, to create and attach a volume that's 70 GB in size to the instance, with the volume name mor-demo-by70:

$ sudo oci-iscsi-config create -S 70 --volume-name=mor-demo-by70 --attach-volume
Creating a new 70 GB volume
Volume name=mor-demo-by70 created
Attaching the volume to this instance
Attaching iSCSI device
iscsiadm attach Result: command executed successfully

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config create Option Details

Option

Description

-v | --volume-name name

Sets the display name for the volume. Avoid entering confidential information for the display name.

-c | --chap

Attaches the device with the Require CHAP Credentials flag.

Attaching an Existing Volume

Use the oci-iscsi-config attach subcommand to attach an existing block volume to the instance and make the volume available to the system. The OCI SDK for Python is required for selecting volumes using their OCID. For more information about the OCI SDK, see Software Development Kits and Command Line Interface.

This subcommand requires root privileges.

Note

When using an IQN, the volume must already be attached (assigned) to the instance in the Console. This option can be used to attach multiple devices at the same time by providing a comma-separated list of IQNs.

Usage

oci-iscsi-config attach [-I | --iqns IQN] [-O | --ocids OCID] [-u | --username name] [-p | --password password] [-c | --chap] [-h | --help]

To attach a specific block volume to the instance:

$ sudo oci-iscsi-config attach --iqns iqn.2015-12.com.oracleiaas:IQN

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config attach Option Details

Option

Description

-I | --iqns IQN

A comma-separated list of the iSCSI qualified names (iqns) of the iSCSI device, or devices, to attach to the instance.

-O | --ocids OCID

A comma-separated list of the OCIDs of the iSCSI device, or devices, to attach to the instance.

-u | --username name

Use the specified username as the CHAP username when authentication is needed for attaching a device. This option isn't needed when the OCI SDK for Python is available.

-p | --password password

Use the supplied password as the CHAP password when authentication is needed for attaching a device. This argument isn't needed when the OCI SDK for Python is available.

-c | --chap

Attach the device with the Require CHAP Credentials flag.

Synchronizing a Volume

Use the oci-iscsi-config sync subcommand to attach available block devices to the instance and perform sync operations. The subcommand requires root privileges.

Usage

oci-iscsi-config sync [-a | --apply] [-y | --yes] [-h | --help]

To attach available block devices to the instance and synchronize the changes with OCI, use the oci-iscsi-config sync subcommand with the --apply option:

sudo oci-iscsi-config sync --apply

For example:

$ sudo oci-iscsi-config sync --apply
Attaching the volume to this instance
Attaching iSCSI device
iscsiadm attach Result: command executed successfully

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config sync Option Details

Option

Description

-a | --apply

Perform sync operations.

Detaching a Volume

Use the oci-iscsi-config detach subcommand to detach a device with the given IQN (a unique ID assigned to a device). If the volume (or any partition of the volume) is mounted, this option tries to unmount it first.

This subcommand requires root privileges.

Note

You can detach multiple devices at the same time by providing a comma-separated list of IQNs.

Usage

oci-iscsi-config detach [-I | --iqns IQN] [-f | --force] [-h | --help]

To detach a specific device from the instance, use the oci-iscsi-config detach subcommand with the -I option:

sudo oci-iscsi-config detach -I IQN

For example:

$ sudo oci-iscsi-config detach -I  iqn.2015-12.com.oracleiaas:IQN
Detaching volume mor-demo-bv70 (iqn.2015-12.com.oracleiaas:IQN)
Volume [iqn.2015-12.com.oracleiaas:oracleiaas:IQN] is detached
Updating detached volume cache file: ['iqn.2015-12.com.oracleiaas:oracleiaas:IQN']

To view the IQN or OCID of the volume you want detached, use the oci-iscsi-config show subcommand. For information, see Displaying iSCSI Configurations.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config detach Option Details

Option

Description

-f | --force

Continue detaching even if the device can't be unmounted.

-I | --iqns IQN

A comma-separated list of the iSCSI qualified names (iqns) of the iSCSI device, or devices, to detach from the instance.

Deleting a Volume

To delete a block storage volume with the given OCID, use the oci-iscsi-config destroy subcommand.

Note

You can delete multiple devices at the same time by providing a comma-separated list of OCIDs.

Usage

oci-iscsi-config destroy [-O | --ocids OCID] [-y | --yes] [-h | --help]

To delete a specific block volume from the instance, use the oci-iscsi-config-destroy subcommand with the -O option:

sudo oci-iscsi-config destroy -O OCID

For example:

$ sudo oci-iscsi-config destroy -O ocid1.volume.oc1.OCID
WARNING: the volume(s) will be destroyed.  This is irreversible.  Continue?
y
Volume [ocid1.volume.oc1.iad.OCID] is destroyed

You can view the OCID of the volume by using the oci-iscsi-config show utility subcommand. For information, see Displaying iSCSI Configurations.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-iscsi-config destroy Option Details

Option

Description

-O | --ocids OCID

A comma-separated list of the block volume OCIDs to delete.

oci-metadata

Use the oci-metadata utility to display or set metadata for an Oracle Linux-based compute instance. When run without any command line options, oci-metadata lists all available metadata.

For more information about instance metadata, see Getting Instance Metadata.

Usage

oci-metadata [-h | --human-readable] [-j | --json] [-g | --get key] [--export] [--trim] [--value-only] [-u key_value] [-i | --instance-id OCID] [--help]

Getting All Metadata For the Instance

To view all metadata for the instance, run the oci-metadata utility with no options:

sudo oci-metadata

For example:

$ sudo oci-metadata
Instance details:
  Display Name: my-example-instance
  Region: phx - us-phoenix-1 (Phoenix, AZ, USA)
  Canonical Region Name: us-phoenix-1
  Availability Domain: cumS:PHX-AD-1
  Fault domain: FAULT-DOMAIN-3
  OCID: ocid1.instance.oc1.phx.OCID
  Compartment OCID: ocid.compartment.oc1..OCID
  Instance shape: VM.Standard2.1
  Image ID: ocid1.image.oc1.phx.OCID
  Created at: 1569529065596
  state: Running
  agentConfig:
    managementDisabled: False
    monitoringDisabled: False
  Instance Metadata:
    ssh_authorized_keys: example-key
Networking details:
  VNIC OCID: ocid1.vnic.oc1.phx.OCID
  VLAN Tag: 2392
  Private IP address: 10.0.0.16
  MAC address: 02:00:17:03:D8:FE
  Subnet CIDR block: 10.0.0.0/24
  Virtual router IP address: 10.0.0.1

Getting Specific Metadata For the Instance

To view instance metadata for a specified key, use the --get option with the oci-metadata utility:

sudo oci-metadata --get key

For example, to view only the state of the compute instance:

$ sudo oci-metadata --get state
Instance details:
Instance state: Running

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-metadata Option Details

Option

Description

-g key | --get key

Retrieve data only for the specified key. The metadata keys for an instance can be defined by Compute or you can create custom keys. For more information, see Metadata Keys.

--export

Used with the -g or --get option, display a shell command to export the key as an environment variable.

--trim

Used with the -g or --get option, trim the key path to the last component to make the output more concise. For example: instance/metadata/ssh_authorized_keys to ssh_authorized_keys. If the key matches multiple keys, only the first matching key is displayed.

--value-only

Used with the -g or --get option, display only the values matching the get key.

-u key_value

Update the value for the specific key (or keys). For key_value, specify a string, a JSON value, or a pointer to a file with JSON content in the following format: key=file:/path/to/file

-i | --instance-id OCID

Get or update the metadata of the instance with the specific OCID. By default, oci-metadata works with the metadata from the instance that you logged in to.

oci-network-config

The oci-network-config utility lets you configure network interfaces for the instance. This utility must be run as root.

The oci-network-config utility shows the current virtual network interface cards (VNICs) provisioned in Oracle Cloud Infrastructure (OCI) and configured for this instance. When a secondary VNIC is provisioned in OCI, it must be explicitly configured on the instance using the oci-network-config utility.

The network interfaces that are being configured can be placed inside separate network namespaces. This separation is necessary when VNICs are in subnets (different VCNs) with overlapping address blocks and the network applications aren't bound directly to the interfaces. Network namespaces require applications to be launched in the namespaces explicitly (with the ip netns exec ns command) to establish association with the interface. When namespaces aren't used, policy-based routing is configured to provide a default route to the secondary VNIC´s virtual router (default gateway) when the VNIC´s address is the source address.

Bare metal secondary VNICs are configured using VLANs (where there is no corresponding physical interface). These VNICs appear as two additional interfaces when showing IP links, with names in MACVLAN_FORMAT for the MAC VLAN and VLAN_FORMAT for the IP VLAN.

Usage

oci-network-config [subcommand] [-q | --quiet] [-h | --help]

Subcommands

The oci-network-config utility has the following subcommands.

oci-network-config Utility Subcommands

Subcommand

For more information, see...

show

Displaying the Current Network Configuration

show-vnics

Displaying Configured VNICs

show-vnics-all

Displaying All Configured VNICS

show-vcns

Displaying VCN Information

show-subnets

Displaying Subnet Information

configure

Configuring VNICs

unconfigure

 Deleting the IP Configuration for Provisioned Secondary VNICs

attach-vnic

Creating and Attaching a VNIC

detach-vnic

Detaching a VNIC

add-secondary-addr

Adding a Secondary Address

remove-secondary-addr

Removing a Secondary IPv6 Address

For a training video that shows how to use the oci-network-config utility, see Network Interface Management Using OCI Utilities on Oracle Linux Instances in the Oracle Linux Training Station.

For information about the oci-network-config utility options, see Common OCI Utility Options.

Displaying the Current Network Configuration

The oci-network-config show subcommand shows information about the VNICs configured on the instance. You can view the current network configuration, such as the provisioned VNICs and current IP configurations for the instance. VNICs that aren't yet configured are marked with ADD, and IP configurations that no longer have an associated VNIC are marked with DELETE.

The output for this command is the default action if the oci-network-config utility is entered without any options.

Usage

oci-network-config show [--output-mode mode] [-I | --include item] [-X | --exclude item] [--details] [--no-truncate] [-h | --help]

To display the current network configuration:

sudo oci-network-config show

For example: 

$ sudo oci-network-config show 
Network configuration
 State | Link | Status |  IP address |        VNIC        |        MAC        |
------------------------------------------------------------------------------
   -   | ens3 |   UP   | 10.2.20.254 |  hostname_ipv6_01  | 02:00:17:01:30:D5 |
  ADD  | ens4 |   UP   | 10.2.10.121 | vnic20220912090629 | 02:00:17:01:A9:0E |


Operating System level network configuration:
CONFIG      ADDR          SUBNET     BITS   VIRTROUTER      NS    IND      IFACE     VLTAG     VLAN    STATE        MAC                                                VNIC ID                                          
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  -     10.2.20.254     10.2.20.0     24    10.2.20.1       -      2        ens3      3181      -        UP  02:00:17:01:30:D5 ocid1.vnic.oc1.uk-london-1.VNIC_OCID  
 ADD    10.2.10.121     10.2.10.0     24    10.2.10.1       -      3        ens4      1435      -        UP  02:00:17:01:A9:0E ocid1.vnic.oc1.uk-london-1.VNIC_OCID

To configure VNICs that aren't yet configured (labeled ADD), and delete IP addresses that don't have any associated VNICs, use the oci-network-config config subcommand. For more information, see Configuring VNICs.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config show Option Details

Option

Description

-I | --include item

Include an IP address or VLAN interface that was previously excluded using the --exclude option in automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name.

-X | --exclude item

Persistently exclude an IP address or VLAN interface from automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name. Use the --include option to include the IP address or VLAN interface again.

Creating and Attaching a VNIC

Use the oci-network-config attach-vnic subcommand to create and attach a VNIC to an instance. You can assign a public or private IP address to the new VNIC with this subcommand.

Important

Attaching a VNIC with a primary IPv6 address isn't supported by OCI.

Usage

oci-network-config attach-vnic [-I | --ip-address ip_address] [-ipv4 | --ipv4] [-ipv6 | --ipv6] [-i | --nic-index index] [--subnet subnet] [-n | --name name] [--assign-public-ip] [-h | --help]

To create a VNIC and attach the VNIC to an instance, use the oci-network-config attach-vnic subcommand with the -n option:

sudo oci-network-config attach-vnic -n name

For example, to create a VNIC named ex-demo-inst-10 and attach the VNIC to the instance:

$ sudo oci-network-config attach-vnic -n ex-demo-inst-10
creating VNIC: 10.102.119.140

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config attach-vnic Option Details

Option

Description

-I | --ip-address ip_address

Assign the given private IP address to the VNIC. If this option isn't used, an unused IP address from the subnet is assigned automatically to the VNIC.

-ipv4 | --ipv4

Assign an IPv4 address to the VNIC. If the --ipv4 option is used, an unused IPv4 address from the subnet is assigned to the VNIC. If the --ip-address option is specified with this option, the --ipv4 and --ipv6 options are ignored.

-ipv6 | --ipv6

Assign an IPv6 address to the VNIC. If the --ipv6 option is used, an unused IPv6 address from the subnet is assigned to the VNIC. If you use the --ip-address option instead, the --ipv4 and --ipv6 options are ignored.

Important!: Attaching a VNIC with a primary IPv6 address isn't supported by OCI.

The following message displays when running the oci-network-config attach-vnic with the --ipv6 option.

# sudo oci-network-config attach-vnic --ipv6
Attaching a vnic with a primary ipv6 address is not yet supported by OCI.

-i | --nic-index index

Assign the VNIC to the specified physical NIC card. For index, specify the index number assigned to the physical NIC card. The default value is 0. This option is used only for bare metal instances.

--subnet subnet

Connect the VNIC to the given subnet. For subnet, specify an OCID or a regular expression that's matched against the display name of all available subnets. When --ip-address is used, the subnet is inferred from the IP address, or defaults to the subnet of the primary VNIC.

-n | --name name

Set the display name for the VNIC. Avoid entering confidential information.

--assign-public-ip

Assign a public IP address to the VNIC. By default, only a private IP address is assigned.

Configuring VNICs

The oci-network-config configure subcommand adds IP configuration for VNICs that aren't configured and deletes the IP configuration of VNICs that are no longer provisioned. This command synchronizes the instance IP configuration with the current OCI provisioning.

Usage

oci-network-config configure [-n | --namespace format] [-r | --start-sshd] [-I | --include item] [-X | --exclude item] [-h | --help]

To configure all the VNICs on the instance:

sudo oci-network-config configure

For example:

$ sudo oci-network-config configure
Configured

To configure the VNICs on the instance, except for a specific VNIC, use the oci-network-config configure subcommand with the -X option:

sudo oci-network-config configure -X VNIC_OCID

For example:

$ sudo oci-network-config configure -X VNIC_OCID
Configured

You can confirm the VNICs are configured by running the oci-network-config show subcommand. After configuration, no ADD or DELETE labels will be displayed in the output, unless you chose to exclude a VNIC from being configured. For more information, see Displaying the Current Network Configuration.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config configure Option Details

Option

Description

-n | --namespace format

When configuring, place interfaces in the namespace identified by the given format. Format can include $nic and $vltag variables. The name defaults to DEF_NS_FORMAT_BM for BMs and DEF_NS_FORMAT_VM for VMs. When configuring multiple VNICs, ensure the namespaces are unique.

-r | --start-sshd

Start sshd in the namespace (if -n is present).

-I | --include item

Include an IP address or VLAN interface that was previously excluded using the --exclude option in automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name.

-X | --exclude item

Persistently exclude an IP address or VLAN interface from automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name. Use the --include option to include the IP address or VLAN interface again.

Displaying Configured VNICs

The oci-network-config show-vnics subcommand shows information about VNICs configured on the instance.

Usage

oci-network-config show-vnics [--output-mode mode] [--details] [--ocid OCID] [--name name] [--ip-address primary_ip] [--no-truncate] [-h | --help]

To show information about VNICs configured on the instance:

sudo oci-network-config show-vnics

For example:

$ sudo oci-network-config show-vnics
VNICs Information:
              Name              |   Private IP  |                                           OCID                                           |       MAC       |
--------------------------------------------------------------------------------------------------------------------------------------------------------------
        ex-demo-inst-10         |10.102.119.140|     ocid1.vnic.oc1.iad.OCID                                                    |00:00:17:02:CC:CB|
        mor-demoinst-10         |10.102.118.251|     ocid1.vnic.oc1.iad.OCID                                                    |02:00:17:02:C6:B2|

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config show-vnics Option Details

Option

Description

--ocid OCID

Show information about the VNIC that matches the given Oracle Cloud Identifier (OCID).

--name name

Show information about the VNIC associated with the given name.

--ip-address primary_IP

Show information about the VNIC associated with the given primary IP address.

Displaying All Configured VNICS

Use the oci-network-config show-vnics-all subcommand to view detailed information about all VNICs configured on this instance.

Usage

oci-network-config show-vnics-all [--output-mode mode] [-h | --help]

To display all VNICs configured on the instance:

sudo oci-network-config show-vnics-all

For example:

# sudo oci-network-config show-vnics-all
Virtual Network Interface Information:
        Name        |  Private IP |        MAC        | Config |                                           OCID                                          | Primary  |      Subnet      | Subnet cidr  |       State        | NIC  |   Public IP    |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  hostname_ipv6_01  | 10.2.20.254 | 02:00:17:01:30:D5 |   -    | ocid1.vnic.oc1.iad.OCID                                                |   True   | hostname_uk02_02 | 10.2.20.0/24 | AVAILABLE-ATTACHED |  -   | 140.238.76.113 |
      IP address details      
                      Private IP               |                                             OCID                                             |      
      ----------------------------------------------------------------------------------------------------------------------------------------      
                     10.2.20.254               | ocid1.privateip.oc1.iad.OCID |      
      
      
 vnic20220912090629 | 10.2.10.121 | 02:00:17:01:A9:0E |   -    | ocid1.vnic.oc1.iad.OCID                                               |    -     | hostname_uk02_01 | 10.2.10.0/24 | AVAILABLE-ATTACHED |  -   |       -        |
      IP address details      
                      Private IP               |                                             OCID                                             |      
      ----------------------------------------------------------------------------------------------------------------------------------------      
                     10.2.10.121               | ocid1.privateip.oc1.iad.OCID |      
       2603:c020:c003:3a10:b64c:8f35:7f9e:7e87 |   ocid1.ipv6.oc1.iad.OCID    |

For information about the oci-network-config show-vnics-all options, see Common OCI Utility Options.

Adding a Secondary Address

Use the oci-network-config add-secondary-addr utility to add a secondary private IP address with the specified IPv4 or IPv6 address to an existing VNIC.

Usage

oci-network-config add-secondary-addr [-ipv4 | --ipv4] [-ipv6 | --ipv6] [-I | --ip-address ip_address] [-O | --ocid OCID] [-h | --help]

To add a private secondary IP address, in this case an IPv6 address, to an existing VNIC, use the oci-network-config add-secondary-addr subcommand with the --ipv6 and --ocid options:

sudo oci-network-config add-secondary-addr --ipv6 --ocid OCID

For example:

$ sudo oci-network-config add-secondary-addr --ipv6 --ocid ocid1.vnic.oc1.iad.OCID
Provisioning secondary private IPv6: 2603:c020:c003:3a10:b64c:8f35:7f9e:7e87
IP 2603:c020:c003:3a10:b64c:8f35:7f9e:7e87 has been assigned to vnic ocid1.vnic.oc1.iad.OCID

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config add-secondary-addr Option Details

Option

Description

-ipv4 | --ipv4

Specify that an IPv4 private secondary address be added to an existing VNIC. This option is the default if the command is entered without any options.

-ipv6 | --ipv6

Specify that an IPv6 private secondary address be added to an existing VNIC.

-I ip_address | --ip-address ip_address

Specify secondary private IP address to add to the VNIC.

-O | --ocid OCID

Assign the secondary address to the VNIC associated with the specific OCID.

Deleting the IP Configuration for Provisioned Secondary VNICs

Use the oci-network-config unconfigure subcommand to delete all IP configuration for provisioned secondary VNICs (except the ones explicitly excluded). The primary VNIC can't be deleted.

Usage

oci-network-config unconfigure [-I | --include item] [-X | --exclude item] [-h | --help]

To delete all IP configuration for provisioned secondary VNICs, use the oci-network-config unconfigure subcommand:

sudo oci-network-config unconfigure

For example:

$ sudo oci-network-config unconfigure
Unconfigured

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config unconfigure Option Details

Option

Description

-I | --include item

Include an IP address or VLAN interface that was previously excluded using the --exclude option in automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name.

-X | --exclude item

Persistently exclude an item (IP address or VLAN interface) from automatic configuration/deconfiguration. For item, you can specify a VNIC OCID, an IP address, or a VLAN interface name. Use the --include option to include the IP address or VLAN interface again.

Removing a Secondary IPv6 Address

Use the oci-network-config remove-secondary-addr subcommand to remove a secondary private IP address with the specified IPv4 or IPv6 address from an existing VNIC.

Usage

oci-network-config remove-secondary-addr [-I | --ip-address ip_address] [-h | --help]

To remove a private secondary IPv6 address from an existing VNIC, use the oci-network-config remove-secondary-addr subcommand with the -I option:

sudo oci-network-config remove-secondary-addr -I ip_address

For example, to remove the secondary IPv6 address, 2603:c020:c003:3a10:b64c:8f35:7f9e:7e87, from an existing VNIC:

$ sudo oci-network-config remove-secondary-addr -I 2603:c020:c003:3a10:b64c:8f35:7f9e:7e87
Deconfigure secondary private IP 2603:c020:c003:3a10:b64c:8f35:7f9e:7e87

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config remove-secondary-addr Option Details

Option

Description

-I | --ip-address ip_address

Specify the secondary private IP address to remove from the VNIC.

Detaching a VNIC

Use the oci-network-config detach-vnic subcommand to detach and delete the VNIC with the specific OCID or IP address from the instance. This subcommand can be used to remove the assigned IP address from an existing VNIC. However, the primary VNIC can't be detached. Any secondary private IP addresses associated with the VNIC are also deleted.

Usage

oci-network-config detach-vnic [-I | --ip-address ip_address] [-O | --ocid OCID] [-h | --help]

To detach a VNIC from the instance, use the oci-network-config detach-vnic subcommand with the --ocid option:

sudo oci-network-config detach-vnic --ocid OCID

For example, to detach a VNIC with a specific VNIC OCID from the instance: 

$ sudo oci-network-config detach-vnic --ocid ocid1.vnic.oc1.iad.OCID
Detaching VNIC 10.2.10.121 [ocid1.vnic.oc1.iad.OCID]
VNIC [ocid1.vnic.oc1.iad.OCID] is detached.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config detach-vnic Option Details

Option

Description

-I | --ip-address ip_address

Detach the VNIC with the given IP address.

--ocid OCID

Detach the VNIC with the given OCID.

Displaying VCN Information

The oci-network-config show-vcns subcommand displays virtual cloud network (VCN) information in the compartment where the instance resides.

Usage

oci-network-config show-vcns [--output-mode mode] [--details] [--ocid OCID] [--name name] [--no-truncate] [-h | --help]

To display detailed VCN information in text output format, use the oci-network-config show-vcns subcommand with the --details and --output-mode text options:

sudo oci-network-config show-vcns --details --output-mode text

For example:

$ sudo oci-network-config show-vcns --details --output-mode text
Virtual Cloud Network Information:

Name: hostname_uk_01
IPv4 cidr block: 10.0.0.0/16
IPv6 cidr block: 2603:c020:c003:6c00::/56
OCID: ocid1.vcn.oc1..example_OCID
IPv4 cidr blocks: 10.0.0.0/16
DNS label: gtijskenuk01
State: AVAILABLE
Lifecycle state: AVAILABLE

Name: hostname_uk_02
IPv4 cidr block: 10.2.0.0/16
IPv6 cidr block: 2603:c020:c003:3a00::/56
OCID: ocid1.vcn.oc1..example_OCID
IPv4 cidr blocks: 10.2.0.0/16
DNS label: gtijskenuk02
State: AVAILABLE
Lifecycle state: AVAILABLE

Name: hostname_uk_ref
IPv4 cidr block: 10.253.0.0/16
IPv6 cidr block: 2603:c020:c007:9f00::/56
OCID: ocid1.vcn.oc1..example_OCID
IPv4 cidr blocks: 10.253.0.0/16
DNS label: gtijskenukref
State: AVAILABLE
Lifecycle state: AVAILABLE

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config show-vcns Option Details

Option

Description

--ocid OCID

 Display the VCN with the given OCID.

--name name

Display the VCN with the given name.

Displaying Subnet Information

The oci-network-config show-subnets subcommand shows subnet information in the compartment where this instance resides.

Usage

oci-network-config show-subnets [--output-mode mode] [--details] [--ocid OCID] [--name name] [--no-truncate] [-h | --help]

To view detailed subnet information in JSON output format, use the oci-network-config show-subnets subcommand with the --details and --output-mode json options:

sudo oci-network-config show-subnets --details --output-mode json

For example:

$ sudo oci-network-config show-subnets --details --output-mode json
[
  {
    "Name": "Public Subnet-hostname_uk_01",
    "ipv4 cidr block": "10.0.0.0/24",
    "ipv6 cidr block": "2603:c020:c003:6c00::/64",
    "OCID": "ocid1.subnet.oc1..OCID",
    "VCN name": "hostname_uk_01",
    "VCN ocid": "ocid1.vcn.oc1..OCID",
    "Public": true,
    "Public ingress": true,
    "DNS label": "sub06230933270",
    "Domain name": "sub06230933270.gtijskenuk01.oraclevcn.com",
    "Lifecycle state": "AVAILABLE"
  },
  {
    "Name": "hostname_uk_ref_02",
    "ipv4 cidr block": "10.253.20.0/24",
    "ipv6 cidr block": "2603:c020:c007:9f20::/64",
    "OCID": "ocid1.subnet.oc1..OCID",
    "VCN name": "hostname_uk_ref",
    "VCN ocid": "ocid1.vcn.oc1..OCID",
    "Public": true,
    "Public ingress": true,
    "DNS label": "gtijskenukref02",
    "Domain name": "gtijskenukref02.gtijskenukref.oraclevcn.com",
    "Lifecycle state": "AVAILABLE"
  },
  {
    "Name": "hostname_uk_ref_01",
    "ipv4 cidr block": "10.253.10.0/24",
    "ipv6 cidr block": "2603:c020:c007:9f10::/64",
    "OCID": "ocid1.subnet.oc1..OCID",
    "VCN name": "hostname_uk_ref",
    "VCN ocid": "ocid1.vcn.oc1..OCID",
    "Public": true,
    "Public ingress": true,
    "DNS label": "gtijskenukref01",
    "Domain name": "gtijskenukref01.gtijskenukref.oraclevcn.com",
    "Lifecycle state": "AVAILABLE"
  },
]

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-network-config show-subnets Option Details

Option

Description

--ocid OCID

Show information about the subnet that matches the given Oracle Cloud Identifier (OCID).

--name name

Show information about the subnet associated with the given name.

oci-network-inspector

The oci-network inspector utility displays a detailed network report for a specific compartment or network configured for the instance.

Usage

oci-network-inspector [-C | --compartment OCID] [-N | --vcn OCID] [-h | --help]

Displaying a Detailed Report for a Specific VCN

To display a detailed report for a specific VCN, run the oci-network-inspector utility and use the -N option to specify the VCN OCID:

sudo oci-network-inspector -N OCID

For example:

$ sudo oci-network-inspector -N ocid1.compartment.oc1..OCID

Compartment: KVM_workspace (ocid1.compartment.oc1..OCID)

  vcn  : uk_02 (ocid1.vcn.oc1..OCID)
    Security List: Default Security List for uk_02
      Ingress: tcp              0.0.0.0/0:-                       ---:22
      Ingress: icmp             0.0.0.0/0:-                    code-4:type-3
      Ingress: icmp           10.2.0.0/16:-                 code-None:type-3
      Ingress: tcp                   ::/0:-                       ---:22
      Ingress: 58                    ::/0:-                       ---:-
      Egress : all                    ---:-                 0.0.0.0/0:-
      Egress : all                    ---:-                      ::/0:-

    Subnet  : uk02_02 (ocid1.subnet.oc1..OCID)
      ipv4 cidr block : 10.2.20.0/24
      ipv6 cidr block : 2603:c020:c003:3a20::/64
      DNS domain name : gtijskenuk0202.gtijskenuk02.oraclevcn.com
       Security List: Default Security List for uk_02
         Ingress: tcp              0.0.0.0/0:-                       ---:22
         Ingress: icmp             0.0.0.0/0:-                    code-4:type-3
         Ingress: icmp           10.2.0.0/16:-                 code-None:type-3
         Ingress: tcp                   ::/0:-                       ---:22
         Ingress: 58                    ::/0:-                       ---:-
         Egress : all                    ---:-                 0.0.0.0/0:-
         Egress : all                    ---:-                      ::/0:-

      Private IP      : 10.2.20.42(primary)  Host: gtijsken-amd-kvm-lon-flex3-vnicb752
        Vnic            : ocid1.vnic.oc1..OCID (AVAILABLE-ATTACHED)
        Vnic PublicIP   : None
        Instance        : amd_kvm_lon_flex3
          Instance State  : RUNNING
          Instance ocid   : ocid1.instance.oc1..OCID

      ...

Displaying a Detailed Report for a Specific Compartment

To view a detailed network report for a specific compartment, run the oci-network-inspector utility and use the -C option to specify a compartment OCID:

sudo oci-network-inspector -C OCID

For example:

$ sudo oci-network-inspector -C ocid1.compartment.oc1..OCID

Compartment: scottb_sandbox (ocid1.compartment.oc1..OCID)

  vcn: scottb_vcn
    Security List: Default Security List for scottb_vcn
      Ingress: tcp              0.0.0.0/0:-                       ---:22
      Ingress: icmp             0.0.0.0/0:-                    code-4:type-3
      Ingress: icmp           10.0.0.0/16:-                 code-None:type-3
      Ingress: tcp              0.0.0.0/0:80                      ---:80
      Ingress: tcp              0.0.0.0/0:43                      ---:43
      Ingress: tcp              0.0.0.0/0:-                       ---:-
      Egress : all                    ---:-                 0.0.0.0/0:-

     Subnet: Public Subnet cumS:PHX-AD-3 Avalibility domain: cumS:PHX-AD-3
         Cidr_block: 10.0.2.0/24 Domain name: sub99999999999.scottbvcn.oraclevcn.com
       Security List: Default Security List for scottb_vcn
         Ingress: tcp              0.0.0.0/0:-                       ---:22
         Ingress: icmp             0.0.0.0/0:-                    code-4:type-3
         Ingress: icmp           10.0.0.0/16:-                 code-None:type-3
         Ingress: tcp              0.0.0.0/0:80                      ---:80
         Ingress: tcp              0.0.0.0/0:43                      ---:43
         Ingress: tcp              0.0.0.0/0:-                       ---:-
         Egress : all                    ---:-                 0.0.0.0/0:-

     ...

For information about the oci-network-inspector utility option, see Common OCI Utility Options.

oci-notify

The oci-notify utility sends a message to a Notifications service topic. This utility must be run as root.

A message is composed of a message header (title) and file. The Notifications service configuration for the topic determines where and how the messages are delivered. Topics are configured using the Oracle Cloud Infrastructure (OCI) Console, API, or CLI.

For more information about the Notifications service, including how to create topics, see Notifications Overview.

Usage

oci-notify [subcommand] [-h | --help]

Subcommands

The oci-notify utility has the following subcommands.

oci-notify Utility Subcommands

Subcommand

For more information, see...

config

Configuring a Notifications Service Topic on an Instance

message

 Publishing a Message to a Topic

For information about the oci-notify utility option, see Common OCI Utility Options.

Configuring a Notifications Service Topic on an Instance

Use the oci-notify config subcommand to write the Notifications service topic OCID to the oci.conf file. After configured, you can publish messages to this configured topic.

By default, the path to the configuration file is /etc/oci-utils/oci.conf. You can override the configuration file path by using the OCI_CONFIG_DIR environment variable.

Usage

oci-notify config notifications_topic_OCID [-h | --help]

To write the OCID of a configured Notifications service topic to the oci.conf file, use the oci-notify config subcommand, and specify the Notifications service topic OCID.

For example:

$ sudo oci-notify config ocid1.onstopic.oc1..OCID

For information about the oci-notify-config utility option, see Common OCI Utility Options.

Publishing a Message to a Topic

With the oci-notify message subcommand, you can publish the contents of a file or a text string with the specified title to the configured topic.

Note: When the message is published, the oci-notify utility prepends the instance name to the subject of the message. For example: instance_name:log messages

Usage

oci-notify message [-t | --title 'message_title'] [-f | --file message_file] [-h | --help]

To send the contents of the /var/log/messages file with the title 'logging messages' to the configured topic, use the --title and --file options with the oci-notify-message subcommand.

For example:

$ sudo oci-notify message --title 'logging messages' --file /var/log/messages

To send a text string to the configured topic, enter a line of text in single quotation marks for the value of the --file option.

For example:

$ sudo oci-notify message --title 'sending a text' --file 'Today is a beautiful day'

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-notify-message Option Details

Option

Description

-t | --title message_title

Specify the title to be used in the message header (for example, 'log messages' if you're sending log files). The message_title must be enclosed in either single or double quotation marks. Message headers are truncated to 128 characters.

-f | --file message_file

Specify the full or relative directory path, HTTP, or FTP URL of the message file or the text string to be sent. Larger files are split into 64-KB chunks and are sent as separate messages. The number of chunks is limited to 10.

If the specified message_file isn't recognized as a URL or the directory path doesn't exist, the text entered for message_file is sent as a text string. Text strings are limited to 128 characters.

oci-public-ip

Use the oci-public-ip utility to display the public IP address of the current compute instance, in either human-readable or JSON format.

The oci-public-ip utility uses the Oracle Cloud Infrastructure (OCI) SDK to discover the IP address (see Software Development Kits and Command Line Interface). If the IP address can't be obtained by this method, the oci-public-ip utility then tries the Session Traversal Utilities for NAT (STUN) protocol as a last resort to discover the IP address. For more information about STUN, see the STUN Wikepedia article.

Usage

oci-public-ip [-h | --human-readable] [-j | --json] [-g | --get] [-a | --all] [-s | --sourceip source_IP] [-S | --stun-server STUN_server] [-L | --list-servers] [--instance-id OCID] [--help]

Displaying the IP Address of the Current Instance

Run the oci-public-ip command with no options to return the IP address of the current instance:

sudo oci-public-ip

For example:

$ sudo oci-public-ip
Public IP address: 203.0.113.2

Displaying the IP Address of Another Instance

To view the public IP address of another instance other than the current instance, use the oci-public-ip utility with the --instance-id option.

Note

This option requires the OCI SDK for Python to be installed and configured. For more information, see Software Development Kits and Command Line Interface.
sudo oci-public-ip --instance-id OCID

For example:

$ sudo oci-public-ip --instance-id ocid1.instance.oc1.phx.OCID
Public IP address: 203.0.113.2

Viewing a List of STUN Servers

To display a list of STUN servers, use the oci-public-ip utility with the --list-servers option:

sudo oci-public-ip --list-servers

For example:

$ sudo oci-public-ip --list-servers
stun.stunprotocol.org
stun.counterpath.net
stun.voxgratia.org
stun.callwithus.com
stun.ekiga.net
stun.ideasip.com
stun.voipbuster.com
stun.voiparound.com
stun.voipstunt.com

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-public-ip Utility Options

Option

Description

-g | get

Prints the IP address only.
--instance-id OCID

Displays the public IP address of the given instance instead of the current one. Requires the OCI SDK for Python to be installed and configured.
-L | --list-servers

Prints a list of known STUN servers and exits.

-s | --sourceip source_IP

Specifies the source IP address to use.

-S | --stun-server STUN_server

Specifies the STUN server to use.

oci-volume-data

Use the oci-volume-data utility to view data about a specific iSCSI volume attached to an Oracle Linux-based compute instance.

The oci-volume-data utility requires the -k (key) option to display data for a specific iSCSI volume. Key option values can be the display name, OCID, or iqn (iSCSI Qualified Name) of the volume.

Usage

oci-volume-data [-h | --help] [-k KEY | --key KEY] [-p | --par {name, iqn, ocid, portal, chap, attachestate, avdomain, compartment, attached, size, state}] [-v | --value-only]

Viewing All Data About an Attached iSCSI Volume

To view all data about an iSCSI volume attached to the compute instance:

sudo oci-volume-data -k OCID

For example:

$ sudo oci-volume-data -k OCID
             display name: name=oci1-iscsi-volume-1
                     ocid: ocid1.volume.oc1.OCID
                      iqn: iqn.2122-45.com.oracleiaas:IQN
                portal ip: 123.245.6.7
              portal port: 1234
                chap user: None
            chap password: None
      availability domain: DSdu:US-EAST-DOMAIN
              compartment: comparment1
           compartment id: ocid1.compartment.OCID
              attached to: oci-utils-instance
         attachment state: --
                     size: 70GB
                    state: AVAILABLE

Viewing Specific Data About an Attached iSCSI Volume

Optionally use the -k, -p, and -v (value-only) options with the oci-volume-data utility to narrow down what you want displayed for the iSCSI volume:

oci-volume-data -k OCID -p size -v

For example, to display only the size of an iSCSI volume, in this case, 70 GB: 

$ oci-volume-data -k ocid1.volume.OCID -p size -v
70GB

For more information about the supported option values (such as size, state, compartment, and so on), see the man page for oci-volume-data. For information about accessing OCI utility man pages, see Common OCI Utility Options.

Option Details

The following table provides detailed information about options specific to this utility or subcommand. For information about the common options used across OCI utilities, see Common OCI Utility Options.

oci-volume-data Utility Options

Option

Description

-k KEY | --key KEY

Required. The key to identify the volume. The KEY value can be the OCID, IQN, or display name of the volume.

-p | --par

Specifies the source IP address to use.

-v | --value-only

Show only the values in the output.

OCI Utilities Summary

A summary of the OCI utilities components.

Name Description
ocid The service component of oci-utils, which runs as a daemon started by systemd. This service scans for changes in the iSCSI and VNIC device configurations and caches the OCI metadata and public IP address of the instance.
oci-compartmentid Displays the Oracle Cloud Identifier(OCID) of the compartment where the instance is running.
oci-growfs Expands the root file system of the instance to its configured size.
oci-image-expand Converts the Oracle Linux Minimal instance to add services and packages of a standard Oracle Linux platform image.
oci-instanceid Displays the OCID of the instance.
oci-iscsi-config Lists or configures iSCSI devices attached to a compute instance. If no command line options are specified, lists devices that need attention.
oci-metadata Displays metadata for the compute instance. If no command line options are specified, lists all available metadata. Metadata includes the instance 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.
oci-network-config Lists or configures virtual network interface cards (VNICs) attached to the compute instance. When a secondary VNIC is provisioned in the cloud, it must be explicitly configured on the instance using this script or similar commands.
oci-network-inspector Displays a detailed report for a given compartment or network.
oci-notify Sends a message to a Notification service topic.
oci-public-ip Displays the public IP address of the current system in either human-readable or JSON format.
oci-volume-data Displays data about a specific iSCSI volume attached to the instance.

Common OCI Utility Options

Many of the Oracle Cloud Infrastructure (OCI) utilities have the same options, or arguments, available when the utilities are run from the command line. These options and arguments help to further define what type of information is produced by the utility, or how a utility task is performed.

The following table lists the options, and their supported values, that are common across the OCI utilities.

Option Description
--help Displays help information about the utility, such as the utility usage, available options, and the supported values for each option. For example, to view the help for the oci-metadata utility:
$ sudo oci-metadata --help

usage: oci-metadata [-h] [-j] [-g KEY] [--value-only] [--export] [--trim]
                    [-u KEY=VALUE  [KEY=VALUE  ...]] [-i OCID] [--help]

Utility for displaying metadata for an instance running in the Oracle Cloud
Infrastructure.

optional arguments:
  -h, --human-readable  Display human readable output (default)
  -j, --json            Display json output
  ...
  --help                Display this help

--all

Shows all items, or values, in the output.

--details

Shows detailed information in the output.

--output-mode

Lets you define how the utility output is displayed. The following are the available OCI utility modes:

  • json: Displays the output in JSON format.
  • human-readable: Displays the output in human readable format.
  • parsable: Displays the output in parsable format.
  • table: Displays the output in a table.
  • text: Displays textual output.

--no-truncate

Doesn't shorten the values in the displayed output.

--truncate

Shortens the values in the displayed output.

-y| --yes

Answers "yes" at all prompts.

-n | --no

Answers "no" at all prompts.

-q | --quiet

Suppresses information messages.
Note

You can also view man pages for each OCI utility by entering man oci-utility at the command line. For example, to display the built-in manual pages for the oci-metadata utility:
man oci-metadata