18 minute read.Last Modified 2022-04-07 16:08 EDT
Configure SSH in TrueNAS before creating a remote replication task. This ensures that new snapshots are regularly available for replication.
To streamline creating simple replication configurations, the replication wizard assists with creating a new SSH connection and automatically creates a periodic snapshot task for sources that have no existing snapshots.
- Data Protection > Replication Tasks
- Choose sources for snapshot replication.
- Remote sources require an SSH connection.
- TrueNAS shows the number snapshots available to replicate.
- Choose sources for snapshot replication.
- Define the snapshot destination.
- A remote destination requires an SSH connection.
- Choose destination or define manually by typing a path.
- Adding a new name on the end of the path creates a new dataset.
- Choose replication security.
- iXsystems always recommend replication with encryption.
- Disabling encryption is only meant for absolutely secure and trusted destinations.
- Schedule the replication.
- You can schedule standardized presets or a custom defined schedule.
- Running once runs the replication immediately after creation.
- Task is still saved and you can rerun or edit it.
- Choose how long to keep the replicated snapshots.
This video tutorial presents a simple example of setting up replication:
To create a new replication, go to Data Protection > Replication Tasks and click ADD.
You can load any saved replication to prepopulate the wizard with that configuration. 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.
Start by configuring the replication sources. Sources are the datasets or zvols with snapshots to use for replication. Choosing a remote source requires selecting an SSH connection to that system. Expanding the directory browser shows the current datasets or zvols that are available for replication. You can select multiple sources or manually type the names into the field.
TrueNAS shows how many snapshots are available for replication. We recommend you manually snapshot the sources or create a periodic snapshot task before creating the replication task. However, when the sources are on the local system and don’t have any existing snapshots, TrueNAS can create a basic periodic snapshot task and snapshot the sources immediately before starting the replication. Enabling Recursive replicates all snapshots contained within the selected source dataset snapshots.
Local sources can also use a naming schema to identify any custom snapshots to include in the replication. Remote sources require entering a snapshot naming schema to identify the snapshots to replicate. A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
The destination is where replicated snapshots are stored. Choosing a remote destination requires an SSH connection to that system. Expanding the directory browser shows the current datasets that are available for replication. You can select a destination dataset or manually type a path in the field. You cannot use zvols as a remote replication destination. Adding a name to the end of the path creates a new dataset in that location.
To use encryption when replicating data click the Encryption box. After selecting the box these additional encryption options become available:
- Ecryption Key Format allows the user to choose between a hex (base 16 numeral) or passphrase (alphanumeric) style encryption key.
- Store Encryption key in Sending TrueNAS database allows the user to either store the encryption key in the sending TrueNAS database (box checked) or choose a temporary location for the encryption key that decrypts replicated data (box unchecked)
Using encryption for SSH transfer security is always recommended.
In situations where two systems within an absolutely secure network are used 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 these can be overriden by switching to the advanced options screen or editing the task after creation.
TrueNAS suggests a name based off the selected sources and destination, but this can be overwritten with a custom name.
Adding a schedule automates the task to run according to your chosen times. You can choose between a number of preset schedules or create a custom schedule for when the replication runs. Choosing to run the replication once runs the replication immediately after saving the task, but you must manually trigger any additional replications.
Finally, define how long you want to keep snapshots on the destination system. We generally recommend defining snapshot lifetime to prevent cluttering the system with obsolete snapshots.
Start Replication* saves the new replication task. New tasks are enabled by default and activate according to their schedule or immediately when no schedule is chosen. The first time a replication task runs, it takes longer because the snapshots must be copied entirely fresh to the destination.
Later replications run faster, as only the subsequent changes to snapshots are replicated. Clicking the task state opens the log for that task.
Requirements: Storage pools and datasets created in Storage > Pools.
Go to Data Protection > Replication Tasks and click ADD
- Choose Sources
- Set the source location to the local system
- Use the file browser or type paths to the sources
- Define a Destination path
- Set the destination location to the local system
- Select or manually define a path to the single destination location for the snapshot copies.
- Set the Replication schedule to run once
- Define how long the snapshots are stored in the Destination
- Clicking START REPLICATION immediately snapshots the chosen sources and copies those snapshots to the destination
- Dialog might ask to delete existing snapshots from the destination. Be sure that all important important data is protected before deleting anything.
- Choose Sources
Clicking the task State shows the logs for that replication task.
TrueNAS provides a wizard for quickly configuring different simple replication scenarios.
While we recommend regularly scheduled replications to a remote location as the optimal backup scenario, the wizard can very quickly create and copy ZFS snapshots to another location on the same system. This is useful when no remote backup locations are available, or when a disk is in immediate danger of failure.
The only thing you need before creating a quick local replication are datasets or zvols in a storage pool to use as the replication source and (preferably) a second storage pool to use for storing replicated snapshots. You can set up the local replication entirely in the Replication Wizard.
To open the Replication Wizard, go to Data Protection > Replication Tasks and click ADD.
Set the source location to the local system and pick which datasets to snapshot.
The wizard takes new snapshots of the sources when no existing source snapshots are found.
Enabling Recursive replicates all snapshots contained within the selected source dataset snapshots. Local sources can also use a naming schema to identify any custom snapshots to include in the replication. A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
Set the destination to the local system and define the path to the storage location for replicated snapshots. When manually defining the destination, be sure to type the full path to the destination location.
TrueNAS suggests a default name for the task based on the selected source and destination locations, but you can type your own name for the replication. You can load any saved replication task into the wizard to make creating new replication schedules even easier.
You can define a specific schedule for this replication or choose to run it immediately after saving the new task. Unscheduled tasks are saved in the replication task list and you can run saved tasks manually or edit later to add a schedule.
The destination lifetime is how long copied snapshots are stored in the destination before they are deleted. We usually recommend defining a snapshot lifetime to prevent storage issues. Choosing to keep snapshots indefinitely can require you to manually clean old snapshots from the system if or when the destination fills to capacity.
Clicking START REPLICATION saves the new task and immediately attempts to replicate snapshots to the destination. When TrueNAS detects that the destination already has unrelated snapshots, it asks to delete the unrelated snapshots and do a full copy of the new snapshots. This can delete important data, so be sure any existing snapshots can be deleted or are backed up in another location.
The simple replication is added to the replication task list and shows that it is currently running. Clicking the task state shows the replication log with an option to download the log to your local system.
To confirm that snapshots are replicated, go to Storage > Snapshots >Snapshots and verify the destination dataset has new snapshots with correct timestamps.
- Storage pools with datasets and data to snapshot.
- SSH configured with a connection to the remote system saved in Credentials > Backup Credentials > SSH Connections.
- Dataset snapshot task saved in Data Protection > Periodic Snapshot Tasks.
Go to Data Protection > Replication Tasks and click ADD, then select ADVANCED REPLICATION CREATION.
- General Options:
- Name the task.
- Select Push or Pull for the local system.
- Select a replication transport method.
- SSH is recommended.
- SSH+Netcat is used for secured networks.
- Local is for in-system replication.
- Configure the replication transport method:
- Remote options require a preconfigured SSH connection.
- SSH+Netcat requires defining netcat ports and addresses.
- Select sources for replication.
- Choose a preconfigured periodic snapshot task as the source of snapshots to replicate.
- Remote sources require defining a snapshot naming schema.
- Remote destination requires an SSH connection.
- Select a destination or type a path in the field.
- Define how long to keep snapshots in the destination.
- Run automatically starts the replication after a related periodic snapshot task completes.
- To automate the task according to its own schedule, set the schedule option and define a schedule for the replication task.
To use the advanced editor to create a replication task, go to Data Protection > Replication Tasks, click ADD to open the wizard, then click the ADVANCED REPLICATION CREATION button.
Options are grouped together by category. Options can appear, disappear, or be disabled depending on the configuration choices you make. Start by configuring the General options first, then the Transport options before configuring replication Source, Destination, and Replication Schedule.
Type a name for the task in Name. Each task name must be unique, and we recommend you name it in a way that makes it easy to remember what the task is doing.
Direction allows you to choose whether the local system is sending (Push) or receiving data (Pull).
Decide what Transport method (SSH, SSH+NETCAT, or LOCAL) to use for the replication before configuring the other sections.
Set the Number of retries for failed replications before stopping and marking the task as failed (the default is 5).
Use the Logging Level to set the message verbosity level in the replication task log.
To ensure the replication task is active check the Enabled box.
The Transport selector determines the method to use for the replication: SSH is the standard option for sending or receiving data from a remote system, but SSH+NETCAT is available as a faster option for replications that take place within completely secure networks. Local is only used for replicating data to another location on the same system.
With SSH-based replications, configure the transport method by selecting the SSH Connection to the remote system that sends or receives snapshots. Options for compressing data, adding a bandwidth limit, or other data stream customizations are available. Stream Compression options are only available when using SSH. Before enabling Compressed WRITE Records, verify that the destination system also supports compressed WRITE records.
For SSH+NETCAT replications, you must define the addresses and ports to use for the Netcat connection.
Allow Blocks Larger than 128KB is a one-way toggle. Replication tasks using large block replication only continues to work as long as this option remains enabled.
The replication Source is the datasets or zvols to use for replication. Select the sources to use for this replication task by opening the file browser or entering dataset names in the field. Pulling snapshots from a remote source requires a valid SSH Connection before the file browser can show any directories.
If the file browser shows a connection error after selecting the correct SSH Connection, you might need to log in to the remote system and make sure it is configured to allow SSH connections.
In TrueNAS, do this by going to the System Settings > Services screen, checking the SSH service configuration, and starting the service.
By default, the replication task uses snapshots to quickly transfer data to the receiving system. When Full Filesystem Replication is set, the chosen Source is completely replicated, including all dataset properties, snapshots, child datasets, and clones. When choosing this option, it is recommended to allocate additional time for the replication task to run.
Leaving Full Filesystem Replication unset but setting Include Dataset Properties includes just the dataset properties in the snapshots to be replicated.
Checking the Recursive check box allows you to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.
Enter new defined properties in the Properties Override field to replace existing dataset properties with the newly defined properties in the replicated files.
List any existing dataset properties to remove from the replicated files in the Properties Exclude field.
Local sources are replicated by snapshots that were generated from a periodic snapshot task and/or from a defined naming schema that matches manually created snapshots.
Select a previously configured periodic snapshot task for this replication task in Periodic Snapshot Tasks drop down list. The replication task selected must have the same vales in Recursive and Exclude Child Datasets as the chosen periodic snapshot task. Selecting a periodic snapshot schedule removes the Schedule field.
To define specific snapshots from the periodic task to use for the replication, set Replicate Specific Snapshots and enter a schedule. The only periodically generated snapshots included in the replication task are those that match your defined schedule.
Remote sources require entering a snapshot naming schema to identify the snapshots to replicate.
A naming schema is a collection of strftime time and date strings and any identifiers that a user might have added to the snapshot name.
For example, entering the naming schema
custom-%Y-%m-%d_%H-%M finds and replicates snapshots like
Multiple schemas can be entered by pressing Enter to separate each schema.
Alternately, you can use your Replication Schedule to determine which snapshots are replicated by setting Run Automatically, Only Replicate Snapshots Matching Schedule, and defining when the replication task runs.
When a replication task is having difficulty completing, it is a good idea to set Save Pending Snapshots. This prevents the source TrueNAS from automatically deleting any snapshots that failg to replicate to the destination system.
Use Destination to specify where replicated data is stored. Choosing a remote destination requires an *SSH Connection to that system. Expanding the file browser shows the current datasets that are available on the destination system. You can click a destination or manually type a path in the field. Adding a name to the end of the path creates a new dataset in that location.
DO NOT use zvols for a remote destination
By default, the destination dataset is set to be read-only* after the replication is complete. You can change the **Destination Dataset Read-only Policy** to only start replication when the destination is read-only (***REQUIRE**) or to disable checking the dataset’s read-only state (**IGNORE**).
The Encryption checkbox adds another layer of security to replicated data by encrypting the data before transfer and decrypting it on the destination system.
- Setting the checkbox adds more options to choose between using a HEX key or defining your own encryption PASSPHRASE.
- You can store the encryption key either in the TrueNAS system database or in a custom-defined location.
Synchronizing Destination Snapshots With Source destroys any snapshots in the destination that do not match the source snapshots. TrueNAS also does a full replication of the source snapshots as if the replication task had never been run before, which can lead to excessive bandwidth consumption.
This can be a very destructive option. Make sure that any snapshots deleted from the destination are obsolete or otherwise backed up in a different location.
Defining the Snapshot Retention Policy is generally recommended to prevent cluttering the system with obsolete snapshots. Choosing Same as Source keeps the snapshots on the destination system for the same amount of time as the defined Snapshot Lifetime from the source system periodic snapshot task.
You can use Custom to define your own lifetime for snapshots on the destination system.
By default, setting the task to Run Automatically starts the replication immediately after the related periodic snapshot task is complete.
Setting the Schedule checkbox allows scheduling the replication to run at a separate time.
- Defining a specific time for the replication task to run is a must do.
- Choose a time frame that both gives the replication task enough time to finish and is during a time of day when network traffic for both source and destination systems is minimal.
- Use the custom scheduler (recommended) when you need to fine-tune an exact time or day for the replication.
Choosing a Presets option populatess in the rest of the fields.
To customize a schedule, enter crontab values for the
These fields accept standard cron values. The simplest option is to enter a single number in the field. The task runs when the time value matches that number. For example, entering 10 means that the job runs when the time is ten minutes past the hour.
An asterisk (
*) means match all values.
You can set specific time ranges by entering hyphenated number values. For example, entering 30-35 in the Minutes field sets the task to run at minutes 30, 31, 32, 33, 34, and 35.
You can also enter lists of values.
Enter individual values separated by a comma (
For example, entering 1,14 in the Hours field means the task runs at 1:00 AM (0100) and 2:00 PM (1400).
A slash (
/) designates a step value.
For example, entering
* in Days runs the task every day of the month. Entering
*/2 runs it every other day.
Combining the above examples creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.
TrueNAS has an option to select which Months the task runs. Leaving each month unset is the same as selecting every month.
The Days of Week schedules the task to run on specific days in addition to any listed days. For example, entering 1 in Days and setting Wed for Days of Week creates a schedule that starts a task on the first day of the month and every Wednesday of the month.
The Schedule Preview dipslays when the current settings mean the task runs.
|*||Every item.||* (minutes) = every minute of the hour.|
* (days) = every day.
|*/N||Every Nth item.||*/15 (minutes) = every 15th minute of the hour.|
*/3 (days) = every 3rd day.
*/3 (months) = every 3rd month.
|Comma and hyphen/dash||Each stated item (comma)|
Each item in a range (hyphen/dash).
|1,31 (minutes) = on the 1st and 31st minute of the hour.|
1-3,31 (minutes) = on the 1st to 3rd minutes inclusive, and the 31st minute, of the hour.
mon-fri (days) = every Monday to Friday inclusive (every weekday).
mar,jun,sep,dec (months) = every March, June, September, December.
You can specify days of the month or days of the week.
TrueNAS lets users create flexible schedules using the available options. The table below has some examples:
|Desired schedule||Values to enter|
|3 times a day (at midnight, 08:00 and 16:00)||months=*; days=*; hours=0/8 or 0,8,16; minutes=0|
(Meaning: every day of every month, when hours=0/8/16 and minutes=0)
|Every Monday/Wednesday/Friday, at 8.30 pm||months=*; days=mon,wed,fri; hours=20; minutes=30|
|1st and 15th day of the month, during October to June, at 00:01 am||months=oct-dec,jan-jun; days=1,15; hours=0; minutes=1|
|Every 15 minutes during the working week, which is 8am - 7pm (08:00 - 19:00) Monday to Friday||Note that this requires two tasks to achieve:|
(1) months=*; days=mon-fri; hours=8-18; minutes=*/15
(2) months=*; days=mon-fri; hours=19; minutes=0
We need the second scheduled item, to execute at 19:00, otherwise we would stop at 18:45. Another workaround would be to stop at 18:45 or 19:45 rather than 19:00.
Setting Only Replicate Snapshots Matching Schedule restricts the replication to only replicate those snapshots created at the same time as the replication schedule.
TrueNAS SCALE users should either replicate the dataset/Zvol without properties to disable encryption at the remote end or construct a special json manifest to unlock each child dataset/zvol with a unique key.
- Replicate every encrypted dataset you want to replicate with properties.
- Export key for every child dataset that has a unique key.
- For each child dataset construct a proper json with poolname/datasetname of the destination system and key from the source system like this:
- Save this file with the extension
- On the remote system, unlock the dataset(s) using properly constructed
Uncheck properties when replicating so that the destination dataset is not encrypted on the remote side and does not require a key to unlock.
- Go to Data Protection and click ADD in the Replication Tasks window.
- Click Advanced Replication Creation.
- Fill out the form as needed and make sure Include Dataset Properties is NOT checked.
- Click Save.
- Go to Storage -> pool/root dataset on the replication system. Click and select Export Key.
- Apply the key file or key code to the dataset. You can either download the key file, open that file and change the pool name/dataset to the receiving pool name/dataset, or copy the key code provided in the Key window.
- On the receiving pool/dataset: Click next to pool/dataset and select Unlock.
- Unlock the dataset. You can either clear the Unlock with Key file checkbox, paste the Key Code into Dataset Key field (if there is a space character at the end of the key, delete the space), or select the downloaded Key file that was edited.
- Click Save.
- Click Continue.