From d8172c2fbc5a6db3ec8d6981f6b3069bb20bc699 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 1 Jun 2023 20:46:06 +0200 Subject: [PATCH] btrfs-progs: docs: fixups, references Signed-off-by: David Sterba --- CHANGES | 4 +- Documentation/Feature-by-version.rst | 105 +++++++++++++------------ Documentation/Kernel-by-version.rst | 6 +- Documentation/Source-repositories.rst | 2 +- Documentation/Status.rst | 2 - Documentation/btrfs-convert.rst | 3 +- Documentation/btrfs-device.rst | 10 ++- Documentation/btrfs-filesystem.rst | 2 +- Documentation/btrfs-man5.rst | 14 +++- Documentation/btrfs-quota.rst | 5 +- Documentation/btrfs.rst | 9 ++- Documentation/btrfstune.rst | 9 ++- Documentation/ch-balance-filters.rst | 3 +- Documentation/ch-balance-intro.rst | 3 +- Documentation/ch-bootloaders.rst | 2 +- Documentation/ch-compression.rst | 3 +- Documentation/ch-flexibility.rst | 2 +- Documentation/ch-fs-limits.rst | 4 +- Documentation/ch-sysfs.rst | 31 ++++---- Documentation/dev/Developer-s-FAQ.rst | 2 + Documentation/dev/dev-btrfs-design.rst | 2 +- Documentation/index.rst | 2 +- Documentation/mkfs.btrfs.rst | 38 ++++++--- INSTALL | 3 +- 24 files changed, 157 insertions(+), 109 deletions(-) diff --git a/CHANGES b/CHANGES index 85de5e91..b901eb8c 100644 --- a/CHANGES +++ b/CHANGES @@ -32,8 +32,8 @@ btrfs-progs-6.3.1 (2023-05-29) * mkfs: make option --rootdir more verbose and report start when filling from the given directory starts * experimental: - * btrfstune: checksum switch logic reimplemented, conversion of all - metadata and data now works, resume from various states also supported + * btrfstune: checksum switch logic reimplemented, conversion of all + metadata and data now works, resume from various states also supported * other: * more CI github actions test coverage * more kernel/userspace source code sync diff --git a/Documentation/Feature-by-version.rst b/Documentation/Feature-by-version.rst index 5be7e9dd..f4d35642 100644 --- a/Documentation/Feature-by-version.rst +++ b/Documentation/Feature-by-version.rst @@ -7,7 +7,7 @@ information look below. The version states at which version a feature has been merged into the mainline kernel. It does not tell anything about at which kernel version it is considered mature enough for production use. For an estimation on stability of -features see [[Status]] page. +features see :doc:`Status` page. 6.x --- @@ -16,15 +16,15 @@ features see [[Status]] page. Send protocol update that adds new commands and extends existing functionality to write large data chunks. Compressed (and encrypted) extents can be optionally emitted and transferred as-is without the need - to recompress (or reencrypt) on the receiving side. + to re-compress (or re-encrypt) on the receiving side. 6.0 - sysfs exports commit stats - The file /sys/fs/btrfs/FSID/commit_stats shows number of commits and + The file :file:`/sys/fs/btrfs/FSID/commit_stats` shows number of commits and various time related statistics. 6.0 - sysfs exports chunk sizes Chunk size value can be read from - /sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size . + :file:`/sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size`. 6.0 - sysfs shows zoned mode among features The zoned mode has been supported since 5.10 and adding functionality. @@ -33,7 +33,7 @@ features see [[Status]] page. 6.0 - checksum implementation is logged at mount time When a filesystem is mounted the implementation backing the checksums is logged. The information is also accessible in - /sys/fs/btrfs/FSID/checksum . + :file:`/sys/fs/btrfs/FSID/checksum`. 6.1 - sysfs support to temporarily skip exact qgroup accounting Allow user override of qgroup accounting and make it temporarily out @@ -56,14 +56,14 @@ features see [[Status]] page. features. 6.1 - discard stats available in sysfs - The directory '/sys/fs/btrfs/FSID/discard' exports statistics and + The directory :file:`/sys/fs/btrfs/FSID/discard` exports statistics and tunables related to discard. 6.1 - additional qgroup stats in sysfs The overall status of qgroups are exported in - /sys/sys/fs/btrfs/FSID/qgroups/ . + :file:`/sys/sys/fs/btrfs/FSID/qgroups/`. -6.1 - check that subperblock is unchanged at thaw time +6.1 - check that super block is unchanged at thaw time Do full check of super block once a filesystem is thawed. This namely happens when system resumes from suspend or hibernation. Accidental change by other operating systems will be detected. @@ -74,7 +74,7 @@ features see [[Status]] page. 6.3 - discard=async settings tuned The default IOPS limit has changed from 100 to 1000 and writing value 0 - to '/sys/fs/btrfs/FSID/discard/iops_limit' newly means to not do any + to :file:`/sys/fs/btrfs/FSID/discard/iops_limit` newly means to not do any throttling. 6.3 - block group allocation class heuristics @@ -82,14 +82,14 @@ features see [[Status]] page. in block groups, assuming that file size and life time is correlated, in particular this may help during balance. The stats about the number of used classes per block group type is exported in - '/sys/fs/btrfs/FSID/allocation/\*/size_classes'. + :file:`/sys/fs/btrfs/FSID/allocation/\*/size_classes`. 6.3 - in DEV_INFO ioctl export per-device FSID - A seeding device could have a different FSID, available in syfs and now + A seeding device could have a different FSID, available in sysfs and now available via DEV_INFO ioctl. 6.3 - send utimes cache, reduced stream size - Utimes for directories are emitted into the send steram only when + Utimes for directories are emitted into the send stream only when finalizing the directory, the cache also gains significant speedups (up to 10x). @@ -151,7 +151,7 @@ features see [[Status]] page. filesystem. Now supports: nologreplay, usebackuproot 5.9 - qgroups in sysfs - The information about qgroup status and relations is exported in */sys/fs/UUID/qgroups* + The information about qgroup status and relations is exported in :file:`/sys/fs/UUID/qgroups` 5.9 - FS_INFO ioctl Export more information: checksum type, checksum size, generation, metadata_uuid @@ -163,24 +163,25 @@ features see [[Status]] page. 5.11 - remove *inode_cache* Remove inode number caching feature (mount -o inode_cache) -5.11 - more rescue= +5.11 - more rescue= modes Additional modes for mount option *rescue=*: ignorebadroots/ibadroots, - ignoredatacsums/idatacsums. All are exported in sysfs. + ignoredatacsums/idatacsums. All are exported in + :file:`/sys/fs/btrfs/features/supported_rescue_options`. 5.12 - zoned mode Support for zoned devices with special allocation/write mode to - fixed-size zones. See [[Zoned]]. + fixed-size zones. See :doc:`Zoned`. 5.13 - supported_sectorsizes in sysfs - List supported sector sizes in sysfs file /sys/fs/btrfs/features/supported_sectorsizes + List supported sector sizes in sysfs file :file:`/sys/fs/btrfs/features/supported_sectorsizes`. 5.14 - sysfs scrub bw limit Tunable bandwidth limit - (/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max) for scrub (and + :file:`/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max` for scrub (and device replace) for a given device. 5.14 - sysfs device stats - The device stats can be also found in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats. + The device stats can be also found in :file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`. 5.14 - cancellable resize, device delete The filesystem resize and device delete operations can be cancelled by @@ -217,25 +218,25 @@ features see [[Status]] page. 5.17 - *no warning with flushoncommit* Mounting with *-o flushoncommit* does not trigger the (harmless) - warning at each transaction commit + warning at each transaction commit. .. note:: Also backported to 5.15.27 and 5.16.13 5.18 - zoned and DUP metadata - DUP metadata works with zoned mode + DUP metadata works with zoned mode. 5.18 - encoded data ioctl New ioctls to read and write pre-encoded data (i.e. no transformation - and directly written as extents), now works for compressed data + and directly written as extents), now works for compressed data. 5.18 - *removed balance ioctl v1* The support for ioctl BTRFS_IOC_BALANCE has been removed, superseded by - BTRFS_IOC_BALANCE_V2m long time ago + BTRFS_IOC_BALANCE_V2 long time ago. 5.18 - *cross-mount reflink works* - the VFS limitation to reflink files on separate subvolume mounts of the - same filesystem has been removed + The VFS limitation to reflink files on separate subvolume mounts of the + same filesystem has been removed. 5.18 - syslog error messages with filesystem state Messages are printed with a one letter tag ("state: X") that denotes in @@ -281,7 +282,7 @@ features see [[Status]] page. Add possibility to set a threshold to automatically reclaim block groups also in non-zoned mode. By default completely empty block groups are reclaimed automatically but the threshold can be tuned in - /sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold . + :file:`/sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold`. 5.19 - tree-checker verifies metadata block ownership Additional check done by tree-checker to verify relationship between a @@ -308,9 +309,10 @@ features see [[Status]] page. 4.4 - balance filter updates Enhanced syntax and new balance filters: - * limit=min..max - * usage=min..max - * stripes=min..max + + * limit=min..max + * usage=min..max + * stripes=min..max 4.5 - free space tree Improved implementation of free space cache (aka v2), using b-trees. @@ -330,7 +332,7 @@ features see [[Status]] page. 4.6 - read features from control device The existing ioctl GET_SUPPORTED_FEATURES can be now used on the - control device (/dev/btrfs-control) and returns the supported features + control device (:file:`/dev/btrfs-control`) and returns the supported features without any mounted filesystem. 4.7 - delete device by id @@ -384,7 +386,7 @@ features see [[Status]] page. 4.15 - *ref-verify* Debugging functionality to verify extent references. New mount option - ref-verify, must be built with CONFIG_BTRFS_FS_REF_VERIFY. + *ref-verify*, must be built with CONFIG_BTRFS_FS_REF_VERIFY. 4.15 - ZLIB level Allow to set the ZLIB compression level via mount option, e.g. like @@ -395,8 +397,7 @@ features see [[Status]] page. An enhanced version of ioctl that can translate logical extent offset to inode numbers, "who owns this block". For certain use cases the V1 performs bad and this is addressed by V2. - [https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884 - Read more.] + See for more https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884 . 4.15 - compression heuristics Apply a few heuristics to the data before they're compressed to decide @@ -404,14 +405,13 @@ features see [[Status]] page. sampling, repeated pattern detection, Shannon entropy calculation. 4.16 - fallocate: zero range - Mode of the [http://man7.org/linux/man-pages/man2/fallocate.2.html - *fallocate*] syscall to zero file range. + Mode of the *fallocate* syscall to zero file range. 4.17 - *removed user transaction ioctl* - deprecated in 4.14, see above + Deprecated in 4.14, see above. 4.17 - *rmdir* on subvolumes - Allow rmdir to delete an empty subvolume. + Allow *rmdir* to delete an empty subvolume. 4.18 - XFLAGS ioctl Add support for ioctl FS_IOC_FSSETXATTR/FS_IOC_FSGETXATTR, successor of @@ -470,7 +470,7 @@ features see [[Status]] page. Support for metadata blocks larger than page size .. note:: - Default nodesize is 16k since btrfs-progs 3.12 + Default nodesize is 16KiB since btrfs-progs 3.12 3.4 - error handling Generic infrastructure for graceful error handling (EIO) @@ -487,54 +487,59 @@ features see [[Status]] page. 3.6 - send/receive Ability to transfer one filesystem via a data stream (full or incremental) and apply the changes on a remote filesystem. + 3.7 - extrefs - Hardlink count limit is lifted to 64k + Hardlink count limit is lifted to 65536. .. note:: Default since btrfs-progs 3.12 3.7 - hole punching - Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate* + Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*. 3.8 - device replace - Efficient replacement of existing device (add/remove in one go) + Efficient replacement of existing device (add/remove in one go). 3.9 - raid 5/6 *(incomplete)* - Basic support for RAID5/6 profiles, no crash resiliency, replace and scrub support + Basic support for RAID5/6 profiles, no crash resiliency, replace and + scrub support. 3.9 - snapshot-aware defrag - Defrag does not break links between shared extents (snapshots, reflinked files) + Defrag does not break links between shared extents (snapshots, + reflinked files). .. note:: Disabled since 3.14 (and backported to some stable kernel versions) due to problems. Has been completely removed in 5.6. 3.9 - lightweight send - A mode of *send* that does not add the actual file data to the stream + A mode of *send* that does not add the actual file data to the stream. 3.9 - on-line label set/get - Label editable on mounted filesystems + Label editable on mounted filesystems. 3.10 - skinny metadata - Reduced metadata size (format change) of extents + Reduced metadata size (format change) of extents. .. note:: Default since btrfs-progs 3.18 3.10 - qgroup rescan - Sync qgroups with existing filesystem data + Sync qgroups with existing filesystem data. 3.12 - UUID tree - A map of subvolume/UUID that vastly speeds up send/receive + A map of subvolume/UUID that vastly speeds up send/receive. 3.12 - out-of-bound deduplication Support for deduplicating extents on a given set of files. 3.14 - no-holes - No extent representation for file holes (format change), may reduce overall metadata consumption + No extent representation for file holes (format change), may reduce + overall metadata consumption 3.14 - feature bits in sysfs - /sys/fs/btrfs exports various bits about filesystem capabilities and feature support + :file:`/sys/fs/btrfs` exports various bits about filesystem + capabilities and feature support 3.16 - O_TMPFILE Mode of open() to safely create a temporary file diff --git a/Documentation/Kernel-by-version.rst b/Documentation/Kernel-by-version.rst index 6d315d00..0d554af1 100644 --- a/Documentation/Kernel-by-version.rst +++ b/Documentation/Kernel-by-version.rst @@ -1260,10 +1260,10 @@ Fixes: 3.10 (Jun 2013) ^^^^^^^^^^^^^^^ -* reduced size of metadata by so-called '''[[Feature:Skinny_Metadata|skinny extents]]''' [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c] +* reduced size of metadata by so-called :ref:`skinny extents` [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c] * enhanced syslog message format [http://permalink.gmane.org/gmane.comp.file-systems.btrfs/24330] * the mount option ''subvolrootid'' is deprecated -* lots of stability improvements, removed many BUG_ONs +* lots of stability improvements, removed many< BUG_ONs * qgroups are automatically created when quotas are enabled [http://git.kernel.org/linus/7708f029dca5f1b9e9d6ea01ab10cd83e4c74ff2] * qgroups are able to ''rescan'' current filesystem and sync the quota state with the existing subvolumes * enhanced ''send/recv '' format for multiplexing more data into one stream [http://git.kernel.org/linus/c2c71324ecb471c932bc1ff59e46ffcf82f274fc] @@ -1281,7 +1281,7 @@ Fixes: ^^^^^^^^^^^^^^^ * Major performance improvement for send/receive with large numbers of subvolumes -* Support for batch [[deduplication]] (userspace tools required) +* Support for batch :doc:`deduplication` (userspace tools required) * new mount option ''commit'' to set the commit interval * Lots of stability and bugfix patches diff --git a/Documentation/Source-repositories.rst b/Documentation/Source-repositories.rst index 2636dcb9..1d2cbd5f 100644 --- a/Documentation/Source-repositories.rst +++ b/Documentation/Source-repositories.rst @@ -27,7 +27,7 @@ There are: * snapshots of *for-next*, that contain all of the above (e.g. for-next-20200512) Note that the branches get rebased. The base point for patches depend on the -development phase. See [[Developer%27s_FAQ#Development_schedule]]. +development phase. See :ref:`development schedule`. Independent changes can be based on the *linus/master* branch, changes that could depend on patches that have been added to one of the queues should use that as a base. diff --git a/Documentation/Status.rst b/Documentation/Status.rst index d735cd93..d84dceb5 100644 --- a/Documentation/Status.rst +++ b/Documentation/Status.rst @@ -232,8 +232,6 @@ Please open an issue if: - a particular feature combination that has a different status and is worth mentioning separately - you know of a bug that lowers the feature status -- a reference could be enhanced by an actual link to documentation - (wiki, manual pages) Subpage block size ------------------ diff --git a/Documentation/btrfs-convert.rst b/Documentation/btrfs-convert.rst index 2cbea01c..55d9afa0 100644 --- a/Documentation/btrfs-convert.rst +++ b/Documentation/btrfs-convert.rst @@ -41,7 +41,8 @@ OPTIONS -O|--features [,...] A list of filesystem features enabled the at time of conversion. Not all features are supported by old kernels. To disable a feature, prefix it with *^*. - Description of the features is in section *FILESYSTEM FEATURES* of + Description of the features is in section + :ref:`FILESYSTEM FEATURES` of :doc:`mkfs.btrfs(8)`. To see all available features that btrfs-convert supports run: diff --git a/Documentation/btrfs-device.rst b/Documentation/btrfs-device.rst index 0a6c4d84..01d7f7e2 100644 --- a/Documentation/btrfs-device.rst +++ b/Documentation/btrfs-device.rst @@ -112,9 +112,9 @@ scan [options] [ [...]] stats [options] | Read and print the device IO error statistics for all devices of the given - filesystem identified by *path* or for a single *device>. The filesystem must - be mounted. See section *DEVICE STATS* for more information about the reported - statistics and the meaning. + filesystem identified by *path* or for a single *device*. The filesystem must + be mounted. See section :ref:`DEVICE STATS` + for more information about the reported statistics and the meaning. ``Options`` @@ -195,6 +195,8 @@ usage [options] [...]:: If conflicting options are passed, the last one takes precedence. +.. _man-device-device-stats: + DEVICE STATS ------------ @@ -228,7 +230,7 @@ generation_errs parent node). Since kernel 5.14 the device stats are also available in textual form in -*/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats*. +:file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`. EXIT STATUS ----------- diff --git a/Documentation/btrfs-filesystem.rst b/Documentation/btrfs-filesystem.rst index 46c32752..7c963aa4 100644 --- a/Documentation/btrfs-filesystem.rst +++ b/Documentation/btrfs-filesystem.rst @@ -351,7 +351,7 @@ usage [options] [...] filesystem) * *Multiple profiles* -- what block group types (data, metadata) have more than one profile (single, raid1, ...), see :doc:`btrfs(5)` section - *FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES*. + :ref:`FILESYSTEMS WITH MULTIPLE PROFILES`. And on a zoned filesystem there are two more lines in the *Device* section: diff --git a/Documentation/btrfs-man5.rst b/Documentation/btrfs-man5.rst index 04550ac1..798401d3 100644 --- a/Documentation/btrfs-man5.rst +++ b/Documentation/btrfs-man5.rst @@ -23,12 +23,15 @@ tools. Currently covers: #. RAID56 status and recommended practices #. storage model, hardware considerations +.. _man-btrfs5-mount-option: MOUNT OPTIONS ------------- .. include:: ch-mount-options.rst +.. _man-btrfs5-filesystem-features: + FILESYSTEM FEATURES ------------------- @@ -59,7 +62,8 @@ after mkfs, on a mounted filesystem in the directory */sys/fs/btrfs/features/*, one file per feature. The value *1* means the feature can be enabled. -List of features (see also :doc:`mkfs.btrfs(8)` section *FILESYSTEM FEATURES*): +List of features (see also :doc:`mkfs.btrfs(8)` section +:ref:`FILESYSTEM FEATURES`): big_metadata (since: 3.4) @@ -189,6 +193,8 @@ SWAPFILE SUPPORT .. include:: ch-swapfile.rst +.. _man-mkfs-checksum-algorithms: + CHECKSUM ALGORITHMS ------------------- @@ -204,6 +210,8 @@ SYSFS INTERFACE .. include:: ch-sysfs.rst +.. _man-btrfs5-fileysstem-exclusive-operations: + FILESYSTEM EXCLUSIVE OPERATIONS ------------------------------- @@ -245,6 +253,8 @@ FILE ATTRIBUTES .. include:: ch-file-attributes.rst +.. _man-btrfs5-zoned-mode: + ZONED MODE ---------- @@ -294,6 +304,7 @@ work and a workaround would need to be used to mount a multi-device filesystem. The mount option *device* can trigger the device scanning during mount, see also :command:`btrfs device scan`. +.. _man-btrfs5-filesystem-with-multiple-profiles: FILESYSTEM WITH MULTIPLE PROFILES --------------------------------- @@ -359,6 +370,7 @@ that report space usage: :command:`filesystem df`, :command:`device usage`. The Multiple profiles: yes (data, metadata) +.. _man-btrfs5-seeding-device: SEEDING DEVICE -------------- diff --git a/Documentation/btrfs-quota.rst b/Documentation/btrfs-quota.rst index b8955f46..830e9059 100644 --- a/Documentation/btrfs-quota.rst +++ b/Documentation/btrfs-quota.rst @@ -16,7 +16,8 @@ of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand .. note:: Qgroups are different than the traditional user quotas and designed to track shared and exclusive data per-subvolume. Please refer to the section - *HIERARCHICAL QUOTA GROUP CONCEPTS* for a detailed description. + :ref:`HIERARCHICAL QUOTA GROUP CONCEPTS` + for a detailed description. PERFORMANCE IMPLICATIONS ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -33,6 +34,8 @@ the core of the filesystem operation. Qgroup users have hit various corner cases over time, such as incorrect accounting or system instability. The situation is gradually improving and issues found and fixed. +.. _man-quota-hierarchical-quota-group-concepts: + HIERARCHICAL QUOTA GROUP CONCEPTS --------------------------------- diff --git a/Documentation/btrfs.rst b/Documentation/btrfs.rst index 35d786cc..8164d845 100644 --- a/Documentation/btrfs.rst +++ b/Documentation/btrfs.rst @@ -11,11 +11,12 @@ DESCRIPTION The :command:`btrfs` utility is a toolbox for managing btrfs filesystems. There are command groups to work with subvolumes, devices, for whole filesystem or other -specific actions. See section *COMMANDS*. +specific actions. See section :ref:`COMMANDS`. There are also standalone tools for some tasks like :command:`btrfs-convert` or :command:`btrfstune` that were separate historically and/or haven't been merged to the -main utility. See section *STANDALONE TOOLS* for more details. +main utility. See section :ref:`STANDALONE TOOLS` +for more details. For other topics (mount options, etc) please refer to the separate manual page :doc:`btrfs(5)`. @@ -68,6 +69,8 @@ The remaining options are relevant only for the main tool: --version print version string +.. _man-btrfs8-commands: + COMMANDS -------- @@ -131,6 +134,8 @@ subvolume Create/delete/list/manage btrfs subvolume. See :doc:`btrfs-subvolume(8)` for details. +.. _man-btrfs8-standalone-tools: + STANDALONE TOOLS ---------------- diff --git a/Documentation/btrfstune.rst b/Documentation/btrfstune.rst index db45e973..fb643fb8 100644 --- a/Documentation/btrfstune.rst +++ b/Documentation/btrfstune.rst @@ -15,8 +15,8 @@ parameters. The filesystem must be unmounted. The common use case is to enable features that were not enabled at mkfs time. Please make sure that you have kernel support for the features. You can find a complete list of features and kernel version of their introduction at -https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature . Also, the -manual page :doc:`mkfs.btrfs(8)` contains more details about the features. +:doc:`Feature by version` page. Also, the manual page +:doc:`mkfs.btrfs(8)` contains more details about the features. Some of the features could be also enabled on a mounted filesystem by other means. Please refer to the *FILESYSTEM FEATURES* in :doc:`btrfs(5)`. @@ -81,7 +81,8 @@ OPTIONS Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. A seeding filesystem is forced to be mounted read-only. A new device can be added to the filesystem and will capture all writes - keeping the seeding device intact. See also section *SEEDING DEVICE* + keeping the seeding device intact. See also section + :ref:`SEEDING DEVICE` in :doc:`btrfs(5)`. .. warning:: @@ -113,7 +114,7 @@ OPTIONS .. warning:: Cancelling or interrupting a UUID change operation will make the filesystem temporarily unmountable. To fix it, rerun - *btrfstune -u* and let it complete. + :command:`btrfstune -u` and let it complete. -x (since kernel: 3.10) diff --git a/Documentation/ch-balance-filters.rst b/Documentation/ch-balance-filters.rst index 2b2dc5ea..3c7b7a92 100644 --- a/Documentation/ch-balance-filters.rst +++ b/Documentation/ch-balance-filters.rst @@ -80,4 +80,5 @@ Profile names, used in *profiles* and *convert* are one of: *raid0*, *raid1*, *raid1c3*, *raid1c4*, *raid10*, *raid5*, *raid6*, *dup*, *single*. The mixed data/metadata profiles can be converted in the same way, but it's conversion between mixed and non-mixed is not implemented. For the constraints of the -profiles please refer to :doc:`mkfs.btrfs(8)`, section *PROFILES*. +profiles please refer to :doc:`mkfs.btrfs(8)` section +:ref:`PROFILES`. diff --git a/Documentation/ch-balance-intro.rst b/Documentation/ch-balance-intro.rst index 8269ca5a..c4fabace 100644 --- a/Documentation/ch-balance-intro.rst +++ b/Documentation/ch-balance-intro.rst @@ -1,6 +1,7 @@ The primary purpose of the balance feature is to spread block groups across all devices so they match constraints defined by the respective profiles. See -:doc:`mkfs.btrfs(8)` section *PROFILES* for more details. +:doc:`mkfs.btrfs(8)` section :ref:`PROFILES` +for more details. The scope of the balancing process can be further tuned by use of filters that can select the block groups to process. Balance works only on a mounted filesystem. Extent sharing is preserved and reflinks are not broken. diff --git a/Documentation/ch-bootloaders.rst b/Documentation/ch-bootloaders.rst index 635a8655..4fd6102a 100644 --- a/Documentation/ch-bootloaders.rst +++ b/Documentation/ch-bootloaders.rst @@ -1,7 +1,7 @@ GRUB2 (https://www.gnu.org/software/grub) has the most advanced support of booting from BTRFS with respect to features. -U-boot (https://www.denx.de/wiki/U-Boot/) has decent support for booting but +U-Boot (https://www.denx.de/wiki/U-Boot/) has decent support for booting but not all BTRFS features are implemented, check the documentation. In general, the first 1MiB on each device is unused with the exception of diff --git a/Documentation/ch-compression.rst b/Documentation/ch-compression.rst index 9578a47f..805b29ef 100644 --- a/Documentation/ch-compression.rst +++ b/Documentation/ch-compression.rst @@ -38,7 +38,8 @@ How to enable compression Typically the compression can be enabled on the whole filesystem, specified for the mount point. Note that the compression mount options are shared among all mounts of the same filesystem, either bind mounts or subvolume mounts. -Please refer to section *MOUNT OPTIONS*. +Please refer to :doc:`btrfs(5)` section +:ref:`MOUNT OPTIONS`. .. code-block:: shell diff --git a/Documentation/ch-flexibility.rst b/Documentation/ch-flexibility.rst index 2cfc7a22..5208ebfa 100644 --- a/Documentation/ch-flexibility.rst +++ b/Documentation/ch-flexibility.rst @@ -8,7 +8,7 @@ or enabling some features on-the-fly. * **block group profile change on-the-fly** -- the block group profiles can be changed on a mounted filesystem by running the balance operation and - specifying the conversion filters (see :doc:`balance`.) + specifying the conversion filters (see :doc:`balance`) * **resize** -- the space occupied by the filesystem on each device can be resized up (grow) or down (shrink) as long as the amount of data can be still diff --git a/Documentation/ch-fs-limits.rst b/Documentation/ch-fs-limits.rst index a96c8301..87d8a380 100644 --- a/Documentation/ch-fs-limits.rst +++ b/Documentation/ch-fs-limits.rst @@ -21,7 +21,7 @@ maximum number of inodes inode numbers minimum number: 256 (for subvolumes), regular files and directories: 257, - maximum number: (2\:sup:`64` - 256) + maximum number: (2\ :sup:`64` - 256) The inode numbers that can be assigned to user created files are from the whole 64bit space except first 256 and last 256 in that range that @@ -42,7 +42,7 @@ maximum number of subvolumes maximum number of hardlinks of a file in a directory 65536 when the *extref* feature is turned on during mkfs (default), roughly - 100 otherwise + 100 otherwise and depends on file name length that fits into one metadata node minimum filesystem size the minimal size of each device depends on the *mixed-bg* feature, without that diff --git a/Documentation/ch-sysfs.rst b/Documentation/ch-sysfs.rst index 86a79326..3d3179a1 100644 --- a/Documentation/ch-sysfs.rst +++ b/Documentation/ch-sysfs.rst @@ -1,6 +1,6 @@ Btrfs has a sysfs interface to provide extra knobs. -The top level path is `/sys/fs/btrfs/`, and the main directory layout is the following: +The top level path is :file:`/sys/fs/btrfs/`, and the main directory layout is the following: ============================= =================================== ======== Relative Path Description Version @@ -16,16 +16,16 @@ features/ All supported features 3.14+ /discard/ Discard stats and tunables 6.1+ ============================= =================================== ======== -For `/sys/fs/btrfs/features/` directory, each file means a supported feature +For :file:`/sys/fs/btrfs/features/` directory, each file means a supported feature for the current kernel. -For `/sys/fs/btrfs//features/` directory, each file means an enabled +For :file:`/sys/fs/btrfs//features/` directory, each file means an enabled feature for the mounted filesystem. -The features shares the same name in section *FILESYSTEM FEATURES*. +The features shares the same name in section +:ref:`FILESYSTEM FEATURES`. - -Files in `/sys/fs/btrfs//` directory are: +Files in :file:`/sys/fs/btrfs//` directory are: bg_reclaim_threshold (RW, since: 5.19) @@ -37,7 +37,8 @@ checksum (RO, since: 5.5) The checksum used for the mounted filesystem. - This includes both the checksum type (see section *CHECKSUM ALGORITHMS*) + This includes both the checksum type (see section + :ref:`CHECKSUM ALGORITHMS`) and the implemented driver (mostly shows if it's hardware accelerated). clone_alignment @@ -58,7 +59,9 @@ exclusive_operation (RO, since: 5.10) Shows the running exclusive operation. - Check section *FILESYSTEM EXCLUSIVE OPERATIONS* for details. + Check section + :ref:`FILESYSTEM EXCLUSIVE OPERATIONS` + for details. generation (RO, since: 5.11) @@ -100,7 +103,7 @@ sectorsize Shows the sectorsize of the mounted filesystem. -Files and directories in `/sys/fs/btrfs//allocations` directory are: +Files and directories in :file:`/sys/fs/btrfs//allocations` directory are: global_rsv_reserved (RO, since: 3.14) @@ -118,7 +121,7 @@ global_rsv_size Space info accounting for the 3 chunk types. Mostly for debug purposes. -Files in `/sys/fs/btrfs//allocations/{data,metadata,system}` directory are: +Files in :file:`/sys/fs/btrfs//allocations/{data,metadata,system}` directory are: bg_reclaim_threshold (RW, since: 5.19) @@ -133,7 +136,7 @@ chunk_size Shows the chunk size. Can be changed for data and metadata. Cannot be set for zoned devices. -Files in `/sys/fs/btrfs//devinfo/` directory are: +Files in :file:`/sys/fs/btrfs//devinfo/` directory are: error_stats: (RO, since: 5.14) @@ -175,7 +178,7 @@ writeable Show if the device is writeable. -Files in `/sys/fs/btrfs//qgroups/` directory are: +Files in :file:`/sys/fs/btrfs//qgroups/` directory are: enabled (RO, since: 6.1) @@ -206,7 +209,7 @@ drop_subtree_threshold Lower value can reduce qgroup workload, at the cost of extra qgroup rescan to re-calculate the numbers. -Files in `/sys/fs/btrfs//_/` directory are: +Files in :file:`/sys/fs/btrfs//_/` directory are: exclusive (RO, since: 5.9) @@ -249,7 +252,7 @@ rsv_meta_prealloc Shows the reserved bytes for preallocated metadata. -Files in `/sys/fs/btrfs//discard/` directory are: +Files in :file:`/sys/fs/btrfs//discard/` directory are: discardable_bytes (RO, since: 6.1) diff --git a/Documentation/dev/Developer-s-FAQ.rst b/Documentation/dev/Developer-s-FAQ.rst index 8ef27660..5a01ca91 100644 --- a/Documentation/dev/Developer-s-FAQ.rst +++ b/Documentation/dev/Developer-s-FAQ.rst @@ -482,6 +482,8 @@ You may also read a perspective from Linux Foundation that shares a similar view: https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/ +.. _devfaq-development-schedule: + Development schedule -------------------- diff --git a/Documentation/dev/dev-btrfs-design.rst b/Documentation/dev/dev-btrfs-design.rst index cc813ce2..c3a6d738 100644 --- a/Documentation/dev/dev-btrfs-design.rst +++ b/Documentation/dev/dev-btrfs-design.rst @@ -456,7 +456,7 @@ The Btrfs snapshotting implementation is based on the ideas he presented. Btrfsck -~~~~~~~ +------- The filesystem checking utility is a crucial tool, but it can be a major bottleneck in getting systems back online after something has gone diff --git a/Documentation/index.rst b/Documentation/index.rst index 0219f6d7..a26a52b5 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,9 +12,9 @@ Welcome to BTRFS documentation! man-index Administration Hardware - CHANGES Feature-by-version Kernel-by-version + CHANGES Contributors Glossary INSTALL diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst index f3cb6089..d1626f73 100644 --- a/Documentation/mkfs.btrfs.rst +++ b/Documentation/mkfs.btrfs.rst @@ -15,7 +15,8 @@ as well. Multiple devices are grouped by UUID of the filesystem. Before mounting such filesystem, the kernel module must know all the devices either via preceding execution of :command:`btrfs device scan` or using the *device* -mount option. See section *MULTIPLE DEVICES* for more details. +mount option. See section :ref:`MULTIPLE DEVICES` +for more details. The default block group profiles for data and metadata depend on number of devices and possibly other factors. It's recommended to use specific profiles @@ -35,14 +36,16 @@ OPTIONS --csum , --checksum Specify the checksum algorithm. Default is *crc32c*. Valid values are *crc32c*, *xxhash*, *sha256* or *blake2*. To mount such filesystem kernel must support the - checksums as well. See *CHECKSUM ALGORITHMS* in :doc:`btrfs(5)`. + checksums as well. See section :ref:`CHECKSUM ALGORITHMS` + in :doc:`btrfs(5)`. -d|--data Specify the profile for the data block groups. Valid values are *raid0*, *raid1*, *raid1c3*, *raid1c4*, *raid5*, *raid6*, *raid10* or *single* or *dup* (case does not matter). - See *DUP PROFILES ON A SINGLE DEVICE* for more details. + See section :ref:`DUP PROFILES ON A SINGLE DEVICE` + for more details. On multiple devices, the default was *raid0* until version 5.7, while it is *single* since version 5.8. You can still select *raid0* manually, but it was not @@ -62,7 +65,7 @@ OPTIONS .. note:: Up to version 5.14 there was a detection of a SSD device (more precisely if it's a rotational device, determined by the contents of file - */sys/block/DEV/queue/rotational*) that used to select *single*. This has + :file:`/sys/block/DEV/queue/rotational`) that used to select *single*. This has changed in version 5.15 to be always *dup*. Note that the rotational status can be arbitrarily set by the underlying block @@ -71,7 +74,8 @@ OPTIONS etc). It's recommended to always set the options *--data/--metadata* to avoid confusion and unexpected results. - See *DUP PROFILES ON A SINGLE DEVICE* for more details. + See section :ref:`DUP PROFILES ON A SINGLE DEVICE` + for more details. On multiple devices the default is *raid1*. @@ -154,8 +158,9 @@ OPTIONS A list of filesystem features turned on at mkfs time. Not all features are supported by old kernels. To disable a feature, prefix it with *^*. - See section *FILESYSTEM FEATURES* for more details. To see all available - features that :command:`mkfs.btrfs` supports run: + See section :ref:`FILESYSTEM FEATURES` + for more details. To see all available features that + :command:`mkfs.btrfs` supports run: .. code-block:: bash @@ -199,6 +204,8 @@ The default unit is *byte*. All size parameters accept suffixes in the 1024 base. The recognized suffixes are: *k*, *m*, *g*, *t*, *p*, *e*, both uppercase and lowercase. +.. _man-mkfs-multiple-devices: + MULTIPLE DEVICES ---------------- @@ -230,11 +237,13 @@ devices to scan at the time of mount. .. warning:: RAID5/6 has known problems and should not be used in production. +.. _man-mkfs-filesystem-features: + FILESYSTEM FEATURES ------------------- Features that can be enabled during creation time. See also :doc:`btrfs(5)` section -*FILESYSTEM FEATURES*. +:ref:`FILESYSTEM FEATURES`. mixed-bg (kernel support since 2.6.37) @@ -275,8 +284,9 @@ zoned (kernel support since 5.12) zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS devices, - see *ZONED MODE* in :doc:`btrfs(5)`, the mode is automatically selected when - a zoned device is detected + see :ref:`ZONED MODE` in + :doc:`btrfs(5)`, the mode is automatically selected when a + zoned device is detected quota (kernel support since 3.4) @@ -332,7 +342,9 @@ RAID profile when used in connection with block groups refers to the allocation strategy - and constraints, see the section *PROFILES* for more details + and constraints, see the section :ref:`PROFILES` for more details + +.. _man-mkfs-profiles: PROFILES -------- @@ -456,6 +468,8 @@ C1 QD PB D1 PD B2 PC PA ======== ======== ======== ======== +.. _man-mkfs-dup-profiles-on-a-single-device: + DUP PROFILES ON A SINGLE DEVICE ------------------------------- @@ -508,7 +522,7 @@ to be created and could end up in the following situation: # mkfs.btrfs -f -n 65536 /dev/loop0 btrfs-progs v3.19-rc2-405-g976307c - See http://btrfs.wiki.kernel.org for more information. + See https://btrfs.readthedocs.io for more information. Performing full device TRIM (512.00MiB) ... Label: (null) diff --git a/INSTALL b/INSTALL index 4f247998..8f8bf569 100644 --- a/INSTALL +++ b/INSTALL @@ -36,7 +36,6 @@ Generating documentation: - sphinx Please note that the package names may differ according to the distribution. -See https://btrfs.wiki.kernel.org/index.php/Btrfs_source_repositories#Dependencies . Building from sources @@ -122,4 +121,4 @@ versions on a 32bit host is recommended. References: * https://btrfs.readthedocs.io -* https://btrfs.wiki.kernel.org +* https://btrfs.wiki.kernel.org (outdated)