Skip to content

Commit

Permalink
ug: Add documentation for aktualizr-lite command line interface
Browse files Browse the repository at this point in the history 
Signed-off-by: Andre Detsch <andre.detsch@foundries.io>
  • Loading branch information
@detsch
detsch committed Sep 12, 2024
1 parent af91c20 commit 9d9037d
Show file tree
Hide file tree
Showing 2 changed files with 209 additions and 48 deletions.
49 changes: 1 addition & 48 deletions source/reference-manual/ota/aktualizr-lite.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <build_number>

.. 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
-------------
Expand Down
208 changes: 208 additions & 0 deletions source/user-guide/custom-sota-client.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Check warning on line 14 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.em-dash] Did you mean to you use an em dash '—'?

Raw Output:
{"message": "[Fio-docs.em-dash] Did you mean to you use an em dash '—'?", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 14, "column": 26}}}, "severity": "WARNING"}

Callbacks
---------
Expand Down Expand Up @@ -101,3 +102,210 @@ 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)

Check warning on line 106 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.em-dash] Did you mean to you use an em dash '—'?

Raw Output:
{"message": "[Fio-docs.em-dash] Did you mean to you use an em dash '—'?", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 106, "column": 23}}}, "severity": "WARNING"}
---------------------------------------------------------

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

Check warning on line 154 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 154, "column": 7}}}, "severity": "WARNING"}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

Check warning on line 176 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 176, "column": 20}}}, "severity": "WARNING"}
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 <build_number_or_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


.. 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.

The 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 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 below:

**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

Check warning on line 224 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 224, "column": 31}}}, "severity": "WARNING"}
- *4*: Failure
- Failed to update TUF metadata

Check warning on line 226 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 226, "column": 24}}}, "severity": "WARNING"}
- *6*: Failure
- There is no target in the device TUF repo that matches a device tag and/or hardware ID

Check warning on line 228 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 228, "column": 40}}}, "severity": "WARNING"}
- *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

Check warning on line 232 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 232, "column": 15}}}, "severity": "WARNING"}
- *12*: Failure
- TUF metadata is expired

Check warning on line 234 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 234, "column": 7}}}, "severity": "WARNING"}
- *13*: Failure
- Unable to fetch TUF metadata

Check warning on line 236 in source/user-guide/custom-sota-client.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/custom-sota-client.rst", "range": {"start": {"line": 236, "column": 23}}}, "severity": "WARNING"}
- *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,
especially ``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.

This `sample bash script
<https://raw.githubusercontent.com/foundriesio/sotactl/main/scripts/aklite-cli-example.sh>`_
illustrates the usage of CLI operations and proper return codes handling.

0 comments on commit 9d9037d

Please sign in to comment.