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.

  Mount commands
mount
    Mount a filesystem.

  Repair commands
fsck
    Check an existing filesystem for errors.

  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

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