ASR(8) System Manager's Manual ASR(8)

asr — Apple Software Restore; copy volumes (e.g. from disk images)

asr verb [options]

asr --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 | file ... 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, respectively.

source and target can be /dev entries or volume mountpoints. For more information on restoring to or from APFS filesystems, see the RESTORING WITH APFS FILESYSTEMS section below. 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 source has to be a UDIF disk image. Restoring from a multicast stream is accomplished by passing a asr:// url as source.

When restoring APFS volumes, asr supports restoring snapshots from the source volume, as well as restoring snapshot deltas. See the RESTORING WITH APFS SNAPSHOTS section below.

asr supports restoring systems with a Read-Only System Volume (ROSV). For more information, see the RESTORING WITH READ-ONLY SYSTEM VOLUMES section below.

asr needs to be run as root (see sudo(8)) in order to accomplish its tasks.

Each verb is listed with its description and individual arguments.

restores a disk image or volume to another volume (including a mounted disk image)
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 filesystem as the source, unless it happened to be mounted read-only).
can be a /dev entry, or volume mountpoint. Must be unmountable in order for an erase block-copy to occur. If source specifies an image of an APFS container, then target can specify a mounted APFS volume. See the RESTORING WITH APFS FILESYSTEMS section below for details.
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.
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.
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.
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.
num
specifies num seconds that a multicast client should wait when no payload data has been received over a multicast stream before exiting, allowing the client to stop in case of server failure/stoppage. It defaults to 0 (i.e. never time out).
provide progress output that is easy for another program to parse. Any program trying to interpret asr's progress should use --puppetstrings.
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.
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. This option only makes sense if the source specifes an HFS+ filesystem variant. It is otherwise ignored.
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.
forces the restore to use the SHA-1 hash in the image during verification. If the image doesn't contain a SHA-1 hash, then an error will be raised.
forces the restore to use the SHA2-256 hash in the image during verification. If the image doesn't contain a SHA2-256 hash, then an error will be raised.
tells asr which volume in the source container to invert when doing an APFS restore. It is an error if more than one volume has the specified name. You can see the volume names and UUIDs by running asr with the info verb. See the section RESTORING WITH APFS FILESYSTEMS below for when this option is necessary.
tells asr which volume in the source container to invert when doing an APFS restore. You can see the volume names and UUIDs by running asr with the info verb. See the section RESTORING WITH APFS FILESYSTEMS below for when this option is necessary.
forces asr to use replication for restoring APFS volumes (see the section REPLICATION AND THE INVERTER below). This is the default, but there may be a preference setting to use the inverter instead. This would override that preference setting.
forces asr to use the inverter for restoring APFS volumes (see the section REPLICATION AND THE INVERTER below). This overrides any preference setting.
specifies the snapshot on the source APFS volume to restore to the target APFS volume. The argument must be either the name or UUID of a snapshot on source. See the RESTORING WITH APFS SNAPSHOTS section below for more details.
names a snapshot on the source APFS volume to use in combination with --toSnapshot to specify a snapshot delta to restore to the target APFS volume. The argument must be either the name or UUID of a snapshot on both source and target. See the RESTORING WITH APFS SNAPSHOTS section below for more details.
performs the same operation as restore, taking all the same options, but with the following difference: for an HFS Plus volume, 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.

restoreexact is not allowed with APFS volumes (see the section RESTORING WITH APFS FILESYSTEMS below), so its use is deprecated.

multicasts source over the network. Requires --erase be passed in by clients (multicasting only supports erase block-copy restores).
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.
the network interface to be used for multicasting (e.g. en0) instead of the default network interface.
requires a configuration file to be passed, in standard property list format. The following keys/options configure the various parameters for multicast operation.
 
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.
 
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 operation. 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 cannot 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)).
calculate checksums of the data in the provided image and store them in the image. These checksums are used to ensure proper restores. By default, a SHA2-256 hash is used. 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.
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.
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 impractical.
report the image metadata which was placed in the image by a previous use of the imagescan verb. Requires --source. The report is written to standard output.
writes its output as an XML-formatted plist, suitable for parsing by another program.

Individual APFS volumes can not be restored directly, because their device nodes don't allow I/O from a standard process. However, asr can restore entire APFS containers, including all volumes. Or it can restore valid system configurations, which can get the effect of restoring a single system. This requires understanding what is meant by a valid system.

In order for an APFS volume to be bootable, it must contain a properly installed macOS system. It must also be part of an APFS container which also has two special volumes in it: a Preboot volume and a Recovery volume. A container may have arbitrarily many system volumes in it, but it must have only one Preboot volume and one Recovery volume, each with the corresponding APFS volume role set (see diskutil(1) for information on roles). The Preboot and Recovery volumes contain information which is tied to each system volume in the container. So for a system volume to be bootable, that information needs to be set up in the Preboot and Recovery volumes. A system which is part of a container that has these two special volumes, and for which the requisite information is set up in those volumes, will be referred to here as a valid system.

