summaryrefslogtreecommitdiff
path: root/pcr/syncthing/syncthing.1
blob: 9a06ddb7f8aa97dc8f96abe4ec2abba37ad69a63 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SYNCTHING" "" "May 2014" "" "syncthing"
.
.SH "Project Goals"
This is the \fBsyncthing\fR project\. The following are the project goals:
.
.IP "1." 4
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 \fIhttps://github\.com/calmh/syncthing/blob/master/protocol/PROTOCOL\.md\fR\.
.
.IP "2." 4
Provide the reference implementation to demonstrate the usability of said protocol\. This is the \fBsyncthing\fR utility\. It is the hope that alternative, compatible implementations of the protocol will come to exist\.
.
.IP "" 0
.
.P
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\.
.
.P
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\.
.
.SH "Systemd"
The systemd services for Syncthing and its discovery server can be used to start, stop, restart and enable them to run at boot\.
.
.SS "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\.
.
.IP "\(bu" 4
\fBStart Syncthing\fR: \fBsystemctl start syncthing@username\fR
.
.IP "\(bu" 4
\fBStop Syncthing\fR: \fBsystemctl stop syncthing@username\fR
.
.IP "\(bu" 4
\fBRestart Syncthing\fR: \fBsystemctl restart syncthing@username\fR
.
.IP "\(bu" 4
\fBEnable Syncthing at Boot\fR: \fBsystemctl enable syncthing@username\fR
.
.IP "\(bu" 4
\fBDisable Syncthing at Boot\fR: \fBsystemctl disable syncthing@username\fR
.
.IP "" 0
.
.SS "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 "\fI~/\.syncthing/config\.xml\fR" and replace "\fIannounce\.syncthing\.net\fR" with your custom discovery server\'s address\.
.
.IP "\(bu" 4
\fBStart Discovery Server Service\fR: \fBsystemctl start syncthing\-discosrv\fR
.
.IP "\(bu" 4
\fBStop Discovery Server Service\fR: \fBsystemctl stop syncthing\-discosrv\fR
.
.IP "\(bu" 4
\fBRestart Discovery Server Service\fR: \fBsystemctl restart syncthing\-discosrv\fR
.
.IP "\(bu" 4
\fBEnable Discovery Server at Boot\fR: \fBsystemctl enable syncthing\-discosrv\fR
.
.IP "\(bu" 4
\fBDisable Discovery Server at Boot\fR: \fBsystemctl disable syncthing\-discosrv\fR
.
.IP "" 0
.
.SH "Configuring"
The config folder is automatically generated when syncthing is run for the first time, and can be found (by default) @ \'~/\.syncthing\'\.
.
.P
The admin GUI starts automatically when the service is running, and remains available (by default) @ \fIhttp://localhost:8080\fR\.
.
.P
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\.
.
.P
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\.
.
.P
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\.
.
.P
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\.
.
.P
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\.
.
.P
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\.
.
.P
An up to date version of this documentation that includes images can be found @ \fIhttp://discourse\.syncthing\.net/t/getting\-started/46\fR\.
.
.SH "Online Documentation"
Additional documentation can be found online @ discourse site \fIhttp://discourse\.syncthing\.net/category/documentation\fR\.
.
.SH "License"
All documentation and protocol specifications are licensed under the Creative Commons Attribution 4\.0 International License \fIhttp://creativecommons\.org/licenses/by/4\.0/\fR\.
.
.P
All code is licensed under the MIT License \fIhttps://github\.com/calmh/syncthing/blob/master/LICENSE\fR\.