mirror/syncthing
1
0
Fork 0
mirror of https://github.com/syncthing/syncthing.git synced 2026-04-12 02:18:07 -04:00
Code Issues Packages Projects Releases Wiki Activity

Initial

Browse Source
This commit is contained in:
Jakob Borg
2015-05-28 12:40:43 +02:00
commit fd7fe795ad
92 changed files with 4050 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
_build/

85
.ropeproject/config.py Normal file
View File

@@ -0,0 +1,85 @@
# The default ``config.py``
def set_prefs(prefs):
"""This function is called before opening the project"""
# Specify which files and folders to ignore in the project.
# Changes to ignored resources are not added to the history and
# VCSs. Also they are not returned in `Project.get_files()`.
# Note that ``?`` and ``*`` match all characters but slashes.
# '*.pyc': matches 'test.pyc' and 'pkg/test.pyc'
# 'mod*.pyc': matches 'test/mod1.pyc' but not 'mod/1.pyc'
# '.svn': matches 'pkg/.svn' and all of its children
# 'build/*.o': matches 'build/lib.o' but not 'build/sub/lib.o'
# 'build//*.o': matches 'build/lib.o' and 'build/sub/lib.o'
prefs['ignored_resources'] = ['*.pyc', '*~', '.ropeproject',
'.hg', '.svn', '_svn', '.git']
# Specifies which files should be considered python files. It is
# useful when you have scripts inside your project. Only files
# ending with ``.py`` are considered to be python files by
# default.
#prefs['python_files'] = ['*.py']
# Custom source folders: By default rope searches the project
# for finding source folders (folders that should be searched
# for finding modules). You can add paths to that list. Note
# that rope guesses project source folders correctly most of the
# time; use this if you have any problems.
# The folders should be relative to project root and use '/' for
# separating folders regardless of the platform rope is running on.
# 'src/my_source_folder' for instance.
#prefs.add('source_folders', 'src')
# You can extend python path for looking up modules
#prefs.add('python_path', '~/python/')
# Should rope save object information or not.
prefs['save_objectdb'] = True
prefs['compress_objectdb'] = False
# If `True`, rope analyzes each module when it is being saved.
prefs['automatic_soa'] = True
# The depth of calls to follow in static object analysis
prefs['soa_followed_calls'] = 0
# If `False` when running modules or unit tests "dynamic object
# analysis" is turned off. This makes them much faster.
prefs['perform_doa'] = True
# Rope can check the validity of its object DB when running.
prefs['validate_objectdb'] = True
# How many undos to hold?
prefs['max_history_items'] = 32
# Shows whether to save history across sessions.
prefs['save_history'] = True
prefs['compress_history'] = False
# Set the number spaces used for indenting. According to
# :PEP:`8`, it is best to use 4 spaces. Since most of rope's
# unit-tests use 4 spaces it is more reliable, too.
prefs['indent_size'] = 4
# Builtin and c-extension modules that are allowed to be imported
# and inspected by rope.
prefs['extension_modules'] = []
# Add all standard c-extensions to extension_modules list.
prefs['import_dynload_stdmods'] = True
# If `True` modules with syntax errors are considered to be empty.
# The default value is `False`; When `False` syntax errors raise
# `rope.base.exceptions.ModuleSyntaxError` exception.
prefs['ignore_syntax_errors'] = False
# If `True`, rope ignores unresolvable imports. Otherwise, they
# appear in the importing namespace.
prefs['ignore_bad_imports'] = False
def project_opened(project):
"""This function is called after opening the project"""
# Do whatever you like here!

5
.ropeproject/globalnames Normal file
View File

@@ -0,0 +1,5 @@
<EFBFBD>}qUconf]q(UprojectqU
source_suffixqUlatex_elementsqU copyrightqUtemplates_pathqUlatex_documentsqUsetupq Upygments_styleq
Uexclude_patternsq Utexinfo_documentsq U man_pagesq
Uhtmlhelp_basenameqUversionqU
extensionsqUhtml_static_pathqU

1
.ropeproject/history Normal file
View File

@@ -0,0 +1 @@
<EFBFBD>]q(]q]qe.

1
.ropeproject/objectdb Normal file
View File

@@ -0,0 +1 @@
<EFBFBD>}q.

177
Makefile Normal file
View File

@@ -0,0 +1,177 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Syncthing.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Syncthing.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Syncthing"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Syncthing"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

7
_static/syncthing.css Normal file
View File

@@ -0,0 +1,7 @@
p {
font-size: 14pt;
line-height: 1.25;
}
.wy-nav-content {
max-width: 1050px
}

266
conf.py Normal file
View File

