Hp Windows NT4 Network Adapter Scripting User Guide

Download

Windows NT4 Network Adapter Scripting

User Guide

May 2003 (First Edition)

Part Number 334274-00A

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the U.S. and other countries.

Intel, Pentium, and Itanium are trademarks of Intel Corporation in the U.S. and other countries.

UNIX is a trademark of The Open Group in the U.S. and other countries.

Hewlett-Packard Company shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided “as is” without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Windows NT4 Network Adapter Scripting User Guide

May 2003 (First Edition) Part Number 334274-00A

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Abstract ............................................................................................................................... 5

Audience Assumptions...................................................................................................... 5

Overview.............................................................................................................................. 5

Introduction......................................................................................................................... 5

Scripting Application (CQNICCMD)................................................................................... 7

Command Line Syntax ................................................................................................................................. 7

Command Line Arguments........................................................................................................................... 8

Command Line Example .............................................................................................................................. 9

Unattended Installation ...................................................................................................... 9

Configuration Properties ................................................................................................. 10

NIC Configuration Properties ..................................................................................................................... 10

Team Configuration Properties................................................................................................................... 10

XML Script File.................................................................................................................. 11

Error Handling and Reporting ......................................................................................... 13

Windows NT4 Network Adapter Scripting User Guide 3

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Abstract

This guide provides information about the scripting feature of the HP Network Teaming and Configuration Utility for Microsoft Windows NT4.

Audience Assumptions

This guide is for the person who administers, configures and troubleshoots networks. HP assumes you are qualified in the servicing of computer equipment and trained in recognizing hazards in products with hazardous energy levels.

Overview

The HP Network Teaming and Configuration Utility enables configuration of network adapters (NICs) and teams of network adapters. The scripting feature of the utility provides the ability to perform adapter configuration using a batch process.

Scripting functionality provides the capability to configure a target system based on configuration information saved from a source server. The target system is not required to be identical to the source server. The configuration of the source server may not be duplicated in its entirety on the target system.

Both NICs and teams of NICs can be configured on the target system. When scripting is run, the NIC properties specified in the data file from the source server are used to modify the configuration of the NICs on the target system.

Introduction

The HP Network Teaming and Configuration Utility (CPQNTAC) and the information provided in this document are for use in Windows NT4 environments only.

When using scripting to configure the target systems, NICs are identified by their relative order in the system. The relative order is determined first by installation status, then by bus, slot and port order in the system. Installed NICs on the system board are assigned the lowest numbers, followed by installed NICs ordered by their slot number, lowest slot number first. Uninstalled NICs follow the same ordering scheme, and are always assigned a higher number than installed NICs. Multi-ported NICs are ordered by ascending port number within each slot.

CAUTION: You must ensure that you are aware of the relative NIC order of both the source and target servers. Failure to do so may cause unexpected results.

Windows NT4 Network Adapter Scripting User Guide 5

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Example 1:

Assume that the source server (A) has four installed NICs, and the target server (B) has two installed and two uninstalled NICs, the relative NIC order would be as follows:

Table 1: Relative NIC Order

Server Relative

Order

A NIC 1 Installed 0 1

A NIC 2 Installed 1 2

A NIC 3 Installed 1 3

A NIC 4 Installed 1 4

B NIC 1 Installed 1 3

B NIC 2 Installed 1 4

B NIC 3 Uninstalled 0 1

B NIC 4 Uninstalled 1 2

Installation State

Bus Slot

Although the bus and slot information for the four NICs is the same in each server, there installation state is different, which results in different relative NIC order.

NICs on the target system are configured to match the corresponding NIC number on the source server. The first NIC on the target system is configured using data from the first NIC on the source server, the second NIC on the target system is configured according to the saved data for the second NIC on the source server, and so on. If the target system has more NICs than the source server, then the extra NICs retain their current settings. If the target system has fewer NICs than the source server, data for additional NICs on the source server is ignored.

Corresponding NICs on the source and target systems do not have to be of the same type since the only properties that are configured from the source data are properties which are common to all NICs.

