IBM Z and LinuxONE - LinuxONE - Group home

The LinuxONE Community Cloud is a wonderful way to get a free Linux virtual machine running on a real IBM Z (or IBM LinuxONE) machine for up to 120 days. In principle you can re-sign up as many times as you want, but how'd you like to run the latest Linux distribution for IBM Z and IBM LinuxONE on a PC, Mac, or even ARM-based device (such as a Raspberry Pi)? Read on!

In April, 2020, Canonical released Ubuntu 20.04 LTS (Long Term Support) and the Fedora Community released Fedora 32. Both are available for the "s390x" processor architecture and thus run on IBM Z and IBM LinuxONE machines. There's some fairly good documentation available on how to install s390x Linux on QEMU (thanks to Astr0baby in particular), but now seems like a great time to provide this step-by-step guide that covers the basics. One important caveat is that using an emulator such as QEMU to run software compiled for one processor architecture on another processor architecture incurs performance overhead, often significant. However, for building cross-architecture software, functional testing, and educational purposes, it's viable. Also, please be aware that many features found on real IBM Z and IBM LinuxONE machines obviously won't be available on your PC or Mac, including recent processor instructions and cryptographic facilities.

Let's get started! You'll need the following ingredients:

1. A Linux distribution for the s390x architecture in ".iso" (CD/DVD) format. I initially selected Ubuntu 18.04.4 LTS and then performed an "in place" upgrade to Ubuntu 20.04 LTS. That worked well, but you can jump straight to Ubuntu 20.04 LTS now. You should be able to download the .iso image for s390x Ubuntu 20.04 LTS here, but the Ubuntu s390x Wiki provides additional links if you need them.
   
   
2. A PC, Mac, or other device running Microsoft Windows, x86 Linux, macOS, or some other operating system that can run QEMU. I recommend a device with a 64-bit processor and operating system for performance reasons (since s390x is also a 64-bit architecture, and then QEMU has a little less work to do) and to make more memory available to your s390x Linux guest. You'll also need some free disk (or flash) storage space somewhere, and 10 GB or more would be nice. Just for fun I chose a laptop that's nearly 12 years old. It runs 64-bit Windows 10 (1909) and has 2 GB of RAM. It's definitely not speedy, but it worked!
   
   
3. A relatively recent release of QEMU, which includes some KVM technologies. Most Linux distributors' repositories include QEMU, so you can install it easily that way. Stefan Weil provides precompiled QEMU binaries for Windows here, and I used the 64-bit QEMU 4.2 package. On macOS you can use Brew or MacPorts to install QEMU. Whichever way you install QEMU make sure it includes the qemu-system-s390x program since that's the one you'll definitely need.
   
   
4. A network connection. Often the Linux installation program will try to fetch updates over the network, and it's probably a good idea to test the network early on. (When prompted on Windows I granted QEMU sufficient firewall permission for outbound Internet access.)
   
   
5. A little patience. Typically the installation will take an hour or more to run, but you can check back every so often to see if the installation program is asking another question.
   
   
6. Both Telnet and SSH clients on the host device. On Windows PuTTY works well in both roles.

As mentioned, s390x Linux distributions running as QEMU guests perceive a KVM on IBM Z/IBM LinuxONE environment, which is nice because the console, disk, and network are all straightforward to understand and configure. In terms of machine model similarity QEMU emulates a subset of an IBM z13 (or first generation LinuxONE) machine, which is just good enough to run Ubuntu 20.04 LTS. Once you've assembled the ingredients and installed QEMU (add QEMU to your PATH for convenience if you wish) you can install practically any Linux distribution that supports KVM on IBM Z with these basic steps:

1. Create a disk image to hold your s390x Linux installation. Here's an example using the qemu-img command:
   
   qemu-img create -f raw ubuntu-run.raw 10G
   
   which creates a preallocated "raw" disk image that's 10 GB in size with the file name ubuntu-run.raw in the current working directory. You should also be able to use the "qcow2" image format if you prefer.
   
   
