USB Storage

USB Storage

Crow can use an external USB drive for persistent message, image, and Winlink form storage. This is useful on AREDN nodes with limited internal flash, or when you want messages and images to survive firmware upgrades.

Note: Not all AREDN nodes have a USB port. Crow detects this automatically and will report "no port on this device" if USB is unavailable.

---

Prerequisites

Before using USB storage commands, the node needs USB kernel modules installed. Crow ships a setup script that handles this:

ssh -p 2222 root@<node-ip>
sh /usr/local/raven/platforms/aredn/usb-setup.sh

Setup options

Command	Description
sh usb-setup.sh	Install USB packages only
sh usb-setup.sh format	Install packages + format first USB drive as ext4
sh usb-setup.sh format sda1	Install packages + format /dev/sda1 as ext4

The setup script:

1. Installs USB storage kernel modules (kmod-usb-storage, kmod-fs-ext4, etc.)
2. Installs DWC3 controller drivers if needed (IPQ40xx / Qualcomm SoCs)
3. Detects attached USB drives
4. Optionally formats a drive with the CROWDATA label

The script is safe to re-run — already-installed packages are skipped.

---

Slash Commands

All USB storage management is done through /storage commands in the Crow message composer.

/storage status

Show the current storage state including mode, root path, image directory, and USB availability.

Example output:

Crow storage: usb
Mode: usb
Root: /mnt/crow
Images: /mnt/crow/images
Mountpoint: /mnt/crow

If USB was configured but the drive is missing, status will show degraded with a reason explaining why, and note that the service is running from internal node storage.

/storage usb scan

Scan for removable USB storage devices attached to the node. Lists each candidate with its device path, model name, size, and whether it is currently mounted.

Example output:

USB storage candidates:

/dev/sda1 USB Flash Drive 14.4 GB [mounted]

/storage usb enable

Mount and activate USB storage. Crow will:

1. Scan for removable USB drives
2. Mount the first candidate at /mnt/crow
3. Create the required directory structure (data/, images/, winlink/forms/)
4. Migrate existing messages and images from internal storage to USB
5. Report success or a reason for failure

If a drive is already mounted, Crow activates it immediately.

/storage usb disable

Return to internal node storage. The USB drive remains mounted but Crow stops using it for new data. Existing data on the USB drive is not deleted.

/storage quota images <mb>

Set the image storage quota in megabytes (1–65536 MB). When the total size of stored images exceeds the quota, the oldest images are pruned automatically.

Example:

/storage quota images 128

---

Storage Modes

Mode	Description
internal	Messages stored on the node's internal flash (/usr/local/crow)
usb	Messages and images stored on the USB drive (/mnt/crow)
degraded	USB was configured but is unavailable; falls back to internal storage

---

Configuration

USB storage can also be pre-configured in crow.conf.override. See Configuration — USB Storage for the complete configuration reference and all available options. | image_quota_mb | 64 | Maximum MB for image storage | | min_free_mb | 16 | Minimum free space required on the drive |

---

Data Migration

When USB storage is first enabled, Crow automatically copies existing data from internal storage to the USB drive:

• Message data (/usr/local/crow/data/ → /mnt/crow/data/)
• Images (/tmp/apps/crow/images/ → /mnt/crow/images/)
• Winlink forms (/usr/local/crow/winlink/forms/ → /mnt/crow/winlink/forms/)

Only missing files are copied — existing files on the USB drive are not overwritten.

---

Degraded Mode

Crow periodically verifies that the USB volume is mounted, writable, and has enough free space. If the check fails, the platform switches to degraded mode:

• The core service remains running.
• The user is alerted that storage is degraded.
• Temporary fallback storage is used under /tmp/apps/crow/degraded.
• Image uploads fall back to /tmp/apps/crow/images.

This protects the node from a hard failure when a USB stick is removed, fails, or fills up. Crow will continue operating from internal storage and clearly report that persistence is degraded until the external storage is restored.

Check	Interval	Action on failure
Mount / writable	~1 minute	Switch to degraded, alert user
Free space ≥ min_free_mb	~1 minute	Switch to degraded, alert user
Image quota	~5 minutes	Prune oldest images until under quota

To recover from degraded mode, fix the USB issue (replug, check filesystem) and run /storage usb enable again.

---

Storage Layout

When USB storage is healthy, Crow uses:

Path	Purpose
/mnt/crow/data	JSON state, message stores, node database, platform data
/mnt/crow/winlink/forms	Winlink and form storage
/mnt/crow/images	Persistent uploaded images

The Crow runtime, package files, and minimal configuration remain on internal node storage. Do not move the Crow core application files to the USB drive — external storage is only the data layer.

---

Operator Notes

• External storage should only be used as the data layer. The Crow core should remain on the node.
• If external storage is not available, Crow keeps running from internal storage and clearly reports degraded persistence.
• The image cleanup policy removes the oldest files first and only acts inside the Crow-managed image directory.