1.\"- 2.\" Copyright (c) 2000-2014 Dag-Erling Smørgrav 3.\" Copyright (c) 2013 Michael Gmelin <freebsd@grem.de> 4.\" All rights reserved. 5.\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used 6.\" by permission. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer 13.\" in this position and unchanged. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd March 25, 2015 34.Dt FETCH 1 35.Os 36.Sh NAME 37.Nm fetch 38.Nd retrieve a file by Uniform Resource Locator 39.Sh SYNOPSIS 40.Nm 41.Op Fl 146AadFlMmnPpqRrsUv 42.Op Fl B Ar bytes 43.Op Fl -bind-address= Ns Ar host 44.Op Fl -ca-cert= Ns Ar file 45.Op Fl -ca-path= Ns Ar dir 46.Op Fl -cert= Ns Ar file 47.Op Fl -crl= Ns Ar file 48.Op Fl i Ar file 49.Op Fl -key= Ns Ar file 50.Op Fl N Ar file 51.Op Fl -no-passive 52.Op Fl -no-proxy= Ns Ar list 53.Op Fl -no-sslv3 54.Op Fl -no-tlsv1 55.Op Fl -no-verify-hostname 56.Op Fl -no-verify-peer 57.Op Fl o Ar file 58.Op Fl -referer= Ns Ar URL 59.Op Fl S Ar bytes 60.Op Fl T Ar seconds 61.Op Fl -user-agent= Ns Ar agent-string 62.Op Fl w Ar seconds 63.Ar URL ... 64.Nm 65.Op Fl 146AadFlMmnPpqRrsUv 66.Op Fl B Ar bytes 67.Op Fl -bind-address= Ns Ar host 68.Op Fl -ca-cert= Ns Ar file 69.Op Fl -ca-path= Ns Ar dir 70.Op Fl -cert= Ns Ar file 71.Op Fl -crl= Ns Ar file 72.Op Fl i Ar file 73.Op Fl -key= Ns Ar file 74.Op Fl N Ar file 75.Op Fl -no-passive 76.Op Fl -no-proxy= Ns Ar list 77.Op Fl -no-sslv3 78.Op Fl -no-tlsv1 79.Op Fl -no-verify-hostname 80.Op Fl -no-verify-peer 81.Op Fl o Ar file 82.Op Fl -referer= Ns Ar URL 83.Op Fl S Ar bytes 84.Op Fl T Ar seconds 85.Op Fl -user-agent= Ns Ar agent-string 86.Op Fl w Ar seconds 87.Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc 88.Sh DESCRIPTION 89The 90.Nm 91utility provides a command-line interface to the 92.Xr fetch 3 93library. 94Its purpose is to retrieve the file(s) pointed to by the URL(s) on the 95command line. 96.Pp 97The following options are available: 98.Bl -tag -width Fl 99.It Fl 1 , -one-file 100Stop and return exit code 0 at the first successfully retrieved file. 101.It Fl 4 , -ipv4-only 102Forces 103.Nm 104to use IPv4 addresses only. 105.It Fl 6 , -ipv6-only 106Forces 107.Nm 108to use IPv6 addresses only. 109.It Fl A , -no-redirect 110Do not automatically follow ``temporary'' (302) redirects. 111Some broken Web sites will return a redirect instead of a not-found 112error when the requested object does not exist. 113.It Fl a , -retry 114Automatically retry the transfer upon soft failures. 115.It Fl B Ar bytes , Fl -buffer-size= Ns Ar bytes 116Specify the read buffer size in bytes. 117The default is 16,384 bytes. 118Attempts to set a buffer size lower than this will be silently 119ignored. 120The number of reads actually performed is reported at verbosity level 121two or higher (see the 122.Fl v 123flag). 124.It Fl -bind-address= Ns Ar host 125Specifies a hostname or IP address to which sockets used for outgoing 126connections will be bound. 127.It Fl c Ar dir 128The file to retrieve is in directory 129.Ar dir 130on the remote host. 131This option is deprecated and is provided for backward compatibility 132only. 133.It Fl -ca-cert= Ns Ar file 134[SSL] 135Path to certificate bundle containing trusted CA certificates. 136If not specified, 137.Pa /etc/ssl/cert.pem 138is used. 139The file may contain multiple CA certificates. The port 140.Pa security/ca_root_nss 141is a common source of a current CA bundle. 142.It Fl -ca-path= Ns Ar dir 143[SSL] 144The directory 145.Ar dir 146contains trusted CA hashes. 147.It Fl -cert= Ns Ar file 148[SSL] 149.Ar file 150is a PEM encoded client certificate/key which will be used in 151client certificate authentication. 152.It Fl -crl= Ns Ar file 153[SSL] 154Points to certificate revocation list 155.Ar file , 156which has to be in PEM format and may contain peer certificates that have 157been revoked. 158.It Fl d , -direct 159Use a direct connection even if a proxy is configured. 160.It Fl F , -force-restart 161In combination with the 162.Fl r 163flag, forces a restart even if the local and remote files have 164different modification times. 165Implies 166.Fl R . 167.It Fl f Ar file 168The file to retrieve is named 169.Ar file 170on the remote host. 171This option is deprecated and is provided for backward compatibility 172only. 173.It Fl h Ar host 174The file to retrieve is located on the host 175.Ar host . 176This option is deprecated and is provided for backward compatibility 177only. 178.It Fl i Ar file , Fl -if-modified-since= Ns Ar file 179If-Modified-Since mode: the remote file will only be retrieved if it 180is newer than 181.Ar file 182on the local host. 183(HTTP only) 184.It Fl -key= Ns Ar file 185[SSL] 186.Ar file 187is a PEM encoded client key that will be used in client certificate 188authentication in case key and client certificate are stored separately. 189.It Fl l , -symlink 190If the target is a file-scheme URL, make a symbolic link to the target 191rather than trying to copy it. 192.It Fl M 193.It Fl m , -mirror 194Mirror mode: if the file already exists locally and has the same size 195and modification time as the remote file, it will not be fetched. 196Note that the 197.Fl m 198and 199.Fl r 200flags are mutually exclusive. 201.It Fl N Ar file , Fl -netrc= Ns Ar file 202Use 203.Ar file 204instead of 205.Pa ~/.netrc 206to look up login names and passwords for FTP sites. 207See 208.Xr ftp 1 209for a description of the file format. 210This feature is experimental. 211.It Fl n , -no-mtime 212Do not preserve the modification time of the transferred file. 213.It Fl -no-passive 214Forces the FTP code to use active mode. 215.It Fl -no-proxy= Ns Ar list 216Either a single asterisk, which disables the use of proxies 217altogether, or a comma- or whitespace-separated list of hosts for 218which proxies should not be used. 219.It Fl -no-sslv3 220[SSL] 221Don't allow SSL version 3 when negotiating the connection. 222.It Fl -no-tlsv1 223[SSL] 224Don't allow TLS version 1 when negotiating the connection. 225.It Fl -no-verify-hostname 226[SSL] 227Do not verify that the hostname matches the subject of the 228certificate presented by the server. 229.It Fl -no-verify-peer 230[SSL] 231Do not verify the peer certificate against trusted CAs. 232.It Fl o Ar file , Fl output= Ns Ar file 233Set the output file name to 234.Ar file . 235By default, a ``pathname'' is extracted from the specified URI, and 236its basename is used as the name of the output file. 237A 238.Ar file 239argument of 240.Sq Li \&- 241indicates that results are to be directed to the standard output. 242If the 243.Ar file 244argument is a directory, fetched file(s) will be placed within the 245directory, with name(s) selected as in the default behaviour. 246.It Fl P 247.It Fl p , -passive 248Use passive FTP. 249These flags have no effect, since passive FTP is the default, but are 250provided for compatibility with earlier versions where active FTP was 251the default. 252To force active mode, use the 253.Fl -no-passive 254flag or set the 255.Ev FTP_PASSIVE_MODE 256environment variable to 257.Ql NO . 258.It Fl -referer= Ns Ar URL 259Specifies the referrer URL to use for HTTP requests. 260If 261.Ar URL 262is set to 263.Dq auto , 264the document URL will be used as referrer URL. 265.It Fl q , -quiet 266Quiet mode. 267.It Fl R , -keep-output 268The output files are precious, and should not be deleted under any 269circumstances, even if the transfer failed or was incomplete. 270.It Fl r , -restart 271Restart a previously interrupted transfer. 272Note that the 273.Fl m 274and 275.Fl r 276flags are mutually exclusive. 277.It Fl S Ar bytes , Fl -require-size= Ns Ar bytes 278Require the file size reported by the server to match the specified 279value. 280If it does not, a message is printed and the file is not fetched. 281If the server does not support reporting file sizes, this option is 282ignored and the file is fetched unconditionally. 283.It Fl s , -print-size 284Print the size in bytes of each requested file, without fetching it. 285.It Fl T Ar seconds , Fl -timeout= Ns Ar seconds 286Set timeout value to 287.Ar seconds . 288Overrides the environment variables 289.Ev FTP_TIMEOUT 290for FTP transfers or 291.Ev HTTP_TIMEOUT 292for HTTP transfers if set. 293.It Fl U , -passive-portrange-default 294When using passive FTP, allocate the port for the data connection from 295the low (default) port range. 296See 297.Xr ip 4 298for details on how to specify which port range this corresponds to. 299.It Fl -user-agent= Ns Ar agent-string 300Specifies the User-Agent string to use for HTTP requests. 301This can be useful when working with HTTP origin or proxy servers that 302differentiate between user agents. 303.It Fl v , -verbose 304Increase verbosity level. 305.It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds 306When the 307.Fl a 308flag is specified, wait this many seconds between successive retries. 309.El 310.Pp 311If 312.Nm 313receives a 314.Dv SIGINFO 315signal (see the 316.Cm status 317argument for 318.Xr stty 1 ) , 319the current transfer rate statistics will be written to the 320standard error output, in the same format as the standard completion 321message. 322.Sh ENVIRONMENT 323.Bl -tag -width HTTP_TIMEOUT 324.It Ev FTP_TIMEOUT 325Maximum time, in seconds, to wait before aborting an FTP connection. 326.It Ev HTTP_TIMEOUT 327Maximum time, in seconds, to wait before aborting an HTTP connection. 328.El 329.Pp 330See 331.Xr fetch 3 332for a description of additional environment variables, including 333.Ev FETCH_BIND_ADDRESS , 334.Ev FTP_LOGIN , 335.Ev FTP_PASSIVE_MODE , 336.Ev FTP_PASSWORD , 337.Ev FTP_PROXY , 338.Ev ftp_proxy , 339.Ev HTTP_ACCEPT , 340.Ev HTTP_AUTH , 341.Ev HTTP_PROXY , 342.Ev http_proxy , 343.Ev HTTP_PROXY_AUTH , 344.Ev HTTP_REFERER , 345.Ev HTTP_USER_AGENT , 346.Ev NETRC , 347.Ev NO_PROXY , 348.Ev no_proxy , 349.Ev SSL_CA_CERT_FILE , 350.Ev SSL_CA_CERT_PATH , 351.Ev SSL_CLIENT_CERT_FILE , 352.Ev SSL_CLIENT_KEY_FILE , 353.Ev SSL_CRL_FILE , 354.Ev SSL_NO_SSL3 , 355.Ev SSL_NO_TLS1 , 356.Ev SSL_NO_VERIFY_HOSTNAME 357and 358.Ev SSL_NO_VERIFY_PEER . 359.Sh EXIT STATUS 360The 361.Nm 362command returns zero on success, or one on failure. 363If multiple URLs are listed on the command line, 364.Nm 365will attempt to retrieve each one of them in turn, and will return 366zero only if they were all successfully retrieved. 367.Pp 368If the 369.Fl i 370argument is used and the remote file is not newer than the 371specified file then the command will still return success, 372although no file is transferred. 373.Sh SEE ALSO 374.Xr fetch 3 375.Sh HISTORY 376The 377.Nm 378command appeared in 379.Fx 2.1.5 . 380This implementation first appeared in 381.Fx 4.1 . 382.Sh AUTHORS 383.An -nosplit 384The original implementation of 385.Nm 386was done by 387.An Jean-Marc Zucconi Aq Mt jmz@FreeBSD.org . 388It was extensively re-worked for 389.Fx 2.2 390by 391.An Garrett Wollman Aq Mt wollman@FreeBSD.org , 392and later completely rewritten to use the 393.Xr fetch 3 394library by 395.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 396and 397.An Michael Gmelin Aq Mt freebsd@grem.de . 398.Sh NOTES 399The 400.Fl b 401and 402.Fl t 403options are no longer supported and will generate warnings. 404They were workarounds for bugs in other OSes which this implementation 405does not trigger. 406.Pp 407One cannot both use the 408.Fl h , 409.Fl c 410and 411.Fl f 412options and specify URLs on the command line. 413