krypted.com

Tiny Deathstars of Foulness

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

April 23rd, 2018

Posted In: Mac OS X, Mac OS X Server, Mac Security

Tags: , , , ,

The Time Machine service in Yosemite Server hasn’t changed much from the service in previous operating systems. To enable the Time Machine service, open the Server app, click on Time Machine in the SERVICES sidebar. If the service hasn’t been enabled to date, the ON/OFF switch will be in the OFF position and no “Backup destination” will be shown in the Settings pane. TimeMachine1 Click on the ON button to see the New Destination screen, used to configure a list of volumes as a destinations for Time Machine backups. The selection volume should be large enough to have space for all of the users that can potentially use the Time Machine service hosted on the server. When you click the Choose button, a list of volumes appears in a standard Finder selection screen. TimeMachine2 Here, click on the volume to save your backups to in the sidebar. In most cases the Backup destination will be a mass storage device and not the boot volume of the computer. Once selected, click Choose and then if desired, limit the amount of storage on the volume to be used for backups. Click Create and a share called Backups is created and the service will start. Don’t touch anything until the service starts. Once started, add a backup destination at any time using the plus sign button (“+”) and defining another destination. Time Machine Server works via Bonjour. Open the Time Machine System Preference pane and then click on the Select Backup Disk button from a client to see the server in the list of available targets, much as you would do with an Apple Time Capsule. TimeMachine3 Under the hood, a backup share is creating in the file sharing service. To see the attributes of this share, use the serveradmin command followed by the settings option and then the sharing:sharePointList:_array_id:, so for a path of /Volumes/New Volume 1/Shared Items/Backups use: sudo serveradmin settings sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups The output indicates the options configured for the share, including how locking is handled, guest access disabled, generated identifiers and the protocols the backups share listens as: sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:name = "Backups"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbName = "Backups"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:nfsExportRecord = _empty_array
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsGuestAccessEnabled = no
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isTimeMachineBackup = yes
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeNative\:sharepoint_group_id = "F4610C2C-70CD-47CF-A75B-3BAFB26D9EF3"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isIndexingEnabled = yes
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:mountedOnPath = "/Volumes/New Volume 1"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeStandard\:GeneratedUID = "FAB13586-2A2A-4DB2-97C7-FDD2D747A0CD"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:path = "/Volumes/New Volume 1/Shared Items/Backups"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsShared = no
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsGuestAccessEnabled = no
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpName = "Backups"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbDirectoryMask = "755"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsShared = yes
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbCreateMask = "644"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:ftpName = "Backups"
sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:timeMachineBackupUUID = "844A1C43-61C9-4F99-91DE-C105EA95BD45" Once the service is running, administrators frequently fill up the target volume. To move data to another location, first stop the service and then move the folder (e.g. using mv). Once moved, use the serveradmin command to send settings to the new backup path. For example, to change the target to /Volumes/bighonkindisk, use the following command: sudo serveradmin settings sharing:sharePointList:_array_id:/Shared Items/Backups:path = "/Volumes/bighonkindisk" Another way to see the share and attributes of the share is through the sharing command: sharing -l Which should show output similar to the following: List of Share Points
name: Backups
path: /Shared Items/Backups
afp: {
name: Backups
shared: 1
guest access: 0
inherit perms: 0
}
ftp: {
name: Backups
shared: 0
guest access: 0
}
smb: {
name: Backups
shared: 0
guest access: 0
} There’s also a Bonjour service published that announces to other clients on the same subnet that the server can be used as a backup destination (the same technology used in a Time Capsule). One major update from back in Mavericks Server is the addition of the timemachine service in the severadmin command line interface. To see the command line settings for Time Machine: sudo serveradmin settings timemachine The output shows that share info is displayed as with the sharing service, but you can also see the GUID assigned to each share that is a part of the backup pool of storage: timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeStandard\:GeneratedUID = "FAB13586-2A2A-4DB2-97C7-FDD2D747A0CD"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbName = "Backups"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsGuestAccessEnabled = no
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbDirectoryMask = "755"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpName = "Backups"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbCreateMask = "644"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:nfsExportRecord = _empty_array
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:path = "/Volumes/New Volume 1/Shared Items/Backups"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsGuestAccessEnabled = no
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:name = "Backups"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:ftpName = "Backups"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsShared = no
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsShared = yes
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:timeMachineBackupUUID = "844A1C43-61C9-4F99-91DE-C105EA95BD45"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isTimeMachineBackup = yes
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:backupQuota = 0
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeNative\:sharepoint_group_id = "F4610C2C-70CD-47CF-A75B-3BAFB26D9EF3"
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isIndexingEnabled = yes
timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:mountedOnPath = "/Volumes/New Volume 1" Additionally you can also query for the service to verify it’s running using full status: sudo serveradmin fullstatus timemachine Which outputs something similar to the following: timemachine:command = "getState"
timemachine:state = "RUNNING" While I found plenty to ramble on about in this article, Mass deployment is still the same, as is client side configuration.

