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 --group=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 device Ar new-state
237 Force, if data redundancy will be degraded
239 .It Nm Ic device Ic resize Ar device Op Ar size
240 Resize filesystem on a device
242 .Sh Commands for managing filesystem data
244 .It Nm Ic device Ic rereplicate Ar filesystem
245 Walks existing data in a filesystem,
246 writing additional copies of any degraded data.
248 .Sh Commands for encryption
250 .It Nm Ic unlock Ar device
251 Unlock an encrypted filesystem prior to running/mounting.
252 .It Nm Ic set-passphrase Ar devices\ ...
253 Change passphrase on an existing (unmounted) filesystem.
254 .It Nm Ic remove-passphrase Ar devices\ ...
255 Remove passphrase on an existing (unmounted) filesystem.
257 .Sh Commands for migration
259 .It Nm Ic migrate Oo Ar options Oc Ar device
260 Migrate an existing filesystem to bcachefs
263 Root of filesystem to migrate
265 Enable whole filesystem encryption (chacha20/poly1305)
266 .It Fl -no_passphrase
267 Don't encrypt master encryption key
269 Force, even if metadata file already exists
271 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
272 Create default superblock after migrating
275 Device to create superblock for
277 Offset of existing superblock
280 .Sh Commands for debugging
281 These commands work on offline, unmounted filesystems.
283 .It Nm Ic dump Oo Ar options Oc Ar device
284 Dump filesystem metadata
287 Required flag: Output qcow2 image(s)
289 Force; overwrite when needed
291 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
292 List filesystem metadata to stdout
294 .It Fl b ( Cm extents | inodes | dirents | xattrs )
296 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
297 Start position to list from
298 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
301 List keys for a given inode number
302 .It Fl m ( Cm keys | formats )
310 .Sh Miscellaneous commands
313 Display the version of the invoked bcachefs tool