Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

syncthing

Syncthing module for Puppet.
Project URLRSS FeedReport issues

21,959 downloads

10,460 latest version

4.3 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.1.3 (latest)
  • 1.0.0
  • 0.3.1
  • 0.3.0
  • 0.2.6
  • 0.2.3
  • 0.2.1
  • 0.2.0
  • 0.1.0
released Apr 23rd 2017
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.0.0 < 5.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'whefter-syncthing', '1.1.3'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add whefter-syncthing
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install whefter-syncthing --version 1.1.3

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

whefter/syncthing — version 1.1.3 Apr 23rd 2017

#syncthing Build Status

Compatibility note: the Puppet 3.7.0 and 3.8.0 compatibility has been dropped from metadata.json because the Puppet Forge does not provide a way to specifiy "compatible with Puppet 3.8.0 with future parser enabled". The module is, in fact, compatible with Puppet 3.7.0/3.8.0 with future parser enabled.

Version 1.0.0 has a (small) number of incompatible changes, most notably:

  • The version parameter has been renamed to package_version to reflect that this will only affact the version of the package installed, not of binaries.
  • Almost all defined types relevant to instance configuration now require instance_name in addition to home_path.
  • On the plus side, it is now possible to create what I like to call "binary" instances that install a defined version of the syncthing binary. See the binary_version parameter for more details.

####Table of Contents

  1. Overview
  2. Simple setup
  3. Usage - Classes and defined types available for configuration
  4. Limitations - OS compatibility, etc.

##Overview This module is still very much beta. Syncthing itself is still changing rapidly and has a few quirks.

This Syncthing module is meant to automate large parts of the Syncthing installation, service management and configuration editing. If provides defined types for Syncthing instances and various parts of the Syncthing configuration files.

Daemonization is currently achieved through a modified version of the Yeasoft btsync init.d script. Currently, there are a number of issues, mostly to do with the fact that Syncthing spawns new processes so often.

##Simple setup

What syncthing affects:

  • The syncthing installation directory (/usr/bin/syncthing by default)
  • Configuration file directory (/etc/syncthing by default)
  • The init.d script for Syncthing, if present (/etc/init.d/syncthing)

###Beginning with Syncthing

Install Syncthing, the service (init.d script) with default paths, no instances:

class { 'syncthing': }

###Syncthing instances

Instances can be declared directly in the Syncthing base class, or by defined types:

class { '::syncthing':
  instances => {
    'example' => {
      home_path   => '/home/synctester/example_instance',
      daemon_uid  => 'synctest', # Default: root
      daemon_gid  => 'synctester', # Default: root

      # Variables for standard parameters
      gui_tls     => true,
      gui_address => '0.0.0.0', # (Default)
      gui_port    => '8888', # Default: 8080

      # Override or set arbitrary options
      options     => {
        'listenAddress' => 'tcp4://0.0.0.0:19000',
        'startBrowser'  => 'false',
        'globalAnnounceServer'  => '', # disable defaults globalAnnounceServers
        'globalAnnounceServer'  => $announce_node, # add your private this way
        'globalAnnounceServer2' => $announce_node2, # add a second this way
      },
    }
  }
}

or:

::syncthing::instance { 'example':
  home_path => '/home/synctester/example_instance',
  ...
}

##Usage

###Classes and Defined Types

####Class: syncthing

Installs Syncthing and sets up the init.d service. The download URL is determined from the Syncthing Github releases page.

Parameters within syncthing:

#####bin

Override the assumed value for the Syncthing binary name. Defaults to syncthing.

#####binpath

Override the assumed value for the path to the Syncthing binary. Defaults to /usr/local/bin. This will actually by a symlink to the latest downloaded syncthing Binary.

#####store_path

Override the assumed path to store downloaded and extracted Syncthing releases in. Defaults to /usr/local/share/syncthing.

#####instancespath

Override the assumed value to the Syncthing instances configuration files. Defaults to /etc/syncthing.

#####package_version

Override the value used for the installation. Defaults to latest, in which case new releases will be downloaded when they are publishing on the Syncthing Github page. Note that Syncthing also has an auto-update mechanism.

#####manage_repo

Boolean to install syncthing APT repository. Defaults to true. Set it to false to control package installation using your internal / personal repository.

#####package_name

The name of the package that will be used for syncthing installation. Defaults to syncthing. Nice option for those we built their own packages.

#####instances

Hash that will be used to declare syncthing::instance resources.

#####folders

Hash that will be used to declare syncthing::folder resources.

#####devices

Hash that will be used to declare syncthing::device resources.

#####services_type

The module attempts to determine the service provider and, based on this, the service file type to install (systemd, initd), on its own, first using the service_provider fact, then based on the OS version. This may or may not work, depending on your setup. This can be used to override the automatically determined value. Pass in "systemd" or "initd".

#####create_home_path

Override the default value passed to syncthing::instancefor create_home_path.

#####daemon_uid

Override the default value passed to syncthing::instancefor daemon_uid.

#####daemon_gid

Override the default value passed to syncthing::instancefor daemon_gid.

#####daemon_umask

