1	Problem
To install some S/390 Software (zLINUX, OS/390), I installed an OS/390-System and a zLINUX under the S/390 emulator Hercules.
This document represents the experience on my PC in the office (PIII, 500 MHz, Win2K).
2	Software
2.1	CYGWIN
The GNU-software CYGWIN is a UNIX emulator for Windows-Systems. With this emulator, one can execute or port LINUX-packets directly on a Windows-PC
The product can be installed by download the SETUP.EXE from http://www.cygwin.com and execute it with administrator rights (needed only for the installation process).
I used the method first to download the packets from internet, second to install it from the local download directory.
2.1.1	Download
The CYGWIN installation process needs an archive path on local disk for the installation packets and the internet connection method. For the later, I selected the “use IE5.5 values”. I had to sign on my PC on the firewall to get internet access for the download.
I selected the mirror server ftp.uni-erlangen.de, from which the packet list will be downloaded.
At a later point in time, I recognized, that two CYGWIN non-default-libs have to be specified explicitly for the Hercules emulator:
libbz2_0	Ver. 1.0.2-1
pcre		Ver. 3.7-1
2.1.2	Installation
After the download of the packets, I installed them in the program directory
C:\Programme\cygwin
This directory becomes the root directory of your Windows bash shell !
When the installation is finished, you get an icon CYGWIN on your desktop which runs a bash shell with a current directory of /home/<username>.
2.2	Hercules
The Hercules emulator was downloaded from website http://www.conmicro.cx/hercules/, I decided to download the packet http://www.conmicro.cx/hercules/hercules2165-i686f.exe (PII with Fish-thread-optimization).
I unzipped the packed into path
C:\Programme\hercules
I modified the DOS/Win path by appending C:\Programme\hercules , so that the programs and some dll´s can be found by bash and windows. 
At this point, we could call the emulator but as there exist no configuration files, it makes no sense (so read further ;-).
2.3	Utilities
To run an OS/390 on hercules, you first must create a copy of an IPL´able system (IPL=boot). Here, you can go two paths, of which I used the last one:
2.3.1	TAPECOPY/RAWSTAPE
I extracted these two assembly programs from the Hercules sourcepackage in subdirectory /util as a complete Compile-Link-Go job. I transferred them via ASCII-FTP into an FB80-PDS of our “real” OS/390.
The program TAPECOPY reads RECFM-U datasets (DFDSS full dump) and write them on DASD as RECFM-F from where you can transfer it to your PC and create AWSTAPE dataset.
The program RAWSTAPE unpacks datasets in AWSTAPE format (P/390, virtual tape dataset) to RECFM-U datasets.
So you can copy full dumps in both directions.
2.3.2	CCKDDUMP
The program CCKDDUMP is an S/390 assembly program too; it dumps a complete S/390 DASD volume and compresses it to a Hercules CCKD file, which you transfer FTP binary to your PC.
The advantage is, that this CCKD file represents an OS/390 volume on your PC from which you can boot under Hercules (IPL). In our case, this dataset was a small fraction of the real OS/390 volume.
2.4	Dump of our OS/390 DSV emergy system
Previous to assemble CCKDDUMP under OS/390, you have to download (http://www.gzip.org/zlib/) and install the zlib under OS/390.
You can get some hints from http://www.conmicro.cx/hercules/cckddasd.html, but I will describe my steps too:
1.	I downloaded an actual version from http://www.gzip.org/zlib/ and transfered it with binary ftp to OS/390 OpenEdition – the OS/390-Unix (tar.gz !)
2.	I uncompressed und unpacked it in OpenEdition with gunzip and tar -xvf
3.	I converted the sources with iconv -f ISO8859-1 -t IBM-1047 <name>  >  <newpath/name> from ASCII to EBCDIC (Attention: you have to specify the output-redirector bracket in the above command between input and output dataset !) 
Hint: I made a litte shellscript which contained the command:
iconv -f ISO8859-1 -t IBM-1047 $1 > ../converted/$1
and run this command for all *.c und *.h files.
4.	I put these converted members (should now be readable under OpenEdition or TSO-ish) into OS/390 PDS (OpenEdition FTP with transfermode EBCDIC to localhost). I stored the .c files into a PDS “libname.C” and the .h files into a PDS named “libname.H”.
5.	I submitted the jobs (description under http://www.conmicro.cx/hercules/cckddasd.html) after I changed the dataset names to our local names.
Attention ! Before you do this, you have to make the necessary modifications to ZCONF.H:
pragma map from compress to COMPRESS, from compress2 to COMPRES2, from uncompress to UNCOMPRE
6.	The loadlib of the so generated loadmod CCKDDUMP has to be APF authorised (SET PROG=, SETPROG), else you will get the mentioned abends.
For our purpose, I dumped a volume NOT280 with CCKDDUMP (single-disk emergency system). The result was a DSORG-PS dataset with 6200 tracks (350 Mbyte), which I transferred binary via FTP to my PC.
2.5	Hercules and network
Windows needs the necessary Fishpack.dll and tuntap32.dll in its search path, so I added the path (Win2K control) C:\Programme\hercules and copied the dll´s to there. So, all hercules utilities can be run without path specification.
2.5.1	WinPcap (virtual Windows network adapter)
I used the network component CTCI-W32 later as I installed zLINUX. For this, I had to download a Windows driver that emulates a virtual network adapter: http://winpcap.polito.it/install/bin/WinPcap_2_3.exe. This program installs the driver.
Hint: the newer version WinPcap_3_0 didn´t work.
After installation, you can use the virtual adapter on your local PC. If you want to reach the adapter from the network around, you have to set a Windows registry entry:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters]
"IPEnableRouter"="1" (WIN2K/XP)
[HKEY LOCAL MACHINE\System\CurrentControlSet\Services\VxD\MSTCP]
"EnableRouting"="1" (Win98/ME)
With this, Windows becomes an „IP-Forwarder“ and routes IP-packets from and to the virtual adapter over the real network card. In the network itself, the routers must get an host entry (either manually or via RIP).
2.5.2	Problem with local TCP connections
The local connections between the win2K hosting system and hercules (172.16.19.250 and 172.16.19.251) worked at first only for ping and traceroute, neither telnet nor ftp was possible The problem didn´t exist for real LAN connections.
The reason was the configuration of my 3com network adapter: in the Win2K driver was selected, that the adapter hardware should do the IP checksum calculation instead of the Windows driver.
To solve the problem, I had to reconfigure my network adapter (Windows LAN options: network adapter), so that hardware checksum calculation for receive and send is deactivatet.
Ping and traceroute seem to check only the income of packets, not the packet length/content itself (which get no checksum field for PC-internal transfers).
2.5.3	Activation of WinPCap
The packet.dll (necessary for CTCI-W32) is not loaded automatically for the first time but must be called once by executing the program testapp.exe from the WinPCap developper package: http://winpcap.polito.it/install/bin/WPdpack_2_3.zip (unpack only this program and to directory C:\Programme\hercules !).
Important: testapp.exe asks you for the network adapter and falls then into endless tracing – I stopped it with CTRL-C.
The program testapp.exe must be run with administrator rights (Shift-right mouse button, “run as“), else it will not install the NPF driver. You can check this by running “START” – “execute” – “msinfo32” – “Software” – “driver”. When you find the “netgroup packet filter” (“npf” or “NPF”), the driver is loaded.
Under Win2K, I had to run testapp.exe only once (after installation). From then, the npf driver was loaded automatically after Windows-Start.
2.5.4	Fishpack.dll
Now, you can install the Fishpack.dll
http://home.sprintmail.com/~dtrout/Hercules/FishPack-1.0.2.288-dll.zip
and extract it to C:\Programme\hercules too
2.5.5	TunTap32.dll
Not to forget the TunTap32.dll, download it from :
http://home.sprintmail.com/~dtrout/Hercules/TunTap32-1.0.2.360-dll.zip
and extract it to C:\Programme\hercules.
2.5.6	Hercules.cnf
The network adapter was specified in hercules.cnf as
0C00    3088   CTCI-W32 172.16.19.251 00-50-DA-36-BA-23 1024 64
0C01    3088   CTCI-W32 172.16.19.251 00-50-DA-36-BA-23 1024 64
Thereby, 172.16.19.251 was the virtual adress of the Hercules virtual network adapter and the macaddress was the real one of my 3com adapter (ipconfig /all).
In a second test, I specified the Win IP address instead of the macaddress:
0C00    3088   CTCI-W32 172.16.19.251 172.16.19.250 1024 64
0C01    3088   CTCI-W32 172.16.19.251 172.16.19.250 1024 64
but care with DHCP ! (Currently, I use a fixed address)
The pair 0C00/0C01 is actually in our OS/390 for several hardware in the IODF as 3088 defined, later, I will test an OS/390 network connection with this.
3	Runtime
3.1	First start of Hercules
Before I started Hercules first, I downloaded and modified a sample dataset of hercules.cnf from internet (searched in YAHOO). This dataset contains parameters and device information for Hercules.
The address of the tn3270 session can be specified, for example with “devicetype” in Attachmate EXTRA!. If nothing (or simply “3279”) is specified in the 3270 session, Hercules fills the 3270 list from low to high. For a fixed relation, you have to specify for Attachmate EXTRA! under the connection options the devicetype IBM-3279@0A81, Hercules assigns this session then to the S/390 address 0A81.
The first start of Hercules brought a message, that dataset „tuntap32.dll” was not found. As I didn´t install nor use CTCI-W32 at this moment, I ignored it. After installation of CTCI-W32 (Chapter 2.5), the message disappeared.
To see error messages at Hercules startup, I called Hercules by hercules 2>a2 . Hercules abends then, but the message is captured in dataset a2. Else, Hercules clears the screen immediately after the error message.
I did my first IPL onto a dataset, which contained the IND$FILE binary downloaded file IPL DDRXA S (the VM/ESA disk image backup restore). The dataset was a device 00C (virtual card reader). Attachmate EXTRA! blocked the screen with the “clock”. First, we resetted the connection of our tn3270 session. (we experienced the same problem earlier with our “real” IBM-2074, so we could solve it quickly by adding WCCResetClock=TRUE to the [terminal] section of the EXTRA! session file .edp).
3.2	First startup of OS/390
The earlier transfered CCKDDUMP dataset of the OS/390 volume was defined as address 459.
I talked about the console assignment in chapter 3.1
The first IPL 459 results in an abend 7A7A (A7A=problem with service processor) and lead us to the knowledge, that Hercules runs per default in ILF mode (Integrated LINUX facility), an IBM “marketing gag” that prohibits execution of non-LINUX-systems on cheaper priced processors.
After we added PGMPRDOS LICENSED to the hercules.cnf, we got a non-ILF processor and could IPL without abend.
Another problem was, that the console (tn3270 session 0A81) was blocked with the „clock“ after a new line was written. We had the problem (specific to Attachmate EXTRA!) earlier with our IBM 2074 control unit and EXTRA! – solvable by adding WCCResetClock=TRUE (manually with Windows notepad) to the [Terminal] section of the session file (I called it “HERCMVS.EDP” under C:\programme\E!98\sessions).
4	zLINUX on Hercules
4.1	Download of the packages
I used the packages from http://www.marist.edu/linuxvm/, from which I downloaded:
http://linux390.marist.edu/download/inst.pdf	Installation Guide [IGD]
http://linux390.marist.edu/download/image.tape.bin	IPL´able tape image of the kernel
http://linux390.marist.edu/download/initrd.bin.gz	Initial RAM disk
http://linux390.marist.edu/download/initfs_small.tgz	Small root filesystem (for test)
http://linux390.marist.edu/download/initfs_big.tgz	Big root filesystem (optional) BIG
4.2	IPL zLINUX
4.2.1	Virtual tapefile
For the first IPL of zLINUX, you need a virtual tapefile (IBM-OMA-Format), consisting of the bootable kernel, a parameter file and a initial RAMDISK.
Virtual tapefiles consist of a descriptor file, which must reside in the subdirectory tapes (under the directory from which you call Hercules) and represents the TDF format (control information and links to the individual tape files).
After searching for sample definitions, I created a file /hercules/TAPES/zLINUX.boot.tdf with following content:
@TDF
TAPES/zLINUX/image.tape.bin		FIXED RECSIZE 1024
TAPES/zLINUX/parmfile.asc		TEXT  RECSIZE 1024
TAPES/zLINUX/initial.ramdisk_initrd.bin.gz FIXED RECSIZE 1024
TM
TM
EOT
4.2.2	Boot parameter
The trick is to specifiy the parmfile.asc as „TEXT“ so this dataset will be converted from ASCII to EBCDIC by the Hercules tape simulation. So I can edit this file simply with Windows notepad (or CYGWIN vi) without the need to convert it back to EBCDIC.
The first content of the parmfile.asc was
root=/dev/ram0 ro
The virtual tapefile was defined to hercules by the entry in hercules.cnf:
0200    3420   /cygdrive/d/uahaag1/hercules/TAPES/zLINUX.boot.tdf
and an IPL 200 was done.
LINUX uses the hardware console to communicate. Be shure not to use a command which must be aborted by CTRL-C, this is not possible ! If this happens: poweroff the mainframe (I mean: stopall, quit, recall Hercules ;-). So be nice, specify –c 3 when you use a ping…
Commands from the hardware console to zLINUX must be prefixed by a single point (“.ls –l”).
4.2.3	Network via CTC
When zLINUX starts from the compressed RAMDISK, it asks the network parameters for the CTC connection. After you specified all parameters, you have to respond with “YES”, else you are prompted once more for these parameters. Next comes my configuration:
Configuration will be:
Host name        : w0273herc
IP address       : 172.16.19.251
Net mask         : 255.255.255.0
Peer IP address  : 172.16.19.250
Net address      : 172.16.19.0
DNS IP address   : 172.16.160.250
DNS search domain: dsv-gruppe.de
Is this correct (Yes/No) ?

As the network connection initially didn´t work (chapter 2.5.2), I took the workaround to logon from windows to a AIX station and from there to the hercules virtual adapter 172.16.19.251.
4.3	Format DASD
4.3.1	Create the volumes
With the hercules utility dasdinit, I created the cckd volumes ZLIN01.cckd and ZLIN02.3390 in a CYGWIN bash. The second volume was used as swapspace, so I decided to create it uncompressed with 200 cylinders:
dasdinit –z ./disk/ZLIN01.cckd 3390-3 ZLIN01
dasdinit  ./disk/ZLIN02.3390 3390-3 ZLIN02 200
These volumes were given to Hercules dynamically with the Attach command and added to the hercules.cnf for a later restart (the same as dynamic IOCDS, you know ?!?).
After a damaged installation, I decided to run the root volume with shadowfile. So, the original volume file is kept, instead, updates to the root volume are written to a separate Windows dataset called shadowfile. This is not a feature of zLINUX but of Hercules and so available for all S/390 operating systems.
Hint: the possibility of a shadowfile was given by the parameters in hercules.cnf but the shadowfile will be used when the base file cannot be accessed in read/write mode, for example specified by the ro parameter: 
attach 0127 3390 /cygdrive/d/uahaag1/hercules/disk/ZLIN01.cckd cache=60 sf=/cygdrive/d/uahaag1/hercules/disk/ZLIN01.cckd_1 ra=2 ro
attach 0128 3390 /cygdrive/d/uahaag1/hercules/disk/ZLIN02.3390 cache=60 sf=/cygdrive/d/uahaag1/hercules/disk/ZLIN02.3390_1 ra=2
4.3.2	Defining the volumes to zLINUX
To force the use of the created volumes, I had to specify an additional parameter in parmfile.asc:
dasd=0127-0128 root=/dev/ram0 ro
The next steps follow the description in [IGD], „Chapter 4. Installation – native single image and LPAR – OS/390“.
After zLINUX came up, I formatted the new disk volumes in a zLINUX shell (ZLIN02 is used as 200 cylinder swap volume)
dasdfmt -b 409-6 -f /dev/dasda
mke2fs -b 4096 /dev/dasda1
dasdfmt -b 4096 -f /dev/dasdb
mkswap /dev/dasdb1
chmod 600 /dev/dasdb1
swapon /dev/dasdb1
(Checked by cat /proc/dasd/devices and cat /proc/swaps)
4.3.3	BIG-Filesystem
These formatted compressed ckd volumes had an initial size of 8 MByte as Windows files. On ZLIN01, I copied the “Big” filesystem with intermediate use of our OS/390 (my PC´s disk was too small):
1.	Created a HFS in our OS/390 OpenEdition S1M3 with approx. 120 Mbyte / CYL(100 50)
2.	Mounted this filesystem in S1M3 as /u/UAHAAG1/tmp and transferred the BIG filesystem with binary FTP from my PC Download directory to S1M3 into the /u/UAHAAG1/tmp directory
3.	Added mount directory (prefixed by /hfs, suffixed by -ro) to OS/390 NFS definition SYS1.TCPPARMS(EXPORTFS) and refreshed the OS/390 NFS daemon by F MVSNFS,EXPORTFS on the OS/390 Console.
4.	Created in zLINUX rootsession on the PC with mkdir /mnt/s1m3 a mountpoint and mounted the OS/390 HFS by mount 172.25.1.133:/hfs/u/UAHAAG1/tmp /mnt/s1m3
5.	Mounted the Hercules volume ZLIN01 under zLINUX by
 mkdir /mnt/dasda1 und mount /dev/dasda /mnt/dasda
6.	Unpacked the BIG filesystem to ZLIN01 by
cd /mnt/dasda1
tar xfzBp /mnt/s1m3/big.root.filesys_initfs_big.tgz
7.	Created swap volume by
mkswap /dev/dasdb1
4.3.4	Modification of the BIG-Filesystem
We have to customize the fstab of the BIG filesystem. So, we create a mountpoint if it not already exists (mkdir /mnt/dasda1) and mount the BIG-Filesystem there (mount /dev/dasda1 /mnt/dasda1). Dort wird unter /mnt/dasda1/etc die fstab wie folgt modifiziert (die Zeile mit dem swapspace). Now, we can edit the /mnt/dasda1/etc/fstab:
/dev/dasda1	/	ext2	defaults ,errors=remount-ro	0	1
/dev/dasdb1	swap	swap	defaults	0	0
none	/proc	proc	defaults	0	0
The network configuration files should be copied from the RAMDISK to the BIG filesystem:
cp -rp /etc/sysconfig/network-scripts/ifcfg-ctc* /mnt/dasda1/etc/sysconfig/network-scripts/
cp -rp /etc/resolv.conf /mnt/dasda1/etc/
Notice: in the following IPL from ZLIN01, the network parameters were asked again, so maybe the previous copy doesn´t make sense.
4.3.5	Prepare and run IPL von ZLIN01
First of all, I activatet the shadowfile support for ZLIN01, so updates to the ZLIN01 volume could be easily removed by deleting the shadowfile. So I added the ro parameter to the hercules.cnf for the volume 127. (Chapter 4.3.1).
Following the document [IGD] chapter 4, I changed to the boot directory of the BIG filesystem by cd /mnt/dasda1/boot.
Here, we modify the existing file parmline :
dasd=0127-0128    root=/dev/dasda1 ro noinitrd
To create an IPL record (boot record) on the ZLIN01 volume, we have to use silo. First, I run a test:
/mnt/dasda1/sbin/silo -f image -d /dev/dasda -p parmline -b ipleckd.boot
and, assuming, there are no problems, we write it to disk with the parameter –t2:
/mnt/dasda1/sbin/silo -f image -d /dev/dasda -p parmline -b ipleckd.boot –t2
Now it is the time to restart zLINUX with shutdown or halt (lead to disabled wait) and the Hercules command IPL 127.
zLINUX asks the network parameters again but only once. They were kept on the new filesystem and used automatically for the following IPLs.
Now, zLINUX with the BIG filesystem is installed and contains an Apache webserver, an X-Client aso. and the DNS resolution is active.
A. Haag, IVP1