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

-b, --block=size

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

--btree_node=size

Btree node size, default 256k

--metadata_checksum_type=(none | crc32c | crc64)

Set metadata checksum type (default: crc32c).

--data_checksum_type=(none | crc32c | crc64)

Set data checksum type (default: crc32c).

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

Set compression type (default: none).

--data_replicas=number

Number of data replicas

--metadata_replicas=number

Number of metadata replicas

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

--error_action=(continue | remount-ro | panic)

Action to take on filesystem error (default: remount-ro)

-L, --label=label

Create the filesystem with the specified label

-U, --uuid=uuid

Create the filesystem with the specified uuid

-f, --force

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

Device specific options:

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

--discard

Enable discards on subsequent devices

-q, --quiet

Only print errors

bcachefs show-super [options] device

Dump superblock information to stdout.

-f, --fields=fields

List of sections to print

-l, --layout

Print superblock layout

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

-v

Be verbose

Startup/shutdown, assembly of multi device filesystems¶

bcachefs assemble devices ...

Assemble an existing multi device filesystem.

bcachefs incremental device

Incrementally assemble an existing multi device filesystem.

bcachefs run

Start a partially assembled filesystem.

bcachefs stop filesystem

Stop a running filesystem.

Commands for managing a running filesystem¶

bcachefs fs usage [options] [filesystem]

Show disk usage.

-h

Print human readable sizes.

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

-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

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

bcachefs device resize device [size]

Resize filesystem on a device

Commands for managing filesystem data¶

bcachefs device rereplicate filesystem

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

Commands for encryption¶

bcachefs unlock device

Unlock an encrypted filesystem prior to running/mounting.

bcachefs set-passphrase devices ...

Change passphrase on an existing (unmounted) filesystem.

bcachefs remove-passphrase devices ...

Remove passphrase on an existing (unmounted) filesystem.

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

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

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; overwrite when needed

bcachefs list [options] devices ...

List filesystem metadata to stdout

-b (extents | inodes | dirents | xattrs)

Btree to list from

-s inode:offset

Start position to list from

-e inode:offset

End position

-i inode

List keys for a given inode number

-m (keys | formats)

 

-f

Force fsck

-v

Verbose mode List mode

Miscellaneous commands¶

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.