Syncthing

https://github.com/syncthing/syncthing
Admin
Syncthing is a continuous file synchronization program that securely synchronizes files between two...
Tokens:29,570
Snippets:276
Trust Score:8.8
License:MPL-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Syncthing via Upstart

Source: https://github.com/syncthing/syncthing/blob/main/etc/linux-upstart/README.md

Command to manually start Syncthing when using the system configuration.

```bash
sudo initctl start syncthing
```

--------------------------------

### Enable Syncthing at boot in /etc/rc.conf

Source: https://github.com/syncthing/syncthing/blob/main/etc/freebsd-rc/README.md

Add this line to /etc/rc.conf to automatically start Syncthing at boot time.

```plaintext
syncthing_enable=YES
```

--------------------------------

### Example release notes file v1.2.3.md

Source: https://github.com/syncthing/syncthing/blob/main/relnotes/README.md

Shows the required format for a release notes file: an H2-level header followed by bullet points. This example is for release 1.2.3.

```markdown
## Major changes in v1.2.3

- Files are now synchronized twice as fast on Tuesdays
```

--------------------------------

### Allow syncthing-gui port

Source: https://github.com/syncthing/syncthing/blob/main/etc/firewall-ufw/README.md

Allows the syncthing-gui port for web GUI access from anywhere. Not necessary for a normal installation.

```bash
sudo ufw allow syncthing-gui
```

--------------------------------

### testutil client command

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

Command to start the testutil client, which connects to a relay server and prints its client ID. Requires two x509 key pairs (key.pem and cert.pem) in separate directories.

```bash
./testutil -relay="relay://192.0.2.1:22067" -keys=certs/client/ -join
```

--------------------------------

### testutil server command

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

Command to start the testutil server, which connects to the relay server using the client ID and provides an interactive prompt for relaying messages.

```bash
 ./testutil -relay="relay://192.0.2.1:22067" -keys=certs/server/ -connect=BG2C5ZA-W7XPFDO-LH222Z6-65F3HJX-ADFTGRT-3SBFIGM-KV26O2Q-E5RMRQ2
```

--------------------------------

### testutil client ID output

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

Output printed by the testutil client after starting, showing the client ID.

```text
2015/09/21 23:00:52 main.go:42: ID: BG2C5ZA-W7XPFDO-LH222Z6-65F3HJX-ADFTGRT-3SBFIGM-KV26O2Q-E5RMRQ2
```

--------------------------------

### Relay tooltip template (AngularJS HTML)

Source: https://github.com/syncthing/syncthing/blob/main/cmd/infra/strelaypoolsrv/gui/index.html

AngularJS tooltip template for relay markers, displaying hostname, provider, start time, proxied bytes, sessions, clients, pools, and rate limits (global and per-session) with conditional rendering for unavailable data.

```html
<div>
  <p><b>{{ relay.uri.hostname }}</b>
    <span ng-if="relay.stats.options['provided-by']">provided by <u>{{ relay.stats.options['provided-by'] }}</u></span></p>
  <div ng-if="relay.stats">
    <span ng-if="relay.stats.startTime">Start time: {{ relay.stats.startTime | date:"medium" }}</br></span>
    <span ng-if="relay.stats.bytesProxied != undefined">Proxied: {{ relay.stats.bytesProxied | bytes }}</br></span>
    <span ng-if="relay.stats.numActiveSessions != undefined">Sessions: {{ relay.stats.numActiveSessions }}</br></span>
    <span ng-if="relay.stats.numConnections != undefined">Clients: {{ relay.stats.numConnections }}</br></span>
    <span ng-if="relay.stats.options.pools">Pools: {{ relay.stats.options.pools.join(', ') }}</br></span>
    <span ng-if="relay.stats.options['global-rate'] != undefined">
      <span ng-if="relay.stats.options['global-rate'] > 0">Global rate limit: {{ relay.stats.options['global-rate'] | bytes }}/s</span>
      <span ng-if="relay.stats.options['global-rate'] == 0">Global rate limit: unlimited</span>
      <br/>
    </span>
    <span ng-if="relay.stats.options['per-session-rate'] != undefined">
      <span ng-if="relay.stats.options['per-session-rate'] > 0">Session rate limit: {{ relay.stats.options['per-session-rate'] | bytes }}/s</span>
      <span ng-if="relay.stats.options['per-session-rate'] == 0">Session rate limit: unlimited</span>
      <br/>
    </span>
  </div>
  <div ng-if="!relay.stats">
    Data unavailable.
  <div>
</div>
```

--------------------------------

### Commit message with DCO sign-off

