From a4ce52a7c0f047b5f3bee2d389d540a5d29e1f98 Mon Sep 17 00:00:00 2001 From: Fabian Keil Date: Thu, 17 Mar 2016 10:43:55 +0000 Subject: [PATCH] Rebuild documentation --- doc/webserver/faq/general.html | 2 +- doc/webserver/faq/index.html | 2 +- doc/webserver/user-manual/actions-file.html | 114 +++++++++++--- doc/webserver/user-manual/appendix.html | 26 ++-- doc/webserver/user-manual/config.html | 157 ++++++++++++++++++++ doc/webserver/user-manual/index.html | 17 ++- 6 files changed, 276 insertions(+), 42 deletions(-) diff --git a/doc/webserver/faq/general.html b/doc/webserver/faq/general.html index 80c202cd..70492904 100644 --- a/doc/webserver/faq/general.html +++ b/doc/webserver/faq/general.html @@ -567,7 +567,7 @@

If you have any questions regarding donations please mail to either the public user mailing list or, if it's a private matter, to Fabian Keil - (Privoxy's SPI liason) directly.

+ (Privoxy's SPI liaison) directly.

diff --git a/doc/webserver/faq/index.html b/doc/webserver/faq/index.html index 46ff1a6a..0293d3c5 100644 --- a/doc/webserver/faq/index.html +++ b/doc/webserver/faq/index.html @@ -22,7 +22,7 @@ 2001-2014 by Privoxy Developers

-

$Id: faq.sgml,v 2.117 2016/03/04 13:21:33 fabiankeil +

$Id: faq.sgml,v 2.118 2016/03/06 11:32:06 fabiankeil Exp $

diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 94a86172..a7f1ac38 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -117,7 +117,7 @@ in default.action are:

- +

Table 1. Default Configurations

@@ -744,22 +744,24 @@

8.4.3. The - Tag Pattern

+ Request Tag Pattern -

Tag patterns are used to change the applying actions based on the - request's tags. Tags can be created with either the Request tag patterns are used to change the applying actions based + on the request's tags. Tags can be created based on HTTP headers with + either the client-header-tagger or the server-header-tagger action.

-

Tag patterns have to start with "TAG:", - so Privoxy can tell them apart from - URL patterns. Everything after the colon including white space, is - interpreted as a regular expression with path pattern 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).

+

Request tag patterns have to start with "TAG:", so Privoxy + can tell them apart from other patterns. Everything after the colon + including white space, is interpreted as a regular expression with + path pattern 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" wouldn't work as it requires white space.

-

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.

+

Sections can contain URL and request tag patterns at the same + time, but request 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.

+

Once a new request tag is added, Privoxy checks right away if it's + matched by one of the request tag patterns and updates the action + settings accordingly. As a result request 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, then use this tag to activate another @@ -797,21 +800,86 @@

8.4.4. The Negative Tag Patterns

+ "NEGATIVE-TAG-PATTERNS">8.4.4. The Negative Request Tag + Patterns -

To match requests that do not have a certain tag, specify a - negative tag pattern by prefixing the tag pattern line with either +

To match requests that do not have a certain request tag, specify + a negative tag pattern by prefixing the tag pattern line with either "NO-REQUEST-TAG:" or "NO-RESPONSE-TAG:" instead of "TAG:".

-

Negative tag patterns created with Negative request tag patterns created with "NO-REQUEST-TAG:" are checked after all client headers are scanned, the ones created with "NO-RESPONSE-TAG:" are checked after all server headers are scanned. In both cases all the created tags are considered.

+ +
+

8.4.5. The Client Tag Pattern

+ +
+ + + + + + + + +
Warning
+

This is an experimental feature. The syntax is likely to + change in future versions.

+
+
+ +

Client tag patterns are not set based on HTTP headers but based on + the client's IP address. Users can enable them themselves, but the + Privoxy admin controls which tags are available and what their effect + is.

+ +

After a client-specific tag has been defined with the client-specific-tag, directive, + action sections can be activated based on the tag by using a + CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same + priority as URL patterns, as a result the last matching pattern wins. + Tags that are created based on client or server headers are evaluated + later on and can overrule CLIENT-TAG and URL patterns!

+ +

The tag is set for all requests that come from clients that + requested it to be set. Note that "clients" are differentiated by IP + address, if the IP address changes the tag has to be requested + again.

+ +

