Administration Guide
Name
dsh - Concurrently issues remote shell commands to multiple hosts and
formats results.
Synopsis
dsh -q
dsh [ -h]
[-a] [-c] [-i
] [-m] [-v]
[-z] [-l
login_name] [-n
host[,host...]] [-N
node_group[,node_group...]]
[-w {host[,host...] |
- }] [-o
"remote_shell_options"] [-r
remote_shell_path] [-f fanout_value
] [-s] [command]
Description
The dsh command invokes commands on a set of nodes
concurrently. It issues a remote shell command concurrently for each
node that is specified and returns the output from all the nodes, formatted so
that command results from all the nodes can be managed.
/bin/rsh is the model for syntax and security. It is assumed
that the remote login shell of the user of dsh is the bash
shell.
The set of nodes to which the commands are sent can be determined in two
ways:
The first way is called the node list. The node list is
obtained from the first existence of one of the following:
- A list of host names is specified on the command line when the
-n option is used. A list of node groups is specified on the
command line when the -N option is used.
- The contents of a file named by the DSH_LIST environment
variable. The node-list file format is one host name per line.
Blank lines and comment lines beginning with # are
ignored.
This is the preferred manner.
The second way is called the working collective. The
working collective is obtained from the first existence of one of the
following:
- A list of host names is specified on the command line when the
-w option is used. A list of node groups is specified on the
command line when the -N option is used.
- The contents of a file named by the WCOLL environment
variable. The working collective file format is one host name per
line. Blank lines and comment lines beginning with # are
ignored.
If neither a node list nor a working collective exists when this approach
is used, an error has occurred, and no commands are issued.
If nodes are specified in more than one way, only the highest priority
specification is used, as follows:
- -n option
- -w option
- DSH_LIST
- WCOLL
If the command parameter is not specified, dsh reads
lines from the command line or standard input and issues each input as a
command on each host in the node list or working collective. The
commands use the syntax of the remote shell command.
To exit the dsh command line mode, type exit or press
Enter at the dsh prompt.
When commands are resolved on the remote node, the path used is
determined by the DSH_PATH environment variable specified by the
user. If DSH_PATH is not set, the path used is the remote
shell default path, /usr/ucb:/bin:/usr/bin. (For
example, to set DSH_PATH to the path set on the source node, use
DSH_PATH=$PATH).
The maximum number of concurrent remote shell commands can be
specified with the fanout (-f) option or by means of the
DSH_FANOUT environment variable. If desired, sequential
invocation can be obtained by specifying a fanout value of 1. The
fanout is kept at the fanout number that is specified. When one command
is completed on a node, another command is started. If fanout is not
specified by the DSH_FANOUT environment variable or by the
-f option, then a default fanout of 64 is used. Each remote
shell command that dsh runs requires a reserved TCP/IP port, and only
512 such ports are available per node.
If the streaming mode is specified by the -s option instead of the
fanout mode, then output is returned from each node as the command is
completed on that node rather than waiting for the command to be completed on
all nodes before the results are returned. This can improve performance
but causes the output to be unsorted.
Exit values for the remote shell commands are displayed in messages from
the dsh command if the exit values are nonzero. A nonzero
return code from a remote shell indicates that the remote shell has
failed. This has nothing to do with the exit code of the remotely
issued command. If a remote shell fails, that node is removed from the
current node list. Use the -z option to obtain the return code
from the last command issued on the remote node.
The dsh exit value is 0 if no errors occurred in the dsh
command and all remote shell commands finished with exit codes of 0. If
internal errors occur or the remote shell commands fail, the dsh exit
value is greater than 0. The exit value is increased by 1 for each
remote shell failure.
No particular error recovery for command failure on remote hosts is
provided. The application or user can examine the command results in
the standard error and standard output of the dsh command and take
appropriate action.
The dsh command waits until results are in for each command for
all hosts and displays those results before reading more input
commands. This is true only if the -s option is not
specified on the dsh command line.
The dsh command does not work with interactive commands, including
those read from standard input.
The dsh command output consists of the output (standard error and
standard output) of the remotely issued commands. The dsh
standard output is the standard output of the remote shell command. The
dsh standard error is the standard error of the remote shell
command. Each line is prefixed with the host name of the node which
produced the output. The host name is followed by ":" and a line
of the command output.
For example: a command was issued to a node list of host1, host2, and host3. When the command was issued on
each of the hosts, the following lines were written by the remote
commands:
For host1 stdout:
h1out1
h1out2
For host2 stdout:
h2out1
h2out2
For host3 stdout:
h3out1
For host3 stderr:
h3err1
h3err2
dsh stdout will be
host1: h1out1
host1: h1out2
host2: h2out1
host2: h2out2
host3: h3out1
dsh stderr will be
host3: h3err1
host3: h3err2
A filter to display identical outputs grouped by node is provided
separately. See the dshbak command.
If a node is detected as down (for example, a remote shell command issues a
nonzero return code), subsequent commands are not sent to this node on this
invocation of dsh unless the -c option is specified.
An exclamation point (!) at the beginning of a command line causes
the command to be passed directly to the local host in the current
environment. The command is not sent to the node list.
Signal 2 (INT), Signal 3 (QUIT), and Signal 15 (TERM) are propagated to the
remote commands.
Signal 19 (CONT), Signal 17 (STOP), and Signal 18 (TSTP) are
defaulted. This means that the dsh command responds normally
to these signals, but the signals do not have an effect on the remotely
running commands. Other signals are caught by dsh and have
their default effects on the dsh command. In the case of these
other signals, all current child processes, and, by means of propagation,
their remotely running commands, are terminated (SIGTERM).
- Note:
- The -P and -B options are no longer
valid for this command.
- Note:
- The DSH_REMOTE_CMD environment variable can be used to specify a
remote shell other than the default (rsh), for example, a secure remote command that conforms to the IETF (Internet Engineering Task Force) secure remote command protocol. Be aware, however of the following limitations:
- The dsh itself has no security configuration or
obligations. All security issues are related to the remote execution
environment enabled by the user and the security configuration level that the
user has implemented. For example, if the remote shell requires public
keys, it is the responsibility of the user to implement this.
- Use the fully qualified host name when you define a node for the
remote shell. If the remote shell requires a list of nodes in its
configuration, then the nodes must be defined by their fully qualified host
names. This allows the dsh command to recognize the
node. You can also use an alias to define a node. Aliases are
permitted provided the fully qualified host name is also provided.
- command
- Specifies a command to invoke on the node list. It is passed to
remote shell. This command is specified by using the remote shell
command syntax.
Options
- -a
- Adds all nodes defined to IBM Cluster Systems Management for Linux (CSM)
to the node list.
- -c
- Specifies that commands that failed continue to be sent to the remote
nodes for execution.
- -f fanout_value
- Specifies a fanout value. The default value is 64. It
indicates the maximum number of concurrent remote shell commands to
issue. Sequential execution can be specified by indicating a fanout
value of 1. The fanout value is taken from the DSH_FANOUT
environment variable if the -f option is not specified.
- -h
- Writes the command's usage statement to standard out.
- -i
- Informs the user that a node is not responding and prompts the user as to
whether the node should be included in the node list.
- -l login_name
- Specifies a remote user name under which to invoke the commands. If
-l is not used, the remote user name is the same as the local user
name. Use this option as you would with the remote shell
command.
- -m
- Prints the results of monitoring for each node in the form of the starting
and completion messages for each node.
- -n {host[,host...] | - }
- Specifies a list of host names, separated by commas, to include in the
node list. If "-" is specified, you enter standard input mode.
You know that you are in standard input mode because a new line is provided
that has no dsh prompt. Enter the host names a line at a
time. When you are finished, press <Ctrl+d> to exit
standard input mode and return to the dsh prompt. If -n
- is used, commands cannot be read from standard input.
- Note:
- Duplicate host names are included only once in the node list.
- -N node_group[, node_group...]
- Resolves one or more CSM-specified node groups, separated by commas, and
adds the nodes to the node list or working collective.
- -o "remote_shell_options"
- Forwards options for the remote shell. The information within the
quotation marks is forwarded and included in the remote shell.
- -q
- Displays the current environment variable settings. For
example, the list of nodes in the current node list or working collective file
and the value of the DSH_FANOUT environment variable are
displayed.
- Note:
- This option must exist on the dsh command line alone. It
cannot be used in conjunction with any other dsh option or with the
command argument.
- -r remote_shell_path
- Provides the full path of the remote shell that is used to access the
remote systems. The default remote shell is rsh.
- -s
- Specifies output in streaming mode. The output is unsorted, but
performance is likely to improve, and memory utilization is reduced.
- -v
- Verifies a node before adding it to the node list. If a node is not
responding, it is not included in the node list. If the
/opt/csm/bin/lsnode command is installed, then it can be used to
check the ping status of the node. If lsnode is not
installed or if the status returned is not zero, then the command
/bin/ping can be used to check the node. The
/bin/ping command takes 10 seconds to check the node that is not
responding, rather than the minute typically taken for the remote shell
command to time out.
- -w {host[,host...] | - }
- Specifies a list of host names, separated by commas, to include in the
working collective. If "-" is specified, you enter standard input
mode. You know that you are in standard input mode because a new line
is provided that has no dsh prompt. Enter the host names a
line at a time. When you are finished, press <Ctrl+d> to
exit standard input mode and return to the dsh prompt. If
-w - is used, commands cannot be read from standard input.
- Note:
- Duplicate host names are included only once in the working collective.
- -z
- Prints the return code of the last command that was run remotely.
The return code is appended at the end of the output for each node.
Environment
- DSH_PATH
- Sets the path that is used on the remote nodes. If DSH_PATH is not
set, the default path for the remote shell is used. For example,
DSH_PATH=$PATH sets the path on the remote node to the same path
that is used on the source node.
- DSH_REMOTE_CMD
- Specifies the path of the remote shell executable to use instead of
the default.
- DSH_REMOTE_OPTS
- Includes the options specified in the remote command when the command is
forwarded to the remote nodes.
- DSH_FANOUT
- Sets the maximum number of concurrent remote shell commands. This
can also be set by the -f option.
- DSH_LIST
- Specifies a file that contains definitions of the set of nodes that
comprise the node list.
- WCOLL
- Specifies a file that contains definitions of the set of nodes that
comprise the working collective.
Security
Security considerations are the same as for the remote shell
command.
Examples
- To issue the ps command on each host listed in the
dshhosts file, enter:
DSH_LIST=./dshhosts dsh ps
- To list the current node list file as specified by the DSH_LIST
environment variable, enter:
dsh -q
- To set the node list to three nodes and start reading commands from
standard input, enter:
dsh -n otherhost1,otherhost2,otherhost3
- To set the current node list to three nodes and issue a command on those
nodes while formatting the output, enter:
dsh -n host1,host2,host3 -a cat /etc/passwd | dshbak
- To append the file remotefile on the node named
otherhost, to the file named otherremotefile, which is
located on otherhost, enter:
dsh -n otherhost cat remotefile '>>' otherremotefile
- To run the ps command on the node list and filter results
locally, enter:
dsh ps -ef | grep root
- To run the ps command and filter results on the node list hosts
(this can improve performance considerably), enter:
dsh 'ps -ef | grep root'
or
dsh ps -ef "|" grep root
- To cat a file from host1 to the local system, stripping
off the preceding host name to preserve the file, enter:
dsh -n host1 cat /etc/passwd | cut -d: -f2- | cut -c2- >myetcpasswd
- To run the needs_auth_program with the -D
option specified on the remote shell, on all of the nodes in the cluster,
enter:
dsh -a -o "-D" /usr/bin/needs_auth_program
- To enter a list of host names in standard input mode by specifying
-n- and then request the date from the specified nodes,
enter:
dsh -n -
When you complete the list of host names, press <Ctrl+d> to
return to the dsh prompt. At the dsh prompt,
specify:
date
The output will be similar to the following:
# dsh -n -
host1
host2
host3
dsh> date
host1: Fri Mar 23 08:46:59 EST 2001
host2: Fri Mar 23 08:46:59 EST 2001
host3: Fri Mar 23 08:46:59 EST 2001
dsh> exit
#
Files
- /opt/csm/bin/dsh
- Location of the dsh command.
- /opt/csm/bin/dshbak
- Location of the command that is supplied as the back-end formatting
filter.
- node list file
- File that contains host names, one per line, that defines a set of
nodes which comprise the node list. This file is specified by the
DSH_LIST environment variable.
- working collective file
- File that contains host names, one per line, that defines a working
collective. This file is specified by the WCOLL environment
variable.
See Also
The dshbak and rsh man pages.
Author
Patrick Ladd - cluster@us.ibm.com
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]