Transparent Interception Recipes

MockServer's L7 mock and chaos engine can be reached through many different delivery mechanisms. Two things must be true for transparent interception to work:

1. Traffic must reach MockServer — covered by this page. Mechanisms range from OS firewall rules to cloud route tables.
2. MockServer must recover the original destination — covered by Transparent Proxy / Sidecar Mode, which explains the resolver chain (PROXY protocol v1/v2, then TPROXY, eBPF, SO_ORIGINAL_DST, Linux conntrack, DNS-intent, and Host header fallback).

This page catalogues the delivery mechanisms — (1) above. For each mechanism, the relevant resolver strategy from (2) is noted so you can check whether it is implemented or future work.

One prerequisite applies to all mechanisms: transparentProxyEnabled must be set to true (environment variable MOCKSERVER_TRANSPARENT_PROXY_ENABLED=true). Without this flag, MockServer does not treat incoming connections as transparent-proxy requests.

Resolver Chain Summary

When a connection arrives, MockServer resolves the original destination through an ordered chain. The first strategy that succeeds wins; if none succeed, MockServer falls back to the Host header. The rows below are listed in the real priority order MockServer applies them. (A PROXY protocol header, when present, is detected and consumed earlier in the pipeline, before this resolver chain runs.) See Original Destination Resolution for full details.

Kubernetes and Containers

Kubernetes sidecar with iptables REDIRECT (recommended)

This is the primary Kubernetes interception pattern. An init container writes iptables REDIRECT rules in the Pod's network namespace; MockServer resolves the original destination via the Linux conntrack table. The Transparent Proxy / Sidecar Mode page covers this pattern in full, including the Helm chart values (sidecar.enabled, sidecar.transparentProxy, sidecar.iptables.enabled) and the UID-exclusion loop-avoidance rule. Do not duplicate that setup here; refer to it instead.

Resolver used: Linux conntrack, then Host header fallback.

DaemonSet node-level interception

A DaemonSet runs MockServer on every node and the host-network iptables rules redirect all traffic from selected Pods. The node-level rules use iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 1080 applied in the host network namespace. This is more invasive than the sidecar pattern — it affects all Pods on the node unless tightly scoped by -m set --match-set or an equivalent cgroup filter.

Resolver used: Linux conntrack, then Host header fallback.

Limitation: requires hostNetwork: true and NET_ADMIN capability on the DaemonSet Pod. Platform security policies (PSA/PSP) may block this.

Istio / Envoy VirtualService routing

In a service mesh that already runs Envoy sidecars (Istio, AWS App Mesh), you do not need iptables rules or transparent proxy mode at all. Deploy MockServer as a normal Kubernetes Deployment and Service, then use an Istio VirtualService to route specific hostnames or paths to MockServer's Service instead of the real backend. MockServer receives explicit HTTP requests with a valid Host header; no transparent interception is involved.

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: route-to-mockserver
spec:
  hosts:
    - payments.internal
  http:
    - route:
        - destination:
            host: mockserver
            port:
              number: 1080

Resolver used: Host header (the mesh passes the original Host through). transparentProxyEnabled is not needed for this pattern — MockServer operates as a normal HTTP service.

Docker Compose and Testcontainers (CI network)

In a Docker Compose network or a Testcontainers network, set MockServer as the default gateway for one or more services. Containers in the network send their default-route traffic through MockServer.

services:
  mockserver:
    image: mockserver/mockserver:latest
    environment:
      MOCKSERVER_TRANSPARENT_PROXY_ENABLED: "true"
    networks:
      test-net:
        ipv4_address: 192.168.100.1

  app-under-test:
    image: myapp:latest
    networks:
      test-net:
    # Add a default route through MockServer:
    # gateway option is Docker-compose-network-level, set below.

networks:
  test-net:
    driver: bridge
    ipam:
      config:
        - subnet: 192.168.100.0/24
          gateway: 192.168.100.1

