BCACHEFS(8)

NAME
bcachefs - manage bcachefs filesystems/devices

SYNOPSIS
bcachefs command [options] [arguments]

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

  Superblock commands
format
    Format one or a list of devices with bcachefs data structures.
show-super
    Dump superblock information to stdout.

  Repair commands
fsck
    Check an existing filesystem for errors.

  Startup/shutdown, assembly of multi device filesystems
assemble
    Assemble an existing multi device filesystem
incremental
    Incrementally assemble an existing multi device filesystem
run Start a partially assembled filesystem.
stop
    Stop a running filesystem.

  Commands for managing a running filesystem
fs usage
    Show disk usage

  Commands for managing devices within a running filesystem
device add
    Add a new device to an existing filesystem
device remove
    Remove a device from an existing filesystem
device online
    Re-add an existing member to a filesystem
device offline
    Take a device offline, without removing it
device evacuate
    Migrate data off of a specific device
device set-state
    Mark a device as failed
device resize
    Resize filesystem on a device

  Commands for managing filesystem data
data rereplicate
    Rereplicate degraded data

  Commands for encryption
unlock
    Unlock an encrypted filesystem prior to running/mounting
set-passphrase
    Change passphrase on an existing (unmounted) filesystem
remove-passphrase
    Remove passphrase on an existing (unmounted) filesystem

  Commands for migration
migrate
    Migrate an existing filesystem to bcachefs, in place
migrate-superblock
    Add default superblock, after bcachefs migrate

  Commands for debugging
dump
    Dump filesystem metadata to a qcow2 image
list
    List filesystem metadata in textual form

  Miscellaneous commands
version
    Display the version of the invoked bcachefs tool

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] device new-state

    -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