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.
38 .Nd retrieve a file by Uniform Resource Locator
41 .Op Fl 146AadFlMmnPpqRrsUv
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
49 .Op Fl -key= Ns Ar file
52 .Op Fl -no-proxy= Ns Ar list
55 .Op Fl -no-verify-hostname
56 .Op Fl -no-verify-peer
58 .Op Fl -referer= Ns Ar URL
61 .Op Fl -user-agent= Ns Ar agent-string
65 .Op Fl 146AadFlMmnPpqRrsUv
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
73 .Op Fl -key= Ns Ar file
76 .Op Fl -no-proxy= Ns Ar list
79 .Op Fl -no-verify-hostname
80 .Op Fl -no-verify-peer
82 .Op Fl -referer= Ns Ar URL
85 .Op Fl -user-agent= Ns Ar agent-string
87 .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
91 utility provides a command-line interface to the
94 Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
97 The following options are available:
100 Stop and return exit code 0 at the first successfully retrieved file.
101 .It Fl 4 , -ipv4-only
104 to use IPv4 addresses only.
105 .It Fl 6 , -ipv6-only
108 to use IPv6 addresses only.
109 .It Fl A , -no-redirect
110 Do not automatically follow ``temporary'' (302) redirects.
111 Some broken Web sites will return a redirect instead of a not-found
112 error when the requested object does not exist.
114 Automatically retry the transfer upon soft failures.
115 .It Fl B Ar bytes , Fl -buffer-size= Ns Ar bytes
116 Specify the read buffer size in bytes.
117 The default is 16,384 bytes.
118 Attempts to set a buffer size lower than this will be silently
120 The number of reads actually performed is reported at verbosity level
121 two or higher (see the
124 .It Fl -bind-address= Ns Ar host
125 Specifies a hostname or IP address to which sockets used for outgoing
126 connections will be bound.
128 The file to retrieve is in directory
131 This option is deprecated and is provided for backward compatibility
133 .It Fl -ca-cert= Ns Ar file
135 Path to certificate bundle containing trusted CA certificates.
137 .Pa /usr/local/etc/ssl/cert.pem
139 If this file does not exist,
140 .Pa /etc/ssl/cert.pem
142 If neither file exists and no CA path has been configured,
143 OpenSSL's default CA cert and path settings apply.
144 The certificate bundle can contain multiple CA certificates.
146 .Pa security/ca_root_nss
147 port is a common source of a current CA bundle.
148 .It Fl -ca-path= Ns Ar dir
152 contains trusted CA hashes.
153 .It Fl -cert= Ns Ar file
156 is a PEM encoded client certificate/key which will be used in
157 client certificate authentication.
158 .It Fl -crl= Ns Ar file
160 Points to certificate revocation list
162 which has to be in PEM format and may contain peer certificates that have
165 Use a direct connection even if a proxy is configured.
166 .It Fl F , -force-restart
167 In combination with the
169 flag, forces a restart even if the local and remote files have
170 different modification times.
174 The file to retrieve is named
177 This option is deprecated and is provided for backward compatibility
180 The file to retrieve is located on the host
182 This option is deprecated and is provided for backward compatibility
184 .It Fl i Ar file , Fl -if-modified-since= Ns Ar file
185 If-Modified-Since mode: the remote file will only be retrieved if it
190 .It Fl -key= Ns Ar file
193 is a PEM encoded client key that will be used in client certificate
194 authentication in case key and client certificate are stored separately.
196 If the target is a file-scheme URL, make a symbolic link to the target
197 rather than trying to copy it.
200 Mirror mode: if the file already exists locally and has the same size
201 and modification time as the remote file, it will not be fetched.
206 flags are mutually exclusive.
207 .It Fl N Ar file , Fl -netrc= Ns Ar file
212 to look up login names and passwords for FTP sites.
215 for a description of the file format.
216 This feature is experimental.
218 Do not preserve the modification time of the transferred file.
220 Forces the FTP code to use active mode.
221 .It Fl -no-proxy= Ns Ar list
222 Either a single asterisk, which disables the use of proxies
223 altogether, or a comma- or whitespace-separated list of hosts for
224 which proxies should not be used.
227 Do not allow SSL version 3 when negotiating the connection.
228 This option is deprecated and is provided for backward compatibility
230 SSLv3 is disabled by default.
233 to change this behavior.
236 Do not allow TLS version 1 when negotiating the connection.
237 .It Fl -no-verify-hostname
239 Do not verify that the hostname matches the subject of the
240 certificate presented by the server.
241 .It Fl -no-verify-peer
243 Do not verify the peer certificate against trusted CAs.
244 .It Fl o Ar file , Fl -output= Ns Ar file
245 Set the output file name to
247 By default, a ``pathname'' is extracted from the specified URI, and
248 its basename is used as the name of the output file.
253 indicates that results are to be directed to the standard output.
256 argument is a directory, fetched file(s) will be placed within the
257 directory, with name(s) selected as in the default behaviour.
261 These flags have no effect, since passive FTP is the default, but are
262 provided for compatibility with earlier versions where active FTP was
264 To force active mode, use the
268 environment variable to
270 .It Fl -referer= Ns Ar URL
271 Specifies the referrer URL to use for HTTP requests.
276 the document URL will be used as referrer URL.
279 .It Fl R , -keep-output
280 The output files are precious, and should not be deleted under any
281 circumstances, even if the transfer failed or was incomplete.
283 Restart a previously interrupted transfer.
288 flags are mutually exclusive.
289 .It Fl S Ar bytes , Fl -require-size= Ns Ar bytes
290 Require the file size reported by the server to match the specified
292 If it does not, a message is printed and the file is not fetched.
293 If the server does not support reporting file sizes, this option is
294 ignored and the file is fetched unconditionally.
295 .It Fl s , -print-size
296 Print the size in bytes of each requested file, without fetching it.
297 .It Fl T Ar seconds , Fl -timeout= Ns Ar seconds
300 Overrides the environment variables
304 for HTTP transfers if set.
305 .It Fl U , -passive-portrange-default
306 When using passive FTP, allocate the port for the data connection from
307 the low (default) port range.
310 for details on how to specify which port range this corresponds to.
311 .It Fl -user-agent= Ns Ar agent-string
312 Specifies the User-Agent string to use for HTTP requests.
313 This can be useful when working with HTTP origin or proxy servers that
314 differentiate between user agents.
316 Increase verbosity level.
317 .It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds
320 flag is specified, wait this many seconds between successive retries.
331 the current transfer rate statistics will be written to the
332 standard error output, in the same format as the standard completion
335 .Bl -tag -width HTTP_TIMEOUT
337 Maximum time, in seconds, to wait before aborting an FTP connection.
339 Maximum time, in seconds, to wait before aborting an HTTP connection.
344 for a description of additional environment variables, including
345 .Ev FETCH_BIND_ADDRESS ,
347 .Ev FTP_PASSIVE_MODE ,
355 .Ev HTTP_PROXY_AUTH ,
357 .Ev HTTP_USER_AGENT ,
361 .Ev SSL_CA_CERT_FILE ,
362 .Ev SSL_CA_CERT_PATH ,
363 .Ev SSL_CLIENT_CERT_FILE ,
364 .Ev SSL_CLIENT_KEY_FILE ,
370 .Ev SSL_NO_VERIFY_HOSTNAME
372 .Ev SSL_NO_VERIFY_PEER .
376 command returns zero on success, or one on failure.
377 If multiple URLs are listed on the command line,
379 will attempt to retrieve each one of them in turn, and will return
380 zero only if they were all successfully retrieved.
384 argument is used and the remote file is not newer than the
385 specified file then the command will still return success,
386 although no file is transferred.
395 This implementation first appeared in
399 The original implementation of
402 .An Jean-Marc Zucconi Aq Mt jmz@FreeBSD.org .
403 It was extensively re-worked for
406 .An Garrett Wollman Aq Mt wollman@FreeBSD.org ,
407 and later completely rewritten to use the
410 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org
412 .An Michael Gmelin Aq Mt freebsd@grem.de .
418 options are no longer supported and will generate warnings.
419 They were workarounds for bugs in other OSes which this implementation
422 One cannot both use the
427 options and specify URLs on the command line.