5690eee49c12689f5bf3ac6a6dec3f06c5985616
[privoxy.git] / privoxy.1
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document.  This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "PRIVOXY" "1" "05 September 2002" "Privoxy 3.1.1 alpha" ""
7 .SH NAME
8 privoxy \- Privacy Enhancing Proxy
9 .SH SYNOPSIS
10
11 \fBprivoxy\fR [\fB--help\fR ] [\fB--version\fR ] [\fB--no-daemon\fR ] [\fB--pidfile \fIpidfile\fB\fR ] [\fB--user \fIuser[.group]\fB\fR ] [\fB\fIconfigfile\fB\fR ]\fB (UNIX)\fR
12
13
14 \fBprivoxy.exe\fR [\fB\fIconfigfile\fB\fR ]\fB (Windows)\fR
15
16 .SH "OPTIONS"
17 .PP
18 \fBPrivoxy\fR may be invoked with the following command line
19 options:
20 .TP
21 \fB--help\fR
22 Print brief usage info and exit.
23 .TP
24 \fB--version\fR
25 Print version info and exit.
26 .TP
27 \fB--no-daemon\fR
28 Don't  become  a daemon, i.e. don't fork and become process group
29 leader, don't detach from controlling tty, and do all logging there.
30 .TP
31 \fB--pidfile \fIpidfile\fB\fR
32 On startup, write the process ID to \fIpidfile\fR.
33 Delete the \fIpidfile\fR on exit.
34 Failure to create or delete the \fIpidfile\fR
35 is non-fatal. If no \fB--pidfile\fR option is given, no PID file will be used.
36 .TP
37 \fB--user \fIuser[.group]\fB\fR
38 After (optionally) writing the PID file, assume the user ID of
39 \fIuser\fR and the GID of
40 \fIgroup\fR, or, if the optional
41 \fIgroup\fR was not given, the default group of
42 \fIuser\fR. Exit if the privileges are not
43 sufficient to do so.
44 .PP
45 If the \fIconfigfile\fR is not specified on  the  command  line,
46 \fBPrivoxy\fR  will  look for a file named
47 \fIconfig\fR in the current directory (except on Win32 where
48 it will try \fIconfig.txt\fR). If no
49 \fIconfigfile\fR is found, \fBPrivoxy\fR will 
50 fail to start.
51 .SH "DESCRIPTION"
52 .PP
53 \fBPrivoxy\fR is a web proxy with advanced filtering
54 capabilities for protecting privacy, filtering web page content, managing
55 cookies, controlling access, and removing ads, banners, pop-ups and other
56 obnoxious Internet junk. \fBPrivoxy\fR has a very
57 flexible configuration and can be customized to suit individual needs and
58 tastes. \fBPrivoxy\fR has application for both
59 stand-alone systems and multi-user networks.
60 .PP
61 \fBPrivoxy\fR is based on \fBInternet
62 Junkbuster\fR (tm).
63 .SH "INSTALLATION AND USAGE"
64 .PP
65 Browsers must be individually configured to use \fBPrivoxy\fR as
66 a HTTP proxy.  The default setting is  for  localhost,  on port  8118
67 (configurable in the main config file).  To set the HTTP proxy in Netscape
68 and Mozilla, go through:  \fBEdit\fR;
69 \fBPreferences\fR;  \fBAdvanced\fR;
70 \fBProxies\fR;  \fBManual Proxy Configuration\fR;
71 \fBView\fR. 
72 .PP
73 For Internet Explorer, go through: \fBTools\fR; 
74 \fBInternet Properties\fR; \fBConnections\fR;
75 \fBLAN Settings\fR. 
76 .PP
77 The Secure (SSL) Proxy should also be set to the same values, otherwise
78 https: URLs will not be proxied. Note: \fBPrivoxy\fR can only
79 proxy HTTP and HTTPS traffic. Do not try it with FTP or other protocols.
80 .PP
81 For other browsers, check the documentation.
82 .SH "CONFIGURATION"
83 .PP
84 \fBPrivoxy\fR can be configured with the various configuration
85 files. The default configuration files are: \fIconfig\fR,
86 \fIdefault.filter\fR, and
87 \fIdefault.action\fR. \fIuser.action\fR should 
88 be used for locally defined exceptions to the default rules of
89 \fIdefault.action\fR These are all well commented.  On Unix
90 and Unix-like systems, these are located in
91 \fI/etc/privoxy/\fR by default. On Windows, OS/2 and AmigaOS,
92 these files are in the same directory as the \fBPrivoxy\fR
93 executable.
94 .PP
95 The name and number of configuration files has changed from previous
96 versions, and is subject to change as development
97 progresses. In fact, the configuration itself is changed  and  much more
98 sophisticated. See the user-manual for a complete
99 explanation of all configuration options and general usage, and notes for 
100 upgrading from \fBJunkbuster\fR and earlier \fBPrivoxy\fR
101 versions.
102 .PP
103 The actions list (ad blocks, etc) can also be configured with your
104 web browser at http://config.privoxy.org/.
105 \fBPrivoxy's\fR configuration parameters  can also  be viewed at
106 the same page. In addition, \fBPrivoxy\fR can be toggled on/off.
107 This is an internal page, and does not require Internet access.
108 .SH "SAMPLE CONFIGURATION"
109 .PP
110 A brief example of what a simple \fIdefault.action\fR
111 configuration might look like:
112
113 .nf
114  # Define a few useful custom aliases for later use
115  {{alias}}
116
117  # Useful aliases
118  +crunch-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
119  -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
120  +imageblock      = +block +handle-as-image
121
122  # Fragile sites should have the minimum changes
123  fragile     = -block -deanimate-gifs -fast-redirects -filter \\
124                -hide-referer -prevent-cookies -kill-popups
125
126  ## Turn some actions on ################################
127  { \\
128  -add-header \\
129  -block \\
130  +deanimate-gifs{last} \\
131  -downgrade-http-version \\
132  -fast-redirects \\
133  +filter{html-annoyances} \\
134  +filter{js-annoyances} \\
135  +filter{content-cookies} \\
136  +filter{webbugs} \\
137  +filter{banners-by-size} \\
138  +hide-forwarded-for-headers \\
139  +hide-from-header{block} \\
140  +hide-referrer{forge} \\
141  -hide-user-agent \\
142  -handle-as-image \\
143  +set-image-blocker{pattern} \\
144  -limit-connect \\
145  +prevent-compression \\
146  +session-cookies-only \\
147  -crunch-cookies \\
148  -kill-popups \\
149  }
150  /   # '/' Matches *all* URL patterns
151  
152  # Block, and treat these URL patterns as if they were 'images'.
153  # We would expect these to be ads.
154  {+imageblock}
155   .ad.doubleclick.net
156   .a[0-9].yimg.com/(?:(?!/i/).)*$
157   ad.*.doubleclick.net
158
159  # Block any URLs that match these patterns
160  {+block}
161   ad*.
162   .*ads.
163   banner?.
164   /.*count(er)?\\.(pl|cgi|exe|dll|asp|php[34]?)
165   .hitbox.com 
166
167  # Make exceptions for these harmless ones that would be 
168  # caught by our +block patterns just above.
169  {-block}
170   adsl.
171   advice.
172   .*downloads.
173 .fi
174 .PP
175 Then for a \fIuser.action\fR, we would put local,
176 narrowly defined exceptions:
177
178 .nf
179  # Re-define aliases as needed here
180  {{alias}}
181
182  # Useful aliases
183  -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
184  
185  # Set personal exceptions to the policies in default.action #######
186
187  # Sites where we want persistant cookies, so allow *all* cookies
188  {-crunch-cookies -session-cookies-only}
189   .redhat.com
190   .sun.com
191   .msdn.microsoft.com
192  
193  # This site breaks easily.
194  {-block -fast-redirects}
195   .forbes.com
196 .fi
197 .PP
198 See the comments in the configuration files themselves, or the 
199 \fIuser-manual\fR
200 for explanations of the above syntax, and other \fBPrivoxy\fR
201 configuration options.
202 .SH "FILES"
203
204 .nf
205  
206  \fI/usr/sbin/privoxy\fR
207  \fI/etc/privoxy/config\fR
208  \fI/etc/privoxy/default.action\fR
209  \fI/etc/privoxy/standard.action\fR
210  \fI/etc/privoxy/user.action\fR
211  \fI/etc/privoxy/default.filter\fR
212  \fI/etc/privoxy/trust\fR
213  \fI/etc/privoxy/templates/*\fR
214  \fI/var/log/privoxy/logfile\fR
215 .fi
216 .PP
217 Various other files should be included, but may vary depending on platform
218 and build configuration. More documentation should be included in the local
219 documentation directory.
220 .SH "SIGNALS"
221 .PP
222 \fBPrivoxy\fR terminates on the \fBSIGINT\fR,
223 \fBSIGTERM\fR and \fBSIGABRT\fR signals. Log
224 rotation scripts may cause a re-opening of the logfile by sending a 
225 \fBSIGHUP\fR to \fBPrivoxy\fR. Note that unlike
226 other daemons,  \fBPrivoxy\fR does not need to be made aware of
227 config file changes by \fBSIGHUP\fR -- it will detect them
228 automatically. 
229 .SH "NOTES"
230 .PP
231 This is a alpha version of \fBPrivoxy\fR. Not 
232 all features are well tested.
233 .PP
234 Please see the \fIUser Manual\fR on how to contact the
235 developers for feature requests, reporting problems, and other questions.
236 .SH "SEE ALSO"
237 .PP
238 Other references and sites of interest to \fBPrivoxy\fR
239 users:
240 .PP
241
242 http://www.privoxy.org/, 
243 the \fBPrivoxy\fR Home page. 
244
245 http://www.privoxy.org/faq/, 
246 the \fBPrivoxy\fR FAQ. 
247
248 http://sourceforge.net/projects/ijbswa/, 
249 the Project Page for \fBPrivoxy\fR on 
250 SourceForge.
251
252 http://config.privoxy.org/,
253 the web-based user interface. \fBPrivoxy\fR must be
254 running for this to work. Shortcut: http://p.p/
255
256 http://www.privoxy.org/actions/, to submit ``misses'' to the developers. 
257
258 http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/contrib/, cool
259 and fun ideas from \fBPrivoxy\fR users.
260
261 http://www.junkbusters.com/ht/en/cookies.html,
262 an explanation how cookies are used to track web users.
263
264 http://www.junkbusters.com/ijb.html,
265 the original Internet Junkbuster.
266
267 http://www.waldherr.org/junkbuster/,
268 Stefan Waldherr's version of Junkbuster, from which \fBPrivoxy\fR was
269 derived.
270
271 http://privacy.net/analyze/, a useful site
272 to check what information about you is leaked while you browse the web.
273
274 http://www.squid-cache.org/, a very popular
275 caching proxy, which is often used together with \fBPrivoxy\fR.
276
277 http://www.privoxy.org/developer-manual/, 
278 the \fBPrivoxy\fR developer manual. 
279 .SH "DEVELOPMENT TEAM"
280
281 .nf
282  Jon Foster
283  Andreas Oesterhelt
284  Stefan Waldherr
285  Thomas Steudten
286  Rodney Stromlund
287  Rodrigo Barbosa (RPM specfiles)
288  Moritz Barsnick
289  Hal Burgiss (docs)
290  Karsten Hopp (Red Hat)
291  Alexander Lazic
292  Gábor Lipták
293  Guy
294  Haroon Rafique
295  Roland Rosenfeld (Debian)
296  Georg Sauthoff (Gentoo)
297  David Schmidt (OS/2, Mac OSX ports)
298  Joerg Strohmayer (Amiga)
299  Sarantis Paskalis
300 .fi
301 .SH "COPYRIGHT AND LICENSE"
302 .SS "COPYRIGHT"
303 .PP
304 Copyright (C) 2001, 2002 by Privoxy Developers <developers@privoxy.org>
305 .PP
306 Some source code is based on code Copyright (C) 1997 by Anonymous Coders
307 and Junkbusters, Inc. and licensed under the \fIGNU General Public
308 License\fR.
309 .SS "LICENSE"
310 .PP
311 \fBPrivoxy\fR is free software; you can
312 redistribute it and/or modify it under the terms of the 
313 \fIGNU General Public
314 License\fR, version 2, as published by the Free Software Foundation.
315 .PP
316 This program is distributed in the hope that it will be useful, but WITHOUT
317 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
318 FITNESS FOR A PARTICULAR PURPOSE.  See the 
319 \fIGNU General Public License\fR for
320 more details, which is available from the Free Software Foundation, Inc, 59
321 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
322 .PP
323 You should have received a copy of the  \fIGNU General Public License\fR
324 along with this program; if not, write to the  Free Software
325 Foundation, Inc. 59 Temple Place - Suite 330
326 Boston, MA 02111-1307
327 USA