Recommit to include Gerry.
[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" "19 January 2008" "Privoxy 3.0.8" ""
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--chroot\fR ] [\fB--pre-chroot-nslookup \fIhostname\fB\fR ] [\fB\fIconfigfile\fB\fR ]
12
13 .SH "OPTIONS"
14 .PP
15 \fBPrivoxy\fR may be invoked with the following command line
16 options:
17 .TP
18 \fB--help\fR
19 Print brief usage info and exit.
20 .TP
21 \fB--version\fR
22 Print version info and exit.
23 .TP
24 \fB--no-daemon\fR
25 Don't  become  a daemon, i.e. don't fork and become process group
26 leader, don't detach from controlling tty, and do all logging there.
27 .TP
28 \fB--pidfile \fIpidfile\fB\fR
29 On startup, write the process ID to \fIpidfile\fR.
30 Delete the \fIpidfile\fR on exit.
31 Failure to create or delete the \fIpidfile\fR
32 is non-fatal. If no \fB--pidfile\fR option is given, no PID file will be used.
33 .TP
34 \fB--user \fIuser[.group]\fB\fR
35 After (optionally) writing the PID file, assume the user ID of
36 \fIuser\fR and the GID of
37 \fIgroup\fR, or, if the optional
38 \fIgroup\fR was not given, the default group of
39 \fIuser\fR. Exit if the privileges are not
40 sufficient to do so.
41 .TP
42 \fB--chroot\fR
43 Before changing to the user ID given in the --user option, chroot to
44 that user's home directory, i.e. make the kernel pretend to the
45 \fBPrivoxy\fR process that the directory tree starts
46 there. If set up carefully, this can limit the impact of possible
47 vulnerabilities in \fBPrivoxy\fR to the files contained in
48 that hierarchy. 
49 .TP
50 \fB--pre-chroot-nslookup \fIhostname\fB\fR
51 Initialize the resolver library using \fIhostname\fR
52 before chroot'ing. On some systems this reduces the number of files
53 that must be copied into the chroot tree.
54 .PP
55 If the \fIconfigfile\fR is not specified on  the  command  line,
56 \fBPrivoxy\fR  will  look for a file named
57 \fIconfig\fR in the current directory . If no
58 \fIconfigfile\fR is found, \fBPrivoxy\fR will 
59 fail to start.
60 .SH "DESCRIPTION"
61 .PP
62 Privoxy is a non-caching
63 web proxy
64 with advanced filtering capabilities for enhancing privacy,
65 modifying web page data, managing HTTP
66 cookies, 
67 controlling access, and removing ads, banners, pop-ups and other obnoxious
68 Internet junk. Privoxy has a flexible configuration and can be
69 customized to suit individual needs and tastes. Privoxy has application for
70 both stand-alone systems and multi-user networks.
71 .PP
72 Privoxy is based on Internet Junkbuster (tm).
73 .SH "INSTALLATION AND USAGE"
74 .PP
75 Browsers can either be individually configured to use
76 \fBPrivoxy\fR as a HTTP proxy (recommended),
77 or \fBPrivoxy\fR can be combined with a packet
78 filter to build an intercepting proxy
79 (see \fIconfig\fR).  The default setting is  for
80 localhost,  on port  8118 (configurable in the main config file).  To set the
81 HTTP proxy in Netscape and Mozilla, go through:  \fBEdit\fR;
82 \fBPreferences\fR;  \fBAdvanced\fR;
83 \fBProxies\fR;  \fBManual Proxy Configuration\fR;
84 \fBView\fR. 
85 .PP
86 For Firefox, go through: \fBTools\fR; 
87 \fBOptions\fR; \fBGeneral\fR;
88 \fBConnection Settings\fR;
89 \fBManual Proxy Configuration\fR. 
90 .PP
91 For Internet Explorer, go through: \fBTools\fR; 
92 \fBInternet Properties\fR; \fBConnections\fR;
93 \fBLAN Settings\fR. 
94 .PP
95 The Secure (SSL) Proxy should also be set to the same values, otherwise
96 https: URLs will not be proxied. Note: \fBPrivoxy\fR can only
97 proxy HTTP and HTTPS traffic. Do not try it with FTP or other protocols.
98 HTTPS presents some limitations, and not all features will work with HTTPS 
99 connections.
100 .PP
101 For other browsers, check the documentation.
102 .SH "CONFIGURATION"
103 .PP
104 \fBPrivoxy\fR can be configured with the various configuration
105 files. The default configuration files are: \fIconfig\fR,
106 \fIdefault.filter\fR, and
107 \fIdefault.action\fR. \fIuser.action\fR should 
108 be used for locally defined exceptions to the default rules of
109 \fIdefault.action\fR, and \fIuser.filter\fR for 
110 locally defined filters. These are well commented.  On Unix
111 and Unix-like systems, these are located in
112 \fI/etc/privoxy/\fR by default. 
113 .PP
114 \fBPrivoxy\fR uses the concept of \fBactions\fR 
115 in order to manipulate the data stream between the browser and remote sites.
116 There are various actions available with specific functions for such things 
117 as blocking web sites, managing cookies, etc. These actions can be invoked
118 individually or combined, and used against individual URLs, or groups of URLs 
119 that can be defined using wildcards and regular expressions. The result is
120 that the user has greatly enhanced control and freedom.
121 .PP
122 The actions list (ad blocks, etc) can also be configured with your
123 web browser at http://config.privoxy.org/ 
124 (assuming the configuration allows it).
125 \fBPrivoxy's\fR configuration parameters  can also  be viewed at
126 the same page. In addition, \fBPrivoxy\fR can be toggled on/off.
127 This is an internal page, and does not require Internet access.
128 .PP
129 See the \fIUser Manual\fR for a detailed
130 explanation of installation, general usage, all configuration options, new
131 features and notes on upgrading.
132 .SH "SAMPLE CONFIGURATION"
133 .PP
134 A brief example of what a simple \fIdefault.action\fR
135 configuration might look like:
136
137 .nf
138  # Define a few useful custom aliases for later use
139  {{alias}}
140
141  # Useful aliases that combine more than one action
142  +crunch-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
143  -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
144  +block-as-image = +block +handle-as-image
145
146  # Fragile sites should have the minimum changes
147  fragile     = -block -deanimate-gifs -fast-redirects -filter \\
148                -hide-referer -prevent-cookies -kill-popups
149
150  ## Turn some actions on ################################
151  ## NOTE: Actions are off by default, unless explictily turned on 
152  ## otherwise with the '+' operator.
153
154 { \\
155 +deanimate-gifs{last} \\
156 +filter{refresh-tags} \\
157 +filter{img-reorder} \\
158 +filter{banners-by-size} \\
159 +filter{webbugs} \\
160 +filter{jumping-windows} \\
161 +filter{ie-exploits} \\
162 +hide-forwarded-for-headers \\
163 +hide-from-header{block} \\
164 +hide-referrer{conditional-block} \\
165 +session-cookies-only \\
166 +set-image-blocker{pattern} \\
167 }
168 / # '/' Match *all* URL patterns
169
170  
171  # Block all URLs that match these patterns
172  { +block }
173   ad.
174   ad[sv].
175   .*ads.
176   banner?.
177   /.*count(er)?\\.(pl|cgi|exe|dll|asp|php[34]?)
178   .hitbox.com 
179   media./.*(ads|banner)
180
181  # Block, and treat these URL patterns as if they were 'images'.
182  # We would expect these to be ads.
183  { +block-as-image }
184   .ad.doubleclick.net
185   .a[0-9].yimg.com/(?:(?!/i/).)*$
186   ad.*.doubleclick.net
187
188  # Make exceptions for these harmless ones that would be 
189  # caught by our +block patterns just above.
190  { -block }
191   adsl.
192   adobe.
193   advice.
194   .*downloads.
195   # uploads or downloads
196   /.*loads
197 .fi
198 .PP
199 Then for a \fIuser.action\fR, we would put local,
200 narrowly defined exceptions:
201
202 .nf
203  # Re-define aliases as needed here
204  {{alias}}
205
206  # Useful aliases
207  -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
208  
209  # Set personal exceptions to the policies in default.action #######
210
211  # Sites where we want persistent cookies, so allow *all* cookies
212  { -crunch-cookies -session-cookies-only }
213   .redhat.com
214   .sun.com
215   .msdn.microsoft.com
216  
217  # These sites break easily. Use our "fragile" alias here.
218  { fragile }
219   .forbes.com
220   mybank.example.com
221
222  # Replace example.com's style sheet with one of my choosing
223  { +redirect{http://localhost/css-replacements/example.com.css} }
224   .example.com/stylesheet.css
225 .fi
226 .PP
227 See the comments in the configuration files themselves, or the 
228 \fIUser Manual\fR
229 for full explanations of the above syntax, and other \fBPrivoxy\fR
230 configuration options.
231 .SH "FILES"
232
233 .nf
234  
235  \fI/usr/sbin/privoxy\fR
236  \fI/etc/privoxy/config\fR
237  \fI/etc/privoxy/default.action\fR
238  \fI/etc/privoxy/standard.action\fR
239  \fI/etc/privoxy/user.action\fR
240  \fI/etc/privoxy/default.filter\fR
241  \fI/etc/privoxy/user.filter\fR
242  \fI/etc/privoxy/trust\fR
243  \fI/etc/privoxy/templates/*\fR
244  \fI/var/log/privoxy/logfile\fR
245 .fi
246 .PP
247 Various other files should be included, but may vary depending on platform
248 and build configuration. Additional documentation should be included in the local
249 documentation directory.
250 .SH "SIGNALS"
251 .PP
252 \fBPrivoxy\fR terminates on the \fBSIGINT\fR,
253 \fBSIGTERM\fR and \fBSIGABRT\fR signals. Log
254 rotation scripts may cause a re-opening of the logfile by sending a 
255 \fBSIGHUP\fR to \fBPrivoxy\fR. Note that unlike
256 other daemons,  \fBPrivoxy\fR does not need to be made aware of
257 config file changes by \fBSIGHUP\fR -- it will detect them
258 automatically. 
259 .SH "NOTES"
260 .PP
261 Please see the \fIUser Manual\fR on how to contact the
262 developers, for feature requests, reporting problems, and other questions.
263 .SH "SEE ALSO"
264 .PP
265 Other references and sites of interest to \fBPrivoxy\fR
266 users:
267 .PP
268
269 http://www.privoxy.org/, 
270 the \fBPrivoxy\fR Home page. 
271
272 http://www.privoxy.org/faq/, 
273 the \fBPrivoxy\fR FAQ. 
274
275 http://sourceforge.net/projects/ijbswa/, 
276 the Project Page for \fBPrivoxy\fR on 
277 SourceForge.
278
279 http://config.privoxy.org/,
280 the web-based user interface. \fBPrivoxy\fR must be
281 running for this to work. Shortcut: http://p.p/
282
283 http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit ``misses'' and other
284 configuration related suggestions to the developers. 
285
286 http://www.junkbusters.com/ht/en/cookies.html,
287 an explanation how cookies are used to track web users.
288
289 http://www.junkbusters.com/ijb.html,
290 the original Internet Junkbuster.
291
292 http://privacy.net/, a useful site
293 to check what information about you is leaked while you browse the web.
294
295 http://www.squid-cache.org/, a popular
296 caching proxy, which is often used together with \fBPrivoxy\fR.
297
298 http://www.pps.jussieu.fr/~jch/software/polipo/,
299 \fBPolipo\fR is a caching proxy with advanced features
300 like pipelining, multiplexing and caching of partial instances. In many setups
301 it can be used as \fBSquid\fR replacement.
302
303 http://tor.eff.org/, 
304 \fBTor\fR can help anonymize web browsing, 
305 web publishing, instant messaging, IRC, SSH, and other applications.
306
307 http://www.privoxy.org/developer-manual/, 
308 the \fBPrivoxy\fR developer manual. 
309 .SH "DEVELOPMENT TEAM"
310
311 .nf
312  Fabian Keil, lead developer
313  David Schmidt, developer
314  
315  Hal Burgiss
316  Gerry Murphy
317  Roland Rosenfeld
318  J├Ârg Strohmayer
319 .fi
320 .SH "COPYRIGHT AND LICENSE"
321 .SS "COPYRIGHT"
322 .PP
323 Copyright (C) 2001-2007 by Privoxy Developers <ijbswa-developers@lists.sourceforge.net>
324 .PP
325 Some source code is based on code Copyright (C) 1997 by Anonymous Coders
326 and Junkbusters, Inc. and licensed under the \fIGNU General Public
327 License\fR.
328 .SS "LICENSE"
329 .PP
330 \fBPrivoxy\fR is free software; you can
331 redistribute it and/or modify it under the terms of the 
332 \fIGNU General Public
333 License\fR, version 2, as published by the Free Software Foundation.
334 .PP
335 This program is distributed in the hope that it will be useful, but WITHOUT
336 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
337 FITNESS FOR A PARTICULAR PURPOSE.  See the 
338 \fIGNU General Public License\fR for
339 more details, which is available from the Free Software Foundation, Inc, 
340 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
341 .PP
342 You should have received a copy of the  \fIGNU General Public License\fR
343 along with this program; if not, write to the  Free Software
344 Foundation, Inc. 51 Franklin Street, Fifth Floor
345 Boston, MA 02110-1301
346 USA