8 Using the dcli Utility

The dcli utility facilitates centralized management across Oracle Exadata Database Machine.

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

• Overview of the dcli Utility
  The dcli utility runs operating system commands on multiple servers in parallel threads. The target servers can be Exadata Storage Servers or Exadata database servers. However, the dcli utility does not support an interactive session with a remote application.
• dcli Syntax
  This topic describes the syntax for the dcli utility.
• dcli Examples
  This section contains examples of the using the dcli utility.
• 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.

8.1 Overview of the dcli Utility

The dcli utility runs operating system commands on multiple servers in parallel threads. The target servers can be Exadata Storage Servers or Exadata database servers. However, the dcli utility does not support an interactive session with a remote application.

You can run the dcli utility on an Exadata Storage Server or Exadata database server, or you can copy the utility to another host computer that acts as a central management server. You can issue a command to be run on multiple servers, or use files that can be copied to servers and then run. The servers 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 the target servers. You can use the dcli utility initially with the -k option to set up SSH user-equivalence. Also, you can manually set up SSH user-equivalence to servers.

Command output (stdout and stderr) is collected and displayed after the copy and command execution is finished on the specified servers. 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
--batchsize=MAXTHDS	Limits the number of parallel execution threads, which limits the number of target servers on which to run the operation in parallel.
-c CELLS	Specifies a comma-delimited list of target servers to which commands are sent.
--ctimeout=CTIMEOUT	Specifies the maximum time in seconds for initial connection to a target server.
-d DESTFILE	Specifies the target destination directory or file on remote servers 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 servers. 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 server.
-g GROUPFILE	Specifies a file containing a list of target servers to which commands are sent. The servers can be identified by host 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 servers specified with the -c or -g option by appending public key files to the authorized_keys file on servers.
--key-with-one-password	This option simplifies SSH user-equivalence setup by prompting once for the user password and using the specified password for all the configured servers. If not specified, then a password prompt occurs for each server.
-l USERID	Identifies the user to log in as on remote servers. The default is the celladmin user.
--root-exadatatmp	This option uses the root user, similar to -l root. However, instead of using /root as the default working directory, this option uses /var/log/exadatatmp, which avoids alerts generated by Advanced Intrusion Detection Environment (AIDE) for files written to /root.
--maxlines=MAXLINES	Limits output from each target server to the specified number of lines. By default, the output limit from each target server is 100000 lines.
-n	Abbreviates nonerror output. Servers that return normal output (return code of 0) only have the server 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 servers 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 servers 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	Runs the vmstat utility on the target servers with the specified command options.
-x EXECFILE	Specifies the command file to be copied and run on the servers. 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 server. The file is copied to the default home directory of the user on the target server.

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 servers.
• 1: One or more servers could not be reached or remote execution returned a nonzero status.
• 2: A local error prevented any command execution.

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

8.3 dcli Examples

This section contains examples of the using the dcli utility.

• 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.
• Using dcli with the -n Option
  This example shows how to run the CellCLI command ALTER IORMPLAN OBJECTIVE='basic', and abbreviates non-error output.
• 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.
• Using dcli with the -v Option
  This example shows how to use the verbose (-v) option with SSH.
• Using dcli with the -t Option
  This example shows how to use the -t option to list target cells.
• Using dcli with the -f Option
  This example shows how to use the -f option.
• Using dcli with the --vmstat Option
  This example shows how to use the --vmstat option of dcli.
• Using dcli with the --hidestderr Option
  This example shows how to use the --hidestderr option.
• Using dcli with the --showbanner Option
  This example shows how to use the --showbanner option.
• 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.
• Using dcli with a Script
  This example shows the CellCLI commands in the reConfig.scl file on the target cells.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Using dcli to View Alert History
  This example shows a CellCLI command to view the alert history from a particular period.

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.

• To set up SSH user-equivalence for use with the dcli utility, use the -k option.
  See Using dcli to Set up SSH User-equivalence for a Current User.