Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PCP(1)			  BSD General Commands 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.	In-
	  stead	of copying a single file from a	single machine,	out to the
	  list of target machines, the command will copy a file	from all tar-
	  get 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 re-
	  duced	latency	in the initial authentication, and connection.	How-
	  ever,	large files, especially	on a shared ethernet, will suffer
	  tremendous speed degredation,	because	of the collisions the trans-
	  fers 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, ignor-
	  ing the umask.  By default, the mode and owner of file2 are pre-
	  served 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 direc-
	  tory.

     -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 clus-
	  ter, 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	run-
	  ning 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	envi-
	  ronment 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 clus-
	  ter.	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 rcp.

     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 connec-
	      tions.

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

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcp&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help