From 21e25137072312ab48b8793196b1620f5644a470 Mon Sep 17 00:00:00 2001 From: Julien Dessaux Date: Mon, 13 Feb 2023 20:41:43 +0100 Subject: Syncthing ansible role docs article --- content/docs/adyxax.org/backups/_index.md | 2 +- content/docs/adyxax.org/syncthing/_index.md | 2 +- content/docs/adyxax.org/syncthing/ansible-role.md | 90 +++++++++++++++++++++++ 3 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 content/docs/adyxax.org/syncthing/ansible-role.md diff --git a/content/docs/adyxax.org/backups/_index.md b/content/docs/adyxax.org/backups/_index.md index 6b0ea01..3d0ef13 100644 --- a/content/docs/adyxax.org/backups/_index.md +++ b/content/docs/adyxax.org/backups/_index.md @@ -5,7 +5,7 @@ description: what is backuped where and how I manage it ## Introduction -Backups are performed with the [borg](https://borgbackup.readthedocs.io/en/stable/) tool ("You will be assimilated" Star Trek vibes). It is simple, fast, storage efficient and fits my needs. I manage it thanks to a [custom made ansible role]({{< ref borg-ansible-role >}}). +Backups are performed with the [borg](https://borgbackup.readthedocs.io/en/stable/) tool ("You will be assimilated" Star Trek vibes). It is simple, fast, storage efficient and fits my needs. ## Inventory diff --git a/content/docs/adyxax.org/syncthing/_index.md b/content/docs/adyxax.org/syncthing/_index.md index bd07e23..79654f4 100644 --- a/content/docs/adyxax.org/syncthing/_index.md +++ b/content/docs/adyxax.org/syncthing/_index.md @@ -5,7 +5,7 @@ description: what is replicated where and how I manage it ## Introduction -I have been using [syncthing](https://syncthing.net/) for some time now. It is a tool to handle bidirectional synchronization of data. I manage it thanks to a [custom made ansible role]({{< ref "syncthing-ansible-role.md" >}}). +I have been using [syncthing](https://syncthing.net/) for some time now. It is a tool to handle bidirectional synchronization of data. ## Inventory diff --git a/content/docs/adyxax.org/syncthing/ansible-role.md b/content/docs/adyxax.org/syncthing/ansible-role.md new file mode 100644 index 0000000..1748261 --- /dev/null +++ b/content/docs/adyxax.org/syncthing/ansible-role.md @@ -0,0 +1,90 @@ +--- +title: Syncthing ansible role +description: The ansible role I wrote to manage my syncthing configurations +--- + +## Introduction + +I have been using [syncthing](https://syncthing.net/) for some time now. It is a tool to handle bidirectional synchronization of data. For example I use it on my personal infrastructure to synchronize: +- org-mode files between my workstation, laptop, a server and my phone (I need those everywhere!) +- pictures from my phone and my nas +- my music collection between my phone and my nas + +It is very useful, but by default the configuration leave a few things to be desired like telemetry or information leaks. If you want maximum privacy you need to disable the auto discovery and the default nat traversal features. + +Also provisioning is easy, but deleting or unsharing stuff would require to remember what is shared where and go manage each device individually from syncthing's web interface. I automated all that with ansible (well except for my phone which I cannot manage with ansible, its syncthing configuration will remain manual... for now). + +## Why another ansible role + +I wanted a role to install and configure syncthing for me and did not find an existing one that satisfied me. I had a few mandatory features in mind: +- the ability to configure a servers parameters in only one place to avoid repetition +- having a fact that retrieves the ID of a device +- the validation of host_vars which virtually no role in the wild ever does +- the ability to manage an additional inventory file for devices which ansible cannot manage (like my phone) + +## Dependencies + +This role relies on `doas` being installed and configured so that your ansible user can run the syncthing cli as the syncthing user. + +Here is an example of a `doas.conf` that works for the ansible user: +```yaml +permit nopass ansible as syncthing +``` + +## Role variables + +There is a single variable to specify in the `host_vars` of your hosts: `syncthing`. This is a dict that can contain the following keys: +- address: optional string to specify how to connect to the server, must match the format `tcp://` or `tcp://`. Default value is *dynamic* which means a passive host. +- shared: a mandatory dict describing the directories this host shares, which can contain the following keys: + - name: a mandatory string to name the share in the configuration. It must match on all devices that share this folder. + - path: the path of the folder on the device. This can differ on each device sharing this data. + - peers: a list a strings. Each item should be either the `ansible_hostname` of another device, or a hostname from the `syncthing_data.yaml` file + +Configuring a host through its `host_vars` looks like this: +```yaml +syncthing: + address: tcp://lore.adyxax.org + shared: + - name: org-mode + path: /var/syncthing/org-mode + peers: + - hero + - light + - lumapps + - Pixel 3a +``` + +## The optional syncthing_data.yaml file + +To be found by the `action_plugins`, this file should be in the same folder as your playbook. It shares the same format as the `host_vars` but with additional keys for the hostname and its ID. + +The data file for non ansible devices looks like this: +```yaml +- name: Pixel 3a + id: ABCDEFG-HIJKLMN-OPQRSTU-VWXYZ01-2345678-90ABCDE-FGHIJKL-MNOPQRS + shared: + - name: Music + path: /storage/emulated/0/Music + peers: + - phoenix + - name: Photos + path: /storage/emulated/0/DCIM/Camera + peers: + - phoenix + - name: org-mode + path: /storage/emulated/0/Org + peers: + - lore.adyxax.org +``` + +## Example playbook + +```yaml +- hosts: all + roles: + - { role: syncthing, tags: [ 'syncthing' ], when: "syncthing is defined" } +``` + +## Conclusion + +You can find the role [here](https://git.adyxax.org/adyxax/syncthing-ansible-role/about/). If I left something unclear or some piece seems to be missing, do not hesitate to [contact me]({{< ref "about-me.md" >}}). -- cgit v1.2.3