Feature Request: Support binding local outbound source IP in forward_proxy

[sandbox-report]

Problem:
When running the forward_proxy plugin on a multi-homed server, there is no configuration option to specify which local source IP address to use for outbound requests. It relies solely on OS-level routing.

Proposed Solution:
Add a configuration option (similar to bind in standard transport blocks) inside the forward_proxy directive to explicitly set the local outgoing IP.

Alternatives:
Using OS-level SNAT (iptables) or policy-based routing, which is less flexible than a direct configuration option.

[sandbox-report]

local_address implementation

The local_address option can be implemented entirely in the forwardproxy module.

1. forwardproxy.go

The existing Handler already contains DialTimeout, and Provision() already creates the net.Dialer used for outbound connections.

Add LocalAddress immediately after DialTimeout:

// How long to wait before timing out initial TCP connections.
DialTimeout caddy.Duration `json:"dial_timeout,omitempty"`

// Local IP address to use for outbound connections.
LocalAddress string `json:"local_address,omitempty"`

In Provision(), replace the existing dialer:

dialer := &net.Dialer{
    Timeout:   time.Duration(h.DialTimeout),
    KeepAlive: 30 * time.Second,
    DualStack: true,
}

with:

var localAddress *net.TCPAddr

if h.LocalAddress != "" {
    ip := net.ParseIP(h.LocalAddress)
    if ip == nil {
        return fmt.Errorf("invalid local_address: %s", h.LocalAddress)
    }

    localAddress = &net.TCPAddr{
        IP:   ip,
        Port: 0,
    }
}

dialer := &net.Dialer{
    Timeout:   time.Duration(h.DialTimeout),
    KeepAlive: 30 * time.Second,
    DualStack: true,
    LocalAddr: localAddress,
}

No new imports are required because forwardproxy.go already imports both net and fmt.

The naming is intentionally consistent:

• Caddyfile: local_address
• JSON: local_address
• Handler field: LocalAddress
• Local Go variable: localAddress
• net.Dialer field: LocalAddr

LocalAddr is the only exception because it is the existing Go standard-library field name.

If local_address is not configured, localAddress remains nil, preserving the existing OS routing behavior.

The existing dialer is already used for outbound connections. h.dialContext is initialized from dialer.DialContext, and when an upstream proxy is configured, the same dialer is passed to the upstream proxy. Therefore no separate dialing path is required.

This covers:

• direct HTTP proxy connections
• CONNECT connections
• connections through the configured upstream

2. caddyfile.go

The existing parser handles dial_timeout in the switch inside UnmarshalCaddyfile().

Add local_address immediately after the dial_timeout case:

case "local_address":
    args := d.RemainingArgs()
    if len(args) != 1 {
        return d.ArgErr()
    }
    h.LocalAddress = args[0]

No additional import is required.

Validation is performed in Provision() using net.ParseIP(). This also ensures that JSON configuration receives the same validation.

Caddyfile example:

forward_proxy {
    local_address 192.168.1.10
}

IPv6 is supported:

forward_proxy {
    local_address 2001:db8::10
}

3. forwardproxy_test.go

Use the existing forwardproxy_test.go for the tests.

Add coverage for:

• parsing local_address from the Caddyfile
• rejecting an invalid IP address
• accepting an IPv4 address
• accepting an IPv6 address
• preserving the existing behavior when local_address is omitted
• actually using the configured local address for an outbound connection

The most important test is the actual outbound connection test.

The test should configure a specific local_address, make the forward proxy establish a connection to a test listener, and verify the source IP observed by the destination.

For example:

remoteAddress := conn.RemoteAddr()

The test should verify that the IP portion of remoteAddress matches the configured local_address.

This verifies that net.Dialer.LocalAddr is actually being used, rather than only verifying that the configuration value was parsed.

4. README.md

Document the new option:

forward_proxy {
    dial_timeout  30s
    local_address 192.0.2.10
}

Description:

local_address [IP address] specifies the local IP address to use as the source address for outbound proxy connections. If omitted, the operating system selects the source address according to its normal routing behavior. The source port is selected automatically by the operating system.

Both IPv4 and IPv6 addresses are supported.

Files changed

Production code

• forwardproxy.go

  • Add Handler.LocalAddress
  • Parse and validate the configured IP address
  • Set net.Dialer.LocalAddr

• caddyfile.go

  • Parse the local_address Caddyfile option

Tests

• forwardproxy_test.go
  • Add Caddyfile parsing test
  • Add invalid-address test
  • Add IPv4 test
  • Add IPv6 test
  • Add default-behavior test
  • Add actual outbound source-address test

Documentation

• README.md
  • Document local_address

No changes to Caddy itself are required.