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