ASR(8) System Manager's Manual ASR(8)
NAME
asr - Apple Software Restore
SYNOPSIS
asr -source source -target target [options]
asr -imagescan image
asr -h | -v
DESCRIPTION
asr efficiently copies disk images onto volumes. asr can also accurately
clone volumes.
In its first form, asr copies source (usually a disk image) to target.
In it's second form, asr prepares a disk image to be restored effi-
ciently, adding file by file and whole-volume checksum information. -h
and -v provide usage and version information, respectively.
source and target can be /dev entries or volume mountpoints. asr gener-
ally needs to be run as root (see sudo(8)) in order to accomplish its
tasks.
OPTIONS
-erase erase erases target and is required if a fast block-copy
restore is desired. By default asr will do a restore-in-
place. Duplicate items will not harm target contents,
but files will be replaced.
-noprompt suppresses the prompt which usually occurs before target
is erased. newfs_hfs(8) will be called on target and
once you start writing new data, there isn't much hope
for recovery. You have been warned.
By default, asr will restore in place, and it will not do
any OS volume blessing beyond what was on the original
volume (bless -info /Volumes/<vol> will let you know the
current state).
-rebuild causes the desktop database on target (used by Classic
System Software) to be rebuilt.
-nocheck skips the verification steps normally taken to insure
that a volume has been properly restored. -nocheck
allows images which have not been scanned to be restored.
-disableOwners prevents the default owner-enabling behavior for source
and target. Enabling owners is usually very important
for an accurate file-by-file copy to be made. In block-
copy restore mode, -disableOwners has no effect.
The following options control how asr uses memory. These options can
have a significant impact on performance. asr is optimized for copying
between devices (different disk drives, from a network volume to a local
disk, etc). As such, asr defaults to using eight one megabyte buffers.
These buffers are wired down (occupying physical memory). For partition
to partition copies on the same device, one large buffer (e.g. 32 MB) is
much faster than the default eight medium sized ones.
-csumbuffers and -csumbuffersize allow a different buffer configuration
for checksumming operations. Two checksum buffers is a minimum for good
performance, especially on dual-processor machines. Without these
options, checksumming operations will use the same buffer configuration
as copying.
Like mkfile(8), size defaults to bytes but can be followed by a multi-
plier character (e.g. 'm').
-buffers num
specifies that num buffers should be used.
-buffersize size
specifies the size of each buffer.
-csumbuffers num
specifies that num buffers should be used for checksumming
operations (which only affect the target).
-csumbuffersize size
specifies the size of each buffer used for checksumming.
Other Options:
-verbose enables verbose progress and error messages, including those
from the DiskImages framework.
-debug enables other progress and error messages, including those
from the DiskImages framework.
-h prints usage information
-v displays version number.
EXAMPLES
Volume cloning:
sudo asr -source /Volumes/Classic -target /Volumes/install
Restoring:
sudo asr -source <compressedimage> -target <targetvol> -erase
will erase the target and potentially do a block copy restore.
HOW TO USE ASR
asr requires a properly created disk image for most efficient operation.
This image is most easily made with Disk Copy application's "Image from
Folder/Volume" function. The Disk Copy from OS X 10.2.2 (v54.3) or later
is required.
To create a disk image for restoration on another volume:
1. Install OS X and set it up the way you want it. In general, the
best way to do this will be to actually boot the volume, go through
setup, create the accounts you want, dock items, applications, pref-
erences, etc. You'll see later how to delete accounts and re-enable
setup assistant to run on first boot.
2. Boot from a different volume (e.g. firewire drive, or second volume
on your primary drive). This isn't strictly necessary, but makes
this easier.
3. Enable permissions on the volume you want to image. The easiest way
to do this is to "get info" in the Finder and make sure the "ignore
ownership on this volume" is unchecked under the "ownership & per-
missions" tab.
4. Use Disk Copy to create a image from a folder/volume. Save to a
read-write image.
If you create a image from a device, you will not be able to block
restore it to any volume larger than the one you created the image
on. Creating a image from folder/volume is slower, but will give a
better result (stretchable, defragmented).
5. Become root (e.g. 'sudo -s') or prepare to type 'sudo' ahead of the
next few commands.
6. Clean up the image:
rm /Volumes/<imagevol>/var/db/BootCache.playlist # (see TIL
article 107111)
rm /Volumes/<imagevol>/var/db/volinfo.database
rm -r /Volumes/<imagevol>/var/vm/swap*
7. Optional extra cleanup items while the image is mounted read/write:
o If you want to be rid of the admin account you used to set up
the machine:
nicl -raw /Volumes/<imagevol>/var/db/netinfo/local.nidb
delete /users/<admin>
rm -r /Volumes/<imagevol>/Users/<admin>
o If you want the restore image to start up in setup assistant
rm /Volumes/<imagevol>/var/db/.AppleSetupDone
8. Make sure the volume is ejected.
9. Convert the image to read-only or compressed (asr won't scan
read/write images) using either "Convert Image" in Disk Copy or
hdiutil convert -format UDZO <pathtoimage> -o
<compressedimage>
10. Scan the image:
asr -imagescan <compressedimage>
Now asr will be able to restore the image per EXAMPLES above.
HOW TO GET THE FASTEST RESTORES
If you are trying to understand file copy (slow) vs. block copy (fast):
When you see "Restoring...", that means the source image volume is larger
than the target volume or the volume geometry of the source image is
stretchable to the target size, allowing a high speed block copy can
occur.
When you see:
Copying "/private/tmp/..." (/dev/diskMsN) to "<target>" (/dev/diskPsQ)...
It means the above is not true, and asr has fallen back to a file copy
operation. asr will only block copy if the volume geometries support it
AND you are doing an erase restore. If you are restoring in place, a
file copy is always performed.
If some target volumes restore quickly and others slowly, the source
image was probably created without stretch from a 60 GB drive. Thus it
will block restore on 60 GB and smaller partition, but file copy on an 80
GB target.
By default (given source size > 50 MB), Disk Copy will create an image of
a volume that is block restorable to 256 GB. If you want to create an
image that will restore to a larger volume (say a 480 GB RAID set), you
will need to set some defaults before you have Disk Copy image the vol-
ume:
defaults write com.apple.DiskCopy \
hfsplus-stretch-parameters -dict \
hfsplus-stretch-threshold 102400 \
hfsplus-stretch-allocation-block-size 4096 \
hfsplus-stretch-allocation-file-size 16777216
will make a 512 GB stretchable volume. By default the hfsplus-stretch-
allocation-file-size value is 8388608 (8 MB).
The size of the allocation file will increase image size, so it shouldn't
be too big. It has only been tested as a multiple of 4k.
ERRORS
asr will exit with status 1 if it cannot complete the requested opera-
tion. A human readable error message will be printed in most cases.
HISTORY
Apple Software Restore got it's start as a field service restoration tool
used to reconfigure computers' software to 'factory' state. It later
became a more general software restore mechanism and software installa-
tion helper application for various Apple computer products. ASR has
been used in manfacturing processes and in shipping computers' System
Software Installers.
For Mac OS X, asr was rewritten as a command line tool for manufacturing
and professional customers. asr is the backend fo the Mac OS X Software
Restore application that ships on new Macintosh computers.
Per its history, most functionality in asr is limited to HFS+ volumes.
SEE ALSO
hdiutil(1), df(1), bless(8), and what(1)
Mac OS X 28 Oct 2002 Mac OS X