Source: https://github.com/syncthing/syncthing/blob/main/CONTRIBUTING.md

Example commit message with the required Signed-off-by line to indicate acceptance of the Developer Certificate of Origin (DCO). The name and email in the sign-off must match the committing author and the AUTHORS file.

```text
This is my commit message

Signed-off-by: Random J Developer <random@developer.example.org>
```

--------------------------------

### strelaysrv /status endpoint JSON output

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

Example output from the /status HTTP endpoint on port 22070, showing metrics like bytesProxied, number of connections, and options. This output is used by pool servers to read relay metrics.

```json
{
    "bytesProxied": 0,
    "goArch": "amd64",
    "goMaxProcs": 1,
    "goNumRoutine": 13,
    "goOS": "linux",
    "goVersion": "go1.6",
    "kbps10s1m5m15m30m60m": [
        0,
        0,
        0,
        0,
        0,
        0
    ],
    "numActiveSessions": 0,
    "numConnections": 0,
    "numPendingSessionKeys": 2,
    "numProxies": 0,
    "options": {
        "global-rate": 0,
        "message-timeout": 60,
        "network-timeout": 120,
        "per-session-rate": 0,
        "ping-interval": 60,
        "pools": [
            "https://relays.syncthing.net/endpoint"
        ],
        "provided-by": ""
    },
    "startTime": "2016-03-06T12:53:07.090847749-05:00",
    "uptimeSeconds": 17
}
```

--------------------------------

### Load UFW application presets

Source: https://github.com/syncthing/syncthing/blob/main/etc/firewall-ufw/README.md

Loads the syncthing and syncthing-gui application presets into UFW after copying the syncthing file to /etc/ufw/applications.d/.

```bash
sudo ufw app update syncthing
sudo ufw app update syncthing-gui
```

--------------------------------

### Allow syncthing ports

Source: https://github.com/syncthing/syncthing/blob/main/etc/firewall-ufw/README.md

Allows the syncthing ports through the firewall.

```bash
sudo ufw allow syncthing
```

--------------------------------

### Verify UDP buffer size limit

Source: https://github.com/syncthing/syncthing/blob/main/etc/linux-sysctl/README.md

Run this command to verify that the new limit is active.

```bash
sysctl net.core.rmem_max
```

--------------------------------

### Docker CLI: Pull and run Syncthing container

Source: https://github.com/syncthing/syncthing/blob/main/README-Docker.md

Pulls the Syncthing image and runs it with host network mode, sets STGUIADDRESS to empty, and maps a host directory to /var/syncthing for synchronized files.

```bash
$ docker pull syncthing/syncthing
$ docker run --network=host  -e STGUIADDRESS= \
    -v /wherever/st-sync:/var/syncthing \
    syncthing/syncthing:latest
```

--------------------------------

### Optional Syncthing rc.d configuration options

Source: https://github.com/syncthing/syncthing/blob/main/etc/freebsd-rc/README.md

These optional configuration variables can be set in /etc/rc.conf to customize Syncthing's home directory, log file, user, and group.

```plaintext
syncthing_home=</path/to/syncthing/config/dir>
syncthing_log_file=</path/to/syncthing/log/file>
syncthing_user=<syncthing_user>
syncthing_group=<syncthing_group>
```

--------------------------------

### Apply sysctl changes

Source: https://github.com/syncthing/syncthing/blob/main/etc/linux-sysctl/README.md

Run this command in a terminal to apply the sysctl changes after copying the configuration file.

```bash
sudo sysctl -q --system
```

--------------------------------

### Configure Git user name and email

Source: https://github.com/syncthing/syncthing/blob/main/CONTRIBUTING.md

Set the global Git user name and email before making the first commit. The name and email must match the details listed in the AUTHORS file.

```bash
$ git config --global user.name "Jane Doe"
$ git config --global user.email janedoe@example.com
```

--------------------------------

### Docker Compose: Syncthing service with healthcheck

Source: https://github.com/syncthing/syncthing/blob/main/README-Docker.md

Defines a Syncthing service using Docker Compose with host network mode, PUID/PGID environment variables, volume mapping, restart policy, and a healthcheck that curls the Syncthing health endpoint.

```yaml
---
version: "3"
services:
  syncthing:
    image: syncthing/syncthing
    container_name: syncthing
    hostname: my-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - STGUIADDRESS=
    volumes:
      - /wherever/st-sync:/var/syncthing
    network_mode: host
    restart: unless-stopped
    healthcheck:
      test: curl -fkLsS -m 2 127.0.0.1:8384/rest/noauth/health | grep -o OK || exit 1
      interval: 1m
      timeout: 10s
      retries: 3
```

