index: Logically group articles, undo renaming discosrv

draft/syncing.rst

@@ -0,0 +1,53 @@
+.. _syncing:
+
+Understanding Synchronization
+=============================
+
+Blocks
+------
+
+Files are divided into *blocks*. The blocks are currently fixed size, 128 KiB,
+except the last one in the file which may be smaller. Each file is sliced into
+a number of these blocks, and the SHA256 hash of each block is computed. This
+results in a *block list* containing the offset, size and hash of all blocks
+in the file.
+
+To update a file, Syncthing compares the block list of the current version of
+the file to the block list of the desired version of the file. It then tries
+to find a source for each block that differs. This might be locally, if
+another file already has a block with the same hash, or it may be from another
+device in the cluster. In the first case the block is simply copied on disk,
+in the second case it is requested over the network from the other device.
+
+When a block is copied or recieved from another device, its SHA256 hash is
+computed and compared with the expected value. If it matches the block is
+written to a temporary copy of the file, otherwise it is discarded and
+Syncthing tries to find another source for the block.
+
+Scanning
+--------
+
+Syncthing detects changes to files by scanning. By default this happens every
+60 seconds, but this can be changed per folder. Increasing the scan interval
+uses less resources and is useful for example on large folders that changes
+infrequently. Syncthing-inotify can also be used, which tells Syncthing to
+scan changed files when changes are detected, thus reducing the need for
+periodic rescans.
+
+During a rescan the existing files are checked for changes to their
+modification time or size. The file is "rehashed" if a change is detected
+based on those attributes, that is a new block list is calculated for the
+file. It is not possible to know which parts of a file changed without reading
+the file and computing new SHA256 hashes for each block.
+
+Changes that were detected and hashed are transmitted to the other devices
+after a rescan.
+
+Temporary Files
+---------------
+
+Syncthing never writes directly to a file. Instead all changes are made to a
+temporary copy which is then moved in place over the old version. If an error
+occurrs during the copying or syncing, such as a necessary block not being
+available, the temporary file is kept around for up to a day. This is to avoid
+needlessly requesting data over the network.

index.rst

@@ -57,9 +57,23 @@ can use the headings in the left sidebar to navigate the site.
    :glob:
 
    Command Line Operation <users/syncthing>
-   Configuration <users/config>
    users/faq
+
+   Configuration <users/config>
+   users/advanced
+   users/foldermaster
+
    users/firewall
+   users/relaying
+   users/proxying
+
+   users/ignoring
+   users/versioning
+
+   users/discosrv
+   users/relaysrv
+   users/custom-upgrades
+
    users/*
 
 .. toctree::

users/foldermaster.rst

@@ -1,7 +1,7 @@
 .. _folder-master:
 
-Folder Master
+Folder Master Configuration
-=============
+===========================
 
 A folder can be set in "master mode" among the folder settings.