cfaa259d987224c58dd53f69c951d71de187a243
[privoxy.git] / 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