diff options
Diffstat (limited to 'usr.bin/fetch/fetch.1')
-rw-r--r-- | usr.bin/fetch/fetch.1 | 195 |
1 files changed, 128 insertions, 67 deletions
diff --git a/usr.bin/fetch/fetch.1 b/usr.bin/fetch/fetch.1 index 1f3ae01..6955250 100644 --- a/usr.bin/fetch/fetch.1 +++ b/usr.bin/fetch/fetch.1 @@ -11,7 +11,7 @@ .Op Fl o Ar file .Ar URL .Nm fetch -.Op Fl MPmnpqr +.Op Fl MPRmnpqr .Op Fl o Ar file .Op Fl c Ar dir .Fl f Ar file @@ -26,22 +26,17 @@ or the protocol. In the first form of the command, the .Ar URL may be of the form -.Em http://site.domain/path/to/the/file +.Li http://site.domain/path/to/the/file or -.Em ftp://site.domain/path/to/the/file. -For compatibility with -.Xr tftp 1 -the form -.Em site.domain:/path/to/the/file -is also accepted. -To denote a local filename to be copied or linked to (see +.Li ftp://site.domain/path/to/the/file. +To denote a local filename to be copied or linked to (see the .Fl l -flag), the +flag below), the .Em file:/path/to/the/file URL form is used. - +.Pp The second form of the command can be used to get a file using the -.Em ftp +.Tn FTP protocol, specifying the file name and the remote host with the .Fl h and the @@ -50,34 +45,51 @@ flags. .Pp The following options are available: .Bl -tag -width Fl -compact -.It Fl M -.It Fl m -Mirror mode: Set the modification time of the file so that it is -identical to the modification time of the file at the remote host. -If the file already exists on the local host and is identical (as -gauged by size and modification time), no transfer is done. -.It Fl n -Don't preserve the modtime of the transfered file, use the current time. -.It Fl P -.It Fl p -Use passive mode if you are behind a firewall. .It Fl c Ar dir -Change to directory +The file to retrieve is in directory .Ar dir -at remote host before starting the transfer. +on the remote host. .It Fl f Ar file -Retrieve +The file to retrieve is named .Ar file on the remote host. .It Fl h Ar host -Set the -.Ar host -for transfer. +The file to retrieve is located on the host +.Ar host . .It Fl l If target is a .Ar file:/ style of URL, make a link to the target rather than trying to copy it. +.It Fl M +.It Fl m +Mirror mode: Set the modification time of the file so that it is +identical to the modification time of the file at the remote host. +If the file already exists on the local host and is identical (as +gauged by size and modification time), no transfer is done. +.It Fl n +Don't preserve the modtime of the transfered file, use the current time. +.It Fl o Ar file +Set the output file name to +.Ar file . +By default, a ``pathname'' is extracted from the specified URI, and +its basename is used as the name of the output file. A +.Ar file +argument of +.Sq Li \&- +indicates that results are to be directed to the standard output. +.It Fl P +.It Fl p +Use the passive mode of the +.Tn FTP +protocol. This is useful for crossing certain sorts of firewalls. +.It Fl q +Quiet mode. Do not report transfer progress on the terminal. +.It Fl R +The filenames specified are ``precious'', and should not be deleted +under any circumstances, even if the transfer failed or was incomplete. +.It Fl r +Restart a previously interrupted transfer. .It Fl T Ar seconds Set timeout value to .Ar seconds. @@ -86,47 +98,90 @@ Overrides the environment variables for ftp transfers or .Ev HTTP_TIMEOUT for http transfers if set. -.It Fl q -Quiet mode. Do not report transfer progress on the terminal. .It Fl v -Verbose mode - display FTP connection information in painful detail. -.It Fl r -Reget. Use this flag to restart an interrupted transfer. -.It Fl o Ar file -Set the output file name to -.Ar file +Increase verbosity. More +.Fl v Ns \&'s +result in more information. .El +.Pp +Many options are also controlled solely by the environment (this is a +bug). +.Sh PROXY SERVERS +Many sites use application gateways (``proxy servers'') in their +firewalls in order to allow communication across the firewall using a +trusted protocol. The +.Nm fetch +program can use both the +.Tn FTP +and the +.Tn HTTP +protocol with a proxy server. +.Tn FTP +proxy servers can only relay +.Tn FTP +requests; +.Tn HTTP +proxy servers can relay both +.Tn FTP +and +.Tn HTTP +requests. +A proxy server can be configured by defining an environment variable +named +.Dq Va PROTO Ns Ev _PROXY , +where +.Va PROTO +is the name of the protocol in upper case. The value of the +environment variable specifies a hostname, optionally followed by a +colon and a port number. +.Pp +The +.Tn FTP +proxy client specifies +.Dq anonymous +as its user name, and passes the remote user name and host as the +.Tn FTP +session's password, in the form +.Dq Va remoteuser Ns Li \&@ Va remotehost . +The +.Tn HTTP +proxy client simply passes the originally-requested URI to the remote +server in an +.Tn HTTP +.Dq Li GET +request. HTTP proxy authentication is not yet implemented. +When multiple proxy protcols are configured, +.Nm +will prefer +.Tn HTTP . .Sh ENVIRONMENT -A transfer using the -.Em ftp -protocol will be aborted after the delay specified by the -.Ev FTP_TIMEOUT -variable. The default is 300 (seconds) - -A transfer using the -.Em http -protocol will be aborted after the delay specified by the -.Ev HTTP_TIMEOUT -variable. The default is 300 (seconds) - -.Ev FTP_LOGIN -is the login name for the remote host. Default is -.Em anonymous - -.Ev FTP_PASSWORD -is the password for the remote host. Default is -.Em <yourname>@ - -.Ev FTP_PASSIVE_MODE -will force the use of passive mode FTP for firewalls. - -If -.Ev HTTP_PROXY -is set to a value of the form -.Em host:port -it specifies the address of a http proxy. The proxy will be used -for all ftp and http requests. This is useful if you are behind -an application firewall. +.Bl -tag -width FTP_PASSIVE_MODE -offset indent +.It Ev FTP_TIMEOUT +maximum time, in seconds, to wait before aborting an +.Tn FTP +connection. +.It Ev HTTP_TIMEOUT +maximum time, in seconds, to wait before aborting an +.Tn HTTP +connection. +.It Ev FTP_LOGIN +the login name used for +.Tn FTP +transfers (default +.Dq Li anonymous ) +.It Ev FTP_PASSWORD +the password used for +.Tn FTP +transfers (default +.Dq Va yourname Ns Li \&@ Ns Va yourhost ) +.It Ev FTP_PASSIVE_MODE +force the use of passive mode FTP +.It Ev HTTP_PROXY +the address of a proxy server which understands +.Tn HTTP +.It Ev FTP_PROXY +the address of a proxy server which understands +.Tn FTP .Sh SEE ALSO .Xr ftp 1 , .Xr tftp 1 @@ -135,3 +190,9 @@ The .Nm fetch command appeared in .Fx 2.1.5 . +.Sh AUTHORS +The original implementation of +.Nm +was done by Jean-Marc Zucconi. It was extensively re-worked for +.Fx 3.0 +by Garrett Wollman. |