X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=9483f7363802a6e8237eb604221ba2bc9e73d438;hb=285444907a0bb967b465f2704581a6cac563cacd;hp=80762e68ba1ea765c8aa01c1ae0ac0b2cd848147;hpb=eb521de5fe2e90ede6f0742985c2152dd973c68a;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 80762e68..9483f736 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -9,11 +9,12 @@
+
-
-
+
+
@@ -29,15 +30,11 @@
Privoxy">
]>
- Copyright &my-copy; 2001-2013 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2018 by
+ Privoxy Developers
-$Id: user-manual.sgml,v 2.166 2013/01/25 14:18:48 fabiankeil Exp $
-
@@ -100,14 +95,11 @@ Hal.
You can find the latest version of the Privoxy User Manual at http://www.privoxy.org/user-manual/.
+ url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/.
Please see the Contact section on how to
contact the developers.
-
-
-
@@ -116,7 +108,7 @@ Hal.
Introduction
This documentation is included with the current &p-status; version of
- Privoxy, v.&p-version;Privoxy, &p-version;
Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
- CVS sources). And there may be bugs, though hopefully
+ git sources).
+ And there may be bugs, though hopefully
not many!
]]>
@@ -161,7 +154,7 @@ Hal.
Privoxy is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
- Privoxy Project
+ Privoxy Project
Page.
@@ -243,7 +236,6 @@ How to install the binary packages depends on your operating system:
system. Check that no Junkbuster
or Privoxy objects are in
your startup folder.
-
@@ -334,22 +326,12 @@ How to install the binary packages depends on your operating system:
-FreeBSD
+FreeBSD
Privoxy is part of FreeBSD's Ports Collection, you can build and install
it with cd /usr/ports/www/privoxy; make install clean.
-
- If you don't use the ports, you can fetch and install
- the package with pkg_add -r privoxy.
-
-
- The port skeleton and the package can also be downloaded from the
- File Release
- Page, but there's no reason to use them unless you're interested in the
- beta releases which are only available there.
-
@@ -358,38 +340,163 @@ How to install the binary packages depends on your operating system:
Building from Source
- The most convenient way to obtain the Privoxy sources
- is to download the source tarball from our
- project download
- page.
-
-
-
- If you like to live on the bleeding edge and are not afraid of using
- possibly unstable development versions, you can check out the up-to-the-minute
- version directly from the
- CVS repository.
-
+ The most convenient way to obtain the Privoxy source
+ code is to download the source tarball from our
+
+ project download page,
+ or you can get the up-to-the-minute, possibly unstable, development version from
+ https://www.privoxy.org/.
&buildsource;
+
+ Windows
+
+ Setup
+
+ Install the Cygwin utilities needed to build Privoxy.
+ If you have a 64 bit CPU (which most people do by now), get the
+ Cygwin setup-x86_64.exe program here
+ (the .sig file is here).
+
+
+ Run the setup program and from View / Category select:
+
+
+ Devel
+ autoconf 2.5
+ automake 1.15
+ binutils
+ cmake
+ gcc-core
+ gcc-g++
+ git
+ make
+ mingw64-i686-gcc-core
+ mingw64-i686-zlib
+ Editors
+ vim
+ Libs
+ libxslt: GNOME XSLT library (runtime)
+ Net
+ curl
+ openssh
+ Text
+ docbook-dssl
+ docbook-sgml31
+ docbook-utils
+ openjade
+ Utils
+ gnupg
+ Web
+ w3m
+
+
+
+ If you haven't already downloaded the Privoxy source code, get it now:
+
+
+ mkdir <root-dir>
+ cd <root-dir>
+ git clone https://www.privoxy.org/git/privoxy.git
+
+
+
+ Get the source code (.zip or .tar.gz) for tidy from
+
+ https://github.com/htacg/tidy-html5/releases,
+ unzip into <root-dir> and build the software:
+
+
+ cd <root-dir>
+ cd tidy-html5-x.y.z/build/cmake
+ cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local
+ make && make install
+
+
+
+ If you want to be able to make a Windows release package, get the NSIS .zip file from
+
+
+ https://sourceforge.net/projects/nsis/files/NSIS%203/
+ and extract the NSIS directory to privoxy/windows.
+ Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg:
+
+
+# Path to NSIS
+MAKENSIS = ./nsis/makensis.exe
+
+
+
+
+ Build
+
+
+ To build just the Privoxy executable and not the whole installation package, do:
+
+
+ cd <root-dir>/privoxy
+ ./windows/MYconfigure && make
+
+
+
+ Privoxy uses the GNU Autotools
+ for building software, so the process is:
+
+
+ $ autoheader # creates config.h.in
+ $ autoconf # uses config.h.in to create the configure shell script
+ $ ./configure [options] # creates GNUmakefile
+ $ make [options] # builds the program
+
+
+
+ The usual configure options for building a native Windows application under cygwin are
+
+
+
+ --host=i686-w64-mingw32
+ --enable-mingw32
+ --enable-zlib
+ --enable-static-linking
+ --disable-pthread
+ --disable-dynamic-pcre
+
+
+
+ You can set the CFLAGS and LDFLAGS envars before
+ running configure to set compiler and linker flags. For example:
+
+
+
+ $ export CFLAGS="-O2" # set gcc optimization level
+ $ export LDFLAGS="-Wl,--nxcompat" # Enable DEP
+ $ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \
+ > --enable-static-linking --disable-pthread --disable-dynamic-pcre
+ $ make # build Privoxy
+
+
+
+ See the Developer's Manual
+ for building a Windows release package.
+
+
+
+
+
+
Keeping your Installation Up-to-Date
If you wish to receive an email notification whenever we release updates of
Privoxy or the actions file, subscribe
- to our announce mailing list, ijbswa-announce@lists.sourceforge.net.
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-announce">subscribe
+ to our announce mailing list, privoxy-announce@lists.privoxy.org.
@@ -424,7 +531,6 @@ How to install the binary packages depends on your operating system:
versions of Privoxy:
-
@@ -509,11 +615,9 @@ How to install the binary packages depends on your operating system:
that filtering does not work on compressed pages, so if you use, or want to
use, filtering, you will need to force compression off. Example:
-
{ +filter{google} +prevent-compression }
.google.
-
Or if you use a number of filters, or filter many sites, you may just want
to turn off compression for all sites in
@@ -541,14 +645,13 @@ How to install the binary packages depends on your operating system:
-->
-Quickstart to Using Privoxy
-
+
@@ -633,18 +736,6 @@ How to install the binary packages depends on your operating system:
-
-
Please see the section Contacting the
@@ -660,7 +751,6 @@ How to install the binary packages depends on your operating system:
-
@@ -737,7 +827,6 @@ How to install the binary packages depends on your operating system:
set-image-blocker:
-
@@ -812,7 +901,6 @@ How to install the binary packages depends on your operating system:
-
Advanced users will eventually want to explore &my-app;
@@ -858,7 +946,6 @@ How to install the binary packages depends on your operating system:
A quick and simple step by step example:
-
@@ -882,7 +969,6 @@ How to install the binary packages depends on your operating system:
-
-
@@ -928,7 +1013,6 @@ How to install the binary packages depends on your operating system:
-
This is a very crude and simple example. There might be good reasons to use a
@@ -976,7 +1060,6 @@ How to install the binary packages depends on your operating system:
-
-
@@ -997,7 +1079,6 @@ How to install the binary packages depends on your operating system:
Tools -> Options -> Advanced -> Network ->Connection -> Settings
-
@@ -1006,7 +1087,6 @@ How to install the binary packages depends on your operating system:
Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
-
@@ -1020,7 +1100,6 @@ How to install the binary packages depends on your operating system:
Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy
-
@@ -1040,7 +1119,6 @@ How to install the binary packages depends on your operating system:
-
-
@@ -1080,11 +1157,30 @@ How to install the binary packages depends on your operating system:
/etc/privoxy/config as its main configuration
file.
-
# /etc/init.d/privoxy start
+
+
+
+FreeBSD and ElectroBSD
+
+ To start Privoxy upon booting, add
+ "privoxy_enable='YES'" to /etc/rc.conf.
+ Privoxy will use
+ /usr/local/etc/privoxy/config as its main
+ configuration file.
+
+ If you installed Privoxy into a jail, the
+ paths above are relative to the jail root.
+
+
+ To start Privoxy manually, run:
+
+
+ # service privoxy onestart
+
@@ -1106,14 +1202,18 @@ Click on the &my-app; Icon to start Privoxy. If no co
-Solaris, NetBSD, FreeBSD, HP-UX and others
+Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)
Example Unix startup command:
-
- # /usr/sbin/privoxy /etc/privoxy/config
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
+
+ Note that if you installed Privoxy through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start Privoxy
+ upon boot.
@@ -1130,32 +1230,21 @@ Example Unix startup command:
Mac OS X
- After downloading the privoxy software, unzip the downloaded file by
- double-clicking on the zip file icon. Then, double-click on the
- installer package icon and follow the installation process.
-
-
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-
-
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-
-
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
- In addition, the Privoxy Utility presents a simple way for
- administrators to edit the various privoxy config files. A method
- to uninstall the software is also available.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
@@ -1266,7 +1355,6 @@ must find a better place for this paragraph
command-line options:
-
@@ -1353,9 +1441,10 @@ must find a better place for this paragraph
--pre-chroot-nslookup hostname
- Specifies a hostname to look up before doing a chroot. On some systems, initializing the
- resolver library involves reading config files from /etc and/or loading additional shared
- libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
+ Specifies a hostname (for example www.privoxy.org) to look up before doing a chroot.
+ On some systems, initializing the resolver library involves reading config files from
+ /etc and/or loading additional shared libraries from /lib.
+ On these systems, doing a hostname lookup before the chroot reduces
the number of files that must be copied into the chroot tree.
@@ -1381,7 +1470,6 @@ must find a better place for this paragraph
-
On MS Windows only there are two additional
@@ -1410,7 +1498,7 @@ for details.
-
+Controlling Privoxy with Your Web BrowserPrivoxy's user interface can be reached through the special
@@ -1418,20 +1506,18 @@ for details.
(shortcut: http://p.p/),
which is a built-in page and works without Internet access.
You will see the following section:
-
-
+ Privoxy Menu
-
▪ View & change the current configuration
- ▪ View the source code version numbers
+ ▪ View or toggle the tags that can be set based on the clients address
▪ View the request headers.
@@ -1444,7 +1530,7 @@ for details.
▪ Documentation
+ url="https://www.privoxy.org/&p-version;/user-manual/">Documentation
@@ -1466,10 +1552,7 @@ for details.
it as a test to see whether it is Privoxy
causing the problem or not. Privoxy continues
to run as a proxy in this case, but all manipulation is disabled, i.e.
- Privoxy acts like a normal forwarding proxy. There
- is even a toggle Bookmarklet offered, so
- that you can toggle Privoxy with one click from
- your browser.
+ Privoxy acts like a normal forwarding proxy.
@@ -1492,9 +1575,9 @@ for details.
Configuration Files Overview
- For Unix, *BSD and Linux, all configuration files are located in
- /etc/privoxy/ by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
+ For Unix, *BSD and GNU/Linux, all configuration files are located in
+ /etc/privoxy/ by default. For MS Windows and OS/2
+ these are all in the same directory as the
Privoxy executable.
@@ -1506,13 +1589,12 @@ for details.
principle configuration files are:
-
The main configuration file is named config
- on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt
+ on GNU/Linux, Unix, BSD, and OS/2, and config.txt
on Windows. This is a required file.
@@ -1564,7 +1646,6 @@ for details.
-
The syntax of the configuration and filter files may change between different
@@ -1650,7 +1731,6 @@ for details.
are three action files included with Privoxy with
differing purposes:
-
@@ -1713,7 +1793,6 @@ for details.
The default profiles, and their associated actions, as pre-defined in
default.action are:
-
Default Configurations
@@ -1831,11 +1910,9 @@ for details.
@@ -7747,85 +8112,6 @@ Requests
-
-
-
- These may be bookmarked for quick reference. See next.
-
-
-
-
-Bookmarklets
-
- Below are some bookmarklets to allow you to easily access a
- mini version of some of Privoxy's
- special pages. They are designed for MS Internet Explorer, but should work
- equally well in Netscape, Mozilla, and other browsers which support
- JavaScript. They are designed to run directly from your bookmarks - not by
- clicking the links below (although that should work for testing).
-
-
- To save them, right-click the link and choose Add to Favorites
- (IE) or Add Bookmark (Netscape). You will get a warning that
- the bookmark may not be safe - just click OK. Then you can run the
- Bookmarklet directly from your favorites/bookmarks. For even faster access,
- you can put them on the Links bar (IE) or the Personal
- Toolbar (Netscape), and run them with a single click.
-
-
-
-
-
-
-
- Privoxy - Enable
-
-
-
-
-
- Privoxy - Disable
-
-
-
-
-
- Privoxy - Toggle Privoxy (Toggles between enabled and disabled)
-
-
-
-
-
- Privoxy- View Status
-
-
-
-
-
- Privoxy - Why?
-
-
-
-
-
-
- Credit: The site which gave us the general idea for these bookmarklets is
- www.bookmarklets.com. They
- have more information about bookmarklets.
-
-
-
-
@@ -7839,7 +8125,6 @@ Requests
page is requested by your browser:
-
@@ -7948,7 +8233,7 @@ Requests
-
+
NOTE: This is somewhat of a simplistic overview of what happens with each URL
request. For the sake of brevity and simplicity, we have focused on
@@ -7978,8 +8263,7 @@ Requests
One quick test to see if Privoxy is causing a problem
or not, is to disable it temporarily. This should be the first troubleshooting
- step. See the Bookmarklets section on a quick
- and easy way to do this (be sure to flush caches afterward!). Looking at the
+ step (be sure to flush caches afterward!). Looking at the
logs is a good idea too. (Note that both the toggle feature and logging are
enabled via config file settings, and may need to be
turned on.)
@@ -8022,7 +8306,6 @@ Requests
configuration may vary):
-
Matches for http://www.google.com:
@@ -8052,7 +8335,6 @@ Requests
In file: user.action [ View ][ Edit ]
(no matches in this file)
-
This is telling us how we have defined our
@@ -8108,12 +8390,9 @@ In file: user.action [ View ][ Edit ]Privoxy is applying all its actions
to google.com:
-
-
-
Final results:
-add-header
@@ -8171,8 +8450,8 @@ In file: user.action [ View ][ Edit ]
-
+ +set-image-blocker {pattern}
+
Notice the only difference here to the previous listing, is to
@@ -8185,9 +8464,7 @@ In file: user.action [ View ][ Edit ]ad.doubleclick.net:
-
-
{ +block{Domains starts with "ad"} }
ad*.
@@ -8197,7 +8474,6 @@ In file: user.action [ View ][ Edit ]
-
We'll just show the interesting part here - the explicit matches. It is
@@ -8229,9 +8505,7 @@ In file: user.action [ View ][ Edit ]
-
-
Matches for http://www.example.net/adsl/HOWTO/:
In file: default.action [ View ][ Edit ]
@@ -8295,7 +8569,6 @@ In file: user.action [ View ][ Edit ]
-
Ooops, the /adsl/ is matching /ads in our
@@ -8311,13 +8584,10 @@ In file: user.action [ View ][ Edit ]
-
-
{ -block }
/adsl
-
Now the page displays ;-)
@@ -8331,13 +8601,10 @@ In file: user.action [ View ][ Edit ]
-
-
{ +block{Path starts with "ads".} +handle-as-image }
/ads
-
That actually was very helpful and pointed us quickly to where the problem
@@ -8351,9 +8618,7 @@ In file: user.action [ View ][ Edit ]+filter:
-
-
{ shop }
.quietpc.com
.worldpay.com # for quietpc.com
@@ -8361,25 +8626,20 @@ In file: user.action [ View ][ Edit ]
-{ shop } is an alias that expands to
{ -filter -session-cookies-only }.
Or you could do your own exception to negate filtering:
-
-
-
{ -filter }
# Disable ALL filter actions for sites in this section
.forbes.com
developer.ibm.com
localhost
-
This would turn off all filtering for these sites. This is best
@@ -8402,14 +8662,12 @@ In file: user.action [ View ][ Edit ]
-
-
+
{ fragile }
# Handle with care: easy to break
mail.google.
mybank.example.com
-