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>