diff --git a/content/docs/1.12.0/nodes-and-volumes/volumes/replica-filesystem-layout.md b/content/docs/1.12.0/nodes-and-volumes/volumes/replica-filesystem-layout.md new file mode 100644 index 000000000..e582e765a --- /dev/null +++ b/content/docs/1.12.0/nodes-and-volumes/volumes/replica-filesystem-layout.md @@ -0,0 +1,53 @@ +--- +title: Replica Directory Layout +weight: 2 +--- + +The replica directory contains the raw data and metadata for a volume replica on the host's local filesystem. By default, these are located at `/var/lib/longhorn/replicas/`. + +## Directory Naming + +Each replica is stored in a directory named using the format: `-`. + +Example: `pvc-b43f2832-33ef-4ff1-ac7e-b097f71a5977-6f2d4c29` + +## Core Files + +### 1. `volume.meta` +The "Source of Truth" for the replica's state. It is a JSON file that defines the volume's operational parameters. + +* **Size**: The total logical size of the volume in bytes. +* **Head**: The filename of the current active `.img` file receiving writes. +* **Parent**: The snapshot file that the current head is branched from. +* **BackingFilePath**: The path to a Backing Image, if used. +* **backupBlockSize**: (Added in v1.10.0) The block size used for backups (e.g., `2097152` for 2MiB or `16777216` for 16MiB). + +### 2. `revision.counter` +A critical metadata file used for data consistency. It contains a single integer that increments with every write operation. When a replica starts, Longhorn compares the `revision.counter` across all replicas; the one with the highest number is considered the most up-to-date. + +### 3. `volume-head-###.img` +A **sparse file** representing the "live" data layer. +* All new writes are directed here. +* It only consumes physical disk space for written blocks, even if its logical size matches the volume capacity. + +### 4. `volume-snap-.img` +Read-only binary files created during a snapshot. +* Once a snapshot is completed, the `.img` file becomes immutable. +* These files represent the volume's state at a specific point in time. + +### 5. Metadata Files (`.img.meta`) +Every `.img` file has a corresponding `.img.meta` JSON file. +* **Name**: Internal identifier for the image. +* **Parent**: The UUID/Name of the previous snapshot. This creates the **Snapshot Chain** (a linked list). +* **UserCreated**: Indicates if the snapshot was user-triggered or system-generated (e.g., during a rebuild). + +## Data Read Logic + +Longhorn employs a "Top-Down" lookup strategy: +1. **Active Head**: The engine first checks the `volume-head`. +2. **Chain Traversal**: If the block isn't found, it follows the `Parent` link in the `.img.meta` to the previous snapshot. +3. **Base Layer**: It continues down the chain until the data is located or the beginning of the volume is reached. + +## Troubleshooting + +If a replica fails with an "invalid chain" error, administrators can inspect the `Parent` fields in the `.img.meta` files to ensure they form an unbroken sequence pointing to existing files on the disk. \ No newline at end of file diff --git a/content/docs/1.12.0/snapshots-and-backups/backup-and-restore/backupstore-internal-layout.md b/content/docs/1.12.0/snapshots-and-backups/backup-and-restore/backupstore-internal-layout.md new file mode 100644 index 000000000..7c24dd6db --- /dev/null +++ b/content/docs/1.12.0/snapshots-and-backups/backup-and-restore/backupstore-internal-layout.md @@ -0,0 +1,111 @@ +--- +title: Backupstore Internal Structure +weight: 2 +--- + +The backupstore is the external storage location where Longhorn backups are saved. It can be either an NFS share, CIFS share, or an S3-compatible object store. Unlike the local replica directory, the Backupstore is designed for **deduplication** and **incremental storage**, breaking large volumes into small, manageable blocks. + +## Directory Structure Overview + +The root of the backupstore contains a `volumes` directory. Inside, each volume is organized using a hashed path to ensure scalability: + +```text +backupstore/ +└── volumes/ + └── 4b/ + └── e2/ + └── [volume-name]/ + ├── volume.cfg + ├── backups/ + │ ├── backup_backup-01.cfg + │ └── backup_backup-02.cfg + └── blocks/ + ├── 0a/ + │ └── 0a1b2c3d... (block file) + └── ... +``` + +## Core Components + +### 1. `volume.cfg` + +This is the primary configuration file for a specific volume within the backupstore. It tracks the volume's overall metadata and acts as the entry point for Longhorn to discover which backups are available for restoration. + +**Example Content (`volume.cfg`):** + +```json +{ + "Name": "pvc-b43f2832-33ef-4ff1-ac7e-b097f71a5977", + "Size": 1073741824, + "Labels": { + "BackupTarget": "minio-persistent" + }, + "CreatedTime": "2026-03-18T14:07:12Z", + "Backups": { + "backup-01": { + "Name": "backup-01", + "SnapshotName": "snap-457233d...", + "SnapshotCreated": "2026-03-18T14:50:28Z", + "CreatedTime": "2026-03-18T15:13:02Z", + "Size": "128Ki", + "Labels": null + } + } +} +``` + +**Field Descriptions**: + +* **Name**: The original PV/PVC name. +* **Size**: Total provisioned size of the volume in bytes. +* **Backups**: A dictionary indexing all successful backups currently stored in this target. + +### 2. The `backups/` Directory + +Contains "Manifest" files for every individual backup. + +* **`backup_[name].cfg`**: A JSON blueprint for a specific backup point-in-time. + +**Example Content (`backup_backup-01.cfg`):** + +```json +{ + "Name": "backup-01", + "VolumeName": "pvc-b43f2832-33ef-4ff1-ac7e-b097f71a5977", + "SnapshotName": "snap-457233d...", + "SnapshotCreated": "2026-03-18T14:50:28Z", + "CreatedTime": "2026-03-18T15:13:02Z", + "Size": 131072, + "Blocks": [ + { + "Address": 0, + "Size": 2097152, + "Hash": "0a1b2c3d4e5f..." + } + ] +} + +``` + +**Field Descriptions**: + +* **Size**: The actual data size of the backup (not the full volume size). +* **Blocks**: An array mapping the volume's offset (`Address`) to a specific physical chunk in the `blocks/` directory via its `Hash`. + +### 3. The `blocks/` Directory + +This is where the actual data resides. Longhorn uses **Content-Addressable Storage**: + +* **Chunking**: Volume data is divided into blocks. The **default block size is 2MB** (2097152 bytes), but since v1.10.0, this is configurable up to **16MB**. +* **Hashing**: Each block is hashed (SHA512), and the filename is the hash itself. +* **Deduplication**: If two snapshots share the same data, they reference the same hash, saving significant space. +* **Subdirectories**: Blocks are organized into subdirectories (e.g., `/0a/`) based on the first two characters of their hash to maintain filesystem performance. + +## Backup Process Logic + +1. **Identification**: Longhorn identifies changed blocks between the current snapshot and the previous backup. +2. **Hashing**: Changed blocks are hashed. +3. **Upload**: Only **new, unique blocks** (hashes not already in the `blocks/` folder) are uploaded. +4. **Manifest Creation**: A new `backup_*.cfg` is created, and `volume.cfg` is updated to include the new entry. + +> **Note**: Previous versions of Longhorn used a `last_backup.cfg` file. In modern versions (v1.2.0+), this has been replaced by an asynchronous Custom Resource (CR) model where the cluster tracks the state directly, making `last_backup.cfg` obsolete.