Skip to main content
BlackWeb contains millions of domains, so fine-tuned filtering is essential to avoid blocking legitimate services while maintaining strong security.

​
Complete Advanced Configuration

Here’s the recommended complete configuration with all advanced rules:
squid.conf
# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS

# Allow Rule for Domains
acl allowdomains dstdomain "/path_to/allowdomains.txt"
http_access allow allowdomains

# Block Rule for Punycode
acl punycode dstdom_regex -i \.xn--.*
http_access deny punycode

# Block Rule for gTLD, sTLD, ccTLD
acl blocktlds dstdomain "/path_to/blocktlds.txt"
http_access deny blocktlds

# Block Rule for Domains
acl blockdomains dstdomain "/path_to/blockdomains.txt"
http_access deny blockdomains

# Block Rule for Patterns (Optional)
# https://raw.githubusercontent.com/maravento/vault/refs/heads/master/blackshield/acl/squid/blockpatterns.txt
acl blockwords url_regex -i "/path_to/blockpatterns.txt"
http_access deny blockwords

# Block Rule for web3 (Optional)
# https://raw.githubusercontent.com/maravento/vault/refs/heads/master/blackshield/acl/web3/web3domains.txt
acl web3 dstdomain "/path_to/web3domains.txt"
http_access deny web3

# Block Rule for Blackweb
acl blackweb dstdomain "/path_to/blackweb.txt"
http_access deny blackweb
Rule Order Matters! Allowlists must come before blocklists to function correctly.

​
Allow Rule for Essential Domains

​
Purpose

Use allowdomains.txt to exclude essential domains or subdomains that might be blocked by BlackWeb but are necessary for legitimate services.

​
Configuration

acl allowdomains dstdomain "/path_to/allowdomains.txt"
http_access allow allowdomains

​
Why This Matters

According to Squid’s documentation, subdomains like accounts.google.com and accounts.youtube.com may be used by Google for authentication within its ecosystem. Blocking them could disrupt access to services like Gmail, Drive, Docs, and others.

​
Example allowdomains.txt

allowdomains.txt
.accounts.google.com
.accounts.youtube.com
.yahoo.com
.github.com
.microsoft.com
.office.com

​
Block Rule for Additional Domains

​
Purpose

Use blockdomains.txt to block domains not included in blackweb.txt, such as organization-specific blocked sites.

​
Configuration

acl blockdomains dstdomain "/path_to/blockdomains.txt"
http_access deny blockdomains

​
Example blockdomains.txt

blockdomains.txt
.example-blocked-site.com
.time-wasting-site.net
.internal-blocked.org

​
Block Rule for Top-Level Domains

​
Purpose

Use blocktlds.txt to block entire top-level domains (gTLD, sTLD, ccTLD, etc.) that are commonly associated with spam, malware, or unwanted content.

​
Configuration

acl blocktlds dstdomain "/path_to/blocktlds.txt"
http_access deny blocktlds

​
How It Works

Input domains: 
.bardomain.xxx
.subdomain.bardomain.xxx
.bardomain.ru
.bardomain.adult
.foodomain.com
.foodomain.porn
Output (blocked): 
.foodomain.com
All .xxx, .adult, .porn, and .ru domains are blocked based on their TLD, while .com remains accessible.

​
Example blocktlds.txt

blocktlds.txt
.xxx
.adult
.porn
.webcam
.click
.download

​
Punycode Protection (IDN Homograph Attack)

​
Purpose

Block Punycode - RFC3492 and internationalized domain names (IDN) to prevent IDN homograph attacks, where attackers use similar-looking characters to create fake domains.

​
Configuration

acl punycode dstdom_regex -i \.xn--.*
http_access deny punycode

​
How It Works

Input domains: 
.bücher.com       (rendered as xn--bcher-kva.com)
.mañana.com       (rendered as xn--maana-pta.com)
.google.com       (ASCII - allowed)
.auth.wikimedia.org (ASCII - allowed)
.xn--fiqz9s       (Punycode - blocked)
.xn--p1ai         (Punycode - blocked)
ASCII Output (allowed): 
.google.com
.auth.wikimedia.org
All domains containing xn-- (Punycode prefix) are blocked to prevent homograph attacks.
For more information, visit welivesecurity: Homograph attacks.

​
Block Rule for Patterns (Words)

​
Purpose

Block URLs containing specific keywords or patterns in the URL path.
Caution: This rule can generate false positives. Use carefully and test thoroughly.

​
Configuration

# Download ACL:
sudo wget -P /etc/acl/ https://raw.githubusercontent.com/maravento/vault/refs/heads/master/blackshield/acl/squid/blockwords.txt

# Squid Rule to Block Words:
acl blockwords url_regex -i "/etc/acl/blockwords.txt"
http_access deny blockwords

​
How It Works

Input URLs: 
.bittorrent.com
https://www.google.com/search?q=torrent
https://www.google.com/search?q=mydomain
https://www.google.com/search?q=porn
.mydomain.com
Output (allowed): 
https://www.google.com/search?q=mydomain
.mydomain.com
URLs containing “torrent”, “porn”, or “bittorrent” are blocked, while benign searches remain accessible.

​
Streaming Control (Optional)

​
Purpose

Use streaming.txt to block streaming domains not included in blackweb.txt, such as YouTube, Facebook Live, or other video platforms.

​
Configuration

acl streaming dstdomain "/path_to/streaming.txt"
http_access deny streaming

​
Important Considerations

This list may contain overlapping domains. It’s important to manually clean it according to your objective:Option 1: Block entire platform (e.g., Facebook)
streaming.txt
.fbcdn.net
.facebook.com
This blocks Facebook entirely.Option 2: Block specific features (e.g., Facebook streaming only)
streaming.txt
.z-p3-video.flpb1-1.fna.fbcdn.net
This blocks streaming content while allowing general Facebook access.

​
Example streaming.txt

streaming.txt
# YouTube (complete block)
.youtube.com
.googlevideo.com
.ytimg.com

# Facebook Video (selective block)
.z-p3-video.flpb1-1.fna.fbcdn.net

# Twitch
.twitch.tv
.ttvnw.net

​
Testing Your Advanced Rules

After configuring advanced rules:
1

Validate Configuration

sudo squid -k parse
2

Restart Squid

sudo systemctl restart squid
3

Test Allow Rules

Verify that allowed domains (like accounts.google.com) are accessible
4

Test Block Rules

Confirm that blocked domains, TLDs, and patterns are denied
5

Monitor Logs

sudo tail -f /var/log/squid/access.log

​
Best Practices

Before deploying BlackWeb broadly, create a comprehensive allowdomains.txt with all essential business and authentication domains.
Implement rules gradually:
  1. Start with basic BlackWeb blocking
  2. Add allowlists
  3. Enable punycode protection
  4. Add TLD blocking
  5. Finally, add pattern matching and streaming controls
Keep detailed notes on which domains you’ve added to custom lists and why, especially for allowdomains.txt.
Periodically review your custom lists and remove entries that are no longer needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us