From: Fabian Keil Date: Wed, 25 Apr 2007 15:10:36 +0000 (+0000) Subject: - Describe installation for FreeBSD. X-Git-Tag: v_3_0_7~264 X-Git-Url: http://www.privoxy.org/gitweb/announce.txt?a=commitdiff_plain;h=01a86cf92114031f10bc03032883ebe1fc45f781;hp=355b51d46c75908f843ede4f4c9d629fdd2a1781;p=privoxy.git - Describe installation for FreeBSD. - Start to document taggers and tag patterns. - Don't confuse devils and daemons. --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index e2a45aae..9d738223 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -33,7 +33,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.28 2006/12/10 23:42:48 hal9 Exp $ + $Id: user-manual.sgml,v 2.29 2007/04/05 11:47:51 fabiankeil Exp $ Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/ See LICENSE. @@ -59,7 +59,7 @@ -$Id: user-manual.sgml,v 2.28 2006/12/10 23:42:48 hal9 Exp $ +$Id: user-manual.sgml,v 2.29 2007/04/05 11:47:51 fabiankeil Exp $ + Red Hat and Fedora RPMs @@ -260,7 +262,7 @@ How to install the binary packages depends on your operating system: -Solaris, NetBSD, FreeBSD, HP-UX +Solaris, NetBSD, HP-UX Create a new directory, cd to it, then unzip and @@ -335,6 +337,25 @@ How to install the binary packages depends on your operating system: + +FreeBSD + + + Privoxy is part of FreeBSD's Ports Collection, you can build and install + it with cd /usr/ports/www/privoxy; make install clean. + + + If you don't use the ports, you can fetch and install + the package with pkg_add -r privoxy. + + + The port skeleton and the package can also be downloaded from the + File Release + Page, but if you're interested in stable releases only you don't + gain anything by using them. + + + Gentoo @@ -1996,7 +2017,7 @@ for details. The list of actions files to be used are defined in the main configuration file, and are processed in the order they are defined (e.g. - default.action is typically process before + default.action is typically processed before user.action). The content of these can all be viewed and edited from http://config.privoxy.org/show-status. @@ -2082,24 +2103,28 @@ for details. -How Actions are Applied to URLs +How Actions are Applied to Requests Actions files are divided into sections. There are special sections, like the alias sections which will be discussed later. For now let's concentrate on regular sections: They have a heading line (often split up to multiple lines for readability) which consist of a list of actions, separated by whitespace and enclosed in curly braces. - Below that, there is a list of URL patterns, each on a separate line. + Below that, there is a list of URL and tag patterns, each on a separate line. To determine which actions apply to a request, the URL of the request is - compared to all patterns in each action file file. Every time it matches, the list of - applicable actions for the URL is incrementally updated, using the heading - of the section in which the pattern is located. If multiple matches for - the same URL set the same action differently, the last match wins. If not, - the effects are aggregated. E.g. a URL might match a regular section with - a heading line of { + compared to all URL patterns in each action file. + Every time it matches, the list of applicable actions for the request is + incrementally updated, using the heading of the section in which the + pattern is located. The same is done again for tags and tag patterns later on. + + + + If multiple applying sections set the same action differently, + the last match wins. If not, the effects are aggregated. + E.g. a URL might match a regular section with a heading line of { +handle-as-image }, then later another one with just { +block }, resulting @@ -2118,7 +2143,7 @@ for details. - You can trace this process for any given URL by visiting http://config.privoxy.org/show-url-info. @@ -2141,7 +2166,7 @@ for details. - Generally, a Privoxy pattern has the form + Generally, a URL pattern has the form <domain>/<path>, where both the <domain> and <path> are optional. (This is why the special / pattern matches all @@ -2422,6 +2447,68 @@ for details. + +The Tag Pattern + + + Tag patterns are used to change the applying actions based on the + request's tags. Tags can be created with either the + client-header-tagger + or the server-header-tagger action. + + + + Tag patterns have to start with TAG:, so &my-app; + can tell them apart from URL patterns. Everything after the colon + including white space, is interpreted as a regular expression with + path patterns syntax, except that tag patterns aren't left-anchored + automatically (Privoxy doesn't silently add a ^, + you have to do it yourself if you need it). + + + + To match all requests that are tagged with foo + your pattern line should be TAG:^foo$, + TAG:foo would work as well, but it would also + match requests whose tags contain foo somewhere. + + + + Sections can contain URL and tag patterns at the same time, + but tag patterns are checked after the URL patterns and thus + always overrule them, even if they are located before the URL patterns. + + + + Once a new tag is added, Privoxy checks right away if it's matched by one + of the tag patterns and updates the action settings accordingly. As a result + tags can be used to activate other tagger actions, as long as these other + taggers look for headers that haven't already be parsed. + + + + For example you could tag client requests which use the POST method, + use this tag to activate another tagger that adds a tag if cookies + are send, and then block based on the cookie tag. However if you'd + reverse the position of the described taggers, and activated the method + tagger based on the cookie tagger, no method tags would be created. + The method tagger would look for the request line, but at the time + the cookie tag is created the request line has already been parsed. + + + + While this is a limitation you should be aware of, this kind of + indirection is seldom needed anyway and even the example doesn't + make too much sense. + + + + + + + + + @@ -2770,6 +2857,7 @@ for details. Client-header filters are applied to each header on its own, not to all at once. This makes it easier to diagnose problems, but on the downside you can't write filters that only change header x if header y's value is z. + You can do that by using tags though. Client-header filters are executed after the other header actions have finished @@ -2799,6 +2887,81 @@ for details. + + +client-header-tagger + + + + Typical use: + + + Block requests based on their headers. + + + + + + Effect: + + + Client headers to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions, the result is used as + tag. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + The name of a client-header tagger, as defined in one of the + filter files. + + + + + + Notes: + + + Client-header taggers are applied to each header on its own, + and as the header isn't modified, each tagger sees + the original. + + + Client-header taggers are the first actions that are executed + and their tags can be used to control every other action. + + + + + + Example usage (section): + + + +# Tag every request with the User-Agent header +{+client-header-filter{user-agent}} +/ + + + + + + + + + + +server-header-tagger + + + + Typical use: + + + Disable or disable filters based on the Content-Type header. + + + + + + Effect: + + + Server headers to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions, the result is used as + tag. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + The name of a server-header tagger, as defined in one of the + filter files. + + + + + + Notes: + + + Server-header taggers are applied to each header on its own, + and as the header isn't modified, each tagger sees + the original. + + + Server-header taggers are executed before all other header actions + that modify server headers. Their tags can be used to control + all of the other server-header actions, the content filters + and the crunch actions (redirect + and block). + + + Obviously crunching based on tags created by server-header taggers + doesn't prevent the request from showing up in the server's log file. + + + + + + Example usage (section): + + + +# Tag every request with the declared content type +{+client-header-filter{content-type}} +/ + + + + + + + + + session-cookies-only @@ -5576,7 +5822,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not +set-image-blocker{pattern} - Redirect to the BSD devil: + Redirect to the BSD daemon: +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} @@ -5651,15 +5897,7 @@ new action For Connect requests the clients tell Privoxy which host they are interested in, but not which document they plan to get later. As a result, the - Go there anyway link becomes rather useless: - it lets the client request the home page of the forbidden host - through unencrypted HTTP, still using the port of the last request. - - - If you previously configured Privoxy to do the - request through a SSL tunnel, everything will work. Most likely you haven't - and the server will respond with an error message because it is expecting - HTTPS (SSL). + Go there anyway wouldn't work and is therefore suppressed. @@ -6515,6 +6753,18 @@ stupid-server.example.com/ to rewrite headers that are send by the server, and + + &my-app; also supports two tagger actions: + client-header-tagger + and + server-header-tagger. + Taggers and filters use the same syntax in the filter files, the differnce + is that taggers don't modify the text they are filtering, but use a rewritten + version of the filtered text as tag. The tags can then be used to change the + applying actions through sections with tag-patterns. + + + Multiple filter files can be defined through the filterfile config directive. The filters @@ -6566,6 +6816,8 @@ stupid-server.example.com/ + Filter definitions start with a header line that contains the filter + type, the filter name and the filter description. A content filter header line for a filter called foo could look like this: @@ -8564,6 +8816,11 @@ In file: user.action [ View ] [ Edit ]