Installing Debian GNU/Linux under the Hercules emulator

Contents

Disclaimer
Maintenance Log
Introduction
Preparing the Host System
     Networking Changes
          ifupdown vs. network-manager
          Static vs. Dynamic IP Address
          IP Forwarding
     Security Considerations
          Changes to Program Privileges
          Changes to udev
     UTF-8 Character Mapping
Router Reconfiguration
Configuring Hercules
Installing Debian
Init System Changes
     Changes for sysvinit
     Changes for systemd
Multiple Instances of Hercules on the Same Host System
Conclusion

Disclaimer

This is not an official Debian site.  The author is not a member of the Debian s390x port team.  The author is not a member of the Debian installer team.  The author is not a member of the Debian Hercules team.  The author is not a member of the upstream Hercules team.  This document details the author's experiences and recommendations with regard to installing and using Debian GNU/Linux for the s390x port under the Hercules emulator.  All opinions expressed are those of the author and do not necessarily represent the opinions or official positions of the Debian project, the Hercules developers, or any other organization or individual.  This information is presented in the hope that it will be useful, but without any warranty or guarantee of any kind.  This information is presented free of charge, free of support, free of service, and free of liability.  Take this information with as many grains of salt as you think it's worth; and use it, if you choose to do so, entirely at your own risk.  The author hereby explicitly places this material in the public domain.  All trademarks, registered trademarks, service marks, etc., are the property of their respective owners.

Maintenance Log

Introduction

There is an open source program called Hercules, which is packaged for Debian in a package called hercules, which can emulate an IBM z/Architecture mainframe (s390x).  The Hercules program can run under Debian GNU/Linux on any hardware platform supported by Debian GNU/Linux, such as i386 or amd64.  (Hercules is also available for other GNU/Linux distributions, as well as other operating systems, including some versions of Windows®.)

You may find that the Hercules emulator is too slow for useful production mainframe workload.  The emulation layer simply adds too much overhead.  (This is especially true if you are trying to emulate a 64-bit mainframe on a 32-bit hardware platform, such as i386.  Such a thing is possible, but it really adds to the overhead.)  Furthermore, IBM does not normally license their proprietary 64-bit mainframe operating systems, such as z/OS®, z/VM®, or z/VSE®, to run on anything other than IBM mainframe hardware.  However, Hercules may be useful for software developers who need to support the s390x hardware platform in a GNU/Linux environment but cannot afford to buy an IBM mainframe for testing purposes.  (There are no licensing issues for running GNU/Linux under the Hercules emulator, since GNU/Linux is free software.)

Since the IBM Redbooks do not even mention the Hercules emulator, some details are provided here for installation of Debian GNU/Linux in the Hercules environment.

Historically, mainframes have had their performance measured in "MIPS".  Originally, MIPS was "Millions of Instructions Per Second".  Exactly what an "instruction" is, however, has become less clear as the physical architecture of mainframes has evolved.  IBM has historical benchmarking software that they use to calculate the "MIP" ratings of their processors.  Hercules calculates a "MIP" rating while it is running, but it doesn't seem to be very useful when comparing Hercules to a real mainframe.  As an example, I have a Hercules system which rates approximately equal to a low-end z/Architecture mainframe in terms of its "MIP" rating, but performance is vastly different.  As an example, a typical upgrade of Debian testing, i.e.
 

     apt-get update
     apt-get upgrade
     apt-get clean
     apt-get --purge dist-upgrade
     apt-get clean
     apt-get --purge autoremove
     aptitude forget-new
     aptitude keep-all

with one month between upgrades, normally takes about 20 minutes or less on a real mainframe.  The same task on my Hercules system takes the better part of a day.  So the MIP ratings can't really give any meaningful comparison.  I/O speed is not rated, and that's the rate-determining step in most cases.  Real mainframe I/O is much faster than Hercules emulated I/O in every scenario I've ever seen.

Preparing the Host System

You will want to use the fastest and most powerful host system you can get your hands on, since Hercules emulation adds so much overhead.  You want a fast processor, lots of RAM, and lots of disk space.  And you want, if possible, 64-bit hardware running a 64-bit operating system.  For example purposes, a home networking environment is assumed: a cable or DSL modem, into which is plugged a home router, into which are plugged several home computers, one of which is the host system for Hercules.  It is also assumed that the host system for Hercules runs the Debian GNU/Linux operating system.  In addition, due to bugs in binary floating point emulation in Hercules 3.07, I highly recommend Hercules 3.10 or later, which is only available in Debian stretch (9.x) or later.  Therefore, I recommend that the host system be Debian stretch or later.

Networking Changes

The first thing you will need to do to the host system for Hercules is to make some networking changes to it.

ifupdown vs. network-manager

If you have installed the default Debian desktop environment, GNOME, you probably have network-manager installed.  Other desktop environments, such as XFCE, also use network-manager.  And if you are running the default configuration of network-manager and ifupdown provided by the Debian installer, it typically allows ifupdown to manage only the local loopback interface (lo), while allowing network-manager to manage everything else, including the wired ethernet interface.  (Historically, the wired ethernet interface name was usually eth0, and that is the name used in this document for reference purposes.  If you use the new udev-provided persistent network interface names, it may be something like enp0s1.  Substitute the name of your interface throughout this document wherever you see eth0.)  We are going to give control of the wired ethernet interface back to ifupdown. 

Note: all commands in this document are assumed to be issued by the root user unless otherwise noted.

Edit the file /etc/network/interfaces.  If the description for the wired ethernet interface is present at all, it probably looks something like this:
 

     # The primary network interface
     allow-hotplug eth0
     #NetworkManager#iface eth0 inet dhcp

You need to do three things: (1) Remove "allow-hotplug eth0" from the file.  (2) Uncomment the iface statement which was commented out by the installation of network-manager.  (3) Add an "auto eth0" statement.  The resulting section of the file should now look like this:
 

     # The primary network interface
     auto eth0
     iface eth0 inet dhcp

If /etc/network/interfaces does not currently contain a definition for the primary network interface, then create one as above.  If there is a definition for the device in network-manager, delete it.  Make sure that network-manager will not try to manage ifupdown-controlled interfaces by making sure that the /etc/NetworkManager/NetworkManager.conf file shows "managed=false" in the "[ifupdown]" section.

Now shutdown and reboot.  Before logging in to the graphical desktop, login on a text console and verify that your network interface is working.  (For example, use the lynx web browser, the ftp client, etc. to connect to an outside site.)  Then, after logging in to the graphical desktop, verify that you still have network connectivity there as well.  The network-manager applet should now no longer show an eth0 connection.  Yet, your desktop applications, such as the browser, should still have network connectivity via the eth0 interface.  If you need or want to deactivate the eth0 interface, use the ifdown command.  To bring it up again, use the ifup command.  (Both of those commands must be issued as root.)

Static vs. Dynamic IP Address

