1. Using Oracle Big Data Cloud Service
  2. Manage Oracle Big Data Cloud Service System Software at the Command Line
  3. Using dcli to Execute Commands Across a Cluster

Using dcli to Execute Commands Across a Cluster

The dcli utility executes commands across a group of nodes on Oracle Big Data Cloud Service and returns the output.

This chapter contains the following sections:

Overview of the dcli Utility

The dcli utility executes commands across a group of nodes in an Oracle Big Data Cloud Service cluster and returns the output. You use dcli to reinstall or reconfigure software on a cluster.

Basic Use of dcli

Getting Help

To see the dcli help page, enter the dcli command with the -h or --help options. You can see a description of the commands by entering the dcli command with no options.

Identifying the Target Nodes

You can identify the nodes where you want the commands to run either in the command line or in a file. For a list of default target nodes, use the -t option. To change the target nodes for the current command, use the -c or -g options described in the table below..

You can manually create files with groups of nodes to manage together. For example, you might manage nodes 5 to 18 together, because they have no special functions like nodes 1 to 4.

Specifying the Commands

You typically specify a command for execution on the target nodes on the command line. However, you can also create a command file for a series of commands that you often use together or for commands with complex syntax. See the -x option in the table below.

You can also copy files to the target nodes without executing them by using the -f option.

Controlling the Output Levels

You can request more information with the -v option or less information with the -n option. You can also limit the number of returned lines with the --maxlines option, or replace matching strings with the -r option.

Following are examples of various output levels using a simple example: the Linux date command.

Note:

The output from only one node (node07) is shown. The syntax in these examples executes the date command on all nodes.

This is the default output, which lists the node followed by the date.

# dcli date 
bda1node07-adm.example.com: Tue Feb 14 10:22:31 PST 2016

The minimal output returns OK for completed execution: 

# dcli -n date 
OK: ['bda1node07.example.com']

Verbose output provides extensive information about the settings under which the command ran:

dcli -v dateoptions.nodes: Noneoptions.destfile: Noneoptions.file: Noneoptions.group: dcserversoptions.maxLines: 100000options.listNegatives: Falseoptions.pushKey: Falseoptions.regexp: Noneoptions.sshOptions: Noneoptions.scpOptions: Noneoptions.dropKey: Falseoptions.serializeOps: Falseoptions.userID: rootoptions.verbosity 1options.vmstatOps Noneoptions.execfile: Noneargv: ['/opt/oracle/bda/bin/dcli', '-g', 'dcservers', '-v', 'date']Success connecting to nodes: ['bda1node07.example.com']...entering thread for bda1node07.example.com:execute: /usr/bin/ssh -l root bda1node07.example.com ' date' ...exiting thread for bda1node07.example.com status: 0bda1node07.example.com: Tue Feb 14 10:24:43 PST 2012]

dcli Syntax

dcli [option] [command]

Parameters

option
An option described in the table below. You can omit all options to run a command on all nodes in the cluster.
command

Any command that runs from the operating system prompt. If the command contains punctuation marks or special characters, then enclose the command in double quotation marks.

The backslash (\) is the escape character. Precede the following special characters with a backslash on the command line to prevent interpretation by the shell. The backslash is not needed in a command file. See the -x option for information about command files.

  • $ (dollar sign)

  • ' (quotation mark)

  • < (less than)

  • > (greater than)

  • ( ) (parentheses)

dcli Options

Option Description
-c nodes

Specifies a comma-separated list of Oracle Big Data Cloud Service nodes where the command is executed

-C

Uses the list of nodes in /opt/oracle/bda/cluster-rack-infiniband as the target. See Identifying the Target Nodes.

-d destfile

Specifies a target directory or file name for the -f option

-f file

Specifies files to be copied to the user's home directory on the target nodes. The files are not executed. See the -l option.

-g groupfile

Specifies a file containing a list of Oracle Big Data Cloud Service nodes where the command is executed. You can use either node names or IP addresses in the file.

-h, --help

Displays a description of the commands
-k

Pushes the ssh key to each node's /root/.ssh/authorized_keys file.

-l userid

Identifies the user ID for logging in to another node. The default ID is root.

--maxlines=maxlines

Identifies the maximum lines of output displayed from a command executed on multiple nodes. The default is 10,000 lines.
-n

Abbreviates the output for non-error messages. Only the node name is displayed when a node returns normal output (return code 0).

You cannot use the -n and -r options together.

-r regexp

Replaces the output with the node name for lines that match the specified regular expression
-s sshoptions

Specifies a string of options that are passed to SSH
--scp=scpoptions

Specifies a string of options that are passed to Secure Copy (SCP), when these options are different from sshoptions
--serial

Serializes execution over the nodes. The default is parallel execution.
-t

Lists the target nodes
--unkey

Drops the keys from the authorized_key files of the target nodes

-v

Displays the verbose version of all messages
--version

Displays the dcli version number

--vmstat=VMSTATOPS

Displays the syntax of the Linux Virtual Memory Statistics utility (vmstat). This command returns process, virtual memory, disk, trap, and CPU activity information.

To enter a vmstat command, enclose its options in quotation marks. For example: 

--vmstat="-a 3 5"

See your Linux documentation for more information about vmstat.

-x execfile

Specifies a command file to be copied to the user's home directory and executed on the target nodes. See the -l option.

dcli Return Values

  • 0: The command ran successfully on all nodes.

  • 1: One or more nodes were inaccessible or remote execution returned a nonzero value. A message lists the unresponsive nodes. Execution continues on the other nodes.

  • 2: A local error prevented the command from executing.

If you interrupt the local dcli process, then the remote commands may continue without returning their output or status.

dcli Examples

Following are examples of the dcli utility.

This example returns the default list of target nodes:

# dcli -t
Target nodes: ['bda1node01-adm.example.com', 'bda1node02-adm.example.com', 'bda1node03-adm.example.com', 'bda1node04-adm.example.com', 'bda1node05-adm.example.com', 'bda1node06-adm.example.com', 'bda1node07-adm.example.com', 'bda1node08-adm.example.com', 'bda1node09-adm.example.com']

The next example checks the temperature of all nodes:

# dcli 'ipmitool sunoem cli "show /SYS/T_AMB" | grep value'

bda1node01-adm.example.com: value = 22.000 degree C
bda1node02-adm.example.com: value = 22.000 degree C
bda1node03-adm.example.com: value = 22.000 degree C
bda1node04-adm.example.com: value = 23.000 degree C
          .
          .
          .