[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-27T16:28Z.

## 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 status of the new user service can be verified via:

    $ systemctl --user status syncthing.service

## 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
	6	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.
	7
	8	## 1. Summary
	9
	10	Syncthing is a decentralized file-synchronization program that permits
	11	sharing of files over the Internet with computers that have been
	12	configured to trust one another.
	13
	14	## 2. Instructions
	15
	16	The following are instructions for installing Syncthing onto a GNU/Linux Debian 10 machine.
	17
	18	### 2.1. Install `syncthing` via `apt-get`
	19
	20	Update the local repository package lists with `$ sudo apt-get update`.
	21
	22	Install the `syncthing` package with `$ sudo apt-get install syncthing`.
	23
	24	Note: As of 2020-04-27, Debian 10 Buster uses Syncthing version `1.0.0`.
	25
	26	### 2.2. Enable automatic startup via `systemd` service.
	27
	28	Syncthing can be started automatically via `systemd` as a system
	29	service upon boot or a user service upon login. If `syncthing` was
	30	installed from the Debian 10 repository (ex: via `apt-get`), then the
	31	necessary service files (ex: `syncthing@.service` ) should already be
	32	installed. If not, see the detailed autostart instructions for where
	33	to download a copy of the service
	34	files.<sup>[[1]](#syncthing_20200331_autostart)</sup>
	35
	36	#### 2.2.a. Enable automatic startup via `systemd` upon boot (system service).
	37
	38	For a system service, identify the user under which to run
	39	`syncthing`. Even though `syncthing` will be run upon startup (without
	40	needing a user to login first), files cannot be created or modified by
	41	`syncthing` with permissions of a specified user. In this example,
	42	`baltakatei` will be the user. This means an appropriate directory for
	43	a `syncthing` shared folder would be `/home/baltakatei/Sync/`.
	44
	45	Alternatively, if `syncthing` were running as a headless server where
	46	no user is expected to directly modify files in the server's file
	47	system, then a dedicated dummy user named `syncthing-user` might be
	48	appropriate.
	49
	50	The commands to create a `systemd` system service under user
	51	`baltakatei` are:
	52
	53	$ sudo systemctl enable syncthing@baltakatei.service
71687450	54	$ sudo systemctl start syncthing@baltakatei.service
	55
	56	The following notifications may appear while running these commands:
	57
	58	$ systemctl enable syncthing@baltakatei.service
	59	Created symlink /etc/systemd/system/multi-user.target.wants/syncthing@baltakatei.service → /lib/systemd/system/syncthing@.service.
045f579a SBS	60
	61	The status of the new system service can be verified via:
	62
	63	$ systemctl status syncthing@baltakatei.service
	64
71687450	65	The resulting status data will resemble:
	66
	67	$ systemctl status syncthing@baltakatei.service
	68	● syncthing@baltakatei.service - Syncthing - Open Source Continuous File Synchronization for baltakatei
	69	Loaded: loaded (/lib/systemd/system/syncthing@.service; enabled; vendor preset: enabled)
	70	Active: active (running) since Mon 2020-04-27 09:01:00 PDT; 3min 34s ago
	71	Docs: man:syncthing(1)
	72	Main PID: 2799 (syncthing)
	73	Tasks: 23 (limit: 1132)
	74	Memory: 45.3M
	75	CGroup: /system.slice/system-syncthing.slice/syncthing@baltakatei.service
	76	└─2799 /usr/bin/syncthing -no-browser -no-restart -logflags=0
	77
045f579a SBS	78	#### 2.2.b. Enable automatic startup via `systemd` upon login (user service).
	79
	80	For a user service, identify which user under which to run
	81	`syncthing`. In this example, `baltakatei` will be the user. This
	82	means an appropriate directory for a `syncthing` shared folder would
	83	be `/home/baltakatei/Sync/`.
	84
	85	The commands to create a `systemd` user service under user
	86	`baltakatei` are:
	87
	88	$ systemctl --user enable syncthing.service
	89	$ systemctl --user start syncthing.service
	90
	91	The status of the new user service can be verified via:
	92
	93	$ systemctl --user status syncthing.service
	94
	95	## 3. References
	96	- <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.
	97
	98	[1]: https://docs.syncthing.net/users/autostart.html
	99	[bktei_2020_homepage]: http://baltakatei.com
	100	[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/
	101
	102
	103	<hr>
	104	<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>