1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
8 <meta name="GENERATOR" content=
9 "Modular DocBook HTML Stylesheet Version 1.79">
10 <link rel="HOME" title="Privoxy 3.0.25 User Manual" href="index.html">
11 <link rel="PREVIOUS" title="Introduction" href="introduction.html">
12 <link rel="NEXT" title="What's New in this Release" href="whatsnew.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">
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">
23 <th colspan="3" align="center">
24 Privoxy 3.0.25 User Manual
28 <td width="10%" align="left" valign="bottom">
29 <a href="introduction.html" accesskey="P">Prev</a>
31 <td width="80%" align="center" valign="bottom">
33 <td width="10%" align="right" valign="bottom">
34 <a href="whatsnew.html" accesskey="N">Next</a>
38 <hr align="LEFT" width="100%">
42 <a name="INSTALLATION">2. Installation</a>
45 <span class="APPLICATION">Privoxy</span> is available both in
46 convenient pre-compiled packages for a wide range of operating
47 systems, and as raw source code. For most users, we recommend using
48 the packages, which can be downloaded from our <a href=
49 "https://sourceforge.net/projects/ijbswa/" target="_top">Privoxy
53 Note: On some platforms, the installer may remove previously
54 installed versions, if found. (See below for your platform). In any
55 case <span class="emphasis"><i class="EMPHASIS">be sure to backup
56 your old configuration if it is valuable to you.</i></span> See the
57 <a href="whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section
62 <a name="INSTALLATION-PACKAGES">2.1. Binary Packages</a>
65 How to install the binary packages depends on your operating
70 <a name="INSTALLATION-DEB">2.1.1. Debian and Ubuntu</a>
73 DEBs can be installed with <tt class="LITERAL">apt-get install
74 privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt>
75 for the location of configuration files.
80 <a name="INSTALLATION-PACK-WIN">2.1.2. Windows</a>
83 Just double-click the installer, which will guide you through the
84 installation process. You will find the configuration files in
85 the same directory as you installed <span class=
86 "APPLICATION">Privoxy</span> in.
89 Version 3.0.5 beta introduced full <span class=
90 "APPLICATION">Windows</span> service functionality. On Windows
91 only, the <span class="APPLICATION">Privoxy</span> program has
92 two new command line arguments to install and uninstall <span
93 class="APPLICATION">Privoxy</span> as a <span class="emphasis"><i
94 class="EMPHASIS">service</i></span>.
96 <div class="VARIABLELIST">
103 <tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class=
104 "REPLACEABLE"><i>service_name</i></tt>]
107 <tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class=
108 "REPLACEABLE"><i>service_name</i></tt>]
114 After invoking <span class="APPLICATION">Privoxy</span> with <b
115 class="COMMAND">--install</b>, you will need to bring up the
116 <span class="APPLICATION">Windows</span> service console to
117 assign the user you want <span class="APPLICATION">Privoxy</span>
118 to run under, and whether or not you want it to run whenever the
119 system starts. You can start the <span class=
120 "APPLICATION">Windows</span> services console with the following
121 command: <b class="COMMAND">services.msc</b>. If you do not take
122 the manual step of modifying <span class=
123 "APPLICATION">Privoxy's</span> service settings, it will not
124 start. Note too that you will need to give Privoxy a user account
125 that actually exists, or it will not be permitted to write to its
126 log and configuration files.
131 <a name="INSTALLATION-OS2">2.1.3. OS/2</a>
134 First, make sure that no previous installations of <span class=
135 "APPLICATION">Junkbuster</span> and / or <span class=
136 "APPLICATION">Privoxy</span> are left on your system. Check that
137 no <span class="APPLICATION">Junkbuster</span> or <span class=
138 "APPLICATION">Privoxy</span> objects are in your startup
142 Then, just double-click the WarpIN self-installing archive, which
143 will guide you through the installation process. A shadow of the
144 <span class="APPLICATION">Privoxy</span> executable will be
145 placed in your startup folder so it will start automatically
146 whenever OS/2 starts.
149 The directory you choose to install <span class=
150 "APPLICATION">Privoxy</span> into will contain all of the
156 <a name="INSTALLATION-MAC">2.1.4. Mac OS X</a>
159 Installation instructions for the OS X platform depend upon
160 whether you downloaded a ready-built installation package (.pkg
161 or .mpkg) or have downloaded the source code.
166 <a name="OS-X-INSTALL-FROM-PACKAGE">2.1.5. Installation from
167 ready-built package</a>
170 The downloaded file will either be a .pkg (for OS X 10.5 upwards)
171 or a bzipped .mpkg file (for OS X 10.4). The former can be
172 double-clicked as is and the installation will start;
173 double-clicking the latter will unzip the .mpkg file which can
174 then be double-clicked to commence the installation.
177 The privoxy service will automatically start after a successful
178 installation (and thereafter every time your computer starts up)
179 however you will need to configure your web browser(s) to use it.
180 To do so, configure them to use a proxy for HTTP and HTTPS at the
181 address 127.0.0.1:8118.
184 To prevent the privoxy service from automatically starting when
185 your computer starts up, remove or rename the file <tt class=
186 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt>
187 (on OS X 10.5 and higher) or the folder named <tt class=
188 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
192 To manually start or stop the privoxy service, use the scripts
193 startPrivoxy.sh and stopPrivoxy.sh supplied in
194 /Applications/Privoxy. They must be run from an administrator
198 To uninstall, run /Applications/Privoxy/uninstall.command as sudo
199 from an administrator account.
204 <a name="OS-X-INSTALL-FROM-SOURCE">2.1.6. Installation from
208 To build and install the Privoxy source code on OS X you will
209 need to obtain the macsetup module from the Privoxy Sourceforge
210 CVS repository (refer to Sourceforge help for details of how to
211 set up a CVS client to have read-only access to the repository).
212 This module contains scripts that leverage the usual open-source
213 tools (available as part of Apple's free of charge Xcode
214 distribution or via the usual open-source software package
215 managers for OS X (MacPorts, Homebrew, Fink etc.) to build and
216 then install the privoxy binary and associated files. The
217 macsetup module's README file contains complete instructions for
221 The privoxy service will automatically start after a successful
222 installation (and thereafter every time your computer starts up)
223 however you will need to configure your web browser(s) to use it.
224 To do so, configure them to use a proxy for HTTP and HTTPS at the
225 address 127.0.0.1:8118.
228 To prevent the privoxy service from automatically starting when
229 your computer starts up, remove or rename the file <tt class=
230 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt>
231 (on OS X 10.5 and higher) or the folder named <tt class=
232 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
236 To manually start or stop the privoxy service, use the Privoxy
237 Utility for Mac OS X (also part of the macsetup module). This
238 application can start and stop the privoxy service and display
239 its log and configuration files.
242 To uninstall, run the macsetup module's uninstall.sh as sudo from
243 an administrator account.
248 <a name="INSTALLATION-FREEBSD">2.1.7. FreeBSD</a>
251 Privoxy is part of FreeBSD's Ports Collection, you can build and
252 install it with <tt class="LITERAL">cd /usr/ports/www/privoxy;
253 make install clean</tt>.
259 <a name="INSTALLATION-SOURCE">2.2. Building from Source</a>
262 The most convenient way to obtain the <span class=
263 "APPLICATION">Privoxy</span> sources is to download the source
264 tarball from our <a href=
265 "https://sourceforge.net/projects/ijbswa/files/Sources/" target=
266 "_top">project download page</a>.
269 If you like to live on the bleeding edge and are not afraid of
270 using possibly unstable development versions, you can check out the
271 up-to-the-minute version directly from <a href=
272 "https://sourceforge.net/p/ijbswa/code/?source=navbar" target=
273 "_top">the CVS repository</a>.
276 To build <span class="APPLICATION">Privoxy</span> from source, <a
277 href="http://www.gnu.org/software/autoconf/autoconf.html" target=
278 "_top">autoconf</a>, <a href=
279 "http://www.gnu.org/software/make/make.html" target="_top">GNU make
280 (gmake)</a>, and, of course, a C compiler like <a href=
281 "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a>
285 When building from a source tarball, first unpack the source:
289 <table border="0" bgcolor="#E0E0E0" width="100%">
293 tar xzvf privoxy-3.0.25-beta-src.tar.gz
294 cd privoxy-3.0.25-beta
301 For retrieving the current CVS sources, you'll need a CVS client
302 installed. Note that sources from CVS are typically development
303 quality, and may not be stable, or well tested. To download CVS
304 source, check the Sourceforge documentation, which might give
309 <table border="0" bgcolor="#E0E0E0" width="100%">
313 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
314 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
322 This will create a directory named <tt class=
323 "FILENAME">current/</tt>, which will contain the source tree.
326 You can also check out any <span class="APPLICATION">Privoxy</span>
327 <span class="QUOTE">"branch"</span>, just exchange the <span class=
328 "APPLICATION">current</span> name with the wanted branch name
329 (Example: v_3_0_branch for the 3.0 cvs tree).
332 It is also strongly recommended to not run <span class=
333 "APPLICATION">Privoxy</span> as root. You should
334 configure/install/run <span class="APPLICATION">Privoxy</span> as
335 an unprivileged user, preferably by creating a <span class=
336 "QUOTE">"privoxy"</span> user and group just for this purpose. See
337 your local documentation for the correct command line to do add new
338 users and groups (something like <b class="COMMAND">adduser</b>,
339 but the command syntax may vary from platform to platform).
342 <tt class="FILENAME">/etc/passwd</tt> might then look like:
346 <table border="0" bgcolor="#E0E0E0" width="100%">
350 privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
357 And then <tt class="FILENAME">/etc/group</tt>, like:
361 <table border="0" bgcolor="#E0E0E0" width="100%">
372 Some binary packages may do this for you.
375 Then, to build from either unpacked tarball or CVS source:
379 <table border="0" bgcolor="#E0E0E0" width="100%">
385 ./configure # (--help to see options)
386 make # (the make from GNU, sometimes called gmake)
387 su # Possibly required
388 make -n install # (to see where all the files will go)
389 make -s install # (to really install, -s to silence output)
396 Using GNU <b class="COMMAND">make</b>, you can have the first four
397 steps automatically done for you by just typing:
401 <table border="0" bgcolor="#E0E0E0" width="100%">
412 in the freshly downloaded or unpacked source directory.
415 To build an executable with security enhanced features so that
416 users cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go
417 There Anyway"</span>), or alter their own configurations, <b class=
418 "COMMAND">configure</b> like this:
422 <table border="0" bgcolor="#E0E0E0" width="100%">
426 ./configure --disable-toggle --disable-editor --disable-force
433 Note that all of these options can also be disabled through the
437 <span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If
438 installing as root, the install will fail unless a non-root user or
439 group is specified, or a <tt class="LITERAL">privoxy</tt> user and
440 group already exist on the system. If a non-root user is specified,
441 and no group, then the installation will try to also use a group of
442 the same name as <span class="QUOTE">"user"</span>. If a group is
443 specified (and no user), then the support files will be installed
444 as writable by that group, and owned by the user running the
448 <b class="COMMAND">configure</b> accepts <tt class=
449 "LITERAL">--with-user</tt> and <tt class=
450 "LITERAL">--with-group</tt> options for setting user and group
451 ownership of the configuration files (which need to be writable by
452 the daemon). The specified <span class="emphasis"><i class=
453 "EMPHASIS">user must already exist</i></span>. When starting <span
454 class="APPLICATION">Privoxy</span>, it must be run as this same
455 user to insure write access to configuration and log files!
458 Alternately, you can specify <tt class="LITERAL">user</tt> and <tt
459 class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
460 command line, but be sure both already exist:
464 <table border="0" bgcolor="#E0E0E0" width="100%">
468 make -s install USER=privoxy GROUP=privoxy
475 The default installation path for <b class="COMMAND">make
476 install</b> is <tt class="FILENAME">/usr/local</tt>. This may of
477 course be customized with the various <b class=
478 "COMMAND">./configure</b> path options. If you are doing an install
479 to anywhere besides <tt class="FILENAME">/usr/local</tt>, be sure
480 to set the appropriate paths with the correct configure options (<b
481 class="COMMAND">./configure --help</b>). Non-privileged users must
482 of course have write access permissions to wherever the target
483 installation is going.
486 If you do install to <tt class="FILENAME">/usr/local</tt>, the
487 install will use <tt class=
488 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
489 destinations, and the direct usage of <tt class=
490 "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not
491 add the extra <tt class="FILENAME">privoxy</tt> directory. This is
492 for a safer install, as there may already exist another program
493 that uses a file with the <span class="QUOTE">"config"</span> name,
494 and thus makes <tt class="FILENAME">/usr/local/etc</tt> cleaner.
497 If installing to <tt class="FILENAME">/usr/local</tt>, the
498 documentation will go by default to <tt class=
499 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't
500 exist, it will then try <tt class="FILENAME">$prefix/doc</tt> and
501 install there before creating a new <tt class=
502 "FILENAME">$prefix/share/doc</tt> just for <span class=
503 "APPLICATION">Privoxy</span>.
506 Again, if the installs goes to <tt class=
507 "FILENAME">/usr/local</tt>, the <tt class=
508 "LITERAL">localstatedir</tt> (ie: <tt class="FILENAME">var/</tt>)
509 will default to <tt class="FILENAME">/var</tt> instead of <tt
510 class="LITERAL">$prefix/var</tt> so the logs will go to <tt class=
511 "FILENAME">/var/log/privoxy/</tt>, and the pid file will be created
512 in <tt class="FILENAME">/var/run/privoxy.pid</tt>.
515 <b class="COMMAND">make install</b> will attempt to set the correct
516 values in <tt class="FILENAME">config</tt> (main configuration
517 file). You should check this to make sure all values are correct.
518 If appropriate, an init script will be installed, but it is up to
519 the user to determine how and where to start <span class=
520 "APPLICATION">Privoxy</span>. The init script should be checked for
521 correct paths and values, if anything other than a default install
525 If install finds previous versions of local configuration files,
526 most of these will not be overwritten, and the new ones will be
527 installed with a <span class="QUOTE">"new"</span> extension.
528 default.action and default.filter <span class="emphasis"><i class=
529 "EMPHASIS">will be overwritten</i></span>. You will then need to
530 manually update the other installed configuration files as needed.
531 The default template files <span class="emphasis"><i class=
532 "EMPHASIS">will</i></span> be overwritten. If you have customized,
533 local templates, these should be stored safely in a separate
534 directory and defined in <tt class="FILENAME">config</tt> by the
535 <span class="QUOTE">"templdir"</span> directive. It is of course
536 wise to always back-up any important configuration files <span
537 class="QUOTE">"just in case"</span>. If a previous version of <span
538 class="APPLICATION">Privoxy</span> is already running, you will
539 have to restart it manually.
542 For more detailed instructions on how to build Redhat RPMs, Windows
543 self-extracting installers, building on platforms with special
544 requirements etc, please consult the <a href=
545 "https://www.privoxy.org/developer-manual/newrelease.html" target=
546 "_top">developer manual</a>.
551 <a name="INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
555 If you wish to receive an email notification whenever we release
556 updates of <span class="APPLICATION">Privoxy</span> or the actions
558 "https://lists.privoxy.org/mailman/listinfo/privoxy-announce"
559 target="_top">subscribe to our announce mailing list</a>,
560 privoxy-announce@lists.privoxy.org.
563 In order not to lose your personal changes and adjustments when
564 updating to the latest <tt class="LITERAL">default.action</tt> file
565 we <span class="emphasis"><i class="EMPHASIS">strongly
566 recommend</i></span> that you use <tt class=
567 "LITERAL">user.action</tt> and <tt class="LITERAL">user.filter</tt>
568 for your local customizations of <span class=
569 "APPLICATION">Privoxy</span>. See the <a href=
570 "actions-file.html">Chapter on actions files</a> for details.
574 <div class="NAVFOOTER">
575 <hr align="LEFT" width="100%">
576 <table summary="Footer navigation table" width="100%" border="0"
577 cellpadding="0" cellspacing="0">
579 <td width="33%" align="left" valign="top">
580 <a href="introduction.html" accesskey="P">Prev</a>
582 <td width="34%" align="center" valign="top">
583 <a href="index.html" accesskey="H">Home</a>
585 <td width="33%" align="right" valign="top">
586 <a href="whatsnew.html" accesskey="N">Next</a>
590 <td width="33%" align="left" valign="top">
593 <td width="34%" align="center" valign="top">
596 <td width="33%" align="right" valign="top">
597 What's New in this Release