chore(config-shared): Remove emacs config files
[BK-2020-03.git] / config-shared / syncthing / INSTRUCTIONS.md
index dd68fb7bf4af526cff10b64a29d256256eabfcee..7ff3f6cc7fb4bae881c26bd59af42b55e7767831 100644 (file)
@@ -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
 - <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.