NETEX NESiGate-CO User manual

NESiGate-CO
NetEx/IP Offload Channel-to-IP Gateway
Release 2.10
Reference Manual
MAN-REF-COSW 2.10-19

Revision Record
Revision Description
01 (April 2001) Initial manual release by Network Executive Software.
02 (July 2001) Added messages and NRBSTAT Session error codes
03 (Oct 2001) Incorporate NetEx/IP Release 6.2.5.
04 (Jan 2002) Updated for Red Hat 7.2 distribution and miscellaneous corrections and addi-
tions.
05 (Apr 2002) •Added documentation for new initialization parameters.
•Added documentation for additional NetEx operator commands.
06 (xxx 2002) Added documentation for Hitachi IBM-compatible configuration require-
ments.
07 (Oct 2002) Added documentation for NG_CO service
08 (Dec 2002) Removed Integration section to NESiGate Software Installation Guide
09 (Jun 2005) Added Software RAID to installation
10 (Aug 2005) Updated for release 2.7.2
11 (Jan 2006) Updated for release 2.7.4
12 (Jan 2006) Updated for release 2.7.5
13 (Feb 2006) Updated for release 2.7.6
14 (Oct 2006) Updated for release 2.8
15 (Nov 2006) Updated for release 2.8.1
16 (Feb 2007) Updated for release 2.8.2
17 (Apr 2007) Updated for release 2.8.3; Major command security redefinitions
18 (Feb 2008) Updated for release 2.9.1
19 (Feb 2010) Update for release 2.10
© 2008-2010 Network Executive Software, Inc. Reproduction is prohibited without prior permission of
Network Executive Software. Printed in USA. All rights reserved.
The U.S. Department of Commerce restricts the distribution of technical information contained in this
document when exported outside the U.S. Therefore, careful attention should be given to compliance
with all applicable U.S. Export Laws if any part of this document is to be exported.
Page ii MAN-REF-COSW 2.10-19

Table of Contents
Table of Contents .....................................................................................................................................iii
Copyrights and Trademarks ...................................................................................................................v
Notice to the Customer..........................................................................................................................vi
NESiGate Modification Policy..........................................................................................................vi
Introduction................................................................................................................................................1
Customization.............................................................................................................................................3
Overview................................................................................................................................................3
Device addressing ..............................................................................................................................3
Device Number ..............................................................................................................................3
GNA Address..................................................................................................................................4
IP Address......................................................................................................................................4
Using a Web Browser to Configure NESiGate......................................................................................5
Define the Channel Boards(s) ............................................................................................................5
Define the Devices.............................................................................................................................5
Configure NetEx/IP............................................................................................................................5
GNA to IP Mapping...........................................................................................................................6
Reboot NESiGate...............................................................................................................................7
Web Browser Interface...............................................................................................................................9
Overview................................................................................................................................................9
Browser Considerations .....................................................................................................................9
Initial Screen ......................................................................................................................................9
Common Command Frame................................................................................................................9
Common Webpage Navigation..........................................................................................................9
NESiGate Board/Channel Commands .............................................................................................10
Show Channel Config ..................................................................................................................12
Show Channel Info.......................................................................................................................13
Channel Display Stats ..................................................................................................................13
Channel Define Interface..............................................................................................................15
Remove Channel Interface...........................................................................................................16
NETEX Webpage.............................................................................................................................17
MAN-REF-COSW 2.10-19 Page iii

Modify NetEx Startup Parms.......................................................................................................18
NetEx Eat/Gen Test......................................................................................................................18
Appendix A: Configuration Worksheet ...................................................................................................19
Appendix B: NetEx Default Parameters...................................................................................................21
Appendix C: NetEx/IP Messages.............................................................................................................29
Viewing NetEx/IP Messages............................................................................................................29
Using the Web Browser Interface ................................................................................................29
Using the Command Line Interface..............................................................................................29
Messages:.........................................................................................................................................30
Appendix D. NRB Status Error Codes.....................................................................................................37
General Errors ......................................................................................................................................37
Session Errors.......................................................................................................................................38
Appendix E: NESiGate Sense Bytes........................................................................................................41
NESiGate ESCON............................................................................................................................41
Page iv MAN-REF-COSW 2.10-19

