Getting z/OS installed on my Ubuntu laptop

Some people retire and buy an open top sports car or big motorbike.  Up here in Orkney  the weather can change every day, so instead of buying a fast car with an open top, when I retired, I got z/OS running on my laptop for the similar sort of price!   This means I can continue “playing” with z/OS and MQ, and helping the next generation to use z/OS.  At the end of this process I had the software installed on my laptop, many unwanted DVDs, and a lot of unnecessary cardboard.

I’ll cover my journey in getting the product and installing it, so anyone following in my footsteps will know what to expect and the time frame.  The process works, but could be slicker.

What options are there?

There are two emulators

Hercules – Hercules is an open source software implementation of the mainframe System/370 and ESA/390 architectures, in addition to the new 64-bit z/Architecture. Hercules runs under Linux, Windows (98, NT, 2000, and XP), Solaris, FreeBSD, and Mac OS X (10.3 and later).

zPDT from IBM.  IBM System z® Personal Development Tool (IBM zPDT®), which produces a small System z environment suitable for application development. zPDT is a PC Linux application. When zPDT is installed (on Linux), normal System z operating systems (such as IBM z/OS®) can be run on it. zPDT provides the basic System z architecture and emulated IBM 3390 disk drives, 3270 interfaces, OSA interfaces, and so on.  It needs a USB dongle or a license server to run.

What software can be used?

• Products like z/OS, z/VM and z/VSE are licensed to run on only zPDT software.
• Using z/VM to provide a coupling facility allows z/OS sysplex functions to be run.  Your USB dongle needs to have the support for this.
• Public domain or “copyrighted software provided without charge”  software like OS/360,  DOS/VS, MVS, VM/370 were in the field a long time ago and can be installed on Hercules without a license.     You can also get MTS (which I used when I was at University).

What software is available to me?

I will not cover Hercules, as it is not licensed, and will only cover the IBM solution.

1. For (big) business partners who are developing software to run on z/OS, you need to get approval to become a z ISV.  You can then  get the hardware dongles and the software from one part of IBM
2. For other people (like me) who want to use z/OS running on a laptop for non production work there is zDevelopment and Test (zD&T). This comes in 3 flavours.
   1. ZD&T Personal Edition enables a single user to run an IBM® Z distribution on a personal computer. For more information about Personal Edition, see Personal Edition.
      • See here for the price.  You can pay for a 1 year subscription, get support from IBM,  download the code and any updates, and a hardware dongle which has the license to use/decrypt the code
      • You can pay for a perpetual license where you get the 1 year subscription as above, but can use it for ever (no support or updates after 1 year).  You can renew the license for the dongle at no charge.
   2. ZD&T Enterprise Edition enables enterprises to host an IBM Z distribution on low-cost Intel-based x86 machines. Enterprise Edition provides a web-based interface. You can extract, deploy, and manage the application images from an existing Z or ADCD packages. For more information about ZD&T Enterprise Edition, see Enterprise Edition.
      • I could not find the price for this. The license set-up looks very complex.  It looks like you need multiple machines to implement it  With a flexible licensing method, ZD&T Enterprise Edition can be used on cloud, VMs, or in-housed physical 8086 hardware. The Enterprise Edition also comes with a single user license that is known as Authorized User (AU) license, or with a multi-user license that is known as the Resource value Unit (RVU) license.
   3. ZD&T Parallel Sysplex can be used to enable a Sysplex environment that is running within z/VM®. For more information about ZD&TParallel Sysplex, see Parallel Sysplex.
      • I could not find the price for this. It looks like you have to use  a separate machine running as a license server.  The Software-based License Server and ZD&T Parallel Sysplex cannot be installed on the same machine.   I got confused between hardware dongle, software License Server and Rational tokens (which look like they need a different machine).

How do I purchase it?

See the IBM website.  That is the for the UK.    Or use

• HTTP://IBM.COM
• sign on
• search for Development test environment
• Select IBM Z Development and Test Environment in the right hand side of the window.

I’ve paid my money – now what?

This page says Software available for immediate download after online purchase.  This was not true for me.

• You need an IBM id – this takes seconds to obtain.
• To be able to download software and get the hardware key, you need access to Passport Advantage.
• To get access to Passport Advantage you need a site number
• To download software you need an IBM customer number, and an entry in a database saying what you are entitled to download.
• To get a customer number takes a few days.

