Annotation of src/usr.bin/ftp/ftp.1, Revision 1.16
1.16 ! millert 1: .\" $OpenBSD: ftp.1,v 1.15 1997/09/04 04:42:34 millert 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.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
36: .\"
1.14 millert 37: .Dd August 18, 1997
1.1 deraadt 38: .Dt FTP 1
39: .Os BSD 4.2
40: .Sh NAME
41: .Nm ftp
42: .Nd
43: .Tn ARPANET
44: file transfer program
45: .Sh SYNOPSIS
1.6 millert 46: .Nm
1.16 ! millert 47: .Op Fl A
1.6 millert 48: .Op Fl a
1.1 deraadt 49: .Op Fl d
1.8 kstailey 50: .Op Fl e
1.6 millert 51: .Op Fl g
1.1 deraadt 52: .Op Fl i
53: .Op Fl n
1.6 millert 54: .Op Fl p
55: .Op Fl P Ar port
1.7 millert 56: .Op Fl r Ar seconds
1.6 millert 57: .Op Fl t
58: .Op Fl v
59: .Op Fl V
60: .Op Ar host Op Ar port
1.3 deraadt 61: .Nm ftp
1.11 millert 62: ftp://[\fIuser\fR:\fIpassword\fR@]\fIhost\fR[:\fIport\fR]/\fIfile\fR[/]
1.3 deraadt 63: .Nm ftp
1.6 millert 64: http://\fIhost\fR[:\fIport\fR]/\fIfile\fR
1.3 deraadt 65: .Nm ftp
1.9 millert 66: \fIhost\fR:[/\fIpath\fR/]\fIfile\fR[/]
1.1 deraadt 67: .Sh DESCRIPTION
1.7 millert 68: .Nm Ftp
1.1 deraadt 69: is the user interface to the
70: .Tn ARPANET
71: standard File Transfer Protocol.
72: The program allows a user to transfer files to and from a
73: remote network site.
1.3 deraadt 74: .Pp
1.7 millert 75: The latter three usage formats will fetch a file using either the
76: HTTP or FTP protocols into the current directory.
1.9 millert 77: This is ideal for scripts. Refer to
78: .Sx AUTO-FETCHING FILES
79: below for more information.
1.7 millert 80: .Pp
1.1 deraadt 81: Options may be specified at the command line, or to the
82: command interpreter.
1.6 millert 83: .Bl -tag -width "port "
1.16 ! millert 84: .It Fl A
! 85: Force active mode ftp. By default,
! 86: .Nm
! 87: will try to use passive mode ftp and fall back to active mode
! 88: if passive is not supported by the server. This option causes
! 89: .Nm
! 90: to always use an active connection. It is only useful for connecting
! 91: to very old servers that do not implement passive mode properly.
1.6 millert 92: .It Fl a
93: Causes
94: .Nm
95: to bypass normal login procedure, and use an anonymous login instead.
96: .It Fl d
97: Enables debugging.
1.8 kstailey 98: .It Fl e
1.9 millert 99: Disables command line editing. Useful for Emacs ange-ftp.
1.6 millert 100: .It Fl g
101: Disables file name globbing.
102: .It Fl i
103: Turns off interactive prompting during
104: multiple file transfers.
1.1 deraadt 105: .It Fl n
106: Restrains
1.6 millert 107: .Nm
108: from attempting
109: .Dq auto-login
110: upon initial connection.
1.1 deraadt 111: If auto-login is enabled,
1.6 millert 112: .Nm
1.1 deraadt 113: will check the
114: .Pa .netrc
115: (see below) file in the user's home directory for an entry describing
116: an account on the remote machine.
117: If no entry exists,
1.6 millert 118: .Nm
1.1 deraadt 119: will prompt for the remote machine login name (default is the user
120: identity on the local machine), and, if necessary, prompt for a password
121: and an account with which to login.
1.6 millert 122: .It Fl p
123: Enable passive mode operation for use behind connection filtering firewalls.
1.16 ! millert 124: This option has been deprecated as
! 125: .Nm
! 126: now tries to use passive mode by default, falling back to active mode
! 127: if the server does not support passive connections.
1.6 millert 128: .It Fl P Ar port
129: Sets the port number to
130: .Ar port .
1.7 millert 131: .It Fl r Ar number
132: Retry to connect if failed, pausing for
133: .Ar number
134: of seconds.
1.6 millert 135: .It Fl t
136: Enables packet tracing.
137: .It Fl v
138: Enable verbose mode.
139: This is the default if input is from a terminal.
140: Forces
141: .Nm
142: to show all responses from the remote server, as well
143: as report on data transfer statistics.
144: .It Fl V
145: Disable verbose mode, overriding the default of enabled when input
146: is from a terminal.
1.1 deraadt 147: .El
148: .Pp
149: The client host with which
1.6 millert 150: .Nm
1.1 deraadt 151: is to communicate may be specified on the command line.
152: If this is done,
1.6 millert 153: .Nm
1.1 deraadt 154: will immediately attempt to establish a connection to an
155: .Tn FTP
156: server on that host; otherwise,
1.6 millert 157: .Nm
1.1 deraadt 158: will enter its command interpreter and await instructions
159: from the user.
160: When
1.6 millert 161: .Nm
1.1 deraadt 162: is awaiting commands from the user the prompt
163: .Ql ftp>
164: is provided to the user.
165: The following commands are recognized
166: by
167: .Nm ftp :
168: .Bl -tag -width Fl
169: .It Ic \&! Op Ar command Op Ar args
170: Invoke an interactive shell on the local machine.
171: If there are arguments, the first is taken to be a command to execute
172: directly, with the rest of the arguments as its arguments.
173: .It Ic \&$ Ar macro-name Op Ar args
174: Execute the macro
175: .Ar macro-name
176: that was defined with the
177: .Ic macdef
178: command.
179: Arguments are passed to the macro unglobbed.
180: .It Ic account Op Ar passwd
181: Supply a supplemental password required by a remote system for access
182: to resources once a login has been successfully completed.
183: If no argument is included, the user will be prompted for an account
184: password in a non-echoing input mode.
185: .It Ic append Ar local-file Op Ar remote-file
186: Append a local file to a file on the remote machine.
187: If
188: .Ar remote-file
189: is left unspecified, the local file name is used in naming the
190: remote file after being altered by any
191: .Ic ntrans
192: or
193: .Ic nmap
194: setting.
195: File transfer uses the current settings for
196: .Ic type ,
197: .Ic format ,
198: .Ic mode ,
199: and
200: .Ic structure .
201: .It Ic ascii
202: Set the file transfer
203: .Ic type
204: to network
205: .Tn ASCII .
206: This is the default type.
207: .It Ic bell
208: Arrange that a bell be sounded after each file transfer
209: command is completed.
210: .It Ic binary
211: Set the file transfer
212: .Ic type
213: to support binary image transfer.
214: .It Ic bye
215: Terminate the
216: .Tn FTP
217: session with the remote server
218: and exit
1.6 millert 219: .Nm ftp .
1.1 deraadt 220: An end of file will also terminate the session and exit.
221: .It Ic case
222: Toggle remote computer file name case mapping during
223: .Ic mget
224: commands.
225: When
226: .Ic case
227: is on (default is off), remote computer file names with all letters in
228: upper case are written in the local directory with the letters mapped
229: to lower case.
230: .It Ic \&cd Ar remote-directory
231: Change the working directory on the remote machine
232: to
1.6 millert 233: .Ar remote-directory .
1.1 deraadt 234: .It Ic cdup
235: Change the remote machine working directory to the parent of the
236: current remote machine working directory.
237: .It Ic chmod Ar mode file-name
238: Change the permission modes of the file
239: .Ar file-name
240: on the remote
1.6 millert 241: system to
242: .Ar mode .
1.1 deraadt 243: .It Ic close
244: Terminate the
245: .Tn FTP
246: session with the remote server, and
247: return to the command interpreter.
248: Any defined macros are erased.
249: .It Ic \&cr
250: Toggle carriage return stripping during
251: ascii type file retrieval.
252: Records are denoted by a carriage return/linefeed sequence
253: during ascii type file transfer.
254: When
255: .Ic \&cr
256: is on (the default), carriage returns are stripped from this
257: sequence to conform with the
258: .Ux
259: single linefeed record
260: delimiter.
261: Records on
262: .Pf non\- Ns Ux
263: remote systems may contain single linefeeds;
264: when an ascii type transfer is made, these linefeeds may be
265: distinguished from a record delimiter only when
266: .Ic \&cr
267: is off.
268: .It Ic delete Ar remote-file
269: Delete the file
270: .Ar remote-file
271: on the remote machine.
272: .It Ic debug Op Ar debug-value
273: Toggle debugging mode.
274: If an optional
275: .Ar debug-value
276: is specified it is used to set the debugging level.
277: When debugging is on,
1.6 millert 278: .Nm
1.7 millert 279: prints each command sent to the remote machine,
280: preceded by the string
1.1 deraadt 281: .Ql \-\->
1.6 millert 282: .It Ic dir Op Ar remote-directory Op Ar local-file
283: Print a listing of the contents of a
284: directory on the remote machine.
285: The listing includes any system-dependent information that the server
286: chooses to include; for example, most
287: .Ux
288: systems will produce
289: output from the command
290: .Ql ls \-l .
291: (See also
292: .Ic ls . )
293: If
294: .Ar remote-directory
295: is left unspecified, the current working directory is used.
1.1 deraadt 296: If interactive prompting is on,
1.6 millert 297: .Nm
1.1 deraadt 298: will prompt the user to verify that the last argument is indeed the
299: target local file for receiving
300: .Ic dir
301: output.
1.6 millert 302: If no local file is specified, or if
1.1 deraadt 303: .Ar local-file
304: is
1.6 millert 305: .Sq Fl ,
306: the output is sent to the terminal.
1.1 deraadt 307: .It Ic disconnect
308: A synonym for
1.6 millert 309: .Ic close .
310: .It Ic edit
311: Toggle command line editing, and context sensitive command and file
312: completion.
313: This is automatically enabled if input is from a terminal, and
314: disabled otherwise.
315: .It Ic exit
316: A synonym for
317: .Ic bye .
318: .It Ic ftp Ar host Op Ar port
319: A synonym for
320: .Ic open .
1.1 deraadt 321: .It Ic form Ar format
322: Set the file transfer
323: .Ic form
324: to
1.6 millert 325: .Ar format .
1.1 deraadt 326: The default format is \*(Lqfile\*(Rq.
327: .It Ic get Ar remote-file Op Ar local-file
328: Retrieve the
329: .Ar remote-file
330: and store it on the local machine.
331: If the local
332: file name is not specified, it is given the same
333: name it has on the remote machine, subject to
334: alteration by the current
335: .Ic case ,
336: .Ic ntrans ,
337: and
338: .Ic nmap
339: settings.
340: The current settings for
341: .Ic type ,
342: .Ic form ,
343: .Ic mode ,
344: and
345: .Ic structure
346: are used while transferring the file.
1.14 millert 347: .It Ic gate Op Ar host Op Ar port
348: Toggle gate-ftp mode.
349: This will not be permitted if the gate-ftp server hasn't been set
350: (either explicitly by the user, or from the
351: .Ev FTPSERVER
352: environment variable).
353: If
354: .Ar host
355: is given,
356: then gate-ftp mode will be enabled, and the gate-ftp server will be set to
357: .Ar host .
358: If
359: .Ar port
360: is also given, that will be used as the port to connect to on the
361: gate-ftp server.
1.1 deraadt 362: .It Ic glob
363: Toggle filename expansion for
364: .Ic mdelete ,
365: .Ic mget
366: and
1.6 millert 367: .Ic mput .
1.1 deraadt 368: If globbing is turned off with
369: .Ic glob ,
370: the file name arguments
371: are taken literally and not expanded.
372: Globbing for
373: .Ic mput
374: is done as in
375: .Xr csh 1 .
376: For
377: .Ic mdelete
378: and
379: .Ic mget ,
380: each remote file name is expanded
381: separately on the remote machine and the lists are not merged.
382: Expansion of a directory name is likely to be
383: different from expansion of the name of an ordinary file:
384: the exact result depends on the foreign operating system and ftp server,
385: and can be previewed by doing
386: .Ql mls remote-files \-
387: Note:
388: .Ic mget
389: and
390: .Ic mput
391: are not meant to transfer
392: entire directory subtrees of files.
393: That can be done by
394: transferring a
395: .Xr tar 1
396: archive of the subtree (in binary mode).
1.5 kstailey 397: .It Ic hash Op Ar size
1.1 deraadt 398: Toggle hash-sign (``#'') printing for each data block
399: transferred.
1.5 kstailey 400: The size of a data block defaults to 1024 bytes.
1.6 millert 401: This can be changed by specifying
402: .Ar size
403: in bytes.
1.1 deraadt 404: .It Ic help Op Ar command
405: Print an informative message about the meaning of
1.6 millert 406: .Ar command .
1.1 deraadt 407: If no argument is given,
1.6 millert 408: .Nm
1.1 deraadt 409: prints a list of the known commands.
410: .It Ic idle Op Ar seconds
411: Set the inactivity timer on the remote server to
412: .Ar seconds
413: seconds.
414: If
415: .Ar seconds
416: is omitted, the current inactivity timer is printed.
417: .It Ic lcd Op Ar directory
418: Change the working directory on the local machine.
419: If
420: no
421: .Ar directory
422: is specified, the user's home directory is used.
1.10 millert 423: .It Ic less Ar file
424: A synonym for
425: .Ic page .
1.6 millert 426: .It Ic lpwd
427: Print the working directory on the local machine.
428: .It Ic \&ls Op Ar remote-directory Op Ar local-file
429: Print a list of the files in a
1.1 deraadt 430: directory on the remote machine.
431: If
432: .Ar remote-directory
433: is left unspecified, the current working directory is used.
434: If interactive prompting is on,
1.6 millert 435: .Nm
1.1 deraadt 436: will prompt the user to verify that the last argument is indeed the
437: target local file for receiving
1.6 millert 438: .Ic ls
1.1 deraadt 439: output.
440: If no local file is specified, or if
441: .Ar local-file
442: is
1.6 millert 443: .Fl ,
1.1 deraadt 444: the output is sent to the terminal.
445: .It Ic macdef Ar macro-name
446: Define a macro.
447: Subsequent lines are stored as the macro
448: .Ar macro-name ;
449: a null line (consecutive newline characters
450: in a file or
451: carriage returns from the terminal) terminates macro input mode.
452: There is a limit of 16 macros and 4096 total characters in all
453: defined macros.
454: Macros remain defined until a
455: .Ic close
456: command is executed.
457: The macro processor interprets `$' and `\e' as special characters.
458: A `$' followed by a number (or numbers) is replaced by the
459: corresponding argument on the macro invocation command line.
460: A `$' followed by an `i' signals that macro processor that the
461: executing macro is to be looped.
462: On the first pass `$i' is
463: replaced by the first argument on the macro invocation command line,
464: on the second pass it is replaced by the second argument, and so on.
465: A `\e' followed by any character is replaced by that character.
466: Use the `\e' to prevent special treatment of the `$'.
467: .It Ic mdelete Op Ar remote-files
468: Delete the
469: .Ar remote-files
470: on the remote machine.
471: .It Ic mdir Ar remote-files local-file
472: Like
473: .Ic dir ,
474: except multiple remote files may be specified.
475: If interactive prompting is on,
1.6 millert 476: .Nm
1.1 deraadt 477: will prompt the user to verify that the last argument is indeed the
478: target local file for receiving
479: .Ic mdir
480: output.
481: .It Ic mget Ar remote-files
482: Expand the
483: .Ar remote-files
484: on the remote machine
485: and do a
486: .Ic get
487: for each file name thus produced.
488: See
489: .Ic glob
490: for details on the filename expansion.
491: Resulting file names will then be processed according to
492: .Ic case ,
493: .Ic ntrans ,
494: and
495: .Ic nmap
496: settings.
497: Files are transferred into the local working directory,
498: which can be changed with
499: .Ql lcd directory ;
500: new local directories can be created with
501: .Ql "\&! mkdir directory" .
502: .It Ic mkdir Ar directory-name
503: Make a directory on the remote machine.
504: .It Ic mls Ar remote-files local-file
505: Like
1.6 millert 506: .Ic ls ,
1.1 deraadt 507: except multiple remote files may be specified,
508: and the
509: .Ar local-file
510: must be specified.
511: If interactive prompting is on,
1.6 millert 512: .Nm
1.1 deraadt 513: will prompt the user to verify that the last argument is indeed the
514: target local file for receiving
515: .Ic mls
516: output.
517: .It Ic mode Op Ar mode-name
518: Set the file transfer
519: .Ic mode
520: to
1.6 millert 521: .Ar mode-name .
1.1 deraadt 522: The default mode is \*(Lqstream\*(Rq mode.
523: .It Ic modtime Ar file-name
524: Show the last modification time of the file on the remote machine.
1.10 millert 525: .It Ic more Ar file
526: A synonym for
527: .Ic page .
1.1 deraadt 528: .It Ic mput Ar local-files
529: Expand wild cards in the list of local files given as arguments
530: and do a
531: .Ic put
532: for each file in the resulting list.
533: See
534: .Ic glob
535: for details of filename expansion.
536: Resulting file names will then be processed according to
537: .Ic ntrans
538: and
539: .Ic nmap
540: settings.
1.6 millert 541: .It Ic msend Ar local-files
542: A synonym for
543: .Ic mput .
1.1 deraadt 544: .It Ic newer Ar file-name
545: Get the file only if the modification time of the remote file is more
546: recent that the file on the current system.
547: If the file does not
548: exist on the current system, the remote file is considered
1.6 millert 549: .Ic newer .
1.1 deraadt 550: Otherwise, this command is identical to
1.6 millert 551: .Ar get .
552: .It Ic nlist Op Ar remote-directory Op Ar local-file
553: A synonym for
554: .Ic ls .
1.1 deraadt 555: .It Ic nmap Op Ar inpattern outpattern
556: Set or unset the filename mapping mechanism.
557: If no arguments are specified, the filename mapping mechanism is unset.
558: If arguments are specified, remote filenames are mapped during
559: .Ic mput
560: commands and
561: .Ic put
562: commands issued without a specified remote target filename.
563: If arguments are specified, local filenames are mapped during
564: .Ic mget
565: commands and
566: .Ic get
567: commands issued without a specified local target filename.
568: This command is useful when connecting to a
569: .No non\- Ns Ux
570: remote computer
571: with different file naming conventions or practices.
572: The mapping follows the pattern set by
573: .Ar inpattern
574: and
1.6 millert 575: .Ar outpattern .
1.1 deraadt 576: .Op Ar Inpattern
577: is a template for incoming filenames (which may have already been
578: processed according to the
579: .Ic ntrans
580: and
581: .Ic case
582: settings).
583: Variable templating is accomplished by including the
584: sequences `$1', `$2', ..., `$9' in
1.6 millert 585: .Ar inpattern .
1.1 deraadt 586: Use `\\' to prevent this special treatment of the `$' character.
587: All other characters are treated literally, and are used to determine the
588: .Ic nmap
589: .Op Ar inpattern
590: variable values.
591: For example, given
592: .Ar inpattern
593: $1.$2 and the remote file name "mydata.data", $1 would have the value
594: "mydata", and $2 would have the value "data".
595: The
596: .Ar outpattern
597: determines the resulting mapped filename.
598: The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
599: from the
600: .Ar inpattern
601: template.
602: The sequence `$0' is replace by the original filename.
603: Additionally, the sequence
604: .Ql Op Ar seq1 , Ar seq2
605: is replaced by
606: .Op Ar seq1
607: if
608: .Ar seq1
609: is not a null string; otherwise it is replaced by
610: .Ar seq2 .
611: For example, the command
612: .Pp
613: .Bd -literal -offset indent -compact
614: nmap $1.$2.$3 [$1,$2].[$2,file]
615: .Ed
616: .Pp
617: would yield
618: the output filename "myfile.data" for input filenames "myfile.data" and
619: "myfile.data.old", "myfile.file" for the input filename "myfile", and
620: "myfile.myfile" for the input filename ".myfile".
621: Spaces may be included in
622: .Ar outpattern ,
623: as in the example: `nmap $1 sed "s/ *$//" > $1' .
624: Use the `\e' character to prevent special treatment
625: of the `$','[','[', and `,' characters.
626: .It Ic ntrans Op Ar inchars Op Ar outchars
627: Set or unset the filename character translation mechanism.
628: If no arguments are specified, the filename character
629: translation mechanism is unset.
630: If arguments are specified, characters in
631: remote filenames are translated during
632: .Ic mput
633: commands and
634: .Ic put
635: commands issued without a specified remote target filename.
636: If arguments are specified, characters in
637: local filenames are translated during
638: .Ic mget
639: commands and
640: .Ic get
641: commands issued without a specified local target filename.
642: This command is useful when connecting to a
643: .No non\- Ns Ux
644: remote computer
645: with different file naming conventions or practices.
646: Characters in a filename matching a character in
647: .Ar inchars
648: are replaced with the corresponding character in
1.6 millert 649: .Ar outchars .
1.1 deraadt 650: If the character's position in
651: .Ar inchars
652: is longer than the length of
653: .Ar outchars ,
654: the character is deleted from the file name.
655: .It Ic open Ar host Op Ar port
656: Establish a connection to the specified
657: .Ar host
658: .Tn FTP
659: server.
660: An optional port number may be supplied,
661: in which case,
1.6 millert 662: .Nm
1.1 deraadt 663: will attempt to contact an
664: .Tn FTP
665: server at that port.
666: If the
667: .Ic auto-login
668: option is on (default),
1.6 millert 669: .Nm
1.1 deraadt 670: will also attempt to automatically log the user in to
671: the
672: .Tn FTP
673: server (see below).
1.9 millert 674: .It Ic page Ar file
675: Retrieve
676: .Ic file
677: and display with the program defined in
678: .Ev PAGER
679: (which defaults to
680: .Xr more 1 ).
1.1 deraadt 681: .It Ic passive
682: Toggle passive mode. If passive mode is turned on
683: (default is off), the ftp client will
684: send a
685: .Dv PASV
686: command for all data connections instead of the usual
687: .Dv PORT
688: command. The
689: .Dv PASV
690: command requests that the remote server open a port for the data connection
691: and return the address of that port. The remote server listens on that
692: port and the client connects to it. When using the more traditional
693: .Dv PORT
694: command, the client listens on a port and sends that address to the remote
695: server, who connects back to it. Passive mode is useful when using
1.6 millert 696: .Nm
1.1 deraadt 697: through a gateway router or host that controls the directionality of
698: traffic.
699: (Note that though ftp servers are required to support the
700: .Dv PASV
701: command by RFC 1123, some do not.)
1.6 millert 702: .It Ic preserve
703: Toggle preservation of modification times on retrieved files.
704: .It Ic progress
705: Toggle display of transfer progress bar.
1.9 millert 706: The progress bar will be disabled for a transfer that has
707: .Ar local-file
708: as
709: .Sq Fl
710: or a command that starts with
711: .Sq \&| .
712: Refer to
713: .Sx FILE NAMING CONVENTIONS
714: for more information.
1.1 deraadt 715: .It Ic prompt
716: Toggle interactive prompting.
717: Interactive prompting
718: occurs during multiple file transfers to allow the
719: user to selectively retrieve or store files.
720: If prompting is turned off (default is on), any
721: .Ic mget
722: or
723: .Ic mput
724: will transfer all files, and any
725: .Ic mdelete
726: will delete all files.
1.6 millert 727: .Pp
728: When prompting is on, the following commands are available at a prompt:
729: .Bl -tag -width 2n -offset indent
730: .It Ic n
731: Do not transfer the file.
732: .It Ic a
733: Answer
734: .Sq yes
735: to the current file, and automatically answer
736: .Sq yes
737: to any remaining files for the current command.
738: .It Ic p
739: Answer
740: .Sq yes
741: to the current file, and turn off prompt mode
742: (as is
743: .Dq prompt off
744: had been given).
745: .El
746: .Pp
747: Any other reponse will answer
748: .Sq yes
749: to the current file.
1.1 deraadt 750: .It Ic proxy Ar ftp-command
751: Execute an ftp command on a secondary control connection.
752: This command allows simultaneous connection to two remote ftp
753: servers for transferring files between the two servers.
754: The first
755: .Ic proxy
756: command should be an
757: .Ic open ,
758: to establish the secondary control connection.
759: Enter the command "proxy ?" to see other ftp commands executable on the
760: secondary connection.
761: The following commands behave differently when prefaced by
762: .Ic proxy :
763: .Ic open
764: will not define new macros during the auto-login process,
765: .Ic close
766: will not erase existing macro definitions,
767: .Ic get
768: and
769: .Ic mget
770: transfer files from the host on the primary control connection
771: to the host on the secondary control connection, and
772: .Ic put ,
773: .Ic mput ,
774: and
775: .Ic append
776: transfer files from the host on the secondary control connection
777: to the host on the primary control connection.
778: Third party file transfers depend upon support of the ftp protocol
779: .Dv PASV
780: command by the server on the secondary control connection.
781: .It Ic put Ar local-file Op Ar remote-file
782: Store a local file on the remote machine.
783: If
784: .Ar remote-file
785: is left unspecified, the local file name is used
786: after processing according to any
787: .Ic ntrans
788: or
789: .Ic nmap
790: settings
791: in naming the remote file.
792: File transfer uses the
793: current settings for
794: .Ic type ,
795: .Ic format ,
796: .Ic mode ,
797: and
1.6 millert 798: .Ic structure .
1.1 deraadt 799: .It Ic pwd
800: Print the name of the current working directory on the remote
801: machine.
802: .It Ic quit
803: A synonym for
1.6 millert 804: .Ic bye .
1.1 deraadt 805: .It Ic quote Ar arg1 arg2 ...
806: The arguments specified are sent, verbatim, to the remote
807: .Tn FTP
808: server.
809: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 810: A synonym for
811: .Ic get .
1.1 deraadt 812: .It Ic reget Ar remote-file Op Ar local-file
813: Reget acts like get, except that if
814: .Ar local-file
815: exists and is
816: smaller than
817: .Ar remote-file ,
818: .Ar local-file
819: is presumed to be
820: a partially transferred copy of
821: .Ar remote-file
822: and the transfer
823: is continued from the apparent point of failure.
824: This command
825: is useful when transferring very large files over networks that
826: are prone to dropping connections.
827: .It Ic remotehelp Op Ar command-name
828: Request help from the remote
829: .Tn FTP
830: server.
831: If a
832: .Ar command-name
833: is specified it is supplied to the server as well.
1.6 millert 834: .It Ic rstatus Op Ar file-name
1.1 deraadt 835: With no arguments, show status of remote machine.
836: If
837: .Ar file-name
838: is specified, show status of
839: .Ar file-name
840: on remote machine.
1.6 millert 841: .It Ic rename Op Ar from Op Ar to
1.1 deraadt 842: Rename the file
843: .Ar from
844: on the remote machine, to the file
1.6 millert 845: .Ar to .
1.1 deraadt 846: .It Ic reset
847: Clear reply queue.
848: This command re-synchronizes command/reply sequencing with the remote
849: ftp server.
850: Resynchronization may be necessary following a violation of the ftp protocol
851: by the remote server.
852: .It Ic restart Ar marker
853: Restart the immediately following
854: .Ic get
855: or
856: .Ic put
857: at the
858: indicated
1.6 millert 859: .Ar marker .
1.1 deraadt 860: On
861: .Ux
862: systems, marker is usually a byte
863: offset into the file.
864: .It Ic rmdir Ar directory-name
865: Delete a directory on the remote machine.
866: .It Ic runique
867: Toggle storing of files on the local system with unique filenames.
868: If a file already exists with a name equal to the target
869: local filename for a
870: .Ic get
871: or
872: .Ic mget
873: command, a ".1" is appended to the name.
874: If the resulting name matches another existing file,
875: a ".2" is appended to the original name.
876: If this process continues up to ".99", an error
877: message is printed, and the transfer does not take place.
878: The generated unique filename will be reported.
879: Note that
880: .Ic runique
881: will not affect local files generated from a shell command
882: (see below).
883: The default value is off.
884: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 885: A synonym for
886: .Ic put .
1.1 deraadt 887: .It Ic sendport
888: Toggle the use of
889: .Dv PORT
890: commands.
891: By default,
1.6 millert 892: .Nm
1.1 deraadt 893: will attempt to use a
894: .Dv PORT
895: command when establishing
896: a connection for each data transfer.
897: The use of
898: .Dv PORT
899: commands can prevent delays
900: when performing multiple file transfers.
901: If the
902: .Dv PORT
903: command fails,
1.6 millert 904: .Nm
1.1 deraadt 905: will use the default data port.
906: When the use of
907: .Dv PORT
908: commands is disabled, no attempt will be made to use
909: .Dv PORT
910: commands for each data transfer.
911: This is useful
912: for certain
913: .Tn FTP
914: implementations which do ignore
915: .Dv PORT
916: commands but, incorrectly, indicate they've been accepted.
917: .It Ic site Ar arg1 arg2 ...
918: The arguments specified are sent, verbatim, to the remote
919: .Tn FTP
920: server as a
921: .Dv SITE
922: command.
923: .It Ic size Ar file-name
924: Return size of
925: .Ar file-name
926: on remote machine.
927: .It Ic status
928: Show the current status of
1.6 millert 929: .Nm ftp .
1.1 deraadt 930: .It Ic struct Op Ar struct-name
931: Set the file transfer
932: .Ar structure
933: to
934: .Ar struct-name .
935: By default \*(Lqstream\*(Rq structure is used.
936: .It Ic sunique
937: Toggle storing of files on remote machine under unique file names.
938: Remote ftp server must support ftp protocol
939: .Dv STOU
940: command for
941: successful completion.
942: The remote server will report unique name.
943: Default value is off.
944: .It Ic system
945: Show the type of operating system running on the remote machine.
946: .It Ic tenex
947: Set the file transfer type to that needed to
948: talk to
949: .Tn TENEX
950: machines.
951: .It Ic trace
952: Toggle packet tracing.
953: .It Ic type Op Ar type-name
954: Set the file transfer
955: .Ic type
956: to
1.6 millert 957: .Ar type-name .
1.1 deraadt 958: If no type is specified, the current type
959: is printed.
960: The default type is network
961: .Tn ASCII .
962: .It Ic umask Op Ar newmask
963: Set the default umask on the remote server to
1.6 millert 964: .Ar newmask .
1.1 deraadt 965: If
966: .Ar newmask
967: is omitted, the current umask is printed.
968: .It Xo
969: .Ic user Ar user-name
1.6 millert 970: .Op Ar password Op Ar account
1.1 deraadt 971: .Xc
972: Identify yourself to the remote
973: .Tn FTP
974: server.
975: If the
976: .Ar password
977: is not specified and the server requires it,
1.6 millert 978: .Nm
1.1 deraadt 979: will prompt the user for it (after disabling local echo).
980: If an
981: .Ar account
982: field is not specified, and the
983: .Tn FTP
984: server
985: requires it, the user will be prompted for it.
986: If an
987: .Ar account
988: field is specified, an account command will
989: be relayed to the remote server after the login sequence
990: is completed if the remote server did not require it
991: for logging in.
992: Unless
1.6 millert 993: .Nm
1.1 deraadt 994: is invoked with \*(Lqauto-login\*(Rq disabled, this
995: process is done automatically on initial connection to
996: the
997: .Tn FTP
998: server.
999: .It Ic verbose
1000: Toggle verbose mode.
1001: In verbose mode, all responses from
1002: the
1003: .Tn FTP
1004: server are displayed to the user.
1005: In addition,
1006: if verbose is on, when a file transfer completes, statistics
1007: regarding the efficiency of the transfer are reported.
1008: By default,
1009: verbose is on.
1010: .It Ic ? Op Ar command
1.6 millert 1011: A synonym for
1012: .Ic help .
1.1 deraadt 1013: .El
1014: .Pp
1015: Command arguments which have embedded spaces may be quoted with
1016: quote `"' marks.
1.6 millert 1017: .Pp
1018: Commands which toggle settings can take an explicit
1019: .Ic on
1020: or
1021: .Ic off
1022: argument to force the setting appropriately.
1023: .Pp
1024: If
1025: .Nm
1026: receives a
1027: .Dv SIGINFO
1028: (see the
1029: .Dq status
1030: argument of
1031: .Xr stty 1 )
1032: signal whilst a transfer is in progress, the current transfer rate
1033: statistics will be written to the standard error output, in the
1034: same format as the standard completion message.
1035: .Sh AUTO-FETCHING FILES
1036: In addition to standard commands, this version of
1037: .Nm
1038: supports an auto-fetch feature.
1039: To enable auto-fetch, simply pass the list of hostnames/files
1040: on the command line.
1041: .Pp
1042: The following formats are valid syntax for an auto-fetch element:
1.11 millert 1043: .Bl -tag -width "ftp://[user:password@]host[:port]/file"
1.6 millert 1044: .It host:/file
1045: .Dq Classic
1046: ftp format
1.11 millert 1047: .It ftp://[user:password@]host[:port]/file
1048: An ftp URL, retrieved using the ftp protocol if
1.10 millert 1049: .Ev ftp_proxy
1050: isn't defined.
1051: Otherwise, transfer using http via the proxy defined in
1052: .Ev ftp_proxy .
1.11 millert 1053: If
1054: .Ar user:password@
1055: is given and
1056: .Ev ftp_proxy
1057: isn't defined, login as
1058: .Ar user
1059: with a password of
1060: .Ar password .
1.6 millert 1061: .It http://host[:port]/file
1.11 millert 1062: An http URL, retrieved using the http protocol.
1.6 millert 1063: If
1064: .Ev http_proxy
1065: is defined, it is used as a URL to an HTTP proxy server.
1066: .El
1067: .Pp
1068: If a classic format or a ftp URL format has a trailing
1069: .Sq / ,
1070: then
1071: .Nm
1072: will connect to the site and
1073: .Ic cd
1074: to the directory given as the path, and leave the user in interactive
1075: mode ready for further input.
1076: .Pp
1077: If successive auto-fetch ftp elements refer to the same host, then
1078: the connection is maintained between transfers, reducing overhead on
1079: connection creation and deletion.
1.9 millert 1080: .Pp
1081: If
1082: .Ic file
1083: contains a glob character and globbing is enabled,
1084: (see
1.13 millert 1085: .Ic glob ) ,
1.9 millert 1086: then the equivalent of
1087: .Ic "mget file"
1088: is performed.
1089: .Pp
1.12 deraadt 1090: If standard output is redirected to a non-tty device, ftp will write
1091: the data file out to standard output. This can be used to pipe data
1092: directly to another process.
1093: Otherwise if the directory component of
1.9 millert 1094: .Ic file
1095: contains no globbing characters,
1096: it is stored in the current directory as the
1097: .Xr basename 1
1098: of
1099: .Ic file .
1100: Otherwise, the remote name is used as the local name.
1.1 deraadt 1101: .Sh ABORTING A FILE TRANSFER
1102: To abort a file transfer, use the terminal interrupt key
1103: (usually Ctrl-C).
1104: Sending transfers will be immediately halted.
1105: Receiving transfers will be halted by sending a ftp protocol
1106: .Dv ABOR
1107: command to the remote server, and discarding any further data received.
1108: The speed at which this is accomplished depends upon the remote
1109: server's support for
1110: .Dv ABOR
1111: processing.
1112: If the remote server does not support the
1113: .Dv ABOR
1114: command, an
1115: .Ql ftp>
1116: prompt will not appear until the remote server has completed
1117: sending the requested file.
1118: .Pp
1119: The terminal interrupt key sequence will be ignored when
1.6 millert 1120: .Nm
1.1 deraadt 1121: has completed any local processing and is awaiting a reply
1122: from the remote server.
1123: A long delay in this mode may result from the ABOR processing described
1124: above, or from unexpected behavior by the remote server, including
1125: violations of the ftp protocol.
1126: If the delay results from unexpected remote server behavior, the local
1.6 millert 1127: .Nm
1.1 deraadt 1128: program must be killed by hand.
1129: .Sh FILE NAMING CONVENTIONS
1130: Files specified as arguments to
1.6 millert 1131: .Nm
1.1 deraadt 1132: commands are processed according to the following rules.
1133: .Bl -enum
1134: .It
1135: If the file name
1136: .Sq Fl
1137: is specified, the
1138: .Ar stdin
1139: (for reading) or
1140: .Ar stdout
1141: (for writing) is used.
1142: .It
1143: If the first character of the file name is
1144: .Sq \&| ,
1145: the
1146: remainder of the argument is interpreted as a shell command.
1.6 millert 1147: .Nm
1.1 deraadt 1148: then forks a shell, using
1149: .Xr popen 3
1150: with the argument supplied, and reads (writes) from the stdout
1151: (stdin).
1152: If the shell command includes spaces, the argument
1153: must be quoted; e.g.
1154: \*(Lq" ls -lt"\*(Rq.
1155: A particularly
1.6 millert 1156: useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
1.1 deraadt 1157: .It
1158: Failing the above checks, if ``globbing'' is enabled,
1159: local file names are expanded
1160: according to the rules used in the
1161: .Xr csh 1 ;
1162: c.f. the
1163: .Ic glob
1164: command.
1165: If the
1.6 millert 1166: .Nm
1.1 deraadt 1167: command expects a single local file (.e.g.
1168: .Ic put ) ,
1169: only the first filename generated by the "globbing" operation is used.
1170: .It
1171: For
1172: .Ic mget
1173: commands and
1174: .Ic get
1175: commands with unspecified local file names, the local filename is
1176: the remote filename, which may be altered by a
1177: .Ic case ,
1178: .Ic ntrans ,
1179: or
1180: .Ic nmap
1181: setting.
1182: The resulting filename may then be altered if
1183: .Ic runique
1184: is on.
1185: .It
1186: For
1187: .Ic mput
1188: commands and
1189: .Ic put
1190: commands with unspecified remote file names, the remote filename is
1191: the local filename, which may be altered by a
1192: .Ic ntrans
1193: or
1194: .Ic nmap
1195: setting.
1196: The resulting filename may then be altered by the remote server if
1197: .Ic sunique
1198: is on.
1199: .El
1200: .Sh FILE TRANSFER PARAMETERS
1201: The FTP specification specifies many parameters which may
1202: affect a file transfer.
1203: The
1204: .Ic type
1205: may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1206: \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1207: .Tn PDP Ns -10's
1208: and
1209: .Tn PDP Ns -20's
1210: mostly).
1.6 millert 1211: .Nm
1.1 deraadt 1212: supports the ascii and image types of file transfer,
1213: plus local byte size 8 for
1214: .Ic tenex
1215: mode transfers.
1216: .Pp
1.6 millert 1217: .Nm
1.1 deraadt 1218: supports only the default values for the remaining
1219: file transfer parameters:
1220: .Ic mode ,
1221: .Ic form ,
1222: and
1.6 millert 1223: .Ic struct .
1.1 deraadt 1224: .Sh THE .netrc FILE
1225: The
1226: .Pa .netrc
1227: file contains login and initialization information
1228: used by the auto-login process.
1229: It resides in the user's home directory.
1230: The following tokens are recognized; they may be separated by spaces,
1231: tabs, or new-lines:
1232: .Bl -tag -width password
1233: .It Ic machine Ar name
1234: Identify a remote machine
1235: .Ar name .
1236: The auto-login process searches the
1237: .Pa .netrc
1238: file for a
1239: .Ic machine
1240: token that matches the remote machine specified on the
1.6 millert 1241: .Nm
1.1 deraadt 1242: command line or as an
1243: .Ic open
1244: command argument.
1245: Once a match is made, the subsequent
1246: .Pa .netrc
1247: tokens are processed,
1248: stopping when the end of file is reached or another
1249: .Ic machine
1250: or a
1251: .Ic default
1252: token is encountered.
1253: .It Ic default
1254: This is the same as
1255: .Ic machine
1256: .Ar name
1257: except that
1258: .Ic default
1259: matches any name.
1260: There can be only one
1261: .Ic default
1262: token, and it must be after all
1263: .Ic machine
1264: tokens.
1265: This is normally used as:
1266: .Pp
1267: .Dl default login anonymous password user@site
1268: .Pp
1269: thereby giving the user
1270: .Ar automatic
1271: anonymous ftp login to
1272: machines not specified in
1273: .Pa .netrc .
1274: This can be overridden
1275: by using the
1276: .Fl n
1277: flag to disable auto-login.
1278: .It Ic login Ar name
1279: Identify a user on the remote machine.
1280: If this token is present, the auto-login process will initiate
1281: a login using the specified
1282: .Ar name .
1283: .It Ic password Ar string
1284: Supply a password.
1285: If this token is present, the auto-login process will supply the
1286: specified string if the remote server requires a password as part
1287: of the login process.
1288: Note that if this token is present in the
1289: .Pa .netrc
1290: file for any user other
1291: than
1292: .Ar anonymous ,
1.6 millert 1293: .Nm
1.1 deraadt 1294: will abort the auto-login process if the
1295: .Pa .netrc
1296: is readable by
1297: anyone besides the user.
1298: .It Ic account Ar string
1299: Supply an additional account password.
1300: If this token is present, the auto-login process will supply the
1301: specified string if the remote server requires an additional
1302: account password, or the auto-login process will initiate an
1303: .Dv ACCT
1304: command if it does not.
1305: .It Ic macdef Ar name
1306: Define a macro.
1307: This token functions like the
1.6 millert 1308: .Nm
1.1 deraadt 1309: .Ic macdef
1310: command functions.
1311: A macro is defined with the specified name; its contents begin with the
1312: next
1313: .Pa .netrc
1314: line and continue until a null line (consecutive new-line
1315: characters) is encountered.
1316: If a macro named
1317: .Ic init
1318: is defined, it is automatically executed as the last step in the
1319: auto-login process.
1320: .El
1.6 millert 1321: .Sh COMMAND LINE EDITING
1322: .Nm
1323: supports interactive command line editing, via the
1324: .Xr editline 3
1325: library.
1326: It is enabled with the
1327: .Ic edit
1.9 millert 1328: command, and is enabled by default if input is from a tty.
1.6 millert 1329: Previous lines can be recalled and edited with the arrow keys,
1330: and other GNU Emacs-style editing keys may be used as well.
1331: .Pp
1332: The
1333: .Xr editline 3
1334: library is configured with a
1335: .Pa .editrc
1336: file - refer to
1337: .Xr editrc 5
1338: for more information.
1339: .Pp
1340: An extra key binding is available to
1341: .Nm
1342: to provide context sensitive command and filename completion
1343: (including remote file completion).
1344: To use this, bind a key to the
1345: .Xr editline 3
1346: command
1347: .Ic ftp-complete .
1348: By default, this is bound to the TAB key.
1.1 deraadt 1349: .Sh ENVIRONMENT
1.6 millert 1350: .Nm
1.1 deraadt 1351: utilizes the following environment variables.
1.15 millert 1352: .Bl -tag -width "FTPSERVERPORT"
1.16 ! millert 1353: .It Ev FTPMODE
! 1354: Overrides the default operation mode. Recognized values are:
! 1355: .Bl -tag -width "passive "
! 1356: .It passive
! 1357: passive mode ftp only
! 1358: .It active
! 1359: active mode ftp only
! 1360: .It auto
! 1361: automatic determination of passive or active (this is the default)
! 1362: .It gate
! 1363: gate-ftp mode
! 1364: .El
1.14 millert 1365: .It Ev FTPSERVER
1366: Host to use as gate-ftp server when
1367: .Ic gate
1368: is enabled.
1369: .It Ev FTPSERVERPORT
1370: Port to use when connecting to gate-ftp server when
1371: .Ic gate
1372: is enabled.
1373: Default is port returned by a
1374: .Fn getservbyname
1375: lookup of
1376: .Dq ftpgate/tcp .
1.1 deraadt 1377: .It Ev HOME
1378: For default location of a
1379: .Pa .netrc
1380: file, if one exists.
1.9 millert 1381: .It Ev PAGER
1382: Used by
1383: .Ic page
1384: to display files.
1.1 deraadt 1385: .It Ev SHELL
1386: For default shell.
1.15 millert 1387: .It Ev TMPDIR
1388: Directory to put temporary files.
1.10 millert 1389: .It Ev ftp_proxy
1390: URL of FTP proxy to use when making FTP URL requests
1391: (if not defined, use the standard ftp protocol).
1.6 millert 1392: .It Ev http_proxy
1.10 millert 1393: URL of HTTP proxy to use when making HTTP URL requests.
1.1 deraadt 1394: .El
1395: .Sh SEE ALSO
1.14 millert 1396: .Xr getservbyname 3 ,
1.6 millert 1397: .Xr editrc 5 ,
1.14 millert 1398: .Xr services 5 ,
1.1 deraadt 1399: .Xr ftpd 8
1400: .Sh HISTORY
1401: The
1.6 millert 1402: .Nm
1.1 deraadt 1403: command appeared in
1404: .Bx 4.2 .
1405: .Sh BUGS
1406: Correct execution of many commands depends upon proper behavior
1407: by the remote server.
1408: .Pp
1409: An error in the treatment of carriage returns
1410: in the
1411: .Bx 4.2
1412: ascii-mode transfer code
1413: has been corrected.
1414: This correction may result in incorrect transfers of binary files
1415: to and from
1416: .Bx 4.2
1417: servers using the ascii type.
1418: Avoid this problem by using the binary image type.
![[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