Rebuild documentation
authorFabian Keil <fk@fabiankeil.de>
Thu, 17 Mar 2016 10:43:55 +0000 (10:43 +0000)
committerFabian Keil <fk@fabiankeil.de>
Thu, 17 Mar 2016 10:43:55 +0000 (10:43 +0000)
doc/webserver/faq/general.html
doc/webserver/faq/index.html
doc/webserver/user-manual/actions-file.html
doc/webserver/user-manual/appendix.html
doc/webserver/user-manual/config.html
doc/webserver/user-manual/index.html

index 80c202c..7049290 100644 (file)
         <p>If you have any questions regarding donations please mail to
         either the public user mailing list or, if it's a private matter, to
         <a href="mailto:fk@fabiankeil.de" target="_top">Fabian Keil</a>
-        (Privoxy's SPI liason) directly.</p>
+        (Privoxy's SPI liaison) directly.</p>
       </div>
     </div>
   </div>
index 46ff1a6..0293d3c 100644 (file)
@@ -22,7 +22,7 @@
       2001-2014 by <a href="http://www.privoxy.org/" target="_top">Privoxy
       Developers</a></sub><br></p>
 
-      <p class="PUBDATE">$Id: faq.sgml,v 2.117 2016/03/04 13:21:33 fabiankeil
+      <p class="PUBDATE">$Id: faq.sgml,v 2.118 2016/03/06 11:32:06 fabiankeil
       Exp $<br></p>
 
       <div>
index 94a8617..a7f1ac3 100644 (file)
         in <tt class="FILENAME">default.action</tt> are:</p>
 
         <div class="TABLE">
-          <a name="AEN2618" id="AEN2618"></a>
+          <a name="AEN2676" id="AEN2676"></a>
 
           <p><b>Table 1. Default Configurations</b></p>
 
 
       <div class="SECT3">
         <h3 class="SECT3"><a name="TAG-PATTERN" id="TAG-PATTERN">8.4.3. The
-        Tag Pattern</a></h3>
+        Request Tag Pattern</a></h3>
 
-        <p>Tag patterns are used to change the applying actions based on the
-        request's tags. Tags can be created with either the <a href=
+        <p>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 <a href=
         "actions-file.html#CLIENT-HEADER-TAGGER">client-header-tagger</a> or
         the <a href=
         "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a>
         action.</p>
 
-        <p>Tag patterns have to start with <span class="QUOTE">"TAG:"</span>,
-        so <span class="APPLICATION">Privoxy</span> 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 (<span class=
-        "APPLICATION">Privoxy</span> doesn't silently add a <span class=
-        "QUOTE">"^"</span>, you have to do it yourself if you need it).</p>
+        <p>Request tag patterns have to start with <span class=
+        "QUOTE">"TAG:"</span>, so <span class="APPLICATION">Privoxy</span>
+        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 (<span class="APPLICATION">Privoxy</span> doesn't
+        silently add a <span class="QUOTE">"^"</span>, you have to do it
+        yourself if you need it).</p>
 
         <p>To match all requests that are tagged with <span class=
         "QUOTE">"foo"</span> your pattern line should be <span class=
         "QUOTE">"TAG: foo"</span> wouldn't work as it requires white
         space.</p>
 
-        <p>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.</p>
+        <p>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.</p>
 
-        <p>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.</p>
+        <p>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.</p>
 
         <p>For example you could tag client requests which use the <tt class=
         "LITERAL">POST</tt> method, then use this tag to activate another
 
       <div class="SECT3">
         <h3 class="SECT3"><a name="NEGATIVE-TAG-PATTERNS" id=
-        "NEGATIVE-TAG-PATTERNS">8.4.4. The Negative Tag Patterns</a></h3>
+        "NEGATIVE-TAG-PATTERNS">8.4.4. The Negative Request Tag
+        Patterns</a></h3>
 
-        <p>To match requests that do not have a certain tag, specify a
-        negative tag pattern by prefixing the tag pattern line with either
+        <p>To match requests that do not have a certain request tag, specify
+        negative tag pattern by prefixing the tag pattern line with either
         <span class="QUOTE">"NO-REQUEST-TAG:"</span> or <span class=
         "QUOTE">"NO-RESPONSE-TAG:"</span> instead of <span class=
         "QUOTE">"TAG:"</span>.</p>
 
-        <p>Negative tag patterns created with <span class=
+        <p>Negative request tag patterns created with <span class=
         "QUOTE">"NO-REQUEST-TAG:"</span> are checked after all client headers
         are scanned, the ones created with <span class=
         "QUOTE">"NO-RESPONSE-TAG:"</span> are checked after all server
         headers are scanned. In both cases all the created tags are
         considered.</p>
       </div>
+
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="CLIENT-TAG-PATTERN" id=
+        "CLIENT-TAG-PATTERN">8.4.5. The Client Tag Pattern</a></h3>
+
+        <div class="WARNING">
+          <table class="WARNING" border="1" width="100%">
+            <tr>
+              <td align="center"><b>Warning</b></td>
+            </tr>
+
+            <tr>
+              <td align="left">
+                <p>This is an experimental feature. The syntax is likely to
+                change in future versions.</p>
+              </td>
+            </tr>
+          </table>
+        </div>
+
+        <p>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.</p>
+
+        <p>After a client-specific tag has been defined with the <a href=
+        "config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a>, 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!</p>
+
+        <p>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.</p>
+
+        <p>Clients can request tags to be set by using the CGI interface
+        <a href="http://config.privoxy.org/show-client-tags" target=
+        "_top">http://config.privoxy.org/show-client-tags</a>.</p>
+
+        <p>Example:</p>
+
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">
+# 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
+</pre>
+            </td>
+          </tr>
+        </table>
+      </div>
     </div>
 
     <div class="SECT2">
index 46f97bb..96c6c73 100644 (file)
 
       <ul>
         <li>
-          <p>Privoxy main page:</p><a name="AEN5777" id="AEN5777"></a>
+          <p>Privoxy main page:</p><a name="AEN5848" id="AEN5848"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/" target=
 
         <li>
           <p>Show information about the current configuration, including
-          viewing and editing of actions files:</p><a name="AEN5785" id=
-          "AEN5785"></a>
+          viewing and editing of actions files:</p><a name="AEN5856" id=
+          "AEN5856"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-status" target=
         </li>
 
         <li>
-          <p>Show the source code version numbers:</p><a name="AEN5790" id=
-          "AEN5790"></a>
+          <p>Show the source code version numbers:</p><a name="AEN5861" id=
+          "AEN5861"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-version" target=
         </li>
 
         <li>
-          <p>Show the browser's request headers:</p><a name="AEN5795" id=
-          "AEN5795"></a>
+          <p>Show the browser's request headers:</p><a name="AEN5866" id=
+          "AEN5866"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-request" target=
         </li>
 
         <li>
-          <p>Show which actions apply to a URL and why:</p><a name="AEN5800"
-          id="AEN5800"></a>
+          <p>Show which actions apply to a URL and why:</p><a name="AEN5871"
+          id="AEN5871"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-url-info" target=
           <span class="QUOTE">"off"</span>, <span class=
           "QUOTE">"Privoxy"</span> continues to run, but only as a
           pass-through proxy, with no actions taking place:</p><a name=
-          "AEN5808" id="AEN5808"></a>
+          "AEN5879" id="AEN5879"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle" target=
             "_top">http://config.privoxy.org/toggle</a></p>
           </blockquote>
 
-          <p>Short cuts. Turn off, then on:</p><a name="AEN5812" id=
-          "AEN5812"></a>
+          <p>Short cuts. Turn off, then on:</p><a name="AEN5883" id=
+          "AEN5883"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=disable" target=
             "_top">http://config.privoxy.org/toggle?set=disable</a></p>
-          </blockquote><a name="AEN5815" id="AEN5815"></a>
+          </blockquote><a name="AEN5886" id="AEN5886"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=enable" target=
index 44beeac..292aeaa 100644 (file)
           </dl>
         </div>
       </div>
+
+      <div class="SECT3">
+        <h4 class="SECT3"><a name="CLIENT-SPECIFIC-TAG" id=
+        "CLIENT-SPECIFIC-TAG">7.6.14. client-specific-tag</a></h4>
+
+        <div class="VARIABLELIST">
+          <dl>
+            <dt>Specifies:</dt>
+
+            <dd>
+              <p>The name of a tag that will always be set for clients that
+              requested it through the webinterface.</p>
+            </dd>
+
+            <dt>Type of value:</dt>
+
+            <dd>
+              <p><tt class="REPLACEABLE"><i>Tag name followed by a
+              description that will be shown in the webinterface</i></tt></p>
+            </dd>
+
+            <dt>Default value:</dt>
+
+            <dd>
+              <p>None</p>
+            </dd>
+
+            <dt>Notes:</dt>
+
+            <dd>
+              <div class="WARNING">
+                <table class="WARNING" border="1" width="90%">
+                  <tr>
+                    <td align="center"><b>Warning</b></td>
+                  </tr>
+
+                  <tr>
+                    <td align="left">
+                      <p>This is an experimental feature. The syntax is
+                      likely to change in future versions.</p>
+                    </td>
+                  </tr>
+                </table>
+              </div>
+
+              <p>Client-specific tags allow Privoxy admins to create
+              different profiles and let the users chose which one they want
+              without impacting other users.</p>
+
+              <p>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 <a href=
+              "config.html#ENABLE-REMOTE-TOGGLE">enable-remote-toggle
+              feature</a> 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.</p>
+
+              <p>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 <a href="#CLIENT-TAG-PATTERN"
+              target="_top">CLIENT-TAG</a> 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!</p>
+
+              <p>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.</p>
+
+              <p>Clients can request tags to be set by using the CGI
+              interface <a href="http://config.privoxy.org/show-client-tags"
+              target="_top">http://config.privoxy.org/show-client-tags</a>.
+              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.</p>
+            </dd>
+
+            <dt>Examples:</dt>
+
+            <dd>
+              <table border="0" bgcolor="#E0E0E0" width="90%">
+                <tr>
+                  <td>
+                    <pre class="SCREEN">
+    # 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
+
+</pre>
+                  </td>
+                </tr>
+              </table>
+            </dd>
+          </dl>
+        </div>
+      </div>
+
+      <div class="SECT3">
+        <h4 class="SECT3"><a name="CLIENT-TAG-LIFETIME" id=
+        "CLIENT-TAG-LIFETIME">7.6.15. client-tag-lifetime</a></h4>
+
+        <div class="VARIABLELIST">
+          <dl>
+            <dt>Specifies:</dt>
+
+            <dd>
+              <p>How long a temporarily enabled tag remains enabled.</p>
+            </dd>
+
+            <dt>Type of value:</dt>
+
+            <dd>
+              <p><tt class="REPLACEABLE"><i>Time in seconds.</i></tt></p>
+            </dd>
+
+            <dt>Default value:</dt>
+
+            <dd>
+              <p>None</p>
+            </dd>
+
+            <dt>Notes:</dt>
+
+            <dd>
+              <div class="WARNING">
+                <table class="WARNING" border="1" width="90%">
+                  <tr>
+                    <td align="center"><b>Warning</b></td>
+                  </tr>
+
+                  <tr>
+                    <td align="left">
+                      <p>This is an experimental feature. The syntax is
+                      likely to change in future versions.</p>
+                    </td>
+                  </tr>
+                </table>
+              </div>
+
+              <p>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.</p>
+
+              <p>The CGI interface <a href=
+              "http://config.privoxy.org/show-client-tags" target=
+              "_top">http://config.privoxy.org/show-client-tags</a> therefore
+              provides a "enable this tag temporarily" option. If it is used,
+              the tag will be set until the client-tag-lifetime is over.</p>
+            </dd>
+          </dl>
+        </div>
+      </div>
     </div>
 
     <div class="SECT2">
index 712212d..dbbf135 100644 (file)
 
                 <dt>7.6.13. <a href=
                 "config.html#CLIENT-HEADER-ORDER">client-header-order</a></dt>
+
+                <dt>7.6.14. <a href=
+                "config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a></dt>
+
+                <dt>7.6.15. <a href=
+                "config.html#CLIENT-TAG-LIFETIME">client-tag-lifetime</a></dt>
               </dl>
             </dd>
 
                 <dt>8.4.2. <a href="actions-file.html#PATH-PATTERN">The Path
                 Pattern</a></dt>
 
-                <dt>8.4.3. <a href="actions-file.html#TAG-PATTERN">The Tag
-                Pattern</a></dt>
+                <dt>8.4.3. <a href="actions-file.html#TAG-PATTERN">The
+                Request Tag Pattern</a></dt>
 
                 <dt>8.4.4. <a href=
-                "actions-file.html#NEGATIVE-TAG-PATTERNS">The Negative Tag
-                Patterns</a></dt>
+                "actions-file.html#NEGATIVE-TAG-PATTERNS">The Negative
+                Request Tag Patterns</a></dt>
+
+                <dt>8.4.5. <a href="actions-file.html#CLIENT-TAG-PATTERN">The
+                Client Tag Pattern</a></dt>
               </dl>
             </dd>