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

rm: linux-lmp-fs: add page about lmp file structure #613

Merged
merged 1 commit into from
Oct 20, 2023
Merged

rm: linux-lmp-fs: add page about lmp file structure #613

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
145 changes: 145 additions & 0 deletions source/reference-manual/linux/linux-lmp-fs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
.. _ref-linux-lmp-fs:

LmP File Structure
==================

LmP uses the `OSTree`_ upgrade system to cover platform updates. It brings a modified file system structure, the details for which are covered on this page, along with some tips about the LmP structure and OTA behavior.

Check warning on line 6 in source/reference-manual/linux/linux-lmp-fs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/linux/linux-lmp-fs.rst", "range": {"start": {"line": 6, "column": 66}}}, "severity": "INFO"}

OSTree File System Structure
----------------------------

.. prompt::

# ls -l /
vanmaegima marked this conversation as resolved.
Show resolved Hide resolved
total 17
lrwxrwxrwx 2 root root 7 Jul 31 22:32 bin -> usr/bin
drwxr-xr-x 5 root root 1024 Aug 1 15:44 boot
drwxr-xr-x 12 root root 3340 Aug 2 17:17 dev
drwxr-xr-x 39 root root 4096 Aug 1 15:46 etc
lrwxrwxrwx 2 root root 17 Jul 31 22:32 home -> var/rootdirs/home
lrwxrwxrwx 2 root root 7 Jul 31 22:32 lib -> usr/lib
lrwxrwxrwx 2 root root 18 Jul 31 22:32 media -> var/rootdirs/media
lrwxrwxrwx 2 root root 16 Jul 31 22:32 mnt -> var/rootdirs/mnt
lrwxrwxrwx 2 root root 16 Jul 31 22:32 opt -> var/rootdirs/opt
lrwxrwxrwx 2 root root 14 Jul 31 22:32 ostree -> sysroot/ostree
dr-xr-xr-x 148 root root 0 Aug 2 17:16 proc
lrwxrwxrwx 2 root root 12 Jul 31 22:32 root -> var/roothome
drwxrwxrwt 20 root root 540 Aug 2 17:17 run
lrwxrwxrwx 2 root root 8 Jul 31 22:32 sbin -> usr/sbin
lrwxrwxrwx 2 root root 16 Jul 31 22:32 srv -> var/rootdirs/srv
dr-xr-xr-x 12 root root 0 Aug 2 17:16 sys
drwxr-xr-x 5 root root 4096 Jul 31 22:34 sysroot
drwxrwxrwt 7 root root 140 Aug 2 17:17 tmp
drwxr-xr-x 12 root root 4096 Jan 1 1970 usr
drwxr-xr-x 13 root root 4096 Aug 1 15:46 var

OSTree brings a **read-only** file system, where the disk partition is ``/sysroot`` and the root that mounted at ``/`` (as above) is ``/sysroot/ostree/deploy/lmp/deploy/<sha>``.

Some folders should not be manipulated in order to ensure proper behavior of OTA. The ``/usr`` path is an example of a critical folder that is mounted as read-only and should not be touched—this is covered by LmP OTA.

Check warning on line 38 in source/reference-manual/linux/linux-lmp-fs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/linux/linux-lmp-fs.rst", "range": {"start": {"line": 38, "column": 83}}}, "severity": "INFO"}

Persistent Storage
------------------

These folders are treated like persistent storage on the device and have particularities with regards to updates:

* ``/var``

* Main persistent storage, writable directory.

* Most important files are located under ``/var`` (see :ref:`ref-linux-lmp-fs-important-files`).

Check failure on line 49 in source/reference-manual/linux/linux-lmp-fs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/reference-manual/linux/linux-lmp-fs.rst", "range": {"start": {"line": 49, "column": 69}}}, "severity": "ERROR"}

Check failure on line 49 in source/reference-manual/linux/linux-lmp-fs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/reference-manual/linux/linux-lmp-fs.rst", "range": {"start": {"line": 49, "column": 75}}}, "severity": "ERROR"}

* Not covered by OTA.

* ``/etc``

* Covered by OTA if untouched.

* As soon as OSTree detects a change in this directory, it performs a 3-way merge using the old default configuration, the active system's ``/etc``, and the new default configuration. This is then not covered by OTA anymore.

* For the reason above, Foundries.io do not recommend setting system configurations in this directory. It is more reliable to set critical configurations under ``/usr/lib`` as that is always covered by OTA.

.. _ref-linux-lmp-fs-important-files:

Important Files and Folders
---------------------------