The target system will be configured with the same number of teams that were present on the source server.

Teams are created on the target system consisting of the same relative NICs that were teamed on the source server. For example, if NICs 3 and 5 were teamed on the source server, then that teaming information is saved in the data file, and NICs 3 and 5 are teamed on the target system during the scripted configuration. In general, the NICs on the team on the target system do not have to be the same type of NICs that were teamed on the source server. However, some NICs cannot be teamed and if an attempt is made to form a team with invalid combinations of NICs, an error will occur. For example, teams with no common speed capabilities cannot be teamed on a load balancing team.

An error will occur in the configuration if the NICs forming the team on the source server are not present on the target system. For example, if NICs 3 and 5 are teamed on the source server but the target system has only four NICs, an error will be reported and the configuration will not be applied.

6 Windows NT4 Network Adapter Scripting User Guide

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

When teams are configured on the target system, the team properties will be set to the values read from the data file for the corresponding team on the source server. Properties not specified in the data file (and properties specified with invalid data values) will be configured using their default settings.

If no teams were configured on the source server, no teaming information will be written to the data file and configuration of the target system will consist only of configuring individual NICs.

Scripting Application (CQNICCMD)

CQNICCMD is a Windows NT4 utility that processes a network adapter configuration script file to duplicate the NIC Teaming configuration of a source ProLiant ML/DL server on a target server. The utility can be run from the command line in a DOS window, from the Run option on the Windows Start menu, or from a Windows command file.

NOTE: In order to execute the CQNICCMD utility from the command line, the HP Network and Teaming Configuration Utility must be closed.

These steps should be followed when using the scripting application.

1. Generate a script file on the source server by clicking Save in the Compaq Network Teaming Configuration user interface or selecting CQNICCMD /S in the Command Line utility.

2. Modify the script file as necessary.

IMPORTANT: If you modify the script file, HP recommends that you run CQNICCMD /P to check the syntax of the modified file and check the log file for errors and warnings. The default location of the log file is \cpqsystem\log\cpqteam.log on the system drive. The syntax of the /P option is cqniccmd /pfilename.

3. Install the HP Network Teaming and Configuration utility on the target system.

4. Run the Command Line utility with the following syntax.

cqniccmd /cfilename

5. Check the log file for errors and warnings. The default location of the log file is \cpqsystem\log\cpqteam.log on the system drive.

NOTE: This utility is designed to be used for unattended installation of NT4. See the “Unattended Installation” section for information.

Command Line Syntax

The configuration option to be performed is specified by command line switches. Only one of the following configuration options can be specified at a time.

Windows NT4 Network Adapter Scripting User Guide 7

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

The following options may be specified with any of the configuration options.

Command Line Arguments

This configuration option causes the source server configuration to be saved. The name of the XML configuration data file must be specified and the path to the data file must exist. This option is identical to saving the source server configuration by clicking Save in the Compaq Network Teaming Configuration user interface.

This configuration option causes all teams on the target server to be dissolved, all VLANs to be removed, and 802.1p/q Packet Tagging to be disabled for all NICs that had VLANs. No additional arguments are required or allowed with this option.

This configuration option applies the configuration specified in the data file to the target system. An existing XML configuration data file must be specified following the target switch. A space following the switch is optional.

NOTE: Any teams that exist on the target system will be dissolved before the configuration is applied. Therefore, any VLAN that exists on the team will be removed, and 802.1p/q Packet Tagging will be disabled. If any VLANs are defined for non-teamed NICs, all existing NIC VLANs will be removed, and

802.1p/q Packet Tagging will be disabled.

This option is identical to the /C option, except that the configuration options are not applied to the target system. This is useful for syntax checking the XML data file.

This option can be used to change the name and location of the cpqteam.log default log file, that is created in \cpqsystem\log on the system drive, for example, C:. The supplied path must exist. An invalid log file name will cause the configuration to terminate with no changes, Compaq recommends this option only in batch files. This option can be specified on the command line with any of the configuration options.

