3.1 CLI Usage

The Oracle PCA command line interface is triggered by running the pca-admin command. It can run either in interactive mode (see Section 3.1.1, “Interactive Mode”) or in single-command mode (see Section 3.1.2, “Single-command Mode”) depending on whether you provide the syntax to run a particular CLI command when you invoke the command line interpreter.

The syntax when using the CLI is as follows:

PCA> Command Command_Target <Arguments> Options

where:

  • Command is the command type that should be initiated. For example list;

  • Command_Target is the Oracle PCA component or process that should be affected by the command. For example management-node, compute-node, task etc;

  • <Arguments> consist of positioning arguments related to the command target. For instance, when performing a reprovisioning action against a compute node, you should provide the specific compute node that should be affected as an argument for this command. For example: reprovision compute-node ovcacn11r1;

  • Options consist of options that may be provided as additional parameters to the command to affect its behavior. For instance, the list command provides various sorting and filtering options that can be appended to the command syntax to control how output is returned. For example: list compute-node --filter-column ILOM_State --filter dead. See Section 3.1.3, “Controlling CLI Output” for more information on many of these options.

The CLI includes its own internal help that can assist you with understanding the commands, command targets, arguments and options available. See Section 3.1.4, “Internal CLI Help” for more information on how to use this help system. When used in interactive mode, the CLI also provides tab completion to assist you with the correct construction of a command. See Section 3.1.1.1, “Tab Completion” for more information on this.

3.1.1 Interactive Mode

The Oracle PCA command line interface (CLI) provides an interactive shell that can be used for user-friendly command line interactions. This shell provides a closed environment where users are able to enter commands specific to the management of the Oracle PCA. By using the CLI in interactive mode, the user can avail of features like tab completion to easily complete commands correctly. By default, running the pca-admin command without providing any additional parameters causes the CLI interpreter to run in interactive mode.

It is possible to identify that you are in a CLI shell running in interactive mode as the shell prompt is indicated by PCA>.

Example 3.1 An example of interactive mode usage of the CLI

# pca-admin 
Welcome to PCA! Release: 2.0.5
PCA>         
PCA> list management-node   

Management_Node IP_Address    Node_State    ILOM_MAC             ILOM_State    Master 
--------------- ----------    ----------    --------             ----------    ------ 
ovcamn06r1      192.168.4.4   RUNNING       00:10:e0:2e:7c:53    running             
ovcamn05r1      192.168.4.3   RUNNING       00:10:e0:31:93:6f    running       Yes   
----------------
2 rows displayed

Status: Success
PCA> exit
# 

To exit from the CLI when it is in interactive mode, you can use either the quit or exit command, or alternatively use the Ctrl+D key combination.

3.1.1.1 Tab Completion

The CLI supports tab-completion when in interactive mode. This means that pressing the tab key while entering a command can either complete the command on your behalf, or can indicate options and possible values that can be entered to complete a command. Usually you must press the tab key at least twice to effect tab-completion.

Tab-completion is configured to work at all levels within the CLI and is context sensitive. This means that you can press the tab key to complete or prompt for commands, command targets, options, and for certain option values. For instance, pressing the tab key twice at a blank prompt within the CLI automatically lists all possible commands, while pressing the tab key after typing the first letter or few letters of a command automatically completes the command for you. Once a command is specified, pressing the tab key indicates command targets. If you have specified a command target, pressing the tab key indicates other options available for the command sequence. If you press the tab key after specifying a command option that requires an option value, such as the --filter-column option, the CLI attempts to provide you with the values that can be used with that option.

Example 3.2 Examples showing tab-completion

PCA> <tab>
EOF          backup       delete       diagnose     exit         help
list         q            quit         reprovision  rerun        set
shell        show         start        stop
        
PCA> list <tab>
compute-node     config-error     management-node  network-cloud
opus-port        storage-cloud    task             wwpn-info

PCA> list m<tab>anagement-node
        

The <tab> indicates where the user pressed the tab key while in an interactive CLI session. In the final example, the command target is automatically completed by the CLI.


3.1.1.2 Running Shell Commands

It is possible to run standard shell commands while you are in the CLI interpreter shell. These can be run by either preceding them with the shell command or by using the ! operator as a shortcut to indicate that the command that follows is a standard shell command. For example:

PCA> shell date
Wed Jun 24 04:54:54 PDT 2015
PCA> !uptime > /tmp/uptime-today
PCA> !rm /tmp/uptime-today

3.1.2 Single-command Mode

