xcat-core/xCAT-client-2.0/share/man/man1/xdsh.1

.TH xdsh 12/13/07
xdsh Command
.PP
\fBPurpose
\fR
.PP
\fBxdsh\fR - Concurrently runs commands on multiple nodes.
.PP
\fBSyntax
\fR
.PP
\fBxdsh\fR \fB-h\fR
.PP
\fBxdsh\fR \fB-V\fR
.PP
\fBxdsh\fR \fB-q\fR
.PP
\fBxdsh\fR [[\fInode_list\fR]| [\fInodegroup\fR]]
[\fB-B\fR \fIbypass\fR]
[\fB-C\fR \fIcontext\fR] [\fB-e\fR]
[\fB-E\fR \fIenvironment_file\fR] [\fB-f\fR\fIfanout\fR]
[\fB-i\fR] [\fB-K\fR] [\fB-L\fR] [\fB-l\fR \fIuser_ID\fR] 
[\fB-m\fR] [\fB-o\fR \fInode_options\fR] 
[\fB-Q\fR] [\fB-r\fR \fInode_remote_shell\fR]
[\fB-s\fR] [\fB-S\fR \fBcsh\fR | \fBksh\fR] [\fB-t\fR \fItimeout\fR]
[\fB-T\fR] [\fB-v\fR] [\fB-X\fR \fIenv_list\fR] [\fB-z\fR] 
[\fIcommand_list\fR]
.PP
.PP
\fBDescription
\fR
.PP
The \fBxdsh\fR command runs commands concurrently on remote nodes. 
Targets can be selected from  multiple contexts.
A context is a target database that contains the node definition. 
The \fBxdsh\fR command issues a remote shell command for each 
target specified, and returns the output from all targets,
 formatted so that command results from all nodes
