+ Mounting {disk.name} at {mountPoint} would
+ hide existing files that are already there.
+
+
+ Found {entries} ({formatBytes(shadowed.size_bytes)}) at the mount target.
+
+
+ Those files will continue to consume space on the underlying filesystem
+ (typically the SD card on a Raspberry Pi) and can fill it up.
+
+
+ Recommended: cancel, move or delete the existing files, then mount.
+
+
+
+
+
+
+
+ );
+ }
+
return (
diff --git a/controller/api/disks.py b/controller/api/disks.py
index cacd820e..d061fa89 100644
--- a/controller/api/disks.py
+++ b/controller/api/disks.py
@@ -14,6 +14,7 @@ from controller.lib.config import (
update_config,
)
from controller.lib.disks import (
+ check_shadowed_data,
get_block_devices,
get_mounts,
mount_drive,
@@ -39,6 +40,10 @@ class MountRequest(BaseModel):
fstype: Optional[str] = Field(default=None, description="Filesystem type (auto-detected if not specified)")
options: str = Field(default="defaults", description="Mount options")
persist: bool = Field(default=False, description="Add to fstab for persistent mounting")
+ force_shadowed: bool = Field(
+ default=False,
+ description="Proceed even if existing data at the mount target would be hidden by the new mount",
+ )
class UnmountRequest(BaseModel):
@@ -98,6 +103,24 @@ async def disk_mount(request: MountRequest):
"""Mount a partition."""
_check_native_mode()
+ # Soft-block if the mount target already contains user data that would
+ # be hidden by the new mount. The UI re-submits with force_shadowed=True
+ # to override.
+ if not request.force_shadowed:
+ shadowed = check_shadowed_data(request.mount_point)
+ if shadowed:
+ return {
+ "success": False,
+ "needs_force": "shadowed",
+ "shadowed_data": shadowed,
+ "error": (
+ f"{request.mount_point} contains {len(shadowed['entries'])} "
+ f"existing data "
+ f"{'entry' if len(shadowed['entries']) == 1 else 'entries'}. "
+ f"Mounting now would hide them on the underlying filesystem."
+ ),
+ }
+
result = mount_drive(
device=request.device,
mount_point=request.mount_point,
diff --git a/controller/api/onboarding.py b/controller/api/onboarding.py
index 93caa11c..1e28bf0a 100644
--- a/controller/api/onboarding.py
+++ b/controller/api/onboarding.py
@@ -12,6 +12,7 @@ from controller.api.schemas import (
OnboardingCommitResponse,
OnboardingProbeRequest,
OnboardingProbeResponse,
+ ShadowedDataInfo,
)
from controller.lib.config import is_docker_mode, is_primary_drive_mounted
from controller.lib.onboarding import (
@@ -78,9 +79,23 @@ async def commit(request: OnboardingCommitRequest):
result = commit_onboarding(
device_path=request.device_path,
fstype=request.fstype,
- force=request.force,
+ force_shadowed=request.force_shadowed,
)
+ # Soft-block: existing data at the mount target would be hidden. Return
+ # a structured response (200 OK with success=False) so the UI can prompt
+ # the user to override.
+ if not result.get("success") and result.get("needs_force") == "shadowed":
+ shadowed = result.get("shadowed_data") or {}
+ return OnboardingCommitResponse(
+ success=False,
+ error=result.get("error"),
+ mounts=[],
+ repair_started=False,
+ needs_force="shadowed",
+ shadowed_data=ShadowedDataInfo(**shadowed) if shadowed else None,
+ )
+
if not result.get("success"):
raise HTTPException(status_code=500, detail=result.get("error", "Onboarding failed"))
diff --git a/controller/api/schemas.py b/controller/api/schemas.py
index 7d500258..eaf0b312 100644
--- a/controller/api/schemas.py
+++ b/controller/api/schemas.py
@@ -467,7 +467,17 @@ class OnboardingCommitRequest(BaseModel):
device_path: str = Field(description="Device path to use as primary drive")
fstype: str = Field(description="Filesystem type")
- force: bool = Field(default=False, description="Proceed even if no config found on drive")
+ force_shadowed: bool = Field(
+ default=False,
+ description="Proceed even if existing data at the mount target would be hidden by the new mount",
+ )
+
+
+class ShadowedDataInfo(BaseModel):
+ """Information about data that would be hidden by a mount."""
+
+ size_bytes: int = Field(description="Total size of data that would be shadowed")
+ entries: list[str] = Field(description="Top-level entries that would be hidden")
class OnboardingCommitResponse(BaseModel):
@@ -477,3 +487,12 @@ class OnboardingCommitResponse(BaseModel):
error: Optional[str] = Field(default=None, description="Error message if failed")
mounts: list[str] = Field(default_factory=list, description="Mount points that were mounted")
repair_started: bool = Field(default=False, description="Whether repair script was started")
+ needs_force: Optional[str] = Field(
+ default=None,
+ description="If set, the request was soft-blocked. Re-submit with the matching force flag. "
+ "Currently: 'shadowed'.",
+ )
+ shadowed_data: Optional[ShadowedDataInfo] = Field(
+ default=None,
+ description="Populated when needs_force='shadowed'.",
+ )
diff --git a/controller/lib/disks.py b/controller/lib/disks.py
index 9762d9f2..ef8448ca 100644
--- a/controller/lib/disks.py
+++ b/controller/lib/disks.py
@@ -254,6 +254,49 @@ def is_mount_busy(mount_point: str) -> bool:
return False
+def check_shadowed_data(target: str) -> Optional[dict]:
+ """Look for user data at `target` that would be hidden by a mount over it.
+
+ Returns a dict with `size_bytes` and `entries` when non-config content is
+ present, or None when the target is empty (or contains only `config/`).
+
+ `config/` is whitelisted because it is created transiently by
+ `generate_certificates.sh` before the primary drive is mounted; that is
+ expected, not user data.
+
+ Returns None for non-existent targets.
+ """
+ target_path = Path(target)
+ if not target_path.exists() or not target_path.is_dir():
+ return None
+
+ try:
+ entries = [e.name for e in target_path.iterdir() if e.name != "config"]
+ except OSError:
+ return None
+ if not entries:
+ return None
+
+ size_bytes = 0
+ for entry in entries:
+ entry_path = target_path / entry
+ try:
+ if entry_path.is_dir():
+ for path in entry_path.rglob("*"):
+ try:
+ if path.is_file() and not path.is_symlink():
+ size_bytes += path.stat().st_size
+ except OSError:
+ # File disappeared mid-walk or unreadable; skip.
+ continue
+ elif entry_path.is_file() and not entry_path.is_symlink():
+ size_bytes += entry_path.stat().st_size
+ except OSError:
+ continue
+
+ return {"size_bytes": size_bytes, "entries": sorted(entries)}
+
+
def get_mounts() -> list[dict]:
"""
Get current mounts under /media.
diff --git a/controller/lib/onboarding.py b/controller/lib/onboarding.py
index c990ef3c..e102d517 100644
--- a/controller/lib/onboarding.py
+++ b/controller/lib/onboarding.py
@@ -21,7 +21,7 @@ from controller.lib.config import (
save_config,
update_config,
)
-from controller.lib.disks import get_block_devices, mount_drive, unmount_drive
+from controller.lib.disks import check_shadowed_data, get_block_devices, mount_drive, unmount_drive
from controller.lib.fstab import add_fstab_entry
from controller.lib.scripts import start_script
@@ -165,25 +165,32 @@ def cancel_probe() -> dict:
return {"success": True}
-def commit_onboarding(device_path: str, fstype: str, force: bool = False) -> dict:
+def commit_onboarding(
+ device_path: str,
+ fstype: str,
+ force_shadowed: bool = False,
+) -> dict:
"""
Execute the full onboarding setup.
1. Unmount temp mount
- 2. Mount primary drive at /media/wrolpi
- 3. Add fstab entry for primary
- 4. Reload config
- 5. Mount secondary drives per config
- 6. Add fstab entries for secondary drives
- 7. Start repair
+ 2. Check for shadowed data at the mount target
+ 3. Mount primary drive at /media/wrolpi
+ 4. Add fstab entry for primary
+ 5. Reload config
+ 6. Mount secondary drives per config
+ 7. Add fstab entries for secondary drives
+ 8. Start repair
Args:
device_path: Device path
fstype: Filesystem type
- force: If True, proceed even without config on drive
+ force_shadowed: If True, proceed even when existing data at the
+ mount target would be hidden by the new mount
Returns:
- dict with success, error, mounts, repair_started
+ dict with success, error, mounts, repair_started, and on a shadowed
+ block, `needs_force` and `shadowed_data`
"""
media_dir = str(get_media_directory())
mounted_mounts = []
@@ -201,6 +208,26 @@ def commit_onboarding(device_path: str, fstype: str, force: bool = False) -> dic
shutil.rmtree(transient_config)
logger.info("Removed transient config directory at %s", transient_config)
+ # Step 1c: Check for shadowed data. If the user has been downloading
+ # to /media/wrolpi without a drive mounted, mounting now would hide
+ # those files on the SD card / root filesystem.
+ if not force_shadowed:
+ shadowed = check_shadowed_data(media_dir)
+ if shadowed:
+ return {
+ "success": False,
+ "needs_force": "shadowed",
+ "shadowed_data": shadowed,
+ "error": (
+ f"{media_dir} contains {len(shadowed['entries'])} "
+ f"existing data "
+ f"{'entry' if len(shadowed['entries']) == 1 else 'entries'}. "
+ f"Mounting now would hide them on the underlying filesystem."
+ ),
+ "mounts": [],
+ "repair_started": False,
+ }
+
# Step 2: Mount primary drive
result = mount_drive(device_path, media_dir, fstype=fstype)
if not result.get("success"):
diff --git a/controller/templates/index.html b/controller/templates/index.html
index 0308c52e..53073664 100644
--- a/controller/templates/index.html
+++ b/controller/templates/index.html
@@ -841,7 +841,7 @@
Found WROLPi configuration on this drive.
-
+
@@ -849,11 +849,24 @@
No WROLPi configuration found on this drive.
This may be a new drive or the wrong drive. You can still use it as a fresh WROLPi drive.
-
+
+
+
+
Existing Files Detected
+
+
Mounting this drive would hide existing files at the mount point.
+
+
If you mount anyway, those files will continue to consume space on the underlying filesystem (typically the SD card on a Raspberry Pi) and can fill it up.
+
Recommended: cancel, move or delete the existing files, then mount.
+
+
+
+
+
Setting Up Drives...
@@ -2166,12 +2179,24 @@
let onboardingFstype = null;
function showOnboardingStep(step) {
- ['select', 'confirm', 'progress', 'complete', 'error'].forEach(s => {
+ ['select', 'confirm', 'shadowed', 'progress', 'complete', 'error'].forEach(s => {
const el = document.getElementById('onboarding-' + s);
if (el) el.style.display = (s === step) ? 'block' : 'none';
});
}
+ function formatBytes(bytes) {
+ if (!bytes || bytes < 1) return '0 B';
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ let i = 0;
+ let n = bytes;
+ while (n >= 1024 && i < units.length - 1) {
+ n /= 1024;
+ i++;
+ }
+ return `${n.toFixed(n >= 10 ? 0 : 1)} ${units[i]}`;
+ }
+
async function loadOnboardingCandidates() {
const container = document.getElementById('onboarding-drives');
const noDrives = document.getElementById('onboarding-no-drives');
@@ -2261,7 +2286,10 @@
}
}
- async function commitOnboarding(force) {
+ async function commitOnboarding(opts) {
+ opts = opts || {};
+ const forceShadowed = !!opts.force_shadowed;
+
showOnboardingStep('progress');
document.querySelector('#onboarding-progress p').textContent = 'Mounting drives and starting repair. Please wait...';
@@ -2272,7 +2300,7 @@
body: JSON.stringify({
device_path: onboardingDevicePath,
fstype: onboardingFstype,
- force: force
+ force_shadowed: forceShadowed,
}),
signal: AbortSignal.timeout(60000)
});
@@ -2283,6 +2311,17 @@
}
const data = await resp.json();
+
+ // Soft-block: target contains existing data that would be shadowed.
+ if (data.success === false && data.needs_force === 'shadowed') {
+ const shadowed = data.shadowed_data || {entries: [], size_bytes: 0};
+ const entries = (shadowed.entries || []).join(', ') || '(unknown)';
+ document.getElementById('onboarding-shadowed-msg').textContent =
+ `Found ${entries} (${formatBytes(shadowed.size_bytes)}) at the mount target.`;
+ showOnboardingStep('shadowed');
+ return;
+ }
+
showOnboardingStep('complete');
if (data.repair_started) {
@@ -2302,6 +2341,10 @@
}
}
+ function confirmShadowedMount() {
+ commitOnboarding({force_shadowed: true});
+ }
+
async function cancelOnboarding() {
try {
await fetch('api/onboarding/cancel', {
diff --git a/controller/test/test_disks.py b/controller/test/test_disks.py
index 7d7bfbe3..78d5b8c6 100644
--- a/controller/test/test_disks.py
+++ b/controller/test/test_disks.py
@@ -9,6 +9,7 @@ import pytest
from controller.lib.disks import (
BlockDevice,
+ check_shadowed_data,
get_block_devices,
get_uuid,
get_wrolpi_uid_gid,
@@ -409,3 +410,51 @@ class TestGetMounts:
assert result[1]["mount_point"] == "/media/usb"
+class TestCheckShadowedData:
+ """Tests for check_shadowed_data."""
+
+ def test_returns_none_for_missing_target(self, tmp_path):
+ assert check_shadowed_data(str(tmp_path / "nope")) is None
+
+ def test_returns_none_for_empty_target(self, tmp_path):
+ target = tmp_path / "wrolpi"
+ target.mkdir()
+ assert check_shadowed_data(str(target)) is None
+
+ def test_returns_none_when_only_config_present(self, tmp_path):
+ """`config/` is whitelisted — it's expected pre-mount state."""
+ target = tmp_path / "wrolpi"
+ target.mkdir()
+ (target / "config").mkdir()
+ (target / "config" / "ssl.crt").write_text("cert")
+ assert check_shadowed_data(str(target)) is None
+
+ def test_detects_directory_entry(self, tmp_path):
+ target = tmp_path / "wrolpi"
+ target.mkdir()
+ (target / "videos").mkdir()
+ (target / "videos" / "a.mp4").write_bytes(b"x" * 100)
+ result = check_shadowed_data(str(target))
+ assert result == {"size_bytes": 100, "entries": ["videos"]}
+
+ def test_detects_file_entry(self, tmp_path):
+ target = tmp_path / "wrolpi"
+ target.mkdir()
+ (target / "stray.txt").write_bytes(b"hello")
+ result = check_shadowed_data(str(target))
+ assert result == {"size_bytes": 5, "entries": ["stray.txt"]}
+
+ def test_sums_sizes_across_multiple_entries(self, tmp_path):
+ target = tmp_path / "wrolpi"
+ target.mkdir()
+ (target / "config").mkdir() # ignored
+ (target / "videos").mkdir()
+ (target / "videos" / "a.mp4").write_bytes(b"x" * 200)
+ (target / "videos" / "b.mp4").write_bytes(b"x" * 300)
+ (target / "zims").mkdir()
+ (target / "zims" / "z.zim").write_bytes(b"x" * 500)
+ result = check_shadowed_data(str(target))
+ assert result["size_bytes"] == 1000
+ assert result["entries"] == ["videos", "zims"]
+
+
diff --git a/controller/test/test_disks_api.py b/controller/test/test_disks_api.py
index 8107578c..977cf909 100644
--- a/controller/test/test_disks_api.py
+++ b/controller/test/test_disks_api.py
@@ -74,6 +74,39 @@ class TestMountEndpoint:
)
assert response.status_code == 500
+ def test_shadowed_data_soft_blocks_mount(self, test_client):
+ """Existing data at the mount target soft-blocks the mount."""
+ shadowed = {"size_bytes": 1024, "entries": ["videos"]}
+ with mock.patch("controller.api.disks.check_shadowed_data", return_value=shadowed), \
+ mock.patch("controller.api.disks.mount_drive") as mock_mount:
+ response = test_client.post(
+ "/api/disks/mount",
+ json={"device": "/dev/sda1", "mount_point": "/media/test"},
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data["success"] is False
+ assert data["needs_force"] == "shadowed"
+ assert data["shadowed_data"] == shadowed
+ mock_mount.assert_not_called()
+
+ def test_force_shadowed_overrides_soft_block(self, test_client):
+ """force_shadowed=True bypasses the shadowed-data check."""
+ with mock.patch("controller.api.disks.check_shadowed_data", return_value={"size_bytes": 1, "entries": ["a"]}) as mock_check, \
+ mock.patch("controller.api.disks.mount_drive", return_value={"success": True, "mount_point": "/media/test"}):
+ response = test_client.post(
+ "/api/disks/mount",
+ json={
+ "device": "/dev/sda1",
+ "mount_point": "/media/test",
+ "force_shadowed": True,
+ },
+ )
+ assert response.status_code == 200
+ assert response.json()["success"] is True
+ # Check skipped entirely when force is set.
+ mock_check.assert_not_called()
+
class TestUnmountEndpoint:
"""Tests for /api/disks/unmount endpoint."""
diff --git a/controller/test/test_onboarding.py b/controller/test/test_onboarding.py
index e372885e..6d8b7cbb 100644
--- a/controller/test/test_onboarding.py
+++ b/controller/test/test_onboarding.py
@@ -2,6 +2,7 @@
Unit tests for onboarding orchestration logic.
"""
+import contextlib
from pathlib import Path
from unittest import mock
@@ -278,8 +279,12 @@ class TestCommitOnboarding:
assert str(media_dir) in result["mounts"]
assert result["repair_started"] is True
- def test_fresh_drive_with_force(self, mock_docker_mode, tmp_path):
- """Fresh drive with force=True should succeed."""
+ def test_fresh_drive_proceeds(self, mock_docker_mode, tmp_path):
+ """A fresh drive with no config on it still mounts cleanly.
+
+ The probe + UI button copy is the user-facing gate for the "no config"
+ case; the backend does not enforce its own check.
+ """
media_dir = tmp_path / "wrolpi"
with mock.patch("controller.lib.onboarding.get_media_directory", return_value=media_dir), \
@@ -289,7 +294,7 @@ class TestCommitOnboarding:
mock.patch("controller.lib.onboarding.reload_config_from_drive", return_value=False), \
mock.patch("controller.lib.onboarding.save_config"), \
mock.patch("controller.lib.onboarding.start_script", return_value={"success": True}):
- result = commit_onboarding("/dev/sda1", "ext4", force=True)
+ result = commit_onboarding("/dev/sda1", "ext4")
assert result["success"] is True
assert result["repair_started"] is True
@@ -437,3 +442,77 @@ class TestCancelProbe:
assert result["success"] is True
mock_cleanup.assert_called_once()
+
+
+class TestCommitOnboardingShadowedData:
+ """Tests for commit_onboarding's shadowed-data soft-block."""
+
+ def _patched_mount_calls(self, media_dir):
+ return [
+ mock.patch("controller.lib.onboarding.get_media_directory", return_value=media_dir),
+ mock.patch("controller.lib.onboarding._cleanup_temp_mount"),
+ mock.patch("controller.lib.onboarding.mount_drive", return_value={"success": True}),
+ mock.patch("controller.lib.onboarding.add_fstab_entry", return_value={"success": True}),
+ mock.patch("controller.lib.onboarding.reload_config_from_drive", return_value=False),
+ mock.patch("controller.lib.onboarding.save_config"),
+ mock.patch("controller.lib.onboarding.start_script", return_value={"success": True}),
+ ]
+
+ def test_empty_target_proceeds(self, mock_docker_mode, tmp_path):
+ """Empty target → no shadow block → mount proceeds."""
+ media_dir = tmp_path / "wrolpi"
+ media_dir.mkdir()
+
+ with contextlib.ExitStack() as stack:
+ for p in self._patched_mount_calls(media_dir):
+ stack.enter_context(p)
+ result = commit_onboarding("/dev/sda1", "ext4")
+
+ assert result["success"] is True
+ assert "needs_force" not in result or result.get("needs_force") is None
+
+ def test_config_only_target_proceeds(self, mock_docker_mode, tmp_path):
+ """A target containing only `config/` is the expected pre-mount state."""
+ media_dir = tmp_path / "wrolpi"
+ media_dir.mkdir()
+ (media_dir / "config").mkdir()
+ (media_dir / "config" / "ssl.crt").write_text("cert")
+
+ with contextlib.ExitStack() as stack:
+ for p in self._patched_mount_calls(media_dir):
+ stack.enter_context(p)
+ result = commit_onboarding("/dev/sda1", "ext4")
+
+ assert result["success"] is True
+
+ def test_shadowed_data_blocks_without_force(self, mock_docker_mode, tmp_path):
+ """A target with non-config data should soft-block."""
+ media_dir = tmp_path / "wrolpi"
+ media_dir.mkdir()
+ (media_dir / "videos").mkdir()
+ (media_dir / "videos" / "movie.mp4").write_bytes(b"x" * 1024)
+
+ with contextlib.ExitStack() as stack:
+ for p in self._patched_mount_calls(media_dir):
+ stack.enter_context(p)
+ result = commit_onboarding("/dev/sda1", "ext4")
+
+ assert result["success"] is False
+ assert result["needs_force"] == "shadowed"
+ assert result["shadowed_data"]["entries"] == ["videos"]
+ assert result["shadowed_data"]["size_bytes"] == 1024
+ assert result["mounts"] == []
+
+ def test_force_shadowed_proceeds(self, mock_docker_mode, tmp_path):
+ """force_shadowed=True overrides the soft-block."""
+ media_dir = tmp_path / "wrolpi"
+ media_dir.mkdir()
+ (media_dir / "videos").mkdir()
+ (media_dir / "videos" / "movie.mp4").write_bytes(b"x" * 1024)
+
+ with contextlib.ExitStack() as stack:
+ for p in self._patched_mount_calls(media_dir):
+ stack.enter_context(p)
+ result = commit_onboarding("/dev/sda1", "ext4", force_shadowed=True)
+
+ assert result["success"] is True
diff --git a/controller/test/test_onboarding_api.py b/controller/test/test_onboarding_api.py
index 718a8c37..39e905ce 100644
--- a/controller/test/test_onboarding_api.py
+++ b/controller/test/test_onboarding_api.py
@@ -152,6 +152,50 @@ class TestOnboardingCommitEndpoint:
)
assert response.status_code == 500
+ def test_commit_shadowed_data_returns_structured_block(self, test_client):
+ """Shadowed-data soft-block returns 200 with needs_force=shadowed."""
+ with mock.patch(
+ "controller.api.onboarding.commit_onboarding",
+ return_value={
+ "success": False,
+ "needs_force": "shadowed",
+ "shadowed_data": {"size_bytes": 1024, "entries": ["videos"]},
+ "error": "Existing data",
+ "mounts": [],
+ "repair_started": False,
+ },
+ ):
+ response = test_client.post(
+ "/api/onboarding/commit",
+ json={"device_path": "/dev/sda1", "fstype": "ext4"},
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data["success"] is False
+ assert data["needs_force"] == "shadowed"
+ assert data["shadowed_data"] == {"size_bytes": 1024, "entries": ["videos"]}
+
+ def test_commit_forwards_force_shadowed(self, test_client):
+ """force_shadowed is forwarded to commit_onboarding."""
+ with mock.patch(
+ "controller.api.onboarding.commit_onboarding",
+ return_value={"success": True, "mounts": [], "repair_started": False},
+ ) as mock_commit:
+ response = test_client.post(
+ "/api/onboarding/commit",
+ json={
+ "device_path": "/dev/sda1",
+ "fstype": "ext4",
+ "force_shadowed": True,
+ },
+ )
+ assert response.status_code == 200
+ mock_commit.assert_called_once_with(
+ device_path="/dev/sda1",
+ fstype="ext4",
+ force_shadowed=True,
+ )
+
class TestOnboardingCancelEndpoint:
"""Tests for POST /api/onboarding/cancel."""