Read zPDT: Installation and Basic Usage text version

Front cover

Draft Document for Review September 4, 2009 10:36 am SG24-7722-00

System z Personal Development Tool: Volume 2

Installation and Basic Use

System z Development Tool

Full z/OS usage

Linux base

Bill Ogden

Draft Document for Review September 4, 2009 10:36 am

International Technical Support Organization zPDT: Installation and Basic Usage June 2009


Draft Document for Review September 4, 2009 10:36 am

Note: Before using this information and the product it supports, read the information in "Notices" on page v.

First Edition (June 2009) This edition applies to the IBM 1090 system (known as zPDT) that is available at the time of publication. Note: This book is based on a pre-GA version of a product and may not apply when the product becomes generally available. We recommend that you consult the product documentation or follow-on versions of this redbook for more current information.

© Copyright International Business Machines Corporation 2009. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Draft Document for Review September 4, 2009 10:36 am


Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii The team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Chapter 1. Linux and 1090 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Disk planning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Linux installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.1 x3270 keyboard maps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.2 Other Linux notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.3 Install the 1090 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.4 1090 hardware key activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.4.1 IBM Resource Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.5 Installing a new 1090 release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Chapter 2. AD CD z/OS installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 General principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 System z operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Packages for the 1090 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 Installing an AD system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 Specific installation instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.2 IODF device numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.3 1090 control files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.4 IPL and operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.5 Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.6 Startup messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.7 Local volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5 z/OS parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 Multiple operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3. LANs and TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.0.1 Overview of LAN usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Simple OSA LAN usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 LAN and tunnel usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Routers and DHCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Wireless connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5 z/OS TCP/IP profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6 Telnet to z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7 Choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8 Useful networking commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4. Basic zPDT commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1 Setup commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Basic operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 CP commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 17 18 18 19 19 19 20 21 22 23 24 24 25 25 27 27 29 31 33 34 35 36 37 37 39 39 40 42

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

4.4 Devmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Chapter 5. Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Appendix A. z/OS 1.10 AD CD example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1 Disk planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2 Connectivity planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.3 Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B. Linux installation examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.1 SUSE 10.3 (32-bit) installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.1.1 openSUSE 10.3 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.2 openSUSE 10.3 (64-bit) installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.2.1 Driver for NVIDIA graphics adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.3 IBM Open Client 2.2 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.3.1 OC2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to get Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 51 51 52 57 57 58 58 60 61 62 65 65 65 65 65

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am


IBM, the IBM logo, and are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or TM), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

CICS® DB2® IBM® PartnerWorld® Redbooks® Redbooks (logo) Resource LinkTM S/390® System z® VTAM® WebSphere® z/Architecture® z/OS® z/VM® z/VSETM zSeries®


The following terms are trademarks of other companies: SUSE, the Novell logo, and the N logo are registered trademarks of Novell, Inc. in the United States and other countries. Red Hat, and the Shadowman logo are trademarks or registered trademarks of Red Hat, Inc. in the U.S. and other countries. Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


This IBM® Redbooks® publication introduces the IBM System z® Personal Development Tool (zPDT), which runs on an underlying Linux® system based on an Intel® processor. zPDT provides a System z system on a PC capable of running current System z operating systems, including emulation of selected System z I/O devices and control units. It is intended as a development, demonstration, and learning platform and is not designed as a production system. This book, providing specific installation instructions, is the second of three volumes. The first volume describes the general concepts of zPDT and a syntax reference for zPDT commands and device managers. The third volume discusses more advanced topics that may not interest all zPDT users. The OBM order numbers for the three volumes are SG24-7721, SG24-7722, and SG24-7723. The systems discussed in these volumes are complex, with elements of Linux (for the underlying PC machine), z/Architecture® (for the core zPDT elements), System z I/O functions (for emulated I/O devices), and z/OS® (providing the System z application interface), and possibly with other System z operating systems. We assume the reader is familiar with the general concepts and terminology of System z hardware and software elements and with basic PC Linux characteristics.

The team that wrote this book

This series of IBM Redbook publications was produced by the zPDT development team, with assistance from many other people Bill Ogden is a retired Senior Technical Staff Member at the International Technical Support Organization, Poughkeepsie. He enjoys working with new mainframe users and entry-level systems. Thanks to the following people for their contributions to this project: Keith VanBenschoten, IBM Poughkeepsie, was very helpful in establishing installation and startup processes for the 1090 and in providing test systems. Theodore Bohizic, IBM Poughkeepsie, helped us understand command, design, and internal details. Richard Brandle, IBM Dallas, helped with much of the practical usage information incorporated in this redbook. Kelly Ryan, IBM Poughkeepsie, provided importance directions for determining user levels and associated support requirements.

Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

technologies. You'll have the opportunity to team with IBM technical professionals, Business Partners, and Clients. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at:

Comments welcome

Your comments are important to us! We want our Redbooks to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: Send your comments in an email to: [email protected] Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400 T

Note to Author: When writing the preface, define your audience and tell the reader what the book is about (features and benefits). Summarize the content in a way to help sell your book instead of listing every part and chapter.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Chapter 1.

Linux and 1090 installation

The 1090 operates as a normal Linux application. IBM support assumes certain patterns of installation and usage. The "supported" bases for zPDT, both hardware and software, are described in Volume 1 of this series of documents. We strongly recommend that the general procedures described here be followed for initial 1090 usage. After you have gained some experience with the 1090, you can explore other installation and usage arrangements. Many of our choices are arbitrary and simply reflect our preference for a simple Linux. We assume the PC is dedicated to Linux, with the 1090 application used when wanted. If this is not the case, we suggest obtaining a separate hard disk for the Linux disk if this is possible. The original hard disk can then be used for its original purpose. If this is not appropriate, then a dual boot environment might be created. There are so many variations possible that we do not attempt to provide specific instructions for creating dual boot installations. You should ensure that sufficient free disk space is available for Linux and your emulated System z volumes. For Linux and a very small z/OS you should have at least 40 GB of free disk space. Virtual environments, such as with VMWare or Xen or similar product environments, are not supported. Informal attempts to use these environments have almost always been unsatisfactory. The fundamental issue is that zPDT, with z/OS running under it for example, is a large, heavy, complex environment that pretty much consumes the PC running it. It also introduces timing constraints (for the many timers that z/OS has running internally) that do not fit well in an extended virtual environment. We elected to install Linux with fixed IP addresses, with firewalls and other security elements disabled. This was to ease communication in a private LAN environment (connected to a small, personal router). Your needs may be different. The 1090 functions are not related to these controls, except that you may need to open firewall access for TCP/IP connections to the 1090 functions.

Ordering requirements

This document does not provide detailed ordering information. The ordering process may differ for various categories of users and for different countries. Whatever ordering process is used should result in the following:

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

A 1090 token (which may need to be activated via an IBM business partner or through IBM ResourceLink). The 1090 software, which must be installed before the token can be activated. The 1090 software does not include any System z operating systems. One of the zPDT-supported Linux distributions. This may need to be ordered, or it might be downloaded from a Web site. Whatever System z software you plan to use, in a format usable with the 1090. This may require a different ordering process than ordering the 1090 itself. The remainder of this document assumes you have acquired the z/OS AD-CD package to use with your 1090. For IBM internal users, the ordering process can be summarized as follows: 1. Submit an RPQ request for the 1090. 2. When the RPQ is approved, order the 1090 via the standard IBM System z ordering process for your country. What you are actually ordering is the 1090 token. 3. Obtain one of the zPDT-supported Linux distributions for your PC. This typically involves downloading a DVD from a web site. 4. You then order the 1090 software, or it can be downloaded from ResourceLink. You need this software to activate the token. 5. IBM internal users can request the AD-CD package. This is a prepackaged z/OS system in a format usable with the 1090. Much of the material in this document assumes you will install the z/OS AD-CD system. If you are installing different System z software, you need to obtain specific instructions for the 1090 from the supplier of that software.

Installation overview

A summary of the usual installation sequence is this: 1. Read this series of books. You may not remember all the details at this stage, but you should skim through most of the material before starting. Remember to work as root when indicated and as another userid (ibmsys1 in all our examples) when indicated. If you are new to Linux or the 1090, install a simple system first, before attempting something more complex. 2. Think about your disk partitioning, especially if you plan to install major applications in addition to the 1090 package. 3. Gather the required software packages: ­ Linux for your base PC. (An example would be an openSUSE or Red Hat® Enterprise Linux distribution on a DVD). Be certain you have the correct Linux (32- or 64-bit version). ­ The 1090 software (which might be obtained on a CD or DVD, or by a download). · You need the sntl-sud and shk-server prerequisite programs. · You need the z1090 installer program and z1090 rpm. There are multiple versions of these programs, as described later. ­ Your System z software (z/OS, z/VM®, or z/VSETM) in a format usable with the 1090. 4. Follow the installation steps described later in this chapter: a. Install Linux. Several specific examples of this are described in an appendix. b. Install x3270 (or another 3270 emulator) if it is not included in your base Linux distribution. Optionally, customize the x3270 keyboard. c. Create group ibmsys and userid ibmsys1.1 d. Install two 1090 Linux prerequisite packages.


This is not required. However, all our examples assume that the 1090 is operated through Linux userid ibmsys1. Do not attempt to operate the 1090 while working as root.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

e. Install the 1090 package. f. Customize several Linux files (sysctl.conf, /etc/profile.local, /etc/profile, .bashrc). g. Optionally, customize the x3270 keyboard, and install a sample devmap. 5. Activate your 1090 token, as described in "1090 hardware key activation" on page 12. You cannot do this until the 1090 package is installed. (This step may be done by a business partner.) 6. Generally following Chapter 3, install z/OS or other System z software: a. Select the AD distribution (or another System z operating system) b. Unzip or untar the volumes. c. Customize or create a devmap. d. Start the 1090 and IPL your operating system. 7. After you have run a basic system, you might consider more advanced LAN configurations. As is often true with new hardware and software combinations, remember that a given Linux level may not support the newest PC hardware. This is most often seen with new LAN adapter chips, and with new graphics chips and/or display screens. Support for these may require additional Linux drivers or upgrades. If you have a very new PC model, or an unusual configuration, you may need to verify that your Linux version is completely operational on your hardware.

1.1 Disk planning

During Linux installations we usually create three partitions on the hard disk: A root partition for Linux (including the various 1090 files). We usually make this about 8 GB although this is larger than needed. This partition contains all the normal Linux root directories, such as /usr, /lib, /home, /etc, and so forth. If you have additional major applications installed (other than basic Linux functions), this partition may need to be much larger. A swap partition for Linux. We suggest 2 GB (or larger). Small Linux system on a 32-bit system seem to work well with a 2 GB swap partition. Larger Linux systems should have a larger swap partition. A common recommendation is (real memory size) + 2 GB, although this may result in some wasted disk space. A large partition for emulated System z volumes. We mount this partition as /z. We normally use all the remaining space on the disk drive for this partition. This disk usage layout is not required. You could make many partitions for the various standard Linux directories. You could place emulated volumes in various directories under /home. You could place emulated volumes in /tmp, and so forth. We recommend our disk layout as a starting point solely because it is simple and it isolates emulated System z volumes from the normal Linux files. This isolation is useful if you reinstall Linux (without disturbing your emulated volumes) and it may have minor performance benefits because it tends to reduce fragmentation in the disk space used for large emulated volumes. If you plan a dual boot system, then you will have at least one more partition (probably for Windows®). You will probably need to shrink the existing Windows partition to make room for the new partitions. The various ways to do this are not covered in this document.

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

1.2 Linux installation

Install your Linux distribution. You might select only those packages that are needed for basic Linux operation, or you might install everything in your distribution. We make the following suggestions: Select Universal Time (UTC) for your base PC, if this is possible. (This may not be possible if you also run Windows on the same PC. Do not consider changing the PC time-of-day when switching between Linux and Windows; this can disrupt your zPDT usage.) For Red Hat releases we recommend including the dmidecode rpm. For SUSE® releases we recommend including pmtools. Both these packages include the upddecode tool. This is optional, but it provides additional diagnostic information if there is a problem with zPDT. We always use gnome as our desktop manager, and this is reflected in our examples. You could select KDE (we have no indication that it would not work with zPDT). We recommend the k3b package for burning DVDs. It seems to adapt to more different drive types than other packages. We avoid installing beagle. This is an automatic indexing tool that apparently tries to index almost all files, including System z emulated volumes. We found that it consumed substantial processor time and slowed zPDT operation. This was in earlier Linux releases (SUSE 10.1, for example), and this problem may not exist in current releases. We usually install telnet-server, although this is an insecure service. It is not necessary to use it, but it is convenient to have it installed if a simple telnet session to the zPDT machine is needed. (All zPDT functions can be run remotely, through telnet or ssh or other packages.) Install x3270 if it is included in your Linux distribution. It is not installed by default. You may need to search diligently to find it, or to determine it definitely is not present. Generally, we find that the Linux installer provides a way to specify installation packages at the rpm level, but some effort may be needed to find this path. Install vsftp or some other Linux ftp package. It is not needed for zPDT use, although you may want to transfer files between Linux and z/OS using ftp. The X Software Development package may be needed if x3270 is not included in the initial installation and is to be installed later. We have recently found it advisable to perform an online update for Linux, if this is possible for your Linux distribution. Determine if additional drivers or driver updates are needed for your specific PC. At the time of writing, Red Hat Enterprise Linux 5.3 was our primary base Linux. The following script illustrates how we installed it on a W500 laptop. Many of our choices are arbitrary. (boot from DVD) (The installer was unable to work in graphic mode on our particular laptop) Media test: <skip> Language selection: English <OK> Keyboard selection: US <OK> Installation number: skip entering Installation Number <OK> Partitioning type: Create custom layout <OK> Device Start End Size Type Mount Point /dev/sda sda1 1 1084 8002M ext3 / sda2 1085 1355 2000M swap sda3 1356 25841 180775M ext3 /z 4

zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

<OK> Boot Loader Configuration: Use Grub <OK> Boot Loader Configuration: <OK> Boot Loader Configuration: (no password) <OK> Boot Loader Configuration: boot label=Red Hat Enterprise... <OK> Boot Loader Configuration: /dev/sda Master Boot Record (MBR) <OK> Configure Network Interface: Yes Configure Network Interface for eth0: Activate on boot Enable IPv4 support <OK> Configure Network Interface for eth0: Manual address configuration IP= / <OK> Miscellaneous Network Settings: Gateway= <OK> (no DNS specified) Hostname Configuration: manual = W500 <OK> Time zone: (as needed) (system clock uses UTC) <OK> Root password: xxxxx (be certain to check the shift key first!) Package Selection: Customize software selection <OK> Administration tools Development Libraries Development Tools Editors Gnome Desktop Environment Graphical Internet Graphics Legacy Network Server (optional: select telnet-server, inetd via F2) Legacy Software Support Network Servers (this provides a VNC server) Office / Productivity (optional) Server Configuration Tools Sound and Video System Tools (do not select x3270 via F2) Text-based Internet X Software Development (needed for later x3270 installation) X Window System <OK> Installation to begin: <OK> (takes a while to install packages) Reboot: <OK> Setup Agent: Authentication: Run Tool: Use MD5 passwords Local authentication sufficient <next> Setup Agent: Firewall Config: Run Tool: Security level disabled SELinux disabled <OK> <Exit> At this point we were presented with a "teletype mode" (non-graphic) login. Our W500 laptop high-resolution screen (1920x1200) was not recognized by our new Linux system. If your system enters a normal graphic mode, the following steps are not needed. login: root # init 5 switch to graphics mode (screen blinks several times) Failed to start the X server .... Like to view error details...? <No> Like to try to configure X server...? <Yes> (several messages, pauses, blinks) Display settings Resolution 800x600 (no other useful choices available) Display Settings changed <OK>

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

Trying to restart the X Server <OK> (blinks several times. Should then switch to full resolution) # gedit /etc/inittab find line: id:3:initdefault: change to: id:5:initdefault: As noted in the script above, we suggest you disable SELinux ("SEL") for initial 1090 usage, or set it to permissive. Otherwise, you may have permission problems when starting the 1090, with messages such as the following:2 /usr/z1090/bin/ cannot restore segment prot after reloc: Permission denied

TN3270e clients

IBM has used these TN3270e clients with the 1090 offering: x3270 (recent versions) Recent PCOM releases (running on Windows systems) PowerTerm with the IBM Open Client system We most commonly use x3270. Our last step in the installation we are describing was to install x3270, since a full version was not included with the RHEL 5.3 server DVD. We installed two packages from a DVD by mounting the DVD and clicking on the two rpm names. (The two rpm packages were obtained by downloading them from the Web.) Our packages, in the order they must be installed, were: x3270-3.3.4p7-3.e15.1.i386.rpm x3270-x11-3.3.4p7-3.e15.1.i386.rpm Other x3270 levels may be used, or another 3270 emulator may be used. In order to install these two rpms, we found it was necessary to include the X Software Development package when we installed RHEL 5.3 Linux. Note that this particular x3270 version did not include the keyboard map file we describe next.

1.2.1 x3270 keyboard maps

The default x3270 keyboard assignments are not in the traditional 3270 style. In particular, the large Enter key on the PC keyboard functions as the 3270 Enter key. With traditional 3270 keyboards this same key provides a new line function and the 3270 Enter key is located where the right-hand Ctrl key is located on most PC keyboards. There is no requirement to change the default x3270 keyboard mapping. If you prefer the more traditional mapping, use the following steps (working as root):3 # cd /usr/share/X11/app-defaults This directory may contain file X3270 (with an upper case letter X). Use the appropriate path to app-defaults for your Linux and verify that file X3270 is present. If it is not present, you could consider using a local x3270 profile, described later. # gedit X3270 (use your favorite editor) (scroll to the stanza named X3270.keymap.base.3270: #override) (scroll to second line in this stanza): ...

2 3