When the application connects to an external host, the container's TCP SYN exits through MockServer. MockServer must run iptables rules on the host or inside the container to REDIRECT traffic to its own listener port. The Linux conntrack table then provides the original destination.

Resolver used: Linux conntrack (if iptables REDIRECT is applied), otherwise Host header fallback. DNS-intent applies if dnsEnabled=true and the app resolves through MockServer's DNS port.

Note: Automatic iptables injection into Docker bridges requires running Docker with sufficient host privileges. In standard Testcontainers usage, the simpler approach is to configure the application's HTTP_PROXY/HTTPS_PROXY to point at MockServer — see the OS / host section below.

eBPF original-destination resolution

MockServer can resolve the original destination from an eBPF map: an external BPF program (which you deploy, e.g. via an init container) records the pre-NAT destination keyed by socket cookie in a pinned BPF map, and MockServer reads it. Enable with transparentProxyEbpf=true and point transparentProxyEbpfMapPath at the pinned map (default /sys/fs/bpf/mockserver_orig_dst). Requires Linux, the native (epoll) transport, and CAP_BPF. MockServer only reads the map — it does not load or attach the BPF program. Automatic sidecar + init-container injection is available via the admission webhook.

OS / Host

System proxy environment variables (simplest)

MockServer is a standards-compliant HTTP/HTTPS proxy. If the application honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, no firewall rules are needed — just point those variables at MockServer. No transparentProxyEnabled is required; this is explicit proxy mode, not transparent mode.

export HTTP_PROXY=http://localhost:1080
export HTTPS_PROXY=http://localhost:1080
export NO_PROXY=localhost,127.0.0.1

For JVM applications:

java -Dhttp.proxyHost=localhost -Dhttp.proxyPort=1080 \
     -Dhttps.proxyHost=localhost -Dhttps.proxyPort=1080 \
     -jar myapp.jar

For Node.js applications that use the global-agent package:

GLOBAL_AGENT_HTTP_PROXY=http://localhost:1080 node -r global-agent/bootstrap myapp.js

Resolver used: not applicable — MockServer receives explicit CONNECT or proxy requests with the target in the request line. No transparent-proxy resolver is needed.

PAC file

A Proxy Auto-Configuration (PAC) file returned by MockServer (or a static file server) tells browsers and applications which proxy to use for which URLs. Set the system or browser proxy settings to use http://your-host/proxy.pac. This is useful when you want to selectively route only certain hostnames through MockServer.

function FindProxyForURL(url, host) {
  if (shExpMatch(host, "*.example.com")) {
    return "PROXY localhost:1080";
  }
  return "DIRECT";
}

Resolver used: not applicable — explicit proxy mode.

Local DNS redirection with MockServer's DNS server

MockServer includes a built-in DNS server. When enabled, it answers A/AAAA queries and records the hostname-to-IP mapping in the DNS-intent registry. If the client then connects to the IP that MockServer returned, the DNS-intent resolver recovers the original hostname for matching and forwarding — without any iptables rules.

Enable the DNS server:

MOCKSERVER_DNS_ENABLED=true
MOCKSERVER_DNS_PORT=53   # or a non-privileged port such as 5053

Point the host (or container) at MockServer's DNS port:

# /etc/resolv.conf
nameserver 127.0.0.1

Or with dnsmasq, forward a specific domain:

server=/example.com/127.0.0.1#5053

Resolver used: DNS-intent (primary), then Host header fallback. This works on Linux, macOS, and Windows — no iptables required.

Requirement: dnsEnabled=true must be set so MockServer's DNS server starts. System property: mockserver.dnsEnabled. Environment variable: MOCKSERVER_DNS_ENABLED. Port: MOCKSERVER_DNS_PORT. The default of 0 binds an OS-assigned ephemeral port, which is unusable for DNS-client configuration — always set a fixed port (e.g. 53 with the needed privileges, or a non-privileged port like 5053 fronted by dnsmasq).

Linux iptables / nftables REDIRECT