The CLI supports 'single-command mode', which allows you to execute a single command from the shell via the CLI and to obtain the output before the CLI exits back to the shell. This is particularly useful when writing scripts that may interact with the CLI, particularly if used in conjunction with the CLI's JSON output mode described in Section 3.1.3.1, “JSON Output”.

To run the CLI in single-command mode, simply include the full command syntax that you wish to execute as parameters to the pca-admin command.

An example of single command mode is provided below:

# pca-admin list compute-node

Compute_Node    IP_Address      Node_State      ILOM_MAC             ILOM_State
------------    ----------      ----------      --------             ----------
ovcacn08r1      192.168.4.9     RUNNING         00:10:e0:65:2f:b7    running
ovcacn28r1      192.168.4.10    RUNNING         00:10:e0:62:31:81    running
ovcacn10r1      192.168.4.7     RUNNING         00:10:e0:65:2f:cf    running
ovcacn30r1      192.168.4.8     RUNNING         00:10:e0:40:cb:59    running
ovcacn07r1      192.168.4.11    RUNNING         00:10:e0:62:ca:09    running
ovcacn26r1      192.168.4.12    RUNNING         00:10:e0:65:30:f5    running
ovcacn29r1      192.168.4.5     RUNNING         00:10:e0:31:49:1d    running
ovcacn09r1      192.168.4.6     RUNNING         00:10:e0:65:2f:3f    running
----------------
8 rows displayed
Status: Success

#

3.1.3 Controlling CLI Output

The CLI provides options to control how output is returned in responses to the various CLI commands that are available. These are provided as additional options as the final portion of the syntax for a CLI command. Many of these options can make it easier to identify particular items of interest through sorting and filtering, or can be particularly useful when scripting solutions as they help to provide output that is more easily parsed.

3.1.3.1 JSON Output

JSON format is a commonly used format to represent data objects in a way that is easy to machine-parse but is equally easy for a user to read. Although JSON was originally developed as a way to represent JavaScript objects, parsers are available for a wide number of programming languages, making it an ideal output format for the CLI if you are scripting a custom solution that may need to interface directly with the CLI.

The CLI returns its output for any command in JSON format if the --json option is specified when a command is run. Typically this option may be used when running the CLI in single-command mode. An example follows:

# pca-admin list compute-node --json
{
    "00:10:e0:65:2f:b2": {
        "ip": "192.168.4.9",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn08r1",
        "ilom_mac": "00:10:e0:65:2f:b7"
    },
    "00:10:e0:62:31:7c": {
        "ip": "192.168.4.10",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn28r1",
        "ilom_mac": "00:10:e0:62:31:81"
    },
    "00:10:e0:65:2f:ca": {
        "ip": "192.168.4.7",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn10r1",
        "ilom_mac": "00:10:e0:65:2f:cf"
    },
    "00:10:e0:40:cb:54": {
        "ip": "192.168.4.8",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn30r1",
        "ilom_mac": "00:10:e0:40:cb:59"
    },
    "00:10:e0:62:ca:04": {
        "ip": "192.168.4.11",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn07r1",
        "ilom_mac": "00:10:e0:62:ca:09"
    },
    "00:10:e0:65:30:f0": {
        "ip": "192.168.4.12",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn26r1",
        "ilom_mac": "00:10:e0:65:30:f5"
    },
    "00:10:e0:31:49:18": {
        "ip": "192.168.4.5",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn29r1",
        "ilom_mac": "00:10:e0:31:49:1d"
    },
    "00:10:e0:65:2f:3a": {
        "ip": "192.168.4.6",
        "state": "RUNNING",
        "ilom_state": "running",
        "name": "ovcacn09r1",
        "ilom_mac": "00:10:e0:65:2f:3f"
    }
}

In some cases the JSON output may contain more information than is displayed in the tabulated output that is usually shown in the CLI when the --json option is not used. Furthermore, the keys used in the JSON output may not map identically to the table column names that are presented in the tabulated output.

Sorting and filtering options are currently not supported in conjunction with JSON output, since these facilities can usually be implemented on the side of the parser.

3.1.3.2 Sorting

Typically, when using the list command, you may wish to sort information in a way that makes it easier to view items of particular interest. This is achieved using the --sorted-by and --sorted-order options in conjunction with the command. When using the --sorted-by option, you must specify the column name against which the sort should be applied. You can use the --sorted-order option to control the direction of the sort. This option should be followed either with ASC for an ascending sort, or DESC for a descending sort. If this option is not specified, the default sort order is ascending.

For example, to sort a view of compute nodes based on the status of the ILOM for each compute node, you may do the following:

PCA> list compute-node --sorted-by ILOM_State --sorted-order ASC
 
