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.

Setting Up a Remote Replication Task

Using Remote Replication

TrueNAS SCALE replication allows users to create one-time or regularly scheduled snapshots of data stored in pools, datasets or zvols on their SCALE system as a way to back up stored data. When properly configured and scheduled, remote replication takes take regular snapshots of storage pools or datasets and saves them in the destination location on another system.

Remote replication can occur between your TrueNAS SCALE system and another TrueNAS system (SCALE or CORE) where you want to use to store your replicated snapshots.

With the implementation of the Local Administrator user and role-based permissions, setting up replication tasks as an admin user has a few differences than with setting up replication tasks when logged in as root. Setting up remote replication while logged in as the admin user requires selecting Use Sudo For ZFS Commands.

The first snapshot taken for a task creates a full file system snapshot, and all subsequent snapshots taken for that task are incremental to capture differences occurring between the full and subsequent incremental snapshots.

Scheduling options allow users to run replication tasks daily, weekly, monthly, or on a custom schedule. Users also have the option to run a scheduled job on demand.

Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.

Setting Up a Simple Replication Task Overview

This section provides a simple overview of setting up a replication task regardless of the type of replication, local or remote. It also covers the related steps you should take prior to configuring a replication task.


Before setting up a replication task, you must configure the admin user with the Home Directory set to something other than /var/empty and Auxiliary Groups set to include the builtin_administrators group.

Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.

Remote replication requires setting up an SSH connection in TrueNAS before creating a remote replication task.

Verify the SSH service settings to ensure you have Root with Password, Log in as Admin with Password, and Allow Password Authentication selected to enable these capabilities. Incorrect SSH service settings can impact the admin user ability to establish an SSH session during replication and require you to obtain and paste a public SSH key into the admin user settings.

Replication tasks typically require a configured and active periodic snapshot task.

Typical Replication Configuration Process

  1. Set up the data storage for where you want to save replicated snapshots.

  2. Make sure the admin user is correctly configured.

  3. Create a Periodic Snapshot task of the storage locations to be backed up.

  4. Create an SSH connection between the local SCALE system and the remote system for remote replication tasks. Local replication does not require an SSH connection. You can do this from either Credentials > Backup Credentials > SSH Connection and clicking Add or from the Replication Task Wizard using the Generate New option in the settings for the remote system.

  5. Go to Data Protection > Replication Tasks and click Add to open the Replication Task Wizard where you specify the settings for the replication task.

    Setting options change based on the source selections. Replicating to or from a local source does not require an SSH connection.

Creating a Remote Replication Task

To streamline creating simple replication tasks use the Replication Task Wizard to create and copy ZFS snapshots to another system. The wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.

If you have an existing replication task, you can select it on the Load Previous Replication Task dropdown list to load the configuration settings for that task into the wizard, and then make change such as assigning it a different destination, schedule, or retention lifetime, etc. Saving changes to the configuration creates a new replication task without altering the task you loaded into the wizard. This saves some time when creating multiple replication tasks between the same two systems.

Before you begin configuring the replication task, first verify the destination dataset you want to use to store the replication snapshots is free of existing snapshots, or that snapshots with critical data are backed up before you create the task.