* ``/var/sota``: Stores critical OTA files.

.. prompt::

# ls -l /var/sota/
vanmaegima marked this conversation as resolved.
Show resolved Hide resolved
total 208
-rw-r--r-- 1 root root 692 Aug 1 15:41 client.pem
drwxr-xr-x 3 root root 4096 Aug 1 15:44 compose-apps
-rw-r--r-- 1 root root 265 Aug 1 15:49 current-target
drwxr-xr-x 2 root root 4096 Aug 1 15:41 import
-rw-r--r-- 1 root root 227 Aug 1 15:41 pkey.pem
drwxr-xr-x 4 root root 4096 Aug 1 15:42 reset-apps
-rw-r--r-- 1 root root 668 Aug 1 15:41 root.crt
-rw-r--r-- 1 root root 885 Aug 1 15:41 sota.toml
-rw-r--r-- 1 root root 180224 Aug 1 15:49 sql.db

**/var/sota/sota.toml**: Stores relevant OTA information, like Tag, Apps, custom configurations, certificates location and server address.

**/var/sota/reset-apps**: Holds preloaded apps if :ref:`ug-restorable-apps` are used (default since LmP **v85**).

**/var/sota/compose-apps**: Apps are extracted to this location during app loading. It holds preloaded apps if Compose Apps are used.

**/var/sota/current-target**: Brings valuable information about the current Target running on the device, including LmP and containers information. This is populated after the first OTA.

.. prompt::

# cat /var/sota/current-target
TARGET_NAME="qemuarm64-secureboot-lmp-116"
CUSTOM_VERSION="<target>"
LMP_MANIFEST_SHA="9f288aba55d140786360a71f773a098d1aa0a4fd"
META_SUBSCRIBER_OVERRIDES_SHA="dfd11d7e00db24641bd88c2d9d680c38ba5fdf19"
CONTAINERS_SHA="459e19cde44e17b17054b0cd972f0520cd214f58"
TAG="<tag>"

**/var/sota/sql.db**: Device registration database.

**/var/sota/client.pem**, **/var/sota/pkey.pem** and **/var/sota/root.crt**: Device registration certificates. If available, ``client.pem`` and ``pkey.pem`` can be stored in an HSM rather than on files.

* ``/var/lib/docker``: Stores Docker images and containers.

* ``/var/rootdirs/home/fio/``: Home directory.

* ``/etc/os-release``: Brings valuable LmP information, including LmP Target, Tag and LmP release. It does not include information on containers Target.

.. prompt::

# cat /etc/os-release
ID=lmp
NAME="Linux-microPlatform"
VERSION="4.0.11-116-91"
VERSION_ID=4.0.11-116-91
PRETTY_NAME="Linux-microPlatform 4.0.11-116-91"
HOME_URL="https://foundries.io/"
SUPPORT_URL="https://support.foundries.io/"
DEFAULT_HOSTNAME="qemuarm64-secureboot"
LMP_MACHINE="qemuarm64-secureboot"
LMP_FACTORY="<factory-name>"
LMP_FACTORY_TAG="<tag>"
IMAGE_ID=lmp-factory-image
IMAGE_VERSION=<os-target>

Tips and Suggestions
--------------------

* A :ref:`systemd service <ref-troubleshooting_systemd-service>` can be used in case a file in a directory not covered by OTA needs to be updated.

* It is recommended to store custom user files under ``/var/local``. Keep any custom files location in mind when implementing a :ref:`ref-factory-device-reset`.

* The full initial Target information (includes containers and LmP) just after the provisioning of a device can be checked with:

.. prompt::

# cat /var/sota/import/installed_versions | grep "\"version\""
"version": "102",

After the first OTA, it can be read in ``/var/sota/current-target`` as discussed previously.

* If enabling :ref:`ref-linux-persistent-log`, ``/var/log`` is used to store system logs. It is recommended to mount it in an additional storage so it does not take valuable internal storage space which could impact the OTA behavior.

Check failure on line 143 in source/reference-manual/linux/linux-lmp-fs.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Linux' instead of 'linux'", "location": {"path": "source/reference-manual/linux/linux-lmp-fs.rst", "range": {"start": {"line": 143, "column": 25}}}, "severity": "ERROR"}

.. _OSTree: https://ostreedev.github.io/ostree/introduction/
1 change: 1 addition & 0 deletions source/reference-manual/linux/linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ and maintained by Foundries.io on `GitHub`_.
linux-dev-container
linux-building
linux-kernel
linux-lmp-fs
linux-layers
linux-distro
linux-wic-installer
Expand Down