Squid cache_peer Upstream Proxy With Authentication

The usual trigger is a mixed LAN. A smart TV app, an old Java crawler, a monitoring appliance, a Windows system proxy setting that some programs honour and others don't. Each accepts host:port. Few of them can send a Proxy-Authorization header, and the ones that can each store the password in a different place.

Squid fixes this by sitting in the middle. Clients connect to Squid with no credentials. Squid checks that they come from your LAN, then forwards every request to the paid gateway as a parent, attaching the username and password itself. The paid proxy only ever sees Squid.

LAN clients (no auth)        Squid box                 SparkProxy gateway
192.168.1.0/24  --->  192.168.1.10:3128  --->  gateway.sparkproxy.io:11000  --->  target
                      ACL: LAN only             login=USER:PASS sent here         sees the
                      never_direct              rotation happens here             exit IP

If the parent and child terminology is new, the short version lives in what is an upstream proxy. This post assumes you know the idea and need the config to survive real traffic. It is also not a privacy chain. Stacking hops for anonymity is a different goal with different tradeoffs, covered in what is proxy chaining. Here the second hop exists purely to hold credentials and enforce who may use them.

Gather these first. Most broken setups we see trace back to one wrong value in this list rather than to Squid itself.

On the version: the Squid project lists v7.7, released 2026-08-24, as the current release series on its Getting Squid page (read 2026-10-30), and the latest commit on the GitHub repository was dated 2026-10-23 when we checked. Your distribution may ship an older 6.x package. Every directive below is documented for both v6 and v7 in the cache_peer reference.

Before touching Squid, confirm the Squid box can reach the gateway on its own. If this fails, no squid.conf will help:

# Run on the Squid box, not on a client
curl -s -x http://YOUR_USER:YOUR_PASS@gateway.sparkproxy.io:11000 https://api.ipify.org; echo

You should see an IP that is not the box's own public address. Write it down.

Install Squid (sudo apt install squid on Debian or Ubuntu), move the stock file aside, and start from this. It is a pure forwarder: no disk cache, LAN-only access, and no way out except through the parent.

# /etc/squid/squid.conf  -- Squid 6.x / 7.x
http_port 3128

# Who may use this proxy. Keep it to your real subnet.
acl localnet src 192.168.1.0/24
acl SSL_ports port 443
acl Safe_ports port 80 443

http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow localhost
http_access allow localnet
http_access deny all

# The paid gateway as the only parent, with credentials
cache_peer gateway.sparkproxy.io parent 11000 0 no-query no-digest default name=spark_rotating login=YOUR_USER:YOUR_PASS connect-timeout=10 connect-fail-limit=5

# Never connect to a target directly, even if the parent is down
never_direct allow all

# Don't leak LAN details to the target
forwarded_for delete
via off
httpd_suppress_version_string on

# Forward only, store nothing
cache deny all

Then validate and load it:

sudo squid -k parse          # syntax check, prints the offending line on error
sudo systemctl restart squid
curl -s -x http://192.168.1.10:3128 https://api.ipify.org; echo   # from a LAN client

What each non-obvious piece does:

• cache_peer ... parent 11000 0: the gateway's HTTP port, then 0 for the ICP port because a commercial gateway does not speak ICP. no-query and no-digest stop Squid from trying cache-sibling protocols against it.
• default: marks this as the last-resort parent. With a single peer it mostly affects how the hierarchy code appears in the log.
• name=spark_rotating: the label Squid uses in cache.log and in cache_peer_access. You need it once you add a second peer on the same hostname, so set it from day one.
• login=YOUR_USER:YOUR_PASS: Squid adds a Basic Proxy-Authorization header on every request it sends to this peer, including CONNECT for HTTPS.
• connect-timeout=10 overrides the global peer_connect_timeout, which defaults to 30 seconds per the directive docs. Thirty seconds of hanging is a long time for a LAN client.
• connect-fail-limit=5: how many connect failures mark the peer DEAD. The documented default is 10.
• never_direct allow all: the line that makes the setup trustworthy. Without it, if the parent fails Squid may quietly fetch from your own IP, and you'd only find out from the target's logs.
• forwarded_for delete: Squid's default is on, which appends X-Forwarded-For: 192.168.1.x to plain-HTTP requests it forwards. Through a paid exit, that header hands the target your internal address. delete removes it, and via off drops the Via header Squid adds by default.

The ACL order matters. http_access rules are first-match, so deny all must be last, and the localnet range must never be widened to all on a box with a public interface. An open Squid that logs in to a paid gateway is an open proxy billed to you.

