2 File : doc/source/privoxy-man-page.sgml
6 Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/
9 ========================================================================
10 NOTE: Please read developer-manual/documentation.html before touching
11 anything in this, or other Privoxy documentation.
12 ========================================================================
14 Doc NOTES: This is some tricky markup! There are some quirks
15 to how this markup is handled. It is not always so co-operative.
16 Please don't change the markup unless you can verify the changes
17 will improve finished output!
19 literallayout tags are particularly sensitive to where they are placed.
20 The 'replaceable' and 'command' tags are used here somewhat unconventionally,
21 since it seems to generate the proper formatting (at least for me :).
23 Create man page: 'make man'
25 Requires docbook2man (short perl script), see CVS
26 http://sources.redhat.com/docbook-tools/. Also requires openjade and SGMLSpm
29 For man page references, see:
30 http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/using.html
31 http://docbook.org/tdg/en/html/ch02.html#making-refentry
34 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
35 <!entity % dummy "IGNORE">
36 <!entity p-intro SYSTEM "privoxy.sgml">
37 <!entity seealso SYSTEM "seealso.sgml">
38 <!entity copyright SYSTEM "copyright.sgml">
39 <!entity license SYSTEM "license.sgml">
40 <!entity authors SYSTEM "p-authors.sgml">
41 <!entity p-version "3.0.35">
42 <!entity p-status "UNRELEASED">
43 <!entity % p-not-stable "INCLUDE">
44 <!entity % p-stable "IGNORE">
45 <!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
46 <!entity % p-authors-formal "IGNORE"> <!-- exclude additional formatting -->
47 <!entity my-copy "(C)"> <!-- db2man barfs on copyright symbol -->
48 <!entity % seealso-extra "IGNORE"> <!-- for excluding sections of seealso -->
51 <refentry id="privoxy">
53 <date>2012-11-08</date>
56 <refentrytitle>privoxy</refentrytitle>
57 <manvolnum>8</manvolnum>
59 Privoxy &p-version;<![%p-not-stable;[ &p-status;]]>
64 <refname><application>privoxy</application></refname>
65 <refpurpose>Privacy Enhancing Proxy</refpurpose>
70 <command>privoxy</command>
71 <arg><option>--chroot</option></arg>
72 <arg><option>--config-test</option></arg>
73 <arg><option>--help</option></arg>
74 <arg><option>--no-daemon</option></arg>
75 <arg><option>--pidfile </option><replaceable class="parameter">pidfile</replaceable></arg>
76 <arg><option>--pre-chroot-nslookup </option><replaceable class="parameter">hostname</replaceable></arg>
77 <arg><option>--user </option><replaceable class="parameter">user[.group]</replaceable></arg>
78 <arg><option>--version</option></arg>
79 <arg><replaceable class="parameter">configfile</replaceable></arg>
85 <!-- ~~~~~ New section ~~~~~ -->
86 <refsect1><title>Options</title>
88 <command>Privoxy</command> may be invoked with the following command line
98 Before changing to the user ID given in the --user option, chroot to
99 that user's home directory, i.e. make the kernel pretend to the
100 <command>Privoxy</command> process that the directory tree starts
101 there. If set up carefully, this can limit the impact of possible
102 vulnerabilities in <command>Privoxy</command> to the files contained in
109 <term>--config-test</term>
112 Exit after loading the configuration files before binding to
113 the listen address. The exit code signals whether or not the
114 configuration files have been successfully loaded.
117 If the exit code is 1, at least one of the configuration files
118 is invalid, if it is 0, all the configuration files have been
119 successfully loaded (but may still contain errors that can
120 currently only be detected at run time).
123 This option doesn't affect the log setting, combination with
124 "--no-daemon" is recommended if a configured log file shouldn't
134 Print brief usage info and exit.
140 <term>--no-daemon</term>
143 Don't become a daemon, i.e. don't fork and become process group
144 leader, don't detach from controlling tty, and do all logging there.
150 <term>--pidfile <replaceable class="parameter">pidfile</replaceable></term>
153 On startup, write the process ID to <replaceable class="parameter">pidfile</replaceable>.
154 Delete the <replaceable class="parameter">pidfile</replaceable> on exit.
155 Failure to create or delete the <replaceable class="parameter">pidfile</replaceable>
156 is non-fatal. If no <command>--pidfile</command> option is given, no PID file will be used.
162 <term>--pre-chroot-nslookup <replaceable class="parameter">hostname</replaceable></term>
165 Initialize the resolver library using <replaceable class="parameter">hostname</replaceable>
166 before chroot'ing. On some systems this reduces the number of files
167 that must be copied into the chroot tree.
173 <term>--user <replaceable class="parameter">user[.group]</replaceable></term>
176 <!-- Note: replaceable is maybe the wrong tag, but generates -->
177 <!-- correct looking man output. -->
178 After (optionally) writing the PID file, assume the user ID of
179 <replaceable class="parameter">user</replaceable> and the GID of
180 <replaceable class="parameter">group</replaceable>, or, if the optional
181 <replaceable class="parameter">group</replaceable> was not given, the default group of
182 <replaceable class="parameter">user</replaceable>. Exit if the privileges are not
189 <term>--version</term>
192 Print version info and exit.
200 If the <filename>configfile</filename> is not specified on the command line,
201 <command>Privoxy</command> will look for a file named
202 <filename>config</filename> in the current directory. If no
203 <filename>configfile</filename> is found, <command>Privoxy</command> will
210 <!-- ~~~~~ New section ~~~~~ -->
211 <refsect1><title>Description</title>
212 <!-- Include privoxy.sgml boilerplate: -->
214 <!-- end boilerplate -->
218 <!-- ~~~~~ New section ~~~~~ -->
219 <refsect1><title>Installation and Usage</title>
221 Browsers can either be individually configured to use
222 <command>Privoxy</command> as a HTTP proxy (recommended),
223 or <command>Privoxy</command> can be combined with a packet
224 filter to build an intercepting proxy
225 (see <filename>config</filename>). The default setting is for
226 localhost, on port 8118 (configurable in the main config file). To set the
227 HTTP proxy in Firefox, go through: <command>Tools</command>;
228 <command>Options</command>; <command>General</command>;
229 <command>Connection Settings</command>;
230 <command>Manual Proxy Configuration</command>.
233 For Internet Explorer, go through: <command>Tools</command>;
234 <command>Internet Properties</command>; <command>Connections</command>;
235 <command>LAN Settings</command>.
238 The Secure (SSL) Proxy should also be set to the same values, otherwise
239 https: URLs will not be proxied. Note: <command>Privoxy</command> can only
240 proxy HTTP and HTTPS traffic. Do not try it with FTP or other protocols.
241 HTTPS presents some limitations, and not all features will work with HTTPS
246 For other browsers, check the documentation.
251 <!-- ~~~~~ New section ~~~~~ -->
252 <refsect1><title>Configuration</title>
254 <command>Privoxy</command> can be configured with the various configuration
255 files. The default configuration files are: <filename>config</filename>,
256 <filename>default.filter</filename>, <filename>default.action</filename> and
257 <filename>default.action</filename>. <filename>user.action</filename> should
258 be used for locally defined exceptions to the default rules in
259 <filename>match-all.action</filename> and <filename>default.action</filename>,
260 and <filename>user.filter</filename> for locally defined filters. These are
261 well commented. On Unix and Unix-like systems, these are located in
262 <filename>/etc/privoxy/</filename> by default.
265 <command>Privoxy</command> uses the concept of <command>actions</command>
266 in order to manipulate the data stream between the browser and remote sites.
267 There are various actions available with specific functions for such things
268 as blocking web sites, managing cookies, etc. These actions can be invoked
269 individually or combined, and used against individual URLs, or groups of URLs
270 that can be defined using wildcards and regular expressions. The result is
271 that the user has greatly enhanced control and freedom.
274 The actions list (ad blocks, etc) can also be configured with your
275 web browser at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
276 (assuming the configuration allows it).
277 <command>Privoxy's</command> configuration parameters can also be viewed at
278 the same page. In addition, <command>Privoxy</command> can be toggled on/off.
279 This is an internal page, and does not require Internet access.
283 url="https://www.privoxy.org/user-manual/"><citetitle>User Manual</citetitle></ulink> for a detailed
284 explanation of installation, general usage, all configuration options, new
285 features and notes on upgrading.
291 <!-- ~~~~~ New section ~~~~~ -->
292 <refsect1><title>Files</title>
293 <!-- this is a cheesy way to do this, but WTF. -->
295 <filename>/usr/sbin/privoxy</filename>
296 <filename>/etc/privoxy/config</filename>
297 <filename>/etc/privoxy/match-all.action</filename>
298 <filename>/etc/privoxy/default.action</filename>
299 <filename>/etc/privoxy/user.action</filename>
300 <filename>/etc/privoxy/default.filter</filename>
301 <filename>/etc/privoxy/user.filter</filename>
302 <filename>/etc/privoxy/trust</filename>
303 <filename>/etc/privoxy/templates/*</filename>
304 <filename>/var/log/privoxy/logfile</filename>
308 Various other files should be included, but may vary depending on platform
309 and build configuration. Additional documentation should be included in the local
310 documentation directory.
316 <!-- ~~~~~ New section ~~~~~ -->
317 <refsect1><title>Signals</title>
319 <!-- command tag is used here to get proper looking format -->
320 <command>Privoxy</command> terminates on the <command>SIGINT</command>
321 and <command>SIGTERM</command> signals. Log
322 rotation scripts may cause a re-opening of the logfile by sending a
323 <command>SIGHUP</command> to <command>Privoxy</command>. Note that unlike
324 other daemons, <command>Privoxy</command> does not need to be made aware of
325 config file changes by <command>SIGHUP</command> -- it will detect them
326 automatically. Signals other than the ones listed above aren't explicitly
327 handled and result in the default action defined by the operating system.
332 <!-- ~~~~~ New section ~~~~~ -->
333 <refsect1><title>Notes</title>
336 This is a &p-status; version of <command>Privoxy</command>. Not
337 all features are well tested.
340 Please see the <citetitle>User Manual</citetitle> on how to contact the
341 developers, for feature requests, reporting problems, and other questions.
346 <!-- ~~~~~ New section ~~~~~ -->
347 <refsect1><title>See Also</title>
348 <!-- Include seealso.sgml boilerplate: -->
350 <!-- end boilerplate -->
353 <!-- ~~~~~ New section ~~~~~ -->
354 <refsect1><title>Development Team</title>
355 <!-- Include p-authors.sgml boilerplate: -->
357 <!-- end boilerplate -->
360 <!-- ~~~~~ New section ~~~~~ -->
361 <refsect1><title>Copyright and License</title>
363 <refsect2><title>Copyright</title>
364 <!-- Include copyright.sgml boilerplate: -->
366 <!-- end boilerplate -->
369 <refsect2><title>License</title>
370 <!-- Include license.sgml boilerplate: -->
372 <!-- end boilerplate -->