Debian Codegraph @

upstream/debian-unstable/man8/btrfs-device.8

raw
1 .\" Man page generated from reStructuredText
2 .\" by the Docutils 0.22.4 manpage writer.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "BTRFS-DEVICE" "8" "May 10, 2026" "7.0" "BTRFS"
32 .SH NAME
33 btrfs-device \- manage devices of btrfs filesystems
34 .SH SYNOPSIS
35 .sp
36 \fBbtrfs device\fP <subcommand> <args>
37 .SH DESCRIPTION
38 .sp
39 The \fBbtrfs device\fP command group is used to manage devices of the btrfs filesystems.
40 .SH DEVICE MANAGEMENT
41 .sp
42 BTRFS filesystem can be created on top of single or multiple block devices.
43 Devices can be then added, removed or replaced on demand. Data and metadata are
44 organized in allocation profiles with various redundancy policies. There\(aqs some
45 similarity with traditional RAID levels, but this could be confusing to users
46 familiar with the traditional meaning. Due to the similarity, the RAID
47 terminology is widely used in the documentation. See mkfs.btrfs(8) \%<> for more
48 details and the exact profile capabilities and constraints.
49 .sp
50 The device management works on a mounted filesystem. Devices can be added,
51 removed or replaced, by commands provided by \fBbtrfs device\fP and \fBbtrfs replace\fP\&.
52 .sp
53 The profiles can be also changed, provided there\(aqs enough workspace to do the
54 conversion, using the \fBbtrfs balance\fP command and namely the filter \fIconvert\fP\&.
55 .INDENT 0.0
56 .TP
57 .B Type
58 The block group profile type is the main distinction of the information stored
59 on the block device. User data are called \fIData\fP, the internal data structures
60 managed by filesystem are \fIMetadata\fP and \fISystem\fP\&.
61 .TP
62 .B Profile
63 A profile describes an allocation policy based on the redundancy/replication
64 constraints in connection with the number of devices. The profile applies to
65 data and metadata block groups separately. E.g. \fIsingle\fP, \fIRAID1\fP\&.
66 .TP
67 .B RAID level
68 Where applicable, the level refers to a profile that matches constraints of the
69 standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
70 RAID10, RAID5 and RAID6.
71 .UNINDENT
72 .SH TYPICAL USE CASES
73 .SS Starting with a single\-device filesystem
74 .sp
75 Assume we\(aqve created a filesystem on a block device \fB/dev/sda\fP with profile
76 \fIsingle/single\fP (data/metadata), the device size is 50GiB and we\(aqve used the
77 whole device for the filesystem. The mount point is \fB/mnt\fP\&.
78 .sp
79 The amount of data stored is 16GiB, metadata have allocated 2GiB.
80 .SS Add new device
81 .sp
82 We want to increase the total size of the filesystem and keep the profiles. The
83 size of the new device \fB/dev/sdb\fP is 100GiB.
84 .INDENT 0.0
85 .INDENT 3.5
86 .sp
87 .EX
88 $ btrfs device add /dev/sdb /mnt
89 .EE
90 .UNINDENT
91 .UNINDENT
92 .sp
93 The amount of free data space increases by less than 100GiB, some space is
94 allocated for metadata.
95 .SS Convert to RAID1
96 .sp
97 Now we want to increase the redundancy level of both data and metadata, but
98 we\(aqll do that in steps. Note, that the device sizes are not equal and we\(aqll use
99 that to show the capabilities of split data/metadata and independent profiles.
100 .sp
101 The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2
102 copies will be stored on the devices.
103 .sp
104 First we\(aqll convert the metadata. As the metadata occupy less than 50GiB and
105 there\(aqs enough workspace for the conversion process, we can do:
106 .INDENT 0.0
107 .INDENT 3.5
108 .sp
109 .EX
110 $ btrfs balance start \-mconvert=raid1 /mnt
111 .EE
112 .UNINDENT
113 .UNINDENT
114 .sp
115 This operation can take a while, because all metadata have to be moved and all
116 block pointers updated. Depending on the physical locations of the old and new
117 blocks, the disk seeking is the key factor affecting performance.
118 .sp
119 You\(aqll note that the system block group has been also converted to RAID1, this
120 normally happens as the system block group also holds metadata (the physical to
121 logical mappings).
122 .sp
123 What changed:
124 .INDENT 0.0
125 .IP \(bu 2
126 available data space decreased by 3GiB, usable roughly (50 \- 3) + (100 \- 3) = 144 GiB
127 .IP \(bu 2
128 metadata redundancy increased
129 .UNINDENT
130 .sp
131 In other words, the unequal device sizes allow for combined space for data yet
132 improved redundancy for metadata. If we decide to increase redundancy of data as
133 well, we\(aqre going to lose 50GiB of the second device for obvious reasons.
134 .INDENT 0.0
135 .INDENT 3.5
136 .sp
137 .EX
138 $ btrfs balance start \-dconvert=raid1 /mnt
139 .EE
140 .UNINDENT
141 .UNINDENT
142 .sp
143 The balance process needs some workspace (i.e. a free device space without any
144 data or metadata block groups) so the command could fail if there\(aqs too much
145 data or the block groups occupy the whole first device.
146 .sp
147 The device size of \fB/dev/sdb\fP as seen by the filesystem remains unchanged, but
148 the logical space from 50\-100GiB will be unused.
149 .SS Remove device
150 .sp
151 Device removal must satisfy the profile constraints, otherwise the command
152 fails. For example:
153 .INDENT 0.0
154 .INDENT 3.5
155 .sp
156 .EX
157 $ btrfs device remove /dev/sda /mnt
158 ERROR: error removing device \(aq/dev/sda\(aq: unable to go below two devices on raid1
159 .EE
160 .UNINDENT
161 .UNINDENT
162 .sp
163 In order to remove a device, you need to convert the profile in this case:
164 .INDENT 0.0
165 .INDENT 3.5
166 .sp
167 .EX
168 $ btrfs balance start \-mconvert=dup \-dconvert=single /mnt
169 $ btrfs device remove /dev/sda /mnt
170 .EE
171 .UNINDENT
172 .UNINDENT
173 .sp
174 \fBWarning:\fP
175 .INDENT 0.0
176 .INDENT 3.5
177 Do not run balance to convert from a profile with more redundancy to one with
178 less redundancy in order to remove a failing device from a filesystem.
179 .sp
180 Balance is done by reading out the good metadata/data and write them into a
181 new chunk.
182 Thus it\(aqs possible the new chunk is written into the failing device.
183 .sp
184 Use \fBbtrfs device replace\fP instead.
185 .UNINDENT
186 .UNINDENT
187 .SH SUBCOMMAND
188 .INDENT 0.0
189 .TP
190 .B add [\-Kf] <device> [<device>...] <path>
191 Add device(s) to the filesystem identified by \fIpath\fP\&.
192 .sp
193 If applicable, a whole device discard (TRIM) operation is performed prior to
194 adding the device. A device with existing filesystem detected by blkid(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:blkid\:.8\:.html>
195 will prevent device addition and has to be forced. Alternatively the filesystem
196 can be wiped from the device using e.g. the wipefs(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:wipefs\:.8\:.html> tool.
197 .sp
198 The operation is instant and does not affect existing data. The operation merely
199 adds the device to the filesystem structures and creates some block groups
200 headers.
201 .sp
202 \fBOptions\fP
203 .INDENT 7.0
204 .TP
205 .B \-K|\-\-nodiscard
206 do not perform discard (TRIM) by default
207 .TP
208 .B \-f|\-\-force
209 force overwrite of existing filesystem on the given disk(s)
210 .UNINDENT
211 .INDENT 7.0
212 .TP
213 .B \-\-enqueue
214 wait if there\(aqs another exclusive operation running, otherwise continue
215 .UNINDENT
216 .TP
217 .B remove [options] <device>|<devid> [<device>|<devid>...] <path>
218 Remove device(s) from a filesystem identified by <path>
219 .sp
220 Device removal must satisfy the profile constraints, otherwise the command
221 fails and cannot be enforced. The filesystem must be converted to
222 profile(s) that would allow the removal. This can for example happen when
223 going down from 2 devices to 1 and using the RAID1 profile. See the
224 section Typical use cases \%<btrfs-device//#\:man-device-typical-use-cases>\&.
225 .sp
226 The operation can take long as it needs to move all data from the device.
227 .sp
228 \fBNote:\fP
229 .INDENT 7.0
230 .INDENT 3.5
231 It\(aqs possible to specify more than one device on the command
232 line but the devices will be removed one by one, not at once.
233 This means that the remaining devices to be deleted can be
234 still used for writes. In that case there\(aqs a warning and safety
235 timeout as this can be confusing and unexpected. The timeout can
236 be overridden by option \fI\-\-force\fP\&.
237 .UNINDENT
238 .UNINDENT
239 .sp
240 It is possible to delete the device that was used to mount the filesystem. The
241 device entry in the mount table (\fB/proc/self/mounts\fP) will be
242 replaced by another device name with the lowest device id.
243 .sp
244 If the filesystem is mounted in degraded mode (\fI\-o degraded\fP), special term
245 \fImissing\fP can be used for \fIdevice\fP\&. In that case, the first device that is
246 described by the filesystem metadata, but not present at the mount time will be
247 removed.
248 .sp
249 \fBNote:\fP
250 .INDENT 7.0
251 .INDENT 3.5
252 In most cases, there is only one missing device in degraded mode,
253 otherwise mount fails. If there are two or more devices missing (e.g. possible
254 in RAID6), you need specify \fImissing\fP as many times as the number of missing
255 devices to remove all of them.
256 .UNINDENT
257 .UNINDENT
258 .sp
259 \fBOptions\fP
260 .INDENT 7.0
261 .TP
262 .B \-\-enqueue
263 wait if there\(aqs another exclusive operation running, otherwise continue
264 .TP
265 .B \-\-force
266 skip the safety timeout when there are multiple devices for removal, this
267 does not force removing devices that would break the profile constraints
268 .UNINDENT
269 .TP
270 .B delete <device>|<devid> [<device>|<devid>...] <path>
271 Alias of remove kept for backward compatibility
272 .TP
273 .B replace <command> [options] <path>
274 Alias of whole command group \fIbtrfs replace\fP for convenience. See
275 btrfs\-replace(8) \%<>\&.
276 .TP
277 .B ready <device>
278 Wait until all devices of a multiple\-device filesystem are scanned and
279 registered within the kernel module. This is to provide a way for automatic
280 filesystem mounting tools to wait before the mount can start. The device scan
281 is only one of the preconditions and the mount can fail for other reasons.
282 Normal users usually do not need this command and may safely ignore it.
283 .TP
284 .B scan [options] [<device> [<device>...]]
285 Scan devices for a btrfs filesystem and register them with the kernel module.
286 This allows mounting multiple\-device filesystem by specifying just one from the
287 whole group.
288 .sp
289 If no devices are passed, all block devices that blkid reports to contain btrfs
290 are scanned.
291 .sp
292 The options \fI\-\-all\-devices\fP or \fI\-d\fP can be used as a fallback in case blkid is
293 not available. If used, behavior is the same as if no devices are passed.
294 .sp
295 The command can be run repeatedly. Devices that have been already registered
296 remain as such. Reloading the kernel module will drop this information. There\(aqs
297 an alternative way of mounting multiple\-device filesystem without the need for
298 prior scanning. See the mount option
299 device (in btrfs\-man5) \%<btrfs-man5//#\:mount-option-device>\&.
300 .sp
301 \fBOptions\fP
302 .INDENT 7.0
303 .TP
304 .B \-d|\-\-all\-devices
305 Enumerate and register all devices, use as a fallback in case blkid is not
306 available.
307 .TP
308 .B \-u|\-\-forget
309 Unregister a given device or all stale devices if no path is given, the device
310 must be unmounted otherwise it\(aqs an error.
311 .UNINDENT
312 .TP
313 .B stats [options] <path>|<device>|<file>
314 Read and print the device IO error statistics for all devices of the given
315 filesystem identified by \fIpath\fP or for a single \fIdevice\fP or \fIfile\fP (the
316 offline mode, unmounted filesystem).
317 .sp
318 When the filesystem is mounted the \fIpath\fP is expected to be a directory
319 and the stats are read using an ioctl and can be reset or checked. Same
320 for a block \fIdevice\fP of a mounted filesystem.
321 .sp
322 For an offline mode the path must be a file image or a block device,
323 the option \fI\-\-offline\fP is mandatory. As it\(aqs read\-only access the
324 option \fI\-\-reset\fP does not work.
325 .sp
326 See section DEVICE STATS for more
327 information about the reported statistics and the meaning.
328 .sp
329 \fBOptions\fP
330 .INDENT 7.0
331 .TP
332 .B \-z|\-\-reset
333 Print the stats and reset the values to zero afterwards. Does
334 not work in offline mode.
335 .TP
336 .B \-c|\-\-check
337 Check if the stats are all zeros and return 0 if it is so. Set bit 6 of the
338 return code if any of the statistics is no\-zero. The error values is 65 if
339 reading stats from at least one device failed, otherwise it\(aqs 64.
340 .UNINDENT
341 .INDENT 7.0
342 .TP
343 .B \-\-offline
344 Read the stats from the file image or directly from block device.
345 .TP
346 .B \-T
347 Print stats in a tabular form, devices as rows and stats as columns
348 .UNINDENT
349 .TP
350 .B usage [options] <path> [<path>...]::
351 Show detailed information about internal allocations on devices.
352 .sp
353 The level of detail can differ if the command is run under a regular or the
354 root user (due to use of restricted ioctls). The first example below is for
355 normal user (warning included) and the next one with root on the same
356 filesystem:
357 .INDENT 7.0
358 .INDENT 3.5
359 .sp
360 .EX
361 WARNING: cannot read detailed chunk info, per\-device usage will not be shown, run as root
362 /dev/sdc1, ID: 1
363 Device size: 931.51GiB
364 Device slack: 0.00B
365 Unallocated: 931.51GiB
366
367 /dev/sdc1, ID: 1
368 Device size: 931.51GiB
369 Device slack: 0.00B
370 Data,single: 641.00GiB
371 Data,RAID0/3: 1.00GiB
372 Metadata,single: 19.00GiB
373 System,single: 32.00MiB
374 Unallocated: 271.48GiB
375 .EE
376 .UNINDENT
377 .UNINDENT
378 .INDENT 7.0
379 .IP \(bu 2
380 \fIDevice size\fP \-\- size of the device as seen by the filesystem (may be
381 different than actual device size)
382 .IP \(bu 2
383 \fIDevice slack\fP \-\- portion of device not used by the filesystem but
384 still available in the physical space provided by the device, e.g.
385 after a device shrink
386 .IP \(bu 2
387 \fIData,single\fP, \fIMetadata,single\fP, \fISystem,single\fP \-\- in general, list
388 of block group type (Data, Metadata, System) and profile (single,
389 RAID1, ...) allocated on the device
390 .IP \(bu 2
391 \fIData,RAID0/3\fP \-\- in particular, striped profiles
392 RAID0/RAID10/RAID5/RAID6 with the number of devices on which the
393 stripes are allocated, multiple occurrences of the same profile can
394 appear in case a new device has been added and all new available
395 stripes have been used for writes
396 .IP \(bu 2
397 \fIUnallocated\fP \-\- remaining space that the filesystem can still use
398 for new block groups
399 .UNINDENT
400 .sp
401 \fBOptions\fP
402 .INDENT 7.0
403 .TP
404 .B \-b|\-\-raw
405 raw numbers in bytes, without the \fIB\fP suffix
406 .TP
407 .B \-h|\-\-human\-readable
408 print human friendly numbers, base 1024, this is the default
409 .UNINDENT
410 .INDENT 7.0
411 .TP
412 .B \-H
413 print human friendly numbers, base 1000
414 .TP
415 .B \-\-iec
416 select the 1024 base for the following options, according to the IEC standard
417 .TP
418 .B \-\-si
419 select the 1000 base for the following options, according to the SI standard
420 .UNINDENT
421 .INDENT 7.0
422 .TP
423 .B \-k|\-\-kbytes
424 show sizes in KiB, or kB with \-\-si
425 .TP
426 .B \-m|\-\-mbytes
427 show sizes in MiB, or MB with \-\-si
428 .TP
429 .B \-g|\-\-gbytes
430 show sizes in GiB, or GB with \-\-si
431 .TP
432 .B \-t|\-\-tbytes
433 show sizes in TiB, or TB with \-\-si
434 .UNINDENT
435 .sp
436 If conflicting options are passed, the last one takes precedence.
437 .UNINDENT
438 .SH DEVICE STATS
439 .sp
440 The device stats keep persistent record of several error classes related to
441 doing IO. The current values are printed at mount time and updated during
442 filesystem lifetime or from a scrub run.
443 .INDENT 0.0
444 .INDENT 3.5
445 .sp
446 .EX
447 $ btrfs device stats /dev/sda3
448 [/dev/sda3].write_io_errs 0
449 [/dev/sda3].read_io_errs 0
450 [/dev/sda3].flush_io_errs 0
451 [/dev/sda3].corruption_errs 0
452 [/dev/sda3].generation_errs 0
453 .EE
454 .UNINDENT
455 .UNINDENT
456 .INDENT 0.0
457 .TP
458 .B write_io_errs
459 Failed writes to the block devices, means that the layers beneath the
460 filesystem were not able to satisfy the write request.
461 .TP
462 .B read_io_errs
463 Read request analogy to write_io_errs.
464 .TP
465 .B flush_io_errs
466 Number of failed writes with the \fIFLUSH\fP flag set. The flushing is a method of
467 forcing a particular order between write requests and is crucial for
468 implementing crash consistency. In case of btrfs, all the metadata blocks must
469 be permanently stored on the block device before the superblock is written.
470 .TP
471 .B corruption_errs
472 A block checksum mismatched or a corrupted metadata header was found.
473 .TP
474 .B generation_errs
475 The block generation does not match the expected value (e.g. stored in the
476 parent node).
477 .UNINDENT
478 .sp
479 Since kernel 5.14 the device stats are also available in textual form in
480 \fB/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats\fP\&.
481 .SH EXIT STATUS
482 .sp
483 \fBbtrfs device\fP returns a zero exit status if it succeeds. Non zero is
484 returned in case of failure.
485 .sp
486 If the \fI\-c\fP option is used, \fIbtrfs device stats\fP will add 64 to the
487 exit status if any of the error counters is non\-zero.
488 .SH AVAILABILITY
489 .sp
490 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
491 \%<https://\:btrfs\:.readthedocs\:.io>\&.
492 .SH SEE ALSO
493 .sp
494 btrfs\-balance(8) \%<>
495 btrfs\-device(8) \%<>,
496 btrfs\-replace(8) \%<>,
497 mkfs.btrfs(8) \%<>
498 .\" End of generated man page.