mirror of
https://github.com/kdave/btrfs-progs
synced 2024-12-17 20:05:24 +00:00
btrfs-progs: docs: fixups, references
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
7887e978ba
commit
d8172c2fbc
4
CHANGES
4
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
|
||||
|
||||
@ -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<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<Zoned-mode>`.
|
||||
|
||||
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
|
||||
<i>ref-verify</i>, 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
|
||||
|
||||
@ -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<mkfs-feature-skinny-metadata>` [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 <big>many</big> <small>BUG_ONs</small> <!-- a big thing! -->
|
||||
* 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<Deduplication>` (userspace tools required)
|
||||
* new mount option ''commit'' to set the commit interval
|
||||
* Lots of stability and bugfix patches
|
||||
|
||||
|
||||
@ -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<devfaq-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.
|
||||
|
||||
@ -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
|
||||
------------------
|
||||
|
||||
@ -41,7 +41,8 @@ OPTIONS
|
||||
-O|--features <feature1>[,<feature2>...]
|
||||
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<man-mkfs-filesystem-features>` of
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`.
|
||||
|
||||
To see all available features that btrfs-convert supports run:
|
||||
|
||||
@ -112,9 +112,9 @@ scan [options] [<device> [<device>...]]
|
||||
|
||||
stats [options] <path>|<device>
|
||||
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<man-device-device-stats>`
|
||||
for more information about the reported statistics and the meaning.
|
||||
|
||||
``Options``
|
||||
|
||||
@ -195,6 +195,8 @@ usage [options] <path> [<path>...]::
|
||||
|
||||
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
|
||||
-----------
|
||||
|
||||
@ -351,7 +351,7 @@ usage [options] <path> [<path>...]
|
||||
filesystem)
|
||||
* *Multiple profiles* -- what block group types (data, metadata) have
|
||||
more than one profile (single, raid1, ...), see :doc:`btrfs(5)<btrfs-man5>` section
|
||||
*FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES*.
|
||||
:ref:`FILESYSTEMS WITH MULTIPLE PROFILES<man-btrfs5-filesystem-with-multiple-profiles>`.
|
||||
|
||||
And on a zoned filesystem there are two more lines in the *Device* section:
|
||||
|
||||
|
||||
@ -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)<mkfs.btrfs>` section *FILESYSTEM FEATURES*):
|
||||
List of features (see also :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section
|
||||
:ref:`FILESYSTEM FEATURES<man-mkfs-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
|
||||
--------------
|
||||
|
||||
@ -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<man-quota-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
|
||||
---------------------------------
|
||||
|
||||
|
||||
@ -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<man-btrfs8-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<man-btrfs8-standalone-tools>`
|
||||
for more details.
|
||||
|
||||
For other topics (mount options, etc) please refer to the separate manual
|
||||
page :doc:`btrfs(5)<btrfs-man5>`.
|
||||
@ -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)<btrfs-subvolume>` for details.
|
||||
|
||||
.. _man-btrfs8-standalone-tools:
|
||||
|
||||
STANDALONE TOOLS
|
||||
----------------
|
||||
|
||||
|
||||
@ -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)<mkfs.btrfs>` contains more details about the features.
|
||||
:doc:`Feature by version<Feature-by-version>` page. Also, the manual page
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` 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)<btrfs-man5>`.
|
||||
@ -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<man-btrfs5-seeding-device>`
|
||||
in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
|
||||
.. 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)
|
||||
|
||||
@ -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)<mkfs.btrfs>`, section *PROFILES*.
|
||||
profiles please refer to :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section
|
||||
:ref:`PROFILES<man-mkfs-profiles>`.
|
||||
|
||||
@ -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)<mkfs.btrfs>` section *PROFILES* for more details.
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` section :ref:`PROFILES<man-mkfs-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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)<btrfs-man5>` section
|
||||
:ref:`MOUNT OPTIONS<man-btrfs5-mount-option>`.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@ -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<Balance>`.)
|
||||
specifying the conversion filters (see :doc:`balance<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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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+
|
||||
<UUID>/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/<UUID>/features/` directory, each file means an enabled
|
||||
For :file:`/sys/fs/btrfs/<UUID>/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<man-btrfs5-filesystem-features>`.
|
||||
|
||||
|
||||
Files in `/sys/fs/btrfs/<UUID>/` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/` 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<man-mkfs-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<man-btrfs5-fileysstem-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/<UUID>/allocations` directory are:
|
||||
Files and directories in :file:`/sys/fs/btrfs/<UUID>/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/<UUID>/allocations/{data,metadata,system}` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/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/<UUID>/devinfo/<DEVID>` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/devinfo/<DEVID>` directory are:
|
||||
|
||||
error_stats:
|
||||
(RO, since: 5.14)
|
||||
@ -175,7 +178,7 @@ writeable
|
||||
|
||||
Show if the device is writeable.
|
||||
|
||||
Files in `/sys/fs/btrfs/<UUID>/qgroups/` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/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/<UUID>/<LEVEL>_<ID>/` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/<LEVEL>_<ID>/` 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/<UUID>/discard/` directory are:
|
||||
Files in :file:`/sys/fs/btrfs/<UUID>/discard/` directory are:
|
||||
|
||||
discardable_bytes
|
||||
(RO, since: 6.1)
|
||||
|
||||
@ -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
|
||||
--------------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -12,9 +12,9 @@ Welcome to BTRFS documentation!
|
||||
man-index
|
||||
Administration
|
||||
Hardware
|
||||
CHANGES
|
||||
Feature-by-version
|
||||
Kernel-by-version
|
||||
CHANGES
|
||||
Contributors
|
||||
Glossary
|
||||
INSTALL
|
||||
|
||||
@ -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<man-mkfs-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 <type>, --checksum <type>
|
||||
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)<btrfs-man5>`.
|
||||
checksums as well. See section :ref:`CHECKSUM ALGORITHMS<man-mkfs-checksum-algorithms>`
|
||||
in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
|
||||
-d|--data <profile>
|
||||
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<man-mkfs-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<man-mkfs-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<man-mkfs-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)<btrfs-man5>` section
|
||||
*FILESYSTEM FEATURES*.
|
||||
:ref:`FILESYSTEM FEATURES<man-btrfs5-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)<btrfs-man5>`, the mode is automatically selected when
|
||||
a zoned device is detected
|
||||
see :ref:`ZONED MODE<man-btrfs5-zoned-mode>` in
|
||||
:doc:`btrfs(5)<btrfs-man5>`, 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<man-mkfs-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)
|
||||
|
||||
3
INSTALL
3
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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user