TrueNAS AppsTrueNAS 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.

Asigra

TrueNAS Enterprise

TrueNAS Enterprise-licensed systems do not have applications available by default. To enable applications as part of the Enterprise license, consult with iXsystems.

Only install qualified applications from the Enterprise applications train with the assistance of iXsystems Support.

Contacting Support

Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.

iXsystems Customer Support
Support Portalhttps://support.ixsystems.com
Emailsupport@ixsystems.com
Telephone and Other Resourceshttps://www.ixsystems.com/support/

The Asigra DS-System app enables you to offer a robust, scalable service to multiple customers. Agentless architecture, where customers only need to install the DS-Client on one LAN computer, eliminates the need to install software on each target backup/restore computer.

If the DS-Client is networked with the target backup/restore computers, you can browse data, back it up, and restore it as required. Customers can run automatic and unattended backups for data environments ranging from single-user standalone computers to enterprise-wide LANs and WANs.

During backups, the DS-Client extracts changed data, compresses it, and encrypts the items specified for backup. Only new or modified data is backed up. This accelerates the backup transmission time. Backed-up data is transmitted to the secure off-site data center hosting the DS-System vault over the Internet, intranet, or a direct dial-up connection. After clearing security measures for the DS-Client, restores are performed on demand, through the same DS-Client.

The TrueNAS Asigra DS-System app is the vault. An agentless DS-Client backs up data in the vault. The DS-Operator is the management software for the DS-System.

After installing the Asigra DS-System app, register an account with Asigra if you do not already have one. Refer to communications from Asigra for the license and the link to the DS-Operator download. See Setting Up Asigra in the DS Operator below for the next steps after installing the Asigra DS-System app.

Before You Begin

Before you install the Asigra app:

  • Read the Asigra DS-System User Guide.

    For information on the DS-License Server, see Section 2.1 in the Asigra DS-System User Guide.

    For information on creating customer accounts and DS-Client, see Section 3.1 in the Asigra DS-System User Guide.

    For more information on DS-Client accounts, see Section 4.1 in the Asigra DS-System User Guide.

  • 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.

Asigra has two run-as user IDs, 0 for the root users and 999 for the postgres data user. The Asigra and TrueNAS default user oper serves as the DS-Operator user with administration roles. Log into the DS-Operator GUI with this user and the password entered as the **Operator Password** in the wizard after deploying the app. You do not need to add the **oper** user in TrueNAS as a user account.

  • 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.

    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. Asigra expects two host path dataset storage volumes, data and postgres_data. You can create more datasets if you want additional storage volumes for the app, but these are not required. You can add datasets and storage volumes after installing the app.

Creating Datasets for Apps

When creating datasets for apps follow these steps:

  1. Go to Datasets, select the location for the parent dataset if organizing required datasets under a parent dataset, then click Add Dataset. For example, select the root dataset of the pool, and click Add Dataset to create a new parent called apps or appName*, where appName is the name of the app.

    Do not create the app datasets under the ix-applications or ix-apps dataset.

  2. Enter the name of the dataset, then select Apps as the Dataset Preset. Creating the parent dataset with the preset set to Generic causes permissions issues when you try to create the datasets the app requires with the preset set to Apps.

  3. Click Save. Return to dataset creation when prompted rather than configuring ACL permissions.

    You can set up permissions (ACLs) for a dataset after adding it by selecting Go to ACL Manager to open the Edit ACL screen, or wait and use the app Install wizard ACL settings to add permissions. You can also edit permissions after installing the app using either method.

  4. Select the parent dataset and then click Create Dataset to open the Add Dataset screen again.

  5. Enter the name of a dataset required for the app, such as config, select Apps as the Dataset Preset, and then click Save. When prompted, return to creating datasets rather than setting up ACL permissions.

  6. Repeat for remaining datasets required for the app.

Installing the Application

This basic procedure covers the required Asigra 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).

Naming Multiple App Deployments

