# Update Engine and ue-rs

## Update Engine

* [GitHub repo](https://github.com/flatcar/update_engine)

(For now its debian only, we should also add fedora etc later of course)

## Environment Setup Instructions

In order to set up the environment, follow these steps:

### Step 1: Update and Install Dependencies

First, update your package list and install the necessary dependencies:

sudo apt update
sudo apt install -y libunwind-dev libblkid-dev libext2fs-dev libmount-dev curl unzip libdbus-glib-1-dev protobuf-compiler libbz2-dev libgflags-dev libssl-dev libgoogle-glog-dev libcurl4-openssl-dev libxml2-dev libprotobuf-dev cmake wget libtool autoconf libgtest-dev libgmock-dev libbrotli-dev libdivsufsort-dev libsodium-dev

### Step 2: Prepare `rootdev`

Download and install `rootdev`:

curl -sSL -o /tmp/seismograph.zip https://github.com/kinvolk/seismograph/archive/flatcar-master.zip
cd /tmp
unzip /tmp/seismograph.zip
cd seismograph-flatcar-master
./autogen.sh
./configure
make
sudo make install
sudo ldconfig

### Step 3: Prepare `bsdiff`

Clone and install the Chromium OS version of `bsdiff`:

cd /tmp
git clone https://android.googlesource.com/platform/external/bsdiff
cd bsdiff
git checkout 7b331f19d984c508be8935bdcab2ab6c267f3b57
make -j$(nproc)
sudo make install PREFIX=/usr/local

### Step 4: Run `autogen.sh`

Generate the `configure` script and other necessary files:

./autogen.sh

### Step 5: Run `configure`

Configure the project for building:

./configure

### Step 6: Build the Project

Compile the project:

make -j$(nproc)

### Step 7: Run Tests

Run the tests to ensure everything is working correctly:

make check -j$(nproc)

### structure

It consists of several parts.

* update_engine: daemon that listens to client requests
* update_engine_client: client binary that sends queries to update_engine
- both server and binary are linked against shared lib libupdate_engine.so

* delta_generator: command-line tool that generates binary diff (delta) between 2 versions of images. (`src/update_engine/generate_delta_main.cc`) - involked during build_image step of main Flatcar build scripts.
- takes private key, `flatcar_production_update.bin` image, Kernel image,
- calculates delta: install operations to delta archive manifest
- stores output into `flatcar_production_update.gz`

* flatcar-postinst: a standalone script to take care of postinstall actions in Omaha response
- The script is part of update_engine package, shipped in the production image
- symlinked to `/usr/postinst` (done in scripts/.../coreos-overlay/.../`update_engine-9999.ebuild`)
- involked for postinstall hook Omaha, by `PostinstallRunnerAction::PerformAction` in `postinstall_runner_action.cc`.

### Omaha protocol with protobuf

Data structure is defined with protobuf format in `update_metadata.proto`, which becomes translated into actual source files `update_metadata.pb.cc` and `update_metadata.pb.h`. Keep the single source of truth.

### File magic of update payload

Header of every update payload includes a file magic string `CrAU`, defined in the source file `update_metadata.proto`. That is also widely-used both in update engine and ue-rs.

### Format of update payload

| header | manifest | data blobs |signatures |
| -------- | -------- | -------- | -------- |

Note that signatures are placed at the end of the message.

## ue-rs

[GitHub repo](https://github.com/flatcar/ue-rs)

* Should be as minimal as possible. Since `update_engine` has a long history of multiple forks of a [ChromiumOS project](https://chromium.googlesource.com/aosp/platform/system/update_engine/), its code base is inherently heavy and complicated. To address that, it is made by rewriting only essential parts like parsing Omaha protocol from scratch, and use pure Rust RSA libraries instead of relying on openssl.
* Written in Rust, a huge advantage for security, especially memory safety, in contrast to the previous `update_engine`, which is written mainly in C++ and bash.
* In addition to traditional OS update payloads, it supports systemd-sysext OEM supported by Flatcar Container Linux.
* Should be pluggable for integration with systemd-sysupdate.
* Should be integrated with Nebraska

However, ue-rs should still follow the same data format as update_engine. Need to take source `update_metadata.proto` to translate into `update_metadata.rs`.

It consists of several parts:

* download_sysext : standalone binary to demonstrate sysext OEM image to parse Omaha response and verify checksum & signatures.
* omaha: library for parsing Omaha messages in dedicated workspace
* update-format-crau: library for verifying RSA signatures in dedicated workspace

### Milestone

(might be outdated, as of Dec. 2023)

* Implement DBus communication for client-server architecture like update_engine
* based on Rust-native DBus implementations like zbus
* Facilitate state machine model
* reports states like UPDATE_STATUS_IDLE, UPDATE_STATUS_UPDATE_AVAILABLE
* Full support of Omaha protocol
* ping, check for updates, generate payloads
* Fetch, validate, install OS image and extensions
* Fetch images with signature verification (Done)
* Fetch, verify, write partitions, Kernel, sysext images
* Run postinstall hook