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>CommandCommand_Target<Arguments>Options
where:
Commandis the command type that should be initiated. For example list;Command_Targetis the Oracle PCA component or process that should be affected by the command. For examplemanagement-node,compute-node,tasketc;<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-nodeovcacn11r1;Optionsconsist 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-columnILOM_State--filterdead. 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.
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.
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.
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
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 #
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.
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.
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.
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.
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 criterionYou 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'].