Skip to content

Latest commit

 

History

History
297 lines (212 loc) · 10.8 KB

clefonvm.md

File metadata and controls

297 lines (212 loc) · 10.8 KB

ClefOS-on-VM

Installing ClefOS on z/VM

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

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:

  1. Device name: (form: enccw0.0.0340):
  2. IP v4: (form: 192.168.0.100):
  3. Netmask: (form: 255.255.255.0):
  4. IP gateway: (form: 192.168.0.1):
  5. 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

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

Sign On

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

logon.png

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

ready.png

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.

Upload ZNETBOOT

Retrieve the following files and upload them to z/VM.

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

filetrans.png

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

Run 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)

znetboot.png

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

anaconda.png

You should now do just that, use SSH to connect and finish the installation.

Install ClefOS

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.

Reboot

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.

Hardening

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.

Reboot again

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

done

Recovery is sometimes possible; other times it seems more expedient to re-install to fix a typo.