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.
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.
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.
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.
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.
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]
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 You cannot use the |
-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
( To enter a
See your Linux documentation for more information about |
-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. |
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']