Syncthing (Enterprise)

14 minute read.

Last Modified 2024-12-02 09:57 EST

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

TrueNAS has two versions of the Syncthing application, the offical version in the stable 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 official stable version.

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.

Users migrating data from an existing third-party NAS solution to TrueNAS 24.04 (Dragonfish) or newer can use the Syncthing enterprise application to mount the source with a remote SMB share that preserves metadata.

See Third-Party SMB Data Migration for considerations and a full tutorial.

Enterprise users with the appropriate licenese can see the apps in the enterprise train. Community users can access enterprise versions of apps by adding the enterprise train to their catalog. To change app train settings:

Go to Apps, click on Configuration at the top of the Installed applications screen, and select Settings to open the train Settings screen.

You can also access the Installed scren from the Discover screen by clicking on Manage Installed Apps at the top of the screen.

Select enterprise to add it to the list of trains, and then click Save.

After changing train settings, return to the Discover screen and click Refresh Catalog.

Before You Begin

Before launching the app installation wizard, do the following:

Create a self-signed certificate for the Syncthing enterprise app.
Adding an App Certificate
1. Go to Credentials > Certificates to add a self-signed certificate authority (CA) and certificate for the application to use.
2. Click Add on the Certificate Authorities (CA) widget to open the Add Certificate Authority screen.
  a. Enter a name for the CA. For example, minio, syncthing, etc. Accept the defaults for Type and Profile, then click Next.
  b. Accept the defaults on Certificate Options unless you want to set an expiration on the certificate. Enter a new value in Lifetime to impose an expiration time period, then click Next.
  c. Enter location and organization values for your installation in the Certificate Subject fields. Enter the email address you want to receive system notifications.
  d. Enter your system IP address in Subject Alternate Names, then click Next. When configuring a cluster, enter the system IP addresses for each system in the cluster.
  e. Accept the default values on Extra Constraints, then click Next.
  f. Review the CA configuration then click Save.
3. Click Add on the Certificates widget to open the Add Certificate screen.
  a. Enter a name for the certificate. For example, minio, syncthing, etc. Select Internal Certificate as Type and HTTPS RSA Certificate in Profiles, then click Next.
  b. Select the newly-created CA in Signing Certificate Authority. Accept the rest of the defaults unless you want to set an expiration on the certificate. Enter a new value in Lifetime to impose an expiration time period, then click Next.
  c. Enter location and organization values for your installation in the Certificate Subject fields. Enter the email address you want to receive system notifications.
  d. Enter your system IP address in Subject Alternate Names, then click Next. When configuring a cluster, enter the system IP addresses for each system in the cluster.
  e. Accept the default values on Extra Constraints, then click Next.
  f. Review the CA configuration then click Save.
4. Download the certificate and install it.
  a. Click the download icon on the Certificates widget to start the download. When complete, click the browser download icon to open in a File Explorer window.
  b. Right click on the certificate.crt file, then click Install Certificate. Click Open on the Open File window.
  c. Click Install Certificate, then select Local Machine on the Welcome to the Certificate Import Wizard window. Click Next.
  d. Select Place all certificates in the following store, then select Trusted Root Certificate Authorities and click OK.
  c. Click Next then Finish.
Create the required datasets, home and data1.
Syncthing stores configuration home dataset and app data in the data1 dataset.

Create the two datasets before beginning the app installation process. You can organize these under a parent dataset to keep the Syncthing storage datasets separated from datasets for other potential applications. For example, create a parent dataset syncthing with the two child datasets nested under it.

If not already assigned, set a pool for applications to use.
(Optional) Create a new TrueNAS user to serve as the administrator for the app
Either use the default user and group IDs or create a 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, click on Discover Apps, and locate the app widget by either scrolling down to it or begin typing the name into the search field. For example, to locate the MinIO app widget, begin typing minIO into the search field to show app widgets matching the search input.

Figure 2: Example of Locating an App Widget

If this is the first application installed, TrueNAS displays a dialog about configuring apps.

Configuring Apps Dialog

Click Confirm then Agree to close the dialog and open the application details screen.

If not the first time installing apps the dialog does not show, click on the widget to open the app information screen.

Click Install to open the app installation wizard.

Application configuration settings are grouped into several sections, each explained below in Understanding App Installation Wizard Settings. To find specific fields begin typing in the Search Input Fields search field to show the section or field, scroll down to a particular section, or click on the section heading in the list of sections on the upper-right of the wizard screen.

Figure 4: Install Syncthing Enterprise Screen

Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.

Accept the default version number in Version. When a new version becomes available, the application shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.

Next, enter the Syncthing Configuration settings.

Select the timezone where your TrueNAS system is located. Begin typing the location into the Timezone field to filter the list until the location shows, then select it.

Accept the default user and group IDs or enter the UID for any new TrueNAS user created to serve as the administrator for this app. See User and Group Settings below for more information.

Select Host Network to bind to the default host settings programmed for Syncthing. See Network Configuration below for more information.

Figure 5: Syncthing Enterprise Network Settings

