Configuring Rsync Tasks

Rsync provides fast incremental data transfer to synchronize files between a TrueNAS system and a remote system. The Push function copies data from TrueNAS to a remote system. The Pull function copies data from a remote system to the TrueNAS local host system and stores it in the dataset defined in the Path field.

There are two ways to connect to a remote system and run an rsync task:

• Set up an SSH connection to the remote server.
• Set up an rsync module for the remote server.

An rsync task has two basic methods:

• Module
• SSH

Module mode requires adding an rsync app to the remote system, configuring a module on that system, and then entering it in the rsync task in TrueNAS.

SSH mode has two connection options:

• SSH private key stored in the user’s home directory
• SSH connection for the keychain

Setting options change based on the SSH connection option selected.

Before adding an rsync task using the SSH private key stored in the user’s home directory option:

1. Go to Credentials > Backup Credentials to add an SSH connection and keypair for the remote system.
2. Download the SSH keypair to your system
3. Add the private key to the home directory for the admin user you plan to use for the rsync task.

TrueNAS allows configuring multiple admin users on the system. All admin users configured in the TrueNAS system show in the rsync task User dropdown list.

See Adding SSH Credentials for more information on keypairs.

Enabled SSH on both the local host TrueNAS, and the remote destination system.

You can use the SSS connection created in Setting Up an SSH Connection or create a new connection while configuring the rsync task.

1. Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.

   

2. Enter or browse to the dataset or folder to sync with the remote server. Use the arrow_right to the left of the /mnt folder and each folder listed on the tree to expand and browse through, then click on the name to populate the path field.

   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.

   

3. Select the administration user for the local host TrueNAS system from the User dropdown. This is the user account to perform the rsync task. The user must have read/write permissions for the local dataset.

4. Set the Direction for the rsync task. Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.

5. Set the Rsync Mode to SSH, and then select the connection method from the Connect using dropdown list. Settings fields for the selected connection type show.

   Leave this set to Module if syncing with a non-TrueNAS remote system. See Addin an Rsync Task Using Module Mode for more information.

   If selecting SSH private key stored in the user home directory, the public key for the SSH connection must be alread be saved in the home directory for the admin user.

   If selecting SSH connection from the keychain, choose either the existing SSH credential from the SSH Connection dropdown list or select Add New to open the New SSH Connection configuration screen. See Using an SSH Connection below for more information.

   If the connection fails, the system lets you know what is wrong so you can correct the issue with the connection.

6. Enter the full path to the dataset on the remote server in Remote Path. The maximum path length is 255 characters.

   To confirm the remote server is reachable and the path exists, leave Validate Remote Path selected.

7. Select a schedule for when to run this task and any other options you want to use.

   

   If you need a custom schedule, select Custom to open the advanced scheduler window.

   Advanced Scheduler

   

   Choosing a Presets option populates 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.

   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 displays when the current settings mean the task runs.

   Examples of CRON syntax

   Syntax	Meaning	Examples
   *	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.

8. Leave Enabled selected. Clear the checkbox to disable the task without deleting the configuration.

9. Click Save. The system verifies the SSH connection and adds the task to the Rsync Tasks widget.

To run the rsync task at any time, select it on the Rsync Tasks widget, click on the vertical ellipses more_vert for the task, and select the Run Now.

The TrueNAS UI allows users to select an existing SSH connection or to create a new connection while configuring the task. The New SSH Connection screen opened using the Add New option in the rsync task and accessed while on the Backup Credentials screen are essentially the same and show the same setting options.

To set up a new SSH connection before adding an rsync task, go to Credentials > Backup Credentials and click Add on the SSH Connections widget. See Adding SSH Credentials for more information on adding SSH Connections and key pairs.

To add a new connection while configuring the rsync task on the Add Rsync Task screen, set the mode to SSH, select SSH connection for the keychain, and then select Add New on the SSH Connection dropdown list. The New SSH Connection screen opens.

