/doc/pdcp.1.in
https://code.google.com/ · Autoconf · 246 lines · 219 code · 27 blank · 0 comment · 12 complexity · b245c7907b08b9499132ae3718ea40b9 MD5 · raw file
- \." $Id$
- .\"
- .\"
- .\"
- .TH "@PACKAGE@" "1" "@host_os@" "@PDSH_VERSION@"
- .SH NAME
- pdcp \- copy files to groups of hosts in parallel
- .br
- rpdcp \- (reverse pdcp) copy files from a group of hosts in parallel
- .SH SYNOPSIS
- \fBpdcp\fR [\fIoptions\fR]... src [src2...] dest
- .br
- \fBrpdcp\fR [\fIoptions\fR]... src [src2...] dir
- .SH DESCRIPTION
- \fBpdcp\fR is a variant of the rcp(1) command. Unlike rcp(1), which
- copies files to a single remote host, \fBpdcp\fR can copy files to
- multiple remote hosts in parallel. However, \fBpdcp\fR does
- not recognize files in the format ``rname@rhost:path,'' therefore all
- source files must be on the local host machine. Destination nodes must
- be listed on the \fBpdcp\fR command line using a suitable target
- nodelist option (See the \fIOPTIONS\fR section below). Each destination
- node listed must have \fBpdcp\fR installed for the copy to succeed.
- .LP
- When \fBpdcp\fR receives SIGINT (ctrl-C), it lists the status of current
- threads. A second SIGINT within one second terminates the program. Pending
- threads may be canceled by issuing ctrl-Z within one second of ctrl-C.
- Pending threads are those that have not yet been initiated, or are still
- in the process of connecting to the remote host.
- .LP
- Like pdsh(1), the functionality of \fBpdcp\fR may be supplemented by
- dynamically loadable modules. In \fBpdcp\fR, the modules may provide
- a new connect protocol (replacing the standard rsh(1) protocol), filtering
- options (e.g. excluding hosts that are down), and/or host selection
- options (e.g. \fI-a\fR selects all nodes from a local config file).
- By default, \fBpdcp\fR requires at least one "rcmd" module to be
- loaded (to provide the channel for remote copy).
- .SH "REVERSE PDCP"
- \fBrpdcp\fR performs a reverse parallel copy. Rather than copying files
- to remote hosts, files are retrieved from remote hosts and stored locally.
- All directories or files retrieved will be stored with their remote
- hostname appended to the filename. The destination file must be a
- directory when this option is used.
- .LP
- In other respects, \fBrpdcp\fR is exactly like \fBpdcp\fR, and further
- statements regarding \fBpdcp\fR in this manual also apply to \fBrpdcp\fR.
- .SH "RCMD MODULES"
- The method by which \fBpdcp\fR connects to remote hosts may be
- selected at runtime using the \fI-R\fR option (See \fIOPTIONS\fR below).
- This functionality is ultimately implemented via dynamically loadable
- modules, and so the list of available options may be different
- from installation to installation. A list of currently available rcmd
- modules is printed when using any of the \fI-h\fR, \fI-V\fR, or \fI-L\fR
- options. The default rcmd module will also be displayed with the
- \fI-h\fR and \fI-V\fR options.
- .LP
- A list of \fIrcmd\fR modules currently distributed with \fBpdcp\fR
- follows.
- .TP 8
- rsh
- Uses an internal, thread-safe implementation of BSD rcmd(3)
- to run commands using the standard rsh(1) protocol.
- .TP
- ssh
- Uses a variant of popen(3) to run multiple copies of the ssh(1)
- command.
- .TP
- mrsh
- This module uses the mrsh(1) protocol to execute jobs on remote hosts.
- The mrsh protocol uses a credential based authentication, forgoing
- the need to allocate reserved ports. In other aspects, it acts just
- like rsh.
- .TP
- krb4
- The krb4 module allows users to execute remote commands after
- authenticating with kerberos. Of course, the remote rshd daemons
- must be kerberized.
- .TP
- xcpu
- The xcpu module uses the xcpu service to execute remote commands.
- .SH OPTIONS
- The list of available \fBpdcp\fR options is determined at runtime
- by supplementing the list of standard \fBpdcp\fR options with
- any options provided by loaded \fIrcmd\fR and \fImisc\fR modules.
- In some cases, options provided by modules may conflict with
- each other. In these cases, the modules are incompatible and
- the first module loaded wins.
- .SH "Standard target nodelist options"
- .TP
- \fB\-w\fR \fITARGETS,...\fR
- Target and or filter the specified list of hosts. Do not use with any
- other node selection options (e.g. \fI\-a\fR, \fI\-g\fR, if they are
- available). No spaces are allowed in the comma-separated list. Arguments in
- the \fITARGETS\fR list may include normal host names, a range of hosts
- in hostlist format (See \fBHOSTLIST EXPRESSIONS\fR), or a single `-'
- character to read the list of hosts on stdin.
- If a host or hostlist is preceded by a `-' character, this causes those
- hosts to be explicitly excluded. If the argument is preceded by a single `^'
- character, it is taken to be the path to file containing a list of hosts,
- one per line. If the item begins with a `/' character, it is taken as a
- regular expression on which to filter the list of hosts (a regex argument
- may also be optionally trailed by another '/', e.g. /node.*/). A regex or
- file name argument may also be preceeded by a minus `-' to exclude instead
- of include thoses hosts.
- A list of hosts may also be preceded by "user@" to specify a remote
- username other than the default, or "rcmd_type:" to specify an alternate
- rcmd connection type for these hosts. When used together, the rcmd type
- must be specified first, e.g. "ssh:user1@host0" would use ssh to connect
- to host0 as user "user1."
- .TP
- .I \fB-x\fR \fIhost,host,...\fR
- Exclude the specified hosts. May be specified in conjunction with
- other target node list options such as \fI\-a\fR and \fI\-g\fR (when
- available). Hostlists may also be specified to the \fI\-x\fR option
- (see the \fBHOSTLIST EXPRESSIONS\fR section below). Arguments to
- \fI-x\fR may also be preceeded by the filename (`^') and regex ('/')
- characters as described above, in which case the resulting hosts are excluded
- as if they had been given to \fB\-w\fR and preceeded with the minus `-'
- character.
- .SH "Standard pdcp options"
- .TP
- .I "-h"
- Output usage menu and quit. A list of available rcmd modules
- will be printed at the end of the usage message.
- .TP
- .I "-q"
- List option values and the target nodelist and exit without action.
- .TP
- .I "-b"
- Disable ctrl-C status feature so that a single ctrl-C kills parallel
- copy. (Batch Mode)
- .TP
- .I "-r"
- Copy directories recursively.
- .TP
- .I "-p"
- Preserve modification time and modes.
- .TP
- .I "-e PATH"
- Explicitly specify path to remote \fBpdcp\fR binary
- instead of using the locally executed path. Can also be set via
- the environment variable PDSH_REMOTE_PDCP_PATH.
- .TP
- .I "-l user"
- This option may be used to copy files as another user, subject to
- authorization. For BSD rcmd, this means the invoking user and system must
- be listed in the user\'s .rhosts file (even for root).
- .TP
- .I "-t seconds"
- Set the connect timeout. Default is @CONNECT_TIMEOUT@ seconds.
- .TP
- .I "-f number"
- Set the maximum number of simultaneous remote copies to \fInumber\fR.
- The default is @FANOUT@.
- .TP
- .I "-R name"
- Set rcmd module to \fIname\fR. This option may also be set via the
- PDSH_RCMD_TYPE environment variable. A list of available rcmd
- modules may be obtained via either the \fI-h\fR or \fI-L\fR options.
- .TP
- .I "-M name,..."
- When multiple \fBmisc\fR modules provide the same options to \fBpdsh\fR,
- the first module initialized "wins" and subsequent modules are not loaded.
- The \fI-M\fR option allows a list of modules to be specified that will be
- force-initialized before all others, in-effect ensuring that they load
- without conflict (unless they conflict with eachother). This option may
- also be set via the PDSH_MISC_MODULES environment variable.
- .TP
- .I "-L"
- List info on all loaded \fBpdcp\fR modules and quit.
- .TP
- .I "-d"
- Include more complete thread status when SIGINT is received, and display
- connect and command time statistics on stderr when done.
- .TP
- .I "-V"
- Output \fBpdcp\fR version information, along with list of currently
- loaded modules, and exit.
- .SH "HOSTLIST EXPRESSIONS"
- As noted in sections above,
- .B pdcp
- accepts ranges of hostnames in
- the general form: prefix[n-m,l-k,...], where n < m and l < k, etc.,
- as an alternative to explicit lists of hosts. This form should not
- be confused with regular expression character classes (also denoted
- by ``[]''). For example, foo[19] does not represent foo1 or foo9, but
- rather represents a degenerate range: foo19.
- This range syntax is meant
- only as a convenience on clusters with a prefixNN naming convention and
- specification of ranges should not be considered necessary -- the list
- foo1,foo9 could be specified as such, or by the range foo[1,9].
- Some examples of range usage follow:
- .nf
- Copy /etc/hosts to foo01,foo02,...,foo05
- pdcp -w foo[01-05] /etc/hosts /etc
- Copy /etc/hosts to foo7,foo9,foo10
- pdcp -w foo[7,9-10] /etc/hosts /etc
- Copy /etc/hosts to foo0,foo4,foo5
- pdcp -w foo[0-5] -x foo[1-3] /etc/hosts /etc
- .fi
- As a reminder to the reader, some shells will interpret brackets ('['
- and ']') for pattern matching. Depending on your shell, it may be
- necessary to enclose ranged lists within quotes. For example, in
- tcsh, the first example above should be executed as:
- pdcp -w "foo[01-05]" /etc/hosts /etc
- .SH "ORIGIN"
- Pdsh/pdcp was originally a rewrite of IBM dsh(1) by Jim Garlick
- <garlick@llnl.gov> on LLNL's ASCI Blue-Pacific IBM SP system.
- It is now also used on Linux clusters at LLNL.
- .SH "LIMITATIONS"
- When using
- .B ssh
- for remote execution, stderr of ssh to be folded in with that of the
- remote command. When invoked by pdcp, it is not possible for ssh to
- prompt for confirmation if a host key changes, prompt for passwords if
- RSA keys are not configured properly, etc.. Finally, the connect
- timeout is only adjustable with ssh when the underlying ssh implementation
- supports it, and pdsh has been built to use the correct option.
- .SH "SEE ALSO"
- pdsh(1)