LtfsCapybara is an LTFS toolkit for managing LTO tape on Windows and Linux. It combines a C# LTFS core, direct SCSI tape access, cartridge-memory parsing, an ASP.NET Core API, and a Vue 3 frontend that can run in a browser or a Tauri desktop shell.
This project is under active development. It is not a complete backup solution; keep independent backups of important data.
The current implementation supports:
- LTFS label, index, format, read, write, verify, and index-recovery flows.
- Sequential tape I/O, filemarks, partition switching, positioning, rewind, load, unthread, and unload.
- Early Warning and hard EOM handling with fixed- and descriptor-sense parsing.
- LOG SENSE monitoring for capacity, performance, TapeAlert, error counters, and volume statistics.
- In-memory tape simulation and fixed CDB/status/sense trace replay before real-hardware testing.
- Ordered SMB/NAS source read-ahead with bounded memory and CRC64 processing.
- Durable file and directory write selections with capacity checks, execution checkpoints, and incident records.
- Recoverable stop controls for the current read or write operation without implicitly clearing the queued work.
- Durable recovery fences, isolated candidate indexes, and atomic server-wide admission with synchronized GUI busy controls.
- Offline index search/history, guarded generation rollback, and a verification workbench with persistent reports.
- Versioned encryption credentials and explicit encrypted-media identification, plus separately authorized expert MAM and maintenance backends.
As of 2026-10-30, the simulated-hardware gate passed 542 tests, the full .NET suite passed 1023, and the GUI passed 144 tests plus its production build. HP LTO-6 J5SW / Windows / LTO5 validation covers normal format/read/write, API file mutations and historical restore, persistent verification reports, encryption credentials and encrypted I/O, guarded MAM and logical erase, physical write protection, partition-0 WRITE EW/hard EOM, and production streaming finalization at real EW. Real empty-drive GUI/API checks also cover stale diagnostic CM rejection, disabled media controls and connection recovery. Physical faults, unavailable media/platforms, NAS and remaining UI cases are tracked separately. See the documentation index, hardware evidence, and remaining acceptance work (Chinese).
The SCSI and LTFS hardware path is intentionally frozen except for changes backed by a focused test and the mandatory simulated-hardware gate.
- File and directory sources are added through separate APIs. Directory selections are scanned into durable manifests so a long-running write has a reviewable source snapshot and byte total before tape I/O starts.
- An intermediate LTFS index contains only files whose data and metadata have been fully written. Failed, pending, or partially written files are not published in that generation.
- Stopping a write cancels only the current physical operation and enters a decision state. The user can continue, commit a full index containing completed files and stop, or discard the new generation and finish by rewriting the previous valid full index. Discarding a generation cannot erase data blocks already streamed to tape.
- Stopping a read cancels the current read operation without clearing the remaining task queue.
- New hardware operations and task/settings edits return HTTP 409 while the server is busy, without queuing. The GUI enables only controls advertised for the current execution and phase; cached/local-index browsing and reports remain available.
- Data-partition indexes currently use the SNIA LTFS 2.4 full-index model.
ServerSettings:DataPartitionIndexModemust beFullOnly; incremental-index output remains disabled until incremental parsing and application are implemented end to end. - Committed and working index ownership is bounded instead of retaining every historical generation in memory. Intermediate and final indexes are derived from completed entries in the active generation.
- Internal storage and file-size calculations use bytes. User-facing file and capacity values use adaptive IEC units: B, KiB, MiB, GiB, and TiB.
- Transfer rates reported by drive performance pages and shown by the task UI use decimal MB/s. Benchmark fixtures that measure binary throughput are explicitly labeled MiB/s.
- The legacy HPE Tape Capacity LOG SENSE page 31h is interpreted as MiB, while Sequential Access Device page 0Ch capacity and performance values use decimal MB as defined by the device documentation.
- LTO physical-format data-set sizes are decimal kilobytes.
LtoTapeexposes bothDecimalKilobytesPerSetand the normalizedBytesPerSetvalue. - Physical wrap layouts include redundant data sets, so modeled or reported writable bytes can be slightly higher than a cartridge's nominal marketed capacity. The implementation preserves the physical value instead of clamping it to the nominal label.
The figures below are measured baselines, not guarantees. They were collected on an anonymized LTO-6-class drive with authorized test media.
These historical measurements do not certify every subsequent change. The new production-pipeline local baseline validates correctness and release behavior on a small local dataset; original-NAS and current-device acceptance are separate handoff items.
A 60 GiB incompressible workload was written from BOP using 512 KiB variable blocks in a single partition. No LOG SENSE, READ POSITION, or filemark command was interleaved with the streaming write.
| Metric | Verified result |
|---|---|
| Steady 1 GiB window | 137.53 MiB/s |
| Durable rate including final flush | 132.67 MiB/s / 139.11 MB/s |
| Reported native rate utilization | 99.37% of 140 MB/s |
| Full forward / reverse wrap | 134.348 / 134.397 MiB/s |
| Average wrap turnaround penalty | 2.839 s |
| Reported device object buffer | 418 MB |
| Write retries / unrecovered write errors | 0 / 0 |
An anonymized SMB workload containing 5,508 files and 5.693 GiB of mixed small and large files was read in source order through the production Ltfs.FileBuffer implementation. All runs produced the same aggregate CRC64. The sink used the measured tape rate, device-buffer size, and one simulated wrap turnaround.
| Source read-ahead configuration | Effective active window | Throughput | Peak source buffer |
|---|---|---|---|
| 256 MiB, concurrency 32, window 64 | 32 | 125.123 MiB/s | 187.765 MiB |
| 512 MiB, concurrency 32, window 64 | 32 | 125.297 MiB/s | 183.765 MiB |
| 512 MiB, concurrency 64, window 128 | 64 | 123.489 MiB/s | 262.214 MiB |
Increasing only the configured buffer did not expand the active window or provide a meaningful throughput improvement. Expanding concurrency increased SMB contention and reduced throughput. The validated defaults therefore remain 256 MiB buffer, concurrency 32, window 64, 4 MiB chunks, and two chunks per file.
See Hardware testing and performance for methodology and limitations.
Vue 3 + Tauri / browser
|
v
LtfsServer (API, durable manifests, task orchestration)
|
v
Ltfs.Tape (mounted-volume facade and tape workflows)
| | |
v v v
Ltfs.Core Ltfs.Execution TapeDrive --> LtoTape
(XML/model) (task contracts) (SCSI I/O) (device metadata)
- The C# projects target .NET 8.
TapeDrivehas Windows SCSI pass-through and Linux SG_IO backends.- Automated gates are device-free. Separate Windows SPT validation on HP LTO-6 J5SW / LTO5 is recorded in the hardware evidence; Linux SG_IO and other firmware/media combinations remain pending.
- Windows tape discovery uses
\\.\TapeN; Linux uses/dev/nst*or/dev/st*. - The desktop GUI uses Vue 3, Naive UI, Pinia, vue-i18n, Tauri 2, and the platform Tauri prerequisites.
Ltfs.Core/: tape-independent LTFS label/index XML models and filesystem operations.Ltfs.Execution/: task, progress, source-snapshot, and streaming-write contracts.Ltfs.Tape/: mounted-volume facade plus format, index, read, write, verify, and recovery workflows.TapeDrive/: device discovery, CDB encoding, sense handling, positioning, MAM, alerts, and I/O.LtoTape/: cartridge-memory and tape-metadata parsing.LtfsServer/: ASP.NET Core API and task orchestration.ltfs-capybara-gui/: Vue 3 web UI and optional Tauri shell.tests/Ltfs.Tests/: LTFS unit, index, task, read/write, and regression tests.tests/TapeDrive.SimulationTests/: in-memory hardware, exact CDB, trace-replay, and benchmark-model tests.tests/LtfsServer.Tests/: server feature and local-index integration tests.TestSupport/LtfsHardwareTest.Core/: reusable hardware-test options and benchmark logic with no device entry point.Tools/LtfsHardwareTest/: guarded real-hardware probe, format, EOD, raw benchmark, and error-rate flows.Tools/LtfsPipelineBenchmark/: device-free production source/pipeline benchmark and checksum validation.
Documentation:
- Hardware/SCSI change policy (中文)
- Hardware testing and performance (中文)
- SCSI command audit (中文)
- Local documentation index and commits / Hardware and NAS handoff checklist
- .NET 8 SDK
- Node.js and pnpm
- Rust and the Tauri prerequisites for desktop builds
- Windows or Linux for direct tape access
Build and test the backend:
dotnet build .\LtfsCapybara.sln
pwsh -NoProfile -File .\script\test-simulated-hardware.ps1
dotnet test .\LtfsCapybara.sln -c ReleaseRun the API and GUI:
dotnet run --project .\LtfsServer
pnpm -C .\ltfs-capybara-gui install
pnpm -C .\ltfs-capybara-gui devThe default API endpoint is http://localhost:5003; the Vite development server uses http://localhost:1420.
The checked-in configuration uses in-memory fake drives. Review environment and Data.Path/config.json overrides before starting the server; real-device access requires an explicit target-host setup. Expert tools are disabled unless separately configured.
Build all release artifacts on Windows:
script\buildall.batPrepare a generic remote deployment without embedding environment-specific addresses in source documentation:
.\script\deploy.ps1 `
-Mode SMB `
-RemoteHost <remote-host> `
-RemotePath <remote-install-path> `
-RemoteDataPath <remote-data-path>For local GUI development against another backend, pass its URL explicitly:
.\script\dev-gui-remote.ps1 -ApiBaseUrl http://<remote-host>:5003/The server defaults are intentionally conservative after the SMB baseline:
{
"LtfsWrite": {
"SmallFilePrefetchThresholdBytes": 4194304,
"SmallFileDirectWriteThresholdBytes": 131072,
"SmallFilePrefetchConcurrency": 16,
"SmallFilePrefetchWindow": 32,
"SourceReadAheadEnabled": true,
"SourceReadAheadConcurrency": 32,
"SourceReadAheadWindow": 64,
"SourceReadAheadBufferBytes": 268435456,
"SourceReadAheadChunkBytes": 4194304,
"SourceReadAheadPerFileChunks": 2,
"ChecksumAlgorithm": "Crc64"
}
}Changes to LTFS tape I/O, SCSI CDB encoding, sense or LOG SENSE parsing, positioning, device access, or hardware test commands must add or update the relevant in-memory/replay test and pass this command before commit:
.\script\test-simulated-hardware.ps1Real hardware testing happens only after this gate passes and never replaces it.
Changes to file enumeration, source reads, buffering, prefetch, CRC, tape-write pipelines, or concurrency must also pass the full test suite and the applicable correctness/performance baseline. At minimum, verify byte counts and checksums, bounded peak memory, tape-starvation events, and throughput against the committed baseline. A regression must be explained and approved; silently accepting a slower or unbounded implementation is not allowed.
See Hardware/SCSI change policy for the complete commit rules.
Licensed under the GNU General Public License v3.0.