Your host system currently uses DHCP (Dynamic Host Control Protocol).  But your host system is about to become a gateway system to another network, and will become a primitive router in its own right.  And therefore, DHCP is no longer appropriate.  You will need to convert it to use a static IP address.  Your home router typically not only provides routing services, but is also typically a DHCP server and a caching Domain Name Server (DNS).  A common IP address used by home routers is 192.168.0.1, and it administers the private class C network 192.168.0.0/24.  That is, the network address is 192.168.0.0; and the subnet mask is 255.255.255.0.  It has a pool of addresses used by its internal DHCP server, running from 100 to 149 in the last octet perhaps, but there will be other IP addresses which are in the network but outside the DHCP pool.  You will need to use one of those.  For example purposes, 192.168.0.2 is assumed to be the new static IP address of your host system.

There are usually two levels of DHCP currently involved here.  Typically, the router acts as a DHCP client to obtain an IP address for it to use from your ISP's public network.  During the process of this configuration, your ISP also provides the IP address of one or more Domain Name Servers for your router to use for Domain Name lookups.  Your router also acts as a DHCP server so that computers on its internal private network can obtain IP addresses on the internal network.  When a computer on your internal network requests DHCP configuration, your router will supply it with an IP address on the internal network from its DHCP pool.  But it will also supply it with one or more IP addresses for Domain Name Servers.  There are two ways your router can handle this task.  One way is for the router to provide its own internal IP address to its DHCP clients, since the router runs a caching Domain Name Server.  The other way it can handle this is to simply pass on the address or addresses that it obtained from your ISP as Domain Name Servers when the router was acting as a DHCP client.  Some routers do it one way, some do it the other way.  But even routers which pass on the ISP's DNS server addresses to its DHCP clients still run an internal caching Domain Name Server.

How can you tell which way your router does it?  Well, the first task is to determine your router's address.  Issue the command
 

     netstat -rn

Typical output will look something like this:
 

     Kernel IP routing table
     Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
     0.0.0.0         192.168.0.1     0.0.0.0         UG        0 0          0 eth0
     192.168.0.0     0.0.0.0         255.255.255.0   U         0 0          0 eth0

The second entry is the local route.  It says that for IP addresses on the network 192.168.0.0 (Destination) with subnet mask 255.255.255.0 (Genmask), send the packets directly (Gateway address 0.0.0.0) via interface eth0.  The first entry is the default route.  It says that for IP addresses on any other network other than those specifically defined in other entries (Destination and Genmask both 0.0.0.0), send the packets indirectly via Gateway address 192.168.0.1.  This gateway address is the router's address.

Now examine the file /etc/resolv.conf.  Typical content might look something like this:
 

     domain wowway.com
     search wowway.com
     nameserver 64.233.222.2
     nameserver 64.233.222.7

As you can see, the router passed your ISP's Domain Name Server addresses through to its local client computers in this case, rather than providing its own address as a Domain Name Server.  It also passed your ISP's domain name through to the resolve service, rather than using the domain name you supplied during installation.  The domain name you supplied during installation can be obtained from /etc/hosts.  Look for an entry like this:
 

     IP_address     hostname.domainname     hostname

For example,
 

     127.0.1.1     debian1.my.home.network.us     debian1

In the above example, the host name is "debian1" and the domain name supplied during installation is "my.home.network.us".

When configuring your host system with a static IP address, you don't want to use your ISP's Domain Name Server addresses because they can get out of date easily.  If the ISP changes the IP addresses of its Domain Name Servers, rebooting the router and rebooting the host computers will cause the new DNS servers to be recognized for DHCP-configured computers; but computers which use a static IP address will still be pointing to the old DNS server addresses.  Thus, they should not be configured this way.  Computers which are configured with a static IP address should use the router's address as the one and only DNS server address.  Rebooting the router will cause the router to pick up the change to the ISP's DNS server addresses, and no configuration changes will be necessary for computers in the network which use static IP addresses as long as they point to the router's address as the DNS server address.  Also, the domain name used really should be the domain name supplied during installation.

Another thing you should do is to examine the current configuration of the wired ethernet interface with the "ifconfig" command to determine the current network configuration parameters for the eth0 interface, such as Maximum Transmission Unit (MTU) size.  With the exception of the IP address, you want your static configuration options to match the way the DHCP service configured it.  The MTU size listed probably reflects size limitations from your router, the cable/DSL modem, or your ISP's network.  Write this information down.  Check to see if the resolvconf package is installed.  You can check this with
 

     dpkg-query -l resolvconf

If it is not installed, install it with
 

     apt-get install resolvconf

Then, shutdown the interface before you reconfigure it:
 

     ifdown eth0

This will do a clean DHCP release.  (Obviously you need to be using a local console to do this.  If you are logged in to your host system via an ssh session from another host, the above command will kill your session!)  Now edit the file /etc/network/interfaces to reconfigure the interface.  Here is what the entry for your interface might look like after being configured for a static IP address:
 

     # The primary network interface
     auto eth0
     iface eth0 inet static
             address 192.168.0.2
             netmask 255.255.255.0
             network 192.168.0.0
             broadcast 192.168.0.255
             gateway 192.168.0.1
             mtu 1500
             # dns-* options are implemented by the resolvconf package, if installed
             dns-nameservers 192.168.0.1
             dns-search my.home.network.us

Obviously, change "my.home.network.us" to the domain name you use for your home network. 

These changes will take effect on the next reboot. 

IP Forwarding

You will also need to turn on IPv4 forwarding.  Otherwise, your host system will not forward packets it receives from the operating system running under Hercules that are destined for another host, nor will it forward packets it receives from another host that are destined for the operating system that runs under Hercules.  Edit the file "/etc/sysctl.conf".  Find the lines which say
 

     # Uncomment the next line to enable packet forwarding for IPv4
     #net.ipv4.ip_forward=1

Then uncomment the second line so that you see
 

     # Uncomment the next line to enable packet forwarding for IPv4
     net.ipv4.ip_forward=1

Save the changes and exit the editor.  This change will take effect on the next reboot.

Now shutdown and reboot to make the networking changes take effect.  Verify that your network interface is still working after the reboot, and make sure that it is now using the assigned static IP address.  The "ifconfig" command will show you how the interface is currently configured.  Examine the file /etc/resolv.conf.  After rebooting, it should look something like this:
 

     # Dynamic resolv.conf(5) file for glibc resolver(3) generated by resolvconf(8)
     #     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
     nameserver 192.168.0.1
     search my.home.network.us

As you can see, the resolve service now specifies your router's address as the DNS server address and your home network's domain name as the search domain.  Issue the command
 

    cat /proc/sys/net/ipv4/ip_forward 

To verify that IP forwarding is active.  A value of 1 indicates that IP forwarding is in effect; a value of 0 indicates that IP forwarding is not in effect.

Security Considerations

If you have not already done so, install the hercules package with
 

     apt-get install hercules

Changes to Program Privileges

