303c20ffa7
git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@7463 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd
533 lines
19 KiB
Plaintext
533 lines
19 KiB
Plaintext
=head1 B<NAME>
|
|
|
|
B<xdsh> - Concurrently runs commands on multiple nodes, or an install image.
|
|
|
|
=head1 B<SYNOPSIS>
|
|
|
|
B<xdsh> I<noderange> [B<-B> I<bypass>] [B<--devicetype> I<type_of_device>] [B<-e>] [B<-E> I<environment_file>] [B<-f> I<fanout>]
|
|
[B<-L>] [B<-l> I<userID>] [B<-m>] [B<-o>
|
|
I<node_options>] [B<-Q>] [B<-r> I<node_remote_shell>] [B<-s>] [B<-S> B<csh>|B<ksh>] [B<-t> I<timeout>]
|
|
[B<-T>] [B<-v>] [B<-X> I<env_list>] [B<-z>] I<command_list>
|
|
|
|
B<xdsh> I<noderange> [B<-K>]
|
|
|
|
B<xdsh> I<noderange> [B<-K>] [B<-l> I<userID>] B<--devicetype> I<type_of_device>
|
|
|
|
B<xdsh> [B<-i> I<image path | nim image name>] I<command_list>
|
|
|
|
B<xdsh> I<servicenoderange> [B<-c>]
|
|
|
|
B<xdsh> [B<-h> | B<-V> | B<-q>]
|
|
|
|
=head1 B<DESCRIPTION>
|
|
|
|
The B<xdsh> command runs commands in parallel on remote nodes. The B<xdsh> 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.
|
|
The B<xdsh> command is an xCAT Distributed Shell Utility.
|
|
|
|
|
|
B<COMMAND> B<SPECIFICATION>:
|
|
|
|
The commands to execute on the remote targets are specified by the
|
|
I<command_list> B<xdsh> parameter, or executing a local script using the B<-e>
|
|
flag.
|
|
|
|
The syntax for the I<command_list> B<xdsh> parameter is as follows:
|
|
|
|
I<command>[; I<command>]...
|
|
|
|
|
|
where I<command> 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 B<-e>
|
|
flag. If B<-e> is specified, I<command_list> is the
|
|
script name and arguments to the script. For example:
|
|
|
|
xdsh hostname -e I<script_filename> [I<arguments>]...
|
|
|
|
The I<script_filename> file is copied to a random filename in the B</tmp>
|
|
directory on each remote target and then executed on the targets.
|
|
|
|
The B<xdsh> command does not work with any interactive commands, including
|
|
those that read from standard input.
|
|
|
|
B<REMOTE> B<SHELL> B<COMMAND>:
|
|
|
|
The B<xdsh> 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.
|
|
|
|
The remote shell is determined as follows, in order of precedence:
|
|
|
|
1. The B<-r> flag.
|
|
|
|
2. The B<DSH_NODE_RSH> environment variable.
|
|
|
|
3. The default node remote shell as defined by the target I<context>.
|
|
|
|
4. The B</usr/bin/ssh> command.
|
|
|
|
The remote shell options are determined as follows, in order of prece-
|
|
dence:
|
|
|
|
1. The B<-o> flag.
|
|
|
|
2. The B<DSH_NODE_OPTS> environment variable.
|
|
|
|
B<REMOTE> B<SHELL> B<ENVIRONMENT>:
|
|
|
|
The shell environment used on the remote target defaults to the shell
|
|
defined for the I<user_ID> on the remote target. The command
|
|
syntax that B<xdsh> uses to form the remote commands can be specified using the B<-S>
|
|
flag. If B<-S> is not specified, the syntax defaults to B<sh> syntax.
|
|
|
|
When commands are executed on the remote target, the path used is
|
|
determined by the B<DSH_PATH> environment variable defined in the shell of
|
|
the current user. If B<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 B<-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 I<command_list> is executed.
|
|
|
|
B<COMMAND> B<EXECUTION>:
|
|
|
|
The maximum number of concurrent remote shell command processes (the
|
|
fanout) can be specified with the B<-f> flag or with the B<DSH_FANOUT>
|
|
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
|
|
B<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
|
|
B<-t> flag or with the B<DSH_TIMEOUT> environment variable. If any remote
|
|
target does not provide output to either standard output or standard
|
|
error within the timeout value, B<xdsh> displays an error message and
|
|
exits.
|
|
|
|
If streaming mode is specified with the B<-s> flag, output is returned as
|
|
it becomes available from each target, instead of waiting for the
|
|
I<command_list> to complete on all targets before returning output. This can
|
|
improve performance but causes the output to be unsorted.
|
|
|
|
The B<-z> flag displays the exit code from the last command issued on the
|
|
remote node in I<command_list>. 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 B<xdsh> and may require using the B<-c>
|
|
flag. If the command issued on the remote node is run in the
|
|
background, the exit status is not displayed.
|
|
|
|
The B<-m> flag monitors execution of the B<xdsh> command by printing status
|
|
messages to standard output. Each status message is preceded by B<dsh>.
|
|
|
|
The B<-T> flag provides diagnostic trace information for the execution of
|
|
the B<xdsh> command. Default settings and the actual remote shell commands
|
|
executed on the remote targets are displayed.
|
|
|
|
No error detection or recovery mechanism is provided for remote
|
|
targets. The B<xdsh> command output to standard error and standard output can
|
|
be analyzed to determine the appropriate course of action. In interac-
|
|
tive 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
|
|
B<xdsh> command unless the B<-c> flag is specified.
|
|
|
|
B<COMMAND> B<OUTPUT>:
|
|
|
|
The B<xdsh> 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
|
|
B<-s> flag.
|
|
|
|
The B<xdsh> command output consists of standard error and standard output
|
|
from the remote commands. The B<xdsh> standard output is the standard
|
|
output from the remote shell command. The B<xdsh> 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 B<:> character and a command output line. A filter for
|
|
displaying identical outputs grouped by node is provided separately.
|
|
See the B<xdshbak> command for more information.
|
|
|
|
A command can be run silently using the B<-Q> flag; no output from each
|
|
target's standard output or standard error is displayed.
|
|
|
|
B<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
|
|
B<xdsh>; the B<xdsh> command responds normally to these signals, but the
|
|
signals do not have an effect on remotely executing commands. Other
|
|
signals are caught by B<xdsh> and have their default effects on the B<xdsh>
|
|
command; all current child processes, through propagation to remotely
|
|
running commands, are terminated (SIGTERM).
|
|
|
|
=head1 B<OPTIONS>
|
|
|
|
=over 5
|
|
|
|
|
|
=item B<-c>|B<--cleanup>
|
|
|
|
This flag will have xdsh remove all files from the subdirectories of the
|
|
the directory on the Service Node, where xdcp stages the copy to the
|
|
compute nodes as defined in the site table SNsyncfiledir attribute.
|
|
|
|
=item B<-e>|B<--execute>
|
|
|
|
Indicates that I<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
|
|
B<DSH_NODE_RCP> environment variables specify the remote copy
|
|
command to use to copy the script file to node targets.
|
|
|
|
=item B<-E>|B<--environment> I<environment_file>
|
|
|
|
Specifies that the I<environment_file> contains environment
|
|
variable definitions to export to the target before
|
|
executing the I<command_list>. The B<DSH_NODE_RCP> and environment
|
|
variables specify the remote copy command to use to export
|
|
the file to node targets.
|
|
|
|
=item B<--devicetype> I<type_of_device>
|
|
|
|
Specify a user-defined device type that references the location
|
|
of relevant device configuration file. The devicetype value must
|
|
correspond to a valid device configuration file under the /var/opt/xcat/
|
|
directory.
|
|
For example, /var/opt/xcat/IBSwitch/Qlogic/config is the configuration
|
|
file location if devicetype is specified as IBSwitch::Qlogic
|
|
|
|
=item B<-f>|B<--fanout> I<fanout_value>
|
|
|
|
Specifies a fanout value for the maximum number of concur-
|
|
rently executing remote shell processes. Serial execution
|
|
can be specified by indicating a fanout value of B<1>. If B<-f>
|
|
is not specified, a default fanout value of B<64> is used.
|
|
|
|
=item B<-h>|B<--help>
|
|
|
|
Displays usage information.
|
|
|
|
|
|
=item B<-i>|B<--rootimg> I<install image>
|
|
|
|
For Linux, Specifies the path to the install image on the local node.
|
|
For AIX, specifies the name of the osimage on the local node. Run lsnim
|
|
for valid names.
|
|
xdsh will chroot (xcatchroot for AIX) to this path and run the xdsh command against the
|
|
install image. No other xdsh flags, environment variables apply with
|
|
this input. A noderange is not accepted. Only runs on the local host,
|
|
normally the Management Node.
|
|
|
|
=item B<-K>|B<--ssh-setup>
|
|
|
|
=item B<-K>|B<--ssh-setup> B<-l>|B<--user> I<user_ID> B<--devicetype> I<type_of_device>
|
|
|
|
Set up the SSH keys for the user running the command to the specified node list.
|
|
The userid must have the same uid, gid and password as the userid on the node
|
|
where the keys will be setup.
|
|
If the current user is root, roots public ssh keys will be put in the
|
|
authorized_keys* files under roots .ssh directory on the node(s).
|
|
If the current user is non-root, the user must be in the policy table and have credential to run the xdsh command.
|
|
The non-root users public ssh keys and root's public ssh keys will be put in
|
|
the authorized_keys* files under the non-root users .ssh directory on the node(s).
|
|
Other device types, such as IB switch, are also supported. The
|
|
device should be defined as a node and nodetype should be defined
|
|
as switch before connecting.
|
|
The xdsh -K command must be run from the Management Node.
|
|
|
|
=item B<-l>|B<--user> I<user_ID>
|
|
|
|
Specifies a remote user name to use for remote command exe-
|
|
cution.
|
|
|
|
=item B<-L>|B<--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.
|
|
|
|
=item B<-m>|B<--monitor>
|
|
|
|
Monitors remote shell execution by displaying status
|
|
messages during execution on each target.
|
|
|
|
=item B<-o>|B<--node-options> I<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 B<xdsh> options.
|
|
|
|
=item B<-q>|B<--show-config>
|
|
|
|
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 I<context>: to
|
|
identify the source context of the setting.
|
|
|
|
=item B<-Q>|B<--silent>
|
|
|
|
Specifies silent mode. No target output is written to stan-
|
|
dard output or standard error. Monitoring messages are
|
|
written to standard output.
|
|
|
|
=item B<-r>|B<--node-rsh> I<node_remote_shell>
|
|
|
|
|
|
Specifies the path of the remote shell command used
|
|
for remote command execution on node targets.
|
|
|
|
|
|
=item B<-s>|B<--stream>
|
|
|
|
Specifies that output is returned as it becomes available
|
|
from each target, instead of waiting for the I<command_list>
|
|
to be completed on a target before returning output.
|
|
|
|
=item B<-S>|B<--syntax> B<csh>|B<ksh>
|
|
|
|
Specifies the shell syntax to be used on the remote target.
|
|
If not specified, the B<ksh> syntax is used.
|
|
|
|
=item B<-t>|B<--timeout> I<timeout>
|
|
|
|
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 I<timeout>, B<xdsh>
|
|
displays an error and terminates execution for the remote
|
|
targets that failed to respond. If I<timeout> is not specified,
|
|
B<xdsh> waits indefinitely to continue processing output from
|
|
all remote targets. When specified with the B<-i> flag, the
|
|
user is prompted for an additional timeout interval to wait
|
|
for output.
|
|
|
|
=item B<-T>|B<--trace>
|
|
|
|
Enables trace mode. The B<xdsh> command prints diagnostic
|
|
messages to standard output during execution to each target.
|
|
|
|
=item B<-v>|B<--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 B<-i> flag, the user is prompted to retry the
|
|
verification request.
|
|
|
|
=item B<-V>|B<--version>
|
|
|
|
Displays the B<xdsh> command version information.
|
|
|
|
=item B<-X> I<env_list>
|
|
|
|
Ignore B<xdsh> environment variables. This option can take an
|
|
argument which is a comma separated list of environment
|
|
variable names that should B<NOT> be ignored. If there is no
|
|
argument to this option, or the argument is an empty
|
|
string, all B<xdsh> environment variables will be ignored.
|
|
This option is useful when running B<xdsh> from within other
|
|
scripts when you don't want the user's environment affecting
|
|
the behavior of xdsh.
|
|
|
|
=item B<-z>|B<--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 values for each remote shell execution are displayed in
|
|
messages from the B<xdsh> 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 B<xdsh> command exit code is B<0> if the command executed without
|
|
errors and all remote shell commands finished with exit codes of B<0>.
|
|
If internal B<xdsh> errors occur or the remote shell commands do not
|
|
complete successfully, the B<xdsh> command exit value is greater than
|
|
B<0>. The exit value is increased by B<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 B<0>.
|
|
|
|
=back
|
|
|
|
|
|
=head1 B<Environment> B<Variables>
|
|
|
|
=over 4
|
|
|
|
=item B<DEVICETYPE>
|
|
|
|
Specify a user-defined device type. See B<--devicetype> flag.
|
|
|
|
|
|
=item B<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 B<-E> flag.
|
|
|
|
=item B<DSH_FANOUT>
|
|
|
|
Specifies the fanout value. This variable is overridden by
|
|
the B<-f> flag.
|
|
|
|
=item B<DSH_NODE_OPTS>
|
|
|
|
Specifies the options to use for the remote shell command
|
|
with node targets only. This variable is overridden by the
|
|
B<-o> flag.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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 B<-r> flag.
|
|
|
|
=item B<DSH_PATH>
|
|
|
|
Sets the command path to use on the targets. If B<DSH_PATH> is
|
|
not set, the default path defined in the profile of the
|
|
remote I<user_ID> is used.
|
|
|
|
=item B<DSH_SYNTAX>
|
|
|
|
Specifies the shell syntax to use on remote targets; B<ksh> or
|
|
B<csh>. If not specified, the B<ksh> syntax is assumed. This
|
|
variable is overridden by the B<-S> flag.
|
|
|
|
=item B<DSH_TIMEOUT>
|
|
|
|
Specifies the time, in seconds, to wait for output from
|
|
each remote target. This variable is overridden by the B<-t>
|
|
flag.
|
|
|
|
=back
|
|
|
|
=head1 B<Compatibility with AIX dsh>
|
|
|
|
To provide backward compatibility for scripts written using dsh in
|
|
AIX and CSM, a tool has been provide B<groupfiles4dsh>,
|
|
which will build node group files from the
|
|
xCAT database that can be used by dsh. See man groupfiles4dsh.
|
|
|
|
=head1 B<Security>
|
|
|
|
The B<xdsh> command has no security configuration requirements. All
|
|
remote command security requirements - configuration,
|
|
authentication, and authorization - are imposed by the underlying remote
|
|
command configured for B<xdsh>. 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
|
|
userdefined.
|
|
|
|
|
|
=head1 B<Exit Status>
|
|
|
|
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.
|
|
|
|
|
|
=head1 B<Examples>
|
|
|
|
=over 3
|
|
|
|
=item *
|
|
|
|
To define the IB switch as a node and to set up the SSH keys for IB switch
|
|
B<qswitch> with device configuration file
|
|
B</var/opt/xcat/IBSwitch/Qlogic/config> and user name B<username>, Enter
|
|
|
|
B<chdef> I<-t node -o qswitch groups=all nodetype=switch>
|
|
B<xdsh> I<qswitch -K -l username --devicetype IBSwitch::Qlogic>
|
|
|
|
|
|
=item *
|
|
|
|
To set up the SSH keys for root on node1, run as root:
|
|
|
|
B<xdsh> I<node1 -K>
|
|
|
|
=item *
|
|
|
|
To run the B<ps -ef > command on node targets B<node1> and B<node2>, enter:
|
|
|
|
B<xdsh> I<node1,node2 "ps -ef">
|
|
|
|
=item *
|
|
|
|
To run the B<ps> command on node targets B<node1> and run the remote command with the -v and -t flag, enter:
|
|
|
|
B<xdsh> I<node1,node2 -o"-v -t" ps>
|
|
=item *
|
|
|
|
To execute the commands contained in B<myfile> in the B<XCAT>
|
|
context on several node targets, with a fanout of B<1>, enter:
|
|
|
|
B<xdsh> I<node1,node2 -C XCAT -f 1 -e myfile>
|
|
|
|
|
|
=item *
|
|
|
|
To run the ps command on node1 and ignore all the dsh
|
|
environment variable except the DSH_NODE_OPTS, enter:
|
|
|
|
B<xdsh> I<node1 -X `DSH_NODE_OPTS' ps>
|
|
|
|
|
|
=item *
|
|
|
|
To run on Linux, the xdsh command "rpm -qa | grep xCAT"
|
|
on the service node fedora9 diskless image, enter:
|
|
|
|
B<xdsh> I<-i /install/netboot/fedora9/x86_64/service/rootimg "rpm -qa | grep xCAT">
|
|
|
|
=item *
|
|
|
|
To run on AIX, the xdsh command "lslpp -l | grep bos"
|
|
on the NIM 611dskls spot, enter:
|
|
|
|
B<xdsh> I<-i 611dskls "/usr/bin/lslpp -l | grep bos">
|
|
|
|
=item *
|
|
|
|
To cleanup the servicenode directory that stages the copy of files to the
|
|
nodes, enter:
|
|
|
|
B<xdsh> I<servicenoderange -c >
|
|
|
|
=back
|
|
|
|
=head1 B<Files>
|
|
|
|
|
|
=head1 B<SEE ALSO>
|
|
|
|
L<xdshbak(1)|xdshbak.1>, L<noderange(3)|noderange.3>, L<groupfiles4dsh(1)|groupfiles4dsh.1>
|