Oracle Cloud Infrastructure Documentation

Configuration

You can use these optional configurations to extend CLI functionality. The CLI supports using a file for CLI-specific configurations. You can:

  • Specify a default profile.
  • Set default values for command options so you don't have to type them into the command line.
  • Define aliases for commands. For example, using "ls" as an alias for list.
  • Define aliases for options. For example, using "--ad" as an alias for --availability-domain.
  • Define named queries that are passed to the --query option instead of typing a JMESPath expression on the command line.

The default location and file name is ~/.oci/oci_cli_rc. You can also explicitly specify this file with the --cli-rc-file option or by with the legacy --defaults-file option. For example:

# Uses the file from ~/.oci/oci_cli_rc
oci os bucket list
			
# Uses a custom file
oci os bucket list --cli-rc-file path/to/my/cli/rc/file

To set up an oci-cli-rc file, run the following command.


oci setup oci-cli-rc --file path/to/target/file

This command creates the file you specify that includes examples of default command aliases, parameter aliases, and named queries.

Specifying a Default Profile

Specify a default profile in the OCI_CLI_SETTINGS section of the CLI configuration file. The next example shows how to specify a default profile named IAD. The CLI looks for a profile named IAD in your ~/.oci/config file, or any other file that you specify using the --config-file option.

[OCI_CLI_SETTINGS]
default_profile=IAD

You can also specify a default value for the --profile option using the OCI_CLI_PROFILE environment variable.

If a default profile value has been specified in multiple locations, the order of precedence is:

  1. The value specified in the --profile option.
  2. The value specified in the OCI_CLI_PROFILE environment variable.
  3. The value specified in the default_profile field in the OCI_CLI_SETTINGS section of the CLI configuration file.

Specifying Default Values

The CLI supports using a default values file so that you don't have to keep typing them into the command line. For example, instead of typing in a --compartment-id on each launch instance command or having to keep specifying the --namespace when using Object Storage commands. You can put this information in a default values file.

Default values can be applied at different levels, from general to specific:

  • Globally, across all the CLI commands.
  • To a particular service, such as Compute or Object Storage.
  • To a specific group, such as commands related to exporting images.
  • To a specific command.

Default values are treated hierarchically, with specific values having a higher order of precedence than general values. For example, if there is a globally defined value for compartment-id and a specific compartment-id defined for the compute instance launch command, the CLI uses the value for the compute instance launch instead of the global default.

Default Values File Name and Location

When you start the CLI, the program looks for the default values file in ~/.oci/oci_cli_rc. You can also specify a different file and location by using the --cli-rc-file option, as illustrated by the following:

# Uses the default values file from ~/.oci/oci_cli_rc
oci os bucket list
					
# Uses a custom default values file
oci os bucket list --cli-rc-file path/to/my/cli/custom-oci-cli-rc-file

Command Value Priority

If a value is provided on the command line also exists in --cli-rc-file, the value from the command line has priority. For a command with options that take multiple values, the values are taken entirely from the command line or from --cli-rc-file. The 2 sources aren't merged.

Defaults Value File Syntax

The --cli-rc-file file can be divided into different sections with one or more keys per section.

Sections

In the next example, the file has two sections, with a key in each section. To specify which section to use, you use the --profile option in the CLI.

[DEFAULT]
compartment-id = ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa
[ANOTHER_SECTION]
compartment-id = ocid1.compartment.oc1..aaaaaaaal3gzieyqdrggnx7xil26astxxhqol2pgjjdlieqeyg35nz5znhwa

Keys

