Configuring Squid 6.1 to proxy traffic between IPv4 clients and IPv6 origin servers requires enabling dual-stack support within the daemon rather than performing network address translation. This setup allows the proxy to maintain separate listening sockets for each protocol version, translating the request context while preserving the original destination IP family. By correctly binding
http_port directives and ensuring DNS resolution supports AAAA records, administrators can bridge legacy IPv4 infrastructure with modern IPv6-only backends without requiring NAT64 gateways or complex routing tables.
Understanding Dual-Stack Proxying
The term "IPv4 to IPv6 proxy" often causes confusion because it suggests a translation layer similar to NAT64. In reality, Squid operates as a standard HTTP proxy that can handle multiple IP versions simultaneously. When an IPv4 client connects to the Squid server, the connection arrives on an IPv4 socket. Squid then initiates a new outbound connection to the target website. If the target domain resolves to an IPv6 address, Squid opens an IPv6 socket to reach it. This process is transparent to the end-user and does not alter the packet headers in the way traditional NAT does.
To achieve this, the Squid instance must be compiled with IPv6 support, which is standard in most modern distributions. The core configuration lies in how you define the listening ports. You cannot rely on a single wildcard binding if you want explicit control over the protocols. Instead, you must specify distinct port entries for IPv4 and IPv6 addresses. This ensures that the daemon listens on the correct interfaces and respects the network stack's capabilities.
Configuring Listening Ports
The primary mechanism for controlling protocol behavior in Squid is the
http_port directive. To support both IPv4 and IPv6, you need to declare separate lines for each address family. For example, if your server has an IPv4 address of
192.0.2.10 and an IPv6 address of
2001:db8::10, you would configure the following in
squid.conf:
http_port 192.0.2.10:3128
http_port [2001:db8::10]:3128
Note the square brackets around the IPv6 address. This syntax is mandatory for Squid to correctly parse the literal IPv6 address and associate it with the specified port. Without these brackets, the parser may fail or interpret the colons incorrectly. If you wish to listen on all available IPv4 interfaces, you can use
0.0.0.0:3128. However, for IPv6, using the wildcard
:: is often preferred to ensure the service binds to all local IPv6 interfaces automatically.
It is crucial to verify that your operating system’s firewall permits inbound connections on port 3128 for both IP versions. On Linux systems using
ufw or
firewalld, rules are typically protocol-agnostic unless explicitly restricted. Ensure that no iptables rules are dropping IPv6 packets destined for the Squid port before they reach the application layer.
DNS Resolution and Outbound Connections
Once the listening ports are configured, the next critical step is ensuring Squid can resolve hostnames to IPv6 addresses. By default, Squid uses the system’s resolver library. If your system’s
/etc/resolv.conf points to a DNS server that returns AAAA records, Squid will attempt IPv6 connections when possible. You can influence this behavior using the
dns_v4_first directive. Setting
dns_v4_first off tells Squid to prefer IPv6 addresses if they are available, falling back to IPv4 only if necessary.
When Squid makes an outbound request, it inspects the resolved IP addresses. If the target site has an IPv6 address, Squid creates an IPv6 socket. The original request from the IPv4 client remains intact in the HTTP headers. Squid adds the
X-Forwarded-For header to indicate the client’s IPv4 address, allowing the backend server to identify the true source. This interaction is detailed further in our guide on
Squid Proxy: Why aren't Via-Headers showing up in X-Forwarded-For?, which explains how header manipulation works during protocol transitions.
If you encounter issues where Squid consistently falls back to IPv4 despite the presence of AAAA records, check your local DNS cache. Tools like
dig or
nslookup can help verify that your resolver is returning IPv6 addresses for the target domains. Additionally, ensure that
forwarded_for is set to
on or
truncate in your configuration to maintain proper client identification across the protocol boundary.
Security and Access Control Lists
Access Control Lists (ACLs) in Squid can distinguish between IPv4 and IPv6 sources. This is useful if you want to apply different caching policies or bandwidth limits based on the incoming protocol. You can define ACLs using the
src keyword combined with specific IP ranges. For instance, to allow only trusted IPv6 networks to access certain resources, you might use:
acl ipv6_clients src 2001:db8::/32
http_access allow ipv6_clients
This granular control ensures that your dual-stack environment remains secure. It also helps in troubleshooting connectivity issues by isolating traffic based on its source protocol. Remember that internal LAN connectivity might behave differently depending on your network topology. As discussed in
IPv6 works inside LAN, doesn't externally, understanding the distinction between local and external routing is vital when configuring proxies that span multiple network segments.
Verifying the Configuration
After applying changes, restart the Squid service and monitor the logs. Look for entries indicating successful connections from IPv4 clients and subsequent IPv6 outbound requests. Use
tail -f /var/log/squid/access.log to observe real-time activity. You should see log entries where the client IP is IPv4 but the requested URL resolves to an IPv6 endpoint. If you notice frequent connection timeouts, verify that the upstream DNS is responsive and that no intermediate firewalls are blocking IPv6 traffic. Properly configured, this setup provides a robust bridge between legacy and modern internet infrastructures.
Frequently Asked Questions
Does Squid translate IPv4 packets to IPv6?
No, Squid does not perform packet-level translation like NAT64. It acts as an application-layer proxy that establishes separate TCP connections for the inbound and outbound legs of the request. The client sees an IPv4 connection, while the server sees an IPv6 connection, with Squid managing the HTTP exchange between them.
What happens if the target website only supports IPv4?
If the target domain resolves only to an A record (IPv4), Squid will automatically open an IPv4 socket for the outbound connection. Your dual-stack configuration handles this gracefully without manual intervention, ensuring compatibility with older websites that have not yet implemented IPv6.
Can I use a wildcard for IPv6 listening ports?
Yes, you can use
http_port [::]:3128 to bind to all available IPv6 interfaces. This is generally recommended for simplicity, provided your server’s firewall allows traffic on this interface. It eliminates the need to list every individual IPv6 address assigned to the machine.
Why are my IPv6 clients getting blocked?
Check your ACLs to ensure you have not inadvertently restricted IPv6 source addresses. Also, verify that your
http_port directives include the IPv6 binding. If Squid is not listening on an IPv6 socket, clients connecting via IPv6 will receive a connection refused error immediately.
How do I troubleshoot DNS resolution failures for IPv6?
Use command-line tools like
dig AAAA example.com to test if your system resolver returns IPv6 addresses. If it does not, update your
/etc/resolv.conf to point to a public DNS provider like Google DNS or Cloudflare that supports IPv6 recursion. Squid relies entirely on the system resolver for these lookups.