diff options
Diffstat (limited to 'upstream/archlinux/man5/btrfs.5')
| -rw-r--r-- | upstream/archlinux/man5/btrfs.5 | 322 |
1 files changed, 145 insertions, 177 deletions
diff --git a/upstream/archlinux/man5/btrfs.5 b/upstream/archlinux/man5/btrfs.5 index 208aa24b..036f9f4a 100644 --- a/upstream/archlinux/man5/btrfs.5 +++ b/upstream/archlinux/man5/btrfs.5 @@ -1,3 +1,4 @@ +'\" t .\" Man page generated from reStructuredText. . . @@ -27,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BTRFS" "5" "Feb 14, 2024" "6.7.1" "BTRFS" +.TH "BTRFS" "5" "May 03, 2024" "6.8.1" "BTRFS" .SH NAME btrfs \- topics about the BTRFS filesystem (mount options, supported file attributes and other) .SH DESCRIPTION @@ -70,7 +71,7 @@ storage model, hardware considerations .SS BTRFS SPECIFIC MOUNT OPTIONS .sp This section describes mount options specific to BTRFS. For the generic mount -options please refer to \fBmount(8)\fP manual page. The options are sorted alphabetically +options please refer to \X'tty: link https://man7.org/linux/man-pages/man8/mount.8.html'\fI\%mount(8)\fP\X'tty: link' manual page. The options are sorted alphabetically (discarding the \fIno\fP prefix). .sp \fBNOTE:\fP @@ -95,7 +96,7 @@ have been applied. (default: on) .sp Enable/disable support for POSIX Access Control Lists (ACLs). See the -\fBacl(5)\fP manual page for more information about ACLs. +\X'tty: link https://man7.org/linux/man-pages/man5/acl.5.html'\fI\%acl(5)\fP\X'tty: link' manual page for more information about ACLs. .sp The support for ACL is build\-time configurable (BTRFS_FS_POSIX_ACL) and mount fails if \fIacl\fP is requested but the feature is not compiled in. @@ -228,7 +229,7 @@ If compression is enabled, \fInodatacow\fP and \fInodatasum\fP are disabled. .sp Enable data copy\-on\-write for newly created files. \fINodatacow\fP implies \fInodatasum\fP, and disables \fIcompression\fP\&. All files created -under \fInodatacow\fP are also set the NOCOW file attribute (see \fBchattr(1)\fP). +under \fInodatacow\fP are also set the NOCOW file attribute (see \X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link'). .sp \fBNOTE:\fP .INDENT 7.0 @@ -247,7 +248,7 @@ at the cost of potential partial writes, in case the write is interrupted Enable data checksumming for newly created files. \fIDatasum\fP implies \fIdatacow\fP, i.e. the normal mode of operation. All files created under \fInodatasum\fP inherit the \(dqno checksums\(dq property, however there\(aqs no -corresponding file attribute (see \fBchattr(1)\fP). +corresponding file attribute (see \X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link'). .sp \fBNOTE:\fP .INDENT 7.0 @@ -599,7 +600,7 @@ Historically, any user could create a snapshot even if he was not owner of the source subvolume, the subvolume deletion has been restricted for that reason. The subvolume creation has been restricted but this mount option is still required. This is a usability issue. -Since 4.18, the \fBrmdir(2)\fP syscall can delete an empty subvolume just like an +Since 4.18, the \X'tty: link https://man7.org/linux/man-pages/man2/rmdir.2.html'\fI\%rmdir(2)\fP\X'tty: link' syscall can delete an empty subvolume just like an ordinary directory. Whether this is possible can be detected at runtime, see \fIrmdir_subvol\fP feature in \fIFILESYSTEM FEATURES\fP\&. .UNINDENT @@ -629,13 +630,13 @@ but will work on 4.5+ kernels. .INDENT 3.5 The functionality has been removed in 5.11, any stale data created by previous use of the \fIinode_cache\fP option can be removed by -\fI\%btrfs rescue clear\-ino\-cache\fP\&. +\X'tty: link #man-rescue-clear-ino-cache'\fI\%btrfs rescue clear\-ino\-cache\fP\X'tty: link'\&. .UNINDENT .UNINDENT .UNINDENT .SS NOTES ON GENERIC MOUNT OPTIONS .sp -Some of the general mount options from \fBmount(8)\fP that affect BTRFS and are +Some of the general mount options from \X'tty: link https://man7.org/linux/man-pages/man8/mount.8.html'\fI\%mount(8)\fP\X'tty: link' that affect BTRFS and are worth mentioning. .INDENT 0.0 .TP @@ -647,7 +648,7 @@ inode atime updates in comparison to the traditional \fIstrictatime\fP\&. The wo case for atime updates under \fIrelatime\fP occurs when many files are read whose atime is older than 24 h and which are freshly snapshotted. In that case the atime is updated and COW happens \- for each file \- in bulk. See also -\fI\%https://lwn.net/Articles/499293/\fP \- \fIAtime and btrfs: a bad combination? (LWN, 2012\-05\-31)\fP\&. +\X'tty: link https://lwn.net/Articles/499293/'\fI\%https://lwn.net/Articles/499293/\fP\X'tty: link' \- \fIAtime and btrfs: a bad combination? (LWN, 2012\-05\-31)\fP\&. .sp Note that \fInoatime\fP may break applications that rely on atime uptimes like the venerable Mutt (unless you use maildir mailboxes). @@ -684,7 +685,7 @@ means the feature can be enabled. .UNINDENT .sp List of features (see also \fI\%mkfs.btrfs(8)\fP section -\fI\%FILESYSTEM FEATURES\fP): +\X'tty: link #man-mkfs-filesystem-features'\fI\%FILESYSTEM FEATURES\fP\X'tty: link'): .INDENT 0.0 .TP .B big_metadata @@ -763,6 +764,11 @@ stored as an extent, saves a few percent of metadata if sparse files are used .sp extended RAID1 mode with copies on 3 or 4 devices respectively .TP +.B raid_stripe_tree +(since: 6.7) +.sp +a separate tree for tracking file extents on RAID profiles +.TP .B RAID56 (since: 3.9) .sp @@ -771,7 +777,7 @@ the filesystem contains or contained a RAID56 profile of block groups .B rmdir_subvol (since: 4.18) .sp -indicate that \fBrmdir(2)\fP syscall can delete an empty subvolume just like an +indicate that \X'tty: link https://man7.org/linux/man-pages/man2/rmdir.2.html'\fI\%rmdir(2)\fP\X'tty: link' syscall can delete an empty subvolume just like an ordinary directory. Note that this feature only depends on the kernel version. .TP .B skinny_metadata @@ -784,6 +790,11 @@ reduced\-size metadata for extent references, saves a few percent of metadata .sp number of the highest supported send stream version .TP +.B simple_quota +(since: 6.7) +.sp +simplified quota accounting +.TP .B supported_checksums (since: 5.5) .sp @@ -813,8 +824,8 @@ sequentially, see section \fI\%ZONED MODE\fP .SH SWAPFILE SUPPORT .sp A swapfile, when active, is a file\-backed swap area. It is supported since kernel 5.0. -Use \fBswapon(8)\fP to activate it, until then (respectively again after deactivating it -with \fBswapoff(8)\fP) it\(aqs just a normal file (with NODATACOW set), for which the special +Use \X'tty: link https://man7.org/linux/man-pages/man8/swapon.8.html'\fI\%swapon(8)\fP\X'tty: link' to activate it, until then (respectively again after deactivating it +with \X'tty: link https://man7.org/linux/man-pages/man8/swapoff.8.html'\fI\%swapoff(8)\fP\X'tty: link') it\(aqs just a normal file (with NODATACOW set), for which the special restrictions for active swapfiles don\(aqt apply. .sp There are some limitations of the implementation in BTRFS and Linux swap @@ -867,16 +878,14 @@ To create and activate a swapfile run the following commands: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # truncate \-s 0 swapfile # chattr +C swapfile # fallocate \-l 2G swapfile # chmod 0600 swapfile # mkswap swapfile # swapon swapfile -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -885,12 +894,10 @@ Since version 6.1 it\(aqs possible to create the swapfile in a single command .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # btrfs filesystem mkswapfile \-\-size 2G swapfile # swapon swapfile -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -902,13 +909,11 @@ Once activated the file will appear in \fB/proc/swaps\fP: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # cat /proc/swaps Filename Type Size Used Priority /path/swapfile file 2097152 0 \-2 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -921,11 +926,9 @@ priority, not the BTRFS mount options). .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX /path/swapfile none swap defaults 0 0 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -952,21 +955,19 @@ the physical can still map to one or more device\-specific physical block addresses. It\(aqs the device\-specific physical offset that is suitable as resume offset. .sp -Since version 6.1 there\(aqs a command \fI\%btrfs inspect\-internal map\-swapfile\fP +Since version 6.1 there\(aqs a command \X'tty: link #man-inspect-map-swapfile'\fI\%btrfs inspect\-internal map\-swapfile\fP\X'tty: link' that will print the device physical offset and the adjusted value for \fB/sys/power/resume_offset\fP\&. Note that the value is divided by page size, i.e. it\(aqs not the offset itself. .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # btrfs filesystem mkswapfile swapfile # btrfs inspect\-internal map\-swapfile swapfile Physical start: 811511726080 Resume offset: 198122980 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -974,12 +975,10 @@ For scripting and convenience the option \fI\-r\fP will print just the offset: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # btrfs inspect\-internal map\-swapfile \-r swapfile 198122980 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -996,12 +995,10 @@ failed: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # swapon /path/swapfile swapon: /path/swapfile: swapon failed: Invalid argument -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1010,12 +1007,10 @@ module: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # journalctl \-t kernel | grep swapfile kernel: BTRFS warning (device sda): swapfile must have single data profile -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH CHECKSUM ALGORITHMS @@ -1060,9 +1055,8 @@ additional overhead of the b\-tree leaves. Approximate relative performance of the algorithms, measured against CRC32C using implementations on a 11th gen 3.6GHz intel CPU: .TS -center; -|l|l|l|l|. -_ +box center; +l|l|l|l. T{ Digest T} T{ @@ -1222,7 +1216,6 @@ T} T{ T} T{ builtin, reference impl. T} -_ .TE .sp Many kernels are configured with SHA256 as built\-in and not as a module. @@ -1235,15 +1228,13 @@ Check the file \fB/proc/crypto\fP, when the implementation is built\-in, you\(aq .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX name : sha256 driver : sha256\-generic module : kernel priority : 100 \&... -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1251,15 +1242,13 @@ while accelerated implementation is e.g. .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX name : sha256 driver : sha256\-avx2 module : sha256_ssse3 priority : 170 \&... -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH COMPRESSION @@ -1326,11 +1315,9 @@ Please refer to \fI\%btrfs(5)\fP section .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX $ mount \-o compress=zstd /dev/sdx /mnt -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1342,11 +1329,9 @@ cause noticeable performance drops. .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX $ btrfs filesystem defrag \-czstd file -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1360,12 +1345,10 @@ Persistent settings on a per\-file basis can be set in two ways: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX $ chattr +c file $ btrfs property set file compression zstd -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1421,12 +1404,10 @@ algorithm does not make an improvement .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX $ lsattr file \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-m file -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1447,9 +1428,9 @@ pattern detection, byte frequency, Shannon entropy. .SH COMPATIBILITY .sp Compression is done using the COW mechanism so it\(aqs incompatible with -\fInodatacow\fP\&. Direct IO works on compressed files but will fall back to buffered -writes and leads to recompression. Currently \fInodatasum\fP and compression don\(aqt -work together. +\fInodatacow\fP\&. Direct IO read works on compressed files but will fall back to +buffered writes and leads to no compression even if force compression is set. +Currently \fInodatasum\fP and compression don\(aqt work together. .sp The compression algorithms have been added over time so the version compatibility should be also considered, together with other tools that may @@ -1460,9 +1441,8 @@ Btrfs has a sysfs interface to provide extra knobs. .sp The top level path is \fB/sys/fs/btrfs/\fP, and the main directory layout is the following: .TS -center; -|l|l|l|. -_ +box center; +l|l|l. T{ Relative Path T} T{ @@ -1542,7 +1522,6 @@ Discard stats and tunables T} T{ 6.1+ T} -_ .TE .sp For \fB/sys/fs/btrfs/features/\fP directory, each file means a supported feature @@ -1886,7 +1865,7 @@ depends on the \fInodesize\fP value, for 4KiB it\(aqs 3949 bytes, for larger nod it\(aqs 4095 due to the system limit PATH_MAX .sp The symlink target may not be a valid path, i.e. the path name components -can exceed the limits (NAME_MAX), there\(aqs no content validation at \fBsymlink(3)\fP +can exceed the limits (NAME_MAX), there\(aqs no content validation at \X'tty: link https://man7.org/linux/man-pages/man3/symlink.3.html'\fI\%symlink(3)\fP\X'tty: link' creation. .TP .B maximum number of inodes @@ -1927,10 +1906,10 @@ the minimal size of each device depends on the \fImixed\-bg\fP feature, without .UNINDENT .SH BOOTLOADER SUPPORT .sp -GRUB2 (\fI\%https://www.gnu.org/software/grub\fP) has the most advanced support of +GRUB2 (\X'tty: link https://www.gnu.org/software/grub'\fI\%https://www.gnu.org/software/grub\fP\X'tty: link') has the most advanced support of booting from BTRFS with respect to features. .sp -U\-Boot (\fI\%https://www.denx.de/wiki/U\-Boot/\fP) has decent support for booting but +U\-Boot (\X'tty: link https://www.denx.de/wiki/U-Boot/'\fI\%https://www.denx.de/wiki/U\-Boot/\fP\X'tty: link') has decent support for booting but not all BTRFS features are implemented, check the documentation. .sp In general, the first 1MiB on each device is unused with the exception of @@ -1944,7 +1923,7 @@ old and new interfaces, with confusing names. The following list should clarify that: .INDENT 0.0 .IP \(bu 2 -\fIattributes\fP: \fBchattr(1)\fP or \fBlsattr(1)\fP utilities (the ioctls are +\fIattributes\fP: \X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link' or \X'tty: link https://man7.org/linux/man-pages/man1/lsattr.1.html'\fI\%lsattr(1)\fP\X'tty: link' utilities (the ioctls are FS_IOC_GETFLAGS and FS_IOC_SETFLAGS), due to the ioctl names the attributes are also called flags .IP \(bu 2 @@ -1952,7 +1931,7 @@ are also called flags bits similar to the attributes but extensible and new bits will be added in the future (the ioctls are FS_IOC_FSGETXATTR and FS_IOC_FSSETXATTR but they are not related to extended attributes that are also called xattrs), there\(aqs -no standard tool to change the bits, there\(aqs support in \fBxfs_io(8)\fP as +no standard tool to change the bits, there\(aqs support in \X'tty: link https://man7.org/linux/man-pages/man8/xfs_io.8.html'\fI\%xfs_io(8)\fP\X'tty: link' as command \fBxfs_io \-c chattr\fP .UNINDENT .SS Attributes @@ -1986,11 +1965,11 @@ empty files. .UNINDENT .TP .B d -\fIno dump\fP, makes sense with 3rd party tools like \fBdump(8)\fP, on BTRFS the +\fIno dump\fP, makes sense with 3rd party tools like \X'tty: link https://man7.org/linux/man-pages/man8/dump.8.html'\fI\%dump(8)\fP\X'tty: link', on BTRFS the attribute can be set/unset but no other special handling is done .TP .B D -\fIsynchronous directory updates\fP, for more details search \fBopen(2)\fP for \fIO_SYNC\fP +\fIsynchronous directory updates\fP, for more details search \X'tty: link https://man7.org/linux/man-pages/man2/open.2.html'\fI\%open(2)\fP\X'tty: link' for \fIO_SYNC\fP and \fIO_DSYNC\fP .TP .B i @@ -1999,23 +1978,23 @@ long as this attribute is set (obviously the exception is unsetting the attribut .TP .B m \fIno compression\fP, permanently turn off compression on the given file. Any -compression mount options will not affect this file. (\fBchattr\fP support added in +compression mount options will not affect this file. (\X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link' support added in 1.46.2) .sp When set on a directory, all newly created files will inherit this attribute. This attribute cannot be set with \fIc\fP at the same time. .TP .B S -\fIsynchronous updates\fP, for more details search \fBopen(2)\fP for \fIO_SYNC\fP and +\fIsynchronous updates\fP, for more details search \X'tty: link https://man7.org/linux/man-pages/man2/open.2.html'\fI\%open(2)\fP\X'tty: link' for \fIO_SYNC\fP and \fIO_DSYNC\fP .UNINDENT .sp No other attributes are supported. For the complete list please refer to the -\fBchattr(1)\fP manual page. +\X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link' manual page. .SS XFLAGS .sp There\(aqs an overlap of letters assigned to the bits with the attributes, this list -refers to what \fBxfs_io(8)\fP provides: +refers to what \X'tty: link https://man7.org/linux/man-pages/man8/xfs_io.8.html'\fI\%xfs_io(8)\fP\X'tty: link' provides: .INDENT 0.0 .TP .B i @@ -2041,7 +2020,7 @@ In short, a device is partitioned into fixed\-size zones and each zone can be updated by append\-only manner, or reset. As btrfs has no fixed data structures, except the super blocks, the zoned mode only requires block placement that follows the device constraints. You can learn about the whole architecture at -\fI\%https://zonedstorage.io\fP . +\X'tty: link https://zonedstorage.io'\fI\%https://zonedstorage.io\fP\X'tty: link' . .sp The devices are also called SMR/ZBC/ZNS, in \fIhost\-managed\fP mode. Note that there are devices that appear as non\-zoned but actually are, this is @@ -2127,8 +2106,8 @@ community sources gathering information from real devices. Note: zoned mode won\(aqt work with DM\-SMR disks. .INDENT 0.0 .IP \(bu 2 -Ultrastar® DC ZN540 NVMe ZNS SSD (\fI\%product -brief\fP) +Ultrastar® DC ZN540 NVMe ZNS SSD (\X'tty: link https://documents.westerndigital.com/content/dam/doc-library/en_us/assets/public/western-digital/collateral/product-brief/product-brief-ultrastar-dc-zn540.pdf'\fI\%product +brief\fP\X'tty: link') .UNINDENT .SS Emulated: null_blk .sp @@ -2144,12 +2123,10 @@ Setup: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX modprobe\ configfs modprobe\ null_blk\ nr_devices=0 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2159,8 +2136,7 @@ example taking defaults: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX cd\ /sys/kernel/config/nullb/ mkdir\ mydev cd\ mydev @@ -2169,8 +2145,7 @@ echo\ 1\ >\ zoned echo\ 1\ >\ memory_backed echo\ 256\ >\ zone_size echo\ 1\ >\ power -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2181,30 +2156,26 @@ Remove the device: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX rmdir\ /sys/kernel/config/nullb/mydev -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp Then continue with \fBmkfs.btrfs /dev/nullb0\fP, the zoned mode is auto\-detected. .sp For convenience, there\(aqs a script wrapping the basic null_blk management operations -\fI\%https://github.com/kdave/nullb.git\fP, the above commands become: +\X'tty: link https://github.com/kdave/nullb.git'\fI\%https://github.com/kdave/nullb.git\fP\X'tty: link', the above commands become: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX nullb setup nullb create \-s 2g \-z 256 mkfs.btrfs /dev/nullb0 \&... nullb rm nullb0 -.ft P -.fi +.EE .UNINDENT .UNINDENT .SS Emulated: TCMU runner @@ -2212,7 +2183,7 @@ nullb rm nullb0 TCMU is a framework to emulate SCSI devices in userspace, providing various backends for the storage, with zoned support as well. A file\-backed zoned device can provide more options for larger storage and zone size. Please follow -the instructions at \fI\%https://zonedstorage.io/projects/tcmu\-runner/\fP . +the instructions at \X'tty: link https://zonedstorage.io/projects/tcmu-runner/'\fI\%https://zonedstorage.io/projects/tcmu\-runner/\fP\X'tty: link' . .SS Compatibility, incompatibility .INDENT 0.0 .IP \(bu 2 @@ -2237,25 +2208,25 @@ or 1GiB, larger size is expected, maximum zone size supported by btrfs is .sp The zoned mode has been released in 5.12 and there are still some rough edges and corner cases one can hit during testing. Please report bugs to -\fI\%https://github.com/naota/linux/issues/\fP . +\X'tty: link https://github.com/naota/linux/issues/'\fI\%https://github.com/naota/linux/issues/\fP\X'tty: link' . .SS References .INDENT 0.0 .IP \(bu 2 -\fI\%https://zonedstorage.io\fP +\X'tty: link https://zonedstorage.io'\fI\%https://zonedstorage.io\fP\X'tty: link' .INDENT 2.0 .IP \(bu 2 -\fI\%https://zonedstorage.io/projects/libzbc/\fP \-\- \fIlibzbc\fP is library and set +\X'tty: link https://zonedstorage.io/projects/libzbc/'\fI\%https://zonedstorage.io/projects/libzbc/\fP\X'tty: link' \-\- \fIlibzbc\fP is library and set of tools to directly manipulate devices with ZBC/ZAC support .IP \(bu 2 -\fI\%https://zonedstorage.io/projects/libzbd/\fP \-\- \fIlibzbd\fP uses the kernel +\X'tty: link https://zonedstorage.io/projects/libzbd/'\fI\%https://zonedstorage.io/projects/libzbd/\fP\X'tty: link' \-\- \fIlibzbd\fP uses the kernel provided zoned block device interface based on the ioctl() system calls .UNINDENT .IP \(bu 2 -\fI\%https://hddscan.com/blog/2020/hdd\-wd\-smr.html\fP \-\- some details about exact device types +\X'tty: link https://hddscan.com/blog/2020/hdd-wd-smr.html'\fI\%https://hddscan.com/blog/2020/hdd\-wd\-smr.html\fP\X'tty: link' \-\- some details about exact device types .IP \(bu 2 -\fI\%https://lwn.net/Articles/853308/\fP \-\- \fIBtrfs on zoned block devices\fP +\X'tty: link https://lwn.net/Articles/853308/'\fI\%https://lwn.net/Articles/853308/\fP\X'tty: link' \-\- \fIBtrfs on zoned block devices\fP .IP \(bu 2 -\fI\%https://www.usenix.org/conference/vault20/presentation/bjorling\fP \-\- Zone +\X'tty: link https://www.usenix.org/conference/vault20/presentation/bjorling'\fI\%https://www.usenix.org/conference/vault20/presentation/bjorling\fP\X'tty: link' \-\- Zone Append: A New Way of Writing to Zoned Storage .UNINDENT .SH CONTROL DEVICE @@ -2265,12 +2236,10 @@ numbers 10 and 234 (the device can be found under the \fImisc\fP category). .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX $ ls \-l /dev/btrfs\-control crw\-\-\-\-\-\-\- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs\-control -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2297,11 +2266,9 @@ likely accidentally deleted), it\(aqs possible to recreate it by .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # mknod \-\-mode=600 /dev/btrfs\-control c 10 234 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2309,11 +2276,9 @@ or (since 5.11) by a convenience command .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # btrfs rescue create\-control\-device -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2331,13 +2296,11 @@ a test to detect this kind of condition and print a warning like this: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX WARNING: Multiple block group profiles detected, see \(aqman btrfs(5)\(aq. WARNING: Data: single, raid1 WARNING: Metadata: single, raid1 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2345,8 +2308,7 @@ The corresponding output of \fBbtrfs filesystem df\fP might look like: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX WARNING: Multiple block group profiles detected, see \(aqman btrfs(5)\(aq. WARNING: Data: single, raid1 WARNING: Metadata: single, raid1 @@ -2356,8 +2318,7 @@ System, single: total=4.00MiB, used=16.00KiB Metadata, single: total=8.00MiB, used=112.00KiB Metadata, RAID1: total=64.00MiB, used=32.00KiB GlobalReserve, single: total=16.25MiB, used=0.00B -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2398,11 +2359,9 @@ that report space usage: \fBfilesystem df\fP, \fBdevice usage\fP\&. The command .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX Multiple profiles: yes (data, metadata) -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH SEEDING DEVICE @@ -2414,9 +2373,9 @@ imagine an immutable golden image of an operating system enhanced with another device that allows to use the data from the golden image and normal operation. This idea originated on CD\-ROMs with base OS and allowing to use them for live systems, but this became obsolete. There are technologies providing similar -functionality, like \fI\%unionmount\fP, -\fI\%overlayfs\fP or -\fI\%qcow2\fP image snapshot. +functionality, like \X'tty: link https://en.wikipedia.org/wiki/Union_mount'\fI\%unionmount\fP\X'tty: link', +\X'tty: link https://en.wikipedia.org/wiki/OverlayFS'\fI\%overlayfs\fP\X'tty: link' or +\X'tty: link https://en.wikipedia.org/wiki/Qcow#qcow2'\fI\%qcow2\fP\X'tty: link' image snapshot. .sp The seeding device starts as a normal filesystem, once the contents is ready, \fBbtrfstune \-S 1\fP is used to flag it as a seeding device. Mounting such device @@ -2457,8 +2416,7 @@ Example how to create and use one seeding device: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # mkfs.btrfs /dev/sda # mount /dev/sda /mnt/mnt1 \&... fill mnt1 with data @@ -2471,8 +2429,7 @@ Example how to create and use one seeding device: # umount /mnt/mnt1 # mount /dev/sdb /mnt/mnt1 \&... /mnt/mnt1 is now writable -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2481,15 +2438,13 @@ again with a another writable device: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # mount /dev/sda /mnt/mnt2 # btrfs device add /dev/sdc /mnt/mnt2 # umount /mnt/mnt2 # mount /dev/sdc /mnt/mnt2 \&... /mnt/mnt2 is now writable -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2498,11 +2453,9 @@ used independently: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # btrfs device delete /dev/sda /mnt/mnt1 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2538,8 +2491,7 @@ and it continues as before as a simple tree structure on devices. .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # mkfs.btrfs /dev/sda # mount /dev/sda /mnt/mnt1 \&... fill mnt1 with data @@ -2560,8 +2512,7 @@ and it continues as before as a simple tree structure on devices. # mount \-o remount,rw /mnt/mnt1 \&... /mnt/mnt1 is now writable # umount /mnt/mnt1 -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -2757,10 +2708,23 @@ have been demonstrated (\fIrowhammer\fP) achieving specific bits to be flipped. While these were targeted, this shows that a series of reads or writes can affect unrelated parts of memory. .sp +Block group profiles with redundancy (like RAID1) will not protect against +memory errors as the blocks are first stored in memory before they are written +to the devices from the same source. +.sp +A filesystem mounted read\-only will not affect the underlying block device in +almost 100% (with highly unlikely exceptions). The exception is a tree\-log that +needs to be replayed during mount (and before the read\-only mount takes place), +working memory is needed for that and that can be affected by bit flips. +There\(aqs a theoretical case where bit flip changes the filesystem status from +read\-only to read\-write. +.sp Further reading: .INDENT 0.0 .IP \(bu 2 -\fI\%https://en.wikipedia.org/wiki/Row_hammer\fP +\X'tty: link https://en.wikipedia.org/wiki/Row_hammer'\fI\%https://en.wikipedia.org/wiki/Row_hammer\fP\X'tty: link' +.IP \(bu 2 +memory overclocking, XMP, potential risks .UNINDENT .sp What to do: @@ -2772,6 +2736,10 @@ is under heavy load that the default memtest cannot trigger memory errors may appear as filesystem going read\-only due to \(dqpre write\(dq check, that verify meta data before they get written but fail some basic consistency checks +.IP \(bu 2 +newly built systems should be tested before being put to production use, +ideally start a IO/CPU load that will be run on such system later; namely +systems that will utilize overclocking or special performance features .UNINDENT .SS Direct memory access (DMA) .sp @@ -2827,7 +2795,7 @@ to avoid unnecessary resets and performs optimizations to maximize the storage media lifetime. The known techniques are deduplication (blocks with same fingerprint/hash are mapped to same physical block), compression or internal remapping and garbage collection of used memory cells. Due to the additional -processing there are measures to verity the data e.g. by ECC codes. +processing there are measures to verify the data e.g. by ECC codes. .sp The observations of failing SSDs show that the whole electronic fails at once or affects a lot of data (e.g. stored on one chip). Recovering such data @@ -2882,13 +2850,13 @@ it\(aqs hard to justify wear reduction as a benefit. Further reading: .INDENT 0.0 .IP \(bu 2 -\fI\%https://www.snia.org/educational\-library/ssd\-and\-deduplication\-end\-spinning\-disk\-2012\fP +\X'tty: link https://www.snia.org/educational-library/ssd-and-deduplication-end-spinning-disk-2012'\fI\%https://www.snia.org/educational\-library/ssd\-and\-deduplication\-end\-spinning\-disk\-2012\fP\X'tty: link' .IP \(bu 2 -\fI\%https://www.snia.org/educational\-library/realities\-solid\-state\-storage\-2013\-2013\fP +\X'tty: link https://www.snia.org/educational-library/realities-solid-state-storage-2013-2013'\fI\%https://www.snia.org/educational\-library/realities\-solid\-state\-storage\-2013\-2013\fP\X'tty: link' .IP \(bu 2 -\fI\%https://www.snia.org/educational\-library/ssd\-performance\-primer\-2013\fP +\X'tty: link https://www.snia.org/educational-library/ssd-performance-primer-2013'\fI\%https://www.snia.org/educational\-library/ssd\-performance\-primer\-2013\fP\X'tty: link' .IP \(bu 2 -\fI\%https://www.snia.org/educational\-library/how\-controllers\-maximize\-ssd\-life\-2013\fP +\X'tty: link https://www.snia.org/educational-library/how-controllers-maximize-ssd-life-2013'\fI\%https://www.snia.org/educational\-library/how\-controllers\-maximize\-ssd\-life\-2013\fP\X'tty: link' .UNINDENT .sp What to do: @@ -2918,9 +2886,9 @@ physical connection of the device. You may want to run self\-tests (using \fBsmartctl\fP). .INDENT 0.0 .IP \(bu 2 -\fI\%https://en.wikipedia.org/wiki/NVM_Express\fP +\X'tty: link https://en.wikipedia.org/wiki/NVM_Express'\fI\%https://en.wikipedia.org/wiki/NVM_Express\fP\X'tty: link' .IP \(bu 2 -\fI\%https://www.smartmontools.org/wiki/NVMe_Support\fP +\X'tty: link https://www.smartmontools.org/wiki/NVMe_Support'\fI\%https://www.smartmontools.org/wiki/NVMe_Support\fP\X'tty: link' .UNINDENT .SS Drive firmware .sp @@ -2960,13 +2928,13 @@ and replacing the card could be required as well. filesystem when it tells you.\fP .SH SEE ALSO .sp -\fBacl(5)\fP, +\X'tty: link https://man7.org/linux/man-pages/man5/acl.5.html'\fI\%acl(5)\fP\X'tty: link', \fI\%btrfs(8)\fP, -\fBchattr(1)\fP, -\fBfstrim(8)\fP, -\fBioctl(2)\fP, +\X'tty: link https://man7.org/linux/man-pages/man1/chattr.1.html'\fI\%chattr(1)\fP\X'tty: link', +\X'tty: link https://man7.org/linux/man-pages/man8/fstrim.8.html'\fI\%fstrim(8)\fP\X'tty: link', +\X'tty: link https://man7.org/linux/man-pages/man2/ioctl.2.html'\fI\%ioctl(2)\fP\X'tty: link', \fI\%mkfs.btrfs(8)\fP, -\fBmount(8)\fP, -\fBswapon(8)\fP +\X'tty: link https://man7.org/linux/man-pages/man8/mount.8.html'\fI\%mount(8)\fP\X'tty: link', +\X'tty: link https://man7.org/linux/man-pages/man8/swapon.8.html'\fI\%swapon(8)\fP\X'tty: link' .\" Generated by docutils manpage writer. . |