source: adblock2privoxy/adblock2privoxy-utils/man/man1/adblock2privoxy.1 @ 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: 8.8 KB
Line 
1.\" Automatically generated by Pandoc 1.16.0.2
2.\"
3.TH "ADBLOCK2PRIVOXY" "1" "2016\-02\-12" "adblock2privoxy 1.4.2" "General Commands Manual"
4.hy
5.SH ADBLOCK2PRIVOXY
6.PP
7\f[B]Convert adblock config files to privoxy format\f[]
8.SS Synopsis
9.RS
10.PP
11adblock2privoxy [OPTION...] [URL...]
12.RE
13.SS Objectives
14.PP
15AdBlock Plus browser plugin has great block lists provided by big
16community, but it is client software and cannot work on a server as a
17proxy.
18.PP
19Privoxy proxy has good potential to block ads at server side, but it
20experiences acute shortage of updated block lists.
21.PP
22This software converts adblock lists to privoxy config files format.
23.PP
24Almost all adblock features are supported including
25.RS
26.IP \[bu] 2
27block/unblock requests (on privoxy)
28.RS 2
29.IP \[bu] 2
30all syntax features are supported except for regex templates matching
31host name
32.RE
33.IP \[bu] 2
34hide/unhide page elements (via CSS)
35.RS 2
36.IP \[bu] 2
37all syntax features are supported
38.RE
39.IP \[bu] 2
40all block request options except for outdated ones:
41.RS 2
42.IP \[bu] 2
43Supported: script, image, stylesheet, object, xmlhttprequest,
44object\-subrequest, subdocument,document, elemhide, other, popup,
45third\-party, domain=..., match\-case, donottrack
46.IP \[bu] 2
47Unsupported: collapse, background, xbl, ping and dtd
48.RE
49.RE
50.PP
51Tested with privoxy version 3.0.21.
52Element hiding (https://adblockplus.org/filters#elemhide) feature
53requires a webserver to serve CSS files.
54See Nginx and Apache config examples provided.
55.SS Description
56.PP
57Adblock files specified by [URL]...
58are converted to privoxy config files and auxiliarly elemHide CSS files.
59Local file names and http(s) addresses are accepted as URLs.
60.PP
61If no source URLs are specified, task file is used to determine sources:
62previously processed sources are processed again if any of them is
63expired.
64Nothing is done if all sources in the task file are up to date.
65.SS Options
66.RS
67.TP
68.B \-v, \-\-version
69Show version number
70.RS
71.RE
72.TP
73.B \-p PATH, \-\-privoxyDir=PATH
74Privoxy config output path
75.RS
76.RE
77.TP
78.B \-w PATH, \-\-webDir=PATH
79Css files output path
80.RS
81.RE
82.TP
83.B \-d DOMAIN, \-\-domainCSS=DOMAIN
84Domain of CSS web server (required for Element Hide functionality)
85.RS
86.RE
87.TP
88.B \-t PATH, \-\-taskFile=PATH
89Path to task file containing urls to process and options.
90.RS
91.RE
92.TP
93.B \-f, \-\-forced
94Run even if no sources are expired
95.RS
96.RE
97.RE
98.PP
99If \f[C]taskFile\f[] is not specified explicilty,
100\f[C][privoxyDir]/ab2p.task\f[] is used.
101.PP
102If task file exists and \f[C]privoxyDir\f[], \f[C]webDir\f[] or
103\f[C]domainCSS\f[] is not specified, corresponding value is taken from
104task file.
105.PP
106If \f[C]webDir\f[] is not specified and cannot be taken from task file,
107\f[C]privoxyDir\f[] value is used for \f[C]webDir\f[].
108.PP
109If \f[C]domainCSS\f[] is not specified and cannot be taken from task
110file, Element Hide (https://adblockplus.org/filters#elemhide)
111\f[B]functionality become disabled\f[].
112No webserver is needed in this case.
113.PP
114\f[C]domainCSS\f[] can contain just IP address if CSS web server has no
115associated domain.
116Use \f[C]localhost\f[] or \f[C]127.0.0.1\f[] if you run your browser on
117the same machine with webserver.
118.SS Usage
119.PP
120Example of first run:
121.IP
122.nf
123\f[C]
124adblock2privoxy\ \-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
125\f[]
126.fi
127.PP
128Example of subsequent runs:
129.IP
130.nf
131\f[C]
132adblock2privoxy\ \-t\ my_ab2b.task
133\f[]
134.fi
135.PP
136The app generates following files
137.RS
138.IP \[bu] 2
139privoxyDir:
140.RS 2
141.IP \[bu] 2
142ab2p.system.action
143.IP \[bu] 2
144ab2p.action
145.IP \[bu] 2
146ab2p.system.filter
147.IP \[bu] 2
148ab2p.filter
149.RE
150.IP \[bu] 2
151webDir:
152.RS 2
153.IP \[bu] 2
154ab2p.common.css
155.IP \[bu] 2
156ab2p.css
157.IP \[bu] 2
158[lot of directories for all levels of domain names]
159.RE
160.IP \[bu] 2
161taskFile:
162.RS 2
163.IP \[bu] 2
164special file containing execution details.
165It can be reused to update privoxy config from same sources with same
166options.
167Its name is \f[C]ab2p.task\f[] by default.
168.RE
169.RE
170.SS How to apply results
171.IP "1." 3
172Install privoxy.
173Optionally setup it as transparent proxy.
174See privoxy installation
175manual (http://www.privoxy.org/user-manual/installation.html) for
176details.
177.IP "2." 3
178Change privoxy config file located in
179.RS 4
180.RS
181.IP \[bu] 2
182\f[C]/etc/privoxy/config\f[] for linux
183.IP \[bu] 2
184\f[C]C:\\Program\ Files\\Privoxy\\config.txt\f[] for windows
185.PP
186Add following lines:
187.IP
188.nf
189\f[C]
190actionsfile\ ab2p.system.action
191actionsfile\ ab2p.action
192filterfile\ ab2p.system.filter
193filterfile\ ab2p.filter
194\f[]
195.fi
196.RE
197.RE
198.IP "3." 3
199In order to make Element
200hiding (https://adblockplus.org/filters#elemhide) work you also need a
201webserver to serve CSS files.
202You can choose nginx, apache or any other webserver.
203See nginx installation
204manual (https://www.nginx.com/resources/wiki/start/topics/tutorials/install/),
205apache on linux installation
206manual (https://httpd.apache.org/docs/2.4/install.html) or apache on
207windows intallation
208manual (http://www.thesitewizard.com/apache/install-apache-2-windows.shtml)
209for details.
210.IP "4." 3
211Change webserver config.
212In examples below
213.RS 4
214.IP \[bu] 2
215replace \f[C]www.example.com\f[] with your domain or IP address (equal
216to \f[C]\-\-domainCSS\f[] adblock2privoxy parameter)
217.IP \[bu] 2
218replace \f[C]/var/www/privoxy\f[] with your CSS files location (equal to
219\f[C]\-\-webDir\f[] adblock2privoxy parameter)
220.IP \[bu] 2
221remember, these examples are simplified to use by unexperienced people.
222If you\[aq]re familiar with webservers administration, you\[aq]ll find
223better ways to apply these configs.
224.PP
225Nginx config: add following lines into http section of
226\f[C]nginx.conf\f[] file
227.RS
228.IP \[bu] 2
229for linus \f[C]/etc/nginx/nginx.conf\f[]
230.IP \[bu] 2
231for windows \f[C][nginx\ location]\\conf\\nginx.conf\f[]
232.IP
233.nf
234\f[C]
235server\ {
236\ \ \ \ \ \ listen\ 80;
237\ \ \ \ \ \ #ab2p\ css\ domain\ name\ (optional,\ should\ be\ equal\ to\ \-\-domainCSS\ parameter)
238\ \ \ \ \ \ server_name\ www.example.com;
239
240\ \ \ \ \ \ #root\ =\ \-\-webDir\ parameter\ value
241\ \ \ \ \ \ root\ /var/www/privoxy;
242
243\ \ \ \ \ \ location\ ~\ ^/[^/.]+\\..+/ab2p.css$\ {
244\ \ \ \ \ \ \ \ \ \ #\ first\ reverse\ domain\ names\ order
245\ \ \ \ rewrite\ ^/([^/]*?)\\.([^/.]+)(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?/ab2p.css$\ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css\ last;
246\ \ \ \ \ \ }
247
248\ \ \ \ \ \ location\ ~\ (^.*/+)[^/]+/+ab2p.css\ {
249\ \ \ \ \ \ \ \ \ \ #\ then\ try\ to\ get\ CSS\ for\ current\ domain
250\ \ \ \ \ \ \ \ \ \ #\ if\ it\ is\ unavailable\ \-\ get\ CSS\ for\ parent\ domain
251\ \ \ \ \ \ \ \ \ \ try_files\ $uri\ $1ab2p.css;
252\ \ \ \ \ \ }
253}
254\f[]
255.fi
256.RE
257.PP
258Apache config: put following lines into
259.RS
260.IP \[bu] 2
261for linux: \f[C]/etc/apache2/sites\-available/000\-default.conf\f[]
262(replace existing content)
263.IP \[bu] 2
264for windows:
265\f[C]C:\\Program\ Files\\Apache\ Group\\Apache2\\conf\\httpd.conf\f[]
266(append to the end)
267.IP
268.nf
269\f[C]
270<VirtualHost\ *:80>
271\ \ \ \ \ \ #ab2p\ css\ domain\ name\ (optional,\ should\ be\ equal\ to\ \-\-domainCSS\ parameter)
272\ \ \ \ \ \ ServerName\ www.example.com
273
274\ \ \ \ \ \ #root\ =\ \-\-webDir\ parameter\ value
275\ \ \ \ \ \ DocumentRoot\ /var/www/privoxy
276
277
278\ \ \ \ \ \ RewriteEngine\ on
279
280\ \ \ \ \ \ #\ first\ reverse\ domain\ names\ order
281\ \ \ \ \ \ RewriteRule\ ^/([^/]*?)\\.([^/.]+)(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?/ab2p.css$\ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css\ [N]
282
283\ \ \ \ \ \ #\ then\ try\ to\ get\ CSS\ for\ current\ domain
284\ \ \ \ \ \ #\ if\ it\ is\ unavailable\ \-\ get\ CSS\ for\ parent\ domain
285\ \ \ \ \ \ RewriteCond\ %{DOCUMENT_ROOT}/%{REQUEST_FILENAME}\ !\-f
286\ \ \ \ \ \ RewriteRule\ (^.*/+)[^/]+/+ab2p.css$\ $1ab2p.css\ [N]
287</VirtualHost>
288\f[]
289.fi
290.RE
291.RE
292.IP "5." 3
293Get adblock2privoxy output
294.RS 4
295.RS
296.IP \[bu] 2
297Either run adblock2privoxy providing privoxy dir, web dir, domain and
298adblock input file urls such as
299.RS 2
300.IP \[bu] 2
301EasyList (https://easylist.adblockplus.org/en/)
302.IP \[bu] 2
303Russian AD list (https://code.google.com/p/ruadlist/)
304.IP \[bu] 2
305and many others from official adblock
306repository (https://easylist.adblockplus.org/en/)
307.RE
308.IP \[bu] 2
309Or just download processed lists from downloads
310page (https://projects.zubr.me/wiki/adblock2privoxyDownloads) and unpack
311\f[C]privoxy\f[] to and \f[C]web\f[] directories content into
312.RS 2
313.IP \[bu] 2
314\f[C]/var/www/privoxy\f[] and \f[C]/var/www/privoxy\f[] for linux
315.IP \[bu] 2
316\f[C]C:\\Program\ Files\\Privoxy\f[] and
317\f[C][your\ webserver\ directory]\f[] for windows
318.RE
319.RE
320.RE
321.IP "6." 3
322Restart privoxy and webserver to load updated configs
323.SS Contribution
324.IP \[bu] 2
325Clone repository from <http://projects.zubr.me/adblock2privoxy.git>.
326.IP \[bu] 2
327Report bugs (https://projects.zubr.me/newticket?project=adblock2privoxy)
328.SH AUTHORS
329Alexey Zubritsky <adblock2privoxy\@zubr.me>.
Note: See TracBrowser for help on using the repository browser.