From 72a30d34004610b0175deb16348b1320660bdd6f Mon Sep 17 00:00:00 2001 From: hal9 Date: Thu, 21 Mar 2002 17:01:05 +0000 Subject: [PATCH] New section in Appendix. --- doc/source/user-manual.sgml | 285 +++++++++++++++++++++++++++++++++--- 1 file changed, 264 insertions(+), 21 deletions(-) diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index b0073171..a0d2d50f 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -6,7 +6,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.47 2002/03/11 13:13:27 swa Exp $ + $Id: user-manual.sgml,v 1.48 2002/03/12 06:33:01 hal9 Exp $ Written by and Copyright (C) 2001 the SourceForge IJBSWA team. http://ijbswa.sourceforge.net @@ -28,7 +28,7 @@ Hal Burgiss Junkbuster User Manual -$Id: user-manual.sgml,v 1.47 2002/03/11 13:13:27 swa Exp $ +$Id: user-manual.sgml,v 1.48 2002/03/12 06:33:01 hal9 Exp $ @@ -103,6 +103,9 @@ You can find the latest version of the user manual at - + Blocking of annoying pop-up browser windows. @@ -469,7 +472,7 @@ configuration section below. HB.) JunkBuster can be reached by the special URL http://i.j.b/ (or alternately - http://ijbswa.sourceforge.net/config/, + http://ijbswa.sourceforge.net/config/), which is an internal page. You will see the following section: @@ -612,7 +615,8 @@ Please choose from the following options: - Indicates that the blockfile is named blocklist.ini. + Indicates that the blockfile is named blocklist.ini. (A + default installation does not use this.) @@ -714,8 +718,10 @@ Please choose from the following options: are not saved to disk). Pop-ups are disabled for all sites. All sites are filtered through selected sections of re_filterfile. No sites are blocked. The JunkBuster logo is displayed for filtered ads and other - images . The syntax of this file is explained in detail below. + images. The syntax of this file is explained in detail below. Other actions files + are included, and you are free to use any of them. They have varying + degrees of aggressiveness. @@ -990,7 +996,7 @@ Please choose from the following options: It is highly recommended that you enable ERROR - reporting (debug 8192), at least until the next stable release. + reporting (debug 8192), at least until v3.0 is released. @@ -1478,7 +1484,9 @@ Please choose from the following options: + Some users have reported difficulties related to LPWA's use of . as the last element of the domain, and have said that this can be fixed with this: @@ -1533,7 +1541,7 @@ Please choose from the following options: Also, we're told they insist on getting cookies and JavaScript, so you should - add home.com to the cookie file. We consider JavaScript a security risk. + allow cookies from home.com. We consider JavaScript a potential security risk. Java need not be enabled. @@ -1875,13 +1883,19 @@ Removed references to Win32. HB 09/23/01 Junkbuster takes, and thus determines how images, cookies and various other aspects of HTTP content and transactions are handled. Images can be anything you want, including ads, banners, or just - some obnoxious image that you would rather not see. Cookies can be accepted + some obnoxious URL that you would rather not see. Cookies can be accepted or rejected, or accepted only during the current browser session (i.e. not written to disk). Changes to ijb.action should be immediately visible to Junkbuster without the need to restart. + + The easiest way to edit actions file is with a browser by + loading http://i.j.b/, and then select + Edit Actions List. A text editor can also be used. + + To determine which actions apply to a request, the URL of the request is compared to all patterns in this file. Every time it matches, the list of @@ -1890,11 +1904,6 @@ Removed references to Win32. HB 09/23/01 url="http://i.j.b/show-url-info">http://i.j.b/show-url-info. - - The actions file can be edited with a browser by loading - http://i.j.b/, and then select - Edit Actions. - There are four types of lines in this file: comments (begin with a @@ -2131,7 +2140,9 @@ Removed references to Win32. HB 09/23/01 - Block this URL totally. + Block this URL totally. In a default installation, a blocked + URL will result in bright red banner that says BLOCKED, + with a reason why it is being blocked. @@ -2415,8 +2426,11 @@ Removed references to Win32. HB 09/23/01 Treat this URL as an image. This only matters if it's also +blocked, - in which case a blocked image can be sent rather than a HTML page. - See +image-blocker{} below for the control over what is actually sent. + in which case a blocked image can be sent rather than a HTML page. + See +image-blocker{} below for the control over what is actually sent. + If you want invisible ads, they should be defined as + images and blocked. And also, + image-blocker should be set to blank. @@ -2768,6 +2782,16 @@ Removed references to Win32. HB 09/23/01 + + Note that many of these actions have the potential to cause a page to + misbehave, possibly even not to display at all. There are many ways + a site designer may choose to design his site, and what HTTP header + content he may depend on. There is no way to have hard and fast rules + for all sites. See the Appendix + for a brief example on troubleshooting actions. + + + @@ -3565,8 +3589,8 @@ For any other issues, feel free to use the + + + +Anatomy of an Action + + + The way Junkbuster applies actions + to any given URL can be complex, and not always so easy to understand what + is happening. And sometimes we need to be able to see + just what Junkbuster is doing. Especially, + if something Junkbuster is doing is causing + us a problem inadvertantly. It can be a little daunting to look at + the actions files themselves, since they tend to be filled with + regular expressions whose consequences are not always + so obvious. + + + + First, you enter one URL (or partial URL), and this page will tell you how + the currently configured Junkbuster + actions are being applied to that specific URL. This will not + help with filtering effects from the re_filterfile! It + also will not tell you about any other URLs that may be embedded within the + URL you are testing. For instance, images such as ads are expressed as URLs + within the raw page source of HTML pages. So you will only get info for the + actual URL that is pasted into the prompt area -- not any sub-URLs. If you + want to know about embedded URLs like ads, you will have to dig those out of + the HTML source. Use your browser's View Page Source option + for this. + + + + Let's look at an example, google.com, + one section at a time: + + + + + System default actions: + + { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter + -hide-forwarded -hide-from -hide-referer -hide-user-agent -image + -image-blocker -limit-connect -no-compression -no-cookies-keep + -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer } + + + + + + This is the top section, and only tells us of the compiled in defaults. This + is basically what Junkbuster would do if there + were not any actions defined, i.e. it does nothing. Every action + is disabled. This is not particularly informative for our purposes here. OK, + next section: + + + + + + Matches for http://google.com: + + { -add-header -block +deanimate-gifs -downgrade +fast-redirects + +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} + +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} + +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} + -hide-user-agent -image +image-blocker{blank} +no-compression + +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups + -vanilla-wafer -wafer } + / + + { -no-cookies-keep -no-cookies-read -no-cookies-set } + .google.com + + { -fast-redirects } + .google.com + + + + + + This is much more informative, and tells us how we have defined our + actions, and which ones match for our example, + google.com. The first grouping shows our default + settings, which would apply to all URLs. If you look at your actions + file, this would be the section just below the aliases section + near the top. This applies to all URLs as signified by the single forward + slash -- /. + + + + + These are the default actions we have enabled. But we can define additional + actions that would be exceptions to these general rules, and then list + specific URLs that these exceptions would apply to. Last match wins. + Just below this then are two explict matches for .google.com. + The first is negating our various cookie blocking actions (i.e. we will allow + cookies here). The second is allowing fast-redirects. Note + that there is a leading dot here -- .google.com. This will + match any hosts and sub-domains, in the google.com domain also, such as + www.google.com. So, apparently, we have these actions defined + somewhere in the lower part of our actions file, and + google.com is referenced in these sections. + + + + + And now we pull it altogether in the bottom section and summarize how + Junkbuster is appying all its actions + to google.com: + + + + + + + Final results: + + -add-header -block -deanimate-gifs -downgrade -fast-redirects + +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} + +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} + +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} + -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression + -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer + -wafer + + + + + + Now another example, ad.doubleclick.net: + + + + + + { +block +image } + .ad.doubleclick.net + + { +block +image } + ad*. + + { +block +image } + .doubleclick.net + + + + + + We'll just show the interesting part here, the explicit matches. It is + matched three different times. Each as an +block +image, + which is the expanded form of one of our aliases that had been defined as: + +imageblock. (Aliases are defined in the + first section of the actions file and typically used to combine more + than one action.) + + + + Any one of these would have done the trick and blocked this as an unwanted + image. This is unnecessarily redundant since the last case effectively + would also cover the first. No point in taking chances with these guys + though ;-) Note that if you want an ad or obnoxious + URL to be invisible, it should be defined as ad.doubleclick.net + is done here -- as both a +block and an + +image. The custom alias +imageblock does this + for us. + + + + One last example. Let's try http://www.rhapsodyk.net/adsl/HOWTO/. + This one is giving us problems. We are getting a blank page. Hmmm... + + + + + + Matches for http://www.rhapsodyk.net/adsl/HOWTO/: + + { -add-header -block +deanimate-gifs -downgrade +fast-redirects + +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} + +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} + +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} + -hide-user-agent -image +image-blocker{blank} +no-compression + +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups + -vanilla-wafer -wafer } + / + + { +block +image } + /ads + + + + + + Ooops, the /adsl/ is matching /ads! But + we did not want this at all! Now we see why we get the blank page. We could + now add a new action below this that explictly does not + block (-block) pages with adsl. There are various ways to + handle such exceptions. Example: + + + + + + { -block } + /adsl + + + + + + Now the page displays ;-) + + + + +