<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/p-config.sgml,v $
+ File : doc/source/p-config.sgml
Purpose : Used with other docs and files only.
- $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $
-
- Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
example:
</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>confdir /etc/privoxy</emphasis></literallayout>
- </msgtext>
- </literal>
-</para>
+<literallayout>
+ <emphasis>confdir /etc/privoxy</emphasis>
+</literallayout>
<para>
Assigns the value <literal>/etc/privoxy</literal> to the option
Sample Configuration File for Privoxy &p-version;
</title>
<para>
- $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $
-</para>
-<para>
-Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
</para>
-<para>
- <literallayout>
+<literallayout>
##################################################################
#
Table of Contents #
7. WINDOWS GUI OPTIONS #
#
##################################################################
- </literallayout>
-</para>
-<literallayout>I. INTRODUCTION
- =============== <!-- fuck this madness --></literallayout>
+
+I. INTRODUCTION
+ ===============
+</literallayout>
<para>
This file holds Privoxy's main configuration. Privoxy detects
<literal>PATH</literal> to where the <citetitle>User Manual</citetitle> is
located:
</para>
- <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
+ <screen> user-manual /usr/share/doc/privoxy/user-manual</screen>
<para>
The User Manual is then available to anyone with access to
<application>Privoxy</application>, by following the built-in URL:
If the documentation is not on the local system, it can be accessed
from a remote server, as:
</para>
- <screen> user-manual http://example.com/privoxy/user-manual/</screen>
+ <screen> user-manual http://example.com/privoxy/user-manual/</screen>
<![%user-man;[
<!-- this gets hammered in conversion to config. Text repeated below. -->
<warning>
Requests are accepted if the specified trusted-cgi-refer is the prefix
of the Referer.
</para>
+ <para>
+ If the trusted source is supposed to access the CGI pages via
+ JavaScript the <link linkend="cors-allowed-origin">cors-allowed-origin</link>
+ option can be used.
+ </para>
<warning>
<para>
Declaring pages the admin doesn't control trustworthy may allow
</varlistentry>
</variablelist>
-<![%config-file;[<literallayout>@@trusted-cgi-referer http://www.example.org/local-privoxy-control-page</literallayout>]]>
+<![%config-file;[<literallayout>@@#trusted-cgi-referer http://www.example.org/local-privoxy-control-page</literallayout>]]>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="cors-allowed-origin"><title>cors-allowed-origin</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A trusted website which can access &my-app;'s CGI pages through JavaScript.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Unset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No external sites get access via cross-origin resource sharing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Modern browsers by default prevent cross-origin requests made
+ via JavaScript to &my-app;'s CGI interface even if &my-app;
+ would trust the referer because it's white listed via the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <para>
+ <ulink url="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing"
+ >Cross-origin resource sharing (CORS)</ulink> is a mechanism to allow
+ cross-origin requests.
+ </para>
+ <para>
+ The <quote>cors-allowed-origin</quote> option can be used to specify
+ a domain that is allowed to make requests to Privoxy CGI interface
+ via JavaScript. It is used in combination with the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <warning>
+ <para>
+ Declaring domains the admin doesn't control trustworthy may allow
+ malicious third parties to modify Privoxy's internal state against
+ the user's wishes and without the user's knowledge.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@#cors-allowed-origin http://www.example.org/</literallayout>]]>
</sect3>
</sect2>
<listitem>
<para>
<replaceable class="parameter">target_pattern</replaceable>
- <replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ [<replaceable class="parameter">user</replaceable>:<replaceable class="parameter">pass</replaceable>@]<replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
<replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
(<replaceable class="parameter">http_parent</replaceable>
may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
<replaceable class="parameter">port</replaceable> parameters are TCP ports,
- i.e. integer values from 1 to 65535
+ i.e. integer values from 1 to 65535. <replaceable class="parameter">user</replaceable> and
+ <replaceable class="parameter">pass</replaceable> can be used for SOCKS5 authentication if required.
</para>
</listitem>
</varlistentry>
forward-socks4 / socks-gw.example.com:1080 .
</screen>
+ <para>
+ To connect SOCKS5 proxy which requires username/password authentication:
+ </para>
+ <screen>
+ forward-socks5 / user:pass@socks-gw.example.com:1080 .
+</screen>
+
<para>
To chain Privoxy and Tor, both running on the same system, you would use
something like:
</para>
<screen>
forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .
</screen>
<para>
Unencrypted connections to systems in these address ranges will
<para>
This directive was added as a work-around for Firefox bug 492459:
<quote>Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.</quote>
- (<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=492459"
- >https://bugzilla.mozilla.org/show_bug.cgi?id=492459</ulink>),
+ (<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=492459">
+ https://bugzilla.mozilla.org/show_bug.cgi?id=492459</ulink>),
the bug has been fixed for quite some time, but this directive is also useful
to make it harder for websites to detect whether or not resources are being
blocked.
<screen>
# Best speed (compared to the other levels)
compression-level 1
+
# Best compression
compression-level 9
+
# No compression. Only useful for testing as the added header
# slightly increases the amount of data that has to be sent.
# If your benchmark shows that using this compression level
# is superior to using no compression at all, the benchmark
# is likely to be flawed.
compression-level 0
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
# 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
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<screen>
# Increase the time to life for temporarily enabled tags to 3 minutes
client-tag-lifetime 180
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
# Allow systems that can reach Privoxy to provide the client
# IP address with a X-Forwarded-For header.
trust-x-forwarded-for 1
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<screen>
# Increase the receive buffer size
receive-buffer-size 32768
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<![%config-file;[<literallayout>@@#activity-animation 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>activity-animation 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-messages">
<![%config-file;[<literallayout>@@#log-messages 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-buffer-size">
<![%config-file;[<literallayout>@@#log-buffer-size 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-buffer-size 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-max-lines">
<![%config-file;[<literallayout>@@#log-max-lines 200</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-max-lines 200</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-highlight-messages">
<![%config-file;[<literallayout>@@#log-highlight-messages 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-highlight-messages 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-font-name">
<![%config-file;[<literallayout>@@#log-font-name Comic Sans MS</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-font-name Comic Sans MS</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="log-font-size">
<![%config-file;[<literallayout>@@#log-font-size 8</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>log-font-size 8</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="show-on-task-bar">
<![%config-file;[<literallayout>@@#show-on-task-bar 0</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>show-on-task-bar 0</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="close-button-minimizes">
<![%config-file;[<literallayout>@@#close-button-minimizes 1</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
<emphasis>close-button-minimizes 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
<anchor id="hide-console">
<![%config-file;[<literallayout>@@#hide-console</literallayout>]]>
<![%user-man;[
-<para>
- <literal>
- <msgtext>
<literallayout>
#<emphasis>hide-console</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+</literallayout>
]]>
</sect2>
projects / privoxy.git / blobdiff