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

Configuring Rsync Tasks

Rsync provides fast incremental data transfer to synchronize files between a TrueNAS host 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:

Configuring SSH Mode Rsync Tasks

Before you create an rsync task in SSH mode, add an SSH connection and keypair between the TrueNAS host and remote system. See Adding SSH Credentials for more information.

After setting up the SSH connection, configure the rsync task on the TrueNAS host.

Setting Up an SSH Connection

You can set up a new SSH connection on the Credentials > Backup Credentials screen by clicking Add on the SSH Connections widget, or while setting up a new rsync task using the option to select SSH connection from the keychain in the Connect using field and selecting Add New in SSH Connection on the Add Rsync Task screen.

The following procedure provides instructions on setting up an SSH connection using the New SSH Connection screen.

Enable SSH on both the local and remote systems. On the local TrueNAS host system, go to System > Services and toggle SSH to on, and enable the SSH service on the remote host system.

Set up a home directory for the remote system administrator on the remote system. Note the path to where home directories are stored to enter on the local host TrueNAS.

If the remote system is also a TrueNAS, go to Credentials, select Users to see the list of users. Select the administration user and click Edit.

If creating a new administration user, for rsync functions, click Add. See Managing Users for more information. Take note of the path to the home directory to use in setting up the connection.

Add an SSH connection for the remote server on the local TrueNAS host system.

Adding a remote TrueNAS system

Click Add on the SSH Connections widget to open the configuration screen:

  1. Enter a name for the connection, then select the Setup Method.

    If establishing an SSH connection to another TrueNAS server use the default Semi-automatic (TrueNAS only) option.

    If connecting to a non-TrueNAS server select Manual from the dropdown list.

  2. Enter the authentication settings.

    a. Enter a valid URL scheme for the remote TrueNAS URL in TrueNAS URL. If specifying an IPv6 address, you must enter the IPv6 address enclosed in square brackets. For example, https://[ffff:ff:59f1:123::12].

    b. Enter an admin user name, which is the username on the remote system entered to log in via the web UI to set up the connection. You can leave Admin Username set to the default root user, then enter the user password in Admin Password.

    c. (Optional) Enter the one-time password in One-Time Password (if necessary) if two-factor authentication is enabled.

    d. Enter a Username, which is the user name on the remote system to log in via SSH.

    e. Enter or import the private key from a previously created SSH key pair, or select Generate New to create a new one.

  3. (Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.

  4. Click Save.

    Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys. The new SSH connection displays on the SSH Connection widget. To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.

Adding a connection to a non-TrueNAS remote host system

Click Add on the SSH Connections widget to open the configuration screen:

  1. Enter a name for the connection, then select Manual from the Setup Method dropdown list.

  2. Enter the authentication settings.

    a. Enter a host name or host IP address for the remote non-TrueNAS system as a valid URL. An IP address example is https://10.231.3.76. This is a required field.

    b. Enter the port number of the remote system to use for the SSH connection.

    c. Enter a user name for logging into the remote system in Username.

    d. Select the private key from the SSH key pair that you use to transfer the public key on the remote NAS from the Private Key dropdown.

    e. Click Discover Remote Host Key after properly configuring all other fields to query the remote system and automatically populate the Remote Host Key field.

  3. (Optional) Enter the number of seconds you want to wait for the remote TrueNAS system to connect in Connect Timeout.

  4. Click Save.

    Saving a new connection automatically opens a connection to the remote TrueNAS and exchanges SSH keys. The new SSH connection displays on the SSH Connection widget. To edit it, click on the name to open the SSH Connections configuration screen populated with the saved settings.

The generated keypair shows on the SSH Keypair widget. To download the public and private keypairs, click the for the new keypair on the SSH Keypairs widget.

Adding an Rsync Task

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. Select SSH as the connection mode from the Rsync Mode dropdown to use an SSH connection. The settings fields show.

    Set this to Module if syncing with a non-TrueNAS remote system. See Setting Up an Rsync Task Using Module Mode for more information.

  6. Choose a connection method from the Connect using dropdown list.

    If selecting SSH private key stored in user’s home directory, the public key for the SSH connection must be saved in the home directory for administration user. To accomplish this, copy the public key from the SSH Keypair and paste into the Authorized Keys field on the Edit User screen.

    If selecting SSH connection from the keychain the system grabs the key for you, and select either the existing SSH credential from the SSH Connection dropdown list or select Add New to open the New SSH Connection configuration screen.

  7. Enter the full path to the dataset on the remote server to either pull from or push to in Remote Path. Maximum path length is 255 characters.

    If the remote path location does not exist, select Validate Remote Path to create and define it in Remote Path.

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

    DataProtectionSMARTTestAdvancedSchedSCALE

    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

    SyntaxMeaningExamples
    *Every item.* (minutes) = every minute of the hour.
    * (days) = every day.
    */NEvery Nth item.*/15 (minutes) = every 15th minute of the 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.

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

  9. Select the Enabled to enable the task. Leave cleared to disable the task but not delete the configuration. You can run the rsync task at any time from the Rsync Taks widget by the Run Now icon for the rsync task.

  10. Click Save. The system verifies the SSH connection and adds the task to the Rsync Tasks widget. If the connection fails the system lets you know what went wrong so you can correct the issue with the connection.

Configuring Module Mode Rsync Tasks

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 rsync server, configure the rsync task.

Defining an Rsync Module

If the non-TruNAS remote server includes an rsync service, make sure it is turned on.

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

  2. Create an rsync module on the remote system. On TrueNAS, install an rsync app (such as Rsyncd) and configure the module.

Setting Up an Rsync Task Using Module Mode

  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 a User account to perform the rsync task. The user must have permissions to run an rsync on the remote server and read/write permission 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. Select Module as the connection mode from the Rsync Mode dropdown. The module settings fields show.

  6. Enter the remote host name or IP in Remote Host. Use the format username@remote_host when the username differs from the host entered into the Remote Host field.

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

    DataProtectionSMARTTestAdvancedSchedSCALE

    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

    SyntaxMeaningExamples
    *Every item.* (minutes) = every minute of the hour.
    * (days) = every day.
    */NEvery Nth item.*/15 (minutes) = every 15th minute of the 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.

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

  8. Select the Enabled to enable the task. Leave cleared to disable the task but not delete the configuration.

    You can run the rsync task by clicking then the Run Now icon for the rsync task.

  9. Click Save.