## My Turnkey-5 Implementation
Several people have asked me how I managed to get a mainframe running on my laptop. This post explains how I did that. Enjoy!
### Setting Up The Host Machine
You can run the entire setup from your native workstation, if you want. But that's not what I did. for the sake of portability, compatibility, and stability, I constructed a virtualbox using Debian 12, on which to host the Turnkey package:
* ISO: Debian 12 (64bit)
* CPU(s): 2 (explained in a moment)
* Acceleration: Paging, VT-x/AMD-V, PAE/NX, KVM
* RAM: 1024MB
* Display: Default
* Storage: VDI 60GB
* Network: **Bridged**
The reason for 2 CPUs is because when we set up the TK5 system, it will include two of its own mainframe cpus, and we want to be able to take advantage of that on the host.
The reason for the BRIDGED adapter, is because we want to make the mainframe accessible from other devices on the local subnet. If everything you do is local to the host machine, then a normal NAT connection will also work.
Go through the normal debian installation process. Don't include a desktop environment, because it won't be needed. Make sure to include the ssh server as part of the installation, and make sure you're able to ssh into the the VM from your host:
gmgauthier@boethius $ ssh sysa
Linux tk5-sysa 6.1.0-23-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.99-1 (2024-07-15) x86_64
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Jan 14 21:45:05 2025 from 192.168.68.103
### Installing Turnkey
Next, you'll want to install the base turnkey package to the root account. You'll be working entirely from root now. Use wget to download the zip file from [Eric Prince's Turnkey Page](https://www.prince-webdesign.nl/images/downloads/mvs-tk5.zip), to the root account. Once there, unzip it in place. your director should now have an `mvs-tk5.zip` file, and an `mvs-tk5` directory:
gmgauthier@tk5-sysa:~$ su root
Password:
root@tk5-sysa:/# cd /root
root@tk5-sysa:~# ls -l
total 432068
-rw-r--r-- 1 root root 34 Aug 3 16:35 blkid.txt
drwxr-xr-x 3 root root 4096 Aug 3 17:05 go
drwxr-xr-x 20 root root 4096 Aug 4 03:19 mvs-tk5
-rw-r--r-- 1 root root 442420923 Jul 29 22:25 mvs-tk5.zip
drwxr-xr-x 10 root root 4096 Aug 3 17:05 virtual1403
root@tk5-sysa:~#
cd into the `mvs-tk5` directory. This is roughly what you should see:
root@tk5-sysa:~/mvs-tk5# ls -l
total 100
drwxr-xr-x 2 root root 4096 Aug 4 13:00 archive
drwxr-xr-x 3 root root 4096 Oct 25 17:04 conf
drwxr-xr-x 11 root root 4096 Jul 29 22:25 ctca_demo
drwxr-xr-x 2 root root 4096 Aug 4 21:12 dasd
drwxr-xr-x 2 root root 4096 Jul 29 22:25 doc
-rw-r--r-- 1 root root 1104 Aug 1 22:27 herclogo.txt
drwxr-xr-x 7 root root 4096 Aug 1 22:22 hercules
drwxr-xr-x 2 root root 4096 Aug 4 09:05 jcl
drwxr-xr-x 2 root root 4096 Jul 29 22:25 local_conf
drwxr-xr-x 2 root root 4096 Aug 4 01:46 local_scripts
drwxr-xr-x 2 root root 4096 Jul 29 22:25 log
-rwxr-xr-x 1 root root 1221 May 30 2023 mvs
-rwxr-xr-x 1 root root 1776 May 30 2023 mvs.bat
-rwxr-xr-x 1 root root 2196 May 30 2023 mvs_ipl
-rwxr-xr-x 1 root root 1489 May 30 2023 mvs_osx
drwxr-xr-x 16 root root 4096 Jul 29 22:25 Packages
drwxr-xr-x 2 root root 4096 Jul 29 22:25 pch
drwxr-xr-x 2 gmgauthier gmgauthier 4096 Aug 3 17:45 printouts
drwxr-xr-x 2 root root 4096 Jul 29 22:25 prt
drwxr-xr-x 2 root root 4096 May 24 2013 rdr
drwxr-xr-x 3 root root 4096 Aug 4 13:56 scripts
-rw-r--r-- 1 root root 1968 Aug 6 2023 start_herc
-rw-r--r-- 1 root root 1331 Aug 6 2023 start_herc.bat
drwxr-xr-x 2 root root 4096 Jul 31 21:19 tape
drwxr-xr-x 2 root root 4096 Jul 29 22:25 unattended
### Configuring Turnkey
We'll now need to make a few minor configuration changes to be able to run our system locally. `cd` into the "conf" directory:
root@tk5-sysa:~/mvs-tk5# cd conf
root@tk5-sysa:~/mvs-tk5/conf# ls -l
total 132
-rw-r--r-- 1 root root 131 Mar 29 2023 cbt_dasd.cnf
-rw-r--r-- 1 root root 212 May 30 2023 extcons.cnf
-rw-r--r-- 1 root root 89 Nov 15 2013 intcons.cnf
-rw-r--r-- 1 root root 894 May 15 2020 local.cnf
-rw-r--r-- 1 root root 160 Mar 29 2023 source_dasd.cnf
-rw-r--r-- 1 root root 2542 Aug 4 11:49 tk5.cnf
-rw-r--r-- 1 root root 3550 May 30 2023 tk5_default.cnf
-rw-r--r-- 1 root root 1125 May 30 2023 tk5_specific02.cnf
drwxr-xr-x 2 root root 4096 Jul 29 22:25 tk5_updates
-rw-r--r-- 1 root root 928 May 30 2023 tk5_updates.cnf
-rwxrwxrwx 1 root root 29360 Dec 7 1998 ZZSACARD.BIN
-rw-r--r-- 1 root root 1026 Aug 4 09:53 zzsa.cnf
-rwxrwxrwx 1 root root 26400 Dec 7 1998 ZZSADIMG.BIN
-rwxrwxrwx 1 root root 26400 Dec 7 1998 ZZSATIMG.BIN
Now, edit the `tk5.cnf` file, which is the default configuration (despite the fact that there's already a file by that name). You should see this as the first few lines before the device configs:
#**********************************************************************
#*** ***
#*** File: tk5.cnf ***
#*** ***
#*** Purpose: Hercules configuration file for MVS 3.8j TK5 ***
#*** ***
#*** Updated: 2023/05/30 ***
#*** ***
#**********************************************************************
MSGLEVEL -EMSGLOC
${EXPLICIT_LOG:=#}
CPUSERIAL 000611
CPUMODEL 3083
MAINSIZE ${MAINSIZE:=16}
XPNDSIZE 0
CNSLPORT ${CNSLPORT:=3270}
HTTP PORT ${HTTPPORT:=8038}
HTTP ROOT hercules/httproot
HTTP START
NUMCPU ${NUMCPU:=2}
MAXCPU ${MAXCPU:=2}
TZOFFSET +0000
ARCHMODE S/370
OSTAILOR QUIET
DIAG8CMD ENABLE ECHO
Set `CPUMODEL` to `3083`. Then, set `NUMCPU` and `MAXCPU` to `2`. Finally, set `TZOFFSET` to either `+` or `-` the value in hours, relative to GMT. I personally just leave it as-is, because I don't care about the precise time. Once that's all done, the system will be set up to take advantage of both cpus on the virtual host.
Below the basic configuration values, you'll find the "DASD" virtual volume configuration. "DASD" is the IBM acronym for "Direct Access Storage Device", which basically just means magnetic disk. Or, in our case, virtual files that emulate IBM magnetic disk devices.
#
# TK5 DASD
#
0390 3390 dasd/tk5res.390
0391 3390 dasd/tk5cat.391
0392 3390 dasd/tk5dlb.392
0380 3380 dasd/int001.380
0190 3390 dasd/tso001.190
0191 3390 dasd/tso002.191
0192 3390 dasd/tso003.192
0248 3350 dasd/page00.248
0249 3350 dasd/spool0.249
0290 3390 dasd/work01.290
0291 3390 dasd/work02.291
0292 3390 dasd/work03.292
0293 3390 dasd/work04.293
0298 3390 dasd/tk5001.298
0299 3390 dasd/tk5002.299
ALL of these volumes are absolutely necessary for a full system. But the most important volumes are the ones suffixed `RES`, `CAT`, and the `PAGE` and `SPOOL` volumes.
The `RES` Volume stands for "System Resident", and just means all the datasets that need to be loaded directly into memory for system execution. This of this as the conceptual equivalent of a bootstrap directory of a PC.
The `CAT` Volume stands for "System Catalog", and contains an indexed list of all the datasets available on your MVS system. Without this, you would have no way to access data on the system. Think of it as the conceptual equivalent of a VTOC on a PC disk drive.
The `PAGE` volumes are conceptually similar to Swap partitions on a linux machine, and the `SPOOL` volume is actually kind of unique to MVS. It's a place where all program output is queued for distribution to an output device like a printer.
The remaining disk volumes are data disk volumes for storing source code, binary executables, and other forms of data necessary for application programs.
The next batch of lines in the configuration file, are for peripheral devices attached to the mainframe:
# unit record devices
#
0002 3211 prt/prt002.txt ${TK5CRLF}
#000E 1403 prt/prt00e.txt ${TK5CRLF}
000E 1403 localhost:1403 sockdev
000C 3505 ${RDRPORT:=3505} sockdev ascii trunc eof
000D 3525 pch/pch00d.txt ascii
0480 3420 *
010C 3505 jcl/dummy eof ascii trunc
010D 3525 pch/pch10d.txt ascii
#000F 1403 prt/prt00f.txt ${TK5CRLF}
000F 1403 localhost:1404 sockdev
030E 1403 log/hardcopy.log ${TK5CRLF}
The first column sets a device id the system will use to identify the peripheral. The second column is the model of the device, which effectively identifies the *kind* of device. A `1403` is a printer. A `3505` is a card reader. A `3525` is a card punch. Device 0480 is a `3420` tape drive. This will be important to know, when we attempt to apply the supplement tape update to this instance.
By default, all output devices are defined to dump to text files on the host system path for that device ("prt/", "pch/", "log/"). But you will notice that a few have been defined with TCPIP ports instead. The reader device on 000C, for example, is set to port 3505. This will come into play in a further post, on how to submit remote JCL cards to your mainframe, which will make it easy to write and submit JCL from someplace like VSCode!
Note also, tha there are two 1403 Printers defined to localhost:1403 and localhost:1404. These printers will send all of their plain-text output to those ports. A separate post here will explain how to set up linux printer daemons that will produce greenbar PDF files from that output, and ship it to an output directory on your local machine.
Lastly the configuration file sets up our 3270 devices and terminals. These are the way we will "log in" to the system as a human user, and interact with it; writing programs, running programs, looking at output, and other things.
#
# local 3270 devices (VTAM)
#
00C0 3270
00C1 3270
00C2 3270
00C3 3270
00C4 3270
00C5 3270
00C6 3270
00C7 3287
#
# local 3270 terminals (TCAM)
#
03C0 3270 TCAM
03C1 3270 TCAM
03C2 3270 TCAM
03C3 3270 TCAM
03C4 3270 TCAM
03C5 3270 TCAM
03C6 3270 TCAM
03C7 3270 TCAM
For now, that's all we really need to cover in the configuration file. So, let's close out of the file, and `cd` back into the base directory
root@tk5-sysa:~/mvs-tk5/conf# nano tk5.cnf
root@tk5-sysa:~/mvs-tk5/conf# cd ..
root@tk5-sysa:~/mvs-tk5#
### Running The Turnkey MVS Instance
At this point, there is technically only one other thing that is necessary to get the system going. You will want to do this so that you can interact with the machine directly from the console. `cd` into the "unattended" directory:
root@tk5-sysa:~/mvs-tk5# cd unattended
root@tk5-sysa:~/mvs-tk5/unattended# ls -l
total 20
-rw-r--r-- 1 root root 8 Dec 2 09:52 mode
-rwxr-xr-x 1 root root 788 Jul 23 2023 set_console_mode
-rwxr-xr-x 1 root root 830 Nov 28 2013 set_console_mode.bat
-rwxr-xr-x 1 root root 792 May 30 2023 set_daemon_mode
-rwxr-xr-x 1 root root 828 May 30 2023 set_daemon_mode.bat
Run the `set_console_mode` script:
root@tk5-sysa:~/mvs-tk5/unattended# ./set_console_mode
Hercules console mode activated for unattended operations mvs
Press any key to continue...
Once that's done, return to the base directory. From there, we can launch the system with the `mvs` command, which will load the master console directly:
root@tk5-sysa:~/mvs-tk5/unattended# cd ..
root@tk5-sysa:~/mvs-tk5# ./mvs
HHC01536W HDL: WARNING: '/usr/local/lib/hercules' is not a valid directory
HHC00007I Previous message from function 'hdl_checkpath' at hdl.c(769)
HHC01413I Hercules version 4.7.0.0-SDL
HHC01414I (C) Copyright 1999-2024 by Roger Bowler, Jan Jaeger, and others
HHC01417I ** The SDL 4.x Hyperion version of Hercules **
HHC01415I Build date: Mar 11 2024 at 19:11:26
HHC01417I Built with: GCC 11.4.0
HHC01417I Build type: GNU/Linux x86_64 host architecture build
HHC01417I Modes: S/370 ESA/390 z/Arch
HHC01417I Max CPU Engines: 128
[ truncated ]
. . .
Congratulations. You are now at the **Master Console** of an IBM S/370 running MVS 3.8j. A system that, back in 1980, would have cost you approximately $4.7m ($17.9m in current day).
### Mastering The Master Console
HHC01603I * TT TT TT KK KK 55 +
HHC01603I * TT TT TT KK KK 55 Update 3
HHC01603I * TT KK KK 55
HHC01603I * 4l _,,,---,,_ TT KK KK 55
HHC01603I * ZZZzz /,'.-'`' -. ;-;;, TT KKKK 55555555555
HHC01603I * 4,4- ) )-,_. ,( ( ''-' TT KKKKK 55
HHC01603I * '---''(_/--' `-')_) TT KK KK 55
HHC01603I * TT KK KK 55
HHC01603I * The MVS 3.8j TT KK KK 55
HHC01603I * Tur(n)key System TT KK KK 55
HHC01603I * TTTTTT KKKK KKK 55555555555
HHC01603I *
HHC01603I * TK3 created by Volker Bandke volker@bandke.org
HHC01603I * TK4- update by Juergen Winkelmann juergen.winkelmann@pebble-beach.ch
HHC01603I * TK5 update by Rob Prins prin0096@gmail.com
HHC01603I * see SYS2.JCLLIB(CREDITS) for complete credits
HHC01603I *
HHC02264I Script 4: file scripts/tk5.rc processing ended
HHC00013I '/' input entered for console 0:0009: "d r,l"
d r,l
/23.13.27 IEE111I NO OUTSTANDING REQUESTS
HHC00013I '/' input entered for console 0:0009: "d a,l"
d a,l
/23.13.31 IEE102I 23.13.31 25.018 ACTIVITY 453
/ 00009 JOBS 00006 INITIATORS
/ CMD1 CMD1 CMD1 V=V
/ BSPPILOT BSPPILOT C3PO V=V S
/ JES2 JES2 IEFPROC V=V
/ NET NET IEFPROC V=V
/ TP TP TCAM V=V
/ MF1 MF1 IEFPROC V=V S
/ TSO TSO STEP1 V=V S
/ SNASOL SNASOL SOLICIT V=V
/ JRP JRP JRP V=V
/ 00000 TIME SHARING USERS
/ 00000 ACTIVE 00040 MAX VTAM TSO USERS
herc =====>
At this point, most of you will be wondering: "Okay. What now?". Well, now you operate your system. That's what. There is a distinction that needs to be made here. It's not like how we "use" microcomputers today. Back in the day, there was an "operator", and there was a "user". The user was the administrator, the programmer, or the accountant, who just used various programs available to him on his terminal device.
The Operator, however, sat all day long at this console, monitoring system resources, responding to system prompts, mounting tapes, running utility jobs, printing output, and occasionally "IPLing" the system (what we now call 'rebooting').
To know how to operate the system, you need to know a little something about the system. For starters, how do you enter commands, and what are they showing you? For example, how can you see all the things running on the system? For linux users, there's the `ps` command, or `htop` if you prefer something a little more aesthetically pleasing. It's kind of not like that on MVS.