You should plan on two weeks from ordering the package to be able to run it.

The sequence of events before I could download the software and order the USB key…

• I paid my money on the day 1
• I quickly received an an email from IBM saying “thank you for your order”.   I was expecting a slick process like Amazon, saying “Your dongle has been dispatched – expect it in 3 days, you can download the software now” – but no.
• I quickly received an email from IBM saying “Welcome to IBM Rational License Key Center.  Here is your License Key Center account ID:123456789.  Here are the instructions for downloading your license key”.  Great – the first question it asks  is “what is the serial number of your hardware key”.  I had not received it yet, so could not download the license.
• I created a Passport Advantage account using the “License Key Center account ID” as my “site”.  This worked, and I got an email saying “IBM Welcomes you to Passport Advantage Online”
• I logged on and tried downloading software – there was non available to me.  I could not order a hardware dongle as I needed a customer number.
• I had an email from IBM Philippines asking “please confirm if this is for personal or commercial use”.  I said this was for me using as part of my company.    As a result it was flagged as “personal use”.
• Day 2. I got an electronic PDF invoice, which told me my site number was as above.
• I received my “Proof of entitlement” giving me my customer number and site number.
• Later that night I got an email “IBM Electronic Support: Welcome to IBM Electronic Support“
• Day 3. I could order my hardware dongle and there was software for me to download!
• The money was taken from my account
• The hardware USB key arrived on day 11 – but the courier notified my it was coming on day 15.

So overall allow for a couple of days before you can access the software, and 2 weeks for the box of dongles.

Downloading the software

If you use the DownloadDirector, check that directory is empty before you start the download – you can move files to a sub directory, or select a different directory for the downloads.  The default directory is ~/DownloadDirector.

You need about 46GB just to download the files,and 270 GB when the files are unpacked.  There are 31 unpacked files of 8GB and one file of 15 GB for z/OS and its disks.  If you are going to allocate additional disks, plan for 8GB for each.

At first glance, the download looked pretty simple. It is, unless you want to put the files on a different drive to the default.

• From the IBM Passport Advantage site click on Download software.
• It had IBM Z Development and Test Environment Personal Edition displayed.  I clicked on it.
• It popped up a window saying
  • IBM Z Development and Test Environment Personal Edition
  • Please do not select an operating system and language for all Engineering and Rational software.   I don’t know what this means.  I ignored it
  • Operating system had a pull down list 1) All operating systems 2) Redhat.   I use Ubuntu so I chose 1) All operating systems.
  • Language had a pull down list of languages.  I selected English and clicked Go.
• The download page said Required: 38 files (45319MB)  which was the first time I had been told about the amount of space needed.
• I could select all files or individual files.   This page  gives a list of packages to volids.  A package may have more than one file in it – despite what the description is.
• I clicked on Estimate download time for selected files.   it gave me T1 Download Director 951 minutes, HTTP 4758 minutes.
• I clicked on  Download, which displayed a terms and conditions page.  Click “HTTP” or “Download Director”, click “I agree” and click “download now” .
• It displayed “Your browser might ask to open/save a JNLP file in order to launch Download Director. Open the JNLP file with Java WebStart (javaws).”  Click OK
• It popped up a window “Opening IBM_DownloadDirector.jnlp” Select “Open with “Oracle Java 8 Web Start (default)”   click OK
• There is a pop up ” Do you want to run this application?  IBM Download Director?” Click on Run
  • The first time I ran it, it tried to put all of the downloads in ~/DownloadDirector.  I clicked cancel, and Setup, and specified the download location to my external hard drive, and clicked “Always ask for Download location”. When I reran it, I think it ignored the location and  put the files in the ~/DownloadDirector path.   The second time I came through this process, it prompted me for the Download Location as expected.  It would be nice if the first time through it prompted for download location rather than take the default.
• Check where the files are being downloaded to, and restart the download if they are going to the wrong place.
• The documentation says Verify the integrity of downloaded ADCD packages by using the MD5SUM that is in the adcd.md5 and pe.md5 files.   You can use the command  md5sum -c nov2019_adcd_md5.txt  to do a checksum on the downloads.

Ordering the hardware dongle.

In Passport Advantage, select “Software download & media access“.  Then select “Request Media”.   It should have the hardware dongle items you need.  I can’t remember what I ordered, but I overachieved and ordered stuff I didn’t want.   I cannot remember what the request page looked like, but once the order had been fulfilled it I could see I had ordered

