Use OCI iSCSI Utility on Oracle Cloud Infrastructure

Send lab feedback

Use OCI iSCSI Utility on Oracle Cloud Infrastructure


In this tutorial, you learn how to enable and configure the OCI Utilities, and then run oci-iscsi-config to manage iSCSI block volumes on an Oracle Cloud Infrastructure instance.


Before the OCI Utilities package was available, you had to use the iSCSI administration commands, through the cloud web console, to manually attach and detach the block devices to an instance.

With the oci-iscsi-config command and the oci-utils daemon, you can easily create and manage volume attachments on the instance and in the cloud.

When the oci-utils daemon runs, it automatically looks for iSCSI block volumes available in the cloud compartment and attached through the web console.

It also supports the creation and removal of devices in the cloud resources, as well as the attachment of those devices to and from the Linux instance.


  • Install required software
  • Setup Oracle Cloud Infrastructure config file
  • Explore oci-iscsi-config command usage
  • Create block volumes
  • Attach block volumes
  • Detach block volumes on an instance
  • Destroy block volumes on an instance

What Do You Need?

  • A fully patched Oracle Linux system

Install Required Software

Complete the following steps to enable and configure the OCI Utilities:

  • Enable the Oracle Linux repositories
  • Install the required packages
  • Enable the ocid.service service
  1. Connect to ol-server by following the instructions in Oracle Linux Lab Basics . The guide provides connection and usage instructions.

  2. In a terminal, use the dnf config-manager command to enable the ol8_oci_included and ol8_developer repositories.

    sudo dnf config-manager --enable ol8_oci_included
    sudo dnf config-manager --enable ol8_developer

    With the repositories enable, you can install the required software.

  3. Use the dnf install command to install the python36-oci-sdk, python36-oci-cli, and oci-utils packages.

    sudo dnf -y install python36-oci-sdk python36-oci-cli oci-utils  

    The python36-oci-sdk package is for use in Oracle Cloud Infrastructure. The python36-oci-cli package provides the Python SDK for Oracle Cloud Infrastructure command line client utilities. The oci-utils package provides scripts for querying, validating, and configuring instances running Oracle Linux.

  4. Use the systemctl command to start and enable the OCI Utilities service (ocid.service).

    sudo systemctl enable --now ocid.service

    The enable --now option activates the service and enables restarts on reboots.

Setup Oracle Cloud Infrastructure SDK config File

