bcachefs - Man Page

• Format a partition with bcachefs: sudo bcachefs format path/to/partition

• Mount a bcachefs filesystem: sudo bcachefs mount path/to/partition path/to/mountpoint

• Create a RAID 0 filesystem where an SSD acts as a cache and an HDD acts as a long-term storage: sudo bcachefs format --label=ssd.ssd1 path/to/ssd/partition --label=hdd.hdd1 path/to/hdd/partition --replicas=1 --foreground_target=ssd --promote_target=ssd --background_target=hdd

• Mount a multidevice filesystem: sudo bcachefs mount path/to/partition1:path/to/partition2 path/to/mountpoint

• Display disk usage: bcachefs fs usage --human-readable path/to/mountpoint

• Display help: bcachefs

tldr.sh

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

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

--metadata_replicas=number

Number of metadata replicas

--data_replicas_required=number

--metadata_replicas_required=number

--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 (DO NOT USE YET)

--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 caused 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

Don't encrypt master encryption key

-L, --fs_label=label

Create the filesystem with the specified label

-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-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

--metadata_replicas_required=number

--data_replicas_required=number

--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 (DO NOT USE YET)

--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

--nocow

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

Snapshots and reflink will still caused 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

bcachefs mount [options] device mountpoint

Mount a filesystem. The device can be a device, a colon-separated list of devices, or UUID=<UUID>. 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 data degraded

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

-v

Be verbose. Can be specified more than once.

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

bcachefs fs usage [options] [filesystem]

Show disk usage.

-h, --human-readable

Print human readable sizes.

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 | failed | spare)

-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

bcachefs device resize-journal device [size]

Resize journal on a device

subvolume create [options] path

Create a new subvolume

subvolume delete [options] path

Delete an existing subvolume

subvolume delete [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

bcachefs data rereplicate filesystem

Walks existing data in a filesystem, writing additional copies of any degraded data.

bcachefs data job job filesystem

Kick off a data job and report progress

job is one of ( scrub | rereplicate | migrate | rewrite_old_nodes )

-b btree

Btree to operate on

-s inode:offset

Start position

-e inode:offset

End position

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 (unmounted) filesystem.

bcachefs remove-passphrase devices ...

Remove passphrase on an existing (unmounted) filesystem.

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

Don't encrypt master encryption key

-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

bcachefs setattr [options] devices ...

--data_replicas=number

Number of data replicas

--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 (DO NOT USE YET)

--project

--nocow

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

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

-t, --transaction-filter=bbpos

Filter transactions not updating bbpos

-k, --key-filter=btree

Filter keys not updating btree

-v, --verbose

Verbose mode

bcachefs fusemount

Mount a filesystem via FUSE

bcachefs completions shell

Generate shell completions

bcachefs version

Display the version of the invoked bcachefs tool

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