----------------------------------------------------------------- Hercules Networking ----------------------------------------------------------------- *** Please read herctcp.html as Roger explains how *** *** to set up TCP/IP networking with Hercules. *** All of the communications emulation implemented within Hercules use a CTCA (Channel to Channel Adapter) type device. Depending on the "flavor", the CTCA device will provide either a point-to-point or a virtual network adapter interface to the driving system's TCP/IP stack or in the case of CTCT, a "true" CTCA connection to another instance of Hercules via a TCP/IP connection. All current emulations, with the exception of VMNET and CTCT use the Universal TUN/TAP driver on *nix and TunTap32 (WinPCap) on the Windows platforms which creates a network interface on the driving system which allow Hercules to present frames to, and receive frames from the TCP/IP stack. This network interface is configured on *nix platforms by the hercifc program which is invoked by Hercules after the TUN/TAP device is opened. The hercifc program runs as root. Please read herctcp.html for more information on the security implications of the hercifc program. Now for the gory details: *** Important informatiom about changes to the *** *** Hercules configuration files - PLEASE READ *** The format of the Hercules configuration file statements for all of the networking emulations have changed from the previous releases of Hercules. The older format will still be accepted to maintain compatability, however it is the recommendation of the maintainer that the new format be used. Also note that there is no destinction between the CTCI and CTCI-W32 modes any more, in fact CTCI-W32 does not exist in this release (other than to maintain compatability with previous configuration files). In previous releases of Hercules, all of the TCP/IP emulations required two addresses to be defined in the Hercules configuration file. One address is the read subchannel and the other for write. WITH THIS RELEASE OF HERCULES, ONLY THE FIRST ADDRESS SHOULD BE SPECIFIED IN THE CONFIGURATION FILE. Hercules will auomatically create the second address. Care must be taken to not define the second address or a configuration error will occur. The previous statement does NOT apply to VMNET or CTCT. Current emulation modes are: CTCT - CTCA Emulation via TCP connection CTCI - Point-to-point connection to the host IP stack. LCS - LAN Channel Station (3172/OSA) VMNET - Point-to-point link via SLIP/VMNET ----------------------------------------------------------------- CTCT - Channel to Channel Emulation via TCP connection ----------------------------------------------------------------- This emulation mode provides protocol-independent communication with another instance of this driver via a TCP connection. This mode appears to the operating system running in the Hercules machine as an IBM 3088 Channel to Channel Adapter and can operate in either Basic or Exteneded mode. The configuration statement for CTCT is as follows: 3088 CTCT where: is the address of the CTCT device. is the TCP/IP port on the local system. is the IP address on the remote. is the TCP/IP port on the remote system. ----------------------------------------------------------------- CTCI - Channel to Channel link to Linux TCP/IP stack ----------------------------------------------------------------- This is a point-to-point link to the driving system's TCP/IP stack. From the point of view of the operating system running in the Hercules machine it appears to be a CTC link to a machine running TCP/IP for MVS or VM. CTCI uses the Universal TUN/TAP driver on *nix and Politecnico di Torino's WinPCap packet driver(*) on Windowd. In addition, Windows requires the TunTap32 and FishPack DLLs. The configuration statement for CTCI is as follows: 3088 CTCI [options] where: is the first address of the CTCI device. Since CTCI uses paired addressing, this *must* be an even number. is the IP address of the Hercules (guest OS) side. is the IP address on the driving system. [options] can be any of the following: -n or --dev where is: [*nix] the name of the TUN/TAP special character device, normally /dev/net/tun. [Windows] is either the IP or MAC address of the driving systems network card. TunTap32 will automatically select the first network card it finds if this option is omitted, this may not be desirable for some users. -t or --mtu where is the maximum transmission unit size, normally 1500 -m or --netmask where is the netmask to be configured on the link. Note: Since this is a point-to-point link netmask is meaningless from the perspective of the actual network device. -k or --kbuff where is the size of the WinPCap kernel buffer size, normally 1024. This option is only effective on Windows platforms. -i or --ibuff where is the size of the WinPCap I/O buffer size, normally 64. This option is only effective on Windows platforms. -d or --debug this will turn on the internal debugging routines. Warning: This will produce a tremendous amount of output to the Hercules console. It is suggested that you only enable this at the request of the maintainers. ----------------------------------------------------------------- LCS - LAN Channel Station ----------------------------------------------------------------- This emulation mode appears to the operating system running in the Hercules machine as an IBM 8232 LCS device, an IBM 2216 router, a 3172 running ICP (Interconnect Communications Program), the LCS3172 driver of a P/390, or an IBM Open Systems Adapter. Rather than a point-to-point link, this emulation creates a virtual ethernet adapter through which the guest operating system running in the Hercules machine can communicate. As such, this mode is not limited to TCP/IP traffic, but in fact will handle any ethernet frame. The configuration statement for CTCI is as follows: LCS [options] [] where: is the first address of the LCS device. Since LCS uses paired addressing, this *must* be an even number. [] is an optional IP address of the Hercules (guest OS) side. Note: This is only used to establish a point-to-point routing table entry on driving system. If you use the --oat option, do not specify an address here. There are no required parameters for the LCS emulation, however there are several options that can be specified on the config statement: -n or --dev where is: [*nix] the name of the TUN/TAP special character device, normally /dev/net/tun. [Windows] is either the IP or MAC address of the driving systems network card. TunTap32 will automatically select the first network card it finds if this option is omitted, this may not be desirable for some users. -o or --oat where specifies the filename of the Address Translation file. If this option is specified, the optional and --mac entries are ignored in preference to statements in the OAT. (See below for the format of the OAT) -m or --mac where is the optional hardware address of the interface in the format: xx:xx:xx:xx:xx:xx -d or --debug this will turn on the internal debugging routines. Warning: This will produce a tremendous amount of output to the Hercules console. It is suggested that you only enable this at the request of the maintainers. If no Address Translation file is specified, the emulation module will create the following: An ethernet adapter (port 0) for TCP/IP traffic only. Two device addresses will be defined (devnum and devnum + 1). The syntax for the Address Translation file is as follows: ********************************************************* * Dev Mode Port Entry specific information * ********************************************************* 0400 IP 00 PRI 172.021.003.032 0402 IP 00 SEC 172.021.003.033 0404 IP 00 NO 172.021.003.038 0406 IP 01 NO 172.021.002.016 040E SNA 00 HWADD 00 02:00:FE:DF:00:42 HWADD 01 02:00:FE:DF:00:43 ROUTE 00 172.021.003.032 255.255.255.224 where: Dev is the base device address Mode is the operation mode - IP or SNA Port is the virtual (relative) adapter number. For IP modes, the entry specific information is as follows: PRI|SEC|NO specifies where a packet with an unkwown IP address is forwarded to. PRI is the primary default entry, SEC specifies the entry to use when the primary is not available, and NO specifies that this is not a default entry. nnn.nnn.nnn.nnn specifies the home IP address When the operation mode is IP, specify only the even (read) address. The odd (write) address will be create automatically. Note: SNA mode does not currently work. Additionally, two other statements can be included in the address translation file. The HWADD and ROUTE statements. Use the HWADD to specify a hardware (MAC) address for a virtual adapter. The first parameter after HWADD specifies with relative adapter for which the address is applied. The ROUTE statement is included for convenience. This allows the hercifc program to create a network route for this specified virtual adapter. Please note that it is not necessary to include point-to-point routes for each IP address in the table. This is done automatically by the emulation module. Up to 4 virtual (relative) adapters 00-03 are currently supported. ----------------------------------------------------------------- SLIP/VMNET - Channel to Channel link to TCP/IP via SLIP/VMNET ----------------------------------------------------------------- If the emulation mode is not specified on the configuration statement, it is assumed to be a point-to-point link to the driving system's TCP/IP stack using Willem Konynenberg's VMNET package. This provides the same function as the CTCI mode of operation, except that it uses a virtual SLIP interface instead of the TUN/TAP driver. Refer to http://www.kiyoinc.com/herc3088.html for more details. (*) The TunTap32.dll and FishPack.dll are included as part of the Windows distribution of Hercules, but the required WinPCap packet driver must be installed separately. The WinPCap packet driver can be obtained from: http://netgroup-serv.polito.it/winpcap/