Next, set up a home directory for the system administrator on the remote system if one does not already exist. If the remote system is a TrueNAS, edit the user to add the public key. In TrueNAS, go to Users, click Edit, and paste the key into the pubic key field.

After adding the SSH connection, go to System > Services to turn on the SSH service. We don’t recommend leaving the SSH service turned on when not in use for security hardening. Turn it on before the rsync task is scheduled to run, then off again after the task completes to keep your system secured. (Optional) To automatically start or restart the SSH service after a system restart, select this option. Enable the SSH service on the remote system according to the configuration process for a non-TrueNAS system.

Before you create an rsync task in module mode, you must define at least one module per rsyncd.conf(5) on the remote rsync server. The Rsync Daemon application is available in situations where configuring TrueNAS as an rsync server with an rsync module is necessary.

After configuring the remote server with rsync and a module, configure the rsync task in TrueNAS.

If the non-TruNAS remote server includes an rsync service, make sure it is turned on. To configure a module on the remote server:

1. Create a dataset. Write down the host and path to the data on the remote system you plan to sync with.

2. Create an rsync module.

   If the remote system is not a TrueNAS and has an rsync app installed, create a module according to the configuration process for that app and system. If the remote system is not a TrueNAS, install an rsync app, such as Rsyncd, and configure it per the instructions for the app and your remote non-TrueNAS system.

   If the remote system is another TrueNAS, install an rsync app. Debian-based TrueNAS systems include the Rsync Daemon app in the Community app catalog. Install the app and use it to configure a module.

   Configuring a module in the TrueNAS RsyncD app

   To create the module, you need the IP address or host name of your TrueNAS (host) server. The host server is configured with the rsync task that transfers your data to the remote server.

   When the remote system is a Debian-based TrueNAS system, go to Apps > Discover Apps and search for the Rsync Daemon app.

   Click on the widget, and then click Install to open the installation wizard.

   To add a module, click Add to the right of Rsync Modules, then:

   1. Assign a name. This name is added in the Add Rsync Task screen on your TrueNAS system when you set up a task using Module in the Rsync Mode field.
   2. (Optional) Enter a comment to help you remember the purpose of this module or where it is used.
   3. Select the host path for the rsyncd app. You can use Create Dataset to add a new dataset, and repeat to add a new child dataset if not selecting an existing dataset.
   4. Set the level of access by selecting the option on the Access Mode dropdown list.
   5. (Optional) Add IP addresses to the Host Allow or Host Deny options if you want to narrow access to this module.
   6. Take note of the name of the module and the host path to it or use in later when you add the rsync task in your TrueNAS system.

   Complete the rest of the app configuration to suit your use case, and click Install. The app shows in the TrueNAS UI on the Applications screen as Running when fully deployed.

To configure the rsync task using module mode, you need:

• The name of the module
• The IP address or host name for the remote server
• The path to the dataset

Go to Data Protection and click Add on the Rsync Tasks widget to open the Add Rsync Task screen.

1. Enter or browse to and select the dataset or folder to sync with the remote server. Clicking on the dataset name populates the path field.

   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.

   

2. Select the admin account to perform the rsync task on the User dropdown list. The user must have permissions to run an rsync on the remote server and read/write permission for the local dataset.

3. Set the Direction for the rsync task. Select Pull to copy from the remote server to TrueNAS or Push to copy to the remote server.

4. Set the Rsync Mode to Module. The module settings fields show.

5. Enter the remote host name or IP in Remote Host.

6. Set the schedule for when to run this task, and any other options you want to use.

   

   If you need a custom schedule, select Custom to open the advanced scheduler window.

   Advanced Scheduler

   

   Choosing a Presets option populates 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.

   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 displays when the current settings mean the task runs.

   Examples of CRON syntax

   Syntax	Meaning	Examples
   *	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.

7. Leave the Enabled selected to enable the task. Clear the checkbox to disable the task without deleting the configuration.

8. Click Save.

You can run the rsync task by clicking then the Run Now play_arrow icon for the rsync task on the Rsync Task widget.