NAME

bcachefs — manage bcachefs filesystems/devices

SYNOPSIS

DESCRIPTION

The bcachefs utility supports the following subcommands, which are documented in detail below:

Superblock commands

bcachefs format [options] devices ...

Format one or a list of devices with bcachefs data structures. You need to do this before you create a volume.

Device specific options must come before corresponding devices, e.g.

bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb

--block_size=size

block size, in bytes (e.g. 4k)

--btree_node_size=size

Btree node size, default 256k

--errors=(continue | ro | panic)

Action to take on filesystem error

--data_replicas=number

Number of data replicas. With erasure coding enabled, this is currently capped at 3 (RAID6).

--metadata_replicas=number

Number of metadata replicas

--encoded_extent_max=size

Maximum size of checksummed/compressed extents

--metadata_checksum=(none | crc32c | crc64 | xxhash)

Set metadata checksum type (default: crc32c).

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--str_hash=(crc32c | crc64 | siphash)

Hash function for directory entries and xattrs

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (RAID5/6; data replicas are capped at 3)

--inodes_32bit

Constrain inode numbers to 32 bits

--shared_inode_numbers

Shared new inode numbers by CPU id

--inodes_use_key_cache

Use the btree key cache for the inodes btree

--gc_reserve_percent=percentage

Percentage of disk space to reserve for copygc

--gc_reserve_bytes=percentage

Amount of disk space to reserve for copygc

This takes precedence over gc_reserve_percent if set

--root_reserve_percent=percentage

Percentage of disk space to reserve for superuser

--wide_macs

Store full 128bits of cryptographic MACS, instead of 80

--acl

Enable POSIX acls

--usrquota

Enable user quotas

--grpquota

Enable group quotas

--prjquota

Enable project quotas

--journal_transaction_names

Log transaction function names in journal

--nocow

Nocow mode: Writes will be done in place when possible.

Snapshots and reflink will still cause writes to be COW.

This flag implicitly disables data checksumming, compression and encryption.

--replicas=number

Sets both data and metadata replicas.

--encrypted

Enable whole filesystem encryption (chacha20/poly1305); passphrase will be prompted for.

--no_passphrase

Store master encryption key unencrypted in superblock

-L, --fs_label=label

Create the filesystem with the specified label This is the filesystem label, distinct from per-device labels used for target selection. On a mounted filesystem it can be changed by tools that issue the standard Linux FS_IOC_SETFSLABEL ioctl.

-U, --uuid=uuid

Create the filesystem with the specified uuid

--superblock_size=size

Device specific options:

--discard

Enable discard/TRIM support

--fs_size=size

Create the filesystem using size bytes on the subsequent device.

--bucket=size

Specifies the bucket size; must be greater than the btree node size

--durability=n

Data written to this device will be considered to have already been replicated n times

-l, --label

Disk label

-f, --force

Force the filesystem to be created, even if the device already contains a filesystem.

-q, --quiet

Only print errors

-v, --verbose

Verbose filesystem initialization

bcachefs show-super [options] device

Dump superblock information to stdout.

-f, --fields=fields

List of sections to print

-l, --layout

Print superblock layout

bcachefs set-fs-option [options] device

--errors=(continue | ro | panic)

Action to take on filesystem error

--metadata_replicas=number

Number of metadata replicas

--data_replicas=number

Number of data replicas. With erasure coding enabled, this is currently capped at 3 (RAID6).

--metadata_checksum=(none | crc32c | crc64 | xxhash)

Set metadata checksum type (default: crc32c).

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--str_hash=(crc32c | crc64 | siphash)

Hash function for directory entries and xattrs

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (RAID5/6; data replicas are capped at 3)

--inodes_32bit

Constrain inode numbers to 32 bits

--shared_inode_numbers

Shared new inode numbers by CPU id

--inodes_use_key_cache

Use the btree key cache for the inodes btree

--gc_reserve_percent=percentage

Percentage of disk space to reserve for copygc

--gc_reserve_bytes=percentage

Amount of disk space to reserve for copygc

This takes precedence over gc_reserve_percent if set

--root_reserve_percent=percentage

Percentage of disk space to reserve for superuser

--wide_macs

Store full 128bits of cryptographic MACS, instead of 80

