Initial commit

This commit is contained in:
Rafael Bodill 2018-11-28 21:22:58 +02:00
commit 8b7b85b8f1
5 changed files with 700 additions and 0 deletions

111
README.md Normal file
View File

@ -0,0 +1,111 @@
# Ansible Modules for Syncthing
Collection of modules for [Syncthing](https://syncthing.net) management.
## Install
Copy the `./library` directory to your Ansible project and ensure your
`ansible.cfg` has this line:
```ini
[defaults]
library = ./library
```
Please note this module was test on:
* Ubuntu 16.04 with Syncthing v0.14.52
Please report successful usage on other platforms/versions.
## Usage
See [example playbooks](./playbooks) for robust feature usage:
* [install_syncthing.yml] - Install Syncthing on Ubuntu (with systemd)
* [manage.yml] - Ensure Syncthing devices and folders across devices
[install_syncthing.yml]: http://
[manage.yml]: http://
## Modules
### Module: `syncthing_device`
Manage synced devices. Add, remove or pause devices using ID.
Examples:
```yml
# Add a device to share with, use auto-configuration
- name: Add syncthing device
syncthing_device:
id: ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
name: my-device-name
# Add a device to share with
- name: Add syncthing device
syncthing_device:
id: ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
name: my-other-device
host: http://127.0.0.1:8384
api_key: aBCDeFG1h2IJKlmNopq3rs45uvwxy6Zz
# Pause an existing device
- name: Pause syncthing device
syncthing_device:
id: ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
name: my-device-name
state: pause
# Remove an existing device
- name: Remove syncthing device
syncthing_device:
id: ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
name: my-device-name
state: absent
```
### Module: `syncthing_folder`
Manage synced devices. Add, remove or pause devices using ID.
Examples:
```yml
# Add a folder to synchronize with another device, use auto-configuration
- name: Add syncthing folder
syncthing_folder:
path: ~/Documents
id: documents
devices:
- ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
# Add a folder to share with several devices, specify host and api key
- name: Add syncthing folder
syncthing_folder:
path: ~/Downloads
id: downloads
devices:
- ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG-ABCDEFG
- GFEDCBA-GFEDCBA-GFEDCBA-GFEDCBA-GFEDCBA-GFEDCBA-GFEDCBA-GFEDCBA
host: http://127.0.0.1:8384
api_key: aBCDeFG1h2IJKlmNopq3rs45uvwxy6Zz
# Pause an existing folder
- name: Pause syncthing folder
syncthing_folder:
id: downloads
state: pause
# Remove an existing folder
- name: Remove syncthing folder
syncthing_folder:
id: downloads
state: absent
```
## License
Copyright: (c) 2018, Rafael Bodill `<justrafi at g>`
GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

View File

@ -0,0 +1,232 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Rafael Bodill <justrafi at google mail>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'
}
DOCUMENTATION = '''
---
module: syncthing_device
short_description: Manage Syncthing devices
version_added: "2.7"
description:
- "This is my longer description explaining my sample module"
options:
id:
description:
- This is the unique id of this new device
required: true
name:
description:
- The name for this new device
required: false
host:
description:
- Host to connect to, including port
default: http://127.0.0.1:8384
api_key:
description:
- API key to use for authentication with host.
If not provided, will try to auto-configure from filesystem.
required: false
timeout:
description:
- The socket level timeout in seconds
default: 30
state:
description:
- Use present/absent to ensure device is added, or not.
default: present
choices: ['absent', 'present', 'paused']
author:
- Rafael Bodill (@rafi)
'''
EXAMPLES = '''
# Add a device to share with
- name: Add syncthing device
syncthing_device:
id: 1234-1234-1234-1234
name: my-server-name
'''
RETURN = '''
response:
description: The API response, in-case of an error.
type: dict
'''
import os
import json
import platform
from xml.etree.ElementTree import parse
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url, url_argument_spec
SYNCTHING_API_URI = "/rest/system/config"
if platform.system() == 'Windows':
DEFAULT_ST_CONFIG_LOCATION = '%localappdata%/Syncthing/config.xml'
elif platform.system() == 'Darwin':
DEFAULT_ST_CONFIG_LOCATION = '$HOME/Library/Application Support/Syncthing/config.xml'
else:
DEFAULT_ST_CONFIG_LOCATION = '$HOME/.config/syncthing/config.xml'
def make_headers(host, api_key):
url = '{}{}'.format(host, SYNCTHING_API_URI)
headers = {'X-Api-Key': api_key }
return url, headers
def get_key_from_filesystem(module):
try:
stconfigfile = os.path.expandvars(DEFAULT_ST_CONFIG_LOCATION)
stconfig = parse(stconfigfile)
root = stconfig.getroot()
gui = root.find('gui')
api_key = gui.find('apikey').text
return api_key
except Exception:
module.fail_json(msg="Auto-configuration failed. Please specify"
"the API key manually.")
# Fetch Syncthing configuration
def get_config(module):
url, headers = make_headers(module.params['host'], module.params['api_key'])
resp, info = fetch_url(
module, url, data=None, headers=headers,
method='GET', timeout=module.params['timeout'])
if not info or info['status'] != 200:
result['response'] = info
module.fail_json(msg='Error occured while calling host', **result)
try:
content = resp.read()
except AttributeError:
result['content'] = info.pop('body', '')
result['response'] = str(info)
module.fail_json(msg='Error occured while reading response', **result)
return json.loads(content)
# Post the new configuration to Syncthing API
def post_config(module, config, result):
url, headers = make_headers(module.params['host'], module.params['api_key'])
headers['Content-Type'] = 'application/json'
result['msg'] = config
resp, info = fetch_url(
module, url, data=json.dumps(config), headers=headers,
method='POST', timeout=module.params['timeout'])
if not info or info['status'] != 200:
result['response'] = str(info)
module.fail_json(msg='Error occured while posting new config', **result)
# Returns an object of a new device
def create_device(params):
device = {
'addresses': [
'dynamic'
],
'allowedNetworks': [],
'autoAcceptFolders': False,
'certName': '',
'compression': 'metadata',
'deviceID': params['id'],
'ignoredFolders': [],
'introducedBy': '',
'introducer': False,
'maxRecvKbps': 0,
'maxSendKbps': 0,
'name': params['name'],
'paused': True if params['state'] == 'paused' else False,
'pendingFolders': [],
'skipIntroductionRemovals': False
}
return device
def run_module():
# module arguments
module_args = url_argument_spec()
module_args.update(dict(
id=dict(type='str', required=True),
name=dict(type='str', required=False),
host=dict(type='str', default='http://127.0.0.1:8384'),
api_key=dict(type='str', required=False, no_log=True),
timeout=dict(type='int', default=30),
state=dict(type='str', default='present',
choices=['absent', 'present', 'pause']),
))
# seed the result dict in the object
result = {
"changed": False,
"response": None,
}
# the AnsibleModule object will be our abstraction working with Ansible
module = AnsibleModule(
argument_spec=module_args,
supports_check_mode=True
)
if module.params['state'] != 'absent' and not module.params['name']:
module.fail_json(msg='You must provide a name when creating', **result)
if module.check_mode:
return result
# Auto-configuration: Try to fetch API key from filesystem
if not module.params['api_key']:
module.params['api_key'] = get_key_from_filesystem(module)
config = get_config(module)
if module.params['state'] == 'absent':
# Remove device from list, if found
for idx, device in enumerate(config['devices']):
if device['deviceID'] == module.params['id']:
config['devices'].pop(idx)
result['changed'] = True
break
else:
# Bail-out if device is already added
for device in config['devices']:
if device['deviceID'] == module.params['id']:
want_pause = module.params['state'] == 'pause'
if (want_pause and device['paused']) or \
(not want_pause and not device['paused']):
module.exit_json(**result)
else:
device['paused'] = want_pause
result['changed'] = True
break
# Append the new device into configuration
if not result['changed']:
device = create_device(module.params)
config['devices'].append(device)
result['changed'] = True
if result['changed']:
post_config(module, config, result)
module.exit_json(**result)
def main():
run_module()
if __name__ == '__main__':
main()

