1.\" $FreeBSD$ 2.Dd July 2, 1996 3.Dt FETCH 1 4.Os FreeBSD 3.0 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 specifies 144.Dq anonymous 145as its user name, and passes the remote user name and host as the 146.Tn FTP 147session's password, in the form 148.Dq Va remoteuser Ns Li \&@ Ns Va remotehost . 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. 156When multiple proxy protcols are configured, 157.Nm 158will prefer 159.Tn HTTP . 160.Sh HTTP AUTHENTICATION 161The 162.Tn HTTP 163protocol includes support for various methods of authentication. 164Currently, the 165.Dq basic 166method, which provides no security from packet-sniffing or 167man-in-the-middle attacks, is the only method supported in 168.Nm fetch . 169Authentication is enabled by the 170.Ev HTTP_AUTH 171and 172.Ev HTTP_PROXY_AUTH 173environment variables. Both variables have the same format, which 174consists of space-separated list of parameter settings, where each 175setting consists of a colon-separated list of parameters. The first 176two parameters are always the (case-insensitive) authentication scheme 177name and the realm in which authentication is to be performed. If the 178realm is specified as 179.Sq Li \&* , 180then it will match all realms not specified otherwise. 181.Pp 182For the 183.Li basic 184authentication scheme uses two additional optional parameters; the 185first is a user name, and the second is the password associated with 186it. If either the password or both parameters are not specified in 187the environment, and the standard input of 188.Nm 189is connected to a terminal, then 190.Nm 191will prompt the user to enter the missing parameters. Thus, if the 192user is known as 193.Dq Li jane 194in the 195.Dq Li WallyWorld 196realm, and has a password of 197.Dq Li QghiLx79 198there, then she might set her 199.Ev HTTP_AUTH 200variable to: 201.Bl -enum -offset indent 202.It 203.Dq Li basic:WallyWorld:jane:QghiLx79 204.It 205.Dq Li basic:WallyWorld:jane , 206or 207.It 208.Dq Li basic:WallyWorld 209.El 210.Pp 211and 212.Nm 213will prompt for the missing information if it is required. She might 214also specify a realm of 215.Dq Li \&* 216instead of 217.Dq Li WallyWorld 218to indicate that the parameters can be applied to any realm. (This is 219most commonly used in a construction such as 220.Dq Li basic:* , 221which indicates to 222.Nm 223that it may offer to do 224.Li basic 225authentication for any realm. 226.Sh ERRORS 227The 228.Nm 229command returns zero on success, or a non-zero value from 230.Aq Pa sysexits.h 231on failure. If multiple URIs are given for retrieval, 232.Nm 233will attempt all of them and return zero only if all succeeded 234(otherwise it will return the error from the last failure). 235.Sh ENVIRONMENT 236.Bl -tag -width FTP_PASSIVE_MODE -offset indent 237.It Ev FTP_TIMEOUT 238maximum time, in seconds, to wait before aborting an 239.Tn FTP 240connection. 241.It Ev FTP_LOGIN 242the login name used for 243.Tn FTP 244transfers (default 245.Dq Li anonymous ) 246.It Ev FTP_PASSIVE_MODE 247force the use of passive mode FTP 248.It Ev FTP_PASSWORD 249the password used for 250.Tn FTP 251transfers (default 252.Dq Va yourname Ns Li \&@ Ns Va yourhost ) 253.It Ev FTP_PROXY 254the address of 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 of a proxy server which understands 261.Tn HTTP 262.It Ev HTTP_PROXY_AUTH 263defines authentication parameters for 264.Tn HTTP 265proxy servers 266.It Ev HTTP_TIMEOUT 267maximum time, in seconds, to wait before aborting an 268.Tn HTTP 269connection. 270.Sh SEE ALSO 271.Xr ftp 1 , 272.Xr tftp 1 273.Sh HISTORY 274The 275.Nm fetch 276command appeared in 277.Fx 2.1.5 . 278.Sh AUTHORS 279The original implementation of 280.Nm 281was done by Jean-Marc Zucconi. It was extensively re-worked for 282.Fx 3.0 283by Garrett Wollman. 284.Sh BUGS 285There are too many environment variables and command-line options. 286.Pp 287The 288.Fl a 289option is only implemented for certain kinds of 290.Tn HTTP 291failures, and no 292.Tn FTP 293failures. 294.Pp 295Only the 296.Dq basic 297authentication mode is implemented for 298.Tn HTTP . 299This should be replaced by digest authentication. 300