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