TrueNAS Enterprise
TrueNAS SCALE
TrueNAS CORE
Compare Editions
TrueCommand
Software Status
FreeNAS
Compare Systems
F-Series
M-Series
H-Series
R-Series
Mini Series
Download TrueNAS SCALE
Download TrueNAS CORE
Get TrueNAS Enterprise
Contact an Enterprise SpecialistTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.
Setting Up a Remote Replication Task
11 minute read.
TrueNAS replication allows users to create one-time or regularly scheduled ZFS snapshots of data stored in pools, datasets, or zvols on their system as a way to back up stored data. When properly configured and scheduled, remote replication takes regular snapshots of storage pools or datasets and saves them in the destination location on another system.
Remote replication occurs between an originating TrueNAS system and a destination TrueNAS system with replicated snapshots.
With the implementation of the administration user and role-based permissions, setting up replication tasks as an admin user has a few differences from those set up when logged in as the root user. Setting up remote replication when 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.
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 before configuring a replication task.
Before setting up a replication task, you must configure an admin user with the Home Directory set to something other than /var/empty.
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.
Set up the data storage for where you want to save replicated snapshots.
Make sure the admin user is correctly configured.
Create a periodic snapshot task of the storage locations to back up.
Create an SSH connection between the local TrueNAS 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.
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.
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 changes 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:
Create the destination dataset or storage location you want to use to store the replication snapshots. If using another TrueNAS system, create a dataset in one of your pools.
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 13.0-U6.x system as the remote server, the remote user is always root.
If using an earlier TrueNAS 22.12.1 system or you installed TrueNAS 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, and then click Edit.
Scroll down to the Home Directory setting. 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.
For more information, follow the instructions in Adding Home Directories to create the home directory for the admin user.
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.
Go to Data Protection and click Add on the Replication Tasks widget to open the Replication Task Wizard. Configure the following settings:
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 system, you must select On a Different System from the Destination Location dropdown list to do remote replication.
TrueNAS shows the number of 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 allowcommand in Shell on the remote system. When the dialog displays, click Use Sudo for ZFS Commands. If you close this dialog, select the option on the Add Replication Task wizard screen.f. Select Replicate Custom 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.
Selecting Matching regular expression does not automatically destroy snapshots where selecting Matching naming schema does. If using regular expression, the snapshots on the destination host are not automatically destroyed if they are also destroyed on the source host due to snapshot lifetime. Snapshots on the destination host display as “Will not be destroyed automatically” and do not display with a retention period. Use naming schema for these.
g. (Optional) Enter a name for the snapshot in Task Name. TrueNAS populates this field with a default name using the source and destination paths separated by a hyphen, but this default can make locating the snapshot in the destination dataset a challenge. To make it easier to find the snapshot, give it a name that is easy for you to identify. For example, a replicated task named dailyfull for a full file system snapshot taken daily.
Click Next to display the scheduling options.
Select the schedule and snapshot retention life time.
a. Select Replication Schedule 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 TrueNAS should store copied snapshots in the destination dataset before TrueNAS 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.
Click START REPLICATION. A dialog displays if this is the first snapshot taken using the destination dataset. If TrueNAS 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 an Encrypted Replication Task.
When using a TrueNAS system on a different release, the remote or destination system user is always root.
To configure a new SSH connection from the Replication Task Wizard:
Select Create New on the SSH Connection dropdown list to open the New SSH Connection configuration screen.
Enter a name for the connection.
Select the Setup Method from the dropdown list. If a TrueNAS system, select Semi-Automatic.
Enter the URL to the remote TrueNAS in TrueNAS URL.
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.
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.
Select Generate New from the Private Key dropdown list.
(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.
Click Save to create a new SSH connection and populate the SSH Connection field in the Replication Task Wizard.
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.
