mirror of
https://github.com/SDL-Hercules-390/hyperion.git
synced 2026-04-14 07:55:24 +02:00
299 lines
11 KiB
Plaintext
299 lines
11 KiB
Plaintext
-----------------------------------------------------------------
|
|
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:
|
|
|
|
<devnum> 3088 CTCT <lport> <raddress> <rport> <mtu>
|
|
|
|
where:
|
|
|
|
<devnum> is the address of the CTCT device.
|
|
|
|
<lport> is the TCP/IP port on the local system.
|
|
|
|
<raddress> is the IP address on the remote.
|
|
|
|
<rport> 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:
|
|
|
|
<devnum> 3088 CTCI [options] <guestip> <hostip>
|
|
|
|
where:
|
|
|
|
<devnum> is the first address of the CTCI device.
|
|
Since CTCI uses paired addressing, this *must* be
|
|
an even number.
|
|
|
|
<guestip> is the IP address of the Hercules (guest OS) side.
|
|
|
|
<hostip> is the IP address on the driving system.
|
|
|
|
[options] can be any of the following:
|
|
|
|
-n <devname> or --dev <devname>
|
|
|
|
where <devname> 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 <mtu> or --mtu <mtu>
|
|
|
|
where <mtu> is the maximum transmission unit size,
|
|
normally 1500
|
|
|
|
-m <netmask> or --netmask <netmask>
|
|
|
|
where <netmask> 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 <kbuff> or --kbuff <kbuff>
|
|
|
|
where <kbuff> is the size of the WinPCap kernel
|
|
buffer size, normally 1024. This option is only
|
|
effective on Windows platforms.
|
|
|
|
-i <ibuff> or --ibuff <ibuff>
|
|
|
|
where <ibuff> 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:
|
|
|
|
<devnum> LCS [options] [<guestip>]
|
|
|
|
where:
|
|
|
|
<devnum> is the first address of the LCS device.
|
|
Since LCS uses paired addressing, this *must* be
|
|
an even number.
|
|
|
|
[<guestip>] 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 <devname> or --dev <devname>
|
|
|
|
where <devname> 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 <filename> or --oat <filename>
|
|
|
|
where <filename> specifies the filename of the Address
|
|
Translation file. If this option is specified, the optional
|
|
<guestip> and --mac entries are ignored in preference to
|
|
statements in the OAT. (See below for the format of the OAT)
|
|
|
|
-m <MAC Address> or --mac <MAC address>
|
|
|
|
where <MAC Address> 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/
|
|
|