diff --git a/Documentation/Auto-repair.rst b/Documentation/Auto-repair.rst new file mode 100644 index 00000000..1d6c60b7 --- /dev/null +++ b/Documentation/Auto-repair.rst @@ -0,0 +1,4 @@ +Auto-repair on read +=================== + +... diff --git a/Documentation/Balance.rst b/Documentation/Balance.rst new file mode 100644 index 00000000..29e0b4df --- /dev/null +++ b/Documentation/Balance.rst @@ -0,0 +1,4 @@ +Balance +======= + +... diff --git a/Documentation/Checksumming.rst b/Documentation/Checksumming.rst new file mode 100644 index 00000000..6ae8c38f --- /dev/null +++ b/Documentation/Checksumming.rst @@ -0,0 +1,4 @@ +Checksumming +============ + +... diff --git a/Documentation/Common-features.rst b/Documentation/Common-features.rst new file mode 100644 index 00000000..6fee7817 --- /dev/null +++ b/Documentation/Common-features.rst @@ -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 diff --git a/Documentation/Compression.rst b/Documentation/Compression.rst new file mode 100644 index 00000000..1a1c4578 --- /dev/null +++ b/Documentation/Compression.rst @@ -0,0 +1,4 @@ +Compression +=========== + +... diff --git a/Documentation/Convert.rst b/Documentation/Convert.rst new file mode 100644 index 00000000..c1f85959 --- /dev/null +++ b/Documentation/Convert.rst @@ -0,0 +1,4 @@ +Convert +======= + +... diff --git a/Documentation/Custom-ioctls.rst b/Documentation/Custom-ioctls.rst new file mode 100644 index 00000000..11f08280 --- /dev/null +++ b/Documentation/Custom-ioctls.rst @@ -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 diff --git a/Documentation/Deduplication.rst b/Documentation/Deduplication.rst new file mode 100644 index 00000000..9f491a91 --- /dev/null +++ b/Documentation/Deduplication.rst @@ -0,0 +1,4 @@ +Deduplication +============= + +... diff --git a/Documentation/Defragmentation.rst b/Documentation/Defragmentation.rst new file mode 100644 index 00000000..89f4fc1f --- /dev/null +++ b/Documentation/Defragmentation.rst @@ -0,0 +1,4 @@ +Defragmentation +=============== + +... diff --git a/Documentation/Flexibility.rst b/Documentation/Flexibility.rst new file mode 100644 index 00000000..e0c00e63 --- /dev/null +++ b/Documentation/Flexibility.rst @@ -0,0 +1,6 @@ +Flexibility +=========== + +* dynamic inode creation (no preallocated space) + +* block group profile change on-the-fly diff --git a/Documentation/Inline-files.rst b/Documentation/Inline-files.rst new file mode 100644 index 00000000..91ee1801 --- /dev/null +++ b/Documentation/Inline-files.rst @@ -0,0 +1,4 @@ +Inline files +============ + +... diff --git a/Documentation/Interoperability.rst b/Documentation/Interoperability.rst new file mode 100644 index 00000000..b0b44dc8 --- /dev/null +++ b/Documentation/Interoperability.rst @@ -0,0 +1,28 @@ +.. BTRFS integration related pages index + +Interoperability +================ + +NFS +--- + +Samba +----- + +cgroups +------- + +fsverity +-------- + +idmapped mounts +--------------- + +Device mapper +------------- + +overlayfs +--------- + +SELinux +------- diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst new file mode 100644 index 00000000..5b28a3d5 --- /dev/null +++ b/Documentation/Introduction.rst @@ -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) diff --git a/Documentation/Qgroups.rst b/Documentation/Qgroups.rst new file mode 100644 index 00000000..3f9cb701 --- /dev/null +++ b/Documentation/Qgroups.rst @@ -0,0 +1,4 @@ +Quota groups +============ + +... diff --git a/Documentation/Quick-start.rst b/Documentation/Quick-start.rst new file mode 100644 index 00000000..23e1dcd3 --- /dev/null +++ b/Documentation/Quick-start.rst @@ -0,0 +1,4 @@ +Quick start +=========== + +... diff --git a/Documentation/Reflink.rst b/Documentation/Reflink.rst new file mode 100644 index 00000000..00efe09b --- /dev/null +++ b/Documentation/Reflink.rst @@ -0,0 +1,4 @@ +Reflink +======= + +... diff --git a/Documentation/Resize.rst b/Documentation/Resize.rst new file mode 100644 index 00000000..0ffdf672 --- /dev/null +++ b/Documentation/Resize.rst @@ -0,0 +1,4 @@ +Resize +====== + +... diff --git a/Documentation/Scrub.rst b/Documentation/Scrub.rst new file mode 100644 index 00000000..35199289 --- /dev/null +++ b/Documentation/Scrub.rst @@ -0,0 +1,4 @@ +Scrub +===== + +... diff --git a/Documentation/Seeding-device.rst b/Documentation/Seeding-device.rst new file mode 100644 index 00000000..5ebffb8f --- /dev/null +++ b/Documentation/Seeding-device.rst @@ -0,0 +1,4 @@ +Seeding device +============== + +... diff --git a/Documentation/Send-receive.rst b/Documentation/Send-receive.rst new file mode 100644 index 00000000..29e0b4df --- /dev/null +++ b/Documentation/Send-receive.rst @@ -0,0 +1,4 @@ +Balance +======= + +... diff --git a/Documentation/Source-repositories.rst b/Documentation/Source-repositories.rst new file mode 100644 index 00000000..cfed2e4c --- /dev/null +++ b/Documentation/Source-repositories.rst @@ -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 + `_) + -- 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 `_) +* git://gitlab.com/kdave/btrfs-progs.git (`web access `_) + +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) `_] +* **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 - 'https://patchwork.kernel.org/patch/123456/mbox' | git am - + +You may want to add *--reject*, or decide otherwise what to do with the patch. diff --git a/Documentation/Subvolumes.rst b/Documentation/Subvolumes.rst new file mode 100644 index 00000000..2475956f --- /dev/null +++ b/Documentation/Subvolumes.rst @@ -0,0 +1,4 @@ +Subvolumes +========== + +... diff --git a/Documentation/Tree-checker.rst b/Documentation/Tree-checker.rst new file mode 100644 index 00000000..43b1fff2 --- /dev/null +++ b/Documentation/Tree-checker.rst @@ -0,0 +1,6 @@ +Tree checker +============ + +Pre-write checks + +Post-read checks diff --git a/Documentation/Trim.rst b/Documentation/Trim.rst new file mode 100644 index 00000000..13e2842d --- /dev/null +++ b/Documentation/Trim.rst @@ -0,0 +1,4 @@ +Trim +==== + +... diff --git a/Documentation/Volume-management.rst b/Documentation/Volume-management.rst new file mode 100644 index 00000000..21adbfe8 --- /dev/null +++ b/Documentation/Volume-management.rst @@ -0,0 +1,4 @@ +Volume management +================= + +... diff --git a/Documentation/Zoned-mode.rst b/Documentation/Zoned-mode.rst new file mode 100644 index 00000000..52a747cd --- /dev/null +++ b/Documentation/Zoned-mode.rst @@ -0,0 +1,4 @@ +Zoned mode +========== + +... diff --git a/Documentation/index.rst b/Documentation/index.rst index 3ca5b822..53f321a4 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -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 diff --git a/Documentation/project-index.rst b/Documentation/project-index.rst new file mode 100644 index 00000000..6a4c2851 --- /dev/null +++ b/Documentation/project-index.rst @@ -0,0 +1,9 @@ +.. BTRFS project related pages index + +Project pages +============= + +.. toctree:: + :maxdepth: 1 + + Source-repositories diff --git a/Documentation/trouble-index.rst b/Documentation/trouble-index.rst new file mode 100644 index 00000000..fc2f04ae --- /dev/null +++ b/Documentation/trouble-index.rst @@ -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 diff --git a/Documentation/wiki-index.rst b/Documentation/wiki-index.rst deleted file mode 100644 index ddd98039..00000000 --- a/Documentation/wiki-index.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. BTRFS wiki pages index - -Wiki pages -========== - -.. toctree:: - :maxdepth: 1 - - Glossary