Bootnodes or static nodes: how a private Besu network should find its peers
A team building a permissioned Besu network across several organizations or sites needs two answers before go-live: how a new node finds the network, and how known nodes stay connected. Bootnodes answer the first question. They are the nodes a new node contacts to discover the rest of the network. Static nodes answer the second. They pin known peers so that a node keeps trying to reconnect to them. Permissioning answers the question of who may connect at all, and it does that work on each node, not through the peer lists.
According to the Besu docs, static nodes are exempt from maximum peer limits, and Besu periodically reconnects to static nodes that are not connected. That makes them useful in small networks, where the Besu documentation recommends them to mitigate low peer counts. The limit of the mechanism matters just as much: static nodes do not stop other nodes from connecting. A peer that is not on your static list can still connect unless permissioning blocks it. Teams that treat the static list as an access list leave connections open that they meant to close.
Runtime changes made with admin_addPeer and admin_removePeer are not persisted across restarts, so any peer list that must survive a restart belongs in configuration. Before choosing between a bootnode list, a static-nodes.json file or both, confirm with your Besu version which options your node reads at startup and how each treats enode URLs that change after a rebuild. The Besu static nodes documentation and the Besu bootnodes guide set out the exact behavior.
Which peer discovery method fits which network
This table compares three ways to connect private Besu nodes: bootnodes only, a static-nodes.json file only, and both together. Read each row against your topology, since the right choice depends on network size, how often nodes restart and how much change control your consortium can handle. The main takeaway is that Besu actively retries static nodes, which makes them the stronger reconnection path in small networks, while bootnodes give new nodes an entry point. Confirm restart behavior for any change in your Besu version.
| Factor | Bootnodes only | static-nodes.json only | Both |
|---|---|---|---|
| Best fit | Networks where new nodes join through a known entry point and the peer set changes often | Small networks with a fixed set of nodes that must always connect | Permissioned networks with a fixed validator core plus an entry point for new nodes |
| Failure behavior | A new or restarted node needs at least one reachable bootnode to find peers | Besu periodically reconnects to unconnected static nodes after an outage | Losing one discovery path still leaves the other to reconnect nodes |
| Stable identity after total loss | Create the bootnode key pair before first start and assign a static IP so its enode stays stable | Each listed enode must match the peer's key, so a reissued key means editing every peer's file | Keep bootnode keys and IPs fixed, and update static entries for core nodes only when keys change |
| Peer limits | Confirm in your Besu version how bootnode connections count toward maximum peer limits | Static nodes are exempt from maximum peer limits | Static entries stay connected regardless of limits, so confirm bootnode behavior separately |
| Change without restart | Confirm in your Besu version whether a changed bootnode list is read without a restart | Runtime admin_addPeer and admin_removePeer changes are not persisted, so confirm how file edits apply | Runtime peer changes are temporary, so confirm which file changes need a restart |
| Operator effort | Publish and keep stable enode or ENR values for each bootnode | Maintain a static entry for every peer on every node | Maintain both lists and keep enodes consistent across them |
| Main risk | A bootnode with a changed address or key breaks discovery for nodes that depend on it | Static nodes do not stop other nodes from connecting, so permissioning must enforce access | Lists can drift apart, and a stale enode may go unnoticed until a failure |
How to configure bootnodes and static nodes in a private network
This sequence sets up private Besu nodes so they find each other reliably, keep stable enode identities through failures and stay permitted under the network's access rules. Each step closes with a check that the network behaves as designed.
Agree enode ownership across organizations
Before any node starts, the participating organizations agree who runs each bootnode and static node, who publishes its enode URL, and who may change the peer lists. Record this in a shared document or repository that every operator can read. The step is done when each bootnode and static node has a named owner and a named publisher for its enode, and every organization has confirmed the list in writing.
Generate and store bootnode key pairs
Each bootnode operator creates its node key pair before the first start, so the enode identity exists before the node is ever reachable. Store the private key file in the operator's approved secret store with access limited to the node's service account, and note that the local node key file is not encrypted by Besu. The check is that the enode derived from the public key matches the value written in the shared record, and that the private key is absent from configuration files kept in version control.
Assign static IP addresses to bootnodes
Give each bootnode a static IP address or a stable DNS-backed address that does not change when the host is rebuilt or rescheduled. Because the enode embeds the host address, a changing address breaks every peer list that references it. Confirm the addresses with the network team and open the agreed peer-to-peer port between the participating networks. The check is that each bootnode answers on its address from the other organizations' networks.
Write static-nodes.json and bootnode settings
Each node gets a static-nodes.json file listing the enode URLs of the peers it should always connect to, and a --bootnodes setting that points to the agreed bootnode enodes. Keep both files under the same change control as the genesis file. Check the file syntax and that every enode URL matches the published list before deployment. The check is that a node started with these settings logs connection attempts to the listed peers, and that no enode in the file belongs to a node you do not expect.
Align node permissioning with the peer lists
Static nodes do not stop other nodes from connecting; permissioning does. Update each node's local permissions configuration so that the node allows connections only to enodes on the agreed list, and confirm that account permissioning rules are consistent across the consortium. Test with a node outside the list to confirm it is refused. The check is that the permitted peers connect and an unlisted node cannot establish a connection.
Verify peer counts after first start
Start the bootnodes first, then the validators and RPC nodes, and read the peer count on each node through the JSON-RPC interface or the metrics endpoint. Compare the counts with the number of peers expected from the agreed topology. Investigate any node whose count stays low, since small networks depend on static nodes to avoid low peer counts. The check is that every node reports the expected peers and the bootnodes show connections from each participating organization.
Test reconnection after a bootnode restart
Restart one bootnode in a non-production copy of the network, then confirm that its enode is unchanged and that peers reconnect without manual intervention. Static nodes are reconnected periodically, so allow time for the reconnection cycle and watch the logs. Repeat the test with the static IP in place to confirm the identity and address survive a rebuild. The check is that the restarted bootnode regains its peers and that the enode in the shared record still matches the running node.
Add a new bootnode without restarting the network
To add a bootnode to a running network, the operator generates and stores its key pair, publishes the new enode through the agreed process, and then updates the --bootnodes setting and static-nodes.json on nodes that need the new entry. Runtime changes made with admin_addPeer are not persisted, so the file change must be made and applied as a configuration change. The check is that the new bootnode accepts connections from the agreed peers and that its entry appears in every updated peer list without disrupting block production.
Keeping bootnode enodes stable through a complete failure
The point to get right before go-live is that a bootnode's enode is derived from its node key, and the enode is what every other node records as the address to dial. To keep that enode stable after a complete failure, create the node key pair before the bootnode starts for the first time and assign it a static IP address. The Besu bootnode documentation describes both steps as the way to keep the enode intact if the whole node has to be rebuilt. If the key is generated on first start, a rebuilt host will produce a new identity, and every node that lists the old enode will need a new entry. Confirm with your platform team that the static address survives the failure modes you plan for, such as instance replacement, a new availability zone or a rebuilt virtual machine, because an address that changes silently breaks the same way a new key does.
The node key file is the most sensitive artifact in this design, and the Besu documentation states that the local node private key file is not encrypted. Treat it as a secret: restrict file permissions on the host, keep it out of source control and container images, and store an encrypted backup in a location with its own access controls, such as your secrets manager or an encrypted vault that your operators can reach during an outage. Record which key belongs to which bootnode and where the backup lives in your runbook. Anyone holding the key can impersonate the bootnode's identity, so a restore should be rehearsed and the restored enode checked against the recorded value before the node is trusted again. Where your policy requires hardware-backed key storage, the documentation points to a security module plugin such as the Besu HSM plugin, and that choice should be made before the key is first generated.
Because a static-nodes.json file or a --bootnodes value refers to the bootnode by its enode, any change to that enode forces an update on every node that references it. The update is a configuration change on each member's infrastructure, and in a multi-organization network it requires coordination with every operator, not only the one who lost the host. Keep a single list of approved enodes under version control, with an owner and a change record, so that a rebuilt bootnode can be reviewed against its expected identity and rolled out in one controlled change. Ask each participant to confirm how long their nodes take to pick up a new file and whether a restart is needed, because that determines how long part of the network may be unable to find the bootnode after a failure.
Security risks in peer discovery settings
Peer discovery settings decide which nodes can reach each other, but they are not the same as access control. The cards below separate what a peer list signals from what actually stops an unknown node from joining, and they name the places where a private network is most often exposed.
Static nodes are intent, not enforcement
A static-nodes.json file tells a node which peers to dial and keep reconnecting to. It does not stop any other node from connecting to it. Treat the file as a record of intended connections, and confirm with a test that a node outside the list is still refused by permissioning rather than accepted because it is missing from the file.
Node permissioning is the real gate
Node permissioning is the control that decides which peers a node accepts. Each node enforces its own permissions configuration file, so an allowlist that lists only known enodes is what keeps unknown peers out. Check that every node in the network loads that file, that the entries match current enodes, and that a rejected connection attempt shows up in logs.
Unencrypted node key files
The local node private key file is not encrypted. Anyone who copies it can impersonate that node's identity on the network, and the enode derived from it stays the same. Restrict file permissions, keep backups under the same controls as other secrets, and where your policy requires hardware-backed storage, confirm whether a security module plugin fits your validator and bootnode design.
Exposed P2P ports
Peer-to-peer traffic reaches nodes on their discovery and P2P ports. Bootnodes often sit on public addresses so that new nodes can find the network, which widens the exposure. Limit inbound access with firewall rules to the addresses that need them, keep RPC interfaces off the P2P path, and review which ports each role opens before go-live.
Drift between organizations' peer lists
In a consortium, each organization maintains its own peer lists and bootnode settings. Over time those lists fall out of step, so one party may dial stale enodes or keep an old address that another party has retired. Agree on a single source of truth for enodes and bootnodes, and check each participant's copy against it on a schedule.
Enode changes outside change control
Enode values change when a node key or its address changes, and a changed enode can silently break peer lists across the network. Route every key rotation, IP change and bootnode addition through change control, record the old and new enode, and confirm that all dependent peer lists were updated before the old identity is retired.
Adding bootnodes without restarting the network
Can a new bootnode join a running private Besu network without any restart?
Not as a blanket rule. A new bootnode can be started and its enode shared, but the supplied Besu documentation does not establish that every node picks up a new bootnode without a restart, so treat restart-free joining as something to prove in your own environment. Rehearse the change in a dev environment with the same Besu version, permissioning file and node roles before touching a live network. Confirm the exact behavior for your Besu version with the Besu bootnodes documentation and the release notes for the version you run.
What must other operators agree on before we add a bootnode?
Every organization that runs nodes on the network needs to know the new bootnode's enode URL, its host address, and which party owns it. Agree who generates and stores the node key, who assigns the static IP address, and who approves the change. Each operator then updates its own configuration, since no single party can change another operator's node. Also confirm that the new bootnode is allowed by the permissioning rules that every node enforces locally, because a bootnode that other nodes cannot connect to is of little use.
What is the difference between admin_addPeer and a persisted static-nodes.json entry?
The admin_addPeer and admin_removePeer calls change a node's peer set at runtime, but they are not persisted. After a restart the node loses those changes and reads its configuration again. A static-nodes.json file, by contrast, is read at startup and holds the peers the node should keep reconnecting to. For a change that must survive restarts, write it to the file on every node that needs it, and use the runtime calls only for short-term testing or troubleshooting.
Do static nodes let a new bootnode connect even when permissioning blocks it?
No. According to the supplied Besu static nodes documentation, static nodes do not stop other nodes from connecting, and permissioning is the mechanism that restricts connections. Adding a static entry for a bootnode does not grant it access. Check the node permissioning file on each node, and confirm that the new enode is on the allowlist before rolling out the change.
How should we roll out a bootnode change one node at a time?
Work in small, reversible steps. First, start the new bootnode with its key pair created in advance and a static IP address so its enode stays stable. Then update one non-validator node, restart it in a controlled window, and confirm it reconnects to the expected peers. Check peer counts and block import on that node before changing the next one. Keep validators for last, and keep a written rollback step for each node. Repeat the same sequence in the dev environment first.
How do we keep a bootnode enode stable if the bootnode fails completely?
Create the node key pair before the bootnode first starts, then assign it a static IP address. The enode is derived from the public key and the address, so a restored node with the same key and address keeps the same enode, and existing peers can keep using it. Store the key file in your key management process, back it up under access controls, and record the enode in your configuration under source control. Without the backed-up key, a rebuilt node gets a new enode and every peer config that references the old one must be changed.
How much does it cost to add a bootnode, and who pays for it?
No figure for this change is supplied here, so ask for one that reflects your environment. The main cost components are the time of the engineers who plan, rehearse and roll out the change, the infrastructure for the new node with a static address, and the coordination effort across each organization on the network. Ongoing costs are the monitoring and key custody that the bootnode needs for as long as it runs. A written scope for the rehearsal, rollout and rollback steps is the most useful input for an accurate quote.
Limits to confirm in your environment
Peer discovery depends on details that vary by Besu release, network layout and operator. The cards below list what to confirm in your own environment before you pick a discovery design and write it into your node configuration.
Behavior in your Besu release
Besu ships roughly monthly, using calendar versions such as 26.10.0, dated October 16, 2026. Peer discovery options, flag names and defaults can change between releases, so read the release notes for the exact version you run. Confirm how static node handling and bootnode parsing behave in that build, and retest after each upgrade before it reaches production validators.
JDK 25 requirement from 26.6.0
Besu 26.6.0 requires JDK 25 to build and run. Every node in the network needs a matching runtime, including bootnodes, which are often small hosts that teams forget when they plan image updates. Check your base images, configuration management and container builds so that a bootnode is not left on an older JDK after the rest of the network moves forward.
Firewall rules for peer ports
Nodes must reach each other on the peer-to-peer port, and bootnodes must accept inbound discovery and connection traffic from every participant. Confirm that firewall, security group and network policy rules allow traffic between validator, RPC and bootnode subnets in both directions. Test with a connectivity check from each zone, because a rule that allows only outbound traffic will look correct on paper and still leave nodes isolated.
DNS and IP stability
An enode URL embeds an IP address or hostname, so any change to the address changes the identity other nodes use to reach it. Confirm whether your bootnodes and static nodes get fixed addresses, whether DNS records are managed by you, and how long records take to propagate in your environment. A bootnode whose address changes after a restart forces every node that references it to be updated.
Bootnode reachability in a closed network
In a closed network, a bootnode that is down or unreachable can stop new nodes from finding peers, even when existing nodes stay connected. Decide how many bootnodes you run, where they sit, and which operator owns each one. Confirm that a new node can join when one bootnode is offline, and document the fallback path your team will use, such as static node entries on existing peers.
Questions buyers ask before choosing peer discovery
Do I need bootnodes, or can I use static nodes instead?
Neither is strictly required for every network, but most private networks use one or both. Bootnodes give a new node an entry point to find peers, while static nodes are a fixed list of peers that Besu keeps trying to reconnect to. Static nodes are the simpler choice for a small, known set of validators because they do not depend on a discovery service. Bootnodes suit larger or changing topologies where new nodes join over time. Many teams use static nodes for validators and bootnodes for everything else, and the right mix depends on how many nodes you run and how often membership changes. Confirm the approach against the Besu documentation for your release before you commit.
What drives the cost and effort of setting up peer discovery?
Peer discovery is a small configuration task on paper, so most of the effort lies in the decisions around it. The main drivers are the number of nodes, the number of organizations that run them, whether each node has a static IP address and stable DNS, and how your firewalls and load balancers handle peer traffic. Each organization that runs its own nodes must agree on the peer list, record enode URLs, and update them when hosts change. One-time work includes designing the topology, generating and protecting node keys, and writing the configuration. Recurring work includes updating peer lists after replacements and keeping configuration under source control. Ask any partner to show the written scope, the list of nodes covered and the change process for peer updates.
How long does it take to get a private Besu network connected?
The time to connect nodes depends mainly on infrastructure readiness rather than on the peer discovery settings themselves. Once hosts, networking rules, DNS or static addresses, and node keys are in place, adding peer lists to a few nodes is quick to apply. Delays usually come from waiting on firewall changes, approvals for new hosts, agreement between organizations on who runs which bootnode, and testing that peers stay connected after restarts. A realistic plan allows time for a test network that rehearses restarts and host failures before production. Ask for a timeline tied to named milestones and to the access you need from your network and security teams, rather than a single duration.
What does my team need to provide for this work?
Your team needs to supply the infrastructure and the decisions. That includes hosts or containers with fixed addresses, network rules that allow the P2P port between the nodes that must connect, a place to store node key files securely, and a named owner for each bootnode and validator. Engineers should also be able to review the configuration, run the node logs and peer counts, and approve changes to the peer list. Security teams usually need to review which ports open and how peer traffic is limited. If you run Prometheus or another monitoring stack, having peer metrics visible from day one makes problems much easier to spot.
Can my own team set up peer discovery without a partner?
A capable platform team can set up peer discovery alone if it has experience with Besu, container or host networking, and key management. The configuration is short, and the Besu documentation covers the options. The harder part is making the setup survive failures: keeping enode URLs stable after a bootnode is lost, handling restarts, and proving that the network recovers without manual rework. Teams that lack this experience often find the gaps during an incident rather than during testing. A partner can help by reviewing the design, building a rehearsal network and documenting the runbook. Whichever route you choose, agree the scope and deliverables in writing before work starts.
How does peer discovery change when more organizations join later?
Each new organization adds nodes that must find the existing network, so the peer list and bootnode plan need to grow with it. A new member usually needs the current bootnodes or static peer list, its own node keys, and approval under the network's permissioning rules. Static peer lists that are not shared across organizations can leave some nodes unreachable, so the consortium should agree on who maintains the shared list and how changes are announced. Adding a bootnode can be done without restarting the whole network, but each node that uses it must still be configured and checked. Confirm how your governance model assigns ownership of bootnodes and static peers before the first partner joins.
What goes wrong if a bootnode fails and its address changes?
If a bootnode loses its key or gets a new address, its enode URL changes, and every node that points to the old URL loses that entry point. To keep the enode stable through a complete failure, create the node's key pair before starting it and give it a static IP address. Store the key file in a backed-up, access-controlled location so a rebuilt host can reuse the same identity. Also keep static peer lists in source control so you can update them quickly. Test this in a rehearsal network by removing a bootnode and confirming the rest of the network reconnects, because a key that is lost during an incident cannot be recovered from the running network.
Who owns bootnodes and static peer lists in a consortium
In a multi-organization network, the question of who owns bootnodes and the static peer list needs a written answer before go-live. Each operator typically controls its own nodes, but the enode URLs that identify them must be agreed and published to every member, and changing one is a coordinated act rather than a local edit. Treat the shared list of enodes as a governed artifact with a named owner, an approval step for changes, and a record of which key pair and address each enode corresponds to.
A bootnode run by one party affects everyone. Every new or restarting node in the consortium may use the bootnode to find its first peers, so if that operator loses the node, changes its IP address, or regenerates its key, nodes that rely on it may struggle to join the network. For this reason, the consortium should decide how many bootnodes exist, which organizations host them, and how each is hardened and monitored. Confirm the operating expectations for bootnode hosts in writing, including who is notified of planned maintenance and how a replacement bootnode is introduced.
Before go-live, agree on the governance process itself: who may propose a new enode, who approves it, how the agreed list is distributed, and how members confirm they have applied it. Keep the peer list under source control with the genesis and permissioning configuration so that every change has an audit trail. The permissioning rules each node enforces locally remain the control on who may connect, so the peer list should be read as a discovery aid that the consortium has agreed to, not as the access control itself. Ask each member to confirm, in writing, which enodes they run and which they have configured.
How DeployOpen scopes peer discovery work
Peer discovery touches every node in the network, so the work is scoped as one connected effort: design the topology, prepare configuration and keys, prove the network reconnects after failures, then hand the runbook to your operators. Each card below is a separate deliverable that can be agreed in writing before work starts.
Discovery design review
We review which nodes act as bootnodes, which are listed as static nodes, and which peers each organization is expected to reach. The output is a written topology that states who owns each bootnode, which IP addresses or DNS names they use, and whether the network relies on static-nodes.json, --bootnodes, or both. We also confirm that permissioning, not static nodes, controls which peers may connect, so the design does not assume static nodes block outside peers.
Configuration and key handling
We prepare node key pairs before any bootnode starts, so each enode URL is known in advance and can be published to the other organizations. Static IP addresses are assigned where a bootnode must survive a full failure. The static-nodes.json file and the --bootnodes option are written under source control, with each value traced to the owner who supplied it. Key files are stored with the access controls your key management policy requires, since the local node private key file is not encrypted by default.
Verification and rehearsal
We test discovery in a dev or staging network before production. Tests cover cold starts with only bootnodes reachable, recovery after a bootnode is rebuilt from its saved key and static IP, and the addition of a new bootnode while the network keeps running. Results are recorded as peer counts and reconnection times per node, so your team can see which nodes stayed isolated. Runtime admin_addPeer changes are tested separately because they are not persisted across restarts.
Operations handover
We hand over a runbook covering how to replace a bootnode, how to add one without restarting validators, how to read peer count metrics, and who approves changes to the peer list. The runbook names the monitoring alerts that signal a node has lost all peers. Your operators receive a walkthrough of the rehearsal results, so they know which failures the design tolerates and which need an operator decision.
How DeployOpen works on this
DeployOpen plans the peer discovery design for your permissioned Besu network before any node is built, then implements it in infrastructure you control. The work covers bootnode placement, static node lists, permissioning and the runbook your operators follow when a node moves or fails.
How we scope
- Inventory every validator, RPC and bootnode, with its planned host, network segment and whether it faces applications.
- Confirm which organizations run which nodes, since each owner maintains its own node configuration.
- Agree the written scope in advance, including the peer discovery design, deliverables and timelines. Engagements are fixed-scope.
How we build
- Generate node key pairs before first start and record each enode URL under version control.
- Assign static IP addresses or stable DNS names to bootnodes so their enodes survive a rebuild.
- Configure static-nodes.json and local permissioning together, then test that unlisted nodes are refused.
How we hand over
- Deliver the peer discovery design, node inventory, enode register and configuration files with the rationale for each choice.
- Document the procedure for adding a bootnode or replacing a node key, including the restart order that keeps quorum.
- Walk your operators through a rehearsed failure and recovery exercise on the dev or test network before go-live.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Review peer counts and connection logs after each Besu upgrade, since startup behavior can change between releases.
- Confirm with your Besu version and vendor documentation before relying on any discovery option in production.

