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