surf

surf
git clone git@git.zachrice.app:repos/surf.git
Log | Files | Refs | README | LICENSE

ADBLOCK.md (2556B)

      1 # surf adblock
      2 
      3 Ad/tracker/malware blocking for surf using WebKit's Content Filter API.
      4 
      5 ## How it works
      6 
      7 `surf-adblock-update` downloads a hosts-based blocklist (Steven Black's
      8 unified list, ~80k domains), converts it to WebKit Content Blocker JSON,
      9 and saves it to `~/.surf/adblock.json`. On startup, surf compiles this
     10 JSON to bytecode and applies it to all page loads at the network layer.
     11 
     12 ## Setup
     13 
     14 ### 1. Install surf with the adblock patch applied
     15 
     16     cd ~/suckless/surf
     17     sudo make clean install
     18 
     19 This also installs `surf-adblock-update` if you add it to the Makefile
     20 install target, or you can run it directly from the repo:
     21 
     22     ./surf-adblock-update
     23 
     24 ### 2. Run the initial blocklist download
     25 
     26     surf-adblock-update
     27 
     28 This creates `~/.surf/adblock.json`. You should see output like:
     29 
     30     Downloading blocklist...
     31     Done: 82207 domains blocked -> ~/.surf/adblock.json
     32 
     33 ### 3. Set up automatic updates with cron
     34 
     35 Install cronie if you don't have it (Arch):
     36 
     37     sudo pacman -S cronie
     38     sudo systemctl enable --now cronie
     39 
     40 Add a weekly cron job (runs Sunday 4am):
     41 
     42     crontab -e
     43 
     44 Add this line:
     45 
     46     0 4 * * 0 /home/YOUR_USER/suckless/surf/surf-adblock-update
     47 
     48 Or from the repo directory:
     49 
     50     (crontab -l 2>/dev/null; echo "0 4 * * 0 $PWD/surf-adblock-update") | crontab -
     51 
     52 Verify it was added:
     53 
     54     crontab -l
     55 
     56 ### 4. Launch surf
     57 
     58     GDK_BACKEND=x11 surf
     59 
     60 The filter loads asynchronously on startup. If there's an error
     61 compiling the filter, it prints to stderr.
     62 
     63 ## Verifying it works
     64 
     65 Visit a known ad domain directly — it should fail to load:
     66 
     67     GDK_BACKEND=x11 surf https://ads.google.com
     68 
     69 ## Updating the blocklist
     70 
     71 Run `surf-adblock-update` any time, then restart surf to pick up changes.
     72 
     73 ## Custom rules
     74 
     75 You can edit `~/.surf/adblock.json` directly. The format is WebKit
     76 Content Blocker JSON (same as Safari content blockers). Example rules:
     77 
     78 Block a specific domain:
     79 
     80     {"trigger":{"url-filter":"^https?://([^/]*\\.)?example\\.com"},"action":{"type":"block"}}
     81 
     82 Hide page elements with CSS:
     83 
     84     {"trigger":{"url-filter":".*"},"action":{"type":"css-display-none","selector":".ad-banner, .sponsored"}}
     85 
     86 Block cookies from third parties:
     87 
     88     {"trigger":{"url-filter":".*","load-type":["third-party"]},"action":{"type":"block-cookies"}}
     89 
     90 Whitelist a site (cancel all previous rules):
     91 
     92     {"trigger":{"url-filter":".*","if-domain":["trusted-site.com"]},"action":{"type":"ignore-previous-rules"}}
     93 
     94 ## Disabling adblock
     95 
     96 Remove or rename the JSON file and restart surf:
     97 
     98     mv ~/.surf/adblock.json ~/.surf/adblock.json.bak