If the source of a restore is an APFS image (i.e. an image which contains an APFS container), then asr does different things depending on how target was specified:

Volume Restore
If the target is an individual volume within an existing APFS container, then asr will block restore the APFS container to a file within that volume, after which it will invert the volume within the restored container, erasing the previous contents of the target volume and replacing them with the source volume contents. If the source container only has a single non-special volume (i.e. not Preboot or Recovery), then that is the volume which will be inverted. If the source container has more than one non-special volume, then either the --sourcevolumename or --sourcevolumeUUID option must be present and must specify the volume to invert. Additionally, if the volume being inverted is a valid system (as defined above), then the relevant contents of both the Preboot and Recovery volumes will be copied from the source to the target, creating those volumes on the target if necessary.
Volume Restore with Creation
If the target is a synthesized APFS whole disk or Apple_APFS partition, and the --erase option is not present, then asr will create a new volume in the given container, after which it will do a volume restore to that new volume, as with the previous section. All other volumes in the container are preserved.
Volume Restore with Erase
If the target is a synthesized APFS whole disk or any disk partition, and the --erase option is present, then asr will erase the existing partition, create a new APFS container and a new volume in it, after which it will do a volume restore to that new volume, as with the previous section.

See the EXAMPLES section below for some command lines that show these operations.

