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