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