+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Quickstart to Using Privoxy</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.64
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
-TITLE="Privoxy User Manual"
+TITLE="Privoxy 3.0.14 User Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
-TITLE="Note to Upgraders"
-HREF="upgradersnote.html"><LINK
+TITLE="What's New in this Release"
+HREF="whatsnew.html"><LINK
REL="NEXT"
TITLE="Starting Privoxy"
HREF="startup.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
-HREF="../p_doc.css"></HEAD
+HREF="../p_doc.css"><META
+HTTP-EQUIV="Content-Type"
+CONTENT="text/html;
+charset=ISO-8859-1">
+<LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
+</head
><BODY
CLASS="SECT1"
BGCOLOR="#EEEEEE"
><DIV
CLASS="NAVHEADER"
><TABLE
+SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
><TH
COLSPAN="3"
ALIGN="center"
->Privoxy User Manual</TH
+>Privoxy 3.0.14 User Manual</TH
></TR
><TR
><TD
ALIGN="left"
VALIGN="bottom"
><A
-HREF="upgradersnote.html"
+HREF="whatsnew.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="bottom"
><A
HREF="startup.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
CLASS="SECT1"
><A
NAME="QUICKSTART"
->4. Quickstart to Using <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-></A
+>4. Quickstart to Using Privoxy</A
></H1
><P
> <P
><UL
><LI
><P
-> If upgrading, from versions before 2.9.16, please back up any configuration
- files. See the <A
-HREF="upgradersnote.html"
->Note to Upgraders</A
-> Section.
- </P
-></LI
-><LI
-><P
> Install <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> as HTTP and
- HTTPS proxy by setting the proxy configuration for address of
+ HTTPS (SSL) <A
+HREF="http://en.wikipedia.org/wiki/Proxy_server"
+TARGET="_top"
+>proxy</A
+>
+ by setting the proxy configuration for address of
<TT
CLASS="LITERAL"
>127.0.0.1</TT
CLASS="LITERAL"
>8118</TT
>.
- (<SPAN
-CLASS="APPLICATION"
->Junkbuster</SPAN
-> and earlier versions of
<SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> used port 8000.) See the section <A
-HREF="startup.html"
->Starting <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-></A
-> below
- for more details on this.
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>DO NOT</I
+></SPAN
+> activate proxying for <TT
+CLASS="LITERAL"
+>FTP</TT
+> or
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
</P
></LI
><LI
><P
> Flush your browser's disk and memory caches, to remove any cached ad images.
+ If using <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> to manage
+ <A
+HREF="http://en.wikipedia.org/wiki/Browser_cookie"
+TARGET="_top"
+>cookies</A
+>,
+ you should remove any currently stored cookies too.
</P
></LI
><LI
> A default installation should provide a reasonable starting point for
most. There will undoubtedly be occasions where you will want to adjust the
configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases.
+ to no initial configuration is required in most cases, you may want
+ to enable the
+ <A
+HREF="config.html#ENABLE-EDIT-ACTIONS"
+TARGET="_top"
+>web-based action editor</A
+> though.
+ Be sure to read the warnings first.
</P
><P
> See the <A
>Configuration section</A
> for more
configuration options, and how to customize your installation.
-
- </P
+ You might also want to look at the <A
+HREF="quickstart.html#QUICKSTART-AD-BLOCKING"
+>next section</A
+> for a quick
+ introduction to how <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> blocks ads and
+ banners.</P
></LI
><LI
><P
-> If you experience ads that slipped through, innocent images that are
+> If you experience ads that slip through, innocent images that are
blocked, or otherwise feel the need to fine-tune
<SPAN
CLASS="APPLICATION"
>Privoxy's</SPAN
-> behaviour, take a look at the <A
+> behavior, take a look at the <A
HREF="actions-file.html"
>actions files</A
>. As a quick start, you might
CLASS="QUOTE"
>"<A
HREF="appendix.html#ACTIONSANAT"
->Anatomy of an
+>Troubleshooting: Anatomy of an
Action</A
>"</SPAN
-> has hints how to debug actions that
+> has hints on how to understand and debug actions that
<SPAN
CLASS="QUOTE"
>"misbehave"</SPAN
HREF="contact.html"
>Contacting the
Developers</A
-> on how to report bugs or problems with websites or to get
+> on how to report bugs, problems with websites or to get
help.
</P
></LI
><LI
><P
-> Now enjoy surfing with enhanced comfort and privacy!
+> Now enjoy surfing with enhanced control, comfort and privacy!
</P
></LI
></UL
>
This section will provide a quick summary of ad blocking so
you can get up to speed quickly without having to read the more extensive
- information provided below, though this is highly recommeneded.</P
+ information provided below, though this is highly recommended.</P
><P
> First a bit of a warning ... blocking ads is much like blocking SPAM: the
more aggressive you are about it, the more likely you are to block
- things that were not intended. So there is a trade off here. If you want
+ things that were not intended. And the more likely that some things
+ may not work as intended. So there is a trade off here. If you want
extreme ad free browsing, be prepared to deal with more
<SPAN
CLASS="QUOTE"
>"problem"</SPAN
> sites, and to spend more time adjusting the
configuration to solve these unintended consequences. In short, there is
- not an easy way to eliminate <I
+ not an easy way to eliminate <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>all</I
+></SPAN
> ads. Either take
- the easy way and settle for <I
+ the easy way and settle for <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>most</I
+></SPAN
> ads blocked with the
default configuration, or jump in and tweak it for your personal surfing
habits and preferences.</P
HREF="actions-file.html#AF-PATTERNS"
>patterns</A
> that use
- wildcards so they can apply potentially to a range of similar URLs.</P
+ wildcards so they can apply potentially to a range of similar URLs. The
+ actions, together with the URL patterns are called a section.</P
><P
-> When you connect to a website, the full path of the URL will either match one
- of the <SPAN
-CLASS="QUOTE"
->"actions"</SPAN
-> as defined in
- <SPAN
+> When you connect to a website, the full URL will either match one or more
+ of the sections as defined in <SPAN
CLASS="APPLICATION"
>Privoxy's</SPAN
-> configuration, or not. If so, then
- <SPAN
+> configuration,
+ or not. If so, then <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> will perform the action accordingly. If
- not, then nothing special happens. Futhermore, web pages may contain
- embedded, secondary URLs that your web browser will display as it parses the
- original page's HTML content. An ad image for instance, is just a URL
+> will perform the
+ respective actions. If not, then nothing special happens. Furthermore, web
+ pages may contain embedded, secondary URLs that your web browser will
+ use to load additional components of the page, as it parses the
+ original page's HTML content. An ad image for instance, is just an URL
embedded in the page somewhere. The image itself may be on the same server,
or a server somewhere else on the Internet. Complex web pages will have many
- such embedded URLs.</P
+ such embedded URLs. <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> can deal with each URL individually, so, for
+ instance, the main page text is not touched, but images from such-and-such
+ server are blocked.</P
><P
-> The actions we need to know about for ad blocking are: <A
+> The most important actions for basic ad blocking are: <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#BLOCK"
>block</A
->, <A
+></TT
+>, <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#HANDLE-AS-IMAGE"
>handle-as-image</A
->, and <A
+></TT
+>,
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
+>handle-as-empty-document</A
+></TT
+>,and
+ <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
>set-image-blocker</A
+></TT
>:</P
><P
> <P
><UL
><LI
><P
-> <A
+> <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#BLOCK"
-><I
-CLASS="EMPHASIS"
->block</I
-></A
-> - this action stops
- any contact between your browser and any URL patterns that match this
- action's configuration. It can be used for blocking ads, but also anything
- that is determined to be unwanted. By itself, it simply stops any
- communication with the remote server. If this is the only action that
- matches for this particular URL, then <SPAN
+>block</A
+></TT
+> - this is perhaps
+ the single most used action, and is particularly important for ad blocking.
+ This action stops any contact between your browser and any URL patterns
+ that match this action's configuration. It can be used for blocking ads,
+ but also anything that is determined to be unwanted. By itself, it simply
+ stops any communication with the remote server and sends
+ <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> will
- display its own BLOCKED page to let you now what has happened.
+>'s own built-in BLOCKED page instead to
+ let you now what has happened (with some exceptions, see below).
</P
></LI
><LI
><P
-> <A
+> <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#HANDLE-AS-IMAGE"
-><I
-CLASS="EMPHASIS"
->handle-as-image</I
-></A
+>handle-as-image</A
+></TT
> -
- forces <SPAN
+ tells <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> to treat this URL as an image.
+ <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> to treat this URL as if it were
- an image. <SPAN
+>'s default configuration already does this
+ for all common image types (e.g. GIF), but there are many situations where this
+ is not so easy to determine. So we'll force it in these cases. This is particularly
+ important for ad blocking, since only if we know that it's an image of
+ some kind, can we replace it with an image of our choosing, instead of the
+ <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> knows about common image
- types (e.g. GIF), but there are many situations where this does not apply.
- So we'll force it. This is particularly important for ad blocking, since
- once we can treat it as an image, we can make more intelligent decisisions
- on how to handle it. There are some limitations to this though. For
- instance, you can't just force an image substituion for an entire HTML page
- in most situations.
+> BLOCKED page (which would only result in
+ a <SPAN
+CLASS="QUOTE"
+>"broken image"</SPAN
+> icon). There are some limitations to this
+ though. For instance, you can't just brute-force an image substitution for
+ an entire HTML page in most situations.
</P
></LI
><LI
><P
-> <A
+> <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
+>handle-as-empty-document</A
+></TT
+> -
+ sends an empty document instead of <SPAN
+CLASS="APPLICATION"
+>Privoxy's</SPAN
+>
+ normal BLOCKED HTML page. This is useful for file types that are neither
+ HTML nor images, such as blocking JavaScript files.
+ </P
+></LI
+><LI
+><P
+> <TT
+CLASS="LITERAL"
+><A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
-><I
-CLASS="EMPHASIS"
->set-image-blocker</I
-></A
-> -
- tells <SPAN
+>set-image-blocker</A
+></TT
+> - tells
+ <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> what to display in place of
- an ad image that has hit a block rule. For this to come into play,
- the URL must match a block action somewhere in the configuration.
- <I
-CLASS="EMPHASIS"
->And</I
->, it must also either be of a known image type, or
- match an <A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
+> what to display in place of an ad image that
+ has hit a block rule. For this to come into play, the URL must match a
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> action somewhere in the
+ configuration, <SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
->handle-as-image</I
-></A
->
- action.
+>and</I
+></SPAN
+>, it must also match an
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#HANDLE-AS-IMAGE"
+>handle-as-image</A
+></TT
+> action.
</P
><P
> The configuration options on what to display instead of the ad are:
><TBODY
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>pattern</I
-> - a checkboard pattern, so that an ad
+></SPAN
+> - a checkerboard pattern, so that an ad
replacement is obvious. This is the default.
</TD
></TR
><TBODY
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>blank</I
+></SPAN
> - A very small empty GIF image is displayed.
This is the so-called <SPAN
CLASS="QUOTE"
><TBODY
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>http://<URL></I
-> - A redirect to any URL of the
- user's choosing (advanced usage).
+></SPAN
+> - A redirect to any image anywhere
+ of the user's choosing (advanced usage).
</TD
></TR
></TBODY
></UL
></P
><P
+> Advanced users will eventually want to explore <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filters</A
+></TT
+> as well. Filters
+ are very different from <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>blocks</A
+></TT
+>.
+ A <SPAN
+CLASS="QUOTE"
+>"block"</SPAN
+> blocks a site, page, or unwanted contented. Filters
+ are a way of filtering or modifying what is actually on the page. An example
+ filter usage: a text replacement of <SPAN
+CLASS="QUOTE"
+>"no-no"</SPAN
+> for
+ <SPAN
+CLASS="QUOTE"
+>"nasty-word"</SPAN
+>. That is a very simple example. This process can be
+ used for ad blocking, but it is more in the realm of advanced usage and has
+ some pitfalls to be wary off.</P
+><P
> The quickest way to adjust any of these settings is with your browser through
the special <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> editor at <A
+> editor at <A
HREF="http://config.privoxy.org/show-status"
TARGET="_top"
>http://config.privoxy.org/show-status</A
TARGET="_top"
>http://p.p/show-status</A
>). This
- is an internal page, and does not require Internet access. Select the
- appropriate <SPAN
+ is an internal page, and does not require Internet access.</P
+><P
+> Note that as of <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> 3.0.7 beta the
+ action editor is disabled by default. Check the
+ <A
+HREF="config.html#ENABLE-EDIT-ACTIONS"
+TARGET="_top"
+>enable-edit-actions
+ section in the configuration file</A
+> to learn why and in which
+ cases it's safe to enable again.</P
+><P
+> If you decided to enable the action editor, select the appropriate
+ <SPAN
CLASS="QUOTE"
>"actions"</SPAN
> file, and click
> <DIV
CLASS="FIGURE"
><A
-NAME="AEN349"
+NAME="AEN534"
></A
><P
><B
CLASS="MEDIAOBJECT"
><P
><IMG
-SRC="../images/files-in-use.jpg"
-ALT="Screenshot of Files in Use"
-></IMG
-></P
+SRC="files-in-use.jpg"></P
></DIV
></DIV
>
></LI
><LI
><P
-> You should have an Actions section labeled <I
-CLASS="EMPHASIS"
->+block</I
->.
- If not, click the <SPAN
+> You should have a section with only
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> listed under
+ <SPAN
+CLASS="QUOTE"
+>"Actions:"</SPAN
+>.
+ If not, click a <SPAN
CLASS="QUOTE"
>"<SPAN
CLASS="GUIBUTTON"
->Edit</SPAN
+>Insert new section below</SPAN
>"</SPAN
-> button just
- under the word <SPAN
-CLASS="QUOTE"
->"Actions"</SPAN
->. This will bring up a list of all
- actions. Find <I
-CLASS="EMPHASIS"
->block</I
-> near the top, and click in the
+>
+ button, and in the new section that just appeared, click the
<SPAN
+CLASS="GUIBUTTON"
+>Edit</SPAN
+> button right under the word <SPAN
+CLASS="QUOTE"
+>"Actions:"</SPAN
+>.
+ This will bring up a list of all actions. Find
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> near the top, and click
+ in the <SPAN
CLASS="QUOTE"
>"Enabled"</SPAN
-> column, then
- <SPAN
+> column, then <SPAN
CLASS="QUOTE"
>"<SPAN
CLASS="GUIBUTTON"
>Submit</SPAN
>"</SPAN
-> just below the list.
+>
+ just below the list.
</P
></LI
><LI
><P
-> Now, in the <I
-CLASS="EMPHASIS"
->+block</I
-> actions section, click the
- <SPAN
+> Now, in the <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#BLOCK"
+>block</A
+></TT
+> actions section,
+ click the <SPAN
CLASS="QUOTE"
>"<SPAN
CLASS="GUIBUTTON"
CLASS="QUOTE"
>"<SPAN
CLASS="GUIMENUITEM"
->Copy Link
- Location</SPAN
+>Copy Link Location</SPAN
>"</SPAN
->. Remove the <TT
+>.
+ Remove the <TT
CLASS="LITERAL"
>http://</TT
-> at
- the beginning of the URL. Then, click
+> at the beginning of the URL. Then, click
<SPAN
CLASS="QUOTE"
>"<SPAN
CLASS="GUIBUTTON"
>Submit</SPAN
>"</SPAN
->.
+> (or
+ <SPAN
+CLASS="QUOTE"
+>"<SPAN
+CLASS="GUIBUTTON"
+>OK</SPAN
+>"</SPAN
+> if in a pop-up window).
</P
></LI
><LI
to now go to the <A
HREF="actions-file.html#ACT-EXAMPLES"
>Actions Files Tutorial</A
->.</P
+>.
+ The ideas explained therein also apply to the web-based editor.</P
+><P
+> There are also various
+ <A
+HREF="actions-file.html#FILTER"
+>filters</A
+> that can be used for ad blocking
+ (filters are a special subset of actions). These
+ fall into the <SPAN
+CLASS="QUOTE"
+>"advanced"</SPAN
+> usage category, and are explained in
+ depth in later sections. </P
></DIV
></DIV
><DIV
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
ALIGN="left"
VALIGN="top"
><A
-HREF="upgradersnote.html"
+HREF="whatsnew.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="top"
><A
HREF="index.html"
+ACCESSKEY="H"
>Home</A
></TD
><TD
VALIGN="top"
><A
HREF="startup.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
WIDTH="33%"
ALIGN="left"
VALIGN="top"
->Note to Upgraders</TD
+>What's New in this Release</TD
><TD
WIDTH="34%"
ALIGN="center"
WIDTH="33%"
ALIGN="right"
VALIGN="top"
->Starting <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-></TD
+>Starting Privoxy</TD
></TR
></TABLE
></DIV