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 Commands for managing a running filesystem
30 .Bl -tag -width 18n -compact
34 .Ss Commands for managing devices within a running filesystem
35 .Bl -tag -width 18n -compact
37 Add a new device to an existing filesystem
39 Remove a device from an existing filesystem
41 Re-add an existing member to a filesystem
43 Take a device offline, without removing it
44 .It Ic device evacuate
45 Migrate data off of a specific device
46 .It Ic device set-state
47 Mark a device as failed
49 Resize filesystem on a device
51 .Ss Commands for managing filesystem data
52 .Bl -tag -width 18n -compact
53 .It Ic data rereplicate
54 Rereplicate degraded data
56 .Ss Commands for encryption
57 .Bl -tag -width 18n -compact
59 Unlock an encrypted filesystem prior to running/mounting
61 Change passphrase on an existing (unmounted) filesystem
62 .It Ic remove-passphrase
63 Remove passphrase on an existing (unmounted) filesystem
65 .Ss Commands for migration
66 .Bl -tag -width 18n -compact
68 Migrate an existing filesystem to bcachefs, in place
69 .It Ic migrate-superblock
70 Add default superblock, after bcachefs migrate
72 .Ss Commands for debugging
73 .Bl -tag -width 18n -compact
75 Dump filesystem metadata to a qcow2 image
77 List filesystem metadata in textual form
79 .Ss Miscellaneous commands
80 .Bl -tag -width 18n -compact
82 Display the version of the invoked bcachefs tool
84 .Sh Superblock commands
86 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
87 Format one or a list of devices with bcachefs data structures.
88 You need to do this before you create a volume.
90 Device specific options must come before corresponding devices, e.g.
91 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
93 .It Fl b , Fl -block Ns = Ns Ar size
94 block size, in bytes (e.g. 4k)
95 .It Fl -btree_node Ns = Ns Ar size
96 Btree node size, default 256k
97 .It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
98 Set metadata checksum type (default:
100 .It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
101 Set data checksum type (default:
103 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
104 Set compression type (default:
106 .It Fl -data_replicas Ns = Ns Ar number
107 Number of data replicas
108 .It Fl -metadata_replicas Ns = Ns Ar number
109 Number of metadata replicas
110 .It Fl -replicas Ns = Ns Ar number
111 Sets both data and metadata replicas
113 Enable whole filesystem encryption (chacha20/poly1305);
114 passphrase will be prompted for.
115 .It Fl -no_passphrase
116 Don't encrypt master encryption key
117 .It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
118 Action to take on filesystem error (default:
120 .It Fl L , Fl -label Ns = Ns Ar label
121 Create the filesystem with the specified
123 .It Fl U , -uuid Ns = Ns Ar uuid
124 Create the filesystem with the specified
127 Force the filesystem to be created,
128 even if the device already contains a filesystem.
131 Device specific options:
133 .It Fl -fs_size Ns = Ns Ar size
134 Create the filesystem using
136 bytes on the subsequent device.
137 .It Fl -bucket Ns = Ns Ar size
138 Specifies the bucket size;
139 must be greater than the btree node size
141 Enable discards on subsequent devices
145 .It Nm Ic show-super Oo Ar options Oc Ar device
146 Dump superblock information to stdout.
148 .It Fl f , Fl -fields Ns = Ns Ar fields
149 List of sections to print
150 .It Fl l , Fl -layout
151 Print superblock layout
156 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
157 Check an existing filesystem for errors.
160 Automatic repair (no questions)
162 Don't repair, only check for errors
164 Assume "yes" to all questions
166 Force checking even if filesystem is marked clean
171 .Sh Commands for managing a running filesystem
173 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
177 Print human readable sizes.
180 .Sh Commands for managing devices within a running filesystem
182 .It Nm Ic device Ic add Oo Ar options Oc Ar device
183 Add a device to an existing filesystem.
185 .It Fl -fs_size Ns = Ns Ar size
186 Size of filesystem on device
187 .It Fl -bucket Ns = Ns Ar size
192 Use device even if it appears to already be formatted
194 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
195 Remove a device from a filesystem
198 Force removal, even if some data couldn't be migrated
199 .It Fl -force-metadata
200 Force removal, even if some metadata couldn't be migrated
202 .It Nm Ic device Ic online Ar device
203 Re-add a device to a running filesystem
204 .It Nm Ic device Ic offline Ar device
205 Take a device offline, without removing it
208 Force, if data redundancy will be degraded
210 .It Nm Ic device Ic evacuate Ar device
211 Move data off of a given device
212 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
214 .It Ar new-state Ns = Ns ( Ar rw | ro | failed | spare )
216 Force, if data redundancy will be degraded
218 .It Nm Ic device Ic resize Ar device Op Ar size
219 Resize filesystem on a device
221 .Sh Commands for managing filesystem data
223 .It Nm Ic device Ic rereplicate Ar filesystem
224 Walks existing data in a filesystem,
225 writing additional copies of any degraded data.
227 .Sh Commands for encryption
229 .It Nm Ic unlock Ar device
230 Unlock an encrypted filesystem prior to running/mounting.
231 .It Nm Ic set-passphrase Ar devices\ ...
232 Change passphrase on an existing (unmounted) filesystem.
233 .It Nm Ic remove-passphrase Ar devices\ ...
234 Remove passphrase on an existing (unmounted) filesystem.
236 .Sh Commands for migration
238 .It Nm Ic migrate Oo Ar options Oc Ar device
239 Migrate an existing filesystem to bcachefs
242 Root of filesystem to migrate
244 Enable whole filesystem encryption (chacha20/poly1305)
245 .It Fl -no_passphrase
246 Don't encrypt master encryption key
248 Force, even if metadata file already exists
250 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
251 Create default superblock after migrating
254 Device to create superblock for
256 Offset of existing superblock
259 .Sh Commands for debugging
260 These commands work on offline, unmounted filesystems.
262 .It Nm Ic dump Oo Ar options Oc Ar device
263 Dump filesystem metadata
266 Required flag: Output qcow2 image(s)
268 Force; overwrite when needed
270 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
271 List filesystem metadata to stdout
273 .It Fl b ( Cm extents | inodes | dirents | xattrs )
275 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
276 Start position to list from
277 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
280 List keys for a given inode number
281 .It Fl m ( Cm keys | formats )
289 .Sh Miscellaneous commands
292 Display the version of the invoked bcachefs tool