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

> Learn how the docker-icloudpd failsafe prevents data loss by verifying volume mounts with a sentinel file before syncing data. Keep your iCloud data safe and secure.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`:

```bash

# 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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:

```bash

# 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:

```bash
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:

```bash

# 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.