This document describes how to install ClefOS on z/VM using ZNETBOOT. The target audience is those who are skilled at using and installing Linux but not knowledgeable about z/VM or CMS. The purpose of this document is to enable installation of ClefOS as quickly and painlessly as possible by those who don't know CMS or z/VM.
While this document was written specifically for ClefOS, it is applicable for NORD, SUSE, OpenSUSE, Debian, Fedora, or any other Linux which can run on IBM Z architecture. In fact, the ZNETBOOT utility could theoretically be used for installing any operating system capable of running on IBM Z as long as the OS kernel can be retrieved from the web.
You will need a virtual machine. On z/VM, a virtual machine is also referred to as a user, and a user is assigned to a specific virtual machine. As a general purpose operating system, z/VM provides interactive computing services by defining each user as a virtual machine, typically running CMS. But being true virtual machines, "users" of z/VM can run any operating system suitable for the IBM Z architecture.
On z/VM, users (virtual machines) are also commonly referred to as "guests". The operating system you run in your virtual machine is called a "guest operating system" and z/VM is the "host".
Your virtual machine should be defined for at least 1G of memory (RAM, "storage") and have at least one disk of 5G or more (about 7000 "cylinders" of 3390 type disk). The example here has two disks, 1B0 and 1B1, both 10000 cylinders. The addresses and sizes of your disks will vary, but are by convention a three or four hexadecimal digit number (here, '180', as a leading zero is conventionally dropped).
Your virtual machine should also have a virtual NIC. The z/VM sysadmin will determine whether your NIC is set for Layer 2 or Layer 3 (of the seven layer ISO networking stack) and you will need to adjust the installation accordingly. The NIC will likely be coupled to routed network to a virtual switch. (No changes needed for virtual switch versus other connectivity modes.) In this example, the virtual NIC is defined at 340. The address of your NIC will probably be different.
If DHCP is available, it will provide IP address, routing, and nameserver assignment. In that case, all one usually needs to know is the network device name, and the system handles setting up network connectivity. If DHCP is not present, one should gather the following information:
- Device name: (form:
enccw0.0.0340
): - IP v4: (form:
192.168.0.100
): - Netmask: (form:
255.255.255.0
): - IP gateway: (form:
192.168.0.1
): - Nameserver: (form:
8.8.8.8
):
Additionally, your virtual machine should have standard CMS requirements, either an SFS space to serve as "filemode A" or (better) a 191 minidisk to serve as your "A disk". You will of course need z/VM TCP/IP connectivity. (When running CMS, you should be able to run standard end-user internet tools and client utilities.)
CMS is a single-user operating system available on z/VM for
interactive work. When installing Linux, CMS acts as a self-sacrificing
[chained] loader: It provides the underpinnings to do the uploads
and run the ZNETBOOT utility. (see next) Once the kernel and other
requisite files have been fetched and arranged, control is handed off
to your virtual machine, which will perform the rough equivalent of a
kexec()
function and then, CMS will step aside and vanish.
(thus: 'self-sacrificing')
You will also need the ZNETBOOT tool, or at least two files from that
package. Specifically, you will need ZNETBOOT EXEC
and CURL REXX
.
(Filenames in CMS are two part, divided by blank space. Those files
would be znetboot.exec
and curl.rexx
on most other systems.
CMS is indifferent as to capitalization.)
Uploading via X3270 is explained. If you use some other means than X3270 to connect with your z/VM host, your upload experience will be different.
A third required file is CLEFONVM ZNETBOOT
(aka clefonvm.znetboot
),
which will hold bootstrap parameters unique to your virtual machine.
It must either be created with the CMS text editor xedit
or must be
created on your desktop or laptop and then uploaded. There is an
example included with the ZNETBOOT package and on the web, but the
example will not work for your virtual machine because you will
minimally have different network addresses.
Note: if you're in the middle of installing Linux and get interrupted
you can safely #cp logoff
from the virtual console (3270 session).
Using the local x3270
command, connect to your z/VM host.
The z/VM logon screen will present three fields: USERID
, PASSWORD
,
and COMMAND
. Ignore the last one, COMMAND
. Type your virtual
machine name in the USERID
field. Advance the cursor by pressing
<Tab>. Type your password in the PASSWORD
field.
(The field has a display 'masking' for that class of a field,
so the plain text of the password will not be displayed.)
After you have typed your userid and password, press <Enter>.
Your virtual machine should boot CMS, quickly presenting a "Ready;" prompt. (CMS does not take long to boot.)
Look at the lower right corner of your X3270 window for a status indicator.
If you see VM READ
, then press <Enter> again (just one more time).
You should then see RUNNING
in the status area.
Retrieve the following files and upload them to z/VM.
- http://www.casita.net/pub/znetboot/znetboot.exec
- http://www.casita.net/pub/znetboot/curl.rexx
- http://www.casita.net/pub/znetboot/clefonvm.znetboot
You can use any web retrieval tool or method to make local copies of these files. The 'wget' command line tool will do nicely. In the latter case, it may make sense to make a local directory to store such:
$ mkdir s390x
and then move into it:
$ cd s390x
Then retrieve each of the three files:
$ wget http://www.casita.net/pub/znetboot/znetboot.exec
$ wget http://www.casita.net/pub/znetboot/curl.rexx
$ wget http://www.casita.net/pub/znetboot/clefonvm.znetboot
clefonvm.znetboot
is a template file, and will need to be tailored
to the specifics assigned by your provider for your virtual machine.
Use your favorite plain text editor and amend the IP address, netmask,
network, and DNS server accordingly. Some of the statements,
for example ...
IPADDR=192.168.0.100 <<< your IP address goes here
NETMASK=255.255.255.0 <<< your IPv4 netmask goes here
GATEWAY=192.168.0.1 <<< your IPv4 gateway goes here
... and so forth. Save your changes to that file, then upload all three files to your virtual machine.
Note that the installer often requires more boot parameters
than can fit on a standard boot parm line, so you may need to
prefix statements with ZNETBOOT_TOFILE=
. This will direct
ZNETBOOT to store those statements in an auxiliary CMS file.
(More on that some other time.)
These are all plain text files, not binary.
To upload, use the X3270 file transfer dialogue. Hold down the left mouse button to bring up the "File" menu. Slide down to "File Transfer ...".
Within the "File Transfer" dialogue, select "Send to host", "Host is VM/CMS", and "Transfer as ASCII file". Then click "Transfer File".
Files in CMS are identified with a filename, a blank,
and then a filetype. Therefore znetboot.exec
must be named
znetboot exec
on the "Host File Name" line. (This field is not
case sensitive, so feel free to enter it as lower case.)
Similarly for curl.rexx
and clefonvm.znetboot
When you have finished uploading the files, enter the following command:
znetboot clefonvm
ZNETBOOT will read your CLEFONVM ZNETBOOT file and begin trying to download the kernel and initrd (and as optionally specified in the kernel command line, a remote 'kickstart.cfg' file)
Depending on network connectivity between your z/VM host and the
repository, the CMS pipe
commands may take a while to run. Give it time.
ZNETBOOT will cache and queue-up the Linux files in your virtual reader and then once all are present, tell z/VM to boot from the reader (similar to booting from a tape drive). You should see dozens, even hundreds, of lines of Linux console output. z/VM will pause the output one screen at a time. (Be patient. There is a way to speed that up, but it is much easier just to let it ride.)
Once the installer has been brought up, you should see "Please ssh" ...
You should now do just that, use SSH to connect and finish the installation.
Congratulations!
At this point you are finished with the X3270 part of the task. The rest should be very familiar.
You may disconnect from the virtual console. This is optional. You can remain connected, but if you disconnect then z/VM will continue to run your virtual machine without any chance of network interruptions triggering unwanted console signals. Enter the command:
#cp disconn
The hash/pound-sign is not a typo. The command is #cp disconn
and
press <Enter>. (It's optional. You don't strictly have to disconnect.)
Whether you disconnect the virtual console or not,
use ssh
to connect and drive the rest of the installation.
This part will be very familiar to experienced Linux users.
The ClefOS installer will automatically reboot after normal completion. You do not need to be attached to your virtual console for this to happen. As a bonus for remaining connected, if you did stay connected, then you will again see many screens of Linux console boot message output scroll by.
If your networking parameters are correct and the installation
worked correctly, you can now open a separate terminal, and use an
SSH client to connect your shiny new ClefOS mainframe virtual machine.
If not previously set during the installation, please immediately set
a root
account password now.
Always set a unique and strong root password.
If an end user account is set up, a strong password there too.
Apply updates immediately:
yum clean all
yum -y updates
Add SElinux policy and netwrok descrption convenience packages:
yum install policycoreutils net-tools
Trigger an SElinux relabel:
touch /.autorelabel
The presence of this file will trigger SElinux relabel next boot.
SElinux relabel will take effect.
Optionally set up "keyed SSH access":
$ umask 077
$ mkdir .ssh
$ cd .ssh
$ touch authorized_keys
$ vi authorized_keys
Assuming the PUBLIC half of the key is on the clipboard, the key sequence:
A <paste> :w!:q!
and then see that it was cleanly saved:
$ wc -l authorized_keys
## should return 1 line
$ cat authorized_keys
## should contain that PUBLIC key
Recovery is sometimes possible; other times it seems more expedient to re-install to fix a typo.