usr.bin/fetch/fetch.1

   1 .\"-
   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
   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 .Dd October 29, 2020
  32 .Dt FETCH 1
  33 .Os
  34 .Sh NAME
  35 .Nm fetch
  36 .Nd retrieve a file by Uniform Resource Locator
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl 146AadFlMmnPpqRrsUv
  40 .Op Fl B Ar bytes
  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
  46 .Op Fl i Ar file
  47 .Op Fl -key= Ns Ar file
  48 .Op Fl N Ar file
  49 .Op Fl -no-passive
  50 .Op Fl -no-proxy= Ns Ar list
  51 .Op Fl -no-sslv3
  52 .Op Fl -no-tlsv1
  53 .Op Fl -no-verify-hostname
  54 .Op Fl -no-verify-peer
  55 .Op Fl o Ar file
  56 .Op Fl -referer= Ns Ar URL
  57 .Op Fl S Ar bytes
  58 .Op Fl T Ar seconds
  59 .Op Fl -user-agent= Ns Ar agent-string
  60 .Op Fl w Ar seconds
  61 .Ar URL ...
  62 .Nm
  63 .Op Fl 146AadFlMmnPpqRrsUv
  64 .Op Fl B Ar bytes
  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
  70 .Op Fl i Ar file
  71 .Op Fl -key= Ns Ar file
  72 .Op Fl N Ar file
  73 .Op Fl -no-passive
  74 .Op Fl -no-proxy= Ns Ar list
  75 .Op Fl -no-sslv3
  76 .Op Fl -no-tlsv1
  77 .Op Fl -no-verify-hostname
  78 .Op Fl -no-verify-peer
  79 .Op Fl o Ar file
  80 .Op Fl -referer= Ns Ar URL
  81 .Op Fl S Ar bytes
  82 .Op Fl T Ar seconds
  83 .Op Fl -user-agent= Ns Ar agent-string
  84 .Op Fl w Ar seconds
  85 .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
  86 .Sh DESCRIPTION
  87 The
  88 .Nm
  89 utility provides a command-line interface to the
  90 .Xr fetch 3
  91 library.
  92 Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
  93 command line.
  94 .Pp
  95 The following options are available:
  96 .Bl -tag -width Fl
  97 .It Fl 1 , -one-file
  98 Stop and return exit code 0 at the first successfully retrieved file.
  99 .It Fl 4 , -ipv4-only
 100 Forces
 101 .Nm
 102 to use IPv4 addresses only.
 103 .It Fl 6 , -ipv6-only
 104 Forces
 105 .Nm
 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.
 111 .It Fl a , -retry
 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
 117 ignored.
 118 The number of reads actually performed is reported at verbosity level
 119 two or higher (see the
 120 .Fl v
 121 flag).
 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.
 125 .It Fl c Ar dir
 126 The file to retrieve is in directory
 127 .Ar dir
 128 on the remote host.
 129 This option is deprecated and is provided for backward compatibility
 130 only.
 131 .It Fl -ca-cert= Ns Ar file
 132 [SSL]
 133 Path to certificate bundle containing trusted CA certificates.
 134 If not specified,
 135 .Pa /usr/local/etc/ssl/cert.pem
 136 is used.
 137 If this file does not exist,
 138 .Pa /etc/ssl/cert.pem
 139 is used instead.
 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.
 143 The
 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
 147 [SSL]
 148 The directory
 149 .Ar dir
 150 contains trusted CA hashes.
 151 .It Fl -cert= Ns Ar file
 152 [SSL]
 153 .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
 157 [SSL]
 158 Points to certificate revocation list
 159 .Ar file ,
 160 which has to be in PEM format and may contain peer certificates that have
 161 been revoked.
 162 .It Fl d , -direct
 163 Use a direct connection even if a proxy is configured.
 164 .It Fl F , -force-restart
 165 In combination with the
 166 .Fl r
 167 flag, forces a restart even if the local and remote files have
 168 different modification times.
 169 Implies
 170 .Fl R .
 171 .It Fl f Ar file
 172 The file to retrieve is named
 173 .Ar file
 174 on the remote host.
 175 This option is deprecated and is provided for backward compatibility
 176 only.
 177 .It Fl h Ar host
 178 The file to retrieve is located on the host
 179 .Ar host .
 180 This option is deprecated and is provided for backward compatibility
 181 only.
 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
 184 is newer than
 185 .Ar file
 186 on the local host.
 187 (HTTP only)
 188 .It Fl -key= Ns Ar file
 189 [SSL]
 190 .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.
 193 .It Fl l , -symlink
 194 If the target is a file-scheme URL, make a symbolic link to the target
 195 rather than trying to copy it.
 196 .It Fl M
 197 .It Fl m , -mirror
 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.
 200 Note that the
 201 .Fl m
 202 and
 203 .Fl r
 204 flags are mutually exclusive.
 205 .It Fl N Ar file , Fl -netrc= Ns Ar file
 206 Use
 207 .Ar file
 208 instead of
 209 .Pa ~/.netrc
 210 to look up login names and passwords for FTP sites.
 211 See
 212 .Xr ftp 1
 213 for a description of the file format.
 214 This feature is experimental.
 215 .It Fl n , -no-mtime
 216 Do not preserve the modification time of the transferred file.
 217 .It Fl -no-passive
 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.
 223 .It Fl -no-sslv3
 224 [SSL]
 225 Do not allow SSL version 3 when negotiating the connection.
 226 This option is deprecated and is provided for backward compatibility
 227 only.
 228 SSLv3 is disabled by default.
 229 Set
 230 .Ev SSL_ALLOW_SSL3
 231 to change this behavior.
 232 .It Fl -no-tlsv1
 233 [SSL]
 234 Do not allow TLS version 1 when negotiating the connection.
 235 .It Fl -no-verify-hostname
 236 [SSL]
 237 Do not verify that the hostname matches the subject of the
 238 certificate presented by the server.
 239 .It Fl -no-verify-peer
 240 [SSL]
 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
 244 .Ar file .
 245 By default, a ``pathname'' is extracted from the specified URI, and
 246 its basename is used as the name of the output file.
 247 A
 248 .Ar file
 249 argument of
 250 .Sq Li \&-
 251 indicates that results are to be directed to the standard output.
 252 If the
 253 .Ar file
 254 argument is a directory, fetched file(s) will be placed within the
 255 directory, with name(s) selected as in the default behaviour.
 256 .It Fl P
 257 .It Fl p , -passive
 258 Use passive FTP.
 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
 261 the default.
 262 To force active mode, use the
 263 .Fl -no-passive
 264 flag or set the
 265 .Ev FTP_PASSIVE_MODE
 266 environment variable to
 267 .Ql NO .
 268 .It Fl -referer= Ns Ar URL
 269 Specifies the referrer URL to use for HTTP requests.
 270 If
 271 .Ar URL
 272 is set to
 273 .Dq auto ,
 274 the document URL will be used as referrer URL.
 275 .It Fl q , -quiet
 276 Quiet mode.
 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.
 280 .It Fl r , -restart
 281 Restart a previously interrupted transfer.
 282 Note that the
 283 .Fl m
 284 and
 285 .Fl r
 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
 289 value.
 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
 296 Set timeout value to
 297 .Ar seconds .
 298 Overrides the environment variables
 299 .Ev FTP_TIMEOUT
 300 for FTP transfers or
 301 .Ev HTTP_TIMEOUT
 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.
 306 See
 307 .Xr ip 4
 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.
 313 .It Fl v , -verbose
 314 Increase verbosity level.
 315 .It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds
 316 When the
 317 .Fl a
 318 flag is specified, wait this many seconds between successive retries.
 319 .El
 320 .Pp
 321 If
 322 .Nm
 323 receives a
 324 .Dv SIGINFO
 325 signal (see the
 326 .Cm status
 327 argument for
 328 .Xr stty 1 ) ,
 329 the current transfer rate statistics will be written to the
 330 standard error output, in the same format as the standard completion
 331 message.
 332 .Sh ENVIRONMENT
 333 .Bl -tag -width HTTP_TIMEOUT
 334 .It Ev FTP_TIMEOUT
 335 Maximum time, in seconds, to wait before aborting an FTP connection.
 336 .It Ev HTTP_TIMEOUT
 337 Maximum time, in seconds, to wait before aborting an HTTP connection.
 338 .El
 339 .Pp
 340 See
 341 .Xr fetch 3
 342 for a description of additional environment variables, including
 343 .Ev FETCH_BIND_ADDRESS ,
 344 .Ev FTP_LOGIN ,
 345 .Ev FTP_PASSIVE_MODE ,
 346 .Ev FTP_PASSWORD ,
 347 .Ev FTP_PROXY ,
 348 .Ev ftp_proxy ,
 349 .Ev HTTP_ACCEPT ,
 350 .Ev HTTP_AUTH ,
 351 .Ev HTTP_PROXY ,
 352 .Ev http_proxy ,
 353 .Ev HTTP_PROXY_AUTH ,
 354 .Ev HTTP_REFERER ,
 355 .Ev HTTP_USER_AGENT ,
 356 .Ev NETRC ,
 357 .Ev NO_PROXY ,
 358 .Ev no_proxy ,
 359 .Ev SSL_CA_CERT_FILE ,
 360 .Ev SSL_CA_CERT_PATH ,
 361 .Ev SSL_CLIENT_CERT_FILE ,
 362 .Ev SSL_CLIENT_KEY_FILE ,
 363 .Ev SSL_CRL_FILE ,
 364 .Ev SSL_ALLOW_SSL3 ,
 365 .Ev SSL_NO_TLS1 ,
 366 .Ev SSL_NO_TLS1_1 ,
 367 .Ev SSL_NO_TLS1_2 ,
 368 .Ev SSL_NO_VERIFY_HOSTNAME
 369 and
 370 .Ev SSL_NO_VERIFY_PEER .
 371 .Sh EXIT STATUS
 372 The
 373 .Nm
 374 command returns zero on success, or one on failure.
 375 If multiple URLs are listed on the command line,
 376 .Nm
 377 will attempt to retrieve each one of them in turn, and will return
 378 zero only if they were all successfully retrieved.
 379 .Pp
 380 If the
 381 .Fl i
 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.
 385 .Sh EXAMPLES
 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
 392         https://www.fake.url
 393 fetch: https://www.freebsd.org/bad.html: Not Found
 394 .Ed
 395 .Pp
 396 Be verbose when retrieving the
 397 .Pa README.TXT
 398 file:
 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
 406 .Ed
 407 .Pp
 408 Quietly save the
 409 .Pa README.TXT
 410 file as
 411 .Pa myreadme.txt
 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
 415 .Ed
 416 .Pp
 417 Print the size of the requested file and identify the request with a custom user
 418 agent string:
 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"
 422 3513231
 423 .Ed
 424 .Pp
 425 Restart the transfer of the
 426 .Pa README.TXT
 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
 430 .Ed
 431 .Sh SEE ALSO
 432 .Xr fetch 3 ,
 433 .Xr phttpget 8
 434 .Sh HISTORY
 435 The
 436 .Nm
 437 command appeared in
 438 .Fx 2.1.5 .
 439 This implementation first appeared in
 440 .Fx 4.1 .
 441 .Sh AUTHORS
 442 .An -nosplit
 443 The original implementation of
 444 .Nm
 445 was done by
 446 .An Jean-Marc Zucconi Aq Mt jmz@FreeBSD.org .
 447 It was extensively re-worked for
 448 .Fx 2.2
 449 by
 450 .An Garrett Wollman Aq Mt wollman@FreeBSD.org ,
 451 and later completely rewritten to use the
 452 .Xr fetch 3
 453 library by
 454 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org
 455 and
 456 .An Michael Gmelin Aq Mt freebsd@grem.de .
 457 .Sh NOTES
 458 The
 459 .Fl b
 460 and
 461 .Fl t
 462 options are no longer supported and will generate warnings.
 463 They were workarounds for bugs in other OSes which this implementation
 464 does not trigger.
 465 .Pp
 466 One cannot both use the
 467 .Fl h ,
 468 .Fl c
 469 and
 470 .Fl f
 471 options and specify URLs on the command line.