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