usr.bin/fetch/fetch.1

   1 .\"-
   2 .\" Copyright (c) 2000-2013 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 July 30, 2013
  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 -allow-sslv2
  43 .Op Fl B Ar bytes
  44 .Op Fl -bind-address= Ns Ar host
  45 .Op Fl -ca-cert= Ns Ar file
  46 .Op Fl -ca-path= Ns Ar dir
  47 .Op Fl -cert= Ns Ar file
  48 .Op Fl -crl= Ns Ar file
  49 .Op Fl i Ar file
  50 .Op Fl -key= Ns Ar file
  51 .Op Fl N Ar file
  52 .Op Fl -no-passive
  53 .Op Fl -no-proxy= Ns Ar list
  54 .Op Fl -no-sslv3
  55 .Op Fl -no-tlsv1
  56 .Op Fl -no-verify-hostname
  57 .Op Fl -no-verify-peer
  58 .Op Fl o Ar file
  59 .Op Fl -referer= Ns Ar URL
  60 .Op Fl S Ar bytes
  61 .Op Fl T Ar seconds
  62 .Op Fl -user-agent= Ns Ar agent-string
  63 .Op Fl w Ar seconds
  64 .Ar URL ...
  65 .Nm
  66 .Op Fl 146AadFlMmnPpqRrsUv
  67 .Op Fl B Ar bytes
  68 .Op Fl -bind-address= Ns Ar host
  69 .Op Fl -ca-cert= Ns Ar file
  70 .Op Fl -ca-path= Ns Ar dir
  71 .Op Fl -cert= Ns Ar file
  72 .Op Fl -crl= Ns Ar file
  73 .Op Fl i Ar file
  74 .Op Fl -key= Ns Ar file
  75 .Op Fl N Ar file
  76 .Op Fl -no-passive
  77 .Op Fl -no-proxy= Ns Ar list
  78 .Op Fl -no-sslv3
  79 .Op Fl -no-tlsv1
  80 .Op Fl -no-verify-hostname
  81 .Op Fl -no-verify-peer
  82 .Op Fl o Ar file
  83 .Op Fl -referer= Ns Ar URL
  84 .Op Fl S Ar bytes
  85 .Op Fl T Ar seconds
  86 .Op Fl -user-agent= Ns Ar agent-string
  87 .Op Fl w Ar seconds
  88 .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
  89 .Sh DESCRIPTION
  90 The
  91 .Nm
  92 utility provides a command-line interface to the
  93 .Xr fetch 3
  94 library.
  95 Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
  96 command line.
  97 .Pp
  98 The following options are available:
  99 .Bl -tag -width Fl
 100 .It Fl 1 , -one-file
 101 Stop and return exit code 0 at the first successfully retrieved file.
 102 .It Fl 4 , -ipv4-only
 103 Forces
 104 .Nm
 105 to use IPv4 addresses only.
 106 .It Fl 6 , -ipv6-only
 107 Forces
 108 .Nm
 109 to use IPv6 addresses only.
 110 .It Fl A , -no-redirect
 111 Do not automatically follow ``temporary'' (302) redirects.
 112 Some broken Web sites will return a redirect instead of a not-found
 113 error when the requested object does not exist.
 114 .It Fl a , -retry
 115 Automatically retry the transfer upon soft failures.
 116 .It Fl -allow-sslv2
 117 [SSL]
 118 Allow SSL version 2 when negotiating the connection.
 119 .It Fl B Ar bytes , Fl -buffer-size= Ns Ar bytes
 120 Specify the read buffer size in bytes.
 121 The default is 4096 bytes.
 122 Attempts to set a buffer size lower than this will be silently
 123 ignored.
 124 The number of reads actually performed is reported at verbosity level
 125 two or higher (see the
 126 .Fl v
 127 flag).
 128 .It Fl -bind-address= Ns Ar host
 129 Specifies a hostname or IP address to which sockets used for outgoing
 130 connections will be bound.
 131 .It Fl c Ar dir
 132 The file to retrieve is in directory
 133 .Ar dir
 134 on the remote host.
 135 This option is deprecated and is provided for backward compatibility
 136 only.
 137 .It Fl -ca-cert= Ns Ar file
 138 [SSL]
 139 Path to certificate bundle containing trusted CA certificates.
 140 If not specified,
 141 .Pa /etc/ssl/cert.pem
 142 is used.
 143 The file may contain multiple CA certificates. The port
 144 .Pa security/ca_root_nss
 145 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 Don't allow SSL version 3 when negotiating the connection.
 226 .It Fl -no-tlsv1
 227 [SSL]
 228 Don't allow TLS version 1 when negotiating the connection.
 229 .It Fl -no-verify-hostname
 230 [SSL]
 231 Do not verify that the hostname matches the subject of the
 232 certificate presented by the server.
 233 .It Fl -no-verify-peer
 234 [SSL]
 235 Do not verify the peer certificate against trusted CAs.
 236 .It Fl o Ar file , Fl output= Ns Ar file
 237 Set the output file name to
 238 .Ar file .
 239 By default, a ``pathname'' is extracted from the specified URI, and
 240 its basename is used as the name of the output file.
 241 A
 242 .Ar file
 243 argument of
 244 .Sq Li \&-
 245 indicates that results are to be directed to the standard output.
 246 If the
 247 .Ar file
 248 argument is a directory, fetched file(s) will be placed within the
 249 directory, with name(s) selected as in the default behaviour.
 250 .It Fl P
 251 .It Fl p , -passive
 252 Use passive FTP.
 253 These flags have no effect, since passive FTP is the default, but are
 254 provided for compatibility with earlier versions where active FTP was
 255 the default.
 256 To force active mode, use the
 257 .Fl -no-passive
 258 flag or set the
 259 .Ev FTP_PASSIVE_MODE
 260 environment variable to
 261 .Ql NO .
 262 .It Fl -referer= Ns Ar URL
 263 Specifies the referrer URL to use for HTTP requests.
 264 If
 265 .Ar URL
 266 is set to
 267 .Dq auto ,
 268 the document URL will be used as referrer URL.
 269 .It Fl q , -quiet
 270 Quiet mode.
 271 .It Fl R , -keep-output
 272 The output files are precious, and should not be deleted under any
 273 circumstances, even if the transfer failed or was incomplete.
 274 .It Fl r , -restart
 275 Restart a previously interrupted transfer.
 276 Note that the
 277 .Fl m
 278 and
 279 .Fl r
 280 flags are mutually exclusive.
 281 .It Fl S Ar bytes , Fl -require-size= Ns Ar bytes
 282 Require the file size reported by the server to match the specified
 283 value.
 284 If it does not, a message is printed and the file is not fetched.
 285 If the server does not support reporting file sizes, this option is
 286 ignored and the file is fetched unconditionally.
 287 .It Fl s , -print-size
 288 Print the size in bytes of each requested file, without fetching it.
 289 .It Fl T Ar seconds , Fl -timeout= Ns Ar seconds
 290 Set timeout value to
 291 .Ar seconds .
 292 Overrides the environment variables
 293 .Ev FTP_TIMEOUT
 294 for FTP transfers or
 295 .Ev HTTP_TIMEOUT
 296 for HTTP transfers if set.
 297 .It Fl U , -passive-portrange-default
 298 When using passive FTP, allocate the port for the data connection from
 299 the low (default) port range.
 300 See
 301 .Xr ip 4
 302 for details on how to specify which port range this corresponds to.
 303 .It Fl -user-agent= Ns Ar agent-string
 304 Specifies the User-Agent string to use for HTTP requests.
 305 This can be useful when working with HTTP origin or proxy servers that
 306 differentiate between user agents.
 307 .It Fl v , -verbose
 308 Increase verbosity level.
 309 .It Fl w Ar seconds , Fl -retry-delay= Ns Ar seconds
 310 When the
 311 .Fl a
 312 flag is specified, wait this many seconds between successive retries.
 313 .El
 314 .Pp
 315 If
 316 .Nm
 317 receives a
 318 .Dv SIGINFO
 319 signal (see the
 320 .Cm status
 321 argument for
 322 .Xr stty 1 ) ,
 323 the current transfer rate statistics will be written to the
 324 standard error output, in the same format as the standard completion
 325 message.
 326 .Sh ENVIRONMENT
 327 .Bl -tag -width HTTP_TIMEOUT
 328 .It Ev FTP_TIMEOUT
 329 Maximum time, in seconds, to wait before aborting an FTP connection.
 330 .It Ev HTTP_TIMEOUT
 331 Maximum time, in seconds, to wait before aborting an HTTP connection.
 332 .El
 333 .Pp
 334 See
 335 .Xr fetch 3
 336 for a description of additional environment variables, including
 337 .Ev FETCH_BIND_ADDRESS ,
 338 .Ev FTP_LOGIN ,
 339 .Ev FTP_PASSIVE_MODE ,
 340 .Ev FTP_PASSWORD ,
 341 .Ev FTP_PROXY ,
 342 .Ev ftp_proxy ,
 343 .Ev HTTP_ACCEPT ,
 344 .Ev HTTP_AUTH ,
 345 .Ev HTTP_PROXY ,
 346 .Ev http_proxy ,
 347 .Ev HTTP_PROXY_AUTH ,
 348 .Ev HTTP_REFERER ,
 349 .Ev HTTP_USER_AGENT ,
 350 .Ev NETRC ,
 351 .Ev NO_PROXY ,
 352 .Ev no_proxy ,
 353 .Ev SSL_ALLOW_SSL2 ,
 354 .Ev SSL_CA_CERT_FILE ,
 355 .Ev SSL_CA_CERT_PATH ,
 356 .Ev SSL_CLIENT_CERT_FILE ,
 357 .Ev SSL_CLIENT_KEY_FILE ,
 358 .Ev SSL_CRL_FILE ,
 359 .Ev SSL_NO_SSL3 ,
 360 .Ev SSL_NO_TLS1 ,
 361 .Ev SSL_NO_VERIFY_HOSTNAME
 362 and
 363 .Ev SSL_NO_VERIFY_PEER .
 364 .Sh EXIT STATUS
 365 The
 366 .Nm
 367 command returns zero on success, or one on failure.
 368 If multiple URLs are listed on the command line,
 369 .Nm
 370 will attempt to retrieve each one of them in turn, and will return
 371 zero only if they were all successfully retrieved.
 372 .Pp
 373 If the
 374 .Fl i
 375 argument is used and the remote file is not newer than the
 376 specified file then the command will still return success,
 377 although no file is transferred.
 378 .Sh SEE ALSO
 379 .Xr fetch 3
 380 .Sh HISTORY
 381 The
 382 .Nm
 383 command appeared in
 384 .Fx 2.1.5 .
 385 This implementation first appeared in
 386 .Fx 4.1 .
 387 .Sh AUTHORS
 388 .An -nosplit
 389 The original implementation of
 390 .Nm
 391 was done by
 392 .An Jean-Marc Zucconi Aq jmz@FreeBSD.org .
 393 It was extensively re-worked for
 394 .Fx 2.2
 395 by
 396 .An Garrett Wollman Aq wollman@FreeBSD.org ,
 397 and later completely rewritten to use the
 398 .Xr fetch 3
 399 library by
 400 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
 401 and
 402 .An Michael Gmelin Aq freebsd@grem.de .
 403 .Sh NOTES
 404 The
 405 .Fl b
 406 and
 407 .Fl t
 408 options are no longer supported and will generate warnings.
 409 They were workarounds for bugs in other OSes which this implementation
 410 does not trigger.
 411 .Pp
 412 One cannot both use the
 413 .Fl h ,
 414 .Fl c
 415 and
 416 .Fl f
 417 options and specify URLs on the command line.