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