The hercules package contains a couple of executable files which must run with root privileges.  These files are /usr/bin/hercules and /usr/bin/hercifc.  /usr/bin/hercules is the main Hercules program.  It needs to be root in order to change its priority, as well as the priorities of additional threads that it spawns.  /usr/bin/hercifc needs to be root in order to configure the dynamically-defined tun0 network interface.  One solution is to run the hercules program as the root user.  This works; but routinely running a user-space program as root is something that should be avoided, if possible, for security reasons.  To get around this, these programs change their id to root dynamically, if needed, just long enough to do what they need to do as root, then switch back to their original user id.  This allows you to run the programs as a normal user, but it also requires that the program have the "setuid root" privilege.

This is a security improvement, but programs with the "setuid root" privilege are somewhat of a security risk too.  You want to restrict who can execute these programs as much as possible.  One solution is to create a new userid on the system, called hercules.  By default, the hercules user id will be a member of the hercules group.  (In fact, unless you add more members to the group, the hercules user id will be the one and only member of the hercules group.)  You then make the file owner root, the file group hercules, revoke execute privileges on the file from "other", then give the program "setuid root" privileges.  Now, only root and members of the hercules group can execute the program.  And unless you add more members to the hercules group, the hercules user id will be the only non-root user id on the system that can execute this program.  The following commands will effect this change (after the hercules user and group have been added to the system):
 

     dpkg-statoverride --update --add root hercules 4750 /usr/bin/hercules
     dpkg-statoverride --update --add root hercules 4750 /usr/bin/hercifc

This immediately changes the module attributes and also registers your modifications with Debian's package management system.  If the hercules package is subsequently serviced, these overrides should be automatically applied to the modules that come with the new version of the package.  (However, it is a good idea to verify this if the hercules package is subsequently serviced.)

Changes to udev

Also, if you do this, you may wish to make a change to udev for additional security.  Create or edit the file /etc/udev/rules.d/99-local.rules.  Add the following line to it:
 

     KERNEL=="tun", ACTION=="add", GROUP="hercules", MODE="0660", OPTIONS+="static_node=net/tun"

This will allow only root and members of the group hercules to access the /dev/net/tun device.  Changes made to the udev rules files do not take effect until the next reboot.

UTF-8 Character Mapping

While you're reconfiguring the host system, make sure that it uses UTF-8 as the character mapping in the locales package and the console-setup package.  This can be accomplished with
 

     dpkg-reconfigure locales

and
 

     dpkg-reconfigure console-setup

When reconfiguring locales, you can select several locales to be included on your system, but be sure to make the default locale one which uses the UTF-8 character mapping.  For example, US users might select en_US, en_US.8859-15, and en_US.UTF-8 as the locales to include on their system; but en_US.UTF-8 must be the default locale.  When reconfiguring console-setup, you choose UTF-8 as the character mapping on the first screen, then you make other choices on subsequent screens, such as the font, etc.  These changes take effect on the next reboot.

Router Reconfiguration

The local router for the host system under which Hercules runs will need a new static route defined.  (Alternatives to static routes will be discussed later.)  In a typical home networking environment, there are probably no static routes currently defined.  In our example, if the host system under which Hercules runs has an IP address of 192.168.0.2, and the local router has an IP address of 192.168.0.1, the local router at 192.168.0.1 will need to be told that if it needs to reach a host on subnet 192.168.1.4, with a subnet mask of 255.255.255.252, packets should be routed to gateway 192.168.0.2.  Note that this is a network route, not a host route!  If the router requires you to enter the "number of hops" or the "metric" for a static route, define it as 2.  (The first hop is from the router to the host system; the second hop is from the host system to the zLinux system.)

Most home routers can be reconfigured via a web browser interface.  For example, for Trendnet® routers, type "http://192.168.0.1" in the address line of your browser and press Enter.  By default, the administrator id is "admin" and a password is not required.  Select "Advanced" configuration.  On the left, select "Routes", then under that select "Static Routes".

For Linksys® routers, the factory default IP address for the router is 192.168.1.1 (network 192.168.1.0/24); so you would type "http://192.168.1.1" in the address line of your browser initially.  The default userid and password are the reverse of what Trendnet uses.  For Linksys routers, the userid is not required; but the password is "admin".  Once you make a connection to the administration screen, you can change the router's address to 192.168.0.1 if you want to, to be consistent with this example.  Once you make this change, and the change is in effect, you will of course lose your browser connection.  This also puts your host system and the router on different networks, so you will need to reboot your host system to obtain a new IP address from the new DHCP pool.  (Obviously, all other PCs on the router's network will also need to be rebooted, since they will have the same problem.)

If you have already reconfigured your host system to use a static IP address, change /etc/network/interfaces to put the new static IP address in the router's new network before rebooting.  Change the other related addresses too, such as the network address, the broadcast address, the gateway address, and the DNS nameserver address, to be in the router's new network.  Save the changes and exit the editor.  After rebooting, you can now go back into the router's administration screens (using the new address, "http://192.168.0.1", in the browser's address line) and define your static route.

See your router's manual for details, if necessary, on how to configure your router.

You can see now why a static IP address is necessary for your host system.  If its IP address ever changes, the static route definition that you just entered is no longer correct.

If you don't add this static route to your router table, you won't get any domain name resolution packets back from the router to your zLinux IP stack because the router doesn't know where the zLinux IP stack is or how to get packets to it.  Since the zLinux IP stack is not on the router's local network (192.168.0.0/24), the router will either drop the packets or send the packets via its default route, which is to the cable/DSL modem and on to the internet.  And it will never find you out there.  Similarly, although the zLinux IP stack may be able to send packets to an external internet site, the external internet site can't get packets back to the zLinux IP stack because, again, the router does not know where the zLinux IP stack is.  The router will either drop the packets or send them out the same interface that they came in on — back to the internet.  And the zLinux IP stack will never get the packets.

After making all of these configuration changes to your host system and your router, a reboot of both is recommended in order to make sure that all the changes are in effect.  After rebooting your router, it is a good idea to go into the administration screens again and make sure that your new static route definition is still there.  Also, if you changed your router's network from the factory defaults, make sure it is still on the new network.

Configuring Hercules

From here on, all configuration is done by the hercules user id that you created earlier unless otherwise noted.  Login to the host system as user id hercules.  You will need to create some emulated DASD devices on which to install Debian.  See the Hercules documentation for the dasdinit utility for information on how to do this.  For all practical purposes, the Debian installer only supports CKD DASD devices; so choose a CKD device type to emulate, such as a 3390.

Strictly speaking, FBA DASD devices are supported by the Debian installer.  But the only format supported by the Linux kernel for FBA DASD devices is the CMS format, either non-reserved or reserved.  The Debian installer has no capability to format disks in CMS format.  For all practical purposes, that means that you must have a z/VM® system, running CMS in a virtual machine, to do the formatting.  I am not aware of any Linux-based tool which will format DASD devices (CKD or FBA) in CMS format.  Old free releases of VM, such as VM/370 Release 6, won't cut it.  They create CDF CMS disks.  The Linux kernel requires EDF CMS disks.

