Gentoo Logo
Gentoo Logo Side

s390 Installation Document


1. Before you Begin

Before you Begin 

This guide assumes that you are installing from an existing Linux distribution. It also assumes that you are comfortable using tools such as zipl,dasdfmt and fdasd.

2. Selecting your Installation File

Stage 1 

When you begin an installation from a Stage 1 Tarball you will have the ability to completely customize your Gentoo Linux system by controlling the optimization settings and build-time functionality on your system. The downside of using a Stage 1 Tarball is that it takes a long time to finish the installation and if you do not tweak any of the settings you will not gain anything.

Stage 2 

You will have some ability to customize your installation and tweak many settings if you start your installation from a Stage 2 tarball. It's faster than installing from a Stage 1 tarball because you don't need to bootstrap. It also not the fastest way to installGentoo and you have to accept the optimizations that were chosen for the bootstrap.

Stage 3 

If you use a Stage 3 tarball to install Gentoo you are using the fastest installation method possible. You will also be able to use prebuilt packages if they are available. The downside of installing from a Stage 3 tarball is that you cannot tweak the basesystem, because it has already been built.

3. Preparing the Dasd


Here is a list of things that you need to keep in mind when you are partitioning your Dasd using fdasd.

  • You need to use dasdfmt before you can use your dasd
  • Swap Partitions cannot Exceed 4 Gb
  • 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

Here's an example of where dasdfmt was used to initialize our 200 Disc.

Code listing 3.1

#dasdfmt -f /dev/dasd/0200/disc --label=gentoo

There are several different modes to run fdasd in. The first mode is an interactive mode. There is also a mode that will automatically create one parition on the disk. The third mode sets the partitions according to a configuration file that you specifiy.

The following example uses the -a option to create one partition on the system's 200 dasd. It will occupy all the space on the disc. It also specifies the volume label with the -l option.

Code listing 3.2

# fdasd -a /dev/dasd/0.0.0200/disc -a -l gentoo


There are several filesystems that are commonly used on Linux. They are ext2, ext3, ReiserFS, XFS and JFS. These are all available under Gentoo S390 so you should select the filesystem that best fits your needs.

Code listing 3.3: Creating an ext2 Filesystem

#mke2fs /dev/dasd/0.0.0200/part1

Code listing 3.4: Creating an ext3 Filesystem

#mke2fs -j /dev/dasd/0.0.0200/part2

Code listing 3.5: Creating a ReiserFS Fileystem

#mkreiserfs /dev/dasd/0.0.0201/part1

Code listing 3.6: Creating an XFS Filesystem

#mkfs.xfs /dev/dasd/0.0.0201/part2

Code listing 3.7: Creating a JFS Filesystem

#mkfs.jfs /dev/dasd/0.0.0202/part1

Code listing 3.8: Creating a Swap Partition

#mkswap /dev/dasd/0.0.0202/part2

Now you need to activate the swap partition and mount the filesystems.

To activate the swap partition, use swapon.

Code listing 3.9: Activating the swap partition

#swapon /dev/dasd/0.0.0202/part2

Now you will need to create the mount directories for each partition that you have just created. After the directories have been created you will be able to mount the partitions using the mount command.

Code listing 3.10: Mounting Partitions

#mkdir /mnt/gentoo/boot
#mkdir /mnt/gentoo/proc
#mkdir /mnt/gentoo/var
#mount /dev/dasd/0.0.0200/part2 /mnt/gentoo
#mount /dev/dasd/0.0.0200/part1 /mnt/gentoo/boot
#mount /dev/dasd/0.0.0201/part2 /mnt/gentoo/var
#mount -t proc none /mnt/gentoo/proc

4. Unpacking Tarballs and Entering Chroot

Unpacking your tarball 

Now you must unpack the stage tarball that you have chosen.

Code listing 4.1: Unpacking the stage tarball

#cd /mnt/gentoo
#tar -xvjpf /path/to/stage/tarball/stage*.tar.bz2

Note: You can ignore any "No such file or directory" warnings regarding ./proc. Also, the message "Error exit delayed from previous errors" can be ignored as well.

Entering the Chroot 

Before you enter your chrooted envrinoment there are several things that you will need to do. You will need to set your compile options, setup your DNS information, select a mirror, and then update portage.

To set your compile options you need to edit /mnt/gentoo/etc/make.conf. A list of available gcc options for the s390 Architecture is available here.

