Skip to main content

Global vs Local Discovery

Before two Syncthing devices can sync, they must find each other. Discovery is the mechanism that maps a Device ID to a reachable address. Syncthing supports two modes: local (LAN) and global (internet).

Learning Focus

Know exactly which discovery servers your devices contact and how to disable global discovery for air-gapped or maximum-privacy deployments.

Tool Snapshot
Discovery ModeProtocolRangePortPrivacy
LocalIPv4/IPv6 multicastLAN onlyUDP 21027High — stays on LAN
GlobalHTTPS to discovery.syncthing.netInternetTCP 443Moderate — IP revealed to Syncthing's servers
Static addressNone (direct)AnyAnyHighest — no discovery server used
Custom discovery serverHTTPSAnyConfigurableFull control

How Local Discovery Works​

sequenceDiagram
  participant DevA as Device A (LAN)
  participant Multicast as 239.21.0.1:21027 (UDP multicast)
  participant DevB as Device B (LAN)

  DevA->>Multicast: "I am K3X2R... reachable at 192.168.1.10:22000"
  Multicast->>DevB: Broadcast announcement
  DevB-->>DevA: Direct TCP/TLS connection on port 22000

Local discovery requires no internet access and no configuration. Devices on the same LAN find each other automatically within seconds.

verify-local-discovery.sh
# Confirm UDP 21027 is listening
ss -ulnp | grep 21027

# Watch local discovery announcements in logs
journalctl --user -u syncthing -f | grep -i "local discovery"

How Global Discovery Works​

When peers are on different networks, Syncthing announces its current IP and port to Syncthing's hosted discovery servers:

  1. Device A starts, contacts https://discovery.syncthing.net
  2. Registers its Device ID → IP:port mapping
  3. Device B queries the discovery server for Device A's Device ID
  4. Both devices receive each other's addresses and establish a direct connection
note

The discovery server sees your IP address and Device ID, but not your files or file names. All data transfer is P2P and encrypted.

Configuring Discovery in config.xml​

config.xml — discovery options
<options>
  <!-- Local discovery (LAN multicast) -->
  <localAnnounceEnabled>true</localAnnounceEnabled>
  <localAnnouncePort>21027</localAnnouncePort>
  <localAnnounceMCAddr>[ff12::8384]:21027</localAnnounceMCAddr>

  <!-- Global discovery -->
  <globalAnnounceEnabled>true</globalAnnounceEnabled>
  <globalAnnounceServers>default</globalAnnounceServers>
</options>

The value default expands to https://discovery.syncthing.net/v2/?id=... (Syncthing's hosted servers).

Disabling Global Discovery (Air-Gapped / Privacy Mode)​

config.xml — disable global discovery
<options>
  <globalAnnounceEnabled>false</globalAnnounceEnabled>
  <localAnnounceEnabled>true</localAnnounceEnabled>
</options>

With global discovery off, you must configure static addresses for remote peers:

config.xml — static peer address
<device id="K3X2R..." name="remote-vps">
  <address>tcp://203.0.113.45:22000</address>
</device>

Running a Self-Hosted Discovery Server​

For organizations that want control over discovery:

run-discovery-server.sh
# Build or download stdiscosrv
go install github.com/syncthing/syncthing/cmd/stdiscosrv@latest

# Run (generates its own TLS cert)
stdiscosrv -listen :8443

# Get the server's Device ID
stdiscosrv --device-id

In each client's config.xml:

<globalAnnounceServers>https://your-discovery.example.com:8443/?id=SERVER_DEVICE_ID</globalAnnounceServers>

Discovery Troubleshooting Matrix​

SymptomCauseFix
Peer shows as Disconnected on LANUDP 21027 blockedAllow ufw allow 21027/udp on both hosts
Peer never connects over internetGlobal discovery disabled or unreachableEnable global discovery or configure static address
Constant reconnection attemptsWrong static IP configuredUpdate <address> entry with correct IP/port
"Discovery error" in logsDNS or HTTPS blocked to discovery serversWhitelist discovery.syncthing.net or use custom server

What's Next​