1SYNCTHING-FAQ(7)                   Syncthing                  SYNCTHING-FAQ(7)
2
3
4

NAME

6       syncthing-faq - Frequently Asked Questions
7
8General
9
10What is Syncthing?
11
12Is it “syncthing”, “Syncthing” or “SyncThing”?
13
14What things are synced?
15
16Is synchronization fast?
17
18How does Syncthing differ from BitTorrent/Resilio Sync?
19
20Why is there no iOS client?
21
22Should I keep my device IDs secret?
23
24Troubleshooting
25
26Where are the Syncthing logs?
27
28Why is the sync so slow?
29
30Why does it use so much CPU?
31
32Why is the setup more complicated than BitTorrent/Resilio Sync?
33
34Why do I get “Host check error” in the GUI/API?
35
36My Syncthing database is corrupt
37
38Why do I see Syncthing twice in task manager?
39
40How can I view the history of changes?
41
42Does the audit log contain every change?
43
44Why does Syncthing connect to this unknown/suspicious address?
45
46Usage
47
48What if there is a conflict?
49
50How do I serve a folder from a read only filesystem?
51
52I really hate the .stfolder directory, can I remove it?
53
54Am I able to nest shared folders in Syncthing?
55
56How do I rename/move a synced folder?
57
58How do I configure multiple users on a single machine?
59
60Does Syncthing support syncing between folders on the same system?
61
62When I do have two distinct Syncthing-managed folders on two hosts,
63           how does Syncthing handle moving files between them?
64
65Is Syncthing my ideal backup application?
66
67How can I exclude files with brackets ([]) in the name?
68
69How do I access the web GUI from another computer?
70
71I don’t like the GUI or the theme. Can it be changed?
72
73How do I upgrade Syncthing?
74
75Where do I find the latest release?
76
77How do I run Syncthing as a daemon process on Linux?
78
79How do I increase the inotify limit to get my filesystem watcher to
80           work?
81
82How do I reset the GUI password?
83

GENERAL

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
94   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
100   What things are synced?
101       The following things are always synchronized:
102
103       • File contents
104
105       • File modification times
106
107       The following may be synchronized or not, depending:
108
109       • File permissions (when supported by file system; on Windows only  the
110         read only bit is synchronized)
111
112       • Symbolic links (synced, except on Windows, but never followed)
113
114       The following are not synchronized;
115
116       • File or directory owners and Groups (not preserved)
117
118       • Directory modification times (not preserved)
119
120       • Hard links and Windows directory junctions (followed, not preserved)
121
122       • Extended attributes, resource forks (not preserved)
123
124       • Windows, POSIX or NFS ACLs (not preserved)
125
126       • Devices, FIFOs, and other specials (ignored)
127
128       • Sparse  file sparseness (will become sparse, when supported by the OS
129         & filesystem)
130
131   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
139       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
144       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
149   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
154       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
159       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
164       [1]  https://en.wikipedia.org/wiki/Resilio_Sync
165
166   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
173   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
179       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
185       SEE ALSO:
186          device-ids
187

