# datto/dattobd architecture

> Architecture diagram of the GitHub repository datto/dattobd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datto/dattobd
- Repository: https://github.com/datto/dattobd

## Overview

Dattobd is a Linux kernel block driver for live copy-on-write snapshots and incremental backup tracking. The user workflow is to create a snapshot with dbdctl, copy the exposed snapshot device to an image, switch the driver to incremental tracking, and later create a new snapshot and apply changed blocks with update-img. The graph includes the documented control path and core tracing/storage layers. Some runtime wiring is unsampled, so uncertain links are omitted; the incremental-copy relationship is documented in the README.

Main entry points: [`src/tracer.c`](https://github.com/datto/dattobd/blob/main/src/tracer.c) (I/O Tracer), [`utils/update-img.c`](https://github.com/datto/dattobd/blob/main/utils/update-img.c) (update-img), [`src/ioctl_handlers.c`](https://github.com/datto/dattobd/blob/main/src/ioctl_handlers.c) (IOCTL Handlers), [`src/cow_manager.c`](https://github.com/datto/dattobd/blob/main/src/cow_manager.c) (COW Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["User Control"]
  node_dbdctl["dbdctl<br/>[dbdctl.c]"]
  node_clientlib["Control Library<br/>[libdattobd.c]"]
end

subgraph group_driver["Kernel Driver"]
  node_ioctl["IOCTL Handlers<br/>[ioctl_handlers.c]"]
  node_state["Device State<br/>[snap_device.h]"]
  node_tracer["I/O Tracer<br/>[tracer.c]"]
  node_bio["Bio Processing<br/>[bio_helper.c]"]
  node_bdev["Block Device Access<br/>[blkdev.c]"]
  node_mountstate["Mount State"]
end

subgraph group_storage["Snapshot Storage"]
  node_cow["COW Manager<br/>[cow_manager.c]"]
  node_filesystem["File Operations<br/>[filesystem.c]"]
  node_cowfile["COW File"]
end

subgraph group_backup["Backup Workflow"]
  node_snapshot["Snapshot Device<br/>[snap_device.c]"]
  node_imagecopy["Image Copy"]
  node_updateimg["update-img<br/>[update-img.c]"]
  node_backupimage["Backup Image"]
end

node_operator(("Operator"))
node_kernelio["Linux Block I/O"]

node_operator -->|"runs commands"| node_dbdctl
node_dbdctl -->|"calls API"| node_clientlib
node_clientlib -.->|"issues controls"| node_ioctl
node_ioctl -->|"manages state"| node_state
node_ioctl -->|"configures COW"| node_cow
node_tracer -->|"uses state"| node_state
node_tracer -->|"uses mappings"| node_cow
node_tracer -->|"processes bios"| node_bio
node_tracer -->|"uses block devices"| node_bdev
node_mountstate -->|"checks devices"| node_state
node_cow -->|"reads and writes"| node_filesystem
node_filesystem -.->|"accesses COW data"| node_cowfile
node_operator -->|"copies snapshot"| node_imagecopy
node_snapshot -.->|"copies image data"| node_backupimage
node_operator -->|"runs update"| node_updateimg
node_updateimg -->|"reads changed blocks"| node_snapshot
node_updateimg -->|"reads block list"| node_cowfile
node_updateimg -->|"updates image"| node_backupimage
node_kernelio -.->|"submits I/O"| node_tracer

click node_dbdctl "https://github.com/datto/dattobd/blob/main/app/dbdctl.c"
click node_clientlib "https://github.com/datto/dattobd/blob/main/lib/libdattobd.c"
click node_ioctl "https://github.com/datto/dattobd/blob/main/src/ioctl_handlers.c"
click node_state "https://github.com/datto/dattobd/blob/main/src/snap_device.h"
click node_tracer "https://github.com/datto/dattobd/blob/main/src/tracer.c"
click node_bio "https://github.com/datto/dattobd/blob/main/src/bio_helper.c"
click node_bdev "https://github.com/datto/dattobd/blob/main/src/blkdev.c"
click node_mountstate "https://github.com/datto/dattobd/blob/main/src/bdev_state_handler.c"
click node_cow "https://github.com/datto/dattobd/blob/main/src/cow_manager.c"
click node_filesystem "https://github.com/datto/dattobd/blob/main/src/filesystem.c"
click node_snapshot "https://github.com/datto/dattobd/blob/main/src/snap_device.c"
click node_updateimg "https://github.com/datto/dattobd/blob/main/utils/update-img.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dbdctl,node_clientlib toneBlue
class node_ioctl,node_state,node_tracer,node_bio,node_bdev,node_mountstate toneAmber
class node_cow,node_filesystem,node_cowfile toneMint
class node_snapshot,node_imagecopy,node_updateimg,node_backupimage toneRose
class node_operator,node_kernelio toneIndigo
```

## Components

### User Control

- [dbdctl](https://github.com/datto/dattobd/blob/main/app/dbdctl.c): `app/dbdctl.c`
- [Control Library](https://github.com/datto/dattobd/blob/main/lib/libdattobd.c): `lib/libdattobd.c`

### Kernel Driver

- [IOCTL Handlers](https://github.com/datto/dattobd/blob/main/src/ioctl_handlers.c): `src/ioctl_handlers.c`
- [Device State](https://github.com/datto/dattobd/blob/main/src/snap_device.h): `src/snap_device.h`
- [I/O Tracer](https://github.com/datto/dattobd/blob/main/src/tracer.c): `src/tracer.c`
- [Bio Processing](https://github.com/datto/dattobd/blob/main/src/bio_helper.c): `src/bio_helper.c`
- [Block Device Access](https://github.com/datto/dattobd/blob/main/src/blkdev.c): `src/blkdev.c`
- [Mount State](https://github.com/datto/dattobd/blob/main/src/bdev_state_handler.c): `src/bdev_state_handler.c`

### Snapshot Storage

- [COW Manager](https://github.com/datto/dattobd/blob/main/src/cow_manager.c): `src/cow_manager.c`
- [File Operations](https://github.com/datto/dattobd/blob/main/src/filesystem.c): `src/filesystem.c`
- **COW File**

### Backup Workflow

- [Snapshot Device](https://github.com/datto/dattobd/blob/main/src/snap_device.c): `src/snap_device.c`
- **Image Copy**
- [update-img](https://github.com/datto/dattobd/blob/main/utils/update-img.c): `utils/update-img.c`
- **Backup Image**

### Other components

- **Operator**
- **Linux Block I/O**

## Connections

- Operator → dbdctl: runs commands
- dbdctl → Control Library: calls API (evidence: `app/dbdctl.c`)
- Control Library → IOCTL Handlers: issues controls
- IOCTL Handlers → Device State: manages state (evidence: `src/ioctl_handlers.c`)
- IOCTL Handlers → COW Manager: configures COW (evidence: `src/ioctl_handlers.c`)
- I/O Tracer → Device State: uses state (evidence: `src/tracer.c`)
- I/O Tracer → COW Manager: uses mappings (evidence: `src/tracer.c`)
- I/O Tracer → Bio Processing: processes bios (evidence: `src/tracer.c`)
- I/O Tracer → Block Device Access: uses block devices (evidence: `src/tracer.c`)
- Mount State → Device State: checks devices (evidence: `src/bdev_state_handler.c`)
- COW Manager → File Operations: reads and writes (evidence: `src/cow_manager.c`)
- File Operations → COW File: accesses COW data
- Operator → Image Copy: copies snapshot
- Snapshot Device → Backup Image: copies image data
- Operator → update-img: runs update
- update-img → Snapshot Device: reads changed blocks
- update-img → COW File: reads block list
- update-img → Backup Image: updates image
- Linux Block I/O → I/O Tracer: submits I/O
