Curby's MacOS Hooks (C'Smosh) README By Michael 'Curby' Lee v1.00.05, 2004-02-07 ====================================================================== - Introduction ====================================================================== System hooks in MacOS X are used to run custom code on certain events. There is builtin support for login and logout hooks, and other hooks such as sleep and wake-up hooks can be supported through a freeware project called SleepWatcher. A shareware utility called Scenario supports hooks related to idleness and hotkeys too. There are many uses for these hooks, including setting custom volume levels and setting iChat status. There are even more uses for lab/ corporate environments, such as setting up a consistent home environment upon log-in, performing backups, etc. ====================================================================== - Installation via Makefile ====================================================================== To come. Both installation methods require administrator access. ====================================================================== - Manual Installation in three steps (and 3*10^8 substeps) ====================================================================== First, set up the file system ----------------------------- Make a common directory for system hooks such as /Library/Hooks. This directory can use permissions as strict as 755 and should be owned by root:admin or root:wheel. Make a log file such as /var/log/hooks.log. This directory can use permissions as strict as 600 and should be owned by root:admin or root:wheel. Users that cannot write to this log will automatically write to a log in their ~/Documents directory. Users will be able to run custom scripts as well. Such users will want to create a ~/Library/Hooks folder. Secondly, install the files --------------------------- Copy the contents of the Hooks directory into /Library/Hooks. If you wish, copy the exampe_userhook.sh into each user's ~/Library/Hooks folder. Lastly, let the system know --------------------------- To enable the login/logout hooks, type the following. IMPORTANT: Either use sudo or perform the actions as root. The commands will appear to work if performed as a normal user. sudo defaults write com.apple.loginwindow LoginHook /Library/Hooks/loginhook.sh sudo defaults write com.apple.loginwindow LogoutHook /Library/Hooks/logouthook.sh To enable sleep/wake-up hooks, install SleepWatcher, Scenario, or a similar software. If you install Sleepwatcher and the related StartupItem, you may have to soft-link the default hooks: ln -s /Library/Hooks/sleephook.sh /etc/rc.sleep ln -s /Library/Hooks/wakehook.sh /etc/rc.wakeup If you use Scenario, you can also configure the other hooks. ====================================================================== - How it works ====================================================================== Overview -------- The first thing to run is a hook in /Library/Hooks. That script then sources /Library/Hooks/hookcommon.sh which initializes some common variables and sets up a logging mechanism. The original script then looks for and runs applicable user scripts. Lastly, the original script runs user-independent commands. These run last to ensure that system policies will overwrite user settings. Gory Details ------------ Login and Logout hooks are called with the associated username by default. This can be accessed using the variable $1, and is used for logging as well as looking for a user script. hookcommon.sh expects $1 to be filled. Hooks that aren't called with a username can set the $HOOK_DEFAULTUSER variable, causing hookcommon to use 'root' as the user. hookcommon uses /var/log/hooks.log for its default log. Users that don't have write permission into that file will write to a log in their Documents directory. Logging has an autoindent feature. Any line with a `{' will open an indented block, and any line with a `}' will close the block. This indenting is naive; it doesn't do any parsing. hookcommon sets up the following variables: HOOK_USER, HOOK_PAD, HOOK_LOGFILE, HOOK_INDENT. It also provides a LogLine function that prints a line of text to whatever logfile the user has write access. The hook script calls the user script using sudo, so the user doesn't get root priveleges when running the custom script. The original script called for using su, which doesn't work well in this case. Make sure that root can sudo anything (this is the default in MacOS) and everything should be fine. User scripts are called with the user's name and indentation level. The user script wouldn't normally know the current indentation level because sudo sets up a new environment for the user script. After all appropriate user scripts are found, the original hook script runs system-wide commands, overwriting user commands with system policies as necessary. ====================================================================== - Known issues ====================================================================== * Versions: All Issue: The process of going to sleep is limited to fifteen seconds, after which the system will force a sleep. Make sure your sleep script isn't doing anything terribly intensive. Solution: If you must perform a lengthy operation just prior to sleep, create a custom script that first does the heavy lifting and then uses AppleScript to tell the Finder to sleep. ====================================================================== - Versioning ====================================================================== Versions are given by the string `v#.$$.%%' such that: # represents the version or major release number, and increments after a significant rewrite of the code or when changes cause some incompatibility with previous versions. $$ represents the minor release number, increments when a new feature is added or a large number of small changes are made, and resets when the major release number increments. %% represents the patch number or build number, increments whenever any change is made to keep track of minor changes, and resets when either of the above values increments. Versions are also labeled by their release date in ISO standard date format: `YYYY-MM-DD'. ====================================================================== - QFAO (Questions, Frequently-Asked and Otherwise) ====================================================================== Q: Huh? A: Yeah, totally.