Installing

Installing

Xhooks is a radmind overload.  To install Xhooks, you need to have a radmind server running. Just copy the files over to the server and add them to your command files and run radmind and that is it!  If that sentence was too much to chew on, then here are detailed instructions, which are really instructions on how to use radmind with a little bit of Xhooks-goodness thrown in at the end.

NOTE, do not install Xhooks on a production system!!!  If you have never used Xhooks before, PLEASE BE CAREFUL!  It erases files and changes OS stuff and could delete all your files and make the computer NOT BOOT.  If you follow the plan, things should work fine, but just be aware that installing Xhooks for the first time on a production computer is worse than running with scissors, it is like playing dodge car on a busy highway at night...

Xhooks does not have an uninstaller.  If you install Xhooks and then delete the /Library/Xhooks folder YOUR COMPUTER WILL NOT BOOT.  This is because Xhooks changes the plist at /System/Library/LaunchDaemons/com.apple.loginwindow.plist and the change essentially makes it dependent on Xhooks being present.

One more major warning if you are unfamiliar with radmind.  It may take you 10 minutes to read this, but I am about to discuss a process that takes weeks if not months for newbies to learn.  Really.  If you are new to radmind, you should become familiar with the whole fsdiff, lcreate, lcksum, ktcheck, fsdiff, lappy cycle (FLLKFL) before you even ATTEMPT to use Xhooks.  Installing Xhooks on the radmind server is a fairly advanced topic as newbies don't really understand that you can even do this, and this all requires that you really understand what is what on the server and how to get updates to the clients.

And yet another warning. Xhooks manages the login and logout hooks on Mac OS X.  If you have your own login and logout hooks, then either you have to get them launched by Xhooks (which is trivial to do) or you are going to have to disable Xhooks' loginhook and logouthook hooks, which is an idea that has never been considered in the development of Xhooks until this paragraph was written.

################################################################

If you do not have a radmind server running, here are some quick steps to get one running really quick (not a production server--this server will not keep running once you reboot the computer).

Download and install the Radmind tools from www.radmind.org.

Open Terminal.app.

Type:

sudo -s
/usr/local/sbin/radmind
cd /var/radmind
chmod 777 command file transcript
open .

