.Dd November 17, 2023 .Dt BCACHEFS 8 SMM .Os .Sh NAME .Nm bcachefs .Nd manage bcachefs filesystems/devices .Sh SYNOPSIS .Nm .Ar command .Op Ar options .Op Ar arguments .Sh DESCRIPTION The .Nm utility supports the following subcommands, which are documented in detail below: .Ss Superblock commands .Bl -tag -width 18n -compact .It Ic format Format one or a list of devices with bcachefs data structures. .It Ic show-super Dump superblock information to stdout. .It Ic set-option Set a filesystem option .El .Ss Mount commands .Bl -tag -width 18n -compact .It Ic mount Mount a filesystem. .El .Ss Repair commands .Bl -tag -width 18n -compact .It Ic fsck Check an existing filesystem for errors. .El .Ss Commands for managing a running filesystem .Bl -tag -width 18n -compact .It Ic fs usage Show disk usage .El .Ss Commands for managing devices within a running filesystem .Bl -tag -width 22n -compact .It Ic device add Add a new device to an existing filesystem .It Ic device remove Remove a device from an existing filesystem .It Ic device online Re-add an existing member to a filesystem .It Ic device offline Take a device offline, without removing it .It Ic device evacuate Migrate data off of a specific device .It Ic device set-state Mark a device as failed .It Ic device resize Resize filesystem on a device .It Ic device resize-journal Resize journal on a device .El .Ss Commands for managing subvolumes and snapshots .Bl -tag -width 18n -compact .It Ic subvolume create Create a new subvolume .It Ic subvolume delete Delete an existing subvolume .It Ic subvolume snapshot Create a snapshot .El .Ss Commands for managing filesystem data .Bl -tag -width 18n -compact .It Ic data rereplicate Rereplicate degraded data .It Ic data job Kick off low level data jobs .El .Ss Commands for encryption .Bl -tag -width 18n -compact .It Ic unlock Unlock an encrypted filesystem prior to running/mounting .It Ic set-passphrase Change passphrase on an existing (unmounted) filesystem .It Ic remove-passphrase Remove passphrase on an existing (unmounted) filesystem .El .Ss Commands for migration .Bl -tag -width 18n -compact .It Ic migrate Migrate an existing filesystem to bcachefs, in place .It Ic migrate-superblock Add default superblock, after bcachefs migrate .El .Ss Commands for operating on files in a bcachefs filesystem .Bl -tag -width 18n -compact .It Ic setattr Set various per file attributes .El .Ss Commands for debugging .Bl -tag -width 18n -compact .It Ic dump Dump filesystem metadata to a qcow2 image .It Ic list List filesystem metadata in textual form .It Ic list_journal List contents of journal .El .Ss FUSE commands .Bl -tag -width 18n -compact .It Ic fusemount Mount a filesystem via FUSE .El .Ss Miscellaneous commands .Bl -tag -width 18n -compact .It Ic version Display the version of the invoked bcachefs tool .It Ic completions Generate shell completions .El .Sh Superblock commands .Bl -tag -width Ds .It Nm Ic format Oo Ar options Oc Ar devices\ ... Format one or a list of devices with bcachefs data structures. You need to do this before you create a volume. .Pp Device specific options must come before corresponding devices, e.g. .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb .Bl -tag -width Ds .It Fl -block_size Ns = Ns Ar size block size, in bytes (e.g. 4k) .It Fl -btree_node_size Ns = Ns Ar size Btree node size, default 256k .It Fl -errors Ns = Ns ( Cm continue | ro | panic ) Action to take on filesystem error .It Fl -data_replicas Ns = Ns Ar number Number of data replicas .It Fl -metadata_replicas Ns = Ns Ar number Number of metadata replicas .It Fl -data_replicas_required Ns = Ns Ar number .It Fl -metadata_replicas_required Ns = Ns Ar number .It Fl -encoded_extent_max Ns = Ns Ar size Maximum size of checksummed/compressed extents .It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash ) Set metadata checksum type (default: .Cm crc32c ) . .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash ) Set data checksum type (default: .Cm crc32c ) . .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) Set compression type (default: .Cm none ) . .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) .It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash ) Hash function for directory entries and xattrs .It Fl -metadata_target Ns = Ns Ar target Device or label for metadata writes .It Fl -foreground_target Ns = Ns Ar target Device or label for foreground writes .It Fl -background_target Ns = Ns Ar target Device or label to move data to in the background .It Fl -promote_target Ns = Ns Ar target Device or label to promote data to on read .It Fl -erasure_code Enable erasure coding (DO NOT USE YET) .It Fl -inodes_32bit Constrain inode numbers to 32 bits .It Fl -shared_inode_numbers Shared new inode numbers by CPU id .It Fl -inodes_use_key_cache Use the btree key cache for the inodes btree .It Fl -gc_reserve_percent Ns = Ns Ar percentage Percentage of disk space to reserve for copygc .It Fl -gc_reserve_bytes Ns = Ns Ar percentage Amount of disk space to reserve for copygc .sp This takes precedence over .Cm gc_reserve_percent if set .It Fl -root_reserve_percent Ns = Ns Ar percentage Percentage of disk space to reserve for superuser .It Fl -wide_macs Store full 128bits of cryptographic MACS, instead of 80 .It Fl -acl Enable POSIX acls .It Fl -usrquota Enable user quotas .It Fl -grpquota Enable group quotas .It Fl prjquota Enable project quotas .It Fl -journal_transaction_names Log transaction function names in journal .It Fl -nocow Nocow mode: Writes will be done in place when possible. .sp Snapshots and reflink will still caused writes to be COW. .sp This flag implicitly disables data checksumming, compression and encryption. .It Fl -replicas Ns = Ns Ar number Sets both data and metadata replicas .It Fl -encrypted Enable whole filesystem encryption (chacha20/poly1305); passphrase will be prompted for. .It Fl -no_passphrase Don't encrypt master encryption key .It Fl L , Fl -fs_label Ns = Ns Ar label Create the filesystem with the specified .Ar label .It Fl U , -uuid Ns = Ns Ar uuid Create the filesystem with the specified .Ar uuid .It Fl -superblock_size Ns = Ns Ar size .El .Pp Device specific options: .Bl -tag -width Ds .It Fl -discard Enable discard/TRIM support .It Fl -fs_size Ns = Ns Ar size Create the filesystem using .Ar size bytes on the subsequent device. .It Fl -bucket Ns = Ns Ar size Specifies the bucket size; must be greater than the btree node size .It Fl -durability Ns = Ns Ar n Data written to this device will be considered to have already been replicated .Ar n times .It Fl l , Fl -label Disk label .It Fl f , Fl -force Force the filesystem to be created, even if the device already contains a filesystem. .It Fl q , Fl -quiet Only print errors .It Fl v , Fl -verbose Verbose filesystem initialization .El .It Nm Ic show-super Oo Ar options Oc Ar device Dump superblock information to stdout. .Bl -tag -width Ds .It Fl f , Fl -fields Ns = Ns Ar fields List of sections to print .It Fl l , Fl -layout Print superblock layout .El .It Nm Ic set-option Oo Ar options Oc Ar device .Bl -tag -width Ds .It Fl -errors Ns = Ns ( Cm continue | ro | panic ) Action to take on filesystem error .It Fl -metadata_replicas Ns = Ns Ar number Number of metadata replicas .It Fl -data_replicas Ns = Ns Ar number Number of data replicas .It Fl -metadata_replicas_required Ns = Ns Ar number .It Fl -data_replicas_required Ns = Ns Ar number .It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash ) Set metadata checksum type (default: .Cm crc32c ) . .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash ) Set data checksum type (default: .Cm crc32c ) . .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) Set compression type (default: .Cm none ) . .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) .It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash ) Hash function for directory entries and xattrs .It Fl -metadata_target Ns = Ns Ar target Device or label for metadata writes .It Fl -foreground_target Ns = Ns Ar target Device or label for foreground writes .It Fl -background_target Ns = Ns Ar target Device or label to move data to in the background .It Fl -promote_target Ns = Ns Ar target Device or label to promote data to on read .It Fl -erasure_code Enable erasure coding (DO NOT USE YET) .It Fl -inodes_32bit Constrain inode numbers to 32 bits .It Fl -shared_inode_numbers Shared new inode numbers by CPU id .It Fl -inodes_use_key_cache Use the btree key cache for the inodes btree .It Fl -gc_reserve_percent Ns = Ns Ar percentage Percentage of disk space to reserve for copygc .It Fl -gc_reserve_bytes Ns = Ns Ar percentage Amount of disk space to reserve for copygc .sp This takes precedence over .Cm gc_reserve_percent if set .It Fl -root_reserve_percent Ns = Ns Ar percentage Percentage of disk space to reserve for superuser .It Fl -wide_macs Store full 128bits of cryptographic MACS, instead of 80 .It Fl -acl Enable POSIX acls .It Fl -usrquota Enable user quotas .It Fl -grpquota Enable group quotas .It Fl -prjquota Enable project quotas .It Fl -degraded Allow mounting in degraded mode .It Fl -very_degraded Allow mounting in when data will be missing .It Fl -discard Enable discard/TRIM support .It Fl -verbose Extra debugging information during mount/recovery .It Fl -journal_flush_delay Ns = Ns Ar ms Delay in milliseconds before automatic journal commits .It Fl -journal_flush_disabled Disable journal flush on sync/fsync .sp If enabled, writes can be lost, but only since the last journal write (default 1 second) .It Fl -journal_reclaim_delay Ns = Ns Ar ms Delay in milliseconds before automatic journal reclaim .It Fl -move_bytes_in_flight Ns = Ns Ar bytes Maximum Amount of IO to keep in flight by the move path .It Fl -move_ios_in_flight Ns = Ns Ar number Maximum number of IOs to keep in flight by the move path .It Fl -fsck Run fsck on mount .It Fl -fix_errors Ns = Ns Ar error Fix errors during fsck without asking .It Fl -ratelimit_errors Ratelimit error messages during fsck .It Fl -nochanges Super read only mode - no writes at all will be issued, even if we have to replay the journal .It Fl -norecovery Don't replay the journal .It Fl -journal_transaction_names Log transaction function names in journal .It Fl -noexcl Don't open device in exclusive mode .It Fl -direct_io Use O_DIRECT (userspace only) .It Fl -sb Ns = Ns Ar offset Sector offset of superblock .It Fl -reconstruct_alloc Reconstruct alloc btree .It Fl -version_upgrade Ns = Ns ( Cm compatible | incompatible | none ) Set superblock to latest version, allowing any new features to be used .It Fl -nocow Nocow mode: Writes will be done in place when possible. .sp Snapshots and reflink will still caused writes to be COW. .sp This flag implicitly disables data checksumming, compression and encryption. .It Fl -nocow_enabled Enable nocow mode: enables runtime locking in data move path needed if nocow will ever be in use .It Fl -no_data_io Skip submit_bio() for data reads and writes, for performance testing purposes .El .El .Sh Mount commands .Bl -tag -width Ds .It Nm Ic mount Oo Ar options Oc Ar device mountpoint Mount a filesystem. The .Ar device can be a device, a colon-separated list of devices, or UUID=. The .Ar 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. .Pp the options are as follows: .Bl -tag -width Ds .It Fl o Ar options Mount options provided as a comma-separated list. See user guide for complete list. .Bl -tag -width Ds -compact .It Cm degraded Allow mounting with data degraded .It Cm verbose Extra debugging info during mount/recovery .It Cm fsck Run fsck during mount .It Cm fix_errors Fix errors without asking during fsck .It Cm read_only Mount in read only mode .It Cm version_upgrade .El .It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask ) Where the password would be loaded from. (default: .Cm ask ) . .Bl -tag -width Ds -compact .It Cm fail don't ask for password, fail if filesystem is encrypted. .It Cm wait wait for password to become available before mounting. .It Cm ask prompt the user for password. .El .It Fl c , Fl -colorize Ns = Ns ( Cm true | false ) Force color on/off. Default: auto-detect TTY .It Fl v Be verbose. Can be specified more than once. .El .El .Sh Repair commands .Bl -tag -width Ds .It Nm Ic fsck Oo Ar options Oc Ar devices\ ... Check an existing filesystem for errors. .Bl -tag -width Ds .It Fl p Automatic repair (no questions) .It Fl n Don't repair, only check for errors .It Fl y Assume "yes" to all questions .It Fl f Force checking even if filesystem is marked clean .It Fl r , Fl -ratelimit_errors Don't display more than 10 errors of a given type .It Fl R , Fl -reconstruct_alloc Reconstruct the alloc btree .It Fl v Be verbose .El .El .Sh Commands for managing a running filesystem .Bl -tag -width Ds .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem Show disk usage. .Bl -tag -width Ds .It Fl h , Fl -human-readable Print human readable sizes. .El .El .Sh Commands for managing devices within a running filesystem .Bl -tag -width Ds .It Nm Ic device Ic add Oo Ar options Oc Ar device Add a device to an existing filesystem. .Bl -tag -width Ds .It Fl -fs_size Ns = Ns Ar size Size of filesystem on device .It Fl -bucket Ns = Ns Ar size Set bucket size .It Fl -discard Enable discards .It Fl l , Fl -label Ns = Ns Ar label Disk label .It Fl f , Fl -force Use device even if it appears to already be formatted .El .It Nm Ic device Ic remove Oo Ar options Oc Ar device Remove a device from a filesystem .Bl -tag -width Ds .It Fl f , Fl -force Force removal, even if some data couldn't be migrated .It Fl F , Fl -force-metadata Force removal, even if some metadata couldn't be migrated .El .It Nm Ic device Ic online Ar device Re-add a device to a running filesystem .It Nm Ic device Ic offline Ar device Take a device offline, without removing it .Bl -tag -width Ds .It Fl f , Fl -force Force, if data redundancy will be degraded .El .It Nm Ic device Ic evacuate Ar device Move data off of a given device .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device .Bl -tag -width Ds .It Ar new-state Ns = Ns ( Ar rw | ro | failed | spare ) .It Fl f , Fl -force Force, if data redundancy will be degraded .It Fl -force-if-data-lost Force, if data will be lost .It Fl o , Fl -offline Set state of an offline device .El .It Nm Ic device Ic resize Ar device Op Ar size Resize filesystem on a device .It Nm Ic device Ic resize-journal Ar device Op Ar size Resize journal on a device .El .Sh Commands for managing subvolumes and snapshots .Bl -tag -width Ds .It Ic subvolume create Oo Ar options Oc Ar path Create a new subvolume .It Ic subvolume delete Oo Ar options Oc Ar path Delete an existing subvolume .It Ic subvolume delete Oo Ar options Oc Ar source dest Create a snapshot of .Ar source at .Ar dest . If specified, .Ar source must be a subvolume; if not specified the snapshot will be of the subvolume containing .Ar dest . .Bl -tag -width Ds .It Fl r Make snapshot read-only .El .El .Sh Commands for managing filesystem data .Bl -tag -width Ds .It Nm Ic data Ic rereplicate Ar filesystem Walks existing data in a filesystem, writing additional copies of any degraded data. .It Nm Ic data Ic job Ar job filesystem Kick off a data job and report progress .sp .Ar job is one of ( .Cm scrub | rereplicate | migrate | rewrite_old_nodes ) .Bl -tag -width Ds .It Fl b Ar btree Btree to operate on .It Fl s Ar inode Ns Cm \&: Ns Ar offset Start position .It Fl e Ar inode Ns Cm \&: Ns Ar offset End position .El .El .Sh Commands for encryption .Bl -tag -width Ds .It Nm Ic unlock Ar device Unlock an encrypted filesystem prior to running/mounting. .Bl -tag -width Ds .It Fl c Check if a device is encrypted .It Fl k Ns = Ns ( Cm session | user | user_session ) Keyring to add to (default: .Cm user ) .El .It Nm Ic set-passphrase Ar devices\ ... Change passphrase on an existing (unmounted) filesystem. .It Nm Ic remove-passphrase Ar devices\ ... Remove passphrase on an existing (unmounted) filesystem. .El .Sh Commands for migration .Bl -tag -width Ds .It Nm Ic migrate Oo Ar options Oc Ar device Migrate an existing filesystem to bcachefs .Bl -tag -width Ds .It Fl f Ar fs Root of filesystem to migrate .It Fl -encrypted Enable whole filesystem encryption (chacha20/poly1305) .It Fl -no_passphrase Don't encrypt master encryption key .It Fl F Force, even if metadata file already exists .El .It Nm Ic migrate-superblock Oo Ar options Oc Ar device Create default superblock after migrating .Bl -tag -width Ds .It Fl d Ar device Device to create superblock for .It Fl o Ar offset Offset of existing superblock .El .El .Sh Commands for operating on files in a bcachefs filesystem .Bl -tag -width Ds .It Nm Ic setattr Oo Ar options Oc Ar devices\ ... .Bl -tag -width Ds .It Fl -data_replicas Ns = Ns Ar number Number of data replicas .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash ) Set data checksum type (default: .Cm crc32c ) . .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) Set compression type (default: .Cm none ) . .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd ) .It Fl -metadata_target Ns = Ns Ar target Device or label for metadata writes .It Fl -foreground_target Ns = Ns Ar target Device or label for foreground writes .It Fl -background_target Ns = Ns Ar target Device or label to move data to in the background .It Fl -promote_target Ns = Ns Ar target Device or label to promote data to on read .It Fl -erasure_code Enable erasure coding (DO NOT USE YET) .It Fl -project .It Fl -nocow Nocow mode: Writes will be done in place when possible. .El .El .Sh Commands for debugging These commands work on offline, unmounted filesystems. .Bl -tag -width Ds .It Nm Ic dump Oo Ar options Oc Ar device Dump filesystem metadata .Bl -tag -width Ds .It Fl o Ar output Required flag: Output qcow2 image(s) .It Fl f , Fl -force Force; overwrite when needed .It Fl -nojournal Don't dump entire journal, just dirty entries .El .It Nm Ic list Oo Ar options Oc Ar devices\ ... List filesystem metadata to stdout .Bl -tag -width Ds .It Fl b ( Cm extents | inodes | dirents | xattrs ) Btree to list from. (default: .Cm extents) .It Fl l , Fl -level Btree depth to descend to. ( .Cm 0 == leaves; default: .Cm 0) .It Fl s Ar inode Ns Cm \&: Ns Ar offset Start position to list from .It Fl e Ar inode Ns Cm \&: Ns Ar offset End position .It Fl m , Fl -mode ( Cm keys | formats | nodes | nodes-ondisk ) (default: .Cm keys) .It Fl f Check (fsck) the filesystem first .It Fl c , Fl -colorize Ns = Ns ( Cm true | false ) Force color on/off. Default: auto-detect TTY .It Fl v Verbose mode .El .It Nm Ic list_journal Oo Ar options Oc Ar devices\ ... .Bl -tag -width Ds .It Fl a Read entire journal, not just dirty entries .It Fl n , Fl -nr-entries Ns = Ns Ar nr Number of journal entries to print, starting from the most recent .It Fl t , Fl -transaction-filter Ns = Ns Ar bbpos Filter transactions not updating .Ar bbpos .It Fl k , Fl -key-filter Ns = Ns Ar btree Filter keys not updating .Ar btree .It Fl v , Fl -verbose Verbose mode .El .El .Sh FUSE commands .Bl -tag -width Ds .It Nm Ic fusemount Mount a filesystem via FUSE .El .Sh Miscellaneous commands .Bl -tag -width Ds .It Nm Ic completions Ar shell Generate shell completions .It Nm Ic version Display the version of the invoked bcachefs tool .El .Sh EXIT STATUS .Ex -std