IBM z/OS V2R2: Unix Systems Services · · 2015-12-16z/OS UNIX Tools and Solutions ... which illustrate programming techniques on various operating ... UNIX System Services. IBM

Redbooks

Front cover

IBM z/OS V2R2:UNIX System Services

Keith Winnard

Paul Robert Hering

International Technical Support Organization

IBM z/OS V2R2: UNIX System Services

December 2015

SG24-8310-00

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

First Edition (December 2015)

This edition applies to Version 2, Release 2, of IBM z/OS (5650-ZOS).

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

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

IBM Redbooks promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixAuthors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNow you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiStay connected to IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. 64-bit z/OS UNIX stacks above the bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 64-bit z/OS UNIX stacks above the bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.1 New z/OS UNIX parmlib statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.2 OMVS MODIFY and DISPLAY enhancements. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 z/OS UNIX System Services scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.1 Addressing PFS commands to zFS and TFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.2 Displaying OMVS storage information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. z/OS UNIX Shell and Utilities man pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 New z/OS UNIX man pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.1.1 Advantages of and search processing the new implementation . . . . . . . . . . . . . . . 82.1.2 Examples of the use of new man command options. . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 3. z/OS UNIX file system support in ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.1 New functions for the ISPF option 3.17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.2 Showing the new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 4. Enhancements for the System z file system . . . . . . . . . . . . . . . . . . . . . . . . 154.1 zFS 64-bit Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.1.1 zFS cache enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.1.2 Health check for zFS cache removals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1.3 Statistics Storage Information API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1.4 Running zFS within the OMVS address space . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.1.5 Specifying larger values with the 64-bit zFS support . . . . . . . . . . . . . . . . . . . . . . 194.1.6 Migration and coexistence considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.2 zFS enhanced and new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.2.1 New 8-byte counter support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.2.2 New sysplex-related APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.2.3 z/OS UNIX command zfsadm fsinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.2.4 Displaying zfsadm fsinfo examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.2.5 New zFS API ZFSCALL_FSINFO (0x40000013) . . . . . . . . . . . . . . . . . . . . . . . . . 274.2.6 REXX example that uses the new ZFSCALL_FSINFO API . . . . . . . . . . . . . . . . . 284.2.7 FSINFO zFS Modify interface command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.2.8 Removing two zFS health checks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.3 Moving zFS into the OMVS address space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.3.1 Move preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.3.2 Moving and running zFS commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 5. z/OS OpenSSH new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

© Copyright IBM Corp. 2015. All rights reserved. iii

5.1 OpenSSH upgrade to 6.4p1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.1.2 Enhanced ICSF support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.1.3 Improved SMF support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.1.4 Support for the TSO OMVS shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.1.5 Relaxing the syntax of IdentityKeyRingLabels . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.1.6 Use of OpenSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345.1.7 Eliminating ssh-rand-helper function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365.1.8 SMF records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365.1.9 Migration and coexistence considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375.1.10 OpenSSH Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

5.2 Examples for use of OpenSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385.2.1 Verifying version and showing basic debug information . . . . . . . . . . . . . . . . . . . . 385.2.2 Use of SFTP from TSO OMVS and a PuTTY session . . . . . . . . . . . . . . . . . . . . . 395.2.3 Use of ISPFSFTP utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 6. z/OS UNIX Tools and Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416.1 Utility RXISHMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

6.1.1 Starting RXISHMT in TSO/ISPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.1.2 Use of FILTER command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.1.3 Use of the FILTER command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

6.2 zFS zfsfsutl utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436.2.1 The zfsfsutl tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436.2.2 Use of the zfsfsutl utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

6.3 ISPFSFTP utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456.3.1 Use of the ISPFSFTP utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6.4 rxdowner utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Locating the web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Using the web material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Downloading and extracting the web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

iv IBM z/OS V2R2: UNIX System Services

Notices

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 grant 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 websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites 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.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

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. 2015. All rights reserved. v

Trademarks

IBM, the IBM logo, and ibm.com 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 ™), 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 http://www.ibm.com/legal/copytrade.shtml

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

BookManager®IBM®MVS™

OS/390®Redbooks®Redbooks (logo) ®

System z®z/OS®

The following terms are trademarks of other companies:

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

vi IBM z/OS V2R2: UNIX System Services

http://www.ibm.com/legal/copytrade.shtml

IBM REDBOOKS PROMOTIONS

Find and read thousands of IBM Redbooks publications

Search, bookmark, save and organize favorites

Get up-to-the-minute Redbooks news and announcements

Link to the latest Redbooks blogs and videos

DownloadNow

Get the latest version of the Redbooks Mobile App

iOS

Android

Place a Sponsorship Promotion in an IBM Redbooks publication, featuring your business or solution with a link to your web site.

Qualified IBM Business Partners may place a full page promotion in the most popular Redbooks publications. Imagine the power of being seen by users who download millions of Redbooks publications each year!

®

®

Promote your business in an IBM Redbooks publication

ibm.com/RedbooksAbout Redbooks Business Partner Programs

IBM Redbooks promotions

http://bit.ly/redbooksapp

http://bit.ly/1bvYuMM

http://bit.ly/1lCxuBG

http://ibm.co/1maZVrw

THIS PAGE INTENTIONALLY LEFT BLANK

Preface

This IBM® Redbooks® publication familiarizes you with the technical changes that were introduced into the UNIX System Services areas with IBM z/OS® V2R2.

This book is one of a series of IBM Redbooks publications that take a modular approach to providing information about the updates that are included within z/OS V2R2. This approach has the following goals:

� Provide modular content� Group the technical changes into a topic� Provide a more streamlined way of finding relevant information that is based on the topic

We hope you find this approach useful. We value your feedback.

Authors

This book was produced by a team of specialists from around the world working at the International Technical Support Organization, Poughkeepsie Center.

Keith Winnard is the z/OS Project Leader at the International Technical Support Organization, Poughkeepsie Center. He writes extensively and is keen to engage with customers to understand what they want from IBM Redbooks publications. Before joining the ITSO in 2014, Keith worked for clients and Business Partners in the UK and Europe in various technical and account management roles. He is experienced with blending and integrating new technologies into the traditional landscape of mainframes.

Paul Robert Hering is an IT Specialist at the ITS Technical Support Center, Mainz, Germany. He provides support to clients with z/OS and z/OS UNIX related questions and problems. He participated in several ITSO residencies since 1988, writing about UNIX related topics. Before supporting IBM OS/390® and z/OS, Robert worked for many years with the IBM VM operating system and its variations (VM/370, VM/HPO, VM/XA, and VM/ESA).

Thanks to the following people for their technical guidance contributions to this project:

Sue Kimmel (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Michael Cox (Advisory Programmer, UNIX Systems Services Development, Poughkeepsie Center) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Lynne Delesky (Software Engineer, Shell and Utilities, Poughkeepsie Center) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Lei Wang (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Yi Ming (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Scott Marcotte (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

© Copyright IBM Corp. 2015. All rights reserved. ix

Michelle Li (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Dennis Hewitt (IBM) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Charles T. Ware (Advisory Software Engineer, z/OS Level 2 service, Poughkeepsie Center) for providing valuable advice and guidance throughout the creation of this IBM Redbooks publication.

Thanks to the following people for their environment and residency support contributions to this project:

Bob Haimowitz (Development Support Team [DST], Poughkeepsie Center) for setting up and maintaining the systems, and providing valuable advice, guidance, and assistance throughout the creation of this IBM Redbooks publication.

Rich Conway (DST, Poughkeepsie Center) for setting up and maintaining the systems, and providing valuable advice, guidance, and assistance throughout the creation of this IBM Redbooks publication.

Peter Bertolozzi (Systems Management specialist, IBM Redbooks residency support, Poughkeepsie Center) for setting up and maintaining the environments within syslab in which residents worked.

John Gierloff (Operations, Poughkeepsie Center) for residency set up and support.

Don Brennan (DST, Poughkeepsie Center) for setting up and maintaining the systems hardware that was used in the creation of this IBM Redbooks publication.

Ella Buslovich (Graphics specialist, location) for providing guidance and specialist graphics for this IBM Redbooks publication.

Ann Lund (ITSO Administration, Poughkeepsie Center) for administrative support to enable the residency.

Cheryl Gera (ITSO Administration, Poughkeepsie Center) for managing the business operations for this IBM Redbooks publication.

Now you can become a published author, too!

Here’s an opportunity to spotlight your skills, grow your career, and become a published author—all at the same time! Join an ITSO residency project and help write a book in your area of expertise, while honing your experience by using leading-edge technologies. Your efforts help to increase product acceptance and customer satisfaction as you expand your network of technical contacts and relationships. Residencies run 2 - 6 weeks in length and you can participate in person or as a remote resident working from your home base.

Find out more about the residency program, browse the residency index, and apply online at this website:

ibm.com/redbooks/residencies.html

x IBM z/OS V2R2: UNIX System Services

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html

Comments welcome

Your comments are important to us!

We want our books to be as helpful as possible. Send us your comments about this book or other IBM Redbooks publications in one of the following ways:

� Use the online Contact us review Redbooks form found at:

ibm.com/redbooks

� Send your comments in an email to:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

Stay connected to IBM Redbooks

� Find us on Facebook:

http://www.facebook.com/IBMRedbooks

� Follow us on Twitter:

http://twitter.com/ibmredbooks

� Look for us on LinkedIn:

http://www.linkedin.com/groups?home=&gid=2130806

� Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter:

https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm

� Stay current on recent Redbooks publications with RSS Feeds:

http://www.redbooks.ibm.com/rss.html

Preface xi

http://www.facebook.com/IBMRedbooks

http://twitter.com/ibmredbooks



http://www.redbooks.ibm.com/


http://www.redbooks.ibm.com/contacts.html

http://www.redbooks.ibm.com/rss.html



xii IBM z/OS V2R2: UNIX System Services

Chapter 1. 64-bit z/OS UNIX stacks above the bar

z/OS UNIX System Services (z/OS UNIX) is the IBM UNIX implementation in the z/OS operating system.

This chapter describes the new 64-bit support for z/OS UNIX stacks above the bar in z/OS Version 2 Release 2 and includes the following topics:

� 1.1, “64-bit z/OS UNIX stacks above the bar” on page 2� 1.2, “z/OS UNIX System Services scenarios” on page 3

1

© Copyright IBM Corp. 2015. All rights reserved. 1

1.1 64-bit z/OS UNIX stacks above the bar

The increasing demand for threads resulted in the capacity approaching maximum limits of the kernel that are below the bar storage. Changes with IBM z/OS V2R2 introduced new 64-bit support; the following possibilities are available:

� Internal dynamic stacks can be moved above the bar.� The thread capacity is increased.

1.1.1 New z/OS UNIX parmlib statement

There is a new BPXPRMxx parmlib statement that specifies whether to allocate kernel stacks from above or below bar storage, as shown in Example 1-1.

Example 1-1 New BPXPRMxx parmlib statement

KERNELSTACKS(ABOVE|BELOW)

The two values have the following meaning:

� ABOVE

All kernel stacks are allocated above the bar, which increases the thread limit to a maximum of 500,000.

� BELOW

All kernel stacks are allocated below the bar, which is the default setting.

1.1.2 OMVS MODIFY and DISPLAY enhancements

There are two new interface controls or output changes that are introduced with z/OS V2R2.

MODIFY OMVS command enhancementThere is a new interface to send Physical File System (PFS) specific commands to a PFS independent of whether the PFS is within the OMVS address space or outside in a colony address space, as shown in Example 1-2.

Example 1-2 Passing a MODIFY command string to a PFS through a z/OS UNIX LFS interface

F OMVS,PFS=pfsname,command_string

The parameters feature the following meanings:

� pfsname

The name of the PFS that receives the command.

� command-string

The command string to be passed from the Logical File System (LFS) to the PFS.

Note: As you plan your systems, consider the following points:

� The value of KERNELSTACKS cannot be changed dynamically.

� Any changes in KERNELSTACKS in the BPXPRMxx member do not take effect until the next initial program load (IPL).

2 IBM z/OS V2R2: UNIX System Services

OMVS storage display output enhancementIf KERNELSTACKS(ABOVE) is specified in the BPXPRMxx parmlib member, the output of command D OMVS,STORAGE shows thread information instead of stack cell information.

1.2 z/OS UNIX System Services scenarios

The command enhancements can be used in different environment set ups.

1.2.1 Addressing PFS commands to zFS and TFS

As shown in Example 1-3, zFS and TFS feature their own address space outside OMVS.

Example 1-3 Displays showing zFS and TFS are in a colony address space

$> cn "d omvs,p" | grep TFS TFS BPXTFS TFS LOCAL A 2015/07/15 15.15.21 TFS GLOBAL SETTINGS: fsfull(99,5) ea 0 em 0$> cn "d omvs,p" | grep ZFS ZFS IOEFSCM ZFS LOCAL A 2015/07/15 15.15.20 ZFS PRM=(74,00)

zFS MODIFY commands when zFS is in a colony address spaceExample 1-4 shows how to use the two methods that are available to address MODIFY commands to zFS when zFS is running in its own address space outside OMVS because it was introduced.

Example 1-4 Running zFS modify commands directly and via the new F OMVS,PFS interface

$> cn "f zfs,query,level" IOEZ00639I zFS kernel: z/OS zFS Version 02.02.00 Service Level OA47906 - HZFS420. Created on Fri May 29 11:49:19 EDT 2015. sysplex(filesys,rwshare) interface(4) IOEZ00025I zFS kernel: MODIFY command - QUERY,LEVEL completed successfully.$> cn "f omvs,pfs=zfs,query,level" IOEZ00639I zFS kernel: z/OS zFS Version 02.02.00 Service Level OA47906 - HZFS420.

Important: This new interface is needed by a 64-bit zFS when it runs in the OMVS address space because the MODIFY ZFS commands no longer work.

Note: This difference in displays below and above the line are shown in Figure 1-7 on page 5 and Figure 1-8 on page 5.

Note: The UNIX command cn is a tool to allow IBM MVS™ system commands to be issued and to receive the output to STDOUT in your shell.

For more information, see IBM z/OS Version 2 Release 1 Technical Updates, SG24-8140-00, which is available at this website:

ftp://www.redbooks.ibm.com/redbooks/SG248140/

Chapter 1. 64-bit z/OS UNIX stacks above the bar 3


Created on Fri May 29 11:49:19 EDT 2015. sysplex(filesys,rwshare) interface(4) IOEZ00025I zFS kernel: MODIFY command - QUERY,LEVEL completed successfully.

TFS MODIFY commands when TFS is in a colony address spaceExample 1-5 shows how to use the two ways of addressing MODIFY commands to Temporary File System (TFS) when TFS is running in its own address space outside OMVS.

Example 1-5 Running TFS modify commands directly and via the new F OMVS,PFS interface

$> cn "f tfs,q" | grep "GLOBAL SETTINGS" BPXTF012I GLOBAL SETTINGS: fsfull(99,5) ea 0 em 0$> cn "f omvs,pfs=tfs,fsfull(80,5)" BPXTF012I GLOBAL SETTINGS: fsfull(80,5) ea 0 em 0$> cn "f tfs,ea 10" BPXTF012I GLOBAL SETTINGS: fsfull(80,5) ea 10 em 0$> cn "f omvs,pfs=tfs,em 5" BPXTF012I GLOBAL SETTINGS: fsfull(80,5) ea 10 em 5

TFS MODIFY commands when the TFS PFS is within OMVSExample 1-6 shows the difference when the PFS is not running in its own address space as the MODIFY interface is not available.

Example 1-6 For a TFS within OMVS MODIFY commands only work via F OMVS,PFS=

$> cat "//'SYS1.PARMLIB(BPXPRMTF)'" FILESYSTYPE TYPE(TFSO) ENTRYPOINT(BPXTFS) PARM('-fsfull(80,5) -ea 1 -em 1')$> cn "set omvs=(tf)" BPXO032I THE SET OMVS COMMAND WAS SUCCESSFUL.$> cn "d omvs,p" | grep TFSO TFSO BPXTFS TFSO -fsfull(80,5) -ea 1 -em 1 TFSO GLOBAL SETTINGS: fsfull(80,5) ea 1 em 1$> cn "f tfso,ea 0" IEE341I TFSO NOT ACTIVE$> cn "f omvs,pfs=tfso,ea 0" BPXTF012I GLOBAL SETTINGS: fsfull(80,5) ea 0 em 1

Because the MODIFY OMVS interface always works for addressing commands to zFS and TFS, the following tip is suggested.

Attention: Changing a TFS to be within OMVS is not meant as a suggestion. It is done for demonstration purposes only. We still suggest running a TFS in a colony address space. However, you can move a TFS into OMVS in addition to HFS and zFS.

Tip: If you switch to always use F OMVS,PFS=, this change is independent of the location of the PFS and helps reduce potential errors.


1.2.2 Displaying OMVS storage information

Example 1-7 and Example 1-8 shows how the output of the D OMVS,STORAGE command differs depending on the BPXPRMxx setting of KERNELSTACKS.

In Example 1-7, KERNELSTACKS is set to BELOW, which is the default and works as it did before.

Example 1-7 Displaying OMVS storage information if KERNELSTACKS is set to BELOW

$> cn "d omvs,o" | grep KERNELSTACKS KERNELSTACKS = BELOW$> cn "d omvs,storage" BPXO075I 20.44.51 DISPLAY OMVS 395 OMVS 0011 ACTIVE OMVS=(2A) KERNEL STORAGE USAGE PRIVATE STORAGE: CURRENT USAGE MAXIMUM AVAILABLE HIGH WATER REGION SIZE 59740158 363046502 59748350 1830789120 STACK CELLS: CURRENT USAGE MAXIMUM CELLS HIGH WATER 36 35453 46 PROCESS STACK CELL USAGE USER JOBNAME ASID PID PPID STATE THREADS STACKS NO PROCESSES FOUND USING 50 OR MORE SPACE SWITCHED STACK CELLS.

In Example 1-8, KERNELSTACKS is set to value ABOVE.

Example 1-8 Displaying OMVS storage information if KERNELSTACKS is set to ABOVE

$> cn "d omvs,o" | grep KERNELSTACKS KERNELSTACKS = ABOVE$> cn "d omvs,storage" BPXO075I 13.01.46 DISPLAY OMVS 919 OMVS 0011 ACTIVE OMVS=(74,2A) KERNEL STORAGE USAGE PRIVATE STORAGE: CURRENT USAGE MAXIMUM AVAILABLE HIGH WATER REGION SIZE 147451904 1815228416 163024896 1830789120 THREADS: CURRENT USAGE MAXIMUM THREADS HIGH WATER 87 500000 108 PROCESS THREAD USAGE USER JOBNAME ASID PID PPID STATE THREADS NO PROCESSES FOUND USING 50 OR MORE THREADS

Chapter 1. 64-bit z/OS UNIX stacks above the bar 5


Chapter 2. z/OS UNIX Shell and Utilities man pages

The z/OS UNIX Shell and Utilities is the complementary part in z/OS to communicate with the IBM UNIX implementation.

This chapter introduces the features and benefits of the new z/OS UNIX man pages.

2


2.1 New z/OS UNIX man pages

The z/OS UNIX man command used IBM BookManager® format for manual pages. ID does not support the BookManager format; instead, it supports the Darwin Information Typing Architecture (DITA) format for document data.

To use ID, z/OS UNIX man command was updated in z/OS V2R2 to support a new format, Single Tagged pre-Formatted Plain Text (.stfpt) for manual pages. The DITA format file can be converted to the new format .stfpt manual page.

2.1.1 Advantages of and search processing the new implementation

The new z/OS UNIX man pages enhancements provide the following key advantages:

� The manual of UNIX System Services Command is converted from DITA to .stfpt format and displayed by the man command transparently.

� The new z/OS UNIX man command does no longer support cached versions of manual pages because of security considerations.

The older man command used cached versions of manual pages in the UNIX System Services file system, even if it was a zero-byte file, which was invalid.

The man command searches MANPATH for the following files in the order listed:

� catn/entry.n in each directory in MANPATH� mann/*.stfpt in each directory in MANPATH� mann/*.book in each directory in MANPATH� mann/entry.n in each directory in MANPATH

Note: Consider the following points:

� An ID attribute assigns a unique identifier to an element so the element can be referenced.

� ID values can be generated on request or automatically for DITA elements.

� The DITA is an XML data model for authoring and, with the DITA Open Toolkit, publishing.


� The BookManager format manual is still supported, but now has low priority in comparison to the new format .stfpt manual file.

� The BookManager manual page of UNIX System Services Command bpxa5mst.book will not be delivered.


2.1.2 Examples of the use of new man command options

Example 2-1 shows that option -x can be used to see all the files that are searched. The first and last five lines are shown for reference.

Example 2-1 Use of option -x to list where the man command looks for the wanted information

$> man -x ls 2>&1 | head -l5Trying /usr/lpp/Printsrv/man/En_US/cat1/ls.1Trying /usr/lpp/Printsrv/man/En_US/man1/*.stfptTrying /usr/lpp/Printsrv/man/En_US/man1/*.bookTrying /usr/lpp/Printsrv/man/En_US/man1/ls.1Trying /usr/lpp/Printsrv/man/En_US/cat2/ls.2$> man -x ls 2>&1 >/dev/null | tail -5Trying /usr/man/C/man1/*.stfptTrying /usr/man/C/man1/*.book Trying /usr/man/C/man1/bpxa5mst.book Looking for topic "ls" in /usr/man/C/man1/bpxa5mst.book And converting to codepage 1047

Example 2-2 shows how to search for information about keywords.

Example 2-2 Use of option -k to search for information about keywords

$> man -k ownerchgrp - Change the group owner of a file or directorychown - Change the owner or group of a file or directorygetfacl - Display owner, group and ACL$> man -k groupchgrp - Change the group owner of a file or directorychown - Change the owner or group of a file or directorygetfacl - Display owner, group and ACLnewgrp - Change to a new group

Chapter 2. z/OS UNIX Shell and Utilities man pages 9


Chapter 3. z/OS UNIX file system support in ISPF

The Interactive System Productivity Facility (ISPF) product helps with program development and uses the characteristics of IBM display terminals to increase users productivity in an interactive environment.

This chapter describes the new z/OS UNIX file system support in ISPF that is introduced with IBM z/OS V2R2 and includes the following topics:

� 3.1, “New functions for the ISPF option 3.17” on page 12� 3.2, “Showing the new functions” on page 12

3


3.1 New functions for the ISPF option 3.17

In z/OS V2R2, the following file system-related functions were added to ISPF option 3.17:

� The z/OS UNIX ISPF Shell (ISHELL) file system functions were added.

� Enhanced displays for mounted file systems:

– Lists can be shown ordered by file system name or mount point name.– Lists can be expanded and collapsed to improve usability.

The enhancements have the following advantages:

� File system functions are consolidated in a single location. In older versions, the following functions were available with UNIX file systems:

– Mount Table functions in the z/OS UNIX ISPF Shell (ISHELL)– z/OS UNIX Directory List Utility (udlist) of ISPF option 3.17

� The usability for displaying mounted file systems was improved.

� There are practical usability issues when many file systems must be displayed and managed in the ISHELL mount table.

3.2 Showing the new functions

In this section, we describe some of the new functions.

Figure 3-1 shows the new File Systems menu that was added to ISPF option 3.17.

Figure 3-1 New File Systems menu in ISPF option 3.17


Figure 3-2 shows expanding and collapsing list entries for access to files systems.

Figure 3-2 Expand/contract list entries for access to files systems


� The ISHELL is still available for use. The mount table function is still used often.

� If udlist was used in parallel with the ISHELL mount table, see “Utility RXISHMT” on page 42 for more information about an ISHELL mount table only function that is used with filter functions.

Chapter 3. z/OS UNIX file system support in ISPF 13


Chapter 4. Enhancements for the System z file system

The z/OS Distributed File Service System z® File System (zFS) is a z/OS UNIX file system that is used in parallel with the hierarchical file system (HFS).

This chapter describes new support and enhancements for zFS in z/OS V2R2 and includes the following chapters:

� 4.1, “zFS 64-bit Support” on page 16� 4.2, “zFS enhanced and new functions” on page 20� 4.3, “Moving zFS into the OMVS address space” on page 29

4


4.1 zFS 64-bit Support

z/OS V2R2 zFS provides the following enhancements for storage limitations, cache structures, and CPU usage:

� 64-bit addressability

� A new log method

� Elimination of the metadata backing cache and keeping only the use of one metadata cache

� Running zFS in the OMVS address space

These enhancements result in the following benefits:

� Elimination of issues with running out of storage below the bar� Use of bigger caches and a larger trace history� Improved metadata performance, especially for parallel updates to the same v5 directory� Improved vnode operations

4.1.1 zFS cache enhancements

In z/OS V2R2, a new log caching facility is used and statistics are available in a new format.

The statistics log cache information is available via the zFS API service command ZFSCALL_STATS (0x40000007), option code 247. Consider the following points:

� Specifying Version 1 returns the old structure API_LOG_STAT data.

� Specifying Version 2 returns the new structure API_NL_STATS data.

� z/OS UNIX command zfsadm query -logcache and MVS system command MODIFY ZFS,QUERY,LOG support the new statistical data.

The following types of caches are no longer available or used:

� The Transaction cache was removed.

With improved logging method, it is no longer needed.

� The Client cache was removed.

z/OS V1R12 cannot coexist with z/OS V2R2; therefore, it is no longer needed.

Elimination of the metadata backing cacheAs 64-bit support allows zFS to obtain caches above the bar, there is no longer a need to define a metaback cache in data spaces.

Consider the following points:

� The zFS parmlib member option metaback_cache_size is used for compatibility.

� zFS internally combines meta cache and metaback cache and allocates one cache in zFS address space storage.

� It is suggested that where appropriate, remove the metaback_cache_size option from your zFS parmlib members and add its value to the meta_cache_size option.


4.1.2 Health check for zFS cache removals

There is a health check that is named ZFS_CACHE_REMOVALS to monitor zFS cache removals. Consider the following points:

� The health check determines whether zFS is running with parmlib configuration options metaback_cache_size, client_cache_size, and tran_cache_size.

� Specifying any of the options causes an exception. Therefore, we suggest that not to these options are not specified.

The following override check parameters keywords are available:

� METABACK� CLIENT� TRANS

The possible values are ABSENCE or EXISTENCE. Example 4-1 shows a sample of the parameter setting for this health checker.

Example 4-1 Sample parameter setting for the ZFS_CACHE_REMOVALS health checker

PARM('METABACK(EXISTENCE), CLIENT(EXISTENCE), TRANS(EXISTENCE)')

If active, the severity is set to low.

4.1.3 Statistics Storage Information API

In z/OS V2R2, a new Statistics Above 2G Storage Information API was introduced. It is available via zFS API service command ZFSCALL_STATS (0x40000007), opcode 255 and named STATOP_STORAGE_ABOVE.

Note: The Statistics Storage Information API STATOP_STORAGE option code 241 uses API_STOR_STATS2 for Version 2.

Chapter 4. Enhancements for the System z file system 17

The MODIFY ZFS,QUERY,STORAGE,DETAILS command provides many free lists for serviceability. An example is shown in Figure 4-1.

Figure 4-1 zFS storage information above 2 GB

4.1.4 Running zFS within the OMVS address space

In z/OS V2R2, zFS can run in the OMVS address space. Depending on the workload circumstances, this configuration might reduce CPU usage based on the shorter path lengths.

Consider the following points if you want to move zFS into the OMVS address space:

� You must remove the ASNAME keyword in the FILESYSTYPE statement for zFS in the BPXPRMxx parmlib member.

� If you still use the IOEZPRM DD statement in the zFS STC to point to the zFS configuration parameters, this DD statement should be added to the OMVS STC.

� If OMVS does not use the value that is defined in IBM-supplied Program Properties Table (PPT), ensure that the OMVS ID has the proper privileges as the zFS STC user ID did.

This issue might not be a problem because the OMVS user ID also is set up with high authority as is zFS.

� You must use the new MODIFY OMVS,PFS=ZFS command to address zFS MODIFY commands to zFS because there is no extra zFS STC active.

Note: For more information about this new command interface, see “MODIFY OMVS command enhancement” on page 2 and “Addressing PFS commands to zFS and TFS” on page 3.


4.1.5 Specifying larger values with the 64-bit zFS support

The new 64-bit support provides support for larger caches; the value ranges are listed in Table 4-1.

Table 4-1 Old and new cache range values

The larger numbers use the following suffixes for counters and storage sizes:

� For counters:

– t: Units of 1,000– m: Units of 1,000,000– b: Units of 1,000,000,000– tr: Units of 1,000,000,000,000

� For storage sizes:

– K: Units of 1,024.– M: Units of 1,048,576.– G: Units of 1,073,741,824– T: Units of 1,099,511,627,776

4.1.6 Migration and coexistence considerations

Several required actions and possibilities are described in this section that are based on the conditions and software levels that were available at the time of this writing. We suggest you research the APAR numbers for any other related information.

Toleration APAR OA46026Toleration APAR OA46026 must be installed and active on all z/OS V1R13 and z/OS V2R1 systems before z/OS V2R2 is introduced.

Consider the following points regarding the new format of the log cache statistics:

� Down level systems can recognize the new logging method and run the new log recovery and return Version 1 output, although most of the API_LOG_STAT values are 0.

� Applications that use STATOP_LOG_CACHE (opcode 247) to request Version 1 output must be updated to use Version 2 output.

� z/OS UNIX command zfsadm query -logcache and MVS system command MODIFY ZFS,QUERY,LOG return the new statistics.

Removing transaction cache and client cacheIf the zFS parmlib configuration option tran_cache_size or client_cache_size are used, the specifications are ignored.

zFS configuration options Old range New range

vnode_cache_size 32 - 500,000 1000 - 10,000,000

meta_cache_size 1 M – 1024 M 1 M – 64 G

token_cache_size 20480 – 2,621,440 20480 – 20,000,000

trace_table_size 1 M – 2048 M 1 M – 65535 M

xcf_trace_table_size 1 M – 2048 M 1 M – 65535 M


Use of Statistics APIsConsider the following points regarding the use usage of Statistics APIs:

� The use of STATOP_USER_CACHE (opcode 242) remote VM_STATS are shown as all zero for Version 1 requests. No remote VM_STATs are provided for Version 2 requests.

Version 1 requests should be updated to Version 2 to receive the new output.

� When STATOP_TRAN_CACHE (opcode 250) is used, all zeros are returned for Version 1 requests and nothing is returned for Version 2 requests.

You should use STATOP_LOG_CACHE (opcode 247) with a Version 2 request to get the new output.

� The use one of Query Config Option tran_cache_size setting (opcode 208), client_cache_size setting (231) or Set Config Option tran_cache_size (opcode 160), client_cache_size (opcode 230) APIs has no effect.

Using commandsConsider the following points regarding the use of commands:

� Commands zfsadm config or zfsadm configquery with options -tran_cache_size or -client_cache_size have no effect, as shown in Example 4-2.

Example 4-2 Output of command zfsadm configquery -client_cache_size

$> zfsadm configquery -client_cache_sizeIOEZ00317I The value for configuration option -client_cache_size is 32M.IOEZ00668I zFS Configuration option -client_cache_size is obsolete and is not used.

� Command zfsadm query -trancache now displays all zeros. We suggest removing the use of the command.

� In the MODIFY ZFS,QUERY,LFS command report transaction, cache data was removed.

4.2 zFS enhanced and new functions

The following main enhancements were added in z/OS V2R2:

� The 4-byte counters (version 1) are replaced by 8-byte counters (version 2).

� Three new sysplex-related APIs are provided.

� A new powerful FSINFO function to obtain detailed file system information was introduced.

These enhanced new functions provide the following benefits:

� Monitoring statistics over a much longer period is possible.

� Improved performance in the use of API services.

� FSINFO provides more detailed information for single and multiple file systems in a faster and more flexible manner, including sysplex-wide information.

� More detailed statistics per file system.


4.2.1 New 8-byte counter support

The following APIs that manage statistic numbers now support 8-byte counters:

� STATOP_LOCKING (opcode 240)� STATOP_STORAGE (opcode 241)� STATOP_USER_CACHE (opcode 242)� STATOP_IOCOUNTS (opcode 243)� STATOP_IOBYAGGR (opcode 244)� STATOP_IOBYDASD (opcode 245)� STATOP_KNPFS (opcode 246)� STATOP_META_CACHE (opcode 248)� STATOP_VNODE_CACHE (opcode 251)

The zfsadm query and MODIFY QUERY commands are affected by the new 8-byte counters; therefore, we suggest that you review any automation or scripts that parse or reference the output from the commands.

4.2.2 New sysplex-related APIs

The following new sysplex-related APIs are available:

� Statistics Sysplex Client Operation Info, named STATOP_CTKC (opcode 253)

This API returns information about the number of local operations that required sending a message to another system.

� Server Token management Info, named STATOP_STKM (opcode 252)

This API returns the server token manager statistics.

� Statistics Sysplex Owner Operation, named STATOP_SVI (opcode 254)

This API returns information about the number of calls that were processed on the local system as a result of a message that was sent from another system.

zfsadm query commandsThe API is used by the following new zfsadm query options:

� zfsadm query -ctkc� zfsadm query -stkm� zfsadm query -svi

zFS MODIFY commandsThe following MODIFY ZFS,QUERY commands now support 8-byte counters:

� MODIFY ZFS,QUERY,CTKC� MODIFY ZFS,QUERY,STKM� MODIFY ZFS,QUERY,SVI

New FSINFO interfaceThe new and powerful FSINFO interface provides the following enhancements:

� A zfsadm command.� A detailed file system API command that is named ZFSCALL_FSINFO (0x40000013).� A zFS MODIFY command.� Support for 8-byte counters.


4.2.3 z/OS UNIX command zfsadm fsinfo

Figure 4-2 shows syntax information for the zfsadm fsinfo command.

Figure 4-2 zfsadm fsinfo syntax

Available fsinfo optionsThe fsinfo command features the following options:

� -aggregate name

This option is used to specify the name of the aggregate. Use an asterisk (*) at the beginning, end, or both of the name as a wildcard. When wildcards are used, the default display mode is -basic. Otherwise, the default display is -owner.

� -path path_name

This option specifies the path name of a file or directory that is contained in the file system. The default information display is -owner.

� -all

This option displays information for all aggregates in the sysplex. The default information display is -owner.

� -basic

This option displays a line of basic file system information for each specified file system.

� -owner

This option displays only information that is maintained by the system that owns each specified file system.

� -full

This option displays information that is maintained by the system that owns each specified file system. It also displays information that is locally maintained by each system in the sysplex that has each specified file system locally mounted.

� -reset

This option resets zFS statistics that relate to each specified file system. This option requires system administrator authority.

Displaying information about aggregates with exceptional conditionsUse the -exceptions option to display information about aggregates with exception conditions. Table 4-2 on page 23 lists the available exceptions.

Tip: We recommend the use of FSINFO instead of List Aggregate Status (opcode 135 or 140) or List File system status (opcode 142).

zfsadm fsinfo [-aggregate name | -path path_name | -all][-basic |-owner | -full |-reset][-select criteria | -exceptions][-sort sort_name][-level][-help]


Table 4-2 Available exceptions

Specifying select criteriaUse the -select option to indicate that each specified file system that matches the criteria is displayed. Multiple criteria are separated by commas, such as -select Q,DI,L.

To use this select option, specify one or more select criteria that are listed in Table 4-3.

Table 4-3 Selection criteria

Exceptions Description

CE XCF communication failures between clients systems and owning systems

DA Marked damaged by the zFS salvager

DI Disabled for reading and writing

GD Disabled for dynamic grow

GF Failures on dynamic grow attempts

IE Disk IO errors

L Less than 1 MB of free space; forces increased XCF traffic for writing files

Q Currently quiesced

SE Returned ENOSPC errors to applications

V5D Shown for aggregates that are disabled for conversion to version 1.5

Note: This option cannot be specified with -exceptions, -reset, and -path.

Criteria Description

CE XCF communication failures between clients systems and owning systems

DA Marked damaged by the zFS salvager

DI Disabled for reading and writing

GD Disabled for dynamic grow

GF Failures on dynamic grow attempts

GR Currently being grown

IE Returned ENOSPC errors to applications

L Less than 1 MB of free space; forces increased XCF traffic for writing files

NS Mounted NORWSHARE

OV Extended (v5) directories that are using overflow pages

Q Currently quiesced

RQ Had application activity

RO Mounted read-only

RW Mounted read/write

RS Mounted RWSHARE (sysplex-aware)


Requesting sorted display dataUse the -sort sort_name option to specify that the information that is displayed is sorted as specified by the value of sort name, as listed in Table 4-4.

Table 4-4 Sort names for sorting information that is displayed

General zfsadm optionsFor other zfsadm commands, fsinfo supports the following options:

� -level

This option prints the level of the zfsadm command. Except for -help, all valid options that are specified with -level are ignored.

� -help

This option prints the online help for this command. All other valid options that are specified with this option are ignored.

SE Returned ENOSPC errors to applications

TH Having sysplex thrashing objects in them

V4 Aggregates that are version 1.4

V5 Aggregates that are version 1.5

V5D Aggregates that are disabled for conversion to version 1.5

WR Had application write activity

sort_name Function

Name Sort by file system name, in ascending order. This option is the default.

Requests Sort by the number of external requests that are made to the file system by user applications, in descending order. The most actively requested file systems are listed first.

Response Sort by response time of requests to the file system, in descending order. The slower responding file systems are listed first.

Note: This option cannot be specified with -reset.

Criteria Description


4.2.4 Displaying zfsadm fsinfo examples

An example of how to use an asterisk (*) as a wildcard is shown in Figure 4-3.

Figure 4-3 Use of an asterisk to list all file systems starting with string “hering”

An example that provides a path name is shown in Figure 4-4.

Figure 4-4 Listing base information for the zFS to which the specific path belongs

$> zfsadm fsinfo hering*HERING.TEST.DUMMY.ZFS SC74 RW,RS,Q,LHERING.TEST.ZFS SC74 RW,NS,LHERING.ZFS SC74 RW,RS

Legend: RW=Read-write,Q=Quiesced,L=Low on space,RS=Mounted RWSHARE NS=Mounted NORWSHARE$>

$> zfsadm fsinfo -path test -basicHERING.TEST.ZFS SC74 RW,NS,L

Legend: RW=Read-write, L=Low on space, NS=Mounted NORWSHARE

$>


More information about the same path and zFS file system is shown in Figure 4-5.

Figure 4-5 Listing more information about the zFS to which the specific path belongs

All zFS aggregates that are quiesced or not mounted sysplex-aware are shown in Figure 4-6.

Figure 4-6 Listing all quiesced or not sysplex-aware mounted zFS aggregates

You can also retrieve information about zFS aggregates that are not attached, as shown in Figure 4-7 on page 27.

$> zfsadm fsinfo -path testFile System Name: HERING.TEST.ZFS

*** owner information *** Owner: SC74 Converttov5: OFF,n/a Size: 36000K Free 8K Blocks: 88 Free 1K Fragments: 46 Log File Size: 112K Bitmap Size: 8K Anode Table Size: 80K File System Objects: 257 Version: 1.5 Overflow Pages: 0 Overflow HighWater: 0 Thrashing Objects: 0 Thrashing Resolution: 0 Token Revocations: 0 Revocation Wait Time: 0.000 Devno: 54 Space Monitoring: 0,0 Quiescing System: n/a Quiescing Job Name: n/a Quiescor ASID: n/a File System Grow: ON,0 Status: RW,NS,L Audit Fid: C2C8F5E2 E3F20184 0000

File System Creation Time: Sep 8 09:38:25 2006 Time of Ownership: Jul 31 11:57:53 2015 Statistics Reset Time: Jul 31 11:57:53 2015 Quiesce Time: n/a Last Grow Time: n/a

Connected Clients: n/a

Legend: RW=Read-write, L=Low on space, NS=Mounted NORWSHARE

$>

$> zfsadm fsinfo -select q,nsHERING.TEST.DUMMY.ZFS SC74 RW,RS,Q,LHERING.TEST.ZFS SC74 RW,NS,L

Legend: RW=Read-write,Q=Quiesced,L=Low on space,RS=Mounted RWSHARE NS=Mounted NORWSHARE$>


Figure 4-7 Listing information about a zFS aggregate that is not mounted and not attached

4.2.5 New zFS API ZFSCALL_FSINFO (0x40000013)

As for most zFS API calls, the pfsctl (BPX1PCT) application programming interface is used to send requests to the zFS physical file system. The simplified format for FSINFO is shown in Figure 4-8.

Figure 4-8 Format of the fsinfo pfsctl() interface call

$> rxdowner -a hering.largedir.v4RXDWN004E Aggregate HERING.LARGEDIR.V4 cannot be found.$> zfsadm fsinfo hering.largedir.v4File System Name: HERING.LARGEDIR.V4

*** owner information *** Owner: n/a Converttov5: OFF,n/a Size: 360000K Free 8K Blocks: 9152 Free 1K Fragments: 7 Log File Size: 3600K Bitmap Size: 56K Anode Table Size: 250264K File System Objects: 1000003 Version: 1.5 Overflow Pages: 0 Overflow HighWater: 0 Thrashing Objects: 0 Thrashing Resolution: 0 Token Revocations: 0 Revocation Wait Time: 0.000 Devno: 0 Space Monitoring: 0,0 Quiescing System: n/a Quiescing Job Name: n/a Quiescor ASID: n/a File System Grow: OFF,0 Status: NM Audit Fid: C2C8F5D6 C5F1000A 0000

File System Creation Time: Jun 16 00:48:25 2013 Time of Ownership: Aug 12 22:38:19 2015 Statistics Reset Time: Aug 12 22:38:19 2015 Quiesce Time: n/a Last Grow Time: n/a

Connected Clients: n/a

Legend: NM=Not mounted

$>

BPX1PCT(“ZFS “, /* File system type followed by 5 blanks */0x40000013, /* ZFSCALL_FSINFO – fsinfo operation */parmlen, /* Length of parameter buffer */parmbuf, /* Address of parameter buffer */&rv, /* return value */&rc, /* return code */&rsn) /* reason code */


FSINFO features the following subcommands:

� Query file system info (opcode 153)

This subcommand requires a minimum buffer size of 10 K for a single-aggregate query and 64 K for a multi-aggregate query.

� Reset file system statistics (opcode 154)

This command requires a minimum buffer size of 10 K.

4.2.6 REXX example that uses the new ZFSCALL_FSINFO API

A sample REXX named rxlstqsd that uses the new fsinfo API was created for demonstration and reference for this book. Consider the following points:

� Sample rxlstqsd uses the new pfsctl() command ZFSCALL_FSINFO to list all quiesced zFS aggregates in a sysplex sharing environment.

� It was created run in z/OS UNIX, TSO, and as a SYSREXX routine.

� The utility is provided in ASCII text mode as other material for this IBM Redbooks publication. When the utility is transferred from your workstation to z/OS via FTP, it is suggested that you perform the following tasks:

– Transfer the rxlstqsd.txt file in text mode (not binary) to z/OS UNIX first.

– Use the FTP quote site sbd=(1047,819) subcommand before you run the transfer and rename it to rxlstqsd.

– From UNIX, you can copy it to a TSO REXX and a SYSREXX library.

How to use the utility from different environments is shown in Figure 4-9.

Figure 4-9 Use of rxlstqsd from z/OS UNIX, TSO, and as SYSREXX routine

$> rxlstqsdHERING.TEST.PRELE.ZFSHERING.TEST.RW.ZFSHERING.TEST.ZFS$> cn "f axr,rxlstqsd" ZFSQS004I RXLSTQSD on SC74 - HERING.TEST.PRELE.ZFS HERING.TEST.RW.ZFS HERING.TEST.ZFS$> sudo zfsadm unquiesce HERING.TEST.PRELE.ZFSIOEZ00166I Aggregate HERING.TEST.PRELE.ZFS successfully unquiesced$> sudo zfsadm unquiesce HERING.TEST.RW.ZFSIOEZ00166I Aggregate HERING.TEST.RW.ZFS successfully unquiesced$> sudo zfsadm unquiesce HERING.TEST.ZFSIOEZ00166I Aggregate HERING.TEST.ZFS successfully unquiesced$> rxlstqsdZFSQS006I There are no quiesced aggregates.$> tsocmd "rxlstqsd"rxlstqsdZFSQS006I There are no quiesced aggregates.$>


4.2.7 FSINFO zFS Modify interface command

The syntax of the FSINFO zFS Modify interface command is similar to the corresponding zfsadm command. The syntax is shown in Figure 4-10.

Figure 4-10 FSINFO zFS Modify interface command

Consider the following points regarding the command:

� Multiple selection criteria are separated by blanks.� Parameters are positional.

4.2.8 Removing two zFS health checks

In z/OS V2R2, the following zFS health checks were removed because they are no longer needed:

� ZOSMIGV1R13_ZFS_FILESYS� ZOSMIGREC_ZFS_RM_MULTIFS

4.3 Moving zFS into the OMVS address space

In this section, we described how to move zFS within OMVS.

4.3.1 Move preparation

First, we ensure that we are running with KERNELSTACKS above the bar or at least after the next IPL. The option is shown in Figure 4-11.

Figure 4-11 Displaying the OMVS KERNELSTACKS setting

Note: On a down-level system, you receive a message that you must be at least on z/OS V2R2 to use the utility.

modify zFS_procname,fsinfo[,{aggrname | all}[,{full | basic | owner | reset} [,{select=criteria | exceptions}][,sort=sort_name]]]

$> cn "d omvs,o" | grep KERNELSTACKS KERNELSTACKS = ABOVE$>


It must be made clear that you have (at least) a BPXPRMxx member that is processed locally on next IPL and assures the new set up, as shown in Figure 4-12.

Figure 4-12 Showing the BPXPRMxx parmlib settings for KERNELSTACKS and zFS

4.3.2 Moving and running zFS commands

If an IPL was needed to move, check to see whether this move was successful.

Displaying zFS related information and running zFS commandsThe MODIFY ZFS command is no longer available. You must use the new MODIFY OMVS,PFS=ZFS interface, as shown in Figure 4-13.

Figure 4-13 Displaying information about zFS by using the new MODIFY interface

$> echo "The local sysclone value is:" $(sysvar SYSCLONE)The local sysclone value is: 74$> cat "//'SYS1.PARMLIB(IEASYS00)'" | grep OMVS OMVS=(&SYSCLONE.,&OMVSPARM.),$> cat "//'SYS1.PARMLIB(BPXPRM74)'" KERNELSTACKS(ABOVE)

FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM) PARM('PRM=(&SYSCLONE.,00)')$>

$> cn "d omvs,p" | grep ZFS ZFS IOEFSCM ZFS PRM=(74,00)$> cn "f zfs,query,level" IEE341I ZFS NOT ACTIVE$> cn "f omvs,pfs=zfs,query,level" IOEZ00639I zFS kernel: z/OS zFS Version 02.02.00 Service Level OA47915 - HZFS420. Created on Fri May 29 13:31:44 EDT 2015. sysplex(filesys,rwshare) interface(4) IOEZ00025I zFS kernel: MODIFY command - QUERY,LEVEL completed successfully.$>


Chapter 5. z/OS OpenSSH new functions

z/OS OpenSSH is the z/OS implementation of open source product OpenSSH.

This chapter describes the OpenSSH upgrade to 6.4p1 for IBM Ported Tools for OpenSSH V1R3 and z/OS OpenSSH V2R2 and includes the following topics:

� 5.1, “OpenSSH upgrade to 6.4p1” on page 32� 5.2, “Examples for use of OpenSSH” on page 38

5


5.1 OpenSSH upgrade to 6.4p1

IBM Ported Tools for z/OS is a non-priced program product; it is not part of the z/OS operating system.

z/OS Ported Tools OpenSSH V1R3 is delivered available now. A follow-on release z/OS OpenSSH V2R2 is scheduled for inclusion in z/OS V2R2.

5.1.1 Overview

z/OS OpenSSH was upgraded to OpenSSH 6.4p1 and includes the following benefits:

� Provides a much more current OpenSSH version

� Same versions of OpenSSL 1.0.1c and zlib 1.2.3 are used

� The ssh-rand-helper tool is no longer supported in 6.4p1

� Support for many new crypto algorithms are included, which provides compatibility with other OpenSSH or SSH implementations that prefer to use these new algorithms

� Many functional enhancements

5.1.2 Enhanced ICSF support

AES-CTR mode support was added to ICSF via APAR OA45548. It was added to work similar to g AES-CBC mode ICSF support.

The following OpenSSH algorithm names are affected:

� aes128-ctr� aes192-ctr� aes256-ctr

The change was made because z/OS OpenSSH must support ICSF acceleration of CTR mode AES ciphers. This support is important because the defaults in open source OpenSSH recently changed so that AES-CTR is preferred over AES-CBC. For these connections, ICSF acceleration previously was not available.

Note: OpenSSH V1R3 and V2R2 have the same functions.

Important: As ssh-rand-helper is no longer supported in 6.4p1, ICSF is now required.


� AES-CTR is Advanced Encryption Standard (AES) Counter mode� AES-CBC is Cipher Block Chaining� AES-CTR is preferred over AES-CBC

Note: This enhancement may provide the benefit of reducing CPU usage over software implementation when AES-CTR Ciphers are used.


5.1.3 Improved SMF support

Support was added for better SSH connection accounting and auditing.

A new triplet was added to the SFTP client transfer SMF record for the target path name. The SFTP client did not record the target path name in the past.

A new SMF 119 record was created that is written at the beginning of a successful SSH connection, just after user authentication. The SSH client and SSHD server feature their own new subtypes.

Existing Common TCPIP and SSH Common Security triplets are included.

5.1.4 Support for the TSO OMVS shell

The SSH client can be started under a TSO OMVS shell. However, entering password credentials is still not allowed so that exposures and displaying passwords is prevented.

This configuration makes diagnosing connection and handshake problems easier for many customers.

It allows verifying a working network connection, acceptance of server host keys, and a completed connection if a password is not required.

5.1.5 Relaxing the syntax of IdentityKeyRingLabels

The IBM-added option IdentityKeyRingLabel was complex to use in a shell script because literal double-quotes are required. This problem was solved with the implementation of the following changes:

� The syntax of IdentityKeyRingLabel was relaxed so that double quotes are optional when it is entered from an SSH, SFTP, or SCP command line. However, the quotes are still required when the keyword appears in the zos_ssh_config or authorized_keys files.

� The HostKeyRingLabel is similarly relaxed so that double quotes are not required when this keyword is used on an SSHD command line.

� The old syntax still works.

Note: Access to BPX.SMF is required to record the SSH client connection started record because the SSH client is not APF authorized.

Note: Passwords are not required if SSH user keys are used.

Note: Difficult multiple shell script escape sequences are no longer required.

Chapter 5. z/OS OpenSSH new functions 33

5.1.6 Use of OpenSSH

The use of OpenSSH is described in this section,.

Key Exchange algorithmsKey exchange (also known as key establishment) is any method in cryptography by which cryptographic keys are exchanged between two parties that allows the use of a cryptographic algorithm.

The following Key Exchange algorithms can now be specified via the -oKexAlgorithms option:

� Old algorithms:

– diffie-hellman-group1-sha1– diffie-hellman-group14-sha1– diffie-hellman-group-exchange-sha1– diffie-hellman-group-exchange-sha256

� New National Institute of Standards and Technology (NIST) Elliptic-curve algorithms:

– ecdh-sha2-nistp256– ecdh-sha2-nistp384– ecdh-sha2-nistp521

Key algorithmsThe following Key algorithms are supported:

� Old algorithms: ssh-rsa and ssh-dss

� New NIST Elliptic-curve DSA with SHA-2 algorithms added:

– ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, and ecdsa-sha2-nistp521,– [email protected] and [email protected],– [email protected]– [email protected]– [email protected]– [email protected] and [email protected]

� OpenSSH certificates also were added.

Cipher algorithmsIn cryptography, a cipher (or cypher) is an algorithm for performing encryption or decryption.

The following cipher algorithms are supported. The default preference order is as shown. New ciphers are highlighted in bold and ICSF support is noted by * (already supported) or ** (newly supported):

� aes128-ctr**, aes192-ctr**, aes256-ctr**, and arcfour256,arcfour128,� [email protected] and [email protected],� aes128-cbc*, 3des-cbc*, blowfish-cbc, and cast128-cbc, aes192-cbc*,� aes256-cbc*, arcfour, and [email protected]*

Note: Non-standard non-RFC names are marked with “[email protected]”.

Note: The new ciphers are called AES Gallois Counter Mode (GCM) ciphers. These ciphers function as cipher and HMAC in one.


MAC algorithmsIn cryptography, a message authentication code (MAC) is a short piece of information that is used to authenticate a message and provide integrity and authenticity assurances on the message.

A keyed-hash message authentication code (HMAC) is a specific construction for calculating a MAC that includes a cryptographic hash function with a secret cryptographic key.

The following MAC algorithms are supported. The default preference order is as shown. New MAC algorithms are highlighted in bold and ICSF support is denoted by * (already supported) or ** (newly supported).

� [email protected]* and [email protected]*� [email protected] and [email protected]� [email protected]**� [email protected]**� [email protected]*� [email protected]*� [email protected]*� hmac-md5*, and hmac-sha1*� [email protected] and [email protected]� hmac-sha2-256** and hmac-sha2-512**� hmac-ripemd160* and [email protected]*� hmac-sha1-96* and hmac-md5-96*

Dynamic port assignment for remote port forwarding You can use the ssh -R 0:host:port command for dynamic port assignment. A remote port of 0 can be specified in which case a dynamic port is assigned on the server. The client reports a message with the specific ephemeral port assigned.

More flexibility in configuration filesMatch blocks have more criteria and can include more options within the block.

Support for public key (user and host) certificatesThese certificates are not X.509 certificates. Rather, these certificates are a simpler implementation that is unique to OpenSSH. A single key (CA key) can sign (vouch for) the public keys of many users or servers. If a host or user trusts the CA public key, it implicitly accepts the keys that were signed by it.


� SHA-2 algorithms added are supported with ICSF.

� Support for the umac algorithm support was added. A message authentication code that is based on universal hashing, or UMAC, is a type of MAC that is calculated choosing a hash function from a class of hash functions according to some secret (random) process and applying it to the message.

� The [email protected] algorithms are not new algorithms. These algorithms are variants that indicate that the MAC is calculated after encryption (Encrypt-then-MAC) rather than the inverse.


Multiple user authentication methodsThe server (see AuthenticationMethods in the sshd_config file) can specify that more than one authentication method is required for a user or for all users. For example, it can be requested to need a key and to enter a password.

SFTP enhancementsThe following SFTP enhancements are available:

� Support for recursively transferring files in a directory tree via get -r and put -r� SFTP server read-only mode� SFTP df command for displaying file system attributes� Improved performance of directory listings� Support of the ls -h option - human readable file attribute units

5.1.7 Eliminating ssh-rand-helper function

z/OS OpenSSH now requires a working /dev/random UNIX device. Consider the following points:

� The ssh-rand-helper function was slow, not as secure, and often timed out.

� ICSF /dev/random support is now required to start SSH or SSHD.

� If /dev/random is not available, SSH and SSHD start fails and results in the following error message:

FOTS1949 PRNG is not seeded. Please activate the Integrated Cryptographic Service Facility (ICSF).

5.1.8 SMF records

For more information about the new functions that were implemented, see “Improved SMF support” on page 33.

New algorithms are added to the related SMF records. The SFTP client records target path name was added in subtype 97. Another triplet was added to this record that contains the target (remote) path name for a SFTP client file transfer.

The following new SMF 119 records were added. The SSH client and SSHD server feature their own new subtypes:

� Type 94 (x"5E"): Client connection started record� Type 95 (x"5F"): Server connection started record

The content of these records is identical, and a subset of other 119 SSH records.

� Standard SMF 119 header� Common 119 TCP/IP identification section� SSH common security section; this identifies which algorithms were used


� A crypto card is not required With HCR77A0.

� CSFRNG check can be skipped by defining a resource in class XFACILIT that is named CSF.CSFSERV.AUTH.CSFRNG.DISABLE.


5.1.9 Migration and coexistence considerations

Consider the following points regarding migration actions and coexistence:

� As in previous releases, protocol 1 is disabled by default.

� Different from the open source Version 6.4 of OpenSSH, SFTP is changed so that non-error messages are not printed to stdout if a batch file (-b) is run.

In effect, the -q (quiet mode) option is turned on with -b and cannot be turned off. Because this configuration affects many installations, it was changed in the z/OS port so that -b does not force -q. The -q option can be specified in addition to -b.

Therefore, this action is not a migration action; however, the behavior is not consistent with other implementations.

� Preferences for GlobalKnownHostsFile in ssh_config:

/etc/ssh/ssh_known_hosts, /etc/ssh/ssh_known_hosts2

� Preferences for IdentityFile in ssh_config:

For protocol version 2, the default is:

~/.ssh/id_rsa, ~/.ssh/id_dsa, and ~/.ssh/id_ecdsa

� Preferences for UserKnownHostsFile in ssh_config:

~/.ssh/known_hosts, ~/.ssh/known_hosts2

� Preferences for AuthorizedKeysFile in sshd_config:

.ssh/authorized_keys, .ssh/authorized_keys2

� Preferences for HostKey in sshd_config:

/etc/ssh/ssh_host_rsa_key, /etc/ssh/ssh_host_dsa_key and /etc/ssh/ssh_host_ecdsa_key

5.1.10 OpenSSH Installation

Consider the following points regarding installation:

� z/OS Ported Tools OpenSSH V1R3 is supported in z/OS 1.13 and later.

� OpenSSH V2R2 is packaged as a base element of z/OS V2R2.

� ICSF FMID HCR7780 or later is required with PTF for APAR OA45548. OpenSSH V1R3 and V2R2 do not run without ICSF started because /dev/random is now required.

Note: We do not show all the configuration file and command changes here. For more information, see OpenSSH User’s Guide SC27-6806.

Note: HCR77A0 or later supports /dev/random without a crypto card.

HCR77A1 allows for SAF checking of CSFRNG to be disabled.


Figure 5-1 shows the updated parts of OpenSSH for z/OS V1R3 and that routine ssh-rand-helper was removed.

Figure 5-1 Updated OpenSSH parts

5.2 Examples for use of OpenSSH

Basic examples for the use of OpenSSH are described in this section.

5.2.1 Verifying version and showing basic debug information

Example 5-1 shows how to verifying the version of the SSH command.

Example 5-1 Verifying the actual version of the SSH command

$> ssh -VOpenSSH_6.4p1, OpenSSL 1.0.1c 10 May 2012

In Example 5-2 on page 38, we show a simple way for getting basic debug information on running SSHD in test mode by using option -t. This options checks only the validity of the sshd_config configuration file and the sanity of the keys.

Example 5-2 Testing the sshd command

$> sudo /usr/sbin/sshd -dtdebug1: zsshSmfTestRecord: SMF is collecting type 119, subtype 96 recordsdebug1: sshd version OpenSSH_6.4, OpenSSL 1.0.1c 10 May 2012debug1: read PEM private key done: type RSAdebug1: private host key: #0 type 1 RSAdebug1: read PEM private key done: type DSAdebug1: private host key: #1 type 2 DSAdebug1: could not open key file '/etc/ssh/ssh_host_ecdsa_key': EDC5129I No suchfile or directory. (errno2=0x05620062)FOTS1438 Could not load host key: /etc/ssh/ssh_host_ecdsa_key$>

The error message is shown because no such key file was provided. This error does not mean that the server cannot start normally.

/bin/ssh/bin/scp/bin/sftp/bin/ssh-add/bin/ssh-agent/bin/ssh-keygen/bin/ssh-keyscan/usr/lib/ssh/ssh-keysignusr/lib/ssh/sftp-server/usr/sbin/sshd/usr/lib/nls/msg/C/openssh.cat/usr/man/C/man1/fotz200.book/samples/ssh_smf.hSYS1.MACLIB(FOTSMF77)


5.2.2 Use of SFTP from TSO OMVS and a PuTTY session

Two examples are described in this section. When a session is open to node WTSC70OE, the authorization is achieved by a keypair. As with WTSC74OE, no keys are available and you must enter a password, which is still not permitted from OMVS.

Example 5-3 shows how starting a session can be achieved by using OMVS.

Example 5-3 Use OMVS for starting SFTP sessions

$> echo We are logon in system $(sysvar SYSNAME).We are logon in system SC65.$> iduid=888(HERING) gid=2(SYS1) groups=1047(USSTEST)$> sftp hering@wtsc70oeConnected to wtsc70oe.sftp> pwdRemote working directory: /u/heringsftp> cd /tmpsftp> pwdRemote working directory: /SC70/tmpsftp> quit$> sftp hering@wtsc74oeFOTS3322 Passwords may not be entered from 3270 terminalsFOTS0841 Connection closed

In Example 5-4, we see the option of starting from within a PuTTY session.

Example 5-4 Using a PuTTY session for starting sftp sessions

$> sftp hering@wtsc74oehering@wtsc74oe's password: xxxxxxxxConnected to wtsc74oe.sftp> cd /tmpsftp> pwdRemote working directory: /SC74/tmpsftp> quit

5.2.3 Use of ISPFSFTP utility

There is a utility available for the use of SFTP from TSO. It also provides a useful batch interface. For more information, see 6.3, “ISPFSFTP utility” on page 45.



Chapter 6. z/OS UNIX Tools and Solutions

This chapter describes several z/OS UNIX utilities and provides examples for achieving a specific goal. The tools that are described in this chapter are available at the following ITSO website:


This chapter includes the following topics:

� 6.1, “Utility RXISHMT” on page 42� 6.2, “zFS zfsfsutl utility” on page 43� 6.3, “ISPFSFTP utility” on page 45� 6.4, “rxdowner utility” on page 47

6




6.1 Utility RXISHMT

The utility RXISHMT filters the mount table display, which is not supported in ISHELL. The tool is based on the V2R1 version of ISHELL with some extra functions to support the mount table only.

6.1.1 Starting RXISHMT in TSO/ISPF

You can run the utility by using the following command from any ISPF panel command line:

tso rxishmt

All of your file systems are listed as in the original ISHELL when the mount table display is started.

6.1.2 Use of FILTER command

The use of a new FILTER command you can reduce the list according to filter specifications regarding the owning system, mount point, and file system name. The syntax of the command is shown in Figure 6-1.

Figure 6-1 Syntax of the FILTER command

Consider the following points regarding this command:

� The reset option clears all filter settings and shows the complete list of file systems.

� The o= option filters entries that are shown according to the owning system.

� The m= option filters entries that are shown according to the file systems mount point directory.

� The option f= filters entries that are shown according to the file system name. Filter testing is done against the file system name that is changed to uppercase letters.

� In the syntax of the FILTER command, string remains for a continuous string that is part of an option value.

� Specifying an asterisk * at the beginning of a filter value means that the corresponding option value can start with an arbitrary number of characters before the string as specified.

� Specifying a trailing asterisk * means that the corresponding option value can have an arbitrary number of characters following the string as specified.

� If “filter” without options is used, you see a panel that shows the current filter options. You can modify the current settings as wanted.

� In all cases, only the specified filter is changed. The other filter settings are not changed.

� Only the first three filter specifications are used. If one of the specifications is invalid, you see that at least one filter parameter was invalid and ignored.

filter [ reset | [o=[*]string[*]] [m=[*]string[*] [f=[*]string[*] ]

Note: The panel that is displayed and used for this function is the original ISHELL that was used for filtering file entries in a directory list display. Therefore, do not use HELP on that panel.


6.1.3 Use of the FILTER command

For more information about the sample tools see the corresponding files on the ITSO disk:


The following files are available on the disc:

� rxishmt.pdf: This file describes the tool rxishmt.

� rxishmt.zip: This file contains the REXX procedure that must be included in a REXX library within the SYSPROC or SYSEXEC library chain.

If the ISHELL is supported, you also can use this tool. It also shares all the ISPF variables and panels with the ISHELL.

If you want to change the mount table display, call the ISHELL and then, call RXISHMT again.

6.2 zFS zfsfsutl utility

In z/OS V2R1, the zFS utilities IOEAGFMT and IOEAGSLV were rewritten in Metal C and for the new super tool that is named IOEFSUTL. Consider the following points:

� The utilities no longer can be used in UNIX via external links.

� The utilities run as batch utilities only.

Use SYSPRINT as the output ddname.

IOEAGFMT and IOEAGSLV switch to another ASID.

� IOEFSUTL is the strategic tool and must be used.

A sample of step JCL is shown in Example 6-1.

Example 6-1 Running utility IOEFSUTL in a batch program

//VERIFY EXEC PGM=IOEFSUTL,REGION=0M,// PARM=('salvage -aggregate HERING.TEST.ZFS -verifyonly')//SYSPRINT DD SYSOUT=*//STDOUT DD SYSOUT=*//STDERR DD SYSOUT=*//SYSOUT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//CEEDUMP DD SYSOUT=*

6.2.1 The zfsfsutl tool

The utility can work by incorporating the following modifications:

� The zfsfsutl tool allows the use of IOEFSUTL from UNIX:

– IOEFSUTL stays in its initial ASID when working.

– IOEFSUTL must be set as an authorized program by adding it to “AUTHPGM NAMES” in the IKJTSOxx parmlib member for TSO.

� The zfsfsutl tool performs the following tasks:

– Uses a temporarily named pipe in the /tmp directory that is allocated with ddname SYSPRINT to be used via Address TSO.

Chapter 6. z/OS UNIX Tools and Solutions 43

– A simple cp command is started via spawnp to read the data from the pipe and write it to STDOUT (/dev/fd1).

– IOEFSUTL command is addressed to TSO via the following TSO call command:

call *(ioefsutl)

6.2.2 Use of the zfsfsutl utility

Example 6-2 shows to two samples of how to use the zfsfsut1 utility to display help information.

Example 6-2 Displaying help information by using zfsfsutl

$> zfsfsutl -helpIOEZ00559I zFS IOEFSUTL: Initializing z/OS zFSVersion 02.01.00 Service Level OA45948 - HZFS410.Created on Fri Jan 30 15:41:22 EST 2015.Address space asid x6CIOEZ00760I No IOEZPRM DD specified. Parmlib search being used.IOEZ00229I IOEFSUTL: Commands are:apropos search by help textconverttov4 Convert aggregate to version 4converttov5 Convert aggregate to version 5format format an aggregatehelp get help on commandslevel display service levelsalvage Salvage an aggregate$> zfsfsutl salvage -helpIOEZ00559I zFS IOEFSUTL: Initializing z/OS zFSVersion 02.01.00 Service Level OA45948 - HZFS410.Created on Fri Jan 30 15:41:22 EST 2015.Address space asid x6CIOEZ00760I No IOEZPRM DD specified. Parmlib search being used.Usage: IOEFSUTL salvage -aggregate <name> [-verifyonly] [-level] [-help]$>

Example 6-3 shows a sample of verifying a zFS aggregate.

Example 6-3 Verifying a zFS aggregate

$> zfsfsutl salvage HERING.TEST.ZFS -verifyonlyIOEZ00559I zFS IOEFSUTL: Initializing z/OS zFS…IOEZ00707I Log file size 13 8K blocks, verified correctIOEZ00729I Verification of aggregate HERING.TEST.ZFS startedIOEZ00705I Formatted v4 aggregate size 2250 8K blocks, dataset size 2250 8K blocksIOEZ00707I Log file size 13 8K blocks, verified correctIOEZ00709I Bitmap size 1 8K blocks, verified correctIOEZ00782I Salvage has verified 1 of 13 pages in the anode table.IOEZ00782I Salvage has verified 2 of 13 pages in the anode table.…IOEZ00782I Salvage has verified 13 of 13 pages in the anode table.IOEZ00782I Salvage has verified 8 of 8 directories in the directory tree.IOEZ00782I Salvage has verified 2 of 2 pages in the partially-free page list.IOEZ00782I Salvage has verified 1 of 1 pages in the totally free page stack.IOEZ00722I Primary file system size 21 8K blocks, verified correctIOEZ00739I Salvage processed 10 directory pages, 333 anodes, 18 indirect blocks


and 13 anode table pages.IOEZ00730I Verification of aggregate HERING.TEST.ZFS completed, no errors found.$>

Example 6-4 shows how to create and format a non-sms zFS aggregate and perform an initial format of 6000 cylinders.

Example 6-4 Formatting a non-SMS managed zFS initially to 6000 cylinders

$> zfsadm define hering.nonsms.zfs -volumes BH5ST3 BH5ST4 BH5ST5 BH5ST6 \> -cylinders 500 500IOEZ00248I VSAM linear dataset hering.nonsms.zfs successfully created.$> tsocmd "alter 'hering.nonsms.zfs' extaddr"alter 'hering.nonsms.zfs' extaddrENTRY HERING.NONSMS.ZFS ALTERED$> zfsfsutl format hering.nonsms.zfs -size 540000 -grow 4500 \> -version5IOEZ00559I zFS IOEFSUTL: Initializing z/OS zFSVersion 02.02.00 Service Level OA47915 - HZFS420.Created on Fri May 29 13:31:44 EDT 2015.Address space asid x54IOEZ00760I No IOEZPRM DD specified. Parmlib search being used.IOEZ00004I Formatting to 8K block number 45000 for primary extent of HERING.NONSMS.ZFS.IOEZ00005I Primary extent loaded successfully for HERING.NONSMS.ZFS.IOEZ00323I Attempting to extend HERING.NONSMS.ZFS to 49500 8K blocks.IOEZ00324I Formatting to 8K block number 49500 for secondary extents of HERING.NONSM ...IOEZ00323I Attempting to extend HERING.NONSMS.ZFS to 54000 8K blocks.IOEZ00324I Formatting to 8K block number 54000 for secondary extents of HERING.NONSM ...…IOEZ00323I Attempting to extend HERING.NONSMS.ZFS to 535500 8K blocks.IOEZ00324I Formatting to 8K block number 535500 for secondary extents of HERING.NONS ...IOEZ00323I Attempting to extend HERING.NONSMS.ZFS to 540000 8K blocks.IOEZ00324I Formatting to 8K block number 540000 for secondary extents of HERING.NONS ...IOEZ00077I HFS-compatibility aggregate HERING.NONSMS.ZFS has been successfully created$>

Consider the following points regarding the formatting:

� The IOEFSUTL format command always creates zFS aggregates with unique FIDs.� One cylinder of a zFS aggregate contains 90 8 K blocks.� 4500 8 K blocks are 500 cylinders; 540000 8 K blocks are 6000 cylinders.� 6000 cylinders of a zFS aggregate contain more than 4 GB of data.

6.3 ISPFSFTP utility

ISPFSFTP is a TSO utility that is used to run SFTP sessions in an interactive mode from the ISPF foreground.

It picks up the terminal emulation code page from ISPF and the user can enter the commands as though the session is set up with code page 01047.

It also supports reaching a target node via private and public key (preferred) or a password. Password support is available via OpenSSH SSH_ASKPASS environment variable if no keys are available.

It also contains UNIX shell scripts for copying files between MVS and UNIX with or without conversion to or from ASCII.


For more information, see the corresponding files on the ITSO disk.

The following files are available on the disc:

� ispfsftp.pdf: This file describes the ispfsftptool.� ispfsftp.zip: This file contains all the files of the tool.

6.3.1 Use of the ISPFSFTP utility

This section describes some examples of the use of the ISPFSFTP utility.

Example 6-5 shows a sample of using ispfsftp when keys are used for authentication.

Example 6-5 Use of ispfsftp from ISPF by using keys

ispfsftp hering@wtsc70oeConnected to wtsc70oe. sftp>cd /tmp sftp> cd /tmp sftp>pwd sftp> pwd Remote working directory: /SC70/tmp sftp>quit sftp> quit ISFTP005I The sftp session ended normally. ***

Password support can be used, as shown in Example 6-6.

Example 6-6 Use of ispfsftp from ISPF by using its password support

ispfsftp hering@wtsc74oeConnected to wtsc74oe. sftp>cd /tmp sftp> cd /tmp sftp>pwd sftp> pwd Remote working directory: /SC74/tmp sftp>quit sftp> quit ISFTP005I The sftp session ended normally. ***


Example 6-7 shows a sample jobstep to start IBATSFTP in batch.

Example 6-7 Sample IBATSFTP JCL step for use of SFTP in batch mode

//IBATSFTP EXEC PGM=IKJEFT01,PARM=IBATSFTP//SYSEXEC DD DSNAME=HERING.UNIX.REXX.EXEC,DISP=SHR//SFTPDATA DD DATA,DLM=##ispfsftp hering@wtsc70oecd /tmp! pwd!mvs2uss "'hering.test.file'" hering.test.file y yput hering.test.file hering.test.file! rm hering.test.filequit##//SFTPENV DD DATA,DLM=##PATH=/u/hering/bin:/usr/local/bin:/bin_EDC_ADD_ERRNO2=1##//CODEPAGE DD DATA,DLM=##ISPFSFTP_CP=01141 < Terminal Emulation CP for the job and job log##//SYSTSIN DD DUMMY//SYSTSPRT DD SYSOUT=*,LRECL=136,RECFM=VB

6.4 rxdowner utility

The rxdowner tool is provided with the zfstools package. It can be used to display owner-related information about z/OS UNIX file systems and zFS aggregates.

The syntax to run the tool is shown in Figure 6-2.

Figure 6-2 Syntax of command rxdowner

The following parameters are available:

� uss_direntry

This parameter is a UNIX System Services file system directory entry.

� file_system

This parameter is the name of a mounted z/OS UNIX file system.

� zfs_aggrname

This parameter is the name of an active zFS aggregate.

rxdowner -l|-d uss_direntry | -f file_system | -a zfs_aggrname


As a result, the owner and owner-related information is displayed. Example 6-8 shows sample commands.

Example 6-8 Sample rxdowner commands

$> sudo /usr/sbin/mount -t zFS -o rwshare -f HERING.TEST.ZFS test$> rxdowner -d test

MP Directory : /u/hering/testFile System : HERING.TEST.ZFSPFS Type : ZFSLocal Sysname: SC70 - File System local-client=NUSS Owner : SC70 - File System read-only=NzFS Owner : SC70 - Aggregate read-only=N, sysplex-aware=Y

$> sudo /usr/sbin/chmount -d SC65 test$> zfsowner HERING.TEST.ZFSzFS Owner : SC70 - Aggregate read-only=N, sysplex-aware=Y$> rxdowner -d test

MP Directory : /u/hering/testFile System : HERING.TEST.ZFSPFS Type : ZFSLocal Sysname: SC70 - File System local-client=NUSS Owner : SC65 - File System read-only=NzFS Owner : SC70 - Aggregate read-only=N, sysplex-aware=Y

$>

For more information, see the corresponding files starting with string “zfstools” that are on the ITSO disk.


Appendix A. Additional material

This book refers to additional material that can be downloaded from the Internet as described in the following sections.

Locating the web material

The web material that is associated with this book is available in softcopy from the following website:

ftp://www.redbooks.ibm.com/redbooks/SG248310

You also can see the following IBM Redbooks website:

ibm.com/redbooks

At the website, select Additional materials and open the directory that corresponds with the IBM Redbooks form number SG248310.

Using the web material

The web material that accompanies this book includes the following file:

File name Descriptionrxlstqsd.zip Zipped Code Sample

Downloading and extracting the web material

Create a subdirectory (folder) on your workstation and extract the contents of the web material .zip file into this folder.

A


ftp://www.redbooks.ibm.com/redbooks/SG248310




Related publications

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

IBM Redbooks

The following IBM Redbooks publications provide more information about the z/OS V2R2 updates. Some of the publications that are referenced in this list might be available in softcopy only:

� z/OS V2R2: JES2, JES3, and SDSF, SG24-8287� z/OS V2R2: Security, SG24-8287� z/OS V2R2: Storage Management and Utilities, SG24-8289� z/OS V2R2: Availability Management, SG24-8290� z/OS V2R2: Performance, SG24-8292� z/OS V2R2: Operations, SG24-8305� z/OS V2R2: Diagnostics, SG24-8306� z/OS V2R2: Sysplex, SG24-8307� z/OS V2R2: UNIX System Services SG24-8310� z/OS V2R2: User Interfaces, SG24-8311� z/OS V2R2: ServerPac, SG24-8500

You can search for, view, download, or order these documents and other Redbooks, Redpapers, Web Docs, draft and other materials, at the following website:

ibm.com/redbooks

Other publications

The following publications also are relevant as further information sources:

� z/OS V2R2 UNIX System Services Command Reference SA23-2280� z/OS V2R2 Using REXX and z/OS UNIX System Services, SA23-2283� z/OS UNIX System Services Planning, GA32-0884-� z/OS UNIX System Services File System Interface Reference, SA23-2285� z/OS MVS System Commands, SA38-0666� z/OS MVS Initialization and Tuning Reference, SA23-1380� z/OS Distributed File Service zFS Administration, SC23-6887� z/OS Distributed File Service Messages and Codes, SC23-6885� IBM Health Checker for z/OS User's Guide, SC23-6843� z/OS V2R2 OpenSSH User's Guide, SC27-6806� z/OS Cryptographic Services ICSF Overview, SC14-7505� z/OS Cryptographic Services ICSF Administrator's Guide, SC14-7506� z/OS Cryptographic Services ICSF System Programmer's Guide, SC14-7507� z/OS Cryptographic Services ICSF Application Programmer's Guide, SC14-7508� z/OS Cryptographic Services ICSF Writing PKCS #11 Applications, SC14-7510




Online resources

The following websites also are relevant as further information sources:

� IBM Ported Tools for z/OS:

http://www.ibm.com/servers/eserver/zseries/zos/unix/ported/

� IBM Ported Tools for z/OS: OpenSSH:

http://www.ibm.com/servers/eserver/zseries/zos/unix/ported/openssh/index.html

� OpenSSH:

http://www.openssh.org/

� OpenSSL:

http://www.openssl.org

Help from IBM

IBM Support and downloads:

ibm.com/support

IBM Global Services:

ibm.com/services


http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/

http://www.ibm.com/servers/eserver/zseries/zos/unix/ported/

http://www.ibm.com/servers/eserver/zseries/zos/unix/ported/openssh/index.html

http://www-03.ibm.com/servers/eserver/zseries/zos/unix/ported/

http://www-03.ibm.com/servers/eserver/zseries/zos/unix/ported/openssh/index.html

http://www.openssh.org/

http://www.openssl.org

(0.1”spine)0.1”<

->0.169”

53<->

89 pages

ibm.com/redbooks

SG24-8310-00

ISBN 0738441015

Printed in U.S.A.

Back cover

https://www.facebook.com/IBMRedbooks

https://plus.google.com/117986870691663860381/posts

https://www.youtube.com/user/IBMRedbooks

https://twitter.com/IBMRedbooks

https://www.linkedin.com/company/2890543?goback=.fcs_GLHD_ibm+redbooks_false_*2_*2_*2_*2_*2_*2_*2_*2_*2_*2_*2_*2&trk=ncsrch_hits

http://www.weibo.com/ibmredbooks

http://www.redbooks.ibm.com/redbooks.nsf/pages/mobileapp?Open

http://www.redbooks.ibm.com

Documents

IBM z/OS V2R2: Unix Systems Services · · 2015-12-16z/OS UNIX Tools and Solutions ... which illustrate programming techniques on various operating ... UNIX System Services. IBM