ASR(8) BSD System Manager's Manual ASR(8)
NAME
asr -- Apple Software Restore; copy volumes (e.g. from disk images)
SYNOPSIS
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
DESCRIPTION
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, respectively.
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
Each verb is listed with its description and individual arguments.
restore restores a disk image or volume to another volume (including a mounted disk image)
--source can be a disk image, /dev entry, or volume mountpoint. In the latter two cases, the volume must be unmountable
or mounted read-only in order for a erase blockcopy to occur (thus, one cannot erase blockcopy the root filesys-
tem as the source, unless it happened to be mounted read-only).
--target can be a /dev entry, or volume mountpoint. Must be unmountable in order for an erase block-copy to occur.
--file when performing a multicast restore, --file can be specified instead of --target. 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.
--erase erases target and is required. --erase must always be used, as file copies are no longer supported by asr. If
source is a asr:// url for restoring from a multicast stream, --erase must be passed (multicasting only supports
erase block-copy restores). Passing --erase with --file indicates any existing file should be overwritten when
doing a multicast file copy.
--format HFS+ | HFSX
specifies the destination filesystem format, when --erase is also given. If not specified, the destination will
be formatted with the same filesystem format as the source. If multicasting, the --format specified must be
block copy compatible with the source. --format is ignored if --erase is not used. Note: HFS Journaling is an
attribute of the source image, and is not affected by --format.
--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.
--timeout num specifies num seconds that a multicast client should wait when no payload data has been received over a multi-
cast stream before exiting, allowing the client to stop in case of server failure/stoppage. It defaults to 0
(e.g. never time out).
--puppetstrings
provide progress output that is easy for another program to parse. Any program trying to interpret asr's
progress should use --puppetstrings.
--noverify skips the verification steps normally taken to ensure that a volume has been properly restored. --noverify
allows images which have not been scanned to be restored. Skipping verification is dangerous for a number of
reasons and should never be used in production systems.
--allowfragmentedcatalog
allows restores to proceed even if the source's catalog file is fragmented (in particular, if it has more than 8
extents). By default such restores are disallowed. Catalog fragmentation is undesirable and in most cases it
is better to fix the problem on the source (e.g. by running fsck_hfs -r on it), but --allowfragmentedcatalog is
provided for situations where such a change is impractical.
--corestorageconvert
Cause target to be converted to a Core Storage LVG at the end of the restore. After the copy and verify are
complete, asr will create a new Core Storage Logical Volume Group (LVG), using the partition represented by
target as its only physical volume (PV). The volume contents restored from source will be present as a single
logical volume (LV) exported from this LVG. If target is already a Core Storage LV, then this option has no
effect.
restoreexact performs the same operation as restore, taking all the same options, but with the following difference: the target partition
is resized to exactly match the size of the source partition/volume, if such a resize can be done. If the target partition
needs to grow and there is not enough space, then the operation will fail. If it needs to shrink, then it should always be
able to do so, possibly leaving free space in the target disk's partition map. Because the target exactly matches the source
in size, all volume structures should be identical in source and target upon completion of the restore.
server multicasts source over the network. Requires --erase be passed in by clients (multicasting only supports erase block-copy
restores).
--source source has to be a UDIF disk image. A path to a disk image on a local/remote volume can be passed in, or a http://
url to a disk image that is accessible via a web server.
--interface
the network interface to be used for multicasting (e.g. en0) instead of the default network interface.
--config server requires a configuration file to be passed, in standard property list format. The following keys/options
configure the various parameters for multicast operation.
Required
Data Rate this is the desired data rate in bytes per second. On average, the stream will go slightly slower than
this speed, but will never exceed it. It's a number in the plist (-int when set with defaults(1)).
Note: The performance/reliability of the networking infrastructure being multicast on is an important
factor in determining what data rate can be supported. Excessive/bursty packet loss for a given data
rate could be due to an inability of the server/client to be able to send/receive multicast data at that
rate, but it's equally important to verify that the network infrastructure can support multicasting at
the requested rate.
Multicast Address this is the Multicast address for the data stream. It's a string in the plist.
Optional
Client Data Rate this is the rate the slowest client can write data to its target in bytes per second. if asr misses
data on the first pass (x's during progress) and slowing the Data Rate doesn't resolve it, setting the
Client Data Rate will dynamically regulate the speed of the multicast stream to allow clients more time
to write the data. It's a number in the plist (-int when set with defaults(1)).
DNS Service Discovery whether the server should be advertised via DNS Service Discovery, a.k.a. Bonjour (tm). It defaults to
true. It's a boolean in the plist (-bool when set with defaults(1)).
Loop Suspend a limit of the number of times to multicast the image file when no clients have started a restore opera-
tion. Once exceeded, the server will stop the stream and wait for new clients before multicasting the
image file. It defaults to 0 (e.g. never stop multicasting once a client starts the stream), and should
not be set to <2. It's a number in the plist (-int when set with defaults(1)).
Multicast TTL the time to live on the multicast packets (for multicasting through routers). It defaults to 3. It can-
not be set to 0, and should not be set to 1 (otherwise, it could adversely affect some network routers).
It's a number in the plist (-int when set with defaults(1)).
Port the port of initial client-server handshake, version checks, multicast restore metadata, and stream
data. It defaults to 7800. This should only be included/modified if the default port cannot be used.
It's a number in the plist (-int when set with defaults(1)).
imagescan calculate checksums of the data in the provided image and store them in the image. These checksums are used to ensure proper
restores. Also determines if the disk image is in order for multicasting, and rewrites the file in order if not. If the image
has to be reordered, it will require free disk space equal to the size of the disk image being scanned.
--nostream
bypasses the check/reordering of a disk image file for multicasting. By default disk images will be rewritten in a
way that's necessary for multicasting.
--allowfragmentedcatalog
bypasses the check for a fragmented catalog file. By default that check is done and scanning won't be allowed on an
image that has a fragmented catalog file. It is usually a better idea to fix the image (e.g. run fsck_hfs -r on a
writable copy of it) than to use --allowfragmentedcatalog, but it is provided in case fixing the image is impracti-
cal.
BUFFERING
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 buf-
fers. 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. For multicast, 4 256k buffers are the default. Custom buffering for
multicast operation is not recommended.
--csumbuffers and --csumbuffersize allow a different buffer configuration for checksumming operations. One checksum buffer offers the best
performance. The default is 1 1MB buffer. Custom checksum buffering is not recommended.
Like mkfile(8), size defaults to bytes but can be followed by a multiplier 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). Custom checksum buffering
is not recommended.
--csumbuffersize size
specifies the size of each buffer used for checksumming. Custom checksum buffering is not recommended.
OTHER OPTIONS
--verbose enables verbose progress and error messages.
--debug enables other progress and error messages.
EXAMPLES
Volume cloning:
sudo asr restore --source /Volumes/Classic --target /Volumes/install --erase
Restoring:
sudo asr restore -s <compressedimage> -t <targetvol> --erase
Will erase the 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 multicas-
ting on the network until a client attempts to start a restore. The server will continue to multicast the image until the process is termi-
nated.
An example multicast configuration file:
defaults write /tmp/streamconfig "Data Rate" -int 6000000
defaults write /tmp/streamconfig "Multicast Address" <mcastaddr>
(will create the file /tmp/streamconfig.plist)
<mcastaddr> 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://<hostname> --target <targetvol> --erase
Multicast client restoring to a file
sudo asr restore --source asr://<hostname> --file <file> --erase
Will receive the multicast stream from <hostname> and save it to a file. If <file> 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 overwritten.
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 <device>" 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 appropriate).
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 information 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 preflighting 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 tran-
sient in nature (e.g. there was an I/O error on the disk), and it is worth simply trying the restore again.
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 installation 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 shipped on Macintosh computers as well as the Scan and Restore functionality in Disk Utility.
Multicast support was added to allow multiple clients to erase restore an image from a multicast network stream.
Per its history, most functionality in asr is limited to HFS+ volumes.
SEE ALSO
hdiutil(1), df(1), bless(8), ditto(1), and what(1)
Mac OS X 23 October 2012 Mac OS X