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="Modular DocBook HTML Stylesheet Version 1.79">
7 <link rel="HOME" title="Privoxy 3.0.27 User Manual" href="index.html">
8 <link rel="PREVIOUS" title="Introduction" href="introduction.html">
9 <link rel="NEXT" title="What's New in this Release" href="whatsnew.html">
10 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
11 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
12 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
14 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <div class="NAVHEADER">
16 <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
18 <th colspan="3" align="center">Privoxy 3.0.27 User Manual</th>
21 <td width="10%" align="left" valign="bottom"><a href="introduction.html" accesskey="P">Prev</a></td>
22 <td width="80%" align="center" valign="bottom"></td>
23 <td width="10%" align="right" valign="bottom"><a href="whatsnew.html" accesskey="N">Next</a></td>
26 <hr align="left" width="100%">
29 <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2. Installation</a></h1>
30 <p><span class="APPLICATION">Privoxy</span> is available both in convenient pre-compiled packages for a wide range
31 of operating systems, and as raw source code. For most users, we recommend using the packages, which can be
32 downloaded from our <a href="https://sourceforge.net/projects/ijbswa/" target="_top">Privoxy Project Page</a>.</p>
33 <p>Note: On some platforms, the installer may remove previously installed versions, if found. (See below for your
34 platform). In any case <span class="emphasis"><i class="EMPHASIS">be sure to backup your old configuration if it is
35 valuable to you.</i></span> See the <a href="whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section below.</p>
37 <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id="INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
38 <p>How to install the binary packages depends on your operating system:</p>
40 <h3 class="SECT3"><a name="INSTALLATION-DEB" id="INSTALLATION-DEB">2.1.1. Debian and Ubuntu</a></h3>
41 <p>DEBs can be installed with <tt class="LITERAL">apt-get install privoxy</tt>, and will use <tt class=
42 "FILENAME">/etc/privoxy</tt> for the location of configuration files.</p>
45 <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id="INSTALLATION-PACK-WIN">2.1.2. Windows</a></h3>
46 <p>Just double-click the installer, which will guide you through the installation process. You will find the
47 configuration files in the same directory as you installed <span class="APPLICATION">Privoxy</span> in.</p>
48 <p>Version 3.0.5 beta introduced full <span class="APPLICATION">Windows</span> service functionality. On
49 Windows only, the <span class="APPLICATION">Privoxy</span> program has two new command line arguments to
50 install and uninstall <span class="APPLICATION">Privoxy</span> as a <span class="emphasis"><i class=
51 "EMPHASIS">service</i></span>.</p>
52 <div class="VARIABLELIST">
56 <p><tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class="REPLACEABLE"><i>service_name</i></tt>]</p>
57 <p><tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class="REPLACEABLE"><i>service_name</i></tt>]</p>
61 <p>After invoking <span class="APPLICATION">Privoxy</span> with <b class="COMMAND">--install</b>, you will need
62 to bring up the <span class="APPLICATION">Windows</span> service console to assign the user you want
63 <span class="APPLICATION">Privoxy</span> to run under, and whether or not you want it to run whenever the
64 system starts. You can start the <span class="APPLICATION">Windows</span> services console with the following
65 command: <b class="COMMAND">services.msc</b>. If you do not take the manual step of modifying <span class=
66 "APPLICATION">Privoxy's</span> service settings, it will not start. Note too that you will need to give Privoxy
67 a user account that actually exists, or it will not be permitted to write to its log and configuration
71 <h3 class="SECT3"><a name="INSTALLATION-OS2" id="INSTALLATION-OS2">2.1.3. OS/2</a></h3>
72 <p>First, make sure that no previous installations of <span class="APPLICATION">Junkbuster</span> and / or
73 <span class="APPLICATION">Privoxy</span> are left on your system. Check that no <span class=
74 "APPLICATION">Junkbuster</span> or <span class="APPLICATION">Privoxy</span> objects are in your startup
76 <p>Then, just double-click the WarpIN self-installing archive, which will guide you through the installation
77 process. A shadow of the <span class="APPLICATION">Privoxy</span> executable will be placed in your startup
78 folder so it will start automatically whenever OS/2 starts.</p>
79 <p>The directory you choose to install <span class="APPLICATION">Privoxy</span> into will contain all of the
80 configuration files.</p>
83 <h3 class="SECT3"><a name="INSTALLATION-MAC" id="INSTALLATION-MAC">2.1.4. Mac OS X</a></h3>
84 <p>Installation instructions for the OS X platform depend upon whether you downloaded a ready-built
85 installation package (.pkg or .mpkg) or have downloaded the source code.</p>
88 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-PACKAGE" id="OS-X-INSTALL-FROM-PACKAGE">2.1.5. Installation from
89 ready-built package</a></h4>
90 <p>The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped .mpkg file (for OS X 10.4).
91 The former can be double-clicked as is and the installation will start; double-clicking the latter will unzip
92 the .mpkg file which can then be double-clicked to commence the installation.</p>
93 <p>The privoxy service will automatically start after a successful installation (and thereafter every time your
94 computer starts up) however you will need to configure your web browser(s) to use it. To do so, configure them
95 to use a proxy for HTTP and HTTPS at the address 127.0.0.1:8118.</p>
96 <p>To prevent the privoxy service from automatically starting when your computer starts up, remove or rename
97 the file <tt class="LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS X 10.5 and higher) or
98 the folder named <tt class="LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4 'Tiger').</p>
99 <p>To manually start or stop the privoxy service, use the scripts startPrivoxy.sh and stopPrivoxy.sh supplied
100 in /Applications/Privoxy. They must be run from an administrator account, using sudo.</p>
101 <p>To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an administrator account.</p>
104 <h4 class="SECT3"><a name="OS-X-INSTALL-FROM-SOURCE" id="OS-X-INSTALL-FROM-SOURCE">2.1.6. Installation from
106 <p>To build and install the Privoxy source code on OS X you will need to obtain the macsetup module from the
107 Privoxy Sourceforge CVS repository (refer to Sourceforge help for details of how to set up a CVS client to have
108 read-only access to the repository). This module contains scripts that leverage the usual open-source tools
109 (available as part of Apple's free of charge Xcode distribution or via the usual open-source software package
110 managers for OS X (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary and associated
111 files. The macsetup module's README file contains complete instructions for its use.</p>
112 <p>The privoxy service will automatically start after a successful installation (and thereafter every time your
113 computer starts up) however you will need to configure your web browser(s) to use it. To do so, configure them
114 to use a proxy for HTTP and HTTPS at the address 127.0.0.1:8118.</p>
115 <p>To prevent the privoxy service from automatically starting when your computer starts up, remove or rename
116 the file <tt class="LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on OS X 10.5 and higher) or
117 the folder named <tt class="LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4 'Tiger').</p>
118 <p>To manually start or stop the privoxy service, use the Privoxy Utility for Mac OS X (also part of the
119 macsetup module). This application can start and stop the privoxy service and display its log and configuration
121 <p>To uninstall, run the macsetup module's uninstall.sh as sudo from an administrator account.</p>
124 <h3 class="SECT3"><a name="INSTALLATION-FREEBSD" id="INSTALLATION-FREEBSD">2.1.7. FreeBSD</a></h3>
125 <p>Privoxy is part of FreeBSD's Ports Collection, you can build and install it with <tt class="LITERAL">cd
126 /usr/ports/www/privoxy; make install clean</tt>.</p>
130 <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id="INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
131 <p>The most convenient way to obtain the <span class="APPLICATION">Privoxy</span> sources is to download the
132 source tarball from our <a href="https://sourceforge.net/projects/ijbswa/files/Sources/" target="_top">project
133 download page</a>.</p>
134 <p>If you like to live on the bleeding edge and are not afraid of using possibly unstable development versions,
135 you can check out the up-to-the-minute version directly from <a href=
136 "https://sourceforge.net/p/ijbswa/code/?source=navbar" target="_top">the CVS repository</a>.</p>
137 <p>To build <span class="APPLICATION">Privoxy</span> from source, <a href=
138 "http://www.gnu.org/software/autoconf/autoconf.html" target="_top">autoconf</a>, <a href=
139 "http://www.gnu.org/software/make/make.html" target="_top">GNU make (gmake)</a>, and, of course, a C compiler
140 like <a href="http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are required.</p>
141 <p>When building from a source tarball, first unpack the source:</p>
142 <table border="0" bgcolor="#E0E0E0" width="100%">
145 <pre class="SCREEN"> tar xzvf privoxy-3.0.27-beta-src.tar.gz
146 cd privoxy-3.0.27-beta</pre>
150 <p>For retrieving the current CVS sources, you'll need a CVS client installed. Note that sources from CVS are
151 typically development quality, and may not be stable, or well tested. To download CVS source, check the
152 Sourceforge documentation, which might give commands like:</p>
153 <table border="0" bgcolor="#E0E0E0" width="100%">
156 <pre class="SCREEN"> cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
157 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
162 <p>This will create a directory named <tt class="FILENAME">current/</tt>, which will contain the source tree.</p>
163 <p>You can also check out any <span class="APPLICATION">Privoxy</span> <span class="QUOTE">"branch"</span>, just
164 exchange the <span class="APPLICATION">current</span> name with the wanted branch name (Example: v_3_0_branch for
165 the 3.0 cvs tree).</p>
166 <p>It is also strongly recommended to not run <span class="APPLICATION">Privoxy</span> as root. You should
167 configure/install/run <span class="APPLICATION">Privoxy</span> as an unprivileged user, preferably by creating a
168 <span class="QUOTE">"privoxy"</span> user and group just for this purpose. See your local documentation for the
169 correct command line to do add new users and groups (something like <b class="COMMAND">adduser</b>, but the
170 command syntax may vary from platform to platform).</p>
171 <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
172 <table border="0" bgcolor="#E0E0E0" width="100%">
175 <pre class="SCREEN"> privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</pre>
179 <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
180 <table border="0" bgcolor="#E0E0E0" width="100%">
183 <pre class="SCREEN"> privoxy:*:7777:</pre>
187 <p>Some binary packages may do this for you.</p>
188 <p>Then, to build from either unpacked tarball or CVS source:</p>
189 <table border="0" bgcolor="#E0E0E0" width="100%">
192 <pre class="SCREEN"> autoheader
194 ./configure # (--help to see options)
195 make # (the make from GNU, sometimes called gmake)
196 su # Possibly required
197 make -n install # (to see where all the files will go)
198 make -s install # (to really install, -s to silence output)</pre>
202 <p>Using GNU <b class="COMMAND">make</b>, you can have the first four steps automatically done for you by just
204 <table border="0" bgcolor="#E0E0E0" width="100%">
207 <pre class="SCREEN"> make</pre>
211 <p>in the freshly downloaded or unpacked source directory.</p>
212 <p>To build an executable with security enhanced features so that users cannot easily bypass the proxy (e.g.
213 <span class="QUOTE">"Go There Anyway"</span>), or alter their own configurations, <b class=
214 "COMMAND">configure</b> like this:</p>
215 <table border="0" bgcolor="#E0E0E0" width="100%">
218 <pre class="SCREEN"> ./configure --disable-toggle --disable-editor --disable-force</pre>
222 <p>Note that all of these options can also be disabled through the configuration file.</p>
223 <p><span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If installing as root, the install will fail
224 unless a non-root user or group is specified, or a <tt class="LITERAL">privoxy</tt> user and group already exist
225 on the system. If a non-root user is specified, and no group, then the installation will try to also use a group
226 of the same name as <span class="QUOTE">"user"</span>. If a group is specified (and no user), then the support
227 files will be installed as writable by that group, and owned by the user running the installation.</p>
228 <p><b class="COMMAND">configure</b> accepts <tt class="LITERAL">--with-user</tt> and <tt class=
229 "LITERAL">--with-group</tt> options for setting user and group ownership of the configuration files (which need
230 to be writable by the daemon). The specified <span class="emphasis"><i class="EMPHASIS">user must already
231 exist</i></span>. When starting <span class="APPLICATION">Privoxy</span>, it must be run as this same user to
232 insure write access to configuration and log files!</p>
233 <p>Alternately, you can specify <tt class="LITERAL">user</tt> and <tt class="LITERAL">group</tt> on the <b class=
234 "COMMAND">make</b> command line, but be sure both already exist:</p>
235 <table border="0" bgcolor="#E0E0E0" width="100%">
238 <pre class="SCREEN"> make -s install USER=privoxy GROUP=privoxy</pre>
242 <p>The default installation path for <b class="COMMAND">make install</b> is <tt class="FILENAME">/usr/local</tt>.
243 This may of course be customized with the various <b class="COMMAND">./configure</b> path options. If you are
244 doing an install to anywhere besides <tt class="FILENAME">/usr/local</tt>, be sure to set the appropriate paths
245 with the correct configure options (<b class="COMMAND">./configure --help</b>). Non-privileged users must of
246 course have write access permissions to wherever the target installation is going.</p>
247 <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the install will use <tt class=
248 "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other destinations, and the direct usage of
249 <tt class="LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add the extra <tt class=
250 "FILENAME">privoxy</tt> directory. This is for a safer install, as there may already exist another program that
251 uses a file with the <span class="QUOTE">"config"</span> name, and thus makes <tt class=
252 "FILENAME">/usr/local/etc</tt> cleaner.</p>
253 <p>If installing to <tt class="FILENAME">/usr/local</tt>, the documentation will go by default to <tt class=
254 "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist, it will then try <tt class=
255 "FILENAME">$prefix/doc</tt> and install there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
256 just for <span class="APPLICATION">Privoxy</span>.</p>
257 <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>, the <tt class=
258 "LITERAL">localstatedir</tt> (ie: <tt class="FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
259 instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to <tt class=
260 "FILENAME">/var/log/privoxy/</tt>, and the pid file will be created in <tt class=
261 "FILENAME">/var/run/privoxy.pid</tt>.</p>
262 <p><b class="COMMAND">make install</b> will attempt to set the correct values in <tt class="FILENAME">config</tt>
263 (main configuration file). You should check this to make sure all values are correct. If appropriate, an init
264 script will be installed, but it is up to the user to determine how and where to start <span class=
265 "APPLICATION">Privoxy</span>. The init script should be checked for correct paths and values, if anything other
266 than a default install is done.</p>
267 <p>If install finds previous versions of local configuration files, most of these will not be overwritten, and
268 the new ones will be installed with a <span class="QUOTE">"new"</span> extension. default.action and
269 default.filter <span class="emphasis"><i class="EMPHASIS">will be overwritten</i></span>. You will then need to
270 manually update the other installed configuration files as needed. The default template files <span class=
271 "emphasis"><i class="EMPHASIS">will</i></span> be overwritten. If you have customized, local templates, these
272 should be stored safely in a separate directory and defined in <tt class="FILENAME">config</tt> by the
273 <span class="QUOTE">"templdir"</span> directive. It is of course wise to always back-up any important
274 configuration files <span class="QUOTE">"just in case"</span>. If a previous version of <span class=
275 "APPLICATION">Privoxy</span> is already running, you will have to restart it manually.</p>
276 <p>For more detailed instructions on how to build Redhat RPMs, Windows self-extracting installers, building on
277 platforms with special requirements etc, please consult the <a href=
278 "https://www.privoxy.org/developer-manual/newrelease.html" target="_top">developer manual</a>.</p>
281 <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id="INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
283 <p>If you wish to receive an email notification whenever we release updates of <span class=
284 "APPLICATION">Privoxy</span> or the actions file, <a href=
285 "https://lists.privoxy.org/mailman/listinfo/privoxy-announce" target="_top">subscribe to our announce mailing
286 list</a>, privoxy-announce@lists.privoxy.org.</p>
287 <p>In order not to lose your personal changes and adjustments when updating to the latest <tt class=
288 "LITERAL">default.action</tt> file we <span class="emphasis"><i class="EMPHASIS">strongly recommend</i></span>
289 that you use <tt class="LITERAL">user.action</tt> and <tt class="LITERAL">user.filter</tt> for your local
290 customizations of <span class="APPLICATION">Privoxy</span>. See the <a href="actions-file.html">Chapter on
291 actions files</a> for details.</p>
294 <div class="NAVFOOTER">
295 <hr align="left" width="100%">
296 <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
298 <td width="33%" align="left" valign="top"><a href="introduction.html" accesskey="P">Prev</a></td>
299 <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
300 <td width="33%" align="right" valign="top"><a href="whatsnew.html" accesskey="N">Next</a></td>
303 <td width="33%" align="left" valign="top">Introduction</td>
304 <td width="34%" align="center" valign="top"> </td>
305 <td width="33%" align="right" valign="top">What's New in this Release</td>