Copyrights and Trademarks
This document contains references to the trademarks of the following corporations.
Corporation Trademarks
International Business Machines ESCON®
Unisys Corporation SBCON
RedHat,Inc. RedHat®
Note: RedHat® is a registered trademark of Red Hat, Inc. This product is not a product of Red Hat,
Inc. and is not endorsed by Red Hat, Inc. This is a product of Network Executive Software and we have
no relationship with Red Hat, Inc.
Additional trademark references:
MAN-REF-COSW 2.10-19 Page v

Notice to the Customer
Comments about this manual may be submitted via mailto:pubs@ netex.com or by visiting our website:
www.netex.com. Always include the complete title of the document with your comments.
Information on Network Executive Software’s general software support policy (e.g., alternate contact
methods, support severity level descriptions, and service status definitions) may be found at
http://www.netex.com/support/software-support-policy.
Details on Network Executive Software’s warranty and support policies specific to NESiGate may be
found at http://www.netex.com/support/nesigate-warranty-and-support-policy.
NESiGate Modification Policy
NESiGate is an appliance that contains proprietary software and firmware. Modifications to the soft-
ware, firmware, or hardware platform that are not specifically authorized by NESi are prohibited.
Examples of prohibited activities include (but are not limited to) the following items:
•Installing other software on NESiGate
•Modifying the file system through means other than NESiGate’s defined User Interfaces (in-
cluding adding, deleting, or moving files and/or directories, adding or deleting user accounts or
changing permission levels, ownership, or other attributes of files and/or directories)
•Starting or stopping system services through means other than NESiGate’s defined User Inter-
faces
•Adding or removing hardware components
Any unauthorized modifications to NESiGate may affect its operation and/or obstruct NESi’s ability to
diagnose problems and provide corrections. Any work resulting from unauthorized modifications shall
be paid by the customer at NESi’s then-current support rates and may result in the immediate termina-
tion of warranty/support coverage.
Page vi MAN-REF-COSW 2.10-19

MAN-REF-COSW 2.10-19 Page vii

Introduction
The purpose of this manual is to provide an overview of the procedures used to integrate and customize
the NetEx/IP components onto a NESiGate channel offload platform, and to provide a description of the
command and web browser interfaces.
This manual is divided into the following sections:
1) Software Installation: Installation of NESiGate software on the hardware platform is covered in
the NESiGate Common Reference Manual. Refer to that guide, then return to this manual to com-
plete the configuration of NESiGate as a Channel Offload (CO) type device
2) Customization: this section is targeted to the end-user who is responsible for customizing the NE-
SiGate appliance for use as a NetEx/IP channel offload device. It is assumed the NESiGate already
has the appropriate level of the system software installed. To complete the customization, the read-
er must be familiar with channel device and network addressing concepts.
3) Web Browser Interface: this section is targeted to the end-user who is responsible for customizing
the NESiGate appliance for use as a NetEx/IP channel offload device, and who is responsible for
configuring and controlling operational aspects of the device.
MAN-REF-COSW 2.10-19 Introduction Page 1

Page 2Introduction MAN-REF-COSW 2.10-19

Customization
Overview
The purpose of this section is to provide an overview of the procedures used to complete the customiza-
tion of the NESiGate Offload channel-to-IP NetEx/IP gateway for use with NetEx/IP offload products.
This section is targeted to the end-user responsible for customizing a NESiGate appliance for use as a
NetEx/IP offload channel device. It is assumed the NESiGate already has the appropriate level of the
system software installed. To complete the customization, the reader must be familiar with channel de-
vice and network addressing concepts.
The customization process consists of these major steps:
1. Configure NESiGate
2. Configure NetEx/IP
3. Update DNS or local ‘hosts’ file (optional)
4. Reboot NESiGate
Device addressing
Prior to performing the Device and IP customization tasks, it would be beneficial to review NESiGate
device and network addressing concepts.
There are three important addressing elements involved in delivering NetEx/IP channel data that is not
IP-aware, and transferring it over an IP network to the correct destination:
•Device Number
•GNA Address
•IP Address
Device Number
The Device Number on the host and Device Index on the NESiGate channel board are numeric repre-
sentations of the same unique "device". On the Host operating system, a "Device Number" is mapped
as a Unit Address on a Logical Control Unit (a physical control unit may consist of from 1-16 logical
control units). The Physical Control Unit may be connected to a Port on an ESCON Director. Multiple
inbound Host channels may be connected to the ESCON Director and provide connectivity to the device
from multiple partitions (LPARs) across multiple hosts.
MAN-REF-COSW 2.10-19 Customization Page 3

