TrueNAS Apps: Tutorials
Application maintenance is independent from TrueNAS version release cycles.
App versions, features, options, and installation behavior at time of access might vary from documented tutorials and UI reference.
Syncthing (Enterprise)
22 minute read.
TrueNAS Enterprise
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 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.
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 license 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.
To install the Syncthing enterprise train app, do the following:
- Acquire and apply the Enterprise VM & Apps license to the Enterprise system.
Set a pool for applications to use if not already assigned.
You can use either an existing pool or create a new one. TrueNAS creates the ix-apps (hidden) dataset in the pool set as the application pool. This dataset is internally managed, so you cannot use this as the parent when you create required application datasets.
After setting the pool, the Installed Applications screen displays Apps Service Running on the top screen banner.
Locate the run-as user for the app.
Take note of the run-as user for the app, shown on the app information screen in the Run As Context widget and in the Application Metadata widget on the Installed applications screen after the app fully deploys. The run-as user(s) get added to the ACL permissions for each dataset used as a host path storage volume.
(Optional) Create a new TrueNAS user account to manage this application. When creating a new user account to manage this application or using an existing TrueNAS administrator account, enable sudo permissions for that TrueNAS user account, select Create New Primary Group, and add the appropriate group in the Auxiliary Group for the type of user you want to create. Make note of the UID for the new user to add in the installation wizard.
Add the user ID to the dataset ACL permissions when setting up app storage volumes in the Install app wizard.
(Optional) Create datasets for the storage volumes for the app.
Do not create encrypted datasets for apps if not required! Using an encrypted dataset can result in undesired behaviors after upgrading TrueNAS when pools and datasets are locked. When datasets for the containers are locked, the container does not mount, and the apps do not start. To resolve issues, unlock the dataset(s) by entering the passphrase/key to allow datasets to mount and apps to start.You can create required datasets before or after launching the installation wizard. The install wizard includes the Create Dataset option for host path storage volumes, but if you are organizing required datasets under a parent you must create that dataset before launching the app installation wizard.
Go to Datasets and select the pool or dataset where you want to place the dataset(s) for the app. For example, /tank/apps/appName.
Create the dataset(s) before beginning the app installation process.
Syncthing enterprise train app requires two datasets, home to store configuration data and data1 to store app data.
Follow the instructions below in Creating Datasets for Apps to correctly create the dataset(s). You can organize the app dataset(s) under a parent dataset to separate them from datasets for other applications. For example, create a syncthing parent dataset with these datasets nested under it. If you organize the required dataset(s) under a parent dataset, set up the required ACL permissions for the parent dataset before using the app installation wizard to avoid receiving installation wizard errors. Use the Enable ACL option in the Install Sycnting wizard to configure permissions for the home and data1 datasets.
This basic procedure covers the required Syncthing app settings. For optional settings, see Understanding App Installation Wizard Settings.
You can have multiple deployments of the same app (for example, two or more from the stable or enterprise trains, or a combination of the stable and enterprise trains).
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.
If this is the first application installed, TrueNAS displays a dialog about configuring apps.
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.
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.
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. For more information, see Network Settings below.
Configure the storage settings. Syncthing uses two datasets. Set Type to Host Path (Path that already exists on the system) Select Enable ACL, then either enter or browse to select the home dataset. The other mount point is /data1 with the host path set to the data1 dataset. Click Add to the right of ACL Entries. Set ID to Entry is for a USER, enter 0 in ID, and then give the user full control permissions.
Select Force Flag to allow upgrading the app. This allows writing to the dataset when there is existing data.
Repeat for the /data1 storage volume. Click Add to the right of Additional Storage to show the storage settings.
Set Type to Host Path. Select Enable ACL, then enter or browse to select the path to the data1 dataset. Add the run as user, 0 as an ACE entry with full control permissions.
If migrating from another NAS system, set Type to SMB/CIFS Share (Mounts a volume to an SMB share), and then select Migrate Data. For more information, see Mounting an SMB Share Storage Volume below.
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.
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.
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.
The following sections provide detailed explanations of the settings found in each section of the Enterprise train Install Syncthing screen.
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.
The app wizard is configured with all settings required to deploy the container, but you can add additional settings if you want to further customize the app in TrueNAS.
Click Add to the right of Environmental Variables to show a set of fields to configure the application with additional variables.
You can add environment variables to the app configuration after deploying it. Click Edit on the Application Info widget for the app found on the Installed Application screen to open the edit screen.
Click here for more information on Syncthing environmental variables
Some TrueNAS apps have predefined run-as user and group IDs. These assignments vary based on the app train and other variables such as installing but not running as the root user.
Default user and group IDs are:
- 473 for the MinIO stable train app.
- 568 (apps user), used in some community apps and all apps in the enterprise train
- 999 (netdata user), used for all postgres storage volumes
- 0 (root user).
Accept the default user and group ID in the User and Group Configuration section or enter the user ID for a new TrueNAS user created to serve as the administrator for this app.
Create any app administrator user before installing the application, and take note of the UID. Enter this user ID when configuring the user for the app and as the user when setting up storage volume permissions.
The Syncthing enterprise app listens on port 8384.
All TrueNAS apps are assigned default port numbers. Accept the default port numbers, but if changing port number assignments, enter a number within the range 1-65535, however, 0-1024 might require the application to have elevated privileges. Before changing default ports, refer to the TrueNAS default port list for a list of assigned and available port numbers.
Disabling Host Network shows the TCP and UDP port numbers, and sets the web UI to listen on port 22000.
To use a certificate, best practice is to create the self-signed certificate before you begin using the app installation wizard. If you did not create a certificate before starting the installation wizard you can select the default TrueNAS certificate and edit the app to change the certificate after deploying the application.
Select the certificate created in TrueNAS for the app from the Certificate dropdown list.
TrueNAS provides two storage options for storage volumes: ixVolumes and host paths.
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 (recommended option), set Type to Host Path (Path that already exists on the system).
The Syncthing enterprise train app requires two storage volumes/datasets to store configuration data and app data storage. Create one named home and another dataset named data1.
If you organize the config dataset under a parent dataset named syncthing, configure the ACL permissions for this parent dataset and add an ACE entry for the root user.
You can add extra storage volumes during the app installation, or edit the application after it deploys. Stop the app before editing settings.
You can configure ACL permissions for the required dataset in the Install Syncthing wizard, or from the Datasets screen after adding the datasets.
Select Enable ACL to show the ACL and ACE Entries options for host path volumes except for postgres storage volumes. Configure ACE entries for each UID and/or GID you recorded from the Run As Context widget in Before You Begin.
Configuring ACE Entries
Enter or browse to select the dataset and populate Host Path.
Next, click Add to the right of ACL Entries to show the permissions settings. Set ID Type to Entry is for a USER or Entry is for a GROUP. If you configured a group in TrueNAS that you want to give access to instead of a single user, set the ID to the group option and enter the GID for that group.
Enter the UID and/or GID for the run as users. The run-as user(s) show on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys.
If the app shows User and Group Configuration settings, the default UID shows on the screen. If not, choose the run-as user ID found in the Run As Content widget.
Postgres storage volumes have 999 as the default user ID and run-as user.
If you created a new TrueNAS user to serve as the app administration user, add an entry record and enter the UID for this user in addition to the run-as user ID.
When adding the ACL entry for the run-as user, default user, and/or optional TrueNAS app administrator user, set the Access permissions level to FULL CONTROL.
Do not use the Edit ACL option for postgres storage volumes. Select the Automatic Permissions option, which correctly sets permissions for the postgres and parent dataset (if used).
Select Force Flag to apply the ACL even if the path has existing data. This allows you to update the app when an update is available.
The TrueNAS Syncthing Enterprise app includes the option to mount an SMB share inside the container pod and to migrate data from another 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.
Accept the default values in Resources Configuration or enter new CPU and memory values. By default, this application is limited to use no more than 2 CPU cores and 4096 megabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container the app uses, enter new CPU values as a plain integer value (letter suffix is not required). The default is 4096.
Accept the default value (4 Gb) allocated memory or enter a new limit in bytes. Enter a plain integer without the measurement suffix, for example, 129 not 129M or 123MiB.
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 using 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 restart.
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 of 1080 bytes for each inotify watcher, 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.