filesystem_btrfs

filesystem-btrfs

Pure-Go read/write access to Btrfs filesystem images — no root privileges, no external tools, no CGO.

Supports single-device Btrfs images with CRC32c metadata checksums (btrfs-progs ≥ 5.x). MBR/GPT partition tables are auto-detected.

References

https://btrfs.readthedocs.io/en/latest/

Support summary

Limitations

• Subvolume/snapshot creation and send/receive are not implemented (read-only support exists — see above).
• Quotas and reflink are not implemented.
• Multi-device/RAID writes are not implemented (reading multi-device pools is).
• No online device add/remove or balance operations.
• Intended for testing and tooling; not recommended for production use.

Untrusted input

An image is attacker-controlled bytes. Every allocation, walk and recursion the driver sizes from a value read off the image is checked against what the format can produce before it happens (tests assert the allocation or the device-read count for each refused road). Bounds that come from the kernel source are cited in harden.go:

Fuzz targets: FuzzDecompressExtent, FuzzStripedRead (allocation and device-read count stay proportional to the input), plus FuzzMountImage, FuzzReadFileData, FuzzMountPatched.

Supported operations

API

FS is an interface (not a struct) — Open/OpenFromDevice/OpenFromDevices return FS; Format returns the narrower filesystem.Filesystem. Every method below is called through the interface value (fs.Symlink(...), not (*FS).Symlink).

Format / Open

type FormatConfig struct {
    UUID  [16]byte // zero = randomly generated
    Label string    // up to 255 bytes, NUL-padded on disk
}

func Format(path string, sizeBytes int64, cfg FormatConfig) (filesystem.Filesystem, error)
func Open(imagePath string, partIndex int) (FS, error)
func OpenFromDevice(dev BlockBackend, partIndex int) (FS, error)
func OpenFromDevices(devs []BlockBackend, partIndex int) (FS, error) // multi-device RAID, read-only

FS interface

type FS interface {
    filesystem.Filesystem // Close, ReadFile, ListDir, Stat, WriteFile, ReadLink,
                           // MkDir, DeleteFile, DeleteDir, Rename

    Link(oldPath, newPath string) error
    Symlink(target, linkPath string) error

    Xattrs(path string) (map[string][]byte, error)
    GetXattr(path, name string) ([]byte, error)
    SetXattr(path, name string, value []byte) error
    RemoveXattr(path, name string) error

    ExtendedStat(path string) (*InodeStat, error)
    Chown(path string, uid, gid uint32) error
    Chmod(path string, perm os.FileMode) error
    Chtimes(path string, atime, mtime time.Time) error
    Truncate(path string, newSize int64) error

    Label() string
    SetLabel(label string) error

    // Subvolume / snapshot read support (creation is not supported).
    Subvolumes() ([]Subvolume, error)
    OpenSubvolumeByID(id uint64) (filesystem.Filesystem, error)
    OpenSubvolumeByName(name string) (filesystem.Filesystem, error)

    // Filesystem-level resize. Requires an idle FS (no concurrent writers).
    Grow(newSizeBytes int64) error
    Shrink(newSizeBytes int64) error
    Resize(newSizeBytes int64) error
}

Integration test

Set integrationImagePath in btrfs_test.go and run (from the repo root):

go test -v -run TestOpen_Integration .

Implements

This package implements the filesystem.Filesystem contract from github.com/go-filesystems/interface. Use the interface in higher-level tools to operate on multiple filesystem backends interchangeably.

Example:

import (
    filesystem "github.com/go-filesystems/interface"
    fsb "github.com/go-filesystems/btrfs"
)

f, _ := fsb.Open("btrfs.img", -1)
defer f.Close()
var fs filesystem.Filesystem = f
_, _ = fs.ReadFile("/data")