..
 # SPDX-FileCopyrightText: Copyright (c) 2025, Linaro Limited.
 #
 # SPDX-License-Identifier: MIT

.. _mender_system_update_label:

********************
Mender System Update
********************

Once the Mender server is running and the Device Under Test
(DUT) is provisioned, the next step is to deliver your
update payloads to the server for performing system update on DUT.

Requirements:

  * :ref:`Mender artifact <build_with_mender_support_label>`
  * :ref:`Artifacts are uploaded <artifact_upload_label>`
  * :ref:`Running Mender server <setup_mender_server_label>`
  * :ref:`Device Under Test (DUT) is provisioned <dut_provisioning_label>`

This section covers two different scenarios.

 * Signed artifacts for secure deployments.
 * Unsigned artifact to demonstrate failure deployments.

.. _copy_artifact_key_label:

* **Setup** :

  Copy artifact key from the host machine to the DUT.

  .. code-block:: console

    scp -o "StrictHostKeyChecking no" ${HOST_MACHINE_USER}@${MENDER_SERVER_IP}:${MENDER_SERVER_DIR}/keys/artifact-verify-key.pem ${MENDER_DUT_TEST_DIR}

  Install the artifact key to validate the incoming mender artifacts which are deployed from the Mender server.

  .. code-block:: console

    cp ./artifact-verify-key.pem /etc/mender

* **Deploying Updates** :

  To trigger an **unsigned system update**, we deploy an unsigned artifact.

  .. code-block:: console

    create_artifact_deployment unsigned-image
    check_for_unsigned_update

  Expected outcome:

    * The device rejects the artifact due to missing or invalid signature.
    * This also validates proper enforcement of security policies.

  To trigger a **signed system update**, we deploy a signed artifact.

  .. code-block:: console

    create_artifact_deployment release-2
    wait_for_signed_update

  Expected outcome:

    * The artifact passes signature validation.
    * The Mender client downloads and installs the update.
    * The device reboots upon successful deployment.

  .. note::
    Please allow up to 30 minutes for the DUT to automatically reboot after running these commands.

.. _final_verification_label:

* **Final Verification** :

  Final check to confirm that the **signed system update** was successfully completed and
  acknowledged by DUT to the Mender server.

  This step ensures the DUT, is able to **securely communicate** with
  the correct Mender server that was used during the provisioning and deployment steps.

  Once the DUT has rebooted after applying the mender system update login and switch to root user:

  .. code-block:: console

    sudo su -

  These are the required environment variables, refer :ref:`here <mender-env-vars-section>` for more details.

    * `MENDER_DUT_TEST_DIR`
    * `MENDER_SERVER_HTTPS_PORT`
    * `MENDER_SERVER_HTTP_PORT`
    * `MENDER_SERVER_IP`
    * `MENDER_SERVER_NAME`

  .. code-block:: console

    cd  ${MENDER_DUT_TEST_DIR}
    cp  ${MENDER_DUT_TEST_DIR}/artifact-verify-key.pem /etc/mender
    cp  ${MENDER_DUT_TEST_DIR}/mender.crt /etc/mender
    chmod 644 /etc/mender/mender.crt

  .. note::
    This step is required for ``corstone1000-fvp`` machine to prevent unexpected shutdown during the validation of mender system update.

    .. code-block:: console

      sudo ip link set eth0 down

  Setup environment variables and load helper functions used for final validation.

  .. code-block:: console

    source ./mender_test_helper.sh

  Restart Mender authentication service to reinitialize secure communication.

  .. code-block:: console

    systemctl restart mender-authd

  .. note::
    This step is required for ``corstone1000-fvp`` machine to prevent unexpected shutdown during the validation of mender system update.

    .. code-block:: console

      sudo ip link set eth0 up

  Finally, check to confirm the signed update was applied successfully.

  .. code-block:: console

    check_for_signed_update