Installing Gentoo on a IBM z/VM instance is more or less like on another architecture, except in booting the install environment and the networking setup. Patience is needed to understand how everything works.
I won't go in too much detail because if you have access to a z/VM and want to install Gentoo on it, you should have some experience.
This guide supposes you simply got access to a z/VM instance. You can also install Gentoo using another distribution, skipping the 'x3270' part.
To be able to install Gentoo, you'll need the following:
- Access to a z/VM instance
- A 3270 emulator(We'll be using the graphical part of net-misc/suite3270)
- A network connection
Setting up the z/VM environment for installing
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.
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 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.
Create a file called gentoo.parmfile with the following content:
If your DASD has the 0150 ID, then you need to put dasd=0150. If you have more than one DASD you can append the IDs of them to the dasd parameter, like dasd=0150,0151,0152, etc. That will translate, in the Linux environment, the 0150 DASD as /dev/dasda, 0151 as /dev/dasdb and so on...
Create a file called gentoo.exec with the following content:
/* REXX EXEC TO IPL GENTOO GNU/LINUX */ /* FOR S/390 FROM THE VM READER. */ /* */ 'CP CLOSE RDR' 'PURGE RDR ALL' 'SPOOL PUNCH * RDR' 'PUNCH GENTOO KERNEL * (NOHEADER' 'PUNCH GENTOO PARMFILE * (NOHEADER' 'PUNCH GENTOO INITRD * (NOHEADER' 'CHANGE RDR ALL KEEP NOHOLD' 'CP IPL 000C CLEAR'
Installing a 3270 emulator
For connecting to the console of the z/VM, you need a 3270 terminal emulator. On a Gentoo system, emerge net-misc/suite3270 with X support.
Copy the install images
For copying the install images to the z/VM instance, we'll use x3270's functionality.
Connect to your z/VM instance using x3270, then find which CMS disk is writable for your z/VM account executing Q DISK at the x3270 terminal and look for a "R/W" in the STAT column. Once it's clear what is your writeable disk, select File -> File Transfer. Mark Send to host and Host is VM/CMS.
First we're going to send the gentoo.exec and gentoo.params files. Select Transfer ASCII file and Record Format as Variable. Make sure Add/remove CR at end of line and Remap ASCII characters is marked as well. In Local File Name type the full path to the gentoo.exec file, and in Host File Name type GENTOO EXEC A1, replacing A1 with the disk you have write access to. Do the same with the gentoo.parmfile file, adjusting Local File Name accordingly and Host File Name to GENTOO PARMFILE A1.
Next, we're going to send the binary files netboot-ARCH-kernel-DATE, which is the kernel, and netboot-ARCH-initramfs-DATE which is the initramfs. Select Transfer binary file and Record Format as Fixed and type 80 in LRECL. Same as before, in Local File Name, type the full path to the gentoo file and in Host File Name type GENTOO KERNEL A1. For the gentoo.igz file, type GENTOO INITRD A1.
Here's a table of how you should transfer files:
|Local File Name||Host File Name||Type||Record Format||LRECL|
|gentoo.exec||GENTOO EXEC A1||ASCII||Variable||Empty|
|gentoo.params||GENTOO PARMFILE A1||ASCII||Variable||Empty|
|netboot-ARCH-kernel-DATE||GENTOO KERNEL A1||Binary||Fixed||80|
|netboot-ARCH-initramfs-DATE||GENTOO INITRD A1||Binary||Fixed||80|
Boot the install environment
Now, to boot into the install environment, type:
IPL CMS GENTOO
This should boot into the busybox-based install environment.
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:
- Setup the network in the install environment
- Initialize and format the DASD disks and mount them
- Download a stage3 and a portage snapshot
- Setup fstab
- Setup root password
- Configure hostname and networking (optional, but recommended)
- Enable SSH access (optional, but recommended)
- Enable serial console access
Setup the network in the install environment
In this guide we'll document the configuration of the network using the qeth module.
For using qeth, you need to know the read, write and data bus ID of your virtual network card. In this guide we'll use 0.0.600, 0.0.601 and 0.0.602.
echo 0.0.0600,0.0.0601,0.0.0602 > /sys/bus/ccwgroup/drivers/qeth/group
echo 0 > /sys/bus/ccwgroup/drivers/qeth/0.0.0600/layer2
echo 1 > /sys/bus/ccwgroup/drivers/qeth/0.0.0600/online
Now you should have the eth0 interface ready to be setup.
For configuring the static networking, use net-setup:
In this example, I have a 192.168.1.1/24 IP and my gateway is 192.168.1.254:
net-setup 192.168.1.1/24 192.168.1.254
Networking for something else than eth0
Unfortunately net-setup only wants to touch eth0 (Will try to fix that), so if your network ends up being anything else than eth0, this is what net-setup does:
/sbin/ifconfig eth0 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0
/sbin/route add -net default gw 192.168.1.254 netmask 0.0.0.0 metric 1
udhcpc -i eth0 -q
This part is important for the SSH daemon to work and must be done in both static and dynamic
/sbin/ifconfig lo 127.0.0.1
/sbin/route add -net 127.0.0.0 netmask 255.0.0.0 gw 127.0.0.1 dev lo
Its highly recommended to use SSH to finish the install, since it will be more comfortable and you have to use a text editor to finish the installation.
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
dasdfmt -f /dev/dasda --label=gentoo
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.
fdasd -a /dev/dasda -a -l gentoo
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.
mount /dev/dasda1 /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.
Extracting a stage3
tar xjpf stage3-s390x-latest.tar.bz2 -C /mnt/gentoo
Extracting a portage snapshot
Please note that it may take a while
tar xjpf portage-latest.tar.bz2 -C /mnt/gentoo/usr
Chrooting into your new system
To chroot into the real system we need to mount some directories.
mount -t proc none /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
Copy the /etc/resolv.conf file to the new system
cp -L /etc/resolv.conf /mnt/gentoo/etc
Finally, let's chroot into the new system
chroot /mnt/gentoo /bin/bash
Unfortunately, the permission in some character devices are wrong, so we need to fix them before we run emerge.
chmod 0666 /dev/null /dev/urandom
Edit the /etc/fstab file to look like this:
/dev/dasda1 / ext4 noatime 0 1
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:
# Set to the hostname of this machine hostname="s390"
Edit the /etc/conf.d/net file like this, to fit our example:
config_eth0="192.168.1.1/24" routes_eth0="default via 192.168.1.254" ccwgroup_eth0="0.0.0600 0.0.0601 0.0.0602" ccwgroup_opts_eth0="layer2=0"
Let's create some symlinks to start the network at boot
ln -sf /etc/init.d/net.lo /etc/init.d/net.eth0
rc-update add net.eth0 default
You have to adjust the following lines in the /etc/inittab:
# TERMINALS #c1:12345:respawn:/sbin/agetty 38400 tty1 linux #c2:2345:respawn:/sbin/agetty 38400 tty2 linux #c3:2345:respawn:/sbin/agetty 38400 tty3 linux #c4:2345:respawn:/sbin/agetty 38400 tty4 linux #c5:2345:respawn:/sbin/agetty 38400 tty5 linux #c6:2345:respawn:/sbin/agetty 38400 tty6 linux
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.
rc-update add sshd default
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:
rc-update del termencoding boot
rc-update del keymaps boot
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:
echo 'sys-kernel/gentoo-sources' > /etc/portage/package.accept_keywords
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.
zcat /proc/config.gz > .config
Now let's compile it and its modules
make && make modules && make modules_install
Once that is done, copy the kernel file to the /boot directory:
cp arch/s390/boot/image /boot/image
Edit the /etc/zipl.conf file like this, to fit our example:
[defaultboot] defaultmenu = menu [Gentoo] image = /boot/image target = /boot/zipl parameters = "dasd=0150 root=/dev/dasda1 rootfstype=ext4 TERM=dumb net.ifnames=0" :menu default = 1 prompt = 1 target = /boot/zipl timeout = 10 1 = Gentoo
Create the /boot/zipl directory
mkdir -p /boot/zipl
Now let's run zipl:
If everything went fine it should output something like this:
Using config file '/etc/zipl.conf' Building bootmap in '/boot/zipl' Building menu 'menu' Adding #1: IPL section 'Gentoo' (default) Preparing boot device: dasda (0120). Done.
Finishing the installation
Great, we're done. Let's exit from the chroot and umount the filesystem
umount /mnt/gentoo/sys /mnt/gentoo/proc /mnt/gentoo/dev/shm /mnt/gentoo/dev/pts /mnt/gentoo/dev /mnt/gentoo
And let's power off the machine:
Boot our installed system
Now, to boot our new installed system, we have to type into z/VM:
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.
Obviously you will get a warning that the SSH host key has changed, since the install environment has one SSH key and our new installation has another different. Delete the old SSH key in your .ssh/known_hosts file and try to SSH again.
This should get you a working Gentoo in z/VM. Enjoy!
- Dave Jones @ V/Soft Software(http://www.vsoft-software.com/) for providing us access to a z/VM system to document this procedure and his help.