Commands Reference, Volume 2, d - h dsh Command Purpose dsh - 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 node_list | -] [-w [node_list] | - ] [-N nodegroups] [-o "remote_shell_options"] [-r remote_shell_path] [-f fanout_value] [-t timeout] [-R | --reports directory] [--log filename] [-W | --noFileWriting] [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 nodes can be managed. /usr/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 instance of one of the following: 1. 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. 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. Another method is called the working collective. The working collective is obtained from the first instance of one of the following: 1. 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. 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. An error occurs if neither a node list nor 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: 1. -n flag 2. -w flag 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, 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 non-zero 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 /usr/bin/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 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. 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 /usr/bin/rsh. Note that dsh defaults to ksh syntax unless you use the -S flag. Flags -a Adds all nodes defined to CSM to the node list. Note that you cannot use the -a flag with the -n or -w flag. -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 to decide 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. --log filename Sets the log file. Log entries are added for each instance of the dsh command. This flag overrides the DSH_LOG environment variable. -L Specifies to not export locale environment. -m Prints the results of monitoring for each node in the form of the starting and completion messages for each node. -n node_list | - Specifies a comma or space-separated list of node host names, IP addresses, or node ranges on which to run the command. Space-separated lists must be inside double quotes. For information about specifying node ranges, see the noderange man page. If - is specified, you enter standard input mode. dsh prompts for host names with dsh host>".". Enter the host names one line at a time. When you are finished, press to exit standard input mode and return to the dsh prompt. If -n - is used, commands cannot be read from standard input when redirected from a file. Note: Duplicate host names are included only once in the node list. -N nodegroups Resolves one or more CSM 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 flag must be specified by itself on the dsh command line. 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. -R | --reports directory Sets the reports directory for reporting. All output from each host is saved to individual output and error files and a report is generated. A unique subdirectory is created to hold the output files and the report for each instance of the command. The subdirectory name is created using the default unspecified. An integer extension is added to the name to create a unique directory name. The flag overrides the DSH_REPORTS_DIRECTORY environment variable. -s Specifies output in streaming mode. The output is unsorted, but performance is likely to improve, and memory utilization is reduced. -S csh | ksh Specifies the shell syntax to be used on the remote system. -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 node_list | - Specifies a comma or space-separated list of node host names, IP addresses, or node ranges on which to run the command. Space-separated lists must be inside double quotes. Host names must be specified as positional arguments or preceded by the -w flag. For information about specifying node ranges, see the noderange man page. If - is specified, you enter standard input mode. dsh prompts for host names with dsh host>".". Enter the host names one line at a time. When you are finished, press to exit standard input mode and return to the dsh prompt. If -w - is used, commands cannot be read from standard input when redirected from a file. Note: Duplicate host names are included only once in the working collective. -W | --noFileWriting Disables output file writing for an instance of the command when used with the --reports flag or when the DSH_REPORTS_DIRECTORY is set. -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 the remote shell. This command is specified by using the remote shell command syntax. Security The command requires root access to the cluster management server. Additional security considerations are the same as those for the remote shell command. Exit Status 0 The command has run successfully. 1 An error has occurred. Environment Variables 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_LOG Enables logging when set to the absolute path and file name of the log file. This variable is overriden by the --log flag. 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_REPORTS_DIRECTORY Enables reporting and output file writing when set to the reports directory path. This variable is overriden by the --reports flag. 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 1. To run 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 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 results 2>&1 7. To run the ps command on the node list and filter results locally, enter: dsh ps -ef | grep root 8. 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 9. 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 10. 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 11. 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 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 # Location /opt/csm/bin/dsh Related Information The dshbak and rsh commands.