X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Fquickstart.html;h=f7e26a6fae7476265f260786d61ba652b089ad50;hp=58ac3ba891ad27cef65cee41936c4d08715cce7e;hb=3c890b0540031fa87cc28514b3e4d0e23124fbcd;hpb=7a99a61ab1a3ce0401821aedcd06eba19a698b2a diff --git a/doc/webserver/user-manual/quickstart.html b/doc/webserver/user-manual/quickstart.html index 58ac3ba8..f7e26a6f 100644 --- a/doc/webserver/user-manual/quickstart.html +++ b/doc/webserver/user-manual/quickstart.html @@ -1,437 +1,933 @@ - - - -
-Install Privoxy. See the Installation Section below for platform - specific information.
-Advanced users and those who want to offer Privoxy service to more than just their local - machine should check the main config file, - especially the security-relevant options. These are - off by default.
-Start Privoxy, if the - installation program has not done this already (may vary according to - platform). See the section Starting - Privoxy.
-Set your browser to use Privoxy - as HTTP and HTTPS (SSL) proxy - by setting the proxy configuration for address of 127.0.0.1 and port 8118. - DO NOT activate - proxying for FTP or any protocols besides - HTTP and HTTPS (SSL) unless you intend to prevent your browser from - using these protocols.
-Flush your browser's disk and memory caches, to remove any cached - ad images. If using Privoxy to - manage cookies, you should remove any currently stored cookies - too.
-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, - you may want to enable the web-based action editor though. Be sure to read the - warnings first.
- -See the Configuration section for - more configuration options, and how to customize your installation. - You might also want to look at the next section for a quick - introduction to how Privoxy blocks - ads and banners.
-If you experience ads that slip through, innocent images that are - blocked, or otherwise feel the need to fine-tune Privoxy's behavior, take a look at the actions files. As a quick start, you might - find the richly commented - examples helpful. You can also view and edit the actions files - through the web-based user interface. The Appendix "Troubleshooting: Anatomy - of an Action" has hints on how to understand and debug - actions that "misbehave".
-Please see the section Contacting the - Developers on how to report bugs, problems with websites or to - get help.
-Now enjoy surfing with enhanced control, comfort and privacy!
-Ad blocking is but one of Privoxy's - array of features. Many of these features are for the technically - minded advanced user. But, ad and banner blocking is surely common - ground for everybody.
- -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 recommended.
- -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. 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 - "problem" sites, and to spend more time - adjusting the configuration to solve these unintended consequences. In - short, there is not an easy way to eliminate all ads. Either take the easy - way and settle for most ads blocked with the default configuration, - or jump in and tweak it for your personal surfing habits and - preferences.
- -Secondly, a brief explanation of Privoxy's "actions". - "Actions" in this context, are the - directives we use to tell Privoxy to - perform some task relating to HTTP transactions (i.e. web browsing). We - tell Privoxy to take some "action". Each action has a unique name and function. - While there are many potential actions - in Privoxy's arsenal, only a few are - used for ad blocking. Actions, - and action configuration files, are - explained in depth below.
- -Actions are specified in Privoxy's - configuration, followed by one or more URLs to which the action should - apply. URLs can actually be URL type patterns that use wildcards so they - can apply potentially to a range of similar URLs. The actions, together - with the URL patterns are called a section.
- -When you connect to a website, the full URL will either match one or - more of the sections as defined in Privoxy's configuration, or not. If so, then - Privoxy 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. Privoxy 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.
- -The most important actions for basic ad blocking are: block, handle-as-image, - handle-as-empty-document,and - set-image-blocker:
- -block - 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 Privoxy's - own built-in BLOCKED page instead to let you now what has happened - (with some exceptions, see below).
-handle-as-image - - tells Privoxy to treat this URL as - an image. Privoxy'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 Privoxy BLOCKED - page (which would only result in a "broken - image" 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.
-handle-as-empty-document - - sends an empty document instead of Privoxy's normal BLOCKED HTML page. This is - useful for file types that are neither HTML nor images, such as - blocking JavaScript files.
-set-image-blocker - - tells Privoxy 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, and, it must also match an handle-as-image - action.
- -The configuration options on what to display instead of the ad - are:
- -pattern - a checkerboard pattern, so - that an ad replacement is obvious. This is the default. | -
blank - A very small empty GIF image is - displayed. This is the so-called "invisible" configuration option. | -
http://<URL> - A redirect to any - image anywhere of the user's choosing (advanced usage). | -
Advanced users will eventually want to explore Privoxy filters as well. Filters are very - different from blocks. A "block" 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 "no-no" for "nasty-word". - 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.
- -The quickest way to adjust any of these settings is with your - browser through the special Privoxy - editor at http://config.privoxy.org/show-status (shortcut: http://p.p/show-status). This is an - internal page, and does not require Internet access.
- -Note that as of Privoxy 3.0.7 beta - the action editor is disabled by default. Check the enable-edit-actions - section in the configuration file to learn why and in which cases - it's safe to enable again.
- -If you decided to enable the action editor, select the appropriate - "actions" file, and click "Edit". It is best to put - personal or local preferences in user.action - since this is not meant to be overwritten during upgrades, and will - over-ride the settings in other files. Here you can insert new - "actions", and URLs for ad blocking or other - purposes, and make other adjustments to the configuration. Privoxy will detect these changes - automatically.
- -A quick and simple step by step example:
- -Right click on the ad image to be blocked, then select - "Copy Link - Location" from the pop-up menu.
-Set your browser to http://config.privoxy.org/show-status
-Find user.action in the top section, - and click on "Edit":
- - -You should have a section with only block listed under "Actions:". If not, click a "Insert new section - below" button, and in the new section that just - appeared, click the Edit button - right under the word "Actions:". This - will bring up a list of all actions. Find block near the - top, and click in the "Enabled" column, - then "Submit" just below the list.
-Now, in the block actions section, click the - "Add" - button, and paste the URL the browser got from "Copy Link - Location". Remove the http:// at the beginning of the URL. Then, click - "Submit" - (or "OK" - if in a pop-up window).
-Now go back to the original page, and press SHIFT-Reload (or flush all browser caches). The image - should be gone now.
-This is a very crude and simple example. There might be good reasons - to use a wildcard pattern match to include potentially similar images - from the same site. For a more extensive explanation of "patterns", and the entire actions concept, see the Actions section.
- -For advanced users who want to hand edit their config files, you - might want to now go to the Actions Files Tutorial. The ideas - explained therein also apply to the web-based editor.
- -There are also various filters that can be used for ad blocking - (filters are a special subset of actions). These fall into the - "advanced" usage category, and are explained - in depth in later sections.
-Prev | - -Home | - -Next | -
What's New in this - Release | - -- - | Starting Privoxy | -
Install Privoxy. See the Installation Section below for platform specific + information. +
Advanced users and those who want to offer Privoxy + service to more than just their local machine should check the main config file, especially the security-relevant options. These are + off by default. +
Start Privoxy, if the installation program has + not done this already (may vary according to platform). See the section + Starting Privoxy. +
Set your browser to use Privoxy as HTTP and + HTTPS (SSL) proxy + by setting the proxy configuration for address of + 127.0.0.1 and port 8118. + DO NOT activate proxying for FTP or + any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your + browser from using these protocols. +
Flush your browser's disk and memory caches, to remove any cached ad images. + If using Privoxy to manage + cookies, + you should remove any currently stored cookies too. +
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, you may want + to enable the + web-based action editor though. + Be sure to read the warnings first. +
See the Configuration section for more + configuration options, and how to customize your installation. + You might also want to look at the next section for a quick + introduction to how Privoxy blocks ads and + banners.
If you experience ads that slip through, innocent images that are + blocked, or otherwise feel the need to fine-tune + Privoxy's behavior, take a look at the actions files. As a quick start, you might + find the richly commented examples + helpful. You can also view and edit the actions files through the web-based user interface. The + Appendix "Troubleshooting: Anatomy of an + Action" has hints on how to understand and debug actions that + "misbehave". +
Please see the section Contacting the + Developers on how to report bugs, problems with websites or to get + help. +
Now enjoy surfing with enhanced control, comfort and privacy! +
Ad blocking is but one of Privoxy's + array of features. Many of these features are for the technically minded advanced + user. But, ad and banner blocking is surely common ground for everybody.
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 recommended.
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. 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 + "problem" sites, and to spend more time adjusting the + configuration to solve these unintended consequences. In short, there is + not an easy way to eliminate all ads. Either take + the easy way and settle for most ads blocked with the + default configuration, or jump in and tweak it for your personal surfing + habits and preferences.
Secondly, a brief explanation of Privoxy's + "actions". "Actions" in this context, are + the directives we use to tell Privoxy to perform + some task relating to HTTP transactions (i.e. web browsing). We tell + Privoxy to take some "action". Each + action has a unique name and function. While there are many potential + actions in Privoxy's + arsenal, only a few are used for ad blocking. Actions, and action + configuration files, are explained in depth below.
Actions are specified in Privoxy's configuration, + followed by one or more URLs to which the action should apply. URLs + can actually be URL type patterns that use + wildcards so they can apply potentially to a range of similar URLs. The + actions, together with the URL patterns are called a section.
When you connect to a website, the full URL will either match one or more + of the sections as defined in Privoxy's configuration, + or not. If so, then Privoxy 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. Privoxy 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.
The most important actions for basic ad blocking are: block, handle-as-image, + handle-as-empty-document,and + set-image-blocker:
block - 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 + Privoxy's own built-in BLOCKED page instead to + let you now what has happened (with some exceptions, see below). +
handle-as-image - + tells Privoxy to treat this URL as an image. + Privoxy'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 + Privoxy BLOCKED page (which would only result in + a "broken image" 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. +
handle-as-empty-document - + sends an empty document instead of Privoxy's + normal BLOCKED HTML page. This is useful for file types that are neither + HTML nor images, such as blocking JavaScript files. +
set-image-blocker - tells + Privoxy 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, and, it must also match an + handle-as-image action. +
The configuration options on what to display instead of the ad are: +
pattern - a checkerboard pattern, so that an ad + replacement is obvious. This is the default. + |
blank - A very small empty GIF image is displayed. + This is the so-called "invisible" configuration option. + |
http://<URL> - A redirect to any image anywhere + of the user's choosing (advanced usage). + |
Advanced users will eventually want to explore Privoxy + filters as well. Filters + are very different from blocks. + A "block" 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 "no-no" for + "nasty-word". 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.
The quickest way to adjust any of these settings is with your browser through + the special Privoxy editor at http://config.privoxy.org/show-status + (shortcut: http://p.p/show-status). This + is an internal page, and does not require Internet access.
Note that as of Privoxy 3.0.7 beta the + action editor is disabled by default. Check the + enable-edit-actions + section in the configuration file to learn why and in which + cases it's safe to enable again.
If you decided to enable the action editor, select the appropriate + "actions" file, and click + "Edit". It is best to put personal or + local preferences in user.action since this is not + meant to be overwritten during upgrades, and will over-ride the settings in + other files. Here you can insert new "actions", and URLs for ad + blocking or other purposes, and make other adjustments to the configuration. + Privoxy will detect these changes automatically.
A quick and simple step by step example:
Right click on the ad image to be blocked, then select + "Copy Link Location" from the + pop-up menu. +
Set your browser to + http://config.privoxy.org/show-status +
Find user.action in the top section, and click + on "Edit": +
You should have a section with only + block listed under + "Actions:". + If not, click a "Insert new section below" + button, and in the new section that just appeared, click the + Edit button right under the word "Actions:". + This will bring up a list of all actions. Find + block near the top, and click + in the "Enabled" column, then "Submit" + just below the list. +
Now, in the block actions section, + click the "Add" button, and paste the URL the + browser got from "Copy Link Location". + Remove the http:// at the beginning of the URL. Then, click + "Submit" (or + "OK" if in a pop-up window). +
Now go back to the original page, and press SHIFT-Reload + (or flush all browser caches). The image should be gone now. +
This is a very crude and simple example. There might be good reasons to use a + wildcard pattern match to include potentially similar images from the same + site. For a more extensive explanation of "patterns", and + the entire actions concept, see the Actions + section.
For advanced users who want to hand edit their config files, you might want + to now go to the Actions Files Tutorial. + The ideas explained therein also apply to the web-based editor.
There are also various + filters that can be used for ad blocking + (filters are a special subset of actions). These + fall into the "advanced" usage category, and are explained in + depth in later sections.