1. Maintenance Guide
  2. Using the exadcli Utility

11 Using the exadcli Utility

The exadcli utility facilitates centralized management across an Oracle Exadata system by orchestrating ExaCLI commands.

exadcli runs the commands on a set of remote nodes and returns the output to the centralized management location where the exadcli utility was run.

  • exadcli Command Reference
    The exadcli utility runs commands on multiple remote nodes in parallel threads.
  • Using exadcli for the First Time
    This is a multi-step example that demonstrates how to configure your Oracle Exadata Database Machine to use exadcli.
  • exadcli Examples
    These examples show how use ExaCLI after the users have been created and granted the necessary privileges.

11.1 exadcli Command Reference

The exadcli utility runs commands on multiple remote nodes in parallel threads.

Overview

exadcli enables you to issue an ExaCLI command to be run on multiple remote nodes. Remote nodes are referenced by their host name or IP address. Unlike dcli, exadcli can only run ExaCLI commands. Other commands, such as shell commands, cannot be performed using exadcli.

The exadcli utility is installed when the database node is imaged. exadcli does not support an interactive session with a remote application on the remote node.

exadcli connects in parallel to the remote nodes and authenticates the user. Command output (stdout and stderr) is collected and displayed after the command finishes on the specified remote nodes.

exadcli runs ExaCLI in a “no-prompt” mode. This means that if user interaction is needed (for example, if you need to enter a password or if you need to verify that the certificate from a remote node is valid), then exadcli exits with an error. The command exadcli --authenticate can be used to log into every cell or database node using the same password. The authentication token is stored in the cookie jar and future exadcli sessions will not need to enter an password.

Prerequisites

  • To use exadcli, you have to set up users and roles on all the remote nodes.

  • Before using exadcli, you must use ExaCLI to accept the identity certificate of cell or database nodes. This needs to be done only once per cell (unless the cell is upgraded or a new certificate is uploaded to the remote database or cell node), for example:

    Note:

    If you are using Oracle Exadata System Software release 19.3 or later, then enter y or n followed by pressing Enter when prompted. 
    $ exacli -l dbnodeadministrator -c dbnode01 --cookie-jar 
No cookies found for dbnodeadministrator@dbnode01. 
Password: ************ 
EXA-30016: This connection is not secure. You have asked ExaCLI to connect to cell dbnode01:7879 securely. The identity of dbnode01:7879 cannot be verified. 
Got certificate from server: 
C=US,ST=California,L=Redwood City,O=Oracle Corporation,OU=Oracle Exadata,CN=localhost 
Do you want to accept and store this certificate? (Press y/n) y 
exacli dbnodeadministrator@dbnode01:7879> exit

    You must accept the certificate on every cell or database node. See Using exadcli for the First Time for a complete example of configuring access prior to using exadcli.

  • Java version 1.8 or later

    You can determine the version of Java by running the java -version command. In addition, the JAVA_HOME environment variable must be set to point to the installation directory of the proper version of Java.

File Path

/usr/local/sbin/exadcli

Syntax

You run ExaCLI from the operating system command line.

exadcli options command[; command]

Options

Option Description 
-c host [,host] 

--connect=host [,host]

Specifies a comma-delimited list of target remote nodes to which ExaCLI commands are sent.

 
-g filename

--group-file=filename

Specifies a file containing a list of target remote nodes to which commands are sent. The remote nodes can be identified by host names or IP addresses.

 
-l username

--login-user=username

Specifies the user to log in as on the remote nodes. This is a DBMCLI or CellCLI user, not an operating system user.

 
-t

--list

Displays the target remote nodes that are named with the -c option or in the group file identified by the -g option. 

-x filename

--exec-file=filename

Specifies the command file to run on the remote nodes. The command file contains a list of ExaCLI commands.

Note: exadcli does not have an interactive mode. You can specify the commands to run using the –x option, or you can specify the commands at the end of the command-line. 

