The Oracle Private Cloud Appliance command line interface is triggered by running the pca-admin command. It can run either in interactive mode (see Section 4.1.1, “Interactive Mode”) or in single-command mode (see Section 4.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 Private Cloud Appliance 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-columnProvisioning_State--filterdead. See Section 4.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 4.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 4.1.1.1, “Tab Completion” for more information on this.
The Oracle Private Cloud Appliance 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 can enter commands specific to the management of the Oracle Private Cloud Appliance. 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 4.1 An example of interactive mode usage of the CLI
# pca-admin Welcome to PCA! Release: 2.4.1 PCA> list management-node Management_Node IP_Address Provisioning_Status ILOM_MAC Provisioning_State Master --------------- ---------- ------------------- -------- ------------------ ------ ovcamn05r1 192.168.4.3 RUNNING 00:10:e0:e9:1f:c9 running Yes ovcamn06r1 192.168.4.4 RUNNING 00:10:e0:e7:26:ad running None ---------------- 2 rows displayed Status: Success PCA> exit #
To exit from the CLI when it is in interactive mode, you can use either the q, 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, followed by a space, 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 4.2 Examples showing tab-completion
PCA><tab>EOF backup create deprovision exit help q remove rerun shell start update add configure delete diagnose get list quit reprovision set show stop PCA> list<tab>compute-node lock mgmt-switch-port network-port task update-task uplink-port-group config-error management-node network network-switch tenant-group uplink-port PCA> list com<tab>pute-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 5 08:15:56 UTC 2019 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 4.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 Provisioning_Status ILOM_MAC Provisioning_State ------------ ---------- ------------------- -------- ------------------ ovcacn12r1 192.168.4.8 RUNNING 00:10:e0:e5:e6:d3 running ovcacn07r1 192.168.4.7 RUNNING 00:10:e0:e6:8d:0b running ovcacn13r1 192.168.4.11 RUNNING 00:10:e0:e6:f7:f7 running ovcacn14r1 192.168.4.9 RUNNING 00:10:e0:e7:15:eb running ovcacn10r1 192.168.4.12 RUNNING 00:10:e0:e7:13:8d running ovcacn09r1 192.168.4.6 RUNNING 00:10:e0:e6:f8:6f running ovcacn11r1 192.168.4.10 RUNNING 00:10:e0:e6:f9:ef running ---------------- 7 rows displayed #
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:e5:e6:ce": {
"name": "ovcacn12r1",
"ilom_state": "running",
"ip": "192.168.4.8",
"tenant_group_name": "Rack1_ServerPool",
"state": "RUNNING",
"networks": "default_external, default_internal",
"ilom_mac": "00:10:e0:e5:e6:d3"
},
"00:10:e0:e6:8d:06": {
"name": "ovcacn07r1",
"ilom_state": "running",
"ip": "192.168.4.7",
"tenant_group_name": "Rack1_ServerPool",
"state": "RUNNING",
"networks": "default_external, default_internal",
"ilom_mac": "00:10:e0:e6:8d:0b"
},
[...]
"00:10:e0:e6:f9:ea": {
"name": "ovcacn11r1",
"ilom_state": "running",
"ip": "192.168.4.10",
"tenant_group_name": "",
"state": "RUNNING",
"networks": "default_external, default_internal",
"ilom_mac": "00:10:e0:e6:f9:ef"
}
}
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 DES 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 provisioning for each compute node, you may do the following:
PCA> list compute-node --sorted-by Provisioning_State --sorted-order ASC Compute_Node IP_Address Provisioning_Status ILOM_MAC Provisioning_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 you can use tab-completion with the
--sorted-by option to easily obtain the
options for different column names. See
Section 4.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 may
contain wildcard characters. If that is not the case, it must
be an exact match. Filtering does not currently support
regular expressions or partial matches.
For example, to view only the compute nodes that have a Provisioning state equivalent to 'dead', you could use the following filter:
PCA> list compute-node --filter-column Provisioning_State --filter dead Compute_Node IP_Address Provisioning_Status ILOM_MAC Provisioning_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 you can use tab-completion with the
--filter-column option to easily obtain the
options for different column names. See
Section 4.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>): ======================================== add create diagnose list rerun start backup delete get remove set stop configure deprovision help reprovision show update 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 Private Cloud Appliance, 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:
compute-node List computer node.
config-error List configuration errors.
lock List lock.
management-node List management node.
mgmt-switch-port List management switch port.
network List active networks.
network-port List network port.
network-switch List network switch.
task List task.
tenant-group List tenant-group.
update-task List update task.
uplink-port List uplink port.
uplink-port-group List uplink port group.
Options:
--json Display the output in json format.
--less Display output in the less pagination mode.
--more Display output in the more pagination mode.
--tee=OUTPUTFILENAME Export output to a file.
--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: ['update-task', 'uplink-port-group', 'config-error', 'network', 'lock', 'network-port', 'tenant-group', 'network-switch', 'task', 'compute-node', 'uplink-port', 'mgmt-switch-port', 'management-node'].