SYNCTHING()

Project Goals
This is the syncthing project. The following are the project goals:

1.  Define a protocol for synchronization of a file repository between a number of collaborating nodes. The protocol should be well defined, unambiguous, easily understood, free to use, efficient, secure and language neutral. This is the Block Exchange Protocol https://github.com/calmh/syncthing/blob/master/protocol/PROTOCOL.md.

2.  Provide the reference implementation to demonstrate the usability of said protocol. This is the syncthing utility. It is the hope that alternative, compatible implementations of the protocol will come to exist.

The two are evolving together; the protocol is not to be considered stable until syncthing 1.0 is released, at which point it is locked down for incompatible changes.

Syncthing does not use the BitTorrent protocol. The reasons for this are 1) we don't know if BitTorrent Sync does either, so there's nothing to be compatible with, 2) BitTorrent includes a lot of functionality for making sure large swarms of selfish agents behave and somehow work towards a common goal. Here we have a much smaller swarm of cooperative agents and a simpler approach will suffice.

Systemd
The systemd services for Syncthing and its discovery server can be used to start, stop, restart and enable them to run at boot.

  Syncthing
Syncthing is the main sync client and can be controlled using systemd using the commands below. Since Syncthing is run for a particular user, replace 'username' in the commands below with the name of the user you want it to run it under.

    Start Syncthing:                    systemctl start syncthing@username
    Stop Syncthing:                     systemctl stop syncthing@username
    Restart Syncthing:                  systemctl restart syncthing@username
    Enable Syncthing at Boot:           systemctl enable syncthing@username
    Disable Syncthing at Boot:          systemctl disable syncthing@username

  Discovery Server
The discovery server is an optional service that can be run and connected to by Syncthing in place of the default. To have clients connect to a custom discovery server, you'll want to start the service on your server, then open "~/.syncthing/config.xml" and replace "announce.syncthing.net" with your custom discovery server's address.

    Start Discovery Server Service:     systemctl start syncthing-discosrv
    Stop Discovery Server Service:      systemctl stop syncthing-discosrv
    Restart Discovery Server Service:   systemctl restart syncthing-discosrv
    Enable Discovery Server at Boot:    systemctl enable syncthing-discosrv
    Disable Discovery Server at Boot:   systemctl disable syncthing-discosrv

Configuring
The config folder is automatically generated when syncthing is run for the first time, and can be found (by default) @ '~/.syncthing'.

The admin GUI starts automatically when the service is running, and remains available (by default) @ http://localhost:8080.

On the left is the list of "repositories", or directories to synchronize. On the right is the list of nodes. Currently there is only one node, the local node. The first thing you need to do is tell each node about the other node so they can talk to each other. Click the "Add Node" button on each node. You'll get the "Add Node" dialog, where you need to input the node ID of the other node and give it a short name. If you have both nodes GUI available on the same machine (say via remote desktop or a port forward) you can simply cut and paste the node ID from the bottom of one dialog to the other. Otherwise it is probably easiest to send the ID:s in a mail to yourself or something similar.

The node IDs are quite long and unwieldy, but this is part of the security of the system. They uniquely identify node's key so that each node can be assured of who it's talking to. The node ID is not a password and does not need to be kept secret.

Once you click "Save" the new node will appear on right side of the GUI and a prompt will be shown to indicate the need for a restart.

Syncthing needs to be restarted for configuration changes like new nodes and repositories to take effect. We shouldn't restart just yet though, because we also need to share the repository with the new node. Click "Edit" on the repository to the left, and check the checkbox for the other node before saving and restarting.

When you click restart syncthing will first restart, then come back up and after a while (up to a minute) connect to the other node.

At this point the two nodes share an empty directory. Adding files to the Sync directory on either node will synchronize those files to the other side. Each node scans for changes every sixty seconds, so changes can take a bit over a minute to propagate to the other side.

An up to date version of this documentation that includes images can be found @ http://discourse.syncthing.net/t/getting-started/46.

Online Documentation
Additional documentation can be found online @ discourse site http://discourse.syncthing.net/category/documentation.

License
All documentation and protocol specifications are licensed under the Creative Commons Attribution 4.0 International License http://creativecommons.org/licenses/by/4.0/.

All code is licensed under the MIT License https://github.com/calmh/syncthing/blob/master/LICENSE.