Skip to content

Conversation

Siomachkin
Copy link
Contributor

Implements GitHub issue #6856 - adds support for binding Caddy listeners to network interfaces by name instead of requiring specific IP addresses.

Features

  • Interface name binding: Use `bind "eth0" instead of hardcoded IP addresses
  • IP version modes: Control IPv4/IPv6 preference with bind "eth0:8080:ipv4", bind "eth0:8080:ipv6", or bind "eth0:8080:auto"

Usage Examples

Basic Interface Binding

example.com {
    bind "eth0"  # Binds to first available IP on eth0 interface
    respond "Hello from eth0!"
}

With Specific Ports and IP Version Modes

# IPv4 only binding
api.example.com {
    bind "eth0:8080:ipv4"
    respond "IPv4 API"
}

# IPv6 only binding
api-v6.example.com {
    bind "eth0:8080:ipv6"
    respond "IPv6 API"
}

# Auto mode (prefers IPv4, falls back to IPv6)
auto.example.com {
    bind "eth0:8080:auto"  # Default mode
    respond "Auto-selected IP"
}

Key Functions

  • isInterfaceName(): Validates interface names and handles interface:port:mode patterns
  • selectIPByMode(): Chooses appropriate IP address based on binding mode
  • resolveInterfaceNameWithMode(): Resolves interface names to IP addresses
  • parseInterfaceAddress(): Parses and validates interface binding syntax

Testing

  • Unit tests for all parsing and validation logic

Assistance Disclosure
I consulted Claude to understand the project architecture, but I authored/coded the fix myself

@francislavoie francislavoie changed the title Add Network Interface Binding Support with IP Version Modes listeners: Add network interface binding support, with IP version modes Sep 13, 2025
@francislavoie
Copy link
Member

More interface names to test:

  • br-901e40e4488d
  • enx9cbf0d00631a
  • veth1308dcd
  • fe80:: IPv6 that has a starting letter (hex)

listeners.go Outdated
Comment on lines 902 to 909
// Check if contains only supported placeholders
if strings.Contains(s, "{env.") || strings.Contains(s, "{file.") {
// Check for unsupported placeholders
if strings.Contains(s, "{http.") || strings.Contains(s, "{vars.") ||
strings.Contains(s, "{system.") || strings.Contains(s, "{time.") ||
strings.Contains(s, "{upstream}") {
return "", false
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't need all this, NewReplacer() implicitly has that protection for you anyway since it only has those placeholders registered

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added explicit checks for system.* and time.* placeholders since they are still processed by ReplaceKnown() and could produce invalid interface names.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don't like having any kind of limitations here, it means if we later add more global placeholders we'd have to remember to consider this code to allow it. Don't need to hand-hold users, if they use placeholders that don't make sense, that's on them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. Removed explicit placeholder restrictions and now trust the replacer system - any globally registered placeholder will work.

@francislavoie francislavoie added the feature ⚙️ New feature or request label Sep 14, 2025
@francislavoie francislavoie added this to the v2.11.0 milestone Sep 14, 2025
@Monviech
Copy link
Contributor

Monviech commented Oct 6, 2025

Im interested in this, thats why Im asking some questions.

Why does it bind to only a single IP address per interface (the first), and not all of the available ones on an interface? Especially for IPv6 there could be a link local address, one or multiple GUAs (with and without privacy extension) and possibly even ULAs. IPv4 can also have virtual IPs on the same interface.

Also what happens if IP addresses change during runtime, e.g. DHCPv4 and v6 leases on ISP provided WAN interfaces (and by extension SLAAC prefix changes), does Caddy notice that the runtime environment changed and reload with the updated addresses? Or will it crash, or stop to serve until manually restarted?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature ⚙️ New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants