Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ug: Add documentation for aktualizr-lite command line interface #734

Merged
merged 1 commit into from
Sep 12, 2024
Merged

ug: Add documentation for aktualizr-lite command line interface #734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 1 addition & 48 deletions source/reference-manual/ota/aktualizr-lite.rst
View file
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

#. 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 @@
* ``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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `aktualizr-lite` executable can be invoked to perform individual operations allowing more control over the update flow.
The ``aktualizr-lite`` executable can be invoked to perform individual operations allowing more control over the update flow.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.


.. warning:: The Command Line Interface is on beta stage,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. warning:: The Command Line Interface is on beta stage,
.. warning:: The Command Line Interface is in beta stage,

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

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``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the `aktualizr-lite` service needs to be stopped with ``sudo systemctl stop aktualizr-lite``
the ``aktualizr-lite`` service needs to be stopped with ``sudo systemctl stop aktualizr-lite``

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

and/or disabled with ``sudo systemctl disable aktualizr-lite``.

.. note:: If lmp-device-register is used,
the `--start-daemon 0` is recommended
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the `--start-daemon 0` is recommended
Using ``--start-daemon 0`` is recommended

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

in order to avoid starting aktualizr-lite daemon automatically.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
in order to avoid starting aktualizr-lite daemon automatically.
in order to avoid starting the aktualizr-lite daemon automatically.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.


.. 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"}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Fetch TUF Metadata and List Updates
Fetch :term:`TUF` Metadata and List Updates

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To update to a specific build number or target name,
To update to a specific build number or Target name,

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

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.
vanmaegima marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to ask someone from CS team to check if the CLI commands and return codes as explained here works for them.

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