Annotation of src/usr.bin/ssh/scp.1, Revision 1.112
1.1 deraadt 1: .\"
2: .\" scp.1
3: .\"
4: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
5: .\"
6: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
7: .\" All rights reserved
8: .\"
9: .\" Created: Sun May 7 00:14:37 1995 ylo
10: .\"
1.112 ! djm 11: .\" $OpenBSD: scp.1,v 1.111 2022/12/16 03:40:03 djm Exp $
1.1 deraadt 12: .\"
1.112 ! djm 13: .Dd $Mdocdate: December 16 2022 $
1.3 aaron 14: .Dt SCP 1
15: .Os
16: .Sh NAME
17: .Nm scp
1.87 jmc 18: .Nd OpenSSH secure file copy
1.3 aaron 19: .Sh SYNOPSIS
20: .Nm scp
1.105 djm 21: .Op Fl 346ABCOpqRrsTv
1.29 jmc 22: .Op Fl c Ar cipher
1.97 djm 23: .Op Fl D Ar sftp_server_path
1.19 stevesk 24: .Op Fl F Ar ssh_config
1.84 jmc 25: .Op Fl i Ar identity_file
1.83 tb 26: .Op Fl J Ar destination
1.25 markus 27: .Op Fl l Ar limit
1.17 stevesk 28: .Op Fl o Ar ssh_option
1.29 jmc 29: .Op Fl P Ar port
30: .Op Fl S Ar program
1.111 djm 31: .Op Fl X Ar sftp_option
1.76 jmc 32: .Ar source ... target
1.7 aaron 33: .Sh DESCRIPTION
1.3 aaron 34: .Nm
1.6 aaron 35: copies files between hosts on a network.
1.91 deraadt 36: .Pp
1.112 ! djm 37: .Nm
! 38: uses the SFTP protocol over a
1.3 aaron 39: .Xr ssh 1
1.112 ! djm 40: connection for data transfer, and uses the same authentication and provides
! 41: the same security as a login session.
1.91 deraadt 42: .Pp
1.3 aaron 43: .Nm
1.1 deraadt 44: will ask for passwords or passphrases if they are needed for
45: authentication.
1.3 aaron 46: .Pp
1.75 millert 47: The
1.76 jmc 48: .Ar source
49: and
1.75 millert 50: .Ar target
51: may be specified as a local pathname, a remote host with optional path
52: in the form
1.76 jmc 53: .Sm off
54: .Oo user @ Oc host : Op path ,
55: .Sm on
56: or a URI in the form
57: .Sm off
58: .No scp:// Oo user @ Oc host Oo : port Oc Op / path .
59: .Sm on
1.44 jmc 60: Local file names can be made explicit using absolute or relative pathnames
61: to avoid
62: .Nm
63: treating file names containing
64: .Sq :\&
65: as host specifiers.
1.75 millert 66: .Pp
67: When copying between two remote hosts, if the URI format is used, a
68: .Ar port
1.100 naddy 69: cannot be specified on the
1.75 millert 70: .Ar target
71: if the
1.100 naddy 72: .Fl R
1.75 millert 73: option is used.
1.3 aaron 74: .Pp
75: The options are as follows:
76: .Bl -tag -width Ds
1.55 markus 77: .It Fl 3
78: Copies between two remote hosts are transferred through the local host.
79: Without this option the data is copied directly between the two remote
80: hosts.
1.108 djm 81: Note that, when using the legacy SCP protocol (via the
82: .Fl O
83: flag), this option
1.98 djm 84: selects batch mode for the second host as
1.89 jmc 85: .Nm
86: cannot ask for passwords or passphrases for both hosts.
1.98 djm 87: This mode is the default.
1.29 jmc 88: .It Fl 4
89: Forces
90: .Nm
91: to use IPv4 addresses only.
92: .It Fl 6
93: Forces
1.3 aaron 94: .Nm
1.29 jmc 95: to use IPv6 addresses only.
1.90 djm 96: .It Fl A
97: Allows forwarding of
98: .Xr ssh-agent 1
99: to the remote system.
100: The default is not to forward an authentication agent.
1.3 aaron 101: .It Fl B
1.1 deraadt 102: Selects batch mode (prevents asking for passwords or passphrases).
1.3 aaron 103: .It Fl C
1.6 aaron 104: Compression enable.
105: Passes the
1.3 aaron 106: .Fl C
107: flag to
108: .Xr ssh 1
1.1 deraadt 109: to enable compression.
1.29 jmc 110: .It Fl c Ar cipher
111: Selects the cipher to use for encrypting the data transfer.
112: This option is directly passed to
113: .Xr ssh 1 .
1.97 djm 114: .It Fl D Ar sftp_server_path
1.112 ! djm 115: Connect directly to a local SFTP server program rather than a
1.97 djm 116: remote one via
117: .Xr ssh 1 .
118: This option may be useful in debugging the client and server.
1.19 stevesk 119: .It Fl F Ar ssh_config
120: Specifies an alternative
121: per-user configuration file for
122: .Nm ssh .
123: This option is directly passed to
124: .Xr ssh 1 .
1.29 jmc 125: .It Fl i Ar identity_file
1.46 djm 126: Selects the file from which the identity (private key) for public key
1.29 jmc 127: authentication is read.
1.82 tb 128: This option is directly passed to
129: .Xr ssh 1 .
130: .It Fl J Ar destination
1.84 jmc 131: Connect to the target host by first making an
1.82 tb 132: .Nm
133: connection to the jump host described by
134: .Ar destination
135: and then establishing a TCP forwarding to the ultimate destination from
136: there.
137: Multiple jump hops may be specified separated by comma characters.
138: This is a shortcut to specify a
139: .Cm ProxyJump
140: configuration directive.
1.29 jmc 141: This option is directly passed to
142: .Xr ssh 1 .
143: .It Fl l Ar limit
144: Limits the used bandwidth, specified in Kbit/s.
1.99 djm 145: .It Fl O
1.108 djm 146: Use the legacy SCP protocol for file transfers instead of the SFTP protocol.
1.99 djm 147: Forcing the use of the SCP protocol may be necessary for servers that do
1.101 djm 148: not implement SFTP, for backwards-compatibility for particular filename
149: wildcard patterns and for expanding paths with a
150: .Sq ~
151: prefix for older SFTP servers.
1.29 jmc 152: .It Fl o Ar ssh_option
153: Can be used to pass options to
154: .Nm ssh
155: in the format used in
156: .Xr ssh_config 5 .
157: This is useful for specifying options
158: for which there is no separate
159: .Nm scp
160: command-line flag.
161: For full details of the options listed below, and their possible values, see
162: .Xr ssh_config 5 .
163: .Pp
164: .Bl -tag -width Ds -offset indent -compact
165: .It AddressFamily
166: .It BatchMode
167: .It BindAddress
1.77 jmc 168: .It BindInterface
1.61 djm 169: .It CanonicalDomains
170: .It CanonicalizeFallbackLocal
171: .It CanonicalizeHostname
172: .It CanonicalizeMaxDots
173: .It CanonicalizePermittedCNAMEs
1.81 jmc 174: .It CASignatureAlgorithms
1.68 jmc 175: .It CertificateFile
1.29 jmc 176: .It CheckHostIP
177: .It Ciphers
178: .It Compression
1.74 naddy 179: .It ConnectionAttempts
1.34 dtucker 180: .It ConnectTimeout
1.36 djm 181: .It ControlMaster
182: .It ControlPath
1.57 djm 183: .It ControlPersist
1.29 jmc 184: .It GlobalKnownHostsFile
185: .It GSSAPIAuthentication
186: .It GSSAPIDelegateCredentials
1.38 jmc 187: .It HashKnownHosts
1.29 jmc 188: .It Host
1.95 naddy 189: .It HostbasedAcceptedAlgorithms
1.29 jmc 190: .It HostbasedAuthentication
191: .It HostKeyAlgorithms
192: .It HostKeyAlias
1.86 jmc 193: .It Hostname
1.70 jmc 194: .It IdentitiesOnly
1.69 markus 195: .It IdentityAgent
1.29 jmc 196: .It IdentityFile
1.54 jmc 197: .It IPQoS
1.57 djm 198: .It KbdInteractiveAuthentication
1.37 djm 199: .It KbdInteractiveDevices
1.52 jmc 200: .It KexAlgorithms
1.92 jmc 201: .It KnownHostsCommand
1.29 jmc 202: .It LogLevel
203: .It MACs
204: .It NoHostAuthenticationForLocalhost
205: .It NumberOfPasswordPrompts
206: .It PasswordAuthentication
1.50 markus 207: .It PKCS11Provider
1.29 jmc 208: .It Port
209: .It PreferredAuthentications
210: .It ProxyCommand
1.71 jmc 211: .It ProxyJump
1.93 dtucker 212: .It PubkeyAcceptedAlgorithms
1.29 jmc 213: .It PubkeyAuthentication
1.39 dtucker 214: .It RekeyLimit
1.110 djm 215: .It RequiredRSASize
1.35 jmc 216: .It SendEnv
1.32 markus 217: .It ServerAliveInterval
218: .It ServerAliveCountMax
1.79 jmc 219: .It SetEnv
1.29 jmc 220: .It StrictHostKeyChecking
1.31 markus 221: .It TCPKeepAlive
1.65 jmc 222: .It UpdateHostKeys
1.29 jmc 223: .It User
224: .It UserKnownHostsFile
225: .It VerifyHostKeyDNS
226: .El
1.4 markus 227: .It Fl P Ar port
1.6 aaron 228: Specifies the port to connect to on the remote host.
229: Note that this option is written with a capital
1.3 aaron 230: .Sq P ,
231: because
232: .Fl p
1.103 dtucker 233: is already reserved for preserving the times and mode bits of the file.
1.29 jmc 234: .It Fl p
1.103 dtucker 235: Preserves modification times, access times, and file mode bits from the
236: source file.
1.29 jmc 237: .It Fl q
1.43 djm 238: Quiet mode: disables the progress meter as well as warning and diagnostic
239: messages from
240: .Xr ssh 1 .
1.98 djm 241: .It Fl R
242: Copies between two remote hosts are performed by connecting to the origin
243: host and executing
244: .Nm
245: there.
246: This requires that
247: .Nm
248: running on the origin host can authenticate to the destination host without
249: requiring a password.
1.29 jmc 250: .It Fl r
251: Recursively copy entire directories.
1.45 dtucker 252: Note that
253: .Nm
254: follows symbolic links encountered in the tree traversal.
1.10 deraadt 255: .It Fl S Ar program
256: Name of
257: .Ar program
1.12 aaron 258: to use for the encrypted connection.
259: The program must understand
1.9 deraadt 260: .Xr ssh 1
261: options.
1.85 djm 262: .It Fl T
263: Disable strict filename checking.
264: By default when copying files from a remote host to a local directory
265: .Nm
266: checks that the received filenames match those requested on the command-line
267: to prevent the remote end from sending unexpected or unwanted files.
268: Because of differences in how various operating systems and shells interpret
269: filename wildcards, these checks may cause wanted files to be rejected.
270: This option disables these checks at the expense of fully trusting that
271: the server will not send unexpected filenames.
1.29 jmc 272: .It Fl v
273: Verbose mode.
274: Causes
1.24 markus 275: .Nm
1.29 jmc 276: and
277: .Xr ssh 1
278: to print debugging messages about their progress.
279: This is helpful in
280: debugging connection, authentication, and configuration problems.
1.111 djm 281: .It Fl X Ar sftp_option
282: Specify an option that controls aspects of SFTP protocol behaviour.
283: The valid options are:
284: .Bl -tag -width Ds
285: .It Cm nrequests Ns = Ns Ar value
286: Controls how many concurrent SFTP read or write requests may be in progress
287: at any point in time during a download or upload.
288: By default 64 requests may be active concurrently.
289: .It Cm buffer Ns = Ns Ar value
290: Controls the maximum buffer size for a single SFTP read/write operation used
291: during download or upload.
292: By default a 32KB buffer is used.
293: .El
1.8 aaron 294: .El
1.51 jmc 295: .Sh EXIT STATUS
1.40 jmc 296: .Ex -std scp
1.3 aaron 297: .Sh SEE ALSO
1.14 djm 298: .Xr sftp 1 ,
1.3 aaron 299: .Xr ssh 1 ,
300: .Xr ssh-add 1 ,
301: .Xr ssh-agent 1 ,
302: .Xr ssh-keygen 1 ,
1.23 stevesk 303: .Xr ssh_config 5 ,
1.99 djm 304: .Xr sftp-server 8 ,
1.3 aaron 305: .Xr sshd 8
1.28 jmc 306: .Sh HISTORY
307: .Nm
1.62 tedu 308: is based on the rcp program in
1.60 jmc 309: .Bx
310: source code from the Regents of the University of California.
1.108 djm 311: .Pp
1.109 tj 312: Since OpenSSH 9.0,
1.108 djm 313: .Nm
1.109 tj 314: has used the SFTP protocol for transfers by default.
1.28 jmc 315: .Sh AUTHORS
1.59 schwarze 316: .An Timo Rinne Aq Mt tri@iki.fi
317: .An Tatu Ylonen Aq Mt ylo@cs.hut.fi
1.102 jmc 318: .Sh CAVEATS
1.108 djm 319: The legacy SCP protocol (selected by the
320: .Fl O
321: flag) requires execution of the remote user's shell to perform
1.102 jmc 322: .Xr glob 3
323: pattern matching.
324: This requires careful quoting of any characters that have special meaning to
325: the remote shell, such as quote characters.