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