Similarly, on the NESiGate ESCON board, a "Device Index" is defined as a Unit Address on a Logical
Control Unit (up to 16 may exist). The Physical Control Unit may be connected to a Port on an ESCON
Director, which may provide connectivity to multiple LPARs across multiple hosts.
Since both the Device Number and Device Index represent the same unique device (from different per-
spectives), the same addressing components must be specified exactly the same in both definitions.
Failure to do so will prevent the NESiGate devices from functioning properly.
When defining devices on the ESCON channel board, the following items are specified: Device Unit
Address, Logical Control Unit, the Director port to which the host channel is connected, and Partition-id
(LPAR). The Device Index values are not specified by the user. They are automatically generated
when the channel configuration is defined.
A maximum of 64 devices are supported on each ESCON interface.
Refer to the “Channel Define Interface” button on page 15 for a description of defining the channel de-
vices.
Conflicts and illogical configurations may be accepted as input (to the web or CLI), however that does
NOT mean they will work (i.e. overlapping subchannel addresses, incorrect CUs, etc.). The channel
configuration in the NESiGate must match the (gen'ed) configuration in the host.
GNA Address
The GNA address represents a NetEx/IP network address that is associated with a given device. It is
specified in the NetEx/IP Network Configuration Table (NCT). It is also specified during the customi-
zation of the NESiGate Channel Driver. At that time, an association is established between a particular
GNA address and a Device Index.
IP Address
The IP address represents a NetEx/IP network node address. There is no channel device awareness in-
herent in an IP address. However, during the NESiGate configuration, IP host names are defined, each
having a format based on its GNA address. This enables NESiGate to perform a direct mapping be-
tween GNA and IP addresses. This mapping is transparent to the NetEx/IP running on the host, as well
as to all NetEx/IP applications.
Page 4Customization MAN-REF-COSW 2.10-19

Using a Web Browser to Configure NESiGate
The NESiGate Web Browser Interface should be used to configure and manage NESiGate. Before con-
figuring the NG-CO specific items, the common System and Network configuration should be com-
pleted. See the “NESiGate Common Reference Manual” (NG-SW) manual for details.
Refer to the "Web Browser Interface" section on page 9for a complete description of the commands
used in this section.
Define the Channel Boards(s)
The channel board(s) are automatically configured by the NESiGate initialization software. Normally,
no re-configuration of the board configuration is required.
Define the Devices
This step is required. If this step is not performed, the ESCON devices will respond as the correct de-
vice without regard to LPAR or ESCON director port affinity. If this does not match the real configura-
tion, incorrect results will occur.
Select the Board/Channel link located on the navigation menu. This will open the page that is titled:
NESiGate CO Board/Channel.
Using the device configuration data from a completed worksheet provided in “Appendix A: Configura-
tion Worksheet” on page 19, use the "Channel Define Interface" button to define the devices. Refer to
page 17 for a description of this command.
Repeat this step as many times as necessary until all required channel interfaces are defined.
Configure NetEx/IP
There are three steps to configure NetEx/IP for NESiGate:
•create and download an NCT
•make a pamfile for this NESiGate
•modify default parameters for this NESiGate
NCT
The NCT can be created on any network-attached host and placed in a file named ‘<nesigate>.nct’
where <nesigate> is the configured hostname of the NESiGate being configured.
Refer to the “Configuration Manager and NetEx Alternate Path Retry (APR) User Guide” [MAN-
CNET-CONF-MGR] manual for a description of the NCT parameters.
MAN-REF-COSW 2.10-19 Customization Page 5

The NCT can then be uploaded to the NESiGate by using the web browser interface, on the Product
webpage under the “Send/Receive” section or via the Uploads webpage.
Typical steps for NCT modification are:
1. From the NESiGate, Downloads webpage, copy the NCT from the NESiGate to your work-
station
2. On your workstation, edit the NCT to make modifications (i.e. adding another host)
3. From the NESiGate, Uploads webpage, copy the modified NCT back to the NESiGate
4. From the NESiGate, Netex webpage, run the build PAM for this NESiGate hostname
5. Insure the GNA to IP mapping or DNS accommodates the new modifications.
6. Reboot the NESiGate
PAM
The pamfile is an internal file built from the NCT by the Configuration Manager. It contains a configu-
ration image of the NCT relative to a particular host.
To build a PAM, use the web browser interface, on the Netex webpage under the “(buildPam) for Ne-
tex Host” section and select the hostname for which you are creating the pamfile.
NETEX parameters
Netex has a set of default initialization parameters. Refer to “Appendix B: NetEx Default Parameters ”
on page 21 for a description of the parameters contained in ntx_default.
Two parameters MUST be changed in order to make Netex functional (“local” and “device1”) for your
site and one may be changed in order to improve performance on some networks (“segsize”). See
“Modify NetEx Startup Parms” on page 18 for details.
GNA to IP Mapping
NetEx/IP Offload performs dynamic mapping of GNA addresses to IP addresses. Dynamic mapping is
performed at NetEx/IP initialization time for all hosts defined in the NCT. If DNS is configured, a DNS
lookup is done for a hostname entry in the following format:
NTX0000UUSS
where UU is the network address and SS is the subaddress. (Note: the "NTX" DNS entry
names must all be upper case).
These addresses comprise the Netex toGNA address, as defined in the NetEx/IP NCT by the
NETADDR (UU) and SMGDREF (SS) parameters. If the DNS lookup is successful, an entry is dy-
namically created in the NetEx/IP mapping table that maps the toGNA and toIP addresses. Subsequent
searches of the table for any outgoing and incoming messages will find this new entry, thus avoiding
additional DNS lookups.
If a host is not defined in the NCT, or if a DNS entry does not exist for the host, you can configure the
GNA to IP mapping on the “GNA Host Mapping” webpage.
Page 6Customization MAN-REF-COSW 2.10-19

Reboot NESiGate
After the configuration changes have been made, the NESiGate unit must be rebooted to make the
changes effective:
•Vary the devices offline to the host operating system.
•Navigate to the “System Config” webpage of the NESiGate
•In the “Misc Command” drop down menu, select “REBOOT”
•Click the <Misc Commands> button
•After NESiGate is back up vary the devices online to the host operating system
MAN-REF-COSW 2.10-19 Customization Page 7

Page 8Customization MAN-REF-COSW 2.10-19

Web Browser Interface
Overview
NESiGate provides a web-enabled configuration facility. Connecting NESiGate to an intranet infrastruc-
ture enables usage of a web browser to configure and manage the NESiGate CO. Refer to the common
NESiGate Installation Manual for descriptions of all the common web pages.
Browser Considerations
The browser can be hosted on any system, as long as that system has network connectivity to the NESi-
Gate. However, the browser must be configured to refresh pages on each page reference.
Initial Screen
When the browser first connects to NESiGate, a password entry window will be displayed. Enter the
ngadmin userid you have been assigned and its password to gain access to the NesiGate. Default user-
ids and passwords are described in the common NESiGate Installation Manual.
The initial screen displayed when the password has been accepted includes a “Welcome” screen with
general information on the right.
Common Command Frame
In the top, left frame is a dropdown navigation list of the available command pages, and some common
display commands, as well as commonly used miscellaneous commands. Command page specific func-
tions are below this area. Help for each selected page can be accessed by clicking on the HELP button in
the top left frame.
Common Webpage Navigation
These navigation links will bring you to the webpage for re-configuring and displaying common infor-
mation. Refer to the “NESiGate Installation Manual” for a description of these commands.
MAN-REF-COSW 2.10-19 Web Browser Interface Page 9

NESiGate Board/Channel Commands
This webpage is used to define, display and monitor the channel interface and devices with respect to
the NESiGate CO.
Conflicts and illogical configurations may be accepted as input (to the web or CLI), however that does
NOT mean they will work (i.e. overlapping subchannel addresses, incorrect CUs, etc.). The channel
configuration in the NESiGate must match the (gen'ed) configuration in the host.
Figure 1. Channel/Board Webpage
The following are general definitions of components on this page.
IFname
name given to a channel interface for displays, other commands
board name of the channel board on which this interface is being defined.
UADD
OS-gened Unit Address.
StartGNA:
first HCM network address (UUSS). UU matches NCT netaddr & smgdref is within
SS,SS+num devices.
Number of devices
number of GNA addresses (subchannels) for this interface (4 is recommended for NG-
CA;
at least 2 per concurrent session is required for NG-CO)
NOTE: up to 64 active devices per board and 128 active devices per NESiGate are sup-
ported.
Page 10 Web Browser Interface MAN-REF-COSW 2.10-19

CU (escon only)
OS-genned Control Unit Address (must be 0 for Unisys)
CHlink (escon only)
Escon director host-side port#; or for direct connect:
1 (IBM), 2 (Unisys old SBCON), 77 (Unisys SCIOP/SIOP SBCON)
LPAR (escon only)
Logical Partition # (IBM)
MAN-REF-COSW 2.10-19 Web Browser Interface Page 11

Show Channel Config
This shows the currently defined and currently loaded ESCON subchannel ranges and their index val-
ues.
Prior to selecting this button, provide the following data on the selection screen:
IFname the name of the channel interface to display.
If IFname is not specified, all defined channel interfaces are displayed.
Show Channel Config [ x3650 - Thu Jun 3 15:49:50 ]
id type bus slot
-------- ------------------ --- ----
board1 ESCON 2 1
id board type prot sgna num in sUnt sdi bfsz opt minor
l_index dtTo wmTo mxData
-------- -------- ---- ---- -------- --- -- ---- --- ------ --- ----- ----
--- ---- ---- ------
if5e00 board1 MSG HCM 00005e00 4 0 -1 1 65535 0 1
1 30 0 65535
--- Boards Config File ---
### Auto-configured on 2010Jun03-150841 ###
#
board1 pcibus 2 pcidev 1 escon cfgd
--- Interface Config File ---
### channel config file - created: 2010 May 11 at 09:08:14
if5e00 board board1 type MSG prot HCM sgna 5E00 num 4 in 00 mxdt 65535 bfsz
65535 uadd 0 cu 1 chlink E6 lpar 1 sdevinx 1
--- Escon Config File ---
; ESCON configuration : created on 2010 May 11 at 09:08:14
; indexNN=uadd,emulation,controlunit,channellink,lpar,tag
slot=197121
index1=0,HCM,1,E6,1,nesiCLI
index2=1,HCM,1,E6,1,nesiCLI
index3=2,HCM,1,E6,1,nesiCLI
index4=3,HCM,1,E6,1,nesiCLI
Figure 2. Output from ‘Show Channel Config’
Page 12 Web Browser Interface MAN-REF-COSW 2.10-19

Show Channel Info
This displays detailed channel interface information. Prior to selecting this button, provide the following
data on the selection screen:
IFname The name of the channel interface to display. If not specified, all defined chan-
nel interfaces are displayed.
Device# Limit the display of the channel interface to a particular device. For an ESCON
channel interface running in “configured” mode, this parameter is the Device
Index. For an ESCON channel interface running in “non-configured” mode,,
this parameter is an offset from the UADD specification. If the UADD parame-
ter is not used, this parameter is an offset from the low-order byte of the start-
GNA address.
Show Info [ x3650 - Thu Jun 3 15:51:07 ]
id minor state db type prot startGna #Su sUnt sdi TxMsgs
RxMsgs
-------- ----- -------- -- ---- ---- -------- --- ---- --- -------- ------
--
if5e00 1 STARTED 0 MSG HCM 00005e00 4 -1 1 0
0
id sub unit devi initStat accWSize currWMsg
------------ --- ---- ---- -------- -------- --------
if5e00:1 0 -1 1 0 0 0
Figure 3. Output from ‘Show Channel Config’
Channel Display Stats
This displays statistics for a particular channel interface. Prior to selecting this button, provide the fol-
lowing data on the selection screen:
IFname The name of the channel interface to display. If not specified, all defined chan-
nel interfaces are displayed.
Device# Limit the display of the channel statistics to a particular device. For an ESCON
channel interface running in “configured” mode, this parameter is the Device
Index. For an ESCON channel interface running in “non-configured” mode,
this parameter is an offset from the UADD specification. If the UADD parame-
ter is not used, this parameter is an offset from the low-order byte of the start-
GNA address.
MAN-REF-COSW 2.10-19 Web Browser Interface Page 13