LtfsCapybara

English | 简体中文

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.

Current Status

The current hardware-I/O baseline 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.

The SCSI and LTFS hardware path is intentionally frozen except for changes backed by a focused test and the mandatory simulated-hardware gate.

Verified Performance

The figures below are measured baselines, not guarantees. They were collected on an anonymized LTO-6-class drive with authorized test media.

Raw tape streaming

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

SMB ordered read-ahead

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.

Architecture

Vue 3 + Tauri / browser
          |
          v
LtfsServer (ASP.NET Core API)
          |
          v
Ltfs (filesystem and task flows)
          |
          v
TapeDrive (SCSI and tape I/O)
          |
          v
LtoTape (cartridge metadata)

Platform Support

• Ltfs, LtoTape, and LtfsServer target .NET 8.
• TapeDrive has Windows SCSI pass-through and Linux SG_IO backends.
• 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.

Repository Layout

• Ltfs/: LTFS labels, indexes, format, read, write, verify, and recovery.
• 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.

Documentation:

• Hardware/SCSI change policy (中文)
• Hardware testing and performance (中文)
• SCSI command audit (中文)

Requirements

• .NET 8 SDK
• Node.js and pnpm
• Rust and the Tauri prerequisites for desktop builds
• Windows or Linux for direct tape access

Build and Run

Build and test the backend:

dotnet build .\LtfsCapybara.sln
dotnet test .\LtfsCapybara.sln -c Release

Run the API and GUI:

dotnet run --project .\LtfsServer
pnpm -C .\ltfs-capybara-gui install
pnpm -C .\ltfs-capybara-gui dev

The default API endpoint is http://localhost:5003; the Vite development server uses http://localhost:1420.

Build all release artifacts on Windows:

script\buildall.bat

Prepare 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/

Validated Write Defaults

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"
  }
}

Mandatory Development Gates

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.ps1

Real 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.

License

Licensed under the GNU General Public License v3.0.