To setup your DNS information you will need to copy your /etc/resolv.conf to the chroot.

Code listing 4.2: Copying your /etc/resolv.conf

#cp -L /etc/resolv.conf /mnt/gentoo/etc

Now it is time to enter your chroot envirnoment.

Code listing 4.3: Entering the chroot

#chroot /mnt/gentoo /bin/bash
Regenerating /etc/
#source /etc/profile

Now you will need to update your portage tree before you continue with the installation.

Code listing 4.4: Updating Portage

#emerge sync
If you are unable to use rsync you should use webrsync

Ignore any warning messages that say that there is an update to portage available. Portage will be updated later on in the installation.

5. Progressing through the Installation

Progressing from Stage 1 to Stage 2 

If you decided to start the installation from a Stage 1 tarball this is where you need to begin. If you started from a Stage 2 or a Stage 3 tarball you can start in one of the other sections.

You need to enter the following lines to start bootstrapping the system. This will take a long time to complete so after you start the bootstrapping process you can go and do something else.

Code listing 5.1: Starting the Bootstrap Process

# cd /usr/portage
# scripts/

You can also have the bootstrap process download all of the source code that it needs first. To do this run with the -f option

Progressing from Stage 2 to Stage 3 

To progress from Stage 2 to Stage 3 you will need to emerge the base system packages for your Gentoo system. Before you begin you can see what packages will be installed on your system by running the following command.

Code listing 5.2: Seeing what emerge system will do

#emerge -p system

Now you can start building the base system packages. This will also take a very long time to complete so you should go find something else to do for a while

Code listing 5.3: Starting emerge system

#emerge system

Installing a Kernel 

Now we will go through and install and then compile a kernel with the necessary options. The first thing that is required is to set the system's time zone. Then you need to install the source code, configure the kernel and then compile the kernel.

Setting the time zone is done by creating a symlink to /etc/localtime.

Code listing 5.4: Setting the time zone

# ln -sf /usr/share/zoneinfo/GMT /etc/localtime

Now we need to install the kernel sources. The only kernel that is currently supported by Gentoo's S/390 Port is the 2.6.5 development-sources. If you want to you can try a different kernel by adding the s390 keyword to the ebuild. To install the kernel source all you need to is emerge them.

Code listing 5.5: Installing Kernel Sources

# emerge development-sources

Now we need to configure the options that are required for our kernel. Here's a list of required options for S/390 users.

Code listing 5.6: Selecting experimental code/drivers

Code maturity level options --->
	[*] Select only drivers expected to compile cleanly

Code listing 5.7: Base Setup

Base Setup -->
	[ ] 64 Bit Kernel
	    Processor type (IBM eServer zSeries model z800 and z900) --->
		(X) IBM eServer zSeries model z800 and z900
	<*> QDIO Support

	[*]Builtin IPL record Support

Code listing 5.8: Block Devices

Block Devices --->
	<*> Support for DASD devices

Code listing 5.9: Selecting Filesystems and Partition Types

File Systems -->
	<*> Second extend fs support
	<*> Ext3 journalling file system support	
	Pseudo filesystems --->
		[*] /proc file system support
		[*] /dev file system support (OBSOLETE)
		[*] Automatically mount at boot
		[*] /dev/pts Extended Attributes
		[*] Virtual memory file system support (former shm fs)
	Partition Types --->
		[*] Advanced partition selection
		[*] IBM disk label and partition support		

To begin configuring the kernel you need to run make menuconfig.

Code listing 5.10: Executing Make menuconfig

# cd /usr/src/linux
# make menuconfig

Now its time to compile the kernel.

Code listing 5.11: Compiling the kernel

# make && make modules_install

When the kernel is done compiling, copy the kernel image to /boot:

Code listing 5.12: Installing the kernel

# cp arch/s390/boot/image /boot/kernel-2.6.5-gentoo
# cp /boot/
# cp .config /boot/config-2.6.5-gentoo
# chmod +x /boot/image

The kernel modules that should be loaded automatically at boot should be placed in /etc/modules.autoload.d/kernel-2.6. To view all available kernel modules, run the following find command.

Code listing 5.13: Viewing available kernel modules

# find /lib/modules/<kernel version>/ -type f -iname '*.o' -or -iname '*.ko'

To automaticcaly load the qeth module, edit kernel-2.6 file and enter the module name in it.

