8 Using the dcli Utility

The dcli utility facilitates centralized management across an Oracle Exadata System Software realm.

dcli automates the execution of CellCLI commands on a set of cells and returns the output to the centralized management location where the dcli utility was run.

8.1 Overview of the dcli Utility

The dcli utility runs commands on multiple cells in parallel threads, but does not support an interactive session with a remote application on a cell.

To use the dcli utility, copy the utility from the bin directory on a cell to a host computer from which central management can be performed. You can issue a command to be run on multiple cells, or use files that can be copied to cells and then run. The cells are referenced by their host name or IP address.

The dcli utility requires Python version 2.3 or later. You can determine the version of Python by running the python -V command. In addition, use of this tool assumes prior setup of SSH user-equivalence to a cell. You can use the dcli utility initially with the -k option to set up SSH user-equivalence to a cell. Also, you can manually set up SSH user-equivalence to cells.

Command output (stdout and stderr) is collected and displayed after the copy and command execution is finished on the specified cells. The dcli options allow command output to be abbreviated to minimize non-error output, such as messages showing normal status.

8.2 dcli Syntax

This topic describes the syntax for the dcli utility.

Syntax

dcli [options] [command]

Command Arguments

  • options: command options
  • command: Any command that can be run from an operating system prompt.

Command Options

Table 8-1 dcli Options

Option Description

-c cells

Specifies a comma-delimited list of target cells to which commands are sent.

-d destfile

Specifies the target destination directory or file on remote cells to be used when copying files or directories using the -f option.

-f file

Specifies the files or file template to be copied to the cells. These files are not run. These files can be script files to be run later. The files are copied to the default home directory of the user on the target cell.

-g groupFile

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

-h, --help

Displays help text and then exits.

--hidestderr

Hide standard error messages (STDERR) for commands run remotely using SSH.

-k

Sets up SSH user-equivalence for the current user to the cells specified with the -c or -g option by appending public key files to the authorized_keys file on cells.

-l userId

Identifies the user to log in as on remote cells. The default is the celladmin user.

-n

Abbreviates nonerror output. Cells that return normal output (return code of 0) only have the cell name listed.

The -n and -r options cannot be used together.

-r regexp

Abbreviates the output lines that match a regular expression. All output lines with that pattern are deleted from output, and the cells names from those output lines are listed on one line.

The -r and -n options cannot be used together.

-s sshOptions

Passes a string of options to SSH.

--scp= scpOptions

Passes a string of options to scp if different from sshoptions.

--serial

Serializes the process over Oracle Exadata Storage Servers.

--showbanner, --sh

Show the banner of the remote node when using SSH.

-t

Displays the target cells that are named with the -c option or in the groupfile identified by the -g option.

--unkey

Drops keys from the target authorized_keys file on Oracle Exadata Storage Servers.

-v

Prints the verbose version of messages to stdout.

--version

Shows the version number of the program and then exits.

--vmstat=VMSTATOPS

Displays view process, virtual memory, disk, trap, and CPU activity information, depending on the switches.

-x execFile

Specifies the command file to be copied and run on the cells. The specified file contains a list of commands. A file with the .scl extension is run by the CellCLI utility. A file with a different extension is run by the operating system shell on the cell. The file is copied to the default home directory of the user on the target cell.

Usage Notes

For commands that contain punctuation that would be interpreted by the local shell, enclose the command in double quotation marks. If the command includes the following characters, then outer quotation marks and escape characters are required:

  • $ (dollar sign)
  • ' (quotation mark)
  • < (less than)
  • > (greater than)
  • ( ) (parentheses)

The backslash (\) is the escape character that allows the characters to be passed to the CellCLI utility without being interpreted by the remote shell.

If the command is complex in terms of punctuation that need escape characters, then it may require that the command be put in a script, and run using the -x option. Within a script, the escape character is not required.

Troubleshooting

If the local dcli process is terminated, then remote commands might continue, but their output and status is unknown.

Return values from the dcli utility are:

  • 0: The file or command was copied, and run successfully on all cells.
  • 1: One or more cells could not be reached or remote execution returned a nonzero status.
  • 2: A local error prevented any command execution.

If any cells are down or do not respond, then a message is written to stderr listing the unresponsive cells. The operations continue on the other cells, and the return code after completion is 1.

8.3 dcli Examples

This section contains examples of the using the dcli utility.

8.3.1 Using dcli to Set up SSH User-equivalence for a Current User