We experienced this with RHEL 5.2. We did not try running RHEL 5.3 with SELinux enabled. Do not place any blank lines, tab characters, or extra blanks at the end of the lines within these definitions! The X3270 file appears to be very sensitive to unexpected characters within the definitions. Some Linux distributions do not contain this file and customizing x3270 for these distributions can be more challenging.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

Shift<Key>Return: :<Key>Return: :<Key>Linefeed: :<Key>Backspace: <Key>Control_R: <Key>Control_L: <Key>Return: <Key>Pause: <Key>BackSpace: <Key>KP_Enter: <Key>End: <Key>Prior: <Key>Next: Shift<Key>Tab: ...

Newline()\n\ Enter()\n\ <-- delete this line Newline()\n\ <-- delete this line Erase()\n\ <-- delete thisline Enter()\n\ <-- add these lines Reset()\n\ Newline()\n\ Clear()\n\ BackSpace() Delete()\n\ Enter()\n\ <---optional EraseEOF()\n\ <-- optional PF(7)\n\ <-- optional PF(8)\n\ <-- optional BackTab()\n\

Notice that the 3270 screen defaults to model 4 (with 43 lines). Our ThinkPad keyboard contained extra keys associated with Microsoft® Windows usage, making the left and right Ctrl keys smaller than they are on some keyboards. We did not attempt to map these Windows keys to any 3270 function. As a result of these changes to the keymap, common 3270 functions are as follows: Function 3270 Enter 3270 Reset 3270 Clear Next line PA1 PA2 F13 Key Right-hand Ctrl key or the numeric keypad Enter key Left-hand Ctrl key or alt-r Pause or alt-c Large Enter key on keyboard alt-1 alt-2 shift-1

You can adapt these instructions to other x3270 versions or simply use the default keymap distributed with x3270.

Local x3270 profile

An alternative to altering the app-defaults/X3270 keyboard map (or if this file does not exist) is to override the x3270 default keyboard using a profile in your home directory. To do this, create a file (in your home directory) named .x3270pro (note the period as the first character of the file name): ! Use Bill's overrides x3270.keymap: bill ! Define the overrides x3270.keymap.bill: #override \ <Key>Control_R: Enter()\n\ <Key>Control_L: Reset()\n\ <Key>Return: Newline()\n\ <Key>Pause: Clear()\n\ <Key>BackSpace: BackSpace() Delete() It seems that x3270 keyboard files are very sensitive to extra spaces and tab characters. Do not have anything after the \n\ in the text lines. In this file, we spaced the <Key> field starting in column 4, although this was arbitrary.

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

x3270 fonts

If x3270 is installed from a separate source, it may not have its normal fonts. In the x3270 fonts menu there is an option for iso fonts. We selected the following one: -eti-fixed-bold-r-normal--18-180-72-72-c-90-iso8859-1 The 18 that is embedded in the name is the point size. A similar choice, with 24 in this position selected a larger font.

1.2.2 Other Linux notes

Appendix B, "Linux installation examples" on page 57 provides comments about other Linux installations we experienced earlier. These descriptions may be helpful if you have problems. We found the following Linux commands to be useful for setup verification: $ $ $ $ ulimit -a ipcs -l /sbin/sysctl -a /sbin/ifconfig (display various limits for this user session) (lower-case l; shared memory limits) (many kernel and other system parameters) (LAN status)

Other Linux distributions

Other Linux distributions may work properly as a 1090 base. There is no formal IBM testing of other base Linux systems and IBM 1090 support is not available for other bases. Having said this, we are aware of users working with openSUSE 11.0, Red Hat Fedora, and build-it-yourself Linux versions. The 1090 has no code that is unique to the supported bases. However, the 1090 uses a complex set of Linux programs for its base function and it is possible that the library levels involved may not be compatible with other Linux distributions. As currently constructed, the 1090 software must be installed through rpm. Linux distributions that do not use rpm cannot be used for the 1090.

Multiple workspaces

The gnome window manager can provide multiple workspaces (or "screens"). Some versions provide four workspaces by default and some provide only a single workspace by default. To create more workspaces, right-click the bar on the bottom of the gnome screen. Select the Add to Panel menu item. Scroll to the bottom of the long list of items presented, select Workspace Switcher, and then Add it to the panel. Now right-click the new Workspace Switcher icon on the bottom bar and select Preferences. In the preferences panel select Show All Workspaces in 1 Row and set the number of workspaces to 2 or 3 or 4, depending on your needs. (We find that 2 is usually sufficient.)

Burning CDs and DVDs

We found that the k3b application created DVDs correctly but failed to create CDs correctly. We found that the Gnome CD/DVD Creator application created CDs correctly but had problems creating DVDs. We used k3b to burn DVDs and Gnome CD/DVD Creator to burn CDs. These problems may have been related to the particular CD/DVD Multiburner model in our laptops.

CD/DVD drive access

For the Linux distributions we used, the path used to access the CD/DVD drive is /media/xxxxx where xxxxx is the volume name or title of the CD/DVD. Whoever creates a CD/DVD can assign a title. You may be able to determine a CD/DVD title by observing the window title that is presented when the Linux automount function detects the new CD.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

Many of our examples use path /media/ROM to access the drive. This would be the correct path for a CD/DVD with the title ROM. A CD/DVD with a different title would have a different path name.

Linux PATH

We suggest that you do not add other directories before /usr/z1090/bin in the PATH and LD_LIBRARY_PATH variables. There are many commands and executed modules provided with the 1090 and these correspond to Linux file names that are accessed through the PATH variables. For example, the command d is used to display System z memory. If you should place another directory containing a file named d earlier in the PATH, then the 1090 d function would not be available in the normal manner. Various internal 1090 functions assume they can access 1090 modules via PATH and LD_LIBRARY_PATH; you must ensure this is possible.

1.3 Install the 1090

Note that $ prompts (throughout the examples in this document) indicate a non-root userid and # prompts indicate we are working as root. We recommend that you always login as ibmsys14 and then use an su command to switch to root when needed. The following directions assume that a single 1090 instance will be used. (Multiple 1090 instances require multiple userids, such as ibmsys2 and ibmsys3.) If you have not already done so, create group ibmsys and user ibmsys1, which should be a member of group ibmsys. (These specific names are not required; however, we use them consistently in all documentation.) By default, userid ibmsys1 has /home/ibmsys1 as its home directory and most 1090 control files appear in subdirectories here. We created file system /z as a separate partition during our Linux installation.5 We want userid ibmsys1 to own this file system: (logon as ibmuser1) # su # chown ibmsys1:ibmsys /z switch to root user ibmsys1 to own emulated volume directory

You need three rpms and one executable program to install the 1090 base functions. This section describes the installation of the following components: sntl-sud-7.4.0-0.i386.rpm shk-server-1.0.2-0.zp4.i586.rpm the primary z1090 rpm an "installer program" for the z1090 rpm (a driver for the 1090 token) (another token program) (cannot be directly installed)

The sntl-sud and shk-server programs need be installed only once and can be used with future 1090 updates unless new versions of these two programs are needed. The same two modules are used for both 32- and 64-bit Linux systems. The primary z1090 rpm and the installer program are available in four different versions. The exact names change with new 1090 releases, but the names are similar to the following: z1090-1- z1090-1- z1090-1-


(for openSUSE 32-bit Linux) (for openSUSE 32-bit Linux) (for openSUSE 64-bit Linux)


There is nothing special about userid ibmsys1. We consistently use it to illustrate 1090 operation. Any userid can be substituted for ibmsys1, but that userid should be consistently used for all 1090 installation and operation actions. This may not be the case for the IBM Open Client, but we ignore this exception here.

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

z1090-1- z1090-1- z1090-1-1-39.09.11.i386.RH.rpm z1090-1- z1090-1-

(for (for (for (for (for

openSUSE 64-bit Linux) Red Hat 32-bit Linux) Red Hat 32-bit Linux) Red Hat 64-bit Linux) Red Hat 64-bit Linux)

Note that these names contain SU or RH.6 The RH files are for Red Hat Linux and the SU files are for openSUSE Linux. Be certain to use the correct set. Within a set (openSUSE or Red Hat, 32- or 64-bit) one file is an rpm and one is not. Do not install the rpm file; the installation will fail. You need to execute the other file (the non-rpm file). It will process the 1090 license agreement and automatically install the rpm file. You do not directly process the 1090 rpm file. You can download (or copy) the rpms and executable program to your /tmp directory and install them from there. You may be able to install the rpms and the installer program directly from a distribution CD.7 Proceed with 1090 installation as follows: (logon as ibmsys1) $ su # cd /media/ROM or #cd /tmp (change to root) (if you can install from a CD) (if you copied material to /tmp)

# rpm -ivh --force --nodeps sntl-sud-7.4.0-0.i386.rpm # rpm -ivh --force --nodeps shk-server-1.0.2-0.zp4.i586.rpm If you have an earlier release of 1090 installed you need to manually delete links and programs8, as follows: # # # # # # rm rm rm rm rm rm /usr/z1090/bin/z1090pick /usr/local/bin/z1090pick /usr/z1090/man /usr/z1090/next /usr/z1090/prev /usr/z1090/bin (remove the old z1090pick program) (remove the other copy or z1090pick) (if it exists) (if it exists)

# rpm -e z1090 --allmatches (removes all previous 1090 versions, if desired) Select the proper z1090 rpm and installer program file names, and execute the installer program: # ./z1090-1- (verify the exact file name first)9

Scroll through the license and reply to the question about the license. The 1090 rpm is then installed automatically. The installation does the following: Subdirectory z1090 is created in your home directory and several subdirectories are created under that.

6 7

8 9

The names could contain i586 instead of i386. Some rpm building packages use i386 and some use i586. There is no difference in the resulting use of the rpm. With some Linux distributions we can install the prerequsite rpms directly from a CD, by clicking on the rpm name in the file window. With other Linux distributions, we needed to copy the rpms (and the zPDT installer program) to a hard disk location (such as /tmp) before installing them. Installation from a hard disk location should always work; you can try installing from a CD as a shortcut. This step is not required for future releases. It is needed only if you have releases earlier than 39.09.01 installed. The "./" characters before the file name tell Linux to execute this file from the current directory.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

The 1090 executable files are loaded into /usr/z1090/bin. A set of man files is loaded into /usr/z1090/man. Releases prior to z1090-1- used a z1090pick command at this point in the installation process. This command and function are no longer used. You must update a few Linux files before you can use the 1090. The following command adds lines to /etc/sysctl.conf.10 We indicate the use of gedit but you may use any suitable editor (such as vi) to create these files or add the indicated lines.11 (We suggest that you do not attempt to use vi unless you have a basic familiarity with it!) Our RHEL 5.3 already had acceptable values for shmmax, msgmnb, msgmax, and core_uses_pid, but other distributions may need to have all these values set. # gedit /etc/sysctl.conf (the following lines should begin in column 1) kernel.shmmax=2415919104 (2.4 GB for 32-bit kernels) kernel.shmmax=17179869184 (17 GB or more for 64-bit kernels) (Use only one of these shmmax lines) kernel.core_pattern=core-%e-%p-%t kernel.core_uses_pid=1 kernel.msgmni=512 kernel.msgmax=65536 kernel.msgmnb=65536 # /sbin/sysctl -p /etc/sysctl.conf The shmmax values shown above (and you must select the appropriate one, depending on whether you have a 32-bit or 64-bit Linux system) establish the maximum shared memory than a user can request. System z memory, plus several other 1090 work areas, are in Linux shared memory. Another parameter, shmall, sets the total shared memory size of all users. The value of shmall is specified in page sizes, which is usually 4096. The default value of shmall is usually acceptable. However if you have multiple 1090 instances, all with large System z memory, you might exceed the default shmall value. If this happens you need to include a parameter such as: kernel.shmall=3000000 This would result in the total amount of shared memory, for all users, to be 3000000*4096. This value should be greater than the number of 1090 instances times the System z memory size for each instance plus about 10%. The following lines should be added to /etc/profile.local. If this file does not exist, you should create it. (Some Linux distributions do not use this file, but its presence should not hurt anything.) # gedit /etc/profile.local (the following lines should begin in column 1) ulimit -c unlimited ulimit -d unlimited ulimit -m unlimited (if you have more than 128 emulated I/O devices) ulimit -v unlimited (if you have more than 128 emulated I/O devices) # gedit /etc/profile


Some versions of the IBM Open Client reset these values when maintenance is applied. If this happens, you should again enter the values shown here and run /sbin/sysctl. Future Open Client versions should not do this. 11 The 32-bit shmmax value shown should be used for 32-bit Linux systems. The value shown for 64-bit systems (the value is approximately 17GB) is suitable for most users. If you have more than, say, 16 GB of real memory and you intend to define a System z configuration with more than about 16 GB then the shmmax value should be increased. As a general rule, the shmmax value should be at least 500 MB larger than the total System z memory you define (for all instances) but your defined System z memory should be about 500 MB less than the real memory in your machine.

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

(add the following line as the last line if not already present somewhere in the profile. It is already present in openSUSE 10.3) test -s /etc/profile.local && . /etc/profile.local

The ulimit commands in /etc/profile.local are not effective unless this file is processed from the /etc/profile reference. The ulimit commands can also be placed in the .bashrc file (or in both places). The kernel.msgmni number, specified as 512 here, may need to be larger if you have many emulated I/O devices. The msgmax and msgmnb settings are not needed for some Linux releases because these are the default settings. However, including these parameters in sysctl.conf does no harm; the settings are needed for proper OSA operation. Change from root to ibmsys1: # exit (leave root) $ cd /home/ibmsys1 (my login directory) $ gedit .bashrc (use your favorite editor) Add the following lines beginning in column 1): export PATH=/usr/z1090/bin:$PATH export LD_LIBRARY_PATH=/usr/z1090/bin:$LD_LIBRARY_PATH export MANPATH=/usr/z1090/man:$MANPATH ulimit -c unlimited ulimit -d unlimited ulimit -m unlimited (if more than 128 emulated I/O devices) ulimit -v unlimited (if more than 128 emulated I/O devices) Double-check the entries in all of these Linux files. Errors here may be difficult to detect later. The ulimit -m and -v statements are not required for most users and should probably be excluded unless you have more than 128 emulated I/O devices.) Check your 1090 distribution materials to see if there are sample devmaps files that may be helpful. Copy these to /home/ibmsys1, for example: $ cd /tmp/ROM $ cp aprof1 /home/ibmsys1/aprof1 $ chmod 664 /home/ibmsys1/aprof1 (or wherever your 1090 source is)) (sample devmap)

Reboot Linux to pick up all the changes you have made. You should then use the z1090instcheck command to partly verify your environment for running the 1090. Your new PATH is needed to find the command: (login as ibmsys1) $ z1090instcheck If this command is not found, you do not have the PATH variables set or you did not install the 1090 code correctly.

1.4 1090 hardware key activation

A USB hardware key ("token") is valid for a year from the time it was last activated.12 Activation (and lease renewal) may be handled by your IBM business partner or, if authorized, by using IBM Resource Link. IBM internal users and IBM PartnerWorld for Developer (PWD) members and use the Resource Link method.


The information in this section applies to hardware keys with serial numbers of 15,000 or above.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

1.4.1 IBM Resource Link

Activation instructions are provided with the 1090 USB hardware key (token) for initial activation and renewals. For convenience, we include a summary here. The USB hardware key, as shipped, must be activated before it can be used. Activations last one year and are known as leases. Leases can be extended any time for another year by using the same Resource LinkTM functions. The important steps in this process are summarized as follows: 1. Preliminary work. ­ Obtain an IBM employee Resource Link ID ("profile")13 and password, or a Resource Link userid that has been approved for 1090 use by a IBM PWD member. ­ Copy and save the information printed on the tag attached to your token. 2. Install the 1090 software on your Linux machine. The installation can be done without using the token. (You need a working token to run the 1090 software.) 3. Connect your token to a USB port (on your 1090 machine) and run the 1090 SecureUpdateUtility program to create a request file. 4. Using any PC connected to the Internet, logon to Resource Link and send the request file. 5. After a while you will receive e-mail with an attached update file.14 6. Run the 1090 SecureUpdateUtility program to apply the update file to your token. 7. Your token is now ready to use. You will need to repeat the process after a year (or any time before a year expires.) If your 1090 Linux system is connected to the Internet you can perform the whole process from there. In practice, we find many 1090 systems are not connected to the Internet. In this case, you can copy the request file and the update file between your 1090 machine and your Internet machine (possibly running Microsoft Windows) by using a memory stick, a diskette, FTP, or any other convenient method. These two files are small. An update file will function only with the specific token that you identified in the request file.

Preliminary work

Copy the information that is printed on the token tag (illustrated in Figure 1-1) attached to the USB hardware key. Save this information in a safe place.


Also known as an IBM Registration ID. If there is a problem send a note to [email protected] to request help with Resource Link registration. 14 The Resource Link function also provides a web page where the upw file can be downloaded. Providing the web page takes a little time and it may not be ready as quickly as you receive the email response. The upw is the same in both the email and web options, and you may use the most convenient way to receive the upw file. The web option is convenient if your 1090 system is connected to the web and if it is not your email system (thus avoiding any email requirement).

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am

11S number: use last 6 digits (055123 in this example)

(11S)PN/SN: 15r7312 YH1102055123 || |||| ||||| || || |||| || ||||


Type 1090-L01 S/N 02-1180C

MTSN number: (02-1180C in this example)

Figure 1-1 USB hardware key tag

Canada iCES/NMB-003 IBM-1090-XXX(A) Class/Classe A FCC class A - see manual

The data in the 11S and MTSN fields on the tag is required to: Activate the USB hardware key for the first time. Extend the lease for one year. Obtain a model upgrade. Activate and use a replacement USB hardware key. An IBM-employee or PWD-approved Resource Link profile is required. If you do not have one, go to and follow the Register for an IBM ID link (in the upper right part of the panel). After establishing a userid and password, follow the Sign in link to create your Resource Link profile. Wait two hours after creating the profile before signing back in. The profile information must be replicated among several servers and this can take some time. PWD members must validate this userid with the IBM PWD office. If you do not have an IBM employee Resource Link userid, or if your PWD Resource Link userid has not been validated by the IBM PWD office, you will not see the appropriate menu items in Resource Link.

