[BK-2020-03.git] / config-shared / syncthing / INSTRUCTIONS.md

<!DOCTYPE html>
<meta charset="utf-8">

# 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.<sup>[[1]](#syncthing_20200331_autostart)</sup>

#### 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
- <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.

[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/


<hr>
<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>
Commit	Line	Data
045f579a SBS	1	<!DOCTYPE html>
	2	<meta charset="utf-8">
	3
	4	# Install and configure `syncthing`
	5
17d7b803 SBS	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.
045f579a SBS	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
17d7b803 SBS	18	The following are instructions for installing Syncthing onto a
17d7b803 SBS	19	GNU/Linux Debian 10 machine.
045f579a SBS	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
71687450	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.
045f579a SBS	63
	64	The status of the new system service can be verified via:
	65
	66	$ systemctl status syncthing@baltakatei.service
	67
71687450	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
045f579a SBS	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
4a404c7e	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.
045f579a SBS	97
	98	The status of the new user service can be verified via:
	99
	100	$ systemctl --user status syncthing.service
	101
4a404c7e	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
17d7b803 SBS	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
045f579a SBS	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>