This free lab provides a pre-generated SDK configuration which you copy to the lab server. You follow these instructions due to the configuration and constraints of the free lab environment. Outside of the free lab enviroment, follow the instructions in the Additional Lab Instructions section at the end of the tutorial.

  1. Create SDK default configuration directory.

    mkdir -p ~/.oci
  2. Complete the following to create the SDK configuration file.

    1. Open a new terminal from the desktop environment.

      Note: Do not connect to the ol-server.

    2. Copy all of the SDK configuration files to ol-server.

      scp ~/.oci/* oracle@<ip_address_of_ol-server>:~/.oci/.

      Type exit to close the terminal window.


      The following example shows key values in a configuration file:

  3. Switch to the terminal window connected to ol-server.

    Update the location of the key_file in the SDK configuration file. When copying the SDK configuration file from the desktop environment, you must modify the user's home directory portion of the key_file.

    sed -i 's/luna.user/oracle/g' ~/.oci/config

    If you modify the file manually with your editor of choice, you can replace /home/luna.user with the shorthand syntax of ~.

Explore oci-iscsi-config Command Usage

In this task, you explore the features of the oci-iscsi-config utility.

You can also watch the following video for an overview on managing ISCSI block volumes using OCI Utilities.

  1. Run the command oci-iscsi-config without any arguments.

    sudo oci-iscsi-config 

    The output reports no known information on any attached devices.

  2. Run the man oci-iscsi-config command to display a description of syntax and usage.

    man oci-iscsi-config
    • Familiarize yourself with the information provided
    • Press q to exit help
  3. Run the command oci-iscsi-config usage to display available arguments.

    sudo oci-iscsi-config usage

    As noted in the command output, the utility provides both positional and optional arguments.

    • The positional arguments include: create, attach, detach, and destroy.
    • The optional arguments include -h or --help, and the arguments associated with a specific positional argument
  4. Run the command oci-iscsi-config show.

    sudo oci-iscsi-config show

    When ISCSI devices are present, tabular output would show Volume name, Attached devices, and Size.

  5. Run the oci-iscsi-config show command again, adding the -h option to display available argurments.

    sudo oci-iscsi-config show -h

    The output displays the arguments available when using show. You use these arguments during this tutorial.

  6. Run the command oci-iscsi-config create -h to display its usage and a description of available arguments.

sudo oci-iscsi-config create -h

Explore the available options.

  • Run the oci-iscsi-config create without any options and note the error message.
sudo oci-iscsi-config create

The message tells you that the Size option is required.

Create Block Volumes

In the exercise, you create block volumes using the oci-iscsi-config create command.

  1. Open the web console and go to the details page of your instance. Keep the console open. Follow the instructions in Oracle Linux Lab Basics to access the web console.

  2. Run oci-iscsi-config create to create and attach a block volume to your instance.

    sudo oci-iscsi-config create -S 50 --volume-name=blkvm01 --attach-volume

    This takes a couple of minutes to complete. As it runs, the command displays notifications on its progress. When the command completes, a new block volume appears in the Oracle Cloud Infrastructure compartment and attched to your lab instance.

  3. Create another block volume, but do not attach it to your instance.

    sudo oci-iscsi-config create -S 50 --volume-name=blkvm02
  4. Run the command oci-iscsi-config show --details to display information on the attached block volume.

    sudo oci-iscsi-config show --details

    The table displays with truncated details about the attached volume (blkvm01).

  5. Run the command oci-iscsi-config show --details again, adding the --no-truncate option.

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

    The --no-truncate option prints the full IQN identifier and volume OCID of the attached volume.

  6. Run the oci-iscsi-config show --details command again adding the --output-mode=text argument.

    sudo oci-iscsi-config show --details --output-mode=text

    The output displays detailed information on attached volumes in an easy to read format.

  7. Run the oci-iscsi-config command again with the -s option.

    sudo oci-iscsi-config -s

    The -s option displays details on both attached and available volumes.

  8. Go to the Resources section on instance details page and click Attached block volumes.


    blkvm01 is the only block volume attached to your instance. You might need to refresh the screen.

  9. Go the Storage > Block Volumes in the web console to view the available block volumes in the compartment.


    Both block volumes are available in the compartment.

Attach a Block Volume

In this task, attach the blkvm02 to your instance using the oci-iscsi-config command.

  1. Run the command oci-iscsi-config attach -h to view its usage.

    sudo oci-iscsi-config attach -h

    Note: You can attach a block volume using the device's IQN or OCID.

  2. Run the command oci-iscsi-config -s to view the IQN and OCID of blkvm02.

    sudo oci-iscsi-config -s

    Notice that blkvm02 does not show an IQN, but blkvm01 does.

  3. Run oci-iscsi-config attach command using the -O argument with the volume's OCID.

    sudo oci-iscsi-config attach -O <OCID_of_BLKVM02>

    The volume successfully connects and becomes available for use. It is during the attachment that the instance performs iSCSI target discovery and login.

  4. Run the following oci-iscsi-config commands and note the information each displays.

    sudo oci-iscsi-config -s

    The -s option displays information relevant to the OCID of the instance to which it is attached, the IQN of the target device, the compartment name, and the availability domain.

    sudo oci-iscsi-config show

    The show argument provides details on the block volume name, the attached device name, and size of attached volumes.

    sudo oci-iscsi-config show --details --output-mode=text

    The --details --output-mode=text arguments format and display the most commonly searched information about attached volumes at your fingertips.

Detach a Block Volume

In this task, you detach a block volume.

  1. Run the command oci-iscis-config detach -h to display available arguments.

    sudo oci-iscsi-config detach -h
  2. Use the oci-iscsi-config show --details --output-mode=text command to show the full IQN of the block volumes.

    sudo oci-iscsi-config show --details --output-mode=text

    Note: in this scenario, the attached block volumes do not have any mounted file systems. You must unmount all file systems before you can detach block volumes.

  3. Use the oci-iscsi-config detach command to detach a volume from your instance.

    sudo oci-iscsi-config detach -I <IQN_of_Attached_Block_Volume>
  4. Rerun the oci-iscsi-config show --details --output-mode=text and verify the volume is no longer attached.

    sudo oci-iscsi-config show --details --output-mode=text
  5. From the hamburger menu in the web console, go to Storage > Block Volumes and select it.

    blk storage

    The block volume is still available in the compartment.

Destroy a Block Volume

To destroy a block volume, you must first detach it, and then run the oci-iscsi-config destroy command to remove it from the compartment.

  1. Run the command oci-iscsi-config -s to display details on volumes in your compartment.

    sudo oci-iscsi-config -s 

    Note the volume's IQN and OCID.

  2. Run the oci-iscsi-config destroy without any arguments.

    sudo oci-iscsi-config destroy

    Note: that the -O argument is the only valid option to use.

  3. Use the oci-iscsi-config destroy -O command adding its OCID to the argument. Enter y when prompted.

    sudo oci-iscsi-config destroy -O <OCID_of_Block_Volume>
  4. Verify that the block volume has been removed from the compartment.

    sudo oci-iscsi-config -s 

    There is only one remaining volume. The web console reports the same.

Additional Lab Instructions

Use these instructions when following this tutorial outside of the free lab environment. For more information on enabling oci-utils, including creating SSH keys and a SDK configuration file, watch the following video on enabling OCI Utilities.

Alternatively, use the instructions provided within the SDK and CLI Configuration File and Required Keys and OCIDs sections of the OCI Documentation.

  1. Use the oci setup config command to create a CLI config file. The command can also create the API key pair (public and private keys) if one does not exist. The keys allow for automatic authentication of SDK CLI calls to the API.

    The information you are prompted for can be found in the web console. The script prompts you for the User OCID, Tenancy OCID, and Region. To locate this information:

    • User OCID - Click Profile icon > User Settings, and then click the OCID Copy link in the User Informaton tab.

      User OCID

    • Tenancy OCID - Click Profile icon > Tenancy, and then click the OCID Copy link in the Tenancy Informaton tab.

      User OCID

    • Region - You can locate your region from the Browser URL.


    • Run the oci setup config command to create the config file.

      oci setup config
      • The following is a sample walkthrough of running the command to create a valid CLI config file:

        Enter a location for your config [/home/oracle/.oci/config]: 
        Enter a user OCID: ocid1.user.oc1..aaaaaaaaiwoyjmqabtl7qln7jrniy5al2v5sliadg5grwvrfzk6mrditsqra
        Enter a tenancy OCID: ocid1.tenancy.oc1..aaaaaaaakhyblglzku4lktefccllqsb37dshizfprljvw5imzq55zppsg2lq
        Enter a region by index or name(e.g.
        1: af-johannesburg-1, 2: ap-chiyoda-1, 3: ap-chuncheon-1, 4: ap-dcc-canberra-1, 5: ap-hyderabad-1,
        6: ap-ibaraki-1, 7: ap-melbourne-1, 8: ap-mumbai-1, 9: ap-osaka-1, 10: ap-seoul-1,
        11: ap-singapore-1, 12: ap-sydney-1, 13: ap-tokyo-1, 14: ca-montreal-1, 15: ca-toronto-1,
        16: eu-amsterdam-1, 17: eu-frankfurt-1, 18: eu-marseille-1, 19: eu-milan-1, 20: eu-stockholm-1,
        21: eu-zurich-1, 22: il-jerusalem-1, 23: me-abudhabi-1, 24: me-dcc-muscat-1, 25: me-dubai-1,
        26: me-jeddah-1, 27: sa-santiago-1, 28: sa-saopaulo-1, 29: sa-vinhedo-1, 30: uk-cardiff-1,
        31: uk-gov-cardiff-1, 32: uk-gov-london-1, 33: uk-london-1, 34: us-ashburn-1, 35: us-gov-ashburn-1,
        36: us-gov-chicago-1, 37: us-gov-phoenix-1, 38: us-langley-1, 39: us-luke-1, 40: us-phoenix-1,
        41: us-sanjose-1): eu-frankfurt-1
        Do you want to generate a new API Signing RSA key pair? (If you decline you will be asked to supply the path to an existing key.) [Y/n]: Y
        Enter a directory for your keys to be created [/home/oracle/.oci]: 
        Enter a name for your key [oci_api_key]: 
        Public key written to: /home/oracle/.oci/oci_api_key_public.pem
        Enter a passphrase for your private key (empty for no passphrase): 
        Private key written to: /home/oracle/.oci/oci_api_key.pem
        Fingerprint: 9f:00:c6:8b:43:fb:87:58:4b:82:9b:0f:98:31:4c:31
        Config written to /home/oracle/.oci/config
            If you haven't already uploaded your API Signing public key through the console, follow the instructions on the page linked below in the section
            'How to upload the public key':
  2. Import the API public key to your Oracle Cloud Infrastructure account. From the web console:

    1. Click Profile Icon > User Settings, and then click the API Keys resources link.


    2. Click Add API Key.

    3. Select either Choose Public Key File or Paste Public Key, and then click Add to upload the key.