On Linux, redirect outbound traffic on the host to MockServer's port. This is the host-level equivalent of the Kubernetes sidecar pattern.

# Exclude MockServer's own egress to avoid a redirect loop. The UID must match
# the user MockServer runs as (the Docker image / Helm chart default is 65534).
iptables -t nat -I OUTPUT -m owner --uid-owner 65534 -j RETURN
# Redirect HTTP and HTTPS to MockServer
iptables -t nat -A OUTPUT -p tcp --dport 80  -j REDIRECT --to-port 1080
iptables -t nat -A OUTPUT -p tcp --dport 443 -j REDIRECT --to-port 1080

With nftables:

table ip nat {
  chain output {
    type nat hook output priority -100;
    meta skuid 65534 return
    tcp dport { 80, 443 } redirect to :1080
  }
}

Resolver used: Linux conntrack (reads /proc/net/nf_conntrack — requires nf_conntrack module loaded), then Host header fallback.

Loop avoidance: always exclude MockServer's egress UID before adding REDIRECT rules. See Transparent Proxy / Sidecar Mode for the full explanation.

TPROXY (IP_TRANSPARENT): the TPROXY iptables target (-j TPROXY) is a more efficient alternative to REDIRECT because it preserves the original destination as the socket's local address, eliminating the conntrack lookup. MockServer supports it: set transparentProxyTproxy=true (environment variable MOCKSERVER_TRANSPARENT_PROXY_TPROXY=true) in addition to transparentProxyEnabled=true. It requires the native epoll transport on Linux and the CAP_NET_ADMIN capability, plus TPROXY rules in the mangle table and a policy-routing rule, for example:

ip route add local 0.0.0.0/0 dev lo table 100
ip rule add fwmark 1 lookup 100
iptables -t mangle -A PREROUTING -p tcp --dport 80 \
  -j TPROXY --tproxy-mark 0x1/0x1 --on-port 1080

If TPROXY is not enabled, MockServer falls back to SO_ORIGINAL_DST then conntrack then Host header, so REDIRECT-based setups continue to work unchanged.

macOS / BSD pf rdr

On macOS and other BSDs, use pf packet filter redirect rules. The conntrack resolver is Linux-only; on macOS, MockServer falls back to the Host header resolver.

# /etc/pf.anchors/mockserver
rdr pass on lo0 proto tcp from any to any port 80  -> 127.0.0.1 port 1080
rdr pass on lo0 proto tcp from any to any port 443 -> 127.0.0.1 port 1080

sudo pfctl -f /etc/pf.anchors/mockserver -e

Note: loading the anchor file directly (as above) replaces the entire active pf ruleset — fine for a dev machine, but for shared/production hosts include the anchor in /etc/pf.conf (anchor "mockserver" + load anchor "mockserver" from "/etc/pf.anchors/mockserver") and reload with pfctl -f /etc/pf.conf to preserve your other rules.

Resolver used: Host header fallback (conntrack is Linux-only; no SO_ORIGINAL_DST via JNI yet).

Limitation: without a conntrack equivalent, the original IP destination is not available — only the Host header. For HTTPS this means MockServer must perform SNI-based TLS termination (which it does via SniHandler) and trust the SNI hostname as the forwarding target. This works correctly for modern HTTPS clients that send SNI.

Windows netsh portproxy

On Windows, netsh interface portproxy redirects TCP connections on a local port to MockServer.

netsh interface portproxy add v4tov4 listenaddress=127.0.0.1 listenport=80  connectaddress=127.0.0.1 connectport=1080
netsh interface portproxy add v4tov4 listenaddress=127.0.0.1 listenport=443 connectaddress=127.0.0.1 connectport=1080

Resolver used: Host header fallback (conntrack is Linux-only; no JNI-based resolver yet on Windows).

Alternative: WinDivert or similar user-space packet capture tools can intercept connections and rewrite destination addresses, but they require native drivers not included in MockServer. Using HTTP_PROXY / HTTPS_PROXY environment variables is the simpler, cross-platform alternative on Windows.