Furthermore, versions of the Debian installer prior to jessie don't even recognize pre-formatted CMS disks.  The jessie installer now recognizes pre-formatted CMS disks; but again, the problem is getting the disks formatted this way in the first place.  Unless you have a z/VM® system to do the formatting, stick to CKD DASD devices.  Besides, using CKD devices is more efficient anyway, due to the block size of 512 necessary when using FBA devices.

Here is an example of creating a DASD device:
 

     dasdinit -lfs LX63FC.63FC 3390 X063FC 3338

The above command will create an emulated DASD file called LX63FC.63FC, of device type 3390, with an initial volser of X063FC, and a size of 3338 cylinders.  (The Debian installer will change the volser from X063FC to LX63FC during formatting.)  This is one less than the number of cylinders on a 3390-3: 3339.  This is the maximum size of a minidisk on z/VM® (other than a full-pack minidisk) when the underlying disk is a 3390-3.  Note that the disk can be any size (within reason).  It doesn't have to match the size of a commercial model of real DASD.  You have the same flexibility here as when creating minidisks under z/VM®.

Now you need to create the Hercules configuration file, hercules.cnf.  The Hercules configuration file statement
 

     ARCHMODE z/Arch

must be used to configure the emulator for z-Architecture mode.  ESAME is accepted as an alias for z/Arch.  The ENGINES configuration file statement must specify either CP (standard processor) or IL (IFL processor).  (IFL stands for "Integrated Facility for Linux".)  There is no particular advantage to using one processor type or the other in a GNU/Linux environment: GNU/Linux will run with equal performance on either processor type.  The only difference between the two is that z/OS® will not run on an IFL processor, but it will run on a standard processor.  But we're not running z/OS®, so who cares?

Hercules supports all three booting methods for booting the Debian installer: CD-ROM, tape, and card reader.  However, the card reader is the easiest method to use.  For example, with the tape method you will need to do some pre-processing to get the input into the proper emulation format, such as HET or AWS emulated tape files, etc.  The card reader allows you to use the installation files directly.  Consider, for example, the following Hercules device definition statement:
 

     000C 3505 kernel.debian parmfile.debian initrd.debian ebcdic autopad eof

This statement defines an emulated card reader (device type 3505) at device number 000C.  The card reader contains three files: kernel.debian, parmfile.debian, and initrd.debian, in that order.  These files should be downloaded in binary from the "generic" flavor of the Debian archive (as opposed to the "tape" flavor).  For example, dists/jessie/main/installer-s390x/current/images/generic is the place to download them from in the Debian archive if you're using the jessie (8.x) release.  ebcdic, autopad, and eof are reader options.

The ebcdic option specifies that Hercules is not to perform any ASCII-to-EBCDIC translation of the input records, nor look for line-feed characters (0x0a) as end-of-record indicators.  Instead, the input file is simply chopped into 80-byte pieces; and each 80-byte piece is supplied to the program in turn, without translation, as it reads card images.

The autopad option specifies that the last card image is padded on the right as needed with null characters (0x00) to make the last card image 80 bytes long, if the size of the file in bytes is not an integer multiple of 80.

The eof option specifies that the card reader will signal end-of-file ("unit exception" in the device status) on the first read attempt by the program following the read for the last card image.  This is what is required for the Debian installer.  (The alternative behavior, intrq, causes the card reader to signal "unit check" in the device status instead, followed by signaling "intervention required" in the sense byte on the ensuing sense command.  This will not work with the Debian installer.)

Note that the multifile reader option must not be used.  If multifile is used, the three files are essentially concatenated together as a single file.  End-of-file is signalled only once, on the read attempt following the read for the last card image of the last file.  This will not work with the Debian installer.  If multifile is not used, end-of-file is signaled on the read attempt following the read for the last card image of each file.  If there is another file in the reader following the one just processed, the reader then asynchronously signals an attention interruption following signaling end-of-file for the previous file. This lets the program know that the card reader is ready to send another file.  This is the behavior required by the Debian installer.  Therefore, the multifile option must not be used.

You boot the installer with
 

     ipl 000C

(issued from the Hercules console) for a "load normal" or
 

     iplc 000C

for a "load clear".  000C is the device number of the card reader.  IPL stands for "Initial Program Load".

Note: under Hercules, the CPU must be in the stopped state before the ipl or iplc command will work.  A CPU in a disabled wait state (the wait bit is on and I/O and External interruptions are both disabled) is still considered to be "running".  If this is your situation, then the stop command may be issued first to put the CPU into the stopped state.  The ipl/iplc command should then work.  This is a quirk of Hercules.  Real IBM mainframes can be IPLed while "running", although answering an "Are you sure?" prompt is necessary.

When installing the Debian GNU/Linux s390x port "natively" (i.e. not in a virtual machine under z/VM®), including installing under Hercules, the kernel messages, as well as the initial messages from the Debian installer, are written to the SCLP (Service Call Logical Processor) line-mode console.  On a real mainframe, the SCLP line-mode console is accessed by means of the "Operating System Messages" application on the SE (Support Element) or the HMC (Hardware Management Console) for the LPAR (Logical PARtition) being used.

The SCLP line-mode console is integrated into the Hercules main console under Hercules.  SCLP line-mode console output is displayed in a different color (green) to distinguish it from normal Hercules console output (white).  Anything typed on the Hercules console is assumed to be a Hercules command.  If you want to send input to the SCLP line-mode console, you preface it with a period.  For example, typing
 

     1

on the Hercules console and then pressing Enter will be interpreted as entering the Hercules command "1".  This will generate an error message, since "1" is not a valid Hercules command.  But typing
 

     .1

on the Hercules console and then pressing Enter will be interpreted as a request to send "1" as input to the SCLP line-mode console.  It is critically important to remember to preface SCLP line-mode console input with a period.  For example, after your system is installed, if you are logged in to Linux via the SCLP line-mode console, then
 

     .exit

issued at a shell prompt will cause you to exit the current shell session.  (If the current shell session is your login shell, then this will also log you out of your terminal session.)  But
 

     exit

(with no leading period) will shut down Hercules!

For operating systems which use the SCLP line-mode console, such as zLinux, you must specify
 

     CODEPAGE 437/500

in the Hercules configuration file in order to match the ASCII/EBCDIC translation rules used by the "Operating System Messages" application on a real IBM mainframe.  Otherwise, some characters, such as the left and right square bracket characters, will be garbled.

A home network uses private network addresses.  The router serves as a proxy between the private home network and the public internet to provide internet connectivity.  By internet convention, the following networks are private networks:
 

     10.0.0.0/8                            A single class A network
     172.16.0.0/16 - 172.31.0.0/16         16 contiguous class B networks
     192.168.0.0/24 - 192.168.255.0/24     256 contiguous class C networks

