puppetlabs-rsync

[!NOTE] This module is supported by the Puppet community. We expect it to be of the same high quality as our own Supported modules, but it does not qualify for Puppet Support plans. See the CODEOWNERS file for usernames of the maintainers.

Table of Contents

1. Module Description - What does the module do?
2. Usage - Configuration options and additional functionality
3. Reference - An under-the-hood peek at what the module is doing and how
   • Classes
   • Defined Types
4. Limitations - OS compatibility, etc.

Module description

puppetlabs-rsync manages rsync clients, repositories, and servers as well as providing defines to easily grab data via rsync.

Usage

Install the latest version of rsync

class { 'rsync':
  package_ensure => 'latest'
}

Get file 'foo' via rsync

rsync::get { '/foo':
  source  => "rsync://${rsyncServer}/repo/foo/",
  require => File['/foo'],
}

Put file 'foo' on 'rsyncDestHost'

rsync::put { '${rsyncDestHost}:/repo/foo':
  user    => 'user',
  source  => "/repo/foo/",
}

Setup default rsync repository

rsync::server::module{ 'repo':
  path    => $base,
  require => File[$base],
}

To disable default values for incoming_chmod and outgoing_chmod, and do not add empty values to the resulting config, set both values to false

rsync::server::module { 'repo':
  path           => $base,
  incoming_chmod => false,
  outgoing_chmod => false,
  require        => File[$base],
}

Configuring via Hiera

rsync::put, rsync::get, and rsync::server::module resources can be configured using Hiera hashes. For example:

rsync::server::modules:
  myrepo:
    path: /mypath
    incoming_chmod: false
    outgoing_chmod: false
  myotherrepo:
    path: /otherpath
    read_only: false

Reference

Classes:

• rsync

Defined Types:

• rsync::get
• rsync::put
• rsync::server::module

Classes

rsync

Manage the rsync package.

package_ensure

Ensure the for the rsync package. Any of the valid values for the package resource (present, absent, purged, held, latest) are acceptable.

Default value: 'installed'

manage_package

Setting this to false stops the rsync package resource from being managed.

Default value: true

Defined Types

rsync::get

get files via rsync

source

Required

Source to copy from.

path

Path to copy to.

Default value: $name

user

Username on remote system

purge

If set, rsync will use '--delete'

recursive

If set, rsync will use '-r'

links

If set, rsync will use '--links'

hardlinks

If set, rsync will use '--hard-links'

copylinks

If set, rsync will use '--copy-links'

times

If set, rsync will use '--times'

exclude

String (or array of strings) paths for files to be excluded.

include

String (or array of strings) paths for files to be explicitly included.

exclude_first

If true, exclude first and then include; the other way around if false.

Default value: true

keyfile

SSH key used to connect to remote host.

timeout

Timeout in seconds.

Default value: 900

execuser

User to run the command (passed to exec).

options

Default options to pass to rsync (-a).

chown

USER:GROUP simple username/groupname mapping.

chmod

File and/or directory permissions.

logfile

Log file name.

onlyif

Condition to run the rsync command.

rsync::put

put files via rsync

source

Required

Source to copy from.

path

Path to copy to.

Default value: $name

user

Username on target remote system.

purge

If set, rsync will use '--delete'

exclude

String (or array of strings) paths for files to be excluded.

include

String (or array of strings) paths for files to be explicitly included.

exclude_first

If true, exclude first and then include; the other way around if false.

Default value: true

keyfile

Path to SSH key used to connect to remote host.

Default value: '/home/${user}/.ssh/id_rsa'

timeout

Timeout in seconds.

Default value: 900

options

Default options to pass to rsync (-a)

rsync::server::module

Sets up a rsync server

path

Required

Path to data.

comment

Rsync comment.

motd

File containing motd info.

pid_file

PID file. Defaults to /var/run/rsyncd.pid. The pid file parameter won't be applied if set to "UNSET"; rsyncd will not use a PID file in this case.

read_only

yes||no

Default value: 'yes'

write_only

yes||no

Default value: 'no'

list

yes||no

Default value: 'no'

uid

uid of rsync server

Default value: 0

gid

gid of rsync server

Default value: 0

incoming_chmod

Incoming file mode

Default value: '644'

outgoing_chmod

Outgoing file mode

Default value: '644'

