V.O.I.C.E Virtual OS/2 International Consumer Education

January 2006

A A A

Active GUI element

Static GUI element

Code

WPS object

File/Path

Command line

Entry-field content

[Key combination]

more

by Alex Taylor, © January 2006

A couple of years ago, RSU was a nifty little IBM utility that made installing FixPaks a breeze. All you needed was a web browser and a working Internet connection, and that new OS/2 FixPak was just a few mouse clicks away (plus download time).

Alas, at around the time IBM was converting Software Choice over to Passport Advantage, they decided not to provide FixPaks via RSU anymore. And so, FixPak installation once again became an awkward and technical business: locate and download the diskette images, extract them somehow to a temporary directory, hunt down the correct version of CSF, and then remember the correct sequence of commands to get it installed. And for people who weren't already familiar with the process, it can be a hair-pulling nightmare.

Even when you know most of the tricks—as I do—it's an awkward business, especially when you keep having to install different FixPaks on various OS/2 systems (which seems to happen a lot since I got Virtual PC). So it occurred to me to set up my own private RSU server to simplify my life.

I'm sure I remember seeing a detailed description of the .RSU file format somewhere or other, but I can't find it anymore. Perhaps it was on a web page that IBM has since erased from existence. In any case, I resorted to study and experimentation, and in the end I figured out almost everything myself.

How RSU Works

RSU isn't really a single program; it's a logical process that starts with the user clicking on a link in a web browser, and ends with the installation of the FixPak (usually through CSF, the Corrective Service Facility). In between these two points are three main components:

The .RSU file

A specially formatted ASCII text file which contains installation instructions.

RSUINST.EXE

The program which interprets the .RSU file and acts according to its instructions.

FTPINSTL.EXE

A utility used to download FixPak images and launch the Corrective Service Facility.

When you click on the link to an RSU FixPak in your web browser, the browser downloads a special script file which has a filename ending in .RSU. If your browser has the RSU MIME type properly configured, this action causes RSUINST.EXE to launch.

RSUINST.EXE reads the .RSU file and acts according to the instructions it contains. These instructions basically consist of connect to this FTP site using this username/password, download these files, unzip them if necessary, run this command with these parameters.

RSUINST.EXE downloads (and unzips) all files into the directory \$RSUTMP$, on a drive you specify when RSU starts up. Then it executes the specified command, and exits immediately afterwards.

For standard FixPaks the only file that gets downloaded by RSUINST.EXE is CSF144.ZIP, which is a special distribution of the CSF that includes FTPINSTL.EXE and a few other utilities. After this file is unzipped, RSUINST.EXE executes FTPINSTL.EXE with a parameter string containing an FTP server, username, password, and the remote directory where the FixPak files are located. (This does not have to be the same FTP server that RSUINST.EXE just used, although it often is.)

FTPINSTL.EXE logs onto this FTP server, changes to the specified directory, and looks for a file called FTPINSTL.ZIP. This is a special ZIP file which contains a list of files to be downloaded. FTPINSTL.EXE downloads and unzips these files into its working directory, performs some verification, and finally executes the OS2SERV.EXE program, which is a front-end to the Corrective Service Facility (CSF). This, in turn, is what actually installs the FixPak.

Once the FixPak is installed, OS2SERV.EXE returns control to FTPINSTL.EXE, which performs some final cleanup and then exits.

Well, that's the general idea. Now let's look at the various components in a bit more detail.

The .RSU file format

A .RSU file looks something like this:

INSTALL_TYPE=R
INSTALL_PGM=ftpinstl.exe pristine
INSTALL_PARMS=service.boulder.ibm.com anonymous pspdist@vnet.ibm.com ps/products/os2/rsu/xr_m015
FTP_SITE=service.boulder.ibm.com anonymous pspdist@vnet.ibm.com
PKG_FILE={
  NAME=ps/products/os2/rsu/csf144.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=5000000
  MODE=B
}

The various keywords are:

INSTALL_TYPE

As far as I can tell, this should always be R.

INSTALL_PGM

This tells RSUINST.EXE what executable program it should run after it's finished downloading and unzipping files. The value for normal FixPaks should be ftpinstl.exe pristine. (Don't ask me what "pristine" means.)

