1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <title>Installation</title>
7 <meta name="GENERATOR" content=
8 "Modular DocBook HTML Stylesheet Version 1.79">
9 <link rel="HOME" title="Privoxy 3.0.20 User Manual" href="index.html">
10 <link rel="PREVIOUS" title="Introduction" href="introduction.html">
11 <link rel="NEXT" title="What's New in this Release" href="whatsnew.html">
12 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
13 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
14 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
15 <style type="text/css">
17 background-color: #EEEEEE;
20 :link { color: #0000FF }
21 :visited { color: #840084 }
22 :active { color: #0000FF }
23 table.c4 {background-color: #E0E0E0}
24 tt.c3 {font-style: italic}
25 span.c2 {font-style: italic}
26 hr.c1 {text-align: left}
31 <div class="NAVHEADER">
32 <table summary="Header navigation table" width="100%" border="0"
33 cellpadding="0" cellspacing="0">
35 <th colspan="3" align="center">Privoxy 3.0.20 User Manual</th>
39 <td width="10%" align="left" valign="bottom"><a href=
40 "introduction.html" accesskey="P">Prev</a></td>
42 <td width="80%" align="center" valign="bottom"></td>
44 <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
45 accesskey="N">Next</a></td>
48 <hr class="c1" width="100%">
52 <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
55 <p><span class="APPLICATION">Privoxy</span> is available both in
56 convenient pre-compiled packages for a wide range of operating systems,
57 and as raw source code. For most users, we recommend using the packages,
58 which can be downloaded from our <a href=
59 "http://sourceforge.net/projects/ijbswa/" target="_top">Privoxy Project
62 <p>Note: On some platforms, the installer may remove previously installed
63 versions, if found. (See below for your platform). In any case
64 <span class="emphasis EMPHASIS c2">be sure to backup your old
65 configuration if it is valuable to you.</span> See the <a href=
66 "whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section below.</p>
69 <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
70 "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
72 <p>How to install the binary packages depends on your operating
76 <h3 class="SECT3"><a name="INSTALLATION-PACK-RPM" id=
77 "INSTALLATION-PACK-RPM">2.1.1. Red Hat and Fedora RPMs</a></h3>
79 <p>RPMs can be installed with <tt class="LITERAL">rpm -Uvh
80 privoxy-3.0.20-1.rpm</tt>, and will use <tt class=
81 "FILENAME">/etc/privoxy</tt> for the location of configuration
84 <p>Note that on Red Hat, <span class="APPLICATION">Privoxy</span>
85 will <span class="emphasis EMPHASIS c2">not</span> be automatically
86 started on system boot. You will need to enable that using <b class=
87 "COMMAND">chkconfig</b>, <b class="COMMAND">ntsysv</b>, or similar
90 <p>If you have problems with failed dependencies, try rebuilding the
91 SRC RPM: <tt class="LITERAL">rpm --rebuild
92 privoxy-3.0.20-1.src.rpm</tt>. This will use your locally installed
93 libraries and RPM version.</p>
95 <p>Also note that if you have a <span class=
96 "APPLICATION">Junkbuster</span> RPM installed on your system, you
97 need to remove it first, because the packages conflict. Otherwise,
98 RPM will try to remove <span class="APPLICATION">Junkbuster</span>
99 automatically if found, before installing <span class=
100 "APPLICATION">Privoxy</span>.</p>
104 <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
105 "INSTALLATION-DEB">2.1.2. Debian and Ubuntu</a></h3>
107 <p>DEBs can be installed with <tt class="LITERAL">apt-get install
108 privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt> for
109 the location of configuration files.</p>
113 <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
114 "INSTALLATION-PACK-WIN">2.1.3. Windows</a></h3>
116 <p>Just double-click the installer, which will guide you through the
117 installation process. You will find the configuration files in the
118 same directory as you installed <span class=
119 "APPLICATION">Privoxy</span> in.</p>
121 <p>Version 3.0.5 beta introduced full <span class=
122 "APPLICATION">Windows</span> service functionality. On Windows only,
123 the <span class="APPLICATION">Privoxy</span> program has two new
124 command line arguments to install and uninstall <span class=
125 "APPLICATION">Privoxy</span> as a <span class=
126 "emphasis EMPHASIS c2">service</span>.</p>
128 <div class="VARIABLELIST">
133 <p><tt class="REPLACEABLE c3">--install</tt>[:<tt class=
134 "REPLACEABLE c3">service_name</tt>]</p>
136 <p><tt class="REPLACEABLE c3">--uninstall</tt>[:<tt class=
137 "REPLACEABLE c3">service_name</tt>]</p>
142 <p>After invoking <span class="APPLICATION">Privoxy</span> with
143 <b class="COMMAND">--install</b>, you will need to bring up the
144 <span class="APPLICATION">Windows</span> service console to assign
145 the user you want <span class="APPLICATION">Privoxy</span> to run
146 under, and whether or not you want it to run whenever the system
147 starts. You can start the <span class="APPLICATION">Windows</span>
148 services console with the following command: <b class=
149 "COMMAND">services.msc</b>. If you do not take the manual step of
150 modifying <span class="APPLICATION">Privoxy's</span> service
151 settings, it will not start. Note too that you will need to give
152 Privoxy a user account that actually exists, or it will not be
153 permitted to write to its log and configuration files.</p>
157 <h3 class="SECT3"><a name="INSTALLATION-PACK-BINTGZ" id=
158 "INSTALLATION-PACK-BINTGZ">2.1.4. Solaris</a></h3>
160 <p>Create a new directory, <tt class="LITERAL">cd</tt> to it, then
161 unzip and untar the archive. For the most part, you'll have to figure
162 out where things go.</p>
166 <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
167 "INSTALLATION-OS2">2.1.5. OS/2</a></h3>
169 <p>First, make sure that no previous installations of <span class=
170 "APPLICATION">Junkbuster</span> and / or <span class=
171 "APPLICATION">Privoxy</span> are left on your system. Check that no
172 <span class="APPLICATION">Junkbuster</span> or <span class=
173 "APPLICATION">Privoxy</span> objects are in your startup folder.</p>
175 <p>Then, just double-click the WarpIN self-installing archive, which
176 will guide you through the installation process. A shadow of the
177 <span class="APPLICATION">Privoxy</span> executable will be placed in
178 your startup folder so it will start automatically whenever OS/2
181 <p>The directory you choose to install <span class=
182 "APPLICATION">Privoxy</span> into will contain all of the
183 configuration files.</p>
187 <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
188 "INSTALLATION-MAC">2.1.6. Mac OS X</a></h3>
190 <p>Installation instructions for the OS X platform depend upon
191 whether you downloaded a ready-built installation package (.pkg or
192 .mpkg) or have downloaded the source code.</p>
196 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-PACKAGE" id=
197 "OS-X-INSTALL-FROM-PACKAGE">2.1.7. Installation from ready-built
200 <p>The downloaded file will either be a .pkg (for OS X 10.5 upwards)
201 or a bzipped .mpkg file (for OS X 10.4). The former can be
202 double-clicked as is and the installation will start; double-clicking
203 the latter will unzip the .mpkg file which can then be double-clicked
204 to commence the installation.</p>
206 <p>The privoxy service will automatically start after a successful
207 installation (and thereafter every time your computer starts up)
208 however you will need to configure your web browser(s) to use it. To
209 do so, configure them to use a proxy for HTTP and HTTPS at the
210 address 127.0.0.1:8118.</p>
212 <p>To prevent the privoxy service from automatically starting when
213 your computer starts up, remove or rename the file <tt class=
214 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
215 X 10.5 and higher) or the folder named <tt class=
216 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
219 <p>To manually start or stop the privoxy service, use the scripts
220 startPrivoxy.sh and stopPrivoxy.sh supplied in /Applications/Privoxy.
221 They must be run from an administrator account, using sudo.</p>
223 <p>To uninstall, run /Applications/Privoxy/uninstall.command as sudo
224 from an administrator account.</p>
228 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-SOURCE" id=
229 "OS-X-INSTALL-FROM-SOURCE">2.1.8. Installation from source</a></h4>
231 <p>To build and install the Privoxy source code on OS X you will need
232 to obtain the macsetup module from the Privoxy Sourceforge CVS
233 repository (refer to Sourceforge help for details of how to set up a
234 CVS client to have read-only access to the repository). This module
235 contains scripts that leverage the usual open-source tools (available
236 as part of Apple's free of charge Xcode distribution or via the usual
237 open-source software package managers for OS X (MacPorts, Homebrew,
238 Fink etc.) to build and then install the privoxy binary and
239 associated files. The macsetup module's README file contains complete
240 instructions for its use.</p>
242 <p>The privoxy service will automatically start after a successful
243 installation (and thereafter every time your computer starts up)
244 however you will need to configure your web browser(s) to use it. To
245 do so, configure them to use a proxy for HTTP and HTTPS at the
246 address 127.0.0.1:8118.</p>
248 <p>To prevent the privoxy service from automatically starting when
249 your computer starts up, remove or rename the file <tt class=
250 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
251 X 10.5 and higher) or the folder named <tt class=
252 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
255 <p>To manually start or stop the privoxy service, use the Privoxy
256 Utility for Mac OS X (also part of the macsetup module). This
257 application can start and stop the privoxy service and display its
258 log and configuration files.</p>
260 <p>To uninstall, run the macsetup module's uninstall.sh as sudo from
261 an administrator account.</p>
265 <h3 class="SECT3"><a name="INSTALLATION-AMIGA" id=
266 "INSTALLATION-AMIGA">2.1.9. AmigaOS</a></h3>
268 <p>Copy and then unpack the <tt class="FILENAME">lha</tt> archive to
269 a suitable location. All necessary files will be installed into
270 <span class="APPLICATION">Privoxy</span> directory, including all
271 configuration and log files. To uninstall, just remove this
276 <h3 class="SECT3"><a name="INSTALLATION-TBZ" id=
277 "INSTALLATION-TBZ">2.1.10. FreeBSD</a></h3>
279 <p>Privoxy is part of FreeBSD's Ports Collection, you can build and
280 install it with <tt class="LITERAL">cd /usr/ports/www/privoxy; make
281 install clean</tt>.</p>
283 <p>If you don't use the ports, you can fetch and install the package
284 with <tt class="LITERAL">pkg_add -r privoxy</tt>.</p>
286 <p>The port skeleton and the package can also be downloaded from the
288 "https://sourceforge.net/project/showfiles.php?group_id=11118"
289 target="_top">File Release Page</a>, but there's no reason to use
290 them unless you're interested in the beta releases which are only
295 <h3 class="SECT3"><a name="INSTALLATTION-GENTOO" id=
296 "INSTALLATTION-GENTOO">2.1.11. Gentoo</a></h3>
298 <p>Gentoo source packages (Ebuilds) for <span class=
299 "APPLICATION">Privoxy</span> are contained in the Gentoo Portage Tree
300 (they are not on the download page, but there is a Gentoo section,
301 where you can see when a new <span class="APPLICATION">Privoxy</span>
302 Version is added to the Portage Tree).</p>
304 <p>Before installing <span class="APPLICATION">Privoxy</span> under
305 Gentoo just do first <tt class="LITERAL">emerge --sync</tt> to get
306 the latest changes from the Portage tree. With <tt class=
307 "LITERAL">emerge privoxy</tt> you install the latest version.</p>
309 <p>Configuration files are in <tt class="FILENAME">/etc/privoxy</tt>,
310 the documentation is in <tt class=
311 "FILENAME">/usr/share/doc/privoxy-3.0.20</tt> and the Log directory
312 is in <tt class="FILENAME">/var/log/privoxy</tt>.</p>
317 <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
318 "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
320 <p>The most convenient way to obtain the <span class=
321 "APPLICATION">Privoxy</span> sources is to download the source tarball
323 "http://sourceforge.net/project/showfiles.php?group_id=11118&package_id=10571"
324 target="_top">project download page</a>.</p>
326 <p>If you like to live on the bleeding edge and are not afraid of using
327 possibly unstable development versions, you can check out the
328 up-to-the-minute version directly from <a href=
329 "http://sourceforge.net/cvs/?group_id=11118" target="_top">the CVS
332 <p>To build <span class="APPLICATION">Privoxy</span> from source,
333 <a href="http://www.gnu.org/software/autoconf/autoconf.html" target=
334 "_top">autoconf</a>, <a href=
335 "http://www.gnu.org/software/make/make.html" target="_top">GNU make
336 (gmake)</a>, and, of course, a C compiler like <a href=
337 "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are
340 <p>When building from a source tarball, first unpack the source:</p>
342 <table class="c4" border="0" width="100%">
346 tar xzvf privoxy-3.0.20-beta-src.tar.gz
347 cd privoxy-3.0.20-beta
353 <p>For retrieving the current CVS sources, you'll need a CVS client
354 installed. Note that sources from CVS are typically development
355 quality, and may not be stable, or well tested. To download CVS source,
356 check the Sourceforge documentation, which might give commands
359 <table class="c4" border="0" width="100%">
363 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
364 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
371 <p>This will create a directory named <tt class=
372 "FILENAME">current/</tt>, which will contain the source tree.</p>
374 <p>You can also check out any <span class="APPLICATION">Privoxy</span>
375 <span class="QUOTE">"branch"</span>, just exchange the <span class=
376 "APPLICATION">current</span> name with the wanted branch name (Example:
377 v_3_0_branch for the 3.0 cvs tree).</p>
379 <p>It is also strongly recommended to not run <span class=
380 "APPLICATION">Privoxy</span> as root. You should configure/install/run
381 <span class="APPLICATION">Privoxy</span> as an unprivileged user,
382 preferably by creating a <span class="QUOTE">"privoxy"</span> user and
383 group just for this purpose. See your local documentation for the
384 correct command line to do add new users and groups (something like
385 <b class="COMMAND">adduser</b>, but the command syntax may vary from
386 platform to platform).</p>
388 <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
390 <table class="c4" border="0" width="100%">
394 privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
400 <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
402 <table class="c4" border="0" width="100%">
412 <p>Some binary packages may do this for you.</p>
414 <p>Then, to build from either unpacked tarball or CVS source:</p>
416 <table class="c4" border="0" width="100%">
422 ./configure # (--help to see options)
423 make # (the make from GNU, sometimes called gmake)
424 su # Possibly required
425 make -n install # (to see where all the files will go)
426 make -s install # (to really install, -s to silence output)
432 <p>Using GNU <b class="COMMAND">make</b>, you can have the first four
433 steps automatically done for you by just typing:</p>
435 <table class="c4" border="0" width="100%">
445 <p>in the freshly downloaded or unpacked source directory.</p>
447 <p>To build an executable with security enhanced features so that users
448 cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go There
449 Anyway"</span>), or alter their own configurations, <b class=
450 "COMMAND">configure</b> like this:</p>
452 <table class="c4" border="0" width="100%">
456 ./configure --disable-toggle --disable-editor --disable-force
462 <p>Then build as above. In Privoxy 3.0.7 and later, all of these
463 options can also be disabled through the configuration file.</p>
465 <p><span class="emphasis EMPHASIS c2">WARNING:</span> If installing as
466 root, the install will fail unless a non-root user or group is
467 specified, or a <tt class="LITERAL">privoxy</tt> user and group already
468 exist on the system. If a non-root user is specified, and no group,
469 then the installation will try to also use a group of the same name as
470 <span class="QUOTE">"user"</span>. If a group is specified (and no
471 user), then the support files will be installed as writable by that
472 group, and owned by the user running the installation.</p>
474 <p><b class="COMMAND">configure</b> accepts <tt class=
475 "LITERAL">--with-user</tt> and <tt class="LITERAL">--with-group</tt>
476 options for setting user and group ownership of the configuration files
477 (which need to be writable by the daemon). The specified <span class=
478 "emphasis EMPHASIS c2">user must already exist</span>. When starting
479 <span class="APPLICATION">Privoxy</span>, it must be run as this same
480 user to insure write access to configuration and log files!</p>
482 <p>Alternately, you can specify <tt class="LITERAL">user</tt> and
483 <tt class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
484 command line, but be sure both already exist:</p>
486 <table class="c4" border="0" width="100%">
490 make -s install USER=privoxy GROUP=privoxy
496 <p>The default installation path for <b class="COMMAND">make
497 install</b> is <tt class="FILENAME">/usr/local</tt>. This may of course
498 be customized with the various <b class="COMMAND">./configure</b> path
499 options. If you are doing an install to anywhere besides <tt class=
500 "FILENAME">/usr/local</tt>, be sure to set the appropriate paths with
501 the correct configure options (<b class="COMMAND">./configure
502 --help</b>). Non-privileged users must of course have write access
503 permissions to wherever the target installation is going.</p>
505 <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the
506 install will use <tt class=
507 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
508 destinations, and the direct usage of <tt class=
509 "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add
510 the extra <tt class="FILENAME">privoxy</tt> directory. This is for a
511 safer install, as there may already exist another program that uses a
512 file with the <span class="QUOTE">"config"</span> name, and thus makes
513 <tt class="FILENAME">/usr/local/etc</tt> cleaner.</p>
515 <p>If installing to <tt class="FILENAME">/usr/local</tt>, the
516 documentation will go by default to <tt class=
517 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist,
518 it will then try <tt class="FILENAME">$prefix/doc</tt> and install
519 there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
520 just for <span class="APPLICATION">Privoxy</span>.</p>
522 <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>,
523 the <tt class="LITERAL">localstatedir</tt> (ie: <tt class=
524 "FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
525 instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to
526 <tt class="FILENAME">/var/log/privoxy/</tt>, and the pid file will be
527 created in <tt class="FILENAME">/var/run/privoxy.pid</tt>.</p>
529 <p><b class="COMMAND">make install</b> will attempt to set the correct
530 values in <tt class="FILENAME">config</tt> (main configuration file).
531 You should check this to make sure all values are correct. If
532 appropriate, an init script will be installed, but it is up to the user
533 to determine how and where to start <span class=
534 "APPLICATION">Privoxy</span>. The init script should be checked for
535 correct paths and values, if anything other than a default install is
538 <p>If install finds previous versions of local configuration files,
539 most of these will not be overwritten, and the new ones will be
540 installed with a <span class="QUOTE">"new"</span> extension.
541 default.action and default.filter <span class=
542 "emphasis EMPHASIS c2">will be overwritten</span>. You will then need
543 to manually update the other installed configuration files as needed.
544 The default template files <span class=
545 "emphasis EMPHASIS c2">will</span> be overwritten. If you have
546 customized, local templates, these should be stored safely in a
547 separate directory and defined in <tt class="FILENAME">config</tt> by
548 the <span class="QUOTE">"templdir"</span> directive. It is of course
549 wise to always back-up any important configuration files <span class=
550 "QUOTE">"just in case"</span>. If a previous version of <span class=
551 "APPLICATION">Privoxy</span> is already running, you will have to
552 restart it manually.</p>
554 <p>For more detailed instructions on how to build Redhat RPMs, Windows
555 self-extracting installers, building on platforms with special
556 requirements etc, please consult the <a href=
557 "http://www.privoxy.org/developer-manual/newrelease.html" target=
558 "_top">developer manual</a>.</p>
562 <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
563 "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
566 <p>As user feedback comes in and development continues, we will make
567 updated versions of both the main <a href="actions-file.html">actions
568 file</a> (as a <a href=
569 "http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670"
570 target="_top">separate package</a>) and the software itself (including
571 the actions file) available for download.</p>
573 <p>If you wish to receive an email notification whenever we release
574 updates of <span class="APPLICATION">Privoxy</span> or the actions
576 "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/" target=
577 "_top">subscribe to our announce mailing list</a>,
578 ijbswa-announce@lists.sourceforge.net.</p>
580 <p>In order not to lose your personal changes and adjustments when
581 updating to the latest <tt class="LITERAL">default.action</tt> file we
582 <span class="emphasis EMPHASIS c2">strongly recommend</span> that you
583 use <tt class="LITERAL">user.action</tt> and <tt class=
584 "LITERAL">user.filter</tt> for your local customizations of
585 <span class="APPLICATION">Privoxy</span>. See the <a href=
586 "actions-file.html">Chapter on actions files</a> for details.</p>
590 <div class="NAVFOOTER">
591 <hr class="c1" width="100%">
593 <table summary="Footer navigation table" width="100%" border="0"
594 cellpadding="0" cellspacing="0">
596 <td width="33%" align="left" valign="top"><a href="introduction.html"
597 accesskey="P">Prev</a></td>
599 <td width="34%" align="center" valign="top"><a href="index.html"
600 accesskey="H">Home</a></td>
602 <td width="33%" align="right" valign="top"><a href="whatsnew.html"
603 accesskey="N">Next</a></td>
607 <td width="33%" align="left" valign="top">Introduction</td>
609 <td width="34%" align="center" valign="top"> </td>
611 <td width="33%" align="right" valign="top">What's New in this