Technical Docs

How to Use Syncthing: Practical Notes from Device Pairing to File Sync

A practical guide to Syncthing based on the official documentation: device IDs, folder sharing, folder types, firewall ports, ignore rules, file versioning, security boundaries, and what to watch for when syncing between NAS, Windows, and Android devices.

Syncthing Series

Syncthing is well suited for peer-to-peer file synchronization between multiple devices. It is not a traditional cloud drive, and it does not first upload all data to a central server before downloading it elsewhere. Instead, authorized devices exchange files directly.

If you are considering it for Markdown notes, photo backup, configuration files, or a home NAS directory, the first question is not just whether it can sync. You should first understand devices, folders, device IDs, sync direction, discovery, and conflict handling.

What Syncthing Solves

Syncthing is designed for one core scenario: you have two or more devices and want a directory to stay consistent across them.

Typical examples include:

  • Syncing work files between a Windows desktop and laptop.
  • Syncing photos or documents between a phone and NAS.
  • Syncing small scripts, examples, or configuration notes between Linux servers.
  • Keeping Obsidian notes, Joplin attachments, or Markdown folders available on several devices.

It is better for cases where you control the devices and the data. If you need team permissions, web previews, sharing links, or collaborative editing, a conventional cloud drive or document platform may fit better.

What Happens on First Start

The official getting started guide suggests configuring two machines side by side. In Syncthing, each machine is a device. The machine you are configuring is the local device, while the other machine is a remote device.

On first start, Syncthing creates its configuration, cryptographic keys, and device ID. It also opens the local Web GUI by default:

1

http://127.0.0.1:8384/

The Web GUI is the everyday configuration interface. Syncthing may also create a default folder, usually a Sync directory under your user profile. You can use it for testing, or remove it later and add your own folders.

Device ID Is the Basis of Pairing

Syncthing pairs devices through device IDs.

Each device creates its own key on first start. The device ID is a readable fingerprint of that device certificate. Two devices only establish a sync relationship after they have added each other’s device ID.

A typical flow is:

  1. Start Syncthing on both devices.
  2. Open the Web GUI on both sides.
  3. Add device B’s device ID on device A.
  4. Add device A’s device ID on device B.
  5. Choose which folders to share.
  6. Save and wait for the connection.

The device ID does not need to be protected like a password, but you should not publish your sync topology unnecessarily. The things that really need protection are the device private key, Web GUI access, and the synced folders themselves.

Syncthing Does Not Sync the Whole Machine

Syncthing only syncs folders that you explicitly add. It does not sync an entire device by default.

Each folder has its own path, ID, shared devices, and folder type. It is usually better to separate folders by purpose:

  • notes/: Markdown notes.
  • photos-inbox/: phone photo intake.
  • docs/: documents shared across devices.
  • scripts/: scripts and configuration examples.

Do not start by syncing huge system directories, download directories, or mixed folders. The more complex the directory, the more likely conflicts, ignore rules, permissions, and scan cost will become long-term problems.

Three Common Folder Types

The official documentation explains folder types clearly. In practice, you mainly need to understand these three.

Send & Receive

This is the default mode. The folder sends local changes and receives remote changes.

It fits:

  • Editing notes across several devices.
  • Maintaining documents on multiple devices.
  • Normal two-way synchronization.

If two devices modify the same file at the same time, Syncthing creates a conflict file instead of silently overwriting one side.

Send Only

This mode treats the local folder as the reference copy. It sends changes to other devices, but does not apply changes from them.

It fits:

  • A primary device distributing files to backup devices.
  • Cases where one machine should be authoritative.
  • Situations where remote changes should not affect the local folder.

If remote changes appear, the local device may show the folder as out of sync. The Web GUI can then offer Override Changes, which pushes the local state to the rest of the cluster. Use that button carefully.

Receive Only

This is the opposite of Send Only. The folder receives cluster changes, but local changes are not sent to other devices.

It fits:

  • Backup targets.
  • Read-only mirrors.
  • Devices where local mistakes should not pollute the main sync set.

If local changes appear, the Web GUI may offer Revert Local Changes to return the folder to the cluster state.

Check Firewall and Ports First

Syncthing can use discovery, NAT traversal, and relays, but connections are more stable when the network is understood.

The important ports listed in the official firewall guide are:

1
2
3

22000/TCP
22000/UDP
21027/UDP

Where:

  • 22000/TCP is used for TCP sync traffic.
  • 22000/UDP is used for QUIC sync traffic.
  • 21027/UDP is used for local discovery.

If devices are on the same LAN but cannot discover each other, first check local firewalls, router isolation, and whether Wi-Fi and wired networks are on different segments.

Across the internet or NAT, direct connections are usually faster than relays when port forwarding is possible. Without port forwarding, relays can still help devices connect, but performance is often worse.

On Linux with ufw and the corresponding application profile installed, you can use:

1
2

sudo ufw allow syncthing
sudo ufw status verbose

The Web GUI listens on 127.0.0.1:8384 by default. If you change it to 0.0.0.0:8384, the management interface becomes reachable from outside the machine. At that point you must think about passwords, HTTPS, reverse proxies, or SSH tunnels. For home use, an SSH tunnel is usually safer.

.stignore Belongs in the Sync Root