8 Windows NT4 Network Adapter Scripting User Guide

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

This option causes all errors, including those errors normally treated as non-fatal errors, to be treated as fatal errors. This option applies only to the /C option.

This option causes DHCP to be enabled on all NICs that are installed as a result of the configuration. This is intended to be used as part of an unattended installation since this keeps the TCP/IP settings property page from appearing after the binding engine runs. See the “Unattended Installation” section for more information.

Command Line Example

cqniccmd /Sc:\Compaq\teamcfg.xml

cqniccmd /S c:\Compaq\teamcfg.xml

cqniccmd /S”c:\Compaq\teamcfg.xml”

cqniccmd /D

cqniccmd /Cc:\Compaq\teamcfg.xml

cqniccmd /C c:\Compaq\teamcfg.xml

cqniccmd /C”c:\Compaq\teamcfg.xml”

cqniccmd /Pc:\Compaq\teamcfg.xml

cqniccmd /P c:\Compaq\teamcfg.xml

cqniccmd /P”c:\Compaq\teamcfg.xml”

cqniccmd /Cc:\Compaq\teamcfg.xml /Lc:\Compaq\config.log

cqniccmd /C c:\Compaq\teamcfg.xml /L c:\Compaq\config.log

cqniccmd /C”c:\Compaq\teamcfg.xml” /L”{c:\Compaq\config.log”

cqniccmd /F /C c:\Compaq\teamcfg.xml

cqniccmd /N /C c:\Compaq\teamcfg.xml

Unattended Installation

NICs can be installed and configured during unattended installation of the OS in Windows NT4 using the scripting utility, provided that you have a server configured which can act as the source.

Windows NT4 Network Adapter Scripting User Guide 9

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

1. Refer to Microsoft’s documentation regarding unattended setup, and follow the steps

provided.

2. Revise UNATTEND.TXT to install the NICs in your system, and optionally to configure

TCP/IP parameters.

3. Create a script file with the desired speed and duplex settings. HP recommends that you

use the HP Network and Teaming Configuration Utility (CPQNTAC) to create this script file. Click the Save button on the main page of the utility to create TEAMCFG.XML which will contain the current information for the NICs on the source server.

4. Create a directory structure on the share point to be copied to the target server:

<share>\C\HPNICCFG

5. Ensure that $OEM$ directory exists at the root of the share point.

6. Copy the script file to the directory structure created in step 4.

7. Create a CMDLINES.TXT file in the $OEM$ directory on the share point with the

following command line:

c:\winnt\system32\cqniccmd /H /cc:\hpniccfg\<script name> /lc:\hpniccfg\<log file name>

Configuration Properties

The XML data file contains configuration properties for NICs and teams.

NIC Configuration Properties

The properties that are configured on the target server NICs from the source server data are properties that are common to all Compaq NICs. These properties include:

• SpeedDuplex—possible values include Auto/Auto, 10/Half, 10/Full, 100/Half, 100/Full,

1000/Full. The value must be valid for the NIC on the target system.

• NetworkAddress—this value is written only for NICs that are not teamed. It allows the

burned-in address to be overridden with a locally administered address. A null value will always be written to the XML data file because locally administered addresses must be unique. A null value is valid; the network address will be the burned-in address. This value must be a valid unicast address if it is edited.

Team Configuration Properties

The team configuration properties that are configured on the target server include:

• TeamName—determines the unique identifier for the NIC team. Each team name on the

target system must be unique.

• OpMode—determines the team operating mode. Possible values are Manual,

FailOnFault, SmartSwitch, TransmitLoadBalancing, and SwitchAsstLoadBalancing.

10 Windows NT4 Network Adapter Scripting User Guide

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

• PreferredPrimaryNIC—establishes the Initial Primary NIC for Manual, FailOnFault, and TransmitLoadBalancing or the Preferred Primary NIC for SmartSwitch. This configuration property is not applicable to Switch-Assisted Load Balancing teams. The value must be a non-zero integer that corresponds to one of the NICS on the team.

• TeamNetworkAddress—establishes the MAC address for the NIC team. A null value will always be written to the XML data file. A null value is valid and will cause a default address to be computed. This value must be a valid unicast address if it is edited.

• HeartBeatMode—enables or disables the heartbeat signal between the team NICs. Possible values are Enabled or Disabled.

• HeartBeatInterval—determines how frequently the heartbeat signals are transmitted. The range of acceptable values is 3000 to 60000. Values less than 3000 will be set to 3000, while values greater than 60000 will be set to 60000.

XML Script File

The XML data file consists of the three following XML elements:

• <teamingconfig>—Brackets the entire data file and is required.

• <nic>—Defines NIC properties.

• <team>—Defines teams and their properties.

The ‘relnics’ attribute of the <team> element lists the NICs that are to be configured on the team.

The following example is a typical NIC teaming script.

Example 2:

<teamingconfig>         <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>

Windows NT4 Network Adapter Scripting User Guide 11

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

<nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> <property id=‘NetworkAddress’ value=‘‘ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> <property id=‘NetworkAddress’ value=‘‘ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> <property id=‘NetworkAddress’ value=‘‘ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> <property id=‘NetworkAddress’ value=‘‘ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>  <nic> <property id=‘SpeedDuplex’ value=‘Auto/Auto’ /> </nic>     <team relnics=‘1 2’> <property id=‘TeamName’ value=‘Compaq Network Team #1’ /> <property id=‘PreferredPrimaryNIC’ value=‘1’ /> <property id=‘OpMode’ value=‘FailOnFault’ /> <property id=‘HeartbeatInterval’ value=‘3000’ /> <property id=‘HeartbeatMode’ value=‘Enabled’ /> <property id=‘TeamNetworkAddress’ value=‘‘ /> </team>  <team relnics=‘3 4’> <property id=‘TeamName’ value=‘Compaq Network Team #2’ /> <property id=‘PreferredPrimaryNIC’ value=‘3’ /> <property id=‘OpMode’ value=‘FailOnFault’ /> <property id=‘HeartbeatInterval’ value=‘3000’ /> <property id=‘HeartbeatMode’ value=‘Enabled’ /> <property id=‘TeamNetworkAddress’ value=‘‘ /> </team>  <team relnics=‘9 10’> <property id=‘TeamName’ value=‘Compaq Network Team #3’ /> <property id=‘PreferredPrimaryNIC’ value=‘9’ /> <property id=‘OpMode’ value=‘FailOnFault’ /> <property id=‘HeartbeatInterval’ value=‘3000’ /> <property id=‘HeartbeatMode’ value=‘Enabled’ /> <property id=‘TeamNetworkAddress’ value=‘‘ /> </team> </teamingconfig>

12 Windows NT4 Network Adapter Scripting User Guide

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Error Handling and Reporting

Errors can occur for a variety of reasons including differences between the source and target system NICs or because of errors introduced by editing the XML data file. The software performs extensive error checking as the XML data file is read and processed.

When invalid property values are detected, a WARNING error message will be written to a log file and configuration will continue with either default or existing values.

The configuration software returns a completion code as an error level that can be examined in a Windows command file. Successful completion returns an error level of zero (0). Non-fatal errors return a completion code of one (1). An invalid log file returns an error level of two (2). Other fatal errors return a completion code of three (3) or greater. The specifics about all errors can be determined by viewing the log file.

Windows NT4 Network Adapter Scripting User Guide 13

HP CONFIDENTIAL Codename: Gilmer Part Number: 334274-00A Last Saved On: 4/22/03 10:21 AM

Hp Windows NT4 Network Adapter Scripting User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Abstract

Audience Assumptions

Overview

Introduction

Scripting Application (CQNICCMD)

Command Line Syntax

Command Line Arguments

Command Line Example

Unattended Installation

Configuration Properties

NIC Configuration Properties

Team Configuration Properties

XML Script File

Error Handling and Reporting