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