1SYNCTHING-EVENT-API(7)             Syncthing            SYNCTHING-EVENT-API(7)
2
3
4

NAME

6       syncthing-event-api - Event API
7

DESCRIPTION

9       Syncthing  provides a simple long polling interface for exposing events
10       from the core utility towards a GUI. To receive events, see events-get.
11

EVENT STRUCTURE

13       Each event is represented by an object similar to the following:
14
15          {
16              "id": 2,
17              "globalID": 3,
18              "type": "DeviceConnected",
19              "time": "2014-07-13T21:04:33.687836696+02:00",
20              "data": {
21                  "addr": "172.16.32.25:22000",
22                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
23              }
24          }
25
26       The top level keys  id,  globalID,  time,  type  and  data  are  always
27       present, though data may be null.
28
29       id     A  unique  ID  for  this  event  on  the  events  API. It always
30              increases by 1: the first event generated has id 1, the next has
31              id  2  etc.  If  this increases by more than 1, then one or more
32              events have been skipped by the events API.
33
34       globalID
35              A global ID for this event, across the  events  API,  the  audit
36              log,  and any other sources. It may increase by more than 1, but
37              it will always be greater than or equal to the id.
38
39       time   The time the event was generated.
40
41       type   Indicates the type of (i.e. reason for) the event and is one  of
42              the event types below.
43
44       data   An  object  containing  optional  extra  information;  the exact
45              structure is determined by the event type.
46

EVENT TYPES