This one costs people an afternoon. The cache_peer docs state that the login= string "can include URL escapes (i.e. %20 for spaces). This also means % must be written as %%." So Squid decodes the value before sending it, and a password that contains % gets mangled unless you double it.

The symptom of getting this wrong is a perfectly reachable parent that answers every request with 407. The quickest fix is boring: generate a gateway password from letters and digits only, and keep the escaping table for credentials you don't control.

If Squid runs on a machine with a stable public IP, usually a small VPS or an office line with a static address, you can skip credentials entirely. Add the box's public IP to the whitelist in the SparkProxy dashboard and delete the login= option:

cache_peer gateway.sparkproxy.io parent 11000 0 no-query no-digest default name=spark_rotating connect-timeout=10
never_direct allow all

The gateway now authorises by source address. Two things change.

First, no password travels between Squid and the gateway. That hop is plain HTTP to port 11000, so a login= header is Base64, not encryption, readable by anything on the path. Whitelisting removes that exposure.

Second, your http_access rules become the only lock. Anyone who can reach port 3128 rides your whitelisted IP. On a VPS, localnet should be your office's public address, not a private range, and the cloud firewall should block 3128 from everywhere else:

# Squid on a VPS, used from one office
acl office src 198.51.100.40/32
http_access allow office
http_access deny all

Plans include a fixed number of whitelist slots; on 2026-10-30 the SparkProxy pricing section listed 5 on the $75/month Starter pack and 10 on the $140/month Core pack (USD, excluding VAT/GST). One Squid box uses one slot, which is the point: dozens of LAN devices, one whitelisted address. Whitelisting fails if the box's IP changes, so don't use it on a residential connection with a dynamic address. The mechanics and the dynamic-IP trap are covered in what is IP whitelisting for proxies.

Squid does not rotate anything. It forwards; the gateway picks the exit. SparkProxy offers Random Rotation (the site describes it as a fresh IP per request) and Sticky Sessions, which hold one exit for 5 minutes. What Squid controls is how many upstream connections carry your traffic, and that decides how rotation looks from the client side.

Plain HTTP. Squid keeps idle connections to the parent open and reuses them, because server_persistent_connections defaults to on (docs). Several client requests can share one upstream connection. If your measurements show the same exit repeating more than you expect for plain-HTTP targets, force a new upstream connection per request:

server_persistent_connections off

You pay a TCP handshake per request to the gateway in exchange.

HTTPS. Here rotation granularity is the tunnel, and no setting changes that. A CONNECT tunnel is one TCP stream from the exit IP to the target. The gateway cannot swap the exit in the middle of it without breaking TLS. So a browser that opens one tunnel and sends forty requests over HTTP keep-alive presents one IP for all forty. A script that opens a new connection per request presents a new IP per request. Same Squid, same gateway, different client behaviour.

Don't take our word for it. Measure it on your own setup with this script, which runs from any LAN machine:

import requests

SQUID = "http://192.168.1.10:3128"
PROXIES = {"http": SQUID, "https": SQUID}
ECHO = "https://api.ipify.org"


def fresh_connections(n):
    # requests.get() builds a new session each call, so each call opens a new tunnel
    return [requests.get(ECHO, proxies=PROXIES, timeout=20).text.strip() for _ in range(n)]


def one_session(n):
    # one Session reuses the same CONNECT tunnel while the server keeps it alive
    with requests.Session() as s:
        s.proxies.update(PROXIES)
        return [s.get(ECHO, timeout=20).text.strip() for _ in range(n)]


if __name__ == "__main__":
    a = fresh_connections(10)
    b = one_session(10)
    print("new tunnel per request:", len(set(a)), "distinct IPs of", len(a))
    print("one reused session:    ", len(set(b)), "distinct IPs of", len(b))

If both numbers come back the same, the echo service closed the connection between calls and you're seeing per-connection behaviour either way. The lesson for tools you can't modify: a browser-like client through a rotating gateway rotates per tunnel, so if you need one IP across a whole login flow, give that tool the sticky port described next instead of hoping keep-alive holds.

Different tools want different exits. A price checker wants a new IP every request. A tool that logs in wants Sticky Sessions. A QA box wants German exits. Since the tools can't send usernames, encode the choice in the Squid port they connect to.

Squid can name each http_port, match on that name with a myportname ACL, and steer requests to a specific peer with cache_peer_access. Three peers on the same hostname need distinct name= values, which the docs require.

http_port 3128 name=rotating
http_port 3129 name=sticky
http_port 3130 name=de

