Document update processes

docs/README.md

@@ -56,9 +56,11 @@ The list of default applications and their description can be found [here](appli
 
 - [Applications and libraries](specs/applications-libraries.md) - document describing common things between applications and libraries
 - [Applications](specs/applications.md) - how applications are structured and behave
+- [Libraries](specs/libraries.md) - what are libraries
 - [Filesystem](specs/filesystem.md) - how the filesystem works
 - [Storage permissions](specs/storage-permissions.md) - how permissions are managed on filesystem elements
-- [Libraries](specs/libraries.md) - what are libraries
+- [The boot process](specs/boot-process.md) - how updates are performed
+- [Update processes](update-processes.md) - how updates are performed
 - [Containers](specs/containers.md) - process isolation system
 - [Permissions](specs/permissions.md) - list of applications' permissions
 - [The registry](specs/registry.md) - exhaustive specification of the registry's content

docs/SUMMARY.md

@@ -40,10 +40,11 @@
 - [Specifications](specs/README.md)
   - [Applications and libraries](specs/applications-libraries.md) - what applications and libraries are
   - [Applications](specs/applications.md) - how applications are structured and behave
+  - [Libraries](specs/libraries.md) - what are libraries
   - [Filesystem](specs/filesystem.md) - how the filesystem works
-  - [Boot process](specs/boot-process.md) - how the system starts
   - [Storage permissions](specs/storage-permissions.md) - how permissions are managed on filesystem elements
-  - [Libraries](specs/libraries.md) - what are libraries
+  - [The boot process](specs/boot-process.md) - how the system starts
+  - [Update processes](update-processes.md) - how updates are performed
   - [Permissions](specs/permissions.md) - list of applications' permissions
   - [Containers](specs/containers.md) - process isolation system
   - [The registry](specs/registry.md) - exhaustive specification of the registry's content

docs/specs/README.md

@@ -6,10 +6,11 @@ For more informations about low-level concepts these documents refer to, you can
 
 - [Applications and libraries](applications-libraries.md) - document describing common things between applications and libraries
 - [Applications](applications.md) - how applications are structured and behave
-- [Boot process](boot-process.md) - how the system starts
+- [Libraries](libraries.md) - what are libraries
 - [Filesystem](filesystem.md) - how the filesystem works
 - [Storage permissions](storage-permissions.md) - how permissions are managed on filesystem elements
-- [Libraries](libraries.md) - what are libraries
+- [The boot process](boot-process.md) - how the system starts
+- [Update processes](update-processes.md) - how updates are performed
 - [Containers](containers.md) - process isolation system
 - [Permissions](permissions.md) - list of applications' permissions
 - [The registry](registry.md) - exhaustive specification of the registry's content

docs/specs/boot-process.md

@@ -2,17 +2,19 @@
 
 The system's boot process is divided in two parts: the unsecure bootloader (BOOT1) and the system bootloader (BOOT2).
 
+Note that BOOT1 and BOOT2 have their own [dedicated partitions](filesystem.md#partitions), the latter getting one for slot 1 and another for slot 2 (see below for more details).
+
 ## Stage 1: unsecure bootloader (BOOT1)
 
 This is the component loading at the very beginning, called directly by the UEFI. It is unencrypted (hence the name "unsecure").
 
 It starts by initializing the minimum required computer's components.
 
-If the "Escape" key is detected as being pressed during a short time frame, it shows a troubleshooting menu.
+If the "Escape" key is detected as being pressed during a short time frame, it shows a troubleshooting menu, notably switching the boot slot.
 
 If other bootloaders are found on the storage, it displays a boot menu asking which system to boot. If another system is selected, it launches it.
 
-Otherwise, it perform decryption steps depending on the configured [encryption method](../features/encryption.md):
+Otherwise, it tries to get the master key depending on the configured [encryption method](../features/encryption.md):
 
 * If storage encryption is disabled or if only [USGE](../features/encryption.md#per-user-shared-global-encryption-usge) is enabled, nothing to do ;
 * If [full-storage encryption](../features/encryption.md#full-storage-encryption) is enabled:
@@ -21,6 +23,8 @@ Otherwise, it perform decryption steps depending on the configured [encryption m
     * Otherwise, ask for the recovery key to decrypt the storage (only required once)
   * Otherwise ask for master password and use it to decrypt the master key
 
+It checks the boot slot to use (1 or 2), and read BOOT2 from it.
+
 If BOOT2 is encrypted (full-storage encryption only), the master key is used to decrypt it. Its signature is then checked to ensure it has not been modified. If the signature don't match, the computer will by default refuse to boot to avoid corruption and/or booting malicious programs. By inputting a specific phrase displayed on the screen, the user can force the boot process, at the expense of security.
 
 If signatures match, BOOT2 is launched directly.

docs/specs/filesystem.md

@@ -2,7 +2,7 @@
 
 This document presents how files are stored in NightOS.
 
-- [Presentation](#presentation)
+- [Partitions](#partitions)
 - [Identifiers and limitations](#identifiers-and-limitations)
   - [Filesystem unique identifier](#filesystem-unique-identifier)
   - [Element unique identifier](#element-unique-identifier)
@@ -20,14 +20,15 @@ This document presents how files are stored in NightOS.
 - [Structure](#structure)
   - [Notes](#notes)
 
-## Presentation
+## Partitions
 
 NightOS uses the **Btrfs** filesystem for the main storage due to its robustness, performance, and features (e.g. snapshots).
 
 Three partitions are used to store the data:
 
-* One **FAT32** partition for the bootloader ;
-* One **FAT32** partition for the system (`/sys` and `/etc/sys`) ;
+* One **FAT32** partition for [BOOT1](./boot-process.md#stage-1-unsecure-bootloader-boot1) ;
+* One **FAT32** partition for [BOOT2](./boot-process.md#stage-2-system-loader-boot2) (slot 1) ;
+* One **FAT32** partition for [BOOT2](./boot-process.md#stage-2-system-loader-boot2) (slot 2) ;
 * One **Btrfs** partition for users' data (`/etc` except `/etc/sys`, `/apps` and `/home`)
 
 ## Identifiers and limitations
@@ -150,11 +151,10 @@ _NOTE:_ `<F>` indicates the item is a file.
 ├── etc                            Mutable data folder
 │   ├── env   <F>                  Environment variables
 │   ├── hosts <F>                  Hosts overriding (e.g. 'localhost')
-│   ├── lock                       Opened lock files
 │   ├── logs                       Log files
 │   |   └── upe <F>                History of UPE requests (1)
 │   ├── public                     Public data, readable and writable by everyone
-│   └── sys                        System's mutable data - available to system only
+│   └── sys (4)                    System's mutable data - available to system only
 │       ├── registry    <F>        System's registry
 │       ├── awake       <F>        System's shutdown indicator to detect if there was an error during last shutdown
 │       ├── integrity              Integrity data used during the boot process (2)
@@ -176,7 +176,7 @@ _NOTE:_ `<F>` indicates the item is a file.
 │       └── trash                  User's trash
 ├── mnt                            Mounted storages
 │   └── root                       Soft link to `/`
-├── sys                            System - immutable outside of installation, repair processes and updates
+├── sys (4)                        System - immutable outside of installation, repair processes and updates
 │   ├── apps                       System applications
 │   ├── boot                       System's boot program
 │   ├── langs                      Translation files
@@ -193,6 +193,7 @@ Links:
 - (1) [UPE requests](../concepts/users.md#user-privileges-elevation-upe)
 - (2) Used for [integrity checking](../specs/boot-process.md)
 - (3) Global storage's [encryption](../features/encryption.md) key
+- (4) Not stored in the main data pratition but in the [BOOT2 partition](#partitions)
 
 ### Notes
 

docs/specs/update-processes.md

@@ -0,0 +1,72 @@
+# Update processes
+
+This document describes how updates are performed.
+
+## System updates
+
+The system selects an update source, which is one of:
+
+* The official servers (default)
+* An alternative server (configured by the user)
+* A local update repository package
+
+The source is authenticated, then the latest updates (not yet present on the system) are pulled from it as update package files (`.nsu`).
+
+If multiple updates must be installed, they are installed one after the other. This will probably change in the future when an incremental update system is designed.
+
+### System update packages
+
+Each package file is a simple TAR + GZ archive with the following structure:
+
+* `/metadata`: contains metadata on the updates
+* `/update`: "up-down" update program
+* `/assets`: a directory containing various files (can be anything)
+
+### Update steps
+
+1. The update package is extracted in a temporary path
+2. Update metadata are checked
+3. The system checks the currently used [slot](boot-process.md)
+4. The active slot (= all files currently in `/sys`) is copied to the other slot
+5. An incremental system backup is created, containing all data from active slot (`/sys`) as well as the `/etc/sys` directory is created
+6. A non-incremental (full) system backup is created
+7. A Btrfs snapshot of the main partition is created
+8. The "up-down" update program is run
+9. In case of success, the active slot number is inverted
+10. System reboots
+11. After a week or two more reboots (whichever happens last), the main partition snapshot as well as the non-incremental system backup are deleted
+
+This allows the following:
+
+* If the new BOOT2 does not work, we can revert it instantly until the next update ;
+* If some modifications created problems, we can roll them back using the main partition snapshot ;
+* If some problems appear later on, the boot snapshot allows to entirely rollback both `/sys` and `/etc/sys`
+
+Incremental system snapshots are kept indefinitely in order to allow an easy rollback. A timestamp, system version and update number are associated, in order to quickly determine the state it was in.
+
+### Up-down update program
+
+An up-down update program is a program that can either install or uninstall an update.
+
+It is provided an history of all system updates as well as a snapshot of the BOOT2 partition at each point in time.
+
+## Application updates
+
+An application update can happen in either scenario:
+
+* The system checked for updates in the Store (official or custom) and found one ;
+* The application asked the system to check for update and it found one ;
+* A custom application update package (`.nua`) was provided
+
+The update package file is then checked. It is a simple TAR + GZ archive containing the following:
+
+* `metadata`: contains update metadata
+* `files`: a directory containing all files to replace in the application
+
+Note that an update can only apply to a specific version of the application, specified in the metadata. Otherwise, previous updates must be installed first.
+
+If valid, the system asks the user to close the application if it is opened.
+
+After the application is fully closed (including services), its files are replaced with the ones provided in the archive's `files` directory.
+
+The application is then started with its new state.

docs/technical/file-formats.md

@@ -6,6 +6,7 @@ This document presents the file formats natively handled by NightOS. Some files
 - [Virtual storages](#virtual-storages)
 - [Application packages](#application-packages)
 - [System updates](#system-updates)
+- [Application updates](#application-updates)
 
 ## Common formats
 
@@ -44,3 +45,11 @@ The system is intended to be updated through the update section in the settings,
 They may contain one or several updates, and are only installable on a very specific version of the system, to avoid missing some other incremental updates.
 
 System update files have the `.nsu` (NightOS System Update) extension and are opened using the [control center](../applications/Central.md).
+
+## Application updates
+
+Applications are intended to be updated through the update section in the settings, but sometimes it may be required to install updates offline for specific reasons (e.g. no network connection available at the moment). In such case, it is possible to download incremental updates as application update files.
+
+They may contain one or several updates, and are only installable on a very specific version of the application, to avoid missing some other incremental updates.
+
+Application update files have the `.nau` (NightOS Application Update) extension and are opened using the [control center](../applications/Central.md).