Debian Codegraph @

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

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