As you can see, your home router has chosen the lowest-numbered private class C network and manages host addresses 192.168.0.1 through 192.168.0.254.  (192.168.0.0 is the network address, and 192.168.0.255 is the broadcast address for the network.  These two addresses cannot be used for host addresses.)  The router uses 192.168.0.1 as its own IP address.  This allows up to 253 additional hosts on the network.

For the new point-to-point connection network, this example picks the next available private class C network, 192.168.1.0/24, subnets it for two-host subnets, then picks the first available subnet: 192.168.1.4/30.  If you are using an internal corporate network, as opposed to a home network, you obviously must work closely with your network administration staff in choosing network addresses and IP addresses.  They will want to know what you are doing and make sure that you do not pick addresses which are already in use in your organization.  This includes the static IP address that you pick for the host system under which Hercules runs.

This example illustrates the use of a Channel-To-Channel Adapter (CTCA).  A Channel-To-Channel Adapter provides a point-to-point connection.  A point-to-point connection, in networking terms, is a network consisting of exactly two hosts.  It is a waste of IP addresses to use an entire class C network address space, which can support up to 254 hosts, on a two-host network.  Therefore, subnetting is used.  Consider the following Hercules device definition statements from hercules.cnf:
 

     1000.2 CTCI 192.168.1.5 192.168.1.6

The above statement defines a pair of Channel-To-Channel Adapter device numbers (1000 and 1001) identically.  (One device number is used for reading and the other is used for writing.)  The two CTC device numbers must be consecutive, and the lower one must be even.  The actual mainframe device type being emulated is a 3088.  But the keyword CTCI does more than simply create a hardware emulation of a 3088.  It also causes Hercules to emulate another mainframe connected to the other end of the 3088 which is communicating with this one using the S/390 protocol (protocol 0).  From the point of view of the host Linux operating system under which Hercules runs, the Hercules CTCI device driver is communicating with the Linux TUN/TAP device driver using the expected Linux protocols.  The Hercules CTCI device driver does the protocol conversion between the mainframe S/390 network protocols and the Linux tunneling device driver protocols.

In this example, 192.168.1.4 is the subnet address, 192.168.1.5 is the IP address used by the operating system which runs under Hercules, 192.168.1.6 is the IP address used by the host operating system under which Hercules runs, and 192.168.1.7 is the broadcast address (although broadcast is not supported for a point-to-point connection).  That's it.  That's the entire subnet.

With subnetting, an IP address is divided into three parts: the network number (the first 24 bits in this case), the subnet number (the next six bits in this case), and the host number (the last two bits in this case).  And it is an internet rule that, for a host, none of the three parts of the IP address can be all zero bits or all one bits.  In summary, with this type of subnetting, the subnet address must be a multiple of 4, the two host addresses are the two addresses immediately above the subnet address, and the broadcast address is one higher than the highest host address.  Furthermore, the last octet of the subnet address cannot be 0 or 252.  (That would make the subnet number all zero bits or all one bits, respectively.)  This allows us to create up to 62 two-host subnets out of a class C network.  These subnets have a last octet ending in 4, 8, 12, 16, etc., up to a maximum of 248.  If another instance of Hercules were later installed, subnet 192.168.1.8/30 could be used for it (host addresses 192.168.1.9 and 192.168.1.10).  Without subnetting, you would have to burn another class C address space (say, 192.168.2.0/24) for another two-host network.

At this point, the host system under which Hercules runs has become a multi-homed system.  It now has two IP addresses.  192.168.0.2 is its IP address on the eth0 interface, and 192.168.1.6 is its IP address on the tun0 interface, the interface which connects it to the operating system which runs under Hercules.  (Actually, it does have a third IP address, 127.0.0.1, which is its IP address on the lo interface, but no other system will ever communicate with it using this address.)  Only the eth0 and lo interfaces will be defined in /etc/network/interfaces.  The tun0 interface is defined dynamically and exists only while Hercules is running.  However, if Hercules is running, the "ifconfig" command issued on the host system will show the details of how the tun0 interface is configured.  For more information, see the Hercules TCP/IP page.

Note: "ifconfig" will show the tun0 interface as having a subnet mask of 255.255.255.255.  This is normal for a point-to-point connection.

Here is an example of a complete hercules.cnf file configured for the installation of the s390x port of Debian GNU/Linux.  It is based on an IBM z/890 (2086).
 

     #
     # Configuration file for the Hercules z/Architecture emulator.
     #
     # System Parameters
     #
     ARCHMODE ESAME
     ASN_AND_LX_REUSE ENABLE
     AUTO_SCSI_MOUNT NO
     CCKD RA=2,RAQ=4,RAT=2,WR=2,GCINT=10,GCPARM=0,NOSTRESS=0,TRACE=0,FREEPEND=-1
     CODEPAGE 437/500
     CNSLPORT 3270
     CONKPALV (3,1,10)
     CPUMODEL 2086
     CPUPRIO 15
     CPUSERIAL 000001
     CPUVERID 00
     DEVPRIO 8
     DEVTMAX 0
     DIAG8CMD DISABLE
     ECPSVM NO
     ENGINES IL
     HERCPRIO 0
     IODELAY 0
     LEGACYSENSEID OFF
     LOGOPT TIMESTAMP
     LPARNAME LNXPROD
     LPARNUM 01
     MAINSIZE 1024
     MANUFACTURER IBM
     MAXCPU 1
     MODEL A04 110
     MOUNTED_TAPE_REINIT DISALLOW
     NUMCPU 1
     OSTAILOR QUIET
     PANRATE SLOW
     PANTITLE "LPAR LNXPROD"
     PGMPRDOS RESTRICTED
     PLANT 02
     SHCMDOPT NODIAG8
     SYSEPOCH 1900
     TIMERINT 50
     TODDRAG 1
     TODPRIO -20
     TRACEOPT REGSFIRST
     TZOFFSET +0000
     XPNDSIZE 0
     YROFFSET 0
     #
     # Device statements
     #
     # Card reader to boot Debian installer
     000C 3505 kernel.debian parmfile.debian initrd.debian ebcdic autopad eof
     # Channel-To-Channel Adapter network device pair
     1000.2 CTCI 192.168.1.5 192.168.1.6
     # Will be mounted as /
     63FC 3390 LX63FC.63FC
     # Will be mounted as /boot
     63FD 3390 LX63FD.63FD
     # Will be mounted as /home
     63FE 3390 LX63FE.63FE
     # Will be a swap disk
     63FF 3390 LX63FF.63FF