You now have a basic radmind server running and ready to modify (without worrying about permissions--don't set up a production server this way).

################################################################

This is how you put Xhooks on your radmind server.

Download the Xhooks package (you probably already did this).

In the Finder, go to the Xhooks folder "xhooks (radmind server)".  You need to move the files from the Xhooks package to the same folders on your radmind server.  If you are installing Xhooks for the first time, you can just copy the folders over:

copy "xhooks (radmind server)/command/xhooks" to the server /var/radmind/command
copy "xhooks (radmind server)/transcript/xhooks" to the server /var/radmind/transcript
copy "xhooks (radmind server)/file/xhooks" to the server /var/radmind/file

There is a file "xhooks (radmind server)/config" which is just an example.  Don't copy it.  There are also extra files in "xhooks (radmind server)/command".  Don't copy those (see the Readme.txt section discussing Installing for an explaination of those).

If you have the xhooks folders on your server already, you should be able to copy the x18 (or whatever the current version is) file and transcript folder into your existing "xhooks" folders.  The misc folder shouldn't really have any changes so if you already have the overloads then you are probably are all set.  The files in "xhooks (radmind server)/command/xhooks" are more like site specific settings.  They shouldn't really change that much, but the examples might or there might be new files.  So when upgrading you will just have to look these over and look at the changes.

NOTE: Xhooks transcripts all have **relative paths**.  If you already have a radmind server and you are using absolute paths in your transcripts, you will need to change the paths.  We would recommend you switch all your transcripts to relative paths since it is more powerful rather than change the Xhooks transcripts, but it is up to you.

Xhooks is now on your radmind server.

################################################################

This is the most basic way to get Xhooks from your radmind server to your clients.

If you do not have a command file for your client computer create a new file, for example /var/radmind/command/all.K

Edit /var/radmind/config so that the computer has access to the command file.  For example:

echo "* all.K" >> /var/radmind/config

Edit your command file (e.g. /var/radmind/command/all.K) and add these lines (replace radmind.example.com with your server address):

p xhooks/x18/xhooks_core.T
p xhooks/x18/prefs/xhooks_prefs.T
n xhooks/x18/xhooks_neg.T
k xhooks/download_overload.pl

Note, this will only put Xhooks on the computer and wont actually "enable it".  To enable it, you need to add:

p xhooks/x18/xhooks_on_10.5.T

or

p xhooks/x18/xhooks_on_10.4.T

Depending on your OS version.

If this is the first time you have setup radmind, it is helpful to watch the log as you attempt to download an overload.  Open a new Terminal window and type:

tail -f /var/log/system.log

Move that window to the side so you can see it, but you will not interact with it anymore.

Now type:

ktcheck -c sha1 -h radmind.example.com

(if you are running radmind on the client you can actually use localhost after the -h).

You now have the transcripts on your client.  To download the files, you can run radmind if your client is all set to run, or you can use download_overload.pl.  The next section explains how.

################################################################

How to get and use download_overload.pl.

After running ktcheck, run this command:

head -4 /var/radmind/client/xhooks/download_overload.pl

It will print something like this:

##!/usr/bin/perl -w
#
##perl -pi -e's/^#//' /var/radmind/client/xhooks/download_overload.pl; cp /var/radmind/client/xhooks/download_overload.pl /usr/local/bin/download_overload.pl; chmod 755 /usr/local/bin/download_overload.pl
##/usr/local/bin/download_overload.pl -h example.com overload_name.T


See the 3rd line?  Copy it and paste it back into the terminal.  So paste this:

perl -pi -e's/^#//' /var/radmind/client/xhooks/download_overload.pl; cp /var/radmind/client/xhooks/download_overload.pl /usr/local/bin/download_overload.pl; chmod 755 /usr/local/bin/download_overload.pl

That will create the file /usr/local/bin/download_overload.pl and make it executable.  You now have download_overload.pl.  Sneaky, eh?

To run it, look at the 4th line printed from the head command above.  Replace example.com with the name of your radmind server and replace overload_name.T with the name of your overload.  You must specify the full path of the overload starting from /var/radmind/transcript.  So /var/radmind/transcript/xhooks/x18/xhooks_core.T is downloaded like this:

/usr/local/bin/download_overload.pl -h example.com xhooks/x18/xhooks_core.T

You can specify them all if you want:

/usr/local/bin/download_overload.pl -h example.com xhooks/x18/xhooks_core.T xhooks/x18/prefs/xhooks_prefs.T xhooks/x18/xhooks_neg.T

This will try to download to the current directory.  So if you get an error like:

./Library/LaunchAgents/edu.umich.iHook.loginwindow.plist.radmind.610: No such file or directory

That is because the folder ./Library/LaunchAgents/ does not exist at your current path.  So cd to / and run it again:

cd /
/usr/local/bin/download_overload.pl -h example.com xhooks/x18/xhooks_core.T xhooks/x18/prefs/xhooks_prefs.T xhooks/misc/xhooks_neg.T

You will see the list of files get downloaded to your client.

################################################################

Now that you have it on your computer, now what?  Well, you will probably want to reboot.  If all goes well it will just reboot and nothing will be different.  How do you know if anything even happened?  Run this command:

grep edu.utah.scl /var/log/system.log

You should see some entries with "startupearly" and "startuplate" in it.  The messages themselves are pretty useless.  Logging isn't something Xhooks does well yet.  It just proves that it works.

Anyway, by default Xhooks wont actually do anything (other than hook in).  You have to give it some hooks to run.  To give it hooks, create some symlinks in /Library/Xhooks/Modules/xhooks/hooks.  (I might change this path some day).  The links must be named a certain way.  

A really crazy way to test all of this (and learn real well when stuff runs) is by adding the debug symlinks.  Type these commands:

cd /Library/Xhooks/Modules/xhooks/hooks
ln -s ../../edu.utah.scl.debug/basic_debug.pl SED_debug.pl
ln -s ../../edu.utah.scl.debug/basic_debug.pl SLD_debug.pl
ln -s ../../edu.utah.scl.debug/basic_debug.pl LID_debug.pl
ln -s ../../edu.utah.scl.debug/basic_debug.pl LOD_debug.pl

These are the hooks and where Xhooks gets its name!!! Yay!!!

Now test it by typing:

./SED_debug.pl

It should say "Script running library xhooks modules xhooks hooks sed debug dot pl."

If it worked, logout.  Login.  Restart.  You should hear it say something each time.

The filename prefixes in /Library/Xhooks/Modules/xhooks/hooks determine if and when it runs.  It must begin with one of the following:

SE means startup early, before the loginwindow shows
SL means sometime after startup (if the machine is autologin, this could exectue *after* the login scripts run).
LI means login
LO means logout

One more that actually wont run right now is:

PM means "post maintenance".

To run the PM scripts, you need the hook edu.utah.scl.radmind/SEE_2_run_postmaintenance.pl **AND** that script will only run the PM scripts if the file /Library/Preferences/Xhooks/triggerfiles/run_startup_post_maintenance exists.

The 3rd character has to be an E (early), D (detached), or L (late).  All E's will run first one by one, then all the D's run at the same time, then all the L's run one by one.  Some scripts don't care when they run, some have to run before all others, and some after all others.  That is all that means.

This example created the hooks manually.  But the "normal" way to create the hooks is with a radmind transcript.  You will see many examples of the hook transcripts in the xhooks transcript folder.  You will notice there is one named xhooks_hooks_debug.T.  It creates the same hooks we created above except it creates a ton of them so you can **really** see how the hooks will run.  You can download it to your client by adding "xhooks/x18/hooks/xhooks_hooks_debug.T" to the All.T command file and then run download_overload.pl like so:

/usr/local/bin/download_overload.pl -h example.com xhooks/x18/hooks/xhooks_hooks_debug.T

Then reboot.

################################################################

There is one more thing to discuss and that is full management.  Full management is when Xhooks takes over the radmind update cycle (ktcheck, fsdiff, lapply steps).  The advantage of this is that you no longer have to type the radmind commands at the command line to update the machine.  Before you can have Xhooks fully manage a box, you need to set some Radmind/Xhooks variables.

The variables are stored in 2 places.  The first is a backup incase something goes wrong, and the only variables that are stored are radmind server variables.  These are stored in the overload "xhooks/x18/prefs/xhooks_prefs_neg.T".  Go ahead and open all 3 files in that overload and change the radmind settings to match your setup.  The most important setting is your radmind server and port.  Be sure to update the checksum for that overload (run this on your server: "lcksum -c sha1 /var/radmind/transcript/xhooks/x18/prefs/xhooks_prefs_neg.T").

Those 3 files are actually rewritten at start if they are missing or if radmind has just run.  So you can't rely on the backup overload, it only exists if you run radmind outside of Xhooks (ktcheck, fsdiff, lapply on your own).

The contents of those pref files are grabbed from the command files for that machine.  The contents of the command files are searched and *anything* that matches this basic patter is added the the pref files:

# VARIABLE =

or

# ARRAY +=

There are a few other variations that we will look at in a sec.

So you need to add this to your command file:

# RADMIND_SERVERS += radmind.example.com
# FSDIFF_PATH = .

There are other settings as well for full management, such as setting when you want radmind to run all on it's own.  The variable to set that is "NIGHTLY_RADMIND_REBOOT".  So add this to your command file and you are telling it to run radmind at 1:30 am on Sundays

# NIGHTLY_RADMIND_REBOOT = 30    1    U    -

If you have 1000 Mac's you don't want them all to run radmind at the exact same minute, so you can either change this setting for each command file for each machine, or, if you find that you have 200 computers that are exactly identical except for this stupid setting, instead of having multiple command files just to say when it should run radmind, you can use put the IP in the variable and the variable will only be added to the Xhooks prefs if the IP or IP range matches.  So something like this will assign the variable to 64 possible computers and run radmind on half at 1:30 AM, and the other half at 2:00 AM.

# (10.0.1.1-32) NIGHTLY_RADMIND_REBOOT = 30    1    U    -
# (10.0.1.33-64) NIGHTLY_RADMIND_REBOOT = 0    2    U    -

If you wanted to get even more complicated (or simple--just takes more setup), you can actually put this setting in your radmind's config file located at /var/radmind/config on the radmind server.  See the included config file for an example.  For this to work you have to put a LaunchDaemon on your radmind server that watches when /var/radmind/config changes, and if it changes, it will scan it and pull out all the variables and put them in a file inside of /var/radmind/command which you can then put in your command files.  This is a bit complex to setup, and it can fail easily.  But once you have it setup it makes managing certain settings a piece of cake (you are basically using the config file to control more than just what command file a machine gets).

The LaunchDaemon to get this working is located in "radmind server scripts/radmind master/Library/LaunchDaemons/edu.utah.scl.radmind_config_updater.plist".  The script is located at "radmind server scripts/radmind master/usr/local/bin/radmind_config_updater.pl".  If you look at the top of the script you will see what file it saves these settings to (by default "/var/radmind/command/xhooks/radmind_reboot.conf").  You will also notice a place for your email address where you will receive an email every time this script makes a change.

Have fun!  (That is, once you get this all setup, you should have fun because your life is now so much easier and because you have to do less managing and now you finally have time to write that iPhone game you have wanted to write ever since the iPhone came out!)