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