Rename --html-extension to --adjust-extension.
[wget] / doc / wget.texi
1 \input texinfo   @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename wget.info
5 @include version.texi
6 @settitle GNU Wget @value{VERSION} Manual
7 @c Disable the monstrous rectangles beside overfull hbox-es.
8 @finalout
9 @c Use `odd' to print double-sided.
10 @setchapternewpage on
11 @c %**end of header
12
13 @iftex
14 @c Remove this if you don't use A4 paper.
15 @afourpaper
16 @end iftex
17
18 @c Title for man page.  The weird way texi2pod.pl is written requires
19 @c the preceding @set.
20 @set Wget Wget
21 @c man title Wget The non-interactive network downloader.
22
23 @dircategory Network Applications
24 @direntry
25 * Wget: (wget).         The non-interactive network downloader.
26 @end direntry
27
28 @copying
29 This file documents the GNU Wget utility for downloading network
30 data.
31
32 @c man begin COPYRIGHT
33 Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002,
34 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
35
36 @iftex
37 Permission is granted to make and distribute verbatim copies of
38 this manual provided the copyright notice and this permission notice
39 are preserved on all copies.
40 @end iftex
41
42 @ignore
43 Permission is granted to process this file through TeX and print the
44 results, provided the printed document carries a copying permission
45 notice identical to this one except for the removal of this paragraph
46 (this paragraph not being relevant to the printed manual).
47 @end ignore
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation License, Version 1.2 or
50 any later version published by the Free Software Foundation; with no
51 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
52 copy of the license is included in the section entitled ``GNU Free
53 Documentation License''.
54 @c man end
55 @end copying
56
57 @titlepage
58 @title GNU Wget @value{VERSION}
59 @subtitle The non-interactive download utility
60 @subtitle Updated for Wget @value{VERSION}, @value{UPDATED}
61 @author by Hrvoje Nik@v{s}i@'{c} and others
62
63 @ignore
64 @c man begin AUTHOR
65 Originally written by Hrvoje Niksic <hniksic@xemacs.org>.
66 Currently maintained by Micah Cowan <micah@cowan.name>.
67 @c man end
68 @c man begin SEEALSO
69 This is @strong{not} the complete manual for GNU Wget.
70 For more complete information, including more detailed explanations of
71 some of the options, and a number of commands available
72 for use with @file{.wgetrc} files and the @samp{-e} option, see the GNU
73 Info entry for @file{wget}.
74 @c man end
75 @end ignore
76
77 @page
78 @vskip 0pt plus 1filll
79 @insertcopying
80 @end titlepage
81
82 @contents
83
84 @ifnottex
85 @node Top, Overview, (dir), (dir)
86 @top Wget @value{VERSION}
87
88 @insertcopying
89 @end ifnottex
90
91 @menu
92 * Overview::            Features of Wget.
93 * Invoking::            Wget command-line arguments.
94 * Recursive Download::  Downloading interlinked pages.
95 * Following Links::     The available methods of chasing links.
96 * Time-Stamping::       Mirroring according to time-stamps.
97 * Startup File::        Wget's initialization file.
98 * Examples::            Examples of usage.
99 * Various::             The stuff that doesn't fit anywhere else.
100 * Appendices::          Some useful references.
101 * Copying this manual:: You may give out copies of Wget and of this manual.
102 * Concept Index::       Topics covered by this manual.
103 @end menu
104
105 @node Overview, Invoking, Top, Top
106 @chapter Overview
107 @cindex overview
108 @cindex features
109
110 @c man begin DESCRIPTION
111 GNU Wget is a free utility for non-interactive download of files from
112 the Web.  It supports @sc{http}, @sc{https}, and @sc{ftp} protocols, as
113 well as retrieval through @sc{http} proxies.
114
115 @c man end
116 This chapter is a partial overview of Wget's features.
117
118 @itemize @bullet
119 @item
120 @c man begin DESCRIPTION
121 Wget is non-interactive, meaning that it can work in the background,
122 while the user is not logged on.  This allows you to start a retrieval
123 and disconnect from the system, letting Wget finish the work.  By
124 contrast, most of the Web browsers require constant user's presence,
125 which can be a great hindrance when transferring a lot of data.
126 @c man end
127
128 @item
129 @ignore
130 @c man begin DESCRIPTION
131
132 @c man end
133 @end ignore
134 @c man begin DESCRIPTION
135 Wget can follow links in @sc{html}, @sc{xhtml}, and @sc{css} pages, to
136 create local versions of remote web sites, fully recreating the
137 directory structure of the original site.  This is sometimes referred to
138 as ``recursive downloading.''  While doing that, Wget respects the Robot
139 Exclusion Standard (@file{/robots.txt}).  Wget can be instructed to
140 convert the links in downloaded files to point at the local files, for
141 offline viewing.
142 @c man end
143
144 @item
145 File name wildcard matching and recursive mirroring of directories are
146 available when retrieving via @sc{ftp}.  Wget can read the time-stamp
147 information given by both @sc{http} and @sc{ftp} servers, and store it
148 locally.  Thus Wget can see if the remote file has changed since last
149 retrieval, and automatically retrieve the new version if it has.  This
150 makes Wget suitable for mirroring of @sc{ftp} sites, as well as home
151 pages.
152
153 @item
154 @ignore
155 @c man begin DESCRIPTION
156
157 @c man end
158 @end ignore
159 @c man begin DESCRIPTION
160 Wget has been designed for robustness over slow or unstable network
161 connections; if a download fails due to a network problem, it will
162 keep retrying until the whole file has been retrieved.  If the server
163 supports regetting, it will instruct the server to continue the
164 download from where it left off.
165 @c man end
166
167 @item
168 Wget supports proxy servers, which can lighten the network load, speed
169 up retrieval and provide access behind firewalls.  Wget uses the passive
170 @sc{ftp} downloading by default, active @sc{ftp} being an option.
171
172 @item
173 Wget supports IP version 6, the next generation of IP.  IPv6 is
174 autodetected at compile-time, and can be disabled at either build or
175 run time.  Binaries built with IPv6 support work well in both
176 IPv4-only and dual family environments.
177
178 @item
179 Built-in features offer mechanisms to tune which links you wish to follow
180 (@pxref{Following Links}).
181
182 @item
183 The progress of individual downloads is traced using a progress gauge.
184 Interactive downloads are tracked using a ``thermometer''-style gauge,
185 whereas non-interactive ones are traced with dots, each dot
186 representing a fixed amount of data received (1KB by default).  Either
187 gauge can be customized to your preferences.
188
189 @item
190 Most of the features are fully configurable, either through command line
191 options, or via the initialization file @file{.wgetrc} (@pxref{Startup
192 File}).  Wget allows you to define @dfn{global} startup files
193 (@file{/usr/local/etc/wgetrc} by default) for site settings.
194
195 @ignore
196 @c man begin FILES
197 @table @samp
198 @item /usr/local/etc/wgetrc
199 Default location of the @dfn{global} startup file.
200
201 @item .wgetrc
202 User startup file.
203 @end table
204 @c man end
205 @end ignore
206
207 @item
208 Finally, GNU Wget is free software.  This means that everyone may use
209 it, redistribute it and/or modify it under the terms of the GNU General
210 Public License, as published by the Free Software Foundation (see the
211 file @file{COPYING} that came with GNU Wget, for details).
212 @end itemize
213
214 @node Invoking, Recursive Download, Overview, Top
215 @chapter Invoking
216 @cindex invoking
217 @cindex command line
218 @cindex arguments
219 @cindex nohup
220
221 By default, Wget is very simple to invoke.  The basic syntax is:
222
223 @example
224 @c man begin SYNOPSIS
225 wget [@var{option}]@dots{} [@var{URL}]@dots{}
226 @c man end
227 @end example
228
229 Wget will simply download all the @sc{url}s specified on the command
230 line.  @var{URL} is a @dfn{Uniform Resource Locator}, as defined below.
231
232 However, you may wish to change some of the default parameters of
233 Wget.  You can do it two ways: permanently, adding the appropriate
234 command to @file{.wgetrc} (@pxref{Startup File}), or specifying it on
235 the command line.
236
237 @menu
238 * URL Format::
239 * Option Syntax::
240 * Basic Startup Options::
241 * Logging and Input File Options::
242 * Download Options::
243 * Directory Options::
244 * HTTP Options::
245 * HTTPS (SSL/TLS) Options::
246 * FTP Options::
247 * Recursive Retrieval Options::
248 * Recursive Accept/Reject Options::
249 @end menu
250
251 @node URL Format, Option Syntax, Invoking, Invoking
252 @section URL Format
253 @cindex URL
254 @cindex URL syntax
255
256 @dfn{URL} is an acronym for Uniform Resource Locator.  A uniform
257 resource locator is a compact string representation for a resource
258 available via the Internet.  Wget recognizes the @sc{url} syntax as per
259 @sc{rfc1738}.  This is the most widely used form (square brackets denote
260 optional parts):
261
262 @example
263 http://host[:port]/directory/file
264 ftp://host[:port]/directory/file
265 @end example
266
267 You can also encode your username and password within a @sc{url}:
268
269 @example
270 ftp://user:password@@host/path
271 http://user:password@@host/path
272 @end example
273
274 Either @var{user} or @var{password}, or both, may be left out.  If you
275 leave out either the @sc{http} username or password, no authentication
276 will be sent.  If you leave out the @sc{ftp} username, @samp{anonymous}
277 will be used.  If you leave out the @sc{ftp} password, your email
278 address will be supplied as a default password.@footnote{If you have a
279 @file{.netrc} file in your home directory, password will also be
280 searched for there.}
281
282 @strong{Important Note}: if you specify a password-containing @sc{url}
283 on the command line, the username and password will be plainly visible
284 to all users on the system, by way of @code{ps}.  On multi-user systems,
285 this is a big security risk.  To work around it, use @code{wget -i -}
286 and feed the @sc{url}s to Wget's standard input, each on a separate
287 line, terminated by @kbd{C-d}.
288
289 You can encode unsafe characters in a @sc{url} as @samp{%xy}, @code{xy}
290 being the hexadecimal representation of the character's @sc{ascii}
291 value.  Some common unsafe characters include @samp{%} (quoted as
292 @samp{%25}), @samp{:} (quoted as @samp{%3A}), and @samp{@@} (quoted as
293 @samp{%40}).  Refer to @sc{rfc1738} for a comprehensive list of unsafe
294 characters.
295
296 Wget also supports the @code{type} feature for @sc{ftp} @sc{url}s.  By
297 default, @sc{ftp} documents are retrieved in the binary mode (type
298 @samp{i}), which means that they are downloaded unchanged.  Another
299 useful mode is the @samp{a} (@dfn{ASCII}) mode, which converts the line
300 delimiters between the different operating systems, and is thus useful
301 for text files.  Here is an example:
302
303 @example
304 ftp://host/directory/file;type=a
305 @end example
306
307 Two alternative variants of @sc{url} specification are also supported,
308 because of historical (hysterical?) reasons and their widespreaded use.
309
310 @sc{ftp}-only syntax (supported by @code{NcFTP}):
311 @example
312 host:/dir/file
313 @end example
314
315 @sc{http}-only syntax (introduced by @code{Netscape}):
316 @example
317 host[:port]/dir/file
318 @end example
319
320 These two alternative forms are deprecated, and may cease being
321 supported in the future.
322
323 If you do not understand the difference between these notations, or do
324 not know which one to use, just use the plain ordinary format you use
325 with your favorite browser, like @code{Lynx} or @code{Netscape}.
326
327 @c man begin OPTIONS
328
329 @node Option Syntax, Basic Startup Options, URL Format, Invoking
330 @section Option Syntax
331 @cindex option syntax
332 @cindex syntax of options
333
334 Since Wget uses GNU getopt to process command-line arguments, every
335 option has a long form along with the short one.  Long options are
336 more convenient to remember, but take time to type.  You may freely
337 mix different option styles, or specify options after the command-line
338 arguments.  Thus you may write:
339
340 @example
341 wget -r --tries=10 http://fly.srk.fer.hr/ -o log
342 @end example
343
344 The space between the option accepting an argument and the argument may
345 be omitted.  Instead of @samp{-o log} you can write @samp{-olog}.
346
347 You may put several options that do not require arguments together,
348 like:
349
350 @example
351 wget -drc @var{URL}
352 @end example
353
354 This is a complete equivalent of:
355
356 @example
357 wget -d -r -c @var{URL}
358 @end example
359
360 Since the options can be specified after the arguments, you may
361 terminate them with @samp{--}.  So the following will try to download
362 @sc{url} @samp{-x}, reporting failure to @file{log}:
363
364 @example
365 wget -o log -- -x
366 @end example
367
368 The options that accept comma-separated lists all respect the convention
369 that specifying an empty list clears its value.  This can be useful to
370 clear the @file{.wgetrc} settings.  For instance, if your @file{.wgetrc}
371 sets @code{exclude_directories} to @file{/cgi-bin}, the following
372 example will first reset it, and then set it to exclude @file{/~nobody}
373 and @file{/~somebody}.  You can also clear the lists in @file{.wgetrc}
374 (@pxref{Wgetrc Syntax}).
375
376 @example
377 wget -X '' -X /~nobody,/~somebody
378 @end example
379
380 Most options that do not accept arguments are @dfn{boolean} options,
381 so named because their state can be captured with a yes-or-no
382 (``boolean'') variable.  For example, @samp{--follow-ftp} tells Wget
383 to follow FTP links from HTML files and, on the other hand,
384 @samp{--no-glob} tells it not to perform file globbing on FTP URLs.  A
385 boolean option is either @dfn{affirmative} or @dfn{negative}
386 (beginning with @samp{--no}).  All such options share several
387 properties.
388
389 Unless stated otherwise, it is assumed that the default behavior is
390 the opposite of what the option accomplishes.  For example, the
391 documented existence of @samp{--follow-ftp} assumes that the default
392 is to @emph{not} follow FTP links from HTML pages.
393
394 Affirmative options can be negated by prepending the @samp{--no-} to
395 the option name; negative options can be negated by omitting the
396 @samp{--no-} prefix.  This might seem superfluous---if the default for
397 an affirmative option is to not do something, then why provide a way
398 to explicitly turn it off?  But the startup file may in fact change
399 the default.  For instance, using @code{follow_ftp = on} in
400 @file{.wgetrc} makes Wget @emph{follow} FTP links by default, and
401 using @samp{--no-follow-ftp} is the only way to restore the factory
402 default from the command line.
403
404 @node Basic Startup Options, Logging and Input File Options, Option Syntax, Invoking
405 @section Basic Startup Options
406
407 @table @samp
408 @item -V
409 @itemx --version
410 Display the version of Wget.
411
412 @item -h
413 @itemx --help
414 Print a help message describing all of Wget's command-line options.
415
416 @item -b
417 @itemx --background
418 Go to background immediately after startup.  If no output file is
419 specified via the @samp{-o}, output is redirected to @file{wget-log}.
420
421 @cindex execute wgetrc command
422 @item -e @var{command}
423 @itemx --execute @var{command}
424 Execute @var{command} as if it were a part of @file{.wgetrc}
425 (@pxref{Startup File}).  A command thus invoked will be executed
426 @emph{after} the commands in @file{.wgetrc}, thus taking precedence over
427 them.  If you need to specify more than one wgetrc command, use multiple
428 instances of @samp{-e}.
429
430 @end table
431
432 @node Logging and Input File Options, Download Options, Basic Startup Options, Invoking
433 @section Logging and Input File Options
434
435 @table @samp
436 @cindex output file
437 @cindex log file
438 @item -o @var{logfile}
439 @itemx --output-file=@var{logfile}
440 Log all messages to @var{logfile}.  The messages are normally reported
441 to standard error.
442
443 @cindex append to log
444 @item -a @var{logfile}
445 @itemx --append-output=@var{logfile}
446 Append to @var{logfile}.  This is the same as @samp{-o}, only it appends
447 to @var{logfile} instead of overwriting the old log file.  If
448 @var{logfile} does not exist, a new file is created.
449
450 @cindex debug
451 @item -d
452 @itemx --debug
453 Turn on debug output, meaning various information important to the
454 developers of Wget if it does not work properly.  Your system
455 administrator may have chosen to compile Wget without debug support, in
456 which case @samp{-d} will not work.  Please note that compiling with
457 debug support is always safe---Wget compiled with the debug support will
458 @emph{not} print any debug info unless requested with @samp{-d}.
459 @xref{Reporting Bugs}, for more information on how to use @samp{-d} for
460 sending bug reports.
461
462 @cindex quiet
463 @item -q
464 @itemx --quiet
465 Turn off Wget's output.
466
467 @cindex verbose
468 @item -v
469 @itemx --verbose
470 Turn on verbose output, with all the available data.  The default output
471 is verbose.
472
473 @item -nv
474 @itemx --no-verbose
475 Turn off verbose without being completely quiet (use @samp{-q} for
476 that), which means that error messages and basic information still get
477 printed.
478
479 @cindex input-file
480 @item -i @var{file}
481 @itemx --input-file=@var{file}
482 Read @sc{url}s from a local or external @var{file}.  If @samp{-} is
483 specified as @var{file}, @sc{url}s are read from the standard input.  
484 (Use @samp{./-} to read from a file literally named @samp{-}.)
485
486 If this function is used, no @sc{url}s need be present on the command
487 line.  If there are @sc{url}s both on the command line and in an input
488 file, those on the command lines will be the first ones to be
489 retrieved.  If @samp{--force-html} is not specified, then @var{file}
490 should consist of a series of URLs, one per line.
491
492 However, if you specify @samp{--force-html}, the document will be
493 regarded as @samp{html}.  In that case you may have problems with
494 relative links, which you can solve either by adding @code{<base
495 href="@var{url}">} to the documents or by specifying
496 @samp{--base=@var{url}} on the command line.
497
498 If the @var{file} is an external one, the document will be automatically
499 treated as @samp{html} if the Content-Type matches @samp{text/html}.
500 Furthermore, the @var{file}'s location will be implicitly used as base
501 href if none was specified.
502
503 @cindex force html
504 @item -F
505 @itemx --force-html
506 When input is read from a file, force it to be treated as an @sc{html}
507 file.  This enables you to retrieve relative links from existing
508 @sc{html} files on your local disk, by adding @code{<base
509 href="@var{url}">} to @sc{html}, or using the @samp{--base} command-line
510 option.
511
512 @cindex base for relative links in input file
513 @item -B @var{URL}
514 @itemx --base=@var{URL}
515 Resolves relative links using @var{URL} as the point of reference,
516 when reading links from an HTML file specified via the
517 @samp{-i}/@samp{--input-file} option (together with
518 @samp{--force-html}, or when the input file was fetched remotely from
519 a server describing it as @sc{html}). This is equivalent to the
520 presence of a @code{BASE} tag in the @sc{html} input file, with
521 @var{URL} as the value for the @code{href} attribute.
522
523 For instance, if you specify @samp{http://foo/bar/a.html} for
524 @var{URL}, and Wget reads @samp{../baz/b.html} from the input file, it
525 would be resolved to @samp{http://foo/baz/b.html}.
526 @end table
527
528 @node Download Options, Directory Options, Logging and Input File Options, Invoking
529 @section Download Options
530
531 @table @samp
532 @cindex bind address
533 @cindex client IP address
534 @cindex IP address, client
535 @item --bind-address=@var{ADDRESS}
536 When making client TCP/IP connections, bind to @var{ADDRESS} on
537 the local machine.  @var{ADDRESS} may be specified as a hostname or IP
538 address.  This option can be useful if your machine is bound to multiple
539 IPs.
540
541 @cindex retries
542 @cindex tries
543 @cindex number of retries
544 @item -t @var{number}
545 @itemx --tries=@var{number}
546 Set number of retries to @var{number}.  Specify 0 or @samp{inf} for
547 infinite retrying.  The default is to retry 20 times, with the exception
548 of fatal errors like ``connection refused'' or ``not found'' (404),
549 which are not retried.
550
551 @item -O @var{file}
552 @itemx --output-document=@var{file}
553 The documents will not be written to the appropriate files, but all
554 will be concatenated together and written to @var{file}.  If @samp{-}
555 is used as @var{file}, documents will be printed to standard output,
556 disabling link conversion.  (Use @samp{./-} to print to a file
557 literally named @samp{-}.)
558
559 Use of @samp{-O} is @emph{not} intended to mean simply ``use the name
560 @var{file} instead of the one in the URL;'' rather, it is
561 analogous to shell redirection:
562 @samp{wget -O file http://foo} is intended to work like
563 @samp{wget -O - http://foo > file}; @file{file} will be truncated
564 immediately, and @emph{all} downloaded content will be written there.
565
566 For this reason, @samp{-N} (for timestamp-checking) is not supported
567 in combination with @samp{-O}: since @var{file} is always newly
568 created, it will always have a very new timestamp. A warning will be
569 issued if this combination is used.
570
571 Similarly, using @samp{-r} or @samp{-p} with @samp{-O} may not work as
572 you expect: Wget won't just download the first file to @var{file} and
573 then download the rest to their normal names: @emph{all} downloaded
574 content will be placed in @var{file}. This was disabled in version
575 1.11, but has been reinstated (with a warning) in 1.11.2, as there are
576 some cases where this behavior can actually have some use.
577
578 Note that a combination with @samp{-k} is only permitted when
579 downloading a single document, as in that case it will just convert
580 all relative URIs to external ones; @samp{-k} makes no sense for
581 multiple URIs when they're all being downloaded to a single file.
582
583 @cindex clobbering, file
584 @cindex downloading multiple times
585 @cindex no-clobber
586 @item -nc
587 @itemx --no-clobber
588 If a file is downloaded more than once in the same directory, Wget's
589 behavior depends on a few options, including @samp{-nc}.  In certain
590 cases, the local file will be @dfn{clobbered}, or overwritten, upon
591 repeated download.  In other cases it will be preserved.
592
593 When running Wget without @samp{-N}, @samp{-nc}, @samp{-r}, or
594 @samp{-p}, downloading the same file in the same directory will result
595 in the original copy of @var{file} being preserved and the second copy
596 being named @samp{@var{file}.1}.  If that file is downloaded yet
597 again, the third copy will be named @samp{@var{file}.2}, and so on.
598 (This is also the behavior with @samp{-nd}, even if @samp{-r} or
599 @samp{-p} are in effect.)  When @samp{-nc} is specified, this behavior
600 is suppressed, and Wget will refuse to download newer copies of
601 @samp{@var{file}}.  Therefore, ``@code{no-clobber}'' is actually a
602 misnomer in this mode---it's not clobbering that's prevented (as the
603 numeric suffixes were already preventing clobbering), but rather the
604 multiple version saving that's prevented.
605
606 When running Wget with @samp{-r} or @samp{-p}, but without @samp{-N},
607 @samp{-nd}, or @samp{-nc}, re-downloading a file will result in the
608 new copy simply overwriting the old.  Adding @samp{-nc} will prevent
609 this behavior, instead causing the original version to be preserved
610 and any newer copies on the server to be ignored.
611
612 When running Wget with @samp{-N}, with or without @samp{-r} or
613 @samp{-p}, the decision as to whether or not to download a newer copy
614 of a file depends on the local and remote timestamp and size of the
615 file (@pxref{Time-Stamping}).  @samp{-nc} may not be specified at the
616 same time as @samp{-N}.
617
618 Note that when @samp{-nc} is specified, files with the suffixes
619 @samp{.html} or @samp{.htm} will be loaded from the local disk and
620 parsed as if they had been retrieved from the Web.
621
622 @cindex continue retrieval
623 @cindex incomplete downloads
624 @cindex resume download
625 @item -c
626 @itemx --continue
627 Continue getting a partially-downloaded file.  This is useful when you
628 want to finish up a download started by a previous instance of Wget, or
629 by another program.  For instance:
630
631 @example
632 wget -c ftp://sunsite.doc.ic.ac.uk/ls-lR.Z
633 @end example
634
635 If there is a file named @file{ls-lR.Z} in the current directory, Wget
636 will assume that it is the first portion of the remote file, and will
637 ask the server to continue the retrieval from an offset equal to the
638 length of the local file.
639
640 Note that you don't need to specify this option if you just want the
641 current invocation of Wget to retry downloading a file should the
642 connection be lost midway through.  This is the default behavior.
643 @samp{-c} only affects resumption of downloads started @emph{prior} to
644 this invocation of Wget, and whose local files are still sitting around.
645
646 Without @samp{-c}, the previous example would just download the remote
647 file to @file{ls-lR.Z.1}, leaving the truncated @file{ls-lR.Z} file
648 alone.
649
650 Beginning with Wget 1.7, if you use @samp{-c} on a non-empty file, and
651 it turns out that the server does not support continued downloading,
652 Wget will refuse to start the download from scratch, which would
653 effectively ruin existing contents.  If you really want the download to
654 start from scratch, remove the file.
655
656 Also beginning with Wget 1.7, if you use @samp{-c} on a file which is of
657 equal size as the one on the server, Wget will refuse to download the
658 file and print an explanatory message.  The same happens when the file
659 is smaller on the server than locally (presumably because it was changed
660 on the server since your last download attempt)---because ``continuing''
661 is not meaningful, no download occurs.
662
663 On the other side of the coin, while using @samp{-c}, any file that's
664 bigger on the server than locally will be considered an incomplete
665 download and only @code{(length(remote) - length(local))} bytes will be
666 downloaded and tacked onto the end of the local file.  This behavior can
667 be desirable in certain cases---for instance, you can use @samp{wget -c}
668 to download just the new portion that's been appended to a data
669 collection or log file.
670
671 However, if the file is bigger on the server because it's been
672 @emph{changed}, as opposed to just @emph{appended} to, you'll end up
673 with a garbled file.  Wget has no way of verifying that the local file
674 is really a valid prefix of the remote file.  You need to be especially
675 careful of this when using @samp{-c} in conjunction with @samp{-r},
676 since every file will be considered as an "incomplete download" candidate.
677
678 Another instance where you'll get a garbled file if you try to use
679 @samp{-c} is if you have a lame @sc{http} proxy that inserts a
680 ``transfer interrupted'' string into the local file.  In the future a
681 ``rollback'' option may be added to deal with this case.
682
683 Note that @samp{-c} only works with @sc{ftp} servers and with @sc{http}
684 servers that support the @code{Range} header.
685
686 @cindex progress indicator
687 @cindex dot style
688 @item --progress=@var{type}
689 Select the type of the progress indicator you wish to use.  Legal
690 indicators are ``dot'' and ``bar''.
691
692 The ``bar'' indicator is used by default.  It draws an @sc{ascii} progress
693 bar graphics (a.k.a ``thermometer'' display) indicating the status of
694 retrieval.  If the output is not a TTY, the ``dot'' bar will be used by
695 default.
696
697 Use @samp{--progress=dot} to switch to the ``dot'' display.  It traces
698 the retrieval by printing dots on the screen, each dot representing a
699 fixed amount of downloaded data.
700
701 When using the dotted retrieval, you may also set the @dfn{style} by
702 specifying the type as @samp{dot:@var{style}}.  Different styles assign
703 different meaning to one dot.  With the @code{default} style each dot
704 represents 1K, there are ten dots in a cluster and 50 dots in a line.
705 The @code{binary} style has a more ``computer''-like orientation---8K
706 dots, 16-dots clusters and 48 dots per line (which makes for 384K
707 lines).  The @code{mega} style is suitable for downloading very large
708 files---each dot represents 64K retrieved, there are eight dots in a
709 cluster, and 48 dots on each line (so each line contains 3M).
710
711 Note that you can set the default style using the @code{progress}
712 command in @file{.wgetrc}.  That setting may be overridden from the
713 command line.  The exception is that, when the output is not a TTY, the
714 ``dot'' progress will be favored over ``bar''.  To force the bar output,
715 use @samp{--progress=bar:force}.
716
717 @item -N
718 @itemx --timestamping
719 Turn on time-stamping.  @xref{Time-Stamping}, for details.
720
721 @cindex server response, print
722 @item -S
723 @itemx --server-response
724 Print the headers sent by @sc{http} servers and responses sent by
725 @sc{ftp} servers.
726
727 @cindex Wget as spider
728 @cindex spider
729 @item --spider
730 When invoked with this option, Wget will behave as a Web @dfn{spider},
731 which means that it will not download the pages, just check that they
732 are there.  For example, you can use Wget to check your bookmarks:
733
734 @example
735 wget --spider --force-html -i bookmarks.html
736 @end example
737
738 This feature needs much more work for Wget to get close to the
739 functionality of real web spiders.
740
741 @cindex timeout
742 @item -T seconds
743 @itemx --timeout=@var{seconds}
744 Set the network timeout to @var{seconds} seconds.  This is equivalent
745 to specifying @samp{--dns-timeout}, @samp{--connect-timeout}, and
746 @samp{--read-timeout}, all at the same time.
747
748 When interacting with the network, Wget can check for timeout and
749 abort the operation if it takes too long.  This prevents anomalies
750 like hanging reads and infinite connects.  The only timeout enabled by
751 default is a 900-second read timeout.  Setting a timeout to 0 disables
752 it altogether.  Unless you know what you are doing, it is best not to
753 change the default timeout settings.
754
755 All timeout-related options accept decimal values, as well as
756 subsecond values.  For example, @samp{0.1} seconds is a legal (though
757 unwise) choice of timeout.  Subsecond timeouts are useful for checking
758 server response times or for testing network latency.
759
760 @cindex DNS timeout
761 @cindex timeout, DNS
762 @item --dns-timeout=@var{seconds}
763 Set the DNS lookup timeout to @var{seconds} seconds.  DNS lookups that
764 don't complete within the specified time will fail.  By default, there
765 is no timeout on DNS lookups, other than that implemented by system
766 libraries.
767
768 @cindex connect timeout
769 @cindex timeout, connect
770 @item --connect-timeout=@var{seconds}
771 Set the connect timeout to @var{seconds} seconds.  TCP connections that
772 take longer to establish will be aborted.  By default, there is no
773 connect timeout, other than that implemented by system libraries.
774
775 @cindex read timeout
776 @cindex timeout, read
777 @item --read-timeout=@var{seconds}
778 Set the read (and write) timeout to @var{seconds} seconds.  The
779 ``time'' of this timeout refers to @dfn{idle time}: if, at any point in
780 the download, no data is received for more than the specified number
781 of seconds, reading fails and the download is restarted.  This option
782 does not directly affect the duration of the entire download.
783
784 Of course, the remote server may choose to terminate the connection
785 sooner than this option requires.  The default read timeout is 900
786 seconds.
787
788 @cindex bandwidth, limit
789 @cindex rate, limit
790 @cindex limit bandwidth
791 @item --limit-rate=@var{amount}
792 Limit the download speed to @var{amount} bytes per second.  Amount may
793 be expressed in bytes, kilobytes with the @samp{k} suffix, or megabytes
794 with the @samp{m} suffix.  For example, @samp{--limit-rate=20k} will
795 limit the retrieval rate to 20KB/s.  This is useful when, for whatever
796 reason, you don't want Wget to consume the entire available bandwidth.
797
798 This option allows the use of decimal numbers, usually in conjunction
799 with power suffixes; for example, @samp{--limit-rate=2.5k} is a legal
800 value.
801
802 Note that Wget implements the limiting by sleeping the appropriate
803 amount of time after a network read that took less time than specified
804 by the rate.  Eventually this strategy causes the TCP transfer to slow
805 down to approximately the specified rate.  However, it may take some
806 time for this balance to be achieved, so don't be surprised if limiting
807 the rate doesn't work well with very small files.
808
809 @cindex pause
810 @cindex wait
811 @item -w @var{seconds}
812 @itemx --wait=@var{seconds}
813 Wait the specified number of seconds between the retrievals.  Use of
814 this option is recommended, as it lightens the server load by making the
815 requests less frequent.  Instead of in seconds, the time can be
816 specified in minutes using the @code{m} suffix, in hours using @code{h}
817 suffix, or in days using @code{d} suffix.
818
819 Specifying a large value for this option is useful if the network or the
820 destination host is down, so that Wget can wait long enough to
821 reasonably expect the network error to be fixed before the retry.  The
822 waiting interval specified by this function is influenced by
823 @code{--random-wait}, which see.
824
825 @cindex retries, waiting between
826 @cindex waiting between retries
827 @item --waitretry=@var{seconds}
828 If you don't want Wget to wait between @emph{every} retrieval, but only
829 between retries of failed downloads, you can use this option.  Wget will
830 use @dfn{linear backoff}, waiting 1 second after the first failure on a
831 given file, then waiting 2 seconds after the second failure on that
832 file, up to the maximum number of @var{seconds} you specify.  Therefore,
833 a value of 10 will actually make Wget wait up to (1 + 2 + ... + 10) = 55
834 seconds per file. 
835
836 By default, Wget will assume a value of 10 seconds.
837
838 @cindex wait, random
839 @cindex random wait
840 @item --random-wait
841 Some web sites may perform log analysis to identify retrieval programs
842 such as Wget by looking for statistically significant similarities in
843 the time between requests. This option causes the time between requests
844 to vary between 0.5 and 1.5 * @var{wait} seconds, where @var{wait} was
845 specified using the @samp{--wait} option, in order to mask Wget's
846 presence from such analysis.
847
848 A 2001 article in a publication devoted to development on a popular
849 consumer platform provided code to perform this analysis on the fly.
850 Its author suggested blocking at the class C address level to ensure
851 automated retrieval programs were blocked despite changing DHCP-supplied
852 addresses.
853
854 The @samp{--random-wait} option was inspired by this ill-advised
855 recommendation to block many unrelated users from a web site due to the
856 actions of one.
857
858 @cindex proxy
859 @itemx --no-proxy
860 Don't use proxies, even if the appropriate @code{*_proxy} environment
861 variable is defined.
862
863 @c man end
864 For more information about the use of proxies with Wget, @xref{Proxies}.
865 @c man begin OPTIONS
866
867 @cindex quota
868 @item -Q @var{quota}
869 @itemx --quota=@var{quota}
870 Specify download quota for automatic retrievals.  The value can be
871 specified in bytes (default), kilobytes (with @samp{k} suffix), or
872 megabytes (with @samp{m} suffix).
873
874 Note that quota will never affect downloading a single file.  So if you
875 specify @samp{wget -Q10k ftp://wuarchive.wustl.edu/ls-lR.gz}, all of the
876 @file{ls-lR.gz} will be downloaded.  The same goes even when several
877 @sc{url}s are specified on the command-line.  However, quota is
878 respected when retrieving either recursively, or from an input file.
879 Thus you may safely type @samp{wget -Q2m -i sites}---download will be
880 aborted when the quota is exceeded.
881
882 Setting quota to 0 or to @samp{inf} unlimits the download quota.
883
884 @cindex DNS cache
885 @cindex caching of DNS lookups
886 @item --no-dns-cache
887 Turn off caching of DNS lookups.  Normally, Wget remembers the IP
888 addresses it looked up from DNS so it doesn't have to repeatedly
889 contact the DNS server for the same (typically small) set of hosts it
890 retrieves from.  This cache exists in memory only; a new Wget run will
891 contact DNS again.
892
893 However, it has been reported that in some situations it is not
894 desirable to cache host names, even for the duration of a
895 short-running application like Wget.  With this option Wget issues a
896 new DNS lookup (more precisely, a new call to @code{gethostbyname} or
897 @code{getaddrinfo}) each time it makes a new connection.  Please note
898 that this option will @emph{not} affect caching that might be
899 performed by the resolving library or by an external caching layer,
900 such as NSCD.
901
902 If you don't understand exactly what this option does, you probably
903 won't need it.
904
905 @cindex file names, restrict
906 @cindex Windows file names
907 @item --restrict-file-names=@var{modes}
908 Change which characters found in remote URLs must be escaped during
909 generation of local filenames.  Characters that are @dfn{restricted}
910 by this option are escaped, i.e. replaced with @samp{%HH}, where
911 @samp{HH} is the hexadecimal number that corresponds to the restricted
912 character. This option may also be used to force all alphabetical
913 cases to be either lower- or uppercase.
914
915 By default, Wget escapes the characters that are not valid or safe as
916 part of file names on your operating system, as well as control
917 characters that are typically unprintable.  This option is useful for
918 changing these defaults, perhaps because you are downloading to a
919 non-native partition, or because you want to disable escaping of the
920 control characters, or you want to further restrict characters to only
921 those in the @sc{ascii} range of values.
922
923 The @var{modes} are a comma-separated set of text values. The
924 acceptable values are @samp{unix}, @samp{windows}, @samp{nocontrol},
925 @samp{ascii}, @samp{lowercase}, and @samp{uppercase}. The values
926 @samp{unix} and @samp{windows} are mutually exclusive (one will
927 override the other), as are @samp{lowercase} and
928 @samp{uppercase}. Those last are special cases, as they do not change
929 the set of characters that would be escaped, but rather force local
930 file paths to be converted either to lower- or uppercase.
931
932 When ``unix'' is specified, Wget escapes the character @samp{/} and
933 the control characters in the ranges 0--31 and 128--159.  This is the
934 default on Unix-like operating systems.
935
936 When ``windows'' is given, Wget escapes the characters @samp{\},
937 @samp{|}, @samp{/}, @samp{:}, @samp{?}, @samp{"}, @samp{*}, @samp{<},
938 @samp{>}, and the control characters in the ranges 0--31 and 128--159.
939 In addition to this, Wget in Windows mode uses @samp{+} instead of
940 @samp{:} to separate host and port in local file names, and uses
941 @samp{@@} instead of @samp{?} to separate the query portion of the file
942 name from the rest.  Therefore, a URL that would be saved as
943 @samp{www.xemacs.org:4300/search.pl?input=blah} in Unix mode would be
944 saved as @samp{www.xemacs.org+4300/search.pl@@input=blah} in Windows
945 mode.  This mode is the default on Windows.
946
947 If you specify @samp{nocontrol}, then the escaping of the control
948 characters is also switched off. This option may make sense
949 when you are downloading URLs whose names contain UTF-8 characters, on
950 a system which can save and display filenames in UTF-8 (some possible
951 byte values used in UTF-8 byte sequences fall in the range of values
952 designated by Wget as ``controls'').
953
954 The @samp{ascii} mode is used to specify that any bytes whose values
955 are outside the range of @sc{ascii} characters (that is, greater than
956 127) shall be escaped. This can be useful when saving filenames
957 whose encoding does not match the one used locally.
958
959 @cindex IPv6
960 @itemx -4
961 @itemx --inet4-only
962 @itemx -6
963 @itemx --inet6-only
964 Force connecting to IPv4 or IPv6 addresses.  With @samp{--inet4-only}
965 or @samp{-4}, Wget will only connect to IPv4 hosts, ignoring AAAA
966 records in DNS, and refusing to connect to IPv6 addresses specified in
967 URLs.  Conversely, with @samp{--inet6-only} or @samp{-6}, Wget will
968 only connect to IPv6 hosts and ignore A records and IPv4 addresses.
969
970 Neither options should be needed normally.  By default, an IPv6-aware
971 Wget will use the address family specified by the host's DNS record.
972 If the DNS responds with both IPv4 and IPv6 addresses, Wget will try
973 them in sequence until it finds one it can connect to.  (Also see
974 @code{--prefer-family} option described below.)
975
976 These options can be used to deliberately force the use of IPv4 or
977 IPv6 address families on dual family systems, usually to aid debugging
978 or to deal with broken network configuration.  Only one of
979 @samp{--inet6-only} and @samp{--inet4-only} may be specified at the
980 same time.  Neither option is available in Wget compiled without IPv6
981 support.
982
983 @item --prefer-family=none/IPv4/IPv6
984 When given a choice of several addresses, connect to the addresses
985 with specified address family first.  The address order returned by
986 DNS is used without change by default.
987
988 This avoids spurious errors and connect attempts when accessing hosts
989 that resolve to both IPv6 and IPv4 addresses from IPv4 networks.  For
990 example, @samp{www.kame.net} resolves to
991 @samp{2001:200:0:8002:203:47ff:fea5:3085} and to
992 @samp{203.178.141.194}.  When the preferred family is @code{IPv4}, the
993 IPv4 address is used first; when the preferred family is @code{IPv6},
994 the IPv6 address is used first; if the specified value is @code{none},
995 the address order returned by DNS is used without change.
996
997 Unlike @samp{-4} and @samp{-6}, this option doesn't inhibit access to
998 any address family, it only changes the @emph{order} in which the
999 addresses are accessed.  Also note that the reordering performed by
1000 this option is @dfn{stable}---it doesn't affect order of addresses of
1001 the same family.  That is, the relative order of all IPv4 addresses
1002 and of all IPv6 addresses remains intact in all cases.
1003
1004 @item --retry-connrefused
1005 Consider ``connection refused'' a transient error and try again.
1006 Normally Wget gives up on a URL when it is unable to connect to the
1007 site because failure to connect is taken as a sign that the server is
1008 not running at all and that retries would not help.  This option is
1009 for mirroring unreliable sites whose servers tend to disappear for
1010 short periods of time.
1011
1012 @cindex user
1013 @cindex password
1014 @cindex authentication
1015 @item --user=@var{user}
1016 @itemx --password=@var{password}
1017 Specify the username @var{user} and password @var{password} for both
1018 @sc{ftp} and @sc{http} file retrieval.  These parameters can be overridden
1019 using the @samp{--ftp-user} and @samp{--ftp-password} options for 
1020 @sc{ftp} connections and the @samp{--http-user} and @samp{--http-password} 
1021 options for @sc{http} connections.
1022
1023 @item --ask-password
1024 Prompt for a password for each connection established. Cannot be specified
1025 when @samp{--password} is being used, because they are mutually exclusive.
1026
1027 @cindex iri support
1028 @cindex idn support
1029 @item --no-iri
1030
1031 Turn off internationalized URI (IRI) support. Use @samp{--iri} to
1032 turn it on. IRI support is activated by default.
1033
1034 You can set the default state of IRI support using the @code{iri}
1035 command in @file{.wgetrc}. That setting may be overridden from the
1036 command line.
1037
1038 @cindex local encoding
1039 @item --local-encoding=@var{encoding}
1040
1041 Force Wget to use @var{encoding} as the default system encoding. That affects
1042 how Wget converts URLs specified as arguments from locale to @sc{utf-8} for
1043 IRI support.
1044
1045 Wget use the function @code{nl_langinfo()} and then the @code{CHARSET}
1046 environment variable to get the locale. If it fails, @sc{ascii} is used.
1047
1048 You can set the default local encoding using the @code{local_encoding}
1049 command in @file{.wgetrc}. That setting may be overridden from the
1050 command line.
1051
1052 @cindex remote encoding
1053 @item --remote-encoding=@var{encoding}
1054
1055 Force Wget to use @var{encoding} as the default remote server encoding.
1056 That affects how Wget converts URIs found in files from remote encoding
1057 to @sc{utf-8} during a recursive fetch. This options is only useful for
1058 IRI support, for the interpretation of non-@sc{ascii} characters.
1059
1060 For HTTP, remote encoding can be found in HTTP @code{Content-Type}
1061 header and in HTML @code{Content-Type http-equiv} meta tag.
1062
1063 You can set the default encoding using the @code{remoteencoding}
1064 command in @file{.wgetrc}. That setting may be overridden from the
1065 command line.
1066 @end table
1067
1068 @node Directory Options, HTTP Options, Download Options, Invoking
1069 @section Directory Options
1070
1071 @table @samp       
1072 @item -nd
1073 @itemx --no-directories
1074 Do not create a hierarchy of directories when retrieving recursively.
1075 With this option turned on, all files will get saved to the current
1076 directory, without clobbering (if a name shows up more than once, the
1077 filenames will get extensions @samp{.n}).
1078
1079 @item -x
1080 @itemx --force-directories
1081 The opposite of @samp{-nd}---create a hierarchy of directories, even if
1082 one would not have been created otherwise.  E.g. @samp{wget -x
1083 http://fly.srk.fer.hr/robots.txt} will save the downloaded file to
1084 @file{fly.srk.fer.hr/robots.txt}.
1085
1086 @item -nH
1087 @itemx --no-host-directories
1088 Disable generation of host-prefixed directories.  By default, invoking
1089 Wget with @samp{-r http://fly.srk.fer.hr/} will create a structure of
1090 directories beginning with @file{fly.srk.fer.hr/}.  This option disables
1091 such behavior.
1092
1093 @item --protocol-directories
1094 Use the protocol name as a directory component of local file names.  For
1095 example, with this option, @samp{wget -r http://@var{host}} will save to
1096 @samp{http/@var{host}/...} rather than just to @samp{@var{host}/...}.
1097
1098 @cindex cut directories
1099 @item --cut-dirs=@var{number}
1100 Ignore @var{number} directory components.  This is useful for getting a
1101 fine-grained control over the directory where recursive retrieval will
1102 be saved.
1103
1104 Take, for example, the directory at
1105 @samp{ftp://ftp.xemacs.org/pub/xemacs/}.  If you retrieve it with
1106 @samp{-r}, it will be saved locally under
1107 @file{ftp.xemacs.org/pub/xemacs/}.  While the @samp{-nH} option can
1108 remove the @file{ftp.xemacs.org/} part, you are still stuck with
1109 @file{pub/xemacs}.  This is where @samp{--cut-dirs} comes in handy; it
1110 makes Wget not ``see'' @var{number} remote directory components.  Here
1111 are several examples of how @samp{--cut-dirs} option works.
1112
1113 @example
1114 @group
1115 No options        -> ftp.xemacs.org/pub/xemacs/
1116 -nH               -> pub/xemacs/
1117 -nH --cut-dirs=1  -> xemacs/
1118 -nH --cut-dirs=2  -> .
1119
1120 --cut-dirs=1      -> ftp.xemacs.org/xemacs/
1121 ...
1122 @end group
1123 @end example
1124
1125 If you just want to get rid of the directory structure, this option is
1126 similar to a combination of @samp{-nd} and @samp{-P}.  However, unlike
1127 @samp{-nd}, @samp{--cut-dirs} does not lose with subdirectories---for
1128 instance, with @samp{-nH --cut-dirs=1}, a @file{beta/} subdirectory will
1129 be placed to @file{xemacs/beta}, as one would expect.
1130
1131 @cindex directory prefix
1132 @item -P @var{prefix}
1133 @itemx --directory-prefix=@var{prefix}
1134 Set directory prefix to @var{prefix}.  The @dfn{directory prefix} is the
1135 directory where all other files and subdirectories will be saved to,
1136 i.e. the top of the retrieval tree.  The default is @samp{.} (the
1137 current directory).
1138 @end table
1139
1140 @node HTTP Options, HTTPS (SSL/TLS) Options, Directory Options, Invoking
1141 @section HTTP Options
1142
1143 @table @samp
1144 @cindex default page name
1145 @cindex index.html
1146 @item --default-page=@var{name}
1147 Use @var{name} as the default file name when it isn't known (i.e., for
1148 URLs that end in a slash), instead of @file{index.html}.
1149
1150 @cindex .html extension
1151 @cindex .css extension
1152 @item -E
1153 @itemx --adjust-extension
1154 If a file of type @samp{application/xhtml+xml} or @samp{text/html} is 
1155 downloaded and the URL does not end with the regexp 
1156 @samp{\.[Hh][Tt][Mm][Ll]?}, this option will cause the suffix @samp{.html} 
1157 to be appended to the local filename.  This is useful, for instance, when 
1158 you're mirroring a remote site that uses @samp{.asp} pages, but you want 
1159 the mirrored pages to be viewable on your stock Apache server.  Another 
1160 good use for this is when you're downloading CGI-generated materials.  A URL 
1161 like @samp{http://site.com/article.cgi?25} will be saved as
1162 @file{article.cgi?25.html}.
1163
1164 Note that filenames changed in this way will be re-downloaded every time
1165 you re-mirror a site, because Wget can't tell that the local
1166 @file{@var{X}.html} file corresponds to remote URL @samp{@var{X}} (since
1167 it doesn't yet know that the URL produces output of type
1168 @samp{text/html} or @samp{application/xhtml+xml}.  To prevent this 
1169 re-downloading, you must use @samp{-k} and @samp{-K} so that the original 
1170 version of the file will be saved as @file{@var{X}.orig} (@pxref{Recursive 
1171 Retrieval Options}).
1172
1173 As of version 1.12, Wget will also ensure that any downloaded files of
1174 type @samp{text/css} end in the suffix @samp{.css}, and the option was
1175 renamed from @samp{--html-extension}, to better reflect its new
1176 behavior. The old option name is still acceptable, but should now be
1177 considered deprecated.
1178
1179 At some point in the future, this option may well be expanded to
1180 include suffixes for other types of content, including content types
1181 that are not parsed by Wget.
1182
1183 @cindex http user
1184 @cindex http password
1185 @cindex authentication
1186 @item --http-user=@var{user}
1187 @itemx --http-password=@var{password}
1188 Specify the username @var{user} and password @var{password} on an
1189 @sc{http} server.  According to the type of the challenge, Wget will
1190 encode them using either the @code{basic} (insecure),
1191 the @code{digest}, or the Windows @code{NTLM} authentication scheme.
1192
1193 Another way to specify username and password is in the @sc{url} itself
1194 (@pxref{URL Format}).  Either method reveals your password to anyone who
1195 bothers to run @code{ps}.  To prevent the passwords from being seen,
1196 store them in @file{.wgetrc} or @file{.netrc}, and make sure to protect
1197 those files from other users with @code{chmod}.  If the passwords are
1198 really important, do not leave them lying in those files either---edit
1199 the files and delete them after Wget has started the download.
1200
1201 @iftex
1202 For more information about security issues with Wget, @xref{Security
1203 Considerations}.
1204 @end iftex
1205
1206 @cindex Keep-Alive, turning off
1207 @cindex Persistent Connections, disabling
1208 @item --no-http-keep-alive
1209 Turn off the ``keep-alive'' feature for HTTP downloads.  Normally, Wget
1210 asks the server to keep the connection open so that, when you download
1211 more than one document from the same server, they get transferred over
1212 the same TCP connection.  This saves time and at the same time reduces
1213 the load on the server.
1214
1215 This option is useful when, for some reason, persistent (keep-alive)
1216 connections don't work for you, for example due to a server bug or due
1217 to the inability of server-side scripts to cope with the connections.
1218
1219 @cindex proxy
1220 @cindex cache
1221 @item --no-cache
1222 Disable server-side cache.  In this case, Wget will send the remote
1223 server an appropriate directive (@samp{Pragma: no-cache}) to get the
1224 file from the remote service, rather than returning the cached version.
1225 This is especially useful for retrieving and flushing out-of-date
1226 documents on proxy servers.
1227
1228 Caching is allowed by default.
1229
1230 @cindex cookies
1231 @item --no-cookies
1232 Disable the use of cookies.  Cookies are a mechanism for maintaining
1233 server-side state.  The server sends the client a cookie using the
1234 @code{Set-Cookie} header, and the client responds with the same cookie
1235 upon further requests.  Since cookies allow the server owners to keep
1236 track of visitors and for sites to exchange this information, some
1237 consider them a breach of privacy.  The default is to use cookies;
1238 however, @emph{storing} cookies is not on by default.
1239
1240 @cindex loading cookies
1241 @cindex cookies, loading
1242 @item --load-cookies @var{file}
1243 Load cookies from @var{file} before the first HTTP retrieval.
1244 @var{file} is a textual file in the format originally used by Netscape's
1245 @file{cookies.txt} file.
1246
1247 You will typically use this option when mirroring sites that require
1248 that you be logged in to access some or all of their content.  The login
1249 process typically works by the web server issuing an @sc{http} cookie
1250 upon receiving and verifying your credentials.  The cookie is then
1251 resent by the browser when accessing that part of the site, and so
1252 proves your identity.
1253
1254 Mirroring such a site requires Wget to send the same cookies your
1255 browser sends when communicating with the site.  This is achieved by
1256 @samp{--load-cookies}---simply point Wget to the location of the
1257 @file{cookies.txt} file, and it will send the same cookies your browser
1258 would send in the same situation.  Different browsers keep textual
1259 cookie files in different locations:
1260
1261 @table @asis
1262 @item Netscape 4.x.
1263 The cookies are in @file{~/.netscape/cookies.txt}.
1264
1265 @item Mozilla and Netscape 6.x.
1266 Mozilla's cookie file is also named @file{cookies.txt}, located
1267 somewhere under @file{~/.mozilla}, in the directory of your profile.
1268 The full path usually ends up looking somewhat like
1269 @file{~/.mozilla/default/@var{some-weird-string}/cookies.txt}.
1270
1271 @item Internet Explorer.
1272 You can produce a cookie file Wget can use by using the File menu,
1273 Import and Export, Export Cookies.  This has been tested with Internet
1274 Explorer 5; it is not guaranteed to work with earlier versions.
1275
1276 @item Other browsers.
1277 If you are using a different browser to create your cookies,
1278 @samp{--load-cookies} will only work if you can locate or produce a
1279 cookie file in the Netscape format that Wget expects.
1280 @end table
1281
1282 If you cannot use @samp{--load-cookies}, there might still be an
1283 alternative.  If your browser supports a ``cookie manager'', you can use
1284 it to view the cookies used when accessing the site you're mirroring.
1285 Write down the name and value of the cookie, and manually instruct Wget
1286 to send those cookies, bypassing the ``official'' cookie support:
1287
1288 @example
1289 wget --no-cookies --header "Cookie: @var{name}=@var{value}"
1290 @end example
1291
1292 @cindex saving cookies
1293 @cindex cookies, saving
1294 @item --save-cookies @var{file}
1295 Save cookies to @var{file} before exiting.  This will not save cookies
1296 that have expired or that have no expiry time (so-called ``session
1297 cookies''), but also see @samp{--keep-session-cookies}.
1298
1299 @cindex cookies, session
1300 @cindex session cookies
1301 @item --keep-session-cookies
1302 When specified, causes @samp{--save-cookies} to also save session
1303 cookies.  Session cookies are normally not saved because they are
1304 meant to be kept in memory and forgotten when you exit the browser.
1305 Saving them is useful on sites that require you to log in or to visit
1306 the home page before you can access some pages.  With this option,
1307 multiple Wget runs are considered a single browser session as far as
1308 the site is concerned.
1309
1310 Since the cookie file format does not normally carry session cookies,
1311 Wget marks them with an expiry timestamp of 0.  Wget's
1312 @samp{--load-cookies} recognizes those as session cookies, but it might
1313 confuse other browsers.  Also note that cookies so loaded will be
1314 treated as other session cookies, which means that if you want
1315 @samp{--save-cookies} to preserve them again, you must use
1316 @samp{--keep-session-cookies} again.
1317
1318 @cindex Content-Length, ignore
1319 @cindex ignore length
1320 @item --ignore-length
1321 Unfortunately, some @sc{http} servers (@sc{cgi} programs, to be more
1322 precise) send out bogus @code{Content-Length} headers, which makes Wget
1323 go wild, as it thinks not all the document was retrieved.  You can spot
1324 this syndrome if Wget retries getting the same document again and again,
1325 each time claiming that the (otherwise normal) connection has closed on
1326 the very same byte.
1327
1328 With this option, Wget will ignore the @code{Content-Length} header---as
1329 if it never existed.
1330
1331 @cindex header, add
1332 @item --header=@var{header-line}
1333 Send @var{header-line} along with the rest of the headers in each
1334 @sc{http} request.  The supplied header is sent as-is, which means it
1335 must contain name and value separated by colon, and must not contain
1336 newlines.
1337
1338 You may define more than one additional header by specifying
1339 @samp{--header} more than once.
1340
1341 @example
1342 @group
1343 wget --header='Accept-Charset: iso-8859-2' \
1344      --header='Accept-Language: hr'        \
1345        http://fly.srk.fer.hr/
1346 @end group
1347 @end example
1348
1349 Specification of an empty string as the header value will clear all
1350 previous user-defined headers.
1351
1352 As of Wget 1.10, this option can be used to override headers otherwise
1353 generated automatically.  This example instructs Wget to connect to
1354 localhost, but to specify @samp{foo.bar} in the @code{Host} header:
1355
1356 @example
1357 wget --header="Host: foo.bar" http://localhost/
1358 @end example
1359
1360 In versions of Wget prior to 1.10 such use of @samp{--header} caused
1361 sending of duplicate headers.
1362
1363 @cindex redirect
1364 @item --max-redirect=@var{number}
1365 Specifies the maximum number of redirections to follow for a resource.
1366 The default is 20, which is usually far more than necessary. However, on
1367 those occasions where you want to allow more (or fewer), this is the
1368 option to use.
1369
1370 @cindex proxy user
1371 @cindex proxy password
1372 @cindex proxy authentication
1373 @item --proxy-user=@var{user}
1374 @itemx --proxy-password=@var{password}
1375 Specify the username @var{user} and password @var{password} for
1376 authentication on a proxy server.  Wget will encode them using the
1377 @code{basic} authentication scheme.
1378
1379 Security considerations similar to those with @samp{--http-password}
1380 pertain here as well.
1381
1382 @cindex http referer
1383 @cindex referer, http
1384 @item --referer=@var{url}
1385 Include `Referer: @var{url}' header in HTTP request.  Useful for
1386 retrieving documents with server-side processing that assume they are
1387 always being retrieved by interactive web browsers and only come out
1388 properly when Referer is set to one of the pages that point to them.
1389
1390 @cindex server response, save
1391 @item --save-headers
1392 Save the headers sent by the @sc{http} server to the file, preceding the
1393 actual contents, with an empty line as the separator.
1394
1395 @cindex user-agent
1396 @item -U @var{agent-string}
1397 @itemx --user-agent=@var{agent-string}
1398 Identify as @var{agent-string} to the @sc{http} server.
1399
1400 The @sc{http} protocol allows the clients to identify themselves using a
1401 @code{User-Agent} header field.  This enables distinguishing the
1402 @sc{www} software, usually for statistical purposes or for tracing of
1403 protocol violations.  Wget normally identifies as
1404 @samp{Wget/@var{version}}, @var{version} being the current version
1405 number of Wget.
1406
1407 However, some sites have been known to impose the policy of tailoring
1408 the output according to the @code{User-Agent}-supplied information.
1409 While this is not such a bad idea in theory, it has been abused by
1410 servers denying information to clients other than (historically)
1411 Netscape or, more frequently, Microsoft Internet Explorer.  This
1412 option allows you to change the @code{User-Agent} line issued by Wget.
1413 Use of this option is discouraged, unless you really know what you are
1414 doing.
1415
1416 Specifying empty user agent with @samp{--user-agent=""} instructs Wget
1417 not to send the @code{User-Agent} header in @sc{http} requests.
1418
1419 @cindex POST
1420 @item --post-data=@var{string}
1421 @itemx --post-file=@var{file}
1422 Use POST as the method for all HTTP requests and send the specified
1423 data in the request body.  @samp{--post-data} sends @var{string} as
1424 data, whereas @samp{--post-file} sends the contents of @var{file}.
1425 Other than that, they work in exactly the same way. In particular,
1426 they @emph{both} expect content of the form @code{key1=value1&key2=value2},
1427 with percent-encoding for special characters; the only difference is
1428 that one expects its content as a command-line paramter and the other
1429 accepts its content from a file. In particular, @samp{--post-file} is
1430 @emph{not} for transmitting files as form attachments: those must
1431 appear as @code{key=value} data (with appropriate percent-coding) just
1432 like everything else. Wget does not currently support
1433 @code{multipart/form-data} for transmitting POST data; only
1434 @code{application/x-www-form-urlencoded}. Only one of
1435 @samp{--post-data} and @samp{--post-file} should be specified.
1436
1437 Please be aware that Wget needs to know the size of the POST data in
1438 advance.  Therefore the argument to @code{--post-file} must be a regular
1439 file; specifying a FIFO or something like @file{/dev/stdin} won't work.
1440 It's not quite clear how to work around this limitation inherent in
1441 HTTP/1.0.  Although HTTP/1.1 introduces @dfn{chunked} transfer that
1442 doesn't require knowing the request length in advance, a client can't
1443 use chunked unless it knows it's talking to an HTTP/1.1 server.  And it
1444 can't know that until it receives a response, which in turn requires the
1445 request to have been completed -- a chicken-and-egg problem.
1446
1447 Note: if Wget is redirected after the POST request is completed, it
1448 will not send the POST data to the redirected URL.  This is because
1449 URLs that process POST often respond with a redirection to a regular
1450 page, which does not desire or accept POST.  It is not completely
1451 clear that this behavior is optimal; if it doesn't work out, it might
1452 be changed in the future.
1453
1454 This example shows how to log to a server using POST and then proceed to
1455 download the desired pages, presumably only accessible to authorized
1456 users:
1457
1458 @example
1459 @group
1460 # @r{Log in to the server.  This can be done only once.}
1461 wget --save-cookies cookies.txt \
1462      --post-data 'user=foo&password=bar' \
1463      http://server.com/auth.php
1464
1465 # @r{Now grab the page or pages we care about.}
1466 wget --load-cookies cookies.txt \
1467      -p http://server.com/interesting/article.php
1468 @end group
1469 @end example
1470
1471 If the server is using session cookies to track user authentication,
1472 the above will not work because @samp{--save-cookies} will not save
1473 them (and neither will browsers) and the @file{cookies.txt} file will
1474 be empty.  In that case use @samp{--keep-session-cookies} along with
1475 @samp{--save-cookies} to force saving of session cookies.
1476
1477 @cindex Content-Disposition
1478 @item --content-disposition
1479
1480 If this is set to on, experimental (not fully-functional) support for
1481 @code{Content-Disposition} headers is enabled. This can currently result in
1482 extra round-trips to the server for a @code{HEAD} request, and is known
1483 to suffer from a few bugs, which is why it is not currently enabled by default.
1484
1485 This option is useful for some file-downloading CGI programs that use
1486 @code{Content-Disposition} headers to describe what the name of a
1487 downloaded file should be.
1488
1489 @cindex authentication
1490 @item --auth-no-challenge
1491
1492 If this option is given, Wget will send Basic HTTP authentication
1493 information (plaintext username and password) for all requests, just
1494 like Wget 1.10.2 and prior did by default.
1495
1496 Use of this option is not recommended, and is intended only to support
1497 some few obscure servers, which never send HTTP authentication
1498 challenges, but accept unsolicited auth info, say, in addition to
1499 form-based authentication.
1500
1501 @end table
1502
1503 @node HTTPS (SSL/TLS) Options, FTP Options, HTTP Options, Invoking
1504 @section HTTPS (SSL/TLS) Options
1505
1506 @cindex SSL
1507 To support encrypted HTTP (HTTPS) downloads, Wget must be compiled
1508 with an external SSL library, currently OpenSSL.  If Wget is compiled
1509 without SSL support, none of these options are available.
1510
1511 @table @samp
1512 @cindex SSL protocol, choose
1513 @item --secure-protocol=@var{protocol}
1514 Choose the secure protocol to be used.  Legal values are @samp{auto},
1515 @samp{SSLv2}, @samp{SSLv3}, and @samp{TLSv1}.  If @samp{auto} is used,
1516 the SSL library is given the liberty of choosing the appropriate
1517 protocol automatically, which is achieved by sending an SSLv2 greeting
1518 and announcing support for SSLv3 and TLSv1.  This is the default.
1519
1520 Specifying @samp{SSLv2}, @samp{SSLv3}, or @samp{TLSv1} forces the use
1521 of the corresponding protocol.  This is useful when talking to old and
1522 buggy SSL server implementations that make it hard for OpenSSL to
1523 choose the correct protocol version.  Fortunately, such servers are
1524 quite rare.
1525
1526 @cindex SSL certificate, check
1527 @item --no-check-certificate
1528 Don't check the server certificate against the available certificate
1529 authorities.  Also don't require the URL host name to match the common
1530 name presented by the certificate.
1531
1532 As of Wget 1.10, the default is to verify the server's certificate
1533 against the recognized certificate authorities, breaking the SSL
1534 handshake and aborting the download if the verification fails.
1535 Although this provides more secure downloads, it does break
1536 interoperability with some sites that worked with previous Wget
1537 versions, particularly those using self-signed, expired, or otherwise
1538 invalid certificates.  This option forces an ``insecure'' mode of
1539 operation that turns the certificate verification errors into warnings
1540 and allows you to proceed.
1541
1542 If you encounter ``certificate verification'' errors or ones saying
1543 that ``common name doesn't match requested host name'', you can use
1544 this option to bypass the verification and proceed with the download.
1545 @emph{Only use this option if you are otherwise convinced of the
1546 site's authenticity, or if you really don't care about the validity of
1547 its certificate.}  It is almost always a bad idea not to check the
1548 certificates when transmitting confidential or important data.
1549
1550 @cindex SSL certificate
1551 @item --certificate=@var{file}
1552 Use the client certificate stored in @var{file}.  This is needed for
1553 servers that are configured to require certificates from the clients
1554 that connect to them.  Normally a certificate is not required and this
1555 switch is optional.
1556
1557 @cindex SSL certificate type, specify
1558 @item --certificate-type=@var{type}
1559 Specify the type of the client certificate.  Legal values are
1560 @samp{PEM} (assumed by default) and @samp{DER}, also known as
1561 @samp{ASN1}.
1562
1563 @item --private-key=@var{file}
1564 Read the private key from @var{file}.  This allows you to provide the
1565 private key in a file separate from the certificate.
1566
1567 @item --private-key-type=@var{type}
1568 Specify the type of the private key.  Accepted values are @samp{PEM}
1569 (the default) and @samp{DER}.
1570
1571 @item --ca-certificate=@var{file}
1572 Use @var{file} as the file with the bundle of certificate authorities
1573 (``CA'') to verify the peers.  The certificates must be in PEM format.
1574
1575 Without this option Wget looks for CA certificates at the
1576 system-specified locations, chosen at OpenSSL installation time.
1577
1578 @cindex SSL certificate authority
1579 @item --ca-directory=@var{directory}
1580 Specifies directory containing CA certificates in PEM format.  Each
1581 file contains one CA certificate, and the file name is based on a hash
1582 value derived from the certificate.  This is achieved by processing a
1583 certificate directory with the @code{c_rehash} utility supplied with
1584 OpenSSL.  Using @samp{--ca-directory} is more efficient than
1585 @samp{--ca-certificate} when many certificates are installed because
1586 it allows Wget to fetch certificates on demand.
1587
1588 Without this option Wget looks for CA certificates at the
1589 system-specified locations, chosen at OpenSSL installation time.
1590
1591 @cindex entropy, specifying source of
1592 @cindex randomness, specifying source of
1593 @item --random-file=@var{file}
1594 Use @var{file} as the source of random data for seeding the
1595 pseudo-random number generator on systems without @file{/dev/random}.
1596
1597 On such systems the SSL library needs an external source of randomness
1598 to initialize.  Randomness may be provided by EGD (see
1599 @samp{--egd-file} below) or read from an external source specified by
1600 the user.  If this option is not specified, Wget looks for random data
1601 in @code{$RANDFILE} or, if that is unset, in @file{$HOME/.rnd}.  If
1602 none of those are available, it is likely that SSL encryption will not
1603 be usable.
1604
1605 If you're getting the ``Could not seed OpenSSL PRNG; disabling SSL.'' 
1606 error, you should provide random data using some of the methods
1607 described above.
1608
1609 @cindex EGD
1610 @item --egd-file=@var{file}
1611 Use @var{file} as the EGD socket.  EGD stands for @dfn{Entropy
1612 Gathering Daemon}, a user-space program that collects data from
1613 various unpredictable system sources and makes it available to other
1614 programs that might need it.  Encryption software, such as the SSL
1615 library, needs sources of non-repeating randomness to seed the random
1616 number generator used to produce cryptographically strong keys.
1617
1618 OpenSSL allows the user to specify his own source of entropy using the
1619 @code{RAND_FILE} environment variable.  If this variable is unset, or
1620 if the specified file does not produce enough randomness, OpenSSL will
1621 read random data from EGD socket specified using this option.
1622
1623 If this option is not specified (and the equivalent startup command is
1624 not used), EGD is never contacted.  EGD is not needed on modern Unix
1625 systems that support @file{/dev/random}.
1626 @end table
1627
1628 @node FTP Options, Recursive Retrieval Options, HTTPS (SSL/TLS) Options, Invoking
1629 @section FTP Options
1630
1631 @table @samp
1632 @cindex ftp user
1633 @cindex ftp password
1634 @cindex ftp authentication
1635 @item --ftp-user=@var{user}
1636 @itemx --ftp-password=@var{password}
1637 Specify the username @var{user} and password @var{password} on an
1638 @sc{ftp} server.  Without this, or the corresponding startup option, 
1639 the password defaults to @samp{-wget@@}, normally used for anonymous 
1640 FTP.
1641
1642 Another way to specify username and password is in the @sc{url} itself
1643 (@pxref{URL Format}).  Either method reveals your password to anyone who
1644 bothers to run @code{ps}.  To prevent the passwords from being seen,
1645 store them in @file{.wgetrc} or @file{.netrc}, and make sure to protect
1646 those files from other users with @code{chmod}.  If the passwords are
1647 really important, do not leave them lying in those files either---edit
1648 the files and delete them after Wget has started the download.
1649
1650 @iftex
1651 For more information about security issues with Wget, @xref{Security
1652 Considerations}.
1653 @end iftex
1654
1655 @cindex .listing files, removing
1656 @item --no-remove-listing
1657 Don't remove the temporary @file{.listing} files generated by @sc{ftp}
1658 retrievals.  Normally, these files contain the raw directory listings
1659 received from @sc{ftp} servers.  Not removing them can be useful for
1660 debugging purposes, or when you want to be able to easily check on the
1661 contents of remote server directories (e.g. to verify that a mirror
1662 you're running is complete).
1663
1664 Note that even though Wget writes to a known filename for this file,
1665 this is not a security hole in the scenario of a user making
1666 @file{.listing} a symbolic link to @file{/etc/passwd} or something and
1667 asking @code{root} to run Wget in his or her directory.  Depending on
1668 the options used, either Wget will refuse to write to @file{.listing},
1669 making the globbing/recursion/time-stamping operation fail, or the
1670 symbolic link will be deleted and replaced with the actual
1671 @file{.listing} file, or the listing will be written to a
1672 @file{.listing.@var{number}} file.
1673
1674 Even though this situation isn't a problem, though, @code{root} should
1675 never run Wget in a non-trusted user's directory.  A user could do
1676 something as simple as linking @file{index.html} to @file{/etc/passwd}
1677 and asking @code{root} to run Wget with @samp{-N} or @samp{-r} so the file
1678 will be overwritten.
1679
1680 @cindex globbing, toggle
1681 @item --no-glob
1682 Turn off @sc{ftp} globbing.  Globbing refers to the use of shell-like
1683 special characters (@dfn{wildcards}), like @samp{*}, @samp{?}, @samp{[}
1684 and @samp{]} to retrieve more than one file from the same directory at
1685 once, like:
1686
1687 @example
1688 wget ftp://gnjilux.srk.fer.hr/*.msg
1689 @end example
1690
1691 By default, globbing will be turned on if the @sc{url} contains a
1692 globbing character.  This option may be used to turn globbing on or off
1693 permanently.
1694
1695 You may have to quote the @sc{url} to protect it from being expanded by
1696 your shell.  Globbing makes Wget look for a directory listing, which is
1697 system-specific.  This is why it currently works only with Unix @sc{ftp}
1698 servers (and the ones emulating Unix @code{ls} output).
1699
1700 @cindex passive ftp
1701 @item --no-passive-ftp
1702 Disable the use of the @dfn{passive} FTP transfer mode.  Passive FTP
1703 mandates that the client connect to the server to establish the data
1704 connection rather than the other way around.
1705
1706 If the machine is connected to the Internet directly, both passive and
1707 active FTP should work equally well.  Behind most firewall and NAT
1708 configurations passive FTP has a better chance of working.  However,
1709 in some rare firewall configurations, active FTP actually works when
1710 passive FTP doesn't.  If you suspect this to be the case, use this
1711 option, or set @code{passive_ftp=off} in your init file.
1712
1713 @cindex symbolic links, retrieving
1714 @item --retr-symlinks
1715 Usually, when retrieving @sc{ftp} directories recursively and a symbolic
1716 link is encountered, the linked-to file is not downloaded.  Instead, a
1717 matching symbolic link is created on the local filesystem.  The
1718 pointed-to file will not be downloaded unless this recursive retrieval
1719 would have encountered it separately and downloaded it anyway.
1720
1721 When @samp{--retr-symlinks} is specified, however, symbolic links are
1722 traversed and the pointed-to files are retrieved.  At this time, this
1723 option does not cause Wget to traverse symlinks to directories and
1724 recurse through them, but in the future it should be enhanced to do
1725 this.
1726
1727 Note that when retrieving a file (not a directory) because it was
1728 specified on the command-line, rather than because it was recursed to,
1729 this option has no effect.  Symbolic links are always traversed in this
1730 case.
1731 @end table
1732
1733 @node Recursive Retrieval Options, Recursive Accept/Reject Options, FTP Options, Invoking
1734 @section Recursive Retrieval Options
1735
1736 @table @samp
1737 @item -r
1738 @itemx --recursive
1739 Turn on recursive retrieving.  @xref{Recursive Download}, for more
1740 details.
1741
1742 @item -l @var{depth}
1743 @itemx --level=@var{depth}
1744 Specify recursion maximum depth level @var{depth} (@pxref{Recursive
1745 Download}).  The default maximum depth is 5.
1746
1747 @cindex proxy filling
1748 @cindex delete after retrieval
1749 @cindex filling proxy cache
1750 @item --delete-after
1751 This option tells Wget to delete every single file it downloads,
1752 @emph{after} having done so.  It is useful for pre-fetching popular
1753 pages through a proxy, e.g.:
1754
1755 @example
1756 wget -r -nd --delete-after http://whatever.com/~popular/page/
1757 @end example
1758
1759 The @samp{-r} option is to retrieve recursively, and @samp{-nd} to not
1760 create directories.  
1761
1762 Note that @samp{--delete-after} deletes files on the local machine.  It
1763 does not issue the @samp{DELE} command to remote FTP sites, for
1764 instance.  Also note that when @samp{--delete-after} is specified,
1765 @samp{--convert-links} is ignored, so @samp{.orig} files are simply not
1766 created in the first place.
1767
1768 @cindex conversion of links
1769 @cindex link conversion
1770 @item -k
1771 @itemx --convert-links
1772 After the download is complete, convert the links in the document to
1773 make them suitable for local viewing.  This affects not only the visible
1774 hyperlinks, but any part of the document that links to external content,
1775 such as embedded images, links to style sheets, hyperlinks to non-@sc{html}
1776 content, etc.
1777
1778 Each link will be changed in one of the two ways:
1779
1780 @itemize @bullet
1781 @item
1782 The links to files that have been downloaded by Wget will be changed to
1783 refer to the file they point to as a relative link.
1784
1785 Example: if the downloaded file @file{/foo/doc.html} links to
1786 @file{/bar/img.gif}, also downloaded, then the link in @file{doc.html}
1787 will be modified to point to @samp{../bar/img.gif}.  This kind of
1788 transformation works reliably for arbitrary combinations of directories.
1789
1790 @item
1791 The links to files that have not been downloaded by Wget will be changed
1792 to include host name and absolute path of the location they point to.
1793
1794 Example: if the downloaded file @file{/foo/doc.html} links to
1795 @file{/bar/img.gif} (or to @file{../bar/img.gif}), then the link in
1796 @file{doc.html} will be modified to point to
1797 @file{http://@var{hostname}/bar/img.gif}.
1798 @end itemize
1799
1800 Because of this, local browsing works reliably: if a linked file was
1801 downloaded, the link will refer to its local name; if it was not
1802 downloaded, the link will refer to its full Internet address rather than
1803 presenting a broken link.  The fact that the former links are converted
1804 to relative links ensures that you can move the downloaded hierarchy to
1805 another directory.
1806
1807 Note that only at the end of the download can Wget know which links have
1808 been downloaded.  Because of that, the work done by @samp{-k} will be
1809 performed at the end of all the downloads.
1810
1811 @cindex backing up converted files
1812 @item -K
1813 @itemx --backup-converted
1814 When converting a file, back up the original version with a @samp{.orig}
1815 suffix.  Affects the behavior of @samp{-N} (@pxref{HTTP Time-Stamping
1816 Internals}).
1817
1818 @item -m
1819 @itemx --mirror
1820 Turn on options suitable for mirroring.  This option turns on recursion
1821 and time-stamping, sets infinite recursion depth and keeps @sc{ftp}
1822 directory listings.  It is currently equivalent to
1823 @samp{-r -N -l inf --no-remove-listing}.
1824
1825 @cindex page requisites
1826 @cindex required images, downloading
1827 @item -p
1828 @itemx --page-requisites
1829 This option causes Wget to download all the files that are necessary to
1830 properly display a given @sc{html} page.  This includes such things as
1831 inlined images, sounds, and referenced stylesheets.
1832
1833 Ordinarily, when downloading a single @sc{html} page, any requisite documents
1834 that may be needed to display it properly are not downloaded.  Using
1835 @samp{-r} together with @samp{-l} can help, but since Wget does not
1836 ordinarily distinguish between external and inlined documents, one is
1837 generally left with ``leaf documents'' that are missing their
1838 requisites.
1839
1840 For instance, say document @file{1.html} contains an @code{<IMG>} tag
1841 referencing @file{1.gif} and an @code{<A>} tag pointing to external
1842 document @file{2.html}.  Say that @file{2.html} is similar but that its
1843 image is @file{2.gif} and it links to @file{3.html}.  Say this
1844 continues up to some arbitrarily high number.
1845
1846 If one executes the command:
1847
1848 @example
1849 wget -r -l 2 http://@var{site}/1.html
1850 @end example
1851
1852 then @file{1.html}, @file{1.gif}, @file{2.html}, @file{2.gif}, and
1853 @file{3.html} will be downloaded.  As you can see, @file{3.html} is
1854 without its requisite @file{3.gif} because Wget is simply counting the
1855 number of hops (up to 2) away from @file{1.html} in order to determine
1856 where to stop the recursion.  However, with this command:
1857
1858 @example
1859 wget -r -l 2 -p http://@var{site}/1.html
1860 @end example
1861
1862 all the above files @emph{and} @file{3.html}'s requisite @file{3.gif}
1863 will be downloaded.  Similarly,
1864
1865 @example
1866 wget -r -l 1 -p http://@var{site}/1.html
1867 @end example
1868
1869 will cause @file{1.html}, @file{1.gif}, @file{2.html}, and @file{2.gif}
1870 to be downloaded.  One might think that:
1871
1872 @example
1873 wget -r -l 0 -p http://@var{site}/1.html
1874 @end example
1875
1876 would download just @file{1.html} and @file{1.gif}, but unfortunately
1877 this is not the case, because @samp{-l 0} is equivalent to
1878 @samp{-l inf}---that is, infinite recursion.  To download a single @sc{html}
1879 page (or a handful of them, all specified on the command-line or in a
1880 @samp{-i} @sc{url} input file) and its (or their) requisites, simply leave off
1881 @samp{-r} and @samp{-l}:
1882
1883 @example
1884 wget -p http://@var{site}/1.html
1885 @end example
1886
1887 Note that Wget will behave as if @samp{-r} had been specified, but only
1888 that single page and its requisites will be downloaded.  Links from that
1889 page to external documents will not be followed.  Actually, to download
1890 a single page and all its requisites (even if they exist on separate
1891 websites), and make sure the lot displays properly locally, this author
1892 likes to use a few options in addition to @samp{-p}:
1893
1894 @example
1895 wget -E -H -k -K -p http://@var{site}/@var{document}
1896 @end example
1897
1898 To finish off this topic, it's worth knowing that Wget's idea of an
1899 external document link is any URL specified in an @code{<A>} tag, an
1900 @code{<AREA>} tag, or a @code{<LINK>} tag other than @code{<LINK
1901 REL="stylesheet">}.
1902
1903 @cindex @sc{html} comments
1904 @cindex comments, @sc{html}
1905 @item --strict-comments
1906 Turn on strict parsing of @sc{html} comments.  The default is to terminate
1907 comments at the first occurrence of @samp{-->}.
1908
1909 According to specifications, @sc{html} comments are expressed as @sc{sgml}
1910 @dfn{declarations}.  Declaration is special markup that begins with
1911 @samp{<!} and ends with @samp{>}, such as @samp{<!DOCTYPE ...>}, that
1912 may contain comments between a pair of @samp{--} delimiters.  @sc{html}
1913 comments are ``empty declarations'', @sc{sgml} declarations without any
1914 non-comment text.  Therefore, @samp{<!--foo-->} is a valid comment, and
1915 so is @samp{<!--one-- --two-->}, but @samp{<!--1--2-->} is not.
1916
1917 On the other hand, most @sc{html} writers don't perceive comments as anything
1918 other than text delimited with @samp{<!--} and @samp{-->}, which is not
1919 quite the same.  For example, something like @samp{<!------------>}
1920 works as a valid comment as long as the number of dashes is a multiple
1921 of four (!).  If not, the comment technically lasts until the next
1922 @samp{--}, which may be at the other end of the document.  Because of
1923 this, many popular browsers completely ignore the specification and
1924 implement what users have come to expect: comments delimited with
1925 @samp{<!--} and @samp{-->}.
1926
1927 Until version 1.9, Wget interpreted comments strictly, which resulted in
1928 missing links in many web pages that displayed fine in browsers, but had
1929 the misfortune of containing non-compliant comments.  Beginning with
1930 version 1.9, Wget has joined the ranks of clients that implements
1931 ``naive'' comments, terminating each comment at the first occurrence of
1932 @samp{-->}.
1933
1934 If, for whatever reason, you want strict comment parsing, use this
1935 option to turn it on.
1936 @end table
1937
1938 @node Recursive Accept/Reject Options,  , Recursive Retrieval Options, Invoking
1939 @section Recursive Accept/Reject Options
1940
1941 @table @samp
1942 @item -A @var{acclist} --accept @var{acclist}
1943 @itemx -R @var{rejlist} --reject @var{rejlist}
1944 Specify comma-separated lists of file name suffixes or patterns to
1945 accept or reject (@pxref{Types of Files}). Note that if
1946 any of the wildcard characters, @samp{*}, @samp{?}, @samp{[} or
1947 @samp{]}, appear in an element of @var{acclist} or @var{rejlist},
1948 it will be treated as a pattern, rather than a suffix.
1949
1950 @item -D @var{domain-list}
1951 @itemx --domains=@var{domain-list}
1952 Set domains to be followed.  @var{domain-list} is a comma-separated list
1953 of domains.  Note that it does @emph{not} turn on @samp{-H}.
1954
1955 @item --exclude-domains @var{domain-list}
1956 Specify the domains that are @emph{not} to be followed.
1957 (@pxref{Spanning Hosts}).
1958
1959 @cindex follow FTP links
1960 @item --follow-ftp
1961 Follow @sc{ftp} links from @sc{html} documents.  Without this option,
1962 Wget will ignore all the @sc{ftp} links.
1963
1964 @cindex tag-based recursive pruning
1965 @item --follow-tags=@var{list}
1966 Wget has an internal table of @sc{html} tag / attribute pairs that it
1967 considers when looking for linked documents during a recursive
1968 retrieval.  If a user wants only a subset of those tags to be
1969 considered, however, he or she should be specify such tags in a
1970 comma-separated @var{list} with this option.
1971
1972 @item --ignore-tags=@var{list}
1973 This is the opposite of the @samp{--follow-tags} option.  To skip
1974 certain @sc{html} tags when recursively looking for documents to download,
1975 specify them in a comma-separated @var{list}.  
1976
1977 In the past, this option was the best bet for downloading a single page
1978 and its requisites, using a command-line like:
1979
1980 @example
1981 wget --ignore-tags=a,area -H -k -K -r http://@var{site}/@var{document}
1982 @end example
1983
1984 However, the author of this option came across a page with tags like
1985 @code{<LINK REL="home" HREF="/">} and came to the realization that
1986 specifying tags to ignore was not enough.  One can't just tell Wget to
1987 ignore @code{<LINK>}, because then stylesheets will not be downloaded.
1988 Now the best bet for downloading a single page and its requisites is the
1989 dedicated @samp{--page-requisites} option.
1990
1991 @cindex case fold
1992 @cindex ignore case
1993 @item --ignore-case
1994 Ignore case when matching files and directories.  This influences the
1995 behavior of -R, -A, -I, and -X options, as well as globbing
1996 implemented when downloading from FTP sites.  For example, with this
1997 option, @samp{-A *.txt} will match @samp{file1.txt}, but also
1998 @samp{file2.TXT}, @samp{file3.TxT}, and so on.
1999
2000 @item -H
2001 @itemx --span-hosts
2002 Enable spanning across hosts when doing recursive retrieving
2003 (@pxref{Spanning Hosts}).
2004
2005 @item -L
2006 @itemx --relative
2007 Follow relative links only.  Useful for retrieving a specific home page
2008 without any distractions, not even those from the same hosts
2009 (@pxref{Relative Links}).
2010
2011 @item -I @var{list}
2012 @itemx --include-directories=@var{list}
2013 Specify a comma-separated list of directories you wish to follow when
2014 downloading (@pxref{Directory-Based Limits}).  Elements
2015 of @var{list} may contain wildcards.
2016
2017 @item -X @var{list}
2018 @itemx --exclude-directories=@var{list}
2019 Specify a comma-separated list of directories you wish to exclude from
2020 download (@pxref{Directory-Based Limits}).  Elements of
2021 @var{list} may contain wildcards.
2022
2023 @item -np
2024 @item --no-parent
2025 Do not ever ascend to the parent directory when retrieving recursively.
2026 This is a useful option, since it guarantees that only the files
2027 @emph{below} a certain hierarchy will be downloaded.
2028 @xref{Directory-Based Limits}, for more details.
2029 @end table
2030
2031 @c man end
2032
2033 @node Recursive Download, Following Links, Invoking, Top
2034 @chapter Recursive Download
2035 @cindex recursion
2036 @cindex retrieving
2037 @cindex recursive download
2038
2039 GNU Wget is capable of traversing parts of the Web (or a single
2040 @sc{http} or @sc{ftp} server), following links and directory structure.
2041 We refer to this as to @dfn{recursive retrieval}, or @dfn{recursion}.
2042
2043 With @sc{http} @sc{url}s, Wget retrieves and parses the @sc{html} or
2044 @sc{css} from the given @sc{url}, retrieving the files the document
2045 refers to, through markup like @code{href} or @code{src}, or @sc{css}
2046 @sc{uri} values specified using the @samp{url()} functional notation.
2047 If the freshly downloaded file is also of type @code{text/html},
2048 @code{application/xhtml+xml}, or @code{text/css}, it will be parsed
2049 and followed further.
2050
2051 Recursive retrieval of @sc{http} and @sc{html}/@sc{css} content is
2052 @dfn{breadth-first}.  This means that Wget first downloads the requested
2053 document, then the documents linked from that document, then the
2054 documents linked by them, and so on.  In other words, Wget first
2055 downloads the documents at depth 1, then those at depth 2, and so on
2056 until the specified maximum depth.
2057
2058 The maximum @dfn{depth} to which the retrieval may descend is specified
2059 with the @samp{-l} option.  The default maximum depth is five layers.
2060
2061 When retrieving an @sc{ftp} @sc{url} recursively, Wget will retrieve all
2062 the data from the given directory tree (including the subdirectories up
2063 to the specified depth) on the remote server, creating its mirror image
2064 locally.  @sc{ftp} retrieval is also limited by the @code{depth}
2065 parameter.  Unlike @sc{http} recursion, @sc{ftp} recursion is performed
2066 depth-first.
2067
2068 By default, Wget will create a local directory tree, corresponding to
2069 the one found on the remote server.
2070
2071 Recursive retrieving can find a number of applications, the most
2072 important of which is mirroring.  It is also useful for @sc{www}
2073 presentations, and any other opportunities where slow network
2074 connections should be bypassed by storing the files locally.
2075
2076 You should be warned that recursive downloads can overload the remote
2077 servers.  Because of that, many administrators frown upon them and may
2078 ban access from your site if they detect very fast downloads of big
2079 amounts of content.  When downloading from Internet servers, consider
2080 using the @samp{-w} option to introduce a delay between accesses to the
2081 server.  The download will take a while longer, but the server
2082 administrator will not be alarmed by your rudeness.
2083
2084 Of course, recursive download may cause problems on your machine.  If
2085 left to run unchecked, it can easily fill up the disk.  If downloading
2086 from local network, it can also take bandwidth on the system, as well as
2087 consume memory and CPU.
2088
2089 Try to specify the criteria that match the kind of download you are
2090 trying to achieve.  If you want to download only one page, use
2091 @samp{--page-requisites} without any additional recursion.  If you want
2092 to download things under one directory, use @samp{-np} to avoid
2093 downloading things from other directories.  If you want to download all
2094 the files from one directory, use @samp{-l 1} to make sure the recursion
2095 depth never exceeds one.  @xref{Following Links}, for more information
2096 about this.
2097
2098 Recursive retrieval should be used with care.  Don't say you were not
2099 warned.
2100
2101 @node Following Links, Time-Stamping, Recursive Download, Top
2102 @chapter Following Links
2103 @cindex links
2104 @cindex following links
2105
2106 When retrieving recursively, one does not wish to retrieve loads of
2107 unnecessary data.  Most of the time the users bear in mind exactly what
2108 they want to download, and want Wget to follow only specific links.
2109
2110 For example, if you wish to download the music archive from
2111 @samp{fly.srk.fer.hr}, you will not want to download all the home pages
2112 that happen to be referenced by an obscure part of the archive.
2113
2114 Wget possesses several mechanisms that allows you to fine-tune which
2115 links it will follow.
2116
2117 @menu
2118 * Spanning Hosts::         (Un)limiting retrieval based on host name.
2119 * Types of Files::         Getting only certain files.
2120 * Directory-Based Limits:: Getting only certain directories.
2121 * Relative Links::         Follow relative links only.
2122 * FTP Links::              Following FTP links.
2123 @end menu
2124
2125 @node Spanning Hosts, Types of Files, Following Links, Following Links
2126 @section Spanning Hosts
2127 @cindex spanning hosts
2128 @cindex hosts, spanning
2129
2130 Wget's recursive retrieval normally refuses to visit hosts different
2131 than the one you specified on the command line.  This is a reasonable
2132 default; without it, every retrieval would have the potential to turn
2133 your Wget into a small version of google.
2134
2135 However, visiting different hosts, or @dfn{host spanning,} is sometimes
2136 a useful option.  Maybe the images are served from a different server.
2137 Maybe you're mirroring a site that consists of pages interlinked between
2138 three servers.  Maybe the server has two equivalent names, and the @sc{html}
2139 pages refer to both interchangeably.
2140
2141 @table @asis
2142 @item Span to any host---@samp{-H}
2143
2144 The @samp{-H} option turns on host spanning, thus allowing Wget's
2145 recursive run to visit any host referenced by a link.  Unless sufficient
2146 recursion-limiting criteria are applied depth, these foreign hosts will
2147 typically link to yet more hosts, and so on until Wget ends up sucking
2148 up much more data than you have intended.
2149
2150 @item Limit spanning to certain domains---@samp{-D}
2151
2152 The @samp{-D} option allows you to specify the domains that will be
2153 followed, thus limiting the recursion only to the hosts that belong to
2154 these domains.  Obviously, this makes sense only in conjunction with
2155 @samp{-H}.  A typical example would be downloading the contents of
2156 @samp{www.server.com}, but allowing downloads from
2157 @samp{images.server.com}, etc.:
2158
2159 @example
2160 wget -rH -Dserver.com http://www.server.com/
2161 @end example
2162
2163 You can specify more than one address by separating them with a comma,
2164 e.g. @samp{-Ddomain1.com,domain2.com}.
2165
2166 @item Keep download off certain domains---@samp{--exclude-domains}
2167
2168 If there are domains you want to exclude specifically, you can do it
2169 with @samp{--exclude-domains}, which accepts the same type of arguments
2170 of @samp{-D}, but will @emph{exclude} all the listed domains.  For
2171 example, if you want to download all the hosts from @samp{foo.edu}
2172 domain, with the exception of @samp{sunsite.foo.edu}, you can do it like
2173 this:
2174
2175 @example
2176 wget -rH -Dfoo.edu --exclude-domains sunsite.foo.edu \
2177     http://www.foo.edu/
2178 @end example
2179
2180 @end table
2181
2182 @node Types of Files, Directory-Based Limits, Spanning Hosts, Following Links
2183 @section Types of Files
2184 @cindex types of files
2185
2186 When downloading material from the web, you will often want to restrict
2187 the retrieval to only certain file types.  For example, if you are
2188 interested in downloading @sc{gif}s, you will not be overjoyed to get
2189 loads of PostScript documents, and vice versa.
2190
2191 Wget offers two options to deal with this problem.  Each option
2192 description lists a short name, a long name, and the equivalent command
2193 in @file{.wgetrc}.
2194
2195 @cindex accept wildcards
2196 @cindex accept suffixes
2197 @cindex wildcards, accept
2198 @cindex suffixes, accept
2199 @table @samp
2200 @item -A @var{acclist}
2201 @itemx --accept @var{acclist}
2202 @itemx accept = @var{acclist}
2203 The argument to @samp{--accept} option is a list of file suffixes or
2204 patterns that Wget will download during recursive retrieval.  A suffix
2205 is the ending part of a file, and consists of ``normal'' letters,
2206 e.g. @samp{gif} or @samp{.jpg}.  A matching pattern contains shell-like
2207 wildcards, e.g. @samp{books*} or @samp{zelazny*196[0-9]*}.
2208
2209 So, specifying @samp{wget -A gif,jpg} will make Wget download only the
2210 files ending with @samp{gif} or @samp{jpg}, i.e. @sc{gif}s and
2211 @sc{jpeg}s.  On the other hand, @samp{wget -A "zelazny*196[0-9]*"} will
2212 download only files beginning with @samp{zelazny} and containing numbers
2213 from 1960 to 1969 anywhere within.  Look up the manual of your shell for
2214 a description of how pattern matching works.
2215
2216 Of course, any number of suffixes and patterns can be combined into a
2217 comma-separated list, and given as an argument to @samp{-A}.
2218
2219 @cindex reject wildcards
2220 @cindex reject suffixes
2221 @cindex wildcards, reject
2222 @cindex suffixes, reject
2223 @item -R @var{rejlist}
2224 @itemx --reject @var{rejlist}
2225 @itemx reject = @var{rejlist}
2226 The @samp{--reject} option works the same way as @samp{--accept}, only
2227 its logic is the reverse; Wget will download all files @emph{except} the
2228 ones matching the suffixes (or patterns) in the list.
2229
2230 So, if you want to download a whole page except for the cumbersome
2231 @sc{mpeg}s and @sc{.au} files, you can use @samp{wget -R mpg,mpeg,au}.
2232 Analogously, to download all files except the ones beginning with
2233 @samp{bjork}, use @samp{wget -R "bjork*"}.  The quotes are to prevent
2234 expansion by the shell.
2235 @end table
2236
2237 @noindent
2238 The @samp{-A} and @samp{-R} options may be combined to achieve even
2239 better fine-tuning of which files to retrieve.  E.g. @samp{wget -A
2240 "*zelazny*" -R .ps} will download all the files having @samp{zelazny} as
2241 a part of their name, but @emph{not} the PostScript files.
2242
2243 Note that these two options do not affect the downloading of @sc{html}
2244 files (as determined by a @samp{.htm} or @samp{.html} filename
2245 prefix). This behavior may not be desirable for all users, and may be
2246 changed for future versions of Wget.
2247
2248 Note, too, that query strings (strings at the end of a URL beginning
2249 with a question mark (@samp{?}) are not included as part of the
2250 filename for accept/reject rules, even though these will actually
2251 contribute to the name chosen for the local file. It is expected that
2252 a future version of Wget will provide an option to allow matching
2253 against query strings.
2254
2255 Finally, it's worth noting that the accept/reject lists are matched
2256 @emph{twice} against downloaded files: once against the URL's filename
2257 portion, to determine if the file should be downloaded in the first
2258 place; then, after it has been accepted and successfully downloaded,
2259 the local file's name is also checked against the accept/reject lists
2260 to see if it should be removed. The rationale was that, since
2261 @samp{.htm} and @samp{.html} files are always downloaded regardless of
2262 accept/reject rules, they should be removed @emph{after} being
2263 downloaded and scanned for links, if they did match the accept/reject
2264 lists. However, this can lead to unexpected results, since the local
2265 filenames can differ from the original URL filenames in the following
2266 ways, all of which can change whether an accept/reject rule matches:
2267
2268 @itemize @bullet
2269 @item
2270 If the local file already exists and @samp{--no-directories} was
2271 specified, a numeric suffix will be appended to the original name.
2272 @item
2273 If @samp{--adjust-extension} was specified, the local filename might have
2274 @samp{.html} appended to it. If Wget is invoked with @samp{-E -A.php},
2275 a filename such as @samp{index.php} will match be accepted, but upon
2276 download will be named @samp{index.php.html}, which no longer matches,
2277 and so the file will be deleted.
2278 @item
2279 Query strings do not contribute to URL matching, but are included in
2280 local filenames, and so @emph{do} contribute to filename matching.
2281 @end itemize
2282
2283 @noindent
2284 This behavior, too, is considered less-than-desirable, and may change
2285 in a future version of Wget.
2286
2287 @node Directory-Based Limits, Relative Links, Types of Files, Following Links
2288 @section Directory-Based Limits
2289 @cindex directories
2290 @cindex directory limits
2291
2292 Regardless of other link-following facilities, it is often useful to
2293 place the restriction of what files to retrieve based on the directories
2294 those files are placed in.  There can be many reasons for this---the
2295 home pages may be organized in a reasonable directory structure; or some
2296 directories may contain useless information, e.g. @file{/cgi-bin} or
2297 @file{/dev} directories.
2298
2299 Wget offers three different options to deal with this requirement.  Each
2300 option description lists a short name, a long name, and the equivalent
2301 command in @file{.wgetrc}.
2302
2303 @cindex directories, include
2304 @cindex include directories
2305 @cindex accept directories
2306 @table @samp
2307 @item -I @var{list}
2308 @itemx --include @var{list}
2309 @itemx include_directories = @var{list}
2310 @samp{-I} option accepts a comma-separated list of directories included
2311 in the retrieval.  Any other directories will simply be ignored.  The
2312 directories are absolute paths.
2313
2314 So, if you wish to download from @samp{http://host/people/bozo/}
2315 following only links to bozo's colleagues in the @file{/people}
2316 directory and the bogus scripts in @file{/cgi-bin}, you can specify:
2317
2318 @example
2319 wget -I /people,/cgi-bin http://host/people/bozo/
2320 @end example
2321
2322 @cindex directories, exclude
2323 @cindex exclude directories
2324 @cindex reject directories
2325 @item -X @var{list}
2326 @itemx --exclude @var{list}
2327 @itemx exclude_directories = @var{list}
2328 @samp{-X} option is exactly the reverse of @samp{-I}---this is a list of
2329 directories @emph{excluded} from the download.  E.g. if you do not want
2330 Wget to download things from @file{/cgi-bin} directory, specify @samp{-X
2331 /cgi-bin} on the command line.
2332
2333 The same as with @samp{-A}/@samp{-R}, these two options can be combined
2334 to get a better fine-tuning of downloading subdirectories.  E.g. if you
2335 want to load all the files from @file{/pub} hierarchy except for
2336 @file{/pub/worthless}, specify @samp{-I/pub -X/pub/worthless}.
2337
2338 @cindex no parent
2339 @item -np
2340 @itemx --no-parent
2341 @itemx no_parent = on
2342 The simplest, and often very useful way of limiting directories is
2343 disallowing retrieval of the links that refer to the hierarchy
2344 @dfn{above} than the beginning directory, i.e. disallowing ascent to the
2345 parent directory/directories.
2346
2347 The @samp{--no-parent} option (short @samp{-np}) is useful in this case.
2348 Using it guarantees that you will never leave the existing hierarchy.
2349 Supposing you issue Wget with:
2350
2351 @example
2352 wget -r --no-parent http://somehost/~luzer/my-archive/
2353 @end example
2354
2355 You may rest assured that none of the references to
2356 @file{/~his-girls-homepage/} or @file{/~luzer/all-my-mpegs/} will be
2357 followed.  Only the archive you are interested in will be downloaded.
2358 Essentially, @samp{--no-parent} is similar to
2359 @samp{-I/~luzer/my-archive}, only it handles redirections in a more
2360 intelligent fashion.
2361
2362 @strong{Note} that, for HTTP (and HTTPS), the trailing slash is very
2363 important to @samp{--no-parent}. HTTP has no concept of a ``directory''---Wget
2364 relies on you to indicate what's a directory and what isn't. In
2365 @samp{http://foo/bar/}, Wget will consider @samp{bar} to be a
2366 directory, while in @samp{http://foo/bar} (no trailing slash),
2367 @samp{bar} will be considered a filename (so @samp{--no-parent} would be
2368 meaningless, as its parent is @samp{/}).
2369 @end table
2370
2371 @node Relative Links, FTP Links, Directory-Based Limits, Following Links
2372 @section Relative Links
2373 @cindex relative links
2374
2375 When @samp{-L} is turned on, only the relative links are ever followed.
2376 Relative links are here defined those that do not refer to the web
2377 server root.  For example, these links are relative:
2378
2379 @example
2380 <a href="foo.gif">
2381 <a href="foo/bar.gif">
2382 <a href="../foo/bar.gif">
2383 @end example
2384
2385 These links are not relative:
2386
2387 @example
2388 <a href="/foo.gif">
2389 <a href="/foo/bar.gif">
2390 <a href="http://www.server.com/foo/bar.gif">
2391 @end example
2392
2393 Using this option guarantees that recursive retrieval will not span
2394 hosts, even without @samp{-H}.  In simple cases it also allows downloads
2395 to ``just work'' without having to convert links.
2396
2397 This option is probably not very useful and might be removed in a future
2398 release.
2399
2400 @node FTP Links,  , Relative Links, Following Links
2401 @section Following FTP Links
2402 @cindex following ftp links
2403
2404 The rules for @sc{ftp} are somewhat specific, as it is necessary for
2405 them to be.  @sc{ftp} links in @sc{html} documents are often included
2406 for purposes of reference, and it is often inconvenient to download them
2407 by default.
2408
2409 To have @sc{ftp} links followed from @sc{html} documents, you need to
2410 specify the @samp{--follow-ftp} option.  Having done that, @sc{ftp}
2411 links will span hosts regardless of @samp{-H} setting.  This is logical,
2412 as @sc{ftp} links rarely point to the same host where the @sc{http}
2413 server resides.  For similar reasons, the @samp{-L} options has no
2414 effect on such downloads.  On the other hand, domain acceptance
2415 (@samp{-D}) and suffix rules (@samp{-A} and @samp{-R}) apply normally.
2416
2417 Also note that followed links to @sc{ftp} directories will not be
2418 retrieved recursively further.
2419
2420 @node Time-Stamping, Startup File, Following Links, Top
2421 @chapter Time-Stamping
2422 @cindex time-stamping
2423 @cindex timestamping
2424 @cindex updating the archives
2425 @cindex incremental updating
2426
2427 One of the most important aspects of mirroring information from the
2428 Internet is updating your archives.
2429
2430 Downloading the whole archive again and again, just to replace a few
2431 changed files is expensive, both in terms of wasted bandwidth and money,
2432 and the time to do the update.  This is why all the mirroring tools
2433 offer the option of incremental updating.
2434
2435 Such an updating mechanism means that the remote server is scanned in
2436 search of @dfn{new} files.  Only those new files will be downloaded in
2437 the place of the old ones.
2438
2439 A file is considered new if one of these two conditions are met:
2440
2441 @enumerate
2442 @item
2443 A file of that name does not already exist locally.
2444
2445 @item
2446 A file of that name does exist, but the remote file was modified more
2447 recently than the local file.
2448 @end enumerate
2449
2450 To implement this, the program needs to be aware of the time of last
2451 modification of both local and remote files.  We call this information the
2452 @dfn{time-stamp} of a file.
2453
2454 The time-stamping in GNU Wget is turned on using @samp{--timestamping}
2455 (@samp{-N}) option, or through @code{timestamping = on} directive in
2456 @file{.wgetrc}.  With this option, for each file it intends to download,
2457 Wget will check whether a local file of the same name exists.  If it
2458 does, and the remote file is older, Wget will not download it.
2459
2460 If the local file does not exist, or the sizes of the files do not
2461 match, Wget will download the remote file no matter what the time-stamps
2462 say.
2463
2464 @menu
2465 * Time-Stamping Usage::
2466 * HTTP Time-Stamping Internals::
2467 * FTP Time-Stamping Internals::
2468 @end menu
2469
2470 @node Time-Stamping Usage, HTTP Time-Stamping Internals, Time-Stamping, Time-Stamping
2471 @section Time-Stamping Usage
2472 @cindex time-stamping usage
2473 @cindex usage, time-stamping
2474
2475 The usage of time-stamping is simple.  Say you would like to download a
2476 file so that it keeps its date of modification.
2477
2478 @example
2479 wget -S http://www.gnu.ai.mit.edu/
2480 @end example
2481
2482 A simple @code{ls -l} shows that the time stamp on the local file equals
2483 the state of the @code{Last-Modified} header, as returned by the server.
2484 As you can see, the time-stamping info is preserved locally, even
2485 without @samp{-N} (at least for @sc{http}).
2486
2487 Several days later, you would like Wget to check if the remote file has
2488 changed, and download it if it has.
2489
2490 @example
2491 wget -N http://www.gnu.ai.mit.edu/
2492 @end example
2493
2494 Wget will ask the server for the last-modified date.  If the local file
2495 has the same timestamp as the server, or a newer one, the remote file
2496 will not be re-fetched.  However, if the remote file is more recent,
2497 Wget will proceed to fetch it.
2498
2499 The same goes for @sc{ftp}.  For example:
2500
2501 @example
2502 wget "ftp://ftp.ifi.uio.no/pub/emacs/gnus/*"
2503 @end example
2504
2505 (The quotes around that URL are to prevent the shell from trying to
2506 interpret the @samp{*}.)
2507
2508 After download, a local directory listing will show that the timestamps
2509 match those on the remote server.  Reissuing the command with @samp{-N}
2510 will make Wget re-fetch @emph{only} the files that have been modified
2511 since the last download.
2512
2513 If you wished to mirror the GNU archive every week, you would use a
2514 command like the following, weekly:
2515
2516 @example
2517 wget --timestamping -r ftp://ftp.gnu.org/pub/gnu/
2518 @end example
2519
2520 Note that time-stamping will only work for files for which the server
2521 gives a timestamp.  For @sc{http}, this depends on getting a
2522 @code{Last-Modified} header.  For @sc{ftp}, this depends on getting a
2523 directory listing with dates in a format that Wget can parse
2524 (@pxref{FTP Time-Stamping Internals}).
2525
2526 @node HTTP Time-Stamping Internals, FTP Time-Stamping Internals, Time-Stamping Usage, Time-Stamping
2527 @section HTTP Time-Stamping Internals
2528 @cindex http time-stamping
2529
2530 Time-stamping in @sc{http} is implemented by checking of the
2531 @code{Last-Modified} header.  If you wish to retrieve the file
2532 @file{foo.html} through @sc{http}, Wget will check whether
2533 @file{foo.html} exists locally.  If it doesn't, @file{foo.html} will be
2534 retrieved unconditionally.
2535
2536 If the file does exist locally, Wget will first check its local
2537 time-stamp (similar to the way @code{ls -l} checks it), and then send a
2538 @code{HEAD} request to the remote server, demanding the information on
2539 the remote file.
2540
2541 The @code{Last-Modified} header is examined to find which file was
2542 modified more recently (which makes it ``newer'').  If the remote file
2543 is newer, it will be downloaded; if it is older, Wget will give
2544 up.@footnote{As an additional check, Wget will look at the
2545 @code{Content-Length} header, and compare the sizes; if they are not the
2546 same, the remote file will be downloaded no matter what the time-stamp
2547 says.}
2548
2549 When @samp{--backup-converted} (@samp{-K}) is specified in conjunction
2550 with @samp{-N}, server file @samp{@var{X}} is compared to local file
2551 @samp{@var{X}.orig}, if extant, rather than being compared to local file
2552 @samp{@var{X}}, which will always differ if it's been converted by
2553 @samp{--convert-links} (@samp{-k}).
2554
2555 Arguably, @sc{http} time-stamping should be implemented using the
2556 @code{If-Modified-Since} request.
2557
2558 @node FTP Time-Stamping Internals,  , HTTP Time-Stamping Internals, Time-Stamping
2559 @section FTP Time-Stamping Internals
2560 @cindex ftp time-stamping
2561
2562 In theory, @sc{ftp} time-stamping works much the same as @sc{http}, only
2563 @sc{ftp} has no headers---time-stamps must be ferreted out of directory
2564 listings.
2565
2566 If an @sc{ftp} download is recursive or uses globbing, Wget will use the
2567 @sc{ftp} @code{LIST} command to get a file listing for the directory
2568 containing the desired file(s).  It will try to analyze the listing,
2569 treating it like Unix @code{ls -l} output, extracting the time-stamps.
2570 The rest is exactly the same as for @sc{http}.  Note that when
2571 retrieving individual files from an @sc{ftp} server without using
2572 globbing or recursion, listing files will not be downloaded (and thus
2573 files will not be time-stamped) unless @samp{-N} is specified.
2574
2575 Assumption that every directory listing is a Unix-style listing may
2576 sound extremely constraining, but in practice it is not, as many
2577 non-Unix @sc{ftp} servers use the Unixoid listing format because most
2578 (all?) of the clients understand it.  Bear in mind that @sc{rfc959}
2579 defines no standard way to get a file list, let alone the time-stamps.
2580 We can only hope that a future standard will define this.
2581
2582 Another non-standard solution includes the use of @code{MDTM} command
2583 that is supported by some @sc{ftp} servers (including the popular
2584 @code{wu-ftpd}), which returns the exact time of the specified file.
2585 Wget may support this command in the future.
2586
2587 @node Startup File, Examples, Time-Stamping, Top
2588 @chapter Startup File
2589 @cindex startup file
2590 @cindex wgetrc
2591 @cindex .wgetrc
2592 @cindex startup
2593 @cindex .netrc
2594
2595 Once you know how to change default settings of Wget through command
2596 line arguments, you may wish to make some of those settings permanent.
2597 You can do that in a convenient way by creating the Wget startup
2598 file---@file{.wgetrc}.
2599
2600 Besides @file{.wgetrc} is the ``main'' initialization file, it is
2601 convenient to have a special facility for storing passwords.  Thus Wget
2602 reads and interprets the contents of @file{$HOME/.netrc}, if it finds
2603 it.  You can find @file{.netrc} format in your system manuals.
2604
2605 Wget reads @file{.wgetrc} upon startup, recognizing a limited set of
2606 commands.
2607
2608 @menu
2609 * Wgetrc Location::   Location of various wgetrc files.
2610 * Wgetrc Syntax::     Syntax of wgetrc.
2611 * Wgetrc Commands::   List of available commands.
2612 * Sample Wgetrc::     A wgetrc example.
2613 @end menu
2614
2615 @node Wgetrc Location, Wgetrc Syntax, Startup File, Startup File
2616 @section Wgetrc Location
2617 @cindex wgetrc location
2618 @cindex location of wgetrc
2619
2620 When initializing, Wget will look for a @dfn{global} startup file,
2621 @file{/usr/local/etc/wgetrc} by default (or some prefix other than
2622 @file{/usr/local}, if Wget was not installed there) and read commands
2623 from there, if it exists.
2624
2625 Then it will look for the user's file.  If the environmental variable
2626 @code{WGETRC} is set, Wget will try to load that file.  Failing that, no
2627 further attempts will be made.
2628
2629 If @code{WGETRC} is not set, Wget will try to load @file{$HOME/.wgetrc}.
2630
2631 The fact that user's settings are loaded after the system-wide ones
2632 means that in case of collision user's wgetrc @emph{overrides} the
2633 system-wide wgetrc (in @file{/usr/local/etc/wgetrc} by default).
2634 Fascist admins, away!
2635
2636 @node Wgetrc Syntax, Wgetrc Commands, Wgetrc Location, Startup File
2637 @section Wgetrc Syntax
2638 @cindex wgetrc syntax
2639 @cindex syntax of wgetrc
2640
2641 The syntax of a wgetrc command is simple:
2642
2643 @example
2644 variable = value
2645 @end example
2646
2647 The @dfn{variable} will also be called @dfn{command}.  Valid
2648 @dfn{values} are different for different commands.
2649
2650 The commands are case-insensitive and underscore-insensitive.  Thus
2651 @samp{DIr__PrefiX} is the same as @samp{dirprefix}.  Empty lines, lines
2652 beginning with @samp{#} and lines containing white-space only are
2653 discarded.
2654
2655 Commands that expect a comma-separated list will clear the list on an
2656 empty command.  So, if you wish to reset the rejection list specified in
2657 global @file{wgetrc}, you can do it with:
2658
2659 @example
2660 reject =
2661 @end example
2662
2663 @node Wgetrc Commands, Sample Wgetrc, Wgetrc Syntax, Startup File
2664 @section Wgetrc Commands
2665 @cindex wgetrc commands
2666
2667 The complete set of commands is listed below.  Legal values are listed
2668 after the @samp{=}.  Simple Boolean values can be set or unset using
2669 @samp{on} and @samp{off} or @samp{1} and @samp{0}.
2670
2671 Some commands take pseudo-arbitrary values.  @var{address} values can be
2672 hostnames or dotted-quad IP addresses.  @var{n} can be any positive
2673 integer, or @samp{inf} for infinity, where appropriate.  @var{string}
2674 values can be any non-empty string.
2675
2676 Most of these commands have direct command-line equivalents.  Also, any
2677 wgetrc command can be specified on the command line using the
2678 @samp{--execute} switch (@pxref{Basic Startup Options}.)
2679
2680 @table @asis
2681 @item accept/reject = @var{string}
2682 Same as @samp{-A}/@samp{-R} (@pxref{Types of Files}).
2683
2684 @item add_hostdir = on/off
2685 Enable/disable host-prefixed file names.  @samp{-nH} disables it.
2686
2687 @item ask_password = on/off
2688 Prompt for a password for each connection established. Cannot be specified
2689 when @samp{--password} is being used, because they are mutually
2690 exclusive. Equivalent to @samp{--ask-password}.
2691
2692 @item auth_no_challenge = on/off
2693 If this option is given, Wget will send Basic HTTP authentication
2694 information (plaintext username and password) for all requests. See
2695 @samp{--auth-no-challenge}.
2696
2697 @item background = on/off
2698 Enable/disable going to background---the same as @samp{-b} (which
2699 enables it).
2700
2701 @item backup_converted = on/off
2702 Enable/disable saving pre-converted files with the suffix
2703 @samp{.orig}---the same as @samp{-K} (which enables it).
2704
2705 @c @item backups = @var{number}
2706 @c #### Document me!
2707 @c
2708 @item base = @var{string}
2709 Consider relative @sc{url}s in input files (specified via the
2710 @samp{input} command or the @samp{--input-file}/@samp{-i} option,
2711 together with @samp{force_html} or @samp{--force-html})
2712 as being relative to @var{string}---the same as @samp{--base=@var{string}}.
2713
2714 @item bind_address = @var{address}
2715 Bind to @var{address}, like the @samp{--bind-address=@var{address}}.
2716
2717 @item ca_certificate = @var{file}
2718 Set the certificate authority bundle file to @var{file}.  The same
2719 as @samp{--ca-certificate=@var{file}}.
2720
2721 @item ca_directory = @var{directory}
2722 Set the directory used for certificate authorities.  The same as
2723 @samp{--ca-directory=@var{directory}}.
2724
2725 @item cache = on/off
2726 When set to off, disallow server-caching.  See the @samp{--no-cache}
2727 option.
2728
2729 @item certificate = @var{file}
2730 Set the client certificate file name to @var{file}.  The same as
2731 @samp{--certificate=@var{file}}.
2732
2733 @item certificate_type = @var{string}
2734 Specify the type of the client certificate, legal values being
2735 @samp{PEM} (the default) and @samp{DER} (aka ASN1).  The same as
2736 @samp{--certificate-type=@var{string}}.
2737
2738 @item check_certificate = on/off
2739 If this is set to off, the server certificate is not checked against
2740 the specified client authorities.  The default is ``on''.  The same as
2741 @samp{--check-certificate}.
2742
2743 @item connect_timeout = @var{n}
2744 Set the connect timeout---the same as @samp{--connect-timeout}.
2745
2746 @item content_disposition = on/off
2747 Turn on recognition of the (non-standard) @samp{Content-Disposition}
2748 HTTP header---if set to @samp{on}, the same as @samp{--content-disposition}.
2749
2750 @item continue = on/off
2751 If set to on, force continuation of preexistent partially retrieved
2752 files.  See @samp{-c} before setting it.
2753
2754 @item convert_links = on/off
2755 Convert non-relative links locally.  The same as @samp{-k}.
2756
2757 @item cookies = on/off
2758 When set to off, disallow cookies.  See the @samp{--cookies} option.
2759
2760 @item cut_dirs = @var{n}
2761 Ignore @var{n} remote directory components.  Equivalent to
2762 @samp{--cut-dirs=@var{n}}.
2763
2764 @item debug = on/off
2765 Debug mode, same as @samp{-d}.
2766
2767 @item default_page = @var{string}
2768 Default page name---the same as @samp{--default-page=@var{string}}.
2769
2770 @item delete_after = on/off
2771 Delete after download---the same as @samp{--delete-after}.
2772
2773 @item dir_prefix = @var{string}
2774 Top of directory tree---the same as @samp{-P @var{string}}.
2775
2776 @item dirstruct = on/off
2777 Turning dirstruct on or off---the same as @samp{-x} or @samp{-nd},
2778 respectively.
2779
2780 @item dns_cache = on/off
2781 Turn DNS caching on/off.  Since DNS caching is on by default, this
2782 option is normally used to turn it off and is equivalent to
2783 @samp{--no-dns-cache}.
2784
2785 @item dns_timeout = @var{n}
2786 Set the DNS timeout---the same as @samp{--dns-timeout}.
2787
2788 @item domains = @var{string}
2789 Same as @samp{-D} (@pxref{Spanning Hosts}).
2790
2791 @item dot_bytes = @var{n}
2792 Specify the number of bytes ``contained'' in a dot, as seen throughout
2793 the retrieval (1024 by default).  You can postfix the value with
2794 @samp{k} or @samp{m}, representing kilobytes and megabytes,
2795 respectively.  With dot settings you can tailor the dot retrieval to
2796 suit your needs, or you can use the predefined @dfn{styles}
2797 (@pxref{Download Options}).
2798
2799 @item dot_spacing = @var{n}
2800 Specify the number of dots in a single cluster (10 by default).
2801
2802 @item dots_in_line = @var{n}
2803 Specify the number of dots that will be printed in each line throughout
2804 the retrieval (50 by default).
2805
2806 @item egd_file = @var{file}
2807 Use @var{string} as the EGD socket file name.  The same as
2808 @samp{--egd-file=@var{file}}.
2809
2810 @item exclude_directories = @var{string}
2811 Specify a comma-separated list of directories you wish to exclude from
2812 download---the same as @samp{-X @var{string}} (@pxref{Directory-Based
2813 Limits}).
2814
2815 @item exclude_domains = @var{string}
2816 Same as @samp{--exclude-domains=@var{string}} (@pxref{Spanning
2817 Hosts}).
2818
2819 @item follow_ftp = on/off
2820 Follow @sc{ftp} links from @sc{html} documents---the same as
2821 @samp{--follow-ftp}.
2822
2823 @item follow_tags = @var{string}
2824 Only follow certain @sc{html} tags when doing a recursive retrieval,
2825 just like @samp{--follow-tags=@var{string}}.
2826
2827 @item force_html = on/off
2828 If set to on, force the input filename to be regarded as an @sc{html}
2829 document---the same as @samp{-F}.
2830
2831 @item ftp_password = @var{string}
2832 Set your @sc{ftp} password to @var{string}.  Without this setting, the
2833 password defaults to @samp{-wget@@}, which is a useful default for
2834 anonymous @sc{ftp} access.
2835
2836 This command used to be named @code{passwd} prior to Wget 1.10.
2837
2838 @item ftp_proxy = @var{string}
2839 Use @var{string} as @sc{ftp} proxy, instead of the one specified in
2840 environment.
2841
2842 @item ftp_user = @var{string}
2843 Set @sc{ftp} user to @var{string}.
2844
2845 This command used to be named @code{login} prior to Wget 1.10.
2846
2847 @item glob = on/off
2848 Turn globbing on/off---the same as @samp{--glob} and @samp{--no-glob}.
2849
2850 @item header = @var{string}
2851 Define a header for HTTP downloads, like using
2852 @samp{--header=@var{string}}.
2853
2854 @item adjust_extension = on/off
2855 Add a @samp{.html} extension to @samp{text/html} or
2856 @samp{application/xhtml+xml} files that lack one, or a @samp{.css}
2857 extension to @samp{text/css} files that lack one, like
2858 @samp{-E}. Previously named @samp{html_extension} (still acceptable,
2859 but deprecated).
2860
2861 @item http_keep_alive = on/off
2862 Turn the keep-alive feature on or off (defaults to on).  Turning it
2863 off is equivalent to @samp{--no-http-keep-alive}.
2864
2865 @item http_password = @var{string}
2866 Set @sc{http} password, equivalent to
2867 @samp{--http-password=@var{string}}.
2868
2869 @item http_proxy = @var{string}
2870 Use @var{string} as @sc{http} proxy, instead of the one specified in
2871 environment.
2872
2873 @item http_user = @var{string}
2874 Set @sc{http} user to @var{string}, equivalent to
2875 @samp{--http-user=@var{string}}.
2876
2877 @item https_proxy = @var{string}
2878 Use @var{string} as @sc{https} proxy, instead of the one specified in
2879 environment.
2880
2881 @item ignore_case = on/off
2882 When set to on, match files and directories case insensitively; the
2883 same as @samp{--ignore-case}.
2884
2885 @item ignore_length = on/off
2886 When set to on, ignore @code{Content-Length} header; the same as
2887 @samp{--ignore-length}.
2888
2889 @item ignore_tags = @var{string}
2890 Ignore certain @sc{html} tags when doing a recursive retrieval, like
2891 @samp{--ignore-tags=@var{string}}.
2892
2893 @item include_directories = @var{string}
2894 Specify a comma-separated list of directories you wish to follow when
2895 downloading---the same as @samp{-I @var{string}}.
2896
2897 @item iri = on/off
2898 When set to on, enable internationalized URI (IRI) support; the same as
2899 @samp{--iri}.
2900
2901 @item inet4_only = on/off
2902 Force connecting to IPv4 addresses, off by default.  You can put this
2903 in the global init file to disable Wget's attempts to resolve and
2904 connect to IPv6 hosts.  Available only if Wget was compiled with IPv6
2905 support.  The same as @samp{--inet4-only} or @samp{-4}.
2906
2907 @item inet6_only = on/off
2908 Force connecting to IPv6 addresses, off by default.  Available only if
2909 Wget was compiled with IPv6 support.  The same as @samp{--inet6-only}
2910 or @samp{-6}.
2911
2912 @item input = @var{file}
2913 Read the @sc{url}s from @var{string}, like @samp{-i @var{file}}.
2914
2915 @item keep_session_cookies = on/off
2916 When specified, causes @samp{save_cookies = on} to also save session
2917 cookies.  See @samp{--keep-session-cookies}.
2918
2919 @item limit_rate = @var{rate}
2920 Limit the download speed to no more than @var{rate} bytes per second.
2921 The same as @samp{--limit-rate=@var{rate}}.
2922
2923 @item load_cookies = @var{file}
2924 Load cookies from @var{file}.  See @samp{--load-cookies @var{file}}.
2925
2926 @item local_encoding = @var{encoding}
2927 Force Wget to use @var{encoding} as the default system encoding. See
2928 @samp{--local-encoding}.
2929
2930 @item logfile = @var{file}
2931 Set logfile to @var{file}, the same as @samp{-o @var{file}}.
2932
2933 @item max_redirect = @var{number}
2934 Specifies the maximum number of redirections to follow for a resource.
2935 See @samp{--max-redirect=@var{number}}.
2936
2937 @item mirror = on/off
2938 Turn mirroring on/off.  The same as @samp{-m}.
2939
2940 @item netrc = on/off
2941 Turn reading netrc on or off.
2942
2943 @item no_clobber = on/off
2944 Same as @samp{-nc}.
2945
2946 @item no_parent = on/off
2947 Disallow retrieving outside the directory hierarchy, like
2948 @samp{--no-parent} (@pxref{Directory-Based Limits}).
2949
2950 @item no_proxy = @var{string}
2951 Use @var{string} as the comma-separated list of domains to avoid in
2952 proxy loading, instead of the one specified in environment.
2953
2954 @item output_document = @var{file}
2955 Set the output filename---the same as @samp{-O @var{file}}.
2956
2957 @item page_requisites = on/off
2958 Download all ancillary documents necessary for a single @sc{html} page to
2959 display properly---the same as @samp{-p}.
2960
2961 @item passive_ftp = on/off
2962 Change setting of passive @sc{ftp}, equivalent to the
2963 @samp{--passive-ftp} option.
2964
2965 @itemx password = @var{string}
2966 Specify password @var{string} for both @sc{ftp} and @sc{http} file retrieval. 
2967 This command can be overridden using the @samp{ftp_password} and 
2968 @samp{http_password} command for @sc{ftp} and @sc{http} respectively.
2969
2970 @item post_data = @var{string}
2971 Use POST as the method for all HTTP requests and send @var{string} in
2972 the request body.  The same as @samp{--post-data=@var{string}}.
2973
2974 @item post_file = @var{file}
2975 Use POST as the method for all HTTP requests and send the contents of
2976 @var{file} in the request body.  The same as
2977 @samp{--post-file=@var{file}}.
2978
2979 @item prefer_family = none/IPv4/IPv6
2980 When given a choice of several addresses, connect to the addresses
2981 with specified address family first.  The address order returned by
2982 DNS is used without change by default.  The same as @samp{--prefer-family},
2983 which see for a detailed discussion of why this is useful.
2984
2985 @item private_key = @var{file}
2986 Set the private key file to @var{file}.  The same as
2987 @samp{--private-key=@var{file}}.
2988
2989 @item private_key_type = @var{string}
2990 Specify the type of the private key, legal values being @samp{PEM}
2991 (the default) and @samp{DER} (aka ASN1).  The same as
2992 @samp{--private-type=@var{string}}.
2993
2994 @item progress = @var{string}
2995 Set the type of the progress indicator.  Legal types are @samp{dot}
2996 and @samp{bar}.  Equivalent to @samp{--progress=@var{string}}.
2997
2998 @item protocol_directories = on/off
2999 When set, use the protocol name as a directory component of local file
3000 names.  The same as @samp{--protocol-directories}.
3001
3002 @item proxy_password = @var{string}
3003 Set proxy authentication password to @var{string}, like
3004 @samp{--proxy-password=@var{string}}.
3005
3006 @item proxy_user = @var{string}
3007 Set proxy authentication user name to @var{string}, like
3008 @samp{--proxy-user=@var{string}}.
3009
3010 @item quiet = on/off
3011 Quiet mode---the same as @samp{-q}.
3012
3013 @item quota = @var{quota}
3014 Specify the download quota, which is useful to put in the global
3015 @file{wgetrc}.  When download quota is specified, Wget will stop
3016 retrieving after the download sum has become greater than quota.  The
3017 quota can be specified in bytes (default), kbytes @samp{k} appended) or
3018 mbytes (@samp{m} appended).  Thus @samp{quota = 5m} will set the quota
3019 to 5 megabytes.  Note that the user's startup file overrides system
3020 settings.
3021
3022 @item random_file = @var{file}
3023 Use @var{file} as a source of randomness on systems lacking
3024 @file{/dev/random}.
3025
3026 @item random_wait = on/off
3027 Turn random between-request wait times on or off. The same as 
3028 @samp{--random-wait}.
3029
3030 @item read_timeout = @var{n}
3031 Set the read (and write) timeout---the same as
3032 @samp{--read-timeout=@var{n}}.
3033
3034 @item reclevel = @var{n}
3035 Recursion level (depth)---the same as @samp{-l @var{n}}.
3036
3037 @item recursive = on/off
3038 Recursive on/off---the same as @samp{-r}.
3039
3040 @item referer = @var{string}
3041 Set HTTP @samp{Referer:} header just like
3042 @samp{--referer=@var{string}}.  (Note that it was the folks who wrote
3043 the @sc{http} spec who got the spelling of ``referrer'' wrong.)
3044
3045 @item relative_only = on/off
3046 Follow only relative links---the same as @samp{-L} (@pxref{Relative
3047 Links}).
3048
3049 @item remote_encoding = @var{encoding}
3050 Force Wget to use @var{encoding} as the default remote server encoding.
3051 See @samp{--remote-encoding}.
3052
3053 @item remove_listing = on/off
3054 If set to on, remove @sc{ftp} listings downloaded by Wget.  Setting it
3055 to off is the same as @samp{--no-remove-listing}.
3056
3057 @item restrict_file_names = unix/windows
3058 Restrict the file names generated by Wget from URLs.  See
3059 @samp{--restrict-file-names} for a more detailed description.
3060
3061 @item retr_symlinks = on/off
3062 When set to on, retrieve symbolic links as if they were plain files; the
3063 same as @samp{--retr-symlinks}.
3064
3065 @item retry_connrefused = on/off
3066 When set to on, consider ``connection refused'' a transient
3067 error---the same as @samp{--retry-connrefused}.
3068
3069 @item robots = on/off
3070 Specify whether the norobots convention is respected by Wget, ``on'' by
3071 default.  This switch controls both the @file{/robots.txt} and the
3072 @samp{nofollow} aspect of the spec.  @xref{Robot Exclusion}, for more
3073 details about this.  Be sure you know what you are doing before turning
3074 this off.
3075
3076 @item save_cookies = @var{file}
3077 Save cookies to @var{file}.  The same as @samp{--save-cookies
3078 @var{file}}.
3079
3080 @item save_headers = on/off
3081 Same as @samp{--save-headers}.
3082
3083 @item secure_protocol = @var{string}
3084 Choose the secure protocol to be used.  Legal values are @samp{auto}
3085 (the default), @samp{SSLv2}, @samp{SSLv3}, and @samp{TLSv1}.  The same
3086 as @samp{--secure-protocol=@var{string}}.
3087
3088 @item server_response = on/off
3089 Choose whether or not to print the @sc{http} and @sc{ftp} server
3090 responses---the same as @samp{-S}.
3091
3092 @item span_hosts = on/off
3093 Same as @samp{-H}.
3094
3095 @item spider = on/off
3096 Same as @samp{--spider}.
3097
3098 @item strict_comments = on/off
3099 Same as @samp{--strict-comments}.
3100
3101 @item timeout = @var{n}
3102 Set all applicable timeout values to @var{n}, the same as @samp{-T
3103 @var{n}}.
3104
3105 @item timestamping = on/off
3106 Turn timestamping on/off.  The same as @samp{-N} (@pxref{Time-Stamping}).
3107
3108 @item tries = @var{n}
3109 Set number of retries per @sc{url}---the same as @samp{-t @var{n}}.
3110
3111 @item use_proxy = on/off
3112 When set to off, don't use proxy even when proxy-related environment
3113 variables are set.  In that case it is the same as using
3114 @samp{--no-proxy}.
3115
3116 @item user = @var{string}
3117 Specify username @var{string} for both @sc{ftp} and @sc{http} file retrieval. 
3118 This command can be overridden using the @samp{ftp_user} and 
3119 @samp{http_user} command for @sc{ftp} and @sc{http} respectively.
3120
3121 @item user_agent = @var{string}
3122 User agent identification sent to the HTTP Server---the same as
3123 @samp{--user-agent=@var{string}}.
3124
3125 @item verbose = on/off
3126 Turn verbose on/off---the same as @samp{-v}/@samp{-nv}.
3127
3128 @item wait = @var{n}
3129 Wait @var{n} seconds between retrievals---the same as @samp{-w
3130 @var{n}}.
3131
3132 @item wait_retry = @var{n}
3133 Wait up to @var{n} seconds between retries of failed retrievals
3134 only---the same as @samp{--waitretry=@var{n}}.  Note that this is
3135 turned on by default in the global @file{wgetrc}.
3136 @end table
3137
3138 @node Sample Wgetrc,  , Wgetrc Commands, Startup File
3139 @section Sample Wgetrc
3140 @cindex sample wgetrc
3141
3142 This is the sample initialization file, as given in the distribution.
3143 It is divided in two section---one for global usage (suitable for global
3144 startup file), and one for local usage (suitable for
3145 @file{$HOME/.wgetrc}).  Be careful about the things you change.
3146
3147 Note that almost all the lines are commented out.  For a command to have
3148 any effect, you must remove the @samp{#} character at the beginning of
3149 its line.
3150
3151 @example
3152 @include sample.wgetrc.munged_for_texi_inclusion
3153 @end example
3154
3155 @node Examples, Various, Startup File, Top
3156 @chapter Examples
3157 @cindex examples
3158
3159 @c man begin EXAMPLES
3160 The examples are divided into three sections loosely based on their
3161 complexity.
3162
3163 @menu
3164 * Simple Usage::         Simple, basic usage of the program.
3165 * Advanced Usage::       Advanced tips.
3166 * Very Advanced Usage::  The hairy stuff.
3167 @end menu
3168
3169 @node Simple Usage, Advanced Usage, Examples, Examples
3170 @section Simple Usage
3171
3172 @itemize @bullet
3173 @item
3174 Say you want to download a @sc{url}.  Just type:
3175
3176 @example
3177 wget http://fly.srk.fer.hr/
3178 @end example
3179
3180 @item
3181 But what will happen if the connection is slow, and the file is lengthy?
3182 The connection will probably fail before the whole file is retrieved,
3183 more than once.  In this case, Wget will try getting the file until it
3184 either gets the whole of it, or exceeds the default number of retries
3185 (this being 20).  It is easy to change the number of tries to 45, to
3186 insure that the whole file will arrive safely:
3187
3188 @example
3189 wget --tries=45 http://fly.srk.fer.hr/jpg/flyweb.jpg
3190 @end example
3191
3192 @item
3193 Now let's leave Wget to work in the background, and write its progress
3194 to log file @file{log}.  It is tiring to type @samp{--tries}, so we
3195 shall use @samp{-t}.
3196
3197 @example
3198 wget -t 45 -o log http://fly.srk.fer.hr/jpg/flyweb.jpg &
3199 @end example
3200
3201 The ampersand at the end of the line makes sure that Wget works in the
3202 background.  To unlimit the number of retries, use @samp{-t inf}.
3203
3204 @item
3205 The usage of @sc{ftp} is as simple.  Wget will take care of login and
3206 password.
3207
3208 @example
3209 wget ftp://gnjilux.srk.fer.hr/welcome.msg
3210 @end example
3211
3212 @item
3213 If you specify a directory, Wget will retrieve the directory listing,
3214 parse it and convert it to @sc{html}.  Try:
3215
3216 @example
3217 wget ftp://ftp.gnu.org/pub/gnu/
3218 links index.html
3219 @end example
3220 @end itemize
3221
3222 @node Advanced Usage, Very Advanced Usage, Simple Usage, Examples
3223 @section Advanced Usage
3224
3225 @itemize @bullet
3226 @item
3227 You have a file that contains the URLs you want to download?  Use the
3228 @samp{-i} switch:
3229
3230 @example
3231 wget -i @var{file}
3232 @end example
3233
3234 If you specify @samp{-} as file name, the @sc{url}s will be read from
3235 standard input.
3236
3237 @item
3238 Create a five levels deep mirror image of the GNU web site, with the
3239 same directory structure the original has, with only one try per
3240 document, saving the log of the activities to @file{gnulog}:
3241
3242 @example
3243 wget -r http://www.gnu.org/ -o gnulog
3244 @end example
3245
3246 @item
3247 The same as the above, but convert the links in the downloaded files to
3248 point to local files, so you can view the documents off-line:
3249
3250 @example
3251 wget --convert-links -r http://www.gnu.org/ -o gnulog
3252 @end example
3253
3254 @item
3255 Retrieve only one @sc{html} page, but make sure that all the elements needed
3256 for the page to be displayed, such as inline images and external style
3257 sheets, are also downloaded.  Also make sure the downloaded page
3258 references the downloaded links.
3259
3260 @example
3261 wget -p --convert-links http://www.server.com/dir/page.html
3262 @end example
3263
3264 The @sc{html} page will be saved to @file{www.server.com/dir/page.html}, and
3265 the images, stylesheets, etc., somewhere under @file{www.server.com/},
3266 depending on where they were on the remote server.
3267
3268 @item
3269 The same as the above, but without the @file{www.server.com/} directory.
3270 In fact, I don't want to have all those random server directories
3271 anyway---just save @emph{all} those files under a @file{download/}
3272 subdirectory of the current directory.
3273
3274 @example
3275 wget -p --convert-links -nH -nd -Pdownload \
3276      http://www.server.com/dir/page.html
3277 @end example
3278
3279 @item
3280 Retrieve the index.html of @samp{www.lycos.com}, showing the original
3281 server headers:
3282
3283 @example
3284 wget -S http://www.lycos.com/
3285 @end example
3286
3287 @item
3288 Save the server headers with the file, perhaps for post-processing.
3289
3290 @example
3291 wget --save-headers http://www.lycos.com/
3292 more index.html
3293 @end example
3294
3295 @item
3296 Retrieve the first two levels of @samp{wuarchive.wustl.edu}, saving them
3297 to @file{/tmp}.
3298
3299 @example
3300 wget -r -l2 -P/tmp ftp://wuarchive.wustl.edu/
3301 @end example
3302
3303 @item
3304 You want to download all the @sc{gif}s from a directory on an @sc{http}
3305 server.  You tried @samp{wget http://www.server.com/dir/*.gif}, but that
3306 didn't work because @sc{http} retrieval does not support globbing.  In
3307 that case, use:
3308
3309 @example
3310 wget -r -l1 --no-parent -A.gif http://www.server.com/dir/
3311 @end example
3312
3313 More verbose, but the effect is the same.  @samp{-r -l1} means to
3314 retrieve recursively (@pxref{Recursive Download}), with maximum depth
3315 of 1.  @samp{--no-parent} means that references to the parent directory
3316 are ignored (@pxref{Directory-Based Limits}), and @samp{-A.gif} means to
3317 download only the @sc{gif} files.  @samp{-A "*.gif"} would have worked
3318 too.
3319
3320 @item
3321 Suppose you were in the middle of downloading, when Wget was
3322 interrupted.  Now you do not want to clobber the files already present.
3323 It would be:
3324
3325 @example
3326 wget -nc -r http://www.gnu.org/
3327 @end example
3328
3329 @item
3330 If you want to encode your own username and password to @sc{http} or
3331 @sc{ftp}, use the appropriate @sc{url} syntax (@pxref{URL Format}).
3332
3333 @example
3334 wget ftp://hniksic:mypassword@@unix.server.com/.emacs
3335 @end example
3336
3337 Note, however, that this usage is not advisable on multi-user systems
3338 because it reveals your password to anyone who looks at the output of
3339 @code{ps}.
3340
3341 @cindex redirecting output
3342 @item
3343 You would like the output documents to go to standard output instead of
3344 to files?
3345
3346 @example
3347 wget -O - http://jagor.srce.hr/ http://www.srce.hr/
3348 @end example
3349
3350 You can also combine the two options and make pipelines to retrieve the
3351 documents from remote hotlists:
3352
3353 @example
3354 wget -O - http://cool.list.com/ | wget --force-html -i -
3355 @end example
3356 @end itemize
3357
3358 @node Very Advanced Usage,  , Advanced Usage, Examples
3359 @section Very Advanced Usage
3360
3361 @cindex mirroring
3362 @itemize @bullet
3363 @item
3364 If you wish Wget to keep a mirror of a page (or @sc{ftp}
3365 subdirectories), use @samp{--mirror} (@samp{-m}), which is the shorthand
3366 for @samp{-r -l inf -N}.  You can put Wget in the crontab file asking it
3367 to recheck a site each Sunday:
3368
3369 @example
3370 crontab
3371 0 0 * * 0 wget --mirror http://www.gnu.org/ -o /home/me/weeklog
3372 @end example
3373
3374 @item
3375 In addition to the above, you want the links to be converted for local
3376 viewing.  But, after having read this manual, you know that link
3377 conversion doesn't play well with timestamping, so you also want Wget to
3378 back up the original @sc{html} files before the conversion.  Wget invocation
3379 would look like this:
3380
3381 @example
3382 wget --mirror --convert-links --backup-converted  \
3383      http://www.gnu.org/ -o /home/me/weeklog
3384 @end example
3385
3386 @item
3387 But you've also noticed that local viewing doesn't work all that well
3388 when @sc{html} files are saved under extensions other than @samp{.html},
3389 perhaps because they were served as @file{index.cgi}.  So you'd like
3390 Wget to rename all the files served with content-type @samp{text/html}
3391 or @samp{application/xhtml+xml} to @file{@var{name}.html}.
3392
3393 @example
3394 wget --mirror --convert-links --backup-converted \
3395      --html-extension -o /home/me/weeklog        \
3396      http://www.gnu.org/
3397 @end example
3398
3399 Or, with less typing:
3400
3401 @example
3402 wget -m -k -K -E http://www.gnu.org/ -o /home/me/weeklog
3403 @end example
3404 @end itemize
3405 @c man end
3406
3407 @node Various, Appendices, Examples, Top
3408 @chapter Various
3409 @cindex various
3410
3411 This chapter contains all the stuff that could not fit anywhere else.
3412
3413 @menu
3414 * Proxies::             Support for proxy servers.
3415 * Distribution::        Getting the latest version.
3416 * Web Site::            GNU Wget's presence on the World Wide Web.
3417 * Mailing Lists::       Wget mailing list for announcements and discussion.
3418 * Internet Relay Chat:: Wget's presence on IRC.
3419 * Reporting Bugs::      How and where to report bugs.
3420 * Portability::         The systems Wget works on.
3421 * Signals::             Signal-handling performed by Wget.
3422 @end menu
3423
3424 @node Proxies, Distribution, Various, Various
3425 @section Proxies
3426 @cindex proxies
3427
3428 @dfn{Proxies} are special-purpose @sc{http} servers designed to transfer
3429 data from remote servers to local clients.  One typical use of proxies
3430 is lightening network load for users behind a slow connection.  This is
3431 achieved by channeling all @sc{http} and @sc{ftp} requests through the
3432 proxy which caches the transferred data.  When a cached resource is
3433 requested again, proxy will return the data from cache.  Another use for
3434 proxies is for companies that separate (for security reasons) their
3435 internal networks from the rest of Internet.  In order to obtain
3436 information from the Web, their users connect and retrieve remote data
3437 using an authorized proxy.
3438
3439 Wget supports proxies for both @sc{http} and @sc{ftp} retrievals.  The
3440 standard way to specify proxy location, which Wget recognizes, is using
3441 the following environment variables:
3442
3443 @table @code
3444 @item http_proxy
3445 @itemx https_proxy
3446 If set, the @code{http_proxy} and @code{https_proxy} variables should
3447 contain the @sc{url}s of the proxies for @sc{http} and @sc{https}
3448 connections respectively.
3449
3450 @item ftp_proxy
3451 This variable should contain the @sc{url} of the proxy for @sc{ftp}
3452 connections.  It is quite common that @code{http_proxy} and
3453 @code{ftp_proxy} are set to the same @sc{url}.
3454
3455 @item no_proxy
3456 This variable should contain a comma-separated list of domain extensions
3457 proxy should @emph{not} be used for.  For instance, if the value of
3458 @code{no_proxy} is @samp{.mit.edu}, proxy will not be used to retrieve
3459 documents from MIT.
3460 @end table
3461
3462 In addition to the environment variables, proxy location and settings
3463 may be specified from within Wget itself.
3464
3465 @table @samp
3466 @itemx --no-proxy
3467 @itemx proxy = on/off
3468 This option and the corresponding command may be used to suppress the
3469 use of proxy, even if the appropriate environment variables are set.
3470
3471 @item http_proxy = @var{URL}
3472 @itemx https_proxy = @var{URL}
3473 @itemx ftp_proxy = @var{URL}
3474 @itemx no_proxy = @var{string}
3475 These startup file variables allow you to override the proxy settings
3476 specified by the environment.
3477 @end table
3478
3479 Some proxy servers require authorization to enable you to use them.  The
3480 authorization consists of @dfn{username} and @dfn{password}, which must
3481 be sent by Wget.  As with @sc{http} authorization, several
3482 authentication schemes exist.  For proxy authorization only the
3483 @code{Basic} authentication scheme is currently implemented.
3484
3485 You may specify your username and password either through the proxy
3486 @sc{url} or through the command-line options.  Assuming that the
3487 company's proxy is located at @samp{proxy.company.com} at port 8001, a
3488 proxy @sc{url} location containing authorization data might look like
3489 this:
3490
3491 @example
3492 http://hniksic:mypassword@@proxy.company.com:8001/
3493 @end example
3494
3495 Alternatively, you may use the @samp{proxy-user} and
3496 @samp{proxy-password} options, and the equivalent @file{.wgetrc}
3497 settings @code{proxy_user} and @code{proxy_password} to set the proxy
3498 username and password.
3499
3500 @node Distribution, Web Site, Proxies, Various
3501 @section Distribution
3502 @cindex latest version
3503
3504 Like all GNU utilities, the latest version of Wget can be found at the
3505 master GNU archive site ftp.gnu.org, and its mirrors.  For example,
3506 Wget @value{VERSION} can be found at
3507 @url{ftp://ftp.gnu.org/pub/gnu/wget/wget-@value{VERSION}.tar.gz}
3508
3509 @node Web Site, Mailing Lists, Distribution, Various
3510 @section Web Site
3511 @cindex web site
3512
3513 The official web site for GNU Wget is at
3514 @url{http://www.gnu.org/software/wget/}. However, most useful
3515 information resides at ``The Wget Wgiki'',
3516 @url{http://wget.addictivecode.org/}.
3517
3518 @node Mailing Lists, Internet Relay Chat, Web Site, Various
3519 @section Mailing Lists
3520 @cindex mailing list
3521 @cindex list
3522
3523 @unnumberedsubsec Primary List
3524
3525 The primary mailinglist for discussion, bug-reports, or questions
3526 about GNU Wget is at @email{bug-wget@@gnu.org}. To subscribe, send an
3527 email to @email{bug-wget-join@@gnu.org}, or visit
3528 @url{http://lists.gnu.org/mailman/listinfo/bug-wget}.
3529
3530 You do not need to subscribe to send a message to the list; however,
3531 please note that unsubscribed messages are moderated, and may take a
3532 while before they hit the list---@strong{usually around a day}.  If
3533 you want your message to show up immediately, please subscribe to the
3534 list before posting. Archives for the list may be found at
3535 @url{http://lists.gnu.org/pipermail/bug-wget/}.
3536
3537 An NNTP/Usenettish gateway is also available via
3538 @uref{http://gmane.org/about.php,Gmane}. You can see the Gmane
3539 archives at
3540 @url{http://news.gmane.org/gmane.comp.web.wget.general}. Note that the
3541 Gmane archives conveniently include messages from both the current
3542 list, and the previous one. Messages also show up in the Gmane
3543 archives sooner than they do at @url{lists.gnu.org}.
3544
3545 @unnumberedsubsec Bug Notices List
3546
3547 Additionally, there is the @email{wget-notify@@addictivecode.org} mailing
3548 list. This is a non-discussion list that receives bug report
3549 notifications from the bug-tracker. To subscribe to this list,
3550 send an email to @email{wget-notify-join@@addictivecode.org},
3551 or visit @url{http://addictivecode.org/mailman/listinfo/wget-notify}.
3552
3553 @unnumberedsubsec Obsolete Lists
3554
3555 Previously, the mailing list @email{wget@@sunsite.dk} was used as the
3556 main discussion list, and another list,
3557 @email{wget-patches@@sunsite.dk} was used for submitting and
3558 discussing patches to GNU Wget.
3559
3560 Messages from @email{wget@@sunsite.dk} are archived at
3561 @itemize @tie{}
3562 @item
3563 @url{http://www.mail-archive.com/wget%40sunsite.dk/} and at
3564 @item
3565 @url{http://news.gmane.org/gmane.comp.web.wget.general} (which also
3566 continues to archive the current list, @email{bug-wget@@gnu.org}).
3567 @end itemize
3568
3569 Messages from @email{wget-patches@@sunsite.dk} are archived at
3570 @itemize @tie{}
3571 @item
3572 @url{http://news.gmane.org/gmane.comp.web.wget.patches}.
3573 @end itemize
3574
3575 @node Internet Relay Chat, Reporting Bugs, Mailing Lists, Various
3576 @section Internet Relay Chat
3577 @cindex Internet Relay Chat
3578 @cindex IRC
3579 @cindex #wget
3580
3581 In addition to the mailinglists, we also have a support channel set up
3582 via IRC at @code{irc.freenode.org}, @code{#wget}. Come check it out!
3583
3584 @node Reporting Bugs, Portability, Internet Relay Chat, Various
3585 @section Reporting Bugs
3586 @cindex bugs
3587 @cindex reporting bugs
3588 @cindex bug reports
3589
3590 @c man begin BUGS
3591 You are welcome to submit bug reports via the GNU Wget bug tracker (see
3592 @url{http://wget.addictivecode.org/BugTracker}).
3593
3594 Before actually submitting a bug report, please try to follow a few
3595 simple guidelines.
3596
3597 @enumerate
3598 @item
3599 Please try to ascertain that the behavior you see really is a bug.  If
3600 Wget crashes, it's a bug.  If Wget does not behave as documented,
3601 it's a bug.  If things work strange, but you are not sure about the way
3602 they are supposed to work, it might well be a bug, but you might want to
3603 double-check the documentation and the mailing lists (@pxref{Mailing
3604 Lists}).
3605
3606 @item
3607 Try to repeat the bug in as simple circumstances as possible.  E.g. if
3608 Wget crashes while downloading @samp{wget -rl0 -kKE -t5 --no-proxy
3609 http://yoyodyne.com -o /tmp/log}, you should try to see if the crash is
3610 repeatable, and if will occur with a simpler set of options.  You might
3611 even try to start the download at the page where the crash occurred to
3612 see if that page somehow triggered the crash.
3613
3614 Also, while I will probably be interested to know the contents of your
3615 @file{.wgetrc} file, just dumping it into the debug message is probably
3616 a bad idea.  Instead, you should first try to see if the bug repeats
3617 with @file{.wgetrc} moved out of the way.  Only if it turns out that
3618 @file{.wgetrc} settings affect the bug, mail me the relevant parts of
3619 the file.
3620
3621 @item
3622 Please start Wget with @samp{-d} option and send us the resulting
3623 output (or relevant parts thereof).  If Wget was compiled without
3624 debug support, recompile it---it is @emph{much} easier to trace bugs
3625 with debug support on.
3626
3627 Note: please make sure to remove any potentially sensitive information
3628 from the debug log before sending it to the bug address.  The
3629 @code{-d} won't go out of its way to collect sensitive information,
3630 but the log @emph{will} contain a fairly complete transcript of Wget's
3631 communication with the server, which may include passwords and pieces
3632 of downloaded data.  Since the bug address is publically archived, you
3633 may assume that all bug reports are visible to the public.
3634
3635 @item
3636 If Wget has crashed, try to run it in a debugger, e.g. @code{gdb `which
3637 wget` core} and type @code{where} to get the backtrace.  This may not
3638 work if the system administrator has disabled core files, but it is
3639 safe to try.
3640 @end enumerate
3641 @c man end
3642
3643 @node Portability, Signals, Reporting Bugs, Various
3644 @section Portability
3645 @cindex portability
3646 @cindex operating systems
3647
3648 Like all GNU software, Wget works on the GNU system.  However, since it
3649 uses GNU Autoconf for building and configuring, and mostly avoids using
3650 ``special'' features of any particular Unix, it should compile (and
3651 work) on all common Unix flavors.
3652
3653 Various Wget versions have been compiled and tested under many kinds of
3654 Unix systems, including GNU/Linux, Solaris, SunOS 4.x, Mac OS X, OSF
3655 (aka Digital Unix or Tru64), Ultrix, *BSD, IRIX, AIX, and others.  Some
3656 of those systems are no longer in widespread use and may not be able to
3657 support recent versions of Wget.  If Wget fails to compile on your
3658 system, we would like to know about it.
3659
3660 Thanks to kind contributors, this version of Wget compiles and works
3661 on 32-bit Microsoft Windows platforms.  It has been compiled
3662 successfully using MS Visual C++ 6.0, Watcom, Borland C, and GCC
3663 compilers.  Naturally, it is crippled of some features available on
3664 Unix, but it should work as a substitute for people stuck with
3665 Windows.  Note that Windows-specific portions of Wget are not
3666 guaranteed to be supported in the future, although this has been the
3667 case in practice for many years now.  All questions and problems in
3668 Windows usage should be reported to Wget mailing list at
3669 @email{wget@@sunsite.dk} where the volunteers who maintain the
3670 Windows-related features might look at them.
3671
3672 Support for building on MS-DOS via DJGPP has been contributed by Gisle
3673 Vanem; a port to VMS is maintained by Steven Schweda, and is available
3674 at @url{http://antinode.org/}.
3675
3676 @node Signals,  , Portability, Various
3677 @section Signals
3678 @cindex signal handling
3679 @cindex hangup
3680
3681 Since the purpose of Wget is background work, it catches the hangup
3682 signal (@code{SIGHUP}) and ignores it.  If the output was on standard
3683 output, it will be redirected to a file named @file{wget-log}.
3684 Otherwise, @code{SIGHUP} is ignored.  This is convenient when you wish
3685 to redirect the output of Wget after having started it.
3686
3687 @example
3688 $ wget http://www.gnus.org/dist/gnus.tar.gz &
3689 ...
3690 $ kill -HUP %%
3691 SIGHUP received, redirecting output to `wget-log'.
3692 @end example
3693
3694 Other than that, Wget will not try to interfere with signals in any way.
3695 @kbd{C-c}, @code{kill -TERM} and @code{kill -KILL} should kill it alike.
3696
3697 @node Appendices, Copying this manual, Various, Top
3698 @chapter Appendices
3699
3700 This chapter contains some references I consider useful.
3701
3702 @menu
3703 * Robot Exclusion::         Wget's support for RES.
3704 * Security Considerations:: Security with Wget.
3705 * Contributors::            People who helped.
3706 @end menu
3707
3708 @node Robot Exclusion, Security Considerations, Appendices, Appendices
3709 @section Robot Exclusion
3710 @cindex robot exclusion
3711 @cindex robots.txt
3712 @cindex server maintenance
3713
3714 It is extremely easy to make Wget wander aimlessly around a web site,
3715 sucking all the available data in progress.  @samp{wget -r @var{site}},
3716 and you're set.  Great?  Not for the server admin.
3717
3718 As long as Wget is only retrieving static pages, and doing it at a
3719 reasonable rate (see the @samp{--wait} option), there's not much of a
3720 problem.  The trouble is that Wget can't tell the difference between the
3721 smallest static page and the most demanding CGI.  A site I know has a
3722 section handled by a CGI Perl script that converts Info files to @sc{html} on
3723 the fly.  The script is slow, but works well enough for human users
3724 viewing an occasional Info file.  However, when someone's recursive Wget
3725 download stumbles upon the index page that links to all the Info files
3726 through the script, the system is brought to its knees without providing
3727 anything useful to the user (This task of converting Info files could be
3728 done locally and access to Info documentation for all installed GNU
3729 software on a system is available from the @code{info} command).
3730
3731 To avoid this kind of accident, as well as to preserve privacy for
3732 documents that need to be protected from well-behaved robots, the
3733 concept of @dfn{robot exclusion} was invented.  The idea is that
3734 the server administrators and document authors can specify which
3735 portions of the site they wish to protect from robots and those
3736 they will permit access.
3737
3738 The most popular mechanism, and the @i{de facto} standard supported by
3739 all the major robots, is the ``Robots Exclusion Standard'' (RES) written
3740 by Martijn Koster et al. in 1994.  It specifies the format of a text
3741 file containing directives that instruct the robots which URL paths to
3742 avoid.  To be found by the robots, the specifications must be placed in
3743 @file{/robots.txt} in the server root, which the robots are expected to
3744 download and parse.
3745
3746 Although Wget is not a web robot in the strictest sense of the word, it
3747 can download large parts of the site without the user's intervention to
3748 download an individual page.  Because of that, Wget honors RES when
3749 downloading recursively.  For instance, when you issue:
3750
3751 @example
3752 wget -r http://www.server.com/
3753 @end example
3754
3755 First the index of @samp{www.server.com} will be downloaded.  If Wget
3756 finds that it wants to download more documents from that server, it will
3757 request @samp{http://www.server.com/robots.txt} and, if found, use it
3758 for further downloads.  @file{robots.txt} is loaded only once per each
3759 server.
3760
3761 Until version 1.8, Wget supported the first version of the standard,
3762 written by Martijn Koster in 1994 and available at
3763 @url{http://www.robotstxt.org/wc/norobots.html}.  As of version 1.8,
3764 Wget has supported the additional directives specified in the internet
3765 draft @samp{<draft-koster-robots-00.txt>} titled ``A Method for Web
3766 Robots Control''.  The draft, which has as far as I know never made to
3767 an @sc{rfc}, is available at
3768 @url{http://www.robotstxt.org/wc/norobots-rfc.txt}.
3769
3770 This manual no longer includes the text of the Robot Exclusion Standard.
3771
3772 The second, less known mechanism, enables the author of an individual
3773 document to specify whether they want the links from the file to be
3774 followed by a robot.  This is achieved using the @code{META} tag, like
3775 this:
3776
3777 @example
3778 <meta name="robots" content="nofollow">
3779 @end example
3780
3781 This is explained in some detail at
3782 @url{http://www.robotstxt.org/wc/meta-user.html}.  Wget supports this
3783 method of robot exclusion in addition to the usual @file{/robots.txt}
3784 exclusion.
3785
3786 If you know what you are doing and really really wish to turn off the
3787 robot exclusion, set the @code{robots} variable to @samp{off} in your
3788 @file{.wgetrc}.  You can achieve the same effect from the command line
3789 using the @code{-e} switch, e.g. @samp{wget -e robots=off @var{url}...}.
3790
3791 @node Security Considerations, Contributors, Robot Exclusion, Appendices
3792 @section Security Considerations
3793 @cindex security
3794
3795 When using Wget, you must be aware that it sends unencrypted passwords
3796 through the network, which may present a security problem.  Here are the
3797 main issues, and some solutions.
3798
3799 @enumerate
3800 @item
3801 The passwords on the command line are visible using @code{ps}.  The best
3802 way around it is to use @code{wget -i -} and feed the @sc{url}s to
3803 Wget's standard input, each on a separate line, terminated by @kbd{C-d}.
3804 Another workaround is to use @file{.netrc} to store passwords; however,
3805 storing unencrypted passwords is also considered a security risk.
3806
3807 @item
3808 Using the insecure @dfn{basic} authentication scheme, unencrypted
3809 passwords are transmitted through the network routers and gateways.
3810
3811 @item
3812 The @sc{ftp} passwords are also in no way encrypted.  There is no good
3813 solution for this at the moment.
3814
3815 @item
3816 Although the ``normal'' output of Wget tries to hide the passwords,
3817 debugging logs show them, in all forms.  This problem is avoided by
3818 being careful when you send debug logs (yes, even when you send them to
3819 me).
3820 @end enumerate
3821
3822 @node Contributors,  , Security Considerations, Appendices
3823 @section Contributors
3824 @cindex contributors
3825
3826 @iftex
3827 GNU Wget was written by Hrvoje Nik@v{s}i@'{c} @email{hniksic@@xemacs.org},
3828 @end iftex
3829 @ifnottex
3830 GNU Wget was written by Hrvoje Niksic @email{hniksic@@xemacs.org},
3831 @end ifnottex
3832 and it is currently maintained by Micah Cowan @email{micah@@cowan.name}.
3833
3834 However, the development of Wget could never have gone as far as it has, were
3835 it not for the help of many people, either with bug reports, feature proposals,
3836 patches, or letters saying ``Thanks!''.
3837
3838 Special thanks goes to the following people (no particular order):
3839
3840 @itemize @bullet
3841 @item Dan Harkless---contributed a lot of code and documentation of
3842 extremely high quality, as well as the @code{--page-requisites} and
3843 related options.  He was the principal maintainer for some time and
3844 released Wget 1.6.
3845
3846 @item Ian Abbott---contributed bug fixes, Windows-related fixes, and
3847 provided a prototype implementation of the breadth-first recursive
3848 download.  Co-maintained Wget during the 1.8 release cycle.
3849
3850 @item
3851 The dotsrc.org crew, in particular Karsten Thygesen---donated system
3852 resources such as the mailing list, web space, @sc{ftp} space, and
3853 version control repositories, along with a lot of time to make these
3854 actually work.  Christian Reiniger was of invaluable help with setting
3855 up Subversion.
3856
3857 @item
3858 Heiko Herold---provided high-quality Windows builds and contributed
3859 bug and build reports for many years.
3860
3861 @item
3862 Shawn McHorse---bug reports and patches.
3863
3864 @item
3865 Kaveh R. Ghazi---on-the-fly @code{ansi2knr}-ization.  Lots of
3866 portability fixes.
3867
3868 @item
3869 Gordon Matzigkeit---@file{.netrc} support.
3870
3871 @item
3872 @iftex
3873 Zlatko @v{C}alu@v{s}i@'{c}, Tomislav Vujec and Dra@v{z}en
3874 Ka@v{c}ar---feature suggestions and ``philosophical'' discussions.
3875 @end iftex
3876 @ifnottex
3877 Zlatko Calusic, Tomislav Vujec and Drazen Kacar---feature suggestions
3878 and ``philosophical'' discussions.
3879 @end ifnottex
3880
3881 @item
3882 Darko Budor---initial port to Windows.
3883
3884 @item
3885 Antonio Rosella---help and suggestions, plus the initial Italian
3886 translation.
3887
3888 @item
3889 @iftex
3890 Tomislav Petrovi@'{c}, Mario Miko@v{c}evi@'{c}---many bug reports and
3891 suggestions.
3892 @end iftex
3893 @ifnottex
3894 Tomislav Petrovic, Mario Mikocevic---many bug reports and suggestions.
3895 @end ifnottex
3896
3897 @item
3898 @iftex
3899 Fran@,{c}ois Pinard---many thorough bug reports and discussions.
3900 @end iftex
3901 @ifnottex
3902 Francois Pinard---many thorough bug reports and discussions.
3903 @end ifnottex
3904
3905 @item
3906 Karl Eichwalder---lots of help with internationalization, Makefile
3907 layout and many other things.
3908
3909 @item
3910 Junio Hamano---donated support for Opie and @sc{http} @code{Digest}
3911 authentication.
3912
3913 @item
3914 Mauro Tortonesi---improved IPv6 support, adding support for dual
3915 family systems.  Refactored and enhanced FTP IPv6 code. Maintained GNU
3916 Wget from 2004--2007.
3917
3918 @item
3919 Christopher G.@: Lewis---maintenance of the Windows version of GNU WGet.
3920
3921 @item
3922 Gisle Vanem---many helpful patches and improvements, especially for
3923 Windows and MS-DOS support.
3924
3925 @item
3926 Ralf Wildenhues---contributed patches to convert Wget to use Automake as
3927 part of its build process, and various bugfixes.
3928
3929 @item
3930 Steven Schubiger---Many helpful patches, bugfixes and improvements.
3931 Notably, conversion of Wget to use the Gnulib quotes and quoteargs
3932 modules, and the addition of password prompts at the console, via the
3933 Gnulib getpasswd-gnu module.
3934
3935 @item
3936 Ted Mielczarek---donated support for CSS.
3937
3938 @item
3939 Saint Xavier---Support for IRIs (RFC 3987).
3940
3941 @item
3942 People who provided donations for development---including Brian Gough.
3943 @end itemize
3944
3945 The following people have provided patches, bug/build reports, useful
3946 suggestions, beta testing services, fan mail and all the other things
3947 that make maintenance so much fun:
3948
3949 Tim Adam,
3950 Adrian Aichner,
3951 Martin Baehr,
3952 Dieter Baron,
3953 Roger Beeman,
3954 Dan Berger,
3955 T.@: Bharath,
3956 Christian Biere,
3957 Paul Bludov,
3958 Daniel Bodea,
3959 Mark Boyns,
3960 John Burden,
3961 Julien Buty,
3962 Wanderlei Cavassin,
3963 Gilles Cedoc,
3964 Tim Charron,
3965 Noel Cragg,
3966 @iftex
3967 Kristijan @v{C}onka@v{s},
3968 @end iftex
3969 @ifnottex
3970 Kristijan Conkas,
3971 @end ifnottex
3972 John Daily,
3973 Andreas Damm,
3974 Ahmon Dancy,
3975 Andrew Davison,
3976 Bertrand Demiddelaer,
3977 Alexander Dergachev,
3978 Andrew Deryabin,
3979 Ulrich Drepper,
3980 Marc Duponcheel,
3981 @iftex
3982 Damir D@v{z}eko,
3983 @end iftex
3984 @ifnottex
3985 Damir Dzeko,
3986 @end ifnottex
3987 Alan Eldridge,
3988 Hans-Andreas Engel,
3989 @iftex
3990 Aleksandar Erkalovi@'{c},
3991 @end iftex
3992 @ifnottex
3993 Aleksandar Erkalovic,
3994 @end ifnottex
3995 Andy Eskilsson,
3996 @iftex
3997 Jo@~{a}o Ferreira,
3998 @end iftex
3999 @ifnottex
4000 Joao Ferreira,
4001 @end ifnottex
4002 Christian Fraenkel,
4003 David Fritz,
4004 Mike Frysinger,
4005 Charles C.@: Fu,
4006 FUJISHIMA Satsuki,
4007 Masashi Fujita,
4008 Howard Gayle,
4009 Marcel Gerrits,
4010 Lemble Gregory,
4011 Hans Grobler,
4012 Alain Guibert,
4013 Mathieu Guillaume,
4014 Aaron Hawley,
4015 Jochen Hein,
4016 Karl Heuer,
4017 Madhusudan Hosaagrahara,