Merge pull request #7 from rumpelsepp/man

Create and enable manpages

conf.py

@@ -239,12 +239,37 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'syncthing', u'Syncthing Documentation',
+    ('users/config', 'syncthing-config',
-     [u'The Syncthing Authors'], 1)
+     'Syncthing Configuration',
+     ['The Syncthing Authors'], 5),
+    ('users/ignoring', 'syncthing-stignore',
+     'Prevent files from being synchronized to other nodes',
+     ['The Syncthing Authors'], 5),
+    ('dev/rest', 'syncthing-rest-api',
+     'REST API',
+     ['The Syncthing Authors'], 7),
+    ('dev/events', 'syncthing-event-api',
+     'Event API',
+     ['The Syncthing Authors'], 7),
+    ('dev/device-ids', 'syncthing-device-ids',
+     'Understanding Device IDs',
+     ['The Syncthing Authors'], 7),
+    ('users/security', 'syncthing-security',
+     'Security Principles',
+     ['The Syncthing Authors'], 7),
+    ('users/firewall', 'syncthing-networking',
+     'Firewall Setup',
+     ['The Syncthing Authors'], 7),
+    ('users/versioning', 'syncthing-versioning',
+     'Keep automatic backups of deleted files by other nodes',
+     ['The Syncthing Authors'], 7),
+    ('users/faq', 'syncthing-faq',
+     'Frequently Asked Questions',
+     ['The Syncthing Authors'], 7),
 ]
 
 # If true, show URL addresses after external links.
-#man_show_urls = False
+man_show_urls = True
 
 
 # -- Options for Texinfo output -------------------------------------------

dev/device-ids.rst

@@ -1,28 +1,28 @@
-########################
 Understanding Device IDs
-########################
+========================
 
-Every device is identified by a device ID. The device ID is used for
+Description
-address resolution, authentication and authorization. The term "device
+-----------
-ID" could interchangably have been "key ID" since the device ID is a
+
-direct properties of the public key in use.
+Every device is identified by a device ID. The device ID is used for address
+resolution, authentication and authorization. The term "device ID" could
+interchangably have been "key ID" since the device ID is a direct properties of
+the public key in use.
 
 Keys
-====
+----
 
-To understand device IDs we need to look at the underlying mechanisms.
+To understand device IDs we need to look at the underlying mechanisms. At first
-At first startup, Syncthing will create an public/private key pair.
+startup, Syncthing will create an public/private key pair.
 
-Currently this is a 3072 bit RSA key. The keys are saved in the form of
+Currently this is a 3072 bit RSA key. The keys are saved in the form of the
-the private key (``key.pem``) and a self signed certificate
+private key (``key.pem``) and a self signed certificate (``cert.pem``). The self
-(``cert.pem``). The self signing part doesn't actually add any security
+signing part doesn't actually add any security or functionality as far as
-or functionality as far as Syncthing is concerned but it enables the use
+Syncthing is concerned but it enables the use of the keys in a standard TLS
-of the keys in a standard TLS exchange.
+exchange.
 
 The typical certificate will look something like this, inspected with
-``openssl x509``:
+``openssl x509``::
-
-::
 
     Certificate:
         Data:
@@ -58,28 +58,26 @@ The typical certificate will look something like this, inspected with
             88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db:
             df:54:b9:4e:be:1b
 
-We can see here that the certificate is little more than a container for
+We can see here that the certificate is little more than a container for the
-the public key; the serial number is zero and the Issuer and Subject are
+public key; the serial number is zero and the Issuer and Subject are both
-both "syncthing" where a qualified name might otherwise be expected.
+"syncthing" where a qualified name might otherwise be expected.
 
-An advanced user could replace the ``key.pem`` and ``cert.pem`` files
+An advanced user could replace the ``key.pem`` and ``cert.pem`` files with a
-with a keypair generated directly by the ``openssl`` utility or other
+keypair generated directly by the ``openssl`` utility or other mechanism.
-mechanism.
 
 Device IDs
-==========
+----------
 
-To form a device ID the SHA-256 hash of the certificate data in DER form
+To form a device ID the SHA-256 hash of the certificate data in DER form is
-is calculated. This means the hash covers all information under the
+calculated. This means the hash covers all information under the
 ``Certificate:`` section above.
 
-The hashing results in a 256 bit hash, which we encode using base32.
+The hashing results in a 256 bit hash, which we encode using base32. Base32
-Base32 encodes five bits per character, so we need 256 / 5 = 51.2
+encodes five bits per character, so we need 256 / 5 = 51.2 characters to encode
-characters to encode the device ID. This becomes 52 characters in
+the device ID. This becomes 52 characters in practice, but 52 characters of
-practice, but 52 characters of base32 would decode to 260 bits which is
+base32 would decode to 260 bits which is not an whole number of bytes. The
-not an whole number of bytes. The base32 encoding adds padding to 280
+base32 encoding adds padding to 280 bits (the next multiple of both 5 and 8
-bits (the next multiple of both 5 and 8 bits) so the resulting ID looks
+bits) so the resulting ID looks something like
-something like
 ``MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====``.
 
 The padding (``====``) is stripped away, the device ID split in four
@@ -90,13 +88,12 @@ grouped with dashes, resulting in the final value:
 ``MFZWI3D-BONSGYC-YLTMRWG-C43ENR5 -QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD``.
 
 Connection Establishment
-========================
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-So now we know what device IDs are, here's how they are used in
+So now we know what device IDs are, here's how they are used in Syncthing. When
-Syncthing. When you add a device ID to the syncthing configuration,
+you add a device ID to the syncthing configuration, Syncthing will attempt to
-Syncthing will attempt to connect to that device. The first thing we
+connect to that device. The first thing we need to do is figure out the IP and
-need to do is figure out the IP and port to connect to. There's three
+port to connect to. There's three possibilities here;
-possibilities here;
 
 -  The IP and port can be set statically in the configuration. The IP
    can equally well be a hostname, so if you have a static IP or a
@@ -114,10 +111,10 @@ possibilities here;
    any local announcements the global discovery server will be queried
    for an address.
 
-Once we have and address and port a TCP connection is established and a
+Once we have and address and port a TCP connection is established and a TLS
-TLS handshake performed. As part of the handshake both devices present
+handshake performed. As part of the handshake both devices present their
-their certificates. Once the handshake has completed and the peer
+certificates. Once the handshake has completed and the peer certificate is
-certificate is known, the following steps are performed.
+known, the following steps are performed.
 
 #. Calculate the remote device ID by using the process above on the
    received certificate.
@@ -169,27 +166,26 @@ here:
     more probable than the SHA-256 collision. Briefly stated, if you
     find SHA-256 collisions scary then your priorities are wrong.
 