--acl

Enable POSIX acls

--usrquota

Enable user quotas

--grpquota

Enable group quotas

--prjquota

Enable project quotas

--degraded

Allow mounting in degraded mode

--very_degraded

Allow mounting in when data will be missing

--discard

Enable discard/TRIM support

--verbose

Extra debugging information during mount/recovery

--journal_flush_delay=ms

Delay in milliseconds before automatic journal commits

--journal_flush_disabled

Disable journal flush on sync/fsync

If enabled, writes can be lost, but only since the last journal write (default 1 second)

--journal_reclaim_delay=ms

Delay in milliseconds before automatic journal reclaim

--move_bytes_in_flight=bytes

Maximum Amount of IO to keep in flight by the move path

--move_ios_in_flight=number

Maximum number of IOs to keep in flight by the move path

--fsck

Run fsck on mount

--fix_errors=error

Fix errors during fsck without asking

--ratelimit_errors

Ratelimit error messages during fsck

--nochanges

Super read only mode - no writes at all will be issued, even if we have to replay the journal

--norecovery

Don't replay the journal

--journal_transaction_names

Log transaction function names in journal

--noexcl

Don't open device in exclusive mode

--direct_io

Use O_DIRECT (userspace only)

--sb=offset

Sector offset of superblock

--reconstruct_alloc

Reconstruct alloc btree

--version_upgrade=(compatible | incompatible | none)

Set superblock to latest version, allowing any new features to be used

compatible is the default: compatible metadata upgrades may be applied automatically, and the filesystem may still downgrade those compatible version fields when mounted by an older kernel. Use incompatible only for an intentional one-way metadata upgrade that may prevent mounting with older kernels, and use none to avoid optional version upgrades.

--nocow

Nocow mode: Writes will be done in place when possible.

Snapshots and reflink will still cause writes to be COW.

This flag implicitly disables data checksumming, compression and encryption.

--nocow_enabled

Enable nocow mode: enables runtime locking in data move path needed if nocow will ever be in use

--no_data_io

Skip submit_bio() for data reads and writes, for performance testing purposes

Mount commands

bcachefs mount [options] device mountpoint

The mount -t bcachefs path invokes the installed mount.bcachefs helper; this is the same mount path exposed as bcachefs mount.

Mount a filesystem. The device can be a device, a colon-separated list of devices, UUID=<UUID>, OLD_BLKID_UUID=<UUID>, or LABEL=<label>. Use OLD_BLKID_UUID=<UUID> in fstab entries when systemd consumes UUID=<UUID> before the bcachefs mount helper can scan all members. The mountpoint is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted but all steps preceding mounting the filesystem (e.g. asking for passphrase) will still be performed.

-o options

Mount options provided as a comma-separated list. See user guide for complete list.

degraded

Allow mounting with missing devices. Use degraded=yes to allow normal operation with devices missing, and degraded=very only when writes are allowed to continue even if the requested replica count cannot be maintained.

Use degraded read-write mounts for recovery and maintenance when some members are temporarily unavailable. Do not mount different subsets of the same filesystem read-write, or mount one subset read-write and later mount a different subset read-write before the full filesystem has been assembled and reconciled. That creates split-brain history: each subset can accept writes that the other subset never saw, and when the members are later brought back together there may be no single correct value for conflicting files.

When in doubt, mount degraded filesystems read-only until the missing members are available, or assemble the complete filesystem before allowing writes.

verbose

Extra debugging info during mount/recovery

fsck

Run fsck during mount

fix_errors

Fix errors without asking during fsck

read_only

Mount in read only mode

version_upgrade

 

-k, --key-location=(fail | wait | ask)

Where the password would be loaded from. (default: ask).

fail

don't ask for password, fail if filesystem is encrypted.

wait

wait for password to become available before mounting.

ask

prompt the user for password.

-c, --colorize=(true | false)

Force color on/off. Default: auto-detect TTY

-n, --no-mtab

Do not update /etc/mtab. This is accepted for compatibility with mount(8); bcachefs uses the mount syscall directly and does not update /etc/mtab.

-f, --fake

Do everything except the actual mount syscall. Accepted for compatibility with mount(8).

-s, --sloppy

