source: adblock2privoxy/README.rst @ b0dcae2

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

updated readme

  • Property mode set to 100644
File size: 4.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.
39Element blocking 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 (required)
55    -w PATH, --webDir=PATH     
56        css files output path (optional, privoxyDir is used by default)
57    -t PATH, --taskFile=PATH   
58        path to task file containing urls to process
59    -f, --forced               
60        run even if no sources are expired
61
62Usage
63-----
64
65Example of first run::
66
67    adblock2privoxy -p /etc/privoxy -w /var/www/privoxy -t my_ab2b.task https://easylist-downloads.adblockplus.org/easylist.txt https://easylist-downloads.adblockplus.org/advblock.txt my_custom.txt
68
69Example of subsequent runs::
70
71    adblock2privoxy -p /etc/privoxy -w /var/www/privoxy -t my_ab2b.task
72
73The app generates following files
74
75        * privoxyDir:
76
77                * ab2p.system.action
78                * ab2p.action
79                * ab2p.system.filter
80                * ab2p.filter
81
82        * webDir:
83
84                * ab2p.common.css
85                * ab2p.css
86                * [lot of directories for first level domain names]
87
88        * taskFile:
89
90    * special file containing execution details. It can be reused to update privoxy config from same sources.
91
92How to apply results
93--------------------
94
951. Install privoxy. Optionally setup it as transparent proxy
96
972. Change privoxy config file: Add following lines
98
99    actionsfile ab2p.system.action
100    actionsfile ab2p.action
101    filterfile ab2p.system.filter
102    filterfile ab2p.filter
103
1043. Install nginx or apache webserver
105
106   Nginx config example::
107
108    server {
109            listen 80;
110            #ab2p css domain name (optional)
111            server_name privoxy.zubr.me;
112
113            #root = webDir parameter value
114            root /var/www/privoxy;
115
116            location ~ ^/[^/.]+\..+/ab2p.css$ {
117                # first reverse domain names order
118                        rewrite ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css last;
119            }
120
121            location ~ (^.*/+)[^/]+/+ab2p.css {
122                # then try to get CSS for current domain
123                # if it is unavailable - get CSS for parent domain
124                try_files $uri $1ab2p.css;
125            }
126    }
127
128
129   Apache config example::
130
131    <VirtualHost *:80>
132            #ab2p css domain name (optional)
133            ServerName www.example.com
134
135            #root = webDir parameter value
136            DocumentRoot /var/www/privoxy
137
138
139            RewriteEngine on
140
141            # first reverse domain names order
142            RewriteRule ^/([^/]*?)\.([^/.]+)(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?(?:\.([^/.]+))?/ab2p.css$ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css [N]
143
144            # then try to get CSS for current domain
145            # if it is unavailable - get CSS for parent domain
146            RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
147            RewriteRule (^.*/+)[^/]+/+ab2p.css$ $1ab2p.css [N]
148    </VirtualHost>
149
1504) Find out abdlock config files to use. Some download locations
151
152  * EasyList - https://easylist.adblockplus.org/en/
153  * Russian AD list - https://code.google.com/p/ruadlist/
154
1555) Run adblock2privoxy providing privoxy dir, web dir and adblock input file urls
156
1576) Restart privoxy and apache to load updated configs
158
159Clone repository from http://projects.zubr.me/adblock2privoxy.git
Note: See TracBrowser for help on using the repository browser.