When the Hyperledger Besu ENTERPRISE profile fits a private network
If you run a permissioned Besu network and want a tested starting point instead of setting every sync and storage option by hand, the ENTERPRISE profile is the place to begin. Besu loads a pre-configured profile with the --profile option, and ENTERPRISE and PRIVATE are aliases for the same profile. It is designed for private network operators and expects two settings: --sync-mode=FULL and --data-storage-format=FOREST. Choosing it means you accept a full-sync, Forest-storage node as the baseline for your private chain, so the decision should be made deliberately rather than inherited from a sample configuration.
The profile sits within a client that has a clear position for this use case. Besu is an open source Ethereum execution client written in Java and licensed under Apache 2.0. It is a Graduated project of LF Decentralized Trust, and its maintainers document support for private networks using proof-of-authority consensus, specifically QBFT and IBFT 2.0, for enterprise and consortium environments. A profile is only a set of defaults, so the consensus choice, validator set and genesis design still need to be settled separately before the profile is applied. Confirm the consensus configuration in your own genesis file and with your consortium members before go-live.
Before you adopt the profile, check your current Besu version against the release notes, because the client changes quickly and several privacy, permissioning and consensus features have been removed in recent releases. Confirm that your build environment meets the JDK requirement stated in the release notes for your target version. Then plan a test node that starts with --profile=ENTERPRISE, and verify which options are in effect. Remember that an option set in your configuration file or on the command line overrides the same option in a profile, so a stray setting in your own file can silently change the outcome.
Which profile values to keep, override or replace
This table compares the ENTERPRISE profile with the other Besu profiles and with values you set yourself in the configuration file or on the command line. Read each row as a decision: what the profile sets, when it fits, and what to check before you keep it. The main takeaway is that ENTERPRISE fixes sync mode and storage format, while PERFORMANCE changes cache and execution, so these are separate choices.
| Profile or setting | What it sets | When it fits | Action for private networks |
|---|---|---|---|
| ENTERPRISE or PRIVATE | Sync mode FULL and data storage format FOREST | Private network operators running nodes that need full state | Keep as the base unless a documented requirement says otherwise |
| MINIMALIST_STAKER | Lightweight settings for staking setups (confirm exact values in the profile docs) | Staking nodes with a small footprint, not private consortium nodes | Avoid as the base for a private network unless you have confirmed its values fit |
| STAKER | Settings for staking operators (confirm exact values in the profile docs) | Staking operators on public-style networks | Confirm the sync and storage values before using it on a private network |
| PERFORMANCE | Larger RocksDB cache and parallel transaction execution | Busy networks where throughput and cache size are the constraint | Test before combining with ENTERPRISE, since it changes execution and cache settings |
| PERFORMANCE_RPC | Larger RocksDB cache and caching of the last 2048 blocks | Nodes serving heavy read traffic to applications over JSON-RPC | Measure read load first, then confirm the cache effect on memory in your environment |
| Your own option in the config file or CLI | Overrides the same option set in the profile | You need a value different from the profile for a specific reason | Record each override and confirm it is intended, since it wins over the profile |
| Sync mode or storage format override | Replaces the profile's FULL or FOREST value | Only when your storage plan or sync approach is documented and tested | Confirm the change with your Besu version and test a restore before go-live |
How to load the profile and verify the effective settings
This sequence loads the ENTERPRISE profile on a test node, places your own settings in the configuration file, and confirms which values the node actually applies. The result is a documented baseline you can repeat before any change reaches a production network.
Confirm the Besu version and runtime
The platform engineer checks the Besu version the test node will run and confirms the Java runtime it requires. Besu 26.6.0 release notes state that Besu requires JDK 25 to build and run, so the team should check that release's notes and the version they plan to deploy before starting. Done means the binary starts on a clean test host with the expected version string printed at startup.
Select the profile with the profile flag
The engineer adds the profile option to the startup command, using ENTERPRISE or its alias PRIVATE, which the configuration profiles documentation describes as one profile. Alongside it, the team should not yet add other tuning flags, so that any later difference can be traced to a single source. Done means the launch command or service unit contains the profile option and nothing else changes the storage or sync defaults.
Write your own settings in the configuration file
The engineer places the node's own values, such as network identifiers, data path, RPC exposure and permissioning file references, in the TOML configuration file rather than on the command line. Keeping them in one file makes the override order easy to audit and keeps the file under source control. Done means the file is committed to the repository and each key is documented with the reason it is set.
Apply the override precedence rule
The team reviews every key in the configuration file that also appears in the profile and records it in a short table. The profile documentation states that an option set in the configuration file or on the command line overrides the same option in a profile, so each overlapping key is expected to take the file value. Done means the table lists each overlap, its profile value and its file value, and the owner has signed off that the override is intentional.
Start the node and check sync and storage
The engineer starts the test node and checks that it reports FULL sync mode and FOREST data storage format, the two settings the ENTERPRISE profile expects. The team should confirm the exact startup log lines for the sync mode and storage format against their Besu version's documentation, since log wording can change between releases. Done means both values appear as expected in the logs or in the node's reported configuration, and any mismatch is investigated before continuing.
Verify that file-set values take effect
For each overlapping key from the precedence table, the engineer confirms the running node uses the file value, not the profile value, by checking startup logs or the node's reported configuration. A value that differs from the profile should be visible as the one in effect. Done means every overlap has been checked, and any value that still shows the profile default is traced to a typo, a command-line flag or a second configuration file.
Observe node behavior on the test network
The engineer lets the node join the test network, then watches peer count, sync progress and RPC responses over a short run while checking the logs for errors. The aim is to confirm the node behaves as the profile intends, with no unexpected storage or sync messages. Done means the observations, log excerpts and the effective configuration are saved as a baseline record that the team can compare against after upgrades or config changes.
Security and operations to plan around the profile
The ENTERPRISE profile sets sync and storage defaults, but it does not change how Besu protects keys, authenticates API callers, terminates TLS, exposes metrics or handles upgrades. Each of the controls below needs a decision from your team, whichever profile or configuration file you use.
Unencrypted node private key file
The node private key file is not encrypted at rest. Anyone who can read that file on the host can impersonate the node on the network. Decide whether the file lives on a locked-down volume with restricted access, or whether your key policy requires hardware-backed storage. If you need HSM-backed keys, Besu supports a security module plugin, such as the Besu HSM plugin, enabled with the --security-module option. Confirm the plugin's supported hardware with the plugin's documentation before you commit to it.
JSON-RPC authentication choices
Besu can require credentials on its JSON-RPC API through a username and password credentials file, or through JWTs issued by an external identity provider and validated against a public key. JWT validation supports RS256, RS384, RS512, ES256, ES384 and ES512. Decide which callers need access to which methods, who rotates the credentials or signing keys, and how a revoked caller is cut off. The profile does not enable authentication for you.
TLS in front of the node
Besu does not terminate HTTPS natively. Application traffic to the JSON-RPC port needs TLS from a reverse proxy, a load balancer, a service mesh or an API gateway in front of the node. Ask who owns the certificate lifecycle, where TLS ends, and whether traffic between the proxy and the node stays on a trusted network segment. Check that the proxy does not forward the RPC port to clients that should not reach it.
Metrics on the Prometheus endpoint
Besu exposes metrics for Prometheus when you start it with --metrics-enabled, and the default endpoint uses port 9545. Metrics are off unless you enable them, so decide whether your monitoring stack scrapes the endpoint or receives pushes through a Prometheus push gateway. Restrict which networks can reach port 9545, since metrics reveal node state to anyone who can query them. A sample Grafana dashboard is documented to start from.
Backups before version upgrades
The Bonsai database upgrades automatically on first start, and older Besu versions cannot open an upgraded database. A rollback therefore depends on a backup taken before the upgrade, not on reinstalling the previous binary. Plan a stopped-node backup of the data directory, record the version you are moving from, and test a restore on a separate host before rollout. Confirm with the release notes for each target version whether a database upgrade applies to your storage format.
Questions teams ask before configuring the ENTERPRISE profile
Is the ENTERPRISE profile enough on its own for a consortium network?
No. The profile sets a small group of defaults, mainly --sync-mode=FULL and --data-storage-format=FOREST, and it does not decide who may join, which validators sign blocks, how keys are stored or how members share one genesis file. A consortium still needs agreed genesis settings, a validator set, node permissioning files on every node, a key custody decision and a shared operating model. Treat the profile as one configuration input among several. Ask your team to list every option the network depends on and confirm each one in the node configuration file, not only in the profile.
What does configuring the profile cost, and who pays for it?
The profile itself costs nothing to use, since Besu is open source under Apache 2.0. The cost sits in the people who design, configure, test and run the network. Internal teams pay with engineering time, which recurs through every upgrade and validator change. A fixed-scope partner engagement is priced from a written scope that lists the nodes, environments, integrations and deliverables. When you request a quote, ask what is one-time (design, configuration, validation, documentation) and what recurs (monitoring, upgrades, support), and how each item changes with network size and the number of member organizations.
How long does configuration and validation take?
Duration depends mainly on how many nodes and organizations are involved, how much of the design is already settled, and how much existing tooling you can reuse. A single-team test network can be configured quickly. A multi-party network needs time for governance agreements, genesis review and joint testing, which usually takes longer than the configuration itself. Your team should first confirm the node count, the storage and sync plan, and whether deployment automation already exists. Ask any partner for a timeline tied to that written scope rather than a generic estimate.
What must our team provide before configuration starts?
Prepare the inputs that the configuration depends on:
- Network topology: which organizations run which nodes, and where those nodes are hosted
- Genesis file: consensus settings, chain ID, initial accounts and the agreed validator set
- Node roles: validators, boot nodes, RPC nodes and any archive needs
- Key custody decisions: where node and validator keys are stored, and whether a security module plugin such as the Besu HSM plugin will be used
- Permissioning and access rules for peers and accounts
The Besu documentation on private networks is the natural starting point for the list. Confirm each item with every member organization before work begins.
Can we configure the ENTERPRISE profile ourselves using the Besu docs?
Yes, a team with Besu operations experience can configure a single profile from the official documentation. The harder work is consistency across a consortium: every node must agree on genesis, permissioning and consensus, and every operator must understand which options the profile overrides. Your team should be able to explain the --profile flag, the rule that command-line and configuration file options override profile values, and how to test a change on a non-production network. If those skills are thin, a fixed-scope engagement can cover design, configuration and handover.
How do profile changes interact with later Besu upgrades?
Profile values are read at startup, so upgrades can change behavior even when your configuration file does not. Besu ships calendar releases roughly monthly, and the release notes list removed features. For example, Besu 25.6.0 removed Tessera privacy and onchain permissioning, and 26.4.0 removed Clique consensus. Before each upgrade, review the release notes, test the same profile and configuration on a non-production node, and confirm that every option still exists. Note that the Besu 26.10.0 release notes say the Bonsai database auto-upgrades on first start and cannot be opened by older versions, so take a backup before upgrading.
Which option conflicts should we check first in our configuration file?
Start with any option that the profile also sets, since your file wins over the profile. Check --sync-mode and --data-storage-format first, because a mismatch changes how a node syncs and stores state. Then check RPC exposure, metrics and permissioning paths. Confirm the effective values on each node after startup, using the logs or the node's own reporting, and compare them across the network. Document every override so that an operator can explain why a node differs from the profile defaults during an incident.
What changes when FULL sync and FOREST storage replace defaults
Selecting the ENTERPRISE profile also fixes two settings that many operators never change by hand: --sync-mode=FULL and --data-storage-format=FOREST. Full sync means the node builds its state by processing the chain, and it is the sync path that remains after the maintainers sunset fast sync. The trade-off is time and resource use during initial sync and recovery, since a node that loses its data must go through that process again. Before go-live, measure how long a full sync takes on your own chain and infrastructure, and set your restore expectations from that measurement rather than from assumptions. The profile's behavior is described in the Besu configuration profiles documentation.
Forest storage keeps the historical world state that Besu needs to answer queries about past blocks, which is the reason operators pick it for archive-style needs. The cost is storage growth over the life of the chain, so disk planning has to assume the database keeps growing rather than staying near its first-day size. The role of each node changes how much this matters. An RPC node that serves historical state queries to applications depends on that history. A validator mainly needs to stay in consensus and produce blocks, so it may not need the same history, and a boot node mainly needs stable peer connectivity. Decide the storage format per node role, and confirm with the Besu docs which roles genuinely need historical state before applying the profile everywhere.
The profile is a set of defaults, not a lock. An option set in your configuration file or on the command line overrides the same option in the profile, so a sync-mode or data-storage-format entry in your own file silently replaces the ENTERPRISE value. Audit the effective settings on each node at startup, keep the profile choice and any overrides in version control, and record the reason for each override. Also confirm whether changing the storage format on a node with an existing data directory requires a resync or a new data directory, and plan that step before any change on a production node.
How DeployOpen works on this
DeployOpen scopes the ENTERPRISE profile as part of a wider private network configuration, not as a single flag. We map which profile values apply to your nodes, which of your own settings override them, and what your storage and sync plan must support before any node goes live.
How we scope
- The written scope lists every node type, the sync and storage settings in use, and each override kept in your configuration file.
- We record which profile values your team accepts and which it replaces, so reviewers can trace each setting.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ask for the scope to name the Besu release you will run, since profile behavior is tied to specific versions.
How we build
- We build the node configuration in version control with the profile flag and explicit overrides kept in separate, reviewable files.
- We test startup on each node type to confirm FULL sync and FOREST storage take effect as the configuration intends.
- We check that command-line and configuration file values behave as expected when they conflict with profile defaults.
- We size disk growth for the chosen storage format and document the expected data directory layout for each node.
How we hand over
- You receive the configuration repository, a record of every override, and notes on which profile values were kept or replaced.
- The handover covers how to upgrade Besu and recheck profile behavior against the release notes for each new version.
- Runbooks explain how to restore a node from a backup taken before an upgrade, since database formats can change between versions.
- Your operators get a walkthrough of the configuration, with the reasons for each setting recorded alongside it.
How we support
- Ongoing support, upgrades and configuration reviews are available as a retainer after handover.
- Retainer work can cover checks of profile behavior against each new Besu release before your team upgrades.
- Confirm with DeployOpen whether a retainer includes monitoring setup, incident response and release testing before you sign.
- Ask for the support hours, escalation path and change process in the written scope before the engagement begins.
