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