doc/webserver/user-manual/startup.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       Starting Privoxy
   7     </title>
   8     <meta name="GENERATOR" content=
   9     "Modular DocBook HTML Stylesheet Version 1.79">
  10     <link rel="HOME" title="Privoxy 3.0.25 User Manual" href="index.html">
  11     <link rel="PREVIOUS" title="Quickstart to Using Privoxy" href=
  12     "quickstart.html">
  13     <link rel="NEXT" title="Privoxy Configuration" href="configuration.html">
  14     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  15     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  16     <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  17   </head>
  18   <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
  19   "#840084" alink="#0000FF">
  20     <div class="NAVHEADER">
  21       <table summary="Header navigation table" width="100%" border="0"
  22       cellpadding="0" cellspacing="0">
  23         <tr>
  24           <th colspan="3" align="center">
  25             Privoxy 3.0.25 User Manual
  26           </th>
  27         </tr>
  28         <tr>
  29           <td width="10%" align="left" valign="bottom">
  30             <a href="quickstart.html" accesskey="P">Prev</a>
  31           </td>
  32           <td width="80%" align="center" valign="bottom">
  33           </td>
  34           <td width="10%" align="right" valign="bottom">
  35             <a href="configuration.html" accesskey="N">Next</a>
  36           </td>
  37         </tr>
  38       </table>
  39       <hr align="LEFT" width="100%">
  40     </div>
  41     <div class="SECT1">
  42       <h1 class="SECT1">
  43         <a name="STARTUP">5. Starting Privoxy</a>
  44       </h1>
  45       <p>
  46         Before launching <span class="APPLICATION">Privoxy</span> for the
  47         first time, you will want to configure your browser(s) to use <span
  48         class="APPLICATION">Privoxy</span> as a HTTP and HTTPS (SSL) <a href=
  49         "http://en.wikipedia.org/wiki/Proxy_server" target="_top">proxy</a>.
  50         The default is 127.0.0.1 (or localhost) for the proxy address, and
  51         port 8118 (earlier versions used port 8000). This is the one
  52         configuration step <span class="emphasis"><i class="EMPHASIS">that
  53         must be done</i></span>!
  54       </p>
  55       <p>
  56         Please note that <span class="APPLICATION">Privoxy</span> can only
  57         proxy HTTP and HTTPS traffic. It will not work with FTP or other
  58         protocols.
  59       </p>
  60       <p>
  61       </p>
  62       <div class="FIGURE">
  63         <a name="AEN667"></a>
  64         <p>
  65           <b>Figure 2. Proxy Configuration Showing Mozilla/Netscape HTTP and
  66           HTTPS (SSL) Settings</b>
  67         </p>
  68         <div class="MEDIAOBJECT">
  69           <p>
  70             <img src="proxy_setup.jpg">
  71           </p>
  72         </div>
  73       </div>
  74
  75       <p>
  76         With <span class="APPLICATION">Firefox</span>, this is typically set
  77         under:
  78       </p>
  79       <p class="LITERALLAYOUT">
  80         &nbsp;<span class="GUIBUTTON">Tools</span>&nbsp;-&gt;&nbsp;<span
  81         class="GUIBUTTON">Options</span>&nbsp;-&gt;&nbsp;&nbsp;<span class=
  82         "GUIBUTTON">Advanced</span>&nbsp;-&gt;&nbsp;<span class=
  83         "GUIBUTTON">Network</span>&nbsp;-&gt;<span class=
  84         "GUIBUTTON">Connection</span>&nbsp;-&gt;&nbsp;<span class=
  85         "GUIBUTTON">Settings</span><br>
  86          &#13;
  87       </p>
  88       <p>
  89         Or optionally on some platforms:
  90       </p>
  91       <p class="LITERALLAYOUT">
  92         &nbsp;<span class="GUIBUTTON">Edit</span>&nbsp;-&gt;&nbsp;<span
  93         class="GUIBUTTON">Preferences</span>&nbsp;-&gt;&nbsp;<span class=
  94         "GUIBUTTON">General</span>&nbsp;-&gt;&nbsp;<span class=
  95         "GUIBUTTON">Connection Settings</span>&nbsp;-&gt;&nbsp;<span class=
  96         "GUIBUTTON">Manual Proxy Configuration</span><br>
  97          &#13;
  98       </p>
  99       <p>
 100         With <span class="APPLICATION">Netscape</span> (and <span class=
 101         "APPLICATION">Mozilla</span>), this can be set under:
 102       </p>
 103       <p class="LITERALLAYOUT">
 104         &nbsp;<span class="GUIBUTTON">Edit</span>&nbsp;-&gt;&nbsp;<span
 105         class="GUIBUTTON">Preferences</span>&nbsp;-&gt;&nbsp;<span class=
 106         "GUIBUTTON">Advanced</span>&nbsp;-&gt;&nbsp;<span class=
 107         "GUIBUTTON">Proxies</span>&nbsp;-&gt;&nbsp;<span class=
 108         "GUIBUTTON">HTTP Proxy</span><br>
 109          &#13;
 110       </p>
 111       <p>
 112         For <span class="APPLICATION">Internet Explorer v.5-7</span>:
 113       </p>
 114       <p class="LITERALLAYOUT">
 115         &nbsp;<span class="GUIBUTTON">Tools</span>&nbsp;-&gt;&nbsp;<span
 116         class="GUIBUTTON">Internet Options</span>&nbsp;-&gt;&nbsp;<span
 117         class="GUIBUTTON">Connections</span>&nbsp;-&gt;&nbsp;<span class=
 118         "GUIBUTTON">LAN Settings</span>
 119       </p>
 120       <p>
 121         Then, check <span class="QUOTE">"Use Proxy"</span> and fill in the
 122         appropriate info (Address: 127.0.0.1, Port: 8118). Include HTTPS
 123         (SSL), if you want HTTPS proxy support too (sometimes labeled <span
 124         class="QUOTE">"Secure"</span>). Make sure any checkboxes like <span
 125         class="QUOTE">"Use the same proxy server for all protocols"</span> is
 126         <span class="emphasis"><i class="EMPHASIS">UNCHECKED</i></span>. You
 127         want only HTTP and HTTPS (SSL)!
 128       </p>
 129       <p>
 130       </p>
 131       <div class="FIGURE">
 132         <a name="AEN712"></a>
 133         <p>
 134           <b>Figure 3. Proxy Configuration Showing Internet Explorer HTTP and
 135           HTTPS (Secure) Settings</b>
 136         </p>
 137         <div class="MEDIAOBJECT">
 138           <p>
 139             <img src="proxy2.jpg">
 140           </p>
 141         </div>
 142       </div>
 143
 144       <p>
 145         After doing this, flush your browser's disk and memory caches to
 146         force a re-reading of all pages and to get rid of any ads that may be
 147         cached. Remove any <a href=
 148         "http://en.wikipedia.org/wiki/Browser_cookie" target=
 149         "_top">cookies</a>, if you want <span class=
 150         "APPLICATION">Privoxy</span> to manage that. You are now ready to
 151         start enjoying the benefits of using <span class=
 152         "APPLICATION">Privoxy</span>!
 153       </p>
 154       <p>
 155         <span class="APPLICATION">Privoxy</span> itself is typically started
 156         by specifying the main configuration file to be used on the command
 157         line. If no configuration file is specified on the command line,
 158         <span class="APPLICATION">Privoxy</span> will look for a file named
 159         <tt class="FILENAME">config</tt> in the current directory. Except on
 160         Win32 where it will try <tt class="FILENAME">config.txt</tt>.
 161       </p>
 162       <div class="SECT2">
 163         <h2 class="SECT2">
 164           <a name="START-DEBIAN">5.1. Debian</a>
 165         </h2>
 166         <p>
 167           We use a script. Note that Debian typically starts <span class=
 168           "APPLICATION">Privoxy</span> upon booting per default. It will use
 169           the file <tt class="FILENAME">/etc/privoxy/config</tt> as its main
 170           configuration file.
 171         </p>
 172         <p>
 173         </p>
 174         <table border="0" bgcolor="#E0E0E0" width="100%">
 175           <tr>
 176             <td>
 177 <pre class="SCREEN">
 178  # /etc/init.d/privoxy start
 179 </pre>
 180             </td>
 181           </tr>
 182         </table>
 183       </div>
 184       <div class="SECT2">
 185         <h2 class="SECT2">
 186           <a name="START-FREEBSD">5.2. FreeBSD and ElectroBSD</a>
 187         </h2>
 188         <p>
 189           To start <span class="APPLICATION">Privoxy</span> upon booting, add
 190           "privoxy_enable='YES'" to <tt class="FILENAME">/etc/rc.conf</tt>.
 191           <span class="APPLICATION">Privoxy</span> will use <tt class=
 192           "FILENAME">/usr/local/etc/privoxy/config</tt> as its main
 193           configuration file.
 194         </p>
 195         <p>
 196           If you installed <span class="APPLICATION">Privoxy</span> into a
 197           jail, the paths above are relative to the jail root.
 198         </p>
 199         <p>
 200           To start <span class="APPLICATION">Privoxy</span> manually, run:
 201         </p>
 202         <p>
 203         </p>
 204         <table border="0" bgcolor="#E0E0E0" width="100%">
 205           <tr>
 206             <td>
 207 <pre class="SCREEN">
 208  # service privoxy onestart
 209 </pre>
 210             </td>
 211           </tr>
 212         </table>
 213       </div>
 214       <div class="SECT2">
 215         <h2 class="SECT2">
 216           <a name="START-WINDOWS">5.3. Windows</a>
 217         </h2>
 218         <p>
 219           Click on the <span class="APPLICATION">Privoxy</span> Icon to start
 220           <span class="APPLICATION">Privoxy</span>. If no configuration file
 221           is specified on the command line, <span class=
 222           "APPLICATION">Privoxy</span> will look for a file named <tt class=
 223           "FILENAME">config.txt</tt>. Note that Windows will automatically
 224           start <span class="APPLICATION">Privoxy</span> when the system
 225           starts if you chose that option when installing.
 226         </p>
 227         <p>
 228           <span class="APPLICATION">Privoxy</span> can run with full Windows
 229           service functionality. On Windows only, the <span class=
 230           "APPLICATION">Privoxy</span> program has two new command line
 231           arguments to install and uninstall <span class=
 232           "APPLICATION">Privoxy</span> as a service. See the <a href=
 233           "installation.html#INSTALLATION-PACK-WIN">Windows Installation
 234           instructions</a> for details.
 235         </p>
 236       </div>
 237       <div class="SECT2">
 238         <h2 class="SECT2">
 239           <a name="START-UNICES">5.4. Generic instructions for Unix derivates
 240           (Solaris, NetBSD, HP-UX etc.)</a>
 241         </h2>
 242         <p>
 243           Example Unix startup command:
 244         </p>
 245         <p>
 246         </p>
 247         <table border="0" bgcolor="#E0E0E0" width="100%">
 248           <tr>
 249             <td>
 250 <pre class="SCREEN">
 251  # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
 252 </pre>
 253             </td>
 254           </tr>
 255         </table>
 256
 257         <p>
 258           Note that if you installed <span class="APPLICATION">Privoxy</span>
 259           through a package manager, the package will probably contain a
 260           platform-specific script or configuration file to start <span
 261           class="APPLICATION">Privoxy</span> upon boot.
 262         </p>
 263       </div>
 264       <div class="SECT2">
 265         <h2 class="SECT2">
 266           <a name="START-OS2">5.5. OS/2</a>
 267         </h2>
 268         <p>
 269           During installation, <span class="APPLICATION">Privoxy</span> is
 270           configured to start automatically when the system restarts. You can
 271           start it manually by double-clicking on the <span class=
 272           "APPLICATION">Privoxy</span> icon in the <span class=
 273           "APPLICATION">Privoxy</span> folder.
 274         </p>
 275       </div>
 276       <div class="SECT2">
 277         <h2 class="SECT2">
 278           <a name="START-MACOSX">5.6. Mac OS X</a>
 279         </h2>
 280         <p>
 281           The privoxy service will automatically start after a successful
 282           installation (and thereafter every time your computer starts up)
 283           however you will need to configure your web browser(s) to use it.
 284           To do so, configure them to use a proxy for HTTP and HTTPS at the
 285           address 127.0.0.1:8118.
 286         </p>
 287         <p>
 288           To prevent the privoxy service from automatically starting when
 289           your computer starts up, remove or rename the file <tt class=
 290           "LITERAL">/Library/LaunchDaemons/org.ijbswa.privoxy.plist</tt> (on
 291           OS X 10.5 and higher) or the folder named <tt class=
 292           "LITERAL">/Library/StartupItems/Privoxy</tt> (on OS X 10.4
 293           'Tiger').
 294         </p>
 295         <p>
 296           To manually start or stop the privoxy service, use the scripts
 297           startPrivoxy.sh and stopPrivoxy.sh supplied in
 298           /Applications/Privoxy. They must be run from an administrator
 299           account, using sudo.
 300         </p>
 301       </div>
 302       <div class="SECT2">
 303         <h2 class="SECT2">
 304           <a name="CMDOPTIONS">5.7. Command Line Options</a>
 305         </h2>
 306         <p>
 307           <span class="APPLICATION">Privoxy</span> may be invoked with the
 308           following command-line options:
 309         </p>
 310         <p>
 311         </p>
 312         <ul>
 313           <li>
 314             <p>
 315               <span class="emphasis"><i class=
 316               "EMPHASIS">--config-test</i></span>
 317             </p>
 318             <p>
 319               Exit after loading the configuration files before binding to
 320               the listen address. The exit code signals whether or not the
 321               configuration files have been successfully loaded.
 322             </p>
 323             <p>
 324               If the exit code is 1, at least one of the configuration files
 325               is invalid, if it is 0, all the configuration files have been
 326               successfully loaded (but may still contain errors that can
 327               currently only be detected at run time).
 328             </p>
 329             <p>
 330               This option doesn't affect the log setting, combination with
 331               <span class="emphasis"><i class=
 332               "EMPHASIS">--no-daemon</i></span> is recommended if a
 333               configured log file shouldn't be used.
 334             </p>
 335           </li>
 336           <li>
 337             <p>
 338               <span class="emphasis"><i class="EMPHASIS">--version</i></span>
 339             </p>
 340             <p>
 341               Print version info and exit. Unix only.
 342             </p>
 343           </li>
 344           <li>
 345             <p>
 346               <span class="emphasis"><i class="EMPHASIS">--help</i></span>
 347             </p>
 348             <p>
 349               Print short usage info and exit. Unix only.
 350             </p>
 351           </li>
 352           <li>
 353             <p>
 354               <span class="emphasis"><i class=
 355               "EMPHASIS">--no-daemon</i></span>
 356             </p>
 357             <p>
 358               Don't become a daemon, i.e. don't fork and become process group
 359               leader, and don't detach from controlling tty. Unix only.
 360             </p>
 361           </li>
 362           <li>
 363             <p>
 364               <span class="emphasis"><i class="EMPHASIS">--pidfile
 365               FILE</i></span>
 366             </p>
 367             <p>
 368               On startup, write the process ID to <span class="emphasis"><i
 369               class="EMPHASIS">FILE</i></span>. Delete the <span class=
 370               "emphasis"><i class="EMPHASIS">FILE</i></span> on exit. Failure
 371               to create or delete the <span class="emphasis"><i class=
 372               "EMPHASIS">FILE</i></span> is non-fatal. If no <span class=
 373               "emphasis"><i class="EMPHASIS">FILE</i></span> option is given,
 374               no PID file will be used. Unix only.
 375             </p>
 376           </li>
 377           <li>
 378             <p>
 379               <span class="emphasis"><i class="EMPHASIS">--user
 380               USER[.GROUP]</i></span>
 381             </p>
 382             <p>
 383               After (optionally) writing the PID file, assume the user ID of
 384               <span class="emphasis"><i class="EMPHASIS">USER</i></span>, and
 385               if included the GID of GROUP. Exit if the privileges are not
 386               sufficient to do so. Unix only.
 387             </p>
 388           </li>
 389           <li>
 390             <p>
 391               <span class="emphasis"><i class="EMPHASIS">--chroot</i></span>
 392             </p>
 393             <p>
 394               Before changing to the user ID given in the <span class=
 395               "emphasis"><i class="EMPHASIS">--user</i></span> option, chroot
 396               to that user's home directory, i.e. make the kernel pretend to
 397               the <span class="APPLICATION">Privoxy</span> process that the
 398               directory tree starts there. If set up carefully, this can
 399               limit the impact of possible vulnerabilities in <span class=
 400               "APPLICATION">Privoxy</span> to the files contained in that
 401               hierarchy. Unix only.
 402             </p>
 403           </li>
 404           <li>
 405             <p>
 406               <span class="emphasis"><i class=
 407               "EMPHASIS">--pre-chroot-nslookup hostname</i></span>
 408             </p>
 409             <p>
 410               Specifies a hostname (for example www.privoxy.org) to look up
 411               before doing a chroot. On some systems, initializing the
 412               resolver library involves reading config files from /etc and/or
 413               loading additional shared libraries from /lib. On these
 414               systems, doing a hostname lookup before the chroot reduces the
 415               number of files that must be copied into the chroot tree.
 416             </p>
 417             <p>
 418               For fastest startup speed, a good value is a hostname that is
 419               not in /etc/hosts but that your local name server (listed in
 420               /etc/resolv.conf) can resolve without recursion (that is,
 421               without having to ask any other name servers). The hostname
 422               need not exist, but if it doesn't, an error message (which can
 423               be ignored) will be output.
 424             </p>
 425           </li>
 426           <li>
 427             <p>
 428               <span class="emphasis"><i class=
 429               "EMPHASIS">configfile</i></span>
 430             </p>
 431             <p>
 432               If no <span class="emphasis"><i class=
 433               "EMPHASIS">configfile</i></span> is included on the command
 434               line, <span class="APPLICATION">Privoxy</span> will look for a
 435               file named <span class="QUOTE">"config"</span> in the current
 436               directory (except on Win32 where it will look for <span class=
 437               "QUOTE">"config.txt"</span> instead). Specify full path to
 438               avoid confusion. If no config file is found, <span class=
 439               "APPLICATION">Privoxy</span> will fail to start.
 440             </p>
 441           </li>
 442         </ul>
 443
 444         <p>
 445           On <span class="APPLICATION">MS Windows</span> only there are two
 446           additional command-line options to allow <span class=
 447           "APPLICATION">Privoxy</span> to install and run as a <span class=
 448           "emphasis"><i class="EMPHASIS">service</i></span>. See the <a href=
 449           "installation.html#INSTALLATION-PACK-WIN">Window Installation
 450           section</a> for details.
 451         </p>
 452       </div>
 453     </div>
 454     <div class="NAVFOOTER">
 455       <hr align="LEFT" width="100%">
 456       <table summary="Footer navigation table" width="100%" border="0"
 457       cellpadding="0" cellspacing="0">
 458         <tr>
 459           <td width="33%" align="left" valign="top">
 460             <a href="quickstart.html" accesskey="P">Prev</a>
 461           </td>
 462           <td width="34%" align="center" valign="top">
 463             <a href="index.html" accesskey="H">Home</a>
 464           </td>
 465           <td width="33%" align="right" valign="top">
 466             <a href="configuration.html" accesskey="N">Next</a>
 467           </td>
 468         </tr>
 469         <tr>
 470           <td width="33%" align="left" valign="top">
 471             Quickstart to Using Privoxy
 472           </td>
 473           <td width="34%" align="center" valign="top">
 474             &nbsp;
 475           </td>
 476           <td width="33%" align="right" valign="top">
 477             Privoxy Configuration
 478           </td>
 479         </tr>
 480       </table>
 481     </div>
 482   </body>
 483 </html>
 484