can be managed. \fB/usr/bin/rsh\fR is the model for the syntax and
security. The \fBxdsh\fR command is a xCAT Distributed Shell
Utility.
.PP
\fBTARGET CONTEXT\fR:
.PP
The \fBxdsh\fR command target context is the database where the target or
target group is defined. A default context can be configured using the
\fB-C\fR \fIcontext\fR flag or the \fBDSH_CONTEXT\fR
environment variable. If neither are specified, the default context is
\fBXCAT\fR.
.PP
A context is enabled for use with a DSH Utilities command by installing a
context extension file in the \fB/opt/xcat/xdsh/Context\fR
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
\fBTarget lists\fR).
.PP
\fBTARGET SPECIFICATION\fR:
.PP
A target is a node where a remote command will be
executed. Node targets are specified inputting the 
\fInode_list\fR or \fInodegroups\fR, or the
\fBDSH_NODE_LIST\fR environment variable. 
.PP
If the local host is included as part of the targets, the
\fIcommand_list\fR is executed directly on the local host and not through
the configured remote shell, unless a \fIuser_ID\fR is specified for
execution with the local host (see \fBRemote user\fR).
.PP
The \fBDSH_NODE_LIST\fR environment
variable specify the file listing the target nodes. The file
format is one target per line. Blank lines and comment lines beginning
with \fB#\fR are ignored.
.PP
Node targets can also be specified using node
ranges as supported by xCAT. If the same
target is specified more than once, the remote command will only be executed
once on the specified target.
.PP
\fBCOMMAND SPECIFICATION\fR:
.PP
The commands to execute on the remote targets are specified by the
\fIcommand_list\fR \fBxdsh\fR parameter,
or executing a local script using the \fB-e\fR
flag.
.PP
The syntax for the \fIcommand_list\fR \fBxdsh\fR parameter is as
follows: 
.sp
.nf
"\fIcommand\fR[; \fIcommand\fR]..."\ 
.fi
.sp
.PP
where \fIcommand\fR is the command to run on the remote
target. Quotation marks are required to ensure that all commands in the
list are executed remotely, and that any special characters are interpreted
correctly on the remote target. A script file on the local host can be
executed on each of the remote targets by using the \fB-e\fR
flag. If \fB-e\fR is specified, \fIcommand_list\fR is the
script name and arguments to the script. For example: 
.sp
.nf
xdsh hostname -e [\fIflags\fR] \fIscript_filename\fR [\fIarguments\fR]...
.fi
.sp
.PP
The \fIscript_filename\fR file is copied to a random filename in the
\fB/tmp\fR directory on each remote target and then executed on the
targets.
.PP
The \fBxdsh\fR command does not work with any interactive commands,
including those that read from standard input.
.PP
\fBREMOTE USER\fR:
.PP
The \fIuser_ID\fR to use for a remote target can be specified 
using the \fB-l\fR (lowercase L) flag. 
.PP
\fBREMOTE SHELL COMMAND\fR:
.PP
The \fBxdsh\fR command uses a configurable remote shell command to
execute remote commands on the remote targets. Support is explicitly
provided for AIX Remote Shell and OpenSSH, but any secure remote command that
conforms to the IETF (Internet Engineering Task Force) Secure Remote Command
Protocol can be used.
.PP
The remote shell is determined as follows, in order of
precedence: 
.RS +3
.HP 3
1. The \fB-r\fR flag.
.HP 3
2. The \fBDSH_NODE_RSH\fR environment variable.
.HP 3
3. The default node remote shell as defined by the target
\fIcontext\fR.
.HP 3
4. The \fB/usr/bin/rsh\fR command.
.RE
.PP
The remote shell options are determined as follows, in
order of precedence: 
.RS +3
.HP 3
1. The \fB-o\fR flag.
.HP 3
2. The \fBDSH_NODE_OPTS\fR environment variable.
.RE
.PP
\fBREMOTE SHELL ENVIRONMENT\fR:
.PP
The shell environment used on the remote target defaults to the shell
defined for the \fIuser_ID\fR used for remote command execution.
The command syntax used for remote command execution can be specified using
the \fB-S\fR flag. If \fB-S\fR is not specified, the
syntax defaults to \fBksh\fR syntax.
.PP
When commands are executed on the remote target, the path used is
determined by the \fBDSH_PATH\fR environment variable defined in the shell
of the current user. If \fBDSH_PATH\fR is not set, the path used is
the remote shell default path. For example, to set the local path for
the remote targets, use: 
.sp
.nf
DSH_PATH=$PATH
.fi
.sp
.PP
The \fB-E\fR 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 \fIcommand_list\fR is
executed.
.PP
\fBCOMMAND EXECUTION\fR:
.PP
The maximum number of concurrent remote shell command processes (the
fanout) can be specified with the \fB-f\fR flag or with the
\fBDSH_FANOUT\fR environment variable. The fanout is only restricted by the number of remote shell commands
that can be run in parallel. You can experiment with the
\fBDSH_FANOUT\fR value on your management server to see if higher values
are appropriate.
.PP
A timeout value for remote command execution can be specified with the
\fB-t\fR flag or with the \fBDSH_TIMEOUT\fR environment
variable. If any remote target does not provide output to either
standard output or standard error within the timeout value, \fBxdsh\fR
displays an error message and exits.
.PP
If streaming mode is specified with the \fB-s\fR flag, output is
returned as it becomes available from each target, instead of waiting for the
\fIcommand_list\fR to complete on all targets before returning
output. This can improve performance but causes the output to be
unsorted.
.PP
The \fB-z\fR flag displays the exit code from the last command
issued on the remote node in \fIcommand_list\fR. Note that OpenSSH
behaves differently; it returns the exit status of the last remote
command issued as its exit status. This affects the behavior of
\fBxdsh\fR and may require using the \fB-c\fR flag. If the
command issued on the remote node is run in the background, the exit status is
not displayed.
.PP
The \fB-m\fR flag monitors execution of the \fBxdsh\fR command
by printing status messages to standard output. Each status message is
preceded by \fBdsh>\fR.
.PP
The \fB-T\fR flag provides diagnostic trace information for the
execution of the \fBxdsh\fR command. Default settings and the actual
remote shell commands executed on the remote targets are displayed.
.PP
No error detection or recovery mechanism is provided for remote
targets. The \fBxdsh\fR 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 executed on a remote target (for
example, a remote shell command resulting in a non-zero return code),
subsequent commands are not sent to this node on this invocation of the
\fBxdsh\fR command unless the \fB-c\fR flag is specified.
.PP
\fBCOMMAND OUTPUT\fR:
.PP
The \fBxdsh\fR command waits until complete output is available from each
remote shell process and then displays that output before initiating new
remote shell processes. This default behavior is overridden by the
\fB-s\fR flag.
.PP
The \fBxdsh\fR command output consists of standard error and standard
output from the remote commands. The \fBxdsh\fR standard output is
the standard output from the remote shell command. The \fBxdsh\fR
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 \fB:\fR character and
a command output line. A filter for displaying identical outputs
grouped by node is provided separately. See the \fBxdshbak\fR command
for more information.
.PP
A command can be run silently using the \fB-Q\fR flag; no
output from each target's standard output or standard error is
displayed. 
.PP
\fBSIGNALS\fR:
.PP
Signal 2 (INT), Signal 3 (QUIT), and Signal 15 (TERM) are propagated to the
commands executing on the remote targets.
.PP
Signal 19 (CONT), Signal 17 (STOP), and Signal 18 (TSTP) default to
\fBxdsh\fR; the \fBxdsh\fR command responds normally to these
signals, but the signals do not have an effect on remotely executing
commands. Other signals are caught by \fBxdsh\fR and have their
default effects on the \fBxdsh\fR command; all current child processes,
through propagation to remotely running commands, are terminated
(SIGTERM).
.PP
.PP
\fBParameters
\fR
.RS +3
\fB\fIcommand_list\fR
\fR
.RE
.RS +9
Specifies a list of commands to execute on the remote targets. The
syntax for the \fIcommand_list\fR parameter is as follows:
.sp
.nf
"\fIcommand\fR[; \fIcommand\fR..."
.fi
.sp
.RE
.PP
.RE
.RS +3
\fInode_list\fR
\fR
.RE
.RS +9
Specifies a list of node targets to include in the target list. 
.sp
.RE
.RS +3
\fInodegroups\fR
.RS +9
Includes in the target list all nodes defined in the node groups specified
in the \fInodegroups\fR list.
\fR
.RE
\fBFlags
\fR
.RS +3
\fB-C | --context \fIcontext\fR
\fR
.RE
.RS +9
The default context to use when resolving target names. The
\fIcontext\fR value must correspond to a valid context extension module
in the \fB/opt/xcat/xdsh/Context\fR directory. For example, the
\fB/opt/xcat/xdsh/Context/DSH.pm\fR file is the module for the
\fBDSH\fR context.
.RE
.RS +3
\fB-e | --execute
\fR
.RE
.RS +9
Indicates that \fIcommand_list\fR 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 \fBDSH_NODE_RCP\fR
environment variables specify the remote copy command to use to copy the
script file to node targets.
.RE
.RS +3
\fB-E | --environment \fIenvironment_file\fR
\fR
.RE
.RS +9
Specifies that the \fIenvironment_file\fR contains environment
variable definitions to export to the target before executing the
\fIcommand_list\fR. The \fBDSH_NODE_RCP\fR and
environment variables specify the remote copy command
to use to export the file to node targets.
.RE
.RS +3
\fB-f | --fanout \fIfanout_value\fR
\fR
.RE
.RS +9
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 \fB1\fR. If \fB-f\fR is not specified, a
default fanout value of \fB64\fR is used.
.RE
.RS +3
\fB-h | --help
\fR
.RE
.RS +9
Displays usage information.
.RE
.RS +3
\fB-K | --ssh-setup  
\fR
.RE
.RS +9
Request to setup SSH for the input node list.
.RE
.RS +3
\fB-l | --user \fIuser_ID\fR
\fR
.RE
.RS +9
Specifies a remote user name to use for remote command execution.
.RE
.RS +3
\fB-L | --no-locale
\fR
.RE
.RS +9
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.
.RE
.RS +3
\fB-m | --monitor
\fR
.RE
.RS +9
Monitors remote shell execution by displaying status messages during
execution on each target.
.RE
.RS +3
\fB-o | --node-options \fInode_options\fR
\fR
.RE
.RS +9
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 \fBxdsh\fR options. 
The syntax for \fInode_options\fR
.RE
.RS +3
\fB-q | --show-config
\fR
.RE
.RS +9
Displays the current environment settings for 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 \fIcontext\fR: to identify the source context of
the setting.
.RE
.RS +3
\fB-Q | --silent
\fR
.RE
.RS +9
Specifies silent mode. No target output is written to standard
output or standard error. Monitoring messages are written to standard
output.
.RE
.RS +3
\fB-r | --node-rsh \fInode_remote_shell\fR
\fR
.RE
.RS +9
Specifies the full path of the remote shell command used for remote
command execution on node targets. 
.sp
.nf
 [\fIcontext\fR:]\fIpath\fR[,[\fIcontext\fR:]\fIpath\fR]...
