.. _tinc__ref_upgrade_nodes:

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.

.. _tinc__ref_upgrade_nodes_v0.4:

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:

.. code-block:: yaml

   tinc__host_networks:

     - name: 'mesh0'
       port: '655'

     - name: 'mesh1'
       port: '656'

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

.. code-block:: yaml

   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 :command:`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:

.. code-block:: console

   systemd-analyze critical-chain tinc.service

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


.. _tinc__ref_upgrade_nodes_v0.3:

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:

.. literalinclude:: scripts/upgrade-from-v0.2.X-to-v0.3.X
   :language: shell

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