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