APPLEJACK README

AppleJack 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 REQUIREMENTS
1. 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 :-)

INSTALLATION
Mount 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 USAGE
1. You can type 'manapplejack' 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.

If you get an error message saying that Apple Jack could not
be found type in the following address to let your Mac know
where it is located on your system.

/private/var/root/Library/Scripts/applejack.sh

3. Auto mode: You can let the script run through its tasks
automatically by typing 'applejackauto'. If you want the
machine to automatically restart at the end of its tasks, use
'applejackautorestart'. You can also tell the computer to shut
down automatically at the end by using the command line
'applejackautoshutdown'.
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 'applejackAUTO' 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.

CREDITS
Current Version: There would probably be no AppleJack for
Leopard or Snow Leopard without the yeoman efforts of Steve
Anthony <sma310 at lehigh dot edu>,
<http://sourceforge.net/users/ultramathman/>. 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.

DONATIONS
If you would like to contribute to further AppleJack development,
please visit <http://theapotek.com/donations/?i=AppleJack>. 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:haltbyroot:Shuttingdownduetopowerloss!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:
applejackuninstall
If 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.shuninstall
Please 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 & INFORMATION

AppleJack Project Page on SourceForge:
<http://applejack.sourceforge.net>.
Sign up for the applejack-report mailing list to be kept abreast of
developments:
<http://lists.sourceforge.net/lists/listinfo/applejack-report>
AppleJack News: <https://sourceforge.net/news/?group_id=79562>
AppleJack Help Forum: <https://sourceforge.net/forum/forum.php?
 forum_id=271611>
Project Discussion: <https://sourceforge.net/forum/forum.php?
forum_id=271610>
Bug Reporting: <https://sourceforge.net/tracker/?
group_id=79562&atid=557034>
Support Requests: <https://sourceforge.net/tracker/?
group_id=79562&atid=557035>
Feature Requests: <https://sourceforge.net/tracker/?
group_id=79562&atid=557037>
Donations: <http://sourceforge.net/project/project_donations.php?
group_id=79562>

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 'SystemStarterstartDisks' 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). manapplejack 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.css
tore
-/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 'applejackauto', script will
run in auto mode, and exit at end. If, however, you
invoke the script by typing 'applejackautorestart', 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
AppleJack

Additionally, 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
memtest

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

I 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]deepcleancachefiles (Allows you to run the deep

clean without having to run
AUTO)
[1]verifyharddrive(S.M.A.R.T.) (Not implemented yet. Can't
get smartctl to work on all
drives.)
[2]testmemory
[3]blesssystemfolder
[4]disableautologin
[5]disableloginitemsforauser
[6]restorenetinfodatabasefrombackup (10.4.xonly)
[7]disablesystemconfigurationfiles
[8]disableNetInfoNFSmounts (Only if you've set them up in
NetInfo rather than fstab)
[9]enablenewmachinesetup

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