đ Apple Software Restore 1.3.2 Quick Reference Apple Software Restore (ASR) is a utility application that will exactly restore disk images created with Disk Copy to a target hard drive. ASR is designed to automate the duplication of a software configuration onto any number of computer systems. It has a configurable preferences file that allows the application to preset features, show or hide features (depending on the intended user), and automatically restore and shutdown a system. It can be configured for keyboard/mouse control, can be controlled via an ADB barcode scanner, or can be scripted via AppleScript. ASR can restore a disk image stored locally, or from an image on an AppleShare (or AFP compliant) file server. This reference is intended for people who will be creating disk images for ASR to restore, and/or configuring ASR for a specific purpose. Please note that ASR allows itself to be configured to very quickly and very easily erase and restore a given hard drive. Take care that during the development of your image content or configuration setup you do not accidentally erase and overwrite data. This Quick Reference will explain the basic functions of ASR, and describe the different settings available. Changes from Apple Software Restore 1.3.1 Ą ASR will enter background mode from AppleScript 'Launch' command, obsoleting the 'LaunchASR' Scripting Addition Ą Corrected an error when restoring an HFS+ volume Ą If only a single image is dropped on ASR or available, and the splash screen and configuration resources are present in the image, they will be used instead of the corresponding resources in the preferences files. Other resources (in particular ones related to localization) in preferences files will still be used Ą The ImageScan Scripting Addition can optionally perform a volume verification scan when scanning a disk image. This scan is the same as running Disk First Aid on the mounted disk image volume. This is turned on by default in the example AppleScripts Ą ImageScan and ASR 1.3.2 support block checksumming when restoring an HFS+ formatted image Ą The STR# 9000 resource can contain entries to files by path, and can specify the blessed system folder without referencing the folder name Ą Updated ASR and ImageScan to support a block checksum. If restoring an HFS+ volume with a block copy, a high speed block checksum will be used to verify the copy (if the image has been ImageScanned with the latest version) Ą The Apple Upgrader can use ASR to restore an image as an alternative to the Apple Installer Changes from Apple Software Restore 1.3 Ą ASR now fully supports restoring images to HFS+ volumes. The source disk image can be either HFS or HFS+. When running ASR under an OS that supports HFS+ images, there is an additional popup menu under the 'Erase Disk' checkbox. This allows the user to format the target volume the same as the source image (the default), or HFS or HFS+ regardless of the source image volume format. Changes from previous versions of Apple Software Restore ASR 1.1.3 was shipped with certain PowerBook models All previous versions of ASR were shipped with the Apple Software Restoration CD series, available to Apple Service Providers. ASR 1.3 replaces all previous versions. Basic Functions Ą ASR supports restoration of a disk image. ASR can restore a Read-Only or Read-Only compressed disk image created by Disk Copy 6.1.3 (or greater), provided it is ImageScanned first. Previous versions of ASR only supported restoration of software from a folder structure of files commonly known as a 'Custom Mac Bundle'. ASR will still restore this older format in addition to disk images. (Note that the Custom Mac Bundle format is undocumented, and its creation as a source for ASR is unsupported.) Ą ASR can be controlled by AppleScript. See the AppleScript Dictionary for the specific structure of the Restore AppleEvent. There are also some simple example AppleScripts included with the CCK. In order to launch ASR in a mode where it will accept AppleEvents, you must use the 'Launch application "Apple Software Restore"' syntax in AppleScript. Ą Restoration options. ASR can be configured to restore the files/folders in a source image in three different manners: Restore in place, Erase Disk, or neither. -When Restoring in place, all files being copied will overwrite any existing files that are on the target disk, but will leave all existing information intact. Note that from AppleScript, when restoring in place a destination folder can be specified in addition to just a destination volume. This allows one to restore an image in place to a sub folder of a given volume. When restoring an image in place to a subfolder, the contents of the image is copied to the target folder (vs. a folder named for the image with the content copied to the folder). -When Erasing the Disk, the target disk will be erased (in the chosen volume format), and the files/folders from the source image will be copied over to the target. -When neither option is selected, ASR will move all the existing data on the target disk to a folder named "Original Items", then copy all files/folders from the source image. When erasing the target disk, ASR will copy all the information from the source image exactly, including volume level information. This means that applications and extensions that store information concerning the volume will continue to function once restored to a new disk. For example, aliases will continue to function on the newly restored volume. When not erasing the target disk, ASR will perform a copy operation similar to copying files in the Finder. Applications whose preferences depend on specific volume information may not function without being reinstalled, and all aliases may not resolve. In addition to these three options, there are two additional selections that may be configured before restoring in any manner: Restore System Folder or Restore Everything Else. By default they are both checked. If System Folder is unchecked, everything from the source image will be restored except the blessed System Folder. If Everything Else is unchecked, only a blessed System Folder will be restored. If a blessed System Folder is not present, or is the only item present, unchecking these options may result in nothing to restore. In that case, the status area in the main selection dialog will reflect this, and the restore button will be disabled. Ą Customization via a preferences file. Previous versions of ASR allowed customized behavior via a configuration resource stored in the application itself. Additionally, string messages and splash screens could be customized by changing the resources in the application. Any resource in ASR can now be stored in a external preferences file. An ASR preference file can be -double-clicked -dropped on ASR -in the same folder as ASR -in the boot system preferences folder. -in the image itself (only the 'PICT' splash screens and 'CFIG' configuration preference) In looking for a preference file, ASR searches for a file with creator 'ERNI' (ASR's signature), and type 'pref'. If such a file is dropped onto ASR in the Finder, then ASR will use that file. Otherwise, it first searches in the folder which contains ASR itself, then it looks in the active system's Preferences folder. If more than one such file exists, ASR will use the first file it finds (which means the first file in catalog order, if more than one are in the same folder). If several valid preference files are dragged onto ASR, the first one seen will be the one used. Note that it is also possible to drag a preference file as well as one or more volumes or image files onto ASR, and it will use the volumes and images instead of the Configurations folder, as well as using the preference file appropriately. If a single disk image is dragged onto ASR (or is the only configuration available in the Configurations folder), and it contains PICT resources ID's 1024 (Black and White) 1025 (Color), and CFIG resource ID 9000, they will be used for the splash screen and default settings. All other resources will be accessed via the preference method described above. Ą ADB barcode reader support. ASR can be configured such that configurations can be chosen via a ADB barcode reader, and buttons in the various dialogs that appear can be selected via a scanning the button name with a ADB barcode reader. Ą Disk cloning. If a mounted disk volume is dropped on ASR, it can be restored to any other mounted disk volume provided it is not the startup disk, the target disk being cloned, or the disk with the ASR application itself. System requirements and supported features Apple Software Restore requires System Software 7.5 or later. A/UX and Macintosh Application Environment (MAE) are not supported. Restoring disk images ASR has 5 basic windows: A splash screen that appears at application launch, a configuration selection dialog, an erase disk confirmation dialog, a progress dialog, and a restoration confirmation/error dialog. Additionally, an error dialog will appear if any part of ASR's operation fail. ASR looks for images to restore in a folder named 'Configurations' located in the same folder as ASR itself, or a folder alias named 'Configurations' in the same folder as ASR itself. If a 'Configurations' folder is not present, ASR will search the same folder that the application is in for images to restore (versions 1.3.1 and higher). Restoring mounted volumes Any HFS or HFS+ volume mounted on the desktop can be dropped on ASR, in order to restore it to another volume. Dropping multiple volumes or a combination of volumes and images onto ASR will cause them to all show up in the configuration dialog. User Interface Figure 1 shows the main configuration selection dialog, running under a version of the MacOS with HFS+ support. The name in the upper left corner is the filename of the ASR application itself. The number in the upper right corner is the version of the Application. The ? balloon in the upper right corner turns balloon help on and off. All the buttons and fields in ASR have balloon help describing their function. The Configuration area is a list of configurations found in the 'Configurations' folder, or a single configuration if an image was dropped on ASR, or the images found in the same folder as ASR (if a 'Configurations' folder was not present). The Description field displays a text description of the configuration selected. This is found in a text resource in the image being restored, or an external Readme file. The functions of the rest of the dialog are documented with balloon help. Ę Fig. 1 Preparing an image for use with ASR In order to use an image created by Disk Copy with ASR, it has to be a read-only or read-only compressed image, and it needs to have a file level checksum generated and added to it. The first step is to create the content you want to restore. Install the appropriate system software and applications you want on a target hard drive. Make sure that all the preference files are configured in the manner you want. Make sure the hard drive boots on the systems you are going to be restoring the image onto. If there are aliases on the hard drive, you can use the Fix Local Aliases AppleScript droplet to make sure the aliases are properly resolved. Once you have your content finalized, it is recommended that you defragment your drive. A volume with all its data contiguous on the disk will image to a smaller file (for both read-only and read-only compressed). Then run Disk Copy and Select "'Create Image from Disk...' from the 'Image' menu. Select your target disk, and save it as read-only or read-only compressed. See the Disk Copy manual for more details about imaging a disk. Note: When working with Macintosh OS Extended (HFS+) volumes, creating a disk image in a certain manner will result in ASR being able to restore it in a high performance 'block copy' mode. This is only available when restoring HFS+ images and erasing the target disk. In order to create a disk image of a HFS+ volume that can be block restored, when selecting a volume to create a disk image, hold down the shift key when pressing the "Ok" button. You should see a status dialog that is scanning the volume. When the save dialog appears, an additional item appears in the size popup: a volume size followed by (data size). If this item is chosen, or any volume size other than the one listed as '(partition size)', the resulting HFS+ formatted image will block restore under ASR. The indication that this is occurring during a restore is that the progress dialog will not display file names during the restore options, but just reference that all files and volume information is being copied. In the CCK, there is a 'Scripts' folder, and a Scripting Addition called 'ImageScan'. Place the 'Scripts' folder in the same folder as Disk Copy. If you are using Disk Copy 6.2.1 or greater, you can leave the "ImageScan" Scripting Addition in the 'Scripts' folder. Disk Copy will recognize this and make it available to AppleScripts run from Disk Copy. Otherwise, place the 'ImageScan' Scripting Addition in the Scripting Additions folder in the Extensions folder of the System folder (or the Scripting Additions folder in the System Folder of Mac OS 8). Additionally, there is an optional Scripting Addition, 'Play Sound'. If you place this in the Scripting Additions folder, the various scripts used in this CCK will play success or failure sounds when they have completed. Once you have installed these items, when you launch or return to Disk Copy you will notice an additional menu, 'Scripts'. This menu will display all compiled AppleScripts, as well as droplets that are in the 'Scripts' folder. You can execute these scripts directly from Disk Copy. There should be a menu item named 'Scan Image for ASR'. If you select it, you will be presented with a dialog asking for a disk image. Select the disk image you created previously. After a period of time (the larger the volume the longer it takes), Disk Copy will report that the AppleScript completed successfully. You can view the Disk Copy log to get information about the disk image scanned. Once scanned, you can place that disk image in the 'Configurations' folder, and ASR will recognize it and allow you to restore it. If you do not ImageScan the disk image, ASR will note that the checksum is missing, and will not allow you to restore the image (unless you change the preference below). Miscellaneous keyboard shortcuts -When in the confirm erase dialog, command-shift-o has the same effect as pressing the 'Ok' button. -When in the final dialog, holding down the option key will toggle the 'quit' button to 'try again', which will return to the main selection dialog. Options settings for ASR ASR's configurable options are stored in a resource of type 'CFIG', with ID 9000. A Resedit template is included with the preferences files in the CCK in order to view the resource. NOTE: All bits listed as "Unused" should be left unset (e.g. zero). Set = 1 Unset = 0 Ą Version: A number representing the current configuration version. Should be set to 1 (one). Ą BoxFlag Disposition This field is used by Apple Software Restore when restoring images in a manufacturing environment. It should always be set to 0. Ą Skip Desktop Rebuild Errors If set, then errors which occur while installing the desktop information do not cause the restore to fail. Note that if such errors occur while this is set, it is likely that the Finder will rebuild the desktop on the target volume the next time it is launched and the volume is mounted. Ą Use Explicit FileSystem Setting If set, then the value of the next setting ("Use HFS+ for New Volume") will determine what the 'Volume Format' popup menu will display by default. If unset, then the 'Volume Format' popup menu will default to 'same as selected configuration'. Ą Use HFS+ for New Volume If set, and the 'Explicit FileSystem Setting' is also set, then the 'Volume Format' popup menu will default to 'Macintosh Extended' volume format. If unset, and the 'Explicit FileSystem Setting' is also set, the 'Volume Format' popup menu will default to 'Macintosh Standard' volume format. If the 'Explicit FileSystem Setting' is not set, this preference has no effect. Ą Copy Boot Blocks from resource: If set, then the boot blocks are written from the System file's 'boot' 1 resource, instead of from the source releaseŐs boot blocks. This option is only valid if the source release is an image or whole volume. If the source is an old-style Custom Mac bundle, then the boot blocks must come from the 'boot' 1 resource. Should normally be unset (e.g. zero). Ą Auto Shutdown after restore: If set, the machine will automatically shut down after performing a successful restore. The shutdown will occur after the number of seconds indicated in the Shutdown Delay field. Note that this will only take effect if the next flag (Allow Shutdown after restore) is also set. Ą Allow Shutdown after restore: If set, then a button labeled "Shutdown" appears in the dialog box which is presented after a successful restore. If the "Auto Shutdown after restore" flag is also set, then the button will flash automatically when the auto-shutdown kicks in. Ą Show Splash Screen: If set, a dialog box with an attractive picture is displayed when the application is first launched. Otherwise, the main selection dialog will appear right away. The picture is taken from a resource of type 'PICT', either in a preferences file (see the previous section) or from the application itself. If Color Quickdraw is available, then a resource with name "Color Splash Screen" is used. If Color Quickdraw is not available, or if that resource could not be found, then a resource with name "Splash Screen" is used. Ą Show Expert Controls: If set, then the main selection dialog will show the check-boxes which control which parts of the image/bundle to restore. Otherwise, the boxes will not appear, and depending on the value of the "Lock Expert Toggle" flag, there will either be nothing in their place or a triangle control which the user can click to make them appear. Ą Lock Expert Toggle: If set, the visibility of the check-boxes which control which parts of the bundle to restore may not be changed; i.e. if the previous flag is set, then the check-boxes are visible and cannot be hidden. If it is clear, then they are hidden and cannot be revealed. This flag does not prevent user from changing the values in the check-boxes if they are visible. Ą Allow Autopilot: If set, then a restore will begin right away and bypass the main selection dialog if there is only one valid disk image to select, and only one mounted drive eligible for restoration. If there is more than one disk image, then this flag is ignored. Ą Show Erase Disk Control: If set, the check-box which controls whether or not the target volume is erased is shown, allowing the user to change the setting. Otherwise, the setting is given by the Erase Target Volume flag (below), and cannot be changed by the user. Ą Barcode mode: If set, the main selection dialog will not select one of the configurations from the list when it detects type-ahead characters until it gets an exact match for one of the files. If it detects a return key character when it has not made an exact match, it will beep and flash a large x in the barcode graphic above the Configurations field. Additionally, the Ok button in the confirm erase dialog can be selected if a barcode of "ok" is scanned, and the Cancel button in the Confirm erase dialog can be selected if a single return is scanned, of if a barcode of "Cancel" is scanned. The final dialog's buttons (Quit and optionally Shutdown) can also be selected via a barcode of their names. If this flag is clear, then type-ahead selection is as normal, similar to standard file dialog boxes. Ą Root System Folders only (bundles only - obsolete): If set, then only the root level of a bundle is searched for a valid System Folder. Otherwise, a System Folder anywhere in the bundle can be valid. This option is only valid if the release is an Custom Mac bundle. If the release is an image, then the valid blessed system folder on the image is always used. Ą Restore To Folder: Does nothing if the EraseTargetVolume flag (below) is set. However, if this flag is set and the EraseTargetVolume flag is clear, then instead of putting the original contents of the target volume into a backup folder, the original contents stay where they were, and the files which are restored are placed in a folder on the target volume called "Restored Items". It is recommended that the Restore AppleEvent specifying the specific folder desired be used instead of this preference. The AppleEvent is more flexible. Ą Skip Checksum: If not set, the checksum of the restored release is calculated and compared to the value contained in the bundle folder name. If they don't match, an error is reported. For images, the checksum is compared to the value taken from the 'cSum' resource in the image. For both images and disk cloning, an additional checksum is performed on the filenames and FileID's of those file names. Ą Leave Unwanted Files: If set, then the files whose names are given in 'STR#' resource 9006 will not be touched. Otherwise, these files are removed from the target volume after the final checksum is performed. The files listed by default should always be left in. Additional unwanted files and folders can be specified by adding more STR# entries. If a folder is specified then its contents are deleted/moved as well. The string "şÂ" (opt-b, opt-l) represents the blessed folder, so if the resource contains "şÂ" then that folder will be removed. To remove the Extensions folder you can put "şÂ:Extensions". Ą Copy Rest of bundle: If set, the contents of the release outside the System Folder are included as part of the restore. Otherwise, they are ignored. This option may be overridden by user actions (see Show Expert Controls). Ą Copy System: If set, the contents of the System Folder (if there is one) are included as part of the restore. Otherwise, the System Folder is ignored. This option may be overridden by user actions (see Show Expert Controls). Ą Erase Target On Failure: If this option is set, and Erase Target Volume is set also, then if a failure occurs during the restore (and once the target volume has been touched), then the target volume will be entirely erased before quitting the application. Note that this will not be done if the user holds down the option key during the final dialog (invoking the "Try Again" feature). Ą Restore In Place: If set, the contents of the source configuration image will be copied to the target volume, overwriting any file in the same place with the same name. Note that there is no checking performed against the copy, e.g. it does not matter if the file is newer, older, or a higher/lower version. If it has the same name as the source file it is overwritten. Additionally, the Erase Target Volume checkbox is disabled when this option is checked. Ą Skip Erase Warning: Does nothing if the EraseTargetVolume flag is clear. If the EraseTargetVolume flag is set, then if this flag is unset there will be a warning dialog box before the contents of the target volume are erased. If both flags are set, then there will be no warning, and the disk will be erased silently. Be very careful when changing this option. Ą Erase Target Volume: If set, then the contents of the target volume are erased before the restore takes place, as if by a disk initialization. This option may be overridden by user actions (see Show Erase Disk Control). Ą Auto shutdown time(seconds): How much time to wait (in seconds) before shutting down when the auto shutdown after restore option is set Ą Thermometer update ticks: How often in ticks (60th of a second) the status barber pole should update while calculating the checksum and rebuilding the desktop. Set to 0 for fastest possible. đ Apple Computer, Inc. Copyright © 1997-1998 by Apple Computer, Inc. The Apple logo is a trademark of Apple Computer, Inc., registered in the U.S. and other countries. Use of the ŇkeyboardÓ Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. Apple, the Apple logo, AppleScript, Mac, Macintosh, and PlainTalk are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Balloon Help is a trademarks of Apple Computer, Inc. PowerPC is a trademark of International Business Machines, Inc., used under license. Updated July 23, 1998