TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Syncthing Charts App

This article provides information on installing and using the TrueNAS Syncthing app.

SCALE has two versions of the Syncthing application, the community version in the charts train and a smaller version tested and polished for a safe and supportable experience for enterprise customers in the enterprise train. Community members can install either the enterprise or community version.

Adding the Enterprise App

To add the enterprise train Syncthing application to the list of available applications:

Go to Apps and click on Discover Apps.

Click on Manage Catalogs at the top of the Discover screen to open the Catalog screen.

Click on the TRUENAS catalog to expand it, then click Edit to open the Edit Catalog screen.

Click in the Preferred Trains field, click on enterprise to add it to the list of trains, and then click Save.

The charts and enterprise train versions of the Syncthing app widget display on the Discover application screen.

Syncthing Overview

Syncthing is a file synchronization application that provides a simple and secure environment for file sharing between different devices and locations. Use it to synchronize files between different departments, teams, or remote workers.

Syncthing is tested and validated to work in harmony with TrueNAS platforms and underlying technologies such as ZFS to offer a turnkey means of keeping data across many systems. It can seamlessly integrate with TrueNAS.

Syncthing does not use or need a central server or cloud storage. All data is encrypted and synchronized directly between devices to ensure files are protected from unauthorized access.

Syncthing is easy to use and configure. You can install on a wide range of operating systems, including Windows, MacOS, Linux, FreeBSD, iOS or Android. The Syncthing web UI provides users with easy management and configuration of the application software.

How does Syncthing work?

Syncthing does not have a central directory or cache to manage. It segments files into pieces called blocks. These blocks transfer data from one device to another. Multiple devices can share the synchronization load in a similar way to the torrent protocol. With more devices and smaller blocks, devices receive data faster because all devices fetch blocks in parallel.

Syncthing renames files and updates metadata more efficiently because renaming does not cause a re-transmission of that file.

Temporary files store partial data downloaded from devices. Temporary files are removed when a file transfer completes or after the configured amount of time elapses.

Before Installing Syncthing

You can allow the app to create a storage volume(s) or use existing datasets created in SCALE. The TrueNAS Syncthing app requires a main configuration storage volume for application information. You can also mount existing datasets for storage volume inside the container pod.

If you want to use existing datasets for the main storage volume, [create any datasets]/scale/scaletutorials/datasets/datasetsscale/ before beginning the app installation process (for example, syncthing for the configuration storage volume). If also mounting storage volume inside the container, create a second dataset named data1. If mounting multiple storage volumes, create a dataset for each volume (for example, data2, data3, etc.).

You can have multiple Syncthing app deployments (two or more Charts, two or more Enterprise, or Charts and Enterprise trains, etc.). Each Syncthing app deployment requires a unique name that can include numbers and dashes or underscores (for example, syncthing2, syncthing-test, syncthing_1, etc.).

Use a consistent file-naming convention to avoid conflict situations where data does not or cannot synchronize because of file name conflicts. Path and file names in the Syncthing app are case sensitive. For example, a file named MyData.txt is not the same as mydata.txt file in Syncthing.

If not already assigned, set a pool for applications to use.

Either use the default user and group IDs or create the new user with Create New Primary Group selected. Make note of the UID/GID for the new user.

Installing the Syncthing Application

Go to Apps > Discover Apps and locate the Syncthing charts app widget.

Syncthing Charts App Widget
Figure 3: Syncthing Charts App Widget

Click on the widget to open the Syncthing details screen.

Syncthing Charts Details Screen
Figure 4: Syncthing Charts Details Screen

Click Install to open the Install Syncthing screen.

Application configuration settings are presented in several sections, each explained below. To find specific fields, click in the Search Input Fields search field, scroll down to a particular section or click on the section heading on the navigation area in the upper-right corner.

Install Syncthing Screen
Figure 5: Install Syncthing Screen

Accept the default values in Application Name and Version.

Accept the default owner user and group ID settings. You can customize your Syncthing charts deployment by adding environment variables but these are not required.

Add the storage volume(s). Either allow the Syncthing app to create the configuration storage volume or use an existing dataset created for this app. To use an existing dataset, select Enable Custom Host Path for Syncthing Configuration Volume, then browse to and select the dataset to populate the field. See Storage Settings for more details on adding existing datasets.

Accept the default port numbers in Networking. See Network Settings below for more information on network settings. Before changing the default port number, see Default Ports for a list of assigned port numbers. When selected, Host Network binds to the default host settings programmed for Syncthing. We recommend leaving this disabled.

Syncthing does not require advanced DNS options. If you want to add DNS options, see Advanced DNS Settings below.

Accept the default resource limit values for CPU and memory or select Enable Pod resource limits to show the CPU and memory limit fields, then enter the new values you want to use for Syncthing. See Resource Configuration Settings below for more information.

Click Install. The system opens the Installed Applications screen with the Syncthing app in the Deploying state. After installation completes the status changes to Running.

Syncthing Installed
Figure 6: Syncthing Installed

Click Web Portal on the Application Info widget to open the Syncthing web portal to begin configuring folders, devices, and other settings.

Syncthing Web Portal for TrueNAS
Figure 7: Syncthing Web Portal for TrueNaS

Secure Syncthing by setting up a username and password.

Understanding Syncthing Settings

The following sections provide more detail explanations of the settings found in each section of the Install Syncthing screen.

Application Name Settings

Accept the default value or enter a name in Application Name field. In most cases use the default name but adding a second application deployment requires a different name.

Accept the default version number in Version. When a new version becomes available, the application has an update badge. The Installed Applications screen shows the option to update applications.

