asr(8) BSD System Manager's Manual asr(8)
NAME
asr - Apple Software Restore
SYNOPSIS
asr -source source -target target [options]
asr -imagescan [-blockonly] 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, potentially
on an HTTP server) to target. In its second form, asr prepares a disk
image to be restored efficiently, 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. By default,
asr will restore in place, and will not bless (see bless(8)) any folders.
If -erase is specified, any blessed folders on the source will also be
blessed on the target.
bless -info /Volumes/<vol>
will display current blessed folders for the given volume.
asr generally needs to be run as root (see sudo(8)) in order to accom-
plish 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.
-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.
-wrapper forces an HFS wrapper to be created on the target volume
if the -erase option is used. Normally the creation of a
wrapper depends on certain filesystem variables.
-wrapper is ignored if -erase is not used.
-nowrapper forces an HFS wrapper to not be created on the target
volume if the -erase option is used. Normally the cre-
ation of a wrapper depends on certain filesystem vari-
ables. -nowrapper is ignored if -erase is not used.
-blockonly causes asr to only insert information relevant to block
copies when used with -imagescan. -blockonly makes the
scan much faster. However, if an image scanned with
-blockonly cannot be block-copied to a particular target
volume then an error will occur, since the file-copy
information was omitted.
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 the Disk Utility application's "Image
from Folder" function in OS X 10.3. The Disk Copy from OS X 10.2.3
(v55.6) 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.
Beware that not all settings can be copied through the filesystem
from one machine to another. For example, some preferences are
stored "ByHost" which means they only apply to a machine with a par-
ticular ethernet address. Other preferences files generated on one
piece of hardware may not apply (or may even mask functionality) on
other hardware with a different feature set (e.g. batteries).
2. Boot from a different volume (e.g. firewire drive, or second volume
on your primary drive). This isn't strictly necessary, but makes
the following easier.
3. Enable ownership 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 Utility to create an image from a folder/volume. Save to a
read-write image on a volume other than the one you are imaging.
Beware that this operation requires two times as much free space on
the volume to which you are saving the image as you have data on the
source.
If you create an 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 an 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 not attached (e.g. drag mounted volumes to
the trash).
9. Convert the image to read-only or compressed (asr won't scan
read/write images) using either "Convert Image" in Disk Utility 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 (slower) 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 to
occur. As of asr in OS X 10.3, the geometry restrictions have been sig-
nificantly relaxed such that stretchable source images are no longer
required.
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 (ie. "image from device"
instead of the "image from folder" recommended above). For example, if
the source was a 60 GB volume, the image will block restore on 60 GB and
smaller volumes, but file copy on an 80 GB target.
By default (given source size > 50 MB), Disk Utility 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 Utility image the
volume:
defaults write com.apple.frameworks.diskimages \
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 with sizes that are multiples 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.
Note that asr will mount the source image as part of verifying its geome-
try. Using hdiutil(1), particularly the imageinfo, verify, and attach
verbs, can help isolate various problems in accessing the image in ques-
tion.
HISTORY
Apple Software Restore got its 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 manufacturing 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 for 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
Mac OS X 10.3 - Generated Fri Jun 6 19:46:39 CDT 2008