--------------------------------

### AngularJS module configuration and filters

Source: https://github.com/syncthing/syncthing/blob/main/cmd/infra/strelaypoolsrv/gui/index.html

Defines the 'syncthing' Angular module, sets a 5-second HTTP timeout, and provides a 'bytes' filter to format byte values with units.

```javascript
angular.module('syncthing', [ ])
.config(['$httpProvider', function($httpProvider) {
  $httpProvider.defaults.timeout = 5000;
}])
.filter('bytes', function() {
  return function(bytes, precision) {
    if (isNaN(parseFloat(bytes)) || !isFinite(bytes)) return '-';
    if (typeof precision === 'undefined') precision = 1;
    var units = ['bytes', 'kB', 'MB', 'GB', 'TB', 'PB'],
        number = Math.floor(Math.log(bytes) / Math.log(1024));
    var value = (bytes / Math.pow(1000, Math.floor(number)));
    if (!isFinite(value)) {
      value = 0;
      precision = 0;
    }
    if (!isFinite(number)) {
      units = 'bytes';
    } else {
      units = units[number];
    }
    return value.toFixed(precision) + ' ' + units;
  }
})
```

--------------------------------

### Verify UFW status

Source: https://github.com/syncthing/syncthing/blob/main/etc/firewall-ufw/README.md

Verifies the opened ports after applying the UFW rules.

```bash
sudo ufw status verbose
```

--------------------------------

### strelaysrv relay URI with public IP

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

The generated relay URI with the host part replaced by a public IP address, as required when the -listen option was not used.

```bash
relay://192.0.2.1:22067/?id=EZQOIDM-6DDD4ZI-DJ65NSM-4OQWRAT-EIKSMJO-OZ552BO-WQZEGYY-STS5RQM&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070
```

--------------------------------

### Protocol buffer definitions for FileInfo and ExtendedAttribute

Source: https://github.com/syncthing/syncthing/wiki/Syncing-extended-attributes

Defines the FileInfo message with an extended_attributes field and a locale_inode_change_time_ns field, and the ExtendedAttribute message with os, name, and value fields. The {os, name} tuple must be unique. The locale_inode_change_time_ns field is not sent over the wire.

```protobuf
message FileInfo {
  ...
  repeated ExtendedAttribute extended_attributes = 42;
  ...
  int64 locale_inode_change_time_ns = 1002; // not sent over the wire
}

message ExtendedAttribute {
  OperatingSystem os = 1;
  string name = 2;
  bytes value = 3;
}
```

--------------------------------

### strelaysrv generated relay URI

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

URI printed by strelaysrv after generating a key pair. Contains a partial address and options; replace the host part with your public IP if -listen is not used.

```bash
relay://:22067/?id=EZQOIDM-6DDD4ZI-DJ65NSM-4OQWRAT-EIKSMJO-OZ552BO-WQZEGYY-STS5RQM&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070
```

--------------------------------

### Shortened relay URI

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

A shortened relay URI containing only the host part, for use when certificate pinning and verbose settings are not needed.

```bash
relay://192.0.2.1:22067
```

--------------------------------

### strelaysrv joining public relay pool message

Source: https://github.com/syncthing/syncthing/blob/main/cmd/strelaysrv/README.md

Expected log message when the relay server successfully joins the public relay pool. This appears when running with no arguments or with -debug.

```text
2015/09/21 22:45:46 pool.go:60: Joined https://relays.syncthing.net/endpoint rejoining in 48m0s
```

--------------------------------

### Relay pool map functions (addMarkerToMap, addCircleToMap, constructURI)

Source: https://github.com/syncthing/syncthing/blob/main/cmd/infra/strelaypoolsrv/gui/index.html

JavaScript functions for the relay pool map: iterate over relays to add circles, handle single-relay centering, add markers with popups and overlapping-marker jitter, add proportional circles, and parse relay URLs into URI objects with query arguments.

```javascript
angular.forEach($scope.relays, function(relay) {
  if (relay.stats) {
    addCircleToMap(relay);
  }
});
if ($scope.relays.length == 1) {
  //Center to only relay with zoom
  $scope.map.panTo(new L.LatLng(relays[0].location.latitude, relays[0].location.longitude));
  $scope.map.setZoom(13);
}
});
```

