Rebuild HTML docs 3.0.26 UNRELEASED
[privoxy.git] / doc / webserver / user-manual / installation.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
3 <html>
4   <head>
5     <title>
6       Installation
7     </title>
8     <meta name="GENERATOR" content=
9     "Modular DocBook HTML Stylesheet Version 1.79">
10     <link rel="HOME" title="Privoxy 3.0.26 User Manual" href="index.html">
11     <link rel="PREVIOUS" title="Introduction" href="introduction.html">
12     <link rel="NEXT" title="What's New in this Release" href="whatsnew.html">
13     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
14     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
15     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
16   </head>
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">
24             Privoxy 3.0.26 User Manual
25           </th>
26         </tr>
27         <tr>
28           <td width="10%" align="left" valign="bottom">
29             <a href="introduction.html" accesskey="P">Prev</a>
30           </td>
31           <td width="80%" align="center" valign="bottom">
32           </td>
33           <td width="10%" align="right" valign="bottom">
34             <a href="whatsnew.html" accesskey="N">Next</a>
35           </td>
36         </tr>
37       </table>
38       <hr align="LEFT" width="100%">
39     </div>
40     <div class="SECT1">
41       <h1 class="SECT1">
42         <a name="INSTALLATION">2. Installation</a>
43       </h1>
44       <p>
45         <span class="APPLICATION">Privoxy</span> is available both in
46         convenient pre-compiled packages for a wide range of operating
47         systems, and as raw source code. For most users, we recommend using
48         the packages, which can be downloaded from our <a href=
49         "https://sourceforge.net/projects/ijbswa/" target="_top">Privoxy
50         Project Page</a>.
51       </p>
52       <p>
53         Note: On some platforms, the installer may remove previously
54         installed versions, if found. (See below for your platform). In any
55         case <span class="emphasis"><i class="EMPHASIS">be sure to backup
56         your old configuration if it is valuable to you.</i></span> See the
57         <a href="whatsnew.html#UPGRADERSNOTE">note to upgraders</a> section
58         below.
59       </p>
60       <div class="SECT2">
61         <h2 class="SECT2">
62           <a name="INSTALLATION-PACKAGES">2.1. Binary Packages</a>
63         </h2>
64         <p>
65           How to install the binary packages depends on your operating
66           system:
67         </p>
68         <div class="SECT3">
69           <h3 class="SECT3">
70             <a name="INSTALLATION-DEB">2.1.1. Debian and Ubuntu</a>
71           </h3>
72           <p>
73             DEBs can be installed with <tt class="LITERAL">apt-get install
74             privoxy</tt>, and will use <tt class="FILENAME">/etc/privoxy</tt>
75             for the location of configuration files.
76           </p>
77         </div>
78         <div class="SECT3">
79           <h3 class="SECT3">
80             <a name="INSTALLATION-PACK-WIN">2.1.2. Windows</a>
81           </h3>
82           <p>
83             Just double-click the installer, which will guide you through the
84             installation process. You will find the configuration files in
85             the same directory as you installed <span class=
86             "APPLICATION">Privoxy</span> in.
87           </p>
88           <p>
89             Version 3.0.5 beta introduced full <span class=
90             "APPLICATION">Windows</span> service functionality. On Windows
91             only, the <span class="APPLICATION">Privoxy</span> program has
92             two new command line arguments to install and uninstall <span
93             class="APPLICATION">Privoxy</span> as a <span class="emphasis"><i
94             class="EMPHASIS">service</i></span>.
95           </p>
96           <div class="VARIABLELIST">
97             <dl>
98               <dt>
99                 Arguments:
100               </dt>
101               <dd>
102                 <p>
103                   <tt class="REPLACEABLE"><i>--install</i></tt>[:<tt class=
104                   "REPLACEABLE"><i>service_name</i></tt>]
105                 </p>
106                 <p>
107                   <tt class="REPLACEABLE"><i>--uninstall</i></tt>[:<tt class=
108                   "REPLACEABLE"><i>service_name</i></tt>]
109                 </p>
110               </dd>
111             </dl>
112           </div>
113           <p>
114             After invoking <span class="APPLICATION">Privoxy</span> with <b
115             class="COMMAND">--install</b>, you will need to bring up the
116             <span class="APPLICATION">Windows</span> service console to
117             assign the user you want <span class="APPLICATION">Privoxy</span>
118             to run under, and whether or not you want it to run whenever the
119             system starts. You can start the <span class=
120             "APPLICATION">Windows</span> services console with the following
121             command: <b class="COMMAND">services.msc</b>. If you do not take
122             the manual step of modifying <span class=
123             "APPLICATION">Privoxy's</span> service settings, it will not
124             start. Note too that you will need to give Privoxy a user account
125             that actually exists, or it will not be permitted to write to its
126             log and configuration files.
127           </p>
128         </div>
129         <div class="SECT3">
130           <h3 class="SECT3">
131             <a name="INSTALLATION-OS2">2.1.3. OS/2</a>
132           </h3>
133           <p>
134             First, make sure that no previous installations of <span class=
135             "APPLICATION">Junkbuster</span> and / or <span class=
136             "APPLICATION">Privoxy</span> are left on your system. Check that
137             no <span class="APPLICATION">Junkbuster</span> or <span class=
138             "APPLICATION">Privoxy</span> objects are in your startup
139             folder.&#13;
140           </p>
141           <p>
142             Then, just double-click the WarpIN self-installing archive, which
143             will guide you through the installation process. A shadow of the
144             <span class="APPLICATION">Privoxy</span> executable will be
145             placed in your startup folder so it will start automatically
146             whenever OS/2 starts.
147           </p>
148           <p>
149             The directory you choose to install <span class=
150             "APPLICATION">Privoxy</span> into will contain all of the
151             configuration files.
152           </p>
153         </div>
154         <div class="SECT3">
155           <h3 class="SECT3">
156             <a name="INSTALLATION-MAC">2.1.4. Mac OS X</a>
157           </h3>
158           <p>
159             Installation instructions for the OS X platform depend upon
160             whether you downloaded a ready-built installation package (.pkg
161             or .mpkg) or have downloaded the source code.
162           </p>
163         </div>
164         <div class="SECT3">
165           <h4 class="SECT3">
166             <a name="OS-X-INSTALL-FROM-PACKAGE">2.1.5. Installation from
167             ready-built package</a>
168           </h4>
169           <p>
170             The downloaded file will either be a .pkg (for OS X 10.5 upwards)
171             or a bzipped .mpkg file (for OS X 10.4). The former can be
172             double-clicked as is and the installation will start;
173             double-clicking the latter will unzip the .mpkg file which can
174             then be double-clicked to commence the installation.
175           </p>
176           <p>
177             The privoxy service will automatically start after a successful
178             installation (and thereafter every time your computer starts up)
179             however you will need to configure your web browser(s) to use it.
180             To do so, configure them to use a proxy for HTTP and HTTPS at the
181             address 127.0.0.1:8118.
182           </p>
183           <p>
184             To prevent the privoxy service from automatically starting when
185             your computer starts up, remove or rename the file <tt class=
186             "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt>
187             (on OS X 10.5 and higher) or the folder named <tt class=
188             "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
189             'Tiger').
190           </p>
191           <p>
192             To manually start or stop the privoxy service, use the scripts
193             startPrivoxy.sh and stopPrivoxy.sh supplied in
194             /Applications/Privoxy. They must be run from an administrator
195             account, using sudo.
196           </p>
197           <p>
198             To uninstall, run /Applications/Privoxy/uninstall.command as sudo
199             from an administrator account.
200           </p>
201         </div>
202         <div class="SECT3">
203           <h4 class="SECT3">
204             <a name="OS-X-INSTALL-FROM-SOURCE">2.1.6. Installation from
205             source</a>
206           </h4>
207           <p>
208             To build and install the Privoxy source code on OS X you will
209             need to obtain the macsetup module from the Privoxy Sourceforge
210             CVS repository (refer to Sourceforge help for details of how to
211             set up a CVS client to have read-only access to the repository).
212             This module contains scripts that leverage the usual open-source
213             tools (available as part of Apple's free of charge Xcode
214             distribution or via the usual open-source software package
215             managers for OS X (MacPorts, Homebrew, Fink etc.) to build and
216             then install the privoxy binary and associated files. The
217             macsetup module's README file contains complete instructions for
218             its use.
219           </p>
220           <p>
221             The privoxy service will automatically start after a successful
222             installation (and thereafter every time your computer starts up)
223             however you will need to configure your web browser(s) to use it.
224             To do so, configure them to use a proxy for HTTP and HTTPS at the
225             address 127.0.0.1:8118.
226           </p>
227           <p>
228             To prevent the privoxy service from automatically starting when
229             your computer starts up, remove or rename the file <tt class=
230             "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt>
231             (on OS X 10.5 and higher) or the folder named <tt class=
232             "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
233             'Tiger').
234           </p>
235           <p>
236             To manually start or stop the privoxy service, use the Privoxy
237             Utility for Mac OS X (also part of the macsetup module). This
238             application can start and stop the privoxy service and display
239             its log and configuration files.
240           </p>
241           <p>
242             To uninstall, run the macsetup module's uninstall.sh as sudo from
243             an administrator account.
244           </p>
245         </div>
246         <div class="SECT3">
247           <h3 class="SECT3">
248             <a name="INSTALLATION-FREEBSD">2.1.7. FreeBSD</a>
249           </h3>
250           <p>
251             Privoxy is part of FreeBSD's Ports Collection, you can build and
252             install it with <tt class="LITERAL">cd /usr/ports/www/privoxy;
253             make install clean</tt>.
254           </p>
255         </div>
256       </div>
257       <div class="SECT2">
258         <h2 class="SECT2">
259           <a name="INSTALLATION-SOURCE">2.2. Building from Source</a>
260         </h2>
261         <p>
262           The most convenient way to obtain the <span class=
263           "APPLICATION">Privoxy</span> sources is to download the source
264           tarball from our <a href=
265           "https://sourceforge.net/projects/ijbswa/files/Sources/" target=
266           "_top">project download page</a>.
267         </p>
268         <p>
269           If you like to live on the bleeding edge and are not afraid of
270           using possibly unstable development versions, you can check out the
271           up-to-the-minute version directly from <a href=
272           "https://sourceforge.net/p/ijbswa/code/?source=navbar" target=
273           "_top">the CVS repository</a>.
274         </p>
275         <p>
276           To build <span class="APPLICATION">Privoxy</span> from source, <a
277           href="http://www.gnu.org/software/autoconf/autoconf.html" target=
278           "_top">autoconf</a>, <a href=
279           "http://www.gnu.org/software/make/make.html" target="_top">GNU make
280           (gmake)</a>, and, of course, a C compiler like <a href=
281           "http://www.gnu.org/software/gcc/gcc.html" target="_top">gcc</a>
282           are required.
283         </p>
284         <p>
285           When building from a source tarball, first unpack the source:
286         </p>
287         <p>
288         </p>
289         <table border="0" bgcolor="#E0E0E0" width="100%">
290           <tr>
291             <td>
292 <pre class="SCREEN">
293  tar xzvf privoxy-3.0.26-beta-src.tar.gz
294  cd privoxy-3.0.26-beta
295 </pre>
296             </td>
297           </tr>
298         </table>
299
300         <p>
301           For retrieving the current CVS sources, you'll need a CVS client
302           installed. Note that sources from CVS are typically development
303           quality, and may not be stable, or well tested. To download CVS
304           source, check the Sourceforge documentation, which might give
305           commands like:
306         </p>
307         <p>
308         </p>
309         <table border="0" bgcolor="#E0E0E0" width="100%">
310           <tr>
311             <td>
312 <pre class="SCREEN">
313   cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
314   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
315   cd current
316 </pre>
317             </td>
318           </tr>
319         </table>
320
321         <p>
322           This will create a directory named <tt class=
323           "FILENAME">current/</tt>, which will contain the source tree.
324         </p>
325         <p>
326           You can also check out any <span class="APPLICATION">Privoxy</span>
327           <span class="QUOTE">"branch"</span>, just exchange the <span class=
328           "APPLICATION">current</span> name with the wanted branch name
329           (Example: v_3_0_branch for the 3.0 cvs tree).
330         </p>
331         <p>
332           It is also strongly recommended to not run <span class=
333           "APPLICATION">Privoxy</span> as root. You should
334           configure/install/run <span class="APPLICATION">Privoxy</span> as
335           an unprivileged user, preferably by creating a <span class=
336           "QUOTE">"privoxy"</span> user and group just for this purpose. See
337           your local documentation for the correct command line to do add new
338           users and groups (something like <b class="COMMAND">adduser</b>,
339           but the command syntax may vary from platform to platform).
340         </p>
341         <p>
342           <tt class="FILENAME">/etc/passwd</tt> might then look like:
343         </p>
344         <p>
345         </p>
346         <table border="0" bgcolor="#E0E0E0" width="100%">
347           <tr>
348             <td>
349 <pre class="SCREEN">
350   privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell
351 </pre>
352             </td>
353           </tr>
354         </table>
355
356         <p>
357           And then <tt class="FILENAME">/etc/group</tt>, like:
358         </p>
359         <p>
360         </p>
361         <table border="0" bgcolor="#E0E0E0" width="100%">
362           <tr>
363             <td>
364 <pre class="SCREEN">
365   privoxy:*:7777:
366 </pre>
367             </td>
368           </tr>
369         </table>
370
371         <p>
372           Some binary packages may do this for you.
373         </p>
374         <p>
375           Then, to build from either unpacked tarball or CVS source:
376         </p>
377         <p>
378         </p>
379         <table border="0" bgcolor="#E0E0E0" width="100%">
380           <tr>
381             <td>
382 <pre class="SCREEN">
383  autoheader
384  autoconf
385  ./configure      # (--help to see options)
386  make             # (the make from GNU, sometimes called gmake)
387  su               # Possibly required
388  make -n install  # (to see where all the files will go)
389  make -s install  # (to really install, -s to silence output)
390 </pre>
391             </td>
392           </tr>
393         </table>
394
395         <p>
396           Using GNU <b class="COMMAND">make</b>, you can have the first four
397           steps automatically done for you by just typing:
398         </p>
399         <p>
400         </p>
401         <table border="0" bgcolor="#E0E0E0" width="100%">
402           <tr>
403             <td>
404 <pre class="SCREEN">
405   make
406 </pre>
407             </td>
408           </tr>
409         </table>
410
411         <p>
412           in the freshly downloaded or unpacked source directory.
413         </p>
414         <p>
415           To build an executable with security enhanced features so that
416           users cannot easily bypass the proxy (e.g. <span class="QUOTE">"Go
417           There Anyway"</span>), or alter their own configurations, <b class=
418           "COMMAND">configure</b> like this:
419         </p>
420         <p>
421         </p>
422         <table border="0" bgcolor="#E0E0E0" width="100%">
423           <tr>
424             <td>
425 <pre class="SCREEN">
426  ./configure  --disable-toggle  --disable-editor  --disable-force
427 </pre>
428             </td>
429           </tr>
430         </table>
431
432         <p>
433           Note that all of these options can also be disabled through the
434           configuration file.
435         </p>
436         <p>
437           <span class="emphasis"><i class="EMPHASIS">WARNING:</i></span> If
438           installing as root, the install will fail unless a non-root user or
439           group is specified, or a <tt class="LITERAL">privoxy</tt> user and
440           group already exist on the system. If a non-root user is specified,
441           and no group, then the installation will try to also use a group of
442           the same name as <span class="QUOTE">"user"</span>. If a group is
443           specified (and no user), then the support files will be installed
444           as writable by that group, and owned by the user running the
445           installation.
446         </p>
447         <p>
448           <b class="COMMAND">configure</b> accepts <tt class=
449           "LITERAL">--with-user</tt> and <tt class=
450           "LITERAL">--with-group</tt> options for setting user and group
451           ownership of the configuration files (which need to be writable by
452           the daemon). The specified <span class="emphasis"><i class=
453           "EMPHASIS">user must already exist</i></span>. When starting <span
454           class="APPLICATION">Privoxy</span>, it must be run as this same
455           user to insure write access to configuration and log files!
456         </p>
457         <p>
458           Alternately, you can specify <tt class="LITERAL">user</tt> and <tt
459           class="LITERAL">group</tt> on the <b class="COMMAND">make</b>
460           command line, but be sure both already exist:
461         </p>
462         <p>
463         </p>
464         <table border="0" bgcolor="#E0E0E0" width="100%">
465           <tr>
466             <td>
467 <pre class="SCREEN">
468  make -s install  USER=privoxy GROUP=privoxy
469 </pre>
470             </td>
471           </tr>
472         </table>
473
474         <p>
475           The default installation path for <b class="COMMAND">make
476           install</b> is <tt class="FILENAME">/usr/local</tt>. This may of
477           course be customized with the various <b class=
478           "COMMAND">./configure</b> path options. If you are doing an install
479           to anywhere besides <tt class="FILENAME">/usr/local</tt>, be sure
480           to set the appropriate paths with the correct configure options (<b
481           class="COMMAND">./configure --help</b>). Non-privileged users must
482           of course have write access permissions to wherever the target
483           installation is going.
484         </p>
485         <p>
486           If you do install to <tt class="FILENAME">/usr/local</tt>, the
487           install will use <tt class=
488           "LITERAL">sysconfdir=$prefix/etc/privoxy</tt> by default. All other
489           destinations, and the direct usage of <tt class=
490           "LITERAL">--sysconfdir</tt> flag behave like normal, i.e. will not
491           add the extra <tt class="FILENAME">privoxy</tt> directory. This is
492           for a safer install, as there may already exist another program
493           that uses a file with the <span class="QUOTE">"config"</span> name,
494           and thus makes <tt class="FILENAME">/usr/local/etc</tt> cleaner.
495         </p>
496         <p>
497           If installing to <tt class="FILENAME">/usr/local</tt>, the
498           documentation will go by default to <tt class=
499           "FILENAME">$prefix/share/doc</tt>. But if this directory doesn't
500           exist, it will then try <tt class="FILENAME">$prefix/doc</tt> and
501           install there before creating a new <tt class=
502           "FILENAME">$prefix/share/doc</tt> just for <span class=
503           "APPLICATION">Privoxy</span>.
504         </p>
505         <p>
506           Again, if the installs goes to <tt class=
507           "FILENAME">/usr/local</tt>, the <tt class=
508           "LITERAL">localstatedir</tt> (ie: <tt class="FILENAME">var/</tt>)
509           will default to <tt class="FILENAME">/var</tt> instead of <tt
510           class="LITERAL">$prefix/var</tt> so the logs will go to <tt class=
511           "FILENAME">/var/log/privoxy/</tt>, and the pid file will be created
512           in <tt class="FILENAME">/var/run/privoxy.pid</tt>.
513         </p>
514         <p>
515           <b class="COMMAND">make install</b> will attempt to set the correct
516           values in <tt class="FILENAME">config</tt> (main configuration
517           file). You should check this to make sure all values are correct.
518           If appropriate, an init script will be installed, but it is up to
519           the user to determine how and where to start <span class=
520           "APPLICATION">Privoxy</span>. The init script should be checked for
521           correct paths and values, if anything other than a default install
522           is done.
523         </p>
524         <p>
525           If install finds previous versions of local configuration files,
526           most of these will not be overwritten, and the new ones will be
527           installed with a <span class="QUOTE">"new"</span> extension.
528           default.action and default.filter <span class="emphasis"><i class=
529           "EMPHASIS">will be overwritten</i></span>. You will then need to
530           manually update the other installed configuration files as needed.
531           The default template files <span class="emphasis"><i class=
532           "EMPHASIS">will</i></span> be overwritten. If you have customized,
533           local templates, these should be stored safely in a separate
534           directory and defined in <tt class="FILENAME">config</tt> by the
535           <span class="QUOTE">"templdir"</span> directive. It is of course
536           wise to always back-up any important configuration files <span
537           class="QUOTE">"just in case"</span>. If a previous version of <span
538           class="APPLICATION">Privoxy</span> is already running, you will
539           have to restart it manually.
540         </p>
541         <p>
542           For more detailed instructions on how to build Redhat RPMs, Windows
543           self-extracting installers, building on platforms with special
544           requirements etc, please consult the <a href=
545           "https://www.privoxy.org/developer-manual/newrelease.html" target=
546           "_top">developer manual</a>.
547         </p>
548       </div>
549       <div class="SECT2">
550         <h2 class="SECT2">
551           <a name="INSTALLATION-KEEPUPDATED">2.3. Keeping your Installation
552           Up-to-Date</a>
553         </h2>
554         <p>
555           If you wish to receive an email notification whenever we release
556           updates of <span class="APPLICATION">Privoxy</span> or the actions
557           file, <a href=
558           "https://lists.privoxy.org/mailman/listinfo/privoxy-announce"
559           target="_top">subscribe to our announce mailing list</a>,
560           privoxy-announce@lists.privoxy.org.
561         </p>
562         <p>
563           In order not to lose your personal changes and adjustments when
564           updating to the latest <tt class="LITERAL">default.action</tt> file
565           we <span class="emphasis"><i class="EMPHASIS">strongly
566           recommend</i></span> that you use <tt class=
567           "LITERAL">user.action</tt> and <tt class="LITERAL">user.filter</tt>
568           for your local customizations of <span class=
569           "APPLICATION">Privoxy</span>. See the <a href=
570           "actions-file.html">Chapter on actions files</a> for details.
571         </p>
572       </div>
573     </div>
574     <div class="NAVFOOTER">
575       <hr align="LEFT" width="100%">
576       <table summary="Footer navigation table" width="100%" border="0"
577       cellpadding="0" cellspacing="0">
578         <tr>
579           <td width="33%" align="left" valign="top">
580             <a href="introduction.html" accesskey="P">Prev</a>
581           </td>
582           <td width="34%" align="center" valign="top">
583             <a href="index.html" accesskey="H">Home</a>
584           </td>
585           <td width="33%" align="right" valign="top">
586             <a href="whatsnew.html" accesskey="N">Next</a>
587           </td>
588         </tr>
589         <tr>
590           <td width="33%" align="left" valign="top">
591             Introduction
592           </td>
593           <td width="34%" align="center" valign="top">
594             &nbsp;
595           </td>
596           <td width="33%" align="right" valign="top">
597             What's New in this Release
598           </td>
599         </tr>
600       </table>
601     </div>
602   </body>
603 </html>
604