source: adblock2privoxy/man/man1/adblock2privoxy.1 @ 5ee1d7d

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

before debianizaton

  • Property mode set to 100644
File size: 5.6 KB
Line 
1.TH "ADBLOCK2PRIVOXY" "1" "2014\-11\-30" "adblock2privoxy 1.2.4" "General Commands Manual"
2.SH ADBLOCK2PRIVOXY
3.PP
4\f[B]Convert adblock config files to privoxy format\f[]
5.PP
6Synopsis1 \-\-\-\-\-\-\-\-
7.RS
8.PP
9adblock2privoxy [OPTION...] [URL...]
10.RE
11.SS Objectives
12.PP
13AdBlock Plus browser plugin has great block lists provided by big
14community, but it is client software and cannot work on a server as a
15proxy.
16.PP
17Privoxy proxy has good potential to block ads at server side, but it
18experiences acute shortage of updated block lists.
19.PP
20This software converts adblock lists to privoxy config files format.
21.PP
22Almost all adblock features are supported including
23.IP \[bu] 2
24block/unblock requests (on privoxy)
25.RS 2
26.IP \[bu] 2
27all syntax features are supported except for regex templates matching
28host name
29.RE
30.IP \[bu] 2
31hide/unhide page elements (via CSS)
32.RS 2
33.IP \[bu] 2
34all syntax features are supported
35.RE
36.IP \[bu] 2
37all block request options except for outdated ones:
38.RS 2
39.IP \[bu] 2
40Supported: script, image, stylesheet, object, xmlhttprequest,
41object\-subrequest, subdocument,document, elemhide, other, popup,
42third\-party, domain=..., match\-case, donottrack
43.IP \[bu] 2
44Unsupported: collapse, background, xbl, ping and dtd
45.RE
46.PP
47Tested with privoxy version 3.0.21.
48Element blocking feature requires a webserver to serve CSS files.
49See Nginx and Apache config examples provided.
50.SS Description
51.PP
52Adblock files specified by [URL]...
53are converted to privoxy config files and auxiliarly elemHide CSS files.
54Local file names and http(s) addresses are accepted as URLs.
55.PP
56If no source URLs are specified, task file is used to determine sources:
57previously processed sources are processed again if any of them is
58expired.
59Nothing is done if all sources in the task file are up to date.
60.SS Options
61.RS
62.TP
63.B \-v, \-\-version
64show version number
65.RS
66.RE
67.TP
68.B \-p PATH, \-\-privoxyDir=PATH
69privoxy config output path (required)
70.RS
71.RE
72.TP
73.B \-w PATH, \-\-webDir=PATH
74css files output path (optional, privoxyDir is used by default)
75.RS
76.RE
77.TP
78.B \-t PATH, \-\-taskFile=PATH
79path to task file containing urls to process
80.RS
81.RE
82.TP
83.B \-f, \-\-forced
84run even if no sources are expired
85.RS
86.RE
87.RE
88.SS Usage
89.PP
90Example of first run:
91.IP
92.nf
93\f[C]
94adblock2privoxy\ \-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
95\f[]
96.fi
97.PP
98Example of subsequent runs:
99.IP
100.nf
101\f[C]
102adblock2privoxy\ \-p\ /etc/privoxy\ \-w\ /var/www/privoxy\ \-t\ my_ab2b.task
103\f[]
104.fi
105.PP
106The app generates following files
107.RS
108.IP \[bu] 2
109privoxyDir:
110.RS
111.IP \[bu] 2
112ab2p.system.action
113.IP \[bu] 2
114ab2p.action
115.IP \[bu] 2
116ab2p.system.filter
117.IP \[bu] 2
118ab2p.filter
119.RE
120.IP \[bu] 2
121webDir:
122.RS
123.IP \[bu] 2
124ab2p.common.css
125.IP \[bu] 2
126ab2p.css
127.IP \[bu] 2
128[lot of directories for first level domain names]
129.RE
130.IP \[bu] 2
131taskFile:
132.RE
133.RS
134.IP \[bu] 2
135special file containing execution details.
136It can be reused to update privoxy config from same sources.
137.RE
138.SS How to apply results
139.IP "1." 3
140Install privoxy.
141Optionally setup it as transparent proxy
142.IP "2." 3
143Change privoxy config file: Add following lines
144.RS 4
145.RS
146.PP
147actionsfile ab2p.system.action actionsfile ab2p.action filterfile
148ab2p.system.filter filterfile ab2p.filter
149.RE
150.RE
151.IP "3." 3
152Install nginx or apache webserver
153.RS 4
154.PP
155Nginx config example:
156.IP
157.nf
158\f[C]
159server\ {
160\ \ \ \ \ \ \ \ listen\ 80;
161\ \ \ \ \ \ \ \ #ab2p\ css\ domain\ name\ (optional)
162\ \ \ \ \ \ \ \ server_name\ privoxy.zubr.me;
163
164\ \ \ \ \ \ \ \ #root\ =\ webDir\ parameter\ value\
165\ \ \ \ \ \ \ \ root\ /var/www/privoxy;\
166
167\ \ \ \ \ \ \ \ location\ ~\ ^/[^/.]+\\..+/ab2p.css$\ {
168\ \ \ \ \ \ \ \ \ \ \   #\ first\ reverse\ domain\ names\ order
169\       \       \       rewrite\ ^/([^/]*?)\\.([^/.]+)(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?/ab2p.css$\ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css\ last;
170\ \ \ \ \ \ \ \ }
171
172\ \ \ \ \ \ \ \ location\ ~\ (^.*/+)[^/]+/+ab2p.css\ {
173\ \ \ \ \ \ \ \ \ \ \   #\ then\ try\ to\ get\ CSS\ for\ current\ domain
174\ \ \ \ \ \ \ \ \ \ \   #\ if\ it\ is\ unavailable\ \-\ get\ CSS\ for\ parent\ domain
175\ \ \ \ \ \ \ \ \ \ \   try_files\ $uri\ $1ab2p.css;
176\ \ \ \ \ \ \ \ }\
177}
178\f[]
179.fi
180.PP
181Apache config example:
182.IP
183.nf
184\f[C]
185<VirtualHost\ *:80>
186\ \ \ \ \ \ \ \ #ab2p\ css\ domain\ name\ (optional)
187\ \ \ \ \ \ \ \ ServerName\ www.example.com\
188
189\ \ \ \ \ \ \ \ #root\ =\ webDir\ parameter\ value\
190\ \ \ \ \ \ \ \ DocumentRoot\ /var/www/privoxy
191
192
193\ \ \ \ \ \ \ \ RewriteEngine\ on
194
195\ \ \ \ \ \ \ \ #\ first\ reverse\ domain\ names\ order
196\ \ \ \ \ \ \ \ RewriteRule\ ^/([^/]*?)\\.([^/.]+)(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?(?:\\.([^/.]+))?/ab2p.css$\ /$9/$8/$7/$6/$5/$4/$3/$2/$1/ab2p.css\ [N]
197
198\ \ \ \ \ \ \ \ #\ then\ try\ to\ get\ CSS\ for\ current\ domain
199\ \ \ \ \ \ \ \ #\ if\ it\ is\ unavailable\ \-\ get\ CSS\ for\ parent\ domain
200\ \ \ \ \ \ \ \ RewriteCond\ %{DOCUMENT_ROOT}/%{REQUEST_FILENAME}\ !\-f
201\ \ \ \ \ \ \ \ RewriteRule\ (^.*/+)[^/]+/+ab2p.css$\ $1ab2p.css\ [N]
202</VirtualHost>
203\f[]
204.fi
205.RE
206.IP "4)" 3
207Find out abdlock config files to use.
208Some download locations
209.RS
210.IP \[bu] 2
211EasyList (https://easylist.adblockplus.org/en/)
212.IP \[bu] 2
213Russian AD list (https://code.google.com/p/ruadlist/)
214.RE
215.IP "5)" 3
216Run adblock2privoxy providing privoxy dir, web dir and adblock input
217file urls
218.IP "6)" 3
219Restart privoxy and apache to load updated configs
220.PP
221Clone repository from <http://projects.zubr.me/adblock2privoxy.git>
222.SH AUTHORS
223Alexey Zubritsky <adblock2privoxy\@zubr.me>.
Note: See TracBrowser for help on using the repository browser.