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