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