Tinc

This role installs Tinc in a star or ring setup.

The nodes listed in the group [tinc_nodes] are the complete set of nodes for applying/installing the role.

The nodes in [tinc_spine_nodes] are the main nodes that all other nodes connect to.

The nodes in [tinc_leaf_nodes] connect only to the spine nodes. An example of this would be devices behind a NAT.

If all the [tinc_nodes] are also in the [tinc_spine_nodes], you have a more "ring" setup. If there's only one node in [tinc_spine_nodes], you have a more "star" setup.

Requirements

• Ubuntu 18.04 / CentOS 7 (or higher) / OpenWRT
• For CentOS and higher, the EPEL repository must be set up first.

You can do this with the following commands:

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

Role Variables

• tinc_key_size: Size of the generated keys (Default: 4096)
• tinc_address_family can be ipv4/ipv6/any (or left 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 assigned to a single VPN endpoint. Set this in host variables.
• tinc_vpn_cidr: The CIDR used in the Tinc network (Default: /24, or force /32 in router mode).
• tinc_vpn_interface: The device Tinc will use if there are multiple tun devices (Default: tun0)
• tinc_control_plane_bind_ip: The IP for Tinc service to bind to (Default: ansible_default_ipv4.address })

The inventory must define tinc_control_plane_bind_ip (for core nodes) and/or tinc_vpn_ip (for core and edge nodes). Check the task files for more details.

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 use the Ansible Molecule framework to:

• Check the role syntax
• Start several containers with different operating systems (only for tests; we don’t mix Tinc versions in production)
• Apply the role to each container
• Run tests to ensure that running the role multiple times doesn’t change anything unexpectedly
• Verify that each prepared node can ping other nodes over VPN

Tests are run in GitHub Actions on pull requests and daily. You can also run them on your local machine.

Requirements to run the tests:

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

Run Tests Manually with Molecule

You can run existing tests for star and ring topologies:

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

The molecule test command runs all steps: 'create', 'converge', 'check idempotency', 'verify', and 'destroy'. If you want to keep the containers for debugging, replace molecule test with:

molecule converge # this creates containers and applies the role
molecule verify # runs tests defined in molecule/default/verify.yml

# After both steps, you can access the live Docker containers
# using the usual commands 'docker ps', 'docker exec', etc.

molecule destroy

Run Tests Manually with Tox

Tox is a test runner for Python. It installs all the required Python dependencies (Ansible, molecule[docker]) in a virtual environment.

To run a test:

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

Supported values for version are 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 from destroying the environment:

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

How to Test Role with New Operating System

Add a new image to molecule/default/molecule.yml and molecule/star/molecule.yml following existing examples. The files are quite similar, except for the variables scenario.name and groups. Here are a few helpful highlights:

• Use privileged: true with command: /sbin/init to enable systemd if the container supports it. Be cautious, as privileged containers can pose risks.
• Docker images may lack standard software, so molecule/default/converge.yml manages installing necessary dependencies.
• According to https://github.com/ansible-community/molecule/issues/959, Docker does not allow modifications to /etc/hosts in a container. As a workaround, we skip one step using the molecule-notest tag in tasks/tinc_configure.yml and modify /etc/hosts during container creation, following the directives in molecule/default/molecule.yml.

License

Apache2

Author Information

Jean-Philippe Evrard