Using the Service CLI

The command line interface to the Service Enclave, which we refer to as the Service CLI in the documentation, is available through the Oracle Linux shell on the management nodes. There is no additional installation or configuration required. The CLI provides access to all the functionality of the Service Web UI, as well as several additional operations that do not have a UI equivalent.

This section provides general guidelines for using the Service CLI. The actual commands and their functions are documented throughout the Oracle Private Cloud Appliance Administrator Guide as part of the step-by-step instructions in the chapters that follow.

Accessing the CLI

To access the Service CLI, establish an SSH connection to TCP port 30006 on one of the following nodes and log in as an authorized administrator:

  • On one of the management nodes.

    $ ssh admin@pcamn02 -p 30006
Password authentication
Password:
PCA-ADMIN>

  • On the Private Cloud Appliance. 

    $ ssh admin@admin.pca_hostname.example.com -p 30006

After successful authentication, you are in an interactive, closed shell environment where you perform administrative operations by entering commands at the PCA-ADMIN> prompt.

To terminate your CLI session, enter the exit command.

Command syntax and completion functions are described in the following sections.

Command Syntax

In general, commands entered in the Service CLI have the following syntax: 

PCA-ADMIN> command objectType <attributes> [options]

where:

  • command is the command type to be initiated, for example: list or create.

  • objectType is the target component or process affected by the command, for example: list ComputeNode or create Tenant.

  • attributes are properties used to identify a specific object of the selected type to which the command must be applied, for example: show ManagementNode name=pcamn02.

  • options are additional parameters that may be provided to affect the behavior of the command.

    For example, you can add sorting and filtering options to the list command and select which data columns (fields) to display: list RackUnit fields ipAddress,name,rackElevation,serialNumber,firmwareVersion where state eq running.

The main elements of a command are separated by a space. Attributes are specified as "type=value". Lists are entered as a comma-separated series of values (such as fields ipAddress,name,rackElevation,serialNumber,firmwareVersion).

Help and Command Completion

The Service CLI includes a help command. It shows how the most common types of commands are used, which helps you get familiar with the basics of the CLI. 