48   ConfigSaved
49       Emitted after the config has been saved by the  user  or  by  Syncthing
50       itself.
51
52          {
53              "id": 50,
54              "globalID": 50,
55              "type": "ConfigSaved",
56              "time": "2014-12-13T00:09:13.5166486Z",
57              "data": {
58                  "Version": 7,
59                  "Options": {"..."},
60                  "GUI": {"..."},
61                  "Devices": [{"..."}],
62                  "Folders": [{"..."}]
63              }
64          }
65
66   DeviceConnected
67       Generated each time a connection to a device has been established.
68
69          {
70              "id": 2,
71              "globalID": 2,
72              "type": "DeviceConnected",
73              "time": "2014-07-13T21:04:33.687836696+02:00",
74              "data": {
75                  "addr": "172.16.32.25:22000",
76                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
77                  "deviceName": "Laptop",
78                  "clientName": "syncthing",
79                  "clientVersion": "v0.13.4",
80                  "type": "TCP (Client)"
81              }
82          }
83
84   DeviceDisconnected
85       Generated each time a connection to a device has been terminated.
86
87          {
88              "id": 48,
89              "globalID": 48,
90              "type": "DeviceDisconnected",
91              "time": "2014-07-13T21:18:52.859929215+02:00",
92              "data": {
93                  "error": "unexpected EOF",
94                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
95              }
96          }
97
98       NOTE:
99          The  error key contains the cause for disconnection, which might not
100          necessarily be an error as such. Specifically, “EOF” and “unexpected
101          EOF”  both  signify  TCP  connection  termination, either due to the
102          other device restarting or going offline or due to a network change.
103
104   DeviceDiscovered
105       Emitted when a new device is discovered using local discovery.
106
107          {
108              "id": 13,
109              "globalID": 13,
110              "type": "DeviceDiscovered",
111              "time": "2014-07-17T13:28:05.043465207+02:00",
112              "data": {
113                  "addrs": [
114                      "172.16.32.25:22000"
115                  ],
116                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
117              }
118          }
119
120   DevicePaused
121       Emitted when a device was paused.
122
123          {
124              "id": 13,
125              "globalID": 13,
126              "type": "DevicePaused",
127              "time": "2014-07-17T13:28:05.043465207+02:00",
128              "data": {
129                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
130              }
131          }
132
133   DeviceRejected
134       Emitted when there is a connection from a device we are not  configured
135       to talk to.
136
137          {
138              "id": 24,
139              "globalID": 24,
140              "type": "DeviceRejected",
141              "time": "2014-08-19T10:43:00.562821045+02:00",
142              "data": {
143                  "address": "127.0.0.1:51807",
144                  "name": "My dusty computer",
145                  "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK"
146              }
147          }
148
149   DeviceResumed
150       Generated each time a device was resumed.
151
152          {
153              "id": 2,
154              "globalID": 2,
155              "type": "DeviceResumed",
156              "time": "2014-07-13T21:04:33.687836696+02:00",
157              "data": {
158                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
159              }
160          }
161
162   DownloadProgress
163       Emitted during file downloads for each folder for each file. By default
164       only a single file in a folder is handled at the same time, but  custom
165       configuration can cause multiple files to be shown.
166
167          {
168              "id": 221,
169              "globalID": 221,
170              "type": "DownloadProgress",
171              "time": "2014-12-13T00:26:12.9876937Z",
172              "data": {
173                  "folder1": {
174                      "file1": {
175                          "total": 800,
176                          "pulling": 2,
177                          "copiedFromOrigin": 0,
178                          "reused": 633,
179                          "copiedFromElsewhere": 0,
180                          "pulled": 38,
181                          "bytesTotal": 104792064,
182                          "bytesDone": 87883776
183                      },
184                      "dir\\file2": {
185                          "total": 80,
186                          "pulling": 2,
187                          "copiedFromOrigin": 0,
188                          "reused": 0,
189                          "copiedFromElsewhere": 0,
190                          "pulled": 32,
191                          "bytesTotal": 10420224,
192                          "bytesDone": 4128768
193                      }
194                  },
195                  "folder2": {
196                      "file3": {
197                          "total": 800,
198                          "pulling": 2,
199                          "copiedFromOrigin": 0,
200                          "reused": 633,
201                          "copiedFromElsewhere": 0,
202                          "pulled": 38,
203                          "bytesTotal": 104792064,
204                          "bytesDone": 87883776
205                      },
206                      "dir\\file4": {
207                          "total": 80,
208                          "pulling": 2,
209                          "copiedFromOrigin": 0,
210                          "reused": 0,
211                          "copiedFromElsewhere": 0,
212                          "pulled": 32,
213                          "bytesTotal": 10420224,
214                          "bytesDone": 4128768
215                      }
216                  }
217              }
218          }
219
220       · total - total number of blocks in the file
221
222       · pulling - number of blocks currently being downloaded
223
224       · copiedFromOrigin - number of blocks copied from the file we are about
225         to replace
226
227       · reused - number of blocks reused from a previous temporary file
228
229       · copiedFromElsewhere - number of blocks copied  from  other  files  or
230         potentially other folders
231
232       · pulled - number of blocks actually downloaded so far
233
234       · bytesTotal - approximate total file size
235
236       · bytesDone  -  approximate  number  of  bytes already handled (already
237         reused, copied or pulled)
238
239       Where block size is 128KB.
240
241       Files/folders appearing in the event data imply that the  download  has
242       been  started for that file/folder, where disappearing implies that the
243       downloads have been finished or failed for that file/folder.  There  is
244       always  a  last event emitted with no data, which implies all downloads
245       have finished/failed.
246
247   FolderCompletion
248       The FolderCompletion event is emitted when the local or remote contents
249       for a folder changes. It contains the completion percentage for a given
250       remote device and  is  emitted  once  per  currently  connected  remote
251       device.
252
253          {
254              "id": 84,
255              "globalID": 84,
256              "type": "FolderCompletion",
257              "time": "2015-04-17T14:14:27.043576583+09:00",
258              "data": {
259                  "completion": 100,
260                  "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
261                  "folder": "default"
262              }
263          }
264
265   FolderErrors
266       The  FolderErrors event is emitted when a folder cannot be successfully
267       synchronized. The event contains the ID of the affected  folder  and  a
268       list of errors for files or directories therein. This list of errors is
269       obsolete once the folder changes state to syncing -  if  errors  remain
270       after  the  next  synchronization  attempt, a new FolderErrors event is
271       emitted.
272
273          {
274              "id": 132,
275              "type": "FolderErrors",
276              "time": "2015-06-26T13:39:24.697401384+02:00",
277              "data": {
278                  "errors": [
279                      {
280                          "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied",
281                          "path": "h2j/aslkjd"
282                      }
283                  ],
284                  "folder": "default"
285              }
286          }
287
288       New in version 0.11.12.
289
290
291       SEE ALSO:
292          The statechanged event.
293
294   FolderRejected
295       Emitted when a device sends index information for a folder  we  do  not
296       have, or have but do not share with the device in question.
297
298          {
299              "id": 27,
300              "globalID": 27,
301              "type": "FolderRejected",
302              "time": "2014-08-19T10:41:06.761751399+02:00",
303              "data": {
304                  "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
305                  "folder": "GXWxf-3zgnU",
306                  "folderLabel": "My Pictures"
307              }
308          }
309
310   Folder Scan Progress
311       Emitted  in  regular intervals (folder setting ProgressIntervalS, 2s by
312       default) during scans giving the amount of bytes already scanned and to
313       be  scanned  in  total , as well as the current scanning rates in bytes
314       per second.
315
316          {
317             "data" : {
318                "total" : 1,
319                "rate" : 0,
320                "current" : 0,
321                "folder" : "bd7q3-zskm5"
322             },
323             "globalID" : 29,
324             "type" : "FolderScanProgress",
325             "time" : "2017-03-06T15:00:58.072004209+01:00",
326             "id" : 29
327          }
328
329   FolderSummary
330       The FolderSummary event is emitted when folder  contents  have  changed
331       locally.  This  can  be  used to calculate the current local completion
332       state.
333
334          {
335              "id": 16,
336              "globalID": 16,
337              "type": "FolderSummary",
338              "time": "2015-04-17T14:12:20.460121585+09:00",
339              "data": {
340                  "folder": "default",
341                  "summary": {
342                      "globalBytes": 0,
343                      "globalDeleted": 0,
344                      "globalFiles": 0,
345                      "ignorePatterns": false,
346                      "inSyncBytes": 0,
347                      "inSyncFiles": 0,
348                      "invalid": "",
349                      "localBytes": 0,
350                      "localDeleted": 0,
351                      "localFiles": 0,
352                      "needBytes": 0,
353                      "needFiles": 0,
354                      "state": "idle",
355                      "stateChanged": "2015-04-17T14:12:12.455224687+09:00",
356                      "version": 0
357                  }
358              }
359          }
360
361   ItemFinished
362       Generated when Syncthing ends synchronizing a file to a newer  version.
363       A successful operation:
364
365          {
366              "id": 93,
367              "globalID": 93,
368              "type": "ItemFinished",
369              "time": "2014-07-13T21:22:03.414609034+02:00",
370              "data": {
371                  "item": "test.txt",
372                  "folder": "default",
373                  "error": null,
374                  "type": "file",
375                  "action": "update"
376              }
377          }
378
379       An unsuccessful operation:
380
381          {
382              "id": 44,
383              "globalID": 44,
384              "type": "ItemFinished",
385              "time": "2015-05-27T11:21:05.711133004+02:00",
386              "data": {
387                  "action": "update",
388                  "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
389                  "folder": "default",
390                  "item": "foo/hej",
391                  "type": "file"
392              }
393          }
394
395       The  action  field  is either update (contents changed), metadata (file
396       metadata changed but not contents), or delete.
397
398       New in version 0.11.10: The metadata action.
399
400
401   ItemStarted
402       Generated when Syncthing begins synchronizing a file to  a  newer  ver‐
403       sion.
404
405          {
406              "id": 93,
407              "globalID": 93,
408              "type": "ItemStarted",
409              "time": "2014-07-13T21:22:03.414609034+02:00",
410              "data": {
411                  "item": "test.txt",
412                  "folder": "default",
413                  "type": "file",
414                  "action": "update"
415              }
416          }
417
418       The  action  field  is either update (contents changed), metadata (file
419       metadata changed but not contents), or delete.
420
421       New in version 0.11.10: The metadata action.
422
423
424   Listen Addresses Changed
425       This event is emitted when a listen address changes.
426
427          {
428             "type" : "ListenAddressesChanged",
429             "id" : 70,
430             "time" : "2017-03-06T15:01:24.88340663+01:00",
431             "globalID" : 70,
432             "data" : {
433                "address" : {
434                   "Fragment" : "",
435                   "RawQuery" : "",
436                   "Scheme" : "dynamic+https",
437                   "Path" : "/endpoint",
438                   "RawPath" : "",
439                   "User" : null,
440                   "ForceQuery" : false,
441                   "Host" : "relays.syncthing.net",
442                   "Opaque" : ""
443                },
444                "wan" : [
445                   {
446                      "ForceQuery" : false,
447                      "User" : null,
448                      "Host" : "31.15.66.212:443",
449                      "Opaque" : "",
450                      "Path" : "/",
451                      "RawPath" : "",
452                      "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
453                      "Scheme" : "relay",
454                      "Fragment" : ""
455                   }
456                ],
457                "lan" : [
458                   {
459                      "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
460                      "Scheme" : "relay",
461                      "Fragment" : "",
462                      "RawPath" : "",
463                      "Path" : "/",
464                      "Host" : "31.15.66.212:443",
465                      "Opaque" : "",
466                      "ForceQuery" : false,
467                      "User" : null
468                   }
469                ]
470             }
471          }
472
473   LocalChangeDetected
474       Generated upon scan whenever the local disk has discovered  an  updated
475       file  from  the  previous  scan.  This does not include events that are
476       discovered and copied from other devices (remote-change-detected), only
477       files that were changed on the local filesystem.
478
479          {
480            "id": 7,
481            "globalID": 59,
482            "time": "2016-09-26T22:07:10.7189141-04:00",
483            "type": "LocalChangeDetected",
484            "data": {
485              "action": "deleted",
486              "folderID": "vitwy-zjxqt",
487              "label": "TestSync",
488              "path": "C:\\Users\\Nate\\Sync\\testfolder\\test file.rtf",
489              "type": "file"
490            }
491          }
492
493   LocalIndexUpdated
494       Generated when the local index information has changed, due to synchro‐
495       nizing one or more items from the cluster or discovering local  changes
496       during a scan.
497
498          {
499              "id": 59,
500              "globalID": 59,
501              "type": "LocalIndexUpdated",
502              "time": "2014-07-17T13:27:28.051369434+02:00",
503              "data": {
504                  "folder": "default",
505                  "items": 1000,
506              }
507          }
508
509   Login Attempt
510       When  authentication  is  enabled for the GUI, this event is emitted on
511       every login attempt. If either the username or password are  incorrect,
512       success is false and in any case the given username is returned.
513
514          {
515             "id" : 187,
516             "time" : "2017-03-07T00:19:24.420386143+01:00",
517             "data" : {
518                "username" : "somename",
519                "success" : false
520             },
521             "type" : "LoginAttempt",
522             "globalID" : 195
523          }
524
525   RemoteChangeDetected
526       Generated  upon scan whenever a file is locally updated due to a remote
527       change.  Files that are updated locally produce a local-change-detected
528       event.
529
530          {
531             "time" : "2017-03-06T23:58:21.844739891+01:00",
532             "globalID" : 123,
533             "data" : {
534                "type" : "file",
535                "action" : "deleted",
536                "path" : "/media/ntfs_data/Dokumente/testfile",
537                "label" : "Dokumente",
538                "folderID" : "Dokumente",
539                "modifiedBy" : "BPDFDTU"
540             },
541             "type" : "RemoteChangeDetected",
542             "id" : 2
543          }
544
545   Remote Download Progress
546       This  event is emitted when a download-progress message is received. It
547       returns a map data of filenames with a count of downloaded blocks.  The
548       files  in questions are currently being downloaded on the remote device
549       and belong to folder.
550
551          {
552             "time" : "2017-03-07T00:11:37.65838955+01:00",
553             "globalID" : 170,
554             "data" : {
555                "state" : {
556                   "tahr64-6.0.5.iso" : 1784
557                },
558                "device" : "F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A",
559                "folder" : "Dokumente"
560             },
561             "type" : "RemoteDownloadProgress",
562             "id" : 163
563          }
564
565   RemoteIndexUpdated
566       Generated each time new index information is received from a device.
567
568          {
569              "id": 44,
570              "globalID": 44,
571              "type": "RemoteIndexUpdated",
572              "time": "2014-07-13T21:04:35.394184435+02:00",
573              "data": {
574                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
575                  "folder": "lightroom",
576                  "items": 1000
577              }
578          }
579
580   Starting
581       Emitted exactly once, when Syncthing starts, before parsing  configura‐
582       tion etc.
583
584          {
585              "id": 1,
586              "globalID": 1,
587              "type": "Starting",
588              "time": "2014-07-17T13:13:32.044470055+02:00",
589              "data": {
590                  "home": "/home/jb/.config/syncthing"
591              }
592          }
593
594   StartupComplete
595       Emitted  exactly once, when initialization is complete and Syncthing is
596       ready to start exchanging data with other devices.
597
598          {
599              "id": 1,
600              "globalID": 1,
601              "type": "StartupComplete",
602              "time": "2014-07-13T21:03:18.383239179+02:00",
603              "data": null
604          }
605
606   StateChanged
607       Emitted when a folder changes state. Possible states  are  idle,  scan‐
608       ning,  syncing  and  error. The field duration is the number of seconds
609       the folder spent in state  from.  In  the  example  below,  the  folder
610       default  was  in  state  scanning for 0.198 seconds and is now in state
611       idle.
612
613          {
614              "id": 8,
615              "globalID": 8,
616              "type": "StateChanged",
617              "time": "2014-07-17T13:14:28.697493016+02:00",
618              "data": {
619                  "folder": "default",
620                  "from": "scanning",
621                  "duration": 0.19782869900000002,
622                  "to": "idle"
623              }
624          }
625

AUTHOR

627       The Syncthing Authors
628
630       2014-2019, The Syncthing Authors
631
632
633
634
635v1                               Mar 17, 2020           SYNCTHING-EVENT-API(7)
Impressum