Since some of the more interesting features of Time Machine Server are gone, let’s talk about doing even more than what was previously available in that interface by using the command line to access Time Machine.
As with any other command, you should probably start by reading the man page. For Time Machine, that would be:
man tmutil
Sometimes, the incantation of the command you’re looking for might even be available at the bottom of the man page. Feel free to use the space bar a few times to skip to the bottom, or q to quit the man interface.
In addition to the man page, there’s a help command, which can be used in conjunction with any of the command verbs (which makes me think of “conjunction junction, what’s your function”). For example, you can tell tmutil to compare backups using the compare verb. To see more on the usage of the compare verb, use tmutil followed by compare (the verb, or action you wish the command to perform), followed by help:
/usr/bin/tmutil compare help
Before you start using Time Machine, you’ll want to set a backup source and destination. Before you do, check the destination that’s configured:
/usr/bin/tmutil destinationinfo
The output will include
Name: TimeMachineBackup
Kind: Network
URL: afp://;AUTH=No%20User%20Authent@MyCloud-YAZ616._afpovertcp._tcp.local/TimeMachineBackup
ID: 265438E6-73E5-48DF-80D7-A325372DAEDB
Once you’ve checked the destination, you can set a destination. For example, the most common destination will be something like /Volumes/mybackupdrive where mybackupdrive is a drive you plugged into your computer for Time Machine.
sudo /usr/bin/tmutil setdestination /Volumes/mybackupdrive
Once you’ve configured a destination for your backups, it’s time to enable Time Machine. The simplest verbs to use are going to be the enable and disable verbs, which you might guess turn Time Machine on and off respectively. For these, you’ll need elevated privileges. To turn Time Machine on:
sudo /usr/bin/tmutil enable
To then disable Time Machine:
sudo /usr/bin/tmutil disable
You can also kick off a backup manually. To do so, use the startbackup verb as follows:
sudo /usr/bin/tmutil startbackup
To see the status, once you’ve kicked off a backup (this one is gonna’ be hard to remember) use the status verb:
sudo /usr/bin/tmutil status
Or to stop a backup that is running (e.g. if your computer is running slowly and you think it’s due to a backup running), you’d use the stopbackup verb:
sudo tmutil stopbackup
Once backups are complete, you can see the directory they’re being stored in with the machinedirectory verb. This will become important when we go to view information about backups and compare backups, which require that directory to be available as those options check local files and databases for information directly. The tmutil verb to do that is machinedirectory:
sudo /usr/bin/tmutil machinebackup
Other options you can enable, include the ability to exclude files or directories from your backups. For example, you won’t likely want to backup your music or movies that were purchased on iTunes as they take up a lot of space and are dynamically restored from Apple in the event that such a restore is necessary. The verb to do so is addexclusion and this also requires sudo. So to exclude the user krypted’s ~/Music directory, you’d use a command as follows:
sudo /usr/bin/tmutil addexclusion /Users/krypted/Music
To then check if a directory is excluded, use the isexcluded verb and define the path:
sudo /usr/bin/tmutil isexcluded /Users/krypted/Music
If you make an errant exclusion do the opposite to remove, leveraging the removeexclusion verb:
/usr/bin/tmutil removeexclusion /Users/krypted/Music
Once a backup is complete, you can also check various information about the backups. This can be done using a few different verbs. One of the more common manual tasks that is run is listing the recent backups that can be restored. This is done using the listbackups verb with no operators (the backup directory needs to be available when run, so cd into that before using listbackups).
/usr/bin/tmutil listbackups
You can also view the latest backup, which can then be grabbed by your management tool, which is provided in the YYYY-MM-DD-HHMMSS format.
/usr/bin/tmutil latestbackup
You can also compare backups so you can see the files that have been changed, added, and removed, as well as the size of the drift between the two backups. To do so, use the compare verb and provide the paths between the two backups that were obtained when using the listbackups verb, as follows:
/usr/bin/tmutil compare “/Volumes/mybackupdrive/Backups.backupdb/Krypted/2018–04–24–051014” “/Volumes/mybackupdrive/Backups.backupdb/Krypted/2018–04–24–061015”
In the above paths, we’re using the mybackupdrive and krypted is the source volume name. You can also look at all of the backups (and potentially derive future space requirements based on a trend line) by using the calculatedrift verb:
/usr/bin/tmutil calculatedrift /Volumes/mybackupdrive/Backups.backupdb/Krypted
At times, you may end up replacing infrastructure. So you might move backups to a new location, or move backups to a new solution. You can use the inherent backups to claim a new machine directory. So if you moved your backups from /Volumes/mybackupdrive/Backups.backupdb/Krypted to /Volumes/mylargerbackupdrive/Backups.backupdb/Krypted during an upgrade you might run the following so you don’t have to start backing up all over again and end up wiping out your backup history:
/usr/bin/tmutil inheritbackup /Volumes/mylargerbackupdrive/Backups.backupdb/Krypted
Or if you have both available at once, use the associatedisk verb with the new volume followed by the old volume:
sudo /usr/bin/tmutil associatedisk "/Volumes/mylargerbackupdrive/Backups.backupdb/Krypted" "/Volumes/mybackupdrive/Backups.backupdb/Krypted"
Or if you do want to start over but want to clear out old backups, you can use the delete verb followed by the path to the backup or snapshot, as follows:
sudo /usr/bin/tmutil delete /Volumes/mybackupdrive/Backups.backupdb/Krypted
There are also a few more verbs available, mostly for apfs. The localsnapshot command creates new snapshots of APFS volumes, and is used with no operators, as follows:
sudo /usr/bin/tmutil localsnapshot
To then see the snapshots, use the listlocalsnapshots verb,
sudo /usr/bin/tmutil listlocalsnapshots
Which outputs as follows:
com.apple.TimeMachine.2018-04-20-061417
Or to constrain the output for easier parsing, use listlocalsnapshotdates:
sudo /usr/bin/tmutil listlocalsnapshotdates
Which outputs as follows
2018-04-20-061417
And you can delete a snapshot with the deletesnapshot
sudo tmutil deletelocalsnapshots 2018-04-20-061417
Now, thinning out your backups is always an interesting task. And in my experience your mileage may vary. Here, you can use the thinlocalsnapshots verb to prune the oldest data from backups. In the following example, we’re going to purge 10 gigs of data:
sudo /usr/bin/tmutil thinlocalsnapshots / 10000000000
Finally, let’s talk about automated restores. You could use this type of technology to do a rudimentary form of imaging or rolling users into a new machine. To restore a backup, you would use the (shocking here) restore verb. First, let’s look at restoring a single file. In the following example, we’ll restore a file called mysuperimportantfile from a computer called mycomputername and provide the date of the snapshot we’re restoring from:
sudo /usr/bin/tmutil restore /Volumes/mybackupdrive/Backups.backupdb/mycomputername/2018-04-24-051015/Macintosh\ HD/Users/krypted/Desktop/mysuperimportantfile
Now, let’s look at restoring a volume. Here, we’re going to change our working directory to the root of our latest backup, not booted to the volume we’re about to erase and overwrite with a backup):
cd "/Volumes/Time Machine Backup Disk/Backups.backupdb/mycomputername/Latest/Macintosh HD"
And then (this is dangerous, as it wipes out what’s on the old volume with the backed up data):
sudo /usr/bin/tmutil restore -v "/Volumes/Time Machine Backup Disk/Backups.backupdb/mycomputername/Latest/Macintosh HD" "/Volumes/Macintosh HD"
Now, let’s talk about what’s realistic. If I were to programmatically erase one of my coworkers data. I’d really, really want to verify that everything they need is there. So I’d run a checksum against the source and keep a copy of it only once I verify that absolutely everything is going where I want it to go. I would trust a cloning tool, but would I want to basically write my own archival solution using tmutil? No. I’ve simply seen too many strange little tidbits here and there that make me not… exactly… trust it with other people’s data. With my own data, though… sure! <3
