Upgrading Network Client Software with Automatic Client Update (ACU)
Articles and Tips: article
Technical Writer
Distributed Networks Business Unit
BRAD ANDERSON
Product Manager
Distributed Networks Business Unit
01 May 1996
In the past, when Novell has released updates to the client software, network administrators have had to physically go to each workstation and manually upgrade the NetWare client software. To reduce this administrative burden and make it easier to distribute and install NetWare clients, Novell has developed an Automatic Client Update (ACU) process. Using this process, administrators can set things up so that updated NetWare client software is installed automatically when users log in. This Application Note describes the Automatic Client Update process and gives examples of how to set up ACU to update workstations to the latest release of NetWare Client 32 for DOS/Windows 3.1x.
- Introduction
- ACU Components
- Overview of the ACU Process
- Using the Install Stamp Parameters
- Syntax for the ACU Utilities
- Checking Out the INSTALL.CFG File
- For More Information
Introduction
Novell's Automatic Client Update (ACU) provides a way for network administrators to automatically upgrade NetWare client software. ACU executes a series of instructions placed by the administrator in a container, profile, or system login script. These instructions automatically upgrade the client workstations during the next login, without requiring any manual intervention from the user or the administrator.
Automatic Client Update is the name of a process, rather than a specific utility. The process involves four new individual utilities -- NWDETECT.EXE, NWSTAMP.EXE, NWLOG.EXE, and REBOOT.COM-- plus an enhanced version of the NetWare client installation program (INSTALL.EXE). These components are included as part of the NetWare Client 32 for DOS/Windows 3.1x software, as well as in the latest releases of other NetWare client software.
This AppNote describes the purpose and use of the ACU components and gives instructions on how the ACU process works. It also provides a command reference for the ACU utilities.
ACU Components
Before implementing the Automatic Client Update process, it is helpful to understand the purpose and use of each of the related components. These include the four ACU utilities listed above, the enhanced INSTALL.EXE program, the Install Stamp, and Exit Codes.
ACU Utilities
Following is a brief explanation of what each of the ACU utilities does. More details will be given later in this AppNote.
NWDETECT.EXE begins the ACU process by looking for an Install Stamp in the NET.CFG file and detecting whether there is a difference between the stamp parameters within the login script and those within the NET.CFG file.
NWSTAMP.EXE updates (or creates for the first time) the Install Stamp in the NET.CFG file.
NWLOG.EXE creates a log file of all upgraded nodes in a subdirectory specified by the network supervisor. The log file lists the date, time, username, IPX external network number, node address, and, optionally, any text defined by the network supervisor.
REBOOT.COM is an executable file that automatically reboots the workstation.
INSTALL.EXE Program
INSTALL.EXE is the DOS-based NetWare client installation utility. It is executed if NWDETECT.EXE determines that an upgrade is necessary. The actual files that are copied to the workstation are determined by the listing contained in the [Files] section of the INSTALL.CFG file (described below).
Only INSTALL.EXE versions 1.50 and later support the ACU instructions in the INSTALL.CFG file. Previous version of INSTALL cannot be used with the ACU process.
|
Note: Due to a compatibility problem between LOGIN.EXE andDR-DOS version 6, INSTALL.EXE version 1.5x will not runon a workstation running DR-DOS 6 unless upper memoryis disabled. To disable upper memory, type:memmax -u. |
Install Stamp
The Install Stamp is an entry in a workstation's NET.CFG file that specifies values for four parameters: Name, Major Version, Minor Version, and Revision Version. These parameters are indented under the Install Stamp heading in the NET.CFG file, as follows:
Install Stamp Name = Novell_Client32 Major Version = 4 Minor Version = 1 Revision Version = 0
If any of these parameters differ from those defined by the network administrator in the NWDETECT command in the login script, the upgrade instructions within the login script may be invoked (depending on other conditions set in the login script).
Exit Codes
An exit code is a value returned by NWDETECT.EXE based on its comparison of the workstation's Install Stamp located in the NET.CFG file:
An exit code of "0" (true) means that the command-line syntax values placed in the NWDETECT login script command match those in the workstation's Install Stamp.
An exit code of "1" (false) signifies that the values in the Install Stamp do not match, or that an Install Stamp heading does not exist in the NET.CFG file.
|
Note: An exit code is the same as an ERROR_LEVEL, which is akeyword used in login scripts. All executable ACU utilitiesuse exit codes, not just NWDETECT. |
Overview of the ACU Process
The basic process by which the NetWare client software is automatically updated with ACU is simple. Before you perform the actual ACU process, however, you need to complete a few preliminary tasks.
Decide which type of login script to use.
The type of login script you need to modify to execute the ACU utilities depends on which workstations you want to upgrade:
For workstations running Bindery-based client software (NETX) on a NetWare 3.x network, or bindery emulation on a NetWare 4.x server, you'll use the system login script(NET$LOG.DAT). This is accessed from the SYSCON utility.
For workstations running Directory Services-based client software (VLM or Client 32) on a NetWare4.x network, you can use either a container or a profile login script. These are accessed using either the NWADMIN or NETADMIN utility.
If the type of login script you decide to use does not exist, you must create one. You should also determine which drive the users will map to in the login script to access INSTALL.EXE and the Client 32 installation files.
Install the NetWare Client 32 files onto a network server.
If you haven't done so already, create a subdirectory on the server to install the NetWare Client 32 files into: for example, SYS:PUBLIC\CLIENT\DOSWIN32. Then run the Client 32 installation program as outlined in the AppNote entitled "Installing NetWare Client 32 for DOS/Windows" in this issue.
Copy the ACU utilities up to the Client 32 parent directory.
For easier access to the ACU utilities, copy the executables from the \ADMIN\DOS_ACU subdirectory to the parent directory into which you installed the Client 32 files(SYS:PUBLIC\CLIENT\DOSWIN32 in our example). You can use a command such as the following, after using the DOS CD command to change to the DOS_ACU directory:
XCOPY *.* ... /S
The three dots are shorthand for "two levels up from the current directory." The "/S" option copies the message(*.MSG) files from the \NLS\ENGLISH subdirectories under DOS_ACU into the \NLS\ENGLISH subdirectories under DOSWIN32.
Create a directory for the ACU log files.
Create a LOG subdirectory under the DOSWIN32 directory. Grant all users Create and Write rights to this subdirectory, which will be used for log files produced by NWLOG.EXE.
Review the settings in the INSTALL.CFG file.
The XCOPY command in Step 3 should also have copied the INSTALL.CFG file into the DOSWIN32 directory. With a text editor, open this file and change the InstallType setting under the [Setup] heading to AUTO as shown:
[Setup] InstallType=AUTO
This setting allows the installation program to run in unattended mode, which does not require the user to answer any prompts. Any other desired configuration changes in INSTALL.CFG should also be made at this time. See the heading "Checking Out the INSTALL.CFG File" later in this AppNote for details.)
Insert the ACU commands into the login script.
To perform an actual automatic upgrade, you access the login script you chose to use in Step 1 and insert the appropriate commands for the ACU process. (An example is given below.) The ACU occurs the next time users run the login script.
Test your ACU setup in a test environment.
Before you implement ACU on a large scale, start by monitoring the client upgrades on two or three workstations. If the upgrades run successfully, you can extend ACU to your entire user base.
|
Note: If a large number of users meet the criteria for upgrade, you may want to stagger the times or days that the workstations are upgraded to avoid network traffic and server utilization problems. For example, you wouldn't want 1000 users to be upgraded all at once when theylog in at 8:00 a.m. on Monday morning. |
ACU Example
The following example assumes that you are the supervisor of a NetWare 4.x network and you have just obtained the NetWare Client 32 for DOS/Windows 3.1x software. You have several workstations to upgrade that are currently running the NetWare DOS Requester (VLM) client software.
For simplicity's sake, we assume your users are all in the same NDS container, and you have already set up a container login script for them. This is the login script you'll use for the ACU process.
You next install the NetWare Client 32 for DOS/Windows 3.1x files to a network server. The files are placed in the SYS:PUBLIC\ CLIENT\DOSWIN32 subdirectory on the server. You copy the ACU utilities and message files to this directory and create the \LOG subdirectory as instructed.
In a text editor, you bring up the INSTALL.CFG file and, under the [Setup] heading, change the InstallType= setting to AUTO.
Using the NWADMIN utility, you access the container login script and insert the following lines at the beginning of the script (line numbers have been added for ease of reference):
01 MAP I:=FS1/SYS:PUBLIC\CLIENT\DOSWIN32 02 #I:NWDETECT Novell_Client32 4.1.0 03 IF ERROR_LEVEL = "1" THEN 04 #I:INSTALL 05 IF ERROR_LEVEL = "0" THEN 06 #I:NWSTAMP Novell_Client32 4.1.0 07 #I:NWLOG /F I:\PUBLIC\CLIENT\DOSWIN32\LOG\UPDATE.LOG 08 #I:REBOOT 09 END 10 END 11 MAP DEL I:
Line 01: As each user logs in, the container login script maps drive I to the SYS:PUBLIC\CLIENT\DOSWIN32 subdirectory.
Line 02: The NWDETECT.EXE utility runs next and looks in the workstation's NET.CFG file for an Install Stamp. In this case no Install Stamp exists, so NWDETECT returns an exit code of "1".
Line 03: The IF ERROR_LEVEL = "1" statement in the login script evaluates as true, because the exit code returned by the ACU utilities is the same as ERROR_LEVEL in the login script.
Line 04: The INSTALL.EXE program is run. During the DOS-based client installation, the files specified in INSTALL.CFG (all Client 32 files by default) are copied to the workstation. When the installation completes successfully, INSTALL.EXE returns an exit code of "0".
Line 05: If INSTALL.EXE does not complete successfully, we do not want to update the Install Stamp. This IF/THEN statement allows NWSTAMP to run only if IF ERROR_LEVEL = "0" evaluates as true.
Line 06: The NWSTAMP.EXE utility runs next. Since no Install Stamp existed in the NET.CFG file, it creates one with the values indicated on the command line:
Install Stamp Name=Novell_Client32 Major Version=4 Minor Version=1 Revision Version=0
The workstation is now set up with an updated Install Stamp so the ACU process will be bypassed during subsequent logins. (It is also prepared with current version information so that ACU will work smoothly when a new Client 32 release becomes available.)
Line 07: The next command in the login script causes the NWLOG.EXE utility to run, appending the date and time of the update, the username, the network and node address, and any other defined text to the UPDATE.LOG file in the \LOG subdirectory of SYS:PUBLIC\CLIENT\DOSWIN.
Line 08: Finally, the REBOOT.COM utility reboots the workstation so that the new client software can be loaded.
This time around when the container login script executes, NWDETECT finds the Install Stamp in the NET.CFG file and detects a match for the four parameters. It returns an exit code of "0", which causes the execution logic to bypass the ACU instructions and proceed with the rest of the login script.
This example has presented the ACU process in its simplest form. You can adapt these login script commands and add parameters as necessary to meet the needs of your particular client base.
Using the Install Stamp Parameters
The four Install Stamp parameters are defineable by the network administrator. In typical usage, the Major Version, Minor Version, and Revision Version parameters refer to the version of the client software. In the example above, the Install Stamp identifies Novell Client 32 version 4.1.0. However, it's not required that these values match up with a particular NetWare client version. The critical thing for ACU is that they match (or don't match) the values specified in the NWDETECT command in the login script.
Consequently, you can use any values you want for these parameters. The only rules are that the Name parameter can contain up to 63 alphanumeric characters, while the three Version parameters can contain 127 characters each. If you choose to use spaces, the entire name or version string must be enclosed in double quotes (" ").
For example, you could set the Name parameter to "ENG" or "GROUP-1" to identify a group of users to be upgraded at the same time. You could use the Major Version parameter to define the server storing the ACU and client files, the Minor Version to list the department to be upgraded, the the Revision Version to identify the version of client files to be installed.
You may need to set up groups for each type of workstation hardware configuration you have, with separate INSTALL.CFG files for each group. You can specify which file you want to use for ACU by adding the /C option to the INSTALL command in the login script. For example:
INSTALL /C=INSTGR1.CFG
Syntax for the ACU Utilities
The following tables describe the command-line syntax and optional parameters for each of the ACU utilities. Square brackets ( [ ] ) indicate optional parameters; pointed brackets ( < < ) indicate required parameters.
NWDETECT.EXE
NWDETECT [name] [version1] [version2] [Options...]
|
Parameter |
Description |
Examples |
|
[name] |
Name to detect. This can be any alphanumeric string specified by the administrator. For example, it can be used to identify a NetWare client type, or a group ofusers to upgrade. |
Novell_Client32Engineering |
|
[version1] |
Version stamp or starting version to detect. |
1.0.04.*.* |
|
[version2] |
Ending version to detect. Used only when [version1] isa starting version, to define a range of version numbers. |
1.2.B5.*.* |
OPTIONS...
|
Option |
Description |
Examples |
|
[/T client_type] |
Used for detecting type of client loaded. Valid clienttypes include NETX, VLM, and NIOS. |
/T VLM |
|
[/P "prompt text"] |
Prompts the user if the /T option returns "True" or 0. The user must be able to answer the prompt with a Y or N. A Y returns an exit code of 0; an N returns an exit code of 1. |
/P "Upgrade client? (Y/N)" |
|
[/C path\filename] |
Full path and name to the configuration file containing the Install Stamp. This is normally C:\NWCLIENT\NET.CFG, but it can be any configuration file you specify. This option is not necessary if the client loads either LSL or NIOS.EXE. |
/C C:\NET\NET.CFG |
|
[/NS] |
Detects whether there is no stamp in the NET.CFG file.If no stamp is found, an exit code of 0 is returned. |
/NS |
USAGE EXAMPLES
|
Command |
Result |
|
NWDETECT Novell_Client32 1.0.0 |
If the values in NET.CFG's Install Stamp match these, an exit code of 0 (TRUE) is returned. Ifnot, an exit code of 1 (FALSE) is returned. |
|
NWDETECT /T VLM /P "Do you want to upgrade (Y/N)?" |
If the workstation is running the VLM client software, the prompt text is displayed. If the user answers Y, an exit code of 0 (TRUE) is returned. Otherwise, an exit code of 1 (FALSE)is returned. |
|
NWDETECT GROUP_1 1.0.0 2.0.0 /T NIOS |
If the workstation is running NetWare Client 32 (NIOS client type) and has a stamp name of "GROUP_1" and a version between 1.0.0 and 2.0.0, an exit code of 0 (TRUE) is returned. Otherwise, an exit code of 1 (FALSE) isreturned. |
|
NWDETECT ENG 1.*.* |
If the workstation has a stamp name of "ENG" and a Major Version of 1, an exit code of 0 (TRUE) is returned. Otherwise, an exit code of 1 (FALSE) is returned. |
|
NWDETECT /NS /T NETX |
If the workstation is running the NETX client software and does not have an Install Stamp in its NET.CFG file, an exit code of 0 (TRUE) is returned. Otherwise, an exit code of 1 (FALSE) is returned. |
NWSTAMP.EXE
NWSTAMP <name< <version< [Options...]
|
Parameter |
Description |
Examples |
|
<name< |
Name to set in the Install Stamp section of the NET.CFG file. The name can be any alphanumeric string defined by theadministrator, but it cannot contain spaces. |
Novell_Client32Engineering |
|
<version< |
Version stamp to set in the Install Stamp section of the NET.CFG file. The version must be in the x.x.x format. |
1.1.0 |
OPTIONS...
|
Option |
Description |
Examples |
|
[/B <backup_name<] |
Create a backup of the original NET.CFG fileusing the path and filename specified. |
/B C:\NWCLIENT\NETCFG.BAK |
|
[/C path\filename] |
Full path and name of the configuration file where the Install Stamp will reside. This is normally C:\NWCLIENT\NET.CFG, but it can be any file you specify. This option is not necessary if the client loads either LSL orNIOS.EXE. |
/C C:\NET\NET.CFG |
USAGE EXAMPLES
|
Command |
Result |
|
NWSTAMP Novell_Client32 1.0.0 |
Writes the following to the NET.CFG file: Install StampName = Novell_Client32Major Version = 1Minor Version = 0Revision Version = 0 |
|
NWSTAMP GROUP_1 96.5.A /B C:\NWCLIENT\NET.BAK |
Writes the following to the NET.CFG file:Install StampName = GROUP_1Major Version = 96Minor Version = 5Revision Version = A Saves the original NET.CFG file as NET.BAK. |
NWLOG.EXE
NWLOG </F path\filename< [/M "messag e"]
|
Parameter |
Description |
Examples |
|
</F path\filename< |
Path and filename to write log entry. |
/F UPDATE.LOG |
|
[/M "message"] |
Additional message to add with log entry. The message must be in quotes. The total number of alphanumeric characters allowed for the message and NWLOG command line syntax is 125. However, when using loginscript identifier variables, the number of characters allowed is reduced. |
/M "Client upgrade successful" |
A sample log entry for an upgraded NDS (NetWare Directory Services) client is shown below:
5-17-96 4:01:25 pm JSMITH.ACCTG.NOVELL 010104A0:00001B021FDB Client upgrade successful.
This log entry indicates that the workstation belonging to User object JSMITH.ACCTG.NOVELL was upgraded at 4:01 p.m. on May 17, 1996. The numbers are the workstation's IPX external network number and node number. The message on the second line was defined by the administrator in the login script.
Checking Out the INSTALL.CFG File
INSTALL.CFG is a configuration file that has been available since the NetWare DOS Requester client was released. Essentially, you add the configuration parameters you want to the INSTALL.CFG file, and the INSTALL.EXE program will read in those parameters and place them in the workstation's NET.CFG file during the client installation.
A default INSTALL.CFG file is included with NetWare Client 32 in the \NLS\ENGLISH subdirectory. This file contains a listing all of the client software files and any associated configuration parameters to be copied to the workstation during installation. During the ACU process, INSTALL.EXE (version 1.5 and above) uses the configurations listed in INSTALL.CFG (or in another configuration file defined by the network administrator) to know which files to copy and where to copy them.
Most users will not need to modify INSTALL.CFG except for the ACU-specific settings under the [SETUP] heading. The only necessary modification is to change the InstallType= setting from BASIC to AUTO under the [SETUP] heading. You can use a text editor to do this.
The [SETUP] section of the INSTALL.CFG file is shown below, as it should appear with the InstallType set to AUTO:
[Setup] InstallType = AUTO TargetPath = *AUTO InstallWindows = AUTO WindowsUserPath = C:\WINDOWS UpdateDOSSystemFiles = True OverwriteStartnetBat = True DoInstallIfLowSpace = True CopyAllUnicodeFiles = False OverwriteNewerFiles = False OverwriteNewerINIFiles = False OverwriteReadOnlyFiles = False OverwriteReadOnlySYSFiles = False Use32BitDrivers = True UpdateRequester = False
An explanation of each setting follows.
|
InstallType |
AUTO: (Default) Runs in unattended mode, asks no questions (errors are not presented to the user, but are logged in NWCINST.LOG, located in the directory where LSL is loaded). BASIC: Asks user to confirm automatically detected answers and to answer allother questions. |
|
TargetPath |
*AUTO: (Default) Automatically detects the target path according to where LSL found NET.CFG. In the unlikely event that this cannot be found, then searches the environment path for NIOS.EXE, VLM.EXE, or NETX.COM and installs in that location. The default TargetPath is NOVELL\CLIENT32. <path<: A full path (no spaces allowed) to the directory where the client filesare to be installed (for example, D:\NETWARE). |
|
InstallWindows |
TRUE: Installs MS Windows utilities and drivers; requires an MS Windows user path (WindowsUserPath).FALSE: Does not install MS Windows utilities and drivers. AUTO: (Default) If Windows' WIN.COM is found in the environment path,then installs Windows support in that path. |
|
WindowsUserPath |
<path<: A full path to the Windows directory where the files will be installed. A shared network path won't work; the ACU process supports only a local Windows path. A path is needed only if the InstallWindows parameter is set to TRUE. |
|
UpdateDOSSystemFiles |
TRUE: (Default) Modifies AUTOEXEC.BAT and CONFIG.SYS and saves backups with a .BNW extension. FALSE: Does not modify AUTOEXEC.BAT and CONFIG.SYS. Makes the necessary changes to the AUTOEXEC.NEW and CONFIG.NEW files, whichare created automatically and stored in the NOVELL\CLIENT32 subdirectory. |
|
OverwriteStartnetBat |
TRUE: (Default) Updates STARTNET.BAT, creates a STARTNET.BNW, and saves it as a backup. FALSE: Does not update STARTNET.BAT. Makes the changes to the STARTNET.NEW file, which is created automatically in the NOVELL\CLIENT32subdirectory. |
|
DoInstallIfLowSpace |
TRUE: (Default) Continues the installation even if disk space is low. FALSE: Stops the installation if disk space is low and records an error in theNWCINST.LOG file, located in the directory where LSL was loaded. |
|
CopyAllUnicodeFiles |
TRUE: Copies the Unicode files for all countries. FALSE: (Default) Copies only the Unicode files for the country code loaded onthe target machine. |
|
OverwriteNewerFiles |
TRUE: Overwrites files located in the TargetPath that are newer if installation source files are older. FALSE: (Default) Does not overwrite newer files in the target path with anyolder files from the installation source path. |
|
OverwriteNewerINIFiles |
TRUE: INSTALL.EXE overwrites any modifications made to the NWADMIN.INI file by copying over the file with the original NWADMIN.INI file and its original settings. (This setting is not suggested.)FALSE: (Default) Does not overwrite a modified NWADMIN.INI file. |
|
OverwriteReadOnlyFiles |
TRUE: Overwrites files marked Read Only. (See OverwriteReadOnlySYSFiles)FALSE: (Default) Does not replace files marked Read Only. |
|
OverwriteReadOnlySYSFiles |
TRUE: Updates or modifies DOS and Windows system configuration files that are flagged Read Only. FALSE: (Default) Does not modify DOS and Windows system configuration files that are flagged Read Only. Stores the file modifications in a file with thesame name but with a .NEW file extension. |
|
UpdateRequester |
TRUE: Compares the [REQUESTER] section of the INSTALL.CFG file with the NetWare DOS Requester section in the workstation's NET.CFG file. If keywords are different, deletes all information in the NetWare DOS Requester section and replaces it with information in the [REQUESTER] section of theINSTALL.CFG file. FALSE: (Default) Compares the [REQUESTER] section of the INSTALL.CFG file with the NetWare DOS Requester section located in the workstation's NET.CFG file. If keywords are different, appends the information in the NetWare DOS Requester section with the information in the [REQUESTER]section of the INSTALL.CFG file. |
There are certain instances where you might want to edit the INSTALL.CFG file to achieve the desired ACU results. For example, you can edit the [FILES] section when you want to update only a few files (for example, some updated client files downloaded from NetWire) rather than the entire set of client files.
|
Note: For detailed information about the settings in the othersections of INSTALL.CFG, refer to the ACU.TXT file foundin the DOS_ACU\NLS\ENGLISHsubdirectory. |
If you choose to edit the INSTALL.CFG file, we recommend that you make a copy of the original INSTALL.CFG file and save it somewhere so that it can be retrieved in case you encounter problems with the edited INSTALL.CFG.
Settings in the [FILES], [REQUESTER], and[SETUP] sections of INSTALL.CFG are generallyuniversal to all upgraded workstations and do notrequire additional configuration work at theindividual workstations.
A number of settings in the [TCP/IP], [NWIP],[SNMP], [HOSTMIB] and [TSA] sections requireadditional configuration at the workstation.Consequently, many of the settings in thesesections are "dummy" settings.
Some sections in the INSTALL.CFG file contain an "Override local settings =" parameter. If this parameter is set to FALSE, the values within that section will be updated only on workstations that don't have those values defined. If the parameter is set to TRUE, those values will override the existing values, or replace them as new values.
You can specify which INSTALL.CFG file you want to use for ACU by adding the /C option to the INSTALL command in the login script. For example:
INSTALL /C=INSTGR1.CFG
For More Information
More information on ACU, sample login scripts, and explanations of all INSTALL.CFG settings are given in the ACU.TXT readme file found in the DOS_ACU\NLS\ENGLISH subdirectory.
If you have any enhancement requests for Automatic Client Update, send them to:
enhclient@novell.com
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.