.fi
.sp
.RE
.RS +3
\fB-s | --stream
\fR
.RE
.RS +9
Specifies that output is returned as it becomes available from each
target, instead of waiting for the \fIcommand_list\fR to be completed on
a target before returning output.
.RE
.RS +3
\fB-S | --syntax csh | ksh
\fR
.RE
.RS +9
Specifies the shell syntax to be used on the remote target. If not
specified, the \fBksh\fR syntax is used.
.RE
.RS +3
\fB-t | --timeout \fItimeout\fR
\fR
.RE
.RS +9
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 \fItimeout\fR, \fBxdsh\fR displays an error and
terminates execution for the remote targets that failed to respond. If
\fItimeout\fR is not specified, \fBxdsh\fR waits indefinitely to
continue processing output from all remote targets. When specified with
the \fB-i\fR flag, the user is prompted for an additional timeout
interval to wait for output.
.RE
.RS +3
\fB-T | --trace
\fR
.RE
.RS +9
Enables trace mode. The \fBxdsh\fR command prints diagnostic
messages to standard output during execution to each target.
.RE
.RS +3
\fB-v | --verify
\fR
.RE
.RS +9
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 \fB-i\fR flag,
the user is prompted to retry the verification request.
.RE
.RS +3
\fB-V | --version
\fR
.RE
.RS +9
Displays \fBxdsh\fR command version information.
.RE
.RS +3
\fB-X \fIenv_list\fR
\fR
.RE
.RS +9
Ignore \fBxdsh\fR environment variables. This option can take an argument which is a comma separated list of environment variable names that should \fBNOT\fR be ignored. If there is no argument to this option, or the argument is an empty string, all \fBxdsh\fR environment variables will be ignored.
.RE
.RS +3
\fB-z | --exit-status
\fR
.RE
.RS +9
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.
.RE
.PP
.PP
\fBExit Status
\fR
.PP
Exit values for each remote shell execution are displayed in messages from
the \fBxdsh\fR 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.
.PP
The \fBxdsh\fR command exit code is \fB0\fR if the command executed
without errors and all remote shell commands finished with exit codes of
\fB0\fR. If internal \fBxdsh\fR errors occur or the remote shell
commands do not complete successfully, the \fBxdsh\fR command exit value is
greater than \fB0\fR. The exit value is increased by \fB1\fR 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 \fB0\fR.
.PP
.PP
\fBEnvironment Variables
\fR
.RS +3
\fBDSH_CONTEXT
\fR
.RE
.RS +9
Specifies the default context to use when resolving targets. This
variable is overridden by the \fB-C\fR flag.
.RE
.RS +3
\fBDSH_ENVIRONMENT
\fR
.RE
.RS +9
Specifies a file that contains environment variable definitions to export
to the target before executing the remote command. This variable is
overridden by the \fB-E\fR flag.
.RE
.RS +3
\fBDSH_FANOUT
\fR
.RE
.RS +9
Specifies the fanout value. This variable is overridden by the
\fB-f\fR flag.
.RE
.RS +3
\fBDSH_NODE_LIST
\fR
.RE
.RS +9
Specifies a file containing a list of node targets. 
.RE
.RS +3
\fBDSH_NODE_OPTS
\fR
.RE
.RS +9
Specifies the options to use for the remote shell command with node
targets only. This variable is overridden by the \fB-o\fR
flag.
.RE
.RS +3
\fBDSH_NODE_RCP
\fR
.RE
.RS +9
Specifies the full path of the remote copy command to use to copy local
scripts and local environment configuration files to node targets.
.RE
.RS +3
\fBDSH_NODE_RSH
\fR
.RE
.RS +9
Specifies the full path of the remote shell to use for remote command
execution on node targets. This variable is overridden by the
\fB-r\fR flag.
.RE
.RS +3
\fBDSH_NODEGROUP_PATH
\fR
.RE
.RS +9
Specifies a colon-separated list of directories that contain node group
files for the \fBDSH\fR context. When the \fB-a\fR flag is
specified in the \fBDSH\fR context, a list of unique node names is
collected from all node group files in the path.
.RE
.RS +3
\fBDSH_PATH
\fR
.RE
.RS +9
Sets the command path to use on the targets. If \fBDSH_PATH\fR
is not set, the default path defined in the profile of the remote
\fIuser_ID\fR is used. 
.RE
.RS +3
\fBDSH_SYNTAX
\fR
.RE
.RS +9
Specifies the shell syntax to use on remote targets; \fBksh\fR or
\fBcsh\fR. If not specified, the \fBksh\fR syntax is
assumed. This variable is overridden by the \fB-S\fR
flag.
.RE
.RS +3
\fBDSH_TIMEOUT
\fR
.RE
.RS +9
Specifies the time, in seconds, to wait for output from each remote
target. This variable is overridden by the \fB-t\fR
flag.
.RE
.PP
.PP
\fBSecurity
\fR
.PP
The \fBxdsh\fR command has no security configuration requirements.
All remote command security requirements - configuration,
authentication, and authorization - are imposed by the underlying remote
command configured for \fBxdsh\fR. The command assumes that
authentication and authorization is 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.
.PP
.PP
\fBExamples
\fR
.PP
.RS +3
.HP 3
1. To run the \fBps\fR command on node targets \fBnode1\fR and
\fBnode2\fR, enter: 
.sp
.nf
xdsh node1,node2 "ps"
.fi
.sp
.HP 3
2. To run the \fBps\fR command on each node target listed in the
\fBmyhosts\fR file, enter: 
.sp
.nf
DSH_NODE_LIST=./myhosts; xdsh ps
.fi
.sp
.HP 3
3. To execute the commands contained in \fBmyfile\fR in the XCAT 
\fBcontext\fR on several node targets,
with a fanout of \fB1\fR,
enter: 
.sp
.nf
xdsh node1,node2 -C XCAT -f 1 -e myfile
.fi
.sp
.HP 3
4. To run the ps command on node1 and ignore all the dsh environment 
variable except the DSH_NODE_OPTS, enter:
.sp
.nf
xdsh node1 -X 'DSH_NODE_OPTS' ps
.fi
.sp
.RE
.PP
\fBImplementation Specifics
\fR
.PP
\fBFiles
\fR
.RS +3
\fB/opt/xcat/xdsh/Context/
\fR
.RE
.RS +9
Location of the contexts available to use with DSH Utilities.
.RE
.RS +3
\fB\fB/opt/xcat/bin/xdshbak\fR
\fR
.RE
.RS +9
Location of the command that is supplied as the back-end formatting
filter.
.RE
.PP
\fBLocation
\fR
.PP
\fB/opt/xcat/bin/xdsh\fR
.PP
.RE