First rebuild for 3.0.18 stable
[privoxy.git] / doc / webserver / user-manual / installation.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3
4 <html>
5 <head>
6   <meta name="generator" content=
7   "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
8
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.18 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">
19 body {
20   background-color: #EEEEEE;
21   color: #000000;
22   }
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}
30   </style>
31 </head>
32
33 <body class="SECT1">
34   <div class="NAVHEADER">
35     <table summary="Header navigation table" width="100%" border="0"
36     cellpadding="0" cellspacing="0">
37       <tr>
38         <th colspan="3" align="center">Privoxy 3.0.18 User Manual</th>
39       </tr>
40
41       <tr>
42         <td width="10%" align="left" valign="bottom"><a href=
43         "introduction.html" accesskey="P">Prev</a></td>
44
45         <td width="80%" align="center" valign="bottom"></td>
46
47         <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
48         accesskey="N">Next</a></td>
49       </tr>
50     </table>
51     <hr class="c1" width="100%">
52   </div>
53
54   <div class="SECT1">
55     <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
56     Installation</a></h1>
57
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
63     Page</a>.</p>
64
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>
70
71     <div class="SECT2">
72       <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
73       "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
74
75       <p>How to install the binary packages depends on your operating
76       system:</p>
77
78       <div class="SECT3">
79         <h3 class="SECT3"><a name="INSTALLATION-PACK-RPM" id=
80         "INSTALLATION-PACK-RPM">2.1.1. Red Hat and Fedora RPMs</a></h3>
81
82         <p>RPMs can be installed with <tt class="LITERAL">rpm -Uvh
83         privoxy-3.0.18-1.rpm</tt>, and will use <tt class=
84         "FILENAME">/etc/privoxy</tt> for the location of configuration
85         files.</p>
86
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
91         methods.</p>
92
93         <p>If you have problems with failed dependencies, try rebuilding the
94         SRC RPM: <tt class="LITERAL">rpm --rebuild
95         privoxy-3.0.18-1.src.rpm</tt>. This will use your locally installed
96         libraries and RPM version.</p>
97
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>
104       </div>
105
106       <div class="SECT3">
107         <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
108         "INSTALLATION-DEB">2.1.2. Debian and Ubuntu</a></h3>
109
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>
113       </div>
114
115       <div class="SECT3">
116         <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
117         "INSTALLATION-PACK-WIN">2.1.3. Windows</a></h3>
118
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>
123
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>
130
131         <div class="VARIABLELIST">
132           <dl>
133             <dt>Arguments:</dt>
134
135             <dd>
136               <p><tt class="REPLACEABLE c3">--install</tt>[:<tt class=
137               "REPLACEABLE c3">service_name</tt>]</p>
138
139               <p><tt class="REPLACEABLE c3">--uninstall</tt>[:<tt class=
140               "REPLACEABLE c3">service_name</tt>]</p>
141             </dd>
142           </dl>
143         </div>
144
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>
157       </div>
158
159       <div class="SECT3">
160         <h3 class="SECT3"><a name="INSTALLATION-PACK-BINTGZ" id=
161         "INSTALLATION-PACK-BINTGZ">2.1.4. Solaris</a></h3>
162
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>
166       </div>
167
168       <div class="SECT3">
169         <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
170         "INSTALLATION-OS2">2.1.5. OS/2</a></h3>
171
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>
177
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
182         starts.</p>
183
184         <p>The directory you choose to install <span class=
185         "APPLICATION">Privoxy</span> into will contain all of the
186         configuration files.</p>
187       </div>
188
189       <div class="SECT3">
190         <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
191         "INSTALLATION-MAC">2.1.6. Mac OS X</a></h3>
192
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>
197
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>
203
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
207         software).</p>
208       </div>
209
210       <div class="SECT3">
211         <h3 class="SECT3"><a name="INSTALLATION-AMIGA" id=
212         "INSTALLATION-AMIGA">2.1.7. AmigaOS</a></h3>
213
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
218         directory.</p>
219       </div>
220
221       <div class="SECT3">
222         <h3 class="SECT3"><a name="INSTALLATION-TBZ" id=
223         "INSTALLATION-TBZ">2.1.8. FreeBSD</a></h3>
224
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>
228
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>
231
232         <p>The port skeleton and the package can also be downloaded from the
233         <a href=
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
237         available there.</p>
238       </div>
239
240       <div class="SECT3">
241         <h3 class="SECT3"><a name="INSTALLATTION-GENTOO" id=
242         "INSTALLATTION-GENTOO">2.1.9. Gentoo</a></h3>
243
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>
249
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>
254
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.18</tt> and the Log directory
258         is in <tt class="FILENAME">/var/log/privoxy</tt>.</p>
259       </div>
260     </div>
261
262     <div class="SECT2">
263       <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
264       "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
265
266       <p>The most convenient way to obtain the <span class=
267       "APPLICATION">Privoxy</span> sources is to download the source tarball
268       from our <a href=
269       "http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571"
270       target="_top">project download page</a>.</p>
271
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
276       repository</a>.</p>
277
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
284       required.</p>
285
286       <p>When building from a source tarball, first unpack the source:</p>
287
288       <table class="c4" border="0" width="100%">
289         <tr>
290           <td>
291             <pre class="SCREEN">
292  tar xzvf privoxy-3.0.18-stable-src.tar.gz
293  cd privoxy-3.0.18-stable
294 </pre>
295           </td>
296         </tr>
297       </table>
298
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
303       like:</p>
304
305       <table class="c4" border="0" width="100%">
306         <tr>
307           <td>
308             <pre class="SCREEN">
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
311   cd current
312 </pre>
313           </td>
314         </tr>
315       </table>
316
317       <p>This will create a directory named <tt class=
318       "FILENAME">current/</tt>, which will contain the source tree.</p>
319
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>
324
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>
333
334       <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
335
336       <table class="c4" border="0" width="100%">
337         <tr>
338           <td>
339             <pre class="SCREEN">
340   privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
341 </pre>
342           </td>
343         </tr>
344       </table>
345
346       <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
347
348       <table class="c4" border="0" width="100%">
349         <tr>
350           <td>
351             <pre class="SCREEN">
352   privoxy:*:7777:
353 </pre>
354           </td>
355         </tr>
356       </table>
357
358       <p>Some binary packages may do this for you.</p>
359
360       <p>Then, to build from either unpacked tarball or CVS source:</p>
361
362       <table class="c4" border="0" width="100%">
363         <tr>
364           <td>
365             <pre class="SCREEN">
366  autoheader
367  autoconf
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)
373 </pre>
374           </td>
375         </tr>
376       </table>
377
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>
380
381       <table class="c4" border="0" width="100%">
382         <tr>
383           <td>
384             <pre class="SCREEN">
385   make
386 </pre>
387           </td>
388         </tr>
389       </table>
390
391       <p>in the freshly downloaded or unpacked source directory.</p>
392
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>
397
398       <table class="c4" border="0" width="100%">
399         <tr>
400           <td>
401             <pre class="SCREEN">
402  ./configure  --disable-toggle  --disable-editor  --disable-force
403 </pre>
404           </td>
405         </tr>
406       </table>
407
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>
410
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>
419
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>
427
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>
431
432       <table class="c4" border="0" width="100%">
433         <tr>
434           <td>
435             <pre class="SCREEN">
436  make -s install  USER=privoxy GROUP=privoxy
437 </pre>
438           </td>
439         </tr>
440       </table>
441
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>
450
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>
460
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>
467
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>
474
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
482       done.</p>
483
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>
499
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>
505     </div>
506
507     <div class="SECT2">
508       <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
509       "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
510       Up-to-Date</a></h2>
511
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&amp;release_id=103670"
516       target="_top">separate package</a>) and the software itself (including
517       the actions file) available for download.</p>
518
519       <p>If you wish to receive an email notification whenever we release
520       updates of <span class="APPLICATION">Privoxy</span> or the actions
521       file, <a href=
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>
525
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>
533     </div>
534   </div>
535
536   <div class="NAVFOOTER">
537     <hr class="c1" width="100%">
538
539     <table summary="Footer navigation table" width="100%" border="0"
540     cellpadding="0" cellspacing="0">
541       <tr>
542         <td width="33%" align="left" valign="top"><a href="introduction.html"
543         accesskey="P">Prev</a></td>
544
545         <td width="34%" align="center" valign="top"><a href="index.html"
546         accesskey="H">Home</a></td>
547
548         <td width="33%" align="right" valign="top"><a href="whatsnew.html"
549         accesskey="N">Next</a></td>
550       </tr>
551
552       <tr>
553         <td width="33%" align="left" valign="top">Introduction</td>
554
555         <td width="34%" align="center" valign="top">&nbsp;</td>
556
557         <td width="33%" align="right" valign="top">What's New in this
558         Release</td>
559       </tr>
560     </table>
561   </div>
562 </body>
563 </html>