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