To create a replication task:

  1. Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS SCALE system, create a dataset in one of your pools.

  2. Verify the admin user home directory, auxiliary groups, and sudo setting on both the local and remote destination systems. Local replication does not require an SSH connection, so this only applies to replication to another system.

    If using a TrueNAS CORE system as the remote server, the remote user is always root.

    If using a TrueNAS SCALE system on an earlier release like Angelfish, the remote user is always root.

    If using an earlier TrueNAS SCALE Bluefin system (22.12.1) or you installed SCALE as the root user then created the admin user after initial installation, you must verify the admin user is correctly configured.

    Verify Admin User Settings

    a. Go to Credentials > Local User, click anywhere on the admin user row to expand it. Click Edit.

    Scroll down to the Home Directory setting. If set to /home/admin, select Create Home Directory, then Click Save.

    If set to /var/empty, first create a dataset to use for home directories, like /tank/homedirs. Enter this in the Home Directory field, make sure this is not read only.

    b. Select the sudo permission level you want the admin user to have. Allow all sudo commands with no password must be selected to enable SSH+NETCAT remote replication.

    c. Click Save.

  1. Go to Data Protection and click Add on the Replication Tasks widget to open the Replication Task Wizard. Configure the following settings:

    Browsing to select a path

    Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.

    a. Select either On this System or On a Different System on the Source Location dropdown list. If your source is a remote system, select On a Different System. The Destination Location automatically changes to On this System. If your source is the local TrueNAS SCALE system, you must select On a Different System from the Destination Location dropdown list to do remote replication.

    TrueNAS shows the number snapshots available for replication.

    b. Select an existing SSH connection to the remote system, or select Create New to open the New SSH Connection configuration screen.

    c. Browse to the source pool/dataset(s), then click on the dataset(s) to populate the Source with the path. You can select multiple sources or manually type the names into the Source field. Selecting Recursive replicates all snapshots contained within the selected source dataset snapshots.

    d. Repeat to populate the Destination field. You cannot use zvols as a remote replication destination. Add a name to the end of the path to create a new dataset in that location.

    e. Select Use Sudo for ZFS Commands. Only displays when logged in as the admin user (or the name of the admin user). This removes the need to issue the cli zfs allow command in Shell on the remote system. When the dialog displays, click Use Sudo for ZFS Comands. If you close this dialog, select the option on the Add Replication Task wizard screen.

    f. Select Replicate Custome Snapshots, then leave the default value in Naming Schema. If you know how to enter the schema you want, enter it in Naming Schema. Remote sources require entering a snapshot naming schema to identify the snapshots to replicate. A naming schema is a pattern of naming custom snapshots you want to replicate. Enter the name and strftime(3) %Y, %m, %d, %H, and %M strings that match the snapshots to include in the replication. Separate entries by pressing Enter. The number of snapshots matching the patterns display.

    g. (Optional) Enter a name for the snapshot in Task Name. SCALE populates this field with the default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in destination dataset a challenge. To make it easier to find the snapshot, give it name easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.

  1. Click Next to display the scheduling options.

  2. Select the schedule and snapshot retention life time.

    a. Select the Replication Schedule radio button you want to use. Select Run Once to set up a replication task you run one time. Select Run On a Schedule then select when from the Schedule dropdown list.

    b. Select the Destination Snapshot Lifetime radio button option you want to use. This specifies how long SCALE should store copied snapshots in the destination dataset before SCALE deletes it. Same as Source is selected by default. Select Never Delete to keep all snapshots until you delete them manually. Select Custom to show two additional settings, then enter the number of the duration you select from the dropdown list. For example, 2 Weeks.

  3. Click START REPLICATION. A dialog displays if this is the first snapshot taken using the destination dataset. If SCALE does not find a replicated snapshot in the destination dataset to use to create an incremental snapshot, it deletes any existing snapshots found and creates a full copy of the day snapshot to use as a basis for the future scheduled incremental snapshots for this schedule task.

    This operation can delete important data, so ensure you can delete any existing snapshots or back them up in another location.

    Click Confirm, then Continue to add the task to the Replication Task widget. The newly added task shows the status as PENDING until it runs on the schedule you set.

    Select Run Now if you want to run the task immediately.

To see a log for a task, click the task State to open a dialog with the log for that replication task.

To see the replication snapshots, go to Datasets, select the destination dataset on the tree table, then select Manage Snapshots on the Data Protection widget to see the list of snapshots in that dataset. Click Show extra columns to add more information columns to the table such as the date created which can help you locate a specific snapshot or enter part of or the full the name in the search field to narrow the list of snapshots.

For information on replicating encrypted pools or datasets, see Setting Up a Encrypted Replication Task.

Configuring a New SSH Connection

When using a TrueNAS system on a different release, like CORE or SCALE Angelfish, the remote or destination system user is always root.

To configure a new SSH connection from the Replication Task Wizard:

  1. Select Create New on the SSH Connection dropdown list to open the New SSH Connection configuration screen.

  2. Enter a name for the connection.

  3. Select the Setup Method from the dropdown list. If a TrueNAS system, select Semi-Automatic.

  4. Enter the URL to the remote TrueNAS in TrueNAS URL.

  5. Enter the administration user (i.e., root or admin) that logs into the remote system with the web UI in Admin Username. Enter the password in Admin Password.

  6. Enter the administration user (i.e., root or admin) for remote system SSH session. If you clear root as the the user and type any other name the Enable passwordless sudo for ZFS commands option displays. This option does nothing so leave it cleared.

  7. Select Generate New from the Private Key dropdown list.

  8. (Optional) Select a cipher from the dropdown list, or enter a new value in seconds for the Connection Timeout if you want to change the defaults.

  9. Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.

Using SSH Transfer Security

Using encryption for SSH transfer security is always recommended.

In situations where you use two systems within an absolutely secure network for replication, disabling encryption speeds up the transfer. However, the data is completely unprotected from eavesdropping.

Choosing No Encryption for the task is less secure but faster. This method uses common port settings but you can override these by switching to the Advanced Replication Creation options or by editing the task after creation.