btrfs-progs: docs: add more of the new doc structure
Add overall structure for now, some contents is from wiki. Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
ee801c07d7
commit
9756d90ce3
|
|
@ -0,0 +1,4 @@
|
|||
Auto-repair on read
|
||||
===================
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Balance
|
||||
=======
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Checksumming
|
||||
============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
Common Linux features
|
||||
=====================
|
||||
|
||||
Anything that's standard and also supported
|
||||
|
||||
- statx
|
||||
|
||||
- fallocate modes
|
||||
|
||||
- birth/origin inode time
|
||||
|
||||
- filesystem label
|
||||
|
||||
- xattr, acl
|
||||
|
||||
- FIEMAP
|
||||
|
||||
- O_TMPFILE
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Compression
|
||||
===========
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Convert
|
||||
=======
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
Custom ioctls
|
||||
=============
|
||||
|
||||
Anything that's not doing the other features and stands on it's own
|
||||
|
||||
- reverse lookup, from file offset to inode
|
||||
|
||||
- resolve inode number -> name
|
||||
|
||||
- file offset -> all inodes that share it
|
||||
|
||||
- tree search, all the metadata at your hand (if you know what to do with them)
|
||||
|
||||
- informative (device, fs, space)
|
||||
|
||||
- query/set a subset of features on a mounted fs
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Deduplication
|
||||
=============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Defragmentation
|
||||
===============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
Flexibility
|
||||
===========
|
||||
|
||||
* dynamic inode creation (no preallocated space)
|
||||
|
||||
* block group profile change on-the-fly
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Inline files
|
||||
============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
.. BTRFS integration related pages index
|
||||
|
||||
Interoperability
|
||||
================
|
||||
|
||||
NFS
|
||||
---
|
||||
|
||||
Samba
|
||||
-----
|
||||
|
||||
cgroups
|
||||
-------
|
||||
|
||||
fsverity
|
||||
--------
|
||||
|
||||
idmapped mounts
|
||||
---------------
|
||||
|
||||
Device mapper
|
||||
-------------
|
||||
|
||||
overlayfs
|
||||
---------
|
||||
|
||||
SELinux
|
||||
-------
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
BTRFS is a modern copy on write (COW) filesystem for Linux aimed at
|
||||
implementing advanced features while also focusing on fault tolerance, repair
|
||||
and easy administration. Its main features and benefits are:
|
||||
|
||||
* Snapshots which do not make the full copy of files
|
||||
* Built-in volume management, support for software-based RAID 0, RAID 1, RAID 10 and others
|
||||
* Self-healing - checksums for data and metadata, automatic detection of silent data corruptions
|
||||
|
||||
Feature overview:
|
||||
|
||||
* Extent based file storage
|
||||
* 2^64 byte == 16 EiB maximum file size (practical limit is 8 EiB due to Linux VFS)
|
||||
* Space-efficient packing of small files
|
||||
* Space-efficient indexed directories
|
||||
* Dynamic inode allocation
|
||||
* Writable snapshots, read-only snapshots
|
||||
* Subvolumes (separate internal filesystem roots)
|
||||
* Checksums on data and metadata (crc32c, xxhash, sha256, blake2b)
|
||||
* Compression (ZLIB, LZO, ZSTD), heuristics
|
||||
* Integrated multiple device support
|
||||
* File Striping
|
||||
* File Mirroring
|
||||
* File Striping+Mirroring
|
||||
* Single and Dual Parity implementations (experimental, not production-ready)
|
||||
* SSD (flash storage) awareness (TRIM/Discard for reporting free blocks for
|
||||
reuse) and optimizations (e.g. avoiding unnecessary seek optimizations,
|
||||
sending writes in clusters, even if they are from unrelated files. This
|
||||
results in larger write operations and faster write throughput)
|
||||
* Efficient incremental backup
|
||||
* Background scrub process for finding and repairing errors of files with redundant copies
|
||||
* Online filesystem defragmentation
|
||||
* Offline filesystem check
|
||||
* In-place conversion of existing ext2/3/4 and reiserfs file systems
|
||||
* Seed devices. Create a (readonly) filesystem that acts as a template to seed
|
||||
other Btrfs filesystems. The original filesystem and devices are included as
|
||||
a readonly starting point for the new filesystem. Using copy on write, all
|
||||
modifications are stored on different devices; the original is unchanged.
|
||||
* Subvolume-aware quota support
|
||||
* Send/receive of subvolume changes
|
||||
* Efficient incremental filesystem mirroring
|
||||
* Batch, or out-of-band deduplication (happens after writes, not during)
|
||||
* Swapfile support
|
||||
* Tree-checker, post-read and pre-write metadata verification
|
||||
* Zoned mode support (SMR/ZBC/ZNS friendly allocation)
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Quota groups
|
||||
============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Quick start
|
||||
===========
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Reflink
|
||||
=======
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Resize
|
||||
======
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Scrub
|
||||
=====
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Seeding device
|
||||
==============
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Balance
|
||||
=======
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,114 @@
|
|||
Source repositories
|
||||
===================
|
||||
|
||||
Since 2.6.29-rc1, Btrfs has been included in the mainline kernel.
|
||||
|
||||
Kernel module
|
||||
-------------
|
||||
|
||||
The kernel.org git repository is not used for development, only for pull
|
||||
requests that go to Linus and for linux-next integration:
|
||||
|
||||
* https://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux.git -- pull requests, branch *for-next* gets pulled to the linux-next tree
|
||||
|
||||
The following git repositories are used for development and are updated with
|
||||
patches from the mailinglist:
|
||||
|
||||
* https://github.com/kdave/btrfs-devel
|
||||
* https://gitlab.com/kdave/btrfs-devel
|
||||
|
||||
Branches are usually pushed to both repositories, either can be used.
|
||||
|
||||
There are:
|
||||
|
||||
* main queue with patches for next development cycle (branch name *misc-next*)
|
||||
* queue with patches for current release cycle (the name has the version, eg *for-4.15* or *misc-4.15*).
|
||||
* topic branches, eg. from a patchset picked from mailinglist
|
||||
* snapshots of *for-next*, that contain all of the above (eg. 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]].
|
||||
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.
|
||||
|
||||
btrfs-progs git repository
|
||||
--------------------------
|
||||
|
||||
Official repositories
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The sources of the userspace utilities can be obtained from these repositories:
|
||||
|
||||
* git://git.kernel.org/pub/scm/linux/kernel/git/kdave/btrfs-progs.git (`gitweb
|
||||
access
|
||||
<http://git.kernel.org/?p=linux/kernel/git/kdave/btrfs-progs.git;a=summary>`_)
|
||||
-- release repository, not for development
|
||||
|
||||
The **master** branch contains the latest released version and is never rebased.
|
||||
|
||||
Development git repositories:
|
||||
|
||||
* git://github.com/kdave/btrfs-progs.git (`web access <https://github.com/kdave/btrfs-progs>`_)
|
||||
* git://gitlab.com/kdave/btrfs-progs.git (`web access <https://gitlab.com/kdave/btrfs-progs>`_)
|
||||
|
||||
For build dependencies and installation instructions please see
|
||||
https://github.com/kdave/btrfs-progs/blob/master/INSTALL
|
||||
|
||||
Development branches
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The latest **development branch** is called **devel**. Contains patches that
|
||||
are reviewed or tested and on the way to the next release. When a patch is
|
||||
added to the branch, a mail notification is sent as a reply to the patch.
|
||||
|
||||
The git repositories on *kernel.org* are not used for development or
|
||||
integration branches.
|
||||
|
||||
Note to GitHub users
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The pull requests will not be accepted directly, the preferred way is to send
|
||||
patches to the mailinglist instead. You can link to a branch in any git
|
||||
repository if the mails do not make it to the mailinglist or for convenience.
|
||||
|
||||
The development model of btrfs-progs shares a lot with the kernel model. The
|
||||
github way is different in some ways. We, the upstream community, expect that
|
||||
the patches meet some criteria (often lacking in github contributions):
|
||||
|
||||
* proper **subject line**: eg. prefix with *btrfs-progs: subpart, ...* ,
|
||||
descriptive yet not too long
|
||||
* proper **changelog**: the changelogs are often missing or lacking
|
||||
explanation *why* the change was made, or *how* is something broken,
|
||||
*what* are user-visible effects of the bug or the fix, *how* does an
|
||||
improvement help or the intended *usecase*
|
||||
* the **Signed-off-by** line: this document who authored the change, you can
|
||||
read more about the *The Developer's Certificate of Origin*
|
||||
`here (chapter 11) <https://www.kernel.org/doc/Documentation/SubmittingPatches>`_]
|
||||
* **one logical change** per patch: eg. not mixing bugfixes, cleanups,
|
||||
features etc., sometimes it's not clear and will be usually pointed out
|
||||
during reviews
|
||||
|
||||
Administration and support tools
|
||||
--------------------------------
|
||||
|
||||
There is a separate repository of useful scripts for common administrative
|
||||
tasks on btrfs. This is at:
|
||||
|
||||
https://github.com/kdave/btrfsmaintenance/
|
||||
|
||||
Patches sent to mailinglist
|
||||
---------------------------
|
||||
|
||||
A convenient interface to get an overview of patches and the related mail
|
||||
discussions can be found at
|
||||
https://patchwork.kernel.org/project/linux-btrfs/list/ .
|
||||
|
||||
It is possible to directly apply a patch by pasting the *mbox* link from the
|
||||
patch page to the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ wget -O - '<nowiki>https://patchwork.kernel.org/patch/123456/mbox</nowiki>' | git am -
|
||||
|
||||
You may want to add *--reject*, or decide otherwise what to do with the patch.
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Subvolumes
|
||||
==========
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
Tree checker
|
||||
============
|
||||
|
||||
Pre-write checks
|
||||
|
||||
Post-read checks
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Trim
|
||||
====
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Volume management
|
||||
=================
|
||||
|
||||
...
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Zoned mode
|
||||
==========
|
||||
|
||||
...
|
||||
|
|
@ -5,8 +5,44 @@ Welcome to BTRFS documentation!
|
|||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Contents:
|
||||
:caption: Overview
|
||||
|
||||
Introduction
|
||||
Quick-start
|
||||
man-index
|
||||
wiki-index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Features:
|
||||
|
||||
Common-features
|
||||
Custom-ioctls
|
||||
Auto-repair
|
||||
Balance
|
||||
Compression
|
||||
Checksumming
|
||||
Convert
|
||||
Deduplication
|
||||
Defragmentation
|
||||
Inline-files
|
||||
Qgroups
|
||||
Reflink
|
||||
Resize
|
||||
Scrub
|
||||
Seeding-device
|
||||
Send-receive
|
||||
Subvolumes
|
||||
Tree-checker
|
||||
Trim
|
||||
Volume-management
|
||||
Zoned-mode
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: TODO
|
||||
|
||||
Interoperability
|
||||
Glossary
|
||||
Flexibility
|
||||
project-index
|
||||
trouble-index
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
.. BTRFS project related pages index
|
||||
|
||||
Project pages
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Source-repositories
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
.. BTRFS troubleshooting related pages index
|
||||
|
||||
Troubleshooting pages
|
||||
=====================
|
||||
|
||||
Correctness related, permanent
|
||||
|
||||
- transid verify error
|
||||
|
||||
Transient
|
||||
|
||||
- enospc
|
||||
|
||||
- operation cannot be done
|
||||
|
||||
Possibly both
|
||||
|
||||
- checksum errors from changes on the medium under hands
|
||||
|
||||
- transient because of direct io
|
||||
|
||||
- stored from faulty data in memory
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
.. BTRFS wiki pages index
|
||||
|
||||
Wiki pages
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Glossary
|
||||
Loading…
Reference in New Issue