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