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
    Set a device state
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
subvolume list
    List subvolumes
subvolume list-snapshots
    List snapshots and their disk usage

  Commands for managing filesystem data
reconcile
    Query or wait for background data reconciliation
scrub
    Verify data checksums

  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. With erasure coding enabled, this is currently capped at 3 (RAID6).

    --metadata_replicas=number
        Number of metadata replicas

    --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 (RAID5/6; data replicas are capped at 3)

    --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
        Store master encryption key unencrypted in superblock

    -L, --fs_label=label
        Create the filesystem with the specified label This is the filesystem label, distinct from per-device labels used for target selection. On a mounted filesystem it can be changed by tools that issue the standard Linux FS_IOC_SETFSLABEL ioctl.

    -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. With erasure coding enabled, this is currently capped at 3 (RAID6).

    --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 (RAID5/6; data replicas are capped at 3)

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

        compatible is the default: compatible metadata upgrades may be applied automatically, and the filesystem may still downgrade those compatible version fields when mounted by an older kernel. Use incompatible only for an intentional one-way metadata upgrade that may prevent mounting with older kernels, and use none to avoid optional version upgrades.

    --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
    The mount -t bcachefs path invokes the installed mount.bcachefs helper; this is the same mount path exposed as bcachefs mount.

    Mount a filesystem. The device can be a device, a colon-separated list of devices, UUID=<UUID>, OLD_BLKID_UUID=<UUID>, or LABEL=<label>. Use OLD_BLKID_UUID=<UUID> in fstab entries when systemd consumes UUID=<UUID> before the bcachefs mount helper can scan all members. 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 missing devices. Use degraded=yes to allow normal operation with devices missing, and degraded=very only when writes are allowed to continue even if the requested replica count cannot be maintained.

            Use degraded read-write mounts for recovery and maintenance when some members are temporarily unavailable. Do not mount different subsets of the same filesystem read-write, or mount one subset read-write and later mount a different subset read-write before the full filesystem has been assembled and reconciled. That creates split-brain history: each subset can accept writes that the other subset never saw, and when the members are later brought back together there may be no single correct value for conflicting files.

            When in doubt, mount degraded filesystems read-only until the missing members are available, or assemble the complete filesystem before allowing writes.
        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

    -n, --no-mtab
        Do not update /etc/mtab. This is accepted for compatibility with mount(8); bcachefs uses the mount syscall directly and does not update /etc/mtab.

    -f, --fake
        Do everything except the actual mount syscall. Accepted for compatibility with mount(8).

    -s, --sloppy
        Ignore unrecognized mount options instead of failing. Accepted for compatibility with mount(8); bcachefs already ignores unrecognized options.

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

bcachefs fs top [options] [filesystem]
    Show live filesystem performance counters. When stdout is a terminal, this starts an interactive display. When stdout is not a terminal, it prints one sample and exits.

    -h, --human-readable
        Print human readable sizes.

    --once
        Print one sample and exit; equivalent to specifying a count of 1.

    -n, --count=count
        Print count samples and exit. A count of 0 keeps the interactive display running.

    -d, --delay=seconds
        Delay between samples, in seconds.

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 | evacuating | spare)
        New member state. Use rw to cancel an in-progress evacuation and return the device to normal use.

    -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. Online shrinking is passed to the mounted filesystem kernel; if that kernel does not support shrinking, the resize ioctl fails. Offline shrinking is still unsupported by the bundled userspace filesystem implementation.

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 roots may be renamed or moved as subvolume roots. Ordinary files and directories cannot be renamed across subvolume boundaries; copy or reflink data when reorganizing contents between subvolumes.

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

subvolume list [options] target
    List subvolumes in a mounted filesystem.

    --json
        Output machine-readable JSON.

    -t, --tree
        Show a hierarchical view.

    -R, --recursive
        List subvolumes recursively.

    -s, --snapshots
        Include snapshot subvolumes.

    --readonly
        Only show read-only subvolumes.

    --sort=(name | size | time)
        Sort output.

subvolume list-snapshots [options] target
    List snapshots and their disk usage in a mounted filesystem.

    -f, --flat
        Show a flat list instead of the default tree.

    -R, --recursive
        List snapshot trees for nested subvolumes too.

    --json
        Output machine-readable JSON, including snapshot IDs and parent relationships.

    --readonly
        Only show read-only snapshots in flat view.

    --sort=(name | size | time)
        Sort flat output.

Commands for managing filesystem data

bcachefs scrub [-m | --metadata] filesystem
    Verify checksums and correct errors, if possible. When scrub finds checksum errors, affected file paths are currently reported in the kernel log.

    -m, --metadata
        Check metadata only

bcachefs reconcile status [-t type[,...]]
    [filesystem] Show pending background reconciliation work. Reconcile restores redundancy after a degraded mount or device replacement; mounted filesystems also queue reconcile work automatically when degraded extents are detected.

    -t, --types type[,...]
        Limit output to the selected reconciliation types.

bcachefs reconcile wait [-t type[,...]]
    [filesystem] Wait for background reconciliation work to finish.

    -t, --types type[,...]
        Wait only for the selected reconciliation types.

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 encrypted (unmounted) filesystem. This rewraps the existing filesystem encryption key; it does not enable encryption on a filesystem formatted without --encrypted.

bcachefs remove-passphrase devices ...
    Remove passphrase protection from an existing encrypted (unmounted) filesystem. This stores the existing filesystem encryption key without passphrase protection; it does not decrypt existing data or disable filesystem encryption.

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
        Store master encryption key unencrypted in superblock

    -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. Changed options take effect immediately for new writes. For existing data, background reconcile applies changed IO options asynchronously, for example rewriting existing extents with a new compression algorithm or replica count.

    --data_replicas=number
        Number of data replicas. With erasure coding enabled, this is currently capped at 3 (RAID6).

    --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 (RAID5/6; data replicas are capped at 3)

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

bcachefs reflink-option-propagate [--set-may-update] files...
    Propagate each file's current IO options, including compression, checksum, replicas, and targets, to its extents. This includes indirect, reflinked extents where the reflink pointer permits option updates.

    --set-may-update
        Enable option propagation on old reflink pointers that predate the may-update-options permission flag. This requires administrative privileges and is only needed once per affected file.

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