2. Mount the .iso image, locate the files initrd and kernel (examples: initrd.ubuntu and kernel.ubuntu), and copy them to the working directory. For example, on Microsoft Windows with the Ubuntu .iso you can simply use the File Explorer, right click/tap on the .iso image file, select "Mount," navigate to the boot directory, locate the two files, copy them, then "Eject" the .iso.
   
   
3. Using a text editor, prepare a batch file (or shell script) to launch QEMU with the correct parameters for Linux installation. Here's what I used for Linux's installation phase on a Microsoft Windows host in a single line batch file called linux-install.bat:
   
   qemu-system-s390x -machine s390-ccw-virtio -cpu max,zpci=on,msa5-base=off -serial telnet::4441,server -display none -m 1024 --cdrom ubuntu-18.04.4-server-s390x.iso -kernel kernel.ubuntu -initrd initrd.ubuntu -drive file=ubuntu-run.raw,format=raw
   
   Technically you don't have to put this long, single line command in a batch file or shell script, but I think it's best to do that so you can adjust parameters and re-run QEMU more easily if need be. There's quite a lot to explain here:
   
   (a) I added QEMU to my PATH, so qemu-system-s390x invokes QEMU's s390x architecture emulator program.
   (b) -cpu max,zpci=on,msa5-base=off does two things. First, it tells QEMU to emulate the highest processor generation it knows how and with a rudimentary IBM Z PCI bus simulation. It also suppresses a QEMU warning message about a missing cryptographic feature.
   (c) -serial telnet::4441,server tells QEMU to start up a telnet server running on port 4441 and to connect this server to the virtual serial console. That's how we can see kernel boot and console messages: Linux literally thinks it's talking to a hardwired serial terminal.
   (d) -display none basically means "this is a server," and it doesn't have a video display monitor.
   (e) -m 1024 tells QEMU to provide 1024 MB (1 GB) of RAM to the guest. That should be sufficient for installing Linux, and you might even be able to decrease this number if you need to. Since the 12 year old laptop I used has only 2 GB of RAM, I settled on 1 GB. Obviously you can increase this number to 2048 (2 GB) or more if you have the memory to spend.
   (f) The --cdrom parameter mounts the .iso to the guest, assuming the .iso image file is in the working directory. (You can include the partial or full path if you need to.) From the Linux guest's perspective the contents of the .iso image were accessible at /dev/vda. Obviously you can replace the Ubuntu 18.04.4 .iso image with the 20.04 image if you're using that.
   (g) The -kernel and -initrd parameters point to the two boot files I copied from the .iso image, and here too you can add partial or full paths if needed.
   (h) The -drive parameter points to the virtual disk image that I created with the qemu-img command.
   
   On Windows I didn't need administrative authority to run this QEMU command. If QEMU starts with no errors it'll pause until you connect the virtual console via Telnet. If you get an error then go back and check parameters, permissions, etc.
4. Start your Telnet client (e.g. PuTTY) on the host and connect to address 127.0.0.1 (the loopback address) and port 4441. As soon as you connect you should start seeing Linux boot messages as QEMU starts the boot process. If you don't, go back and check your configuration. If you see strange symbols then you're probably using a Telnet client that isn't emulating a "VT" terminal (e.g. VT-220), so try to fix that.
5. From this point it's just a straightforward, text mode Linux installation process. Here are a few comments, not necessarily in order:
   
   (a) The network driver is "virtio," and Layer 3 networking is sufficient (if asked).
   (b) Be careful not to confuse /dev/vda with /dev/vdb when you partition and format your virtual disk. The virtual disk is probably the larger one.
   (c) The installation program might offer to continue with a ssh connection, but you can just accept the offer and ignore it. The virtual serial console is fine.
   (d) You probably don't want to install any of the optional packages at this stage. You can always add them later. Even OpenSSH is optional since Ubuntu includes a basic ssh daemon regardless.
   (e) At the end of the installation the reboot process may take a particularly long time. Give it plenty of time if only to make sure everything is written to disk properly. You don't really want a simple reboot, though, since you're going to shut down QEMU and run it with some new parameters.
6. After you finish installing Linux you're now ready to run your new virtual installation. (Now would be a good time to make a backup of your virtual disk image file.) To run Linux after installing it you'll need a slightly different QEMU command, and this command should also be on a single line in its own batch file (e.g. linux-run.bat). Here's an example:
   
   qemu-system-s390x -machine s390-ccw-virtio -cpu max,zpci=on,msa5-base=off -smp 2 -serial telnet::4441,server -display none -m 1024 -drive file=ubuntu-run.raw,if=none,id=drive-virtio-disk0,format=raw,cache=none -device virtio-blk-ccw,devno=fe.0.0001,drive=drive-virtio-disk0,bootindex=1 -nic user,hostfwd=tcp::2222-:22
   
   I've made just a few changes here:
   
   (a) The -smp 2 parameter is optional but allows you to specify how many virtual processor cores QEMU should emulate, which could be more interesting after you've installed Linux. You probably shouldn't increase this number beyond the number of real processor cores you have on your host machine.
   (b) The -drive and -device parameters are reworked a bit to shift the virtual disk image into a boot position. You might want to tweak these parameters later.
   (c) The -nic parameter tells QEMU to expose port 2222 on the host side and map it to the guest's port 22. Port 22 is the typical ssh port, so that's how it's possible to connect to the Linux guest via ssh. The console is still available (Telnet on port 4441), and as before QEMU will pause and wait to start the guest until you connect via Telnet.
7. Run this new batch file, and if there are no QEMU error messages you can then connect again via Telnet to address 127.0.0.1 port 4441. If you start seeing Linux console messages, then all is well so far.
8. Once you get a login prompt in the console, try starting up a ssh client on the host (e.g. PuTTY), connecting to address 127.0.0.1 port 2222. Then you should be able to login via ssh.
9. Try testing the network again. For example, try checking for updates from the Linux distributor's repositories.
10. If you made it this far, congratulations! You now have a working s390x Linux guest running on your PC, Mac, or perhaps even Raspberry Pi. You might now want to remove the -serial parameter if you no longer need the console, and you can also make adjustments to the network configuration. Remember to backup working disk image files before making big changes.

If you have questions or success reports, please post a comment. Have fun!