Now run modules-update to commit the changes to /etc/modules.conf.

Configuring your System 

One of the first things that you need to configure is your /etc/fstab . This file contains all of the information about the partitions that are mounted when the system is booted.

Code listing 5.14: An example /etc/fstab

/dev/dasd/0.0.0201/part2             /boot           ext2            noauto,noatime          1 1
/dev/dasd/0.0.0202/part1        /               ext3            noatime                 0 0
/dev/dasd/0.0.0201/part1 /var/www/localhost/htdocs/ ext3
/dev/dasd/0.0.0202/part2             none            swap            sw                      0 0
none                    /proc           proc            defaults                0 0
none    /sys    sysfs    defaults    0 0
none                    /dev/shm        tmpfs           defaults                0 0

Choosing a System Logger 

At this point you will need to select a system logger. The available choices are metalog, syslog-ng, and sysklogd. Metalog is highly configurable, syslog-ng is very powerfull because it comes with a great default configuration, and sysklogd is a traditional system logger.

When you chose a system logger you should use emerge to install it. Then you should add it to the default runlevel using rc-update. This example installs metalog.

Code listing 5.15: Installing a System Logger

# emerge metalog
# rc-update add metalog default

Filesystem Tools 

Depending on what file systems you are using, you need to install the necessary file system utilities (for checking the filesystem integrity, creating additional file systems etc.).

The following table lists the tools you need to install if you use a certain file system:

File System Tool Install Command
XFS xfsprogs emerge xfsprogs
ReiserFS reiserfsprogs emerge reiserfsprogs
JFS jfsutils emerge jfsutils

Networking Configuration 

The first thing that we need to do is to setup the network devices. Depending on your type of network, you will need to create several configuration files. Device numbers are denoted 0.0.abcd to comply with the naming scheme for 2.6 kernels. This device number is equivalent with 0xabcd. The supported network devices are:

  • lcs osa
  • qdio osa
  • HiperSockets
  • Channel to Channel and Escon
  • IUCV
  • Claw (2.4 series only)

/etc/chandev.conf is used in the configuration of the 2.4 series kernels, and /etc/ccwgroup.conf is used in the configuration of the 2.6 series kernels.

For lcs osa token ring networks, and lcs osa ethernet networks You need to know your read device, write device and relative port number, f.e. read device 0.0.fd00, write device 0.0.fd01, a relative port number 0 will use auto-detection.

Code listing 5.16: /etc/chandev.conf


Code listing 5.17: /etc/ccwgroup.conf

		group lcs 0.0.fd00 0.0.fd01
		portno 0

Your network devices will be tr0 for token ring devices, and eth0 for ethernet devices.

For qdio osa token ring networks, and qdio osa ethernet networks you need to know your read, write, and data device and your portname,for example .0.fd00, 0.0.fd01, 0.0.fd02 and OSAPORT

Code listing 5.18: /etc/chandev.conf


Code listing 5.19: /etc/ccwgroup.conf

	group qeth 0.0.fd00 0.0.fd01 0.0.fd02
	portname OSAPORT

Your network devices will be tr0 for token ring devices, and eth0 for ethernet devices.

For Hipersockets You need a read, a write, and a data device, for example 0.0.fd00, 0.0.fd01, 0.0.fd02

Code listing 5.20: /etc/chandev.conf


Code listing 5.21: /etc/ccwgroup.conf

	group qeth 0.0.fd00 0.0.fd01 0.0.fd02

Your network device will be hsi0

For channel to channel and escon channel connections you need a read and a write device, for example 0.0.fd00, 0.0.fd01.

Code listing 5.22: /etc/chandev.conf


Code listing 5.23: /etc/ccwgroup.conf

	group ctc 0.0.fd00 0.0.fd01

Your network device will be ctc0. Please note that this is a point to point connection, you can't assign a network/broadcast address to the device and you need to supply the IP of your peer.

For IUCV Networking you need the name of the guest you want to connect to, for example guest2.

Code listing 5.24: /etc/modules.conf

	options netiucv iucv=guest2

Your network device will be iucv0. Please note that this is a point to point connection, you can't assign a network/broadcast address to the device and you need to supply the IP of your peer.

For CLAW you need to know the read and write devices, the host and adapter name and the API type, for example the device 0xfd00 and 0xfd01, host linux, adapter rs6k, and the TCPIP API.

