Annotation of src/usr.bin/ftp/ftp.1, Revision 1.101
1.101 ! schwarze 1: .\" $OpenBSD: ftp.1,v 1.100 2015/09/25 20:32:39 schwarze Exp $
1.96 jmc 2: .\" $NetBSD: ftp.1,v 1.22 1997/08/18 10:20:22 lukem Exp $
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1985, 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.39 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
32: .\"
1.100 schwarze 33: .Dd $Mdocdate: September 25 2015 $
1.1 deraadt 34: .Dt FTP 1
1.25 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm ftp
1.86 lteo 38: .Nd Internet file transfer program
1.1 deraadt 39: .Sh SYNOPSIS
1.23 aaron 40: .Nm ftp
1.97 tedu 41: .Op Fl 46AadEegiMmnptVv
1.91 jmc 42: .Op Fl D Ar title
1.61 espie 43: .Op Fl k Ar seconds
1.6 millert 44: .Op Fl P Ar port
1.7 millert 45: .Op Fl r Ar seconds
1.82 haesbaer 46: .Op Fl s Ar srcaddr
1.6 millert 47: .Op Ar host Op Ar port
1.3 deraadt 48: .Nm ftp
1.65 jmc 49: .Op Fl C
1.42 jmc 50: .Op Fl o Ar output
1.82 haesbaer 51: .Op Fl s Ar srcaddr
1.42 jmc 52: .Sm off
1.100 schwarze 53: .Pf ftp:// Op Ar user : password No @
1.99 schwarze 54: .Ar host Op : Ar port
55: .No / Ar file Op /
1.81 jmc 56: .Sm on
1.77 martynas 57: .Ar ...
1.3 deraadt 58: .Nm ftp
1.65 jmc 59: .Op Fl C
60: .Op Fl c Ar cookie
1.42 jmc 61: .Op Fl o Ar output
1.89 jca 62: .Op Fl S Ar ssl_options
1.82 haesbaer 63: .Op Fl s Ar srcaddr
1.93 lteo 64: .Op Fl U Ar useragent
1.42 jmc 65: .Sm off
1.100 schwarze 66: .Pf http Oo s Oc ://
1.99 schwarze 67: .Op Ar user : password No @
68: .Ar host Op : Ar port
69: .No / Ar file
1.81 jmc 70: .Sm on
1.77 martynas 71: .Ar ...
1.54 deraadt 72: .Nm ftp
1.65 jmc 73: .Op Fl C
1.54 deraadt 74: .Op Fl o Ar output
1.82 haesbaer 75: .Op Fl s Ar srcaddr
1.100 schwarze 76: .Pf file: Ar
1.78 sobrado 77: .Nm ftp
78: .Op Fl C
79: .Op Fl o Ar output
1.82 haesbaer 80: .Op Fl s Ar srcaddr
1.99 schwarze 81: .Ar host : Ns / Ns Ar file Ns Op /
1.77 martynas 82: .Ar ...
1.1 deraadt 83: .Sh DESCRIPTION
1.27 aaron 84: .Nm
1.86 lteo 85: is the user interface to the Internet standard File Transfer
86: Protocol (FTP).
1.1 deraadt 87: The program allows a user to transfer files to and from a
88: remote network site.
1.3 deraadt 89: .Pp
1.84 lteo 90: The latter four usage formats will fetch a file using either the
1.55 jmc 91: FTP, HTTP, or HTTPS protocols into the current directory.
1.29 aaron 92: This is ideal for scripts.
93: Refer to
1.9 millert 94: .Sx AUTO-FETCHING FILES
95: below for more information.
1.7 millert 96: .Pp
1.28 aaron 97: The options are as follows:
1.32 aaron 98: .Bl -tag -width Ds
1.42 jmc 99: .It Fl 4
100: Forces
101: .Nm
102: to use IPv4 addresses only.
103: .It Fl 6
104: Forces
105: .Nm
106: to use IPv6 addresses only.
1.16 millert 107: .It Fl A
1.48 jmc 108: Force active mode FTP.
1.29 aaron 109: By default,
1.16 millert 110: .Nm
1.48 jmc 111: will try to use passive mode FTP and fall back to active mode
1.29 aaron 112: if passive is not supported by the server.
113: This option causes
1.16 millert 114: .Nm
1.29 aaron 115: to always use an active connection.
116: It is only useful for connecting
1.16 millert 117: to very old servers that do not implement passive mode properly.
1.6 millert 118: .It Fl a
119: Causes
120: .Nm
1.22 aaron 121: to bypass the normal login procedure and use an anonymous login instead.
1.63 martynas 122: .It Fl C
1.65 jmc 123: Continue a previously interrupted file transfer.
1.64 jmc 124: .Nm
125: will continue transferring from an offset equal to the length of
126: .Ar file .
1.65 jmc 127: .Pp
1.64 jmc 128: Resuming HTTP(S) transfers are only supported
129: if the remote server supports the
130: .Dq Range
131: header.
1.60 jmc 132: .It Fl c Ar cookie
133: Load a Netscape-like cookiejar file
134: for HTTP and HTTPS transfers.
1.59 pyr 135: With this option relevant cookies from the jar are sent with each HTTP(S)
136: request.
1.60 jmc 137: Setting the
138: .Ev http_cookies
139: environment variable has the same effect.
140: If both the
141: .Ev http_cookies
142: environment variable is set and the
1.59 pyr 143: .Fl c
1.60 jmc 144: argument is given, the latter takes precedence.
1.91 jmc 145: .It Fl D Ar title
146: Specify a short
147: .Ar title
148: for the start of the progress bar.
1.6 millert 149: .It Fl d
150: Enables debugging.
1.53 fgsch 151: .It Fl E
152: Disables EPSV/EPRT command on IPv4 connections.
1.8 kstailey 153: .It Fl e
1.29 aaron 154: Disables command line editing.
155: Useful for Emacs ange-ftp.
1.6 millert 156: .It Fl g
157: Disables file name globbing.
158: .It Fl i
159: Turns off interactive prompting during
160: multiple file transfers.
1.61 espie 161: .It Fl k Ar seconds
1.67 jmc 162: When greater than zero,
1.66 espie 163: sends a byte after each
1.61 espie 164: .Ar seconds
165: period over the control connection during long transfers,
166: so that incorrectly configured network equipment won't
1.62 jmc 167: aggressively drop it.
1.61 espie 168: The FTP protocol supports a
169: .Dv NOOP
170: command that can be used for that purpose.
171: This assumes the FTP server can deal with extra commands coming over
172: the control connection during a transfer.
173: Well-behaved servers queue those commands, and process them after the
174: transfer.
1.68 espie 175: By default,
176: .Nm
177: will send a byte every 60 seconds.
1.97 tedu 178: .It Fl M
179: Causes
180: .Nm
181: to never display the progress meter in cases where it would do
182: so by default.
1.20 millert 183: .It Fl m
184: Causes
185: .Nm
1.21 millert 186: to always display the progress meter in cases where it would not do
187: so by default.
1.1 deraadt 188: .It Fl n
189: Restrains
1.6 millert 190: .Nm
191: from attempting
192: .Dq auto-login
193: upon initial connection.
1.1 deraadt 194: If auto-login is enabled,
1.6 millert 195: .Nm
1.1 deraadt 196: will check the
197: .Pa .netrc
1.42 jmc 198: file (see below) in the user's home directory for an entry describing
1.1 deraadt 199: an account on the remote machine.
200: If no entry exists,
1.6 millert 201: .Nm
1.1 deraadt 202: will prompt for the remote machine login name (default is the user
1.98 jmc 203: identity on the local machine) and, if necessary, prompt for a password
1.47 jmc 204: and an account with which to log in.
1.17 millert 205: .It Fl o Ar output
1.42 jmc 206: When fetching a single file or URL, save the contents in
1.17 millert 207: .Ar output .
1.22 aaron 208: To make the contents go to stdout,
1.17 millert 209: use
1.48 jmc 210: .Sq -
1.17 millert 211: for
212: .Ar output .
1.42 jmc 213: .It Fl P Ar port
214: Sets the port number to
215: .Ar port .
1.6 millert 216: .It Fl p
217: Enable passive mode operation for use behind connection filtering firewalls.
1.16 millert 218: This option has been deprecated as
219: .Nm
220: now tries to use passive mode by default, falling back to active mode
221: if the server does not support passive connections.
1.42 jmc 222: .It Fl r Ar seconds
223: Retry to connect if failed, pausing for number of
224: .Ar seconds .
1.89 jca 225: .It Fl S Ar ssl_options
226: SSL/TLS options to use with HTTPS transfers.
227: The following settings are available:
228: .Bl -tag -width Ds
229: .It Cm cafile Ns = Ns Ar /path/to/cert.pem
230: PEM encoded file containing CA certificates used for certificate
231: validation.
232: .It Cm capath Ns = Ns Ar /path/to/certs/
233: Directory containing PEM encoded CA certificates used for certificate
234: validation.
1.92 jmc 235: Such a directory can be prepared using the c_rehash script distributed with
236: OpenSSL.
1.89 jca 237: .It Cm ciphers Ns = Ns Ar cipher_list
238: Specify the list of ciphers that will be used by
239: .Nm .
240: See the
241: .Xr openssl 1
242: .Cm ciphers
243: subcommand.
244: .It Cm depth Ns = Ns Ar max_depth
245: Maximum depth of the certificate chain allowed when performing
246: validation.
247: .It Cm do
248: Perform server certificate validation.
249: .It Cm dont
250: Don't perform server certificate validation.
251: .El
252: .Pp
253: By default, server certificate validation is performed, and if it fails
254: .Nm
255: will abort.
256: If no
257: .Cm cafile
258: or
259: .Cm capath
260: setting is provided,
261: .Pa /etc/ssl/cert.pem
262: will be used.
1.82 haesbaer 263: .It Fl s Ar srcaddr
264: Use
265: .Ar srcaddr
266: on the local machine as the source address
267: of the connection.
268: Only useful on systems with more than one address.
1.6 millert 269: .It Fl t
270: Enables packet tracing.
1.93 lteo 271: .It Fl U Ar useragent
272: Set
273: .Ar useragent
274: as the User-Agent for HTTP(S) URL requests.
1.94 bentley 275: If not specified, the default User-Agent is
276: .Dq OpenBSD ftp .
1.42 jmc 277: .It Fl V
278: Disable verbose mode, overriding the default of enabled when input
279: is from a terminal.
1.6 millert 280: .It Fl v
281: Enable verbose mode.
282: This is the default if input is from a terminal.
283: Forces
284: .Nm
285: to show all responses from the remote server, as well
286: as report on data transfer statistics.
1.1 deraadt 287: .El
288: .Pp
1.43 jmc 289: The host with which
1.6 millert 290: .Nm
1.1 deraadt 291: is to communicate may be specified on the command line.
292: If this is done,
1.6 millert 293: .Nm
1.1 deraadt 294: will immediately attempt to establish a connection to an
1.48 jmc 295: FTP server on that host; otherwise,
1.6 millert 296: .Nm
1.1 deraadt 297: will enter its command interpreter and await instructions
298: from the user.
299: When
1.6 millert 300: .Nm
1.42 jmc 301: is awaiting commands, the prompt
1.51 jmc 302: .Dq ftp\*(Gt
1.1 deraadt 303: is provided to the user.
304: The following commands are recognized
305: by
1.48 jmc 306: .Nm :
1.1 deraadt 307: .Bl -tag -width Fl
1.73 sobrado 308: .It Ic \&! Oo Ar command
309: .Op Ar arg ...
310: .Oc
1.1 deraadt 311: Invoke an interactive shell on the local machine.
312: If there are arguments, the first is taken to be a command to execute
313: directly, with the rest of the arguments as its arguments.
1.73 sobrado 314: .It Ic \&$ Ar macro-name Op Ar arg ...
1.1 deraadt 315: Execute the macro
316: .Ar macro-name
317: that was defined with the
318: .Ic macdef
319: command.
320: Arguments are passed to the macro unglobbed.
1.42 jmc 321: .It Ic \&? Op Ar command
322: A synonym for
323: .Ic help .
1.73 sobrado 324: .It Ic account Op Ar password
1.1 deraadt 325: Supply a supplemental password required by a remote system for access
326: to resources once a login has been successfully completed.
327: If no argument is included, the user will be prompted for an account
328: password in a non-echoing input mode.
329: .It Ic append Ar local-file Op Ar remote-file
330: Append a local file to a file on the remote machine.
331: If
332: .Ar remote-file
333: is left unspecified, the local file name is used in naming the
334: remote file after being altered by any
335: .Ic ntrans
336: or
337: .Ic nmap
338: setting.
339: File transfer uses the current settings for
1.29 aaron 340: .Ic type ,
1.1 deraadt 341: .Ic format ,
1.29 aaron 342: .Ic mode ,
1.1 deraadt 343: and
344: .Ic structure .
345: .It Ic ascii
346: Set the file transfer
347: .Ic type
348: to network
349: .Tn ASCII .
1.73 sobrado 350: .It Ic bell Op Ic on | off
1.1 deraadt 351: Arrange that a bell be sounded after each file transfer
352: command is completed.
353: .It Ic binary
354: Set the file transfer
355: .Ic type
356: to support binary image transfer.
1.73 sobrado 357: This is the default type.
1.1 deraadt 358: .It Ic bye
1.48 jmc 359: Terminate the FTP session with the remote server and exit
360: .Nm .
1.22 aaron 361: An end-of-file will also terminate the session and exit.
1.73 sobrado 362: .It Ic case Op Ic on | off
1.1 deraadt 363: Toggle remote computer file name case mapping during
364: .Ic mget
365: commands.
366: When
367: .Ic case
368: is on (default is off), remote computer file names with all letters in
369: upper case are written in the local directory with the letters mapped
370: to lower case.
1.42 jmc 371: .It Ic cd Ar remote-directory
1.1 deraadt 372: Change the working directory on the remote machine
373: to
1.6 millert 374: .Ar remote-directory .
1.1 deraadt 375: .It Ic cdup
376: Change the remote machine working directory to the parent of the
377: current remote machine working directory.
1.73 sobrado 378: .It Ic chmod Ar mode file
379: Change the permission modes of
380: .Ar file
1.1 deraadt 381: on the remote
1.6 millert 382: system to
383: .Ar mode .
1.1 deraadt 384: .It Ic close
1.48 jmc 385: Terminate the FTP session with the remote server and
1.1 deraadt 386: return to the command interpreter.
387: Any defined macros are erased.
1.73 sobrado 388: .It Ic cr Op Ic on | off
1.1 deraadt 389: Toggle carriage return stripping during
1.22 aaron 390: ASCII type file retrieval.
1.1 deraadt 391: Records are denoted by a carriage return/linefeed sequence
1.22 aaron 392: during ASCII type file transfer.
1.1 deraadt 393: When
1.42 jmc 394: .Ic cr
1.1 deraadt 395: is on (the default), carriage returns are stripped from this
396: sequence to conform with the
397: .Ux
1.42 jmc 398: single linefeed record delimiter.
399: Records on non-UNIX
1.1 deraadt 400: remote systems may contain single linefeeds;
1.22 aaron 401: when an ASCII type transfer is made, these linefeeds may be
1.1 deraadt 402: distinguished from a record delimiter only when
1.42 jmc 403: .Ic cr
1.1 deraadt 404: is off.
1.73 sobrado 405: .It Ic debug Oo Ic on | off |
406: .Ar debuglevel
407: .Oc
1.1 deraadt 408: Toggle debugging mode.
409: If an optional
1.73 sobrado 410: .Ar debuglevel
1.42 jmc 411: is specified, it is used to set the debugging level.
1.1 deraadt 412: When debugging is on,
1.6 millert 413: .Nm
1.7 millert 414: prints each command sent to the remote machine,
415: preceded by the string
1.51 jmc 416: .Ql --\*(Gt .
1.42 jmc 417: .It Ic delete Ar remote-file
418: Delete the file
419: .Ar remote-file
420: on the remote machine.
1.6 millert 421: .It Ic dir Op Ar remote-directory Op Ar local-file
1.30 millert 422: A synonym for
423: .Ic ls .
1.1 deraadt 424: .It Ic disconnect
425: A synonym for
1.6 millert 426: .Ic close .
1.73 sobrado 427: .It Ic edit Op Ic on | off
1.6 millert 428: Toggle command line editing, and context sensitive command and file
429: completion.
430: This is automatically enabled if input is from a terminal, and
431: disabled otherwise.
1.73 sobrado 432: .It Ic epsv4 Op Ic on | off
1.31 itojun 433: Toggle use of EPSV/EPRT command on IPv4 connection.
1.6 millert 434: .It Ic exit
435: A synonym for
436: .Ic bye .
1.1 deraadt 437: .It Ic form Ar format
438: Set the file transfer
439: .Ic form
440: to
1.6 millert 441: .Ar format .
1.42 jmc 442: The default format is
443: .Dq file .
444: .It Ic ftp Ar host Op Ar port
445: A synonym for
446: .Ic open .
1.73 sobrado 447: .It Ic gate Oo Ic on | off |
448: .Ar host Op Ar port
449: .Oc
1.42 jmc 450: Toggle gate-ftp mode.
451: This will not be permitted if the gate-ftp server hasn't been set
452: (either explicitly by the user, or from the
453: .Ev FTPSERVER
454: environment variable).
455: If
456: .Ar host
457: is given,
458: then gate-ftp mode will be enabled, and the gate-ftp server will be set to
459: .Ar host .
460: If
461: .Ar port
462: is also given, that will be used as the port to connect to on the
463: gate-ftp server.
1.1 deraadt 464: .It Ic get Ar remote-file Op Ar local-file
465: Retrieve the
466: .Ar remote-file
467: and store it on the local machine.
468: If the local
469: file name is not specified, it is given the same
470: name it has on the remote machine, subject to
471: alteration by the current
1.29 aaron 472: .Ic case ,
1.1 deraadt 473: .Ic ntrans ,
474: and
475: .Ic nmap
476: settings.
477: The current settings for
1.29 aaron 478: .Ic type ,
1.1 deraadt 479: .Ic form ,
1.29 aaron 480: .Ic mode ,
1.1 deraadt 481: and
482: .Ic structure
483: are used while transferring the file.
1.73 sobrado 484: .It Ic glob Op Ic on | off
1.1 deraadt 485: Toggle filename expansion for
1.29 aaron 486: .Ic mdelete ,
1.1 deraadt 487: .Ic mget
488: and
1.6 millert 489: .Ic mput .
1.1 deraadt 490: If globbing is turned off with
1.29 aaron 491: .Ic glob ,
1.1 deraadt 492: the file name arguments
493: are taken literally and not expanded.
494: Globbing for
495: .Ic mput
496: is done as in
497: .Xr csh 1 .
498: For
499: .Ic mdelete
500: and
1.29 aaron 501: .Ic mget ,
1.1 deraadt 502: each remote file name is expanded
503: separately on the remote machine and the lists are not merged.
504: Expansion of a directory name is likely to be
505: different from expansion of the name of an ordinary file:
1.48 jmc 506: the exact result depends on the foreign operating system and FTP server,
1.1 deraadt 507: and can be previewed by doing
1.42 jmc 508: .Dq mls remote-files - .
1.1 deraadt 509: Note:
510: .Ic mget
511: and
512: .Ic mput
513: are not meant to transfer
514: entire directory subtrees of files.
515: That can be done by
516: transferring a
517: .Xr tar 1
518: archive of the subtree (in binary mode).
1.73 sobrado 519: .It Ic hash Oo Ic on | off |
520: .Ar size
521: .Oc
1.29 aaron 522: Toggle hash mark
523: .Pq Ql #
524: printing for each data block transferred.
1.5 kstailey 525: The size of a data block defaults to 1024 bytes.
1.6 millert 526: This can be changed by specifying
527: .Ar size
528: in bytes.
1.1 deraadt 529: .It Ic help Op Ar command
530: Print an informative message about the meaning of
1.6 millert 531: .Ar command .
1.1 deraadt 532: If no argument is given,
1.6 millert 533: .Nm
1.1 deraadt 534: prints a list of the known commands.
535: .It Ic idle Op Ar seconds
536: Set the inactivity timer on the remote server to
537: .Ar seconds
538: seconds.
539: If
540: .Ar seconds
541: is omitted, the current inactivity timer is printed.
1.73 sobrado 542: .It Ic lcd Op Ar local-directory
1.1 deraadt 543: Change the working directory on the local machine.
544: If
545: no
1.73 sobrado 546: .Ar local-directory
1.1 deraadt 547: is specified, the user's home directory is used.
1.10 millert 548: .It Ic less Ar file
549: A synonym for
550: .Ic page .
1.6 millert 551: .It Ic lpwd
552: Print the working directory on the local machine.
1.42 jmc 553: .It Ic ls Op Ar remote-directory Op Ar local-file
554: Print a listing of the contents of a directory on the remote machine.
1.30 millert 555: The listing includes any system-dependent information that the server
556: chooses to include; for example, most
557: .Ux
1.42 jmc 558: systems will produce output from the command
559: .Ql ls -l .
1.1 deraadt 560: If
561: .Ar remote-directory
562: is left unspecified, the current working directory is used.
563: If interactive prompting is on,
1.6 millert 564: .Nm
1.1 deraadt 565: will prompt the user to verify that the last argument is indeed the
566: target local file for receiving
1.6 millert 567: .Ic ls
1.1 deraadt 568: output.
569: If no local file is specified, or if
570: .Ar local-file
571: is
1.49 jmc 572: .Sq - ,
1.1 deraadt 573: the output is sent to the terminal.
574: .It Ic macdef Ar macro-name
575: Define a macro.
576: Subsequent lines are stored as the macro
1.29 aaron 577: .Ar macro-name ;
1.1 deraadt 578: a null line (consecutive newline characters
579: in a file or
580: carriage returns from the terminal) terminates macro input mode.
581: There is a limit of 16 macros and 4096 total characters in all
582: defined macros.
1.50 jmc 583: Macro names can be a maximum of 8 characters.
584: Macros are only applicable to the current session they are
585: defined in (or if defined outside a session, to the session
586: invoked with the next
587: .Ic open
588: command), and remain defined until a
1.1 deraadt 589: .Ic close
590: command is executed.
1.51 jmc 591: To invoke a macro,
1.52 jmc 592: use the
593: .Ic $
594: command (see above).
1.51 jmc 595: .Pp
1.29 aaron 596: The macro processor interprets
597: .Ql $
598: and
599: .Ql \e
600: as special characters.
601: A
602: .Ql $
603: followed by a number (or numbers) is replaced by the
1.1 deraadt 604: corresponding argument on the macro invocation command line.
1.29 aaron 605: A
606: .Ql $
607: followed by an
608: .Sq i
609: tells the macro processor that the
1.1 deraadt 610: executing macro is to be looped.
1.29 aaron 611: On the first pass
612: .Ql $i
613: is
1.1 deraadt 614: replaced by the first argument on the macro invocation command line,
615: on the second pass it is replaced by the second argument, and so on.
1.29 aaron 616: A
617: .Ql \e
618: followed by any character is replaced by that character.
619: Use the
620: .Ql \e
621: to prevent special treatment of the
622: .Ql $ .
1.1 deraadt 623: .It Ic mdelete Op Ar remote-files
624: Delete the
625: .Ar remote-files
626: on the remote machine.
627: .It Ic mdir Ar remote-files local-file
1.30 millert 628: A synonym for
629: .Ic mls .
1.70 martynas 630: .It Xo Ic mget
1.74 martynas 631: .Op Fl cnr
632: .Op Fl d Ar depth
1.70 martynas 633: .Ar remote-files
634: .Xc
1.1 deraadt 635: Expand the
636: .Ar remote-files
637: on the remote machine
638: and do a
639: .Ic get
640: for each file name thus produced.
641: See
642: .Ic glob
643: for details on the filename expansion.
644: Resulting file names will then be processed according to
1.29 aaron 645: .Ic case ,
1.1 deraadt 646: .Ic ntrans ,
647: and
648: .Ic nmap
649: settings.
650: Files are transferred into the local working directory,
651: which can be changed with
652: .Ql lcd directory ;
653: new local directories can be created with
654: .Ql "\&! mkdir directory" .
1.71 martynas 655: .Pp
1.74 martynas 656: The options are as follows:
657: .Bl -tag -width Ds
658: .It Fl c
659: Use
1.71 martynas 660: .Ic reget
1.74 martynas 661: instead of
1.71 martynas 662: .Ic get .
1.74 martynas 663: .It Fl d Ar depth
664: Specify the maximum recursion level
665: .Ar depth .
666: The default is 0, which means unlimited.
667: .It Fl n
668: Use
669: .Ic newer
670: instead of
671: .Ic get .
672: .It Fl r
673: Recursively descend the directory tree, transferring all files and
674: directories.
675: .El
1.1 deraadt 676: .It Ic mkdir Ar directory-name
677: Make a directory on the remote machine.
678: .It Ic mls Ar remote-files local-file
679: Like
1.29 aaron 680: .Ic ls ,
1.1 deraadt 681: except multiple remote files may be specified,
682: and the
683: .Ar local-file
684: must be specified.
685: If interactive prompting is on,
1.6 millert 686: .Nm
1.1 deraadt 687: will prompt the user to verify that the last argument is indeed the
688: target local file for receiving
689: .Ic mls
690: output.
691: .It Ic mode Op Ar mode-name
692: Set the file transfer
693: .Ic mode
694: to
1.6 millert 695: .Ar mode-name .
1.42 jmc 696: The default mode is
697: .Dq stream
698: mode.
1.73 sobrado 699: .It Ic modtime Ar file
700: Show the last modification time of
701: .Ar file
702: on the remote machine.
1.10 millert 703: .It Ic more Ar file
704: A synonym for
705: .Ic page .
1.70 martynas 706: .It Xo Ic mput
1.85 bluhm 707: .Op Fl cr
708: .Op Fl d Ar depth
1.70 martynas 709: .Ar local-files
710: .Xc
1.1 deraadt 711: Expand wild cards in the list of local files given as arguments
712: and do a
713: .Ic put
714: for each file in the resulting list.
715: See
716: .Ic glob
717: for details of filename expansion.
718: Resulting file names will then be processed according to
719: .Ic ntrans
720: and
721: .Ic nmap
722: settings.
1.71 martynas 723: .Pp
724: If the
725: .Fl c
726: flag is specified then
1.85 bluhm 727: The options are as follows:
728: .Bl -tag -width Ds
729: .It Fl c
730: Use
1.71 martynas 731: .Ic reput
1.85 bluhm 732: instead of
1.71 martynas 733: .Ic put .
1.85 bluhm 734: .It Fl d Ar depth
735: Specify the maximum recursion level
736: .Ar depth .
737: The default is 0, which means unlimited.
738: .It Fl r
739: Recursively descend the directory tree, transferring all files and
740: directories.
741: .El
1.73 sobrado 742: .It Xo Ic msend
743: .Op Fl c
744: .Ar local-files
745: .Xc
1.6 millert 746: A synonym for
747: .Ic mput .
1.73 sobrado 748: .It Ic newer Ar remote-file Op Ar local-file
1.1 deraadt 749: Get the file only if the modification time of the remote file is more
1.22 aaron 750: recent than the file on the current system.
1.1 deraadt 751: If the file does not
752: exist on the current system, the remote file is considered
1.6 millert 753: .Ic newer .
1.1 deraadt 754: Otherwise, this command is identical to
1.6 millert 755: .Ar get .
756: .It Ic nlist Op Ar remote-directory Op Ar local-file
1.30 millert 757: Print a list of the files in a
758: directory on the remote machine.
759: If
760: .Ar remote-directory
761: is left unspecified, the current working directory is used.
762: If interactive prompting is on,
763: .Nm
764: will prompt the user to verify that the last argument is indeed the
765: target local file for receiving
766: .Ic nlist
767: output.
768: If no local file is specified, or if
769: .Ar local-file
770: is
1.49 jmc 771: .Sq - ,
1.38 jmc 772: the output is sent to the terminal.
773: Note that on some servers, the
1.30 millert 774: .Ic nlist
775: command will only return information on normal files (not directories
776: or special files).
1.1 deraadt 777: .It Ic nmap Op Ar inpattern outpattern
778: Set or unset the filename mapping mechanism.
779: If no arguments are specified, the filename mapping mechanism is unset.
780: If arguments are specified, remote filenames are mapped during
781: .Ic mput
782: commands and
783: .Ic put
784: commands issued without a specified remote target filename.
785: If arguments are specified, local filenames are mapped during
786: .Ic mget
787: commands and
788: .Ic get
789: commands issued without a specified local target filename.
1.42 jmc 790: This command is useful when connecting to a non-UNIX remote computer
1.1 deraadt 791: with different file naming conventions or practices.
1.42 jmc 792: .Pp
1.1 deraadt 793: The mapping follows the pattern set by
794: .Ar inpattern
795: and
1.6 millert 796: .Ar outpattern .
1.22 aaron 797: .Ar inpattern
1.1 deraadt 798: is a template for incoming filenames (which may have already been
799: processed according to the
800: .Ic ntrans
801: and
802: .Ic case
803: settings).
804: Variable templating is accomplished by including the
1.29 aaron 805: sequences
806: .Ql $1 ,
807: .Ql $2 ,
1.44 jmc 808: \&...,
1.29 aaron 809: .Ql $9
810: in
1.6 millert 811: .Ar inpattern .
1.29 aaron 812: Use
813: .Ql \e
814: to prevent this special treatment of the
815: .Ql $
816: character.
1.1 deraadt 817: All other characters are treated literally, and are used to determine the
818: .Ic nmap
1.22 aaron 819: .Ar inpattern
1.1 deraadt 820: variable values.
1.45 jmc 821: .Pp
1.1 deraadt 822: For example, given
823: .Ar inpattern
824: $1.$2 and the remote file name "mydata.data", $1 would have the value
825: "mydata", and $2 would have the value "data".
826: The
827: .Ar outpattern
828: determines the resulting mapped filename.
1.29 aaron 829: The sequences
830: .Ql $1 ,
831: .Ql $2 ,
1.42 jmc 832: \&...,
1.29 aaron 833: .Ql $9
834: are replaced by any value resulting from the
1.1 deraadt 835: .Ar inpattern
836: template.
1.29 aaron 837: The sequence
838: .Ql $0
839: is replaced by the original filename.
1.1 deraadt 840: Additionally, the sequence
1.40 jmc 841: .Sq Op Ar seq1 , Ar seq2
1.1 deraadt 842: is replaced by
1.45 jmc 843: .Ar seq1
1.1 deraadt 844: if
845: .Ar seq1
846: is not a null string; otherwise it is replaced by
847: .Ar seq2 .
1.42 jmc 848: For example:
1.1 deraadt 849: .Pp
1.42 jmc 850: .Dl nmap $1.$2.$3 [$1,$2].[$2,file]
1.1 deraadt 851: .Pp
1.42 jmc 852: This command would yield the output filename
853: .Pa myfile.data
1.29 aaron 854: for input filenames
855: .Pa myfile.data
856: and
1.42 jmc 857: .Pa myfile.data.old ;
1.29 aaron 858: .Pa myfile.file
859: for the input filename
1.42 jmc 860: .Pa myfile ;
1.29 aaron 861: and
862: .Pa myfile.myfile
863: for the input filename
1.42 jmc 864: .Pa .myfile .
1.1 deraadt 865: Spaces may be included in
1.46 jmc 866: .Ar outpattern
867: by quoting them,
868: as in the following example:
1.42 jmc 869: .Bd -literal -offset indent
1.46 jmc 870: nmap $1.$2 "$1 $2"
1.29 aaron 871: .Ed
872: .Pp
873: Use the
874: .Ql \e
875: character to prevent special treatment
876: of the
877: .Ql $ ,
1.80 schwarze 878: .Ql \&[ ,
1.29 aaron 879: .Ql \&] ,
880: and
881: .Ql \&,
882: characters.
1.1 deraadt 883: .It Ic ntrans Op Ar inchars Op Ar outchars
884: Set or unset the filename character translation mechanism.
885: If no arguments are specified, the filename character
886: translation mechanism is unset.
887: If arguments are specified, characters in
888: remote filenames are translated during
889: .Ic mput
890: commands and
891: .Ic put
892: commands issued without a specified remote target filename.
893: If arguments are specified, characters in
894: local filenames are translated during
895: .Ic mget
896: commands and
897: .Ic get
898: commands issued without a specified local target filename.
1.42 jmc 899: This command is useful when connecting to a non-UNIX remote computer
1.1 deraadt 900: with different file naming conventions or practices.
901: Characters in a filename matching a character in
902: .Ar inchars
903: are replaced with the corresponding character in
1.6 millert 904: .Ar outchars .
1.1 deraadt 905: If the character's position in
906: .Ar inchars
907: is longer than the length of
1.29 aaron 908: .Ar outchars ,
1.1 deraadt 909: the character is deleted from the file name.
910: .It Ic open Ar host Op Ar port
911: Establish a connection to the specified
912: .Ar host
1.48 jmc 913: FTP server.
1.42 jmc 914: An optional port number may be supplied,
1.22 aaron 915: in which case
1.6 millert 916: .Nm
1.48 jmc 917: will attempt to contact an FTP server at that port.
1.1 deraadt 918: If the
919: .Ic auto-login
920: option is on (default),
1.6 millert 921: .Nm
1.1 deraadt 922: will also attempt to automatically log the user in to
1.48 jmc 923: the FTP server (see below).
1.9 millert 924: .It Ic page Ar file
925: Retrieve
926: .Ic file
927: and display with the program defined in
1.25 aaron 928: .Ev PAGER
1.26 pjanzen 929: (defaulting to
930: .Xr more 1
931: if
932: .Ev PAGER
933: is null or not defined).
1.73 sobrado 934: .It Ic passive Op Ic on | off
1.29 aaron 935: Toggle passive mode.
1.48 jmc 936: If passive mode is turned on (default is on),
937: .Nm
938: will send a
1.57 jmc 939: .Dv EPSV
1.1 deraadt 940: command for all data connections instead of the usual
941: .Dv PORT
1.29 aaron 942: command.
943: The
1.1 deraadt 944: .Dv PASV
945: command requests that the remote server open a port for the data connection
1.29 aaron 946: and return the address of that port.
947: The remote server listens on that port and the client connects to it.
948: When using the more traditional
1.1 deraadt 949: .Dv PORT
950: command, the client listens on a port and sends that address to the remote
1.29 aaron 951: server, who connects back to it.
952: Passive mode is useful when using
1.6 millert 953: .Nm
1.1 deraadt 954: through a gateway router or host that controls the directionality of
955: traffic.
1.48 jmc 956: (Note that though FTP servers are required to support the
1.1 deraadt 957: .Dv PASV
958: command by RFC 1123, some do not.)
1.73 sobrado 959: .It Ic preserve Op Ic on | off
1.6 millert 960: Toggle preservation of modification times on retrieved files.
1.73 sobrado 961: .It Ic progress Op Ic on | off
1.6 millert 962: Toggle display of transfer progress bar.
1.9 millert 963: The progress bar will be disabled for a transfer that has
964: .Ar local-file
965: as
1.48 jmc 966: .Sq -
1.9 millert 967: or a command that starts with
968: .Sq \&| .
969: Refer to
970: .Sx FILE NAMING CONVENTIONS
971: for more information.
1.73 sobrado 972: .It Ic prompt Op Ic on | off
1.1 deraadt 973: Toggle interactive prompting.
974: Interactive prompting
975: occurs during multiple file transfers to allow the
976: user to selectively retrieve or store files.
977: If prompting is turned off (default is on), any
978: .Ic mget
979: or
980: .Ic mput
981: will transfer all files, and any
982: .Ic mdelete
983: will delete all files.
1.6 millert 984: .Pp
985: When prompting is on, the following commands are available at a prompt:
986: .Bl -tag -width 2n -offset indent
1.69 martynas 987: .It Ic ?\&
988: Print help message.
1.6 millert 989: .It Ic a
990: Answer
1.22 aaron 991: .Dq yes
992: to the current file and automatically answer
993: .Dq yes
1.6 millert 994: to any remaining files for the current command.
1.42 jmc 995: .It Ic n
996: Do not transfer the file.
1.6 millert 997: .It Ic p
998: Answer
1.22 aaron 999: .Dq yes
1000: to the current file and turn off prompt mode
1001: (as if
1.6 millert 1002: .Dq prompt off
1003: had been given).
1.69 martynas 1004: .It Ic q
1005: Answer
1006: .Dq no
1007: to the current file and automatically answer
1008: .Dq no
1009: to any remaining files for the current command.
1.42 jmc 1010: .It Ic y
1011: Transfer the file.
1.6 millert 1012: .El
1.73 sobrado 1013: .It Ic proxy Ar command
1.48 jmc 1014: Execute an FTP command on a secondary control connection.
1015: This command allows simultaneous connection to two remote FTP
1.1 deraadt 1016: servers for transferring files between the two servers.
1017: The first
1018: .Ic proxy
1019: command should be an
1.29 aaron 1020: .Ic open ,
1.1 deraadt 1021: to establish the secondary control connection.
1.29 aaron 1022: Enter the command
1.41 jmc 1023: .Ic proxy ?\&
1.48 jmc 1024: to see other FTP commands executable on the
1.1 deraadt 1025: secondary connection.
1026: The following commands behave differently when prefaced by
1.29 aaron 1027: .Ic proxy :
1.1 deraadt 1028: .Ic open
1.42 jmc 1029: will not define new macros during the auto-login process;
1.1 deraadt 1030: .Ic close
1.42 jmc 1031: will not erase existing macro definitions;
1.1 deraadt 1032: .Ic get
1033: and
1034: .Ic mget
1035: transfer files from the host on the primary control connection
1.42 jmc 1036: to the host on the secondary control connection; and
1.29 aaron 1037: .Ic put ,
1.1 deraadt 1038: .Ic mput ,
1039: and
1040: .Ic append
1041: transfer files from the host on the secondary control connection
1042: to the host on the primary control connection.
1.48 jmc 1043: Third party file transfers depend upon support of the FTP protocol
1.1 deraadt 1044: .Dv PASV
1045: command by the server on the secondary control connection.
1046: .It Ic put Ar local-file Op Ar remote-file
1047: Store a local file on the remote machine.
1048: If
1049: .Ar remote-file
1050: is left unspecified, the local file name is used
1051: after processing according to any
1052: .Ic ntrans
1053: or
1054: .Ic nmap
1055: settings
1056: in naming the remote file.
1057: File transfer uses the
1058: current settings for
1.29 aaron 1059: .Ic type ,
1.1 deraadt 1060: .Ic format ,
1.29 aaron 1061: .Ic mode ,
1.1 deraadt 1062: and
1.6 millert 1063: .Ic structure .
1.1 deraadt 1064: .It Ic pwd
1065: Print the name of the current working directory on the remote
1066: machine.
1067: .It Ic quit
1068: A synonym for
1.6 millert 1069: .Ic bye .
1.73 sobrado 1070: .It Ic quote Ar arg ...
1.48 jmc 1071: The arguments specified are sent, verbatim, to the remote FTP server.
1.1 deraadt 1072: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 1073: A synonym for
1074: .Ic get .
1.1 deraadt 1075: .It Ic reget Ar remote-file Op Ar local-file
1076: Reget acts like get, except that if
1077: .Ar local-file
1078: exists and is
1079: smaller than
1.29 aaron 1080: .Ar remote-file ,
1.1 deraadt 1081: .Ar local-file
1082: is presumed to be
1083: a partially transferred copy of
1084: .Ar remote-file
1085: and the transfer
1086: is continued from the apparent point of failure.
1087: This command
1088: is useful when transferring very large files over networks that
1089: are prone to dropping connections.
1.73 sobrado 1090: .It Ic rename Ar from-name to-name
1.1 deraadt 1091: Rename the file
1.73 sobrado 1092: .Ar from-name
1.22 aaron 1093: on the remote machine to the file
1.73 sobrado 1094: .Ar to-name .
1.70 martynas 1095: .It Ic reput Ar local-file Op Ar remote-file
1096: Reput acts like put, except that if
1097: .Ar remote-file
1098: exists and is
1099: smaller than
1100: .Ar local-file ,
1101: .Ar remote-file
1102: is presumed to be
1103: a partially transferred copy of
1104: .Ar local-file
1105: and the transfer
1106: is continued from the apparent point of failure.
1107: This command
1108: is useful when transferring very large files over networks that
1109: are prone to dropping connections.
1.1 deraadt 1110: .It Ic reset
1111: Clear reply queue.
1112: This command re-synchronizes command/reply sequencing with the remote
1.48 jmc 1113: FTP server.
1114: Resynchronization may be necessary following a violation of the FTP protocol
1.1 deraadt 1115: by the remote server.
1116: .It Ic restart Ar marker
1117: Restart the immediately following
1118: .Ic get
1119: or
1120: .Ic put
1121: at the
1122: indicated
1.6 millert 1123: .Ar marker .
1.1 deraadt 1124: On
1125: .Ux
1.22 aaron 1126: systems,
1127: .Ar marker
1128: is usually a byte
1.1 deraadt 1129: offset into the file.
1.42 jmc 1130: .It Ic rhelp Op Ar command-name
1.48 jmc 1131: Request help from the remote FTP server.
1.42 jmc 1132: If a
1133: .Ar command-name
1134: is specified, it is supplied to the server as well.
1.1 deraadt 1135: .It Ic rmdir Ar directory-name
1136: Delete a directory on the remote machine.
1.73 sobrado 1137: .It Ic rstatus Op Ar file
1.42 jmc 1138: With no arguments, show status of remote machine.
1139: If
1.73 sobrado 1140: .Ar file
1.42 jmc 1141: is specified, show status of
1.73 sobrado 1142: .Ar file
1.42 jmc 1143: on remote machine.
1.73 sobrado 1144: .It Ic runique Op Ic on | off
1.1 deraadt 1145: Toggle storing of files on the local system with unique filenames.
1146: If a file already exists with a name equal to the target
1147: local filename for a
1148: .Ic get
1149: or
1150: .Ic mget
1.29 aaron 1151: command, a
1.42 jmc 1152: .Dq .1
1.29 aaron 1153: is appended to the name.
1.1 deraadt 1154: If the resulting name matches another existing file,
1.29 aaron 1155: a
1.42 jmc 1156: .Dq .2
1.29 aaron 1157: is appended to the original name.
1158: If this process continues up to
1.42 jmc 1159: .Dq .99 ,
1160: an error message is printed, and the transfer does not take place.
1.1 deraadt 1161: The generated unique filename will be reported.
1162: Note that
1163: .Ic runique
1164: will not affect local files generated from a shell command
1165: (see below).
1166: The default value is off.
1167: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 1168: A synonym for
1169: .Ic put .
1.73 sobrado 1170: .It Ic sendport Op Ic on | off
1.1 deraadt 1171: Toggle the use of
1172: .Dv PORT
1173: commands.
1174: By default,
1.6 millert 1175: .Nm
1.1 deraadt 1176: will attempt to use a
1177: .Dv PORT
1178: command when establishing
1179: a connection for each data transfer.
1180: The use of
1181: .Dv PORT
1182: commands can prevent delays
1183: when performing multiple file transfers.
1184: If the
1185: .Dv PORT
1186: command fails,
1.6 millert 1187: .Nm
1.1 deraadt 1188: will use the default data port.
1189: When the use of
1190: .Dv PORT
1191: commands is disabled, no attempt will be made to use
1192: .Dv PORT
1193: commands for each data transfer.
1.48 jmc 1194: This is useful for certain FTP implementations which do ignore
1.1 deraadt 1195: .Dv PORT
1196: commands but, incorrectly, indicate they've been accepted.
1.73 sobrado 1197: .It Ic site Ar arg ...
1.48 jmc 1198: The arguments specified are sent, verbatim, to the remote FTP server as a
1.1 deraadt 1199: .Dv SITE
1200: command.
1.73 sobrado 1201: .It Ic size Ar file
1.1 deraadt 1202: Return size of
1.73 sobrado 1203: .Ar file
1.1 deraadt 1204: on remote machine.
1205: .It Ic status
1206: Show the current status of
1.48 jmc 1207: .Nm .
1.42 jmc 1208: .\" .It Ic struct Op Ar struct-name
1209: .\" Set the file transfer
1210: .\" .Ar structure
1211: .\" to
1212: .\" .Ar struct-name .
1213: .\" By default,
1214: .\" .Dq file
1215: .\" structure is used.
1.73 sobrado 1216: .It Ic sunique Op Ic on | off
1.1 deraadt 1217: Toggle storing of files on remote machine under unique file names.
1.48 jmc 1218: The remote FTP server must support the FTP protocol
1.1 deraadt 1219: .Dv STOU
1220: command for
1221: successful completion.
1.42 jmc 1222: The remote server will report the unique name.
1.1 deraadt 1223: Default value is off.
1224: .It Ic system
1225: Show the type of operating system running on the remote machine.
1.73 sobrado 1226: .It Ic trace Op Ic on | off
1.1 deraadt 1227: Toggle packet tracing.
1228: .It Ic type Op Ar type-name
1229: Set the file transfer
1230: .Ic type
1231: to
1.6 millert 1232: .Ar type-name .
1.1 deraadt 1233: If no type is specified, the current type
1234: is printed.
1.42 jmc 1235: The default type is
1236: .Dq binary .
1.1 deraadt 1237: .It Ic umask Op Ar newmask
1238: Set the default umask on the remote server to
1.6 millert 1239: .Ar newmask .
1.1 deraadt 1240: If
1241: .Ar newmask
1242: is omitted, the current umask is printed.
1243: .It Xo
1.73 sobrado 1244: .Ic user Ar username
1.6 millert 1245: .Op Ar password Op Ar account
1.1 deraadt 1246: .Xc
1.48 jmc 1247: Identify yourself to the remote FTP server.
1.1 deraadt 1248: If the
1249: .Ar password
1250: is not specified and the server requires it,
1.6 millert 1251: .Nm
1.1 deraadt 1252: will prompt the user for it (after disabling local echo).
1253: If an
1254: .Ar account
1.48 jmc 1255: field is not specified, and the FTP server requires it,
1256: the user will be prompted for it.
1.1 deraadt 1257: If an
1258: .Ar account
1259: field is specified, an account command will
1260: be relayed to the remote server after the login sequence
1261: is completed if the remote server did not require it
1262: for logging in.
1263: Unless
1.6 millert 1264: .Nm
1.42 jmc 1265: is invoked with
1266: .Dq auto-login
1267: disabled, this process is done automatically on initial connection to the
1.48 jmc 1268: FTP server.
1.73 sobrado 1269: .It Ic verbose Op Ic on | off
1.1 deraadt 1270: Toggle verbose mode.
1271: In verbose mode, all responses from
1.48 jmc 1272: the FTP server are displayed to the user.
1.1 deraadt 1273: In addition,
1274: if verbose is on, when a file transfer completes, statistics
1275: regarding the efficiency of the transfer are reported.
1276: By default,
1277: verbose is on.
1278: .El
1279: .Pp
1280: Command arguments which have embedded spaces may be quoted with
1.29 aaron 1281: quote
1.42 jmc 1282: .Pq Ql \&"
1.29 aaron 1283: marks.
1.6 millert 1284: .Pp
1285: Commands which toggle settings can take an explicit
1286: .Ic on
1287: or
1288: .Ic off
1289: argument to force the setting appropriately.
1290: .Pp
1291: If
1292: .Nm
1293: receives a
1294: .Dv SIGINFO
1295: (see the
1296: .Dq status
1297: argument of
1298: .Xr stty 1 )
1299: signal whilst a transfer is in progress, the current transfer rate
1300: statistics will be written to the standard error output, in the
1301: same format as the standard completion message.
1302: .Sh AUTO-FETCHING FILES
1303: In addition to standard commands, this version of
1304: .Nm
1305: supports an auto-fetch feature.
1306: To enable auto-fetch, simply pass the list of hostnames/files
1307: on the command line.
1308: .Pp
1309: The following formats are valid syntax for an auto-fetch element:
1.56 ray 1310: .Bl -tag -width Ds
1.99 schwarze 1311: .It Ar host : Ns / Ns Ar file Ns Op /
1.6 millert 1312: .Dq Classic
1.48 jmc 1313: .Nm
1314: format.
1.99 schwarze 1315: .Sm off
1316: .It Xo
1.100 schwarze 1317: .Pf ftp:// Op Ar user : password No @
1.99 schwarze 1318: .Ar host Op : Ar port
1319: .No / Ar file Op /
1320: .Xc
1321: .Sm on
1.48 jmc 1322: An FTP URL, retrieved using the FTP protocol if
1.10 millert 1323: .Ev ftp_proxy
1324: isn't defined.
1.48 jmc 1325: Otherwise, transfer using HTTP via the proxy defined in
1.10 millert 1326: .Ev ftp_proxy .
1.84 lteo 1327: If a
1328: .Ar user
1329: and
1330: .Ar password
1331: are given and
1.11 millert 1332: .Ev ftp_proxy
1.84 lteo 1333: isn't defined,
1334: log in as
1.11 millert 1335: .Ar user
1336: with a password of
1337: .Ar password .
1.99 schwarze 1338: .Sm off
1339: .It Xo
1.100 schwarze 1340: .Pf http:// Op Ar user : password No @
1.99 schwarze 1341: .Ar host Op : Ar port
1342: .No / Ar file
1343: .Xc
1344: .Sm on
1.48 jmc 1345: An HTTP URL, retrieved using the HTTP protocol.
1.6 millert 1346: If
1347: .Ev http_proxy
1348: is defined, it is used as a URL to an HTTP proxy server.
1.84 lteo 1349: If a
1350: .Ar user
1351: and
1352: .Ar password
1353: are given and
1354: .Ev http_proxy
1355: isn't defined,
1356: log in as
1357: .Ar user
1358: with a password of
1359: .Ar password
1360: using Basic authentication.
1.99 schwarze 1361: .Sm off
1362: .It Xo
1.100 schwarze 1363: .Pf https:// Op Ar user : password No @
1.99 schwarze 1364: .Ar host Op : Ar port
1365: .No / Ar file
1366: .Xc
1367: .Sm on
1.54 deraadt 1368: An HTTPS URL, retrieved using the HTTPS protocol.
1369: If
1370: .Ev http_proxy
1371: is defined, this HTTPS proxy server will be used to fetch the
1372: file using the CONNECT method.
1.84 lteo 1373: If a
1374: .Ar user
1375: and
1376: .Ar password
1377: are given and
1378: .Ev http_proxy
1379: isn't defined,
1380: log in as
1381: .Ar user
1382: with a password of
1383: .Ar password
1384: using Basic authentication.
1.100 schwarze 1385: .It Pf file: Ar file
1.78 sobrado 1386: .Ar file
1387: is retrieved from a mounted file system.
1.6 millert 1388: .El
1389: .Pp
1.48 jmc 1390: If a classic format or an FTP URL format has a trailing
1.6 millert 1391: .Sq / ,
1392: then
1393: .Nm
1394: will connect to the site and
1395: .Ic cd
1396: to the directory given as the path, and leave the user in interactive
1397: mode ready for further input.
1398: .Pp
1.48 jmc 1399: If successive auto-fetch FTP elements refer to the same host, then
1.6 millert 1400: the connection is maintained between transfers, reducing overhead on
1401: connection creation and deletion.
1.9 millert 1402: .Pp
1403: If
1.42 jmc 1404: .Ar file
1405: contains a glob character and globbing is enabled
1.9 millert 1406: (see
1.13 millert 1407: .Ic glob ) ,
1.9 millert 1408: then the equivalent of
1.42 jmc 1409: .Ic mget Ar file
1.9 millert 1410: is performed.
1411: .Pp
1.19 d 1412: If no
1413: .Fl o
1414: option is specified, and
1415: the directory component of
1.42 jmc 1416: .Ar file
1.9 millert 1417: contains no globbing characters,
1.19 d 1418: then
1.9 millert 1419: it is stored in the current directory as the
1420: .Xr basename 1
1421: of
1.42 jmc 1422: .Ar file .
1423: If
1424: .Fl o Ar output
1425: is specified, then
1426: .Ar file
1427: is stored as
1428: .Ar output .
1.9 millert 1429: Otherwise, the remote name is used as the local name.
1.1 deraadt 1430: .Sh ABORTING A FILE TRANSFER
1431: To abort a file transfer, use the terminal interrupt key
1432: (usually Ctrl-C).
1433: Sending transfers will be immediately halted.
1.48 jmc 1434: Receiving transfers will be halted by sending an FTP protocol
1.1 deraadt 1435: .Dv ABOR
1436: command to the remote server, and discarding any further data received.
1437: The speed at which this is accomplished depends upon the remote
1438: server's support for
1439: .Dv ABOR
1440: processing.
1441: If the remote server does not support the
1442: .Dv ABOR
1443: command, an
1.51 jmc 1444: .Ql ftp\*(Gt
1.1 deraadt 1445: prompt will not appear until the remote server has completed
1446: sending the requested file.
1447: .Pp
1448: The terminal interrupt key sequence will be ignored when
1.6 millert 1449: .Nm
1.1 deraadt 1450: has completed any local processing and is awaiting a reply
1451: from the remote server.
1452: A long delay in this mode may result from the ABOR processing described
1453: above, or from unexpected behavior by the remote server, including
1.48 jmc 1454: violations of the FTP protocol.
1.1 deraadt 1455: If the delay results from unexpected remote server behavior, the local
1.6 millert 1456: .Nm
1.1 deraadt 1457: program must be killed by hand.
1458: .Sh FILE NAMING CONVENTIONS
1459: Files specified as arguments to
1.6 millert 1460: .Nm
1.1 deraadt 1461: commands are processed according to the following rules.
1462: .Bl -enum
1463: .It
1.101 ! schwarze 1464: If
1.48 jmc 1465: .Sq -
1.101 ! schwarze 1466: is specified as a local file name, the standard input (for reading)
1.29 aaron 1467: or standard output (for writing)
1468: is used.
1.1 deraadt 1469: .It
1.101 ! schwarze 1470: If the first character of a local file name is
1.1 deraadt 1471: .Sq \&| ,
1472: the
1473: remainder of the argument is interpreted as a shell command.
1.6 millert 1474: .Nm
1.1 deraadt 1475: then forks a shell, using
1476: .Xr popen 3
1.29 aaron 1477: with the argument supplied, and reads (writes) from the standard output
1478: (standard input).
1.1 deraadt 1479: If the shell command includes spaces, the argument
1.29 aaron 1480: must be quoted; e.g.,
1.42 jmc 1481: .Qq ls -lt .
1.1 deraadt 1482: A particularly
1.42 jmc 1483: useful example of this mechanism is:
1.101 ! schwarze 1484: .Qq ls \&. |more .
1.1 deraadt 1485: .It
1.29 aaron 1486: Failing the above checks, if
1487: .Dq globbing
1488: is enabled,
1.1 deraadt 1489: local file names are expanded
1490: according to the rules used in the
1.96 jmc 1491: .Xr csh 1
1.1 deraadt 1492: .Ic glob
1493: command.
1494: If the
1.6 millert 1495: .Nm
1.29 aaron 1496: command expects a single local file (e.g.,
1497: .Ic put ) ,
1498: only the first filename generated by the
1499: .Dq globbing
1500: operation is used.
1.1 deraadt 1501: .It
1502: For
1503: .Ic mget
1504: commands and
1505: .Ic get
1506: commands with unspecified local file names, the local filename is
1507: the remote filename, which may be altered by a
1.29 aaron 1508: .Ic case ,
1.1 deraadt 1509: .Ic ntrans ,
1510: or
1511: .Ic nmap
1512: setting.
1513: The resulting filename may then be altered if
1514: .Ic runique
1515: is on.
1516: .It
1517: For
1518: .Ic mput
1519: commands and
1520: .Ic put
1521: commands with unspecified remote file names, the remote filename is
1522: the local filename, which may be altered by a
1523: .Ic ntrans
1524: or
1525: .Ic nmap
1526: setting.
1527: The resulting filename may then be altered by the remote server if
1528: .Ic sunique
1529: is on.
1530: .El
1531: .Sh FILE TRANSFER PARAMETERS
1532: The FTP specification specifies many parameters which may
1533: affect a file transfer.
1534: The
1535: .Ic type
1.42 jmc 1536: may be one of
1537: .Dq ascii ,
1538: .Dq binary ,
1539: or
1.95 tedu 1540: .Dq image .
1.6 millert 1541: .Nm
1.95 tedu 1542: supports the ASCII and image types of file transfer.
1.1 deraadt 1543: .Pp
1.6 millert 1544: .Nm
1.1 deraadt 1545: supports only the default values for the remaining
1546: file transfer parameters:
1.29 aaron 1547: .Ic mode ,
1.1 deraadt 1548: .Ic form ,
1549: and
1.6 millert 1550: .Ic struct .
1.1 deraadt 1551: .Sh THE .netrc FILE
1552: The
1553: .Pa .netrc
1554: file contains login and initialization information
1555: used by the auto-login process.
1556: It resides in the user's home directory.
1557: The following tokens are recognized; they may be separated by spaces,
1558: tabs, or new-lines:
1559: .Bl -tag -width password
1560: .It Ic machine Ar name
1561: Identify a remote machine
1562: .Ar name .
1563: The auto-login process searches the
1564: .Pa .netrc
1565: file for a
1566: .Ic machine
1567: token that matches the remote machine specified on the
1.6 millert 1568: .Nm
1.1 deraadt 1569: command line or as an
1570: .Ic open
1571: command argument.
1572: Once a match is made, the subsequent
1573: .Pa .netrc
1574: tokens are processed,
1575: stopping when the end of file is reached or another
1576: .Ic machine
1577: or a
1578: .Ic default
1579: token is encountered.
1580: .It Ic default
1581: This is the same as
1582: .Ic machine
1583: .Ar name
1584: except that
1585: .Ic default
1586: matches any name.
1587: There can be only one
1588: .Ic default
1589: token, and it must be after all
1590: .Ic machine
1591: tokens.
1592: This is normally used as:
1593: .Pp
1594: .Dl default login anonymous password user@site
1595: .Pp
1596: thereby giving the user
1597: .Ar automatic
1.48 jmc 1598: anonymous FTP login to
1.1 deraadt 1599: machines not specified in
1600: .Pa .netrc .
1601: This can be overridden
1602: by using the
1603: .Fl n
1604: flag to disable auto-login.
1605: .It Ic login Ar name
1606: Identify a user on the remote machine.
1607: If this token is present, the auto-login process will initiate
1608: a login using the specified
1609: .Ar name .
1610: .It Ic password Ar string
1611: Supply a password.
1612: If this token is present, the auto-login process will supply the
1613: specified string if the remote server requires a password as part
1614: of the login process.
1615: Note that if this token is present in the
1616: .Pa .netrc
1617: file for any user other
1618: than
1.29 aaron 1619: .Ar anonymous ,
1.6 millert 1620: .Nm
1.1 deraadt 1621: will abort the auto-login process if the
1622: .Pa .netrc
1623: is readable by
1624: anyone besides the user.
1625: .It Ic account Ar string
1626: Supply an additional account password.
1627: If this token is present, the auto-login process will supply the
1628: specified string if the remote server requires an additional
1629: account password, or the auto-login process will initiate an
1630: .Dv ACCT
1631: command if it does not.
1632: .It Ic macdef Ar name
1633: Define a macro.
1634: This token functions like the
1.6 millert 1635: .Nm
1.1 deraadt 1636: .Ic macdef
1637: command functions.
1638: A macro is defined with the specified name; its contents begin with the
1639: next
1640: .Pa .netrc
1641: line and continue until a null line (consecutive new-line
1642: characters) is encountered.
1.50 jmc 1643: Like the other tokens in the
1644: .Pa .netrc
1645: file, a
1646: .Ic macdef
1647: is applicable only to the
1648: .Ic machine
1649: definition preceding it.
1650: A
1651: .Ic macdef
1652: entry cannot be utilized by multiple
1653: .Ic machine
1654: definitions; rather, it must be defined following each
1655: .Ic machine
1656: it is intended to be used with.
1.1 deraadt 1657: If a macro named
1658: .Ic init
1659: is defined, it is automatically executed as the last step in the
1660: auto-login process.
1661: .El
1.6 millert 1662: .Sh COMMAND LINE EDITING
1663: .Nm
1.25 aaron 1664: supports interactive command line editing, via the
1.6 millert 1665: .Xr editline 3
1666: library.
1667: It is enabled with the
1668: .Ic edit
1.9 millert 1669: command, and is enabled by default if input is from a tty.
1.6 millert 1670: Previous lines can be recalled and edited with the arrow keys,
1671: and other GNU Emacs-style editing keys may be used as well.
1672: .Pp
1673: The
1674: .Xr editline 3
1675: library is configured with a
1676: .Pa .editrc
1.42 jmc 1677: file \- refer to
1.6 millert 1678: .Xr editrc 5
1679: for more information.
1680: .Pp
1681: An extra key binding is available to
1682: .Nm
1683: to provide context sensitive command and filename completion
1684: (including remote file completion).
1685: To use this, bind a key to the
1686: .Xr editline 3
1687: command
1688: .Ic ftp-complete .
1689: By default, this is bound to the TAB key.
1.1 deraadt 1690: .Sh ENVIRONMENT
1.6 millert 1691: .Nm
1.22 aaron 1692: utilizes the following environment variables:
1.15 millert 1693: .Bl -tag -width "FTPSERVERPORT"
1.16 millert 1694: .It Ev FTPMODE
1.29 aaron 1695: Overrides the default operation mode.
1696: Recognized values are:
1.48 jmc 1697: .Pp
1698: .Bl -tag -width "passive " -offset indent -compact
1.16 millert 1699: .It passive
1.48 jmc 1700: passive mode FTP only
1.16 millert 1701: .It active
1.48 jmc 1702: active mode FTP only
1.16 millert 1703: .It auto
1704: automatic determination of passive or active (this is the default)
1705: .It gate
1706: gate-ftp mode
1707: .El
1.14 millert 1708: .It Ev FTPSERVER
1709: Host to use as gate-ftp server when
1710: .Ic gate
1711: is enabled.
1712: .It Ev FTPSERVERPORT
1713: Port to use when connecting to gate-ftp server when
1714: .Ic gate
1715: is enabled.
1716: Default is port returned by a
1717: .Fn getservbyname
1.25 aaron 1718: lookup of
1.14 millert 1719: .Dq ftpgate/tcp .
1.1 deraadt 1720: .It Ev HOME
1721: For default location of a
1722: .Pa .netrc
1723: file, if one exists.
1.9 millert 1724: .It Ev PAGER
1725: Used by
1726: .Ic page
1727: to display files.
1.1 deraadt 1728: .It Ev SHELL
1729: For default shell.
1.15 millert 1730: .It Ev TMPDIR
1.72 martynas 1731: Directory in which temporary files are stored.
1.10 millert 1732: .It Ev ftp_proxy
1733: URL of FTP proxy to use when making FTP URL requests
1.48 jmc 1734: (if not defined, use the standard FTP protocol).
1.6 millert 1735: .It Ev http_proxy
1.54 deraadt 1736: URL of HTTP proxy to use when making HTTP or HTTPS URL requests.
1.59 pyr 1737: .It Ev http_cookies
1.60 jmc 1738: Path of a Netscape-like cookiejar file to use when making
1.59 pyr 1739: HTTP or HTTPS URL requests.
1.1 deraadt 1740: .El
1.36 jakob 1741: .Sh PORT ALLOCATION
1.38 jmc 1742: For active mode data connections,
1.36 jakob 1743: .Nm
1.42 jmc 1744: will listen to a random high TCP port.
1.36 jakob 1745: The interval of ports used are configurable using
1.38 jmc 1746: .Xr sysctl 8
1.36 jakob 1747: variables
1.42 jmc 1748: .Va net.inet.ip.porthifirst
1.36 jakob 1749: and
1.42 jmc 1750: .Va net.inet.ip.porthilast .
1.1 deraadt 1751: .Sh SEE ALSO
1.42 jmc 1752: .Xr basename 1 ,
1753: .Xr csh 1 ,
1754: .Xr more 1 ,
1755: .Xr stty 1 ,
1756: .Xr tar 1 ,
1.28 aaron 1757: .Xr tftp 1 ,
1.42 jmc 1758: .Xr editline 3 ,
1.14 millert 1759: .Xr getservbyname 3 ,
1.42 jmc 1760: .Xr popen 3 ,
1.6 millert 1761: .Xr editrc 5 ,
1.14 millert 1762: .Xr services 5 ,
1.34 beck 1763: .Xr ftp-proxy 8 ,
1.1 deraadt 1764: .Xr ftpd 8
1.87 lteo 1765: .Sh STANDARDS
1766: .Rs
1767: .%A J. Postel
1768: .%A J. Reynolds
1769: .%D October 1985
1770: .%R RFC 959
1771: .%T FILE TRANSFER PROTOCOL (FTP)
1772: .Re
1773: .Pp
1774: .Rs
1775: .%A P. Hethmon
1776: .%D March 2007
1777: .%R RFC 3659
1778: .%T Extensions to FTP
1779: .Re
1.1 deraadt 1780: .Sh HISTORY
1781: The
1.6 millert 1782: .Nm
1.1 deraadt 1783: command appeared in
1784: .Bx 4.2 .
1785: .Sh BUGS
1786: Correct execution of many commands depends upon proper behavior
1787: by the remote server.
1.71 martynas 1788: .Pp
1789: In the recursive mode of
1790: .Ic mget ,
1791: files and directories starting with whitespace are ignored
1792: because the list cannot be parsed any other way.
![[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