├── .github ├── dependabot.yml └── workflows │ ├── build.yml │ ├── refresh-authors.yml │ └── refresh-versions.yml ├── .gitignore ├── AUTHORS ├── Makefile ├── README.rst ├── _ext ├── edit_on_github.py └── syncthing_config.py ├── _script ├── find-metrics │ └── find-metrics.go ├── go.mod ├── go.sum ├── histver │ ├── synver.go │ └── table.go └── lsver.go ├── _static ├── custom.css ├── favicon.png ├── jquery-3.7.1.min.js ├── logo-horizontal.svg └── version_redirect.js ├── _templates ├── layout.html └── version.html ├── advanced ├── device-allowednetworks.rst ├── device-numconnections.rst ├── folder-autonormalize.rst ├── folder-caseSensitiveFS.rst ├── folder-copyrangemethod.rst ├── folder-disable-fsync.rst ├── folder-filesystem-type.rst ├── folder-ignoredelete.rst ├── folder-send-ownership.rst ├── folder-send-xattrs.rst ├── folder-sync-ownership.rst ├── folder-sync-xattrs.rst ├── folder-uselargeblocks.rst ├── folder-xattr-filter.rst ├── option-connection-limits.rst ├── option-database-tuning.rst └── option-max-concurrency.rst ├── conf.py ├── dev ├── building.rst ├── contributing.rst ├── crashrep.rst ├── debugging.rst ├── device-ids.rst ├── events.rst ├── http-services.rst ├── index.rst ├── infrastructure.rst ├── intro.rst ├── issues.rst ├── lgtm.png ├── release-creation.rst ├── release-signing.rst ├── rest.rst └── web.rst ├── docker-build.sh ├── draft ├── localver.rst └── selective.rst ├── events ├── clusterconfigreceived.rst ├── configsaved.rst ├── deviceconnected.rst ├── devicedisconnected.rst ├── devicediscovered.rst ├── devicepaused.rst ├── devicerejected.rst ├── deviceresumed.rst ├── downloadprogress.rst ├── failure.rst ├── foldercompletion.rst ├── foldererrors.rst ├── folderpaused.rst ├── folderrejected.rst ├── folderresumed.rst ├── folderscanprogress.rst ├── foldersummary.rst ├── folderwatchstatechanged.rst ├── itemfinished.rst ├── itemstarted.rst ├── listenaddresseschanged.rst ├── localchangedetected.rst ├── localindexupdated.rst ├── loginattempt.rst ├── pendingdeviceschanged.rst ├── pendingfolderschanged.rst ├── remotechangedetected.rst ├── remotedownloadprogress.rst ├── remoteindexupdated.rst ├── starting.rst ├── startupcomplete.rst └── statechanged.rst ├── includes ├── cli-commands.rst ├── env-vars.rst └── metrics-list.rst ├── index.rst ├── intro ├── getting-started.rst ├── gs1.png ├── gs2.png ├── gs3.png ├── gs5.png ├── gui.rst ├── gui1.png ├── index.rst └── project-presentation.rst ├── issues.png ├── make.bat ├── refresh-authors.sh ├── refresh-metrics.sh ├── refresh-versions.sh ├── rest ├── cluster-pending-devices-delete.rst ├── cluster-pending-devices-get.rst ├── cluster-pending-folders-delete.rst ├── cluster-pending-folders-get.rst ├── config.rst ├── db-browse-get.rst ├── db-completion-get.rst ├── db-file-get.rst ├── db-ignores-get.rst ├── db-ignores-post.rst ├── db-localchanged-get.rst ├── db-need-get.rst ├── db-override-post.rst ├── db-prio-post.rst ├── db-remoteneed-get.rst ├── db-revert-post.rst ├── db-scan-post.rst ├── db-status-get.rst ├── debug.rst ├── events-get.rst ├── folder-errors-get.rst ├── folder-pullerrors-get.rst ├── folder-versions-get.rst ├── folder-versions-post.rst ├── noauth-health-get.rst ├── stats-device-get.rst ├── stats-folder-get.rst ├── svc-deviceid-get.rst ├── svc-lang-get.rst ├── svc-random-string-get.rst ├── svc-report-get.rst ├── system-browse-get.rst ├── system-config-get.rst ├── system-config-insync-get.rst ├── system-config-post.rst ├── system-connections-get.rst ├── system-debug-get.rst ├── system-debug-post.rst ├── system-discovery-get.rst ├── system-discovery-post.rst ├── system-error-clear-post.rst ├── system-error-get.rst ├── system-error-post.rst ├── system-log-get.rst ├── system-paths-get.rst ├── system-pause-post.rst ├── system-ping-get.rst ├── system-ping-post.rst ├── system-reset-post.rst ├── system-restart-post.rst ├── system-resume-post.rst ├── system-shutdown-post.rst ├── system-status-get.rst ├── system-upgrade-get.rst ├── system-upgrade-post.rst └── system-version-get.rst ├── specs ├── bep-v1.rst ├── globaldisco-v3.rst ├── index.rst ├── localdisco-v4.rst ├── relay-v1.rst └── untrusted.rst ├── thanks.txt └── users ├── advanced-gui-ldap.png ├── advanced-ldap-groups.png ├── advanced-ldap.png ├── advanced-settings.png ├── advanced.rst ├── autostart.rst ├── config.rst ├── contrib.rst ├── crashrep.rst ├── custom-upgrades.rst ├── disco-settings.png ├── faq-parts ├── general.rst ├── troubleshooting.rst └── usage.rst ├── faq.rst ├── firewall.rst ├── foldermaster.rst ├── foldersendonly.png ├── foldertypes.rst ├── gui-debugging.png ├── guilisten.rst ├── ignoring.rst ├── index.rst ├── introducer.rst ├── ldap.rst ├── metrics.rst ├── override.png ├── profiling.rst ├── proxying.rst ├── relay.png ├── relaying.rst ├── releases.csv ├── releases.rst ├── reverseproxy.rst ├── security.rst ├── stdiscosrv.rst ├── strelaysrv.rst ├── syncing.rst ├── syncthing.rst ├── tuning.rst ├── tunneling.rst ├── untrusted-folder-share.png ├── untrusted.rst ├── versioning.rst ├── windows-nssm-config.png ├── windows-startup-addressbar.png ├── windows-startup-createshortcut.png ├── windows-startup-newshortcut.png ├── windows-taskschd-actions.png ├── windows-taskschd-additional-actions.png ├── windows-taskschd-additional-conditions.png ├── windows-taskschd-createtask.png ├── windows-taskschd-general.png ├── windows-taskschd-settingstab.png ├── windows-taskschd-triggers-logon.png └── windows-taskschd-triggers-startup.png /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "monthly" 7 | -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | _build/ 2 | _deployed 3 | _deployed.old 4 | _syncthing 5 | /RELEASE 6 | /TAG 7 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Syncthing Docs 2 | ============== 3 | 4 | This repo is the source behind https://docs.syncthing.net/. 5 | 6 | Editing 7 | ------- 8 | 9 | To edit the documentation you need a GitHub account. Once you have created one 10 | and logged in, you can edit any page by navigating to the corresponding file and 11 | clicking the edit (pen) icon. This will create a so called "fork" and a "pull 12 | request", which will be approved by one of the existing documentation team 13 | members. Once you have made a contribution or two, you can be added to the 14 | documentation team and perform edits without requiring approval. 15 | 16 | In the long run, learning to use Git_ and running Sphinx_ on your computer is 17 | beneficial. 18 | 19 | First steps to run it locally:: 20 | 21 | git clone https://github.com/syncthing/docs.git 22 | pip install -U Sphinx 23 | cd docs 24 | make html 25 | # open _build/html/index.html 26 | 27 | You can also use our Docker image to build the documentation, which is the 28 | same thing the build server does in the end: 29 | 30 | ./docker-build.sh html 31 | 32 | Structure 33 | --------- 34 | 35 | The documentation is divided into an index page (``index.rst``) and various 36 | subsections. The sections are: 37 | 38 | - Introductory information in ``intro``. 39 | - Information for users in ``users``. 40 | - Information for developers in ``dev``. 41 | 42 | The documentation uses the `rst format`_. For a starting point check out the 43 | `reStructuredText Primer`_. 44 | 45 | .. _Git: https://www.git-scm.com/ 46 | .. _Sphinx: https://www.sphinx-doc.org/ 47 | .. _`rst format`: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html 48 | .. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 49 | 50 | License 51 | ======= 52 | 53 | All documentation and protocol specifications are licensed under the `Creative 54 | Commons Attribution 4.0 International License 55 | `__. 56 | -------------------------------------------------------------------------------- /_ext/edit_on_github.py: -------------------------------------------------------------------------------- 1 | """ 2 | Sphinx extension to add ReadTheDocs-style "Edit on GitHub" links to the 3 | sidebar. 4 | 5 | Loosely based on https://github.com/astropy/astropy/pull/347 6 | """ 7 | 8 | import os 9 | import warnings 10 | 11 | 12 | __licence__ = 'BSD (3 clause)' 13 | 14 | 15 | def get_github_url(app, view, path): 16 | return 'https://github.com/{project}/{view}/{branch}/{path}'.format( 17 | project=app.config.edit_on_github_project, 18 | view=view, 19 | branch=app.config.edit_on_github_branch, 20 | path=path) 21 | 22 | 23 | def html_page_context(app, pagename, templatename, context, doctree): 24 | if templatename != 'page.html': 25 | return 26 | 27 | if not app.config.edit_on_github_project: 28 | warnings.warn("edit_on_github_project not specified") 29 | return 30 | 31 | path = os.path.relpath(doctree.get('source'), app.builder.srcdir) 32 | show_url = get_github_url(app, 'blob', path) 33 | edit_url = get_github_url(app, 'edit', path) 34 | 35 | context['show_on_github_url'] = show_url 36 | context['edit_on_github_url'] = edit_url 37 | 38 | 39 | def setup(app): 40 | app.add_config_value('edit_on_github_project', '', True) 41 | app.add_config_value('edit_on_github_branch', 'main', True) 42 | app.connect('html-page-context', html_page_context) -------------------------------------------------------------------------------- /_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 | -------------------------------------------------------------------------------- /_script/go.sum: -------------------------------------------------------------------------------- 1 | github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= 2 | github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38= 3 | github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= 4 | github.com/google/go-github/v49 v49.1.0 h1:LFkMgawGQ8dfzWLH/rNE0b3u1D3n6/dw7ZmrN3b+YFY= 5 | github.com/google/go-github/v49 v49.1.0/go.mod h1:MUUzHPrhGniB6vUKa27y37likpipzG+BXXJbG04J334= 6 | github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8= 7 | github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU= 8 | golang.org/x/crypto v0.35.0 h1:b15kiHdrGCHrP6LvwaQ3c03kgNhhiMgvlhxHQhmg2Xs= 9 | golang.org/x/crypto v0.35.0/go.mod h1:dy7dXNW32cAb/6/PRuTNsix8T+vJAqvuIy5Bli/x0YQ= 10 | golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb h1:mIKbk8weKhSeLH2GmUTrvx8CjkyJmnU1wFmg59CUjFA= 11 | golang.org/x/exp v0.0.0-20230811145659-89c5cff77bcb/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc= 12 | golang.org/x/mod v0.12.0 h1:rmsUpXtvNzj340zd98LZ4KntptpfRHwpFOHG188oHXc= 13 | golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= 14 | golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E= 15 | golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= 16 | golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc= 17 | golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= 18 | golang.org/x/tools v0.12.0 h1:YW6HUoUmYBpwSgyaGaZq1fHjrBjX1rlpZ54T6mu2kss= 19 | golang.org/x/tools v0.12.0/go.mod h1:Sc0INKfu04TlqNoRA1hgpFZbhYXHPr4V5DzpSBTPqQM= 20 | golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= 21 | -------------------------------------------------------------------------------- /_script/histver/table.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "encoding/csv" 5 | "fmt" 6 | "io" 7 | "regexp" 8 | "sort" 9 | ) 10 | 11 | type tableRow struct { 12 | Version string 13 | Runtime string 14 | Date string 15 | } 16 | 17 | func (r *tableRow) fromStrings(ss []string) error { 18 | if len(ss) < 3 { 19 | return fmt.Errorf("not enough fields") 20 | } 21 | r.Version = ss[0] 22 | r.Runtime = ss[1] 23 | r.Date = ss[2] 24 | return nil 25 | } 26 | 27 | func (r *tableRow) fromVersion(ver string) error { 28 | // syncthing v1.23.1-rc.1 "Fermium Flea" (go1.19.5 darwin-arm64) teamcity@build.syncthing.net 2023-01-12 03:30:17 UTC [stnoupgrade] 29 | exp := regexp.MustCompile(`syncthing (v\d+\.\d+\.\d+).*(go\d+\.\d+(?:\.\d+)?).*(\d{4}-\d{2}-\d{2}) `) 30 | m := exp.FindStringSubmatch(ver) 31 | if len(m) < 3 { 32 | return fmt.Errorf("failed to parse version") 33 | } 34 | r.Version = m[1] 35 | r.Runtime = m[2] 36 | r.Date = m[3] 37 | return nil 38 | } 39 | 40 | func (r *tableRow) toStrings() []string { 41 | return []string{r.Version, r.Runtime, r.Date} 42 | } 43 | 44 | var tableHeader = []string{"Version", "Runtime", "Date"} 45 | 46 | func writeTable(w io.Writer, rows []*tableRow) error { 47 | sort.Slice(rows, func(a, b int) bool { 48 | if rows[a].Date == rows[b].Date { 49 | return rows[a].Version > rows[b].Version 50 | } 51 | return rows[a].Date > rows[b].Date 52 | }) 53 | cw := csv.NewWriter(w) 54 | if err := cw.Write(tableHeader); err != nil { 55 | return err 56 | } 57 | for _, r := range rows { 58 | if err := cw.Write(r.toStrings()); err != nil { 59 | return err 60 | } 61 | } 62 | cw.Flush() 63 | return cw.Error() 64 | } 65 | 66 | func readTable(r io.Reader) ([]*tableRow, error) { 67 | cr := csv.NewReader(r) 68 | var rows []*tableRow 69 | for { 70 | ss, err := cr.Read() 71 | if err == io.EOF { 72 | break 73 | } 74 | if err != nil { 75 | return nil, err 76 | } 77 | if len(ss) == 0 { 78 | continue 79 | } 80 | if ss[0] == tableHeader[0] { 81 | continue 82 | } 83 | var row tableRow 84 | if err := row.fromStrings(ss); err != nil { 85 | return nil, err 86 | } 87 | rows = append(rows, &row) 88 | } 89 | return rows, nil 90 | } 91 | -------------------------------------------------------------------------------- /_script/lsver.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "encoding/json" 5 | "log" 6 | "os" 7 | "regexp" 8 | "sort" 9 | "strconv" 10 | "strings" 11 | ) 12 | 13 | func main() { 14 | dir := os.Args[1] 15 | if err := lsver(dir); err != nil { 16 | log.Fatalln("ls:", err) 17 | } 18 | } 19 | 20 | func lsver(dir string) error { 21 | entries, err := os.ReadDir(dir) 22 | if err != nil { 23 | return err 24 | } 25 | 26 | versionExp := regexp.MustCompile(`^v[0-9]+\.[0-9]+\.[0-9]+$`) 27 | 28 | names := make([]string, 0, len(entries)) 29 | for _, entry := range entries { 30 | if versionExp.MatchString(entry.Name()) { 31 | names = append(names, entry.Name()) 32 | } 33 | } 34 | sort.Slice(names, func(a, b int) bool { 35 | return compareVersions(names[a], names[b]) < 0 36 | }) 37 | 38 | enc := json.NewEncoder(os.Stdout) 39 | return enc.Encode(map[string][]string{"entries": names}) 40 | } 41 | 42 | func compareVersions(a, b string) int { 43 | a = strings.TrimPrefix(a, "v") 44 | b = strings.TrimPrefix(b, "v") 45 | as := strings.Split(a, ".") 46 | bs := strings.Split(b, ".") 47 | an := make([]int, len(as)) 48 | bn := make([]int, len(bs)) 49 | for i, v := range as { 50 | an[i], _ = strconv.Atoi(v) 51 | } 52 | for i, v := range bs { 53 | bn[i], _ = strconv.Atoi(v) 54 | } 55 | for i := 0; i < len(an) && i < len(bn); i++ { 56 | switch { 57 | case an[i] < bn[i]: 58 | return -1 59 | case an[i] > bn[i]: 60 | return 1 61 | } 62 | } 63 | switch { 64 | case len(an) < len(bn): 65 | return -1 66 | case len(an) > len(bn): 67 | return 1 68 | } 69 | return 0 70 | } 71 | -------------------------------------------------------------------------------- /_static/custom.css: -------------------------------------------------------------------------------- 1 | @media screen and (max-width: 875px) { 2 | div.body { 3 | /* prevent horizontal overflowing on mobile */ 4 | min-width: inherit; 5 | } 6 | } 7 | 8 | p.logo { 9 | text-align: left; 10 | } 11 | img.logo { 12 | height: 66px; 13 | margin-bottom: 20px; 14 | } 15 | 16 | img.border { 17 | border: 1px solid #888; 18 | border-radius: 5px; 19 | } 20 | 21 | div#searchbox, 22 | div.sphinxsidebar h3.donation { 23 | margin-top: 20px; 24 | } 25 | 26 | div.body { 27 | /* margin here is same as height + margin of logo */ 28 | margin-top: 86px; 29 | } 30 | 31 | div.footer-body { 32 | /* hack for the "edit on github" container below the body */ 33 | margin-top: 30px; 34 | margin-bottom: 20px; 35 | text-align: center; 36 | } 37 | 38 | li.toctree-l1 { 39 | margin-top: 1em; 40 | } 41 | 42 | /* Add a strike-through class. */ 43 | .strike { 44 | text-decoration: line-through; 45 | } 46 | 47 | div.note { 48 | background-color: #ffc; 49 | } 50 | div.admonition { 51 | /* reduce default padding a bit because it's asymmetrical and ugly */ 52 | padding: 5px; 53 | } 54 | div.admonition p.admonition-title { 55 | font-size: inherit; 56 | font-weight: bold; 57 | } 58 | p.admonition-title:after { 59 | content: none; 60 | } 61 | 62 | /* Override Alabaster theme defaults to add space between list items. */ 63 | li > p:last-child { 64 | margin-bottom: 1em; 65 | } 66 | li:last-child > p:last-child { 67 | margin-bottom: 0; 68 | } 69 | 70 | /* Overrides for built in contents directive */ 71 | div.contents { 72 | margin: inherit; 73 | padding: inherit; 74 | background-color: inherit; 75 | border: inherit; 76 | } 77 | div.contents li > p:last-child { 78 | margin-bottom: inherit; 79 | } 80 | 81 | pre { 82 | padding: 8px; 83 | } 84 | 85 | /* Make terms bold in definition lists for better visibility, e.g. in 86 | users/config. */ 87 | dt { 88 | font-weight: bold; 89 | } 90 | 91 | /* Extra padding after configuration options in e.g. in users/config. */ 92 | dl.option { 93 | margin-bottom: 1em; 94 | } 95 | -------------------------------------------------------------------------------- /_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/syncthing/docs/d932ef5d8e87dd649764c9abc51eaef4d7421a67/_static/favicon.png -------------------------------------------------------------------------------- /_static/logo-horizontal.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 16 | 17 | 18 | 19 | 21 | 22 | 23 | 25 | 26 | 28 | 29 | 30 | 31 | 32 | 33 | 36 | 38 | 40 | 42 | 44 | 46 | 47 | 49 | 53 | 54 | 55 | -------------------------------------------------------------------------------- /_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 | -------------------------------------------------------------------------------- /_templates/version.html: -------------------------------------------------------------------------------- 1 |

