Jump to article
< >

Active GUI element

Static GUI element


WPS object


Command line

Entry-field content

[Key combination]


Resurrecting RSU - Remote Software Updates

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.

While RSU is great to have on standard OS/2 systems, I don't recommend using it on eComStation systems. The eCS Maintenance Tool [ecsmt] provides its own method of installing FixPaks over the Internet, and it's already much more advanced than RSU ever was. It also handles post-installation dependencies specific to eComStation (like updating the dialog and icon resources), which RSU does not.

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.
The program which interprets the .RSU file and acts according to its instructions.
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:

A typical .RSU file
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

The various keywords are:

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

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.)


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.


This is the string

<FTP server> <username> <password>

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


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:

The fully-qualified name (including path) of the file on the FTP server.
Indicates whether the file should be unzipped (Y) or not (N) after downloading.
The amount of free disk space required on the target drive to store the file.
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.)
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.

The RSUINST.EXE program window
Fig. 1: The RSUINST.EXE program window
If the program window doesn't look like this, then you are using an outdated version of RSUINST.EXE, and need to upgrade it. For some reason even the Convenience Packages ship with an obsolete version of this program.

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.

The FTPINSTL.EXE program window
Fig. 2: The FTPINSTL.EXE program window

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."

Letter suffixes must be in lowercase. FTPINSTL.EXE seems to insist on case-sensitivity when it matches file and directory names; for this reason, I strongly recommend that you always use lowercase names.

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:

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:

Template file for FixPaks on a hypothetical RSU server at
INSTALL_PGM=ftpinstl.exe pristine
INSTALL_PARMS= anonymous user@host.rsu os2_fixpak/*******
FTP_SITE= anonymous user@host.rsu

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:


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= anonymous user@host.rsu os2_fixpak/xr_m005
xr_d001.rsu (Device Driver FixPak 3):
INSTALL_PARMS= anonymous user@host.rsu os2_fixpak/xr_d003
ip_8414.rsu (Peer 4.0 FixPak IP_8414):
INSTALL_PARMS= anonymous user@host.rsu os2_fixpak/ip_8414

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

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.
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.

Remember, as noted earlier, each ZIP file must have the same name as the FTP directory in which it is located, with the addition of a single (lowercase) alphanumeric character at the end, followed by the .ZIP extension.

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.


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.

I recommend using the very latest version of ZIP.EXE. Some other versions abort during the ZIP file creation with a strange error message; I've noticed this in particular with version 2.30 (encryption-enabled distribution), although it seems to be system dependent.

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:

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).


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

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

Example .RSU file for IP_8414
INSTALL_PGM=ftpinstl.exe pristine
INSTALL_PARMS= anonymous user@host.rsu os2_fixpak/ip_8414
FTP_SITE= anonymous user@host.rsu

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 ...

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:

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).


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:

FTP_SITE= anonymous user@host.rsu

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:

FTP_SITE= anonymous user@host.rsu

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

Formatting: Christian Hennecke
Editing: James Moe

The DSKXTRCT.EXE utility, required for extracting FixPak diskette images.
The latest version of RSUINST.EXE and supplementary files from IBM.
The latest RSU-enabled version of the Corrective Service Facility.
My own web page dedicated to RSU; includes RSU FixPak links to IBM's FTP site.
My own web page for REXX programs; DSK2RSU.CMD is available here.
The latest version of Info-Zip's ZIP.EXE utility, recommended.
IBM website for the latest FixPaks (Passport Advantage required for download access).