IBM Books

Administration Guide

dsh Command

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:

  1. 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.
  2. 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:

  1. 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.
  2. 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:

  1. -n option
  2. -w option
  3. DSH_LIST
  4. 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:
  1. 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.
  2. 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

  1. To issue the ps command on each host listed in the dshhosts file, enter:
    DSH_LIST=./dshhosts dsh ps
    
  2. To list the current node list file as specified by the DSH_LIST environment variable, enter:
    dsh -q
    
  3. To set the node list to three nodes and start reading commands from standard input, enter:
    dsh -n otherhost1,otherhost2,otherhost3
     
    
  4. 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
    
  5. 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
    
  6. To run the ps command on the node list and filter results locally, enter:
    dsh ps -ef | grep root
     
    
  7. 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
    
  8. 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
            
    
  9. 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
    
  10. 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 ]