1----------------------------------------------------------------- 2 Hercules Networking 3----------------------------------------------------------------- 4 5 *** Please read herctcp.html as Roger explains how *** 6 *** to set up TCP/IP networking with Hercules. *** 7 8All of the communications emulation implemented within Hercules 9use a CTCA (Channel to Channel Adapter) type device. Depending on 10the "flavor", the CTCA device will provide either a 11point-to-point or a virtual network adapter interface to the 12driving system's TCP/IP stack or in the case of CTCT, a "true" 13CTCA connection to another instance of Hercules via a TCP/IP 14connection. 15 16All current emulations, with the exception of VMNET, CTCT and CTCE use 17the Universal TUN/TAP driver on *nix and TunTap32 (WinPCap) on 18the Windows platforms which creates a network interface on the 19driving system which allow Hercules to present frames to, and 20receive frames from the TCP/IP stack. This network interface is 21configured on *nix platforms by the hercifc program which is 22invoked by Hercules after the TUN/TAP device is opened. The 23hercifc program runs as root. Please read herctcp.html for more 24information on the security implications of the hercifc program. 25 26Now for the gory details: 27 28--------------------------------------------------------------- 29 30 *** Important information about changes to the *** 31 *** Hercules configuration files - PLEASE READ *** 32 33The format of the Hercules configuration file statements for all 34of the networking emulations have changed from the previous 35releases of Hercules. The older format will still be accepted 36to maintain compatibility, however it is the recommendation 37of the maintainer that the new format be used. Also note that 38there is no distinction between the CTCI and CTCI-W32 modes any 39more, in fact CTCI-W32 does not exist in this release (other 40than to maintain compatibility with previous configuration files). 41 42--------------------------------------------------------------- 43 44 *** Important information about changes to the *** 45 *** Hercules configuration files - PLEASE READ *** 46 47In releases prior to Hercules version 3.00, all of the TCP/IP 48emulations required two addresses to be defined in the Hercules 49configuration file: one address for the read subchannel and the 50other for write. 51 52--------------------------------------------------------------- 53 54 *** Important information about changes to the *** 55 *** Hercules configuration files - PLEASE READ *** 56 57Hercules release version 3.00, however, [temporarily] changed 58the rules: With [ONLY!] version 3.00 of Hercules, only the FIRST 59address address need be specified in the configuration file. 60Hercules version 3.00 automatically creates the second address. 61Care must be taken to NOT define the second address [with Hercules 62version 3.00 ONLY!] or a configuration error will occur. 63 64--------------------------------------------------------------- 65 66 *** Important information about changes to the *** 67 *** Hercules configuration files - PLEASE READ *** 68 69Starting with Hercules version 3.01 however, we've gone back to 70doing things the way we ORIGINALLY were (and the way most users 71are used to (i.e. the way most users EXPECT things to work)): 72 73With Hercules version 3.01 you need to define BOTH addresses! 74 75Both the even numbered read device AS WELL AS the odd numbered 76write device must BOTH be defined in your Hercules configuration 77file starting with Hercules version 3.01. We apologize for the 78mess, but we thought having Herc automatically define the write 79device for you (as it does in version 3.00) would be easier for 80everyone. Turns out it caused a lot of problems with a lot of 81people, so we decided to go back to the original way. Again, we 82apologize for whatever headaches this may have caused anyone. 83 84--------------------------------------------------------------- 85 86 *** Important information about changes to the *** 87 *** Hercules configuration files - PLEASE READ *** 88 89Note that the VMNET and CTCT protocols have ALWAYS required BOTH 90addresses to be defined (i.e. ALL versions of Hercules, including 91version 3.00 as well, require BOTH even/odd read/write devices to 92be defined separately [in your Hercules configuration file]). 93 94--------------------------------------------------------------- 95 96The currently supported emulation modes are: 97 98 CTCT - CTCA Emulation via TCP connection 99 CTCE - Enhanced CTCA Emulation via CTP connection 100 CTCI - Point-to-point connection to the host IP stack. 101 LCS - LAN Channel Station (3172/OSA) 102 VMNET - Point-to-point link via SLIP/VMNET 103 104----------------------------------------------------------------- 105CTCT - Channel to Channel Emulation via TCP connection 106----------------------------------------------------------------- 107 108This emulation mode provides protocol-independent communication 109with another instance of this driver via a TCP connection. 110 111This mode appears to the operating system running in the Hercules 112machine as an IBM 3088 Channel to Channel Adapter and can operate 113in either Basic or Extended mode. 114 115The configuration statement for CTCT is as follows: 116 117 <devnum> 3088 CTCT <lport> <raddress> <rport> <mtu> 118 119where: 120 121 <devnum> is the address of the CTCT device. 122 123 <lport> is the TCP/IP port on the local system. 124 125 <raddress> is the IP address on the remote. 126 127 <rport> is the TCP/IP port on the remote system. 128 129----------------------------------------------------------------- 130CTCI - Channel to Channel link to Linux TCP/IP stack 131----------------------------------------------------------------- 132 133This is a point-to-point link to the driving system's TCP/IP 134stack. From the point of view of the operating system running 135in the Hercules machine it appears to be a CTC link to a machine 136running TCP/IP for MVS or VM. 137 138CTCI uses the Universal TUN/TAP driver on *nix and Politecnico 139di Torino's WinPCap packet driver as well as Fish's TunTap32 140and FishPack DLLs on Windows[1]. 141 142The configuration statement for CTCI is as follows: 143 144 <devnum1-devnum2> CTCI [options] <guestip> <hostip> 145 146where: 147 148 <devnum1-devnum2> is the address pair of the CTCI device. 149 150 <guestip> is the IP address of the Hercules (guest OS) side. 151 152 <hostip> is the IP address on the driving system. 153 154 [options] can be any of the following: 155 156 -n <devname> or --dev <devname> 157 158 where <devname> is: 159 160 [*nix] the name of the TUN/TAP special character 161 device, normally /dev/net/tun. 162 163 [Windows] is either the IP or MAC address of the 164 driving systems network card. TunTap32 will 165 automatically select the first network card it 166 finds if this option is omitted, this may not be 167 desirable for some users. 168 169 -t <mtu> or --mtu <mtu> 170 171 [*nix only] where <mtu> is the maximum transmission 172 unit size, normally 1500 173 174 -s <netmask> or --netmask <netmask> 175 176 [*nix only] where <netmask> is the netmask to 177 be configured on the link. Note: Since this is a 178 point-to-point link netmask is meaningless from 179 the perspective of the actual network device. 180 181 -m <MAC Address> or --mac <MAC address> 182 183 [Windows only] where <MAC Address> is the optional 184 hardware address of the interface in the format of 185 either xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx. 186 187 -k <kbuff> or --kbuff <kbuff> 188 189 [Windows only] where <kbuff> is the size of the 190 WinPCap kernel buffer size, normally 1024. 191 192 -i <ibuff> or --ibuff <ibuff> 193 194 [Windows only] where <ibuff> is the size of the 195 WinPCap I/O buffer size, normally 64. 196 197 -d or --debug 198 199 this will turn on the internal debugging routines. 200 Warning: This will produce a tremendous amount of 201 output to the Hercules console. It is suggested that 202 you only enable this at the request of the maintainers. 203 204----------------------------------------------------------------- 205LCS - LAN Channel Station 206----------------------------------------------------------------- 207 208This emulation mode appears to the operating system running in 209the Hercules machine as an IBM 8232 LCS device, an IBM 2216 210router, a 3172 running ICP (Interconnect Communications Program), 211the LCS3172 driver of a P/390, or an IBM Open Systems Adapter. 212 213Rather than a point-to-point link, this emulation creates a 214virtual ethernet adapter through which the guest operating system 215running in the Hercules machine can communicate. As such, this 216mode is not limited to TCP/IP traffic, but in fact will handle 217any ethernet frame. 218 219The configuration statement for LCS is as follows: 220 221 <devnum1-devnum2> LCS [options] [<guestip>] 222 223where: 224 225 <devnum1-devnum2> is the address pair of the LCS device. 226 This pair must be an even-odd address. 227 228 [<guestip>] is an optional IP address of the Hercules 229 (guest OS) side. Note: This is only used to 230 establish a point-to-point routing table entry 231 on driving system. If you use the --oat option, 232 do not specify an address here. 233 234There are no required parameters for the LCS emulation, however 235there are several options that can be specified on the config 236statement: 237 238 -n <devname> or --dev <devname> 239 240 where <devname> is: 241 242 [*nix] the name of the TUN/TAP special character device, 243 normally /dev/net/tun. 244 245 [Windows] is either the IP or MAC address of the driving 246 systems network card. TunTap32 will automatically select 247 the first network card it finds if this option is 248 omitted, this may not be desirable for some users. 249 250 -o <filename> or --oat <filename> 251 252 where <filename> specifies the filename of the Address 253 Translation file. If this option is specified, the optional 254 <guestip> and --mac entries are ignored in preference to 255 statements in the OAT. (See below for the format of the OAT) 256 257 -m <MAC Address> or --mac <MAC address> 258 259 where <MAC Address> is the optional hardware address of 260 the interface in the format: xx:xx:xx:xx:xx:xx 261 262 -d or --debug 263 264 this will turn on the internal debugging routines. 265 Warning: This will produce a tremendous amount of 266 output to the Hercules console. It is suggested that 267 you only enable this at the request of the maintainers. 268 269 270If no Address Translation file is specified, the emulation module 271will create the following: 272 273 An ethernet adapter (port 0) for TCP/IP traffic only. 274 Two device addresses will be defined (devnum and devnum + 1). 275 276 277The syntax for the Address Translation file is as follows: 278 279********************************************************* 280* Dev Mode Port Entry specific information * 281********************************************************* 282 0400 IP 00 PRI 172.021.003.032 283 0402 IP 00 SEC 172.021.003.033 284 0404 IP 00 NO 172.021.003.038 285 0406 IP 01 NO 172.021.002.016 286 040E SNA 00 287 288 HWADD 00 02:00:FE:DF:00:42 289 HWADD 01 02:00:FE:DF:00:43 290 ROUTE 00 172.021.003.032 255.255.255.224 291 292where: 293 294 Dev is the base device address 295 Mode is the operation mode - IP or SNA 296 Port is the virtual (relative) adapter number. 297 298When the device is specifies the odd address of the pair, 299then the read/write functions of the pair will be swapped. 300 301For IP modes, the entry specific information is as follows: 302 303 PRI|SEC|NO specifies where a packet with an unknown IP 304 address is forwarded to. PRI is the primary 305 default entry, SEC specifies the entry to use 306 when the primary is not available, and NO 307 specifies that this is not a default entry. 308 309 nnn.nnn.nnn.nnn specifies the home IP address 310 311When the operation mode is IP, specify only the even (read) 312address. The odd (write) address will be create automatically. 313 314Note: SNA mode does not currently work. 315 316Additionally, two other statements can be included in the 317address translation file. The HWADD and ROUTE statements. 318 319Use the HWADD to specify a hardware (MAC) address for a 320virtual adapter. The first parameter after HWADD specifies 321with relative adapter for which the address is applied. 322 323The ROUTE statement is included for convenience. This allows the 324hercifc program to create a network route for this specified 325virtual adapter. Please note that it is not necessary to include 326point-to-point routes for each IP address in the table. This is 327done automatically by the emulation module. 328 329Up to 4 virtual (relative) adapters 00-03 are currently supported. 330 331----------------------------------------------------------------- 332SLIP/VMNET - Channel to Channel link to TCP/IP via SLIP/VMNET 333----------------------------------------------------------------- 334 335If the emulation mode is not specified on the configuration 336statement, it is assumed to be a point-to-point link to the 337driving system's TCP/IP stack using Willem Konynenberg's VMNET 338package. This provides the same function as the CTCI mode of 339operation, except that it uses a virtual SLIP interface instead 340of the TUN/TAP driver. 341 342Refer to http://www.kiyoinc.com/herc3088.html for more details. 343 344----------------------------------------------------------------- 345CTCE - Enhanced Channel to Channel Emulation via TCP connection 346----------------------------------------------------------------- 347 348The CTCE device type will emulate a real 3088 Channel to Channnel 349Adapter also for non-IP traffic, enhancing the CTCT capabilities. 350CTCE connections are also based on TCP/IP between two (or more) 351Hercules instances, and requires an even-odd pair of port numbers 352per device side. Only the even port numbers are to be configured; 353the odd numbers are just derived by adding 1 to the (configured) 354even port numbers. The socket connection pairs cross-connect, 355the arrows showing the send->receive direction : 356 357 x-lport-even -> y-rport-odd 358 x-lport-odd <- y-rport-even 359 360The configuration statement for CTCE is as follows : 361 362 <devnum> CTCE <lport> <raddress> <rport> [[<mtu>] <sml>] 363 364where: 365 366 <devnum> is the address of the CTCT device. 367 368 <lport> is the even TCP/IP port on the local system. 369 370 <raddress> is the IP address on the remote. 371 372 <rport> is the even TCP/IP port on the remote system. 373 374 <mtu> optional mtu buffersize, defaults to 32778 375 376 <sml> optional small minimum for mtu, defaults to 8 377 378A sample CTCE device configuration is shown below: 379 380 Hercules PC Host A with IP address 192.168.1.100 : 381 382 0E40 CTCE 30880 192.168.1.200 30880 383 0E41 CTCE 30882 192.168.1.200 30882 384 385 Hercules PC Host B with IP address 192.168.1.200 : 386 387 0E40 CTCE 30880 192.168.1.100 30880 388 0E41 CTCE 30882 192.168.1.100 30882 389 390CTCE connected Hercules instances can be hosted on either Unix 391or Windows platforms, both sides do not need to be the same. 392 393 394 395================================================================= 396[1] The TunTap32.dll and FishPack.dll are part of Fish's CTCI-W32 397http://www.softdevlabs.com/Hercules/ctci-w32-index.html 398package, but the required WinPCap packet driver must be installed 399separately from http://www.winpcap.org See Fish's web page for 400details. 401 402ALSO NOTE that it is HIGHLY RECOMMENDED that you stick with using 403only the current RELEASE version of WinPCap and NOT any type of 404'alpha' OR 'beta' version! Alpha and Beta versions of WinPCap are 405NOT SUPPORTED! Only official *release* version are supported! 406 407When you visit the WinPCap download web page, you need need to 408scroll down the page a bit to reach the OFFICIAL RELEASE VERSION 409of WinPcap. They usually put their Beta versions at the top of the 410page, and BETA versions ARE NOT SUPPORTED. *Please* scroll down 411the page and use and official RELEASE version. Thanks. 412 413You may, if you want, use a beta version of WinPCap, but if you do, 414then you're on your own if you have any problems with it. 415 416 -- Fish, May 2004. 417