Admin Alert: Magical & Mysterious iSeries Access CWB Programs

Published: August 29, 2007

by Joe Hertvik

IBM's iSeries Access for Windows package includes a little advertised set of CWB batch utility programs that extend iSeries Access functions beyond the core package. These DOS-based programs perform many valuable functions including backing up and restoring an iSeries Access installation and caching passwords for automatic system i logons. This week, I'll examine these two CWB functions and discuss how they can provide additional capability to Windows machines.

What Are iSeries Access CWB Programs?

The CWB batch utility programs have a long history with iSeries Access for Windows, where some of the programs originated in IBM's older Client Access Express for Windows software and many of them were even available in earlier products. Like many other executables in iSeries Access, all of these program names start with the prefix "CWB," which I suspect may stand for Client for Windows Batch. Some of the more common and valuable CWB utility programs include:

• CWBBACK – Back up iSeries Access for Windows configurations
• CWBCFG – Add or change iSeries Access configuration information
• CWBENV – Import and export server environments
• CWBLOG – Start and stop iSeries Access service logs
• CWBLOGON – Cache system i and iSeries user profile and password information
• CWBPING – Check the status of i5/OS TCP/IP socket servers
• CWBREST – Restore iSeries Access for Windows configurations
• CWBRXD – Runs as a service to process incoming remote commands from a server session.

Most CWB utilities are DOS-based programs that can be called from a shortcut on the Windows desktop, from the Windows Run box, or inside a DOS command box activated from the Windows desktop. While I can't cover every CWB function in this article, I'll focus on the more valuable CWB utilities this issue: the CWBLOGON utility for caching system i and iSeries passwords; and the CWBBACK and CWBREST utilities for backing up and restoring iSeries Access for Windows configurations. I'll cover other valuable CWB programs in future issues.

Caching Passwords for Remote Users

CWBLOGON is designed to simulate persistent password caching on Windows desktops and servers. Using this function, you can cache one or more user IDs and passwords on your PC, and these cached values can be used to automatically sign on to iSeries Access for Windows functions. Given that CWBLOGON is used to create automatic sign-ons and that you may have to store a live password in a text file, you should be careful where you deploy this feature. In general, you should only use CWBLOGON in secured Windows PCs environments, such as you would find in a computer room with limited access. With a few exceptions, using CWBLOGON to automatically sign on to your partitions is generally not a technique administrators should deploy to the general user population.

To cache a password for an i5/OS connection, you would run CWBLOGON this way:

CWBLOGON servername /u userID  /p password

Where servername equals the DNS name or IP address of the server that you want to connect to, userID is equal to the i5/OS user ID that you are caching a password for, and password is the password that will be cached on the machine. When you add a cached password to your Windows system, many of your PC's iSeries Access applications will use that password to automatically sign on the stored user to your target server, provided that you follow these ground rules for entering and using valid passwords.

1. Cached user profiles must match the default user profile that is defined in iSeries Navigator (OpsNav) for the target partition. If the user ID for your cached password does not match the default user profile you defined for that system in OpsNav, you will not be able to use password caching with that partition. For more information about designating default user profiles in OpsNav, see an earlier article I wrote called PC5250 Communication Sign-On Tricks.
2. When you create a cached user profile-password combination with CWBLOGON, the cached password is only valid for the current Windows session. All iSeries Access cached passwords are removed when the hosting Windows machine is rebooted. You can use CWBLOGON to create persistent cached passwords across log-ins by embedding the CWBLOGON command inside a batch file that runs whenever the Windows server starts or when a user logs on. Embedding passwords in a text file is a compelling reason to limit this technique to server machines in a restricted environment, because passwords in .BAT files are generally stored in clear text that can easily be discovered by other users or hackers.
3. CWBLOGON cached profiles and passwords can be accessed in several different iSeries Access for Windows functions. When used for PC5250 sign-ons, these cached passwords are generally used only to make the initial connection to your i5/OS box when the Signon to iSeries input box appears. Depending on how your system is configured, the user may also have to sign-on again to the session's PC520 device to start a green-screen session. I have also tested using CWBLOGON to automatically start ODBC sessions and to start file transfers with the iSeries Access Data Transfer to iSeries Server and Data Transfer from iSeries Server programs, and it works well with those programs.

