S390/Hercules

Overview
Installing Gentoo on a hercules...etc

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


 * A machine that is able to run Hercules
 * Hercules, the emulator
 * A network connection
 * iptables if you want to add networking to hercules

Overview
For installing Gentoo, we're going to transfer the installation files...

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.

Downloading the installation images
Once you've made up your choice, you can now download the needed files from the mirrors in the experimental directory, blablabla...

Adjusting boot parameters for the installation image
One of the files you've downloadesomething.params'gentoo.params''. You need to edit this file and adjust the dasd=xxx parameter according to your z/VM environment.

If your DASD has the 0190 ID, then you need to put dasd=0190. If you have more than one DASD you can append the IDs of them to the dasd parameter, like dasd=0190,0191,0192, etc.

That will translate, in the Linux environment, the 0190 DASD as /dev/dasda, 0191 as /dev/dasdb and so on...

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

Download the files from http:// to the rdr directory.

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)

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 4818 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

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/net file like this, to fit our example:

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

Kernel
We have to build a kernel first. Let's emerge a kernel source.

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 we emerge gentoo-sources, we have to do:

Once you've done that, we'll do:

Once that is done, we should have in /usr/src/linux the kernel sources, so let's cd into that directory.

We need a kernel configuration file. To make sure we are able to boot our Hercules VM we'll use the kernel configuration from the installation environment.

Now let's 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:

Now let's run zipl:

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

Boot our installed system
How to boot...