2 .\" Copyright (c) 2000-2014 Dag-Erling Smørgrav
3 .\" Copyright (c) 2013-2016 Michael Gmelin <freebsd@grem.de>
4 .\" All rights reserved.
5 .\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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.
36 .Nd retrieve a file by Uniform Resource Locator
39 .Op Fl 146AadFlMmnPpqRrsUv
41 .Op Fl -bind-address= Ns Ar host
42 .Op Fl -ca-cert= Ns Ar file
43 .Op Fl -ca-path= Ns Ar dir
44 .Op Fl -cert= Ns Ar file
45 .Op Fl -crl= Ns Ar file
47 .Op Fl -key= Ns Ar file
50 .Op Fl -no-proxy= Ns Ar list
53 .Op Fl -no-verify-hostname
54 .Op Fl -no-verify-peer
56 .Op Fl -referer= Ns Ar URL
59 .Op Fl -user-agent= Ns Ar agent-string
63 .Op Fl 146AadFlMmnPpqRrsUv
65 .Op Fl -bind-address= Ns Ar host
66 .Op Fl -ca-cert= Ns Ar file
67 .Op Fl -ca-path= Ns Ar dir
68 .Op Fl -cert= Ns Ar file
69 .Op Fl -crl= Ns Ar file
71 .Op Fl -key= Ns Ar file
74 .Op Fl -no-proxy= Ns Ar list
77 .Op Fl -no-verify-hostname
78 .Op Fl -no-verify-peer
80 .Op Fl -referer= Ns Ar URL
83 .Op Fl -user-agent= Ns Ar agent-string
85 .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
89 utility provides a command-line interface to the
92 Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
95 The following options are available:
98 Stop and return exit code 0 at the first successfully retrieved file.
102 to use IPv4 addresses only.
103 .It Fl 6 , -ipv6-only
106 to use IPv6 addresses only.
107 .It Fl A , -no-redirect
108 Do not automatically follow ``temporary'' (302) redirects.
109 Some broken Web sites will return a redirect instead of a not-found
110 error when the requested object does not exist.
112 Automatically retry the transfer upon soft failures.
113 .It Fl B Ar bytes , Fl -buffer-size= Ns Ar bytes
114 Specify the read buffer size in bytes.
115 The default is 16,384 bytes.
116 Attempts to set a buffer size lower than this will be silently
118 The number of reads actually performed is reported at verbosity level
119 two or higher (see the
122 .It Fl -bind-address= Ns Ar host
123 Specifies a hostname or IP address to which sockets used for outgoing
124 connections will be bound.
126 The file to retrieve is in directory
129 This option is deprecated and is provided for backward compatibility
131 .It Fl -ca-cert= Ns Ar file
133 Path to certificate bundle containing trusted CA certificates.
135 .Pa /usr/local/etc/ssl/cert.pem
137 If this file does not exist,
138 .Pa /etc/ssl/cert.pem
140 If neither file exists and no CA path has been configured,
141 OpenSSL's default CA cert and path settings apply.
142 The certificate bundle can contain multiple CA certificates.
144 .Pa security/ca_root_nss
145 port is a common source of a current CA bundle.
146 .It Fl -ca-path= Ns Ar dir
150 contains trusted CA hashes.
151 .It Fl -cert= Ns Ar file
154 is a PEM encoded client certificate/key which will be used in
155 client certificate authentication.
156 .It Fl -crl= Ns Ar file
158 Points to certificate revocation list
160 which has to be in PEM format and may contain peer certificates that have
163 Use a direct connection even if a proxy is configured.
164 .It Fl F , -force-restart
165 In combination with the
167 flag, forces a restart even if the local and remote files have
168 different modification times.
172 The file to retrieve is named
175 This option is deprecated and is provided for backward compatibility
178 The file to retrieve is located on the host
180 This option is deprecated and is provided for backward compatibility
182 .It Fl i Ar file , Fl -if-modified-since= Ns Ar file
183 If-Modified-Since mode: the remote file will only be retrieved if it
188 .It Fl -key= Ns Ar file
191 is a PEM encoded client key that will be used in client certificate
192 authentication in case key and client certificate are stored separately.
194 If the target is a file-scheme URL, make a symbolic link to the target
195 rather than trying to copy it.
198 Mirror mode: if the file already exists locally and has the same size
199 and modification time as the remote file, it will not be fetched.
204 flags are mutually exclusive.
205 .It Fl N Ar file , Fl -netrc= Ns Ar file
210 to look up login names and passwords for FTP sites.
213 for a description of the file format.
214 This feature is experimental.
216 Do not preserve the modification time of the transferred file.
218 Forces the FTP code to use active mode.
219 .It Fl -no-proxy= Ns Ar list
220 Either a single asterisk, which disables the use of proxies
221 altogether, or a comma- or whitespace-separated list of hosts for
222 which proxies should not be used.
225 Do not allow SSL version 3 when negotiating the connection.
226 This option is deprecated and is provided for backward compatibility
228 SSLv3 is disabled by default.
231 to change this behavior.
234 Do not allow TLS version 1 when negotiating the connection.
235 .It Fl -no-verify-hostname
237 Do not verify that the hostname matches the subject of the
238 certificate presented by the server.
239 .It Fl -no-verify-peer
241 Do not verify the peer certificate against trusted CAs.
242 .It Fl o Ar file , Fl -output= Ns Ar file
243 Set the output file name to
245 By default, a ``pathname'' is extracted from the specified URI, and
246 its basename is used as the name of the output file.
251 indicates that results are to be directed to the standard output.
254 argument is a directory, fetched file(s) will be placed within the
255 directory, with name(s) selected as in the default behaviour.
259 These flags have no effect, since passive FTP is the default, but are
260 provided for compatibility with earlier versions where active FTP was
262 To force active mode, use the
266 environment variable to
268 .It Fl -referer= Ns Ar URL
269 Specifies the referrer URL to use for HTTP requests.
274 the document URL will be used as referrer URL.
277 .It Fl R , -keep-output
278 The output files are precious, and should not be deleted under any
279 circumstances, even if the transfer failed or was incomplete.
281 Restart a previously interrupted transfer.
286 flags are mutually exclusive.
287 .It Fl S Ar bytes , Fl -require-size= Ns Ar bytes
288 Require the file size reported by the server to match the specified
290 If it does not, a message is printed and the file is not fetched.
291 If the server does not support reporting file sizes, this option is
292 ignored and the file is fetched unconditionally.
293 .It Fl s , -print-size
294 Print the size in bytes of each requested file, without fetching it.
295 .It Fl T Ar seconds , Fl -timeout= Ns Ar seconds
298 Overrides the environment variables
302 for HTTP transfers if set.
303 .It Fl U , -passive-portrange-default
304 When using passive FTP, allocate the port for the data connection from
305 the low (default) port range.
308 for details on how to specify which port range this corresponds to.
309 .It Fl -user-agent= Ns Ar agent-string
310 Specifies the User-Agent string to use for HTTP requests.
311 This can be useful when working with HTTP origin or proxy servers that
312 differentiate between user agents.
314 Increase verbosity level.
315 .It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds
318 flag is specified, wait this many seconds between successive retries.
329 the current transfer rate statistics will be written to the
330 standard error output, in the same format as the standard completion
333 .Bl -tag -width HTTP_TIMEOUT
335 Maximum time, in seconds, to wait before aborting an FTP connection.
337 Maximum time, in seconds, to wait before aborting an HTTP connection.
342 for a description of additional environment variables, including
343 .Ev FETCH_BIND_ADDRESS ,
345 .Ev FTP_PASSIVE_MODE ,
353 .Ev HTTP_PROXY_AUTH ,
355 .Ev HTTP_USER_AGENT ,
359 .Ev SSL_CA_CERT_FILE ,
360 .Ev SSL_CA_CERT_PATH ,
361 .Ev SSL_CLIENT_CERT_FILE ,
362 .Ev SSL_CLIENT_KEY_FILE ,
368 .Ev SSL_NO_VERIFY_HOSTNAME
370 .Ev SSL_NO_VERIFY_PEER .
374 command returns zero on success, or one on failure.
375 If multiple URLs are listed on the command line,
377 will attempt to retrieve each one of them in turn, and will return
378 zero only if they were all successfully retrieved.
382 argument is used and the remote file is not newer than the
383 specified file then the command will still return success,
384 although no file is transferred.
386 Silently try to fetch the URLs passed as parameters.
387 The first one will fail.
388 If the second URL succeeds the third one will not be tried:
389 .Bd -literal -offset indent
390 $ fetch -1 -q https://www.freebsd.org/bad.html \e
391 ftp.freebsd.org/pub/FreeBSD/README.TXT \e
393 fetch: https://www.freebsd.org/bad.html: Not Found
396 Be verbose when retrieving the
399 .Bd -literal -offset indent
400 $ fetch -v ftp.freebsd.org/pub/FreeBSD/README.TXT
401 resolving server address: ftp.freebsd.org:80
402 requesting http://ftp.freebsd.org/pub/FreeBSD/README.TXT
403 local size / mtime: 4259 / 1431015519
404 remote size / mtime: 4259 / 1431015519
405 README.TXT 4259 B 44 MBps 00s
412 and do not delete the output file under any circumstances:
413 .Bd -literal -offset indent
414 fetch -o myreadme.txt -q -R ftp.freebsd.org/pub/FreeBSD/README.TXT
417 Print the size of the requested file and identify the request with a custom user
419 .Bd -literal -offset indent
420 $ fetch -s ftp.freebsd.org/pub/FreeBSD/README.TXT
421 --user-agent="Mozilla/5.0 (X11; FreeBSD x86_64; rv:78.0) Gecko/20100101"
425 Restart the transfer of the
427 file and retry the transfer upon soft failures:
428 .Bd -literal -offset indent
429 $ fetch -a -r http://ftp.freebsd.org/pub/FreeBSD/README.TXT
439 This implementation first appeared in
443 The original implementation of
446 .An Jean-Marc Zucconi Aq Mt jmz@FreeBSD.org .
447 It was extensively re-worked for
450 .An Garrett Wollman Aq Mt wollman@FreeBSD.org ,
451 and later completely rewritten to use the
454 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org
456 .An Michael Gmelin Aq Mt freebsd@grem.de .
462 options are no longer supported and will generate warnings.
463 They were workarounds for bugs in other OSes which this implementation
466 One cannot both use the
471 options and specify URLs on the command line.