├── _templates ├── version.html └── layout.html ├── issues.png ├── dev ├── lgtm.png ├── index.rst ├── http-services.rst ├── web.rst ├── events.rst ├── infrastructure.rst ├── release-signing.rst ├── rest.rst ├── debugging.rst ├── crashrep.rst └── issues.rst ├── intro ├── gs1.png ├── gs2.png ├── gs3.png ├── gs5.png ├── gui1.png ├── index.rst └── project-presentation.rst ├── users ├── relay.png ├── override.png ├── advanced-ldap.png ├── disco-settings.png ├── foldersendonly.png ├── gui-debugging.png ├── advanced-gui-ldap.png ├── advanced-settings.png ├── windows-nssm-config.png ├── advanced-ldap-groups.png ├── untrusted-folder-share.png ├── windows-taskschd-actions.png ├── windows-taskschd-general.png ├── windows-startup-addressbar.png ├── windows-startup-newshortcut.png ├── windows-taskschd-createtask.png ├── windows-taskschd-settingstab.png ├── windows-startup-createshortcut.png ├── windows-taskschd-triggers-logon.png ├── foldermaster.rst ├── windows-taskschd-triggers-startup.png ├── windows-taskschd-additional-actions.png ├── windows-taskschd-additional-conditions.png ├── faq.rst ├── metrics.rst ├── index.rst ├── advanced.rst ├── relaying.rst ├── introducer.rst ├── proxying.rst ├── profiling.rst ├── foldertypes.rst ├── custom-upgrades.rst ├── guilisten.rst ├── reverseproxy.rst ├── crashrep.rst ├── ldap.rst └── tunneling.rst ├── _static ├── favicon.png ├── custom.css └── logo-horizontal.svg ├── .gitignore ├── refresh-versions.sh ├── rest ├── system-ping-post.rst ├── system-restart-post.rst ├── system-error-clear-post.rst ├── system-shutdown-post.rst ├── noauth-health-get.rst ├── system-ping-get.rst ├── system-error-post.rst ├── system-upgrade-post.rst ├── svc-lang-get.rst ├── svc-random-string-get.rst ├── db-prio-post.rst ├── system-pause-post.rst ├── system-discovery-get.rst ├── system-resume-post.rst ├── folder-pullerrors-get.rst ├── db-ignores-post.rst ├── system-upgrade-get.rst ├── system-error-get.rst ├── system-version-get.rst ├── db-revert-post.rst ├── system-config-insync-get.rst ├── system-loglevels-post.rst ├── db-override-post.rst ├── stats-folder-get.rst ├── cluster-pending-devices-get.rst ├── stats-device-get.rst ├── system-reset-post.rst ├── system-log-get.rst ├── system-discovery-post.rst ├── folder-errors-get.rst ├── system-loglevels-get.rst ├── svc-deviceid-get.rst ├── system-config-post.rst ├── folder-versions-post.rst ├── db-ignores-get.rst ├── db-scan-post.rst ├── cluster-pending-devices-delete.rst ├── db-remoteneed-get.rst ├── db-localchanged-get.rst ├── cluster-pending-folders-delete.rst ├── system-paths-get.rst ├── debug.rst ├── system-browse-get.rst ├── folder-versions-get.rst ├── cluster-pending-folders-get.rst ├── svc-report-get.rst ├── system-connections-get.rst ├── events-get.rst ├── db-need-get.rst ├── db-completion-get.rst ├── db-status-get.rst ├── db-browse-get.rst ├── db-file-get.rst └── config.rst ├── .github ├── dependabot.yml └── workflows │ ├── refresh-authors.yml │ └── refresh-versions.yml ├── refresh-metrics.sh ├── docker-build.sh ├── refresh-authors.sh ├── events ├── starting.rst ├── startupcomplete.rst ├── devicepaused.rst ├── deviceresumed.rst ├── folderpaused.rst ├── folderresumed.rst ├── remoteindexupdated.rst ├── devicediscovered.rst ├── failure.rst ├── clusterconfigreceived.rst ├── configsaved.rst ├── deviceconnected.rst ├── folderscanprogress.rst ├── itemstarted.rst ├── devicerejected.rst ├── statechanged.rst ├── pendingdeviceschanged.rst ├── folderrejected.rst ├── remotedownloadprogress.rst ├── folderwatchstatechanged.rst ├── devicedisconnected.rst ├── localindexupdated.rst ├── remotechangedetected.rst ├── localchangedetected.rst ├── foldererrors.rst ├── pendingfolderschanged.rst ├── foldercompletion.rst ├── itemfinished.rst ├── loginattempt.rst ├── listenaddresseschanged.rst ├── foldersummary.rst └── downloadprogress.rst ├── _script ├── go.mod ├── lsver.go ├── go.sum └── histver │ └── table.go ├── advanced ├── folder-send-xattrs.rst ├── folder-send-ownership.rst ├── folder-disable-fsync.rst ├── option-max-concurrency.rst ├── folder-caseSensitiveFS.rst ├── device-allowednetworks.rst ├── folder-sync-xattrs.rst ├── folder-autonormalize.rst ├── folder-filesystem-type.rst ├── folder-ignoredelete.rst ├── option-connection-limits.rst ├── folder-uselargeblocks.rst ├── folder-xattr-filter.rst ├── folder-copyrangemethod.rst ├── device-numconnections.rst └── folder-sync-ownership.rst ├── specs ├── index.rst ├── localdisco-v4.rst └── globaldisco-v3.rst ├── _ext └── edit_on_github.py ├── includes ├── cli-commands.rst └── env-vars.rst ├── README.rst ├── index.rst ├── thanks.txt └── draft └── localver.rst /_templates/version.html: -------------------------------------------------------------------------------- 1 |

Written for {{ version }}

