On Fri, Dec 09, 2022 at 03:23:14PM +0100, Sergei Shtepa wrote: > The document contains: > * Describes the purpose of the mechanism > * Description of features > * Description of algorithms > * Recommendations about using the module from the user-space side > * Reference to module interface description The patch subject should be "Documentation: document Block Devices Snapshots Module". Don't forget to write the description in imperative mood instead. > +Introduction > +============ > + > +At first glance, there is no novelty in the idea of creating snapshots for > +block devices. The Linux kernel already has mechanisms for creating snapshots. > +Device Mapper includes dm-snap, which allows to create snapshots of block > +devices. BTRFS supports snapshots at the file system level. However, both > +of these options have flaws that do not allow to use them as a universal > +tool for creating backups. > + > +Device Mapper flaws: > + > +- Block devices must have LVM markup. > + If no logical volumes were created during system installation, then dm-snap > + cannot be applied. > +- To store snapshot differences of one logical volume, it is necessary to > + reserve a fixed range of sectors on a reserved empty logical volume. > + Firstly, it is required that the system has enough space unoccupied by the > + file system, which rarely occurs on real servers. Secondly, as a rule, > + it is necessary to create snapshots for all logical volumes at once, which > + requires dividing this reserved space between several logical volumes. > + This space can be divided equally or proportionally to the size. But > + the load on different disks is usually uneven. As a result, a snapshot > + overflow may occur for one of the block devices, while for others all > + the reserved space may remain free. This complicates management of the > + difference storage and makes it almost impossible to create a coherent > + snapshot of multiple logical volumes. > + > +BTRFS flaws: > + > +- Snapshots create a persistent image of the file system, not a block device. > + Such a snapshot is only applicable for a file backup. > +- When synchronizing the snapshot subvolume with the backup subvolume, reading > + the differences leads to random access to the block device, which leads > + to decrease in efficiency compared to direct copying of the block device. > +- BTRFS allows to get an incremental backup [#btrfs_increment]_, but it is > + necessary to keep a snapshot of the previous backup cycle on the system, > + which leads to excessive consumption of disk space. > +- If there is not enough free space on the file system while holding the > + snapshot, new data cannot be saved, which leads to a server malfunction. > + > +Features of the blksnap module: > + > +- Change tracker > +- Snapshots at the block device level > +- Dynamic allocation of space for storing differences > +- Snapshot overflow resistance > +- Coherent snapshot of multiple block devices There is a jump from drawbacks of existing method to blksnap features. Before introducing the latter, there should have been blksnap description and how it solves the drawbacks. Also, the features list above is redundant due to features section which describes each of them. > +Static C++ library > +------------------ > + > +The [#userspace_libs]_ library was created primarily to simplify creation of "The libblksnap [#userspace_libs]_ library was ..." > +Module interface description > +============================ > + > +.. kernel-doc:: include/uapi/linux/blksnap.h IMO this section should be placed after "How to use" section, because it's quite odd to add another info after references section. Thanks. -- An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
