xcancel-forwarder

Local network tool that transparently redirects all X/Twitter traffic to xcancel.com, allowing you to browse Twitter content without directly accessing X's servers.

Project maintained by ryantenney Hosted on GitHub Pages — Theme by mattgraham

dnsmasq Configuration

Guide for using the included dnsmasq DNS server to redirect X/Twitter domains.

For advanced configuration: See DNSMASQ_ADVANCED.md for multiple upstream DNS servers, domain-specific upstreams, DHCP server configuration, custom DNS records, performance tuning, and security considerations.

When to Use This Option

Use the included dnsmasq server if:

Important: dnsmasq requires macvlan networking to function properly as a DNS server.

Prerequisites

Setup Steps

1. Configure Environment Variables

Edit your .env file:

# Network settings
NETWORK_INTERFACE=eth0               # Your network interface
LAN_SUBNET=192.168.1.0/24           # Your subnet
LAN_GATEWAY=192.168.1.1             # Your router
NGINX_IP=192.168.1.100              # IP for nginx
DNSMASQ_IP=192.168.1.101            # IP for dnsmasq (must be free)

# Upstream DNS (dnsmasq will forward other queries here)
UPSTREAM_DNS=1.1.1.1                # Cloudflare DNS

2. Update dnsmasq Configuration

Edit dnsmasq/dnsmasq.conf and update the IP addresses to match your nginx IP:

# Replace 192.168.1.100 with your actual NGINX_IP
address=/twitter.com/192.168.1.100
address=/x.com/192.168.1.100
address=/t.co/192.168.1.100

Also update upstream DNS servers if desired:

# Cloudflare (default)
server=1.1.1.1
server=1.0.0.1

# Or use Google DNS
# server=8.8.8.8
# server=8.8.4.4

# Or your ISP/router
# server=192.168.1.1

3. Enable Macvlan in docker-compose.yaml

Edit docker-compose.yaml:

Uncomment the macvlan network:

networks:
  macvlan_lan:
    driver: macvlan
    driver_opts:
      parent: ${NETWORK_INTERFACE:-eth0}
    ipam:
      config:
        - subnet: ${LAN_SUBNET:-192.168.1.0/24}
          gateway: ${LAN_GATEWAY:-192.168.1.1}
          ip_range: ${IP_RANGE:-192.168.1.64/28}
          aux_addresses:
            host: ${HOST_IP:-192.168.1.10}

Update nginx service to use macvlan:

Comment out ports and uncomment networks:

nginx:
  # Comment out these lines:
  # ports:
  #   - "${HTTP_PORT:-80}:80"
  #   - "${HTTPS_PORT:-443}:443"

  # Uncomment these lines:
  networks:
    macvlan_lan:
      ipv4_address: ${NGINX_IP:-192.168.1.100}

Uncomment the dnsmasq service:

dnsmasq:
  image: jpillora/dnsmasq:latest
  container_name: xcancel-dnsmasq
  restart: unless-stopped
  networks:
    macvlan_lan:
      ipv4_address: ${DNSMASQ_IP:-192.168.1.101}
  volumes:
    - ./dnsmasq/dnsmasq.conf:/etc/dnsmasq.conf:ro
  environment:
    - TZ=${TZ:-America/New_York}
  cap_add:
    - NET_ADMIN

4. Start Services

# Start both nginx and dnsmasq
docker compose up -d

# Check status
docker compose ps

# Check logs
docker compose logs -f dnsmasq

Configure Clients to Use dnsmasq

Now you need to point devices to use your dnsmasq server as their DNS.

macOS:

  1. System Settings → Network
  2. Select your connection → Details
  3. DNS tab → Click “+”
  4. Add your dnsmasq IP (e.g., 192.168.1.101)
  5. Drag it to the top of the list
  6. Click OK

Windows:

  1. Settings → Network & Internet
  2. Properties for your connection
  3. Edit DNS settings
  4. Manual → IPv4 → ON
  5. Preferred DNS: 192.168.1.101
  6. Save