Keys are named after command line options, but do not use a leading double hyphen (--). For example, the key for --image-id is image-id. You can specify keys for single values, multiple values, and flags.

  • Keys for Single Values. The next example shows how to specify key values at different levels, and with different scope.

    [DEFAULT]
    # Defines a global default for bucket-name
    bucket-name = my-global-default-bucket-name
    
    # Defines a default for bucket-name, which applies to all 'compute' commands
    compute.bucket-name = bucket-name-for-image-import-export
    				
    # Defines a default for bucket-name, which applies to all 'os object' commands (e.g., os object get)
    os.object.bucket-name = bucket-name-for-object-commands
    
    # Defines a default for bucket-name, for the 'os object multipart list' command
    os.object.multipart.list.bucket-name = bucket-name-for-multipart-list
  • Keys for Multiple Values. Some options, such as --include and --exclude on the oci os object bulk-upload command can be specified more than once. For example:

    oci os object bulk-upload -ns my-namespace -bn my-bucket --src-dir my-directory --include *.txt --include *.png

    The next example shows how you would enter the --include values in the --cli-rc-file file

    [DEFAULT]
    os.object.bulk-upload.include =
    			*.txt
    			*.png

    In the previous example, one value is given for each line and each line must be indented underneath its key. You can use tabs or spaces and the amount of indentation doesn't matter. You can also put a value on the same line as the key, add more values on the following lines, and use a path statement for a value. For example:

    [DEFAULT]
    os.object.bulk-upload.include = *.pdf
    			*.txt
    			*.png
    			my-subfolder/*.tiff
  • Keys for Flags. Some command options are flags, like --force, which uses a Boolean value. To set a flag for the --force option, use the following command.

    os.object.delete.force=true

Specifying Command Aliases

Specify named queries in the OCI_CLI_COMMAND_ALIASES section of the CLI configuration file. There are two types of aliases, global aliases and command sequence aliases. The following example shows each type of alias.

[OCI_CLI_COMMAND_ALIASES]
# This is a global alias that lets you use "ls" instead of "list" for any list command in the CLI.
#
ls = list

# Command examples:
# oci os object ls or oci os compute ls

# This is a command sequence alias that lets you use "oci os object rm" instead of "oci os 
# object delete". 
# <alias> = <dot-separated sequence of groups and sub-groups>.<command or group to alias>
# 
rm = os.object.delete					

# Command example:
# <alias> = rm, <sequence of groups and sub-groups> = os object, <command or group to alias> = delete	 								

If you want to define default values for options in your CLI configuration file, you can use the alias names you have defined. For example, if you have -ls as an alias for --list, you can define a default for an availability domain when listing instances by using the following command.

[DEFAULT]
compute.instance.ls.compartment-id=ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa

Specifying Option Aliases

Specify option aliases in the OCI_CLI_PARAM_ALIASES section of the CLI configuration file. Option aliases are applied globally. The following example shows some aliases for command options.


[OCI_CLI_PARAM_ALIASES]
# Option aliases either start with a double hyphen (--) or are a single hyphen (-) followed by a # single letter. For example: --example-alias, -e
#
--ad = --availability-domain
--dn = --display-name
--egress-rules = --egress-security-rules
--ingress-rules = --ingress-security-rules

If you want to define default values for options in your CLI configuration file, you can use the alias names you have defined. For example, if you have -ad as an alias for --availability-domain, you can define a default for an availability domain when listing instances by using the following command.

[DEFAULT]
compute.instance.list.ad=xyx:PHX-AD-1

Specifying Named Queries

If you use the --query parameter to filter or manipulate output, you can define named queries instead of using a JMESPath expression on the command line.

Specify named queries in the OCI_CLI_CANNED_QUERIES section of the CLI configuration file.

Examples of Named Queries

Enabling Auto-complete

If you used the CLI installer, you don't have to configure auto-complete because it's enabled automatically.

To enable auto-complete (tab completion) for a manual CLI installation, run the following command.

oci setup autocomplete

To enable auto-complete on a session by session basis, run the following command.

eval "$(_OCI_COMPLETE=source oci)"
Note

Support for Auto-complete on Windows

Auto-complete on Windows is only supported if you're using PowerShell. A script runs to enable this feature. However, you must change the PowerShell execution policy to RemoteSigned. To configure this policy, run the following command at the PowerShell command line.

Set-ExecutionPolicy RemoteSigned

Using FIPS-validated Libraries

The CLI can be configured to use FIPS-validated libraries on Linux. The CLI is built on the Python SDK and leverages operating system level cryptographic libraries.

Configuring the Environment

  1. Verify the installed version of OpenSSL is FIPS-compliant. Run the following command:
  2. openssl version

    If "fips" is not part of the version name, you should upgrade OpenSSL to a FIPS-compliant version. You can download the latest versions of OpenSSL at: https://www.openssl.org/source/

  3. Determine the location of the FIPS-compliant version of libcrypto:
  4. ls -l /usr/lib64/libcrypto*
  5. Set the environment variable OCI_CLI_FIPS_LIBCRYPTO_FILE to the location of libcrypto:
  6. export OCI_CLI_FIPS_LIBCRYPTO_FILE=</path/to/libcrypto.x.x.x>

    If you do not want to run this command at the start of every session, you can add it to your.bashrc or .bash_profile file.

    You can confirm that the environment variable is set properly with this command:

    set | grep OCI_CLI_FIPS_LIBCRYPTO_FILE

You can now proceed to the standard installation process outlined in Quickstart

Verifying the Configuration

To verify that the CLI is using the library that you specified during Configuring the Environment, execute the following commands in Python. Be sure to do so in the same environment that the CLI uses.

import ssl
ssl.FIPS_mode()

This should return 1, indicating that SSL is using the library specified by the OCI_CLI_FIPS_LIBCRYPTO_FILE environment variable.