October 16th, 2014

Posted In: Mac OS X, Mac OS X Server, Mac Security, Mass Deployment

Tags: , , , , , ,

The Time Machine service in Mountain Lion Server hasn’t changed much from the service in Lion Server. To enable the Time Machine service, open the Server app, click on Time Machine in the SERVICES sidebar. If the service hasn’t been enabled to date, the ON/OFF switch will be in the OFF position and no “Backup destination” will be shown in the Settings pane. Screen Shot 2013-10-06 at 9.12.24 PMClick on the ON button to see the New Destination screen, used to configure a list of volumes as a destinations for Time Machine backups. The selection volume should be large enough to have space for all of the users that can potentially use the Time Machine service hosted on the server. When you click the Choose button, a list of volumes appears in a standard Finder selection screen. Screen Shot 2013-10-06 at 9.14.10 PMHere, click on the volume to save your backups to in the sidebar. In most cases the Backup destination will be a mass storage device and not the boot volume of the computer. Once selected, click Choose and then if desired, limit the amount of storage on the volume to be used for backups. Click Create and a share called Backups is created and the service will start. Don’t touch anything until the service starts. Once started, add a backup destination at any time using the plus sign button (“+”) and defining another destination. Note: A new feature in Mavericks Server is allowing for multiple backup destinations using the Server app, as well as allowing administrators to manage backups using the Backups tab. Time Machine Server works via Bonjour. Open the Time Machine System Preference pane and then click on the Select Backup Disk button from a client to see the server in the list of available targets, much as you would do with an Apple Time Capsule. Screen Shot 2013-10-06 at 9.17.28 PMUnder the hood, a backup share is creating in the file sharing service. To see the attributes of this share, use the serveradmin command followed by the settings option and then the sharing:sharePointList:_array_id:<Path to backup target>, so for a path of /Volumes/New Volume 1/Shared Items/Backups use: sudo serveradmin settings sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups The output indicates the options configured for the share, including how locking is handled, guest access disabled, generated identifiers and the protocols the backups share listens as: sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:name = "Backups" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbName = "Backups" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:nfsExportRecord = _empty_array sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsGuestAccessEnabled = no sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isTimeMachineBackup = yes sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeNative\:sharepoint_group_id = "F4610C2C-70CD-47CF-A75B-3BAFB26D9EF3" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isIndexingEnabled = yes sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:mountedOnPath = "/Volumes/New Volume 1" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeStandard\:GeneratedUID = "FAB13586-2A2A-4DB2-97C7-FDD2D747A0CD" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:path = "/Volumes/New Volume 1/Shared Items/Backups" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsShared = no sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsGuestAccessEnabled = no sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpName = "Backups" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbDirectoryMask = "755" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsShared = yes sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbCreateMask = "644" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:ftpName = "Backups" sharing:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:timeMachineBackupUUID = "844A1C43-61C9-4F99-91DE-C105EA95BD45" Once the service is running, administrators frequently fill up the target volume. To move data to another location, first stop the service and then move the folder (e.g. using mv). Once moved, use the serveradmin command to send settings to the new backup path. For example, to change the target to /Volumes/bighonkindisk, use the following command: sudo serveradmin settings sharing:sharePointList:_array_id:/Shared Items/Backups:path = "/Volumes/bighonkindisk" Another way to see the share and attributes of the share is through the sharing command: sharing -l Which should show output similar to the following: List of Share Points name: Backups path: /Shared Items/Backups afp: { name: Backups shared: 1 guest access: 0 inherit perms: 0 } ftp: { name: Backups shared: 0 guest access: 0 } smb: { name: Backups shared: 0 guest access: 0 } There’s also a Bonjour service published that announces to other clients on the same subnet that the server can be used as a backup destination (the same technology used in a Time Capsule). One major update in Mavericks Server is the addition of the timemachine service in the severadmin command line interface. To see the command line settings for Time Machine: sudo serveradmin settings timemachine The output shows that share info is displayed as with the sharing service, but you can also see the GUID assigned to each share that is a part of the backup pool of storage: timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeStandard\:GeneratedUID = "FAB13586-2A2A-4DB2-97C7-FDD2D747A0CD" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbName = "Backups" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsGuestAccessEnabled = no timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbDirectoryMask = "755" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpName = "Backups" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbCreateMask = "644" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:nfsExportRecord = _empty_array timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:path = "/Volumes/New Volume 1/Shared Items/Backups" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsGuestAccessEnabled = no timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:name = "Backups" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:ftpName = "Backups" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:smbIsShared = no timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:afpIsShared = yes timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:timeMachineBackupUUID = "844A1C43-61C9-4F99-91DE-C105EA95BD45" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isTimeMachineBackup = yes timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:backupQuota = 0 timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:dsAttrTypeNative\:sharepoint_group_id = "F4610C2C-70CD-47CF-A75B-3BAFB26D9EF3" timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:isIndexingEnabled = yes timemachine:sharePointList:_array_id:/Volumes/New Volume 1/Shared Items/Backups:mountedOnPath = "/Volumes/New Volume 1" Additionally you can also query for the service to verify it’s running using full status: sudo serveradmin fullstatus timemachine Which outputs something similar to the following: timemachine:command = "getState" timemachine:state = "RUNNING" While I found plenty to ramble on about in this article, Mass deployment is still the same, as is client side configuration. One change that appeared in Mountain Lion is that the screen for the Time Machine Options on the client no longer has an option for managing Versions, as seen here.Screen Shot 2013-10-06 at 9.25.05 PM

