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
27 Check an existing filesystem for errors.
29 .Ss Startup/shutdown, assembly of multi device filesystems
30 .Bl -tag -width 18n -compact
32 Assemble an existing multi device filesystem
34 Incrementally assemble an existing multi device filesystem
36 Start a partially assembled filesystem.
38 Stop a running filesystem.
40 .Ss Commands for managing a running filesystem
41 .Bl -tag -width 18n -compact
45 .Ss Commands for managing devices within a running filesystem
46 .Bl -tag -width 18n -compact
48 Add a new device to an existing filesystem
50 Remove a device from an existing filesystem
52 Re-add an existing member to a filesystem
54 Take a device offline, without removing it
55 .It Ic device evacuate
56 Migrate data off of a specific device
57 .It Ic device set-state
58 Mark a device as failed
60 Resize filesystem on a device
62 .Ss Commands for managing filesystem data
63 .Bl -tag -width 18n -compact
64 .It Ic data rereplicate
65 Rereplicate degraded data
67 .Ss Commands for encryption
68 .Bl -tag -width 18n -compact
70 Unlock an encrypted filesystem prior to running/mounting
72 Change passphrase on an existing (unmounted) filesystem
73 .It Ic remove-passphrase
74 Remove passphrase on an existing (unmounted) filesystem
76 .Ss Commands for migration
77 .Bl -tag -width 18n -compact
79 Migrate an existing filesystem to bcachefs, in place
80 .It Ic migrate-superblock
81 Add default superblock, after bcachefs migrate
83 .Ss Commands for debugging
84 .Bl -tag -width 18n -compact
86 Dump filesystem metadata to a qcow2 image
88 List filesystem metadata in textual form
90 .Ss Miscellaneous commands
91 .Bl -tag -width 18n -compact
93 Display the version of the invoked bcachefs tool
95 .Sh Superblock commands
97 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
98 Format one or a list of devices with bcachefs data structures.
99 You need to do this before you create a volume.
101 Device specific options must come before corresponding devices, e.g.
102 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
104 .It Fl b , Fl -block Ns = Ns Ar size
105 block size, in bytes (e.g. 4k)
106 .It Fl -btree_node Ns = Ns Ar size
107 Btree node size, default 256k
108 .It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
109 Set metadata checksum type (default:
111 .It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
112 Set data checksum type (default:
114 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
115 Set compression type (default:
117 .It Fl -data_replicas Ns = Ns Ar number
118 Number of data replicas
119 .It Fl -metadata_replicas Ns = Ns Ar number
120 Number of metadata replicas
121 .It Fl -replicas Ns = Ns Ar number
122 Sets both data and metadata replicas
124 Enable whole filesystem encryption (chacha20/poly1305);
125 passphrase will be prompted for.
126 .It Fl -no_passphrase
127 Don't encrypt master encryption key
128 .It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
129 Action to take on filesystem error (default:
131 .It Fl L , Fl -label Ns = Ns Ar label
132 Create the filesystem with the specified
134 .It Fl U , -uuid Ns = Ns Ar uuid
135 Create the filesystem with the specified
138 Force the filesystem to be created,
139 even if the device already contains a filesystem.
142 Device specific options:
144 .It Fl -fs_size Ns = Ns Ar size
145 Create the filesystem using
147 bytes on the subsequent device.
148 .It Fl -bucket Ns = Ns Ar size
149 Specifies the bucket size;
150 must be greater than the btree node size
152 Enable discards on subsequent devices
156 .It Nm Ic show-super Oo Ar options Oc Ar device
157 Dump superblock information to stdout.
159 .It Fl f , Fl -fields Ns = Ns Ar fields
160 List of sections to print
161 .It Fl l , Fl -layout
162 Print superblock layout
167 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
168 Check an existing filesystem for errors.
171 Automatic repair (no questions)
173 Don't repair, only check for errors
175 Assume "yes" to all questions
177 Force checking even if filesystem is marked clean
182 .Sh Startup/shutdown, assembly of multi device filesystems
184 .It Nm Ic assemble Ar devices\ ...
185 Assemble an existing multi device filesystem.
186 .It Nm Ic incremental Ar device
187 Incrementally assemble an existing multi device filesystem.
189 Start a partially assembled filesystem.
190 .It Nm Ic stop Ar filesystem
191 Stop a running filesystem.
193 .Sh Commands for managing a running filesystem
195 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
199 Print human readable sizes.
202 .Sh Commands for managing devices within a running filesystem
204 .It Nm Ic device Ic add Oo Ar options Oc Ar device
205 Add a device to an existing filesystem.
207 .It Fl -fs_size Ns = Ns Ar size
208 Size of filesystem on device
209 .It Fl -bucket Ns = Ns Ar size
214 Use device even if it appears to already be formatted
216 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
217 Remove a device from a filesystem
220 Force removal, even if some data couldn't be migrated
221 .It Fl -force-metadata
222 Force removal, even if some metadata couldn't be migrated
224 .It Nm Ic device Ic online Ar device
225 Re-add a device to a running filesystem
226 .It Nm Ic device Ic offline Ar device
227 Take a device offline, without removing it
230 Force, if data redundancy will be degraded
232 .It Nm Ic device Ic evacuate Ar device
233 Move data off of a given device
234 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
236 .It Ar new-state Ns = Ns ( Ar rw | ro | failed | spare )
238 Force, if data redundancy will be degraded
240 .It Nm Ic device Ic resize Ar device Op Ar size
241 Resize filesystem on a device
243 .Sh Commands for managing filesystem data
245 .It Nm Ic device Ic rereplicate Ar filesystem
246 Walks existing data in a filesystem,
247 writing additional copies of any degraded data.
249 .Sh Commands for encryption
251 .It Nm Ic unlock Ar device
252 Unlock an encrypted filesystem prior to running/mounting.
253 .It Nm Ic set-passphrase Ar devices\ ...
254 Change passphrase on an existing (unmounted) filesystem.
255 .It Nm Ic remove-passphrase Ar devices\ ...
256 Remove passphrase on an existing (unmounted) filesystem.
258 .Sh Commands for migration
260 .It Nm Ic migrate Oo Ar options Oc Ar device
261 Migrate an existing filesystem to bcachefs
264 Root of filesystem to migrate
266 Enable whole filesystem encryption (chacha20/poly1305)
267 .It Fl -no_passphrase
268 Don't encrypt master encryption key
270 Force, even if metadata file already exists
272 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
273 Create default superblock after migrating
276 Device to create superblock for
278 Offset of existing superblock
281 .Sh Commands for debugging
282 These commands work on offline, unmounted filesystems.
284 .It Nm Ic dump Oo Ar options Oc Ar device
285 Dump filesystem metadata
288 Required flag: Output qcow2 image(s)
290 Force; overwrite when needed
292 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
293 List filesystem metadata to stdout
295 .It Fl b ( Cm extents | inodes | dirents | xattrs )
297 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
298 Start position to list from
299 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
302 List keys for a given inode number
303 .It Fl m ( Cm keys | formats )
311 .Sh Miscellaneous commands
314 Display the version of the invoked bcachefs tool