Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.





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 accom-plished accomplished
     plished 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
                                  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.

                   --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 filesys-tem filesystem
                                  tem 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 multicast 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 follow-ing following
                   ing 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 par-tition partition
                   tition 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 (multicast-ing (multicasting
                   ing 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 mul-ticast multicast
                              ticast 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 operation. Once exceeded, the
                                          server will stop the stream and wait for new clients before multi-casting multicasting
                                          casting the image file. It defaults to 0 (e.g. never stop multi-casting multicasting
                                          casting 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, mul-
                                          ticast 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 impractical.

BUFFERING
     The following options control how asr uses memory.  These options can have a significant impact on per-formance. performance.
     formance.  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 buffer-ing buffering
     ing 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 configura-tion.plist. configuration.plist.
     tion.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>
           (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 tar-get's target's
     get'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 mes-sage message
     sage 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, how-ever, however,
     ever, 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 dur-ing during
          ing 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
     installation helper application for various Apple computer products.  ASR has been used in manufactur-ing manufacturing
     ing 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 net-work network
     work 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

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback