From 23d492b04703ca356a699d4de136c4f781f2568d Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Tue, 28 Nov 2023 08:52:43 -0500 Subject: [PATCH] Add info about fioctl auto update Added a note in the getting started guide, a slightly more detailed note in the user guide, and an additional somewhat related note in team based access. QA: information will be verified during PR process. Rendered html checked, no errors spotted. No linter errors that need correcting. This commit addresses issue FFTK 2905 Signed-off-by: Katrina Prosise --- .../getting-started/install-fioctl/index.rst | 16 +++++---- .../account-management/team-based-access.rst | 12 +++++++ source/user-guide/fioctl/index.rst | 35 +++++++++++++++++++ 3 files changed, 56 insertions(+), 7 deletions(-) diff --git a/source/getting-started/install-fioctl/index.rst b/source/getting-started/install-fioctl/index.rst index 628d1ae1d..7b1dfdfa3 100644 --- a/source/getting-started/install-fioctl/index.rst +++ b/source/getting-started/install-fioctl/index.rst @@ -3,7 +3,7 @@ Installing Fioctl ================= -:ref:`Fioctl™ ` is a simple tool for interacting with the Foundries.io REST API. +:ref:`Fioctl™ ` is a simple tool for interacting with the Foundries.io™ REST API. .. seealso:: Fioctl is based on Foundries.io's `ota-lite API `_. @@ -27,10 +27,12 @@ Installation Manual Installation ^^^^^^^^^^^^^^^^^^^ -We use `Github Releases`_ to distribute static golang binaries. +We use `GitHub Releases`_ to distribute static golang binaries. .. tip:: - Repeating the following steps will overwrite an existing binary, useful for updating or changing version. + Fioctl v0.36 and later has an auto-update feature. + Run ``fioctl version`` to check for an update, then run ``fioctl version --update-to ``. + For more details checkout the :ref:`Fioctl user guide `. .. tabs:: @@ -64,7 +66,7 @@ We use `Github Releases`_ to distribute static golang binaries. .. attention:: Make sure you have ``curl`` installed. - 1. Download a Darwin binary from the `Github Releases`_ page to a directory on your ``PATH``. + 1. Download a Darwin binary from the `GitHub Releases`_ page to a directory on your ``PATH``. For example, to download version |fioctl_version| on macOS, define the version: @@ -91,7 +93,7 @@ We use `Github Releases`_ to distribute static golang binaries. .. group-tab:: Windows - 1. Download a Windows binary from the `Github Releases`_ page. + 1. Download a Windows binary from the `GitHub Releases`_ page. 2. Put it in a folder of your choosing and rename it to ``fioctl.exe`` 3. Press ``Win + R`` and type ``SystemPropertiesAdvanced`` 4. Press ``enter`` or click ``OK``. @@ -112,7 +114,7 @@ Authenticating Fioctl ##################### With :ref:`ref-fioctl` installed, authenticate it with our backend. -For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory API: +For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory® API: .. prompt:: bash host:~$, auto @@ -190,7 +192,7 @@ The following command can be used to test the ``fioctl`` configuration. .. seealso:: :ref:`ref-fioctl` documentation. -.. _Github Releases: https://github.com/foundriesio/fioctl/releases +.. _GitHub Releases: https://github.com/foundriesio/fioctl/releases .. _gs-git-config: diff --git a/source/user-guide/account-management/team-based-access.rst b/source/user-guide/account-management/team-based-access.rst index e3ce13ce2..dcd629250 100644 --- a/source/user-guide/account-management/team-based-access.rst +++ b/source/user-guide/account-management/team-based-access.rst @@ -90,6 +90,7 @@ The member then has a combined list of scopes: The user now has read **and** write (update) access to the CI, while retaining the read-only scopes for the other resources. + .. _Access to Device Groups: Team Based Access to Device Groups @@ -137,3 +138,14 @@ Therefore, members of this team can modify the ``test-lab-devices`` group and it .. figure:: /_static/userguide/account-management/team-with-group-and-write-access.png :align: center :alt: "lab-dev-users" scopes: read-update team with a device group + + +.. _team-based-access-tuf: + +Changes to TUF Root +------------------- + +With Fioctl® v0.35 and newer, if someone makes changes to TUF root, others will be required to upgrade to the same version if they wish to make changes. +This is to prevent accidental eraser of the TUF keys ownership information. + + diff --git a/source/user-guide/fioctl/index.rst b/source/user-guide/fioctl/index.rst index 42b7a8cb2..289f476c8 100644 --- a/source/user-guide/fioctl/index.rst +++ b/source/user-guide/fioctl/index.rst @@ -10,6 +10,41 @@ Prerequisites * Completion of the getting started guide. + +.. _ug-fioctl-auto-update: + +Auto Updating +------------- + +``fioctl version --update-to `` + Fioctl v0.36 and later can be updated—rather securely, via TUF—without the need to manually reinstall the binary. + +.. code-block:: console + + # check if an update is available: + host:~$ fioctl version + v0.37-24-gd450f5b + Update available: 0.38.0 + https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64 + + # update by running: + host:~$ fioctl version --update-to 0.38.0 + v0.37-24-gd450f5b + Downloading update: https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64 + Saving new version to /var/code/vs-code-server-config/fioctl/bin/fioctl-linux-amd64 + +.. important:: + + A note about write permissions: + + It is likely that you will need to gain write privilege to update. + This *can* be done via ``sudo``, assuming it is not a read-only partition. + However, also consider running ``sudo su`` within a new terminal. + This is to avoid having sudo holding a session, and some privilege escalation risks. + +.. seealso:: + :ref:`Updating Fioctl version for writing to TUF Root ` + .. _ug-fioctl-enable-apps: Enabling/Disabling Apps