New in version 1.4.
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.
parameter | required | default | choices | comments |
---|---|---|---|---|
archive |
no | yes |
|
Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D. |
checksum (added in 1.6) |
no | 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 |
|
Compress file data during the transfer. In most cases, leave this enabled unless it causes problems. |
copy_links |
no | no |
|
Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink. |
delete |
no | 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 |
|
Transfer directories without recursing |
existing_only (added in 1.5) |
no | no |
|
Skip creating new files on receiver. |
group |
no | the value of the archive option |
|
Preserve group |
links |
no | the value of the archive option |
|
Copy symlinks as symlinks. |
mode |
no | push |
|
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 |
|
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 |
|
Preserve permissions. |
recursive |
no | the value of the archive option |
|
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 |
|
Preserve modification times |
use_ssh_args (added in 2.0) |
no | no |
|
Use the ssh_args specified in ansible.cfg |
verify_host (added in 2.0) |
no | Verify destination host key. |
# 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"
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.
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.