Removing Cached Passwords

If you want to remove cached passwords for a particular system i or iSeries server, you can run CWBLOGON this way:

CWBLOGON servername  /c

Where servername is again equal to the DNS name or IP address of the server that you are removing cached passwords from, and the /c parameter tells CWBLOGON to clear the cached passwords for the designated entries.

To remove all cached passwords from all system i servers defined on your machine, you can run CWBLOGON like this:

CWBLOGON /c

Run this way, CWBLOGON clears out your entire stock of cached passwords for any system i or iSeries server that you access from this PC.

Backing Up and Restoring an iSeries Access Installation

In case your computer crashes, data corruption occurs, or if you want to restore or move an earlier configuration, IBM provides two programs that allow you to backup and restore iSeries Access for Windows configurations. These programs are:

CWBBACK – Backup your iSeries Access configuration to disk

CWBREST – Restore a previously backed up iSeries Access configuration from disk to your desktop

The process to backup and restore your configuration allows you to save/restore copies of the following iSeries Access for Windows configuration objects.

• Environment definitions and connections
• Default system names for each environment
• Service parameters
• Password warning expiration parameters
• Password caching settings

The saved objects are stored in two files. One file is saved with an extension of .rs, and IBM documentation says that it contains all the main configuration information for your installation. The second file is created with an extension of .ts, and it contains what IBM refers to as companion auxiliary information for the .rs file.

The programs are easy to run. To back up a machine's iSeries Access configuration, you would run the CWBBACK program this way:

CWBBACK [x:\folder\filename.rs] [/u]

Both parameters are optional. If you don't specify a name or directory to save the files to, the backup files will be saved to your iSeries Access installation directory with the following names:

Main file: CWBCFBAK.RS

Auxiliary file: CWBCFBAK.TS

The /u parameter is only necessary if you are running CWBBACK as a restricted user, not as a Windows administrator. This is because CWBBACK will attempt to back up iSeries Access information from locations that restricted users do not have access to, particularly information regarding service pack installs. So if a restricted user is running CWBBACK, they should use the /u parameter to flag the program not to save that information. Administrative users should run CWBBACK without the /u parameter.

It's also worth noting that while the default CWBBACK save location is the iSeries Access install directory, it may be worth your while to save this information to a user network drive so that you don't run the risk of corrupting your backup on the target machine.

To restore this information from your save files to your target machine, you would then run the CWBREST restore command like this:

CWBREST [x:\folder\filename.rs] [/c]

The x:\folder\filename.rs parameter is the location and name of the same .rs file that you backed up with CWBBACK. Like CWBBACK, it will look for the default .rs and .ts files in the iSeries Access install directory if no file name is specified. Also like the backup program, it's best to run CWBREST as the Windows administrator.

Besides backing up and restoring as the Windows administrator, the only other gotcha for restoring a configuration occurs when an iSeries Access service pack has been installed on the machine since the last backup. In that case, there's a possibility that the location of service pack information is different from the location of some of the data that was backed up. This situation can cause your restore to fail. To properly complete the restore, CWBREST includes the /c parameter, which finishes the restore process even when it would normally fail. The problem with a /c restore is that it could corrupt your new installation if your directory locations have changed. My recommendation is that if you need to force a CWBREST restore with the /c parameter, you are probably better off reinstalling the program and configuring the PC's iSeries Access setup from scratch.

About Our Testing Environment

Configurations described in this article were tested on an i5 550 box running i5/OS V5R3. Many of the commands may also be available in earlier versions of the operating system running on iSeries or AS/400 machines. iSeries Access for Windows features were tested with iSeries Access for Windows V5R3M0. If a command or function is present in earlier versions of the i5/OS or OS/400 operating systems, you may notice some variations in the pre-V5R3 copies of these commands. These differences may be due to command improvements that have occurred from release to release.

RELATED ARTICLE

PC5250 Communication Sign-On Tricks

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot