When a Besu network needs IPv6 or dual-stack networking
Besu peers use IPv4 by default, but they can also run over IPv6 only, or over both protocols at once (dual-stack). A permissioned network needs to consider this when its hosting environment is moving to IPv6, when some participants or cloud subnets expose only IPv6 addresses, or when a consortium member must reach peers that are reachable only over the newer protocol. The Besu IPv6 docs describe the mode as a choice made per node: --discovery-mode is set to v4 by default, and the IPv6 options are added alongside the IPv4 settings rather than replacing them. Before planning a change, confirm with your network team which address families your load balancers, firewalls, DNS and cloud subnets actually route for each node, because a node can only advertise what its host can reach.
The decision is mostly about reachability, not performance. Dual-stack lets one node keep serving IPv4 peers while it also listens for IPv6 peers, and a discovery v5 Ethereum Node Record can carry an IPv4 and an IPv6 address at the same time. That matters for bootnodes and for any node you expect other members to find through records rather than fixed enode addresses. Ask each consortium member which protocol their nodes will use, and whether they need to reach your validators and bootnodes over IPv6, before you agree on a discovery mode for the whole network.
A practical first step is a mixed test network with two or three nodes, one per address family combination you expect in production. Confirm in that test that peers connect, that the advertised addresses are the ones your firewall rules allow, and that the node logs show the expected protocol for each connection. Keep the IPv4-only configuration as a documented fallback until the IPv6 path has been verified end to end. The exact flags, port defaults and ENR behavior should be checked against the current Besu IPv6 documentation for the release you run.
Which IPv6 and discovery options fit each network
This table compares the IPv4 default, an IPv6 listener alongside IPv4, and dual-stack advertisement under discovery v4, v5 and BOTH. Read each row against your network's addressing plan and your bootnode design. The main takeaway is that discovery mode and ENR bootnodes decide whether IPv6 addresses are advertised to peers, so confirm both before you change ports.
| Network situation | Recommended setting | What it fits | What to confirm in the docs |
|---|---|---|---|
| IPv4-only network, no IPv6 plans | --discovery-mode V4 (default) | Existing permissioned networks with IPv4 addressing and static peer lists | That no IPv6 options are required for your peer set |
| Dual-stack, IPv4 peers with IPv6 reachable | IPv4 primary options plus --p2p-host-ipv6 and --p2p-port-ipv6 | Nodes that must accept or reach IPv6 peers while keeping IPv4 as the primary path | The IPv6 port default of 30404 and firewall rules for both families |
| Advertise both addresses in node records | --discovery-mode V5 or BOTH | Networks that want an Ethereum Node Record to carry an IPv4 and an IPv6 address together | Which discovery versions your peers support before you switch modes |
| ENR-based bootnodes | --discovery-mode V5 or BOTH | Bootnodes that publish ENR records instead of only IPv4 enode addresses | That bootnodes and every peer run a compatible discovery mode |
| IPv6-first migration | Dual-stack with BOTH, IPv4 kept running | Enterprise networks moving toward IPv6 without a single cutover date | Which parts of your stack, such as load balancers and monitoring, accept IPv6 |
| Mixed-version peer set | Keep V4 until all peers are upgraded | Networks where some operators run older Besu releases | The release notes for each Besu version in your network before changing discovery mode |
| Firewall and segmentation review | Open the IPv6 P2P port alongside the IPv4 port | Zones where IPv6 rules are managed separately from IPv4 | Whether your security team has approved IPv6 policies for the P2P port |
How discovery v4 and v5 change peer advertisement
Discovery mode decides what a Besu node advertises to the network, so it is the first setting to settle when you add IPv6. Discovery v4 is the default under --discovery-mode, and on its own it does not carry an IPv6 address in the way a dual-stack node needs. Discovery v5 uses Ethereum Node Records (ENRs), and an ENR can carry an IPv4 and an IPv6 address at the same time. To advertise both addresses, or to use ENR bootnodes, the node must run with --discovery-mode set to V5 or BOTH. Plan the mode change as a deliberate step, not a side effect of adding --p2p-host-ipv6.
The main trade-off is between staying on v4 only and running a mixed bootnode set during migration. A v4-only node keeps the simplest, most widely understood peering, but peers that reach it over IPv6 will not learn its IPv6 address from discovery. A BOTH node advertises more, yet its neighbors must be able to interpret ENR records, and a bootnode list that mixes plain enode entries with ENR entries needs checking on every node. During a transition, many teams run a mixed set so that old and new nodes can still find each other. Keep the mixed period short and record which nodes are on which mode.
Before you change any node, verify the bootnode list against your own environment. Confirm which bootnodes are v4 enode URLs, which are ENRs, and which addresses each one publishes, including whether an IPv6 address is reachable from every site that needs it. Confirm that your firewall and routing rules allow the IPv6 P2P port you set with --p2p-port-ipv6 (default 30404) in addition to the IPv4 port. Check the exact flag names and accepted values for your Besu release in the Besu IPv6 and dual-stack documentation before you write the configuration.
How to set up dual-stack Besu peers step by step
This sequence takes a Besu node from an IPv4-only peer setup to peers that connect over both IPv4 and IPv6, with a check at each stage so the team can confirm each address family works before moving on.
Inventory addressing and firewall rules
The network team lists the IPv6 prefixes assigned to each node's subnet, the global or routable addresses each node will use, and the firewall and security group rules that currently allow the P2P port over IPv4. They confirm that the same P2P port is permitted over IPv6 in both directions, and that any cloud load balancer or NAT path in front of the node does not sit between peers. The output is a written table of node, address family, address and port. The step is done when every planned peer has a reachable IPv6 address and the rules match that table. Ask your cloud or data center provider to confirm IPv6 routing and any default-deny policies for the subnet, since these vary by environment.
Set the IPv4 primary P2P options
The platform engineer keeps the existing IPv4 settings as the primary path for the node. This means confirming the P2P host and P2P port values that peers already use, so the node's current connections do not change while IPv6 is added. Review the configuration file under version control and record the values in the change ticket. The check is a restart in a test environment followed by confirmation that the node starts, listens on the IPv4 P2P port and keeps its existing IPv4 peers. Do not change the production port in the same change as the IPv6 work.
Add IPv6 host and port options
Next, the engineer adds the IPv6 options to the node configuration. The main settings are the IPv6 P2P host option, which sets the address the node binds and advertises for IPv6, and the IPv6 P2P port option. Besu documents a default IPv6 P2P port of 30404, so the team should keep that value unless the firewall plan requires a different one. Apply the change on one node first. The check is that the node logs or reports a listening socket on the IPv6 address and port, and that a host on the same IPv6 network can open a TCP connection to that port.
Choose the discovery mode
The network architect decides how peers find each other. Discovery v4 is the default and is the baseline for IPv4-only networks. To advertise both address families in a node record, or to use Ethereum Node Records (ENR) as bootnodes, the mode must be set to V5 or BOTH through the discovery mode option. Confirm which mode each node in the network will run, and record the choice with the reason. Before rollout, check whether every client in the network supports the mode chosen, because mixed modes can leave some peers unable to find others. The check is that the node starts with the selected mode and reports the expected discovery service in its startup log.
Distribute ENR or enode bootnodes
The network operator generates the bootnode list for the network. If the chosen mode uses ENR records, each bootnode entry should carry the node's IPv4 and IPv6 addresses where they are needed. If the network still uses enode URLs, the team confirms which address family each entry uses. The list is then distributed through the same change-controlled channel as the genesis file, so every operator uses identical entries. Ask each operator to confirm receipt and to keep the previous list until the migration is complete. The check is that a freshly started node with only the new bootnode list discovers at least one peer on each address family it advertises.
Verify peer connections on both stacks
Finally, the operations team checks peer connections on each address family and on every node in the network. Using the node's peer count and peer list through the JSON-RPC API or the admin interface enabled in the test environment, they confirm that IPv4 peers remain connected and that IPv6 peers appear with IPv6 addresses. They also confirm that block production or block import continues normally after the change. Record the results for each node in the change record. The step is complete when each node shows peers on both stacks for a sustained period under normal load, and when a rollback path is documented. Keep a configuration backup taken before the change so the previous IPv4-only settings can be restored quickly.
Security and operational risks of exposing Besu peers on IPv6
Adding an IPv6 listener gives a Besu node a second network surface with its own ports, firewall rules and peer identity. The cards below cover the risks that appear when that surface is opened, and each one names a check to make before peers are allowed to connect.
New ports and firewall rules
Dual-stack adds a separate P2P listener through --p2p-port-ipv6, which defaults to 30404, alongside the IPv4 P2P port. Each address family needs its own inbound rules, and an IPv4 rule does not cover IPv6 traffic. Check that the IPv6 P2P port is allowed only from expected peer ranges, that the RPC and metrics ports stay bound to the interfaces you intend, and that security groups, host firewalls and network policies are reviewed for both stacks at the same time.
Permissioning on the new address family
Node permissioning in Besu is local to each node, so an allowlist that works over IPv4 is not automatically applied to IPv6 connections in the way you expect. Each node's permissions configuration file must list the peers you accept, and every node in the network should be checked against the same membership list. Test that a peer outside the list is refused over IPv6 as well as IPv4 before you rely on the restriction.
Node key identity across stacks
The node private key identifies the node on the peer network, and Besu's documentation says the local key file is not encrypted. Dual-stack does not create a second key, but the same key now backs a node that is reachable over two addresses, so a leaked key lets an attacker impersonate that node on either stack. Confirm who can read the key file, restrict its permissions, and decide with your security team whether hardware-backed storage through a security module plugin is required for validator and bootnode identities.
Monitoring both stacks
Besu exposes Prometheus metrics through --metrics-enabled, but a dashboard built for IPv4 peer counts can hide an IPv6 partition. A node may show healthy totals while most of its IPv6 peers are missing. Track peer counts and connection failures per address family, alert when either falls to zero, and confirm that scrape targets reach the metrics endpoint over the path your monitoring server actually uses.
Change control when peers move
Moving a peer to a new IPv6 address changes what other nodes must trust and allow. Bootnode lists, static peer files, firewall rules and permissioning entries can all point at the old address. Treat an address change as a change request with a named owner, a rollback step that restores the previous settings, and a verification run that confirms every node in the consortium can still reach the moved peer.
Discovery mode and advertised addresses
Discovery defaults to v4 through --discovery-mode, and v5 Ethereum Node Records can carry both an IPv4 and an IPv6 address. Advertising a wrong or unreachable address spreads that error to other peers, while enabling V5 or BOTH without checking records can expose addresses you did not intend to publish. Review which addresses each node advertises, confirm the discovery mode is set the same way across the network, and test that ENR bootnodes resolve from outside your network before go-live.
Questions teams ask before running Besu over IPv6
How much effort does a dual-stack move to IPv6 take?
The effort depends less on the Besu flags than on the network around them. Enabling IPv6 on a node is a configuration change, but the work includes confirming that each host has a routable IPv6 address, that firewalls and security groups allow the IPv6 P2P port, and that every peer you depend on is reachable over the same path. Teams with many validators and bootnodes across several clouds or data centers have more paths to check than a single-site network. Ask any partner to break the work into network review, configuration changes per node, firewall changes, and testing, and to tell you which of those items your team already owns.
Can our in-house team configure Besu for IPv6 without a partner?
Often yes, if the team already runs Besu and has ownership of the host network, firewall rules and change control. The Besu settings for dual-stack are documented, and the hardest parts are usually organizational: getting IPv6 addressing approved, updating network policy, and proving the change on a staging network first. A partner adds value when the team lacks network engineers familiar with IPv6 routing, when several organizations share a consortium network that must change together, or when the change must be documented as evidence for an assessor. Compare the in-house effort against that list before deciding.
What do we need from the network owner before the work starts?
The network owner must confirm the addressing plan and the routing path before any Besu node changes. Ask for the IPv6 prefixes assigned to each site, whether hosts receive global or unique local addresses, which firewall or cloud security layers sit between peers, and whether a load balancer or NAT device rewrites traffic. Also agree on the change window, the rollback approach, and who approves a change to the P2P port. Without these answers, a node may appear configured while peers still cannot reach it.
Does enabling IPv6 change how existing IPv4 peers connect?
Dual-stack is designed so that IPv4 remains the primary path. Besu peers can communicate over IPv4 by default, and IPv6 options such as --p2p-host-ipv6 and --p2p-port-ipv6 add a second listener without removing the IPv4 settings. Existing IPv4 peers should continue to connect as before, provided the IPv4 host and port settings are unchanged. The risk comes from changing discovery mode. Moving to --discovery-mode V5 or BOTH changes how nodes advertise addresses, so confirm the effect on peer discovery in a test network before applying it to production validators.
Which discovery mode should we choose for a dual-stack network?
Choose the discovery mode based on whether you need to advertise both address families and use ENR bootnodes. Discovery is set with --discovery-mode and defaults to v4. Discovery v5 Ethereum Node Records can carry an IPv4 and an IPv6 address at once, and --discovery-mode V5 or BOTH is needed to advertise both or use ENR bootnodes. Confirm which bootnode format your other participants publish, because a mismatch can leave nodes unable to find each other even when the host networking is correct.
How should we test dual-stack Besu before go-live?
Test on a separate network that mirrors your production topology, with the same firewall rules and the same address families. Check that each node advertises the expected addresses, that IPv6-only and IPv4-only paths both connect where you expect, and that peers reconnect after a restart. Verify that blocks propagate across the mixed network and that monitoring shows peer counts for each path. Run the same checks after each Besu upgrade, since release notes can change defaults. Ask a partner to show which tests they run, and keep the results as change evidence.
What recurring work does an IPv6 setup add after go-live?
A dual-stack network adds recurring checks rather than a large ongoing project. Teams should watch peer counts by address family, review firewall rules when addresses or prefixes change, and retest discovery after each Besu release, because the project ships roughly monthly. Costs recur through staff time for monitoring and change control, and through any retainer you agree for support. Ask any partner to separate one-time configuration and testing from ongoing monitoring and upgrade testing so you can budget each part.
How DeployOpen scopes and delivers Besu IPv6 networking
DeployOpen plans, builds and documents IPv6 and dual-stack networking for Hyperledger Besu nodes inside your own infrastructure. Each engagement starts from a written scope that fixes which peers, ports and discovery modes are in play before any configuration changes.
How we scope
- Inventory every Besu node, its current P2P port and whether its network path supports IPv6 end to end.
- Agree in writing which discovery mode (v4, v5 or BOTH) each node class will run and why.
- Record firewall, load balancer and DNS dependencies so the scope names every change needed for IPv4 and IPv6 traffic.
How we build
- Configure IPv4 primary options alongside IPv6 options such as --p2p-host-ipv6 and --p2p-port-ipv6 on a test network first.
- Verify that peers connect over each address family and that ENR records advertise the expected addresses.
- Confirm that IPv6 port rules match the planned P2P port, including the default IPv6 port of 30404, on every host.
How we hand over
- Deliver the configuration files, network diagrams, address and port tables and the firewall change record for your review.
- Document the test cases used to prove IPv4-only, IPv6-only and dual-stack peering, with the results for each node.
- Walk your network, security and operations teams through the runbook for adding nodes and rolling back to IPv4 only.
How we support
- Ongoing support, upgrades and periodic re-testing of peering paths are available as a retainer after handover.
- Review each Besu release for changes to discovery or P2P options before you schedule an upgrade on a dual-stack network.
- Confirm with your team and the Besu documentation which options apply to the exact release you run in production.