Configuration Settings

Accept the defaults in the Configuration settings or enter new user and group IDs. The default value for Owner User ID and Owner Group ID is 568.

Syncthing Configuration Settings
Figure 8: Syncthing Configuration Settings

Click Add to the right of Syncthing environment to show the Name and Value fields.

Add Syncthing Environment Variable
Figure 9: Add Syncthing Environment Variable

For a list of Syncthing environment variables, go to the Syncthing documentation website and search for environment variables. You can add environment variables to the Syncthing app configuration after deploying the app. Click Edit on the Syncthing Application Info widget found on the Installed Application screen to open the Edit Syncthing screen.

Storage Settings

You can allow the Syncthing app to create the configuration storage volume or you can create datasets to use for the configuration storage volume and to use for storage within the container pod.

To use existing datasets, select Enable Custom Host Path for Syncthing Configuration Volume to show the Host Path for Syncthing Configuration Volume and Extra Host Path Volumes fields. Enter the host path in Host Path for Syncthing Configuration Volume or browse to and select the dataset an existing dataset created for the configuration storage volume.

Syncthing Enable Host Path Storage fields
Figure 10: Syncthing Enable Host Path Storage Fields

Add to the right of Extra Host Path Volumes shows the Mount Path in Pod and Host Path fields.

Syncthing Add Extra Host Paths
Figure 11: Syncthing Add Extra Host Paths

Enter the data1 dataset in Mount Path in Pod, then enter or browse to the dataset location in Host Path. If you added extra datasets to mount inside the container pod, click Add for each extra host path you want to mount inside the container pod. Enter or browse to the dataset created for the extra storage volumes to add inside the pod.

Networking Settings

Accept the default port numbers in Web Port for Syncthing, TCP Port for Syncthing and UDP Port for Syncthing. The SCALE Syncthing chart app listens on port 20910. The default TCP port is 20978 and the default UDP port is 20979. Before changing default ports and assigning new port numbers, refer to the TrueNAS default port list for a list of assigned port numbers. To change the port numbers, enter a number within the range 9000-65535.

Syncthing (Chart) Network Configuration
Figure 12: Syncthing (Chart) Network Configuration

We recommend not selecting Host Network. This binds to the host network.

Advanced DNS Settings

Syncthing does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.

Syncthing Add Advanced DNS Options
Figure 13: Syncthing Add Advanced DNS Options

Resource Configuration Settings

Accept the default values in Resources Configuration or select Enable Pod resource limits to enter new CPU and memory values. By default, this application is limited to use no more than 4 CPU cores and 8 Gigabytes available memory. The application might use considerably less system resources.

Syncthing Enable Pod Resource Limits
Figure 14: Syncthing Enable Pod Resource Limit

To customize the CPU and memory allocated to the container (pod) Syncthing uses, enter new CPU values as a plain integer value followed by the suffix m (milli). Default is 4000m.

Accept the default value 8Gi allocated memory or enter a new limit in bytes. Enter a plain integer followed by the measurement suffix, for example 129M or 123Mi

Securing the Syncthing Web UI

After installing and starting the Syncthing application, launch the Syncthing web portal. Go to Actions > Settings and set a user password for the web UI.

Syncthing UI Actions Menu
Figure 15: Syncthing UI Actions Menu

Using the Syncthing Web Portal for TrueNAS

The Syncthing web portal allows administrators to monitor and manage the synchronization process, view logs, and adjust settings.

Folders list configured sync folders, details on sync status and file count, capacity, etc. To change folder configuration settings, click on the folder.

This Device displays the current system IO status including transfer/receive rate, number of listeners, total uptime, sync state, and the device ID and version.

Actions displays a dropdown list of options. Click Advanced to access GUI, LDAP, folder, device, and other settings.

You can manage directional settings for sync configurations, security, encryption, and UI server settings through the Actions options.

Managing Syncthing Folder

To change or enter a directory path to share a folder, click on the folder, then select Edit. We recommend each shared folder have a sync folder to allow for more granular traffic and data flow. Syncthing creates a default sync folder in the main user or HOME directory during installation of the application.

Click on a folder to see details on that folder.

Untrusted Device Password is a beta feature and not recommended for production environments. This feature is for edge cases where two users want to share data on a given device but cannot risk interception of data. Only trusted users with the code can open the file(s) with shared data.

Using Syncthing File Versioning

File Versioning applies to changes received from other devices. For example, Bill turns on versioning and Alice changes a file. Syncthing archives the old version on Bill’s computer when it syncs the change from Alice. But if Bill changes a file locally on his computer, Syncthing does not and cannot archive the old version.

For more information on specific file versioning, see Versioning

Using Syncthing Advanced Administration

Go to Actions > Advanced to access advanced settings. These setting options allow you to set up network isolation, directory services, database, and bandwidth throttling, and to change device-specific settings and global default settings.

Incorrect configuration can damage folder contents and render Syncthing inoperable!
Viewing Syncthing Logs and Debugs

Go to Logs to access current logs and debug files. The Log tab displays current logs, and the Debugging Facilities tab provides access to debug logging facilities. Select different parameters to add to the logs and assist with debugging specific functionalities.

You can forward logs to a specific folder or remote device.

Maintaining File Ownership (ACL Preservation) Syncthing includes the ability to maintain ownership and extend attributes during transfers between nodes (systems). This ensures ACLs and permissions remain consistent across TrueNAS SCALE systems during one and bi-directional Syncthing moves. You can configure this setting on a per folder basis.