S390/Hercules

Overview
This guide is about installing Gentoo in a emulated S390 machine using Hercules.

Requirements
To be able to install Gentoo, you'll need the following:


 * A machine that is able to run Hercules
 * Hercules, the emulator (app-emulation/hercules in Gentoo)
 * A network connection
 * iptables if you want to add networking to hercules
 * In this case you'll also need a kernel with TUN/TAP support (CONFIG_TUN=y/m)

Overview
For installing Gentoo, we're going to need to download some files for the installation environment. Once we boot into the installation environment, we'll be able to install Gentoo.

Keep reading.

Choosing the userland
Before going further with the process, we have to choose which userland we want to install.

In Gentoo we provide two userlands: a 31-bit one, which in the Linux on zSeries is named as s390 and a 64-bit one, which in the Linux on zSeries is called s390x.

Create the work directory
Let's create a directory where our VM will be located, so we can put in there all the files we need. For example, /home/user/hercules.

Create the following directories: dasd, rdr and prt

Downloading the installation images
Once you've made up your choice of userland, you can now download the needed files from the mirrors. In the s390 autobuilds directory, this means releases/s390/autobuilds/, inside the directory with the last date, there should be two files: netboot-ARCH-kernel-DATE and netboot-ARCH-initramfs-DATE.

ARCH should be either s390 or s390x, and DATE should be the date of the build. So choose if you want to download s390 or s390x, select one of them depending in the choice you made in the previous step, whether you want 31bit or 64bit. In the example we'll use s390x. Once you've made your choice, download the files and put them into the rdr directory.

Create a file called gentoo.parmfile with the following content:

And put into the rdr directory as well.

Setup the hercules environment
Create a configuration file for hercules, let's call it s390x.cnf with this content:

From the first part, the important parameters are CPUMODEL, which specifies which kind of machine we are emulating. Note that Hercules doesn't support all the machines. MAINSIZE the RAM quantity you want to use for the VM. NUMCPU is the number of cores you want the VM to have. There are some reports in Debian that Hercules doesn't work well with a high quantity of cores(more than 4)

Adjust the reader part with the filenames of the files you've downloaded.

The other important part is the last line, which defines the networking, the first IP is the one the VM will have while the second is the one the host machine will have.

Create the disks
Go into the dasd directory and create the disks. In this guide, we'll use one partition for everything.

The 6963 is the number of cylinders. In this type of storage, each cylinder has 15 tracks per cylinder, and 56832 bytes per track, therefore one cylinder equals to 0.85MBytes. So if you wanted to create a 8GB disk, you should do 8192 * 0.85 = 6963 rounded.

Run Hercules
Let's go back to our root work directory and run hercules:

You can ignore the "tun0: Operation not supported" message.

Setup networking in the host machine with iptables
In another console, setup the networking.

Boot the Gentoo installation environment
Let's start the Gentoo installation environment, inside Hercules type:

It may take a while until you get a shell prompt, since it has to emulate all the code.

If everything went well, you should see something like this:

Great, we have our installation environment ready!

Typing into the shell
In Hercules, if you want to type into the shell, you have to use a. (dot) before the command, for example:

will run uptime in the shell.

Setup the networking in the emulated system
Okay, we have the networking setup in the host system, but we have to configure it in the emulated machine as well. We'll use the networking to be able to ssh into the install environment, after all typing the commands with a dot in front and the Hercules console isn't very comfortable.

Inside Hercules, type:

We also need to setup the DNS.

This should make the network functional.

Setup a password and ssh into the emulated machine
Last step before ssh'ing into the machine is setup a password:

Great, now let's ssh into the machine from our host machine, in this example the emulated machine should have the IP 10.1.1.2

type the password you've just set and now we should be inside the install environment!!!

Let's proceed with the installation.

Overview
We now have an installation environment where we can prepare our Gentoo s390 system.

What we'll have to do to setup our installation is:


 * 1) Initialize and format the DASD disks and mount them
 * 2) Download a stage3 and a portage snapshot
 * 3) Setup fstab
 * 4) Setup root password
 * 5) Configure hostname and networking (optional, but recommended)
 * 6) Enable SSH access (optional, but recommended)
 * 7) Enable serial console access