connect() interposition (LD_PRELOAD / proxychains)

Tools such as proxychains-ng or a custom LD_PRELOAD library intercept the connect() system call and redirect connections through a proxy without changing application code or environment variables. MockServer accepts connections from these tools in its standard HTTP proxy mode — no transparent proxy flag needed.

# proxychains4 config (/etc/proxychains4.conf or ~/.proxychains/proxychains4.conf)
[ProxyList]
http 127.0.0.1 1080

# Run the application through proxychains
proxychains4 curl https://api.example.com/data

Resolver used: not applicable — explicit proxy mode. MockServer receives a CONNECT request with the target address.

Network / Cloud (Subnet-Level Interception)

The following patterns intercept traffic for entire subnets or VPCs without per-host configuration. They all rely on the resolver chain for original-destination recovery — typically PROXY protocol (when the load balancer prepends it) or Host header fallback (when it does not).

AWS — NLB with PROXY protocol v2

An AWS Network Load Balancer (NLB) target group can prepend a PROXY protocol v2 header to each connection by setting the target-group attribute proxy_protocol_v2.enabled=true. The header carries the original source and destination IP and port.

Register MockServer (EC2 instance or ECS task) in such a target group. MockServer automatically detects and parses the PROXY protocol v2 header — no additional configuration is needed beyond transparentProxyEnabled=true.

Resolver used: PROXY protocol v2 (implemented, automatic detection).

Not supported — AWS Gateway Load Balancer (GWLB): GWLB delivers traffic via GENEVE encapsulation (UDP 6081), not as a TCP stream with a PROXY header. MockServer does not implement GENEVE decapsulation, so the GWLB appliance pattern is not currently usable. Use an NLB with PROXY protocol v2, or the VPC route-table pattern below.

AWS — VPC route table with source/dest check disabled

For HTTP/HTTPS traffic without a GWLB, deploy MockServer on an EC2 instance with source/dest check disabled (so it accepts packets not addressed to its own IP). Add a route table entry sending the target CIDR to MockServer's ENI as the next hop. MockServer receives the original TCP connections; the original destination is available from the Host header (or from conntrack if running Linux iptables NAT in the appliance itself).

Resolver used: conntrack (if NAT rules are set up on the MockServer instance) or Host header fallback.

GCP — custom static route

In Google Cloud, create a custom static route with --next-hop-instance pointing at a MockServer VM (or with --next-hop-ilb for an Internal Load Balancer fronting a MockServer managed instance group). Traffic from selected source ranges is forwarded to MockServer.

gcloud compute routes create intercept-to-mockserver \
  --network=my-vpc \
  --destination-range=0.0.0.0/0 \
  --next-hop-instance=mockserver-vm \
  --next-hop-instance-zone=us-central1-a \
  --priority=900

Resolver used: PROXY protocol v2 (if an ILB or HAProxy fronts MockServer and is configured to send it), otherwise Host header fallback.

Note: with --next-hop-instance, the MockServer VM must enable IP forwarding (sysctl -w net.ipv4.ip_forward=1) and have iptables/nftables REDIRECT rules steering the forwarded packets to MockServer's listener port — otherwise routed traffic is forwarded onward and never reaches MockServer. The same applies to the AWS ENI and Azure UDR virtual-appliance patterns.

Azure — User-Defined Route (virtual appliance)

In Azure, create a User-Defined Route (UDR) in a route table with next-hop type VirtualAppliance and the next-hop IP address set to MockServer's private IP. Attach the route table to the subnet. IP forwarding must be enabled on MockServer's NIC.

Resolver used: PROXY protocol v2 (if a load balancer in front of MockServer is configured to emit it), otherwise Host header fallback.

Generic default gateway / NAT instance

On any network, you can place MockServer as the default gateway for a test subnet. All traffic from clients in that subnet egresses through MockServer. This is the generic pattern for physical labs, private cloud, and on-premises environments.

Resolver used: conntrack (if the MockServer host applies iptables NAT REDIRECT to steer traffic to its own listener port) or Host header fallback.

