Annotation of src/usr.bin/ftp/ftp.1, Revision 1.27
1.27 ! aaron 1: .\" $OpenBSD: ftp.1,v 1.26 1999/06/10 22:38:02 pjanzen 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
1.25 aaron 39: .Os
1.1 deraadt 40: .Sh NAME
41: .Nm ftp
42: .Nd
43: .Tn ARPANET
44: file transfer program
45: .Sh SYNOPSIS
1.23 aaron 46: .Nm ftp
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.27 ! aaron 59: .Nm
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.25 aaron 351: .It Ic gate Op Ar host Op Ar port
1.14 millert 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
1.25 aaron 355: .Ev FTPSERVER
1.14 millert 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
1.25 aaron 682: .Ev PAGER
1.26 pjanzen 683: (defaulting to
684: .Xr more 1
685: if
686: .Ev PAGER
687: is null or not defined).
1.1 deraadt 688: .It Ic passive
689: Toggle passive mode. If passive mode is turned on
1.24 deraadt 690: (default is on), the ftp client will
1.1 deraadt 691: send a
692: .Dv PASV
693: command for all data connections instead of the usual
694: .Dv PORT
695: command. The
696: .Dv PASV
697: command requests that the remote server open a port for the data connection
698: and return the address of that port. The remote server listens on that
699: port and the client connects to it. When using the more traditional
700: .Dv PORT
701: command, the client listens on a port and sends that address to the remote
702: server, who connects back to it. Passive mode is useful when using
1.6 millert 703: .Nm
1.1 deraadt 704: through a gateway router or host that controls the directionality of
705: traffic.
706: (Note that though ftp servers are required to support the
707: .Dv PASV
708: command by RFC 1123, some do not.)
1.6 millert 709: .It Ic preserve
710: Toggle preservation of modification times on retrieved files.
711: .It Ic progress
712: Toggle display of transfer progress bar.
1.9 millert 713: The progress bar will be disabled for a transfer that has
714: .Ar local-file
715: as
716: .Sq Fl
717: or a command that starts with
718: .Sq \&| .
719: Refer to
720: .Sx FILE NAMING CONVENTIONS
721: for more information.
1.1 deraadt 722: .It Ic prompt
723: Toggle interactive prompting.
724: Interactive prompting
725: occurs during multiple file transfers to allow the
726: user to selectively retrieve or store files.
727: If prompting is turned off (default is on), any
728: .Ic mget
729: or
730: .Ic mput
731: will transfer all files, and any
732: .Ic mdelete
733: will delete all files.
1.6 millert 734: .Pp
735: When prompting is on, the following commands are available at a prompt:
736: .Bl -tag -width 2n -offset indent
737: .It Ic n
738: Do not transfer the file.
739: .It Ic a
740: Answer
1.22 aaron 741: .Dq yes
742: to the current file and automatically answer
743: .Dq yes
1.6 millert 744: to any remaining files for the current command.
745: .It Ic p
746: Answer
1.22 aaron 747: .Dq yes
748: to the current file and turn off prompt mode
749: (as if
1.6 millert 750: .Dq prompt off
751: had been given).
752: .El
753: .Pp
754: Any other reponse will answer
1.22 aaron 755: .Dq yes
1.6 millert 756: to the current file.
1.1 deraadt 757: .It Ic proxy Ar ftp-command
758: Execute an ftp command on a secondary control connection.
759: This command allows simultaneous connection to two remote ftp
760: servers for transferring files between the two servers.
761: The first
762: .Ic proxy
763: command should be an
764: .Ic open ,
765: to establish the secondary control connection.
766: Enter the command "proxy ?" to see other ftp commands executable on the
767: secondary connection.
768: The following commands behave differently when prefaced by
769: .Ic proxy :
770: .Ic open
771: will not define new macros during the auto-login process,
772: .Ic close
773: will not erase existing macro definitions,
774: .Ic get
775: and
776: .Ic mget
777: transfer files from the host on the primary control connection
778: to the host on the secondary control connection, and
779: .Ic put ,
780: .Ic mput ,
781: and
782: .Ic append
783: transfer files from the host on the secondary control connection
784: to the host on the primary control connection.
785: Third party file transfers depend upon support of the ftp protocol
786: .Dv PASV
787: command by the server on the secondary control connection.
788: .It Ic put Ar local-file Op Ar remote-file
789: Store a local file on the remote machine.
790: If
791: .Ar remote-file
792: is left unspecified, the local file name is used
793: after processing according to any
794: .Ic ntrans
795: or
796: .Ic nmap
797: settings
798: in naming the remote file.
799: File transfer uses the
800: current settings for
801: .Ic type ,
802: .Ic format ,
803: .Ic mode ,
804: and
1.6 millert 805: .Ic structure .
1.1 deraadt 806: .It Ic pwd
807: Print the name of the current working directory on the remote
808: machine.
809: .It Ic quit
810: A synonym for
1.6 millert 811: .Ic bye .
1.1 deraadt 812: .It Ic quote Ar arg1 arg2 ...
813: The arguments specified are sent, verbatim, to the remote
814: .Tn FTP
815: server.
816: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 817: A synonym for
818: .Ic get .
1.1 deraadt 819: .It Ic reget Ar remote-file Op Ar local-file
820: Reget acts like get, except that if
821: .Ar local-file
822: exists and is
823: smaller than
824: .Ar remote-file ,
825: .Ar local-file
826: is presumed to be
827: a partially transferred copy of
828: .Ar remote-file
829: and the transfer
830: is continued from the apparent point of failure.
831: This command
832: is useful when transferring very large files over networks that
833: are prone to dropping connections.
834: .It Ic remotehelp Op Ar command-name
835: Request help from the remote
836: .Tn FTP
837: server.
838: If a
839: .Ar command-name
840: is specified it is supplied to the server as well.
1.6 millert 841: .It Ic rstatus Op Ar file-name
1.1 deraadt 842: With no arguments, show status of remote machine.
843: If
844: .Ar file-name
845: is specified, show status of
846: .Ar file-name
847: on remote machine.
1.6 millert 848: .It Ic rename Op Ar from Op Ar to
1.1 deraadt 849: Rename the file
850: .Ar from
1.22 aaron 851: on the remote machine to the file
1.6 millert 852: .Ar to .
1.1 deraadt 853: .It Ic reset
854: Clear reply queue.
855: This command re-synchronizes command/reply sequencing with the remote
856: ftp server.
857: Resynchronization may be necessary following a violation of the ftp protocol
858: by the remote server.
859: .It Ic restart Ar marker
860: Restart the immediately following
861: .Ic get
862: or
863: .Ic put
864: at the
865: indicated
1.6 millert 866: .Ar marker .
1.1 deraadt 867: On
868: .Ux
1.22 aaron 869: systems,
870: .Ar marker
871: is usually a byte
1.1 deraadt 872: offset into the file.
873: .It Ic rmdir Ar directory-name
874: Delete a directory on the remote machine.
875: .It Ic runique
876: Toggle storing of files on the local system with unique filenames.
877: If a file already exists with a name equal to the target
878: local filename for a
879: .Ic get
880: or
881: .Ic mget
882: command, a ".1" is appended to the name.
883: If the resulting name matches another existing file,
884: a ".2" is appended to the original name.
885: If this process continues up to ".99", an error
886: message is printed, and the transfer does not take place.
887: The generated unique filename will be reported.
888: Note that
889: .Ic runique
890: will not affect local files generated from a shell command
891: (see below).
892: The default value is off.
893: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 894: A synonym for
895: .Ic put .
1.1 deraadt 896: .It Ic sendport
897: Toggle the use of
898: .Dv PORT
899: commands.
900: By default,
1.6 millert 901: .Nm
1.1 deraadt 902: will attempt to use a
903: .Dv PORT
904: command when establishing
905: a connection for each data transfer.
906: The use of
907: .Dv PORT
908: commands can prevent delays
909: when performing multiple file transfers.
910: If the
911: .Dv PORT
912: command fails,
1.6 millert 913: .Nm
1.1 deraadt 914: will use the default data port.
915: When the use of
916: .Dv PORT
917: commands is disabled, no attempt will be made to use
918: .Dv PORT
919: commands for each data transfer.
920: This is useful
921: for certain
922: .Tn FTP
923: implementations which do ignore
924: .Dv PORT
925: commands but, incorrectly, indicate they've been accepted.
926: .It Ic site Ar arg1 arg2 ...
927: The arguments specified are sent, verbatim, to the remote
928: .Tn FTP
929: server as a
930: .Dv SITE
931: command.
932: .It Ic size Ar file-name
933: Return size of
934: .Ar file-name
935: on remote machine.
936: .It Ic status
937: Show the current status of
1.6 millert 938: .Nm ftp .
1.1 deraadt 939: .It Ic struct Op Ar struct-name
940: Set the file transfer
941: .Ar structure
942: to
943: .Ar struct-name .
944: By default \*(Lqstream\*(Rq structure is used.
945: .It Ic sunique
946: Toggle storing of files on remote machine under unique file names.
947: Remote ftp server must support ftp protocol
948: .Dv STOU
949: command for
950: successful completion.
951: The remote server will report unique name.
952: Default value is off.
953: .It Ic system
954: Show the type of operating system running on the remote machine.
955: .It Ic tenex
956: Set the file transfer type to that needed to
957: talk to
958: .Tn TENEX
959: machines.
960: .It Ic trace
961: Toggle packet tracing.
962: .It Ic type Op Ar type-name
963: Set the file transfer
964: .Ic type
965: to
1.6 millert 966: .Ar type-name .
1.1 deraadt 967: If no type is specified, the current type
968: is printed.
969: The default type is network
970: .Tn ASCII .
971: .It Ic umask Op Ar newmask
972: Set the default umask on the remote server to
1.6 millert 973: .Ar newmask .
1.1 deraadt 974: If
975: .Ar newmask
976: is omitted, the current umask is printed.
977: .It Xo
978: .Ic user Ar user-name
1.6 millert 979: .Op Ar password Op Ar account
1.1 deraadt 980: .Xc
981: Identify yourself to the remote
982: .Tn FTP
983: server.
984: If the
985: .Ar password
986: is not specified and the server requires it,
1.6 millert 987: .Nm
1.1 deraadt 988: will prompt the user for it (after disabling local echo).
989: If an
990: .Ar account
991: field is not specified, and the
992: .Tn FTP
993: server
994: requires it, the user will be prompted for it.
995: If an
996: .Ar account
997: field is specified, an account command will
998: be relayed to the remote server after the login sequence
999: is completed if the remote server did not require it
1000: for logging in.
1001: Unless
1.6 millert 1002: .Nm
1.1 deraadt 1003: is invoked with \*(Lqauto-login\*(Rq disabled, this
1004: process is done automatically on initial connection to
1005: the
1006: .Tn FTP
1007: server.
1008: .It Ic verbose
1009: Toggle verbose mode.
1010: In verbose mode, all responses from
1011: the
1012: .Tn FTP
1013: server are displayed to the user.
1014: In addition,
1015: if verbose is on, when a file transfer completes, statistics
1016: regarding the efficiency of the transfer are reported.
1017: By default,
1018: verbose is on.
1019: .It Ic ? Op Ar command
1.6 millert 1020: A synonym for
1021: .Ic help .
1.1 deraadt 1022: .El
1023: .Pp
1024: Command arguments which have embedded spaces may be quoted with
1025: quote `"' marks.
1.6 millert 1026: .Pp
1027: Commands which toggle settings can take an explicit
1028: .Ic on
1029: or
1030: .Ic off
1031: argument to force the setting appropriately.
1032: .Pp
1033: If
1034: .Nm
1035: receives a
1036: .Dv SIGINFO
1037: (see the
1038: .Dq status
1039: argument of
1040: .Xr stty 1 )
1041: signal whilst a transfer is in progress, the current transfer rate
1042: statistics will be written to the standard error output, in the
1043: same format as the standard completion message.
1044: .Sh AUTO-FETCHING FILES
1045: In addition to standard commands, this version of
1046: .Nm
1047: supports an auto-fetch feature.
1048: To enable auto-fetch, simply pass the list of hostnames/files
1049: on the command line.
1050: .Pp
1051: The following formats are valid syntax for an auto-fetch element:
1.11 millert 1052: .Bl -tag -width "ftp://[user:password@]host[:port]/file"
1.25 aaron 1053: .It host:/file
1.6 millert 1054: .Dq Classic
1055: ftp format
1.11 millert 1056: .It ftp://[user:password@]host[:port]/file
1057: An ftp URL, retrieved using the ftp protocol if
1.10 millert 1058: .Ev ftp_proxy
1059: isn't defined.
1060: Otherwise, transfer using http via the proxy defined in
1061: .Ev ftp_proxy .
1.11 millert 1062: If
1063: .Ar user:password@
1064: is given and
1065: .Ev ftp_proxy
1066: isn't defined, login as
1067: .Ar user
1068: with a password of
1069: .Ar password .
1.6 millert 1070: .It http://host[:port]/file
1.11 millert 1071: An http URL, retrieved using the http protocol.
1.6 millert 1072: If
1073: .Ev http_proxy
1074: is defined, it is used as a URL to an HTTP proxy server.
1075: .El
1076: .Pp
1077: If a classic format or a ftp URL format has a trailing
1078: .Sq / ,
1079: then
1080: .Nm
1081: will connect to the site and
1082: .Ic cd
1083: to the directory given as the path, and leave the user in interactive
1084: mode ready for further input.
1085: .Pp
1086: If successive auto-fetch ftp elements refer to the same host, then
1087: the connection is maintained between transfers, reducing overhead on
1088: connection creation and deletion.
1.9 millert 1089: .Pp
1090: If
1091: .Ic file
1.25 aaron 1092: contains a glob character and globbing is enabled,
1.9 millert 1093: (see
1.13 millert 1094: .Ic glob ) ,
1.9 millert 1095: then the equivalent of
1096: .Ic "mget file"
1097: is performed.
1098: .Pp
1.19 d 1099: If no
1100: .Fl o
1101: option is specified, and
1102: the directory component of
1.9 millert 1103: .Ic file
1104: contains no globbing characters,
1.19 d 1105: then
1.9 millert 1106: it is stored in the current directory as the
1107: .Xr basename 1
1108: of
1109: .Ic file .
1110: Otherwise, the remote name is used as the local name.
1.1 deraadt 1111: .Sh ABORTING A FILE TRANSFER
1112: To abort a file transfer, use the terminal interrupt key
1113: (usually Ctrl-C).
1114: Sending transfers will be immediately halted.
1.22 aaron 1115: Receiving transfers will be halted by sending an ftp protocol
1.1 deraadt 1116: .Dv ABOR
1117: command to the remote server, and discarding any further data received.
1118: The speed at which this is accomplished depends upon the remote
1119: server's support for
1120: .Dv ABOR
1121: processing.
1122: If the remote server does not support the
1123: .Dv ABOR
1124: command, an
1125: .Ql ftp>
1126: prompt will not appear until the remote server has completed
1127: sending the requested file.
1128: .Pp
1129: The terminal interrupt key sequence will be ignored when
1.6 millert 1130: .Nm
1.1 deraadt 1131: has completed any local processing and is awaiting a reply
1132: from the remote server.
1133: A long delay in this mode may result from the ABOR processing described
1134: above, or from unexpected behavior by the remote server, including
1135: violations of the ftp protocol.
1136: If the delay results from unexpected remote server behavior, the local
1.6 millert 1137: .Nm
1.1 deraadt 1138: program must be killed by hand.
1139: .Sh FILE NAMING CONVENTIONS
1140: Files specified as arguments to
1.6 millert 1141: .Nm
1.1 deraadt 1142: commands are processed according to the following rules.
1143: .Bl -enum
1144: .It
1145: If the file name
1146: .Sq Fl
1.22 aaron 1147: is specified, the stdin
1148: (for reading) or stdout
1.1 deraadt 1149: (for writing) is used.
1150: .It
1151: If the first character of the file name is
1152: .Sq \&| ,
1153: the
1154: remainder of the argument is interpreted as a shell command.
1.6 millert 1155: .Nm
1.1 deraadt 1156: then forks a shell, using
1157: .Xr popen 3
1158: with the argument supplied, and reads (writes) from the stdout
1159: (stdin).
1160: If the shell command includes spaces, the argument
1161: must be quoted; e.g.
1162: \*(Lq" ls -lt"\*(Rq.
1163: A particularly
1.6 millert 1164: useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
1.1 deraadt 1165: .It
1166: Failing the above checks, if ``globbing'' is enabled,
1167: local file names are expanded
1168: according to the rules used in the
1169: .Xr csh 1 ;
1170: c.f. the
1171: .Ic glob
1172: command.
1173: If the
1.6 millert 1174: .Nm
1.1 deraadt 1175: command expects a single local file (.e.g.
1176: .Ic put ) ,
1177: only the first filename generated by the "globbing" operation is used.
1178: .It
1179: For
1180: .Ic mget
1181: commands and
1182: .Ic get
1183: commands with unspecified local file names, the local filename is
1184: the remote filename, which may be altered by a
1185: .Ic case ,
1186: .Ic ntrans ,
1187: or
1188: .Ic nmap
1189: setting.
1190: The resulting filename may then be altered if
1191: .Ic runique
1192: is on.
1193: .It
1194: For
1195: .Ic mput
1196: commands and
1197: .Ic put
1198: commands with unspecified remote file names, the remote filename is
1199: the local filename, which may be altered by a
1200: .Ic ntrans
1201: or
1202: .Ic nmap
1203: setting.
1204: The resulting filename may then be altered by the remote server if
1205: .Ic sunique
1206: is on.
1207: .El
1208: .Sh FILE TRANSFER PARAMETERS
1209: The FTP specification specifies many parameters which may
1210: affect a file transfer.
1211: The
1212: .Ic type
1213: may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1214: \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1215: .Tn PDP Ns -10's
1216: and
1217: .Tn PDP Ns -20's
1218: mostly).
1.6 millert 1219: .Nm
1.1 deraadt 1220: supports the ascii and image types of file transfer,
1221: plus local byte size 8 for
1222: .Ic tenex
1223: mode transfers.
1224: .Pp
1.6 millert 1225: .Nm
1.1 deraadt 1226: supports only the default values for the remaining
1227: file transfer parameters:
1228: .Ic mode ,
1229: .Ic form ,
1230: and
1.6 millert 1231: .Ic struct .
1.1 deraadt 1232: .Sh THE .netrc FILE
1233: The
1234: .Pa .netrc
1235: file contains login and initialization information
1236: used by the auto-login process.
1237: It resides in the user's home directory.
1238: The following tokens are recognized; they may be separated by spaces,
1239: tabs, or new-lines:
1240: .Bl -tag -width password
1241: .It Ic machine Ar name
1242: Identify a remote machine
1243: .Ar name .
1244: The auto-login process searches the
1245: .Pa .netrc
1246: file for a
1247: .Ic machine
1248: token that matches the remote machine specified on the
1.6 millert 1249: .Nm
1.1 deraadt 1250: command line or as an
1251: .Ic open
1252: command argument.
1253: Once a match is made, the subsequent
1254: .Pa .netrc
1255: tokens are processed,
1256: stopping when the end of file is reached or another
1257: .Ic machine
1258: or a
1259: .Ic default
1260: token is encountered.
1261: .It Ic default
1262: This is the same as
1263: .Ic machine
1264: .Ar name
1265: except that
1266: .Ic default
1267: matches any name.
1268: There can be only one
1269: .Ic default
1270: token, and it must be after all
1271: .Ic machine
1272: tokens.
1273: This is normally used as:
1274: .Pp
1275: .Dl default login anonymous password user@site
1276: .Pp
1277: thereby giving the user
1278: .Ar automatic
1279: anonymous ftp login to
1280: machines not specified in
1281: .Pa .netrc .
1282: This can be overridden
1283: by using the
1284: .Fl n
1285: flag to disable auto-login.
1286: .It Ic login Ar name
1287: Identify a user on the remote machine.
1288: If this token is present, the auto-login process will initiate
1289: a login using the specified
1290: .Ar name .
1291: .It Ic password Ar string
1292: Supply a password.
1293: If this token is present, the auto-login process will supply the
1294: specified string if the remote server requires a password as part
1295: of the login process.
1296: Note that if this token is present in the
1297: .Pa .netrc
1298: file for any user other
1299: than
1300: .Ar anonymous ,
1.6 millert 1301: .Nm
1.1 deraadt 1302: will abort the auto-login process if the
1303: .Pa .netrc
1304: is readable by
1305: anyone besides the user.
1306: .It Ic account Ar string
1307: Supply an additional account password.
1308: If this token is present, the auto-login process will supply the
1309: specified string if the remote server requires an additional
1310: account password, or the auto-login process will initiate an
1311: .Dv ACCT
1312: command if it does not.
1313: .It Ic macdef Ar name
1314: Define a macro.
1315: This token functions like the
1.6 millert 1316: .Nm
1.1 deraadt 1317: .Ic macdef
1318: command functions.
1319: A macro is defined with the specified name; its contents begin with the
1320: next
1321: .Pa .netrc
1322: line and continue until a null line (consecutive new-line
1323: characters) is encountered.
1324: If a macro named
1325: .Ic init
1326: is defined, it is automatically executed as the last step in the
1327: auto-login process.
1328: .El
1.6 millert 1329: .Sh COMMAND LINE EDITING
1330: .Nm
1.25 aaron 1331: supports interactive command line editing, via the
1.6 millert 1332: .Xr editline 3
1333: library.
1334: It is enabled with the
1335: .Ic edit
1.9 millert 1336: command, and is enabled by default if input is from a tty.
1.6 millert 1337: Previous lines can be recalled and edited with the arrow keys,
1338: and other GNU Emacs-style editing keys may be used as well.
1339: .Pp
1340: The
1341: .Xr editline 3
1342: library is configured with a
1343: .Pa .editrc
1344: file - refer to
1345: .Xr editrc 5
1346: for more information.
1347: .Pp
1348: An extra key binding is available to
1349: .Nm
1350: to provide context sensitive command and filename completion
1351: (including remote file completion).
1352: To use this, bind a key to the
1353: .Xr editline 3
1354: command
1355: .Ic ftp-complete .
1356: By default, this is bound to the TAB key.
1.1 deraadt 1357: .Sh ENVIRONMENT
1.6 millert 1358: .Nm
1.22 aaron 1359: utilizes the following environment variables:
1.15 millert 1360: .Bl -tag -width "FTPSERVERPORT"
1.16 millert 1361: .It Ev FTPMODE
1362: Overrides the default operation mode. Recognized values are:
1363: .Bl -tag -width "passive "
1364: .It passive
1365: passive mode ftp only
1366: .It active
1367: active mode ftp only
1368: .It auto
1369: automatic determination of passive or active (this is the default)
1370: .It gate
1371: gate-ftp mode
1372: .El
1.14 millert 1373: .It Ev FTPSERVER
1374: Host to use as gate-ftp server when
1375: .Ic gate
1376: is enabled.
1377: .It Ev FTPSERVERPORT
1378: Port to use when connecting to gate-ftp server when
1379: .Ic gate
1380: is enabled.
1381: Default is port returned by a
1382: .Fn getservbyname
1.25 aaron 1383: lookup of
1.14 millert 1384: .Dq ftpgate/tcp .
1.1 deraadt 1385: .It Ev HOME
1386: For default location of a
1387: .Pa .netrc
1388: file, if one exists.
1.9 millert 1389: .It Ev PAGER
1390: Used by
1391: .Ic page
1392: to display files.
1.1 deraadt 1393: .It Ev SHELL
1394: For default shell.
1.15 millert 1395: .It Ev TMPDIR
1396: Directory to put temporary files.
1.10 millert 1397: .It Ev ftp_proxy
1398: URL of FTP proxy to use when making FTP URL requests
1399: (if not defined, use the standard ftp protocol).
1.6 millert 1400: .It Ev http_proxy
1.10 millert 1401: URL of HTTP proxy to use when making HTTP URL requests.
1.1 deraadt 1402: .El
1403: .Sh SEE ALSO
1.14 millert 1404: .Xr getservbyname 3 ,
1.6 millert 1405: .Xr editrc 5 ,
1.14 millert 1406: .Xr services 5 ,
1.1 deraadt 1407: .Xr ftpd 8
1408: .Sh HISTORY
1409: The
1.6 millert 1410: .Nm
1.1 deraadt 1411: command appeared in
1412: .Bx 4.2 .
1413: .Sh BUGS
1414: Correct execution of many commands depends upon proper behavior
1415: by the remote server.
1416: .Pp
1417: An error in the treatment of carriage returns
1418: in the
1419: .Bx 4.2
1.22 aaron 1420: ASCII-mode transfer code
1.1 deraadt 1421: has been corrected.
1422: This correction may result in incorrect transfers of binary files
1423: to and from
1424: .Bx 4.2
1.22 aaron 1425: servers using the ASCII type.
1.1 deraadt 1426: Avoid this problem by using the binary image type.