Note that you don't have to run FTPINSTL.EXE; if you need to run a different program, you can specify that instead. (I'll provide a couple of examples of this later on.)

INSTALL_PARMS

This specifies the command-line parameters that get passed to the executed program (from INSTALL_PGM). For FTPINSTL.EXE, this is the string

<FTP server> <username> <password> <FTP directory>

which tells FTPINSTL.EXE where to find the FixPak files that it needs to download.

FTP_SITE

This is the string

<FTP server> <username> <password>

which specifies the FTP server and login information with which RSUINST.EXE downloads files.

PKG_FILE

This is a multi-line definition which specifies a file that must be downloaded before the INSTALL_PGM program can run. This definition contains the following keywords between a single pair of curly braces, all of which are required:

NAME

The fully-qualified name (including path) of the file on the FTP server.

UNZIP

Indicates whether the file should be unzipped (Y) or not (N) after downloading.

FILE_SIZE

The amount of free disk space required on the target drive to store the file.

UNZIPPED_SIZE

The amount of free disk space required on the target drive to unzip the file after downloading. (If the file is not to be unzipped, you make this the same as the FILE_SIZE value.)

MODE

Whether the file should be downloaded in binary (B) or ASCII (A) mode.

You can specify multiple PKG_FILE definitions if you need RSUINST.EXE to download multiple files.

RSUINST.EXE operation

The first thing RSUINST.EXE does when initializing is to verify that it's been passed a valid .RSU file as a parameter. If this is missing, or if the file is not valid, the program exits immediately.

On successful initialization, RSUINST.EXE presents a window which allows the user to select a few basic options, such as the disk drive on which to store files, and whether or not to run in "verbose" mode. The actual work doesn't start until you click on Begin.

RSUINST.EXE processes the values from the .RSU file as follows:

1. Connects to the FTP server specified in FTP_SITE (using the username and password given).
2. Downloads each file specified with a PKG_FILE definition, first making sure that there is sufficient disk space available. Unzips each file which has UNZIP=Y.
3. Executes the program specified in INSTALL_PGM, with the parameters specified in INSTALL_PARMS.
4. Exits.

All downloaded and unzipped files go into the directory \$RSUTMP$ on the drive which the user selected.

FTPINSTL.EXE operation

FTPINSTL.EXE downloads the actual FixPak files, unzips them, and then calls OS2SERV.EXE to launch the FixPak installation. It, too, starts by offering the user a few options.

Once you click on Begin, FTPINSTL.EXE connects to the FTP site specified in the parameters, using the username and password provided. It then changes to the specified FTP directory, and looks for a file named FTPINSTL.ZIP. This ZIP file must always be present in the FTP directory, and must contain a special ASCII text file known as the table file.

The table file must always have the filename <fixpak>.TBL, where <fixpak> is the name of the FTP directory. For example, if the FTP directory is named /ps/products/os2/rsu/xr_m015, then the FTPINSTL.ZIP archive within that directory must contain a table file named xr_m015.tbl.

The table file contains a list of additional ZIP files which FTPINSTL.EXE must download and unzip. These files are listed, one per line, in the format:

<size> <filename> [<checksum>]

where <size> is the size of the file in bytes, and <filename> is the name of the file. <checksum> is optional; it seems to be some kind of checksum for the file, but I haven't figured out exactly what kind.

The files listed in the table file must be present in the same directory; their size in bytes (and their checksums, if specified) must exactly match those given in the table file. Furthermore, their filenames must correspond to a specific pattern: the name of each file (without the .ZIP extension) must correspond to the name of the FTP directory, with a single alphanumeric character appended. To continue our earlier example, if the FTP directory is named /ps/products/os2/rsu/xr_m015, then the additional ZIP files must be named xr_m015?.zip, where ? is either a number from "1" to "9," or a letter from "a" to "z."

If any of these conditions does not hold true, FTPINSTL.EXE aborts the download with an error message complaining about a corrupted table file.

FTPINSTL.ZIP may also contain a file named README.1ST. FTPINSTL.EXE offers to display this file (by calling E.EXE) while the additional ZIP files are being downloaded.