Network DNS returning MockServer's IP

Configure the network's recursive resolver to return MockServer's IP address for specific domains (split-horizon DNS or DNS override). Clients resolve the target hostname, receive MockServer's IP, and connect directly. If MockServer's own DNS server (dnsEnabled=true) is the authoritative source that clients query, the DNS-intent resolver recovers the hostname. If an external resolver is substituted, MockServer relies on the Host header.

Resolver used: DNS-intent (when clients resolve through MockServer's DNS server) or Host header fallback (when an upstream resolver substitutes the IP).

Browser and CI

Browser proxy / PAC

Set the browser's proxy configuration to route traffic through MockServer. All major browsers support manual proxy settings and PAC files. For automated browser testing (Selenium, Playwright, Puppeteer), pass the proxy via launch options:

# Chromium / Chrome
chromium --proxy-server="http://localhost:1080"

# Firefox via geckodriver
--proxy-type=manual --proxy-http=localhost:1080 --proxy-ssl=localhost:1080

Resolver used: not applicable — explicit proxy mode (CONNECT requests for HTTPS, proxied GET for HTTP).

CI network alias / gateway

In CI pipelines (GitHub Actions, Buildkite, GitLab CI), start MockServer as a service container. Configure the application or test runner to use HTTP_PROXY=http://mockserver:1080 or set MockServer as the network gateway for the job's Docker network. The service container approach (explicit proxy env) requires no firewall rules and works on any CI platform.

# GitHub Actions: service container approach
services:
  mockserver:
    image: mockserver/mockserver:latest
    ports:
      - 1080:1080

steps:
  - name: Run tests
    env:
      HTTP_PROXY: http://localhost:1080
      HTTPS_PROXY: http://localhost:1080
    run: mvn test

Resolver used: not applicable — explicit proxy mode.

Cross-Cutting Prerequisites

TLS trust (universal prerequisite for HTTPS)

Transparent HTTPS interception requires the client to trust MockServer's Certificate Authority (CA). MockServer dynamically generates leaf certificates signed by its CA. The CA's public certificate must be added to the client's trust store before any HTTPS connection is intercepted.

Obtain MockServer's CA certificate one of these ways (see HTTPS & TLS for the full story):

• Default CA — the bundled CA public certificate ships in the jar at org/mockserver/socket/CertificateAuthorityCertificate.pem (also in the source repo under mockserver-core/src/main/resources/).
• Dynamically-generated CA — when dynamicallyCreateCertificateAuthorityCertificate=true, MockServer writes the generated CA certificate to the directory given by directoryToSaveDynamicSSLCertificate; read it from there.
• Custom CA — if you supplied your own via certificateAuthorityCertificate, use that file.

Add the CA certificate to a JVM trust store:

keytool -import -alias mockserver-ca \
  -file mockserver-ca.pem \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

Add it to the system trust store on Debian/Ubuntu:

cp mockserver-ca.pem /usr/local/share/ca-certificates/mockserver-ca.crt
update-ca-certificates

This prerequisite applies to every mechanism that intercepts HTTPS — whether sidecar iptables, OS pf redirect, cloud route table, or browser proxy. It is the one change that cannot be avoided for HTTPS interception.

Redirect-loop avoidance (all firewall-based mechanisms)

When iptables or pf rules redirect outbound traffic to MockServer, MockServer's own egress traffic must be excluded from the rules. Otherwise MockServer's forwarding connections loop back into itself. The standard approach on Linux is a UID-based RETURN rule:

# Add BEFORE the REDIRECT rules. Replace 65534 with MockServer's actual run UID.
iptables -t nat -I OUTPUT -m owner --uid-owner 65534 -j RETURN

See Transparent Proxy / Sidecar Mode for the full iptables init container example and the Helm chart sidecar.iptables.excludeUid value.

Capability Matrix

One row per delivery mechanism. "Original-dst strategy" shows which resolver strategy the mechanism relies on.