1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
5 <title>Installation</title>
6 <meta name="GENERATOR" content=
7 "Modular DocBook HTML Stylesheet Version 1.79">
8 <link rel="HOME" title="Privoxy 3.0.26 User Manual" href="index.html">
9 <link rel="PREVIOUS" title="Introduction" href="introduction.html">
10 <link rel="NEXT" title="What's New in this Release" href="whatsnew.html">
11 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
12 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
13 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
15 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
16 "#840084" alink="#0000FF">
17 <div class="NAVHEADER">
18 <table summary="Header navigation table" width="100%" border="0"
19 cellpadding="0" cellspacing="0">
21 <th colspan="3" align="center">Privoxy 3.0.26 User Manual</th>
24 <td width="10%" align="left" valign="bottom"><a href=
25 "introduction.html" accesskey="P">Prev</a></td>
26 <td width="80%" align="center" valign="bottom"></td>
27 <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
28 accesskey="N">Next</a></td>
31 <hr align="left" width="100%">
34 <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
36 <p><span class="APPLICATION">Privoxy</span> is available both in
37 convenient pre-compiled packages for a wide range of operating systems,
38 and as raw source code. For most users, we recommend using the packages,
39 which can be downloaded from our <a href=
40 "https://sourceforge.net/projects/ijbswa/" target="_top">Privoxy Project
42 <p>Note: On some platforms, the installer may remove previously installed
43 versions, if found. (See below for your platform). In any case
44 <span class="emphasis"><i class="EMPHASIS">be sure to backup your old
45 configuration if it is valuable to you.</i></span> See the <a href=
46 "whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section below.</p>
48 <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
49 "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
50 <p>How to install the binary packages depends on your operating
53 <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
54 "INSTALLATION-DEB">2.1.1. Debian and Ubuntu</a></h3>
55 <p>DEBs can be installed with <tt class="LITERAL">apt-get install
56 privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt> for
57 the location of configuration files.</p>
60 <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
61 "INSTALLATION-PACK-WIN">2.1.2. Windows</a></h3>
62 <p>Just double-click the installer, which will guide you through the
63 installation process. You will find the configuration files in the
64 same directory as you installed <span class=
65 "APPLICATION">Privoxy</span> in.</p>
66 <p>Version 3.0.5 beta introduced full <span class=
67 "APPLICATION">Windows</span> service functionality. On Windows only,
68 the <span class="APPLICATION">Privoxy</span> program has two new
69 command line arguments to install and uninstall <span class=
70 "APPLICATION">Privoxy</span> as a <span class="emphasis"><i class=
71 "EMPHASIS">service</i></span>.</p>
72 <div class="VARIABLELIST">
76 <p><tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class=
77 "REPLACEABLE"><i>service_name</i></tt>]</p>
78 <p><tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class=
79 "REPLACEABLE"><i>service_name</i></tt>]</p>
83 <p>After invoking <span class="APPLICATION">Privoxy</span> with
84 <b class="COMMAND">--install</b>, you will need to bring up the
85 <span class="APPLICATION">Windows</span> service console to assign
86 the user you want <span class="APPLICATION">Privoxy</span> to run
87 under, and whether or not you want it to run whenever the system
88 starts. You can start the <span class="APPLICATION">Windows</span>
89 services console with the following command: <b class=
90 "COMMAND">services.msc</b>. If you do not take the manual step of
91 modifying <span class="APPLICATION">Privoxy's</span> service
92 settings, it will not start. Note too that you will need to give
93 Privoxy a user account that actually exists, or it will not be
94 permitted to write to its log and configuration files.</p>
97 <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
98 "INSTALLATION-OS2">2.1.3. OS/2</a></h3>
99 <p>First, make sure that no previous installations of <span class=
100 "APPLICATION">Junkbuster</span> and / or <span class=
101 "APPLICATION">Privoxy</span> are left on your system. Check that no
102 <span class="APPLICATION">Junkbuster</span> or <span class=
103 "APPLICATION">Privoxy</span> objects are in your startup folder.</p>
104 <p>Then, just double-click the WarpIN self-installing archive, which
105 will guide you through the installation process. A shadow of the
106 <span class="APPLICATION">Privoxy</span> executable will be placed in
107 your startup folder so it will start automatically whenever OS/2
109 <p>The directory you choose to install <span class=
110 "APPLICATION">Privoxy</span> into will contain all of the
111 configuration files.</p>
114 <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
115 "INSTALLATION-MAC">2.1.4. Mac OS X</a></h3>
116 <p>Installation instructions for the OS X platform depend upon
117 whether you downloaded a ready-built installation package (.pkg or
118 .mpkg) or have downloaded the source code.</p>
121 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-PACKAGE" id=
122 "OS-X-INSTALL-FROM-PACKAGE">2.1.5. Installation from ready-built
124 <p>The downloaded file will either be a .pkg (for OS X 10.5 upwards)
125 or a bzipped .mpkg file (for OS X 10.4). The former can be
126 double-clicked as is and the installation will start; double-clicking
127 the latter will unzip the .mpkg file which can then be double-clicked
128 to commence the installation.</p>
129 <p>The privoxy service will automatically start after a successful
130 installation (and thereafter every time your computer starts up)
131 however you will need to configure your web browser(s) to use it. To
132 do so, configure them to use a proxy for HTTP and HTTPS at the
133 address 127.0.0.1:8118.</p>
134 <p>To prevent the privoxy service from automatically starting when
135 your computer starts up, remove or rename the file <tt class=
136 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
137 X 10.5 and higher) or the folder named <tt class=
138 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
140 <p>To manually start or stop the privoxy service, use the scripts
141 startPrivoxy.sh and stopPrivoxy.sh supplied in /Applications/Privoxy.
142 They must be run from an administrator account, using sudo.</p>
143 <p>To uninstall, run /Applications/Privoxy/uninstall.command as sudo
144 from an administrator account.</p>
147 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-SOURCE" id=
148 "OS-X-INSTALL-FROM-SOURCE">2.1.6. Installation from source</a></h4>
149 <p>To build and install the Privoxy source code on OS X you will need
150 to obtain the macsetup module from the Privoxy Sourceforge CVS
151 repository (refer to Sourceforge help for details of how to set up a
152 CVS client to have read-only access to the repository). This module
153 contains scripts that leverage the usual open-source tools (available
154 as part of Apple's free of charge Xcode distribution or via the usual
155 open-source software package managers for OS X (MacPorts, Homebrew,
156 Fink etc.) to build and then install the privoxy binary and
157 associated files. The macsetup module's README file contains complete
158 instructions for its use.</p>
159 <p>The privoxy service will automatically start after a successful
160 installation (and thereafter every time your computer starts up)
161 however you will need to configure your web browser(s) to use it. To
162 do so, configure them to use a proxy for HTTP and HTTPS at the
163 address 127.0.0.1:8118.</p>
164 <p>To prevent the privoxy service from automatically starting when
165 your computer starts up, remove or rename the file <tt class=
166 "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS
167 X 10.5 and higher) or the folder named <tt class=
168 "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
170 <p>To manually start or stop the privoxy service, use the Privoxy
171 Utility for Mac OS X (also part of the macsetup module). This
172 application can start and stop the privoxy service and display its
173 log and configuration files.</p>
174 <p>To uninstall, run the macsetup module's uninstall.sh as sudo from
175 an administrator account.</p>
178 <h3 class="SECT3"><a name="INSTALLATION-FREEBSD" id=
179 "INSTALLATION-FREEBSD">2.1.7. FreeBSD</a></h3>
180 <p>Privoxy is part of FreeBSD's Ports Collection, you can build and
181 install it with <tt class="LITERAL">cd /usr/ports/www/privoxy; make
182 install clean</tt>.</p>
186 <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
187 "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
188 <p>The most convenient way to obtain the <span class=
189 "APPLICATION">Privoxy</span> sources is to download the source tarball
191 "https://sourceforge.net/projects/ijbswa/files/Sources/" target=
192 "_top">project download page</a>.</p>
193 <p>If you like to live on the bleeding edge and are not afraid of using
194 possibly unstable development versions, you can check out the
195 up-to-the-minute version directly from <a href=
196 "https://sourceforge.net/p/ijbswa/code/?source=navbar" target=
197 "_top">the CVS repository</a>.</p>
198 <p>To build <span class="APPLICATION">Privoxy</span> from source,
199 <a href="http://www.gnu.org/software/autoconf/autoconf.html" target=
200 "_top">autoconf</a>, <a href=
201 "http://www.gnu.org/software/make/make.html" target="_top">GNU make
202 (gmake)</a>, and, of course, a C compiler like <a href=
203 "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are
205 <p>When building from a source tarball, first unpack the source:</p>
206 <table border="0" bgcolor="#E0E0E0" width="100%">
209 <pre class="SCREEN"> tar xzvf privoxy-3.0.26-stable-src.tar.gz
210 cd privoxy-3.0.26-stable</pre>
214 <p>For retrieving the current CVS sources, you'll need a CVS client
215 installed. Note that sources from CVS are typically development
216 quality, and may not be stable, or well tested. To download CVS source,
217 check the Sourceforge documentation, which might give commands
219 <table border="0" bgcolor="#E0E0E0" width="100%">
223 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
224 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
229 <p>This will create a directory named <tt class=
230 "FILENAME">current/</tt>, which will contain the source tree.</p>
231 <p>You can also check out any <span class="APPLICATION">Privoxy</span>
232 <span class="QUOTE">"branch"</span>, just exchange the <span class=
233 "APPLICATION">current</span> name with the wanted branch name (Example:
234 v_3_0_branch for the 3.0 cvs tree).</p>
235 <p>It is also strongly recommended to not run <span class=
236 "APPLICATION">Privoxy</span> as root. You should configure/install/run
237 <span class="APPLICATION">Privoxy</span> as an unprivileged user,
238 preferably by creating a <span class="QUOTE">"privoxy"</span> user and
239 group just for this purpose. See your local documentation for the
240 correct command line to do add new users and groups (something like
241 <b class="COMMAND">adduser</b>, but the command syntax may vary from
242 platform to platform).</p>
243 <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
244 <table border="0" bgcolor="#E0E0E0" width="100%">
248 privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</pre>
252 <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
253 <table border="0" bgcolor="#E0E0E0" width="100%">
256 <pre class="SCREEN"> privoxy:*:7777:</pre>
260 <p>Some binary packages may do this for you.</p>
261 <p>Then, to build from either unpacked tarball or CVS source:</p>
262 <table border="0" bgcolor="#E0E0E0" width="100%">
265 <pre class="SCREEN"> autoheader
267 ./configure # (--help to see options)
268 make # (the make from GNU, sometimes called gmake)
269 su # Possibly required
270 make -n install # (to see where all the files will go)
271 make -s install # (to really install, -s to silence output)</pre>
275 <p>Using GNU <b class="COMMAND">make</b>, you can have the first four
276 steps automatically done for you by just typing:</p>
277 <table border="0" bgcolor="#E0E0E0" width="100%">
280 <pre class="SCREEN"> make</pre>
284 <p>in the freshly downloaded or unpacked source directory.</p>
285 <p>To build an executable with security enhanced features so that users
286 cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go There
287 Anyway"</span>), or alter their own configurations, <b class=
288 "COMMAND">configure</b> like this:</p>
289 <table border="0" bgcolor="#E0E0E0" width="100%">
293 ./configure --disable-toggle --disable-editor --disable-force</pre>
297 <p>Note that all of these options can also be disabled through the
298 configuration file.</p>
299 <p><span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If
300 installing as root, the install will fail unless a non-root user or
301 group is specified, or a <tt class="LITERAL">privoxy</tt> user and
302 group already exist on the system. If a non-root user is specified, and
303 no group, then the installation will try to also use a group of the
304 same name as <span class="QUOTE">"user"</span>. If a group is specified
305 (and no user), then the support files will be installed as writable by
306 that group, and owned by the user running the installation.</p>
307 <p><b class="COMMAND">configure</b> accepts <tt class=
308 "LITERAL">--with-user</tt> and <tt class="LITERAL">--with-group</tt>
309 options for setting user and group ownership of the configuration files
310 (which need to be writable by the daemon). The specified <span class=
311 "emphasis"><i class="EMPHASIS">user must already exist</i></span>. When
312 starting <span class="APPLICATION">Privoxy</span>, it must be run as
313 this same user to insure write access to configuration and log
315 <p>Alternately, you can specify <tt class="LITERAL">user</tt> and
316 <tt class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
317 command line, but be sure both already exist:</p>
318 <table border="0" bgcolor="#E0E0E0" width="100%">
322 make -s install USER=privoxy GROUP=privoxy</pre>
326 <p>The default installation path for <b class="COMMAND">make
327 install</b> is <tt class="FILENAME">/usr/local</tt>. This may of course
328 be customized with the various <b class="COMMAND">./configure</b> path
329 options. If you are doing an install to anywhere besides <tt class=
330 "FILENAME">/usr/local</tt>, be sure to set the appropriate paths with
331 the correct configure options (<b class="COMMAND">./configure
332 --help</b>). Non-privileged users must of course have write access
333 permissions to wherever the target installation is going.</p>
334 <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the
335 install will use <tt class=
336 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
337 destinations, and the direct usage of <tt class=
338 "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add
339 the extra <tt class="FILENAME">privoxy</tt> directory. This is for a
340 safer install, as there may already exist another program that uses a
341 file with the <span class="QUOTE">"config"</span> name, and thus makes
342 <tt class="FILENAME">/usr/local/etc</tt> cleaner.</p>
343 <p>If installing to <tt class="FILENAME">/usr/local</tt>, the
344 documentation will go by default to <tt class=
345 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist,
346 it will then try <tt class="FILENAME">$prefix/doc</tt> and install
347 there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
348 just for <span class="APPLICATION">Privoxy</span>.</p>
349 <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>,
350 the <tt class="LITERAL">localstatedir</tt> (ie: <tt class=
351 "FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
352 instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to
353 <tt class="FILENAME">/var/log/privoxy/</tt>, and the pid file will be
354 created in <tt class="FILENAME">/var/run/privoxy.pid</tt>.</p>
355 <p><b class="COMMAND">make install</b> will attempt to set the correct
356 values in <tt class="FILENAME">config</tt> (main configuration file).
357 You should check this to make sure all values are correct. If
358 appropriate, an init script will be installed, but it is up to the user
359 to determine how and where to start <span class=
360 "APPLICATION">Privoxy</span>. The init script should be checked for
361 correct paths and values, if anything other than a default install is
363 <p>If install finds previous versions of local configuration files,
364 most of these will not be overwritten, and the new ones will be
365 installed with a <span class="QUOTE">"new"</span> extension.
366 default.action and default.filter <span class="emphasis"><i class=
367 "EMPHASIS">will be overwritten</i></span>. You will then need to
368 manually update the other installed configuration files as needed. The
369 default template files <span class="emphasis"><i class=
370 "EMPHASIS">will</i></span> be overwritten. If you have customized,
371 local templates, these should be stored safely in a separate directory
372 and defined in <tt class="FILENAME">config</tt> by the <span class=
373 "QUOTE">"templdir"</span> directive. It is of course wise to always
374 back-up any important configuration files <span class="QUOTE">"just in
375 case"</span>. If a previous version of <span class=
376 "APPLICATION">Privoxy</span> is already running, you will have to
377 restart it manually.</p>
378 <p>For more detailed instructions on how to build Redhat RPMs, Windows
379 self-extracting installers, building on platforms with special
380 requirements etc, please consult the <a href=
381 "https://www.privoxy.org/developer-manual/newrelease.html" target=
382 "_top">developer manual</a>.</p>
385 <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
386 "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
388 <p>If you wish to receive an email notification whenever we release
389 updates of <span class="APPLICATION">Privoxy</span> or the actions
391 "https://lists.privoxy.org/mailman/listinfo/privoxy-announce" target=
392 "_top">subscribe to our announce mailing list</a>,
393 privoxy-announce@lists.privoxy.org.</p>
394 <p>In order not to lose your personal changes and adjustments when
395 updating to the latest <tt class="LITERAL">default.action</tt> file we
396 <span class="emphasis"><i class="EMPHASIS">strongly
397 recommend</i></span> that you use <tt class="LITERAL">user.action</tt>
398 and <tt class="LITERAL">user.filter</tt> for your local customizations
399 of <span class="APPLICATION">Privoxy</span>. See the <a href=
400 "actions-file.html">Chapter on actions files</a> for details.</p>
403 <div class="NAVFOOTER">
404 <hr align="left" width="100%">
405 <table summary="Footer navigation table" width="100%" border="0"
406 cellpadding="0" cellspacing="0">
408 <td width="33%" align="left" valign="top"><a href="introduction.html"
409 accesskey="P">Prev</a></td>
410 <td width="34%" align="center" valign="top"><a href="index.html"
411 accesskey="H">Home</a></td>
412 <td width="33%" align="right" valign="top"><a href="whatsnew.html"
413 accesskey="N">Next</a></td>
416 <td width="33%" align="left" valign="top">Introduction</td>
417 <td width="34%" align="center" valign="top"> </td>
418 <td width="33%" align="right" valign="top">What's New in this