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