Syncthing¶

Synopsis¶

Description¶

Syncthing lets you synchronize your files bidirectionally 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.

Options¶

Write events to timestamped file audit-YYYYMMDD-HHMMSS.log .

Use specified file or stream ( «-» for stdout, «—» for stderr) for audit events, rather than the timestamped default file name.

Open the web UI in a browser for an already running Syncthing instance.

Print device ID to command line.

Generate key and config in specified dir, then exit.

Override GUI listen address. Set this to an address ( 0.0.0.0:8384 ) or file path ( /var/run/st.sock , for UNIX sockets).

Set common configuration and data directory. The default configuration directory is $HOME/.config/syncthing (Unix-like), $HOME/Library/Application Support/Syncthing (Mac) and %LOCALAPPDATA%\Syncthing (Windows).

Set configuration directory. Alternative to -home and must be used together with -data .

Set data (e.g. database) directory. Alternative to -home and must be used together with -config .

Set destination filename for logging (use «-» for stdout, which is the default option).

Select information in log line prefix. The -logflags value is a sum of the following:

4: Microsecond time

8: Long filename

16: Short filename

To prefix each log line with date and time, set -logflags=3 (1 + 2 from above). The value 0 is used to disable all of the above. The default is to show time only (2).

Do not start a browser.

Hide the console window. (On Windows only)

Do not restart Syncthing when it exits. The monitor process will still run to handle crashes and writing to logfiles (if configured to).

Print the paths used for configuration, keys, database, GUI overrides, default sync folder and the log file.

Start with all devices and folders paused.

Reset the database, forcing a full rescan and resync. Create .stfolder folders in each sync folder if they do not already exist. Caution: Ensure that all sync folders which are mountpoints are already mounted. Inconsistent versions may result if the mountpoint is later mounted and contains older versions.

Reset delta index IDs, forcing a full index exchange.

Start with all devices and folders unpaused.

Check for available upgrade.

Force upgrade directly from specified URL.

Print verbose log output.

Exit Codes¶

Upgrade not available

Exit codes over 125 are usually returned by the shell/binary loader/default signal handler. Exit codes over 128+N on Unix usually represent the signal which caused the process to exit. For example, 128 + 9 (SIGKILL) = 137 .

Proxies¶

Syncthing can use a SOCKS, HTTP, or HTTPS proxy to talk to the outside world. The proxy is used for outgoing connections only — it is not possible to accept incoming connections through the proxy. The proxy is configured through the environment variable all_proxy . Somewhat unusually, this variable must be named in lower case — it is not “ ALL_PROXY ”. For example:

Development Settings¶

The following environment variables modify Syncthing’s behavior in ways that are mostly useful for developers. Use with care. If you start Syncthing from within service managers like systemd or supervisor, path expansion may not be supported.

Used to increase the debugging verbosity in specific or all facilities, generally mapping to a Go package. Enabling any of these also enables microsecond timestamps, file names plus line numbers. Enter a comma-separated string of facilities to trace. syncthing -help always outputs an up-to-date list. The valid facility strings are:

Main and operational facilities: config

Configuration loading and saving.

The database layer.

The root hub; the largest chunk of the system. File pulling, index transmission and requests for chunks.

File change detection and hashing.

Networking facilities: beacon

Multicast and broadcast UDP discovery packets: Selected interfaces and addresses.

Remote device discovery requests, replies and registration of devices.

NAT discovery and port mapping.

NAT-PMP discovery and port mapping.

The BEP protocol.

Relay interaction ( strelaysrv ).

UPnP discovery and port mapping.

Other facilities: fs

Event generation and logging.

SHA256 hashing package (this facility currently unused).

Persistent device and folder statistics.

Mutexes. Used for debugging race conditions and deadlocks.

Filesystem access while walking.

All of the above.

Write block profiles to block-$pid-$timestamp.pprof every 20 seconds.

Write a CPU profile to cpu-$pid.pprof on exit.

Used for debugging internal deadlocks; sets debug sensitivity. Use only under direction of a developer.

Used for debugging internal deadlocks; sets debug sensitivity. Use only under direction of a developer.

