Documentation

synchronize - Uses rsync to make synchronizing file paths in your playbooks quick and easy.

New in version 1.4.

Synopsis

synchronize is a wrapper around the rsync command, meant to make common tasks with rsync easier. It is run and originates on the local host where Ansible is being run. Of course, you could just use the command action to call rsync yourself, but you also have to add a fair number of boilerplate options and host facts. You still may need to call rsync directly via command or shell depending on your use case. synchronize does not provide access to the full power of rsync, but does make most invocations easier to follow.

Options

parameter required default choices comments
archive
no yes
  • yes
  • no
Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D.
checksum
(added in 1.6)
no no
  • yes
  • no
Skip based on checksum, rather than mod-time & size; Note that that "archive" option is still enabled by default - the "checksum" option will not disable it.
compress
(added in 1.7)
no yes
  • yes
  • no
Compress file data during the transfer. In most cases, leave this enabled unless it causes problems.
copy_links
no no
  • yes
  • no
Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink.
delete
no no
  • yes
  • no
Delete files that don't exist (after transfer, not before) in the src path. This option requires recursive=yes.
dest
yes
    Path on the destination host that will be synchronized from the source; The path can be absolute or relative.
    dest_port
    (added in 1.5)
    no Value of ansible_ssh_port for this host, remote_port config setting, or 22 if none of those are set
      Port number for ssh on the destination host. Prior to ansible 2.0, the ansible_ssh_port inventory var took precedence over this value.
      dirs
      no no
      • yes
      • no
      Transfer directories without recursing
      existing_only
      (added in 1.5)
      no no
      • yes
      • no
      Skip creating new files on receiver.
      group
      no the value of the archive option
      • yes
      • no
      Preserve group
      links
      no the value of the archive option
      • yes
      • no
      Copy symlinks as symlinks.
      mode
      no push
      • push
      • pull
      Specify the direction of the synchronization. In push mode the localhost or delegate is the source; In pull mode the remote host in context is the source.
      owner
      no the value of the archive option
      • yes
      • no
      Preserve owner (super user only)
      partial
      (added in 2.0)
      no
        Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster.
        perms
        no the value of the archive option
        • yes
        • no
        Preserve permissions.
        recursive
        no the value of the archive option
        • yes
        • no
        Recurse into directories.
        rsync_opts
        (added in 1.6)
        no
          Specify additional rsync options by passing in an array.
          rsync_path
          no
            Specify the rsync command to run on the remote host. See --rsync-path on the rsync man page.
            rsync_timeout
            no
              Specify a --timeout for the rsync command in seconds.
              set_remote_user
              no True
                put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host that does not match the inventory user, you should set this parameter to "no".
                src
                yes
                  Path on the source host that will be synchronized to the destination; The path can be absolute or relative.
                  times
                  no the value of the archive option
                  • yes
                  • no
                  Preserve modification times
                  use_ssh_args
                  (added in 2.0)
                  no no
                  • yes
                  • no
                  Use the ssh_args specified in ansible.cfg
                  verify_host
                  (added in 2.0)
                  no
                    Verify destination host key.

                    Examples

                    # Synchronization of src on the control machine to dest on the remote hosts
                    synchronize: src=some/relative/path dest=/some/absolute/path
                    
                    # Synchronization using rsync protocol (push)
                    synchronize: src=some/relative/path/ dest=rsync://somehost.com/path/
                    
                    # Synchronization using rsync protocol (pull)
                    synchronize: mode=pull src=rsync://somehost.com/path/ dest=/some/absolute/path/
                    
                    # Synchronization using rsync protocol on delegate host (push)
                    synchronize: >
                        src=/some/absolute/path/ dest=rsync://somehost.com/path/
                        delegate_to: delegate.host
                    
                    # Synchronization using rsync protocol on delegate host (pull)
                    synchronize: >
                        mode=pull src=rsync://somehost.com/path/ dest=/some/absolute/path/
                        delegate_to: delegate.host
                    
                    # Synchronization without any --archive options enabled
                    synchronize: src=some/relative/path dest=/some/absolute/path archive=no
                    
                    # Synchronization with --archive options enabled except for --recursive
                    synchronize: src=some/relative/path dest=/some/absolute/path recursive=no
                    
                    # Synchronization with --archive options enabled except for --times, with --checksum option enabled
                    synchronize: src=some/relative/path dest=/some/absolute/path checksum=yes times=no
                    
                    # Synchronization without --archive options enabled except use --links
                    synchronize: src=some/relative/path dest=/some/absolute/path archive=no links=yes
                    
                    # Synchronization of two paths both on the control machine
                    local_action: synchronize src=some/relative/path dest=/some/absolute/path
                    
                    # Synchronization of src on the inventory host to the dest on the localhost in pull mode
                    synchronize: mode=pull src=some/relative/path dest=/some/absolute/path
                    
                    # Synchronization of src on delegate host to dest on the current inventory host.
                    synchronize:
                        src: /first/absolute/path
                        dest: /second/absolute/path
                    delegate_to: delegate.host
                    
                    # Synchronize two directories on one remote host.
                    synchronize:
                        src: /first/absolute/path
                        dest: /second/absolute/path
                    delegate_to: "{{ inventory_hostname }}"
                    
                    # Synchronize and delete files in dest on the remote host that are not found in src of localhost.
                    synchronize: src=some/relative/path dest=/some/absolute/path delete=yes
                    
                    # Synchronize using an alternate rsync command
                    # This specific command is granted su privileges on the destination
                    synchronize: src=some/relative/path dest=/some/absolute/path rsync_path="su -c rsync"
                    
                    # Example .rsync-filter file in the source directory
                    - var       # exclude any path whose last part is 'var'
                    - /var      # exclude any path starting with 'var' starting at the source directory
                    + /var/conf # include /var/conf even though it was previously excluded
                    
                    # Synchronize passing in extra rsync options
                    synchronize:
                        src: /tmp/helloworld
                        dest: /var/www/helloword
                        rsync_opts:
                          - "--no-motd"
                          - "--exclude=.git"
                    

                    Notes

                    Note

                    rsync must be installed on both the local and remote host.

                    Note

                    For the synchronize module, the “local host” is the host the synchronize task originates on, and the “destination host” is the host synchronize is connecting to.

                    Note

                    The “local host” can be changed to a different host by using delegate_to. This enables copying between two remote hosts or entirely on one remote machine.

                    Note

                    The user and permissions for the synchronize src are those of the user running the Ansible task on the local host (or the remote_user for a delegate_to host when delegate_to is used).

                    Note

                    The user and permissions for the synchronize dest are those of the remote_user on the destination host or the become_user if become=yes is active.

                    Note

                    In 2.0.0.0 a bug in the synchronize module made become occur on the “local host”. This was fixed in 2.0.1.

                    Note

                    Expect that dest=~/x will be ~<remote_user>/x even if using sudo.

                    Note

                    Inspect the verbose output to validate the destination user/host/path are what was expected.

                    Note

                    To exclude files and directories from being synchronized, you may add .rsync-filter files to the source directory.

                    Note

                    rsync daemon must be up and running with correct permission when using rsync protocol in source or destination path.

                    This is a Core Module

                    For more information on what this means please read Core Modules

                    For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.