source: adblock2privoxy/adblock2privoxy/README.rst @ a2fcf33

Last change on this file since a2fcf33 was a2fcf33, checked in by Alexey Zubritskiy <a.zubritskiy@…>, 4 years ago

Release 1.4.2

  • Property mode set to 100644
File size: 7.9 KB
Line 
1===============
2Adblock2Privoxy
3===============
4
5**Convert adblock config files to privoxy format**
6
7Synopsis
8--------
9
10    adblock2privoxy [OPTION...] [URL...]
11
12Objectives
13----------
14
15AdBlock Plus browser plugin has great block lists provided by big community,
16but it is client software and cannot work on a server as a proxy.
17
18Privoxy proxy has good potential to block ads at server side,
19but it experiences acute shortage of updated block lists.
20
21This software converts adblock lists to privoxy config files format.
22
23Almost all adblock features are supported including
24
25  * block/unblock requests (on privoxy)
26
27    * all syntax features are supported except for regex templates matching host name
28
29  * hide/unhide page elements (via CSS)
30
31    * all syntax features are supported
32
33  * all block request options except for outdated ones:
34
35    * Supported: script, image, stylesheet, object, xmlhttprequest, object-subrequest, subdocument,document, elemhide, other, popup, third-party, domain=..., match-case, donottrack
36    * Unsupported: collapse, background, xbl, ping and dtd
37
38Tested with privoxy version 3.0.21.
39`Element hiding <https://adblockplus.org/filters#elemhide>`_  feature requires a webserver to serve CSS files. See Nginx and Apache config examples provided.
40
41Description
42-----------
43
44Adblock files specified by [URL]... are converted to privoxy config files and auxiliarly elemHide CSS files. Local file names and http(s) addresses are accepted as URLs.
45
46If no source URLs are specified, task file is used to determine sources: previously processed sources are processed again if any of them is expired. Nothing is done if all sources in the task file are up to date.
47
48Options
49-------
50
51  -v,         --version
52      Show version number
53  -p PATH,    --privoxyDir=PATH
54      Privoxy config output path
55  -w PATH,    --webDir=PATH
56      Css files output path
57  -d DOMAIN,  --domainCSS=DOMAIN
58      Domain of CSS web server (required for Element Hide functionality)
59  -t PATH,    --taskFile=PATH
60      Path to task file containing urls to process and options.
61  -f,         --forced
62      Run even if no sources are expired
63
64If ``taskFile`` is not specified explicilty, ``[privoxyDir]/ab2p.task`` is used.
65
66If task file exists and ``privoxyDir``, ``webDir`` or ``domainCSS`` is not specified, corresponding value is taken from task file.
67
68If ``webDir`` is not specified and cannot be taken from task file, ``privoxyDir`` value is used for ``webDir``.
69
70If ``domainCSS`` is not specified and cannot be taken from task file, `Element Hide <https://adblockplus.org/filters#elemhide>`_ **functionality become disabled**. No webserver is needed in this case.
71
72``domainCSS`` can contain just IP address if CSS web server has no associated domain. Use ``localhost`` or ``127.0.0.1`` if you run your browser on the same machine with webserver.
73
74Usage
75-----
76
77Example of first run::
78
79    adblock2privoxy -p /etc/privoxy -w /var/www/privoxy -d www.example.com -t my_ab2b.task https://easylist-downloads.adblockplus.org/easylist.txt https://easylist-downloads.adblockplus.org/advblock.txt my_custom.txt
80
81Example of subsequent runs::
82
83    adblock2privoxy -t my_ab2b.task
84
85The app generates following files
86
87  * privoxyDir:
88
89    * ab2p.system.action
90    * ab2p.action
91    * ab2p.system.filter
92    * ab2p.filter
93
94  * webDir:
95
96    * ab2p.common.css
97    * ab2p.css
98    * [lot of directories for all levels of domain names]
99
100  * taskFile:
101
102    * special file containing execution details. It can be reused to update privoxy config from same sources with same options. Its name is ``ab2p.task`` by default.
103
104How to apply results
105--------------------
106
107#. Install privoxy. Optionally setup it as transparent proxy. See `privoxy installation manual <http://www.privoxy.org/user-manual/installation.html>`_ for details.
108
109#. Change privoxy config file located in
110   
111    * ``/etc/privoxy/config`` for linux
112    * ``C:\Program Files\Privoxy\config.txt`` for windows
113
114    Add following lines::
115
116      actionsfile ab2p.system.action
117      actionsfile ab2p.action
118      filterfile ab2p.system.filter
119      filterfile ab2p.filter
120
121#. In order to make `Element hiding <https://adblockplus.org/filters#elemhide>`_ work you also need a webserver to serve CSS files. You can choose nginx, apache or any other webserver.
122   See `nginx installation manual <https://www.nginx.com/resources/wiki/start/topics/tutorials/install/>`_,
123   `apache on linux installation manual <https://httpd.apache.org/docs/2.4/install.html>`_
124   or `apache on windows intallation manual <http://www.thesitewizard.com/apache/install-apache-2-windows.shtml>`_ for details.
125
126#. Change webserver config. In examples below
127
128   * replace ``www.example.com`` with your domain or IP address (equal to ``--domainCSS`` adblock2privoxy parameter)
129   * replace ``/var/www/privoxy`` with your CSS files location (equal to ``--webDir`` adblock2privoxy parameter)
130   * remember, these examples are simplified to use by unexperienced people. If you're familiar with webservers administration, you'll find better ways to apply these configs.
131
132   Nginx config: add following lines into http section of ``nginx.conf`` file
133
134    * for linus ``/etc/nginx/nginx.conf``
135    * for windows ``[nginx location]\conf\nginx.conf``
136
137    ::
138
139      server {
140            listen 80;
141            #ab2p css domain name (optional, should be equal to --domainCSS parameter)
142            server_name www.example.com;
143
144            #root = --webDir parameter value
145            root /var/www/privoxy;
146
147            location ~ ^/[^/.]+\..+/ab2p.css$ {
148                # first reverse domain names order
149          rewrite ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css last;
150            }
151
152            location ~ (^.*/+)[^/]+/+ab2p.css {
153                # then try to get CSS for current domain
154                # if it is unavailable - get CSS for parent domain
155                try_files $uri $1ab2p.css;
156            }
157      }
158
159
160   Apache config: put following lines into
161   
162    * for linux: ``/etc/apache2/sites-available/000-default.conf`` (replace existing content)
163    * for windows: ``C:\Program Files\Apache Group\Apache2\conf\httpd.conf`` (append to the end)
164   
165    ::
166
167      <VirtualHost *:80>
168            #ab2p css domain name (optional, should be equal to --domainCSS parameter)
169            ServerName www.example.com
170
171            #root = --webDir parameter value
172            DocumentRoot /var/www/privoxy
173
174
175            RewriteEngine on
176
177            # first reverse domain names order
178            RewriteRule ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css [N]
179
180            # then try to get CSS for current domain
181            # if it is unavailable - get CSS for parent domain
182            RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
183            RewriteRule (^.*/+)[^/]+/+ab2p.css$ $1ab2p.css [N]
184      </VirtualHost>
185
186#. Get adblock2privoxy output
187
188     * Either run adblock2privoxy providing privoxy dir, web dir, domain and adblock input file urls such as
189
190       * `EasyList <https://easylist.adblockplus.org/en/>`_
191       * `Russian AD list <https://code.google.com/p/ruadlist/>`_
192       * and many others from `official adblock repository <https://easylist.adblockplus.org/en/>`_
193
194     * Or just download processed lists from `downloads page <https://projects.zubr.me/wiki/adblock2privoxyDownloads>`_ and unpack ``privoxy`` to and ``web`` directories content into
195
196       * ``/var/www/privoxy`` and ``/var/www/privoxy`` for linux
197       * ``C:\Program Files\Privoxy`` and ``[your webserver directory]`` for windows
198
199#. Restart privoxy and webserver to load updated configs
200
201Contribution
202------------
203
204* Clone repository from http://projects.zubr.me/adblock2privoxy.git.
205* `Report bugs <https://projects.zubr.me/newticket?project=adblock2privoxy>`_
Note: See TracBrowser for help on using the repository browser.