'\" te
.\"  Copyright 1989 AT&T
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH RCP 1 "Dec 23, 2008"
.SH NAME
rcp \- remote file copy
.SH SYNOPSIS
.LP
.nf
\fBrcp\fR [\fB-p\fR] [\fB-a\fR] [\fB-K\fR] [\fB-x\fR] [\fB-PN\fR | \fB-PO\fR] [\fB-k\fR \fIrealm\fR] \fIfilename1\fR \fIfilename2\fR
.fi

.LP
.nf
\fBrcp\fR [\fB-pr\fR] [\fB-a\fR] [\fB-K\fR] [\fB-x\fR] [\fB-PN\fR | \fB-PO\fR] [\fB-k\fR \fIrealm\fR] \fIfilename\fR... \fIdirectory\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBrcp\fR command copies files between machines. Each \fIfilename\fR or
\fIdirectory\fR argument is either a remote file name of the form:
.sp
.in +2
.nf
\fIhostname\fR\fB:\fR\fIpath\fR
.fi
.in -2
.sp

.sp
.LP
or a local file name (containing no \fB:\fR (colon) characters, or \fB/\fR
(backslash) before any \fB:\fR (colon) characters).
.sp
.LP
The \fIhostname\fR can be an IPv4 or IPv6 address string. See \fBinet\fR(7P)
and \fBinet6\fR(7P). Since IPv6 addresses already contain colons, the
\fIhostname\fR should be enclosed in a pair of square brackets when an IPv6
address is used. Otherwise, the first occurrence of a colon can be interpreted
as the separator between \fIhostname\fR and \fIpath\fR. For example,
.sp
.in +2
.nf
[1080::8:800:200C:417A]:tmp/file
.fi
.in -2
.sp

.sp
.LP
If a \fIfilename\fR is not a full path name, it is interpreted relative to your
home directory on \fIhostname\fR. A \fIpath\fR on a remote host can be quoted
using \fB\e\|\fR, \fB"\|\fR, or \fB\&'\|\fR, so that the metacharacters are
interpreted remotely. Please notice that the kerberized versions of \fBrcp\fR
are not IPv6-enabled.
.sp
.LP
\fBrcp\fR does not prompt for passwords. It either uses Kerberos authentication
which is enabled through command-line options or your current local user name
must exist on \fIhostname\fR and allow remote command execution by
\fBrsh\fR(1).
.sp
.LP
The \fBrcp\fR session can be kerberized using any of the following Kerberos
specific options : \fB-a\fR, \fB-PN\fR or \fB-PO\fR, \fB-x\fR, and \fB-k\fR
\fIrealm\fR. Some of these options (\fB-a\fR, \fB-x\fR and \fB-PN\fR or
\fB-PO\fR) can also be specified in the \fB[appdefaults]\fR section of
\fBkrb5.conf\fR(4). The usage of these options and the expected behavior is
discussed in the OPTIONS section below. If Kerberos authentication is used,
authorization to the account is controlled by rules in
\fBkrb5_auth_rules\fR(5). If this authorization fails, fallback to normal
\fBrcp\fR using rhosts occurs only if the \fB-PO\fR option is used explicitly
on the command line or is specified in \fBkrb5.conf\fR(4). If authorization
succeeds, remote copy succeeds without any prompting of password. Also notice
that the \fB-PN\fR or \fB-PO\fR, \fB-x\fR, and \fB-k\fR \fIrealm\fR options are
just supersets of the \fB-a\fR option.
.sp
.LP
\fBrcp\fR handles third party copies, where neither source nor target files are
on the current machine. Hostnames can also take the form
.sp
.in +2
.nf
\fIusername\fR\fB@\fR\fIhostname\fR\fB:\fR\fIfilename\fR
.fi
.in -2

.sp
.LP
to use \fIusername\fR rather than your current local user name as the user name
on the remote host. \fBrcp\fR also supports Internet domain addressing of the
remote host, so that:
.sp
.in +2
.nf
\fIusername\fR\fB@\fR\fIhost\fR\fB\&.\fR\fIdomain\fR\fB:\fR\fIfilename\fR
.fi
.in -2

.sp
.LP
specifies the username to be used, the hostname, and the domain in which that
host resides. File names that are not full path names are interpreted relative
to the home directory of the user named \fIusername\fR, on the remote host.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 12n
This option explicitly enables Kerberos authentication and trusts the
\fB\&.k5login\fR file for access-control. If the authorization check by
\fBin.rshd\fR(1M) on the server-side succeeds and if the \fB\&.k5login\fR file
permits access, the user is allowed to carry out the \fBrcp\fR transfer.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR \fIrealm\fR\fR
.ad
.RS 12n
Causes \fBrcp\fR to obtain tickets for the remote host in \fIrealm\fR instead
of the remote host's realm as determined by \fBkrb5.conf\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB-K\fR \fIrealm\fR\fR
.ad
.RS 12n
This option explicitly disables Kerberos authentication. It can be used to
override the \fBautologin\fR variable in \fBkrb5.conf\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 12n
Attempts to give each copy the same modification times, access times, modes,
and \fBACL\fRs if applicable as the original file.
.RE

