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