The Sync Script That Corrupted Its Own Backup

max@bonnef.in (Max Bonnefin) — Sun, 04 Oct 2026 00:00:00 +0000

Back in 2019 I built an 800GB iPod and, pleased with myself, published the little script I used to keep it in sync with my laptop. Seven years later that script had quietly eaten a chunk of my music library and I only noticed when the iPod refused to boot.

How a sync script corrupts the thing it’s backing up Link to heading

After years in my pocket, one of the microSD cards in the iFlash-Quad started returning bad bytes on reads: not errors that rsync would notice, just garbage and zero-length files handed back as if they were real. The adapter was fine. Flash cards simply wear out, and this one had. A read error would have been fine, rsync would have stopped. Silent corruption is the dangerous kind, because every tool in the chain treats the garbage as legitimate data.

The original 2019 script ran rsync --ignore-existing in both directions, library to iPod and iPod back to library. Once the card started handing back corrupt reads, the iPod-to-library pass copied that corruption straight over the good originals on my laptop. Every subsequent run propagated it further.

--ignore-existing is what made it invisible. The flag skips any file already present on the destination, which sounds safe until you realise a file full of zeroes is still present. Once a track was corrupted on the laptop, rsync saw a filename that existed and skipped it from then on. The good copy was gone and nothing would ever overwrite it. The corruption had been seeping outward for a long time before the iPod finally wouldn’t boot, which meant the copies I thought of as backups had been absorbing it too.

Direction isn’t the fix. Verification is. Link to heading

The tempting conclusion is to make the sync strictly one-way: library to iPod, never the reverse, with the laptop as the source of truth. That does stop a failing iPod from poisoning the master, and if all you want is a disposable mirror it’s enough.

It also throws away something I actually use. A two-way sync lets either device hold tracks the other is missing, which is handy when I add music on the go or rip something on the laptop. The reason two-way was dangerous in 2019 wasn’t the second direction. It was that nothing checked whether the bytes being copied were real.

So the script I run now is still two-way. It’s safe because every audio file is decode-verified before it’s allowed to move, in both directions. If a file doesn’t decode, it’s corrupt, and corrupt files are skipped and logged rather than copied over anything.

verify_rel() {
 local src=$1 rel=$2
 if is_rockbox "$rel"; then printf '%s\0' "$rel"; return; fi # .rockbox exempt
 if ! is_audio "$rel"; then printf '%s\0' "$rel"; return; fi # non-audio copied as-is
 if [ -s "$src/$rel" ] && \
 ffmpeg -v error -i "$src/$rel" -map 0:a -c:a pcm_s16le -f null - >/dev/null 2>&1
 then
 printf '%s\0' "$rel"
 else
 printf 'CORRUPT, skipped: %s\n' "$rel" >> "$CORRUPTLOG"
 fi
}

ffmpeg -f null decodes the audio stream and discards the output.¹ It’s the cheapest way to ask “would this file actually play?” without writing anything. A zero-byte FLAC fails. A track read through a flaky contact fails. Only files that fully decode make it onto the approved list, and that list is the only thing rsync is allowed to touch:

rsync -rt --from0 --files-from="$approved" \
 --ignore-existing --no-perms --no-owner --no-group \
 "$src/" "$dst/"

What makes the two-way version safe where the 2019 one was lethal comes down to a few deliberate choices.

Verification gates every copy. This is the one that matters. A corrupt read never reaches the other side, so neither copy can poison the other no matter which direction the sync runs. It’s the check that would have caught the degrading card straight away.

To be precise about what that check buys you: a decode pass proves a file still plays end to end, not that it’s bit-for-bit what it was when you ripped it. It catches the failures that actually bit me, zero-byte files and garbled reads that fail to decode at all, but a subtle glitch buried mid-stream can still decode cleanly and slip through. It’s a liveness check, not a cryptographic one. If you want true integrity you keep checksums from the moment of ripping and compare against those. For catching a dying card handing back rubbish, decode-verification is enough.