-It's also worth noting that the property of SHA-256 that we are using is
+It's also worth noting that the property of SHA-256 that we are using is not
-not simply collision resistance but resistance to a preimage attack.
+simply collision resistance but resistance to a preimage attack. I.e. even if
-I.e. even if you can find two messages that result in a hash collision
+you can find two messages that result in a hash collision that doesn't help you
-that doesn't help you attack Syncthing (or TLS in general). You need to
+attack Syncthing (or TLS in general). You need to create a message that hashes
-create a message that hashes to exactly the hash that my certificate
+to exactly the hash that my certificate already has or you won't get in.
-already has or you won't get in.
 
-Note also that it's not good enough to find a random blob of bits that
+Note also that it's not good enough to find a random blob of bits that happen to
-happen to have the same hash as my certificate. You need to create a
+have the same hash as my certificate. You need to create a valid DER- encoded,
-valid DER- encoded, signed certificate that has the same hash as mine.
+signed certificate that has the same hash as mine. The difficulty of this is
-The difficulty of this is staggeringly far beyond the already staggering
+staggeringly far beyond the already staggering difficulty of finding a SHA-256
-difficulty of finding a SHA-256 collision.
+collision.
 
 Problems and Vulnerabilities
-============================
+----------------------------
 
 As far as I know, these are the issues or potential issues with the
 above mechanism.
 
 Discovery Spoofing
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Currently, neither the local nor global discovery mechanism is protected
 by crypto. This means that any device can in theory announce itself for
@@ -217,13 +213,13 @@ It's something we might want to look at at some point, but not a huge
 problem as I see it.
 
 Long Device IDs are Painful
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It's a mouthful to read over the phone, annoying to type into an SMS or
+It's a mouthful to read over the phone, annoying to type into an SMS or even
-even into a computer. And it needs to be done twice, once for each side.
+into a computer. And it needs to be done twice, once for each side.
 
