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.
9.1 Overview of the dcli Utility
The dcli utility runs commands on multiple cells in parallel threads. However, it 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 (
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.
This sections contains the following topics:
9.1.1 dcli Syntax
dcli [options] [command]
In the preceding command, the following arguments are used:
options: The following table lists the available options and their descriptions.
Table 9-1 dcli Options
Specifies a comma-delimited list of target cells to which commands are sent.
Specifies the target destination directory or file on remote cells to be used when copying files or directories using the
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.
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.
Displays help text and then exits.
Hide standard error messages (STDERR) for commands run remotely using SSH.
Sets up SSH user-equivalence for the current user to the cells specified with the
-goption by appending public key files to the
authorized_keysfile on cells.
Identifies the user to log in as on remote cells. The default is the
Abbreviates nonerror output. Cells that return normal output (return code of
0) only have the cell name listed.
-roptions cannot be used together.
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.
-noptions cannot be used together.
Passes a string of options to SSH.
Passes a string of options to
scpif different from
Serializes the process over Oracle Exadata Storage Servers.
Show the banner of the remote node when using SSH.
Displays the target cells that are named with the
-coption or in the
groupfileidentified by the
Drops keys from the target
authorized_keysfile on Oracle Exadata Storage Servers.
Prints the verbose version of messages to
Shows the version number of the program and then exits.
Displays view process, virtual memory, disk, trap, and CPU activity information, depending on the switches.
Specifies the command file to be copied and run on the cells. The specified file contains a list of commands. A file with the
.sclextension 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.
command: Any command that can be run from an operating system prompt. 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
-xoption. Within a script, the escape character is not required.
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.
9.1.2 dcli Examples
This section contains examples of the dcli utility.
Example 9-1 shows how to set SSH user-equivalence for a current user using the
Example 9-2 shows how to run the CellCLI command
ALTER IORMPLAN OBJECTIVE='basic', and abbreviates nonerror output.
Example 9-3 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 9-4 shows how to use the verbose (
-v) option with SSH.
Example 9-5 shows how to use the
-t option to list target cells. This option should be used with
Example 9-6 shows how to use the
-f option. In the example, a set of files is copied to the cells.
Example 9-7 shows how to use the
Example 9-8 shows how to use the
--hidestderr option. The first command in the example does not use the
--hidestderr option, so the errors are shown. The second command does use the option, so the errors are not shown. This option can only be used when SSH is used for remotely run commands.
Example 9-9 shows how to use the
--showbanner option. The banner of the remote cell replaces
******BANNER****** shown in the example.
Example 9-10 shows a CellCLI command that changes the IORMPLAN to active on the target cells in the mycells group file as the
celladmin user. The
-t option displays the cells that are in the mycells groupfile.
Example 9-11 shows a CellCLI commands in the
reConfig.scl file on the target cells in the mycells group file as the default
Example 9-12 shows a CellCLI command that lists the name and status of grid disks on the target cells in the mycells group file as the default
celladmin user. Output lines that contain
active as the status are deleted.
Example 9-13 shows a CellCLI command that lists alert history name, examined by, severity on the target cells in the mycells group file as the default
celladmin user. Output lines that contain
clear for severity are deleted.
Example 9-14 shows a CellCLI command that lists alert history where examined by has not been set on the target cells in the mycells group file as the
Example 9-15 shows a CellCLI command that lists the current metric alert state and metric value for metric GD_IO_BY_R_LG on the target cells in the mycells group file as the
celladmin user. This query retrieves metric current objects for the number of MB read in large blocks on a grid disk.
Example 9-16 shows a CellCLI command that lists metric current objects for names that begin with GD_IO_RQ on the target cells in the mycells group file as the
celladmin user. This query retrieves metric current objects for the number of requests to read or write blocks on a grid disk.
Example 9-17 shows a CellCLI command that lists metric current objects with name equal to
cl_put (cell CPU utilization) on the target cells in the mycells group file as the default
Example 9-18 shows a CellCLI command that lists physical disks where status is not equal to normal on the target cells in the mycells group file as the default
Example 9-19 shows a CellCLI command that lists cell disks where free space is less than 100 MB on the target cells in the mycells group file as the default
Example 9-20 shows a CellCLI command to view the alert history from a particular period.
In the preceding 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.
Example 9-1 Setting up SSH User-equivalence for a Current User
$ ./dcli -k -g mycells
-k option assumes the user has accepted the default key file names for the SSH protocol, version 2. These file names are
id_rsa.pub, and are located in the
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.
Example 9-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'.
Example 9-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
Example 9-4 Using the -v Option
$ ./dcli -s "-v" -c mycell date
Example 9-5 Using the -t Option
$ ./dcli -t -c stsd2s1 date Target cells: ['stsd2s1'] stsd2s1: Fri Jul 17 15:37:31 PDT 2009
Example 9-6 Using the -f Option
dcli -g mycells -f '*.bin'
Example 9-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
Example 9-8 Using the --hidestderr Option
$ ./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 $ ./dcli -l root -g cell --hidestderr -l root "ls -l unknown_file; cellcli \ -e list cell" exam08cel01: exam08cel01 online exam08cel02: exam08cel02 online
Example 9-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
Example 9-10 Using dcli to Change an IORM Plan
$ ./dcli -g mycells -l root -t "cellcli -e alter iormplan active"
Example 9-11 Using dcli with a Script
$ ./dcli -g mycells -x reConfig.scl
Example 9-12 Using dcli to List Grid Disk Status
$ ./dcli -r '.*active' -g mycells "cellcli -e list griddisk"
Example 9-13 Using dcli to List Alert History Information
$ ./dcli -r '.*clear' -g mycells \ "cellcli -e list alerthistory attributes name, examinedby, severity"
Example 9-14 Using dcli to List Alert History where examinedby is not Set
$ ./dcli -g allcells -l celladmin \ "cellcli -e list alerthistory where examinedby=\'\' "
Example 9-15 Using dcli to List Current Metric Alert State
$ ./dcli -g mycells "cellcli -e list metriccurrent GD_IO_BY_R_LG \ attributes alertstate, metricvalue"
Example 9-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.*\'"
Example 9-17 Using dcli to List Specific Metric Current Objects
$ ./dcli -g mycells "cellcli -e list metriccurrent cl_cput"
Example 9-18 Using dcli to List Physical Disks
$ ./dcli -g allcells "cellcli -e list physicaldisk where status not = normal"
Example 9-19 Using dcli to List Cell Disks with Free Space
$ ./dcli -g allcells "cellcli -e list celldisk where freespace \> 100M"
Example 9-20 Using dcli to View Alert History
dcli -g lab.cells "cellcli -e list alerthistory where begintime \> \'Aug 4, 2009 12:06:38 PM\'"
9.2 Setting Up SSH User-Equivalence on Oracle Exadata Storage Server
- To set up SSH user-equivalence for use with the
dcliutility, use the
-koption.Setting user-equivalence enables you to issue commands to remote cells without having to enter the password for the cell.See Example 9-1.