source: adblock2privoxy/adblock2privoxy/README.rst @ ff7ee56

Last change on this file since ff7ee56 was ff7ee56, checked in by zubr <a@…>, 5 years ago

Fixes and docs

  • Property mode set to 100644
File size: 5.6 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.
39Element hiding 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 functionality become disabled (and no webserver is needed).
71
72domainCSS can contain just IP address if no CSS web server has no associated domain. 
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.
103
104How to apply results
105--------------------
106
1071. Install privoxy. Optionally setup it as transparent proxy
108
1092. Change privoxy config file. Add following lines::
110
111    actionsfile ab2p.system.action
112    actionsfile ab2p.action
113    filterfile ab2p.system.filter
114    filterfile ab2p.filter
115
1163. Install nginx or apache webserver
117
118   Nginx config example::
119
120    server {
121            listen 80;
122            #ab2p css domain name (optional, should be equal to domainCSS parameter)
123            server_name www.example.com;
124
125            #root = webDir parameter value
126            root /var/www/privoxy;
127
128            location ~ ^/[^/.]+\..+/ab2p.css$ {
129                # first reverse domain names order
130                        rewrite ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css last;
131            }
132
133            location ~ (^.*/+)[^/]+/+ab2p.css {
134                # then try to get CSS for current domain
135                # if it is unavailable - get CSS for parent domain
136                try_files $uri $1ab2p.css;
137            }
138    }
139
140
141   Apache config example::
142
143    <VirtualHost *:80>
144            #ab2p css domain name (optional, should be equal to domainCSS parameter)
145            ServerName www.example.com
146
147            #root = webDir parameter value
148            DocumentRoot /var/www/privoxy
149
150
151            RewriteEngine on
152
153            # first reverse domain names order
154            RewriteRule ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css [N]
155
156            # then try to get CSS for current domain
157            # if it is unavailable - get CSS for parent domain
158            RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
159            RewriteRule (^.*/+)[^/]+/+ab2p.css$ $1ab2p.css [N]
160    </VirtualHost>
161
1624) Find out abdlock config files to use. Some download locations
163
164  * `EasyList <https://easylist.adblockplus.org/en/>`_
165  * `Russian AD list <https://code.google.com/p/ruadlist/>`_
166
1675) Run adblock2privoxy providing privoxy dir, web dir, domain and adblock input file urls
168
1696) Restart privoxy and apache to load updated configs
170
171Clone repository from http://projects.zubr.me/adblock2privoxy.git
Note: See TracBrowser for help on using the repository browser.