This example shows how to set SSH user-equivalence for a current user using the -k option.

Example 8-1 Setting up SSH User-equivalence for a Current User

$ ./dcli -k -g mycells

The -k option assumes the user has accepted the default key file names for the SSH protocol, version 2. These file names are id_dsa.pub or id_rsa.pub, and are located in the ~/.ssh directory.

You may be prompted to acknowledge cell authenticity, and may be prompted for the remote user password. The -k key exchange is done serially over the cells to prevent the user from getting password prompts from all cells simultaneously. After the -k option is used once, subsequent commands to the same cells do not require the -k option and do not require passwords for that user from the host.

8.3.2 Using dcli with the -n Option

This example shows how to run the CellCLI command ALTER IORMPLAN OBJECTIVE='basic', and abbreviates non-error output.

Example 8-2 Using the -n Option

$ ./dcli -g mycells -l celladmin -n "cellcli -e alter iormplan \
objective=\'basic\'"

The abbreviated output would be similar to the following:

OK: ['abcd2x3']
stsd2s2:
stsd2s2: CELL-02619: Current IORMPLAN state is not 'active'.

8.3.3 Using dcli with the -r Option

This example shows how to run the CellCLI command LIST GRIDDISK, and deletes the lines in the output that contain normal.

The command is run on the target cells listed in the mycells group file.

Example 8-3 Using the -r Option

$ ./dcli -l celladmin -r '.*normal' -g mycells "cellcli -e list celldisk"

The output would be similar to the following:

.*normal: ['stsd2s2', 'abcd2x3']
abcd2x3: CD_06_abcd2x3    importRequired

8.3.4 Using dcli with the -v Option

This example shows how to use the verbose (-v) option with SSH.

Example 8-4 Using the -v Option

$ ./dcli -s "-v" -c mycell date

8.3.5 Using dcli with the -t Option

This example shows how to use the -t option to list target cells.

The -t option should be used with -c or -g option.

Example 8-5 Using the -t Option

$ ./dcli -t -c exa01celadm09 date
Target cells: ['exa01celadm09']
exa01celadm09: Fri Jul 17 15:37:31 PDT 2019

8.3.6 Using dcli with the -f Option

This example shows how to use the -f option.

Example 8-6 Using the -f Option

In this example, a set of files is copied to the storage servers listed in the mycells file.

dcli -g mycells -f '*.bin'

8.3.7 Using dcli with the --vmstat Option

This example shows how to use the --vmstat option of dcli.

Example 8-7 Using the --vmstat Option

$ ./dcli -g 123 -l sage --vmstat="-a 3 5"

procs -----------memory---------- ---swap-- -----io----  --system-- ...
13:43:03: r  b   swpd   free  inact active   si   so    bi    bo    in    cs us 
abcd2x1: 2  0      0  22656 178512 792272    0    0     1    21     7     2  2  
abcd2x2: 0  0 452304  21432 108760 867712    0    0   178   269     2     0  2  
abcd2x3: 0  0  49252 912164  70156  49996    1    1    74   249     2     2  1  
Minimum: 0  0      0  21432  70156  49996    0    0     1    21     2     0  1  
Maximum: 2  0 452304 912164 178512 867712    1    1   178   269     7     2  2  
Average: 0  0 167185 318750 119142 569993    0    0    84   179     3     1  1 

8.3.8 Using dcli with the --hidestderr Option

This example shows how to use the --hidestderr option.

This option can only be used when SSH is used for remotely run commands.

Example 8-8 Using the --hidestderr Option

This first command does not use the --hidestderr option, so the errors are shown.

$ ./dcli -l root -g cell "ls -1 unknown_file; cellcli -e list cell"

exam08cel01: ls: unknown_file: No such file or directory
exam08cel01: exam08cel01         online
exam08cel02: ls: unknown_file: No such file or directory
exam08cel02: exam08cel02         online
This second command uses the --hidestderr option, so the errors are not shown.
$ ./dcli -l root -g cell --hidestderr -l root "ls -l unknown_file;\ 
cellcli -e list cell"

exam08cel01: exam08cel01         online
exam08cel02: exam08cel02         online

8.3.9 Using dcli with the --showbanner Option

This example shows how to use the --showbanner option.

The banner of the remote cell replaces ******BANNER****** shown in the example.

Example 8-9 Using the --showbanner Option

$ ./dcli --showbanner -l root -g cell "cellcli -e list cell"
exam08cel01: ******BANNER******
exam08cel01:
exam08cel01: ******BANNER******
exam08cel01: exam08cel01         online
exam08cel02: ******BANNER******
exam08cel02:
exam08cel02: ******BANNER******
exam08cel02: exam08cel02         online

8.3.10 Using dcli to Change an IORM Plan

This example shows a CellCLI command that changes the IORMPLAN to active on the target cells in the mycells group file.

The -t option displays the cells that are in the mycells group file.

Example 8-10 Using dcli to Change an IORM Plan

$ ./dcli -g mycells -l root -t "cellcli -e alter iormplan active"

8.3.11 Using dcli with a Script

This example shows the CellCLI commands in the reConfig.scl file on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-11 Using dcli with a Script

$ ./dcli -g mycells -x reConfig.scl

8.3.12 Using dcli to List Grid Disk Status

This example shows how to run a CellCLI command that lists the name and status of grid disks on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user. Output lines that contain active as the status are deleted.

Example 8-12 Using dcli to List Grid Disk Status

$ ./dcli -r '.*active' -g mycells "cellcli -e list griddisk"

8.3.13 Using dcli to List Alert History Information

This example shows a CellCLI command that lists alert history name, examined by, severity on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user. Output lines that contain clear for severity are deleted.

Example 8-13 Using dcli to List Alert History Information

$ ./dcli -r '.*clear' -g mycells \
   "cellcli -e list alerthistory attributes name, examinedby, severity"

8.3.14 Using dcli to List Alert History Where examinedby is Not Set

This example shows a CellCLI command that lists alert history where examined by has not been set on the target cells.

The target cells are contained in the allcells group file. The command is run as the default celladmin user.

Example 8-14 Using dcli to List Alert History where examinedby is not Set

$ ./dcli -g allcells -l celladmin \
   "cellcli -e list alerthistory where examinedby=\'\' "

8.3.15 Using dcli to List Current Metric Alert State

This example shows a CellCLI command that retrieves metric current objects for the number of MB read in large blocks on a grid disk for a group of cells.

The command lists the current metric alert state and metric value for the metric GD_IO_BY_R_LG on the target cells. The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-15 Using dcli to List Current Metric Alert State

$ ./dcli -g mycells "cellcli -e list metriccurrent GD_IO_BY_R_LG \
  attributes alertstate, metricvalue"

8.3.16 Using dcli to List Specific Metric Current Objects in a Group

This example shows a CellCLI command that retrieves metric current objects for the number of requests to read or write blocks on a grid disk.

The CellCLI command lists metric current objects for names that begin with GD_IO_RQ on the target cells. The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-16 Using dcli to List Specific Metric Current Objects in a Group

$ ./dcli -g mycells "cellcli -e list metriccurrent where name like \'GD_IO_RQ.*\'"

8.3.17 Using dcli to List Specific Metric Current Objects

This example shows a CellCLI command that lists metric current objects with name equal to cl_put (cell CPU utilization) on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-17 Using dcli to List Specific Metric Current Objects

$ ./dcli -g mycells "cellcli -e list metriccurrent cl_cput"

8.3.18 Using dcli to List Physical Disks

This example shows a CellCLI command that lists physical disks where status is not equal to normal on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-18 Using dcli to List Physical Disks

$ ./dcli -g allcells "cellcli -e list physicaldisk where status not = normal"

8.3.19 Using dcli to List Cell Disks with Free Space

This example shows a CellCLI command that lists cell disks where free space is less than 100 MB on the target cells.

The target cells are contained in the mycells group file. The command is run as the default celladmin user.

Example 8-19 Using dcli to List Cell Disks with Free Space

In this example, the backslash (\) is an escape character that allows the greater than character (>) to be passed to the CellCLI utility without being interpreted by the remote shell.

$ ./dcli -g allcells "cellcli -e list celldisk where freespace \> 100M"

8.3.20 Using dcli to View Alert History

This example shows a CellCLI command to view the alert history from a particular period.

Example 8-20 Using dcli to View Alert History

In this example, the backslash (\) is an escape character that allows the greater than character (>) and the quotation marks to be passed to the CellCLI utility without being interpreted by the remote shell.

dcli -g lab.cells "cellcli -e  list alerthistory where begintime \> \'Aug 4, 2009 12:06:38 PM\'"

8.4 Setting Up SSH User-Equivalence on Oracle Exadata Storage Server

Setting user-equivalence enables you to issue commands to remote cells without having to enter the password for the cell.