Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / Copying Files and Directories with rsync

Copying Files and Directories with rsync

Publication Date: 27 Mar 2025
WHAT?

You can use the rsync tool to copy files locally or remotely. rsync is unidirectional and can copy files only in one direction.

WHY?

This article provides an overview of the rsync tool and its basic usage for copying files locally and remotely.

EFFORT

It takes up to 20 minutes to understand the basic usage of the rsync tool.

GOAL

Gain a foundational understanding of rsync and how to use it for file transfers.

REQUIREMENTS

Access permissions to the source and destination locations for copying files.

1 The rsync concept

 

You can use the rsync tool for transferring or copying files locally and remotely. rsync is unidirectional. It copies files in a single direction and does not synchronize data. Instead of transmitting all the contents in the file, rsync minimizes the amount of data copied by moving only the changes within the file. Hence, this supports the transfer of data over a slow network connection.

For copying large files using rsync, detecting changes requires certain computing power. So ensure that machines on both source and destination have enough resources, including RAM.

Use rsync when a large amount of data containing only minor changes needs to be transmitted regularly. This is useful when working with backups. rsync can also be useful for mirroring staging servers that store complete directory trees of Web servers to a Web server in a DMZ.

This article includes examples that show the usage of rsync to copy files locally and remotely. This document also explains how to configure and use an rsync server.

2 Basic rsync usage

 

You can use rsync on any machine where you have access and write permissions.

Copy files from the source location to the destination location as shown in the following example:

> rsync [OPTION] SOURCE [SOURCE]... DESTINATION

You can have multiple SOURCE entries and the SOURCE and DESTINATION placeholders can be paths, URLs or both.

Listed below are a few use cases of copying files:

  • > rsync -av /directory1/ /destination/

    In the above example, the trailing slash after the directory denotes the content of the directory and not the directory itself. In this, only the contents of /directory1 are copied to /destination.

  • > rsync -av /directory1 /destination/

    In the above example, the directory /directory1 is copied to /destination resulting in /directory2/directory1/.

  • > rsync -av example1.txt example2.txt /destination/directory/

    The above example shows copying the files example1.txt and example2.txt to the destination directory.

The commonly used OPTIONS are listed below:

  • -V

    shows verbose output text

  • -a

    archive mode; copies files recursively and preserves time stamps, user/group ownership, file permissions and symbolic links

  • -z

    compresses the transmitted data

  • -n or --dry-run

    performs a trial run with no changes made

  • -r

    recurse into directories

  • --progress

    shows progress during transfer

  • -b

    takes a backup during data synchronization

  • -h

    shows the numbers in the output in a human-readable format

  • -e

    for remote transfers, instructs rsync to use the SSH protocol

  • -q or --quiet

    silences the rsync command and option output

  • --version

    prints the rsync version number and exit

Copy files locally with compression
> rsync -avz example1.txt example2.txt /destination/

-a archive mode

-v verbose

-z compress data during transfer

Copy a directory with compression
> rsync -avz /sourcedirectory/ /destinationdirectory/

Transfers /sourcedirectory/ contents with compression.

Remote file transfer with compression
> rsync -avz example1.txt user@remote_host:/remote/destination/

Transfers example1.txt to a remote machine over SSH while compressing the data.

Remote directory transfer with compression
> rsync -avz /sourcedirectory/ user@remote_host:/remote/destination/

Transfers /sourcedirectory/ to a remote machine over SSH while compressing the data.

3 Copying files and directories with rsync locally

 

You can copy files within the same machine using rsync if you have write permission for the destination location.

To copy the file backup.tar.xz to the location /var/backup/, use the command rsync -avz backup.tar.xz /var/backup/.

The file backup.tar.xz is copied to /var/backup/, and the absolute path is/var/backup/backup.tar.xz.

4 Copying files and directories with rsync remotely

 

You can copy files from one machine to a remote machine using rsync. Ensure that you have rsync in both source and destination machines and that you are connected to the remote machine over SSH.

To copy a single file from one directory on your machine to the /var/backup directory on a remote machine, use the following command:

> rsync -avz example1.txt user@remote_host:/var/backup/
Note
Note: Trailing slash

Ensure that you add the trailing slash after the/var/backup/ directory. If you do not insert the slash, the file example1.txt is copied to /var/backup file and not inside the directory /var/backup/.

Verify the copied file in the absolute path /var/backup/example1.txt.

To copy the directory source/ and its contents into the directory /var/backup/: 

> rsync -avz /source/ user@remote_host:/var/backup/

Verify the copied directory in the absolute path /var/backup/source/.

5 Configuring and using an rsync server

 

An rsync server enables file synchronization, automated backups and centralized storage. You can run rsync as a daemon rsyncd listening on default port 873 for incoming connections. This daemon can receive copying targets.

Procedure 1: Setting up an rsync server
 

