Commands Reference, Volume 2

dsh Command

Purpose

Concurrently issues remote shell commands to multiple hosts and formats results.

Syntax

dsh -q

dsh [-a][-c] [-i ] [-h][-m] [-q] [-v] [-s] [-z] [-S {csh|ksh}] [-L][-l login_name] [-n { [hostname[,hostname]] | - }] [-w { [hostname[,hostname]] | - }] [-N node_group [,node_group...]] [-o "remote_shell_options"] [-r remote_shell_path] [-f fanout_value] [-t timeout[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 command results from all nodes can be managed. /bin/rsh is the model for syntax and security.

The set of nodes to which commands are sent can be determined in two ways:

The preferred method is 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 flag is used. A list of node groups is specified on the command line when the -N flag 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.

Another method is called the working collective. The working collective is obtained from the first instance of one of the following:

A list of host names is specified on the command line when the -w flag is used. A list of node groups is specified on the command line when the -N flag 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.

An error occurs if neither a node list or a working collective exists when this method is used, and no commands are issued.

If nodes are specified in more than one way, only the highest priority specification is used, as follows:

-n flag
-w flag
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, enter exit on the command line or press the Enter key 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. (For example, to set DSH_PATH to the path set on the source node, use DSH_PATH=$PATH).

dsh runs commands directly on the local host rather than using the remote shell unless the -l flag is used.

The maximum number of concurrent remote shell commands can be specified with the fanout -f flag or using 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 flag, 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 flag instead of the fanout mode, then output is returned from each node as the command is completed on that node, instead of 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 encountered a problem. This is unrelated to the exit code of the remotely issued command. If a remote shell encounters a problem, that node is removed from the current node list. Use the -z flag to obtain the return code from the last command issued on the remote node. Note that OpenSSH behaves differently; it returns the exit status of the remote command as its exit status. This affects the behavior of dsh and may require the use of the -c flag.

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 do not complete successfully, the dsh exit value is greater than 0. The exit value is increased by 1 for each successive instance of an unsuccessful run.

No particular error recovery for command errors 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 flag 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 being down (for example, a remote shell command issues a nonzero return code), subsequent commands are not sent to this node on this invocation of the dsh command unless the -c flag 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 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 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.

You can specify the remote shell you wish to use in the following ways. The order shown here is the order of precedence.

-r flag
DSH_REMOTE_CMD environment variable
CSM RemoteShell attribute.

If none of the above are specified, dsh defaults to rsh.

Flags

-a: Adds all nodes defined to CSM to the node list.
-c: Specifies that commands that were unsuccessful should continue to be sent to the remote nodes.
-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 runs can be specified by indicating a fanout value of 1. The fanout value is taken from the DSH_FANOUT environment variable if the -f flag is not specified.
-h: Writes the command's usage statement to standard output.
-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 flag 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 { [hostname [,hostname...]] | - }: Specifies a list of host names, separated by commas, to include in the node list. If - is specified, you enter standard input mode. Standard input mode is indicated by a new line with no dsh prompt. Enter the host names one 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 node groups, separated by commas, and adds the nodes to the node list or working collective.
-L: Specifies to not export locale environment.
-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 flag must exist on the dsh command line alone. It cannot be used in conjunction with any other dsh flag or with the command parameter.
-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 the shell syntax to be used on the remote system.
-S { csh|ksh }: Specifies the shell being used on the remote system. The default is the shell from which dsh is issued.
-t timeout: Specifies the time, in seconds, to wait for response from the remote shell. Overrides the value of the DSH_TIMEOUT environment variable.
-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 the lsnode command 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 a few seconds to check the node that is not responding, rather than the minute typically taken for the remote shell command to time out.
-w { [hostname [,hostname...]] | - }: Specifies a list of host names, separated by commas, to include in the working collective. If - is specified, you enter standard input mode. Standard input mode is indicated by a new line with no dsh prompt. Enter the host names one 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.

Parameters

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.

Security

Security considerations are the same as for the rsh command.

Exit Status

0: The command has run successfully.
1: An error has occurred.

Environment Variables

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 flag.
DSH_LIST: Specifies a file that contains definitions of the set of nodes that comprise the node list.
DSH_TIMEOUT: Specifies the time, in seconds, to wait for response from the remote shell. This can also be set with the -t flag.
WCOLL: Specifies a file that contains definitions of the set of nodes that comprise the working collective.

Examples

To run 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 a file of commands sequentially on all the members of the current working collective and save the results in a file, including the collective and the working collective for each command, enter:
```
dsh -if 1 <commands_file >results 2>&1
```
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 flag 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
```
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/definenode: Location of the definenode command.
/opt/csm/install/nodedef.sample: Location of the sample node definition file.

Prerequisite Information

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

Related Information

The rsh command.
The IBM CSM for AIX 5L: Administration Guide.