October 22nd, 2013

Posted In: Mac OS X, Mac OS X Server

Tags: , , , , , , , ,

A lot of environments want to use Time Machine at scale. But prior to Lion there hasn’t been a simple way to do so. Apple has introduced a new weapon in the war to backup client computers in the new command tmutil that was introduced in OS X Lion. The tmutil command allows administrators to enable Time Machine, make snapshots, kick off backups, delete snapshots, perform restores, configure options within Time Machine and, with a little scripting, build a centralized dashboard, pulling in Time Machine statistics from clients.

Enabling Time Machine

The first thing to know is that pretty much everything you do in Time Machine is going to require elevated privileges. So if you are writing a script, it should run as such, or if you’re running each command independently you will likely need to prefix them with sudo. Let’s start with a computer that doesn’t have Time Machine enabled. To enable it, use tmutil along with the enable verb: tmutil enable To disable Time Machine, use the disable verb: tmutil disable This is the equivalent of sliding the Time Machine slider between the ON and OFF positions.

We’ll also enable local backups, turning on snapshots: tmutil enablelocal But these don’t yet associate Time Machine with any disks or configure any of the settings. One of the first things people usually do when they enable Time Machine is to configure a destination volume for backups as you cannot backup if you don’t have a place to backup to. This is done using the setdestination verb. The destination can be a local file system or a network mounted share.  To set a destination as a local volume, simply follow the setdestination verb with an argument that indicates the path to use. For example, if you are pointing backups to a volume called remade: tmutil setdestination /Volumes/reamde Setting a destination will either write data into a DestinationVolumeUUIDs key in /Library/Preferences/com.apple.TimeMachine.plist. The contents of the key match the Volume UUID output of diskutil info. For example: diskutil info disk1s2 | grep Volume UUID Therefore, it is possible to swap UUIDs using a script on a biweekly or weekly basis or using tmutil along with the volume name, to match an offsite rotation rather than changing the volume in the System Preference pane.

Dealing with Network Mounts

