Documentation for 3.0.19, regenerated with the modified tidy changes
[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   <title>Installation</title>
7   <meta name="GENERATOR" content=
8   "Modular DocBook HTML Stylesheet Version 1.79">
9   <link rel="HOME" title="Privoxy 3.0.19 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">
15 </head>
16
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">
22       <tr>
23         <th colspan="3" align="center">Privoxy 3.0.19 User Manual</th>
24       </tr>
25
26       <tr>
27         <td width="10%" align="left" valign="bottom"><a href=
28         "introduction.html" accesskey="P">Prev</a></td>
29
30         <td width="80%" align="center" valign="bottom"></td>
31
32         <td width="10%" align="right" valign="bottom"><a href="whatsnew.html"
33         accesskey="N">Next</a></td>
34       </tr>
35     </table>
36     <hr align="left" width="100%">
37   </div>
38
39   <div class="SECT1">
40     <h1 class="SECT1"><a name="INSTALLATION" id="INSTALLATION">2.
41     Installation</a></h1>
42
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
48     Page</a>.</p>
49
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>
55
56     <div class="SECT2">
57       <h2 class="SECT2"><a name="INSTALLATION-PACKAGES" id=
58       "INSTALLATION-PACKAGES">2.1. Binary Packages</a></h2>
59
60       <p>How to install the binary packages depends on your operating
61       system:</p>
62
63       <div class="SECT3">
64         <h3 class="SECT3"><a name="INSTALLATION-PACK-RPM" id=
65         "INSTALLATION-PACK-RPM">2.1.1. Red Hat and Fedora RPMs</a></h3>
66
67         <p>RPMs can be installed with <tt class="LITERAL">rpm -Uvh
68         privoxy-3.0.19-1.rpm</tt>, and will use <tt class=
69         "FILENAME">/etc/privoxy</tt> for the location of configuration
70         files.</p>
71
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>
77
78         <p>If you have problems with failed dependencies, try rebuilding the
79         SRC RPM: <tt class="LITERAL">rpm --rebuild
80         privoxy-3.0.19-1.src.rpm</tt>. This will use your locally installed
81         libraries and RPM version.</p>
82
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>
89       </div>
90
91       <div class="SECT3">
92         <h3 class="SECT3"><a name="INSTALLATION-DEB" id=
93         "INSTALLATION-DEB">2.1.2. Debian and Ubuntu</a></h3>
94
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>
98       </div>
99
100       <div class="SECT3">
101         <h3 class="SECT3"><a name="INSTALLATION-PACK-WIN" id=
102         "INSTALLATION-PACK-WIN">2.1.3. Windows</a></h3>
103
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>
108
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>
115
116         <div class="VARIABLELIST">
117           <dl>
118             <dt>Arguments:</dt>
119
120             <dd>
121               <p><tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class=
122               "REPLACEABLE"><i>service_name</i></tt>]</p>
123
124               <p><tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class=
125               "REPLACEABLE"><i>service_name</i></tt>]</p>
126             </dd>
127           </dl>
128         </div>
129
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>
142       </div>
143
144       <div class="SECT3">
145         <h3 class="SECT3"><a name="INSTALLATION-PACK-BINTGZ" id=
146         "INSTALLATION-PACK-BINTGZ">2.1.4. Solaris</a></h3>
147
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>
151       </div>
152
153       <div class="SECT3">
154         <h3 class="SECT3"><a name="INSTALLATION-OS2" id=
155         "INSTALLATION-OS2">2.1.5. OS/2</a></h3>
156
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>
162
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
167         starts.</p>
168
169         <p>The directory you choose to install <span class=
170         "APPLICATION">Privoxy</span> into will contain all of the
171         configuration files.</p>
172       </div>
173
174       <div class="SECT3">
175         <h3 class="SECT3"><a name="INSTALLATION-MAC" id=
176         "INSTALLATION-MAC">2.1.6. Mac OS X</a></h3>
177
178         <p>Unzip the downloaded file (you can either double-click on the zip
179         file icon from the Finder, or from the desktop if you downloaded it
180         there). Then, double-click on the package installer icon and follow
181         the installation process.</p>
182
183         <p>The privoxy service will automatically start after a successful
184         installation (in addition to every time your computer starts up). To
185         prevent the privoxy service from automatically starting when your
186         computer starts up, remove or rename the folder named <tt class=
187         "LITERAL">/Library/StartupItems/Privoxy</tt>.</p>
188
189         <p>To manually start or stop the privoxy service, use the Privoxy
190         Utility for Mac OS X. This application controls the privoxy service
191         (e.g. starting and stopping the service as well as uninstalling the
192         software).</p>
193       </div>
194
195       <div class="SECT3">
196         <h3 class="SECT3"><a name="INSTALLATION-AMIGA" id=
197         "INSTALLATION-AMIGA">2.1.7. AmigaOS</a></h3>
198
199         <p>Copy and then unpack the <tt class="FILENAME">lha</tt> archive to
200         a suitable location. All necessary files will be installed into
201         <span class="APPLICATION">Privoxy</span> directory, including all
202         configuration and log files. To uninstall, just remove this
203         directory.</p>
204       </div>
205
206       <div class="SECT3">
207         <h3 class="SECT3"><a name="INSTALLATION-TBZ" id=
208         "INSTALLATION-TBZ">2.1.8. FreeBSD</a></h3>
209
210         <p>Privoxy is part of FreeBSD's Ports Collection, you can build and
211         install it with <tt class="LITERAL">cd /usr/ports/www/privoxy; make
212         install clean</tt>.</p>
213
214         <p>If you don't use the ports, you can fetch and install the package
215         with <tt class="LITERAL">pkg_add -r privoxy</tt>.</p>
216
217         <p>The port skeleton and the package can also be downloaded from the
218         <a href=
219         "https://sourceforge.net/project/showfiles.php?group_id=11118"
220         target="_top">File Release Page</a>, but there's no reason to use
221         them unless you're interested in the beta releases which are only
222         available there.</p>
223       </div>
224
225       <div class="SECT3">
226         <h3 class="SECT3"><a name="INSTALLATTION-GENTOO" id=
227         "INSTALLATTION-GENTOO">2.1.9. Gentoo</a></h3>
228
229         <p>Gentoo source packages (Ebuilds) for <span class=
230         "APPLICATION">Privoxy</span> are contained in the Gentoo Portage Tree
231         (they are not on the download page, but there is a Gentoo section,
232         where you can see when a new <span class="APPLICATION">Privoxy</span>
233         Version is added to the Portage Tree).</p>
234
235         <p>Before installing <span class="APPLICATION">Privoxy</span> under
236         Gentoo just do first <tt class="LITERAL">emerge --sync</tt> to get
237         the latest changes from the Portage tree. With <tt class=
238         "LITERAL">emerge privoxy</tt> you install the latest version.</p>
239
240         <p>Configuration files are in <tt class="FILENAME">/etc/privoxy</tt>,
241         the documentation is in <tt class=
242         "FILENAME">/usr/share/doc/privoxy-3.0.19</tt> and the Log directory
243         is in <tt class="FILENAME">/var/log/privoxy</tt>.</p>
244       </div>
245     </div>
246
247     <div class="SECT2">
248       <h2 class="SECT2"><a name="INSTALLATION-SOURCE" id=
249       "INSTALLATION-SOURCE">2.2. Building from Source</a></h2>
250
251       <p>The most convenient way to obtain the <span class=
252       "APPLICATION">Privoxy</span> sources is to download the source tarball
253       from our <a href=
254       "http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571"
255       target="_top">project download page</a>.</p>
256
257       <p>If you like to live on the bleeding edge and are not afraid of using
258       possibly unstable development versions, you can check out the
259       up-to-the-minute version directly from <a href=
260       "http://sourceforge.net/cvs/?group_id=11118" target="_top">the CVS
261       repository</a>.</p>
262
263       <p>To build <span class="APPLICATION">Privoxy</span> from source,
264       <a href="http://www.gnu.org/software/autoconf/autoconf.html" target=
265       "_top">autoconf</a>, <a href=
266       "http://www.gnu.org/software/make/make.html" target="_top">GNU make
267       (gmake)</a>, and, of course, a C compiler like <a href=
268       "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a> are
269       required.</p>
270
271       <p>When building from a source tarball, first unpack the source:</p>
272
273       <table border="0" bgcolor="#E0E0E0" width="100%">
274         <tr>
275           <td>
276             <pre class="SCREEN">
277  tar xzvf privoxy-3.0.19-stable-src.tar.gz
278  cd privoxy-3.0.19-stable
279 </pre>
280           </td>
281         </tr>
282       </table>
283
284       <p>For retrieving the current CVS sources, you'll need a CVS client
285       installed. Note that sources from CVS are typically development
286       quality, and may not be stable, or well tested. To download CVS source,
287       check the Sourceforge documentation, which might give commands
288       like:</p>
289
290       <table border="0" bgcolor="#E0E0E0" width="100%">
291         <tr>
292           <td>
293             <pre class="SCREEN">
294   cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
295   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
296   cd current
297 </pre>
298           </td>
299         </tr>
300       </table>
301
302       <p>This will create a directory named <tt class=
303       "FILENAME">current/</tt>, which will contain the source tree.</p>
304
305       <p>You can also check out any <span class="APPLICATION">Privoxy</span>
306       <span class="QUOTE">"branch"</span>, just exchange the <span class=
307       "APPLICATION">current</span> name with the wanted branch name (Example:
308       v_3_0_branch for the 3.0 cvs tree).</p>
309
310       <p>It is also strongly recommended to not run <span class=
311       "APPLICATION">Privoxy</span> as root. You should configure/install/run
312       <span class="APPLICATION">Privoxy</span> as an unprivileged user,
313       preferably by creating a <span class="QUOTE">"privoxy"</span> user and
314       group just for this purpose. See your local documentation for the
315       correct command line to do add new users and groups (something like
316       <b class="COMMAND">adduser</b>, but the command syntax may vary from
317       platform to platform).</p>
318
319       <p><tt class="FILENAME">/etc/passwd</tt> might then look like:</p>
320
321       <table border="0" bgcolor="#E0E0E0" width="100%">
322         <tr>
323           <td>
324             <pre class="SCREEN">
325   privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
326 </pre>
327           </td>
328         </tr>
329       </table>
330
331       <p>And then <tt class="FILENAME">/etc/group</tt>, like:</p>
332
333       <table border="0" bgcolor="#E0E0E0" width="100%">
334         <tr>
335           <td>
336             <pre class="SCREEN">
337   privoxy:*:7777:
338 </pre>
339           </td>
340         </tr>
341       </table>
342
343       <p>Some binary packages may do this for you.</p>
344
345       <p>Then, to build from either unpacked tarball or CVS source:</p>
346
347       <table border="0" bgcolor="#E0E0E0" width="100%">
348         <tr>
349           <td>
350             <pre class="SCREEN">
351  autoheader
352  autoconf
353  ./configure      # (--help to see options)
354  make             # (the make from GNU, sometimes called gmake)
355  su               # Possibly required
356  make -n install  # (to see where all the files will go)
357  make -s install  # (to really install, -s to silence output)
358 </pre>
359           </td>
360         </tr>
361       </table>
362
363       <p>Using GNU <b class="COMMAND">make</b>, you can have the first four
364       steps automatically done for you by just typing:</p>
365
366       <table border="0" bgcolor="#E0E0E0" width="100%">
367         <tr>
368           <td>
369             <pre class="SCREEN">
370   make
371 </pre>
372           </td>
373         </tr>
374       </table>
375
376       <p>in the freshly downloaded or unpacked source directory.</p>
377
378       <p>To build an executable with security enhanced features so that users
379       cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go There
380       Anyway"</span>), or alter their own configurations, <b class=
381       "COMMAND">configure</b> like this:</p>
382
383       <table border="0" bgcolor="#E0E0E0" width="100%">
384         <tr>
385           <td>
386             <pre class="SCREEN">
387  ./configure  --disable-toggle  --disable-editor  --disable-force
388 </pre>
389           </td>
390         </tr>
391       </table>
392
393       <p>Then build as above. In Privoxy 3.0.7 and later, all of these
394       options can also be disabled through the configuration file.</p>
395
396       <p><span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If
397       installing as root, the install will fail unless a non-root user or
398       group is specified, or a <tt class="LITERAL">privoxy</tt> user and
399       group already exist on the system. If a non-root user is specified, and
400       no group, then the installation will try to also use a group of the
401       same name as <span class="QUOTE">"user"</span>. If a group is specified
402       (and no user), then the support files will be installed as writable by
403       that group, and owned by the user running the installation.</p>
404
405       <p><b class="COMMAND">configure</b> accepts <tt class=
406       "LITERAL">--with-user</tt> and <tt class="LITERAL">--with-group</tt>
407       options for setting user and group ownership of the configuration files
408       (which need to be writable by the daemon). The specified <span class=
409       "emphasis"><i class="EMPHASIS">user must already exist</i></span>. When
410       starting <span class="APPLICATION">Privoxy</span>, it must be run as
411       this same user to insure write access to configuration and log
412       files!</p>
413
414       <p>Alternately, you can specify <tt class="LITERAL">user</tt> and
415       <tt class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
416       command line, but be sure both already exist:</p>
417
418       <table border="0" bgcolor="#E0E0E0" width="100%">
419         <tr>
420           <td>
421             <pre class="SCREEN">
422  make -s install  USER=privoxy GROUP=privoxy
423 </pre>
424           </td>
425         </tr>
426       </table>
427
428       <p>The default installation path for <b class="COMMAND">make
429       install</b> is <tt class="FILENAME">/usr/local</tt>. This may of course
430       be customized with the various <b class="COMMAND">./configure</b> path
431       options. If you are doing an install to anywhere besides <tt class=
432       "FILENAME">/usr/local</tt>, be sure to set the appropriate paths with
433       the correct configure options (<b class="COMMAND">./configure
434       --help</b>). Non-privileged users must of course have write access
435       permissions to wherever the target installation is going.</p>
436
437       <p>If you do install to <tt class="FILENAME">/usr/local</tt>, the
438       install will use <tt class=
439       "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
440       destinations, and the direct usage of <tt class=
441       "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not add
442       the extra <tt class="FILENAME">privoxy</tt> directory. This is for a
443       safer install, as there may already exist another program that uses a
444       file with the <span class="QUOTE">"config"</span> name, and thus makes
445       <tt class="FILENAME">/usr/local/etc</tt> cleaner.</p>
446
447       <p>If installing to <tt class="FILENAME">/usr/local</tt>, the
448       documentation will go by default to <tt class=
449       "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't exist,
450       it will then try <tt class="FILENAME">$prefix/doc</tt> and install
451       there before creating a new <tt class="FILENAME">$prefix/share/doc</tt>
452       just for <span class="APPLICATION">Privoxy</span>.</p>
453
454       <p>Again, if the installs goes to <tt class="FILENAME">/usr/local</tt>,
455       the <tt class="LITERAL">localstatedir</tt> (ie: <tt class=
456       "FILENAME">var/</tt>) will default to <tt class="FILENAME">/var</tt>
457       instead of <tt class="LITERAL">$prefix/var</tt> so the logs will go to
458       <tt class="FILENAME">/var/log/privoxy/</tt>, and the pid file will be
459       created in <tt class="FILENAME">/var/run/privoxy.pid</tt>.</p>
460
461       <p><b class="COMMAND">make install</b> will attempt to set the correct
462       values in <tt class="FILENAME">config</tt> (main configuration file).
463       You should check this to make sure all values are correct. If
464       appropriate, an init script will be installed, but it is up to the user
465       to determine how and where to start <span class=
466       "APPLICATION">Privoxy</span>. The init script should be checked for
467       correct paths and values, if anything other than a default install is
468       done.</p>
469
470       <p>If install finds previous versions of local configuration files,
471       most of these will not be overwritten, and the new ones will be
472       installed with a <span class="QUOTE">"new"</span> extension.
473       default.action and default.filter <span class="emphasis"><i class=
474       "EMPHASIS">will be overwritten</i></span>. You will then need to
475       manually update the other installed configuration files as needed. The
476       default template files <span class="emphasis"><i class=
477       "EMPHASIS">will</i></span> be overwritten. If you have customized,
478       local templates, these should be stored safely in a separate directory
479       and defined in <tt class="FILENAME">config</tt> by the <span class=
480       "QUOTE">"templdir"</span> directive. It is of course wise to always
481       back-up any important configuration files <span class="QUOTE">"just in
482       case"</span>. If a previous version of <span class=
483       "APPLICATION">Privoxy</span> is already running, you will have to
484       restart it manually.</p>
485
486       <p>For more detailed instructions on how to build Redhat RPMs, Windows
487       self-extracting installers, building on platforms with special
488       requirements etc, please consult the <a href=
489       "http://www.privoxy.org/developer-manual/newrelease.html" target=
490       "_top">developer manual</a>.</p>
491     </div>
492
493     <div class="SECT2">
494       <h2 class="SECT2"><a name="INSTALLATION-KEEPUPDATED" id=
495       "INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
496       Up-to-Date</a></h2>
497
498       <p>As user feedback comes in and development continues, we will make
499       updated versions of both the main <a href="actions-file.html">actions
500       file</a> (as a <a href=
501       "http://sourceforge.net/project/showfiles.php?group_id=11118&amp;release_id=103670"
502       target="_top">separate package</a>) and the software itself (including
503       the actions file) available for download.</p>
504
505       <p>If you wish to receive an email notification whenever we release
506       updates of <span class="APPLICATION">Privoxy</span> or the actions
507       file, <a href=
508       "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/" target=
509       "_top">subscribe to our announce mailing list</a>,
510       ijbswa-announce@lists.sourceforge.net.</p>
511
512       <p>In order not to lose your personal changes and adjustments when
513       updating to the latest <tt class="LITERAL">default.action</tt> file we
514       <span class="emphasis"><i class="EMPHASIS">strongly
515       recommend</i></span> that you use <tt class="LITERAL">user.action</tt>
516       and <tt class="LITERAL">user.filter</tt> for your local customizations
517       of <span class="APPLICATION">Privoxy</span>. See the <a href=
518       "actions-file.html">Chapter on actions files</a> for details.</p>
519     </div>
520   </div>
521
522   <div class="NAVFOOTER">
523     <hr align="left" width="100%">
524
525     <table summary="Footer navigation table" width="100%" border="0"
526     cellpadding="0" cellspacing="0">
527       <tr>
528         <td width="33%" align="left" valign="top"><a href="introduction.html"
529         accesskey="P">Prev</a></td>
530
531         <td width="34%" align="center" valign="top"><a href="index.html"
532         accesskey="H">Home</a></td>
533
534         <td width="33%" align="right" valign="top"><a href="whatsnew.html"
535         accesskey="N">Next</a></td>
536       </tr>
537
538       <tr>
539         <td width="33%" align="left" valign="top">Introduction</td>
540
541         <td width="34%" align="center" valign="top">&nbsp;</td>
542
543         <td width="33%" align="right" valign="top">What's New in this
544         Release</td>
545       </tr>
546     </table>
547   </div>
548 </body>
549 </html>