Annotation of src/usr.bin/ftp/ftp.1, Revision 1.113
1.113 ! florian 1: .\" $OpenBSD: ftp.1,v 1.112 2019/05/12 21:03:17 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.111 jasper 46: .Dd $Mdocdate: May 12 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
58: .Op Fl 46ACMV
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.17 millert 114: .It Fl o Ar output
1.110 kmos 115: When fetching a file or URL, save the contents in
1.17 millert 116: .Ar output .
1.110 kmos 117: To make the contents go to stdout, use `-' for
1.17 millert 118: .Ar output .
1.110 kmos 119: .It Fl S Ar tls_options
120: TLS options to use with HTTPS transfers.
1.89 jca 121: The following settings are available:
122: .Bl -tag -width Ds
123: .It Cm cafile Ns = Ns Ar /path/to/cert.pem
1.110 kmos 124: PEM encoded file containing CA certificates used for certificate validation.
1.89 jca 125: .It Cm capath Ns = Ns Ar /path/to/certs/
126: Directory containing PEM encoded CA certificates used for certificate
127: validation.
128: .It Cm ciphers Ns = Ns Ar cipher_list
129: Specify the list of ciphers that will be used by
130: .Nm .
131: See the
132: .Xr openssl 1
133: .Cm ciphers
134: subcommand.
135: .It Cm depth Ns = Ns Ar max_depth
1.110 kmos 136: Maximum depth of the certificate chain allowed when performing validation.
1.89 jca 137: .It Cm dont
138: Don't perform server certificate validation.
1.110 kmos 139: .It Cm protocols Ns = Ns Ar string
140: Specify the TLS protocols to use.
141: If not specified the value
142: .Qq all
143: is used.
144: Refer to the
145: .Xr tls_config_parse_protocols 3
146: function for other valid protocol string values.
1.103 beck 147: .It Cm muststaple
1.104 jmc 148: Require the server to present a valid OCSP stapling in the TLS handshake.
1.106 beck 149: .It Cm noverifytime
1.107 jmc 150: Disable validation of certificate times and OCSP validation.
1.108 jsing 151: .It Cm session Ns = Ns Ar /path/to/session
152: Specify a file to use for TLS session data.
153: If this file has a non-zero length, the session data will be read from this file
154: and the client will attempt to resume the TLS session with the server.
1.110 kmos 155: Upon completion of a successful TLS handshake this file will be updated with
156: new session data, if available.
1.108 jsing 157: This file will be created if it does not already exist.
1.89 jca 158: .El
159: .Pp
160: By default, server certificate validation is performed, and if it fails
161: .Nm
162: will abort.
163: If no
164: .Cm cafile
165: or
166: .Cm capath
167: setting is provided,
168: .Pa /etc/ssl/cert.pem
169: will be used.
1.93 lteo 170: .It Fl U Ar useragent
171: Set
172: .Ar useragent
173: as the User-Agent for HTTP(S) URL requests.
1.94 bentley 174: If not specified, the default User-Agent is
175: .Dq OpenBSD ftp .
1.42 jmc 176: .It Fl V
1.110 kmos 177: Disable verbose mode.
1.113 ! florian 178: .It Fl v
! 179: Enable verbose mode. This is the default if input is from a terminal.
! 180: Forces
! 181: .Nm
! 182: to show all responses from the remote server, as well as report on data
! 183: transfer statistics.
1.105 deraadt 184: .It Fl w Ar seconds
1.110 kmos 185: Abort a slow connection after
1.105 deraadt 186: .Ar seconds .
1.1 deraadt 187: .El
188: .Pp
1.43 jmc 189: The host with which
1.6 millert 190: .Nm
1.1 deraadt 191: is to communicate may be specified on the command line.
192: If this is done,
1.6 millert 193: .Nm
1.1 deraadt 194: will immediately attempt to establish a connection to an
1.48 jmc 195: FTP server on that host; otherwise,
1.6 millert 196: .Nm
1.1 deraadt 197: will enter its command interpreter and await instructions
198: from the user.
199: When
1.6 millert 200: .Nm
1.42 jmc 201: is awaiting commands, the prompt
1.51 jmc 202: .Dq ftp\*(Gt
1.1 deraadt 203: is provided to the user.
204: The following commands are recognized
205: by
1.48 jmc 206: .Nm :
1.1 deraadt 207: .Bl -tag -width Fl
1.110 kmos 208: .It Ic open Ar host Op Ar port
209: Establish a connection to the specified
210: .Ar host
211: FTP server.
212: An optional port number may be supplied,
213: in which case
214: .Nm
215: will attempt to contact an FTP server at that port.
1.1 deraadt 216: .It Ic close
1.48 jmc 217: Terminate the FTP session with the remote server and
1.1 deraadt 218: return to the command interpreter.
219: .It Ic help Op Ar command
220: Print an informative message about the meaning of
1.6 millert 221: .Ar command .
1.1 deraadt 222: If no argument is given,
1.6 millert 223: .Nm
1.1 deraadt 224: prints a list of the known commands.
1.110 kmos 225: .It Ic \&? Op Ar command
226: A synonym for
227: .Ic help .
228: .It Ic quit
229: Terminate the FTP session with the remote server and exit
230: .Nm .
231: .It Ic exit
1.10 millert 232: A synonym for
1.110 kmos 233: .Ic quit .
1.42 jmc 234: .It Ic ls Op Ar remote-directory Op Ar local-file
235: Print a listing of the contents of a directory on the remote machine.
1.30 millert 236: The listing includes any system-dependent information that the server
237: chooses to include; for example, most
238: .Ux
1.42 jmc 239: systems will produce output from the command
240: .Ql ls -l .
1.1 deraadt 241: If
242: .Ar remote-directory
243: is left unspecified, the current working directory is used.
244: If no local file is specified, or if
245: .Ar local-file
246: is
1.49 jmc 247: .Sq - ,
1.1 deraadt 248: the output is sent to the terminal.
1.6 millert 249: .It Ic nlist Op Ar remote-directory Op Ar local-file
1.30 millert 250: Print a list of the files in a
251: directory on the remote machine.
252: If
253: .Ar remote-directory
254: is left unspecified, the current working directory is used.
255: If no local file is specified, or if
256: .Ar local-file
257: is
1.49 jmc 258: .Sq - ,
1.38 jmc 259: the output is sent to the terminal.
260: Note that on some servers, the
1.30 millert 261: .Ic nlist
262: command will only return information on normal files (not directories
263: or special files).
1.110 kmos 264: .It Ic pwd
265: Print the name of the current working directory on the remote
266: machine.
267: .It Ic cd Ar remote-directory
268: Change the working directory on the remote machine
269: to
270: .Ar remote-directory .
271: .It Ic get Ar remote-file Op Ar local-file
272: Retrieve the
273: .Ar remote-file
274: and store it on the local machine.
275: If the local
276: file name is not specified, it is given the same
277: name it has on the remote machine.
1.73 sobrado 278: .It Ic passive Op Ic on | off
1.29 aaron 279: Toggle passive mode.
1.48 jmc 280: If passive mode is turned on (default is on),
281: .Nm
282: will send a
1.57 jmc 283: .Dv EPSV
1.1 deraadt 284: command for all data connections instead of the usual
1.110 kmos 285: .Dv EPRT
1.29 aaron 286: command.
287: The
1.110 kmos 288: .Dv EPSV
1.1 deraadt 289: command requests that the remote server open a port for the data connection
1.29 aaron 290: and return the address of that port.
291: The remote server listens on that port and the client connects to it.
292: When using the more traditional
1.110 kmos 293: .Dv EPRT
1.1 deraadt 294: command, the client listens on a port and sends that address to the remote
1.29 aaron 295: server, who connects back to it.
296: Passive mode is useful when using
1.6 millert 297: .Nm
1.1 deraadt 298: through a gateway router or host that controls the directionality of
299: traffic.
1.110 kmos 300: .It Ic lcd Op Ar local-directory
301: Change the working directory on the local machine.
302: If
303: no
304: .Ar local-directory
305: is specified, the user's home directory is used.
306: .It Ic lpwd
307: Print the working directory on the local machine.
1.1 deraadt 308: .It Ic put Ar local-file Op Ar remote-file
309: Store a local file on the remote machine.
310: If
311: .Ar remote-file
1.110 kmos 312: is left unspecified, the local file name is used.
313: .It Ic mget Ar remote-files
314: Do a
1.1 deraadt 315: .Ic get
1.110 kmos 316: for each file name specified.
317: .It Ic mput Ar local-files
318: Do a
1.1 deraadt 319: .Ic put
1.110 kmos 320: for each file name specified.
1.1 deraadt 321: .El
1.6 millert 322: .Sh AUTO-FETCHING FILES
323: In addition to standard commands, this version of
324: .Nm
325: supports an auto-fetch feature.
326: To enable auto-fetch, simply pass the list of hostnames/files
327: on the command line.
328: .Pp
329: The following formats are valid syntax for an auto-fetch element:
1.56 ray 330: .Bl -tag -width Ds
1.99 schwarze 331: .Sm off
1.110 kmos 332: .It Xo ftp://
1.99 schwarze 333: .Ar host Op : Ar port
1.110 kmos 334: .No / Ar file
1.99 schwarze 335: .Xc
336: .Sm on
1.48 jmc 337: An FTP URL, retrieved using the FTP protocol if
1.10 millert 338: .Ev ftp_proxy
339: isn't defined.
1.48 jmc 340: Otherwise, transfer using HTTP via the proxy defined in
1.10 millert 341: .Ev ftp_proxy .
1.99 schwarze 342: .Sm off
1.110 kmos 343: .It Xo http://
1.99 schwarze 344: .Ar host Op : Ar port
345: .No / Ar file
346: .Xc
347: .Sm on
1.48 jmc 348: An HTTP URL, retrieved using the HTTP protocol.
1.6 millert 349: If
350: .Ev http_proxy
351: is defined, it is used as a URL to an HTTP proxy server.
1.99 schwarze 352: .Sm off
1.110 kmos 353: .It Xo https://
1.99 schwarze 354: .Ar host Op : Ar port
355: .No / Ar file
356: .Xc
357: .Sm on
1.54 deraadt 358: An HTTPS URL, retrieved using the HTTPS protocol.
359: If
360: .Ev http_proxy
361: is defined, this HTTPS proxy server will be used to fetch the
362: file using the CONNECT method.
1.100 schwarze 363: .It Pf file: Ar file
1.78 sobrado 364: .Ar file
365: is retrieved from a mounted file system.
1.6 millert 366: .El
1.1 deraadt 367: .Sh ENVIRONMENT
1.6 millert 368: .Nm
1.22 aaron 369: utilizes the following environment variables:
1.110 kmos 370: .Bl -tag -width Ds
1.10 millert 371: .It Ev ftp_proxy
372: URL of FTP proxy to use when making FTP URL requests
1.48 jmc 373: (if not defined, use the standard FTP protocol).
1.6 millert 374: .It Ev http_proxy
1.110 kmos 375: URL of HTTP proxy to use when making HTTP(S) URL requests.
1.1 deraadt 376: .El
1.36 jakob 377: .Sh PORT ALLOCATION
1.38 jmc 378: For active mode data connections,
1.36 jakob 379: .Nm
1.42 jmc 380: will listen to a random high TCP port.
1.36 jakob 381: The interval of ports used are configurable using
1.38 jmc 382: .Xr sysctl 8
1.36 jakob 383: variables
1.42 jmc 384: .Va net.inet.ip.porthifirst
1.36 jakob 385: and
1.42 jmc 386: .Va net.inet.ip.porthilast .
1.1 deraadt 387: .Sh HISTORY
388: The
1.6 millert 389: .Nm
1.110 kmos 390: command first appeard in
1.1 deraadt 391: .Bx 4.2 .
1.110 kmos 392: A complete rewrite of the
393: .Nm
394: command first appeared in
1.112 florian 395: .Ox 6.6 .
1.110 kmos 396: .Sh AUTHORS
397: .An Sunil Nimmagadda Aq Mt sunil@openbsd.org
398: .Sh CAVEATS
399: While aborting a data transfer, certain FTP servers violate
400: the protocol by not responding with a 426 reply first, thereby making
401: .Nm
402: 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