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