diff --git a/source/reference-manual/ota/aktualizr-lite.rst b/source/reference-manual/ota/aktualizr-lite.rst index 7be3f9f7..c783b902 100644 --- a/source/reference-manual/ota/aktualizr-lite.rst +++ b/source/reference-manual/ota/aktualizr-lite.rst @@ -41,54 +41,7 @@ To view the daemon logs: ``sudo journalctl -f -u aktualizr-lite`` -Manual Mode ------------ - -Disabling daemon mode is not recommended nor supported, but running ``aktualizr-lite`` manually can be useful for debugging, testing, or demoing a device. - -.. note:: Manual mode will require you to reboot your device to apply an update. - -.. note:: If ``aktualizr-lite`` default daemon mode does not fit your needs, the alternative is to create a :ref:`ug-custom-sota-client`. - -View Current Status -~~~~~~~~~~~~~~~~~~~ - -To view the current status of the device:: - - sudo aktualizr-lite status - -Fetch and List Updates -~~~~~~~~~~~~~~~~~~~~~~ - -This will refresh the Targets metadata from the OTA server, and present you with a list of available Targets:: - - sudo aktualizr-lite list - -Apply Latest Update -~~~~~~~~~~~~~~~~~~~ - -This will apply the latest available update to the device. -This includes both OSTree and Docker app Targets:: - - sudo aktualizr-lite update - -Apply Specific Update -~~~~~~~~~~~~~~~~~~~~~ - -To update to a specific build number:: - - sudo aktualizr-lite update --update-name - -.. note:: - - This can only be performed when the original and update Targets are under the same tag. - In case the update is tagged differently, it is required to switch tags before running this command. - -.. warning:: - Downgrading to a older Target is neither recommended or supported by our team; - doing so may lead to unverified corner cases. - Only choose to do so mindfully. - For any update, always test before rolling out to production devices. +.. note:: If ``aktualizr-lite`` default daemon mode does not fit your needs, the alternative is :ref:`ug-custom-sota-client`. Configuration ------------- diff --git a/source/user-guide/aklite-cli-example.sh b/source/user-guide/aklite-cli-example.sh new file mode 100755 index 00000000..7f8f1775 --- /dev/null +++ b/source/user-guide/aklite-cli-example.sh @@ -0,0 +1,60 @@ +#!/bin/env bash + +# Relevant aktualizr-lite CLI return codes for controlling execution flow +OK=0 +CHECKIN_OK_CACHED=3 + +UPDATE_NEW_VERSION=16 +UPDATE_SYNC_APPS=17 +UPDATE_ROLLBACK=18 + +REBOOT_REQUIRED_BOOT_FW=90 +REBOOT_REQUIRED_ROOT=100 + +# Commands +reboot_cmd="/sbin/reboot" +aklite_cmd="/bin/aktualizr-lite" + +# Interval between each update server polling (seconds) +interval=60 + +# Complete previous installation, if pending +$aklite_cmd run; ret=$? +if [ $ret -eq $REBOOT_REQUIRED_ROOT ]; then + echo "A system reboot is required to finalize the pending installation." + exit 1 +fi + +while true; do + echo "Checking for updates..." + $aklite_cmd check; ret=$? + if [ $ret -eq $UPDATE_NEW_VERSION -o $ret -eq $UPDATE_SYNC_APPS -o $ret -eq $UPDATE_ROLLBACK ]; then + echo "There is a target that is meant to be installed (check returned $ret). Pulling..." + $aklite_cmd pull; ret=$? + if [ $ret -eq $OK ]; then + echo "Pull operation successful. Installing..." + $aklite_cmd install; ret=$? + if [ $ret -eq $REBOOT_REQUIRED_ROOT -o $ret -eq $REBOOT_REQUIRED_BOOT_FW ]; then + echo "Installation completed, reboot required ($ret)" + break + elif [ $ret -eq $OK ]; then + echo "Installation completed, no reboot needed" + continue + else + echo "Installation failed with error $ret" + fi + else + echo "Pull operation failed with error $ret" + fi + elif [ $ret -eq $OK -o $ret -eq $CHECKIN_OK_CACHED ]; then + echo "No update is needed" + else + echo "Check operation failed with error $ret" + fi + echo "Sleeping $interval seconds..." + sleep $interval +done + +echo "Rebooting ($reboot_cmd)..." +$reboot_cmd + diff --git a/source/user-guide/custom-sota-client.rst b/source/user-guide/custom-sota-client.rst index 0540b587..7e1323f8 100644 --- a/source/user-guide/custom-sota-client.rst +++ b/source/user-guide/custom-sota-client.rst @@ -11,6 +11,7 @@ This is not always the desired operation. There are a couple ways to control thi #. Callbacks #. Custom Update Agent +#. Command Line Interface - CLI (Aktualizr-lite Manual Mode) Callbacks --------- @@ -101,3 +102,217 @@ In addition to the default daemon mode, users can run it as a CLI utility and pe * ``pull`` - pulls the delta between the currently installed and the specified one. * ``install`` - installs the previously pulled Target; yields an error if the specified Target has not been pulled before. * ``run`` - finalizes the installed Target; confirms an update after reboot on a new rootfs version and/or starts the updated apps. + +Command Line Interface - CLI (Aktualizr-lite Manual Mode) +--------------------------------------------------------- + +The `aktualizr-lite` executable can be invoked to perform individual operations allowing more control over the update flow. + +.. warning:: The Command Line Interface is on beta stage, + and is subject to change over the next releases. + +.. note:: In order to use the run individual `aktualizr-lite` commands, + the `aktualizr-lite` service needs to be stopped with ``sudo systemctl stop aktualizr-lite`` + and/or disabled with ``sudo systemctl disable aktualizr-lite``. + +.. note:: If lmp-device-register is used, + the `--start-daemon 0` is recommended + in order to avoid starting aktualizr-lite daemon automatically. + +.. prompt:: + + $ aktualizr-lite --help + aktualizr-lite command line options: + -h [ --help ] Print usage + -v [ --version ] Prints current aktualizr-lite version + -c [ --config ] arg Configuration file or directory path + --loglevel arg Set log level 0-5 (trace, debug, info, warning, error, + fatal) + --update-name arg Name or version of the target to be used in pull, + install, and update commands. default=latest + --install-mode arg Optional install mode. Supported modes: + [delay-app-install]. By default both ostree and apps + are installed before reboot + --interval arg Override uptane.polling_secs interval to poll for + updates when in daemon mode + --json arg Output targets information as json when running check + and list commands + --src-dir arg Directory that contains an offline update bundle. + Enables offline mode for check, pull, install, and + update commands + --command arg Command to execute: run, status, finalize, check, list, + install, pull, update, daemon + + +View Current Status +^^^^^^^^^^^^^^^^^^^ + +To view the current status of the device:: + + sudo aktualizr-lite status + +Fetch TUF Metadata and List Updates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``check`` command will refresh the Targets metadata from the OTA server, +and present you with a list of available Targets:: + + sudo aktualizr-lite check + +The ``list`` command will present the same output, +but will **not** refresh the Targets metadata from the OTA server:: + + sudo aktualizr-lite list + +Both commands can be used in conjunction with the ``--json 1`` option, +which will change the output format to JSON, +and will by default omit other log outputs. + + +Apply Update +^^^^^^^^^^^^ + +The ``update`` command pulls and installs the latest available update to the device, +after updating the TUF metadata. +This includes both OSTree and Docker app Targets:: + + sudo aktualizr-lite update + +To update to a specific build number or target name, +the ``--update-name`` option can be used:: + + sudo aktualizr-lite update --update-name + +A reboot command will be required after installing an update, +followed by the execution on the ``run`` command to finalize the update process:: + + sudo aktualizr-lite run + + +.. note:: + An update can only be performed when the original and update Targets are under the same tag. + In case the target is tagged differently, + it is required to switch tags before running this command. + +.. warning:: + Downgrading to a older Target is neither recommended or supported by our team; + doing so may lead to unverified corner cases. + Only choose to do so mindfully. + For any update, always test before rolling out to production devices. + +Aktualizr-lite command line interface also allows the update steps to be performed individually, +by calling the ``check``, ``pull`` and ``install`` commands individually. +This allows for a higher level of control over the update process. + +The ``check`` command updates the Targets metadata. + +The ``pull`` command pulls the delta between the currently installed Target and the one specified with the ``--update-name`` option. +If no target is specified, the latest one is used. + +The ``install`` command installs the Target, which should have been previously pulled. +It yields an error if the specified Target has not been pulled before, and also supports the ``--update-name`` option. + +It is necessary to verify the return codes for each command in order to guarantee the correct update process flow, +as detailed in the next section. + +Exit Codes +^^^^^^^^^^ +The commands set exit codes (``echo $?``) that can be used by the caller to act accordingly. +The possible return codes for the CLI commands are listed bellow: + +**Return codes for** ``check``, ``pull``, ``install``, **and** ``update`` **commands:** + +- *0*: Success + - Operation executed successfully +- *3*: Success + - Unable to fetch updated TUF metadata, but stored metadata is valid +- *4*: Failure + - Failed to update TUF metadata +- *6*: Failure + - There is no target in the device TUF repo that matches a device tag and/or hardware ID +- *8*: Failure + - Failed to find the ostree commit and/or all Apps of the Target to be installed in the provided source bundle (offline mode only) +- *11*: Failure + - Invalid TUF metadata +- *12*: Failure + - TUF metadata is expired +- *13*: Failure + - Unable to fetch TUF metadata +- *14*: Failure + - TUF metadata not found in the provided path (offline mode only) +- *15*: Failure + - The bundle metadata is invalid (offline mode only).There are a few reasons why the metadata might be invalid: + 1. One or more bundle signatures is/are invalid. + 2. The bundle targets' type, whether CI or production, differs from the device's type. + 3. The bundle targets' tag differs from the device's tag. +- *16*: Success + - Update is required: new target version available +- *17*: Success + - Update is required: apps need synchronization +- *18*: Success + - Update is required: rollback to a previous target +- *20*: Failure + - Selected target not found +- *1*: Failure + - Unknown error + +**Return codes for** ``pull``, ``install``, **and** ``update`` **commands:** + +- *21*: Failure + - Unable to find target to rollback to after a failure to start Apps at boot on a new version of sysroot +- *30*: Failure + - Unable to pull/install: there is an installation that needs completion +- *50*: Failure + - Unable to download target +- *60*: Failure + - There is no enough free space to download the target +- *70*: Failure + - The pulled target content is invalid, specifically App compose file is invalid +- *75*: Failure + - Selected target is already installed +- *102*: Failure + - Attempted to install a previous version + +**Return codes for** ``install``, **and** ``update`` **commands:** + +- *10*: Success + - Execute the `run` subcommand to finalize installation +- *80*: Failure + - Unable read target data, make sure it was pulled +- *90*: Failure + - Reboot is required to complete the previous boot firmware update. After reboot the update attempt must be repeated from the beginning + +**Return codes for** ``install``, ``run``, **and** ``update`` **commands:** + +- *100*: Success + - Reboot to finalize installation +- *5*: Success + - Reboot to finalize bootloader installation +- *120*: Failure + - Installation failed, rollback initiated but requires reboot to finalize + +**Return codes for** ``run`` **command:** + +- *40*: Failure + - No pending installation to run +- *99*: Failure + - Offline installation failed, rollback performed +- *110*: Failure + - Online installation failed, rollback performed +- *130*: Failure + - Installation failed and rollback operation was not successful + +Automating the use of CLI operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The individual command line interface operations, +specially ``check``, ``pull``, ``install`` and ``run``, +can be used to automate an update flow like to the one implemented by the main *aktualizr-lite* daemon, +while allowing for limited customizations. + +.. highlight:: bash + :linenothreshold: 1 + +Sample bash script illustrating usage of CLI operations and return codes handling: + +.. literalinclude:: aklite-cli-example.sh