The information contained in this article has been verified as up‑to‑date on the date of the original publication of the article. HashiCorp endeavors to keep this information up‑to‑date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.
All information contained in this article is for general information purposes only. Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.
Introduction
Vault Enterprise’s Integrated Storage backend uses the Raft consensus protocol to replicate data, ensure consistency, and maintain high availability. Each Vault node persists its portion of state locally using the BoltDB storage engine.
This local state is split across two distinct files:
-
vault.db— encrypted Vault operational data -
raft.db— Raft consensus metadata and coordination state
Understanding what these files contain, how they relate to one another, and why they exist is essential for operating and maintaining healthy Vault Enterprise clusters.
This article provides a clear conceptual explanation of both files and how they interact within Vault’s Integrated Storage architecture
Minimal Data Directory Structure
A typical Integrated Storage data directory looks like:
/opt/vault/data/ ├── raft/ │ ├── raft.db │ └── snapshots/ └── vault.db
Where:
-
vault.dbcontains encrypted Vault operational data -
raft/raft.dbcontains Raft consensus metadata -
raft/snapshots/holds compacted state snapshots used during Raft log compaction and node synchronization
1. What Is vault.db?
Vault Operational Data (Encrypted)
vault.db stores Vault’s application-layer data, including, but not limited to:
- Auth method configuration
- Policies and ACL metadata
- Tokens and identity metadata
- Leases (dynamic and renewable)
- Mount table
- Secrets engine data (KV, PKI, database, transit, etc.)
- Internal system metadata
Key Characteristics
| Property | Description |
|---|---|
| Encrypted? | Yes, Vault encrypts all values before writing them |
| Distributed? | Yes, indirectly via Raft log replication |
| Writable by operators? | No, Vault controls all writes |
| Rebuilt during joins? | Yes, recreated via log replay & snapshots |
vault.db represents the node’s local copy of Vault’s current operational state.
2. What Is raft.db?
Raft Consensus Metadata (Cluster Coordination)
raft.db stores Raft consensus metadata, which governs how nodes participate in the Raft algorithm. This file is not encrypted because it contains coordination metadata, not secrets.
It includes:
- Peer configuration
- Current Raft term
- Commit index and last applied index
- Membership change operations
- Election metadata
- Raft log metadata
- Snapshot metadata
Key Characteristics
| Property | Description |
|---|---|
| Encrypted? | No, stores consensus metadata, not secrets |
| Distributed? | Yes, derived from replicated Raft logs |
| Writable by operators? | No, managed purely by Raft |
| Rebuilt during joins? | Yes, reconstructed from the leader |
raft.db represents the node’s local view of cluster membership, Raft state progression, and log position.3. How vault.db and raft.db Work Together
Normal Raft Operation
- A Vault mutation occurs (e.g., writing a secret, updating a policy).
- The leader writes the mutation as a Raft log entry.
- The leader replicates this entry to followers. Once committed, followers apply the entry to
vault.db.raft.dbtracks term, indices, cluster membership, and Raft progression. Raft snapshots compact older log entries intoraft/snapshots/to reduce storage and speed up joins.
Mental Model
-
raft/raft.db= Raft coordination metadata -
vault.db= Vault’s operational data
Both files are required for the node to function and must stay synchronized with the leader’s committed Raft log. Neither file should ever be manually edited or modified.
4. When Removal of Local State May Be Required:
Although this article does not provide troubleshooting procedures, it is important to understand why local state sometimes must be removed in separate operational workflows.
Local state removal may be necessary when:
- A node has been removed from cluster membership (Autopilot or operator action)
- A node’s local state reflects an outdated Raft term, index, or membership view
- A node has disk corruption affecting its BoltDB files
- A node attempts to operate with stale or invalid Raft metadata
In such scenarios, the node’s local vault.db and raft.db no longer reflect the correct state of the cluster. The files must be cleared so the node can safely rebuild its state from the leader using the current snapshot and Raft logs.
Conclusion
vault.db and raft.db are foundational components of Vault’s Integrated Storage backend:
-
vault.dbcontains encrypted operational Vault data -
raft.dbcontains Raft consensus metadata - Both work together to maintain consistency, durability, and coordination across Vault cluster nodes
- Raft snapshots and log replication ensure all nodes converge to the same operational state
Understanding these files and the distinct roles they play, helps operators maintain healthy clusters, reason about Raft internals, and recognize when local state misalignment may require corrective action (covered in separate articles).
Additional Information:
HashiCorp Documentation
- Raft protocol overview
- Integrated storage (Raft) backend
- Operator raft CLI command
- Lost Quorum Raft Tutorial