Upgrade notes

The upgrade notes only describe necessary changes that you might need to make to your setup in order to use a new role release. Refer to the changelog for more details about what has changed.

Upgrade from v0.3.X to v0.4.X

The tinc__*_networks variables have been redesigned and now use YAML dictionaries instead of lists by default. This allows for easier modification of existing networks from the inventory. The role still supports YAML lists, but there might be some issues with duplicated configuration.

Conversion to the new format is pretty simple, but cannot be reliably performed by a script. If in your inventory you have entries similar to:

tinc__host_networks:

  - name: 'mesh0'
    port: '655'

  - name: 'mesh1'
    port: '656'

You can switch them to the new format by changing them to:

tinc__host_networks:

  'mesh0':
    name: 'mesh0'
    port: '655'

  'mesh1':
    name: 'mesh1'
    port: '656'

If you use the name parameter, the dictionary keys can be arbitrary, otherwise they will be used as the network names.

The autogenerated interface names have been changed, the role checks if the network name starts with tun or tap and uses the network name as the interface name, otherwise the network interfaces will have the form <device_type>-<network_name>, for example tun-mesh0. To prevent that, include the interface parameter in the network configuration.

The systemd units have been adjusted to start the Tinc networks after normal networking is configured (the network-online.target is reached). To review the dependency order of a given Tinc service, you can use the command:

systemd-analyze critical-chain tinc.service

You might need to reboot the host to see the correct order in all related services.

Upgrade from v0.2.X to v0.3.X

All inventory variables have been renamed so you might need to update your inventory. This script can come in handy to do this:

#!/bin/bash
## Upgrade inventory variables for migration from debops.tinc v0.2.X to v0.3.X.
## The script is idempotent.

git ls-files -z "$(git rev-parse --show-toplevel)" | xargs --null -I '{}' find '{}' -type f -print0 \
 | xargs --null sed --in-place --regexp-extended '
     s/tinc__connect_to_mesh0/tinc__reachable_peer_hosts_mesh0/g;
     s/tinc__compression([^_])/tinc__compression_mesh0\1/g;
     s/tinc__address_family([^_])/tinc__address_family_mesh0\1/g;
   '

The script is bundled with this role under docs/scripts/upgrade-from-v0.2.X-to-v0.3.X and can be invoked from there.