X-Git-Url: https://zdv2.bktei.com/gitweb/BK-2020-03.git/blobdiff_plain/045f579aaf0dce58b91b45e49548efdc797c52f7..1dc4ab4a4faa75f66279389b788a5939cf58ce43:/config-shared/syncthing/INSTRUCTIONS.md diff --git a/config-shared/syncthing/INSTRUCTIONS.md b/config-shared/syncthing/INSTRUCTIONS.md index dd68fb7..7ff3f6c 100644 --- a/config-shared/syncthing/INSTRUCTIONS.md +++ b/config-shared/syncthing/INSTRUCTIONS.md @@ -3,7 +3,9 @@ # Install and configure `syncthing` -Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on 2020-04-27T14:37Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and last updated on 2020-04-27T16:28Z. +Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on +2020-04-27T14:37Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and +last updated on 2020-04-27T17:59Z. ## 1. Summary @@ -13,7 +15,8 @@ configured to trust one another. ## 2. Instructions -The following are instructions for installing Syncthing onto a GNU/Linux Debian 10 machine. +The following are instructions for installing Syncthing onto a +GNU/Linux Debian 10 machine. ### 2.1. Install `syncthing` via `apt-get` @@ -51,12 +54,30 @@ The commands to create a `systemd` system service under user `baltakatei` are: $ sudo systemctl enable syncthing@baltakatei.service - $ sudo systemctl start syncthing@baltakatei.service + $ sudo systemctl start syncthing@baltakatei.service + +The following notifications may appear while running these commands: + + $ systemctl enable syncthing@baltakatei.service + Created symlink /etc/systemd/system/multi-user.target.wants/syncthing@baltakatei.service → /lib/systemd/system/syncthing@.service. The status of the new system service can be verified via: $ systemctl status syncthing@baltakatei.service +The resulting status data will resemble: + + $ systemctl status syncthing@baltakatei.service + ● syncthing@baltakatei.service - Syncthing - Open Source Continuous File Synchronization for baltakatei + Loaded: loaded (/lib/systemd/system/syncthing@.service; enabled; vendor preset: enabled) + Active: active (running) since Mon 2020-04-27 09:01:00 PDT; 3min 34s ago + Docs: man:syncthing(1) + Main PID: 2799 (syncthing) + Tasks: 23 (limit: 1132) + Memory: 45.3M + CGroup: /system.slice/system-syncthing.slice/syncthing@baltakatei.service + └─2799 /usr/bin/syncthing -no-browser -no-restart -logflags=0 + #### 2.2.b. Enable automatic startup via `systemd` upon login (user service). For a user service, identify which user under which to run @@ -68,12 +89,126 @@ The commands to create a `systemd` user service under user `baltakatei` are: $ systemctl --user enable syncthing.service - $ systemctl --user start syncthing.service + $ systemctl --user start syncthing.service + +The following notifications may appear while running these commands: + + Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/syncthing.service → /usr/lib/systemd/user/syncthing.service. The status of the new user service can be verified via: $ systemctl --user status syncthing.service +The resulting status data will resemble: + + $ systemctl --user status syncthing.service + ● syncthing.service - Syncthing - Open Source Continuous File Synchronization + Loaded: loaded (/usr/lib/systemd/user/syncthing.service; enabled; vendor preset: enabled) + Active: active (running) since Mon 2020-04-27 09:57:08 PDT; 14s ago + Docs: man:syncthing(1) + Main PID: 3284 (syncthing) + CGroup: /user.slice/user-1000.slice/user@1000.service/syncthing.service + └─3284 /usr/bin/syncthing -no-browser -no-restart -logflags=0 + +### 2.3. Configure `syncthing` + +Some initial tasks should be performed with a new `syncthing` instance +in order to configure it to work with other `syncthing` instances. + +a. Connect to the Syncthing **WebUI** +b. Determine the instance's **Device ID**. +c. Add a **remote device**. +d. Create a **shared folder**. + +#### 2.3.a. Connect to the **WebUI** + +Syncthing may be configured via a "WebUI", which is a configuration +page accessible by a web browser such as Firefox. The address that +must be entered into a web browser's address bar may be: + + http://localhost:8384 + http://127.0.0.1:8384 + +If the `syncthing` instance is running on a headless machine +accessible only via `ssh`, then the WebUI may be accessed by setting +up an "SSH tunnel". One end of the tunnel will be the headless machine +and the other end will be a machine equipped with a keyboard, monitor, +and a web browser. In order to establish an `ssh` tunnel with a remote +headless machine's `syncthing` isntance, run one of the following +commands (both are equivalent). + + $ ssh -L 9999:localhost:8384 username@yourserver + $ ssh -L 127.0.0.1:9999:127.0.0.1:8384 username@yourserver + +Then, open your web browser and enter `http://localhost:9999` into the +address bar. This will cause the WebUI of the `syncthing` instance +running on the remote machine `yourserver` to appear. + +NOTE: The details of setting up machines to connect via `ssh` are not +described here. + +#### 2.3.b. Determine the **Device ID** + +Upon setting up a new `syncthing` instance on a new device, a unique +identifier is generated (derived from the hash of the instance's +public key). This identifier is called a "**Device ID**". This ID is +what one `syncthing` instance uses to connect to another. The ID may +be found by selecting the "Actions" menu at the top right of the WebUI +webpage and selecting "Show ID" from the dropdown menu. A 64-character +string of numbers and capitalized letters will appear as well as a QR +code encoding this same string. + +#### 2.3.c. Add a **remote device** + +Once you have a `syncthing` instance's Device ID, then you can enter +it into another instance in order to establish a connection between +the two instances through which files in shared folders may be +synchronized. + +A "Remote Device" (a remote `syncthing` instance) may be added via the +WebUI by clicking on the "Add Remote Device" button and entering the +Device ID in the "General" tab. Shared folders may be specified in the +"Sharing" tab. The Device IDs of `syncthing` instances already +detected on the local network may already be populated in the General +tab but if you care about the security of your data you should +double-check that the Device ID matches before clicking "Save". + +#### 2.3.d. Create a **shared folder**. + +The "Shared Folder" fulfills the primary function of `syncthing`: +synchronizing file changes of specified directories between different +machines across the internet. + +You may create a "Shared Folder" by clicking the "Add Folder" +button. A window called "Add Folder" should appear with four tabs: +"General", "Sharing", "File Versioning", and "Ignore Patterns". + +The following fields of the "General" tab should be populated as +follows: + +* **Folder Label**: A label that appears in the WebUI. I would suggest + something like `username_PURPOSE` since this label is suggested to + Remote Devices when a folder is first shared. + +* **Folder ID**: A unique alphanumeric string that is automatically + generated by `syncthing`. You shouldn't have to change this. + +* **Folder Path**: The path within the file system of the machine in + which `syncthing` is running. For GNU/Linux Debian machines, I would + suggest something like: `~/Sync/username_PURPOSE` which should + auto-expand into `/home/username/Sync/username_PURPOSE`. + +You may also specify with which Remote Devices to share this new +Shared Folder by clicking on the "Sharing" tab. + +In the "File Versioning" tab, you may specify rules for keeping local +versions of files in this sparticular Shared Folder. By default, no +versions are kept. + +In the "Ignore Patterns" tab, you may specify rules for ignoring files +based upon their file names. By default, no ignore patterns are +specified. + ## 3. References - 1. ["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.