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