@afourpaper
@end iftex
-@c This should really be auto-generated!
-@set VERSION 1.7-pre1
-@set UPDATED May 2001
+@c Title for man page. The weird way texi2pod.pl is written requires
+@c the preceding @set.
+@set Wget Wget
+@c man title Wget The non-interactive network downloader.
+
+@c This should really be generated automatically, possibly by including
+@c an auto-generated file.
+@set VERSION 1.9-cvs
+@set UPDATED September 2003
@dircategory Net Utilities
@dircategory World Wide Web
data.
@c man begin COPYRIGHT
-Copyright @copyright{} 1996, 1997, 1998, 2000, 2001 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1996, 1997, 1998, 2000, 2001, 2002, 2003 Free
+Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@cindex features
@c man begin DESCRIPTION
-GNU Wget is a freely available network utility to retrieve files from
-the World Wide Web, using @sc{http} (Hyper Text Transfer Protocol) and
-@sc{ftp} (File Transfer Protocol), the two most widely used Internet
-protocols. It has many useful features to make downloading easier, some
-of them being:
+GNU Wget is a free utility for non-interactive download of files from
+the Web. It supports @sc{http}, @sc{https}, and @sc{ftp} protocols, as
+well as retrieval through @sc{http} proxies.
+
+@c man end
+This chapter is a partial overview of Wget's features.
@itemize @bullet
@item
+@c man begin DESCRIPTION
Wget is non-interactive, meaning that it can work in the background,
while the user is not logged on. This allows you to start a retrieval
and disconnect from the system, letting Wget finish the work. By
@c man end
@sp 1
-@c man begin DESCRIPTION
@item
-Wget is capable of descending recursively through the structure of
-@sc{html} documents and @sc{ftp} directory trees, making a local copy of
-the directory hierarchy similar to the one on the remote server. This
-feature can be used to mirror archives and home pages, or traverse the
-web in search of data, like a @sc{www} robot (@pxref{Robots}). In that
-spirit, Wget understands the @code{norobots} convention.
+@ignore
+@c man begin DESCRIPTION
+
+@c man end
+@end ignore
+@c man begin DESCRIPTION
+Wget can follow links in @sc{html} pages and create local versions of
+remote web sites, fully recreating the directory structure of the
+original site. This is sometimes referred to as ``recursive
+downloading.'' While doing that, Wget respects the Robot Exclusion
+Standard (@file{/robots.txt}). Wget can be instructed to convert the
+links in downloaded @sc{html} files to the local files for offline
+viewing.
@c man end
@sp 1
-@c man begin DESCRIPTION
@item
File name wildcard matching and recursive mirroring of directories are
available when retrieving via @sc{ftp}. Wget can read the time-stamp
retrieval, and automatically retrieve the new version if it has. This
makes Wget suitable for mirroring of @sc{ftp} sites, as well as home
pages.
-@c man end
@sp 1
-@c man begin DESCRIPTION
@item
-Wget works exceedingly well on slow or unstable connections,
-retrying the document until it is fully retrieved, or until a
-user-specified retry count is surpassed. It will try to resume the
-download from the point of interruption, using @code{REST} with @sc{ftp}
-and @code{Range} with @sc{http} servers that support them.
+@ignore
+@c man begin DESCRIPTION
+
+@c man end
+@end ignore
+@c man begin DESCRIPTION
+Wget has been designed for robustness over slow or unstable network
+connections; if a download fails due to a network problem, it will
+keep retrying until the whole file has been retrieved. If the server
+supports regetting, it will instruct the server to continue the
+download from where it left off.
@c man end
@sp 1
-@c man begin DESCRIPTION
@item
-By default, Wget supports proxy servers, which can lighten the network
-load, speed up retrieval and provide access behind firewalls. However,
-if you are behind a firewall that requires that you use a socks style
-gateway, you can get the socks library and build Wget with support for
-socks. Wget also supports the passive @sc{ftp} downloading as an
-option.
-@c man end
+Wget supports proxy servers, which can lighten the network load, speed
+up retrieval and provide access behind firewalls. However, if you are
+behind a firewall that requires that you use a socks style gateway, you
+can get the socks library and build Wget with support for socks. Wget
+also supports the passive @sc{ftp} downloading as an option.
@sp 1
-@c man begin DESCRIPTION
@item
Builtin features offer mechanisms to tune which links you wish to follow
(@pxref{Following Links}).
-@c man end
@sp 1
-@c man begin DESCRIPTION
@item
The retrieval is conveniently traced with printing dots, each dot
representing a fixed amount of data received (1KB by default). These
representations can be customized to your preferences.
-@c man end
@sp 1
-@c man begin DESCRIPTION
@item
Most of the features are fully configurable, either through command line
options, or via the initialization file @file{.wgetrc} (@pxref{Startup
File}). Wget allows you to define @dfn{global} startup files
(@file{/usr/local/etc/wgetrc} by default) for site settings.
-@c man end
@ignore
@c man begin FILES
@end ignore
@sp 1
-@c man begin DESCRIPTION
@item
Finally, GNU Wget is free software. This means that everyone may use
it, redistribute it and/or modify it under the terms of the GNU General
Public License, as published by the Free Software Foundation
(@pxref{Copying}).
@end itemize
-@c man end
@node Invoking, Recursive Retrieval, Overview, Top
@chapter Invoking
@file{.netrc} file in your home directory, password will also be
searched for there.}
+@strong{Important Note}: if you specify a password-containing @sc{url}
+on the command line, the username and password will be plainly visible
+to all users on the system, by way of @code{ps}. On multi-user systems,
+this is a big security risk. To work around it, use @code{wget -i -}
+and feed the @sc{url}s to Wget's standard input, each on a separate
+line, terminated by @kbd{C-d}.
+
You can encode unsafe characters in a @sc{url} as @samp{%xy}, @code{xy}
being the hexadecimal representation of the character's @sc{ascii}
value. Some common unsafe characters include @samp{%} (quoted as
@item -t @var{number}
@itemx --tries=@var{number}
Set number of retries to @var{number}. Specify 0 or @samp{inf} for
-infinite retrying.
+infinite retrying. The default is to retry 20 times, with the exception
+of fatal errors like ``connection refused'' or ``not found'' (404),
+which are not retried.
@item -O @var{file}
@itemx --output-document=@var{file}
Note that @samp{-c} only works with @sc{ftp} servers and with @sc{http}
servers that support the @code{Range} header.
+@cindex progress indicator
@cindex dot style
-@cindex retrieval tracing style
-@item --dot-style=@var{style}
-Set the retrieval style to @var{style}. Wget traces the retrieval of
-each document by printing dots on the screen, each dot representing a
-fixed amount of retrieved data. Any number of dots may be separated in
-a @dfn{cluster}, to make counting easier. This option allows you to
-choose one of the pre-defined styles, determining the number of bytes
-represented by a dot, the number of dots in a cluster, and the number of
-dots on the line.
-
-With the @code{default} style each dot represents 1K, there are ten dots
-in a cluster and 50 dots in a line. The @code{binary} style has a more
-``computer''-like orientation---8K dots, 16-dots clusters and 48 dots
-per line (which makes for 384K lines). The @code{mega} style is
-suitable for downloading very large files---each dot represents 64K
-retrieved, there are eight dots in a cluster, and 48 dots on each line
-(so each line contains 3M). The @code{micro} style is exactly the
-reverse; it is suitable for downloading small files, with 128-byte dots,
-8 dots per cluster, and 48 dots (6K) per line.
+@item --progress=@var{type}
+Select the type of the progress indicator you wish to use. Legal
+indicators are ``dot'' and ``bar''.
+
+The ``bar'' indicator is used by default. It draws an ASCII progress
+bar graphics (a.k.a ``thermometer'' display) indicating the status of
+retrieval. If the output is not a TTY, the ``dot'' bar will be used by
+default.
+
+Use @samp{--progress=dot} to switch to the ``dot'' display. It traces
+the retrieval by printing dots on the screen, each dot representing a
+fixed amount of downloaded data.
+
+When using the dotted retrieval, you may also set the @dfn{style} by
+specifying the type as @samp{dot:@var{style}}. Different styles assign
+different meaning to one dot. With the @code{default} style each dot
+represents 1K, there are ten dots in a cluster and 50 dots in a line.
+The @code{binary} style has a more ``computer''-like orientation---8K
+dots, 16-dots clusters and 48 dots per line (which makes for 384K
+lines). The @code{mega} style is suitable for downloading very large
+files---each dot represents 64K retrieved, there are eight dots in a
+cluster, and 48 dots on each line (so each line contains 3M).
+
+Note that you can set the default style using the @code{progress}
+command in @file{.wgetrc}. That setting may be overridden from the
+command line. The exception is that, when the output is not a TTY, the
+``dot'' progress will be favored over ``bar''. To force the bar output,
+use @samp{--progress=bar:force}.
@item -N
@itemx --timestamping
@cindex timeout
@item -T seconds
@itemx --timeout=@var{seconds}
-Set the read timeout to @var{seconds} seconds. Whenever a network read
-is issued, the file descriptor is checked for a timeout, which could
-otherwise leave a pending connection (uninterrupted read). The default
+Set the network timeout to @var{seconds} seconds. Whenever Wget
+connects to or reads from a remote host, it checks for a timeout and
+aborts the operation if the time expires. This prevents anomalous
+occurrences such as hanging reads or infinite connects. The default
timeout is 900 seconds (fifteen minutes). Setting timeout to 0 will
disable checking for timeouts.
Please do not lower the default timeout value with this option unless
you know what you are doing.
+@cindex bandwidth, limit
+@cindex rate, limit
+@cindex limit bandwidth
+@item --limit-rate=@var{amount}
+Limit the download speed to @var{amount} bytes per second. Amount may
+be expressed in bytes, kilobytes with the @samp{k} suffix, or megabytes
+with the @samp{m} suffix. For example, @samp{--limit-rate=20k} will
+limit the retrieval rate to 20KB/s. This kind of thing is useful when,
+for whatever reason, you don't want Wget to consume the entire available
+bandwidth.
+
+Note that Wget implements the limiting by sleeping the appropriate
+amount of time after a network read that took less time than specified
+by the rate. Eventually this strategy causes the TCP transfer to slow
+down to approximately the specified rate. However, it takes some time
+for this balance to be achieved, so don't be surprised if limiting the
+rate doesn't work well with very small files.
+
@cindex pause
@cindex wait
@item -w @var{seconds}
Note that this option is turned on by default in the global
@file{wgetrc} file.
+@cindex wait, random
+@cindex random wait
+@item --random-wait
+Some web sites may perform log analysis to identify retrieval programs
+such as Wget by looking for statistically significant similarities in
+the time between requests. This option causes the time between requests
+to vary between 0 and 2 * @var{wait} seconds, where @var{wait} was
+specified using the @samp{-w} or @samp{--wait} options, in order to mask
+Wget's presence from such analysis.
+
+A recent article in a publication devoted to development on a popular
+consumer platform provided code to perform this analysis on the fly.
+Its author suggested blocking at the class C address level to ensure
+automated retrieval programs were blocked despite changing DHCP-supplied
+addresses.
+
+The @samp{--random-wait} option was inspired by this ill-advised
+recommendation to block many unrelated users from a web site due to the
+actions of one.
+
@cindex proxy
@item -Y on/off
@itemx --proxy=on/off
Turn proxy support on or off. The proxy is on by default if the
-appropriate environmental variable is defined.
+appropriate environment variable is defined.
+
+For more information about the use of proxies with Wget, @xref{Proxies}.
@cindex quota
@item -Q @var{quota}
aborted when the quota is exceeded.
Setting quota to 0 or to @samp{inf} unlimits the download quota.
+
+@cindex DNS cache
+@cindex caching of DNS lookups
+@item --dns-cache=off
+Turn off caching of DNS lookups. Normally, Wget remembers the addresses
+it looked up from DNS so it doesn't have to repeatedly contact the DNS
+server for the same (typically small) set of addresses it retrieves
+from. This cache exists in memory only; a new Wget run will contact DNS
+again.
+
+However, in some cases it is not desirable to cache host names, even for
+the duration of a short-running application like Wget. For example,
+some HTTP servers are hosted on machines with dynamically allocated IP
+addresses that change from time to time. Their DNS entries are updated
+along with each change. When Wget's download from such a host gets
+interrupted by IP address change, Wget retries the download, but (due to
+DNS caching) it contacts the old address. With the DNS cache turned
+off, Wget will repeat the DNS lookup for every connect and will thus get
+the correct dynamic address every time---at the cost of additional DNS
+lookups where they're probably not needed.
+
+If you don't understand the above description, you probably won't need
+this option.
+
+@cindex file names, restrict
+@cindex Windows file names
+@item --restrict-file-names=@var{mode}
+Change which characters found in remote URLs may show up in local file
+names generated from those URLs. Characters that are @dfn{restricted}
+by this option are escaped, i.e. replaced with @samp{%HH}, where
+@samp{HH} is the hexadecimal number that corresponds to the restricted
+character.
+
+By default, Wget escapes the characters that are not valid as part of
+file names on your operating system, as well as control characters that
+are typically unprintable. This option is useful for changing these
+defaults, either because you are downloading to a non-native partition,
+or because you want to disable escaping of the control characters.
+
+When mode is set to ``unix'', Wget escapes the character @samp{/} and
+the control characters in the ranges 0--31 and 128--159. This is the
+default on Unix-like OS'es.
+
+When mode is seto to ``windows'', Wget escapes the characters @samp{\},
+@samp{|}, @samp{/}, @samp{:}, @samp{?}, @samp{"}, @samp{*}, @samp{<},
+@samp{>}, and the control characters in the ranges 0--31 and 128--159.
+In addition to this, Wget in Windows mode uses @samp{+} instead of
+@samp{:} to separate host and port in local file names, and uses
+@samp{@@} instead of @samp{?} to separate the query portion of the file
+name from the rest. Therefore, a URL that would be saved as
+@samp{www.xemacs.org:4300/search.pl?input=blah} in Unix mode would be
+saved as @samp{www.xemacs.org+4300/search.pl@@input=blah} in Windows
+mode. This mode is the default on Windows.
+
+If you append @samp{,nocontrol} to the mode, as in
+@samp{unix,nocontrol}, escaping of the control characters is also
+switched off. You can use @samp{--restrict-file-names=nocontrol} to
+turn off escaping of control characters without affecting the choice of
+the OS to use as file name restriction mode.
@end table
@node Directory Options, HTTP Options, Download Options, Invoking
@code{digest} authentication scheme.
Another way to specify username and password is in the @sc{url} itself
-(@pxref{URL Format}). For more information about security issues with
-Wget, @xref{Security Considerations}.
+(@pxref{URL Format}). Either method reveals your password to anyone who
+bothers to run @code{ps}. To prevent the passwords from being seen,
+store them in @file{.wgetrc} or @file{.netrc}, and make sure to protect
+those files from other users with @code{chmod}. If the passwords are
+really important, do not leave them lying in those files either---edit
+the files and delete them after Wget has started the download.
+
+For more information about security issues with Wget, @xref{Security
+Considerations}.
@cindex proxy
@cindex cache
@cindex loading cookies
@cindex cookies, loading
@item --load-cookies @var{file}
-Load cookies from @var{file} before the first HTTP retrieval. The
-format of @var{file} is one used by Netscape and Mozilla, at least their
-Unix version.
+Load cookies from @var{file} before the first HTTP retrieval.
+@var{file} is a textual file in the format originally used by Netscape's
+@file{cookies.txt} file.
+
+You will typically use this option when mirroring sites that require
+that you be logged in to access some or all of their content. The login
+process typically works by the web server issuing an @sc{http} cookie
+upon receiving and verifying your credentials. The cookie is then
+resent by the browser when accessing that part of the site, and so
+proves your identity.
+
+Mirroring such a site requires Wget to send the same cookies your
+browser sends when communicating with the site. This is achieved by
+@samp{--load-cookies}---simply point Wget to the location of the
+@file{cookies.txt} file, and it will send the same cookies your browser
+would send in the same situation. Different browsers keep textual
+cookie files in different locations:
+
+@table @asis
+@item Netscape 4.x.
+The cookies are in @file{~/.netscape/cookies.txt}.
+
+@item Mozilla and Netscape 6.x.
+Mozilla's cookie file is also named @file{cookies.txt}, located
+somewhere under @file{~/.mozilla}, in the directory of your profile.
+The full path usually ends up looking somewhat like
+@file{~/.mozilla/default/@var{some-weird-string}/cookies.txt}.
+
+@item Internet Explorer.
+You can produce a cookie file Wget can use by using the File menu,
+Import and Export, Export Cookies. This has been tested with Internet
+Explorer 5; it is not guaranteed to work with earlier versions.
+
+@item Other browsers.
+If you are using a different browser to create your cookies,
+@samp{--load-cookies} will only work if you can locate or produce a
+cookie file in the Netscape format that Wget expects.
+@end table
+
+If you cannot use @samp{--load-cookies}, there might still be an
+alternative. If your browser supports a ``cookie manager'', you can use
+it to view the cookies used when accessing the site you're mirroring.
+Write down the name and value of the cookie, and manually instruct Wget
+to send those cookies, bypassing the ``official'' cookie support:
+
+@example
+wget --cookies=off --header "Cookie: @var{name}=@var{value}"
+@end example
@cindex saving cookies
@cindex cookies, saving
authentication on a proxy server. Wget will encode them using the
@code{basic} authentication scheme.
+Security considerations similar to those with @samp{--http-passwd}
+pertain here as well.
+
@cindex http referer
@cindex referer, http
@item --referer=@var{url}
likes to use a few options in addition to @samp{-p}:
@example
-wget -E -H -k -K -nh -p http://@var{site}/@var{document}
+wget -E -H -k -K -p http://@var{site}/@var{document}
@end example
-In one case you'll need to add a couple more options. If @var{document}
-is a @code{<FRAMESET>} page, the "one more hop" that @samp{-p} gives you
-won't be enough---you'll get the @code{<FRAME>} pages that are
-referenced, but you won't get @emph{their} requisites. Therefore, in
-this case you'll need to add @samp{-r -l1} to the commandline. The
-@samp{-r -l1} will recurse from the @code{<FRAMESET>} page to to the
-@code{<FRAME>} pages, and the @samp{-p} will get their requisites. If
-you're already using a recursion level of 1 or more, you'll need to up
-it by one. In the future, @samp{-p} may be made smarter so that it'll
-do "two more hops" in the case of a @code{<FRAMESET>} page.
-
To finish off this topic, it's worth knowing that Wget's idea of an
external document link is any URL specified in an @code{<A>} tag, an
@code{<AREA>} tag, or a @code{<LINK>} tag other than @code{<LINK
REL="stylesheet">}.
+
+@cindex HTML comments
+@cindex comments, HTML
+@item --strict-comments
+Turn on strict parsing of HTML comments. The default is to terminate
+comments at the first occurrence of @samp{-->}.
+
+According to specifications, HTML comments are expressed as SGML
+@dfn{declarations}. Declaration is special markup that begins with
+@samp{<!} and ends with @samp{>}, such as @samp{<!DOCTYPE ...>}, that
+may contain comments between a pair of @samp{--} delimiters. HTML
+comments are ``empty declarations'', SGML declarations without any
+non-comment text. Therefore, @samp{<!--foo-->} is a valid comment, and
+so is @samp{<!--one-- --two-->}, but @samp{<!--1--2-->} is not.
+
+On the other hand, most HTML writers don't perceive comments as anything
+other than text delimited with @samp{<!--} and @samp{-->}, which is not
+quite the same. For example, something like @samp{<!------------>}
+works as a valid comment as long as the number of dashes is a multiple
+of four (!). If not, the comment technically lasts until the next
+@samp{--}, which may be at the other end of the document. Because of
+this, many popular browsers completely ignore the specification and
+implement what users have come to expect: comments delimited with
+@samp{<!--} and @samp{-->}.
+
+Until version 1.9, Wget interpreted comments strictly, which resulted in
+missing links in many web pages that displayed fine in browsers, but had
+the misfortune of containing non-compliant comments. Beginning with
+version 1.9, Wget has joined the ranks of clients that implements
+``naive'' comments, terminating each comment at the first occurrence of
+@samp{-->}.
+
+If, for whatever reason, you want strict comment parsing, use this
+option to turn it on.
@end table
@node Recursive Accept/Reject Options, , Recursive Retrieval Options, Invoking
@item -D @var{domain-list}
@itemx --domains=@var{domain-list}
-Set domains to be accepted and @sc{dns} looked-up, where
-@var{domain-list} is a comma-separated list. Note that it does
-@emph{not} turn on @samp{-H}. This option speeds things up, even if
-only one host is spanned (@pxref{Domain Acceptance}).
+Set domains to be followed. @var{domain-list} is a comma-separated list
+of domains. Note that it does @emph{not} turn on @samp{-H}.
@item --exclude-domains @var{domain-list}
-Exclude the domains given in a comma-separated @var{domain-list} from
-@sc{dns}-lookup (@pxref{Domain Acceptance}).
+Specify the domains that are @emph{not} to be followed.
+(@pxref{Spanning Hosts}).
@cindex follow FTP links
@item --follow-ftp
single page and its requisites, using a commandline like:
@example
-wget -Ga,area -H -k -K -nh -r http://@var{site}/@var{document}
+wget -Ga,area -H -k -K -r http://@var{site}/@var{document}
@end example
However, the author of this option came across a page with tags like
@item -H
@itemx --span-hosts
-Enable spanning across hosts when doing recursive retrieving (@pxref{All
-Hosts}).
+Enable spanning across hosts when doing recursive retrieving
+(@pxref{Spanning Hosts}).
@item -L
@itemx --relative
download (@pxref{Directory-Based Limits} for more details.) Elements of
@var{list} may contain wildcards.
-@item -nh
-@itemx --no-host-lookup
-Disable the time-consuming @sc{dns} lookup of almost all hosts
-(@pxref{Host Checking}).
-
@item -np
@item --no-parent
Do not ever ascend to the parent directory when retrieving recursively.
@cindex recursive retrieval
GNU Wget is capable of traversing parts of the Web (or a single
-@sc{http} or @sc{ftp} server), depth-first following links and directory
-structure. This is called @dfn{recursive} retrieving, or
-@dfn{recursion}.
+@sc{http} or @sc{ftp} server), following links and directory structure.
+We refer to this as to @dfn{recursive retrieving}, or @dfn{recursion}.
With @sc{http} @sc{url}s, Wget retrieves and parses the @sc{html} from
the given @sc{url}, documents, retrieving the files the @sc{html}
@code{src}. If the freshly downloaded file is also of type
@code{text/html}, it will be parsed and followed further.
+Recursive retrieval of @sc{http} and @sc{html} content is
+@dfn{breadth-first}. This means that Wget first downloads the requested
+HTML document, then the documents linked from that document, then the
+documents linked by them, and so on. In other words, Wget first
+downloads the documents at depth 1, then those at depth 2, and so on
+until the specified maximum depth.
+
The maximum @dfn{depth} to which the retrieval may descend is specified
-with the @samp{-l} option (the default maximum depth is five layers).
-@xref{Recursive Retrieval}.
+with the @samp{-l} option. The default maximum depth is five layers.
When retrieving an @sc{ftp} @sc{url} recursively, Wget will retrieve all
the data from the given directory tree (including the subdirectories up
to the specified depth) on the remote server, creating its mirror image
locally. @sc{ftp} retrieval is also limited by the @code{depth}
-parameter.
+parameter. Unlike @sc{http} recursion, @sc{ftp} recursion is performed
+depth-first.
By default, Wget will create a local directory tree, corresponding to
the one found on the remote server.
presentations, and any other opportunities where slow network
connections should be bypassed by storing the files locally.
-You should be warned that invoking recursion may cause grave overloading
-on your system, because of the fast exchange of data through the
-network; all of this may hamper other users' work. The same stands for
-the foreign server you are mirroring---the more requests it gets in a
-rows, the greater is its load.
-
-Careless retrieving can also fill your file system uncontrollably, which
-can grind the machine to a halt.
-
-The load can be minimized by lowering the maximum recursion level
-(@samp{-l}) and/or by lowering the number of retries (@samp{-t}). You
-may also consider using the @samp{-w} option to slow down your requests
-to the remote servers, as well as the numerous options to narrow the
-number of followed links (@pxref{Following Links}).
-
-Recursive retrieval is a good thing when used properly. Please take all
-precautions not to wreak havoc through carelessness.
+You should be warned that recursive downloads can overload the remote
+servers. Because of that, many administrators frown upon them and may
+ban access from your site if they detect very fast downloads of big
+amounts of content. When downloading from Internet servers, consider
+using the @samp{-w} option to introduce a delay between accesses to the
+server. The download will take a while longer, but the server
+administrator will not be alarmed by your rudeness.
+
+Of course, recursive download may cause problems on your machine. If
+left to run unchecked, it can easily fill up the disk. If downloading
+from local network, it can also take bandwidth on the system, as well as
+consume memory and CPU.
+
+Try to specify the criteria that match the kind of download you are
+trying to achieve. If you want to download only one page, use
+@samp{--page-requisites} without any additional recursion. If you want
+to download things under one directory, use @samp{-np} to avoid
+downloading things from other directories. If you want to download all
+the files from one directory, use @samp{-l 1} to make sure the recursion
+depth never exceeds one. @xref{Following Links}, for more information
+about this.
+
+Recursive retrieval should be used with care. Don't say you were not
+warned.
@node Following Links, Time-Stamping, Recursive Retrieval, Top
@chapter Following Links
links it will follow.
@menu
-* Relative Links:: Follow relative links only.
-* Host Checking:: Follow links on the same host.
-* Domain Acceptance:: Check on a list of domains.
-* All Hosts:: No host restrictions.
+* Spanning Hosts:: (Un)limiting retrieval based on host name.
* Types of Files:: Getting only certain files.
* Directory-Based Limits:: Getting only certain directories.
+* Relative Links:: Follow relative links only.
* FTP Links:: Following FTP links.
@end menu
-@node Relative Links, Host Checking, Following Links, Following Links
-@section Relative Links
-@cindex relative links
+@node Spanning Hosts, Types of Files, Following Links, Following Links
+@section Spanning Hosts
+@cindex spanning hosts
+@cindex hosts, spanning
+
+Wget's recursive retrieval normally refuses to visit hosts different
+than the one you specified on the command line. This is a reasonable
+default; without it, every retrieval would have the potential to turn
+your Wget into a small version of google.
+
+However, visiting different hosts, or @dfn{host spanning,} is sometimes
+a useful option. Maybe the images are served from a different server.
+Maybe you're mirroring a site that consists of pages interlinked between
+three servers. Maybe the server has two equivalent names, and the HTML
+pages refer to both interchangeably.
+
+@table @asis
+@item Span to any host---@samp{-H}
+
+The @samp{-H} option turns on host spanning, thus allowing Wget's
+recursive run to visit any host referenced by a link. Unless sufficient
+recursion-limiting criteria are applied depth, these foreign hosts will
+typically link to yet more hosts, and so on until Wget ends up sucking
+up much more data than you have intended.
+
+@item Limit spanning to certain domains---@samp{-D}
+
+The @samp{-D} option allows you to specify the domains that will be
+followed, thus limiting the recursion only to the hosts that belong to
+these domains. Obviously, this makes sense only in conjunction with
+@samp{-H}. A typical example would be downloading the contents of
+@samp{www.server.com}, but allowing downloads from
+@samp{images.server.com}, etc.:
+
+@example
+wget -rH -Dserver.com http://www.server.com/
+@end example
+
+You can specify more than one address by separating them with a comma,
+e.g. @samp{-Ddomain1.com,domain2.com}.
-When only relative links are followed (option @samp{-L}), recursive
-retrieving will never span hosts. No time-expensive @sc{dns}-lookups
-will be performed, and the process will be very fast, with the minimum
-strain of the network. This will suit your needs often, especially when
-mirroring the output of various @code{x2html} converters, since they
-generally output relative links.
-
-@node Host Checking, Domain Acceptance, Relative Links, Following Links
-@section Host Checking
-@cindex DNS lookup
-@cindex host lookup
-@cindex host checking
-
-The drawback of following the relative links solely is that humans often
-tend to mix them with absolute links to the very same host, and the very
-same page. In this mode (which is the default mode for following links)
-all @sc{url}s that refer to the same host will be retrieved.
-
-The problem with this option are the aliases of the hosts and domains.
-Thus there is no way for Wget to know that @samp{regoc.srce.hr} and
-@samp{www.srce.hr} are the same host, or that @samp{fly.srk.fer.hr} is
-the same as @samp{fly.cc.fer.hr}. Whenever an absolute link is
-encountered, the host is @sc{dns}-looked-up with @code{gethostbyname} to
-check whether we are maybe dealing with the same hosts. Although the
-results of @code{gethostbyname} are cached, it is still a great
-slowdown, e.g. when dealing with large indices of home pages on different
-hosts (because each of the hosts must be @sc{dns}-resolved to see
-whether it just @emph{might} be an alias of the starting host).
-
-To avoid the overhead you may use @samp{-nh}, which will turn off
-@sc{dns}-resolving and make Wget compare hosts literally. This will
-make things run much faster, but also much less reliable
-(e.g. @samp{www.srce.hr} and @samp{regoc.srce.hr} will be flagged as
-different hosts).
-
-Note that modern @sc{http} servers allow one IP address to host several
-@dfn{virtual servers}, each having its own directory hierarchy. Such
-``servers'' are distinguished by their hostnames (all of which point to
-the same IP address); for this to work, a client must send a @code{Host}
-header, which is what Wget does. However, in that case Wget @emph{must
-not} try to divine a host's ``real'' address, nor try to use the same
-hostname for each access, i.e. @samp{-nh} must be turned on.
-
-In other words, the @samp{-nh} option must be used to enable the
-retrieval from virtual servers distinguished by their hostnames. As the
-number of such server setups grow, the behavior of @samp{-nh} may become
-the default in the future.
-
-@node Domain Acceptance, All Hosts, Host Checking, Following Links
-@section Domain Acceptance
-
-With the @samp{-D} option you may specify the domains that will be
-followed. The hosts the domain of which is not in this list will not be
-@sc{dns}-resolved. Thus you can specify @samp{-Dmit.edu} just to make
-sure that @strong{nothing outside of @sc{mit} gets looked up}. This is
-very important and useful. It also means that @samp{-D} does @emph{not}
-imply @samp{-H} (span all hosts), which must be specified explicitly.
-Feel free to use this options since it will speed things up, with almost
-all the reliability of checking for all hosts. Thus you could invoke
-
-@example
-wget -r -D.hr http://fly.srk.fer.hr/
-@end example
-
-to make sure that only the hosts in @samp{.hr} domain get
-@sc{dns}-looked-up for being equal to @samp{fly.srk.fer.hr}. So
-@samp{fly.cc.fer.hr} will be checked (only once!) and found equal, but
-@samp{www.gnu.ai.mit.edu} will not even be checked.
-
-Of course, domain acceptance can be used to limit the retrieval to
-particular domains with spanning of hosts in them, but then you must
-specify @samp{-H} explicitly. E.g.:
-
-@example
-wget -r -H -Dmit.edu,stanford.edu http://www.mit.edu/
-@end example
-
-will start with @samp{http://www.mit.edu/}, following links across
-@sc{mit} and Stanford.
+@item Keep download off certain domains---@samp{--exclude-domains}
If there are domains you want to exclude specifically, you can do it
with @samp{--exclude-domains}, which accepts the same type of arguments
this:
@example
-wget -rH -Dfoo.edu --exclude-domains sunsite.foo.edu http://www.foo.edu/
+wget -rH -Dfoo.edu --exclude-domains sunsite.foo.edu \
+ http://www.foo.edu/
@end example
-@node All Hosts, Types of Files, Domain Acceptance, Following Links
-@section All Hosts
-@cindex all hosts
-@cindex span hosts
-
-When @samp{-H} is specified without @samp{-D}, all hosts are freely
-spanned. There are no restrictions whatsoever as to what part of the
-net Wget will go to fetch documents, other than maximum retrieval depth.
-If a page references @samp{www.yahoo.com}, so be it. Such an option is
-rarely useful for itself.
+@end table
-@node Types of Files, Directory-Based Limits, All Hosts, Following Links
+@node Types of Files, Directory-Based Limits, Spanning Hosts, Following Links
@section Types of Files
@cindex types of files
files; Wget must load all the @sc{html}s to know where to go at
all---recursive retrieval would make no sense otherwise.
-@node Directory-Based Limits, FTP Links, Types of Files, Following Links
+@node Directory-Based Limits, Relative Links, Types of Files, Following Links
@section Directory-Based Limits
@cindex directories
@cindex directory limits
intelligent fashion.
@end table
-@node FTP Links, , Directory-Based Limits, Following Links
+@node Relative Links, FTP Links, Directory-Based Limits, Following Links
+@section Relative Links
+@cindex relative links
+
+When @samp{-L} is turned on, only the relative links are ever followed.
+Relative links are here defined those that do not refer to the web
+server root. For example, these links are relative:
+
+@example
+<a href="foo.gif">
+<a href="foo/bar.gif">
+<a href="../foo/bar.gif">
+@end example
+
+These links are not relative:
+
+@example
+<a href="/foo.gif">
+<a href="/foo/bar.gif">
+<a href="http://www.server.com/foo/bar.gif">
+@end example
+
+Using this option guarantees that recursive retrieval will not span
+hosts, even without @samp{-H}. In simple cases it also allows downloads
+to ``just work'' without having to convert links.
+
+This option is probably not very useful and might be removed in a future
+release.
+
+@node FTP Links, , Relative Links, Following Links
@section Following FTP Links
@cindex following ftp links
Turning dirstruct on or off---the same as @samp{-x} or @samp{-nd},
respectively.
+@item dns_cache = on/off
+Turn DNS caching on/off. Since DNS caching is on by default, this
+option is normally used to turn it off. Same as @samp{--dns-cache}.
+
@item domains = @var{string}
-Same as @samp{-D} (@pxref{Domain Acceptance}).
+Same as @samp{-D} (@pxref{Spanning Hosts}).
@item dot_bytes = @var{n}
Specify the number of bytes ``contained'' in a dot, as seen throughout
@item dot_spacing = @var{n}
Specify the number of dots in a single cluster (10 by default).
-@item dot_style = @var{string}
-Specify the dot retrieval @dfn{style}, as with @samp{--dot-style}.
-
@item exclude_directories = @var{string}
Specify a comma-separated list of directories you wish to exclude from
download---the same as @samp{-X} (@pxref{Directory-Based Limits}).
@item exclude_domains = @var{string}
-Same as @samp{--exclude-domains} (@pxref{Domain Acceptance}).
+Same as @samp{--exclude-domains} (@pxref{Spanning Hosts}).
@item follow_ftp = on/off
-Follow @sc{ftp} links from @sc{html} documents---the same as @samp{-f}.
+Follow @sc{ftp} links from @sc{html} documents---the same as
+@samp{--follow-ftp}.
@item follow_tags = @var{string}
Only follow certain HTML tags when doing a recursive retrieval, just like
as there is, provided there is more than or equal to the value in
@code{Content-Length}.
+@item limit_rate = @var{rate}
+Limit the download speed to no more than @var{rate} bytes per second.
+The same as @samp{--limit-rate}.
+
@item logfile = @var{string}
Set logfile---the same as @samp{-o}.
Set your @sc{ftp} password to @var{password}. Without this setting, the
password defaults to @samp{username@@hostname.domainname}.
+@item progress = @var{string}
+Set the type of the progress indicator. Legal types are ``dot'' and
+``bar''.
+
@item proxy_user = @var{string}
Set proxy authentication user name to @var{string}, like @samp{--proxy-user}.
If set to on, remove @sc{ftp} listings downloaded by Wget. Setting it
to off is the same as @samp{-nr}.
+@item restrict_file_names = unix/windows
+Restrict the file names generated by Wget from URLs. See
+@samp{--restrict-file-names} for a more detailed description.
+
@item retr_symlinks = on/off
When set to on, retrieve symbolic links as if they were plain files; the
same as @samp{--retr-symlinks}.
@item robots = on/off
-Use (or not) @file{/robots.txt} file (@pxref{Robots}). Be sure to know
-what you are doing before changing the default (which is @samp{on}).
+Specify whether the norobots convention is respected by Wget, ``on'' by
+default. This switch controls both the @file{/robots.txt} and the
+@samp{nofollow} aspect of the spec. @xref{Robot Exclusion}, for more
+details about this. Be sure you know what you are doing before turning
+this off.
@item server_response = on/off
Choose whether or not to print the @sc{http} and @sc{ftp} server
responses---the same as @samp{-S}.
-@item simple_host_check = on/off
-Same as @samp{-nh} (@pxref{Host Checking}).
-
@item span_hosts = on/off
Same as @samp{-H}.
+@item strict_comments = on/off
+Same as @samp{--strict-comments}.
+
@item timeout = @var{n}
Set timeout value---the same as @samp{-T}.
Wait up to @var{n} seconds between retries of failed retrievals
only---the same as @samp{--waitretry}. Note that this is turned on by
default in the global @file{wgetrc}.
+
+@item randomwait = on/off
+Turn random between-request wait times on or off. The same as
+@samp{--random-wait}.
@end table
@node Sample Wgetrc, , Wgetrc Commands, Startup File
@chapter Examples
@cindex examples
-The examples are classified into three sections, because of clarity.
-The first section is a tutorial for beginners. The second section
-explains some of the more complex program features. The third section
-contains advice for mirror administrators, as well as even more complex
-features (that some would call perverted).
+@c man begin EXAMPLES
+The examples are divided into three sections loosely based on their
+complexity.
@menu
-* Simple Usage:: Simple, basic usage of the program.
-* Advanced Usage:: Advanced techniques of usage.
-* Guru Usage:: Mirroring and the hairy stuff.
+* Simple Usage:: Simple, basic usage of the program.
+* Advanced Usage:: Advanced tips.
+* Very Advanced Usage:: The hairy stuff.
@end menu
@node Simple Usage, Advanced Usage, Examples, Examples
wget http://fly.srk.fer.hr/
@end example
-The response will be something like:
-
-@example
-@group
---13:30:45-- http://fly.srk.fer.hr:80/en/
- => `index.html'
-Connecting to fly.srk.fer.hr:80... connected!
-HTTP request sent, awaiting response... 200 OK
-Length: 4,694 [text/html]
-
- 0K -> .... [100%]
-
-13:30:46 (23.75 KB/s) - `index.html' saved [4694/4694]
-@end group
-@end example
-
@item
But what will happen if the connection is slow, and the file is lengthy?
The connection will probably fail before the whole file is retrieved,
password.
@example
-@group
-$ wget ftp://gnjilux.srk.fer.hr/welcome.msg
---10:08:47-- ftp://gnjilux.srk.fer.hr:21/welcome.msg
- => `welcome.msg'
-Connecting to gnjilux.srk.fer.hr:21... connected!
-Logging in as anonymous ... Logged in!
-==> TYPE I ... done. ==> CWD not needed.
-==> PORT ... done. ==> RETR welcome.msg ... done.
-Length: 1,340 (unauthoritative)
-
- 0K -> . [100%]
-
-10:08:48 (1.28 MB/s) - `welcome.msg' saved [1340]
-@end group
+wget ftp://gnjilux.srk.fer.hr/welcome.msg
@end example
@item
@example
wget ftp://prep.ai.mit.edu/pub/gnu/
-lynx index.html
+links index.html
@end example
@end itemize
-@node Advanced Usage, Guru Usage, Simple Usage, Examples
+@node Advanced Usage, Very Advanced Usage, Simple Usage, Examples
@section Advanced Usage
@itemize @bullet
@item
-You would like to read the list of @sc{url}s from a file? Not a problem
-with that:
+You have a file that contains the URLs you want to download? Use the
+@samp{-i} switch:
@example
-wget -i file
+wget -i @var{file}
@end example
If you specify @samp{-} as file name, the @sc{url}s will be read from
standard input.
@item
-Create a mirror image of GNU @sc{www} site (with the same directory structure
-the original has) with only one try per document, saving the log of the
-activities to @file{gnulog}:
+Create a five levels deep mirror image of the GNU web site, with the
+same directory structure the original has, with only one try per
+document, saving the log of the activities to @file{gnulog}:
@example
-wget -r -t1 http://www.gnu.ai.mit.edu/ -o gnulog
+wget -r http://www.gnu.org/ -o gnulog
@end example
@item
-Retrieve the first layer of yahoo links:
+The same as the above, but convert the links in the @sc{html} files to
+point to local files, so you can view the documents off-line:
@example
-wget -r -l1 http://www.yahoo.com/
+wget --convert-links -r http://www.gnu.org/ -o gnulog
+@end example
+
+@item
+Retrieve only one HTML page, but make sure that all the elements needed
+for the page to be displayed, such as inline images and external style
+sheets, are also downloaded. Also make sure the downloaded page
+references the downloaded links.
+
+@example
+wget -p --convert-links http://www.server.com/dir/page.html
+@end example
+
+The HTML page will be saved to @file{www.server.com/dir/page.html}, and
+the images, stylesheets, etc., somewhere under @file{www.server.com/},
+depending on where they were on the remote server.
+
+@item
+The same as the above, but without the @file{www.server.com/} directory.
+In fact, I don't want to have all those random server directories
+anyway---just save @emph{all} those files under a @file{download/}
+subdirectory of the current directory.
+
+@example
+wget -p --convert-links -nH -nd -Pdownload \
+ http://www.server.com/dir/page.html
@end example
@item
@end example
@item
-Save the server headers with the file:
+Save the server headers with the file, perhaps for post-processing.
+
@example
wget -s http://www.lycos.com/
more index.html
@item
Retrieve the first two levels of @samp{wuarchive.wustl.edu}, saving them
-to /tmp.
+to @file{/tmp}.
@example
-wget -P/tmp -l2 ftp://wuarchive.wustl.edu/
+wget -r -l2 -P/tmp ftp://wuarchive.wustl.edu/
@end example
@item
-You want to download all the @sc{gif}s from an @sc{http} directory.
-@samp{wget http://host/dir/*.gif} doesn't work, since @sc{http}
-retrieval does not support globbing. In that case, use:
+You want to download all the @sc{gif}s from a directory on an @sc{http}
+server. You tried @samp{wget http://www.server.com/dir/*.gif}, but that
+didn't work because @sc{http} retrieval does not support globbing. In
+that case, use:
@example
-wget -r -l1 --no-parent -A.gif http://host/dir/
+wget -r -l1 --no-parent -A.gif http://www.server.com/dir/
@end example
-It is a bit of a kludge, but it works. @samp{-r -l1} means to retrieve
-recursively (@pxref{Recursive Retrieval}), with maximum depth of 1.
-@samp{--no-parent} means that references to the parent directory are
-ignored (@pxref{Directory-Based Limits}), and @samp{-A.gif} means to
+More verbose, but the effect is the same. @samp{-r -l1} means to
+retrieve recursively (@pxref{Recursive Retrieval}), with maximum depth
+of 1. @samp{--no-parent} means that references to the parent directory
+are ignored (@pxref{Directory-Based Limits}), and @samp{-A.gif} means to
download only the @sc{gif} files. @samp{-A "*.gif"} would have worked
too.
It would be:
@example
-wget -nc -r http://www.gnu.ai.mit.edu/
+wget -nc -r http://www.gnu.org/
@end example
@item
@sc{ftp}, use the appropriate @sc{url} syntax (@pxref{URL Format}).
@example
-wget ftp://hniksic:mypassword@@jagor.srce.hr/.emacs
+wget ftp://hniksic:mypassword@@unix.server.com/.emacs
@end example
+Note, however, that this usage is not advisable on multi-user systems
+because it reveals your password to anyone who looks at the output of
+@code{ps}.
+
+@cindex redirecting output
@item
-If you do not like the default retrieval visualization (1K dots with 10
-dots per cluster and 50 dots per line), you can customize it through dot
-settings (@pxref{Wgetrc Commands}). For example, many people like the
-``binary'' style of retrieval, with 8K dots and 512K lines:
+You would like the output documents to go to standard output instead of
+to files?
@example
-wget --dot-style=binary ftp://prep.ai.mit.edu/pub/gnu/README
+wget -O - http://jagor.srce.hr/ http://www.srce.hr/
@end example
-You can experiment with other styles, like:
+You can also combine the two options and make pipelines to retrieve the
+documents from remote hotlists:
@example
-wget --dot-style=mega ftp://ftp.xemacs.org/pub/xemacs/xemacs-20.4/xemacs-20.4.tar.gz
-wget --dot-style=micro http://fly.srk.fer.hr/
+wget -O - http://cool.list.com/ | wget --force-html -i -
@end example
-
-To make these settings permanent, put them in your @file{.wgetrc}, as
-described before (@pxref{Sample Wgetrc}).
@end itemize
-@node Guru Usage, , Advanced Usage, Examples
-@section Guru Usage
+@node Very Advanced Usage, , Advanced Usage, Examples
+@section Very Advanced Usage
@cindex mirroring
@itemize @bullet
@item
If you wish Wget to keep a mirror of a page (or @sc{ftp}
subdirectories), use @samp{--mirror} (@samp{-m}), which is the shorthand
-for @samp{-r -N}. You can put Wget in the crontab file asking it to
-recheck a site each Sunday:
+for @samp{-r -l inf -N}. You can put Wget in the crontab file asking it
+to recheck a site each Sunday:
@example
crontab
-0 0 * * 0 wget --mirror ftp://ftp.xemacs.org/pub/xemacs/ -o /home/me/weeklog
+0 0 * * 0 wget --mirror http://www.gnu.org/ -o /home/me/weeklog
@end example
@item
-You may wish to do the same with someone's home page. But you do not
-want to download all those images---you're only interested in @sc{html}.
+In addition to the above, you want the links to be converted for local
+viewing. But, after having read this manual, you know that link
+conversion doesn't play well with timestamping, so you also want Wget to
+back up the original HTML files before the conversion. Wget invocation
+would look like this:
@example
-wget --mirror -A.html http://www.w3.org/
+wget --mirror --convert-links --backup-converted \
+ http://www.gnu.org/ -o /home/me/weeklog
@end example
@item
-But what about mirroring the hosts networkologically close to you? It
-seems so awfully slow because of all that @sc{dns} resolving. Just use
-@samp{-D} (@pxref{Domain Acceptance}).
+But you've also noticed that local viewing doesn't work all that well
+when HTML files are saved under extensions other than @samp{.html},
+perhaps because they were served as @file{index.cgi}. So you'd like
+Wget to rename all the files served with content-type @samp{text/html}
+to @file{@var{name}.html}.
@example
-wget -rN -Dsrce.hr http://www.srce.hr/
+wget --mirror --convert-links --backup-converted \
+ --html-extension -o /home/me/weeklog \
+ http://www.gnu.org/
@end example
-Now Wget will correctly find out that @samp{regoc.srce.hr} is the same
-as @samp{www.srce.hr}, but will not even take into consideration the
-link to @samp{www.mit.edu}.
-
-@item
-You have a presentation and would like the dumb absolute links to be
-converted to relative? Use @samp{-k}:
+Or, with less typing:
@example
-wget -k -r @var{URL}
-@end example
-
-@cindex redirecting output
-@item
-You would like the output documents to go to standard output instead of
-to files? OK, but Wget will automatically shut up (turn on
-@samp{--quiet}) to prevent mixing of Wget output and the retrieved
-documents.
-
-@example
-wget -O - http://jagor.srce.hr/ http://www.srce.hr/
-@end example
-
-You can also combine the two options and make weird pipelines to
-retrieve the documents from remote hotlists:
-
-@example
-wget -O - http://cool.list.com/ | wget --force-html -i -
+wget -m -k -K -E http://www.gnu.org/ -o /home/me/weeklog
@end example
@end itemize
+@c man end
@node Various, Appendices, Examples, Top
@chapter Various
connections.
@item ftp_proxy
-This variable should contain the @sc{url} of the proxy for @sc{http}
+This variable should contain the @sc{url} of the proxy for @sc{ftp}
connections. It is quite common that @sc{http_proxy} and @sc{ftp_proxy}
are set to the same @sc{url}.
You may specify your username and password either through the proxy
@sc{url} or through the command-line options. Assuming that the
-company's proxy is located at @samp{proxy.srce.hr} at port 8001, a proxy
-@sc{url} location containing authorization data might look like this:
+company's proxy is located at @samp{proxy.company.com} at port 8001, a
+proxy @sc{url} location containing authorization data might look like
+this:
@example
http://hniksic:mypassword@@proxy.company.com:8001/
@cindex mailing list
@cindex list
-Wget has its own mailing list at @email{wget@@sunsite.auc.dk}, thanks
+Wget has its own mailing list at @email{wget@@sunsite.dk}, thanks
to Karsten Thygesen. The mailing list is for discussion of Wget
features and web, reporting Wget bugs (those that you think may be of
interest to the public) and mailing announcements. You are welcome to
subscribe. The more people on the list, the better!
-To subscribe, send mail to @email{wget-subscribe@@sunsite.auc.dk}.
+To subscribe, send mail to @email{wget-subscribe@@sunsite.dk}.
the magic word @samp{subscribe} in the subject line. Unsubscribe by
-mailing to @email{wget-unsubscribe@@sunsite.auc.dk}.
+mailing to @email{wget-unsubscribe@@sunsite.dk}.
The mailing list is archived at @url{http://fly.srk.fer.hr/archive/wget}.
Alternative archive is available at
@item
Try to repeat the bug in as simple circumstances as possible. E.g. if
-Wget crashes on @samp{wget -rLl0 -t5 -Y0 http://yoyodyne.com -o
-/tmp/log}, you should try to see if it will crash with a simpler set of
-options.
+Wget crashes while downloading @samp{wget -rl0 -kKE -t5 -Y0
+http://yoyodyne.com -o /tmp/log}, you should try to see if the crash is
+repeatable, and if will occur with a simpler set of options. You might
+even try to start the download at the page where the crash occurred to
+see if that page somehow triggered the crash.
Also, while I will probably be interested to know the contents of your
@file{.wgetrc} file, just dumping it into the debug message is probably
a bad idea. Instead, you should first try to see if the bug repeats
with @file{.wgetrc} moved out of the way. Only if it turns out that
-@file{.wgetrc} settings affect the bug, should you mail me the relevant
-parts of the file.
+@file{.wgetrc} settings affect the bug, mail me the relevant parts of
+the file.
@item
Please start Wget with @samp{-d} option and send the log (or the
@item
If Wget has crashed, try to run it in a debugger, e.g. @code{gdb `which
wget` core} and type @code{where} to get the backtrace.
-
-@item
-Find where the bug is, fix it and send me the patches. :-)
@end enumerate
@c man end
people stuck with Windows. Note that the Windows port is
@strong{neither tested nor maintained} by me---all questions and
problems should be reported to Wget mailing list at
-@email{wget@@sunsite.auc.dk} where the maintainers will look at them.
+@email{wget@@sunsite.dk} where the maintainers will look at them.
@node Signals, , Portability, Various
@section Signals
This chapter contains some references I consider useful.
@menu
-* Robots:: Wget as a WWW robot.
+* Robot Exclusion:: Wget's support for RES.
* Security Considerations:: Security with Wget.
* Contributors:: People who helped.
@end menu
-@node Robots, Security Considerations, Appendices, Appendices
-@section Robots
-@cindex robots
+@node Robot Exclusion, Security Considerations, Appendices, Appendices
+@section Robot Exclusion
+@cindex robot exclusion
@cindex robots.txt
@cindex server maintenance
sucking all the available data in progress. @samp{wget -r @var{site}},
and you're set. Great? Not for the server admin.
-While Wget is retrieving static pages, there's not much of a problem.
-But for Wget, there is no real difference between the smallest static
-page and the hardest, most demanding CGI or dynamic page. For instance,
-a site I know has a section handled by an, uh, bitchin' CGI script that
-converts all the Info files to HTML. The script can and does bring the
-machine to its knees without providing anything useful to the
-downloader.
-
-For such and similar cases various robot exclusion schemes have been
-devised as a means for the server administrators and document authors to
-protect chosen portions of their sites from the wandering of robots.
-
-The more popular mechanism is the @dfn{Robots Exclusion Standard}
-written by Martijn Koster et al. in 1994. It is specified by placing a
-file named @file{/robots.txt} in the server root, which the robots are
-supposed to download and parse. Wget supports this specification.
-
-Norobots support is turned on only when retrieving recursively, and
-@emph{never} for the first page. Thus, you may issue:
+As long as Wget is only retrieving static pages, and doing it at a
+reasonable rate (see the @samp{--wait} option), there's not much of a
+problem. The trouble is that Wget can't tell the difference between the
+smallest static page and the most demanding CGI. A site I know has a
+section handled by an, uh, @dfn{bitchin'} CGI Perl script that converts
+Info files to HTML on the fly. The script is slow, but works well
+enough for human users viewing an occasional Info file. However, when
+someone's recursive Wget download stumbles upon the index page that
+links to all the Info files through the script, the system is brought to
+its knees without providing anything useful to the downloader.
+
+To avoid this kind of accident, as well as to preserve privacy for
+documents that need to be protected from well-behaved robots, the
+concept of @dfn{robot exclusion} has been invented. The idea is that
+the server administrators and document authors can specify which
+portions of the site they wish to protect from the robots.
+
+The most popular mechanism, and the de facto standard supported by all
+the major robots, is the ``Robots Exclusion Standard'' (RES) written by
+Martijn Koster et al. in 1994. It specifies the format of a text file
+containing directives that instruct the robots which URL paths to avoid.
+To be found by the robots, the specifications must be placed in
+@file{/robots.txt} in the server root, which the robots are supposed to
+download and parse.
+
+Although Wget is not a web robot in the strictest sense of the word, it
+can downloads large parts of the site without the user's intervention to
+download an individual page. Because of that, Wget honors RES when
+downloading recursively. For instance, when you issue:
@example
-wget -r http://fly.srk.fer.hr/
+wget -r http://www.server.com/
@end example
-First the index of fly.srk.fer.hr will be downloaded. If Wget finds
-anything worth downloading on the same host, only @emph{then} will it
-load the robots, and decide whether or not to load the links after all.
-@file{/robots.txt} is loaded only once per host.
+First the index of @samp{www.server.com} will be downloaded. If Wget
+finds that it wants to download more documents from that server, it will
+request @samp{http://www.server.com/robots.txt} and, if found, use it
+for further downloads. @file{robots.txt} is loaded only once per each
+server.
-Note that the exlusion standard discussed here has undergone some
-revisions. However, but Wget supports only the first version of
-@sc{res}, the one written by Martijn Koster in 1994, available at
-@url{http://info.webcrawler.com/mak/projects/robots/norobots.html}. A
-later version exists in the form of an internet draft
-<draft-koster-robots-00.txt> titled ``A Method for Web Robots Control'',
-which expired on June 4, 1997. I am not aware if it ever made to an
-@sc{rfc}. The text of the draft is available at
-@url{http://info.webcrawler.com/mak/projects/robots/norobots-rfc.html}.
-Wget does not yet support the new directives specified by this draft,
-but we plan to add them.
+Until version 1.8, Wget supported the first version of the standard,
+written by Martijn Koster in 1994 and available at
+@url{http://www.robotstxt.org/wc/norobots.html}. As of version 1.8,
+Wget has supported the additional directives specified in the internet
+draft @samp{<draft-koster-robots-00.txt>} titled ``A Method for Web
+Robots Control''. The draft, which has as far as I know never made to
+an @sc{rfc}, is available at
+@url{http://www.robotstxt.org/wc/norobots-rfc.txt}.
-This manual no longer includes the text of the old standard.
+This manual no longer includes the text of the Robot Exclusion Standard.
The second, less known mechanism, enables the author of an individual
document to specify whether they want the links from the file to be
@end example
This is explained in some detail at
-@url{http://info.webcrawler.com/mak/projects/robots/meta-user.html}.
-Wget supports this method of robot exclusion in addition to the usual
-@file{/robots.txt} exclusion.
+@url{http://www.robotstxt.org/wc/meta-user.html}. Wget supports this
+method of robot exclusion in addition to the usual @file{/robots.txt}
+exclusion.
+
+If you know what you are doing and really really wish to turn off the
+robot exclusion, set the @code{robots} variable to @samp{off} in your
+@file{.wgetrc}. You can achieve the same effect from the command line
+using the @code{-e} switch, e.g. @samp{wget -e robots=off @var{url}...}.
-@node Security Considerations, Contributors, Robots, Appendices
+@node Security Considerations, Contributors, Robot Exclusion, Appendices
@section Security Considerations
@cindex security
main issues, and some solutions.
@enumerate
-@item
-The passwords on the command line are visible using @code{ps}. If this
-is a problem, avoid putting passwords from the command line---e.g. you
-can use @file{.netrc} for this.
+@item The passwords on the command line are visible using @code{ps}.
+The best way around it is to use @code{wget -i -} and feed the @sc{url}s
+to Wget's standard input, each on a separate line, terminated by
+@kbd{C-d}. Another workaround is to use @file{.netrc} to store
+passwords; however, storing unencrypted passwords is also considered a
+security risk.
@item
Using the insecure @dfn{basic} authentication scheme, unencrypted
authentication.
@item
-Brian Gough---a generous donation.
+The people who provided donations for development, including Brian
+Gough.
@end itemize
The following people have provided patches, bug/build reports, useful
suggestions, beta testing services, fan mail and all the other things
that make maintenance so much fun:
+Ian Abbott
Tim Adam,
Adrian Aichner,
Martin Baehr,
Dieter Baron,
-Roger Beeman and the Gurus at Cisco,
+Roger Beeman,
Dan Berger,
+T. Bharath,
+Paul Bludov,
+Daniel Bodea,
Mark Boyns,
John Burden,
Wanderlei Cavassin,
@ifinfo
Damir Dzeko,
@end ifinfo
+Alan Eldridge,
@iftex
Aleksandar Erkalovi@'{c},
@end iftex
Aleksandar Erkalovic,
@end ifinfo
Andy Eskilsson,
+Christian Fraenkel,
Masashi Fujita,
Howard Gayle,
Marcel Gerrits,
+Lemble Gregory,
Hans Grobler,
Mathieu Guillaume,
Dan Harkless,
-Heiko Herold,
+Herold Heiko,
+Jochen Hein,
Karl Heuer,
HIROSE Masaaki,
Gregor Hoffleit,
Erik Magnus Hulthen,
Richard Huveneers,
+Jonas Jensen,
Simon Josefsson,
@iftex
Mario Juri@'{c},
@ifinfo
Mario Juric,
@end ifinfo
+@iftex
+Hack Kampbj@o rn,
+@end iftex
+@ifinfo
+Hack Kampbjorn,
+@end ifinfo
Const Kaplinsky,
@iftex
Goran Kezunovi@'{c},
Goran Kezunovic,
@end ifinfo
Robert Kleine,
+KOJIMA Haime,
Fila Kolodny,
Alexander Kourakos,
Martin Kraemer,
@end ifinfo
Hrvoje Lacko,
Daniel S. Lewart,
+@iftex
+Nicol@'{a}s Lichtmeier,
+@end iftex
+@ifinfo
+Nicolas Lichtmeier,
+@end ifinfo
Dave Love,
Alexander V. Lukyanov,
Jordan Mendelson,
Lin Zhe Min,
+Tim Mooney,
Simon Munton,
Charlie Negyesi,
R. K. Owen,
Jan Prikryl,
@end ifinfo
Marin Purgar,
+@iftex
+Csaba R@'{a}duly,
+@end iftex
+@ifinfo
+Csaba Raduly,
+@end ifinfo
Keith Refson,
Tyler Riddle,
Tobias Ringstrom,
Heinz Salzmann,
Robert Schmidt,
Andreas Schwab,
+Chris Seawood,
Toomas Soome,
Tage Stabell-Kulo,
Sven Sternberger,
Markus Strasser,
+John Summerfield,
Szakacsits Szabolcs,
Mike Thomas,
+Philipp Thomas,
+Dave Turner,
Russell Vincent,
Charles G Waldman,
Douglas E. Wegscheid,
@cindex copying
@cindex GPL
@cindex GFDL
-
-Wget is @dfn{free software}, where ``free'' refers to liberty, not
-price. As the GNU people like to say, think of ``free speech'' rather
-than ``free beer''. The exact legal distribution terms follow below,
-but in short, you have the right (freedom) to run and change Wget and
-distribute it to other people, and even---if you want---charge money for
-any of these things. The sole restriction is that you have to grant
-your recipients the same rights.
-
-This method of licensing software is also known as @dfn{open-source},
-because it requires that the recipients always receive a program's
-source code along with the program.
-
-More specifically:
+@cindex free software
+
+GNU Wget is licensed under the GNU GPL, which makes it @dfn{free
+software}.
+
+Please note that ``free'' in ``free software'' refers to liberty, not
+price. As some GNU project advocates like to point out, think of ``free
+speech'' rather than ``free beer''. The exact and legally binding
+distribution terms are spelled out below; in short, you have the right
+(freedom) to run and change Wget and distribute it to other people, and
+even---if you want---charge money for doing either. The important
+restriction is that you have to grant your recipients the same rights
+and impose the same restrictions.
+
+This method of licensing software is also known as @dfn{open source}
+because, among other things, it makes sure that all recipients will
+receive the source code along with the program, and be able to improve
+it. The GNU project prefers the term ``free software'' for reasons
+outlined at
+@url{http://www.gnu.org/philosophy/free-software-for-freedom.html}.
+
+The exact license terms are defined by this paragraph and the GNU
+General Public License it refers to:
@quotation
-This program is free software; you can redistribute it and/or modify it
+GNU Wget is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
+GNU Wget is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
+A copy of the GNU General Public License is included as part of this
+manual; if you did not receive it, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end quotation
projects / wget / blobdiff