1SYNCTHING-FAQ(7) Syncthing SYNCTHING-FAQ(7)
2
6 syncthing-faq - Frequently Asked Questions
7 • General
9 • What is Syncthing?
11 • Is it “syncthing”, “Syncthing” or “SyncThing”?
13 • What things are synced?
15 • Is synchronization fast?
17 • How does Syncthing differ from BitTorrent/Resilio Sync?
19 • Why is there no iOS client?
21 • Should I keep my device IDs secret?
23 • Troubleshooting
25 • Where are the Syncthing logs?
27 • Why is the sync so slow?
29 • Why does it use so much CPU?
31 • Why is the setup more complicated than BitTorrent/Resilio Sync?
33 • Why do I get “Host check error” in the GUI/API?
35 • My Syncthing database is corrupt
37 • Why do I see Syncthing twice in task manager?
39 • How can I view the history of changes?
41 • Does the audit log contain every change?
43 • Why does Syncthing connect to this unknown/suspicious address?
45 • Usage
47 • What if there is a conflict?
49 • How do I serve a folder from a read only filesystem?
51 • I really hate the .stfolder directory, can I remove it?
53 • Am I able to nest shared folders in Syncthing?
55 • How do I rename/move a synced folder?
57 • How do I configure multiple users on a single machine?
59 • Does Syncthing support syncing between folders on the same system?
61 • When I do have two distinct Syncthing-managed folders on two hosts,
63 how does Syncthing handle moving files between them?
64 • Is Syncthing my ideal backup application?
66 • How can I exclude files with brackets ([]) in the name?
68 • How do I access the web GUI from another computer?
70 • I don’t like the GUI or the theme. Can it be changed?
72 • How do I upgrade Syncthing?
74 • Where do I find the latest release?
76 • How do I run Syncthing as a daemon process on Linux?
78 • How do I increase the inotify limit to get my filesystem watcher to
80 work?
81 • How do I reset the GUI password?
83
85 What is Syncthing?
86 Syncthing is an application that lets you synchronize your files across
87 multiple devices. This means the creation, modification or deletion of
88 files on one machine will automatically be replicated to your other de‐
89 vices. We believe your data is your data alone and you deserve to
90 choose where it is stored. Therefore Syncthing does not upload your
91 data to the cloud but exchanges your data across your machines as soon
92 as they are online at the same time.
93 Is it “syncthing”, “Syncthing” or “SyncThing”?
95 It’s Syncthing, although the command and source repository is spelled
96 syncthing so it may be referred to in that way as well. It’s definitely
97 not SyncThing, even though the abbreviation st is used in some circum‐
98 stances and file names.
99 What things are synced?
101 The following things are always synchronized:
102 • File contents
104 • File modification times
106 The following may be synchronized or not, depending:
108 • File permissions (when supported by file system; on Windows only the
110 read only bit is synchronized)
111 • Symbolic links (synced, except on Windows, but never followed)
113 The following are not synchronized;
115 • File or directory owners and Groups (not preserved)
117 • Directory modification times (not preserved)
119 • Hard links and Windows directory junctions (followed, not preserved)
121 • Extended attributes, resource forks (not preserved)
123 • Windows, POSIX or NFS ACLs (not preserved)
125 • Devices, FIFOs, and other specials (ignored)
127 • Sparse file sparseness (will become sparse, when supported by the OS
129 & filesystem)
130 Is synchronization fast?
132 Syncthing segments files into pieces, called blocks, to transfer data
133 from one device to another. Therefore, multiple devices can share the
134 synchronization load, in a similar way to the torrent protocol. The
135 more devices you have online, the faster an additional device will re‐
136 ceive the data because small blocks will be fetched from all devices in
137 parallel.
138 Syncthing handles renaming files and updating their metadata in an ef‐
140 ficient manner. This means that renaming a large file will not cause a
141 retransmission of that file. Additionally, appending data to existing
142 large files should be handled efficiently as well.
143 Temporary files are used to store partial data downloaded from other
145 devices. They are automatically removed whenever a file transfer has
146 been completed or after the configured amount of time which is set in
147 the configuration file (24 hours by default).
148 How does Syncthing differ from BitTorrent/Resilio Sync?
150 The two are different and not related. Syncthing and BitTorrent/Resilio
151 Sync accomplish some of the same things, namely syncing files between
152 two or more computers.
153 BitTorrent Sync, now called Resilio Sync, is a proprietary peer-to-peer
155 file synchronization tool available for Windows, Mac, Linux, Android,
156 iOS, Windows Phone, Amazon Kindle Fire and BSD. [1] Syncthing is an
157 open source file synchronization tool.
158 Syncthing uses an open and documented protocol, and likewise the secu‐
160 rity mechanisms in use are well defined and visible in the source code.
161 Resilio Sync uses an undocumented, closed protocol with unknown secu‐
162 rity properties.
163 [1] https://en.wikipedia.org/wiki/Resilio_Sync
165 Why is there no iOS client?
167 There is an alternative implementation of Syncthing (using the same
168 network protocol) called fsync(). There are no plans by the current
169 Syncthing team to support iOS in the foreseeable future, as the code
170 required to do so would be quite different from what Syncthing is to‐
171 day.
172 Should I keep my device IDs secret?
174 No. The IDs are not sensitive. Given a device ID it’s possible to find
175 the IP address for that device, if global discovery is enabled on it.
176 Knowing the device ID doesn’t help you actually establish a connection
177 to that device or get a list of files, etc.
178 For a connection to be established, both devices need to know about the
180 other’s device ID. It’s not possible (in practice) to forge a device
181 ID. (To forge a device ID you need to create a TLS certificate with
182 that specific SHA-256 hash. If you can do that, you can spoof any TLS
183 certificate. The world is your oyster!)
184 SEE ALSO:
186 device-ids
187
189 Where are the Syncthing logs?
190 Syncthing logs to stdout by default. On Windows Syncthing by default
191 also creates syncthing.log in Syncthing’s home directory (run syncthing
192 -paths to see where that is). The command line option -logfile can be
193 used to specify a user-defined logfile.
194 If you’re running a process manager like systemd, check there. If
196 you’re using a GUI wrapper integration, it may keep the logs for you.
197 Why is the sync so slow?
199 When troubleshooting a slow sync, there are a number of things to
200 check.
201 First of all, verify that you are not connected via a relay. In the
203 “Remote Devices” list on the right side of the GUI, double check that
204 you see “Address: <some address>” and not “Relay: <some address>”.
205 [image]
206 If you are connected via a relay, this is because a direct connection
208 could not be established. Double check and follow the suggestions in
209 firewall-setup to enable direct connections.
210 Second, if one of the devices is a very low powered machine (a Rasp‐
212 berry Pi, or a phone, or a NAS, or similar) you are likely constrained
213 by the CPU on that device. See the next question for reasons Syncthing
214 likes a faster CPU.
215 Third, verify that the network connection is OK. Tools such as iperf or
217 just an Internet speed test can be used to verify the performance here.
218 Why does it use so much CPU?
220 1. When new or changed files are detected, or Syncthing starts for the
221 first time, your files are hashed using SHA-256.
222 2. Data that is sent over the network is compressed (optionally) and
224 encrypted (always). When receiving data it must be decrypted and
225 then (if compressed) decompressed.
226 3. There is a certain amount of housekeeping that must be done to track
228 the current and available versions of each file in the index data‐
229 base.
230 4. By default Syncthing uses periodic scanning every hour when watching
232 for changes or every minute if that’s disabled to detect file
233 changes. This means checking every file’s modification time and com‐
234 paring it to the database. This can cause spikes of CPU usage for
235 large folders.
236 Hashing, compression and encryption cost CPU time. Also, using the GUI
238 causes a certain amount of extra CPU usage to calculate the summary
239 data it presents. Note however that once things are in sync CPU usage
240 should be negligible.
241 To minimize the impact of this, Syncthing attempts to lower the process
243 priority when starting up.
244 To further limit the amount of CPU used when syncing and scanning, set
246 the environment variable GOMAXPROCS to the maximum number of CPU cores
247 Syncthing should use at any given moment. For example, GOMAXPROCS=2 on
248 a machine with four cores will limit Syncthing to no more than half the
249 system’s CPU power.
250 Why is the setup more complicated than BitTorrent/Resilio Sync?
252 Security over convenience. In Syncthing you have to setup both sides to
253 connect two devices. An attacker can’t do much with a stolen device ID,
254 because you have to add the device on the other side too. You have bet‐
255 ter control where your files are transferred.
256 This is an area that we are working to improve in the long term.
258 Why do I get “Host check error” in the GUI/API?
260 Since version 0.14.6 Syncthing does an extra security check when the
261 GUI/API is bound to localhost - namely that the browser is talking to
262 localhost. This protects against most forms of DNS rebinding attack
263 <https://en.wikipedia.org/wiki/DNS_rebinding> against the GUI.
264 To pass this test, ensure that you are accessing the GUI using an URL
266 that begins with http://localhost, http://127.0.0.1 or http://[::1].
267 HTTPS is fine too, of course.
268 If you are using a proxy in front of Syncthing you may need to disable
270 this check, after ensuring that the proxy provides sufficient authenti‐
271 cation to protect against unauthorized access. Either:
272 • Make sure the proxy sets a Host header containing localhost, or
274 • Set insecureSkipHostcheck in the advanced settings, or
276 • Bind the GUI/API to a non-localhost listen port.
278 In all cases, username/password authentication and HTTPS should be
280 used.
281 My Syncthing database is corrupt
283 This is almost always a result of bad RAM, storage device or other
284 hardware. When the index database is found to be corrupt Syncthing
285 cannot operate and will note this in the logs and exit. To overcome
286 this delete the database folder <https://docs.syncthing.net/users/con‐
287 fig.html#description> inside Syncthing’s home directory and re-start
288 Syncthing. It will then need to perform a full re-hashing of all shared
289 folders. You should check your system in case the underlying cause is
290 indeed faulty hardware which may put the system at risk of further data
291 loss.
292 Why do I see Syncthing twice in task manager?
294 One process manages the other, to capture logs and manage restarts.
295 This makes it easier to handle upgrades from within Syncthing itself,
296 and also ensures that we get a nice log file to help us narrow down the
297 cause for crashes and other bugs.
298 How can I view the history of changes?
300 The web GUI contains a Global Changes button under the device list
301 which displays changes since the last (re)start of Syncthing. With the
302 -audit option you can enable a persistent, detailed log of changes and
303 most activities, which contains a JSON formatted sequence of events in
304 the ~/.config/syncthing/audit-_date_-_time_.log file.
305 Does the audit log contain every change?
307 The audit log (and the Global Changes window) sees the changes that
308 your Syncthing sees. When Syncthing is continuously connected it usu‐
309 ally sees every change happening immediately and thus knows which node
310 initiated the change. When topology gets complex or when your node re‐
311 connects after some time offline, Syncthing synchronises with its
312 neighbours: It gets the latest synchronised state from the neighbour,
313 which is the result of all the changes between the last known state
314 (before disconnect or network delay) and the current state at the
315 neighbour, and if there were updates, deletes, creates, conflicts,
316 which were overlapping we only see the latest change for a given file
317 or directory (and the node where that latest change occurred). When we
318 connect to multiple neighbours Syncthing decides which neighbor has the
319 latest state, or if the states conflict it initiates the conflict reso‐
320 lution procedure, which in the end results in a consistent up-to-date
321 state with all the neighbours.
322 Why does Syncthing connect to this unknown/suspicious address?
324 If you see outgoing connections to odd and unexpected addresses these
325 are most likely connections to relay servers. Relay servers are run by
326 volunteers all over the world. They usually listen on port 443 or
327 22067, though this is controlled by the user running it. You can com‐
328 pare the address you are concernced about with the current list of ac‐
329 tive relays <https://relays.syncthing.net>. Relays do not and can not
330 see the data transmitted via them.
331
333 What if there is a conflict?
334 SEE ALSO:
335 conflict-handling
336 How do I serve a folder from a read only filesystem?
338 Syncthing requires a “folder marker” to indicate that the folder is
339 present and healthy. By default this is a directory called .stfolder
340 that is created by Syncthing when the folder is added. If this folder
341 can’t be created (you are serving files from a CD or something) you can
342 instead set the advanced config Marker Name to the name of some file or
343 folder that you know will always exist in the folder.
344 I really hate the .stfolder directory, can I remove it?
346 See the previous question.
347 Am I able to nest shared folders in Syncthing?
349 Sharing a folder that is within an already shared folder is possible,
350 but it has its caveats. What you must absolutely avoid are circular
351 shares. This is just one example, there may be other undesired effects.
352 Nesting shared folders is not supported, recommended or coded for, but
353 it can be done successfully when you know what you’re doing - you have
354 been warned.
355 How do I rename/move a synced folder?
357 Syncthing doesn’t have a direct way to do this, as it’s potentially
358 dangerous to do so if you’re not careful - it may result in data loss
359 if something goes wrong during the move and is synchronized to your
360 other devices.
361 The easy way to rename or move a synced folder on the local system is
363 to remove the folder in the Syncthing UI, move it on disk, then re-add
364 it using the new path.
365 It’s best to do this when the folder is already in sync between your
367 devices, as it is otherwise unpredictable which changes will “win” af‐
368 ter the move. Changes made on other devices may be overwritten, or
369 changes made locally may be overwritten by those on other devices.
370 An alternative way is to shut down Syncthing, move the folder on disk
372 (including the .stfolder marker), edit the path directly in config.xml
373 in the configuration folder (see config) and then start Syncthing
374 again.
375 How do I configure multiple users on a single machine?
377 Each user should run their own Syncthing instance. Be aware that you
378 might need to configure listening ports such that they do not overlap
379 (see config).
380 Does Syncthing support syncing between folders on the same system?
382 No. Syncthing is not designed to sync locally and the overhead involved
383 in doing so using Syncthing’s method would be wasteful. There are bet‐
384 ter programs to achieve this such as rsync <https://rsync.samba.org/>
385 or Unison <https://www.cis.upenn.edu/~bcpierce/unison>.
386 When I do have two distinct Syncthing-managed folders on two hosts, how
388 does Syncthing handle moving files between them?
389 Syncthing does not specially handle this case, and most files most
390 likely get re-downloaded.
391 In detail, the behavior depends on the scan order. If you have folder A
393 and B, and move files from A to B, if A gets scanned first, it will an‐
394 nounce removal of the files to others who will remove the files. As you
395 rescan B, B will announce addition of new files, and other peers will
396 have nowhere to get them from apart from re-downloading them.
397 If B gets rescanned first, B will announce additions first, remote
399 peers will reconstruct the files (not rename, more like copy block by
400 block) from A, and then as A gets rescanned remove the files from A.
401 A workaround would be to copy first from A to B, rescan B, wait for B
403 to rebuild on remote ends, and then delete from A.
404 Is Syncthing my ideal backup application?
406 No. Syncthing is not a great backup application because all changes to
407 your files (modifications, deletions, etc.) will be propagated to all
408 your devices. You can enable versioning, but we encourage the use of
409 other tools to keep your data safe from your (or our) mistakes.
410 How can I exclude files with brackets ([]) in the name?
412 The patterns in .stignore are glob patterns, where brackets are used to
413 denote character ranges. That is, the pattern q[abc]x will match the
414 files qax, qbx and qcx.
415 To match an actual file called q[abc]x the pattern needs to “escape”
417 the brackets, like so: q\[abc\]x.
418 On Windows, escaping special characters is not supported as the \ char‐
420 acter is used as a path separator. On the other hand, special charac‐
421 ters such as [ and ? are not allowed in file names on Windows.
422 How do I access the web GUI from another computer?
424 The default listening address is 127.0.0.1:8384, so you can only access
425 the GUI from the same machine. This is for security reasons. Change the
426 GUI listen address through the web UI from 127.0.0.1:8384 to
427 0.0.0.0:8384 or change the config.xml:
428 <gui enabled="true" tls="false">
430 <address>127.0.0.1:8384</address>
431 to
433 <gui enabled="true" tls="false">
435 <address>0.0.0.0:8384</address>
436 Then the GUI is accessible from everywhere. You should set a password
438 and enable HTTPS with this configuration. You can do this from inside
439 the GUI.
440 If both your computers are Unix-like (Linux, Mac, etc.) you can also
442 leave the GUI settings at default and use an ssh port forward to access
443 it. For example,
444 $ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
446 will log you into othercomputer.example.com, and present the remote
448 Syncthing GUI on http://localhost:9090 on your local computer.
449 If you only want to access the remote gui and don’t want the terminal
451 session, use this example,
452 $ ssh -N -L 9090:127.0.0.1:8384 user@othercomputer.example.com
454 If only your remote computer is Unix-like, you can still access it with
456 ssh from Windows.
457 Under Windows 10 (64 bit) you can use the same ssh command if you in‐
459 stall the Windows Subsystem for Linux <https://docs.microsoft.com/win‐
460 dows/wsl/install-win10>.
461 Another Windows way to run ssh is to install gow (Gnu On Windows)
463 <https://github.com/bmatzelle/gow>. The easiest way to install gow is
464 with the chocolatey <https://chocolatey.org/> package manager.
465 I don’t like the GUI or the theme. Can it be changed?
467 You can change the theme in the settings. Syncthing ships with other
468 themes than the default.
469 If you want a custom theme or a completely different GUI, you can add
471 your own. By default, Syncthing will look for a directory gui inside
472 the Syncthing home folder. To change the directory to look for themes,
473 you need to set the STGUIASSETS environment variable. To get the con‐
474 crete directory, run syncthing with the -paths parameter. It will print
475 all the relevant paths, including the “GUI override directory”.
476 To add e.g. a red theme, you can create the file red/as‐
478 sets/css/theme.css inside the GUI override directory to override the
479 default CSS styles.
480 To create a whole new GUI, you should checkout the files at
482 https://github.com/syncthing/syncthing/tree/main/gui/default to get an
483 idea how to do that.
484 How do I upgrade Syncthing?
486 If you use a package manager such as Debian’s apt-get, you should up‐
487 grade using the package manager. If you use the binary packages linked
488 from Syncthing.net, you can use Syncthing built in automatic upgrades.
489 • If automatic upgrades is enabled (which is the default), Syncthing
491 will upgrade itself automatically within 24 hours of a new release.
492 • The upgrade button appears in the web GUI when a new version has been
494 released. Pressing it will perform an upgrade.
495 • To force an upgrade from the command line, run syncthing -upgrade.
497 Note that your system should have CA certificates installed which allow
499 a secure connection to GitHub (e.g. FreeBSD requires sudo pkg install
500 ca_root_nss). If curl or wget works with normal HTTPS sites, then so
501 should Syncthing.
502 Where do I find the latest release?
504 We release new versions through GitHub. The latest release is always
505 found on the release page <https://github.com/syncthing/syncthing/re‐
506 leases/latest>. Unfortunately GitHub does not provide a single URL to
507 automatically download the latest version. We suggest to use the GitHub
508 API <https://api.github.com/repos/syncthing/syncthing/releases/latest>
509 and parsing the JSON response.
510 How do I run Syncthing as a daemon process on Linux?
512 If you’re using systemd, runit, or upstart, we ship example configura‐
513 tions <https://github.com/syncthing/syncthing/tree/main/etc>.
514 If however you’re not using one of these tools, you have a couple of
516 options. If your system has a tool called start-stop-daemon installed
517 (that’s the name of the command, not the package), look into the local
518 documentation for that, it will almost certainly cover 100% of what you
519 want to do. If you don’t have start-stop-daemon, there are a bunch of
520 other software packages you could use to do this. The most well known
521 is called daemontools, and can be found in the standard package reposi‐
522 tories for almost every modern Linux distribution. Other popular
523 tools with similar functionality include S6 and the aforementioned
524 runit.
525 How do I increase the inotify limit to get my filesystem watcher to work?
527 You are probably reading this because you encountered the following er‐
528 ror with the filesystem watcher on linux:
529 Failed to start filesystem watcher for folder yourLabel (yourID):
530 failed to setup inotify handler. Please increase inotify limits, see
531 https://docs.syncthing.net/users/faq.html#inotify-limits
532 Linux typically restricts the amount of watches per user (usually
534 8192). When you have more directories you need to adjust that number.
535 On many Linux distributions you can run the following to fix it:
537 echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf
539 On Arch Linux and potentially others it is preferred to write this line
541 into a separate file, i.e. you should run:
542 echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.d/90-override.conf
544 This only takes effect after a reboot. To adjust the limit immediately,
546 run:
547 sudo sh -c 'echo 204800 > /proc/sys/fs/inotify/max_user_watches'
549 How do I reset the GUI password?
551 If you’ve forgotten/lost the GUI password, you can remove it by delet‐
552 ing the <user> and <password> XML tags from the <gui> block in file
553 config.xml. This should be done while Syncthing is not running. The lo‐
554 cation of the file depends on OS and is described in the configuration
555 documentation.
556 For example, the two emphasized lines below would be removed from the
558 file.
559 <gui enabled="true" tls="false" debugging="false">
561 <address>127.0.0.1:8384</address>
562 <user>syncguy</user>
563 <password>$2a$10$s9wWHOQe...Cq7GPye69</password>
564 <apikey>9RCKohqCAyrj5RjpyZdR2wXmQ9PyQFeN</apikey>
565 <theme>default</theme>
566 </gui>
567
569 The Syncthing Authors
570
572 2014-2019, The Syncthing Authors
573v1 Apr 15, 2021 SYNCTHING-FAQ(7)