Ignore unrecognized mount options instead of failing. Accepted for compatibility with mount(8); bcachefs already ignores unrecognized options.

-v

Be verbose. Can be specified more than once.

Repair commands

bcachefs fsck [options] devices ...

Check an existing filesystem for errors.

-p

Automatic repair (no questions)

-n

Don't repair, only check for errors

-y

Assume "yes" to all questions

-f

Force checking even if filesystem is marked clean

-r, --ratelimit_errors

Don't display more than 10 errors of a given type

-R, --reconstruct_alloc

Reconstruct the alloc btree

-v

Be verbose

Commands for managing a running filesystem

bcachefs fs usage [options] [filesystem]

Show disk usage.

-h, --human-readable

Print human readable sizes.

bcachefs fs top [options] [filesystem]

Show live filesystem performance counters. When stdout is a terminal, this starts an interactive display. When stdout is not a terminal, it prints one sample and exits.

-h, --human-readable

Print human readable sizes.

--once

Print one sample and exit; equivalent to specifying a count of 1.

-n, --count=count

Print count samples and exit. A count of 0 keeps the interactive display running.

-d, --delay=seconds

Delay between samples, in seconds.

Commands for managing devices within a running filesystem

bcachefs device add [options] device

Add a device to an existing filesystem.

--fs_size=size

Size of filesystem on device

--bucket=size

Set bucket size

--discard

Enable discards

-l, --label=label

Disk label

-f, --force

Use device even if it appears to already be formatted

bcachefs device remove [options] device

Remove a device from a filesystem

-f, --force

Force removal, even if some data couldn't be migrated

-F, --force-metadata

Force removal, even if some metadata couldn't be migrated

bcachefs device online device

Re-add a device to a running filesystem

bcachefs device offline device

Take a device offline, without removing it

-f, --force

Force, if data redundancy will be degraded

bcachefs device evacuate device

Move data off of a given device

bcachefs device set-state [options] new-state device

new-state=(rw | ro | evacuating | spare)

New member state. Use rw to cancel an in-progress evacuation and return the device to normal use.

-f, --force

Force, if data redundancy will be degraded

--force-if-data-lost

Force, if data will be lost

-o, --offline

Set state of an offline device

bcachefs device resize device [size]

Resize filesystem on a device. Online shrinking is passed to the mounted filesystem kernel; if that kernel does not support shrinking, the resize ioctl fails. Offline shrinking is still unsupported by the bundled userspace filesystem implementation.

bcachefs device resize-journal device [size]

Resize journal on a device

Commands for managing subvolumes and snapshots

subvolume create [options] path

Create a new subvolume

subvolume delete [options] path

Delete an existing subvolume

Subvolume roots may be renamed or moved as subvolume roots. Ordinary files and directories cannot be renamed across subvolume boundaries; copy or reflink data when reorganizing contents between subvolumes.

subvolume snapshot [options] source dest

Create a snapshot of source at dest. If specified, source must be a subvolume; if not specified the snapshot will be of the subvolume containing dest.

-r

Make snapshot read-only

subvolume list [options] target

List subvolumes in a mounted filesystem.

--json

Output machine-readable JSON.

-t, --tree

Show a hierarchical view.

-R, --recursive

List subvolumes recursively.

-s, --snapshots

Include snapshot subvolumes.

--readonly

Only show read-only subvolumes.

--sort=(name | size | time)

Sort output.

subvolume list-snapshots [options] target

List snapshots and their disk usage in a mounted filesystem.

-f, --flat

Show a flat list instead of the default tree.

-R, --recursive

List snapshot trees for nested subvolumes too.

--json

Output machine-readable JSON, including snapshot IDs and parent relationships.

--readonly

Only show read-only snapshots in flat view.

--sort=(name | size | time)

Sort flat output.

Commands for managing filesystem data

bcachefs scrub [-m | --metadata] filesystem

Verify checksums and correct errors, if possible. When scrub finds checksum errors, affected file paths are currently reported in the kernel log.

-m, --metadata

Check metadata only

bcachefs reconcile status [-t type[,...]]

[filesystem] Show pending background reconciliation work. Reconcile restores redundancy after a degraded mount or device replacement; mounted filesystems also queue reconcile work automatically when degraded extents are detected.

