feature(user) Add legacy user scripts
[BK-2020-03.git] / config-shared / syncthing / INSTRUCTIONS.md
1 <!DOCTYPE html>
2 <meta charset="utf-8">
3
4 # Install and configure `syncthing`
5
6 Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on
7 2020-04-27T14:37Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and
8 last updated on 2020-04-27T17:59Z.
9
10 ## 1. Summary
11
12 Syncthing is a decentralized file-synchronization program that permits
13 sharing of files over the Internet with computers that have been
14 configured to trust one another.
15
16 ## 2. Instructions
17
18 The following are instructions for installing Syncthing onto a
19 GNU/Linux Debian 10 machine.
20
21 ### 2.1. Install `syncthing` via `apt-get`
22
23 Update the local repository package lists with `$ sudo apt-get update`.
24
25 Install the `syncthing` package with `$ sudo apt-get install syncthing`.
26
27 Note: 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
31 Syncthing can be started automatically via `systemd` as a system
32 service upon boot or a user service upon login. If `syncthing` was
33 installed from the Debian 10 repository (ex: via `apt-get`), then the
34 necessary service files (ex: `syncthing@.service` ) should already be
35 installed. If not, see the detailed autostart instructions for where
36 to download a copy of the service
37 files.<sup>[[1]](#syncthing_20200331_autostart)</sup>
38
39 #### 2.2.a. Enable automatic startup via `systemd` upon boot (system service).
40
41 For a system service, identify the user under which to run
42 `syncthing`. Even though `syncthing` will be run upon startup (without
43 needing 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
46 a `syncthing` shared folder would be `/home/baltakatei/Sync/`.
47
48 Alternatively, if `syncthing` were running as a headless server where
49 no user is expected to directly modify files in the server's file
50 system, then a dedicated dummy user named `syncthing-user` might be
51 appropriate.
52
53 The 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
59 The 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
64 The status of the new system service can be verified via:
65
66 $ systemctl status syncthing@baltakatei.service
67
68 The 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
83 For a user service, identify which user under which to run
84 `syncthing`. In this example, `baltakatei` will be the user. This
85 means an appropriate directory for a `syncthing` shared folder would
86 be `/home/baltakatei/Sync/`.
87
88 The 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
94 The 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
98 The status of the new user service can be verified via:
99
100 $ systemctl --user status syncthing.service
101
102 The 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
115 Some initial tasks should be performed with a new `syncthing` instance
116 in order to configure it to work with other `syncthing` instances.
117
118 a. Connect to the Syncthing **WebUI**
119 b. Determine the instance's **Device ID**.
120 c. Add a **remote device**.
121 d. Create a **shared folder**.
122
123 #### 2.3.a. Connect to the **WebUI**
124
125 Syncthing may be configured via a "WebUI", which is a configuration
126 page accessible by a web browser such as Firefox. The address that
127 must be entered into a web browser's address bar may be:
128
129 http://localhost:8384
130 http://127.0.0.1:8384
131
132 If the `syncthing` instance is running on a headless machine
133 accessible only via `ssh`, then the WebUI may be accessed by setting
134 up an "SSH tunnel". One end of the tunnel will be the headless machine
135 and the other end will be a machine equipped with a keyboard, monitor,
136 and a web browser. In order to establish an `ssh` tunnel with a remote
137 headless machine's `syncthing` isntance, run one of the following
138 commands (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
143 Then, open your web browser and enter `http://localhost:9999` into the
144 address bar. This will cause the WebUI of the `syncthing` instance
145 running on the remote machine `yourserver` to appear.
146
147 NOTE: The details of setting up machines to connect via `ssh` are not
148 described here.
149
150 #### 2.3.b. Determine the **Device ID**
151
152 Upon setting up a new `syncthing` instance on a new device, a unique
153 identifier is generated (derived from the hash of the instance's
154 public key). This identifier is called a "**Device ID**". This ID is
155 what one `syncthing` instance uses to connect to another. The ID may
156 be found by selecting the "Actions" menu at the top right of the WebUI
157 webpage and selecting "Show ID" from the dropdown menu. A 64-character
158 string of numbers and capitalized letters will appear as well as a QR
159 code encoding this same string.
160
161 #### 2.3.c. Add a **remote device**
162
163 Once you have a `syncthing` instance's Device ID, then you can enter
164 it into another instance in order to establish a connection between
165 the two instances through which files in shared folders may be
166 synchronized.
167
168 A "Remote Device" (a remote `syncthing` instance) may be added via the
169 WebUI by clicking on the "Add Remote Device" button and entering the
170 Device ID in the "General" tab. Shared folders may be specified in the
171 "Sharing" tab. The Device IDs of `syncthing` instances already
172 detected on the local network may already be populated in the General
173 tab but if you care about the security of your data you should
174 double-check that the Device ID matches before clicking "Save".
175
176 #### 2.3.d. Create a **shared folder**.
177
178 The "Shared Folder" fulfills the primary function of `syncthing`:
179 synchronizing file changes of specified directories between different
180 machines across the internet.
181
182 You may create a "Shared Folder" by clicking the "Add Folder"
183 button. A window called "Add Folder" should appear with four tabs:
184 "General", "Sharing", "File Versioning", and "Ignore Patterns".
185
186 The following fields of the "General" tab should be populated as
187 follows:
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
201 You may also specify with which Remote Devices to share this new
202 Shared Folder by clicking on the "Sharing" tab.
203
204 In the "File Versioning" tab, you may specify rules for keeping local
205 versions of files in this sparticular Shared Folder. By default, no
206 versions are kept.
207
208 In the "Ignore Patterns" tab, you may specify rules for ignoring files
209 based upon their file names. By default, no ignore patterns are
210 specified.
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>