Activation (or renewal, date extension, or lease extension)

After this preliminary work, the key can be activated, renewed, or have the lease date extended (these are all provided in the same way): 1. Connect the USB hardware key to your 1090 system, using any USB port. (You must have already installed the 1090 software.) 2. Working as root, create a request file using the Secure Update Utility: (login with normal z1090 userid, such as ibmsys1) $ su (switch to root) # SecureUpdateUtility -r Enter file name: myrequest (file name is arbitrary) 3. Move this request file to the computer used to access Resource Link and logon to Resource Link. (The file name will have .req added as the name extension.) 4. Navigate to Tools 1090 Support Date Extension and enter the data from your hardware key tag. Use the last six digits of the 11S field. The serial number (the MTSN field) can be entered with or without the dash; it is not case sensitive. Enter the file name of your request file. Finally, click Submit. 5. Resource Link will create an update file and send it to you by e-mail. (This typically takes about 10 minutes.) Receive this file and move it to your 1090 machine. The file name will be the same name that you sent, but with .upw as the name extension. 6. Apply to file to the USB hardware key:


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

# SecureUpdateUtility -u myrequest.upw 7. After the Secure Update is successfully applied, unplug the USB hardware key. Wait at least 10 seconds and then reconnect the hardware key. It is now ready for routine 1090 operation.

1.5 Installing a new 1090 release

New 1090 releases are typically available through your business partner or (for IBMers and PWD members) through Resource Link. They may be in the form of a CD .iso file; you must burn the corresponding CD to use it. The installation procedure is the same regardless of the source. Installation is exactly the same as described earlier, except that the sntl-sud and shk-server programs do not need to be installed again (unless they are new versions). A summary of the steps is as follows: 1. Obtain the z1090 rpm and installer program for your platform. (That is, select among openSUSE, RedHat version, 32-bit, and 64-bit versions). 2. Working as root, execute the installer program.

Chapter 1. Linux and 1090 installation


Draft Document for Review September 4, 2009 10:36 am


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Chapter 2.

AD CD z/OS installation

The System z Personal Development Tool provides System z CP functionality and associated utility programs. It does not include any System z software. System z software, including operating systems, utilities, middleware, applications, and so forth, must be obtained separately. For software licensing purposes, a 1090 system is a System z and all software licensing requirements that apply to a larger System z installation also apply to a 1090 installation. This statement applies to all System z software from IBM and, we assume, applies to all System z software available from other vendors.1 The discussions in this chapter (and elsewhere in this series) assume that proper licenses have been obtained for the System z software. Licensing arrangements (and associated costs) can be complex topics and are not further addressed in this document. Important: The discussions in the remainder of this document and in the third volume in this series assume the reader has a general familiarity with z/OS systems programming and understands how to access various control datasets. We highlight specific details that may be relevant to 1090 usage and the current AD-CD releases. This is not intended as an introduction to z/OS administration. Furthermore, we assume basic familiarity with the AD-CD z/OS package. Update information about the AD-CD packages may be found on

2.1 General principles

All current IBM System z operating systems (assuming proper licenses exist) are supported for 1090 usage. This includes current versions of z/OS, z/VM, and z/VSE. Linux distributions intended for System z usage may be used, but all functions and configurations have not been fully tested. Older versions of operating systems and other software may work correctly (provided they are at least at the XA level), but there is no formal testing or support for older software.


In this discussion we include software for zSeries®, S/390s, and so forth, in the general category of System z software.

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

Software installation methods may be different for 1090 systems than for traditional System z installations. This difference is due to the differences in I/O devices available on 1090 systems and on larger System z machines.

2.2 System z operating systems

There are specific limitations for installing IBM operating systems. These limitations are related to the use of the software media and packaging techniques involved and are not limitations on the use of the operating systems, once they are installed. The most common limitation is for software that is distributed on tape. To install this software, your 1090 must have a tape drive and these are not commonly available for PC machines. Another limitation is related to any System z software that is packaged in such a way that installation requires a System z HMC. Other considerations may be important for specific middleware or applications. For example, the largest System z memory that can be emulated with a 32-bit version of the 1090 is approximately 2 GB. That is, the System z operating system thinks it has up to 2 GB of real memory. Software requiring more than this may not be practical. Some software requires hardware adapters that are not available with the 1090. The most obvious of these involves cryptographic adapters, which are not available with the 1090. (The cryptographic instructions are available, but not the cryptographic adapters.)

2.2.1 Media

In most cases (when a tape drive is not available) installation media is limited to CD, DVD, and LAN connections. (We can consider FTP as "media" in this context.) CD or DVD files must be in formats that can be processed for the 1090. There are two meaningful formats: A Linux image of an emulated 3390 drive2 that can be restored in the 3390 format used by the 1090; the image might be compressed (using gzip, for example) and would need to be uncompressed before use by the 1090. Likewise, the image might be in tar files and would need to be untarred (and possibly uncompressed) before being used by the 1090. The 3390 drive image format must be produced by another 1090 system, because no other product uses the same 3390 image format that is used by the 1090. Whatever preliminary unpacking/uncompression is needed must be done by Linux utilities before the 3390 image can be used by a System z operating system. A tape image in awstape format; such images appear as "real" tape volumes to System z operating systems, and can be processed as such by using emulated tape drives. The tape might contain product installation material (in SMP/E format, for example), an ADRDSSU dump of a disk volume, or any other tape data usable by System z programs. The same files, in the formats described, could be exchanged by FTP (to the base Linux of the 1090 system) instead of using CD or DVDs. This would not affect the processing requirements. Another media option is to FTP a product (or other data) directly to z/OS. Some System z software is distributed in this format. Of course, the 1090 must have a running z/OS and LAN connection in order to use this method. (Most of our discussion is for z/OS but z/VM, z/VSE, or Linux for System z might be used in the same way. The point is that a working System z operating system must be installed before additional software can be sent directly to it via FTP.)


3380 images could also be used, but we ignore these here.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

It is important to differentiate the handling of these methods: CDs and DVDs must be processed by Linux programs (unless they contain awstape files). awstape files must be processed by z/OS (or another System z operating system), although the transport of awstape files can be managed by Linux through CD/DVDs or FTP. Direct FTPs to z/OS may be in other formats, for example in formats suitable for processing by SMP/E or the TSO XMIT command. In any event, these are System z formats and not Linux formats.

2.3 Packages for the 1090

At the time of writing, organizations within IBM produce one z/OS package that can be directly installed on 1090 systems. This is the Application Development System (the "AD System").3 It is distributed on DVDs. This package is not part of the IBM System z Personal Development Tool. It is a convenience package for users of this tool. It is a z/OS system, with additional System z software products, and requires appropriate System z software licenses for use. The AD system is intended for use by members of the IBM PartnerWorld® for Developers, among other users. An informal package for z/VM may be available. One of the standard z/VSE formats (based on awstape files on a DVD) may be used. Brief descriptions of z/VM and z/VSE installation processes are in Volume 3 of this series.

2.4 Installing an AD system

The first step for installing an AD system is to verify that the 1090 version of the AD system is available. Other versions cannot be directly installed. The following examples use volsers corresponding to the z/OS 1.10 (December 2008) release of the AD system. These volsers tend to change in a standard pattern for new releases.

2.4.1 Specific installation instructions

There are typically four DVDs for an z/OS AD release. The first DVD contains the 3390 volumes needed to IPL and to use common subsystems. It may also contain a README file, sample devmap, and so forth. The second DVD may contain DLIB volumes. A third and fourth DVD may contain optional volumes for DB2, WAS, and other material. Documentation with each AD release contains specific information about the DVD layout for that release. The distributed emulated volumes are all in gzipped format. The z/OS 1.10 AD system uses DVD titles such as DVD1 ADCD 1.10; again, we stress that you must determine the volume title on your DVDs. Some CD titles containing multiple blanks are difficult to use with a cd command. We used the Linux automatic command completion function with these. For example: (mount the first AD-CD DVD) $ cd /media $ cd DVD<tab>


(DVDs are mounted as /media/xxxx) (the tab tells Linux to complete the command)

This is also known as the AD-CD system, where CD means Controlled Distribution.

Chapter 2. AD CD z/OS installation


Draft Document for Review September 4, 2009 10:36 am

The completed command is 'cd DVD1 ADCD 1.10' or something similar AD system installation might be as follows, assuming our target directory for emulated 3390 volumes is /z: (work as userid ibmsys1) $ cd /media/DVD<tab> the DVD $ gunzip -c zares1.gz > /z/ZARES1 unzip volumes $ gunzip -c zares2.gz > /z/ZARES2 $ gunzip -c zasys1.gz > /z/ZASYS1 And so forth for all the volumes to be installed. We elected to use the volser of the 3390 volume as the Linux file name that holds the volume. We use upper case letters simply to make these emulated volume file names more distinctive. There is no requirement to use the volser as the Linux file name, and there is no requirement to use upper case names. The files containing emulated volumes (and the directory containing these files) must have read and write permissions for the userid running the 1090 function. Assuming use of the ibmsys1 userid, we suggest that all such files and their directories (/z in our examples) should be owned by ibmsys1.

2.4.2 IODF device numbers

We must know the device numbers ("addresses") used by the AD system. (These may be changed after the z/OS system is running. Changing involves creating a new IODF data set, new IPLPARM member(s), and re-IPLing z/OS.) Most users of the AD system accept the device numbers generated in the IODF supplied with the AD system. These are as follows: ADDRESS 00C 00E-00F 120-15F 300-318 400-40F 550-55F 560-56F 580-58F 590-59F 700 701-73F 900-907 908 909-91F A80-AEF E20-E23 E40-E43 DEVICE 2540R 1403-N1 3380 3390 OSA 3400 3480 3490 3590 3270 3277 3277 3270 3277 3390 CTC CTC Purpose Card reader. Useful as an emulated device. Line printers. Useful as an emulated device. Disks. (Control units defined for 120-127) 3390 disks OSA Round tape drives Without COMPACT feature Tape drives Tape drives Terminal. AD systems use as NIP & z/OS master console Terminal. Normally for VTAM (TSO, CICS, etc) Terminal. Normally for VTAM (TSO, CICS, etc) Terminal. Normally for VTAM (TSO, CICS, etc) Disks Typically for 3172s that appear as CTC devices Typically for 3172s that appear as CTC devices

These addresses are all three hex digits. This is due to historical reasons. Both the AD system and the 1090 system can work with four-digit addresses. In principle the 3390 IPL volume, for example, could be mounted at any address in the 300-318 or A80-AEF range. In practice, the following addresses are used in all the AD examples: VOLSER ZARES1 ADDRESS A80 Purpose IPL volume and key z/OS libraries


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

ZARES2 A81 More z/OS libraries ZASYS1 A82 Paging, spool space, LOGGER data sets, VSAM, etc ZAUSS1 A83 Data sets of UNIX System Services ZAPRD1 A84 Additional program products ZAPRD2 A85 Additional program products ZAPRD3 A86 Additional program products ZADIS1 A87 Distribution libraries (optional) ZADIS2 A88 Distribution libraries (optional) ZADIS3 A89 Distribution libraries (optional) ZADIS4 A8A Distribution libraries (optional) ZADIS5 A8B Distribution libraries (optional) ZADIS6 A8C Distribution libraries (optional) ZADB91 A8D DB2 operational libraries ZADB92 A8E DB2 distribution libraries (optional) ZACIC1 A8F CICS (operational and distribution libraries) ZAIMS1 A90 IMS (Operational and distribution libraries) (three WAS volumes are also available) SARES1 AA0 Single-volume z/OS 700 701-70F 400-40F E20-E21 3270 for z/OS console 3270 terminals for TSO, CICS, etc OSA LAN connections in QDIO mode OSA LAN connection in non-QDIO mode

These addresses and volsers may change in future AD systems but the general pattern is likely to remain the same. Additional 3390 volumes (for WebSphere® Application Server or local data, for example) are typically started at address A91. These addresses are in the ranges defined for 3390 volumes in the default IODF. Other than that, there is nothing special about these addresses. For example, if you elect to not install the DLIB volumes, you might assign the ZADB91 volume to address A86; or your could leave it at A8C and have a gap in your addresses. Recent z/OS AD releases have included both DB2® V8 and DB2 V9 with separate 3390 volumes for each version. Our examples assume DB2 V9 is installed.

2.4.3 1090 control files

Before the AD system can be used, the appropriate devmap must be created. A basic example would be as follows: $ cd /home/ibmsys1 $ gedit aprof19 [system] memory 1500m processors 1 3270port 3270 [manager] name aws3274 0002 device 0700 3279 3274 device 0701 3279 3274 device 0702 3279 3274 device 0703 3279 3274 device 0704 3279 3274 [manager]

Chapter 2. AD CD z/OS installation

(this is an arbitrary file name) # define 1500 MB System z # use 2 or 3, if appropriate # port number for TN3270 connections

# define a few 3270 terminals mstcon tso tso tso tso


Draft Document for Review September 4, 2009 10:36 am

name awsckd 0001 device 0a80 3390 3990 /z/ZARES1 device 0a81 3390 3990 /z/ZARES2 device 0a82 3390 3990 /z/ZASYS1 device 0a83 3390 3990 /z/ZAUSS1 device 0a84 3390 3990 /z/ZAPRD1 # if device 0a85 3390 3990 /z/ZAPRD2 # if device 0a86 3390 3990 /z/ZAPRD2 # if device 0a87 3390 3990 /z/ZADIS1 # if device 0a88 3390 3990 /z/ZADIS2 # if device 0a89 3390 3990 /z/ZADIS3 # if device 0a8a 3390 3990 /z/ZADIS4 # if device 0a8b 3390 3990 /z/ZADIS5 # if device 0a8c 3390 3990 /z/ZADIS6 # if device 0a8d 3390 3990 /z/ZADB91 # if device 0a8e 3390 3990 /z/ZADB92 # if device 0a8f 3390 3990 /z/ZACIC1 # if device 0a90 3390 3990 /z/ZAIMS1 # if device 0aa0 3390 3990 /z/SARES1 # if #(continue with WAS volumes if you installed $ awsckmap aprof1

you restored you restored you restored you restored you restored you restored you restored you restored you restored you restored you restored you restored you restored you restored them)

this this this this this this this this this this this this this this

volume volume volume volume volume volume volume volume volume volume volume volume volume volume

Only the first four volumes of the AD z/OS 1.10 system are needed to IPL. Gaps in the assigned address numbers do not create a problem. The devmap can have any name and be placed in any directory. It is best if it is in the directory you will use when starting the 1090 so that you do not need to enter a full path name when using it. The processors statement determines how many System z CPs are started for this 1090 instance. We suggest you do not define OSA devices for your initial z/OS startup. The OSA definitions can be a little more complex and we suggest you verify that your basic z/OS system is operational first.

2.4.4 IPL and operation

Start the 1090 with an awsstart command. Among other functions this starts the 1090 device manager that emulates local, channel-attached 3270 terminals. Using the awsstart command creates a z1090 subdirectory in the current home directory (if it does not already exist) and a number of zPDT-related directories below it. $ cd /home/ibmsys1 $ awsstart aprof9 use our devmap name (wait for messages. Press Enter to regain the $ prompt.) AWSSTA014I Map file name specified: aprof9 0 Snapdump incident(s), RAS trace and RAS log files occupy 657046 bytes in /home/ibmsys1/z1090/logs. Associated files, logs, and core files occupy 10364 bytes in /home/ibmsys1/z1090/logs Using the same Linux window (or a different window, if you prefer) start two local 3270 sessions: $ x3270 -port 3270 [email protected] & $ x3270 -port 3270 [email protected] & $ x3270 localhost:3270 & (another way to specify a port number)


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

x3270 is the name of the program We assigned Linux TCP/IP port 3270 for this function. This is specified in the devmap. The port number is arbitrary, but should not be used for any other purpose in your system. Port 3270 is usually a good choice and is easy to remember. We want to connect to our own Linux system; this is indicated by the localhost operand. The mstcon and TSO operands are the LUnames of the sessions and must match names in the 3270 device statements in the devmap. These names are case sensitive. If no LUname is specified, the next unused device for the aws3270 device manager is taken. The ampersand (&) causes the x3270 program to execute in the background, leaving the Linux window free for additional commands. We can recall and execute the x3270 command repeatedly to create multiple 3270 sessions. The 3270 window will display a single line if there has been no data sent to it by the System z software. This line indicates the terminal identity by address and LUname. A number of options are available for working with these LUnames and these are discussed in volume 1 of this series. The File and Options menus at the top of the x3270 window can be used for a variety of functions. Changing the font size (using the Options menu) has the effect of changing the 3270 window size. The 3270 session for the z/OS console (address 700 for the AD system) should be ready before IPLing z/OS. Next issue the appropriate IPL command in the Linux window: $ ipl a80 parm 0a82cs After a few seconds, the initial z/OS messages should appear on the 3270 session at address 700. During the first IPL of the AD-CD system (or an IPL after a long period of non-usage) you may see messages similar to the following: IXC420D REPLY I TO INITIALIZE SYSPLEX ADCDPL, OR R TO REINITIALIZE XCF If this message occurs, go to the 3270 session displaying the message and enter: r 00,i After VTAM® is started, the VTAM logo should appear on the other 3270 session.4 There is usually a writeup for each AD release that provides details about different IPL parameters and TSO logon procedures. A very brief summary for the z/OS 1.10 AD system is: IPLparm 0A82CS 0A8200 0A829C 0A829W LogonProcedure ISPFPROC ISPFPROC DBSPROC9 DBSPROC9 Purpose Basic IPL without DB2, etc. Cold start JES, CLPA Subsequent basic IPLs. Warm start. Initial IPL for DB2 V9, etc Subsequent IPLs for DB2 V9, etc

