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