Directory to load GUI assets from. Overrides compiled in assets. Useful for developing webgui, commonly use STGUIASSETS=gui bin/syncthing .

Specify which hashing package to use. Defaults to automatic based on performance. Specify “minio” (compatibility) or “standard” for the default Go implementation.

Write heap profiles to heap-$pid-$timestamp.pprof each time heap usage increases.

Don’t create a default folder when starting for the first time. This variable will be ignored anytime after the first run.

Equivalent to the -no-restart flag

Disable automatic upgrades.

Set to a listen address such as “127.0.0.1:9090” to start the profiler with HTTP access, which then can be reached at http://localhost:9090/debug/pprof. See go tool pprof for more information.

Write running performance statistics to perf-$pid.csv . Not supported on Windows.

Time before folder statistics (file, dir, … counts) are recalculated from scratch. The given duration must be parseable by Go’s time.ParseDuration. If missing or not parseable, the default value of 1 month is used. To force recalculation on every startup, set it to 1s .

Set the maximum number of CPU cores to use. Defaults to all available CPU cores.

Percentage of heap growth at which to trigger GC. Default is 100. Lower numbers keep peak memory usage down, at the price of CPU usage (i.e. performance).

See Also¶

syncthing-config(5), syncthing-stignore(5), syncthing-device-ids(7), syncthing-security(7), syncthing-networking(7), syncthing-versioning(7), syncthing-faq(7)

Starting Syncthing Automatically¶

Jump to configuration for your system:

Windows¶

There is currently no official installer available for Windows. However, there are a number of easy solutions.

Run at user log on or at system startup using Task Scheduler¶

Task Scheduler is a built-in administrative tool, which can be used to start Syncthing automatically either at user log on, or at system startup. In both cases, Syncthing will open and stay invisible in background.

For technical information about Task Scheduler visit https://docs.microsoft.com/windows/win32/taskschd.

Start the Task Scheduler either by going to Start Menu > Windows Administrative Tools and clicking on Task Scheduler , or by opening taskschd.msc from the Run command ( Win+R ).

Create a new Task (“Actions” sidebar > “Create Task…”).

Name the task (for example “Syncthing”).

Select “Run whether user is logged on or not”.

Syncthing can be set up to start either at user log on, or at system startup. Pick your preferred method and follow the instructions below. If unsure, read the explanations underneath each of the two options.

Run at user log on

Choose this option if you intend to use Syncthing only when being logged on to your Windows user account.

Set “Begin the task:” to “At log on”.

Select “Specific user:”

Run at system startup

Choose this option if you want Syncthing to open in background as soon as Windows starts, and even when not being logged on to your user account. Do not use this method if your Syncthing folders are stored on a non-system partition protected by BitLocker, as they will be inaccessible before user log on.

Set “Begin the task:” to “At startup”.

Enter the path to syncthing.exe in “Program/script:” (for example C:\syncthing\syncthing.exe ).

Enter -no-console -no-browser in “Add arguments (optional):”

Uncheck “Stop task if it runs longer than:”.

Enter password for the user.

Additional configuration in Task Scheduler¶

The following settings are optional. They are not required for Syncthing to run properly, but can offer additional functionality. Feel free to make selective use of them depending on your needs.

Uncheck “Stop if the computer switches to battery power”. Note that unchecking “Start the task only if the computer is on AC power” does not disable this option. Even if greyed out, it still applies, and has to be unchecked separately.

Uncheck “Start the task only if the computer is on AC power”.

Check “Start only if the following network connection is available” and set to “Network”. Use this option on a laptop, when you want Syncthing to start only on a wired Internet connection, and not on Wi-Fi. Note that once started, Syncthing will not stop running if the connection changes or becomes unavailable later.

Select the previously created action and click “Edit…”.

Enter the path to the parent folder of syncthing.exe in “Start in (optional)”. This will allow you to use paths relative to this folder in Syncthing.

Due to technical limitations, ending the task in Task Scheduler terminates only the monitor process of Syncthing. In order to actually exit Syncthing, open the Web GUI and press the “Shutdown” button under the “Actions” dropdown menu.

Run at user log on using the Startup folder¶

