Firmware Update
===============

Official Linux Automation GmbH firmware updates for the LXA TAC are distributed
via two release channels:

`Stable`

    The `Stable` channel is updated roughly four times a year with RAUC
    bundles and images that were manually tested and reviewed for production
    readiness.

    The `Release` channel is the recommended release channel for the majority
    of TACs.

`Testing`

    Firmware images and RAUC bundles in the `Testing` channel are automatically
    generated from the ``main`` branch of the ``meta-lxatac`` repository,
    automatically tested on a LXA TAC in our CI infrastructure and, on success,
    automatically published.

    Use this release channel on some of your TACs if you are interested in the
    most recent development.

You can also build your own firmware images and bundles to e.g. automatically
deploy configuration matching you lab setup. See the ``README`` in the
`meta-lxatac repository on GitHub <https://github.com/linux-automation/meta-lxatac>`_
for more information about the build process and how to customize it.

Update Notifications
--------------------

If polling for updates is enabled you will be notified about available updates
via the web interface and the LCD on the TAC.

.. note:: You can enable update polling in the setup wizard.
          Use the buttons on your device to enter the setup wizard.


.. figure:: _static/update_notification_lcd.png
  :width: 240
  :alt: Screenshot of the LCD on the device showing the following text: "Welcome to your TAC! Please continue at http://<url> or http://<ip>."
  :align: center

  The content of the local display informing you about an update.

Migrating Files
---------------

Updates on the TAC are installed using an A/B mechanism.
This means there are two slots for root filesystems,
the one that is currently booted and another one into which
the next root filesystem will be installed.

Files from the running root filesystem,
that should still be available after an update,
need to be copied during the installation of an update.
Which files to migrate is specified using a script in the update bundle.
The default migrations in these bundles should cover most use-cases.

A list of files in ``/etc/rauc/migrate.d`` can be used to specify additional
files to migrate during an upgrade:

.. code-block:: bash

    root@lxatac-00002:~ cat /etc/rauc/migrate.d/git_config.conf
    /etc/gitconfig
    /home/root/.gitconfig

.. note:: Changes to config files that are not migrated will be lost without notification!

Changing Channels
-----------------

To install a RAUC bundle from a different release channel than the one you are
currently using you need to configure RAUC to trust bundles from said channel.

This can be done via the ``rauc-enable-cert`` script on the TAC,
which creates the required symbolic links and hashed certificate indices:

.. code-block:: bash

    root@lxatac-00002:~ ls /etc/rauc/certificates-available/
    devel.cert.pem    stable.cert.pem    testing.cert.pem
    root@lxatac-00002:~ rauc-enable-cert
    Usage: rauc-enable-cert cert.pem
    Available certificates:
    devel.cert.pem testing.cert.pem stable.cert.pem

    root@lxatac-00002:~ rauc-enable-cert testing.cert.pem

Once you've marked bundles from a specific channel as trusted you can install
them via:

.. code-block:: bash

    root@lxatac-00002:~ rauc install https://downloads.linux-automation.com/…