Filesystem and Overlay Management

The cube:evk uses a fail-safe filesystem layout for embedded systems. It supports atomic software updates with rollback, and isolates user-level changes from the base system.

1. Filesystem Overview

The system is divided into multiple partitions, each serving a distinct purpose:

This configuration lets the cube:evk update its software while keeping the base system partitions immutable. Changes made by the user or applications are stored in the read-write overlay layer; the underlying root filesystem stays untouched.

2. Overlay Filesystem (OverlayFS)

The overlay filesystem combines two layers:

1. Lower layer: The immutable base filesystem (from rootfsA or rootfsB).
2. Upper layer: The writable overlay partition.

When files are created, modified, or deleted, the operations affect only the overlay layer. From the user's perspective the system appears writable; in practice, changes are stored separately and can be inspected or reverted.

3. cube-overlay

To simplify inspection and management of the overlay filesystem, the cube:evk includes the command-line utility cube-overlay.

This tool allows you to:

• Inspect filesystem differences (diff)
• Get modification statistics (status)
• Restore specific files or directories to their original state (restore)

Usage

1
2
3
4
5
6
7
8
9
10
cube:~$ cube-overlay --help
usage: cube-overlay [-h] [-n] {diff,status,restore} path

positional arguments:
  {diff,status,restore}
  path

options:
  -h, --help            show this help message and exit
  -n, --dry-run

Inspecting Changes

The diff command lists all changes made under a specified path. Files are categorized as NEW, MOD, DEL, or UKN (unknown/inaccessible).

1
2
3
4
5
6
cube:~$ cube-overlay diff /etc
NEW /etc/cni
NEW /etc/docker/key.json
MOD /etc/machine-id
DEL /etc/systemd/system/cube.target.wants/led-setup.service
UKN /etc/wireguard

Legend:

• NEW – File or directory created in the overlay
• MOD – File modified relative to the base system
• DEL – File deleted from the overlay view
• UKN – Unknown or inaccessible (for example, permission or transient)

This helps developers understand exactly what has changed in the writable layer.

Summarizing Modifications

The status command provides a quick statistical overview of all modifications within a given directory.

1
2
3
4
5
6
cube:~$ cube-overlay status /etc
Unmodified:   693
Modified:     2
Created:      19
Deleted:      4
Inaccessible: 5

This is useful for tracking system drift over time or identifying unexpected changes.

Restoring Files

You can restore individual files or directories to their original state as they exist in the read-only base filesystem. This operation removes their modified or deleted versions from the overlay layer.

1
cube:~$ sudo cube-overlay restore /etc/ssh/sshd_config

After restoration, the system will use the original version from the base root filesystem.

Dry Run Mode

Use the --dry-run (-n) option to preview what would happen without actually performing changes:

1
cube:~$ cube-overlay --dry-run restore /etc

This is useful for automation scripts or before running irreversible operations.

4. Update and Rollback Mechanism

The SWUpdate framework manages system updates on the cube:evk using the dual-partition scheme.

How it works:

1. The active partition (e.g., rootfsA) runs the system.
2. A new update is written to the inactive partition (rootfsB).
3. After a successful integrity check, the system switches boot targets.
4. If boot verification fails, it automatically rolls back to the last known good partition.

Updates are atomic, fail-safe, and reversible, including during power loss or interruption.