Clients can request tags to be set by using the CGI interface + http://config.privoxy.org/show-client-tags.

+ +

Example:

+ + + + + +
+ 
+# If the admin defined the client-specific-tag circumvent-blocks,
+# and the request comes from a client that previously requested
+# the tag to be set, overrule all previous +block actions that
+# are enabled based on URL to CLIENT-TAG patterns.
+{-block}
+CLIENT-TAG:^circumvent-blocks$
+
+# This section is not overruled because it's located after
+# the previous one.
+{+block{Nobody is supposed to request this.}}
+example.org/blocked-example-page
+
+
+
diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html index 46f97bbc..96c6c735 100644 --- a/doc/webserver/user-manual/appendix.html +++ b/doc/webserver/user-manual/appendix.html @@ -313,7 +313,7 @@
+ +
+

7.6.14. client-specific-tag

+ +
+
+
Specifies:
+ +
+

The name of a tag that will always be set for clients that + requested it through the webinterface.

+
+ +
Type of value:
+ +
+

Tag name followed by a + description that will be shown in the webinterface

+
+ +
Default value:
+ +
+

None

+
+ +
Notes:
+ +
+
+ + + + + + + + +
Warning
+

This is an experimental feature. The syntax is + likely to change in future versions.

+
+
+ +

Client-specific tags allow Privoxy admins to create + different profiles and let the users chose which one they want + without impacting other users.

+ +

One use case is allowing users to circumvent certain blocks + without having to allow them to circumvent all blocks. This is + not possible with the enable-remote-toggle + feature because it would bluntly disable all blocks for all + users and also affect other actions like filters. It also is + set globally which renders it useless in most multi-user + setups.

+ +

After a client-specific tag has been defined with the + client-specific-tag directive, action sections can be activated + based on the tag by using a CLIENT-TAG pattern. The CLIENT-TAG pattern is + evaluated at the same priority as URL patterns, as a result the + last matching pattern wins. Tags that are created based on + client or server headers are evaluated later on and can + overrule CLIENT-TAG and URL patterns!

+ +

The tag is set for all requests that come from clients that + requested it to be set. Note that "clients" are differentiated + by IP address, if the IP address changes the tag has to be + requested again.

+ +

Clients can request tags to be set by using the CGI + interface http://config.privoxy.org/show-client-tags. + The specific tag description is only used on the web page and + should be phrased in away that the user understand the effect + of the tag.

+
+ +
Examples:
+ +
+ + + + +
+ 
+    # Define a couple of tags, the described effect requires action sections
+    # that are enabled based on CLIENT-TAG patterns.
+    client-specific-tag circumvent-blocks Overrule blocks but do not affect other actions
+    disable-content-filters Disable content-filters but do not affect other actions
+
+
+
+
+
+
+
+ +
+

7.6.15. client-tag-lifetime

+ +
+
+
Specifies:
+ +
+

How long a temporarily enabled tag remains enabled.

+
+ +
Type of value:
+ +
+

Time in seconds.

+
+ +
Default value:
+ +
+

None

+
+ +
Notes:
+ +
+
+ + + + + + + + +
Warning
+

This is an experimental feature. The syntax is + likely to change in future versions.

+
+
+ +

In case of some tags users may not want to enable them + permanently, but only for a short amount of time, for example + to circumvent a block that is the result of an overly-broad URL + pattern.

+ +

The CGI interface http://config.privoxy.org/show-client-tags therefore + provides a "enable this tag temporarily" option. If it is used, + the tag will be set until the client-tag-lifetime is over.

+
+
+
+
diff --git a/doc/webserver/user-manual/index.html b/doc/webserver/user-manual/index.html index 712212dc..dbbf135a 100644 --- a/doc/webserver/user-manual/index.html +++ b/doc/webserver/user-manual/index.html @@ -340,6 +340,12 @@
7.6.13. client-header-order
+ +
7.6.14. client-specific-tag
+ +
7.6.15. client-tag-lifetime
@@ -372,12 +378,15 @@
8.4.2. The Path Pattern
-
8.4.3. The Tag - Pattern
+
8.4.3. The + Request Tag Pattern
8.4.4. The Negative Tag - Patterns
+ "actions-file.html#NEGATIVE-TAG-PATTERNS">The Negative + Request Tag Patterns + +
8.4.5. The + Client Tag Pattern
-- 2.39.2