SYNCTHING-GLOBALDISCO(7)

💅 syncthing-globaldisco — Global Discovery Protocol v3 ✨

okay bestie, welcome to SYNCTHING-GLOBALDISCO(7) from the Syncthing manual set 🎀 this one's all about how devices find each other out there in the big wide world — it's the Global Discovery Protocol v3, and it's honestly lowkey iconic. let's get into it 🫶

---

🌸 ANNOUNCEMENTS 🌸

so a device should announce itself at startup — like a little "hi, i'm here!!" to the universe 💖 it does this with an HTTPS POST to the announce server URL. Standard discovery currently requires the path to be /v2/, but ngl that's up to the discovery server to decide.

the POST carries a JSON payload listing connection addresses (if any):

{
        addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
}

and it's totally OK for the addresses field to be the empty list ([]), null, or missing entirely. 🙈 but like… an announcement with the field missing or empty is however not useful…

any empty or unspecified IP addresses (i.e. addresses like tcp://:22000, tcp://0.0.0.0:22000, tcp://[::]:22000) get interpreted as referring to the source IP address of the announcement. so the server just fills in the blank, main character energy 💅

the device ID of the announcing device is not part of the announcement. instead, the server requires that the client perform certificate authentication, and the device ID is deduced from the presented certificate 🔐

server response is empty, with code 204 (No Content) on success. if no certificate was presented, status 403 (Forbidden) is returned. if the posted data doesn't conform to the expected format, 400 (Bad Request) is returned.

in successful responses, the server may return a Reannounce-After header containing the number of seconds after which the client should perform a new announcement ⏳

in error responses, the server may return a Retry-After header containing the number of seconds after which the client should retry.

👑 real talk: performing announcements significantly more often than indicated by the Reannounce-After or Retry-After headers may result in the client being throttled. in such cases the server may respond with status code 429 (Too Many Requests). so like… chill, bestie 💀

---

🦋 QUERIES 🦋

queries are performed as HTTPS GET requests to the announce server URL. the requested device ID is passed as the query parameter device, in canonical string form, i.e.

https://discovery.syncthing.net/?device=ABC12345-....

successful responses will have status code 200 (OK) and carry a JSON payload of the same format as the announcement above. the response will not contain empty or unspecified addresses ✨

if the device query parameter is missing or malformed, the status code 400 (Bad Request) is returned.

if the device ID is of a valid format but not found in the registry, 404 (Not Found) is returned 😭

if the client has exceeded a rate limit, the server may respond with 429 (Too Many Requests).

---

🔐 AUTHENTICATION 🔐

global discovery is spoken over HTTPS and is protected against attackers in the same manner as other HTTPS traffic. however, there are a few Syncthing specific considerations on top of this 🧚 as mentioned above, for announcements the client must provide a certificate to prove ownership of the announced device ID.

in addition, Syncthing has a mechanism to verify the identity of the discovery server. while this would normally be accomplished by using a CA signed certificate, Syncthing often runs in environments with outdated or simply nonexistent root CA bundles (we've all been there 🙈). instead, Syncthing can verify the discovery server certificate fingerprint using the device ID mechanism.

this is certificate pinning and conveyed in the Syncthing configuration as a synthetic id parameter on the discovery server URL:

https://discovery.syncthing.net/?id=....

the id parameter is not, in fact, sent to the discovery server — it's used by Syncthing itself to know which certificate to expect on the server side 👀

the public discovery network uses this authentication mechanism instead of CA signed certificates.

the discovery server prints its certificate ID in this manner on startup. slay 🎀

---

⭐ AUTHOR ⭐

The Syncthing Authors 🌈

---

🍓 COPYRIGHT 🍓

2014-2026, The Syncthing Authors

---

and that's the whole vibe check, bestie 💜 this was syncthing-globaldisco(7) from Syncthing v2.1.0, dated Oct 07, 2026 — go forth and get discovered, no cap ✨👑