diff --git a/_static/syncthing.css b/_static/syncthing.css index 64d3cd83b..cc15c90b6 100644 --- a/_static/syncthing.css +++ b/_static/syncthing.css @@ -1,10 +1,10 @@ .rst-content p, .rst-content p.admonition-title, .rst-content li, .rst-content table.docutils td, .rst-content table.docutils th { - font-size: 120%; + font-size: 14pt; line-height: 1.4; } .rst-content code, .rst-content div[class^='highlight'] pre { - font-size: 110%; + font-size: 12pt; line-height: 1.4; } .rst-content li { diff --git a/dev/building.rst b/dev/building.rst index 8f7a3968d..8af8e0744 100644 --- a/dev/building.rst +++ b/dev/building.rst @@ -5,7 +5,7 @@ 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 + 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. @@ -21,7 +21,7 @@ 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 +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. @@ -107,10 +107,10 @@ The following ``build.go`` subcommands and options exist. - ``go run build.go test`` -- run the tests. -- ``go run build.go tar`` -- create a syncthing tar.gz dist file in the +- ``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 +- ``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. @@ -124,10 +124,10 @@ 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. + 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 + distribution of Syncthing for Windows (current architecture) with upgrading disabled. Building without Git diff --git a/dev/debugging.rst b/dev/debugging.rst index af8bca95e..db0f6f332 100644 --- a/dev/debugging.rst +++ b/dev/debugging.rst @@ -3,7 +3,7 @@ Debugging Syncthing =================== -There's a lot that happens behind the covers, and syncthing is generally +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. @@ -63,13 +63,13 @@ 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 +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. +On windows, it needs to be set prior to running Syncthing. :: diff --git a/dev/device-ids.rst b/dev/device-ids.rst index 3e6b8ce82..b5a7a7c36 100644 --- a/dev/device-ids.rst +++ b/dev/device-ids.rst @@ -11,12 +11,12 @@ Keys ==== To understand device IDs we need to look at the underlying mechanisms. -At first startup, syncthing will create an public/private key pair. +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 +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 @@ -93,8 +93,8 @@ 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 +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; @@ -102,12 +102,12 @@ possibilities here; 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 +- 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 +- 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 @@ -172,7 +172,7 @@ here: 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 +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. @@ -231,7 +231,7 @@ are various possible solutions; 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 + 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. diff --git a/dev/issues.rst b/dev/issues.rst index d2543af87..edc4c8a3f 100644 --- a/dev/issues.rst +++ b/dev/issues.rst @@ -26,15 +26,16 @@ error", "Rendered moot by #123" and so on. We don't use the "invalid" or - **docs** - Something requires documenting. -- **easy** - This could be easily fixed, probably an hours work or - less. +- **easy** - This could be easily fixed, probably an hour's work or + less. These issues are good starting points for new contributors. - **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``. + *other* issues. You can see this as a soft ``wontfix``. (A hard + ``wontfix`` is simply a close with a short explanation why.) - **pr-bugfix** - This pull request *fixes* a bug. This is different from the ``bug`` label, as there may also be pull requests with for @@ -48,3 +49,39 @@ error", "Rendered moot by #123" and so on. We don't use the "invalid" or requires more discussion. - **protocol** - This requires a change to the protocol. + +Milestone +--------- + +There are milestones for major and sometimes minor versions. An issues +being assigned to a milestone means it is a blocker - the release can't +be made without the issue being closed. Issues not assigned to a +milestone can be handled whenever. + +Assignee +-------- + +Users can be assigned to issues. We don't usually do so. Sometimes +someone assigns themself to an issue to indicate "I'm working on this" +to avoid others doing so too. It's not mandatory. + +Locking +------- + +We don't normally lock issues (prevent further discussion on them). +There are some exceptions though; + +- "Popular" issues that attract lots of "me too" and "+1" comments. + These are noise and annoy people with useless notifications via mail + and in the Github interface. Once the issue is clear and it suffers + from this symptom I may lock it. + +- Contentious bikeshedding discussions. After two sides in a discussion + have clarified their points, there is no point arguing endlessly + about it. As above, this may get closed. + +- Duplicates. Once an issue has been identified as a duplicate of + another issue, it may be locked to prevent further discussion there. + The intention is to move the discussion to the other (referenced) + issue, while someone just doing a search and jumping on the first + match might otherwise resurrect discussion in the duplicate. diff --git a/dev/release.rst b/dev/release.rst index ea559d1ca..c48257bb6 100644 --- a/dev/release.rst +++ b/dev/release.rst @@ -4,7 +4,7 @@ Creating a Release Prerequisites ------------- -- Push access to the syncthing repo, for pushing a new tag. +- 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. diff --git a/dev/rest.rst b/dev/rest.rst index 3f3e24f3d..0c8d7ade1 100644 --- a/dev/rest.rst +++ b/dev/rest.rst @@ -3,7 +3,7 @@ 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 +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 diff --git a/events/itemfinished.rst b/events/itemfinished.rst index 0b402dbb5..64a7ccf6d 100644 --- a/events/itemfinished.rst +++ b/events/itemfinished.rst @@ -1,7 +1,7 @@ ItemFinished ------------ -Generated when syncthing ends synchronizing a file to a newer version. A +Generated when Syncthing ends synchronizing a file to a newer version. A successfull operation: .. code:: json @@ -35,3 +35,5 @@ An unsuccessfull operation: "type": "file" } } + +The ``action`` field is either ``update`` or ``delete``. diff --git a/events/itemstarted.rst b/events/itemstarted.rst index 96ef12918..253591790 100644 --- a/events/itemstarted.rst +++ b/events/itemstarted.rst @@ -1,7 +1,7 @@ ItemStarted ----------- -Generated when syncthing begins synchronizing a file to a newer version. +Generated when Syncthing begins synchronizing a file to a newer version. .. code:: json @@ -16,3 +16,5 @@ Generated when syncthing begins synchronizing a file to a newer version. "action": "update" } } + +The ``action`` field is either ``update`` or ``delete``. diff --git a/events/starting.rst b/events/starting.rst index 128b99664..4313b5157 100644 --- a/events/starting.rst +++ b/events/starting.rst @@ -1,7 +1,7 @@ Starting -------- -Emitted exactly once, when syncthing starts, before parsing +Emitted exactly once, when Syncthing starts, before parsing configuration etc. .. code:: json diff --git a/events/startupcomplete.rst b/events/startupcomplete.rst index 32b6a5f7a..030c37ced 100644 --- a/events/startupcomplete.rst +++ b/events/startupcomplete.rst @@ -1,7 +1,7 @@ StartupCompleted ---------------- -Emitted exactly once, when initialization is complete and syncthing is +Emitted exactly once, when initialization is complete and Syncthing is ready to start exchanging data with other devices. .. code:: json diff --git a/index.rst b/index.rst index f0f5810ae..80878cedd 100644 --- a/index.rst +++ b/index.rst @@ -12,13 +12,21 @@ As a developer looking to get started with a contribution, see :ref:`how to buil Contact ------- -* To report bugs or request features, please use the `issue tracker `_. Before you do so, make sure you are running the `latest version `_, and please do a quick search to see if the issue has already been reported. +* If you're looking for specific people to talk to, check out the :ref:`project-presentation`. + +* To report bugs or request features, please use the `issue tracker + `_. Before you do so, make + sure you are running the `latest version + `_, and please do a + quick search to see if the issue has already been reported. + + .. figure:: issues.png * To report security issues, please follow the instructions on the `Security page `_. * To get help and support, to discuss scenarios, or just connect with other users and developers you can head over to the `friendly forum `_. -* For a more real time experience, there's also an IRC channel ``#syncthing`` on Freenode. +* For a more real time experience, there's also an IRC channel ``#syncthing`` on `Freenode `_. * For other concerns you may reach out to members of the core team, currently `@calmh `_, `@AudriusButkevicius `_ and `@Zillode `_. @@ -31,6 +39,7 @@ The main documentation for the site is organized into a couple of sections. You intro/getting-started intro/gui + intro/project-presentation .. toctree:: :caption: For Users diff --git a/intro/getting-started.rst b/intro/getting-started.rst index 22ef6feba..33f80e83b 100644 --- a/intro/getting-started.rst +++ b/intro/getting-started.rst @@ -14,6 +14,14 @@ 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. +A film version of this transcript is available on YouTube (contributed by +@theincogtion). `This video `_ +shows how to install Syncthing on Ubuntu/Debian/Mint using PPA, also available +in `German `_. `This video +`_ shows how to install Syncthing +on Windows, also available in `German +`_ + Installing ---------- diff --git a/intro/project-presentation.rst b/intro/project-presentation.rst new file mode 100644 index 000000000..77264e959 --- /dev/null +++ b/intro/project-presentation.rst @@ -0,0 +1,55 @@ +.. _project-presentation: + +Project Presentation +==================== + +These are the various projects under the Syncthing umbrella and the +people responsible for maintaining them. + +`syncthing `__ +------------------------------------------------------ + +``syncthing`` is the core CLI application, used by the Android and +native UI wrappers. + +Maintainers +~~~~~~~~~~~ + +- Jakob Borg / `@calmh `_ (Founder) +- Audrius Butkevicius / + `@AudriusButkevicius `_ +- Lode Hoste / `@Zillode `_ + +`syncthing-android `__ +---------------------------------------------------------------------- + +``syncthing-android`` is the Android packaging and native UI on top of +syncthing. + +Maintainers +~~~~~~~~~~~ + +- Felix Ableitner / `@Nutomic `_ + (Founder) +- Lode Hoste / `@Zillode `_ + +`syncthing-inotify `__ +---------------------------------------------------------------------- + +``syncthing-inotify``\ is a filesystem notifications watcher on top of +syncthing. + +Maintainers +~~~~~~~~~~~ + +- Lode Hoste / `@Zillode `_ (Founder) + +`syncthing-gtk `__ +-------------------------------------------------------------- + +``syncthing-gtk`` is a native UI wrapper on top of syncthing + +Maintainers +~~~~~~~~~~~ + +- Tomas Cerveny `@kozec `_ (Founder) diff --git a/issues.png b/issues.png new file mode 100644 index 000000000..31936df5d Binary files /dev/null and b/issues.png differ diff --git a/rest/db-scan-post.rst b/rest/db-scan-post.rst index 59a36b7ad..7260a3b8d 100644 --- a/rest/db-scan-post.rst +++ b/rest/db-scan-post.rst @@ -1,15 +1,16 @@ 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. +Request immediate rescan of a folder, or a specific path within a folder. +Takes the mandatory parameter `folder` (folder ID), an optional parameter +``sub`` (path relative to the folder root) and an optional parameter ``next``. 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. The +``next`` argument delays Syncthing's automated rescan interval for a given +amount of seconds. 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 +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 diff --git a/rest/system-config-post.rst b/rest/system-config-post.rst index d5ba8b9ff..3555312a0 100644 --- a/rest/system-config-post.rst +++ b/rest/system-config-post.rst @@ -1,7 +1,6 @@ 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. +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. diff --git a/rest/system-reset-post.rst b/rest/system-reset-post.rst index 0b90eb6cb..42ee18863 100644 --- a/rest/system-reset-post.rst +++ b/rest/system-reset-post.rst @@ -1,7 +1,7 @@ POST /rest/system/reset ======================= -Post with empty body to immediately *reset* syncthing. This means +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... diff --git a/rest/system-restart-post.rst b/rest/system-restart-post.rst index d2f7bf2cf..862130024 100644 --- a/rest/system-restart-post.rst +++ b/rest/system-restart-post.rst @@ -1,4 +1,4 @@ POST /rest/system/restart ========================= -Post with empty body to immediately restart syncthing. +Post with empty body to immediately restart Syncthing. diff --git a/rest/system-shutdown-post.rst b/rest/system-shutdown-post.rst index 5d21c047b..cef3291cd 100644 --- a/rest/system-shutdown-post.rst +++ b/rest/system-shutdown-post.rst @@ -1,4 +1,4 @@ POST /rest/system/shutdown ========================== -Post with empty body to cause syncthing to exit and not restart. +Post with empty body to cause Syncthing to exit and not restart. diff --git a/rest/system-version-get.rst b/rest/system-version-get.rst index 0091ce607..93782530b 100644 --- a/rest/system-version-get.rst +++ b/rest/system-version-get.rst @@ -1,7 +1,7 @@ GET /rest/system/version ======================== -Returns the current syncthing version information. +Returns the current Syncthing version information. .. code:: json diff --git a/users/autostart.rst b/users/autostart.rst index a14967c3f..22f996077 100644 --- a/users/autostart.rst +++ b/users/autostart.rst @@ -68,7 +68,7 @@ Run independent of user login 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 +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 @@ -80,7 +80,7 @@ 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 `__ to a folder - where it can stay (e.g. *c:Files* or the syncthing 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 @@ -89,7 +89,7 @@ by a sysadmin who knows enough to understand the security implications. 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 + 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 @@ -106,18 +106,18 @@ Using `homebrew `__ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. ``brew install syncthing`` -2. Follow the info to autostart syncthing using launchctl. At the moment +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: +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 + 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 @@ -162,6 +162,7 @@ Add following to your /etc/supervisord.conf. directory = /home/some_user/ autorestart = True user = some_user + environment = STNORESTART="1" systemd ~~~~~~~ @@ -171,25 +172,27 @@ 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 +their own units. Service files for system are provided by Syncthing and can be found in ```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. +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. +Running Syncthing as a system service ensures that Syncthing is run at startup +even if the Syncthing user has no active session. Since the system service +keeps Syncthing running even without an active user session, it is inteded to +be used on a *server*. 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 `__. -3. Enable and start the service. Append the syncthing user after the +3. Enable and start the service. Append the Syncthing user after the ``@``: :: @@ -200,10 +203,10 @@ startup even if the syncthing user has no active session. 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. +Running Syncthing 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). Thus, the user service is intended to be used on a *(multiuser) desktop +computer*. It avoids unnecessarly running Syncthing instances. 1. Create the user who should run the service, or choose an existing one. @@ -219,7 +222,7 @@ when you want to avoid unnecessarly running syncthing instances. systemctl --user enable syncthing.service systemctl --user start syncthing.service -To check if syncthing runs properly you can use the ``status`` +To check if Syncthing runs properly you can use the ``status`` subcommand: :: @@ -230,7 +233,7 @@ subcommand: Using the journal ^^^^^^^^^^^^^^^^^ -Systemd logs everything into the journal. You can easily acces syncthing +Systemd logs everything into the journal. You can easily acces Syncthing log messages (``-e`` lets the pager jump to the very end): :: @@ -241,10 +244,10 @@ log messages (``-e`` lets the pager jump to the very end): 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: +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: :: diff --git a/users/config.rst b/users/config.rst index 1812ddd49..588759926 100644 --- a/users/config.rst +++ b/users/config.rst @@ -95,7 +95,7 @@ Attributes - ``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``) + Syncthing) on this device. (optional, defaults to ``false``) - ``ignorePerms``: True if the folder should `ignore permissions `__. @@ -109,7 +109,7 @@ 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 +to include a ``device`` element for the local device; Syncthing will currently add one if it is not present. Attributes @@ -194,5 +194,5 @@ configuration settings as children; - ``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, + and Syncthing will ask at some point in the future. ``-1`` means no, ``1`` means yes. diff --git a/users/contrib.rst b/users/contrib.rst index d86ac635d..9bd351a70 100644 --- a/users/contrib.rst +++ b/users/contrib.rst @@ -3,9 +3,9 @@ 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. +This page lists integrations, addons and packagings of Syncthing created by +the community. Like all documentation pages, it's wiki editable so please do +edit and add your own. GUI Wrappers ------------ @@ -34,13 +34,16 @@ 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) + multiple Syncthing instances through the REST API) OS X ~~~~ @@ -109,7 +112,7 @@ OpenSUSE Synology NAS ~~~~~~~~~~~~ -- http://packages.synocommunity.com/ Add url to Package Center in DSM. +- http://packages.synocommunity.com/ Add the 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 @@ -144,11 +147,7 @@ Ports Configuration management ~~~~~~~~~~~~~~~~~~~~~~~~ -- Saltstack: https://bitbucket.org/StartledPhoenix/saltstack-syncthing +- 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 `__ is a rebranding / fork of syncthing. diff --git a/users/faq.rst b/users/faq.rst index 4a1ab220a..cb99a680c 100644 --- a/users/faq.rst +++ b/users/faq.rst @@ -86,6 +86,11 @@ 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. +Temporary files are used to store partial data downloaded from other devices. +They are automatically removed whenever a file transfer has been completed or +after the configured amount of time which is set in the configuration file (24 +hours by default). + Should I keep my device IDs secret? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -230,9 +235,30 @@ 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? +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). + +How do I upgrade Syncthing? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- If automatic upgrades is enabled (which is the default), Sycnthing will upgrade itself automatically within 24 hours of a new release. + +- The ugrade button appears in the web GUI when a new version has been released. Pressing it will perform an upgrade. + +- To force an upgrade from the command line, run ``syncthing -upgrade``. + +Note that your system should have CA certificates installed which allow a secure connection to GitHub (e.g. FreeBSD requires `sudo pkg install ca_root_nss`). If ``curl`` or ``wget`` works with normal HTTPS sites, then so should Syncthing. + +Where do I find the latest release? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We release new versions through GitHub. The latest release is always found `on +the release page `_. +Unfortunately GitHub does not provide a single URL to automatically download +the latest version. We suggest to use the GitHub API at +https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing +the JSON response. diff --git a/users/security.rst b/users/security.rst index 7aa22fb7e..99cbd5d63 100644 --- a/users/security.rst +++ b/users/security.rst @@ -27,7 +27,7 @@ Information Leakage Global Discovery ---------------- -When global discovery is enabled, syncthing sends an announcement packet +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 @@ -44,13 +44,13 @@ the default global discovery server. Local Discovery --------------- -When local discovery is enabled, syncthing sends broadcast (IPv4) and +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 +running Syncthing with local discovery enabled, and what their device IDs are. When turned off, devices with dynamic addresses on the local network @@ -59,10 +59,10 @@ cannot be found and connected to. Upgrade Checks -------------- -When automatic upgrades are enabled, syncthing checks for a new version +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 +Automatic upgrades default to **on** (unless Syncthing was compiled with upgrades disabled). Even when automatic upgrades are disabled in the configuration, an @@ -70,17 +70,17 @@ 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 +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. +identifiable information about the user, device, Syncthing version, etc. Usage Reporting --------------- -When usage reporting is enabled, syncthing reports usage data at startup +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. @@ -89,7 +89,7 @@ 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. +Syncthing. Sync Connections (BEP) ---------------------- @@ -99,7 +99,7 @@ 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 +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. @@ -112,14 +112,14 @@ 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 +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, +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 `__, but the actual transmitted data is protected as well as we can. Knowing diff --git a/users/versioning.rst b/users/versioning.rst index 3ec53fe1f..85bdfd76a 100644 --- a/users/versioning.rst +++ b/users/versioning.rst @@ -32,11 +32,11 @@ 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. +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 than 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. @@ -50,8 +50,8 @@ files that will be kept for each. - Until Maximum Age - Until the maximum age, the most recent version is kept every week. -Maxiumum Age -~~~~~~~~~~~~ +Maximum 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"