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