1.\" $Id: fetch.1,v 1.16 1997/02/22 23:43:32 wosch Exp $ 2.Dd July 2, 1996 3.Dt FETCH 1 4.Os FreeBSD 2.2 5.Sh NAME 6.Nm fetch 7.Nd retrieve a file by Uniform Resource Locator 8.Sh SYNOPSIS 9.Nm fetch 10.Op Fl MPamnpqr 11.Op Fl o Ar file 12.Ar URL 13.Op Ar ... 14.Nm fetch 15.Op Fl MPRmnpqr 16.Op Fl o Ar file 17.Op Fl c Ar dir 18.Fl f Ar file 19.Fl h Ar host 20.Sh DESCRIPTION 21.Nm fetch 22allows a user to transfer files from a remote network site using 23either the 24.Tn FTP 25or the 26.Tn HTTP 27protocol. In the first form of the command, the 28.Ar URL 29may be of the form 30.Li http://site.domain/path/to/the/file 31or 32.Li ftp://site.domain/path/to/the/file. 33To denote a local filename to be copied or linked to (see the 34.Fl l 35flag below), the 36.Em file:/path/to/the/file 37URL form is used. 38.Pp 39The second form of the command can be used to get a file using the 40.Tn FTP 41protocol, specifying the file name and the remote host with the 42.Fl h 43and the 44.Fl f 45flags. 46.Pp 47The following options are available: 48.Bl -tag -width Fl 49.It Fl a 50Automatically retry the transfer upon soft failures. 51.It Fl c Ar dir 52The file to retrieve is in directory 53.Ar dir 54on the remote host. 55.It Fl f Ar file 56The file to retrieve is named 57.Ar file 58on the remote host. 59.It Fl h Ar host 60The file to retrieve is located on the host 61.Ar host . 62.It Fl l 63If target is a 64.Ar file:/ 65style of URL, make a link to the target rather than trying 66to copy it. 67.It Fl M 68.It Fl m 69Mirror mode: Set the modification time of the file so that it is 70identical to the modification time of the file at the remote host. 71If the file already exists on the local host and is identical (as 72gauged by size and modification time), no transfer is done. 73.It Fl n 74Don't preserve the modtime of the transfered file, use the current time. 75.It Fl o Ar file 76Set the output file name to 77.Ar file . 78By default, a ``pathname'' is extracted from the specified URI, and 79its basename is used as the name of the output file. A 80.Ar file 81argument of 82.Sq Li \&- 83indicates that results are to be directed to the standard output. 84.It Fl P 85.It Fl p 86Use the passive mode of the 87.Tn FTP 88protocol. This is useful for crossing certain sorts of firewalls. 89.It Fl q 90Quiet mode. Do not report transfer progress on the terminal. 91.It Fl R 92The filenames specified are ``precious'', and should not be deleted 93under any circumstances, even if the transfer failed or was incomplete. 94.It Fl r 95Restart a previously interrupted transfer. 96.It Fl T Ar seconds 97Set timeout value to 98.Ar seconds. 99Overrides the environment variables 100.Ev FTP_TIMEOUT 101for ftp transfers or 102.Ev HTTP_TIMEOUT 103for http transfers if set. 104.It Fl v 105Increase verbosity. More 106.Fl v Ns \&'s 107result in more information. 108.El 109.Pp 110Many options are also controlled solely by the environment (this is a 111bug). 112.Sh PROXY SERVERS 113Many sites use application gateways (``proxy servers'') in their 114firewalls in order to allow communication across the firewall using a 115trusted protocol. The 116.Nm fetch 117program can use both the 118.Tn FTP 119and the 120.Tn HTTP 121protocol with a proxy server. 122.Tn FTP 123proxy servers can only relay 124.Tn FTP 125requests; 126.Tn HTTP 127proxy servers can relay both 128.Tn FTP 129and 130.Tn HTTP 131requests. 132A proxy server can be configured by defining an environment variable 133named 134.Dq Va PROTO Ns Ev _PROXY , 135where 136.Va PROTO 137is the name of the protocol in upper case. The value of the 138environment variable specifies a hostname, optionally followed by a 139colon and a port number. 140.Pp 141The 142.Tn FTP 143proxy client passes the remote username, host and port as the 144.Tn FTP 145session's username, in the form 146.Do Va remoteuser Ns Li \&@ Ns Va remotehost 147.Op Li \^@ Ns Va port 148.Dc . 149The 150.Tn HTTP 151proxy client simply passes the originally-requested URI to the remote 152server in an 153.Tn HTTP 154.Dq Li GET 155request. HTTP proxy authentication is not yet implemented. 156.Sh HTTP AUTHENTICATION 157The 158.Tn HTTP 159protocol includes support for various methods of authentication. 160Currently, the 161.Dq basic 162method, which provides no security from packet-sniffing or 163man-in-the-middle attacks, is the only method supported in 164.Nm fetch . 165Authentication is enabled by the 166.Ev HTTP_AUTH 167and 168.Ev HTTP_PROXY_AUTH 169environment variables. Both variables have the same format, which 170consists of space-separated list of parameter settings, where each 171setting consists of a colon-separated list of parameters. The first 172two parameters are always the (case-insensitive) authentication scheme 173name and the realm in which authentication is to be performed. If the 174realm is specified as 175.Sq Li \&* , 176then it will match all realms not specified otherwise. 177.Pp 178For the 179.Li basic 180authentication scheme uses two additional optional parameters; the 181first is a user name, and the second is the password associated with 182it. If either the password or both parameters are not specified in 183the environment, and the standard input of 184.Nm 185is connected to a terminal, then 186.Nm 187will prompt the user to enter the missing parameters. Thus, if the 188user is known as 189.Dq Li jane 190in the 191.Dq Li WallyWorld 192realm, and has a password of 193.Dq Li QghiLx79 194there, then she might set her 195.Ev HTTP_AUTH 196variable to: 197.Bl -enum -offset indent 198.It 199.Dq Li basic:WallyWorld:jane:QghiLx79 200.It 201.Dq Li basic:WallyWorld:jane , 202or 203.It 204.Dq Li basic:WallyWorld 205.El 206.Pp 207and 208.Nm 209will prompt for the missing information if it is required. She might 210also specify a realm of 211.Dq Li \&* 212instead of 213.Dq Li WallyWorld 214to indicate that the parameters can be applied to any realm. (This is 215most commonly used in a construction such as 216.Dq Li basic:* , 217which indicates to 218.Nm 219that it may offer to do 220.Li basic 221authentication for any realm. 222.Sh ERRORS 223The 224.Nm 225command returns zero on success, or a non-zero value from 226.Aq Pa sysexits.h 227on failure. If multiple URIs are given for retrieval, 228.Nm 229will attempt all of them and return zero only if all succeeded 230(otherwise it will return the error from the last failure). 231.Sh ENVIRONMENT 232.Bl -tag -width FTP_PASSIVE_MODE -offset indent 233.It Ev FTP_TIMEOUT 234maximum time, in seconds, to wait before aborting an 235.Tn FTP 236connection. 237.It Ev FTP_LOGIN 238the login name used for 239.Tn FTP 240transfers (default 241.Dq Li anonymous ) 242.It Ev FTP_PASSIVE_MODE 243force the use of passive mode FTP 244.It Ev FTP_PASSWORD 245the password used for 246.Tn FTP 247transfers (default 248.Dq Va yourname Ns Li \&@ Ns Va yourhost ) 249.It Ev FTP_PROXY 250the address (in the form 251.Do Va hostname Ns 252.Op Li : Ns Va port 253.Dc ) 254of a proxy server which understands 255.Tn FTP 256.It Ev HTTP_AUTH 257defines authentication parameters for 258.Tn HTTP 259.It Ev HTTP_PROXY 260the address (in the form 261.Do Va hostname Ns 262.Op Li : Ns Va port 263.Dc ) 264of a proxy server which understands 265.Tn HTTP 266.It Ev HTTP_PROXY_AUTH 267defines authentication parameters for 268.Tn HTTP 269proxy servers 270.It Ev HTTP_TIMEOUT 271maximum time, in seconds, to wait before aborting an 272.Tn HTTP 273connection. 274.Sh SEE ALSO 275.Xr ftp 1 , 276.Xr tftp 1 277.Sh HISTORY 278The 279.Nm fetch 280command appeared in 281.Fx 2.1.5 . 282.Sh AUTHORS 283The original implementation of 284.Nm 285was done by Jean-Marc Zucconi. It was extensively re-worked for 286.Fx 2.2 287by Garrett Wollman. 288.Sh BUGS 289There are too many environment variables and command-line options. 290.Pp 291The 292.Fl a 293option is only implemented for certain kinds of 294.Tn HTTP 295failures, and no 296.Tn FTP 297failures. 298.Pp 299Only the 300.Dq basic 301authentication mode is implemented for 302.Tn HTTP . 303This should be replaced by digest authentication. 304