@@ -0,0 +1,266 @@
# -*- coding: utf-8 -*-
#
# Syncthing documentation build configuration file, created by
# sphinx-quickstart on Thu May 28 08:33:11 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Syncthing'
copyright = u'2015, The Syncthing Authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'v0.11'
# The full version, including alpha/beta/rc tags.
release = 'v0.11'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Syncthingdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'Syncthing.tex', u'Syncthing Documentation',
u'The Syncthing Authors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'syncthing', u'Syncthing Documentation',
[u'The Syncthing Authors'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Syncthing', u'Syncthing Documentation',
u'The Syncthing Authors', 'Syncthing', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
def setup(app):
app.add_stylesheet("syncthing.css")

4
deploy.sh Executable file
View File

@@ -0,0 +1,4 @@
#!/bin/sh
git pull && rm -r _build && make html

173
dev/building.rst Normal file
View File

@@ -0,0 +1,173 @@
Building Syncthing
==================
.. note::
You probably only need to go through the build process if you are going
to do development on syncthing or if you need to do a special packaging
of it. For all other purposes we recommend using the the official binary
releases instead.
.. note::
If you're on Linux and want the quickest possible start, check out
:ref:`building-with-docker`. Otherwise follow the guide below to set up the
development environment on your computer.
Branches and Tags
-----------------
You should base your work on the ``master`` branch when doing your
development. This branch is usually what will be going into the next
release and always what pull requests should be based on.
If you're looking to build and package a release of syncthing you should
instead use the latest tag (``vX.Y.Z``) as the contents of ``master``
may be unstable and unsuitable for general consumption.
Prerequisites
-------------
- Go **1.3** or higher
- Git
If you're not a Go developer since before, the easiest way to get going
is to download the latest version of Go as instructed in
http://golang.org/doc/install and ``export GOPATH=~``.
Building (Unix)
---------------
- Install the prerequisites.
- Open a terminal.
.. code:: bash
# This should output "go version go1.3" or higher.
$ go version
# Go is particular about file locations; use this path unless you know very
# well what you're doing.
$ mkdir -p ~/src/github.com/syncthing
$ cd ~/src/github.com/syncthing
# Note that if you are building from a source code archive, you need to
# rename the directory from syncthing-XX.YY.ZZ to syncthing
$ git clone https://github.com/syncthing/syncthing
# Now we have the source. Time to build!
$ cd syncthing
# You should be inside ~/src/github.com/syncthing/syncthing right now.
$ go run build.go
Unless something goes wrong, you will have a ``syncthing`` binary built
and ready in ``~/src/github.com/syncthing/syncthing/bin``.
Building (Windows)
------------------
- Install the prerequisites.
- Open a ``cmd`` Window.
.. code:: bash
# This should output "go version go1.3" or higher.
> go version
# Go is particular about file locations; use this path unless you know very
# well what you're doing.
> mkdir c:\src\github.com\syncthing
> cd c:\src\github.com\syncthing
# Note that if you are building from a source code archive, you need to
# rename the directory from syncthing-XX.YY.ZZ to syncthing
> git clone https://github.com/syncthing/syncthing
# Now we have the source. Time to build!
> cd syncthing
> go run build.go
Unless something goes wrong, you will have a ``syncthing.exe`` binary
built and ready in ``c:\src\github.com\syncthing\syncthing\bin``.
Subcommands and Options
-----------------------
The following ``build.go`` subcommands and options exist.
- ``go run build.go install`` -- installs binaries in ``./bin``
(default command, this is what happens when build.go is run without
any commands or parameters).
- ``go run build.go build`` -- forces a rebuild of the binary to the
current directory; similar to ``install`` but slower.
- ``go run build.go clean`` -- remove build artefacts, guaranteeing a
complete rebuild. Use this when switching between normal builds and
noupgrade builds.
- ``go run build.go test`` -- run the tests.
- ``go run build.go tar`` -- create a syncthing tar.gz dist file in the
current directory. Assumes a Unixy build.
- ``go run build.go zip`` -- create a syncthing zip dist file in the
current directory. Assumes a Windows build.
- ``go run build.go assets`` -- rebuild the compiled-in GUI assets.
- ``go run build.go deps`` -- update the in-repo dependencies.
- ``go run build.go xdr`` -- regenerate the XDR en/decoders. Only
necessary when the protocol has changed.
The options ``-no-upgrade``, ``-goos`` and ``-goarch`` can be given to
influence ``install``, ``build``, ``tar`` and ``zip``. Examples:
- ``go run build.go -goos linux -goarch 386 tar`` -- build a tar.gz
distribution of syncthing for linux-386.
- ``go run build.go -goos windows -no-upgrade zip`` -- build a zip
distribution of syncthing for Windows (current architecture) with
upgrading disabled.
Building without Git
--------------------
Syncthing can be built perfectly fine from a source tarball of course.
If the tarball is from our build server it contains a file called
``RELEASE`` that information the build system of the version being
build. If you're building from a different source package, for example
one automatically generated by Github, you must instead pass the
``-version`` flag to ``build.go``.
If you are building something that will be installed as a package
(Debian, RPM, ...) you almost certainly want to use ``-no-upgrade`` as
well to prevent the built in upgrade system from being activated.
- ``go run build.go -version v0.10.26 -no-upgrade tar`` -- build a
tar.gz distribution of syncthing for the current OS/arch, tagged as
``v0.10.26``, with upgrades disabled.
.. _building-with-docker:
Building with Docker
--------------------
The Docker based build image exactly replicates the official build
process and is a quick way to get up and running with the full cross
compiled setup. Start by getting the build image. It is fairly large
(about 2 GiB).
::
$ docker pull syncthing/build:latest
Then check out and build Syncthing.
::
$ git clone https://github.com/syncthing/syncthing
$ cd syncthing
$ ./build.sh docker-all
A full build is done for all supported architectures, and tests are run.
The process should end with a bunch of release files (``.tar.gz`` and
``.zip``) created.

130
dev/debugging.rst Normal file
View File

@@ -0,0 +1,130 @@
Debugging Syncthing
===================
There's a lot that happens behind the covers, and syncthing is generally
quite silent about it. A number of environment variables can be used to
set the logging to verbose for various parts of the program, and to
enable profiling.
Environment Variables
---------------------
STTRACE
~~~~~~~
The environment variable ``STTRACE`` can be set to a comma separated
list of "facilities", to enable extra debugging information for said
facility. A facility generally maps to a Go package, although there are
a few extra that map to parts of the ``main`` package. Currently, the
following facilities are supported (an up to date list is always printed
by ``syncthing --help``):
- ``beacon`` (the beacon package)
- ``discover`` (the discover package)
- ``events`` (the events package)
- ``files`` (the files package)
- ``http`` (the main package; HTTP requests)
- ``net`` (the main package; connections & network messages)
- ``model`` (the model package)
- ``scanner`` (the scanner package)
- ``stats`` (the stats package)
- ``upnp`` (the upnp package)
- ``xdr`` (the xdr package)
- ``all`` (all of the above)
The debug output is often of the kind that it doesn't make much sense
without looking at the code. The purpose of the different packages /
facilities are something like this:
- ``beacon`` sends and receives UDP broadcasts used by the local
discovery system. Debugging here will show which interfaces and
addresses are selected for broadcasts, etc.
- ``discover`` sends and received local discovery packets. Debugging
here will output the parsed packets, nodes that get registered etc.
- ``files`` keeps track of lists of files with metadata and figures out
which is the newest version of each.
- ``net`` shows connection attempts, incoming connections, and the low
level error when connection attempts fail.
- ``model`` is the largest chunk of the system; this is where pulling
of out of date files happen, indexes sent and received, and incoming
requests for file chunks are logged.
- ``scanner`` is the local filesystem scanner. Debugging here will
output information about changed and unchanged files.
- ``upnp`` is the upnp talker.
- ``xdr`` is the low level protocol encoder. Debugging here will output
all bytes sent/received over the sync connection. Very verbose.
- ``all`` simply enabled debugging of all facilities.
Enabling any of the facilities will also change the log format to
include microsecond timestamps and file names plus line numbers. This
can be used to enable this extra information on the normal logging
level, without enabling any debugging: ``STTRACE=somethingnonexistent``
for example.
Under Unix (including Mac) the easiest way to run syncthing with an
environment variable set is to prepend the variable to the command line.
I.e:
``$ STTRACE=model syncthing``
On windows, it needs to be set prior to running syncthing.
::
C:\> set STTRACE=model
C:\> syncthing
STPROFILER
~~~~~~~~~~
The ``STPROFILER`` environment variable sets the listen address for the
HTTP profiler. If set to for example ``:9090`` the profiler will start
and listen on port 9090. http://localhost:9090/debug/pprof is then the
address to the profiler. Se ``go tool pprof`` for more information.
STGUIASSETS
~~~~~~~~~~~
Directory to load GUI assets from. Overrides compiled in assets. Useful
for developing webgui, commonly use ``STGUIASSETS=gui bin/syncthing``
STCPUPROFILE
~~~~~~~~~~~~
Write a CPU profile to ``cpu-$pid.pprof`` on exit.
STHEAPPROFILE
~~~~~~~~~~~~~
Write heap profiles to ``heap-$pid-$timestamp.pprof`` each time
heap usage increases.
STBLOCKPROFILE
~~~~~~~~~~~~~~
Write block profiles to ``block-$pid-$timestamp.pprof`` every 20
seconds.
STPERFSTATS
~~~~~~~~~~~
Write running performance statistics to ``perf-$pid.csv``. Not supported on
Windows.
STNOUPGRADE
~~~~~~~~~~~
Disable automatic upgrades.
GOMAXPROCS
~~~~~~~~~~
Set the maximum number of CPU cores to use. Defaults to all available
CPU cores.
GOGC
~~~~
Percentage of heap growth at which to trigger GC. Default is 100. Lower
numbers keep peak memory usage down, at the price of CPU usage (ie.
performance)

237
dev/device-ids.rst Normal file
View File

@@ -0,0 +1,237 @@
########################
Understanding Device IDs
########################
Every device is identified by a device ID. The device ID is used for
address resolution, authentication and authorization. The term "device
ID" could interchangably have been "key ID" since the device ID is a
direct properties of the public key in use.
Keys
====
To understand device IDs we need to look at the underlying mechanisms.
At first startup, syncthing will create an public/private key pair.
Currently this is a 3072 bit RSA key. The keys are saved in the form of
the private key (``key.pem``) and a self signed certificate
(``cert.pem``). The self signing part doesn't actually add any security
or functionality as far as syncthing is concerned but it enables the use
of the keys in a standard TLS exchange.
The typical certificate will look something like this, inspected with
``openssl x509``:
::
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 0 (0x0)
Signature Algorithm: sha1WithRSAEncryption
Issuer: CN=syncthing
Validity
Not Before: Mar 30 21:10:52 2014 GMT
Not After : Dec 31 23:59:59 2049 GMT
Subject: CN=syncthing
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (3072 bit)
Modulus (3072 bit):
00:da:83:8a:c0:95:af:0a:42:af:43:74:65:29:f2:
30:e3:b9:12:d2:6b:70:93:da:0b:7b:8a:1e:e5:79:
...
99:09:4c:a9:7b:ba:4a:6a:8b:3b:e6:e7:c7:2c:00:
90:aa:bc:ad:94:e7:80:95:d2:1b
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Basic Constraints: critical
CA:FALSE
Signature Algorithm: sha1WithRSAEncryption
68:72:43:8b:83:61:09:68:f0:ef:f0:43:b7:30:a6:73:1e:a8:
d9:24:6c:2d:b4:bc:c9:e8:3e:0b:1e:3c:cc:7a:b2:c8:f1:1d:
...
88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db:
df:54:b9:4e:be:1b
We can see here that the certificate is little more than a container for
the public key; the serial number is zero and the Issuer and Subject are
both "syncthing" where a qualified name might otherwise be expected.
An advanced user could replace the ``key.pem`` and ``cert.pem`` files
with a keypair generated directly by the ``openssl`` utility or other
mechanism.
Device IDs
==========
To form a device ID the SHA-256 hash of the certificate data in DER form
is calculated. This means the hash covers all information under the
``Certificate:`` section above.
The hashing results in a 256 bit hash, which we encode using base32.
Base32 encodes five bits per character, so we need 256 / 5 = 51.2
characters to encode the device ID. This becomes 52 characters in
practice, but 52 characters of base32 would decode to 260 bits which is
not an whole number of bytes. The base32 encoding adds padding to 280
bits (the next multiple of both 5 and 8 bits) so the resulting ID looks
something like
``MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====``.
The padding (``====``) is stripped away, the device ID split in four
groups, and `check
digits <https://forum.syncthing.net/t/v0-9-0-new-device-id-format/478>`__
are added for each group. For presentation purposes the device ID is
grouped with dashes, resulting in the final value:
``MFZWI3D-BONSGYC-YLTMRWG-C43ENR5 -QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD``.
Connection Establishment
========================
So now we know what device IDs are, here's how they are used in
syncthing. When you add a device ID to the syncthing configuration,
syncthing will attempt to connect to that device. The first thing we
need to do is figure out the IP and port to connect to. There's three
possibilities here;
- The IP and port can be set statically in the configuration. The IP
can equally well be a hostname, so if you have a static IP or a
dynamic DNS setup this might be a good option.
- Using local discovery, if enabled. Every syncthing instance on a LAN
periodically broadcasts information about itself (device ID, address,
port number). If we've seen one of these broadcasts for a given
device ID that's where we try to connect.
- Using global discovery, if enabled. Every syncthing instance
announces itself to the global discovery service (device ID and
external port number - the internal address is not announced to the
global server). If we don't have a static address and haven't seen
any local announcements the global discovery server will be queried
for an address.
Once we have and address and port a TCP connection is established and a
TLS handshake performed. As part of the handshake both devices present
their certificates. Once the handshake has completed and the peer
certificiate is known, the following steps are performed.
1. Calculate the remote device ID by using the process above on the
received certificate.
2. Weed out a few possible misconfigurations - i.e. if the device ID is
that of the local device or of a device we already have an active
connection to. Drop the connection in these cases.
3. Verify the remote device ID against the configuration. If it is not a
device ID we are expecting to talk to, drop the connection.
4. Verify the certificate ``CommonName`` against the configuration. By
default, we expect it to be ``syncthing``, but when using custom
certificates this can be changed.
5. If everything checks out so far, accept the connection.
An Aside About Collisions
-------------------------
The SHA-256 hash is cryptographically collision resistant. This means
that there is no way that we know of to create two different messages
with the same hash.
You can argue that of course there are collisions - there's an infinite
amount of inputs and a finite amount of outputs, so per definition there
are infinitely many messages that result in the same hash.
I'm going to quote `stack
overflow <http://stackoverflow.com/questions/4014090/is-it-safe-to-ignore-the-possibility-of-sha-collisions-in-practice>`__
here:
The usual answer goes thus: what is the probability that a rogue
asteroid crashes on Earth within the next second, obliterating
civilization-as-we- know-it, and killing off a few billion people ?
It can be argued that any unlucky event with a probability lower
than that is not actually very important.
If we have a "perfect" hash function with output size n, and we have
p messages to hash (individual message length is not important),
then probability of collision is about p2/2n+1 (this is an
approximation which is valid for "small" p, i.e. substantially
smaller than 2n/2). For instance, with SHA-256 (n=256) and one
billion messages (p=10^9) then the probability is about 4.3\*10^-60.
A mass-murderer space rock happens about once every 30 million years
on average. This leads to a probability of such an event occurring
in the next second to about 10^-15. That's 45 orders of magnitude
more probable than the SHA-256 collision. Briefly stated, if you
find SHA-256 collisions scary then your priorities are wrong.
It's also worth noting that the property of SHA-256 that we are using is
not simply collision resistance but resistance to a preimage attack.
I.e. even if you can find two messages that result in a hash collision
that doesn't help you attack syncthing (or TLS in general). You need to
create a message that hashes to exactly the hash that my certificate
already has or you won't get in.
Note also that it's not good enough to find a random blob of bits that
happen to have the same hash as my certificate. You need to create a
valid DER- encoded, signed certificate that has the same hash as mine.
The difficulty of this is staggeringly far beyond the already staggering
difficulty of finding a SHA-256 collision.
Problems and Vulnerabilities
============================
As far as I know, these are the issues or potential issues with the
above mechanism.
Discovery Spoofing
------------------
Currently, neither the local nor global discovery mechanism is protected
by crypto. This means that any device can in theory announce itself for
any device ID and potentially receive connections for that device.
This could be a denial of service attack (we can't find the real device
for a given device ID, so can't connect to it and sync). It could also
be an intelligence gathering attack; if I spoof a given ID, I can see
which devices try to connect to it.
It could be mitigated in several ways;
- Announcements could be signed by the device private key. This
requires already having the public key to verify.
- Announcements to the global announce server could be done using TLS,
so the server calculates the device ID based on the certificate
instead of trusting to the device to tell the truth.
- The user could statically configure IP or hostname for the devices.
- The user could run a trusted global server.
It's something we might want to look at at some point, but not a huge
problem as I see it.
Long Device IDs are Painful
---------------------------
It's a mouthful to read over the phone, annoying to type into an SMS or
even into a computer. And it needs to be done twice, once for each side.
This isn't a vulnerability as such, but a user experience problem. There
are various possible solutions;
- Use shorter device IDs with verification based on the full ID ("You
entered MFZWI3; I found and connected to a device with the ID
MFZWI3-DBONSG-YYLTMR-WGC43E-NRQXGZ-DMMFZW-I3DBON-SGYYLT-MRWA, please
confirm that this is correct.").
- Use shorter device IDs with an out of band authentication, a la
Bluetooth pairing. You enter a one time PIN into syncthing and give
that PIN plus a short device ID to another user. On initial connect,
both sides verify that the other knows the correct PIN before
accepting the connection.

53
dev/events.rst Normal file
View File

@@ -0,0 +1,53 @@
Event API
=========
Syncthing provides a simple long polling interface for exposing events from
the core utility towards a GUI.
To receive events, perform a HTTP GET of ``/rest/events?since=<lastSeenID>``,
where ``<lastSeenID>`` is the ID of the last event you've already seen or zero.
Syncthing returns a JSON encoded array of event objects, starting at the event
just after the one with the last seen ID. There is a limit to the number of
events buffered, so if the rate of events is high or the time between polling
calls is long some events might be missed. This can be detected by noting a
discontinuity in the event IDs.
If no new events are produced since ``<lastSeenID>``, the HTTP call blocks and
waits for new events to happen before returning, or if no new events are
produced within 60 seconds, times out.
To receive only a limited number of events, add the ``limit=n`` parameter with a
suitable value for ``n`` and only the *last* ``n`` events will be returned. This
can be used to catch up with the latest event ID after a disconnection for
example: ``/rest/events?since=0&limit=1``.
Event Structure
---------------
Each event is represented by an object similar to the following::
{
"id": 2,
"type": "DeviceConnected",
"time": "2014-07-13T21:04:33.687836696+02:00",
"data": {
"addr": "172.16.32.25:22000",
"id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
}
}
The top level keys ``id``, ``time``, ``type`` and ``data`` are always present, though ``data`` may be ``null``.
* ``id`` is a monotonically increasing integer. The first event generated has id ``1``, the next has id ``2`` etc.
* ``time`` is the time the event was generated.
* ``type`` indicates the type of (i.e. reason for) the event and is one of the event types below.
* ``data`` is an object containing optional extra information; the exact structure is determined by the event type.
Events
------
.. toctree::
:maxdepth: 2
:glob:
../events/*

50
dev/issues.rst Normal file
View File

@@ -0,0 +1,50 @@
Issue Management
================
Bugs, feature requests and other things we need to do are tracked as
Github issues. Issues can be of various types and in various states, and
also belong to milestones or not. This page is an attempt to document
the current practice.
Labels
------
Issues without labels are undecided - that is, we don't yet know if it's
a bug, a configuration issue, a feature request or what. Issues that are
invalid for whatever reason are closed with a short explanation of why.
Examples include "Duplicate of #123", "Discovered to be configuration
error", "Rendered moot by #123" and so on. We don't use the "invalid" or
"wontfix" labels.
- **android** - Marks an issue as occurring on the Android platform
only.
- **bug** - The issue is a verified bug.
- **build** - The issue is caused by or requires changes to the build
system (scripts or Docker image).
- **docs** - Something requires documenting.
- **easy** - This could be easily fixed, probably an hours work or
less.
- **enhancement** - This is a new feature or an improvement of some
kind, as opposed to a problem (bug).
- **help-wanted** - The core team can't or won't do this, but someone
else is welcome to. This does not mean that help is not wanted on the
*other* issues. You can see this as a soft ``wontfix``.
- **pr-bugfix** - This pull request *fixes* a bug. This is different
from the ``bug`` label, as there may also be pull requests with for
example tests that *prove* a bug which would then be labeled ``bug``.
- **pr-refactor** - This pull request is a refactoring, i.e. not
supposed to change behavior.
- **pr-wait-or-pending** - This pull request is not ready for merging,
even if the tests pass and it looks good. It is incomplete or
requires more discussion.
- **protocol** - This requires a change to the protocol.

35
dev/jenkins.rst Normal file
View File

@@ -0,0 +1,35 @@
Interacting with Jenkins
========================
Jenkins will test pull requests from recognized authors. If the pull
request is not from a recognized author, an *admin* needs to tell
Jenkins to perform the tests, after giving the patch a manual look over
to prevent shenanigans. A number of tests are performed, ranging from
verifying correct code formatting and that the author is included in the
AUTHORS file to that the code in fact builds and passes tests. A pull
request should usually only be merged if all tests return green,
although there are exceptions.
To enable testing for this pull request only:
::
@st-jenkins ok to test
To enable testing for this pull request, and all future pull requests
from the same author:
::
@st-jenkins add to whitelist
For pull requests where Jenkins has already run it's tests, but should
run them again:
::
@st-jenkins test this please
This is not necessary when new commits are pushed (tests will be rerun
for the new commits), but is useful if something has changed server side
or to verify that everything is still OK if ``master`` has been updated.

45
dev/release-schedule.rst Normal file
View File

@@ -0,0 +1,45 @@
Release Schedule
================
Structure
---------
Syncthing follows the `Semantic Versioning <http://semver.org/>`__
scheme of versioning. Each release has a three part version number:
*major*.\ *minor*.\ *patch*.
A new *major* version is released when there are incompatible API or
protocol changes, a new *minor* version is released when there are new
features but compatibility with older releases is retained, and a new
*patch* version is released when there are bug fixes (compatibility with
older releases always retained).
While still in pre-release mode, i.e. versions 0.\ *x*, breaking changes
are made in minor releases rather than major. Version 0.7.3 should be
able to talk to version 0.7.52, but will probably not understand version
0.8.0. This also means that if you don't like 0.7.52, you can safely
downgrade to 0.7.3 again and keep your configuration, index caches, etc.
However 0.8.0 might have a different format for those things so a
downgrade to 0.7.x might be trickier.
Patch Releases
--------------
A new patch release is made each sunday, if there have been changes
committed since the last release. Serious bugs, such as would crash the
client or corrupt data, cause an immediate (out of schedule) patch
release.
Minor Releases
--------------
Minor releases are made when new functionality is ready for release.
This happen approximately once every few weeks, with the pace slowing as
the 1.0 release nears.
Major Releases
--------------
A new major release is a rare event. At the time of writing this has not
yet happened and is foreseen to happen only once in the foreseeable
future - the 1.0 release.

53
dev/release.rst Normal file
View File

@@ -0,0 +1,53 @@
Creating a Release
==================
Prerequisites
-------------
- Push access to the syncthing repo, for pushing a new tag.
- SSH account on build server, member of the ``jenkins`` group, for
accessing and signing the releases.
- The release signing key on your GPG keyring on your own computer (for
signing the tag) and your account on the build server (for signing
the release). In a pinch, having it just on the build server will do
since you can run git there to create, sign and push the tag.
- Your Github token in the ``GITHUB_TOKEN`` environment variable on the
build server, for uploading the release.
Process
-------
Make sure the build seems sane. I.e. the build is clean on the build
server, the integration tests pass without complaints. (Currently, the
tests are a bit flaky, specifically the ``TestSyncCluster...`` ones. I'm
not sure if the tests are weird or there is something actually bad
happening that should be fixed - requires investigation).
Create a new, signed tag on master, with the version as comment, and
push it:
.. code:: bash
$ git tag -a -s -u release@syncthing.net -m v0.10.15 v0.10.15
$ git push --tags
The build server will build packages under the job
``syncthing-release``. Wait for this to complete successfully before
moving on.
Run ``./changelog.sh`` (in the repo) to create the changelog comparison
from the previous release. Copy to clipboard.
On the Github releases page, select the newly pushed tag and hit "Edit
Tag". Set the "Release title" to the same version as the tag, paste in
the changelog from above, and publish the release.
On the build server, logged in via ssh, run
``/usr/local/bin/upload-release``. This will create the md5sum and
sha1sum files, sign them (gpg will prompt for key passphrase twice) and
upload the whole shebang to Github.
Verify it looks sane on the releases page.

52
dev/rest.rst Normal file
View File

@@ -0,0 +1,52 @@
REST API
========
Syncthing exposes a REST interface over HTTP on the GUI port. This is
used by the GUI code (Javascript) and can be used by other processes
wishing to control syncthing. In most cases both the input and output
data is in JSON format. The interface is subject to change.
API Key
-------
To use the POST methods, or *any* method when authentication is enabled,
an API key must be set and used. The API key can be generated in the
GUI, or set in the ``configuration/gui/apikey`` element in the
configuration file. To use an API key, set the request header
``X-API-Key`` to the API key value.
System Endpoints
----------------
.. toctree::
:maxdepth: 1
:glob:
../rest/system-*
Database Endpoints
------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/db-*
Statistics Endpoints
--------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/stats-*
Misc Services Endpoints
-----------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/svc-*

20
events/configsaved.rst Normal file
View File

@@ -0,0 +1,20 @@
ConfigSaved
-----------
Emitted after the config has been saved by the user or by Syncthing
itself.
.. code:: json
{
"id": 50,
"type": "ConfigSaved",
"time": "2014-12-13T00:09:13.5166486Z",
"data":{
"Version": 7,
"Options": { ... },
"GUI": { ... },
"Devices": [ ... ],
"Folders": [ ... ]
}
}

16
events/deviceconnected.rst Normal file
View File

@@ -0,0 +1,16 @@
DeviceConnected
---------------
Generated each time a connection to a device has been established.
.. code:: json
{
"id": 2,
"type": "DeviceConnected",
"time": "2014-07-13T21:04:33.687836696+02:00",
"data": {
"addr": "172.16.32.25:22000",
"id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
}
}

23
events/devicedisconnected.rst Normal file
View File

@@ -0,0 +1,23 @@
DeviceDisconnected
------------------
Generated each time a connection to a device has been terminated.
.. code:: json
{
"id": 48,
"type": "DeviceDisconnected",
"time": "2014-07-13T21:18:52.859929215+02:00",
"data": {
"error": "unexpected EOF",
"id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
}
}
.. note::
The error key contains the cause for disconnection, which might not
necessarily be an error as such. Specifically, "EOF" and "unexpected
EOF" both signify TCP connection termination, either due to the other
device restarting or going offline or due to a network change.

18
events/devicediscovered.rst Normal file
View File

@@ -0,0 +1,18 @@
DeviceDiscovered
----------------
Emitted when a new device is discovered using local discovery.
.. code:: json
{
"id": 13,
"type": "DeviceDiscovered",
"time": "2014-07-17T13:28:05.043465207+02:00",
"data": {
"addrs": [
"172.16.32.25:22000"
],
"device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
}
}

17
events/devicerejected.rst Normal file
View File

@@ -0,0 +1,17 @@
DeviceRejected
--------------
Emitted when there is a connection from a device we are not configured
to talk to.
.. code:: json
{
"id": 24,
"type": "DeviceRejected",
"time": "2014-08-19T10:43:00.562821045+02:00",
"data": {
"address": "127.0.0.1:51807",
"device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK"
}
}

80
events/downloadprogress.rst Normal file
View File

@@ -0,0 +1,80 @@
DownloadProgress
----------------
Emitted during file downloads for each folder for each file. By default
only a single file in a folder is handled at the same time, but custom
configuration can cause multiple files to be shown.
.. code:: json
{
"id": 221,
"type": "DownloadProgress",
"time": "2014-12-13T00:26:12.9876937Z",
"data": {
"folder1": {
"file1": {
"Total": 800,
"Pulling": 2,
"CopiedFromOrigin": 0,
"Reused": 633,
"CopiedFromElsewhere": 0,
"Pulled": 38,
"BytesTotal": 104792064,
"BytesDone": 87883776
},
"dir\\file2": {
"Total": 80,
"Pulling": 2,
"CopiedFromOrigin": 0,
"Reused": 0,
"CopiedFromElsewhere": 0,
"Pulled": 32,
"BytesTotal": 10420224,
"BytesDone": 4128768
}
},
"folder2": {
"file3": {
"Total": 800,
"Pulling": 2,
"CopiedFromOrigin": 0,
"Reused": 633,
"CopiedFromElsewhere": 0,
"Pulled": 38,
"BytesTotal": 104792064,
"BytesDone": 87883776
},
"dir\\file4": {
"Total": 80,
"Pulling": 2,
"CopiedFromOrigin": 0,
"Reused": 0,
"CopiedFromElsewhere": 0,
"Pulled": 32,
"BytesTotal": 10420224,
"BytesDone": 4128768
}
}
}
}
- ``Total`` - total number of blocks in the file
- ``Pulling`` - number of blocks currently being downloaded
- ``CopiedFromOrigin`` - number of blocks copied from the file we are
about to replace
- ``Reused`` - number of blocks reused from a previous temporary file
- ``CopiedFromElsewhere`` - number of blocks copied from other files or
potentially other folders
- ``Pulled`` - number of blocks actually downloaded so far
- ``BytesTotal`` - approximate total file size
- ``BytesDone`` - approximate number of bytes already handled (already
reused, copied or pulled)
Where block size is 128KB.
Files/folders appearing in the event data imply that the download has
been started for that file/folder, where disappearing implies that the
downloads has been finished or failed for that file/folder. There is
always a last event emitted with no data, which implies all downloads
being finished/failed.

20
events/foldercompletion.rst Normal file
View File

@@ -0,0 +1,20 @@
FolderCompletion
----------------
The ``FolderCompletion`` event is emitted when the local or remote
contents for a folder changes. It contains the completion percentage for
a given remote device and is emitted once per currently connected remote
device.
.. code:: json
{
"id": 84,
"type": "FolderCompletion",
"time": "2015-04-17T14:14:27.043576583+09:00",
"data": {
"completion": 100,
"device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
"folder": "default"
}
}

17
events/folderrejected.rst Normal file
View File

@@ -0,0 +1,17 @@
FolderRejected
--------------
Emitted when a device sends index information for a folder we do not
have, or have but do not share with the device in question.
.. code:: json
{
"id": 27,
"type": "FolderRejected",
"time": "2014-08-19T10:41:06.761751399+02:00",
"data": {
"device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
"folder": "unique"
}
}

34
events/foldersummary.rst Normal file
View File

@@ -0,0 +1,34 @@
FolderSummary
-------------
The FolderSummary event is emitted when folder contents have changed
locally. This can be used to calculate the current local completion
state.
.. code:: json
{
"id": 16,
"type": "FolderSummary",
"time": "2015-04-17T14:12:20.460121585+09:00",
"data": {
"folder": "default",
"summary": {
"globalBytes": 0,
"globalDeleted": 0,
"globalFiles": 0,
"ignorePatterns": false,
"inSyncBytes": 0,
"inSyncFiles": 0,
"invalid": "",
"localBytes": 0,
"localDeleted": 0,
"localFiles": 0,
"needBytes": 0,
"needFiles": 0,
"state": "idle",
"stateChanged": "2015-04-17T14:12:12.455224687+09:00",
"version": 0
}
}
}

37
events/itemfinished.rst Normal file
View File

@@ -0,0 +1,37 @@
ItemFinished
------------
Generated when syncthing ends synchronizing a file to a newer version. A
successfull operation:
.. code:: json
{
"id": 93,
"type": "ItemFinished",
"time": "2014-07-13T21:22:03.414609034+02:00",
"data": {
"item": "test.txt",
"folder": "default",
"error": null,
"type": "file",
"action": "update"
}
}
An unsuccessfull operation:
.. code:: json
{
"id": 44,
"type": "ItemFinished",
"time": "2015-05-27T11:21:05.711133004+02:00",
"data": {
"action": "update",
"error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
"folder": "default",
"item": "foo/hej",
"type": "file"
}
}

18
events/itemstarted.rst Normal file
View File

@@ -0,0 +1,18 @@
ItemStarted
-----------
Generated when syncthing begins synchronizing a file to a newer version.
.. code:: json
{
"id": 93,
"type": "ItemStarted",
"time": "2014-07-13T21:22:03.414609034+02:00",
"data": {
"item": "test.txt",
"folder": "default",
"type": "file",
"action": "update"
}
}

18
events/localindexupdated.rst Normal file
View File

@@ -0,0 +1,18 @@
LocalIndexUpdated
-----------------
Generated when the local index information has changed, due to
synchronizing one or more items from the cluster or discovering local
changes during a scan.
.. code:: json
{
"id": 59,
"type": "LocalIndexUpdated",
"time": "2014-07-17T13:27:28.051369434+02:00",
"data": {
"folder": "default",
"items": 1000,
}
}

15
events/ping.rst Normal file
View File

@@ -0,0 +1,15 @@
Ping
----
The Ping event is generated automatically every 60 seconds. This means
that even in the absence of any other activity, the event polling HTTP
request will return within a minute.
.. code:: json
{
"id": 46,
"type": "Ping",
"time": "2014-07-13T21:13:18.502171586+02:00",
"data": null
}

17
events/remoteindexupdated.rst Normal file
View File

@@ -0,0 +1,17 @@
RemoteIndexUpdated
------------------
Generated each time new index information is received from a device.
.. code:: json
{
"id": 44,
"type": "RemoteIndexUpdated",
"time": "2014-07-13T21:04:35.394184435+02:00",
"data": {
"device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
"folder": "lightroom",
"items": 1000
}
}

16
events/starting.rst Normal file
View File

@@ -0,0 +1,16 @@
Starting
--------
Emitted exactly once, when syncthing starts, before parsing
configuration etc.
.. code:: json
{
"id": 1,
"type": "Starting",
"time": "2014-07-17T13:13:32.044470055+02:00",
"data": {
"home": "/home/jb/.config/syncthing"
}
}

14
events/startupcomplete.rst Normal file
View File

@@ -0,0 +1,14 @@
StartupCompleted
----------------
Emitted exactly once, when initialization is complete and syncthing is
ready to start exchanging data with other devices.
.. code:: json
{
"id": 1,
"type": "StartupComplete",
"time": "2014-07-13T21:03:18.383239179+02:00",
"data": null
}

22
events/statechanged.rst Normal file
View File

@@ -0,0 +1,22 @@
StateChanged
------------
Emitted when a folder changes state. Possible states are ``idle``,
``scanning``, ``cleaning`` and ``syncing``. The field ``duration`` is
the number of seconds the folder spent in state ``from``. In the example
below, the folder ``default`` was in state ``scanning`` for 0.198
seconds and is now in state ``idle``.
.. code:: json
{
"id": 8,
"type": "StateChanged",
"time": "2014-07-17T13:14:28.697493016+02:00",
"data": {
"folder": "default",
"from": "scanning",
"duration": 0.19782869900000002,
"to": "idle"
}
}

49
index.rst Normal file
View File

@@ -0,0 +1,49 @@
.. Syncthing documentation master file, created by
sphinx-quickstart on Thu May 28 08:33:11 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Syncthing's documentation!
=====================================
The main documentation for the site is organized into a couple sections:
* :ref:`intro-docs`
* :ref:`user-docs`
* :ref:`dev-docs`
Contents:
.. _intro-docs:
.. toctree::
:caption: Introduction
:maxdepth: 1
:glob:
intro/*
.. _user-docs:
.. toctree::
:caption: For Users
:maxdepth: 1
:glob:
users/*
.. _dev-docs:
.. toctree::
:caption: For Developers
:maxdepth: 1
:glob:
dev/*
Indices and tables
==================
* :ref:`search`

143
intro/getting-started.rst Normal file
View File

@@ -0,0 +1,143 @@
Getting Started
===============
For this guide let's assume you have two machines between which you want
to synchronise files. In keeping with Syncthing terminology they are
going to be called "devices" in the rest of the documentation. The
"local device" is the one you are configuring, viewing status for, etc,
while the "remote device" is the other machine.
The best way to follow this guide is to do the install on both machines
and configure them in parallel. If both machines aren't accessible
simultaneously that's fine, the results will just be a little less
immediately obvious.
Installing
----------
We suggest you have a look to many of the `community contributions`_ which let
you pick a flavor of Syncthing that best fits your scenario. For example, if you
are interested in a cross-platform GUI application you can check out
`Syncthing-GTK`_. The community has also developed Windows, Android and `many
more`_ specific flavors that help you run Syncthing on your devices. Currently
all community flavors run the same Syncthing core underneath, so don't worry
about changing your flavor at a later point in time. The remainder of this page
will explain how to set up two devices with the core Syncthing flavor.
.. _`community contributions`: http://docs.syncthing.net/users/contrib.html
.. _`Syncthing-GTK`: https://github.com/syncthing/syncthing-gtk
.. _`many more`: http://docs.syncthing.net/users/contrib.html
Syncthing
~~~~~~~~~
Grab the `latest release`_ of Syncthing for your operating system at and unpack
it. There will be a binary called ``syncthing`` (or ``syncthing.exe`` on
Windows). Start this in whatever way you are most comfortable with;
double-clicking should work in any graphical environment, but I'll use the
terminal to better illustrate what happens. At first start, Syncthing will
generate a configuration and some keys and then start the admin GUI in your
browser. Something like the following will be printed in the terminal::
$ syncthing
[monitor] 15:56:58 INFO: Starting syncthing
15:56:58 INFO: Generating RSA key and certificate for syncthing...
[ANSMX] 15:57:05 INFO: syncthing v0.10.14 (go1.4 darwin-amd64 default) jb@syno...
[ANSMX] 15:57:05 INFO: My ID: ANSMXYD-E6CF3JC-TCVPYGF-GXJPHSJ-MKUXBUQ-ZSPOKXH-...
[ANSMX] 15:57:05 INFO: No config file; starting with empty defaults
[ANSMX] 15:57:05 INFO: Edit gs1/config.xml to taste or use the GUI
[ANSMX] 15:57:05 INFO: Starting web GUI on http://127.0.0.1:8384/
[ANSMX] 15:57:05 INFO: Loading HTTPS certificate: open gs1/https-cert.pem: no ...
[ANSMX] 15:57:05 INFO: Creating new HTTPS certificate
[ANSMX] 15:57:05 INFO: Generating RSA key and certificate for syno...
[ANSMX] 15:57:07 INFO: Starting UPnP discovery...
[ANSMX] 15:57:13 INFO: UPnP discovery complete (found 0 devices).
[ANSMX] 15:57:13 INFO: Starting local discovery announcements
[ANSMX] 15:57:13 INFO: Local discovery over IPv4 unavailable
[ANSMX] 15:57:13 INFO: Starting global discovery announcements
[ANSMX] 15:57:13 OK: Ready to synchronize default (read-write)
[ANSMX] 15:57:13 INFO: Device ANSMXYD-E6CF3JC-TCVPYGF-GXJPHSJ-MKUXBUQ-ZSPOKXH-...
[ANSMX] 15:57:13 INFO: Completed initial scan (rw) of folder default
At this point Syncthing will also have set up a folder called
``default`` for you, in a directory called ``Sync`` in your home
directory. You can use this as a starting point, then remove it or add
more folders later.
.. _`latest release`: https://github.com/syncthing/syncthing/releases/latest
Configuring
-----------
The admin GUI starts automatically and remains available on
``http://localhost:8384/``. It should look something like this:
.. figure:: gs1.png
:alt: gs1.png
On the left is the list of "folders", or directories to synchronize. You
can see the ``default`` folder was created for you, and it's currently
marked "Unshared" since it's not yet shared with any other device. On
the right is the list of devices. Currently there is only one device:
the computer you are running this on.
For Syncthing to be able to synchronize files with another device, it
must be told about that device. This is accomplished by exchanging
"device IDs". A device ID is a unique, cryptographically-secure
identifier that is generated as part of the key generation the first
time you start Syncthing. It is printed in the log above, and you can
see it in the web GUI by selecting the "gear menu" (top right) and "Show
ID".
Two devices will *only* connect and talk to each other if they both know
about the other's device ID. Since the configuration must be mutual for
a connection to happen, device IDs don't need to be kept secret.
To get your two devices to talk to each other, click "Add Device" at the
bottom right on both, and enter the device ID of the other side. You
should also select the folder(s) that you want to share with this
device. The device name is optional, but you can set it to something
that makes sense for you to remember what device this is.
.. figure:: gs2.png
:alt: gs2.png
Once you click "Save" the new device will appear on right side of the
GUI (although disconnected) and a prompt will be shown to indicate the
need for a restart.
.. figure:: gs3.png
:alt: gs3.png
Syncthing needs to be restarted for some configuration changes to take
effect (such as sharing folders with new devices). When you click
"Restart" Syncthing will first restart…
.. figure:: gs4.png
:alt: gs4.png
… then come back up and after a while (up to a minute) connect to the
other device. Remember though that you need to do the above process on
both devices, and only once you've done this on both devices will they
be able to connect.
.. figure:: gs5.png
:alt: gs5.png
At this point the two devices share an empty directory. Adding files to
the Sync directory on either device will synchronize those files to the
other side. Each device scans for changes every 60 seconds, so changes
can take a little over a minute to propagate to the other side. The
rescan interval can be changed for each folder by clicking on a folder,
clicking "Edit" and entering a new value for "Rescan Interval".
--------------
Good luck and have fun! There is more
`documentation <http://docs.syncthing.net/>`__ and if you run into
trouble feel free to post a question in the `support
forum <http://forum.syncthing.net/category/support>`__. If you have
problems getting this to connect, first take a look at `Firewalls and
Port Forwards <http://docs.syncthing.net/users/firewalls.html>`__, then
look at any error messages in the GUI or on the console and if necessary
move on to `Debugging <http://docs.syncthing.net/dev/debugging.html>`__.

BIN
intro/gs1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 122 KiB

BIN
intro/gs2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 168 KiB

BIN
intro/gs3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 158 KiB

BIN
intro/gs4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

BIN
intro/gs5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 168 KiB

45
intro/gui.rst Normal file
View File

@@ -0,0 +1,45 @@
An intro to the GUI
===================
Folder View
-----------
The left side of the screen shows the ID and current state of all configured
folders. Clicking the folder name makes that section expand to show more
detailed folder information, and buttons for editing the configuration or
forcing a rescan.
.. figure:: gui1.png
A folder can be in any one of these states:
- *Unknown* while the GUI is loading.
- *Unshared* when you have not shared this folder,
- *Stopped* when the folder has experienced an error,
- *Scanning* while the folder is lookign for local changes,
- *Up to Date* when the folder is in sync with the rest of the cluster,
- *Syncing* when this device is downloading changes from the network.
Among the folder details, you can see the current "Global State" and "Local State" summaries, as well as the amount of "Out of Sync" data if the the folder state is not up to date.
- *Global State* indicates how much data the fully up to date folder contains - this is basically the sum of the newest versions of all files from all connected devices. This is the size of the folder on your computer when it is fully in sync with the cluster.
- *Local State* shows how much data the folder actually contains right now. This can be more or less than the global state, if the folder is currently synchronizing with other devices.
- *Out of Sync* shows how much data that needs to be synchronized from other devices. Note that this is the sum of all out of sync *files* - if you already have parts of such a file, or an older version of the file, less data than this will need to be transferred over the network.
Device View
-----------
The right side of the screen shows the overall state of all configured
devices. The local device (your computer) is always at the top, with remote
devices in alphabetical order below. For each device you see its current state
and, when expanded, more detailed information. All transfer rates ("Download
Rate" and "Upload Rate") are from the perspective of your computer, even those
shown for remote devices. The rates for your local device is the sum of those
for the remote devices.

BIN
intro/gui1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 425 KiB

11
intro/index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: Index
nav: false
---
{% assign pages = site.intro | sort: 'title' | sort: 'weight' %}
{% for node in pages %}
{% if node.title != null and node.nav == true %}
<a class="sidebar-nav-item{% if page.url == node.url %} active{% endif %}" href="{{ site.baseurl }}{{ node.url }}">{{ node.title }}</a>
{% endif %}
{% endfor %}

242
make.bat Normal file
View File

@@ -0,0 +1,242 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Syncthing.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Syncthing.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

55
rest/db-browse-get.rst Normal file
View File

@@ -0,0 +1,55 @@
GET /rest/db/browse
===================
Returns the directory tree of the global model. Directories are always
JSON objects (map/dictionary), and files are always arrays of
modification time and size. The first integer is the files modification
time, and the second integer is the file size.
The call takes one mandatory ``folder`` parameter and two optional
parameters. Optional parameter ``levels`` defines how deep within the
tree we want to dwell down (0 based, defaults to unlimited depth)
Optional parameter ``prefix`` defines a prefix within the tree where to
start building the structure.
.. code:: bash
$ curl -s http://localhost:8384/rest/db/browse?folder=default | json_pp
{
"directory": {
"file": ["2015-04-20T22:20:45+09:00", 130940928],
"subdirectory": {
"another file": ["2015-04-20T22:20:45+09:00", 130940928]
}
},
"rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
}
$ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
{
"directory": {},
"rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
}
$ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
{
"directory": {
"file": ["2015-04-20T22:20:45+09:00", 130940928],
"subdirectory": {}
},
"rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
}
$ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
{
"another file": ["2015-04-20T22:20:45+09:00", 130940928]
}
$ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
{
"file": ["2015-04-20T22:20:45+09:00", 130940928],
"subdirectory": {}
}
.. note::
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.

14
rest/db-completion-get.rst Normal file
View File

@@ -0,0 +1,14 @@
GET /rest/db/completion
=======================
Returns the completion percentage (0 to 100) for a given device and
folder.Takes ``device`` and ``folder`` parameters.
.. code:: json
{
"completion": 0
}
.. note::
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.

35
rest/db-file-get.rst Normal file
View File

@@ -0,0 +1,35 @@
GET /rest/db/file
=================
Returns most data available about a given file, including version and
availability.
.. code:: json
{
"availability": [
"I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU"
],
"global": {
"flags": "0644",
"localVersion": 3,
"modified": "2015-04-20T22:20:45+09:00",
"name": "util.go",
"numBlocks": 1,
"size": 9642,
"version": [
"5407294127585413568:1"
]
},
"local": {
"flags": "0644",
"localVersion": 4,
"modified": "2015-04-20T22:20:45+09:00",
"name": "util.go",
"numBlocks": 1,
"size": 9642,
"version": [
"5407294127585413568:1"
]
}
}

20
rest/db-ignores-get.rst Normal file
View File

@@ -0,0 +1,20 @@
GET /rest/db/ignores
====================
Takes one parameter, ``folder``, and returns the content of the
``.stignore`` as the ``ignore`` field. A second field, ``patterns``,
provides a compiled version of all included ignore patterns in the form
of regular expressions. Excluded items in the ``patterns`` field have a
nonstandard ``(?exclude)`` marker in front of the regular expression.
.. code:: json
{
"ignore": [
"/Backups"
],
"patterns": [
"(?i)^Backups$",
"(?i)^Backups/.*$"
]
}

7
rest/db-ignores-post.rst Normal file
View File

@@ -0,0 +1,7 @@
POST /rest/db/ignores
=====================
Expects a format similar to the output of ``GET`` call, but only
containing the ``ignore`` field (``patterns`` field should be omitted).
It takes one parameter, ``folder``, and either updates the content of
the ``.stignore`` echoing it back as a response, or returns an error.

32
rest/db-need-get.rst Normal file
View File

@@ -0,0 +1,32 @@
GET /rest/db/need
=================
Takes one parameter, ``folder``, and returns lists of files which are
needed by this device in order for it to become in sync.
.. code:: bash
{
# Files currently being downloaded
"progress": [
{
"flags": "0755",
"localVersion": 6,
"modified": "2015-04-20T23:06:12+09:00",
"name": "ls",
"size": 34640,
"version": [
"5157751870738175669:1"
]
}
],
# Files queued to be downloaded next (as per array order)
"queued": [
...
],
# Files to be downloaded after all queued files will be downloaded.
# This happens when we start downloading files, and new files get added while we are downloading.
"rest": [
...
]
}

10
rest/db-prio-post.rst Normal file
View File

@@ -0,0 +1,10 @@
POST /rest/db/prio
==================
Moves the file to the top of the download queue.
.. code:: bash
curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
Response contains the same output as ``GET /rest/db/need``

20
rest/db-scan-post.rst Normal file
View File

@@ -0,0 +1,20 @@
POST /rest/db/scan
==================
Request immediate rescan of a folder, or a specific path within a
folder. Takes the mandatory parameter ``folder`` (folder ID) and the
optional parameter ``sub`` (path relative to the folder root). If
``sub`` is omitted or empty, the entire folder is scanned for changes,
otherwise only the given path (and children, in case it's a directory)
is scanned.
Requesting scan of a path that no longer exists, but previously did, is
valid and will result in syncthing noticing the deletion of the path in
question.
Returns status 200 and no content upon success, or status 500 and a
plain text error if an error occurred during scanning.
.. code:: bash
curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar

34
rest/db-status-get.rst Normal file
View File

@@ -0,0 +1,34 @@
GET /rest/db/status
===================
Returns information about the current status of a folder.
Parameters: ``folder``, the ID of a folder.
.. code:: bash
{
# latest version according to cluster:
"globalBytes": 13173473780,
"globalDeleted": 1847,
"globalFiles": 42106,
# what we have locally:
"localBytes": 13173473780,
"localDeleted": 1847,
"localFiles": 42106,
# which part of what we have locally is the latest cluster verision:
"inSyncBytes": 13173473780,
"inSyncFiles": 42106,
# which part of what we have locally should be fetched from the cluster:
"needBytes": 0,
"needFiles": 0,
# various other metadata
"ignorePatterns": true,
"invalid": "",
"state": "idle",
"stateChanged": "2015-03-16T21:47:28.750853241+01:00",
"version": 71989
}
.. note::
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.

14
rest/stats-device-get.rst Normal file
View File

@@ -0,0 +1,14 @@
GET /rest/stats/device
======================
Returns general statistics about devices. Currently, only contains the
time the device was last seen.
.. code:: bash
$ curl -s http://localhost:8384/rest/stats/device | json
{
"P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
"lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
}
}

17
rest/stats-folder-get.rst Normal file
View File

@@ -0,0 +1,17 @@
GET /rest/stats/folder
======================
Returns general statistics about folders. Currently, only contains the
last synced file.
.. code:: bash
$ curl -s http://localhost:8384/rest/stats/folder | json
{
"folderid" : {
"lastFile" : {
"filename" : "file/name",
"at" : "2015-04-16T22:04:18.3066971+01:00"
}
}
}

19
rest/svc-deviceid-get.rst Normal file
View File

@@ -0,0 +1,19 @@
GET /rest/svc/deviceid
======================
Verifies and formats a device ID. Accepts all currently valid formats
(52 or 56 characters with or without separators, upper or lower case,
with trivial substitutions). Takes one parameter, ``id``, and returns
either a valid device ID in modern format, or an error.
.. code:: bash
$ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
{
"error": "device ID invalid: incorrect length"
}
$ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
{
"id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
}

9
rest/svc-lang-get.rst Normal file
View File

@@ -0,0 +1,9 @@
GET /rest/svc/lang
==================
Returns a list of canonicalized localization codes, as picked up from
the ``Accept-Language`` header sent by the browser.
.. code:: json
["sv_sv","sv","en_us","en"]

22
rest/svc-report-get.rst Normal file
View File

@@ -0,0 +1,22 @@
GET /rest/svc/report
====================
Returns the data sent in the anonymous usage report.
.. code:: json
{
"folderMaxFiles": 42106,
"folderMaxMiB": 12563,
"longVersion": "syncthing v0.10.27+5-g36c93b7 (go1.4 darwin-amd64 default) jb@syno 2015-03-16 20:43:34 UTC",
"memorySize": 16384,
"memoryUsageMiB": 41,
"numDevices": 10,
"numFolders": 4,
"platform": "darwin-amd64",
"sha256Perf": 122.38,
"totFiles": 45180,
"totMiB": 18151,
"uniqueID": "6vulmdGw",
"version": "v0.10.27+5-g36c93b7"
}

10
rest/system-config-get.rst Normal file
View File

@@ -0,0 +1,10 @@
GET /rest/system/config
=======================
Returns the current configuration.
.. code:: bash
{
# etc
}

11
rest/system-config-insync-get.rst Normal file
View File

@@ -0,0 +1,11 @@
GET /rest/system/config/insync
==============================
Returns whether the config is in sync, i.e. whether the running
configuration is the same as that on disk.
.. code:: json
{
"configInSync": true
}

7
rest/system-config-post.rst Normal file
View File

@@ -0,0 +1,7 @@
POST /rest/system/config
========================
Post the full contents of the configuration, in the same format as
returned by the corresponding GET request. The configuration will be
saved to disk and the configInSync flag set to false. Restart syncthing
to activate.

26
rest/system-connections-get.rst Normal file
View File

@@ -0,0 +1,26 @@
GET /rest/system/connections
============================
Returns the list of current connections and some metadata associated
with the connection/peer.
.. code:: json
{
"connections": {
"SMAHWLH-AP74FAB-QWLDYGV-Q65ASPL-GAAR2TB-KEF5FLB-DRLZCPN-DJBFZAG": {
"address": "172.21.20.78:22000",
"at": "2015-03-16T21:51:38.672758819+01:00",
"clientVersion": "v0.10.27",
"inBytesTotal": 415980,
"outBytesTotal": 396300
}
},
"total": {
"address": "",
"at": "2015-03-16T21:51:38.672868814+01:00",
"clientVersion": "",
"inBytesTotal": 415980,
"outBytesTotal": 396300
}
}

12
rest/system-discovery-get.rst Normal file
View File

@@ -0,0 +1,12 @@
GET /rest/system/discovery
==========================
Returns the contents of the local discovery cache.
.. code:: json
{
"LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
"192.162.129.11:22000"
]
}

11
rest/system-discovery-hint-post.rst Normal file
View File

@@ -0,0 +1,11 @@
POST /rest/system/discovery/hint
================================
Post with the query parameters ``device`` and ``addr`` to add entries to
the discovery cache.
.. code:: bash
curl -X POST http://127.0.0.1:8384/rest/system/discovery/hint?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
# Or with the X-API-Key header:
curl -X POST --header "X-API-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ" http://127.0.0.1:8384/rest/system/discovery/hint?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000

4
rest/system-error-clear-post.rst Normal file
View File

@@ -0,0 +1,4 @@
POST /rest/system/error/clear
==============================
Post with empty to body to remove all recent errors.

15
rest/system-error-get.rst Normal file
View File

@@ -0,0 +1,15 @@
GET /rest/system/error
======================
Returns the list of recent errors.
.. code:: json
{
"errors": [
{
"time": "2014-09-18T12:59:26.549953186+02:00",
"error": "This is an error string"
}
]
}

5
rest/system-error-post.rst Normal file
View File

@@ -0,0 +1,5 @@
POST /rest/system/error
=======================
Post with an error message in the body (plain text) to register a new
error. The new error will be displayed on any active GUI clients.

10
rest/system-ping-get.rst Normal file
View File

@@ -0,0 +1,10 @@
GET /rest/system/ping
=====================
Returns a ``{"ping": "pong"}`` object.
.. code:: json
{
"ping": "pong"
}

7
rest/system-ping-post.rst Normal file
View File

@@ -0,0 +1,7 @@
POST /rest/system/ping
======================
Returns a ``{"ping": "pong"}`` object.
.. note::
Due to being a POST request, this method requires using an API key or CSRF token, as opposed to the GET request to the same URL.

7
rest/system-reset-post.rst Normal file
View File

@@ -0,0 +1,7 @@
POST /rest/system/reset
=======================
Post with empty body to immediately *reset* syncthing. This means
renaming all folder directories to temporary, unique names, wiping all
indexes and restarting. This should probably not be used during normal
operations...

4
rest/system-restart-post.rst Normal file
View File

@@ -0,0 +1,4 @@
POST /rest/system/restart
=========================
Post with empty body to immediately restart syncthing.

4
rest/system-shutdown-post.rst Normal file
View File

@@ -0,0 +1,4 @@
POST /rest/system/shutdown
==========================
Post with empty body to cause syncthing to exit and not restart.

20
rest/system-status-get.rst Normal file
View File

@@ -0,0 +1,20 @@
GET /rest/system/status
=======================
Returns information about current system status and resource usage.
.. code:: json
{
"alloc": 30618136,
"cpuPercent": 0.006944836512046966,
"extAnnounceOK": {
"udp4://announce.syncthing.net:22026": true,
"udp6://announce-v6.syncthing.net:22026": true
},
"goroutines": 49,
"myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
"pathSeparator": "/",
"sys": 42092792,
"tilde": "/Users/jb"
}

13
rest/system-upgrade-get.rst Normal file
View File

@@ -0,0 +1,13 @@
GET /rest/system/upgrade
========================
Checks for a possible upgrade and returns an object describing the
newest version and upgrade possibility.
.. code:: json
{
"latest": "v0.10.27",
"newer": false,
"running": "v0.10.27+5-g36c93b7"
}

5
rest/system-upgrade-post.rst Normal file
View File

@@ -0,0 +1,5 @@
POST /rest/system/upgrade
=========================
Perform an upgrade to the newest released version and restart. Does
nothing if there is no newer version than currently running.

13
rest/system-version-get.rst Normal file
View File

@@ -0,0 +1,13 @@
GET /rest/system/version
========================
Returns the current syncthing version information.
.. code:: json
{
"arch": "amd64",
"longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
"os": "darwin",
"version": "v0.10.27+3-gea8c3de"
}

259
users/autostart.rst Normal file
View File

@@ -0,0 +1,259 @@
Starting Syncthing Automatically
================================
.. warning::
This page may be outdated and requires review.
Windows
-------
There is currently no official installer available for Windows. However,
there are a number of easy solutions.
Third-party Tools
~~~~~~~~~~~~~~~~~
There are a number of third-party utilities which aim to address this
issue. These typically provide an installer, let Syncthing start
automatically, and a more polished user experience (e.g. by behaving as
a "proper" Windows application, rather than forcing you to start your
browser to interact with Syncthing).
.. seealso:: :ref:`Windows GUI Wrappers <contrib-windows>`, :ref:`Cross-platform GUI Wrappers <contrib-all>`.
Start on Login
~~~~~~~~~~~~~~
Starting Syncthing on login, without a console window or browser opening
on start, is relatively easy.
1. Find the correct link of the Windows binary from the `Syncthing
website <https://github.com/syncthing/syncthing/releases>`__ (choose
**amd64** if you have a 64-bit version of Windows)
2. Extract the files in the folder (``syncthing-windows-*``) in the zip
to the folder ``C:\syncthing``
3. Go to the ``C:\syncthing`` folder, make a file named
``syncthing.bat``
4. Right-click the file and choose **Edit**. The file should open in
Notepad or your default text editor.
5. Paste the following command into the file and save the changes:
``start "Syncthing" syncthing.exe -no-console -no-browser``
6. Right-click on ``syncthing.bat`` and press "Create Shortcut"
7. Right-click the shortcut file ``syncthing.bat - Shortcut`` and click
**Copy**
8. Click **Start**, click **All Programs**, then click **Startup**.
Right-click on **Startup** then click **Open**.
|Setup Screenshot|
9. Paste the shortcut (right-click in the folder and choose **Paste**,
or press ``CTRL+V``)
Syncthing will now automatically start the next time Windows boots. No
console or browser window will pop-up. Access the interface by browsing
to http://localhost:8384/
If you prefer slower indexing but a more responsive system during scans,
copy the following command instead of the command in step 5:
``start "Syncthing" /low syncthing.exe -no-console -no-browser``
Run independent of user login
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
There are important security considerations with this approach. If you do not
secure Syncthing's GUI (and REST API), then **any** process running with
**any** permissions can read/write **any** file on your filesystem, by opening
a connection with Syncthing.
Therefore, you **must** ensure that you set a GUI password, or run Syncthing
as an unprivileged user.
With the above configuration, syncthing only starts when a user logs in
onto the machine. This is not optimal on servers, where a machine can
run long times after a reboot without anyone logged in. In this case, it
is best to create a service that runs as soon as Windows starts. This
can be achieved using nssm.
Note that starting Syncthing on login is the preferred approach for
almost any end-user scenario. The only scenario where running Syncthing
as a service makes sense is for (mostly) headless servers, administered
by a sysadmin who knows enough to understand the security implications.
1. Download and extract `nssm <http://nssm.cc/download>`__ to a folder
where it can stay (e.g. *c:Files* or the syncthing folder.
2. run *nssm.exe install syncthing*
3. Select ``syncthing.exe`` in the first tab and enter
``-no-console -no-browser`` as Arguments
|Configuration Screenshot|
4. at the Details tab you can switch to *Automatic (Delayed Start)* to
start it only some time after boot and speed up the boot process
(optional)
5. At the *Log On* tab you can enter a username and password for the
user to run syncthing as. This user needs to have access to all the
synced folders. Usually, you can leave it as the System account.
6. At the Process Tab you can change the priority to low if you want a
more responsive system at the cost of longer sync time
7. Click the *Install Service* Button
8. Start the service using the windows service manager, enter
``sc start syncthing`` in a console window or restart the PC.
9. Connect to the Syncthing UI, enable HTTPS, and set a secure username
and password.
Mac OS X
--------
Using `homebrew <http://brew.sh>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. ``brew install syncthing``
2. Follow the info to autostart syncthing using launchctl. At the moment
this is done using this command:
``launchctl load ~/Library/LaunchAgents/homebrew.mxcl.syncthing.plist``.
Without homebrew
~~~~~~~~~~~~~~~~
Download syncthing for Mac:
https://github.com/syncthing/syncthing/releases/latest.
1. Copy the syncthing binary (the file you would open to launch
syncthing) in a directory called ``bin`` in your home directory. If
"bin" does not exist, create it.
2. Edit the ``syncthing.plist`` (located in /etc/macosx-launchd) in the
two places that refer to your home directory; that is, replace
/Users/jb with your actual home directory location.
3. Copy the ``syncthing.plist`` file to ``~/Library/LaunchAgents``. If
you have trouble finding this location select the "Go" menu in Finder
and choose "Go to folder..." and then type
``~/Library/LaunchAgents``. Copying to ~/Library/LaunchAgents will
require admin password in most cases.
4. Log out and back in again. Or, if you do not want to log out, you can
run this command in terminal:
``launchctl load ~/Library/LaunchAgents/syncthing.plist``
**Note:** You probably want to turn off "Start Browser" in the web GUI
settings to avoid it opening a browser window on each login. Then, to
access the GUI type 127.0.0.1:8384 (by default) into Safari.
Linux
-----
Ubuntu like systems
~~~~~~~~~~~~~~~~~~~
1. Click the dashboard (hit 'Win' button).
2. Open 'Startup Applications'.
3. Click 'Add'.
4. Fill out the form:
- Name: Syncthing
- Command: /path/to/syncthing/binary -no-browser
-home="/home/your\_user/.config/syncthing"
Supervisord
~~~~~~~~~~~
Add following to your /etc/supervisord.conf.
::
[program:syncthing]
command = /path/to/syncthing/binary -no-browser -home="/home/some_user/.config/syncthing"
directory = /home/some_user/
autorestart = True
user = some_user
systemd
~~~~~~~
systemd is a suite of system management daemons, libraries, and
utilities designed as a central management and configuration platform
for the Linux computer operating system. It also offers users the
ability to manage services under the user's control with a per-user
systemd instance, enabling users to start, stop, enable, and disable
their own units. Service files for system are provided by syncthing and
can be found in
```etc/linux-systemd`` <https://github.com/syncthing/syncthing/tree/master/etc/linux-systemd>`__.
Several distros (including arch linux) ship these service files with the
syncthing package. If your distro provides a systemd service file for
syncthing you can skip step 2.
How to use the system instance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Running synchting as a system service ensures that syncthing is run at
startup even if the syncthing user has no active session.
1. Create the user who should run the service, or choose an existing
one.
2. Copy the ``system/syncthing@.service`` file into the `load path of
the system
instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
3. Enable and start the service. Append the syncthing user after the
``@``:
::
systemctl enable syncthing@myuser.service
systemctl start syncthing@myuser.service
How to use the user instance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Running synchting as a user service ensures that syncthing is run after
the syncthing user has created a session (e.g. via the graphical login
screen or ssh). This could be used e.g. on a multiuser desktop computer
when you want to avoid unnecessarly running syncthing instances.
1. Create the user who should run the service, or choose an existing
one.
2. Copy the ``user/syncthing.service`` file into the `load path of the
user
instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
To do this without root privileges you can use
``~/.config/systemd/user/``.
3. Enable and start the service:
::
systemctl --user enable syncthing.service
systemctl --user start syncthing.service
To check if syncthing runs properly you can use the ``status``
subcommand:
::
systemctl status syncthing@myuser.service
systemctl --user status syncthing.service
Using the journal
^^^^^^^^^^^^^^^^^
Systemd logs everything into the journal. You can easily acces syncthing
log messages (``-e`` lets the pager jump to the very end):
::
journalctl -e -u syncthing@myuser.service
journalctl -e --user-unit=syncthing.service
Debugging
^^^^^^^^^
If you are asked on the bugtracker to start syncthing with specific
environment variables it will not work the easy way. Systemd isolates
each service and it cannot access global environment variables. The
solution is to add this variables to the service file instead. Just use:
::
systemctl edit syncthing@myuser.service
systemctl --user edit syncthing.service
This will create an additional configuration file automatically and you
can define (or overwrite) further service parameters like e.g.
``Environment=STTRACE=model``.
.. |Configuration Screenshot| image:: st1.png
.. |Setup Screenshot| image:: st2.png

198
users/config.rst Normal file
View File

@@ -0,0 +1,198 @@
###################
Configuration Files
###################
.. warning::
This page may be outdated and requires review.
Attributes have been added that are not documented.
Syncthing uses a single directory to store configuration, crypto keys
and index caches. The location defaults to ``~/.config/syncthing``
(Unixes), ``%AppData%/Syncthing`` (Windows XP),
``%localappdata%/Syncthing`` (Windows 7/8) or
``~/Library/Application Support/Syncthing`` (Mac) but is also settable
at runtime using the ``-home`` flag. In this directory you'll generally
see something like the following files:
- ``cert.pem``: The device's RSA public key, named "cert" for legacy
reasons.
- ``key.pem``: The device's RSA private key. This needs to be
protected.
- ``config.xml``: The configuration file, in XML format.
- ``https-cert.pem`` and ``https-key.pem``: The certificate and key for
HTTPS GUI connections.
- ``index/``: A directory holding the database with metadata and hashes
of the files currently on disk and available from peers.
- ``csrftokens.txt``: A list of recently issued CSRF tokens (for
protection against browser cross site request forgery).
Config File Format
==================
The following is an example default configuration file:
.. code:: xml
<configuration version="2">
<folder id="default" directory="/Users/jb/Sync" ro="false" ignorePerms="false">
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA"></device>
</folder>
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA" name="jborg-mbp">
<address>dynamic</address>
</device>
<gui enabled="true" tls="true">
<address>127.0.0.1:54096</address>
<user>jb</user>
<password>$2a$10$EKaTIcpz2...</password>
<apikey>O80CDOJ9LVUVCMHFK2OJDO4T882735</apikey>
</gui>
<options>
<listenAddress>:54097</listenAddress>
<globalAnnounceServer>announce.syncthing.net:22025</globalAnnounceServer>
<globalAnnounceEnabled>true</globalAnnounceEnabled>
<localAnnounceEnabled>true</localAnnounceEnabled>
<parallelRequests>16</parallelRequests>
<maxSendKbps>0</maxSendKbps>
<rescanIntervalS>60</rescanIntervalS>
<reconnectionIntervalS>60</reconnectionIntervalS>
<maxChangeKbps>10000</maxChangeKbps>
<startBrowser>true</startBrowser>
<upnpEnabled>true</upnpEnabled>
<urAccepted>0</urAccepted>
</options>
</configuration>
The following sections should be present in a well formed config file.
configuration
-------------
The root element.
Attributes
~~~~~~~~~~
- ``version``: The config version. ``2`` is current.
folder
------
One or more ``folder`` elements must be present in the file. Each
element describes one folder.
Within the ``folder`` element one or more ``device`` element should be
present. These must contain the ``id`` attribute and nothing else.
Mentioned devices are those that will be sharing the folder in question.
Each mentioned device must have a separate ``device`` element later in
the file. It is customary that the local device ID is included in all
repositories. Syncthing will currently add this automatically if it is
not present in the configuration file.
Attributes
~~~~~~~~~~
- ``id``: The folder ID, must be unique. (mandatory)
- ``directory``: The directory where the folder is stored on this
device; not sent to other devices. (mandatory)
- ``ro``: True if the folder is read only (will not be modified by
syncthing) on this device. (optional, defaults to ``false``)
- ``ignorePerms``: True if the folder should `ignore
permissions <http://forum.syncthing.net/t/v0-8-10-ignore-permissions/263>`__.
Children
~~~~~~~~
- One or mode ``device`` elements.
device
------
One or more ``device`` elements must be present in the file. Each
element describes a device participating in the cluster. It is customary
to include a ``device`` element for the local device; syncthing will
currently add one if it is not present.
Attributes
~~~~~~~~~~
- ``id``: The device ID. This must be written in canonical form, that
is without any spaces or dashes. (mandatory)
- ``name``: A friendly name for the device. (optional)
Children
~~~~~~~~
- One or mode ``address`` elements.
address
-------
The address section is only valid inside of ``device`` elements. It
contains a single address, on one of the following forms:
- IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
optionally followed by a port number.
- ``dynamic``: The address will be resolved using discovery.
gui
---
There must be exactly one ``gui`` element.
Attributes
~~~~~~~~~~
- ``enabled``: ``true``/``false``
- ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS
Children
~~~~~~~~
- ``address``: One or more address elements must be present, containing
an ``ip:port`` listen address.
- ``username`` and ``password``: Set to require authentication.
``password`` contains the bcrypt hash of the real password.
- ``apikey``: If set, this is the API key that enables usage of the REST interface.
options
-------
There must be exactly one ``options`` element. It contains the following
configuration settings as children;
- ``listenAddress`` : ``host:port`` or ``:port`` string denoting an
address to listen for BEP (sync protocol) connections. More than one
``listenAddress`` may be given. (default ``0.0.0.0:22000``)
- ``globalAnnounceServer`` : ``host:port`` where a global announce
server may be reached. (default \`announce.syncthing.net:22025´)
- ``globalAnnounceEnabled``: ``true``/``false`` (default ``true``)
- ``localAnnounceEnabled``: ``true``/``false`` (default ``true``)
- ``parallelRequests``: The maximum number of outstanding block
requests to have against any given peer. (default ``16``)
- ``maxSendKbps``: Rate limit
- ``rescanIntervalS``: The number of seconds to wait between each scan
for modification of the local repositories. (default ``60``) A value
of 0 disables the scanner.
- ``reconnectionIntervalS``: The number of seconds to wait between each
attempt to connect to currently unconnected devices. (default ``60``)
- ``maxChangeKbps``: The maximum rate of change allowed for a single
file. When this rate is exceeded, further changes to the file are not
announced, until the rate is reduced below the limit. (default
``10000``)
- ``startBrowser``: ``true``/``false`` (default ``true``)
- ``upnpEnabled``: ``true``/``false`` (default ``true``)
- ``urAccepted``: Whether the user as accepted to submit anonymous
usage data. The default, ``0``, mean the user has not made a choice,
and syncthing will ask at some point in the future. ``-1`` means no,
``1`` means yes.

152
users/contrib.rst Normal file
View File

@@ -0,0 +1,152 @@
Community Contributions
=======================
This page lists integrations, addons and packagings of syncthing created
by the community. Like all documentation pages, it's wiki editable so
feel free to edit and add your own.
GUI Wrappers
------------
.. _contrib-all:
Cross-platform
~~~~~~~~~~~~~~
- https://github.com/syncthing/syncthing-gtk
- https://github.com/alex2108/syncthing-tray (Tray icon only)
Android
~~~~~~~
- https://github.com/syncthing/syncthing-android
Ubuntu
~~~~~~
- https://github.com/icaruseffect/syncthing-ubuntu-indicator
.. _contrib-windows:
Windows
~~~~~~~
- https://github.com/iss0/SyncthingTray
- https://github.com/bloones/SyncThingWin (Windows service helper and
tray icon)
- https://github.com/canton7/SyncTrayzor (Windows host for Syncthing.
Installer, auto-start, built-in browser, tray icon, folder watcher,
and more)
- https://github.com/kreischweide/metrothing (Windows UI to monitor
multiple Synchthing instances through the REST API)
OS X
~~~~
- https://github.com/m0ppers/syncthing-bar
Kindle Touch
~~~~~~~~~~~~
- https://github.com/gutenye/syncthing-kindle
Packages and Bundlings
----------------------
ArchLinux
~~~~~~~~~
- https://www.archlinux.org/packages/?name=syncthing
- https://www.archlinux.org/packages/?name=syncthing-gtk
- https://aur.archlinux.org/packages/syncthing-inotify
- https://aur.archlinux.org/packages/syncthing-discosrv
arkOS
~~~~~
Syncthing is included in arkOS, https://arkos.io/.
Debian / Ubuntu
~~~~~~~~~~~~~~~
- PPA: https://launchpad.net/~ytvwld/+archive/ubuntu/syncthing
- Syncthing GTK PPA:
https://launchpad.net/~nilarimogard/+archive/ubuntu/webupd8/
- https://forum.syncthing.net/t/lxle-a-respin-of-lubuntu-now-has-syncthing-included-by-default/1392
Docker
~~~~~~
- https://github.com/firecat53/dockerfiles/tree/master/syncthing (runs
Syncthing and/or builds the binary from source)
- https://github.com/firecat53/dockerfiles/tree/master/syncthing\_discovery
(Global announce server in a container)
- https://github.com/joeybaker/docker-syncthing/ A fully baked docker
container that allows custom config and will keep your settings and
data past docker image restarts.
Fedora
~~~~~~
- https://github.com/thunderbirdtr/syncthing\_rpm (SRPM, binary
packages coming)
- https://copr.fedoraproject.org/coprs/tune2fs/syncthing/ (RPMs, based
on https://github.com/thunderbirdtr/syncthing\_rpm)
FreeBSD
~~~~~~~
- http://www.freshports.org/net/syncthing/
OpenSUSE
~~~~~~~~
- http://software.opensuse.org/package/syncthing
Synology NAS
~~~~~~~~~~~~
- http://packages.synocommunity.com/ Add url to Package Center in DSM.
(NOTE: This page is not readable in your web browser. You can browse
the files at https://synocommunity.com/packages). Numerous CPU
architectures are supported. SPK's may be older versions, however you
can execute a Syncthing version upgrade via Web-GUI after
installation on Synology device. As Syncthing is marked as beta by
the SynoCommunity, you need to enable beta-versions in the settings.
QNAP NAS
~~~~~~~~
- http://forum.qnap.com/viewtopic.php?f=320&t=97035&start=45#p429896
QPKG (Qnap Package) Available for ALL models x86, x86\_64, Arm (all
including new models)
Integrations
------------
REST API Bindings
~~~~~~~~~~~~~~~~~
- Ruby: https://github.com/retgoat/syncthing-ruby
- Python: https://github.com/Astalaseven/syncthing-python
Ports
~~~~~
- Swift: https://github.com/dapperstout/pulse-swift
- Java: https://github.com/dapperstout/pulse-java
- PHP: https://github.com/cebe/pulse-php-discover (Only Discovery so
far)
Configuration management
~~~~~~~~~~~~~~~~~~~~~~~~
- Saltstack: https://bitbucket.org/StartledPhoenix/saltstack-syncthing
- Puppet: https://github.com/whefter/puppet-syncthing
- Command line interface: https://github.com/syncthing/syncthing-cli
Other
-----
`Pulse <http://ind.ie/pulse/>`__ is a rebranding / fork of syncthing.

23
users/exit-codes.rst Normal file
View File

@@ -0,0 +1,23 @@
Exit Codes
==========
These are the known exit codes returned by Syncthing:
==== =======
Code Meaning
==== =======
0 Success / Shutdown
1 Error
2 Upgrade not available
3 Restarting
5 Upgrading
==== =======
Some of these exit codes are only returned when running without a
monitor process (with environment variable ``STNORESTART`` set).
Exit codes over 125 are usually returned by the shell/binary
loader/default signal handler.
Exit codes over 128+N on Unix usually represent the signal which caused
the process to exit. For example, ``128 + 9 (SIGKILL) = 137``.

236
users/faq.rst Normal file
View File

@@ -0,0 +1,236 @@
FAQ
===
General
-------
What is Syncthing?
~~~~~~~~~~~~~~~~~~
Syncthing is an application that lets you synchronize your files across
multiple devices. This means the creation, modification or deletion of
files on one machine will automatically be replicated to your other
devices. We believe your data is your data alone and you deserve to
choose where it is stored. Therefore Syncthing does not upload your data
to the cloud but exchanges your data across your machines as soon as
they are online at the same time.
Is it "syncthing", "Syncthing" or "SyncThing"?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It's **Syncthing**, although the command and source repository is
spelled ``syncthing`` so it may be referred to in that way as well. It's
definitely not [STRIKEOUT:SyncThing], even though the abbreviation
``st`` is used in some circumstances and file names.
How does Syncthing differ from BitTorrent Sync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The two are different and not related. Syncthing and BitTorrent Sync
accomplish some of the same things, namely syncing files between two or
more computers.
BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file
synchronization tool available for Windows, Mac, Linux, Android, iOS,
Windows Phone, Amazon Kindle Fire and BSD.
`1 <http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an
open source file synchronization tool.
Syncthing uses an open and documented protocol, and likewise the
security mechanisms in use are well defined and visible in the source
code. BitTorrent Sync uses an undocumented, closed protocol with unknown
security properties.
Usage
-----
What things are synced?
~~~~~~~~~~~~~~~~~~~~~~~
The following is *always* synchronized;
- File Contents
- File Modification Times
The following is synchronized or not, depending;
- File Permissions (When supported by file system. On Windows, only the
read only bit is synchronized)
- Symbolic Links (When supported by the OS. On Windows Vista and up,
requires administrator privileges. Links are synced as is and are not
followed.)
The following is *not* synchronized;
- File or Directory Owners and Groups (not preserved)
- Directory Modification Times (not preserved)
- Hard Links (followed, not preserved)
- Extended Attributes, Resource Forks (not preserved)
- Windows, POSIX or NFS ACLs (not preserved)
- Devices, FIFOs, and Other Specials (ignored)
Is synchronization fast?
~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing segments files into pieces, called blocks, to transfer data
from one device to another. Therefore, multiple devices can share the
synchronization load, in a similar way as the torrent protocol. The more
devices you have online (and synchronized), the faster an additional
device will receive the data because small blocks will be fetched from
all devices in parallel.
Syncthing handles renaming files and updating their metadata in an
efficient manner. This means that renaming a large file will not cause a
retransmission of that file. Additionally, appending data to existing
large files should be handled efficiently as well.
Should I keep my device IDs secret?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No. The IDs are not sensitive. Given a device ID it's possible to find
the IP address for that node, if global discovery is enabled on it.
Knowing the device ID doesn't help you actually establish a connection
to that node or get a list of files, etc.
For a connection to be established, both nodes need to know about the
other's device ID. It's not possible (in practice) to forge a device ID.
(To forge a device ID you need to create a TLS certificate with that
specific SHA-256 hash. If you can do that, you can spoof any TLS
certificate. The world is your oyster!)
See also `Understanding Device
IDs <http://docs.syncthing.net/dev/device-ids.html>`__.
What if there is a conflict?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing does recognize conflicts. When a file has been modified on two
devices simultaneously, one of the files will be renamed to
``<filename>.sync- conflict-<date>-<time>.<ext>``. The device which has
the larger value of the first 63 bits for his device ID will have his
file marked as the conflicting file. Note that we only create
``sync-conflict`` files when the actual content differs.
Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` files
are treated as normal files after they are created, so they are
propagated between devices. We do this because the conflict is detected
and resolved on one device, creating the ``sync-conflict`` file, but
it's just as much of a conflict everywhere else and we don't know which
of the conflicting files is the "best" from the user point of view.
Moreover, if there's something that automatically causes a conflict on
change you'll end up with
``sync-conflict-...sync-conflict -...-sync-conflict`` files.
How to configure multiple users on a single machine?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each user should run their own Syncthing instance. Be aware that you
might need to configure ports such that they do not overlap (see the
config.xml).
Is Syncthing my ideal backup application?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No, Syncthing is not a backup application because all changes to your
files (modification, deletion, etc) will be propagated to all your
devices. You can enable versioning, but we encourage the use of other
tools to keep your data safe from your (or our) mistakes.
Why is there no iOS client?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternative implementation Syncthing (using the Syncthing protocol) are
being developed at this point in time to enable iOS support.
Additionally, it seems that the next version of Go will support the
darwin-arm architecture such that we can compile the mainstream code for
the iOS platform.
Why does it use so much CPU?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. When new or changed files are detected, or Syncthing starts for the
first time, your files are hashed using SHA-256.
2. Data that is sent over the network is first compressed and then
encrypted using AES-128. When receiving data, it must be decrypted
and decompressed.
Hashing, compression and encryption cost CPU time. Also, using the GUI
causes a certain amount of CPU usage. Note however that once things are
*in sync* CPU usage should be negligible.
How can I exclude files with brackets (``[]``) in the name?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The patterns in .stignore are glob patterns, where brackets are used to
denote character ranges. That is, the pattern ``q[abc]x`` will match the
files ``qax``, ``qbx`` and ``qcx``.
To match an actual file *called* ``q[abc]x`` the pattern needs to
"escape" the brackets, like so: ``q\[abc\]x``.
Why is the setup more complicated than BTSync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Security over convenience. In Syncthing you have to setup both sides to
connect two nodes. An attacker can't do much with a stolen node ID,
because you have to add the node on the other side too. You have better
control where your files are transferred.
How do I access the web GUI from another computer?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default listening address is 127.0.0.1:8384, so you can only access
the GUI from the same machine. Change the ``GUI listen address`` through
the web UI from ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the
config.xml:
.. code:: xml
<gui enabled="true" tls="false">
<address>127.0.0.1:8384</address>
to
.. code:: xml
<gui enabled="true" tls="false">
<address>0.0.0.0:8384</address>
Then the GUI is accessible from everywhere. You should most likely set a
password and enable HTTPS now. You can do this from inside the GUI.
If both your computers are Unixy (Linux, Mac, etc) You can also leave
the GUI settings at default and use an ssh port forward to access it.
For example,
.. code:: bash
$ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
will log you into othercomputer.example.com, and present the *remote*
Syncthing GUI on http://localhost:9090 on your *local* computer. You
should not open more than one Syncthing GUI in a single browser due to
conflicting X-CSRFTokens. Any modification will be rejected. See `Issue
720 <https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__
to work around this limitation.
The CSRF tokens are stored using cookies. Therefore, if you get the
message
``Syncthing seems to be experiencing a problem processing your request``,
you should verify the cookie settings of your browser.
Why do I see Syncthing twice in task manager?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One process manages the other, to capture logs and manage restarts. This
makes it easier to handle upgrades from within Syncthing itself, and
also ensures that we get a nice log file to help us narrow down the
cause for crashes and other bugs.
Where do syncthing logs go to?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing logs to stdout by default. On Windows Syncthing by default
also creates ``syncthing.log`` in Syncthing's home directory (check
``-help`` to see where that is).

63
users/firewalls.rst Normal file
View File

@@ -0,0 +1,63 @@
Firewalls
=========
Port Forwards
-------------
If you have a NAT router which supports UPnP, the easiest way to get a
working port forward is to make sure UPnP setting is enabled on both
Syncthing and the router – Syncthing will try to handle the rest. If it
succeeds you will see a message in the console saying:
::
Created UPnP port mapping for external port XXXXX on UPnP device YYYYY.
If this is not possible or desirable you should set up a port forward
for port **22000/TCP**, or the port set in the *Sync Protocol Listen
Address* setting. The external forwarded port and the internal
destination port has to be the same (i.e. 22000/TCP).
Communication in Syncthing works both ways. Therefore if you set up port
forwards for one device, other devices will be able to connect to it
even when they are behind a NAT network or firewall.
Local Firewall
--------------
If your PC has a local firewall, you will need to open the following
ports for incoming traffic:
- Port **22000/TCP** (or the actual listening port if you have changed
the *Sync Protocol Listen Address* setting.)
- Port **21025/UDP** (for discovery broadcasts)
Remote Web GUI
--------------
To be able to access the web GUI from other computers, you need to
change the *GUI Listen Address* setting from the default
``127.0.0.1:8384`` to ``0.0.0.0:8384``. You also need to open the port
in your local firewall if you have one.
Tunneling via SSH
~~~~~~~~~~~~~~~~~
If you have SSH access to the machine running Syncthing but would rather
not open the web GUI port to the outside world, you can access it
through a SSH tunnel instead. You can start a tunnel with a command like
the following:
::
ssh -L 9999:localhost:8384 machine
This will bind to your local port 9999 and forward all connections from
there to port 8384 on the target machine. This still works even if
Syncthing is bound to listen on localhost only.
You can forward multiple ports corresponding to many machines this way,
but because Syncthing uses session cookies for the entire domain (i.e.
your local machine), you will need to connect to each control panel in a
separate browser instance or explicitly issue a browser reload when
switching between them.

BIN
users/foldermaster.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 456 KiB

24
users/foldermaster.rst Normal file
View File

@@ -0,0 +1,24 @@
Folder Master
=============
A folder can be set in "master mode" among the folder settings.
.. figure:: foldermaster.png
The intention is for this to be used on devices where a "master copy" of
files are kept - where the files are not expected to be changed on other
devices or where such changes would be undesirable.
In master mode, all changes from other devices in the cluster are
ignored. Changes are still *received* so the folder may become "out of
sync", but no changes will be applied.
When a master folder becomes out of sync, a red "Override Changes"
button is shown at the bottom of the folder details.
.. figure:: override.png
Clicking this button will make enforce the master's current state on the
rest of the cluster. Any changes made to files will be overwritten by
the version on the master, any files that don't exist on the master will
be deleted, and so on.

142
users/ignoring.rst Normal file
View File

@@ -0,0 +1,142 @@
Ignoring Files
==============
If some files should not be synchronized to other nodes, a file called
``.stignore`` can be created containing file patterns to ignore. The
``.stignore`` file must be placed in the root of the repository. The
``.stignore`` file itself will never be synced to other nodes, although
it can ``#include`` files that *are* synchronized between nodes. All
patterns are relative to the repository root.
Patterns
--------
The ``.stignore`` file contains a list of file or path patterns. The
*first* pattern that matches will decide the fate of a given file.
- Regular file names match themselves, i.e. the pattern ``foo`` matches
the files ``foo``, ``subdir/foo`` as well as any directory named
``foo``. Spaces are treated as regular characters.
- Asterisk matches zero or more characters in a filename, but does not
match the directory separator. ``te*st`` matches ``test``,
``subdir/telerest`` but not ``tele/rest``.
- Double asterisk matches as above, but also directory separators.
``te**st`` matches ``test``, ``subdir/telerest`` and
``tele/sub/dir/rest``.
- Question mark matches a single character that is not the directory
separator. ``te??st`` matches ``tebest`` but not ``teb/st`` or
``test``.
- A pattern beginning with ``/`` matches in the current directory only.
``/foo`` matches ``foo`` but not ``subdir/foo``.
- A pattern beginning with ``#include`` results in loading patterns
from the named file. It is an error for a file to not exist or be
included more than once. Note that while this can be used to include
patterns from a file in a subdirectory, the patterns themselves are
still relative to the repository *root*. Example:
``#include more-patterns.txt``.
- A pattern beginning with ``!`` negates the pattern: matching files
are *included* (that is, *not* ignored). This can be used to override
more general patterns that follow. Note that files in ignored
directories can not be re-included this way. This is due to the fact
that syncthing stops scanning when it reaches an ignored directory,
so doesn't know what files it might contain.
- A pattern beginning with ``(?i)`` enables case-insensitive pattern
matching. ``(?i)test`` matches ``test``, ``TEST`` and ``tEsT``. The
``(?i)`` prefix can be combined with other patterns, for example the
pattern ``(?i)!picture*.png`` indicates that ``Picture1.PNG`` should
be synchronized. Note that case-insensitive patterns must start with
``(?i)`` when combined with other flags.
- A line beginning with ``//`` is a comment and has no effect.
Example
-------
Given a directory layout:
::
foo
foofoo
bar/
baz
quux
quuz
bar2/
baz
frobble
My Pictures/
Img15.PNG
and an ``.stignore`` file with the contents:
.. code:: xml
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
all files and directories called "foo", ending in a "2" or starting with
"qu" will be ignored. The end result becomes
.. code:: xml
foo # ignored, matches "foo"
foofoo # synced, does not match "foo" but would match "foo*" or "*foo"
bar/ # synced
baz # synced
quux # ignored, matches "qu*"
quuz # synced, matches "qu*" but is excluded by the preceding "!quuz"
bar2/ # ignored, matched "*2"
baz # ignored, due to parent being ignored
frobble # ignored, due to parent being ignored; "!frobble" doesn't help
My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern
Img15.PNG # ignored, due to parent being ignored
.. raw:: html
<p class="message warning">
Please note that directory patterns ending with a slash
``some/directory/`` matches the content of the directory, but not the
directory itself. If you want the pattern to match the director and it's
content, make sure it does not have a ``/`` at the end of the pattern.
.. raw:: html
</p>
Effects on "In Sync" Status
---------------------------
Currently the effects on who is in sync with what can be a bit confusing
when using ignore patterns. This should be cleared up in a future
version...
Assume two nodes, Alice and Bob, where Alice has 100 files to share, but
Bob ignores 25 of these. From Alice's point of view Bob will become
about 75% in sync (the actual number depends on the sizes of the
individual files) and remain in "Syncing" state even though it is in
fact not syncing anything (issue
`#623 <https://github.com/syncthing/syncthing/issues/623>`__). From
Bob's point of view it's 100% up to date but will show fewer files in
both the local and global view.
If Bob adds files that have already been synced to the ignore list, they
will remain in the "global" view but disappear from the "local" view.
The end result is more files in the global repository than in the local,
but still 100% in sync (issue
`#624 <https://github.com/syncthing/syncthing/issues/624>`__). From
Alice's point of view, Bob will remain 100% in sync until the next
reconnect, because Bob has already announce that he has the files that
are now suddenly ignored.

BIN
users/override.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

126
users/security.rst Normal file
View File

@@ -0,0 +1,126 @@
###################
Security Principles
###################
Security is one of the primary project goals. This means that it should
not be possible for an attacker to join a cluster uninvited, and it
should not be possible to extract private information from intercepted
traffic. Currently this is implemented as follows.
All traffic is protected by TLS. To prevent uninvited nodes from joining
a cluster, the certificate fingerprint of each node is compared to a
preset list of acceptable nodes at connection establishment. The
fingerprint is computed as the SHA-256 hash of the certificate and
displayed in BASE32 encoding to form a reasonably compact and convenient
string.
Incoming requests for file data are verified to the extent that the
requested file name must exist in the local index and the global model.
For information about ensuring you are running the code you think you
are and for reporting security vulnerabilities, please see the official
`security page <http://syncthing.net/security.html>`__.
Information Leakage
===================
Global Discovery
----------------
When global discovery is enabled, syncthing sends an announcement packet
every 30 minutes to the global discovery server, so that it can keep a
mapping between your device ID and external IP. Also, when connecting to
other devices that have not been seen on the local network, a query is
sent to the global discovery server containing the device ID of the
requested device. The discovery server is currently **hosted by
@calmh**. Global discovery defaults to **on**.
When turned off, devices with dynamic addresses not on the local network
cannot be found and connected to.
If a different global discovery server is configured, no data is sent to
the default global discovery server.
Local Discovery
---------------
When local discovery is enabled, syncthing sends broadcast (IPv4) and
multicast (IPv6) packets to the local network every 30 seconds. The
packets contain the device ID and listening port. Local discovery
defaults to **on**.
An eavesdropper on the local network can deduce which machines are
running syncthing with local discovery enabled, and what their device
IDs are.
When turned off, devices with dynamic addresses on the local network
cannot be found and connected to.
Upgrade Checks
--------------
When automatic upgrades are enabled, syncthing checks for a new version
at startup and then once every twelve hours. This is by an HTTPS request
to the download site for releases, currently **hosted at GitHub**.
Automatic upgrades default to **on** (unless syncthing was compiled with
upgrades disabled).
Even when automatic upgrades are disabled in the configuration, an
upgrade check as above is done when the GUI is loaded, in order to show
the "Upgrade to ..." button when necessary. This can be disabled only by
compiling syncthing with upgrades disabled.
In effect this exposes the majority of the syncthing population to
tracking by the operator of the download site (currently GitHub). That
data is not available to outside parties (including @calmh etc), except
that download counts per release binary are available in the GitHub API.
The upgrade check (or download) requests *do not* contain any
identifiable information about the user, device, syncthing version, etc.
Usage Reporting
---------------
When usage reporting is enabled, syncthing reports usage data at startup
and then every 24 hours. The report is sent as an HTTPS POST to the
usage reporting server, currently **hosted by @calmh**. The contents of
the usage report can be seen behind the "Preview" link in settings.
Usage reporting defaults to **off** but the GUI will ask once about
enabling it, shortly after the first install.
The reported data is protected from eavesdroppers, but the connection to
the usage reporting server itself may expose the client as running
syncthing.
Sync Connections (BEP)
----------------------
Sync connections are attempted to all configured devices, when the
address is possible to resolve. The sync connection is based on TLS 1.2.
The TLS certificates are sent in clear text (as in HTTPS etc), meaning
that the certificate Common Name (by default ``syncthing``) is visible.
An eavesdropper can deduce that this is a syncthing connection and
calculate the device ID:s involved based on the hashes of the sent
certificates.
Likewise, if the sync port (default 22000) is accessible from the
internet, a port scanner may discover it, attempt a TLS negotiation and
thus obtain the device certificate. This provides the same information
as in the eavesdropper case.
Web GUI
-------
If the web GUI is accessible, it exposes the device as running
syncthing. The web GUI defaults to being reachable from the **local host
only**.
In Short
========
Parties doing surveillance on your network (whether that be corporate
IT, the NSA or someone else) will be able to see that you use syncthing,
and your device ID's `are OK to share
anyway <http://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret>`__,
but the actual transmitted data is protected as well as we can. Knowing
your device ID can expose your IP address, using global discovery.

BIN
users/st1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

BIN
users/st2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

68
users/versioning.rst Normal file
View File

@@ -0,0 +1,68 @@
File Versioning
===============
.. warning::
This page may be out of date and requires review.
External versioning requires documenting.
There are 3 types of File Versioning. When you select each in the web
interface, a short description of each is shown to help you decide.
No File Versioning
------------------
This is the default setting. With no file versioning, files that are
replaced or deleted on one device are deleted on other devices that the
directory is shared with. (Note: If a folder is marked "Master Folder"
on a device, that device will not accept changes to the files in the
folder, and therefore will not have files replaced or deleted.)
Simple File Versioning
----------------------
With "Simple File Versioning" files are moved to the ".stversions"
folder (inside your shared folder) when replaced or deleted on a remote
device. This option also takes a value in an input titled "Keep
Versions" which tells SyncThing how many old versions of the file it
should keep. For example, if you set this value to 5, if a file is
replaced 5 times on a remote device, you will see 5 time-stamped
versions on that file in the ".stversions" folder on the other devices
sharing the same folder.
Staggered File Versioning
-------------------------
With "Staggered File Versioning" files are also moved to the
".stversions" folder (inside your shared folder) when replaced or
deleted on a remote device (just like "Simple File Versioning"),
however, Version are automatically deleted if they are older then the
maximum age or exceed the number of files allowed in an interval.
The following intervals are used and they each have a maximum number of
files that will be kept for each.
- 1 Hour - For the first hour, the most recent version is kept every 30
seconds.
- 1 Day - For the first day, the most recent version is kept every
hour.
- 30 Days - For the first 30 days, the most recent version is kept
every day.
- Until Maximum Age - Until the maximum age, the most recent version is
kept every week.
Maxiumum Age
~~~~~~~~~~~~
The "Maximum Age" input is the maximum time to keep a version in days.
For example, to keep replaced or deleted files in the ".stversions"
folder for an entire year, use 365. If only for 10 days, use 10. **Note:
Set to 0 to keep versions forever.**
Versions Path
~~~~~~~~~~~~~
With "Staggered File Versioning" method (only), if you would like to
specify where removed and deleted files are stored as part of the
Versioning feature, you can specify the path in the "Versions Path"
input after this method is selected. [*More detail needed here: Can this
be a relative path, or must it be an absolute path?*\ ]