Override the default value passed to syncthing::instancefor daemon_umask.

#####daemon_nice

Override the default value passed to syncthing::instancefordaemon_nice.

#####daemon_debug

Override the default value passed to syncthing::instance for daemon_debug.

#####gui

Override the default value passed to syncthing::instancefor gui.

#####gui_tls

Override the default value passed to syncthing::instancefor gui_tls.

#####gui_address

Override the default value passed to syncthing::instancefor gui_address.

#####gui_port

Override the default value passed to syncthing::instance for gui_port.

#####gui_apikey

Override the default value passed to syncthing::instancefor gui_apikey.

#####gui_user

Override the default value passed to syncthing::instancefor gui_user.

#####gui_password

Override the default value passed to syncthing::instancefor gui_password.

See the notes on gui_password and gui_password_salt in the parameters for syncthing::instance for some important information regarding these two options.

#####gui_password_salt

Override the default value passed to syncthing::instancefor gui_password_salt.

#####gui_options

Override the default value passed to syncthing::instancefor gui_options.

#####instance_options

Override the default value passed to syncthing::instance for options.

#####device_compression

Override the default value passed to syncthing::device for compression .

#####device_introducer

Override the default value passed to syncthing::device for introducer.

#####device_options

Override the default value passed to syncthing::device for options.

####Defined Type: syncthing::instance

Creates an instance. Provides some parameters for common options and an options parameter to override or set arbitrary options.

  syncthing::instance { 'example':
    home_path  => '/etc/backups/example',
    daemon_uid => 'user',
    gui_tls    => true,
  }

Parameters within syncthing::instance:

#####ensure

Specify whether the instance configuration file is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'.

#####home_path

The home path for this instance. Where the configuration file and all certificates are stored. Mandatory parameter, will be created by Syncthing if not present.

#####create_home_path

Attempt to recursively create the passed home path prior to calling Syncthing to generate the configuration/certificates. This will be called in the context of the user identified by daemon_uid.

#####binary

Sets this instance to be a "binary instance", meaning it will download a Syncthing binary to the path specified by binary_path and use that binary instead of the package-provided binary.

#####binary_path

If binary is set to true, the Syncthing binary will be downloaded to this path.

#####binary_version

The Syncthing version to get when downloading a Syncthing binary. Defaults to latest.

Note that once a binary has been downloaded, this parameter becomes ineffective due to the fact that only the existance of a binary is checked, not the version.

This has the advantage that a binary instance, once created, can be upgraded independently from other instances, in constrast with "package instances", which all share the package binary and get upgraded/restarted when the package is upgraded.

#####daemon_uid

The UID to run the daemon for this instance as.

#####daemon_gid

The GID to run the daemon for this instance as.

#####daemon_umask The umask to run the daemon for this instance with.

#####daemon_nice

The niceness level for the instance daemon.

#####daemon_debug

The debug level for the instance daemon.

#####gui

Enable or disable the GUI. Valid values are true or false. Defaults to true.

#####gui_tls

Enable or disable SSL for the GUI. Valid values are true or false. Defaults to true.

#####gui_address

The address the GUI should listen at. Defaults to 0.0.0.0.

#####gui_port

Binding port for the GUI. Defaults to 8080.

#####gui_apikey

The API key for the GUI.

#####gui_user

Providing this and gui_password enables user authentication.

#####gui_password

Password to use to authenticate for the GUI.

If a salt string is provided through the gui_password_salt parameter (see below), then the value passed to gui_password is assumed to be the plaintext password and will be hashed with BCrypt prior to being inserted into the configuration file, using gui_password_salt as salt.

If gui_password_salt is not provided, the value passed to gui_password will be inserted as-is into the configuration file. This way, a BCrypt hash can be provided directly so as not to have plaintext passwords in the Puppet/Hiera files.

One method to hash a password with a random salt to obtain a hash for that password for direct insertion is (requires the bcrypt gem):

