1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <meta name="generator" content=
7 "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
9 <title>Installation</title>
10 <meta name="GENERATOR" content=
11 "Modular DocBook HTML Stylesheet Version 1.79">
12 <link rel="HOME" title="Privoxy 3.0.19 User Manual" href="index.html">
13 <link rel="PREVIOUS" title="Introduction" href="introduction.html">
14 <link rel="NEXT" title="What's New in this Release" href="whatsnew.html">
15 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
16 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
17 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
18 <style type="text/css">
20 background-color: #EEEEEE;
23 :link { color: #0000FF }
24 :visited { color: #840084 }
25 :active { color: #0000FF }
26 table.c4 {background-color: #E0E0E0}
27 tt.c3 {font-style: italic}
28 span.c2 {font-style: italic}
29 hr.c1 {text-align: left}
34 <div class="NAVHEADER">
35 <table summary="Header navigation table" width="100%" border="0"
36 cellpadding="0" cellspacing="0">
38 <th colspan="3" align="center">Privoxy 3.0.19 User Manual</th>
42 <td width="10%" align="left" valign="bottom"><a href=
43 "introduction.html" accesskey="P">Prev</a></td>
45 <td width="80%" align="center" valign="bottom"></td>
47 <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
48 accesskey="N">Next</a></td>
51 <hr class="c1" width="100%">
55 <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
58 <p><span class="APPLICATION">Privoxy</span> is available both in
59 convenient pre-compiled packages for a wide range of operating systems,
60 and as raw source code. For most users, we recommend using the packages,
61 which can be downloaded from our <a href=
62 "http://sourceforge.net/projects/ijbswa/" target="_top">Privoxy Project
65 <p>Note: On some platforms, the installer may remove previously installed
66 versions, if found. (See below for your platform). In any case
67 <span class="emphasis EMPHASIS c2">be sure to backup your old
68 configuration if it is valuable to you.</span> See the <a href=
69 "whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section below.</p>
72 <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
73 "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
75 <p>How to install the binary packages depends on your operating
79 <h3 class="SECT3"><a name="INSTALLATION-PACK-RPM" id=
80 "INSTALLATION-PACK-RPM">2.1.1. Red Hat and Fedora RPMs</a></h3>
82 <p>RPMs can be installed with <tt class="LITERAL">rpm -Uvh
83 privoxy-3.0.19-1.rpm</tt>, and will use <tt class=
84 "FILENAME">/etc/privoxy</tt> for the location of configuration
87 <p>Note that on Red Hat, <span class="APPLICATION">Privoxy</span>
88 will <span class="emphasis EMPHASIS c2">not</span> be automatically
89 started on system boot. You will need to enable that using <b class=
90 "COMMAND">chkconfig</b>, <b class="COMMAND">ntsysv</b>, or similar
93 <p>If you have problems with failed dependencies, try rebuilding the
94 SRC RPM: <tt class="LITERAL">rpm --rebuild
95 privoxy-3.0.19-1.src.rpm</tt>. This will use your locally installed
96 libraries and RPM version.</p>
98 <p>Also note that if you have a <span class=
99 "APPLICATION">Junkbuster</span> RPM installed on your system, you
100 need to remove it first, because the packages conflict. Otherwise,
101 RPM will try to remove <span class="APPLICATION">Junkbuster</span>
102 automatically if found, before installing <span class=
103 "APPLICATION">Privoxy</span>.</p>
107 <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
108 "INSTALLATION-DEB">2.1.2. Debian and Ubuntu</a></h3>
110 <p>DEBs can be installed with <tt class="LITERAL">apt-get install
111 privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt> for
112 the location of configuration files.</p>
116 <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
117 "INSTALLATION-PACK-WIN">2.1.3. Windows</a></h3>
119 <p>Just double-click the installer, which will guide you through the
120 installation process. You will find the configuration files in the
121 same directory as you installed <span class=
122 "APPLICATION">Privoxy</span> in.</p>
124 <p>Version 3.0.5 beta introduced full <span class=
125 "APPLICATION">Windows</span> service functionality. On Windows only,
126 the <span class="APPLICATION">Privoxy</span> program has two new
127 command line arguments to install and uninstall <span class=
128 "APPLICATION">Privoxy</span> as a <span class=
129 "emphasis EMPHASIS c2">service</span>.</p>
131 <div class="VARIABLELIST">
136 <p><tt class="REPLACEABLE c3">--install</tt>[:<tt class=
137 "REPLACEABLE c3">service_name</tt>]</p>
139 <p><tt class="REPLACEABLE c3">--uninstall</tt>[:<tt class=
140 "REPLACEABLE c3">service_name</tt>]</p>
145 <p>After invoking <span class="APPLICATION">Privoxy</span> with
146 <b class="COMMAND">--install</b>, you will need to bring up the
147 <span class="APPLICATION">Windows</span> service console to assign
148 the user you want <span class="APPLICATION">Privoxy</span> to run
149 under, and whether or not you want it to run whenever the system
150 starts. You can start the <span class="APPLICATION">Windows</span>
151 services console with the following command: <b class=
152 "COMMAND">services.msc</b>. If you do not take the manual step of
153 modifying <span class="APPLICATION">Privoxy's</span> service
154 settings, it will not start. Note too that you will need to give
155 Privoxy a user account that actually exists, or it will not be
156 permitted to write to its log and configuration files.</p>
160 <h3 class="SECT3"><a name="INSTALLATION-PACK-BINTGZ" id=
161 "INSTALLATION-PACK-BINTGZ">2.1.4. Solaris</a></h3>
163 <p>Create a new directory, <tt class="LITERAL">cd</tt> to it, then
164 unzip and untar the archive. For the most part, you'll have to figure
165 out where things go.</p>
169 <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
170 "INSTALLATION-OS2">2.1.5. OS/2</a></h3>
172 <p>First, make sure that no previous installations of <span class=
173 "APPLICATION">Junkbuster</span> and / or <span class=
174 "APPLICATION">Privoxy</span> are left on your system. Check that no
175 <span class="APPLICATION">Junkbuster</span> or <span class=
176 "APPLICATION">Privoxy</span> objects are in your startup folder.</p>
178 <p>Then, just double-click the WarpIN self-installing archive, which
179 will guide you through the installation process. A shadow of the
180 <span class="APPLICATION">Privoxy</span> executable will be placed in
181 your startup folder so it will start automatically whenever OS/2
184 <p>The directory you choose to install <span class=
185 "APPLICATION">Privoxy</span> into will contain all of the
186 configuration files.</p>
190 <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
191 "INSTALLATION-MAC">2.1.6. Mac OS X</a></h3>
193 <p>Unzip the downloaded file (you can either double-click on the zip
194 file icon from the Finder, or from the desktop if you downloaded it
195 there). Then, double-click on the package installer icon and follow
196 the installation process.</p>
198 <p>The privoxy service will automatically start after a successful
199 installation (in addition to every time your computer starts up). To
200 prevent the privoxy service from automatically starting when your
201 computer starts up, remove or rename the folder named <tt class=
202 "LITERAL">/Library/StartupItems/Privoxy</tt>.</p>
204 <p>To manually start or stop the privoxy service, use the Privoxy
205 Utility for Mac OS X. This application controls the privoxy service
206 (e.g. starting and stopping the service as well as uninstalling the
211 <h3 class="SECT3"><a name="INSTALLATION-AMIGA" id=
212 "INSTALLATION-AMIGA">2.1.7. AmigaOS</a></h3>
214 <p>Copy and then unpack the <tt class="FILENAME">lha</tt> archive to
215 a suitable location. All necessary files will be installed into
216 <span class="APPLICATION">Privoxy</span> directory, including all
217 configuration and log files. To uninstall, just remove this
222 <h3 class="SECT3"><a name="INSTALLATION-TBZ" id=
223 "INSTALLATION-TBZ">2.1.8. FreeBSD</a></h3>
225 <p>Privoxy is part of FreeBSD's Ports Collection, you can build and
226 install it with <tt class="LITERAL">cd /usr/ports/www/privoxy; make
227 install clean</tt>.</p>
229 <p>If you don't use the ports, you can fetch and install the package
230 with <tt class="LITERAL">pkg_add -r privoxy</tt>.</p>
232 <p>The port skeleton and the package can also be downloaded from the
234 "https://sourceforge.net/project/showfiles.php?group_id=11118"
235 target="_top">File Release Page</a>, but there's no reason to use
236 them unless you're interested in the beta releases which are only
241 <h3 class="SECT3"><a name="INSTALLATTION-GENTOO" id=
242 "INSTALLATTION-GENTOO">2.1.9. Gentoo</a></h3>
244 <p>Gentoo source packages (Ebuilds) for <span class=
245 "APPLICATION">Privoxy</span> are contained in the Gentoo Portage Tree
246 (they are not on the download page, but there is a Gentoo section,
247 where you can see when a new <span class="APPLICATION">Privoxy</span>
248 Version is added to the Portage Tree).</p>
250 <p>Before installing <span class="APPLICATION">Privoxy</span> under
251 Gentoo just do first <tt class="LITERAL">emerge --sync</tt> to get
252 the latest changes from the Portage tree. With <tt class=
253 "LITERAL">emerge privoxy</tt> you install the latest version.</p>
255 <p>Configuration files are in <tt class="FILENAME">/etc/privoxy</tt>,
256 the documentation is in <tt class=
257 "FILENAME">/usr/share/doc/privoxy-3.0.19</tt> and the Log directory
258 is in <tt class="FILENAME">/var/log/privoxy</tt>.</p>
263 <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
264 "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
266 <p>The most convenient way to obtain the <span class=
267 "APPLICATION">Privoxy</span> sources is to download the source tarball
269 "http://sourceforge.net/project/showfiles.php?group_id=11118&package_id=10571"
270 target="_top">project download page</a>.</p>
272 <p>If you like to live on the bleeding edge and are not afraid of using
273 possibly unstable development versions, you can check out the
274 up-to-the-minute version directly from <a href=
275 "http://sourceforge.net/cvs/?group_id=11118" target="_top">the CVS
278 <p>To build <span class="APPLICATION">Privoxy</span> from source,
279 <a href="http://www.gnu.org/software/autoconf/autoconf.html" target=
280 "_top">autoconf</a>, <a href=
281 "http://www.gnu.org/software/make/make.html" target="_top">GNU make
282 (gmake)</a>, and, of course, a C compiler like <a href=
283 "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are
286 <p>When building from a source tarball, first unpack the source:</p>
288 <table class="c4" border="0" width="100%">
292 tar xzvf privoxy-3.0.19-stable-src.tar.gz
293 cd privoxy-3.0.19-stable
299 <p>For retrieving the current CVS sources, you'll need a CVS client
300 installed. Note that sources from CVS are typically development
301 quality, and may not be stable, or well tested. To download CVS source,
302 check the Sourceforge documentation, which might give commands
305 <table class="c4" border="0" width="100%">
309 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
310 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
317 <p>This will create a directory named <tt class=
318 "FILENAME">current/</tt>, which will contain the source tree.</p>
320 <p>You can also check out any <span class="APPLICATION">Privoxy</span>
321 <span class="QUOTE">"branch"</span>, just exchange the <span class=
322 "APPLICATION">current</span> name with the wanted branch name (Example:
323 v_3_0_branch for the 3.0 cvs tree).</p>
325 <p>It is also strongly recommended to not run <span class=
326 "APPLICATION">Privoxy</span> as root. You should configure/install/run
327 <span class="APPLICATION">Privoxy</span> as an unprivileged user,
328 preferably by creating a <span class="QUOTE">"privoxy"</span> user and
329 group just for this purpose. See your local documentation for the
330 correct command line to do add new users and groups (something like
331 <b class="COMMAND">adduser</b>, but the command syntax may vary from
332 platform to platform).</p>
334 <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
336 <table class="c4" border="0" width="100%">
340 privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
346 <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
348 <table class="c4" border="0" width="100%">
358 <p>Some binary packages may do this for you.</p>
360 <p>Then, to build from either unpacked tarball or CVS source:</p>
362 <table class="c4" border="0" width="100%">
368 ./configure # (--help to see options)
369 make # (the make from GNU, sometimes called gmake)
370 su # Possibly required
371 make -n install # (to see where all the files will go)
372 make -s install # (to really install, -s to silence output)
378 <p>Using GNU <b class="COMMAND">make</b>, you can have the first four
379 steps automatically done for you by just typing:</p>
381 <table class="c4" border="0" width="100%">
391 <p>in the freshly downloaded or unpacked source directory.</p>
393 <p>To build an executable with security enhanced features so that users
394 cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go There
395 Anyway"</span>), or alter their own configurations, <b class=
396 "COMMAND">configure</b> like this:</p>
398 <table class="c4" border="0" width="100%">
402 ./configure --disable-toggle --disable-editor --disable-force
408 <p>Then build as above. In Privoxy 3.0.7 and later, all of these
409 options can also be disabled through the configuration file.</p>
411 <p><span class="emphasis EMPHASIS c2">WARNING:</span> If installing as
412 root, the install will fail unless a non-root user or group is
413 specified, or a <tt class="LITERAL">privoxy</tt> user and group already
414 exist on the system. If a non-root user is specified, and no group,
415 then the installation will try to also use a group of the same name as
416 <span class="QUOTE">"user"</span>. If a group is specified (and no
417 user), then the support files will be installed as writable by that
418 group, and owned by the user running the installation.</p>
420 <p><b class="COMMAND">configure</b> accepts <tt class=
421 "LITERAL">--with-user</tt> and <tt class="LITERAL">--with-group</tt>
422 options for setting user and group ownership of the configuration files
423 (which need to be writable by the daemon). The specified <span class=
424 "emphasis EMPHASIS c2">user must already exist</span>. When starting
425 <span class="APPLICATION">Privoxy</span>, it must be run as this same
426 user to insure write access to configuration and log files!</p>
428 <p>Alternately, you can specify <tt class="LITERAL">user</tt> and
429 <tt class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
430 command line, but be sure both already exist:</p>
432 <table class="c4" border="0" width="100%">
436 make -s install USER=privoxy GROUP=privoxy
442 <p>The default installation path for <b class="COMMAND">make
443 install</b> is <tt class="FILENAME">/usr/local</tt>. This may of course
444 be customized with the various <b class="COMMAND">./configure</b> path
445 options. If you are doing an install to anywhere besides <tt class=
446 "FILENAME">/usr/local</tt>, be sure to set the appropriate paths with
447 the correct configure options (<b class="COMMAND">./configure
448 --help</b>). Non-privileged users must of course have write access
449 permissions to wherever the target installation is going.</p>
451 <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the
452 install will use <tt class=
453 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
454 destinations, and the direct usage of <tt class=
455 "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add
456 the extra <tt class="FILENAME">privoxy</tt> directory. This is for a
457 safer install, as there may already exist another program that uses a
458 file with the <span class="QUOTE">"config"</span> name, and thus makes
459 <tt class="FILENAME">/usr/local/etc</tt> cleaner.</p>
461 <p>If installing to <tt class="FILENAME">/usr/local</tt>, the
462 documentation will go by default to <tt class=
463 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist,
464 it will then try <tt class="FILENAME">$prefix/doc</tt> and install
465 there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
466 just for <span class="APPLICATION">Privoxy</span>.</p>
468 <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>,
469 the <tt class="LITERAL">localstatedir</tt> (ie: <tt class=
470 "FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
471 instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to
472 <tt class="FILENAME">/var/log/privoxy/</tt>, and the pid file will be
473 created in <tt class="FILENAME">/var/run/privoxy.pid</tt>.</p>
475 <p><b class="COMMAND">make install</b> will attempt to set the correct
476 values in <tt class="FILENAME">config</tt> (main configuration file).
477 You should check this to make sure all values are correct. If
478 appropriate, an init script will be installed, but it is up to the user
479 to determine how and where to start <span class=
480 "APPLICATION">Privoxy</span>. The init script should be checked for
481 correct paths and values, if anything other than a default install is
484 <p>If install finds previous versions of local configuration files,
485 most of these will not be overwritten, and the new ones will be
486 installed with a <span class="QUOTE">"new"</span> extension.
487 default.action and default.filter <span class=
488 "emphasis EMPHASIS c2">will be overwritten</span>. You will then need
489 to manually update the other installed configuration files as needed.
490 The default template files <span class=
491 "emphasis EMPHASIS c2">will</span> be overwritten. If you have
492 customized, local templates, these should be stored safely in a
493 separate directory and defined in <tt class="FILENAME">config</tt> by
494 the <span class="QUOTE">"templdir"</span> directive. It is of course
495 wise to always back-up any important configuration files <span class=
496 "QUOTE">"just in case"</span>. If a previous version of <span class=
497 "APPLICATION">Privoxy</span> is already running, you will have to
498 restart it manually.</p>
500 <p>For more detailed instructions on how to build Redhat RPMs, Windows
501 self-extracting installers, building on platforms with special
502 requirements etc, please consult the <a href=
503 "http://www.privoxy.org/developer-manual/newrelease.html" target=
504 "_top">developer manual</a>.</p>
508 <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
509 "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
512 <p>As user feedback comes in and development continues, we will make
513 updated versions of both the main <a href="actions-file.html">actions
514 file</a> (as a <a href=
515 "http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670"
516 target="_top">separate package</a>) and the software itself (including
517 the actions file) available for download.</p>
519 <p>If you wish to receive an email notification whenever we release
520 updates of <span class="APPLICATION">Privoxy</span> or the actions
522 "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/" target=
523 "_top">subscribe to our announce mailing list</a>,
524 ijbswa-announce@lists.sourceforge.net.</p>
526 <p>In order not to lose your personal changes and adjustments when
527 updating to the latest <tt class="LITERAL">default.action</tt> file we
528 <span class="emphasis EMPHASIS c2">strongly recommend</span> that you
529 use <tt class="LITERAL">user.action</tt> and <tt class=
530 "LITERAL">user.filter</tt> for your local customizations of
531 <span class="APPLICATION">Privoxy</span>. See the <a href=
532 "actions-file.html">Chapter on actions files</a> for details.</p>
536 <div class="NAVFOOTER">
537 <hr class="c1" width="100%">
539 <table summary="Footer navigation table" width="100%" border="0"
540 cellpadding="0" cellspacing="0">
542 <td width="33%" align="left" valign="top"><a href="introduction.html"
543 accesskey="P">Prev</a></td>
545 <td width="34%" align="center" valign="top"><a href="index.html"
546 accesskey="H">Home</a></td>
548 <td width="33%" align="right" valign="top"><a href="whatsnew.html"
549 accesskey="N">Next</a></td>
553 <td width="33%" align="left" valign="top">Introduction</td>
555 <td width="34%" align="center" valign="top"> </td>
557 <td width="33%" align="right" valign="top">What's New in this