Initializing and formatting the DASD disks
If you haven't formatted yet your DASD disks outside of Linux, you can do that now. Here are some informations:


 * You need to use dasdfmt before you can use your DASD
 * Swap Partitions cannot exceed 4GiB
 * A maximum of three partitions can be created on a physical volume
 * No gaps should be left between partitions
 * There is no tool for moving or resizing partitions
 * Before creating any partitions, you need to initialize the disks. You can do that with dasdfmt.

We initialize the first partition

For creating partitions, we'll use fdasd. There are several different modes to run fdasd in. The first mode is an interactive mode. You can simply do that by running fdasd /dev/dasda.

There is also a mode that will automatically create one partition on the disk. To keep the setup simple, we'll do that.

Now we'll have one partition, /dev/dasda1, which we can format with the known Linux filesystems. In our case, we'll format this partition with ext4.

Now let's mount this partition on /mnt/gentoo.

And let's change to the mounted directory

Downloading a stage3
Remember the choice you made before between 31-bit s390 and 64-bit s390x? You have to download a stage3 for the choice you've made before from your favorite mirror.

Chrooting into your new system
To chroot into the real system we need to mount some directories.

Copy the /etc/resolv.conf file to the new system

Finally, let's chroot into the new system

Fix permissions
Unfortunately, the permission in some character devices are wrong, so we need to fix them before we run emerge.

Setup fstab
Edit the /mnt/gentoo/etc/fstab file to look like this:

Setting the default root password
This is the most important part of the installation. As without the root password we won't be able to login!

For setting the password, simply run passwd

Setup hostname and networking
Edit the /etc/conf.d/hostname file to adjust the hostname:

Edit the /etc/conf.d/net file like this, to fit our example:

Let's create some symlinks to start the network at boot

Adjust inittab
You have to adjust the following lines in the /etc/inittab:

In other words, you have to comment the tty1-6 lines.

Enabling SSH access
We add sshd to the startup of our system so we can access our system using ssh.

Remove errors from boot process
There are two init scripts that in our s390 machine aren't going to work: termencoding and keymaps. The failures will show up as a failures in the console.

To avoid the useless messages, because they aren't going to work in our machine, let's remove them from the boot process:

Kernel
To continue, kernel has to be built.

Unfortunately s390 is nowadays an unstable arch in Gentoo, so this means that some packages aren't stable. One of those packages is gentoo-sources. So before emerge gentoo-sources, allow all keywords:

Next, install the sources:

Once that is done, the kernel sources will exist in. Change into that directory:

A kernel configuration file is necessary. To ensure the ability to boot the Hercules VM, use the kernel configuration from the installation environment:

Now compile it and its modules:

Once that is done, copy the kernel file to the /boot directory:

Bootloader
Edit the /etc/zipl.conf file like this, to fit our example:

Create the /boot/zipl directory

Now let's run zipl:

If everything went fine it should output something like this:

Finishing the installation
Great, we're done. Let's exit from the chroot and umount the filesystem

And let's power off the machine:

Boot our installed system
Now, to boot our new installed system, we have to type into Hercules:

If everything went successfully, we should see the kernel booting and after a few minutes, the login prompt.

If we configured SSH properly, we should be able to SSH into it.

Procedure for booting our VM in a fresh booted system
This would be the procedure for booting the VM in a fresh booted system, with clear iptables rules, etc...

cd into our work directory

Run hercules:

In another console, setup iptables:

Run the VM in hercules:

And that should be it.

Have fun!

Issues
These are some issues when running hercules:

Reboot doesn't work
Rebooting doesn't seem to work. When you reboot, hercules will start displaying some messages like:

The only way I have found to stop these messages and boot again is with the following commands:

Unable to boot the install environment after issuing 'ipl 120'
I have found that if you have been running your system with 'ipl 120', after stopping it and issuing 'ipl c', hercules answers:

To fix this, you need to reinitialize the card reader, you can do that with:

And then you can run ipl c again.

Tips and tricks

 * To power off the machine when you can't login, type ssd into the hercules command line. It should send a shutdown signal to the machine.