Before you start Hercules, you might want to edit parmfile.debian to specify some kernel boot parameters, Debian installer options, or environment variables that you want to be in effect during installation.  For example, you might want to specify the environment variable "TERM=dumb", since the SCLP line-mode console does not support ANSI escape sequences.  You might also want to specify the kernel boot parameter "hvc_iucv=0", since the iucv driver only works in a virtual machine under z/VM®.  "modprobe.blacklist=lcs" is another option you might want to use.  The kernel lists two device drivers for the channel-to-channel adapter: ctcm and lcs.  But the ctcm driver is the only one you need.  The lcs driver is not needed and may cause problems if it tries to take control of the device.  Here is what parmfile.debian might look like when you are through editing:
 

     ro locale=C TERM=dumb hvc_iucv=0 modprobe.blacklist=lcs

To start the Hercules emulator, simply enter the command "hercules".  You may get the message
 

     HHCIF005E hercifc: ioctl error doing SIOCDIFADDR on tun0: 25 Inappropriate ioctl for device

but this is an innocuous error and may be ignored.  Any other error messages should be investigated.  Switch to another terminal session and issue the "ifconfig" command to verify that the tun0 network device is now defined and appropriately configured.

Installing Debian

To boot the Debian installer, type "iplc 000C".

When configuring the network device in the Debian installer, choose the Channel-To-Channel Adapter (CTC) as the network device type.  Choose the lower-numbered device number (1000 in this example) as the read device, choose the higher-numbered device number (1001 in this example) as the write device, and choose protocol 0 (S/390).  When entering the IP address for this host, append /30 to the address.  (In this example, that would be "192.168.1.5/30".)  This is equivalent to specifying a subnet mask of 255.255.255.252.  Specify 192.168.1.6 as the point-to-point partner address.  Specify the same DNS address as the host system under which Hercules runs uses, typically the local router's address: 192.168.0.1.  As you make your responses to the initial configuration questions of the Debian installer, remember to preface your input with a period so that your responses will be routed to the SCLP line-mode console input interface instead of being interpreted as Hercules commands.

Here is an example of what the early installation dialog on the SCLP line-mode console might look like:
 

     Configure the network device
     ----------------------------

     Please choose the type of your primary network interface that you will need for
     installing the Debian system (via NFS or HTTP). Only the listed devices are
     supported.
     Network device type:
       1: ctc: Channel to Channel (CTC) or ESCON connection,
       2: qeth: OSA-Express in QDIO mode / HiperSockets,
       3: iucv: Inter-User Communication Vehicle - available for VM guests only,
       4: virtio: KVM VirtIO,
     Prompt: '?' for help>
     .1
     1

     The following device numbers might belong to CTC or ESCON connections.
     CTC read device:
       1: 0.0.1000,      2: 0.0.1001,
     Prompt: '?' for help>
     .1
     1

     The following device numbers might belong to CTC or ESCON connections.
     CTC write device:
       1: 0.0.1000,      2: 0.0.1001,
     Prompt: '?' for help>
     .2
     2

     Protocol for this connection:
       1: S/390 (0) [*],  2: Linux (1),      3: OS/390 (3),
     Prompt: '?' for help, default=1>
     .1
     1

     Configure a network using static addressing
     -------------------------------------------

     The IP address is unique to your computer and may be:

     * four numbers separated by periods (IPv4);
     * blocks of hexadecimal characters separated by colons (IPv6).

     You can also optionally append a CIDR netmask (such as "/24").

     If you don't know what to use here, consult your network administrator.
     IP address:
     Prompt: '?' for help>
     .192.168.1.5/30
     192.168.1.5/30

     The point-to-point address is used to determine the other endpoint of the point
     to point network.  Consult your network administrator if you do not know the
     value.  The point-to-point address should be entered as four numbers separated
     by periods.
     Point-to-point address:
     Prompt: '?' for help>
     .192.168.1.6
     192.168.1.6

     The name servers are used to look up host names on the network. Please enter
     the IP addresses (not host names) of up to 3 name servers, separated by spaces.
     Do not use commas. The first name server in the list will be the first to be
     queried. If you don't want to use any name server, just leave this field blank.
     Name server addresses:
     Prompt: '?' for help, default=>
     .192.168.0.1
     192.168.0.1

     Detecting link on ctc0; please wait...
     ... 16%
     ... 25%
     ... 33%
     ... 41%
     ... 50%
     ... 66%
     ... 75%
     ... 83%
     ... 91%
     Please enter the hostname for this system.

     The hostname is a single word that identifies your system to the network. If
     you don't know what your hostname should be, consult your network
     administrator. If you are setting up your own home network, you can make
     something up here.
     Hostname:
     Prompt: '?' for help, default=debian>
     .smp6
     smp6

     The domain name is the part of your Internet address to the right of your host
     name.  It is often something that ends in .com, .net, .edu, or .org.  If you
     are setting up a home network, you can make something up, but make sure you use
     the same domain name on all your computers.
     Domain name:
     Prompt: '?' for help>
     .my.home.network.us
     my.home.network.us

     Generating SSH host key

     Continue installation remotely using SSH
     ----------------------------------------

     You need to set a password for remote access to the Debian installer. A
     malicious or unqualified user with access to the installer can have disastrous
     results, so you should take care to choose a password that is not easy to
     guess. It should not be a word found in the dictionary, or a word that could be
     easily associated with you, like your middle name.

     This password is used only by the Debian installer, and will be discarded once
     you finish the installation.
     Remote installation password:
     .john316

     Please enter the same remote installation password again to verify that you
     have typed it correctly.
     Re-enter password to verify:
     .john316

     Start SSH

     To continue the installation, please use an SSH client to connect to the IP
     address 192.168.1.5 and log in as the "installer" user. For example:

        ssh installer@192.168.1.5

     The fingerprint of this SSH server's host key is:
     cf:86:14:39:eb:1d:3c:e6:07:96:ed:9c:89:4e:a6:b2

     Please check this carefully against the fingerprint reported by your SSH
     client.
     [Press enter to continue]

User input above is shown in bold face, and machine output is shown in normal face.  But on the Hercules console, user input will be shown in white, while machine output will be shown in green.  Note that all user input must be prefaced with a period to tell Hercules to treat it as input to the SCLP line-mode console.  Also notice that the installer echoes back user input in green, without the leading period, except for the passwords, which are suppressed.  Once you have your network device, your network, your local ssh server, and the password for the "installer" id configured via the SCLP line-mode console, ignore the "[press Enter to continue]" prompt and switch to another terminal session on the host system.  Login to the host system using your normal non-root userid, then from there, login to the zLinux system remotely via an ssh client as user "installer" to finish the installation.  For example, on the host system under which Hercules runs, assuming that the openssh-client package is installed, you can enter
 

     ssh installer@192.168.1.5

Remember, your ssh client must be using the UTF-8 character mapping.  Otherwise, the box-drawing characters on the screens displayed by the Debian installer won't look right.  (That's why reconfiguring the host system to use UTF-8 was suggested earlier.)

You don't have to connect to your emulated mainframe system from another terminal session on the same host under which Hercules runs; you can connect from any ssh client on any computer on your home network.  Just make sure that the ssh client that you use is using a UTF-8 character mapping.  However, you may have to tell that host how to get to your zLinux host.  For example, on another Linux host system on the router's local network, you can issue the command (as root)
 

     route add -net 192.168.1.4 netmask 255.255.255.252 gw 192.168.0.2 metric 2