As of macOS Catalina, the standard mechanism for restoring APFS volumes is to use the internal APFS replication capability. While this should be sufficient for most needs, asr does provide the ability to use a legacy restore mechanism, which involves running the apfs_invert program. Restoring with the inverter has some limitations (e.g. all volumes in the target container must be unmounted, the source volume can't have any snapshots in it, etc), so using the default APFS replication is usually the better choice. However, in the event that invert restores are desired, that option can be selected. The logic asr uses for this is as follows, from lowest to highest priority:

- By default, use replication.

- Look for a preference in the domain com.apple.asr with key "ForceInvert" and a Boolean value.

- Look for a --useReplication or --useInverter option on the command line.

APFS volumes may contain snapshots, which are point-in-time captures of all volume state (including directory hierarchy, file existence and file content). To distinguish between a snapshot and the current state of a volume, we will here refer to that current state as the "live volume." Snapshots can be identified by name or UUID. Names are unique within a single volume, but two volumes can have snapshots with the same name that are unrelated in content. By contrast, snapshot UUIDs are unique, in the sense that two snapshots on different volumes that have the same UUID must refer to identical content, a situation that will typically arise by restoring a snapshot, as described in this section.

In addition to restoring a live volume (either currently known to the system or from an image), asr also supports restoring a snapshot from the source volume. The result of such a restore is that the target volume ends up looking like the source volume at the time of the given snapshot, rather than like the live source volume. Additionally, the target volume will contain that state as a snapshot of its own, with the same name and UUID as the restored snapshot in the source. See the EXAMPLES section below for some command lines that show snapshot restores.

asr also supports restoring the difference between two snapshots, referred to as a "snapshot delta." In this case there must be both a "from" snapshot and a "to" snapshot on the source volume, the target must be specified as a specific volume rather than a whole container, and the target volume must already contain a snapshot which is identical to the source's "from" snapshot. The result of a snapshot delta restore is that the target ends up looking like the source's "to" snapshot, similar to a regular snapshot restore as described above. But the restore only needs to copy over the difference between the two snapshots, so it may save considerable time and/or network or bus resources. Note that a snapshot delta restore can still discard data from the target volume, so asr does require using the --erase option when doing a snapshot delta restore. Again, see the EXAMPLES section below for some command line examples of snapshot delta restores.

Note that restoring with snapshots and snapshot deltas is only allowed when using replication (see the REPLICATION AND THE INVERTER section above).

macOS Catalina supports a Read-Only System Volume (ROSV) configuration, in which the standard macOS system install is split across two volumes. The two are referred to as the System and Data volumes, that is how their corresponding APFS roles are set (see diskutil(1) for more on APFS roles), they are combined into a volume group, and the System volume gets mounted read-only.

asr has support for restoring ROSV volume groups. If the source is a disk image containing an ROSV volume group, or an existing volume that is part of a volume group, then both volumes will be restored to the target, and the target volumes will be combined as appropriate into a new group on the target. Since the source and the target may each be part of a group or not, there are several cases to consider:

Creating New Volumes
If the specified target is a container rather than a volume, then new volumes will always be created, whether the source is a single volume or part of a group.
Source is Group, Target is Single
The specified target will be erased and replaced with the System-role volume in the source group, and a new volume will be created for the Data-role volume.
Source is Group, Target is Group
Both of the volumes in the target group will be replaced by the corresponding volumes in the source group.
Source is Single, Target is Group
The System-role volume in the target is replaced by the source volume, and the Data-role volume in the target is deleted.

asr can restore snapshots and snapshot deltas from any volume in a volume group, but the behavior is different between snapshot restores and snapshot delta restores.

When doing a snapshot restore (i.e. using the --toSnapshot option without the --fromSnapshot option), each volume in the source volume group is examined to see if it contains the specified "to" snapshot. Each volume in the group which contains the snapshot will be copied as a snapshot replication, as described in the RESTORING WITH APFS SNAPSHOTS section, above. Each volume in the group which does not contain the snapshot will be copied as a live volume replication. So all volumes in the group are restored, and only those which contain the given "to" snapshot will have a snapshot restore performed. Note that if the "to" snapshot is specified by name, multiple volumes in the source group may have a snapshot with that name, though those snapshots need not be related in any way.

By contrast, snapshot delta restores (i.e. using both the --toSnapshot and --fromSnapshot options) are only ever performed on a single volume. The source volume can be any volume (i.e. it need not have any particular role), but whether or not it's in a group, that will be the only volume restored. So if there are multiple volumes which have snapshots with the same names and you want to do a snapshot delta restore for all of them, then you must invoke asr once for each such volume.

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. 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').

num
specifies that num buffers should be used.
size
specifies the size of each buffer.
num
specifies that num buffers should be used for checksumming operations (which only affect the target). Custom checksum buffering is not recommended.
size
specifies the size of each buffer used for checksumming. Custom checksum buffering is not recommended.

enables verbose progress and error messages.
enables other progress and error messages.

sudo asr restore --source /Volumes/Classic --target /Volumes/install --erase

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 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.

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.

Restoring a single APFS volume

sudo asr restore -s <APFS image> -t /Volumes/MyAPFSVolume --erase

In this case the contents of MyAPFSVolume will be replaced by the contents of the source container's single APFS volume, possibly including any associated data for the Preboot and Recovery volumes, if the source is a valid system. If the source has more than one non-special volume, this is an error. No other volumes in the target will be affected.

Restoring one of many APFS volumes

sudo asr restore -s <APFS image> --sourcevolumename SourceVolume -t /Volumes/MyAPFSVolume --erase

This tells asr to select the volume named "SourceVolume" from the given APFS image. If there is no volume with that name, or if there are more than one with that name, it is an error. Use the info verb to see the volume names and UUIDs for an image. No other volumes in the target will be affected.

sudo asr restore -s <APFS image> --sourcevolumename SourceVolume -t /dev/disk2

Here we get the same effect as the last example, except that asr will create a new volume on the target APFS container disk, given by /dev/disk2, and use that newly created volume as the target. Any volumes which already existed in the container will still be there after the restore.

sudo asr restore -s <APFS image> --sourcevolumename SourceVolume -t /dev/disk2 --erase

Like the last example, we restore to a new volume on the target APFS container disk. However in this case we are erasing the target, so any volumes which already existed are destroyed.

asr info -s <APFS image>

Assuming this image has been previously scanned (using the imagescan verb), this will display the volumes' names and UUIDs so they can be used with the --sourcevolumename or --sourcevolumeUUID options.

Restoring a snapshot

sudo asr restore -s <APFS image> -t /dev/disk2 --toSnapshot Snap1

This assumes that the image volume has a snapshot named Snap1. During the restore, asr will create a new volume in the container at /dev/disk2 and use that volume as the target of the restore. The resulting target volume will have the same contents as Snap1 on the source volume, and it will also have a snapshot with the same name (Snap1) and UUID as Snap1 on the source. This snapshot will match the live target volume right after the restore; the live volume can subsequently change, but the snapshot will remain the same.

Restoring a snapshot delta

sudo asr restore -s <APFS image> -t /Volumes/Target --erase --fromSnapshot Snap1 --toSnapshot Snap2

This assumes that the image volume has a snapshot named Snap1 and another snapshot named Snap2. Furthermore the target volume (mounted here at "/Volumes/Target") must also contain Snap1, with the same UUID and content. The result of the restore will be that the target volume will have the same contents as Snap2 on the source volume, and it will also gain a snapshot with the same name (Snap2) and UUID as Snap2 on the source. The restore will only need to copy the difference between the two snapshots, rather than the entire contents of Snap2.

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 "File -> New Image -> Image from Folder..." function and select the root of the volume. Save the image as read-only or compressed. "File->New Image->Image from <device>" is not recommended for restorable images.
  3. Scan the image with "Images -> Scan Image for Restore..."
  4. Select a volume and click on the "Restore" button. Then click on the "Image..." button to select the image you have scanned. Click Restore.

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.

asr maintains compatibility with previous syntax, e.g.

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:

this option is deprecated, but remains for script compatibility. Use -noverify instead.
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.

Compatibility with previous syntax is not guaranteed in the next major OS release.

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 transient in nature (e.g. there was an I/O error on the disk), and it is worth simply trying the restore again.

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 was originally focused on HFS+ volumes, but it has expanded to also include APFS.

hdiutil(1), df(1), bless(8), ditto(1), and what(1)

December 10, 2020 Mac OS X