If some files should not sync, create a .stignore file in the root of the synced folder.

Important details:

  • .stignore must be in the root of the synced folder.
  • Rules are relative to that root.
  • .stignore itself is not synced to other devices.
  • The file should use UTF-8.

A simple example:

1
2
3
4
5

(?d).DS_Store
node_modules
*.tmp
cache/**
!/cache/keep.txt

(?d) means Syncthing may delete those ignored files when they would otherwise prevent a directory deletion. It is useful for generated files such as .DS_Store.

The exclamation mark ! negates a rule and includes a file again. Complex negative rules can make Syncthing scan directories that would otherwise be ignored, so start with simple patterns.

File Versioning Is Not Local Undo

Syncthing supports file versioning, but its meaning is easy to misunderstand.

The official documentation emphasizes that versioning stores the old local version when a remote change replaces it. If B modifies a file and syncs it to A, A can keep the replaced version. But if A edits a file locally, Syncthing cannot preserve A’s previous version before the edit.

Common versioning strategies include:

  • Trash Can File Versioning: move replaced or deleted files into .stversions.
  • Simple File Versioning: keep a fixed number of versions.
  • Staggered File Versioning: keep dense recent versions and sparser older versions.
  • External File Versioning: hand version handling to a script.

For important documents, enable at least simple or trash-can versioning on the backup target. It is not a full backup system, but it reduces the damage from accidental deletion or overwrite.

How Conflicts Happen

Syncthing detects conflicts. If two devices change the same file differently at the same time, it may create a conflict file such as:

1

filename.sync-conflict-date-time-modifiedBy.ext

This is safer than silent overwrite, but you still need to clean up conflict files.

Common conflict sources:

  • Opening the same Markdown note on multiple devices at once.
  • Applications automatically writing the same state file.
  • Syncing device-specific files such as .obsidian/workspace.json.
  • Case-sensitive and case-insensitive filename differences across Windows, macOS, and Android.

For notes, sync the text, attachments, and templates first. Be careful with workspace state, caches, and plugin temporary files; put them in .stignore when needed.

Security Boundaries

One of Syncthing’s security goals is that unauthorized devices cannot join the sync cluster and passive observers cannot read file contents in transit.

The security documentation explains that traffic between devices is protected by TLS, and peers verify that the device certificate fingerprint is in the allowed list. In practice, devices only sync after both sides are configured with the correct device IDs.

That does not mean Syncthing usage is invisible:

  • Global discovery announces device IDs and listening addresses.
  • Local discovery broadcasts on the LAN.
  • Relay servers can see device IDs, though they cannot decrypt synced data.
  • An exposed Web GUI reveals that the machine is running Syncthing.

Practical security advice:

  • Do not expose the Web GUI to the public internet unless authentication and encryption are properly configured.
  • Only add devices you trust.
  • Use disk encryption or separate backups for important folders.
  • Disable global discovery, relays, or auto-upgrade if your environment requires it, while accepting the loss of convenience.

Untrusted Encrypted Devices

Syncthing also supports untrusted encrypted devices. This lets an untrusted device store encrypted data only.

A typical use case is a cloud server or external machine that participates in sync or backup but should not see plaintext. Trusted devices encrypt data with a folder password before sending it; other trusted devices with the same password can sync and decrypt it.

The official documentation still treats this feature as beta/testing. It is useful for specific needs, but not the simplest starting point.

Remember:

  • File data, names, timestamps, hashes, and directory structure are protected.
  • Folder ID, label, and approximate file sizes are not fully hidden.
  • The password and folder ID must be kept safely.
  • The folder type on the untrusted device should be Receive Encrypted.

For a normal home NAS, your own computers, and phones, trusted-device sync plus system login security, disk encryption, and backups is usually easier to maintain.

Practical Configuration Advice

If you plan to use Syncthing for notes or documents long term:

  1. Create separate folders by data type. Do not use one giant mixed folder.
  2. Use Send & Receive on primary computers.
  3. Consider Receive Only plus file versioning on a NAS or backup machine.
  4. On phones, sync only the directories you need.
  5. Use .stignore for caches, temporary files, and workspace state.
  6. Make sure 22000/TCP, 22000/UDP, and 21027/UDP work on the LAN.
  7. Keep the Web GUI local when possible; use SSH tunnels or VPN for remote access.
  8. Do not treat sync as the only backup for important data.

Where Syncthing Fits

Syncthing is a good fit if:

  • You want data to stay mainly on your own devices.
  • You can understand device pairing, folders, and conflict handling.
  • You have a NAS, home server, or multiple personal devices.
  • You want to sync Markdown, photo intake folders, scripts, or lightweight documents.

It is not ideal if:

  • You need collaborative online editing.
  • You need web previews and sharing links.
  • You need fine-grained team permissions.
  • You do not want to deal with network, firewall, or conflict issues.

It is best understood as a reliable device-to-device sync layer, not a full cloud-drive product. Used well, it can connect a NAS, computers, and phones into a controllable personal data network. Used casually, it can become a maintenance burden through conflicts, accidental deletion, ignore rules, and network quirks.

References

© 2022 - 2026 KnightLi Blog
记录并分享
Built with Hugo
Theme Stack designed by Jimmy