|
1 .\" $OpenBSD: ftp.1,v 1.114 2019/05/15 11:53:22 kmos Exp $ |
|
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. |
|
12 .\" 3. Neither the name of the University nor the names of its contributors |
|
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 .\" |
|
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 $ |
|
45 .Dt FTP 1 |
|
46 .Os |
|
47 .Sh NAME |
|
48 .Nm ftp |
|
49 .Nd Internet file transfer program |
|
50 .Sh SYNOPSIS |
|
51 .Nm |
|
52 .Op Fl 46AVv |
|
53 .Op Fl N Ar name |
|
54 .Op Fl D Ar title |
|
55 .Op Ar host Op Ar port |
|
56 .Nm |
|
57 .Op Fl 46ACMmVv |
|
58 .Op Fl N Ar name |
|
59 .Op Fl D Ar title |
|
60 .Op Fl o Ar output |
|
61 .Op Fl S Ar tls_options |
|
62 .Op Fl U Ar useragent |
|
63 .Op Fl w Ar seconds |
|
64 .Ar url ... |
|
65 .Sh DESCRIPTION |
|
66 .Nm |
|
67 is the user interface to the Internet standard File Transfer |
|
68 Protocol (FTP). |
|
69 The program allows a user to transfer files to and from a |
|
70 remote network site. |
|
71 .Pp |
|
72 The latter usage format will fetch a file using either the |
|
73 FTP, HTTP or HTTPS protocols into the current directory. |
|
74 This is ideal for scripts. |
|
75 Refer to |
|
76 .Sx AUTO-FETCHING FILES |
|
77 below for more information. |
|
78 .Pp |
|
79 The options are as follows: |
|
80 .Bl -tag -width Ds |
|
81 .It Fl 4 |
|
82 Forces |
|
83 .Nm |
|
84 to use IPv4 addresses only. |
|
85 .It Fl 6 |
|
86 Forces |
|
87 .Nm |
|
88 to use IPv6 addreses only. |
|
89 .It Fl A |
|
90 Force active mode FTP. |
|
91 By default, |
|
92 .Nm |
|
93 will try to use passive mode FTP and fall back to active mode |
|
94 if passive is not supported by the server. |
|
95 This option causes |
|
96 .Nm |
|
97 to always use an active connection. |
|
98 It is only useful for connecting |
|
99 to very old servers that do not implement passive mode properly. |
|
100 .It Fl C |
|
101 Continue a previously interrupted file transfer. |
|
102 .Nm |
|
103 will continue transferring from an offset equal to the length of file. |
|
104 .Pp |
|
105 Resuming HTTP(S) transfers are only supported if the remote server supports the |
|
106 .Dq Range |
|
107 header. |
|
108 .It Fl D Ar title |
|
109 Specify a short title for the start of the progress bar. |
|
110 .It Fl M |
|
111 Causes |
|
112 .Nm |
|
113 to never display the progress meter in cases where it would do so by default. |
|
114 .It Fl N Ar name |
|
115 Use this alternative name instead of |
|
116 .Nm |
|
117 in some error reports. |
|
118 .It Fl m |
|
119 Causes |
|
120 .Nm |
|
121 to display the progress meter in cases where it would not do so by default. |
|
122 .It Fl o Ar output |
|
123 When fetching a file or URL, save the contents in |
|
124 .Ar output . |
|
125 To make the contents go to stdout, use `-' for |
|
126 .Ar output . |
|
127 .It Fl S Ar tls_options |
|
128 TLS options to use with HTTPS transfers. |
|
129 The following settings are available: |
|
130 .Bl -tag -width Ds |
|
131 .It Cm cafile Ns = Ns Ar /path/to/cert.pem |
|
132 PEM encoded file containing CA certificates used for certificate validation. |
|
133 .It Cm capath Ns = Ns Ar /path/to/certs/ |
|
134 Directory containing PEM encoded CA certificates used for certificate |
|
135 validation. |
|
136 .It Cm ciphers Ns = Ns Ar cipher_list |
|
137 Specify the list of ciphers that will be used by |
|
138 .Nm . |
|
139 See the |
|
140 .Xr openssl 1 |
|
141 .Cm ciphers |
|
142 subcommand. |
|
143 .It Cm depth Ns = Ns Ar max_depth |
|
144 Maximum depth of the certificate chain allowed when performing validation. |
|
145 .It Cm dont |
|
146 Don't perform server certificate validation. |
|
147 .It Cm protocols Ns = Ns Ar string |
|
148 Specify the TLS protocols to use. |
|
149 If not specified the value |
|
150 .Qq all |
|
151 is used. |
|
152 Refer to the |
|
153 .Xr tls_config_parse_protocols 3 |
|
154 function for other valid protocol string values. |
|
155 .It Cm muststaple |
|
156 Require the server to present a valid OCSP stapling in the TLS handshake. |
|
157 .It Cm noverifytime |
|
158 Disable validation of certificate times and OCSP validation. |
|
159 .It Cm session Ns = Ns Ar /path/to/session |
|
160 Specify a file to use for TLS session data. |
|
161 If this file has a non-zero length, the session data will be read from this file |
|
162 and the client will attempt to resume the TLS session with the server. |
|
163 Upon completion of a successful TLS handshake this file will be updated with |
|
164 new session data, if available. |
|
165 This file will be created if it does not already exist. |
|
166 .El |
|
167 .Pp |
|
168 By default, server certificate validation is performed, and if it fails |
|
169 .Nm |
|
170 will abort. |
|
171 If no |
|
172 .Cm cafile |
|
173 or |
|
174 .Cm capath |
|
175 setting is provided, |
|
176 .Pa /etc/ssl/cert.pem |
|
177 will be used. |
|
178 .It Fl U Ar useragent |
|
179 Set |
|
180 .Ar useragent |
|
181 as the User-Agent for HTTP(S) URL requests. |
|
182 If not specified, the default User-Agent is |
|
183 .Dq OpenBSD ftp . |
|
184 .It Fl V |
|
185 Disable verbose mode. |
|
186 .It Fl v |
|
187 Enable verbose mode. |
|
188 This is the default if input if from a terminal. |
|
189 Forces |
|
190 .Nm |
|
191 to show all responses from the remote server, as well as report on data |
|
192 transfer statistics. |
|
193 .It Fl w Ar seconds |
|
194 Abort a slow connection after |
|
195 .Ar seconds . |
|
196 .El |
|
197 .Pp |
|
198 The host with which |
|
199 .Nm |
|
200 is to communicate may be specified on the command line. |
|
201 If this is done, |
|
202 .Nm |
|
203 will immediately attempt to establish a connection to an |
|
204 FTP server on that host; otherwise, |
|
205 .Nm |
|
206 will enter its command interpreter and await instructions |
|
207 from the user. |
|
208 When |
|
209 .Nm |
|
210 is awaiting commands, the prompt |
|
211 .Dq ftp\*(Gt |
|
212 is provided to the user. |
|
213 The following commands are recognized |
|
214 by |
|
215 .Nm : |
|
216 .Bl -tag -width Ds |
|
217 .It Ic open Ar host Op Ar port |
|
218 Establish a connection to the specified |
|
219 .Ar host |
|
220 FTP server. |
|
221 An optional port number may be supplied, |
|
222 in which case |
|
223 .Nm |
|
224 will attempt to contact an FTP server at that port. |
|
225 .It Ic close |
|
226 Terminate the FTP session with the remote server and |
|
227 return to the command interpreter. |
|
228 .It Ic help Op Ar command |
|
229 Print an informative message about the meaning of |
|
230 .Ar command . |
|
231 If no argument is given, |
|
232 .Nm |
|
233 prints a list of the known commands. |
|
234 .It Ic \&? Op Ar command |
|
235 A synonym for |
|
236 .Ic help . |
|
237 .It Ic quit |
|
238 Terminate the FTP session with the remote server and exit |
|
239 .Nm . |
|
240 .It Ic exit |
|
241 A synonym for |
|
242 .Ic quit . |
|
243 .It Ic ls Op Ar remote-directory Op Ar local-file |
|
244 Print a listing of the contents of a directory on the remote machine. |
|
245 The listing includes any system-dependent information that the server |
|
246 chooses to include; for example, most |
|
247 .Ux |
|
248 systems will produce output from the command |
|
249 .Ql ls -l . |
|
250 If |
|
251 .Ar remote-directory |
|
252 is left unspecified, the current working directory is used. |
|
253 If no local file is specified, or if |
|
254 .Ar local-file |
|
255 is |
|
256 .Sq - , |
|
257 the output is sent to the terminal. |
|
258 .It Ic nlist Op Ar remote-directory Op Ar local-file |
|
259 Print a list of the files in a |
|
260 directory on the remote machine. |
|
261 If |
|
262 .Ar remote-directory |
|
263 is left unspecified, the current working directory is used. |
|
264 If no local file is specified, or if |
|
265 .Ar local-file |
|
266 is |
|
267 .Sq - , |
|
268 the output is sent to the terminal. |
|
269 Note that on some servers, the |
|
270 .Ic nlist |
|
271 command will only return information on normal files (not directories |
|
272 or special files). |
|
273 .It Ic pwd |
|
274 Print the name of the current working directory on the remote |
|
275 machine. |
|
276 .It Ic cd Ar remote-directory |
|
277 Change the working directory on the remote machine |
|
278 to |
|
279 .Ar remote-directory . |
|
280 .It Ic get Ar remote-file Op Ar local-file |
|
281 Retrieve the |
|
282 .Ar remote-file |
|
283 and store it on the local machine. |
|
284 If the local |
|
285 file name is not specified, it is given the same |
|
286 name it has on the remote machine. |
|
287 .It Ic passive Op Ic on | off |
|
288 Toggle passive mode. |
|
289 If passive mode is turned on (default is on), |
|
290 .Nm |
|
291 will send a |
|
292 .Dv EPSV |
|
293 command for all data connections instead of the usual |
|
294 .Dv EPRT |
|
295 command. |
|
296 The |
|
297 .Dv EPSV |
|
298 command requests that the remote server open a port for the data connection |
|
299 and return the address of that port. |
|
300 The remote server listens on that port and the client connects to it. |
|
301 When using the more traditional |
|
302 .Dv EPRT |
|
303 command, the client listens on a port and sends that address to the remote |
|
304 server, who connects back to it. |
|
305 Passive mode is useful when using |
|
306 .Nm |
|
307 through a gateway router or host that controls the directionality of |
|
308 traffic. |
|
309 .It Ic lcd Op Ar local-directory |
|
310 Change the working directory on the local machine. |
|
311 If |
|
312 no |
|
313 .Ar local-directory |
|
314 is specified, the user's home directory is used. |
|
315 .It Ic lpwd |
|
316 Print the working directory on the local machine. |
|
317 .It Ic put Ar local-file Op Ar remote-file |
|
318 Store a local file on the remote machine. |
|
319 If |
|
320 .Ar remote-file |
|
321 is left unspecified, the local file name is used. |
|
322 .It Ic mget Ar remote-files |
|
323 Do a |
|
324 .Ic get |
|
325 for each file name specified. |
|
326 .It Ic mput Ar local-files |
|
327 Do a |
|
328 .Ic put |
|
329 for each file name specified. |
|
330 .El |
|
331 .Sh AUTO-FETCHING FILES |
|
332 In addition to standard commands, this version of |
|
333 .Nm |
|
334 supports an auto-fetch feature. |
|
335 To enable auto-fetch, simply pass the list of hostnames/files |
|
336 on the command line. |
|
337 .Pp |
|
338 The following formats are valid syntax for an auto-fetch element: |
|
339 .Bl -tag -width Ds |
|
340 .Sm off |
|
341 .It Xo ftp:// |
|
342 .Ar host Op : Ar port |
|
343 .No / Ar file |
|
344 .Xc |
|
345 .Sm on |
|
346 An FTP URL, retrieved using the FTP protocol if |
|
347 .Ev ftp_proxy |
|
348 isn't defined. |
|
349 Otherwise, transfer using HTTP via the proxy defined in |
|
350 .Ev ftp_proxy . |
|
351 .Sm off |
|
352 .It Xo http:// |
|
353 .Ar host Op : Ar port |
|
354 .No / Ar file |
|
355 .Xc |
|
356 .Sm on |
|
357 An HTTP URL, retrieved using the HTTP protocol. |
|
358 If |
|
359 .Ev http_proxy |
|
360 is defined, it is used as a URL to an HTTP proxy server. |
|
361 .Sm off |
|
362 .It Xo https:// |
|
363 .Ar host Op : Ar port |
|
364 .No / Ar file |
|
365 .Xc |
|
366 .Sm on |
|
367 An HTTPS URL, retrieved using the HTTPS protocol. |
|
368 If |
|
369 .Ev http_proxy |
|
370 is defined, this HTTPS proxy server will be used to fetch the |
|
371 file using the CONNECT method. |
|
372 .It Pf file: Ar file |
|
373 .Ar file |
|
374 is retrieved from a mounted file system. |
|
375 .El |
|
376 .Sh ENVIRONMENT |
|
377 .Nm |
|
378 utilizes the following environment variables: |
|
379 .Bl -tag -width Ds |
|
380 .It Ev ftp_proxy |
|
381 URL of FTP proxy to use when making FTP URL requests |
|
382 (if not defined, use the standard FTP protocol). |
|
383 .It Ev http_proxy |
|
384 URL of HTTP proxy to use when making HTTP(S) URL requests. |
|
385 .El |
|
386 .Sh PORT ALLOCATION |
|
387 For active mode data connections, |
|
388 .Nm |
|
389 will listen to a random high TCP port. |
|
390 The interval of ports used are configurable using |
|
391 .Xr sysctl 8 |
|
392 variables |
|
393 .Va net.inet.ip.porthifirst |
|
394 and |
|
395 .Va net.inet.ip.porthilast . |
|
396 .Sh HISTORY |
|
397 The |
|
398 .Nm |
|
399 command first appeard in |
|
400 .Bx 4.2 . |
|
401 A complete rewrite of the |
|
402 .Nm |
|
403 command first appeared in |
|
404 .Ox x.x . |
|
405 .Sh AUTHORS |
|
406 .An Sunil Nimmagadda Aq Mt sunil@openbsd.org |
|
407 .Sh CAVEATS |
|
408 While aborting a data transfer, certain FTP servers violate |
|
409 the protocol by not responding with a 426 reply first, thereby making |
|
410 .Nm |
|
411 wait indefinitely for a correct reply. |