mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/kdave/btrfs-progs.git
synced 2024-11-23 12:14:24 +08:00
btrfs-progs: docs: formatting updates
- use :file: and :command: - simplify manual page references - add more web links - typo fixes - more cross-references Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
22cf63d8ee
commit
a0137082de
@ -1,7 +1,7 @@
|
||||
Administration
|
||||
==============
|
||||
|
||||
The main administration tool for BTRFS filesystems is :doc:`btrfs(8)<btrfs>`.
|
||||
The main administration tool for BTRFS filesystems is :doc:`btrfs`.
|
||||
Please refer to the manual pages of the subcommands for further documentation.
|
||||
|
||||
Mount options
|
||||
|
||||
@ -21,4 +21,4 @@ a command if available:
|
||||
- query/set a subset of features on a mounted filesystem
|
||||
|
||||
Programming documentaion of the ioctls is in the manual page
|
||||
:doc:`btrfs-ioctl(2)<btrfs-ioctl>`.
|
||||
:doc:`btrfs-ioctl`.
|
||||
|
||||
@ -28,3 +28,4 @@ space layout and fragmentation.
|
||||
|
||||
Defragmentation can be started together with compression on the given range,
|
||||
and takes precedence over per-file compression property or mount options.
|
||||
See command :ref:`btrfs filesystem defrag<man-filesystem-cmd-defragment>`.
|
||||
|
||||
@ -26,8 +26,8 @@ There are some constraints:
|
||||
- works since 5.18
|
||||
- reflink requires source and target file that have the same status regarding
|
||||
NOCOW and checksums, for example if the source file is NOCOW (once created
|
||||
with the chattr +C attribute) then the above command won't work unless the
|
||||
with the :command:`chattr +C` attribute) then the above command won't work unless the
|
||||
target file is pre-created with the +C attribute as well, or the NOCOW
|
||||
attribute is inherited from the parent directory (chattr +C on the directory)
|
||||
attribute is inherited from the parent directory (:command:`chattr +C` on the directory)
|
||||
or if the whole filesystem is mounted with *-o nodatacow* that would create
|
||||
the NOCOW files by default
|
||||
|
||||
@ -32,6 +32,4 @@ Release:
|
||||
Post-release:
|
||||
|
||||
* write and send announcement mail to mailinglist
|
||||
* update wiki://Main_page#News
|
||||
* update wiki://Changelog#btrfs-progs
|
||||
* update title on IRC
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
Resize
|
||||
======
|
||||
|
||||
A BTRFS mounted filesystem can be resized after creation, grown or shrunk. On a
|
||||
multi device filesystem the space occupied on each device can be resized
|
||||
A mounted filesystem can be resized after creation, grown or shrunk. On a
|
||||
multi-device filesystem the space occupied on each device can be resized
|
||||
independently. Data that reside in the area that would be out of the new size
|
||||
are relocated to the remaining space below the limit, so this constrains the
|
||||
minimum size to which a filesystem can be shrunk.
|
||||
@ -10,3 +10,4 @@ minimum size to which a filesystem can be shrunk.
|
||||
Growing a filesystem is quick as it only needs to take note of the available
|
||||
space, while shrinking a filesystem needs to relocate potentially lots of data
|
||||
and this is IO intense. It is possible to shrink a filesystem in smaller steps.
|
||||
See :ref:`btrfs filesystem resize<man-filesystem-resize>` for more.
|
||||
|
||||
@ -20,4 +20,5 @@ The stream is a sequence of encoded commands that change e.g. file metadata
|
||||
(owner, permissions, extended attributes), data extents (create, clone,
|
||||
truncate), whole file operations (rename, delete). The stream can be sent over
|
||||
network, piped directly to the receive command or saved to a file. Each command
|
||||
in the stream is protected by a CRC32C checksum.
|
||||
in the stream is protected by a CRC32C checksum. See :doc:`btrfs-send`
|
||||
and :doc:`btrfs-receive` for more.
|
||||
|
||||
@ -306,7 +306,7 @@ Defrag
|
||||
|
||||
The data affected by the defragmentation process will be newly written
|
||||
and will consume new space, the links to the original extents will not
|
||||
be kept. See also :doc:`btrfs-filesystem<btrfs-filesystem>` . Though
|
||||
be kept. See also :doc:`btrfs-filesystem` . Though
|
||||
autodefrag affects newly written data, it can read a few adjacent blocks
|
||||
(up to 64KiB) and write the contiguous extent to a new location. The
|
||||
adjacent blocks will be unshared. This happens on a smaller scale than
|
||||
|
||||
@ -37,5 +37,5 @@ other factors affecting the memory cells. The device itself could internally
|
||||
relocate the data, however this leads to unexpected performance drop. Running
|
||||
trim periodically could prevent that too.
|
||||
|
||||
When a filesystem is created by :doc:`mkfs.btrfs(8)<mkfs.btrfs>` and is capable
|
||||
When a filesystem is created by :doc:`mkfs.btrfs` and is capable
|
||||
of trim, then it's by default performed on all devices.
|
||||
|
||||
@ -56,11 +56,11 @@ start [options] <path>
|
||||
``Options``
|
||||
|
||||
-d[<filters>]
|
||||
act on data block groups, see *FILTERS* section for details about *filters*
|
||||
act on data block groups, see section :ref:`FILTERS<man-balance-filters>` for details about *filters*
|
||||
-m[<filters>]
|
||||
act on metadata chunks, see *FILTERS* section for details about *filters*
|
||||
act on metadata chunks, see :ref:`FILTERS<man-balance-filters>` for details about *filters*
|
||||
-s[<filters>]
|
||||
act on system chunks (requires *-f*), see *FILTERS* section for details about *filters*.
|
||||
act on system chunks (requires *-f*), see :ref:`FILTERS<man-balance-filters>` for details about *filters*.
|
||||
|
||||
-f
|
||||
force a reduction of metadata integrity, e.g. when going from *raid1* to
|
||||
@ -84,6 +84,8 @@ status [-v] <path>
|
||||
-v
|
||||
(deprecated) alias for global *-v* option
|
||||
|
||||
.. _man-balance-filters:
|
||||
|
||||
FILTERS
|
||||
-------
|
||||
|
||||
@ -127,7 +129,7 @@ EXAMPLES
|
||||
--------
|
||||
|
||||
A more comprehensive example when going from one to multiple devices, and back,
|
||||
can be found in section *TYPICAL USECASES* of :doc:`btrfs-device(8)<btrfs-device>`.
|
||||
can be found in section *TYPICAL USECASES* of :doc:`btrfs-device`.
|
||||
|
||||
MAKING BLOCK GROUP LAYOUT MORE COMPACT
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -268,5 +270,5 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`btrfs-device(8)<btrfs-device>`
|
||||
:doc:`mkfs.btrfs`,
|
||||
:doc:`btrfs-device`
|
||||
|
||||
@ -12,7 +12,7 @@ DESCRIPTION
|
||||
The filesystem checker is used to verify structural integrity of a filesystem
|
||||
and attempt to repair it if requested. It is recommended to unmount the
|
||||
filesystem prior to running the check, but it is possible to start checking a
|
||||
mounted filesystem (see *--force*).
|
||||
mounted filesystem (see :ref:`--force<man-check-option-force>`).
|
||||
|
||||
By default, :command:`btrfs check` will not modify the device but you can reaffirm that
|
||||
by the option *--readonly*.
|
||||
@ -128,6 +128,8 @@ DANGEROUS OPTIONS
|
||||
*lowmem* mode does not work with *--repair* yet, and is still considered
|
||||
experimental.
|
||||
|
||||
.. _man-check-option-force:
|
||||
|
||||
--force
|
||||
allow work on a mounted filesystem and skip mount checks. Note that
|
||||
this should work fine on a quiescent or read-only mounted filesystem
|
||||
@ -157,6 +159,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`btrfs-scrub(8)<btrfs-scrub>`,
|
||||
:doc:`btrfs-rescue(8)<btrfs-rescue>`
|
||||
:doc:`mkfs.btrfs`,
|
||||
:doc:`btrfs-scrub`,
|
||||
:doc:`btrfs-rescue`
|
||||
|
||||
@ -31,7 +31,7 @@ OPTIONS
|
||||
set filesystem nodesize, the tree block size in which btrfs stores its metadata.
|
||||
The default value is 16KiB (16384) or the page size, whichever is bigger.
|
||||
Must be a multiple of the sectorsize, but not larger than 65536. See
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` for more details.
|
||||
:doc:`mkfs.btrfs` for more details.
|
||||
-r|--rollback
|
||||
rollback to the original ext2/3/4 filesystem if possible
|
||||
-l|--label <LABEL>
|
||||
@ -43,7 +43,7 @@ OPTIONS
|
||||
are supported by old kernels. To disable a feature, prefix it with *^*.
|
||||
Description of the features is in section
|
||||
:ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>` of
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`.
|
||||
:doc:`mkfs.btrfs`.
|
||||
|
||||
To see all available features that btrfs-convert supports run:
|
||||
|
||||
@ -73,4 +73,4 @@ If any problems happened, 1 will be returned.
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -47,7 +47,7 @@ remove [options] <device>|<devid> [<device>|<devid>...] <path>
|
||||
Device removal must satisfy the profile constraints, otherwise the command
|
||||
fails. The filesystem must be converted to profile(s) that would allow the
|
||||
removal. This can typically happen when going down from 2 devices to 1 and
|
||||
using the RAID1 profile. See the section *TYPICAL USECASES*.
|
||||
using the RAID1 profile. See the section :ref:`Typical use cases<man-device-typical-use-cases>`.
|
||||
|
||||
The operation can take long as it needs to move all data from the device.
|
||||
|
||||
@ -76,7 +76,7 @@ delete <device>|<devid> [<device>|<devid>...] <path>
|
||||
|
||||
replace <command> [options] <path>
|
||||
Alias of whole command group *btrfs replace* for convenience. See
|
||||
:doc:`btrfs-replace(8)<btrfs-replace>`.
|
||||
:doc:`btrfs-replace`.
|
||||
|
||||
ready <device>
|
||||
Wait until all devices of a multiple-device filesystem are scanned and
|
||||
@ -99,7 +99,7 @@ scan [options] [<device> [<device>...]]
|
||||
The command can be run repeatedly. Devices that have been already registered
|
||||
remain as such. Reloading the kernel module will drop this information. There's
|
||||
an alternative way of mounting multiple-device filesystem without the need for
|
||||
prior scanning. See the mount option *device*.
|
||||
prior scanning. See the mount option :ref:`device<mount-option-device>`.
|
||||
|
||||
``Options``
|
||||
|
||||
@ -250,7 +250,7 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-balance(8)<btrfs-balance>`
|
||||
:doc:`btrfs-device(8)<btrfs-device>`,
|
||||
:doc:`btrfs-replace(8)<btrfs-replace>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`btrfs-balance`
|
||||
:doc:`btrfs-device`,
|
||||
:doc:`btrfs-replace`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -78,6 +78,8 @@ df [options] <path>
|
||||
|
||||
If conflicting options are passed, the last one takes precedence.
|
||||
|
||||
.. _man-filesystem-cmd-defragment:
|
||||
|
||||
defragment [options] <file>|<dir> [<file>|<dir>...]
|
||||
Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer.
|
||||
|
||||
@ -215,6 +217,8 @@ mkswapfile [-s size] file
|
||||
specify UUID to use, or a special value: clear (all zeros), random,
|
||||
time (time-based random)
|
||||
|
||||
.. _man-filesystem-resize:
|
||||
|
||||
resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
|
||||
Resize a mounted filesystem identified by *path*. A particular device
|
||||
can be resized by specifying a *devid*.
|
||||
@ -268,8 +272,8 @@ show [options] [<path>|<uuid>|<device>|<label>]
|
||||
-m|--mounted
|
||||
probe kernel for mounted BTRFS filesystems
|
||||
-d|--all-devices
|
||||
scan all devices under */dev*, otherwise the devices list is extracted from the
|
||||
*/proc/partitions* file. This is a fallback option if there's no device node
|
||||
scan all devices under :file:`/dev`, otherwise the devices list is extracted from the
|
||||
:file:`/proc/partitions` file. This is a fallback option if there's no device node
|
||||
manager (like udev) available in the system.
|
||||
|
||||
--raw
|
||||
@ -350,7 +354,7 @@ usage [options] <path> [<path>...]
|
||||
block reserve, used for emergency purposes (like deletion on a full
|
||||
filesystem)
|
||||
* *Multiple profiles* -- what block group types (data, metadata) have
|
||||
more than one profile (single, raid1, ...), see :doc:`btrfs(5)<btrfs-man5>` section
|
||||
more than one profile (single, raid1, ...), see :doc:`btrfs-man5` section
|
||||
: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:
|
||||
@ -419,7 +423,7 @@ EXAMPLES
|
||||
|
||||
**$ btrfs filesystem defrag -v -r dir/**
|
||||
|
||||
Recursively defragment files under *dir/*, print files as they are processed.
|
||||
Recursively defragment files under :file:`dir/`, print files as they are processed.
|
||||
The file names will be printed in batches, similarly the amount of data triggered
|
||||
by defragmentation will be proportional to last N printed files. The system dirty
|
||||
memory throttling will slow down the defragmentation but there can still be a lot
|
||||
@ -427,18 +431,18 @@ of IO load and the system may stall for a moment.
|
||||
|
||||
**$ btrfs filesystem defrag -v -r -f dir/**
|
||||
|
||||
Recursively defragment files under *dir/*, be verbose and wait until all blocks
|
||||
Recursively defragment files under :file:`dir/`, be verbose and wait until all blocks
|
||||
are flushed before processing next file. You can note slower progress of the
|
||||
output and lower IO load (proportional to currently defragmented file).
|
||||
|
||||
**$ btrfs filesystem defrag -v -r -f -clzo dir/**
|
||||
|
||||
Recursively defragment files under *dir/*, be verbose, wait until all blocks are
|
||||
Recursively defragment files under :file:`dir/`, be verbose, wait until all blocks are
|
||||
flushed and force file compression.
|
||||
|
||||
**$ btrfs filesystem defrag -v -r -t 64M dir/**
|
||||
|
||||
Recursively defragment files under *dir/*, be verbose and try to merge extents
|
||||
Recursively defragment files under :file:`dir/`, be verbose and try to merge extents
|
||||
to be about 64MiB. As stated above, the success rate depends on actual free
|
||||
space fragmentation and the final result is not guaranteed to meet the target
|
||||
even if run repeatedly.
|
||||
@ -479,5 +483,5 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-subvolume`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -33,4 +33,4 @@ If any problems happened, 1 will be returned.
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -62,4 +62,4 @@ If any problems happened, 1 will be returned.
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -165,6 +165,8 @@ logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>
|
||||
-v
|
||||
(deprecated) alias for global *-v* option
|
||||
|
||||
.. _man-inspect-map-swapfile:
|
||||
|
||||
map-swapfile [options] <file>
|
||||
(needs root privileges)
|
||||
|
||||
@ -194,6 +196,8 @@ min-dev-size [options] <path>
|
||||
--id <id>
|
||||
specify the device *id* to query, default is 1 if this option is not used
|
||||
|
||||
.. _man-inspect-rootid:
|
||||
|
||||
rootid <path>
|
||||
for a given file or directory, return the containing tree root id, but for a
|
||||
subvolume itself return its own tree id (i.e. subvol id)
|
||||
@ -239,4 +243,4 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
btrfs-man5(5)
|
||||
=============
|
||||
btrfs(5)
|
||||
========
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
@ -23,7 +23,7 @@ tools. Currently covers:
|
||||
#. RAID56 status and recommended practices
|
||||
#. storage model, hardware considerations
|
||||
|
||||
.. _man-btrfs5-mount-option:
|
||||
.. _man-btrfs5-mount-options:
|
||||
|
||||
MOUNT OPTIONS
|
||||
-------------
|
||||
@ -43,26 +43,26 @@ There are several classes and the respective tools to manage the features:
|
||||
|
||||
at mkfs time only
|
||||
This is namely for core structures, like the b-tree nodesize or checksum
|
||||
algorithm, see :doc:`mkfs.btrfs(8)<mkfs.btrfs>` for more details.
|
||||
algorithm, see :doc:`mkfs.btrfs` for more details.
|
||||
|
||||
after mkfs, on an unmounted filesystem
|
||||
Features that may optimize internal structures or add new structures to support
|
||||
new functionality, see :doc:`btrfstune(8)<btrfstune>`. The command
|
||||
new functionality, see :doc:`btrfstune`. The command
|
||||
:command:`btrfs inspect-internal dump-super /dev/sdx`
|
||||
will dump a superblock, you can map the value of
|
||||
*incompat_flags* to the features listed below
|
||||
|
||||
after mkfs, on a mounted filesystem
|
||||
The features of a filesystem (with a given UUID) are listed in
|
||||
*/sys/fs/btrfs/UUID/features/*, one file per feature. The status is stored
|
||||
:file:`/sys/fs/btrfs/UUID/features/`, one file per feature. The status is stored
|
||||
inside the file. The value *1* is for enabled and active, while *0* means the
|
||||
feature was enabled at mount time but turned off afterwards.
|
||||
|
||||
Whether a particular feature can be turned on a mounted filesystem can be found
|
||||
in the directory */sys/fs/btrfs/features/*, one file per feature. The value *1*
|
||||
in the directory :file:`/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
|
||||
List of features (see also :doc:`mkfs.btrfs` section
|
||||
:ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>`):
|
||||
|
||||
big_metadata
|
||||
@ -111,7 +111,7 @@ metadata_uuid
|
||||
|
||||
the main filesystem UUID is the metadata_uuid, which stores the new UUID only
|
||||
in the superblock while all metadata blocks still have the UUID set at mkfs
|
||||
time, see :doc:`btrfstune(8)<btrfstune>` for more
|
||||
time, see :doc:`btrfstune` for more
|
||||
|
||||
mixed_backref
|
||||
(since: 2.6.31)
|
||||
@ -167,7 +167,7 @@ supported_checksums
|
||||
|
||||
list of checksum algorithms supported by the kernel module, the respective
|
||||
modules or built-in implementing the algorithms need to be present to mount
|
||||
the filesystem, see *CHECKSUM ALGORITHMS*
|
||||
the filesystem, see section :ref:`CHECKSUM ALGORITHMS<man-mkfs-checksum-algorithms>`.
|
||||
|
||||
supported_sectorsizes
|
||||
(since: 5.13)
|
||||
@ -179,14 +179,14 @@ supported_rescue_options
|
||||
(since: 5.11)
|
||||
|
||||
list of values for the mount option *rescue* that are supported by the running
|
||||
kernel, see :doc:`btrfs(5)<btrfs-man5>`
|
||||
kernel, see :doc:`btrfs-man5`
|
||||
|
||||
zoned
|
||||
(since: 5.12)
|
||||
|
||||
zoned mode is allocation/write friendly to host-managed zoned devices,
|
||||
allocation space is partitioned into fixed-size zones that must be updated
|
||||
sequentially, see *ZONED MODE*
|
||||
sequentially, see section :ref:`ZONED MODE<man-btrfs5-zoned-mode>`
|
||||
|
||||
SWAPFILE SUPPORT
|
||||
----------------
|
||||
@ -220,7 +220,7 @@ in parallel. Attempt to start one while another is running will fail (see
|
||||
exceptions below).
|
||||
|
||||
Since kernel 5.10 the currently running operation can be obtained from
|
||||
*/sys/fs/UUID/exclusive_operation* with following values and operations:
|
||||
:file:`/sys/fs/UUID/exclusive_operation` with following values and operations:
|
||||
|
||||
* balance
|
||||
* balance paused (since 5.17)
|
||||
@ -264,8 +264,8 @@ ZONED MODE
|
||||
CONTROL DEVICE
|
||||
--------------
|
||||
|
||||
There's a character special device */dev/btrfs-control* with major and minor
|
||||
numbers 10 and 234 (the device can be found under the 'misc' category).
|
||||
There's a character special device :file:`/dev/btrfs-control` with major and minor
|
||||
numbers 10 and 234 (the device can be found under the *misc* category).
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -279,7 +279,7 @@ filesystem module:
|
||||
automatically) and register them with the kernel module
|
||||
* similar to scan, but also wait until the device scanning process is finished
|
||||
for a given filesystem
|
||||
* get the supported features (can be also found under */sys/fs/btrfs/features*)
|
||||
* get the supported features (can be also found under :file:`/sys/fs/btrfs/features`)
|
||||
|
||||
The device is created when btrfs is initialized, either as a module or a
|
||||
built-in functionality and makes sense only in connection with that. Running
|
||||
@ -311,7 +311,7 @@ FILESYSTEM WITH MULTIPLE PROFILES
|
||||
|
||||
It is possible that a btrfs filesystem contains multiple block group profiles
|
||||
of the same type. This could happen when a profile conversion using balance
|
||||
filters is interrupted (see :doc:`btrfs-balance(8)<btrfs-balance>`). Some
|
||||
filters is interrupted (see :doc:`btrfs-balance`). Some
|
||||
:command:`btrfs` commands perform
|
||||
a test to detect this kind of condition and print a warning like this:
|
||||
|
||||
@ -441,10 +441,10 @@ SEE ALSO
|
||||
--------
|
||||
|
||||
``acl(5)``,
|
||||
:doc:`btrfs(8)<btrfs>`,
|
||||
:doc:`btrfs`,
|
||||
``chattr(1)``,
|
||||
``fstrim(8)``,
|
||||
``ioctl(2)``,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`mkfs.btrfs`,
|
||||
``mount(8)``,
|
||||
``swapon(8)``
|
||||
|
||||
@ -35,4 +35,4 @@ If any problems happened, 1 will be returned.
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -54,7 +54,7 @@ Subvolume properties
|
||||
|
||||
ro
|
||||
read-only flag of subvolume: true or false. Please also see section *SUBVOLUME FLAGS*
|
||||
in :doc:`btrfs-subvolume(8)<btrfs-subvolume>` for possible implications regarding incremental send.
|
||||
in :doc:`btrfs-subvolume` for possible implications regarding incremental send.
|
||||
|
||||
Filesystem properties
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -122,6 +122,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`mkfs.btrfs`,
|
||||
``lsattr(1)``,
|
||||
``chattr(1)``
|
||||
|
||||
@ -175,7 +175,7 @@ EXAMPLES
|
||||
Make a parent group that has two quota group children
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Given the following filesystem mounted at `/mnt/my-vault`
|
||||
Given the following filesystem mounted at :file:`/mnt/my-vault`
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -234,6 +234,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-quota(8)<btrfs-quota>`,
|
||||
:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`btrfs-quota`,
|
||||
:doc:`btrfs-subvolume`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -11,7 +11,7 @@ DESCRIPTION
|
||||
|
||||
The commands under :command:`btrfs quota` are used to affect the global status of quotas
|
||||
of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
|
||||
:doc:`btrfs-qgroup(8)<btrfs-qgroup>`.
|
||||
:doc:`btrfs-qgroup`.
|
||||
|
||||
.. note::
|
||||
Qgroups are different than the traditional user quotas and designed
|
||||
@ -77,6 +77,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-qgroup(8)<btrfs-qgroup>`,
|
||||
:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-qgroup`,
|
||||
:doc:`btrfs-subvolume`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -53,13 +53,13 @@ A subvolume is made read-only after the receiving process finishes successfully
|
||||
-m <ROOTMOUNT>
|
||||
the root mount point of the destination filesystem
|
||||
|
||||
By default the mount point is searched in */proc/self/mounts*.
|
||||
If */proc* is not accessible, e.g. in a chroot environment, use this option to
|
||||
By default the mount point is searched in :file:/proc/self/mounts`.
|
||||
If :file:`/proc` is not accessible, e.g. in a chroot environment, use this option to
|
||||
tell us where this filesystem is mounted.
|
||||
|
||||
--force-decompress
|
||||
if the stream contains compressed data (see *--compressed-data* in
|
||||
:doc:`btrfs-send(8)<btrfs-send>`), always decompress it instead of writing it with
|
||||
:doc:`btrfs-send`), always decompress it instead of writing it with
|
||||
encoded I/O
|
||||
|
||||
--dump
|
||||
@ -117,5 +117,5 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-send(8)<btrfs-send>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-send`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -58,7 +58,7 @@ start [options] <srcdev>|<devid> <targetdev> <path>
|
||||
-K|--nodiscard
|
||||
Do not perform whole device TRIM operation on devices that are capable of that.
|
||||
This does not affect discard/trim operation when the filesystem is mounted.
|
||||
Please see the mount option *discard* for that in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
Please see the mount option *discard* for that in :doc:`btrfs-man5`.
|
||||
|
||||
status [-1] <mount_point>
|
||||
Print status and progress information of a running device replace operation.
|
||||
@ -76,7 +76,7 @@ EXAMPLES
|
||||
Replacing an online drive with a bigger one
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Given the following filesystem mounted at `/mnt/my-vault`
|
||||
Given the following filesystem mounted at :file:`/mnt/my-vault`
|
||||
|
||||
|
||||
.. code-block:: none
|
||||
@ -86,8 +86,8 @@ Given the following filesystem mounted at `/mnt/my-vault`
|
||||
devid 1 size 1TiB used 500.00GiB path /dev/sda
|
||||
devid 2 size 1TiB used 500.00GiB path /dev/sdb
|
||||
|
||||
In order to replace */dev/sda* (*devid 1*) with a bigger drive located at
|
||||
*/dev/sdc* you would run the following:
|
||||
In order to replace :file:`/dev/sda` (*devid 1*) with a bigger drive located at
|
||||
:file:`/dev/sdc` you would run the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -99,7 +99,7 @@ You can monitor progress via:
|
||||
|
||||
btrfs replace status /mnt/my-vault/
|
||||
|
||||
After the replacement is complete, as per the docs at :doc:`btrfs-filesystem(8)<btrfs-filesystem>` in
|
||||
After the replacement is complete, as per the docs at :doc:`btrfs-filesystem` in
|
||||
order to use the entire storage space of the new drive you need to run:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -121,6 +121,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-device(8)<btrfs-device>`,
|
||||
:doc:`btrfs-filesystem(8)<btrfs-filesystem>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-device`,
|
||||
:doc:`btrfs-filesystem`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -119,6 +119,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-check(8)<btrfs-check>`,
|
||||
:doc:`btrfs-scrub(8)<btrfs-scrub>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-check`,
|
||||
:doc:`btrfs-scrub`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -14,7 +14,7 @@ restore them into *path* or just list the subvolume tree roots. The filesystem
|
||||
image is not modified.
|
||||
|
||||
If the filesystem is damaged and cannot be repaired by the other tools
|
||||
(:doc:`btrfs-check(8)<btrfs-check>` or :doc:`btrfs-rescue(8)<btrfs-rescue>`),
|
||||
(:doc:`btrfs-check` or :doc:`btrfs-rescue`),
|
||||
:command:`btrfs restore` could be used to
|
||||
retrieve file data, as far as the metadata are readable. The checks done by
|
||||
restore are less strict and the process is usually able to get far enough to
|
||||
@ -28,12 +28,6 @@ options to extend the set of restored metadata.
|
||||
For images with damaged tree structures, there are several options to point the
|
||||
process to some spare copy.
|
||||
|
||||
.. note::
|
||||
It is recommended to read the following btrfs wiki page if your data is
|
||||
not salvaged with default option:
|
||||
|
||||
https://btrfs.wiki.kernel.org/index.php/Restore
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
@ -112,6 +106,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-check(8)<btrfs-check>`,
|
||||
:doc:`btrfs-rescue(8)<btrfs-rescue>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-check`,
|
||||
:doc:`btrfs-rescue`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -34,6 +34,8 @@ resume [-BdqrR] <path>|<device>
|
||||
|
||||
see :command:`scrub start`.
|
||||
|
||||
.. _man-scrub-start:
|
||||
|
||||
start [-BdrRf] <path>|<device>
|
||||
Start a scrub on all devices of the mounted filesystem identified by
|
||||
*path* or on a single *device*. If a scrub is already running, the new
|
||||
@ -166,4 +168,4 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -43,4 +43,4 @@ OPTIONS
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs(8)<btrfs>`
|
||||
:doc:`btrfs`
|
||||
|
||||
@ -35,13 +35,13 @@ the clone sources.
|
||||
You must not specify clone sources unless you guarantee that these snapshots
|
||||
are exactly in the same state on both sides--both for the sender and the
|
||||
receiver. For implications of changed read-write status of a received snapshot
|
||||
please see section *SUBVOLUME FLAGS* in :doc:`btrfs-subvolume(8)<btrfs-subvolume>`.
|
||||
please see section *SUBVOLUME FLAGS* in :doc:`btrfs-subvolume`.
|
||||
|
||||
``Options``
|
||||
|
||||
-e
|
||||
if sending multiple subvolumes at once, use the new format and omit the
|
||||
'end cmd' marker in the stream separating the subvolumes
|
||||
*end cmd* marker in the stream separating the subvolumes
|
||||
|
||||
-p <parent>
|
||||
send an incremental stream from *parent* to *subvol*
|
||||
@ -113,6 +113,6 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-receive(8)<btrfs-receive>`,
|
||||
:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-receive`,
|
||||
:doc:`btrfs-subvolume`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -40,7 +40,7 @@ similar to a bind mount, and in fact the subvolume mount does exactly that.
|
||||
A freshly created filesystem is also a subvolume, called *top-level*,
|
||||
internally has an id 5. This subvolume cannot be removed or replaced by another
|
||||
subvolume. This is also the subvolume that will be mounted by default, unless
|
||||
the default subvolume has been changed (see subcommand *set-default*).
|
||||
the default subvolume has been changed (see subcommand :ref:`set-default<man-subvolume-set-default>`).
|
||||
|
||||
A snapshot is a subvolume like any other, with given initial content. By
|
||||
default, snapshots are created read-write. File modifications in a snapshot
|
||||
@ -68,12 +68,13 @@ delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid>
|
||||
there are more arguments to process.
|
||||
|
||||
If *--subvolid* is used, *path* must point to a btrfs filesystem. See
|
||||
:command:`btrfs subvolume list` or :command:`btrfs inspect-internal rootid`
|
||||
:ref:`btrfs subvolume list<man-subvolume-list>` or
|
||||
:ref:`btrfs inspect-internal rootid<man-inspect-rootid>`
|
||||
how to get the subvolume id.
|
||||
|
||||
The corresponding directory is removed instantly but the data blocks are
|
||||
removed later in the background. The command returns immediately. See
|
||||
:command:`btrfs subvolume sync` how to wait until the subvolume gets completely removed.
|
||||
:ref:`btrfs subvolume sync<man-subvolume-sync>` how to wait until the subvolume gets completely removed.
|
||||
|
||||
The deletion does not involve full transaction commit by default due to
|
||||
performance reasons. As a consequence, the subvolume may appear again after a
|
||||
@ -83,9 +84,11 @@ delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid>
|
||||
Deleting subvolume needs sufficient permissions, by default the owner
|
||||
cannot delete it unless it's enabled by a mount option
|
||||
*user_subvol_rm_allowed*, or deletion is run as root.
|
||||
The default subvolume (see :command:`btrfs subvolume set-default`) cannot be deleted and
|
||||
The default subvolume (see :ref:`btrfs subvolume set-default<man-subvolume-set-default>`)
|
||||
cannot be deleted and
|
||||
returns error (EPERM) and this is logged to the system log. A subvolume that's
|
||||
currently involved in send (see :command:`btrfs send`) also cannot be deleted until the
|
||||
currently involved in send (see :doc:`btrfs-send`)
|
||||
also cannot be deleted until the
|
||||
send is finished. This is also logged in the system log.
|
||||
|
||||
``Options``
|
||||
@ -110,6 +113,8 @@ get-default <path>
|
||||
|
||||
The output format is similar to :command:`subvolume list` command.
|
||||
|
||||
.. _man-subvolume-list:
|
||||
|
||||
list [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>
|
||||
List the subvolumes present in the filesystem *path*.
|
||||
|
||||
@ -183,6 +188,8 @@ list [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path
|
||||
for *--sort* you can combine some items together by *,*, just like
|
||||
*--sort=+ogen,-gen,path,rootid*.
|
||||
|
||||
.. _man-subvolume-set-default:
|
||||
|
||||
set-default [<subvolume>|<id> <path>]
|
||||
Set the default subvolume for the (mounted) filesystem.
|
||||
|
||||
@ -192,8 +199,11 @@ set-default [<subvolume>|<id> <path>]
|
||||
|
||||
There are two ways how to specify the subvolume, by *id* or by the *subvolume*
|
||||
path.
|
||||
The id can be obtained from :command:`btrfs subvolume list`,
|
||||
:command:`btrfs subvolume show` or :command:`btrfs inspect-internal rootid`.
|
||||
The id can be obtained from :ref:`btrfs subvolume list<man-subvolume-list>`
|
||||
:ref:`btrfs subvolume show<man-subvolume-show>` or
|
||||
:ref:`btrfs inspect-internal rootid<man-inspect-rootid>`.
|
||||
|
||||
.. _man-subvolume-show:
|
||||
|
||||
show [options] <path>
|
||||
Show more information about a subvolume (UUIDs, generations, times, flags,
|
||||
@ -237,6 +247,8 @@ snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>
|
||||
Add the newly created subvolume to a qgroup. This option can be given multiple
|
||||
times.
|
||||
|
||||
.. _man-subvolume-sync:
|
||||
|
||||
sync <path> [subvolid...]
|
||||
Wait until given subvolume(s) are completely removed from the filesystem after
|
||||
deletion. If no subvolume id is given, wait until all current deletion requests
|
||||
@ -254,7 +266,7 @@ Deleting a subvolume
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If we want to delete a subvolume called *foo* from a btrfs volume mounted at
|
||||
*/mnt/bar* we could run the following:
|
||||
:file:`/mnt/bar` we could run the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -275,8 +287,8 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs-qgroup(8)<btrfs-qgroup>`,
|
||||
:doc:`btrfs-quota(8)<btrfs-quota>`,
|
||||
:doc:`btrfs-send(8)<btrfs-send>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
|
||||
:doc:`btrfs-qgroup`,
|
||||
:doc:`btrfs-quota`,
|
||||
:doc:`btrfs-send`,
|
||||
:doc:`mkfs.btrfs`,
|
||||
``mount(8)``
|
||||
|
||||
@ -13,13 +13,13 @@ The :command:`btrfs` utility is a toolbox for managing btrfs filesystems. There
|
||||
command groups to work with subvolumes, devices, for whole filesystem or other
|
||||
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
|
||||
There are also standalone tools for some tasks like :doc:`btrfs-convert` or
|
||||
:doc:`btrfstune` that were separate historically and/or haven't been merged to the
|
||||
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>`.
|
||||
page :doc:`btrfs-man5`.
|
||||
|
||||
COMMAND SYNTAX
|
||||
--------------
|
||||
@ -53,13 +53,13 @@ of the output.
|
||||
if supported by the command, print subcommand output in that format (text, json)
|
||||
|
||||
-v|--verbose
|
||||
increase verbosity of the subcommand\n"
|
||||
increase verbosity of the subcommand
|
||||
|
||||
-q|--quiet
|
||||
print only errors\n"
|
||||
print only errors
|
||||
|
||||
--log <level>
|
||||
set log level (default, info, verbose, debug, quiet)\n"
|
||||
set log level (default, info, verbose, debug, quiet)
|
||||
|
||||
The remaining options are relevant only for the main tool:
|
||||
|
||||
@ -76,63 +76,63 @@ COMMANDS
|
||||
|
||||
balance
|
||||
Balance btrfs filesystem chunks across single or several devices.
|
||||
See :doc:`btrfs-balance(8)<btrfs-balance>` for details.
|
||||
See :doc:`btrfs-balance` for details.
|
||||
|
||||
check
|
||||
Do off-line check on a btrfs filesystem.
|
||||
See :doc:`btrfs-check(8)<btrfs-check>` for details.
|
||||
See :doc:`btrfs-check` for details.
|
||||
|
||||
device
|
||||
Manage devices managed by btrfs, including add/delete/scan and so
|
||||
on. See :doc:`btrfs-device(8)<btrfs-device>` for details.
|
||||
on. See :doc:`btrfs-device` for details.
|
||||
|
||||
filesystem
|
||||
Manage a btrfs filesystem, including label setting/sync and so on.
|
||||
See :doc:`btrfs-filesystem(8)<btrfs-filesystem>` for details.
|
||||
See :doc:`btrfs-filesystem` for details.
|
||||
|
||||
inspect-internal
|
||||
Debug tools for developers/hackers.
|
||||
See :doc:`btrfs-inspect-internal(8)<btrfs-inspect-internal>` for details.
|
||||
See :doc:`btrfs-inspect-internal` for details.
|
||||
|
||||
property
|
||||
Get/set a property from/to a btrfs object.
|
||||
See :doc:`btrfs-property(8)<btrfs-property>` for details.
|
||||
See :doc:`btrfs-property` for details.
|
||||
|
||||
qgroup
|
||||
Manage quota group(qgroup) for btrfs filesystem.
|
||||
See :doc:`btrfs-qgroup(8)<btrfs-qgroup>` for details.
|
||||
See :doc:`btrfs-qgroup` for details.
|
||||
|
||||
quota
|
||||
Manage quota on btrfs filesystem like enabling/rescan and etc.
|
||||
See :doc:`btrfs-quota(8)<btrfs-quota>` and :doc:`btrfs-qgroup(8)<btrfs-qgroup>` for details.
|
||||
See :doc:`btrfs-quota` and :doc:`btrfs-qgroup` for details.
|
||||
|
||||
receive
|
||||
Receive subvolume data from stdin/file for restore and etc.
|
||||
See :doc:`btrfs-receive(8)<btrfs-receive>` for details.
|
||||
See :doc:`btrfs-receive` for details.
|
||||
|
||||
replace
|
||||
Replace btrfs devices.
|
||||
See :doc:`btrfs-replace(8)<btrfs-replace>` for details.
|
||||
See :doc:`btrfs-replace` for details.
|
||||
|
||||
rescue
|
||||
Try to rescue damaged btrfs filesystem.
|
||||
See :doc:`btrfs-rescue(8)<btrfs-rescue>` for details.
|
||||
See :doc:`btrfs-rescue` for details.
|
||||
|
||||
restore
|
||||
Try to restore files from a damaged btrfs filesystem.
|
||||
See :doc:`btrfs-restore(8)<btrfs-restore>` for details.
|
||||
See :doc:`btrfs-restore` for details.
|
||||
|
||||
scrub
|
||||
Scrub a btrfs filesystem.
|
||||
See :doc:`btrfs-scrub(8)<btrfs-scrub>` for details.
|
||||
See :doc:`btrfs-scrub` for details.
|
||||
|
||||
send
|
||||
Send subvolume data to stdout/file for backup and etc.
|
||||
See :doc:`btrfs-send(8)<btrfs-send>` for details.
|
||||
See :doc:`btrfs-send` for details.
|
||||
|
||||
subvolume
|
||||
Create/delete/list/manage btrfs subvolume.
|
||||
See :doc:`btrfs-subvolume(8)<btrfs-subvolume>` for details.
|
||||
See :doc:`btrfs-subvolume` for details.
|
||||
|
||||
.. _man-btrfs8-standalone-tools:
|
||||
|
||||
@ -175,22 +175,22 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs(5)<btrfs-man5>`,
|
||||
:doc:`btrfs-balance(8)<btrfs-balance>`,
|
||||
:doc:`btrfs-check(8)<btrfs-check>`,
|
||||
:doc:`btrfs-convert(8)<btrfs-convert>`,
|
||||
:doc:`btrfs-device(8)<btrfs-device>`,
|
||||
:doc:`btrfs-filesystem(8)<btrfs-filesystem>`,
|
||||
:doc:`btrfs-inspect-internal(8)<btrfs-inspect-internal>`,
|
||||
:doc:`btrfs-property(8)<btrfs-property>`,
|
||||
:doc:`btrfs-qgroup(8)<btrfs-qgroup>`,
|
||||
:doc:`btrfs-quota(8)<btrfs-quota>`,
|
||||
:doc:`btrfs-receive(8)<btrfs-receive>`,
|
||||
:doc:`btrfs-replace(8)<btrfs-replace>`,
|
||||
:doc:`btrfs-rescue(8)<btrfs-rescue>`,
|
||||
:doc:`btrfs-restore(8)<btrfs-restore>`,
|
||||
:doc:`btrfs-scrub(8)<btrfs-scrub>`,
|
||||
:doc:`btrfs-send(8)<btrfs-send>`,
|
||||
:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
|
||||
:doc:`btrfstune(8)<btrfstune>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-man5`,
|
||||
:doc:`btrfs-balance`,
|
||||
:doc:`btrfs-check`,
|
||||
:doc:`btrfs-convert`,
|
||||
:doc:`btrfs-device`,
|
||||
:doc:`btrfs-filesystem`,
|
||||
:doc:`btrfs-inspect-internal`,
|
||||
:doc:`btrfs-property`,
|
||||
:doc:`btrfs-qgroup`,
|
||||
:doc:`btrfs-quota`,
|
||||
:doc:`btrfs-receive`,
|
||||
:doc:`btrfs-replace`,
|
||||
:doc:`btrfs-rescue`,
|
||||
:doc:`btrfs-restore`,
|
||||
:doc:`btrfs-scrub`,
|
||||
:doc:`btrfs-send`,
|
||||
:doc:`btrfs-subvolume`,
|
||||
:doc:`btrfstune`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -16,10 +16,10 @@ 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
|
||||
:doc:`Feature by version<Feature-by-version>` page. Also, the manual page
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` contains more details about the features.
|
||||
:doc:`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>`.
|
||||
means. Please refer to the *FILESYSTEM FEATURES* in :doc:`btrfs-man5`.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
@ -35,7 +35,7 @@ OPTIONS
|
||||
(since kernel 6.1)
|
||||
|
||||
Convert block groups tracked in standalone block group tree back to
|
||||
extent tree and remove 'block-group-tree' feature bit from the filesystem.
|
||||
extent tree and remove *block-group-tree* feature bit from the filesystem.
|
||||
|
||||
--convert-to-free-space-tree
|
||||
(since kernel 4.5)
|
||||
@ -49,8 +49,8 @@ OPTIONS
|
||||
-m
|
||||
(since kernel: 5.0)
|
||||
|
||||
change fsid stored as 'metadata_uuid' to a randomly generated UUID,
|
||||
see also '-U'
|
||||
change fsid stored as *metadata_uuid* to a randomly generated UUID,
|
||||
see also *-U*
|
||||
|
||||
-M <UUID>
|
||||
(since kernel: 5.0)
|
||||
@ -83,7 +83,7 @@ OPTIONS
|
||||
new device can be added to the filesystem and will capture all writes
|
||||
keeping the seeding device intact. See also section
|
||||
:ref:`SEEDING DEVICE<man-btrfs5-seeding-device>`
|
||||
in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
in :doc:`btrfs-man5`.
|
||||
|
||||
.. warning::
|
||||
Clearing the seeding flag on a device may be dangerous. If a
|
||||
@ -91,7 +91,7 @@ OPTIONS
|
||||
that device will become unmountable. Setting the seeding flag
|
||||
back will not fix that.
|
||||
|
||||
A valid usecase is 'seeding device as a base image'. Clear the
|
||||
A valid usecase is *seeding device as a base image*. Clear the
|
||||
seeding flag, update the filesystem and make it seeding again,
|
||||
provided that it's OK to throw away all filesystems built on
|
||||
top of the previous base.
|
||||
@ -101,10 +101,10 @@ OPTIONS
|
||||
change operation in case it was interrupted.
|
||||
|
||||
-U <UUID>
|
||||
Change fsid to 'UUID' in all metadata blocks.
|
||||
Change fsid to *UUID* in all metadata blocks.
|
||||
|
||||
The *UUID* should be a 36 bytes string in ``printf(3)`` format
|
||||
*"%08x-%04x-%04x-%04x-%012x"*.
|
||||
``%08x-%04x-%04x-%04x-%012x``.
|
||||
If there is a previous unfinished fsid change, it will continue only if the
|
||||
*UUID* matches the unfinished one or if you use the option *-u*.
|
||||
|
||||
@ -124,7 +124,7 @@ OPTIONS
|
||||
|
||||
All newly created extents will use the new representation. To
|
||||
completely switch the entire filesystem, run a full balance of the
|
||||
metadata. Please refer to :doc:`btrfs-balance(8)<btrfs-balance>`.
|
||||
metadata. Please refer to :doc:`btrfs-balance`.
|
||||
|
||||
|
||||
EXIT STATUS
|
||||
@ -142,6 +142,6 @@ will be declared obsolete and scheduled for removal.
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs(5)<btrfs-man5>`,
|
||||
:doc:`btrfs-balance(8)<btrfs-balance>`,
|
||||
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
|
||||
:doc:`btrfs-man5`,
|
||||
:doc:`btrfs-balance`,
|
||||
:doc:`mkfs.btrfs`
|
||||
|
||||
@ -123,5 +123,5 @@ Profile names, used in ``profiles`` and ``convert`` are one of:
|
||||
|
||||
The mixed data/metadata profiles can be converted in the same way, but 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 please refer to :doc:`mkfs.btrfs` section
|
||||
:ref:`PROFILES<man-mkfs-profiles>`.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
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 :ref:`PROFILES<man-mkfs-profiles>`
|
||||
:doc:`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
|
||||
|
||||
@ -51,11 +51,11 @@ BLAKE2b 19000 11 libsodium/AVX2
|
||||
|
||||
Many kernels are configured with SHA256 as built-in and not as a module.
|
||||
The accelerated versions are however provided by the modules and must be loaded
|
||||
explicitly (**modprobe sha256**) before mounting the filesystem to make use of
|
||||
them. You can check in */sys/fs/btrfs/FSID/checksum* which one is used. If you
|
||||
explicitly (:command:`modprobe sha256`) before mounting the filesystem to make use of
|
||||
them. You can check in :file:`/sys/fs/btrfs/FSID/checksum` which one is used. If you
|
||||
see *sha256-generic*, then you may want to unmount and mount the filesystem
|
||||
again, changing that on a mounted filesystem is not possible.
|
||||
Check the file */proc/crypto*, when the implementation is built-in, you'd find
|
||||
Check the file :file:`/proc/crypto`, when the implementation is built-in, you'd find
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
||||
@ -38,8 +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 :doc:`btrfs(5)<btrfs-man5>` section
|
||||
:ref:`MOUNT OPTIONS<man-btrfs5-mount-option>`.
|
||||
Please refer to :doc:`btrfs-man5` section
|
||||
:ref:`MOUNT OPTIONS<man-btrfs5-mount-options>`.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ Supported filesystems:
|
||||
|
||||
* reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27
|
||||
|
||||
* ntfs -- external tool https://github.com/maharmstone/ntfs2btrfs
|
||||
* NTFS -- external tool https://github.com/maharmstone/ntfs2btrfs
|
||||
|
||||
The list of supported source filesystem by a given binary is listed at the end
|
||||
of help (option *--help*).
|
||||
@ -89,7 +89,7 @@ lack of enough work space. This is a soft error leaving the filesystem usable
|
||||
but the block group layout may remain unchanged.
|
||||
|
||||
Note that balance operation takes a lot of time, please see also
|
||||
:doc:`btrfs-balance(8)<btrfs-balance>`.
|
||||
:doc:`btrfs-balance`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
||||
@ -182,7 +182,7 @@ degraded
|
||||
filesystems with mixed RAID profiles for data and metadata, even if the
|
||||
device number constraints would not be satisfied for some of the profiles.
|
||||
|
||||
Example: metadata -- raid1, data -- single, devices -- /dev/sda, /dev/sdb
|
||||
Example: metadata -- raid1, data -- single, devices -- :file:`/dev/sda`, :file:`/dev/sdb`
|
||||
|
||||
Suppose the data are completely stored on *sda*, then missing *sdb* will not
|
||||
prevent the mount, even if 1 missing device would normally prevent (any)
|
||||
@ -190,6 +190,8 @@ degraded
|
||||
then the constraint of single/data is not satisfied and the filesystem
|
||||
cannot be mounted.
|
||||
|
||||
.. _mount-option-device:
|
||||
|
||||
device=<devicepath>
|
||||
Specify a path to a device that will be scanned for BTRFS filesystem during
|
||||
mount. This is usually done automatically by a device manager (like udev) or
|
||||
@ -369,7 +371,7 @@ space_cache, space_cache=<version>, nospace_cache
|
||||
On an unmounted filesystem the caches (both versions) can be cleared by
|
||||
"btrfs check --clear-space-cache".
|
||||
|
||||
The :doc:`btrfs-check(8)<btrfs-check>` and `:doc:`mkfs.btrfs(8)<mkfs.btrfs>` commands have full *v2* free space
|
||||
The :doc:`btrfs-check` and `:doc:`mkfs.btrfs` commands have full *v2* free space
|
||||
cache support since v4.19.
|
||||
|
||||
If a version is not explicitly specified, the default implementation will be
|
||||
|
||||
@ -12,7 +12,7 @@ on the fly.
|
||||
On the other hand, the traditional approach has only a poor solution to
|
||||
restrict directories.
|
||||
At installation time, the harddisk can be partitioned so that every directory
|
||||
(e.g. /usr, /var/, ...) that needs a limit gets its own partition. The obvious
|
||||
(e.g. :file:`/usr`, :file:`/var`, ...) that needs a limit gets its own partition. The obvious
|
||||
problem is that those limits cannot be changed without a reinstallation. The
|
||||
btrfs subvolume feature builds a bridge. Subvolumes correspond in many ways to
|
||||
partitions, as every subvolume looks like its own filesystem. With subvolume
|
||||
@ -47,7 +47,7 @@ Subvolume quota groups
|
||||
|
||||
The basic notion of the Subvolume Quota feature is the quota group, short
|
||||
qgroup. Qgroups are notated as *level/id*, e.g. the qgroup 3/2 is a qgroup of
|
||||
level 3. For level 0, the leading '0/' can be omitted.
|
||||
level 3. For level 0, the leading *0/* can be omitted.
|
||||
Qgroups of level 0 get created automatically when a subvolume/snapshot gets
|
||||
created. The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
|
||||
is the qgroup for the root subvolume.
|
||||
@ -142,55 +142,49 @@ own way how to integrate qgroups.
|
||||
Single-user machine
|
||||
"""""""""""""""""""
|
||||
|
||||
``Replacement for partitions``
|
||||
|
||||
**Replacement for partitions.**
|
||||
The simplest use case is to use qgroups as simple replacement for partitions.
|
||||
Btrfs takes the disk as a whole, and /, /usr, /var, etc. are created as
|
||||
Btrfs takes the disk as a whole, and :file:`/`, :file:`/usr`, :file:`/var`, etc. are created as
|
||||
subvolumes. As each subvolume gets it own qgroup automatically, they can
|
||||
simply be restricted. No hierarchy is needed for that.
|
||||
|
||||
``Track usage of snapshots``
|
||||
|
||||
**Track usage of snapshots.**
|
||||
When a snapshot is taken, a qgroup for it will automatically be created with
|
||||
the correct values. 'Referenced' will show how much is in it, possibly shared
|
||||
with other subvolumes. 'Exclusive' will be the amount of space that gets freed
|
||||
the correct values. *Referenced* will show how much is in it, possibly shared
|
||||
with other subvolumes. *Exclusive* will be the amount of space that gets freed
|
||||
when the subvolume is deleted.
|
||||
|
||||
Multi-user machine
|
||||
""""""""""""""""""
|
||||
|
||||
``Restricting homes``
|
||||
|
||||
**Restricting homes.**
|
||||
When you have several users on a machine, with home directories probably under
|
||||
/home, you might want to restrict /home as a whole, while restricting every
|
||||
:file:`/home`, you might want to restrict :file:`/home` as a whole, while restricting every
|
||||
user to an individual limit as well. This is easily accomplished by creating a
|
||||
qgroup for /home , e.g. 1/1, and assigning all user subvolumes to it.
|
||||
qgroup for :file:`/home` , e.g. 1/1, and assigning all user subvolumes to it.
|
||||
Restricting this qgroup will limit /home, while every user subvolume can get
|
||||
its own (lower) limit.
|
||||
|
||||
``Accounting snapshots to the user``
|
||||
|
||||
**Accounting snapshots to the user.**
|
||||
Let's say the user is allowed to create snapshots via some mechanism. It would
|
||||
only be fair to account space used by the snapshots to the user. This does not
|
||||
mean the user doubles his usage as soon as he takes a snapshot. Of course,
|
||||
files that are present in his home and the snapshot should only be accounted
|
||||
once. This can be accomplished by creating a qgroup for each user, say
|
||||
'1/UID'. The user home and all snapshots are assigned to this qgroup.
|
||||
*1/UID*. The user home and all snapshots are assigned to this qgroup.
|
||||
Limiting it will extend the limit to all snapshots, counting files only once.
|
||||
To limit /home as a whole, a higher level group 2/1 replacing 1/1 from the
|
||||
To limit :file:`/home` as a whole, a higher level group 2/1 replacing 1/1 from the
|
||||
previous example is needed, with all user qgroups assigned to it.
|
||||
|
||||
``Do not account snapshots``
|
||||
|
||||
**Do not account snapshots.**
|
||||
On the other hand, when the snapshots get created automatically, the user has
|
||||
no chance to control them, so the space used by them should not be accounted to
|
||||
him. This is already the case when creating snapshots in the example from
|
||||
the previous section.
|
||||
|
||||
``Snapshots for backup purposes``
|
||||
|
||||
**Snapshots for backup purposes.**
|
||||
This scenario is a mixture of the previous two. The user can create snapshots,
|
||||
but some snapshots for backup purposes are being created by the system. The
|
||||
user's snapshots should be accounted to the user, not the system. The solution
|
||||
is similar to the one from section 'Accounting snapshots to the user', but do
|
||||
is similar to the one from section *Accounting snapshots to the user*, but do
|
||||
not assign system snapshots to user's qgroup.
|
||||
|
||||
@ -17,11 +17,11 @@ default *idle* so background scrub should not significantly interfere with
|
||||
normal filesystem operation. The IO scheduler set for the device(s) might not
|
||||
support the priority classes though.
|
||||
|
||||
The scrubbing status is recorded in */var/lib/btrfs/* in textual files named
|
||||
The scrubbing status is recorded in :file:`/var/lib/btrfs/` in textual files named
|
||||
*scrub.status.UUID* for a filesystem identified by the given UUID. (Progress
|
||||
state is communicated through a named pipe in file *scrub.progress.UUID* in the
|
||||
same directory.) The status file is updated every 5 seconds. A resumed scrub
|
||||
will continue from the last saved position.
|
||||
|
||||
Scrub can be started only on a mounted filesystem, though it's possible to
|
||||
scrub only a selected device. See :command:`btrfs scrub start` for more.
|
||||
scrub only a selected device. See :ref:`btrfs scrub start<man-scrub-start>` for more.
|
||||
|
||||
@ -5,7 +5,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 *unionmount*, *overlayfs* or *qcow2* image snapshot.
|
||||
functionality, like `unionmount <https://en.wikipedia.org/wiki/Union_mount>`_,
|
||||
`overlayfs <https://en.wikipedia.org/wiki/OverlayFS>`_ or
|
||||
`qcow2 <https://en.wikipedia.org/wiki/Qcow#qcow2>`_ image snapshot.
|
||||
|
||||
The seeding device starts as a normal filesystem, once the contents is ready,
|
||||
:command:`btrfstune -S 1` is used to flag it as a seeding device. Mounting such device
|
||||
@ -56,7 +58,7 @@ Example how to create and use one seeding device:
|
||||
# mount /dev/sdb /mnt/mnt1
|
||||
... /mnt/mnt1 is now writable
|
||||
|
||||
Now */mnt/mnt1* can be used normally. The device */dev/sda* can be mounted
|
||||
Now :file:`/mnt/mnt1` can be used normally. The device :file:`/dev/sda` can be mounted
|
||||
again with a another writable device:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -67,7 +69,7 @@ again with a another writable device:
|
||||
# mount /dev/sdc /mnt/mnt2
|
||||
... /mnt/mnt2 is now writable
|
||||
|
||||
The writable device (*/dev/sdb*) can be decoupled from the seeding device and
|
||||
The writable device (file:`/dev/sdb`) can be decoupled from the seeding device and
|
||||
used independently:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -75,7 +77,7 @@ used independently:
|
||||
# btrfs device delete /dev/sda /mnt/mnt1
|
||||
|
||||
As the contents originated in the seeding device, it's possible to turn
|
||||
*/dev/sdb* to a seeding device again and repeat the whole process.
|
||||
:file:`/dev/sdb` to a seeding device again and repeat the whole process.
|
||||
|
||||
A few things to note:
|
||||
|
||||
@ -95,9 +97,9 @@ Chained seeding devices
|
||||
|
||||
Though it's not recommended and is rather an obscure and untested use case,
|
||||
chaining seeding devices is possible. In the first example, the writable device
|
||||
*/dev/sdb* can be turned onto another seeding device again, depending on the
|
||||
unchanged seeding device */dev/sda*. Then using */dev/sdb* as the primary
|
||||
seeding device it can be extended with another writable device, say */dev/sdd*,
|
||||
:file:`/dev/sdb` can be turned onto another seeding device again, depending on the
|
||||
unchanged seeding device :file:`/dev/sda`. Then using :file:`/dev/sdb` as the primary
|
||||
seeding device it can be extended with another writable device, say :file:`/dev/sdd`,
|
||||
and it continues as before as a simple tree structure on devices.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -24,7 +24,7 @@ similar to a bind mount, and in fact the subvolume mount does exactly that.
|
||||
A freshly created filesystem is also a subvolume, called *top-level*,
|
||||
internally has an id 5. This subvolume cannot be removed or replaced by another
|
||||
subvolume. This is also the subvolume that will be mounted by default, unless
|
||||
the default subvolume has been changed (see :command:`btrfs subvolume set-default`).
|
||||
the default subvolume has been changed (see :ref:`btrfs subvolume set-default<man-subvolume-set-default>`).
|
||||
|
||||
A snapshot is a subvolume like any other, with given initial content. By
|
||||
default, snapshots are created read-write. File modifications in a snapshot
|
||||
@ -54,7 +54,7 @@ In addition to that, a plain snapshot will also have last change generation and
|
||||
creation generation equal.
|
||||
|
||||
Read-only snapshots are building blocks of incremental send (see
|
||||
:doc:`btrfs-send(8)<btrfs-send>`) and the whole use case relies on unmodified snapshots where
|
||||
:doc:`btrfs-send`) and the whole use case relies on unmodified snapshots where
|
||||
the relative changes are generated from. Thus, changing the subvolume flags
|
||||
from read-only to read-write will break the assumptions and may lead to
|
||||
unexpected changes in the resulting incremental stream.
|
||||
@ -85,7 +85,7 @@ descendants of the toplevel one), or nested.
|
||||
What should be mentioned early is that a snapshotting is not recursive, so a
|
||||
subvolume or a snapshot is effectively a barrier and no files in the nested
|
||||
appear in the snapshot. Instead there's a stub subvolume (also sometimes
|
||||
:command:`empty subvolume` with the same name as original subvolume, with inode number
|
||||
*empty subvolume* with the same name as original subvolume, with inode number
|
||||
2). This can be used intentionally but could be confusing in case of nested
|
||||
layouts.
|
||||
|
||||
@ -94,7 +94,7 @@ Case study: system root layouts
|
||||
|
||||
There are two ways how the system root directory and subvolume layout could be
|
||||
organized. The interesting use case for root is to allow rollbacks to previous
|
||||
version, as one atomic step. If the entire filesystem hierarchy starting in "/"
|
||||
version, as one atomic step. If the entire filesystem hierarchy starting in :file:`/`
|
||||
is in one subvolume, taking snapshot will encompass all files. This is easy for
|
||||
the snapshotting part but has undesirable consequences for rollback. For example,
|
||||
log files would get rolled back too, or any data that are stored on the root
|
||||
@ -103,8 +103,8 @@ images, ...).
|
||||
|
||||
Here we could utilize the snapshotting barrier mentioned above, each directory
|
||||
that stores data to be preserved across rollbacks is it's own subvolume. This
|
||||
could be e.g. ``/var``. Further more-fine grained partitioning could be done, e.g.
|
||||
adding separate subvolumes for ``/var/log``, ``/var/cache`` etc.
|
||||
could be e.g. :file:`/var`. Further more-fine grained partitioning could be done, e.g.
|
||||
adding separate subvolumes for :file:`/var/log`, :file:`/var/cache` etc.
|
||||
|
||||
That there are separate subvolumes requires separate actions to take the
|
||||
snapshots (here it gets disconnected from the system root snapshots). This needs
|
||||
@ -134,7 +134,7 @@ may change in the future.
|
||||
Mounting a read-write snapshot as read-only is possible and will not change the
|
||||
*ro* property and flag of the subvolume.
|
||||
|
||||
The name of the mounted subvolume is stored in file ``/proc/self/mountinfo`` in
|
||||
The name of the mounted subvolume is stored in file :file:`/proc/self/mountinfo` in
|
||||
the 4th column:
|
||||
|
||||
.. code-block::
|
||||
|
||||
@ -59,7 +59,7 @@ Please note that the UUID returned by the *mkswap* utility identifies the swap
|
||||
"filesystem" and because it's stored in a file, it's not generally visible and
|
||||
usable as an identifier unlike if it was on a block device.
|
||||
|
||||
Once activated the file will appear in */proc/swaps*:
|
||||
Once activated the file will appear in :file:`/proc/swaps`:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -103,9 +103,10 @@ the physical can still map to one or more device-specific physical block
|
||||
addresses. It's the device-specific physical offset that is suitable as resume
|
||||
offset.
|
||||
|
||||
Since version 6.1 there's a command :command:`btrfs inspect-internal map-swapfile` that will
|
||||
print the device physical offset and the adjusted value for */sys/power/resume_offset*.
|
||||
Note that the value is divided by page size, i.e. it's not the offset itself.
|
||||
Since version 6.1 there's a command :ref:`btrfs inspect-internal map-swapfile<man-inspect-map-swapfile>`
|
||||
that will print the device physical offset and the adjusted value for
|
||||
:file:`/sys/power/resume_offset`. Note that the value is divided by page size, i.e.
|
||||
it's not the offset itself.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -121,7 +122,7 @@ For scripting and convenience the option *-r* will print just the offset:
|
||||
# btrfs inspect-internal map-swapfile -r swapfile
|
||||
198122980
|
||||
|
||||
The command *map-swapfile* also verifies all the requirements, i.e. no holes,
|
||||
The command :command:`map-swapfile` also verifies all the requirements, i.e. no holes,
|
||||
single device, etc.
|
||||
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ Devices can be then added, removed or replaced on demand. Data and metadata are
|
||||
organized in allocation profiles with various redundancy policies. There's some
|
||||
similarity with traditional RAID levels, but this could be confusing to users
|
||||
familiar with the traditional meaning. Due to the similarity, the RAID
|
||||
terminology is widely used in the documentation. See :doc:`mkfs.btrfs(8)<mkfs.btrfs>` for more
|
||||
terminology is widely used in the documentation. See :doc:`mkfs.btrfs` for more
|
||||
details and the exact profile capabilities and constraints.
|
||||
|
||||
The device management works on a mounted filesystem. Devices can be added,
|
||||
@ -27,15 +27,17 @@ RAID level
|
||||
standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
|
||||
RAID10, RAID5 and RAID6.
|
||||
|
||||
.. _man-device-typical-use-cases:
|
||||
|
||||
Typical use cases
|
||||
-----------------
|
||||
|
||||
Starting with a single-device filesystem
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Assume we've created a filesystem on a block device */dev/sda* with profile
|
||||
Assume we've created a filesystem on a block device :file:`/dev/sda` with profile
|
||||
*single/single* (data/metadata), the device size is 50GiB and we've used the
|
||||
whole device for the filesystem. The mount point is */mnt*.
|
||||
whole device for the filesystem. The mount point is :file:`/mnt`.
|
||||
|
||||
The amount of data stored is 16GiB, metadata have allocated 2GiB.
|
||||
|
||||
@ -43,7 +45,7 @@ Add new device
|
||||
""""""""""""""
|
||||
|
||||
We want to increase the total size of the filesystem and keep the profiles. The
|
||||
size of the new device */dev/sdb* is 100GiB.
|
||||
size of the new device :file:`/dev/sdb` is 100GiB.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@ -94,7 +96,7 @@ The balance process needs some workspace (i.e. a free device space without any
|
||||
data or metadata block groups) so the command could fail if there's too much
|
||||
data or the block groups occupy the whole first device.
|
||||
|
||||
The device size of */dev/sdb* as seen by the filesystem remains unchanged, but
|
||||
The device size of :file:`/dev/sdb` as seen by the filesystem remains unchanged, but
|
||||
the logical space from 50-100GiB will be unused.
|
||||
|
||||
Remove device
|
||||
|
||||
@ -92,7 +92,7 @@ testing. There are some quirks setting up the devices. The module must be
|
||||
loaded with *nr_devices=0* or the numbering of device nodes will be offset. The
|
||||
*configfs* must be mounted at */sys/kernel/config* and the administration of
|
||||
the null_blk devices is done in */sys/kernel/config/nullb*. The device nodes
|
||||
are named like */dev/nullb0* and are numbered sequentially. NOTE: the device
|
||||
are named like :file:`/dev/nullb0` and are numbered sequentially. NOTE: the device
|
||||
name may be different than the named directory in sysfs!
|
||||
|
||||
Setup:
|
||||
@ -117,7 +117,7 @@ example taking defaults:
|
||||
echo 256 > zone_size
|
||||
echo 1 > power
|
||||
|
||||
This will create a device */dev/nullb0* and the value of file *index* will
|
||||
This will create a device :file:`/dev/nullb0` and the value of file *index* will
|
||||
match the ending number of the device node.
|
||||
|
||||
Remove the device:
|
||||
@ -126,7 +126,7 @@ Remove the device:
|
||||
|
||||
rmdir /sys/kernel/config/nullb/mydev
|
||||
|
||||
Then continue with *mkfs.btrfs /dev/nullb0*, the zoned mode is auto-detected.
|
||||
Then continue with :command:`mkfs.btrfs /dev/nullb0`, the zoned mode is auto-detected.
|
||||
|
||||
For convenience, there's a script wrapping the basic null_blk management operations
|
||||
https://github.com/kdave/nullb.git, the above commands become:
|
||||
|
||||
@ -45,7 +45,7 @@ author is also recorded in git log history.
|
||||
|
||||
Then, each maintainer that processed the patch adds his sob line.
|
||||
|
||||
*Reference:* Section 11 of SubmittingPatches
|
||||
*Reference:* `Section of SubmittingPatches <https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`__.
|
||||
|
||||
**Do**: Always send a patch with at least one such line with your name and email.
|
||||
If more people contributed to the patch, add their names and addresses too.
|
||||
@ -60,7 +60,7 @@ The patch has been reviewed and the singed person is putting his hand into
|
||||
fire. If there's a bug found in this patch, the person is usually a good
|
||||
candidate for a CC: of the bugreport.
|
||||
|
||||
*Reference:* Section 13 of SubmittingPatches
|
||||
*Reference:* `Section of SubmittingPatches <https://docs.kernel.org/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`__.
|
||||
|
||||
**Do**: talk to the maintainer if he forgot to add this tag to the final patch.
|
||||
Reviews do take time and the patches land in various branches early after
|
||||
@ -83,7 +83,7 @@ Tested-by:
|
||||
Indicates that the patch has been successfully tested in some environment,
|
||||
usually follows a proposed fix and closes the feedback loop.
|
||||
|
||||
*Reference:* Section 13 of SubmittingPatches
|
||||
*Reference:* `Section of SubmittingPatches <https://docs.kernel.org/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_.
|
||||
|
||||
**Do**: or rather you're encouraged to add this tag to a patch that you've
|
||||
tested.
|
||||
|
||||
@ -9,7 +9,7 @@ Adding a new ioctl, extending an existing one
|
||||
|
||||
- add code to `strace <https://github.com/strace/strace>`__ so the ioctl calls
|
||||
are parsed into a human readable form. Most of the ioctls are already
|
||||
`implemented <https://github.com/strace/strace/blob/master/btrfs.c>`__ and
|
||||
`implemented <https://github.com/strace/strace/blob/master/src/btrfs.c>`__ and
|
||||
can be used a reference.
|
||||
|
||||
Tracepoints
|
||||
@ -134,8 +134,8 @@ helpers (e.g. memory allocation), you can use something like
|
||||
|
||||
Resources:
|
||||
|
||||
- eBPF
|
||||
- BCC tools
|
||||
- `eBPF <https://ebpf.io/>`_
|
||||
- `BCC tools <https://github.com/iovisor/bcc>`_
|
||||
|
||||
Warnings and issues found by static checkers and similar tools
|
||||
--------------------------------------------------------------
|
||||
@ -206,7 +206,7 @@ Patches
|
||||
- steps to reproduce a bug (that will also get turned to a proper fstests
|
||||
case)
|
||||
- sample output before/after if it could have impact on userspace
|
||||
- *pahole* output if structure is being reorganized and optimized
|
||||
- `pahole <https://linux.die.net/man/1/pahole>`_ output if structure is being reorganized and optimized
|
||||
|
||||
Function declarations
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -410,13 +410,16 @@ Please refer to the option documentation for further details.
|
||||
BUG: MAX_LOCKDEP_CHAIN_HLOCKS too low!
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Not a bug. Increase the config value of LOCKDEP_CHAINS_BITS, default is
|
||||
Not a bug. The lockdep structures can get in some cases full and cannot
|
||||
properly track locks anymore. There's only a workaround to increase the kernel
|
||||
config value of CONFIG_LOCKDEP_CHAINS_BITS, default is
|
||||
16, 18 tends to work, increase if needed.
|
||||
|
||||
fstests setup
|
||||
-------------
|
||||
|
||||
The fstests suite has very few "hard" requirements and will succeed without
|
||||
The `fstests <https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git/>`_
|
||||
suite has very few "hard" requirements and will succeed without
|
||||
actually running many tests. In order to ensure full test coverage, your test
|
||||
environment should provide the settings from the following sections. Please
|
||||
note that newly added tests silently add new dependencies, so you should always
|
||||
@ -471,7 +474,7 @@ Storage environment
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- At least 4 identically sized partitions/disks/virtual disks, specified using
|
||||
``$SCRATCH_DEV_POOL``, some tests may require 6 such partitions
|
||||
``$SCRATCH_DEV_POOL``, some tests may require 8 such partitions
|
||||
- some tests need at least 10G of free space, as determined by ``df``, i.e.
|
||||
the size of the device may need to be larger
|
||||
- some tests require ``$LOGWRITES_DEV``, yet another separate block device,
|
||||
|
||||
@ -18,7 +18,7 @@ filesystem was not unmounted cleanly and the log needs to be replayed before
|
||||
mount. This is not needed for BTRFS. You should set fs_passno to 0.
|
||||
|
||||
If you wish to check the consistency of a BTRFS filesystem or repair a damaged
|
||||
filesystem, see :doc:`btrfs-check(8)<btrfs-check>`. By default filesystem consistency is checked,
|
||||
filesystem, see :doc:`btrfs-check`. By default filesystem consistency is checked,
|
||||
the repair mode is enabled via the *--repair* option (use with care!).
|
||||
|
||||
OPTIONS
|
||||
@ -47,6 +47,6 @@ FILES
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs(8)<btrfs>`,
|
||||
:doc:`btrfs`,
|
||||
``fsck(8)``,
|
||||
``fstab(5)``
|
||||
|
||||
@ -21,7 +21,7 @@ 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
|
||||
but the defaults should be OK and allowing future conversions to other profiles.
|
||||
Please see options *-d* and *-m* for further details and :doc:`btrfs-balance(8)<btrfs-balance>` for
|
||||
Please see options *-d* and *-m* for further details and :doc:`btrfs-balance` for
|
||||
the profile conversion post mkfs.
|
||||
|
||||
OPTIONS
|
||||
@ -37,7 +37,7 @@ OPTIONS
|
||||
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 section :ref:`CHECKSUM ALGORITHMS<man-mkfs-checksum-algorithms>`
|
||||
in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
in :doc:`btrfs-man5`.
|
||||
|
||||
-d|--data <profile>
|
||||
Specify the profile for the data block groups. Valid values are *raid0*,
|
||||
@ -132,7 +132,7 @@ OPTIONS
|
||||
-K|--nodiscard
|
||||
Do not perform whole device TRIM operation on devices that are capable of that.
|
||||
This does not affect discard/trim operation when the filesystem is mounted.
|
||||
Please see the mount option *discard* for that in :doc:`btrfs(5)<btrfs-man5>`.
|
||||
Please see the mount option *discard* for that in :doc:`btrfs-man5`.
|
||||
|
||||
-r|--rootdir <rootdir>
|
||||
Populate the toplevel subvolume with files from *rootdir*. This does not
|
||||
@ -242,7 +242,7 @@ devices to scan at the time of mount.
|
||||
FILESYSTEM FEATURES
|
||||
-------------------
|
||||
|
||||
Features that can be enabled during creation time. See also :doc:`btrfs(5)<btrfs-man5>` section
|
||||
Features that can be enabled during creation time. See also :doc:`btrfs-man5` section
|
||||
:ref:`FILESYSTEM FEATURES<man-btrfs5-filesystem-features>`.
|
||||
|
||||
mixed-bg
|
||||
@ -285,14 +285,14 @@ zoned
|
||||
|
||||
zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS devices,
|
||||
see :ref:`ZONED MODE<man-btrfs5-zoned-mode>` in
|
||||
:doc:`btrfs(5)<btrfs-man5>`, the mode is automatically selected when a
|
||||
:doc:`btrfs-man5`, the mode is automatically selected when a
|
||||
zoned device is detected
|
||||
|
||||
quota
|
||||
(kernel support since 3.4)
|
||||
|
||||
Enable quota support (qgroups). The qgroup accounting will be consistent,
|
||||
can be used together with *--rootdir*. See also :doc:`btrfs-quota(8)<btrfs-quota>`.
|
||||
can be used together with *--rootdir*. See also :doc:`btrfs-quota`.
|
||||
|
||||
.. _mkfs-feature-free-space-tree:
|
||||
|
||||
@ -558,7 +558,7 @@ AVAILABILITY
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
:doc:`btrfs(5)<btrfs-man5>`,
|
||||
:doc:`btrfs(8)<btrfs>`,
|
||||
:doc:`btrfs-balance(8)<btrfs-balance>`,
|
||||
:doc:`btrfs-man5`,
|
||||
:doc:`btrfs`,
|
||||
:doc:`btrfs-balance`,
|
||||
``wipefs(8)``
|
||||
|
||||
Loading…
Reference in New Issue
Block a user