How to Manage an SD Storage on EndianOS

How It Works

The EndianOS External Storage system automatically manages SD cards to extend your appliance's storage capacity. Here's how it works from a user's perspective:

What Happens When You Insert an SD Card

1. Automatic Detection: When you insert an SD card into the appliance's SD card slot, the system automatically detects it using built-in rules that identify storage devices.
2. Device Validation: The system checks if the device is valid by:
   • Verifying the device has actual storage capacity (not empty or corrupted)
   • Ensuring it's a recognized storage device type
3. Filesystem Check: The system examines the storage device to see if it has a compatible filesystem (ext4). If the filesystem is damaged, it attempts to repair it automatically.
4. Formatting (if needed): If the device is empty or has an incompatible filesystem, the system can automatically format it with a proper ext4 filesystem (if auto-format is enabled).
5. Mounting: The device gets mounted to a secure location in /run/efw-storage/ using a unique identifier (UUID) to prevent conflicts.
6. Service Integration: The system then creates "bind mounts" that make the external storage appear as if it's part of your appliance's main storage for specific services like Docker, logs, or backups.

Visual Flow

Insert SD Card into Slot

     ↓

System Detects SD Card

     ↓

Check SD Card Validity

     ↓

Examine Filesystem

     ↓

[If needed] Format as ext4

     ↓

Mount to /run/efw-storage/UUID

     ↓

Create Service Bind Mounts

     ↓

Services Can Use Extended Storage

Storage Locations

Where Your Data Goes

• External Storage Mount: /run/efw-storage/[UUID]/
• Service Directories: Each service gets its own subdirectory
  • Docker data: /run/efw-storage/[UUID]/docker/

What Services Can Use External Storage

The system can extend storage for:

• Docker containers and images

How Services Use External Storage

The system automatically maps services to external storage based on configuration files:

• Device Configuration: Defines which SD card to use
• Service Mapping: Links the SD card to specific services (Docker, logs, backups)
• Service Definitions: Specifies which directories each service needs

Monitoring and Maintenance

Check Storage Usage

# See how much space is used on external storage

df -h /run/efw-storage/*

# Check specific service directories

du -sh /run/efw-storage/*/docker

du -sh /run/efw-storage/*/logs

View System Logs

# Check storage service logs

journalctl -u efw-mount-ext-storage.service

# Follow logs in real-time

journalctl -u efw-mount-ext-storage.service -f

Replacing Storage Devices

Safe SD Card Replacement

When you need to replace an SD card, follow these steps:

Step 1: Power Down the Appliance

1. Turn off the appliance completely
2. Wait for the system to shut down completely

Step 2: Copy Content from Old SD Card

1. Remove the old SD card from the appliance's SD card slot carefully
2. Insert the old SD card into your Linux host computer
3. Copy the entire content including hidden files:

# Create a backup of the entire SD card content (including hidden files)

tar -czf sd-card-backup.tar.gz -C /media/sd-card/ .

Step 3: Format New SD Card

1. Insert the new SD card into your Linux host computer
2. Format the new SD card with ext4:

# Find the SD card device (usually /dev/sdb or /dev/mmcblk0)

lsblk

# Format the SD card with ext4 (replace /dev/sdX with your device)

sudo mkfs.ext4 -F /dev/sdX

# Mount the formatted SD card

sudo mkdir -p /media/new-sd-card

sudo mount /dev/sdX /media/new-sd-card

Step 4: Restore Content to New SD Card

1. Copy the full content including hidden files:

# Restore the backup to the new SD card (including hidden files)

tar -xzf sd-card-backup.tar.gz -C /media/new-sd-card/

# Unmount the SD card

sudo umount /media/new-sd-card

Step 5: Install and Power On

1. Insert the new SD card into the appliance's SD card slot
2. Turn on the appliance
3. The system will automatically detect and mount the new SD card

Data Migration Between SD Cards

If you need to migrate data from one SD card to another:

Option 1: Backup and Restore (Recommended)

1. Power down the appliance and remove the old SD card
2. Insert the old SD card into your Linux host computer
3. Create backup including hidden files:

# Create a backup of the entire SD card content (including hidden files)

tar -czf old-sd-card-backup.tar.gz -C /media/sd-card/ .

1. Format the new SD card with ext4:

# Insert the new SD card into your host computer

# Find the SD card device

lsblk

# Format with ext4 (replace /dev/sdX with your device)

sudo mkfs.ext4 -F /dev/sdX

# Mount the formatted SD card

sudo mkdir -p /media/new-sd-card

sudo mount /dev/sdX /media/new-sd-card

1. Restore data:

# Restore the backup to the new SD card (including hidden files)

tar -xzf old-sd-card-backup.tar.gz -C /media/new-sd-card/

# Unmount the SD card

sudo umount /media/new-sd-card

1. Insert the new SD card into the appliance and power on

Option 2: Direct Copy (Advanced)

If you have both SD cards accessible on your Linux host computer:

1. Format the new SD card with ext4:

# Find the new SD card device

lsblk

# Format with ext4 (replace /dev/sdX with your device)

sudo mkfs.ext4 -F /dev/sdX

# Mount both SD cards

sudo mkdir -p /media/old-sd-card /media/new-sd-card

sudo mount /dev/sdY /media/old-sd-card  # old SD card

sudo mount /dev/sdX /media/new-sd-card  # new SD card

1. Copy the full content including hidden files:

# Copy the entire content from old to new (including hidden files)

cp -a /media/old-sd-card/* /media/new-sd-card/

cp -a /media/old-sd-card/.* /media/new-sd-card/ 2>/dev/null || true

# Unmount both SD cards

sudo umount /media/old-sd-card /media/new-sd-card

1. Insert the new SD card into the appliance and power on

Managing Storage Content

The system automatically manages which services use the SD card storage. You don't need to manually configure this - it's handled by the system through configuration files.

Monitoring Storage Usage

You can check how much space is being used:

# See storage usage

df -h /run/efw-storage/*

# Check specific service directories

du -sh /run/efw-storage/*/docker