Linux:

# Edit /etc/resolv.conf
sudo vim /etc/resolv.conf

# Add at the top
nameserver 192.168.1.101

Or use NetworkManager/systemd-resolved configuration.

iOS/Android:

  1. Settings → Wi-Fi
  2. Tap info/settings for your network
  3. Configure DNS → Manual
  4. Add DNS server: 192.168.1.101

Option 2: Router/DHCP Configuration (Network-Wide)

If you want all devices on your network to use dnsmasq:

  1. Log in to your router admin panel
  2. Find DHCP settings
  3. Set Primary DNS server to your dnsmasq IP (e.g., 192.168.1.101)
  4. Set Secondary DNS to your ISP or 1.1.1.1 (fallback)
  5. Save and restart DHCP

New DHCP leases will automatically use dnsmasq. Existing devices may need to:

Verify dnsmasq is Working

Test DNS Resolution

# Should return your nginx IP
nslookup twitter.com 192.168.1.101
nslookup x.com 192.168.1.101

# Expected output:
# Server:   192.168.1.101
# Address:  192.168.1.101#53
#
# Name:     twitter.com
# Address:  192.168.1.100

Test Other Domains (Should Still Work)

# Should return real IP via upstream DNS
nslookup google.com 192.168.1.101

Check dnsmasq Logs

docker compose logs dnsmasq

# Should show queries like:
# dnsmasq[1]: query[A] twitter.com from 192.168.1.50
# dnsmasq[1]: config twitter.com is 192.168.1.100

Enable Query Logging (Optional)

To see all DNS queries for debugging:

Edit dnsmasq/dnsmasq.conf and uncomment:

log-queries

Restart:

docker compose restart dnsmasq
docker compose logs -f dnsmasq

You’ll see every DNS query. Disable after debugging to reduce log volume.

Troubleshooting

dnsmasq Container Won’t Start

Check IP isn’t already in use:

ping 192.168.1.101
# Should get "no route to host" or timeout

Check macvlan configuration:

# Verify network interface exists
ip link show

# Check docker network
docker network ls
docker network inspect xcancel-forwarder_macvlan_lan

Check logs:

docker compose logs dnsmasq

Common errors:

Can’t Reach dnsmasq from Clients

From Docker host, you cannot reach macvlan IPs directly. This is a Docker limitation. Test from another device on your network.

Firewall blocking port 53:

# On the Docker host
sudo iptables -L -n | grep 53

If using firewalld/ufw, allow DNS:

# UFW
sudo ufw allow 53/udp
sudo ufw allow 53/tcp

# Firewalld
sudo firewall-cmd --add-service=dns --permanent
sudo firewall-cmd --reload

Queries Timing Out

Check dnsmasq is listening:

docker compose exec dnsmasq netstat -ulnp
# Should show process listening on 0.0.0.0:53

Test with dig:

# From another device
dig @192.168.1.101 twitter.com

# Should return answer with your nginx IP

Upstream DNS Not Working

If redirected domains work but other domains don’t resolve:

  1. Check upstream DNS is accessible:
docker compose exec dnsmasq ping -c 3 1.1.1.1
  1. Try different upstream DNS in dnsmasq.conf:
server=8.8.8.8
  1. Check if your router/ISP is blocking DNS on port 53

Stopping dnsmasq

To stop using dnsmasq:

  1. Reconfigure clients to use original DNS (router, ISP, or 1.1.1.1)

  2. Stop the container:

docker compose stop dnsmasq
# Or comment out dnsmasq service in docker-compose.yaml
docker compose up -d
  1. Clear DNS caches on clients (see TESTING.md for instructions)

dnsmasq vs Pi-hole

Use dnsmasq if:

Use Pi-hole if:

You can also use both - Pi-hole can use dnsmasq as an upstream DNS server.

Advanced Configuration

For advanced dnsmasq features, see:

Additional Resources