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

Moving this from Confluence to public docs.

Signed-off-by: Vanessa Maegima <[email protected]>

source/reference-manual/linux/linux-lmp-fs.rst

@@ -0,0 +1,153 @@
+.. _ref-linux-lmp-fs:
+
+LmP File Structure
+==================
+
+LmP uses the `OSTree`_ upgrade system to cover platform updates. It brings a modified file system, which details are covered in this page along with some tips about the LmP structure and OTA behavior.
+
+OSTree File System
+------------------
+
+.. prompt::
+
+   # ls -l /
+   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 is mounted on ``/`` (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 as that is covered by an LmP OTA.
+
+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`).
+
+   * 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/
+   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.
+
+* A testing hack is to remount the ``/usr`` folder as **read-write** for testing purposes:
+
+.. prompt::
+
+   $ sudo mount -o remount,rw /usr
+
+This is however **not recommended** and should only be done in development devices, which can be re-flashed in case this change causes a bad behavior in the updates.
+
+.. _OSTree: https://ostreedev.github.io/ostree/introduction/

source/reference-manual/linux/linux.rst

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