The configuration file for the rsync daemon is separated into a main file and certain modules which hold your backup target. This makes it easier to add additional targets later. You can store global values in /etc/rsyncd.d/*.inc files, whereas your modules are placed in /etc/rsyncd.d/*.conf.

The following description explains how to create an rsync server with a backup target. This target can be used to store your backups. To create an rsync server, do the following:

  1. On your local machine, create a directory /var/backup to store all your backup files.

    > mkdir /var/backup

  2. Specify ownership:

    In this example, the user tux in the group users owns the directory:

    > chown tux.users /var/backup

  3. Configure the rsyncd daemon:

    1. Create a directory /etc/rsyncd.d/

      > mkdir /etc/rsyncd.d/

    2. Create the main configuration file /etc/rsyncd.conf and add the following lines:

      log file = /var/log/rsync.log1
pid file = /var/lock/rsync.lock2
merge /etc/rsyncd.d3
include /etc/rsyncd.d4

      1

      /var/log/rsync.log is the location where rsync writes the logs.

      2

      /var/lock/rsync.lock is the file that contains the PID of the running rsync daemon instance.

      3

      Merges global values from /etc/rsyncd.d/*.inc files into the main configuration file.

      4

      Loads any modules (or targets) from /etc/rsyncd.d/*.conf files. These files must not contain any references to global values.

  4. Create your module or your backup target in the file /etc/rsyncd.d/backup.conf with the following lines:

    backup.conf: backup module
  [backup] 1
     uid = tux 2
     gid = users 3
     path = /var/backup 4
     auth users = tux 5
     secrets file = /etc/rsyncd.secrets 6
     comment = Our backup target 7

    In the given example:

    1

    [backup] is the backup target. You can use any name for the backup target. You may use a name according to its purpose and use the same name in your *.conf file.

    2

    uid = tux specifies the user name or group name that is used when the file transfer takes place.

    3

    gid = users defines the path to store your backups (from Step 1).

    4

    path = /var/backup defines the path to store your backups (from Step 1).

    5

    auth users = tux specifies a comma-separated list of allowed users. In its simplest form, it contains the user names that are allowed to connect to this module. In our case, only user tux is allowed.

    6

    secrets file = /etc/rsyncd.secrets specifies the path of a file that contains lines with user names and plain passwords.

  5. Create the /etc/rsyncd.secrets file with the following content and replace PASSPHRASE:

    # user:passwd
tux:PASSPHRASE

  6. Make sure the file is only readable by root: 

    chmod 0600 /etc/rsyncd.secrets

  7. Start and enable the rsyncd daemon with:

    >  systemctl enable rsyncd
>  systemctl start rsyncd

  8. On the remote machine, test the access to your rsync server: 

    >  rsync jupiter::

    A response similar to the following appears:

    backup Our backup target

    If the above response does not appear, verify your configuration file, firewall and network settings.

    The above steps create an rsync server that you can use to store backups. The example also creates a log file listing all connections. This file is stored in /var/log/rsyncd.log. This is useful for debugging your transfers.

  9. To list the content of your backup target, use the following command on your local machine:

    >  rsync -avz jupiter::backup

    This command lists all files present in the directory /var/backup on the server. This request is also logged in the log file /var/log/rsyncd.log.

  10. To copy the current directory to your rsync backup server, provide the source directory. If the source directory is your current directory, use .

    >  rsync -avz . jupiter::backup

    By default, rsync does not delete files and directories when it runs. To enable deletion, the additional option --delete must be stated. To ensure that no newer files are deleted, the option --update can be used instead. Any conflicts that arise must be resolved manually.

6 Deleting and updating files and directories with rsync

 

You can copy and synchronize files within the same machine using rsync if you have write permission for the destination location. You can also delete files or directories after copying.

To copy files example1.txt and example2.txt from /source/directory/ to /destination/directory/:

> rsync -av --update /source/directory/ /destination/directory/

The rsync command updates the files example1.txt and example2.txt in the /destination/directory/ if it is older than the source file. If the version in the destination is newer, then the files will not be overwritten. Also, all other new files or directories from /source/directory/ will be copied to /destination/.

To copy an existing file and delete a file that does not exist in the destination directory:

> rsync -av --delete /source/directory/ /destination/directory/

In this scenario, both the source and destination directories contain example1.txt and example2.txt. The /destination/directory contains an extra file, example3.txt.

The rsync command copies or updates the files example1.txt and example2.txt from /source/directory/ to /destination/directory/. The command also deletes the file example3.txt from /destination/directory/ as it does not exist in the /source/directory/. Also, the directory structure in /destination/directory/ is cleaned up to match the /source/directory/.

7 Troubleshooting rsync

 

File or folder copying may fail due to several reasons. Ensure that you have the required permissions and resources to perform the file copy.

Possible troubleshooting methods are mentioned below:

  • Ensure that you have the latest version of rsync. To transfer files or directories remotely, ensure that rsync is installed on both the source and destination machines.

  • Ensure that you have the required rsync access permission.

  • Ensure that you provide the correct host name to copy files remotely.

  • Ensure that the rsync service is running if you are using rsync in daemon mode.