Starting Syncthing at user log on, without a console window or browser opening on start, is relatively easy.

Copy and paste %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup into the Address Bar in Windows Explorer, and press Enter.

Alternatively, in newer versions of Windows, open shell:startup from the Run command ( Win+R ).

Right-click empty space in the folder and choose “New”, and then “Shortcut”.

Enter the path to syncthing.exe in “Type the location of the item:” followed by -no-console -no-browser (for example C:\syncthing\syncthing.exe -no-console -no-browser ).

Syncthing will now automatically start the next time you log on to your user account in Windows. No console or browser window will pop-up, but you can still access the interface by opening http://localhost:8384 in a Web browser.

Install and run using third-party tools¶

There are a number of third-party utilities which aim to help install and run Syncthing more easily. These typically provide an installer, an option to start the program automatically, and a more polished user experience (e.g. by behaving as a “proper” Windows application, rather than forcing you to start a Web browser to interact with Syncthing).

Run as a service independent of user login¶

There are important security considerations with this approach. If you do not secure Syncthing’s GUI (and REST API), then any process running with any permissions can read/write any file on your filesystem, by opening a connection with Syncthing.

Therefore, you must ensure that you set a GUI password, or run Syncthing as an unprivileged user.

With the above configuration, Syncthing only starts when a user logs on to the machine. This is not optimal on servers where a machine can run long times after a reboot without anyone logged in. In this case it is best to create a service that runs as soon as Windows starts. This can be achieved using NSSM, the “Non-Sucking Service Manager”.

Note that starting Syncthing on login is the preferred approach for almost any end-user scenario. The only scenario where running Syncthing as a service makes sense is for (mostly) headless servers, administered by a sysadmin who knows enough to understand the security implications.

Download and extract nssm to a folder where it can stay. The NSSM executable performs administration as well as executing as the Windows service so it will need to be kept in a suitable location.

From an administrator Command Prompt, CD to the NSSM folder and run nssm.exe install service name>

Set Path to your syncthing.exe and enter -no-restart -no-browser -home=»

to your Syncthing folder>» as Arguments. Note: Logging is set later on. -logfile here will not be applied.

Optional: Set Startup type to Automatic (Delayed Start) to delay the start of Syncthing when the system first boots, to improve boot speed.

Enter the user account to run Syncthing as. This user needs to have full access to the Syncthing executable and its parent folder, configuration files / database folder and synced folders. You can leave this as Local System but doing so poses security risks. Setting this to your Windows user account will reduce this; ideally create a dedicated user account with minimal permissions.

Optional: Change priority to Low if you want a more responsive system at the cost of somewhat longer sync time when the system is busy.

Optional: To enable logging enable “Console window”.

To ensure Syncthing is shut down gracefully select all of the checkboxes and set all Timeouts to 10000ms.

Exit Actions Tab

Set Restart Action to Stop service (oneshot mode). Specific settings are used later for handling Syncthing exits, restarts and upgrades.

Optional: To enable logging set Output (stdout) to the file desired for logging. The Error field will be automatically set to the same file.

File Rotation Tab

Optional: Set the rotation settings to your preferences.

Click the Install Service Button

To ensure that Syncthing exits, restarts and upgrades are handled correctly by the Windows service manager, some final settings are needed. Execute these in the same Command Prompt:

nssm set syncthing AppExit Default Exit

nssm set syncthing AppExit 0 Exit

nssm set syncthing AppExit 3 Restart

nssm set syncthing AppExit 4 Restart

Start the service via sc start syncthing in the Command Prompt.

Connect to the Syncthing UI, enable HTTPS, and set a secure username and password.

macOS¶

Using homebrew¶

brew install syncthing

Follow the information presented by brew to autostart Syncthing using launchctl.

Without homebrew¶

Copy the syncthing binary (the file you would open to launch Syncthing) into a directory called bin in your home directory i.e. into /Users/ /bin. If “bin” does not exist, create it.

Open syncthing.plist located in /etc/macos-launchd. Replace the four occurrences of /Users/USERNAME with your actual home directory location.

Copy the syncthing.plist file to