--authenticate

Prompts for the user password. The user will be authorized on all remote nodes using the password and the authorization is stored in the default cookie jar.

 
--max-lines=maxlines

Limits the maximum output lines from a remote node. Default is 100,000 lines.

 
--xml

Causes the output to be displayed in XML format. This option is passed through to ExaCLI.

 
-h

--help

Displays the help message.

 
command

or

'command[; command]'

Specifies ExaCLI commands to run on the remote nodes. To specify multiple commands, enclose the command string in single quotes and separate each command with the semicolon character ;.

Note: exadcli does not have an interactive mode. You can specify the commands to run using the –x option, or you can specify the commands at the end of the command-line. 

--cookie-jar [filename]

Specifies the cookie jar file. This option is passed through to ExaCLI.

Note: This option is deprecated. Now, exadcli always uses the cookie jar.

Usage Notes

  • Return values from exadcli are:

    • 0: Commands were run successfully on all the remote nodes.
    • 1: One or more remote nodes could not be reached or a remote command returned a non-zero status.
    • 2: A local error prevented the command.

  • If any remote nodes are down or do not respond, then a message is written to stderr listing the unresponsive remote nodes. The operation continues on other remote nodes, and the return code after completion is 1.

  • If you restart the Management Server (MS), then you must re-authenticate exadcli using the exadcli --authenticate command. 

    $ exadcli -c dbnode01,dbnode02,dbnode03 -l dbnodeadministrator --authenticate

Related Topics

Parent topic: Using the exadcli Utility

11.2 Using exadcli for the First Time

This is a multi-step example that demonstrates how to configure your Oracle Exadata Database Machine to use exadcli.

This example shows how to configure access to cell nodes. The same procedure with minor changes can be used for configuring access to database nodes.

  1. Use CellCLI to create the celladministrator user on each node and grant privileges to those users.

    Connect to each remote node and use CellCLI to create the user and assign privileges. In this example, the user is granted all privileges, but you can grant a limited set of privileges that contains only the privileges needed to run the exadcli commands. 

    CellCLI> CREATE ROLE administrator 

CellCLI> GRANT PRIVILEGE ALL ACTIONS ON ALL OBJECTS ALL ATTRIBUTES - 
> WITH ALL OPTIONS TO ROLE administrator 

CellCLI> CREATE USER celladministrator password=* 

CellCLI> GRANT ROLE administrator TO USER celladministrator
  2. On the node where you plan to run exadcli, use ExaCLI to accept the security certificate for each node.

    Note:

    If you are using Oracle Exadata System Software release 19.3 or later, then enter y or n followed by pressing Enter when prompted. 
    exacli -l celladministrator -c cell01 --cookie-jar

No cookies found for celladministrator@cell01.
Password: ********
EXA-30016: This connection is not secure. You have asked ExaCLI to connect to 
cell cell01 securely. The identity of cell01 cannot be verified.
Got certificate from server:
C=US,ST=California,L=Redwood City,O=Oracle Corporation,OU=Oracle Exadata,
CN=localhost
Do you want to accept and store this certificate? (Press y/n)
 y
exacli celladministrator@cell01> exit

    Repeat this step for both cell02 and cell03.

  3. Use exadcli to connect to cells cell01, cell02, and cell03 as the celladministrator user with the --authenticate option.
    $ exadcli -c cell01,cell02,cell03 -l celladministrator --authenticate
Password:
cell01: Password: ********
cell01: exacli celladministrator@cell01:7879>
cell02: Password: ********
cell02: exacli celladministrator@cell02:7879>
cell03: Password: ********
cell03: exacli celladministrator@cell03:7879>

    exadcli stores the credentials in ~/.exacli/cookiejar so that further exadcli commands to the same cells will not prompt for a password.

  4. Optional: Create a mycells file as the celladministrator user that contains a list of the nodes on which you want to run the commands.
    $ cat mycells
