Filesystem and Overlay Management

The cube:evk uses a robust, fail-safe filesystem layout designed specifically for embedded systems. It ensures system reliability during software updates, provides rollback protection, and allows user-level customization without risking system integrity.

1. Filesystem Overview

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

This configuration allows the cube:evk to safely 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, leaving the underlying root filesystem 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, these operations occur only in the overlay layer. From the user’s perspective, the system appears fully writable — but in reality, changes are stored separately and can be easily 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 file (e.g., 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 especially helpful for cautious system administrators and automation scripts.

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.

This mechanism ensures that updates are atomic, fail-safe, and reversible, even if a power loss or interruption occurs during installation.