Emergency Procedures

SD Card Failure Recovery

If your SD card fails:

1. Check system logs for error messages:

journalctl -u efw-mount-ext-storage.service --since "1 hour ago"

1. Verify device health:

# Check if device is still detected

lsblk

# Check filesystem health

fsck.ext4 -f /dev/mmcblk0p1

1. If SD card is recoverable:
   • Follow the replacement procedure above
   • Restore from backups if available
2. If SD card is not recoverable:
   • Services will fall back to internal storage
   • Replace SD card as soon as possible
   • Restore data from backups

Data Recovery

If you need to recover data from a damaged SD card:

1. Stop using the SD card immediately
2. Use data recovery tools:

# Try to recover filesystem

fsck.ext4 -y /dev/mmcblk0p1

# If that fails, try data recovery tools

photorec /dev/mmcblk0p1

1. Mount read-only if possible:

mount -o ro /dev/mmcblk0p1 /mnt/recovery

Best Practices

Device Selection

• Use high-quality SD cards
• Ensure adequate storage capacity for your needs
• Consider write endurance for frequently updated data

Configuration

• Test configurations with non-critical data first
• Keep backup copies of working configurations
• Document any custom service mappings

Maintenance

• Monitor storage usage regularly
• Replace devices before they reach capacity
• Keep system logs for troubleshooting

Security

• The system automatically handles security aspects
• External storage is isolated in /run/efw-storage/
• Service data is properly permissioned
• No manual security configuration is typically needed

Troubleshooting

Checking System Status

To verify that your SD card is working correctly, check the system logs:

# View the storage service logs

journalctl -u efw-mount-ext-storage.service

# Follow logs in real-time

journalctl -u efw-mount-ext-storage.service -f

Normal operation messages you should see:

Find device with rule: KERNEL=="mmcblk0",SUBSYSTEM=="block",ENV{DEVTYPE}=="disk"

udev device: /sys/devices/platform/fe330000.mmc/mmc_host/mmc0/mmc0:0001/block/mmcblk0

is_valid: True

check: True

Mounting /dev/mmcblk0p1 into /run/efw-storage/12345678-1234-1234-1234-123456789abc

Syncing content of /var/lib/docker into /run/efw-storage/12345678-1234-1234-1234-123456789abc/docker

Bind mounting /var/lib/docker into /run/efw-storage/12345678-1234-1234-1234-123456789abc/docker

What these messages mean:

• Device Found: The system found your SD card
• Valid: The device has proper storage capacity
• Check Passed: The filesystem is healthy
• Mounted: The device is now available for use
• Synced: Your service data is being copied to the external storage
• Bound: Services can now use the external storage transparently

SD Card Not Detected

Problem: Your SD card isn't being recognized

Check:

1. Is the SD card properly inserted into the SD card slot?
2. Is the SD card supported? (Check the udev rule in configuration)
3. Are there any hardware issues with the SD card slot?

Solution:

# Check if SD card is detected by the system

lsblk

# Check udev information

udevadm info --query=all --name=/dev/mmcblk0

Filesystem Errors

Problem: SD card is detected but filesystem is corrupted

What you'll see:

is_valid: True

check: False

initialized ok: True

What this means: The system detected the SD card, found filesystem problems, and automatically reformatted it.

Mount Failures

Problem: SD card is valid but won't mount

Common causes:

• SD card is already mounted elsewhere
• Insufficient permissions
• Mount point conflicts

Solution:

# Check current mounts

mount | grep efw-storage

# Check device usage

lsof /dev/mmcblk0p1

# Force unmount if needed

umount -f /run/efw-storage/[UUID]

Service Not Using SD Card Storage

Problem: Services are still using internal storage

Check:

1. Is the SD card properly mounted?
2. Is the service mapping correct?
3. Are the mount points properly configured?

Solution:

# Check if bind mounts are active

mount | grep bind

# Check service status

systemctl status [service-name]

This user manual provides a practical understanding of how the Endian Firewall External Storage system works from a user's perspective, focusing on what users need to know to effectively use and troubleshoot the system.