• IBM Z Development and Test Environment Version 9.1 Hardware Key Multiplatform Multilingual DVD Media Pack (BT0MIML)
• IBM Z Development and Test Environment Version 9.1 Multiplatform Multilingual DVD Media Pack (BT0MJML)
• IBM Z Development and Test Environment Hardware Key Version 9.5 Multiplatform Multilingual DVD Media Pack (BT0NUML)
• IBM Z Development and Test Environment Personal Edition Version 10.0 Multilingual Hardware Key Media Pack (BT0P6ML)
• IBM Z Development and Test Environment Personal Edition V12.0 Multilingual Hardware Key Media Pack (BT0PFML)

I do not know which of these I should have ordered, the names all look similar.   I was reminded of the phrase from the original game of Adventure “you are in a maze of twisty little passages , packages all alike”

What came in the dongle box?

I  was notified that the package would be delivered on day 15, but it arrived on day 11.  I was expecting a small jiffy bag. I got a box 30 cm * 24 cm * 20 cm, with lots of Russian Doll type boxes – it was like Christmas!

In the box I had

• A box labelled RD&T for System z V9.1 Hardware key media pack containing
  • a box containing
    • a bag containing
      • a plastic wallet containing
        • the USB
  • a CD labelled  IBM Rational Developer and test environment for system z V9.1
  • some instructions
  • other paper work
• A box labelled RD&T for System z V9.5 Hardware key media pack containing
  • a box containing a bag,containing a plastic wallet, containing the USB
  • a CD labelled  IBM Rational Developer and test environment for system z V9.5
  • some instructions
  • other paper work
• A box labelled IBM z Systems Development and Test Environment Personal Edition  V10 containing
  • a box containing a bag, containing a plastic wallet, containing the USB
  • a CD labelled IBM z Systems Development and Test Environment Personal Edition  V10
  • some instructions
  • other paper work
• A box labelled IBM z Systems Development and Test Environment Personal Edition  V12 containing
  • a box containing a bag, containing a plastic wallet, containing the USB
  • a CD labelled IBM z Systems Development and Test Environment Personal Edition  V12
  • some instructions
  • other paper work
• A bigger box containing CDs
  • IBM Rational Integration Tester Platform Pack 1 CD
  • IBM Rational License Key Server 1 CD
  • IBM Rational Developer and test environment  for System z v9.1 Software distribution for z/OS 1.1.3 12 CDs
  • IBM Rational Developer and test environment  for System z v9.1 Software distribution for z/OS 2.1 15 CDs

Overall I got 4 USB keys (It  could be a challenge to use all 4 ,as my laptop has only one spare USB slot), lots of software and a lot of cardboard.  As I have already downloaded the images, I have two lots of software CDs I do not need. I think the provisions system needs to be looked at, so I get just what I need (one dongle) instead of a lot of waste cardboard and plastic.

Getting the license for the keys

The documentation has a topic Obtaining an update file from Rational License Key Center  which worked.

• Follow the link and logon
• It showed me IBM Rational Developer for System z Unit Test.
• The serial number of one of my USBs was like 02-00222.
• Number of Server Instances:1
• Number of Licenses:1
• Click generate, wait for 10 second and a window is displayed
• Click download – and save it
• Follow the instructions in the documentation.  I cannot use “su” so I used sudo ./Z1091_token_update…  which worked.  note the upper case Z in Z1091
• The status command “sudo ./Z1091_token_update -status” gave me
  • Info: Processing Status request.
  • Info: Found both ADCD-1 License and ADCD-2 License.
  • Info: Command completed with 0 error(s).

As I was only entitled to one license – I had 3 spare dongles but with no license for them.

Installing zD&T.

The instructions are here.