Compute_Node    IP_Address      Node_State      ILOM_MAC             ILOM_State
------------    ----------      ----------      --------             ----------
ovcacn08r1      192.168.4.9     RUNNING         00:10:e0:65:2f:b7    dead
ovcacn28r1      192.168.4.10    RUNNING         00:10:e0:62:31:81    initializing_stage_wait_for_hmp
ovcacn10r1      192.168.4.7     RUNNING         00:10:e0:65:2f:cf    initializing_stage_wait_for_hmp
ovcacn30r1      192.168.4.8     RUNNING         00:10:e0:40:cb:59    running
ovcacn07r1      192.168.4.11    RUNNING         00:10:e0:62:ca:09    running
ovcacn26r1      192.168.4.12    RUNNING         00:10:e0:65:30:f5    running
ovcacn29r1      192.168.4.5     RUNNING         00:10:e0:31:49:1d    running
ovcacn09r1      192.168.4.6     RUNNING         00:10:e0:65:2f:3f    running
----------------
8 rows displayed

Status: Success

Note that the --sorted-by option is case sensitive, but you can use tab-completion to easily obtain the options for different column names. See Section 3.1.1.1, “Tab Completion” for more information.

3.1.3.3 Filtering

Some tables may contain a large number of rows that you are not interested in, to limit the output to items of particular interest you can use the filtering capabilities that are built into the CLI. Filtering is achieved using a combination of the --filter-column and --filter options. The --filter-column option must be followed by specifying the column name, while the --filter option is followed with the specific text that should be matched to form the filter. The text that should be specified for a --filter must be an exact match. Filtering does not currently support case insensitivity, wildcards, regular expressions or partial matches.

For example, to view only the compute nodes that have an ILOM status equivalent to 'dead', you could use the following filter:

PCA> list compute-node --filter-column ILOM_State --filter dead
 
Compute_Node    IP_Address      Node_State      ILOM_MAC             ILOM_State     
------------    ----------      ----------      --------             ----------     
ovcacn09r1      192.168.4.10    DEAD            00:10:e0:0f:55:cb    dead           
ovcacn11r1      192.168.4.9     DEAD            00:10:e0:0f:57:93    dead           
ovcacn14r1      192.168.4.7     DEAD            00:10:e0:46:9e:45    dead           
ovcacn36r1      192.168.4.11    DEAD            00:10:e0:0f:5a:9f    dead           
----------------
4 rows displayed
 
Status: Success

Note that the --filter-column option is case sensitive, but you can use tab-completion to easily obtain the options for different column names. See Section 3.1.1.1, “Tab Completion” for more information.

3.1.4 Internal CLI Help

The CLI includes its own internal help system. This is triggered by issuing the help command:

PCA> help

Documented commands (type help <topic>):
========================================
backup  diagnose  list         rerun  show   stop
delete  help      reprovision  set    start

Undocumented commands:
======================
EOF  exit  q  quit  shell

The help system displays all of the available commands that are supported by the CLI. These are organized into 'Documented commands' and 'Undocumented commands'. Undocumented commands are usually commands that are not specific to the management of the Oracle PCA, but are mostly discussed within this documentation. Note that more detailed help can be obtained for any documented command by appending the name of the command to the help query. For example, to obtain the help documentation specific to the list command, you can do the following:

PCA> help list

Usage: pca-admin list <Command Target> [OPTS]

Command Targets:
  storage-cloud:        List storage clouds.
  task:                 List task.
  management-node:      List management node.
  opus-port:            List OPUS port.
  config-error:         List configuration errors.
  compute-node:         List computer node.
  network-cloud:        List network clouds.
  wwpn-info:            List wwpn info.

Options:
  --json                Display the output in json format.
  --sorted-by=SORTEDBY  Sorting the table by a column.
  --sorted-order=SORTEDORDER
                        Sorting order.
  --filter-column=FILTERCOLUMN
                        Table column that needs to be filtered.
  --filter=FILTER       filter criterion

You can drill down further into the help system for most commands by also appending the command target onto your help query:

PCA> help reprovision compute-node

  Usage:
  reprovision compute-node <compute node name> [options]

  Example:
  reprovision compute-node ovcacn11r1

  Description:
  Reprovision a compute node.

Finally, if you submit a help query for something that doesn't exist, the help system generates an error and automatically attempts to prompt you with alternative candidates:

PCA> list ta
Status: Failure
Error Message: Error (MISSING_TARGET_000): Missing command target for command: list.
Command targets can be: ['storage-cloud', 'task', 'management-node', 'opus-port',
'config-error', 'compute-node', 'network-cloud', 'wwpn-info'].