generated
[privoxy.git] / doc / webserver / user-manual / configuration.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >Privoxy Configuration</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
8 "><LINK
9 REL="HOME"
10 TITLE="Privoxy User Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Starting Privoxy"
14 HREF="startup.html"><LINK
15 REL="NEXT"
16 TITLE="The Main Configuration File"
17 HREF="config.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"></HEAD
21 ><BODY
22 CLASS="SECT1"
23 BGCOLOR="#EEEEEE"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 WIDTH="100%"
32 BORDER="0"
33 CELLPADDING="0"
34 CELLSPACING="0"
35 ><TR
36 ><TH
37 COLSPAN="3"
38 ALIGN="center"
39 >Privoxy User Manual</TH
40 ></TR
41 ><TR
42 ><TD
43 WIDTH="10%"
44 ALIGN="left"
45 VALIGN="bottom"
46 ><A
47 HREF="startup.html"
48 >Prev</A
49 ></TD
50 ><TD
51 WIDTH="80%"
52 ALIGN="center"
53 VALIGN="bottom"
54 ></TD
55 ><TD
56 WIDTH="10%"
57 ALIGN="right"
58 VALIGN="bottom"
59 ><A
60 HREF="config.html"
61 >Next</A
62 ></TD
63 ></TR
64 ></TABLE
65 ><HR
66 ALIGN="LEFT"
67 WIDTH="100%"></DIV
68 ><DIV
69 CLASS="SECT1"
70 ><H1
71 CLASS="SECT1"
72 ><A
73 NAME="CONFIGURATION"
74 >6. <SPAN
75 CLASS="APPLICATION"
76 >Privoxy</SPAN
77 > Configuration</A
78 ></H1
79 ><P
80 >  All <SPAN
81 CLASS="APPLICATION"
82 >Privoxy</SPAN
83 > configuration is stored  
84   in text files. These files can be edited with a text editor.
85   Many important aspects of <SPAN
86 CLASS="APPLICATION"
87 >Privoxy</SPAN
88 > can 
89   also be controlled easily with a web browser.
90  </P
91 ><DIV
92 CLASS="SECT2"
93 ><H2
94 CLASS="SECT2"
95 ><A
96 NAME="AEN346"
97 >6.1. Controlling <SPAN
98 CLASS="APPLICATION"
99 >Privoxy</SPAN
100 > with Your Web Browser</A
101 ></H2
102 ><P
103 > <SPAN
104 CLASS="APPLICATION"
105 >Privoxy</SPAN
106 >'s user interface can be reached through the special 
107  URL <A
108 HREF="http://config.privoxy.org/"
109 TARGET="_top"
110 >http://config.privoxy.org/</A
111 >
112  (shortcut: <A
113 HREF="http://p.p/"
114 TARGET="_top"
115 >http://p.p/</A
116 >), 
117  which is a built-in page and works without Internet access.
118  You will see the following section:&#13;</P
119 ><TABLE
120 BORDER="0"
121 BGCOLOR="#E0E0E0"
122 WIDTH="100%"
123 ><TR
124 ><TD
125 ><PRE
126 CLASS="SCREEN"
127 > <H3
128 CLASS="BRIDGEHEAD"
129 >Privoxy Menu</H3
130 ><P
131 ></P
132 ><TABLE
133 BORDER="0"
134 ><TBODY
135 ><TR
136 ><TD
137 >          &#9642;  <A
138 HREF="http://config.privoxy.org/show-status"
139 TARGET="_top"
140 >View &#38; change the current configuration</A
141 >
142  </TD
143 ></TR
144 ><TR
145 ><TD
146 >          &#9642;  <A
147 HREF="http://config.privoxy.org/show-version"
148 TARGET="_top"
149 >View the source code version numbers</A
150 >
151  </TD
152 ></TR
153 ><TR
154 ><TD
155 >          &#9642;  <A
156 HREF="http://config.privoxy.org/show-request"
157 TARGET="_top"
158 >View the request headers.</A
159 >
160  </TD
161 ></TR
162 ><TR
163 ><TD
164 >          &#9642;  <A
165 HREF="http://config.privoxy.org/show-url-info"
166 TARGET="_top"
167 >Look up which actions apply to a URL and why</A
168 >
169  </TD
170 ></TR
171 ><TR
172 ><TD
173 >          &#9642;  <A
174 HREF="http://config.privoxy.org/toggle"
175 TARGET="_top"
176 >Toggle Privoxy on or off</A
177 >
178  </TD
179 ></TR
180 ></TBODY
181 ></TABLE
182 ><P
183 ></P
184 ></PRE
185 ></TD
186 ></TR
187 ></TABLE
188 ><P
189 > This should be self-explanatory. Note the first item leads to an editor for the
190  <A
191 HREF="actions-file.html"
192 >actions files</A
193 >, which is where the ad, banner,
194  cookie, and URL blocking magic is configured as well as other advanced features of
195  <SPAN
196 CLASS="APPLICATION"
197 >Privoxy</SPAN
198 >. This is an easy way to adjust various
199  aspects of <SPAN
200 CLASS="APPLICATION"
201 >Privoxy</SPAN
202 > configuration. The actions
203  file, and other configuration files, are explained in detail below. </P
204 ><P
205 > <SPAN
206 CLASS="QUOTE"
207 >"Toggle Privoxy On or Off"</SPAN
208 > is handy for sites that might 
209  have problems with your current actions and filters. You can in fact use
210  it as a test to see whether it is <SPAN
211 CLASS="APPLICATION"
212 >Privoxy</SPAN
213
214  causing the problem or not. <SPAN
215 CLASS="APPLICATION"
216 >Privoxy</SPAN
217 > continues 
218  to run as a proxy in this case, but all manipulation is disabled, i.e.
219  <SPAN
220 CLASS="APPLICATION"
221 >Privoxy</SPAN
222 > acts like a normal forwarding proxy. There
223  is even a toggle <A
224 HREF="appendix.html#BOOKMARKLETS"
225 >Bookmarklet</A
226 > offered, so
227  that you can toggle <SPAN
228 CLASS="APPLICATION"
229 >Privoxy</SPAN
230 > with one click from
231  your browser.</P
232 ></DIV
233 ><DIV
234 CLASS="SECT2"
235 ><H2
236 CLASS="SECT2"
237 ><A
238 NAME="CONFOVERVIEW"
239 >6.2. Configuration Files Overview</A
240 ></H2
241 ><P
242 > For Unix, *BSD and Linux, all configuration files are located in
243  <TT
244 CLASS="FILENAME"
245 >/etc/privoxy/</TT
246 > by default. For MS Windows, OS/2, and
247  AmigaOS these are all in the same directory as the 
248  <SPAN
249 CLASS="APPLICATION"
250 >Privoxy</SPAN
251 > executable.  The name
252  and number of configuration files has changed from previous versions, and is
253  subject to change as development progresses.</P
254 ><P
255 > The installed defaults provide a reasonable starting point, though 
256  some settings may be aggressive by some standards. For the time being, the
257  principle configuration files are:</P
258 ><P
259 > <P
260 ></P
261 ><UL
262 ><LI
263 ><P
264 >     The <A
265 HREF="config.html"
266 >main configuration file</A
267 > is named <TT
268 CLASS="FILENAME"
269 >config</TT
270 >
271      on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
272 CLASS="FILENAME"
273 >config.txt</TT
274 >
275      on Windows. This is a required file.
276    </P
277 ></LI
278 ><LI
279 ><P
280 >    <TT
281 CLASS="FILENAME"
282 >default.action</TT
283 > (the main <A
284 HREF="actions-file.html"
285 >actions file</A
286 >)
287     is used to define which <SPAN
288 CLASS="QUOTE"
289 >"actions"</SPAN
290 > relating to banner-blocking, images, pop-ups,
291     content modification, cookie handling etc should be applied by default. It also defines many
292     exceptions (both positive and negative) from this default set of actions that enable 
293     <SPAN
294 CLASS="APPLICATION"
295 >Privoxy</SPAN
296 > to selectively eliminate the junk, and only the junk, on
297     as many websites as possible.
298    </P
299 ><P
300 >    Multiple actions files may be defined in <TT
301 CLASS="FILENAME"
302 >config</TT
303 >. These 
304     are processed in the order they are defined. Local customizations and locally 
305     preferred exceptions to the default policies  as defined in
306     <TT
307 CLASS="FILENAME"
308 >default.action</TT
309 > (which you will most propably want
310     to define sooner or later) are probably best applied in
311     <TT
312 CLASS="FILENAME"
313 >user.action</TT
314 >, where you can preserve them across
315     upgrades. <TT
316 CLASS="FILENAME"
317 >standard.action</TT
318 > is for
319     <SPAN
320 CLASS="APPLICATION"
321 >Privoxy's</SPAN
322 > internal use.
323    </P
324 ><P
325 >    
326     There is also a web based editor that can be accessed from
327     <A
328 HREF="http://config.privoxy.org/show-status"
329 TARGET="_top"
330 >http://config.privoxy.org/show-status</A
331 >
332     (Shortcut: <A
333 HREF="http://p.p/show-status"
334 TARGET="_top"
335 >http://p.p/show-status</A
336 >) for the
337     various actions files. 
338    </P
339 ></LI
340 ><LI
341 ><P
342 >    <TT
343 CLASS="FILENAME"
344 >default.filter</TT
345 > (the <A
346 HREF="filter-file.html"
347 >filter
348     file</A
349 >) can be used to re-write the raw page content, including
350     viewable text as well as embedded HTML and JavaScript, and whatever else
351     lurks on any given web page. The filtering jobs are only pre-defined here;
352     whether to apply them or not is up to the actions files.
353    </P
354 ></LI
355 ></UL
356 ></P
357 ><P
358 > All files use the <SPAN
359 CLASS="QUOTE"
360 >"<TT
361 CLASS="LITERAL"
362 >#</TT
363 >"</SPAN
364 > character to denote a
365  comment (the rest of the line will be ignored) and understand line continuation
366  through placing a backslash ("<TT
367 CLASS="LITERAL"
368 >\</TT
369 >") as the very last character
370  in a line. If the <TT
371 CLASS="LITERAL"
372 >#</TT
373 > is preceded by a backslash, it looses
374  its special function. Placing a <TT
375 CLASS="LITERAL"
376 >#</TT
377 > in front of an otherwise
378  valid configuration line to prevent it from being interpreted is called "commenting
379  out" that line.</P
380 ><P
381 > The actions files and <TT
382 CLASS="FILENAME"
383 >default.filter</TT
384
385  can use Perl style <A
386 HREF="appendix.html#REGEX"
387 >regular expressions</A
388 > for
389  maximum flexibility. </P
390 ><P
391 > After making any changes, there is no need to restart
392  <SPAN
393 CLASS="APPLICATION"
394 >Privoxy</SPAN
395 > in order for the changes to take
396  effect. <SPAN
397 CLASS="APPLICATION"
398 >Privoxy</SPAN
399 > detects such changes 
400  automatically. Note, however, that it may take one or two additional
401  requests for the change to take effect. When changing the listening address
402  of <SPAN
403 CLASS="APPLICATION"
404 >Privoxy</SPAN
405 >, these <SPAN
406 CLASS="QUOTE"
407 >"wake up"</SPAN
408 > requests
409  must obviously be sent to the <I
410 CLASS="EMPHASIS"
411 >old</I
412 > listening address.</P
413 ><P
414 > While under development, the configuration content is subject to change. 
415  The below documentation may not be accurate by the time you read this. 
416  Also, what constitutes a <SPAN
417 CLASS="QUOTE"
418 >"default"</SPAN
419 > setting, may change, so 
420  please check all your configuration files on important issues.</P
421 ></DIV
422 ></DIV
423 ><DIV
424 CLASS="NAVFOOTER"
425 ><HR
426 ALIGN="LEFT"
427 WIDTH="100%"><TABLE
428 WIDTH="100%"
429 BORDER="0"
430 CELLPADDING="0"
431 CELLSPACING="0"
432 ><TR
433 ><TD
434 WIDTH="33%"
435 ALIGN="left"
436 VALIGN="top"
437 ><A
438 HREF="startup.html"
439 >Prev</A
440 ></TD
441 ><TD
442 WIDTH="34%"
443 ALIGN="center"
444 VALIGN="top"
445 ><A
446 HREF="index.html"
447 >Home</A
448 ></TD
449 ><TD
450 WIDTH="33%"
451 ALIGN="right"
452 VALIGN="top"
453 ><A
454 HREF="config.html"
455 >Next</A
456 ></TD
457 ></TR
458 ><TR
459 ><TD
460 WIDTH="33%"
461 ALIGN="left"
462 VALIGN="top"
463 >Starting <SPAN
464 CLASS="APPLICATION"
465 >Privoxy</SPAN
466 ></TD
467 ><TD
468 WIDTH="34%"
469 ALIGN="center"
470 VALIGN="top"
471 >&nbsp;</TD
472 ><TD
473 WIDTH="33%"
474 ALIGN="right"
475 VALIGN="top"
476 >The Main Configuration File</TD
477 ></TR
478 ></TABLE
479 ></DIV
480 ></BODY
481 ></HTML
482 >