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