Background
Maybe it is just me again overcomplicating things. Yet I recently noticed that when I went on my VPN, using my IPhone to connect to the Internet, and then OpenVPN, at some point, TimeMachine decided to run a backup. Not the best idea in the world even if you are not on a world-wide flat rate, as it will eat up all your internet bandwidth (and also your data plan and hence pocket money if you’re not on a flat rate.)
Unfortunately, TimeMachine, like so many other of Apple’s products, are created for people who Apple apparently considers too dumb to configure anything about – and hence there’s not so much you can configure using their visual tools. I was having one external (USB) disk as TimeMachine target, and one network attached storage (actually a larger server I’m hosting, exposed through netatalk / AFP).
Now TimeMachine having two targets will just cycle through them. If you happen to be on the go, and just “appear” to be home (using VPN), then, well, see above.
Fortunately I saw that Apple provides for a small command line utility, tmutil, which you can utilize to control TimeMachine better. Yet as I’m a strong believer in Wall’s three fundamental virtues of any great programmer, one of which is laziness, I’m definitely too lazy to remember command line options, type stuff by hand, etc. That’s why I utilized today’s lunch break to come up with a quickly hacked together small Perl script which wraps tmutil (i.e., you can use it as a proxy), which gets you back in the driver’s seat. The File is attached, here’s how it works.
Scenario 0: Getting Help
So once you’ve copied the program somewhere and made it executable, e.g. using chmod 755 tmcontrol, you can call it like ./tmcontrol. If you do that without parameters, it first gives out some help of its own, and then invokes tmutil to show its help screen. The way tmcontrol is written, you don’t actually need to call tmutil directly, it acts as a proxy:
mnott-4:scripts mnott$ tmcontrol Usage: tmcontrol add|rm|list [target] For adding, you need the actual url, such as /Volumes/My Passport for Mac or afp://mnott@monster.local/TimeMachine%20Backup For deleting, a part of the name or url is sufficient. For running a backup, use run|start|backup as a shorthand for startbackup. For stopping a running backup, use stop as a shorthand for stopbackup. Usage: tmcontrol help <verb> Usage: tmcontrol version Usage: tmcontrol enable Usage: tmcontrol disable Usage: tmcontrol startbackup [-b | --block] [-r | --rotation] [-d | --destination dest_id] Usage: tmcontrol stopbackup Usage: tmcontrol enablelocal Usage: tmcontrol disablelocal Usage: tmcontrol snapshot Usage: tmcontrol delete snapshot_path ... Usage: tmcontrol restore [-v] src dst Usage: tmcontrol compare [-a@esmugtdEX] [-D depth] [-I name] tmcontrol compare [-a@esmugtdEX] [-D depth] [-I name] snapshot_path tmcontrol compare [-a@esmugtdEX] [-D depth] [-I name] path1 path2 Usage: tmcontrol setdestination [-a] mount_point tmcontrol setdestination [-ap] afp://user[:pass]@host/share Usage: tmcontrol removedestination destination_id Usage: tmcontrol destinationinfo [-X] Usage: tmcontrol addexclusion [-p] item ... Usage: tmcontrol removeexclusion [-p] item ... Usage: tmcontrol isexcluded item ... Usage: tmcontrol inheritbackup machine_directory tmcontrol inheritbackup sparse_bundle Usage: tmcontrol associatedisk [-a] mount_point volume_backup_directory Usage: tmcontrol latestbackup Usage: tmcontrol listbackups Usage: tmcontrol machinedirectory Usage: tmcontrol calculatedrift machine_directory Usage: tmcontrol uniquesize path ... Use `tmcontrol help <verb>` for more information about a specific verb.
As the last line says, for all those commands you can get more detailed help. If, for example, you want to have some help on tmcontrol startbackup, you can do:
mnott-4:scripts mnott$ tmcontrol help startbackup Usage: tmcontrol add|rm|list [target] For adding, you need the actual url, such as /Volumes/My Passport for Mac or afp://mnott@monster.local/TimeMachine%20Backup For deleting, a part of the name or url is sufficient. For running a backup, use run|start|backup as a shorthand for startbackup. For stopping a running backup, use stop as a shorthand for stopbackup. Usage: tmutil startbackup [-b | --block] [-r | --rotation] [-d | --destination dest_id] Perform a backup. This is similar to choosing "Back Up Now" from the Time Machine menu extra. OPTIONS: --block Wait (block) until the backup is finished before exiting. --rotation Allow automatic destination rotation during the backup. --destination Perform the backup to the destination corresponding to the specified ID.
Scenario 1: Controlling your Backup Targets
Requirement 1: List the Backup Targets
If you want to disable or enable backup targets, something that TimeMachine does not allow you to do on the fly without removing and later re-adding the targets, you first need to know which targets you have. To just list your backup targets, you can do it like this:
mnott-4:scripts mnott$ tmcontrol list ==================================================== Name : My Passport for Mac Kind : Local Mount Point : /Volumes/My Passport for Mac ID : 753F44C1-3C43-4C9A-A905-6A7E56D3D121 > ================================================== Name : TimeMachine Backup Kind : Network URL : afp://mnott@monster.local/TimeMachine%20Backup Mount Point : /Volumes/TimeMachine Backup ID : 5BD094C7-7FFE-4984-8BCB-EDB75B6D9538
So what this shows you is that I’ve actually configured two targets; one is an external hard disk (“My Passport”), the other is a network attached storage.
Requirement 2: Remove Backup Targets
Now, assume I’m going on a trip and want to hence remove a target temporarily. Say, I don’t want to have TimeMachine backup my data through a mobile connection, i.e. I want to remove the second target, the “Network” kind of target. This can easily be done like this:
mnott-4:scripts mnott$ sudo tmcontrol rm monster Removing TimeMachine Backup on afp://mnott@monster.local/TimeMachine%20Backup. ==================================================== Name : My Passport for Mac Kind : Local Mount Point : /Volumes/My Passport for Mac ID : 753F44C1-3C43-4C9A-A905-6A7E56D3D121
As you can see, I removed the target (you need to be super user to do that, which is why I prefixed the command with “sudo”). Once removed, the program will show the list of remaining targets. Now, the I basically said, rm (like remove) “monster” – where you can see from the previous listing of targets that “monster” is part of the URL string of the target – it is the name of my server. So how this actually works is that the script will try to find any target that has whatever you provide, as parameter, in either the name of the target or in the URL, if it is a network attached storage. All of the matching targets are then removed.
Which means, if I want to be more drastic and remove all of the targets, I can do it (in my case) like this:
mnott-4:scripts mnott$ sudo tmcontrol rm m Removing My Passport for Mac. Removing TimeMachine Backup on afp://mnott@monster.local/TimeMachine%20Backup. tmutil: No destinations configured.
Since “m” is both part of “TimeMachine” backup as well as “monster”, both are removed. Notice that the data is still on those targets, they are just basically removed from the list of targets that TimeMachine knows about.
Requirement 3: Add Backup Targets
Now, let’s say we were a bit overly ambitious and have now removed all our targets. For the local drive, which we know (using “mount” on the command line) is mounted to
/Volumes/My Passport for Mac
We can just re-add it using:
mnott-4:scripts mnott$ sudo tmcontrol add "/Volumes/My Passport for Mac" ==================================================== Name : My Passport for Mac Kind : Local Mount Point : /Volumes/My Passport for Mac ID : 0C90134F-B984-449F-AA27-0F9535C5B507
As before, the utility lists the targets after the fact. Now, if we want to add the network attached storage, we do basically the same thing, utilizing the data that we had seen before:
mnott-4:scripts mnott$ sudo tmcontrol add afp://mnott@monster.local/TimeMachine%20Backup Destination password: > ================================================== Name : My Passport for Mac Kind : Local Mount Point : /Volumes/My Passport for Mac ID : 0C90134F-B984-449F-AA27-0F9535C5B507 ==================================================== Name : TimeMachine Backup Kind : Network URL : afp://mnott@monster.local/TimeMachine%20Backup Mount Point : /Volumes/TimeMachine Backup ID : 59D4D49E-B12E-4EB8-82EA-154C70AC38B3
As you can see, I’ve a password required for the network attached storage, which is what the utility has asked me to input. If you do not want that password dialog (for automation), you can opt for replacing “-ap” by “-a” in the addLocation function in the script and then pass the password on the command line:
sudo tmcontrol add afp://mnott:password@monster.local/TimeMachine%20Backup
But notice that this is probably not such a good idea as your password will be visible to anyone utilizing your computer at the same time through a simple ps -ax process listing (if you’re alone on your machine, then why not).
Scenario 2: Running a Backup
So down to here, I’ve already solved my actual problem. Now since the tmutil program from Apple provides for quite a number of more options, I decided to make some of them more easily accessible. The first of them, of course, is to actually tell TimeMachine to run a backup “right now”:
mnott-4:scripts mnott$ tmcontrol run
mnott-4:scripts mnott$ tmcontrol status
Latest backups:
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-090926
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-104232
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-131350
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-142114
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-143457
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-150029
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-150635
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-154653
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-161245
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-163117
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-165720
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-170016
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-171631
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-173048
Backup session status:
{
BackupPhase = Copying;
ClientID = "com.apple.backupd";
DateOfStateChange = "2013-06-03 16:09:18 +0000";
DestinationID = "6FA99302-E117-4631-8B9C-57CE90B35704";
DestinationMountPoint = "/Volumes/My Passport for Mac";
Percent = "0.001512141859494737";
Progress = {
TimeRemaining = "-1";
"_raw_totalBytes" = 14408172;
bytes = 24208;
files = 286;
totalBytes = 15848989;
totalFiles = 286;
};
Running = 1;
Stopping = 0;
"_raw_Percent" = "0.001680157621660819";
}
As you can also see, you can use “tmcontrol status” to find out what’s going on. After a while, the situation should show up as idle:
mnott-4:scripts mnott$ tmcontrol status
Latest backups:
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-090926
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-104232
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-131350
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-142114
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-143457
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-150029
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-150635
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-154653
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-161245
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-163117
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-165720
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-170016
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-171631
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-173048
/Volumes/My Passport for Mac/Backups.backupdb/mnott (3)/2013-06-03-181011
Backup session status:
{
ClientID = "com.apple.backupd";
Running = 0;
}
Also, what “tmcontrol status” does is that it gives you a list of your most recent backups.
If you don’t like the word “run”, you can also utilize “start” or “backup” or “startbackup” (which is the default for tmutil.
Scenario 3: Stopping a Backup
If you want to stop a running backup, you’d just use “tmcontrol stop” or also “tmcontrol stopbackup” if that’s what you prefer. You should then use “tmcontrol status” to find out whether your backup has actually been stopped.
What I did notice, though, that sometimes TimeMachine appears to get stuck (think of an overly attached backup drive) – so if you want to clear that up, just “tmcontrol rm” remove all those drives and add them again.
Scenario 4: Becoming even more Productive
Now, that’s of course already pretty awesome. If you want to make even more out of your TimeMachine backups, then I really strongly suggest you check out BackupLoupe. These guys have done an awesome job adding a visual interface on top of TimeMachine which allows you to find stuff, diff stuff, etc. They give it aways for free, but allow you to pay something for supporting them. I just found out about what they do today, and I love it. They don’t do the simple stuff my Perl script does (like removing and attaching targets and running and stopping backups), but that’s not their mission: They care about giving you a much better, cleaner access to the content of your backups. I was just learning about their tool today when I considered adding a diff like functionality (like, git status, git diff, etc.) but as I saw what they did, there’s no point in doing that again. See virtues.
So, I hope this will help you guys to be more comfortable with your backups. I’ve so far not really utilized TimeMachine as I was constantly, regularly, getting broken backups – it sometimes is sufficient to just close the laptop while a backup to a network attached storage is running. It got better, recently, but not entirely reliable. I’m using my own set of rsync scripts on that, but with these options now, there’s a good motivation to go away from that somehow and invest more in TimeMachine.
Here’s the script (and excuse the verbosity and errors, that was literally hacked together in today’s lunch break):
