BCACHEFS(8) System Manager's Manual (smm) 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-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 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 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 setattr 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 caused 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-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 caused 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=. 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 delete [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 setattr [options] devices ... --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. 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 -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 The bcachefs utility exits 0 on success, and >0 if an error occurs. Linux 6.8.2-arch2-1 November 17, 2023 Linux 6.8.2-arch2-1