Hyperledger Besu backup and restore: what a node cannot recover from peers
A regulated operator running Besu nodes in its own infrastructure needs to know, before a disk fails or a database corrupts, which parts of a node it can rebuild and which it cannot. A node that falls behind can resync from peers, but peers do not hold everything that makes a node *your* node. The genesis file, the node key, the configuration and the data directory each play a different role, and each needs its own recovery answer. The Besu backup documentation, linked below, sets out the baseline: keep the genesis file under source control, place the data directory on a separate volume passed with --data-path, and take periodic copies of that directory using tools such as cron and rsync, S3 archives or tar.gz files.
The genesis file is the easiest item to protect and the most costly to lose, because it defines the chain a node must join. Store it in version control with review on every change, so the team can prove which version a node was started with. The node key is different: the Besu documentation states that the local node private key file is not encrypted, so its backup copy needs the same access controls as any other secret. Restoring a node with a new key changes its identity on the network, so decide in advance whether restored nodes keep their original keys. Confirm with your own security team how the key file is stored and who can read the backup archive, and check whether an HSM plugin is part of your design, since that changes where the key lives.
Keeping the data directory on its own volume lets you snapshot or copy it without touching the operating system, and lets you restore by stopping the node, optionally moving the broken directory aside for analysis, and putting the last known good backup back in the same location. Test that sequence on a non-production node, because a backup that has never been restored is an assumption rather than evidence. Plan backups before every upgrade as well: the Besu 26.10.0 release notes state that the Bonsai database auto-upgrades on first start and older versions cannot open it, so a pre-upgrade backup is the only practical rollback. Ask your team to record backup frequency, retention and restore duration for each node, since those figures become resilience evidence.
Which Besu assets to back up and why each one matters
A Besu node can resync chain data from peers, but several files it depends on exist only in your infrastructure. Each asset below has a different location, a different owner and a different way of breaking the node, so the backup plan has to cover each one separately.
Genesis file
The genesis file defines the chain's starting state, chain ID and consensus settings, and every node in the network must start from the same version. Keep it under source control so a rebuilt node can be started from a reviewed copy. Check that the copy in your repository matches the file the running network was launched with, since a drifted genesis can stop a node from joining the network.
Node private key
The node key identifies the node on the peer-to-peer network and is stored as a local file. Besu documentation states this file is not encrypted, so the backup copy needs the same protection as the live key: restricted access, encrypted storage and a documented owner. If the key is lost, the node gets a new identity and must be re-admitted through node permissioning. Teams using hardware-backed storage should record where the key material sits.
Node configuration and permissions files
Command-line settings, configuration files and the local permissions files for node and account permissioning define how a node behaves and who it accepts. Store them in version control with secrets removed, then keep the deployed copies in your backup set. A restore that brings back chain data without the permissions files can leave a node connecting to the wrong peers or accepting accounts it should refuse.
Data directory on a separate volume
Mount the data directory, set with --data-path (default /opt/besu/database in the Docker image), on its own volume so operating system changes and container rebuilds do not touch chain state. Back it up on a schedule with tools such as rsync, tar.gz archives or S3 copies. Snapshots taken while the node is writing can be inconsistent, so confirm your method against the docs before relying on it.
JSON-RPC credentials and TLS material
Besu does not terminate HTTPS itself, so certificates, the credentials file for username and password authentication, and any JWT public keys sit with your reverse proxy or the node configuration. Back them up with the same care as private keys, and record their expiry dates. Losing them does not corrupt chain data, but applications lose access until the material is reissued, which can stop a payment or settlement flow.
How to schedule backups of the Besu data directory
Schedule backups of the data directory on a fixed cadence, and set retention before the first run. The Besu backup guidance points to periodic copies of the data directory passed with --data-path (default /opt/besu/database in the Docker image), taken with tools such as cron and rsync, S3 archives or tar.gz files. Frequency is a trade-off between how much chain state you are willing to resync or replay after a failure and how much storage and I/O the copies consume. Retention should cover more than the most recent copy, because a corrupted node may be backed up in a bad state before anyone notices. Keep the genesis file under source control and back up config.toml, node keys and permissions files on the same schedule, since those are the items a restore depends on. Confirm the retention window with your own recovery objectives and your change calendar.
Put the data directory on its own volume so the copy job and the restore target are isolated from the operating system. A separate data volume lets you snapshot or archive one mount point without touching system files, and it lets a failed OS rebuild leave chain data intact. Mount the volume where --data-path points, keep it out of the root filesystem, and make sure the backup job reads from that mount rather than from a path that might be a symlink to the OS disk. Choose between rsync to a second host, object storage uploads and compressed archives based on where your organization already keeps recoverable copies and who is permitted to read them, since node data is sensitive operational material. Ask your storage team to confirm snapshot support and copy throughput on that volume before you commit to a schedule.
Decide whether each backup runs against a stopped node or a live one, and test that choice against your own node version and storage layout. Copying files from a running node can capture a database mid-write, so a copy taken without stopping the node may not restore cleanly. Stopping the node for every backup gives a consistent copy but adds planned downtime to a validator or RPC node, which matters for a network that needs quorum. Filesystem or volume snapshots can shorten that window, but only if the snapshot is crash-consistent for the database layout your node uses. The Besu backup documentation does not settle this for every setup, so confirm the consistency behavior with the Besu release you run, your storage layout (Bonsai or Forest) and your snapshot tooling, then record the result as evidence before relying on it.
Backup methods and when each fits
This table compares cron with rsync, S3 object archives and tar.gz archives for copying a Besu data directory. Read each row against your own recovery targets and storage estate, because the supplied Besu backup guidance names these tools but does not rank them. The main takeaway is that the method you choose sets who owns encryption and offsite copies, and the upgrade rollback rule applies whichever method you use.
| Criterion | Cron with rsync | S3 object archive | tar.gz archive |
|---|---|---|---|
| Typical use | Scheduled copy of the data directory from the node volume to a second disk or host | Periodic upload of the data directory to an object store bucket | Periodic compressed snapshot of the data directory kept as a file |
| Offsite copy | Only if the target host sits in another site or account you control; confirm the network path | Usually offsite by design; confirm bucket region, replication and retention settings | Only if you move the archive offsite yourself; confirm the transfer and storage path |
| Restore speed | Fast when the target is local; confirm copy-back time against your restore test | Depends on download bandwidth and object count; measure in your own environment | Requires extraction before restore; measure decompression and copy time on your hardware |
| Encryption responsibility | Your team; transport and at-rest protection must be configured separately | Shared: confirm server-side encryption and key ownership with your cloud provider and security team | Your team; the archive is plain unless you encrypt it before storage |
| Operational effort | Low to moderate; monitor cron job success and disk space on the target | Moderate; manage credentials, lifecycle rules and access logging | Low to moderate; manage archive naming, retention and checksums |
| Consistency concern | Copy a stopped node or confirm the database is in a state the Besu docs accept for live copying | Same as rsync: confirm the snapshot is taken while the node is stopped or otherwise consistent | Same as rsync: archiving a running data directory may capture an inconsistent state |
| Rollback before upgrade | Take a copy before each Besu upgrade, because the Bonsai database auto-upgrades on first start | Take an object before each upgrade and keep it until the new version is proven | Create a dated archive before each upgrade and keep it until the new version is proven |
| What to confirm | Target host, retention count, alerting on failed runs | Bucket policy, retention, legal hold needs, egress costs quoted by your provider | Archive location, checksum method, retention, who can read the files |
Setting up backups and restore runbooks for a Besu node
This sequence puts the files a Besu node cannot rebuild from peers under source control and on a separate volume, schedules backups, and produces a restore runbook that has been tested before it is needed. The result is a node that can be stopped, rolled back and brought back to a known state with a documented procedure.
Place the genesis file under source control
The platform engineering lead commits the genesis file for the network to a version control repository that the node operations team can read and that has change review enabled. Every later change to genesis settings, including validator entries and chain parameters, goes through the same review. The output is a tagged commit that matches the genesis file in use on each node. To confirm this step, compare the checksum of the file on each node with the committed version and record any mismatch before the node is started or restored.
Mount a dedicated volume for the data path
The infrastructure team attaches a separate volume to each node and points the data directory at it with the --data-path option. In the Docker image, the default location is /opt/besu/database, so the volume mount should target that path or the option should be set to the new location. Keeping chain data off the operating system disk means that a full system volume, a reinstall or a container rebuild does not remove the database. Confirm the setting by starting the node once and checking that files appear on the new volume and not on the root disk.
Back up the node keys and configuration
The operator copies the node private key file and the node configuration file to the backup target, separately from the chain data. The node key identifies the node on the network, so a restored node that lacks it will present a different identity to its peers. The key file is not encrypted by Besu, so the backup location and its access controls must match the sensitivity of that key. Confirm the copy by checking that the restored key file produces the same node identity as the original when the node reports its identity on startup.
Schedule periodic backups of the data directory
The operator configures a scheduled job, for example with cron, that copies the data directory to a second location using rsync, a compressed tar.gz archive or an upload to object storage such as S3. Backups should run on a schedule the team can justify against the amount of data it is willing to replay or lose, and the retention period should be set in writing. Confirm each job by listing the most recent backup, checking its size and timestamp, and extracting one file from it to a scratch location. A backup that cannot be read is not a backup.
Take a backup before every Besu upgrade
Before the node moves to a new Besu version, the operator stops the node, takes a full backup of the data directory and records the current version and configuration. The Besu 26.10.0 release notes state that the Bonsai database upgrades automatically on first start and that older Besu versions cannot open an upgraded database. This makes the pre-upgrade backup the only rollback path, so the team should confirm the backup is complete before starting the new binary. The output is a labeled backup that is kept until the new version has run cleanly for the agreed period.
Write the restore runbook
The node operations lead writes a step-by-step runbook that names the people who may authorize a restore, the backup location to use and the exact commands for each step. The runbook follows the documented order: stop the node, optionally move the current data directory aside so it can be analyzed, restore the last known good backup into the same directory, then start the node. Each step lists the output that confirms it is complete. The runbook should be stored with the genesis file and reviewed whenever the node version or volume layout changes.
Test the restore on a non-production node
The team runs the runbook on a separate node or environment that is not part of the live network and records each step, the time it took and any deviation from the written procedure. After the restore, the operator starts the node and checks that it connects to peers, that it reports a block height close to the network, and that its logs contain no errors about database format or missing files. The test record, with dates and the Besu version used, is kept as resilience evidence. Any step that failed or needed an unwritten action is corrected in the runbook before the next test.
Why a backup before every Besu upgrade is the rollback plan
The backup you take before an upgrade is the only rollback path for the node's database. The Besu 26.10.0 release notes state that the Bonsai database upgrades automatically on first start, and that older Besu versions cannot open an upgraded database. Once a node has started on a newer release and migrated its data, reinstalling the previous binary will not bring it back. The practical rollback is to stop the node, restore the backup taken before the upgrade into the same data directory, and start the older version. Treat that pre-upgrade backup as part of the change record, not as a routine snapshot that might be out of date by the time you need it.
Besu ships calendar releases roughly monthly. The GitHub releases page lists 26.7.0, 26.8.0, 26.9.0 and 26.10.0 in the period from July to October 2026, and the same backup step applies to each of them. The list describes what has been published, not a schedule you can plan around, so confirm the release you run today, the one you will move to, and any intermediate versions your organization needs to stage. Check the JDK requirement for each target as well, since the 26.6.0 notes state that Besu requires JDK 25 to build and run. Your version path, change window and rollback owner should be written down before the first node is touched. Verify that each backup can be restored to a scratch host running the prior version, because a backup that was never restored proves little about rollback.
Protecting backup contents and restore access
A Besu backup is a copy of everything needed to rebuild a node, so it carries the same sensitivity as the node itself. The cards below cover the places where that exposure usually appears: the node key, the storage holding the copies, configuration secrets, restore permissions, network separation and retention.
Unencrypted node key in backups
The local node private key file is not encrypted by Besu. Any backup that includes the data directory or the key file therefore exposes the node identity to whoever can read the archive. Ask where the key file sits in your backup scope, whether it is copied in plain form, and who can decrypt the archive. Where hardware-backed key storage is required, confirm with your team whether the key can be kept out of the file-based backup altogether through a security module plugin.
Access to S3 and archive storage
Object storage buckets and tar.gz archives are often readable by more people than the node itself. A bucket policy that is broader than the node's operating team turns a backup into a copy of the chain state available to others. Check who holds read, list and delete rights, whether public access is blocked, and whether backup write credentials are separate from restore credentials.
Configuration files holding secrets
Node configuration files, JSON-RPC credentials files and JWT validation settings may contain or point to sensitive values. Backing them up alongside the genesis file and data directory copies those secrets into every backup set. Inventory which configuration entries are secrets, decide whether they belong in the backup at all, and confirm that the recovery process can retrieve them from a separate, controlled source.
Restore permissions on the data directory
A restore writes the last known good backup back to the data directory, so the account running the restore needs write access there. That same access can read or alter node state. Limit restore rights to a named operator role, run the node under a dedicated service account, and confirm that file ownership and permissions match what the node expects after the restore completes.
Separation of backup copies from the node network
A backup stored on the same host, subnet or volume as the node fails together with it. Copies that sit on a network reachable from the peer and RPC interfaces add an attack path to the backup store. Decide which copies stay local for fast restore, which move to a separate account or site, and which networks can reach each store. Document the boundary so audits can trace it.
Retention of old copies
Old copies can hold data, keys or configuration that should have been retired, and they may be the only copies that open under an older client version. Set a retention period for each backup tier, record who approves deletion, and keep copies taken before each upgrade for as long as a rollback could be needed. Confirm the retention rules with your records and legal teams before applying them.
Testing restores as resilience evidence
A backup that has never been restored is an assumption, not evidence. The strongest proof a resilience review can see is a dated restore drill on a non-production Besu node, run from the same backup set the production team would use, with the timing, the sync result and the sign-off recorded. The drill should restore the last known good backup into a scratch copy of the data directory, follow the restore steps from the Besu backup documentation (Besu backup and restore guide), and confirm the node rejoins the network and catches up to the head of the chain. Each run should produce one artifact set: the runbook version, the backup identifier, the Besu version, the start and end times, and the final block height compared with peers.
Write the runbook before the first drill, not during it. It should name who may start a drill, which backup is selected, where the restored data directory lives (the path passed to --data-path), how the restored node is started without touching the production peer list, and what counts as success. Record the time from the decision to restore to the node reporting it is in sync, because that figure is what a recovery time discussion will ask for. Confirm with your own environment how long a full restore takes at your chain size, since the figure depends on storage speed and the amount of history held. Keep the restored node isolated from validator keys and production RPC endpoints so the drill cannot disturb the live network.
Drills also test upgrades. Because the Bonsai database auto-upgrades on first start and older Besu versions cannot open an upgraded database, a rehearsal should include restoring a pre-upgrade backup and confirming the older client version can start from it, or documenting that it cannot. Keep the drill logs, the sync output and the sign-off in version control next to the runbook. Reviewers then see a repeating schedule of drills with consistent results, which is stronger than one successful test. Ask your team to define failure handling too: a failed drill should open a tracked finding with an owner and a date for retest. DeployOpen can help plan the drill schedule and evidence pack, but the evidence belongs to your organization and independent assessors decide what it proves.
Hyperledger Besu backup and restore questions buyers ask
How much does it cost to set up Besu backups in-house versus with a partner?
No supplied fact gives a price for Besu backup work, so the figure depends on your scope. In-house, you pay your engineers to design the volume layout, write the backup jobs, store copies off the node and run restore tests, and that time recurs as the network changes. With a partner, a fixed-scope engagement covers the same design and build work and is quoted from a written scope before work starts. Either way, ask each option to list one-time setup, recurring test and monitoring effort, and storage costs separately. DeployOpen does not publish prices, so a quote follows from the agreed scope.
What drives the effort of a Besu backup and restore project?
The main drivers are the number of nodes, the size and growth rate of each data directory, where copies must be stored, and how much evidence your regulator or auditor expects. More nodes multiply the backup jobs, retention rules and restore tests. Larger data directories increase transfer and storage time. Strict retention, encryption, off-site copies or separate access controls add design work. Each node also needs its genesis file, node key and configuration captured, which is simple for one node and more involved across a consortium with several operators. Ask for the effort split between design, build, testing and handover.
How long does a Besu node restore take?
Restore time depends on the size of the data directory, the throughput of the storage that holds the backup, and the time needed to stop the node, move the old data aside and start it again. Besu also needs to open the restored database, and a version upgrade can add time. No supplied fact gives a duration, so measure it in your own environment: restore a copy of a production-sized data directory onto the same class of storage and time each step. Record the result as part of your resilience evidence and repeat the test after major changes.
Can our own team set up Besu backups without a partner?
Yes, a capable operations team can do this with the Besu backup documentation, provided it has the skills to manage the node, storage and scheduling. The documentation recommends keeping the genesis file under source control, mounting a separate volume for the data path, and running periodic backups with tools such as cron, rsync, S3 archives or tar.gz files. The harder parts are proving that restores work, handling upgrades safely and documenting the process for auditors. If your team lacks time or experience with these, a partner can take the design and testing work under a written scope.
What do we need to provide for a Besu backup engagement?
Expect to provide access to the nodes, hosts and storage in your own infrastructure, the current Besu version and configuration files, the genesis file, and a list of the keys and secrets each node uses. You also need to tell the partner where backups may be stored, how long they must be kept, who may access them and which recovery targets your teams have agreed. Staff time from operations, security and compliance is required for reviews and restore tests. Confirm these inputs before the scope is written, because missing details are a common source of delay.
Do backups alone satisfy resilience reviews for a Besu network?
No. A backup is one control, and reviewers usually want to see that it was taken on schedule, stored securely, covered by access controls and proven to restore. They also expect documented procedures, recorded restore tests with results, and a link to how the backup supports your wider operational resilience plan. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications. Ask your assessor which evidence they accept and whether they need results from restores in your environment.
What must we do before upgrading Besu if we need a rollback?
Take a backup of the data directory before the upgrade. The Besu 26.10.0 release notes state that the Bonsai database upgrades automatically on first start and that older Besu versions cannot open an upgraded database. Without a pre-upgrade backup, rolling back to the previous version may not be possible. Test the restore path on a non-production node before you rely on it, and record the Besu version alongside each backup so you know which binary can open it.
How DeployOpen scopes and delivers Besu backup and restore
DeployOpen plans and implements backup and restore for Hyperledger Besu nodes inside infrastructure you control. The work covers what a node cannot recover from its peers, from the genesis file and node keys to a separate data volume, and ends with restore tests that you can keep as resilience evidence.
How we scope
- Inventory every file and volume each Besu node needs to restore, including genesis, node keys and configuration
- Confirm where the data directory lives, how it is mounted and which volume holds it
- Agree backup frequency, retention, storage location and who holds access, in a written fixed scope
- Define the pre-upgrade backup step for Bonsai database changes before any version change
How we build
- Place the genesis file under source control and document how each node version maps to it
- Configure the data path on a separate volume and schedule backups with tools your team already runs
- Write restore runbooks that stop the node, move the data directory aside and restore the last known good copy
- Protect node key files with access controls and document where hardware-backed storage would fit
How we hand over
- Deliver runbooks, backup job definitions and configuration files stored in your own repositories
- Record the restore test results, including timings and any gaps found, as documented evidence
- Walk your operators through a live restore on a non-production node before handover
- Document the rollback procedure for each Besu upgrade, including the backup that must exist first
How we support
- Available as a retainer for periodic restore tests, backup monitoring and review after each Besu release
- Retainers can cover upgrade rehearsals that check whether a backup opens on the target version
- Support scope, response expectations and test frequency are agreed in writing before work starts
- Ask us to confirm how a retainer would handle restores during an active incident on your network