Userid IBMUSER is always present on z/OS and is typically used for initial TSO logons. The password for IBMUSER should be published with any AD-CD documentation. It is typically SYS1 or IBMUSER. If there are security concerns about your system, this initial password should be changed as soon as possible.

2.4.5 Shutdown

z/OS should be shut down cleanly, if possible. Enter the command s shutdown at the z/OS console and reply to any messages produced. The message ALL FUNCTIONS COMPLETE indicates that JES2 can now be stopped with the command $PJES2. After JES2 ends, then


If the 3270 session displays an "Unsupported Function" message, simply use the 3270 Clear key to obtain the initial VTAM display. Some TN3270e emulators encounter this initial message and others do not.

Chapter 2. AD CD z/OS installation


Draft Document for Review September 4, 2009 10:36 am

System z operation can be stopped. The 1090 is stopped with this command in the Linux window: $ awsstop This produces a number of messages. It may be necessary to press Enter to obtain the Linux prompt. Any 3270 windows may be closed at this point.

2.4.6 Startup messages

Messages such as: AWSSTA014I Map file name specified: aprof9 0 Snapdump incident(s), RAS trace and RAS log files occupy 657046 bytes in /home/ibmsys1/z1090/logs Associated files, logs, and core files occupy 10364 bytes in /home/ibmsys1/z1090/logs are produced by the awsstart command. You should glance at these messages. Snapdump incidents are indications of an internal 1090 error. If you want to work with IBM 1090 support you will need this data. The number of bytes used for various logs and dumps is usually not significant unless it becomes too large. To a great extent, the 1090 manages these files automatically. However, if the numbers displayed become too large (many megabytes) and if you are not actively working on a problem with IBM 1090 support, you may want to cleanup these files. This can be done by adding the --clean option the next time you issue an awsstart command: $ awsstart aprof9 --clean You can get the --clean behavior every time by setting a Linux shell environment variable Z1090_CLEAN=YES; however, we do not recommend doing this because it could easily result in the removal of important debugging information in the event of a 1090 failure.

2.4.7 Local volumes

The process for adding your own 3390 volumes is as follows: Allocate the volume using the 1090 utility: $ alcckd /z/WORK01 -d3390-1 Update the devmap to include the new volume. (Assume address AA0 for this example.) [manager] name awsckd 0001 ... device AA0 3390 3990 /z/WORK01 IPL z/OS with the new volume present. z/OS will detect an uninitialized volume and vary it offline. Create and run an ICKDSF job to initialize the volume: //BILLX JOB 1,OGDEN,MSGCLASS=X // EXEC PGM=ICKDSF,REGION=1M //SYSPRINT DD SYSOUT=* //SYSIN DD * INIT UNIT(AA0) NOVERIFY VOLID(WORK01) VTOC(0,1,14) /* Vary the new volume online and begin using it: VARY AA0,ONLINE (on the z/OS console)


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

2.5 z/OS parameters

We5 recommend that you ensure the MIH6 values for both GRAF and COMM devices are set to three minutes in the IECIOSxx member in your PARMLIB. Three minutes is the default value, but we have seen some installations with a lower value specified. For example, you could have a PARMLIB member named IECIOS00, as follows: MIH GRAF=3:00 MIH COMM=3:00 Your IEASYSxx PARMLIB member should contain the following line: IOS=00,

2.6 Multiple operating systems

We can install multiple System z operating systems, limited only by the disk space we have available. Every emulated 3390-3 volume uses approximately 2.8 GB disk space. Many of our laptop disks were nominally 100 GB. After allowances for Linux and other purposes we had about 82 GB of usable space left. This translates to 29 3390-3 volumes. (Of course, there is no requirement to use 3390-3 volumes. A similar computation may be done for other or mixed 3390 sizes.) We frequently placed emulated volumes on an inexpensive USB drive and we did not did not see a significant performance difference between this drive and the laptop internal hard disk. More recent laptop machines have even larger hard disks. It is important to distinguish between installing additional emulated 3390 volumes (perhaps with a variety of operating systems), and using the volumes. We can, of course, only IPL a single system at any one time in a 1090 instance.7 The volumes that may be "seen" by that system depend on several factors: Does the current devmap contain all the desired volumes? We can have multiple devmaps, each with a different selection of emulated volumes and assigned addresses, but we can have only one devmap specified when we start a 1090 instance. We cannot change the devmap while the 1090 is running.8 Do the device addresses in the devmap match suitable addresses in the IODF of the z/OS system? For example, if one of the emulated 3390 volumes is assigned address 120 (in the devmap), then the default z/OS AD IODF will consider it to be a 3380 volume instead of a 3390 volume. (z/VM does not have predefined addresses for various device types, making this aspect of z/VM easier to use.) Duplicate disk volsers may not be present. You may have duplicate volsers for emulated volumes on your PC disk, but the duplicates should not be present in a given devmap. It may not be possible to use the common addresses typically associated with an operating system. For example, all the AD documentation uses A80 as the IPL address for an AD system. We can have two (or more) AD systems installed at the same time, but only one volume

5 6 7 8

The 1090 developers have recommended this parameter set. However, we very seldom see the need for it and suggest that you might skip it unless you encounter 3270 connection timeouts. This is the Missing Interrupt Handler function. This statement ignores the possibility of running multiple z/OS guests under z/VM. This is not completely true. We can change the volume mounted on an emulated disk drive or tape drive by using the awsmount command.

Chapter 2. AD CD z/OS installation


Draft Document for Review September 4, 2009 10:36 am

can have address A80 during any single execution of the 1090. This does not prevent us from IPLing any of the (multiple) AD systems installed, but we need to specify the correct address. An example might make this clearer: Address A80 A81 A82 ... A90 A91 A92 ... VOLSER ZARES1 ZARES1 ZASYS1 S9RES1 S9RES2 S9SYS1 Purpose IPL volume for z/OS 1.10 AD system Libraries for z/OS 1.10 AD system Paging, spooling, VSAM for 1.10 AD system IPL volume for z/OS 1.9S system Libraries for z/OS 1.9S system Paging, spooling, VSAM for 1.9S system

Assuming our devmap is configured for these addresses, we can ipl A80 parm 0A82CS to run the 1.10 system or we can ipl A90 parm 0A92CS to run the 1.9S system. In either case, the running z/OS system can access all the volumes of both z/OS systems. This is very convenient for migration purposes. The volumes are readdressed by simply changing the addresses in the devmap. We can run multiple System z operating systems at the same time by starting multiple zPDT instances, but this requires more resources (especially PC memory). Details about using multiple instances are in Volume 3 of this documentation series.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Chapter 3.


Connectivity (usually emulated 3270 terminals or TCP/IP functions) is an important area for any system and the various options available with the 1090 should be understood. The concepts present in this chapter are a little complex; we strongly recommend that you read this material carefully (several times) before deciding how to configure your LAN access. If your only requirement is for local 3270 sessions, using x3270 on your base Linux system, then you can skip this chapter! Attention: We strongly recommand that your initial LAN configuration be as simple as possible. If at all possible, work within a local network (based on a small hub or router) using nonroutable IP addresses such as 10.x.x.x or 192.168.x x as shown in our examples. Use a single Ethernet adapter and/or the tunnel operation described below. Make the simple configuration work and become familiar with it before attempting anything more complex. This recommendation is not due to any 1090 restrictions but reflects the issues encountered (and often self generated) by users who have not personally configured System z LAN operation before.

3.0.1 Overview of LAN usage

When planning LAN usage with z/OS, you must consider that z/OS does not function as a DHCP client. z/OS must have fixed IP addresses. The most basic 3270 connectivity is through the aws3274 device manager, which has already been described. This operates with the underlying Linux system and does not involve z/OS TCP/IP or OSA Express emulation. If the only 3270 sessions are on the local Linux system, then no Ethernet is involved. Remote 3270 sessions can connect, via the Linux Ethernet adapter, to the aws3274 device manager. These also appear as channel-attached, non-SNA terminals to the System z.1


These remote 3270 sessions use the IP address of Linux and the TCP/IP port number you specified in the system section of your devmap.

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

