The Process

Step 1: Snapshot a clean system

This easiest way to get a clean system is to use the JACAL installation disk and choose to do a Windows install with the "sysdiff" option. The sysdiff option will install: Windows NT, the latest service pack, the latest version of Internet Explorer (which is really another service pack), Perl, and the Perl shortcut library. The administrator password will be blank at this point. You should change the password to match the global administrator password so that the network can be accessed as administrator.

Once you have a clean system prepared, log on to the system as administrator and snapshot the clean system. The command for this is c:\admin\sysdiff\sysdiff /snap <snapshot_file>. The best place to put the snapshot file is into the c:\temp directory.

Step 2: Install the application

This step includes installing the application and any associated patches/service packs. You will typically want to let the application install to its default install point on the hard drive. After this run the application One important thing to note during this step is that every change to the system will be recorded by the sysdiff process. This even includes re-sizing the explorer window, mapping network drivers and such things. It is recommended that you do as little as possible between the point where you run sysdiff with the "snap" option and when you run sysdiff with the "diff" option. What you do before and after that shouldn't matter. For example, if you want to set explorer to "show all files" you should do that before you snapshot the system so that the change is not captured as part of the necessary changes to make to the system as part of the application install later.

Step 3: Sysdiff the system

Once the application has been installed, take a "difference" of the system (against the snapshot taken earlier). This is done using c:\admin\sysdiff\sysdiff /diff <snapshot_file> <diff_file>). The diff file that is created in this step holds all the information about what changes the application made to the machine including registry entries, file added and replaced, ".ini" files that were modified, etc.

Step 4: Extract registry settings, system files, and other files needed for the application install

If there were not any changes that needed to be made to how the application is executed then we would be nearly done because the diff file could be used directly to recreate the changes on a blank machine (thus installing the application). However, since we typically want to run applications off the network, there are several changes that must be made to the data contain in the diff file.

In order to change the difference information we have to extract it. The command to do this is c:\admin\sysdiff\sysdiff /inf /m <diff_file> <extract_location> (Note that the /m option is mandatory [sic]). The extracted difference information should be placed in an appropriately named sub-directory on samson within the (JDIR)/installs/ directory. The sub-directory name must be eleven characters or less because of SMB share limitations (see step 8). The command would probably look like this: c:\admin\sysdiff\sysdiff /inf /m c:\temp\msoffice.dif \\(JSHARE)\installs\msoffice97\. ((JDIR) is mapped to the samba share \\(JSHARE)\).

New directories under (JDIR)/installs/ should be named with the application name and the version number (generally without periods). The directory name should also be limited to eleven characters (this is because of the samba share which is discussed later).

Step 5: Repath the install source shortcuts

The next two steps change shortcuts and the registry file so that the application can be run off the application server (samson). The script used to change the paths within Windows shortcuts (.lnk files) is \\(JSHARE)\scripts\ It takes the original path as its first argument, and the desired path as its second argument. It will then modify all shortcut files (by the .lnk extension) under the current directory. Make sure that the script is run from within the root of the install source directory and that you pass the first path using the dos naming convention. Also, this script must be run from within Windows because the Perl shortcut library is only available under Windows. An example (related to above examples) would be as follows:

net use v: \\(JSHARE)
cd \installs\msoffice97
..\..\scripts\ c:\progra~1\msoffice97 \\samson\msoffice97 

The UNC path \\samson\msoffice97 will later be created as a samba share from where the application will actually execute.

Step 6: Rename the install source files

You will have a directory within your install source directory on samson called $OEM$. Within the $OEM$ directory you will have two files (<appname>.inf and cmdlines.txt) and two sub-directories ($$ and C). The .inf file contains all the registry changes and .ini modifications. The $$ directory contains files that were changed in the WINNT directory and the C directory contains the rest of the files that were changed or added to the local drive. Since all information is contained within the $OEM$ it is redundant, so an easy way to get rid of the $OEM$ directory is with the following commands issued from the Linux side:

cd (JDIR)/installs/<appdir>/
mv "\$OEM\$/"* ..
rmdir "\$OEM\$" 

The sysdiff utility (to which we have casually referred to throughout this document) will unfortunately create files in the dos 8.3 naming format, as well as a file called $$rename.txt in both the C and $$ directory, in which are placed name mappings (from 8.3 naming format into longer names). A utility script has been written to automate the renaming of these files into the proper long format. First, rename the $$rename.txt file to rename.txt. The script should be run on the Linux side from within the same directory that the rename.txt file resides. Here is an example use of this command: (JDIR)/scripts/ (JDIR)/installs/msoffice97/winnt/rename.txt.

