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