6 .Nd manage bcachefs filesystems/devices
15 utility supports the following subcommands,
16 which are documented in detail below:
17 .Ss Superblock commands
18 .Bl -tag -width 18n -compact
20 Format one or a list of devices with bcachefs data structures.
22 Dump superblock information to stdout.
24 Set a filesystem option
27 .Bl -tag -width 18n -compact
32 .Bl -tag -width 18n -compact
34 Check an existing filesystem for errors.
36 .Ss Commands for managing a running filesystem
37 .Bl -tag -width 18n -compact
41 .Ss Commands for managing devices within a running filesystem
42 .Bl -tag -width 22n -compact
44 Add a new device to an existing filesystem
46 Remove a device from an existing filesystem
48 Re-add an existing member to a filesystem
50 Take a device offline, without removing it
51 .It Ic device evacuate
52 Migrate data off of a specific device
53 .It Ic device set-state
54 Mark a device as failed
56 Resize filesystem on a device
57 .It Ic device resize-journal
58 Resize journal on a device
60 .Ss Commands for managing subvolumes and snapshots
61 .Bl -tag -width 18n -compact
62 .It Ic subvolume create
63 Create a new subvolume
64 .It Ic subvolume delete
65 Delete an existing subvolume
66 .It Ic subvolume snapshot
69 .Ss Commands for managing filesystem data
70 .Bl -tag -width 18n -compact
71 .It Ic data rereplicate
72 Rereplicate degraded data
74 Kick off low level data jobs
76 .Ss Commands for encryption
77 .Bl -tag -width 18n -compact
79 Unlock an encrypted filesystem prior to running/mounting
81 Change passphrase on an existing (unmounted) filesystem
82 .It Ic remove-passphrase
83 Remove passphrase on an existing (unmounted) filesystem
85 .Ss Commands for migration
86 .Bl -tag -width 18n -compact
88 Migrate an existing filesystem to bcachefs, in place
89 .It Ic migrate-superblock
90 Add default superblock, after bcachefs migrate
92 .Ss Commands for operating on files in a bcachefs filesystem
93 .Bl -tag -width 18n -compact
95 Set various per file attributes
97 .Ss Commands for debugging
98 .Bl -tag -width 18n -compact
100 Dump filesystem metadata to a qcow2 image
102 List filesystem metadata in textual form
104 List contents of journal
107 .Bl -tag -width 18n -compact
108 .It Ic fusemount Mount a filesystem via FUSE
110 .Ss Miscellaneous commands
111 .Bl -tag -width 18n -compact
113 Display the version of the invoked bcachefs tool
115 Generate shell completions
117 .Sh Superblock commands
119 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
120 Format one or a list of devices with bcachefs data structures.
121 You need to do this before you create a volume.
123 Device specific options must come before corresponding devices, e.g.
124 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
126 .It Fl -block_size Ns = Ns Ar size
127 block size, in bytes (e.g. 4k)
128 .It Fl -btree_node_size Ns = Ns Ar size
129 Btree node size, default 256k
130 .It Fl -errors Ns = Ns ( Cm continue | ro | panic )
131 Action to take on filesystem error
132 .It Fl -data_replicas Ns = Ns Ar number
133 Number of data replicas
134 .It Fl -metadata_replicas Ns = Ns Ar number
135 Number of metadata replicas
136 .It Fl -data_replicas_required Ns = Ns Ar number
138 .It Fl -metadata_replicas_required Ns = Ns Ar number
140 .It Fl -encoded_extent_max Ns = Ns Ar size
141 Maximum size of checksummed/compressed extents
142 .It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
143 Set metadata checksum type (default:
145 .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
146 Set data checksum type (default:
148 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
149 Set compression type (default:
151 .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
153 .It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash )
154 Hash function for directory entries and xattrs
155 .It Fl -metadata_target Ns = Ns Ar target
156 Device or label for metadata writes
157 .It Fl -foreground_target Ns = Ns Ar target
158 Device or label for foreground writes
159 .It Fl -background_target Ns = Ns Ar target
160 Device or label to move data to in the background
161 .It Fl -promote_target Ns = Ns Ar target
162 Device or label to promote data to on read
164 Enable erasure coding (DO NOT USE YET)
166 Constrain inode numbers to 32 bits
167 .It Fl -shared_inode_numbers
168 Shared new inode numbers by CPU id
169 .It Fl -inodes_use_key_cache
170 Use the btree key cache for the inodes btree
171 .It Fl -gc_reserve_percent Ns = Ns Ar percentage
172 Percentage of disk space to reserve for copygc
173 .It Fl -gc_reserve_bytes Ns = Ns Ar percentage
174 Amount of disk space to reserve for copygc
176 This takes precedence over
177 .Cm gc_reserve_percent
179 .It Fl -root_reserve_percent Ns = Ns Ar percentage
180 Percentage of disk space to reserve for superuser
182 Store full 128bits of cryptographic MACS, instead of 80
190 Enable project quotas
191 .It Fl -journal_transaction_names
192 Log transaction function names in journal
194 Nocow mode: Writes will be done in place when possible.
196 Snapshots and reflink will still caused writes to be COW.
198 This flag implicitly disables data checksumming, compression and
200 .It Fl -replicas Ns = Ns Ar number
201 Sets both data and metadata replicas
203 Enable whole filesystem encryption (chacha20/poly1305);
204 passphrase will be prompted for.
205 .It Fl -no_passphrase
206 Don't encrypt master encryption key
207 .It Fl L , Fl -fs_label Ns = Ns Ar label
208 Create the filesystem with the specified
210 .It Fl U , -uuid Ns = Ns Ar uuid
211 Create the filesystem with the specified
213 .It Fl -superblock_size Ns = Ns Ar size
217 Device specific options:
220 Enable discard/TRIM support
221 .It Fl -fs_size Ns = Ns Ar size
222 Create the filesystem using
224 bytes on the subsequent device.
225 .It Fl -bucket Ns = Ns Ar size
226 Specifies the bucket size;
227 must be greater than the btree node size
228 .It Fl -durability Ns = Ns Ar n
229 Data written to this device will be considered
230 to have already been replicated
236 Force the filesystem to be created,
237 even if the device already contains a filesystem.
240 .It Fl v , Fl -verbose
241 Verbose filesystem initialization
243 .It Nm Ic show-super Oo Ar options Oc Ar device
244 Dump superblock information to stdout.
246 .It Fl f , Fl -fields Ns = Ns Ar fields
247 List of sections to print
248 .It Fl l , Fl -layout
249 Print superblock layout
251 .It Nm Ic set-option Oo Ar options Oc Ar device
253 .It Fl -errors Ns = Ns ( Cm continue | ro | panic )
254 Action to take on filesystem error
255 .It Fl -metadata_replicas Ns = Ns Ar number
256 Number of metadata replicas
257 .It Fl -data_replicas Ns = Ns Ar number
258 Number of data replicas
259 .It Fl -metadata_replicas_required Ns = Ns Ar number
261 .It Fl -data_replicas_required Ns = Ns Ar number
263 .It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
264 Set metadata checksum type (default:
266 .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
267 Set data checksum type (default:
269 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
270 Set compression type (default:
272 .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
274 .It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash )
275 Hash function for directory entries and xattrs
276 .It Fl -metadata_target Ns = Ns Ar target
277 Device or label for metadata writes
278 .It Fl -foreground_target Ns = Ns Ar target
279 Device or label for foreground writes
280 .It Fl -background_target Ns = Ns Ar target
281 Device or label to move data to in the background
282 .It Fl -promote_target Ns = Ns Ar target
283 Device or label to promote data to on read
285 Enable erasure coding (DO NOT USE YET)
287 Constrain inode numbers to 32 bits
288 .It Fl -shared_inode_numbers
289 Shared new inode numbers by CPU id
290 .It Fl -inodes_use_key_cache
291 Use the btree key cache for the inodes btree
292 .It Fl -gc_reserve_percent Ns = Ns Ar percentage
293 Percentage of disk space to reserve for copygc
294 .It Fl -gc_reserve_bytes Ns = Ns Ar percentage
295 Amount of disk space to reserve for copygc
297 This takes precedence over
298 .Cm gc_reserve_percent
300 .It Fl -root_reserve_percent Ns = Ns Ar percentage
301 Percentage of disk space to reserve for superuser
303 Store full 128bits of cryptographic MACS, instead of 80
311 Enable project quotas
313 Allow mounting in degraded mode
314 .It Fl -very_degraded
315 Allow mounting in when data will be missing
317 Enable discard/TRIM support
319 Extra debugging information during mount/recovery
320 .It Fl -journal_flush_delay Ns = Ns Ar ms
321 Delay in milliseconds before automatic journal commits
322 .It Fl -journal_flush_disabled
323 Disable journal flush on sync/fsync
325 If enabled, writes can be lost, but only since the
326 last journal write (default 1 second)
327 .It Fl -journal_reclaim_delay Ns = Ns Ar ms
328 Delay in milliseconds before automatic journal reclaim
329 .It Fl -move_bytes_in_flight Ns = Ns Ar bytes
330 Maximum Amount of IO to keep in flight by the move path
331 .It Fl -move_ios_in_flight Ns = Ns Ar number
332 Maximum number of IOs to keep in flight by the move path
335 .It Fl -fix_errors Ns = Ns Ar error
336 Fix errors during fsck without asking
337 .It Fl -ratelimit_errors
338 Ratelimit error messages during fsck
340 Super read only mode - no writes at all will be issued,
341 even if we have to replay the journal
343 Don't replay the journal
344 .It Fl -journal_transaction_names
345 Log transaction function names in journal
347 Don't open device in exclusive mode
349 Use O_DIRECT (userspace only)
350 .It Fl -sb Ns = Ns Ar offset
351 Sector offset of superblock
352 .It Fl -reconstruct_alloc
353 Reconstruct alloc btree
354 .It Fl -version_upgrade Ns = Ns ( Cm compatible | incompatible | none )
355 Set superblock to latest version, allowing any new features
358 Nocow mode: Writes will be done in place when possible.
360 Snapshots and reflink will still caused writes to be COW.
362 This flag implicitly disables data checksumming, compression and
364 .It Fl -nocow_enabled
365 Enable nocow mode: enables runtime locking in data
366 move path needed if nocow will ever be in use
368 Skip submit_bio() for data reads and writes,
369 for performance testing purposes
374 .It Nm Ic mount Oo Ar options Oc Ar device mountpoint
375 Mount a filesystem. The
377 can be a device, a colon-separated list of devices, or UUID=<UUID>. The
379 is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted
380 but all steps preceding mounting the filesystem (e.g. asking for passphrase) will still be performed.
381 .Pp the options are as follows:
384 Mount options provided as a comma-separated list. See user guide for complete list.
385 .Bl -tag -width Ds -compact
387 Allow mounting with data degraded
389 Extra debugging info during mount/recovery
391 Run fsck during mount
393 Fix errors without asking during fsck
395 Mount in read only mode
396 .It Cm version_upgrade
398 .It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
399 Where the password would be loaded from. (default:
401 .Bl -tag -width Ds -compact
403 don't ask for password, fail if filesystem is encrypted.
405 wait for password to become available before mounting.
407 prompt the user for password.
409 .It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
410 Force color on/off. Default: auto-detect TTY
412 Be verbose. Can be specified more than once.
417 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
418 Check an existing filesystem for errors.
421 Automatic repair (no questions)
423 Don't repair, only check for errors
425 Assume "yes" to all questions
427 Force checking even if filesystem is marked clean
428 .It Fl r , Fl -ratelimit_errors
429 Don't display more than 10 errors of a given type
430 .It Fl R , Fl -reconstruct_alloc
431 Reconstruct the alloc btree
436 .Sh Commands for managing a running filesystem
438 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
441 .It Fl h , Fl -human-readable
442 Print human readable sizes.
445 .Sh Commands for managing devices within a running filesystem
447 .It Nm Ic device Ic add Oo Ar options Oc Ar device
448 Add a device to an existing filesystem.
450 .It Fl -fs_size Ns = Ns Ar size
451 Size of filesystem on device
452 .It Fl -bucket Ns = Ns Ar size
456 .It Fl l , Fl -label Ns = Ns Ar label
459 Use device even if it appears to already be formatted
461 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
462 Remove a device from a filesystem
465 Force removal, even if some data couldn't be migrated
466 .It Fl F , Fl -force-metadata
467 Force removal, even if some metadata couldn't be migrated
469 .It Nm Ic device Ic online Ar device
470 Re-add a device to a running filesystem
471 .It Nm Ic device Ic offline Ar device
472 Take a device offline, without removing it
475 Force, if data redundancy will be degraded
477 .It Nm Ic device Ic evacuate Ar device
478 Move data off of a given device
479 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
481 .It Ar new-state Ns = Ns ( Ar rw | ro | failed | spare )
483 Force, if data redundancy will be degraded
484 .It Fl -force-if-data-lost
485 Force, if data will be lost
486 .It Fl o , Fl -offline
487 Set state of an offline device
489 .It Nm Ic device Ic resize Ar device Op Ar size
490 Resize filesystem on a device
491 .It Nm Ic device Ic resize-journal Ar device Op Ar size
492 Resize journal on a device
494 .Sh Commands for managing subvolumes and snapshots
496 .It Ic subvolume create Oo Ar options Oc Ar path
497 Create a new subvolume
498 .It Ic subvolume delete Oo Ar options Oc Ar path
499 Delete an existing subvolume
500 .It Ic subvolume delete Oo Ar options Oc Ar source dest
508 if not specified the snapshot will be of the subvolume containing
512 Make snapshot read-only
515 .Sh Commands for managing filesystem data
517 .It Nm Ic data Ic rereplicate Ar filesystem
518 Walks existing data in a filesystem,
519 writing additional copies of any degraded data.
520 .It Nm Ic data Ic job Ar job filesystem
521 Kick off a data job and report progress
525 .Cm scrub | rereplicate | migrate | rewrite_old_nodes
530 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
532 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
536 .Sh Commands for encryption
538 .It Nm Ic unlock Ar device
539 Unlock an encrypted filesystem prior to running/mounting.
542 Check if a device is encrypted
543 .It Fl k Ns = Ns ( Cm session | user | user_session )
544 Keyring to add to (default:
547 .It Nm Ic set-passphrase Ar devices\ ...
548 Change passphrase on an existing (unmounted) filesystem.
549 .It Nm Ic remove-passphrase Ar devices\ ...
550 Remove passphrase on an existing (unmounted) filesystem.
552 .Sh Commands for migration
554 .It Nm Ic migrate Oo Ar options Oc Ar device
555 Migrate an existing filesystem to bcachefs
558 Root of filesystem to migrate
560 Enable whole filesystem encryption (chacha20/poly1305)
561 .It Fl -no_passphrase
562 Don't encrypt master encryption key
564 Force, even if metadata file already exists
566 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
567 Create default superblock after migrating
570 Device to create superblock for
572 Offset of existing superblock
575 .Sh Commands for operating on files in a bcachefs filesystem
577 .It Nm Ic setattr Oo Ar options Oc Ar devices\ ...
579 .It Fl -data_replicas Ns = Ns Ar number
580 Number of data replicas
581 .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
582 Set data checksum type (default:
584 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
585 Set compression type (default:
587 .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
589 .It Fl -metadata_target Ns = Ns Ar target
590 Device or label for metadata writes
591 .It Fl -foreground_target Ns = Ns Ar target
592 Device or label for foreground writes
593 .It Fl -background_target Ns = Ns Ar target
594 Device or label to move data to in the background
595 .It Fl -promote_target Ns = Ns Ar target
596 Device or label to promote data to on read
598 Enable erasure coding (DO NOT USE YET)
602 Nocow mode: Writes will be done in place when possible.
605 .Sh Commands for debugging
606 These commands work on offline, unmounted filesystems.
608 .It Nm Ic dump Oo Ar options Oc Ar device
609 Dump filesystem metadata
612 Required flag: Output qcow2 image(s)
614 Force; overwrite when needed
616 Don't dump entire journal, just dirty entries
618 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
619 List filesystem metadata to stdout
621 .It Fl b ( Cm extents | inodes | dirents | xattrs )
622 Btree to list from. (default:
625 Btree depth to descend to. (
629 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
630 Start position to list from
631 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
633 .It Fl m , Fl -mode ( Cm keys | formats | nodes | nodes-ondisk )
637 Check (fsck) the filesystem first
638 .It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
639 Force color on/off. Default: auto-detect TTY
643 .It Nm Ic list_journal Oo Ar options Oc Ar devices\ ...
646 Read entire journal, not just dirty entries
647 .It Fl n , Fl -nr-entries Ns = Ns Ar nr
648 Number of journal entries to print, starting from the most recent
649 .It Fl t , Fl -transaction-filter Ns = Ns Ar bbpos
650 Filter transactions not updating
652 .It Fl k , Fl -key-filter Ns = Ns Ar btree
653 Filter keys not updating
655 .It Fl v , Fl -verbose
662 Mount a filesystem via FUSE
664 .Sh Miscellaneous commands
666 .It Nm Ic completions Ar shell
667 Generate shell completions
669 Display the version of the invoked bcachefs tool