PCA-ADMIN> help
For Most Object Types:
    create <objectType> [(attribute1)="value1"] ... [on <objectType> <instance>]
    delete <objectType> <instance>
    edit <objectType> <instance>  (attribute1)="value1" ...
    list <objectType> [fields (attribute1,attribute2)]where [(filterableAttribute1)  \
         <filterComparator> "value1" [AND|OR] [(filterableAttribute2) <filterComparator> "value2"
    show <objectType> <instance>
For Most Object Types with Children:
    add <objectType> <instance> to <objectType> <instance>
    remove <objectType> <instance> from <objectType> <instance>
Other Commands:
    exit
    showallcustomcmds
    showcustomcmds <objectType>
    showobjtypes

The easiest way to learn which commands and object types are available, is to use the question mark ("?"). After logging in, you start by entering "?" at the CLI prompt, in order to display the set of base commands. 

PCA-ADMIN> ?
           add
           clear
           count
           create
           delete
           edit
           [...]

You can drill down into the commands, object types and other elements by adding the "?" to see the available parameters at that cursor position.

Note:

Mind the position of the question mark: it is separated from the command by a space. If you omit the space, the CLI displays the parameters allowed at the level of that command, instead of the parameters that may follow after the command.

For example, if you want to see which object types you can list, type list ? and press Enter. Next, assume that you want to find compute nodes that have not yet been provisioned. To achieve this, you can display a list of compute nodes filtered by their provisioning state. The "?" allows you to navigate through the command parameters, as shown below. Each time you type "?" the CLI displays the parameters you can use at the cursor position. Press the Up arrow key to bring back the part of the command you already typed at the prompt, then add the next part of your command, and type "?" again to display the next set of parameters. When your command is complete, press Enter. 

PCA-ADMIN> list ?
                AuthorizationGroup
                ComputeNode
                Event
                Fault
                [...]
PCA-ADMIN> list ComputeNode ?
                            fields
                            limit
                            orderby
                            where
PCA-ADMIN> list ComputeNode where ?
                                  id
                                  provisioningState
                                  provisioningStateLastChangedTime
                                  provisioningType
                                  faultDomain
                                  [...]
PCA-ADMIN> list ComputeNode where provisioningState ?
                                                    EQ
                                                    NE
                                                    LIKE
                                                    [...]
PCA-ADMIN> list ComputeNode where provisioningState EQ ?
                                                       READYTOPROVISION
                                                       PROVISIONED
PCA-ADMIN> list ComputeNode where provisioningState EQ READYTOPROVISION
Command: list ComputeNode where provisioningState EQ READYTOPROVISION
Status: Success
Time: 2021-06-25 14:04:16,837 UTC
Data:
  id                                     name       provisioningState
  --                                     ----       -----------------  
  bb940637-9825-4f7c-a5f4-1b49bcf6a5c9   pcacn005   Ready To Provision
  76df44a9-6980-4242-a3a2-e1614b3d44d1   pcacn008   Ready To Provision
  8fc0d06f-c64a-40ea-8a20-89680f03eb5e   pcacn011   Ready To Provision

The Service CLI also provides a form of tab completion. When you start to type a command and press the Tab key, the CLI auto-completes the part it can predict. If more than one possible value remains, you should add at least one more letter and press the Tab key again. The following examples illustrate how the CLI performs tab completion.

  • Tab completion with one possible match

    PCA-ADMIN> list Com<Tab>
PCA-ADMIN> list ComputeNode

  • Tab completion with more than one possible match

    PCA-ADMIN> list Ra<Tab>
PCA-ADMIN> list Rack

PCA-ADMIN> list RackU<Tab>
PCA-ADMIN> list RackUnit

Base and Custom Commands

When you enter the help command or type the question mark ("?") at the PCA-ADMIN> prompt, the CLI returns information about its base commands, such as create, edit, add, remove, delete, list, show, and so on. However, there is another set of less commonly used custom commands. You can display them all as a single list, or only those available for a particular object type. You can use the "?" to navigate through the commands. 

PCA-ADMIN> showallcustomcmds
Operation Name: <Related Object(s)>
    -----------------------------------
    asrClientDisable:  ASRPhonehome
    asrClientEnable:  ASRPhonehome
    asrClientRegister:  ASRPhonehome
    [...]
    changeIlomPassword:  ComputeNode, ManagementNode
    changePassword:  ComputeNode, LeafSwitch, ManagementNode, ManagementSwitch, SpineSwitch, User, ZFSAppliance
    clearFirstBootError:  NetworkConfig
    configZFSAdDomain:  ZfsAdDomain
    configZFSAdWorkgroup:  ZfsAdDomain
    createAdminAccount:  
    createUserInGroup:  User
    deletePlatformImage:  PlatformImage
    deprovision:  ComputeNode
    disableVmHighAvailability:  PcaSystem
    drAddComputeInstance:  ComputeInstance
    drAddSiteMapping:  DrSiteMapping
    drConfigCleanupPrimary:  DrConfig
    [...]
    maintenanceLock:  ComputeNode
    maintenanceUnlock:  ComputeNode
    migrateVm:  ComputeNode
    patchCN:  PatchRequest
    patchEtcd:  PatchRequest
    patchHost:  PatchRequest
    patchIlom:  PatchRequest
    patchKubernetes:  PatchRequest
    patchMySQL:  PatchRequest
    patchOCIImages:  PatchRequest
    patchPlatform:  PatchRequest
    patchSwitch:  PatchRequest
    patchVault:  PatchRequest
    patchZfssa:  PatchRequest
    [...]
    start:  CnUpdateManager, ComputeNode, Day0NetworkConfigManager, FaultManager, PurgeManager, ZfsPoolManager
    stop:  CnUpdateManager, ComputeNode, Day0NetworkConfigManager, FaultManager, PurgeManager, ZfsPoolManager
    syncHardwareData:  
    syncUpstreamUlnMirror:  PatchRequest
    systemStateLock:  PcaSystem
    systemStateUnlock:  PcaSystem
    updateSauronCredentials:  
    upgradeCN:  UpgradeRequest
    upgradeEtcd:  UpgradeRequest
    upgradeFullMN:  UpgradeRequest
    upgradeHost:  UpgradeRequest
    upgradeIlom:  UpgradeRequest
    upgradeKubernetes:  UpgradeRequest
    upgradeMySQL:  UpgradeRequest
    upgradePlatform:  UpgradeRequest
    upgradePreConfig:  UpgradeRequest
    upgradeSwitch:  UpgradeRequest
    upgradeVault:  UpgradeRequest
    upgradeZfssa:  UpgradeRequest

PCA-ADMIN> showcustomcmds ?
                          ASRBundle
                          ASRPhonehome
                          BackupJob
                          CnUpdateManager
                          ComputeInstance
                          ComputeNode
                          Day0NetworkConfigManager
                          DrConfig
                          DrJob
                          DrSiteMapping
                          Event
                          ExadataNetwork
                          FaultDomainInfo
                          FaultManager
                          Job
                          LeafSwitch
                          ManagementNode
                          ManagementSwitch
                          NetworkConfig
                          PatchRequest
                          PcaSystem
                          PlatformImage
                          PurgeManager
                          SpineSwitch
                          UpgradeJob
                          UpgradeJobList
                          UpgradeRequest
                          User
                          Vcn
                          ZfsAdDomain
                          ZFSAppliance
                          ZfsPoolManager

PCA-ADMIN> showcustomcmds ComputeNode
    provisioningLock
    provisioningUnlock
    maintenanceLock
    maintenanceUnlock
    provision
    deprovision
    migrateVm
    reset
    start
    stop
    changePassword
    changeIlomPassword
    getRunningInstances
    getRunningInstancesCount