Hercules 4.0 (Hyperion)
This is official web page for Hercules version 4.0, working titled 'Hyperion', the development version of Hercules. Hyperion is developed and supported by a small group of volunteers.
Hercules Version 4: 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. I put all Z-VM 5.3 Evaluation file in a directory; then IPL Z-VM ZVM.INS started VM. The IPL sometimes (most of times) doesn't work and Hercules ends; so I made a DDR of RAM DASD to a 3370 and now I can use it on a 32 bit system with 512 MB of Hercules Mainsize.
Hercules is an open source software implementation of the mainframe System/370 and ESA/390 architectures, in addition to the latest 64-bit z/Architecture. Hercules runs under Linux, Windows, Solaris, FreeBSD, and macOS. Hercules is licensed under the terms of the Q Public Licence. The Q Public License is certified as an open source license by the Open Software Initiative.
Using Hercules to Emulate a Mainframe
To emulate a mainframe using Hercules, you will need a few things:
- A suitable host computer.
- Hercules Installation and Setup Instructions
- Mainframe software, most often an operating system.
- Documentation for the software you plan to use.
Prior experience programming or supporting a mainframe operating operating system is not required but is very helpful.
Host Computer Capability
Hercules will run just fine on most modern desktop or laptop computers. Performance will depend on what you do with Hercules. Emulating a mainframe running DOS/360, one of IBM's oldest mainframe operating systems and one that would run in 16KiB of mainframe core memory, will require far fewer host system resources than, say, a more modern MVS 3.8j configured with 16MiB of emulated core and running a number of batch jobs. One of the mainframe ports of Linux will require still more resources.
On x86-based systems, Hercules will work on 32-bit and 64-bit systems. Hercules does not require hardware-based virtualization capabilities and runs fine on operating systems that are themselves running in a virtual environment such as Oracle Virtualbox.
Muliple cores on the host system are helpful when emulating a mainframe configured with multiple CPUs, but multiple cores are not a requirement.
Suitable Host platforms
- Windows: Windows XP x64 or Windows Server 2003 R2 or greater. Windows Vista or newer 32-bit or 64-bit will work.
- UNIX-like systems: Linux-based systems and FreeBSD. Solaris is supported when you build Hercules from source using CMake.
- macOS: Limited testing; feedback encouraged.
The above list is limited by the systems available to developers; we cannot afford to have one of everything. That said, we welcome feedback and issues from people who try to install on other platforms. One Hercules developer has installed on an emulated Raspberry Pi using QEMU.
Hercules Installation and Setup Instructions
Select the installation procedure appropriate for your system.
- Building Hercules for Windows Systems (Recommended). Uses CMake to build from source.
- Building Hercules for UNIX-like Systems (Recommended). Uses CMake to build from source.
- Hercules Installation for macOS Systems (Recommended). Uses CMake to build from source.
- Installation Using Legacy Tools. Uses makefile.bat/NMake (Windows) or GNU Autotools (UNIX-like systems and macOS) to build from source. Includes Windows binaries installation instructions. Useful if you encounter problems using CMake to build from source.
Most of the mainframe system web sites below include configuration instructions, sample configuration files, and in some cases, pre-built emulated DASD files. Some do not. The following links can be used to complete the setup of a Hercules emulated mainframe system.
- Configuration File. Create a configuration file that defines the system configuration including I/O devices.
- Creating DASD. Create emulated DASD volumes for attachment to an emulated mainframe.
- Compressed DASD Emulation. Create emulated DASD volumes using compression to reduce host computer disk space needs.
- Telnet/tn3270 Console How-To. Connect to an emulated mainframe 3270 device, 3270 operator console, and/or 1052 or 3215 printer-keyboard.
- Operating Procedures. Hercules command line parameters, panel commands, keyboard use, and the Hercules Automatic Operator (HAO).
Mainframe Software
You have a number of choices, and you are not limited to the packages listed here. IBM DOS/VS and IBM DOS/360 pre-date and bear absolutely no resemblance to PC-DOS or MS-DOS.
Note that if you run mainframe software within Hercules, you must respect the terms and conditions of the software license for that software.
- IBM MVS. Jay Moseley has a very complete tutorial for installing and running MVS 3.8j, IBM's last release of MVS.
- Turnkey MVS systems. There are at least two. Each includes its own copy of Hercules. If a Turnkey system suits you, with its pre-installed mainframe operating system, there is no need to install Hercules from this site.
- Volker Bandke's MVS Tur(n)key System
- Jürgen Winkelmann's TK4-
- IBM OS/360 MVT, a non-virtual storage operating system. Jay Maynard has a good installation procedure at Introduction to Generating and Running OS/360 on Hercules
- IBM DOS/VS. See Yahoo user ceo1944's 2314DOS.zip. This link downloads a zip archive of JCL and instructions from the Yahoo group H390-DOS/VS; free registration required.
- IBM DOS/360. There are at least four installation procedures available. The first three are in the H390-DOS/VS Yahoo group (free registration required) and the fourth is a stand-alone web site.
- Bill Carlborg's DOS360-2314.zip (downloads a .zip archive).
- Ben Huntsman's DYI-DOS360.zip (downloads a .zip archive).
- Kevin Leonard's DOS-360 26.2
- https://sites.google.com/site/dos360install/. This site is loosely modeled on Jay Moseley's MVS 3.8j site noted above.
- IBM VM/370. See the VM/370 R6, page on the cbttape.org site. Turnkey versions of VM/370 are available on David Wade's G4UGM's Vintage and Classic Computer pages
- Linux. Mainframe versions exist for the following. Some of these are not open source, and installation generally requires configuration of a mainframe Channel-to-Channel adapter to enable network connectivity for installation and/or post-install security updates.
- Debian Download a s390x CD or DVD.
- Fedora. Scroll down the page until you reach 's390x Architecture' at the bottom of the page.
- Gentoo. The s390x is included under '(experimental)' for 'Experimental architectures'. You know what that means.
- Red Hat. Paid license or 30-day trial only. Red Hat supports Fedora as its open source alternative.
- SUSE Enterprise Server. Paid license or 60-day trial only.
- Michigan Terminal System (MTS). The Michigan Terminal System Archive includes a turnkey distribution that has been tailored for use with Hercules. Additional helpful information may be found at https://try-mts.com/why-try-mts/
- SATK. Harold Grovesteen's Stand Alone Tool Kit offers a collection of tools for creating mainframe assembly language programs on your computer for later execution within Hercules. The binary floating point test programs and scripts were created using SATK and serve as examples for the assembler's capabilities and use.
- TXXOS. Tommy Sprinkle's 'Bare Metal Programming for the IBM 370 Mainframe' web site walks you step-by-step from IPL'ing a simple listing program through building a disk-resident operating system.
See Frequently Asked Questions, starting with question 2.01 Can it run z/OS, z/VM, z/VSE? for more details on available operating systems and licensing matters.
Mainframe Software Documentation
Documentation for the Linux distributions, the Michigan Terminal System, SATK, and TXXOS may be found on their respective web sites.
Documentation for the IBM operating systems is a different matter; much of it was published before the Internet existed. The Bitsavers site and its mirrors contain a repository of scanned, and in some cases, OCR'd, IBM hardware and software reference manuals. The DOS360Install site has a couple of essential DOS/360 manuals that are not on Bitsavers.
Bitsavers is organized first by manufacturer, then by machine. Within machine one can find operating system documentation. Use the following shortcuts to the Bitsavers site. And explore..one can find very useful information in unexpected places on Bitsavers.
- System/360 hardware & software manuals
- System/370 hardware & software manuals
- MVS software manuals. Also see OS/VS2 software manuals. OS/VS2 was IBM's original name for MVS.
Hercules Documentation and Useful Links
The Web/HTML documentation is in a 'how-to' style with examples. The downloadable PDFs are comprehensive reference documentation.
| Web/HTML | Downloadable PDFs |
|---|
Additional helpful links
About Hercules
Hercules was created by Roger Bowler.Jay Maynard ('the Tron Guy') was the maintainer from 2000 to 2012.Jan Jaeger designed and implemented many of the advanced features ofHercules, including dynamic reconfiguration, integrated console,interpretive execution and z/Architecture support. A dedicated crew ofprogrammers is constantly at work implementing new features and fixing bugs.
What people are saying about Hercules
'Never in my wildest dreams did I expect to see MVSrunning on a machine that I personally own.Hercules is a marvelous tool. My thanks to you all for a jobvery well done.'
—Reed H. Petty
'I do miss my mainframe a lot, and playing with Herc sure brings backmemories. Just seeing the IBM message prefixes, and responding toconsole messages again was a wonderful bit of nostalgia!'
—Bob Brown
'I have installed your absolutely fantastic /390 emulator.You won't believe what I felt when I saw the prompt.Congratulations, this is a terrific software.I really have not had such a fascinating and interestingtime on my PC lately.'
—IBM Large Systems Specialist
'Such simulators have been available for a long time. One of the mostcomplete (up to modern 64-bit z/Architecture) is hercules.'
—Michel Hack, IBM Thomas J. Watson Research Center
'An apparently excellent emulator that allows those open sourcedevelopers with an 'itch to scratch', to come to the S/390 tableand contribute.'
—Mike MacIsaac, IBM
'BTW grab a copy of Hercules and you can test it at home.It's a very good S/390 and zSeries (S/390 64bit) emulator.'
—Alan Cox
'It works even better than I imagined.Hercules is a fine piece of software!'
—Dave Sienkiewicz
'Hercules is a systems programmer's dream come true.'
—René Vincent Jansen
'Aside from the electric trains my parents gotme in 1953, this is the best toy I've ever been given,bar none.'
—Jeffrey Broido
'Congratulations to you and your team on a fine piece of work!'
—Rich Smrcina
'Congratulations on a magnificent achievement!'
—Mike Ross
'For anyone thinking running Hercules is too much trouble or too hardor whatever, I came home from work one day and my 13 year old 8thgrade son had MVS running under VM under Hercules on Linux. He hadgotten all the information about how to do this from the Internet.When he complained about MVS console configuration and figuring outhow to get it to work with VM, I knew he had felt all the pain heever needed to feel about mainframes.'
—Scott Ledbetter, StorageTek
'I am running a fully graphical Centos z/Linux environment on my desktop.The Hercules emulator is an amazing feat of engineering.I just wanted to send my compliments to the team for an excellent job!Thanks much for making this product part of the open-source community!'
—Roby Gamboa
'I have DOS and DOS/VS running on Hercules withsome demo applications, both batch and on-line. It does bring backsome good memories. My compliments go to the Hercules team. Thank you.'
—Bill Carlborg
'This is stunning piece of work. To say that I am blown away is anunderstatement. I have a mainframe on my notebook!!!!!!P.S. Now if I can just remember my JCL'
—Roger Tunnicliffe
Read Hesh Wiener's Technology News article about Hercules athttp://www.tech-news.com/another/ap200601b.html
Read Moshe Bar's BYTE.com article about Hercules athttp://web.archive.org/web/20010712143133/http://www.byte.com/documents/s=429/BYT20000801S0002/
For eighteen months, the IBM RedbookSG24-4987 Linux for S/390 athttp://www.redbooks.ibm.com/abstracts/sg244987.htmlcontained a chapter written by Richard Higsondescribing how to run Linux/390 under Hercules.Then suddenly, all mention of Hercules was mysteriouslyremoved from the online edition of the book!Read the story of the disappearing Redbook chapter athttp://www2.marist.edu/htbin/wlvtype?LINUX-VM.25658
View the foils from Jay Maynard's presentation given atSHARE Session 2880in San Francisco on 20 August 2002as a PDF file (815K) fromhttp://linuxvm.org/Present/SHARE99/S2880JMa.pdf
If you have any questions or comments please consider joining the hercules-390 discussion group athttp://groups.yahoo.com/group/hercules-390.
Bug reports for either release (together with your diagnosis of the fault, please)may be reported to either thehercules-390 discussion groupor entered into the appropriate Github issue tracker:
- Issues with the spinhawk version of Hercules
Other Hercules-related sites
- http://www.softdevlabs.com
Windows GUI for Hercules 4.0 Hyperion and other Hercules related software. - http://www.bsp-gmbh.com/hercules/index.shtml
Volker Bandke's ready-to-run MVS 3.8J turnkey system and all things MVS. - http://cbttape.org/~jmorrison/
Jim Morrison's downloads (includes 3380 support for MVS 3.8!) - http://www.jaymoseley.com/hercules
Jay Moseley's Hercules site - lots of Hercules and MVS information - http://www.tommysprinkle.com/mvs
Tommy Sprinkle's MVS 3.8 documentation - http://hansen-family.com/mvs
Bob Hansen's MVS 3.8 documentation - http://www.clueful.co.uk/mbeattie/hercules/tso.html
Malcolm Beattie's MVT/TSO documentation - http://www.ibiblio.org/jmaynard
Jay Maynard's S/360 and S/370 public domain software archive - http://www.shedlock.org/Shedlock/Hercules/index.html
George Shedlock's archive of DOS/VS Release 34 and VM/370 software, books, and information - http://www.smrcc.org.uk/members/g4ugm/VM370.htm
Dave Wade's VM/370 archive - http://perso.wanadoo.es/rptv2005/en/index.html
Rafael Pereira's Standalone Programs and 1401 simulator project - http://timpinkawa.net/hercules/
Tim Pinkawa's Hercules Page - http://www.lightlink.com/mhp/2703/
Max Parke's Hercules 2703 Page - TTY, TCAM, 3705 and more - https://github.com/s390guy/SATK
Harold Grovesteen's Stand-Alone Tool Kit (SATK)
IBM, System/370, ESA/390, and z/Architecture are trademarks orregistered trademarks of IBM Corporation.Other product names mentioned here are trademarks of other companies.
This page describes how to set up TCP/IP connectivity betweena Hercules machine and the outside world.
Since Hercules runs as a user process under the control of a drivingsystem (usually Linux/x86 or Windows), it does not have directaccess to the driving system's network adapter. This presents aproblem in establishing connectivity between the network and theTCP/IP stack of an operating system running under Hercules.
But thanks to a technique originally demonstrated byWillem Konynenberg, it is possible to establish a virtualpoint-to-point link between the TCP/IP stack running underHercules and the TCP/IP stack of the driving system. Thedriving system is then used as a router to pass IP framesbetween the Hercules TCP/IP stack and the rest of the network,as shown in the below diagram.
The virtual CTC link is provided by the Universal TUN/TAP driverdeveloped by Maxim Krasnyansky. This driver creates a tunnelwhich appears to Hercules as a character device (/dev/tun0 or/dev/net/tun) and appears to the driving system as a virtualnetwork interface (tun0).The Hercules 3088 driver makes the tun device appear asa CTCA (Channel to Channel Adapter) to the S/390 operating systemrunning under Hercules. Each end of the link has its own IPaddress which is distinct from the IP address of the drivingsystem's real network adapter.
Windows users should refer to Fish's CTCI-WIN web page which provides similar 'TunTap' functionality on Windows platforms.
Installing the TUN/TAP Driver (Linux 2.4)
The TUN/TAP driver is delivered as part of the Linux 2.4 kernel, andif you are using one of the popular Linux distributions you will findthat the TUN/TAP driver is already installed. If not, then you mustrebuild the kernel with the configuration option CONFIG_TUN=m specified.
Note that the version of TUN/TAP in Linux 2.4 differs from the earlierversion in that it allows access to all TUN interfaces (tun0, tun1, etc)through a single character device /dev/net/tun, instead of definingmultiple 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+rw /dev/net/tun
chmod o-rw /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.
Installing the TUN/TAP Driver (Linux 2.6, FreeBSD, OS X)
For distributions based on the Linux 2.6 kernel you will probably find that theTUN/TAP driver is already installed and the /dev/net/tun device is alreadydefined. If not, then follow the procedure for Linux 2.4 as descibed above.
For FreeBSD, refer to man tun.You will likely want to enablenet.link.tun.devfs_cloning to create/dev/tun, but you will be in uncharted waters.
If you are using a current distributionyou will need to alter the permissions on the /dev/net/tun deviceto allow Hercules to open it.Issue ls -l /dev/net/tun (Linux)ls -l /dev/tun0 (OSX) to determine whether Hercules canopen the device.
You have two ways to make the tun device usable.Use the second only with nonstandard and/or old kernels(that is, if the first udev rule does not work for you.)
- The preferred way to change properties for the Linux
tundevice is via a udev rule in/etc/udev/rules.d - Alternatively, use the following commands to set the necessary permissions:
su(enter the root password when prompted)
chgrp xxxxx /dev/net/tun
chmod 0660 /dev/net/tunor make the device file writable by world; this does not consist an integrity exposure, as the world at large cannot do anything with the file descriptor it gets.
chmod 0666 /dev/net/tunAdditional notes from Greg Smith:
- I find on my Fedora Core 6 system that I have to add the above 2 commands to /etc/rc.local and update /etc/udev/rules.d/50-udev.rules replacing
KERNEL'tun', NAME='net/%k'
byKERNEL'tun', NAME='net/%k', GROUP='xxxxx', MODE='0660' - In the hercules log you should see /dev/net/tun0 opened. I get a couple of error messages about SIOCDIFADDR and SIOCSIFHWADDR ioctl's failing but these can be ignored.
- I find on my Fedora Core 6 system that I have to add the above 2 commands to /etc/rc.local and update /etc/udev/rules.d/50-udev.rules replacing
In Linux 2.6 the file /etc/modules.conf no longer exists,instead there is a file called /etc/modprobe.conf.TUN/TAP will usually work, however, without any change to the modprobeconfiguration.
Configuring a TUN interface
You may be able to configure the tunnel interfaces you will needat system boot;but if you cannot or will not, Hercules supplies a utility(hercifc) to do this.
At Linux boot
openvpn (http://openvpn.net/)is a utility that can open a tunnel device permanently.In addition you are likely to need a udev rule as described above.Openvpn is usually installed as a package (yum install openvpn on Fedora);if not refer to http://openvpn.net/index.php/open-source/documentation/howto.html.Note, however, that openvpn is just one way to create a permanent tunnel device;alternative methods may be possible.
To create permanent a tunnel interface, add this to rc.local(or as appropriate forthe distribution you are using):
This example assumes that Hercules is in the grouphercules; it shows the tunnel device in a separate network,which requires routing as described below.ifconfig can display the permanent interface:
If the interface is in the same subnet as the Hercules host,you need to enable proxy arp.One way to achieve this is to turn it on dynamically:
Free BSD
On FreeBSD, use the command ifconfig tun create to createan interface.
Using hercifc
The tun0 network interface in the driving system must be configuredas a point-to-point link. The original design of the TUN/TAP driver did notallow the interface to be statically configured like a regular networkinterface — the tun0 interface does not exist until a programopens the TUN device. For this reason, Hercules provides a specialprogram called hercifc to configure the tun0 network interface. Thisprogram is launched automatically by Hercules 3088 CTC deviceinitialization.(Later, the ability to make an interface permanent was added;this is why openvpn and preconfigured interfaces work.)
Installing korean font on microsoft word for mac. To allow the hercifc program to issue the necessary configurationcommands, you must ensure that hercifc is installed with setuid rootfile permissions. When Hercules is built with theconfiguration option --enable-setuid-hercifc=xxxxx, make installwill install hercifc in /usr/local/bin with setuid root permissions.The hercifc program will be executable only by group xxxxx.Note: Unrestricted access to the hercifc program could present apotential security exposure, so you will want to ensure that hercifccan be executed only by the group which is authorized to run Hercules.
The following commands have the same effect as theconfiguration option --enable-setuid-hercifc=xxxxx:
su (enter the root password when prompted)
chgrp xxxxx /usr/local/bin/hercifc
chmod 4750 /usr/local/bin/hercifc
exit
Note: you can avoid the need to install hercifc as a setuid rootprogram by creating a permanent tunnel interface at Linux boot time,as described above.
Enabling IP forwarding
You must ensure that your kernel is enabled for IP forwarding.Popular Linux distributions usually have a configuration optionto 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 and later kernel:
echo '1' > /proc/sys/net/ipv4/ip_forward
Defining a route to Hercules TCP/IP
Client systems that connect to TCP/IP applications running inthe Hercules machine need to have a routing entry to definethe driving system as the gateway into the Hercules system. Anexample route definition for a Unix client system is shown below:
For a Windows client, go to Settings -> Control Panel -> Network ->Configuration -> TCP/IP -> Properties -> Gatewayand add the driving system's IP address to the list of gateways.Alternatively, enter a route command such as:
Installing Z Vm On Hercules Poirot
If you want to avoid having to update client systems, another wayis to add an appropriate routing entry to your default gateway router.
Defining the link in Hercules
Installing Z Vm On Hercules Tv
You must define a CTC device pair in the Hercules configurationfile:The first device number must be even.The second device must bear the same definition as the firstinstance and be at device number + 1(for CTCI, the first definition beyond the device type is ignored;you only need to specify the definition with the second device).Devices should preferably be grouped (furthermore, it makes theconfiguration file easier to read).
For a preconfigured tunnel:
0E20.2 CTCI tun0
or
0E20,0E21 CTCI tun0
or
0E20-0E21 CTCI tun0
Using hercifc:
0E20.2 CTCI 192.168.200.1 192.168.200.2
or
0E20,0E21 CTCI 192.168.200.1 192.168.200.2
or
0E20-0E21 CTCI 192.168.200.1 192.168.200.2
Check Device Definition Statement syntax for an explanation of device grouping.
Two IP addresses must be assigned, one for the driving system'send of the link, and one for the Hercules end of the link. Forthis example I have chosen 192.168.200.1 for the Hercules IPaddress, 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 inthis example) does not conflict with any existing networkaddresses used in your IP network.
Configuring the Hercules TCP/IP stack
TCP/IP for VSE
This is an example of the configuration statements which you needto include in the IPINIT00.L member of PRD1.BASE:
The CTC devices should be defined to VSE using the followingstatements in the $IPLxxx.PROC procedure in IJSYSRS.SYSLIB:
TCP/IP for OS/390 or VM/ESA
This is an example of the configuration statements which you needto include in the TCPIP.PROFILE.TCPIP dataset (OS/390), or in thePROFILE TCPIP file on TCPMAINT 198 (VM):
For OS/390, the CTC devices need to be defined as device type 3088 inthe IODF. Use the D U,CTC command to find out which 3088addresses 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 interrupthandler should be disabled for the CTC devices.For OS/390, add this statement in PARMLIB member IECIOS00:
For VM, add this command to the PROFILE EXEC file of OPERATOR 191: Iso image extraction failure.
Linux for S/390
This is an example of the network definitions which you needin a Linux/390 system running under Hercules:
Linux/390 will autodetect the CTC devices E20 and E21at 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):
Installing Z Vm On Hercules Full
Bitsavers is organized first by manufacturer, then by machine. Within machine one can find operating system documentation. Use the following shortcuts to the Bitsavers site. And explore..one can find very useful information in unexpected places on Bitsavers.
- System/360 hardware & software manuals
- System/370 hardware & software manuals
- MVS software manuals. Also see OS/VS2 software manuals. OS/VS2 was IBM's original name for MVS.
Hercules Documentation and Useful Links
The Web/HTML documentation is in a 'how-to' style with examples. The downloadable PDFs are comprehensive reference documentation.
| Web/HTML | Downloadable PDFs |
|---|
Additional helpful links
About Hercules
Hercules was created by Roger Bowler.Jay Maynard ('the Tron Guy') was the maintainer from 2000 to 2012.Jan Jaeger designed and implemented many of the advanced features ofHercules, including dynamic reconfiguration, integrated console,interpretive execution and z/Architecture support. A dedicated crew ofprogrammers is constantly at work implementing new features and fixing bugs.
What people are saying about Hercules
'Never in my wildest dreams did I expect to see MVSrunning on a machine that I personally own.Hercules is a marvelous tool. My thanks to you all for a jobvery well done.'
—Reed H. Petty
'I do miss my mainframe a lot, and playing with Herc sure brings backmemories. Just seeing the IBM message prefixes, and responding toconsole messages again was a wonderful bit of nostalgia!'
—Bob Brown
'I have installed your absolutely fantastic /390 emulator.You won't believe what I felt when I saw the prompt.Congratulations, this is a terrific software.I really have not had such a fascinating and interestingtime on my PC lately.'
—IBM Large Systems Specialist
'Such simulators have been available for a long time. One of the mostcomplete (up to modern 64-bit z/Architecture) is hercules.'
—Michel Hack, IBM Thomas J. Watson Research Center
'An apparently excellent emulator that allows those open sourcedevelopers with an 'itch to scratch', to come to the S/390 tableand contribute.'
—Mike MacIsaac, IBM
'BTW grab a copy of Hercules and you can test it at home.It's a very good S/390 and zSeries (S/390 64bit) emulator.'
—Alan Cox
'It works even better than I imagined.Hercules is a fine piece of software!'
—Dave Sienkiewicz
'Hercules is a systems programmer's dream come true.'
—René Vincent Jansen
'Aside from the electric trains my parents gotme in 1953, this is the best toy I've ever been given,bar none.'
—Jeffrey Broido
'Congratulations to you and your team on a fine piece of work!'
—Rich Smrcina
'Congratulations on a magnificent achievement!'
—Mike Ross
'For anyone thinking running Hercules is too much trouble or too hardor whatever, I came home from work one day and my 13 year old 8thgrade son had MVS running under VM under Hercules on Linux. He hadgotten all the information about how to do this from the Internet.When he complained about MVS console configuration and figuring outhow to get it to work with VM, I knew he had felt all the pain heever needed to feel about mainframes.'
—Scott Ledbetter, StorageTek
'I am running a fully graphical Centos z/Linux environment on my desktop.The Hercules emulator is an amazing feat of engineering.I just wanted to send my compliments to the team for an excellent job!Thanks much for making this product part of the open-source community!'
—Roby Gamboa
'I have DOS and DOS/VS running on Hercules withsome demo applications, both batch and on-line. It does bring backsome good memories. My compliments go to the Hercules team. Thank you.'
—Bill Carlborg
'This is stunning piece of work. To say that I am blown away is anunderstatement. I have a mainframe on my notebook!!!!!!P.S. Now if I can just remember my JCL'
—Roger Tunnicliffe
Read Hesh Wiener's Technology News article about Hercules athttp://www.tech-news.com/another/ap200601b.html
Read Moshe Bar's BYTE.com article about Hercules athttp://web.archive.org/web/20010712143133/http://www.byte.com/documents/s=429/BYT20000801S0002/
For eighteen months, the IBM RedbookSG24-4987 Linux for S/390 athttp://www.redbooks.ibm.com/abstracts/sg244987.htmlcontained a chapter written by Richard Higsondescribing how to run Linux/390 under Hercules.Then suddenly, all mention of Hercules was mysteriouslyremoved from the online edition of the book!Read the story of the disappearing Redbook chapter athttp://www2.marist.edu/htbin/wlvtype?LINUX-VM.25658
View the foils from Jay Maynard's presentation given atSHARE Session 2880in San Francisco on 20 August 2002as a PDF file (815K) fromhttp://linuxvm.org/Present/SHARE99/S2880JMa.pdf
If you have any questions or comments please consider joining the hercules-390 discussion group athttp://groups.yahoo.com/group/hercules-390.
Bug reports for either release (together with your diagnosis of the fault, please)may be reported to either thehercules-390 discussion groupor entered into the appropriate Github issue tracker:
- Issues with the spinhawk version of Hercules
Other Hercules-related sites
- http://www.softdevlabs.com
Windows GUI for Hercules 4.0 Hyperion and other Hercules related software. - http://www.bsp-gmbh.com/hercules/index.shtml
Volker Bandke's ready-to-run MVS 3.8J turnkey system and all things MVS. - http://cbttape.org/~jmorrison/
Jim Morrison's downloads (includes 3380 support for MVS 3.8!) - http://www.jaymoseley.com/hercules
Jay Moseley's Hercules site - lots of Hercules and MVS information - http://www.tommysprinkle.com/mvs
Tommy Sprinkle's MVS 3.8 documentation - http://hansen-family.com/mvs
Bob Hansen's MVS 3.8 documentation - http://www.clueful.co.uk/mbeattie/hercules/tso.html
Malcolm Beattie's MVT/TSO documentation - http://www.ibiblio.org/jmaynard
Jay Maynard's S/360 and S/370 public domain software archive - http://www.shedlock.org/Shedlock/Hercules/index.html
George Shedlock's archive of DOS/VS Release 34 and VM/370 software, books, and information - http://www.smrcc.org.uk/members/g4ugm/VM370.htm
Dave Wade's VM/370 archive - http://perso.wanadoo.es/rptv2005/en/index.html
Rafael Pereira's Standalone Programs and 1401 simulator project - http://timpinkawa.net/hercules/
Tim Pinkawa's Hercules Page - http://www.lightlink.com/mhp/2703/
Max Parke's Hercules 2703 Page - TTY, TCAM, 3705 and more - https://github.com/s390guy/SATK
Harold Grovesteen's Stand-Alone Tool Kit (SATK)
IBM, System/370, ESA/390, and z/Architecture are trademarks orregistered trademarks of IBM Corporation.Other product names mentioned here are trademarks of other companies.
This page describes how to set up TCP/IP connectivity betweena Hercules machine and the outside world.
Since Hercules runs as a user process under the control of a drivingsystem (usually Linux/x86 or Windows), it does not have directaccess to the driving system's network adapter. This presents aproblem in establishing connectivity between the network and theTCP/IP stack of an operating system running under Hercules.
But thanks to a technique originally demonstrated byWillem Konynenberg, it is possible to establish a virtualpoint-to-point link between the TCP/IP stack running underHercules and the TCP/IP stack of the driving system. Thedriving system is then used as a router to pass IP framesbetween the Hercules TCP/IP stack and the rest of the network,as shown in the below diagram.
The virtual CTC link is provided by the Universal TUN/TAP driverdeveloped by Maxim Krasnyansky. This driver creates a tunnelwhich appears to Hercules as a character device (/dev/tun0 or/dev/net/tun) and appears to the driving system as a virtualnetwork interface (tun0).The Hercules 3088 driver makes the tun device appear asa CTCA (Channel to Channel Adapter) to the S/390 operating systemrunning under Hercules. Each end of the link has its own IPaddress which is distinct from the IP address of the drivingsystem's real network adapter.
Windows users should refer to Fish's CTCI-WIN web page which provides similar 'TunTap' functionality on Windows platforms.
Installing the TUN/TAP Driver (Linux 2.4)
The TUN/TAP driver is delivered as part of the Linux 2.4 kernel, andif you are using one of the popular Linux distributions you will findthat the TUN/TAP driver is already installed. If not, then you mustrebuild the kernel with the configuration option CONFIG_TUN=m specified.
Note that the version of TUN/TAP in Linux 2.4 differs from the earlierversion in that it allows access to all TUN interfaces (tun0, tun1, etc)through a single character device /dev/net/tun, instead of definingmultiple 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+rw /dev/net/tun
chmod o-rw /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.
Installing the TUN/TAP Driver (Linux 2.6, FreeBSD, OS X)
For distributions based on the Linux 2.6 kernel you will probably find that theTUN/TAP driver is already installed and the /dev/net/tun device is alreadydefined. If not, then follow the procedure for Linux 2.4 as descibed above.
For FreeBSD, refer to man tun.You will likely want to enablenet.link.tun.devfs_cloning to create/dev/tun, but you will be in uncharted waters.
If you are using a current distributionyou will need to alter the permissions on the /dev/net/tun deviceto allow Hercules to open it.Issue ls -l /dev/net/tun (Linux)ls -l /dev/tun0 (OSX) to determine whether Hercules canopen the device.
You have two ways to make the tun device usable.Use the second only with nonstandard and/or old kernels(that is, if the first udev rule does not work for you.)
- The preferred way to change properties for the Linux
tundevice is via a udev rule in/etc/udev/rules.d - Alternatively, use the following commands to set the necessary permissions:
su(enter the root password when prompted)
chgrp xxxxx /dev/net/tun
chmod 0660 /dev/net/tunor make the device file writable by world; this does not consist an integrity exposure, as the world at large cannot do anything with the file descriptor it gets.
chmod 0666 /dev/net/tunAdditional notes from Greg Smith:
- I find on my Fedora Core 6 system that I have to add the above 2 commands to /etc/rc.local and update /etc/udev/rules.d/50-udev.rules replacing
KERNEL'tun', NAME='net/%k'
byKERNEL'tun', NAME='net/%k', GROUP='xxxxx', MODE='0660' - In the hercules log you should see /dev/net/tun0 opened. I get a couple of error messages about SIOCDIFADDR and SIOCSIFHWADDR ioctl's failing but these can be ignored.
- I find on my Fedora Core 6 system that I have to add the above 2 commands to /etc/rc.local and update /etc/udev/rules.d/50-udev.rules replacing
In Linux 2.6 the file /etc/modules.conf no longer exists,instead there is a file called /etc/modprobe.conf.TUN/TAP will usually work, however, without any change to the modprobeconfiguration.
Configuring a TUN interface
You may be able to configure the tunnel interfaces you will needat system boot;but if you cannot or will not, Hercules supplies a utility(hercifc) to do this.
At Linux boot
openvpn (http://openvpn.net/)is a utility that can open a tunnel device permanently.In addition you are likely to need a udev rule as described above.Openvpn is usually installed as a package (yum install openvpn on Fedora);if not refer to http://openvpn.net/index.php/open-source/documentation/howto.html.Note, however, that openvpn is just one way to create a permanent tunnel device;alternative methods may be possible.
To create permanent a tunnel interface, add this to rc.local(or as appropriate forthe distribution you are using):
This example assumes that Hercules is in the grouphercules; it shows the tunnel device in a separate network,which requires routing as described below.ifconfig can display the permanent interface:
If the interface is in the same subnet as the Hercules host,you need to enable proxy arp.One way to achieve this is to turn it on dynamically:
Free BSD
On FreeBSD, use the command ifconfig tun create to createan interface.
Using hercifc
The tun0 network interface in the driving system must be configuredas a point-to-point link. The original design of the TUN/TAP driver did notallow the interface to be statically configured like a regular networkinterface — the tun0 interface does not exist until a programopens the TUN device. For this reason, Hercules provides a specialprogram called hercifc to configure the tun0 network interface. Thisprogram is launched automatically by Hercules 3088 CTC deviceinitialization.(Later, the ability to make an interface permanent was added;this is why openvpn and preconfigured interfaces work.)
Installing korean font on microsoft word for mac. To allow the hercifc program to issue the necessary configurationcommands, you must ensure that hercifc is installed with setuid rootfile permissions. When Hercules is built with theconfiguration option --enable-setuid-hercifc=xxxxx, make installwill install hercifc in /usr/local/bin with setuid root permissions.The hercifc program will be executable only by group xxxxx.Note: Unrestricted access to the hercifc program could present apotential security exposure, so you will want to ensure that hercifccan be executed only by the group which is authorized to run Hercules.
The following commands have the same effect as theconfiguration option --enable-setuid-hercifc=xxxxx:
su (enter the root password when prompted)
chgrp xxxxx /usr/local/bin/hercifc
chmod 4750 /usr/local/bin/hercifc
exit
Note: you can avoid the need to install hercifc as a setuid rootprogram by creating a permanent tunnel interface at Linux boot time,as described above.
Enabling IP forwarding
You must ensure that your kernel is enabled for IP forwarding.Popular Linux distributions usually have a configuration optionto 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 and later kernel:
echo '1' > /proc/sys/net/ipv4/ip_forward
Defining a route to Hercules TCP/IP
Client systems that connect to TCP/IP applications running inthe Hercules machine need to have a routing entry to definethe driving system as the gateway into the Hercules system. Anexample route definition for a Unix client system is shown below:
For a Windows client, go to Settings -> Control Panel -> Network ->Configuration -> TCP/IP -> Properties -> Gatewayand add the driving system's IP address to the list of gateways.Alternatively, enter a route command such as:
Installing Z Vm On Hercules Poirot
If you want to avoid having to update client systems, another wayis to add an appropriate routing entry to your default gateway router.
Defining the link in Hercules
Installing Z Vm On Hercules Tv
You must define a CTC device pair in the Hercules configurationfile:The first device number must be even.The second device must bear the same definition as the firstinstance and be at device number + 1(for CTCI, the first definition beyond the device type is ignored;you only need to specify the definition with the second device).Devices should preferably be grouped (furthermore, it makes theconfiguration file easier to read).
For a preconfigured tunnel:
0E20.2 CTCI tun0
or
0E20,0E21 CTCI tun0
or
0E20-0E21 CTCI tun0
Using hercifc:
0E20.2 CTCI 192.168.200.1 192.168.200.2
or
0E20,0E21 CTCI 192.168.200.1 192.168.200.2
or
0E20-0E21 CTCI 192.168.200.1 192.168.200.2
Check Device Definition Statement syntax for an explanation of device grouping.
Two IP addresses must be assigned, one for the driving system'send of the link, and one for the Hercules end of the link. Forthis example I have chosen 192.168.200.1 for the Hercules IPaddress, 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 inthis example) does not conflict with any existing networkaddresses used in your IP network.
Configuring the Hercules TCP/IP stack
TCP/IP for VSE
This is an example of the configuration statements which you needto include in the IPINIT00.L member of PRD1.BASE:
The CTC devices should be defined to VSE using the followingstatements in the $IPLxxx.PROC procedure in IJSYSRS.SYSLIB:
TCP/IP for OS/390 or VM/ESA
This is an example of the configuration statements which you needto include in the TCPIP.PROFILE.TCPIP dataset (OS/390), or in thePROFILE TCPIP file on TCPMAINT 198 (VM):
For OS/390, the CTC devices need to be defined as device type 3088 inthe IODF. Use the D U,CTC command to find out which 3088addresses 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 interrupthandler should be disabled for the CTC devices.For OS/390, add this statement in PARMLIB member IECIOS00:
For VM, add this command to the PROFILE EXEC file of OPERATOR 191: Iso image extraction failure.
Linux for S/390
This is an example of the network definitions which you needin a Linux/390 system running under Hercules:
Linux/390 will autodetect the CTC devices E20 and E21at 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):
Installing Z Vm On Hercules Full
Z/vse
- Enter the command
ls -l /dev/tun0 /dev/net/tun.
For Linux 2.4 and later kernels, 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:
`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 $Date$ $Revision$
