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