156b2e3176fb83d38d978f6fbd4f5a551267f89d
[privoxy.git] / doc / webserver / user-manual / configuration.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
3 <html>
4   <head>
5     <title>
6       Privoxy Configuration
7     </title>
8     <meta name="GENERATOR" content=
9     "Modular DocBook HTML Stylesheet Version 1.79">
10     <link rel="HOME" title="Privoxy 3.0.26 User Manual" href="index.html">
11     <link rel="PREVIOUS" title="Starting Privoxy" href="startup.html">
12     <link rel="NEXT" title="The Main Configuration File" href="config.html">
13     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
14     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
15     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
16   </head>
17   <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
18   "#840084" alink="#0000FF">
19     <div class="NAVHEADER">
20       <table summary="Header navigation table" width="100%" border="0"
21       cellpadding="0" cellspacing="0">
22         <tr>
23           <th colspan="3" align="center">
24             Privoxy 3.0.26 User Manual
25           </th>
26         </tr>
27         <tr>
28           <td width="10%" align="left" valign="bottom">
29             <a href="startup.html" accesskey="P">Prev</a>
30           </td>
31           <td width="80%" align="center" valign="bottom">
32           </td>
33           <td width="10%" align="right" valign="bottom">
34             <a href="config.html" accesskey="N">Next</a>
35           </td>
36         </tr>
37       </table>
38       <hr align="LEFT" width="100%">
39     </div>
40     <div class="SECT1">
41       <h1 class="SECT1">
42         <a name="CONFIGURATION">6. Privoxy Configuration</a>
43       </h1>
44       <p>
45         All <span class="APPLICATION">Privoxy</span> configuration is stored
46         in text files. These files can be edited with a text editor. Many
47         important aspects of <span class="APPLICATION">Privoxy</span> can
48         also be controlled easily with a web browser.
49       </p>
50       <div class="SECT2">
51         <h2 class="SECT2">
52           <a name="CONTROL-WITH-WEBBROWSER">6.1. Controlling Privoxy with
53           Your Web Browser</a>
54         </h2>
55         <p>
56           <span class="APPLICATION">Privoxy</span>'s user interface can be
57           reached through the special URL <a href=
58           "http://config.privoxy.org/" target=
59           "_top">http://config.privoxy.org/</a> (shortcut: <a href=
60           "http://p.p/" target="_top">http://p.p/</a>), which is a built-in
61           page and works without Internet access. You will see the following
62           section:&#13;
63         </p>
64         <table border="0" bgcolor="#E0E0E0" width="100%">
65           <tr>
66             <td>
67 <pre class="SCREEN">
68
69 </pre>
70               <h2 class="BRIDGEHEAD">
71                 <a name="AEN859"></a>&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu
72               </h2>
73 <pre>
74 </pre>
75               <table border="0">
76                 <tbody>
77                   <tr>
78                     <td>
79                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
80                        href="http://config.privoxy.org/show-status" target=
81                       "_top">View &amp; change the current configuration</a>
82                     </td>
83                   </tr>
84                   <tr>
85                     <td>
86                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
87                        href="http://config.privoxy.org/show-version" target=
88                       "_top">View the source code version numbers</a>
89                     </td>
90                   </tr>
91                   <tr>
92                     <td>
93                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
94                        href="http://config.privoxy.org/show-request" target=
95                       "_top">View the request headers.</a>
96                     </td>
97                   </tr>
98                   <tr>
99                     <td>
100                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
101                        href="http://config.privoxy.org/show-url-info" target=
102                       "_top">Look up which actions apply to a URL and why</a>
103
104                     </td>
105                   </tr>
106                   <tr>
107                     <td>
108                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
109                        href="http://config.privoxy.org/toggle" target=
110                       "_top">Toggle Privoxy on or off</a>
111                     </td>
112                   </tr>
113                   <tr>
114                     <td>
115                       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#9642;&nbsp;&nbsp;<a
116                        href="https://www.privoxy.org/3.0.26/user-manual/"
117                       target="_top">Documentation</a>
118                     </td>
119                   </tr>
120                 </tbody>
121               </table>
122 <pre>
123 </pre>
124             </td>
125           </tr>
126         </table>
127         <p>
128           This should be self-explanatory. Note the first item leads to an
129           editor for the <a href="actions-file.html">actions files</a>, which
130           is where the ad, banner, cookie, and URL blocking magic is
131           configured as well as other advanced features of <span class=
132           "APPLICATION">Privoxy</span>. This is an easy way to adjust various
133           aspects of <span class="APPLICATION">Privoxy</span> configuration.
134           The actions file, and other configuration files, are explained in
135           detail below.
136         </p>
137         <p>
138           <span class="QUOTE">"Toggle Privoxy On or Off"</span> is handy for
139           sites that might have problems with your current actions and
140           filters. You can in fact use it as a test to see whether it is
141           <span class="APPLICATION">Privoxy</span> causing the problem or
142           not. <span class="APPLICATION">Privoxy</span> continues to run as a
143           proxy in this case, but all manipulation is disabled, i.e. <span
144           class="APPLICATION">Privoxy</span> acts like a normal forwarding
145           proxy.
146         </p>
147         <p>
148           Note that several of the features described above are disabled by
149           default in <span class="APPLICATION">Privoxy</span> 3.0.7 beta and
150           later. Check the <a href="config.html" target="_top">configuration
151           file</a> to learn why and in which cases it's safe to enable them
152           again.
153         </p>
154       </div>
155       <div class="SECT2">
156         <h2 class="SECT2">
157           <a name="CONFOVERVIEW">6.2. Configuration Files Overview</a>
158         </h2>
159         <p>
160           For Unix, *BSD and Linux, all configuration files are located in
161           <tt class="FILENAME">/etc/privoxy/</tt> by default. For MS Windows,
162           OS/2, and AmigaOS these are all in the same directory as the <span
163           class="APPLICATION">Privoxy</span> executable. The name and number
164           of configuration files has changed from previous versions, and is
165           subject to change as development progresses.
166         </p>
167         <p>
168           The installed defaults provide a reasonable starting point, though
169           some settings may be aggressive by some standards. For the time
170           being, the principle configuration files are:
171         </p>
172         <p>
173         </p>
174         <ul>
175           <li>
176             <p>
177               The <a href="config.html">main configuration file</a> is named
178               <tt class="FILENAME">config</tt> on Linux, Unix, BSD, OS/2, and
179               AmigaOS and <tt class="FILENAME">config.txt</tt> on Windows.
180               This is a required file.
181             </p>
182           </li>
183           <li>
184             <p>
185               <tt class="FILENAME">match-all.action</tt> is used to define
186               which <span class="QUOTE">"actions"</span> relating to
187               banner-blocking, images, pop-ups, content modification, cookie
188               handling etc should be applied by default. It should be the
189               first actions file loaded.
190             </p>
191             <p>
192               <tt class="FILENAME">default.action</tt> defines many
193               exceptions (both positive and negative) from the default set of
194               actions that's configured in <tt class=
195               "FILENAME">match-all.action</tt>. It should be the second
196               actions file loaded and shouldn't be edited by the user.
197             </p>
198             <p>
199               Multiple actions files may be defined in <tt class=
200               "FILENAME">config</tt>. These are processed in the order they
201               are defined. Local customizations and locally preferred
202               exceptions to the default policies as defined in <tt class=
203               "FILENAME">match-all.action</tt> (which you will most probably
204               want to define sooner or later) are best applied in <tt class=
205               "FILENAME">user.action</tt>, where you can preserve them across
206               upgrades. The file isn't installed by all installers, but you
207               can easily create it yourself with a text editor.
208             </p>
209             <p>
210               There is also a web based editor that can be accessed from <a
211               href="http://config.privoxy.org/show-status" target=
212               "_top">http://config.privoxy.org/show-status</a> (Shortcut: <a
213               href="http://p.p/show-status" target=
214               "_top">http://p.p/show-status</a>) for the various actions
215               files.
216             </p>
217           </li>
218           <li>
219             <p>
220               <span class="QUOTE">"Filter files"</span> (the <a href=
221               "filter-file.html">filter file</a>) can be used to re-write the
222               raw page content, including viewable text as well as embedded
223               HTML and JavaScript, and whatever else lurks on any given web
224               page. The filtering jobs are only pre-defined here; whether to
225               apply them or not is up to the actions files. <tt class=
226               "FILENAME">default.filter</tt> includes various filters made
227               available for use by the developers. Some are much more
228               intrusive than others, and all should be used with caution. You
229               may define additional filter files in <tt class=
230               "FILENAME">config</tt> as you can with actions files. We
231               suggest <tt class="FILENAME">user.filter</tt> for any locally
232               defined filters or customizations.
233             </p>
234           </li>
235         </ul>
236
237         <p>
238           The syntax of the configuration and filter files may change between
239           different Privoxy versions, unfortunately some enhancements cost
240           backwards compatibility.
241         </p>
242         <p>
243           All files use the <span class="QUOTE">"<tt class=
244           "LITERAL">#</tt>"</span> character to denote a comment (the rest of
245           the line will be ignored) and understand line continuation through
246           placing a backslash ("<tt class="LITERAL">\</tt>") as the very last
247           character in a line. If the <tt class="LITERAL">#</tt> is preceded
248           by a backslash, it looses its special function. Placing a <tt
249           class="LITERAL">#</tt> in front of an otherwise valid configuration
250           line to prevent it from being interpreted is called "commenting
251           out" that line. Blank lines are ignored.
252         </p>
253         <p>
254           The actions files and filter files can use Perl style <a href=
255           "appendix.html#REGEX">regular expressions</a> for maximum
256           flexibility.
257         </p>
258         <p>
259           After making any changes, there is no need to restart <span class=
260           "APPLICATION">Privoxy</span> in order for the changes to take
261           effect. <span class="APPLICATION">Privoxy</span> detects such
262           changes automatically. Note, however, that it may take one or two
263           additional requests for the change to take effect. When changing
264           the listening address of <span class="APPLICATION">Privoxy</span>,
265           these <span class="QUOTE">"wake up"</span> requests must obviously
266           be sent to the <span class="emphasis"><i class=
267           "EMPHASIS">old</i></span> listening address.
268         </p>
269         <p>
270           While under development, the configuration content is subject to
271           change. The below documentation may not be accurate by the time you
272           read this. Also, what constitutes a <span class=
273           "QUOTE">"default"</span> setting, may change, so please check all
274           your configuration files on important issues.
275         </p>
276       </div>
277     </div>
278     <div class="NAVFOOTER">
279       <hr align="LEFT" width="100%">
280       <table summary="Footer navigation table" width="100%" border="0"
281       cellpadding="0" cellspacing="0">
282         <tr>
283           <td width="33%" align="left" valign="top">
284             <a href="startup.html" accesskey="P">Prev</a>
285           </td>
286           <td width="34%" align="center" valign="top">
287             <a href="index.html" accesskey="H">Home</a>
288           </td>
289           <td width="33%" align="right" valign="top">
290             <a href="config.html" accesskey="N">Next</a>
291           </td>
292         </tr>
293         <tr>
294           <td width="33%" align="left" valign="top">
295             Starting Privoxy
296           </td>
297           <td width="34%" align="center" valign="top">
298             &nbsp;
299           </td>
300           <td width="33%" align="right" valign="top">
301             The Main Configuration File
302           </td>
303         </tr>
304       </table>
305     </div>
306   </body>
307 </html>
308