max_connections

Maximum number of simultaneous connections allowed

Default value: 0

lock_file

File used to support the max connections parameter. Only needed if max_connections > 0.

Default value: '/var/run/rsyncd.lock'

secrets_file

Path to the file that contains the username:password pairs used for authenticating this module.

auth_users

List of usernames that will be allowed to connect to this module (must be undef or an array).

hosts_allow

List of patterns allowed to connect to this module (rsyncd.conf man page for details, must be undef or an array).

hosts_deny

List of patterns allowed to connect to this module (rsyncd.conf man page for details, must be undef or an array).

transfer_logging

Parameter enables per-file logging of downloads and uploads in a format somewhat similar to that used by ftp daemons.

log_format

This parameter allows you to specify the format used for logging file transfers when transfer logging is enabled. See the rsyncd.conf man page for more details.

refuse_options

List of rsync command line options that will be refused by your rsync daemon.

ignore_nonreadable

This tells the rsync daemon to completely ignore files that are not readable by the user.

Parameters:

$source        - source to copy from
$path          - path to copy to, defaults to $name
$user          - username on remote system
$purge         - if set, rsync will use '--delete'
$exclude       - string (or array) to be excluded
$include       - string (or array) to be included
$exclude_first - if 'true' (default) then first exclude and then include; the other way around if 'false'
$keyfile       - path to ssh key used to connect to remote host, defaults to /home/${user}/.ssh/id_rsa
$timeout       - timeout in seconds, defaults to 900
$options       - default options to pass to rsync (-a)

Actions:

put files via rsync

Requires:

$source must be set

Sample Usage:

rsync::put { '${rsyncDestHost}:/repo/foo':
  user    => 'user',
  source  => "/repo/foo/",
}

Definition: rsync::server::module

sets up a rsync server

Parameters:

$path            - path to data
$comment         - rsync comment
$use_chroot      - yes||no, defaults to yes
$motd            - file containing motd info
$read_only       - yes||no, defaults to yes
$write_only      - yes||no, defaults to no
$list            - yes||no, defaults to no
$uid             - uid of rsync server, defaults to 0
$gid             - gid of rsync server, defaults to 0
$numeric_ids     - don't resolve uids to usernames, defaults to yes
$incoming_chmod  - incoming file mode, defaults to 644
$outgoing_chmod  - outgoing file mode, defaults to 644
$max_connections - maximum number of simultaneous connections allowed, defaults to 0
$timeout         - disconnect client after X seconds of inactivity, defaults to 0
$lock_file       - file used to support the max connections parameter, defaults to /var/run/rsyncd.lock only needed if max_connections > 0
$secrets_file    - path to the file that contains the username:password pairs used for authenticating this module
$auth_users      - list of usernames that will be allowed to connect to this module (must be undef or an array)
$hosts_allow     - list of patterns allowed to connect to this module (man 5 rsyncd.conf for details, must be undef or an array)
$hosts_deny      - list of patterns allowed to connect to this module (man 5 rsyncd.conf for details, must be undef or an array)
$transfer_logging - parameter enables per-file logging of downloads and uploads in a format somewhat similar to that used by ftp daemons.
$log_file         - log messages to the indicated file rather than using syslog
$log_format       - This parameter allows you to specify the format used for logging file transfers when transfer logging is enabled. See the rsyncd.conf documentation for more details.
$refuse_options  - list of rsync command line options that will be refused by your rsync daemon.
$include         - list of files to include
$include_from    - file containing a list of files to include
$exclude         - list of files to exclude
$exclude_from    - file containing a list of files to exclude
$dont_compress   - disable compression on matching files
$ignore_nonreadable - This  tells  the  rsync daemon to completely ignore files that are not readable by the user.

Actions:

sets up an rsync server

Requires:

$path must be set

Sample Usage:

# setup default rsync repository
rsync::server::module{ 'repo':
  path    => $base,
  require => File[$base],
}

To disable default values for incoming_chmod and outgoing_chmod, and do not add empty values to the resulting config, set both values to false

rsync::server::module { 'repo':
  path           => $base,
  incoming_chmod => false,
  outgoing_chmod => false,
  require        => File[$base],
}

Configuring via Hiera

rsync::put, rsync::get, and rsync::server::module resources can be configured using Hiera hashes. For example: