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.
25 .Bl -tag -width 18n -compact
30 .Bl -tag -width 18n -compact
32 Check an existing filesystem for errors.
34 .Ss Commands for managing a running filesystem
35 .Bl -tag -width 18n -compact
39 .Ss Commands for managing devices within a running filesystem
40 .Bl -tag -width 18n -compact
42 Add a new device to an existing filesystem
44 Remove a device from an existing filesystem
46 Re-add an existing member to a filesystem
48 Take a device offline, without removing it
49 .It Ic device evacuate
50 Migrate data off of a specific device
51 .It Ic device set-state
52 Mark a device as failed
54 Resize filesystem on a device
56 .Ss Commands for managing filesystem data
57 .Bl -tag -width 18n -compact
58 .It Ic data rereplicate
59 Rereplicate degraded data
61 .Ss Commands for encryption
62 .Bl -tag -width 18n -compact
64 Unlock an encrypted filesystem prior to running/mounting
66 Change passphrase on an existing (unmounted) filesystem
67 .It Ic remove-passphrase
68 Remove passphrase on an existing (unmounted) filesystem
70 .Ss Commands for migration
71 .Bl -tag -width 18n -compact
73 Migrate an existing filesystem to bcachefs, in place
74 .It Ic migrate-superblock
75 Add default superblock, after bcachefs migrate
77 .Ss Commands for debugging
78 .Bl -tag -width 18n -compact
80 Dump filesystem metadata to a qcow2 image
82 List filesystem metadata in textual form
84 .Ss Miscellaneous commands
85 .Bl -tag -width 18n -compact
87 Display the version of the invoked bcachefs tool
89 .Sh Superblock commands
91 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
92 Format one or a list of devices with bcachefs data structures.
93 You need to do this before you create a volume.
95 Device specific options must come before corresponding devices, e.g.
96 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
98 .It Fl b , Fl -block Ns = Ns Ar size
99 block size, in bytes (e.g. 4k)
100 .It Fl -btree_node Ns = Ns Ar size
101 Btree node size, default 256k
102 .It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
103 Set metadata checksum type (default:
105 .It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
106 Set data checksum type (default:
108 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
109 Set compression type (default:
111 .It Fl -data_replicas Ns = Ns Ar number
112 Number of data replicas
113 .It Fl -metadata_replicas Ns = Ns Ar number
114 Number of metadata replicas
115 .It Fl -replicas Ns = Ns Ar number
116 Sets both data and metadata replicas
118 Enable whole filesystem encryption (chacha20/poly1305);
119 passphrase will be prompted for.
120 .It Fl -no_passphrase
121 Don't encrypt master encryption key
122 .It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
123 Action to take on filesystem error (default:
125 .It Fl L , Fl -label Ns = Ns Ar label
126 Create the filesystem with the specified
128 .It Fl U , -uuid Ns = Ns Ar uuid
129 Create the filesystem with the specified
132 Force the filesystem to be created,
133 even if the device already contains a filesystem.
136 Device specific options:
138 .It Fl -fs_size Ns = Ns Ar size
139 Create the filesystem using
141 bytes on the subsequent device.
142 .It Fl -bucket Ns = Ns Ar size
143 Specifies the bucket size;
144 must be greater than the btree node size
146 Enable discards on subsequent devices
150 .It Nm Ic show-super Oo Ar options Oc Ar device
151 Dump superblock information to stdout.
153 .It Fl f , Fl -fields Ns = Ns Ar fields
154 List of sections to print
155 .It Fl l , Fl -layout
156 Print superblock layout
161 .It Nm Ic mount Oo Ar options Oc Ar device mountpoint
162 Mount a filesystem. The
164 can be a device, a colon-separated list of devices, or UUID=<UUID>. The
166 is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted
167 but all steps preceeding mounting the filesystem (e.g. asking for passphrase) will still be performed.
168 .Pp the options are as follows:
171 Mount options provided as a comma-separated list. See userguide for complete list.
172 .Bl -tag -width Ds -compact
174 Allow mounting with data degraded
176 Extra debugging info during mount/recovery
178 Run fsck during mount
180 Fix errors without asking during fsck
182 Mount in read only mode
183 .It Cm version_upgrade
185 .It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
186 Where the password would be loaded from. (default:
188 .Bl -tag -width Ds -compact
190 don't ask for password, fail if filesystem is encrypted.
192 wait for password to become available before mounting.
194 prompt the user for password.
197 Be verbose. Can be specified more than once.
202 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
203 Check an existing filesystem for errors.
206 Automatic repair (no questions)
208 Don't repair, only check for errors
210 Assume "yes" to all questions
212 Force checking even if filesystem is marked clean
217 .Sh Commands for managing a running filesystem
219 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
223 Print human readable sizes.
226 .Sh Commands for managing devices within a running filesystem
228 .It Nm Ic device Ic add Oo Ar options Oc Ar device
229 Add a device to an existing filesystem.
231 .It Fl -fs_size Ns = Ns Ar size
232 Size of filesystem on device
233 .It Fl -bucket Ns = Ns Ar size
238 Use device even if it appears to already be formatted
240 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
241 Remove a device from a filesystem
244 Force removal, even if some data couldn't be migrated
245 .It Fl -force-metadata
246 Force removal, even if some metadata couldn't be migrated
248 .It Nm Ic device Ic online Ar device
249 Re-add a device to a running filesystem
250 .It Nm Ic device Ic offline Ar device
251 Take a device offline, without removing it
254 Force, if data redundancy will be degraded
256 .It Nm Ic device Ic evacuate Ar device
257 Move data off of a given device
258 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
260 .It Ar new-state Ns = Ns ( Ar rw | ro | failed | spare )
262 Force, if data redundancy will be degraded
264 .It Nm Ic device Ic resize Ar device Op Ar size
265 Resize filesystem on a device
267 .Sh Commands for managing filesystem data
269 .It Nm Ic device Ic rereplicate Ar filesystem
270 Walks existing data in a filesystem,
271 writing additional copies of any degraded data.
273 .Sh Commands for encryption
275 .It Nm Ic unlock Ar device
276 Unlock an encrypted filesystem prior to running/mounting.
277 .It Nm Ic set-passphrase Ar devices\ ...
278 Change passphrase on an existing (unmounted) filesystem.
279 .It Nm Ic remove-passphrase Ar devices\ ...
280 Remove passphrase on an existing (unmounted) filesystem.
282 .Sh Commands for migration
284 .It Nm Ic migrate Oo Ar options Oc Ar device
285 Migrate an existing filesystem to bcachefs
288 Root of filesystem to migrate
290 Enable whole filesystem encryption (chacha20/poly1305)
291 .It Fl -no_passphrase
292 Don't encrypt master encryption key
294 Force, even if metadata file already exists
296 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
297 Create default superblock after migrating
300 Device to create superblock for
302 Offset of existing superblock
305 .Sh Commands for debugging
306 These commands work on offline, unmounted filesystems.
308 .It Nm Ic dump Oo Ar options Oc Ar device
309 Dump filesystem metadata
312 Required flag: Output qcow2 image(s)
314 Force; overwrite when needed
316 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
317 List filesystem metadata to stdout
319 .It Fl b ( Cm extents | inodes | dirents | xattrs )
321 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
322 Start position to list from
323 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
326 List keys for a given inode number
327 .It Fl m ( Cm keys | formats )
335 .Sh Miscellaneous commands
338 Display the version of the invoked bcachefs tool