bcachefs

Resources

Home

Official documentation

Wikipedia

bcache (on irc://irc.oftc.net)

GitWeb

Package information

Warning
bcachefs is still marked as experimental in the Kernel, so ensure important data is regularly backed up to a non-bcachefs medium.

See also
This is a general usage article for bcachefs in Gentoo, those looking to install Gentoo with a bcachefs rootfs may prefer to start with bcachefs/rootfs.

bcachefs is a fully-featured B-tree filesystem based on bcache. It includes features such as Copy-on-Write (CoW), compression, and encryption. Bcachefs is comparable to Btrfs and ZFS.

A noteworthy feature is native tiered storage support, enabling use of one or more fast disk drives (such as flash-based SSD or NVMe disks) to act as a cache for one or more slower disk drives in a pool while transparently managing hot and cold files based on activity.

Installation

Kernel

Activate the following kernel options:

Versions <6.14.0

KERNEL Enable Bcachefs and CRC32c hardware acceleration

File systems  --->
   <*> bcachefs filesystem support Search for <code>CONFIG_BCACHEFS_FS</code> to find this item.
-*- Cryptographic API --->
   Accelerated Cryptographic Algorithms for CPU (x86) --->
       <*> CRC32c (SSE4.2/PCLMULQDQ) Search for <code>CONFIG_CRYPTO_CRC32C_INTEL</code> to find this item.

Versions >=6.14.0

KERNEL Enable Bcachefs and CRC32c hardware acceleration

File systems  --->
   <*> bcachefs filesystem support Search for <code>CONFIG_BCACHEFS_FS</code> to find this item.
Library routines --->
   [*] Enable optimized CRC implementations Search for <code>CONFIG_CRC_OPTIMIZATIONS</code> to find this item.

Note
If the crc32c-intel module is available and bcachefs loads before it (or is built in) the CRC32 hardware instruction will not be used resulting in increased system resource utilisation. Ensure that the module loads before bcachefs or build it into the kernel to avoid this.

USE flags

USE flags for sys-fs/bcachefs-tools Tools for bcachefs

debug	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
fuse	Enable bcachefs FUSE support (experimental!)
verify-sig	Verify upstream signatures on distfiles

Data provided by the Gentoo Package Database · Last update: 2025-04-19 00:15 More information about USE flags

Emerge

Tip
If the bcachefs-tools version on the system is too old for the filesystem errors similar to the following may occur:

bcachefs (/dev/sdc): error reading default superblock: Unsupported superblock version 26 (min 9, max 25)bcachefs (/dev/sdc): error reading superblock: Unsupported superblock version 26 (min 9, max 25)Unsupported superblock version 26 (min 9, max 25)

If the version of bcachefs-tools in the Gentoo repository doesn't work with the latest kernel try building it using the live ebuild (-9999) or directly from git.

root #emerge --ask sys-fs/bcachefs-tools

Shell completions

Note
As of sys-fs/bcachefs-tools-1.6.1-r1, manually installing the shell completion scripts are unnecessary for Bash, ZSH, and Fish.

Emerging the package does not automatically install shell completions, to install shell completions for bcachefs, use the command bcachefs completions. Currently only the following shells have completions: Bash, Evlish, Fish, Powershell, and ZSH.

root #bcachefs completions <shell>

Usage

Creation

To format and use a single filesystem with bcachefs:

root #bcachefs format /dev/sda1

For a multi device filesystem, with /dev/sda caching /dev/sdb:

root #bcachefs format /dev/sd[ab] --foreground_target /dev/sda --promote_target /dev/sda --background_target /dev/sdb --metadata_target /dev/sda

root #mount -t bcachefs /dev/sda:/dev/sdb /mnt

Options

To set options on a filesystem after creation, use bcachefs set-option:

root #bcachefs set-option --compression=lz4 /dev/sdb

Mount

There are multiple ways to mount a bcachefs filesystem once it has been created, manually mounting and using the fstab.

Single-Device Bcachefs

root #mount -t bcachefs /dev/sdb /mnt

Or to mount with bcachefs:

root #bcachefs mount /dev/sdb /mnt

To add it to the fstab:

FILE /etc/fstab

/dev/sdb /mnt bcachefs defaults 0 0

Multi-Device Bcachefs

Systemd does currently not support multi-device fstab entries (see https://github.com/systemd/systemd/issues/8234). As workaround, you can use OLD_BLK_UUID

FILE /etc/fstab

OLD_BLKID_UUID=fc13390c-7e1a-4d64-8626-f3c1e2390856    /mnt   bcachefs defaults 0 0

The UUID could be obtained, for example, via

user $lsblk -f

Resizing

Important
Shrinking a filesystem is not currently supported

Resizing the filesystem can be done with the device resize command:

root #bcachefs device resize /dev/sda [size]

To resize the journal on a device, use resize-journal:

root #bcachefs device resize-journal /dev/sda [size]

Compression

Currently, bcachefs supports gzip, lz4, and zstd for compression. To compress a filesystem on format, add the option as an argument:

root #bcachefs format --compression=zstd /dev/sdb

Multiple devices

Adding

To add a device to an existing bcachefs filesystem, use device add:

root #bcachefs device add <External UUID> /dev/sdb

Removing

To remove the device just added, use remove

root #bcachefs device remove /dev/sdb

Connecting

To add a device to a mounted filesystem that did not have the device when mounted, use online:

root #bcachefs device online /dev/sdb

Disconnecting

To remove a device from a mounted filesystem without removing it, use offline:

root #bcachefs device offline /dev/sdb

Evacuating

To prepare a drive for removal and migrate data off of it, use evacuate:

root #bcachefs device evacuate /dev/sdb

Device state

A device can be in one of four states: rw, ro, failed, spare. A failed device has zero durability and replicas do not count towards the number an extent should have.

To set a device in the failed state, use set-state:

root #bcachefs device set-state failed /dev/sdb

Subvolumes

Important
Listing subvolumes is still in development so in the meantime, having to know what directory is or is not a subvolume is important.

Subvolumes in Bcachefs can currently be interacted with in three different ways: creation, deletion, and snapshots. They also do not need to be mounted as the filesystem handles it when the main volume is mounted.

Create

root #bcachefs subvolume create <name>

Delete

root #bcachefs subvolume delete <name>

Snapshots

Note
The path to the subvolume is only needed if the snapshot directory is stored inside of a different subvolume.

root #bcachefs subvolume create /path/to/subvolume /path/to/snapshots/name

Encryption

Changing the passphrase

To change the passphrase on an encrypted filesystem:

root #bcachefs set-passphrase /dev/sda

Unlocking

The simplest way to decrypt a bcachefs volume (or pool) is to use the following command on a single member:

root #bcachefs unlock /dev/sdx

To decrypt a bcachefs volume while using systemd, insert '-k session' into the unlock command:

root #bcachefs unlock -k session /dev/sdx

It is also possible to permanently unlock a filesystem using the remove-passphrase command:

root #bcachefs remove-passphrase /dev/sda

Labels and target options

By default, bcachefs stripes writes across all devices in a filesystem. For more control over the placement of data (or to improve performance) it is possible to direct particular filesystem activity to a disk or collection of disks using labels.

In bcachefs these activities are categorised as target options. Four target options exist which may be set at the filesystem level (at format time, at mount time, or at runtime via sysfs), or on a particular file or directory:

• foreground target: normal foreground data writes, and metadata if metadata target is not set
• metadata target: btree writes
• background target: If set, user data (not metadata) will be moved to this target in the background
• promote target: If set, a cached copy will be added to this target on read, if none exists

Label names are arbitrary - ssd.ssd1 works just as well as ssd.1 or fast.1. Labels are also hierarchical: to refer to all disks labelled ssd.ssd#, ssd may be used. Labels are not required and it is possible to target to a device directly (e.g. /dev/sda1) however this is not recommended; udev naming is not reliable. In larger pools it is advised to instead use a label for any target that needs to be configured.

Target options may be set as file attributes (i.e. controlled per-file). The bcachefs setattr command is used for this, e.g.:

root #bcachefs setattr --background_target=ssd /path/to/file

Filesystem information

Showing the superblock

Displaying information about the superblock shows everything needed to determine what a bcachefs device does, i.e. it displays: compression type, device members, quotas, if ACLs are enabled, and more.

root #bcachefs show-super /dev/sdb

Data usage

To display information regarding the usage of the filesystem, use fs usage:

root #bcachefs fs usage

Advanced usage

Bcachefs supports a a number of additional features, including compression, encryption, and disk labels; an example configuration using these features may be found below:

root #bcachefs format --compression=zstd \

    --encrypted \
    --replicas=2 \
    --label=hdd.hdd1 /dev/sdc \
    --label=hdd.hdd2 /dev/sdd \
    --label=hdd.hdd3 /dev/sde \
    --label=hdd.hdd4 /dev/sdf \
    --label=hdd.hdd5 /dev/sdg \
    --label=hdd.hdd6 /dev/sdh \
    --label=hdd.hdd7 /dev/sdi \
    --label=hdd.hdd8 /dev/sdj \
    --label=hdd.hdd9 /dev/sdk \
    --label=ssd.ssd1 /dev/sdl \
    --label=ssd.ssd2 /dev/sdm \
    --label=ssd.ssd3 /dev/sdn \
    --label=ssd.ssd4 /dev/sdo \
    --label=ssd.ssd5 /dev/sdp \
    --label=ssd.ssd6 /dev/sdq \
    --foreground_target=ssd \
    --promote_target=ssd \
    --background_target=hdd \
    --metadata_target=ssd

Troubleshooting

Filesystem check

It is possible to check for corruption on a bcachefs filesystem either in userspace or when being mounted by the kernel.

To check in userspace, using the fsck utility should help:

root #bcachefs fsck /dev/sdb

Or a "dry-run" can be ran using the arguments -ny

root #bcachefs fsck -ny /dev/sdb

To run fsck when being mounted, providing -o fsck in the mount options should suffice.

Debugging information

To get debugging information for a bcachefs filesystem, the dump, list, and list_journal commands will be useful.

Dumping a bcachefs filesystem will dump its metadata into a .qcow2 image file

root #bcachefs dump

Listing a filesystem will give the same functionality as the debugfs interface, listing btree nodes and contents but for offline filesystems.

root #bcachefs list

Listing the contents of the journal will show the records of btree updates ordered by when they occurred

root #bcachefs list_journal

See also

• Bcache — a Linux kernel block layer cache.
• Btrfs — a copy-on-write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, self-healing properties, and easy administration.
• ZFS — a next generation filesystem created by Matthew Ahrens and Jeff Bonwick.