In the case of a network mounted share, you would still use the setdestination verb, but define that the target location is a network mount by embedding a URL into the command rather than a file system path. The traditional URL will consist of protocol followed by :// followed by the hostname/sharename. We can go an extra step and also embed the username and password delimited by a colon and prefixing the hostname, using an @ to separate the credentials and the hostname. For example, if we wanted to define a hostname of tm.krypted.com with a share of snowcrash and a username of neal with a password of theU to access that share we would use the following: tmutil setdestination afp://neal:theU@tm.krypted.com/snowcrash Given that you might not want the password embedded into the command, you can use -p to enter a password manually (the password will not be displayed in the terminal screen). In this case, leave the username embedded into the path as follows: tmutil setdestination -p afp://neal@tm.krypted.com/snowcrash While the inclusion of a computer name in the path of actual Time Machine backups seems to indicate that it is OK to allow multiple computers to use it, doing so seems discouraged in Apple’s Time Machine documentation. Therefore, sticking with one computer per share will likely be the most secure and least corruptible means of backup. While creating a bunch of shares for backups might seem daunting at first, it’s worth mention that you can script share creation, per client computer in OS X Server using the sharing command. For example, to create a share for a computer named neal in /Shared with AFP only and no guest access: sharing -a /Shared/neal -s 100 -g 000 To list computers in Open Directory: dscl /LDAPv3/127.0.0.1 -list Computers Variabalizing the dscl output into an array and creating machine-specific shares would then net a share per computer (assuming all computers have corresponding records in the directory service). Likewise, shares can be built using a DeployStudio, Absolute Manage or Casper machine export as well.

Configuring the Backup Source

In Time Machine, all data is backed up by default. Therefore, rather than define what the source is, you define what the source is not. Once a target location has been defined, the next thing many Time Machine users do is define any data that is not to be kept in the Time Machine backups. This is done with the addexclusion verb. These exclusions are defined using the Options button of the Time Machine System Preference pane as well. To use the addexclusion verb, simply define a list of items that are not to be backed up as arguments separated by spaces. The tmutil command will then use those items as an array. If you have one item to exclude, simply list the path. For example, to exclude the OS X Developer Tools: tmutil addexclusion /Developer Or to disable a number of items (below we are only backing up /Users): tmutil addexclusion /System /Library /Applications /var /etc /Developer /Groups /Incompatible Software /Volumes /bin /cores /usr /tmp /temp /opt /net /home /Shared Items /Network /Groups Provided no errors occur the command should have run properly. The isexcluded verb then allows you to see which source locations are being excluded. Use the verb similarly to addexclusion: tmutil isexcluded /Developer A minus sign means it’s being excluded and a plus sign means it’s being backed up. You could also just grab the first position of the output: tmutil isexcluded /Developer | cut -c 1 You can also use this as a sanity check prior to performing restores at a lower depth. For example, there is no reason to try to recover a file called /Users/cedge/Desktop/systemoftheworld.pdf if it hasn’t been backed up: tmutil isexcluded /Users/cedge/Desktop/systemoftheworld.pdf | cut -c 1 The arguments for addexclusion are not all of the items being excluded. Instead, you are adding items, but others may already be present. Also, you can define the same exclusion multiple times without adding each item to the list of excluded items. To remove an item, use the removeexclusion verb (you can separate these with spaces as well): tmutil removeexclusion /Volumes Finally, addexclusion and removeexclusion have a -p option. By default, if you move an item that has been defined as an exclusion, the exclusion will move with the item. You can specify a -p option to set the path for the exclusion as static: tmutil addexclusion -p /etc There are also a number of exclusions that are included by default. These are defined in the .exclusions.plist. The non-default exclusions are stored in the ExcludeByPath array in /Library/Preferences/com.apple.TimeMachine.plist. These are not shown to an end user in the Time Machine System Preference pane though. Those paths can be found in the SkipPaths array within the same file. By default, the backup source needs to be connected to power. This setting corresponds to the Back up while on battery power checkbox in the Time Machine System Preference pane’s Option overlay. That setting can be disabled using defaults to write a 1 into the RequiresACPower key: defaults write /Library/Preferences/com.apple.TimeMachine RequiresACPower 0

Manually Running Backups

Once you have defined your source and target, it’s time to test a backup. The tmutil command allows you to kick off a backup immediately run tmutil with the startbackup verb. tmutil startbackup Either the backup will work or the Finder will display an error that the backup could not complete. If the system performance is poor during backups or you need to stop one for another reason: use the stopbackup verb: tmutil stopbackup In Time Machine a snapshot is an incremental or a fill (aka initial) backup. These are stored on a target volume, or backup disk. For example, the previously used snowcrash volume will contain a snapshot:

