Hercules Version 2: TCP/IP networking with Hercules

# 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/tun0          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) and to the driving system as a virtual network interface (tun0). The Hercules 3088 driver makes the /dev/tun0 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 can be used if the driving system is Linux, Solaris, or FreeBSD. A Windows NT/2000 version of TUN/TAP has been proposed, but does not exist yet at the time of writing.

## Installing the Universal TUN/TAP Driver

If you are using Linux 2.4, you can skip this section, because the TUN/TAP driver is included as a standard feature of the kernel in Linux 2.4 and later.

Users of Linux 2.2, Solaris, or FreeBSD can install the TUN/TAP driver using the following procedure:

1. Download the file tun-1.0.tar.gz from http://vtun.sourceforge.net/tun
2. Build the driver using the following commands: `
   tar xvzf tun-1.0.tar.gz
   cd tun-1.0
   configure
   make
   su` (enter the root password when prompted)`
   make install
   chgrp xxxxx /dev/tun*` (where xxxxx is the group under which you run Hercules)`
   chmod g+w /dev/tun*
   chmod o-r /dev/tun*`
3. For Linux, edit the file /etc/conf.modules and add the following line:
   `alias char-major-90 tun`
   This causes the TUN/TAP driver to be loaded automatically when the /dev/tun device is opened by Hercules.

## 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=1` in 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`

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.

## 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 0A00 and 0A01, as in this example:

`
0A00 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0
0A01 3088 CTCI /dev/tun0 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 TUN interface

The tun0 network interface in the driving system must be configured as a point-to-point link. Because of the design of the TUN/TAP driver (the tun0 network interface does not exist until Hercules has opened the /dev/tun0 device), a special program called hercifc is provided to configure the tun0 network interface. This program is launched automatically by Hercules 3088 CTC device initialization.

The Hercules make install procedure installs the hercifc program into /usr/bin with an owner of root and setuid file permissions which allow anyone to execute the program. You may wish to alter the file permissions so that the hercifc program can only be executed by a userid in a particular group: `
su` (enter the root password when prompted)`
chgrp xxxxx /usr/bin/hercifc` (where xxxxx is the group under which you run Hercules)`
chmod o-rwx /usr/bin/hercifc
exit`

## 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=CTCA00,TYPE=CTCA,DEV=(A00,A01),MTU=1500
    DEFINE ROUTE,ID=LINUX,LINKID=CTCA00,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 A00:A01,CTCA,EML

#### TCP/IP for MVS

This is an example of the configuration statements which you need to include in the TCPIP.PROFILE dataset:

    DEVICE CTCDEV1 CTC A00
    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

The CTC devices A00 and A01 should be defined to MVS as device type 3088 in the IODF.

#### 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 A00 and A01 at startup and will assign the interface name ctc0.

Last updated 01 February 2000