Once all of the files have been downloaded and unzipped, FTPINSTL.EXE executes OS2SERV.EXE (another program from the CSF144.ZIP archive), a graphical front-end to the CSF which is what guides the user through the actual FixPak installation.

Setting up an RSU server

Now that we know more or less how RSU works under the covers, we can set up our own RSU environment. We need to do a number of things:

• Create the .RSU files, and set up a web site to host them.
• Set up an FTP server to host the various downloadable files (both the required utilities and the FixPaks themselves).
• Convert the FixPak images into ZIP files.
• Set up the FixPak directories on the FTP server, including the table files for each FixPak.

Creating the .RSU files

I've described the .RSU file format already. For the most part, you can create a standard template file, and copy it (with minor modifications) for each FixPak you want to RSU-enable.

For now, let's assume we're just dealing with standard (CSF-installed) FixPaks. In this case, you'll be using FTPINSTL.EXE as the exit program (specified under INSTALL_PGM).

Please see the following example:

INSTALL_TYPE=R
INSTALL_PGM=ftpinstl.exe pristine
INSTALL_PARMS=192.168.107.66 anonymous user@host.rsu os2_fixpak/*******
FTP_SITE=192.168.107.66 anonymous user@host.rsu
PKG_FILE={
  NAME=os2_fixpak/csf144.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=5000000
  MODE=B
}

The only part I typically need to change is the ******* (the FixPak directory name) in the INSTALL_PARMS.

The .RSU file values you need to pay attention to (when creating your template) are:

INSTALL_PARMS

Make sure you enter the address of the FTP site where you are placing the zipped FixPak files. Also use the correct user ID and password (an anonymous login is recommended if your FTP server supports it). Generally, these are the same for all FixPaks. The only part of this line that's likely to be different for each FixPak is the directory name at the very end.

Here are some examples from my RSU server:

xr_m015.rsu (Warp 4 FixPak 15):

INSTALL_PARMS=192.168.107.66 anonymous user@host.rsu os2_fixpak/xr_m005

xr_d001.rsu (Device Driver FixPak 3):

INSTALL_PARMS=192.168.107.66 anonymous user@host.rsu os2_fixpak/xr_d003

ip_8414.rsu (Peer 4.0 FixPak IP_8414):

INSTALL_PARMS=192.168.107.66 anonymous user@host.rsu os2_fixpak/ip_8414

Otherwise, the files are all identical to the template shown above.

FTP_SITE

Enter the address (and login info) of the FTP site where the CSF ZIP file is located. You can keep this on your own FTP server (recommended), or even just point to IBM's FTP server, which is service.boulder.ibm.com with an anonymous login.

PKG_FILE

Make sure this points to the CSF ZIP file. You can use the values in the example above, just change the NAME parameter to point to the correct path and filename on your FTP server (or ps/products/os2/rsu/csf144.zip if you're pointing to IBM's FTP server).

Once you've created the .RSU files, you need to make them available somewhere for users to access by web browser. Any web page will do; just set up an HTML link to each file.

Any RSU web page should also have a link to RSUINSTN.EXE (which you can get from here), and maybe some installation instructions, so that users can configure their systems as required. Since IBM's old RSU website no longer has these instructions, I've put together a text file which describes the necessary steps.

Setting up the FTP server

Next, you need an FTP server on which you can host the FixPak files themselves. Unfortunately, both RSUINST.EXE and FTPINSTL.EXE require the FTP protocol for downloading files, so web-based HTTP file hosting won't do.

If you're controlling the server yourself, use your preferred FTP server program. I recommend one which supports anonymous logins, otherwise you'll have to put an actual user ID and password into the .RSU files. If the FTP server belongs to somebody else (such as your ISP, business, or institution), make sure you have permission to host the FixPaks there. Also, the server should have a fast network connection, since FixPaks tend to constitute fairly large downloads.

Creating the ZIP files

FixPak files are usually distributed in the form of binary diskette images. You need to convert each disk image into a ZIP file instead. Use a tool like DSKXTRCT (available on Hobbes) to extract each disk image, then simply use ZIP.EXE or its equivalent to create the ZIP file.

See DSK2RSU.CMD (below) for an automated method of accomplishing this.

Creating the FixPak directories

Place the ZIP files into the appropriately named FTP directory. Next, you must create the special file FTPINSTL.ZIP in the same directory.

FTPINSTL.ZIP must contain the table file <name>.TBL, where <name> is (once again) the name of the FTP directory. The format of this file is described above; it contains a list of the FixPak ZIP files and their respective sizes (in bytes).

FTPINSTL.ZIP should also contain the README.1ST file that came with the FixPak (all FixPaks include a file with this name).

The REXX script described in the next section automates the creation of FTPINSTL.ZIP for you.

DSK2RSU.CMD

Creating all these ZIP files according to the correct format can be tedious and tricky. Therefore, I wrote a simple REXX script to automate the process. The script is called DSK2RSU.CMD, and it requires that you have both ZIP.EXE and DSKXTRCT.EXE in your PATH.

DSK2RSU.CMD is available here. To use this script, do the following:

1. Create a temporary directory, with a name that describes the FixPak. Important: this temporary directory name is used to generate all of the FixPak file and directory names used by RSU, so make sure it's meaningful. (Only the first 7 characters are used.)
2. Obtain the diskette image files for the FixPak you want to RSU-enable, and place them together into the temporary directory.

3. Run the command:

   DSK2RSU <directory-name>
   

   where <directory-name> is the name of the directory containing the diskette images.

DSK2RSU.CMD does the following:

• Converts all of the diskette images into ZIP files.
• Creates the FixPak table file (.TBL) with the correct file data.
• Creates FTPINSTL.ZIP, containing the table file, and also the file README.1ST if one was found on the first diskette image.
• Place all of these ZIP files together into a new subdirectory which follows the naming formula described earlier.

The newly-created subdirectory can then be moved directly into your FTP server directory, and the FixPak should be ready for RSU installation (once you've created an appropriate .RSU file, that is).

Example

Let's say I want to make the Warp 4 Peer FixPak IP_8414 available for RSU installation. We'll assume that I'm using the internal FTP server I mentioned earlier (IP address 192.168.107.66).

First, I'll create the file IP_8414.RSU and make it available on a web page somewhere:

INSTALL_TYPE=R
INSTALL_PGM=ftpinstl.exe pristine
INSTALL_PARMS=192.168.107.66 anonymous user@host.rsu os2_fixpak/ip_8414
FTP_SITE=192.168.107.66 anonymous user@host.rsu
PKG_FILE={
  NAME=os2_fixpak/csf144.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=5000000
  MODE=B
}

Next, I need to create the FixPak files themselves. I obtain the FixPak diskette images from IBM and place them in a temporary directory (say, D:\tmp\ip_8414):

Directory of D:\tmp\ip_8414

 4-21-05 10:45a         <DIR>      0 ----  .
 4-21-05 10:45a         <DIR>  1,323 ----  ..
 1-09-01 10:02a     1,472,041      0 a---  IP08414.1DK
 1-09-01 10:02a     1,472,041      0 a---  IP08414.2DK
 1-09-01 10:02a     1,472,041      0 a---  IP08414.3DK
 1-09-01 10:02a     1,472,041      0 a---  IP08414.4DK
 1-09-01 10:02a       866,345      0 a---  IP08414.5DK
        7 file(s)   6,754,509 bytes used
                    983,244,800 bytes free

I make sure that ZIP.EXE, DSKXTRCT.EXE and DSK2RSU.CMD are all available on my PATH, and then run the conversion.

[D:\]dsk2rsu d:\tmp\ip_8414
Processing 5 diskette images in D:\TMP\IP_8414.

Unpacking D:\TMP\IP_8414\IP08414.1DK ... OK
Unpacking D:\TMP\IP_8414\IP08414.2DK ... OK
Unpacking D:\TMP\IP_8414\IP08414.3DK ... OK
Unpacking D:\TMP\IP_8414\IP08414.4DK ... OK
Unpacking D:\TMP\IP_8414\IP08414.5DK ... OK
Creating ip_84141.zip ... OK
Creating ip_84142.zip ... OK
Creating ip_84143.zip ... OK
Creating ip_84144.zip ... OK
Creating ip_84145.zip ... OK
Writing ip_8414.tbl ...
Creating ftpinstl.zip ...
Done.

RSU files have been placed under D:\TMP\IP_8414\IP_8414.

Now I can simply move the output directory to the FTP directory.

[D:\]move D:\tmp\ip_8414\ip_8414 \FTPServ\ftp\os2_fixpak

Important Notes

The most common error when setting up an RSU server is getting one of the directory or file names wrong. FTPINSTL.EXE is very picky, and if you neglect to name all of your files and directories according to the proper formula, the FixPak installation fails.

To recap, the correct naming formula is as follows:

• The FixPak ZIP files must have the same name, including case, as the directory in which they are located, with the addition of a single lowercase alphanumeric character at the end, before the .ZIP extension. ("1" indicates the first file, "2" the second, "a" the tenth, "b" the eleventh, "g" the sixteenth, and so on.)

• The FixPak directory must also contain a file called FTPINSTL.ZIP, which must in turn contain the following:

  • An ASCII table file with the same name as the directory plus the extension .TBL. This file contains a case-sensitive list of all FixPak ZIP files to be downloaded, one per line, in the format size filename (and an optional checksum).
  • An ASCII file called README.1ST, which the user has the opportunity to read while the ZIP files are being downloaded.

  Neither the name of FTPINSTL.ZIP, nor the names of the two files within it, are case-sensitive. However, the filenames listed within the table (.TBL) file are.

Some recent FixPaks, particularly for networking, are distributed as single ZIP files, not diskette images. In some cases, you can simply rename the ZIP file according to the proper naming convention, and it works with RSU (as long as you generate the table file and so on correctly). However, there appears to be a limit to the size of ZIP file that FTPINSTL.EXE can handle (beyond which it aborts during download). I'm not sure what the precise limit is, but it seems to be a little over 3 MiB. So if the FixPak comes in a ZIP file larger than about 3 MiB, you should split it up into multiple archives (following the proper naming convention, of course).

Without FTPINSTL.EXE

Since it's designed to install standard FixPaks, FTPINSTL.EXE interfaces automatically with the Corrective Service Facility. So what happens if you want to install something which doesn't use the CSF for installation?

Well, as mentioned earlier, it's entirely possible to specify a program other than FTPINSTL.EXE under your .RSU file's INSTALL_PGM parameter.

Let's say you want to install the upgrade to MPTS 5.5 (distributed as WR_8610). As a complete product replacement, this isn't technically a FixPak at all, and doesn't use the CSF—it comes with its own installation program (MPTS.EXE).

Here's my .RSU file for WR_8610:

INSTALL_TYPE=R
INSTALL_PGM=mpts.exe
INSTALL_PARMS=
FTP_SITE=192.168.107.66 anonymous user@host.rsu
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86101.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86102.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86103.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86104.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86105.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86106.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}
PKG_FILE={
  NAME=os2_fixpak/wr_8610/wr_86107.zip
  UNZIP=Y
  FILE_SIZE=1500000
  UNZIPPED_SIZE=3000000
  MODE=B
}

There are three differences between this and one of my files for standard FixPaks. First, the INSTALL_PGM is MPTS.EXE, which is the program that installs the upgraded MPTS version. This program takes no parameters, so the INSTALL_PARMS line is left blank. And, since I'm not using FTPINSTL.EXE, I can't rely on it to download the actual product files. I have to download them instead using RSUINST.EXE directly, so I specify multiple PKG_FILE statements—one for each required file.

Strictly speaking, you can use RSU to download and run programs which have nothing to do with FixPak installation at all. For instance, if I wanted a visitor to my website to download and run a REXX script (TEST.CMD), let's say for support purposes, I could have a link to a .RSU file like the following:

INSTALL_TYPE=R
INSTALL_PGM=test.cmd
INSTALL_PARMS=/v
FTP_SITE=192.168.107.66 anonymous user@host.rsu
PKG_FILE={
  NAME=support/test.cmd
  UNZIP=N
  FILE_SIZE=12000
  UNZIPPED_SIZE=12000
  MODE=A
}

Mind you, there are probably less roundabout ways of accomplishing the same thing.