2 |
3 | -------------------------------------------------------------------------------- /issues.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/issues.png -------------------------------------------------------------------------------- /dev/lgtm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/dev/lgtm.png -------------------------------------------------------------------------------- /intro/gs1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/intro/gs1.png -------------------------------------------------------------------------------- /intro/gs2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/intro/gs2.png -------------------------------------------------------------------------------- /intro/gs3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/intro/gs3.png -------------------------------------------------------------------------------- /intro/gs5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/intro/gs5.png -------------------------------------------------------------------------------- /intro/gui1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/intro/gui1.png -------------------------------------------------------------------------------- /users/relay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/relay.png -------------------------------------------------------------------------------- /_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/_static/favicon.png -------------------------------------------------------------------------------- /users/override.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/override.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | _build/ 2 | _deployed 3 | _deployed.old 4 | _syncthing 5 | /RELEASE 6 | /TAG 7 | -------------------------------------------------------------------------------- /users/advanced-ldap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/advanced-ldap.png -------------------------------------------------------------------------------- /users/disco-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/disco-settings.png -------------------------------------------------------------------------------- /users/foldersendonly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/foldersendonly.png -------------------------------------------------------------------------------- /users/gui-debugging.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/gui-debugging.png -------------------------------------------------------------------------------- /refresh-versions.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | pushd _script 4 | go run ./histver -file ../users/releases.csv 5 | -------------------------------------------------------------------------------- /users/advanced-gui-ldap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/advanced-gui-ldap.png -------------------------------------------------------------------------------- /users/advanced-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/advanced-settings.png -------------------------------------------------------------------------------- /users/windows-nssm-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-nssm-config.png -------------------------------------------------------------------------------- /users/advanced-ldap-groups.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/advanced-ldap-groups.png -------------------------------------------------------------------------------- /users/untrusted-folder-share.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/untrusted-folder-share.png -------------------------------------------------------------------------------- /users/windows-taskschd-actions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-actions.png -------------------------------------------------------------------------------- /users/windows-taskschd-general.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-general.png -------------------------------------------------------------------------------- /users/windows-startup-addressbar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-startup-addressbar.png -------------------------------------------------------------------------------- /rest/system-ping-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/ping 2 | ====================== 3 | 4 | Returns a ``{"ping": "pong"}`` object. 5 | -------------------------------------------------------------------------------- /users/windows-startup-newshortcut.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-startup-newshortcut.png -------------------------------------------------------------------------------- /users/windows-taskschd-createtask.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-createtask.png -------------------------------------------------------------------------------- /users/windows-taskschd-settingstab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-settingstab.png -------------------------------------------------------------------------------- /users/windows-startup-createshortcut.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-startup-createshortcut.png -------------------------------------------------------------------------------- /users/windows-taskschd-triggers-logon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-triggers-logon.png -------------------------------------------------------------------------------- /users/foldermaster.rst: -------------------------------------------------------------------------------- 1 | :orphan: 2 | 3 | Page Moved 4 | ========== 5 | 6 | This page has moved. Please see :ref:`folder-sendonly`. 7 | -------------------------------------------------------------------------------- /users/windows-taskschd-triggers-startup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-triggers-startup.png -------------------------------------------------------------------------------- /users/windows-taskschd-additional-actions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-additional-actions.png -------------------------------------------------------------------------------- /users/windows-taskschd-additional-conditions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/HEAD/users/windows-taskschd-additional-conditions.png -------------------------------------------------------------------------------- /rest/system-restart-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/restart 2 | ========================= 3 | 4 | Post with empty body to immediately restart Syncthing. 5 | -------------------------------------------------------------------------------- /rest/system-error-clear-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/error/clear 2 | ============================== 3 | 4 | Post with empty to body to remove all recent errors. 5 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "monthly" 7 | -------------------------------------------------------------------------------- /intro/index.rst: -------------------------------------------------------------------------------- 1 | Introduction 2 | ============ 3 | 4 | .. toctree:: 5 | :maxdepth: 1 6 | 7 | getting-started 8 | gui 9 | project-presentation 10 | -------------------------------------------------------------------------------- /rest/system-shutdown-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/shutdown 2 | ========================== 3 | 4 | Post with empty body to cause Syncthing to exit and not restart. 5 | -------------------------------------------------------------------------------- /rest/noauth-health-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/noauth/health 2 | ======================= 3 | 4 | Returns a ``{"status": "OK"}`` object. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "status": "OK" 10 | } -------------------------------------------------------------------------------- /rest/system-ping-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/ping 2 | ===================== 3 | 4 | Returns a ``{"ping": "pong"}`` object. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "ping": "pong" 10 | } 11 | -------------------------------------------------------------------------------- /rest/system-error-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/error 2 | ======================= 3 | 4 | Post with an error message in the body (plain text) to register a new 5 | error. The new error will be displayed on any active GUI clients. 6 | -------------------------------------------------------------------------------- /rest/system-upgrade-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/upgrade 2 | ========================= 3 | 4 | Perform an upgrade to the newest released version and restart. Does 5 | nothing if there is no newer version than currently running. 6 | -------------------------------------------------------------------------------- /refresh-metrics.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | set -euo pipefail 3 | 4 | rm -rf _syncthing 5 | git clone --depth 1 https://github.com/syncthing/syncthing.git _syncthing 6 | pushd _script 7 | go run ./find-metrics ../_syncthing > ../includes/metrics-list.rst 8 | popd 9 | -------------------------------------------------------------------------------- /rest/svc-lang-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/svc/lang 2 | ================== 3 | 4 | Returns a list of canonicalized localization codes, as picked up from 5 | the ``Accept-Language`` header sent by the browser. 6 | 7 | .. code-block:: json 8 | 9 | ["sv_sv","sv","en_us","en"] 10 | -------------------------------------------------------------------------------- /users/faq.rst: -------------------------------------------------------------------------------- 1 | .. role:: strike 2 | 3 | .. _faq: 4 | 5 | FAQ 6 | ~~~ 7 | 8 | .. contents:: 9 | :local: 10 | :backlinks: none 11 | :depth: 2 12 | 13 | .. include:: faq-parts/general.rst 14 | .. include:: faq-parts/troubleshooting.rst 15 | .. include:: faq-parts/usage.rst 16 | -------------------------------------------------------------------------------- /rest/svc-random-string-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/svc/random/string 2 | =========================== 3 | 4 | Returns a strong random generated string (alphanumeric) of the specified length. Takes the ``length`` parameter. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "random": "FdPaEaZQ56sXEKYNxpgF" 10 | } 11 | -------------------------------------------------------------------------------- /rest/db-prio-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/db/prio 2 | ================== 3 | 4 | Moves the file to the top of the download queue. 5 | 6 | .. code-block:: bash 7 | 8 | curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar 9 | 10 | Response contains the same output as :doc:`db-need-get`. 11 | -------------------------------------------------------------------------------- /rest/system-pause-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/pause 2 | ======================= 3 | 4 | Pause the given device or all devices. 5 | 6 | Takes the optional parameter ``device`` (device ID). When omitted, 7 | pauses all devices. Returns status 200 and no content upon success, or status 8 | 500 and a plain text error on failure. 9 | -------------------------------------------------------------------------------- /rest/system-discovery-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/discovery 2 | ========================== 3 | 4 | Returns the contents of the local discovery cache. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [ 10 | "192.162.129.11:22000" 11 | ] 12 | } 13 | -------------------------------------------------------------------------------- /rest/system-resume-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/resume 2 | ======================== 3 | 4 | Resume the given device or all devices. 5 | 6 | Takes the optional parameter ``device`` (device ID). When omitted, 7 | resumes all devices. Returns status 200 and no content upon success, or status 8 | 500 and a plain text error on failure. 9 | -------------------------------------------------------------------------------- /docker-build.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -euo pipefail 3 | 4 | git describe --tags --long --always > RELEASE || true 5 | git describe --tags --exact-match > TAG || true 6 | 7 | target="${1:-html}" 8 | docker run --rm \ 9 | -v "$(pwd):$(pwd)" \ 10 | -w "$(pwd)" \ 11 | docker.io/sphinxdoc/sphinx-latexpdf:latest \ 12 | make "$target" 13 | -------------------------------------------------------------------------------- /rest/folder-pullerrors-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/folder/pullerrors (DEPRECATED) 2 | ======================================== 3 | 4 | .. deprecated:: v0.14.53 5 | This endpoint still works as before but is deprecated. Use 6 | :doc:`folder-errors-get` instead, which returns the same information. 7 | 8 | See :commit:`d510e3cca3d5caae42121fa206b3decc981ae59e` 9 | -------------------------------------------------------------------------------- /dev/index.rst: -------------------------------------------------------------------------------- 1 | Development 2 | =========== 3 | 4 | 5 | .. toctree:: 6 | :maxdepth: 1 7 | 8 | Introduction 9 | web 10 | building 11 | contributing 12 | debugging 13 | crashrep 14 | device-ids 15 | infrastructure 16 | issues 17 | release-creation 18 | release-signing 19 | rest 20 | events 21 | http-services 22 | -------------------------------------------------------------------------------- /rest/db-ignores-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/db/ignores 2 | ===================== 3 | 4 | Expects a format similar to the output of :doc:`db-ignores-get` call, but only 5 | containing the ``ignore`` field (``expanded`` field should be omitted). 6 | It takes one parameter, ``folder``, and either updates the content of 7 | the ``.stignore`` echoing it back as a response, or returns an error. 8 | -------------------------------------------------------------------------------- /rest/system-upgrade-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/upgrade 2 | ======================== 3 | 4 | Checks for a possible upgrade and returns an object describing the 5 | newest version and upgrade possibility. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "latest": "v0.14.47", 11 | "majorNewer": false, 12 | "newer": true, 13 | "running": "v0.14.46" 14 | } 15 | -------------------------------------------------------------------------------- /refresh-authors.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | set -euo pipefail 3 | 4 | go install github.com/calmh/git-contributors@latest 5 | git-contributors --read-authors=AUTHORS --authors > authors-new 6 | grep \# AUTHORS > authors-hdr 7 | cat authors-hdr authors-new > AUTHORS 8 | rm authors-hdr authors-new 9 | 10 | git-contributors --read-authors=AUTHORS --names --geekrank | sed 's/_/\\_/g' > thanks.txt 11 | -------------------------------------------------------------------------------- /rest/system-error-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/error 2 | ====================== 3 | 4 | .. note:: Return format changed in 0.12.0. 5 | 6 | Returns the list of recent errors. 7 | 8 | .. code-block:: json 9 | 10 | { 11 | "errors": [ 12 | { 13 | "when": "2014-09-18T12:59:26.549953186+02:00", 14 | "message": "This is an error string" 15 | } 16 | ] 17 | } 18 | -------------------------------------------------------------------------------- /_templates/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "!layout.html" %} 2 | {%- block relbar_bottom %} 3 | {%- if edit_on_github_url %} 4 |
5 | {{ _('Edit this page on GitHub') }} 6 |
7 | Version: {{ release }} 8 |
9 | {%- endif %} 10 | {{ super() }} 11 | {%- endblock %} 12 | -------------------------------------------------------------------------------- /rest/system-version-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/version 2 | ======================== 3 | 4 | Returns the current Syncthing version information. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "arch": "amd64", 10 | "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC", 11 | "os": "darwin", 12 | "version": "v0.10.27+3-gea8c3de" 13 | } 14 | -------------------------------------------------------------------------------- /events/starting.rst: -------------------------------------------------------------------------------- 1 | Starting 2 | -------- 3 | 4 | Emitted exactly once, when Syncthing starts, before parsing 5 | configuration etc. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "id": 1, 11 | "globalID": 1, 12 | "type": "Starting", 13 | "time": "2014-07-17T13:13:32.044470055+02:00", 14 | "data": { 15 | "home": "/home/jb/.config/syncthing" 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /events/startupcomplete.rst: -------------------------------------------------------------------------------- 1 | StartupComplete 2 | --------------- 3 | 4 | Emitted exactly once, when initialization is complete and Syncthing is 5 | ready to start exchanging data with other devices. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "id": 1, 11 | "globalID": 1, 12 | "type": "StartupComplete", 13 | "time": "2014-07-13T21:03:18.383239179+02:00", 14 | "data": null 15 | } 16 | -------------------------------------------------------------------------------- /events/devicepaused.rst: -------------------------------------------------------------------------------- 1 | DevicePaused 2 | ------------ 3 | 4 | Emitted when a device was paused. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 13, 10 | "globalID": 13, 11 | "type": "DevicePaused", 12 | "time": "2014-07-17T13:28:05.043465207+02:00", 13 | "data": { 14 | "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG" 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /_script/go.mod: -------------------------------------------------------------------------------- 1 | module syncthing.net/docs 2 | 3 | go 1.23.0 4 | 5 | require ( 6 | github.com/google/go-github/v49 v49.1.0 7 | golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb 8 | golang.org/x/tools v0.12.0 9 | ) 10 | 11 | require ( 12 | github.com/google/go-querystring v1.1.0 // indirect 13 | golang.org/x/crypto v0.35.0 // indirect 14 | golang.org/x/mod v0.12.0 // indirect 15 | golang.org/x/sys v0.30.0 // indirect 16 | ) 17 | -------------------------------------------------------------------------------- /events/deviceresumed.rst: -------------------------------------------------------------------------------- 1 | DeviceResumed 2 | ------------- 3 | 4 | Generated each time a device was resumed. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 2, 10 | "globalID": 2, 11 | "type": "DeviceResumed", 12 | "time": "2014-07-13T21:04:33.687836696+02:00", 13 | "data": { 14 | "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG" 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /events/folderpaused.rst: -------------------------------------------------------------------------------- 1 | FolderPaused 2 | ------------ 3 | 4 | Generated when the configuration changes regarding the "paused" state 5 | of a folder. Sent repeatedly for each changed folder. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "id": 93, 11 | "globalID": 93, 12 | "type": "FolderPaused", 13 | "time": "2021-06-07T23:45:03.414609034+02:00", 14 | "data": { 15 | "id": "abcde-fghij", 16 | "label": "My folder" 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /rest/db-revert-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/db/revert 2 | ==================== 3 | 4 | .. versionadded:: 0.14.50 5 | 6 | Request revert of a receive only folder. Reverting a folder means to undo 7 | all local changes. This API call does nothing if the folder is not a receive 8 | only folder. 9 | 10 | Takes the mandatory parameter `folder` (folder ID). 11 | 12 | .. code-block:: bash 13 | 14 | curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default 15 | -------------------------------------------------------------------------------- /rest/system-config-insync-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/config/insync (DEPRECATED) 2 | =========================================== 3 | 4 | .. deprecated:: v1.12.0 5 | This endpoint still works as before but is deprecated. Use 6 | :ref:`rest-config-insync` instead. 7 | 8 | Returns whether the config is in sync, i.e. whether the running 9 | configuration is the same as that on disk. 10 | 11 | .. code-block:: json 12 | 13 | { 14 | "configInSync": true 15 | } 16 | -------------------------------------------------------------------------------- /rest/system-loglevels-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/loglevels 2 | =========================== 3 | 4 | .. versionadded:: 2.0.0 5 | 6 | Changes the log level for specified facilities. Post an object with the log 7 | facilites as keys and desired log level (``DEBUG``, ``INFO``, ``WARN``, or 8 | ``ERROR``) as the values. 9 | 10 | .. code-block:: bash 11 | 12 | $ curl -H X-API-Key:abc123 -d '{"beacon":"DEBUG","discovery":"WARN"}' 'http://localhost:8384/rest/system/loglevels' 13 | -------------------------------------------------------------------------------- /events/folderresumed.rst: -------------------------------------------------------------------------------- 1 | FolderResumed 2 | ------------- 3 | 4 | Generated when the configuration changes regarding the "paused" state 5 | of a folder. Sent repeatedly for each changed folder. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "id": 93, 11 | "globalID": 93, 12 | "type": "FolderResumed", 13 | "time": "2021-06-07T23:45:03.414609034+02:00", 14 | "data": { 15 | "id": "abcde-fghij", 16 | "label": "My folder" 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /rest/db-override-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/db/override 2 | ====================== 3 | 4 | Request override of a send only folder. Override means to make the local 5 | version latest, overriding changes made on other devices. This API call does 6 | nothing if the folder is not a send only folder. 7 | 8 | Takes the mandatory parameter `folder` (folder ID). 9 | 10 | .. code-block:: bash 11 | 12 | curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default 13 | -------------------------------------------------------------------------------- /advanced/folder-send-xattrs.rst: -------------------------------------------------------------------------------- 1 | sendXattrs 2 | ========== 3 | 4 | .. versionadded:: 1.22.0 5 | 6 | When enabled, Syncthing will record extended attributes for local files when 7 | they are scanned and send this information to peer devices. Peer devices 8 | configured to :doc:`sync extended attributes ` will use 9 | this information. 10 | 11 | Scanning extended attributes may have a performance impact on scan times. 12 | 13 | .. seealso:: :doc:`folder-sync-xattrs` 14 | -------------------------------------------------------------------------------- /rest/stats-folder-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/stats/folder 2 | ====================== 3 | 4 | Returns general statistics about folders. Currently contains the 5 | last scan time and the last synced file. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "folderid": { 11 | "lastScan": "2016-06-02T13:28:01.288181412-04:00", 12 | "lastFile": { 13 | "filename": "file/name", 14 | "at": "2015-04-16T22:04:18.3066971+01:00" 15 | } 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /users/metrics.rst: -------------------------------------------------------------------------------- 1 | Prometheus-Style Metrics 2 | ======================== 3 | 4 | Syncthing provides an endpoint for Prometheus-style metrics. Metrics are 5 | served on the ``/metrics`` path on the GUI / API address. The metrics endpoint 6 | requires authentication when the GUI / API is configured to require 7 | authentication; see :doc:`/dev/rest` for details. 8 | 9 | Metrics 10 | ------- 11 | 12 | The following metrics are available. 13 | 14 | .. include:: ../includes/metrics-list.rst 15 | -------------------------------------------------------------------------------- /advanced/folder-send-ownership.rst: -------------------------------------------------------------------------------- 1 | sendOwnership 2 | ============= 3 | 4 | .. versionadded:: 1.22.0 5 | 6 | When enabled, Syncthing will record ownership for local files when they are 7 | scanned and send this information to peer devices. Peer devices configured 8 | to :doc:`sync ownership ` will use this information. 9 | 10 | On Windows, scanning ownership information has a fairly significant 11 | performance impact on scan times. 12 | 13 | .. seealso:: :doc:`folder-sync-ownership` 14 | -------------------------------------------------------------------------------- /rest/cluster-pending-devices-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/cluster/pending/devices 2 | ================================= 3 | 4 | .. versionadded:: 1.13.0 5 | 6 | Lists remote devices which have tried to connect, but are not yet 7 | configured in our instance. 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": { 13 | "time": "2020-03-18T11:43:07Z", 14 | "name": "Friend Joe", 15 | "address": "192.168.1.2:22000" 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /rest/stats-device-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/stats/device 2 | ====================== 3 | 4 | Returns general statistics about devices. Currently, only contains the 5 | time the device was last seen and the last connection duration. 6 | 7 | .. code-block:: bash 8 | 9 | $ curl -s http://localhost:8384/rest/stats/device | json 10 | { 11 | "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": { 12 | "lastSeen" : "2015-04-18T11:21:31.3256277+01:00" 13 | "lastConnectionDurationS": 556335.421708141 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /events/remoteindexupdated.rst: -------------------------------------------------------------------------------- 1 | RemoteIndexUpdated 2 | ------------------ 3 | 4 | Generated each time new index information is received from a device. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 44, 10 | "globalID": 44, 11 | "type": "RemoteIndexUpdated", 12 | "time": "2014-07-13T21:04:35.394184435+02:00", 13 | "data": { 14 | "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG", 15 | "folder": "lightroom", 16 | "items": 1000 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /events/devicediscovered.rst: -------------------------------------------------------------------------------- 1 | DeviceDiscovered 2 | ---------------- 3 | 4 | Emitted when a new device is discovered using local discovery. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 13, 10 | "globalID": 13, 11 | "type": "DeviceDiscovered", 12 | "time": "2014-07-17T13:28:05.043465207+02:00", 13 | "data": { 14 | "addrs": [ 15 | "172.16.32.25:22000" 16 | ], 17 | "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /events/failure.rst: -------------------------------------------------------------------------------- 1 | Failure 2 | ------- 3 | 4 | Generated for specific errors that will also be sent to the usage 5 | reporting server, if enabled in the configuration. These are usually 6 | of special interest to the developers to troubleshoot complex errors. 7 | The ``data`` field contains a textual error message. 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "id": 93, 13 | "globalID": 93, 14 | "type": "Failure", 15 | "time": "2021-06-07T21:22:03.414609034+02:00", 16 | "data": "index handler got paused while already paused" 17 | } 18 | -------------------------------------------------------------------------------- /specs/index.rst: -------------------------------------------------------------------------------- 1 | .. _specs: 2 | 3 | Specifications 4 | ============== 5 | 6 | .. toctree:: 7 | :hidden: 8 | 9 | bep-v1 10 | globaldisco-v3 11 | localdisco-v4 12 | relay-v1 13 | untrusted 14 | 15 | :ref:`bep-v1` 16 | The protocol used to exchange file data and metadata between Syncthing devices. 17 | 18 | :ref:`globaldisco-v3` 19 | The protocol used for global discovery over the Internet. 20 | 21 | :ref:`localdisco-v4` 22 | The protocol used for local discovery within a broadcast domain (LAN). 23 | 24 | :ref:`relay-v1` 25 | The protocol used for connection relaying. 26 | -------------------------------------------------------------------------------- /events/clusterconfigreceived.rst: -------------------------------------------------------------------------------- 1 | ClusterConfigReceived 2 | --------------------- 3 | 4 | .. versionadded:: 1.20.0 5 | 6 | The ``ClusterConfigReceived`` event is emitted after processing such a protocol 7 | message received from a remote device. It is mainly used for internal purposes. 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "id": 84, 13 | "globalID": 84, 14 | "type": "ClusterConfigReceived", 15 | "time": "2022-04-27T14:14:27.043576583+09:00", 16 | "data": { 17 | "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /rest/system-reset-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/reset 2 | ======================= 3 | 4 | Post with empty body to erase the current index database and restart 5 | Syncthing. With no query parameters, the entire database is erased from disk. 6 | By specifying the ``folder`` parameter with a valid folder ID, only 7 | information for that folder will be erased: 8 | 9 | .. code-block:: bash 10 | 11 | curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g 12 | 13 | **Caution**: See :option:`--reset-database` for ``.stfolder`` creation 14 | side-effect and caution regarding mountpoints. 15 | -------------------------------------------------------------------------------- /users/index.rst: -------------------------------------------------------------------------------- 1 | Usage 2 | ===== 3 | 4 | .. toctree:: 5 | :maxdepth: 1 6 | 7 | Command Line Operation 8 | faq 9 | releases 10 | 11 | Configuration 12 | advanced 13 | foldertypes 14 | introducer 15 | guilisten 16 | ldap 17 | tuning 18 | metrics 19 | 20 | syncing 21 | untrusted 22 | 23 | firewall 24 | relaying 25 | proxying 26 | tunneling 27 | 28 | ignoring 29 | versioning 30 | 31 | stdiscosrv 32 | strelaysrv 33 | custom-upgrades 34 | 35 | autostart 36 | contrib 37 | profiling 38 | reverseproxy 39 | security 40 | crashrep 41 | -------------------------------------------------------------------------------- /rest/system-log-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/log 2 | ==================== 3 | 4 | .. versionadded:: 0.12.0 5 | 6 | Returns the list of recent log entries. The optional ``since`` parameter limits 7 | the results to message newer than the given timestamp in :rfc:`3339` format. 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "messages": [ 13 | { 14 | "when": "2014-09-18T12:59:26.549953186+02:00", 15 | "message": "This is a log entry" 16 | } 17 | ] 18 | } 19 | 20 | GET /rest/system/log.txt 21 | ======================== 22 | 23 | Returns the same information, formatted as a text log instead of a JSON object. 24 | -------------------------------------------------------------------------------- /events/configsaved.rst: -------------------------------------------------------------------------------- 1 | ConfigSaved 2 | ----------- 3 | 4 | Emitted after the config has been saved by the user or by Syncthing 5 | itself. 6 | 7 | .. code-block:: json 8 | 9 | { 10 | "id": 50, 11 | "globalID": 50, 12 | "type": "ConfigSaved", 13 | "time": "2014-12-13T00:09:13.5166486Z", 14 | "data": { 15 | "version": 7, 16 | "folders": [{"..."}], 17 | "devices": [{"..."}], 18 | "gui": {"..."}, 19 | "ldap": {"..."}, 20 | "options": {"..."}, 21 | "remoteIgnoredDevices": [{"..."}], 22 | "defaults": {"..."} 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /rest/system-discovery-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/discovery 2 | ================================ 3 | 4 | .. note:: Removed in v0.12.0. 5 | 6 | Post with the query parameters ``device`` and ``addr`` to add entries to 7 | the discovery cache. 8 | 9 | .. code-block:: bash 10 | 11 | curl -X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000 12 | # Or with the X-API-Key header: 13 | curl -X POST --header "X-API-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ" http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000 14 | -------------------------------------------------------------------------------- /rest/folder-errors-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/folder/errors 2 | ======================= 3 | 4 | .. versionadded:: 0.14.53 5 | 6 | Takes one mandatory parameter, ``folder``, and returns the list of errors 7 | encountered during scanning or pulling. 8 | 9 | The results can be paginated using the :ref:`common pagination parameters 10 | `. 11 | 12 | .. code-block:: json 13 | 14 | { 15 | "folder": "nnhic-sxuae", 16 | "errors": [ 17 | { 18 | "path": "noperm.txt", 19 | "error": "hashing: open /path/to/folder/noperm.txt: permission denied" 20 | } 21 | ], 22 | "page": 1, 23 | "perpage": 100 24 | } 25 | -------------------------------------------------------------------------------- /events/deviceconnected.rst: -------------------------------------------------------------------------------- 1 | DeviceConnected 2 | --------------- 3 | 4 | Generated each time a connection to a device has been established. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 2, 10 | "globalID": 2, 11 | "type": "DeviceConnected", 12 | "time": "2014-07-13T21:04:33.687836696+02:00", 13 | "data": { 14 | "addr": "172.16.32.25:22000", 15 | "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG", 16 | "deviceName": "Laptop", 17 | "clientName": "syncthing", 18 | "clientVersion": "v0.13.4", 19 | "type": "TCP (Client)" 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /events/folderscanprogress.rst: -------------------------------------------------------------------------------- 1 | FolderScanProgress 2 | ------------------ 3 | 4 | Emitted in regular intervals (folder setting ProgressIntervalS, 2s by default) 5 | during scans giving the amount of bytes already scanned and to be scanned in 6 | total , as well as the current scanning rates in bytes per second. 7 | 8 | .. code-block:: json 9 | 10 | { 11 | "data" : { 12 | "total" : 1, 13 | "rate" : 0, 14 | "current" : 0, 15 | "folder" : "bd7q3-zskm5" 16 | }, 17 | "globalID" : 29, 18 | "type" : "FolderScanProgress", 19 | "time" : "2017-03-06T15:00:58.072004209+01:00", 20 | "id" : 29 21 | } 22 | -------------------------------------------------------------------------------- /rest/system-loglevels-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/system/loglevels 2 | ========================== 3 | 4 | .. versionadded:: 2.0.0 5 | 6 | Returns the set of log facilities and their current log level. 7 | 8 | .. code-block:: json 9 | 10 | { 11 | "levels": { 12 | "api": "INFO", 13 | "beacon": "INFO", 14 | ... 15 | "versioner": "INFO", 16 | "watchaggregator": "INFO" 17 | }, 18 | "packages": { 19 | "api": "REST API", 20 | "beacon": "Multicast and broadcast discovery", 21 | ... 22 | "versioner": "File versioning", 23 | "watchaggregator": "Filesystem event watcher" 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /events/itemstarted.rst: -------------------------------------------------------------------------------- 1 | ItemStarted 2 | ----------- 3 | 4 | Generated when Syncthing begins synchronizing a file to a newer version. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 93, 10 | "globalID": 93, 11 | "type": "ItemStarted", 12 | "time": "2014-07-13T21:22:03.414609034+02:00", 13 | "data": { 14 | "item": "test.txt", 15 | "folder": "default", 16 | "type": "file", 17 | "action": "update" 18 | } 19 | } 20 | 21 | The ``action`` field is either ``update`` (contents changed), ``metadata`` (file metadata changed but not contents), or ``delete``. 22 | 23 | .. versionadded:: 0.11.10 24 | The ``metadata`` action. 25 | -------------------------------------------------------------------------------- /events/devicerejected.rst: -------------------------------------------------------------------------------- 1 | DeviceRejected (DEPRECATED) 2 | --------------------------- 3 | 4 | .. deprecated:: v1.13.0 5 | This event is still emitted for compatibility, but deprecated. Use 6 | the replacement :doc:`pendingdeviceschanged` event instead. 7 | 8 | Emitted when there is a connection from a device we are not configured 9 | to talk to. 10 | 11 | .. code-block:: json 12 | 13 | { 14 | "id": 24, 15 | "globalID": 24, 16 | "type": "DeviceRejected", 17 | "time": "2014-08-19T10:43:00.562821045+02:00", 18 | "data": { 19 | "address": "127.0.0.1:51807", 20 | "name": "My dusty computer", 21 | "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /rest/svc-deviceid-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/svc/deviceid 2 | ====================== 3 | 4 | Verifies and formats a device ID. Accepts all currently valid formats 5 | (52 or 56 characters with or without separators, upper or lower case, 6 | with trivial substitutions). Takes one parameter, ``id``, and returns 7 | either a valid device ID in modern format, or an error. 8 | 9 | .. code-block:: bash 10 | 11 | $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json 12 | { 13 | "error": "device ID invalid: incorrect length" 14 | } 15 | 16 | $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json 17 | { 18 | "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2" 19 | } 20 | -------------------------------------------------------------------------------- /rest/system-config-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/system/config (DEPRECATED) 2 | ===================================== 3 | 4 | .. deprecated:: v1.12.0 5 | This endpoint still works as before but is deprecated. Use :doc:`config` 6 | instead. 7 | 8 | Post the full contents of the configuration, in the same format as returned by 9 | the corresponding GET request. When posting the configuration succeeds, 10 | the posted configuration is immediately applied, except for changes that require a restart. Query 11 | :ref:`rest-config-insync` to check if a restart is required. 12 | 13 | This endpoint is the main point to control Syncthing, even if the change only 14 | concerns a very small part of the config: The usual workflow is to get the 15 | config, modify the needed parts and post it again. 16 | -------------------------------------------------------------------------------- /events/statechanged.rst: -------------------------------------------------------------------------------- 1 | .. _statechanged: 2 | 3 | StateChanged 4 | ------------ 5 | 6 | Emitted when a folder changes state. Possible states are ``idle``, 7 | ``scanning``, ``syncing`` and ``error``. The field ``duration`` is 8 | the number of seconds the folder spent in state ``from``. In the example 9 | below, the folder ``default`` was in state ``scanning`` for 0.198 10 | seconds and is now in state ``idle``. 11 | 12 | .. code-block:: json 13 | 14 | { 15 | "id": 8, 16 | "globalID": 8, 17 | "type": "StateChanged", 18 | "time": "2014-07-17T13:14:28.697493016+02:00", 19 | "data": { 20 | "folder": "default", 21 | "from": "scanning", 22 | "duration": 0.19782869900000002, 23 | "to": "idle" 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /intro/project-presentation.rst: -------------------------------------------------------------------------------- 1 | .. _project-presentation: 2 | 3 | Project Presentation 4 | ==================== 5 | 6 | These are the various projects under the Syncthing umbrella and the people 7 | chiefly responsible for maintaining them. 8 | 9 | Syncthing 10 | --------- 11 | 12 | Syncthing_ is the core CLI application, used by the Android and native UI 13 | wrappers. 14 | 15 | - Jakob Borg / :user:`calmh` 16 | - Audrius Butkevicius / :user:`AudriusButkevicius` 17 | - Simon Frei / :user:`imsodin` 18 | 19 | syncthing-macos 20 | --------------- 21 | 22 | `syncthing-macos`_ is a native macOS Syncthing application bundle. 23 | 24 | - Jerry Jacobs / :user:`xor-gate` 25 | 26 | .. _Syncthing: https://github.com/syncthing/syncthing 27 | .. _`syncthing-macos`: https://github.com/syncthing/syncthing-macos 28 | -------------------------------------------------------------------------------- /events/pendingdeviceschanged.rst: -------------------------------------------------------------------------------- 1 | PendingDevicesChanged 2 | --------------------- 3 | 4 | .. versionadded:: 1.14.0 5 | 6 | Emitted when pending devices were added / updated (connection from 7 | unknown ID) or removed (device is ignored, dismissed or added). 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "id": 87, 13 | "type": "PendingDevicesChanged", 14 | "time": "2020-12-22T22:24:37.578586718+01:00", 15 | "data": { 16 | "added": [ 17 | { 18 | "address": "127.0.0.1:51807", 19 | "deviceID": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK", 20 | "name": "My dusty computer" 21 | } 22 | ], 23 | "removed": [ 24 | { 25 | "deviceID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2" 26 | } 27 | ] 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /rest/folder-versions-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/folder/versions 2 | ========================== 3 | 4 | Restore archived versions of a given set of files. Expects an object with 5 | attributes named after the relative file paths, with timestamps as values 6 | matching valid ``versionTime`` entries in the corresponding 7 | :doc:`folder-versions-get` response object. 8 | 9 | Takes the mandatory parameter ``folder`` (folder ID). Returns an object 10 | containing any error messages that occurred during restoration of the file, with 11 | the file path as attribute name. 12 | 13 | .. code-block:: bash 14 | 15 | curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/folder/versions?folder=default -d '{ 16 | "dir1/dir2/bar": "2022-02-06T20:44:12+01:00", 17 | "baz": "2022-02-06T20:44:20+01:00" 18 | }' 19 | -------------------------------------------------------------------------------- /advanced/folder-disable-fsync.rst: -------------------------------------------------------------------------------- 1 | disableFsync 2 | ============ 3 | 4 | ``disableFsync`` is an advanced folder setting that affects file 5 | modifications. Normally, when a file has been modified Syncthing calls 6 | ``fsync()`` on that file and the containing directory. This forces file data 7 | that is cached in RAM to be flushed to disk. This ensures that data is 8 | safely stored on disk and thus prevents data loss in the case of a power 9 | failure soon after file modification. 10 | 11 | There is however a performance cost to doing this, especially on rotating 12 | disks or network filesystems, especially syncing many small files. Disabling 13 | ``fsync()`` improves performance at the price of risking data loss in a 14 | power failure situation. 15 | 16 | .. note:: This option should normally be set to ``false``. 17 | -------------------------------------------------------------------------------- /events/folderrejected.rst: -------------------------------------------------------------------------------- 1 | FolderRejected (DEPRECATED) 2 | --------------------------- 3 | 4 | .. deprecated:: v1.13.0 5 | This event is still emitted for compatibility, but deprecated. Use 6 | the replacement :doc:`pendingfolderschanged` event instead. 7 | 8 | Emitted when a device sends index information for a folder we do not 9 | have, or have but do not share with the device in question. 10 | 11 | .. code-block:: json 12 | 13 | { 14 | "id": 27, 15 | "globalID": 27, 16 | "type": "FolderRejected", 17 | "time": "2014-08-19T10:41:06.761751399+02:00", 18 | "data": { 19 | "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK", 20 | "folder": "GXWxf-3zgnU", 21 | "folderLabel": "My Pictures" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /events/remotedownloadprogress.rst: -------------------------------------------------------------------------------- 1 | RemoteDownloadProgress 2 | ---------------------- 3 | 4 | This event is emitted when a :ref:`download-progress` message is 5 | received. It returns a map ``data`` of filenames with a count of 6 | downloaded blocks. The files in questions are currently being 7 | downloaded on the remote ``device`` and belong to ``folder``. 8 | 9 | .. code-block:: json 10 | 11 | { 12 | "time" : "2017-03-07T00:11:37.65838955+01:00", 13 | "globalID" : 170, 14 | "data" : { 15 | "state" : { 16 | "tahr64-6.0.5.iso" : 1784 17 | }, 18 | "device" : "F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A", 19 | "folder" : "Dokumente" 20 | }, 21 | "type" : "RemoteDownloadProgress", 22 | "id" : 163 23 | } 24 | -------------------------------------------------------------------------------- /rest/db-ignores-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/db/ignores 2 | ==================== 3 | 4 | Takes one parameter, ``folder``, and returns the content of the 5 | ``.stignore`` as the ``ignore`` field. A second field, ``expanded``, 6 | provides a list of strings which represent globbing patterns described by gobwas/glob (based on standard wildcards) that match the patterns in ``.stignore`` and all the includes. If appropriate these globs are prepended by the following modifiers: ``!`` to negate the glob, ``(?i)`` to do case insensitive matching and ``(?d)`` to enable removing of ignored files in an otherwise empty directory. 7 | 8 | .. code-block:: json 9 | 10 | { 11 | "ignore": [ 12 | "(?i)/Backups" 13 | ], 14 | "expanded": [ 15 | "(?i)Backups", 16 | "(?i)Backups/**" 17 | ] 18 | } 19 | -------------------------------------------------------------------------------- /events/folderwatchstatechanged.rst: -------------------------------------------------------------------------------- 1 | FolderWatchStateChanged 2 | ----------------------- 3 | 4 | The ``FolderWatchStateChanged`` event is emitted when a folder's watcher routine 5 | encounters a new error, or when a previous error disappeared after retrying. 6 | The event contains the ID of the affected folder and textual error messages 7 | describing the previous (``from``) and the updated (``to``) error conditions. 8 | If there was no error in either of these, the respective field is omitted. 9 | 10 | .. code-block:: json 11 | 12 | { 13 | "id": 123, 14 | "type": "FolderWatchStateChanged", 15 | "time": "2022-03-14T12:34:56.890000000+01:00", 16 | "data": { 17 | "folder": "default", 18 | "from": "Something bad happened.", 19 | "to": "Something worse happened." 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /events/devicedisconnected.rst: -------------------------------------------------------------------------------- 1 | DeviceDisconnected 2 | ------------------ 3 | 4 | Generated each time a connection to a device has been terminated. 5 | 6 | .. code-block:: json 7 | 8 | { 9 | "id": 48, 10 | "globalID": 48, 11 | "type": "DeviceDisconnected", 12 | "time": "2014-07-13T21:18:52.859929215+02:00", 13 | "data": { 14 | "error": "unexpected EOF", 15 | "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG" 16 | } 17 | } 18 | 19 | 20 | .. note:: 21 | The error key contains the cause for disconnection, which might not 22 | necessarily be an error as such. Specifically, "EOF" and "unexpected 23 | EOF" both signify TCP connection termination, either due to the other 24 | device restarting or going offline or due to a network change. 25 | -------------------------------------------------------------------------------- /rest/db-scan-post.rst: -------------------------------------------------------------------------------- 1 | POST /rest/db/scan 2 | ================== 3 | 4 | Request immediate scan. Takes the optional parameters ``folder`` (folder ID), 5 | ``sub`` (path relative to the folder root) and ``next`` (time in seconds). If 6 | ``folder`` is omitted or empty all folders are scanned. If ``sub`` is given, 7 | only this path (and children, in case it's a directory) is scanned. The ``next`` 8 | argument delays Syncthing's automated rescan interval for a given amount of 9 | seconds. 10 | 11 | Requesting scan of a path that no longer exists, but previously did, is 12 | valid and will result in Syncthing noticing the deletion of the path in 13 | question. 14 | 15 | Returns status 200 and no content upon success, or status 500 and a 16 | plain text error if an error occurred during scanning. 17 | 18 | .. code-block:: bash 19 | 20 | curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar 21 | -------------------------------------------------------------------------------- /events/localindexupdated.rst: -------------------------------------------------------------------------------- 1 | LocalIndexUpdated 2 | ----------------- 3 | 4 | Generated when the local index information has changed, due to 5 | synchronizing one or more items from the cluster or discovering local 6 | changes during a scan. 7 | 8 | .. code-block:: json 9 | 10 | { 11 | "id": 59, 12 | "globalID": 59, 13 | "type": "LocalIndexUpdated", 14 | "time": "2014-07-17T13:27:28.051369434+02:00", 15 | "data": { 16 | "folder": "default", 17 | "items": 1000, 18 | "filenames": [ 19 | "foo", 20 | "bar", 21 | "baz" 22 | ], 23 | "sequence": 12345, 24 | "version": 12345 25 | } 26 | } 27 | 28 | .. deprecated:: v1.10.0 29 | The ``version`` field is a legacy name kept only for compatibility. Use the 30 | ``sequence`` field with identical content instead. 31 | -------------------------------------------------------------------------------- /advanced/option-max-concurrency.rst: -------------------------------------------------------------------------------- 1 | maxFolderConcurrency 2 | ==================== 3 | 4 | .. versionadded:: 1.4.0 5 | 6 | The ``maxFolderConcurrency`` option controls how many folders may 7 | concurrently be in I/O-intensive operations such as syncing or scanning. The 8 | default value is the same as the number of logical CPU cores in the system. 9 | Folders waiting for their turn to scan or sync will show up as "Waiting to 10 | Scan" or "Waiting to Sync" until the total number of ongoing such operations 11 | is low enough to let them proceed. 12 | 13 | Valid Values 14 | ------------ 15 | 16 | **Zero (0)**: 17 | The default, means the number of logical CPUs in the system (i.e., 2, 4, 18 | 8, etc.), autodetected. 19 | 20 | **Negative (< 0)**: 21 | No limit on the number of concurrent operations. This was the default in 22 | versions < 1.4.0. 23 | 24 | **A positive integer (> 0)**: 25 | Use this specific limit. 26 | -------------------------------------------------------------------------------- /rest/cluster-pending-devices-delete.rst: -------------------------------------------------------------------------------- 1 | DELETE /rest/cluster/pending/devices 2 | ==================================== 3 | 4 | .. versionadded:: 1.18.0 5 | 6 | Remove records about a pending remote device which tried to connect. Valid 7 | values for the ``device`` parameter are those from the corresponding 8 | :doc:`cluster-pending-devices-get` endpoint. 9 | 10 | .. code-block:: bash 11 | 12 | $ curl -X DELETE -H "X-API-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2 13 | 14 | Returns status 200 and no content upon success, or status 500 and a 15 | plain text error on failure. A :doc:`/events/pendingdeviceschanged` 16 | event will be generated in response. 17 | 18 | For a more permanent effect, also for future connections from the same 19 | device ID, the device should be ignored in the :doc:`configuration 20 | ` instead. 21 | -------------------------------------------------------------------------------- /.github/workflows/refresh-authors.yml: -------------------------------------------------------------------------------- 1 | name: Refresh author list 2 | on: 3 | workflow_dispatch: 4 | schedule: 5 | # Thursday mornings 6 | - cron: '42 7 * * 4' 7 | 8 | jobs: 9 | 10 | refresh-versions: 11 | runs-on: ubuntu-latest 12 | name: Refresh authors 13 | steps: 14 | - uses: actions/checkout@v4 15 | with: 16 | fetch-depth: 0 17 | token: ${{ secrets.ACTIONS_GITHUB_TOKEN }} 18 | 19 | - uses: actions/setup-go@v5 20 | with: 21 | go-version: 'stable' 22 | 23 | - name: Run refresh script 24 | run: | 25 | set -euo pipefail 26 | bash refresh-authors.sh 27 | if [ -z "$(git status --porcelain)" ]; then exit 0; fi 28 | git config --global user.name 'Syncthing Release Automation' 29 | git config --global user.email 'release@syncthing.net' 30 | git commit -am 'Update author list' 31 | git push 32 | -------------------------------------------------------------------------------- /.github/workflows/refresh-versions.yml: -------------------------------------------------------------------------------- 1 | name: Refresh version list 2 | on: 3 | workflow_dispatch: 4 | schedule: 5 | # Wednesday mornings 6 | - cron: '42 7 * * 3' 7 | 8 | 9 | jobs: 10 | 11 | refresh-versions: 12 | runs-on: ubuntu-latest 13 | name: Refresh versions 14 | steps: 15 | - uses: actions/checkout@v4 16 | with: 17 | fetch-depth: 0 18 | token: ${{ secrets.ACTIONS_GITHUB_TOKEN }} 19 | 20 | - uses: actions/setup-go@v5 21 | with: 22 | go-version: 'stable' 23 | 24 | - name: Run refresh script 25 | run: | 26 | set -euo pipefail 27 | bash refresh-versions.sh 28 | if [ -z "$(git status --porcelain)" ]; then exit 0; fi 29 | git config --global user.name 'Syncthing Release Automation' 30 | git config --global user.email 'release@syncthing.net' 31 | git commit -am 'Update version list' 32 | git push 33 | -------------------------------------------------------------------------------- /rest/db-remoteneed-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/db/remoteneed 2 | ======================= 3 | 4 | .. versionadded:: 0.14.43 5 | 6 | Takes the mandatory parameters ``folder`` and ``device``, and returns the list 7 | of files which are needed by that remote device in order for it to become in 8 | sync with the shared folder. 9 | 10 | The results can be paginated using the :ref:`common pagination parameters 11 | `. 12 | 13 | .. code-block:: json 14 | 15 | { 16 | "files": [ 17 | { 18 | "flags": "0755", 19 | "sequence": 6, 20 | "modified": "2015-04-20T23:06:12+09:00", 21 | "name": "ls", 22 | "size": 34640, 23 | "version": [ 24 | "5157751870738175669:1" 25 | ] 26 | } 27 | ], 28 | "page": 1, 29 | "perpage": 100 30 | } 31 | 32 | .. note:: This is an expensive call, increasing CPU and RAM usage on the device. 33 | Use sparingly. 34 | -------------------------------------------------------------------------------- /rest/db-localchanged-get.rst: -------------------------------------------------------------------------------- 1 | GET /rest/db/localchanged 2 | ========================= 3 | 4 | .. versionadded:: 0.14.55 5 | 6 | Takes one mandatory parameter, ``folder``, and returns the list of files which 7 | were changed locally in a receive-only folder. Thus they differ from the global 8 | state and could be reverted by pulling from remote devices again, see 9 | :doc:`db-revert-post`. 10 | 11 | The results can be paginated using the :ref:`common pagination parameters 12 | `. 13 | 14 | .. code-block:: json 15 | 16 | { 17 | "files": [ 18 | { 19 | "flags": "0755", 20 | "sequence": 6, 21 | "modified": "2015-04-20T23:06:12+09:00", 22 | "name": "ls", 23 | "size": 34640, 24 | "version": [ 25 | "5157751870738175669:1" 26 | ] 27 | } 28 | ], 29 | "page": 1, 30 | "perpage": 100 31 | } 32 | 33 | .. note:: This is an expensive call, increasing CPU and RAM usage on the device. 34 | Use sparingly. 35 | -------------------------------------------------------------------------------- /events/remotechangedetected.rst: -------------------------------------------------------------------------------- 1 | RemoteChangeDetected 2 | -------------------- 3 | 4 | Generated upon scan whenever a file is locally updated due to a remote change. 5 | Files that are updated locally produce a :doc:`localchangedetected` event. 6 | 7 | .. note:: This event is not included in :doc:`/rest/events-get` endpoint without 8 | a mask specified, but needs to be selected explicitly. 9 | 10 | .. code-block:: json 11 | 12 | { 13 | "time" : "2017-03-06T23:58:21.844739891+01:00", 14 | "globalID" : 123, 15 | "data" : { 16 | "type" : "file", 17 | "action" : "deleted", 18 | "folder": "Dokumente", 19 | "folderID" : "Dokumente", 20 | "path" : "testfile", 21 | "label" : "Dokumente", 22 | "modifiedBy" : "BPDFDTU" 23 | }, 24 | "type" : "RemoteChangeDetected", 25 | "id" : 2 26 | } 27 | 28 | .. deprecated:: v1.1.2 29 | The ``folderID`` field is a legacy name kept only for compatibility. Use the 30 | ``folder`` field with identical content instead. 31 | -------------------------------------------------------------------------------- /advanced/folder-caseSensitiveFS.rst: -------------------------------------------------------------------------------- 1 | .. _case-sensitive-fs: 2 | 3 | caseSensitiveFS 4 | =============== 5 | 6 | .. versionadded:: 1.9.0 7 | 8 | ``caseSensitiveFS`` is an advanced folder setting that affects file name 9 | handling. 10 | 11 | With ``caseSensitiveFS`` set to ``false`` (the default setting) 12 | Syncthing's case sensitivity safety checks are enabled. 13 | Syncthing will then attempt to detect and prevent case-only file 14 | name collisions that can occur on case insensitive systems such as Windows 15 | and macOS, or other systems with case insensitive file systems. 16 | 17 | When set to ``true`` the extra safety checks for case insensitive 18 | filesystems are disabled. This will provide a small improvement in 19 | performance when the underlying filesystem is positively known to be 20 | case-sensitive already. This was the behavior of Syncthing 1.8.0 and earlier. 21 | 22 | .. note:: This option should normally be set to ``false``. It is 23 | **not** meant to change the basic principles of how Syncthing 24 | :ref:`handles case-sensitivity `. 25 | -------------------------------------------------------------------------------- /events/localchangedetected.rst: -------------------------------------------------------------------------------- 1 | LocalChangeDetected 2 | ------------------- 3 | 4 | Generated upon scan whenever the local disk has discovered an updated file from the 5 | previous scan. This does *not* include events that are discovered and copied from 6 | other devices (:doc:`remotechangedetected`), only files that were changed on the 7 | local filesystem. 8 | 9 | .. note:: This event is not included in :doc:`/rest/events-get` endpoint without 10 | a mask specified, but needs to be selected explicitly. 11 | 12 | .. code-block:: json 13 | 14 | { 15 | "id": 7, 16 | "globalID": 59, 17 | "time": "2016-09-26T22:07:10.7189141-04:00", 18 | "type": "LocalChangeDetected", 19 | "data": { 20 | "action": "deleted", 21 | "folder": "vitwy-zjxqt", 22 | "folderID": "vitwy-zjxqt", 23 | "label": "TestSync", 24 | "path": "test file.rtf", 25 | "type": "file" 26 | } 27 | } 28 | 29 | .. deprecated:: v1.1.2 30 | The ``folderID`` field is a legacy name kept only for compatibility. Use the 31 | ``folder`` field with identical content instead. 32 | -------------------------------------------------------------------------------- /users/advanced.rst: -------------------------------------------------------------------------------- 1 | .. _advanced: 2 | 3 | Advanced Configuration 4 | ====================== 5 | 6 | Syncthing has settings that are available but not exposed in the usual folder 7 | and device configuration screens. The reason for not exposing these settings 8 | more prominently varies from them simply being rarely useful, to them being 9 | actively dangerous when used improperly. 10 | 11 | .. warning:: 12 | Use care when changing advanced configuration settings and make sure that 13 | you understand the resulting effects and consequences. 14 | 15 | The advanced settings dialog is accessed from the main menu: 16 | 17 | .. image:: advanced-settings.png 18 | 19 | General Settings 20 | ----------------- 21 | 22 | .. toctree:: 23 | :maxdepth: 1 24 | :glob: 25 | 26 | ../advanced/option-* 27 | 28 | Per Folder Settings 29 | ------------------- 30 | 31 | .. toctree:: 32 | :maxdepth: 1 33 | :glob: 34 | 35 | ../advanced/folder-* 36 | 37 | Per Device Settings 38 | ------------------- 39 | 40 | .. toctree:: 41 | :maxdepth: 1 42 | :glob: 43 | 44 | ../advanced/device-* 45 | -------------------------------------------------------------------------------- /rest/cluster-pending-folders-delete.rst: -------------------------------------------------------------------------------- 1 | DELETE /rest/cluster/pending/folders 2 | ==================================== 3 | 4 | .. versionadded:: 1.18.0 5 | 6 | Remove records about a pending folder announced from a remote device. Valid 7 | values for the ``folder`` and ``device`` parameters are those from the 8 | corresponding :doc:`cluster-pending-folders-get` endpoint. The ``device`` 9 | parameter is optional and affects announcements of this folder from the given 10 | device, or from *any* device if omitted. 11 | 12 | .. code-block:: bash 13 | 14 | $ curl -X DELETE -H "X-API-Key: abc123" http://localhost:8384/rest/cluster/pending/folders?folder=cpkn4-57ysy&device=P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2 15 | 16 | Returns status 200 and no content upon success, or status 500 and a plain text 17 | error on failure. A :doc:`/events/pendingfolderschanged` event will be 18 | generated in response. 19 | 20 | For a more permanent effect, also for future announcements of the same folder 21 | ID, the folder should be ignored in the :doc:`configuration ` 22 | instead. 23 | -------------------------------------------------------------------------------- /dev/http-services.rst: -------------------------------------------------------------------------------- 1 | HTTP Utility Services API 2 | ========================= 3 | 4 | These services are available via HTTP on the GUI listen address, but in contrast 5 | to the REST API do not require any form of authentication or an API key. 6 | 7 | 8 | GET /meta.js 9 | ------------ 10 | 11 | Returns a JavaScript snippet defining a ``metadata`` variable with information 12 | about the serving Syncthing instance. It is meant to be consumed directly from 13 | an HTML ``