Annotation of src/usr.bin/ftp/ftp.1, Revision 1.114
1.114 ! kmos 1: .\" $OpenBSD: ftp.1,v 1.113 2019/05/14 18:27:37 florian Exp $
1.111 jasper 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1985, 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.39 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
30: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
31: .\"
1.110 kmos 32: .\" Copyright (c) 2015 Sunil Nimmagadda <sunil@openbsd.org>
33: .\"
34: .\" Permission to use, copy, modify, and distribute this software for any
35: .\" purpose with or without fee is hereby granted, provided that the above
36: .\" copyright notice and this permission notice appear in all copies.
37: .\"
38: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
39: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
40: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
41: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
42: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
43: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
44: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
45: .\"
1.114 ! kmos 46: .Dd $Mdocdate: May 14 2019 $
1.1 deraadt 47: .Dt FTP 1
1.25 aaron 48: .Os
1.1 deraadt 49: .Sh NAME
50: .Nm ftp
1.86 lteo 51: .Nd Internet file transfer program
1.1 deraadt 52: .Sh SYNOPSIS
1.110 kmos 53: .Nm
54: .Op Fl 46AVv
1.91 jmc 55: .Op Fl D Ar title
1.6 millert 56: .Op Ar host Op Ar port
1.110 kmos 57: .Nm
1.114 ! kmos 58: .Op Fl 46ACMmVv
1.110 kmos 59: .Op Fl D Ar title
1.42 jmc 60: .Op Fl o Ar output
1.110 kmos 61: .Op Fl S Ar tls_options
1.93 lteo 62: .Op Fl U Ar useragent
1.105 deraadt 63: .Op Fl w Ar seconds
1.110 kmos 64: .Ar url ...
1.1 deraadt 65: .Sh DESCRIPTION
1.27 aaron 66: .Nm
1.86 lteo 67: is the user interface to the Internet standard File Transfer
68: Protocol (FTP).
1.1 deraadt 69: The program allows a user to transfer files to and from a
70: remote network site.
1.3 deraadt 71: .Pp
1.110 kmos 72: The latter usage format will fetch a file using either the
73: FTP, HTTP or HTTPS protocols into the current directory.
1.29 aaron 74: This is ideal for scripts.
75: Refer to
1.9 millert 76: .Sx AUTO-FETCHING FILES
77: below for more information.
1.7 millert 78: .Pp
1.28 aaron 79: The options are as follows:
1.32 aaron 80: .Bl -tag -width Ds
1.42 jmc 81: .It Fl 4
82: Forces
83: .Nm
84: to use IPv4 addresses only.
85: .It Fl 6
86: Forces
87: .Nm
1.110 kmos 88: to use IPv6 addreses only.
1.16 millert 89: .It Fl A
1.48 jmc 90: Force active mode FTP.
1.29 aaron 91: By default,
1.16 millert 92: .Nm
1.48 jmc 93: will try to use passive mode FTP and fall back to active mode
1.29 aaron 94: if passive is not supported by the server.
95: This option causes
1.16 millert 96: .Nm
1.29 aaron 97: to always use an active connection.
98: It is only useful for connecting
1.16 millert 99: to very old servers that do not implement passive mode properly.
1.63 martynas 100: .It Fl C
1.65 jmc 101: Continue a previously interrupted file transfer.
1.64 jmc 102: .Nm
1.110 kmos 103: will continue transferring from an offset equal to the length of file.
1.65 jmc 104: .Pp
1.110 kmos 105: Resuming HTTP(S) transfers are only supported if the remote server supports the
1.64 jmc 106: .Dq Range
107: header.
1.91 jmc 108: .It Fl D Ar title
1.110 kmos 109: Specify a short title for the start of the progress bar.
1.97 tedu 110: .It Fl M
111: Causes
112: .Nm
1.110 kmos 113: to never display the progress meter in cases where it would do so by default.
1.114 ! kmos 114: .It Fl m
! 115: Causes
! 116: .Nm
! 117: to display the progress meter in cases where it would not do so by default.
1.17 millert 118: .It Fl o Ar output
1.110 kmos 119: When fetching a file or URL, save the contents in
1.17 millert 120: .Ar output .
1.110 kmos 121: To make the contents go to stdout, use `-' for
1.17 millert 122: .Ar output .
1.110 kmos 123: .It Fl S Ar tls_options
124: TLS options to use with HTTPS transfers.
1.89 jca 125: The following settings are available:
126: .Bl -tag -width Ds
127: .It Cm cafile Ns = Ns Ar /path/to/cert.pem
1.110 kmos 128: PEM encoded file containing CA certificates used for certificate validation.
1.89 jca 129: .It Cm capath Ns = Ns Ar /path/to/certs/
130: Directory containing PEM encoded CA certificates used for certificate
131: validation.
132: .It Cm ciphers Ns = Ns Ar cipher_list
133: Specify the list of ciphers that will be used by
134: .Nm .
135: See the
136: .Xr openssl 1
137: .Cm ciphers
138: subcommand.
139: .It Cm depth Ns = Ns Ar max_depth
1.110 kmos 140: Maximum depth of the certificate chain allowed when performing validation.
1.89 jca 141: .It Cm dont
142: Don't perform server certificate validation.
1.110 kmos 143: .It Cm protocols Ns = Ns Ar string
144: Specify the TLS protocols to use.
145: If not specified the value
146: .Qq all
147: is used.
148: Refer to the
149: .Xr tls_config_parse_protocols 3
150: function for other valid protocol string values.
1.103 beck 151: .It Cm muststaple
1.104 jmc 152: Require the server to present a valid OCSP stapling in the TLS handshake.
1.106 beck 153: .It Cm noverifytime
1.107 jmc 154: Disable validation of certificate times and OCSP validation.
1.108 jsing 155: .It Cm session Ns = Ns Ar /path/to/session
156: Specify a file to use for TLS session data.
157: If this file has a non-zero length, the session data will be read from this file
158: and the client will attempt to resume the TLS session with the server.
1.110 kmos 159: Upon completion of a successful TLS handshake this file will be updated with
160: new session data, if available.
1.108 jsing 161: This file will be created if it does not already exist.
1.89 jca 162: .El
163: .Pp
164: By default, server certificate validation is performed, and if it fails
165: .Nm
166: will abort.
167: If no
168: .Cm cafile
169: or
170: .Cm capath
171: setting is provided,
172: .Pa /etc/ssl/cert.pem
173: will be used.
1.93 lteo 174: .It Fl U Ar useragent
175: Set
176: .Ar useragent
177: as the User-Agent for HTTP(S) URL requests.
1.94 bentley 178: If not specified, the default User-Agent is
179: .Dq OpenBSD ftp .
1.42 jmc 180: .It Fl V
1.110 kmos 181: Disable verbose mode.
1.113 florian 182: .It Fl v
183: Enable verbose mode. This is the default if input is from a terminal.
184: Forces
185: .Nm
186: to show all responses from the remote server, as well as report on data
187: transfer statistics.
1.105 deraadt 188: .It Fl w Ar seconds
1.110 kmos 189: Abort a slow connection after
1.105 deraadt 190: .Ar seconds .
1.1 deraadt 191: .El
192: .Pp
1.43 jmc 193: The host with which
1.6 millert 194: .Nm
1.1 deraadt 195: is to communicate may be specified on the command line.
196: If this is done,
1.6 millert 197: .Nm
1.1 deraadt 198: will immediately attempt to establish a connection to an
1.48 jmc 199: FTP server on that host; otherwise,
1.6 millert 200: .Nm
1.1 deraadt 201: will enter its command interpreter and await instructions
202: from the user.
203: When
1.6 millert 204: .Nm
1.42 jmc 205: is awaiting commands, the prompt
1.51 jmc 206: .Dq ftp\*(Gt
1.1 deraadt 207: is provided to the user.
208: The following commands are recognized
209: by
1.48 jmc 210: .Nm :
1.1 deraadt 211: .Bl -tag -width Fl
1.110 kmos 212: .It Ic open Ar host Op Ar port
213: Establish a connection to the specified
214: .Ar host
215: FTP server.
216: An optional port number may be supplied,
217: in which case
218: .Nm
219: will attempt to contact an FTP server at that port.
1.1 deraadt 220: .It Ic close
1.48 jmc 221: Terminate the FTP session with the remote server and
1.1 deraadt 222: return to the command interpreter.
223: .It Ic help Op Ar command
224: Print an informative message about the meaning of
1.6 millert 225: .Ar command .
1.1 deraadt 226: If no argument is given,
1.6 millert 227: .Nm
1.1 deraadt 228: prints a list of the known commands.
1.110 kmos 229: .It Ic \&? Op Ar command
230: A synonym for
231: .Ic help .
232: .It Ic quit
233: Terminate the FTP session with the remote server and exit
234: .Nm .
235: .It Ic exit
1.10 millert 236: A synonym for
1.110 kmos 237: .Ic quit .
1.42 jmc 238: .It Ic ls Op Ar remote-directory Op Ar local-file
239: Print a listing of the contents of a directory on the remote machine.
1.30 millert 240: The listing includes any system-dependent information that the server
241: chooses to include; for example, most
242: .Ux
1.42 jmc 243: systems will produce output from the command
244: .Ql ls -l .
1.1 deraadt 245: If
246: .Ar remote-directory
247: is left unspecified, the current working directory is used.
248: If no local file is specified, or if
249: .Ar local-file
250: is
1.49 jmc 251: .Sq - ,
1.1 deraadt 252: the output is sent to the terminal.
1.6 millert 253: .It Ic nlist Op Ar remote-directory Op Ar local-file
1.30 millert 254: Print a list of the files in a
255: directory on the remote machine.
256: If
257: .Ar remote-directory
258: is left unspecified, the current working directory is used.
259: If no local file is specified, or if
260: .Ar local-file
261: is
1.49 jmc 262: .Sq - ,
1.38 jmc 263: the output is sent to the terminal.
264: Note that on some servers, the
1.30 millert 265: .Ic nlist
266: command will only return information on normal files (not directories
267: or special files).
1.110 kmos 268: .It Ic pwd
269: Print the name of the current working directory on the remote
270: machine.
271: .It Ic cd Ar remote-directory
272: Change the working directory on the remote machine
273: to
274: .Ar remote-directory .
275: .It Ic get Ar remote-file Op Ar local-file
276: Retrieve the
277: .Ar remote-file
278: and store it on the local machine.
279: If the local
280: file name is not specified, it is given the same
281: name it has on the remote machine.
1.73 sobrado 282: .It Ic passive Op Ic on | off
1.29 aaron 283: Toggle passive mode.
1.48 jmc 284: If passive mode is turned on (default is on),
285: .Nm
286: will send a
1.57 jmc 287: .Dv EPSV
1.1 deraadt 288: command for all data connections instead of the usual
1.110 kmos 289: .Dv EPRT
1.29 aaron 290: command.
291: The
1.110 kmos 292: .Dv EPSV
1.1 deraadt 293: command requests that the remote server open a port for the data connection
1.29 aaron 294: and return the address of that port.
295: The remote server listens on that port and the client connects to it.
296: When using the more traditional
1.110 kmos 297: .Dv EPRT
1.1 deraadt 298: command, the client listens on a port and sends that address to the remote
1.29 aaron 299: server, who connects back to it.
300: Passive mode is useful when using
1.6 millert 301: .Nm
1.1 deraadt 302: through a gateway router or host that controls the directionality of
303: traffic.
1.110 kmos 304: .It Ic lcd Op Ar local-directory
305: Change the working directory on the local machine.
306: If
307: no
308: .Ar local-directory
309: is specified, the user's home directory is used.
310: .It Ic lpwd
311: Print the working directory on the local machine.
1.1 deraadt 312: .It Ic put Ar local-file Op Ar remote-file
313: Store a local file on the remote machine.
314: If
315: .Ar remote-file
1.110 kmos 316: is left unspecified, the local file name is used.
317: .It Ic mget Ar remote-files
318: Do a
1.1 deraadt 319: .Ic get
1.110 kmos 320: for each file name specified.
321: .It Ic mput Ar local-files
322: Do a
1.1 deraadt 323: .Ic put
1.110 kmos 324: for each file name specified.
1.1 deraadt 325: .El
1.6 millert 326: .Sh AUTO-FETCHING FILES
327: In addition to standard commands, this version of
328: .Nm
329: supports an auto-fetch feature.
330: To enable auto-fetch, simply pass the list of hostnames/files
331: on the command line.
332: .Pp
333: The following formats are valid syntax for an auto-fetch element:
1.56 ray 334: .Bl -tag -width Ds
1.99 schwarze 335: .Sm off
1.110 kmos 336: .It Xo ftp://
1.99 schwarze 337: .Ar host Op : Ar port
1.110 kmos 338: .No / Ar file
1.99 schwarze 339: .Xc
340: .Sm on
1.48 jmc 341: An FTP URL, retrieved using the FTP protocol if
1.10 millert 342: .Ev ftp_proxy
343: isn't defined.
1.48 jmc 344: Otherwise, transfer using HTTP via the proxy defined in
1.10 millert 345: .Ev ftp_proxy .
1.99 schwarze 346: .Sm off
1.110 kmos 347: .It Xo http://
1.99 schwarze 348: .Ar host Op : Ar port
349: .No / Ar file
350: .Xc
351: .Sm on
1.48 jmc 352: An HTTP URL, retrieved using the HTTP protocol.
1.6 millert 353: If
354: .Ev http_proxy
355: is defined, it is used as a URL to an HTTP proxy server.
1.99 schwarze 356: .Sm off
1.110 kmos 357: .It Xo https://
1.99 schwarze 358: .Ar host Op : Ar port
359: .No / Ar file
360: .Xc
361: .Sm on
1.54 deraadt 362: An HTTPS URL, retrieved using the HTTPS protocol.
363: If
364: .Ev http_proxy
365: is defined, this HTTPS proxy server will be used to fetch the
366: file using the CONNECT method.
1.100 schwarze 367: .It Pf file: Ar file
1.78 sobrado 368: .Ar file
369: is retrieved from a mounted file system.
1.6 millert 370: .El
1.1 deraadt 371: .Sh ENVIRONMENT
1.6 millert 372: .Nm
1.22 aaron 373: utilizes the following environment variables:
1.110 kmos 374: .Bl -tag -width Ds
1.10 millert 375: .It Ev ftp_proxy
376: URL of FTP proxy to use when making FTP URL requests
1.48 jmc 377: (if not defined, use the standard FTP protocol).
1.6 millert 378: .It Ev http_proxy
1.110 kmos 379: URL of HTTP proxy to use when making HTTP(S) URL requests.
1.1 deraadt 380: .El
1.36 jakob 381: .Sh PORT ALLOCATION
1.38 jmc 382: For active mode data connections,
1.36 jakob 383: .Nm
1.42 jmc 384: will listen to a random high TCP port.
1.36 jakob 385: The interval of ports used are configurable using
1.38 jmc 386: .Xr sysctl 8
1.36 jakob 387: variables
1.42 jmc 388: .Va net.inet.ip.porthifirst
1.36 jakob 389: and
1.42 jmc 390: .Va net.inet.ip.porthilast .
1.1 deraadt 391: .Sh HISTORY
392: The
1.6 millert 393: .Nm
1.110 kmos 394: command first appeard in
1.1 deraadt 395: .Bx 4.2 .
1.110 kmos 396: A complete rewrite of the
397: .Nm
398: command first appeared in
1.112 florian 399: .Ox 6.6 .
1.110 kmos 400: .Sh AUTHORS
401: .An Sunil Nimmagadda Aq Mt sunil@openbsd.org
402: .Sh CAVEATS
403: While aborting a data transfer, certain FTP servers violate
404: the protocol by not responding with a 426 reply first, thereby making
405: .Nm
406: wait indefinitely for a correct reply.
![[BACK]](/icons/back.gif){kind=icon}
Return to ftp.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ftp