Oracle Cloud Infrastructure Documentation

Using dcli to Execute Commands Across a Cluster

Use the dcli utility to execute commands across a group of nodes on a Big Data Service cluster and return the output. You can use dcli to reinstall or reconfigure software on your cluster.

Viewing dcli 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.

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]
[option]

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

Option Description
-c NODES Specifies a comma-separated list of Big Data Service nodes where the command is executed.
-C Uses the cluster hosts file /opt/oracle/bda/cluster-hosts-infiniband as the target.
-d DESTFILE Specifies a destination 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 aren't executed. See the -l option.
-g GROUPFILE Specifies a file containing a list of Big Data 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.
[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 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 Example

Following is an example 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']