The examples below assume that OSA is used as a QDIO device as opposed to an LCS (non-QDIO) device. We recommend using QDIO operation. Key setup differences include the following: For QDIO operation: ­ Three OSA devices are needed for a TCP/IP connection. ­ z/OS devices involved must be defined as OSA devices. ­ A TRLE definition is needed in VTAMLST, pointed to by ATCCON00 in VTAMLST. ­ The z/OS TCPIP PROFILE uses a IPAQENET device type. For LCS operation ­ Two OSA devices are needed for a TCP/IP connection (and these should use unitadd=0 and 1, unless you change the default OAT definitions for the OSA). ­ z/OS devices may be defined as OSA or CTC. ­ No TRLE or other VTAMLST entry is needed. ­ The z/OS TCPIP PROFILE uses an ETHERNET device type There may be three 3270 interfaces with z/OS: The aws3274 device manager accepts TN3270e connections2 (from the local Linux host or over the Linux TCP/IP network.) The TCP/IP port number for this connection is specified in the 3270port parameter in the devmap. z/OS (or other System z operating systems) see these 3270 sessions as local, channel-attached, non-SNA, DFT terminals. Such terminals are suitable for z/OS operator consoles and VTAM use. It is not necessary to have z/OS TCP/IP operational in order to use these terminals. z/OS TCP/IP (or another System z operating system's TCP/IP) provides TN3270e connections. Terminals connected this way are not usable as z/OS operator consoles. TN3270e connections through z/OS TCP/IP are routed to VTAM and may be used as TSO terminals, CICS® terminals, and so forth. z/OS TCP/IP must be configured to use an OSA-Express2 adapter (in either non-QDIO or QDIO mode). The OSA-Express2 functions are emulated by the awsosa device manager.3 z/OS VTAM potentially could work with SNA 3270 Ethernet connections, working through the awsosa device manager. However, SNA operation of the 1090 is not supported at this time. The x3270 program (or PCOMM or another TN3270e client) may be used for connection to the aws3274 device manager or the awsosa device manager. Connections to aws3274 use the IP address of Linux and the port number specified in the devmap. Connections to awsosa use the IP address of z/OS (or other operating system TCP/IP) and the appropriate port number for it (usually the default port 23). The same Ethernet adapter can be used for Linux functions, such as telnet, aws3274, ftp, and so forth and also for OSA connections. Important concepts include the following: An emulated OSA-Express interface requires a hardware Ethernet adapter port on the underlying Linux system (or a tunnel interface, as described later). A laptop normally has one integrated Ethernet port. (It may also have an integrated wireless functions.) Additional Ethernet ports may be added by using PC (PCMCIA) Cards. An emulated OSA-Express interface operating in QDIO mode is used only for z/OS TCP/IP (or z/VM TCP/IP, and so forth). An emulated OSA-Express interface operating in non-QDIO mode can be used by z/OS TCP/IP and/or SNA (although SNA is not supported at this time). Non-QDIO mode is sometimes known as LCS mode.

2 3

A TN3270 connection (as opposed to a TN3270e connection) will be accepted, but extended data steam capabilities are not present and some z/OS functions may not work correctly. We describe this as an OSA-Express2 device manager, but this description is only approximate. This device manager has attributes of both the original OSA, OSA-Express, and OSA-Express2 channels available on larger System z machines.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

If you want to communicate between Linux TCP/IP and OSA TCP/IP on the same PC, a tunnel environment must be established.

3.1 Simple OSA LAN usage

The discussions in this document consider only very basic z/OS TCP/IP environments. If you need something more complex we suggest you first install the very basic configurations we describe and then reference: Communications Server for z/OS V1R9 TCP/IP Implementation Volume1: Base Functions, Connectivity, and Routing (IBM order number SG24-7532) Consider first the Linux TCP/IP functions in Figure 3-1. We suggest you examine this figure carefully because it illustrates a number of important principles. The Linux TCP/IP stack has an IP address, assigned through normal Linux administrative functions. Various Linux applications, such as ftp or a telnet server, have their own port numbers. The aws3274 device manager (a Linux application provided with the 1090) has a port number that is assigned by the 1090 devmap.4 This device manager, which provides TN3270e server functionality, converts the TN3270e client sessions so they appear to be local, channel connected, non-SNA 3270 terminals to the 1090 System z.5 The Linux TCP/IP stack also provides a loopback connection. This connection ( or localhost) is used by x3270 sessions running on the Linux desktop. Figure 3-1 illustrates basic LAN connectivity for a 1090 system.The definitions for the configuration in Figure 3-1 would include something similar to the following: [manager] name aws3270 AB00 device 700 3279 3274 device 701 3279 3274 etc [manager] name awsosa 8888 --path=F0 --pathtype=OSD device 400 osa osa --unitadd=0 device 401 osa osa --unitadd=1 device 402 osa osa --unitadd=2

# uses the LAN adapter # QDIO needs 3 devices # in this case6

The --path operand specifies a CHPID number. The correct number is determined by using the find_io command. For these examples we assume the CHPID for Ethernet is F0 and the CHPID for a tunnel interface (discussed next) is A0.7 The --pathtype is OSD (for QDIO) or OSE (for LCS or non-QDIO). The --unitadd operands specify the internal osa interface number; these usually can be defaulted. z/OS TCP/IP requires three OSA addresses for QDIO operation.

4 5 6 7

The telnet server and the ftp function in the illustration also have their associated port numbers, of course. We use port 3270 for the aws3270 device manager in our examples. These are the types of terminals that had coax cable connections to a 3274 control unit in a traditional mainframe configuration. In a basic situation, TCP/IP operation in QDIO mode requires three OSA interfaces. (The requirements may change for cases where there are multiple TCP/IP stacks working through a single VTAM.) These CHPID addresses (F0 and A0) are the normal addresses that are resolved on most PCs having only a single Ethernet adapter.

Chapter 3. LANs and TCP/IP


Draft Document for Review September 4, 2009 10:36 am

System z TSO VTAM ftp TCPIP telnet server IOS ftp

PC system

device managers

aws3274 x3270 Linux TCP/IP Linux


different IP addresses

One Ethernet port for eveything ftp user telnet TN3270e browser telnet TN3270e ftp

Figure 3-1 Basic 1090 connectivity

The awsosa device manager is independent from Linux TCP/IP, although it can use the same Ethernet adapter. Up to 16 TCP/IP stacks (in z/OS, z/VM, or Linux for System z) can connect to the awsosa device manager. Each of these TCP/IP stacks defines its own IP address. The configuration shown in Figure 3-1 would have two IP addresses, one for Linux TCP/IP and one for z/OS TCP/IP. These IP addresses are unrelated. External routing rules typically require that both IP addresses be on the same subnet, but this rule is external to the 1090. (Many examples in this documentation series use for the Linux IP address and for the z/OS IP address.) The system in this illustration provides two paths for a user to connect to z/OS TSO. One path is through Linux TCP/IP and the aws3274 device manager. The other path is through the awsosa device manager and z/OS TCP/IP. (In this illustration, the awsosa port could be operating in either QDIO or non-QDIO mode.) Note these differences: The first path mentioned does not involve z/OS TCP/IP. The TN3270e client connects to the IP address used by the base Linux system. The client also specifies the port number assigned to the aws3274 device manager; this is port 3270 in our examples. z/OS accepts the connection as a coax-attached local 3270 terminal and is unaware that the client is actually connected via Linux TCP/IP. For this operation the OSA functions need not be implemented. The MVS console must use this path. The second path uses a different IP address for OSA connections (assigned by z/OS PROFILE statements, or equivalent). z/OS TCP/IP internally passes TN3270e client connections to VTAM and thence to TSO. z/OS TCP/IP can also manage ftp sessions, telnet sessions, and so forth. The MVS console cannot use this path. Notice in Figure 3-1 that there is no link between OSA and Linux TCP/IP. In this configuration you cannot communicate between Linux TCP/IP and OSA TCP/IP applications. You cannot, for example, ftp from Linux to z/OS.8 30

zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

3.2 LAN and tunnel usage

The configuration in Figure 3-2 provides a link between Linux TCP/IP and OSA. This involves additional devmap parameters to establish another OSA with a tunnel between the two TCP/IP stacks.

System z

TSO ftp VTAM telnet server x3270 IOS aws3274 Linux TCP/IP Linux TCPIP

PC system

Note that only a single Ethernet port is used here.


awsosa tunnel


device managers different IP addresses One Ethernet port

ftp user


browser telnet


Figure 3-2 Link between Linux IP and OSA IP

The tunnel environment allows connections between Linux TCP/IP applications (such as ftp, telnet, and x3270) and OSA TCP/IP applications9 (such as ftp, the TN3270e server that is part of z/OS communications manager, and so forth). The tunnel environment creates a virtual adapter similar to an Ethernet adapter. This virtual adapter is assigned its own IP address on both the Linux and OSA side, as illustrated in Figure 3-3. We strongly recommend that the tunnel IP addresses (for the Linux side and the OSA side) be on a separate subnet than any other IP addresses involved in the system. We emphasize this in our documentation by using 10.x.x.x addresses for the tunnel and 192.168.x.x addresses for other connections.

8 9

You can connect to OSA from another (external) Linux, of course. This section means you cannot connect to the same Linux that is the base for z1090 operation. A more exact statment would reference TCP/IP applications within an operating system that is using the OSA-Express2 interface, of course. In our examples this would be z/OS applications (such as the TN3270e server) using the z/OS TCP/IP stack that interfaces to OSA-Express2. We abbreviate this detail by simply referring to an OSA application.

Chapter 3. LANs and TCP/IP


Draft Document for Review September 4, 2009 10:36 am

Linux sees two interfaces (eth0 and tap0)

exists only after the 1090 is started

z/OS sees two adapters and assigns two IP addresses via PROFILE statements

tunnel function


Linux TCP/IP awsosa


Ethernet port

External world

Figure 3-3 Basic concept for a tunnel interface

Setting up a tunnel environment requires additional devmap parameters: [manager] name awsosa 2345 --path=A0 --pathtype=OSD --tunnel_intf=y --tunnel_ip= --tunnel_mask= device 404 osa osa --unitadd=0 device 405 osa osa --unitadd=1 device 406 osa osa --unitadd=2 The parameters for the name statement should be all in one line, not split as shown here. The parameters are as follows: path is the emulated CHPID and A0 is usually automatically assigned for the tunnel interface. The find_io command should be used to verify this CHPID assignment. pathtype is OSD for QDIO operation or OSE for non-QDIO operation. Setting this parameter determines the style of OSA emulation. tunnel_intf=y, if specified, establishes tunnel operation for communication between Linux TCP/IP and OSA TCP/IP. tunnel_ip sets an IP address (for Linux) for the tunnel. It defaults to tunnel_mask sets a Linux subnet mask for the tunnel address. It defaults to unitadd sets the unit address for OSA devices. The addresses default to the two low-order digits of the device number. These addresses typically start at zero for each emulated OSA adapter.10 Considering Figure 3-3, the z/OS TCP/IP profile would have two home addresses ( and in the example) and two sets of DEVICE and LINK statements. The devmap would have two awsosa stanzas, one for the Ethernet adapter and one for the tunnel interface. As already stated, the IP addresses used for both sides of the tunnel interface should be on separate subnets from the "real" Ethernet IP addresses. These tunnel IP addresses are not related to any external IP addresses and we suggest using the 10.1.1.x addresses shown.11


We show addresses 404-406 for the devices in this example. This is because our full configuration used addresses 400-402 for the awsosa adapter connected to the Ethernet port. 11 In general, these should be non-routable addresses.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

The tunnel interface does not exist until the 1090 is started (with the awsstart command). A Linux ifconfig issued before starting the 1090 will not display any tunnel information; the same command issued after starting 1090 operation (assuming the devmap includes a tunnel device) will display appropriate information. In the examples shown here, the user could start an x3270 session on the Linux desktop (of the same machine running the 1090) using one of these options: $ x3270 -port 3270 localhost & $ x3270 -port 23 & Loopback to aws3274 Connect to osa and z/OS TCP/IP

A user on a different workstation, with connectivity to the 1090 LAN network, could use either of these commands: $ x3270 -port 3270 & $ x3270 -port 23 & Connect to aws3274 Connect to osa and z/OS TCP/OP

There is no requirement to use numeric IP addresses; you could establish domain names and use the names instead. There is no requirement to use x3270 if you have a similar TN3270e client. A tunnel can also be used with non-QDIO operation. Each of the connections can be used alone: You might use only aws3274, and have no direct connectivity through OSA. You might use aws3274 and a tunnel connection to an OSA. In this case, the System z would have no direct LAN connection to the outside world. (It would be possible to establish IP forwarding in Linux and have it forward IP packets from the tunnel to the LAN; we do not explore this option in this documentation.) You might use two OSAs, one to a tunnel and one to the LAN, as described above. In most cases, you need aws3274 connectivity for the System z operating system console.

3.3 Routers and DHCP

There are practical aspects of LAN usage that need to be considered. These include: The use of DHCP connections Use of multiple Ethernet adapters In most cases the 1090 user has a single network Ethernet cable interface available, probably connected to a router somewhere external to the user. This external network interface typically expects a DHCP client, and this presents two problems: The System z operating system (z/OS, for example) might not operate as a DHCP client. That is, it may want a fixed IP address. In general, network-connected users do not have fixed IP addresses. The 1090 machine may have multiple LAN adapters, requiring multiple network connections. A small router, as shown in Figure 3-4, can be a useful accessory for a 1090 system.

Chapter 3. LANs and TCP/IP


Draft Document for Review September 4, 2009 10:36 am

fixed IP addresses

DHCP address

1090 machine

router with NAT function multiple LAN adapters, if needed other PCs for x3270 or PCOM sessions

Figure 3-4 Small hub or router usage

LAN connection "in the office wall"

The Network Address Translation function allows your machine to work with fixed IP addresses (provided by the NAT router).12 These are typically in the range. The router, in turn, works with variable DHCP addresses provided by your external network. If NAT is not required, the router in the illustration can be changed to a simple hub. (The hub option assumes the LAN connection can operate with a hub; this is not always the case and you may need help from your network administrators to determine the best configuration.) We specified the base router IP address ( as the default gateway address in our TCP/IP definitions (for both Linux and z/OS). For a multiuser system we connected additional PCs to the router (which supplied its own range of DHCP addresses, if requested). The additional PCs can connect to aws3270 (using the Linux IP address and port 3270) or to OSA (using the IP address assigned specified in the z/OS TCP/IP PROFILE). In a more complex configuration, Linux can be configured to function as a NAT router. This is beyond the scope of this document.

3.4 Wireless connections

Wireless connections can be used by Linux TCP/IP or by OSA. We generally discourage the use of wireless connections because they often do not provide the stability needed for System z operation. Consider the following details: Linux may see a wireless connection as device ath0 or eth0. The find_io command lists a wireless interface along with Ethernet interfaces and associate a CHPID with it. (The CHPID address for a wireless adapter is normally F8.) You can then use this CHPID number as the path parameter for defining an awsosa interface. At the time of writing, the 1090 cannot use wireless connections that appear to Linux as wlan_ devices; only ath_ or eth_ devices may be used. If you use wireless connections, we suggest you confine their use to OSA where temporary link drops can often be tolerated. Using wireless for aws3274 connections (via Linux TCP/IP) is not recommended, especially for an MVS console session.


The router might also function as a DHCP server, providing DHCP addresses in a portion of its address range.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

We cannot provide a cookbook for activating your wireless link for Linux, but you need to have stable Linux wireless operation before trying to extend it to 1090 usage.

3.5 z/OS TCP/IP profile

The z/OS TCP/IP profiles are different for non-QDIO operation and QDIO operation. Long-time users of the AD system are probably familiar with LCS usage. Non-QDIO OSA usage is very similar to LCS operation and the TCP/IP profile that was used for LCS operation can be used for non-QDIO OSA operation. Operation in QDIO mode requires TCP/IP profile changes and new VTAM parameters. The awsosa definitions must include PATH numbers and pathtypes for OSA devices. The type is either OSE (for non-QDIO) or OSD (for QDIO). The PATH is determined by using the find_io command on your system. We cannot predict exactly what the PATH may be for your system.

Non-QDIO operation

When using the non-QDIO interface to the emulated OSA-Express2 function, the key parameters might look like the following: Devmap [manager] name awsosa 22 --path=F0 --pathtype=OSE device E20 osa osa --unitadd=0 device E21 osa osa --unitadd=1 z/OS TCP/IP Profile DEVICE LCS1 LCS E20 AUTORESTART LINK ETH1 ETHERNET 0 LCS1 HOME ETH1 BEGINRoutes ; Destination Subnet Mask FirstHop ROUTE = ROUTE DEFAULT ENDRoutes ... START LCS1


This example assumes that z/OS contains an appropriate CTC or OSA definition for addresses E20 and E21.13 Different addresses could be used, of course, but they must match the IODF in your z/OS system. The HOME address and ROUTE statements in the example are just examples, of course. The GATEWAY statements could be used instead of the ROUTE statements. The --unitadd parameter is used in the devmap because the default OSA unit addresses14 would be 20 and 21 (using the two low-order digits of the device number) and we want unit addresses 0 and 1.15


LAN operation in LCS mode can use CTC definitions in the z/OS IODF. This is a carryover from earlier LAN implementations. 14 This unit address is the (emulated) hardware address within the (emulated) OSA control unit. It is not the device number ("address" in common terminology). 15 The default OAT used by OSA requires unit addresses 0 and 1 when in OSE mode.

Chapter 3. LANs and TCP/IP


Draft Document for Review September 4, 2009 10:36 am

QDIO operation

Recent AD systems include OSA devices starting at device number 400. When using the QDIO interface to the emulated OSA-Express2 function, the key parameters might look like the following: Devmap [manager] name awsosa 22 device 400 osa device 401 osa device 402 osa z/OS VTAMLST OSATRL1 VBUILD TYPE=TRL OSATRL1E TRLE LNCTL=MPC,READ=(400),WRITE=(401),DATAPATH=(402), PORTNAME=PORTA,MPCLEVEL=QDIO z/OS TCP/IP Profile DEVICE PORTA MPCIPA LINK ETH1 IPAQENET PORTA HOME ETH1 BEGINRoutes ; Destination Subnet Mask FirstHop ROUTE = ROUTE DEFAULT ENDRoutes ... START PORTA

--path=F0 --pathtype=OSD osa --unitadd=0 osa --unitadd=1 osa --unitadd=2


Link ETH1 ETH1


The additional VTAM major node is required for QDIO operation. This VTAM node must be active before TCP/IP can be started. The MIH value set for the write interface (401 in the example) should be set to at least 30 seconds.16 (A VLANID parameter is used only if the system is part of a VLAN, of course.) The VTAMLST ATCCON00 member must point to the TRL entry in VTAMLST. The PORTNAME (in the TRLE), the DEVICE name (second field), and the LINK parameter (fourth field) must match. The name is arbitrary, but it must be the same in all three places.

3.6 Telnet to z/OS

If you elect to install the tunnel connection as described earlier (an as shown in the complete example listed in the Appendix), you can connect from the base Linux to z/OS by both telnet (in line mode) or by a TN3270 client such as x3270. Using the IP addresses from our examples, the Linux commands would be: $ x3270 & $ telnet 1023 (to start a TN3270 session via z/OS TCP/IP) (line-mode telnet session via z/OS TCP/IP)


This was recommended by the developers. In simple usage we have not seen any problems using the default z/OS MIH values.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

The 1023 parameter in the telnet command specifies the port number that the AD-CD TCP/IP and UNIX System Services profile use for telnet connections. This port number (1023) is not standard, and probably applies only to the AD-CD z/OS system.

3.7 Choices

Which 3270 connection mode is better? If only simple 3270 connections are needed (and not more than 32 sessions are needed), then the use of basic aws3274 connections is better. This is simpler to set up and does not require OSA or z/OS TCP/IP to be configured or started. Which CHPID mode should you use for OSA connectivity? QDIO mode has many advantages for TCP/IP usage on a larger System z; it reduces the System z workload and provides automatic sharing of the adapter across multiple LPARs. These considerations do not fully apply to a 1090 system. The following points are relevant: QDIO operation offloads some processing from the 1090 CP to the Linux processor. The offloading is not as much as on a larger machine, but it helps. It also reduces the number of System z instructions needed to maintain LAN I/O operation. In informal operation we noticed that ftp performance was about 20% faster with QDIO than with LCS. QDIO operation is only for TCP/IP; it does not handle SNA. QDIO can provide VSWITCH, IPv6, and Enterprise Extension connections. QDIO operation requires that OSA devices be defined in z/OS. These were not present in AD systems prior to z/OS 1.8. The devices could be added to earlier AD systems, using HCD to create a new IODF, or might be present in z/OS systems not derived from the AD packages. Non-QDIO operation can mix TCP/IP and SNA (or handle just SNA or just TCP/IP). However, SNA operation of the 1090 is not supported at this time. Suitable non-QDIO (LCS) devices have been defined in all the earlier z/OS AD systems. (These are the CTCs starting at address E20.) The required OAT table is automatically updated when QDIO is used. The default OAT table is probably satisfactory for non-QDIO TCP/IP usage and may be satisfactory for SNA usage (although SNA is not supported at this time). The OSA/SF utility functions are used (if needed) to manipulate the OATs. Other than these points, there is no practical difference between using QDIO or non-QDIO on a 1090 system. In particular, the end user at a TN3270 TSO session cannot detect the difference. Normal TCP/IP functions, such as ftp and telnet, do not detect any differences. If you are using recent AD systems (or another z/OS package with OSA devices defined) we suggest you use QDIO mode because this represents the future direction for z/OS LAN operations.

3.8 Useful networking commands

The following commands may be useful when working with LAN devices: z/OS operator commands D U,,,dddd,nn D M=DEV(dddd) D M=CHP D IOS,MIH SETIOS MIH,DEV=E201,TIME=00:30 TSO commands dddd = address, nn = number to display provides path status display all CHPIDs defined to z/OS display current MIH values example of setting MIH

Chapter 3. LANs and TCP/IP


Draft Document for Review September 4, 2009 10:36 am


display display display display

all devices and links home address gateway addresses connection status

vary local 3270 active to VTAM display major nodes display information about specific node list the TRLEs data about specific TRLE activate a major node remove inactive TRLEs from TRL list

It is important to note that the name LCL701 in the sample V NET command is the VTAM name of the terminal. This name is not related to the LUname specified in the 1090 devmap. A 3270 session has both an aws3274 LUname (specified in the 1090 devmap) and a VTAM name (specified in VTAMLST). Basic MVS consoles are not specified in VTAM and have no VTAM name. This terminology is unfortunate because the aws3274 LUname (used to link a TN3270e session to an aws3274 definition) is not necessarily the same LUname associated with VTAM operation. Please note that zPDT does not support the VMAC function from z/OS. The only virtual mac supported is generated on z/VM with the layer-2 vswitch.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Chapter 4.

Basic zPDT commands

The full set of zPDT commands, with their syntax, is listed in Volume 1 of this series. This chapter illustrates use of the more common commands. 1090 commands fall into several categories: Setup commands, typically used when the 1090 is not operational Basic operation commands, to start the 1090, IPL a system, and later stop the 1090. CP commands for low-level operations such as displaying System z memory Miscellaneous commands All of these commands are Linux executable files. They must be used under the same Linux userid that started 1090 operation. Only one 1090 instance may be started by a given userid and the commands assume they are to work with that instance. (The setup commands are not directly related to a running 1090 and can be used by any Linux userid that can access them.)

4.1 Setup commands

The following commands (with operand examples) are typically used when the 1090 is not operational. The awsckmap command may be used after changing a devmap. It simply verifies that the devmap is in the correct format. It does not verify that files are in the correct emulated format.1 $ awsckmap aprof1 $ awsckmap /bill/map123.txt $ awsckmap aprof1 --list check devmap can specify a full path name long list

An emulated disk volume must be created before it can be used by the 1090. The alcckd command creates 3380 or 3390 volumes. There are four standard-size 3390 volumes (3390-1, -2, -3, -9) that can be created by specifying the full model type. Otherwise the -s


The processing is more sophisticated than indicated. If the devmap specifies an IOCDS, the information from that IOCDS is merged with the devmap and the resulting specifications are verified by awsckmap. A different IOCDS than what is indicated in the devmap may be used via an --iocds n parameter.

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

parameter may be used to specify the number of cylinders to create.2 The emulated volume contains only the effective cylinders; diagnostic and alternate cylinders are not emulated. $ alcckd /z/WORK01 -d3390-3 $ alcckd /z/WORK02 -s9000 -d3390 $ alcckd /z/WORK03 -d3390-1 -z create emulated 3390-3 volume create volume with 9000 cylinders create and zero the volume

The alcckd command does not place any software blocks (label, VTOC) on the volume. The user must do this later, using operating system utilities. The find_io command (which has no operands) is used to list Ethernet interfaces and their associated CHPID number (relevant only for interfaces used for OSA Express emulation). The z1090ver command may be used to determine the version of the 1090 that is being used. The z1090instcheck command may be used to partly verify that the Linux environment is correct for the 1090.

4.2 Basic operation

These two commands start and stop 1090 operation. In the example, the devmap (file name aprof1) is in the current directory; otherwise, a complete path name would be used. $ awsstart aprof1 $ awsstart aprof --clean $ awsstop start 1090 operation3 erase old 1090 logs/traces/dumps stop 1090 operation

The awsstop command instantly ends System z operation. No warning is sent to the System z operating system. We recommend that the System z operating system be stopped normally (whatever this may mean for various operating systems) before issuing awsstop. The token command may be used to verify that the hardware key is available to the 1090. This command works only when the 1090 is running. The ipl command performs the architected System z IPL operation. It must point to a device that has a suitable IPL program installed. This is normally the operating system residence device but could be a disk or tape that contains a stand-alone System z program. The use of an IPL parameter is completely dependent on the operating system involved and how the parameter is configured for that instance of the operating system. The 1090 environment must be initialized (via awsstart) prior to issuing the IPL command. $ ipl 560 $ ipl A80 parm 0A82CS simple IPL IPL with parameter

The awsmount command is used while the 1090 is running. It displays or changes the emulated device file associated with an emulated device. The first example is equivalent to mounting a tape on the device at address (device number) 560. This function makes the device ready and sends the appropriate attention interrupt to the operating system. This command is not limited to emulated tape drives, although that is the most common use. It can also be used for emulated disk drives or an emulated printer. $ $ $ $

2 3

awsmount awsmount awsmount awsmount

560 560 560 560

-m /z/mytape -o /z/tape05 -q -s

mount volume when none is mounted mount another volume, replacing old query device file status rewind emulated tape

Specifying more than 65520 cylinders creates a large volume. You should verify that your System z operating systems supports these before creating one. The earlier versions of awsstart required the characters "--map" before the devmap name. This is now optional.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

$ awsmount 560 -x

rewind and unload emulated tape

If a file name is mounted as a emulated tape and that file does not already exist, it is automatically created by the awsmount command. You must be careful when typing the file name in an awsmount command to ensure that you specify the correct name and directory. For example suppose you intended to mount and write to an existing emulated tape, /tape/oldtape1, but instead typed: $ awsmount 560 -m oldtape1 This would allocate a new awstape file named oldtape1 in your current directory. If you then write a large amount of data to this file, it can fill your /home file system and possibly cause problems. z/OS's label processing routines will catch some of these problems, but not all, so you should always be careful to use the correct names. Files mounted with awsmount must be appropriate for the device, of course. A file mounted on an emulated tape drive must be in awstape format. (For an emulated tape drive opened for output, a new awstape file is automatically created if necessary.) A file mounted on an emulated 3390 disk drive must be in awsckd format. None of these formats are standard Linux formats; the emulated disk device files must be created with 1090 utilities. Emulated tape files (awstape) are created by writing to an emulated tape drive. Emulated tapes, mounted with the awsmount command. The awsstat command provides the status of emulated I/O devices, including the Linux file name mounted on the device and (for disks) the last track used. $ awsstat $ awsstat 0A80 0A82 $ awsstat -i2 0a82 query status of all emulated devices query status of specified devices display status every 2 seconds

The display output from awsstat is wide; it is best to widen the Linux window to almost full screen width before using awsstat. An example of the command is the following: $ awsstat A82 Config file: /ibmsys1/aprof1 DevAdr Subch ---Mgr-- Actv Busy --PID-- -----Device Information---------0A82 15 AWSCKD Yes No 4329 Cyl-368, Head-10 /z/S7SYS1 Most of the output has obvious meanings. The Subch (subchannel) is an internal detail and the PID (Linux process id) is not normally needed. The DevInfo field shows the current logical position in the device. The awsin command sends input to an emulated 3215. z/OS does not use 3215 devices but they are sometimes used by other operating systems. If only one 3215 is defined then the device number (009 in this example) need not be entered (unless the data element starts with a numeric digit; in this case the device number must be entered). $ awsin 009 'This is input' $ awsin 'This is input' assume 3215 address 009 if only one 3215 defined

The oprmsg command sends input to the "hardware console" or "HMC console", or "SCLP operator message interface." This is the interface used by z/OS, for example, when all the normal z/OS consoles have been lost. There is no device address associated with this interface. $ oprmsg 'V CN(*),ACTIVATE' send message to z/OS

1090 commands function as Linux commands, and are entered through a shell prompt. The operands must conform to Linux shell rules. Some characters, such as dollar sign ($), right parenthesis (, and left parenthesis ), have special meanings when entered as part of a

Chapter 4. Basic zPDT commands


Draft Document for Review September 4, 2009 10:36 am

command through a shell. It is necessary to escape these characters. This can be done by placing single quotes (' `) around the whole operand or by placing a backslash (\) before each special character. The ready command generates an asynchronous device end for the indicated emulated device. This is typically associated with mounting a new volume on the device. $ ready 590 The ipl_dvd command emulates the operation of using an IPLable DVD in an HMC. Some software, such as z/VM, is distributed in this way $ ipl_dvd /media/530_GA_3390_DASD_DVD/cpdvd/530vm.ins The file name used with ipl_dvd must be in the correct .ins format, which is similar to an OMA control format. Our particular example involves VM and this may not work without the HMC function because this mode of VM installation uses unique HMC 3270 functions. Some Linux distributions may be packaged for DVD installation.

Search paths

Our examples use a parameter on the awsstart command to specify the devmap. There are other ways to find these files. The complete search algorithms, in the order used, are as follows: To find the devmap: Use the file named in the awsstart parameter, if specified Use the CONFIG_FILE environment variable, if it exists Use file devmap.txt in the current directory, if it exists Use /home/<userid>/z1090/configs/devmap.txt, if it exists (not recommended) Error, if none of the above exist

4.3 CP commands

The following commands control operation of the 1090 System z processor(s), known as CP(s). The first (or only) processor is CP number 0. A second processor (if it exists) is CP number 1, and so forth. By default, these commands are sent to CP 0. The CPU command may be used to specify a different default processor. These commands can also be directed to zIIPs, zAAPs, and IFLs which are assigned cpu numbers as if they were CPs. $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ cpu 1 stop start 1 restart 0 query 0 interrupt 0 storestatus sys_reset storestop 1AC0 adstop 1AC0 on adstop 1AC0 off memld <file name> address loadparm 0a8200 loadparm -d tracem specify default processor stop indicated (or default) processor start indicated (or default) processor perform CP restart function query indicated processor send external interrupt before taking stand-alone dump perform System z reset stop on store in absolute address set an address stop at indicated address remove the address stop load Linux file into System z memory set SCLP IPL parm (for SCLP usage only) display SCLP IPL parameter control interrupt trace


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

The following display and change commands are best used when the CP is stopped. Addresses specified for the adstop, d, and st commands are real addresses or virtual addresses, depending on how the address is written: address address address address $ $ $ $ 1AC0 v1AC0 vh1AC0 vs1AC0 real memory address4 virtual memory address (primary AS) virtual memory address (home AS) virtual memory address (secondary AS) display 64 bytes from address 1AC0 display x'40' bytes (real address) display, including EBCDIC modify memory value at address v1AC0 display psw for current mode set 128-bit PSW display general registers display general register 3 store x'00001234' in 32-bit register store x'0000000000001234' in 64-bit reg display floating point registers display floating point register 3 store x'1234567887654321' 64-bits display access registers (always 32-bits) store x'0000ABCD' in access register 3 display control regisers store 32 bits in control register 1 store 64 bits (x'00000000AABBCCDD') display architecture mode display floating point control register display prefix register

d v1AC0 64 d 1AC0.40 d t vh1AC0 32 st v1AC0 47F01CD0

$ d psw $ st psw FF007AB0 0 0 123456 $ $ $ $ d g d g3 st g1 1234 st gx1 1234

$ d y $ d y3 $ st y1 1234567887654321 $ d z $ st z3 ABCD $ d x $ st x1 AABBCCDD $ st xx1 AABBCCDD $ d r $ d yc $ d pfx

The following conventions are used for the display and store commands: The display storage commands take the specified address and round it downward to the nearest 32-byte (hex 20) boundary. Memory display commands display 32 bytes (in hex) per line. If the t parameter is used, EBCDIC is also displayed at the end of each line. In either case, the lines are long and the Linux window used should be wide. Store commands for memory work in bytes, starting at the address specified in the st command. Registers are displayed as 64-bit registers when in z/Architecture mode and 32-bit values when not in z/Architecture mode. Store commands (memory and registers) assume data is in hex. Store commands for registers work in 32-bit words (st g commands) or 64-bit words (st gx commands). Data is padded on the left with zeros. Memory displays include the storage protection key (displayed after the hex data). PSW values (st psw xxx) are entered as 32-bit words. Changing a 128-bit PSW means that four operands are needed. The command st psw 123 456 789 ABC places


By "real memory address" we mean an address in System z memory. The "real address" is not translated through the System z virtual memory process.

Chapter 4. Basic zPDT commands


Draft Document for Review September 4, 2009 10:36 am

x'00000123' in the first word of the PSW, x'00000456' is intended for the second word (but the second word is forced to zeros), x'00000789' is placed in the third word, and x'00000ABC' is placed in the last word. If a storage word operand overflows (for a register or segment of the PSW) the value is set to x'FFFFFFFF. Floating point registers are always treated as 64-bit words. A memld command might be: $ memld /home/ibmsys1/initrd 800000 This would read the contents of the indicated Linux file into the System z memory, starting at real address (hexadecimal) 800000.

4.4 Devmaps

A devmap must exist when starting 1090 operation. The devmap defines the size of System z memory and several other parameters. It also specifies which device managers to start and what emulated devices are connected to each device manager. Many devmaps may exist; they are simple Linux text files. Only one devmap can be used when starting a 1090 instance and it cannot be dynamically changed while the 1090 is running. Typically, zPDT users have a number of devmaps for a variety of purposes. For example: A devmap for the current z/OS release, with only the basic IPL volumes and no OSA. A devmap for the current z/OS release, with all the volumes that have been installed and with one or two OSAs (depending on the LAN and tunnel environment desired). A devmap for a previous z/OS release (using the normal AD-CD device numbers). A devmap contains both the current AD-CD release (using the normal device numbers) and a previous release (using other device numbers). A devmap for basic z/VM. A devmap for z/VM and one (or two) z/OS releases. Appendix A, "z/OS 1.10 AD CD example" on page 51 provides an example of a complete devmap, along with the z/OS TCP/IP setup require for both LAN and tunnel usage.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Chapter 5.

Frequently asked questions

The following FAQs are more specific to installation and detailed usage. Volume 1 of this redbook series contains additional FAQs that are more related to initial zPDT concepts. Q: I have large System z memory defined in my 64-bit zPDT system, but it is not larger than the shared memory value you recommend (17,179,869,184 bytes for 64-bit machines). I cannot start the 1090 and the problem seems related to memory size. Why? A: The shared memory size specified by the kernel.shmmax parameter must be large enough for all users of shared Linux memory. (We are discussing virtual memory or address space memory here, not real PC memory.) The System z memory you define in your devmap is only one of the users of shared Linux memory. We cannot provide an exact formula, but your kernel.shmmax value should be at least 100MB larger than your defined System z memory. Also, note that the shared memory size specified by kernel.shmmax sets the total limit for all processes, including multiple 1090 instances. If multiple zPDT instances exist, the shared memory must be large enough for all of them. Q: Can I use a SCSI DLT tape drive? A: It should work (provided it supports the SSC-3 SCSI Command Set for Sequential Devices), although this is not supported by IBM and has not been tested. Q: Can I use a SCSI 4mm tape drive? A. It might work but we strongly suggest you do not use 4mm drives. These have proven to be poorly suited for emulated S/390® work. Q: Will using a zIIP or zAAP or IFL increase the performance of my 1090? A: No, assuming you are replacing a CP with the zIIP or zAAP. These speciality processors operate at the same speed as a "normal" 1090 CP. They are provided to allow developers to verify that their applications use a zIIP/zAAP/IFL in the intended manor. Q: Can I use hyperthreading on my PC? A: Yes, it can increase general Linux performance for an L01 system. We have not tested this environment for an L02 or L03 system (two or three CPs), but we suspect it would not work well. Q: Is the floating point hardware of the base machine used when executing System z floating point operations?

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

A: Sometimes. This is a complex area when floating point exception conditions are considered and IBM has not disclosed the 1090 design for this area. Q: Why do you not provide a definite MIPS value? This would help us determine how to best use the 1090. A: There are no definite numbers. A MIPS measurement is very dependent on the exact workload. The approximate ranges we usually discuss for the 1090 assume a traditional commercial application mix, although even this is difficult to exactly define. Q: Why are there warnings about running beagle in a 1090 system? A: Beagle attempts to index the contents of the file systems. A typical 1090 has a number of emulated 3390 volumes containing mostly EBCDIC and executable data sets. From a Linux viewpoint, these are binary files and attempts to index them can lead to excessive CPU usage by beagle or similar programs. It may be possible to control this situation through beagle configuration parameters, and we notice that the problem does not always arise when beagle is running. Q: Can I run multiple TCP/IP stacks on a single emulated OSA-Express adapter? A: Yes. Q: Can I place emulated 3390 volumes on an NFS server? A: In principle, yes. However, access time must remain within the tolerance that z/OS expects for disk activities. In general, we do not think this is a good idea. (If any I/O operation takes more than 30 seconds, the 1090 device manager is considered dead and is restarted. z/OS has internal timers with much shorter timeouts than 30 seconds.) Q: Can I share emulated volumes on an NFS server with several 1090 machines? A: No. This would almost certainly result in corrupted data unless the NFS files are read-only files. Such usage might be practical for AWSTAPE files. Q: My OSA interfaces do not start and I receive error messages that SIOCGIFINDEX failed. What is this? A: This seems to occur mostly with openSUSE 10.3. If you run the find_io command, you will probably see that the LAN interfaces do not have MAC addresses. We do not know exactly what triggers this problem, but we find that updating openSUSE 10.3 (using the online update function that is part of the Linux system) often resolves the problem. We suspect that the support levels for particular brands of Ethernet adapters may be the cause. Q: Why do I need to specify a unit address in the device statements for OSA? I do not understand these. A: A full discussion is beyond the scope of this document. For TCP/IP, you need to ensure that the unit addresses associated with non-QDIO TCP/IP usage are 0 and 1. (This is required by the default OAT used by OSA.) You need to ensure that unit address FE is used only for OSA/SF when using the default OAT. You need to remember that the default unit address is the same as the low-order two digits of the device number ("address"). Provided you meet these requirements there is no need to specify a unit address in the device statements for OSA. We find is easier to consistently specify unit addresses in the device statements, usually starting at address zero. Q: Does zPDT support thin interrupts? A: Not at the time of writing. Q: Can I filter IP traffic before it is sent to my emulated OSA-Express interface? This reduces the overhead involved in rejecting packets not addressed to my system. A: In OSD (QDIO) mode there is no filtering. In OSE (non-QDIO) mode you can customize the OAT with your IP address. If this is done, the OSA interface will pass only packets intended for this IP address. If this customization is not done (and it is not done in the default 46

zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

OAT) then all packets are sent to the host TCP/IP and unwanted packets are rejected at that level. Q: Is OSA-Express emulation different than OSA emulation? A: Yes, very much so, although OSA operation of simple TCP/IP can usually be provided by OSA-Express without changes to the System z operation. (This question is related to a terminology problem and assumes that OSA means the original OSA adapter, which operated largely as an LCS device.) Q: Is OSN operation (CDLC) provided with OSA-Express2 emulation? A: No. Q: Does OSA-Express2 emulation support jumbo frames? With QDIO? With non-QDIO? A: Jumbo frames are not supported by the Linux-based 1090. Q: Should I use 1492 or 1500 as the maximum packet size (MTU) when using awsosa? A: Use a maximum of 1492. The details are beyond the scope of this document. (As best we can tell, the System z communication routines automatically adjust this number down if necessary. Thus it probably does not matter whether you specify 1492 or 1500.) Q: I want to use the OSA Express function with QDIO, but my z/OS does not have any OSA devices defined. How do I add them to z/OS? A: This is done with the HCD utility under z/OS, creating a new IODF. Extensive IBM documentation exists for HCD. Q: Does QSA-Express emulation include advanced functions such as VIPA? A: Yes, when using QDIO. Q: Can I use a continuing range of addresses (device numbers) when I have multiple OSA QDIO interfaces? For example, 400-402 for TCPIP1, 403-405 for TCPIP2, and so forth. A: No. The first OSA address (for a TCP/IP stack, in this example) must be an even number. You would need to use 400-402, skip 403, then use 404-406, skip 407, and so forth. Q: Do the OSA-Express2 offload functions work? Do they accomplish anything on an emulated system? A: The Linux-based 1090 OSA implementation does not use offload functions at this time. Q: What PC Card (PCMCIA card) should I use for additional Ethernet ports on a ThinkPad? A. Use any card that the base Linux system accepts. We tested with an Xterasys Gigabit PC Card (98-012084-585). We also informally tried several older IBM 10/100 Etherjet cards. Q: The Ethernet operation on my internal ThinkPad adapter seems unusually slow or erratic. Is this a known problem? A: This problem is not related to 1090 usage. We found the same situation on our T60p ThinkPad under SUSE 10.1 and a little research on the Web produced the following suggestion: # rmmod e1000 # modprobe e1000 RxIntDelay=4 RxAbsIntDelay=10 This provided a substantial improvement for ping, but did not help other functions very much. You must evaluate the effects in your own environment. (These commands are effective only for the current boot session.) This problem appears to have gone away in later Linux distributions. Q: Can I use IP aliasing in Linux while using the 1090? A: No, not at the time of writing.

Chapter 5. Frequently asked questions


Draft Document for Review September 4, 2009 10:36 am

Q: I have multiple Ethernet adapters, each on a different subnet. Response is very slow and I get multiple responses to pings. Is there a problem using multiple adapters? A: In general, no. However, multiple interfaces on different subnets should not be connected to the same VLAN. This creates routing, ARP, and duplicate response issues. Q: I have an error message about GVRP when I try to use a VLAN/VSWITCH in z/VM. Is this supported: A: No, GVRP is not supported. You should specify NOGVRP for your VSWITCH. Q: Why do some AD releases pause for 120 seconds while shutting down? A: You can edit the SHUTDOWN entries in PARMLIB to remove or change this. Q: I am using z/VM and have a problem with MONITOR. Does the 1090 support this usage? A: An APAR fix for z/VM 5.2 and 5.3 is available to resolve this problem. It is APAR VM64385. Q: You are inconsistent with the addresses for the AD volumes. For example, sometimes volume SARES1 is at address A91 and sometimes at address AA0. Which is correct? A: Both are correct. Any 3390 volume can be at any address that is defined as a 3390 in the IODF for that z/OS system. For ease of documentation we always show the IPL volume at A80 and the SYS1 volume (which contains the IODF and IPLPARM datasets) at A82, but these addresses are not required. The IPL address and parameter much match the addresses you use, of course. Q: What happens if I remove the hardware key? A: The 1090 will stop after a while. Q: You use userid ibmsys1 throughout all the examples. Is there something special about this userid? A: No. Q: Is there any national language support in the 1090? A: No. Q: Can I use an alternate translation table to convert EBCDIC to ASCII for awsprt output? A: No. Q: Can I use multiple 1090 tokens to obtain more CPs? A: No. Q: I have several Linux windows open while running the 1090. I can enter 1090 commands in any window, which is convenient. However, I also sometimes get output messages in a different window from where I entered a command. Is this normal? A: Yes. 1090 output messages (but not command output messages) are sent to the console session that issued the awsstart command. Q: My z1090 rpm installation failed with an error message about db_recovery. What now? A: Try the command rpm --rebuilddb and then install z1090 again (using the z1090 installer program, of course, and not trying to directly install the z1090 rpm). Q: Can I routinely migrate to the next Linux releases when they become available? A: Maybe. There is no unique 1090 tie to a particular release. However, it is possible that the 1090 installation steps might not work for a new release (due to different library paths) or that the new release might not support the particular hardware in your base machine. IBM support exists only for the recommended release(s).


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

Q: I am using an emulated printer and this sends output to a Linux file. Does this file remain open for output by the 1090 all the while the 1090 is running? A: Yes. It is closed if you use awsmount to assign a new output file for the printer. Q: How do I turn off the gnome screen saver in openSUSE? A: Desktop -> Control Center -> Screensaver. Uncheck the Activate screensaver when session is idle option. Q: Is there an easy way to delete all the existing disk partitions when installing openSUSE? A: Yes, delete the /dev/sda entry. This does not really delete the hard disk, but it does delete all partitions on it. Q: Can emulated printer output be directed to /dev/lp0 or something similar? A: We do not know; this was not tested. Q: I installed a different HDD in my T60 ThinkPad and now I cannot boot from CD or HDD. A: You may have installed the new HDD upside down. It is easy to do. Q: You provide very explicit Linux component lists in your examples. Can I include more packages? A: Yes. We routinely include the C/C++ compiler, for example, although it is not needed for the 1090. Q: Does the 1090 operate in kernel mode? In suid mode? A: Kernel mode is not used, but one module (part of awsosa) operates in suid mode. Q: How do I add more openSUSE components after I have completed the basic installation? A: Application -> System -> Yast -> Software Management -> Filter: Package Groups and then follow the installation prompts. Q: You specified that userid ibmsys1 should be a member of group ibmsys. Is this needed? A: As far as we could determine, there is no need for this group. However, it was used on all the development systems during 1090 development. Q: Are 1090 commands case sensitive? Can I issue ipl or IPL? A: The commands are case sensitive. They are simply the names of Linux files and Linux file names are case sensitive. Q: Is there a separate Linux process for each emulated device? A: Yes. Q: Can I run as root when installing and using the 1090? A: No. Please follow the instructions concerning when to work as root and when to work under a normal userid (such as ibmsys1). Q: The z1090instcheck command does not work or gives the wrong results. Why? A: You may need the full path name for the z1090instcheck command in some cases. Your PATH may be pointing to a down-level version at the time you issue the command. Also, you must have installed the 1090 code before you can use this command. Q: I have a SCSI tape drive. I want to use it directly for Linux functions (not directly connected with 1090 operation) but I cannot find the mt command (a "standard" Linux command for manipulating tape devices). A: We noticed that mt is not always installed with some Linux distributions. In some cases it appears to be part of the cpio rpm. For 64-bit RHEL 5.2, we needed to install mt-st-0.9b-2.2.2.x86_64.rpm to obtain the mt command.

Chapter 5. Frequently asked questions


Draft Document for Review September 4, 2009 10:36 am

Q: Does the 1090 handle 3270 nulls correctly? A: This is not a function of the 1090; it is a function of the 3270 emulator and, to some extent, the application involved. Relevant functions for x3270 can be found in Options -> Toggles -> Blank Fill. The ISPF command nulls on|std|all|off may be relevant. Q: Does IBM need to enable something to allow full operation of the five crypto instructions? A: No, full operation is always enabled. Q: How can I write a tape mark on an AWSTAPE volume? A: Use awsmount xxx --wtm where xxx is the address (device number) of the tape drive. Notice there is a double dash before the wtm option. Q: Where do I obtain OMA distributions? A: We do not know of any IBM products currently distributed in OMA format. Q: Should device statements (in a devmap) be in order by addresses? A: No particular order is needed. Q: I want to use PCOM instead of x3270. Is this acceptable? Can you include it with the 1090 package? A: Yes. However, you should use a release later than PCOM 5.5. We have verified that version 5.5 is not suitable for the 1090. PCOM is part of a separate IBM product. We cannot include it as part of the 1090 package. Q: I installed the recommend Linux on my T61p ThinkPad, but I cannot access the token (or a USB disk drive). A: It appears that USB usage may be sensitive to BIOS levels. In at least one case, updating the T61p to the current BIOS level (which was 2.09, at the time of writing) solved the problem. A: The AD system always starts TCPIP and associated jobs. How can I delete them? Q: You can edit the VTAMAPPL entries in PARMLIB and remove the associated commands. While running z/OS you can issue P TCPIP, wait a few seconds, and then issue C INETD4. Q: Can I use RMF? A: Yes, but not all of it is relevant on a 1090 system. Q: I have volumes at addresses A80 through A8F. Do I need to define a new awsckd unit in order to add more disk volumes? A: No, you can have up to 256 volumes in one instance of awsckd. Q: I am using the IBM PCOMM product to connect from a remote PC to z/OS running on the 1090. Every time I start PCOMM it wants to print something. How can I stop this? A: This is a well-known issue, and is not related to the 1090. PCOMM stores user profiles in .ws files (such as, for example). Find the .ws profile you are using and add the following lines: [LT] IgnoreWCCStartPrint=Y at a reasonable place in the profile.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Appendix A.

z/OS 1.10 AD CD example

Using a normal T60p ThinkPad, we installed the z/OS 1.10 AD including all the volumes present on the DVDs. We used the single T60p Ethernet adapter for OSA connectivity and configured it both for LCS mode and QDIO mode (but using only one mode at any time.) This appendix describes our specific definitions. Although this material applies only to the z/OS 1.10 AD system, it may be helpful when setting up other environments.

A.1 Disk planning

The 21 3390-3 volumes1 in the 1.10 release require about 61 GB disk space. (It is unlikely that many users would elect to install all the volumes. Four volumes are needed to IPL; all the others are optional, depending on your usage plans.) We also had two 3390-1 volumes with local data. This made a total of 60 GB for emulated disk volumes. Our Linux base was installed in a single 8 GB partition, and we created a 2-GB Linux swap partition. Our total usage was 70 GB. This left some free disk space (on a nominal 100 GB HDD) for emulated tape volumes and so forth.

A.2 Connectivity planning

We had a single Ethernet adapter in the T60p and used it for both OSA and base Linux functions. We used the internal Linux TCP/IP loopback connection ( to operate several x3270 sessions on the Linux desktop. These sessions were used for the MVS console and local TSO connections. We used a tunnel interface to communicate between Linux TCP/IP and z/OS TCP/IP. The tunnel interface appears as a tap0 device (similar to an Ethernet device) to Linux and as a separate OSA channel to z/OS. The TCP/IP connectivity is as follows: The IP address for Linux (from external connections on a router/hub) is This IP address cannot be accessed from z/OS.


This assumes we installed DB2 V9 instead of DB2 V8. Both versions are included with the AD system.

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

The IP address of z/OS (from external connections on a router/hub) is This IP address cannot be accessed from Linux. The IP address for internal connections to Linux TCP/IP (from the x3270 sessions, for example) is; this is the default localhost address for Linux. The IP address used to access z/OS from Linux (via tunnel) is The IP address used to access Linux from z/OS (via tunnel) is The IP address of the router is and this is the default route for z/OS and Linux.

These connections seen by z/OS as local, channelattached 3270s. z/OS does not see any TCP/IP involvement

emulated System z

PC System

TSO ftp x3270 sessions for MVS console and TSO user VTAM IOS x3270 x3270 Base Linux TCP/IP Linux TCP/IP router/hub Single Ethernet adapter used for OSA and Linux telnet TN3270e browser ftp AWS3274 AWSOSA AWSOSA tunnel TCPIP

z/OS sees these TCP/IP links

device managers SUSE Linux

Figure A-1 Connectivity with single Ethernet adapter

A.3 Listings

We used the find_io command to determine that our Ethernet adapter was eth0, and that it was assigned as CHPID F0. (As a practical matter, the integrated Ethernet adapter is always assigned to CHPID F0.) The tunnel interface is always CHPID A0. We elected to use the QDIO mode for both OSA interfaces, although the listings also show non-QDIO settings as comments. We used the following devmap: [system] memory 1600m 3270port 3270 processors 2 cpuopt vsi=on [manager] name aws3274 0002 device 0700 3279 3274 device 0701 3279 3274 device 0702 3279 3274 device 0703 3279 3274

mstcon tso tso tso


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

[manager] name awsckd device 0A80 device 0A81 device 0A82 device 0A83 device 0A84 device 0A85 device 0A86 device 0A87 device 0A88 device 0A89 device 0A8A device 0A8B device 0A8C device 0A8D device 0A8E device 0A8F device 0A90 device 0A91 device 0A92 device 0A93 device 0A94 device 0A95 device 0A96

0001 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390 3390

3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990 3990

/z/ZARES1 /z/ZARES2 /z/ZASYS1 /z/ZAUSS1 /z/ZAPRD1 /z/ZAPRD2 /z/ZAPRD3 /z/ZADIS1 /z/ZADIS2 /z/ZADIS3 /z/ZADIS4 /z/ZADIS5 /z/ZADIS6 /z/ZADB91 /z/ZADB92 /z/ZACIC1 /z/ZAIMS1 /z/SARES1 /z/ZAWAS1 /z/ZAWAS2 /z/ZAWAS3 /z/WORK01 /z/WORK02

#local volumes, not part of AD

# The following two stanzas for LCS operation #[manager] #name awsosa 0003 --path=F0 --pathtype=OSE #device E20 osa osa --unitadd=0 #device E21 osa osa --unitadd=1 #[manager] #name awsosa 0013 --path=A0 --pathtype=OSE --tunnel_intf=y #device E22 osa osa --unitadd=0 #device E23 osa osa --unitadd=1 # The following two stanzas for QDIO operation [manager] name awsosa 0009 --path=F0 --pathtype=OSD device 400 osa osa --unitadd=0 device 401 osa osa --unitadd=1 device 402 osa osa --unitadd=2 [manager] name awsosa 0019 --path=A0 --pathtype=OSD --tunnel_intf=y device 404 osa osa --unitadd=0 device 405 osa osa --unitadd=1 device 406 osa osa --unitadd=2 [manager] name awstape 004 device 581 3490 3490

Appendix A. z/OS 1.10 AD CD example


Draft Document for Review September 4, 2009 10:36 am

[manager] name awscmd 1000 device 580 3490 3490 Notice that we have two sets of awsosa stanzas, with one set commented out. One stanza (the first) is for LCS operation and the other is for QDIO operation. You can use one or the other, but not both at the same time. LCS operation requires two devices (E20 and E21, for example). QDIO operation, as used here, requires three devices (400-402, for example). The operations of the two OSA CHPIDs (F0 and A0) are independent; we could use a mixture of LCS and QDIO for the two CHPIDs. No modifications or definitions are needed in Linux to define the tunnel interface. This interface (and associated IP address) does not exist until awsstart is issued, using a devmap that contains the tunnel_intf operand in an awsosa definition. QDIO operation requires a TRL major node in VTAM. This is provided by member OSATRL1 in ADCD.Z110.VTAMLST in the AD system, which we changed slightly. (The TRL member name is included in the list in member ATCCON00). The continuation characters (the X characters) are in column 72. OSATRL1 VBUILD TYPE=TRL OSATRL1E TRLE LNCTL=MPC,READ=(0400),WRITE=(0401),DATAPATH=(0402), PORTNAME=PORTA, MPCLEVEL=QDIO OSATRL2E TRLE LNCTL=MPC,READ=(0404),WRITE=(0405),DATAPATH=(0406), PORTNAME=PORTB, MPCLEVEL=QDIO X X X X

We need both TRLEs only when using two OSA definitions, of course. These definitions are not used when operating in LCS mode. We used the following TCP/IP profile in z/OS. This profile contains device definitions for both LCS and QDIO modes. Only one would be used at any given time for a given interface, and it should match the devmap choice. (If using the z/OS AD system, be certain to update the correct PROFILE. In the z/OS 1.10 AD system this is member PROF1.) ARPAGE 5 ;Earlier releases had some TN3270 parameters here. They should remain ;if you are using an earlier release. DATASETPREFIX TCPIP AUTOLOG 5 FTPD JOBNAME FTPD1 PORTMAP ENDAUTOLOG PORT 7 7 9 9 19 19 20 21 UDP TCP UDP TCP UDP TCP TCP TCP MISCSERV MISCSERV MISCSERV MISCSERV MISCSERV MISCSERV OMVS OMVS ; Miscellaneous Server

; FTP Server ; Portmap Server

NOAUTOLOG ; FTP Server ; FTP Server


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am



; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ;

Telnet Server SMTP Server Domain Name Server Domain Name Server OE TFTP SERVER OE WEB SERVER Portmap Server Portmap Server NCS Location Broker SNMP Agent SNMP Query Engine OE WEB Server Secure Server Remote Execution Server OE RLOGIN SERVER OE syslog server Remote Execution Server LPD Server RouteD Server NCPROUTE Server Kerberos Kerberos Kerberos Admin Server Kerberos Admin Server ; OE FTP SERVER ; OE TELNET SERVER ; OE TELNET SERVER ; OE SERVICES ; CSQ1 MQ TCP Listener ; CICS Socket ; SOAP JMX Connector port ; Cell Discovery port ; ORB port ; HTTP port ; HTTPS port ; Daemon port ; Daemon SSL port

; WAS Base Node entries 8880 TCP BBOS001 ;2809 TCP BBOS001 9080 TCP BBOS001 9443 TCP BBOS001 5655 TCP BBODMNB 5656 TCP BBODMNB ; WAS ND Node entries 8879 TCP BBODMGR 7277 TCP BBODMGR 9809 TCP BBODMGR 9090 TCP BBODMGR 9043 TCP BBODMGR 5755 TCP BBODMNC 5756 TCP BBODMNC ; WAS Federation entries 8878 TCP BBON001

; ; ; ; ; ; ; ; ; ; ; ; ;

SOAP JMX Connector port ORB port (COMMENT THIS ONE OUT) HTTP port HTTPS port Daemon port Daemon SSL port SOAP JMX Connector port Cell Discovery port ORB port HTTP port HTTPS port Daemon port Daemon SSL port

; SOAP JMX Connector port

Appendix A. z/OS 1.10 AD CD example


Draft Document for Review September 4, 2009 10:36 am


; Node Discovery port ; Node Agent's ORB port ; Base Server's ORB port ; This statement not in earlier releases



First Hop = =



zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am


Appendix B.

Linux installation examples

Linux installations, with openSUSE and Red Hat Enterprise Linux, are generally similar although the interfaces and order of actions can be different. Experienced Linux users should have no difficulty installing any of these distributions. The material in this appendix may be useful to those not so familiar with Linux installation.

B.1 SUSE 10.3 (32-bit) installation

We used openSUSE 10.3, with a DVD for installation. Installation was on a T60p ThinkPad with a 60-GB disk. We list the steps of this particular installation to illustrate a typical Linux installation process. (boot from DVD) Select F3 and set the proper screen resolution, if necessary Select: Installation Language: English <Next> License Agreement: Yes, I agree.... <Next> Installation Mode: New Installation <Next> Clock and Time Zone: (set as needed) <Next> Desktop Selection: GNOME <Next> Installation Settings: (Highlight Partitioning, Enter) Partitioning: Base partition settings on this proposal Expert Partitioner Device Size F Type Mount /dev/sda .... /dev/sda1 8.0GB F Linux Native (Ext3) / /dev/sda2 1.0GB F Linux swap swap /dev/sda3 46.8GB F Linux Native (Ext3) /z <Accept> Installation Settings: (Highlight Software, Enter) Accept the default settings in Patterns Filter: Package Groups (left-hand top of screen) add: x11 -> Terminals -> x3270 Select zzz All (scroll to bottom of left-hand panel)

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

Working in main window: remove: beagle (automatically deletes several other beagle components) add: k3b (optional, good for burning DVDs) remove: kdebase3-beagle (see the note under 32-bit openSUSE about beagle) add: telnet-server (optional, if you want an unsecure path to Linux) add: vsftpd (optional, if you want a basic Linux ftp server) add: Xerces-c (optional; suggested by some users) add: xosview (optional, a high-level graphic system monitor) <Accept> License Agreements: <Accept> Automatic Changes: <Accept> <Accept> Confirm Installation: <Install> (Installation proceeds) System reboots automatically Password for root: _______ <Next> Hostname and Domain Name: t60 <Next> Network Configuration: <Change> We set firewall startup to manual We disabled IPv6 We edited the Network Card Interface; fixed IP address ( <Next> Test Internet Connection: (we skipped this) <Next> Additional Installation Source: <No> Authorization: Local (/etc/passwd) <Next> New local user: (define a user, but not ibmsys1; do not select automatic logon) <Next> Release Notes: <Next> Hardware Configuration: <Next> <Finish>

B.1.1 openSUSE 10.3 Notes

In some cases we found that beagle tried to use 100% of the CPU for extended periods when attempting to index the files containing emulated volumes. It may be possible to bypass this problem by configuring beagle in a different way; later releases of beagle may not have this problem. Beagle was installed by default; we decided to unselect it during installation and this is reflected in our installation scripts. If you install beagle and want to remove it later, you can follow Computer Control Center YaST Software Software Management; Filter: Package Groups, select zzz All. Look through the list of packages and unselect the packages we listed in the installation script. This (and a subsequent reboot) will remove beagle from your system. We enabled inetd (Computer Control Panel YaST Network Services Network Services (inetd) (.) Enable) and then enabled telnet and ftp. In order to provide an ftp server in Linux, we needed to install vsftpd separately and then edit /etc/vsftpd.conf to set LISTEN=NO. The ftp server could then be used via inetd.

B.2 openSUSE 10.3 (64-bit) installation

The following material describes openSUSE 10.3 (64-bit) installation on a T60p ThinkPad with an NVIDIA graphics adapter, 3 GB of memory, and a 100-GB disk. (This particular T60 had a 64-bit processor.) The goal is to run the 64-bit version of zPDT. The system was not 58

zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

connected to the Internet during installation. Please note that some T61 ThinkPad users have found that openSUSE 10.3 does not support the graphics adapter in their machines, whereas openSUSE 10.2 does support it. We suggest that you do not request the earlier openSUSE installation programs to shrink an existing partition (such as Windows) to create a dual boot system. When we tried this (with openSUSE 10.2), our partition table was destroyed. We suggest the use of a separate partition management product, such as Partition Magic, if you want to create a dual boot system. (We first used BIOS to verify the internal disk drive was in AHCI mode.) Boot the DVD After the logo: You may want to use F3 to select a display resolution (One of our ThinkPad displays had NVIDIA graphics with 1920x1200 resolution, but this is not available on the F3 choices. We selected 1600x1200, which was the highest resolution available. A post-installation step corrected this problem. On another ThinkPad, without NVIDIA graphics, we accepted the default 1024x768 resolution for installation.) Select: Installation <Enter> (long pause) Language: English <Next> Media Check: (we skipped this) <Next> License Agreement: Yes.... <Next> Installation Mode: New Installation <Next> Clock and Time Zone: (As needed. We used UTC) <Next> Desktop Selection: GNOME <Next> Installation Settings: click on Partitioning Select: Base Partition Setup On This Proposal <Next> (use Delete, Create, Edit to produce something like the following:) Device Size F Type Mount /dev/sda1 7.9GB F Linux native (ext3) / /dev/sda2 1.0GB Linux swap swap /dev/sda3 84.1GB F Linux native (ext3) /z <Accept> Installation Settings: click on Software Select: Base Development (needed to upgrade NVIDIA graphics) Select: Linux Kernel Development (needed to upgrade NVIDIA) Select: C/C++ Development (needed to upgrade NVDIA, etc) Select: Details (bottom of screen) Filter: Package Groups (top left on screen) Click X11 -> Terminals -> x3270 Click zzz All (at bottom of left-hand panel) Working in main window: remove: beagle (automatically deletes several other beagle components) add: k3b (optional, good for burning DVDs) remove: kdebase3-beagle (see the note under 32-bit openSUSE about beagle) add: telnet-server (optional, if you want an unsecure path to Linux) add: vsftpd (optional, if you want a basic Linux ftp server) add: Xerces-c (optional; suggested by some users) add: xosview (optional, a high-level graphic system monitor) <Accept> License Agreements: <Accept> (several times) Automatic Change: <Continue> Installation Settings: <Accept> Confirm Installation: <Install> (Package installation takes place here. Reboots automatically.)

Appendix B. Linux installation examples


Draft Document for Review September 4, 2009 10:36 am

(Select "Boot from Hard Disk" or let it time out.) Password for root: ------- <Next> Hostname and Domain Name: ----- <Next> Network Configuration: click Network Interface (Edit this as needed. We used a fixed IP address.) Test Internet Connection: (We skipped this) <Next> User Authentication Method: Local <Next> New Local User: (add a userid here; we suggest disabling Automatic Login)<Next> Release Notes: <Next> Hardware Configuration: click Monitor resolution and set screen resolution (With the NVIDIA adapter this did not have any effect) <Next> <Finish> (remove DVD before rebooting) We logged onto the new system and noted that the screen resolution was still 1600x1200 on the ThinkPad with the NVIDIA adapter. We were unable to change the resolution with the usual Control Panel controls.

B.2.1 Driver for NVIDIA graphics adapter

The following steps are relevant only if you have an NVIDIA adapter and cannot adjust your functional screen resolution to use the full hardware resolution of the screen. This was the case for one of our T61p ThinkPad's 1920x1200 screen. A module named: (for 64-bit Linux)

was used to install the proper driver.1 This package cannot be installed while running under X windows. The following script assumes the package is on a CD titled ROM. Mount CD containing # cp /media/ROM/ /tmp # cd /tmp # chmod 700 # init 3 (leave X windows) login: root (login in character mode) # cd /tmp # ./ License: <Accept> (use Tab key) No precompiled...Download? <No> <OK> (Building kernel module) Install...OpenGL libraries: <Yes> Automatically update X configuration?: <Yes> Complete: <OK> # init 5 (The 1920x1200 resolution should be working and you can change the resolution with the Control Center functions) In one case we needed to reboot to obtain correct screen operation. (In one extreme case, not with openSUSE 10.3, we needed to reboot twice to obtain correct screen operation.)


Later versions of this driver may be found via the Web.


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

B.3 IBM Open Client 2.2 installation

The IBM Open Client is a prepackaged Linux based on Red Hat Enterprise and is available only to IBM internal users. Both 32- and 64-bit versions are available. The installation process is substantially different from that of common Linux distributions; the following notes are from a 32-bit installation, but the 64-bit version should be very similar. A summary of the installation process is as follows: 1. Obtain the latest Lifeboat CD from an IBM internal Web site. This may involve burning a CD from an iso image. 2. Think about your PC hard disk layout. If you can easily use a complete disk for Open Client, then installation is simpler. (This may be typical on a laptop system.) 3. Boot the Lifeboat CD and establish a link to the IBM intranet. (This may involve authentication through a VPN package such as the AT&T dialer.) 4. You may need to use GParted (available on the Lifeboat menu) to rework your hard disk partitions. The typical Lifeboat Linux installation process will rework your Linux partitions but leave Microsoft Windows partitions as they are. If you are creating a dual boot environment, you may want to shrink the Windows partition to make room for Linux partitions. For practical 1090 usage, we should have a minimum of about 50 GB for Linux. We did not create a dual boot environment for the Open Client, and we cannot comment on that process. We found that allowing the Open Client installation process to repartition hard disk Linux partitions was easier than trying to customize it to use our preferred disk layout. If you follow this path, you will have two Linux partitions. There will be a Linux swap partition and a single large partition for everything else. 5. We started the installation with Services Menu On Demand Services Install Wizard Network Build, selected typical installation, selected Open Client v2.2 for RHEL 5.2, selected standard install (8.0GB), and Linux partition destructive install. 6. After a few questions about keyboard and time zones, the installation started. This can take hours (depending on your network speed) and there is no visible indication of progress except for flickers of the disk activity light. 7. Eventually the installation ends and you are asked a few questions, such as a password for root. (Additional rules, above normal Linux rules, may be used for passwords and you may not be able to use your favorite Linux passwords.) When the installation process ended, we made a few adjustments. (logon as root) (reply to all the license agreements) Computer -> Control Center -> Users and Groups add group ibmsys and user ibmsys1 (as member of group ibmsys) (open terminal window) # cd / # mkdir /z # chown ibmsys1:ibmsys /z We used directory /z for all our System z emulated volumes. It is not a separate file system, as we prefer, but there are no operational changes related to this.

Appendix B. Linux installation examples


Draft Document for Review September 4, 2009 10:36 am

B.3.1 OC2 Notes

OC2 does not include the x3270 client. Instead, it provides Ericom PowerTerm for a 3270 client. A client session can be started by Computer More Applications Ericom PowerTerm Interconnect or by entering PowerTerm & on a command line. You need to set several parameters the first time you start a client: Host Name: localhost Terminal Box: select 3270 display and 3278-4-E (43x80) Port Number: 3270 (if this is what you set in your 1090 devmap) LU Name: (set to match devmap or leave blank) While using PowerTerm we clicked the following in the Options dropdown: Hide tool box Hide status bar Hide buttons Other notes about PowerTerm usage include: The PowerTerm window can be resized with the mouse and resizing causes the character size to be adjusted in discrete steps. The keyboard configuration is set through a GUI function. We could eliminate the startup and exit dialogs of PowerTerm by going to Terminal Setup Preferences and selecting AutoConnect, AutoExit PowerTerm, and deselecting Confirm Save. (To see the Preferences option, use the left/right scroll icons at the top of the Terminal Setup page; these icons may not be obvious but they are present.) When downloading (IND$FILE) the default receiving directory is .PowerTerm-config-dir in your home directory. (Notice the period as the first character of the directory name.) Important default keyboard mappings include: ­ ­ ­ ­ ­ ESC provides 3270 Clear The large PC Enter key provides 3270 New Line The right Ctrl key provides 3270 Enter The left Ctrl key provides 3270 Reset The PgUp key provides 3270 PA1

You might want to automatically select a window when the mouse is over it: Computer Control Center Windows Select Window.... We found that both USB disk drives and USB memory sticks were automatically mounted as /media/disk. It appears that xinetd is not installed, and this is needed to start an ftp server or telnet server. Neither of these is needed for typical 1090 operation, but they might be wanted when working in an isolated LAN environment. The psftp and putty packages can be used to access OC 2 through the ssh daemon. Our examples use port 3270 for aws3274 access. When accessed on the localhost (using the loopback address) there is no problem. When OC 2 TCP/IP is accessed over a LAN, port 3270 is blocked. (Most "nonstandard" ports are blocked.) The following commands should make port 3270 available for OC 2: # gedit /etc/iptables.d/filter/INPUT/54-zpdt-allow.rule -A INPUT -p udp -m state --dport 3270 --state NEW -j ACCEPT -A INPUT -p tcp -m state --dport 3270 --state NEW -j ACCEPT # /sbin/service iptables restart


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

If you have no security concerns (perhaps when connected only to a private network) you can completely disable iptables security with the command service iptables stop. We found that the Open Client sometimes did not recognize CD or DVD mounts. When this happened we used commands such as # mount /dev/cdrom /media to allow use of the CD or DVD. Important: Older versions the IBM Open Client have updates that may reset the kernel variables in /etc/sysctl.conf. If your 1090 does not start after installing Open Client updates you should check /etc/sysctl.conf and reapply our changes.

Appendix B. Linux installation examples


Draft Document for Review September 4, 2009 10:36 am


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.

IBM Redbooks

For information about ordering these publications, see "How to get Redbooks" on page 65. Note that some of the documents referenced here may be available in softcopy only. IBM System z Personal Development Tool Volume 1 Introduction and Reference, SG24-7721 IBM System z Personal Development Tool Volume 3 Additional Topics, SG24-7723 Communications Server for z/OS V1R9 TCP/IP Implementation Volume 1: Base Functions, Connectivity, and Routing, SG24-7532

Other publications

These publications are also relevant as further information sources: z/Architecture Principles of Operation, SA22-7832 System z Personal Development Tool User's Guide and Reference, G229-1101

How to get Redbooks

You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks, at this Web site:

Help from IBM

IBM Support and downloads IBM Global Services

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am



.bashrc, changes 12 /etc/profile 11 /etc/profile.local 11 /etc/sysctl.conf 11 /usr/z1090/bin 9 crypto instructions 50


d command 43 db_recovery, rpm error 48 device addresses, for AD 20 devmap 44 devmap, for AD 21 DHCP 33 DHCP client 33 disk partitions, deleting 49 disk planning 3 disk usage layout 3 dmidecode rpm 4 dual boot system 3


1090 hardware key activation 12 11S and MTSN fields 14 3270 nulls 50 3270 sessions, starting 22 3390 volumes, additional 24 4mm tape drive 45


activation, token 14 AD system, device addresses 20 AD system, installation 19 adstop command 42­43 alcckd command 39­40 aliasing, IP 47 APAR VM64385 48 Application Development System 19 ath_ or eth_ devices 34 ath0 device 34 aws3274 device manager 28­29 aws3274, Open Client 62 awsckd, number units 50 awsckmap command 39 awsin command 41 awsmount command 40 awsosa, connections 28 AWSPRT, translation table 48 awsstart 22 awsstart command 33, 40, 48 awsstat command 41 awsstop command 24, 40 awstape, format 18


e1000 device driver 47 Ericom PowerTerm 62 Ethernet adapters, multiple 48 Ethernet operation 47 Ethernet ports, PCMCIA 47 external interrupt 42


find_io command 34, 40, 52 floating point hardware 45


Gnome CD/DVD Creator application 8 GNOME window manager 8 gnome, selection 4 gunzip utility 20 GVRP, for OSA 48 gzip, compression 18


hardware key 48 HCD utility 47 HDD, changing 49 hyperthreading 45


beagle application 4 beagle, Linux utility 46 beagle, removing 58 BIOS level 50 Burning CDs and DVDs 8


IBM Open Client 2 61 ibmsys1 userid 20, 48 ibmsys1, userid 9 IBMUSER password 23 IECIOSxx member 25 ifconfig command 8, 33 inetd, SUSE 10.2 58 installation, Linux 57


CD/DVD drive access 8 commands, package 39 connectivity, 1090 27 cpu command 42

© Copyright IBM Corp. 2009. All rights reserved.


Draft Document for Review September 4, 2009 10:36 am

installation, rpm problem 48 interrupt command 42 IP traffic, filtering 46 ipcs command 8 ipl command 23, 40 IPL operation 22 ipl_dvd command 42 iptables 63 iptables, Open Client 62 iso fonts 8 istep command 42


jumbo frames 47

openSUSE 10.3 (64-bit) installation 58 openSUSE 10.3 Notes 58 operating systems, multiple 25 oprmsg command 41 ordering information 1 OSA devices 47 OSA interfaces 46 OSA QDIO, multiple 47 OSA/SF 46 OSA/SF utility function 37 OSA-Express 28 OSA-Express emulation 47 OSA-Express interface, filtering 46 OSA-Express2 offload functions 47 OSN operation 47


k3b application 8 k3b package 4 kernel mode 49 kernel.shmmax parameter 45


packet size, TCP/IP 47 password, IBMUSER 23 PATH 9 PC Card 47 PCMCIA card, Ethernet 47 PCOM 50 PCOM, 3270 emulator 6 PCOMM printing 50 pmtools rpm 4 PowerTerm 6, 62 printer output 49 PROFILE, z/OS TCP/IP 54 PSW values 43


LCS mode 28 LD_LIBRARY_PATH 9 lease extension, token 14 license agreement 10 Linux installation 4 Linux releases, new 48


media, software 18 memld command 42, 44 memory size, System z 45 MIH values 25 MIPS 46 MONITOR, z/VM 48 msgmax and msgmnb settings 12 mt command 49 MTU size 47


QDIO interface, multiple 47 QDIO mode 28 QDIO operation 36 QDIO operation, advantages 37 query command 42


ready command 42 Redbooks Web site 65 Contact us viii releases, new 15 Resource Link 13 Resource Link, activation 13 restart command 42 Resurce Link 15 RMF 50 root partition 3 root userid 49 routers 33 RPQ request 2


national language support 48 new release 15 NFS server 46 NFS server, usage 46 NOGVRP parameter 48 non-QDIO 35 non-QDIO mode 28 NVIDIA graphics adapter 60


OAT table 37 OAT, default 46 OAT, filtering 46 Open Client updates 63 openSUSE 10.3 46


screen saver 49 SCSI DLT tape drive 45 SCSI tape 49 search paths 42


zPDT: Installation and Basic Usage

Draft Document for Review September 4, 2009 10:36 am

Secure Update Utility 14 SecureUpdateUtility program 13 SELinux 6 shared memory size 45 shk-server 9 shk-server, rpm 10 shmall value 11 shmmax value 11 shutdown, z/OS and 1090 23 SIOCGIFINDEX failed 46 SNA 28 SNA operation 28, 37 sntl-sud 9 sntl-sud, rpm 10 software media 18 st command 43 start command 42 stop command 42 storestatus command 42 storestop command 42 SUSE 10.2 57 SUSE 10.3 (32-bit) installation 57 SUSE components, adding 49 swap partition 3 sys_reset command 42 sysctl command 8 System z software 17


VIPA functions 47 VLAN, usage 48 VLAN/VSWITCH in z/VM 48 VMAC support 38 VMWare 1 vsftp, selection 4 vsftpd, with openSUSE 10.3 58 vswitch support 38 VTAM commands 38


WebSphere Application Server 21 wireless usage 34 wlan_ devices 34 workspaces, gnome 8


X Software Development package 4 x3270 fonts 8 x3270 installation 6 x3270, startup 23 x3270, to z/OS TCP/IP 36 Xen 1 xinetd 62


T60p ThinkPad 57 T61p ThinkPad 58, 60 TCP/IP profile 35 TCP/IP stacks, multiple 46 TCP/IP, connectivity 29 TCPIP, starting z/OS 50 telnet session 36 telnet-server, selection 4 thin interrupts 46 TN3270E clients 6 TN3270e clients 6 token 40 TRL major node 54 TSO commands, NETSTAT 37 tun environment, setup 32 tun interface 51 tunnel connection, usage 36 tunnel environment, for OSA 31 tunnel, for OSA 31


z/OS 17 z/OS TCP/IP 28 z/OS TCP/IP profile 35 z/VM 17 z/VM installation 19 z/VSE 17 z/VSE installation 19 z1090instcheck command 12, 40, 49 z1090pick command 11 z1090ver command 40 zIIP or zAAP, performance 45


ulimit command 8, 12 ulimit commands 12 unit address, OSA 46 Universal Time 4 Unsupported Function, 3270 23 upddecode tool 4



Draft Document for Review September 4, 2009 10:36 am


zPDT: Installation and Basic Usage

zPDT: Installation and Basic Usage

zPDT: Installation and Basic Usage

zPDT: Installation and Basic Usage

zPDT: Installation and Basic Usage

(0.2"spine) 0.17"<->0.473" 90<->249 pages

(0.1"spine) 0.1"<->0.169" 53<->89 pages

zPDT: Installation and Basic Usage

(2.5" spine) 2.5"<->nnn.n" 1315<-> nnnn pages

zPDT: Installation and Basic Usage

(2.0" spine) 2.0" <-> 2.498" 1052 <-> 1314 pages

Draft Document for Review September 4, 2009 10:36 am

Back cover


System z Personal Development Tool: Volume 2

Installation and Basic Use


System z Development Tool Full z/OS usage Linux base

This IBM Redbooks publication introduces the IBM System z Personal Development Tool (zPDT), which runs on an underlying Linux system based on an Intel processor. zPDT provides a System z system on a PC capable of running current System z operating systems, including emulation of selected System z I/O devices and control units. It is intended as a development, demonstration, and learning platform and is not designed as a production system. This book, providing specific installation instructions, is the second of three volumes. The first volume describes the general concepts of zPDT and a syntax reference for zPDT commands and device managers. The third volume discusses more advanced topics that may not interest all zPDT users. The OBM order numbers for the three volumes are SG24-7721, SG24-7722, and SG24-7723. The systems discussed in these volumes are complex, with elements of Linux (for the underlying PC machine), z/Architecture (for the core zPDT elements), System z I/O functions (for emulated I/O devices), and z/OS® (providing the System z application interface), and possibly with other System z operating systems. We assume the reader is familiar with the general concepts and terminology of System z hardware and software elements and with basic PC Linux characteristics.



IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:

SG24-7722-00 ISBN


zPDT: Installation and Basic Usage

84 pages

Report File (DMCA)

Our content is added by our users. We aim to remove reported files within 1 working day. Please use this link to notify us:

Report this file as copyright or inappropriate


You might also be interested in

Implementing Microsoft Windows 2000 with SP4 on ProLiant servers
IEST RPs Development