TCP/IP networking with Hercules
This page describes how to set up TCP/IP connectivity between a Hercules machine and the outside world.
Since Hercules runs as a user process under the control of a driving system (usually Linux/x86 or Windows), it does not have direct access to the driving system's network adapter. This presents a problem in establishing connectivity between the network and the TCP/IP stack of an operating system running under Hercules.
But thanks to a technique originally demonstrated by Willem Konynenberg, it is possible to establish a virtual point-to-point link between the TCP/IP stack running under Hercules and the TCP/IP stack of the driving system. The driving system is then used as a router to pass IP frames between the Hercules TCP/IP stack and the rest of the network, as shown in the following diagram:
+--------------------------------+
| Linux/x86 Driving System |
| |
+-------------+ |
| Hercules | +--------+
|-------------| | eth0 |
| OS/390 | TCP/IP ------------------> Network
| TCP/IP | |10.1.2.1|
|-------------| | +--------+
| CTCA | | |
|192.168.200.1| | |
+------|------+ 192.168.200.2 |
| /dev/tun tun0 |
| | | |
| +----------------+ |
| Virtual CTC link |
| |
+--------------------------------+
The virtual CTC link is provided by the Universal TUN/TAP driver developed by Maxim Krasnyansky. This driver creates a tunnel which appears to Hercules as a character device (/dev/tun0 or /dev/net/tun) and appears to the driving system as a virtual network interface (tun0). The Hercules 3088 driver makes the tun device appear as a CTCA (Channel to Channel Adapter) to the S/390 operating system running under Hercules. Each end of the link has its own IP address which is distinct from the IP address of the driving system's real network adapter.
The Universal TUN/TAP driver is currently only available for Linux, Solaris, and FreeBSD. However, similar functionality may be obtained on Windows 98/Me/2000/XP systems (but not Windows NT) via the CTCI-W32 protocol.
Installing the TUN/TAP Driver (Linux 2.2)
The Linux 2.2 kernel does not include the TUN/TAP driver, so you need to install it using the following procedure:
- Download the file tun-1.0-1.i386.rpm from http://vtun.sourceforge.net/tun
- Install the driver using the following commands:
su
rpm -ivh tun-1.0-1.i386.rpm
chgrp xxxxx /dev/tun*
chmod g+w /dev/tun*
chmod o-r /dev/tun* - Edit the file /etc/modules.conf (it is called
/etc/conf.modules in some distributions)
and add the following line:
alias char-major-90 tun
This causes the TUN/TAP driver to be loaded automatically when a /dev/tun* device is opened by Hercules.
Installing the TUN/TAP Driver (Linux 2.4)
The TUN/TAP driver is delivered as part of the Linux 2.4 kernel, and if you are using one of the popular Linux distributions you will find that the TUN/TAP driver is already installed. If not, then you must rebuild the kernel with the configuration option CONFIG_TUN=m specified.
Note that the version of TUN/TAP in Linux 2.4 differs from the earlier version in that it allows access to all TUN interfaces (tun0, tun1, etc) through a single character device /dev/net/tun, instead of defining multiple devices /dev/tun0, /dev/tun1, etc.
The procedure for completing the TUN/TAP setup for Linux 2.4 is shown below.
- Use these commands to create the TUN device:
su
mkdir /dev/net
mknod /dev/net/tun c 10 200
chgrp xxxxx /dev/net/tun
chmod g+w /dev/net/tun
chmod o-r /dev/net/tun - Edit the file /etc/modules.conf (it is called
/etc/conf.modules in some distributions)
and add the following line:
alias char-major-10-200 tun
This causes the TUN/TAP driver to be loaded automatically when the /dev/net/tun device is opened by Hercules.
Configuring the TUN interface
The tun0 network interface in the driving system must be configured as a point-to-point link. The design of the TUN/TAP driver does not allow the interface to be statically configured like a regular network interface — the tun0 interface does not exist until Hercules opens the TUN device. For this reason, Hercules provides a special program called hercifc to configure the tun0 network interface. This program is launched automatically by Hercules 3088 CTC device initialization.
To allow the hercifc program to issue the necessary configuration
commands, you must ensure that hercifc is installed with setuid root
file permissions. When Hercules is built with the
configuration option --enable-setuid-hercifc, make install
will install hercifc in /usr/local/bin with setuid root permissions.
Note: Unrestricted access to the hercifc program could present a
potential security exposure, so you will want to ensure that hercifc
can be executed only by the group which is authorized to run Hercules.
The following commands alter the file permissions to ensure that only
users in a trusted group can execute hercifc:
(enter the root password when prompted)
su
(where xxxxx is the group under which
you run Hercules)
chgrp xxxxx /usr/local/bin/hercifc
chmod 4750 /usr/local/bin/hercifc
exit
Enabling IP forwarding
You must ensure that your kernel is enabled for IP forwarding. Popular Linux distributions usually have a configuration option to enable IP forwarding or routing:
- For RedHat, specify
net.ipv4.ip_forward=1in the /etc/sysctl.conf file. - For SuSE, specify
IP_FORWARD="yes"in the /etc/rc.config file. - If you cannot find this option in your distribution, the following
command should work on any Linux 2.x kernel:
echo "1" > /proc/sys/net/ipv4/ip_forward
Defining a route to Hercules TCP/IP
Client systems which connect to TCP/IP applications running in
the Hercules machine need to have a routing entry which defines
the driving system as the gateway into the Hercules system. An
example route definition for a Unix client system is shown below:
route add 192.168.200.1 gw 10.1.2.1
For a Windows client, go to Settings -> Control Panel -> Network ->
Configuration -> TCP/IP -> Properties -> Gateway
and add the driving system's IP address to the list of gateways.
Alternatively, enter a route command such as:
route add 192.168.200.0 mask 255.255.255.0 10.1.2.1 metric 1
If you want to avoid having to update client systems, another way is to add an appropriate routing entry to your default gateway router.
Defining the link in Hercules
You must define a pair of CTC devices in the Hercules configuration file. The devices must be defined using an adjacent pair of even/odd device numbers such as 0E20 and 0E21, as in this example:
For Linux 2.2:
0E20 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0
0E21 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0
For Linux 2.4:
0E20 3088 CTCI /dev/net/tun 1500 192.168.200.1 192.168.200.2 255.255.255.0
0E21 3088 CTCI /dev/net/tun 1500 192.168.200.1 192.168.200.2 255.255.255.0
Two IP addresses must be assigned, one for the driving system's end of the link, and one for the Hercules end of the link. For this example I have chosen 192.168.200.1 for the Hercules IP address, and 192.168.200.2 for the driving system's IP address. Since this is a point-to-point link, any addresses may be chosen, provided that the network part of the address (192.168.200 in this example) does not conflict with any existing network addresses used in your IP network.
In the above example, 1500 is the maximum transmission unit (MTU) size, and 255.255.255.0 is the netmask.
Configuring the Hercules TCP/IP stack
TCP/IP for VSE
This is an example of the configuration statements which you need to include in the IPINIT00.L member of PRD1.BASE:
SET IPADDR = 192.168.200.001 SET MASK = 255.255.255.000 DEFINE LINK,ID=CTCE20,TYPE=CTCA,DEV=(E20,E21),MTU=1500 DEFINE ROUTE,ID=LINUX,LINKID=CTCE20,IPADDR=0.0.0.0
The CTC devices should be defined to VSE using the following statements in the $IPLxxx.PROC procedure in IJSYSRS.SYSLIB:
ADD E20:E21,CTCA,EML
TCP/IP for OS/390 or VM/ESA
This is an example of the configuration statements which you need to include in the TCPIP.PROFILE.TCPIP dataset (OS/390), or in the PROFILE TCPIP file on TCPMAINT 198 (VM):
DEVICE CTCDEV1 CTC E20 LINK CTCLINK1 CTC 0 CTCDEV1 HOME 192.168.200.1 CTCLINK1 GATEWAY ; Network First Hop Link Name Size Subnet Mask Subnet Value 192.168.200.2 = CTCLINK1 1500 HOST DEFAULTNET 192.168.200.2 CTCLINK1 1500 0 START CTCDEV1
For OS/390, the CTC devices need to be defined as device type 3088 in
the IODF. Use the D U,CTC command to find out which 3088
addresses are defined in your IODF.
For VM, the CTC devices must be attached to the TCPIP virtual machine.
Because TCP/IP uses long running channel programs, the missing interrupt handler should be disabled for the CTC devices. For OS/390, add this statement in PARMLIB member IECIOS00:
MIH TIME=00:00,DEV=(E20-E21)
For VM, add this command to the PROFILE EXEC file of OPERATOR 191:
'CP SET MITIME 0E20-0E21 OFF'
Linux for S/390
This is an example of the network definitions which you need in a Linux/390 system running under Hercules:
ifconfig ctc0 192.168.200.1 pointopoint 192.168.200.2 mtu 1500 route add defaultroute gw 192.168.200.2
Linux/390 will autodetect the CTC devices E20 and E21 at startup and will assign the interface name ctc0.
What to do if TUN/TAP doesn't work
Check the following (thanks to Richard Higson for this checklist):
- Enter the command
ls -l /dev/tun0 /dev/net/tun.
For Linux 2.4, the response should be:
ls: /dev/tun0: No such file or directory
crw-rw---- 1 root xxxxx 10, 200 Sep 13 07:06 /dev/net/tun
For Linux 2.2, the response should be:
crw-rw---- 1 root xxxxx 90, 0 Feb 3 2001 /dev/tun0
ls: /dev/net/tun: No such file or directory
(xxxxx should be the group under which you run Hercules). ls -l /usr/local/bin/hercifcshould show
-rwsr-x--- 1 root xxxxx 17333 Dec 31 20:55 /usr/local/bin/hercifc
(xxxxx should be the group under which you run Hercules).- When hercules comes up, and before IPLing your favorite OS, verify
that you have your underlying network stuff up and ready to roar:
[root]# ifconfig eth0 Link encap:Ethernet HWaddr 00:12:34:56:78:9A inet addr:10.1.2.1 Bcast:10.255.255.255 Mask:255.0.0.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 tun0 Link encap:Point-to-Point Protocol inet addr:192.168.200.2 P-t-P:192.168.200.1 Mask:255.255.255.0 UP POINTOPOINT RUNNING NOARP MULTICAST MTU:1500 Metric:1 [root]# netstat -in Kernel Interface table Iface MTU Met RX-OK RX-ERR RX-DRP RX-OVR TX-OK TX-ERR TX-DRP TX-OVR Flg eth0 1500 0 201 0 0 0 196 0 0 0 BMRU tun0 1500 0 0 0 0 0 0 0 0 0 MOPRU [root]# netstat -rn Kernel IP routing table Destination Gateway Genmask Flags MSS Window irtt Iface 10.0.0.0 0.0.0.0 255.0.0.0 U 40 0 0 eth0 192.168.200.0 0.0.0.0 255.255.255.0 U 40 0 0 tun0 127.0.0.0 0.0.0.0 255.0.0.0 U 40 0 0 lo 0.0.0.0 10.1.0.1 0.0.0.0 UG 40 0 0 eth0 `cat /proc/sys/net/ipv4/ip_forward`should show "1". If it doesn't, your L386 won't forward (==route) packets at all.- Is the TUN/TAP driver loaded?
- TUN/TAP compiled into the kernel (
`make menuconfig`) look for"CONFIG_TUN=m"in /usr/src/linux `lsmod`after starting hercules should showtun 3456 2 (autoclean)
- TUN/TAP compiled into the kernel (
- Look for
Dec 14 16:47:19 wie kernel: Universal TUN/TAP device driver 1.3 (C)1999-2000
Maxim Krasnyansky
in syslog after starting hercules
Last updated 15 January 2002 by Roger Bowler