github.com/kayoticsully/syncthing@v0.8.9-0.20140724133906-c45a2fdc03f8/discover/PROTOCOL.md (about) 1 Node Discovery Protocol v2 2 ========================== 3 4 Mode of Operation 5 ----------------- 6 7 There are two distinct modes: "local discovery", performed on a LAN 8 segment (broadcast domain) and "global discovery" performed over the 9 Internet in general with the support of a well known server. 10 11 Local discovery does not use Query packets. Instead Announcement packets 12 are sent periodically and each participating node keeps a table of the 13 announcements it has seen. On multihomed hosts the announcement packets 14 should be sent on each interface that syncthing will accept connections. 15 16 It is recommended that local discovery Announcement packets are sent on 17 a 30 to 60 second interval, possibly with forced transmissions when a 18 previously unknown node is discovered. 19 20 Global discovery is made possible by periodically updating a global server 21 using Announcement packets indentical to those transmitted for local 22 discovery. The node performing discovery will transmit a Query packet to 23 the global server and expect an Announcement packet in response. In case 24 the global server has no knowledge of the queried node ID, there will be 25 no response. A timeout is to be used to determine lookup failure. 26 27 There is no message to unregister from the global server; instead 28 registrations are forgotten after 60 minutes. It is recommended to 29 send Announcement packets to the global server on a 30 minute interval. 30 31 Packet Formats 32 -------------- 33 34 The Announcement packet has the following structure: 35 36 0 1 2 3 37 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 38 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 39 | Magic (0x029E4C77) | 40 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 41 / / 42 \ Node Structure \ 43 / / 44 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 45 | Number of Extra Nodes | 46 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 47 / / 48 \ Zero or more Node Structures \ 49 / / 50 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 51 52 Node Structure: 53 54 0 1 2 3 55 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 56 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 57 | Length of ID | 58 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 59 / / 60 \ ID (variable length) \ 61 / / 62 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 63 | Number of Addresses | 64 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 65 / / 66 \ Zero or more Address Structures \ 67 / / 68 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 69 70 Address Structure: 71 72 0 1 2 3 73 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 74 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 75 | Length of IP | 76 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 77 / / 78 \ IP (variable length) \ 79 / / 80 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 81 | Port | 0x0000 | 82 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 83 84 This is the XDR encoding of: 85 86 struct Announcement { 87 unsigned int Magic; 88 Node This; 89 Node Extra<>; 90 } 91 92 struct Node { 93 string ID<>; 94 Address Addresses<>; 95 } 96 97 struct Address { 98 opaque IP<>; 99 unsigned short Port; 100 } 101 102 The first Node structure contains information about the sending node. 103 The following zero or more Extra nodes contain information about other 104 nodes known to the sending node. 105 106 In the Address structure, the IP field can be of three differnt kinds; 107 108 - A zero length indicates that the IP address should be taken from the 109 source address of the announcement packet, be it IPv4 or IPv6. The 110 source address must be a valid unicast address. This is only valid 111 in the first node structure, not in the list of extras. 112 113 - A four byte length indicates that the address is an IPv4 unicast 114 address. 115 116 - A sixteen byte length indicates that the address is an IPv6 unicast 117 address. 118 119 The Query packet has the following structure: 120 121 0 1 2 3 122 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 123 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 124 | Magic Number (0x23D63A9A) | 125 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 126 | Length of Node ID | 127 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 128 / / 129 \ Node ID (variable length) \ 130 / / 131 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 132 133 This is the XDR encoding of: 134 135 struct Announcement { 136 unsigned int MagicNumber; 137 string NodeID<>; 138 } 139