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