ruby -e "require 'bcrypt'; puts BCrypt::Engine.hash_secret('<<<PASSWORD>>>', BCrypt::Engine.generate_salt);"`

#####gui_password_salt

This must be set to a valid BCrypt salt such as $2a$10$vI8aWBnW3fID.ZQ4/zo1G. when providing plaintext passwords for hashing through this module.

One method to generate hashes is (requires the brypt gem):

ruby -e "require 'bcrypt'; salt = BCrypt::Engine.generate_salt; puts salt;"

Setting this parameter will result in the module attempting to generate a BCrypt-encrypted password. This requires the bcrypt gem to be installed on the puppetmaster.

#####gui_options

Set or override arbitrary GUI options. Created as XML nodes in the <gui></gui> element.

#####options

Set or override arbitrary options. Created as XML nodes in the <options></options> element.

####Defined Type: syncthing::device

Adds a <device> entry to the configuration file for the instance associated with the passed home path.

Direct declarations of this type are possible, but discouraged outside of programatical declarations due to its cumbersome options. Defining devices through the devices parameter of the syncthing::instance class is much more practical in any manual definition scenario.

  ::syncthing::device { 'laptop':
    home_path     => '/etc/backup/instance1',
    instance_name => 'instance1',
    id            => '523LMDC-KKQPKVU-JBPGYQU-IAGHP5B-TU38GN4-G7CEEHG-OOL32IR-YWQSFAX',
    compression   => true,
  }

Parameters within syncthing::device:

#####ensure

Specify whether the device configuration is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'.

#####home_path

The home path for the instance that should be told about this device. Mandatory parameter.

#####instance_name

The name of the instance that should be told about this device, as passed to the instances parameter on the syncthing class. Mandatory parameter.

#####id

The ID for the device in the usual form.

#####device_name

The name for the device, defaults to the resource name.

#####compression

Value to set for the compression option for this device. Can be true or false, defaults to false.

#####introducer

Value to set for the introducer option for this device. Can be true or false, defaults to false.

#####address

Set an address to use to contact the device. Defaults to dynamic.

#####options

Set or override arbitrary options. Created as XML nodes in the <device></device> element.

####Defined Type: syncthing::folder

Adds a <folder> entry to the configuration file for the instance associated with the passed home path.

Direct declarations of this type are possible, but discouraged outside of programatical declarations due to its cumbersome options. Defining folders through the folders parameter of the syncthing::instance class is much more practical in any manual definition scenario.

::syncthing::folder { 'laptop':
  home_path     => '/etc/backup/instance1',
  instance_name => 'instance1',
  id            => 'backupfolder1',
  path          => '/home/syncuser/myfiles',
  options       => {
    # Override options here
    # for trashcan versioning :
    'versioning'              => 'trashcan',
    'versioning_cleanoutDays' => '10',
    # for simple versioning
    'versioning'     => 'simple',
    'versioning_keep' => '5',
    # for staggered versioning
    'versioning'               => 'staggered',
    'versioning_maxAge'        => '864000',
    'versioning_cleanInterval' => '3600',
    #for external versioning
    'versioning'         => 'external',
    'versioning_command' => 'cmd',      
  },
  devices       => {
    '523LMDC-KKQPKVU-JBPGYQU-IAGHP5B-TU38GN4-G7CEEHG-OOL32IR-YWQSFAX' => 'present',
  }
}

Parameters within syncthing::folder:

#####ensure

Specify whether the device configuration is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'.

#####home_path

The home path for the instance that should be told about this folder. Mandatory parameter.

#####instance_name

The name of the instance that should be told about this device, as passed to the instances parameter on the syncthing class. Mandatory parameter.

#####id

The ID for the folder. Defaults to the name parameter.

#####path

Path to the folder that should be synced.

#####type

Value to set for the folder type. Can be readwrite or readonly, defaults to readwrite.

#####rescanIntervalS

Value to set for the rescanIntervalS option for this device. Defaults to 60.

#####ignorePerms

Value to set for the ignorePerms option for this device. Can be true or false, defaults to false.

#####autoNormalize

Value to set for the autoNormalize option for this device. Can be true or false, defaults to false.

#####options

Set or override arbitrary options. Created as XML nodes in the <folder></folder> element.

#####devices

A hash of devices to enable for the folder. Invididual device IDs can be specified and set to present or absent:

::syncthing::folder { 'laptop':
  ...
  devices => {
    '523LMDC-KKQPKVU-JBPGYQU-IAGHP5B-TU38GN4-G7CEEHG-OOL32IR-YWQSFAX' => 'present',
    'IAGHP5B-7IASKM-JBPGYQU-G7CEEHG-TU38GN4-TU38GN4-523LMDC-OOL32IR'  => 'absent',
  }
  ...
}

####Defined Type: syncthing::folder_device

Adds a <device> entry for the specified folder.

::syncthing::folder { 'backupfolder1_on_laptop':
  home_path     => '/etc/backup/instance1',
  instance_name => 'instance1',
  folder_id     => 'backupfolder1',
  device_id     => '523LMDC-KKQPKVU-JBPGYQU-IAGHP5B-TU38GN4-G7CEEHG-OOL32IR-YWQSFAX',
}

Parameters within syncthing::folder_device:

#####ensure

Specify whether the device entry is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'.

#####home_path

The home path for the instance that should be told about this device. Mandatory parameter.

#####instance_name

The name of the instance that should be told about this device, as passed to the instances parameter on the syncthing class. Mandatory parameter.

#####folder_id

The ID of the folder.

#####device_id

The ID of the device.

##Reference

###Classes

####Public Classes

####Private Classes

  • syncthing::install_package: Installs the Syncthing package.
  • syncthing::install_binary: Downloads a Syncthing binary.
  • syncthing::service: Installs the Syncthing init.d daemon.
  • syncthing::instance_service: Provides commands that emulate service start/stop/restart for binary Syncthing instances.
  • syncthing::params: Manages Syncthing parameters.

###Defined Types

####Public Defined Types

  • syncthing::instance
  • syncthing::device
  • syncthing::folder
  • syncthing::folder_device: Adds a known device to a folder.

##Limitations

###Operating system support

Currently, only Debian and Ubuntu are supported. Debian has been tested more extensively. Contributions adding support for further OSes are welcome!