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

Partitions 

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.

#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.

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

Filesystems 

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.

#mke2fs /dev/dasd/0.0.0200/part1

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

#mkreiserfs /dev/dasd/0.0.0201/part1

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

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

#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.

#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.

#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.

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

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.

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

Now it is time to enter your chroot envirnoment.

#chroot /mnt/gentoo /bin/bash
#env-update
Regenerating /etc/ld.so.cache...
#source /etc/profile

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

#emerge sync
If you are unable to use rsync you should use webrsync
#emerge-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.

# cd /usr/portage
# scripts/bootstrap.sh

You can also have the bootstrap process download all of the source code that it needs first. To do this run bootstrap.sh 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.

#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

#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.

# 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.

# 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 maturity level options --->
	[*] Select only drivers expected to compile cleanly

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

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

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.

# cd /usr/src/linux
# make menuconfig

Now its time to compile the kernel.

# make && make modules_install

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

# cp arch/s390/boot/image /boot/kernel-2.6.5-gentoo
# cp System.map /boot/System.map-2.6.5-gentoo
# 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.

# 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.

/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.

# 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:

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.

		noauto
		lcs0,0xfd00,0xfd01,0,0

		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

		auto
		qeth0,0xfd00,0xfd01,0xfd02
		add_parms,0x10,portname:OSAPORT

	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

		noauto
		qeth0,0xfd00,0xfd01,0xfd02

	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.

	noauto
	ctc0,0xfd00,0xfd01

	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.

	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.

	noauto
	claw0,0xfd00,0xfd01,linux,rs6k,TCPIP

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.

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

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

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

Here's an example that uses a static network.

iface_eth0="192.168.0.2 broadcast 192.168.0.255 netmask 255.255.255.0"
gateway="eth0/192.168.0.1"

To have your network devices automatically start at boot you need to add them 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:

# 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.

# 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:

#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:

[defaultboot]
	default=name

	[name]

Possible values you can set in such a section include:

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

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

Copy your compiled kernel

# cp arch/s390/boot/{image,*.boot} /boot/kernel
# cp System.map /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.

[defaultboot]
	default=ipl

	[ipl]
	target=/boot/zipl
	image=/boot/kernel/image
	parameters="dasd=0200,02001 root/dev/dasd/0.0.0200/disc1"

	[dump]
	target=/boot/zipl
	dumpto/dev/dasd/0.0.0201/disc1

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

#zipl

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

# zipl dump