How the docker-icloudpd Failsafe Prevents Data Loss from Unmounted Volumes

The docker-icloudpd failsafe prevents data loss by requiring a sentinel file (.mounted) in the download directory before executing any sync operations, ensuring writes occur only to properly mounted volumes rather than the container's root filesystem.

The docker-icloudpd container by boredazfcuk synchronizes iCloud photos to a local bind-mounted host directory. Without protection, an unmounted volume could cause the application to write data directly to the container's root filesystem, rapidly consuming host disk space and risking catastrophic data loss. The docker-icloudpd failsafe feature solves this by implementing a mandatory sentinel file check that gates all download operations behind volume verification.

How the Failsafe Mechanism Works

The failsafe centers on the check_mount() function in sync-icloud.sh (lines 639–669), which verifies volume availability before every sync cycle.

The Sentinel File Verification

At the start of each synchronization, the script checks for the presence of ${download_path}/.mounted:

# sync-icloud.sh – check_mount function

check_mount()
{
    log_info "Check download directory mounted correctly..."
    if [ ! -f "${download_path}/.mounted" ]; then
        log_warning "Failsafe file ${download_path}/.mounted file is not present. Waiting for failsafe file to be created..."
        local counter="0"
    fi
    while [ ! -f "${download_path}/.mounted" ]; do
        sleep 5
        counter=$((counter + 1))
        if [ "${counter}" -eq 360 ]; then
            log_error "Failsafe file has not appeared within 30 minutes. Restarting container..."
            exit 1
        fi
    done
    log_info "Failsafe file ${download_path}/.mounted exists, continuing"
}

If the sentinel file is missing, the script enters a retry loop with the following behavior:

• Immediate pause: The script waits indefinitely in 5-second intervals
• 30-minute timeout: After 360 attempts (30 minutes), the container exits with status 1
• Complete write prevention: No icloudpd download commands execute until the check passes

Configuration Requirements

As documented in CONFIGURATION.md under the FAILSAFE FEATURE section, the sentinel file must be created manually on the host filesystem. The container will not start syncing until this file exists.

The documentation explicitly states: "The container will look for a file called '/home/${user}/iCloud/.mounted' (please note the capitalisation of iCloud) in the download destination directory inside the container. If this file is not present, it will not download anything from iCloud." This requirement ensures that sync operations cannot proceed on an unverified filesystem.

Runtime Behavior and Failure Scenarios

When properly configured, the failsafe operates transparently during normal operations. However, it provides critical protection during infrastructure failures:

1. Initial startup: The container waits at check_mount() until the administrator creates the .mounted file
2. During operation: If the underlying disk detaches or the bind mount fails, the sentinel file disappears from the container's perspective
3. Failure detection: The next sync cycle detects the missing file and pauses execution
4. Graceful termination: If the mount remains unavailable for 30 minutes, the container exits rather than writing to the root filesystem

Why This Prevents Catastrophic Data Loss

The docker-icloudpd failsafe protects against three specific failure modes:

• Stray write prevention: All download operations use --directory ${download_path} only after check_mount() succeeds, guaranteeing the target path resides on the mounted volume
• Root filesystem protection: By exiting before any download attempts when the sentinel is missing, the container avoids filling the host's root partition—a common failure mode when bind mounts silently fail
• Administrative recovery window: The 30-minute timeout provides adequate time for administrators to re-mount the volume and recreate the sentinel file without immediate data corruption

Implementation Example

To implement the failsafe on a new installation, create the sentinel file on the host before starting the container:

# Create the download directory and sentinel file

sudo mkdir -p /home/bob/iCloud
sudo touch /home/bob/iCloud/.mounted

Verify the failsafe is active in container logs:

docker logs icloudpd_container 2>&1 | grep -i mounted

# Expected output when functioning correctly:

# 2026-02-26 12:00:00 INFO     Failsafe file /home/bob/iCloud/.mounted exists, continuing

Simulate a mount failure to observe the protection mechanism:

# Unmount the host directory

sudo umount /home/bob/iCloud

# Monitor logs for the timeout behavior

docker logs icloudpd_container 2>&1 | grep -E "(WARNING|ERROR)"

# Output after ~30 minutes:

# 2026-02-26 12:30:00 ERROR    Failsafe file has not appeared within 30 minutes. Restarting container...

Summary

• The docker-icloudpd failsafe requires a .mounted sentinel file in the download directory before executing any write operations
• The check_mount() function in sync-icloud.sh implements a retry loop with a 30-minute timeout to detect unmounted volumes
• If the sentinel file disappears (indicating volume unavailability), the container pauses sync and ultimately exits to prevent writing to the container root filesystem
• Administrators must manually create the sentinel file once per volume as documented in CONFIGURATION.md

Frequently Asked Questions

What is the docker-icloudpd failsafe feature?

The docker-icloudpd failsafe is a mandatory safety mechanism that prevents the application from downloading photos when the target volume is not properly mounted. It requires a sentinel file (.mounted) to exist in the download directory before any filesystem writes occur, protecting the host from data loss if the bind mount fails or the underlying disk becomes unavailable.

How do I create the required .mounted sentinel file?

Create an empty file named .mounted in the root of your download directory on the host filesystem. For example, if your download path is /home/bob/iCloud, run sudo touch /home/bob/iCloud/.mounted before starting the container. This file must persist on the mounted volume itself, not in the container layer, so that it disappears if the mount fails.

What happens if the volume becomes unmounted during a sync?

If the volume becomes unmounted while the container is running, the .mounted file disappears from the container's perspective. The next time check_mount() executes (at the start of each sync cycle), the script pauses for 5-second intervals. If the file does not reappear within 30 minutes (360 attempts), the container exits with status 1 to prevent writes to the root filesystem.

Can I disable the docker-icloudpd failsafe feature?

No, the failsafe is a mandatory safety feature hard-coded into sync-icloud.sh. There is no configuration environment variable or flag to disable the check_mount() function. The sentinel file must exist for the container to function, ensuring that accidental unmounts never result in data being written to the container's ephemeral storage and filling the host's root partition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}