1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10 TITLE="Privoxy 3.0.27 User Manual"
11 HREF="index.html"><LINK
14 HREF="introduction.html"><LINK
16 TITLE="What's New in this Release"
17 HREF="whatsnew.html"><LINK
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
24 <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
36 SUMMARY="Header navigation table"
45 >Privoxy 3.0.27 User Manual</TH
53 HREF="introduction.html"
88 > is available both in convenient pre-compiled
89 packages for a wide range of operating systems, and as raw source code.
90 For most users, we recommend using the packages, which can be downloaded from our
92 HREF="https://sourceforge.net/projects/ijbswa/"
99 On some platforms, the installer may remove previously installed versions, if
100 found. (See below for your platform). In any case <SPAN
105 your old configuration if it is valuable to you.</I
108 HREF="whatsnew.html#UPGRADERSNOTE"
109 >note to upgraders</A
116 NAME="INSTALLATION-PACKAGES"
117 >2.1. Binary Packages</A
120 >How to install the binary packages depends on your operating system:</P
126 NAME="INSTALLATION-DEB"
127 >2.1.1. Debian and Ubuntu</A
130 > DEBs can be installed with <TT
132 >apt-get install privoxy</TT
137 > for the location of
138 configuration files.</P
145 NAME="INSTALLATION-PACK-WIN"
149 > Just double-click the installer, which will guide you through
150 the installation process. You will find the configuration files
151 in the same directory as you installed <SPAN
156 > Version 3.0.5 beta introduced full <SPAN
160 functionality. On Windows only, the <SPAN
164 program has two new command line arguments to install and uninstall
213 > After invoking <SPAN
220 >, you will need to bring up the
224 > service console to assign the user you
228 > to run under, and whether or not you
229 want it to run whenever the system starts. You can start the
233 > services console with the following
237 >. If you do not take the manual step
241 > service settings, it will
242 not start. Note too that you will need to give Privoxy a user account that
243 actually exists, or it will not be permitted to
244 write to its log and configuration files.</P
251 NAME="INSTALLATION-OS2"
255 > First, make sure that no previous installations of
264 system. Check that no <SPAN
272 your startup folder.</P
274 > Then, just double-click the WarpIN self-installing archive, which will
275 guide you through the installation process. A shadow of the
279 > executable will be placed in your
280 startup folder so it will start automatically whenever OS/2 starts.</P
282 > The directory you choose to install <SPAN
286 into will contain all of the configuration files.</P
293 NAME="INSTALLATION-MAC"
297 > Installation instructions for the OS X platform depend upon whether
298 you downloaded a ready-built installation package (.pkg or .mpkg) or have
299 downloaded the source code.</P
306 NAME="OS-X-INSTALL-FROM-PACKAGE"
307 >2.1.5. Installation from ready-built package</A
310 > The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped
311 .mpkg file (for OS X 10.4). The former can be double-clicked as is and the
312 installation will start; double-clicking the latter will unzip the .mpkg file
313 which can then be double-clicked to commence the installation.</P
315 > The privoxy service will automatically start after a successful installation
316 (and thereafter every time your computer starts up) however you will need to
317 configure your web browser(s) to use it. To do so, configure them to use a
318 proxy for HTTP and HTTPS at the address 127.0.0.1:8118.</P
320 > To prevent the privoxy service from automatically starting when your computer
321 starts up, remove or rename the file <TT
323 >/Library/LaunchDaemons/org.ijbswa.privoxy.plist</TT
325 (on OS X 10.5 and higher) or the folder named
328 >/Library/StartupItems/Privoxy</TT
329 > (on OS X 10.4 'Tiger').</P
331 > To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
332 and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
333 administrator account, using sudo.</P
335 > To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
336 administrator account.</P
343 NAME="OS-X-INSTALL-FROM-SOURCE"
344 >2.1.6. Installation from source</A
347 > To build and install the Privoxy source code on OS X you will need to obtain
348 the macsetup module from the Privoxy Sourceforge CVS repository (refer to
349 Sourceforge help for details of how to set up a CVS client to have read-only
350 access to the repository). This module contains scripts that leverage the usual
351 open-source tools (available as part of Apple's free of charge Xcode
352 distribution or via the usual open-source software package managers for OS X
353 (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary
354 and associated files. The macsetup module's README file contains complete
355 instructions for its use.</P
357 > The privoxy service will automatically start after a successful installation
358 (and thereafter every time your computer starts up) however you will need to
359 configure your web browser(s) to use it. To do so, configure them to use a
360 proxy for HTTP and HTTPS at the address 127.0.0.1:8118.</P
362 > To prevent the privoxy service from automatically starting when your computer
363 starts up, remove or rename the file <TT
365 >/Library/LaunchDaemons/org.ijbswa.privoxy.plist</TT
367 (on OS X 10.5 and higher) or the folder named
370 >/Library/StartupItems/Privoxy</TT
371 > (on OS X 10.4 'Tiger').</P
373 > To manually start or stop the privoxy service, use the Privoxy Utility
374 for Mac OS X (also part of the macsetup module). This application can start
375 and stop the privoxy service and display its log and configuration files.</P
377 > To uninstall, run the macsetup module's uninstall.sh as sudo from an
378 administrator account.</P
385 NAME="INSTALLATION-FREEBSD"
389 > Privoxy is part of FreeBSD's Ports Collection, you can build and install
392 >cd /usr/ports/www/privoxy; make install clean</TT
401 NAME="INSTALLATION-SOURCE"
402 >2.2. Building from Source</A
405 > The most convenient way to obtain the <SPAN
409 code is to download the source tarball from our
411 HREF="https://sourceforge.net/projects/ijbswa/files/Sources/"
413 > project download page</A
415 or you can get the up-to-the-minute, possibly unstable, development version from
417 HREF="https://www.privoxy.org/"
419 >https://www.privoxy.org/</A
427 HREF="http://www.gnu.org/software/autoconf/autoconf.html"
432 HREF="http://www.gnu.org/software/make/make.html"
436 and, of course, a C compiler like
438 HREF="http://www.gnu.org/software/gcc/gcc.html"
443 > When building from a source tarball,
444 first unpack the source:</P
453 > tar xzvf privoxy-3.0.27-beta-src.tar.gz
454 cd privoxy-3.0.27-beta</PRE
459 > To build the development version, you can get the source code by doing:</P
468 > cd <root-dir>
469 git clone https://www.privoxy.org/git/privoxy.git</PRE
474 > This will create a directory named <TT
476 ><root-dir>/privoxy/</TT
478 which will contain the source tree.</P
480 > Note that source code in GIT is development quality, and may not be
481 stable or well tested.</P
483 > It is strongly recommended to not run <SPAN
487 as root. You should configure/install/run <SPAN
491 an unprivileged user, preferably by creating a <SPAN
495 and group just for this purpose. See your local documentation for the correct
496 command line to do add new users and groups (something like
500 >, but the command syntax may vary from platform
506 > might then look like:</P
515 > privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</PRE
532 > privoxy:*:7777:</PRE
537 > Some binary packages may do this for you.</P
539 > Then, to build from either unpacked tarball or CVS source:</P
550 ./configure # (--help to see options)
551 make # (the make from GNU, sometimes called gmake)
552 su # Possibly required
553 make -n install # (to see where all the files will go)
554 make -s install # (to really install, -s to silence output)</PRE
562 >, you can have the first four steps
563 automatically done for you by just typing:</P
577 > in the freshly downloaded or unpacked source directory.</P
579 > To build an executable with security enhanced features so that
580 users cannot easily bypass the proxy (e.g. <SPAN
582 >"Go There Anyway"</SPAN
584 alter their own configurations, <B
596 > ./configure --disable-toggle --disable-editor --disable-force</PRE
601 > Note that all of these options can also be disabled through the configuration file.</P
609 > If installing as root, the install will fail
610 unless a non-root user or group is specified, or a <TT
614 user and group already exist on the system. If a non-root user is specified,
615 and no group, then the installation will try to also use a group of the same name
619 >. If a group is specified (and no user), then the
620 support files will be installed as writable by that group, and owned by the
621 user running the installation.</P
633 > options for setting user and group ownership
634 of the configuration files (which need to be writable by the daemon). The
639 >user must already exist</I
645 >, it must be run as this same user to
646 insure write access to configuration and log files!</P
648 > Alternately, you can specify <TT
658 > command line, but be sure both already exist:</P
667 > make -s install USER=privoxy GROUP=privoxy</PRE
672 > The default installation path for <B
679 >. This may of course be customized with
683 > path options. If you are doing
684 an install to anywhere besides <TT
688 sure to set the appropriate paths with the correct configure options
691 >./configure --help</B
692 >). Non-privileged users must of course
693 have write access permissions to wherever the target installation is going.</P
695 > If you do install to <TT
698 >, the install will use
701 >sysconfdir=$prefix/etc/privoxy</TT
702 > by default. All other
703 destinations, and the direct usage of <TT
707 behave like normal, i.e. will not add the extra <TT
711 directory. This is for a safer install, as there may already exist another
712 program that uses a file with the <SPAN
715 > name, and thus makes
721 > If installing to <TT
724 >, the documentation will go
727 >$prefix/share/doc</TT
728 >. But if this directory
729 doesn't exist, it will then try <TT
733 there before creating a new <TT
735 >$prefix/share/doc</TT
742 > Again, if the installs goes to <TT
760 the logs will go to <TT
762 >/var/log/privoxy/</TT
764 will be created in <TT
766 >/var/run/privoxy.pid</TT
772 > will attempt to set the correct values
776 > (main configuration file). You should
777 check this to make sure all values are correct. If appropriate,
778 an init script will be installed, but it is up to the user to determine
779 how and where to start <SPAN
783 script should be checked for correct paths and values, if anything other than
784 a default install is done.</P
786 > If install finds previous versions of local configuration files, most of
787 these will not be overwritten, and the new ones will be installed with a
791 > extension. default.action and default.filter
796 >will be overwritten</I
798 >. You will then need
799 to manually update the other installed configuration files as needed. The
800 default template files <SPAN
806 > be overwritten. If you have
807 customized, local templates, these should be stored safely in a separate
808 directory and defined in <TT
815 > directive. It is of course wise to always back-up any
816 important configuration files <SPAN
818 >"just in case"</SPAN
823 > is already running, you will
824 have to restart it manually.</P
826 > For more detailed instructions on how to build Redhat RPMs,
827 Windows self-extracting installers, building on platforms with
828 special requirements etc, please consult the <A
829 HREF="https://www.privoxy.org/developer-manual/newrelease.html"
838 NAME="WINBUILD-CYGWIN"
846 NAME="WINBUILD-SETUP"
850 > Install the Cygwin utilities needed to build <SPAN
854 If you have a 64 bit CPU (which most people do by now), get the
855 Cygwin setup-x86_64.exe program <A
856 HREF="https://cygwin.com/setup-x86_64.exe"
861 HREF="https://cygwin.com/setup-x86_64.exe.sig"
867 > Run the setup program and from View / Category select:
886 mingw64-i686-gcc-core
891 libxslt: GNOME XSLT library (runtime)
908 > If you haven't already downloaded the Privoxy source code, get it now:
918 > mkdir <root-dir>
919 cd <root-dir>
920 git clone https://www.privoxy.org/git/privoxy.git</PRE
925 > Get the source code (.zip or .tar.gz) for tidy from
927 HREF="https://github.com/htacg/tidy-html5/releases"
929 > https://github.com/htacg/tidy-html5/releases</A
931 unzip into <root-dir> and build the software:
941 > cd <root-dir>
942 cd tidy-html5-x.y.z/build/cmake
943 cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local
944 make && make install</PRE
949 > If you want to be able to make a Windows release package, get the NSIS .zip file from
952 HREF="https://sourceforge.net/projects/nsis/files/NSIS%203/"
954 > https://sourceforge.net/projects/nsis/files/NSIS%203/</A
956 and extract the NSIS directory to <TT
960 Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg:
971 MAKENSIS = ./nsis/makensis.exe</PRE
981 NAME="WINBUILD-BUILD"
985 > To build just the Privoxy executable and not the whole installation package, do:
994 CLASS="PROGRAMLISTING"
995 > cd <root-dir>/privoxy
996 ./windows/MYconfigure && make</PRE
1001 > Privoxy uses the <A
1002 HREF="https://en.wikipedia.org/wiki/GNU_build_system"
1006 for building software, so the process is:
1015 CLASS="PROGRAMLISTING"
1016 > $ autoheader # creates config.h.in
1017 $ autoconf # uses config.h.in to create the configure shell script
1018 $ ./configure [options] # creates GNUmakefile
1019 $ make [options] # builds the program</PRE
1027 > options for building a native Windows application under cygwin are
1036 CLASS="LITERALLAYOUT"
1037 > --host=i686-w64-mingw32
1040 --enable-static-linking
1042 --disable-dynamic-pcre</PRE
1047 > You can set the <TT
1057 > to set compiler and linker flags. For example:
1066 CLASS="PROGRAMLISTING"
1067 > $ export CFLAGS="-O2" # set gcc optimization level
1068 $ export LDFLAGS="-Wl,--nxcompat" # Enable DEP
1069 $ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \
1070 > --enable-static-linking --disable-pthread --disable-dynamic-pcre
1071 $ make # build Privoxy</PRE
1077 HREF="../developer-manual/newrelease.html#NEWRELEASE-WINDOWS"
1079 >Developer's Manual</A
1081 for building a Windows release package.
1091 NAME="INSTALLATION-KEEPUPDATED"
1092 >2.3. Keeping your Installation Up-to-Date</A
1095 > If you wish to receive an email notification whenever we release updates of
1099 > or the actions file, <A
1100 HREF="https://lists.privoxy.org/mailman/listinfo/privoxy-announce"
1103 to our announce mailing list</A
1104 >, privoxy-announce@lists.privoxy.org.</P
1106 > In order not to lose your personal changes and adjustments when updating
1125 customizations of <SPAN
1129 HREF="actions-file.html"
1130 >Chapter on actions files</A
1139 SUMMARY="Footer navigation table"
1150 HREF="introduction.html"
1168 HREF="whatsnew.html"
1188 >What's New in this Release</TD