acl port_rotating myportname rotating
acl port_sticky   myportname sticky
acl port_de       myportname de

cache_peer gateway.sparkproxy.io parent 11000 0 no-query no-digest name=rot   login=YOUR_USER:YOUR_PASS
cache_peer gateway.sparkproxy.io parent 11002 0 no-query no-digest name=stick login=YOUR_USER:YOUR_PASS
cache_peer gateway.sparkproxy.io parent 11000 0 no-query no-digest name=de    login=YOUR_USER-country-de:YOUR_PASS

cache_peer_access rot   allow port_rotating
cache_peer_access rot   deny all
cache_peer_access stick allow port_sticky
cache_peer_access stick deny all
cache_peer_access de    allow port_de
cache_peer_access de    deny all

never_direct allow all

Notes on this layout:

• The country peer uses the country-suffixed username format that the SparkProxy dashboard shows (the homepage widget displays user-country-us). Copy the exact string from your dashboard rather than guessing a format.
• default is gone. The docs say only the first default parent counts, and a default parent could catch requests from the wrong port. With cache_peer_access and never_direct, each port has exactly one eligible parent.
• Each cache_peer_access group ends in deny all for that peer, which keeps the routing explicit.

Point the smart TV at :3128, the login-heavy tool at :3129 and the QA browser at :3130. One box, three behaviours, no credentials on any client.

For an https:// URL, the client sends Squid CONNECT target:443. Squid checks it against http_access (the stock deny CONNECT !SSL_ports rule rejects tunnels to anything but 443), then opens its own connection to the parent and sends CONNECT target:443 there, with the login= credentials attached. Once the parent answers 200, Squid shovels bytes both ways. TLS runs end to end between the client and the target; neither Squid nor the gateway sees inside without deliberate TLS interception, which you don't want here.

Practical consequences:

• The target's TLS fingerprint is the client's. Squid doesn't rewrite it. If a target blocks your old Java crawler on its handshake, Squid can't fix that, and neither can a better exit IP.
• Non-443 HTTPS fails at Squid. A tool connecting to https://api.sparkproxy.io:8443 gets denied by deny CONNECT !SSL_ports. Add the port to SSL_ports and Safe_ports deliberately if you need it.
• Parent auth failures look different. On HTTPS, Squid's tunneler relays the parent's error reply. curl reports it as curl: (56) CONNECT tunnel failed, response 407. On plain HTTP you get the 407 response body itself.
• Caching does nothing for tunnels. Squid can't cache what it can't read, which is one reason this config uses cache deny all.

Squid's default squid log format is %ts.%03tu %6tr %>a %Ss/%03>Hs %un %Sh/% ([cf.data.pre). Two fields matter here: the result code and status (TCP_MISS/200) and the hierarchy code with the server address (FIRSTUP_PARENT/65.109.70.130). The lines below are illustrative; 65.109.70.130 is the address gateway.sparkproxy.io resolved to when we checked, and yours may differ.

1793350211.402    388 192.168.1.42 TCP_MISS/200 1342 GET http://books.sparkproxy.io/ - FIRSTUP_PARENT/65.109.70.130 text/html
1793350215.118   1904 192.168.1.42 TCP_TUNNEL/200 6120 CONNECT www.sparkproxy.io:443 - FIRSTUP_PARENT/65.109.70.130 -
1793350230.770  10012 192.168.1.42 TCP_MISS/503 4012 GET http://books.sparkproxy.io/ - HIER_NONE/- text/html

import sys
from collections import Counter

PARENT_CODES = {"DEFAULT_PARENT", "FIRSTUP_PARENT", "ANY_OLD_PARENT", "SINGLE_PARENT"}


def summarize(path):
    results, hierarchy, direct = Counter(), Counter(), []
    with open(path, encoding="utf-8", errors="replace") as fh:
        for line in fh:
            parts = line.split()
            if len(parts) < 10:
                continue
            result, hier = parts[3], parts[8].split("/")[0]
            results[result] += 1
            hierarchy[hier] += 1
            if hier == "HIER_DIRECT":
                direct.append(parts[6])
    return results, hierarchy, direct


if __name__ == "__main__":
    res, hier, direct = summarize(sys.argv[1] if len(sys.argv) > 1 else "/var/log/squid/access.log")
    print("Top result codes:", res.most_common(8))
    print("Hierarchy:", dict(hier))
    went_up = sum(v for k, v in hier.items() if k in PARENT_CODES)
    print("Through a parent:", went_up)
    if direct:
        print("WARNING: direct fetches found, check never_direct:", direct[:5])