Nothing is ever overwritten or deleted. --ignore-existing means a file that already exists is left alone, and there’s no --delete anywhere. The sync only ever adds files that are missing from one side. That has a deliberate limitation: if I edit a track in place, re-tag it or re-encode it, the other side keeps the old copy, because the path still exists and existing files are never touched. The script doesn’t try to detect or reconcile that. Working out which of two same-path files is the “right” one would mean reading the whole device back on every run to catch a case I create by hand and already know about. An automatic resolver is also just another way to let bad data win silently. If I change a file in place I delete the stale copy and let the next sync re-add it.

The removable device is mounted and unmounted by the script itself, located by label and falling back to UUID, and it refuses to run if something that isn’t the iPod is mounted at the target path. The 2019 script assumed the mount was already there and correct, which is how an unmounted target quietly becomes a write into a bare directory on your root filesystem.

The verification pass runs in parallel across cores, because decoding an entire library serially is painfully slow. The full script, with the mounting, the parallel verification and the ownership fixes, is on GitLab. I’m publishing it because the approach is worth stealing, not as something you should run unexamined against your only copy of anything. It’s wired to my hardware, my mount points and my tolerance for risk. Read it, understand the direction of trust, and adapt it. The snippets above are the parts that carry the argument.

Reflashing the iPod firmware on Linux, without iTunes Link to heading

Rebuilding the iPod meant repartitioning the microSD cards from scratch, which wiped the firmware partition along with everything else. Rockbox then refused to install.

Rockbox installs its bootloader alongside the Apple firmware, so it needs that firmware present. The usual answer is to restore the iPod with iTunes first. The entire point of this project, since 2019, has been never touching iTunes, plus is iTunes even still a thing in 2026? So the question was whether a 5.5G iPod can be reflashed on Linux alone.

Fortunately it can. The firmware images Apple shipped are plain .ipsw files, which are just ZIP archives, and the iPod will reflash itself from the right payload with no Apple software involved.

Get the correct image for the board. For the 5.5G family it’s iPod_25.1.3.ipsw: the 25 is Apple’s internal model identifier for this iPod rather than a version number, with the actual software version being 1.3.²
unzip the archive and locate the Firmware-* payload inside.
dd that payload directly onto the iPod’s firmware partition.
Unplug the iPod. It detects the fresh image and self-reflashes: Apple logo, progress bar, then a reboot into the Apple OS, which rewrites the firmware partition in the format it expects.
Rockbox’s installer now sees a valid Apple firmware and installs the bootloader. Dual-boot restored.

The self-reflash in step four is the interesting bit. The iPod does the real work itself once it finds a valid image on the partition; iTunes was only ever the thing that put the image there. I assume this is roughly what the official restore does under the hood, though I haven’t disassembled the Apple updater to confirm it. Either way you don’t need iTunes to trigger it, which is a fitting ending for a project built on avoiding iTunes in the first place.

What it cost me Link to heading

The music is back on the iPod. I rebuilt the library from the least-corrupted sources I could find, re-ripped what I still had on disc, and reacquired cough cough the rest. The one failed card went in the bin awaiting its replacement; the iFlash-Quad and the other three cards carried on fine.

The lesson isn’t “test your backups”, though that’s true. It’s narrower: a copy your tooling trusts without checking isn’t a backup, it’s a liability waiting for the first bad read. Direction, retention, delete flags, all of that is secondary. If the bytes aren’t verified before they’re trusted, the rest is decoration. My 2019 self got that backwards and published the mistake. If you copied that old script you probably want to update it.

The -f null muxer writes decoded frames to nowhere, so the whole file is read and decoded with the output thrown away. Pair it with -v error and a non-zero exit means at least one frame failed to decode. It’s the standard trick for a quick “does this media file actually decode?” check without producing a file. ↩︎
Confirmed against the Apple Wiki iPod firmware list. The iPod_25.* naming runs across every 5.5G release, with the trailing numbers (1.3) being the user-facing software version. The 25 identifies the hardware, not the firmware revision, which is why it never changes between versions. ↩︎

Backup on Max Bonnefin

The Sync Script That Corrupted Its Own Backup

How a sync script corrupts the thing it’s backing up Link to heading

Direction isn’t the fix. Verification is. Link to heading

Reflashing the iPod firmware on Linux, without iTunes Link to heading

What it cost me Link to heading