Note: CLAW is only available for the 2.4 series of kernels

Code listing 5.25: /etc/chandev.conf


Your network device will be claw0, the configuration of the network device depends on your router's settings.

Now you need to edit /etc/conf.d/net to setup networking for your Gentoo system. Is uses a straightforward yet not intuitive syntxax. The first thing that you need to to is to opne /etc/conf.d/net with a text editor.

Code listing 5.26: Opening /etc/conf.d/net for editing

# nano -w /etc/conf.d/net

The first variable you'll find is iface_eth0. It uses the following syntax:

Code listing 5.27: iface_eth0 syntax is

ifface_eth0="<your ip address> broadcast <your broadcast address> netmask <your netmask>

Here's an example that uses a static network.

Code listing 5.28: Example for /etc/conf.d/net/

iface_eth0=" broadcast netmask"

To have your network devices automatically start at boot you need to add them to the default runlevel.

Code listing 5.29: Adding net.eth0 to the default runlevel

# irc-update add net.eth0 default

If you have several network interfaces, you need to create the appropiate net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code listing 5.30: Creating extra initscripts

# cd /etc/init.d
# ln -s net.eth0 net.eth1
# rc-update add net.eth1 default

Now we will setup some basic networking options such as the the hostname, and the domainname.

Code listing 5.31: Setting the host and Domain Name

# echo tux > /etc/hostname
# echo homenetwork > /etc/dnsdomainname
# rc-update add domainname default

Configuring Zipl 

Zipl the bootloader for S/390 is available in the s390-tools package.The file /etc/zipl.conf is used to configure zipl. You can think of it as lilo for s390. Basically, zipl can be used without a zipl.conf, however a proper zipl.conf will make life easier for you and save you a lot of typing.

The zipl.conf configuration file is split in different sections, all starting with [name]

Within such a section you can define different parameters you had to pass to zipl on the command line otherwise. You can then just pass the name of the section you have defined to zipl and it will use the values found there:

Code listing 5.32

#zipl name

If you define a section defaultboot, you can even define which section to use if you didn't provide a section name at all:

Code listing 5.33



Possible values you can set in such a section include:

Value Description target directory to install zipl files to image kernel image ramdisk initrd parameters parameters to pass to the kernel during ipl dumpto device for dump (see lkcdutils)

For more advanced options, please see zipl.conf(5)

To setup zipl, the following steps are needed:

Create necessary directories and files

You should create the following directories, assuming you want to install vanilla-sources-2.4.21

Code listing 5.34

# mkdir /boot/zipl
# mkdir /boot/vanilla-sources-2.4.21
# ln -s /boot/vanilla-sources-2.4.21 /boot/kernel
# ln -s kernel/ /boot/
# ln -s kernel/Kerntypes /boot/Kerntypes 

Copy your compiled kernel

Code listing 5.35

# cp arch/s390/boot/{image,*.boot} /boot/kernel
# cp /boot/kernel
# cp Kerntypes /boot/kernel

Create a zipl.conf. It is assumed that /dev/dasd/0.0.0200/disc1 is your root and /dev/dasd/0.0.0201/disc1 is used for dumps. Your /etc/zipl.conf should look something like this.

Code listing 5.36


	parameters="dasd=0200,02001 root/dev/dasd/0.0.0200/disc1"


To install the boot loader with your shiny new zipl.conf you just have to run:

Code listing 5.37


If you also want to prepare your dump disc (yes, you want that), you should run the following command:

Code listing 5.38

# zipl dump

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated 12 May 2004
Michael McCabe
s390 Developer

Jochen Eisinger
s390 Contributor/Tester

Summary: This guide outlines the procedure of installing Gentoo Linux on an IBM s390 Mainframe.

Donate to support our development efforts.

The Gentoo Linux Store

php|architect is the monthly magazine for PHP professionals, available worldwide in print and electronic format. A percentage of all the sales will be donated back into the Gentoo project.

Tek Alchemy

Tek Alchemy offers dedicated servers and other hosting solutions running Gentoo Linux.

DDR Memory at

Purchase RAM from and a percentage of your sale will go towards further Gentoo Linux development.

Win4Lin at NeTraverse

Win4Lin from NeTraverse lets you run Windows applications under Gentoo Linux at native speeds.

Copyright 2001-2003 Gentoo Technologies, Inc. Questions, Comments, Corrections? Email