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