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