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