chore(config-shared): Remove emacs config files
[BK-2020-03.git] / config-shared / syncthing / INSTRUCTIONS.md
... / ...
CommitLineData
1<!DOCTYPE html>
2<meta charset="utf-8">
3
4# Install and configure `syncthing`
5
6Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on
72020-04-27T14:37Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and
8last updated on 2020-04-27T17:59Z.
9
10## 1. Summary
11
12Syncthing is a decentralized file-synchronization program that permits
13sharing of files over the Internet with computers that have been
14configured to trust one another.
15
16## 2. Instructions
17
18The following are instructions for installing Syncthing onto a
19GNU/Linux Debian 10 machine.
20
21### 2.1. Install `syncthing` via `apt-get`
22
23Update the local repository package lists with `$ sudo apt-get update`.
24
25Install the `syncthing` package with `$ sudo apt-get install syncthing`.
26
27Note: As of 2020-04-27, Debian 10 Buster uses Syncthing version `1.0.0`.
28
29### 2.2. Enable automatic startup via `systemd` service.
30
31Syncthing can be started automatically via `systemd` as a system
32service upon boot or a user service upon login. If `syncthing` was
33installed from the Debian 10 repository (ex: via `apt-get`), then the
34necessary service files (ex: `syncthing@.service` ) should already be
35installed. If not, see the detailed autostart instructions for where
36to download a copy of the service
37files.<sup>[[1]](#syncthing_20200331_autostart)</sup>
38
39#### 2.2.a. Enable automatic startup via `systemd` upon boot (system service).
40
41For a system service, identify the user under which to run
42`syncthing`. Even though `syncthing` will be run upon startup (without
43needing a user to login first), files cannot be created or modified by
44`syncthing` with permissions of a specified user. In this example,
45`baltakatei` will be the user. This means an appropriate directory for
46a `syncthing` shared folder would be `/home/baltakatei/Sync/`.
47
48Alternatively, if `syncthing` were running as a headless server where
49no user is expected to directly modify files in the server's file
50system, then a dedicated dummy user named `syncthing-user` might be
51appropriate.
52
53The commands to create a `systemd` system service under user
54`baltakatei` are:
55
56 $ sudo systemctl enable syncthing@baltakatei.service
57 $ sudo systemctl start syncthing@baltakatei.service
58
59The following notifications may appear while running these commands:
60
61 $ systemctl enable syncthing@baltakatei.service
62 Created symlink /etc/systemd/system/multi-user.target.wants/syncthing@baltakatei.service → /lib/systemd/system/syncthing@.service.
63
64The status of the new system service can be verified via:
65
66 $ systemctl status syncthing@baltakatei.service
67
68The resulting status data will resemble:
69
70 $ systemctl status syncthing@baltakatei.service
71 ● syncthing@baltakatei.service - Syncthing - Open Source Continuous File Synchronization for baltakatei
72 Loaded: loaded (/lib/systemd/system/syncthing@.service; enabled; vendor preset: enabled)
73 Active: active (running) since Mon 2020-04-27 09:01:00 PDT; 3min 34s ago
74 Docs: man:syncthing(1)
75 Main PID: 2799 (syncthing)
76 Tasks: 23 (limit: 1132)
77 Memory: 45.3M
78 CGroup: /system.slice/system-syncthing.slice/syncthing@baltakatei.service
79 └─2799 /usr/bin/syncthing -no-browser -no-restart -logflags=0
80
81#### 2.2.b. Enable automatic startup via `systemd` upon login (user service).
82
83For a user service, identify which user under which to run
84`syncthing`. In this example, `baltakatei` will be the user. This
85means an appropriate directory for a `syncthing` shared folder would
86be `/home/baltakatei/Sync/`.
87
88The commands to create a `systemd` user service under user
89`baltakatei` are:
90
91 $ systemctl --user enable syncthing.service
92 $ systemctl --user start syncthing.service
93
94The following notifications may appear while running these commands:
95
96 Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/syncthing.service → /usr/lib/systemd/user/syncthing.service.
97
98The status of the new user service can be verified via:
99
100 $ systemctl --user status syncthing.service
101
102The resulting status data will resemble:
103
104 $ systemctl --user status syncthing.service
105 ● syncthing.service - Syncthing - Open Source Continuous File Synchronization
106 Loaded: loaded (/usr/lib/systemd/user/syncthing.service; enabled; vendor preset: enabled)
107 Active: active (running) since Mon 2020-04-27 09:57:08 PDT; 14s ago
108 Docs: man:syncthing(1)
109 Main PID: 3284 (syncthing)
110 CGroup: /user.slice/user-1000.slice/user@1000.service/syncthing.service
111 └─3284 /usr/bin/syncthing -no-browser -no-restart -logflags=0
112
113### 2.3. Configure `syncthing`
114
115Some initial tasks should be performed with a new `syncthing` instance
116in order to configure it to work with other `syncthing` instances.
117
118a. Connect to the Syncthing **WebUI**
119b. Determine the instance's **Device ID**.
120c. Add a **remote device**.
121d. Create a **shared folder**.
122
123#### 2.3.a. Connect to the **WebUI**
124
125Syncthing may be configured via a "WebUI", which is a configuration
126page accessible by a web browser such as Firefox. The address that
127must be entered into a web browser's address bar may be:
128
129 http://localhost:8384
130 http://127.0.0.1:8384
131
132If the `syncthing` instance is running on a headless machine
133accessible only via `ssh`, then the WebUI may be accessed by setting
134up an "SSH tunnel". One end of the tunnel will be the headless machine
135and the other end will be a machine equipped with a keyboard, monitor,
136and a web browser. In order to establish an `ssh` tunnel with a remote
137headless machine's `syncthing` isntance, run one of the following
138commands (both are equivalent).
139
140 $ ssh -L 9999:localhost:8384 username@yourserver
141 $ ssh -L 127.0.0.1:9999:127.0.0.1:8384 username@yourserver
142
143Then, open your web browser and enter `http://localhost:9999` into the
144address bar. This will cause the WebUI of the `syncthing` instance
145running on the remote machine `yourserver` to appear.
146
147NOTE: The details of setting up machines to connect via `ssh` are not
148described here.
149
150#### 2.3.b. Determine the **Device ID**
151
152Upon setting up a new `syncthing` instance on a new device, a unique
153identifier is generated (derived from the hash of the instance's
154public key). This identifier is called a "**Device ID**". This ID is
155what one `syncthing` instance uses to connect to another. The ID may
156be found by selecting the "Actions" menu at the top right of the WebUI
157webpage and selecting "Show ID" from the dropdown menu. A 64-character
158string of numbers and capitalized letters will appear as well as a QR
159code encoding this same string.
160
161#### 2.3.c. Add a **remote device**
162
163Once you have a `syncthing` instance's Device ID, then you can enter
164it into another instance in order to establish a connection between
165the two instances through which files in shared folders may be
166synchronized.
167
168A "Remote Device" (a remote `syncthing` instance) may be added via the
169WebUI by clicking on the "Add Remote Device" button and entering the
170Device ID in the "General" tab. Shared folders may be specified in the
171"Sharing" tab. The Device IDs of `syncthing` instances already
172detected on the local network may already be populated in the General
173tab but if you care about the security of your data you should
174double-check that the Device ID matches before clicking "Save".
175
176#### 2.3.d. Create a **shared folder**.
177
178The "Shared Folder" fulfills the primary function of `syncthing`:
179synchronizing file changes of specified directories between different
180machines across the internet.
181
182You may create a "Shared Folder" by clicking the "Add Folder"
183button. A window called "Add Folder" should appear with four tabs:
184"General", "Sharing", "File Versioning", and "Ignore Patterns".
185
186The following fields of the "General" tab should be populated as
187follows:
188
189* **Folder Label**: A label that appears in the WebUI. I would suggest
190 something like `username_PURPOSE` since this label is suggested to
191 Remote Devices when a folder is first shared.
192
193* **Folder ID**: A unique alphanumeric string that is automatically
194 generated by `syncthing`. You shouldn't have to change this.
195
196* **Folder Path**: The path within the file system of the machine in
197 which `syncthing` is running. For GNU/Linux Debian machines, I would
198 suggest something like: `~/Sync/username_PURPOSE` which should
199 auto-expand into `/home/username/Sync/username_PURPOSE`.
200
201You may also specify with which Remote Devices to share this new
202Shared Folder by clicking on the "Sharing" tab.
203
204In the "File Versioning" tab, you may specify rules for keeping local
205versions of files in this sparticular Shared Folder. By default, no
206versions are kept.
207
208In the "Ignore Patterns" tab, you may specify rules for ignoring files
209based upon their file names. By default, no ignore patterns are
210specified.
211
212## 3. References
213- <a name="syncthing_20200331_autostart">1.</a> ["Starting Syncthing Automatically"][1]. Date: 2020-03-31. [syncthing.net](https://syncthing.net). Date Accessed: 2020-04-27. [Archive link](https://web.archive.org/web/20200414114635/https://docs.syncthing.net/users/autostart.html). Archive date: 2017-04-14.
214
215[1]: https://docs.syncthing.net/users/autostart.html
216[bktei_2020_homepage]: http://baltakatei.com
217[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/
218
219
220<hr>
221<p xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#">This work by <a rel="cc:attributionURL" href="http://baltakatei.com"><span rel="cc:attributionName">Steven Baltakatei Sandoval</span></a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser" target="_blank" rel="license noopener noreferrer" style="display: inline-block;">CC BY-SA 4.0</a><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser"><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-by_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-sa_icon.svg" /></a></p>