Skip to main content

Architecture & Discovery

Because Syncthing lacks a central server, nodes must find each other dynamically. Understanding this network layer is crucial for optimizing sync speed and maintaining privacy.

Core Idea

Syncthing nodes locate one another using Discovery, and communicate via direct P2P connections whenever possible, falling back to Relays if firewalls block them.

The Three Connection Pillars​

To sync data between Node A and Node B, Syncthing goes through three phases:

  1. Identification: Who am I trying to reach? (Device ID)
  2. Discovery: What is their current IP address and port?
  3. Connection: How do I route the data to them?

1. Device IDs​

A Device ID is a 56-character string representing the public key of the device's TLS certificate.

  • E.g., K3X2R...-.....-.....-.....-.....-.....-.....
  • Nodes must explicitly add each other's Device IDs (mutual trust).
  • If an unapproved node connects, connection is rejected immediately.

2. Discovery Methods​

How does Node A know Node B is currently at 198.51.100.12:22000?

Local Discovery​

Nodes broadcast UDP packets on the local network (IPv4 UDP port 21027 and IPv6 multicast).

  • Pros: Fast, completely private, works without the internet.
  • Cons: Only works on the same LAN segment.

Global Discovery​

Nodes announce their current public IP addresses to Syncthing's global discovery servers (hosted by the community/foundation).

  • Pros: Allows devices to find each other across the internet (e.g., syncing home NAS with a laptop at a coffee shop).
  • Cons: Leaks your IP address (but not your data) to the discovery server.

Privacy Note: You can run your own global discovery server (stdiscosrv) if you require total isolation.

3. Connection and Relays​

Once Node A knows Node B's IP, it attempts a direct TCP/QUIC connection (default port 22000).

Direct Connection (Optimal)​

If at least one device has port 22000 open to the network (e.g., UPnP/NAT-PMP is enabled, or manual port forwarding is configured), they connect directly. You get maximum speed restricted only by your ISPs.

Relayed Connection (Fallback)​

If both devices are behind strict firewalls/NATs and cannot open ports, they connect to a public Relay Server.

  • Traffic flows: Node A -> Relay -> Node B.
  • Security: Data is fully end-to-end encrypted. The Relay cannot see the contents of your files, only encrypted gibberish.
  • Performance: Relays are rate-limited (often 1-5 MB/s). You should strive to avoid relay connections by properly configuring firewalls.

Network Architecture Examples​

Suboptimal: Double-NAT (Relay)​

flowchart LR
  LAP[Laptop\nBehind coffee shop NAT\nTCP 22000 Blocked] -->|Encrypted via Relay| RELAY((Public Relay Server))
  NAS[Home NAS\nBehind Home Router\nNo Port Forward] -->|Encrypted via Relay| RELAY

Result: Slow sync speeds.

Optimal: Direct Connection​

flowchart LR
  LAP[Laptop\nBehind coffee shop NAT] -->|Direct TLS\nHigh Speed| ROUTER[Home Router\nPort 22000 Forwarded]
  ROUTER --> NAS[Home NAS]

Result: Maximum sync speed.

Practical Settings​

In the Syncthing GUI under Settings → Connections, you control these mechanisms:

  • Enable NAT traversal: Tries to use UPnP to open firewall ports automatically.
  • Global Discovery: Turn off if you only ever sync over a private VPN like WireGuard or Tailscale.
  • Local Discovery: Keep on unless operating in a highly restricted datacenter environment.
  • Enable Relaying: Turn off if you want to strictly enforce direct connections to guarantee high bandwidth.

Next Steps​

Now that you understand the theory, it's time to build the system.