X-Git-Url: https://zdv2.bktei.com/gitweb/BK-2020-03.git/blobdiff_plain/5e5ea3bcd5c7338f99307442bd158432a540079b..a36416739b399ae388da41ecd86a95e848a7397b:/config-shared/syncthing/INSTRUCTIONS.md diff --git a/config-shared/syncthing/INSTRUCTIONS.md b/config-shared/syncthing/INSTRUCTIONS.md deleted file mode 100644 index 7ff3f6c..0000000 --- a/config-shared/syncthing/INSTRUCTIONS.md +++ /dev/null @@ -1,221 +0,0 @@ - - - -# 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-27T17:59Z. - -## 1. Summary - -Syncthing is a decentralized file-synchronization program that permits -sharing of files over the Internet with computers that have been -configured to trust one another. - -## 2. Instructions - -The following are instructions for installing Syncthing onto a -GNU/Linux Debian 10 machine. - -### 2.1. Install `syncthing` via `apt-get` - -Update the local repository package lists with `$ sudo apt-get update`. - -Install the `syncthing` package with `$ sudo apt-get install syncthing`. - -Note: As of 2020-04-27, Debian 10 Buster uses Syncthing version `1.0.0`. - -### 2.2. Enable automatic startup via `systemd` service. - -Syncthing can be started automatically via `systemd` as a system -service upon boot or a user service upon login. If `syncthing` was -installed from the Debian 10 repository (ex: via `apt-get`), then the -necessary service files (ex: `syncthing@.service` ) should already be -installed. If not, see the detailed autostart instructions for where -to download a copy of the service -files.[[1]](#syncthing_20200331_autostart) - -#### 2.2.a. Enable automatic startup via `systemd` upon boot (system service). - -For a system service, identify the user under which to run -`syncthing`. Even though `syncthing` will be run upon startup (without -needing a user to login first), files cannot be created or modified by -`syncthing` with permissions of a specified user. In this example, -`baltakatei` will be the user. This means an appropriate directory for -a `syncthing` shared folder would be `/home/baltakatei/Sync/`. - -Alternatively, if `syncthing` were running as a headless server where -no user is expected to directly modify files in the server's file -system, then a dedicated dummy user named `syncthing-user` might be -appropriate. - -The commands to create a `systemd` system service under user -`baltakatei` are: - - $ sudo systemctl enable 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 -`syncthing`. In this example, `baltakatei` will be the user. This -means an appropriate directory for a `syncthing` shared folder would -be `/home/baltakatei/Sync/`. - -The commands to create a `systemd` user service under user -`baltakatei` are: - - $ systemctl --user enable 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. - -[1]: https://docs.syncthing.net/users/autostart.html -[bktei_2020_homepage]: http://baltakatei.com -[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/ - - -
-

This work by Steven Baltakatei Sandoval is licensed under CC BY-SA 4.0