.sp
.ne 2
.na
\fB\fB-PO\fR\fR
.ad
.br
.na
\fB\fB-PN\fR\fR
.ad
.RS 12n
Explicitly requests new (\fB-PN\fR) or old (\fB-PO\fR) version of the Kerberos
"\fBrcmd\fR" protocol. The new protocol avoids many security problems prevalant
in the old one and is regarded much more secure, but is not interoperable with
older (MIT/SEAM) servers. The new protocol is used by default, unless
explicitly specified using these options or through \fBkrb5.conf\fR(4). If
Kerberos authorization fails when using the old "\fBrcmd\fR" protocol, there is
fallback to regular, non-kerberized \fBrcp\fR. This is not the case when the
new, more secure "\fBrcmd\fR" protocol is used.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 12n
Copies each subtree rooted at \fIfilename\fR; in this case the destination must
be a directory.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 12n
Causes the information transferred between hosts to be encrypted. Notice that
the command is sent unencrypted to the remote system. All subsequent transfers
are encrypted.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBrcp\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.sp
.LP
The \fBrcp\fR command is IPv6-enabled. See \fBip6\fR(7P). \fBIPv6\fR is not
currently supported with Kerberos V5 authentication.
.sp
.LP
For the kerberized \fBrcp\fR session, each user can have a private
authorization list in a file \fB\&.k5login\fR in their home directory. Each
line in this file should contain a Kerberos principal name of the form
\fIprincipal\fR/\fIinstance\fR@\fIrealm\fR. If there is a \fB~/.k5login\fR
file, then access is granted to the account if and only if the originater user
is authenticated to one of the principals named in the \fB~/.k5login\fR file.
Otherwise, the originating user is granted access to the account if and only if
the authenticated principal name of the user can be mapped to the local account
name using the \fIauthenticated-principal-name\fR \(-> \fIlocal-user-name\fR
mapping rules. The \fB\&.k5login\fR file (for access control) comes into play
only when Kerberos authentication is being done.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
All files were copied successfully.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.sp
.LP
See the NOTES section for caveats on the exit code.
.SH FILES
.sp
.LP
\fB$HOME/.profile\fR
.sp
.ne 2
.na
\fB\fB$HOME/.k5login\fR\fR
.ad
.RS 23n
File containing Kerberos principals that are allowed access
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/krb5.conf\fR\fR
.ad
.RS 23n
Kerberos configuration file
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
.TE

.SH SEE ALSO
.sp
.LP
\fBcpio\fR(1), \fBftp\fR(1), \fBrlogin\fR(1), \fBrsh\fR(1), \fBsetfacl\fR(1),
\fBtar\fR(1), \fBtar\fR(1), \fBin.rshd\fR(1M), \fBhosts.equiv\fR(4),
\fBkrb5.conf\fR(4), \fBattributes\fR(5), \fBlargefile\fR(5),
\fBkrb5_auth_rules\fR(5), \fBinet\fR(7P), \fBinet6\fR(7P), \fBip6\fR(7P)
.SH NOTES
.sp
.LP
\fBrcp\fR is meant to copy between different hosts. Attempting to \fBrcp\fR a
file onto itself, as with:
.sp
.in +2
.nf
example% \fBrcp tmp/file myhost:/tmp/file\fR
.fi
.in -2
.sp

.sp
.LP
results in a severely corrupted file.
.sp
.LP
\fBrcp\fR might not correctly fail when the target of a copy is a file instead
of a directory.
.sp
.LP
\fBrcp\fR can become confused by output generated by commands in a
\fB$HOME/.profile\fR on the remote host.
.sp
.LP
\fBrcp\fR requires that the source host have permission to execute commands on
the remote host when doing third-party copies.
.sp
.LP
\fBrcp\fR does not properly handle symbolic links. Use \fBtar\fR or \fBcpio\fR
piped to \fBrsh\fR to obtain remote copies of directories containing symbolic
links or named pipes. See \fBtar\fR(1) and \fBcpio\fR(1).
.sp
.LP
If you forget to quote metacharacters intended for the remote host, you get an
incomprehensible error message.
.sp
.LP
\fBrcp\fR fails if you copy \fBACL\fRs to a file system that does not support
\fBACL\fRs.
.sp
.LP
\fBrcp\fR is \fBCSI\fR-enabled except for the handling of username, hostname,
and domain.
.sp
.LP
When \fBrcp\fR is used to perform third-party copies where either of the remote
machines is not running Solaris, the exit code cannot be relied upon. That is,
errors could occur when success is reflected in the exit code, or the copy
could be completely successful even though an error is reflected in the exit
code.