#35027 net: add -outboundbind option for outgoing source address
| Reviewability | Reviews | Agreement | Size | ||||
|---|---|---|---|---|---|---|---|
| #35027 net: add -outboundbind option for outgoing source address | Author silent 74d | 0 | Strong | 168 + 391 tests | |||
|
|
|
|
| |||
Reviewability: ReadyStalePaused Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs. Size: lines added or modified outside tests, then in tests; greener = smaller. | |||||||
Goal
Adds the `-outboundbind=<addr>` configuration option to specify the local source address for outgoing clearnet connections, supporting one address per address family (IPv4 and IPv6). The specified address is validated via a trial bind at startup, and direct connections bind to this local address before connecting. If binding fails during connection establishment, the attempt aborts without fallback and is excluded from addrman peer failure penalties.
Problem: Node operators on multi-homed machines or setups with multiple network interfaces cannot control which local source address is used for outbound Bitcoin P2P connections, as the OS routing table automatically determines outbound source IP selection. Existing `-bind` options configure listening sockets only.
Evidence of importance:
Reviewability
Stale · Author silent 74d
No author activity for 74 days; a review may wait a long time for a response.
Agreement
Strong
substantive support, no open objection (vasild)
Thread notes: Initial objections from luke-jr and gmaxwell against overloading -bind for outbound traffic were resolved by creating a dedicated -outboundbind option. Review feedback regarding trial binding, bare address parsing, and option precedence has been addressed and settled.
Objections, suggestions, and questions:
| Reviewer | Type | Harm, request, or question | Status | Must be | Author replied | Quote |
|---|---|---|---|---|---|---|
| luke-jr (contributor) | objection, approach | changing -bind semantics breaks setups that listen on one IP but load balance outbound connections | fixed · fix pushed · v1, not yet re-checked | answered | yes | 2026-04-09: 'This might break a scenario where someone wants to listen on one IP, but load balance outgoing connections. A new option might be better?' Status from: 2026-05-23: 8144225309: 'Added `-outboundbind=<addr>` as a separate option instead of extending `-bind`' |
| frankomosh (contributor) | objection, safety | storing the address without early validation silently kills outbound connections rather than failing loudly at startup | fixed · fix pushed · v1, not yet re-checked | answered | yes | 2026-04-14: 'misconfigured address fails loudly at init rather than silently killing outbound for that family' Status from: 2026-08-17: 8144225309: 'Done. `IsAddrBindable()` does a trial `bind()` at init, so a misconfigured address fails startup.' |
| gmaxwell (contributor) | objection, approach | binding outbound connections via -bind prevents the node from connecting to peers on the local LAN or VM bridge interfaces | fixed · fix pushed · v1, not yet re-checked | changed | yes | 2026-04-25: 'as proposed here -bind=mypublicinterface would suddenly make my node unable to connect to stuff on my local lan (or, in VM on bridge interfaces)-- pretty surprising.' Status from: 2026-05-23: 8144225309: 'Kept `-bind` semantics unchanged, so existing setups (including LAN/bridge peers) are unaffected' |
| vasild (member) | objection, interface | allowing port numbers in -outboundbind causes confusion since outgoing source ports should not be specified | fixed · fix pushed · v1, not yet re-checked | answered | yes | 2026-06-09: 'this will allow ports to be included, e.g. `-outboundbind=1.2.4.5:5678` which better not be allowed to avoid confusion.' Status from: 2026-08-17: 8144225309: 'switched to `LookupHost()` so a port is rejected at startup.' |
| vasild (member) | objection, interface | silently swallowing unusable addresses masks configuration errors | fixed · fix pushed · v1, not yet re-checked | answered | yes | 2026-06-09: 'What's the reason to silently swallow such addresses? It would be more obvious if we return an error for those at startup, like we do for invalid values.' Status from: 2026-08-17: 8144225309: 'Nothing is dropped silently.' |
| vasild (member) | objection, interface | first-wins prevents overriding earlier configuration settings | answered · v1, not yet re-checked | answered | yes | 2026-06-10: 'Usually the notion is that the last one wins. E.g. `-outboundbind=1.2.3.4 -outboundbind=5.6.7.8` -- `5.6.7.8` should be used. This helps override earlier settings which might be out of one's control.' Status from: 2026-08-17: 8144225309: 'first-wins matches the config-file convention ("the first one is generally chosen", doc/bitcoin-conf.md; reverse_precedence in common/settings.cpp).' |
Support:
- frankomosh (contributor) (Concept ACK, 2026-04-14): concept ACK. [not substantive]
- vasild (member) (Concept ACK, 2026-05-26): I agree that it is better to not change the semantic of the existent `-bind` and introduce a new option instead with a default value "leave it to the OS" which is the same as of before this PR.
- vasild (member) (Approach ACK, 2026-06-10): Approach ACK fa19b8c43489ffcc7693317af3c754992078e536 [not substantive]
- winterrdog (contributor) (Approach ACK, 2026-09-12): approach ACK though, i might be TOO late for the name search party. i'd `-exitbind` in mind (inspired by TOR exit relays). will provide more review [not substantive]
Participants:
- luke-jr (contributor, objection, 1 statements 2026-04-09 to 2026-04-09): objected to altering -bind semantics for outbound traffic as it could break load balancing
- frankomosh (contributor, support, 5 statements 2026-04-14 to 2026-04-14): Concept ACK; suggested trial bind at startup and additional unit tests
- gmaxwell (contributor, objection, 1 statements 2026-04-25 to 2026-04-25): objected to overloading -bind because it breaks local LAN and VM bridge peer connections
- vasild (member, support, 17 statements 2026-05-26 to 2026-06-10): Concept ACK and Approach ACK; provided review feedback on validation, parsing, and tests
- sedited (member, neutral, 1 statements 2026-08-10 to 2026-08-10): asked whether the author was still working on rebasing and addressing open reviews
- winterrdog (contributor, support, 1 statements 2026-09-12 to 2026-09-12): Approach ACK, suggested alternative name -exitbind
Files
391 lines under test/bench/ci.
- src/test/net_tests.cpp +202/-0
- test/functional/feature_bind_outgoing.py +184/-0
- src/netbase.cpp +62/-3
- src/init.cpp +48/-0
- src/net.h +28/-0
- src/netbase.h +19/-2
- doc/release-notes-35027.md +7/-0
- src/net.cpp +4/-3
- src/test/util/net.h +4/-0
- test/functional/test_runner.py +1/-0
Card
The short text the ranking pass compares across PRs.
Adds the `-outboundbind=<addr>` configuration option allowing operators to pin the outgoing source IP address for IPv4 and IPv6 clearnet connections. On multi-homed systems, Bitcoin Core previously left source address selection to the operating system routing table because existing bind options apply exclusively to listening sockets. The change resolves long-standing issue #6476, trial-binds the address at startup, and fails outbound connections closed rather than leaking traffic through fallback interfaces if binding fails.
Data
thread read through 2026-09-12 (45 statements), head 5baa78a79c
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: P2P
Categories
P2P
P3 · user request (ranking pass: Niche multi-homed configuration need; placed with the other opt-in operator options.)
Adds the `-outboundbind` configuration option to allow multi-homed nodes to select their local outgoing source IP address. This addresses long-standing issue #6476 ('Does not use bind to local address for outgoing connections'), providing clear utility for specific network configurations while remaining reasonably deferrable.
Membership: Carries the P2P label and modifies connection establishment and address binding in src/net.cpp and src/netbase.cpp.
Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 0