Step 7: Repath the registry file

The registry settings file (e.g. msoffice.INF) created by the sysdiff /inf /m step must also have paths changed for the program to be able to execute from the network properly. A global substitution can be done by editing the file in vim, and typing: :%s/c:\\progra~1\\msoffice97/\\\\samson\\msoffice97/ig

This command string performs a global case insensitive substitution for c:\\progra~1\msoffice97 -> \\samson\msoffice97 for all occurrences in the file.

Step 8: Create the execution share directory and samba share

In order for the application to execute from the network properly, the main program files must be moved to a samba share location. This is currently located under /samba/progs3/. A directory should be created with the same name as the install source directory created in step 4. Then a samba share that points to that directory should be created with the same name (this is where the eleven character limitation is actually imposed).

Now the execution files must be moved from the install source directory to the execution directory. The files that you are going to want to move will be under the C directory in the install source directory in the directory that you specified when you installed the application. This directory will contain the majority of the files that the application installed. To continue our previous example: mv "(JDIR)/installs/msoffice97/C/program files/Microsoft Office 97"/* /samba/progs3/msoffice97/. The quotes are required in the first path so that the shell doesn't treat the spaces as parameter separators.

Step 9: Synchronize system files between various application install source directories

Because various applications were built at various times, they will have system files that they need for operations. For example, the following two imaginary install source files will overwrite each other when their respective applications are installed:


Some of these system files are older than others, and we want to make sure that all applications are using the most recent version of the system files (so that all applications will work correctly, and none will be complaining about a missing function call because the dll we are using is too old).

There are two scripts used to handle system file conflicts. The first script,, is used to search for and backup any conflicting files in the (JDIR)/_shared_ directory. The second script is which is used to choose which system file should be used. enumerates through all new conflicts and presents a menu for each conflict that lists every application that conflicts and the version of the system file if there is one. Both of these scripts reside in (JDIR)/scripts/ and will both print out usage information and options if called with a --help parameter. The script uses symbolic links to resolve the conflicts. When the file is requested during the install from the windows side, the link will be de-referenced and the correct (occasionally it is not the latest) version of the file will be installed

Step 10: Create the zipped up install source directory

In order to speed up the installation process for each application, the contents of each install source directory is zipped up and placed in an separate install source directory tree. The program which will be issued from the Windows workstation to install an application looks in the zipped install source directory for the application. To create (or re-zip) the zipped install source directory use the script (JDIR)/scripts/ and pass it the name of the install source directory. Then you need to hard link the .INF so that it is referenced from the zipped install source directory (I.e. ln (JDIR)/installs/msoffice97/msoffice97.inf (JDIR)/installzips/msoffice97/msoffice97.inf).

Step 11: Install the application

To install an application, log into the workstation as local administrator and run \\(JSHARE)\scripts\ <appinstallsource>. To install every application that exists in the zipped install source directory, use the parameter all.

Step 12: Fixing the Application

The application almost certainly won't work properly the first time. Things that tend to break are the help menu, the shortcuts not getting re-pathed properly, plugins are broken, picture galleries not loading properly, etc. There are many different areas that can cause these problems most of them related to how sysdiff created the .INF file.

Sometimes when sysdiff creates the .INF file, it uses several different variations of the same path name. For example, c:\program files\Microsoft Office\MS Office 97\ and c:\progra~1\Microsoft Office\MS Office 97\ and c:\progra~1\Micros~3\MSOffi~1\ may all be contained within the .INF file.

Another problem that may happen is that the application itself stores settings that should be global settings in local user settings. Even Microsoft applications do this. Look for lines in the .INF file that begin with "HKCU,". HKCU stands for the H_KEY_Current_User registry hive. Look through HKCU registry entries to see if there are any that look like they might be related to the problem. If they are, you may need to convert those entries to REGEDIT4 format files and put them in the NT login script so that they settings will be entered into each users registry hive each time they log into a workstation.

Another common problem is that sysdiff doesn't always register .ini file changes correctly. At the end of the .INF file there may be .ini changes. If there are .ini files that are specific to the current application (i.e. they are from the execution share directory) listed in the .INF file then these should really be placed in the .ini file within the execution share directory instead of in the .INF file.