1
0
Fork 0
mirror of https://git.anardil.net/austin/timemachine.git synced 2026-11-21 11:00:09 +00:00
Lists and restores files from Time Machine sparsebundle backups without a Mac, for FreeBSD
  • Haskell 99.5%
  • C 0.3%
  • Makefile 0.2%
Find a file
Gandalf- 0cd92152e3 timemachine: a README for strangers, and no private hosts, for the public mirror
The README says why tm exists, how to build it, and what it reads, and
walks through a restore with placeholder paths. README, CLAUDE.md and the
haddocks name the Mac, the file server and the board card generically
instead of by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 12:47:19 -08:00
cbits timemachine: audit 2026-10-25; SIGHUP/SIGTERM remove a partial restore (#406) 2026-10-25 22:39:23 -07:00
src timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
test timemachine: lines are held to 100 columns by make lint (#456) 2026-11-06 13:09:09 -08:00
TimeMachine timemachine: a README for strangers, and no private hosts, for the public mirror 2026-11-11 12:47:19 -08:00
.gitignore timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
.hlint.yaml timemachine: never chown, restore hard links, README 2026-10-24 17:37:42 -07:00
CLAUDE.md timemachine: a README for strangers, and no private hosts, for the public mirror 2026-11-11 12:47:19 -08:00
hie.yaml timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
LICENSE timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
Makefile timemachine: lines are held to 100 columns by make lint (#456) 2026-11-06 13:09:09 -08:00
README.md timemachine: a README for strangers, and no private hosts, for the public mirror 2026-11-11 12:47:19 -08:00
stack.yaml timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
stack.yaml.lock timemachine: read Time Machine sparsebundles without a Mac 2026-10-23 18:44:18 -07:00
timemachine.cabal timemachine: audit 2026-10-25; SIGHUP/SIGTERM remove a partial restore (#406) 2026-10-25 22:39:23 -07:00

tm

Gets files back out of a Mac's Time Machine backups without a Mac.

Time Machine on a network share writes its backups as a sparsebundle: a directory of "band" files holding an APFS disk image, with one APFS snapshot per backup. Off a Mac, nothing reads them well. libmodi reads zeros from v2 bundles, libfsapfs has no snapshots, and apfs-fuse doesn't support sparsebundles. tm reads the bundle directly, on FreeBSD or macOS, including the decmpfs compression APFS uses (zlib, LZVN, LZFSE, LZBITMAP), decoded in pure Haskell.

It only ever reads the backup, and it never replaces anything at the destination.

tm snapshots BUNDLE
tm ls        BUNDLE SNAPSHOT [PATH]
tm restore   BUNDLE SNAPSHOT PATH DEST

Building

With Stack:

make release      # optimized build, installed to ~/.local/bin/tm

Restoring a file

Time Machine rewrites the bundle every hour, and file data in APFS has no checksum, so read a snapshot of the bundle rather than the live copy. On ZFS:

zfs snapshot pool/timemachine@restore
b=/pool/timemachine/.zfs/snapshot/restore/MyMac.sparsebundle

Pick a backup. latest is the newest, or give any unique part of a name, such as a date (2026-10-23):

tm snapshots "$b"

Find the file. A backup's files are under /<date>.backup/Data/, laid out like the Mac's disk:

tm ls "$b" latest /
d=/2026-10-23-101500.backup/Data   # the .backup name the line above printed
tm ls "$b" latest "$d/Users/alice"

Restore a file or a whole directory. DEST must not exist yet, and as root it should be somewhere only root can write (not /tmp), since the path to it is followed:

mkdir -m 700 /root/restore
tm restore "$b" latest "$d/Users/alice/notes.txt" /root/restore/notes.txt

When you're done, drop the snapshot:

zfs destroy pool/timemachine@restore

What comes back

  • Files, directories, symlinks, modes and modification times. Sparse files stay sparse. A file with several names comes back hard linked between the names inside what you restored; names outside it aren't followed.
  • Everything belongs to whoever ran tm (often root). setuid and setgid bits are dropped, and so is the sticky bit on files. chown -R it to whoever it's for.
  • Not restored: Finder tags and other extended attributes, ACLs, resource forks.
  • tm restore names on stderr each file it couldn't restore, and then exits 1; the rest is still restored. A file compressed with a method newer than LZBITMAP (macOS 27 adds some) is skipped this way.
  • A name that couldn't be hard linked to the others is copied instead, with a warning: line saying so; that alone still exits 0.
  • Interrupted (Ctrl-C, a dropped ssh session, kill), it removes the file it was writing and exits nonzero; what it finished stays, its directories still mode 700. Restore again into a new DEST. Only kill -9 leaves a partial file, mode 0600. Under nohup, a dropped session doesn't stop it.
  • A name with accents has to be typed exactly as the Mac stored it. If it isn't found, copy it from the tm ls output, or restore its directory.

What it reads

v1 and v2 sparsebundles holding one unencrypted APFS volume, either bare (as Time Machine writes them) or in a GPT partition map (as hdiutil does). Encrypted backups, mounting, and writing to the bundle are deliberately out of scope.

Development

make ready        # format, lint, test
make fixture      # macOS only: rebuild the test disk image from scratch

The tests run against a small APFS sparsebundle built on a Mac by test/fixtures/make-fixture.sh. CLAUDE.md covers the on-disk format as measured, and the invariants the code is held to.

License

BSD 3-Clause; see LICENSE.