-This isn't a vulnerability as such, but a user experience problem. There
+This isn't a vulnerability as such, but a user experience problem. There are
-are various possible solutions;
+various possible solutions:
 
 -  Use shorter device IDs with verification based on the full ID ("You
    entered MFZWI3; I found and connected to a device with the ID

dev/events.rst

@@ -1,8 +1,11 @@
 Event API
 =========
 
-Syncthing provides a simple long polling interface for exposing events from
+Description
-the core utility towards a GUI.
+-----------
+
+Syncthing provides a simple long polling interface for exposing events from the
+core utility towards a GUI.
 
 To receive events, perform a HTTP GET of ``/rest/events?since=<lastSeenID>``,
 where ``<lastSeenID>`` is the ID of the last event you've already seen or zero.
@@ -26,28 +29,36 @@ Event Structure
 
 Each event is represented by an object similar to the following::
 
-	{
+    {
-	    "id": 2,
+        "id": 2,
-	    "type": "DeviceConnected",
+        "type": "DeviceConnected",
-	    "time": "2014-07-13T21:04:33.687836696+02:00",
+        "time": "2014-07-13T21:04:33.687836696+02:00",
-	    "data": {
+        "data": {
-	        "addr": "172.16.32.25:22000",
+            "addr": "172.16.32.25:22000",
-	        "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
+            "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
-	    }
+        }
-	}
+    }
 
-The top level keys ``id``, ``time``, ``type`` and ``data`` are always present, though ``data`` may be ``null``.
+The top level keys ``id``, ``time``, ``type`` and ``data`` are always present,
+though ``data`` may be ``null``.
 
-* ``id`` is a monotonically increasing integer. The first event generated has id ``1``, the next has id ``2`` etc.
+id
-* ``time`` is the time the event was generated.
+    A monotonically increasing integer. The first event generated has id ``1``,
-* ``type`` indicates the type of (i.e. reason for) the event and is one of the event types below.
+    the next has id ``2`` etc.
-* ``data`` is an object containing optional extra information; the exact structure is determined by the event type.
+time
+    The time the event was generated.
+type
+    Indicates the type of (i.e. reason for) the event and is one of the event
+    types below.
+data
+    An object containing optional extra information; the exact structure is
+    determined by the event type.
 
 Events
 ------
 
 .. toctree::
-	:maxdepth: 2
+    :maxdepth: 2
-	:glob:
+    :glob:
 
-	../events/*
+    ../events/*

dev/rest.rst

@@ -1,19 +1,21 @@
 REST API
 ========
 
-Syncthing exposes a REST interface over HTTP on the GUI port. This is
+Description
-used by the GUI code (JavaScript) and can be used by other processes
+-----------
-wishing to control Syncthing. In most cases both the input and output
+
-data is in JSON format. The interface is subject to change.
+Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
+the GUI code (JavaScript) and can be used by other processes wishing to control
+Syncthing. In most cases both the input and output data is in JSON format. The
+interface is subject to change.
 
 API Key
 -------
 
-To use the POST methods, or *any* method when authentication is enabled,
+To use the POST methods, or *any* method when authentication is enabled, an API
-an API key must be set and used. The API key can be generated in the
+key must be set and used. The API key can be generated in the GUI, or set in the
-GUI, or set in the ``configuration/gui/apikey`` element in the
+``configuration/gui/apikey`` element in the configuration file. To use an API
-configuration file. To use an API key, set the request header
+key, set the request header ``X-API-Key`` to the API key value.
-``X-API-Key`` to the API key value.
 
 System Endpoints
 ----------------

users/config.rst

@@ -1,35 +1,51 @@
-###################
+Syncthing Configuration
-Configuration Files
+=======================
-###################
 
 .. warning::
   This page may be outdated and requires review.
   Attributes have been added that are not documented.
 
-Syncthing uses a single directory to store configuration, crypto keys
+Synopsis
-and index caches. The location defaults to ``~/.config/syncthing``
+--------
-(Unixes), ``%AppData%/Syncthing`` (Windows XP),
-``%localappdata%/Syncthing`` (Windows 7/8) or
-``~/Library/Application Support/Syncthing`` (Mac) but is also settable
-at runtime using the ``-home`` flag. In this directory you'll generally
-see something like the following files:
 
--  ``cert.pem``: The device's RSA public key, named "cert" for legacy
+::
-   reasons.
+
--  ``key.pem``: The device's RSA private key. This needs to be
+    $HOME/.config/syncthing/config.xml
-   protected.
+    $HOME/Library/Application Support/Syncthing
--  ``config.xml``: The configuration file, in XML format.
+    %AppData%/Syncthing
--  ``https-cert.pem`` and ``https-key.pem``: The certificate and key for
+    %localappdata%/Syncthing
-   HTTPS GUI connections.
+
--  ``index/``: A directory holding the database with metadata and hashes
+Description
-   of the files currently on disk and available from peers.
+-----------
--  ``csrftokens.txt``: A list of recently issued CSRF tokens (for
+
-   protection against browser cross site request forgery).
+Syncthing uses a single directory to store configuration, crypto keys
+and index caches. The location defaults to ``$HOME/.config/syncthing``
+(Unix-like), ``$HOME/Library/Application Support/Syncthing`` (Mac),
+``%AppData%/Syncthing`` (Windows XP) or ``%localappdata%/Syncthing``
+(Windows 7/8). It can be changed at runtime using the ``-home`` flag. In this
+directory the following files are located:
+
+cert.pem
+    The device's RSA public key, named "cert" for legacy reasons.
+key.pem
+    The device's RSA private key. This needs to be protected.
+config.xml
+    The configuration file, in XML format.
+https-cert.pem
+    The certificate for HTTPS GUI connections.
+https-key.pem
+    The key for HTTPS GUI connections.
+index/
+    A directory holding the database with metadata and hashes of the files
+    currently on disk and available from peers.
+csrftokens.txt
+    A list of recently issued CSRF tokens (for protection against browser cross
+    site request forgery).
 
 Config File Format
-==================
+------------------
 
-The following is an example default configuration file:
+The following is shows the default configuration file:
 
 .. code-block:: xml
 
@@ -62,20 +78,16 @@ The following is an example default configuration file:
         </options>
     </configuration>
 
-The following sections should be present in a well formed config file.
-
 configuration
--------------
+~~~~~~~~~~~~~
 
-The root element.
+This is the root element.
 
-Attributes
+version
-~~~~~~~~~~
+    The config version. The current version is ``2``.
-
--  ``version``: The config version. ``2`` is current.
 
 folder
-------
+~~~~~~
 
 One or more ``folder`` elements must be present in the file. Each
 element describes one folder.
@@ -88,111 +100,92 @@ the file. It is customary that the local device ID is included in all
 repositories. Syncthing will currently add this automatically if it is
 not present in the configuration file.
 
-Attributes
+id
-~~~~~~~~~~
+    The folder ID, must be unique. (mandatory)
-
+directory
--  ``id``: The folder ID, must be unique. (mandatory)
+    The directory where the folder is stored on this
--  ``directory``: The directory where the folder is stored on this
+    device; not sent to other devices. (mandatory)
-   device; not sent to other devices. (mandatory)
+ro
--  ``ro``: True if the folder is read only (will not be modified by
+    True if the folder is read only (will not be modified by Syncthing) on this
-   Syncthing) on this device. (optional, defaults to ``false``)
+    device. (optional, defaults to ``false``)
--  ``ignorePerms``: True if the folder should `ignore
+ignorePerms
-   permissions <http://forum.syncthing.net/t/v0-8-10-ignore-permissions/263>`__.
+    True if the folder should `ignore permissions <http://forum.syncthing.net/t/263>`_.
-
-Children
-~~~~~~~~
-
--  One or mode ``device`` elements.
 
 device
-------
+~~~~~~
 
 One or more ``device`` elements must be present in the file. Each
 element describes a device participating in the cluster. It is customary
 to include a ``device`` element for the local device; Syncthing will
 currently add one if it is not present.
 
-Attributes
+id
-~~~~~~~~~~
+    The device ID. This must be written in canonical form, that is without any
-
+    spaces or dashes. (mandatory)
--  ``id``: The device ID. This must be written in canonical form, that
+name
-   is without any spaces or dashes. (mandatory)
+    A friendly name for the device. (optional)
--  ``name``: A friendly name for the device. (optional)
-
-Children
-~~~~~~~~
-
--  One or mode ``address`` elements.
-
 address
--------
+    The address section is only valid inside of ``device`` elements. It contains
+    a single address, on one of the following forms:
 
-The address section is only valid inside of ``device`` elements. It
+    - IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
-contains a single address, on one of the following forms:
+      optionally followed by a port number.
-
+    - ``dynamic``: The address will be resolved using discovery.
--  IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
-   optionally followed by a port number.
--  ``dynamic``: The address will be resolved using discovery.
 
 gui
----
+~~~
 
-There must be exactly one ``gui`` element.
+There must be *exactly one* ``gui`` element.
 
-Attributes
+enabled
-~~~~~~~~~~
+    ``true``/``false``
+tls
+    ``true``/``false``: If true then the GUI will use HTTPS.
 
--  ``enabled``: ``true``/``false``
+address
--  ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS
+    One or more address elements must be present, containing an ``ip:port``
+    listen address.
+username
+    Set to require authentication.
+password
+    Contains the bcrypt hash of the real password.
+apikey
+    If set, this is the API key that enables usage of the REST interface.
 
-Children
+Additionally, there must be *exactly one* ``options`` element. It contains the
-~~~~~~~~
+following configuration settings as children:
 
--  ``address``: One or more address elements must be present, containing
+listenAddress
-   an ``ip:port`` listen address.
+    ``host:port`` or ``:port`` string denoting an address to listen for BEP
--  ``username`` and ``password``: Set to require authentication.
+    connections. More than one ``listenAddress`` may be given.
-   ``password`` contains the bcrypt hash of the real password.
+    (default: ``0.0.0.0:22000``)
--  ``apikey``: If set, this is the API key that enables usage of the REST interface.
+globalAnnounceServer
-
+    ``host:port``  string denoting where a global announce server may be
-options
+    reached. (default: ``announce.syncthing.net:22025``)
--------
+globalAnnounceEnabled
-
+    ``true``/``false`` (default: ``true``)
-There must be exactly one ``options`` element. It contains the following
+localAnnounceEnabled
-configuration settings as children;
+    ``true``/``false`` (default: ``true``)
-
+parallelRequests
--  ``listenAddress`` : ``host:port`` or ``:port`` string denoting an
+    The maximum number of outstanding block requests to have against any given
-   address to listen for BEP (sync protocol) connections. More than one
+    peer. (default: ``16``)
-   ``listenAddress`` may be given. (default ``0.0.0.0:22000``)
+maxSendKbps
-
+    Rate limit
--  ``globalAnnounceServer`` : ``host:port`` where a global announce
+rescanIntervalS
-   server may be reached. (default \`announce.syncthing.net:22025´)
+    The number of seconds to wait between each scan for modification of the
-
+    local repositories. A value of ``0`` disables the scanner. (default: ``60``)
--  ``globalAnnounceEnabled``: ``true``/``false`` (default ``true``)
+reconnectionIntervalS
-
+    The number of seconds to wait between each attempt to connect to currently
--  ``localAnnounceEnabled``: ``true``/``false`` (default ``true``)
+    unconnected devices. (default: ``60``)
-
+maxChangeKbps
--  ``parallelRequests``: The maximum number of outstanding block
+    The maximum rate of change allowed for a single file. When this rate is
-   requests to have against any given peer. (default ``16``)
+    exceeded, further changes to the file are not announced, until the rate is
-
+    reduced below the limit. (default: ``10000``)
--  ``maxSendKbps``: Rate limit
+startBrowser
-
+    ``true``/``false`` (default: ``true``)
--  ``rescanIntervalS``: The number of seconds to wait between each scan
+upnpEnabled
-   for modification of the local repositories. (default ``60``) A value
+    ``true``/``false`` (default: ``true``)
-   of 0 disables the scanner.
+urAccepted
-
+    Whether the user as accepted to submit anonymous usage data. The default,
--  ``reconnectionIntervalS``: The number of seconds to wait between each
+    ``0``, mean the user has not made a choice, and Syncthing will ask at some
-   attempt to connect to currently unconnected devices. (default ``60``)
+    point in the future. ``-1`` means no, ``1`` means yes.
-
--  ``maxChangeKbps``: The maximum rate of change allowed for a single
-   file. When this rate is exceeded, further changes to the file are not
-   announced, until the rate is reduced below the limit. (default
-   ``10000``)
-
--  ``startBrowser``: ``true``/``false`` (default ``true``)
-
--  ``upnpEnabled``: ``true``/``false`` (default ``true``)
-
--  ``urAccepted``: Whether the user as accepted to submit anonymous
-   usage data. The default, ``0``, mean the user has not made a choice,
-   and Syncthing will ask at some point in the future. ``-1`` means no,
-   ``1`` means yes.

users/faq.rst

@@ -9,39 +9,36 @@ General
 What is Syncthing?
 ~~~~~~~~~~~~~~~~~~
 
-Syncthing is an application that lets you synchronize your files across
+Syncthing is an application that lets you synchronize your files across multiple
-multiple devices. This means the creation, modification or deletion of
+devices. This means the creation, modification or deletion of files on one
-files on one machine will automatically be replicated to your other
+machine will automatically be replicated to your other devices. We believe your
-devices. We believe your data is your data alone and you deserve to
+data is your data alone and you deserve to choose where it is stored. Therefore
-choose where it is stored. Therefore Syncthing does not upload your data
+Syncthing does not upload your data to the cloud but exchanges your data across
-to the cloud but exchanges your data across your machines as soon as
+your machines as soon as they are online at the same time.
-they are online at the same time.
 
 Is it "syncthing", "Syncthing" or "SyncThing"?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It's **Syncthing**, although the command and source repository is
+It's **Syncthing**, although the command and source repository is spelled
-spelled ``syncthing`` so it may be referred to in that way as well. It's
+``syncthing`` so it may be referred to in that way as well. It's definitely not
-definitely not :strike:`SyncThing`, even though the abbreviation
+:strike:`SyncThing`, even though the abbreviation ``st`` is used in some
-``st`` is used in some circumstances and file names.
+circumstances and file names.
 
 How does Syncthing differ from BitTorrent Sync?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The two are different and not related. Syncthing and BitTorrent Sync
+The two are different and not related. Syncthing and BitTorrent Sync accomplish
-accomplish some of the same things, namely syncing files between two or
+some of the same things, namely syncing files between two or more computers.
-more computers.
 
 BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file
-synchronization tool available for Windows, Mac, Linux, Android, iOS,
+synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows
-Windows Phone, Amazon Kindle Fire and BSD.
+Phone, Amazon Kindle Fire and BSD. `1
-`1 <http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an
+<http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an open source
-open source file synchronization tool.
+file synchronization tool.
 
-Syncthing uses an open and documented protocol, and likewise the
+Syncthing uses an open and documented protocol, and likewise the security
-security mechanisms in use are well defined and visible in the source
+mechanisms in use are well defined and visible in the source code. BitTorrent
-code. BitTorrent Sync uses an undocumented, closed protocol with unknown
+Sync uses an undocumented, closed protocol with unknown security properties.
-security properties.
 
 Usage
 -----
@@ -49,12 +46,12 @@ Usage
 What things are synced?
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-The following things are *always* synchronized;
+The following things are *always* synchronized:
 
 -  File Contents
 -  File Modification Times
 
-The following may be synchronized or not, depending;
+The following may be synchronized or not, depending:
 
 -  File Permissions (When supported by file system. On Windows, only the
    read only bit is synchronized.)
@@ -75,17 +72,16 @@ The following is *not* synchronized;
 Is synchronization fast?
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Syncthing segments files into pieces, called blocks, to transfer data
+Syncthing segments files into pieces, called blocks, to transfer data from one
-from one device to another. Therefore, multiple devices can share the
+device to another. Therefore, multiple devices can share the synchronization
-synchronization load, in a similar way as the torrent protocol. The more
+load, in a similar way as the torrent protocol. The more devices you have online
-devices you have online (and synchronized), the faster an additional
+(and synchronized), the faster an additional device will receive the data
-device will receive the data because small blocks will be fetched from
+because small blocks will be fetched from all devices in parallel.
-all devices in parallel.
 
-Syncthing handles renaming files and updating their metadata in an
+Syncthing handles renaming files and updating their metadata in an efficient
-efficient manner. This means that renaming a large file will not cause a
+manner. This means that renaming a large file will not cause a retransmission of
-retransmission of that file. Additionally, appending data to existing
+that file. Additionally, appending data to existing large files should be
-large files should be handled efficiently as well.
+handled efficiently as well.
 
 Temporary files are used to store partial data downloaded from other devices.
 They are automatically removed whenever a file transfer has been completed or
@@ -95,63 +91,60 @@ hours by default).
 Should I keep my device IDs secret?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No. The IDs are not sensitive. Given a device ID it's possible to find
+No. The IDs are not sensitive. Given a device ID it's possible to find the IP
-the IP address for that node, if global discovery is enabled on it.
+address for that node, if global discovery is enabled on it. Knowing the device
-Knowing the device ID doesn't help you actually establish a connection
+ID doesn't help you actually establish a connection to that node or get a list
-to that node or get a list of files, etc.
+of files, etc.
 
-For a connection to be established, both nodes need to know about the
+For a connection to be established, both nodes need to know about the other's
-other's device ID. It's not possible (in practice) to forge a device ID.
+device ID. It's not possible (in practice) to forge a device ID. (To forge a
-(To forge a device ID you need to create a TLS certificate with that
+device ID you need to create a TLS certificate with that specific SHA-256 hash.
-specific SHA-256 hash. If you can do that, you can spoof any TLS
+If you can do that, you can spoof any TLS certificate. The world is your
-certificate. The world is your oyster!)
+oyster!)
 
-See also `Understanding Device
+.. see-also::
-IDs <http://docs.syncthing.net/dev/device-ids.html>`__.
+    :ref:`dev/device-ids`
 
 What if there is a conflict?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Syncthing does recognize conflicts. When a file has been modified on two
+Syncthing does recognize conflicts. When a file has been modified on two devices
-devices simultaneously, one of the files will be renamed to
+simultaneously, one of the files will be renamed to ``<filename>.sync-
-``<filename>.sync- conflict-<date>-<time>.<ext>``. The device which has
+conflict-<date>-<time>.<ext>``. The device which has the larger value of the
-the larger value of the first 63 bits for his device ID will have his
+first 63 bits for his device ID will have his file marked as the conflicting
-file marked as the conflicting file. Note that we only create
+file. Note that we only create ``sync-conflict`` files when the actual content
-``sync-conflict`` files when the actual content differs.
+differs.
 
-Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` files
+Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` files are
-are treated as normal files after they are created, so they are
+treated as normal files after they are created, so they are propagated between
-propagated between devices. We do this because the conflict is detected
+devices. We do this because the conflict is detected and resolved on one device,
-and resolved on one device, creating the ``sync-conflict`` file, but
+creating the ``sync-conflict`` file, but it's just as much of a conflict
-it's just as much of a conflict everywhere else and we don't know which
+everywhere else and we don't know which of the conflicting files is the "best"
-of the conflicting files is the "best" from the user point of view.
+from the user point of view. Moreover, if there's something that automatically
-Moreover, if there's something that automatically causes a conflict on
+causes a conflict on change you'll end up with ``sync-conflict-...sync-conflict
-change you'll end up with
+-...-sync-conflict`` files.
-``sync-conflict-...sync-conflict -...-sync-conflict`` files.
 
 How to configure multiple users on a single machine?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Each user should run their own Syncthing instance. Be aware that you
+Each user should run their own Syncthing instance. Be aware that you might need
-might need to configure ports such that they do not overlap (see the
+to configure ports such that they do not overlap (see the config.xml).
-config.xml).
 
 Is Syncthing my ideal backup application?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No, Syncthing is not a backup application because all changes to your
+No, Syncthing is not a backup application because all changes to your files
-files (modification, deletion, etc) will be propagated to all your
+(modification, deletion, etc) will be propagated to all your devices. You can
-devices. You can enable versioning, but we encourage the use of other
+enable versioning, but we encourage the use of other tools to keep your data
-tools to keep your data safe from your (or our) mistakes.
+safe from your (or our) mistakes.
 
 Why is there no iOS client?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Alternative implementation Syncthing (using the Syncthing protocol) are
+Alternative implementation Syncthing (using the Syncthing protocol) are being
-being developed at this point in time to enable iOS support.
+developed at this point in time to enable iOS support. Additionally, it seems
-Additionally, it seems that the next version of Go will support the
+that the next version of Go will support the darwin-arm architecture such that
-darwin-arm architecture such that we can compile the mainstream code for
+we can compile the mainstream code for the iOS platform.
-the iOS platform.
 
 Why does it use so much CPU?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -163,35 +156,34 @@ Why does it use so much CPU?
    encrypted using AES-128. When receiving data, it must be decrypted
    and decompressed.
 
-Hashing, compression and encryption cost CPU time. Also, using the GUI
+Hashing, compression and encryption cost CPU time. Also, using the GUI causes a
-causes a certain amount of CPU usage. Note however that once things are
+certain amount of CPU usage. Note however that once things are *in sync* CPU
-*in sync* CPU usage should be negligible.
+usage should be negligible.
 
 How can I exclude files with brackets (``[]``) in the name?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The patterns in .stignore are glob patterns, where brackets are used to
+The patterns in .stignore are glob patterns, where brackets are used to denote
-denote character ranges. That is, the pattern ``q[abc]x`` will match the
+character ranges. That is, the pattern ``q[abc]x`` will match the files ``qax``,
-files ``qax``, ``qbx`` and ``qcx``.
+``qbx`` and ``qcx``.
 
-To match an actual file *called* ``q[abc]x`` the pattern needs to
+To match an actual file *called* ``q[abc]x`` the pattern needs to "escape" the
-"escape" the brackets, like so: ``q\[abc\]x``.
+brackets, like so: ``q\[abc\]x``.
 
 Why is the setup more complicated than BTSync?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Security over convenience. In Syncthing you have to setup both sides to
+Security over convenience. In Syncthing you have to setup both sides to connect
-connect two nodes. An attacker can't do much with a stolen node ID,
+two nodes. An attacker can't do much with a stolen node ID, because you have to
-because you have to add the node on the other side too. You have better
+add the node on the other side too. You have better control where your files are
-control where your files are transferred.
+transferred.
 
 How do I access the web GUI from another computer?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The default listening address is 127.0.0.1:8384, so you can only access
+The default listening address is 127.0.0.1:8384, so you can only access the GUI
-the GUI from the same machine. Change the ``GUI listen address`` through
+from the same machine. Change the ``GUI listen address`` through the web UI from
-the web UI from ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the
+``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the config.xml:
-config.xml:
 
 .. code-block:: xml
 
@@ -208,58 +200,60 @@ to
 Then the GUI is accessible from everywhere. You should most likely set a
 password and enable HTTPS now. You can do this from inside the GUI.
 
-If both your computers are Unixy (Linux, Mac, etc) You can also leave
+If both your computers are Unixy (Linux, Mac, etc) You can also leave the GUI
-the GUI settings at default and use an ssh port forward to access it.
+settings at default and use an ssh port forward to access it. For example,
-For example,
 
 .. code-block:: bash
 
     $ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
 
-will log you into othercomputer.example.com, and present the *remote*
+will log you into othercomputer.example.com, and present the *remote* Syncthing
-Syncthing GUI on http://localhost:9090 on your *local* computer. You
+GUI on http://localhost:9090 on your *local* computer. You should not open more
-should not open more than one Syncthing GUI in a single browser due to
+than one Syncthing GUI in a single browser due to conflicting X-CSRFTokens. Any
-conflicting X-CSRFTokens. Any modification will be rejected. See `Issue
+modification will be rejected. See `Issue 720
-720 <https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__
+<https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__ to
-to work around this limitation.
+work around this limitation.
 
-The CSRF tokens are stored using cookies. Therefore, if you get the
+The CSRF tokens are stored using cookies. Therefore, if you get the message
-message
+``Syncthing seems to be experiencing a problem processing your request``, you
-``Syncthing seems to be experiencing a problem processing your request``,
+should verify the cookie settings of your browser.
-you should verify the cookie settings of your browser.
 
 Why do I see Syncthing twice in task manager?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-One process manages the other, to capture logs and manage restarts. This
+One process manages the other, to capture logs and manage restarts. This makes
-makes it easier to handle upgrades from within Syncthing itself, and
+it easier to handle upgrades from within Syncthing itself, and also ensures that
-also ensures that we get a nice log file to help us narrow down the
+we get a nice log file to help us narrow down the cause for crashes and other
-cause for crashes and other bugs.
+bugs.
 
 Where do Syncthing logs go to?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Syncthing logs to stdout by default. On Windows Syncthing by default
+Syncthing logs to stdout by default. On Windows Syncthing by default also
-also creates ``syncthing.log`` in Syncthing's home directory (check
+creates ``syncthing.log`` in Syncthing's home directory (check ``-help`` to see
-``-help`` to see where that is).
+where that is).
 
 How do I upgrade Syncthing?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- If automatic upgrades is enabled (which is the default), Syncthing will upgrade itself automatically within 24 hours of a new release.
+- If automatic upgrades is enabled (which is the default), Syncthing will
+  upgrade itself automatically within 24 hours of a new release.
 
-- The upgrade button appears in the web GUI when a new version has been released. Pressing it will perform an upgrade.
+- The upgrade button appears in the web GUI when a new version has been released.
+  Pressing it will perform an upgrade.
 
 - To force an upgrade from the command line, run ``syncthing -upgrade``.
 
-Note that your system should have CA certificates installed which allow a secure connection to GitHub (e.g. FreeBSD requires `sudo pkg install ca_root_nss`). If ``curl`` or ``wget`` works with normal HTTPS sites, then so should Syncthing.
+Note that your system should have CA certificates installed which allow a secure
+connection to GitHub (e.g. FreeBSD requires ``sudo pkg install ca_root_nss``).
+If ``curl`` or ``wget`` works with normal HTTPS sites, then so should Syncthing.
 
 Where do I find the latest release?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We release new versions through GitHub. The latest release is always found `on
 the release page <https://github.com/syncthing/syncthing/releases/latest>`_.
-Unfortunately GitHub does not provide a single URL to automatically download
+Unfortunately GitHub does not provide a single URL to automatically download the
-the latest version. We suggest to use the GitHub API at
+latest version. We suggest to use the GitHub API at
-https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing
+https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing the
-the JSON response.
+JSON response.

users/firewall.rst

@@ -6,29 +6,27 @@ Firewall Setup
 Port Forwards
 -------------
 
-If you have a NAT router which supports UPnP, the easiest way to get a
+If you have a NAT router which supports UPnP, the easiest way to get a working
-working port forward is to make sure UPnP setting is enabled on both
+port forward is to make sure UPnP setting is enabled on both Syncthing and the
-Syncthing and the router – Syncthing will try to handle the rest. If it
+router – Syncthing will try to handle the rest. If it succeeds you will see a
-succeeds you will see a message in the console saying:
+message in the console saying::
-
-::
 
     Created UPnP port mapping for external port XXXXX on UPnP device YYYYY.
 
-If this is not possible or desirable you should set up a port forward
+If this is not possible or desirable you should set up a port forward for port
-for port **22000/TCP**, or the port set in the *Sync Protocol Listen
+**22000/TCP**, or the port set in the *Sync Protocol Listen Address* setting.
-Address* setting. The external forwarded port and the internal
+The external forwarded port and the internal destination port has to be the same
-destination port has to be the same (i.e. 22000/TCP).
+(i.e. 22000/TCP).
 
 Communication in Syncthing works both ways. Therefore if you set up port
-forwards for one device, other devices will be able to connect to it
+forwards for one device, other devices will be able to connect to it even when
-even when they are behind a NAT network or firewall.
+they are behind a NAT network or firewall.
 
 Local Firewall
 --------------
 
-If your PC has a local firewall, you will need to open the following
+If your PC has a local firewall, you will need to open the following ports for
-ports for incoming traffic:
+incoming traffic:
 
 -  Port **22000/TCP** (or the actual listening port if you have changed
    the *Sync Protocol Listen Address* setting.)
@@ -37,29 +35,25 @@ ports for incoming traffic:
 Remote Web GUI
 --------------
 
-To be able to access the web GUI from other computers, you need to
+To be able to access the web GUI from other computers, you need to change the
-change the *GUI Listen Address* setting from the default
+*GUI Listen Address* setting from the default ``127.0.0.1:8384`` to
-``127.0.0.1:8384`` to ``0.0.0.0:8384``. You also need to open the port
+``0.0.0.0:8384``. You also need to open the port in your local firewall if you
-in your local firewall if you have one.
+have one.
 
 Tunneling via SSH
 ~~~~~~~~~~~~~~~~~
 
-If you have SSH access to the machine running Syncthing but would rather
+If you have SSH access to the machine running Syncthing but would rather not
-not open the web GUI port to the outside world, you can access it
+open the web GUI port to the outside world, you can access it through a SSH
-through a SSH tunnel instead. You can start a tunnel with a command like
+tunnel instead. You can start a tunnel with a command like the following::
-the following:
-
-::
 
     ssh -L 9999:localhost:8384 machine
 
-This will bind to your local port 9999 and forward all connections from
+This will bind to your local port 9999 and forward all connections from there to
-there to port 8384 on the target machine. This still works even if
+port 8384 on the target machine. This still works even if Syncthing is bound to
-Syncthing is bound to listen on localhost only.
+listen on localhost only.
 
-You can forward multiple ports corresponding to many machines this way,
+You can forward multiple ports corresponding to many machines this way, but
-but because Syncthing uses session cookies for the entire domain (i.e.
+because Syncthing uses session cookies for the entire domain (i.e. your local
-your local machine), you will need to connect to each control panel in a
+machine), you will need to connect to each control panel in a separate browser
-separate browser instance or explicitly issue a browser reload when
+instance or explicitly issue a browser reload when switching between them.
-switching between them.

users/ignoring.rst

@@ -1,12 +1,22 @@
 Ignoring Files
 ==============
 
+Synopsis
+--------
+
+::
+
+    .stignore
+
+Description
+-----------
+
 If some files should not be synchronized to other nodes, a file called
 ``.stignore`` can be created containing file patterns to ignore. The
 ``.stignore`` file must be placed in the root of the repository. The
-``.stignore`` file itself will never be synced to other nodes, although
+``.stignore`` file itself will never be synced to other nodes, although it can
-it can ``#include`` files that *are* synchronized between nodes. All
+``#include`` files that *are* synchronized between nodes. All patterns are
-patterns are relative to the repository root.
+relative to the repository root.
 
 Patterns
 --------
@@ -59,9 +69,7 @@ The ``.stignore`` file contains a list of file or path patterns. The
 Example
 -------
 
-Given a directory layout:
+Given a directory layout::
-
-::
 
     foo
     foofoo
@@ -75,9 +83,7 @@ Given a directory layout:
     My Pictures/
         Img15.PNG
 
-and an ``.stignore`` file with the contents:
+and an ``.stignore`` file with the contents::
-
-::
 
     !frobble
     !quuz
@@ -87,9 +93,7 @@ and an ``.stignore`` file with the contents:
     (?i)my pictures
 
 all files and directories called "foo", ending in a "2" or starting with
-"qu" will be ignored. The end result becomes
+"qu" will be ignored. The end result becomes::
-
-::
 
     foo           # ignored, matches "foo"
     foofoo        # synced, does not match "foo" but would match "foo*" or "*foo"

users/security.rst

@@ -1,126 +1,116 @@
-###################
 Security Principles
-###################
-
-Security is one of the primary project goals. This means that it should
-not be possible for an attacker to join a cluster uninvited, and it
-should not be possible to extract private information from intercepted
-traffic. Currently this is implemented as follows.
-
-All traffic is protected by TLS. To prevent uninvited nodes from joining
-a cluster, the certificate fingerprint of each node is compared to a
-preset list of acceptable nodes at connection establishment. The
-fingerprint is computed as the SHA-256 hash of the certificate and
-displayed in BASE32 encoding to form a reasonably compact and convenient
-string.
-
-Incoming requests for file data are verified to the extent that the
-requested file name must exist in the local index and the global model.
-
-For information about ensuring you are running the code you think you
-are and for reporting security vulnerabilities, please see the official
-`security page <http://syncthing.net/security.html>`__.
-
-Information Leakage
 ===================
 
+Security is one of the primary project goals. This means that it should not be
+possible for an attacker to join a cluster uninvited, and it should not be
+possible to extract private information from intercepted traffic. Currently this
+is implemented as follows.
+
+All traffic is protected by TLS. To prevent uninvited nodes from joining a
+cluster, the certificate fingerprint of each node is compared to a preset list
+of acceptable nodes at connection establishment. The fingerprint is computed as
+the SHA-256 hash of the certificate and displayed in BASE32 encoding to form a
+reasonably compact and convenient string.
+
+Incoming requests for file data are verified to the extent that the requested
+file name must exist in the local index and the global model.
+
+For information about ensuring you are running the code you think you are and
+for reporting security vulnerabilities, please see the official `security page
+<http://syncthing.net/security.html>`__.
+
+Information Leakage
+-------------------
+
 Global Discovery
-----------------
+~~~~~~~~~~~~~~~~
 
-When global discovery is enabled, Syncthing sends an announcement packet
+When global discovery is enabled, Syncthing sends an announcement packet every
-every 30 minutes to the global discovery server, so that it can keep a
+30 minutes to the global discovery server, so that it can keep a mapping between
-mapping between your device ID and external IP. Also, when connecting to
+your device ID and external IP. Also, when connecting to other devices that have
-other devices that have not been seen on the local network, a query is
+not been seen on the local network, a query is sent to the global discovery
-sent to the global discovery server containing the device ID of the
+server containing the device ID of the requested device. The discovery server is
-requested device. The discovery server is currently **hosted by
+currently **hosted by @calmh**. Global discovery defaults to **on**.
-@calmh**. Global discovery defaults to **on**.
 
-When turned off, devices with dynamic addresses not on the local network
+When turned off, devices with dynamic addresses not on the local network cannot
-cannot be found and connected to.
+be found and connected to.
 
-If a different global discovery server is configured, no data is sent to
+If a different global discovery server is configured, no data is sent to the
-the default global discovery server.
+default global discovery server.
 
 Local Discovery
----------------
+~~~~~~~~~~~~~~~
 
-When local discovery is enabled, Syncthing sends broadcast (IPv4) and
+When local discovery is enabled, Syncthing sends broadcast (IPv4) and multicast
-multicast (IPv6) packets to the local network every 30 seconds. The
+(IPv6) packets to the local network every 30 seconds. The packets contain the
-packets contain the device ID and listening port. Local discovery
+device ID and listening port. Local discovery defaults to **on**.
-defaults to **on**.
 
-An eavesdropper on the local network can deduce which machines are
+An eavesdropper on the local network can deduce which machines are running
-running Syncthing with local discovery enabled, and what their device
+Syncthing with local discovery enabled, and what their device IDs are.
-IDs are.
 
-When turned off, devices with dynamic addresses on the local network
+When turned off, devices with dynamic addresses on the local network cannot be
-cannot be found and connected to.
+found and connected to.
 
 Upgrade Checks
---------------
+~~~~~~~~~~~~~~
 
-When automatic upgrades are enabled, Syncthing checks for a new version
+When automatic upgrades are enabled, Syncthing checks for a new version at
-at startup and then once every twelve hours. This is by an HTTPS request
+startup and then once every twelve hours. This is by an HTTPS request to the
-to the download site for releases, currently **hosted at GitHub**.
+download site for releases, currently **hosted at GitHub**. Automatic upgrades
-Automatic upgrades default to **on** (unless Syncthing was compiled with
+default to **on** (unless Syncthing was compiled with upgrades disabled).
-upgrades disabled).
 
-Even when automatic upgrades are disabled in the configuration, an
+Even when automatic upgrades are disabled in the configuration, an upgrade check
-upgrade check as above is done when the GUI is loaded, in order to show
+as above is done when the GUI is loaded, in order to show the "Upgrade to ..."
-the "Upgrade to ..." button when necessary. This can be disabled only by
+button when necessary. This can be disabled only by compiling syncthing with
-compiling syncthing with upgrades disabled.
+upgrades disabled.
 
-In effect this exposes the majority of the Syncthing population to
+In effect this exposes the majority of the Syncthing population to tracking by
-tracking by the operator of the download site (currently GitHub). That
+the operator of the download site (currently GitHub). That data is not available
-data is not available to outside parties (including @calmh etc), except
+to outside parties (including @calmh etc), except that download counts per
-that download counts per release binary are available in the GitHub API.
+release binary are available in the GitHub API. The upgrade check (or download)
-The upgrade check (or download) requests *do not* contain any
+requests *do not* contain any identifiable information about the user, device,
-identifiable information about the user, device, Syncthing version, etc.
+Syncthing version, etc.
 
 Usage Reporting
----------------
+~~~~~~~~~~~~~~~
 
-When usage reporting is enabled, Syncthing reports usage data at startup
+When usage reporting is enabled, Syncthing reports usage data at startup and
-and then every 24 hours. The report is sent as an HTTPS POST to the
+then every 24 hours. The report is sent as an HTTPS POST to the usage reporting
-usage reporting server, currently **hosted by @calmh**. The contents of
+server, currently **hosted by @calmh**. The contents of the usage report can be
-the usage report can be seen behind the "Preview" link in settings.
+seen behind the "Preview" link in settings. Usage reporting defaults to **off**
-Usage reporting defaults to **off** but the GUI will ask once about
+but the GUI will ask once about enabling it, shortly after the first install.
-enabling it, shortly after the first install.
 
-The reported data is protected from eavesdroppers, but the connection to
+The reported data is protected from eavesdroppers, but the connection to the
-the usage reporting server itself may expose the client as running
+usage reporting server itself may expose the client as running Syncthing.
-Syncthing.
 
 Sync Connections (BEP)
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
-Sync connections are attempted to all configured devices, when the
+Sync connections are attempted to all configured devices, when the address is
-address is possible to resolve. The sync connection is based on TLS 1.2.
+possible to resolve. The sync connection is based on TLS 1.2. The TLS
-The TLS certificates are sent in clear text (as in HTTPS etc), meaning
+certificates are sent in clear text (as in HTTPS etc), meaning that the
-that the certificate Common Name (by default ``syncthing``) is visible.
+certificate Common Name (by default ``syncthing``) is visible.
 
-An eavesdropper can deduce that this is a Syncthing connection and
+An eavesdropper can deduce that this is a Syncthing connection and calculate the
-calculate the device ID:s involved based on the hashes of the sent
+device ID:s involved based on the hashes of the sent certificates.
-certificates.
 
-Likewise, if the sync port (default 22000) is accessible from the
+Likewise, if the sync port (default 22000) is accessible from the internet, a
-internet, a port scanner may discover it, attempt a TLS negotiation and
+port scanner may discover it, attempt a TLS negotiation and thus obtain the
-thus obtain the device certificate. This provides the same information
+device certificate. This provides the same information as in the eavesdropper
-as in the eavesdropper case.
+case.
 
 Web GUI
--------
+~~~~~~~
 
-If the web GUI is accessible, it exposes the device as running
+If the web GUI is accessible, it exposes the device as running Syncthing. The
-Syncthing. The web GUI defaults to being reachable from the **local host
+web GUI defaults to being reachable from the **local host only**.
-only**.
 
 In Short
-========
+--------
 
-Parties doing surveillance on your network (whether that be corporate
+Parties doing surveillance on your network (whether that be corporate IT, the
-IT, the NSA or someone else) will be able to see that you use Syncthing,
+NSA or someone else) will be able to see that you use Syncthing, and your device
-and your device ID's `are OK to share
+ID's `are OK to share anyway
-anyway <http://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret>`__,
+<http://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret>`__,
-but the actual transmitted data is protected as well as we can. Knowing
+but the actual transmitted data is protected as well as we can. Knowing your
-your device ID can expose your IP address, using global discovery.
+device ID can expose your IP address, using global discovery.

users/versioning.rst

@@ -2,20 +2,33 @@ File Versioning
 ===============
 
 .. warning::
-	This page may be out of date and requires review.
+    This page may be out of date and requires review.
-	External versioning requires documenting.
 
-There are 3 types of File Versioning. When you select each in the web
+.. todo::
-interface, a short description of each is shown to help you decide.
+    External versioning requires documenting.
+
+Description
+-----------
+
+There are 3 types of File Versioning. When you select each in the web interface,
+a short description of each is shown to help you decide.
+
+.. todo::
+    More detail needed here: Can this be a relative path, or must it be
+    an absolute path?
+
+With "Staggered File Versioning" method (only), you would like to specify where
+removed and deleted files are stored as part of the Versioning feature, you can
+specify the path in the "Versions Path" input after this method is selected.
 
 No File Versioning
 ------------------
 
-This is the default setting. With no file versioning, files that are
+This is the default setting. With no file versioning, files that are replaced or
-replaced or deleted on one device are deleted on other devices that the
+deleted on one device are deleted on other devices that the directory is shared
-directory is shared with. (Note: If a folder is marked "Master Folder"
+with. (Note: If a folder is marked "Master Folder" on a device, that device will
-on a device, that device will not accept changes to the files in the
+not accept changes to the files in the folder, and therefore will not have files
-folder, and therefore will not have files replaced or deleted.)
+replaced or deleted.)
 
 Simple File Versioning
 ----------------------
@@ -28,41 +41,33 @@ should keep. For example, if you set this value to 5, if a file is
 replaced 5 times on a remote device, you will see 5 time-stamped
 versions on that file in the ".stversions" folder on the other devices
 sharing the same folder.
+With "Simple File Versioning" files are moved to the ".stversions" folder
+(inside your shared folder) when replaced or deleted on a remote device. This
+option also takes a value in an input titled "Keep Versions" which tells
+Syncthing how many old versions of the file it should keep. For example, if you
+set this value to 5, if a file is replaced 5 times on a remote device, you will
+see 5 time-stamped versions on that file in the ".stversions" folder on the
+other devices sharing the same folder.
 
 Staggered File Versioning
 -------------------------
 
 With "Staggered File Versioning" files are also moved to the ".stversions"
 folder (inside your shared folder) when replaced or deleted on a remote device
-(just like "Simple File Versioning"), however, Version are automatically
+(just like "Simple File Versioning"), however, Version are automatically deleted
-deleted if they are older than the maximum age or exceed the number of files
+if they are older than the maximum age or exceed the number of files allowed in
-allowed in an interval.
+an interval.
 
-The following intervals are used and they each have a maximum number of
+The following intervals are used and they each have a maximum number of files
-files that will be kept for each.
+that will be kept for each.
 
--  1 Hour - For the first hour, the most recent version is kept every 30
+1 Hour
-   seconds.
+    For the first hour, the most recent version is kept every 30 seconds.
--  1 Day - For the first day, the most recent version is kept every
+1 Day
-   hour.
+    For the first day, the most recent version is kept every hour.
--  30 Days - For the first 30 days, the most recent version is kept
+30 Days
-   every day.
+    For the first 30 days, the most recent version is kept every day.
--  Until Maximum Age - Until the maximum age, the most recent version is
+Until Maximum Age
-   kept every week.
+    The maximum time to keep a version in days. For example, to keep replaced or
-
+    deleted files in the ".stversions" folder for an entire year, use 365. If
-Maximum Age
+    only or 10 days, use 10. **Note: Set to 0 to keep versions forever.**
-~~~~~~~~~~~
-
-The "Maximum Age" input is the maximum time to keep a version in days.
-For example, to keep replaced or deleted files in the ".stversions"
-folder for an entire year, use 365. If only for 10 days, use 10. **Note:
-Set to 0 to keep versions forever.**
-
-Versions Path
-~~~~~~~~~~~~~
-
-With "Staggered File Versioning" method (only), if you would like to
-specify where removed and deleted files are stored as part of the
-Versioning feature, you can specify the path in the "Versions Path"
-input after this method is selected. [*More detail needed here: Can this
-be a relative path, or must it be an absolute path?*\ ]