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

Mount commands

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 preceeding mounting the filesystem (e.g. asking for passphrase) will still be performed.

-o options

Mount options provided as a comma-separated list. See userguide 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.

-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

-v

Be verbose

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.