filesystem_xfs

xfs

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

Supports v5 XFS images (CRC32c metadata checksums, ftype). MBR/GPT partition tables are auto-detected.

References

https://docs.kernel.org/filesystems/xfs/index.html

Support summary

All three advanced features above produce xfs_repair -n-clean images (validated against xfsprogs 6.13 in CI on native amd64/arm64 runners).

Advanced features

Reflink (shared extents, copy-on-write)

Format with FormatConfig{Reflink: true} to enable the XFS_SB_FEAT_RO_COMPAT_REFLINK feature bit and a per-AG reference-count B-tree (refcountbt, matching mkfs.xfs -m reflink=1,rmapbt=0). FS.Reflink(src, dst) then clones a file so it shares physical extents; deleting or overwriting a reflinked file is copy-on-write (the shared extents' reference counts are decremented and blocks are freed only when no longer shared).

Quotas

Format with FormatConfig{Quota: QuotaConfig{User, Group, Project, Enforce}} to create the classic (non-metadir) quota inodes (sb_uquotino/sb_gquotino/ sb_pquotino), seed their dquot clusters, and set sb_qflags + the XFS_SB_VERSION_QUOTABIT. Block/inode accounting is kept consistent after every mutating operation by a full inode-scan quotacheck.

Limitations

• Snapshots are an LVM/device-mapper concern, not an XFS on-disk feature, and are out of scope for this filesystem-format library.
• Residuals in the advanced features: the reference-count B-tree is single-level (a share touching more distinct extents than fit one root block returns an error rather than growing the tree); growing a filesystem whose current last AG is already partial (in-place extension of that AG) is not supported — the last AG must be full before the next grow; quota files are a single dquot block, so identities beyond ~30 (one block of dquots) are not tracked.
• Intended for testing and tooling; not recommended for production workloads.

Untrusted input

An image is attacker-controlled bytes. Every allocation and walk the driver sizes from a value read off the image is checked against what the image can hold before it happens (tests assert the allocation or the device-read count for each refused road):

Fuzz targets: FuzzReadFileBomb, FuzzValidateExtents (allocation and device reads stay proportional to the input; accepted extent lists never overlap), plus the existing FuzzReadSuperblock, FuzzReadExtents, FuzzBtreeExtents, FuzzCntFindBlock, FuzzReadSymlink, FuzzPartitionOffset.

Module

github.com/go-filesystems/xfs

Supported operations

API

FS is an interface (not a struct) — Format, Open, and OpenFromDevice all return FS, and every method below is called through that interface value (fs.Reflink(...), not (*FS).Reflink).

Format / Open

type FormatConfig struct {
    UUID    [16]byte // zero = randomly generated
    Label   string
    Reflink bool        // enable shared-extent (COW) support
    Quota   QuotaConfig // enable user/group/project quota accounting
}

type QuotaConfig struct {
    User, Group, Project bool // which quota types to account
    Enforce              bool // also set the *_ENFD (limit enforcement) flags
}

func Format(path string, sizeBytes int64, cfg FormatConfig) (FS, error)
func Open(imagePath string, partIndex int) (FS, error)
func OpenFromDevice(dev BlockBackend, partIndex int) (FS, error) // layered backends (LUKS/qcow2/in-memory)

FS interface

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

    Grow(newSizeBytes int64) error   // extend to newSizeBytes, whole-AG-aligned
    Resize(newSizeBytes int64) error // routes to Grow; shrink returns filesystem.ErrShrinkUnsupported
    GrowTo(newSizeBytes int64) error // alias of Grow (filesystem.Grower)

    ExtendedStat(path string) (*InodeStat, error) // uid/gid, timestamps, link count, generation
    Chown(path string, uid, gid uint32) error
    Chmod(path string, perm os.FileMode) error
    Chtimes(path string, atime, mtime time.Time) error
    Symlink(target, linkPath string) error
    Truncate(path string, newSize int64) error
    Link(oldPath, newPath string) error

    // Reflink clones srcPath into a new file dstPath sharing srcPath's extents
    // (requires FormatConfig.Reflink); HasReflink reports the feature bit.
    Reflink(srcPath, dstPath string) error
    HasReflink() bool

    Label() string
    SetLabel(label string) error
}

Implements

This package implements the filesystem.Filesystem contract defined in the github.com/go-filesystems/interface module. Use the interface to write generic tooling that works with other filesystem implementations in this repository. Example:

import (
    filesystem     "github.com/go-filesystems/interface"
    filesystem_xfs "github.com/go-filesystems/xfs"
)

f, _ := filesystem_xfs.Open("image.img", -1)
defer f.Close()
var fs filesystem.Filesystem = f
_, _ = fs.ReadFile("/hello.txt")