-t, --types type[,...]

Limit output to the selected reconciliation types.

bcachefs reconcile wait [-t type[,...]]

[filesystem] Wait for background reconciliation work to finish.

-t, --types type[,...]

Wait only for the selected reconciliation types.

Commands for encryption

bcachefs unlock device

Unlock an encrypted filesystem prior to running/mounting.

-c

Check if a device is encrypted

-k=(session | user | user_session)

Keyring to add to (default: user)

bcachefs set-passphrase devices ...

Change passphrase on an existing encrypted (unmounted) filesystem. This rewraps the existing filesystem encryption key; it does not enable encryption on a filesystem formatted without --encrypted.

bcachefs remove-passphrase devices ...

Remove passphrase protection from an existing encrypted (unmounted) filesystem. This stores the existing filesystem encryption key without passphrase protection; it does not decrypt existing data or disable filesystem encryption.

Commands for migration

bcachefs migrate [options] device

Migrate an existing filesystem to bcachefs

-f fs

Root of filesystem to migrate

--encrypted

Enable whole filesystem encryption (chacha20/poly1305)

--no_passphrase

Store master encryption key unencrypted in superblock

-F

Force, even if metadata file already exists

bcachefs migrate-superblock [options] device

Create default superblock after migrating

-d device

Device to create superblock for

-o offset

Offset of existing superblock

Commands for operating on files in a bcachefs filesystem

bcachefs set-file-option [options] [files|folders] ...

Set various per-file attributes on files and directories in a bcachefs filesystem. When applied to directories, attributes are propagated recursively to all files and subdirectories within. Changed options take effect immediately for new writes. For existing data, background reconcile applies changed IO options asynchronously, for example rewriting existing extents with a new compression algorithm or replica count.

--data_replicas=number

Number of data replicas. With erasure coding enabled, this is currently capped at 3 (RAID6).

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (RAID5/6; data replicas are capped at 3)

--project

--nocow

Nocow mode: Writes will be done in place when possible.

--remove-all

Remove all file options from the specified files/directories

To remove specific options, use --option=-

Options can be chained together to perform multiple operations in a single command, for example:

bcachefs set-file-option --remove-all --compression=lz4

.

bcachefs set-file-option --compression=- --background_compression=zstd:10 --data_replicas=- file.txt

bcachefs reflink-option-propagate [--set-may-update] files...

Propagate each file's current IO options, including compression, checksum, replicas, and targets, to its extents. This includes indirect, reflinked extents where the reflink pointer permits option updates.

--set-may-update

Enable option propagation on old reflink pointers that predate the may-update-options permission flag. This requires administrative privileges and is only needed once per affected file.

Commands for debugging

These commands work on offline, unmounted filesystems.

bcachefs dump [options] device

Dump filesystem metadata

-o output

Required flag: Output qcow2 image(s)

-f, --force

Force; overwrite when needed

--nojournal

Don't dump entire journal, just dirty entries

bcachefs list [options] devices ...

List filesystem metadata to stdout

-b (extents | inodes | dirents | xattrs)

Btree to list from. (default: extents)

-l, --level

Btree depth to descend to. ( 0 == leaves; default: 0)

-s inode:offset

Start position to list from

-e inode:offset

End position

-m, --mode (keys | formats | nodes | nodes-ondisk)

(default: keys)

-f

Check (fsck) the filesystem first

-c, --colorize=(true | false)

Force color on/off. Default: auto-detect TTY

-v

Verbose mode

bcachefs list_journal [options] devices ...

-a

Read entire journal, not just dirty entries

-n, --nr-entries=nr

Number of journal entries to print, starting from the most recent

-s, --seq=seq[..seq]

Journal entry sequence or range to print (e.g., 123, 100..200, 100.., ..200)

-t, --transaction-filter=bbpos

Filter transactions not updating bbpos

-k, --key-filter=btree

Filter keys not updating btree

-v, --verbose

Verbose mode

FUSE commands

bcachefs fusemount

Mount a filesystem via FUSE

Miscellaneous commands

bcachefs completions shell

Generate shell completions

bcachefs version

Display the version of the invoked bcachefs tool

EXIT STATUS

The bcachefs utility exits 0 on success, and >0 if an error occurs.