manpagez: man pages & more
man asr(8)
Home | html | info | man


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. 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 speci-
     fied 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 spec-
     ifying server, source has to be a UDIF disk image. Restoring from a mul-
     ticast 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 bet-
     ter 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 (includ-
                   ing 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
                                  filesystem 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.  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.

                   --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).  Pass-
                                  ing --erase with --file indicates any exist-
                                  ing 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 speci-
                                  fied, 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 writ-
                                  ing 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 multicast stream before
                                  exiting, allowing the client to stop in case
                                  of server failure/stoppage.  It defaults to
                                  0 (i.e. never time out).

                   --puppetstrings
                                  provide progress output that is easy for
                                  another program to parse.  Any program try-
                                  ing 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.  Skip-
                                  ping verification is dangerous for a number
                                  of reasons and should never be used in pro-
                                  duction systems.

                   --allowfragmentedcatalog
                                  allows restores to proceed even if the
                                  source's catalog file is fragmented (in par-
                                  ticular, if it has more than 8 extents).  By
                                  default such restores are disallowed.  Cata-
                                  log 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 impracti-
                                  cal.  This option only makes sense if the
                                  source specifes an HFS+ filesystem variant.
                                  It is otherwise ignored.

                   --corestorageconvert
                                  Cause target to be converted to a Core Stor-
                                  age 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.

                   --SHA256       forces the restore to use the SHA-256 hash
                                  in the image during verification.  If the
                                  image doesn't contain a SHA-256 hash, then
                                  an error will be raised.

                   --sourcevolumename
                                  tells asr which volume in the source con-
                                  tainer 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.

                   --sourcevolumeUUID
                                  tells asr which volume in the source con-
                                  tainer 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.

                   --targetnewvolume
                                  can be used in place of the --target option
                                  for APFS restores, to tell asr that a new
                                  volume should be created on the target as
                                  the recipient of the volume data being
                                  restored.  The required argument should be a
                                  synthesized APFS container disk.  See the
                                  section RESTORING WITH APFS FILESYSTEMS
                                  below for more details on the use of this
                                  option.

     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 multicast-
                              ing (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 infrastruc-
                                          ture 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 adver-
                                          tised 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 oper-
                                          ation. 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.  SHA-1 and SHA-256 hashes are used.
                   Also determines if the disk image is in order for multicas-
                   ting, 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 cat-
                             alog 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.

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

                   --plist
                          writes its output as an XML-formatted plist, suit-
                          able for parsing by another program.


RESTORING WITH APFS FILESYSTEMS

     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 sin-
     gle system.  This requires understanding what is meant by a valid system.

     In order for an APFS volume to 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 vol-
     ume.  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:

     Container Restore
           If target is an actual disk partition, either of type Apple_APFS or
           some other type, then asr will block restore the APFS container to
           the target partition, setting the partition type to Apple_APFS.
           The resulting container on the target will then contain all the
           same volumes as the container in the source.

     Volume Restore
           If the target is an individual volume within an existing APFS con-
           tainer, 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, cre-
           ating those volumes on the target if necessary.

     Volume Restore with Creation
           if the --targetnewvolume option is used in place of --target, and
           its argument is the synthesized APFS whole disk, then asr will cre-
           ate a new volume in the given container, 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.


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 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 perfor-
     mance.  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 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).  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.

     Restoring a complete APFS image
           sudo asr restore -s <APFS image> -t /dev/disk1s2 --erase
     In this case /dev/disk1s2 is a partition of arbitrary type, potentially
     including Apple_APFS.  The entire container is restored as-is, and all
     volumes in the source will be replicated in the target.  The target par-
     tition is completely erased.

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

     Creating a new APFS volume on the fly
           sudo asr restore -s <APFS image> --sourcevolumename SourceVolume
           --targetnewvolume /dev/disk2 --erase
     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.  Note that
     there is no --target (-t) option, instead the container disk is specified
     by the --targetnewvolume option.

     Looking at an image's volume names/UUIDs
           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.


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 "File -> New Image -> Image from Folder..." func-
          tion and select the root of the volume.  Save the image as read-only
          or compressed.  "File->New Image->Image from <device>" is not recom-
          mended 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.


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 compatibil-
                ity.  Use -noverify instead.

     -blockonly
                this option is deprecated, but remains for script compatibil-
                ity. 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 opera-
     tion.  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 underly-
     ing 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.


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

Mac OS X 10.13.1 - Generated Thu Nov 9 18:32:47 CST 2017
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.