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 --tier 0 /dev/sdb --tier 1 /dev/sdc
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_type Ns = Ns ( Cm none | lz4 | gzip )
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
153 .It Fl t , Fl -tier Ar index
154 Specifies the tier of subsequent devices, where
156 is a small integer and a smaller index indicates a faster tier; tier 0
158 Currently only two tiers are supported.
162 .It Nm Ic show-super Oo Ar options Oc Ar device
163 Dump superblock information to stdout.
165 .It Fl f , Fl -fields Ns = Ns Ar fields
166 List of sections to print
167 .It Fl l , Fl -layout
168 Print superblock layout
173 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
174 Check an existing filesystem for errors.
177 Automatic repair (no questions)
179 Don't repair, only check for errors
181 Assume "yes" to all questions
183 Force checking even if filesystem is marked clean
188 .Sh Startup/shutdown, assembly of multi device filesystems
190 .It Nm Ic assemble Ar devices\ ...
191 Assemble an existing multi device filesystem.
192 .It Nm Ic incremental Ar device
193 Incrementally assemble an existing multi device filesystem.
195 Start a partially assembled filesystem.
196 .It Nm Ic stop Ar filesystem
197 Stop a running filesystem.
199 .Sh Commands for managing a running filesystem
201 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
205 Print human readable sizes.
208 .Sh Commands for managing devices within a running filesystem
210 .It Nm Ic device Ic add Oo Ar options Oc Ar device
211 Add a device to an existing filesystem.
213 .It Fl -fs_size Ns = Ns Ar size
214 Size of filesystem on device
215 .It Fl -bucket Ns = Ns Ar size
219 .It Fl t , Fl -tier Ns = Ns Ar number
220 Higher tier (e.g. 1) indicates slower devices
222 Use device even if it appears to already be formatted
224 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
225 Remove a device from a filesystem
228 Force removal, even if some data couldn't be migrated
229 .It Fl -force-metadata
230 Force removal, even if some metadata couldn't be migrated
232 .It Nm Ic device Ic online Ar device
233 Re-add a device to a running filesystem
234 .It Nm Ic device Ic offline Ar device
235 Take a device offline, without removing it
238 Force, if data redundancy will be degraded
240 .It Nm Ic device Ic evacuate Ar device
241 Move data off of a given device
242 .It Nm Ic device Ic set-state Oo Ar options Oc Ar device Ar new-state
245 Force, if data redundancy will be degraded
247 .It Nm Ic device Ic resize Ar device Op Ar size
248 Resize filesystem on a device
250 .Sh Commands for managing filesystem data
252 .It Nm Ic device Ic rereplicate Ar filesystem
253 Walks existing data in a filesystem,
254 writing additional copies of any degraded data.
256 .Sh Commands for encryption
258 .It Nm Ic unlock Ar device
259 Unlock an encrypted filesystem prior to running/mounting.
260 .It Nm Ic set-passphrase Ar devices\ ...
261 Change passphrase on an existing (unmounted) filesystem.
262 .It Nm Ic remove-passphrase Ar devices\ ...
263 Remove passphrase on an existing (unmounted) filesystem.
265 .Sh Commands for migration
267 .It Nm Ic migrate Oo Ar options Oc Ar device
268 Migrate an existing filesystem to bcachefs
271 Root of filesystem to migrate
273 Enable whole filesystem encryption (chacha20/poly1305)
274 .It Fl -no_passphrase
275 Don't encrypt master encryption key
277 Force, even if metadata file already exists
279 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
280 Create default superblock after migrating
283 Device to create superblock for
285 Offset of existing superblock
288 .Sh Commands for debugging
289 These commands work on offline, unmounted filesystems.
291 .It Nm Ic dump Oo Ar options Oc Ar device
292 Dump filesystem metadata
295 Required flag: Output qcow2 image(s)
297 Force; overwrite when needed
299 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
300 List filesystem metadata to stdout
302 .It Fl b ( Cm extents | inodes | dirents | xattrs )
304 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
305 Start position to list from
306 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
309 List keys for a given inode number
310 .It Fl m ( Cm keys | formats )
318 .Sh Miscellaneous commands
321 Display the version of the invoked bcachefs tool