rsync Cookbook

May 6, 2026 · View on GitHub

Rsync cookbook with custom resources for installing rsync and managing rsyncd modules. More info on rsyncd options can be found in the Docs.

Migration

This release removes the legacy recipes and attributes. See migration.md for the resource migration guide.

Requirements

Platforms

AlmaLinux 8+
Amazon Linux 2023+
CentOS Stream 9+
Debian 12+
Fedora
Oracle Linux 8+
Red Hat Enterprise Linux 8+
Rocky Linux 8+
Ubuntu 22.04+

Chef

Chef >= 15.3

Resources

serve

This resource implements an rsync server module. The following params are chef-only, the rest implement the feature as described in the [rsyncd docs][1].

Parameters

Required

path - Path which this module should serve.

Optional

Unless specified these parameters use the rsyncd default values as referenced in the [Rsyncd docs][1]. Params are Strings unless specified otherwise.

name - The name of this module that will be referenced by rsync://foo/NAME. Defaults to the resource name.
config_path - Path to write the rsyncd config. Defaults to /etc/rsyncd.conf.
globals - Hash of global rsyncd directives for the config file.
service_name - Service to notify when the config changes.
comment - Comment when rsync gets the list of modules from the server.
read_only - Boolean - Serve this as a read-only module.
write_only - Boolean - Serve this as a write-only module.
list - Boolean - Add this module the the rsync modules list.
uid - String - User name or user ID that file transfers use when the daemon runs as root.
gid - String - Group name or group ID that file transfers use when the daemon runs as root.
auth_users - Comma and space-separated list of usernames allowed to connect to this module. [more info][1]
secrets_file - File containing username:password pairs for authenticating this module. [more info][1]
hosts_allow - Hostname and IP patterns allowed to connect. [more info][1]
hosts_deny - Hostname and IP patterns denied from connecting. [more info][1]
max_connections - Integer - *Default: 0 - The maximum number of simultaneous connections.
munge_symlinks - Boolean - *Default: true - Modify incoming symlinks in a safe, recoverable way. [more info][1]
use_chroot - Boolean - Chroot to the module path before starting file transfer.
numeric_ids - Boolean - *Default: true - Disable user/group name mapping for the module.
fake_super - Boolean - Store full file attributes without running the daemon as root.
exclude_from - File containing daemon exclude patterns. [more info][1]
exclude - Daemon exclude patterns. [more info][1]
include_from - Analogue of exclude_from.
include - Analogue of exclude.
strict_modes - Boolean - Require the secrets file to be readable only by the daemon user ID.
log_file - Module log file path.
log_format - Per-transfer log format. [more info][1]
transfer_logging - Enables per-file logging of downloads and uploads.
timeout - Integer - Default: 600 - Client timeout in seconds.
dont_compress - Filename patterns that should not be compressed.
lock_file - Lock file used to support max_connections.
refuse_options - Space-separated list of refused rsync command-line options.
prexfer_exec - Command to run before each transfer to or from this module.
postxfer_exec - Command to run after each transfer to or from this module.

Usage

After loading the rsync cookbook you have access to the rsync_serve resource for serving up a generic rsyncd module with many options.

Declare rsync_install and rsync_service before rsync_serve when managing a daemon.

Examples

Serve a directory:

rsync_install 'default'
rsync_service 'default'

rsync_serve 'tmp' do
  path '/tmp'
end

Serve a directory with read only and specify uids:

rsync_install 'default'
rsync_service 'default'

rsync_serve 'tmp' do
  path      '/tmp'
  uid       'nobody'
  gid       'nobody'
  read_only true
end

A more complex example with networking:

rsync_install 'default'
rsync_service 'default'

rsync_serve 'centos-prod' do
  path             '/data/repos/prod/centos'
  comment          'CentOS prod mirror'
  read_only        true
  use_chroot       true
  list             true
  uid              'nobody'
  gid              'nobody'
  hosts_allow      '127.0.0.1, 10.4.1.0/24, 192.168.4.0/24'
  hosts_deny       '0.0.0.0/0'
  max_connections  10
  transfer_logging true
  log_file         '/tmp/centos-sync'
  postxfer_exec    '/usr/local/bin/collect_things.sh'
end

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers!