APPLEJACK READMEAppleJack is a shell script intended to assist you in trouble-shooting startup problems in Mac OS X. In many situations it can help resurrect an apparently dead system by cleaning up the mess left by system crashes: disk directory errors, buggy caches, corrupted preferences, etc. AppleJack is designed to be run only in single user mode. Running this script while logged in as a user can crash your operating system (especially if you use it to delete the system's virtual memory or cache files), which would be more than a little bit counterproductive, since we're out to solve problems, not cause them. Beyond these basic functions, AppleJack can also test your RAM (if you choose to install the included memtest), disable auto login, disable login items for a user, bless a new System folder, and more. These last options are only available from the expert menu (accessible by hitting x from in AppleJack's main menu), and should be considered experimental at this point.APPLEJACK REQUIREMENTS1. AppleJack v 1.6.x requires Mac OS X 10.4.x, 10.5.x or 10.6.x on Intel or PowerPC (but see known issues for 10.4, 10.4.1, 10.4.2). For Panther and Jaguar users, please use the latest 1.4.x version available.2. The ability to boot into single user mode (some users may be locked out from single user mode because of corporate IT policies and open firmware security locks).3. A wired keyboard, unless you are using Mac OS X 10.4.3 or later. (Previous versions of Mac OS X do not support wireless keyboards in single user mode.)4. An ability to read documentation, and follow instructions :-)INSTALLATIONMount the AppleJack disk image, and run the AppleJack.pkg installer.If you'd like to install the included Memtest OS X RAM testing utility, choose customize during the install, and select the Memtest OS X check box. Installing Memtest with AppleJack allows you to run RAM tests from within AppleJack (see Appendix B: "Expert Mode" below for more details).Installing over old versions: If you installed AppleJack using the default location, you can install right over the old installation. If not, you will first need to manually remove the applejack.sh file from wherever you've put it.APPLEJACK USAGE1. You can type 'man applejack' in a terminal window for complete usage instructions.2. Restart your computer. When the "bong" sounds, hold down the command and s keys until you get lots of text appearing on a black screen. You are now in single user mode. If you've used the installer, you should just be able to type 'applejack' at the prompt and be on your way.3. Auto mode: You can let the script run through its tasks automatically by typing 'applejack auto'. If you want the machine to automatically restart at the end of its tasks, use 'applejack auto restart'. You can also tell the computer to shut down automatically at the end by using the command line 'applejack auto shutdown'.3a. Deep Auto mode: If you want to let AppleJack clean out all cache files, including the Launch Services database and any cached User Pictures, use 'applejack AUTO' instead. Use this if you still have problems booting after running AppleJack already.4. Interactive mode: To run through just one task, or to run the script manually, type 'applejack' and then choose tasks from the menu. Running the script in interactive mode has the benefit of giving you options for working with user level cache and preference files, not just the default system level caches and preferences. To select an option, type the highlighted number or letter associated with the action, and then hit return. Whenever you enter a choice in AppleJack, you will need to hit return for that choice to take effect.4. Corrupted preference files are moved into a directory that will mirror the original preference directory, with (Corrupt) added to the directory name. For example, corrupt preferences files found in ~/Library/Preferences will be moved to ~/Library/Preferences (Corrupt). After running AppleJack, you'll probably want to take a look at them (and most likely throw out those folders). As of version 1.4.2, AppleJack now creates a copy of the directory tree inside the (Corrupt) folder so that if any files were deeply nested inside the original preference folder, they will be placed in an identical directory hierarchy in the new (Corrupt) folder. This way, if for any reason you would want to move a preference file back, you know where it should go. 6. AppleJack has a primitive logging mechanism. It writes a journal of most of its activity to /var/log/AppleJack.log. AppleJack will automatically reset the log the next time you run it, if the file should ever reach a size somewhat over 500k.CREDITSCurrent Version: There would probably be no AppleJack for Leopard or Snow Leopard without the yeoman efforts of Steve Anthony , . He put in countless hours into solving the Leopard startup riddle, thereby giving Leopard compatibility a chance at seeing the light of day. Also, I wish to thank Dave Provine at Premier Mac for helping kickstart the development process by providing 3 test partitions of Snow Leopard for me to work with. A big thank you.Testers: Thanks also to Charly Avital, Joshua Long (MacTech Magazine), John Stiver, Thomas Ungricht, and Matthew Weinman for risking their files (and their sanity) by helping test AppleJack before release on repeated occasions. Thanks also to all of you (too many to name) who have pitched in with the occasional bug report or test results.Past Versions: I would like to extend a special thanks to Josh Wisenbaker at ComputerTree Technologies whose expertise in Mac OS X allowed him to show me how to make diskutil work in Single User Mode under OS 10.3.x, and 10.4.x. Thanks also to an Ars Technica forums user (who wishes to remain anonymous) for showing me the black art of testing for aliases while in single user mode. DONATIONSIf you would like to contribute to further AppleJack development, please visit . Any amount is greatly appreciated. Also, I do gratefully receive suggestions for improving the AppleJack script. Please post suggestions to the feature request link mentioned above.KNOWN ISSUES: (all versions) Sometimes odd error or log messages will show up from the Mac OS X subsystem and insert themselves right into AppleJack's interface. In single user mode, the screen is the console, so it is extremely difficult to suppress all these messages. Normally you can ignore them as long as you can still use the interface. (all versions) After running AppleJack and deleting the cache files, some users experience odd behavior in the finder or with application launches. This is because Mac OS X did not rebuild the lost cache files correctly. Behaviors include: Finder keyboard shortcuts not working, menu items not appearing correctly, user images gone, inability to launch various applications. A restart will usually correct these errors. Some users of G5 systems have reported that the fans ramp up very fast. This is not related to AppleJack, but is due to the fact that the thermal controllers are not loaded while in single user mode. If this condition persists after restarting into Mac OS X, you may have run into one of the many known fan-management bugs. See the apple.com support forums, or macosxhints.com for extensive postings on this topic. (v 1.4.2) On Mac OS X 10.4.3, some users report that when launching some of the services necessary for permissions repair, the system will take a long time (3-4 mins) before being launching the actual permissions repair. I do believe this issue will have been addressed by the 1.4.3 release of AppleJack. (v. 1.5) On Mac OS X 10.5.x, permissions repair seems to have slowed down again. I'm not sure why diskutil behaves so differently in single user mode from when being invoked in the context of the Disk Utility GUI program, but there you have it. It does work, but it is slower than on Tiger. (v. 1.4) Some users running Mac OS X 10.4, 10.4.1, and 10.4.2 report that their system will suddenly start spitting out a line like 'Limiting closed port RST response from 251 to 250 packets per second'. Some users have been able to continue to use AppleJack by ignoring the lines being written to the screen, while others appear to have their computers hang when this happens. This appears to be related to changes in the boot sequence introduced in Tiger, and the manner in which a user upgraded to Tigerthough no clear pattern has emerged. It appears that the new boot mechanism (relying upon launchd rather than init) has some issues when used in single user mode. Anecdotal reports indicate that this problem might have disappeared in 10.4.3. (all versions) AppleJack and fsck (disk repair). When you run AppleJack in auto mode, it's hard to know whether the disk repair actually has finished repairing all issues on the hard drive. This is because the disk repair utility (the "fsck" program) returns a 0 when finished if a) there were no errors, or b) the errors were fixed. There might possibly be errors that weren't fixed, but there's no way for AppleJack to know this. If you'd like to make 100% certain that your hard drive has been repaired, I recommend you run AppleJack in manual mode so you can repeat the disk repair routine until your disk gets a clean bill of health. If your disk never gets a clean bill of health, it's time to back up your data and either reformat or use a tool like DiskWarrior. The built-in fsck has its limitations. (all versions) Shutdown due to power loss while running AppleJack. Users who are running AppleJack with an uninterruptible power supply (UPS) plugged into their USB ports report that shortly after the repair permissions task starts, they see the following error message before the CPU is halted: shutdown: halt by root: Shutting down due to power loss!The solution to the shutdown is to unplug the USB cable from the UPS.TO UNINSTALL:If you are running AppleJack version 1.4.3 or greater, you can uninstall AppleJack simply by adding the 'uninstall' parameter when you run the script in single user mode, like this:applejack uninstallIf you want to uninstall AppleJack without booting into single user mode, you can do it by opening a Terminal window and typing:sudo /private/var/root/Library/Scripts/applejack.sh uninstallPlease note: The uninstall command will not remove the optional Memtest OS X files. If you selected to have them installed during the AppleJack installation, you will need to remove those files manually.SUPPORT & INFORMATIONAppleJack Project Page on SourceForge: . Sign up for the applejack-report mailing list to be kept abreast of developments: AppleJack News: AppleJack Help Forum: Project Discussion: Bug Reporting: Support Requests: Feature Requests: Donations: VERSION HISTORY#1.6+ Snow Leopard compatibility [feature 2845796] (Thanks again to Steve Anthony)- Improved limits on output from syslog to STDOUT- Simplified startup of services on Leopard and Snow Leopard- Fixed bug in creation of user account lists in Snow Leopard where system accounts would show up+ S.M.A.R.T. status verification is now being done in the expert mode. I still want to implement this using smartmontools, but for now diskutil will do.+ Blessing of Mac OS X System folders on attached volumes is now possible. This is a primitive bless, ie, it does not create boot files, but simply blesses the chosen System folder and (optionally) sets it to be used for startup on next launch.#1.5.1- Fixed bug [ 2086281 ] Memtest installed with wrong ownership- Fixed small bug in chooseUserDirectory()#1.5+ Leopard compatibility! (Thanks Steve Anthony!)- Improved console output suppression from launchd processes.- Improved the process of finding valid user directories, drawing on directory services (dscl), /etc/passwd, and /Users directory as needed. Users can now be chosen by user id or user name, as well as the old method of entereing the home directory. - Logging is more complete#1.4.3- Compatible with Intel-based Mac OS X systems.+ Added an automated uninstaller routine, to enable easy and almost foolproof uninstallation of AppleJack.+ Added /var/root/Library/Caches to the system cache cleanup routine.+ Experimental expert mode exists, but is currently hidden until it can be tested further. (see Appendix B). The only well-tested options at this point are the memory test using the included Memtest utility, and the option to disable auto login.- Improved the internal coding of user-input prompts. Uses a standardized interface for these functions now.- The preference file check now uses a null byte character to separate files rather than an arbitrary "improbable" string.#1.4.2+[Feature request 1214481]: When corrupt preference files are moved into the Preferences (Corrupt) folder they are now given the same path (directory structure) that they had in the Preferences folder, so a user can see where the files existed before being moved.- [Bug fix 1025554]: Added an alias test to the preference file validator, so it will not identify aliases with .plist extensions as corrupt. (This had been a problem, for example, with BBEdit's "Recent Items" aliases. - AppleJack now correctly handles cases where a requested preference directory does not exist.- [Bug fix 1214475]: Removed .xml files from the preference file check routine, except in the /var/db/SystemConfiguration directory (applies to 10.2 only).+ Added checking of root preferences (/var/root/Library/Preferences).+ Improved handling of background processes, but still a long way to go to get the interface perfectly clean.+ In the virtual memory cleanup, added an option (in manual mode only) for users to delete their safe sleep image. (10.4.x only.) This will probably be rolled into a separate function in an upcoming release.+ In the virtual memory cleanup of the application, added removal of working sets (in app_profile) to the virtual memory cleanup routines. (10.4.x only.)+ Improved the user directory listing. AppleJack grabs home directories from NetInfo instead of from just doing an `ls` on the User directory. This might yield extraneous entries (especially entries for system daemons etc.), but is cleaner than guessing at different end-users' folder structure.+ Improved the handling of the built-in commands to always use the ones in the /bin or /usr/bin directory, if available. This should help alleviate problems due to user-installed custom commands by the same name as well as custom aliases to those commands.+ If startup options are incorrectly entered, AppleJack now reports back correct usage rather than just ignoring the startup options (Thanks Charly).+ Standardized exit codes to conform to ideas in /usr/include/sysexits.h#1.4.1- fixed deep cache cleaning under Tiger to respect the new cache file names for launch services and user icons.+ improved the disk repair routine messaging, and implemented a limit for how many times disk repair is repeated on an irreparably damaged disk in auto mode.+ expanded some of the preference file checking to include .xml file extensions as well as the old (deprecated, but still in use) /var/db/SystemConfiguration directory.- removed 'SystemStarter start Disks' from the setup sequence of AppleJack for people running Tiger. Evidently, it's not necessary anymore.#1.4+ Enabled support for Mac OS 10.4 (Tiger).+ Changed AppleJack to allow for checking multiple user's preference files or caches without having to relaunch the routine.+ Improved the display of user directories for machines with many users.- Fixed a few errors in the man page and the ReadMe file.#1.3.2- Fixed a SERIOUS problem in the cache cleaning routine whereby an entire hard drive could be obliterated if the user's home directory was either typed in incorrectly or if it was a file vault rather than an actual directory system.- Improved the safety of the swap file removal routine- Cache cleanup now leaves cached user pictures untouched, except of course when running AppleJack in deep cleaning mode.+ Added a check routine for the /tmp and /private/tmp directories, since a missing temp directory is often implicated in boot failure. AppleJack 1.3.2 will create these directories and symlinks as needed when the drive mounts for write access.- Gave up on putting the man page in the correct location (/usr/local/man or /usr/local/share/man) and put it where it will be found on all OS configurations (/usr/share/man). man applejack should work on all systems now.- Removed the option to search a user's home directory for cache files outside of the ~/Library/Caches directory since this is out of scope for this application and just added to the bloat and complexity. It could also lead to some dangerous file deletions for the unwary user.- Cache cleanup now removes the prebindOnDemandBadFiles list.- The script now changes location at startup to /private/var/tmp, in order to minimize the potential for damage from any lingering bugs in the code. #1.3.1.1- Bugfix in the disk repair section. (line 328 loggin: command not found).#1.3.1+ Finally added a decent installer! (I know I know, this should have been in here a year ago)+ Improved the logging.+ Added /System/Library/Caches to the cache cleanout routine- Kept the cache cleaning routine from removing the LaunchServices cache since it's not really a cache, but more of a preference file. I don't know why Apple insists on keeping something that stores preferences in the Cache directory, but there you have it. + Added /etc/mach_init.d directory to the .plist validation routine.+ Script feedback improvements, including coloring to make options stand out.- Changed the option 'reboot' to 'restart' to make it more consistent with Apple lingo.#1.3+ Added workaround for diskutil in Panther systems+ Added a utility for validating .plist files. Corrupted files are now moved to /Library/Preferences (Corrupt). Expanded this facility to include an option in interactive mode to check individual user's preferences.+ Added a very primitive form of logging, so you can have a record of what AppleJack did. It is located at /private/var/log/AppleJack.log- changed the user level cache file deletion routine to be more like the preference validator, allowing AppleJack user to choose a specific account to target for cleanup.+ Added security checks so that (for example) disk repair will not run if there is write access to the root volume.+ Added security check for single user mode. A warning is now posted.- Made certain routines specific to Jaguar or Panther.- A bazillion other little code improvements.#1.2.2.1- Cosmetic fix for OS version check- Edits on man page.#1.2.2- Forced script to skip permissions repair on Panther systems.#1.2.1+ Added another system cache file to the deletion routine+ /System/Library/Extensions.mkext- Added man file documentation for AppleJack- Added warning message to installer, if attempt is made to run if from outside the distribution folder.#1.2.0.1- Minor fix to the installer+ Also removes /System/Library/Extensions.mkext (how could I have overlooked that one?)#1.2+ Added a basic installer (finally).- Fixed issue where swap files and cache files weren't being dealt with if resident on file systems other than the root filesystem. (If someone has a better way of reading the value of $swapdir in /etc/rc, please let me know.- Better syntax in cache deletion routine.+ More complete deletion of cache files. Now also removing:-/private/var/db/volinfo.database-/private/var/db/NetworkInterfaces.xml-/private/var/db/BootCache.playlist-/Library/Caches/com.apple.LaunchServices.LocalCache.csstore-/System/Library/Extensions.kextcache- The search for more cache files routine is now more inclusive (and more dangerous!).- simplified menu.- tried to make usage more explicit and straightforward.- Added exit proofing--forcing a user to reboot rather than exit to multi-user startup, if certain dangerous actions are performed.#1.1+ Enabled file system checking on journaled file systems, through using the '-f' option with fsck, but only for journaled volumes.- Old version of the script rebooted at the end of an automated run; the new version of the script just exits. + Added command line option for running in automated mode with a reboot:If you invoke the script with 'applejack auto', script will run in auto mode, and exit at end. If, however, you invoke the script by typing 'applejack auto restart', the script runs and reboots when finished.- Fixed a bug where the script would exit if a user typed a key that was not an option in the menu.- Minor code clean up.#1.0- Fixed an issue where disk repair incorrectly assumed success- Changed some of the letter codes for increased readability- Improvements in user output#0.9 - Original beta release.____________________________________________________________APPENDIX A: What Is Installed, and Where?/private/var/root/Library/Scripts/applejack.sh - the AppleJack script/usr/share/man/man8/applejack.8 - man page for AppleJack/Library/Documentation/AppleJack - ReadMe and License files for AppleJackAdditionally, if you choose 'Customize' during the installation process, you can choose to install the Memtest OS X package, which will install the following:/usr/local/sbin/memtest - the memtest memory testing program/usr/share/man/man8/memtest.8 - man page for memtest/Library/Documentation/memtest414 - the documentation for memtestThe installer also modifies the root user's profile (/var/root/.profile) in order to create a friendly usage reminder message at startup in single user mode.____________________________________________________________APPENDIX B: Expert ModeI am currently beginning development of an "expert" troubleshooting menu. It is available by pressing x at the first menu presented when you run AppleJack. Not all the tasks have been fully implemented, and the memory test requires that you either choose to install Memtest OS X from the customize menu of the AppleJack installer, or that you already have a version of Memtest OS X greater than 4.12.[0] deep clean cache files(Allows you to run the deep clean without having to run AUTO)[1] verify hard drive (S.M.A.R.T.)(Not implemented yet. Can't get smartctl to work on all drives.)[2] test memory[3] bless system folder[4] disable auto login[5] disable login items for a user[6] restore netinfo database from backup(10.4.x only)[7] disable system configuration files[8] disable NetInfo NFS mounts(Only if you've set them up in NetInfo rather than fstab)[9] enable new machine setupIf you have a computer that is suitable for testing software on, and you would like to help me test some of these functions, I would greatly appreciate it. I suspect the ones which would be of any immediate helpfulness or usefulness would be option 1, 2, 4, 5, 7, and 8. If you have memtest installed, try out the memtest (option 2). It seems to be working quite well. More in-depth explanations of each function are available from the expert menu. Just pick your option, and a short message will explain what it does before prompting you to continue.Please post bugs to the bug reporting link mentioned above, and please attach the AppleJack log with your report.Thanks!