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 7, 2023
  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 Otherwise,
 135 OpenSSL's default CA cert and path settings apply.
 136 .It Fl -ca-path= Ns Ar dir
 137 [SSL]
 138 The directory
 139 .Ar dir
 140 contains trusted CA hashes.
 141 .It Fl -cert= Ns Ar file
 142 [SSL]
 143 .Ar file
 144 is a PEM encoded client certificate/key which will be used in
 145 client certificate authentication.
 146 .It Fl -crl= Ns Ar file
 147 [SSL]
 148 Points to certificate revocation list
 149 .Ar file ,
 150 which has to be in PEM format and may contain peer certificates that have
 151 been revoked.
 152 .It Fl d , -direct
 153 Use a direct connection even if a proxy is configured.
 154 .It Fl F , -force-restart
 155 In combination with the
 156 .Fl r
 157 flag, forces a restart even if the local and remote files have
 158 different modification times.
 159 Implies
 160 .Fl R .
 161 .It Fl f Ar file
 162 The file to retrieve is named
 163 .Ar file
 164 on the remote host.
 165 This option is deprecated and is provided for backward compatibility
 166 only.
 167 .It Fl h Ar host
 168 The file to retrieve is located on the host
 169 .Ar host .
 170 This option is deprecated and is provided for backward compatibility
 171 only.
 172 .It Fl i Ar file , Fl -if-modified-since= Ns Ar file
 173 If-Modified-Since mode: the remote file will only be retrieved if it
 174 is newer than
 175 .Ar file
 176 on the local host.
 177 (HTTP only)
 178 .It Fl -key= Ns Ar file
 179 [SSL]
 180 .Ar file
 181 is a PEM encoded client key that will be used in client certificate
 182 authentication in case key and client certificate are stored separately.
 183 .It Fl l , -symlink
 184 If the target is a file-scheme URL, make a symbolic link to the target
 185 rather than trying to copy it.
 186 .It Fl M
 187 .It Fl m , -mirror
 188 Mirror mode: if the file already exists locally and has the same size
 189 and modification time as the remote file, it will not be fetched.
 190 Note that the
 191 .Fl m
 192 and
 193 .Fl r
 194 flags are mutually exclusive.
 195 .It Fl N Ar file , Fl -netrc= Ns Ar file
 196 Use
 197 .Ar file
 198 instead of
 199 .Pa ~/.netrc
 200 to look up login names and passwords for FTP sites.
 201 See
 202 .Xr ftp 1
 203 for a description of the file format.
 204 This feature is experimental.
 205 .It Fl n , -no-mtime
 206 Do not preserve the modification time of the transferred file.
 207 .It Fl -no-passive
 208 Forces the FTP code to use active mode.
 209 .It Fl -no-proxy= Ns Ar list
 210 Either a single asterisk, which disables the use of proxies
 211 altogether, or a comma- or whitespace-separated list of hosts for
 212 which proxies should not be used.
 213 .It Fl -no-sslv3
 214 [SSL]
 215 Do not allow SSL version 3 when negotiating the connection.
 216 This option is deprecated and is provided for backward compatibility
 217 only.
 218 SSLv3 is disabled by default.
 219 Set
 220 .Ev SSL_ALLOW_SSL3
 221 to change this behavior.
 222 .It Fl -no-tlsv1
 223 [SSL]
 224 Do not allow TLS version 1 when negotiating the connection.
 225 .It Fl -no-verify-hostname
 226 [SSL]
 227 Do not verify that the hostname matches the subject of the
 228 certificate presented by the server.
 229 .It Fl -no-verify-peer
 230 [SSL]
 231 Do not verify the peer certificate against trusted CAs.
 232 .It Fl o Ar file , Fl -output= Ns Ar file
 233 Set the output file name to
 234 .Ar file .
 235 By default, a ``pathname'' is extracted from the specified URI, and
 236 its basename is used as the name of the output file.
 237 A
 238 .Ar file
 239 argument of
 240 .Sq Li \&-
 241 indicates that results are to be directed to the standard output.
 242 If the
 243 .Ar file
 244 argument is a directory, fetched file(s) will be placed within the
 245 directory, with name(s) selected as in the default behaviour.
 246 .It Fl P
 247 .It Fl p , -passive
 248 Use passive FTP.
 249 These flags have no effect, since passive FTP is the default, but are
 250 provided for compatibility with earlier versions where active FTP was
 251 the default.
 252 To force active mode, use the
 253 .Fl -no-passive
 254 flag or set the
 255 .Ev FTP_PASSIVE_MODE
 256 environment variable to
 257 .Ql NO .
 258 .It Fl -referer= Ns Ar URL
 259 Specifies the referrer URL to use for HTTP requests.
 260 If
 261 .Ar URL
 262 is set to
 263 .Dq auto ,
 264 the document URL will be used as referrer URL.
 265 .It Fl q , -quiet
 266 Quiet mode.
 267 .It Fl R , -keep-output
 268 The output files are precious, and should not be deleted under any
 269 circumstances, even if the transfer failed or was incomplete.
 270 .It Fl r , -restart
 271 Restart a previously interrupted transfer.
 272 Note that the
 273 .Fl m
 274 and
 275 .Fl r
 276 flags are mutually exclusive.
 277 .It Fl S Ar bytes , Fl -require-size= Ns Ar bytes
 278 Require the file size reported by the server to match the specified
 279 value.
 280 If it does not, a message is printed and the file is not fetched.
 281 If the server does not support reporting file sizes, this option is
 282 ignored and the file is fetched unconditionally.
 283 .It Fl s , -print-size
 284 Print the size in bytes of each requested file, without fetching it.
 285 .It Fl T Ar seconds , Fl -timeout= Ns Ar seconds
 286 Set timeout value to
 287 .Ar seconds .
 288 Overrides the environment variables
 289 .Ev FTP_TIMEOUT
 290 for FTP transfers or
 291 .Ev HTTP_TIMEOUT
 292 for HTTP transfers if set.
 293 .It Fl U , -passive-portrange-default
 294 When using passive FTP, allocate the port for the data connection from
 295 the low (default) port range.
 296 See
 297 .Xr ip 4
 298 for details on how to specify which port range this corresponds to.
 299 .It Fl -user-agent= Ns Ar agent-string
 300 Specifies the User-Agent string to use for HTTP requests.
 301 This can be useful when working with HTTP origin or proxy servers that
 302 differentiate between user agents.
 303 .It Fl v , -verbose
 304 Increase verbosity level.
 305 .It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds
 306 When the
 307 .Fl a
 308 flag is specified, wait this many seconds between successive retries.
 309 .El
 310 .Pp
 311 If
 312 .Nm
 313 receives a
 314 .Dv SIGINFO
 315 signal (see the
 316 .Cm status
 317 argument for
 318 .Xr stty 1 ) ,
 319 the current transfer rate statistics will be written to the
 320 standard error output, in the same format as the standard completion
 321 message.
 322 .Sh ENVIRONMENT
 323 .Bl -tag -width HTTP_TIMEOUT
 324 .It Ev FTP_TIMEOUT
 325 Maximum time, in seconds, to wait before aborting an FTP connection.
 326 .It Ev HTTP_TIMEOUT
 327 Maximum time, in seconds, to wait before aborting an HTTP connection.
 328 .El
 329 .Pp
 330 See
 331 .Xr fetch 3
 332 for 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_ALLOW_SSL3 ,
 355 .Ev SSL_NO_TLS1 ,
 356 .Ev SSL_NO_TLS1_1 ,
 357 .Ev SSL_NO_TLS1_2 ,
 358 .Ev SSL_NO_VERIFY_HOSTNAME
 359 and
 360 .Ev SSL_NO_VERIFY_PEER .
 361 .Sh EXIT STATUS
 362 The
 363 .Nm
 364 command returns zero on success, or one on failure.
 365 If multiple URLs are listed on the command line,
 366 .Nm
 367 will attempt to retrieve each one of them in turn, and will return
 368 zero only if they were all successfully retrieved.
 369 .Pp
 370 If the
 371 .Fl i
 372 argument is used and the remote file is not newer than the
 373 specified file then the command will still return success,
 374 although no file is transferred.
 375 .Sh EXAMPLES
 376 Silently try to fetch the URLs passed as parameters.
 377 The first one will fail.
 378 If the second URL succeeds the third one will not be tried:
 379 .Bd -literal -offset indent
 380 $ fetch -1 -q https://www.freebsd.org/bad.html \e
 381         ftp.freebsd.org/pub/FreeBSD/README.TXT \e
 382         https://www.fake.url
 383 fetch: https://www.freebsd.org/bad.html: Not Found
 384 .Ed
 385 .Pp
 386 Be verbose when retrieving the
 387 .Pa README.TXT
 388 file:
 389 .Bd -literal -offset indent
 390 $ fetch -v ftp.freebsd.org/pub/FreeBSD/README.TXT
 391 resolving server address: ftp.freebsd.org:80
 392 requesting http://ftp.freebsd.org/pub/FreeBSD/README.TXT
 393 local size / mtime: 4259 / 1431015519
 394 remote size / mtime: 4259 / 1431015519
 395 README.TXT                                            4259  B   44 MBps    00s
 396 .Ed
 397 .Pp
 398 Quietly save the
 399 .Pa README.TXT
 400 file as
 401 .Pa myreadme.txt
 402 and do not delete the output file under any circumstances:
 403 .Bd -literal -offset indent
 404 fetch -o myreadme.txt -q -R ftp.freebsd.org/pub/FreeBSD/README.TXT
 405 .Ed
 406 .Pp
 407 Print the size of the requested file and identify the request with a custom user
 408 agent string:
 409 .Bd -literal -offset indent
 410 $ fetch -s ftp.freebsd.org/pub/FreeBSD/README.TXT
 411 --user-agent="Mozilla/5.0 (X11; FreeBSD x86_64; rv:78.0) Gecko/20100101"
 412 3513231
 413 .Ed
 414 .Pp
 415 Restart the transfer of the
 416 .Pa README.TXT
 417 file and retry the transfer upon soft failures:
 418 .Bd -literal -offset indent
 419 $ fetch -a -r http://ftp.freebsd.org/pub/FreeBSD/README.TXT
 420 .Ed
 421 .Sh SEE ALSO
 422 .Xr fetch 3 ,
 423 .Xr phttpget 8
 424 .Sh HISTORY
 425 The
 426 .Nm
 427 command appeared in
 428 .Fx 2.1.5 .
 429 This implementation first appeared in
 430 .Fx 4.1 .
 431 .Sh AUTHORS
 432 .An -nosplit
 433 The original implementation of
 434 .Nm
 435 was done by
 436 .An Jean-Marc Zucconi Aq Mt jmz@FreeBSD.org .
 437 It was extensively re-worked for
 438 .Fx 2.2
 439 by
 440 .An Garrett Wollman Aq Mt wollman@FreeBSD.org ,
 441 and later completely rewritten to use the
 442 .Xr fetch 3
 443 library by
 444 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org
 445 and
 446 .An Michael Gmelin Aq Mt freebsd@grem.de .
 447 .Sh NOTES
 448 The
 449 .Fl b
 450 and
 451 .Fl t
 452 options are no longer supported and will generate warnings.
 453 They were workarounds for bugs in other OSes which this implementation
 454 does not trigger.
 455 .Pp
 456 One cannot both use the
 457 .Fl h ,
 458 .Fl c
 459 and
 460 .Fl f
 461 options and specify URLs on the command line.