asr -- Apple Software Restore; copy volumes (e.g. from disk images)
asr verb [options]
asr restore[exact] --source source --target target [options]
asr server --source source --config configuration [options]
asr restore --source asr://source --file file [options]
asr imagescan --source image [options]
asr help | version
asr efficiently copies disk images onto volumes, either directly or via a multicast network stream. asr can also accurately clone volumes without the use of an intermediate disk image.
In its first form, asr copies source (usually a disk image, potentially on an HTTP server) to target. source can be specified using a path in the filesystem, or an http or https URL. It can also be an asr:// URL to indicate a multicast source. asr can also be invoked with its second form to act as a multicast server. In its third form, asr will restore a multicast disk image to a file instead of disk volume. In its fourth form, asr prepares a disk image to be restored efficiently, adding whole-volume checksum information. help and version provide usage and version information, respec- tively.
source and target can be /dev entries or volume mountpoints. If restoring a multicast disk image to a file, file can be a path to a local file or directory. If the specified path is a file, the disk image is given the specified name. If a directory, the name of the disk image being multicast is used. When specifying server, source has to be a UDIF disk image. Restoring from a multicast stream is accomplished by passing a asr:// url as source. When run in its first form above, the --erase option must always be used, as asr no longer supports file copying. Such functionality is done better by ditto(1).
asr needs to be run as root (see sudo(8)) in order to accomplish its tasks.
VERBS
restore restores a disk image or volume to another volume (including a mounted disk image)
|
sudo asr restore --source /Volumes/Classic --target /Volumes/install --erase
Restoring:
erasing the sudo asr restore -s <compressedimage> -t <targetvol> --erase
target and potentially do a block copy restore.
Multicast server: asr server --source <compressedimage> --config <configuration.plist>
Will start up a multicast server for the specified image, using the parameters in the configuration.plist. The image will
not start multicasting on the network until a client attempts to start a restore. The server will continue to multicast
the image until the process is terminated.
An example multicast configuration file:
defaults write /tmp/streamconfig "Data Rate" -int 6000000
defaults write /tmp/streamconfig "Multicast Address" <mcastaddr> (creates /tmp/streamconfig.plist)
should be appropriate for your network infrastructure and policy, usually from a range assigned by your
network administrator.
Multicast client
sudo asr restore --source asr:// --target --erase
Multicast client restoring to a file
sudo asr restore --source asr:// --file --erase
Will receive the multicast stream from and save it to a file. If is a directory, the image of the
streamed disk image will be used the save the file. --erase causes any existing file with the same name to be overwrit-
ten.
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 can
also be used.
Basic steps for imaging and restoring a volume:
1. Set up the source volume the way you want it.
2. Use Disk Utility's "Images -> New -> Image from Folder..." function and select the root of the volume. Save the
image as read-only or compressed. "Images->New->Image from " is not recommended on 10.3.x.
3. Scan the image with "Images -> Scan Image for Restore."
4. Select an image or volume and click on the "Restore" tab. Drag the source image and destination partition to the
source and destination fields. Click Restore.
BLOCK COPY RESTORE REQUIREMENTS
asr can block copy restore HFS+/HFSX filesystems and resize the source filesystem to fit in the target's partition if the
source filesystem data blocks will fit within the target partition's space (resizing the filesystem geometry as appropri-
ate).
HFS+ can be used as the source of a block copy to either an HFS+ or HFSX destination. However, an HFSX source can only
be used to block copy to an HFSX destination. This is because case collision of file names could occur when converting
from an HFSX filesystem to HFS+.
Certain non-HFS+/HFSX filesystems will block copy restore, but the target partition will be resized to match the size of
the source image/partition size, with no filesystem resizing occurring.
COMPATIBILITY
asr maintains compatibility with previous syntax, e.g.
asr -source source -target target [options]
asr -source source -server configuration [options]
asr -source asr://source -file file [options]
asr -imagescan [options] image
asr -h | -v
where -source, -target, and -file are equivalent to --source, --target, and --file respectively, and all [options] are
equivalent to their -- descriptions. asr -server configuration is superseded by asr server --config configuration. The
following deprecated options also remain:
-nocheck this option is deprecated, but remains for script compatibility. Use -noverify instead.
-blockonly
this option is deprecated, but remains for script compatibility. On by default. Note that if an image scanned
with -blockonly cannot be block-copied to a particular target an error will occur, since the file-copy infor-
mation was omitted.
Note: Compatibility with previous syntax is not guaranteed in the next major OS release.
ERRORS
asr will exit with status 1 if it cannot complete the requested operation. A human readable error message will be
printed in most cases. If asr has already started writing to the target volume when the error occurs, then it will erase
the target, leaving it in a valid (but empty) state. It will, however, leave it unmounted.
Some of the error messages which asr prints are generated by the underlying subsystems that it uses, and their meaning is
not always obvious. Here are some useful guidelines:
1. asr does some preflight testing before it starts actually copying data. Errors that show up during this preflight-
ing are usually clear (e.g. "There is not enough space in volume "Macintosh HD" to do the restore.")
2. If an error occurs during the copy, it might be because there is corruption in the source image file. Try running
"hdiutil verify" with the image. A common error message which indicates this is "codec overrun".
3. Errors which occur during the copy and which don't have an obvious cause (i.e. the error message is difficult to
interpret) may be transient in nature (e.g. there was an I/O error on the disk), and it is worth simply trying the
restore again.