(408) 943-4100               V   Commercial Support

Advanced

  9 minute read.

Last Modified 2021-03-24 14:35 EDT

Requirements:

  • Storage pools with datasets and data to snapshot.
  • SSH configured with a connection to the remote system saved in System > SSH Connections.
  • Dataset snapshot task saved in Tasks > Periodic Snapshot Tasks.

Go to Tasks > 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 an SSH connection.
    • SSH+Netcat requires defining netcat ports and addresses.
  • Sources:
    • Select sources for replication.
    • Choose a periodic snapshot task as the source of snapshots to replicate.
    • Remote sources require defining a snapshot naming schema.
  • Destination:
    • 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.
  • Scheduling:
    • Run automatically starts the replication after a related periodic snapshot task completes.
    • To automate the task according to its own schedule, set that option and define a schedule for the replication task.

Creating an Advanced Replication Task

To use the advanced editor to create a replication task, go to Tasks > Replication Tasks, click ADD to open the Wizard, then click ADVANCED REPLICATION CREATION.

TasksReplicationAddAdvanced

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 Sources and Destination.

Name the task. 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.

Choose whether the local system is sending (Push) or receiving data (Pull) and decide what Transport method to use for the replication before configuring the other sections.

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 will send or receive 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.

TasksReplicationAddAvancedTransportOptions

For SSH+NETCAT replications, you also need to 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 will only continue 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, this is done by going to the Services screen, checking the SSH service configuration, and starting the service.

TasksReplicationAddAdvancedSource

By default, the replication task will use 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 will include just the dataset properties in the snapshots to be replicated. Additional options allow you to recursively replicate child dataset snapshots or exclude specific child datasets or properties from the replication.

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. 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 custom-20200325_09:15. Multiple schemas can be entered by pressing Enter to separate each schema.

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 that will be included in the replication task are those that match your defined schedule. 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 will run.

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 are failing to replicate to the destination system.

The destination is where replicated data is stored. Choosing a remote destination requires an SSH Connection to that system. Expanding the file browser shows the current datasets or zvols 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.

TasksReplicationAddAdvancedDestination

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

Encryption 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. The encryption key can be stored 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, so be sure that any snapshots that will be 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 will keep 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 also define your own Custom 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. A specific time must be defined for the replication task to run. It is recommended to 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. Using the custom scheduler is recommended when you need to fine-tune an exact time or day for the replication.

Tasks Advanced Scheduler

Choosing a preset fills in the rest of the fields. To customize a schedule, enter crontab values for the Minutes/Hours/Days.

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

Specific time ranges are set 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.

Lists of values can also be entered. 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, while entering * in Days means the task runs every day of the month, */2 means the task runs every other day.

Combining all the above examples together creates a schedule running a task each minute from 1:30-1:35 AM and 2:30-2:35 PM every other day.

There is 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. This is 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 shows when the current settings mean the task runs.

Examples of CRON syntax

SyntaxMeaningExamples
*Every item.* (minutes) = every minute of the hour.
* (days) = every day.
*/NEvery Nth item.*/15 (minutes) = every 15th minute of the hour (every quarter hour).
*/3 (days) = every 3rd day.
*/3 (months) = every 3rd month.
Comma and hyphen/dashEach 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.

Days can be specified as days of month, or days of week.

With these options, flexible schedules can be created similar to these examples:

Desired scheduleValues 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 and Friday, at 8.30 pmmonths=*; days=mon,wed,fri; hours=20; minutes=30
1st and 15th day of the month, during October to June, at 00:01 ammonths=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 FridayNote 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.

TasksReplicationAddAdvancedSchedule