Each deployment of the same app requires a unique name. App names can include numbers, dashes, or underscores (for example, syncthing2, syncthing-test, syncthing_1, minio2, 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 apps are case-sensitive. For example, a file named MyData.txt is not the same as the mydata.txt file in Syncthing.

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.

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.

Install Asigra DS-System Screen
Figure 5: Install Asigra DS-System 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.

Enter the Asigra Configuration settings.

Enter passwords for the database, root user, and the operator user oper.

Select the DS-Operator language from the dropdown list. English is the default language.

Enable Cluster is selected by default, with five cluster nodes set as the default cluster size. Accept the default or change to a value of 3-16 nodes based on your desired configuration.

The TrueNAS app is configured with all the environment variables required to deploy the app. If you want to customize the container, click Add to the right of Additional Environment Variables for each to enter the variable(s) and values(s).

Accept the default values in Network Configurations. See Network Configuration for details. Leave Host Network unselected.

Add your Storage Configuration settings.

For Asigra DS-System Configuration Storage, set the Type to Host Path (Path that already exists on the system). Select Enable ACL, then enter or browse to and select the data dataset to populate the Host Path field.

Add Config Asigra Data ACL and ACE Settings
Figure 6: Add Asigra Data ACL and ACE Settings

Click Add to the right of ACL Entries for each user or group entry you want to add. Click once to add the 0 user ID. Give it FULL_CONTROL Access.

Select Force Flag.

Next, for Asigra DS-System Postgres Data Storage, set Type to Host Path (Path that already exists on the system). Enter or browse to select the postgres_data dataset to populate the Host Path field. Do not click Edit ACL! Select Automatic Permissions to set the permissions for this dataset and for the parent dataset if storage volume datasets are nested under a parent dataset.

Add Config Asigra Postgres_Data Automatic Permissions
Figure 7: Add Asigra Postgres_Data Automatic Permissions

See Storage Configuration Settings below for more information.

Accept the defaults in Resources Configuration, and select the GPU option if applicable.

Click Install. A progress dialog displays before switching to the Installed applications screen. The Installed screen displays with the Asigra DS-System app in the Deploying state. Status changes to Running when ready to use.

Asigra DS-System App Installed and Running
Figure 8: Asigra DS-System App Installed and Running

See Setting Up the DS-System in DS-Operator below for the next steps.

Setting Up DS-System in DS-Operator

After installing the Asigra application in TrueNAS, either click Register to open the Asigra New Account screen to register your company with Asigra, or if you already have a registered account, use the link provided by Asigra to download and extract the DS-Operator GUI program.

Asigra New Customer Information Screen
Figure 9: Asigra New Customer Information Screen

Asigra provides your valid license and the license server IP address or URL> Enter the IP address when adding the license server for your service. It also provides the link to where you download a zip file with the DS-Operator.

Install the DS-Operator on a local network with access to the TrueNAS system hosting the Asigra DS-System.

The instructions below cover the initial configuration of the TrueNAS Asigra DS-System after installing the TrueNAS app. It covers downloading and logging into the DS-Operator GUI, initializing the TrueNAS DS-System, adding the administrator user roles, and setting up the license server. Refer to Asigra documentation for additional customizing or managing instructions for your DS-Server or DS-Client products.

For help with Asigra products, contact Asigra.

The following instructions cover a Windows OS-based DS-Operator initial configuration:

  1. Download the DS-Operator zip file and use a zip program like 7-Zip or WinZip to extract the dsoper.jar file. Double-click on the extracted file in your Downloads File Explorer folder to launch the DS-Operator GUI program.

  2. Launch the DS-Operator GUI. Either double-click on the dsoper file in the File Explorer Downloads folder or right-click and select Open.

  3. Log in as the default oper user and enter the password entered in the Operator Password field in the Install Asigra DS-System wizard. The TrueNAS Asigra app default user oper is preconfigured with all administration roles, but if you add some other user account to serve as the administration user you must assign the user the Data Operator, Account Manager, and Export CRI roles. Refer to the Asigra DS-System User Guide for more information.

    If you receive authentication errors, you might need to add the oper user to your Windows system.

    Adding a User in Windows

    If you need to create the Asigra DS-Operator user on your Windows system:

    1. Enter Computer Management in the Start menu search field, then open the Computer Management program.
    2. Click on Local Users and Groups, right click on Users, and then click New User.
    3. Add the oper user, enter and confirm the password added to Operator Password in the Install Asigra DS-System wizard.
    4. Clear User must change password at next login,
    5. Select Password never expires.
    6. Click Create.

  4. Set up the TrueNAS DS-Server using the DS-Operator GUI. Click Setup on the top toolbar, then click Initialization to open the DS-Operator Initialization window.

    Click Add to open the Add a DS-System window. Enter the IP address for your TrueNAS server running the Asigra DS-System app, then click OK.

    Click Refresh at the bottom left of the window to change the default IP address to the name of your DS-System.

  5. Enter the license server for your DS-System. Select the checkbox to the left of the system name or IP address, click Setup on the top toolbar, and then select License Server to open the DS-License Server window for your system.

    Enter the license server URL provided by Asigra, for example, rlm.asigra.com, verify the port number is 4417 or the port number Asigra provides with the license, then click Add.

You can now add your customer and DS-Client accounts. For more information refer to:

  • Adding customer accounts for each customer backing up data to the DS-System. Refer to Section 3 in the DS-System User Guide.

  • Adding DS-Client accounts for your customers. Refer to Section 4 in the DS-System User Guide.

  • Customizing your DS-Sever to suit your use case using the DS-Operator GUI. Refer to the DS-System User Guide.

Understanding App Installation Wizard Settings

The following section provides more detailed explanations of the settings in each section of the Install Asigra DS-System installation wizard.

Application Name Settings

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.

Asigra DS-System 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.

The app includes three passwords:

  • Database Password - Sets a password for the DS-System database.
  • Root Password - Set a password for the root run-as user. Allowed to connect to the DS-Operator GUI but is not assigned the administration roles. The root user can create a new user in the DS-Operator and assign administration roles to the new user. Refer to Asigra documentation for more information on assigning administration roles.
  • Operator Password - Sets the password for the default DS-Operator administration user account oper. This user is preassigned the administration roles. Connect to the DS-Operator with this account and password.

Select the language for the DS-Operator. This sets the on-screen language for the DS-Operator UI. The default is English.

Adding Environment Variables

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.

Asigra provides information on environment variables you can add through their DS-Client. For more information on these variables, see Sections 5.18.2 and 5.21.2 in the DS-Client User Guide.

Network Configuration Settings

The TrueNAS Asigra DS-System app has three default ports:

  • 4401 assigned to and exposes the DS-Client
  • 4404 assigned to and exposes the DS-Operator admin interface
  • 4409 assigned to and exposes the DS-System replication interface

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.

We do not recommend selecting Host Network unless required for the specific application or workload. When required or strongly recommended for an application, TrueNAS typically enables host networking by default.

When host networking is disabled, specific ports from the container are exposed on the local network and mapped to a host port. This is the default Docker networking behavior. This approach provides better isolation, flexibility in port assignments, and improved security compared to enabling host networking.

Select Host Network to bypass port mapping, granting the container direct access network interfaces on the host. This can improve performance, especially in deployments with many users, and simplify network configuration, but compromises isolation and introduces the risk of port conflicts, limiting the ability to run multiple instances of the same app. For most deployments, default port mapping is more secure and versatile.

Storage Configuration Settings

TrueNAS provides two options for storage volumes: ixVolumes and host paths. Asigra DS-System expects two host path storage volumes, data to hold app DS-System data and postgres_data for postgres database storage.

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.

To create a dataset while in the app installation wizard, with Type set to the host path option, go to the Host Path field, click into the pool or a dataset in the pool to activate the Create Dataset option. Click on Create Dataset to open the dialog. Enter the name for the dataset, then click Create. TrueNAS creates the dataset in the location selected.

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.

If you organize the data and postgres_data datasets under a parent dataset named asigra, you can set the permissions for the postgres and parent datasets by selecting Automatic Permissions under the Asigra DS-System Postgres Data Configuration settings. To show this option, set Type to Host Path. See Setting Dataset ACL Permissions below.

You can add extra storage volumes during the app installation or edit the application after it deploys. Stop the app before editing settings.

Setting Dataset ACL Permissions

You can configure ACL permissions for a dataset through the Install Asigra DS-System wizard or from the Datasets screen after adding the datasets. We recommend using the Automatic Permissions option found in the Asigra DS-System Postgres Data Storage section to set the permissions for the postgres and parent datasets. Setting permissions from the Datasets screen requires several adjustments that, if not correctly set, prevent the app from deploying.

Select Enable ACL to show the ACL and ACE Entries options. 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 as one of the following:

  • The default app user:
    • 568 for apps in all trains if the app can run as any non-root user.
    • 999 for all postgres storage volumes.
    • 0 if running as root.
    • 473 for MinIO app in the stable train.
  • The run-as-user UID set as a default for the app. The run-as user shows on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys. You can refer to the tutorial for the app, or look in the questions.yaml file found in the GitHub repository for the application to find this UID/GID.
  • The user ID for the new or existing TrueNAS user added to serve as the administrator for the app.

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.

Use the default user ID 999 for all postgres storage volumes, not the 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, and postgres user ID, set the Access permissions level to FULL CONTROL.

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.

Adding ACL Permissions from the Datasets Screen First, select the dataset row, scroll down to the Permissions widget, and click Edit to open the Edit ACL screen. Change the @owner and @group values from root to the administrative user for your TrueNAS system, and click apply for each. Next, add an ACL entry for the run-as user 0 for root. You can also add the app default user 568 for apps. Save the ACL before leaving the screen.
Adding Postgres and Parent Dataset ACL Permissions

First, set Type to Host Path to show the Automatic Permissions option. Do not select Enable ACL as this removes the Automatic Permissions option.

Next, enter or browse to select postgres_data and populate the Host Path field with the path to this dataset. Select Automatic Permissions. TrueNAS sets the required permissions for the postgres storage volume dataset and the parent dataset.

TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.

Mounting an SMB Share Storage Volume

If adding an SMB share as an additional storage volume, create the SMB dataset and share user(s), and add the user ID for the share user(s) to the dataset ACL.

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.

Resources Configuration

Resources Configuration Settings
Figure 17: Resources Configuration Settings

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.