Accept the default web port 8384. Before changing ports, see Default Ports for a list of assigned port numbers.

If created, select the certificate for Syncthing from the Certificates dropdown list. See Network Settings below for more information on network settings.

Configure the storage settings. Syncthing uses two datasets and mount paths. Set the first to /home with the host path set to the home dataset. The other mount point is /data1 with the host path set to the data1 dataset.

Select Enable ACL for the /home storage volume, enter 568 as the user and give it full permissions. Repeat for the /data1 storage volume.

Figure 6: Home and Data1 Host Path ACL and ACE Settings

If migrating from some other NAS system, set Type to SMB/CIFS Share (Mounts a volume to a SMB share), and then select Migrate Data. See Storage Settings below for more information.

Accept the default values in Resources Configuration.

Click Install.

The Installed applications screen opens showing the application in the Deploying state before it changes to Running when the application is ready to use.

Click Web Portal to open the Syncthing admin interface.

Syncthing Web Portal for TrueNAS — Figure 8: Syncthing Web Portal for TrueNaS

Securing the Syncthing Web UI

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

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.

Figure 9: Syncthing Advanced Configuration Menu

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 the computer Bill uses 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 systems during one and bi-directional Syncthing moves. You can configure this setting on a per folder basis.

Understanding TrueNAS Syncthing Wizard Settings

The following sections provide detailed explanations of the settings found in each section of the Enterprise train Install Syncthing screen.

Application Name Settings

Configuration Setting

Select the timezone where your TrueNAS system is located. Begin typing the location into the Timezone field to filter the list until the location shows, then select it.

Click here for more information on Syncthing environmental variables

User and Group Settings

Figure 11: Syncthing Enterprise User and Group IDs

Networking Settings

The TrueNAS Syncthing enterprise app listens on port 8384.

Clearing the Host Network checkbox shows the TCP and UDP port numbers, and the web UI listens on port 22000.

Storage Settings

The Syncthing enterprise train app requires two storage volumes/datasets to store configuration data and app data storage. Create one named home and the other dataset named data1.

Setting the Storage Volume Type

To allow TrueNAS to create the storage volume, leave Type set to ixVolume (Dataset created automatically by the system). This adds a storage volume for the application nested in the hidden ix-apps dataset, located on the pool selected as the apps pool. Using ixVolume is intended for a test deployment of an app but not for a full app deployment, as data does not persist for these volumes after deleting the app where a dataset does. Datasets make recovering, transferring, and accessing app configuration, user, or other data possible where ixVolumes do not.

To use an existing dataset, which is the recommended option, set Type to Host Path (Path that already exists on the system).

If the install wizard shows a Mount Path, either accept the default value or enter the correct mount path. For example, if the dataset name is data, enter /data as the mount path.

Select Enable ACL to define ACL permissions and to populate the Host Path field by either entering or browsing to and selecting the location of the dataset. Populating the Host Path with the dataset location and then selecting Enable ACL clears the values, so we recommend selecting Enable ACL before entering the host path.

Repeat the above for each required dataset.

The TrueNAS Syncthing Enterprise app includes the option to mount an SMB share inside the container pod and to migrate data from some other NAS to TrueNAS.

Selecting Migrate Data forces a read-only mount regardless of the Read Only checkbox selection. The SMB mount options are set to vers=3.0, cifsacl, and noperm. ACL preservation is not guaranteed if in a non-AD environment, or if the ACL or remote server contains local users.

Set Type an SMB/CIFS Share (Mounts a volume to a SMB share) to add an SMB share storage volume.

Select Read Only to make the storage volume read only.

Enter the path inside the container to mount the storage for the share volume in Mount Path.

Enter the server address for the SMB share in Server, the path to mount the SMB share in Path, and the share authentication user credentials in User and Password. (Optional) enter the share domain name in domain.

Permissions are currently limited to the permissions of the user that mounted the share.

Use the SMB option for data synchronization between a share and the app if the option shows on the screen. A present, only the Syncthing app includes this option.

Resource Configuration Settings

Figure 15: Syncthing Enterprise Resource Limits

Increasing inotify Watchers

Syncthing uses inotify to monitor file system events, with one inotify watcher per monitored directory. Linux defaults to a maximum of 8192 inotify watchers. Using the Syncthing Enterprise app to sync directories with greater than 8191 subdirectories (possibly lower if other services are also utilizing inotify) produces errors that prevent automatic monitoring of file system changes.

Increase inotify values to allow Syncthing to monitor all sync directories. Add a sysctl variable to ensure changes persist through reboot.

Go to System > Advanced and locate the Sysctl widget.

Click Add to open the Add Sysctl screen.

Enter fs.inotify.max_user_watches in Variable.

Enter a Value larger than the number of directories monitored by Syncthing. There is a small memory impact for each inotify watcher of 1080 bytes, so it is best to start with a lower number, we suggest 204800 and increase if needed.

Enter a Description for the variable, such as Increase inotify limit.

Select Enabled and click Save.