Now this host will send packets bound for 192.168.1.5 to 192.168.0.2, and 192.168.0.2 will know how to get them to 192.168.1.5.  For a Windows® host, the command is similar:
 

     route add 192.168.1.4 mask 255.255.255.252 192.168.0.2 metric 2

(You may need to run this command as an Administrator.)  Of course, these routing commands are only good until you reboot the host on which they were issued.  For a Linux system, you can make the route permanent by adding the command to /etc/rc.local.  This will cause the command to be issued on every subsequent boot.  For a Windows® host, use the -p option to make the route persistent across boots of the operating system.  For example,
 

     route -p add 192.168.1.4 mask 255.255.255.252 192.168.0.2 metric 2

Of course, if you've already issued the above command without the -p option, you will first have to delete the static route from the routing table before you can add it back as a persistent route.  For a Windows® host, the command to do this is
 

     route delete 192.168.1.4

The syntax to delete the static route in Linux is
 

     route del -net 192.168.1.4 netmask 255.255.255.252

The command
 

     netstat -rn

is useful for examining your current routing table, both for Linux and Windows® hosts.  For completeness' sake, you should make these routing changes on all hosts on your router's local network, except for the host which runs Hercules.

Note: a dynamic routing command may fail if the host on which it is issued cannot contact the gateway system at the time the route command is issued; so if the gateway system is down at the time you boot another Linux host which has routing commands in /etc/rc.local, those routing commands may need to be issued again dynamically after the gateway system is up.

Note: you may wonder why you can't just rely on the router to forward packets to your zLinux host, now that it knows how to get there.  First of all, that involves an extra step.  The packets go through the router unnecessarily, slowing things down and increasing network traffic.  Secondly, it might not work anyway.  Routers, in general, don't like to send routed packets back out on the same interface that they came in on.  To a router, if it has to send a packet back out on the same interface that it came in on, that is a sign that something is wrong with a routing table somewhere.  For this reason, the router may simply drop the packet, even though it knows how to get it where it needs to go.

As an alternative to defining a static route in the local router and all other hosts on the router's local network, you can set up a routing daemon, such as quagga, on the host which runs Hercules which will advertise the new network to all IP stacks which are listening.  Another approach is to use iptables, which, with a combination of Network Address Translation (NAT) and proxy ARPing (Address Resolution Protocol), makes other hosts on the router's local network think that the zLinux host is on the same network, when it really isn't.  For a home network with few hosts, static routes defined in the router and other local hosts are usually the simplest solution.

Once installation is complete, issue the ipl or iplc command to boot from the device number of the DASD device which contains your /boot partition in order to boot your new zLinux system for the first time.  In this example, that would be 63FD.

The zIPL boot loader also writes to the SCLP line-mode console and expects input from the SCLP line-mode console.  If you need to provide input to zIPL, remember to preface your input with a period.  For example,
 

     .2

to instruct zIPL to boot the backup kernel instead of the default kernel.  Partly due to the lack of support for the re-ipl feature in Hercules, it is recommended that you use the iplc command (load clear) instead of the ipl command (load normal) to IPL your system, especially on the second or a subsequent IPL during the same Hercules session.  When you login to your newly-installed system for the first time, check /etc/network/interfaces and make sure that the MTU size of 1500 (or whatever is specified for eth0 on the host system) is specified there for your network device (ctc0).  If not, edit the file and specify it.  (Although a channel-to-channel adapter is capable of much higher MTU sizes than this, you want to limit the size to what the rest of the network is capable of.)  Then shutdown and reboot. 

Note: the same rule applies here for network interface names as was mentioned earlier for the ethernet interface.  ctc0 is the historic name for the first channel-to-channel adapter network interface.  If Debian is using the new udev-provided persistent network interface names, it may be something else.  Substitute that name for ctc0 in this document.

Here is a sample excerpt from the /etc/network/interfaces file for your zLinux system:
 

     # The primary network interface
     auto ctc0
     iface ctc0 inet static
             address 192.168.1.5
             netmask 255.255.255.252
             network 192.168.1.4
             broadcast 192.168.1.7
             gateway 192.168.1.6
             pointopoint 192.168.1.6
             mtu 1500
             # dns-* options are implemented by the resolvconf package, if installed
             dns-nameservers 192.168.0.1
             dns-search my.home.network.us

Again, "my.home.network.us" will instead be the domain name of your home network.  Not all of these parameters are necessary to configure a ctc device, but they have all been included above for documentation purposes.  I also recommend installing the resolvconf package in the zLinux system, if it is not already installed.

You should also edit /etc/zipl.conf and add the "TERM=dumb" and "hvc_iucv=0" kernel boot parameters to the "parameters" control statements, since the Debian installer doesn't seem to do this.  (There are two "parameters" statements: one for the primary kernel, and one for the backup kernel.)  I like to add the "ro" parameter as well.  Check for a file called /etc/modprobe.d/blacklist.local.conf.  Inside this file should be a statement which says, "blacklist lcs".  The Debian installer should have created this file with this entry in it.  If the file doesn't exist, create it.  If the file does exist, but the "blacklist lcs" entry isn't there, then edit the file and add this entry.  The version of the Debian installer that I last used got confused and put the line "blacklist modprobe" in the file instead of "blacklist lcs".  If this is the case for you, change the word "modprobe" to the word "lcs".

Another change you should make to your installed system is to manually fix Debian bug number 620095.  This basically consists of changing
 

     SUBSYSTEM=="ccw", RUN+="/sbin/hwup -A -D $devpath $env{SUBSYSTEM} $kernel"

to
 

     SUBSYSTEM=="ccw", ACTION=="add", RUN+="/sbin/hwup -A -D $devpath $env{SUBSYSTEM} $kernel"

in /lib/udev/rules.d/85-sysconfig-hardware.rules.  You might also want to manually fix Debian bug number 696943.  A fix is included in the bug report.  After making these changes, update the initial RAM file system image file.  For example,
 

     update-initramfs -u -k $(uname -r)

will update the initial RAM file system image file for the running kernel.  (This will also cause zipl to be run afterwards.)  If you have additional kernels installed, their initial RAM file system image files will need to be updated as well.

When you reboot your system, use "shutdown -h now" followed by a subsequent iplc command, rather than "shutdown -r now", since Hercules does not support the mainframe's re-ipl feature.

Once you have completed installation, you can comment out or remove the device definition statement for the card reader from the hercules.cnf file.  Once the operating system is installed, you don't need a card reader anymore.  On the other hand, you might need to boot the Debian installer in rescue mode to recover from a future failed zIPL installation.

Init System Changes

Another change you should make to your installed system is to change the terminal type of the sclp line-mode console to "dumb".  The method for doing this depends on which init system you are using.

Changes for sysvinit

