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