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 .Sh Superblock commands
92 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
93 Format one or a list of devices with bcachefs data structures.
94 You need to do this before you create a volume.
96 Device specific options must come before corresponding devices, e.g.
97 .Dl bcachefs format --tier 0 /dev/sdb --tier 1 /dev/sdc
99 .It Fl b , Fl -block Ns = Ns Ar size
100 block size, in bytes (e.g. 4k)
101 .It Fl -btree_node Ns = Ns Ar size
102 Btree node size, default 256k
103 .It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
104 Set metadata checksum type (default:
106 .It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
107 Set data checksum type (default:
109 .It Fl -compression_type Ns = Ns ( Cm none | lz4 | gzip )
110 Set compression type (default:
112 .It Fl -data_replicas Ns = Ns Ar number
113 Number of data replicas
114 .It Fl -metadata_replicas Ns = Ns Ar number
115 Number of metadata replicas
116 .It Fl -replicas Ns = Ns Ar number
117 Sets both data and metadata replicas
119 Enable whole filesystem encryption (chacha20/poly1305);
120 passphrase will be prompted for.
121 .It Fl -no_passphrase
122 Don't encrypt master encryption key
123 .It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
124 Action to take on filesystem error (default:
126 .It Fl L , Fl -label Ns = Ns Ar label
127 Create the filesystem with the specified
129 .It Fl U , -uuid Ns = Ns Ar uuid
130 Create the filesystem with the specified
133 Force the filesystem to be created,
134 even if the device already contains a filesystem.
137 Device specific options:
139 .It Fl -fs_size Ns = Ns Ar size
140 Create the filesystem using
142 bytes on the subsequent device.
143 .It Fl -bucket Ns = Ns Ar size
144 Specifies the bucket size;
145 must be greater than the btree node size
147 Enable discards on subsequent devices
148 .It Fl t , Fl -tier Ar index
149 Specifies the tier of subsequent devices, where
151 is a small integer and a smaller index indicates a faster tier; tier 0
153 Currently only two tiers are supported.
157 .It Nm Ic show-super Oo Ar options Oc Ar device
158 Dump superblock information to stdout.
160 .It Fl f , Fl -fields Ns = Ns Ar fields
161 List of sections to print
162 .It Fl l , Fl -layout
163 Print superblock layout
168 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
169 Check an existing filesystem for errors.
172 Automatic repair (no questions)
174 Don't repair, only check for errors
176 Assume "yes" to all questions
178 Force checking even if filesystem is marked clean
183 .Sh Startup/shutdown, assembly of multi device filesystems
185 .It Nm Ic assemble Ar devices\ ...
186 Assemble an existing multi device filesystem.
187 .It Nm Ic incremental Ar device
188 Incrementally assemble an existing multi device filesystem.
190 Start a partially assembled filesystem.
191 .It Nm Ic stop Ar filesystem
192 Stop a running filesystem.
194 .Sh Commands for managing a running filesystem
196 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
200 Print human readable sizes.
203 .Sh Commands for managing devices within a running filesystem
205 .It Nm Ic device Ic add Oo Ar options Oc Ar device
206 Add a device to an existing filesystem.
208 .It Fl -fs_size Ns = Ns Ar size
209 Size of filesystem on device
210 .It Fl -bucket Ns = Ns Ar size
214 .It Fl t , Fl -tier Ns = Ns Ar number
215 Higher tier (e.g. 1) indicates slower devices
217 Use device even if it appears to already be formatted
219 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
220 Remove a device from a filesystem
223 Force removal, even if some data couldn't be migrated
224 .It Fl -force-metadata
225 Force removal, even if some metadata couldn't be migrated
227 .It Nm Ic device Ic online Ar device
228 Re-add a device to a running filesystem
229 .It Nm Ic device Ic offline Ar device
230 Take a device offline, without removing it
233 Force, if data redundancy will be degraded
235 .It Nm Ic device Ic evacuate Ar device
236 Move data off of a given device
237 .It Nm Ic device Ic set-state Oo Ar options Oc Ar device Ar new-state
240 Force, if data redundancy will be degraded
242 .It Nm Ic device Ic resize Ar device Op Ar size
243 Resize filesystem on a device
245 .Sh Commands for managing filesystem data
247 .It Nm Ic device Ic rereplicate Ar filesystem
248 Walks existing data in a filesystem,
249 writing additional copies of any degraded data.
251 .Sh Commands for encryption
253 .It Nm Ic unlock Ar device
254 Unlock an encrypted filesystem prior to running/mounting.
255 .It Nm Ic set-passphrase Ar devices\ ...
256 Change passphrase on an existing (unmounted) filesystem.
257 .It Nm Ic remove-passphrase Ar devices\ ...
258 Remove passphrase on an existing (unmounted) filesystem.
260 .Sh Commands for migration
262 .It Nm Ic migrate Oo Ar options Oc Ar device
263 Migrate an existing filesystem to bcachefs
266 Root of filesystem to migrate
268 Enable whole filesystem encryption (chacha20/poly1305)
269 .It Fl -no_passphrase
270 Don't encrypt master encryption key
272 Force, even if metadata file already exists
274 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
275 Create default superblock after migrating
278 Device to create superblock for
280 Offset of existing superblock
283 .Sh Commands for debugging
284 These commands work on offline, unmounted filesystems.
286 .It Nm Ic dump Oo Ar options Oc Ar device
287 Dump filesystem metadata
290 Required flag: Output qcow2 image(s)
292 Force; overwrite when needed
294 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
295 List filesystem metadata to stdout
297 .It Fl b ( Cm extents | inodes | dirents | xattrs )
299 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
300 Start position to list from
301 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
304 List keys for a given inode number
305 .It Fl m ( Cm keys | formats )