Btrfs (B-tree File System)

Btrfs is a copy-on-write Linux file system with snapshots, checksums, subvolumes and built-in multi-device support. It is the default on openSUSE and Fedora Workstation, and on Synology NAS units and some other appliances. It is actively developed in the kernel.

Overview

Btrfs stores everything in copy-on-write B-trees keyed by (objectid, type, offset): the root tree, the chunk tree, the extent tree, file system trees and others. Space is allocated in chunks mapped from logical to physical addresses, which allows multiple devices and RAID profiles. The superblock at 64 KiB has two backup copies. Data and metadata are checksummed (CRC-32C by default) and may be compressed (zlib, LZO, zstd).

History

  • Started by Chris Mason at Oracle in 2007.
  • Merged into Linux 2.6.29 (2009).
  • Became the default on Fedora Workstation 33 (2020).

Structures

Offsets are in bytes from the start of the structure named in each heading. Field names are descriptive and are not an official specification. Fixed-width integers are shown as u/i (unsigned/signed) followed by bit width and byte order.

Lzo

OffsetSizeTypeFieldNotes
0x04u32 LETotal
at4u32 LELength

Load Inode

OffsetSizeTypeFieldNotes
0x108u64 LESize
0x188u64 LEAllocated
0x284u32 LENlink
0x2C4u32 LE–
0x304u32 LE–
0x344u32 LEOde

Parse Dir Items

OffsetSizeTypeFieldNotes
at + 252u16 LEData Length
at + 272u16 LEName Length
at + 291u8Type

Parse Extent

OffsetSizeTypeFieldNotes
0x88u64 LERam
0x158u64 LEBytenr
0x1D8u64 LEDisk Bytes
0x258u64 LEOffset
0x2D8u64 LELength

Parse Xattrs

OffsetSizeTypeFieldNotes
at + 252u16 LEData Length
at + 272u16 LEName Length

Load Subvolumes

OffsetSizeTypeFieldNotes
0x08u64 LE–
0x102u16 LEName Length

Parse Root Item

OffsetSizeTypeFieldNotes
0xA08u64 LE–
0xA88u64 LE–
0xB08u64 LE–
0xD08u64 LE–
0xD84u32 LE–
0x10716bytes–

Verify

OffsetSizeTypeFieldNotes
0x04u32 LE–
0x08u64 LE–

Xx Hash64

OffsetSizeTypeFieldNotes
(i + 16)8u64 LEV3
(i + 24)8u64 LEV4
(i + 8)8u64 LEV2
i8u64 LEV1
i8u64 LE–
i4u32 LE–

Time

OffsetSizeTypeFieldNotes
(offset + 8)4u32 LENanoseconds
offset8i64 LESeconds

Parse

OffsetSizeTypeFieldNotes
0x408bytes–
0xC42u16 LECsum Type
0xC61u8Root
0xC71u8Chunk Root
at8u64 LE–
at4u32 LE–
at + 1521u8–
at + 1531u8–

Parse

OffsetSizeTypeFieldNotes
0x08u64 LELength
0x108u64 LEStripe Length
0x188u64 LEType
0x2C2u16 LECount
0x2E2u16 LESub Stripes
(48 + i * 32)8u64 LE–
(56 + i * 32)8u64 LE–

Parse

OffsetSizeTypeFieldNotes
0x508u64 LEGeneration
0x588u64 LEOwner
0x604u32 LECount
0x641u8Level
at + 174u32 LEOffset
at + 178u64 LE–
at + 214u32 LESize

Other fields read

Read inOffsetSizeTypeFieldNotes
Load Inode0x344u32 LE–
Verifyi8u64 LECrc
Read Best0x308u64 LE–
Read Node0x308u64 LE–

Constants

Btrfs File System

NameValueTypeNotes
InodeShift40int

Btrfs Logical Device

NameValueTypeNotes
Sector512int

Btrfs Const

NameValueTypeNotes
SuperblockOffsets[0x10000, 0x4000000, 0x4000000000]long[]
SuperblockSize4096int
HeaderSize101int
LeafItemSize25int
KeyPointerSize33int

Tree / object ids

NameValueTypeNotes
RootTreeObjectId1ulong
ExtentTreeObjectId2ulong
ChunkTreeObjectId3ulong
DevTreeObjectId4ulong
FsTreeObjectId5ulong
FirstFreeObjectId256ulong
LastFreeObjectIdunchecked((ulong)-256L)ulong
FirstChunkTreeObjectId256ulong

Item types

NameValueTypeNotes
InodeItem1byte
InodeRef12byte
InodeExtRef13byte
XattrItem24byte
DirItem84byte
DirIndex96byte
ExtentData108byte
RootItem132byte
RootBackref144byte
RootRef156byte
DevItem216byte
ChunkItem228byte

Chunk / block group types

NameValueTypeNotes
BlockGroupData0x1ulong
BlockGroupSystem0x2ulong
BlockGroupMetadata0x4ulong
Raid00x8ulong
Raid10x10ulong
Dup0x20ulong
Raid100x40ulong
Raid50x80ulong
Raid60x100ulong
Raid1C30x200ulong
Raid1C40x400ulong
ProfileMaskRaid0 | Raid1 | Dup | Raid10 | Raid5 | Raid6 | Raid1C3 | Raid1C4ulong

Extent data

NameValueTypeNotes
ExtentInline0byte
ExtentRegular1byte
ExtentPrealloc2byte
CompressNone0byte
CompressZlib1byte
CompressLzo2byte
CompressZstd3byte

Directory entry types

NameValueTypeNotes
FtRegular1byte
FtDirectory2byte
FtSymlink7byte

Incompat features this reader knows (others are reported)

NameValueTypeNotes
IncompatKnown0x1 | 0x2 | 0x4 | 0x8 | 0x10 | 0x20 | 0x40 | 0x80 | 0x100 | 0x200 | 0x400 | 0x800 | 0x1…ulong
IncompatMetadataUuid0x400ulong
IncompatExtentTreeV20x2000ulong
IncompatRaidStripeTree0x4000ulong
IncompatEncrypt0x10000ulong

Btrfs Checksum

NameValueTypeNotes
P111400714785074694791ULulong
P214029467366897019727ULulong
P31609587929392839161ULulong
P49650029242287828579ULulong
P52870177450012600261ULulong

Btrfs Volume

NameValueTypeNotes
Sector512int

Implementation limits

ClassNameValueNotes
Btrfs File StreamMaxExtentBytes16 * 1024 * 1024
Btrfs Logical DeviceChunk1 << 20
StructMinnew(0, 0, 0)
StructMaxnew(ulong.MaxValue, byte.MaxValue, ulong.MaxValue)
Btrfs VolumeMaxCachedNodes4096

Signatures and magic strings referenced

TextWhere checked
_BHRfS_MBtrfs Const
Structures and constants were extracted from the implementation. Prose sections are a summary from public sources; verify details before relying on them.