Each machine will have its own entry, meaning you can move Time Machine volumes between hosts or use a single network mount to allow backups for multiple clients (although there are some interesting security implications behind doing so). To create a new local snapshot (seen above in the path), use the snapshot verb: tmutil snapshot

Managing Backups

The Time Machine System Preference pane doesn’t give you a lot of features for managing retention and recycling media. But with OS X Lion, you can now manage and delete given snapshots of data, thus allowing for manually cleaning out your backups (or doing so with a script that has a lot more logic than the default settings). To see a list of snapshots, use the listbackups verb: tmutil listbackups You will see output of each snapshot on the computer: /Volumes/EncryptedTMBackup/Backups.backupdb/stephenson.krypted.com/2011-08-09-181840 /Volumes/EncryptedTMBackup/Backups.backupdb/stephenson.krypted.com/2011-08-09-195105 To just see that last snapshot: tmutil latestbackup The fitting delete verb is used for such a task and is able to take the argument of an old snapshot (or an array of such) to delete. For example, to delete snapshot 2011-08-09 -181840 for computer stephenson.krypted.com on /Volumes/EncryptedTMBackup tmutil delete /Volumes/EncryptedTMBackup/Backups.backupdb/stephenson.krypted.com/2011-08-09-181840 You can also calculate how much drift has occurred between snapshots: tmutil calculatedrift /Volumes/EncryptedTMBackup/Backups.backupdb/stephenson.krypted.com/2011-08-09-195105 The calculatedrift verb will show the amount of data added, removed and changed between each backup as well as output the averages of drift between backups (helpful in capacity planning and reporting). To compare a snapshot to a file system path (or paths), use the compare verb. This is handy for figuring out which snapshots you might be able to nuke if you’re scripting a delete process. The compare verb is one of the more complicated as there are a number of options for how to compare data. tmutil compare /Volumes/EncryptedTMBackup/Backups.backupdb/stephenson.krypted.com/2011-08-09-195105 The output can be a bit verbose as it looks at each directory. You can limit the depth using a -D option. You can also specify a number of different options to specify what differences to look for when performing lookups. The output of compare is helpful if you preflight your backups with a sanity check to verify there is enough room (otherwise the user might get a Time Machine error dialog).

Other Options

The tmutil command also has options for troubleshooting, moving disks and restores. The restore verb can be handy as you can send restore scripts to clients over ARD or even build a self-restore portal with more options than can be found in the TIme Machine restore screen (I’d recommend using the -v option with restores, btw). The inheritbackup verb can be used to take ownership of a machine directory, useful when moving disks or shares between clients. The associatedisk verb can be used to attach a disk to a backup, thus allowing you to skip beginning backups all over again if the UUID of a disk changes. Also, the options in 10.6 are still applicable. To suppress the dialog to make all new disks a TimeMachine volume: defaults write com.apple.TimeMachine DoNotOfferNewDisksForBackup -bool YES Backups are also still kicked off by com.apple.backupd-auto.plist, stored in /System/Library/LaunchDaemons and the interval between backups can be changed using the StartInterval key here. For example, if you set it to 360 then backups will occur every 6 minutes instead of 60, or more likely, if you set the integer to 14400 then your backups will occur every 4 hours instead of every hour.

Puzzle Pieces

To take a few pieces from this article and combine them. Setting up a basic backup (provided that you have a known volume name per client) is as easy as the following basic, quick and dirty shell script: /usr/bin/tmutil enable /usr/bin/tmutil enablelocal /usr/bin/tmutil setdestination /Volumes/BACKUP /usr/bin/tmutil addexclusion /System /Library /Applications /var /etc /Developer /Groups /Incompatible Software /Volumes /bin /cores /usr /tmp /temp /opt /net /home /Shared Items /Network /Groups /usr/bin/defaults write /Library/Preferences/com.apple.TimeMachine RequiresACPower 0 defaults write com.apple.TimeMachine DoNotOfferNewDisksForBackup -bool YES

August 10th, 2011

Posted In: Mac OS X, Mac OS X Server, Mac Security, Mass Deployment

Tags: , , , , , , , , , , , , ,