1. Check the instructions are for the level of zD&T you are using.   Google found me the version for 12.04; I was using 12.05
2. The license is displayed.
   1. The license is displayed using the more command, so you can use ‘f’ and ‘b’ to go forward and back.  (Until you get to the last page when you cannot go back,  you have to decline license, and go through the install again.
   2. I found the license was not clear.   It looks like big chunks are repeated with only minor variations, which were too subtle for me.
   3. Some software you are allowed to install but not use: Fault Analyzer for z/OS and File Manager for z/OS.  (File manager:  IBM® File Manager for z/OS® (base component) provides comprehensive, user-friendly tools for working with Websphere MQ data, HFS files and QSAM, VSAM and IAM data sets. These tools include the familiar view, edit, copy and print utilities found in ISPF, enhanced to meet the needs of application developers)
   4. I think the words about Authorized User Single Session apply to zD&T personal Edition, and the words about  Resource Value Unit (RVU) apply to the enterprise edition.
   5. I don’t understand When determining the number of entitlements required for Licensee’s installation or use of the Program, Licensee is allowed to define up to two log-in identifiers for use by system programmers (i.e. system administrators or database administrators) to support Licensee development and test activities, which are not used to determine the number of entitlements required for the Program.  I do not understand this (what entitlements?, what is not used ?).  At least two userids are defined, for example IBMUSER, so additional  system programming userids may not be needed.  I do not know if I am allowed to define more userids for doing MQ application development, and defining MQ resources.
   6. The license refers to “Program”.   The text has Program Name : IBM Z Development and Test Environment Enterprise Edition Version 12.0.5, so I think the term “Program” to mean the whole package, so CICS, MQ and z/OS are individual Programs.
      1. This sounds a bit recursive, The license Programs, have programs (load modules) which have programs (compilable source code), the compiled programs have z architecture  instructions which deep down have programs in zPDT, which have instructions which have microcode programs which run on the chip.
   7. I could not find how to get a copy of the license, so I cancelled the installation and found the license in ~/DownloadDirector/zdtpefolder/license/Lic_en.txt
   8. Text like L/N: L-JWOG-BKVNF6 are the license number.  I think it is IBM internal use only as I googled it but could not find it.
   9. So overall written by lawyers and hard to understand.

Optional questions.

It asked Do you want to install Network Configuration for IBM® ZD&T Personal Edition ?(y/N):

I don’t think it installs anything.   I think it configures the network. See installation  and network.  The configuration scripts for example in /opt/ConfigGuideSample/zdt_config_network10.sh enables packet forwarding,  uses iptables to set up routing, Network Address Translation(NAT) with destination of 10.1.1.2.

I could IPL and logon without doing this optional step.  To get FTP working, I had to make one network configuration action.

It uses iptables-save  to make a copy of the IP configuration.  You may want to issue sudo iptables-save > myipconfig.txt  to save your current configuration before using this install to change it.

It makes changes to the running system, then saves them, and changes /etc/rc.local so the commands are executed at Linux boot time.

It asked Optional: Enter y to install all needed dependencies or enter n to decline.

I thought I had checked these, so I replied n.  I don’t know if it checks them and warns of any missing ones.

The installation complete message is not as documented.   The documentation says “If the package is installed successfully, the following output is displayed”

z1091-1-10.55.04.x86_64

I got

ii z1091 1.10.55.04 amd64 z1091, version 1.10.55.04, build date - 02/19/20 for Linux on Ubuntu 64bit

which is close enough.

Unzipping the files

Files  ending in .gz can be unzipped with gunzip.  The other files have to be decrypted and you need the dongle to do that.

The command

gunzip file.gz

takes the file, unzips it to file and deletes file.gz.  The option -k says do not delete the input file.

You can use the command

gunzip -c file.gz > /directory/file

the -c option says write to sysout and do not delete the input file.

To unzip all the files (this took a couple of hours to execute).

• you could issue gunzip *.gz  . You may want to check that the directory has only the zP&T files in it before executing the command.  Remember it will delete the .gz file afterwards.  (This helps save space).
• if you want to have the unzipped files on a different drive you could copy the .gz files to the drive then issue  gunzip *.gz in the directory.

Unzip and decrypting the RES files.

When I tried to unzip the *RES files using my colinpaice userid I got.  /usr/z1090/bin/Z1091_ADCD_install: error while loading shared libraries: libawsDiskItf.so: cannot open shared object file: No such file or directory.

I logged switched to the ibmsys1 userid, and followed the instruction in the documentation. I got

• /usr/z1090/bin/Z1091_ADCD_install ./A4RES1.ZPD ./A4RES1
• LIC hasp: * Communication error between API and local Sentinel License Manager : code=33

It took just over 4 minutes to unzip the SARES1 disk

Overall all

The overall process worked.  It took longer than I expected to get entitlement, and the hardware dongles.  I also have 3 dongles I cannot use, a large pile of cardboard, and two piles of CDs I don’t think I need.