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