---
title: Transparent Proxy / Sidecar Mode
shortTitle: Transparent Proxy
description: Run MockServer as a Kubernetes sidecar with transparent proxy interception for service mesh integration.
layout: page
pageOrder: 3
section: 'Chaos Testing'
subsection: true
sitemap:
  priority: 0.7
  changefreq: 'monthly'
  lastmod: 2026-06-01T08:00:00+00:00
keywords: sidecar proxy, transparent proxy, kubernetes sidecar, iptables redirect, mockserver sidecar, conntrack
---

<p>MockServer can run as a <strong>Kubernetes sidecar</strong> with transparent HTTP proxy interception. This enables service mesh integration patterns where MockServer intercepts traffic destined for external services without any application code changes.</p>

<h2>Transparent Proxy Mode</h2>

<p>When <code class="inline code">transparentProxyEnabled</code> is set to <code class="inline code">true</code>, MockServer treats all incoming HTTP connections as proxy requests. Instead of requiring clients to send explicit HTTP CONNECT requests or configure proxy settings, it uses the <code class="inline code">Host</code> header from each request to determine the forwarding target.</p>

<p>This works with Linux <code class="inline code">iptables</code> REDIRECT rules that redirect outbound traffic to MockServer's port, making the interception completely transparent to the application.</p>

<h3>How it works</h3>

<ol>
    <li>An init container sets up iptables rules to redirect outbound HTTP/HTTPS traffic to MockServer's port</li>
    <li>MockServer resolves the original destination:
        <ul>
            <li><strong>On Linux</strong>: reads the original destination from the kernel conntrack table (<code class="inline code">/proc/net/nf_conntrack</code>), which records the pre-REDIRECT destination. This works even when the Host header is missing or incorrect.</li>
            <li><strong>Fallback</strong>: if conntrack is unavailable (non-Linux, module not loaded, or entry flushed), MockServer falls back to reading the <code class="inline code">Host</code> header.</li>
        </ul>
    </li>
    <li>If an expectation matches, MockServer returns the mock response</li>
    <li>Otherwise, MockServer forwards the request to the original target</li>
</ol>

<h3>Configuration</h3>

<table class="table table-bordered table-striped">
    <thead>
        <tr><th>Property</th><th>Default</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr><td><code class="inline code">transparentProxyEnabled</code></td><td><code class="inline code">false</code></td><td>Enable transparent proxy mode</td></tr>
    </tbody>
</table>

<p>Environment variable: <code class="inline code">MOCKSERVER_TRANSPARENT_PROXY_ENABLED</code></p>

<h3>iptables init container example</h3>

<p>Add an init container to your Pod spec to redirect outbound traffic to MockServer:</p>

<pre class="prettyprint lang-yaml code"><code class="code">initContainers:
  - name: iptables-init
    image: alpine:3.19
    securityContext:
      capabilities:
        add: ["NET_ADMIN"]
    command:
      - sh
      - -c
      - |
        # RETURN first -- exclude MockServer's own egress (UID 65534) to prevent redirect loop.
        # The UID must match app.runAsUser (default 65534 in the Helm chart).
        iptables -t nat -I OUTPUT -m owner --uid-owner 65534 -j RETURN
        # Then 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</code></pre>

<h2>Helm Chart</h2>

<p>The MockServer Helm chart includes sidecar configuration values:</p>

<pre class="prettyprint lang-yaml code"><code class="code">sidecar:
  enabled: false
  transparentProxy: false
  iptables:
    enabled: false
    excludeUid: 65534   # must match app.runAsUser to prevent redirect loop</code></pre>

<p>When <code class="inline code">sidecar.transparentProxy</code> is <code class="inline code">true</code>, the chart sets <code class="inline code">MOCKSERVER_TRANSPARENT_PROXY_ENABLED=true</code> in the deployment.</p>

<p>When <code class="inline code">sidecar.iptables.enabled</code> is <code class="inline code">true</code>, the chart renders an init container that adds a UID-based RETURN rule (to exclude MockServer's own egress) before any REDIRECT rules, preventing an infinite redirect loop. The <code class="inline code">excludeUid</code> must match <code class="inline code">app.runAsUser</code> (both default to 65534).</p>

<h2>Original Destination Resolution (SO_ORIGINAL_DST)</h2>

<p>On Linux with the <code class="inline code">nf_conntrack</code> kernel module loaded, MockServer reads the original destination of intercepted connections from <code class="inline code">/proc/net/nf_conntrack</code>. This provides accurate target resolution even when the Host header is absent or incorrect.</p>

<p><strong>Requirements:</strong></p>
<ul>
    <li><strong>Linux only</strong> -- on other OSes, MockServer gracefully falls back to Host-header resolution</li>
    <li><strong>nf_conntrack module</strong> -- must be loaded and <code class="inline code">/proc/net/nf_conntrack</code> must be readable</li>
    <li><strong>iptables REDIRECT</strong> -- the rule must use <code class="inline code">-j REDIRECT</code></li>
    <li><strong>NET_ADMIN capability</strong> -- required for the iptables init container</li>
</ul>

<p>If conntrack is unavailable, MockServer automatically falls back to Host-header-based resolution with no configuration change needed.</p>

<h2>Limitations</h2>

<ul>
    <li><strong>Conntrack lookup is O(n) with a cap</strong> -- the <code class="inline code">/proc/net/nf_conntrack</code> file is parsed per connection, capped at 200,000 lines. If the conntrack table exceeds this limit, MockServer falls back to Host-header resolution. For high-throughput production use, consider a dedicated transparent proxy.</li>
    <li><strong>Linux only for conntrack</strong> -- original-destination resolution via conntrack requires Linux. On other OSes, the transparent proxy falls back to Host-header resolution.</li>
    <li><strong>iptables not automatic</strong> -- an init container or external mechanism must configure traffic redirection.</li>
</ul>