If your init system is sysvinit, edit the file /etc/inittab.  Look for a line which looks something like this:
 

     1:2345:respawn:/sbin/getty --keep-baud 115200,38400,9600 sclp_line0 vt102

where "vt102" is the terminal type.  If the terminal type is "dumb", then you don't need to change anything.  If the terminal type is something other than "dumb", change it to "dumb" (without the quotes, of course).  Save the file and exit the editor.  This change will take effect on the next reboot.

Changes for systemd

If your init system is systemd, issue the following command:
 

     systemctl status serial-getty@sclp_line0.service

You need to issue this command from an ssh session while no-one is logged on to the console.  Output should look something like this:
 

     • serial-getty@sclp_line0.service - Serial Getty on sclp_line0
        Loaded: loaded (/lib/systemd/system/serial-getty@.service; disabled)
        Active: active (running) since Mon 2015-09-14 19:34:35 EDT; 27 min ago
          Docs: man:agetty(8)
                man:systemd-getty-generator(8)
                http://0pointer.de/blog/projects/serial-console.html
      Main PID: 643 (agetty)
        CGroup: /system.slice/system-serial\x2dgetty.slice/serial-getty@sclp_line0.service
                └─643 /sbin/agetty --keep-baud 115200,38400,9600 sclp_line0 vt102

The terminal type is the last word on the last line.  In the above example, it is "vt102".  If the terminal type is anything other than "dumb", you should change it.  Here's how.  Issue the following sequence of commands:
 

     cd /etc/systemd/system
     mkdir serial-getty@sclp_line0.service.d
     cd serial-getty@sclp_line0.service.d

Now create a file in the current directory called "override.conf".  It should look like this:
 

     [Service]
     ExecStart=
     ExecStart=-/sbin/agetty --keep-baud 115200,38400,9600 %I dumb

Save the changes and exit the editor.  Now shutdown and reboot.  When the system comes up again, the terminal type should be "dumb".

Multiple Instances of Hercules on the Same Host System

You may wish to run multiple instances of Hercules on the same host system.  For example, you may want to run a jessie system in one instance of Hercules and a stretch or sid system in another instance.  How do you do that?  Well, there's more than one way to do this; but here's how I do it.  First of all, I use the same userid, hercules, to run both instances.  And they both run from the same home directory (/home/hercules), but in different terminals.  The second instance uses a different configuration file than the first.  The original instance uses the default hercules configuration file: hercules.cnf.  In my case, I use herc2.cnf as the configuration file for the second instance.  When I start the first instance, I simply enter the command "hercules", with no operands, and it picks hercules.cnf as the configuration file by default.  When I run the second instance, I enter the command "hercules -f herc2.cnf" to explicitly specify the configuration file to use.  The second configuration file is a little different from hercules.cnf, of course.  Here's an example of what herc2.cnf might look like:
 

     #
     # Configuration file for the Hercules z/Architecture emulator.
     #
     # System Parameters
     #
     ARCHMODE ESAME
     ASN_AND_LX_REUSE ENABLE
     AUTO_SCSI_MOUNT NO
     CCKD RA=2,RAQ=4,RAT=2,WR=2,GCINT=10,GCPARM=0,NOSTRESS=0,TRACE=0,FREEPEND=-1
     CODEPAGE 437/500
     CNSLPORT 3271
     CONKPALV (3,1,10)
     CPUMODEL 2086
     CPUPRIO 15
     CPUSERIAL 000001
     CPUVERID 00
     DEVPRIO 8
     DEVTMAX 0
     DIAG8CMD DISABLE
     ECPSVM NO
     ENGINES IL
     HERCPRIO 0
     IODELAY 0
     LEGACYSENSEID OFF
     LOGOPT TIMESTAMP
     LPARNAME LNXTEST
     LPARNUM 02
     MAINSIZE 1024
     MANUFACTURER IBM
     MAXCPU 1
     MODEL A04 110
     MOUNTED_TAPE_REINIT DISALLOW
     NUMCPU 1
     OSTAILOR QUIET
     PANRATE SLOW
     PANTITLE "LPAR LNXTEST"
     PGMPRDOS RESTRICTED
     PLANT 02
     SHCMDOPT NODIAG8
     SYSEPOCH 1900
     TIMERINT 50
     TODDRAG 1
     TODPRIO -20
     TRACEOPT REGSFIRST
     TZOFFSET +0000
     XPNDSIZE 0
     YROFFSET 0
     #
     # Device statements
     #
     # Card reader to boot Debian installer
     001C 3505 kernel.debian parmfile.debian initrd.debian ebcdic autopad eof
     # Channel-To-Channel Adapter network device pair
     1002.2 CTCI 192.168.1.9 192.168.1.10
     # Will be mounted as /
     63F8 3390 LX63F8.63F8
     # Will be mounted as /boot
     63F9 3390 LX63F9.63F9
     # Will be mounted as /home
     63FA 3390 LX63FA.63FA
     # Will be a swap disk
     63FB 3390 LX63FB.63FB

As you can see, I made some changes.  CNSLPORT is set to 3271 instead of 3270, since both instances of Hercules cannot share the same port.  LPARNAME, LPARNUM, and PANTITLE also changed.  I'm simulating a second LPAR on the same physical processor as the first instance.  I put the card reader on a different device number too: 001C versus 000C.  That is probably not necessary, but I like to keep the device numbers unique.  In this instance, you would boot the Debian installer by using "iplc 001C" instead of "iplc 000C".  If you're using a different version of the Debian installer for this instance than you used for the original instance, the installer file names will have to be changed too.  In this example, I'm using the same version of the installer as in the first instance.  I used different device numbers for the channel-to-channel adapter as well, 1002 and 1003 instead of 1000 and 1001.  And of course, the IP addresses must be different.  I used the host addresses from the next available subnet, 192.168.1.8/30, which are 192.168.1.9 and 192.168.1.10.  On the host side, this interface will be called tun1 (assuming that the first instance is already running).  The DASD device numbers are different too.  You don't want to install over the top of the DASD devices for the other system!  Once installed, this system will be IPLed from device number 63F9.

Of course, I had to add another static route in my router for the new subnet, as well as static routes for all the other hosts on the router's local network.  All in all, creating a second instance of Hercules was relatively painless.  Another advantage to having a second instance of Debian GNU/Linux for s390x running on the same host as the first is that it gives you a "rescue" system.  If one system gets messed up, you can use the other one to recover it, and vice versa.  You no longer have to rely on using the Debian installer in rescue mode to recover your system.

Conclusion

Setting up Hercules properly for a zLinux operating system with network connectivity can be tricky, but if done properly can provide a functional and cheap testing platform for zLinux itself and software which is written for it.  However, one should not expect performance comparable to a real mainframe, especially in I/O.  If anyone has any comments, suggestions, complaints, corrections, or any other form of feedback, please drop me a line at zlinuxman (at) fastmail (dot) com.

Return to my home page