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.
set-fs-option
    Set a filesystem option

  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
fs top
    Show runtime performance information

  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
    Change the state of a device
device resize
    Resize filesystem on a device
device resize-journal
    Resize journal on a device

  Commands for managing subvolumes and snapshots
subvolume create
    Create a new subvolume
subvolume delete
    Delete an existing subvolume
subvolume snapshot
    Create a snapshot

  Commands for managing filesystem data
data rereplicate
    Rereplicate degraded data
data job
    Kick off low level data jobs

  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 operating on files in a bcachefs filesystem
set-file-option
    Set various per file attributes

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

  FUSE commands
fusemount Mount a filesystem via FUSE

  Miscellaneous commands
version
    Display the version of the invoked bcachefs tool
completions
    Generate shell completions

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

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

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

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

    -r, --ratelimit_errors
        Don't display more than 10 errors of a given type

    -R, --reconstruct_alloc
        Reconstruct the alloc btree

    -v  Be verbose

Commands for managing a running filesystem

bcachefs fs usage [options] [filesystem]
    Show disk usage.

    -h, --human-readable
        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

    -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

Commands for managing subvolumes and snapshots

subvolume create [options] path
    Create a new subvolume

subvolume delete [options] path
    Delete an existing subvolume

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

Commands for managing filesystem data

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

Commands for encryption

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.

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 operating on files in a bcachefs filesystem

bcachefs set-file-option [options] [files|folders] ...
    Set various per-file attributes on files and directories in a bcachefs filesystem. When applied to directories, attributes are propagated recursively to all files and subdirectories within.

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

    --remove-all
        Remove all file options from the specified files/directories

    To remove specific options, use --option=-

    Options can be chained together to perform multiple operations in a single command, for example:
        bcachefs set-file-option --remove-all --compression=lz4.
        bcachefs set-file-option --compression=- --background_compression=zstd:10 --data_replicas=- file.txt

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

    -s, --seq=seq[..seq]
        Journal entry sequence or range to print (e.g., 123, 100..200, 100.., ..200)

    -t, --transaction-filter=bbpos
        Filter transactions not updating bbpos

    -k, --key-filter=btree
        Filter keys not updating btree

    -v, --verbose
        Verbose mode

FUSE commands

bcachefs fusemount
    Mount a filesystem via FUSE

Miscellaneous commands

bcachefs completions shell
    Generate shell completions

bcachefs version
    Display the version of the invoked bcachefs tool

EXIT STATUS