cell01
cell02
cell03
  5. Use exadcli to run a command using the mycells file.
    $ exadcli -g mycells -l celladministrator list cell

cell01: cell01   online
cell02: cell02   online
cell03: cell03   online

    If you did not create the mycells file, you can instead specify the remote nodes on the command line using the -c option. 

    $ exadcli -c cell01,cell02,cell03 -l celladministrator list cell
 detail

Parent topic: Using the exadcli Utility

11.3 exadcli Examples

These examples show how use ExaCLI after the users have been created and granted the necessary privileges.

See Creating Users for Use with ExaCLI for examples of creating users and assigning privileges to them.

For an example of configuring exadcli access to storage cells for the first time, see Using exadcli for the First Time.

Example 11-1 Using the AUTHENTICATE Option to Re-Authenticate exadcli

Connect to nodes dbnode01,dbnode02,dbnode03 as the dbnodeadministrator user and store the credentials in ~/.exacli/cookiejar so that further exadcli commands to the same nodes do not prompt for a password. 

$ exadcli -c dbnode01,dbnode02,dbnode03 -l dbnodeadministrator --authenticate

Example 11-2 Using exadcli to View the DBSERVER Information

You can use exadcli to run a command on multiple node, such as listing DBSERVER information. 

$ exadcli -c dbnode01,dbnode02,dbnode03 -l dbnodeadministrator list dbserver

Example 11-3 Using exadcli to View the Detailed Cell Information

Using exadcli you can retrieved the detailed cell information for multiple nodes with a single command. 

$ exadcli -c cell01,cell02,cell03 -l celladministrator list cell detail

Example 11-4 Using a Node List and Command File with exadcli

You can use input files with exadcli to avoid repeatedly entering the list of nodes to access, or to provide a list of ExaCLI commands to run. This example assumes you have created a text file named mycells or mydbnodes that contains the host names of the remote nodes. This example also uses an input files named cellcommands.txt and dbcommands.txt. 

$ cat cellcommands.txt
list cell
list griddisk attributes name, size order by size,name desc
list celldisk where status!=normal attributes name, status

$ exadcli -g mycells -l celladministrator -x cellcommands.txt
cell01: cell01   online
cell01: DBFS_DG_CD_11_cell01     29.125G
cell01: DBFS_DG_CD_10_cell01     29.125G
cell01: DBFS_DG_CD_09_cell01     29.125G
...
cell02: cell02   online
cell02: DBFS_DG_CD_11_cell02     29.125G
cell02: DBFS_DG_CD_10_cell02     29.125G
cell02: DBFS_DG_CD_09_cell02     29.125G
...
cell03: cell03   online
cell03: DBFS_DG_CD_11_cell03     29.125G
cell03: DBFS_DG_CD_10_cell03     29.125G
cell03: DBFS_DG_CD_09_cell03     29.125G

$ cat dbcommands.txt
list dbserver
list metriccurrent where objectType='IBPORT'
list physicaldisk

$ exadcli -g mydbnodes -l dbnodeadministrator -x dbcommands.txt
dbnode01: dbnode01         online
dbnode01: N_IB_MB_RCV_SEC     HCA-1:1         0.061 MB/sec
dbnode01: N_IB_MB_RCV_SEC     HCA-1:2         0.001 MB/sec
...
dbnode01: N_IB_UTIL_TRANS     HCA-4:1         0.0 %
dbnode01: N_IB_UTIL_TRANS     HCA-4:2         0.0 %
dbnode01: 39:0        71HKPE  normal
dbnode01: 39:1        70CFBP  normal
...
dbnode02: dbnode02         online
dbnode02: N_IB_MB_RCV_SEC     HCA-1:1         0.023 MB/sec
dbnode02: N_IB_MB_RCV_SEC     HCA-1:2         0.036 MB/sec
...

Related Topics

Parent topic: Using the exadcli Utility