/Library/LaunchAgents . If you have trouble finding this location select the “Go” menu in Finder and choose “Go to folder…” and then type

/Library/LaunchAgents . Copying to

/Library/LaunchAgents will require admin password in most cases.

Log out and back in again. Or, if you do not want to log out, you can run this command in terminal: launchctl load

Note: You probably want to turn off “Start Browser” in the web GUI settings to avoid it opening a browser window on each login. Then, to access the GUI type 127.0.0.1:8384 (by default) into Safari.

Linux¶

Using the Desktop Environment (KDE, Gnome, Xfce, Cinnamon, …)¶

You can make Syncthing start when you log into your desktop environment (DE) in two ways.

Search for and launch a tool related to autostart or startup applications.

Add a new autostart application and search for and choose “Start Syncthing”.

If you don’t find “Start Syncthing” in the steps above or just prefer doing it manually:

Find the file syncthing-start.desktop : Either from the package you downloaded from GitHub in etc/linux-desktop/ or in /usr/share/applications/ if installed from your package manager.

Copy syncthing-start.desktop to

For more information relating to .desktop files e.g. for application menus, refer to https://github.com/syncthing/syncthing/tree/main/etc/linux-desktop.

Using Supervisord¶

Go to /etc/supervisor/conf.d/ and create a new file named syncthing.conf with the following content (ensure you replaced with valid username):

and check it is all working:

In case of troubles check the logs:

Using systemd¶

systemd is a suite of system management daemons, libraries, and utilities designed as a central management and configuration platform for the Linux computer operating system. It also offers users the ability to manage services under the user’s control with a per-user systemd instance, enabling users to start, stop, enable, and disable their own units. Service files for systemd are provided by Syncthing, either in the etc/linux-systemd directory of the downloaded tarball or directly installed to the appropriate location on your system when installed through apt.syncthing.net.

You have two primary options: You can set up Syncthing as a system service, or a user service.

Running Syncthing as a system service ensures that Syncthing is run at startup even if the Syncthing user has no active session. Since the system service keeps Syncthing running even without an active user session, it is intended to be used on a server.

Running Syncthing as a user service ensures that Syncthing only starts after the user has logged into the system (e.g., via the graphical login screen, or ssh). Thus, the user service is intended to be used on a (multiuser) desktop computer. It avoids unnecessarily running Syncthing instances.

The official Debian/Ubuntu Syncthing repository, and several distros (including Arch Linux) ship these service files along with the Syncthing package. If your distro provides the systemd service files for Syncthing, you can skip step #2 when you’re setting up either the system service or the user service, as described below.

How to set up a system service¶

Create the user who should run the service, or choose an existing one.

From git location mentioned above copy the Syncthing/etc/linux-systemd/system/syncthing@.service file into the load path of the system instance.

Enable and start the service. Replace “myuser” with the actual Syncthing user after the @ :

How to set up a user service¶

Create the user who should run the service, or choose an existing one. Probably this will be your own user account.

Copy the Syncthing/etc/linux-systemd/user/syncthing.service file into the load path of the user instance. To do this without root privileges you can just use this folder under your home directory:

Enable and start the service:

If your home directory is encrypted with eCryptfs on Debian/Ubuntu, then you will need to make the change described in Ubuntu bug 1734290. Otherwise the user service will not start, because by default, systemd checks for user services before your home directory has been decrypted.

Checking the service status¶

To check if Syncthing runs properly you can use the status subcommand. To check the status of a system service:

To check the status of a user service:

Using the journal¶

Systemd logs everything into the journal, so you can easily access Syncthing log messages. In both of the following examples, -e tells the pager to jump to the very end, so that you see the most recent logs.

To see the logs for the system service:

To see the logs for the user service:

Permissions¶

If you enabled the Ignore Permissions option in the Syncthing client’s folder settings, then you will also need to add the line UMask=0002 (or any other umask setting you like) in the [Service] section of the syncthing@.service file.

Debugging¶

If you are asked on the bugtracker to start Syncthing with specific environment variables it will not work the normal way. Systemd isolates each service and it cannot access global environment variables. The solution is to add the variables to the service file instead.