Tinc

This role installs tinc in a star or a ring topology.

The nodes listed in the group [tinc_nodes] is a full list of nodes to apply/install the role.

The nodes part of [tinc_spine_nodes] are the "core" nodes, where all the nodes connect.

The nodes in [tinc_leaf_nodes] connect only to the spine nodes. Devices behind a NAT would be an example of such.

If all the [tinc_nodes] are part of the [tinc_spine_nodes], you have a more "ringy" topology. If you have one node in [tinc_spine_nodes], you have a more "starry" topology.

Requirements

Ubuntu 18.04 / CentOS 7 (or above) / OpenWRT
On CentOS and above, EPEL repo needs to be configured in advance.

To do so, you can run the following:

yum install epel-release || dnf install epel-release
yum update || dnf update

Role Variables

tinc_key_size: The size of the generated keys (Default: 4096)
tinc_address_family can be ipv4/ipv6/any (or undefined)
tinc_mode can be router, switch, or hub. (See https://www.tinc-vpn.org/documentation/tinc.conf.5). (Default: router)
tinc_netname: The tinc network name
tinc_vpn_ip: The ip to assign to a single VPN endpoint. Use host vars to set it.
tinc_vpn_cidr: The cidr used in tinc network (Default: /24, or force /32 in router mode).
tinc_vpn_interface: The device for tinc to use, in case there are multiple tun devices (Default: tun0)
tinc_control_plane_bind_ip: The ip for tincd service to bind to (Default: ansible_default_ipv4.address }} )

Inventory must set tinc_control_plane_bind_ip (for core) and/or tinc_vpn_ip (for core and edge nodes). Please have a look in the task files.

Examples

Router mode, ring topology

(Short) Inventory:

[tinc_nodes:children]
tinc_spine_nodes
tinc_leaf_nodes

[tinc_spine_nodes]
node1 tinc_vpn_ip=10.10.0.11
node2 tinc_vpn_ip=10.10.0.12
node3 tinc_vpn_ip=10.10.0.13

[tinc_leaf_nodes]
node1
node2
node3

Router mode, star topology

(Detailed) Inventory:

[tinc_nodes]
node1
node2
node3

[tinc_spine_nodes]
node1

[tinc_leaf_nodes]
node1
node2
node3

Group vars for tinc_nodes:

tinc_netname: mynetname
tinc_vpn_interface: tun0

Host vars for spine node, node1:

tinc_control_plane_bind_ip: "{{ ansible_eth0.ipv4.address | default(ansible_default_ipv4.address) }}"
tinc_vpn_ip: 10.10.0.10

Host vars for edge node, node2:

tinc_vpn_ip: 10.10.0.11

Host vars for edge node, node3:

tinc_vpn_ip: 10.10.0.12

Dependencies

None

Example Playbook

See https://raw.githubusercontent.com/evrardjp/ansible-tinc/master/molecule/default/converge.yml

Don't forget to set the necessary variables in your inventory (see above).

Testing

Tests are based on Ansible Molecule framework which:

checks role syntax
starts several containers with different OS (only for tests. We don't mix Tinc versions in production)
applies this role to each container
runs idempotency tests (make sure that second run will not make unexpected changes)
verifies that each prepared node able to ping other nodes over VPN

Tests run in a github actions on PR and daily. Additionally you may execute them on local machine.

Dependencies you need to have installed for running the tests:

Ansible
Docker
Molecule with molecule-docker driver, or tox.

Run tests manually, using molecule directly

You can existing tests for star and ring topologies:

cd ansible-tinc
molecule test # this run default tests for Ring scenario
molecule test -s star

The 'molecule test' command execute full scenario: 'create', 'converge', 'check idempotency', 'verify' and 'destroy' steps. Often you don't want to have container immediately destroyed and need access it for debug. For this might be useful replace 'molecule test' with:

molecule converge # this create containers and apply the role
molecule verify # run tests described in molecule/default/verify.yml

# after both steps you have live Docker containers
# you can access them with usual commands 'docker ps', 'docker exec' etc

molecule destroy

Run tests manually, using tox

tox is a test runner for python. It will install all the necessary python dependencies (ansible, molecule[docker]) in a virtual environment.

To run a test:

tox -e ansible-<version>-<tinc scenario>

See supported values for version in tox.ini. Current testable scenarios for tinc are ring, or star. Positional arguments will be passed to the molecule test command.

For example, to run a test for ansible-2.9, with the ring topology and prevent molecule to destroy the environment:

tox -e ansible-2.9-ring -- --destroy=never

How to test role with new OS

add new image to molecule/default/molecule.yml and molecule/star/molecule.yml following existing examples. Files are similar except the variables scenario.name and groups. Next hightlights could be hepful:

code privileged: true with command: /sbin/init enable systemd if container support it. Please don't forget that privileged containers in your system could be a risk.
Docker images lack some standard software, so molecule/default/converge.yml take care about installing necessary dependencies
according with ansible/molecule#959 Docker doesn't allow modify /etc/hosts in a container. To workaround this we skipping one step with molecule-notest tag in tasks/tinc_configure.yml and modifying /etc/hosts during container creation - following the corresponding directives in molecule/default/molecule.yml

License

Apache2

Author Information

Jean-Philippe Evrard

evrardjp / ansible-tinc