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">
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">Privoxy 3.0.20 User Manual</th>
27 <td width="10%" align="left" valign="bottom"><a href=
28 "introduction.html" accesskey="P">Prev</a></td>
30 <td width="80%" align="center" valign="bottom"></td>
32 <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
33 accesskey="N">Next</a></td>
36 <hr align="left" width="100%">
40 <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
43 <p><span class="APPLICATION">Privoxy</span> is available both in
44 convenient pre-compiled packages for a wide range of operating systems,
45 and as raw source code. For most users, we recommend using the packages,
46 which can be downloaded from our <a href=
47 "http://sourceforge.net/projects/ijbswa/" target="_top">Privoxy Project
50 <p>Note: On some platforms, the installer may remove previously installed
51 versions, if found. (See below for your platform). In any case
52 <span class="emphasis"><i class="EMPHASIS">be sure to backup your old
53 configuration if it is valuable to you.</i></span> See the <a href=
54 "whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section below.</p>
57 <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
58 "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
60 <p>How to install the binary packages depends on your operating
64 <h3 class="SECT3"><a name="INSTALLATION-PACK-RPM" id=
65 "INSTALLATION-PACK-RPM">2.1.1. Red Hat and Fedora RPMs</a></h3>
67 <p>RPMs can be installed with <tt class="LITERAL">rpm -Uvh
68 privoxy-3.0.20-1.rpm</tt>, and will use <tt class=
69 "FILENAME">/etc/privoxy</tt> for the location of configuration
72 <p>Note that on Red Hat, <span class="APPLICATION">Privoxy</span>
73 will <span class="emphasis"><i class="EMPHASIS">not</i></span> be
74 automatically started on system boot. You will need to enable that
75 using <b class="COMMAND">chkconfig</b>, <b class=
76 "COMMAND">ntsysv</b>, or similar methods.</p>
78 <p>If you have problems with failed dependencies, try rebuilding the
79 SRC RPM: <tt class="LITERAL">rpm --rebuild
80 privoxy-3.0.20-1.src.rpm</tt>. This will use your locally installed
81 libraries and RPM version.</p>
83 <p>Also note that if you have a <span class=
84 "APPLICATION">Junkbuster</span> RPM installed on your system, you
85 need to remove it first, because the packages conflict. Otherwise,
86 RPM will try to remove <span class="APPLICATION">Junkbuster</span>
87 automatically if found, before installing <span class=
88 "APPLICATION">Privoxy</span>.</p>
92 <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
93 "INSTALLATION-DEB">2.1.2. Debian and Ubuntu</a></h3>
95 <p>DEBs can be installed with <tt class="LITERAL">apt-get install
96 privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt> for
97 the location of configuration files.</p>
101 <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
102 "INSTALLATION-PACK-WIN">2.1.3. Windows</a></h3>
104 <p>Just double-click the installer, which will guide you through the
105 installation process. You will find the configuration files in the
106 same directory as you installed <span class=
107 "APPLICATION">Privoxy</span> in.</p>
109 <p>Version 3.0.5 beta introduced full <span class=
110 "APPLICATION">Windows</span> service functionality. On Windows only,
111 the <span class="APPLICATION">Privoxy</span> program has two new
112 command line arguments to install and uninstall <span class=
113 "APPLICATION">Privoxy</span> as a <span class="emphasis"><i class=
114 "EMPHASIS">service</i></span>.</p>
116 <div class="VARIABLELIST">
121 <p><tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class=
122 "REPLACEABLE"><i>service_name</i></tt>]</p>
124 <p><tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class=
125 "REPLACEABLE"><i>service_name</i></tt>]</p>
130 <p>After invoking <span class="APPLICATION">Privoxy</span> with
131 <b class="COMMAND">--install</b>, you will need to bring up the
132 <span class="APPLICATION">Windows</span> service console to assign
133 the user you want <span class="APPLICATION">Privoxy</span> to run
134 under, and whether or not you want it to run whenever the system
135 starts. You can start the <span class="APPLICATION">Windows</span>
136 services console with the following command: <b class=
137 "COMMAND">services.msc</b>. If you do not take the manual step of
138 modifying <span class="APPLICATION">Privoxy's</span> service
139 settings, it will not start. Note too that you will need to give
140 Privoxy a user account that actually exists, or it will not be
141 permitted to write to its log and configuration files.</p>
145 <h3 class="SECT3"><a name="INSTALLATION-PACK-BINTGZ" id=
146 "INSTALLATION-PACK-BINTGZ">2.1.4. Solaris</a></h3>
148 <p>Create a new directory, <tt class="LITERAL">cd</tt> to it, then
149 unzip and untar the archive. For the most part, you'll have to figure
150 out where things go.</p>
154 <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
155 "INSTALLATION-OS2">2.1.5. OS/2</a></h3>
157 <p>First, make sure that no previous installations of <span class=
158 "APPLICATION">Junkbuster</span> and / or <span class=
159 "APPLICATION">Privoxy</span> are left on your system. Check that no
160 <span class="APPLICATION">Junkbuster</span> or <span class=
161 "APPLICATION">Privoxy</span> objects are in your startup folder.</p>
163 <p>Then, just double-click the WarpIN self-installing archive, which
164 will guide you through the installation process. A shadow of the
165 <span class="APPLICATION">Privoxy</span> executable will be placed in
166 your startup folder so it will start automatically whenever OS/2
169 <p>The directory you choose to install <span class=
170 "APPLICATION">Privoxy</span> into will contain all of the
171 configuration files.</p>
175 <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
176 "INSTALLATION-MAC">2.1.6. Mac OS X</a></h3>
178 <p>Installation instructions for the OS X platform depend upon
179 whether you downloaded a ready-built installation package (.pkg or
180 .mpkg) or have downloaded the source code.</p>
184 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-PACKAGE" id=
185 "OS-X-INSTALL-FROM-PACKAGE">2.1.7. Installation from ready-built
188 <p>The downloaded file will either be a .pkg (for OS X 10.5 upwards)
189 or a bzipped .mpkg file (for OS X 10.4). The former can be
190 double-clicked as is and the installation will start; double-clicking
191 the latter will unzip the .mpkg file which can then be double-clicked
192 to commence the installation.</p>
194 <p>The privoxy service will automatically start after a successful
195 installation (and thereafter every time your computer starts up)
196 however you will need to configure your web browser(s) to use it. To
197 do so, configure them to use a proxy for HTTP and HTTPS at the
198 address 127.0.0.1:8118.</p>
200 <p>To prevent the privoxy service from automatically starting when
201 your computer starts up, remove or rename the file <tt class=
202 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
203 X 10.5 and higher) or the folder named <tt class=
204 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
207 <p>To manually start or stop the privoxy service, use the scripts
208 startPrivoxy.sh and stopPrivoxy.sh supplied in /Applications/Privoxy.
209 They must be run from an administrator account, using sudo.</p>
211 <p>To uninstall, run /Applications/Privoxy/uninstall.command as sudo
212 from an administrator account.</p>
216 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-SOURCE" id=
217 "OS-X-INSTALL-FROM-SOURCE">2.1.8. Installation from source</a></h4>
219 <p>To build and install the Privoxy source code on OS X you will need
220 to obtain the macsetup module from the Privoxy Sourceforge CVS
221 repository (refer to Sourceforge help for details of how to set up a
222 CVS client to have read-only access to the repository). This module
223 contains scripts that leverage the usual open-source tools (available
224 as part of Apple's free of charge Xcode distribution or via the usual
225 open-source software package managers for OS X (MacPorts, Homebrew,
226 Fink etc.) to build and then install the privoxy binary and
227 associated files. The macsetup module's README file contains complete
228 instructions for its use.</p>
230 <p>The privoxy service will automatically start after a successful
231 installation (and thereafter every time your computer starts up)
232 however you will need to configure your web browser(s) to use it. To
233 do so, configure them to use a proxy for HTTP and HTTPS at the
234 address 127.0.0.1:8118.</p>
236 <p>To prevent the privoxy service from automatically starting when
237 your computer starts up, remove or rename the file <tt class=
238 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
239 X 10.5 and higher) or the folder named <tt class=
240 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
243 <p>To manually start or stop the privoxy service, use the Privoxy
244 Utility for Mac OS X (also part of the macsetup module). This
245 application can start and stop the privoxy service and display its
246 log and configuration files.</p>
248 <p>To uninstall, run the macsetup module's uninstall.sh as sudo from
249 an administrator account.</p>
253 <h3 class="SECT3"><a name="INSTALLATION-AMIGA" id=
254 "INSTALLATION-AMIGA">2.1.9. AmigaOS</a></h3>
256 <p>Copy and then unpack the <tt class="FILENAME">lha</tt> archive to
257 a suitable location. All necessary files will be installed into
258 <span class="APPLICATION">Privoxy</span> directory, including all
259 configuration and log files. To uninstall, just remove this
264 <h3 class="SECT3"><a name="INSTALLATION-TBZ" id=
265 "INSTALLATION-TBZ">2.1.10. FreeBSD</a></h3>
267 <p>Privoxy is part of FreeBSD's Ports Collection, you can build and
268 install it with <tt class="LITERAL">cd /usr/ports/www/privoxy; make
269 install clean</tt>.</p>
271 <p>If you don't use the ports, you can fetch and install the package
272 with <tt class="LITERAL">pkg_add -r privoxy</tt>.</p>
274 <p>The port skeleton and the package can also be downloaded from the
276 "https://sourceforge.net/project/showfiles.php?group_id=11118"
277 target="_top">File Release Page</a>, but there's no reason to use
278 them unless you're interested in the beta releases which are only
283 <h3 class="SECT3"><a name="INSTALLATTION-GENTOO" id=
284 "INSTALLATTION-GENTOO">2.1.11. Gentoo</a></h3>
286 <p>Gentoo source packages (Ebuilds) for <span class=
287 "APPLICATION">Privoxy</span> are contained in the Gentoo Portage Tree
288 (they are not on the download page, but there is a Gentoo section,
289 where you can see when a new <span class="APPLICATION">Privoxy</span>
290 Version is added to the Portage Tree).</p>
292 <p>Before installing <span class="APPLICATION">Privoxy</span> under
293 Gentoo just do first <tt class="LITERAL">emerge --sync</tt> to get
294 the latest changes from the Portage tree. With <tt class=
295 "LITERAL">emerge privoxy</tt> you install the latest version.</p>
297 <p>Configuration files are in <tt class="FILENAME">/etc/privoxy</tt>,
298 the documentation is in <tt class=
299 "FILENAME">/usr/share/doc/privoxy-3.0.20</tt> and the Log directory
300 is in <tt class="FILENAME">/var/log/privoxy</tt>.</p>
305 <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
306 "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
308 <p>The most convenient way to obtain the <span class=
309 "APPLICATION">Privoxy</span> sources is to download the source tarball
311 "http://sourceforge.net/project/showfiles.php?group_id=11118&package_id=10571"
312 target="_top">project download page</a>.</p>
314 <p>If you like to live on the bleeding edge and are not afraid of using
315 possibly unstable development versions, you can check out the
316 up-to-the-minute version directly from <a href=
317 "http://sourceforge.net/cvs/?group_id=11118" target="_top">the CVS
320 <p>To build <span class="APPLICATION">Privoxy</span> from source,
321 <a href="http://www.gnu.org/software/autoconf/autoconf.html" target=
322 "_top">autoconf</a>, <a href=
323 "http://www.gnu.org/software/make/make.html" target="_top">GNU make
324 (gmake)</a>, and, of course, a C compiler like <a href=
325 "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are
328 <p>When building from a source tarball, first unpack the source:</p>
330 <table border="0" bgcolor="#E0E0E0" width="100%">
334 tar xzvf privoxy-3.0.20-beta-src.tar.gz
335 cd privoxy-3.0.20-beta
341 <p>For retrieving the current CVS sources, you'll need a CVS client
342 installed. Note that sources from CVS are typically development
343 quality, and may not be stable, or well tested. To download CVS source,
344 check the Sourceforge documentation, which might give commands
347 <table border="0" bgcolor="#E0E0E0" width="100%">
351 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
352 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
359 <p>This will create a directory named <tt class=
360 "FILENAME">current/</tt>, which will contain the source tree.</p>
362 <p>You can also check out any <span class="APPLICATION">Privoxy</span>
363 <span class="QUOTE">"branch"</span>, just exchange the <span class=
364 "APPLICATION">current</span> name with the wanted branch name (Example:
365 v_3_0_branch for the 3.0 cvs tree).</p>
367 <p>It is also strongly recommended to not run <span class=
368 "APPLICATION">Privoxy</span> as root. You should configure/install/run
369 <span class="APPLICATION">Privoxy</span> as an unprivileged user,
370 preferably by creating a <span class="QUOTE">"privoxy"</span> user and
371 group just for this purpose. See your local documentation for the
372 correct command line to do add new users and groups (something like
373 <b class="COMMAND">adduser</b>, but the command syntax may vary from
374 platform to platform).</p>
376 <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
378 <table border="0" bgcolor="#E0E0E0" width="100%">
382 privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
388 <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
390 <table border="0" bgcolor="#E0E0E0" width="100%">
400 <p>Some binary packages may do this for you.</p>
402 <p>Then, to build from either unpacked tarball or CVS source:</p>
404 <table border="0" bgcolor="#E0E0E0" width="100%">
410 ./configure # (--help to see options)
411 make # (the make from GNU, sometimes called gmake)
412 su # Possibly required
413 make -n install # (to see where all the files will go)
414 make -s install # (to really install, -s to silence output)
420 <p>Using GNU <b class="COMMAND">make</b>, you can have the first four
421 steps automatically done for you by just typing:</p>
423 <table border="0" bgcolor="#E0E0E0" width="100%">
433 <p>in the freshly downloaded or unpacked source directory.</p>
435 <p>To build an executable with security enhanced features so that users
436 cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go There
437 Anyway"</span>), or alter their own configurations, <b class=
438 "COMMAND">configure</b> like this:</p>
440 <table border="0" bgcolor="#E0E0E0" width="100%">
444 ./configure --disable-toggle --disable-editor --disable-force
450 <p>Then build as above. In Privoxy 3.0.7 and later, all of these
451 options can also be disabled through the configuration file.</p>
453 <p><span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If
454 installing as root, the install will fail unless a non-root user or
455 group is specified, or a <tt class="LITERAL">privoxy</tt> user and
456 group already exist on the system. If a non-root user is specified, and
457 no group, then the installation will try to also use a group of the
458 same name as <span class="QUOTE">"user"</span>. If a group is specified
459 (and no user), then the support files will be installed as writable by
460 that group, and owned by the user running the installation.</p>
462 <p><b class="COMMAND">configure</b> accepts <tt class=
463 "LITERAL">--with-user</tt> and <tt class="LITERAL">--with-group</tt>
464 options for setting user and group ownership of the configuration files
465 (which need to be writable by the daemon). The specified <span class=
466 "emphasis"><i class="EMPHASIS">user must already exist</i></span>. When
467 starting <span class="APPLICATION">Privoxy</span>, it must be run as
468 this same user to insure write access to configuration and log
471 <p>Alternately, you can specify <tt class="LITERAL">user</tt> and
472 <tt class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
473 command line, but be sure both already exist:</p>
475 <table border="0" bgcolor="#E0E0E0" width="100%">
479 make -s install USER=privoxy GROUP=privoxy
485 <p>The default installation path for <b class="COMMAND">make
486 install</b> is <tt class="FILENAME">/usr/local</tt>. This may of course
487 be customized with the various <b class="COMMAND">./configure</b> path
488 options. If you are doing an install to anywhere besides <tt class=
489 "FILENAME">/usr/local</tt>, be sure to set the appropriate paths with
490 the correct configure options (<b class="COMMAND">./configure
491 --help</b>). Non-privileged users must of course have write access
492 permissions to wherever the target installation is going.</p>
494 <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the
495 install will use <tt class=
496 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
497 destinations, and the direct usage of <tt class=
498 "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add
499 the extra <tt class="FILENAME">privoxy</tt> directory. This is for a
500 safer install, as there may already exist another program that uses a
501 file with the <span class="QUOTE">"config"</span> name, and thus makes
502 <tt class="FILENAME">/usr/local/etc</tt> cleaner.</p>
504 <p>If installing to <tt class="FILENAME">/usr/local</tt>, the
505 documentation will go by default to <tt class=
506 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist,
507 it will then try <tt class="FILENAME">$prefix/doc</tt> and install
508 there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
509 just for <span class="APPLICATION">Privoxy</span>.</p>
511 <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>,
512 the <tt class="LITERAL">localstatedir</tt> (ie: <tt class=
513 "FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
514 instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to
515 <tt class="FILENAME">/var/log/privoxy/</tt>, and the pid file will be
516 created in <tt class="FILENAME">/var/run/privoxy.pid</tt>.</p>
518 <p><b class="COMMAND">make install</b> will attempt to set the correct
519 values in <tt class="FILENAME">config</tt> (main configuration file).
520 You should check this to make sure all values are correct. If
521 appropriate, an init script will be installed, but it is up to the user
522 to determine how and where to start <span class=
523 "APPLICATION">Privoxy</span>. The init script should be checked for
524 correct paths and values, if anything other than a default install is
527 <p>If install finds previous versions of local configuration files,
528 most of these will not be overwritten, and the new ones will be
529 installed with a <span class="QUOTE">"new"</span> extension.
530 default.action and default.filter <span class="emphasis"><i class=
531 "EMPHASIS">will be overwritten</i></span>. You will then need to
532 manually update the other installed configuration files as needed. The
533 default template files <span class="emphasis"><i class=
534 "EMPHASIS">will</i></span> be overwritten. If you have customized,
535 local templates, these should be stored safely in a separate directory
536 and defined in <tt class="FILENAME">config</tt> by the <span class=
537 "QUOTE">"templdir"</span> directive. It is of course wise to always
538 back-up any important configuration files <span class="QUOTE">"just in
539 case"</span>. If a previous version of <span class=
540 "APPLICATION">Privoxy</span> is already running, you will have to
541 restart it manually.</p>
543 <p>For more detailed instructions on how to build Redhat RPMs, Windows
544 self-extracting installers, building on platforms with special
545 requirements etc, please consult the <a href=
546 "http://www.privoxy.org/developer-manual/newrelease.html" target=
547 "_top">developer manual</a>.</p>
551 <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
552 "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
555 <p>As user feedback comes in and development continues, we will make
556 updated versions of both the main <a href="actions-file.html">actions
557 file</a> (as a <a href=
558 "http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670"
559 target="_top">separate package</a>) and the software itself (including
560 the actions file) available for download.</p>
562 <p>If you wish to receive an email notification whenever we release
563 updates of <span class="APPLICATION">Privoxy</span> or the actions
565 "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/" target=
566 "_top">subscribe to our announce mailing list</a>,
567 ijbswa-announce@lists.sourceforge.net.</p>
569 <p>In order not to lose your personal changes and adjustments when
570 updating to the latest <tt class="LITERAL">default.action</tt> file we
571 <span class="emphasis"><i class="EMPHASIS">strongly
572 recommend</i></span> that you use <tt class="LITERAL">user.action</tt>
573 and <tt class="LITERAL">user.filter</tt> for your local customizations
574 of <span class="APPLICATION">Privoxy</span>. See the <a href=
575 "actions-file.html">Chapter on actions files</a> for details.</p>
579 <div class="NAVFOOTER">
580 <hr align="left" width="100%">
582 <table summary="Footer navigation table" width="100%" border="0"
583 cellpadding="0" cellspacing="0">
585 <td width="33%" align="left" valign="top"><a href="introduction.html"
586 accesskey="P">Prev</a></td>
588 <td width="34%" align="center" valign="top"><a href="index.html"
589 accesskey="H">Home</a></td>
591 <td width="33%" align="right" valign="top"><a href="whatsnew.html"
592 accesskey="N">Next</a></td>
596 <td width="33%" align="left" valign="top">Introduction</td>
598 <td width="34%" align="center" valign="top"> </td>
600 <td width="33%" align="right" valign="top">What's New in this