diff --git a/conf.py b/conf.py index feaef8296..d1e9222b4 100644 --- a/conf.py +++ b/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', - [u'The Syncthing Authors'], 1) + ('users/config', 'syncthing-config', + '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 ------------------------------------------- diff --git a/dev/device-ids.rst b/dev/device-ids.rst index 7c9197e62..6912586f2 100644 --- a/dev/device-ids.rst +++ b/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 -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. +Description +----------- + +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. -At first startup, Syncthing will create an public/private key pair. +To understand device IDs we need to look at the underlying mechanisms. At first +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 -the private key (``key.pem``) and a self signed certificate -(``cert.pem``). The self signing part doesn't actually add any security -or functionality as far as Syncthing is concerned but it enables the use -of the keys in a standard TLS exchange. +Currently this is a 3072 bit RSA key. The keys are saved in the form of the +private key (``key.pem``) and a self signed certificate (``cert.pem``). The self +signing part doesn't actually add any security or functionality as far as +Syncthing is concerned but it enables the use of the keys in a standard TLS +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 -the public key; the serial number is zero and the Issuer and Subject are -both "syncthing" where a qualified name might otherwise be expected. +We can see here that the certificate is little more than a container for the +public key; the serial number is zero and the Issuer and Subject are both +"syncthing" where a qualified name might otherwise be expected. -An advanced user could replace the ``key.pem`` and ``cert.pem`` files -with a keypair generated directly by the ``openssl`` utility or other -mechanism. +An advanced user could replace the ``key.pem`` and ``cert.pem`` files with a +keypair generated directly by the ``openssl`` utility or other mechanism. Device IDs -========== +---------- -To form a device ID the SHA-256 hash of the certificate data in DER form -is calculated. This means the hash covers all information under the +To form a device ID the SHA-256 hash of the certificate data in DER form is +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. -Base32 encodes five bits per character, so we need 256 / 5 = 51.2 -characters to encode the device ID. This becomes 52 characters in -practice, but 52 characters of base32 would decode to 260 bits which is -not an whole number of bytes. The base32 encoding adds padding to 280 -bits (the next multiple of both 5 and 8 bits) so the resulting ID looks -something like +The hashing results in a 256 bit hash, which we encode using base32. Base32 +encodes five bits per character, so we need 256 / 5 = 51.2 characters to encode +the device ID. This becomes 52 characters in practice, but 52 characters of +base32 would decode to 260 bits which is not an whole number of bytes. The +base32 encoding adds padding to 280 bits (the next multiple of both 5 and 8 +bits) so the resulting ID looks 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 -Syncthing. When you add a device ID to the syncthing configuration, -Syncthing will attempt to connect to that device. The first thing we -need to do is figure out the IP and port to connect to. There's three -possibilities here; +So now we know what device IDs are, here's how they are used in Syncthing. When +you add a device ID to the syncthing configuration, Syncthing will attempt to +connect to that device. The first thing we need to do is figure out the IP and +port to connect to. There's three 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 -TLS handshake performed. As part of the handshake both devices present -their certificates. Once the handshake has completed and the peer -certificate is known, the following steps are performed. +Once we have and address and port a TCP connection is established and a TLS +handshake performed. As part of the handshake both devices present their +certificates. Once the handshake has completed and the peer certificate is +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 -not simply collision resistance but resistance to a preimage attack. -I.e. even if you can find two messages that result in a hash collision -that doesn't help you attack Syncthing (or TLS in general). You need to -create a message that hashes to exactly the hash that my certificate -already has or you won't get in. +It's also worth noting that the property of SHA-256 that we are using is not +simply collision resistance but resistance to a preimage attack. I.e. even if +you can find two messages that result in a hash collision that doesn't help you +attack Syncthing (or TLS in general). You need to create a message that hashes +to exactly the hash that my certificate already has or you won't get in. -Note also that it's not good enough to find a random blob of bits that -happen to have the same hash as my certificate. You need to create a -valid DER- encoded, signed certificate that has the same hash as mine. -The difficulty of this is staggeringly far beyond the already staggering -difficulty of finding a SHA-256 collision. +Note also that it's not good enough to find a random blob of bits that happen to +have the same hash as my certificate. You need to create a valid DER- encoded, +signed certificate that has the same hash as mine. The difficulty of this is +staggeringly far beyond the already staggering difficulty of finding a SHA-256 +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 -even into a computer. And it needs to be done twice, once for each side. +It's a mouthful to read over the phone, annoying to type into an SMS or even +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 -are various possible solutions; +This isn't a vulnerability as such, but a user experience problem. There are +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 diff --git a/dev/events.rst b/dev/events.rst index 81389ebb5..35ec30f29 100644 --- a/dev/events.rst +++ b/dev/events.rst @@ -1,8 +1,11 @@ Event API ========= -Syncthing provides a simple long polling interface for exposing events from -the core utility towards a GUI. +Description +----------- + +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=``, where ```` 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, - "type": "DeviceConnected", - "time": "2014-07-13T21:04:33.687836696+02:00", - "data": { - "addr": "172.16.32.25:22000", - "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG" - } - } + { + "id": 2, + "type": "DeviceConnected", + "time": "2014-07-13T21:04:33.687836696+02:00", + "data": { + "addr": "172.16.32.25:22000", + "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. -* ``time`` is 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`` is an object containing optional extra information; the exact structure is determined by the event type. +id + A monotonically increasing integer. The first event generated has id ``1``, + the next has id ``2`` etc. +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 - :glob: + :maxdepth: 2 + :glob: - ../events/* + ../events/* diff --git a/dev/rest.rst b/dev/rest.rst index a471d6358..094af5b53 100644 --- a/dev/rest.rst +++ b/dev/rest.rst @@ -1,19 +1,21 @@ REST API ======== -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. +Description +----------- + +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, -an API key must be set and used. The API key can be generated in the -GUI, or set in the ``configuration/gui/apikey`` element in the -configuration file. To use an API key, set the request header -``X-API-Key`` to the API key value. +To use the POST methods, or *any* method when authentication is enabled, an API +key must be set and used. The API key can be generated in the GUI, or set in the +``configuration/gui/apikey`` element in the configuration file. To use an API +key, set the request header ``X-API-Key`` to the API key value. System Endpoints ---------------- diff --git a/users/config.rst b/users/config.rst index 4a1433612..333a3c02e 100644 --- a/users/config.rst +++ b/users/config.rst @@ -1,35 +1,51 @@ -################### -Configuration Files -################### +Syncthing Configuration +======================= .. 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 -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: +Synopsis +-------- -- ``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`` and ``https-key.pem``: The certificate and 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). +:: + + $HOME/.config/syncthing/config.xml + $HOME/Library/Application Support/Syncthing + %AppData%/Syncthing + %localappdata%/Syncthing + +Description +----------- + +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: -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. ``2`` is current. +version + The config version. The current version is ``2``. 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``: The directory where the folder is stored on this - device; not sent to other devices. (mandatory) -- ``ro``: True if the folder is read only (will not be modified by - Syncthing) on this device. (optional, defaults to ``false``) -- ``ignorePerms``: True if the folder should `ignore - permissions `__. - -Children -~~~~~~~~ - -- One or mode ``device`` elements. +id + The folder ID, must be unique. (mandatory) +directory + The directory where the folder is stored on this + device; not sent to other devices. (mandatory) +ro + True if the folder is read only (will not be modified by Syncthing) on this + device. (optional, defaults to ``false``) +ignorePerms + True if the folder should `ignore permissions `_. 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) -- ``name``: A friendly name for the device. (optional) - -Children -~~~~~~~~ - -- One or mode ``address`` elements. - +id + The device ID. This must be written in canonical form, that is without any + spaces or dashes. (mandatory) +name + A friendly name for the device. (optional) 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 -contains a single address, on one of the following forms: - -- IPv4 addresses, IPv6 addresses within brackets, or DNS names, all - 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`` -- ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS +address + 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 - an ``ip:port`` listen address. -- ``username`` and ``password``: 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. - -options -------- - -There must be exactly one ``options`` element. It contains the following -configuration settings as children; - -- ``listenAddress`` : ``host:port`` or ``:port`` string denoting an - address to listen for BEP (sync protocol) connections. More than one - ``listenAddress`` may be given. (default ``0.0.0.0:22000``) - -- ``globalAnnounceServer`` : ``host:port`` where a global announce - server may be reached. (default \`announce.syncthing.net:22025´) - -- ``globalAnnounceEnabled``: ``true``/``false`` (default ``true``) - -- ``localAnnounceEnabled``: ``true``/``false`` (default ``true``) - -- ``parallelRequests``: The maximum number of outstanding block - requests to have against any given peer. (default ``16``) - -- ``maxSendKbps``: Rate limit - -- ``rescanIntervalS``: The number of seconds to wait between each scan - for modification of the local repositories. (default ``60``) A value - of 0 disables the scanner. - -- ``reconnectionIntervalS``: The number of seconds to wait between each - attempt to connect to currently unconnected devices. (default ``60``) - -- ``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. +listenAddress + ``host:port`` or ``:port`` string denoting an address to listen for BEP + connections. More than one ``listenAddress`` may be given. + (default: ``0.0.0.0:22000``) +globalAnnounceServer + ``host:port`` string denoting where a global announce server may be + reached. (default: ``announce.syncthing.net:22025``) +globalAnnounceEnabled + ``true``/``false`` (default: ``true``) +localAnnounceEnabled + ``true``/``false`` (default: ``true``) +parallelRequests + The maximum number of outstanding block requests to have against any given + peer. (default: ``16``) +maxSendKbps + Rate limit +rescanIntervalS + The number of seconds to wait between each scan for modification of the + local repositories. A value of ``0`` disables the scanner. (default: ``60``) +reconnectionIntervalS + The number of seconds to wait between each attempt to connect to currently + unconnected devices. (default: ``60``) +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. diff --git a/users/faq.rst b/users/faq.rst index b01f38132..e60fe72ed 100644 --- a/users/faq.rst +++ b/users/faq.rst @@ -9,39 +9,36 @@ General What is Syncthing? ~~~~~~~~~~~~~~~~~~ -Syncthing is an application that lets you synchronize your files across -multiple devices. This means the creation, modification or deletion of -files on one machine will automatically be replicated to your other -devices. We believe your data is your data alone and you deserve to -choose where it is stored. Therefore Syncthing does not upload your data -to the cloud but exchanges your data across your machines as soon as -they are online at the same time. +Syncthing is an application that lets you synchronize your files across multiple +devices. This means the creation, modification or deletion of files on one +machine will automatically be replicated to your other devices. We believe your +data is your data alone and you deserve to choose where it is stored. Therefore +Syncthing does not upload your data to the cloud but exchanges your data across +your machines as soon as they are online at the same time. Is it "syncthing", "Syncthing" or "SyncThing"? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It's **Syncthing**, although the command and source repository is -spelled ``syncthing`` so it may be referred to in that way as well. It's -definitely not :strike:`SyncThing`, even though the abbreviation -``st`` is used in some circumstances and file names. +It's **Syncthing**, although the command and source repository is spelled +``syncthing`` so it may be referred to in that way as well. It's definitely not +:strike:`SyncThing`, even though the abbreviation ``st`` is used in some +circumstances and file names. How does Syncthing differ from BitTorrent Sync? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The two are different and not related. Syncthing and BitTorrent Sync -accomplish some of the same things, namely syncing files between two or -more computers. +The two are different and not related. Syncthing and BitTorrent Sync accomplish +some of the same things, namely syncing files between two or more computers. BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file -synchronization tool available for Windows, Mac, Linux, Android, iOS, -Windows Phone, Amazon Kindle Fire and BSD. -`1 `__ Syncthing is an -open source file synchronization tool. +synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows +Phone, Amazon Kindle Fire and BSD. `1 +`__ Syncthing is an open source +file synchronization tool. -Syncthing uses an open and documented protocol, and likewise the -security mechanisms in use are well defined and visible in the source -code. BitTorrent Sync uses an undocumented, closed protocol with unknown -security properties. +Syncthing uses an open and documented protocol, and likewise the security +mechanisms in use are well defined and visible in the source code. BitTorrent +Sync uses an undocumented, closed protocol with unknown 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 -from one device to another. Therefore, multiple devices can share the -synchronization load, in a similar way as the torrent protocol. The more -devices you have online (and synchronized), the faster an additional -device will receive the data because small blocks will be fetched from -all devices in parallel. +Syncthing segments files into pieces, called blocks, to transfer data from one +device to another. Therefore, multiple devices can share the synchronization +load, in a similar way as the torrent protocol. The more devices you have online +(and synchronized), the faster an additional device will receive the data +because small blocks will be fetched from all devices in parallel. -Syncthing handles renaming files and updating their metadata in an -efficient manner. This means that renaming a large file will not cause a -retransmission of that file. Additionally, appending data to existing -large files should be handled efficiently as well. +Syncthing handles renaming files and updating their metadata in an efficient +manner. This means that renaming a large file will not cause a retransmission of +that file. Additionally, appending data to existing large files should be +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 -the IP address for that node, if global discovery is enabled on it. -Knowing the device ID doesn't help you actually establish a connection -to that node or get a list of files, etc. +No. The IDs are not sensitive. Given a device ID it's possible to find the IP +address for that node, if global discovery is enabled on it. Knowing the device +ID doesn't help you actually establish a connection to that node or get a list +of files, etc. -For a connection to be established, both nodes need to know about the -other's device ID. It's not possible (in practice) to forge a device ID. -(To forge a device ID you need to create a TLS certificate with that -specific SHA-256 hash. If you can do that, you can spoof any TLS -certificate. The world is your oyster!) +For a connection to be established, both nodes need to know about the other's +device ID. It's not possible (in practice) to forge a device ID. (To forge a +device ID you need to create a TLS certificate with that specific SHA-256 hash. +If you can do that, you can spoof any TLS certificate. The world is your +oyster!) -See also `Understanding Device -IDs `__. +.. see-also:: + :ref:`dev/device-ids` What if there is a conflict? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Syncthing does recognize conflicts. When a file has been modified on two -devices simultaneously, one of the files will be renamed to -``.sync- conflict--