TROUBLESHOOTING

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
195       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
198   Why is the sync so slow?
199       When troubleshooting a slow sync, there  are  a  number  of  things  to
200       check.
201
202       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
207       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
211       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
216       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
219   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
223       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
227       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
231       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
237       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
242       To minimize the impact of this, Syncthing attempts to lower the process
243       priority when starting up.
244
245       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
251   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
257       This is an area that we are working to improve in the long term.
258
259   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
265       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
269       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
273       • Make sure the proxy sets a Host header containing localhost, or
274
275       • Set insecureSkipHostcheck in the advanced settings, or
276
277       • Bind the GUI/API to a non-localhost listen port.
278
279       In  all  cases,  username/password  authentication  and HTTPS should be
280       used.
281
282   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
293   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
299   How can I view the history of changes?
300       The  web  GUI  contains  a  Recent 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
306   Does the audit log contain every change?
307       The  audit  log  (and  the Recent 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  neighbour  has
319       the  latest  state, or if the states conflict it initiates the conflict
320       resolution  procedure,  which  in  the  end  results  in  a  consistent
321       up-to-date state with all the neighbours.
322
323   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 ports 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

USAGE

333   What if there is a conflict?
334       SEE ALSO:
335          conflict-handling
336
337   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
345   I really hate the .stfolder directory, can I remove it?
346       See the previous question.
347
348   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
356   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
362       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
366       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
371       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
376   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
381   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
387   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 will most
390       likely get re-downloaded.
391
392       In  detail, the behavior depends on the scan order. If you have folders
393       A and B, and move files from A to B, if A gets scanned first,  it  will
394       announce  the  removal  of the files to others who will then remove the
395       files. As you rescan B, B will announce the addition of new files,  and
396       other  peers will have nowhere to get them from apart from re-download‐
397       ing them.
398
399       If B gets rescanned first, B will announce additions first, and  remote
400       peers  will  then  reconstruct the files (not rename, more like copying
401       block by block) from A, and then as A gets rescanned,  it  will  remove
402       the files from A.
403
404       A  workaround  would be to copy first from A to B, rescan B, wait for B
405       to copy the files on the remote side, and then delete from A.
406
407   Is Syncthing my ideal backup application?
408       No. Syncthing is not a great backup application because all changes  to
409       your  files  (modifications, deletions, etc.) will be propagated to all
410       your devices. You can enable versioning, but we encourage  you  to  use
411       other tools to keep your data safe from your (or our) mistakes.
412
413   How can I exclude files with brackets ([]) in the name?
414       The patterns in .stignore are glob patterns, where brackets are used to
415       denote character ranges. That is, the pattern q[abc]x  will  match  the
416       files qax, qbx and qcx.
417
418       To  match  an  actual file called q[abc]x the pattern needs to “escape”
419       the brackets, like so: q\[abc\]x.
420
421       On Windows, escaping special characters is not supported as the \ char‐
422       acter is used as a path separator.
423
424   How do I access the web GUI from another computer?
425       The default listening address is 127.0.0.1:8384, so you can only access
426       the GUI from the same machine. This is for security reasons. To  access
427       the  web  GUI  from  another  computer,  change  the GUI listen address
428       through the web UI from 127.0.0.1:8384 to 0.0.0.0:8384  or  change  the
429       config.xml:
430
431          <gui enabled="true" tls="false">
432            <address>127.0.0.1:8384</address>
433
434       to
435
436          <gui enabled="true" tls="false">
437            <address>0.0.0.0:8384</address>
438
439       Then  the  GUI is accessible from everywhere. You should set a password
440       and enable HTTPS with this configuration. You can do this  from  inside
441       the GUI.
442
443       If  both  your  computers are Unix-like (Linux, Mac, etc.) you can also
444       leave the GUI settings at default and use an ssh port forward to access
445       it. For example,
446
447          $ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
448
449       will  log  you  into  othercomputer.example.com, and present the remote
450       Syncthing GUI on http://localhost:9090 on your local computer.
451
452       If you only want to access the remote gui and don’t want  the  terminal
453       session, use this example,
454
455          $ ssh -N -L 9090:127.0.0.1:8384 user@othercomputer.example.com
456
457       If only your remote computer is Unix-like, you can still access it with
458       ssh from Windows.
459
460       Under Windows 10 (64 bit) you can use the same ssh command if  you  in‐
461       stall  the Windows Subsystem for Linux <https://docs.microsoft.com/win
462       dows/wsl/install-win10>.
463
464       Another Windows way to run ssh is  to  install  gow  (Gnu  On  Windows)
465       <https://github.com/bmatzelle/gow>.  The  easiest way to install gow is
466       with the chocolatey <https://chocolatey.org/> package manager.
467
468   I don’t like the GUI or the theme. Can it be changed?
469       You can change the theme in the settings. Syncthing  ships  with  other
470       themes than the default.
471
472       If  you  want a custom theme or a completely different GUI, you can add
473       your own.  By default, Syncthing will look for a directory  gui  inside
474       the  Syncthing home folder. To change the directory to look for themes,
475       you need to set the STGUIASSETS environment variable. To get  the  con‐
476       crete directory, run syncthing with the -paths parameter. It will print
477       all the relevant paths, including the “GUI override directory”.
478
479       To  add  e.g.  a  red  theme,  you  can   create   the   file   red/as‐
480       sets/css/theme.css  inside  the  GUI override directory to override the
481       default CSS styles.
482
483       To  create  a  whole  new  GUI,  you  should  checkout  the  files   at
484       https://github.com/syncthing/syncthing/tree/main/gui/default  to get an
485       idea how to do that.
486
487   How do I upgrade Syncthing?
488       If you use a package manager such as Debian’s apt-get, you  should  up‐
489       grade  using the package manager. If you use the binary packages linked
490       from Syncthing.net, you can use Syncthing’s built-in automatic  upgrade
491       functionality.
492
493       • If  automatic  upgrades  is enabled (which is the default), Syncthing
494         will upgrade itself automatically within 24 hours of a new release.
495
496       • The upgrade button appears in the web GUI when a new version has been
497         released. Pressing it will perform an upgrade.
498
499       • To force an upgrade from the command line, run syncthing -upgrade.
500
501       Note  that  your system should have CA certificates installed which al‐
502       lows a secure connection to GitHub (e.g. FreeBSD requires sudo pkg  in‐
503       stall ca_root_nss). If curl or wget works with normal HTTPS sites, then
504       so should Syncthing.
505
506   Where do I find the latest release?
507       We release new versions through GitHub. The latest  release  is  always
508       found  on  the release page <https://github.com/syncthing/syncthing/re
509       leases/latest>. Unfortunately GitHub does not provide a single  URL  to
510       automatically download the latest version. We suggest to use the GitHub
511       API  <https://api.github.com/repos/syncthing/syncthing/releases/latest>
512       and parsing the JSON response.
513
514   How do I run Syncthing as a daemon process on Linux?
515       If  you’re using systemd, runit, or upstart, we ship example configura‐
516       tions <https://github.com/syncthing/syncthing/tree/main/etc>.
517
518       If however you’re not using one of these tools, you have  a  couple  of
519       options.   If your system has a tool called start-stop-daemon installed
520       (that’s the name of the command, not the package), look into the  local
521       documentation for that, it will almost certainly cover 100% of what you
522       want to do.  If you don’t have start-stop-daemon, there are a bunch  of
523       other  software packages you could use to do this.  The most well known
524       is called daemontools, and can be found in the standard package reposi‐
525       tories for almost every modern Linux distribution.  Other popular tools
526       with similar functionality include S6 and the aforementioned runit.
527
528   How do I increase the inotify limit to get my filesystem watcher to work?
529       You are probably reading this because you encountered the following er‐
530       ror with the filesystem watcher on linux:
531          Failed  to  start  filesystem watcher for folder yourLabel (yourID):
532          failed to setup inotify handler. Please increase inotify limits, see
533          https://docs.syncthing.net/users/faq.html#inotify-limits
534
535       Linux  typically  restricts  the  amount  of  watches per user (usually
536       8192). When you have more directories you need to adjust that number.
537
538       On many Linux distributions you can run the following to fix it:
539
540          echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf
541
542       On Arch Linux and potentially others it is preferred to write this line
543       into a separate file, i.e. you should run:
544
545          echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.d/90-override.conf
546
547       This only takes effect after a reboot. To adjust the limit immediately,
548       run:
549
550          echo 204800 | sudo tee /proc/sys/fs/inotify/max_user_watches
551
552   How do I reset the GUI password?
553       If you’ve forgotten/lost the GUI password, you can remove it by  delet‐
554       ing  the  <user>  and  <password> XML tags from the <gui> block in file
555       config.xml. This should be done while Syncthing is not running. The lo‐
556       cation of the file depends on the OS and is described in the configura‐
557       tion documentation.
558
559       For example, the two emphasized lines below would be removed  from  the
560       file.
561
562          <gui enabled="true" tls="false" debugging="false">
563             <address>127.0.0.1:8384</address>
564             <user>syncguy</user>
565             <password>$2a$10$s9wWHOQe...Cq7GPye69</password>
566             <apikey>9RCKohqCAyrj5RjpyZdR2wXmQ9PyQFeN</apikey>
567             <theme>default</theme>
568          </gui>
569

AUTHOR

571       The Syncthing Authors
572
574       2014-2019, The Syncthing Authors
575
576
577
578
579v1                               Oct 17, 2021                 SYNCTHING-FAQ(7)
Impressum