9 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.

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 (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.

This sections contains the following topics:

9.1.1 dcli Syntax

The dcli utility syntax is:

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

    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.

  • 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 -x option. 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 -k option.

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 -c or -g option.

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 --vmstat option.

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 celladmin user.

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 celladmin user.

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 celladmin user.

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 celladmin user.

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 celladmin user.

Note:

In the preceding 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.

Example 9-20 shows a CellCLI command to view the alert history from a particular period.

Note:

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

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.

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 dcli utility, use the -k option.
    Setting user-equivalence enables you to issue commands to remote cells without having to enter the password for the cell.