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