syncthing/man/syncthing-faq.7

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SYNCTHING-FAQ" "7" "May 08, 2024" "v1.27.7" "Syncthing"
.SH NAME
syncthing-faq \- Frequently Asked Questions
.INDENT 0.0
.IP \(bu 2
\fI\%General\fP
.INDENT 2.0
.IP \(bu 2
\fI\%What is Syncthing?\fP
.IP \(bu 2
\fI\%Is it “syncthing”, “Syncthing” or “SyncThing”?\fP
.IP \(bu 2
\fI\%What things are synced?\fP
.IP \(bu 2
\fI\%Is synchronization fast?\fP
.IP \(bu 2
\fI\%How does Syncthing differ from BitTorrent/Resilio Sync?\fP
.IP \(bu 2
\fI\%Is there an iOS client?\fP
.IP \(bu 2
\fI\%Should I keep my device IDs secret?\fP
.UNINDENT
.IP \(bu 2
\fI\%Troubleshooting\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Where are the Syncthing logs?\fP
.IP \(bu 2
\fI\%Why is the sync so slow?\fP
.IP \(bu 2
\fI\%Why does it use so much CPU?\fP
.IP \(bu 2
\fI\%Why is the setup more complicated than BitTorrent/Resilio Sync?\fP
.IP \(bu 2
\fI\%Why do I get “Host check error” in the GUI/API?\fP
.IP \(bu 2
\fI\%My Syncthing database is corrupt\fP
.IP \(bu 2
\fI\%Why do I see Syncthing twice in task manager?\fP
.IP \(bu 2
\fI\%How can I view the history of changes?\fP
.IP \(bu 2
\fI\%Does the audit log contain every change?\fP
.IP \(bu 2
\fI\%Why does Syncthing connect to this unknown/suspicious address?\fP
.IP \(bu 2
\fI\%I am seeing the error message “folder marker missing”. What do I do?\fP
.UNINDENT
.IP \(bu 2
\fI\%Usage\fP
.INDENT 2.0
.IP \(bu 2
\fI\%What if there is a conflict?\fP
.IP \(bu 2
\fI\%How do I serve a folder from a read only filesystem?\fP
.IP \(bu 2
\fI\%I really hate the .stfolder directory, can I remove it?\fP
.IP \(bu 2
\fI\%Am I able to nest shared folders in Syncthing?\fP
.IP \(bu 2
\fI\%How do I rename/move a synced folder?\fP
.IP \(bu 2
\fI\%How do I configure multiple users on a single machine?\fP
.IP \(bu 2
\fI\%Does Syncthing support syncing between folders on the same system?\fP
.IP \(bu 2
\fI\%When I do have two distinct Syncthing\-managed folders on two hosts, how does Syncthing handle moving files between them?\fP
.IP \(bu 2
\fI\%Can I help initial sync by copying files manually?\fP
.IP \(bu 2
\fI\%Is Syncthing my ideal backup application?\fP
.IP \(bu 2
\fI\%How can I exclude files with brackets ([]) in the name?\fP
.IP \(bu 2
\fI\%How do I access the web GUI from another computer?\fP
.IP \(bu 2
\fI\%I don’t like the GUI or the theme. Can it be changed?\fP
.IP \(bu 2
\fI\%How do I upgrade Syncthing?\fP
.IP \(bu 2
\fI\%Where do I find the latest release?\fP
.IP \(bu 2
\fI\%How do I run Syncthing as a daemon process on Linux?\fP
.IP \(bu 2
\fI\%How do I increase the inotify limit to get my filesystem watcher to work?\fP
.IP \(bu 2
\fI\%How do I reset the GUI password?\fP
.UNINDENT
.UNINDENT
.SH GENERAL
.SS What is Syncthing?
.sp
Syncthing is an application that lets you synchronize your files across multiple
devices. This means the creation, modification or deletion of files on one
machine will automatically be replicated to your other devices. We believe your
data is your data alone and you deserve to choose where it is stored. Therefore
Syncthing does not upload your data to the cloud but exchanges your data across
your machines as soon as they are online at the same time.
.SS Is it “syncthing”, “Syncthing” or “SyncThing”?
.sp
It’s \fBSyncthing\fP, although the command and source repository is spelled
\fBsyncthing\fP so it may be referred to in that way as well. It’s definitely not
SyncThing, even though the abbreviation \fBst\fP is used in some
circumstances and file names.
.SS What things are synced?
.sp
The following things are \fIalways\fP synchronized:
.INDENT 0.0
.IP \(bu 2
File contents
.IP \(bu 2
File modification times
.UNINDENT
.sp
The following may be synchronized or not, depending:
.INDENT 0.0
.IP \(bu 2
File permissions (when supported by file system; on Windows only the
read only bit is synchronized)
.IP \(bu 2
Symbolic links (synced, except on Windows, but never followed)
.IP \(bu 2
File or directory owners and groups (when enabled)
.IP \(bu 2
Extended attributes (when enabled)
.IP \(bu 2
POSIX or NFS ACLs (as part of extended attributes)
.UNINDENT
.sp
The following are \fInot\fP synchronized;
.INDENT 0.0
.IP \(bu 2
Directory modification times (not preserved)
.IP \(bu 2
Hard links (followed, not preserved)
.IP \(bu 2
Windows junctions (synced as ordinary directories; require enabling in
\X'tty: link #config-option-folder.junctionsasdirs'\fI\%the configuration\fP\X'tty: link' on a per\-folder
basis)
.IP \(bu 2
Resource forks (not preserved)
.IP \(bu 2
Windows ACLs (not preserved)
.IP \(bu 2
Devices, FIFOs, and other specials (ignored)
.IP \(bu 2
Sparse file sparseness (will become sparse, when supported by the OS & filesystem)
.IP \(bu 2
Syncthing internal files and folders (e.g. \fB\&.stfolder\fP, \fB\&.stignore\fP,
\fB\&.stversions\fP, \X'tty: link #temporary-files'\fI\%temporary files\fP\X'tty: link', etc.)
.UNINDENT
.SS Is synchronization fast?
.sp
Syncthing segments files into pieces, called blocks, to transfer data from one
device to another. Therefore, multiple devices can share the synchronization
load, in a similar way to the torrent protocol. The more devices you have online,
the faster an additional device will receive the data
because small blocks will be fetched from all devices in parallel.
.sp
Syncthing handles renaming files and updating their metadata in an efficient
manner. This means that renaming a file will not cause a retransmission of
that file. Additionally, appending data to existing files should be handled
efficiently as well.
.sp
\X'tty: link #temporary-files'\fI\%Temporary files\fP\X'tty: link' are used to store partial data
downloaded from other devices. They are automatically removed whenever a file
transfer has been completed or after the configured amount of time which is set
in the configuration file (24 hours by default).
.SS How does Syncthing differ from BitTorrent/Resilio Sync?
.sp
The two are different and not related. Syncthing and BitTorrent/Resilio Sync accomplish
some of the same things, namely syncing files between two or more computers.
.sp
BitTorrent Sync, now called Resilio Sync, is a proprietary peer\-to\-peer file
synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows
Phone, Amazon Kindle Fire and BSD. [1] Syncthing is an open source file
synchronization tool.
.sp
Syncthing uses an open and documented protocol, and likewise the security
mechanisms in use are well defined and visible in the source code. Resilio
Sync uses an undocumented, closed protocol with unknown security properties.
.IP [1] 5
\X'tty: link https://en.wikipedia.org/wiki/Resilio_Sync'\fI\%https://en.wikipedia.org/wiki/Resilio_Sync\fP\X'tty: link'
.SS Is there an iOS client?
.sp
There are no plans by the current Syncthing team to officially support iOS in the foreseeable future.
.sp
iOS has significant restrictions on background processing that make it very hard to
run Syncthing reliably and integrate it into the system.
.sp
However, there is a commercial packaging of Syncthing for iOS that attempts to work within these limitations. [2]
.IP [2] 5
\X'tty: link https://www.mobiussync.com'\fI\%https://www.mobiussync.com\fP\X'tty: link'
.SS Should I keep my device IDs secret?
.sp
No. The IDs are not sensitive. Given a device ID it’s possible to find the IP
address for that device, if global discovery is enabled on it. Knowing the device
ID doesn’t help you actually establish a connection to that device or get a list
of files, etc.
.sp
For a connection to be established, both devices need to know about the other’s
device ID. It’s not possible (in practice) to forge a device ID. (To forge a
device ID you need to create a TLS certificate with that specific SHA\-256 hash.
If you can do that, you can spoof any TLS certificate. The world is your
oyster!)
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\X'tty: link #device-ids'\fI\%Understanding Device IDs\fP\X'tty: link'
.UNINDENT
.UNINDENT
.SH TROUBLESHOOTING
.SS Where are the Syncthing logs?
.sp
Syncthing logs to stdout by default. On Windows Syncthing by default also
creates \fBsyncthing.log\fP in Syncthing’s home directory (run \fBsyncthing
\-\-paths\fP to see where that is). The command line option \fB\-\-logfile\fP can be
used to specify a user\-defined logfile.  If you only have access to a running
instance’s GUI, check under the \fIActions\fP \- \fIAbout\fP menu item to see the used
paths.
.sp
If you’re running a process manager like systemd, check there. If you’re
using a GUI wrapper integration, it may keep the logs for you.
.SS Why is the sync so slow?
.sp
When troubleshooting a slow sync, there are a number of things to check.
.sp
First of all, verify that you are not connected via a relay. In the “Remote
Devices” list on the right side of the GUI, double check that you see
“Address: <some address>” and \fInot\fP “Relay: <some address>”.
[image]
.sp
If you are connected via a relay, this is because a direct connection could
not be established. Double check and follow the suggestions in
\X'tty: link #firewall-setup'\fI\%Firewall Setup\fP\X'tty: link' to enable direct connections.
.sp
Second, if one of the devices is a very low powered machine (a Raspberry Pi,
or a phone, or a NAS, or similar) you are likely constrained by the CPU on
that device. See the next question for reasons Syncthing likes a faster CPU.
.sp
Third, verify that the network connection is OK. Tools such as iperf or just
an Internet speed test can be used to verify the performance here.
.SS Why does it use so much CPU?
.INDENT 0.0
.IP 1. 3
When new or changed files are detected, or Syncthing starts for the
first time, your files are hashed using SHA\-256.
.IP 2. 3
Data that is sent over the network is compressed (optionally) and
encrypted (always). When receiving data it must be decrypted and then (if
compressed) decompressed.
.IP 3. 3
There is a certain amount of housekeeping that must be done to track the
current and available versions of each file in the index database.
.IP 4. 3
By default Syncthing uses periodic scanning every hour when watching for
changes or every minute if that’s disabled to detect
file changes. This means checking every file’s modification time and
comparing it to the database. This can cause spikes of CPU usage for large
folders.
.UNINDENT
.sp
Hashing, compression and encryption cost CPU time. Also, using the GUI
causes a certain amount of extra CPU usage to calculate the summary data it
presents. Note however that once things are \fIin sync\fP CPU usage should be
negligible.
.sp
To minimize the impact of this, Syncthing attempts to \X'tty: link #config-option-options.setlowpriority'\fI\%lower the
process priority\fP\X'tty: link' when starting up.
.sp
To further limit the amount of CPU used when syncing and scanning, set the
environment variable \fBGOMAXPROCS\fP to the maximum number of CPU cores
Syncthing should use at any given moment. For example, \fBGOMAXPROCS=2\fP on a
machine with four cores will limit Syncthing to no more than half the
system’s CPU power.
.SS Why is the setup more complicated than BitTorrent/Resilio Sync?
.sp
Security over convenience. In Syncthing you have to setup both sides to
connect two devices. An attacker can’t do much with a stolen device ID, because
you have to add the device on the other side too. You have better control
where your files are transferred.
.sp
This is an area that we are working to improve in the long term.
.SS Why do I get “Host check error” in the GUI/API?
.sp
Since version 0.14.6 Syncthing does an extra security check when the GUI/API
is bound to localhost \- namely that the browser is talking to localhost.
This protects against most forms of \X'tty: link https://en.wikipedia.org/wiki/DNS_rebinding'\fI\%DNS rebinding attack\fP <\fBhttps://en.wikipedia.org/wiki/DNS_rebinding\fP>\X'tty: link' against the GUI.
.sp
To pass this test, ensure that you are accessing the GUI using an URL that
begins with \fBhttp://localhost\fP, \fBhttp://127.0.0.1\fP or \fBhttp://[::1]\fP\&. HTTPS
is fine too, of course.
.sp
If you are using a proxy in front of Syncthing you may need to disable this
check, after ensuring that the proxy provides sufficient authentication to
protect against unauthorized access. Either:
.INDENT 0.0
.IP \(bu 2
Make sure the proxy sets a \fBHost\fP header containing \fBlocalhost\fP, or
.IP \(bu 2
Set \X'tty: link #config-option-gui.insecureskiphostcheck'\fI\%gui.insecureSkipHostcheck\fP\X'tty: link' in the advanced settings, or
.IP \(bu 2
Bind the GUI/API to a non\-localhost listen port.
.UNINDENT
.sp
In all cases, username/password authentication and HTTPS should be used.
.SS My Syncthing database is corrupt
.sp
This is almost always a result of bad RAM, storage device or other hardware.
When the index database is found to be corrupt Syncthing cannot operate and will
note this in the logs and exit. To overcome this delete the \X'tty: link #config-locations'\fI\%database
folder\fP\X'tty: link' inside Syncthing’s data directory and re\-start
Syncthing. It will then need to perform a full re\-hashing of all shared
folders. You should check your system in case the underlying cause is indeed
faulty hardware which may put the system at risk of further data loss.
.SS Why do I see Syncthing twice in task manager?
.sp
One process manages the other, to capture logs and manage restarts. This
makes it easier to handle upgrades from within Syncthing itself, and also
ensures that we get a nice log file to help us narrow down the cause for
crashes and other bugs.
.SS How can I view the history of changes?
.sp
The web GUI contains a \fBRecent Changes\fP button under the device list which
displays changes since the last (re)start of Syncthing. With the \fB\-\-audit\fP
option you can enable a persistent, detailed log of changes and most
activities, which contains a JSON\-formatted sequence of events in the
\fB~/.local/state/syncthing/audit\-_date_\-_time_.log\fP file.
.SS Does the audit log contain every change?
.sp
The audit log (and the \fBRecent Changes\fP window) sees the changes that your
Syncthing sees. When Syncthing is continuously connected it usually sees every change
happening immediately and thus knows which node initiated the change.
When topology gets complex or when your node reconnects after some time offline,
Syncthing synchronises with its neighbours: It gets the latest synchronised state
from the neighbour, which is the \fIresult\fP of all the changes between the last
known state (before disconnect or network delay) and the current state at the
neighbour, and if there were updates, deletes, creates, conflicts, which were
overlapping we only see the \fIlatest change\fP for a given file or directory (and
the node where that latest change occurred). When we connect to multiple neighbours
Syncthing decides which neighbour has the latest state, or if the states conflict
it initiates the conflict resolution procedure, which in the end results in a consistent
up\-to\-date state with all the neighbours.
.SS Why does Syncthing connect to this unknown/suspicious address?
.sp
If you see outgoing connections to odd and unexpected addresses these are
most likely connections to \X'tty: link #relaying'\fI\%relay servers\fP\X'tty: link'\&. Relay servers
are run by volunteers all over the world. They usually listen on ports 443 or
22067, though this is controlled by the user running it. You can compare the
address you are concerned about with \X'tty: link https://relays.syncthing.net'\fI\%the current list of active relays\fP <\fBhttps://relays.syncthing.net\fP>\X'tty: link'\&. Relays do not and can not see the data
transmitted via them.
.SS I am seeing the error message “folder marker missing”. What do I do?
.sp
Syncthing uses a specific marker usually called \fB\&.stfolder\fP to determine whether
a folder is healthy. This is a safety check to ensure that your folder is properly
readable and present on disk. For example, if you remove a USB drive from your computer
or unmount a filesystem, then syncthing must know whether you have really deleted \fBall\fP of
your files. Therefore, syncthing always checks that the \fB\&.stfolder\fP is present.
.sp
When this error appears, syncthing assumes that the folder has encountered some type of error
and will stop syncing it until the \fB\&.stfolder\fP reappears. Once that happens, all changes made
to the folder locally will be synced (i.e. missing files will be considered deletions).
.INDENT 0.0
.IP \(bu 2
If you get this error message, check the folder in question on your storage. If you have
unmounted the folder (or a parent of it), you must remount it for syncthing to resume syncing
this folder.
.IP \(bu 2
If you have moved the folder, you must either move it back to its original location, or remove the
folder from within the syncthing UI and re\-add it at its new location.
.IP \(bu 2
If the folder is present on disk, with all of its children files and directories, but the \fB\&.stfolder\fP
is still missing:
.sp
It is possible that a file cleaning software has removed the \fB\&.stfolder\fP\&. Some software
removes empty folders, and the \fB\&.stfolder\fP is often empty. This happens particularly often on Android.
To remediate, recreate the \fB\&.stfolder\fP and add a dummy file in it, or add an exception to your
cleaning software.
.UNINDENT
.sp
If you are still unsure what has happened, you can remove the folder from within the syncthing UI and re\-add it
at the same location. This causes syncthing to attempt an automatic re\-creation of the \fB\&.stfolder\fP\&. Next,
it will also reset the database state of this folder. It will be considered a “new” folder, meaning that its files
will be merged with files from remote devices.
.sp
Also see the \fI\%marker FAQ\fP for more information about the folder marker.
.SH USAGE
.SS What if there is a conflict?
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\X'tty: link #conflict-handling'\fI\%Conflicting Changes\fP\X'tty: link'
.UNINDENT
.UNINDENT
.SS How do I serve a folder from a read only filesystem?
.sp
Syncthing requires a “folder marker” to indicate that the folder is present
and healthy. By default this is a directory called \fB\&.stfolder\fP that is
created by Syncthing when the folder is added. If this folder can’t be
created (you are serving files from a CD or something) you can instead set
the advanced config \fBMarker Name\fP to the name of some file or folder that
you know will always exist in the folder.
.SS I really hate the \fB\&.stfolder\fP directory, can I remove it?
.sp
See the previous question.
.SS Am I able to nest shared folders in Syncthing?
.sp
Sharing a folder that is within an already shared folder is possible, but it has
its caveats. What you must absolutely avoid are circular shares. This is just
one example, there may be other undesired effects. Nesting shared folders is not
supported, recommended or coded for, but it can be done successfully when you
know what you’re doing \- you have been warned.
.SS How do I rename/move a synced folder?
.sp
Syncthing doesn’t have a direct way to do this, as it’s potentially
dangerous to do so if you’re not careful \- it may result in data loss if
something goes wrong during the move and is synchronized to your other
devices.
.sp
The easy way to rename or move a synced folder on the local system is to
remove the folder in the Syncthing UI, move it on disk, then re\-add it using
the new path.
.sp
It’s important to do this when the folder is already in sync between your
devices, as it is otherwise unpredictable which changes will “win” after the
move. Changes made on other devices may be overwritten, or changes made
locally may be overwritten by those on other devices.
.sp
An alternative way is to shut down Syncthing, move the folder on disk (including
the \fB\&.stfolder\fP marker), edit the path directly in \fBconfig.xml\fP in the
configuration folder (see \fI\%Syncthing Configuration\fP) and then start Syncthing again.
.SS How do I configure multiple users on a single machine?
.sp
Each user should run their own Syncthing instance. Be aware that you might need
to configure listening ports such that they do not overlap (see \fI\%Syncthing Configuration\fP).
.SS Does Syncthing support syncing between folders on the same system?
.sp
No. Syncthing is not designed to sync locally and the overhead involved in
doing so using Syncthing’s method would be wasteful. There are better
programs to achieve this such as \X'tty: link https://rsync.samba.org/'\fI\%rsync\fP <\fBhttps://rsync.samba.org/\fP>\X'tty: link' or
\X'tty: link https://www.cis.upenn.edu/~bcpierce/unison'\fI\%Unison\fP <\fBhttps://www.cis.upenn.edu/~bcpierce/unison\fP>\X'tty: link'\&.
.SS When I do have two distinct Syncthing\-managed folders on two hosts, how does Syncthing handle moving files between them?
.sp
Syncthing does not specially handle this case, and most files will most likely get
re\-downloaded.
.sp
In detail, the behavior depends on the scan order. If you have folders A and B,
and move files from A to B, if A gets scanned first, it will announce the removal of
the files to others who will then remove the files. As you rescan B, B will
announce the addition of new files, and other peers will have nowhere to get
them from apart from re\-downloading them.
.sp
If B gets rescanned first, B will announce additions first, and remote
peers will then reconstruct the files (not rename, more like copying block by
block) from A, and then as A gets rescanned, it will remove the files from A.
.sp
A workaround would be to copy first from A to B, rescan B, wait for B to
copy the files on the remote side, and then delete from A.
.SS Can I help initial sync by copying files manually?
.sp
If you have a large folder that you want to keep in sync over a not\-so\-fast network, and you have the possibility to move all files to the remote device in a faster manner, here is a procedure to follow:
.INDENT 0.0
.IP \(bu 2
Create the folder on the local device, but don’t share it with the remote device yet.
.IP \(bu 2
Copy the files from the local device to the remote device using regular file copy. If this takes a long time (perhaps requiring travelling there physically), it may be a good idea to make sure that the files on the local device are not updated while you are doing this.
.IP \(bu 2
Create the folder on the remote device, and copy the Folder ID from the folder on the local device, as we want the folders to be considered the same. Then wait until scanning the folder is done.
.IP \(bu 2
Now share the folder with the other device, on both sides. Syncthing will exchange file information, updating the database, but existing files will not be transferred. This may still take a while initially, be patient and wait until it settled.
.UNINDENT
.SS Is Syncthing my ideal backup application?
.sp
No. Syncthing is not a great backup application because all changes to your
files (modifications, deletions, etc.) will be propagated to all your
devices. You can enable versioning, but we encourage you to use other tools
to keep your data safe from your (or our) mistakes.
.SS How can I exclude files with brackets (\fB[]\fP) in the name?
.sp
The patterns in .stignore are glob patterns, where brackets are used to
denote character ranges. That is, the pattern \fBq[abc]x\fP will match the
files \fBqax\fP, \fBqbx\fP and \fBqcx\fP\&.
.sp
To match an actual file \fIcalled\fP \fBq[abc]x\fP the pattern needs to “escape”
the brackets, like so: \fBq\e[abc\e]x\fP\&.
.sp
On Windows, escaping special characters is not supported as the \fB\e\fP
character is used as a path separator.
.SS How do I access the web GUI from another computer?
.sp
The default listening address is 127.0.0.1:8384, so you can only access the GUI
from the same machine.  This is for security reasons.  To access it from another
computer, change the \fBGUI listen address\fP option in the web GUI from
\fB127.0.0.1:8384\fP to \fB0.0.0.0:8384\fP, or change the \fBconfig.xml\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
<gui enabled=\(dqtrue\(dq tls=\(dqfalse\(dq>
  <address>127.0.0.1:8384</address>
.EE
.UNINDENT
.UNINDENT
.sp
to
.INDENT 0.0
.INDENT 3.5
.sp
.EX
<gui enabled=\(dqtrue\(dq tls=\(dqtrue\(dq>
  <address>0.0.0.0:8384</address>
.EE
.UNINDENT
.UNINDENT
.sp
Then the GUI is accessible from everywhere.  There is no filtering based on
e.g. source address (use a firewall for that).  You should set a password and
enable HTTPS with this configuration.  You can do this from inside the GUI.
.sp
If both your computers are Unix\-like (Linux, Mac, etc.) you can also leave the
GUI settings at default and use an SSH port forward to access it.  For example,
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ ssh \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.EE
.UNINDENT
.UNINDENT
.sp
will log you into \fBothercomputer.example.com\fP, and present the \fIremote\fP
Syncthing GUI on \X'tty: link http://localhost:9090'\fI\%http://localhost:9090\fP\X'tty: link' on your \fIlocal\fP computer.
.sp
If you only want to access the remote GUI and don’t want the terminal session,
use this example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ ssh \-N \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.EE
.UNINDENT
.UNINDENT
.sp
If only your remote computer is Unix\-like, you can still access it with SSH from
Windows.  Under Windows 10 or later you can use the same \fBssh\fP command if you
\X'tty: link https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse'\fI\%install the OpenSSH Client\fP <\fBhttps://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse\fP>\X'tty: link'\&.
.SS I don’t like the GUI or the theme. Can it be changed?
.sp
You can change the theme in the settings. Syncthing ships with other themes
than the default.
.sp
If you want a custom theme or a completely different GUI, you can add your
own.
By default, Syncthing will look for a directory \fBgui\fP inside the Syncthing
home folder. To change the directory to look for themes, you need to set the
STGUIASSETS environment variable. To get the concrete directory, run
syncthing with the \fB\-\-paths\fP parameter. It will print all the relevant paths,
including the “GUI override directory”.
.sp
To add e.g. a red theme, you can create the file \fBred/assets/css/theme.css\fP
inside the GUI override directory to override the default CSS styles.
.sp
To create a whole new GUI, you should checkout the files at
\X'tty: link https://github.com/syncthing/syncthing/tree/main/gui/default'\fI\%https://github.com/syncthing/syncthing/tree/main/gui/default\fP\X'tty: link'
to get an idea how to do that.
.SS How do I upgrade Syncthing?
.sp
If you use a package manager such as Debian’s apt\-get, you should upgrade
using the package manager. If you use the binary packages linked from
Syncthing.net, you can use Syncthing’s built\-in automatic upgrade functionality.
.INDENT 0.0
.IP \(bu 2
If automatic upgrades is enabled (which is the default), Syncthing will
upgrade itself automatically within 24 hours of a new release.
.IP \(bu 2
The upgrade button appears in the web GUI when a new version has been
released. Pressing it will perform an upgrade.
.IP \(bu 2
To force an upgrade from the command line, run \fBsyncthing \-\-upgrade\fP\&.
.UNINDENT
.sp
Note that your system should have CA certificates installed which allows a
secure connection to GitHub (e.g. FreeBSD requires \fBsudo pkg install
ca_root_nss\fP). If \fBcurl\fP or \fBwget\fP works with normal HTTPS sites, then
so should Syncthing.
.SS Where do I find the latest release?
.sp
We release new versions through GitHub. The latest release is always found
\X'tty: link https://github.com/syncthing/syncthing/releases/latest'\fI\%on the release page\fP <\fBhttps://github.com/syncthing/syncthing/releases/latest\fP>\X'tty: link'\&. Unfortunately
GitHub does not provide a single URL to automatically download the latest
version. We suggest to use the \X'tty: link https://api.github.com/repos/syncthing/syncthing/releases/latest'\fI\%GitHub API\fP <\fBhttps://api.github.com/repos/syncthing/syncthing/releases/latest\fP>\X'tty: link' and parsing
the JSON response.
.SS How do I run Syncthing as a daemon process on Linux?
.sp
If you’re using systemd, runit, or upstart, we ship \X'tty: link https://github.com/syncthing/syncthing/tree/main/etc'\fI\%example configurations\fP <\fBhttps://github.com/syncthing/syncthing/tree/main/etc\fP>\X'tty: link'\&.
.sp
If however you’re not using one of these tools, you have a couple of options.
If your system has a tool called \fBstart\-stop\-daemon\fP installed (that’s the name
of the command, not the package), look into the local documentation for that, it
will almost certainly cover 100% of what you want to do.  If you don’t have
\fBstart\-stop\-daemon\fP, there are a bunch of other software packages you could use
to do this.  The most well known is called daemontools, and can be found in the
standard package repositories for almost every modern Linux distribution.
Other popular tools with similar functionality include S6 and the aforementioned
runit.
.SS How do I increase the inotify limit to get my filesystem watcher to work?
.sp
You are probably reading this because you encountered the following error with
the filesystem watcher on linux:
.INDENT 0.0
.INDENT 3.5
Failed to start filesystem watcher for folder yourLabel (yourID): failed to
setup inotify handler. Please increase inotify limits, see \X'tty: link https://docs.syncthing.net/users/faq.html#inotify-limits'\fI\%https://docs.syncthing.net/users/faq.html#inotify\-limits\fP\X'tty: link'
.UNINDENT
.UNINDENT
.sp
Linux typically restricts the number of watches per user (usually 8192). If
you have many directories, you will need to adjust that number.
.sp
On many Linux distributions you can run the following to fix it:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo \(dqfs.inotify.max_user_watches=204800\(dq | sudo tee \-a /etc/sysctl.conf
.EE
.UNINDENT
.UNINDENT
.sp
On Arch Linux and potentially others it is preferred to write this line into a
separate file, i.e. you should run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo \(dqfs.inotify.max_user_watches=204800\(dq | sudo tee \-a /etc/sysctl.d/90\-override.conf
.EE
.UNINDENT
.UNINDENT
.sp
This only takes effect after a reboot. To adjust the limit immediately, run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
echo 204800 | sudo tee /proc/sys/fs/inotify/max_user_watches
.EE
.UNINDENT
.UNINDENT
.SS How do I reset the GUI password?
.sp
If you’ve forgotten / lost the GUI password, you can reset it using the
\X'tty: link #cmdoption-gui-password'\fI\%\-\-gui\-password\fP\X'tty: link' (and possibly \X'tty: link #cmdoption-gui-user'\fI\%\-\-gui\-user\fP\X'tty: link') options to the
\fBsyncthing generate\fP subcommand.  This should be done while Syncthing is not
running.
.INDENT 0.0
.IP 1. 3
Stop Syncthing: \fBsyncthing cli operations shutdown\fP
.IP 2. 3
\fBsyncthing generate \-\-gui\-password=myNewPassword \-\-gui\-user=newUserName\fP
.IP 3. 3
Restart Syncthing as usual.
.UNINDENT
.sp
\fIAlternatively, in step 2\fP, you can manually delete the \X'tty: link #config-option-gui.user'\fI\%<user>\fP\X'tty: link' and \X'tty: link #config-option-gui.password'\fI\%<password>\fP\X'tty: link' XML tags from the
\fB<gui>\fP block in file \fBconfig.xml\fP\&.  The location of the file depends on the
OS and is described in the \fI\%configuration documentation\fP\&.
.sp
For example, the two emphasized lines below would be removed from the file.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
<gui enabled=\(dqtrue\(dq tls=\(dqfalse\(dq debugging=\(dqfalse\(dq>
   <address>127.0.0.1:8384</address>
   <user>syncguy</user>
   <password>$2a$10$s9wWHOQe...Cq7GPye69</password>
   <apikey>9RCKohqCAyrj5RjpyZdR2wXmQ9PyQFeN</apikey>
   <theme>default</theme>
</gui>
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.