dsh Command
Purpose
Runs commands concurrently on multiple nodes and hardware devices.
Syntax
dsh -h dsh -V dsh -q dsh [ -a] [--all-nodes context_list]
[ -A ] [--all-devices context_list] [-n
node_list] [-N nodegroups] [-d device_list]
[-D devicegroups] [-C context]
[-c] [ -e ] [ -E environment_file
] [-f fanout] [ -F output_path]
node_options] [-O device_options] [-Q]
[-r node_remote_shell] [--device-rsh
csh | ksh] [-t timeout]
report_path] [--report-name report_name] [command_list]
Description
The dsh command runs commands concurrently on remote targets - nodes, hardware devices, or both. Targets can be selected from multiple contexts. A context is a target database that contains node and device definitions, such as the NIM database. The dsh command issues a remote shell command for each target specified. It returns output from all targets in a formatted manner to enable the command results from all nodes to be managed easily. The/usr/bin/rsh is the model for syntax and security and the dsh command is a DSM Distributed Shell Utility.
Note: The dsh command is supported only on IPv4 target devices.
IPv6 addresses are not supported currently.
Parameters
| Item | Description |
|---|---|
| TARGET CONTEXT | The dsh command target context is the database where the target or target group is defined. A default context can be configured using the -C context flag or the DSH CONTEXT environment variable. If either parameter is not specified, the default context is NIM when the dsh command is run from a NIM management server, else the default context is DSH (see DSH CONTEXT). A context is used with a DSH Utilities command by installing a context extension file in the /opt/ibm/sysmgt/dsm/pm/Context directory. The target or target group context can be explicitly specified by qualifying a target name with a context name, or implicitly defined by specifying a default context for unqualified target names (see Target list). |
| DSH CONTEXT | The DSH CONTEXT is the in-built context for all the DSH Utilities commands. It permits a user-defined node group database contained in the local file system. The DSH_NODEGROUP_PATH environment variable specifies the path to the node group database. Each file in this directory represents a node group, and contains one host name or TCP/IP address for each node that is a group member. Blank lines and comment lines beginning with a # symbol are ignored. If all nodes are requested for the DSH CONTEXT, a full node list is built from all groups in the DSH_NODEGROUP_PATH directory, and cached in /var/ibm/sysmgt/dsm/dsh/$DSH_NODEGROUP_PATH/AllNodes. This file is recreated each time a group file is modified or added to the DSH_NODEGROUP_PATH directory. Device targets are not supported in the DSH context. |
| TARGET SPECIFICATION | A target is a node or hardware device where a remote command is issued. Node
targets are specified using the -a, --all-nodes context_list, -n
node_list and -N
nodegroups flags, or the DSH_NODE_LIST environment variable. If
both the -N flag and the DSH_NODE_LIST environment variable are used,
the groups and lists are merged eliminating any duplicates. Note: The DSH_NODE_LIST
environment variable has replaced WCOLL.
Device targets are specified using the -A,
--all-devices
context_list, -d
device_list and -D
devicegroups flags, or the DSH_DEVICE_LIST environment variable. If the local host is
included as part of the targets, the command_list is run directly on the local host and not
through the configured remote shell, unless a user_ID is specified for execution with the
local host (see Remote user). The DSH_NODE_LIST and DSH_DEVICE_LIST environment
variables specify files listing target nodes and devices. The file format is 1 target per line.
Blank lines and comment lines beginning with a # symbol are ignored. Both node and device targets
can be specified simultaneously, but the same target name cannot be used for both a device and a
node. If a similar name is used, the program skips the duplicate targets, and continues execution on
the other targets. Node and device targets can also be specified using node ranges; see the
noderange file for details. If the same target is specified more than one time, the
remote command is run one time on the specified target. |
| TARGET LIST | Target and target groups are specified using the following
format: [context:] [user_ID@] target [, [ context:] [user_ID@] target]... where context is the explicit context specification for the target, user_ID is the optional user name to use when remotely running the command on the target, and target is the name or TCP/IP address of the target as permitted by the target's context. For a noderange expression, the user_ID is used for each target in the list that results from the evaluation of the noderange expression. If the target list is only specified with a dash (-), targets can be specified interactively. For nodes, the prompt is dsh node>; and for devices the prompt is dsh device>. Specify the target list using the following syntax on 1 line at a time: [context:] [user_ID@] target where context is the explicit context specification for the target, user_ID is the optional user name to use when remotely running the command on the target, and target is the name or TCP/IP address of the target as permitted by the context of the target. For a noderange expression, the user_ID is used for each target in the list that results from the evaluation of the noderange expression. If the target list is only specified with a dash (-), targets can be specified interactively. For nodes, the prompt is dsh node>; for devices the prompt is dsh device>. Specify the target list using the following syntax on 1line at a time:[context:][user_ID@]target When you are finished, press Ctrl-d to continue. |
| COMMAND SPECIFICATION | The commands to run on the remote targets are specified by
the command_list dsh parameter, entering commands on the command
line in interactive mode, providing a command_list through
standard input, or running a local script using the -e flag.
The syntax for the command_list dsh parameter is as follows:
"command[; command]..." where command is the command to
run on the remote target. Quotation marks are required to ensure that
all commands in the list are run remotely, and that any special characters
are interpreted correctly on the remote target. A script file on the
local host is run on each of the remote targets by using the -e flag. If -e is specified, command_list is the script
name and arguments to the script. For example: |
| REMOTE USER | The user_ID to use for a remote target
can be specified as part of the target syntax (see Target lists) or using the -l (lowercase L) flag. If both methods are used, the user_ID is determined as follows:
|
| REMOTE SHELL COMMAND | The commands to run on the remote targets are specified by the command_list dsh parameter, entering commands on the command line in interactive mode, providing a command_list through standard input, or executing a local script using the -e flag. The syntax for the command_list dsh parameter is as follows: "command[; command]..." where command is the command to run on the remote target. Quotation marks are required to ensure that all commands in the list are run remotely, and that any special characters are interpreted correctly on the remote target. A script file on the local host can be run on each of the remote targets by using the -e flag. If -e is specified, command_list is the script name and arguments to the script. For example: dsh -e[flags] script_filename [arguments]... The script_filename file is copied to a random file name in the /tmp directory on each remote target and then run on the targets. If the command_list parameter is not specified, dsh enters interactive command-line mode and the dsh> prompt is displayed. Enter commands at the dsh> prompt using the following syntax: [!] "command", where command is the command to run on the remote target. An exclamation point (!) preceding a command causes the command to run on the local host only, and not to any remote targets. The dsh command runs each command to each resolved target, the results are displayed and returns to the dsh> prompt. To exit command-line mode, enter exit at the dsh> prompt. The dsh command does not work with any interactive commands, including those commands that read from standard input. |
| REMOTE USER | The user_ID to use for a remote target
can be specified as part of the target syntax (see Target lists) or using the -l (lowercase L) flag. If both methods are used, the user_ID is
determined as follows:
|
| REMOTE SHELL ENVIRONMENT | The shell environment used on the remote target defaults to the shell defined for the user_ID used for remote command execution. The command syntax used for remote command execution can be specified using the -S flag. If -S is not specified, the syntax defaults to ksh syntax. When commands are run on the remote target, the path used is determined by the DSH_PATH environment variable defined in the shell of the current user. If DSH_PATH is not set, the path used is the remote shell default path. For example, to set the local path for the remote targets, use: DSH_PATH=$PATH. The -E flag exports a local environment definition file to each remote target. Environment variables specified in this file are defined in the remote shell environment before the command_list is run. |
| COMMAND EXECUTION | The maximum concurrent remote shell command
processes (the fanout) can be specified with the -f flag or
with the DSH_FANOUT environment variable. The fanout is restricted
by the number of remote shell commands that can be run in parallel.
You can experiment with the DSH_FANOUT value on your management
server to see if higher values are appropriate. A timeout value for
remote command execution can be specified with the -t flag
or with the DSH_TIMEOUT environment variable. If any remote
target does not provide output to either standard output or standard
error within the timeout value, an error message is displayed by the
dsh command and exits. If streaming mode is specified with the -s flag, the output is returned as it becomes available from
each target. This process does not wait for the command_list to complete on all targets before returning output. This can improve
performance but causes the output to be unsorted. The -z flag
is used to display the exit code from the last command issued on the
remote node in command_list. Note: OpenSSH returns the exit
status of the last remote command issued as its exit status.
This affects the behavior of dsh and requires using the -c flag. If the command issued on the remote node is run in the background,
the command does not display the exit status. The -m flag monitors
execution of the dsh command by printing status messages to standard
output. Each status message is preceded by dsh>. The -T flag
provides diagnostic trace information for the execution of the dsh
command. Default settings and the actual remote shell commands
run on the remote targets are shown. No error detection or recovery
mechanism is provided for remote targets. The dsh command output to
standard error and standard output can be analyzed to determine the
appropriate course of action. In interactive mode, if a command cannot
be run on a remote target (for example, a remote shelll command
resulting in 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. |
| COMMAND OUTPUT | The dsh command waits to display the output from each remote shell process and then initiates a new remote shell process. This default behavior is overridden by the -s flag. The dsh command output consists of standard error and standard output from the remote commands. The dsh standard output is the standard output from the remote shell command. The dsh standard error is the standard error from the remote shell command. Each line is prefixed with the host name of the node that produced the output. The host name is followed by the: character and a command output line. A filter to display identical outputs grouped by node is provided separately. See the dshbak command for more information. Output for each target can be copied to a file using the -F output_path flag. Standard output for each target is written to the target.output file in the output_path directory, and standard error for each target is written to the target.error file in the output_path directory. The -F flag does not suppress output on the console. A command can be run silently using the -Q flag; no output from each target’s standard output or standard error is displayed. If the -F flag is specified, output continues to be written to output files. |
| REPORTING | Output from the dsh command can be saved to a report on the local host. The --report report_path flag enables report generation to the specified report_path directory. Reporting is activated by defining the DSH_REPORT environment variable with the report_path. The --report flag overrides the DSH_REPORT environment variable. The --report-name flag defines a report name, if reporting is activated. The report name is also the subdirectory of report_path that contains the report files. A numeric index is appended to the subdirectory name to allow multiple reports with the same name. If the --report-name flag is not used, the name defaults to Unspecified. Summary HTML and XML report files are created, in addition to an XML results file. SIGNALS: Signal 2 (INT), Signal 3 (QUIT), and Signal 15 (TERM) are propagated to the commands executing on the remote targets. Signal 19 (CONT), Signal 17 (STOP), and Signal 18 (TSTP) default to dsh; the dsh command responds normally to these signals, but the signals does not affect on the remotely executing commands. Other signals are determined by dsh and have their default effects on the dsh command; all current child processes, through propagation to remotely running commands, are terminated (SIGTERM). Parameters command_list Specifies a list of commands to execute on the remote targets. The syntax for the command_list parameter is as follows: " command[; command..." |
Keywords
| Item | Description |
|---|---|
| -a | Includes in the target list all nodes that are defined in the default context. The default context can be set using the -C flag or the DSH_CONTEXT environment variable. |
| -A | Includes in the target list all devices that are defined in the default context. The default context can be set using the -C flag or the DSH_CONTEXT environment variable. This flag is disabled on HMCs. |
| --all-nodescontext_list | Includes in the target list all nodes defined in the contexts listed in context_list. The default context is not implicitly included in this list. This flag is disabled on HMC. --all-nodes. |
| --all-devices context_list | Includes in the target list all devices that are defined in the contexts listed in context_list. The default context is not implicitly included in this list. This flag is disabled on HMCs. |
| -C | --continue | In interactive mode only, keeps a node in the target list even if the remote shell command for the host has a non-zero exit value. |
| -C| --contextcontext | The default context to use when resolving target names. The context value must correspond to a valid context extension module in the /opt/ibm/sysmgt/dsm/pm/Context directory. For example, the /opt/ibm/sysmgt/dsm/pm/Context/DSH.pm file is the module for the DSH context. |
| -d | --devices device_list | Specifies a list of device targets to include
in the target list. The device_list syntax is: [context:][user_ID@]device_name[,[context:]\ [user_ID@]device_name]... This flag is disabled on HMCs. |
| --device-rshdevice_remote_shell | Specifies the full path of the remote shell
command used for remote command execution on device targets. A remote
shell for a specific context can be defined by including context:
before the path. The device_remote_shell syntax is: [context:]path[,[context:]path]... This flag is disabled on HMCs. - |
| -D | --devicegroups devicegroups | Includes in the target list all devices defined
in the device groups specified in the devicegroups list. The devicegroups syntax is: [context:] [user_ID@]devicegroup[,[context:]\ [user_ID@]devicegroup]... This flag is disabled on HMCs. |
| -e | --execute | Indicates that command_list specifies a local script filename and arguments to be executed on the remote targets. The script file is copied to the remote targets and then remotely executed with the given arguments. The DSH_NODE_RCP and DSH_DEVICE_RCP environment variables specify the remote copy command to use to copy the script file to node and device targets, respectively. |
| -E | --environment environment_file | Specifies that the environment_file contains environment variable definitions to export to the target before executing thecommand_list. The DSH_NODE_RCP and DSH_DEVICE_RCP environment variables specify the remote copy command to use to export the file to node and device targets, respectively. |
| -f | --fanout fanout_value | Specifies a fanout value for the maximum number of concurrently executing remote shell processes. Serial execution can be specified by indicating a fanout value of 1. If -f is not specified, a default fanout value of 64 is used. |
| -F | --output output_path | Copies standard output to output_path/target_name.output and standard error to output_path/target_name.error. Output continues to be sent to standard output and standard error. Use the -Q flag to suppress standard output and standard error. |
| -i | --notify | Indicates that a target is not responding and prompts to continue remote execution for the target. Specify the -v flag with the -i flag. |
| -l (lowercase L) |--user user_ID | Specifies a remote user name to use for remote command execution. |
| -h | --help | Displays command usage information. |
| -n | --nodes node_list | Specifies a list of node targets to include
in the target list. The node_list syntax is: [context:] [user_ID@]node_name[, [context:]\ [user_ID@]node_name]... |
| -L | --no-locale | Specifies to not export the locale definitions of the local host to the remote targets. Local host locale definitions are exported by default to each remote target. Output is appended to the file for each execution of the dsh command. |
| --log log_file | Enables logging to the specified log_file |
| -m | --monitor | Monitors remote shell execution by displaying status messages during execution on each target. |
| -N | --nodegroups nodegroups | Includes in the target list all nodes defined
in the node groups specified in the nodegroups list. The syntax
of nodegroups is: [context:] [user_ID@] nodegroup [, [context:]\ [user_ID@]nodegroup]... |
| -o--node-options node_options | Specifies options to pass to the remote shell
command for node targets. The options must be specified within
double quotation marks ("") to distinguish them from dsh options.
Options for nodes in a specific context can be defined by including
a context: before the option list. The syntax for node_options is: [context:]" options "[,[context:]"options"]... |
| -O | --device-options device_options | Specifies options to pass to the remote shell
command for device targets. The options must be specified within
double quotation marks to distinguish them from dsh options. Options
for devices in a specific context can be defined by including context:
before the option list. The syntax for device_options is [context:]"options"[,[context:]"options"]... This flag is disabled on HMCs. |
| -Q |--silent | Specifies silent mode. No target output is written to standard output or standard error. Monitoring messages are written to standard output. |
| -q | --show-config | Displays the current environment settings relevant to all DSH Utilities commands. This includes the values of all environment variables and settings for all currently installed and valid contexts. Each setting is prefixed with context: to identify the source context of the setting. |
| -r | --node-rsh node_remote_copy | Specifies the full path of the remote shell
command used to copy files to or from node targets. A remote
shell command for a specific context can be defined by including
context: before the path. The node_remote_copy syntax is: [context:]path[,[context:]path]... If path contains rsync, it is assumed that the rsync command performs the remote copy. |
| --report report_path | Enables report generation and specifies the path to the directory where reports are saved. --report-name report_name Specifies the name to use when generating the report. If not specified, the name defaults to Unspecified. This flag can only be used with the --report flag. |
| -s| --stream | Specifies to return output as it becomes available from each target. It does not wait for the command_list to complete on a target before returning output. |
| -S | --syntax csh | ksh | Specifies the shell syntax to be used on the remote target. If not specified, the ksh syntax is used. |
| -t |--timeouttimeout | Specifies the time, in seconds, to wait for output from any currently executing remote targets. If no output is available from any target in the specified timeout, an error message is displayed by the dsh command and terminates execution to the remote targets that failed to respond. If timeout is not specified, dsh waits indefinitely to continue processing output from all remote targets. When specified with the -i flag, the user is prompted for an additional timeout interval to wait for output. |
| -T | --trace | Enables trace mode. The dsh command prints diagnostic messages to standard output during execution to each target. |
| -v | --verify | Verifies each target before executing any remote commands on the target. If a target is not responding, execution of remote commands for the target is canceled. When specified with the -i flag, the user is prompted to retry the verification request. |
| -X env_list | Ignores dsh environment variables. This option can take an argument which is a comma-separated list of environment variable names that must NOT be ignored. If there is no argument to this option, or the argument is an empty string, all dsh environment variables are ignored. This flag cannot be specified as the last flag. |
| -V | --version | Displays version information for the dsh command. |
| Item | Description |
|---|---|
| -z | --exit-status | Displays the exit status for the last remotely executed non-asynchronous command on each target. If the command issued on the remote node is run in the background, the exit status is not displayed. Exit Status Exit values for each remote shell execution are displayed in messages from the dsh command, if the remote shell exit values are non-zero. A non-zero return code from a remote shell indicates that an error was encountered in the remote shell. This return code is unrelated to the exit code of the remotely issued command. If a remote shell encounters an error, execution of the remote command on that target is bypassed. The dsh command exit code is 0 if the command executed without errors and all remote shell commands finished with exit codes of 0. |
| If internal dsh errors occur or the remote shell commands do not complete successfully, the dsh command exit value is greater than 0. The exit value is increased by 1 for each successive instance of an unsuccessful remote command execution. If the remotely issued command is run in the background, the exit code of the remotely issued command is 0. Environment Variables DSH_CONTEXT Specifies the default context to use when resolving targets. This variable is overridden by the -C flag. DSH_DEVICE_LIST Specifies a file that contains a list of device targets. | |
| This variable is overridden by the -d flag. This environment variable is ignored on HMCs. DSH_DEVICE_OPTS Specifies the options to use for the remote shell command with device targets only. This variable is overridden by the -O flag. This environment variable is ignored on HMCs. DSH_DEVICE_RCP Specifies the full path of the remote copy command used to copy local scripts and local environment configuration files to device targets. | |
| This environment variable is ignored on HMCs. DSH_DEVICE_RSH Specifies the full path of the remote shell to use for remote command execution on device targets. This variable is overridden by the --device-rsh flag. This environment variable is ignored on HMCs. DSH_ENVIRONMENT Specifies a file that contains environment variable definitions to export to the target before executing the remote command. This variable is overridden by the -E flag. DSH_FANOUT Specifies the fanout value. | |
| This variable is overridden by the -f flag. DSH_LOG Specifies the full path of the file to use for logging. This variable is overridden by the --log flag. DSH_NODE_LIST Specifies a file containing a list of node targets. The DSH_NODE_LIST variable has replaced WCOLL.Hel DSH_NODE_OPTS . Specifies the options to use for the remote shell command with node targets only. This variable is overridden by the -o flag. DSH_NODE_RCP | |
| Specifies the full path of the remote copy command to use to copy local scripts and local environment configuration files to node targets. DSH_NODE_RSH Specifies the full path of the remote shell to use for remote command execution on node targets. This variable is overridden by the -r flag. DSH_NODEGROUP_PATH Specifies a colon-separated list of directories that contain node group files for the DSH context. When the -a flag is specified in the DSH context, a list of unique node names is collected from all node group files in the path. DSH_OUTPUT . | |
| Specifies the base file name for standard output and standard error copies. Output continues to be sent to standard output and standard error. This variable is overridden by the -F flag. DSH_PATH Sets the command path to use on the targets. If DSH_PATH is not set, the default path defined in the profile of the remote user_ID is used. DSH_PATH cannot be used to run a dsh command to an HMC. DSH_REPORT. | |
| Enables reporting when set to the absolute path of the directory where reports are saved. This variable is overridden by the --report flag. DSH_SYNTAX Specifies the shell syntax to use on remote targets; ksh or csh. If not specified, the ksh syntax is assumed. This variable is overridden by the -S flag. DSH_TIMEOUT Specifies the time, in seconds, to wait for output from each remote target. This variable is overridden by the -t flag. Security The dsh command has no security configuration requirements. All remote command security requirements - configuration, authentication, and authorization - are imposed by the underlying remote command configured for dsh. | |
| The command assumes that authentication and authorization are configured between the local host and the remote targets. Interactive password prompting is not supported; an error is displayed and execution is bypassed for a remote target if password prompting occurs, or if either authorization or authentication to the remote target fails. Security configurations as they pertain to the remote environment and remote shell command are user-defined. When the remote command is configured as /usr/bin/rsh and this command is configured to use Kerberos Version 5, you must first run the Kerberos kinit command to obtain a ticket-granting ticket, and you must ensure that your Kerberos principal is in the. k5login file in the home directory of the remote user on the targets. |
Examples
- To run the ps command on node targets node1 and node2, enter:
dsh -n node1,node2 "ps" - To run the ps command on each node target listed in the myhosts file, enter:
DSH_NODE_LIST=./myhosts; dsh ps - To enter commands in interactive mode for execution on the node
targets defined in NodeGroup1, enter:
dsh -N NodeGroup1 - To display the number of users on all NIM Managed nodes and in
the DSH context node group NodeGroup2, enter:
dsh --all-nodes NIM -N DSH:NodeGroup2 "who | wc -l" - To enter a list of node targets and device targets interactively
and then execute the date command in interactive mode, enter:
Additional input and the output similar to the following is displayed:dsh -n - -d -dsh node> node1 dsh node> gregb@node2 dsh node> dsh device> CSM:kathyc@device1 dsh device> dsh> date node1: Wed Apr 13 17:15:59 EDT 2005 gregb@node2: Wed Apr 13 17:15:59 EDT 2005 kathyc@device1: Wed Apr 13 17:15:59 EDT 2005 dsh> exit # - To run the ls command on all the nodes in the cluster and
ignore all the dsh environment variables, enter:
dsh -X -a ls - To run the ps command on node1 and ignore all the
dsh environment variables except the DSH_NODE_OPTS, enter:
dsh -n node1 -X ’DSH_NODE_OPTS’ ps