View File

@ -0,0 +1,268 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Rafael Bodill <justrafi at gmail>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'
}
DOCUMENTATION = '''
---
module: syncthing_folder
short_description: Manage Syncthing folders
version_added: "2.7"
description:
- "This is my longer description explaining my sample module"
options:
id:
description:
- This is the unique id of this new folder
required: true
label:
description:
- The label for this new folder
required: false
path:
description:
- This is the path of the folder
required: false
devices:
description:
- List of devices to share folder with
required: false
host:
description:
- Host to connect to, including port
default: http://127.0.0.1:8384
api_key:
description:
- API key to use for authentication with host.
If not provided, will try to auto-configure from filesystem.
required: false
timeout:
description:
- The socket level timeout in seconds
default: 30
state:
description:
- Use present/absent to ensure folder is shared, or not.
default: present
choices: ['absent', 'present', 'paused']
author:
- Rafael Bodill (@rafi)
'''
EXAMPLES = '''
# Add a folder to synchronize with another device
- name: Add syncthing folder
syncthing_folder:
id: box
path: ~/box
devices:
- 1234-1234-1234-1234
'''
RETURN = '''
response:
description: The API response, in-case of an error.
type: dict
'''
import os
import json
import platform
from xml.etree.ElementTree import parse
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url, url_argument_spec
SYNCTHING_API_URI = "/rest/system/config"
if platform.system() == 'Windows':
DEFAULT_ST_CONFIG_LOCATION = '%localappdata%/Syncthing/config.xml'
elif platform.system() == 'Darwin':
DEFAULT_ST_CONFIG_LOCATION = '$HOME/Library/Application Support/Syncthing/config.xml'
else:
DEFAULT_ST_CONFIG_LOCATION = '$HOME/.config/syncthing/config.xml'
def make_headers(host, api_key):
url = '{}{}'.format(host, SYNCTHING_API_URI)
headers = {'X-Api-Key': api_key }
return url, headers
def get_key_from_filesystem(module):
try:
stconfigfile = os.path.expandvars(DEFAULT_ST_CONFIG_LOCATION)
stconfig = parse(stconfigfile)
root = stconfig.getroot()
gui = root.find('gui')
api_key = gui.find('apikey').text
return api_key
except Exception:
module.fail_json(msg="Auto-configuration failed. Please specify"
"the API key manually.")
# Fetch Syncthing configuration
def get_config(module):
url, headers = make_headers(module.params['host'], module.params['api_key'])
resp, info = fetch_url(
module, url, data=None, headers=headers,
method='GET', timeout=module.params['timeout'])
if not info or info['status'] != 200:
result['response'] = info
module.fail_json(msg='Error occured while calling host', **result)
try:
content = resp.read()
except AttributeError:
result['content'] = info.pop('body', '')
result['response'] = str(info)
module.fail_json(msg='Error occured while reading response', **result)
return json.loads(content)
# Post the new configuration to Syncthing API
def post_config(module, config, result):
url, headers = make_headers(module.params['host'], module.params['api_key'])
headers['Content-Type'] = 'application/json'
result['msg'] = config
resp, info = fetch_url(
module, url, data=json.dumps(config), headers=headers,
method='POST', timeout=module.params['timeout'])
if not info or info['status'] != 200:
result['response'] = str(info)
module.fail_json(msg='Error occured while posting new config', **result)
# Returns an object of a new folder
def create_folder(params):
folder = {
'autoNormalize': True,
'copiers': 0,
'devices': [],
'disableSparseFiles': False,
'disableTempIndexes': False,
'filesystemType': 'basic',
'fsWatcherDelayS': 10,
'fsWatcherEnabled': True,
'hashers': 0,
'id': params['id'],
'ignoreDelete': False,
'ignorePerms': False,
'label': params['label'] if params['label'] else params['id'],
'markerName': '.stfolder',
'maxConflicts': -1,
'minDiskFree': {
'unit': '%',
'value': 1
},
'order': 'random',
'path': params['path'],
'paused': True if params['state'] == 'paused' else False,
'pullerMaxPendingKiB': 0,
'pullerPauseS': 0,
'rescanIntervalS': 3600,
'scanProgressIntervalS': 0,
'type': 'sendreceive',
'useLargeBlocks': False,
'versioning': {
'params': {},
'type': ''
},
'weakHashThresholdPct': 25
}
# Collect wanted devices to share folder with
for device_id in params['devices']:
folder['devices'].append({
'deviceID': device_id,
'introducedBy': '',
})
return folder
def run_module():
# module arguments
module_args = url_argument_spec()
module_args.update(dict(
id=dict(type='str', required=True),
label=dict(type='str', required=False),
path=dict(type='path', required=False),
devices=dict(type='list', required=False, default=False),
host=dict(type='str', default='http://127.0.0.1:8384'),
api_key=dict(type='str', required=False, no_log=True),
timeout=dict(type='int', default=30),
state=dict(type='str', default='present',
choices=['absent', 'present', 'pause']),
))
# seed the result dict in the object
result = {
"changed": False,
"response": None,
}
# the AnsibleModule object will be our abstraction working with Ansible
module = AnsibleModule(
argument_spec=module_args,
supports_check_mode=True
)
if module.params['state'] != 'absent' and not module.params['path']:
module.fail_json(msg='You must provide a path when creating', **result)
if module.check_mode:
return result
# Auto-configuration: Try to fetch API key from filesystem
if not module.params['api_key']:
module.params['api_key'] = get_key_from_filesystem(module)
config = get_config(module)
if module.params['state'] == 'absent':
# Remove folder from list, if found
for idx, folder in enumerate(config['folders']):
if folder['id'] == module.params['id']:
config['folders'].pop(idx)
result['changed'] = True
break
else:
# Bail-out if folder is already added
for folder in config['folders']:
if folder['id'] == module.params['id']:
want_pause = module.params['state'] == 'pause'
if (want_pause and folder['paused']) or \
(not want_pause and not folder['paused']):
module.exit_json(**result)
else:
folder['paused'] = want_pause
result['changed'] = True
break
# Append the new folder into configuration
if not result['changed']:
folder = create_folder(module.params)
config['folders'].append(folder)
result['changed'] = True
if result['changed']:
post_config(module, config, result)
module.exit_json(**result)
def main():
run_module()
if __name__ == '__main__':
main()

