PCP(1)                     OpenBSD Reference Manual                     PCP(1)

NAME
     pcp - copy a file to a cluster of machines

SYNOPSIS
     pcp [-bceprtv] [-f fanout] [-g rungroup1,...,rungroupN] [-o porttimeout]
         [-n portnum] [-w node1,...,nodeN] [-x node1,...,nodeN] source_file1
         [source_file2 ... source_fileN] [destination file]

DESCRIPTION
     The pcp utility can be used to copy a file, or directory to a group of
     machines.  The group of machines can be listed on the command line, or
     default to the environment setting CLUSTER The following options are
     available:

     -b   This flag causes pcp to copy files in reverse, or backwards.
          Instead of copying a single file from a single machine, out to the
          list of target machines, the command will copy a file from all
          target machines, to the local machine, and name it file.nodename.
          This can be used to gather configuration files from a group of
          machines and store them locally.

     -c   Normally pcp copies files serially, to all the nodes specified.
          When the -c option is used, pcp will copy the files in parallel to
          the nodes, subject to the FANOUT environment setting and -f option.
          Smaller files will benefit greatly from parallel copies, due to
          reduced latency in the initial authentication, and connection.
          However, large files, especially on a shared ethernet, will suffer
          tremendous speed degredation, because of the collisions the
          transfers will create.  This effect can be reduced, by lowering the
          fanout size of the cluster.

     -e   Unless the -e option is specified, output from remote commands will
          not be reported to the user.

     -p   The -p option causes pcp to attempt to preserve (duplicate) in its
          copies the modification times and modes of the source files,
          ignoring the umask.  By default, the mode and owner of file2 are
          preserved if it already existed; otherwise the mode of the source
          file modified by the umask(2) on the destination host is used.

     -r   If any of the source files are directories, pcp copies each subtree
          rooted at that name; in this case the destination must be a
          directory.

     -v   Prints the version of ClusterIt to the stdout, and exits.

     -f   If the -f option is specified, followed by a number, it sets the
          fanout size of the cluster.  The fanout size is the number of nodes
          a command will run on in parallel at one time.  Thus a 80 node
          cluster, with a fanout size of 64, would run 64 nodes in parallel,
          then, when all have finished, it would execute the command on the
          last 16 nodes.  The fanout size defaults to 64.  This option
          overrides the FANOUT environment variable.

     -o   The -o option is used to set the timeout in seconds to be used when
          testing remote connections.  The default is five seconds.

     -n   The -n option can be used to set the port number that testing should
          occur on when testing remote connections.  The default behavior is
          to guess based on the remote command name.

     -t   The -t option causes pcp to attempt a connection test to each node
          prior to attempting to copy the remote file.  If the test fails for
          any reason, the remote command will not be attempted.  This can be
          useful when clusterfiles have suffered bitrot and some nodes no
          longer exist, or might be down for maintenance.  The default timeout
          is 5 seconds.  The timeout can be changed with the -o option.  pcp
          will attempt to guess the port number of the remote service based on
          your RCMD_CMD setting.  It knows about scp and rcp.  If pcp fails to
          guess your port correctly, you may use the -n argument to set the
          remote port number.  If the RCMD_TEST environment variable exists,
          the testing will automatically take place.

     -g   If the -g option is specified, followed by a comma separated list of
          group names, the command will only be run on that group of nodes.  A
          node may be a part of more than one group if desired, however
          running without the -g option will run the command on the same node
          as many times as it appears in the file specified by the CLUSTER
          environment variable.  This option is silently ignored if used with
          the -w option.

     -w   If the -w option is specified, followed by a comma delimited list of
          machine names, the command will be run on each node in the list.
          Without this flag, pcp runs on the nodes listed in the file pointed
          to by the CLUSTER environment variable.

     -x   The -x option can be used to exclude specific nodes from the
          cluster.  The format is the same as the -w option, a comma delimited
          list of machine names.  This option is silently ignored if used with
          the -w option.

ENVIRONMENT
     pcp utilizes the following environment variables:

     CLUSTER  Contains a filename, which is a newline separated list of nodes
              in the cluster.

     RCP_CMD  Command to use to copy files to remote machines.  The command
              chosen must be able to connect with no password to the remote
              host.  Defaults to scp.

     RCP_CMD_ARGS
              Arguments to pass to the remote copy command. Defaults to none.

     RCP_USER
              The username to connect to remote machines as by default.

     FANOUT   When set, limits the maximum number of concurrent commands sent
              at once.  This can be used to keep from overloading a small host
              when sending out commands in parallel.  Defaults to 64.  This
              environment setting can be overridden by the -f option.

     RCMD_PORT
              The port number used to test remote connections.  See the -n
              flag.

     RCMD_TEST
              When set, pcp will automatically test all hosts before launching
              the remote command. See the -t option for more information.

     RCMD_TEST_TIMEOUT
              The timeout in seconds to use when testing for remote
              connections.

EXAMPLES
     The command:

     pcp file

     will copy the file `file' to the home directory of the current user on
     all machines listed in the file pointed to by the CLUSTER environment
     setting.

     The command:

     pcp -w hadar,rigel file

     will copy the file `file' to the home directory of the current user on
     the machines `hadar' and `rigel'.

     The command:

     pcp -w hadar,rigel /usr/bin/foo /usr/local/bin/foo

     will copy the file `/usr/bin/foo' to `/usr/local/bin/foo' on the machines
     `hadar' and `rigel'.

     The command:

     pcp -bw hadar,rigel /etc/passwd hello

     will copy the file `/etc/passwd' from both hadar and rigel, and name it
     `hello.hadar' and `hello.rigel' in the current working directory.

DIAGNOSTICS
     Exit status is 0 on success, 1 if an error occurs.

SEE ALSO
     cp(1), dsh(1), rcp(1), kerberos(3), hosts.equiv(5), rhosts(5)

HISTORY
     The pcp command appeared in clusterit 1.0. It is based on the pcp command
     in IBM PSSP.

AUTHOR
     Pcp was written by Tim Rightnour.

                               January 11, 2007