Written for {{ version }}

2 |
3 | -------------------------------------------------------------------------------- /advanced/device-allowednetworks.rst: -------------------------------------------------------------------------------- 1 | .. _allowed-networks: 2 | 3 | allowedNetworks 4 | =============== 5 | 6 | ``allowedNetworks`` is an advanced device setting that affects connection 7 | handling. The default is for this setting to be empty, indicating that there 8 | is no restriction on the allowed networks for a device. 9 | 10 | By setting this to a comma separated list of networks, connections to the 11 | given device will be limited to those networks. The networks refer to the 12 | address of the *remote* device, not the network that the local device is 13 | presently on. 14 | 15 | Given a value of ``192.168.0.0/16, 172.16.0.0/12, 2001:db8::/32`` Syncthing will: 16 | 17 | - Allow connections from the device from addresses in the specified 18 | networks. 19 | 20 | - Reject connections from the device from addresses outside the specified 21 | networks. 22 | 23 | - Attempt connections to addresses in the specified networks (manually 24 | configured or discovered). 25 | 26 | - Not attempt connections to addresses outside the specified networks, 27 | regardless of whether manually configured or automatically discovered. 28 | 29 | Allowed values are numeric IPv4 and IPv6 prefixes in CIDR format, as in the 30 | example. Hostnames, netmasks in octet format, etc., are not supported. 31 | 32 | If the value is not empty it will be enforced for all connections. 33 | Mentioning only an IPv4 prefix will thus deny all IPv6 connections and vice 34 | versa. Use ``0.0.0.0/0`` (IPv4) or ``::/0`` (IPv6) to allow all connections on 35 | that address family. 36 | -------------------------------------------------------------------------------- /advanced/device-numconnections.rst: -------------------------------------------------------------------------------- 1 | numConnections 2 | ============== 3 | 4 | .. versionadded:: 1.25.0 5 | 6 | ``numConnections`` is a device setting that affects connection handling. A 7 | zero value means to use the Syncthing default. As of version 1.25.0 the 8 | default is to use one connection, like earlier versions of Syncthing. This 9 | may change in the future. 10 | 11 | Multiple connections will be maintained to the device if you set this to a 12 | value greater than one. Multiple connections can yield improved performance 13 | by load-balancing traffic over multiple physical links or in other 14 | scenarios. 15 | 16 | A simple form of negotiation is used to decide how many connections to use 17 | between a device pair. It goes like this: 18 | 19 | - If either side is configured to use a single connection, then a single 20 | connection is used. Since the default is to use a single connection this 21 | means that to use more than one connection both sides must be configured 22 | to do so. 23 | - If both sides are configured to use multiple connections, then the larger 24 | of the two values is used. That is, if one side is configured to use three 25 | connections and the other is set to use eight connections, eight 26 | connections will be used. 27 | - A maximum of 128 connections will be used under all circumstances. It is 28 | likely that the "return on investment" in further connections is 29 | negligible above about 10 to 20 connections, so this limit should be 30 | sufficient for all realistic use cases. 31 | 32 | .. note:: 33 | 34 | Additional connections are established over time, roughly at the rate of 35 | one per minute when Syncthing is in a steady state, so you may not see 36 | the expected number of connections immediately after changing this 37 | setting. 38 | 39 | Load Balancing 40 | -------------- 41 | 42 | When there are multiple connections between two devices, one connection is 43 | dedicated to metadata transmission: index updates, changes to folder pause 44 | status, etc. Requests and responses are sent over the other connections 45 | randomly. The number of connections in the GUI is represented as `1 + n` for 46 | this reason, e.g. if you configure four connections, the GUI will show `1 + 47 | 3` to indicate one metadata connection and three data connections. 48 | 49 | Rate Limiting 50 | ------------- 51 | 52 | Device rate limiting applies to the sum of traffic on all connections, 53 | regardless of the number of connections. The limit is not per connection. 54 | 55 | Connection Types 56 | ---------------- 57 | 58 | Both TCP and QUIC connections are supported for multiple connections. 59 | Syncthing will, however, only keep connections with the best priority; by 60 | default, TCP has better priority than QUIC, so establishing a TCP connection 61 | will cause existing QUIC connections to be closed. Connection priorities can 62 | be configured. 63 | 64 | When connected via a relay, only one connection is normally established. 65 | However, with some lucky timing, e.g. when attempting to reconnect after losing 66 | a connection, it is also possible to establish one relay connection in each 67 | direction, if the two devices are listening on different relays. In such a case, 68 | the GUI will show `1 + 1` connections. 69 | -------------------------------------------------------------------------------- /advanced/folder-autonormalize.rst: -------------------------------------------------------------------------------- 1 | autoNormalize 2 | ============= 3 | 4 | ``autoNormalize`` is an advanced folder setting that affects the handling of 5 | files with incorrect UTF-8 normalization in their names. When set, such files 6 | are renamed to the correctly normalized form during scanning. 7 | 8 | .. note:: This option should normally be set to ``true``, which is the default. 9 | 10 | Background 11 | ---------- 12 | 13 | File names can be represented in many different ways. Some systems use an 14 | extended ASCII character set like ISO-8859-1 (Latin), others may use a 15 | different encoding to represent Chinese, Russian and so on. The modern 16 | standard is to use Unicode in UTF-8 encoding, even when the file system itself 17 | doesn't dictate a format, such as is the case on most Unix-like systems. 18 | Syncthing will refuse to synchronize files with names not encoded in UTF-8. 19 | 20 | However, there are different ways of encoding the same character even within 21 | UTF-8. These are called normalization forms and differ primarily between Mac 22 | and everything else. Differences in normalization form means that you could on 23 | some systems have three (or more) files all called ``räksmörgås.txt``, 24 | ``räksmörgås.txt``, and ``räksmörgås.txt`` -- those are the same characters, 25 | but expressed in different ways. More commonly an issue arises when files are 26 | copied from a system that uses one normalization form (Mac) to a system using 27 | another normalization form (Windows) without translation; say, via a USB 28 | stick. 29 | 30 | To avoid such issues, Syncthing automatically corrects normalization errors 31 | when it runs into them, unless this option is set to ``false``. 32 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /advanced/folder-copyrangemethod.rst: -------------------------------------------------------------------------------- 1 | .. _folder-copyRangeMethod: 2 | 3 | copyRangeMethod 4 | =============== 5 | 6 | .. versionadded:: 1.8.0 7 | 8 | Provides a choice of method for copying data between files. This can be used 9 | to optimise copies on network filesystems, improve speed of large copies or 10 | clone the data using copy-on-write functionality if the underlying 11 | filesystem supports it. 12 | 13 | The following values are accepted: 14 | 15 | ``standard`` (default) 16 | Reads the data from source file into application memory, writes the 17 | data from application memory into the destination file. (This is the 18 | method used by Syncthing prior to this option being introduced.) 19 | 20 | *Available on: All platforms* 21 | 22 | ``copy_file_range`` 23 | Uses the Linux ``copy_file_range`` syscall which, if the underlying 24 | filesystem supports it, uses copy-on-write semantics to clone the 25 | data. Introduced in Linux 4.5 and tested on XFS and BTRFS. Some 26 | network filesystems might use this to perform server-side copies. 27 | 28 | | *Tested on: BTRFS, EXT4, XFS, ZFS* 29 | | *Available on: Linux* 30 | 31 | ``ioctl`` 32 | Uses the ``ioctl`` syscall with ``FICLONERANGE`` option which, if 33 | the underlying filesystem supports it, uses copy-on-write semantics 34 | to clone the data. Officially introduced in Linux 4.5, but was 35 | previously known as ``BTRFS_IOC_CLONE_RANGE``, which was used to 36 | provide copy-on-write semantics to BTRFS filesystems since Linux 37 | 2.6.29. Some network filesystems might use this to perform 38 | server-side copies. Will fail if not supported by the underlying 39 | filesystem. 40 | 41 | | *Tested on: BTRFS* 42 | | *Available on: Linux* 43 | 44 | ``sendfile`` 45 | Uses the ``sendfile`` syscall which performs in-kernel copy, 46 | avoiding having to copy the data into application memory. 47 | 48 | | *Tested on: BTRFS, XFS, EXT4* 49 | | *Available on: Linux, Solaris* 50 | 51 | ``duplicate_extents`` 52 | Uses Windows Block Cloning via ``FSCTL_DUPLICATE_EXTENTS_TO_FILE``, 53 | which provides copy-on-write semantics to clone the data. Requires 54 | Windows 10 v1607 / Windows Server 2016 or later, and a compatible 55 | filesystem (ReFS, SMB 3.1.1, CsvFS). Will fail if not supported 56 | by the underlying filesystem. 57 | 58 | | *Tested on: ReFS* 59 | | *Available on: Windows* 60 | 61 | ``all`` 62 | Tries all of the copy methods in the following order: ``ioctl``, 63 | ``copy_file_range``, ``sendfile``, ``duplicate_extents``, 64 | ``standard``. 65 | 66 | *Available on: All platforms* 67 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /advanced/folder-filesystem-type.rst: -------------------------------------------------------------------------------- 1 | filesystemType 2 | ============== 3 | 4 | Syncthing has an internal abstraction for file system access with different 5 | available implementations. They can be configured per folder, with the 6 | following possible values: 7 | 8 | ``basic`` (default) 9 | To be used if the folder is intended to store real data. Do not change 10 | unless you are a developer and want to test things. 11 | 12 | ``fake`` 13 | A fake file system type to be used for testing, e.g. when you want to create 14 | a folder with a :abbr:`TB (Terabyte)` or more of random files that can be 15 | synced somewhere, or an infinitely large folder to sync files into. 16 | 17 | It has pseudorandom properties, i.e. data read from one fakefs can be 18 | written into another fakefs, read back, and it will look consistent, without 19 | any real data actually being stored. 20 | 21 | To create an empty file system, use 22 | 23 | .. code-block:: 24 | 25 | 26 | fake 27 | 28 | You can also specify that it should be prefilled with files, 29 | 30 | .. code-block:: 31 | 32 | 33 | fake 34 | 35 | which will create a file system filled with 2 :abbr:`TB (Terabyte)` of 36 | random data that can be scanned and synced. The prefilled data is based on a 37 | deterministic seed, so you can index it, restart Syncthing, and the index 38 | will still be correct for all the stored data. 39 | 40 | Check the source of `fakefs.go 41 | `_ for 42 | more options and details. 43 | -------------------------------------------------------------------------------- /advanced/folder-ignoredelete.rst: -------------------------------------------------------------------------------- 1 | ignoreDelete 2 | ============ 3 | 4 | ``ignoreDelete`` is an advanced folder setting that affects the handling of 5 | incoming index updates. When set, incoming updates with the delete flag set 6 | are ignored. 7 | 8 | .. warning:: This option should normally be set to ``false``. Changing 9 | it is not recommended, unless you are a power user and know exactly 10 | what you are doing. If you still intend to enable this option, 11 | please read the explanation below very thoroughly before doing so. 12 | 13 | Example Scenario 14 | ---------------- 15 | 16 | Assume two devices, "Alice" and "Bob", are sharing a folder. Bob has set 17 | ``ignoreDelete`` to ``true``. 18 | 19 | New and updated files are synchronized as usual between Alice and Bob. When 20 | Bob deletes a file, it is deleted for Alice as well. When Alice deletes a 21 | file, Bob ignores that update and does not delete the file. 22 | 23 | In this state, Bob is fully up to date from his own point of view, as is Alice 24 | from her own point of view. 25 | 26 | However from the point of view of Alice, who deleted a file and propagated the 27 | update, Bob is now out of date because he has yet to remove the file that was 28 | deleted by Alice. 29 | 30 | From the point of view of Bob, who ignored the delete entry from Alice, Alice 31 | is now out of date because she is missing the file that was deleted. 32 | 33 | .. note:: 34 | Bob may continue to see Alice as up to date until the next time 35 | Syncthing is restarted on his device. 36 | 37 | Should Bob modify any of the files that Alice has deleted, the update will be 38 | sent to Alice and Alice will download the now updated file. 39 | 40 | .. note:: 41 | Ignoring deletes in both directions between two devices can be a 42 | confusing configuration. 43 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /advanced/folder-sync-ownership.rst: -------------------------------------------------------------------------------- 1 | syncOwnership 2 | ============= 3 | 4 | .. versionadded:: 1.21.0 5 | 6 | When enabled, Syncthing attempts to also synchronise ownership between 7 | devices. Ownership is divided into two kinds: 8 | 9 | - "Unix" ownership, which is the Unix style UID and GID, and 10 | - "Windows" ownership, which the Windows file ownership concept. 11 | 12 | The two are not mixed -- that is, ownership information is not synchronised 13 | between POSIX and Windows systems, only POSIX-to-POSIX and 14 | Windows-to-Windows. Nonetheless Syncthing attempts to leave unknown 15 | ownership data intact: POSIX systems will not overwrite Windows ownership 16 | data but pass it on unmodified, and vice versa. 17 | 18 | .. note:: 19 | In order for there to be ownership information to apply, the peer device 20 | must have either ``syncOwnership`` or :doc:`folder-send-ownership` enabled. 21 | 22 | Unix implementation 23 | ------------------- 24 | 25 | Syncthing records both the numerical UID and GID for a file and the 26 | corresponding user and group names, when they are known. When applying 27 | ownership Syncthing will first attempt to look up a local user or group with 28 | the given name, and if that fails it will fall back to the numerical UID and 29 | GID. 30 | 31 | Elevated permissions 32 | ~~~~~~~~~~~~~~~~~~~~ 33 | 34 | Syncthing, when running as a normal user account, doesn't have permission to 35 | alter file ownership. There are several reasonable ways of running Syncthing 36 | with elevated permissions to enable ownership sync: 37 | 38 | - As root, in a Docker container, with the synced data mounted as a 39 | volume. 40 | - As a normal user, with extra capabilities granted to the executable. 41 | 42 | To grant extra capabilities, the following steps must be taken: 43 | 44 | - The executable must be owned by root and not writable by normal users. 45 | - The executable must be granted the CHOWN and FOWNER capabilities. The 46 | CHOWN capability is required to be able to change ownership on the file. 47 | However, once that has been done Syncthing may no longer have permission 48 | to act on the file in other ways while running as anonymous user. The 49 | FOWNER capability overrides this. 50 | 51 | Example commands of setting Syncthing up in this manner:: 52 | 53 | % sudo chown root /usr/local/bin/syncthing 54 | % sudo chmod 755 /usr/local/bin/syncthing 55 | % sudo setcap CAP_CHOWN,CAP_FOWNER=pe /usr/local/bin/syncthing 56 | 57 | .. note:: Note that automated upgrades cannot be used with Syncthing elevated 58 | in this manner as any automated upgrade would undo the capabilities granted. 59 | 60 | When using systemd to start the service automatically, the capabilities can be 61 | set in the unit file instead of touching the executable, see 62 | :ref:`autostart-systemd-permissions`. 63 | 64 | Windows implementation 65 | ---------------------- 66 | 67 | Syncthing records the account name of the owner, and whether it is a group 68 | or user. On the receiving side a user or group with the corresponding name 69 | is looked up and set as the owner. 70 | 71 | On Windows, syncing ownership has a fairly significant performance impact on 72 | scan times. 73 | 74 | .. seealso:: :doc:`folder-send-ownership` 75 | -------------------------------------------------------------------------------- /advanced/folder-sync-xattrs.rst: -------------------------------------------------------------------------------- 1 | syncXattrs 2 | ========== 3 | 4 | .. versionadded:: 1.22.0 5 | 6 | When enabled, Syncthing attempts to also synchronize filesystem extended 7 | attributes between devices. 8 | 9 | Extended attributes are recorded and synced on a per-operating system basis. 10 | That is, if a file has an extended attribute on one operating system, it 11 | will not be synced to another operating system. For example, if a file has 12 | an extended attribute on Linux, it will not be synced to macOS. This is 13 | because the extended attribute names, values and interpretation is different 14 | on different operating systems. 15 | 16 | Syncthing will attempt to preserve information about foreign extended 17 | attributes when a file is manipulated. That is, if a file is modified on 18 | Linux it's expected that macOS extended attributes will be preserved in the 19 | metadata and hence applied again on macOS. This is not always possible - for 20 | example if a file is *moved* on Linux, the macOS extended attributes for 21 | that file will be lost. 22 | 23 | As of Syncthing 1.22.0 the supported operating systems are Linux, macOS, 24 | FreeBSD and NetBSD. 25 | 26 | .. note:: 27 | In order for there to be extended attributes to apply, the peer device 28 | must have either ``syncXattrs`` or :doc:`folder-send-xattrs` enabled. 29 | 30 | Elevated permissions 31 | ~~~~~~~~~~~~~~~~~~~~ 32 | 33 | Syncthing, when running as a normal user account, may not have permission to 34 | access or manipulate all extended attributes. See 35 | :doc:`folder-sync-ownership` for more information of granting appropriate 36 | permissions. 37 | 38 | .. seealso:: :doc:`folder-send-xattrs` 39 | -------------------------------------------------------------------------------- /advanced/folder-uselargeblocks.rst: -------------------------------------------------------------------------------- 1 | .. versionadded:: 1.2.0 2 | 3 | As of Syncthing 1.2.0 large blocks are always enabled and this configuration 4 | option has been removed. 5 | 6 | .. versionadded:: 1.1.0 7 | 8 | Syncthing version 1.1.0 and newer have large blocks enabled by default for 9 | new folders. 10 | 11 | .. versionadded:: 0.14.48 12 | 13 | Large blocks can be enabled in Syncthing version 0.14.48 and newer. 14 | 15 | useLargeBlocks 16 | ============== 17 | 18 | ``useLargeBlocks`` is an advanced folder setting that affects the handling 19 | of blocks for files larger than 256 MiB. When enabled, the file will be 20 | indexed and transferred using blocks larger than the standard 128 KiB. This 21 | results in a smaller block list and thus lower overhead. The larger block 22 | sizes are powers of two from 128 KiB up to 16 MiB. Syncthing will 23 | attempt to select a block size to keep the number of blocks in a file 24 | between 1000 and 2000, using the largest and smallest block size accordingly 25 | at either extreme. 26 | 27 | Compatibility 28 | ------------- 29 | 30 | Syncthing version 0.14.46 and newer will accept and handle files with large 31 | blocks, regardless of whether large blocks are enabled on that device. 32 | 33 | Syncthing version 0.14.45 and older will initially appear to accept files 34 | scanned with large blocks, but will later panic during some internal file 35 | operations. Do not enable large blocks in clusters with devices still on 36 | v0.14.45 or older. 37 | 38 | When large blocks are *not* enabled, local changes to any given file are 39 | indexed in standard (small) blocks - regardless of whether other devices are 40 | using large blocks for the same folder. 41 | 42 | When two devices do not agree on the desired block size for a file, the 43 | entire file must be transferred instead of only the changed blocks. To avoid 44 | frequent block size changes for files straddling a threshold boundary there 45 | is a certain elasticity or hysteresis built into the system. The block size 46 | of an existing file is only changed when the difference in block size 47 | exceeds one level, i.e., from 256 KiB to 1 MiB, but not from 256 KiB to 512 48 | KiB. 49 | 50 | -------------------------------------------------------------------------------- /advanced/folder-xattr-filter.rst: -------------------------------------------------------------------------------- 1 | xattrFilter 2 | =========== 3 | 4 | The extended attributes filter is used to manage which attributes should 5 | be synced and which ones should not be. 6 | 7 | When the filter shows 8 | --------------------- 9 | 10 | The ability to manipulate the extended attributes filter in the advanced 11 | panel of a folder configuration only appears after enabling the 12 | ``Sync Extended Attributes`` option. 13 | 14 | Default Behaviour 15 | ----------------- 16 | 17 | When setting filters it's good to understand the default behaviour, this 18 | default behaviour changes once you add rules. When no rules are present 19 | everything is permitted. However, once a single rule is set this default 20 | behaviour flips to denying everything that does not match a rule. 21 | 22 | These rules work on a 'first-match'-principle. This means that once it 23 | matches any rule (going from top to bottom), that rule is applied and the 24 | other rules won't be checked further. When no rules result in a match, 25 | then the default is deny unless stated otherwise (or when no rules are 26 | present at all. In that case the default is to permit everything). 27 | 28 | To override this default behaviour when adding rules, you should add a 29 | rule in the bottom which permits everything (*). 30 | 31 | The GUI reminds you of the default behaviour when you don't have an any-rule 32 | set. 33 | 34 | Setting rules 35 | ------------- 36 | 37 | To set a rule press the button 'Add new rule' to append an empty rule to the 38 | list. The check-box indicates whether to permit (checked) or deny (unchecked) 39 | the matching pattern and the text-field is the pattern to be matched. Adding 40 | a rule while already having a wild-card (*) added will result in the new rule 41 | being added as second-last item. When saving the configuration, empty rules 42 | will be removed. Closing the window without pressing save will cause your 43 | made changes to be reset. 44 | 45 | Be aware that the rules aren't being validated on correctness beyond the point 46 | of cleaning out empty rules. 47 | 48 | Removing rules 49 | -------------- 50 | 51 | To remove a rule simply press on the trash bin on the right hand side of the 52 | rule that you want to remove. 53 | 54 | .. seealso:: :doc:`folder-send-xattrs`, :doc:`folder-sync-xattrs` 55 | -------------------------------------------------------------------------------- /advanced/option-connection-limits.rst: -------------------------------------------------------------------------------- 1 | Connection Limits 2 | ================= 3 | 4 | .. versionadded:: 1.13.0 5 | 6 | Connection limits can be set to prevent Syncthing from establishing 7 | connections under some circumstances. For the most part you want Syncthing 8 | to connect to all its configured peers, thus you should usually *not* use 9 | this option. Connection limits are useful in specific scenarios concerning 10 | large deployments only, and care must be taken when selecting limits to work 11 | in that scenario. The general recommendation is to leave these settings at 12 | their default of zero, meaning unlimited. 13 | 14 | Mechanism 15 | --------- 16 | 17 | There are two limits, called ``enough`` and ``max``. In short, once there 18 | are *enough* connections Syncthing will stop trying to connect to other 19 | devices; when the *max* is reached Syncthing will also refuse incoming 20 | connections. 21 | 22 | Either can be set individually, leaving the other at zero, or both can be 23 | set. When setting both values, ``enough`` should be smaller than ``max`` or 24 | it will have no effect (Syncthing will also stop connecting outwards once 25 | ``max`` is reached). 26 | 27 | Scenarios 28 | --------- 29 | 30 | Load Balancing 31 | ~~~~~~~~~~~~~~ 32 | 33 | Consider a setup with a handful "servers" and many "clients". The servers 34 | are fully connected amongst each other and essentially equivalent. The 35 | clients should connect to one server each in order to receive updates. One 36 | way of accomplishing this is to divide the clients into (static) groups and 37 | configure each group to connect to a specific server. 38 | 39 | Another way is using connection limits, configuring each client identically 40 | for all servers but setting the ``max`` connection limit to ``1``. This has 41 | the advantage that if one server becomes unavailable the clients will 42 | migrate to other servers. 43 | 44 | When establishing new connections Syncthing will preferentially connect to 45 | devices it was recently connected to, thus clients will usually stay on the 46 | same server over a restart. 47 | -------------------------------------------------------------------------------- /advanced/option-database-tuning.rst: -------------------------------------------------------------------------------- 1 | .. _option-databaseTuning: 2 | 3 | databaseTuning 4 | ============== 5 | 6 | .. versionadded:: 1.3.0 7 | 8 | The ``databaseTuning`` option controls how Syncthing uses the backend 9 | key-value database that stores the index data and other persistent data 10 | Syncthing needs. In most cases this database is fairly small (hundred 11 | megabytes or less) and the default tuning is optimized for this. However in 12 | cases with large folders or many devices the database may grow, and updates 13 | may be more frequent. In these cases it's better to use larger buffers, 14 | allow more memory to be used for cache, allow a larger amount of overhead on 15 | disk in order to improve compaction performance, and so on. 16 | 17 | The ``databaseTuning`` option can have one of three values: 18 | 19 | - ``small``: This is the old set of tuning parameters, recommended for small 20 | databases. 21 | - ``large``: This is a new set of tuning parameters, recommended for large 22 | databases. 23 | 24 | - ``auto``: Syncthing will automatically use either the large or small 25 | tuning parameters depending on the database size on disk. A database that is 26 | 200 MiB or more in size is considered "large" for the purposes of this 27 | option. 28 | 29 | The default value is ``auto``. 30 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /dev/crashrep.rst: -------------------------------------------------------------------------------- 1 | .. _crashrep-dev: 2 | 3 | Automatic Crash Reporting for Developers 4 | ======================================== 5 | 6 | Collecting and Sending 7 | ---------------------- 8 | 9 | Syncthing runs with one *monitor process* and one *main 10 | process*. The main process is the thing that is really "Syncthing". The 11 | monitor process is responsible for reading the console output from the main 12 | process, restarting it if it exits, and reporting any crashes of the main 13 | process -- when it's allowed to do so. 14 | 15 | When the monitor process detects a crash it creates a file 16 | ``panic-$timestamp.log`` in the config directory and attempts to upload it 17 | to the crash reporting server -- if crash reporting is enabled. When a log 18 | has been successfully reported it is renamed with the double file ending 19 | ``.reported.log``. Old crash logs are automatically removed after a while, 20 | reported or not. 21 | 22 | Report Format 23 | ------------- 24 | 25 | A crash report is fundamentally a blob of plain UTF-8 text. It has a loose 26 | format, documented below. A report implicitly has a "report ID" which is the 27 | SHA-256 hash of the entire report text, in hex format. 28 | 29 | The report consists of the following: 30 | 31 | - One line containing the Syncthing version, exactly as reported by 32 | ``syncthing --version``. A leading timestamp and log level *may* be 33 | present but is ignored. 34 | 35 | - Zero or more lines of plaintext data that is for human consumption only. 36 | The reports that Syncthing itself sends will have zero lines here, but one 37 | could include a report of what happened, log extracts, etc. here barring 38 | any privacy issues on the sender's behalf. 39 | 40 | - A line beginning with the words ``Panic at`` followed by a timestamp in 41 | RFC3339 format. 42 | 43 | - The panic backtrace as printed / formatted by the Go runtime. 44 | 45 | Here is an example of a well formed but short report:: 46 | 47 | 07:48:24 INFO: syncthing v1.1.4 "Erbium Earthworm" (go1.12.5 darwin-amd64) jb@kvin.kastelo.net 2019-05-21 20:36:38 UTC 48 | Panic at 2019-05-22T07:48:25+02:00 49 | panic: interface conversion: *pfilter.FilteredConn is not net.Conn: missing method Read 50 | 51 | goroutine 106 [running]: 52 | github.com/syncthing/syncthing/lib/connections.(*quicListener).Serve(0xc000158000) 53 | /Users/jb/dev/github.com/syncthing/syncthing/lib/connections/quic_listen.go:74 +0x41b 54 | github.com/thejerf/suture.(*Supervisor).runService.func1(0xc0001c6690, 0xc000000000, 0x54b4728, 0xc000158000) 55 | /Users/jb/go/pkg/mod/github.com/thejerf/suture@v3.0.2+incompatible/supervisor.go:600 +0x47 56 | created by github.com/thejerf/suture.(*Supervisor).runService 57 | /Users/jb/go/pkg/mod/github.com/thejerf/suture@v3.0.2+incompatible/supervisor.go:588 +0x5b 58 | 59 | Wire Protocol 60 | ------------- 61 | 62 | To upload a crash report we need three things: 63 | 64 | - The data comprising the report as above, 65 | - the SHA-256 hash of the report data, making up the report ID, and 66 | - the base URL to send the report to. 67 | 68 | The report URL is constructed by adding the report ID to the base URL. The 69 | default base URL of ``https://crash.syncthing.net/newcrash/`` and the report 70 | ID ``abcd1234`` results in the URL 71 | ``https://crash.syncthing.net/newcrash/abcd1234``. 72 | 73 | First a ``HEAD`` request is performed on the report URL. If this request 74 | returns successfully (``200 OK``) it means the server already has the report 75 | ID in question. We do not need to upload it. 76 | 77 | If the HEAD request returns ``404 Not Found`` or another error we can 78 | attempt to upload the report. This is done by a ``PUT`` request to the same 79 | URL with the report data as the body. 80 | -------------------------------------------------------------------------------- /dev/debugging.rst: -------------------------------------------------------------------------------- 1 | .. _debugging: 2 | 3 | Debugging Syncthing 4 | =================== 5 | 6 | There's a lot that happens behind the covers, and Syncthing is generally 7 | quite silent about it. A number of environment variables can be used to 8 | set the logging to verbose for various parts of the program, and to 9 | enable profiling. 10 | 11 | Enabling any of the STTRACE facilities will also change the log format to 12 | include microsecond timestamps and file names plus line numbers. This 13 | can be used to enable this extra information on the normal logging 14 | level, without enabling any debugging: ``STTRACE=somethingnonexistent`` 15 | for example. 16 | 17 | Under Unix (including Mac) the easiest way to run Syncthing with an 18 | environment variable set is to prepend the variable to the command line. 19 | I.e: 20 | 21 | ``$ STTRACE=model syncthing`` 22 | 23 | On windows, it needs to be set prior to running Syncthing. 24 | 25 | :: 26 | 27 | C:\> set STTRACE=model 28 | C:\> syncthing 29 | 30 | Environment Variables 31 | --------------------- 32 | 33 | .. include:: ../includes/env-vars.rst 34 | 35 | Stepping with breakpoints 36 | ------------------------- 37 | 38 | If you like to step through the running program, build a non-optimized binary and run with https://github.com/derekparker/delve. 39 | 40 | Follow these steps: 41 | 42 | :: 43 | 44 | $ go run build.go -debug-binary build 45 | $ STNODEFAULTFOLDER=1 STNOUPGRADE=1 STNORESTART=1 dlv --listen=:2345 --headless=true --api-version=2 exec ./syncthing -- --home=./_test_config --no-browser 46 | 47 | For installing and using delve itself see: 48 | 49 | - VSCode (Microsoft): https://github.com/golang/vscode-go/blob/master/docs/debugging.md 50 | 51 | - GoLand (JetBrains): create remote run configuration and follow the two steps displayed 52 | -------------------------------------------------------------------------------- /dev/events.rst: -------------------------------------------------------------------------------- 1 | Event API 2 | ========= 3 | 4 | Description 5 | ----------- 6 | 7 | Syncthing provides a simple long polling interface for exposing events from the 8 | core utility towards a GUI. To receive events, see :doc:`/rest/events-get`. 9 | 10 | Event Structure 11 | --------------- 12 | 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 present, 27 | though ``data`` may be ``null``. 28 | 29 | id 30 | A unique ID for this event on the events API. It always increases by 1: the first 31 | event generated has id ``1``, the next has id ``2`` etc. If this increases by 32 | more than 1, then one or more events have been skipped by the events API. 33 | globalID 34 | A global ID for this event, across the events API, the audit log, and any other 35 | sources. It may increase by more than 1, but it will always be greater 36 | than or equal to the id. 37 | time 38 | The time the event was generated. 39 | type 40 | Indicates the type of (i.e. reason for) the event and is one of the event 41 | types below. 42 | data 43 | An object containing optional extra information; the exact structure is 44 | determined by the event type. 45 | 46 | .. _event-types: 47 | 48 | Event Types 49 | ----------- 50 | 51 | .. toctree:: 52 | :maxdepth: 2 53 | :glob: 54 | 55 | ../events/* 56 | -------------------------------------------------------------------------------- /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 ``