View File

@ -0,0 +1,28 @@
---
- hosts: all
vars:
syncthing_apt_key_id: "D26E6ED000654A3E"
syncthing_apt_key_url: "https://syncthing.net/release-key.txt"
syncthing_apt_repository: "deb http://apt.syncthing.net/ syncthing release"
syncthing_service_user: root
tasks:
- name: Add Syncthing repository key
apt_key:
id: "{{ syncthing_apt_key_id }}"
url: "{{ syncthing_apt_key_url }}"
keyring: "/etc/apt/trusted.gpg.d/syncthing.gpg"
- name: Add Syncthing repository
apt_repository:
repo: "{{ syncthing_apt_repository }}"
- name: Install Syncthing package
apt: name=syncthing
- name: Enable and ensure Syncthing is started
systemd:
name: syncthing@{{ syncthing_service_user }}
enabled: yes
state: started

61
playbooks/manage.yml Normal file
View File

@ -0,0 +1,61 @@
---
- hosts: syncthing
vars:
syncthing_api: 127.0.0.1:8384
syncthing_service_user: deploy
syncthing_folders:
- path: /srv/data/media
id: media
group: staff
mode: "0775"
- id: default
state: absent
tasks:
- name: Ensure directories state
file:
path: '{{ item.path }}'
state: '{{ "absent" if item.state|d("") == "absent" else "directory" }}'
owner: '{{ syncthing_service_user }}'
group: '{{ item.group | default("root") }}'
mode: '{{ item.mode | default("0755") }}'
with_items: "{{ syncthing_folders }}"
- name: Get system config to grab unique id of each machine
uri:
url: "http://{{ syncthing_api }}/rest/system/config"
return_content: no
status_code: [ 200, 403 ]
register: syncthing_config_raw
check_mode: no
- name: Set each machine with a unique id
set_fact:
syncthing_id: "{{ syncthing_config_raw.x_syncthing_id }}"
syncthing_ids: []
- name: Prepare a list of all machine ids
set_fact:
syncthing_ids: "{{ syncthing_ids + [ hostvars[item].syncthing_id ] }}"
when: inventory_hostname != item
with_items: "{{ groups['syncthing'] }}"
- name: Ensure syncthing devices
syncthing_device:
id: "{{ hostvars[item].syncthing_id }}"
name: "{{ item }}"
become: yes
become_user: "{{ syncthing_service_user }}"
when: inventory_hostname != item
with_items: "{{ groups['syncthing'] }}"
- name: Ensure syncthing folders
syncthing_folder:
path: "{{ item.path | default(omit) }}"
id: "{{ item.id }}"
devices: "{{ syncthing_ids }}"
state: "{{ item.state | default('present') }}"
become: yes
become_user: "{{ syncthing_service_user }}"
with_items: "{{ syncthing_folders }}"