listeners: Add network interface binding support, with IP version modes

[Siomachkin]

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"
}

# All mode (binds to all IPs on the interface)     
all.example.com {
    bind "eth0:8080:all"
    respond "All IPs on interface"
}

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]

More interface names to test:

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

[francislavoie]

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

[Siomachkin]

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

[francislavoie]

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.

[Siomachkin]

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

[Monviech]

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?

[francislavoie]

This looks good to me at this stage. I'd like to see @Monviech's comments addressed though, before we merge.

[Monviech]

Reading the initial issue the problem is that they use DHCP and do not know which IP address the server gets.

That is easily solvable by binding caddy to localhost (127.0.0.1 or ::1), and using a NAT rule on the same system to redirect traffic from their interface to localhost where caddy listens. Doing that also outsources to iptables/pf/ipfw or whatever firewall they can configure in their system to keep track of the interface IP address dynamically, so even if their IP changes during runtime caddy will continue to work because, well, its bound to localhost.

I'm just saying that binding to an interface IP address is a lot more ambiguous in caddy than setting an IP address (or localhost e.g. 127.0.0.1 or ::1) which nobody writing the config can misinterpret.

[Siomachkin]

@Monviech Thanks for the detailed feedback!

Regarding binding to all IPs: I'm working on adding support for bind "eth0:8080:all" to bind to all addresses on
an interface, which would address the multiple IPs scenario you mentioned.

Regarding runtime IP changes: If the interface IP changes during runtime:

• Caddy won't crash, but it will likely stop accepting new connections since the listener is bound to an IP that no
  longer exists on the interface
• A caddy reload would be required to rebind to the new IP
• Monitoring network interface changes and automatically rebinding is a more complex feature that would require
  separate design work

Regarding the NAT/localhost approach: That's a valid alternative for truly dynamic IPs, but it requires
platform-specific firewall configuration and root privileges. This feature provides a simpler, cross-platform solution
for common scenarios where:

• IPs are stable (DHCP with long/infinite leases)
• IP changes happen infrequently (at provisioning time)
• Users prefer declarative Caddyfile configuration over external system setup

The original issue and follow-up comments show multiple users specifically requesting this interface binding syntax.

[Monviech]

@Siomachkin Thank you for explaining the constraints. Offering an "all" mode for an interface sounds like a great idea. :)

[francislavoie]

Re runtime IP changes, I think we can just leave it to the user to reload, and we can mention it in the docs for this feature that they should do a force reload if they're making networking config changes. (btw a simple reload isn't enough if the Caddy config hasn't changed, would need reload --force).

I'll wait for the all addition, then I think we're ready to merge.