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