diff options
Diffstat (limited to 'src/ftp.1')
| -rw-r--r-- | src/ftp.1 | 357 |
1 files changed, 203 insertions, 154 deletions
diff --git a/src/ftp.1 b/src/ftp.1 index 917980f4081f..34a88c23520b 100644 --- a/src/ftp.1 +++ b/src/ftp.1 @@ -1,6 +1,7 @@ -.\" $NetBSD: ftp.1,v 1.109 2005/02/20 20:54:01 wiz Exp $ +.\" $NetBSD: ftp.1,v 1.13 2009/11/15 10:12:37 lukem Exp $ +.\" from NetBSD: ftp.1,v 1.130 2009/07/11 18:35:48 joerg Exp .\" -.\" Copyright (c) 1996-2004 The NetBSD Foundation, Inc. +.\" Copyright (c) 1996-2008 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation @@ -14,13 +15,6 @@ .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the NetBSD -.\" Foundation, Inc. and its contributors. -.\" 4. Neither the name of The NetBSD Foundation nor the names of its -.\" contributors may be used to endorse or promote products derived -.\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED @@ -64,16 +58,15 @@ .\" .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 .\" -.Dd January 15, 2005 +.Dd May 10, 2008 .Dt FTP 1 .Os .Sh NAME .Nm ftp -.Nd -Internet file transfer program +.Nd Internet file transfer program .Sh SYNOPSIS .Nm -.Op Fl 46AadefginpRtvV +.Op Fl 46AadefginpRtVv .Bk -words .Op Fl N Ar netrc .Ek @@ -89,6 +82,7 @@ Internet file transfer program .Bk -words .Op Fl r Ar retry .Ek +.Op Fl s Ar srcaddr .Bk -words .\" [-T dir,max[,inc]] .Oo @@ -179,7 +173,7 @@ below for more information. .Pp Options may be specified at the command line, or to the command interpreter. -.Bl -tag -width "port " +.Bl -tag -width Fl .It Fl 4 Forces .Nm @@ -219,6 +213,14 @@ Disables file name globbing. .It Fl i Turns off interactive prompting during multiple file transfers. +.It Fl N Ar netrc +Use +.Ar netrc +instead of +.Pa ~/.netrc . +Refer to +.Sx THE .netrc FILE +for more information. .It Fl n Restrains .Nm @@ -238,14 +240,6 @@ identity on the local machine), and, if necessary, prompt for a password and an account with which to login. To override the auto-login for auto-fetch transfers, specify the username (and optionally, password) as appropriate. -.It Fl N Ar netrc -Use -.Ar netrc -instead of -.Pa ~/.netrc . -Refer to -.Sx THE .netrc FILE -for more information. .It Fl o Ar output When auto-fetching files, save the contents in .Ar output . @@ -263,35 +257,32 @@ then only the first file specified will be retrieved into .Ar output ; all other files will be retrieved into the basename of their remote name. +.It Fl P Ar port +Sets the port number to +.Ar port . .It Fl p Enable passive mode operation for use behind connection filtering firewalls. This option has been deprecated as .Nm now tries to use passive mode by default, falling back to active mode if the server does not support passive connections. -.It Fl P Ar port -Sets the port number to -.Ar port . -.It Fl r Ar wait -Retry the connection attempt if it failed, pausing for -.Ar wait -seconds. .It Fl q Ar quittime Quit if the connection has stalled for .Ar quittime seconds. .It Fl R Restart all non-proxied auto-fetches. +.It Fl r Ar wait +Retry the connection attempt if it failed, pausing for +.Ar wait +seconds. +.It Fl s Ar srcaddr +Uses +.Ar srcaddr +as the local IP address for all connections. .It Fl t Enables packet tracing. -.It Xo -.Fl T -.Sm off -.Ar direction , -.Ar maximum -.Op , Ar increment -.Sm on -.Xc +.It Fl T Ar direction Ns , Ns Ar maximum Ns Oo , Ns Ar increment Oc Set the maximum transfer rate for .Ar direction to @@ -312,6 +303,12 @@ is one of the ftp URL types as supported by auto-fetch (with an optional target filename for single file uploads), and .Ar file is one or more local files to be uploaded. +.It Fl V +Disable +.Ic verbose +and +.Ic progress , +overriding the default of enabled when output is to a terminal. .It Fl v Enable .Ic verbose @@ -325,12 +322,6 @@ Forces .Nm to show all responses from the remote server, as well as report on data transfer statistics. -.It Fl V -Disable -.Ic verbose -and -.Ic progress , -overriding the default of enabled when output is to a terminal. .El .Pp The client host with which @@ -351,8 +342,8 @@ is awaiting commands from the user the prompt is provided to the user. The following commands are recognized by -.Nm ftp : -.Bl -tag -width Fl +.Nm ftp : +.Bl -tag -width Ic .It Ic \&! Op Ar command Op Ar args Invoke an interactive shell on the local machine. If there are arguments, the first is taken to be a command to execute @@ -455,16 +446,6 @@ when an ascii type transfer is made, these linefeeds may be distinguished from a record delimiter only when .Ic \&cr is off. -.It Ic debug Op Ar debug-value -Toggle debugging mode. -If an optional -.Ar debug-value -is specified it is used to set the debugging level. -When debugging is on, -.Nm -prints each command sent to the remote machine, preceded -by the string -.Ql \-\-\*[Gt] .It Ic delete Ar remote-file Delete the file .Ar remote-file @@ -500,12 +481,13 @@ Toggle command line editing, and context sensitive command and file completion. This is automatically enabled if input is from a terminal, and disabled otherwise. -.It Ic epsv4 +.It Ic epsv epsv4 epsv6 Toggle the use of the extended .Dv EPSV and .Dv EPRT -commands on IPv4 connections; first try +commands on all IP, IPv4, and IPv6 connections respectively. +First try .Dv EPSV / .Dv EPRT , and then @@ -514,7 +496,10 @@ and then This is enabled by default. If an extended command fails then this option will be temporarily disabled for the duration of the current connection, or until -.Ic epsv4 +.Ic epsv , +.Ic epsv4 , +or +.Ic epsv6 is executed again. .It Ic exit A synonym for @@ -538,6 +523,16 @@ format is .It Ic ftp Ar host Op Ar port A synonym for .Ic open . +.It Ic ftp_debug Op Ar ftp_debug-value +Toggle debugging mode. +If an optional +.Ar ftp_debug-value +is specified it is used to set the debugging level. +When debugging is on, +.Nm +prints each command sent to the remote machine, preceded +by the string +.Ql \-\-\*[Gt] . .It Ic gate Op Ar host Op Ar port Toggle gate-ftp mode, which used to connect through the TIS FWTK and Gauntlet ftp proxies. @@ -613,8 +608,9 @@ transferring a .Xr tar 1 archive of the subtree (in binary mode). .It Ic hash Op Ar size -Toggle hash-sign (``#'') printing for each data block -transferred. +Toggle hash-sign +.Pq Sq # +printing for each data block transferred. The size of a data block defaults to 1024 bytes. This can be changed by specifying .Ar size @@ -663,24 +659,49 @@ A synonym for Define a macro. Subsequent lines are stored as the macro .Ar macro-name ; -a null line (consecutive newline characters -in a file or -carriage returns from the terminal) terminates macro input mode. +a null line (consecutive newline characters in a file or carriage +returns from the terminal) terminates macro input mode. There is a limit of 16 macros and 4096 total characters in all defined macros. -Macros remain defined until a +Macro names can be a maximum of 8 characters. +Macros are only applicable to the current session they are +defined within (or if defined outside a session, to the session +invoked with the next +.Ic open +command), and remain defined until a .Ic close command is executed. -The macro processor interprets `$' and `\e' as special characters. -A `$' followed by a number (or numbers) is replaced by the +To invoke a macro, use the +.Ic $ +command (see above). +.Pp +The macro processor interprets +.Sq $ +and +.Sq \e +as special characters. +A +.Sq $ +followed by a number (or numbers) is replaced by the corresponding argument on the macro invocation command line. -A `$' followed by an `i' signals that macro processor that the -executing macro is to be looped. -On the first pass `$i' is -replaced by the first argument on the macro invocation command line, -on the second pass it is replaced by the second argument, and so on. -A `\e' followed by any character is replaced by that character. -Use the `\e' to prevent special treatment of the `$'. +A +.Sq $ +followed by an +.Sq i +signals the macro processor that the executing macro is to be +looped. +On the first pass +.Dq $i +is replaced by the first argument on the macro invocation command +line, on the second pass it is replaced by the second argument, +and so on. +A +.Sq \e +followed by any character is replaced by that character. +Use the +.Sq \e +to prevent special treatment of the +.Sq $ . .It Ic mdelete Op Ar remote-files Delete the .Ar remote-files @@ -756,7 +777,9 @@ The default (and only supported) mode is .Dq stream . .It Ic modtime Ar remote-file -Show the last modification time of the file on the remote machine. +Show the last modification time of the file on the remote machine, in +.Li RFC2822 +format. .It Ic more Ar file A synonym for .Ic page . @@ -823,9 +846,18 @@ and .Ic case settings). Variable templating is accomplished by including the -sequences `$1', `$2', ..., `$9' in +sequences +.Dq $1 , +.Dq $2 , +\&... +.Dq $9 +in .Ar inpattern . -Use `\\' to prevent this special treatment of the `$' character. +Use +.Sq \e +to prevent this special treatment of the +.Sq $ +character. All other characters are treated literally, and are used to determine the .Ic nmap .Op Ar inpattern @@ -837,13 +869,19 @@ $1.$2 and the remote file name "mydata.data", $1 would have the value The .Ar outpattern determines the resulting mapped filename. -The sequences `$1', `$2', ...., `$9' are replaced by any value resulting -from the +The sequences +.Dq $1 , +.Dq $2 , +\&... +.Dq $9 +are replaced by any value resulting from the .Ar inpattern template. -The sequence `$0' is replace by the original filename. +The sequence +.Dq $0 +is replaced by the original filename. Additionally, the sequence -.Ql Op Ar seq1 , Ar seq2 +.Dq Op Ar seq1 , Ar seq2 is replaced by .Op Ar seq1 if @@ -862,9 +900,18 @@ the output filename "myfile.data" for input filenames "myfile.data" and "myfile.myfile" for the input filename ".myfile". Spaces may be included in .Ar outpattern , -as in the example: `nmap $1 sed "s/ *$//" \*[Gt] $1' . -Use the `\e' character to prevent special treatment -of the `$','[',']', and `,' characters. +as in the example: +.Dl nmap $1 sed "s/ *$//" \*[Gt] $1 +Use the +.Sq \e +character to prevent special treatment +of the +.Sq $ , +.Sq \&[ , +.Sq \&] , +and +.Sq \&, +characters. .It Ic ntrans Op Ar inchars Op Ar outchars Set or unset the filename character translation mechanism. If no arguments are specified, the filename character @@ -952,7 +999,7 @@ traffic. servers are required to support the .Dv PASV command by -.Li RFC 1123 , +.Li RFC1123 , some do not.) .It Ic pdir Op Ar remote-path Perform @@ -1100,10 +1147,7 @@ A synonym for The arguments specified are sent, verbatim, to the remote .Tn FTP server. -.It Xo -.Ic rate Ar direction -.Op Ar maximum Op Ar increment -.Xc +.It Ic rate Ar direction Oo Ar maximum Oo Ar increment Oc Oc Throttle the maximum transfer rate to .Ar maximum bytes/second. @@ -1126,7 +1170,6 @@ Outgoing transfers. can be modified on the fly by .Ar increment bytes (default: 1024) each time a given signal is received: -.B .Bl -tag -width "SIGUSR1" -offset indent .It Dv SIGUSR1 Increment @@ -1388,10 +1431,7 @@ for more information. .It Ic usage Ar command Print the usage message for .Ar command . -.It Xo -.Ic user Ar user-name -.Op Ar password Op Ar account -.Xc +.It Ic user Ar user-name Oo Ar password Oo Ar account Oc Oc Identify yourself to the remote .Tn FTP server. @@ -1439,7 +1479,9 @@ A synonym for .El .Pp Command arguments which have embedded spaces may be quoted with -quote `"' marks. +quote +.Sq \&" +marks. .Pp Commands which toggle settings can take an explicit .Ic on @@ -1491,14 +1533,8 @@ on the command line. The following formats are valid syntax for an auto-fetch element: .Bl -tag -width "FOO " .\" [user@]host:[path][/] -.It Xo -.Sm off -.Op Ar user Li \&@ -.Ar host Li \&: -.Op Ar path -.Op Li / -.Sm on -.Xc +.It Oo Ar user Ns Li \&@ Oc Ns Ar host Ns Li \&: Ns Oo Ar path Oc \ +Ns Oo Li / Oc .Dq Classic .Tn FTP format. @@ -1523,18 +1559,9 @@ in the current directory. Otherwise, the full remote name is used as the local name, relative to the local root directory. .\" ftp://[user[:password]@]host[:port]/path[/][;type=X] -.It Xo -.Sm off -.Li ftp:// -.Oo Ar user -.Op Li \&: Ar password -.Li \&@ Oc -.Ar host Oo Li \&: Ar port Oc -.Li / Ar path -.Op Li / -.Op Li ;type= Ar X -.Sm on -.Xc +.It Li ftp:// Ns Oo Ar user Ns Oo Ns Li \&: Ns Ar password Oc Ns Li \&@ Oc \ +Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns Li / Ns Ar path Ns Oo Li / Oc \ +Ns Oo Li ;type= Ns Ar X Oc An .Tn FTP URL, retrieved using the @@ -1565,7 +1592,7 @@ ascii or binary (respectively). The default transfer type is binary. .Pp In order to be compliant with -.Li RFC 1738 , +.Li RFC3986 , .Nm interprets the .Ar path @@ -1618,7 +1645,7 @@ Any .Sq Li \&% Ns Ar XX codes (per -.Li RFC 1738 ) +.Li RFC3986 ) within the path components are decoded, with .Ar XX representing a character code in hexadecimal. @@ -1705,16 +1732,8 @@ intermediate directories that is used in the equivalent of a command. .El .\" http://[user[:password]@]host[:port]/path -.It Xo -.Sm off -.Li http:// -.Oo Ar user -.Op Li \&: Ar password -.Li \&@ Oc -.Ar host Oo Li \&: Ar port Oc -.Li / Ar path -.Sm on -.Xc +.It Li http:// Ns Oo Ar user Ns Oo Li \&: Ns Ar password Oc Ns Li \&@ Oc \ +Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns Li / Ns Ar path An .Tn HTTP URL, retrieved using the @@ -1735,14 +1754,25 @@ and .Sq password ) is in the URL, use them for the first attempt to authenticate. .\" file:///path -.It Xo -.Sm off -.Li file:/// Ar path -.Sm on -.Xc +.It Li file:/// Ns Ar path A local URL, copied from .Pa / Ns Ar path on the local host. +.\" about: +.It Li about: Ns Ar topic +Display information regarding +.Ar topic ; +no file is retrieved for this auto-fetched element. +Supported values include: +.Bl -tag -width "about:version" +.It Li about:ftp +Information about +.Nm ftp . +.It Li about:version +The version of +.Nm ftp . +Useful to provide when reporting problems. +.El .El .Pp Unless noted otherwise above, and @@ -1868,11 +1898,12 @@ A particularly useful example of this mechanism is: .Dq Li dir \&"\&" \&|more . .It -Failing the above checks, if ``globbing'' is enabled, -local file names are expanded -according to the rules used in the +Failing the above checks, if +.Dq globbing +is enabled, local file names are expanded according to the rules +used in the .Xr csh 1 ; -c.f. the +see the .Ic glob command. If the @@ -2038,6 +2069,20 @@ next .Pa .netrc line and continue until a blank line (consecutive new-line characters) is encountered. +Like the other tokens in the +.Pa .netrc +file, a +.Ic macdef +is applicable only to the +.Ic machine +definition preceding it. +A +.Ic macdef +entry cannot be used by multiple +.Ic machine +definitions; rather, it must be defined following each +.Ic machine +it is intended to be used with. If a macro named .Ic init is defined, it is automatically executed as the last step in the @@ -2100,14 +2145,7 @@ information: .It Li \&%/ The current remote working directory. .\" %c[[0]n], %.[[0]n] -.It Xo -.Sm off -.Li \&%c -.Op Oo Li 0 Oc Ar n Ns , -.Li \&%. -.Op Oo Li 0 Oc Ar n -.Sm on -.Xc +.It \&%c Ns Oo Oo Li 0 Oc Ns Ar n Oc , Ns Li \&%. Ns Oo Oo Li 0 Oc Ns Ar n Oc The trailing component of the current remote working directory, or .Em n trailing components if a digit @@ -2248,7 +2286,7 @@ URL characters are required in the username or password or .Sq / ) , encode them with -.Li RFC 1738 +.Li RFC3986 .Sq Li \&% Ns Ar XX encoding. .Pp @@ -2291,16 +2329,27 @@ for an example of how to make this automatic. .Xr ftpd 8 .Sh STANDARDS .Nm -attempts to be compliant with -.Li RFC 959 , -.Li RFC 1123 , -.Li RFC 1738 , -.Li RFC 2068 , -.Li RFC 2389 , -.Li RFC 2428 , -.Li RFC 2732 , -and -.Cm draft-ietf-ftpext-mlst-11 . +attempts to be compliant with: +.Bl -tag -offset indent -width 8n +.It Li RFC0959 +.Em File Transfer Protocol +.It Li RFC1123 +.Em Requirements for Internet Hosts - Application and Support +.It Li RFC1635 +.Em How to Use Anonymous FTP +.It Li RFC2389 +.Em Feature negotiation mechanism for the File Transfer Protocol +.It Li RFC2428 +.Em FTP Extensions for IPv6 and NATs +.It Li RFC2616 +.Em Hypertext Transfer Protocol -- HTTP/1.1 +.It Li RFC2822 +.Em Internet Message Format +.It Li RFC3659 +.Em Extensions to FTP +.It Li RFC3986 +.Em Uniform Resource Identifier (URI) +.El .Sh HISTORY The .Nm |