```javascript
function addMarkerToMap(relay) {
  var loc = relay.location.latitude + "," + relay.location.longitude;
  // Deal with overlapping markers
  while (loc in $scope.usedLocations) {
    var locParts = loc.split(',');
    locParts = [parseFloat(locParts[0]), parseFloat(locParts[1])];
    locParts[Math.round(Math.random())] += 0.5 * (Math.random() >= 0.5 ? 1 : -1);
    loc = locParts.join(',');
  }
  $scope.usedLocations[loc] = true;
  var locParts = loc.split(',');
  relay.marker = new L.Marker([relay.location.latitude, relay.location.longitude],{
    title: relay.url,
  });
  var scope = $rootScope.$new(true);
  scope.relay = relay;
  var icon = new L.Icon({
    iconSize: [18, 28], // size of the icon
    iconAnchor: [9, 28], // point of the icon which will correspond to marker's location
    shadowAnchor: [0, 0], // the same for the shadow
    popupAnchor: [0, -27], // popup anchor
    shadowSize: [0,0],
    iconUrl: 'https://cdn.rawgit.com/pointhi/leaflet-color-markers/master/img/marker-icon-red.png',
    shadowUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.7/images/marker-shadow.png',
  });
  relay.marker = new L.marker(new L.latLng(locParts[0], locParts[1]),{icon})
    .bindPopup($compile($scope.tooltipTemplate)(scope)[0],{})
    .on('mouseover', function (e) {
      this.openPopup();
    }).on('mouseout', function (e) {
      this.closePopup();
    }).addTo($scope.map);
  relay.showMarker = function() {
    relay.marker.openPopup();
  }
  relay.hideMarker = function() {
    relay.marker.closePopup();
  }
}
```

```javascript
function addCircleToMap(relay) {
  console.log(relay.location.latitude)
  L.circle([relay.location.latitude, relay.location.longitude], {
    radius: ((relay.stats.bytesProxied * 100) / $scope.totals.bytesProxied) * 10000,
    color: "FF0000",
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  }).addTo($scope.map);
}
```

```javascript
function constructURI(url) {
  var uri = document.createElement('a');
  // HAX, otherwise doesn't work
  uri.href = url.replace('relay://', 'http://');
  // Convert query string to object
  uri.args = {};
  angular.forEach(uri.search.replace(/^\?/, '').split('&'), function(query) {
    var split = query.split('=');
    uri.args[split[0]] = split[1];
  });
  return uri;
}
```

--------------------------------

### AngularJS controller for relay data

Source: https://github.com/syncthing/syncthing/blob/main/cmd/infra/strelaypoolsrv/gui/index.html

Defines the 'relayDataController' that initializes totals, sets up a Leaflet map, fetches relay data from '/endpoint/full', and processes it to update totals and add markers.

```javascript
.controller('relayDataController', ['$scope', '$rootScope', '$http', '$q', '$compile', '$timeout', function($scope, $rootScope, $http, $q, $compile, $timeout) {
  $scope.totals = {
    bytesProxied: 0,
    goMaxProcs: 0,
    kbps10s1m5m15m30m60m: [0, 0, 0, 0, 0, 0],
    numActiveSessions: 0,
    numConnections: 0,
    numPendingSessionKeys: 0,
    numProxies: 0,
    uptimeSeconds: 0,
  };
  $scope.map = L.map('map').setView([40.90296, 1.90925], 2);
  L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
    attribution: 'Leaflet',
    maxZoom: 17
  }).addTo($scope.map);
  $scope.tooltipTemplate = $('#infoTemplate').html();
  $scope.usedLocations = {};
  $scope.sortType = 'stats.numActiveSessions';
  $scope.sortReverse = true;
  $scope.sortCompare = function(a, b) {
    if (a.value == b.value) {
      return 0;
    }
    if (a.type == "undefined" || a.type == "null") {
      return -1;
    }
    if (b.type == "undefined" || b.type == "null") {
      return 1;
    }
    return a.value > b.value ? 1 : -1;
  }
  $http.get("/endpoint/full").then(function(response) {
    $scope.relays = response.data.relays;
    angular.forEach($scope.relays, function(relay) {
      relay.uri = constructURI(relay.url);
      relay.address = relay.url.split('/')[2];
      addMarkerToMap(relay);
      if (relay.stats) {
        angular.forEach($scope.totals, function(value, key) {
          if (typeof $scope.totals[key] == 'number') {
            $scope.totals[key] += relay.stats[key];
          } else if (typeof $scope.totals[key] == 'object' && $scope.totals[key] instanceof Array) {
            angular.forEach($scope.totals[key], function(value, index) {
              $scope.totals[key][index] += relay.stats[key][index];
            });
          }
        });
      }
    });
    // After the totals were calculated, add circles.
  });
}])
```
Tokens:
Raw