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