3ac2fc7322
git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@1516 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd
366 lines
11 KiB
Plaintext
366 lines
11 KiB
Plaintext
=head1 B<NAME>
|
|
|
|
B<xdcp> - Concurrently copies files to or from multiple nodes.
|
|
|
|
=head1 B<SYNOPSIS>
|
|
|
|
B<xdcp> I<noderange> [B<-C> I<context>] [B<-f> I<fanout>]
|
|
[B<-L>] [B<-l> I<userID>] [B<-o> I<node_options>]
|
|
[B<-r> I<node_remote_shell>] [B<-R>] [B<-t> I<timeout>]
|
|
[B<-T>] [B<-v>] [B<-X> I<env_list>] sourcefile.... targetpath
|
|
|
|
B<xdcp> [B<-h> | B<-V> | B<-q>]
|
|
|
|
|
|
=head1 B<DESCRIPTION>
|
|
|
|
The B<xdcp> command concurrently copies files to or from remote target
|
|
nodes. The command issues a remote copy com-
|
|
mand for each node or device specified. When files are pulled from a
|
|
target, they are placed into the target_path with the name of the
|
|
remote node or device appended to the copied source_file name. The
|
|
/usr/bin/rcp command is the model for syntax and security.
|
|
|
|
B<TARGET> B<SPECIFICATION>:
|
|
|
|
Target specification is identical for the xdcp and xdsh commands. See the
|
|
xdsh man page for details on specifying targets for the xdcp command.
|
|
|
|
B<REMOTE> B<USER>:
|
|
|
|
A user_ID can be specified for the remote copy command. Remote user
|
|
specification is identical for the xdcp and xdsh commands. See the xdsh
|
|
command for more information.
|
|
|
|
B<REMOTE> B<COMMAND> B<COPY>:
|
|
The B<xdcp> command uses a configurable remote copy command to execute
|
|
remote copies on remote targets. Support is explicitly provided for
|
|
Remote Shell rcp command, the OpenSSH scp command and the
|
|
/usr/bin/rsync command.
|
|
|
|
For node targets, the remote copy command is determined by the follow-
|
|
ing order of precedence:
|
|
|
|
|
|
1. The B<-r> flag.
|
|
|
|
2. The B</usr/bin/scp> command.
|
|
|
|
B<COMMAND> B<EXECUTIONS>
|
|
The maximum number of concurrent remote copy command processes (the
|
|
fanout) can be specified with the -f flag or the 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
|
|
DSH_FANOUT value on your management server to see if higher values are
|
|
appropriate.
|
|
|
|
A timeout value for remote copy command execution can be specified with
|
|
the -t flag or DSH_TIMEOUT environment variable. If any remote target
|
|
does not respond within the timeout value, the xdcp command displays an
|
|
error message and exits.
|
|
|
|
The -T flag provides diagnostic trace information for dcp command exe-
|
|
cution. Default settings and the actual remote copy commands that are
|
|
executed to the remote targets are displayed.
|
|
|
|
The xdcp command can be executed silently using the -Q flag; no target
|
|
standard output or standard error is displayed.
|
|
|
|
=head1 B<OPTIONS>
|
|
|
|
=over 5
|
|
|
|
=item B<sourcefile...>
|
|
|
|
Specifies the complete path for the file to be copied to or
|
|
from the target. Multiple files can be specified. When used
|
|
with the -R flag, only a single directory can be specified.
|
|
When used with the -P flag, only a single file can be specified.
|
|
|
|
=item B<targetpath>
|
|
|
|
Specifies the complete path to copy one or more source_file
|
|
files to on the target. If the -P flag is specified, the tar-
|
|
get_path is the local host location for the copied files. The
|
|
remote file directory structure is recreated under target_path
|
|
and the remote target name is appended to the copied
|
|
source_file name in the target_path directory.
|
|
|
|
|
|
=item B<-C>|B<--context> I<context>
|
|
|
|
The default context to use when resolving target names. The
|
|
I<context> value must correspond to a valid context extension
|
|
module in the B</opt/xcat/xdsh/Context> directory. For
|
|
example, the B</opt/xcat/xdsh/Context/DSH.pm> file is the module
|
|
for the B<DSH> context.
|
|
|
|
=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.
|
|
|
|
|
|
Specifies a remote user name to use for remote command exe-
|
|
cution.
|
|
|
|
|
|
=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<-p>|B<--preserve>
|
|
|
|
Preserves the source file characteristics as implemented by
|
|
the configured remote copy command.
|
|
|
|
|
|
=item B<-P>|B<--pull>
|
|
|
|
Pulls (copies) the files from the targets and places them in
|
|
the target_path directory on the local host. The target_path
|
|
must be a directory. Files pulled from remote machines have
|
|
._target appended to the file name to distinguish between
|
|
them. When the -P flag is used with the -R flag, ._target is
|
|
appended to the directory. Only one file per invocation of the
|
|
xdcp pull command can be pulled from the specified targets.
|
|
|
|
|
|
=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<-r>|B<--node-rcp> I<node_remote_copy>
|
|
|
|
Specifies the full path of the remote copy command used
|
|
for remote command execution on node targets.
|
|
|
|
|
|
=item B<-R>|B<--recursive> I<recursive>
|
|
|
|
Recursively copies files from a local directory to the remote
|
|
targets, or when specified with the -P flag, recursively pulls
|
|
(copies) files from a remote directory to the local host. A
|
|
single source directory can be specified using the source_file
|
|
parameter.
|
|
|
|
=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<xdcp> 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<xdcp> command version information.
|
|
|
|
=back
|
|
|
|
|
|
=head1 B<Environment> B<Variables>
|
|
|
|
=over 4
|
|
|
|
=item B<DSH_CONTEXT>
|
|
|
|
Specifies the default context to use when resolving
|
|
targets. This variable is overridden by the B<-C> 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_NODEGROUP_PATH>
|
|
|
|
Specifies a colon-separated list of directories that
|
|
contain node group files for the B<DSH> context. When the B<-a> flag
|
|
is specified in the B<DSH> context, a list of unique node
|
|
names is collected from all node group files in the path.
|
|
|
|
=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<Exit Status>
|
|
|
|
Exit values for each remote copy command execution are displayed in
|
|
messages from the xdcp command, if the remote copy command exit value is
|
|
non-zero. A non-zero return code from a remote copy command indicates
|
|
that an error was encountered during the remote copy. If a remote copy
|
|
command encounters an error, execution of the remote copy on that tar-
|
|
get is bypassed.
|
|
|
|
The xdcp command exit code is 0 if the xdcp command executed without
|
|
errors and all remote copy commands finished with exit codes of 0. If
|
|
internal xdcp errors occur or the remote copy commands do not complete
|
|
successfully, the xdcp command exit value is greater than 0. The exit
|
|
value is increased by 1 for each successive instance of an unsuccessful
|
|
remote copy command execution.
|
|
|
|
|
|
|
|
=head1 B<Security>
|
|
|
|
The B<xdcp> 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<Examples>
|
|
|
|
=over 3
|
|
|
|
=item *
|
|
|
|
To copy the /tmp/etc/hosts file from the local host to the /etc
|
|
directory on node3, node4, node5, and to user gregb on node16,
|
|
enter:
|
|
|
|
B<xdcp> I<node3-node5 gregb@node16 /tmp/etc/hosts /etc>
|
|
|
|
|
|
=item *
|
|
|
|
To copy the /etc/hosts file from all nodes in the cluster
|
|
to the /tmp/hosts.dir directory on the local host, enter:
|
|
|
|
B<xdcp> I<all -P /etc/hosts /tmp/hosts.dir>
|
|
|
|
A suffix specifying the name of the target is appended to each
|
|
file name. The contents of the /tmp/hosts.dir directory are similar to:
|
|
|
|
hosts._node1 hosts._node4 hosts._node7
|
|
hosts._node2 hosts._node5 hosts._node8
|
|
hosts._node3 hosts._node6
|
|
|
|
|
|
=item *
|
|
|
|
To copy the directory /var/log/testlogdir from all targets in
|
|
NodeGroup1 with a fanout of 12, and save each directory on the local
|
|
host as /var/log._target, enter:
|
|
|
|
B<xdcp> I<NodeGroup1 -f 12 -RP /var/log/testlogdir /var/log>
|
|
|
|
=item *
|
|
|
|
To copy /localnode/smallfile and /tmp/bigfile to /tmp on node1
|
|
using rsync, enter:
|
|
|
|
I<RSYNC_RSH=/usr/bin/ssh; xdcp -r /usr/bin/rsync -o "-z" \
|
|
node1 /localnode/smallfile /tmp/bigfile /tmp>
|
|
|
|
This command uses rsync with the RSYNC_RSH environment variable
|
|
and the -z flag on rsync.
|
|
|
|
|
|
=item *
|
|
|
|
To copy the /etc/hosts file from the local host to all the nodes
|
|
in the cluster, enter:
|
|
|
|
B<xdcp> I<all /etc/hosts /etc/hosts>
|
|
|
|
|
|
=item *
|
|
|
|
To copy the /etc/hosts file from node1 and node2 to the
|
|
/tmp/hosts.dir directory on the local host, enter:
|
|
|
|
B<xdcp> I<node1,node2 -P /etc/hosts /tmp/hosts.dir>
|
|
|
|
|
|
=back
|
|
|
|
=head1 B<Files>
|
|
|
|
B</opt/xcat/xdsh/Context/>
|
|
|
|
Location of the contexts available to use with DSH Utilities.
|
|
|
|
=head1 B<SEE ALSO>
|
|
|
|
xdsh(1), noderange(3)
|