ABCs of z/OS System Programming: Volume 9

An IBM Redbook Publication
IBM Redbook Form Number: SG24-6989-05
ISBN: 0738435309
ISBN: 9780738435305
Publication Date: 27-Apr-2011
Last Update Date: 12-May-2011
Find Similar Download

Related People

Paul Rogers - Author [+1] [-1]
Richard Conway - Author

Abstract

The ABCs of z/OS System Programming is an 13-volume collection that provides an introduction to the z/OS operating system and the hardware architecture. Whether you are a beginner or an experienced system programmer, the ABCs collection provides the information that you need to start your research into z/OS and related subjects. If you would like to become more familiar with z/OS in your current environment, or if you are evaluating platforms to consolidate your e-business applications, the ABCs collection will serve as a powerful technical tool.
The contents of the volumes are as follows:
Volume 1: Introduction to z/OS and storage concepts, TSO/E, ISPF, JCL, SDSF, and z/OS delivery and installation
Volume 2: z/OS implementation and daily maintenance, defining subsystems, JES2 and JES3, LPA, LNKLST, authorized libraries, SMP/E, Language Environment
Volume 3: Introduction to DFSMS, data set basics storage management hardware and software, catalogs, and DFSMStvs
Volume 4: Communication Server, TCP/IP, and VTAM
Volume 5: Base and Parallel Sysplex, System Logger, Resource Recovery Services (RRS), global resource serialization (GRS), z/OS system operations, automatic restart management (ARM), Geographically Dispersed Parallel Sysplex (GDPS)
Volume 6: Introduction to security, RACF, Digital certificates and PKI, Kerberos, cryptography and z990 integrated cryptography, zSeries firewall technologies, LDAP, and Enterprise identity mapping (EIM)
Volume 7: Printing in a z/OS environment, Infoprint Server and Infoprint Central
Volume 8: An introduction to z/OS problem diagnosis
Volume 9: z/OS UNIX System Services
Volume 10: Introduction to z/Architecture, zSeries processor design, zSeries connectivity, LPAR concepts, HCD, and HMC
Volume 11: Capacity planning, performance management, WLM, RMF, and SMF
Volume 12: WLM
Volume 13: JES3

Language

English

Table of Content

Chapter 1. Products and components
Chapter 2. UNIX System Services overview
Chapter 3. UNIX System Services pre-installation requirements
Chapter 4. UNIX System Services installation
Chapter 5. z/OS UNIX shell and utilities
Chapter 6. Security customization
Chapter 7. Managing file systems
Chapter 8. zFS file systems
Chapter 9. Overview of TCP/IP
Chapter 10. TCP/IP applications
Chapter 11. z/OS UNIX PARMLIB members
Chapter 12. Maintenance
Chapter 13. z/OS UNIX operations
Chapter 14. z/OS UNIX shell and programming tools
Chapter 15. Performance, debugging, recovery and tuning
Chapter 16. Printing services for z/OS UNIX
ibm.com/redbooks
Front cover
ABCs of z/OS System
Programming: Volume 9
Paul Rogers
Richard Conway
z/OS UNIX, TCP/IP installation
zSeries file system, z/OS
UNIX security
Shell and programming tools


International Technical Support Organization
ABCs of z/OS System Programming: Volume 9
April 2011
SG24-6989-05

© Copyright International Business Machines Corporation 2011. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Sixth Edition (April 2011)
This edition applies to version 1 release 12 modification 0 of IBM z/OS (product number 5694-A01) and to all
subsequent releases and modifications until otherwise indicated in new editions.
Note: Before using this information and the product it supports, read the information in “Notices” on
page xvii.

© Copyright IBM Corp. 2011. All rights reserved.
iii
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
The team who wrote this book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx
Now you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Stay connected to IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Chapter 1. Products and components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 z/OS UNIX System Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 z/OS UNIX System Services and z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 z/OS and z/OS UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Product and component support for z/OS UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.5 Security Server RACF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.6 Data Facility System-Managed Storage (DFSMS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.7 Transmission Control Protocol/Internet Protocol (TCP/IP) . . . . . . . . . . . . . . . . . . . . . . 12
1.8 System Modification Program Extended (SMP/E). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.9 System Management Facility (SMF). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.10 Resource Measurement Facility (RMF). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.11 Virtual Lookaside Facility (VLF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.12 Time Sharing Option/Extended (TSO/E). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.13 Workload Manager (WLM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.14 Tivoli Storage Manager (TSM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 2. z/OS UNIX overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1 z/OS UNIX and UNIX applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2 z/OS UNIX terminology overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3 HFS and zFS file system PFSes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.4 Using z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.5 z/OS UNIX System Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.6 Physical file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.7 z/OS UNIX file sharing in a sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.8 z/OS UNIX file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.9 File system data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.10 Root file system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.11 File and directory permission bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.12 MVS data sets versus file system files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.13 zFS or HFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.14 z/OS UNIX components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.15 z/OS UNIX programs (processes). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.16 Create a process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.17 z/OS UNIX processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.18 z/OS UNIX interactive interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2.19 ISPF Option 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.20 ISHELL command (ish). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.21 User’s files and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.22 OMVS shell session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.23 OMVS command shell session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

iv
ABCs of z/OS System Programming: Volume 9
2.24 ls -al command - list files in the root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.25 ISPF edit mode for a z/OS UNIX file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
2.26 ISPF edit mode for a z/OS UNIX file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.27 Specifying the z/OS UNIX path name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.28 ISPF ENQs on z/OS UNIX files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.29 Support for editing ASCII data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.30 Handling line feed characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.31 Direct login to shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.32 Telnet access to z/OS UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Chapter 3. z/OS UNIX System Services preinstallation requirements. . . . . . . . . . . . . 71
3.1 Customization of the root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.2 Installing z/OS using ServerPac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.3 Installing z/OS using CBPDO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.4 ServerPac and CBPDO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.5 z/OS UNIX System Services installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.6 z/OS UNIX security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.7 RACF definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.8 RACF OMVS segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.9 OMVS segment fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.10 UNIX security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.11 z/OS UNIX superuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.12 RACF commands and user IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.13 RACF commands to define groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
3.14 RACF commands to define users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.15 LU and LG command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.16 Define a terminal group name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.17 TSO/E support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.18 User access to TSO/E commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Chapter 4. z/OS UNIX System Services installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.1 z/OS UNIX PARMLIB - PROCLIB members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2 IEASYSxx PARMLIB member. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.3 z/OS UNIX minimum mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.4 Minimum mode: TFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.5 z/OS UNIX full-function mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.6 z/OS HFS root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.7 zFS with z/OS V1R7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.8 HFS or zFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
4.9 Set data set type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.10 Choosing zFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.11 ServerPac changes if using zFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.12 UNIX utilities: TSO/E commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.13 UNIX commands to move and copy data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.14 The pax and tar utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.15 ServerPac z/OS UNIX installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.16 Non-volatile root file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.17 Installation of other products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
4.18 z/OS UNIX System Services installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Chapter 5. z/OS UNIX shell and utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.1 The z/OS UNIX shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.2 Input, output, errors with UNIX shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.3 Accessing the z/OS UNIX shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Contents
v
5.4 Controlling session resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.5 Dynamic /dev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.6 Invoking the shell via TSO/E. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
5.7 Invoking the shell via rlogin or telnet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
5.8 rlogin and telnet access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
5.9 Customizing z/OS UNIX initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.10 Initializing z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5.11 Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.12 Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.13 The /etc/init.options file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5.14 The etc/rc file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.15 The /etc/inittab file with z/OS V1R8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.16 The _BPXK_INITTAB_RESPAWN variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.17 Rules for coding /etc/inittab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.18 Customizing the OMVS command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.19 Shell environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
5.20 Customizing your shell environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5.21 Global variables in /etc/profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.22 User-defined settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.23 Setting the time zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.24 Customizing the C89/CC compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.25 Code page tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.26 Specifying a code page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
5.27 Internationalization variables (locales) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
5.28 Setting the region size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
5.29 Setting up printers for shell users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
5.30 Installing books for OHELP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
5.31 Using the man command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
5.32 Enabling various tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
5.33 SVP for z/OS UNIX and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.34 Setup Verification Program (SVP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Chapter 6. Security customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.1 RACF OMVS segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.2 z/OS UNIX UIDs and GIDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
6.3 z/OS UNIX users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.4 BPXROOT user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.5 Superuser with appropriate authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
6.6 Commands for superusers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.7 z/OS UNIX security and RACF profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.8 z/OS UNIX security: BPX.SUPERUSER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.9 z/OS UNIX superuser granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.10 Resource names: UNIXPRIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.11 z/OS UNIX UNIXPRIV class profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
6.12 Assigning UIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
6.13 Shared UID prevention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
6.14 Automatic UID and GID assignment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
6.15 Automatic assignment requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
6.16 Automatic assignment examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
6.17 Automatic assignment with RRSF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
6.18 z/OS UNIX security: File security packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
6.19 Octal values for permission bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
6.20 Data set security versus file security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

vi
ABCs of z/OS System Programming: Volume 9
6.21 z/OS UNIX user’s security environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
6.22 Access checking flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
6.23 File authorization checking flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
6.24 POSIX standard and UNIX ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
6.25 Limitations of current permission bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
6.26 FSPs and ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
6.27 Access control list table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
6.28 File authorization check summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
6.29 Profiles in UNIXPRIV class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
6.30 Profiles in UNIXPRIV class (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
6.31 RACF RESTRICTED attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
6.32 z/OS UNIX file access checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
6.33 RESTRICTED user profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
6.34 Restricted user access checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
6.35 Access checking with ACLs (1). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
6.36 Access checking with ACLs (2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
6.37 Create ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
6.38 ACL types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
6.39 OMVS shell commands for ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
6.40 Create ACLs for a specific directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
6.41 Create an access ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
6.42 Display the access ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
6.43 Create a directory default ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
6.44 Create a file default ACL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
6.45 Creating all ACL types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
6.46 Using the ISHELL panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
6.47 Create an access ACL using ISHELL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
6.48 File attributes panel for /u/harry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
6.49 File attributes panel showing ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
6.50 Select option to create an access ACL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
6.51 Create an access ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
6.52 Add an access ACL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
6.53 Access ACL after creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
6.54 ACL inheritance: New directory/new file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
6.55 Multilevel security with z/OS V1R5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
6.56 Multilevel security (MLS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
6.57 MLS support for z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
6.58 Mandatory access control (MAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
6.59 Discretionary access control (DAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
6.60 SECLABELs and MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
6.61 Special SECLABELs and definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
6.62 SYSMULTI SECLABEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
6.63 z/OS UNIX and SECLABELs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
6.64 Understanding UMASK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
6.65 Displaying the UMASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
6.66 Default permissions and UMASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
6.67 Example of creating a new file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
6.68 Can user JOE access the file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
6.69 Can user ANN copy the file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
6.70 Setting file permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
6.71 Setting file permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
6.72 List file and directory information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
6.73 Introducing daemons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Contents
vii
6.74 z/OS UNIX daemons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
6.75 UNIX-level security for daemons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
6.76 z/OS UNIX security: BPX.DAEMON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
6.77 RACF program control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
6.78 z/OS UNIX-level security for daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
6.79 Start options for daemons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
6.80 Define daemon security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
6.81 Auditing options for z/OS UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
6.82 File-based auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
6.83 Audit z/OS UNIX events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
6.84 Chaudit command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
6.85 List audit information for files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
6.86 Auditing reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
6.87 Maintain z/OS UNIX-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
6.88 Setting up z/OS UNIX (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
6.89 Setting up z/OS UNIX (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
6.90 Setting up z/OS UNIX (3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
6.91 Setting up z/OS UNIX (4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
6.92 Setting up z/OS UNIX (5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
6.93 RACF definitions for zFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
6.94 UNIXPRIV class with z/OS V1R3 and zFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
6.95 List current user IDs with the ISHELL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
6.96 The BPXBATCH utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
6.97 The BPXBATCH job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
6.98 BPXBATCH and shell commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Chapter 7. zFS file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
7.1 zSeries File System (zFS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
7.2 zFS compatibility mode aggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
7.3 BPXPRMxx definitions for zFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
7.4 zFS colony address space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
7.5 HFS data sets and zFS data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
7.6 zFS utilities and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
7.7 zfsadm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
7.8 Allocate Linear VSAM data set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
7.9 Create the aggregate from ISHELL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
7.10 Format VSAM space - create aggregate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
7.11 Format the aggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
7.12 Ioeagfmt successful messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
7.13 Grow an aggregate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
7.14 Dynamic aggregate extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
7.15 The -grow option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
7.16 -grow option for formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
7.17 Mounting the file system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
7.18 ISHELL support for zFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
7.19 Panel of attached zFS aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
7.20 Display aggregate attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
7.21 Display attached aggregates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
7.22 List file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
7.23 zFS aggregate space commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
7.24 Command for aggregate display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
7.25 zFS threshold monitoring space usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
7.26 Dynamic configuration parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

viii
ABCs of z/OS System Programming: Volume 9
7.27 zfsadm configquery command options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
7.28 zfsadm config command options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
7.29 Defining IOEFSPRM options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
7.30 Logical PARMLIB support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
7.31 Specifying PARMLIB members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
7.32 Add a volume to a zFS aggregate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
7.33 zFS migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
7.34 HFS/zFS as generic file system type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
7.35 Migration considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
7.36 Migration tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
7.37 Migration checks file system type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
7.38 Migration tool enhancements with APAR OA18196 . . . . . . . . . . . . . . . . . . . . . . . . . 363
7.39 REXX exec - BPXWH2Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
7.40 BPXWH2Z panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
7.41 Space allocations - HFS versus zFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
7.42 Using the migration tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
7.43 BPXWH2Z panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
7.44 Using SMS if required. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
7.45 Migrate in the foreground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
7.46 Migration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
7.47 Migration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
7.48 Migration steps continued. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
7.49 Alter allocation parameters panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
7.50 APAR OA18196 - Exact data set match. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
7.51 Migrating a list of data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
7.52 Data set list displayed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
7.53 Health Checker USS_HFS_DETECTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
7.54 Health Checker USS_HFS_DETECTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
7.55 Check with RUN_ON_MOUNT=YES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
7.56 Special characters in zFS aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
7.57 BPXMTEXT shell command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Chapter 8. File sharing in a sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
8.1 Shared file systems in a sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
8.2 Sysplex environment setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
8.3 File systems in a shared sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
8.4 Multiple systems: Different versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
8.5 Update BPXPRMxx for sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
8.6 OMVS couple data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
8.7 OMVS couple data set commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
8.8 D XCF,COUPLE,TYPE=BPXMCDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
8.9 Change to the SETXCF command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
8.10 New message for command failure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
8.11 File sharing in a sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
8.12 Mounting shared sysplex file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
8.13 Accessing shared sysplex file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
8.14 Shared file system AUTOMOVE takeover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
8.15 Moving file systems in a sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
8.16 Requests to LFS to PFS to files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
8.17 Systems accessing file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
8.18 zFS sharing mode terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
8.19 Defining zFS as sysplex-unaware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
8.20 zFS File systems with APAR OA29712 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

Contents
ix
8.21 Defining zFS as sysplex-aware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
8.22 APAR OA29619 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
8.23 New zFS configuration options (OA29619). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
8.24 Admin levels in a mixed sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
8.25 Defing zFS as syplex-aware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
8.26 Using the sysplex=filesys parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
8.27 Using the sysplex=filesys parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
8.28 The sysplex_filesys_sharemode parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
8.29 sysplex_filesys_sharemode considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
8.30 sysplex_filesys_sharemode considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
8.31 zFS mixed environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
8.32 zFS cache management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
8.33 zFS sysplex-aware on a file system basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
8.34 Automatic movement of file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Chapter 9. Managing file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
9.1 Hierarchical file system (HFS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
9.2 File linking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
9.3 Hard links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
9.4 Symbolic links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
9.5 External links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
9.6 File system structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
9.7 Temporary directory space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
9.8 Temporary file system (TFS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
9.9 Colony address space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
9.10 Mounting file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
9.11 Mount and unmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
9.12 Managing user file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
9.13 User file systems: Direct mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
9.14 Mounting file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
9.15 Option 3: Mount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
9.16 Automount facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
9.17 Automount setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
9.18 Generic match on lowercase names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
9.19 Automount facility overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
9.20 Activating automount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
9.21 SETOMVS RESET=xx implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
9.22 Issue the SETOMVS command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
9.23 Updating an existing automount policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
9.24 Example of new options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
9.25 One auto.master for a sysplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
9.26 HFS to zFS automount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
9.27 HFS to zFS automount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
9.28 Automount migration considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
9.29 How to mount zFS file systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
9.30 Using direct mount commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
9.31 Mounting zFS file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
9.32 MOUNT commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
9.33 zFS file system clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
9.34 Backup file system - zFS clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
9.35 zFS clone mounted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
9.36 Using the clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
9.37 Mounting File Systems - (HFS - zFS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

x
ABCs of z/OS System Programming: Volume 9
9.38 MOUNT command options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
9.39 UNMOUNT option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
9.40 UNMOUNT option support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
9.41 UNMOUNT option support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
9.42 Mount file system panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
9.43 Set AUTOMOVE options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
9.44 AUTOMOVE system list (syslist). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
9.45 AUTOMOVE parameters for mounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
9.46 AUTOMOVE wildcard support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
9.47 AUTOMOVE wildcard examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
9.48 Stopping zFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
9.49 Restarting the PFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
9.50 Mounting file systems with SET OMVS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
9.51 Messages from shutdown of a ZFS single system . . . . . . . . . . . . . . . . . . . . . . . . . . 500
9.52 Messages for the restart of ZFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
9.53 Shutdown and recovery scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
9.54 zFS commands in a sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
9.55 zfsadm command changes for sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
9.56 zfsadm command changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
9.57 Configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
9.58 Command forwarding support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
9.59 Indirect volsers with zFS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
9.60 Using indirect volume serials with cloned zFS data sets. . . . . . . . . . . . . . . . . . . . . . 510
9.61 Define a VSAM LDS and format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
9.62 Delete the data set and IDCAMS DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
9.63 Centralized BRLM support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
9.64 Distributed BRLM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
9.65 Define BRLM option in CDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
9.66 BRLM problems in a sysplex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
9.67 z/OS V1R8 BRLM recovery of locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
9.68 File system access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
9.69 File access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
9.70 List file and directory information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
9.71 File security packet - extattr bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
9.72 Extended attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
9.73 APF-authorized attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
9.74 Activate program control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
9.75 Shared address space attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
9.76 Shared library attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
9.77 File format attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
9.78 Extended attribute command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
9.79 Sticky bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
9.80 Set the UID/GID bit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Chapter 10. Overview of TCP/IP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
10.1 Introduction to TCP/IP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
10.2 TCP/IP terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
10.3 IPv4 addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
10.4 IPv6 addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
10.5 User login to the z/OS UNIX shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
10.6 Resolver address space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
10.7 TCPDATA search order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
10.8 Create configuration files used by TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Contents
xi
10.9 Customize the TCP/IP profile data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
10.10 Customize TCPDATA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
10.11 z/OS IP search order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
10.12 z/OS IP search order (2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
10.13 Customize the TCP/IP procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
10.14 Customizing PARMLIB members for TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
10.15 PARMLIB members to customize for TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
10.16 RACF customization for TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
10.17 Customizing TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
10.18 TCP/IP shell commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Chapter 11. TCP/IP applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
11.1 Overview of z/OS UNIX data access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
11.2 Sockets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
11.3 z/OS Communications Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
11.4 z/OS UNIX sockets support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
11.5 Customizing sockets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
11.6 Logging in to the z/OS UNIX shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
11.7 Using inetd - master of daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
11.8 Customize inetd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
11.9 Customize inetd (2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
11.10 Login to a Unix system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
11.11 rlogin to z/OS UNIX services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
11.12 Activating z/OS UNIX rlogin daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
11.13 Comparing shell login methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
11.14 Define TCP/IP daemons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
11.15 The syslogd daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
11.16 The FTPD daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
11.17 z/OS IP search order for FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
11.18 z/OS IP search order for /etc/services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
11.19 Start the TCP/IP daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
11.20 Message integration support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
11.21 Message routing to z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
11.22 syslogd command options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
11.23 syslogd defined instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
11.24 syslogd configuration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
11.25 Start procedure for syslogd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
11.26 syslogd availability considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Chapter 12. z/OS UNIX PARMLIB members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
12.1 BPXPRMxx PARMLIB member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
12.2 BPXPRMFS PARMLIB member. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
12.3 BPXPRMxx control keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
12.4 BPXPRMxx PARMLIB member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
12.5 Controlling the number of processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
12.6 Resource limits for processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
12.7 MAXFILEPROC statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
12.8 Setting file descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
12.9 Setting file descriptor for a single user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
12.10 Display BPXPRMxx limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
12.11 Memory mapped files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
12.12 Controlling thread resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
12.13 Creating a process using fork(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625

xii
ABCs of z/OS System Programming: Volume 9
12.14 Values for forked child process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
12.15 Starting a program with exec() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
12.16 Values passed for exec() program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
12.17 z/OS UNIX processes get STEPLIBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
12.18 Locating programs for z/OS UNIX processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
12.19 Shared pages for the fork() function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
12.20 Spawn function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
12.21 Interprocess communication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
12.22 Address Space Memory Map z/OS V1R5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
12.23 Control IPC resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
12.24 Kernel support for IBM 5.0 JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
12.25 Interprocess communication signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
12.26 Pipes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
12.27 Other BPXPRMxx keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
12.28 More BPXPRMxx parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
12.29 FILESYSTYPE statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
12.30 FILESYSTYPE and NETWORK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
12.31 ROOT and MOUNT statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
12.32 Examples of MKDIR in BPXPRMxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
12.33 Allocating SWA above the line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
12.34 z/OS UNIX Web site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Chapter 13. Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
13.1 Example of SMP/E SMPMCS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
13.2 Active root file system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
13.3 Inactive root file system (clone). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
13.4 /SERVICE directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
13.5 Sample SMP/E DDDEFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
13.6 Prepare for SMP/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
13.7 SMP/E APPLY process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
13.8 Supporting multiple service levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
13.9 Supporting multiple service levels (2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
13.10 ISHELL display of root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
13.11 The chroot command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
13.12 Testing a root file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
13.13 Testing the updated root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
13.14 Dynamic service activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
13.15 Dynamic service activation commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
13.16 Using the new service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
13.17 Deactivate service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
13.18 Display service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Chapter 14. z/OS UNIX operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
14.1 Commands to monitor z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
14.2 Display summary of z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
14.3 Display z/OS UNIX options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
14.4 Display BPXPRMxx limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
14.5 Display address space information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
14.6 Display process information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
14.7 Display the kernel address space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
14.8 z/OS V1R7 command options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
14.9 Mount error messages displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
14.10 Mount failure messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

Contents
xiii
14.11 Stopping BPXAS address spaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
14.12 LFS soft shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
14.13 z/OS V1R8 file system shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
14.14 Options with the D OMVS,F command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
14.15 Options with the D OMVS,F command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
14.16 New command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
14.17 New command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
14.18 New command examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
14.19 z/OS UNIX shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
14.20 Recommended shutdown procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
14.21 Application registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
14.22 Display application registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
14.23 F OMVS,SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
14.24 Blocking processes completion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
14.25 Shutdown processing completion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
14.26 Shutdown for permanent processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
14.27 Shutdown processing final cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
14.28 F OMVS,RESTART. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
14.29 Alternate sysplex root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
14.30 Defining an alternate root and mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
14.31 BPXPRMxx parmlib member - ALTROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
14.32 Display information about processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
14.33 Stop a process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
14.34 Superkill function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
14.35 Superkill example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
14.36 Changing OMVS parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
14.37 Manage interprocess communication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
14.38 System problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
14.39 z/OS UNIX abends and messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
14.40 USS errors and codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
14.41 CTIBPX00 and CTCBPXxx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
14.42 Tracing z/OS UNIX events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
14.43 Debugging a z/OS UNIX problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
14.44 IPCS OMVSDATA reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Chapter 15. z/OS UNIX shell and programming tools . . . . . . . . . . . . . . . . . . . . . . . . . 733
15.1 Language Environment run-time library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
15.2 Using pre-LE run-time libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
15.3 Overview of c89/cc/c++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
15.4 Customization of /etc/profile for c89/cc/c++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
15.5 Compile, link-edit, and run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
15.6 Customization of Java for z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
15.7 Java virtual machine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
15.8 Management of software and the make utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
15.9 The dbx debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
15.10 The dbx debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
15.11 Introduction to shells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
15.12 REXX, CLISTs, and shell scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
15.13 Shell script syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
15.14 BPXBATCH enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
15.15 BPXBATCH implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
15.16 BPXBATCH summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
15.17 TSO/E ALLOCATE command for STDPARM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760

xiv
ABCs of z/OS System Programming: Volume 9
15.18 STDERR and STDOUT as MVS data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
15.19 BPXBATCH sample job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
15.20 Child process created for MVS data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
15.21 BPXBATCH utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Chapter 16. Performance, debugging, recovery, and tuning . . . . . . . . . . . . . . . . . . . 767
16.1 z/OS UNIX performance overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
16.2 WLM in goal mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
16.3 Defining service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
16.4 Workload Manager service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
16.5 Subsystem type panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
16.6 WLM work qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
16.7 OMVS work qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
16.8 Defining classification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
16.9 Classification rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
16.10 Classification rules for STC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
16.11 Virtual lookaside facility (VLF). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
16.12 VLF for z/OS UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
16.13 COFVLFxx updates for z/OS UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
16.14 AIM Stage 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
16.15 Further tuning tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
16.16 zFS performance tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
16.17 zFS cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
16.18 zFS cache locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
16.19 Metadata backing cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
16.20 Performance APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
16.21 Performance monitoring APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.22 zfsadm query command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
16.23 The IOEZADM utility from TSO for commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
16.24 Directory cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
16.25 Directory caching display tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.26 File system monitoring tool (FSMON). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.27 The zfsadm query -iobyaggr command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.28 SMF recording. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.29 SMF 92 subtype 14 enhancement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
16.30 RMF reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.31 RMF Monitor III support for zFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
16.32 zFS access to file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
16.33 RMF Overview Report Selection Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.34 zFS Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
16.35 zFS Summary I/O details by type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.36 User and vnode cache detail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
16.37 DFSMSdss dump and restore for zFS file systems. . . . . . . . . . . . . . . . . . . . . . . . . 813
16.38 UNQUIESCE command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.39 zFS recovery support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
16.40 zFS aggregate corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
16.41 Debugging data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
16.42 zFS hang detection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.43 zFS hang detection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
16.44 z/OS UNIX Internet information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825

Contents
xv
Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
How to get IBM Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

xvi
ABCs of z/OS System Programming: Volume 9

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

xviii
ABCs of z/OS System Programming: Volume 9
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:
AIX®
BookManager®
C/370™
C/MVS™
CICS®
DB2®
Domino®
GDPS®
Geographically Dispersed Parallel
Sysplex™
IBM®
IMS™
Language Environment®
Lotus®
NetView®
Open Class®
OS/390®
Parallel Sysplex®
ProductPac®
RACF®
Redbooks®
Redbooks (logo) ®
S/390®
SystemPac®
Tivoli®
VTAM®
WebSphere®
z/Architecture®
z/OS®
zSeries®
The following terms are trademarks of other companies:
PostScript, and Portable Document Format (PDF) are either registered trademarks or trademarks of Adobe
Systems Incorporated in the United States, other countries, or both.
Novell, the Novell logo, and the N logo are registered trademarks of Novell, Inc. in the United States and other
countries.
ABAP, SAP R/3, SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in
several other countries.
Java, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other
countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.

© Copyright IBM Corp. 2011. All rights reserved.
xix
Preface
The ABCs of z/OS® System Programming is a 13-volume collection that provides an
introduction to the z/OS operating system and the hardware architecture. Whether you are a
beginner or an experienced system programmer, the ABCs collection provides the
information that you need to start your research into z/OS and related subjects. If you would
like to become more familiar with z/OS in your current environment, or if you are evaluating
platforms to consolidate your e-business applications, the ABCs collection will serve as a
powerful technical tool.
This IBM® Redbooks® publication describes z/OS UNIX System Services (z/OS UNIX). It will
help you install, tailor, configure, and use the z/OS Version 1 Release 6 version of z/OS UNIX.
Topics covered in this volume are the products and components used with z/OS UNIX:
An overview of z/OS UNIX
z/OS UNIX pre-installation requirements
Step-by-step installation of z/OS UNIX System Services using the ServerPac
The z/OS UNIX shell and utilities
z/OS UNIX security customization using RACF®
The Hierarchical File System (HFS) and zFS
TCP/IP overview and customization; TCP/IP applications
z/OS UNIX PARMLIB member definitions
How to perform maintenance
Using z/OS UNIX operator commands
The z/OS UNIX shell and programming tools
Using the workload manager; performance and tuning considerations
z/OS UNIX printing options
The contents of the volumes are as follows:
Volume 1: Introduction to z/OS and storage concepts, TSO/E, ISPF, JCL, SDSF, and z/OS
delivery and installation
Volume 2: z/OS implementation and daily maintenance, defining subsystems, JES2 and
JES3, LPA, LNKLST, authorized libraries, SMP/E, Language Environment®
Volume 3: Introduction to DFSMS, data set basics storage management hardware and
software, catalogs, and DFSMStvs
Volume 4: Communication Server, TCP/IP, and VTAM®
Volume 5: Base and Parallel Sysplex®, System Logger, Resource Recovery Services (RRS),
global resource serialization (GRS), z/OS system operations, automatic restart management
(ARM), Geographically Dispersed Parallel Sysplex™ (GDPS®)
Volume 6: Introduction to security, RACF, Digital certificates and PKI, Kerberos, cryptography
and z990 integrated cryptography, zSeries® firewall technologies, LDAP, and Enterprise
identity mapping (EIM)

xx
ABCs of z/OS System Programming: Volume 9
Volume 7: Printing in a z/OS environment, Infoprint Server and Infoprint Central
Volume 8: An introduction to z/OS problem diagnosis
Volume 9: z/OS UNIX System Services
Volume 10: Introduction to z/Architecture®, zSeries processor design, zSeries connectivity,
LPAR concepts, HCD, and HMC
Volume 11: Capacity planning, performance management, WLM, RMF, and SMF
Volume 12: WLM
Volume 13: JES3
The team who wrote this book
This book was produced by a team of specialists from around the world working at the
International Technical Support Organization, Poughkeepsie Center.
Paul Rogers is a Consulting IT Specialist at the International Technical Support
Organization, Poughkeepsie Center. He writes extensively and teaches IBM classes
worldwide on various aspects of z/OS, z/OS UNIX, JES3, and Infoprint Server. Before joining
the ITSO 20 years ago, Paul worked in the IBM Installation Support Center (ISC) in
Greenford, England for seven years providing OS/390® and JES support for IBM EMEA and
also in the Washington Systems Center for three years. He has worked for IBM for 40 years.
Richard Conway is a systems programmer at the International Technical Support
Organization, Poughkeepsie Center. He has extensive knowledge of z/OS UNIX System
Services and all of the products installed at the ITSO. He has worked in the ITSO for the last
15 years.
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 using leading-edge technologies. Your efforts
will help to increase product acceptance and customer satisfaction, as you expand your
network of technical contacts and relationships. Residencies run from two to six weeks in
length, and you can participate either 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:
ibm.com/redbooks/residencies.html

Preface
xxi
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:
redbooks@us.ibm.com
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, 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

xxii
ABCs of z/OS System Programming: Volume 9

© Copyright IBM Corp. 2011. All rights reserved.
1
Chapter 1.
Products and components
This chapter provides a brief overview of z/OS UNIX System Services (z/OS UNIX) and
related components. z/OS UNIX interacts with the following elements and features of z/OS:
BCP (WLM and SMF components)
XPG4-compliant shell application
Data Facility Storage Management Subsystem (DFSMS) (HFS is a component of DFSMS)
Security Server RACF
Resource Measurement Facility (RMF)
Time Sharing Option/Extended (TSO/E)
z/OS Communications Server (TCP/IP)
System Modification Program Extended (SMP/E)
Virtual Lookaside Facility (VLF)
Tivoli® Storage Manager (TSM)
z/OS Distributed File Service zSeries File System (zFS)
1

2
ABCs of z/OS System Programming: Volume 9
1.1 z/OS UNIX System Services
Figure 1-1 Implementation of z/OS UNIX System Services
z/OS UNIX System Services
The name OpenEdition was changed to OS/390 UNIX System Services beginning with
OS/390 Release 5. UNIX Services can then be abbreviated OS/390 UNIX.
When OS/390 was renamed to z/OS, the new abbreviation for z/OS UNIX System Services
became z/OS UNIX.
z/OS UNIX was originally implemented in MVS/ESA 4.3 as OpenEdition and supported the
POSIX standards (1003.1, 1003.1a, 1003.1c, and 1003.2) with approximately 300 functions.
In MVS/ESA 5.2.2 many additional functions were added to meet the XPG4 requirements.
In MVS/ESA 5.2.2 more than 1100 functions were included in the OpenEdition
implementation. This incorporated the full X/Open Portability Guide issue 4 (XPG4) and over
90% of the single UNIX specification as defined in XPG4.2. The remaining functions were
added afterwards, and OpenEdition became branded as a UNIX system.
The XPG4.2 support includes all commands and utilities, most of the additional C services
defined in the standard and curses, which was included in specification 1170 but not in the
XPG4.2 itself. Curses is the UNIX multi-color, multi-language screen control package which
comes from the Novell SVID Edition 3 package.
Since OS/390 V2R2, the following items were added: STREAMS, X/Open Transport Interface
(XTI), XPG4.2 regular expressions, XPG4.2 context switching, and XPG4.2 behavior specific
to sockets.
A new name for OpenEdition
Abbreviation - OS/390 UNIX
Beginning with OS/390 Release 5
New abbreviation - z/OS UNIX
Beginning with z/OS Version 1 Release 1
POSIX
XPG4
XPG4.2
MVS/ESA 4.3 and 5.1
MVS/ESA 5.2.2 and OS/390 R1
OS/390 R2
Full
UNIX
Branding
1993 1996

Chapter 1. Products and components
3
XPG4 branding
XPG4 branding means that products use a common set of UNIX APIs. X/Open branding is
the procedure by which a vendor certifies that its product complies with one or more of
X/Open's vendor-independent product standards and OpenEdition in MVS 4.2.2 received
base branding. In 1996, OpenEdition in MVS/ESA SP Version 5 Release 2 received a full
XPG4.2 branding. Branding allows applications that are developed on one branded flavor of
UNIX to run unchanged on other branded UNIX systems.
It is called branding because it allows the right to use the X/Open Trade Mark. OpenEdition in
MVS was shown to comply with the specifications, and therefore IBM is entitled to use the
X/Open Trade Mark in relation to OpenEdition having X/Open-compliant features. That right
continues for as long as z/OS UNIX remains compliant and registered in the Directory of
X/Open Branded Products.
POSIX standards
The work on Portability Operating Systems Interface (POSIX) started as an effort to
standardize UNIX and was performed by a workgroup under the Institute of Electrical and
Electronics Engineers (IEEE). What they defined was an application programming interface
which could be applied not only to UNIX systems but to other operating systems like MVS.
POSIX is not a product. It is an evolving family of standards describing a wide spectrum of
operating system components ranging from C language and shell interfaces to system
administration.
The POSIX standard is sponsored by the International Organization for Standardization (ISO)
and is incorporated into X/Open Portability Guides (XPG). Each element of the standard is
defined by a 1003.* number.
POSIX defines the
interfaces
and not the solution or implementation. In this way POSIX can
be supported by any operating system. Implementation of POSIX can be different in areas
such as performance, availability, and recoverability. All POSIX-compliant systems aren't the
same, although they all support basically the same interface.
The support for open systems in z/OS is based on the POSIX standard.

4
ABCs of z/OS System Programming: Volume 9
1.2 z/OS UNIX System Services and z/OS
Figure 1-2 z/OS UNIX System Services implementation in z/OS
z/OS UNIX and z/OS
The z/OS UNIX System Services element of z/OS is a UNIX operating environment,
implemented in z/OS. It is also known as z/OS UNIX. The z/OS support enables two open
systems interfaces on the z/OS operating system:
An application program interface (API)
With the application programming interface, programs can run in any environment,
including in batch jobs, in jobs submitted by TSO/E users, and in most other started tasks,
or in any other MVS application task environment. The programs can request only MVS
services, z/OS UNIX, or both MVS and z/OS UNIX.
The application interface is composed of C interfaces. Some of the C interfaces are
managed within the C Run-Time Library (RTL), and others access kernel interfaces to
perform authorized system functions on behalf of an unauthorized caller.
An interactive shell interface
z/OS UNIX responds to requests from programs and the shells. z/OS UNIX has two shells,
the z/OS shell and the tcsh shell. They are collectively called the z/OS UNIX shells. The
interactive shell interface is an execution environment analogous to TSO/E, with a
programming language of shell commands analogous to the Restructured eXtended
eXecutor (REXX) Language. The shell work consists of:
– Programs run by shell users
– Shell commands and scripts run by shell users
– Shell commands and scripts run as batch jobs
z/OS UNIX System Services is an element of z/OS
A UNIX operating environment implemented within
the z/OS operating system
The z/OS support enables two open systems
interfaces on the z/OS operating system:
An application program interface (API)
An interactive shell interface
z/OS UNIX System Services provides:
XPG4 UNIX 1995 conformance
Assembler callable services
TSO/E commands to manage the file system
ISPF shell environment

Chapter 1. Products and components
5
z/OS UNIX System Services
z/OS UNIX System Services as a component of z/OS provides:
XPG4 UNIX 1995 conformance
Application programmers create UNIX-compliant application programs by designing,
coding, and testing the programs on their workstations using XPG4 UNIX-conforming
systems.
Assembler callable services
As an interface between the z/OS operating system and the functions specified in the
Single UNIX Specification and earlier standards, z/OS UNIX System Services (z/OS
UNIX) provides access to assembler callable services (syscalls). The z/OS UNIX callable
services have a standard set of syntax and linkage requirements, as well as parameter
specification details necessary for successful invocation.
TSO/E commands to manage the file system
You can use TSO/E commands to do certain tasks with the file system. Some of these are
tasks that UNIX users traditionally perform while in the UNIX shell.
ISPF shell environment
The ISPF shell is a panel interface that you can use instead of TSO/E commands or shell
commands to perform certain tasks. For example, you can use the ISPF shell to display all
mounted file systems or their attributes, such as total blocks.

6
ABCs of z/OS System Programming: Volume 9
1.3 z/OS and z/OS UNIX
Figure 1-3 z/OS UNIX and the z/OS operating system
z/OS UNIX services
The z/OS support for z/OS UNIX System Services (z/OS UNIX) enables two open system
interfaces on z/OS:
An application program interface (API)
An interactive z/OS shell interface
API interface
With the APIs, programs can run in any environment—in batch jobs, in jobs submitted by
TSO/E users, and in most other started tasks—or in any other MVS application task
environment. The programs can request:
Only MVS services
Only z/OS UNIX
Both MVS and z/OS UNIX
Shell interface
The shell interface is an execution environment analogous to TSO/E, with a programming
language of shell commands analogous to the Restructured eXtended eXecutor (REXX)
language. The shell work consists of:
Programs run by shell users
Shell commands and scripts run by shell users
Shell commands and scripts run as batch jobs
Callable
Services
z/OS
Operating
System
(MVS)
API
API
Interface
Interface
(C functions)
(C functions)
Shell
Shell
Interface
Interface
(commands)
(commands)
Kernel
Kernel
z/OS
z/OS
UNIX
UNIX
Services
Services
VLF
VLF
WLM
WLM
SMF
SMF
LE

Chapter 1. Products and components
7
To run a shell command or utility, or any user-provided application program written in C or
C++, you need the C/C++ run-time library provided with the Language Environment (LE).
With the z/OS UNIX System Services Application Services, users can:
Request services from the system through shell commands. Shell commands are like
TSO/E commands.
Write shell scripts to run tasks. Shell scripts are analogous to REXX EXECs.
Run programs interactively (in the foreground) or in the background.
Application programmers are likely to do the following when creating UNIX-compliant
application programs:
Design, code, and test programs on their workstations using XPG4 UNIX-conforming
systems.
Send the source modules from the workstation to z/OS.
Copy the source modules from the MVS data sets to HFS files.
Compile the source modules and link-edit them into executable programs.
Test the application programs.
Use the application programs.
A z/OS UNIX program can be run interactively from a shell in the foreground or background,
run as a z/OS batch job, or called from another program. The following types of applications
exist in a z/OS system with z/OS UNIX:
Strictly conforming XPG4 UNIX-conforming applications
Applications using only kernel services
Applications using both kernel and z/OS services
Applications using only z/OS services
A z/OS program submitted through the job stream or as a job from a TSO/E session can
request kernel services through the following:
C/C++ functions
Shell commands, after invoking the shell
Callable services
Products and components
Following are the z/OS components used by z/OS UNIX:
WLM The workload manager (WLM) transaction initiators provide address spaces when
programs issue the fork(), spawn(), C function, or z/OS callable services.
VLF RACF allows caching of UID and GID information in the Virtual Lookaside Facility
(VLF). Add the following VLF options to the COFVLFxx member of SYS1.PARMLIB to
enable caching since it will improve the performance of z/OS UNIX. VLF is still valid if
you have not converted to AIM stage 3.
SMF System management facilities (SMF) collects data for accounting. SMF job and
job-step accounting records identify processes by user, process, group, and session
identifiers. Fields in these records also provide information about resources used by
the process. SMF File System records describe file system events such as file open,
file close, file system mount, unmount, quiesce, and unquiesce.

CLASS NAME(IRRUMAP)
EMAJ(UMAP)
CLASS NAME(IRRGMAP)
EMAJ(GMAP)

8
ABCs of z/OS System Programming: Volume 9
1.4 Product and component support for z/OS UNIX
Figure 1-4 Products and components used by z/OS UNIX
z/OS UNIX and z/OS facilities
The z/OS UNIX facility allows users to write and invoke shell scripts and utilities, and to use
the shell programming language. z/OS UNIX also interacts with the following elements and
features of z/OS to interact directly with the operating system:
BCP (WLM, VLF, and SMF components)
z/OS XL C/C++ compiler, to compile programs
In V1R6 and earlier, the compiler was known as the z/OS C/C++ compiler.
C is a programming language designed for a wide variety of programming purposes
including system-level code. To compile C code using the c89 command, or to compile
C/C++ code using cxx, you need the z/OS XL C/C++ compiler that is available with z/OS.
Language Environment, to execute the shell and utilities or any other XPG4-compliant
shell application
Language Environment establishes a common language development and execution
environment for application programmers on z/OS. To run a shell command or utility, or
any user-provided application program written in C or C++, you need the C/C++ run-time
library provided with Language Environment.
Data Facility Storage Management Subsystem (DFSMS) (HFS is a component of
DFSMS.)
Security Server for z/OS (RACF is a component of the Security Server.)

RACF DFSMS
TSM
RMF
SMF
WLM
VLF SMP/E
TCP/IP
TSO/E
UNIX
System
Services
z/OS XL C/C++ compiler Language Environment
ISPF
zFS
NFSSDSF

Chapter 1. Products and components
9
Resource Measurement Facility (RMF)
System Display and Search Facility (SDSF)
System Display and Search Facility (SDSF) is an IBM-licensed program that provides a
menu-driven full-screen interface that is used to obtain detailed information about jobs and
resources in a system. Shell users can enter TSO/E sessions and use SDSF to monitor
z/OS activities. For example, they can:
– Monitor printing
– Monitor and control a batch job
– Monitor and control forked address spaces
– Find out which users are logged on to TSO/E sessions
Time Sharing Option Extensions (TSO/E)
You can also enter the shell environment by logging on to a TSO/E session and entering
the OMVS command. Other TSO/E commands logically mount and unmount file systems,
create directories in a file system, and copy files to and from MVS data sets. Users can
switch from the shell to their TSO/E session, enter commands or do editing, and switch
back to the shell.
Communications Server (TCP/IP)
TCP/IP enables users to enter the shell environment by using rlogin or telnet from a
workstation in the TCP/IP network. User-written socket applications can use TCP/IP
services as a communication vehicle. Both client and server socket applications can use
the socket interface to communicate over the Internet (AF_INET and AF_INET6) and
between other socket applications by using local sockets (AF_UNIX). An assembler
interface is also provided for those applications that do not use the C/C++ run-time library.
ISPF, to use the dialogs for OEDIT, or ISPF/PDF for the ISPF shell
Users of ISPF can use the ISPF shell environment to create, edit, browse, and perform
other functions for files and directories in the z/OS UNIX file system.
Network File System (NFS)
Network File System (NFS) enables users to access files on other systems in a network.
z/OS Distributed File Service zSeries File System (zFS)
zSeries File System (zFS) is a UNIX file system that can be used, along with HFS.

10
ABCs of z/OS System Programming: Volume 9
1.5 Security Server RACF
Figure 1-5 Security Server RACF
Security Server RACF
RACF or an equivalent security product like ACF2 can manage system and data set security
by verifying a user and checking that the user can access a resource.
The security products also take care of who is allowed to issue special commands, define
new users, and change access permissions.
The permission to access directories and files is verified by the security product. RACF is
responsible for the OMVS segment which allows the user to access UNIX Services.
In other words, if someone wants to access z/OS UNIX file systems, whether a directory or a
file, RACF checks whether this user is allowed to have access in the z/OS UNIX environment.
The security checking to access specific directories or files is then handled by z/OS UNIX
System Services itself.
RACF is not able to change permission bits or owner statements in the z/OS UNIX
environment. RACF only checks whether a user or program is allowed to access z/OS UNIX
services.
The RACF user profile definition was expanded with a segment called OMVS for z/OS UNIX
support. All users and programs that need access to z/OS UNIX must have a RACF user
profile defined with an OMVS segment which has, as a minimum, a UID specified. A user
without a UID cannot access z/OS UNIX.
z/OS UNIX requires a security product
z/OS UNIX users defined in RACF database
OMVS segment of user profile
UIDs and GIDs
Userid
Default
Group
Connect Groups
TSO
DFP
OMVS
UID Home
Program
15
/u/smith
/bin/sh
SMITH
PROG1
PROG1
PROG2
...
...

Chapter 1. Products and components
11
1.6 Data Facility System-Managed Storage (DFSMS)
Figure 1-6 DFSMS and z/OS UNIX
DFSMS and z/OS UNIX
During the first quarter of 2000, PTFs removed the requirement that HFS data sets reside on
SMS-managed volumes. HFS data sets still need to be cataloged in the master or user
catalog in order for the HFS data sets to be mounted by z/OS UNIX. However, you do not
need to catalog the HFS data sets if you plan on dumping them using DFSMSdss.
Data Facility System-Managed Storage (DFSMS) manages the z/OS UNIX data sets used for
processing. These hierarchical file system (HFS) data sets make up a file hierarchy.
DFSMS manages the hierarchical file system data sets that contain the file systems. To use
kernel services in full-function mode, SMS must be active.
Note: Although the file system does not have to be SMS-managed, this is still highly
suggested. Multivolume file systems are only supported as SMS-managed (that is, you
cannot have multivolume non-SMS-managed data sets). As a user adds files and extends
existing files, the data set increases in size to a maximum of 123 extents if secondary
extents are specified in the allocation.
S
M
S
File system data sets can reside on SMS-managed
volumes
SMS-managed is optional
Although the file system does not have to be
SMS-managed, it is still highly suggested
Multivolume file systems are only supported as
SMS-managed
HFS
HFS
and
and
zFS
zFS

12
ABCs of z/OS System Programming: Volume 9
1.7 Transmission Control Protocol/Internet Protocol (TCP/IP)
Figure 1-7 TCP/IP and z/OS UNIX
TCP/IP and z/OS UNIX
Transmission Control Protocol/Internet Protocol is a peer-to-peer network protocol. It is
officially named the TCP/IP Internet Protocol Suite and is referred to as TCP/IP (after the
name of its two main standard protocols). TCP/IP is a set of industry standard protocols and
applications.
The TCP/IP Internet Protocol Suite is a layered set of protocols that allow cooperating
computers to share resources across a network or networks. The physical networks can be of
different types.
UNIX shell users
One way to enter the shell environment is by using rlogin or telnet from a workstation in the
TCP/IP network. ssh is a client program for logging into a z/OS shell. It is a more secure
alternative to rlogin.
User-written socket applications
User-written socket applications can use TCP/IP as a communication vehicle. Both client and
server socket applications can use the socket interface to communicate over the Internet
(AF_INET) and between other socket applications by using local sockets (AF_UNIX). An
assembler interface is also provided for those applications that do not use the C/C++ run-time
library.
User-written socket applications
z/OS UNIX
Requires full function mode
IEASYSxx parmlib member
OMVS=nn
TCP/IP
Enter UNIX shell
rlogin - telnet - ssh

Chapter 1. Products and components
13
Running in full function mode
The OMVS= parameter in the IEASYSxx parmlib member specifies the BPXPRMxx member
or members that determine the configuration of the kernel service. Minimum mode provides
the minimum requirements for kernel services; you will not be able to use the shell or TCP/IP
in this mode. If you do not specify OMVS= in the IEASYSxx parmlib member, or if you specify
OMVS=DEFAULT, then kernel services start up in a minimum configuration mode with all
BPXPRMxx parmlib options taking their default values when the system is IPLed. This mode
is for installations that do not plan to use the kernel services.

14
ABCs of z/OS System Programming: Volume 9
1.8 System Modification Program Extended (SMP/E)
Figure 1-8 SMP/E and z/OS UNIX
SMP/E and z/OS UNIX
SMP/E is a basic tool for installing and maintaining software in MVS systems and
subsystems. It controls these changes by:
Selecting the proper levels of elements to be installed from a large number of potential
changes.
Calling system utility programs to install the changes.
Keeping records of the installed changes (in the CSI).
SMP/E is an integral part of the installation, service, and maintenance processes for CBIPOs,
CBPDOs, ProductPacs, ServicePacs, and selective follow-on service for CustomPacs. In
addition, SMP/E can be used to install and service any software that is packed in SMP/E
system modification (SYSMOD) format.
SMP/E can be run either using batch jobs or using dialogs under Interactive System
Productivity Facility/Program Development Facility (ISPF/PDF).
Two types of dialogs are provided by SMP/E:
CBIPO dialogs for installing and redistributing Custom-Built Installation Process Offering
(CBIPO) packages.
SMP/E dialogs help you interactively query the SMP/E database, as well as create and
submit jobs to process SMP/E commands.
SMP/E
SMP/E
PTFs
Software Installation
Maintenance
Install service into the HFS
CSI
CSI
Modules
Modules
New
Software
HFS

Chapter 1. Products and components
15
1.9 System Management Facility (SMF)
Figure 1-9 SMF and z/OS UNIX
SMF recording
System Management Facility (SMF), which is a component of the BCP element, collects data
for accounting. SMF job and job-step accounting records identify processes by user, process,
group, and session identifiers. Fields in these records also provide information on resources
used by the process. SMF file system records describe file system events such as file open,
file close, and file system mount, unmount, quiesce, and unquiesce.
You can use SMF to report on activity from a user application, to report activity on a job and
jobstep basis, and to report activity of mounted file systems and files.
SMF job and job-step accounting records identify z/OS UNIX processes by:
User (UID)
Process (z/OS address space)
Group (GID)
Session identifiers
File system activity by process
Fork, spawn address spaces
Kernel activity
Activity on mounted file systems
SMF

16
ABCs of z/OS System Programming: Volume 9
1.10 Resource Measurement Facility (RMF)
Figure 1-10 RMF and z/OS UNIX
RMF and z/OS UNIX
Resource Measurement Facility (RMF) collects data used to describe z/OS UNIX
performance. RMF reports support an address space type of OMVS for address spaces
created by fork or spawn callable services and support two swap reason codes.
RMF monitors the use of resources in an OMVS Kernel Activity report.
The software products supporting system programmers and operators in managing their
systems heavily influence the complexity of their jobs, and their ability to keep systems at a
high level of availability.
RMF collects data used to describe z/OS UNIX performance. RMF reports support an
address space type of OMVS for address spaces created by fork or spawn callable services.
When an installation specifies an OMVS subsystem type in the workload manager service
policy, RMF shows the activity of forked address spaces separately in the RMF Workload
Activity report.
© Copyright IBM Corp. 2009. All rights reserved.
Resource Measurement Facility (RMF)
RMF
DATA
Performance
Analysis
and
Problem
Determination
Monitor III
UNIX performance
Fork, spawn A/S
Kernel activity
zFS caching and I/O

Chapter 1. Products and components
17
1.11 Virtual Lookaside Facility (VLF)
Figure 1-11 VLF and z/OS UNIX
VLF and z/OS UNIX
You can assign a z/OS UNIX user identifier (UID) to a RACF user by specifying a UID value in
the OMVS segment of the RACF user profile. When assigning a UID to a user, make sure that
the user is connected to at least one group that has an assigned GID. This group should be
either the user's default group or one that the user specifies during logon or on the batch job.
A user with a UID and a current connect group with a GID can use z/OS UNIX functions and
access z/OS UNIX files based on the assigned UID and GID values. If a UID and a GID are
not available as described, the user cannot use z/OS UNIX functions.
VLF
The Virtual Lookaside Facility is a set of easy-to-use high-performance services that provide
an alternate fast path method for making frequently used named data objects available to
many users. It will reduce I/O operations for frequently accessed programs that are provided
now in central or expanded storage.
Whether you are developing a new application or modifying an existing one, the kind of
application that can use VLF effectively is an application that frequently retrieves a repetitive
set of data from DASD on behalf of many end users.
COFVLFxx PARMLIB member
Caching UIDs and GIDs improves performance for commands such as ls -l, which must
convert UID numbers to user IDs and GID numbers to RACF group names. RACF allows you
Improve performance
Cache UIDs and GIDs
AIM stage 3
VLF
Address
Space
SYS1.PARMLIB
RACF
RACF Data Base
RACF
Profiles
COFVLFxx
Virtual
Lookaside
Facility
(VLF)

18
ABCs of z/OS System Programming: Volume 9
to cache UID and GID information in VLF. Add the following VLF options to the COFVLFxx
member of SYS1.PARMLIB to enable the caching:
For details about the VLF classes, see z/OS Security Server RACF System Programmer's
Guide, SA22-7681.
AIM stage 3
In stage 3, RACF locates application identities, such as UIDs and GIDs, for users and groups
by using an alias index that is automatically maintained by RACF. This allows RACF to more
efficiently handle authentication and authorization requests from applications such as z/OS
UNIX than was possible using other methods, such as the UNIXMAP class and VLF. Once
your installation reaches stage 3 of application identity mapping (AIM), you will no longer have
UNIXMAP class profiles on your system, and you can deactivate the UNIXMAP class and
remove VLF classes IRRUMAP and IRRGMAP.
CLASS NAME(IRRUMAP)
EMAJ(UMAP)
CLASS NAME(IRRGMAP)
EMAJ(GMAP)
CLASS NAME(IRRGTS)
EMAJ(GTS)
CLASS NAME(IRRACEE)
EMAJ(ACEE)
CLASS NAME(IRRSMAP)
EMAJ(SMAP)
Important: Associating RACF user IDs and groups to UIDs and GIDs has important
performance considerations. If your installation shares the RACF database with systems
running releases prior to OS/390 Version 2 Release 10, it is important to use the VLF
classes IRRUMAP and IRRGMAP and the UNIXMAP class to improve performance by
avoiding sequential searches of the RACF database for UID and GID associations.
If your installation shares the RACF database with only systems running z/OS, or OS/390
Version 2 Release 10 or above, you may be able to achieve improved performance without
using UNIXMAP and VLF. However, before you can avoid using UNIXMAP and VLF, you
need to implement stage 3 of application identity mapping by running the IRRIRA00
conversion utility.

Chapter 1. Products and components
19
1.12 Time Sharing Option/Extended (TSO/E)
Figure 1-12 TSO/E and z/OS UNIX
TSO/E and z/OS UNIX
The TSO Extensions (TSO/E) licensed program is based on the Time Sharing Option (TSO),
which allows users to interactively share computer time and resources.
TSO/E is composed of modules that communicate with the user and perform the work
requested by the user. When a user logs on to TSO/E, the user must either specify the name
of a LOGON procedure by the LOGON command or accept that user's default procedure
name from the user attribute data set.
One way to enter the UNIX shell environment is by using TSO/E. A user logs on to a TSO/E
session and enters the TSO/E OMVS command.
The z/OS environment has other TSO/E commands, for example, to logically mount and
unmount file systems, create directories in a file system, and copy files to and from MVS data
sets. Users can switch from the shell to their TSO/E session, enter commands, or do editing,
and switch back to the shell. For information about how to perform these tasks using TSO/E
commands, see z/OS UNIX System Services User's Guide, SA22- 7801.
User
Interface
Used to enter the UNIX shell - OMVS command
Used to enter the ISHELL - ISHELL command
TSO commands - MOUNT, OGET/OPUT, OEDIT
z/OS UNIX

20
ABCs of z/OS System Programming: Volume 9
1.13 Workload Manager (WLM)
Figure 1-13 WLM and z/OS UNIX
WLM and z/OS UNIX
The purpose of workload management is to balance the available system resources to meet
the demands of subsystem work managers such as CICS®, BATCH, TSO, UNIX Services,
and WebServer, in response to incoming work requests.
The workload manager is a component of the BCP element. When using WLM, you do not
need to do any tuning or issue any commands. The kernel uses WLM to create child
processes when running in goal mode or compatibility mode, or both.
The workload manager is a component of z/OS that provides the ability to run multiple
workloads at the same time in one z/OS image or across multiple images. When using WLM,
you do not need to do any tuning or issue any commands. The kernel uses WLM to create
child processes while running in goal mode.
When programs issue fork() or spawn(), the BPXAS PROC found in SYS1.PROCLIB is used
to provide a new address space. For a fork(), the system copies one process, called the
parent process, into a new process, called the child process. The forked address space is
provided by WLM.
System A
No delays
WLM
Control UNIX address spaces
Start and stop (fork and spawn)
Performance of processes
System A
System B
System C

Chapter 1. Products and components
21
1.14 Tivoli Storage Manager (TSM)
Figure 1-14 Tivoli and z/OS UNIX
TSM and z/OS UNIX
Tivoli Storage Manager (TSM) is a client/server storage management product that provides
administrator-controlled, highly automated, centrally scheduled, network-based backup and
archive functions for workstations and LAN file servers. A TSM server backs up and/or
archives data from a TSM client and stores the data in the TSM server storage pool for z/OS
UNIX clients.
There are two types of backup: incremental, in which all new or changed files are backed up;
and selective, in which the user backs up specific files.
Backup can be performed automatically or when the user requests it. The user can initiate a
specific type of backup or start the scheduler, which will run whatever action the TSM
administrator has scheduled for the user's machine.
As a TSM authorized user, you also have the authority to back up and archive all eligible files
in all locally mounted file systems on your workstation, restore and retrieve all backup and
archive files for your workstation from TSM storage, within the limits imposed by the UNIX file
access permissions. A TSM authorized user can also grant users access to specific files in
TSM storage.
Information about using the z/OS UNIX client is documented in:
TSM Using the Backup-Archive Clients, SH26-4105
TSM Installing the Clients, SH26-4102
TSM
Server
HFS - zFS
Volumes
TSM
Storage Pools

22
ABCs of z/OS System Programming: Volume 9
Data Facility System-Managed Storage Hierarchical Storage Manager (DFSMShsm) provides
automatic backup facilities for HFS data sets. The system programmer uses DFSMShsm
facilities to back up mountable file systems by backing up the HFS data sets that contain them
on a regular basis; the data sets can be restored when necessary. DFSMShsm is also used
for migrating (archiving) and restoring unmounted file systems.

© Copyright IBM Corp. 2011. All rights reserved.
23
Chapter 2.
z/OS UNIX overview
This chapter provides a brief overview of the most important components of z/OS UNIX
System Services (z/OS UNIX). The following topics are discussed:
z/OS UNIX terminology
z/OS UNIX physical file systems
Hierarchical file system structure
File system data sets
The z/OS UNIX components
z/OS UNIX processes
z/OS UNIX interfaces
Methods for direct login to the z/OS UNIX shell
2

24
ABCs of z/OS System Programming: Volume 9
2.1 z/OS UNIX and UNIX applications
Figure 2-1 UNIX applications using z/OS UNIX
z/OS UNIX and SPEC1170
IBM added UNIX to the MVS environment to compete for new work on S/390®. In addition to
the characteristics of UNIX described earlier, portability is important due to the openness of
UNIX. The compliance of systems

to

SPEC1170, which is the Open Group's single UNIX
standard. IBM looked at the SPEC1170 specifications that say “these are what the UNIX
interfaces are” and implemented those specifications directly into its operating system as
OpenEdition services, which is now called z/OS UNIX. The OpenEdition MVS Shell and
Utilities, with many of the Korn shell features, were first to take advantage of the new z/OS
UNIX System Services now in z/OS.
Reasons for z/OS UNIX
For installations, portability of skills from one UNIX to another is important. If you work on a
UNIX system, you can port most of your skills onto another UNIX platform.
For applications, portability of source code from one UNIX platform to another is important. If
applications consisted of only interfaces that meet the X/Open SPEC1170 specifications (also
known as X/Open XPG4.2, or UNIX95, or Single UNIX Specification), a port would require no
changes to the applications. But, in the real world, where applications contain some
non-standard UNIX code, the applications do require some changes.
Accessing UNIX from database applications
As an example of database applications using z/OS UNIX, when using the DB2® ODBC
product for data set access, if you build a DB2 ODBC application in z/OS UNIX, you can use
IBM implemented UNIX based on SPEC1170
specifications
Reasons for z/OS UNIX
Run all types of applications on z/OS and zSeries
Portability of programmer skills
Portability of source code and applications
Accessing databases
DB2 can be called directly from a UNIX application
Importance on UNIX to MVS programmers

Chapter 2. z/OS UNIX overview
25
the c89 compile command to compile your application. Although you compile your application
under z/OS UNIX, you can directly reference the non-HFS DB2 ODBC data sets in the c89
command. There is no need to copy the DB2 ODBC product files to HFS.
Importance of UNIX to MVS programmers
MVS-experienced system programmers now installing, maintaining, and debugging z/OS
UNIX are faced with new responsibilities that require learning new vocabulary and new
concepts. Perhaps they must now interact with UNIX or TCP/IP computer personnel from
whom they have been isolated before now. Differences between the familiar MVS world and
the new UNIX world sometimes seem cultural and philosophical, as well as technical.

26
ABCs of z/OS System Programming: Volume 9
2.2 z/OS UNIX terminology overview
Figure 2-2 z/OS UNIX terminology
z/OS UNIX process
With z/OS, processes can be created by fork or spawn functions. Existing MVS address
space types such as TSO, STC, Batch, and APPC can request z/OS UNIX services. When
one of those address spaces makes its first request to the z/OS kernel, the kernel dubs the
task; that is, it identifies the task as a z/OS UNIX process.
z/OS UNIX thread
A process can have one or more threads; a thread is a single flow of control within a process.
Application programmers create multiple threads to structure an application in independent
sections that can run in parallel for more efficient use of system resources.
z/OS UNIX daemon
Daemon processes perform continuous or periodic system wide functions, such as a Web
server. Daemons are programs that are typically started when the operating system is
initialized and remain active to perform standard services.
z/OS UNIX shell
The UNIX shell interface is an execution environment analogous to TSO/E, with a
programming language of shell commands analogous to the Restructured eXtended
eXecutor (REXX) Language. The shell work consists of:
Programs run by shell users
Shell commands and scripts run by shell users
An address space is a process in UNIX
A task (TCB) is called a thread
A started task (STC) is a daemon
z/OS has TSO/E and ISPF and UNIX has a shell
Applications are written in different languages and
jobs are submitted for processing in different ways
HFS - Hierarchical file system
Structure of the file system - directories and files
PFS - Physical file system
z/OS UNIX kernel
Shared file system in a sysplex

Chapter 2. z/OS UNIX overview
27
Shell commands and scripts run as batch jobs
z/OS UNIX has two shells, the z/OS shell and the tcsh shell. They are collectively called the
z/OS UNIX shells.
z/OS UNIX applications
The following types of applications exist in z/OS UNIX:
Strictly conforming XPG4-conforming applications
Applications using only kernel services
Applications using both kernel and MVS services
Applications using only MVS services
z/OS UNIX file systems
z/OS UNIX files are organized in a hierarchical file system, as in other UNIX systems. Files
are members of a directory, and each directory is in turn a member of another directory at a
higher level. The highest level of the hierarchy is the root directory. Each instance of the
system contains only one root directory.
z/OS UNIX physical file systems
A physical file system (PFS) is the part of the operating system that handles the actual
storage and manipulation of data on a storage medium. In z/OS UNIX, for creating and
accessing HFS files, there are two PFSes, zFS and HFS.
z/OS UNIX kernel
The kernel address space contains the MVS support for z/OS UNIX services. This address
space can also be called the
kernel
and is the part of z/OS UNIX that contains programs for
such tasks as I/O, management, control of hardware, and the scheduling of user tasks.
Shared file system in a sysplex
By establishing the shared file system environment, sysplex users can access data
throughout the file hierarchy from any system in the sysplex. With shared file system support,
all file systems that are mounted by a system participating in a shared file system are
available to all participating systems. In other words, once a file system is mounted by a
participating system, that file system is accessible by any other participating system.
Although it is suggested that you exploit shared file system support when running in a sysplex
environment, you are not required to do so. If you choose not to, you will continue to share file
systems as you have before.

28
ABCs of z/OS System Programming: Volume 9
2.3 HFS and zFS file system PFSes
Figure 2-3 HFS and zFS file system PFSes
HFS and zFS file systems
The zSeries File System (zFS) is a UNIX file system that can be used in addition to the HFS.
This file system actually has been available since 1995 as part of the DCE component of
MVS/ESA V5R2.2, OS/390, and z/OS V1R1. It is a high-performance, log-based file system.
The DCE DFS Local File System is part of the OSF DFS product, and as such is included in
the Distributed File Service base element of z/OS V1R2. zFS is a separate component of the
DFS base element, so it can be serviced separately from the other components of DFS.
HFS stabilization
In early 2004, IBM announced that Hierarchical File System (HFS) function is stabilized. The
zSeries File System (zFS) is the strategic z/OS UNIX System Services file system for z/OS.
IBM has enhanced zFS function in z/OS V1R7 so that you can use zFS file systems at all
levels within the file hierarchy. HFS may no longer be supported in future releases and you
will have to migrate the remaining HFS file systems to zFS.
Using zFS
The zSeries File System (zFS) is a UNIX file system that can be used in addition to the HFS.
zFS is the strategic file system for z/OS. Therefore, in z/OS V1R7, zFS file system functions
are extended beyond those provided by HFS by improving usability, performance, and making
it easier to migrate your data from HFS file systems to zFS file systems.
HFS is a UNIX File System PFS for z/OS
Introduced with OpenEdition
zFS is a UNIX File System PFS for z/OS
Component of the Distributed File Service since 1995
HFS now stabilized - will be removed in future release
Using zFS, you can
Run applications just like HFS
Use zFS in addition to HFS or replace HFS
Advantages of zFS over HFS:
Better performance
Enhanced administrative functions
Less loss of data on system failures

Chapter 2. z/OS UNIX overview
29
2.4 Using z/OS UNIX
Figure 2-4 Using z/OS UNIX for applications and users
Creating UNIX files
When you are logged into the shell you have a choice of editors to create and change files,
depending on which terminal interface you are using, OMVS or the asynchronous terminal
interface. Accessing UNIX files can be done from application programs. Also, ISPF Edit
provides a full-screen editor to create and edit HFS files. You can access ISPF Edit in several
ways:
Using the oedit shell command
Using the TSO/E OEDIT command at the TSO/E READY prompt or from the shell
command line
From the ISPF menu (if a menu option is installed)
From the ISPF shell (accessed using the TSO/E ISHELL command)
Requests from kernel to PFS
When users access file data, the kernel passes the user request to the correct PFS to do the
I/O to the file system.
Physical file systems
A physical file system (PFS) controls access to data. PFSs receive and act upon requests to
read and write files that they control. The format of these requests is defined by the PFS
interface.
UNIX applications and users
Create files in the hierarchical file system
z/OS UNIX kernel passes access request to a PFS
Beginning with OpenEdition, this PFS was called HFS
Beginning with z/OS V1R2, zFS became a PFS
Physical file systems (PFSs)
File system requests can be passed to either HFS or
zFS physical file systems
Defined in the BPXPRMxx parmlib member

30
ABCs of z/OS System Programming: Volume 9
A physical file system (PFS) is packaged as one or more MVS load modules. These load
modules must be installed in an APF-authorized MVS load library. The hierarchical file system
is not available when a PFS is loaded, so it cannot be installed in the file system.
A PFS is defined to z/OS UNIX through the BPXPRMxx PARMLIB member you specify when
you start the kernel address space (OMVS=xx). The FILESYSTYPE statement defines a
single instance of a PFS.
HFS and zFS
When IBM created OpenEdition as part of MVS, the PFS that did the I/O to the file system
was called HFS.
Beginning with z/OS V1R2, a second PFS, called ZFS, was added. In current z/OS operating
systems, both the HFS and ZFS PFSs can be used to access file system data.
User-written programs use the POSIX API to issue file requests. These requests are routed
by the logical file system (LFS) to the appropriate PFS through the PFS interface.

Chapter 2. z/OS UNIX overview
31
2.5 z/OS UNIX System Services
Figure 2-5 z/OS UNIX System Services and the Kernel
POSIX-API
The Application Programming Interface (API) consists of C programming calls that can be
used by C/370™ programs to access z/OS UNIX. These C calls are defined in the POSIX
1003.1 standard. Many of the C calls will use callable services to interact with the z/OS
system to perform the services requested. Some C calls will interface directly with the z/OS
UNIX kernel.
The callable services can be used directly by Assembler programs to access z/OS UNIX, for
example to access files in the hierarchical file system. This possibility allows other high-level
languages (excluding C) and Assembler to use z/OS UNIX.
The API interface provides the ability to run XPG4.2 programs on z/OS. A program that
conforms to the XPG4.2 standard can be developed on one system and then ported to
another system, compiled and link-edited, and then executed on that system. Such a program
is referred to as
portable
.
A programmer can develop a program that uses a mix of standard z/OS services and z/OS
UNIX. Such a program is often referred to as a
mixed program
. A mixed program can, for
example, be a z/OS program that uses some of the Assembler callable services to access
files in the hierarchical file system, or a pipe for temporary data storage.
z/OS UNIX
programs
POSIX-API
C RTL
ASM/C/C++
z/OS UNIX Callable Services interfaces
Logical file system
z/OS UNIX-PFS interface
HFS PFS
Physical file
systems
Kernel
Interactive interface
REXX
Shell
Shell
cmds
cmds

32
ABCs of z/OS System Programming: Volume 9
Shell interactive interface
The interactive interface is called the z/OS UNIX shell. The shell is a command interpreter
that accepts commands defined in the POSIX 1003.2 standard. Shell commands can be put
together in a sequence, stored in a text file as a shell script, and then executed. The request
is then passed to the callable services interface. The shell script is similar to z/OS CLISTs
and REXX execs.
REXX
TSO REXX has been extended to provide access to the z/OS UNIX callable services. A
REXX exec using z/OS UNIX System Services can be run from TSO/E, in z/OS batch, or in
the shell.
You can use a set of z/OS UNIX extensions to TSO/E REXX—host commands and
functions—to access kernel callable services. The z/OS UNIX extensions, called syscall
commands, have names that correspond to the names of the callable services that they
invoke, for example, access, chmod, and chown.
You can run a REXX program with z/OS UNIX extensions from MVS, TSO/E, the shell, or a C
program. The REXX exec is not portable to an operating system that does not have z/OS
UNIX installed.
Physical file system (PFS)
The PFS interface is a set of protocols and calling interfaces between the logical file system
(LFS) and the PFSs that are installed on z/OS UNIX. In a z/OS UNIX System Services
environment, UNIX programs and UNIX users access their files through these interfaces.
PFSs mount and unmount file systems and perform other file operations.
Supported file types
z/OS UNIX supports the following types of files:
Regular files
Directories
Symbolic links
Character special files (for example, terminals)
Pipes (both FIFOs and unnamed)
Sockets

Chapter 2. z/OS UNIX overview
33
2.6 Physical file systems
Figure 2-6 z/OS UNIX and physical file systems
Physical file systems
A physical file system (PFS) is packaged as one or more MVS load modules. These load
modules must be installed in an APF-authorized MVS load library. The hierarchical file system
is not available when a PFS is loaded, so it cannot be installed in the file system.
A PFS controls access to data. PFSs receive and act upon requests to read and write files
that they control. The format of these requests is defined by the PFS interface. In a z/OS
UNIX, the physical file systems are defined in the BPXPRMxx PARMLIB member. zFS, as a
physical file system, is also defined in the PARMLIB member. Figure 2-6 shows all the
physical file systems that can be defined in a z/OS UNIX System Services environment. The
logical file system (LFS) is called by POSIX programs, non-POSIX z/OS UNIX programs, and
VFS servers.
PFS interface‘
The PFS interface is a set of protocols and calling interfaces between the LFS and the PFSs
that are installed on z/OS UNIX. PFSs mount and unmount file systems and perform other file
operations.
There are two types of PFSs, those that manage files and those that manage sockets:
File management PFSs, such as HFS and zFS, deal with objects that have path names
and that generally follow the semantics of POSIX files.
read
write open close
auto-
mount
TFS
IP
sockets
Local
sockets
NFS
client
Hierarchical
File System
ZFS
HFSVOL
HFSVOL
ZFSVOL
ZFSVOL
F
F
/
F
F
F
F
F
/
F
F
F
F
Physical File Systems
Migration
Copy HFS to zFS
z/OS UNIX Callable Services Interfaces
Logical File System
z/OS UNIX-PFS Interface
Kernel

34
ABCs of z/OS System Programming: Volume 9
Socket PFSs deal with objects that are created by the socket() and accept() functions and
that follow socket semantics.
HFS to zFS migration
Because IBM has announced the stabilization of the HFS PFS, a migration of HFS file
systems (both mounted and unmounted) to zFS file systems must occur over time.
Advantages of zFS
Like HFS, zFS is a UNIX file system. It contains files and directories that can be accessed
with the APIs available for HFS. In general, the application view of zFS is the same as the
application view of HFS. Once a zFS file system is mounted, it is almost indistinguishable
from any other mounted HFS. The benefits of using zFS are:
Improved performance
zFS provides significant performance gains in many customer environments accessing
files approaching 8K in size that are frequently accessed and updated. The access
performance of smaller files is equivalent to HFS.
Underlying architecture supports additional functions
Only zFS supports security labels. Therefore, in a multilevel-secure environment, you
must use zFS file systems instead of HFS file systems.
As an optional function, zFS allows the administrator to make a read-only clone of a file
system in the same data set. This clone file system can be made available to users to
provide a read-only point-in-time copy of a file system.
zFS runs as a z/OS UNIX colony address space. Therefore, zFS can be stopped using the
p zfs operator command. zFS file systems should be unmounted or moved to another
sysplex member before stopping zFS.
Improved crash recovery
zFS provides a reduction in exposure to loss of updates. zFS writes data blocks
asynchronously and does not wait for a sync interval. zFS is a logging file system. It logs
metadata updates. If a system failure occurs, zFS replays the log when it comes back up
to ensure that the file system is consistent.

Chapter 2. z/OS UNIX overview
35
2.7 z/OS UNIX file sharing in a sysplex
Figure 2-7 z/OS UNIX file sharing
z/OS UNIX file sharing
Although it is suggested that you exploit shared file system support when running in a sysplex
environment, you are not required to do so. If you choose not to, you will continue to share file
systems as you have before. With shared file system support, all file systems that are
mounted by a system participating in a shared file system are available to all participating
systems. The system that mounts the file system becomes the owner. All other systems have
to go to the owning system to access the file system. In other words, once a file system is
mounted by a participating system, that file system is accessible by any other participating
system. It is not possible to mount a file system so that it is restricted to just one of those
systems. This file sharing mode is supported by both zFS and HFS.
OMVS couple data set
The couple data set (CDS) contains the sysplex-wide mount table and information about all
participating systems, and all mounted file systems in the sysplex. To allocate and format a
CDS, customize and invoke the BPXISCDS sample job in SYS1.SAMPLIB. The job will create
two CDSs: one is the primary and the other is a backup that is referred to as the alternate. In
BPXISCDS, you also specify the number of mount records that are supported by the CDS.
SYSPLEX(YES)
In the BPXPRMxx parmlib member, SYSPLEX(YES) specifies a shared file system for those
who are in the SYSBPX XCF group, the group that is participating in a shared file system.
The systems that specify SYSPLEX(YES) make up the participating group for the sysplex. If
OS/390 V2R9 - First file sharing - (Only HFS)
zFS supports shared file systems - (z/OS V1R2)
Buffer / Cache
System 2
System 1 System 3
File System
Owner/Server
File System
Sharing/Client
R/W R/WR/W
USS sharing group
XCF XCF
I/O's
...
SYSPLEX(YES)
...
BPXPRMxx
F
/
F
F
F
F
File System
File System
Sharing/Client
OMVS couple data set
BPXMCDS

36
ABCs of z/OS System Programming: Volume 9
SYSPLEX(YES) is specified in the BPXPRMxx member, but the system is initialized in
XCF-local mode, either by specifying COUPLE SYSPLEX(LOCAL) in the COUPLExx
member or by specifying PLEXCFG=XCFLOCAL in the IEASYSxx parmlib member, then the
kernel will ignore the SYSPLEX(YES) value and initialize with SYSPLEX(NO). This system
will not participate in a shared file system support after the initialization completes.
File system owner
The system where the file system is mounted is called the file system owner. The owner of a
file system is the first system that processes the mount. This system always accesses the file
system locally; that is, the system does not access the file system through a remote system.
Other non-owning systems in the sysplex access the file system either locally or through the
remote owning system, depending on the PFS and the mount mode.

Chapter 2. z/OS UNIX overview
37
2.8 z/OS UNIX file systems
Figure 2-8 Hierarchical file system structure for HFS and zFS file systems
HFS and zFS file systems
The hierarchical file system is used to store data and organize it in a hierarchical way by
employing file system entries such as directories and files. These file system entries have
certain attributes, such as ownership, permission bits, and access time stamps. The data and
the attributes of a file are stored with the file in the file system.
Path name
The path name is constructed of individual directory names and a file name separated by the
forward-slash character, for example:
/dir1/dir2/dir3/myfile
Like UNIX, z/OS UNIX is case-sensitive for file and directory names. For example, in the
same directory, the file MYFILE is a different file than myfile.
z/OS UNIX data sets
HFS data sets, zFS data sets, and z/OS data sets can reside on the same DASD volume.
The integration of the HFS file system with existing MVS file system management services
provides automated file system management capabilities that may not be available on other
POSIX platforms. This allows file owners to spend less time on tasks such as backup and
restore of entire file systems.
Directory
Directory
DirectoryDirectory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
Directory
Directory
HFS file system
Directory
Directory
DirectoryDirectory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
Directory
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
File
Directory
Directory
zFS file system
Resides in a MVS data set
Resides in a Linear VSAM
data set
File system structure

38
ABCs of z/OS System Programming: Volume 9
2.9 File system data sets
Figure 2-9 File system data sets
z/OS UNIX files
z/OS UNIX files are organized in a hierarchy, as in a UNIX system. All files are members of a
directory, and each directory is in turn a member of another directory at a higher level in the
hierarchy. The highest level of the hierarchy is the root directory.
MVS views an entire file hierarchy as a collection of hierarchical file system data sets (HFS
data sets). Each HFS data set is a mountable file system. DFSMS facilities can be used to
manage an HFS data set, and DFSMS Hierarchical Storage Manager (DFSMShsm*) is used
to back up and restore an HFS data set.
A file in the hierarchical file system is called an HFS file. HFS files are byte-oriented, rather
than record-oriented, as are MVS data sets.
Root file system
The root file system is the first file system mounted. Subsequent file systems can be mounted
on any directory within the root file system or on a directory within any mounted file system.
The root system is the starting point for the overall HFS file structure. It contains the root
directory and any related HFS or zFS files or subdirectories. The root file system is created as
part of the installation process, either by the ServerPac method or CPBDO, when you install
z/OS.
Path name
The path name is a file name specifying all directories leading to a file.
Mounted file system is a zFS
data set at directory /u
Pathname to files: /notesdata/mail
OMVS.USERS.ZFS
TED
RAY
SAM
Root /
u usr notesdata
mail
files

Chapter 2. z/OS UNIX overview
39
2.10 Root file system
Figure 2-10 The root file system
Root file system
The root file system is the first file system mounted. Subsequent file systems can be mounted
on any directory within the root file system or on a directory within any mounted file system.
The file system is the entire set of directories and files, consisting of all HFS files shipped with
the products that are ordered and all those created by the system programmer and users.
The system programmer (superuser) defines the root file system; subsequently, a superuser
can mount other mountable file systems on directories within the file hierarchy. Altogether, the
root file system and mountable file systems comprise the file hierarchy used by shell users
and applications.
The root consists of /dev, /tmp, /var, and /etc symbolic links that point to the /dev, /tmp, /var,
and /etc directories. On each of these directories, there will be a mounted file system
containing the directories and files associated with those functions.
Note: The root file system is called the version file system or version root.
The root file system consists of directories and files
Mountable file systems
Files shipped with the products
/
/
opt
opt
dev
tmp
var
etc
SYSTEM/
symlinks
dev
tmp
var
etc
samples
samples
bin
bin
usr
usr
u
u
lib
lib
$SYSNAME/etc
$SYSNAME/dev
$SYSNAME/tmp
$SYSNAME/var
OMVS.ROOT.ZFS
WebSphere
booksrvTivoli
lpp
.
.

40
ABCs of z/OS System Programming: Volume 9
2.11 File and directory permission bits
Figure 2-11 Permission bits in the FSP
Permission bits
Permission bit information is stored in the file security packet (FSP) within each file and
directory. (ACLs may also be stored with the file.) Permission bits allow you to specify read
authority, write authority, or search authority for a directory. They also allow specification of
read, write, or execute authority for a file. Because there are three sets of bits, separate
authorities can be specified for the owner of the file or directory, the owning group, and
everyone else, which is the other category.
File security packet (FSP)
Security information, such as the owner's UID-GID and the permission bits for a file, is kept in
a 64-byte area called the file security packet (FSP), which is mapped by IRRPIFSP. The FSP
is the security-related section of a file's attributes.
The FSP is created by a SAF call from the PFS when a file is created. Some of the
information is taken from the current security environment, and some of it is passed as
parameters.
The PFS stores the FSP with the attributes of the file.
When an access check is to be done, the PFS calls SAF with the type of check that is being
requested, the audit_structure from the current call, and the file's FSP. SAF passes these to
the security product, which extracts user information from the current security environment
and compares it against the access control that is stored within the FSP.
Permission bit settings checked by security product
For access to every file and directory
Permission Bit Examples:
700
owner(
7
=rwx) group(
0
=---) other(
0
=---)
755
owner(
7
=rwx) group(
5
=r-x) other(
5
=r-x)
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w x
r
w x
r
w x
Owner Group Other
File Permission Bits
File Mode
extattr
FSP

Chapter 2. z/OS UNIX overview
41
2.12 MVS data sets versus file system files
Figure 2-12 Comparison of MVS data set and file system files
Comparing MVS and UNIX files
The z/OS master catalog is analogous to the root directory in a hierarchical file system.
The user prefix assigned to MVS data sets points to a user catalog. The organization of the
user catalog is analogous to a user directory (/u/ibmuser) in the file system. Typically, one
user owns all the data sets whose names begin with his user prefix. For example, the data
sets belonging to the TSO/E user ID IBMUSER all begin with the prefix IBMUSER. There
could be data sets named IBMUSER.C, and IBMUSER.C(PGMA).
In the file system, ibmuser would have a user directory named /u/ibmuser. Under that
directory there could be subdirectories named /u/ibmuser and /u/ibmuser/c/pgma.
Of the various types of MVS data sets, a partitioned data set (PDS) is most like a user
directory in the file system. In a partitioned data set such as IBMUSER.C, you could have
members PGMA, PGMB, and so on. For example, you could have IBMUSER.C(PGMA) and
IBMUSER.C(PGMB). A subdirectory such as /u/ibmuser/c can hold many files, such as
pgma, pgmb, and so on.
All data written to the hierarchical file system can be read by all programs as soon as it is
written. Data is written to a disk when a program issues an fsync().
...
z/OS
MASTER CATALOG
ALIAS IBMUSER
USER
CATALOG
DSN=IBMUSER.C
PDS
DSN=IBMUSER.C(PGMA)
IBMUSER
FILE1
SEQ
FILE2
PDS
(FILE3)
(FILE4)
FILE5
VSAM
RECFM, BLKSIZE,
TYPE OF DATA SET
UNIX System Services
ROOT
/
/u/ibmuser
USER DIRECTORY
/u/ibmuser/c/
/u/ibmuser/c/pgma
/u/ibmuser
file1
file2/
file3 file4
Organization provided
by the application
file5

42
ABCs of z/OS System Programming: Volume 9
2.13 zFS or HFS data sets
Figure 2-13 zFS or HFS data sets
File system data sets
A z/OS UNIX hierarchical file system is contained in a data set type called zFS or HFS. A zFS
or HFS data set can reside on an SMS-managed volume, and it is a single volume data set if
it is non-SMS-managed. zFS or HFS data sets can reside with other MVS data sets on
SMS-managed volumes or non-SMS-managed volumes. Multiple systems can share a zFS
or HFS data set if it is mounted in read-only mode. Beginning with OS/390 V2R9, sharing can
be done in read-write mode.
An HFS data set is allocated by specifying HFS in the DSNTYPE parameter. You can also
define a data class for zFS or HFS data sets. OS/390 V2R7 began to support multivolume
access up to 59 physical volumes, but then the data set must be SMS-managed.
Note: APAR OW35441 now gives you the ability to allocate PDSE and HFS data sets on
unmanaged (non-SMS) volumes, if running DFSMS 1.4 or DFSMS 1.5.
Multivolume
DFSMS with z/OS V1R5 allows
Up to 59 volumes
Multivolume file systems are only supported as
SMS-managed
zFS or HFS data set
F
F
F
F F
/

Chapter 2. z/OS UNIX overview
43
2.14 z/OS UNIX components
Figure 2-14 The components of z/OS UNIX
z/OS UNIX components
z/OS UNIX offers open interfaces for applications and interactive users on a z/OS system.
The z/OS UNIX components and their functions are now described.
The z/OS UNIX kernel
At system IPL time, kernel services are started automatically. The kernel provides z/OS UNIX
System Services in answer to requests from programs and the shell. The kernel manages the
file system, the communications, and the program processes.
The hierarchical file system is shipped as part of DFSMS. zFS is shipped with the Distributed
File Service.
The POSIX standard introduces a completely new terminology in the MVS environment. A
typical UNIX operating system consists of a kernel that interfaces directly with the hardware.
Built on the kernel is the shell and utilities layer that defines a command interface. Then there
are application programs built on the shell and utilities.
In a z/OS UNIX environment the file system is considered part of the kernel because it is
allocated to the kernel. The support for the file system is provided by the DFSMS product.
Figure 2-14, showing the file system as part of the kernel, shows a logical view of the
solution.
Shell and Utilities
Applications
C / C++ for
z/OS
Compiler
DBX
Debugger
DFSMS
HFS
NFS
Language Environment
for z/OS
z/OS UNIX Kernel
Process Management
File Systems
Communications
z/OS Base
Assembler and
REXX Interface
Daemons
zFS

44
ABCs of z/OS System Programming: Volume 9
The z/OS UNIX API conforms to the POSIX and XPG4 standard. OS/390 was branded as a
UNIX system by the Open Group in 1996. To support the APIs, the z/OS system must provide
some system services that are included in the kernel, such as the file system and
communication services.
Daemons are programs that are typically started when the operating system is initialized and
remain active to perform standard services. Some programs are considered daemons that
initialize processes for users even though these daemons are not long-running processes.
z/OS UNIX supplies daemons that start applications and start a user shell session when
requested.
The z/OS UNIX shell and utilities
This is an interactive interface to z/OS UNIX services that interprets commands from
interactive users and programs. The shell and utilities component can be compared to the
TSO function in z/OS.
The z/OS UNIX debugger (dbx)
The z/OS UNIX debugger is a tool that application programmers can use to interactively
debug a C program. The dbx debugger is not part of the POSIX standard and is well known in
many UNIX environments.
The C/C++ compiler and C run-time libraries
The C/C++ compiler and C run-time libraries are needed to make executables that the kernel
understands and can manage.
DFSMS
DFSMS manages the hierarchical file system (HFS) data sets that contain the file systems. To
use kernel services in full-function mode, SMS must be active.
Network File System (NFS) enables users to mount file systems from other systems so that
the files appear to be locally mounted. You end up with a mixture of file systems that come
from systems where the UIDs and GIDs may be independently managed.
Language Environment (LE)
The C compiler and Language Environment feature library are changed and extended to
include support for the POSIX and XPG4 C function calls. The LE product provides a
common run-time environment and language-specific run-time services for compiled
programs.
To run a shell command or utility, or any user-provided application program written in C or
C++, you need the C/C++ run-time library provided with the Language Environment.
zFS
The zSeries File System (zFS) is a UNIX file system that can be used in addition to the
hierarchical file system physical file system. This file system has been available since 1995 as
part of the DCE component of MVS/ESA V5R2.2, OS/390, and z/OS V1R1. The file system
has been known as the DCE DFS Local File System (LFS), sometimes referred to as
Episode. It is a high-performance, log-based file system. The DCE DFS Local File System is
part of the OSF DFS product, and as such is included in the Distributed File Service base
element of z/OS V1R2. zFS is a separate component of the DFS base element, so it can be
serviced separately from the other components of DFS.

Chapter 2. z/OS UNIX overview
45
2.15 z/OS UNIX programs (processes)
Figure 2-15 z/OS UNIX programs (processes) and components
z/OS UNIX processes
A process is a program using kernel services. The program can be created by a fork()
function, fork callable service, or spawn() function; or the program can be dubbed because it
requested kernel services. The three types of processes are:
User processes, which are associated with a program or a shell user
Daemon processes, which perform continuous or periodic system-wide functions, such as
printer spooling
Kernel processes, which perform system-wide functions for the kernel such as cleaning up
zombie processes (init process)
UNIX commands
When you enter a shell command, you start a process that runs in an MVS address space.
When you enter that command, the z/OS shell runs it in its own process group. As such, it is
considered a separate job and the shell assigns it a job identifier—a small number known
only to the shell. A shell job identifier identifies a shell job, not an MVS job. When the process
completes, the system displays the shell prompt.
UNIX programs and components
UNIX programs running in MVS address spaces use or access the following:
ASM/C++/C These programming languages can be used to create the programs.
z/OS Operating System
UNIX System Services (Kernel)
MVS
Data
Sets
AS
AS
AS
PARMLIB
VTAM
TCP/IP
SAF
ASM
C++/C
UNIX programs (processes)
execute in MVS Address Spaces
Communications Server for z/OS
HFS
Files

46
ABCs of z/OS System Programming: Volume 9
SAF A security product is required when running z/OS UNIX System Services.
SAF is the interface to RACF, Top Secret, or ACF2.
BPXPRMxx This PARMLIB member determines the number of processes that may be
started in the z/OS system.
MVS data sets UNIX programs may access MVS data sets.
HFS files UNIX programs may access HFS files.
TCP/IP Workstation users can enter the shell environment by using rlogin or
telnet in a TCP/IP network. User-written applications can use TCP/IP as a
communication vehicle.
VTAM Workstation users can access TSO/E through VTAM. z/OS UNIX is then
accessed from TSO/E.

Chapter 2. z/OS UNIX overview
47
2.16 Create a process
Figure 2-16 Creating a process
Creating a process
A process is created by using any of the following methods:
C fork() function
Creates a child process that is identical to the parent process in a new address space
scheduled by the Workload Manager (WLM).
C spawn() function
Creates a child process that executes a different program than the parent, either in a new
address space scheduled by WLM, or in the same address space as the parent process
(local spawn).
z/OS UNIX callable services
When a program uses a z/OS UNIX assembler callable service, the z/OS address space
is
dubbed
a z/OS UNIX process. The address space gets a PID. The dub does not result in
a new address space.
Using the fork() function
Fork() is a POSIX/XPG4 function that creates a duplicate process referred to as a child
process. The process that issues the fork() is referred to as the parent process.
With z/OS UNIX, a program that issues a fork() function creates a new address space that is
a copy of the address space where the program is running. The fork() function does a
prog1
............
fork()....
............
prog1
............
fork()....
............
WLM
ASID=428
ASID=547
prog2
prog4
prog3
................
spawn(prog3)
spawn(prog4)
................
................
................
................
................
................
ASID=1012
ASID=1423
SYS1.PROCLIB
Parent Process
Child Process
z/OS
UNIX
Kernel
BPXAS

48
ABCs of z/OS System Programming: Volume 9
program call to the kernel, which uses WLM/MVS facilities to create the child process. The
contents of the parent address space are then copied to the child address space.
After the fork() function, the program in the child address space will start at the same
instruction as the program in the parent address space. Control is returned to both programs
at the same point. The only difference that the program sees is the return code from the fork()
function. A return code of zero is returned to the child after a successful fork(). All other return
codes are valid only for the parent.
Child address space
Once the child address space has been created, the child gets the required storage from a
STORAGE request. The kernel then copies the contents of the parent address space to the
child address space using the MVCL instruction. Once the copy has been completed, a short
conversation between the kernel and the child process takes place. At this point, both the
parent and child process are activated. The program in the child address space gets control
at the same point as the program in the parent address space. The only difference is the
return code from the fork() function.
The child address space is almost an identical copy of the parent address space. User data,
for example private subpools, and system data, like Recovery Termination Management
(RTM) control blocks, are identical.
WLM and the kernel
The kernel interfaces to WLM to create the new address space for a fork or spawn. WLM uses
an IBM-supplied procedure, BPXAS, to start up a new address space. This new address
space then initializes the UNIX child process to run in the address space. After the child
process completes, this address space can be reused for another fork or spawn. If none is
waiting, BPXAS times out after being idle for 30 minutes.

Chapter 2. z/OS UNIX overview
49
2.17 z/OS UNIX processes
Figure 2-17 z/OS UNIX processes
z/OS UNIX processes
z/OS UNIX uses processes to run programs, and to associate resources to the programs. A
z/OS address space can contain one or multiple processes. A process is created by another
process, or by a request for a z/OS UNIX service. The process that creates a new process is
called a parent process and the new process is called a child process. There will be a
hierarchy of processes in the system.
Process ID (PID)
Every process is identified by a process ID (PID) and is associated with its parent process by
a parent process ID (PPID).
z/OS UNIX supports processes that run in unique address spaces. These would be created
by fork() and exec() services. It also supports local processes. These will share an address
space and are created by the spawn() service.
The system also assigns a process group identifier (PGID) and a process identifier (PID).
When only one command is entered, the PGID is the same as the PID. The PGID can be
thought of as a system-wide identifier. If you enter more than one command at a time using a
pipe, several processes, each with its own PID, will be started. However, these processes all
have the same PGID and shell job identifier. The PGID is the same as the PID for the first
process in the pipe.
ASID=218
ASID=256
ASID=425
ASID=671
PID=57
PPID=42
PID=42
PPID=18
PID=60
PPID=35
PID=73
PPID=60
PID=96
PPID=73
PID=81
PPID=73

50
ABCs of z/OS System Programming: Volume 9
Process identifiers
Process identifiers associated with a process are as follows:
PID A process ID. A unique identifier assigned to a process while it runs. When the
process ends, its PID is returned to the system. Each time you run a process, it has a
different PID (it takes a long time for a PID to be reused by the system). You can use
the PID to track the status of a process with the ps command or the jobs command, or
to end a process with the kill command.
PGID Each process in a process group shares a process group ID (PGID), which is the
same as the PID of the first process in the process group. This ID is used for signaling
related processes. If a command starts just one process, its PID and PGID are the
same.
PPID A process that creates a new process is called a parent process; the new process is
called a child process. The parent process ID (PPID) becomes associated with the
new child process when it is created. The PPID is not used for job control.
A process can create one or more child processes, and the child processes can be parent
processes of new child processes, thus creating a hierarchy of related processes. The PPID
maintains the relationship between processes. Usually, a process creates a child process to
perform a separate task, for example a shell command. The child process ends when the task
is completed while the parent process continues to execute. If for some reason a parent
process should terminate before a child process, the child process will become an orphan
process. Orphan processes are inherited by the first process created in the system, called the
init
process.

Chapter 2. z/OS UNIX overview
51
2.18 z/OS UNIX interactive interfaces
Figure 2-18 z/OS UNIX interactive interfaces
z/OS UNIX interactive interfaces
Figure 2-18 is an overview of the two interactive interfaces, z/OS UNIX shell and the ISHELL.
In addition, there are some TSO/E commands to support z/OS UNIX, but they are limited to
certain functions such as copying files and creating directories.
The z/OS UNIX shell is based on the UNIX System V shell and has some of the features from
the UNIX Korn shell. The POSIX standard distinguishes between a
command
, which is a
directive to the shell to perform a specific task, and a
utility
, which is the name of a program
callable by name from the shell. To the user, there is no difference between a command and a
utility.
ISHELL or OMVS shell
Interactive users of z/OS UNIX have a choice between using a UNIX-like interface (the shell),
a TSO interface (TSO commands), and an ISPF interface (ISPF CUA dialog). With these
choices, users can choose the interface which they are most familiar with and get a quicker
start on z/OS UNIX.
The z/OS UNIX shell provides the environment that has the most functions and capabilities.
Shell commands can easily be combined in pipes or shell scripts and thereby become
powerful new functions. A sequence of shell commands can be stored in a text file which can
be executed. This is called a shell script. The shell supports many of the features of a regular
programming language.
z/OS UNIX
(z/OS Shell)
OMVS command
ISPF Shell
(ISHELL)
ISHELL command
UNIX interface
POSIX 1003.2
Command interface
ISPF-based
Menu interface
TSO experienced user
UNIX experienced user
type filename
dir bin
dir etc
# ls -l

52
ABCs of z/OS System Programming: Volume 9
TSO commands for interactive use
There are some TSO commands that provide support for z/OS UNIX System Services, as
follows:
ISHELL The ISHELL command will invoke the ISPF shell. The ISHELL is a good starting
point for users familiar with TSO and ISPF who want or need to use z/OS UNIX.
The ISHELL provides CUA panels where users can work with the hierarchical file
system. There are also panels for mounting/unmounting file systems and for doing
some z/OS UNIX administration.
OMVS The OMVS command used to invoke the z/OS UNIX shell.
The ISHELL is an ISPF dialog for users and system administrators which can be used instead
of shell commands to perform many tasks related to file systems, files, and z/OS UNIX user
administration.
REXX support
The REXX support for z/OS UNIX is not really an interactive interface, but we chose to
introduce it here since it is most often used in TSO or in the shell. The SYSCALL environment
is not built into TSO/E, but an external function call called SYSCALLS initializes the
environment.
An interactive user who uses the OMVS command to access the shell can switch back and
forth between the shell and TSO/E, the interactive interface to MVS.
Programmers whose primary interactive computing environment is a UNIX or AIX®
workstation find the z/OS shell programming environment familiar.
Programmers whose primary interactive computing environment is TSO/E and ISPF can do
much of their work in that environment.
Interactive users of z/OS UNIX have a choice between using a UNIX-like interface (the shell),
a TSO interface (TSO commands), or an ISPF interface (ISPF CUA dialog). With these
choices, users can choose the interface which they are most familiar with and get a quicker
start on z/OS UNIX.
Note: The shell is the initial host environment, which means that the SYSCALL
environment is automatically initialized. A difference between the REXX support and shell
scripts is that a REXX EXEC can be invoked from a C program, while a shell script can
only be interpreted from the shell. A REXX EXEC can be called from a shell script.

Chapter 2. z/OS UNIX overview
53
2.19 ISPF Option 6
Figure 2-19 ISPF Option 6 panel
Interactive use via ISPF Option 6
With the ISPF shell (ISHELL), a user or system programmer can use ISPF dialogs instead of
shell commands to perform many tasks, especially those related to file systems and files.
After a logon to TSO/E, enter Option 6 under ISPF to use the OMVS and ISHELL commands.
The ISPF shell is a panel interface that you can use instead of TSO/E commands or shell
commands to perform certain tasks. For example, you can use the ISPF shell to display all
mounted file systems or its attributes, such as total blocks. You can also use the ISPF shell to
perform the following tasks, which require superuser authority or the RACF SPECIAL attribute
or both.
A user can use the ISPF shell to work with:
Directories
Regular files
FIFO special files
Symbolic links, including external links
You can also run shell commands, REXX programs, and C programs from the ISPF shell. The
ISPF shell can only direct stdout and stderr to a file in your file system, not to your terminal. If
it has any contents, the file is displayed when the command or program completes. If you are
a user with an MVS background, you may prefer to use the ISPF shell panel interface instead
of shell commands or TSO/E commands to work with the file system. The ISPF shell also
provides the administrator with a panel interface for setting up users for z/OS UNIX access,
for setting up the root file system, and for mounting and unmounting a file system.
Menu List Mode Functions Utilities Help
____________________________________________________________________________
ISPF Command Shell
Enter TSO or Workstation commands below:

===> ISHELL
______________________________________________________________________


____________________________________________________________________________


____________________________________________________________________________


Place cursor on choice and press enter to Retrieve command

=> ishell
=> omvs
=> netstat
=>
=>
=>
=>
=>
=>
=>

54
ABCs of z/OS System Programming: Volume 9
2.20 ISHELL command (ish)
Figure 2-20 Panel displayed after issuing the ish command
ISHELL command panel
Figure 2-20 shows the ISHELL or ISPF shell panel displayed as a result of the ishell or ish
command entered from ISPF Option 6. Fill in a path name or select a pull-down choice. If you
do not enter a path name, your working directory is used. Some pull-down choices do not
require a path name.
To search a user's files and directories, type the following and press Enter:
/u/userid
Pull-down menu
At the top of the panel is the action bar or pull-down menu, with eight choices, as follows:
File - Directory - Special file - Tools - File systems - Options - Setup - Help
When you select one of these choices, a pull-down panel with a list of actions is displayed.
EUID
The effective user ID (EUID) of the current user or process, is initialized at shell startup.
File Directory Special_file Tools File_systems Options Setup Help
__________________________________________________________________________
UNIX System Services ISPF Shell
Command ===> ____________________________________________________________

Enter a pathname and do one of these:

- Press Enter.
- Select an action bar choice.
- Specify an action code or command on the command line.

Return to this panel to work with a different pathname.
More: +
/u/rogers
________________________________________________________________
________________________________________________________________
________________________________________________________________

EUID=0

Chapter 2. z/OS UNIX overview
55
2.21 User’s files and directories
Figure 2-21 Display of a user’s files and directories
Directory List
This function displays all files in a directory. You can customize the columns by using the
Options pull-down and then selecting the Directory List choice. Select one or more files by
action code or / and press Enter. To scroll the list of files, use the Forward and Backward
function keys. Processing does not begin until you press Enter.
Displaying files and directories
An action code is a single character you can enter to select a specific action for a file. To
display the valid action codes for a file type, put the cursor under the file type and press the
Help function key.
Shown in the figure are the files and directories of user
rogers
. The user can then use action
codes to do the following:
b Browse a file or directory
e Edit a file or directory
d Delete a file or directory
r Rename a file or directory
a Show the attributes of a file or directory
c Copy a file or directory
File Directory Special_file Commands Help
______________________________________________________________________________
Directory List
Command ===> _________________________________________________________________

Select one or more files with / or action codes. If / is used also select an
action from the action bar otherwise your default action will be used. Select
with S to use your default action. Cursor select can also be used for quick
navigation. See help for details.
EUID=0 /u/rogers/
Type Perm Changed-EST5EDT, Owner ------Size Filename Row 1 of 27
_ Dir 755 2009-03-31 16:31 STC 8192 alice
_ Dir 700 2009-11-10 05:49 STC 8192 .
_ Dir 555 2009-11-03 10:14 STC 0 ..
_ File 400 2009-08-18 17:27 STC 17408 .ishell-reflist-ROGERS
_ File 600 2001-03-14 15:44 STC 793 .profile
_ File 600 2009-11-10 05:51 STC 2874 .sh_history
_ File 755 2005-08-17 14:01 STC 0 apf.file
_ Dir 755 2006-03-02 11:43 STC 8192 cachex
_ Dir 755 2006-03-02 15:58 STC 8192 cachey
_ Dir 755 2006-02-28 10:31 STC 8192 cache1
_ Dir 755 2006-02-28 11:51 STC 8192 cache2
_ File 700 2007-08-02 11:32 STC 729 cbprnt

56
ABCs of z/OS System Programming: Volume 9
2.22 OMVS shell session
Figure 2-22 OMVS shell session display after issuing the OMVS command in ISPF
OMVS shell session
After you invoke the shell with the OMVS command, you can switch among the shell, a TSO/E
session, and subcommand mode. You can switch to TSO/E to perform some tasks without
interrupting a process that is running and without shutting down the shell. You can switch to
subcommand mode to end the process if your process is in a loop and you are unable to
interrupt the process or enter a command.
Exit shell session
To exit the shell when a foreground process has completed, type exit and press Enter, or
press the <ESC>-D keys in sequence (where <ESC> is a defined escape character displayed
at the bottom of your panel). Any processes that are spawned using the nohup command
continue to run after you exit. Any processes spawned in the background without using the
nohup command die when you exit.
Enter only one subcommand at a time on the command line. You can enter subcommands
with leading or trailing blanks, but an empty or blank command line is ignored.
IBM
Licensed Material - Property of IBM
5694-A01 Copyright IBM Corp. 1993, 2009
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.

All Rights Reserved.

U.S. Government Users Restricted Rights -
Use,duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

PATH is set to /usr/lpp/java/J1.4/bin:/usr/lpp/Printsrv/bin:/bin:.:/usr/lpp/java
18/J1.1/bin
JAVA_HOME is set to /usr/lpp/java18/J1.1
CLASSPATH is set to /usr/lpp/Printsrv/classes/ipp.jar:/usr/lpp/Printsrv/classes/
ippserver.jar:/usr/lpp/Printsrv/classes/ippclient.jar:/usr/lpp/Printsrv/classes/
ippreal.jar:/usr/lpp/java18/J1.1/lib/classes.zip
LIBPATH is set to /usr/lpp/Printsrv/lib:/lib:/usr/lib:.:/usr/lpp/java18/J1.1/lib
/mvs/native_threads

===> ls -al
INPUT

Chapter 2. z/OS UNIX overview
57
2.23 OMVS command shell session
Figure 2-23 OMVS shell session after entering the ls -al command
Entering the UNIX shell using the OMVS command
Use the OMVS command to invoke the z/OS UNIX shell. Once you are working in a shell
session, you can switch to subcommand mode, return temporarily to TSO/E command mode,
or end the session by exiting the shell.
Shell commands often have options (also known as flags) that you can specify, and they
usually take an argument, such as the name of a file or directory. The format for specifying the
command begins with the command name, then the option or options, and finally the
argument, if any. In Figure 2-23, the following command is shown to list the files and
directories:
ls -al
where ls is the command name, -al are the options.
This figure shows the panel when the OMVS command is issued from ISPF Option 6. The ls
-al command lists the files and directories of the user. If the path name is a file, ls displays
information about the file according to the requested options. If it is a directory, ls displays
information about the files and subdirectories therein. You can get information about a
directory itself using the -d option.
If you do not specify any options, ls displays only the file names. When ls sends output to a
pipe or a file, it writes one name per line; when it sends output to the terminal, it uses the -C
(multicolumn) format.
U.S. Government Users Restricted Rights -
Use,duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

ROGERS @ SC74:/u/rogers>ls -al
total 202
drwxr-x--- 13 SYSPROG SYS1 960 Nov 4 04:52 .
dr-xr-xr-x 11 SYSPROG TTY 0 Nov 4 04:46 ..
-rw------- 1 SYSPROG SYS1 2183 Nov 4 04:58 .sh_history
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 2006 00000100
drwxr-xr-x 5 SYSPROG OMVSGRP 1120 Jul 26 2006 ITSO-link
drwxrwxrwx 4 SYSPROG SYS1 352 Aug 2 16:33
drwxr-xr-x 4 SYSPROG SYS1 320 Aug 2 16:33
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 2006 db2
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 2006 echo
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 2006 ims
-rwx------ 1 SYSPROG SYS1 0 Aug 28 2006 inetd-stderr
-rwx------ 1 SYSPROG SYS1 6 Apr 17 2008 inetd-stdout
-rwxr-xr-x 1 SYSPROG SYS1 73728 Apr 21 2006 maxcore
-rw-r--r-- 1 SYSPROG SYS1 0 Aug 3 12:42 more
ROGERS @ SC74:/u/rogers>

58
ABCs of z/OS System Programming: Volume 9
z/OS UNIX shell (OMVS)
Using the OMVS command to invoke the z/OS shell, you can select options on the OMVS
command to customize aspects of the shell interface, such as the function keys.
Once you are working in a shell session, you can switch to subcommand mode, return
temporarily to TSO/E command mode, or end the session by exiting the shell.
The shell is a command processor that you use to:
Invoke shell commands or utilities that request services from the system.
Write shell scripts using the shell programming language.
Run shell scripts and C-language programs interactively (in the foreground), in the
background, or in batch.
OMVS shell
In the OMVS shell environment, however, things work a little differently. A transaction starts
when a command is issued from the terminal. After the command is issued, polling is done to
wait for output to return from the command. Every half second, there is a test for output and a
test (TGET NOWAIT) for terminal input. This goes on for 20 seconds before the session goes
into INPUT mode and does a TGET WAIT for terminal input only. TGET NOWAIT does not
end the current transaction unless terminal input is found. If there is no more terminal input for
over 20 seconds, the transaction does not end until the TGET WAIT is issued and the session
goes into INPUT mode.

Chapter 2. z/OS UNIX overview
59
2.24 ls -al command - list files in the root
Figure 2-24 A UNIX command that lists the files in the root
Displaying files and directories
Figure 2-24 shows the result of the ls -al command to display files and directories from the
shell in the root file system. It displays the files and directories and shows the file access
allowed for the owner user, the user's group, and other users, which are called permission
bits, for example:
rwxrwxrwx
Permission bits
The default mode (read-write-execute permissions) for a directory created with the mkdir
command is:
owner=rwx
group=rwx
other=rwx


U.S. Government Users Restricted Rights -
Use,duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

ROGERS @ SC74:/u/rogers>cd ..
ROGERS @ SC74:/u>cd ..
ROGERS @ SC74:/>ls -al
total 48
lrwxrwxrwx 1 SYSPROG SYS1 9 May 17 2009 $SYSNAME -> $SYSNAME/
lrwxrwxrwx 1 SYSPROG SYS1 9 May 17 2009 $VERSION -> $VERSION/
drwxr-xr-x 18 SYSPROG SYS1 1504 Oct 19 12:00 .
drwxr-xr-x 18 SYSPROG SYS1 1504 Oct 19 12:00 ..
drwxr-xr-x 2 SYSPROG SYS1 256 May 30 2006 ...
-rw------- 1 SYSPROG SYS1 224 Sep 21 2007 .sh_history
drwx------ 2 SYSPROG SYS1 352 Sep 1 00:05 .ssh
drwxrwxrwx 4 SYSPROG SYS1 352 Oct 26 11:12 PLEX75
drwxr-xr-x 7 SYSPROG SYS1 640 Oct 4 12:48 SC74
drwxr-xr-x 6 SYSPROG SYS1 544 May 30 2006 SC75
===>
MORE...

60
ABCs of z/OS System Programming: Volume 9
2.25 ISPF edit mode for a z/OS UNIX file
Figure 2-25 Edit a z/OS UNIX file from ISPF Option 2
Editing z/OS UNIX files with ISPF
In z/OS V1R9, the ISPF EDIT, VIEW and BROWSE functions are enhanced to support z/OS
UNIX files. This includes support for z/OS UNIX files via Options 1 and 2 on the main ISPF
panel, as well as the ISPF EDIT, VIEW, and BROWSE service interfaces. In addition, the Edit
Entry, Browse/View Entry, Edit Copy, Edit Move, and Edit Create panels are modified so that
the “Other” data set name field is a scrollable field that supports z/OS UNIX files and path
names up to 1023 characters in length.
The Edit Option (2), shown in Figure 2-25, allows you to create, display, and change data
stored in ISPF libraries, other partitioned or single-volume or multivolume sequential data
sets, or now with z/OS V1R9: z/OS UNIX files by specifying a path name.
Type a z/OS UNIX file path name, such as:
Name . . . . . /u/jsmith/test/tst1.sh
Note: In z/OS V1R8, ISPF was enhanced to process z/OS UNIX files. The z/OS V1R8
support includes the ability to edit, browse, create, delete, rename, copy, and replace z/OS
UNIX files. This support is implemented as a directory list utility. The utility is available as
Option 17, z/OS UNIX Directory List Utility, under the ISPF Utilities menu (Option 3 from
the main ISPF panel).
Menu RefList RefMode Utilities Workstation Help
-----------------------------------------------------------------------------
Edit Entry Panel
Command ===>

ISPF Library:
Project . . . ROGERS
Group . . . . ZFS . . . . . . . . .
Type . . . . MIGRTOOL
Member . . . (Blank or pattern for member selection list)

Other Partitioned, Sequential or VSAM Data Set, or z/OS UNIX file:
Name . . . . . /u/rogers
+
Volume Serial . . (If not cataloged)

Workstation File:
File Name . .
Options
Initial Macro . . . . Confirm Cancel/Move/Replace
Profile Name . . . . . Mixed Mode
Format Name . . . . . Edit on Workstation
Data Set Password . . Preserve VB record length
Record Length . . . . Edit ASCII data

Chapter 2. z/OS UNIX overview
61
2.26 ISPF edit mode for a z/OS UNIX file
Figure 2-26 Files and directories with /u/rogers
Select a file to edit
When you press the Enter key on the panel shown in Figure 2-25 on page 60, and you enter
the path name without specifying a file, the panel shown in Figure 2-26 is displayed.
With this panel, select a file to edit by placing an e next to the file you wish to edit, as shown in
Figure 2-26. You then receive an ISPF panel displaying the file in ISPF edit mode, as shown
in Figure 2-27.
Figure 2-27 File selected to be edited
The file could be selected directly from Option 2 by using the following path name:
/u/rogers/cbprnt
e

62
ABCs of z/OS System Programming: Volume 9
2.27 Specifying the z/OS UNIX path name
Figure 2-28 Different ways to specify the z/OS UNIX path name
Specifying the path name
ISPF assumes that a z/OS UNIX path name is entered in this field when the first character is
one of the following:
/ (forward slash) Identifies an absolute path name.
/u/rogers as shown in Figure 2-25 on page 60
~ (tilde) Represents the path name for the user’s home directory.
Assuming a user’s home directory is /u/smith, specifying ~/test/tst1.sh is
the equivalent of specifying the absolute path name /u/smith/test/tst1.sh.
. (dot) Represents the path name for the current working directory.
Specifying ./pgma.c is the equivalent of specifying the absolute path
name /u/proj1/dev/pgma.c when the current working directory is
/u/proj1/dev/.
.. (dot dot) Represents the path name for the parent directory of the current working
directory.
Specifying ../test/pgma.c is the equivalent of specifying the absolute
path name /u/proj1/test/pgma.c when the current working directory is
/u/proj1/dev/.
/ (forward slash) Identifies an absolute path name
~ (tilde) Represents the path name for the user’s
home directory
~/test/tst1.sh specifies /u/smith/test/tst1.sh
. (dot) Represents the path name for the current
working directory
./pgma.c specifies /u/proj1/dev/pgma.c when the
current working directory is /u/proj1/dev/
.. (dot dot) Represents the path name for the parent
directory of the current working directory
../test/pgma.c specifies /u/proj1/test/pgma.c when the
current working directory is /u/proj1/dev/

Chapter 2. z/OS UNIX overview
63
2.28 ISPF ENQs on z/OS UNIX files
Figure 2-29 IPSF ENQs for protection of files
ISPF ENQ for z/OS UNIX files
To restrict concurrent use of a z/OS UNIX file, ISPF edit issues the following ENQ macro for
the file:
ENQ SPFEDIT,rname,E,12,SYSTEMS (z/OS UNIX in sysplex; OextSysplexActv = '
or
ENQ SPFEDIT,rname,E,12,SYSTEM (z/OS UNIX not in sysplex)
Where:
rname is 12 bytes in length, comprising the following 4-byte binary integers:
The inode number of the file
The device number of the file
Sysplex indicator:
– 1 z/OS UNIX is in a sysplex (OextSysplexActv is set ON).
– 0 z/OS UNIX is not in a sysplex (OextSysplexActv is set OFF).
This enqueue is compatible with the enqueue issued by the z/OS UNIX OEDIT command.
To avoid possible data corruption, ISPF issues an
exclusive ENQ request to prevent two or more users
from editing the same z/OS UNIX file at the same time
The ENQ major name is SPFEDIT
The ENQ minor name is a 12 bytes string
compromising these 3 binary integers:
The file’s i-node number (4 bytes)
The file’s device number (4 bytes)
A sysplex indicator (4 bytes), set to 1 when z/OS UNIX
is running with SYSPLEX(YES)

64
ABCs of z/OS System Programming: Volume 9
2.29 Support for editing ASCII data
Figure 2-30 Editing ASCII data with ISPF
Editing ASCII data
With the increasing use of Java™ and WebSphere® products on z/OS, more and more data
is stored in ASCII files on z/OS. One example is XML documents for WebSphere Application
Server. Prior to z/OS V1R9, there were few facilities available in z/OS to display and change
ASCII data, especially under ISPF. In general, it is necessary for ISPF users to download their
ASCII files to a workstation that supports the ASCII character set, edit the files on the
workstation, and upload them back to the z/OS system.
In z/OS V1R9, an ASCII editing facility is provided through the ISPF editor. The ASCII editing
facility translates ASCII data in a file to EBCDIC before displaying it at the terminal and
translates EBCDIC data to ASCII when receiving input from the terminal to write to the file. A
new SOURCE primary command for the ISPF editor is provided in z/OS V1R9 to control the
ASCII editing facility.
To activate the ASCII editing facility for a file, perform these steps:
1.Start editing the file as you would for a normal EBCDIC file. Then,
2.Enter the command SOURCE ASCII.
Once SOURCE ASCII is issued, the ISPF editor treats the source data as ASCII data and
converts it from ASCII to the Coded Character Set ID (CCSID) of the terminal for display
purposes. The data in the file remains unchanged. When you input or modify data at the
terminal, the ISPF editor translates the data entered from the CCSID of the terminal to ASCII
before storing the data in the file.
To activate the ASCII editing facility for a file:
Start editing the file as you would for a normal
EBCDIC file
In z/OS V1R9, an ASCII editing facility is provided
through the ISPF editor
The ASCII editing facility translates ASCII data in a file
to EBCDIC before displaying it at the terminal and
translates EBCDIC data to ASCII when receiving input
from the terminal to write to the file
A new SOURCE primary command for the ISPF editor
is provided in z/OS V1R9 to control the ASCII editing
facility
Enter the following command:
SOURCE ASCII

Chapter 2. z/OS UNIX overview
65
To change back to the normal editing mode, where the data is not translated from and to
ASCII when displaying and receiving input from the terminal, issue the primary EDIT
command: RESET SOURCE.
Note: The ASCII editing facility uses the z/OS Unicode Conversion Services to translate
the data between ASCII (CCSID 850) and the CCSID supported by the terminal. It is
required that z/OS Unicode Conversion Services be installed and the required translations
specified to it, in order for the ASCII editing facility to be operable.

66
ABCs of z/OS System Programming: Volume 9
2.30 Handling line feed characters
Figure 2-31 How to handle line feed characters in ASCII data
Handling line feed characters
Many times ASCII files contain line feed characters. When such an ASCII file is uploaded
from the workstation to a fixed length data set, the data may not be structured correctly
according to the line feed characters. The LF primary command is a new ISPF editor primary
command that restructures the data in the file based on the line feed characters.
The LF command
ASCII data can contain line feed characters (X'0A'). If the data has been uploaded from
another computing platform, the data may not be correctly structured based on the line feed
characters. To restructure the data based on the line feed characters, issue the LF command.
SOURCE ASCII and LF example
Using ISPF Option 2 to edit an ASCII file, it is displayed in Figure 2-32 on page 67. Enter the
SOURCE ASCII command on the command line to convert the file to EBCDIC.
Important: There is no reverse process for restructuring the data based on the line feed
characters. Consequently, once you have saved the data after an LF command, the
change is permanent. Do not enter the LF command more than once against the same file
because blanks following line feed characters are interpreted as the leading data of the
next record.
Many times ASCII files contain line feed characters
When such an ASCII file is uploaded from the workstation to
a fixed length data set, the data may not be structured
correctly according to the line feed characters
The LF primary command is a new ISPF editor primary
command that restructures the data in the file based on the
line feed characters
After starting the editor, issue commands in order to
activate the ASCII editing facility to restructure the ASCII
file according to the line feed characters it contains:
Issue the SOURCE ASCII command
Issue the LF command

Chapter 2. z/OS UNIX overview
67
Figure 2-32 ASCII file displayed with ISPF edit mode
When you Enter the source ascii command on the command line, the ASCII text is
converted to EBCDIC, as shown in Figure 2-33.
Figure 2-33 ASCII text converted to EBCDIC
When you use the LF command to restructure the data based on the line feed characters, the
text now is aligned as shown in Figure 2-34.
Figure 2-34 EBCDIC text following the line feed (LF) command
source ascii
LF

68
ABCs of z/OS System Programming: Volume 9
2.31 Direct login to shell
Figure 2-35 Diagram of a login to the shell from a terminal workstation
Entering a shell session from a workstation
Figure 2-35 shows two ways that you can access the z/OS UNIX shells:
The rlogin command, which provides an ASCII interface
The telnet command, which provides an ASCII interface
When you first log in to one of the z/OS UNIX shells, you are in line mode. Depending on how
you access the shell, you might be able to use utilities that require raw mode (such as vi) or
run an X-Windows application.
A z/OS UNIX user can log in directly to the z/OS UNIX shell using one of the following
solutions:
rlogin When the inetd daemon is set up and active, you can rlogin to the shell from a
workstation that has rlogin client support and is connected via TCP/IP or
Communications Server to the MVS system. To log in, use the rlogin (remote log
in) command syntax supported at your site.
telnet The telnet support comes with the TCP/IP z/OS UNIX feature. It also uses the
inetd daemon, which must be active and set up to recognize and receive the
incoming telnet requests.
ssh OpenSSH is intended to allow a non-z/OS server to communicate securely with a
z/OS server using the ssh protocol in a security-rich environment. Data is encrypted
as it passes through the network unaltered, and OpenSSL technology enables both
z/OS UNIX kernel
TCP/IP
shell
rlogind
shell
telnetd
inetd
WS
WS
WS
telnet-C
UNIX
UNIX
rlogin-C
WS
WS
WS
SSH
sshd

Chapter 2. z/OS UNIX overview
69
secure login and secure file transfer. Following is a partial list of utilities that are
included in OpenSSH:
ssh - A client program for logging into a z/OS shell. It is an alternative to rlogin.
scp - For copying files between networks. It is an alternative to rcp.
sftp - For file transfers over an encrypted ssh transport. It is an interactive file
transfer program similar to ftp.
sshd - A daemon program for ssh that listens for connections from clients. The
IBM Ported Tools for z/OS implementation of sshd simultaneously supports both
SSH protocol versions 1 and 2.
Terminal support considerations
There are some differences between the asynchronous terminal support (direct shell login)
and the 3270-terminal support (OMVS command):
You cannot switch to TSO/E. However, you can use the TSO shell command to run a
TSO/E command from your shell session.
You cannot use the ISPF editor (this includes the oedit and TSO/E OEDIT commands,
which invoke ISPF edit).
When you first log in to one of the z/OS UNIX shells, you are in line mode. Depending on how
you access the shell, you might be able to use utilities that require raw mode (such as vi) or
run an X-Windows application. The modes are:
Line mode Input is processed after you press <Enter>. Line mode is also called
canonical mode.
Raw mode Each character is processed as it is typed. Raw mode is also called
non-canonical mode.
Graphical A graphical user interface for X-Windows applications.
The TCP/IP chapters have more details about this. It is mentioned here to give you an idea of
the methods available to invoke the shell. Later chapters also have more information about
differences between the 3270 and the direct login methods.

70
ABCs of z/OS System Programming: Volume 9
2.32 Telnet access to z/OS UNIX
Figure 2-36 Telnet login to the shell screen
Shell session using Telnet
This figure shows the z/OS shell returned after a Telnet login.
From this session, you cannot switch to TSO/E or use the ISPF editor.
Telnet is a terminal emulation protocol that allows end users to log on to remote host
applications as though they were directly attached to that host. Telnet protocol requires that
the end user have a Telnet client emulating a type of terminal the host application will
understand. The client connects to a Telnet server, which communicates with the host
application. The Telnet server acts as an interface between the client and host application. A
PC can support several clients simultaneously, each with its own connection to any Telnet
server.

© Copyright IBM Corp. 2011. All rights reserved.
71
Chapter 3.
z/OS UNIX System Services
preinstallation requirements
This chapter describes the necessary preinstallation requirements to get z/OS UNIX System
Services up and running.
It explains in detail the following topics:
Customization of the root file system
The difference between ServerPac and CBPDO
The RACF definitions needed before initializing z/OS UNIX System Services
Allocation of the root file
The TSO/E debugging necessary when using the z/OS UNIX ISHELL
3

72
ABCs of z/OS System Programming: Volume 9
3.1 Customization of the root
Figure 3-1 The root file system
Root file system
The root file system is the starting point for the overall file system structure. It consists of the
root (/) directory, system directories, and files. A system programmer defines the root file
system. The system programmer must have an OMVS UID of 0 to allocate, mount, and
customize the root directories. It usually contains system-related files and files that belong to
a program product.
Directories in the root
The z/OS UNIX root file system directories and their contents are as follows:
bin Contains executable modules, mostly shell commands.
var Contains dynamic data that is used internally by products and by elements and
features of z/OS. Any files or directories that are needed are created during
execution of code. An example of this is caching data.
dev Contains character-special files that are used when logging into the OMVS shell
environment and also during c89 processing. Prior to OS/390 V2R7, these
character-special files were created by running the BPXISMKD REXX exec or
would be part of your ServerPac order. Beginning with OS/390 V2R7, /dev is
shipped empty. The necessary files are created when the system is IPLed, and
on a per-demand basis.
etc Contains customization data. Keeping the /etc file system in an HFS data set
separate from other file systems allows you to separate your customization data
Root
USR
VAR
/samples
/bin
/lib
/usr
/opt
symlinks
$SYSNAME/etc
$SYSNAME/dev
$SYSNAME/tmp
$SYSNAME/var
OMVS.ROOT.HFS
/samples
/bin
/lib
/usr
/opt
/
SYSTEM/
symlinks
symlinks
$SYSNAME/etc
$SYSNAME/dev
$SYSNAME/tmp
$SYSNAME/var
OMVS.ROOT.HFS
OMVS.ETC.HFS
OMVS.VAR.HFS
OMVS.TMP.HFS
OMVS.DEV.HFS
DEV TMP VAR ETC
DEV TMP VAR ETC
BIN
SAMPLES
LIB USR
OPT
BIN
SAMPLES
LIB USR OPT
U
mail man sbin include
DOMINO

TCPIP
lpp

Chapter 3. z/OS UNIX System Services preinstallation requirements
73
from IBM’s service updates. It also makes migrating to another release easier.
After you complete instructions for a ServerPac or CBPDO installation, you will
have an /etc file system in its own HFS data set.
tmp Contains temporary data that is used by products and applications. The directory
/tmp is created empty, and temporary files are created dynamically by different
elements and products. You have the option of mounting a temporary file system
(TFS) on /tmp.
lib This directory contains symbolic links to the TCP/IP directory for the X11 Window
interface. In a z/OS UNIX system, it is used as a library containing C run-time
libraries.
samples Contains examples of files that can be customized and used in the /etc directory.
u Contains user home directories
usr/lpp Contains subdirectories for other applications like Domino®, WebSphere, TCP/IP,
DCE, daemons, and so on.
SYSTEM The root file system contains an additional directory, /SYSTEM; existing
directories, /etc, /dev, /tmp and /var are converted into symbolic links. These
changes, however, are transparent to the user who brings up a single system
environment.
Symbolic links (Symlinks)
The presence of symbolic links is transparent to the user. In the illustrations used throughout
this redbook, symbolic links are indicated with an arrow.
Customization of the root file system
In Figure 3-1, the root file system contains an additional directory, /SYSTEM; existing
directories, /etc, /dev, /tmp, and /var are converted into symbolic links. These changes,
however, are transparent to the user who brings up a single system environment. During
installation, IBM defines directories in the /etc directory but does not install files there.
Because the configuration and customization data in your existing /etc directory might not be
correct for the new system, you might need to make changes to the files in your new /etc
directory. IBM recommends that you make these changes before the first IPL of the new
system. The presence of symbolic links is transparent to the user.
Starting in OS/390 V2R9, place the contents of the /etc, /dev, /tmp, and /var directories for
each system into separate HFS data sets if they have not already been set up that way. This
task is required for both non-sysplex users and sysplex users. Some utilities that are provided
by z/OS UNIX require the use of certain configuration files. Customers are responsible for
providing these files if they expect to use these utilities at their installation. IBM provides
default configuration files as samples in the /samples directory. Before the first use of any of
these utilities, you must copy these IBM-provided samples to the /etc directory (in most
cases). You can add further customization of these files to include installation-dependent
information.
Note: If the content of the symbolic link begins with $SYSNAME and SYSPLEX is
specified as NO in the BPXPRMxx member, then $SYSNAME is replaced with /SYSTEM
when the symbolic link is resolved.
Note: If the content of the symbolic link begins with $SYSNAME and SYSPLEX is
specified as NO, then $SYSNAME is replaced with /SYSTEM when the symbolic link is
resolved.

74
ABCs of z/OS System Programming: Volume 9
3.2 Installing z/OS using ServerPac
Figure 3-2 Installing z/OS using the ServerPac
ServerPac installation
ServerPac is a software delivery package consisting of products and services for which IBM
has performed the SMP/E installation steps and some of the post-SMP/E installation steps.
To install the package on your system and complete the installation of the software it includes,
you use the CustomPac Installation Dialog, the same dialog that is used for all the
CustomPac offerings, including SystemPac® and ProductPac®.
Two types of ServerPac installation are available:
A full system replacement
A software upgrade
ServerPac and the root HFS
For z/OS ServerPac customers, IBM delivers a single-root HFS. This HFS is unloaded when
you perform “Establishing UNIX Services” in the ServerPac installation process. Not only
does the single-root HFS make cloning of file systems easier, but it also dramatically reduces
the number of jobs run by system programmers to establish z/OS UNIX.
Note: A full system replacement will provide system software related data sets like Dlib
and Target, as well as SMP/E CSI data sets and sample libraries. A software upgrade can
only be done if those data sets are available.
Copy
Copy
CustomPac dialog
DASD
ShopzSeries - Electronic delivery
or
Installs z/OS UNIX
Root file system
and all products
F
u
l
l

c
o
p
y

F
u
l
l

c
o
p
y

o
r

o
r

U
p
g
r
a
d
e
U
p
g
r
a
d
e

Chapter 3. z/OS UNIX System Services preinstallation requirements
75
Electronic delivery
ShopzSeries is an Internet application you can use to order z/OS software products and
service. Using ShopzSeries, you can order corrective and preventive service over the
Internet, with delivery over the Internet or by tape. Service with ShopzSeries reduces your
research time and effort by using your uploaded SMP/E consolidated software inventory
(CSI) to ensure that all applicable service, including reachahead service, for the installed
FMIDs in the target zones is selected. The ShopzSeries Web address is:
http://www.ibm.com/software/shopzseries

76
ABCs of z/OS System Programming: Volume 9
3.3 Installing z/OS using CBPDO
Figure 3-3 Installing z/OS using CBPDO
CBPDO installation
Custom-Built Product Delivery Option (CBPDO) is a software delivery package consisting of
uninstalled products and unintegrated service. You must use SMP/E to install the individual
z/OS elements and features, and their service, before you can IPL.
The CBPDO installation process is split into separate stages, called waves. These waves
group related activities together so that at the completion of each wave, the wave components
can be activated (like performing an IPL).
These waves are:
Wave 0 installs prerequisite FMIDs onto the driving system, such as HLASM and SMP/E.
Wave 1 installs FMIDs that do not install into HFS.
Wave 2 installs FMIDs that do install into HFS.
Wave 3 installs FMIDs for JES2 or JES3.
BPXISHFS member of samplib
For customers who use the CBPDO software delivery package, a sample job called
BPXISHFS (found in SYS1.SAMPLIB) is provided. It allocates the root and /etc HFS data sets
and then mounts them at a given mount point. This job allocates a file system that is mounted
on the /etc directory so that z/OS-delivered code is part of a single HFS, while customized
data can be kept separate. This allows for easier cloning of file systems.
SMP/E
SMP/E
Wave Processing
DASD
Installs z/OS UNIX
Root file system
and all products
P
r
o
d
u
c
t
P
r
o
d
u
c
t
o
r

S
e
r
v
i
c
e
o
r

S
e
r
v
i
c
e

Chapter 3. z/OS UNIX System Services preinstallation requirements
77
3.4 ServerPac and CBPDO
Figure 3-4 ServerPac and the root file system
Installation data sets
For z/OS ServerPac customers, IBM delivers a single-root HFS. This HFS is unloaded when
you perform the “Establishing UNIX Services” step in the ServerPac installation process. Not
only does the single-root HFS make cloning of file systems easier, but it also dramatically
reduces the number of jobs run by system programmers to establish z/OS UNIX.
IBM also delivers a separate HFS data set for /etc.
Performing ServerPac installation requires that you be a superuser with UID(0) or have
access to the BPX.SUPERUSER resource in the FACILITY class.
For customers who use the Custom-Built Product Delivery Option (CBPDO) software delivery
package, a sample job called BPXISHFS (found in SYS1.SAMPLIB) is provided. It allocates
the root and /etc HFS data sets and then mounts them at a given mount point. This job
allocates a file system that is mounted on the /etc directory so that z/OS-delivered code is
part of a single HFS, while customized data can be kept separate. This allows for easier
cloning of file systems.
/etc file system
The /etc file system contains customization data, such as the definition files for the automount
facility. The install process creates an empty /etc directory into which customers must copy
their existing /etc file system. This directory is similar to SYS1.PARMLIB, but differs in some
aspects. For example, the /etc file system cannot be shared between systems, nor can the
Provide two HFS data sets:
Root file system
Files and executables
ETC file system
Contains only empty directories and symlinks
Recommendation for separate file system data sets
/tmp - /var - /dev - /etc
Separate customized data from shipped code

78
ABCs of z/OS System Programming: Volume 9
/etc file system be concatenated with other directories like SYS1.PARMLIB can. To keep your
customization data separated from IBM's service updates and to make migration to another
release easier, keep the /etc file system in an HFS data set separate from other file systems.
When you complete all instructions for installing z/OS, whether through a ServerPac or
CBPDO, you have an /etc file system in its own HFS data set.
To ensure that your customization files are not modified, IBM does not create any files in the
/etc file system. IBM does, however, create directories when they are needed. Furthermore,
IBM does not ship maintenance into /etc via SMP/E.
Starting in OS/390 V2R9, place the contents of the /etc, /dev, /tmp, and /var directories for
each system into separate HFS data sets if they have not already been set up that way. This
task is required for both sysplex and non-sysplex users.

Chapter 3. z/OS UNIX System Services preinstallation requirements
79
3.5 z/OS UNIX System Services installation
Figure 3-5 Components needed for z/OS UNIX installation
Customizing the z/OS UNIX environment
The ServerPac provides you with full system replacement and software upgrade options.
Online panels contain the jobs and present the information you need to proceed through the
ServerPac installation. Before you can install and set up z/OS UNIX System Services, the
following must be set up in your environment:
RACF
The security administrator defines a user by creating a RACF user profile with an
ADDUSER command or alters the user profile with an ALTUSER command to make the
user a z/OS UNIX user.
SMS
System Managed Storage (SMS), which is part of the DFSMSdfp element of z/OS, can be
configured, whether you define the kernel in minimum mode or full function mode.
TSO/E
To make certain TSO/E commands (such as OEDIT, OBROWSE, and ISHELL) and some
shipped REXX execs available to users, concatenate the following target libraries to the
appropriate ISPF data definition names (ddnames). The following data sets are for the
English panels, messages, and tables:
SYS1.SBPXPENU concatenated to ISPPLIB
SYS1.SBPXMENU concatenated to ISPMLIB
SYS1.SBPXTENU concatenated to ISPTLIB
SYS1.SBPXEXEC concatenated to SYSEXEC or SYSPROC
Customization:
RACF
TSO/E
RACF profiles with commands
ALTUSER, ADDUSER
TSO/E commands and REXX execs
Make available to users

80
ABCs of z/OS System Programming: Volume 9
3.6 z/OS UNIX security
Figure 3-6 z/OS UNIX security products
Security products
To provide data and system security, the security administrator and security auditor need to
set up and maintain security with the tasks used by z/OS UNIX.
z/OS UNIX provides security mechanisms that work with the security offered by the z/OS
system. A security product is required, either RACF or an equivalent security product. This
chapter assumes that you are using RACF. If you are using an equivalent security product,
you should refer to that product's documentation. If you do not have a security product, you
must write SAF exits to simulate all of the functions.
RACF stores z/OS UNIX data in OMVS segments, but Solution Developer products such as
CA-ACF2 and CA-Top Secret have also implemented solutions to seamlessly support z/OS
UNIX.
Security product required:
RACF
CA - ACF2
CA - Top Secret
SAF Exits - security product simulation

Chapter 3. z/OS UNIX System Services preinstallation requirements
81
3.7 RACF definitions
Figure 3-7 RACF definitions for z/OS UNIX
Providing security with RACF
The RACF component of the Security Server authenticates users and verifies whether they
are allowed to access certain resources. An equivalent security product can be used to do
those tasks.
To provide data and system security, the security administrator and security auditor need to
set up and maintain security. z/OS UNIX provides security mechanisms that work with the
security offered by the z/OS system. A security product is required, either RACF or an
equivalent security product. It is assumed that you are using RACF. If you are using an
equivalent security product, you should refer to that product's documentation. If you do not
have a security product, you must write SAF exits to simulate all of the functions.
z/OS UNIX provides security mechanisms that work with the security offered by the z/OS
system. Before you can install and debug z/OS UNIX System Services, you need to have
access to z/OS UNIX System Services data sets and members that are named in directories
and files. RACF and other security-related products allow access to the z/OS UNIX
environment. This access can be allowed without being a TSO/E user.
Permission bits
RACF uses permission bit settings for files and directories to determine if a request for
access to the file or directory can be granted.
R
A
C
F
O
M
V
S
RACF
OMVS
Segment
UIDs - GIDs
RACF database
User profile
OMVS segment
Permission
Bits
Control access to files and
directories

82
ABCs of z/OS System Programming: Volume 9
Create an OMVS segment
If your user ID should have access to z/OS UNIX, your security administrator has to specify
the home directory, the shell program, and a UID in the OMVS segment. In addition, the
administrator has to provide a group ID (GID) for any RACF group the user is connected to. If
this is done you should be able to access the UNIX shell or work with the ISPF-driven
ISHELL. The decision whether you will be able to access directories or files will be made by
UNIX security.
OMVS segments can be created using the RACF commands ADDUSER and ALTUSER.
Create user IDs for z/OS UNIX
In addition, your RACF administrator has to provide a user ID that is assigned to the OMVS
and BPXOINIT address spaces (Started Procedure). This user ID needs only to have an
OMVS segment and should be connected to a RACF group with a GID.

Chapter 3. z/OS UNIX System Services preinstallation requirements
83
3.8 RACF OMVS segments
Figure 3-8 z/OS UNIX RACF OMVS segments
User profiles with OMVS segments
All users and programs that need access to z/OS UNIX System Services must have a RACF
user profile defined, with an OMVS segment which has at least a UID specified. A user
without a UID cannot access z/OS UNIX.
RACF user profile
The RACF user profile has a segment called OMVS for z/OS UNIX support. A user ID must
have an OMVS segment defined in order to use z/OS UNIX System Services, for example,
access the ISHELL or the shell. This segment has three fields, as follows:
UID A number from 0 to 2147483647 that identifies a z/OS UNIX user. A z/OS UNIX
user must have a UID defined.
Home The name of a directory in the file system. This directory is called the home
directory. This field is optional.
Program The name of a program. This is the program that will be started for the user
when the user begins a z/OS UNIX session. Usually this is the program name
for the z/OS UNIX shell. This field is optional.
Note: It is possible for multiple users to have the same UID number specified. However,
this is not recommended.
Groupid
Superior
Group
Connected Users
PROG2
PROGR SMITH
WHITE
...
...
Group profile (no OMVS segment)
Groupid
Superior
Group
Connected Users
OMVS
GID
25
PROG1
PROGR
SMITHBROWN
...
...
Group profile
Userid
Default
Group
Connect Groups
TSO
DFP
OMVS
UID Home
Program
15/u/smith/bin/sh
SMITH
PROG1
PROG1
PROG2
...
...
User profile

84
ABCs of z/OS System Programming: Volume 9
RACF group profile
The RACF group also has a segment called OMVS to define z/OS UNIX groups. It contains
only one field, as follows:
GID A number from 0 to 2147483647 which identifies a z/OS UNIX group.
The home directory is the current directory when a user invokes z/OS UNIX. During z/OS
UNIX processing this can be changed temporarily by using the cd (change directory) shell
command. The command will not change the value in the RACF profile. The directory
specified as home directory in the RACF profile must exist (be pre-allocated) before a user
can invoke z/OS UNIX. If a home directory is not specified in RACF, the root (/) directory will
be used as default.
The example in Figure 3-8 shows a user profile for TSO/E user ID SMITH which is connected
to two groups, PROG1 and PROG2. SMITH is defined as a z/OS UNIX user because he has
a UID specified. His home directory is /u/smith and he will get into the shell when he issues
the OMVS command because the name of the shell, /bin/sh is specified as program name.
The program name in the OMVS segment specifies the name of the first program to start
when z/OS UNIX is invoked. Usually this is the name of the z/OS UNIX shell.

Chapter 3. z/OS UNIX System Services preinstallation requirements
85
3.9 OMVS segment fields
Figure 3-9 Fields in the OMVS segment
Controlling resources for users
You can control the amount of resources consumed by certain z/OS UNIX users by setting
individual limits for these users. The resource limits for the majority of z/OS UNIX users are
specified in the BPXPRMxx PARMLIB member. These limits apply to all users except those
with UID(0), which indicates superuser authority. Instead of assigning superuser authority to
application servers and other users so they can exceed BPXPRMxx limits, you can
individually set higher limits for these users. Setting user limits allows you to minimize the
number of assignments of superuser authority at your installation and reduces your security
risk.
Setting limits for z/OS UNIX users
Specify limits for z/OS UNIX users by choosing options on the ADDUSER or ALTUSER
commands. The limits are stored in the OMVS segment of the user profile. You can set the
following limits in the OMVS user segment:
ASSIZEMAX MAXASSIZE is the maximum region size (in bytes) for an address
space. You can set a system-wide limit in BPXPRMxx and then set
higher limits for individual users. Use the RACF ADDUSER or ALTUSER
command to specify the ASSIZEMAX limit on a per-user basis as
follows:
ALTUSER userid OMVS(ASSIZEMAX(nnnn)
OMVS Segment
UID= 0000000000
HOME= /
PROGRAM= /bin/sh
- - - - - - - - - - - - - - - - - - - -
CPUTIMEMAX= NONE
ASSIZEMAX= NONE
FILEPROCMAX= NONE
PROCUSERMAX= NONE
THREADSMAX= NONE
MMAPAREAMAX= NONE
MEMLIMIT | NOMEMLIMIT
SHMEMAX | NOSHMEMAX

86
ABCs of z/OS System Programming: Volume 9
CPUTIMEMAX MAXCPUTIME is the time limit (in seconds) for processes that were
created by rlogind and other daemons. You can set a system-wide limit
in BPXPRMxx and then set higher limits for individual users. Use the
RACF ADDUSER or ALTUSER command to specify the CPUTIMEMAX
limit on a per user basis as follows:
ALTUSER userid OMVS(CPUTIMEMAX(nnnn))
FILEPROCMAX Use MAXFILEPROC to determine the number of character-special files,
/dev/fdxx, that a single process can have open concurrently. You can
also limit the amount of system resources available to a single user
process. You can set a system-wide limit in BPXPRMxx and then set
higher limits for individual users. Use the RACF ADDUSER or ALTUSER
command to specify the FILEPROCMAX limit on a per user basis as
follows:
ALTUSER userid OMVS(FILEPROCMAX(nnnn))
MMAPAREAMAX For MAXMMAPAREA, you can set a system-wide limit in BPXPRMxx
and then set higher limits for individual users. Use the RACF ADDUSER
or ALTUSER command to specify the MMAPAREAMAX limit on a per
user basis as follows:
ALTUSER userid OMVS(MMAPAREAMAX(nnnn))
PROCUSERMAX You can set a system-wide limit in BPXPRMxx and then set higher limits
for individual users. Use the RACF ADDUSER or ALTUSER command
to specify the PROCUSERMAX limit on a per-user basis as follows:
ALTUSER userid OMVS(PROCUSERMAX(nnnn))
THREADSMAX MAXTHREADS is the maximum number of threads that a single process
can have active concurrently. If an application needs to create more than
the recommended maximum in SAMPLIB, it must minimize storage
allocated below the 16M line by specifying C run-time options. You can
set a system-wide limit in BPXPRMxx and then set higher limits for
individual users by using the RACF ADDUSER or ALTUSER command
to specify the THREADSMAX limit on a per user basis as follows:
ALTUSER userid OMVS(THREADSMAX(nnnn))
SHMEMAX SHMEMMAX(shared-memory-size) specifies the maximum number of
bytes of shared memory that can be allocated by the user. The
shared-memory-size value must be numeric 1 - 16777215, followed by
the letter M, G, T, or P. The M, G, T or P letter indicates the multiplier to
be used. The maximum value is 16383P.
MEMLIMIT MEMLIMIT(nonshared-memory-size) specifies the maximum number of
bytes of nonshared memory that can be allocated by the user. The
nonshared-memory-size value must be numeric 0 - 16777215, followed
by the letter M, G, T, or P. The M, G, T or P letter indicates the multiplier
to be used. The maximum value is 16383P.

Chapter 3. z/OS UNIX System Services preinstallation requirements
87
3.10 UNIX security
Figure 3-10 Security on UNIX platforms
Security on z/OS UNIX
UNIX systems incorporate a concept of users and groups similar to that of RACF. A user
UNIX identifier (or UID) is a number between 0 and some large number that varies between
brands of UNIX. User numbers do not have to be unique and it is possible (though not
recommended) for several users to share the same UID, and even be logged on at the same
time. UNIX sees these users as being the same entities and they receive the same levels of
authorization. A user with UID=0 is what's called a superuser (ROOT on some brands of
UNIX). The superuser has unlimited authority within a UNIX environment. For obvious
reasons, UID=0 needs to be strictly controlled.
Users are all related to a group. Groups allow authority to be controlled in a more economical
way, in that giving access to a group is a lot easier than giving access to a couple of hundred
users. A group identifier (or GID) is a number between 0 and some large number that varies
between brands of UNIX. Any number of users can share the same GID.
UID and GID numbers
pax and tar are UNIX utilities that perform functions such as PKZIP and DFSMSdss. The
z/OS implementation of UNIX allows UID and GID numbers up to 2,147,483,647. The pax
protocol supports UIDs and GIDs up to 8 octal digits. The largest value supported is
77777777 octal or 16 M decimal. To allow the use of pax and tar, keep the UIDs and GIDs
below this value. It is recommended that the maximum number used should be no more than
77,777,777.
UID = user identifier
Number in range 0 - 2,147,483,647
But.... 0 - 16,777,215 due to
pax
protocol
0 = Superuser (Root)
GID = group identifier
Number in range 0 - 2,147,483,647
But.... 0 - 16,777,215 due to pax protocol
/etc/passwd - (Not used by z/OS UNIX)
/etc/group - (Not used by z/OS UNIX)

88
ABCs of z/OS System Programming: Volume 9
Security on other UNIX platforms
The /etc/passwd file contains basic user attributes. This is an ASCII file that contains an entry
for each user. Each entry defines the basic attributes applied to a user. When using the
mkuser command to add a user to your system, the command updates the /etc/passwd file.
An entry in the /etc/passwd file has the following form:
Name:Password: UserID:PrincipleGroup:Gecos: HomeDirectory:Shell
Attributes in an entry are separated by a : (colon). For this reason, you should not use a :
(colon) in any attribute. The attributes are defined as follows:
Name Specifies the user's login name. The user name must be a unique
string of 8 bytes or less. There are a number of restrictions on naming
users. See the mkuser command for more information.
Password Contains an * (asterisk) indicating an invalid password or an !
(exclamation mark) indicating that the password is in the
/etc/security/passwd file. Under normal conditions, the field contains
an !. If the field has an * and a password is required for user
authentication, the user cannot log in.
UserID Specifies the user's unique numeric ID. This ID is used for
discretionary access control. The value is a unique decimal integer.
PrincipleGroup Specifies the user's principal group ID. This must be the numeric ID of
a group in the user database or a group defined by a network
information service. The value is a unique decimal integer.
Gecos Specifies general information about the user that is not needed by the
system, such as an office or phone number. The value is a character
string. The Gecos field cannot contain a colon.
HomeDirectory Specifies the full path name of the user's home directory. If the user
does not have a defined home directory, the home directory of the
guest user is used. The value is a character string.
Shell Specifies the initial program or shell that is executed after a user
invokes the login or su command. If a user does not have a defined
shell, /usr/bin/sh, the system shell, is used. The value is a character
string that may contain arguments to pass to the initial program.
The /etc/group file contains basic group attributes. This is an ASCII file that contains records
for system groups. Each record appears on a single line and has the following format:
Name:Password:ID:User1,User2,...,Usern
Each attribute must be separated by a colon. Records are separated by new-line characters.
The attributes in a record have the following values:
Name Specifies a group name that is unique on the system. The name is a
string of 8 bytes or less. See the mkgroup command for information on
the restrictions for naming groups.
Password Not used. Group administrators are provided instead of group
passwords. See the /etc/security/group file for more information.
ID Specifies the group ID. The value is a unique decimal integer string.
User1,User2,...,Usern Identifies a list of one or more users. Separate group member names
with commas. Each user must already be defined in the local
database configuration files.

Chapter 3. z/OS UNIX System Services preinstallation requirements
89
3.11 z/OS UNIX superuser
Figure 3-11 z/OS UNIX and superusers
Defining superusers
z/OS UNIX has no predefined numbering scheme for UIDs and GIDs, with the exception of
UID=0. UID=0 is a superuser (also known as ROOT on other UNIX platforms). While some
functions require a UID of 0, in most cases you can choose among the three ways. When
choosing among them, try to minimize the number of “human” user IDs (as opposed to
started procedures) set up with UID(0) superuser authority. To summarize the choices, UID(0)
gives you access to all UNIX functions and resources, as is true for all UNIX systems.
However, in z/OS, RACF allows certain users to perform specific privileged functions without
being defined as UID(0). BPX.SUPERUSER allows you to request that you be given such
access, but you do not have the access unless you make the request. And, the UNIXPRIV
class allows you to do other privileged functions, such as mounting a file system. Both these
definitions are similar to having UID(0) in that, before RACF grants access to a system
resource or use of it, the system checks these definitions.
Defined in the user profile
A superuser is a user with a UID of 0 and this UID is in the RACF profile of the user. A
superuser can be a started procedure with a trusted or privileged attribute defined in the
RACF STARTED Class or added to the RACF Started Procedures Table. The procedure must
have a UID. However, when a started procedure is trusted or privileged, RACF does not base
authority checking on the UID value; the UID can have any value.
User having a
UID(0)
Specified in
RACF user profile

Can

access any file or directory
Required for many of the customization and
administration tasks
Required to perform some functions like MOUNT
Superusers can be defined using the following:
BPX.SUPERUSER RACF profiles
UNIXPRIV class (RACF)

90
ABCs of z/OS System Programming: Volume 9
Superuser authority
A superuser can do the following:
Pass all security checks, so that the superuser can access any file in the file system.
Perform the mount function.
Change identity from one UID to another.
Manage processes.
Have an unlimited number of processes running concurrently. For a started procedure, this
is true only if it has a UID of 0. It is not true for a trusted or privileged process with a
different UID.
Change identity from one UID to another.
Use setrlimit to increase any of the system limits for a process.
BPX.SUPERUSER profiles
Using the BPX.SUPERUSER resource in the FACILITY class is another way for users to get
the authority to do most of the tasks that require superuser authority.
UNIXPRIV class
You can define profiles in the UNIXPRIV class to grant RACF authorization for certain z/OS
UNIX privileges. By defining profiles in the UNIXPRIV class, you can specifically grant certain
superuser privileges with a high degree of granularity to users who do not have superuser
authority. This allows you to minimize the number of assignments of superuser authority at
your installation and reduces your security risk.

Chapter 3. z/OS UNIX System Services preinstallation requirements
91
3.12 RACF commands and user IDs
Figure 3-12 The RACF commands used to define users and groups
Defining user IDs
For our UNIX System Service installation we should provide the following setup in RACF:
Provide a GID for our default RACF group.
Define the OMVS RACF segment.
Define the OMVSKERN user ID and group.
Define the OMVS and BPXOINIT cataloged procedures.
RACF commands
The following RACF commands can be used to fulfill the UNIX RACF prerequisites:
ALTGROUP SYS1 OMVS(GID(0))
ALTUSER KORN OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
ADDGROUP OMVSGRP OMVS(GID(1))
ADDUSER OMVSKERN DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
PASSWORD(ONE6PACK).
RDEFINE STARTED OMVS.* STDATA(USER(OMVSKERN) GROUP(OMVSGRP) TRUSTED(YES))
RDEFINE STARTED BPXOINIT.* STDATA(USER(OMVSKERN) GROUP(OMVSGRP) TRUSTED(NO))
ALTUSER
ADDUSER
ADDGROUP
ALTGROUP
OMVSKERN
OMVSGRP
T
T
S
S
O
O
(User IDs)
(RACF
Commands)
ALTGROUP SYS1 OMVS(GID(0))
ALTUSER KORN OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
ADDGROUP OMVSGRP OMVS(GID(1))
ADDUSER OMVSKERN DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
PASSWORD(ONE6PACK).
RDEFINE STARTED OMVS.* STDATA(USER(OMVSKERN) GROUP(OMVSGRP) TRUSTED(YES))
RDEFINE STARTED BPXOINIT.* STDATA(USER(OMVSKERN) GROUP(OMVSGRP) TRUSTED(NO))

92
ABCs of z/OS System Programming: Volume 9
3.13 RACF commands to define groups
Figure 3-13 RACF commands used to define z/OS UNIX groups
RACF commands for defining groups
The ALTGROUP, ADDGROUP, and LISTGRP commands have keywords for administering
the OMVS segment.
Use ALTGROUP (ALG) to modify an existing RACF group, with or without an OMVS
segment. The OMVS segment can be added, modified, or deleted.
Use ADDGROUP (AG) to define a new RACF group, with or without an OMVS segment.
The OMVS keyword can be used to define this group as a z/OS UNIX group.
The LISTGRP (LG) command will display the OMVS segment if the OMVS keyword is
specified.
A z/OS UNIX group is a RACF group with an OMVS segment and a GID defined. Figure 3-13
shows examples of how to use the RACF commands to add, change or delete the OMVS
segment for a group.
Using NOGID removes a GID definition, and NOOMVS removes the OMVS segment.
A user can belong to (or be connected to) multiple groups. A z/OS UNIX user must belong to
at least one z/OS UNIX group. It is not necessary that all the groups a z/OS UNIX user
belongs to are defined as z/OS UNIX groups. Only the groups that are defined as z/OS UNIX
groups will be used for authorization checking in z/OS UNIX.
Add OMVS segment to existing group SYSADM:

ALTGROUP SYSADM OMVS(GID(0))
Define a new group PROG1:

ADDGROUP PROG1 OMVS(GID(25))
List the OMVS segment of group TTY:

LG TTY OMVS

Chapter 3. z/OS UNIX System Services preinstallation requirements
93
3.14 RACF commands to define users
Figure 3-14 RACF commands to define z/OS UNIX users
RACF commands for defining users
The RACF commands ALTUSER, ADDUSER, and LISTUSER have keywords for
administering the OMVS segment, as follows:
Use the ALTUSER (ALU) command to change the definitions for an existing TSO/E user
ID. An OMVS segment can be added, modified, or deleted.
Use the ADDUSER (AU) command to define a new TSO/E user ID with or without an
OMVS segment.
The LISTUSER (LU) command is used for listing the definitions for a TSO/E user ID.
When the OMVS keyword is specified, the values specified in the OMVS segment will also
be listed.
ADDUSER sets up a new user, whereas ALTUSER modifies an existing user. To remove a
specification in the OMVS segment, use the keywords NOUID (to remove UID), NOHOME (to
remove home directory definition), or NOPROGRAM (to remove program definition). The
NOOMVS keyword will remove all the definitions in the OMVS segment. The OMVS keyword
must be used on the LISTUSER command if you want the OMVS segment definitions to be
displayed.
The z/OS UNIX ISPF shell (ISHELL) provides some menus for administering user IDs.
However, before a user can use the ISHELL, he must have a user ID with a UID defined (and
a group with a GID defined). This must be done using the RACF commands.
Note: The values shown are case-sensitive in the definitions for HOME and PROGRAM.
Add OMVS segment to existing user NEILOC:
ALTUSER NEILOC +
OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
Define a new user SMITH:
ADDUSER SMITH +
OMVS(UID(15) HOME('/u/smith')PROGRAM('/bin/sh'))
List the OMVS segment of user SMITH:
LU SMITH OMVS
Note: UID=0 is a Superuser

94
ABCs of z/OS System Programming: Volume 9
3.15 LU and LG command examples
Figure 3-15 RACF commands to display z/OS UNIX OMVS segments
List user and group commands
Specifying the NORACF option stops the LU and LG commands from displaying general
information. You only see the OMVS segment information.
Note that users are only allowed to display their OMVS segments if RACF field-level access
has been enabled.
lu smith omvs noracf

USER=SMITH
OMVS INFORMATION
----------------
UID= 0000000015
HOME= /u/smith
PROGRAM= /bin/sh
CPUTIMEMAX= NONE
ASSIZEMAX= NONE
FILEPROCMAX= NONE
PROCUSERMAX= NONE
THREADSMAX= NONE
MMAPAREAMAX= NONE
lg prog1 omvs noracf

INFORMATION FOR GROUP PROG1
OMVS INFORMATION
----------------
GID= 0000000025

Chapter 3. z/OS UNIX System Services preinstallation requirements
95
3.16 Define a terminal group name
Figure 3-16 Defining a terminal group name
Terminal group name
Certain shell commands, such as mesg, talk, and write require pseudoterminals to have a
group name of TTY. When a user logs in, or issues the OMVS command from TSO/E, the
group name associated with these terminals is changed to TTY. As part of your installation,
you have to define the group TTY.
Pseudoterminal files
Pseudoterminals (pseudo-TTYs) are used by users and applications to gain access to the
shell. A pseudo_TTY is a pair of character special files, a
master file
and a corresponding
slave file
. The master file is used by a networking application such as OMVS or rlogin. The
corresponding slave file is used by the shell or the user's process to read and write terminal
data.
When a user enters the TSO/E OMVS command or logs in using rlogin or telnet to initialize
a shell, the system selects an available pair of these files. The pair represents the connection.
The maximum number of pairs is 10000.
Define a RACF group for pseudoterminals
Group name - TTY (default)
Group id (GID)
ADDGROUP TTY OMVS(GID(2))
TTY group is used by shell programs
Shell users are assigned group TTY

96
ABCs of z/OS System Programming: Volume 9
3.17 TSO/E support
Figure 3-17 TSO/E component used with z/OS UNIX
Using TSO/E for z/OS UNIX
One benefit to users of z/OS UNIX System Services is the z/OS UNIX System Services shell,
which is a command processor that you use to:
Invoke shell commands or utilities that request services from the system (similar to
TSO/E).
Write shell scripts using the shell programming language (similar to REXX).
Run shell scripts and C-language programs interactively in the foreground, in the
background, or in batch (again, similar to REXX).
Once z/OS UNIX is installed, the shell can be invoked through the TSO/E command OMVS.
Like the OBROWSE, OEDIT, and ISHELL commands, the OMVS command can also be
added to an ISPF selection panel, or entered as a TSO/E command.
The z/OS UNIX ISPF Shell or ISHELL is an ISPF panel interface that you can use instead of
TSO/E commands or shell commands to perform tasks against z/OS UNIX user IDs and
HFSs.
If you are more comfortable using the ISPF editor and ISPF pull-down menus, the ISHELL is
the tool for you.
OMVS.ROOT
Data Set
TSO OMVS
command
RACF
Data
Base

Chapter 3. z/OS UNIX System Services preinstallation requirements
97
3.18 User access to TSO/E commands
Figure 3-18 Using TSO/E commands with z/OS UNIX
Customizing the TSO/E environment for z/OS UNIX
In order to make the TSO/E commands OEDIT, OBROWSE, and ISHELL (ISPF Shell)
available to users, the following data sets should be concatenated to the appropriate ISPF DD
names (in the TSO/E logon procedure, or CLIST/REXX EXEC if used):
SYS1.SBPXPENU (concatenated to ISPPLIB)
SYS1.SBPXMENU (concatenated to ISPMLIB)
SYS1.SBPXTENU (concatenated to ISPTLIB)
SYS1.SBPXEXEC (concatenated to SYSEXEC or SYSPROC)
These TSO/E commands can be invoked from a TSO/E command line, but it is more
convenient for users if they are added as an option to an ISPF menu. They can be added to
the ISPF/PDF primary option menu (ISR@PRIM) or any other menu the installation prefers to
use.
TSO/E users need to be defined with an OMVS segment in RACF before they can use the
ISHELL, OEDIT, or OBROWSE commands.
ISHELL
OEDIT
OBROWSE
TSO Commands
TSO Logon Procedures
ISPPLIB
ISPMLIB
ISPTLIB
SYSEXEC or
SYSPROC
SYS1.SBPXPENU
SYS1.SBPXMENU
SYS1.SBPXTENU
SYS1.SBPXEXEC
ISPF menu
ISR@PRIM
0 ...
1 ..
2 ...

98
ABCs of z/OS System Programming: Volume 9

© Copyright IBM Corp. 2011. All rights reserved.
99
Chapter 4.
z/OS UNIX System Services
installation
This chapter provides information about installing z/OS UNIX System Services, and how to
avoid or fix installation problems. It explains how to:
Install z/OS UNIX System Services
Allocate HFS data sets
Mount HFS data sets
Restore file systems
4

100
ABCs of z/OS System Programming: Volume 9
4.1 z/OS UNIX PARMLIB - PROCLIB members
Figure 4-1 PARMLIB and PROCLIB members for z/OS UNIX
Customization of SYS1.PARMLIB
SYS1.PARMLIB has several members in which some customization needs to be done. z/OS
UNIX requires definitions in one or more BPXPRMxx members that are defined in the
IEASYSxx member.
Use the PROGxx member to define language environment run-time libraries.
The COFVLFxx member is used for VLF definitions to cache UIDs and GIDs for performance
when RACF does authorization checks for access to files and directories. The COMMNDxx
member can be used to specify the start command for VLF.
Customization of SYS1.PROCLIB
The following procedures are required in SYS1.PROCLIB for the z/OS UNIX address spaces:
OMVS - The main z/OS UNIX address space
BPXOINIT - The z/OS UNIX initialization address space
BPXAS - For address spaces for all UNIX processes
SYS1.PARMLIB
One or more BPXPRMxx members
IEASYSxx member to define BPXPRMxx members
PROGxx member to define language environment
COFVLFxx member for VLF definitions
COMMNDxx member for start of VLF
SYS1.PROCLIB
Procedures required for z/OS UNIX address spaces
OMVS - Main z/OS UNIX address space
BPXOINIT - z/OS UNIX initilaization address space
BPXAS - Address spaces for all UNIX processes

Chapter 4. z/OS UNIX System Services installation
101
4.2 IEASYSxx PARMLIB member
Figure 4-2 PARMLIB settings needed to start z/OS UNIX
PARMLIB definitions to start z/OS UNIX
The initial PARMLIB settings for the z/OS UNIX kernel are pointed to by the OMVS parameter
in the IEASYSxx PARMLIB member. The OMVS parameter in the IEASYSxx PARMLIB
member lets you specify one or more BPXPRMxx PARMLIB members to be used to specify
the initial PARMLIB settings for the kernel. If you do not specify the OMVS parameter, or if you
specify OMVS=DEFAULT, the kernel is started in a minimum configuration mode with all
BPXPRMxx PARMLIB statements taking their default values.
OMVS may also be left out or coded as DEFAULT. This allows the z/OS UNIX kernel to start
in a minimum configuration. All BPXPRMxx values will take their default values and a
temporary root file system will be set up in memory.
Activation of kernel services is available in two modes:
Minimum mode
Full-function mode
You can set up kernel services in either minimum mode or full function mode. If you want to
use any z/OS UNIX service, TCP/IP, or other functions that require the kernel services, you
will need to use full function mode; otherwise, you can use minimum mode. In order to apply
service to the HFS, you need at least one system that can run in full function mode.
Note: The start and stop commands for the z/OS UNIX kernel are no longer supported.
OMVS=xx
OMVS=(xx,yy,...)
OMVS=DEFAULT
Levels of operation
Minimum mode
Full-function mode
IEASYSxx
SYS1.PROCLIB
OMVS
BPXOINIT
BPXAS
SYS1.PARMLIB
BPXPRMxx
BPXPRMyy

102
ABCs of z/OS System Programming: Volume 9
4.3 z/OS UNIX minimum mode
Figure 4-3 z/OS UNIX running in minimum mode
Using minimum mode
Minimum mode is intended for installations that do not intend to use z/OS UNIX System
Services, but which allow the IPL process to complete. In this mode many services are
available to programs. Some that require further customization, such as a fork(), will fail.
OMVS=DEFAULT
If you do not specify OMVS= in the IEASYSxx PARMLIB member or if you specify
OMVS=DEFAULT, then kernel services start up in minimum mode when the system is IPLed.
This mode is intended for installations that do not plan to use the kernel services.
In minimum mode:
Many services are available, but some functions such as TCP/IP sockets that require other
system customization may not work.
TCP/IP sockets (AF_INET) are not available.
A temporary file system (TFS) is used. A TFS is an in-storage file system, hence no
physical DASD data set needs to exist or be mounted.
In minimum mode, the kernel cannot support some functions, such as the z/OS shell and
TCP/IP.
z/OS UNIX Address Spaces
SYS1.PARMLIB
OMVS=DEFAULT
SYS1.PROCLIB
O
M
V
S
B
P
X
O
I
N
I
T
TFS
. . .
PID=1
IEASYSxx
BPXPRM00
OMVS
BPXOINIT
ZFS
In Storage
HFS

Chapter 4. z/OS UNIX System Services installation
103
Temporary file system (TFS)
In minimum mode, a temporary file system named SYSROOT is used as the root file system.
It is initialized and primed with a minimum set of files and directories. Any data written to this
file system is not written to DASD.
The temporary file system does not have any executables; that is, the shell will not be
available. Do not install z/OS UNIX System Services Application Services in the TFS,
because data will not be written to DASD.
A temporary file system (kept in memory) is created for the root and the required directories
(/bin, /etc, /tmp, /dev, and /dev/null) are built. There are no executables in this file system.

104
ABCs of z/OS System Programming: Volume 9
4.4 Minimum mode: TFS
Figure 4-4 The TFS in minimum mode
TFS in minimum mode
A temporary file system is an in-memory file system which delivers high-speed I/O. If the
kernel is started in minimum setup mode, the TFS is automatically mounted. The system is in
minimum mode when:
OMVS=DEFAULT.
There is no OMVS statement in the IEASYSxx parmlib member and no BPXPRMxx
parmlib member.
Files and directories
The temporary file system is used as the root file system. It is initialized and primed with a
minimum set of files and directories, specifically as follows:
/ (root directory)
/bin directory
/etc directory
/tmp directory
/dev directory
/dev/null file
TFS usage
There are no executables in the temporary file system (that is, you will not find the Shell and
Utilities). Do not attempt to install z/OS UNIX System Services Application Services in the
TFS, since no data will be written to DASD. Because the TFS is a temporary file system,
Root-HFS
Minimum mode
/
bin
etc
tmp
dev

Chapter 4. z/OS UNIX System Services installation
105
unmounting it causes all data stored in the file system to be discarded. If, after an unmount,
you mount another TFS, that file system has only a dot (.) and a dot-dot (..) and nothing else.
Any data written to this file system is not written to DASD.
The TFS is automatically mounted if the kernel is started in minimum mode. In this
environment, the TFS is the in-storage file system and defaults to the root file system.
Because it is an in-storage file system, the TFS delivers high-speed I/O.
If the TFS is to be used in other situations, it is made available by mounting. You can mount it
with a MOUNT or ROOT statement in the BPXPRMxx member or by means of one of the
supported mount commands.
If you are using kernel services in full function mode, you may want to mount a TFS over /tmp.
If you do, it can be used as a high-speed file system for temporary files. However, you cannot
recover vi files if the system goes down because vi writes temporary files to TMPDIR (/tmp by
default). To recover these files, you can use the exrecover command, which automatically
runs from /etc/rc.

106
ABCs of z/OS System Programming: Volume 9
4.5 z/OS UNIX full-function mode
Figure 4-5 z/OS UNIX full function mode
Using full-function mode
Full-function mode is started at IPL time when the OMVS parameter in the IEASYSxx
PARMLIB member points to one or more BPXPRMxx parmlib members.
There must be a root HFS built and defined in BPXPRMxx for OMVS to initialize correctly, and
SMS, WLM, and RACF customization should be completed.
BPXPRMnn
STARTUP_PROC is a 1 to 8 character name of a started procedure JCL that initializes the
z/OS UNIX kernel. The default is OMVS.
The ROOT statement defines and mounts the root file system. In this example:
HFS is the TYPE of the file system.
OMVS.ROOT is the file system, which is the name of an already defined HFS data set.
The root file system has a default of read/write mode.
If an active BPXPRMxx PARMLIB member specifies FILESYTYPE TYPE(HFS), or FILESYSTYPE
TYPE(ZFS), then the kernel services start up in full-function mode when the system is IPLed.
To use the full function, you need to:
Set up BPXPRMxx PARMLIB definitions
Set up DFSMS
Set up the hierarchical file systems
SYS1.PARMLIB
OMVS=00
O
M
V
S
B
P
X
O
I
N
I
T
(Kernel)
PID=1
IEASYSxx
BPXPRM00
SYS1.PROCLIB
OMVS
BPXOINIT
BPXAS
ZFS
STARTUP_PROC=OMVS
...
...
ROOT FILESYSTEM('OMVS.ROOT')
TYPE(HFS)
F
F
F
F F
/
OMVS.ROOT
OMVS.ROOT
HFS
zFS
z/OS UNIX Address Spaces
BPXAS

Chapter 4. z/OS UNIX System Services installation
107

Set up the security product definitions for z/OS UNIX

Set up the users' access and their individual file systems
DFSMS manages the HFS data sets that contain the file systems. zFS data sets are VSAM
linear data sets defined in aggregates.
BPXOINIT address space
BPXOINIT is the started procedure that runs the initialization process. BPXOINIT is also the
jobname of the initialization process. BPXOINIT is shipped in SYS1.PROCLIB.
At system IPL time, kernel services are started automatically. If the OMVS parameter in the
IEASYSxx PARMLIB parameter is not specified, the kernel services are started in minimum
mode. If the OMVS parameter specifies one or more BPXPRMxx PARMLIB members, they
are all used to configure the kernel services when the system is IPLed.
The BPXOINIT address space has two categories of functions:
1.It behaves as PID(1) of a typical UNIX system. This is the parent of /etc/rc, and it inherits
orphaned children so that their processes get cleaned up using normal code in the kernel.
This task is also the parent of any MVS address space that is dubbed and not created by
fork or spawn. Therefore, TSO/E commands, batch jobs, and so forth have a parent PID
of 1.
2.Certain functions that the kernel performs need to be able to make normal kernel calls.
This address space is used for these activities, for example, mmap() and user ID alias
processing.
zFS address space
zFS runs as a z/OS UNIX colony address space. There must be an entry in a BPXPRMxx
parmlib member for ZFS and the ZFS PROC must be available. zFS is started by z/OS UNIX
based on the FILESYSTYPE statement for ZFS in the BPXPRMxx parmlib member.
zFS can be started at IPL if the BPXPRMxx parmlib member is in the IEASYSxx parmlib
member's OMVS=(xx,yy) list. It can also be started later by using the SETOMVS RESET=(xx)
operator command.
Note:
APAR OW35441 now gives you the ability to allocate PDSE and HFS data sets on
unmanaged (non-SMS) volumes, if running DFSMS 1.4 or DFSMS 1.5.

108
ABCs of z/OS System Programming: Volume 9
4.6 z/OS HFS root
Figure 4-6 z/OS UNIX root install using ServerPac
ServerPac jobs
The z/OS ServerPac provides two jobs to complete the installation of the root HFS. They
create a single HFS data set structure that contains the following:

The root directory.

All z/OS-related products placed into the ServerPac order that require z/OS UNIX System
Services.
ALLOCDS job
The ALLOCDS job allocates and catalogs your new target system data sets. For z/OS orders,
this job also allocates the couple data sets. Many of these data sets have unique
considerations for serialization, availability, security, backup and recovery. For these
considerations, see the planning and implementation books for the products you are
installing. If you are installing your order on SMS-managed target system volumes, you likely
performed SMS setup work earlier in the installation dialog, such as defining storage classes.
RESTFS job
The restore of the archive file is directed to the Install Directory on the driving system. Earlier
in the installation process, you specified the Install Directory variable (FA00PQ04) during the
Define Installation Variables function of the dialog. By default, the Install Directory is /Service.
This value cannot be blank (the job will fail). If you specified a directory other than /Service,
ensure that the name you use does not exceed 20 characters in length. In a multilevel
directory path, the lowest level from the root is automatically created. Higher directories are
Single HFS structure containing:
Root directory
All z/OS related products
Simplifies installation and management of HFS
Two jobs to complete installation - ServerPac
ALLOCDS - Allocates HFS data sets
RESTFS - Restores the root file system - and -
mounts new root and additional file systems
RESTFS job
Requires submitting user ID to be superuser
BPX.SUPERUSER profile - Effective UID is 0
BPX.FILEATTR.APF - BPX.FILEATTR.PROGCTL

Chapter 4. z/OS UNIX System Services installation
109
not created. If your driving system's UNIX file system is mounted read-only, the specified
directory must already exist.
Understand that the target system's UNIX file system will be mounted to the Install directory
during the restore. As a result, the real names of the target system's UNIX file system data
sets must be unique in your environment.
This job mounts the new Root file system, and creates mount points for and mounts the
additional file systems. The BPXPRMFS member of CPAC.PARMLIB is updated to reflect the
file system structure.
The RESTFS job then restores those files into the Root file system.
RESTFS job requirements
The RESTFS job (and corresponding subsystem jobs) previously required the submitting
user ID to have UID(0) set in its OMVS segment. Access to the BPX.SUPERUSER profile in
the FACILITY class would provide the required authority without the need for UID(0). The
ServerPac now sets the effective UID to zero when the user ID has access to
BPX.SUPERUSER. This eliminates the need for the user to have to execute the restore of the
ServerPac to have UID(0) authority.
In addition, regardless of your installation method, the user ID must be permitted read access
to the FACILITY classes BPX.FILEATTR.APF and BPX.FILEATTR.PROGCTL (or
BPX.FILEATTR.* if you choose to use a generic facility for both facility classes).
In order to define these FACILITY classes, you can use the following commands (which are
also provided in SYS1.SAMPLIB):
RDEFINE FACILITY BPX.FILEATTR.APF UACC(NONE)
RDEFINE FACILITY BPX.FILEATTR.PROGCTL UACC(NONE)
SETROPTS CLASSACT(FACILITY)
SETROPTS RACLIST(FACILITY)
PERMIT BPX.FILEATTR.APF CLASS(FACILITY) ID(your_userid) ACCESS(READ)
PERMIT BPX.FILEATTR.PROGCTL CLASS(FACILITY) ID(your_userid) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
RESTFS is historically the number one source of service calls. To help eliminate some of the
problems, logic checking for common setup problems, new error messages, and more
specific error messages for better diagnosis have been added. RESTFS calls pax and
BPXISETS from within the exec to eliminate bypass checking and job elimination. A new
status message indicator shows progress of the job.
Note:
This does not affect the pax utility. You still required UID(0) in order to execute the
pax command outside of the ServerPac processing. This change is for ServerPac process-
ing only.

110
ABCs of z/OS System Programming: Volume 9
4.7 zFS with z/OS V1R7
Figure 4-7 zFS as the preferred file system
HFS migration to zFS
In z/OS V1R7, zFS is the preferred file system. Continued use of HFS will be discouraged.
Some effort is needed to migrate data from HFS file systems to zFS file systems. A migration
tool is implemented in z/OS V1R7 to help with migration as needed.
The HFS physical file system is stabilized and will be removed in a future z/OS release.
Migration tool BPXWH2Z
You can use the ISPF-based tool, BPXWH2Z, to migrate HFS file systems to zFS file
systems. It has a panel interface that enables you to alter the space allocation, placement,
SMS classes, and data set names. With this tool, you can:

Migrate HFS file systems (both mounted and unmounted) to zFS file systems. If the HFS
being migrated is mounted, the tool automatically unmounts it and then mounts the new
zFS file system on its current mount point.

Define zFS aggregates by default to be approximately the same size as the HFS. The new
allocation size can also be increased or decreased.

Have the migration run in a TSO foreground or a UNIX background.
zFS is the preferred file system
HFS may no longer be supported in future releases
and you will have to migrate the remaining HFS file
systems to zFS
Continued use of HFS will be discouraged
Effort is needed to migrate data from HFS file
systems to zFS file systems
Tools to help with migration are needed
BPXWH2Z tool - ISPF based in z/OS V1R7

Chapter 4. z/OS UNIX System Services installation
111
4.8 HFS or zFS data sets
Figure 4-8 Choose between HFS or zFS data sets
ServerPac changes in z/OS V1R5
Beginning with z/OS V1R5, you can type over the Data set type field with the new value, as
follows:
HFS
To change a zFS data set to an HFS data set
PDS
To change a PDSE data set to a PDS data set (if the PDSE was originally shipped
as a PDS data set)
PDSE
To change a PDS data set to a PDSE data set
ZFS
To change an HFS data set to a zFS data set
For data sets that are not eligible to be changed, the Data Set Type field is read-only. The
dialog does not, for example, allow you to change your order's PDSE data sets to PDS data
sets, because they contain members that cannot be loaded into a PDS.
CHANGE DSNTYPE command
You can use the CHANGE DSNTYPE command to convert your shipped order's data sets to
a different format:

PDS data sets to PDSE data sets.

PDSE data sets to PDS data sets. (This can be done only for data sets that were originally
PDS data sets.)

HFS data sets to zFS data sets.

zFS data sets to HFS data sets.
You can choose whether each filesystem is to be an
HFS or a zFS:
On the data set attributes panels
With the new CHange DSNTYPE command
New data set types in the installation dialog:
HFS, zFS, PDS, PDSE, SEQ, and VSAM
>---+--- CHANGE ---+---+--- DSNTYPE ---+---+--- PDS PDSE ---+---<
| | | | | |
+--- CH -------+ +--- TYPE ------+ +--- PDSE PDS ---+
| | | |
+--- T ---------+ +--- HFS ZFS ----+
| |
+--- ZFS HFS ----+

112
ABCs of z/OS System Programming: Volume 9
4.9 Set data set type
Figure 4-9 Choose a data set type
ServerPac changes in z/OS V1R5
The dialog provides you with a general-purpose view and change facility for working with
groups of data sets in your configuration. With this facility, you can:

Display groups of data sets in your configuration by various attributes

Make changes to all or some of the data sets in a displayed group

Save lists of groups you display
When you select a data set from a data set list panel through line command A, the panel
shown in Figure 4-9 is displayed. This panel shows the attributes of a specific data set.
You can then choose to make your file systems’ data sets either HFS or zFS.

Chapter 4. z/OS UNIX System Services installation
113
4.10 Choosing zFS
Figure 4-10 Selecting zFS as the data set type
ServerPac processing for zFS
Using a zFS in place of an HFS is transparent to applications. The same utilities work for both
(like pax). This support begins with z/OS V1R5.
But there are some differences, including the following:

An HFS data set is a non-VSAM data set, while a zFS lives in a VSAM Linear Data Set
(LDS).

zFS data sets must be preformatted with the IOEAGFMT program.

Because different programs are used by the system to process HFS and zFS files, a
different FILESYSTYPE statement is required in BPXPRMxx.

To point to the new FILESYSTYPE statement, a different operand is required on MOUNT.

Additional security system setup is needed to use zFSs.
Note:
Additional ECSA is also required to use zFS data sets.
HFS data set vs. VSAM LDS (aggregate) for zFS
zFS aggregate must be preformatted
Different FILESYSTYPEs used in BPXPRMxx
FILESYSTYPE TYPE(ZFS)
ENTRYPOINT(IOEFSCM) ASNAME(ZFS)
Different operands on MOUNT command
Different security system setup
CICS, DB2, and IMS ServerPacs assume that any
necessary zFS setup has been done

114
ABCs of z/OS System Programming: Volume 9
4.11 ServerPac changes if using zFS
Figure 4-11 ServerPac changes for zFS support
ServerPac jobs for zFS processing
All zFS data sets must be formatted with IOEAGFMT. A step to format them is added to the
ALLOCDS job when there is a zFS in the configuration. This support begins with z/OS V1R5.
The RACF setup for zFS is done unconditionally, on the assumption that, sooner or later, you
will want to use zFS.
RESTFS job
The RESTFS job adds a FILESYSTYPE statement for zFS to BPXPRMFS if needed. It is not
added unconditionally because there is a significant amount of free ECSA required to start
the zFS address space.
Before using a zFS, you should review your virtual storage map and make sure there is at
least 70 MB of ECSA available in addition to the ECSA normally required to run your system.
To determine the amount of available ECSA, you can use an RMF Virtual Storage Report that
covers your peak workload periods (vastly preferred!) or format the GDA control block in IPCS
and subtract GDA_ECSA_ALLOC from GDAECSAS to see how much ECSA is free at that
particular time (and guess at the likely variations).
ALLOCDS job formats zFS data sets you define
RACFDRV and RACFTGT Jobs in z/OS orders:
Add group for DFS setup
Add user ID for ZFS address space
RESTFS Job:
Uses appropriate TYPE on MOUNT commands
depending on filesystem type
Puts appropriate TYPE on MOUNT parameters in
BPXPRMFS
Add FILESYSTYPE for zFS to BPXPRMFS if needed

Chapter 4. z/OS UNIX System Services installation
115
4.12 UNIX utilities: TSO/E commands
Figure 4-12 TSO/E OGET and OPUT commands
TSO commands and utilities
You can use the OGET command to copy a z/OS UNIX system file to the following:

A member of an MVS partitioned data set (PDS or PDSE)

An MVS sequential data set

You can convert the data from code page 1047 to code page IBM-037 or ASCII while it is
being copied. Do not use the CONVERT option when copying files that contain doublebyte
data. This option is used for singlebyte data only, not for doublebyte data.
You can use the OPUT command to:

Copy a member of an MVS partitioned data set (PDS or PDSE) to a file.

Copy an MVS sequential data set to a file.

You can also convert the data from code page IBM-037 or ASCII to code page IBM-1047.
pathname
Specifies the pathname of the file that is being copied to a data set. This operand is required.
The pathname is:

A relative or absolute pathname. A relative pathname is relative to the working directory of
the TSO/E session (usually the HOME directory). Therefore, you should usually specify an
absolute pathname.

Up to 1023 characters long and enclosed in single quotes.
Copy to/from MVS data sets
OGET / OPUT
OPUT mvs_data_set_name{(member_name)} 'pathname'
{TEXT | BINARY} {CONVERT(character_conversion_table) | YES | NO}
OGET 'pathname' mvs_data_set_name{(member_name)}
{TEXT | BINARY} {CONVERT(character_conversion_table) | YES | NO}
HFS Files
HFS Files
File
System
Root
Directory
MVS
Data Set
OGET / OPUT
MVS
Data Set
MVS
Data Set
HFS Files
MVS
Data Set

116
ABCs of z/OS System Programming: Volume 9

In uppercase or lowercase characters, which are not changed by the system.
mvs_data_set_name | mvs_data_set_name(member_name)
Specifies the name of an MVS sequential data set or an MVS partitioned data set member to
receive the file that is being copied. One of these two operands is required. The data set
name is:

A fully qualified name that is enclosed in single quotes, or an unqualified name

Up to 44 characters long and is converted to uppercase letters by the system
BINARY | TEXT
Specifies whether the file being copied contains binary data or text.

BINARY
Specifies that the file being copied contains binary data. When you specify BINARY,
OGET operates without any consideration for <newline> characters or the special
characteristics of DBCS data. For example, doublebyte characters might be split between
MVS data set records, or a "shift-out" state might span records.

TEXT
Specifies that the file being copied contains text. This is the default. If you are using a
DBCS-supported terminal, you should use TEXT. It is assumed that doublebyte data in the
file system includes the <newline> character in order to delineate line boundaries. Data
within these lines that are delineated by <newline> characters must begin and end in the
"shift-in" state.

Chapter 4. z/OS UNIX System Services installation
117
4.13 UNIX commands to move and copy data
Figure 4-13 Commands to move and copy data
UNIX commands for copy and move
You can use
cp
and
mv
UNIX commands to copy or move files to and from MVS data sets. If
you specify more than one file to be copied, the target (last pathname on the command line)
must be either a directory or a partitioned data set. If the target is an MVS partitioned data
set, the source cannot be a UNIX directory.
The cp and mv commands
You can copy and move:

One file to another file in the working directory

One file to a new file on another directory

A set of directories and files to another place in your file system

A UNIX file to an MVS data set

An MVS data set to a file system

An MVS data set to an MVS data set
To
cp
or
mv
to a PDS or PDSE, the data set must be allocated before the copy or move. You
may
not

cp/mv
a partitioned data set to another partitioned data set and you may
not

cp/mv
a
directory to a partitioned data set (you may use
dir /*
to accomplish copying/moving all files
from the directory to a partitioned data set).
cp (copy) / mv (move) Commands
copy / move between:
UNIX file <=> MVS seq ds
UNIX files <=> MVS PDS or PDSE members
MVS PDS or PDSE => UNIX dir
MVS PDS or PDSE member => MVS PDS or PDSE
MVS seq => MVS seq
cp/mv can create an MVS sequential data set
HFS Files
HFS Files
File
System
Root
Directory

MVS
PDS Data
Set

MVS
PDSE
Data Set

cp / mv
MVS
seq Data
Set
HFS Files

118
ABCs of z/OS System Programming: Volume 9
4.14 The pax and tar utilities
Figure 4-14 pax and tar utilities
Read and write files with the pax utility
Use
pax
to read, write and list archive files. An archive file is a single file containing one or
more files and directories. Archive files can be HFS files or MVS data sets. A file stored inside
an archive is called a component file; similarly, a directory stored inside an archive is called a
component directory.
You can therefore use a single archive file to transfer a directory structure from one machine
to another, or to back up or restore groups of files and directories.
Archives created by pax are interchangeable with those created with the
tar
utility. Both
utilities can read and create archives in the default format of the other (USTAR for pax and
TAR for tar). Archives are generally named with suffixes such as .pax or .tar (or pax.Z and
tar.Z for compressed files), but this is not required.
Note:
MVS data sets cannot be specified for component files. Included with each
component file and directory is recorded information such as owner and group name,
permission bits, file attributes, and modification time.
Used to back up and restore files
Example to back up a complete directory (OMVS shell)
pax -wf archive_file directory_name
pax -wf /u/sysprog/source.pax /u/sysprog/source
tso ''OGET 'archive_file' 'DATA_SET_NAME' BINARY''
tso ''oget '/u/sysprog/source.pax' 'SYSPROG.PAX' binary''
pax and tar support for MVS data sets
When creating portable archives or extracting files
Archives can be MVS sequential or partitioned data sets
MVS data set are only supported as the archive file
pax -wf "//'user.lib(archive)'" *
pax -rf "//'user.lib(archive)'"

Chapter 4. z/OS UNIX System Services installation
119
The pax utility
The
pax
utility can read and write files in CPIO ASCII format, CPIO binary format, TAR format,
or USTAR format. It can read files that were written using
tar
,
cpio
, or
pax
itself. How it
handles filename length and preservation of link information across the backup and restore
process depends on the format you select: If you select CPIO, it behaves like the
cpio

command; and if you select TAR, it behaves like the
tar
command.
Figure 4-14 shows a
pax
example to back up a complete directory, including the
subdirectories and their contents, into a data set.
In the example:
directory_name
The name of the directory you want to archive
archive_file
An absolute pathname
DATA_SET_NAME
A fully qualified data set name
The pax command
The
pax
command creates an archive file with the specified name in the current working
directory.
For the
pax
command:

The -w option writes to the archive file.

The -f option lets you specify the name of the archive file.
The OGET command copies the archive file into the specified MVS data set.
Reading archive files
The
pax
and
tar
utilities can read an archive file directly from an MVS data set. Use the
pax
or
tar
shell command to restore the directory or file system from the archive file; all the
component files are restored from the archive file.
pax
and
tar
package HFS directory trees
into a single file called an “archive.” Archives are always treated as binary. Only partitioned
data sets in undefined format may store an executable. Archives can be moved to other
systems or directories. “Extracting files” means moving files from the archive into HFS files.
This avoids OPUT of archives from MVS data sets to UNIX, and OGET of archives from UNIX
to MVS data sets.
The tar utility
tar
is both a file format in the form of a type of archive bit stream and the name of the
program used to handle such files. The format was created in the early days of UNIX and
standardized by POSIX.1-1988 and later POSIX.1-2001. It was initially developed to be
written directly to sequential I/O devices for tape backup purposes, but it is now commonly
used to collect many files into one larger file, for distribution or archiving, while preserving file
system information such as user and group permissions, dates, and directory structures.
tar
reads and writes headers in either the original TAR format from UNIX systems or the
USTAR format defined by the POSIX 1003.1 standard.
Note:
When writing to a PDS member, the PDS must already exist;
pax
will automatically
overwrite an existing archive.
Note:
The
pax
command reads and writes headers in any of the
tar
formats.

120
ABCs of z/OS System Programming: Volume 9
4.15 ServerPac z/OS UNIX installation
Figure 4-15 ServerPac flow for z/OS UNIX installation
Installing the root file system
For a full configuration you need to build a complete root file system.
ServerPac supplies the jobs, ALLOCDS and RESTORE, to download the PDS from tape to
DASD. The other job, RESTFS uses the pax utility to restore the HFS file systems.
After running these jobs you have a complete root file system containing all the root-level
directories, files, and programs.
ServerPac builds the root for you with all the features that you ordered already installed in it.
They use the UNIX pax utility to compress the hierarchical format into an HFS file. It is
distributed to you as a member of hlq.HFSFILE:
hlq.HFSFILE(BACKUP) Backup of Root File System
In addition to reading and writing archive files (which concatenate the contents of files and
directories), pax can record file modification information such as dates, owner names, and so
on. You can therefore use a single archive file to transfer a directory structure from one
machine to another, or to back up or restore groups of files and directories.
(1) ALLOCDS
The ServerPac job ALLOCDS performs the following tasks for you:

Creates ROOT HFS
ALLOCDS +
RESTORE
RESTFS
CPAC.HFSFILE
ROOT
ETC, VAR
(1).
(2).
/
/STEP1 EXEC PGM=IKJEFT1B,COND=(4000,LT)
//SYSEXEC DD DSN=SERVILS1.SCPPCENU,DISP=SHR
/
/SYSTSPRT DD SYSOUT=*
/
/SYSTSIN DD *
%CPPEHFS RESTFS
+
/SERVILS1
_
Z16 +
"//'T5Z14.CPAC.HFSFILE(BACKUP)'" +
OMVS.TCx.TRNRSx.ROOT.HFS +
OMVS.TCx.ETC +
OMVS.TCx.VAR +
/*
OMVS.TCx.TRNRSx.ROOT.HFS

/service
OMVS.TCx.ETC
OMVS.TCx.VAR
VAR TMP DEV
ETC
BIN
SAMPLES
LIB
USR OPT U
(3).
Update CPAC.PARMLIB(BPXPRMFS)

Chapter 4. z/OS UNIX System Services installation
121

Creates ETC HFS

Creates the following directories:
VAR - HFS
(2) RESTFS job
The next job to run is RESTFS. This job does the following tasks for you:

Allocates STDIN, STDOUT and STDERR files (UNIX standard outputs). An RC=4 is
received if the directory is empty.

Creates /SERVICE directory.

Calls
pax
to restore the ROOT HFS.

Mounts the created ROOT HFS to /SERVICE.

Mounts the created ETC to /etc and mounts the var data sets.
(3) Update PARMLIB
The installation process RESTFS job updates the CPAC.PARMLIB member as follows:

Updates the BPXPRMFS with the MOUNT FILESYSTYPE section.

Updates the BPXPRMFS with the FILESYSTYPE TYPE(....) and the corresponding entry
point.
Note:
The RESTFS job has been combined with the RESTORE job, which restores the
pax

archive for the USS file system data sets directly from tape.

122
ABCs of z/OS System Programming: Volume 9
4.16 Non-volatile root file system
Figure 4-16 Managing the root file system
Managing the root file system
Extra planning should be done to keep file activity out of the root file system. This will protect
the root and make future migration to new system levels easier.
Installation customized files (such as profiles in /etc) should be kept in their own HFS. This will
protect these files from being overlaid by a future system replace.
Only file systems that are mounted in read-only mode can be shared between multiple
system images. However, IBM no longer recommends mounting the root file system in
read-only mode since it will cause customization problems and incorrect setup.
z/OS is built on a
system replace
basis. As new levels come out, all systems data sets,
including the root HFS, will be replaced. Therefore, make a plan to get all of your tailored files
out of the root and into their own HFS. Then when the system is replaced, you will only have
to do minimal revising of your profiles and other user-oriented files and remount their HFSs to
the new root. Keeping changes out of the root will make future changes much easier to
manage.
Root-HFS
bin
dev
etc
usr
/
lib
ptyp
fd0
null
OMVS.<SYSNAME>.
DEV.HFS
OMVS.<SYSNAME>.
ETC.HFS
tmp
u
joe
jane
OMVS.<SYSNAME>.
USERS.HFS
TFS
(or Automount)
var
OMVS.<SYSNAME>.
VAR.HFS

Chapter 4. z/OS UNIX System Services installation
123
4.17 Installation of other products
Figure 4-17 Installing products that are not part of the ServerPac
Installation of products off the root
When installing products that are not part of the ServerPac order and that install into the HFS,
consider the following:

Create new directories where the files associated with the new products will be installed.

If possible, create a new HFS data set and mount it to the new directory. After installation
of the product, all the files will reside in the new HFS data set.

IBM has created the /usr/lpp directory and each product that puts files in the HFS structure
creates a directory in lpp and then creates and mounts its own HFS at that mount point.

Keeping new products in different HFS data sets offers better file system management
while maintaining a more stable root file system. This also ensures easier maintenance
when applying service.
Figure 4-18 on page 124 shows the IBM convention for managing IBM products. Directory
/usr/lpp is built during the build of the root. As products (such as DCE or ICS) are built, they
will create a directory in /usr/lpp and then will mount an HFS to that directory. All the product
files will then be installed in a separate file system. Since the main installation vehicle for z/OS
is system replace, all these directories are built in root as it is built. System replace should
include these products.
bin
dev
etc
u
usr
/
tmp
lib
Root-HFS
lpp
Tivoli
Tivoli
files
WebSphere
files
WebSphere
FW
files
fw
Note: Keep Products separate until ServerPac supports those products

124
ABCs of z/OS System Programming: Volume 9
4.18 z/OS UNIX System Services installation
Figure 4-18 Display of root file system
Command to display the root
Before we update the provided JCL we should check how the TFS was named. It should be
equal to the name we used in our first step, where we requested an unmount for the TFS.
You can get the information using the
D OMVS,F
command.
This command provides the following output:

BPXTFS NAME=ROOT

PATH = /

UNIX Service is ACTIVE

HFS is in Read/Write (RDWR) Mode
The TFS is used to get UNIX System Services up and running during IPL. Since OS/390
V2R3 it is no longer possible to start and stop z/OS UNIX System Services from OMVS.
Using the
D OMVS,F
command shows the mounted file systems; this can also be done with the
UNIX ISHELL.
BPXO044I 15.23.48 DISPLAY OMVS 971
OMVS 000E ACTIVE OMVS=00
TYPENAME DEVICE ----------STATUS----------- MODE QJOBNAME QPID
BPXTFS 1 ACTIVE RDWR
NAME=
ROOT

PATH=/
/Display
OMVS,F

© Copyright IBM Corp. 2011. All rights reserved.
125
Chapter 5.
z/OS UNIX shell and utilities
This chapter provides information on how to invoke, customize, and use the z/OS UNIX shell
and utilities. It includes details on the following topics:

A brief overview about the z/OS UNIX shell

How to invoke the shell using different methods

Creating the required resources for the shell

Setting up code page translation for the shell

Shell environment variables

Global variables

How to pick up the region size when invoking the shell

Where and how to set up the time zone variable

Customizing the c89/cc compiler

Installing books for OHELP
5

126
ABCs of z/OS System Programming: Volume 9
5.1 The z/OS UNIX shell
Figure 5-1 Overview of the z/OS UNIX shell
z/OS UNIX shell
The z/OS UNIX shell can be compared to TSO/E for z/OS. It is the interactive interface to
z/OS UNIX. The shell feature comes with multiple commands and utilities which are in most
cases the same as the ones that come with a UNIX system. The z/OS UNIX shell is based on
the UNIX System V shell with some of the features from the Korn shell. The z/OS UNIX shell
conforms to the POSIX 1003.2 standard and to the XPG4 standard.
POSIX 1003.2 distinguishes between a command (a directive to the shell to perform a
specific task) and a utility (a program callable by name from the shell). To the end user there
is no difference between a command and a utility. For the purpose of this discussion,
command refers to both commands and utilities.
The shell is a command processor that can be used to:

Invoke shell commands or utilities that request services from the system.

Write shell scripts using the shell programming language.

Run shell scripts, REXX EXECS, and C-language programs interactively, in the
background, or in batch.
Shell commands are typically short, and they can be combined in pipes, or in shell scripts.
Once a shell command begins executing it has access to three files:
stdin: standard input Default is the keyboard.
stdout: standard output Default is the screen.
stderr: standard error Default is the screen.
HFS
Shell users
z/OS UNIX shell
Hierarchical
file system
stdin
stdout
stderr
S
h
e
l
l

c
o
m
m
a
n
d
s
a
n
d

u
t
i
l
i
t
i
e
s

Chapter 5. z/OS UNIX shell and utilities
127
5.2 Input, output, errors with UNIX shell
Figure 5-2 Files that a user has access to in a shell session
Files used by a shell session
z/OS C/C++ programs require that stdin, stdout, and stderr be defined as either a file or a
terminal. Many C functions use stdin, stdout, and stderr. However, it depends on how the
application is coded whether or not it writes to stderr and stdout.
Shell command access to files
When a shell command begins running, it has access to three files:

It reads from its standard input file. By default, standard input is the keyboard.

It writes to its standard output file.
– If you invoke a shell command from the shell, a C program, or a REXX program
invoked from TSO READY, standard output is directed to your terminal screen by
default.
– If you invoke a shell command, REXX program, or C program from the ISPF shell,
standard output cannot be directed to your terminal screen. You can specify an HFS
file or use the default, a temporary file.

It writes error messages to its standard error file.
– If you invoke a shell command from the shell or from a C program or from a REXX
program invoked from TSO READY, standard error is directed to your terminal screen
by default.
Executing commands, REXX or C programs - user has
access to three files:
Input file - This is the input keyboard
Output file - Terminal screen by default
Or, you can specify an HFS file
Error file - Terminal screen for error messages
Or, you can specify an HFS file
File names:
Input - stdin
Output - stdout
Error - stderr

128
ABCs of z/OS System Programming: Volume 9
– If you invoke a shell command, REXX program, or C program from the ISPF shell,
standard error cannot be directed to your terminal screen. You can specify an HFS file
or use the default, a temporary file.
If the standard output or standard error file contains any data when the command
completes, the file is displayed for you to browse.
Shell file names
In the shell, the names for these files are:

stdin for the standard input file

stdout for the standard output file

stderr for the standard error file

Chapter 5. z/OS UNIX shell and utilities
129
5.3 Accessing the z/OS UNIX shell
Figure 5-3 Files used when accessing the z/OS UNIX shell
Pseudoterminal files
Certain shell commands, such as
mesg
,
talk
, and
write
require pseudoterminals to have a
group name of TTY. When a user logs in, or issues the OMVS command from TSO/E, the
group name associated with these terminals is changed to TTY. As part of the installation, you
had to define the group TTY or use the group alias support as a GROUP ID in the security
data base, as shown in the following example:
ADDGROUP TTY (OMVS(GID(2))
Pseudo-TTYs
Pseudoterminals (pseudo-TTYs) are used by users and applications to gain access to the
shell. A pseudo_TTY is a pair of character special files, a master file and a corresponding
slave file. The master file is used by a networking application such as OMVS or rlogin. The
corresponding slave file is used by the shell or the user's process to read and write terminal
data. The convention for the names of the pseudo-TTY pair is:
/dev/ptypNNNN for the master (major 1)
/dev/ttypNNNN for the slave (major 2)
NNNN
is between 0000 and one less than the MAXPTYS value in the BPXPRMxx PARMLIB
member.
When a user enters the TSO/E OMVS command to initialize a shell, the system selects an
available pair of these files. The pair represents the connection. The maximum number of
pairs is 10000. You can specify an appropriate number of pairs in the MAXPTYS parameter.
Pseudoterminal files - (pseudo-TTYs)
Used by users and applications to gain access to the shell
Pair of character special files - (master and slave)
Master - Used by OMVS and rlogin
Slave - Used by the shell to read and write terminal data
Naming convention:
Master - /dev/ptypNNNN
Slave - /dev/ttypNNNN
NNNN - (0000 to MAXPTYS value -1)

130
ABCs of z/OS System Programming: Volume 9
5.4 Controlling session resources
Figure 5-4 Pseudo-TTY files used by shell users
Shell user files
Pseudoterminals (pseudo-TTYs) are used by users and applications to gain access to the
shell. A pseudo_TTY is a pair of character special files, a master file and a corresponding
slave file. The master file is used by a networking application such as OMVS or
rlogin
. The
corresponding slave file is used by the shell or the user's process to read and write terminal
data.
The convention for the names of the pseudo-TTY pair is:
/dev/ptypNNNN for the master (major 1)
/dev/ttypNNNN for the slave (major 2)
The
NNNN
is between 0000 and one less than the MAXPTYS value in the BPXPRMxx
member.
When a user enters the TSO/E OMVS command or logs in using
rlogin
or
telnet
to initialize
a shell, the system selects an available pair of these files. The pair represents the
connection. You can specify an appropriate number of pairs in the MAXPTYS parameter.
The MKNOD command
When using the MKNOD command, make:

The major number 1 for the master and 2 for the slave.

The minor number the same as the
NNNN
.
/dev/ptypNNNN
/dev/ttypNNNN
/dev/ptyp0015
/dev/ttyp0015
major: 1
minor: 15
perm: 666
major: 2
minor: 15
perm: 666
max-1
MKNOD '/dev/ptyp0015' major(1) minor(15) mode(6 6 6)
MKNOD '/dev/ttyp0015' major(2) minor(15) mode (6 6 6)
Master
Slave
Pseudo-TTY
MAXPTYS=256
BPXPRMxx

Chapter 5. z/OS UNIX shell and utilities
131
MAXPTYS statement in the BPXPRMxx member
The default controlling terminal can be accessed through the /dev/tty special file (major 3).
This file is defined the first time the system is IPLed. The MAXPTYS statement specifies the
maximum number of pseudo-TTY sessions that can be active at the same time. The range is
1 to 10000; the default and the value in BPXPRMXX is 256.
MAXPTYS lets you manage the number of interactive shell sessions. When you specify this
value, each interactive session requires one pseudo-TTY pair. You should avoid specifying an
arbitrarily high value for MAXPTYS. However, because each interactive user may have more
than one session, it is recommended that you allow four pseudo-TTY pairs for each user
(MAXIUDS * 4). The MAXPTYS value influences the number of pseudo-TTY pairs that can be
defined in the file system.
Note:
The commands can be in a CLIST or REXX exec or entered directly in a TSO/E
session or a shell session.

132
ABCs of z/OS System Programming: Volume 9
5.5 Dynamic /dev
Figure 5-5 Dynamic /dev definitions
Files created dynamically at IPL
The null file, /dev/null, (major 4) is analogous to an MVS DUMMY data set. Data written to this
file is discarded. The standard null file, named /dev/null, is created the first time the system is
IPLed, or when referenced, if it does not exist already.
The /dev/console (major 9) file is sent to the console and displayed using a write-to-operator
(WTO) within message BPXF024I. This message also contains the user ID of the process
that wrote to the console.
The default controlling terminal can be accessed through the /dev/tty special file (major 3).
The zero file, /dev/zero (major 4, minor 1), is similar to /dev/null in that data written to this file
is discarded, but when the file is read from, it provides an inexhaustible supply of binary
zeros. The standard zero file, named /dev/zero, is created the first time the system is IPLed or
when referenced, if it does not exist already.
The random number files, /dev/random and /dev/urandom (major 4, minor 2) provide
cryptographically secure random output that was generated from the cryptographic hardware
available on zSeries. The foundation of this random number generation is a time-variant input
with a very low probability of recycling. In order to use these device files, Integrated
Cryptographic Service Facility (ICSF) must be started, and a Cryptographic Coprocessor
feature may be required, depending on the model of the zSeries server.
IPL
/dev/null - A null file
/dev/console - The Console (WTO) File
/dev/tty - The Controlling Terminal File
/dev/zero - Contains binary zeros
First
referenced
/dev/ptypNNNN - pseudo-TTY Master
/dev/ttypNNNN - pseudo-TTY Slave
/dev/fnN...N - File Descriptor Files (c89)
/dev/random - /dev/urandom - ISCF must be started
Master
Slave
Pseudo-TTY
MAXPTYS=256
BPXPRMxx

Chapter 5. z/OS UNIX shell and utilities
133
5.6 Invoking the shell via TSO/E
Figure 5-6 Invoking the shell from TSO/E or from a remote workstation
Accessing the shell
There are several ways that you can access the z/OS UNIX shells:

The TSO/E OMVS command, which provides a 3270 interface

The
rlogin
command, which provides an ASCII interface

The
telnet
command, which provides an ASCII interface

The
ssh
command, or secure shell, is an encrypted protocol and associated program
intended to replace
telnet
.
OMVS shell
One of the methods to access the shell is by logging on to TSO/E and issuing the command
OMVS. When accessing the shell from TSO/E, the users can jump back and forth between
the shell and TSO/E. It is also possible to issue TSO/E commands from the shell.
The OMVS TSO/E command, together with the pseudo-TTY function, maps and transforms
the 3270-oriented TSO/E terminal interface and user externals to the POSIX 1003.1 defined
terminal interface expected by the POSIX 1003.2 conforming shell.
When you use the OMVS command to get into the z/OS UNIX shell, you can use ISPF to edit
(OEDIT) and browse (OBROWSE) HFS files. You can switch between the shell and TSO
session. You can have multiple shell sessions at the same time and toggle between the
sessions using PF keys.

SNA
TSO/E
z/OS UNIX
ACF/VTAM
TCP/IP
TN3270
Pseudo-TTY
Master
Slave
shell

TCP/IP
OMVS
cmd

134
ABCs of z/OS System Programming: Volume 9
The shell process can run in the same address space as the user's TSO/E session.
Network shell connections
The network connection to the shell via TSO/E can be either VTAM or TCP/IP. This includes:

Real and emulated 3270 terminals in an SNA network.

UNIX systems and other workstations that in a TCP/IP network support the Telnet 3270
(TN3270) client function. The TN3270 client communicates with the Telnet server (TN-S)
in TCP/IP on z/OS.
Pseudo-terminals
Pseudo-terminals are defined as a pair of character special files, one file designated as the
master, and one file as the slave. The pseudo-TTY master process is traditionally a network
server application; in z/OS UNIX the TSO/E command processor is the server application.
The pseudo-TTY slave process is the user shell process.
The pseudo-TTY function resides in the z/OS UNIX kernel and consists of a master pty and a
slave pty. The master pty is used by the networking application (z/OS UNIX) to communicate
with the user applications, for example the shell. The slave pty is used by the shell process
and associated applications. The TSO/E session reads and writes to the master, and the shell
process reads and writes to the slave.

Chapter 5. z/OS UNIX shell and utilities
135
5.7 Invoking the shell via rlogin or telnet
Figure 5-7 Invoking the shell from an rlogin or telnet
Accessing the shell from a remote terminal
A z/OS UNIX user can log in directly to the z/OS UNIX shell in either of the following ways:
rlogin
If the inetd daemon is set up and active on the z/OS system, a workstation user with
rlogin client support can use the TCP/IP network to log into the shell without going
through TSO/E.
telnet
Telnet support comes with the z/OS CS. It also uses the inetd daemon, which must
be active and set up to recognize and receive the incoming
telnet
requests. You
can
telnet
to the shell from a workstation that is connected via TCP/IP or
Communications Server to the MVS system. Use the
telnet
command syntax
supported at your site.
ssh
ssh (Secure Shell) is a program to log into another computer over a network, to
execute commands in a remote machine, and to move files from one machine to
another. It provides strong authentication and secure communications over
unsecure channels. It is intended as a replacement for rlogin, rsh, and rcp.
Additionally, ssh provides secure X connections and secure forwarding of arbitrary
TCP connections.
The advantage of ssh over Kerberos is that ssh does not require a central database
of users, and users can use their regular password. However, ssh and Kerberos can
safely coexist.
TCP/IP
ptypnnnn ttypnnnn
513
23
inetd
rlogind
otelnetd
shell
rloginc
rloginc
telnetc
telnetc
22
ssh
ssh
sshd
shell

136
ABCs of z/OS System Programming: Volume 9
z/OS OMVS shell
A z/OS system provides asynchronous terminal support for the z/OS UNIX shell. This is
different from the 3270 terminal support provided by the TSO/E OMVS command. In a UNIX
system, the UNIX shell operates in non-canonical mode (often called raw mode). This means
that each keystroke is transmitted from the terminal to the system. Several UNIX applications,
among them a popular editor called vi, depend on raw mode support. Using the 3270-terminal
interface for the z/OS UNIX shell meant that UNIX applications depending upon raw mode
support could not be ported to z/OS.
Figure 5-7 shows an overview of the two methods for logging in directly to the shell. Directly
logging in to the shell is the only way to get raw mode support. Both rlogin and telnet require
the inetd daemon to be set up and active.
Differences between TSO/E and remote terminal
There are some differences between asynchronous terminal support (direct shell login) and
3270 terminal support (OMVS command):

You cannot switch to TSO/E. However, you can use the TSO shell command to run a
TSO/E command from your shell session.

You cannot use the ISPF editor (this includes the oedit and TSO/E OEDIT commands,
which invoke ISPF edit).
Note:
The asynchronous interface does not automatically put you in raw mode. The
terminal is set to operate in line mode, and only when using a utility that requires raw mode
will it be changed.

Chapter 5. z/OS UNIX shell and utilities
137
5.8 rlogin and telnet access
Figure 5-8 rlogin and telnet access to the shell
Entering the shell from a remote terminal
Client users issue a
telnet
or
rlogin
command in the syntax of the system they are logged
on to. TCP/IP must be set up on both systems to recognize the appropriate system names
and ports.
The inetd daemon provides service management for a network. For example, it starts the
rlogind program whenever there is a remote login request from a workstation.
The rlogind program is the server for the remote login command
rlogin
commonly found on
UNIX systems. It validates the remote login request and verifies the password of the target
user. It starts a z/OS shell for the user and handles translation between ASCII and EBCDIC
code pages as data flows between the workstation and the shell.
INETD daemon configuration file
When inetd is running and receives a request for a connection, it processes that request for
the program associated with that socket. For example, if a user tries to log in from a remote
system into the z/OS shell while inetd is running, inetd processes the request for connection
and then issues a fork() and execl() to the rlogin program to process the rlogin request. It then
goes back to monitoring for further requests for those applications that can be found as
defined in the /etc/inetd.conf file as follows:
login stream tcp nowait OMVSKERN /usr/sbin/rlogind rlogind -m
otelnet stream tcp nowait OMVSKERN /usr/sbin/otelnetd otelnetd -lm
TCP/IP
INETD
login stream tcp nowait OMVSKERN /usr/sbin/rlogind rlogind -m
otelnet stream tcp nowait OMVSKERN /usr/sbin/otelnetd otelnetd -lm
RLOGIND
shell
OTELNETD
shell
/etc/inetd.conf
513
23
22
rlogin . .
telnet . .
ssh . .
SSHD
shell

138
ABCs of z/OS System Programming: Volume 9
Where:
stream
stream or dgram. This is the socket_type.
tcp
tcp or udp. The protocol is used to further qualify the service name. Both the
service name and the protocol should match an entry in the data set,
/etc/services, which is part of the user's TCP/IP configuration.
nowait
wait or nowait. Wait indicates the daemon is single-threaded and another request
will not be serviced until the first one completes. Nowait specifies that the inetd
daemon issues an accept when a connect request is received on a stream
socket. If wait is specified, the inetd daemon does not issue the accept. It is the
responsibility of the server to issue the accept if this is a stream socket.
z/OS UNIX daemons
The rlogin daemon or the telnet daemon is responsible for validating the user, handling
ASCII-to-EBCDIC translation, and invoking the shell.
The presence of the
-m
option on the command indicates that the shell should start in the
same address space as the daemon. The
-l
sets default mode for login to line mode.
A pseudo-TTY pair is assigned from the same pool to the shell session. To get multiple shell
sessions the user issues another
rlogin
or
telnet
client command.
The sshd daemon
ssh is actually a client-server protocol and a suite of connectivity tools. The ssh client
program is a secure remote login program—that is, a secure alternative to
rlogin
or
rsh
. The
ssh suite also provides sftp, which is a secure version of ftp, and rcp rcp, a secure version of
rcp. The client program requests a connection to the sshd secure remote login daemon
running in the target host. The sshd daemon handles key exchange, encryption,
authentication of both server and user, command execution, and data exchange. By default
sshd listens to port 22 for incoming connection requests.
The sshd daemon is started independent of the inetd daemon. The daemon can be started
with the following started task JCL:
//SSHD PROC
//SSHD EXEC PGM=BPXBATCH,REGION=0M,TIME=NOLIMIT,
// PARM='PGM /usr/sbin/sshd -f /etc/ssh/sshd_config'
//STDOUT DD SYSOUT=*,LRECL=137,RECFM=VB
//STDENV DD PATH='/etc/ssh/stdenv',PATHOPTS=(ORDONLY)
The main command that should be run from a user ID having BPX.DAEMON read access is:
/usr/sbin/sshd -f /etc/ssh/sshd_config

Chapter 5. z/OS UNIX shell and utilities
139
5.9 Customizing z/OS UNIX initialization
Figure 5-9 Files needed for z/OS UNIX initialization
Files used by z/OS UNIX initialization
The files /etc/init and /usr/sbin/init are referred to synonymously as the initialization program
that is run when the OMVS address space is initialized during the IPL. Copy the file
/samples/init.options to /etc/init.options. At startup, the kernel services attempt to run the
program /etc/init, which is an initialization program created by the user. If that program is not
found, then the kernel services try to run /usr/sbin/init, the default initialization program that is
run when the OMVS address space is initialized. The files are run at IPL.
The /usr/sbin/init and /etc/init programs
The /usr/sbin/init program invokes a shell to execute an initialization shell script that
customizes the environment for z/OS UNIX users. When this shell script finishes or when a
time interval established by /usr/sbin/init expires, kernel services become available for general
batch and interactive use.
Note:
You can use a REXX exec in an MVS data set as an alternative to running the
/etc/init initialization program. To activate the REXX exec for initialization, you must specify
its name on the STARTUP_EXEC statement in the BPXPRMxx parmlib member.
/etc is the "SYS1.PARMLIB" for z/OS UNIX
Files to customize - Copy from /samples
/etc/init or /usr/sbin/init
Program that executes an initialization shell script
/etc/init.options
Initialization options file
/etc/rc
Customization commands
Similar to COMMANDxx for z/OS

140
ABCs of z/OS System Programming: Volume 9
The /etc/init.options file
Before /usr/sbin/init invokes the shell to execute the system initialization shell script, it reads
the file /etc/init.options for values of various options. The IBM-supplied default is in
/samples/init.options. Copy this file to /etc/init.options and make the appropriate changes. If
you already have /etc/init.options, then compare it to /samples/init.options and retrofit any
new updates.
/etc/init.options can contain up to 25 -e option lines specifying names and values for different
environment variables. /usr/sbin/init passes the resultant environment variable array to the
shell that it invokes. In turn, the shell uses this array to set up an execution environment for
the initialization shell script that is appropriate for the installation. TZ is an example of an
environment variable that should be considered.
The /etc/rc file
You need to copy /samples/rc file to /etc/rc. It contains customization commands for z/OS
UNIX System Services Application Services.

Chapter 5. z/OS UNIX shell and utilities
141
5.10 Initializing z/OS UNIX
Figure 5-10 z/OS UNIX initialization processing
z/OS UNIX initialization
/usr/sbin/init and the customized /etc/init.options and /etc/rc files are run at IPL. There is no
other way to invoke them explicitly. During the IPL, one of the first address spaces to start is
OMVS.
The file /etc/init is referred to as the initialization program that is run when the z/OS UNIX
component is started, even though the /usr/sbin/init file may really be run if no such program
is found. This file contains the default initialization program shipped with the z/OS UNIX shell
and utilities.
BPXOINIT
BPXOINIT is the started procedure that runs the initialization process. BPXOINIT is also the
job name of the initialization process and is shipped in SYS1.PROCLIB. The STEPLIB DD
statement is propagated from OMVS to BPXOINIT. If there is a STEPLIB DD statement in the
BPXOINIT procedure, it is not used if a STEPLIB DD statement was specified in the OMVS
procedure.
The /etc/init program
The /etc/init program invokes a shell to execute an initialization shell script that customizes
the environment for the UNIX kernel. When this shell script finishes or a time interval
established by /etc/init expires, z/OS UNIX becomes available for general batch and
interactive use.
Start init task
Initialize kernel
Initialize all
filesystems
Allocate, open
HFS data sets
zFS data sets
Set init.options:
Run rc
/etc/init
/usr/sbin/init
/etc/init.options
/etc/rc
ROOT HFS
SYS1.PROCLIB
OMVS
BPXOINIT
IPL
Start shell /bin/sh
and run "init"
BPXOINIT
OMVS
Start system
address spaces
or
init
Copy:
/samples/init.options
/samples/rc
/samples/inittab
to
/etc/init.options
/etc/rc
/etc/inittab
PID=1
or
/etc/inittab

142
ABCs of z/OS System Programming: Volume 9
5.11 Environment variables
Figure 5-11 Environment variables in UNIX systems
Environment variables
Environment variables are global values or settings that determine the default operation of all
shells and are also passed on to application programs. Environment variables contain
information about your working environment. With all UNIX systems, each process has its
own private set of environment variables. By default, when a UNIX process is created it
inherits a duplicate environment of its parent process, except for explicit changes made by the
parent when it creates the child process, for example a fork or exec function. With different
UNIX systems, they do not all use the same variable names. Running programs can access
the values of environment variables for configuration purposes.
The value of an environment variable is a string of characters. For a C-language program, an
array of strings called the environment shall be made available when a process begins. For
z/OS UNIX, environment variables are defined in files in the file structure such as
/etc/init.options, /etc/rc, and /etc/profile.
Environment variable names used by the utilities in the Shell and Utilities volume of IEEE Std
1003.1-2001 consist solely of uppercase letters, digits, and the '_' (underscore) from the
characters defined in Portable Character Set and do not begin with a digit. Other characters
may be permitted by an implementation; processes tolerate the presence of such names.
Uppercase and lowercase letters shall retain their unique identities and shall not be folded
together. The name space of environment variable names containing lowercase letters is
reserved for processes. Processes can define any environment variables with names from
this name space without modifying the behavior of the standard utilities.
All UNIX systems have environment variables
The value of an environment variable is a string of
characters
Each process has its own private set of
environment variables
By default, when a process is created it inherits a
duplicate environment of its parent process
Running programs can access the values of
environment variables for configuration purposes
Shell scripts and batch files use environment
variables to store temporary values for reference
later in the script

Chapter 5. z/OS UNIX shell and utilities
143
5.12 Environment variables
Figure 5-12 Environment variables
Environment variables
When a program begins, an environment is made available to it. The environment consists of
strings of the form
name=value
, where
name
is the name associated with the environment
variable, and its
value
is represented by the characters specified in value. UNIX systems
traditionally pass information to programs through the environment variable mechanism.
SET command
Using the
set
command without arguments displays the names and values of all shell
variables, sorted by name, in the format Variable="value". An example is:
PWD="/u/rogers"
RANDOM="7322"
SECONDS="2"
SHELL="/bin/sh"
STEPLIB="none"
TERM="dumb"
TZ="EST5EDT,M3.2.0,M11.1.0"
Shell user variables
There are global variables for all shell users and each user can override these variables with
an individual set of variables. You can also change any of the values for the duration of your
session (or until you change them again). You enter the name of the environment variable and
equate it to a new value.
PATH="/usr/lpp/Printsrv/bin:/bin:."
HOME="/u/rogers"
SHELL="/bin/sh"
STEPLIB="none"
TERM="dumb"
TZ="EST5EDT"
_BPXK_SETIBMOPT_TRANSPORT="TCPIPOE"
_BPX_TERMPATH="OMVS"
A name associated with a string of characters made
available to the programs that you run
Some environment variables used by the shell are
PATH and TZ
Display variables with SET command

144
ABCs of z/OS System Programming: Volume 9
5.13 The /etc/init.options file
Figure 5-13 The /etc/init.options file
Updating the /etc/init.options file
The IBM-supplied default is located in the file /samples/init.options. Copy this file to
/etc/init.options. This file will be used the next time z/OS UNIX is started.
The file /etc/init.options treats all lines in the file that do not start with a hyphen (-) as
comment lines. Lines that start with a hyphen are used to specify options.
The following options can be specified:
-a
The maximum time in seconds that /etc/init will wait for the initialization shell script to
complete.
-t
Terminate option indicating whether to terminate the script if the timeout occurs.
-sh
The pathname of the initializing shell.
-sc
The pathname of the initializing shell script.
-e
TZ=EST5EDT The time zone environment variable is set to the time for the USA east
coast (five hours east of GMT/UTC). For a detailed description of how to set the time
zone variable, see “Setting up the Time Zone Variable,” in
z/OS UNIX System Services
Planning
, GA22-7800.
e
Environment variable options. The environment variables that are set in this file will only
be valid for the initialization shell. Later figures show how environment variables can be
set for the shell users.

-a 9999 timeout=180 secs (default)
-t 1 terminate shell = yes
-sc /etc/rc shell script = /etc/rc
-e TZ=EST5EDT TZ environment variable
*e LANG=C LANG environment variable
*e NLSPATH=/usr/lib/nls/msg/%L/%N NLSPATH environment variable
*sh /bin/sh shell = /bin/sh
*e PATH=/bin PATH environment variable
*e SHELL=/bin/sh SHELL environment variable
*e LOGNAME=ROOT LOGNAME environment variable.

Chapter 5. z/OS UNIX shell and utilities
145
5.14 The etc/rc file
Figure 5-14 The /etc/rc file used during initialization
Updating the /etc/rc file
A sample initialization shell script can be found in the file /samples/rc. Figure 5-14 shows the
IBM-supplied /samples/.rc file. Copy this file to the /etc directory. No changes will be used
until the next time z/OS UNIX is started.
The initialization script can be used to start daemons, or perform shell commands or scripts
automatically each time z/OS UNIX is started. For example, the inetd daemon can be added
to this script, as well as the automount command if it is to be used.
The /etc/rc file contains customization commands for z/OS UNIX System Services Application
Services. The figure shows the IBM-supplied default in /samples/rc. Copy this file to /etc/rc
and make the appropriate changes. If you already have an /etc/rc file, then compare it to
/samples/rc and retrofit any new updates.
Customize your /etc/rc file by adding shell commands. For instance, you could add a
command to start an installation-supplied daemon. The script can also invoke other scripts,
for instance, an rc.tcpip script to start tcp daemons.
Export variables
Export marks each variable name so that the current shell makes it automatically available to
the environment of all commands run from that shell. Exported variables are thus available in
the environment to all subsequent commands.
# Setup uucp utility
. . .
# Invoke vi recovery
mkdir -m 777 /etc/recover
/usr/lib/exrecover
# Start AUTOMOUNT
/usr/sbin/automount
# Start the INET daemon
_BPX_JOBNAME='INETD'
/usr/sbin/inetd /etc/inetd.conf &
sleep 5
echo /etc/rc script executed, 'date'
Page 2
# Initial setup for z/OS UNIX
export _BPX_JOBNAME='ETCRC'

# Provide z/OS UNIX Startup Diag.
set -v -x
# Setup utmpx file
>/etc/utmpx
chmod 644 /etc/utmpx

# Reset all slave tty files
chmod 666 /dev/tty*
chown 0 /dev/tty*

# Setup write, talk, mesg utilities
chgrp TTY /bin/write
chgrp TTY /bin/mesg
chgrp TTY /bin/talk
chmod 2755 /bin/write
chmod 2755 /bin/mesg
chmod 2755 /bin/talk

Page 1

146
ABCs of z/OS System Programming: Volume 9
The _BPX_JOBNAME variable sets the z/OS job name for this script to ETCRC.
export _BPX_JOBNAME='ETCRC'
Figure 5-14 shows parts of the sample provided in the /samples/rc file. The AUTOMOUNT
facility is started and some lines were taken out to make it fit the figure frame.
/usr/sbin/automount
The example shows that the inetd daemon will be started automatically each time z/OS UNIX
is initialized. The TCP/IP topic will have more information on the inetd start options. This
_BPX_JOBNAME variable will set the z/OS job name to the INETD daemon.
_BPX_JOBNAME='INETD' /usr/sbin/inetd /etc/inetd.conf
/samples/rc file contents
# Initialization shell script, pathname = /etc/rc
# Initial setup for z/OS UNIX
export _BPX_JOBNAME='ETCRC'
# Provide z/OS UNIX Startup Diagnostics
set -v -x
# Setup utmpx file
>/etc/utmpx
chmod 644 /etc/utmpx
# Reset all slave tty files
chmod 666 /dev/tty*
chown 0 /dev/tty*
# Allow only file owner to remove files from /tmp
chmod 1777 /tmp
# Allow only file owner to remove files from /var
chmod 1777 /var
# Allow only file owner to remove files from /dev
chmod 1755 /dev
# Setup write, talk, mesg utilities
# chgrp TTY /bin/write
# chgrp TTY /bin/mesg
# chgrp TTY /bin/talk
# chmod 2755 /bin/write
# chmod 2755 /bin/mesg
# chmod 2755 /bin/talk
# Performed at install in HOT7707
# Commented out in HOT6609 and performed in SAMPLIB job FOMISCHO
# Setup mailx utility
# No need to CHGRP /usr/mail directory
# No need to CHGRP mailx utility
# No need to CHMOD mailx to turn on SETGID
# Setup uucp utility
# chown uucp:uucpg /usr/lib/uucp
# chown uucp:uucpg /usr/lib/uucp/IBM
# chown uucp:uucpg /usr/spool/uucp
# chown uucp:uucpg /usr/spool/locks
# chown uucp:uucpg /usr/spool/uucppublic
# chown uucp:uucpg /usr/spool/uucp/.Xqtdir
# chown uucp:uucpg /usr/spool/uucp/.Sequence
# chown uucp:uucpg /usr/spool/uucp/.Status
# chown uucp:uucpg /bin/uucp
# chown uucp:uucpg /bin/uuname

Chapter 5. z/OS UNIX shell and utilities
147
# chown uucp:uucpg /bin/uustat
# chown uucp:uucpg /bin/uux
# chown uucp:uucpg /usr/lib/uucp/uucico
# chown uucp:uucpg /usr/lib/uucp/uuxqt
# chown uucp:uucpg /usr/lib/uucp/uucc
# chmod 4775 /bin/uucp
# chmod 4775 /bin/uuname
# chmod 4775 /bin/uustat
# chmod 4775 /bin/uux
# chmod 4754 /usr/lib/uucp/uucico
# chmod 4754 /usr/lib/uucp/uuxqt
# chmod 4774 /usr/lib/uucp/uucc
# Performed at install in HOT7707
# Commented out in HOT6609 and performed in SAMPLIB job FOMISCHO
# Invoke vi recovery
# mkdir -m 777 /var/tmp
# export TMP_VI="/var/tmp"
mkdir -m 777 /etc/recover
/usr/lib/exrecover
# Create TERMINFO database
# tic /usr/share/lib/terminfo/ibm.ti
# tic /usr/share/lib/terminfo/dec.ti
# tic /usr/share/lib/terminfo/wyse.ti
# tic /usr/share/lib/terminfo/dtterm.ti
# commented tic out in HOT1180 - all TERMINFO files are shipped
# Start the INET daemon for remote login activity
#_BPX_JOBNAME='INETD' /usr/sbin/inetd /etc/inetd.conf &
sleep 5
echo /etc/rc script executed, date

148
ABCs of z/OS System Programming: Volume 9
5.15 The /etc/inittab file with z/OS V1R8
Figure 5-15 Using the /etc/inittab file with z/OS V1R8
The /etc/inittab file
In z/OS V1R8, the /etc/inittab file is the same as used on other UNIX platforms. You have the
support for /etc/inittab to allow an installation to identify system processes that can be started
at system initialization; and to identify processes that can be restarted automatically when
they unexpectedly end.
The /etc/inittab file lists system processes such as commands and shell scripts that are to be
started when z/OS UNIX is initialized. Copy the IBM-supplied /samples/inittab file to
/etc/inittab and add additional entries if required.
For example, you can add daemons such as syslogd and cron that are normally started from
/etc/rc to take advantage of the respawn capability. The /etc/inittab file is processed only once
during initialization. If a command entry in the file needs to be run again, it must be manually
restarted, for example, from the z/OS UNIX shell or via BPXBATCH.
To restore the respawn attribute, the command can be started using the
_BPXK_INITTAB_RESPAWN environment variable.
Requirement
: You must have superuser authority in order to set the
_BPXK_INITTAB_RESPAWN environment variable to YES.
Identify system processes that can be started at system
initialization
To identify processes that can be restarted automatically
when they unexpectedly end - (RESPAWN)
The /etc/inittab file lists system processes, commands
and shell scripts to be started when z/OS UNIX initializes
Copy the /samples/inittab file to /etc/inittab and edit
Add daemons - syslogd and cron - started from /etc/rc
/etc/inittab file processed only once during initialization
To run a command again, start manually
From the z/OS UNIX shell or via BPXBATCH
Or - set _BPXK_INITTAB_RESPAWN=YES

Chapter 5. z/OS UNIX shell and utilities
149
5.16 The _BPXK_INITTAB_RESPAWN variable
Figure 5-16 Setting the _BPXK_INITTAB_RESPAWN variable
The _BPXK_INITTAB_RESPAWN variable
The _BPXK_INITTAB_RESPAWN environment variable specifies whether a process is to be
dynamically started with the respawn attribute.
YES
Specifies that a process is to be started with the respawn attribute. Setting the YES
attribute after the process has started does not affect the setting of the respawn
attribute. If a process is started by a spawn with _BPXK_INITTAB_RESPAWN=YES
(set by an export shell command, for example), the shell invokes the target program.
The program will be automatically restarted when it ends, even if it was not originally
started from the /etc/inittab file.
NO
Disables the respawn capability of the process.
This variable specifies whether a process is to be
dynamically started with the respawn attribute
_BPXK_INITTAB_RESPAWN=YES specifies that a
process is to be started with the respawn attribute
Setting the YES attribute after the process has started
does not affect the setting of the respawn attribute
If a process is started by a spawn with
_BPXK_INITTAB_RESPAWN=YES (set by an export
shell command, for example), the shell invokes the
target program
The program is automatically restarted when it ends,
even if it was not originally started from the /etc/inittab
file

150
ABCs of z/OS System Programming: Volume 9
5.17 Rules for coding /etc/inittab
Figure 5-17 Rules for coding /etc/inittab
The /etc/inittab file
The /etc/inittab file lists system processes such as commands and shell scripts that are to be
started when z/OS UNIX is initialized. Copy the IBM-supplied /samples/inittab file, shown in
Figure 5-15, to /etc/inittab and add entries to it.
Rules for coding /etc/inittab
Each entry is delimited by a newline character. A backslash (\) preceding a newline character
indicates the continuation of an entry. There are no limits (other than maximum entry size) on
the number of entries in the /etc/inittab file. The maximum entry size is 1024 characters. Each
entry field is only limited by the maximum entry size. The entry fields are:
Identifier
Identifies the inittab entry. The identifier for a given entry can be up to 7 mixed
case characters and it must be unique from other identifiers in the file. Because
the identifier is used as the job name for the command to be run, it must be
syntactically acceptable as a job name. The lowercase characters are
converted to uppercase to be used in the job name
RunLevel
Not supported for z/OS UNIX. Identifies the run levels in which this entry can be
processed. Even though the RunLevel field is not supported for z/OS UNIX, it is
in the inittab entry for compatibility with other UNIX implementations. The run
level field can be up to 32 alphanumerical characters.
etcrc::wait:/etc/rc > /dev/console 2>&1
inetd::respfrk:/usr/sbin/inetd /etc/inetd.conf
msgend::once:/bin/echo Done processing /etc/inittab > /dev/console
:end of file
Identifier: - Identifies the inittab entry
Runlevel: - Not supported with z/OS UNIX
Action: - Specifies how to handle the process that is
specified in the command field. The supported actions
are:
once - Start the process and do not wait for it to end
respawn - Process is restarted when it ends
respfrk - For programs that fork a child and go away
wait - Start a process and wait for it to end - never
restarted
/samples/inittab

Chapter 5. z/OS UNIX shell and utilities
151
Action
Specifies how to handle the process that is specified in the command field. The
supported actions are:
once
Starts the process and does not wait for it to end. When it ends,
The process is not restarted when it ends.
respawn
Starts the process as specified in the entry and does not wait for it
to end. Instead, it continues scanning the /etc/inittab file. The
process is restarted when it ends. When a process is spawned
again, it is restarted with the same file descriptors and environment
variables that it was started with originally. If a process ends due to
a shutdown of all fork activity, the process is not restarted until fork
activity is re-enabled. If a respawnable process ends and then ends
again after being restarted within 15 minutes of its first ending, then
message BPXI082D is displayed. The message identifies the
process entry and asks whether to retry or ignore the error. A
process identified for respawn will not be able to register as a
permanent process that can survive a shutdown and restart cycle
because the /etc/inittab file will be processed again during restart.
Tip:
To avoid excessive consumption of common storage, limit the
number of processes started with the respawn attribute to 100 or
fewer.
respfrk
Starts the process as specified in the entry. Do not wait for the
process to end; in other words, continue scanning the /etc/inittab
file.

If the process never issues a fork command, then this action
behaves the same way as the respawn action.

If the process issues a fork, then the respawn attribute is
transferred to the forked child process and the original process
is respawned when the child process ends.

If the original process issues any additional forks, the respawn
attribute is not transferred. It is only transferred the first time the
fork is issued.
Tip:
This option is intended for a program that forks itself to
create a child process which then continues running while the
parent process ends. For example, the cron and inetd
daemons are written this way. This option is not found on any
other UNIX platforms.
wait
Starts the process and waits for it to end. The process is not
restarted when it ends.
Note:
If /etc/inittab exists in your system, it is used instead of the /etc/rc file.

152
ABCs of z/OS System Programming: Volume 9
5.18 Customizing the OMVS command
Figure 5-18 Customizing the use of the OMVS command from TSO/E
Customize the TSO command line for UNIX users
The TSO/E access to the shell can be customized by the following options:

The logon procedure for users that want to go directly into the shell when they log on to
TSO/E can be modified to issue the OMVS command.
Select or create a TSO/E logon procedure for users who wish to invoke the shell
automatically when they log on to TSO/E.
In the logon procedure, add a PARM parameter to the EXEC statement for program
IKJEFT01.
// EXEC PGM=IKJEFT01, ...
// PARM=OMVS

A user can then type the OMVS command on the TSO/E logon panel command line.

To customize the OMVS command for all shell users, you can create a REXX exec with
the customized options. Then specify the name of the REXX exec in the PARM parameter,
instead of with the OMVS command. In the exec, for example, you can specify changes
like these:
– Use of the 3270 alarm
– Number of sessions (default is 1)
– The key or keys to be used for escape
– The settings for the function keys
// EXEC PGM=IKJEFT01,
PARM=%OMVS
// ...............................
Enter LOGON parameters:
Userid ==>
.......
Command ==> OMVS
/* REXX */
P = PROMPT("ON");
"omvs pf1(control) sessions(3)";
X = PROMPT(P);
Return;
TSO logon proc:
TSO logon panel:
Sample OMVS REXX EXEC:

Chapter 5. z/OS UNIX shell and utilities
153
– The table to be used for code page conversion
– Shared address space
Using the prompt option
When your profile allows for prompting, the PROMPT function can set the prompting option
on or off for interactive TSO/E commands, or it can return the type of prompting previously
set. When prompting is on, execs can issue TSO/E commands that prompt the user for
missing operands.
The PROMPT function can be used only in REXX execs that run in the TSO/E address space.
To set the prompting option on, use the PROMPT function followed by the word
'ON'
enclosed
within parentheses:
P = PROMPT('ON')
To reset prompting to a specific setting saved in variable
P
, write:
X = PROMPT(P)
Note:
The time limit for a shell user is the same as the TSO/E timeout.

154
ABCs of z/OS System Programming: Volume 9
5.19 Shell environment variables
Figure 5-19 Specifying environment variables for the shell user
Setting the shell user environment
An environment variable is a variable that describes the operating environment of a process
and typically includes information about the home directory, command search path, the
terminal in use, and the current time zone.
Depending on the commands used to set it, an environment variable can be global (used for
all processes), local (used only for the current process), or can be exported (used for the
current process and for any other processes created by the current process).
Search order for environment variables
Setting an environment variable is optional. If a variable is not set, it will have no value. The
following is a list of the places where environment variables can be set:

By the system programmer:
– RACF user profile
Sets the LOGNAME, HOME, and SHELL environment variables from data in the RACF
user profile, which was specified in the RACF ADDUSER.
–/etc/profile
A system-wide file that sets environment variables for all z/OS shell users. This file is
only run for login shells.
Compiler
variables
System
mail file
Language
Timezone
Default
command
path
RACF OMVS Segment
LOGNAME
HOME
SHELL
Search order:
1. RACF user profile
2. /etc/profile
3. $HOME/.profile
4. ENV environment
5. Shell command or script

Chapter 5. z/OS UNIX shell and utilities
155

By the shell users:
– $HOME/.profile
Sets environment variables for individual users. This file is only run for login shells.
– The file named in the ENV environment variable in $HOME/.profile
This file is run for both login shells and subshells.
– A shell command or shell script of the user.

156
ABCs of z/OS System Programming: Volume 9
5.20 Customizing your shell environment
Figure 5-20 Customizing the user shell environment
User shell environment
When you start the z/OS shell, it uses information in three files to determine your particular
needs or preferences as a user. The files are accessed in this order:

/etc/profile

$HOME/.profile

The file that the ENV variable specifies
Settings established in a file accessed earlier can be overwritten by the settings in a file
accessed later.
/etc/profile
The /etc/profile file provides a default system-wide user environment. The system
programmer may modify the variables in this file to reflect local needs (for example, the time
zone or the language). If you do not have an individual user profile, the values in the
/etc/profile are used during your shell session.
/$HOME/.profile
The $HOME/.profile file (where $HOME is a variable for the home directory for your individual
user ID) is an individual user profile. Any values in the .profile file in your home directory that
differ with those in the /etc/profile file override them during your shell session. z/OS provides a
sample individual user profile. Your administrator can set up such a file for you, or you can
create your own.
When you start the shell, these files are used to
determine your settings:
Order of overrides:
/etc/profile
$HOME/.profile
A file named in ENV environment variable in:
$HOME/.profile which points to a .setup file

Chapter 5. z/OS UNIX shell and utilities
157
5.21 Global variables in /etc/profile
Figure 5-21 Customizing the global /etc/profile variables for all users
Customizing /etc/profile
The /etc/profile file is the system-wide profile for the z/OS shell users. It contains environment
variables and commands used by most shell users.
All shell users will get the environment variables set by this profile. Users can override some
of the variables by setting the variables in their private profiles or in their shell sessions.
Environment variables in /etc/profile
The /etc/profile file contains the environment variables and commands used by most shell
users. An IBM-supplied sample is located in /samples/profile. Copy the sample to the /etc
directory and make any necessary changes.
STEPLIB
The use of STEPLIB=none is recommended to improve performance for shell
users. Keep this setting.
TZ
The timezone (TZ) is based on the Greenwich Mean Time (GMT), also called
Universal Time Coordinated (UTC). Change it to your local time. The time zone
used in the example is for the US East Coast (five hours west of UTC or GMT). It
also shows the daylight saving time zone that will be used (EDT).
PATH
This specifies the default command path where z/OS UNIX will search for the
commands and programs a user is executing. If your installation will have
programs in for example, /usr/bin, specify:
PATH=/bin:/usr/bin
Note:
All environment variables are written with capital letters.
# Improve shell performance
if [ -z "$STEPLIB" ] && tty -s;
then
export STEPLIB=none
exec sh -L
fi
# Set the time zone as appropriate.
TZ=EST5EDT
# Set a default command path, including current working dir (CDW)
PATH=/bin:.
# Sets the path environment variables
LIBPATH=/lib:/usr/lib:.
MANPATH=/usr/man/%L
NLSPATH=/usr/lib/nls/msg/%L/%N
# Sets the language
LANG=C
# Sets the name of the system mail file and enables mail notification.
MAIL=/usr/mail/$LOGNAME
# Export the values so the system will have access to them.
export TZ PATH LIBPATH MANPATH NLSPATH MAIL LANG
# Set the default file creation mask - umask
umask 022
# Set the LOGNAME variable readonly so it is not accidentally modified.
readonly LOGNAME

158
ABCs of z/OS System Programming: Volume 9
In the PATH variable, a colon (:) separates the list of pathnames. The dot (.)
represents the current working directory for a user. The order listed in the PATH
variable controls the search order.
NLSPATH
Specifies the pathname for message catalogs.
LANG
Specifies the name of the default locale.
MAIL
Specifies the pathname for mail files. Change it if you want to use another
pathname for the mail files. The setting for the MAIL variable indicates that each
user will use a mail file with the same name as their LOGNAME, and it will be
located in the directory specified for the variable. Note that when you use a dollar
sign ($) in front of a variable in a shell script, it means that you want to use the
value assigned to that variable. $LOGNAME will be interpreted as the user ID of
the shell user (see LOGNAME defined in RACF profile).
EXPORT
The
export
command will export a variable to a subshell. All the environment
variables defined will be valid only for the shell session (login shell) a user gets
when the user invokes the shell (TSO OMVS or
rlogin
). Shell scripts and many
shell commands will actually be executed in a separate shell created by the login
shell. The shell creates child processes to run the scripts or commands. These
subshells will not be aware of the variable settings that were specified in the login
shell unless you export the variable specifications. To ensure that the subshell
runs with the same environment, use the
export
command to export the
variables.
UMASK
The
umask
command was introduced in our discussion on security. The umask
value of 022 will result in permission bits: rwxr-xr-x.
The contents of the /etc/profile file are actually a shell script. It contains examples of the script
programming language with if-then statements, sets values for environment variables, and
issues some shell commands (
export
,
umask
,
readonly
).
Note:
Any changes made in /etc/profile will take effect the next time a user invokes the
shell.

Chapter 5. z/OS UNIX shell and utilities
159
5.22 User-defined settings
Figure 5-22 Setting the user variables by the user
Shell user environment values
Shell users can set their own values for the environment variables using any of the following
methods:

A $HOME/.profile file. A sample is provided in /samples/.profile/; it can be copied to a shell
user's home directory and modified.
Add the environment variable _BPX_SHAREAS=YES to the user profile. This will cause
all shell commands that run in separate processes to create the processes in the same
address space as the shell.

The ENV variable in the $HOME/.profile can be set to a file name which is a shell script
that sets environment variables.

A shell user can use the
env
command to display the environment variables for their
session, and to change any of these variables. The change will only last for the length of
the session.
The .profile file
The .profile file must be located in a user's home directory. Figure 5-22 shows the contents of
the sample provided by IBM. One of the variables in the .profile is called ENV, and this
variable can be used to point to another file where a user can add environment variables and
shell commands that the user wants to perform when the shell is invoked.
==> env
Shell session
/u/korn/.setup
Shell script
/u/korn/.profile
ENV=$HOME/.setup
export ENV

# Append your home directory to the current path.
PATH=$PATH:$HOME:

# Set the default editor to ed.
EDITOR=ed

# Set the prompt to display your login name, and current
# directory.
PS1='$LOGNAME':'$PWD':' >'

# Export the variable settings so that they are known
# to the system.
export PATH EDITOR PS1

160
ABCs of z/OS System Programming: Volume 9
Some of the things a user may want to update in the .profile file are:

ENV: use if the user has a separate shell script with environment variables.

PATH: Add the user's home directory to the search path:
PATH=$PATH:$HOME:
Note how variables can be used in other variables. System programmers and system
administrators need to have a $HOME/.profile file with the PATH environment set as follows:
PATH=$PATH:/usr/sbin:$HOME:
This allows the system programmers to run authorized utilities and to start daemons found in
/usr/sbin, as follows:
PS1
Change the shell prompt. The default is #.
TZ
Change if the user is located in a different time zone than the
system.
_BPX_SHAREAS=YES
Add this to the profile to reduce the number of address spaces
used by a shell user.
The env command
If using the
env
command to set a variable, the setting will only last for the duration of the
user's session. The next time the user invokes the shell, this setting is forgotten. Use the
.profile file or a shell script for variables that should be the same for each session.
The system programmer should use the /etc/profile file for variables that all users should have
set.

Chapter 5. z/OS UNIX shell and utilities
161
5.23 Setting the time zone
Figure 5-23 Setting the time zone variable
Setting the time zone (TZ)
The time zone is an environment variable used by the time service to set the correct time for
z/OS UNIX and for applications running on z/OS UNIX. It is possible to specify a time zone
variable in 4 different files. Table 5-1shows the files and when changes made in these files
become active.
Table 5-1 Activation schedule for time zone variables
Files After z/OS UNIX
restart
After next user
enters the shell
Immediately after
change
/etc/init.options YES NO NO
/etc/rc YES NO NO
/etc/profile YES YES NO
$HOME/.profile YES YES NO
General activation order:
First the settings in /etc/init.options and /etc/rc become active at
kernel initialization time. Afterwards, the settings in /etc/profile are read. If a user has a
.profile in his HOME directory that has its own TZ value specified, this setting will be the
active one for this user if he enters the shell.
/etc/init.options
...
-e TZ=EST5EDT
/etc/profile
...
TZ=EST5EDT
/u/korn/.profile
...
TZ=CET1CST
?
11:10:00
time
M.Korn
/etc/rc
...
TZ=EST5EDT

162
ABCs of z/OS System Programming: Volume 9
Time zones
The shell and utilities assume that the times stored in the file system and returned by the
operating system are stored using the Greenwich Mean Time (GMT) or Universal Time
Coordinated (UTC) as a universal reference. In the system-wide /etc/csh.login, the TZ
environment variable maps that reference time to the local time specified with the variable.
You can use a different time zone by setting the TZ variable in your .login file.
Setting your time zone
If you want to set your time zone to Eastern Standard Time (EST) and export it, specify:
setenv TZ "EST5EDT"
Where:

EST is Eastern Standard Time, the local time zone.

The standard time zone is 5 hours west of the universal reference time.

EDT is the Eastern Daylight Savings time zone.
Recommendation:
It is recommended to have a TZ setting active in /etc/init.options and in
/etc/profile. If there are daemons to start via the /etc/rc file, export the TZ variable before
starting the daemons. If you want the correct time on any replies inside the shell, you will
have to specify the TZ variable at least in the user profiles ($HOME/.profile) if no
specifications were made in the system-wide profile /etc/profile where all users are
affected.

Chapter 5. z/OS UNIX shell and utilities
163
5.24 Customizing the C89/CC compilers
Figure 5-24 Customizing the c89/CC compiler options
Compiler customization
As we mentioned earlier, the /etc/profile file provides a default system-wide user environment.
Any environment variables that are set in /etc/profile affect every shell user unless they
override these settings in their own $HOME/.profile or in a setup script file that is pointed to by
the ENV variable.
For each z/OS release, there is a default compiler for c89, cc, or c++ (cxx) to use. Optionally,
you can choose to use a non-default compiler. This section lists the compiler choices for each
release, including the default compilers; the environment variable settings for each compiler
are identified.
c89/cc/c++ utilities
The c89/cc/c++ utilities use a number of environment variables. The default values are
specified as comments in the /samples/csh.login file that is shipped with each release. The
naming conventions for the environment variables are as follows:

c89 begin with the prefix _C89

cc begin with the prefix _CC

c++ begin with the prefix _CXX
If the C/C++ Class Library DLLS are used in building your executables (the default for the c++
utility), then this will also target your executable for the same level of C/C++ Class Library.
/etc/profile

# Start of c89/cc/c++ customization section
# ================================================================
# High-Level Qualifier "prefixes" for data sets used by c89/cc/c++:
# Compiler:
export
_
C89
_
CLIB
_
PREFIX="CBC"
# Prelinker and runtime library:
export
_
C89
_
PLIB
_
PREFIX="CEE"
#
# OS/390 system data sets:
export
_
C89
_
SLIB
_
PREFIX="SYS1"
# Compile and link-edit search paths:
# Compiler include file directories:
export ${_CMP}_INCDIRS="/usr/include /usr/lpp/ioclib/include"
# Link-edit archive library directories:
export ${_CMP}_LIBDIRS="/lib /usr/lib"
# Esoteric unit for data sets:
# ================================================================
# Unit for (unnamed) work data sets:
export ${_CMP}_WORK_UNIT="SYSALLDA"

164
ABCs of z/OS System Programming: Volume 9
In the section titled
'c89/cc/c++ customization section'
, remove the comment for the
following export commands to tell the C/C++ compiler what the high level qualifier of the
C/C++, Language Environment and z/OS target library data sets are. Check the high level
qualifiers on your system to make sure they agree with these default values.
Use ISPF 3.4 and look at your target libraries to check. If they agree, there is no need to
uncomment these lines because they are the default setting.
#export _C89_CLIB_PREFIX="CBC"
#export _C89_PLIB_PREFIX="CEE"
#export _C89_SLIB_PREFIX="SYS1"
If your high level qualifiers do not match, then make the changes here and uncomment the
three export statements. See the Environment Variables section of the c89/cc/c++ command
discussion in
z/OS UNIX System Services Command Reference
, SA22-7802 for more
information.
If the system is not configured with an esoteric unit SYSDA, or some other esoteric unit is to
be used for VIO temporary unnamed work data sets set by c89, the following environment
variable needs to be set. Specifying a null value for this variable ("") results in c89 using an
installation-defined default for the UNIT. The environment variable is shown being set to the
default value:
#export _C89_WORK_UNIT="SYSDA"
The environment variables used by the cc utility have the same names as the ones used by
c89 except that the prefix is _CC instead of _C89. Likewise, for the c++ (cxx) utility, the prefix
is _CXX instead of _C89. Normally, you do not need to explicitly assign the environment
variables for all three utilities. These
eval
commands set the variables for the other utilities,
based on those set for c89.
#eval "export $(typeset -x | grep "^_C89_" ...
#eval "export $(typeset -x | grep "^_C89_" ...
Note:
SYS1 refers to the high level qualifier of CSSLIB, MACLIB and MODGEN on your
system.

Chapter 5. z/OS UNIX shell and utilities
165
5.25 Code page tables
Figure 5-25 Defining code page tables
Code page tables
A code page for a character set determines the graphic characters produced for each
hexadecimal code. The code page is determined by the programs and national languages
being used.
If the shell is using a locale generated with code pages IBM-1047, an application programmer
needs to be concerned about “variant” characters in the POSIX portable character set whose
encoding may vary from other EBCDIC code pages. For example, the encodings for the
square brackets do not match on code pages IBM-037 and IBM-1047.
For most countries, MVS uses one code page and the z/OS UNIX shell uses a different one.
To complicate the matter, many users have workstations which use an ASCII-based code
page. When moving data between these environments, the data may have to be converted
between the code pages to maintain the same characters. This may result in different
hexadecimal codes depending on the code pages.
Conversion tables in SYS1.LINKLIB
There are code page conversion tables located in SYS1.LINKLIB which can be used to
convert between the z/OS code page and the shell code page for the national languages
supported by the z/OS UNIX shell.
The source for these code page tables can be found in SYS1.SAMPLIB. They can be used as
samples for creating a new table if an installation has special requirements.
BPXFXnnn
Code Page
conversion
tables
SYS1.LINKLIB
IBM-037
IBM-8859-1
IBM-1047
MVS Country
extended
code page
z/OS UNIX
shell
code page
ASCII
code page
Other
code pages
Character
set

166
ABCs of z/OS System Programming: Volume 9
5.26 Specifying a code page
Figure 5-26 Specifying code pages
Specifying code pages
The OMVS command has a CONVERT option that lets you specify a conversion table for
converting between code pages for the shell accesses by a TSO/E user. The table you want
to specify depends on the code pages you are using in MVS and in the shell. For example, if
you are using code page IBM-037 in MVS and code page IBM-1047 in the shell, specify the
following when you enter the OMVS command:
OMVS CONVERT((BPXFX111))
The BPXFX111 translation table is for z/OS (code page 00037) to z/OS UNIX (code page
1047) translation. This would be used by most shell users in the U.S.
IBM has supplied many code pages for different countries with the product. If you were in
Switzerland you might invoke the shell with the BPXFX450 conversion table. If you leave out
the data set name, the normal z/OS search order is used to find the module.
If you are accessing the shell through the rlogin or telnet interface you do not use the
OMVS

command. You must change to the appropriate code page by issuing the
chcp
command. This
could be issued by the user or be put in a profile for them.
The example in Figure 5-26 shows the code for a script that checks to be certain that
OMVS

was not issued, and then issues the
chcp
with an ASCII conversion table of IBM-850 and an
EBCDIC table of IBM-500. You may also want to change the environment variables that
reflect local formats at the same time.
OMVS CONVERT((BPXFX111))
OMVS CONVERT('SYS1.XLATE(BPXFX450)')
$
$ Issue chcp only if not using TSO/E OMVS
$
if
test "$_BPX_TERMPATH" != "OMVS"
then
chcp -a IBM-850 -e IBM-500
fi
TSO
RLOGIN/TELNET

Chapter 5. z/OS UNIX shell and utilities
167
5.27 Internationalization variables (locales)
Figure 5-27 Internationalization variables
Locales
A locale is the subset of your environment that deals with language and cultural conventions.
It is made up of a number of categories, each of which is associated with an environment
variable and controls a specific aspect of the environment. Figure 5-27 shows the categories
and their spheres of influence.
Internationalization variables
Internationalization enables you to work in a cultural context that is comfortable for you
through locales, character sets, and a number of special environment variables. The process
of adapting an internationalized application or program, particular to a language or cultural
environment, is termed localization.
Categories
To give a locale control over a category, set the corresponding variable to the name of the
locale. In addition to the environment variables associated with the categories, there are two
other variables that are used in conjunction with localization, LANG and LC_ALL. All of these
variables affect the performance of the shell commands. The general effects apply to most
commands, but certain commands such as sort, with its dependence on LC_COLLATE,
require special attention to be paid to one or more of the variables; we discuss such cases in
the localization section of the command.
LANG
LC_ALL
LC_COLLATE
LC_CTYPE
LC_MESSAGES
LC_MONETARY
LC_NUMERIC
LC_TIME
LC_SYNTAX
NLSPATH
A locale is the subset of your
environment that deals with
language and cultural
conventions
It is made up of a number of
categories
Each is associated with an
environment variable
Controls a specific aspect of the
environment

168
ABCs of z/OS System Programming: Volume 9
The effects of each environment variable are as follows:
LANG
Determines the international language value. Utilities and applications
can use the information from the given locale to provide error messages
and instructions in that locale's language. If the LC_ALL variable is not
defined, any undefined variable is treated as though it contained the
value of LANG.
LC_ALL
Overrides the value of LANG and the values of any of the other variables
starting with LC_.
LC_COLLATE
Identifies the locale that controls the collating (sorting) order of
characters and determines the behavior of ranges, equivalence classes,
and multicharacter collating elements.
LC_CTYPE
Identifies the locale that defines character classes (for example, alpha,
digit, blank) and their behavior (for example, the mapping of lowercase
letters to uppercase letters). This locale also determines the
interpretation of sequences of bytes as characters (such as singlebyte
versus doublebyte characters).
LC_MESSAGES
Identifies the locale that controls the processing of affirmative and
negative responses. This locale also defines the language and cultural
conventions used when writing messages.
LC_MONETARY
Determines the locale that controls monetary-related numeric formatting
(for example, currency symbol, decimal point character, and thousands
separator).
LC_NUMERIC
Determines the locale that controls numeric formatting (for example,
decimal point character and thousands separator).
LC_TIME
Identifies the locale that determines the format of time and date strings.
LC_SYNTAX
Identifies the locale that defines the encodings for the variant characters
in the portable character set.
NLSPATH
A localization variable that specifies where the message catalogs are to
be found.
Examples of locales
For example, the following locale specifies that the z/OS shell is to look for all message
catalogs in the directory /system/nlslib, where the catalog name is to be constructed from the
name parameter passed to the z/OS shell with the suffix .cat.
NLSPATH="/system/nlslib/%N.cat"
The following specifies that the z/OS shell should look for the requested message catalog in
name, name.cat, and /nlslib/category/name.cat, where category is the value of the
LC_MESSAGES or LANG category of the current locale:
NLSPATH=":%N.cat:/nlslib/%L/%N.cat"
Note:
Substitution fields consist of a % symbol, followed by a single-letter keyword. These
keywords are currently defined as follows:
%N The value of the name parameter
%L The value of the LC_MESSAGES category, or LANG, depending on how the
catopen() function that opens this catalog is coded.
%l The language element from the LC_MESSAGES category
%t The territory element from the LC_MESSAGES category
%c The codeset element from the LC_MESSAGES category

Chapter 5. z/OS UNIX shell and utilities
169
5.28 Setting the region size
Figure 5-28 Setting the user region size default
Setting region sizes for programs
The region size describes the amount of storage within which a user is allowed to run/execute
programs. This value determines what kinds of programs (depending on their size) and how
many programs are executable at the same time.
Remote user logons
Telnet and rlogin users get their region size from the MAXASSIZE parameter in the
SYS1.PARMLIB with the BPXPRMxx member.
BPXBATCH jobs
If BPXBATCH is used there is a BPXBATCH REGION parameter that describes the region
size; however, started procedures that create z/OS UNIX processes use the REGION
parameter on the EXEC statement.
TSO users logon panel
In principle, TSO users get the region size from the logon panel to their programs. If a user
enters the z/OS UNIX shell by issuing a TSO OMVS command, the parent process doesn't
run in the user's address space. Under control of the Work Load Manager, an address space
will be created that gets the same region size as the TSO/E user itself. IEFUSI is a user exit
where an installation can set the region size and region limit for all programs that run under
this job step. Make sure this exit does not change the region size setting for the z/OS UNIX
process.
TSO OMVS
16 MB
WLM
User Region
above
User Region
below
???
???
UNIX User Address Space
BPXAS
BPXPRMxx(MAXASSIZE) - Telnet, rlogin
Region= - BPXBATCH
Set on logon panel - TSO OMVS
---------------------------------------------------------
IEFUSI user exit

170
ABCs of z/OS System Programming: Volume 9
5.29 Setting up printers for shell users
Figure 5-29 Shell user printer defaults
Setting a printer default
Each z/OS UNIX user has a number of default printers specified in different ways. The system
will select a printer in the following order:

The printer in the dest option of the
lp
shell command, or the printf() or fprintf() functions.

The printer specified in the LPDEST environment variable.

The printer specified in the PRINTER environment variable.

The printer in the RACF user profile. It is specified by the DEST parameter of the RACF
ADDUSER or ALTUSER command.
The z/OS Infoprint Server, available beginning with OS/390 V2R8, provides much greater
support for printing than was available in previous systems.
Inform the application programmers of the destinations or symbolic names of printers you
specified in JES initialization statements. The dest option of the
lp
command uses the same
destinations as the DEST parameter in the OUTPUT JCL statement. If omitted, the system
uses the default printer. The dest option on
lp
can be:

LOCAL for any installation printer.

A destination that is defined in a JES2 DESTID initialization statement.
JES controls the print separators, also called cover pages and banner pages, for SYSOUT
output for all users, including z/OS UNIX users. To place a user's name and address in the
print separator for forked processes, specify the user's name and address in the WORKATTR
segment of the RACF user profile.
==> lp prt1
1.dest option on lp, printf(),
or fprintf()
2.LPDEST environment var.
3.PRINTER environment var.
4.RACF user profile: DEST
Shell session:
Choose printer:
Print file

Chapter 5. z/OS UNIX shell and utilities
171
5.30 Installing books for OHELP
Figure 5-30 Setting the user OHELP command to access the z/OS UNIX books
Access to documentation
The TSO/E OHELP command provides online help for:

Shell commands

Callable services

C functions

Shell messages
In order to use OHELP, the following must be done:

BookManager® READ/MVS is required.

The z/OS UNIX bookshelf must be installed.

An HFS file must be customized to map the OHELP reference ID with a z/OS UNIX book.
Do this using the following steps:
– Copy the sample file in /samples/ohelp.ENU to /etc/ohelp.ENU.
– Update the file if you need to change the data set names of the online books, or if you
want to add or delete books.
/etc/ohelp.ENU
OHELP * "environment variable"
From your TSO/E session:
1 'IBMBOOKS.SK210701.BPXA5M02.BOOK' UNIX System Services Command Reference
2 'IBMBOOKS.SK210701.BPXB1M01.BOOK' UNIX System Services Callable Services
3 'IBMBOOKS.SK210701.BPXA7M02.BOOK' C/C++ for z/OS Library Reference
4 'IBMBOOKS.SK210701.BPXA8M02.BOOK' UNIX System Services Shell Messages
* 'IBMBOOKS.SK210701.BPXMAN02.BKSHELF' OHELP UNIX System Services Bookshelf
TSO/E command: OHELP - displays bookshelf

172
ABCs of z/OS System Programming: Volume 9
5.31 Using the man command
Figure 5-31 Using the man command to access manuals
Access to documentation from the shell
You can use the
man
command to get help information about a shell command. The
man

syntax is:
man command_name
To scroll the information in a man page, press Enter.
To end the display of a man page, type
q
and press Enter.
To search for a particular string in a system that has a list of one-line command descriptions,
use the
-k
option:
man -k string
For example, to produce a list of all the shell commands for editing, you could type:
man -k edit
You can use the man command to view manual descriptions of TSO/E commands. To do this,
you must prefix all commands with TSO. For example, to view a description of the
MOUNT

command, you would enter:
man tsomount
-k
Searches a precomputed database of syntax lines for information on keywords.
The man command gives help information about a
shell command
man command_name

To produce a list of all the shell commands for editing

man -k edit
To view descriptions of TSO/E commands such as
mount
man tsomount

Chapter 5. z/OS UNIX shell and utilities
173
-M -M path
searches the directories indicated by path for help files. If
-M
is not specified,
man uses the path specified in the MANPATH environment variable if set; otherwise
man searches /usr/man/%L. The value of the LANG environment variable is substituted
for %L in this directory and in the directories specified by MANPATH.
-w
Displays only the filename of the file containing the help file.
-x
Displays what files man is searching to find the help file.
-x
also displays any errors man
encounters in extracting man pages from online book files.

174
ABCs of z/OS System Programming: Volume 9
5.32 Enabling various tools
Figure 5-32 Customizing shell utilities
Shell utilities
Some of the shell utilities must be customized before they can be used:
make
The make utility uses a configuration file. Copy the sample in /samples/startup.mk to
/etc/startup.mk.
The make utility helps manage large applications consisting of multiple programs.
When an application programmer updates a program, make will help keep all the
files/programs in synchronization.
lex
For the lex utility, copy the sample in /samples/yylex.c to /etc/yylex.c. This file
contains the prototype lex scanner.
lex and yacc are utilities that help an application programmer to write programs. For
example, input to lex and yacc describes how you want the final program to work. The
output from lex and yacc is C source code. lex and yacc are often used to develop
programs that analyze and interpret input, for example a compiler.
yacc
For the yacc utility, copy the sample in /samples/yyparse.c to /etc/yyparse.c. This file
contains the C parser template used by yacc.
file
For the file utility, copy the sample in /samples/magic to /etc/magic.c. This file
contains a series of templates showing different file types.
The file utility determines the format of each file by inspecting the attributes and (for
an ordinary file) reading an initial part of the file. It compares each file on the
startup.mk
yylex.c
yyparse.c
magic
startup.mk
yylex.c
yyparse.c
magic.c
/samples
/etc
make:
lex + yacc:
file:
mail:
mailx.rc
mailx.rc
COPY
COPY

Chapter 5. z/OS UNIX shell and utilities
175
command line to templates found in a system-maintained magic file to determine
their file type.
If the file is an executable, its addressing mode is determined for output. If the file is
not an executable, file compares each file to templates found in a magic file to
determine their file type.
The file utility then divides files that do not match a template in the magic file into text
files and binary data. Then, by reading an initial segment of the text files and making
an informed guess based on the contents, file further divides text files into various
types such as C programs, assembler programs, files of commands to the shell, and
yacc or lex programs.
mailx
For the mailx utility, copy the sample in /samples/mailx.rc to /etc/mailx.rc. This file
contains variable values and definitions common to all shell users.
The mailx utility program allows users to send messages to one another. The mailbox
name is set up in the user's profile. It defaults to /usr/mail/$LOGNAME.

176
ABCs of z/OS System Programming: Volume 9
5.33 SVP for z/OS UNIX and tools
Figure 5-33 Customizing the installation verification program
Setup verification program
The Setup Verification Program (SVP) lets you check for troublesome setup errors before they
cause a problem. After you have followed the instructions in
z/OS UNIX Systems Services
Planning
, SC28-1890, and completed your setup and customization (including the z/OS shell
and utilities), you can run the SVP.
Using the SVP, you can:

Verify that each user has a UID and OMVS segment defined, and each group has a GID.

Check for duplicate assignment of UIDs and GIDs.

Verify that each user has access to and owns a home directory and has read, write, and
search access to it.

Check the permissions for several directories usually set up at installation.

Check that files in the /dev directory are defined correctly. Reconcile the number of
pseudo-ttys and file descriptor files with the BPXPRMxx definitions. On z/OS V1R7 and
above, it does minimal checking in the /dev directory because the files are created by the
system as needed.

Verify that the z/OS UNIX shell will run.

Verify that the OMVS command will run.

Check customization for utilities. The program checks or does the following:
– Files that have been copied from /samples to /etc
IVP programs
test
make
changes
z/OS UNIX
http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1svp.html
LE - CEEWIVP
TCP/IP - HOMETEST
C/C++ - EQAWLECS

OESVP - Tests UNIX Services environment

Chapter 5. z/OS UNIX shell and utilities
177
– terminfo files
– Settings for some environment variables
– Ability to compile and run a program
– Performs various other checks
After customizing the different tools and changing the environment, you have to test the new
settings with the related Setup Verification Programs (SVP).

LE environment
To verify that Language Environment was installed properly, run CEEWIVP, which is found
in your SCEESAMP library. Refer to the comments in the job for instructions, expected
condition codes, and expected output.

IBM Communications Server IP
Verify your host name and address configuration with HOMETEST. This program will test
the system configuration defined by the HOSTNAME, DOMAINORIGIN, and
NSINTERADDR statements in the TCPIP.DATA data set.

C/C++ with Debug Tool
If you are using the C/C++ debug tools, you have to submit the following jobs in this order:
hlq.SCBCJCL(EQAWLECS)
hlq.SCBCJCL(EQAWLU62)
hlq.SCBCJCL(EQAWIVP2)

C/C++ compiler
If C/C++ has been enabled, verify that the following C/C++ components are installed
properly:
– C/C++ compilers
Run the jobs HLB4801F and HLB4801G from the ServerPac Installation Dialog.
– C/C++ Host Performance Analyzer
In order to test the C/C++ Host Performance Analyzer you can run the two jobs
HLB4801M and HLB4801N from the ServerPac Installation Dialog, or find the same
JCL in hlq.SCTVJCL with the names CTVFINT and CTVFUNK.
– C/C++ IBM Open Class® Library
To test the Open Class Library, use the jobs HTV4821R, HTV4821S and HTV4821T,
which can be run from the ServerPac Installation dialog or from the hlq.SCLBJCL
library with following names: CLB3JIV1, CLB3JIV2, and CLB3JIV3.

z/OS UNIX environment and tools
To test the z/OS UNIX environment and tools use the program oesvp, which can be
downloaded from http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1svp.html
with the name oesvp.exec.bin.

178
ABCs of z/OS System Programming: Volume 9
5.34 Setup Verification Program (SVP)
Figure 5-34 Using the Setup Verification Program
Setup Verification Program
The SVP for z/OS UNIX ISPF panels is shown Figure 5-34. During the z/OS shell test, do not
interrupt the process when the indicator RUNNING/INPUT changes; instead, press PF10.
This utility requires ISPF version 4.1 or higher, as well as z/OS V1R7 or higher.
For more information, see
ServerPac: Installing Your Order
or the ServerPac Program
Directory.
Setup verification program
The Setup Verification Program (SVP) lets you check for troublesome setup errors before they
trip you up. After you have followed the instructions in
z/OS UNIX System Services Planning
,
GA22-7800, and completed your setup and customization (including the z/OS shell and
utilities), you can run the SVP.
Select a specific check
Select the specific checks you wish to run, as follows:

Kernel
Displays kernel configuration information. If you believe this information is not how you
intended to set up your system, you should check your BPXPRMxx parmlib member and
startup procedures.

Chapter 5. z/OS UNIX shell and utilities
179

Sysplex
Displays the names of the active systems using SYSPLEX(YES) and verifies that some of
the special symlinks are set up correctly.

Users
Verify that each user that has a UID also has the default group assigned a GID.

Groups
Checks that a GID is assigned to every group.

User and group setup
Checks for duplicate assignment of UIDs and GIDs.

User home directories
Verifies that each user has access to and owns his home directory and has read, write,
and search access to that directory. If automount is used for home directories, all file
systems will be mounted.

Permissions for basic directories
This check surveys the permissions for several directories normally found on the system.

/dev directory
Verifies that customary files are defined correctly. This also reconciles the number of
pseudo-ttys and file descriptor files with parmlib definitions.

Shell environment
Verifies that the shell will run.

OMVS command
Verifies that the OMVS command will run.

Utility customization
Checks for differences in some files in the /samples directory with the corresponding file in
the /etc directory, that the terminfo files have been created, some environment variables
are appropriately set, a program could be compiled and run, and various other checks.
This verification step can be interactive. If it thinks something should be done, it will ask if
you want it to do it.
Requirements for use of the SVP
To use the SVP you must satisfy the following requirements:

You must be a superuser (UID=0) with RACF SPECIAL authority, or the equivalent.

Your system must be at any release of z/OS.

Your system must be at ISPF version 4.1 or higher.

You can use any security product; RACF is not required.

180
ABCs of z/OS System Programming: Volume 9

© Copyright IBM Corp. 2011. All rights reserved.
181
Chapter 6.
Security customization
This chapter provides an overview of UNIX System Services security. It provides information
about how to customize the security definitions for z/OS UNIX System Services. In addition to
introducing the basic concepts of UNIX security, this chapter provides the details on how to:

Define new z/OS UNIX System Services users and groups

Change existing users and groups for z/OS UNIX System Services

Set up security for the z/OS UNIX System Services kernel

Set up security for z/OS UNIX System Services daemons

Set up security for z/OS UNIX System Services products

Define users and groups to RACF

Manage superusers

Define permissions bits and how they are used

Define RACF profiles for z/OS UNIX System Services

Protect the daemons programs

Understand server security

Utilize various auditing capabilities
The security configuration is an important prerequisite to enabling z/OS UNIX System
Services. At least minimal security work is required just to make z/OS UNIX start. After that,
the security configuration becomes increasingly more complex as users are defined and
workload is brought onto the system. This chapter gives you a comprehensive view of the
work required to set up z/OS UNIX in a way that is secure and in line with the needs of typical
business organizations.
6

182
ABCs of z/OS System Programming: Volume 9
6.1 RACF OMVS segments
Figure 6-1 Defining RACF OMVS segments
RACF profile OMVS segments
The RACF user profile definition was expanded with a segment called OMVS for z/OS UNIX
support. All users and programs that need access to z/OS UNIX must have a RACF user
profile defined with an OMVS segment which has, as a minimum, a UID specified. A user
without a UID cannot access z/OS UNIX.
RACF user profile
Within this profile is an OMVS segment that defines the user as a z/OS UNIX user. The
OMVS segment has the following three fields:
UID
A number from 0 to 2147483647 that identifies a z/OS UNIX user. A z/OS UNIX
user must have a UID defined.
HOME
The name of a directory in the file system. This directory is called the home
directory and becomes the current directory when the user accesses z/OS
UNIX. This field is optional.
The home directory is the current directory when a user invokes z/OS UNIX.
During z/OS UNIX processing, this can be changed temporarily by using the
cd

(change directory) shell command. The command will not change the value in
the RACF profile. The directory specified as home directory in the RACF profile
must exist (be pre-allocated) before a user can invoke z/OS UNIX. If a home
directory is not specified in RACF, the root (/) directory will be used as default.
Userid
Default
Group
Connect Groups
TSO
DFP
OMVS
UID Home
Program
15
/u/smith
/bin/sh
SMITH
PROG1
PROG1
PROG2
...
...
Groupid
Superior
Group
Connected Users
OMVS
GID
25
PROG1
PROGR
SMITHBROWN
...
...
Groupid
Superior
Group
Connected Users
PROG2
PROGR
SMITH
WHITE
...
...
Group
profile (no OMVS segment)
Group
profile
User
profile

Chapter 6. Security customization
183
PROGRAM
The name of a program. This is the program that will be started for the user
when the user begins a z/OS UNIX session. Usually this is the program name
for the z/OS UNIX shell. This field is optional.
RACF group profile
The RACF group also has a segment called OMVS to define z/OS UNIX groups. It contains
only one field:
GID
A number from 0 to 2147483647 that identifies a z/OS UNIX group.
Example segment
The example in Figure 6-1 on page 182 shows a user profile for TSO/E user ID SMITH which
is connected to two groups, PROG1 and PROG2. SMITH is defined as a z/OS UNIX user
because he has a UID specified. His home directory is /u/smith and he will get into the shell
when he issues the OMVS command because the name of the shell, /bin/sh, is specified as
the program name.
A program that will access z/OS UNIX and run as a started task (for example, RMFGAT) or a
daemon (for example, the inetd daemon, which is used for remote login (rlogin) to the shell via
TCP/IP) must also be defined to RACF with a user profile and a UID specified. This type of
user does not require a home directory or a program specified in the OMVS segment. The
home directory and program are important for people's user IDs.
The RACF profile for a group is also extended with an OMVS segment. A z/OS UNIX group is
a RACF group with a GID specified in the OMVS segment. The figure shows that group
PROG1 is also a z/OS UNIX group with a GID value of 25. The group PROG2 does not have
an OMVS segment and therefore is not a z/OS UNIX group.
Connected users
If a user is connected to several groups, the user has a level of group authority for each group.
If you are a connected user who has the group-SPECIAL attribute, you have the authority to:

Define new users to RACF (provided you also have the CLAUTH attribute for the USER
class)

Connect and remove users from the group

Delegate and change group authorities and set the default UACC for all new resources
belonging to members of the group

Modify, list, and delete the group profile

Define, delete, and list the names of the subgroups under the group

Specify the group terminal option

184
ABCs of z/OS System Programming: Volume 9
6.2 z/OS UNIX UIDs and GIDs
Figure 6-2 z/OS UNIX users UIDs and GIDs
Defining UIDs and GIDs
UNIX systems have a concept of users and groups similar to RACF. A user identifier (or UID)
is a number between 0 and some large number that varies between brands of UNIX. User
numbers do not have to be unique and it is possible (though not recommended) for several
users to share the same UID, and even be logged on at the same time. UNIX sees these
users as being the same entities and they receive the same levels of authorization. A user
with UID=0 is what is called a superuser (“root” on some brands of UNIX). A superuser has
unlimited authority within a UNIX environment. For obvious reasons, UID=0 needs to be
strictly controlled.
Users are all related to a group. Groups allow authority to be controlled in a more economical
way, in that giving access to a group is a lot easier than giving access to a few hundred users
individually. A group identifier (or GID) is a number between 0 and some large number that
varies between brands of UNIX. Any number of users can share the same GID.
The z/OS UNIX implementation of UNIX allows UID and GID numbers up to 2,147,483,647,
but due to restrictions in UNIX design, it is recommended that the maximum number used be
no more than 77,777,777.
Other UNIX platform security
UNIX systems typically store their user/group information in a file called
/etc/passwd
. This file
does not exist under z/OS UNIX, because RACF (a like security product) is used instead.
UID = user identifier
Number in range 0 - 2,147,483,647
But.... 0 - 16,777,215 due to
pax
protocol
0 = Superuser (Root)
GID = group identifier
Number in range 0 - 2,147,483,647
But.... 0 - 16,777,215 due to
pax
protocol
/etc/passwd

Chapter 6. Security customization
185
6.3 z/OS UNIX users and groups
Figure 6-3 Defining z/OS UNIX users and groups
Defining z/OS UNIX users and groups
z/OS UNIX users are TSO/E user IDs with a RACF segment called OMVS defined for z/OS
UNIX use. All users that want to use z/OS UNIX services must be defined as z/OS UNIX
users. Similar to users in a UNIX system, z/OS UNIX users are identified by a UID (user
identification). The UID has a numerical value.
There are two types of users:

User (regular user)
– Identified by a non-zero UID

Superuser (authorized/privileged user). A superuser can be any of the following:
– A z/OS UNIX user with a UID=0
– A started procedure with a trusted or privileged attribute in the RACF started
procedures table
Superusers
The concept of
superuser
comes from UNIX. Sometimes it is also referred to as
root

authority.
A superuser can:

Pass all z/OS UNIX security checks, so that the superuser can access any file in the
hierarchical file system. A superuser does not get any additional authorities to access
MVS/ESA resources. The authority is limited to the z/OS UNIX component.
SYSADM
GID=10
PROG1
GID=25
PROG2
GID=35
Superusers
Black
UID=0
BPXROOT
UID=0
Smith
UID=0
Brown
UID=15
Jones
UID=35
Greene
UID=40

186
ABCs of z/OS System Programming: Volume 9

Manage z/OS UNIX processes and files.

Have an unlimited number of processes running concurrently. For a started procedure, this
is true only if it has a UID of 0. It is not true for a trusted or privileged process with a
different UID.

Change identity from one UID to another.

Use the
setrlimit
command to increase any of the system limits for a process.
A superuser is usually a system administrator, or it can be a started procedure that is
authorized by the RACF started procedures table or the RACF STARTED class.
z/OS UNIX users belong to one or more groups in the same way that TSO/E users belong to
groups. A z/OS UNIX group is a RACF group with a GID defined. The GID has a numerical
value.
BPXROOT
If the target UID is 0 and a userid is not known, the setuid service sets the MVS userid to
BPXROOT, or to a userid that is specified as a PARMLIB option during installation.
BPXROOT is set up during system initialization as a superuser with a UID of 0. The
BPXROOT userid is not defined to the BPX.DAEMON FACILITY class profile. This special
processing is necessary to prevent a superuser from gaining daemon authority.
Reminder:
Multiple users may have the same UID.

Chapter 6. Security customization
187
6.4 BPXROOT user ID
Figure 6-4 Define a BPXROOT user ID
Defining BPXROOT
Define a superuser with a user ID of BPXROOT on all systems so that daemon processes
can invoke setuid() for superusers. Specify UID=0, a home directory of / (root), and the
program /bin/sh. BPXROOT should not have any special permission to MVS resources. This
user ID is used in rare cases where a daemon process tries to change the identity of a
process to superuser but does not know the MVS identity of the process. BPXROOT is the
default name.
Use of BPXROOT
If the target UID is 0 and a user ID is not known, the setuid service sets the MVS user ID to
BPXROOT, or to a user ID that is specified as a parmlib option during installation. BPXROOT
is set up during system initialization as a superuser with a UID of 0. The BPXROOT user ID is
not defined to the BPX.DAEMON profile in the FACILITY class. This special processing is
necessary to prevent a superuser from gaining daemon authority.
NOPASSWORD option
The NOPASSWORD option indicates that BPXROOT is a protected user ID that cannot be
used to enter the system by using a password or password phrase. The user ID will not be
revoked due to invalid logon attempts.
Define a superuser with a user ID of BPXROOT
Allows daemon processes to invoke setuid() for
superusers
NOPASSWORD option indicates that BPXROOT is
a protected user ID
BPXPRMxx parmlib member
SUPERUSER(BPXROOT)
ADDUSER BPXROOT DFLTGRP(OMVSGRP)
OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
NOPASSWORD

188
ABCs of z/OS System Programming: Volume 9
SUPERUSER statement
On the SUPERUSER statement in the BPXPRMxx parmlib member, specify the user ID that
the kernel will use when you need a user ID for UID(0):
SUPERUSER(BPXROOT)
Note:
If not specified, the default is BPXROOT. In that situation, do not permit the
BPXROOT user ID to BPX.DAEMON. The BPXROOT user ID is used when a daemon
process invokes setuid() to change the UID to 0 and the user name has not been
previously identified by getpwnam() or by the _passwd() function. This action prevents the
granting of daemon authority to a superuser who is not defined to BPX.DAEMON.

Chapter 6. Security customization
189
6.5 Superuser with appropriate authority
Figure 6-5 Defining superuser authority
Defining superuser authority
When you are defining users, you might want to define some of them with appropriate
superuser privileges, a UID of 0. There are three ways of assigning superuser authority, as
follows:

Assigning a UID of 0, which is the least desirable way

Using the BPX.SUPERUSER resource in the FACILITY class

Using the UNIXPRIV class profiles, the preferred way
While some functions require a UID of 0, in most cases you can choose among the three
ways. When choosing among them, try to minimize the number of user IDs (as opposed to
started procedures) with a UID(0) superuser authority. To summarize the choices, UID(0)
gives you access to all UNIX functions and resources, as is true for all UNIX systems.
BPX.SUPERUSER for superuser authority
However, in z/OS, RACF allows certain users to perform specific privileged functions without
being defined as UID(0). BPX.SUPERUSER allows you to request that you be given such
access, but you do not have the access unless you make the request.
Using UNIXPRIV for superuser authority
The UNIXPRIV class allows you to do specific privileged functions, such as mounting a file
system. Both these definitions are similar to having UID(0) in that, before RACF grants
access to a system resource or use of it, the system checks these definitions.
3 ways to assign superuser authority
Assigning a UID of 0, which is the least desirable way
Okay for special administrators
Using the BPX.SUPERUSER resource in the RACF
FACILITY class
Allows requesting superuser access, but you do not
have the access unless you make the request
Using the UNIXPRIV class profiles, the preferred way
Profiles in the UNIXPRIV class grant RACF
authorization for certain z/OS UNIX privileges

190
ABCs of z/OS System Programming: Volume 9
6.6 Commands for superusers
Figure 6-6 Superuser commands
Commands only for superusers
Superusers are special users in a z/OS UNIX environment and they are identified by a UID
value of 0. One way of defining superusers is to set the UID to 0 in the user's OMVS segment.
Using this method, the user always runs as a superuser. Multiple users can be defined with a
UID of 0.
Define some system administrators as superusers by adding an OMVS segment to their user
profile. Define the home directory as root (/). Add an OMVS segment to the groups to which
these users are connected.
Superuser commands
There are TSO and shell commands that can only be issued by a superuser or the file owner.
Several of these commands are shown in Figure 6-6.
chown
Used to change the owner or group of a file or directory.
chmod
Changes the access permissions
mount
Used to mount a file system
chgrp
Sets the group ID to group for the files and directories
su
Starts a new shell and lets you operate in it with the privileges of a superuser or
another user.
SYSADM
GID=10
BLACK
UID=0
JANE
UID=0
BROWN
UID=0
#
==>chown ...
z/OS UNIX Shell
TSO commands
Shell commands
mount
unmount
mknod
osteplib
su
mount
chown
chgrp
chmod

Chapter 6. Security customization
191
6.7 z/OS UNIX security and RACF profiles
Figure 6-7 z/OS UNIX RACF profiles for security
RACF profiles to provide security for z/OS UNIX
A RACF FACILITY class profile example follows to give a non-zero user superuser authority:
RDEFINE FACILITY BPX.SUPERUSER UACC(NONE)
PERMIT BPX.SUPERUSER CLASS(FACILITY) ID(JANE) ACCESS(READ)
Using the BPX.SUPERUSER resource in the FACILITY class is another way for users to get
the authority to do most of the tasks that require superuser authority. When they need to
perform superuser tasks, they can switch to superuser mode using the
su
command or the
“Enable superuser mode (SU)” option in the ISPF shell.
RACF FACILITY class resource names
The following are FACILITY class profiles you may want to define for z/OS UNIX:
BPX.DAEMON
BPX.DAEMON serves two functions in the z/OS UNIX environment:
– Any superuser permitted to this profile has the daemon authority to change MVS
identities via z/OS UNIX services without knowing the target user ID's password. This
identity change can only occur if the target user ID has an OMVS segment defined.
If BPX.DAEMON is not defined, then all superusers (UID=0) have daemon authority. If
you want to limit which superusers have daemon authority, define this profile and
permit only selected superusers to it.
RDEFINE FACILITY BPX.SUPERUSER UACC(NONE)
PERMIT BPX.SUPERUSER CLASS(FACILITY) ID(JANE) ACCESS(READ)
BPX.DAEMON
BPX.DEBUG
BPX.WLMSERVER
BPX.SUPERUSER
BPX.STOR.SWAP
BPX.SMF
BPX.SERVER
BPX.FILEATTR.PROGCTL
BPX.FILEATTR.APF
BPX.DEFAULT.USER
BPX.DAEMON.HFSCTL
BPX.NEXT.USER
BPX.FILEATTR.SHARELIB
BPX.JOBNAME
BPX.SAFFASTPATH
Define superuser authority

192
ABCs of z/OS System Programming: Volume 9
– Any program loaded into an address space that requires daemon level authority must
be defined to program control. If the BPX.DAEMON profile is defined, then z/OS UNIX
will verify that the address space has not loaded any executables that are uncontrolled
before it allows any of the following services that are controlled by z/OS UNIX to
succeed:
• seteuid
• setuid
• setreuid
• pthread_security_np()
• auth_check_resource_np()
• _login()
• _spawn() with user ID change
• _password()
BPX.DAEMON.HFSCTL

Controls which users with daemon authority are allowed to load uncontrolled programs
from MVS libraries into their address space.
BPX.DEBUG
Users with read access to the BPX.DEBUG FACILITY class profile can use
ptrace
(via
dbx) to debug programs that run with APF authority or with BPX.SERVER authority.
BPX.DEFAULT.USER
Not all users and groups need to have discrete OMVS segments defined for them. For
example:
– Users who need to use sockets and do not need any other UNIX services. In the past,
users could open sockets without any other special permissions.
– Users who want to run multithreading PL/1 programs. PL1 uses some kernel services,
so the OMVS segments are currently required to get dubbed.
– Users who just want to experiment with the shell and do not have an OMVS segment
defined.
The default OMVS segments will reside in a USER profile and a GROUP profile. The
names of these profiles are selected by the installation, and stored in the application data
field of BPX.DEFAULT.USER.
BPX.FILEATTR.APF
Controls which users are allowed to set the APF-authorized attribute in an HFS file. This
authority allows the user to create a program that will run APF-authorized. This is similar
to the authority of allowing a programmer to update 'SYS1.LINKLIB' or 'SYS1.LPALIB'.
BPX.FILEATTR.PROGCTL
Controls which users are allowed to set the program-controlled attribute in an HFS file.
Programs marked with this attribute can execute in server address spaces that run with a
high level of authority.
BPX.FILEATTR.SHARELIB

Indicates that extra privilege is required when setting the shared library extended attribute
via the chattr() callable service. This prevents the shared library region from being
misused.
BPX.JOBNAME

Controls which users are allowed to set their own job names by using the
_BPX_JOBNAME environment variable or the inheritance structure on spawn. Users with
READ or higher permissions to this profile can define their own job names.

Chapter 6. Security customization
193
BPX.NEXT.USER
Enables automatic assignment of UIDs and GIDs. The APPLDATA of this profile specifies
a starting value, or range of values, from which RACF will derive unused UID and GID
values.
BPX.SAFFASTPATH

Enables faster security checks for file system and IPC constructs.
BPX.SERVER

Restricts the use of the
pthread_security_np()
service. A user with at least READ or
WRITE access to the BPX.SERVER FACILITY class profile can use this service. It creates
or deletes the security environment for the caller's thread.
This profile is also used to restrict the use of the BPX1ACK service, which determines
access authority to z/OS resources. Servers with authority to BPX.SERVER must run in a
clean program-controlled environment. z/OS UNIX will verify that the address space has
not loaded any executables that are uncontrolled before it allows any of the following
services that are controlled by z/OS UNIX to succeed:
– seteuid
– setuid
– setreuid
– pthread_security_np()
– auth_check_resource_np()
– _login()
– _spawn() with user ID change
– _password()
BPX.SMF
Checks if the caller attempting to cut an SMF record is allowed to write an SMF record or
test if an SMF type or subtype is being recorded.
BPX.SRV.userid

Allows users to change their UID if they have access to BPX.SRV.userid, where uuuuuuuu
is the MVS user ID associated with the target UID. BPX.SRV.userid is a RACF
SURROGAT FACILITY class profile.
BPX.STOR.SWAP
Controls which users can make address spaces nonswappable. Users permitted with at
least READ access to BPX.STOR.SWAP can invoke the _mlockall() function to make their
address space either nonswappable or swappable.
When an application makes an address space nonswappable, it may cause additional real
storage in the system to be converted to preferred storage. Because preferred storage
cannot be configured offline, using this service can reduce the installation's ability to
reconfigure storage in the future. Any application using this service should warn the
customer about this side effect in their installation documentation.
BPX.SUPERUSER
Users with access to the BPX.SUPERUSER FACILITY class profile can switch to
superuser authority (effective UID of 0).
BPX.WLMSERVER
Controls access to the WLM server functions _server_init() and _server_pwu(). A server
application with read permission to this FACILITY class profile can use the server
functions, as well as the WLM C language functions, to create and manage work requests.

194
ABCs of z/OS System Programming: Volume 9
6.8 z/OS UNIX security: BPX.SUPERUSER
Figure 6-8 Using BPX.SUPERUSER to define superuser authority
Superuser authority with BPX.SUPERUSER profiles
There is an alternative way of defining superusers. Define system administrators in RACF
with non-zero UIDs, and give them READ access to a RACF FACILITY class called
BPX.SUPERUSER. Users with this authority will be able to temporarily switch to become
superuser when this authority is required for administrative tasks. These users can use any of
the following methods to switch to superuser:

In the z/OS UNIX shell, use the command
su
(switch user). This command creates a
subshell where the user will have superuser authority and authorized commands can be
executed. When the subshell session is ended, the user returns to the first shell session
as a regular user.

Use the ISHELL command to enter the z/OS UNIX ISPF Shell. Select the option to switch
to superuser state. The user will then have superuser authority until the user exits the
ISHELL environment.

After gaining superuser authority in the ISHELL, you can do a split screen in ISPF and
enter the OMVS command. The z/OS UNIX shell that is started inherits the superuser
authority set up in the ISHELL.
The su command
Enter the shell using the OMVS command and then issue the
su
command with no operands.
This creates a nested shell that runs with superuser authority. With the
su
command, you can
switch to any user ID, including the superuser. A user can switch to superuser authority (with
an effective UID of 0, if the user is permitted to the BPX.SUPERUSER resource in the
BLACK
UID=5
JANE
UID=6
BROWN
UID=7
RACF FACILITY Class
BPX.SUPERUSER
BLACK
JANE
BROWN
$
==> su
#
==> chown
...
Regular
User
Superuser
RDEFINE FACILITY BPX.SUPERUSER UACC(NONE)
PERMIT BPX.SUPERUSER CLASS(FACILITY) ID(BLACK) ACCESS(READ)
SYSADM
GID=10

Chapter 6. Security customization
195
FACILITY class within RACF. Either the ISPF shell or the
su
shell command can be used for
switching to superuser authority.
If you do not specify a user ID, the
su
command changes your authorization to that of the
superuser. If you specify a user ID,
su
changes your authorization to that of the specified user
ID.
When you change the user ID by specifying a user ID and password or password phrase, you
assume the MVS identity of the new user ID even if the user ID has UID 0.
If you use the
-s
option on the
su
command, you will not be prompted for a password. Use this
option if you have access to the BPX.SRV.userid SURROGAT class profile. The userid is the
MVS user ID associated with the target UID.
To return to your own user ID, type:
exit
This returns you to the shell in which you entered the
su
command.
chown command
The
chown
command sets the user ID (UID) to the owner for the files and directories named by
pathname arguments. The owner can be a user name from the user data base, or it can be a
numeric user ID. (If a numeric owner exists as a user name in the user data base, the user ID
number associated with that user name is used.)
If you include a group name (that is, if you specify owner followed immediately by a colon (:)
and then group with no intervening spaces, such as owner:group)
chown
also sets the group
ID (GID) to the group for the files and directories named. The group can be a group name
from the security facility group data base, or it can be a numeric group ID. If a numeric group
exists as a group name in the group data base, the group ID number associated with that
group is used. If there is no change to the GID, then specify -1 (or do not specify the :group).

196
ABCs of z/OS System Programming: Volume 9
6.9 z/OS UNIX superuser granularity
Figure 6-9 Adding superuser granularity for access
Superuser authority
A superuser can:

Pass all security checks, so that the superuser can access any file in the file system.

Manage processes.

Have an unlimited number of processes running concurrently. For a started procedure, this
is true only if it has a UID of 0. It is not true for a trusted or privileged process with a
different UID.

Change identity from one UID to another.

Use setrlimit to increase any of the system limits for a process.
RACF UNIXPRIV class
You can define profiles in the UNIXPRIV class to grant RACF authorization for certain z/OS
UNIX privileges. By defining profiles in the UNIXPRIV class, you can specifically grant certain
superuser privileges with a high degree of granularity to users who do not have superuser
authority. This allows you to minimize the number of assignments of superuser authority at
your installation and reduces your security risk.
Resource names in the UNIXPRIV class are associated with z/OS UNIX privileges. You must
define profiles in the UNIXPRIV class protecting these resources in order to use RACF
authorization to grant z/OS UNIX privileges. The UNIXPRIV class must be active and
Superuser security exposure
Can execute all commands
Access all HFS files in the system
Applicable to every superuser

RACF UNIXPRIV class
Give a user superuser function for specific task

Chapter 6. Security customization
197
SETROPTS RACLIST must be in effect for the UNIXPRIV class. Global access checking is
not used for authorization checking to UNIXPRIV resources.
Assigning superuser authority using the UNIXPRIV class
You may choose to assign the UID of 0 to multiple RACF user IDs. However, you should seek
to minimize the assignment of superuser authority in your installation. You can accomplish
this by setting z/OS UNIX user limits and by managing superuser privileges through
UNIXPRIV profiles.
This RACF profile allows a normal user to become a superuser for only a specific superuser
function.

198
ABCs of z/OS System Programming: Volume 9
6.10 Resource names: UNIXPRIV
Figure 6-10 Profiles in the RACF UNIXPRIV class
UNIXPRIV RACF profiles
You can define profiles in the UNIXPRIV class to grant RACF authorization for certain z/OS
UNIX privileges. These privileges are automatically granted to all users with z/OS UNIX
superuser authority. By defining profiles in the UNIXPRIV class, you can specifically grant
certain superuser privileges, with a high degree of granularity, to users who do not have
superuser authority. This allows you to minimize the number of assignments of superuser
authority at your installation and reduces your security risk.
Resource names for profiles
Resource names in the UNIXPRIV class are associated with z/OS UNIX privileges. You must
define profiles in the UNIXPRIV class protecting these resources in order to use RACF
authorization to grant z/OS UNIX privileges. The UNIXPRIV class must be active and
SETROPTS RACLIST must be in effect for the UNIXPRIV class. Global access checking is
not used for authorization checking to UNIXPRIV resources. The following profiles are:

CHOWN.UNRESTRICTED
ACCESS required (NONE). Allows all users to use the
chown
command to transfer
ownership of their own files.

FILE.GROUPOWNER.SETGID
Specifies that a directory's set-gid bit is used to determine the group owner of any new
objects created within the directory.
CHOWN.UNRESTRICTED - NONE
FILE.GROUPOWNER.SETGID - NONE
RESTRICTED.FILESYS.ACCESS - NONE
SUPERUSER.FILESYS - READ - UPDATE - CONTROL
SUPERUSER.FILESYS.CHOWN - READ
SUPERUSER.FILESYS.MOUNT - READ - UPDATE
SUPERUSER.FILESYS.PFSCTL - READ
SUPERUSER.QUIESCE - READ - UPDATE
SUPERUSER.IPC.RMID - READ
SUPERUSER.PROCESS.GETPSENT - READ
SUPERUSER.PROCESS.KILL - READ
SUPERUSER.PROCESS.PTRACE - READ
SUPERUSER.SETPRIORITY - READ
SUPERUSER.FILESYS.VREGISTER - READ
SHARED.IDS - NONE
SUPERUSER.FILESYS.ACLOVERRIDE - NONE
RESTRICTED.FILESYS.ACCESS - NONE
SUPERUSER.FILESYS.CHANGEPERMS - READ

Chapter 6. Security customization
199

SUPERUSER.FILESYS
ACCESS required (READ). Allows you to read any HFS file, and to read or search any
HFS directory.
ACCESS required (UPDATE). Allows you to write to any HFS file, and includes privileges
of READ access.
ACCESS required (CONTROL or higher). Allows you to write to any HFS directory, and
includes privileges of UPDATE access.

SUPERUSER.FILESYS.CHOWN
ACCESS required (READ). Allows you to use the
chown
command to change ownership of
any file.

SUPERUSER.FILESYS.MOUNT
ACCESS required (READ). Allows you to issue the TSO/E MOUNT command or the
mount

shell command with the nosetuid option. Also allows you to unmount a file system with the
TSO/E UNMOUNT command or the
unmount
shell command mounted with the
nosetuid

command. Users permitted to this profile can use the
chmount
shell command to change
the mount attributes of a specified file system.
ACCESS required (UPDATE). Allows user to issue the TSO/E MOUNT command or the
mount
shell command with the setuid option. Also allows user to issue the TSO/E
UNMOUNT command or the
unmount
shell command with the setuid option. Users
permitted to this profile can issue the
chmount
shell command on a file system that is
mounted with the setuid option.

SPERUSER.FILESYS.QUIESCE
ACCESS required (READ). Allows users to issue
quiesce
and
unquiesce
commands for a
file system mounted with the nosetuid option.
ACCESS required (UPDATE). Allows users to issue
quiesce
and
unquiesce
commands for
a file system mounted with the setuid option.

SUPERUSER.FILESYS.PFSCTL
ACCESS required (READ). Allows users to use the
pfsctl()
callable service.

SUPERUSER.FILESYS.VREGISTER
ACCESS required (READ). Allows a server to use the
vreg()
callable service to register
as a VFS file server.

SUPERUSER.IPC.RMID
ACCESS required (READ). Allows users to issue the
ipcrm
command to release IPC
resources.

SUPERUSER.PROCESS.GETPSENT
ACCESS required (READ). Allows users to use the
w_getpsent
callable service to receive
data for any process.

SUPERUSER.PROCESS.KILL
ACCESS required (READ). Allows users to use the
kill()
callable service to send signals
to any process.

SUPERUSER.PROCESS.PTRACE
ACCESS required (READ). Allows users to use the
ptrace()
function through the dbx
debugger to trace any process. Allows users of the
ps
command to output information on
all processes. This is the default behavior of ps on most UNIX platforms.

200
ABCs of z/OS System Programming: Volume 9

SUPERUSER.SETPRIORITY
ACCESS required (READ). Allows users to increase their own priority.

SHARED.IDS
Allows users to assign UID and GID values that are not unique.

SUPERUSER.FILESYS.ACLOVERRIDE
Specifies that ACL contents override the access that was granted by
SUPERUSER.FILESYS. Can be overridden for specific users or groups. The user or
group must have the same access that would be required to SUPERUSER.FILESYS while
accessing the file.

SUPERUSER.FILESYS.CHANGEPERMS
Allows users to use the
chmod
command to change the permission bits of any file and to
use the
setfacl
command to manage access control lists for any file.

Chapter 6. Security customization
201
6.11 z/OS UNIX UNIXPRIV class profiles
Figure 6-11 Defining superuser authority with the UNIXPRIV class
Defining profiles in the UNIXPRIV class
You can reduce the number of people who have superuser authority at you installation by
defining profiles in the UNIXPRIV class that grant RACF authorization for certain z/OS UNIX
privileges.
Normally, these privileges are automatically defined for all users who are defined with z/OS
UNIX superuser authority. But you can use UNIXPRIV to grant certain superuser privileges,
with a high degree of granularity, to users who do not have superuser authority.
UNIXPRIV class example
For example, if users have READ access to SUPERUSER.FILESYS.MOUNT, they can issue
a
mount
and
unmount
command without being a defined superuser with all superuser
capabilities, as follows:
RDEFINE UNIXPRIV SUPERUSER.FILESYS.MOUNT UACC(NONE)
PERMIT SUPERUSER.FILESYS.MOUNT CLASS(UNIXPRIV) ID(SMITH) ACCESS(READ)
SETROPTS RACLIST(UNIXPRIV) REFRESH
Now user SMITH (UID=35) can issue mounts, which is a superuser function. This is the only
superuser function user SMITH can do.
SETROPTS CLASSACT(UNIXPRIV)
RDEFINE UNIXPRIV SUPERUSER.FILESYS.MOUNT
UACC(NONE)
PERMIT SUPERUSER.FILESYS.MOUNT
CLASS(UNIXPRIV) ID(SMITH) ACCESS(READ)
SETROPTS RACLIST(UNIXPRIV)
RACF Class - UNIXPRIV

RDEFINE UNIXPRIV resource-name UACC( )

202
ABCs of z/OS System Programming: Volume 9
6.12 Assigning UIDs
Figure 6-12 Assigning UIDs with shared UID prevention
Assigning UIDs
z/OS UNIX allows multiple users to have the same UID. Assigning the same UID to multiple
user IDs allows each user to access all of the resources associated with the other users of
that shared user ID. The shared access includes not only z/OS UNIX resources such as files,
but also includes the possibility that one user could access z/OS resources of the other users
that are normally considered to be outside the scope of z/OS UNIX.
You can assign a z/OS UNIX user identifier (UID) to a RACF user by specifying a UID value in
the OMVS segment of the RACF user profile. This can be an employee serial number or
some other unique number for each user.
When assigning a UID to a user, make sure that the user is connected to at least one group
that has an assigned GID. This group should be either the user's default group or one that the
user specifies during logon or on the batch job. A user with a UID and a current connect group
with a GID can use z/OS UNIX functions and access z/OS UNIX files based on the assigned
UID and GID values. If a UID and a GID are not available as described, the user cannot use
z/OS UNIX functions.
Note:
This function was added in z/OS V1R4.
Make UIDs unique, or users end up 'sharing' files
Assign manually - ADDUSER OMVS(UID(37850))
Use employee serial number, if you can - or
SHARED.IDS profile UNIXPRIV class - z/OS V1R4
Acts as a system-wide switch to prevent assignment of
an ID that is already in use
Enable shared UID prevention
RDEFINE UNIXPRIV SHARED.IDS UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
IRR52174I Incorrect UID 12. This value is already in use by BRADY.
IRR52185I The same UID cannot be assigned to more than one user.
ADDUSER MARCY OMVS(UID(12))
ADDUSER (HARRY MARY) OMVS(UID(14))
BRADY
OMVS
UID=12
RACF DB
PATS
OMVS
GID=46

Chapter 6. Security customization
203
Shared UID prevention option
In order to prevent several users from having the same UID number, a new RACF
SHARED.IDS profile has been introduced in the UNIXPRIV class. This new profile acts as a
system-wide switch to prevent assignment of a UID that is already in use. The use of the
SHARED.IDS profile requires AIM stage 2 or 3. To enable shared UID prevention, it is
necessary to define a new SHARED.IDS profile in the UNIXPRIV class, as follows:
RDEFINE UNIXPRIV SHARED.IDS UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
SHARED.IDS examples
Once the SHARED.IDS profile has been defined and the UNIXPRIV class refreshed, it will not
allow a UID to be assigned if the UID is already in use.
As shown in Figure 6-12 on page 202, UID 12 is not assigned to user MARCY because in the
RACF database this UID is assigned to user BRADY. Also, users HARRY and MARY can not
be assigned the same UID 14.
The same is true for GIDs; it will not allow a GID to be shared between different groups.
Note:
The use of this new functionality does not affect pre-existing shared UIDs. They
remain as shared once you install the new support. If you want to eliminate sharing of the
same UID, you must clean them up separately. The release provides a new IRRICE report
to find the shared UIDs.

204
ABCs of z/OS System Programming: Volume 9
6.13 Shared UID prevention
Figure 6-13 Using the SHARED keyword to allow duplicate UID assignment
Allowing duplicate user IDs
You may want to assign the same UID to multiple user IDs if these user IDs are used by the
same person or persons. It may also be necessary to assign multiple users a UID of 0
(superuser authority). When doing this, it is important to remember that a superuser is
implicitly a trusted user who has the potential of using UID(0) to access all z/OS resources.
Even if the SHARED.IDS profile is defined, you may still require some UIDs to be shared and
others not to be shared. For example, you may require multiple superusers with a UID(0). It is
possible to do this using the new SHARED keyword in the OMVS segment of the ADDUSER,
ALTUSER, ADDGROUP, and ALTGROUP commands.
To allow an administrator to assign a non-unique UID or GID using the SHARED keyword,
you must grant that administrator at least READ access to the SHARED.IDS profile and be at
the z/OS V1R4 level or above, as follows:
PERMIT SHARED.IDS CLASS(UNIXPRIV) ID(UNIXGUY) ACCESS(READ)
SETROPTS RACLIST(UNIXPRIV) REFRESH
Once user ID UNIXGUY has at least READ access to the SHARED.IDS profile, UNIXGUY
can assign the same UID or GID to multiple users, using the SHARED KEYWORD, as
follows: ADDUSER OMVSKERN OMVS(UID(0) SHARED)
Note:
To specify the SHARED operand, you must have the SPECIAL attribute or at least
READ authority to the SHARED.IDS profile in the UNIXPRIV class.
BPXOINIT
OMVS
UID=0
RACF DB
New SHARED keyword
OMVS segment of the ADDUSER, ALTUSER, ADDGROUP,
and ALTGROUP commands
IRR52175I You are not authorized to specify the SHARED keyword.
AU OMVSKERN OMVS(UID(0) SHARED)
AU MYBUDDY OMVS(UID(0) SHARED)
AG (G1 G2 G3) OMVS(GID(9) SHARED)
UNIXGUY
HARRY
To specify the SHARED operand, you must have the SPECIAL attribute or
at least READ authority to the SHARED.IDS profile in the UNIXPRIV class
PERMIT SHARED.IDS CLASS(UNIXPRIV) ID(UNIXGUY) ACC(READ)
SETROPTS RACLIST(UNIXPRIV) REFRESH

Chapter 6. Security customization
205
6.14 Automatic UID and GID assignment
Figure 6-14 Assigning UIDs and GIDs automatically
Specifying automatic assignment of UIDs and GIDs
You can assign a z/OS UNIX user identifier (UID) and group identifier (GID) to a RACF user
by specifying a UID value in the OMVS segment of the RACF user profile or by using the
AUTOUID and AUTOGID keywords.
UIDs and GIDs can be assigned automatically by RACF to new users, making it easier to
manage the process of assigning UIDs and GIDs to users. Previously, this was a manual
process and guaranteed the uniqueness of the UID and GID for every user.
Using a new AUTOUID keyword with the ADDUSER and ALTUSER commands, an unused
UID will be assigned to the new or modified user. Using the AUTOGID keyword on the
ADDGROUP and ALTGROUP commands, a GID will be assigned automatically to the new or
modified group.
Note:
When assigning a UID to a user, make sure that the user is connected to at least
one group that has an assigned GID. This group should be either the user's default group
or one that the user specifies during logon or on the batch job. A user with a UID and a
current connect group with a GID can use z/OS UNIX functions and access z/OS UNIX
files based on the assigned UID and GID values. If a UID and a GID are not available as
described, the user cannot use z/OS UNIX functions.
Note:
This function was added in z/OS V1R4.
New AUTOUID and AUTOGID keywords
OMVS segment of the ADDUSER and ALTUSER
OMVS segment of the ADDGROUP and ALTGROUP
Derived values are guaranteed to be unique
Automatic assignment by RACF with z/OS V1R4
IRR52177I User MARY was assigned an OMVS UID value of 4646
IRR52177I Group PAYR was assigned an OMVS GID value of 105
ADDUSER MARY OMVS(AUTOUID)
ADDGROUP PAYR OMVS(AUTOGID)

206
ABCs of z/OS System Programming: Volume 9
6.15 Automatic assignment requirements
Figure 6-15 Requirements for automatic assignment of UIDs and GIDs
Application identity mapping
Application identity mapping (AIM) must be implemented if you wish to define and use
SHARED.IDS. If the RACF command detects that the SHARED.IDS profile is defined, but the
RACF database is not at least at AIM stage 2, the command fails and message IRR52176I is
issued. Refer to
z/OS Security Server RACF System Programmer's Guide
, SA22-7681 for
more information on using the IRRIRA00 utility to advance to AIM stage 2.
Automatic assignment requirements
A SHARED.IDS profile allows users to assign UID and GID values that are not unique.
The use of automatic UID/GID requires the following:

You can convert your RACF database to stage 3 of application identity mapping using the
IRRIRA00 conversion utility. It converts an existing RACF database to application identity
mapping functionality using a four-stage approach. Install AIM stage 2 or 3, otherwise an
IRR52182I message is issued and the automatic assignment attempt fails with the
following message:
IRR52182I Automatic UID assignment requires application identity mapping to
be implemented.

A SHARED.IDS profile must be defined, otherwise, an IRR52183I message is issued and
the attempt fails with the following message:
IRR52183I Use of automatic UID assignment requires SHARED.IDS to be
implemented.
AIM stage 2 or 3 is required -
IRR52182I message
SHARED.IDS
must
be defined -
IRR52183I
message
The SHARED.IDS profile is defined as follows:
RDEFINE UNIXPRIV SHARED.IDS UACC(NONE)
SHARED.IDS
- Allows assigning UID/GID values that
are unique. It acts as a system-wide switch to prevent
assignment of an ID which is already in use
The BPX.NEXT.USER Facility class profile must be
defined and RACLISTed -
IRR52179I
message
RDEFINE FACILITY BPX.NEXT.USER APPLDATA(UID/GID)
SETROPTS RACLIST(FACILITY) REFRESH

Chapter 6. Security customization
207

The SHARED.IDS must be defined as follows:
RDEFINE UNIXPRIV SHARED.IDS UACC(NONE)
The BPX.NEXT.USER profile
RACF can automatically generate a unique ID value in the OMVS segment upon your
request. This is done by defining a profile called BPX.NEXT.USER in the FACILITY class by
specifying the following:

The AUTOUID operand of the ADDUSER and ALTUSER commands

The AUTOGID operand of the ADDGROUP and ALTGROUP commands

The BPX.NEXT.USER facility class profile must be defined and RACLISTed. Otherwise,
an IRR52179I message will be issued and the attempt fails with the following message:
IRR52179I The BPX.NEXT.USER profile must be defined before you can use
automatic UID assignment.

208
ABCs of z/OS System Programming: Volume 9
6.16 Automatic assignment examples
Figure 6-16 Examples of assigning UIDs and GIDs automatically
Automatic assignment using APPLDATA
APPLDATA consists of 2 qualifiers separated by a forward slash (/). The qualifier on the left of
the slash character specifies the starting UID value or range of UID values. The qualifier on
the right of the slash character specifies the starting GID value or range of GID values.
Qualifiers can be null or specified as
'NOAUTO'
to prevent automatic assignment of UIDs or
GIDs.
The starting value is the value RACF attempts to use in ID assignment, after determining that
the ID is not in use. If it is in use, the value is incremented until an appropriate value is found.
The maximum value valid in the APPLDATA specification is 16,777,215. If this value is
reached or a candidate UID/GID value has been exhausted for the specified range,
subsequent automatic ID assignment attempts fail and message IRR52181I is issued.
Profile examples
In the following example, we have defined the APPLDATA for a range of values from 5 to
70000 for UIDs and from 3 to 30000 for GIDs. USERA and USERB are added using the
automatic assignment of UID. The range of automatic UID assignment starts with 5, so
USERA is assigned to UID(5), which was free. UID(6) and UID(7) were already assigned
before we started our example, so the next free UID is 8. USERB is assigned to UID(8).
RDEFINE FACILITY BPX.NEXT.USER APPLDATA('5-70000/3-30000')
ADDUSER USERA OMVS(AUTOUID)
RDEFINE FACILITY BPX.NEXT.USER APPLDATA('5-70000/3-30000')
ADDUSER USERA OMVS(AUTOUID)
IRR52177I User USERA was assigned an OMVS UID value of 5.
ADDUSER USERB OMVS(AUTOUID)
IRR52177I User USERB was assigned an OMVS UID value of 6.
Profile examples
Other Examples of APPLDATA
RDEFINE FACILITY BPX.NEXT.USER APPLDATA('1/0')
RALTER FACILITY BPX.NEXT.USER APPLDATA('2001/201')
RDEFINE FACILITY BPX.NEXT.USER APPLDATA('NOAUTO/3000')

Chapter 6. Security customization
209
IRR52177I User USERA was assigned an OMVS UID value of 5.
ADDUSER USERB OMVS(AUTOUID)
IRR52177I User USERB was assigned an OMVS UID value of 6.
RACF assigns the UID or GID
RACF extracts the APPLDATA from the BPX.NEXT.USER and parses out the starting value. It
checks whether it is already in use and if so, the value is incremented and checked again until
an unused value is found. Once a free value is found, it assigns the value to the user or group
and replaces the APPLDATA with the new starting value, which is the next potential value or
the end of the range.
In our example, that means that if UID(6) is free after UID(5) is assigned to USERA, RACF
will start checking from UID(7) in the next assignment. But you can change the APPLDATA
and modify the starting value. The APPLDATA can be changed using the following command:
RALTER FACILITY BPX.NEXT.USER APPLDATA('2000/500')
Other examples of APPLDATA
Here are some examples of correct and incorrect APPLDATA specifications:
Good data
1/0
1-50000/1-20000
NOAUTO/100000
/100000
10000-20000/NOAUTO
10000-20000/
Bad data
123B
/
2147483648 /* higher than max UID value */
555/1000-900
If you have an incorrect specification and attempt to use AUTOUID on an ADDUSER
command, the following message is issued:
IRR52187I Incorrect APPLDATA syntax for the BPX.NEXT.USER profile.
Note:
Automatic assignment of UIDs and GIDs fails if you specify a list of users to be
defined with the same name or if you specify the
SHARED
keyword. Also,
AUTOUID
or
AUTOGID

is ignored if UID or GID is also specified.

210
ABCs of z/OS System Programming: Volume 9
6.17 Automatic assignment with RRSF
Figure 6-17 Automatic assignment with RRSF
RACF remote sharing facility (RRSF)
The RACF remote sharing facility allows RACF to communicate via APPC with other MVS
systems that use RACF, allowing you to maintain remote RACF databases. RRSF extends
the RACF operating environment beyond the traditional single host and shared DASD
environments, to an environment made up of RRSF nodes that are capable of communicating
with one another. This support provides administration of multiple RACF databases from
anywhere in the RRSF network.
Use nonoverlapping APPLDATA ranges
In an RRSF configuration, shown in Figure 6-17, use nonoverlapping APPLDATA ranges to
avoid UID and GID duplications.
An additional concern is to make RACF automatically suppress propagation of internal
updates. This can be done by specifying the
ONLYAT
keyword to manage the
BPX.NEXT.USER profile, as follows:
RDEFINE BPX.NEXT.USER APPLDATA('5000-10000/5000-10000') ONLYAT(NODEA.MYID)
RDEFINE BPX.NEXT.USER APPLDATA('10001-20000/10001-20000') ONLYAT(NODEB.MYID)
For more information about automatic assignment in a RRSF configuration, refer to
z/OS
Security Server RACF Security Administrator’s Guide
, SA22-7683.
NODEA
NODEB
BPX.NEXT.USER
5000-10000
/
5000-10000
RACF DB
ADDUSER HARRY OMVS(AUTOUID)
ADDUSER MARY OMVS(AUTOUID)
BPX.NEXT.USER
10001-20000
/
10001-20000
RACF DB
USER profile updates kept in sync
AU HARRY OMVS(AUTOUID UID(5000))
AU MARY OMVS(AUTOUID UID(10001))
Use non-overlapping APPLDATA ranges to avoid UID/GID duplication
RDEF BPX.NEXT.USER APPLDATA('500-1000/500-1000') ONLYAT(NODEA.MYID)
RDEF BPX.NEXT.USER APPLDATA('1001-2000/1001-2000') ONLYAT(NODEB.MYID)

Chapter 6. Security customization
211
6.18 z/OS UNIX security: File security packet
Figure 6-18 File security packet definitions
File security packet (FSP)
Each z/OS UNIX file and directory has a file security packet (FSP) associated with it to control
access. The FSP is created when a file or directory is created. It is stored in the file system for
the life of the file or directory, until the file or directory is deleted, at which time the FSP is also
deleted. The FSP consists of:

File owner UID

File owner GID

File mode
Extended attributes
Another section of the FSP, which is specific to the z/OS UNIX implementation, is called
extended attributes (extattr). It contains flags to mark HFS program files as APF-authorized
and program controlled. The
extattr
shell command is used to manipulate these bits.
File Mode
The file mode consists of:
SetUID
This bit only relates to executable files. If on, it causes the UID of the user
executing the file to be set to the file's UID.
SetGID
This bit only relates to executable files. If on, it causes the GID of the user
executing the file to be set to the file's GID.
Sticky Bit
This bit only relates to executable files. If on, it causes the file to be retained in
memory for performance reasons. The implementation of this varies between
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w
x
r
w
x
r
w
x
Owner Group Other
File Permission Bits
File Mode
Access
Permission for File
Permission for Directory
Read
(
r
)
Permission to read or print the
contents.
Permission to read, but not
search, the contents.
Write
(
w
)
Permission to change, add to,
or delete from the contents.
Permission to change, add, or
delete directory entries.
Execute
(
x
)
Permission to run the file. This
permission is used for
executable files.
Permission to search the
directory.
extattr

212
ABCs of z/OS System Programming: Volume 9
platforms. In z/OS UNIX, it means programs are loaded from LPA (or LNKLST
as per normal MVS program search) instead of an HFS file. For a directory, the
sticky bit causes UNIX to permit files in a directory or subdirectories to be
deleted or renamed only by the owner of the file, or by the owner of the directory,
or by a superuser.
Sticky bit for directories
Using the
mkdir
, MKDIR, or
chmod
command, you can set the sticky bit on a directory to
control permission to remove or rename files or subdirectories in the directory. When the bit is
set, a user can remove or rename a file or remove a subdirectory only if one of these is true:

The user owns the file or subdirectory.

The user owns the directory.

The user has superuser authority.
If you use the rmdir, rename, rm, or mv utility to work with a file, and you receive a message
that you are attempting an “operation not permitted,” check to see if the sticky bit is set for the
directory the file resides in.
Permission bits
The file mode also has the file permission bits, consisting of:

Owner read/write/execute permissions

Group read/write/execute permissions

Other (or all users) read/write/execute permissions
where:
r
Read (
r
) access to both files and directories
w
Write (
w
) access to both files and directories
x
Execute (
x
) has a different meaning for files and directories, as follows:
- For an executable file, an access of
x
means that the user can execute the file.
- For a directory, an access of
x
means the user can search the directory.
Both read (
r
) and execute (
x
) are required in order to execute a shell script. To access HFS
files, a user needs the following:

Search (
x
) permission to all the directories in the pathname of files the user wants to
access.

Write permission to directories where the user will be creating new files and directories.

Read and/or write permission, as appropriate, to files for access.

Execute (
x
) permission for an executable file.
Note:
In z/OS UNIX, these three permissions are not hierarchical. For example, a user with
write permission who does
not

have read permission, can only write over existing data or
add data to a file, and cannot look at the contents of the file or print the file. Similarly, write
and read permission does not allow a user to execute a file or search a directory.

Chapter 6. Security customization
213
6.19 Octal values for permission bits
Figure 6-19 Octal values of permission bit settings
Permission bits in octal
z/OS UNIX commands typically allow the definition of permission bit settings using octal
notation. It is a simpler way to describe the permission bit string.
The octal numbers relate to the bit positions as follows:
Dec Bin Map
=== === ===
0 = 000 = ---
1 = 001 = --x
2 = 010 = -w-
3 = 011 = -wx
4 = 100 = r--
5 = 101 = r-x
6 = 110 = rw-
7 = 111 = rwx
where:
Dec
Decimal representation of the octal value
Bin
Binary representation of the octal value
Map
Map of permission bits according to binary positions
0
---
No access
1
--x
Execute-only
2
-w-
Write-only
3
-wx
Write and execute
4
r--
Read-only
5
r-x
Read and execute
6
rw-
Read and write
7
rwx
Read, write and execute
Permission Bit Examples:
700
owner(
7
=rwx) group(
0
=---) other(
0
=---
)
755
owner(
7
=rwx) group(
5
=r-x) other(
5
=r-x
)
XXX
421
To change the permission bits for a file:
The ISPF shell
The chmod and setfacl commands
The chmod() function in a program

214
ABCs of z/OS System Programming: Volume 9
Permission bit settings
UNIX commands such as
chmod
accept octal notation when referring to permission bit
settings.
A permission bit setting of 700 is good for a user's private files, allowing the owner full access
while denying access to others.
A permission bit setting of 755 is good for a user to let other people access their files (read
and execute), but not update them.
Changing permission bit settings
To change the permission bits for a file, use one of the following:

The ISPF shell.

The
chmod
command. You can use it to change individual bits without affecting the other
bits. You can also use the
setfacl
command to change permission bits.

The
chmod()
function in a program. The function changes all permission bits to the values
in the mode argument.

Chapter 6. Security customization
215
6.20 Data set security versus file security
Figure 6-20 MVS data set security versus file system security
MVS security versus z/OS UNIX security
Security processing within z/OS UNIX differs in many ways from standard security processing
in MVS. MVS resources like users and data are protected by RACF profiles stored in the
RACF database. RACF refers to the profiles when deciding which users should be permitted
to protected system resources. Security administration is done with RACF commands or
RACF ISPF panels.
z/OS UNIX users are defined as MVS users and they are administrated by RACF profiles.
The security information for files and directories in a hierarchical file system is stored within
the file system itself in a file security packet (FSP). HFS files and directories are protected by
permission bit information which is kept in the FSP. Administration of file security is performed
by using z/OS UNIX shell commands, or ISHELL menu options.
The user administration is similar for regular MVS users and z/OS UNIX users. Every user
must present a password when logging on to the system. z/OS UNIX uses a UID and GID for
each user and this information is stored in RACF profiles together with the user ID and
password information. The concept of a superuser in z/OS UNIX is similar to a RACF security
administrator.
z/OS UNIX users do not work with data sets, they work with files and directories. z/OS UNIX
users do not have to be aware that their data is located physically in an HFS data set. All they
see is the hierarchical file structure made up of multiple mounted HFS data sets. The FSPs
are maintained by z/OS UNIX commands. RACF data set profiles cannot be used to protect
z/OS UNIX files and directories.
RACF
administrator
MVS Data Set Security:UNIX File Security:
z/OS UNIX
Superuser
Access to all data sets
Access to all files
All other
users
All other
users
Access to a data set
if RACF profile permits
Access to a file if
permission bits allow
or ACL allows (z/OS 1.3)
or UNIXPRIV allows

216
ABCs of z/OS System Programming: Volume 9
6.21 z/OS UNIX user’s security environment
Figure 6-21 A z/OS UNIX user’s file security environment
User’s security environment
Authorization checking for z/OS UNIX files and directories uses the control blocks shown in
Figure 6-21, and RACF makes the following checks:

The accessor environment element (ACEE) is a control block that contains a description of
the current user's security environment, including the user ID, current connect group, user
attributes, and group authorities. An ACEE is constructed during user identification and
verification by RACF.

The effective UID and effective GID of the process are used in determining access
decisions. The only exception is that if file access is being tested, rather than requested,
the real UID and GID are used instead of the effective UID and GID. The real and effective
IDs are generally the same for a process, but if a set-uid or set-gid program is executed,
they can be different.
FSP and security flow
Permission bit information is stored in the file security packet (FSP) within each file and
directory. (ACLs may also be stored with the file.) Permission bits allow you to specify read
authority, write authority, or search authority for a directory. They also allow specification of
read, write, or execute authority for a file. Because there are three sets of bits, separate
authorities can be specified for the owner of the file or directory, the owning group, and
everyone else (like RACF's universal access authority, or UACC). The owner is represented
by a UID. The owning group is represented by a GID. Access checking compares the user's
UID and GID to the ones stored in the FSP.
ACEE
Permission bits
(ACLs - (optional))
Owning UID
50
Owning GID
100
FSP
Supplemental Groups
Effective UID
77
Effective GID
999
100 200 300
User Security Packet (USP)

Chapter 6. Security customization
217
Security check
The security check and flow is as follows:

Security information, such as the owner's UID-GID and the permission bits for a file, is
kept in a 64-byte area called the file security packet (FSP), which is mapped by IRRPIFSP.
The FSP is the security-related section of a file's attributes.

The FSP is created by a SAF call from the PFS when a file is created. Some of the
information is taken from the current security environment, and some of it is passed as
parameters.

The PFS stores the FSP with the attributes of the file.

When an access check is to be done, the PFS calls SAF with the type of check that is
being requested, the audit_structure from the current call, and the file's FSP. SAF passes
these to the security product, which extracts user information from the current security
environment and compares it against the access control that is stored within the FSP. The
audit_structure is used primarily for any auditing that may be necessary.

218
ABCs of z/OS System Programming: Volume 9
6.22 Access checking flows
Figure 6-22 Access checking flow for access to a file
Security check flow
Figure 6-22 shows the access checking flow from a UNIX program—or the access could be
from a z/OS UNIX shell user—to the security product, as follows:

The z/OS UNIX kernel calls the file system, and the file system calls the security product.

The kernel calls the file system iteratively for each directory component of the path name
(one is required in order to locate the next).

The base file name is retrieved.

For each directory lookup, the file system calls the security product to make sure the user
has search authority.

The security product is called to ensure the user has the requested access to the base file.
This is the basic architecture of every UNIX file system.
z/OS UNIX Kernel
Logical File System
C Runtime Library
IRRSKA00
IRRRKA00
zFS File System PFS
1) open "/" directory for search (execute) access
2) open "u" directory for search (execute) access
3) open "harry" directory for search (execute) access
4) open "programx" directory for search (execute access)
5) open "myfile" file for read and write access
zFS
SMF
SMF
FSP
ACL
SAF
RACF
Unix program
fopen("/u/harry/programx/myfile","rw")

Chapter 6. Security customization
219
6.23 File authorization checking flow
Figure 6-23 Authorization checking with z/OS UNIX
Authorization checking flow
Authorization checking is done for all directories and files (including special files) in the file
system. z/OS UNIX calls RACF to perform the authorization checking and passes RACF the
FSP (file security packet), and the CRED (security credentials).
Figure 6-23 shows the sequence of authorization checks, as follows:

A superuser (UID of zero) is allowed access to all resources.

If the effective UID of the process (the accessor) equals the UID of the file, RACF uses the
owner permissions in the FSP to either allow or deny access.

If the effective GID of the process equals the GID of the file, RACF uses the group
permissions in the FSP to either allow or deny access. If RACF list-of-groups checking is
active (SETROPTS GRPLIST), RACF will look at the user's connect groups that have a
GID for a group that matches the GID of the file. If it finds a matching GID, RACF will allow
or deny access based on the group permissions specified in the FSP. Note that if a user is
connected to more that 300 z/OS UNIX groups, only the first 300 will be used.

If the effective UID or GID of the process does not match the file UID or GID, then the
other permission bits will determine access.
eUID=0?
eUID=FSP
owning
UID?
eGID/sGID
= FSP
GID?
OTHER bits
allow
access?
OWNER
bits allow
access?
GROUP
bits allow
access?
yes
no no
no
no
yes yes
yes
yes
no
UNIXPRIV
allow
access?
yes
no
no
S
t
a
r
t
yes
ACEE
FSP
or MVS trusted or
privileged user
effective UID
77
effective UID
GID 999
Supplemental Groups
100 200 300
User Security Packet (USP)
owning UID
50
owning GID
100
Permission bits
rwx r-x r-x
Access
granted
Access
denied

220
ABCs of z/OS System Programming: Volume 9
6.24 POSIX standard and UNIX ACLs
Figure 6-24 The POSIX standard for ACL support
z/OS UNIX support for ACLs
ACLs have existed on various UNIX platforms for many years, but with variations in the
interfaces. ACL support in z/OS V1R3 is based on a POSIX standard that was never
implemented when z/OS UNIX was first introduced as OpenEdition.
In the POSIX standard, two different ACLs are referenced as follows:

Base ACL entries
These entries are permission bits (owner, group, other). This refers to the FSP. You can
change the permissions using
chmod
or
setfacl
. They are not physically part of the ACL,
although you can use
setfacl
to change them and
getfacl
to display them.

Extended ACL entries
These entries

are ACL entries for individual users or groups, such as the permission bits
that are stored with the file, not in RACF profiles. Extended ACL entries, like the
permission bits, are stored with the file, not in RACF profiles. Each ACL type (access, file
default, directory default) can contain up to 1024 extended ACL entries. Each extended
ACL entry specifies a qualifier to indicate whether the entry pertains to a user or a group,
the actual UID or GID itself, and the permissions being granted or denied by this entry.
The allowable permissions are read, write, and execute. As with other UNIX commands,
setfacl
allows the use of either names or numbers when referring to users and groups.
Note:
This function was added in z/OS V1R3.
In the POSIX standard, two different ACLs are
referenced as follows:
Base ACL entries
are permission bits (owner,
group, other) - It refers to the FSP
Extended ACL entries
are ACL entries for
individual users or groups, such as the permission
bits that are stored with the file, not in RACF
profiles

Chapter 6. Security customization
221
6.25 Limitations of current permission bits
Figure 6-25 z/OS UNIX limitation with POSIX standard on ACLs
ACLs for greater granularity
Access control lists (ACLs) were introduced in z/OS V1R3 as a way to provide a greater
granularity for access to z/OS UNIX files and directories. ACLs are based on a POSIX
standard that was never approved, and other UNIX implementations.
z/OS V1R3 provides support for ACLs to control access to files and directories for:

Specific individual user or users (UID)

Specific group or groups (GID)
To create an ACL for a file, you must have one of the following security access controls:

Be the file owner

Be permitted to the BPX.SUPERUSER RACF profile

Have superuser authority (UID=0)

Have READ access to the SUPERUSER.FILESYS.CHANGEPERMS profile in the
UNIXPRIV class
Can only specify permissions for file owner (user),
group owner, and everybody else (other)
Cannot permit/restrict access to specific users and
groups - lots of customer requirements for capability
Access Control Lists introduced in z/OS V1R3
To manage files using UNIX setfacl/chmod
commands, or the ISHELL, a user must be either:
UID(0)
The file owner
Have READ access to the UNIXPRIV class profile
SUPERUSER.FILESYS.CHANGEPERMS
Requirements are the same for changing the
permission bits

222
ABCs of z/OS System Programming: Volume 9
6.26 FSPs and ACLs
Figure 6-26 File security packet and ACL support
ACL types
Use access control lists (ACLs) to control access to files and directories by individual user
(UID) and group (GID). ACLs are used in conjunction with permission bits. They are created,
modified, and deleted using the
setfacl
shell command. To display them, use the
getfacl
shell command. You can also use the ISHELL interface to define and display ACLs.
ACLs are used together with the permission bits in the FSP to control the access to z/OS
UNIX files and directories by individual users (UIDs) and groups (GIDs).
To reduce administrative overhead, three types of ACLs (extended ACLs) are defined, giving
the capability to inherit ACLs to newly created files and directories as follows:
Access ACLs
This type of ACL is used to provide protection for a file system
object (specific for a file or directory).
File default ACLs
This type is a model ACL that is inherited by files created within the
parent directory. The file default ACL is copied to a newly created
file as its access ACL. It is also copied to a newly created
subdirectory as its file default ACL.
Directory default ACLs
This type is a model ACL that is inherited by subdirectories created
within the parent directory. The directory default ACL is copied to a
newly created subdirectory as both its access ACL and directory
default ACL.
File Permission Bits
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w
x
r
w
x
r
w
x
Owner Group Other
File Mode
extattr
Access
ACL
exists
File
model
ACL
exists
Directory
model
ACL
exists
ACL Flags
There are 3 types of ACLs
Access ACLs
File default model ACLs
Directory default model ACLs

Chapter 6. Security customization
223
6.27 Access control list table
Figure 6-27 ACL table that contains ACL entries after creation
ACL table structure
An ACL is mapped by the SAF IRRPFACL macro, as shown in Figure 6-27, where the set of
user entries is followed by the set of group entries.
The entries are sorted in ascending order by UID and GID to help optimize the access
checking algorithm. The table consists of a list of entries (with a maximum of 1024) where
every entry has information about the type (user or group), identifier (UID or GID), and
permissions (read, write, and execute) to apply to a file or directory.
Extended ACL entries are ACL entries for individual users or groups. Like the permission bits,
they are stored with the file, not in RACF profiles.
Note:
ACLs are supported by HFS, zFS, and TFS. It is possible that other physical file
systems will eventually support z/OS ACLs. Consult your file system documentation to see
if ACLs are supported.
Entry Type
Identifier (UID or GID)
Permissions
User (X'01')
46
r - x
Header
- length
- number of entries
- type
Entries (1 - 1024)
....
....
....
- number of user entries

224
ABCs of z/OS System Programming: Volume 9
6.28 File authorization check summary
Figure 6-28 Authorization checks made for access to files and directories
RACF checking summary
Authorization checking for z/OS UNIX files and directories is done by RACF, which makes the
following checks:

The accessor environment element (ACEE) is a control block that contains a description of
the current user's security environment, including user ID, current connect group, user
attributes, and group authorities. An ACEE is constructed during user identification and
verification.

RESTRICTED.FILESYS.ACCESS
Specifies that RESTRICTED users cannot gain file access by virtue of the “other”
permission bits.

SUPERUSER.FILESYS.ACLOVERRIDE
If no group bits access is allowed and the FSSEC class is active, and an ACL exists, and
there is an ACL entry for any of the user's supplemental GIDs, then the permission bits of
that ACL entry are checked. If at least one matching ACL entry was found for the GID, or
any of the supplemental GIDs, then processing continues with the ACLOVERRIDE
checking.

SUPERUSER.FILESYS
If no group ACL matches, then if the UNIXPRIV class is active, the
SUPERUSER.FILESYS access is checked.
RACF uses the following to determine whether the
user is authorized to access the file with the
requested access level:
The user's security environment - (ACEE and USP)
The permission bits - (FSP)
The access ACL - (FSP and ACL table)
The following UNIXPRIV class profiles
SUPERUSER.FILESYS
RESTRICTED.FILESYS.ACCESS
SUPERUSER.FILESYS.ACLOVERRIDE
ACL entries are used only if the RACF FSSEC class is active
SETROPTS CLASSACT(FSSEC)

Chapter 6. Security customization
225
6.29 Profiles in UNIXPRIV class
Figure 6-29 SUPERUSER.FILESYS profile in UNIXPRIV class
UNIXPRIV class profile for authorization checking
The UNIXPRIV class provided the capability to assign specific superuser functions to a user
or group when you give a user or group either a:

UID of 0

BPX.SUPERUSER profile
Either of these gives a user or group access to all UNIX functions and resources. A
BPX.SUPERUSER profile allows you to request that you be given such access, but you do
not have the access unless you make the request. So, instead of giving a user or group
access to all functions a superuser has, the UNIXPRIV class provides profiles that allow
access to specific superuser functions.
The SUPERUSER.FILESYS profile in the UNIXPRIV class has three access levels that allow
access to z/OS UNIX files as follows:
READ
Allows a user to read any local file, and to read or search any local
directory.
UPDATE
Allows a user to write to any local file, and includes privileges of READ
access.
CONTROL/ALTER
Allows a user to write to any local directory, and includes privileges of
UPDATE access.
Grant authorization for certain UNIX privileges
RDEFINE UNIXPRIV SUPERUSER.FILESYS UACC(NONE)
PERMIT SUPERUSER.FILESYS CLASS(UNIXPRIV) ID(user|group) ACC(READ)
SUPERUSER.FILESYS - ACC(.....)
READ
- Allows a user to read any local file, and to
read or search any local directory
UPDATE
- Allows a user to write to any local file, and
includes privileges of READ access
CONTROL/ALTER - Allows a user to write to any
local directory, and includes privileges of UPDATE
access

226
ABCs of z/OS System Programming: Volume 9
6.30 Profiles in UNIXPRIV class (2)
Figure 6-30 UNIXPRIV profiles introduced with z/OS V1R3
Profiles for authorization checking
Resource names in the UNIXPRIV class are associated with z/OS UNIX privileges. You must
define profiles in the UNIXPRIV class protecting these resources in order to use RACF
authorization to grant z/OS UNIX privileges. The UNIXPRIV class must be active and
SETROPTS RACLIST must be in effect for the UNIXPRIV class. Global access checking is
not used for authorization checking to UNIXPRIV resources.
RESTRICTED.FILESYS.ACCESS profile
This profile specifies that RESTRICTED users cannot gain file access by virtue of the “other”
permission bits. Checking for this new profile RESTRICTED.FILESYS.ACCESS is done for
RESTRICTED users regardless of whether an ACL exists, so this function can be exploited
whether you plan to use ACLs or not. You can define the profile as follows:
RDEFINE UNIXPRIV RESTRICTED.FILESYS.ACCESS UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
SUPERUSER.FILESYS.ACLOVERRIDE profile
Any user who is not a superuser with UID(0) or the file owner, and who is denied access
through the ACL, can still access a file system resource if the user has sufficient authority to
the SUPERUSER.FILESYS resource in the UNIXPRIV class. Therefore, to prevent this, you
can force RACF to use your ACL authorizations to override a user's SUPERUSER.FILESYS
authority by defining the following profiles:
RDEFINE UNIXPRIV SUPERUSER.FILESYS.ACLOVERRIDE UACC(NONE)
RESTRICTED.FILESYS.ACCESS
- This profile in the
UNIXPRIV class controls the access to filesystem
resources for restricted users based on the “other”
permission bits
SUPERUSER.FILESYS.ACLOVERRIDE
- This profile
allows RACF to force the use of the ACL authorizations
to override a user’s SUPERUSER.FILESYS profile
authority
SUPERUSER.FILESYS.CHANGEPERMS
- This profile
allows users to use the chmod command to change the
permission bits of any file and to use the setfacl
command to manage access control lists for any file
New with z/OS V1R3

Chapter 6. Security customization
227
SETROPTS RACLIST(UNIXPRIV) RACLIST
SUPERUSER.FILESYS.CHANGEPERMS profile
As an enhancement to superuser granularity, when using the
chmod
command, a RACF
service (IRRSCF00) has been updated to check the caller's authorization to the resource
SUPERUSER.FILESYS.CHANGEPERMS in the UNIXPRIV class if the caller's user ID is not
either:

UID(0)

The owner of the file

BPX.SUPERUSER
If the user executing the
chmod
command has at least READ authority to the resource, the
user is authorized to change the file mode in the same manner as a user having UID(0).
This profile allows users to use the
chmod
command to change the permission bits of any file
and to use the
setfacl
command to manage access control lists for any file.

228
ABCs of z/OS System Programming: Volume 9
6.31 RACF RESTRICTED attribute
Figure 6-31 Assigning the RESTRICTED attribute with RACF
Defining restricted users
You can define a restricted user ID by assigning the RESTRICTED attribute through the
ADDUSER or ALTUSER commands, as follows:
ALTUSER RSTDUSR RESTRICTED
User IDs with the RESTRICTED attribute cannot access protected resources they are not
specifically authorized to access. Access authorization for restricted user IDs bypasses global
access checking. In addition, the UACC of a resource and an ID(*) entry on the access list are
not used to enable a restricted user ID to gain access.
However, the RESTRICTED attribute has no effect when a user accesses a z/OS UNIX file
system resource; the file's “other” permission bits can allow access to users who are not
explicitly authorized. To ensure that restricted users do not gain access to z/OS UNIX file
system resources through other bits, use the new UNIXPRIV profile, RESTRICTED
FILESYS.ACCESS.
This is a solution to a problem many installations face when they connect the mainframe to
the Internet. There are RACF user IDs assigned to "any user who comes in from the Web
who asks to look at sensitive information." If the installation has not yet set the UACCs to all
our sensitive data sets and resources to NONE, then such users could conceivably read
sensitive data. If these user IDs are set as RESTRICTED, they can only access data to which
they have been explicitly permitted.
Defined through ADDUSER or ALTUSER
ALTUSER RSTDUSR RESTRICTED
Restricted user IDs cannot access protected
resources they are not specifically authorized to
access
Access authorization for restricted user IDs
bypasses global access checking
In addition, the UACC of a resource and an ID(*)
entry on the access list are not used to enable a
restricted user ID to gain access
The RESTRICTED attribute does not prevent users from
gaining access to z/OS UNIX file system resources
----- Access allowed through "other" permissions -----

Chapter 6. Security customization
229
6.32 z/OS UNIX file access checking
Figure 6-32 Authorization checking after introduction of UNIXPRIV profiles
Authorization checking flow
The effective UID and effective GID of the process are used in determining access decisions.
The only exception is that if file access is being tested, rather than requested, the real UID
and GID are used instead of the effective UID and GID. The real and effective IDs are
generally the same for a process, but if a set-uid or set-gid program is executed, they can be
different.
Check UID
If the user is not system and is not a superuser, the permission bits and ACL (if one exists,
and if the FSSEC class is active) for the file are checked to see if the access requested is
allowed.

If the selected UID matches the owner UID of the file, the owner permission bits are
checked.

If the UIDs don't match, the user ACL entries are checked. If the selected UID matches an
ACL entry, the ACL entry bits are checked.
Check GID
If a matching ACL entry was not found for the user, the group bits and the group ACL entries
are checked. The selected GID and supplemental GIDs are checked against the file owner
GID and the group ACL entries until a match is found that grants the requested access, or
until all the GIDs have been checked.
S
T
A
R
T
RESTRICT.FS.A is an abbreviation for the new
profile named RESTRICTED.FILESYS.ACCESS
SU.FS = SUPERUSER.FILESYS
yes
yes
no
Access
Access
granted
granted
Access
Access
denied
denied
UID=0?
EXECUTE
access
requested?
Any
EXECUTE
bit on ?
yes
no
eUID=FSP
owner UID?
eUID=ACL
entry?
eGID/sGID=
FSP or ACL
entry?
no no
no
no
RESTRICTED
user?
yes
yes yes yes
no
OWNER bits
allow
access?
yes
ACL bits
allow
access?
yes
bits
allow
access?
yes
yes
no
yes
SU.FS allow
access?
no
no
yes
SU.FS
ACLOVERRIDE
defined?
no
no
yes
SU.FS
ACLOVERRIDE
access?
yes
no
no
group ACL
entry match?
OTHER bits
allow
access?
no
yes
no
RESTRICT. FS.A
access?
RESTRICT. FS.A
defined?
Abbreviations in chart
(A)
(AA)
(B)
(BB)
For ACL checking FSSEC class must be active
no
(C)
(D)
(4)
yes
(2) (2)
(3)
(1)
(4)
(4)

230
ABCs of z/OS System Programming: Volume 9

If the GID matches the file owner GID, the file's “group” permission bits are checked. If the
group bits allow the requested access, then access is granted.

If any of the user's supplemental GIDs match the file owner GID, the file's group
permission bits are checked. If the group bits allow the requested access, then access is
granted.
Check for ACLs
If no group bits access is allowed and the FSSEC class is active, and an ACL exists, and
there is an ACL entry for any of the user's supplemental GIDs, then the permission bits of that
ACL entry are checked. If at least one matching ACL entry was found for the GID, or any of
the supplemental GIDs, then processing continues with the ACLOVERRIDE checking.
If no group ACL matches, then if the UNIXPRIV class is active, the SUPERUSER.FILESYS
access is checked.
Check SUPERUSER.FILESYS.ACLOVERRIDE
SUPERUSER.FILESYS.ACLOVERRIDE is checked only when a user's access was denied
by a matching ACL entry based on the user's UID or one of the user's GIDs. If the user's
access was denied by the file's permission bits, SUPERUSER.FILESYS is checked.
See “Access checking with ACLs (1)” on page 233 and “Access checking with ACLs (2)” on
page 234.
Check RESTRICTED.FILESYS.ACCESS
If no match was found, the other permission bits are checked, unless the user has the
RESTRICTED attribute, the UNIXPRIV class is active, the resource named
RESTRICTED.FILESYS.ACCESS is protected, and the user does not have at least READ
access.
See “RESTRICTED user profile” on page 231 and “Restricted user access checking” on
page 232.

Chapter 6. Security customization
231
6.33 RESTRICTED user profile
Figure 6-33 How the RESTRICTED user profile works
Checking RESTRICTED user profile
Users with the RESTRICTED attribute cannot access protected resources they are not
specifically authorized to access. However, the RESTRICTED attribute has no effect when a
user accesses a z/OS UNIX file system resource; therefore, if you do not define the
RESTRICTED.FILESYS.ACCESS profile, then the file's “other” permission bits can allow
access to users who are not explicitly authorized.
To ensure that restricted users do not gain access to z/OS UNIX file system resources
through other bits, you must define the RACF profiles as follows:
RDEFINE UNIXPRIV RESTRICTED.FILESYS.ACCESS UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
Note:
Do not attempt to deny access to certain restricted users by defining this resource
with UACC(READ) and then permitting those users with access of NONE. The UACC of a
resource cannot be used to allow access when the user is restricted.
Profile -
RESTRICTED.FILESYS.ACCESS
If not defined, then the 'other' bits are treated like
UACC and ID(*) for RESTRICTED users during
RACF profile checking (3 on access flow)
If defined, RESTRICTED users cannot be granted
file access via the 'other' bits and file access is
denied
RDEFINE UNIXPRIV RESTRICTED.FILESYS.ACCESS UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
(BB on access flow)

232
ABCs of z/OS System Programming: Volume 9
6.34 Restricted user access checking
Figure 6-34 How the RESTRICTED user profile is used on the authority checking
Checking RESTRICTED user profile
If needed, grant exceptions to certain restricted users to allow them to gain access based on
the file's other bits. Add those users, or one of their groups, to the access list with READ
authority.
This does not grant the user access to any files. It just allows the other bits to be used in
access decisions for this user.
Note:
SUPERUSER.FILESYS still applies to RESTRICTED users regardless of the
existence of the RESTRICTED.FILESYS.ACCESS profile.
(D on access flow)
(B on access flow)
For exception cases, permit the RESTRICTED user (or
one of its groups) to RESTRICTED.FILESYS.ACCESS
(1 on access flow)
PERMIT RESTRICTED.FILESYS.ACCESS CLASS(UNIXPRIV)
ID(RSTDUSR) ACCESS(READ)

SETROPTS RACLIST(UNIXPRIV) REFRESH
This does not grant the user access to any files - It just
allows the 'other' bits to be used in access decisions for
this user (C on access flow)
SUPERUSER.FILESYS still applies to RESTRICTED
users regardless (2 on access flow) of the existence of
RESTRICTED.FILESYS.ACCESS

Chapter 6. Security customization
233
6.35 Access checking with ACLs (1)
Figure 6-35 Access checking with the ACLOVERRIDE profile
SUPERUSER.FILESYS.ACLOVERRIDE profile
Any user who is not a superuser with UID(0) or the file owner, and who is denied access
through the ACL, can still access a file system resource if the user has sufficient authority to
the SUPERUSER.FILESYS resource in the UNIXPRIV class. Therefore, to prevent this, you
can force RACF to use your ACL authorizations to override a user’s SUPERUSER.FILESYS
authority by defining the following profiles:
RDEFINE UNIXPRIV SUPERUSER.FILESYS.ACLOVERRIDE UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) RACLIST
Figure 6-32 on page 229 shows the algorithm used by RACF in order to do authorization
checking that now includes checking for profiles in the UNIXPRIV class for
SUPER.FILESYS.ACLOVERRIDE, as shown at (AA).
Note:
This describes the relationship between the existing SUPERUSER.FILESYS profile
and the new SUPERUSER.FILESYS.ACLOVERRIDE profile. Either profile could get
checked for a file; it depends upon the presence of an ACL for the file, and the contents of
the ACL for granting access.
Profile -
SUPERUSER.FILESYS.ACLOVERRIDE
Any user - not a superuser with UID(0) or file owner
- and is denied access through the ACL can still
access a file system resource if having sufficient
authority to
SUPERUSER.FILESYS
resource in
UNIXPRIV class (4 on access flow)
Therefore, to prevent this, you can force RACF to
use your ACL authorizations to override a user's
SUPERUSER.FILESYS authority by defining:
RDEFINE UNIXPRIV SUPERUSER.FILESYS.ACLOVERRIDE UACC(NONE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
(AA on access flow)

234
ABCs of z/OS System Programming: Volume 9
6.36 Access checking with ACLs (2)
Figure 6-36 Access authority checking with the ACLOVERRIDE profile
Access checking with ACLs
For exception cases, permit the user or group to SUPERUSER.FILESYS.ACLOVERRIDE
with whatever access level would have been required for SUPERUSER.FILESYS as follows:
PERMIT SUPERUSER.FILESYS.ACLOVERRIDE CLASS(UNIXPRIV) ID(ADMIN) ACCESS(READ)
SETROPTS RACLIST(UNIXPRIV) REFRESH
SUPERUSER.FILESYS authority is still checked when an ACL does not exist for the file. This
should be done for administrators for whom you want total file access authority. That is, you
do not want anyone to deny them access to a given file or directory by defining an ACL entry
for them with limited, or no permission bit access.
This check is made at check (A) in the flow shown in the Figure 6-32 on page 229.
SUPERUSER.FILESYS.ACLOVERRIDE is checked only when a user's access was denied
by a matching ACL entry based on the user's UID or one of the user's GIDs. If the user's
access was denied by the file's permission bits, SUPERUSER.FILESYS is checked.
Important:
The intent of these new profiles is to allow ACLs to behave as much as
possible like RACF profile access lists. The new profiles are provided to avoid changing the
default behavior since that could introduce compatibility issues with previous releases.
For exception cases, permit the user or group to
SUPERUSER.FILESYS.ACLOVERRIDE with
whatever access level would have been required
for SUPERUSER.FILESYS
(A on access flow)
PERMIT SUPERUSER.FILESYS.ACLOVERRIDE CLASS(UNIXPRIV)
ID(ADMIN) ACCESS(READ)
SETROPTS RACLIST(UNIXPRIV) REFRESH
SUPERUSER.FILESYS authority will still be required
when an ACL does not exist for the file
(grants access)
(4 on access flow)

Chapter 6. Security customization
235
6.37 Create ACLs
Figure 6-37 Types of ACLs that can be created
Creating ACLs for files and directories
ACLs have existed on various UNIX platforms for many years, but with variations in the
interfaces. ACL support in z/OSV1R3 is based on a POSIX standard (that was never
approved) and other UNIX implementations. In the POSIX standard, two different ACLs are
referenced as follows:

Base ACL entries are permission bits (owner, group, other). It refers to the FSP.

Extended ACL entries

are ACL entries for individual users or groups, such as the
permission bits that are stored with the file, not in RACF profiles.
Access control lists are introduced in z/OS V1R3 as a way to provide a greater granularity for
access to z/OS UNIX files and directories. z/OS V1R3 provides support for ACLs to control
access to files and directories by individual user (UID) and group (GID). ACLs are now
created and checked by RACF. ACLs are created, modified, and deleted by using either of the
following:
setfacl
shell command

ISHELL interface
ACL inheritance
With the introduction of ACL support, when new files and directories are created in a file
system, ACL inheritance is the process of automatically associating an ACL with a newly
created object without requiring administrative action. ACL inheritance associates an ACL
with the newly created file, myfile, without requiring administrative action. However, it is not
Use OMVS shell command - setfacl
Use ISHELL panels
3 types of ACLs
Access ACL - Directory default ACL - File default ACL
ACL inheritance
Can establish default (or 'model') ACLs on a directory
or a file
They will get automatically applied to new files or
directories created within the directory
Separate default ACL used for files and (sub)
directories
Default ACLs can reduce administrative overhead

236
ABCs of z/OS System Programming: Volume 9
always necessary to apply ACLs on every file or directory within a subtree. If you have a
requirement to grant access to an entire subtree (for example, a subtree specific to a given
application), then access can be established at the top directory. If a given user or group does
not have search access to the top directory, then no files within the subtree will be accessible,
regardless of the permission bit settings or ACL contents associated with these files. The user
or group will still need permission to the files within the directory subtree where appropriate. If
this is already granted by the “group” or “other” bits, then no ACLs are necessary below the
top directory.
Default or model ACLs
The phrases “default ACL” and “model ACL” are used interchangeably throughout z/OS UNIX
documentation. Other systems that support ACLs have default ACLs that are essentially the
same as the directory default ACLs in z/OS UNIX. According to the X/Open UNIX 95
specification, additional access control mechanisms may only restrict the access permissions
that are defined by the file permission bits. They cannot grant additional access permissions.
Because z/OS ACLs can grant and restrict access, the use of ACLs is not UNIX 95-compliant.
To create an ACL for a file, you must have one of the following security access controls:

Be the file owner

BPX.SUPERUSER

Have superuser authority (UID=0)

Have READ access to the SUPERUSER.FILESYS.CHANGEPERMS profile in the
UNIXPRIV class
To activate the use of ACLs in z/OS UNIX file authority checks, the following RACF command
needs to be run to activate the new RACF class FSSEC:
SETROPTS CLASSACT(FSSEC)
Note:
When defining ACLs, it is recommended to place ACLs on directories, rather than on
each file in a directory.
Note:
The RACF UNIXPRIV class was introduced in OS/390 V2R8. It allows you to define
profiles in the UNIXPRIV class to grant RACF authorization for certain z/OS UNIX
privileges. By defining profiles in the UNIXPRIV class, you can grant specific superuser
privileges to users who do not have superuser authority (UID=0). This allows you to
minimize the number of assignments of superuser authority at your installation and
reduces your security risk.

Chapter 6. Security customization
237
6.38 ACL types
Figure 6-38 Types of ACLs that can be created
Types of ACLs
To reduce administrative overhead, three types of ACLs (extended ACLs) are defined in order
to have the capability to inherit ACLs to newly created files and directories, as follows:
Access ACLs
This type of ACL is used to provide protection for a file system
object (specific for a file or directory).
File default ACLs
This type is a model ACL that is inherited by files created within
the parent directory. The file default ACL is copied to a newly
created file as its access ACL. It is also copied to a newly created
subdirectory as its file default ACL.
Directory default ACLs
This type is a model ACL that is inherited by subdirectories
created within the parent directory. The directory default ACL is
copied to a newly created subdirectory as both its access ACL
and directory default ACL.
Access ACLs This type of ACL is used to provide
protection for a file system object (specific for a file or
directory)
File default ACLs This type is a model ACL that is
inherited by files created within the parent directory.
The file default ACL is copied to a newly created file
as its access ACL. It is also copied to a newly created
subdirectory as its file default ACL
Directory default ACLs This type is a model ACL
that is inherited by subdirectories created within the
parent directory. The directory default ACL is copied
to a newly created subdirectory as both its access
ACL and directory default ACL

238
ABCs of z/OS System Programming: Volume 9
6.39 OMVS shell commands for ACLs
Figure 6-39 OMVS shell commands to create and display ACLs
z/OS UNIX commands to create and display ACLs
The new shell commands,
setfacl
and
getfacl
are used to create, modify, and display ACL
entries specified by the path.
Use ACLs to control access to files and directories by individual user and group. ACLs are
used in conjunction with
permission bits
. They are created, modified, and deleted using the
setfacl
shell command. To display them, use the
getfacl
shell command. You can also use
the ISHELL interface to define and display ACLs.
Among the options you can specify for
setfacl
are the following:
-s
option: Replaces the contents of an ACL with the entries specified on the command
line. It requires that the base permissions be specified. The base permissions are
specified similarly to extended ACL entries, except that there is no user or group name
qualifier.
-m
option: Modifies ACL entries, or adds them if they do not exist.
-D
option: Specifies that the access ACL is to be deleted. When a file is deleted, its ACL is
automatically deleted; there is no extra administrative effort required.
Recommendation:
Use the -m option instead of the -s option when creating ACLs.
Creating ACLs using the ISHELL is probably preferred. See “Using the ISHELL panel” on
page 245 through “Access ACL after creation” on page 253.
setfacl - The setfacl command sets, modifies,
and deletes an ACL definition for a file or directory.
setfacl has the following syntax:
setfacl [–ahqv] -s entries [path ... ]
setfacl [–ahqv] -S file [path ...]
setfacl [–ahqv] -D type [...][path ... ]
setfacl [–ahqv] -m|M|x|X EntryOrFile [...][path ... ]
getfacl - The getfacl command obtains and
displays an ACL entry for a requested file or
directory. It has the following syntax:
getfacl [–acdfhmos][-e user] file

Chapter 6. Security customization
239
6.40 Create ACLs for a specific directory
Figure 6-40 Creating ACLs for a specific directory HARRY
Example of creating ACLs
The next few figures show how to create the three ACLs shown in Figure 6-40 that give user
JANE access to directory HARRY and any directories and files defined under directory
HARRY.
You can use an access ACL on a directory to grant search access only to those users and
groups who should have file access. The access ACL of the directory might have been
automatically created as the result of a directory default ACL on its parent. Make sure that the
“other” and perhaps the “group” search permission bit is off for the parent directory.
To minimize the impact to performance, keep ACLs as small as possible, and permit groups to
files instead of individual users. The path length of the access check will increase with the
size of an ACL, but will be smaller than the associated checking would be for a RACF profile
with the same number of entries in its access list.
access
ACL
directory
default
ACL
file
default
ACL
jane tom harry
u
bin etc dev tmp
...
/
For user jane

240
ABCs of z/OS System Programming: Volume 9
6.41 Create an access ACL
Figure 6-41 Create an access ACL for directory HARRY
Creating an access ACL
When you are setting the access ACL, the ACL entries must consist of three required base
ACL entries that correspond to the file permission bits. The ACL entries must also consist of
zero or more extended ACL entries, which will allow a greater level of granularity when
controlling access. The permissions for base entries must be in absolute form. As shown in
Figure 6-41, issuing the
ls -al
command, the
+
sign following the permission bits for
directory HARRY indicates that an ACL exists for that directory.
Using the -m option
With the
setfacl
command, you use the
-m
option to create an ACL. The base ACL
(permission bits) are indicated by omitting user or group qualifiers.
This command creates an access ACL that gives user ID JANE rwx access to directory
HARRY:
ROGERS @ SC65:/u>setfacl -m “u:jane:rwx” harry
Create an access ACL
- using setfacl -m option
For directory harry - create an access ACL that gives
user ID JANE rwx access to directory harry
setfacl -m "u:jane:rwx" harry
ROGERS @ SC65:/u>ls -al
total 152
dr-xr-xr-x 11 HAIMO NOGROUP 0 Aug 2 10:45 .
drwxr-xr-x 48 HAIMO SYS1 24576 Jul 25 14:44 ..
drwx------+ 2 HARRY SYS1 8192 Aug 2 10:44 harry
drwx------ 2 JANE SYS1 8192 Aug 2 10:44 jane
drwxr-xr-x 2 HAIMO SYS1 8192 Jun 28 12:23 ldapsrv
drwx------ 2 HAIMO SYS1 8192 Aug 1 11:02 rogers
drwxr-xr-x 2 HAIMO SYS1 8192 Nov 15 2001 syslogd
drwx------ 3 HAIMO SYS1 8192 May 26 11:03 user1

Chapter 6. Security customization
241
6.42 Display the access ACL
Figure 6-42 Displaying the created ACL using the getfacl command
Displaying the defined ACL
The
getfacl
command displays the comment header, base ACL entries, and extended ACL
entries, if there are any, for each file that is specified. It also resolves symbolic links. You can
specify whether to display access, file default, or directory default. You can also change the
default display format. The output can be used as input to
setfacl
.
-a option for getfacl
This option displays the access ACL entries. This is the default if
-a
,
-d
, or
-f
is not specified.
Figure 6-42 displays the ACL entry just created for directory HARRY.
Display the access ACL - using
getfacl
-a
Displays the access ACL entries
ROGERS @ SC65:/u>getfacl -a harry
#file: harry/
#owner: HARRY
#group: SYS1
user::rwx <=== The owner's permission bit setting
group::--- <=== The group's permission bit setting
other::--- <=== Permission bit setting if neither user nor group
user:JANE:rwx

242
ABCs of z/OS System Programming: Volume 9
6.43 Create a directory default ACL
Figure 6-43 Creating a directory default ACL for directory HARRY
Creating a directory default ACL
Directory default ACLs are model ACLs that are inherited by subdirectories created within the
parent directory. The directory inherits the model ACL as its directory default ACL, and as its
access ACL when a new directory is created under directory HARRY.
To facilitate management of ACLs, you can define a default ACL in a directory; it will then be
automatically inherited by an object, as follows:

The directory default ACL is copied to a newly created subdirectory as both its access
ACL and directory default ACL. You can modify or delete inherited ACLs later.
For directory HARRY, the following command creates a directory default ACL that gives user
JANE rwx access in a directory default ACL for directory HARRY:
ROGERS @ SC65:/u>setfacl -m "d:u:jane:rwx" harry
Create a directory default ACL

A model ACL that is inherited by subdirectories created
within the parent directory
The directory inherits the model ACL as its directory
default ACL and as its access ACL
setfacl -m "d:u:jane:rwx" harry
ROGERS @ SC65:/u>getfacl -d harry
#file: harry/
#owner: HARRY
#group: SYS1
default:user:JANE:rwx

Chapter 6. Security customization
243
6.44 Create a file default ACL
Figure 6-44 Create a file default ACL for directory HARRY
Creating a file default ACL
File default ACLs are model ACLs that are inherited by files created within the parent
directory. The file inherits the model ACL as its access ACL. Directories also inherit the file
default ACL as their file default ACL.
To facilitate management of ACLs, you can define a default ACL in a directory; it will then be
automatically inherited by an object, as follows:

The file default ACL is copied to a newly created file as its access ACL. It is also copied to
a newly created subdirectory as its file default ACL.
For directory HARRY, the following command creates a file default ACL that gives user JANE
r-- access in a file default ACL for directory HARRY:
ROGERS @ SC65:/u>setfacl -m "f:u:jane:r--" harry
Create a file default ACL

A model ACL that is inherited by files created within
the parent directory
The file inherits the model ACL as its access ACL
Directories also inherit the file default ACL as their file
default ACL
setfacl -m "f:u:jane:r--" harry
ROGERS @ SC65:/u>getfacl -f harry
#file: harry/
#owner: HARRY
#group: SYS1
fdefault:user:JANE:r--

244
ABCs of z/OS System Programming: Volume 9
6.45 Creating all ACL types
Figure 6-45 Creating all three ACLs and specifying the permission settings
Creating all ACLs using the -s option
The
-s
option replaces the contents of an ACL with the entries specified on the command
line. It requires that the base permissions be specified. The base permissions are specified
similarly to extended ACL entries, except that there is no user or group name qualifier.
If you want to create all three ACLs for the directory, you can issue just one command for
ACLs, and by using
-s
, you can specify the current permission bit settings as follows:
setfacl -s "u::rwx,g::---,o::---,u:jane:rwx,d:u:jane:rwx,f:u:jane:r--" harry
To display the ACLs just created by the
setfacl
command, issue the following command:
getfacl -adf harry
setfacl -s "u::rwx,g::---,o::---,u:jane:rwx,d:u:jane:rwx,f:u:jane:r--" harry
ROGERS @ SC65:/u>getfacl -adf harry
#file: harry/
#owner: HARRY
#group: SYS1
user::rwx
group::---
other::---
user:JANE:rwx
fdefault:user:JANE:r--
default:user:JANE:rwx

Chapter 6. Security customization
245
6.46 Using the ISHELL panel
Figure 6-46 Using the ISHELL panel to create ACLs
Create an ACL using the ISHELL
With the ISPF shell (ISHELL), a user or system programmer can use ISPF dialogs instead of
shell commands to perform many tasks, especially those related to file systems and files. An
ordinary user can use the ISPF shell to work with:

Directories

Regular files

FIFO special files

Symbolic links, including external links
You can also run shell commands, REXX programs, and C programs from the ISPF shell. The
ISPF shell can direct stdout and stderr only to an HFS file, not to your terminal.

246
ABCs of z/OS System Programming: Volume 9
Note:
Features to improve the ISHELL functionality were added on z/OS V1R3. The
ISHELL is a user interface that allows users to work with menus rather than sometimes
cryptic commands. In z/OS V1R3, many new features that have been requested over the
years to improve ISHELL functionality and panel navigation are implemented.
These new features are a significant upgrade to the ISHELL, and many of them are part of
the Directory List option, which lists files in a particular directory. Other enhancements
include sorting and highlighting support, as well as easy ways to access information. The
effective user ID(EUID) is displayed on the panel so you can know the authority you have
at any particular moment. In the figure, EUID=0 indicates that the current UID that is
accessing the ISHELL is a superuser.

Chapter 6. Security customization
247
6.47 Create an access ACL using ISHELL
Figure 6-47 Creating an access ACL using the ISHELL
Create an access ACL using the ISHELL
Figure 6-47 shows the Directory List that is displayed once you have entered the ISHELL,
typed
/u
on the command line, and pressed Enter.
Placing an “
a
” action code for directory HARRY results in the File Attribute

panel being
displayed. This is the first step to create ACLs.
In the following sections we describe how to create an ACL that gives user JANE access to
directory HARRY.
a
Use "a" as an action character to access the File attributes
Create an ACL for user jane to access directory harry

248
ABCs of z/OS System Programming: Volume 9
6.48 File attributes panel for /u/harry
Figure 6-48 Display File Attribute panel showing no ACL exists
Working in the ISHELL
If you scroll forward twice, you can see if a Directory Default ACL or File Default ACL is
defined, as shown in Figure 6-49. These two fields (Directory Default and File Default ACL)
only apply to directory files.
Current Access control list shows a 0
To create an ACL, place cursor under Edit and press Enter

Chapter 6. Security customization
249
6.49 File attributes panel showing ACLs
Figure 6-49 Display file attributes panel showing ACLs
Panel to display ACLs
Figure 6-49 shows the Directory default ACL and the File default ACL for the pathname
/u/harry.
For directory /u/harry, the Directory default ACL and File default ACL fields both show zeros,
indicating that no directory or file ACL exists.

250
ABCs of z/OS System Programming: Volume 9
6.50 Select option to create an access ACL
Figure 6-50 Select Option 8 to create the access ACL
Select option for ACL creation
Specify either option 8, 9, or 10, then press Enter; you now have access to modify, add, or
delete the ACL entries for the access ACL, directory default ACL, and the file default ACL,
respectively.

Chapter 6. Security customization
251
6.51 Create an access ACL
Figure 6-51 Creating the access ACL for directory HARRY
Window to create the ACL
Figure 6-51 shows the panel used to create an ACL for a user ID to give access to a file or
directory. In this example, you are going to give user JANE access to directory HARRY. To do
this, place a 2 on the Option line and press Enter.
Type a 2 on the Option line to create ACL - press Enter

252
ABCs of z/OS System Programming: Volume 9
6.52 Add an access ACL
Figure 6-52 The Add an ACL Entry window is used to create the ACL
Window to choose permission bits for the ACL access
Use the panel shown in Figure 6-52 to specify the permission bit settings that you require to
give user JANE access to directory HARRY. Give user JANE
rwx
(read, write and execute)
access to directory HARRY, as shown in the Pathname field in the figure. the panel in
Figure 6-53 shows the newly created ACL after you press Enter.
Place a / next to each permission required
Enter name of user ID - press Enter

Chapter 6. Security customization
253
6.53 Access ACL after creation
Figure 6-53 Display of access ACL after creation
Display of access ACL using the ISHELL
The ACL list is ordered with the group ACLs before the user ACLs. Initially the group and user
ACLs are ordered by name. This order can be changed with the command
sort id
or
sort
name
. This list will only show UIDs and GIDs that have associated names. The
setfacl
shell
utility must be used to manage entries with UIDs and GIDs that are not defined on this
system.
The panel shows the newly created access ACL that gives user JANE rwx access to directory
/u/harry.
You can use D in the selection field (S) to delete the ACL entry.
The END command (F3) will exit the ACL list and save any changes. The SAVE command
can also be used to save changes but will not exit the ACL list.

254
ABCs of z/OS System Programming: Volume 9
6.54 ACL inheritance: New directory/new file
Figure 6-54 ACL inheritance
ACL inheritance
The directory structure is changed, as shown in Figure 6-54, by issuing the following
command:
mkdir /u/harry/programx
The new directory, programx, inherits an access ACL from the directory default ACL of
directory HARRY, and inherits the directory default ACL and file default ACL from directory
HARRY.
ACL inheritance, as shown in the figure, associates an ACL with the newly created file,
myfile
,
without requiring administrative action. However, it is not always necessary to apply ACLs on
every file or directory within a subtree. If you have a requirement to grant access to an entire
subtree (for example, a subtree specific to a given application), then access can be
established at the top directory. If a given user or group does not have search access to the
top directory, then no files within the subtree will be accessible, regardless of the permission
bit settings or ACL contents associated with these files. The user or group will still need
permission to the files within the directory subtree where appropriate. If this is already granted
by the “group” or “other” bits, then no ACLs are necessary below the top directory.
Note:
When defining ACLs, it is recommended to place ACLs on directories, rather than on
each file in a directory.
access
ACL
directory
default
ACL
file
default
ACL
access
ACL
directory
default
ACL
file
default
ACL
access
ACL
oedit
/u/harry/programx/myfile
-
myfile
programx
/
jane tom harry
u
bin etc dev tmp
...
mkdir /u/harry/programx

Chapter 6. Security customization
255
6.55 Multilevel security with z/OS V1R5
Figure 6-55 Using multilevel security beginning with z/OS V1R5
Multilevel security (MLS)
Traditionally, access to z/OS UNIX resources is based on POSIX permissions. Beginning with
z/OS V1R5, if the SECLABEL class active, additional security is provided by authorization
checks that are performed for security labels, in addition to POSIX permissions. Security
labels are used to maintain multiple levels of security within a system. By assigning a security
label to a resource, the security administrator can prevent the movement of data from one
level of security to another within the z/OS UNIX environment.
When the SECLABEL class is active, security labels can be set on z/OS UNIX resources.
zFS root
zFS and HFS can both participate in shared sysplexes. However, only zFS supports security
labels. Therefore, in a multilevel-secure environment, you must use zFS file systems instead
of HFS file systems. See
z/OS Planning for Multilevel Security
, GA22-7509 for more
information on multilevel security and migrating your HFS version root to a zFS version root
with security labels.
When an HFS file system or zFS aggregate is created, the file system root will be assigned
the security label that is specified in the RACF data set profile that covers the data set name.
If a security label is not specified or if a data set profile does not exist, then a security label will
not be assigned to the file system root.
Support is added allowing SECLABELs to be
associated with file system resources and users to
provide greater restrictiveness than is possible with
POSIX permissions alone
ALL systems must be z/OS V1R5 or above
Requires use of zFS for ROOT and /dev resources
Requires use of zFS for all file systems mounted for
readwrite access

256
ABCs of z/OS System Programming: Volume 9
6.56 Multilevel security (MLS)
Figure 6-56 Understanding multilevel security
Classifying data
Security classification of users and data allows installations to impose additional access
controls on sensitive resources. Each user and each resource can have a security
classification in its profile. You can choose among the following:

A security level (SECLEVEL) is an installation-defined name that corresponds to a
numerical security level (the higher the number, the higher the security level).

A security category (CATEGORY) is an installation-defined name that corresponds to a
department or an area within an organization in which the users have similar security
requirements.

A security label (SECLABEL) is an installation-defined name that corresponds to a
security level and zero or more security categories.
Multilevel-secure environment
The security policy that you implement in a multilevel-secure environment has as its key
feature a system of access controls that not only prevents individuals from accessing
information at a classification for which they are not authorized, but also prevents individuals
from declassifying information. The system must protect resources of different levels of
sensitivity.
Multilevel security is a security policy that allows:
Classification of data and users based on:
Hierarchical security levels combined with
Non-hierarchical security categories
Multilevel-secure security policy has two primary
goals, as follows:
First, the controls must prevent unauthorized
individuals from accessing information at a higher
classification than their authorization
Second, the controls must prevent individuals from
declassifying information

Chapter 6. Security customization
257
6.57 MLS support for z/OS UNIX
Figure 6-57 MLS support in z/OS UNIX
SECLABELS for z/OS UNIX processes and sockets
This function has been modified to allow SECLABELs to be defined as follows:

For workstations (allowing for both reading and writing)

To support the z/OS UNIX environment where a user may enter the system from a remote
IP address using an application such as rlogin

To associate SECLABELs to IP addresses
SECLABELS for z/OS UNIX files and directories
RACF assigns a user’s SECLABEL to a new file or directory when it is created. The
SECLABEL cannot be changed. Use the z/OS UNIX command
chlabel
to create the
SECLABEL. The SECLABEL can be changed by copying the file to a directory with a different
SECLABEL. Because subdirectories have the same SECLABEL as the parent directory, files
in a directory will have the same SECLABEL as the directory.
SECLABELS for z/OS UNIX interprocess communication (IPC)
When creating an IPC security packet (ISP), if the SECLABEL class is active, RACF will copy
the process SECLABEL (if one exists) into the ISP. Later, when checking access to the IPC
for a subsequent connection, RACF will reject the request if the current process does not
have a SECLABEL or the SECLABEL does not match. Once a SECLABEL has been
assigned to an IPC object, there is no way to change it.
SECLABELs for z/OS UNIX processes and sockets
SECLABELs for z/OS UNIX files and directories
SECLABELs for z/OS UNIX interprocess
communications (IPC)
zFS supports security labels for MLS
Externals for MLS are contained in other
elements/components
(RACF, shell, z/OS UNIX APIs, etc.)
zFS supports low level functions for MLS

258
ABCs of z/OS System Programming: Volume 9
Access checking for IPC objects will be treated as EQUALMAC checking, meaning that
SECLABELs must be equivalent, unless the resource’s SECLABEL is SYSMULTI, or the
accessor’s SECLABEL is SYSMULTI.
zFS support for SECLABELs
The zSeries file system (zFS) supports security labels. A zFS file system is contained in a
VSAM linear data set. The security label of the root within each zFS file system data set is
determined at the time the file system aggregate (container) is allocated, from the security
label of the profile in the DATASET class that covers the aggregate. If the SECLABEL class is
active when allocating the aggregate, all file systems subsequently created within that
aggregate contain a root with the security label that is specified in the profile for that
aggregate. If no profile exists for the aggregate, or if it exists but does not specify a security
label, and if the MLFSOBJ option is not active, the root for any file systems within that
aggregate has no security label. If the MLFSOBJ option is active, requiring security labels on
all file system objects, the user's security label is assigned to the root of the file system.
zFS stores security labels in the FSP in the metadata. zFS calls RACF for security label
processing and also can do some checking on its own.
MLS support
z/OS V1R5 support includes support for MLS with the following components:

RACF

z/OS UNIX System Services

zFS

TCP/IP

JES2 (not JES3)

SDSF

DFSMS - MLS SECLABELs in ACS Routines

DB2 V8 - Security labels on rows in tables

Chapter 6. Security customization
259
6.58 Mandatory access control (MAC)
Figure 6-58 Mandatory access control (MAC) checking
MAC checking
Mandatory access control is based on the theory of
dominance
, and is achieved through the
use of security labels.
Dominance
One security label dominates a second security label when the following two conditions are
true:

The security level that defines the first security label is greater than or equal to the security
level that defines the second security label.

The set of security categories that defines the first security label includes the set of
security categories that defines the second security label.
MAC checking overview
A mandatory access check compares the security labels of the subject and object and grants
the subject access to the object as follows:

A subject can read an object if the subject's security label dominates the object's security
label.

A subject can write to an object if the object's security label dominates the subject's
security label. A subject cannot write to an object whose security label the subject's
security label dominates, unless the security labels are equivalent; we say that the subject
is not allowed to write down.
A MAC check compares the security labels of the
subject and object and grants the subject access to
the object
A subject can read an object if the subject's security
label dominates the object's security label
A subject can write to an object if the object's security
label dominates the subject's security label
A subject cannot write to an object whose security
label the subject's security label dominates, unless the
security labels are equivalent - not allowed to write
down
A subject can both read and write an object only if the
subject's and object's security labels are equivalent

260
ABCs of z/OS System Programming: Volume 9

A subject can both read and write an object only if the subject's and object's security
labels are equivalent.
To ensure that a user does not declassify data, a subject can read from and write to (alter)
only an object with an equivalent security label; however, a subject can copy information from
an object having a security label that does not dominate the security label of the subject to an
object having the subject's current security label. Or, for objects that support write-only
processing, such as z/OS UNIX files, to an object with a security label that dominates the
subject's security label.

Chapter 6. Security customization
261
6.59 Discretionary access control (DAC)
Figure 6-59 Discretionary access control (DAC) checking
Discretionary access control checking
Discretionary access control is the principle of restricting access to objects based on the
identity of the subject (the user or the group to which the user belongs). Discretionary access
control is implemented using access control lists. A resource profile contains an access
control list that identifies the users who can access the resource and the authority (such as
read or update) each user is allowed in referencing the resource. The security administrator
defines a profile for each object (a resource or group of resources), and updates the access
control list for the profile. This type of control is discretionary in the sense that subjects can
manipulate it, because the owner of a resource, in addition to the security administrator, can
identify who can access the resource and with what authority.
Once the user passes the mandatory access check, a discretionary check follows. The
discretionary access check ensures that the user is identified as having a “need to know” for
the requested resource. The discretionary access check uses other access control
information, such as the access control list in the profile protecting a resource, or z/OS UNIX
access control (permissions, the access control list, and the UNIXPRIV class).
Once the user passes a MAC check, a discretionary
check follows
A DAC check ensures that the user is identified as
having a "need to know" for the requested resource
DAC uses other access control information, such as:
Access control list in the profile protecting a resource
z/OS UNIX access control (permissions, the access
control list, and the UNIXPRIV class)
MAC check occurs first, then DAC
Or DAC only, if the SECLABEL class is not active

262
ABCs of z/OS System Programming: Volume 9
6.60 SECLABELs and MAC
Figure 6-60 SECLABELs with categories and MAC checking
SECLABELs with categories and MAC checking
A security label establishes an association between a RACF security level and a set of zero or
more RACF security categories. For example, the system shown in Figure 6-60 might have
three security levels: unclassified, sensitive, and secret; and three security categories: Project
A, Project B, and Project C. Then, PURPLE could be a security label name indicating Secret
for Project A, Project B, and Project C. COLUMBIA could be a security label name meaning
Sensitive for Project A and Project B; UNION could be a security label name indicating
unclassified for Project C.
Defining SECLABELs
The security administrator defines two profiles in the RACF SECDATA resource class that
define the security levels and security categories for the system:

The SECLEVEL profile contains a member for each hierarchical security level in the
system.

The CATEGORY profile contains a member for each non-hierarchical category in the
system.
SECLEVEL
The hierarchical security level defines the degree of sensitivity of the data.
“SECRET,” “SENSITIVE,” and “UNCLASSIFIED” are examples of levels
you could define. You might define “SECRET” to be a security level of 30,
“SENSITIVE” to be a level of 20, and “UNCLASSIFIED” to be a level of 10.
The security administrator can define up to 254 security levels.
PURPLE could be a SECLABEL name indicating
SECLEVEL secret for categories PROJECTA,
PROJECTB, and PROJECTC
GREEN could be a SECLABEL name indicating
SECLEVEL sensitive for categories PROJECTA and
PROJECTB
RED could be a SECLABEL name indicating
SECLEVEL unclassified for category PROJECTC
SETROPTS CLASSACT(SECLABEL) RACLIST(SECLABEL)
SECLABEL SECLEVEL
PROJECTA, PROJECTB, PROJECTC
GREEN
RED
UNCLASSIFIED
SENSITIVE
SECRET
PURPLE
PROJECTA, PROJECTB
PROJECTC
CATEGORY (Not required)

Chapter 6. Security customization
263
CATEGORY
The non-hierarchical categories further qualify the access capability. The
security administrator can define zero or more categories that correspond
to some grouping arrangement in the installation. “PROJECTA,”
“PROJECTB,” and “PROJECTC” could be categories defined.
Security labels
After defining the SECLEVEL and CATEGORY profiles, the security
administrator defines a profile in the SECLABEL resource class for each
security label. Each security label name must be unique. Each SECLABEL
profile specifies the particular combination of a SECLEVEL member and
zero or more members of the CATEGORY profile that applies to the
security label. You do not need to define a security label for every possible
combination of level and category.
SECLABEL dominance with categories
One security label dominates a second security label when the following two conditions are
true:

The security level that defines the first security label is greater than or equal to the security
level that defines the second security label.

The set of security categories that define the first security label includes the set of security
categories that defines the second security label.
Two security labels are said to be disjoint or incompatible if neither dominates the other
because they have incompatible sets of categories. For example, if SECLABEL GREEN has
categories PROJECTA and PROJECTB, and SECLABEL RED has categories PROJECTC,
neither contains all the categories of the other, so neither dominates the other and they are
disjoint.

264
ABCs of z/OS System Programming: Volume 9
6.61 Special SECLABELs and definitions
Figure 6-61 Special SECLABELs and their definitions
System SECLABELs
At IPL time, RACF dynamically creates system SECLABELs that cannot be defined, modified,
or deleted by any user, but can be assigned to users and resources. The following
SECLABELs are defined:
SYSHIGH
SYSHIGH is created at the highest security level defined to RACF and
includes all defined categories. Resources with SYSHIGH can be accessed
only by users with SYSHIGH; users with SYSHIGH have access to all other
SECLABELs. If a higher level or additional categories are defined, SYSHIGH
automatically assumes the new values when the SECLABEL class is
refreshed.
SYSLOW
SYSLOW is created at the lowest security level defined to RACF and includes
no categories. Resources with SYSLOW can be accessed by users with any
valid SECLABEL; users with SYSLOW can access only resources that are
SYSLOW. If a lower level is defined, SYSLOW automatically assumes the
new value when the SECLABEL class is refreshed.
SYSNONE
SYSNONE is assigned to resources that have no security-relevant data. MAC
verification considers SYSNONE to be equivalent to any user’s SECLABEL,
automatically allowing access. Assigning SYSNONE to a user has the same
effect as assigning SYSLOW to the user.
SYSMULTI
The SYSMULTI SECLABEL is new with z/OS V1R5. The SYSMULTI security
label is equivalent to any other security label.
SYSHIGH - SYSLOW - SYSNONE
SYSMULTI - (New with MLS in z/OS V1R5)
Defining SECLABELs
RDEFINE SECLABEL security-label
SECLEVEL(seclevel-name)
ADDCATEGORY(category-1 category-2 ...)
PERMIT security-label CLASS(SECLABEL)
ACCESS(READ) ID(user-id-1 user-id-2 ...)
SETROPTS CLASSACT(SECLABEL)
RACLIST(SECLABEL)
or
SETROPTS RACLIST(SECLABEL) REFRESH

Chapter 6. Security customization
265
6.62 SYSMULTI SECLABEL
Figure 6-62 SYSMULTI SECLABEL
SYSMULTI SECLABEL
SYSMULTI can be assigned in cases where any classification of data could be processed. It
compares as equivalent to any other defined SECLABEL for MAC decisions.
It is intended for the following types of functions:

Daemons and servers that can accept connections from users running at different
classification levels (SECLABELs) and properly mediate data access

UNIX directories (often, not always, root in a file system) that can have subdirectories of
different SECLABELs
It generally should not be assigned to real users, nor to a server that is not designed to handle
multiple SECLABELs.
Assigning SYSMULTI to directories
If a directory has been assigned a security label, then new files and directories created within
that directory will inherit a security label as follows:

If the parent directory is assigned a security label of SYSMULTI, the new file or directory
will be assigned the security label of the user. If the user has no security label, then one is
assigned to the new object.

If the parent directory is assigned a security label other than SYSMULTI, the new file or
directory is assigned the same security label as the parent directory.
SYSMULTI
Compares as "equivalent" to any other defined
SECLABEL for MAC decisions
Intended for daemons and servers that can accept
connections from users running at different
classification levels (SECLABELs) and properly
mediate data access
UNIX directories (often, not always, root in a file
system) that can have subdirectories of different
SECLABELs

266
ABCs of z/OS System Programming: Volume 9
6.63 z/OS UNIX and SECLABELs
Figure 6-63 Defining SECLABELs with z/OS UNIX
Defining SECLABELs
The
chlabel
shell command allows a security administrator to assign a security label to a file
system object that does not have one.
If a z/OS UNIX file, directory, or symbolic link was created in a zFS file system without being
assigned a security label (for example, if the SECLABEL class was not active when the file,
directory, or symbolic link was created), the security administrator can assign a security label
to it using the
chlabel
shell command.
chlabel command
chlabel
sets the multilevel security label of the files and directories specified by pathname.
Setting the seclabel is only allowed if the user has RACF SPECIAL authority, and no seclabel
currently exists on the resource. Once a seclabel is set, it cannot be changed.
Note:
zFS file systems support the chlabel utility, which allows the setting of an initial
security label on a file or directory. Use this utility to set security labels on allocated zFS
files and directories
after
they have been created.
chlabel command
This new shell command chlabel can be used to set
security labels for UNIX files and directories
Requires RACF SPECIAL authorization
Recommended do this command before MLS
activated
Once SECLABEL has been set, it cannot be changed
chlabel [–cqR] [–h|–L] seclabel pathname
By specifying the -R parameter, labels are set
“recursively” on file subdirectories
Note: Only the zFS file systems supports the setting of SECLABELs

Chapter 6. Security customization
267
6.64 Understanding UMASK
Figure 6-64 Understanding the UMASK
Defining the UMASK
When a file is created, it is assigned initial access permissions. If you want to control the
permissions that a program can set when it creates a file or directory, you can set a file mode
creation mask using the
umask
command.
The user can set this file mode creation mask for one shell session by entering the
umask

command interactively, or you can make the
umask
command part of your login. When you set
the mask, you are setting a limit on allowable permissions: You are implicitly specifying which
permissions are not to be set, even though the calling program may allow those permissions.
When a file or directory is created, the permissions set by the program are adjusted by the
umask value: the final permissions set a the program's permissions minus what the umask
values restrict.
To use the
umask
command for a single session, enter:
umask mode
To create a mask that sets read-write-execute permission
on
for the owner of the file and
off

for everyone else, enter:
umask 077
Set the default file creation mask:
umask 022
Default mask is: 022 000 010 010
New file created with permission bits: 777
rwx rwx rwx
111 111 111
000 010 010
111 101 101
File
UMASK
File permission bits (with UMASK): 755

268
ABCs of z/OS System Programming: Volume 9
6.65 Displaying the UMASK
Figure 6-65 Displaying the UMASK
Displaying the UMASK
The umask sets the file-creation permission-code mask of the invoking process to the given
mode.
The mode may be specified in symbolic (rwx) or octal format. The symbolic form specifies
what permissions are allowed. The octal form specifies what permissions are disallowed.
The file-creation permission-code mask (often called the umask) modifies the default (initial)
permissions for any file created by the process. The umask specifies the permissions which
are not to be allowed.
If the bit is turned off in the umask, a process can set it on when it creates a file. If you specify:
umask a=rx
you have allowed files to be created with read and execute access for all users. If you were to
look at the mask, it would be 222. The write bit is set, because write is not allowed. If you want
to permit created files to have read, write, and execute access, then set umask to 000. If you
call
umask
without a mode argument, umask displays the current umask.

ROGERS @ SC47:/etc>umask
0022
ROGERS @ SC47:/etc>umask -S
u=rwx,g=rx,o=rx
ROGERS @ SC47:/etc>umask u=rwx,go=r
ROGERS @ SC47:/etc>umask
0033
ROGERS @ SC47:/etc>
===>
Symbolic and Octal UMASK notation

Chapter 6. Security customization
269
6.66 Default permissions and UMASK
Figure 6-66 Default permissions and the UMASK
Default permissions
The system assigns default permission bits for files and directories at creation time. The
settings depend on the type of command or facility that is used, and in some cases, on the
type of file that is created.
A user can change the default setting when a file is created by using the
umask
shell
command. The values set by the
umask
command will last for the length of the user's session,
or the command can be part of the user's login so that the user always has the same default
permissions.
PATHDISP indicates how MVS should handle the file when the job step ends normally or
abnormally. This performs the same function as the DISP parameter for a data set.
umask
In /etc/profile, umask sets the default file creation mask. Using a umask of 022 causes a file
created with mode 777 to have permissions of 755. The creator cannot set the group write or
other write bits on in the file mode field, because the mask sets them off.
==> umask 022
Changes defaults for a user
Command Default Permission
mkdir
MKDIR
JCL, no PATHOPTS
OEDIT
vi editor
ed editor
Redirection (>)
cp
OCOPY
OPUT/OPUTX
rwx r-x r-x
rwx r-x r-x
--- --- ---
rwx --- ---
rw- r-- r--
rw- r-- r--
rw- r-- r--
output = input
--- --- ---
rw- --- --- (text)
rwx --- --- (binary)
rwx rwx rwx
rwx r-x r-x
--- --- ---
rwx --- ---
rw- rw- rw-
rw- rw- rw-
rw- rw- rw-
output = input
--- --- ---
rw- --- --- (text)
rwx --- --- (binary)
Final settings after umask

270
ABCs of z/OS System Programming: Volume 9
Changing the default permission settings
The umask service changes the process's file creation mask. This mask controls file
permission bits that are set whenever the process creates a file. File permission bits that are
turned on in the file creation mask are turned off in the file permission bits of files that are
created by the process. For example, if a call to the open service, BPX1OPN, specifies a
“mode” argument with file permission bits, the process's file creation mask affects that
argument. Bits that are on in the mask are turned off in the mode argument, and therefore in
the mode of the created file.
If you use the MKDIR TSO/E command to create a directory, the permission bits will be
different than if you use the shell command
mkdir
to do the same thing.
Each user can influence these defaults for his or her shell session by using the
umask

command.
umask
sets the file-creation permission-code mask of the invoking process to the
given mode. You can specify the mode in any of the formats recognized by
chmod
.
As stated previously, the file-creation permission-code mask determines the default
permissions for any file created by the process. For example, a file created by the
vi

command has the permissions specified by the umask unless the
vi
command specifies
explicit permissions itself.
Redirecting command output to a file
Commands entered at the command line typically use the three standard files (STDIN,
STDOUT, and STDERR), but you can redirect the output for a command to a file you name. If
you redirect output to a file that does not already exist, the system creates the file
automatically.

Chapter 6. Security customization
271
6.67 Example of creating a new file
Figure 6-67 Example of creating a new file
Creating a new file
In this example the user JANE (UID 73) is creating a new file. A file could be created in
various ways. It could be copied from another file, it could be created with an editor, it could
be moved, it could be created using JCL, and so on.
Security for a file is specified in the file security packet (FSP) which is a part of the attributes
of the file. Each file has an FSP. The FSP is created when the file is created and is deleted
when the file is deleted.
The contents of the FSP are determined as follows:

The owning UID of the new file is taken from the effective UID (EUID) of the process that
creates the file.

The owning GID of the new file is taken from the owning GID of the directory for the new
file.

The file permission bits are set by the process that creates the file. The setting of the
permission bits can be different, depending on the method used to create the file.
Effect of the UMASK
In this example, the user has set a umask to specify what the permissions should be for all
files that the user creates. To do this, the user JANE issued the following shell command:
umask u=rwx,go=r
Directory: projectb
File: prog1
bill
JANE
UID
GID
owner
group
other
UID
GID
owner
group
other
42
595
rwx
rwx
r-x
data
Process
UID=73, GID=595
umask u=rwx,go=r
vi editor
/u/bill/projectb/prog1
(umask u=033)
73 595 rw- r-- r--

272
ABCs of z/OS System Programming: Volume 9
This will give the owner of the file
r
,
w
, and
x
access, while group and others will get
r
access.
Settings for the new file
As illustrated in Figure 6-67, when the new file is created:

The UID of the file is set to 73.

The GID is set to 595.

The file permission bits are set according to the umask as follows:
– The file owner has
rw
, which mean read and write access.
– Users in the group with a GID of 595 have
r--
, which means read access.
– All other users (also known as world) have
r--
, which means read access.
In order to create a new file, the user must have write access to the directory for the new file.

Chapter 6. Security customization
273
6.68 Can user JOE access the file
Figure 6-68 Can a user access the newly created file
User access to the new file
In this example, another user who has a UID of 65 wants read access to the file
/u/bill/projectb/prog1.
This user is not a superuser and is not a privileged or trusted started procedure.
The UID of the process, 65, does not match the file UID.
The GID of the process does match the file GID, and therefore the group permissions apply.
The user wants read access and the permissions are
r--
, so the user is allowed access.
If the effective GID of the process did not match the file GID, RACF would have looked at the
user's list of groups (assuming that RACF list of groups is active) for a group that has a GID
that is the same as the file GID.
In order to access a file, the user must also have read and search permission to all directories
in the path.
Directory: projectb
File: prog1
bill
JOE
UID
GID
owner
group
other
UID
GID
owner
group
other
42
595
rwx
rwx
r-x
data
Process
UID=65, GID=595
OBROWSE
/u/bill/projectb/prog1
for read
73 595 rw- r-- r--

274
ABCs of z/OS System Programming: Volume 9
6.69 Can user ANN copy the file
Figure 6-69 Can a user copy the newly created file
Access to copy the new file
In this example, a user called ANN with a UID=88 wants to copy the file that user JANE
created. The user is not a superuser, and is not a privileged or trusted started proc. This user
is not the owner of the file and none of this user's groups have a GID that match the GID of
the file.
In this case, access will be determined by the permissions for other users. Since the
permission for other users is read access (
r--
), the user is allowed to copy the file.
User ANN does not have a umask set and the file permissions will be determined by the
defaults for the
cp
command which was the method used for the copy. The new file will get the
following attributes:

The UID will be set to the UID of the person who copied the file. This will be 88.

The GID will be GID of the directory where the file will be placed, which is 225.

The file permission bits will be copied from the file
prog1
since this is the default for the
cp
command.
Directory: projectb
File: prog1
bill
ANN
UID
GID
owner
group
other
UID
GID
owner
group
other
42
595
rwx
rwx
r-x
data
Process
UID=88, GID=225
COPY
/u/bill/projectb/prog1
73
595
rw-
r--
r--
UID
GID
owner
group
other
data
88
225
rw-
r--
r--
Directory: /u/dept5/work
UID
GID
owner
group
other
50
225
rwx
rwx
r-x
File: prog1
c
p

c
o
m
m
a
n
d

Chapter 6. Security customization
275
6.70 Setting file permissions
Figure 6-70 Commands to set permission bits
Commands to change permission bits
A file's mode mask includes the file permission bits, the SetUID bit, the SetGID bit, and the
sticky bit. The file security packet (FSP) has the setuid, setgid, and sticky bits.
The chmod command
The initial permission bit for the file prog1 is shown in the box at the top right. The
chmod

command is used to make a change to the file mode mask of a file or directory, as follows:
rwx
---
---
---
---
---
---
---
---
---
rw-
r-- r--
rwx
rwx
rwx
rwx
rwx
s--
u
g
o
a
chmod u-x,g+r,o+r prog1 , or
chmod u=rw,go=r prog1
chmod a=rwx prog1 , or
chmod rwx prog1
chmod go-rwx prog1 , or
chmod u=rwx prog1
chmod u+s prog1
Permission bits for file prog1:
Symbolic Notation
File Permission Bits
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w
x
r
w
x
r
w
x
Owner Group Other
File Mode
extattr
Access
ACL
exists
File
model
ACL
exists
Directory
model
ACL
exists
ACL Flags

276
ABCs of z/OS System Programming: Volume 9

The z/OS UNIX shell command
chmod u-x,g+r,o+r
deletes execute (
x
) from the owner (
u

for user) permissions, adds read (
r
) to the group (
g
) permissions, and adds read (
r
) to the
other (
o
) permissions.

The same effect can be achieved with
chmod u=rw,go=r
which sets the owner (
u
) mask to
read/write (
rw
), and sets the group and other (
go
) mask to read (
r
). When the equal sign is
used, it turns on the bits specified and turns off all other bits.

The command
chmod a=rwx
sets on the read, write, and execute bits for all (
a
) users, which
includes the owner, group, and other.

An equivalent command is
chmod rwx
in which the
a
(all users) is implied.

In the command
chmod go-rwx
,
rwx
is turned off for group and other.

An alternative form
chmod u=rwx
sets
rwx
on for the owner (u) mask, and turns off all other
bits.

The command
chmod u+s
shows how to turn on the SetUID bit. The
s
stands for set, and
the
u
stands for UID. If we wanted to turn on the SetGID bit, we would use
chmod g+s
.
Turning on the sticky bit would be achieved using
chmod +t
.
We cannot use RACF commands or panels to set the permissions. We use the z/OS UNIX
shell commands. This is the same as AIX and UNIX. An alternative to the
chmod
command is
to use the ISHELL menus. They may be more user-friendly for people who are not familiar
with UNIX, and they provide help information.
Note:

chmod
can only be used by the file owner or a superuser.

Chapter 6. Security customization
277
6.71 Setting file permissions
Figure 6-71 Commands to set the permission bits
Command to sets bits using octal notation
Octal notation can be used on the
chmod
command instead of the symbolic notation. With
octal notation, each set of three bits is represented in a single octal digit. For example, a
permission of rwx would be represented as the octal digit 7 which is the sum of the 4 for read
(r), the 2 for write (w), and 1 for execute/search (x), as follows:

In the command
chmod 644
the octal 6 sets read and write (4+2) for the file owner, and sets
read (4) for group and other users.

The command
chmod 777
sets on read/write/execute (4+2+1) for the owner, group, and
other users.

The command
chmod 700
sets on the read, write, and execute bits (4+2+1) for the owner,
and gives no access to group and other users.

In the last command
chmod 4700
we see how to set the set UID, set GID, and sticky bits.
This is done by using four octal digits, where the first digit represents the set UID, set GID,
and sticky bits. Here, SetUID is the left-most bit (4), SetGID is the middle bit (2), and the
sticky bit is the right-most bit (1).
Note:
To specify permissions for a file or directory, you use at least a three digit octal
number, omitting the digit in the first position. When you specify three digits instead of four,
the first digit describes owner permissions, the second digit describes group permissions,
and the third digit describes permissions for all others.
rwx
---
---
---
---
---
---
---
-
--
---
---
rw-
r--
r--
rwx
rwx
rwx
rwx
rwx
s--
chmod 644 prog1
chmod 777 prog1
chmod 700 prog1
Permission bits for file prog1:
421
421
421
421
Octal Notation
chmod 4700 prog1

278
ABCs of z/OS System Programming: Volume 9
6.72 List file and directory information
Figure 6-72 Listing the file and directory permission settings
Command to list permission bit settings
The
ls
command can be used to list important information about files and directories. If the
ls

command is used for a directory, it will display this information for all the files in the directory
as shown in Figure 6-72.
Although there are 25 different options for the
ls
command, we only show the output for one
option,
-l
, which stands for long. The file type in position 1 in the output indicates the type of
file that is displayed on this line:
-
Regular file
d
Directory
b
Block special file (not supported for z/OS UNIX)
c
Character special file (for example, device)
l
Symbolic link
e
External link
p
FIFO special file (also known as a named pipe)
s
Socket file type
Positions 2 through 10 represent the file permissions for the owner, group, and other users.
File
type
File
permissions
Links
Owner
userid
Owner
groupid
File
size
Date
and
time
Name
ROGERS @ SC65:/u/rogers>ls -l /usr/man/C

total 136
drwxr-xr-x 2 HAIMO OMVSGRP 8192 May 29 2002 IBM
drwxr-xr-x 3 HAIMO OMVSGRP 8192 Jun 10 2002 cat1
drwxrwxr-x 3 HAIMO OMVSGRP 8192 May 29 2002 cat8
drwxr-xr-x 3 HAIMO OMVSGRP 8192 May 29 2002 man1
-rw-rw-r-- 2 HAIMO OMVSGRP 33887 May 29 2002 whatis


Chapter 6. Security customization
279
6.73 Introducing daemons
Figure 6-73 Introducing z/OS UNIX daemons
Introducing z/OS UNIX daemons
A daemon process is a process that runs in the background environment and is not
associated with any particular terminal or user. Daemons run authorized (superuser
authority) and can issue authorized functions like the following to change the identity of a
user's process:

setuid()

seteuid()

setreuid

pthread_security_np()

auth_check_resource_np()

_login()

_spawn() with user ID change

_password()
Daemon authority
Daemon authority is required only when a program does a setuid(), seteuid(), setreuid(), or
spawn() user ID to change the current UID without first having issued a __passwd() call to the
Note:
The spawn() service is allowed to create a new image under a specific user ID that is
different from that of the invoker. When an invoker with appropriate privileges specifies a
username on the _BPX_USERID environment variable or in the inheritance structure
(INHEUSERID), the resulting image runs under the associated MVS user identity.
LISTEN
fork,
spawn
User = OMVSKERN
UID = 0
Work
Request
UID = 25
User = BOB
UID = 25
Child Process
in WLM AS
Change UID
setuid(25)
Execute
work
Exit
User = BOB
Start

280
ABCs of z/OS System Programming: Volume 9
target user ID. In order to change the MVS identity without knowing the target user ID's
password, the caller of these services must be a superuser. Additionally, if a BPX.DAEMON
FACILITY class profile is defined and the FACILITY class is active, the caller must be
permitted to use this profile. If a program comes from a controlled library and knows the target
UID's password, it can change the UID without having daemon authority.
You can run daemons with regular UNIX security or with z/OS UNIX security. A z/OS UNIX
daemon could also be described as a classical server process. Initially, the daemon process
is started by an external command or event. Once started, the daemon
listens

for work
requests from clients. When a request is received, the daemon will note the UID of the
requester, and then fork a child process to carry out the request. Before executing the
request, the daemon uses a special SYSCALL
setuid
to reset the security environment to
match that of the requester.
For administrators, controlling daemons requires some extra considerations:

How and when is a daemon process started (or restarted if it fails)?

Daemons often need initialization options customized to installation requirements.

Daemons have the ability to issue
setuid()
. Access to this type of power needs to be
controlled, by controlling which programs can be daemons.

A special user security profile BPXROOT must be created in order to support some
daemon operations.
Daemon authority for the kernel
Give daemon authority to the kernel. Most daemons that inherit their identities from the kernel
address space are started from /etc/rc. To authorize the OMVSKERN user ID for the daemon
FACILITY class profile, issue:
PERMIT BPX.DAEMON CLASS(FACILITY) ID(OMVSKERN) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
Add user BPXROOT
In order for daemon processes to be able to invoke
setuid()
for superusers, define a
superuser with a user ID of BPXROOT on all systems. To define the BPXROOT user ID,
issue:
ADDUSER BPXROOT DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/')
PROGRAM('/bin/sh') PASSWORD(A4B3C3D1)
Exactly how requests are passed to a daemon depends on the type of daemon. For
TCP/IP-based daemons like the telnet or rlogin daemons, the user request will be passed
over a socket connection from the IP network. For the cron daemon, the request is passed via
a parameter area and a cross memory post to the daemon.
Note:
The important point about the
setuid
instruction is that, in a z/OS environment, it will
reset the whole security profile of the forked address space. The UID will be set to the
requester's UID and the current RACF user ID information (the ACEE) will be changed to
BOB to complement the UID. The requester's task therefore runs with access to both the
UNIX and z/OS resources (data sets) owned by BOB.

Chapter 6. Security customization
281
6.74 z/OS UNIX daemons
Figure 6-74 The z/OS UNIX daemons
z/OS UNIX daemons
A daemon is a long-lived process that runs unattended to perform continuous or periodic
system-wide functions, such as network control. Some daemons are triggered automatically
to perform their task; others operate periodically. Daemons typically encountered on z/OS
UNIX systems include:
cron
The batch scheduler, cron is a clock daemon that runs commands at specified
dates and times. You can specify regularly scheduled commands by using the
crontab
command. Jobs that are to be run only once can be submitted using
the
at
or
batch
commands. cron runs commands with priorities and limits set by
a queuedefs file.
ftpd
The file transfer daemon supplied with z/OS Communications Server.
inetd
The Internet daemon. The inetd daemon provides service management for a
network. It starts the rlogind program or otelnetd program whenever there is
either a remote login request or a remote telnet login from a workstation.
lm
The CS login monitor. The login monitor is a daemon that starts the login
process in the shell for logins initiated by Communications Server (CS). CS
nodes then forward service requests to the login monitor, which listens for the
requests on a port number assigned to the lm service.
rlogind
The remote login daemon. The rlogind program is the server for the remote
login command
rlogin
. It validates the remote login request and verifies the
password of the target user. It starts a z/OS UNIX shell for the user and handles
cron
ftpd
inetd
lm
rlogind
uucico
timed
Orouted
lpd
httpd
syslogd
otelnetd
orexec
uucpd
uuxqt

282
ABCs of z/OS System Programming: Volume 9
translation between ASCII and EBCDIC code pages as data flows between the
workstation and the shell.
syslogd
The syslog daemon supplied with z/OS Communications Server. Syslog
daemon (syslogd) is a server process that has to be started as one of the first
processes in your z/OS UNIX environment. Other servers and stack
components use syslogd for logging purposes and can also send trace
information to syslogd.
otelnetd
The remote logon daemon supplied with z/OS Communications Server.
orexecd
The remote execution protocol daemon supplied with z/OS Communications
Server. The Remote Execution Protocol Daemon (REXECD) is the server for
the REXEC routine. REXECD provides remote execution facilities with
authentication based on user names and passwords.
uucpd
The UNIX-to-UNIX copy program daemon. The uucpd daemon is used to
communicate with any UNIX system that is running a version of the
UNIX-to-UNIX copy program. UUCP functions are used to automatically
transfer files and requests for command execution from one UUCP system to
another, usually in batch mode at particular times. Other daemons associated
with uucp include:
uucico
Processes uucp and uux file transfer requests.
uuxqt
Runs commands from other systems.
Orouted
The Orouted daemon is supplied with z/OS Communications Server. The route
daemon is a server that implements the Routing Information Protocol (RIP)
(RFC 1058). It provides an alternative to the static TCP/IP gateway definitions.
lpd
The line printer daemon supplied with z/OS Communications Server. The line
printer daemon enables printers from any TCP/IP host that is attached to the
MVS spooling system.
timed
The time daemon supplied with z/OS Communications Server. The time
daemon provides clients with UTC time. Network stations without a time chip
obtain clocks from this daemon.
httpd
The http daemon supplied with WebSphere.

Chapter 6. Security customization
283
6.75 UNIX-level security for daemons
Figure 6-75 UNIX-level security for daemons
UNIX-level security for daemons
You can run daemons with UNIX-level security or with z/OS UNIX security. If the
BPX.DAEMON (or BPX.SERVER) facility class is not defined, your system has UNIX-level
security. In this case, the system is less secure. This level of security is for installations where
superuser authority has been granted to system programmers. These individuals already
have permission to access critical data sets such as PARMLIB, PROCLIB, and LINKLIB.
These system programmers have total authority over a system.
Daemons are processes that perform services for other users. In order to do this, a daemon
must be able to change its identity temporarily to the identity of the user it will perform work
for. The functions
setuid()
and
seteuid()
are authorized functions which will change the
identity of a z/OS UNIX user or program.
The daemon program clones itself using a
fork()
SYSCALL. The cloned child copy issues
the
setuid()
request to initialize the security environment for the requester. The child issues
exec()
to pass control to the real request program to be executed. Superuser authority is
required to use these functions which requires authority of UID=0. All daemon programs must
execute as superusers, and all superusers are allowed to use the
setuid()
and
seteuid()

functions to change the identity of a process to any other UID. Their z/OS identity will be
changed to the one corresponding to the UID value; in the example, the cron daemon
changes its identity to UID=25, which is the z/OS user ID BOB.
Note:
If the target UID=0, and the target user ID is not known, the kernel sets default user
ID=BPXROOT.
cron
Batch daemon
OMVSCRON
UID=0
BOB
UID=25
BOB's user
environment
MVS
Data Set
zFS File
cron
OMVSCRON
UID=0
setuid(25)
exec cp1
cp1
(copy files)
"fork"
Child Address Space
Superuser?
Y
N
setuid
fails!
"Run program
cp1 for BOB"

284
ABCs of z/OS System Programming: Volume 9
6.76 z/OS UNIX security: BPX.DAEMON
Figure 6-76 z/OS UNIX security with daemons
BPX.DAEMON profiles
If the DAEMON (or BPX.SERVER) FACILITY class is defined, your system has z/OS UNIX
security. Your system can exercise more control over your superusers.
This level of security is for customers with very strict security requirements who need to have
some superusers maintaining the file system but want to have greater control over the z/OS
resources that these users can access. Although BPX.DAEMON provides some additional
control over the capabilities of a superuser, a superuser should still be regarded as a
privileged user because of the full range of privileges the superuser is granted.
The additional control that BPX.DAEMON provides involves the use of kernel services such
as
setuid()
that change a caller's z/OS user identity. With BPX.DAEMON defined, a
superuser process can successfully run these services if the following are true:

The caller's user identity has been permitted to the BPX.DAEMON FACILITY class profile.

All programs running in the address space have been loaded from a library controlled by a
security product. A library identified to RACF Program Control is an example. Individual
files in the HFS can be identified as controlled programs.
Kernel services that change a caller's z/OS user identity require the target z/OS user identity
to have an OMVS segment defined. If you want to maintain this extra level of control at your
installation, you will have to choose which daemons to permit to the BPX.DAEMON FACILITY
class. You will also have to choose the users to whom you give the OMVS security profile
segments.
Provides more control over superusers
Provides a higher level of security
Daemon's identity must be permitted to FACILITY
class
RDEFINE FACILITY BPX.DAEMON UACC(NONE)
PERMIT BPX.DAEMON CLASS(FACILITY)
ID(userid) ACC(READ)
All programs running in the address space
Must be loaded from a library controlled by a security
product

Chapter 6. Security customization
285
6.77 RACF program control
Figure 6-77 Defining RACF program control
RACF program control for daemons
The purpose of protecting load modules is to provide installations with the ability to control
who can execute what programs and to treat those programs as assets.
You protect individual load modules (programs) by creating a profile for the program in the
PROGRAM general resource class. A program protected profile in the PROGRAM class is
called a controlled program.
The name of the profile can be complete, in which case the profile protects only one program,
or the name of the profile can end with an asterisk (*), in which case the profile can protect
more than one program. For example, a profile named ABC* protects all programs that begin
with ABC, unless a more specific profile exists. In this way you can find which programs are
causing the environment (such as PADS checking) to not work.
The profile for a controlled program must also include the name of the program library that
contains the program and the volume serial number of the volume containing the program
library. The profile can also contain a standard access list of users and groups and their
associated access authorities.
Any program loaded into an A/S with daemon
authority
Must be a controlled program
Define programs to Program Control
z/OS daemons reside in the HFS and are controlled
User defined daemons
Specific daemon program names or *
RDEFINE PROGRAM * UACC(READ) ADDMEM +
('SYS1.LINKLIB'/'******'/NOPADCHK +
'CEE.SCEERUN'/RLTPAK/NOPADCHK +
'SYS1.SEZALOAD'//NOPADCHK )
SETROPTS WHEN(PROGRAM) REFRESH

286
ABCs of z/OS System Programming: Volume 9
Program access to data sets
Program access to data sets (PADS) allows an authorized user or group of users to access
specified data sets with the user's authority to execute a certain program. That is, some users
can access specified data sets at a specified access level only while executing a certain
program (and the program access is restricted to controlled programs).
To set up program access to data sets, create a conditional access list for the data set profile
protecting the data sets. To do this, specify
WHEN(PROGRAM(program-name))
with the
ID
and
ACCESS
operands on the
PERMIT
command. Specifying the
WHEN(PROGRAM)
operand requires
that the user or group specified must be running the specified program to receive the
specified access.
PADCHK and NOPADCHK operands
Choosing between the
PADCHK
and
NOPADCHK
operands: With the
ADDMEM
operand of the
RDEFINE
and
RALTER
commands, you can also specify
PADCHK
or
NOPADCHK
as follows:
NOPADCHK NOPADCHK
means that RACF does not perform the program-accessed data
checks for the program. The program is loaded and has access to any
currently opened program-accessed data sets, even though the user
ID/program combination is not in the conditional access list.
NOPADCHK
allows
an installation to define entire libraries of modules (such as the PL/I transient
routines or ISPF) as controlled programs without having to give each of these
modules explicit access to many program-accessed data sets. Use
NOPADCHK

if you trust the programs to access only data they should.
PADCHK PADCHK
(the default) means that RACF checks for program-accessed data
sets that are already open before executing the program. If there are any
open program-accessed data sets, RACF ensures, before it allows this
program to be loaded, that this user ID/program combination is in the
conditional access list of each data set.

Chapter 6. Security customization
287
6.78 z/OS UNIX-level security for daemons
Figure 6-78 z/OS UNIX security with daemons
Example using the cron daemon
cron is a clock daemon that runs commands at specified dates and times.
Figure 6-78 shows the cron daemon running a shell script for the user ID BOB (UID=25). The
script will copy HFS files to an MVS data set. Before cron can run the script, it will fork a new
process and set the identity of this process to UID=25 and the MVS identity to BOB. This will
ensure that the script can be run successfully with BOB's shell environment and BOB's
access to his MVS data sets. When the job is done, the cron child process will end, and cron
will not have any access to BOB's MVS data sets.
To obtain a higher level of security in a z/OS system with daemons, the RACF FACILITY class
called BPX.DAEMON can be used to control the use of the
setuid/seteuid
functions. Only
the superusers permitted to the BPX.DAEMON class will be allowed to use the
setuid/seteuid
functions. In addition, there is a program control requirement.
When
setuid()
SYSCALL is issued, the caller (daemon) program, and all other programs
currently loaded in the address space, must have been loaded from a z/OS data set with the
RACF Program Control activated, meaning they must be controlled programs. As it is the
cloned child daemon program that issues the request, it will inherit the contents of its address
space from the parent daemon via fork.
This solution enables an installation to have some superusers which have authority to
perform system maintenance (for example, to manage the hierarchical file system), while
other special superusers (daemon user IDs) are allowed to change the identity of a process.
HFS File
BOB
UID=25
cron
OMVSCRON
UID=0
setuid(25)
exec cp1
cp1
(copy files)
Child Address
Space
Superuser?
Y
N
Defined to
BPX.DAEMON
Program
Control?
Y
Y
setuid
fails!
N
N
OMVSCRON
OMVSKERN
BPX.DAEMON
........
fork() from
cron daemon
ROGERS @ SC43:/etc>
ls -E /usr/sbin/cron

-
rwxr--r-- -p- /usr/sbin/cron
R
OGERS @ SC43:/etc>
MVS
Data Set

288

ABCs of z/OS System Programming: Volume 9
6.79 Start options for daemons
Figure 6-79 Start options for daemons
Start options for daemons
In a z/OS system, there are several ways of starting and restarting daemons. The method
used depends on the level of control the installation has chosen for daemons. The daemon
programs are installed in /usr/sbin. Daemons can be started using the following methods:

To be started automatically when kernel is started, place the start options in the HFS file
called /etc/rc. The initialization of z/OS UNIX includes running the commands in /etc/rc.
The _BPX_JOBNAME environment variable assigns a job name to the daemon.

As a cataloged procedure using the BPXBATCH program to invoke the daemon program.
If daemons need to be stopped, the
kill
command is typically used. Some daemons may
have their own specific method of shutdown.
You should have appropriate procedures and directions in place to restart these daemons in
case of failure. Started procedures are one way to do this; other methods may be more
attractive depending on your automation strategy.
_BPX_JOBNAME='INETD' /usr/sbin/inetd /etc/inetd.conf &
//INETD PROC
//INETD EXEC PGM=BPXBATCH,REGION=30M,TIME=NOLIMIT,
// PARM='PGM /usr/sbin/inetd /etc/inetd.conf'
//* STDIN and STDOUT are both defaulted to /dev/null
//STDERR DD PATH='/etc/log',PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
MVS
Started
Task
/etc/rc
or
any shell script
Can use INITTAB

Chapter 6. Security customization
289
6.80 Define daemon security
Figure 6-80 Defining daemon security
Defining daemon security
The following steps describe how to define security for a daemon:
1.Define a user ID for the daemon which is a superuser with UID=0, for example
OMVSCRON:
ADDUSER OMVSCRON DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
2.Define the BPX.DAEMON FACILITY class in RACF:
RDEFINE FACILITY BPX.DAEMON UACC(NONE)
Activate the class if this is the first RACF FACILITY class:
SETROPTS CLASSACT(FACILITY) GENERIC(FACILITY) AUDIT(FACILITY)
SETROPTS RACLIST(FACILITY)
3.Permit the daemon user ID to the BPX.DAEMON class:
PERMIT BPX.DAEMON CLASS(FACILITY) ID(OMVSCRON) ACCESS(READ)
4.Protect the program libraries that need to be protected from unauthorized updates. The
ADDSD command creates data set profiles for the data sets. You should protect against
unauthorized updates so that nobody can replace a daemon program with a fake daemon
program. If these profiles are already defined, this step can be skipped.
ADDSD 'SYS1.LINKLIB' UACC(READ)
ADDSD 'SYS1.SCEERUN' UACC(READ)
ADDSD 'SYS1.SEZALOAD' UACC(READ)
1.Define daemon user ID as superuser
2.Define BPX.DAEMON in the facility class
3.Permit daemon user ID to BPX.DAEMON class
4.Protect program libraries
5.Activate RACF program control
ADDUSER OMVSCRON DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))
RDEFINE FACILITY BPX.DAEMON UACC(NONE)
PERMIT BPX.DAEMON CLASS(FACILITY) ID(OMVSCRON) ACCESS(READ)
SETROPTS WHEN(PROGRAM) REFRESH
SETROPTS FACILITY(RACLIST) REFRESH
RDEFINE PROGRAM * ADDMEM('SYS1.LINKLIB'//NOPADCHK) UACC(READ)

290

ABCs of z/OS System Programming: Volume 9
Mark the data sets as controlled libraries:
RDEFINE PROGRAM * ADDMEM('SYS1.LINKLIB'//NOPADCHK +
'SYS1.SCEERUN'//NOPADCHK +
'SYS1.SEZALOAD'//NOPADCHK +
Or, mark the daemon program as controlled instead of the whole library:
RDEFINE PROGRAM CRON ADDMEM('SYS1.LINKLIB'//NOPADCHK)
UACC(READ) AUDIT(ALL)
5.Activate RACF program control:
Place the PROGRAM profile in storage:
SETROPTS WHEN(PROGRAM) REFRESH
Starting daemon programs
In many cases, a daemon program is started from the kernel and will inherit the kernel user
ID, OMVSKERN. This example shows that it can have a separate user ID as long as the user
ID is defined as a superuser. This superuser must be defined with a UID=0 in RACF, which
means that this user cannot become a superuser by using the
su
command.
The name BPX.DAEMON must be used. No substitutions for this name are allowed.
UACC(NONE) is recommended. If this is the first RACF FACILITY class defined in RACF, the
SETROPTS command must be used to activate the class.
You can choose to protect a whole program library or individual load modules (members) in a
library. The daemon program must reside in a program-controlled MVS partitioned data set,
or in an HFS file with the extended attribute turned on via the
extattr +p
command. Both the
program library for the daemons (for example, SYS1.LINKLIB) and the C run-time library
must be protected.
An installation has a choice of either protecting all programs in a program library or individual
programs. To protect all members in a data set, specify PROGRAM *.
When specifying program control for a program, you can choose to specify
UACC(READ)
or
UACC(NONE)
.
UACC(READ)
should be sufficient to protect the daemon program.
Note:
This user ID should not have a TSO/E segment defined; only the OMVS segment is
needed.
Note:
Libraries in the LNKLIST concatenation are opened during IPL, and the programs in
them are available to anyone unless the program name is defined as a controlled program.

Chapter 6. Security customization
291
6.81 Auditing options for z/OS UNIX
Figure 6-81 Auditing options for z/OS UNIX
z/OS UNIX auditing options
Every file and directory has security information, which consists of:

File access permissions

UID and GID of the file

Audit options that the file owner can control

Audit options that the security auditor can control
The security auditor uses reports formatted from RACF system management facilities (SMF)
records to check successful and failing accesses to z/OS UNIX resources. An SMF record
can be written at each point where the system makes security decisions.
Six classes are used to control auditing of z/OS UNIX security events. These classes have no
profiles. They do not have to be active to control auditing.
The security administrator or the file owners can also specify auditing at the file level in the file
system.
RACF provides utilities for unloading SMF data (IRRADU00) and data from the RACF
database (IRRDBU00), which can be used as input in audit reports.
Users
RACF
HFS
z/OS UNIX
User
Audit reports
Files and directories:
Audit options file owner can control
Audit options security auditor can control
(FSP)
SMF
records

292

ABCs of z/OS System Programming: Volume 9
6.82 File-based auditing
Figure 6-82 Auditing command for file access and the FSP
File-based auditing options
Auditing for file access is specified in the file security packet (FSP) with the
chaudit

command. Only a file owner or a security auditor can specify if auditing is turned on or off,
and when audit records should be written for a directory or a file. There are two separate sets
of auditing flags:

Auditing set by the file owner (and superuser)

Auditing set by the RACF AUDITOR
Audit records are written based on the combined owner and auditor settings. Auditing is set
for read, write, and execute (search for directories) for the following kinds of accesses:

Successful accesses

Failures, that is, access violations

All, which is both successes and failures

None
Assigning audit options
When a file or a directory is created, default audit options are assigned. Different defaults are
set for users and auditors. The same audit option is used no matter what kind of access is
attempted (read, write, or execute). If auditing is not specified for a file, the defaults are:

For owner auditing - audit failed accesses
File Permission Bits
File Mode
Superuser
Owner or
Superuser
Owner or
Superuser
Auditor
chaudit
chmod
chown
extattr
(Special)
(FSP)
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w
x
r
w
x
r
w
x
Owner Group Other
extattr
File
Owner

RACF
Auditor
ACLs

Chapter 6. Security customization
293

For RACF AUDITOR auditing - no auditing
When a file is created, these are the default audit options:

User audit options: for all access types, audit_access_failed

Auditor audit options: for all access types, don't_audit
Changing audit options
To change the audit options, you must use
chaudit
, a z/OS UNIX shell command, or the
ISHELL menus. There are restrictions on who can change these options.

For user audit options, you must be the owner of the file.

For auditor audit options, you must have the RACF AUDITOR attribute. You can then
change the auditor audit options for any file in the file system.
The default file-level audit options control the auditing of directory and file accesses. These
defaults will only be used for a particular class (DIRSRCH, DIRACC, or FSOBJ) if
SETROPTS LOGOPTIONS(DEFAULT(class)) has been issued for that class.
The syntax of the
chaudit
command is similar to the syntax of the
chmod
command, which
you use to set the security of the file. Use r,w,x to specify whether you want to audit reads,
writes, and/or execute accesses.

294

ABCs of z/OS System Programming: Volume 9
6.83 Audit z/OS UNIX events
Figure 6-83 RACF classes used for auditing
RACF classes for auditing
RACF provides the following classes for auditing z/OS UNIX events:
DIRSRCH
Controls auditing of directory searches.
DIRACC
Controls auditing of access checks for read/write access to directories.
FSOBJ
Controls auditing of all access checks for file system objects except directory
searches via SETROPTS LOGOPTIONS and controls auditing of creation
and deletion of file system objects via SETROPTS AUDIT.
FSSEC
Controls auditing of changes to the security data (FSP) for file system
objects.
PROCESS
Controls auditing of changes to the UIDs and GIDs of processes and
changing of the thread limit via the SETROPTS LOGOPTIONS, and controls
auditing of dubbing, undubbing, and server registration of processes via
SETROPTS AUDIT.
PROCAT
Controls auditing of functions that look at data from or affect other processes.
IPCOBJ
Specifies auditing options for IPC accesses and access checks for objects
and changes to UIDs, GIDs, and modes. For access control and for z/OS
UNIX user identifier (UID), z/OS UNIX group identifier (GID), and mode
changes, use SETROPTS LOGOPTIONS. For object create and delete, use
SETROPTS AUDIT.
SETROPTS
LOGOPTIONS
or
SETROPTS
AUDIT
Controlled by:
RACF classes for auditing:
DIRSRCH
DIRACC
FSOBJ
FSSEC
PROCESS
PROCACT
Directory accesses
Directory searches
All file and directory
accesses
Change of FSP
Change of process
UID/GID
Functions that look at
data from other processes
IPCOBJ
Specifies auditing options for
IPC accesses
SETROPTS LOGOPTIONS(FAILURES(DIRSRCH,DIRACC))
SETROPTS AUDIT(FSOBJ,PROCESS,IPCOBJ)

Chapter 6. Security customization
295
Controlling auditing with commands
Auditing can be controlled by using the commands SETROPTS LOGOPTIONS, and
SETROPTS AUDIT, as follows:

SETROPTS LOGOPTIONS(auditing_level(class_name)) audits access attempts to the
resources in the specified class according to the auditing level specified and can be used
for all classes.

SETROPTS AUDIT(class_name) specifies the names of the classes that RACF should
audit. The AUDIT option can be used for the classes FSOBJ, IPCOBJ, and PROCESS.

SETROPTS LOGOPTIONS(DEFAULT) indicates you want no class auditing and only
file-level auditing (use
chaudit
to specify).
Audit records are always written when:

A user who is not defined as a z/OS UNIX user tries to dub a process.

A user who is not a superuser tries to mount or unmount a file system.

A user tries to change a home directory.

A user tries to remove a file, hard link, or directory.

A user tries to rename a file, hard link, symbolic link, or directory.

A user creates a hard link.
The auditing levels for LOGOPTIONS are:
ALWAYS
All access attempts to resources protected by the class are audited.
NEVER
No access attempts to resources protected by the class are audited (all
auditing is suppressed).
SUCCESSES
All successful access attempts to resources protected by the class are
audited.
FAILURES
All failed access attempts to resources protected by the class are audited.
DEFAULT
Auditing is controlled by the auditing bits in the FSP for z/OS UNIX files and
directories.
Note:
There is no option to turn off these audit records.

296

ABCs of z/OS System Programming: Volume 9
6.84 Chaudit command
Figure 6-84 chaudit command to set auditing options
Chaudit command
The
chaudit
command changes the audit attributes of the specified files or directories. Audit
attributes determine whether or not accesses to a file are audited by the system authorization
facility (SAF) interface.
Command examples
The top part of Figure 6-84 shows examples of the
chaudit
command usage by the file owner
(or superuser). The default audit settings are shown in the upper right corner of the figure,
then the command is applied as follows:
chaudit w+s prog1
adds (
+
) auditing for successful accesses (
s
) for write accesses (
w
).
chaudit rwx=sf prog1
specifies that all (
a
) accesses, that is both successes (
s
) and
failures (
f
), are to be audited for reads, writes, and executes.
chaudit r-s,x-sf prog1
says to stop (
-
) auditing successes (
s
) for read (
r
), and stop (
-
)
auditing both successes (
s
) and failures (
f
) for execute (
x
) access. The same effect can be
achieved with the command
chaudit r=f,x= prog1
.
Note:

chaudit
can be used only by the file owner or a superuser for non-auditor-requested
audit attributes. It takes a user with auditor authority to change the auditor-requested audit
attributes.
f f f - - -
- - -
- - -
- - -
- - -
f f f
f f f
f f f
f f f
f a f
a a a
f a -
f a f
- a -
f f f
chaudit w+s prog1
chaudit rwx=sf prog1
chaudit r-s,x-sf prog1
default
default
RACF auditor auditing:
chaudit -a r-f,x-f prog1
chaudit -a rwx=f prog1
chaudit -a r+f,w+sf,x+f prog1
Files owner auditing:

Chapter 6. Security customization
297
Command examples
Examples of the
chaudit
command usage by the RACF Auditor are shown in the lower part of
Figure 6-84. The default audit settings shown first, then the command is applied as follows:
chaudit -a r+f,w+s,x+f prog1
adds auditing of successes (
s
) and failures (
f
) for write
access, and specifies to write an audit record whenever an access failure (
f
) occurs for
read or execute accesses.
chaudit -a r-f,x-f prog1
turns off (
-
) auditing for failures (
f
) for read and execute
accesses.
chaudit -a rwx=f prog1
turns on auditing for unsuccessful (
f
) read, write, and execute
accesses.
Note that the auditor includes the option
-a
when issuing the
chaudit
command, and that the
auditor can only set the audit flags in the auditor's section of the FSP.
The audit condition part of a symbolic mode is any combination of the following:
s
Audit on successful access if the audit attribute is on.
f
Audit on failed access if the audit attribute is on.
The following command changes the file prog1 so that all successful and unsuccessful file
accesses are audited:
chaudit rwx=sf prog1

298

ABCs of z/OS System Programming: Volume 9
6.85 List audit information for files
Figure 6-85 Listing auditing options for specified files
Command to list audit information for files and directories
The
ls
command with the
-W
option is used to display the auditing that is in effect for a file. In
this example, since we have done the
ls
for a directory, all the files in the directory are
displayed.
The auditing options are displayed to the right of the file permissions. The left three
characters are for owner-set auditing, and the right three characters are for auditor-set
auditing.
There are four possible characters for each of these columns:

No auditing (
-
)

Successful accesses (
s
)

Access failures (
f
)

All accesses (
a
)
File
auditing
ROGERS @ SC65:/u/rogers>ls -W /usr/man/C
total 136
drwxr-xr-x fff--- 2 HAIMO OMVSGRP 8192 May 29 2002 IBM
drwxr-xr-x fff--- 3 HAIMO OMVSGRP 8192 Jun 10 2002 cat1
drwxrwxr-x fff--- 3 HAIMO OMVSGRP 8192 May 29 2002 cat8
drwxr-xr-x fff--- 3 HAIMO OMVSGRP 8192 May 29 2002 man1
-rw-rw-r-- fff--- 2 HAIMO OMVSGRP 33887 May 29 2002 whatis

Chapter 6. Security customization
299
6.86 Auditing reports
Figure 6-86 Creating auditing reports
Audit reports
In a z/OS UNIX environment which uses RACF as its access control program, the security
auditor has two main tasks to perform:

Verify that the RACF profiles have the proper contents (OMVS segments in the user and
group profiles, and logging options in particular).

Use the security logs to follow up on detected violations, and to detect abnormal behavior
by authorized users.
The audit information can be quite extensive and is found in the RACF database, the RACF
security log, and in SMF records. RACF provides two utilities for unloading security data and
placing the output in a sequential data set:

The RACF database unload utility, IRRDBU00 can be used to unload a user's OMVS
segment.

The RACF SMF data unload utility, IRRADU00 can be used to unload the relevant audit
records.
The output from these utilities can be used in several ways: viewed directly, used as input for
installation-written programs, and manipulated with sort/merge utilities. It can also be
uploaded to a database manager (for example, DB2) to process complex inquiries and create
installation-tailored reports. SYS1.SAMPLIB contains examples of how to create DB2 tables,
and load RACF data produced from the RACF unload utilities, into the DB2 tables. It also has
database query examples.
RACF SMF data
unload utility
RACF data base
unload utility
SMF
records
DB2 tables
Direct viewing
Tivoli Decision
Support (TDS)
User
applications
A
u
d
i
t

r
e
p
o
r
t
s
RACF
data base
Sequential
data set

300

ABCs of z/OS System Programming: Volume 9
6.87 Maintain z/OS UNIX-level security
Figure 6-87 Checking products for z/OS UNIX-level security
Checking programs for security
To maintain the security available from the system, take these steps:

Check any purchased program to make sure that it will not lower the system security level.
If you cannot be sure of a program, do not put it on the system.

Determine the auditing requirements for the installation. Control auditing data with the
RACF SETROPTS command and the
chaudit
shell command.

Set up rules for:
– Sharing data in files
– Specifying permission bits when creating files or using the
chmod
shell command or
chmod()
function

Protect all HFS data sets with a RACF profile that specifies
UACC(NONE)
. Only
administrators with responsibility for creating, restoring, or dumping HFS data sets should
be permitted to this profile.
To maintain security, require z/OS UNIX users to set the permission bits for their own files to
deny access to any user but the file owner.
Each user is responsible for protecting their own data. However, data that other users need to
access must have the appropriate permission bits set for group or other.
Check purchased applications
Determine auditing requirements for installation
Set up rules for:
Sharing data in files
Specifying permission bits
Protect all HFS data sets with UACC(NONE)

Chapter 6. Security customization
301
6.88 Setting up z/OS UNIX (1)
Figure 6-88 Tasks needed to set up z/OS UNIX
Setting up security check list
There is no predefined numbering scheme for z/OS UNIX GIDs. Therefore, you must decide
what is suitable for your system when allocating GIDs.
Once a scheme has been chosen, you need to set up some groups. It is recommended that
you set up at least two new groups: one for z/OS UNIX and another for TTY. The
recommended group name for z/OS UNIX is OMVSGRP, but this can be changed to
something else if it is not suitable on your system. The other group, TTY is recommended to
be called that name—otherwise changes will be required in BPXPRMxx to support the
different name.
You will need to add OMVS segments to some existing groups. For example, you (as the
person doing the OMVS configuration work) will need a group OMVS segment (GID). Then
you need to consider who else will need to use z/OS UNIX and ensure that they, too, have
OMVS segments.
Some software detects that z/OS UNIX is active, and if so will want to use it. Two examples
are TCP/IP and RMFGAT.
Determine GID numbering strategy
Define new groups
TTY
OMVSGRP
Add OMVS segments to existing groups
You
Any potential z/OS UNIX users

302

ABCs of z/OS System Programming: Volume 9
6.89 Setting up z/OS UNIX (2)
Figure 6-89 Tasks needed to set up z/OS UNIX
Setting up security check list
There is no predefined numbering scheme for z/OS UNIX UIDs other than UID=0 means
Superuser. Therefore, you must decide what is suitable for your system when allocating UIDs.
Once a scheme has been chosen, you need to set up some user IDs. It is recommended that
you set up at least two new user IDs: OMVSKERN and BPXROOT. The OMVSKERN user ID
is used for the OMVS and BPXOINIT address spaces. The BPXROOT user ID is used when a
daemon sets UID=0, but the user ID is not known. These recommended user ID names can
be changed to something else if they are not suitable on your system.
You will need to add OMVS segments to some existing user IDs. For example, you (as the
person doing the OMVS configuration work) will need a user ID OMVS segment
(UID/HOME/PROGRAM). Then you need to consider who else will need to use z/OS UNIX
and ensure that they, too, have OMVS segments.
Some software detects that z/OS UNIX is active, and if so will want to use it. Two examples
are TCP/IP and RMFGAT.
Determine UID numbering strategy
Define new users
OMVSKERN
BPXROOT
Add OMVS segments to existing users
You
Any potential z/OS UNIX users

Chapter 6. Security customization
303
6.90 Setting up z/OS UNIX (3)
Figure 6-90 Tasks needed to set up z/OS UNIX
Setting up security check list
To activate z/OS UNIX, z/OS UNIX itself needs to have some identification (user ID/group)
assigned to it. This is done either by the RACF started procedures table (ICHRIN03) or the
STARTED class profiles.
Both the OMVS and BPXOINIT cataloged (or started) procedures (or started tasks - STCs)
need to be defined. Only the OMVS procedure should be defined with the
TRUSTED
attribute.
When programs issue fork or spawn, the BPXAS PROC found in SYS1.PROCLIB is used to
provide a new address space. For a fork, the system copies one process, called the parent
process, into a new process, called the child process. Then it places the child process in a
new address space. The forked address space is provided by workload manager (WLM),
which uses the BPXAS PROC to create the address spaces.
zFS runs as a z/OS UNIX colony address space. There must be an entry in a BPXPRMxx
parmlib member for ZFS and the ZFS procedure (PROC) must be available. zFS is started by
z/OS UNIX based on the FILESYSTYPE statement for ZFS in the BPXPRMxx parmlib
member.
Define cataloged procedure (STC) controls
OMVS
BPXOINIT
BPXAS
ZFS

304

ABCs of z/OS System Programming: Volume 9
6.91 Setting up z/OS UNIX (4)
Figure 6-91 Tasks needed to set up z/OS UNIX
Setting up a security check list
All programs loaded into an address space that requires daemon authority need to be marked
as controlled (for example, user programs that are loaded and any run-time library modules
that are loaded). All modules loaded from LPA are considered to be controlled. The
BPX.DAEMON requires z/OS UNIX load libraries to be program-controlled. The data sets
listed in Figure 6-91 are the main ones required to be program-controlled when setting up
z/OS UNIX. These data sets are:

LINKLIB - z/OS (including z/OS UNIX)

SCEERUN - Language Environment

SEZALOAD - TCP/IP
Daemons shipped by z/OS reside in the HFS and are marked program-controlled, so you do
not need to define them. For example, suppose you have a daemon named server1. The file
/bin/server1 would have the sticky bit on. Member SERVER1 would reside in SYS1.LINKLIB
and be defined as program-controlled:
RDEFINE PROGRAM SERVER1 ADDMEM('SYS1.LINKLIB'/'******'/NOPADCHK) + UACC(READ)
SETROPTS WHEN(PROGRAM) REFRESH
Note:
'******' (six asterisks surrounded by single quotes) specifies the current SYSRES
volume.
Any program loaded into an A/S with daemon
authority
Must be a controlled program
Define programs to Program Control
z/OS daemons reside in the HFS and are controlled
User defined daemons
Specific daemon program names or *
RDEFINE PROGRAM * UACC(READ) ADDMEM +
('SYS1.LINKLIB'/'******'/NOPADCHK +
'CEE.SCEERUN'/RLTPAK/NOPADCHK +
'SYS1.SEZALOAD'//NOPADCHK)
SETROPTS WHEN(PROGRAM) REFRESH

Chapter 6. Security customization
305
6.92 Setting up z/OS UNIX (5)
Figure 6-92 Tasks needed to set up z/OS UNIX
Setting up security check list
Of the BPX.* FACILITY class profiles, it is strongly recommended that at least BPX.DAEMON
and BPX.SUPERUSER be implemented. BPX.DAEMON restricts access to the following
services:

seteuid (BPX1SEU service)

setuid (BPX1SUI service)

setreuid (BPX1SRU service)

spawn (BPX1SPN service with a change in user ID requested.

pthread_security_np()

auth_check_resource_np()

_login()

_password()
BPX.SUPERUSER allows users with access to the BPX.SUPERUSER FACILITY class profile
to switch to superuser authority (effective UID of 0).
You can define profiles in the UNIXPRIV class to grant RACF authorization for certain z/OS
UNIX privileges. These privileges are automatically granted to all users with z/OS UNIX
superuser authority. By defining profiles in the UNIXPRIV class, you can specifically grant
certain superuser privileges with a high degree of granularity to users who do not have
superuser authority. This allows you to minimize the number of assignments of superuser
authority at your installation and reduces your security risk.
Define BPX.DAEMON
Define BPX.SUPERUSER or UNIXPRIV (R8)
Define other BPX.* profiles if required

306

ABCs of z/OS System Programming: Volume 9
6.93 RACF definitions for zFS
Figure 6-93 RACF definitions for zFS
zFS RACF definitions
To define DFS to RACF you must create the following definitions with these exact names.
Even if you use none of the functions of DFS, you can use the following DFS definitions for
zFS:

Define DFSGRP as a group.

Define DFS as a user.

Define ZFS as a started task.
For RACF, use the following commands:
ADDGROUP DFSGRP SUPGROUP(SYS1) OMVS(GID(2))
ADDUSER DFS OMVS(HOME(/opt/dfslocal/home/dfscntl) UID(0))
DFLTGRP(DFSGRP) AUTHORITY(CREATE) UACC(NONE)
RDEFINE STARTED ZFS.** STDATA(USER(DFS) GROUP(DFSGRP) TRUSTED(YES))
SETROPTS RACLIST(STARTED) REFRESH
Note:
A user ID other than DFS can be used to run the ZFS started task if it is defined with
the same RACF characteristics as shown for the DFS user ID.
RACF definitions required for Distributed File Service
SMB and DFS support
Not required to use zFS
Additional definitions for zFS
RDEFINE STARTED ZFS.** STDATA(USER(DFS))
SETROPTS RACLIST(STARTED) REFRESH
ADDGROUP DFSGRP SUPGROUP(SYS1) OMVS(GID(2))
ADDUSER DFS OMVS(HOME(/opt/dfslocal/home/dfscntl)
UID(0))
DFLTGRP(DFSGRP) AUTHORITY(CREATE) UACC(NONE)
RDEFINE STARTED DFS.** STDATA(USER(DFS))
RDEFINE STARTED DFSCM.** STDATA(USER(DFS))
RDEFINE STARTED ZFS.** STDATA(USER(DFS)GROUP(DFSGRP
TRUSTED(YES))
SETROPTS RACLIST(STARTED)
SETROPTS RACLIST(STARTED) REFRESH

Chapter 6. Security customization
307
6.94 UNIXPRIV class with z/OS V1R3 and zFS
Figure 6-94 UNIXPRIV class changes for zFS
Authorization for administrators for zFS commands
zFS with z/OS V1R3 supports the SUPERUSER.FILESYS.PFSCTL profile of the UNIXPRIV
class. This makes it possible for a zFS administrator to have just READ authority to this
UNIXPRIV profile resource, SUPERUSER.FILESYS.PFSCTL, rather than requiring a UID of
0 for
zfsadm
commands that modify zFS file systems or aggregates. The same is true for the
other zFS commands and utilities, so zFS administrators do not need a UID of 0.
To allow the zFS administrator to mount and unmount file systems, permit update access to
another profile, SUPERUSER.FILESYS.MOUNT, in class UNIXPRIV.
UNIXPRIV authorization is invoked by creating the needed resources in the UNIXPRIV class
and then giving users READ authority to it, as follows:
Note:
UPDATE access is needed if the user needs to
mount
,
chmount
, or
unmount
file sys-
tems with the
setuid
option; otherwise, READ access is sufficient.
SETROPTS CLASSACT(UNIXPRIV)
SETROPTS RACLIST(UNIXPRIV)
RDEFINE UNIXPRIV SUPERUSER.FILESYS.PFSCTL UACC(NONE)
PERMIT SUPERUSER.FILESYS.PFSCTL CLASS(UNIXPRIV) ID(ROGERS) ACCESS(READ)
RDEFINE UNIXPRIV SUPERUSER.FILESYS.MOUNT UACC(NONE)
PERMIT SUPERUSER.FILESYS.MOUNT CLASS(UNIXPRIV) ID(ROGERS) ACCESS(UPDATE)
SETROPTS RACLIST(UNIXPRIV) REFRESH
Some zfsadm commands require superuser authority
This is true also for other zFS commands and utilities
zFS with z/OS V1R3 supports:
SUPERUSER.FILESYS.PFSCTL profile - UNIXPRIV
Allows a zFS administrator to have just READ
authority to this UNIXPRIV profile resource
Commands that modify zFS file systems or aggregates
uid 0 not required with this access
RDEFINE UNIXPRIV SUPERUSER.FILESYS.PFSCTL UACC(NONE)
PERMIT SUPERUSER.FILESYS.PFSCTL CLASS(UNIXPRIV) ID(ROGERS) ACCESS(READ)
RDEFINE UNIXPRIV SUPERUSER.FILESYS.MOUNT UACC(NONE)
PERMIT SUPERUSER.FILESYS.MOUNT CLASS(UNIXPRIV) ID(ROGERS) ACCESS(UPDATE)

308

ABCs of z/OS System Programming: Volume 9
6.95 List current user IDs with the ISHELL
Figure 6-95 List the currently defined z/OS UNIX users
List z/OS UNIX users
A system programmer can use the ISPF shell to perform tasks such as listing the current
users defined in the OMVS segment. This requires superuser authority.
You can use the ISHELL to do the following:

List files in a directory

Create, delete, or rename directories, files, and special files

Browse files

Edit files

Copy files

Display file attributes

Search files for text strings

Compare files or directories

Run executable files

Display the attributes and contents of a symbolic link (symlink)

Mount and unmount a hierarchical file system (HFS)

Create a hierarchical file system (HFS)

Set up character special files

Set up standard directories for a root file system

Set up existing users and groups for z/OS UNIX System Services access
----------------------------------------------------------------------------
User List Row 622 to 645 of 927
Command ===> ____________________________________________________________

User ID UID Group Home Directory Initial Program
PUBLIC 998 SYS1 / /bin/sh
PUBUSER -1 ________ ____________________ ____________________
RACF -1 ________ ____________________ ____________________
RACHEL -1 ________ ____________________ ____________________
RALPHB 477 SYS1 /u/ralphb /bin/sh
RALPHR -1 ________ ____________________ ____________________
RAMA 87674 SYS1 / /bin/sh
RANIERI 0 SYS1 / /bin/sh
RAYNO -1 ________ ____________________ ____________________
RBORGES -1 ________ ____________________ ____________________
RCHIANG -1 ________ ____________________ ____________________
RCONWAY 0 SYS1 /etc /bin/sh
RC63 0 SYS1 /u/rc63 /bin/sh
RC64 0 SYS1 / /bin/sh
RC65 0 SYS1 / /bin/sh
REYO 10052 SYS1 / /bin/sh
ISHELL - Setup - (2). User list

Chapter 6. Security customization
309
6.96 The BPXBATCH utility
Figure 6-96 Using the BPXBATCH utility
The BPXBATCH utility
BPXBATCH is an MVS utility that you can use to run shell commands or shell scripts and to
run executable files through the MVS batch environment. You can invoke BPXBATCH as
follows:

In JCL - Use one of the following:
EXEC PGM=BPXBATCH,PARM='SH program-name'
EXEC PGM=BPXBATCH,PARM='PGM program-name'

From the TSO/E READY prompt

From TSO CLISTs and REXX execs - Use one of the following:
BPXBATCH SH program-name
BPXBATCH PGM program-name

From a program
BPXBATCH has logic to detect when it is run from JCL. If the BPXBATCH program is running
as the only program on the job step task level, it sets up stdin, stdout, and stderr and execs
the requested program. If BPXBATCH is not running as the only program at the job step task
level, the requested program will run as the second step of a JES batch address space from
JCL in batch. If run from any other environment, the requested program will run in a WLM
initiator in the OMVS subsys category.
BPXBATCH is an MVS utility that you can use to
run shell commands or shell scripts
Can run executable files through the MVS batch
environment
Invoke BPXBATCH as follows:
In JCL
From the TSO/E READY prompt
From TSO CLISTs and REXX execs
From a program

310

ABCs of z/OS System Programming: Volume 9
6.97 The BPXBATCH job
Figure 6-97 Sample JCL for a BPXBATCH job
Using BPXBATCH
When you are using BPXBATCH to run a program, you typically pass the program a file that
sets the environment variables. If you do not pass an environment variable file when running
a program with BPXBATCH or if the HOME and LOGNAME variables are not set in the
environment variable file, those two variables are set from your logon RACF profile.
LOGNAME is set to the user name and HOME is set to the initial working directory from the
RACF profile.
With BPXBATCH, you can allocate the MVS standard files stdin, stdout, and stderr as HFS
files for passing input. If you do allocate these files, they must be HFS files. You can also
allocate MVS data sets or HFS text files containing environment variables (stdenv). If you do
not allocate them, stdin, stdout, stderr, and stdenv default to /dev/null. Allocate the standard
files using the data definition PATH keyword options, or standard data definition options for
MVS data sets.
The BPXBATCH default for stderr is the same file defined for stdout. For example, if you
define stdout to be /tmp/output1 and do not define stderr, then both printf() and perror() output
is directed to /tmp/output1.
For BPXBATCH, you can define stdin, stdout, and stderr using one of the following:

The TSO/E ALLOCATE command, using the ddnames STDIN, STDOUT, and STDERR

A JCL DD statement with the PATH operand, using the ddnames STDIN, STDOUT, and
STDERR
//OMVSPGM JOB USER=userid
//OMVSEXEC EXEC
PGM=BPXBATCH
,PARM='pgm /cprog a1 a2'
//STDOUT DD PATH='/dir1/dir2/std.output',
// PATHOPTS=(OWRONLY,OCREATE),
// PATHMODE=(SIRWXV),
// PATHDISP=KEEP
//STDERR DD PATH='/dir1/dir2/std.error',
// PATHOPTS=(OWRONLY,OCREATE),
// PATHMODE=(SIRWXV),
// PATHDISP=KEEP
/*


Chapter 6. Security customization
311

Redirection, which, in a shell, is a method of associating files with the input or output of
commands.
STDIN and STDOUT
STDIN is an input stream from which data is retrieved. Standard input is normally associated
with the keyboard, but if redirection or piping is used, the standard input can be a file or the
output from a command.
STDOUT is the output stream to which data is directed. Standard output is normally
associated with the console, but if redirection or piping is used, the standard output can be a
file or the input to a command. See also standard error.

312

ABCs of z/OS System Programming: Volume 9
6.98 BPXBATCH and shell commands

Figure 6-98 Using shell commands in BPXBATCH JCL
The BPXBATCH utility
BPXBATCH makes it easy for you to run shell scripts, REXX execs, and executable files that
reside in hierarchical file system (HFS) files through the MVS job control language (JCL). If
you do most of your work from TSO/E, using BPXBATCH saves you the trouble of going into
the shell to run your scripts and executable files. The format of BPXBATCH for JCL and
TSO/E is as follows:
The format of BPXBATCH for JCL and TSO/E is as follows:
JCL:
EXEC PGM=BPXBATCH,PARM='SH | PGM program_name'
TSO/E:
BPXBATCH SH | PGM program_name
In addition, BPXBATCH can be used in a REXX exec to call a shell script as shown in the
following example:
"BPXBATCH SH "shellcmd

IF RC ^= 0 Then
DO
Say ' OSHELL RC = ' RC
You can allocate STDIN, STDOUT, and STDERR as files, using the PATH operand, and
redirect the messages to HFS files.
//GGIBPXBA JOB (55,500,,999),'MVS ',CLASS=A,
// MSGCLASS=R,REGION=0K,NOTIFY=&SYSUID
//EXECBPX EXEC PGM=BPXBATCH,REGION=8M,
// PARM='SH ls /usr/lib'
//*STDIN DD PATH='/stdin-file-pathname',
//* PATHOPTS=(ORDONLY)
//STDOUT DD PATH='/u/ggi/bin/mystd.out',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDERR DD PATH='/u/ggi/bin/mystd.err',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDENV DD *
TZ=EST5EDT
LANG=C
PATH=/bin:/usr/lpp/java/J1.4/bin:.

//*STDENV DD PATH='/etc/setting.envvars',
//* PATHOPTS=ORDONLY

Chapter 6. Security customization
313
The command to execute the shell script or program is located in the PARM='...' section. You
can either specify the PARM='...' or the //STDIN DD statements. The default when PARM='...'
is not specified is SH.
SH
Specifies that the shell designated in your TSO/E user ID's security product profile is
to be started and is to run shell commands or scripts provided from STDIN or the
specified program_name.
PGM
Specifies that the specified program_name is to be run as a called program from a
shell environment.
For environment settings, use the //STDENV DD statement. This can be specified as JCLIN
or as a path pointing to an HFS file.
The STDERR file
The STDERR file is the output stream to which error messages or diagnostic messages are
sent. See also standard input, standard output.
The STDENV file
The BPXBATCH utility also uses the STDENV file to allow you to pass environment variables
to the program that is being invoked. This can be useful when not using the shell, such as
when using the PGM parameter.

314

ABCs of z/OS System Programming: Volume 9

© Copyright IBM Corp. 2011. All rights reserved.
315
Chapter 7.
zFS file systems
The z/OS Distributed File Service zSeries File System (zFS) is a z/OS UNIX System Services
(z/OS UNIX) file system that can be used in addition to the hierarchical file system (HFS). zFS
file systems contain files and directories that can be accessed with z/OS UNIX application
programming interfaces (APIs). These file systems can support access control lists (ACLs).
zFS file systems can be mounted into the z/OS UNIX hierarchy along with other local (or
remote) file system types (for example, HFS, TFS, AUTOMNT, and NFS).
This chapter describes the structure of zFS hierarchical file systems and how to customize it
to your requirements. zFS is part of the Distributed File Service base element of z/OS. Before
using the zFS support, you must install the z/OS release, the Distributed File Service, and the
other base elements of z/OS using the appropriate release documentation.
zFS does not replace HFS, rather it is complementary to HFS. zFS can be used for all levels
of the z/OS UNIX System Services hierarchy (including the root file system) when all
members are at the z/OS V1R7 level. Because zFS has higher performance characteristics
than HFS and is the strategic file system, HFS might not be supported in future releases,
which will cause you to migrate the remaining HFS file systems to zFS.
zFS and HFS can both participate in a shared sysplex environment. zFS supports a shared
file system capability in a multisystem sysplex environment. The term shared file system
environment refers to a sysplex that has a BPXPRMxx specification of SYSPLEX(YES). That
is, users in a sysplex can access zFS data that is owned by another system in the sysplex.
For full sysplex support, zFS must be running on all systems in the sysplex in a shared file
system environment and all zFS file systems must be compatibility mode file systems (that is,
they cannot be file systems in multi-file system aggregates). zFS muti-file system aggregates
are not supported by automount.
In addition to providing an introduction to zFS concepts, this chapter provides details on how
to:

Manage and create a zFS hierarchical file system.

Use zFS commands to display information.

Perform space management for a zFS hierarchical file system.
7

316

ABCs of z/OS System Programming: Volume 9
7.1 zSeries File System (zFS)
Figure 7-1 zFS replacing HFS
zFS file systems
zFS is complementary to HFS. zFS can be used for all levels of the z/OS UNIX System
Services hierarchy (including the root file system) when all members are at the z/OS V1R7
level. Because zFS has higher performance characteristics than HFS and is now considered
the strategic file system, HFS may no longer be supported in future releases and you will
have to migrate the remaining HFS file systems to zFS.
HFS support
Support for the HFS file system has been stabilized and you are encouraged to migrate to the
zFS file system for better performance, but IBM has not announced removal of support for the
HFS file system.
zFS functionality
The zSeries File System (zFS) is the strategic z/OS UNIX System Services file system for
z/OS. IBM has enhanced zFS function in z/OS V1R7 so that you can use zFS file systems at
all levels within the file hierarchy.
The migration to zFS file systems needs to be well planned since it will take significant effort
to migrate all data from HFS file systems to zFS file systems.
Unavailability of the data for read/write access must be planned for, as well as the space for
two file systems that are about the same size.
zFS is the strategic UNIX Systems Services file
system for z/OS
The Hierarchical File System (HFS) functionality has
been stabilized
HFS is expected to continue shipping as part of the
operating system and will be supported in
accordance with the terms of a customer's applicable
support agreement
IBM intends to continue enhancing zFS functionality,
including RAS and performance capabilities, in future
z/OS releases
All requirements for UNIX file services are expected to
be addressed in the context of zFS only

Chapter 7. zFS file systems
317
7.2 zFS compatibility mode aggregate
Figure 7-2 zFS compatibility mode aggregate
zFS aggregates
A zFS aggregate is a data set that contains zFS file systems. The aggregate is a VSAM
Linear Data Set (VSAM LDS) and is a container that can contain one or more zFS file
systems. An aggregate can only have one VSAM LDS, but it can contain an unlimited number
of file systems. The name of the aggregate is the same as the VSAM LDS name. Sufficient
space must be available on the volume or volumes, because multiple volumes may be
specified on the DEFINE of the VSAM LDS. DFSMS decides when to allocate on these
volumes during any extension of a primary allocation. VSAM LDSs greater than 4 GB may be
specified by using the extended format and extended addressability capability in the data
class of the data set.
zFS compatibility aggregate
A compatibility mode aggregate can contain only one zFS file system,
making this type of
aggregate more like an HFS file system.
This is flagged in the aggregate when it is created.
The name of the file system is the same as the name of the aggregate, which is the same as
the VSAM LDS cluster name.
The file system size (called a quota) in a compatibility mode aggregate is set to the size of the
aggregate. Compatibility mode aggregates are more like an HFS data set, except that they
are VSAM linear data sets instead of HFS data sets.
ZFSVOL
ZFSVOL
zFS file system
zFS compatibility mode
aggregate
OMVS.PAY.ZFS
VSAM LDS name=Aggregate name=File system name=OMVS.PAY.ZFS
F
/
F
F
F
F
An aggregate is a VSAM linear data set (LDS)

318

ABCs of z/OS System Programming: Volume 9
7.3 BPXPRMxx definitions for zFS
Figure 7-3 zFS definitions in PARMLIB and PROCLIB
Defining zFS as a PFS
Physical file systems are sometimes initialized in an address space called a colony address
space. You can think of these address spaces as extensions of the kernel address space. The
NFS Client and DFS Client physical file systems must be set up in a colony address space
because they need to use socket sessions to talk to their remote servers, and this cannot be
done from the kernel. Whether or not a PFS runs in a colony address space is controlled by
the ASNAME parameter of the FILESYSTYPE statement for the PFS in the BPXPRMxx
member of the SYS1.PARMLIB concatenation.
zFS is the newest colony address space and is defined as follows:
FILESYSTYPE TYPE(ZFS)
ENTRYPOINT(IOEFSCM)
ASNAME(ZFS)
zFS procedure
To set up a physical file system in a colony address space, create a cataloged procedure in
SYS1.PROCLIB.
Note:
The name of the procedure must match the name specified on an ASNAME operand
on the FILESYSTYPE statement in BPXPRMxx that starts physical file systems in this
colony address space.
FILESYSTYPE TYPE(ZFS)
ENTRYPOINT(IOEFSCM)
ASNAME(ZFS)
//ZFS PROC REGSIZE=0M
//ZFSGO EXEC PGM=BPXVCLNY,REGION=&REGSIZE,TIME=1440
//*STEPLIB DD DISP=SHR,DSN=IOE.SIOELMOD
//IOEZPRM DD DSN=IOE.PARMLIB(IOEFSPRM),DISP=SHR
// PEND
BPXPRMxx FILESYSTYPE statement
Defines zFS as a physical file system (PFS)

Chapter 7. zFS file systems
319
7.4 zFS colony address space
Figure 7-4 zFS colony address space
zFS colony address space
zFS runs in a z/OS UNIX System Services (USS) colony address space. A colony address
space is an address space that is separate from the USS address space. HFS runs inside the
USS address space and zFS runs in its own address space, as shown in Figure 7-4.
The colony address space runs outside of JES control and does not have to be stopped if
JES has to be stopped, which facilitates planned shutdowns of individual systems in a sysplex
that has shared file systems.
Other z/OS UNIX colony address spaces
The NFS Client, TFS, and zFS physical file systems support running outside of JES. The
following information may help you to decide whether to move these z/OS UNIX colonies
outside of JES. The DFS Client PFS does not support being started outside of JES.
Started procedures
z/OS UNIX colony address spaces are started procedures. If you do not want to run them
under JES, you will need to change any DD SYSOUT= data sets that are specified in these
procedures. These must be changed because SYSOUT data sets are only supported under
JES. There are three ways you can change these data sets.
TFS
NFS
Client
Logical File
System
Physical
File
Systems
HFS
TFSPROC
NFSCLNT
ZFS
SYS1.PROCLIB
I/O
syscall
FILESYSTYPE TYPE(ZFS
)
ENTRYPOINT(IOEFSCM
)
ASNAME(ZFS)
FILESYSTYPE TYPE(TFS
)
ENTRYPOINT(BPXTFS
)
ASNAME(TFSPROC
)
Procedure name
in SYS1.PROCLIB
BPXPRMxx
ZFS
OMVS Kernel

320

ABCs of z/OS System Programming: Volume 9
7.5 HFS data sets and zFS data sets
Figure 7-5 HFS data sets and zFS data sets
HFS data sets
A z/OS UNIX hierarchical file system is contained in a data set type called HFS. An HFS data
set can reside on an SMS-managed volume or a non SMS-managed volume. HFS data sets
can reside with other z/OS data sets on SMS-managed volumes and non SMS-managed
volumes. Multiple systems can share an HFS data set if it is mounted in read-only mode.
An HFS data set can have up to 123 extents, and the maximum size of the data set is one
physical volume. For a 3390-Model 3, the maximum size is 2.838 GB. HFS data sets only be
accessed by z/OS UNIX.
zFS data sets
The z/OS Distributed File Service (DFS) zSeries File System (zFS) is a z/OS UNIX file
system that can be used in addition to, or to replace an HFS file system. zFS provides
significant performance gains in accessing files approaching 8K in size that are frequently
accessed and updated. The access performance of smaller files is equivalent to that of HFS.
zFS file systems contain files and directories that can be accessed with the z/OS hierarchical
file system application programming interfaces on the z/OS operating system.
HFSVOL
F
F
F
F F
/
ZFSVOL
F
F
F
F F
/
Using zFS, you can
Run applications just like HFS
Use zFS in addition to HFS or replace HFS

Chapter 7. zFS file systems
321
7.6 zFS utilities and commands
Figure 7-6 zFS utilities and commands
IOEAGFMT utility
The IOEAGFMT utility is used to format an existing VSAM LDS as a zFS aggregate. All zFS
aggregates must be formatted before use (including HFS compatibility mode aggregates).
The utility can be run even if the ZFS PFS is not active on the system.
IOEAGSLV utility
This utility scans an aggregate and reports inconsistencies. Aggregates can be verified,
recovered (that is, the log is replayed), or salvaged (that is, the aggregate is repaired). This
utility is known as the Salvager.
zFS provides a recovery mechanism that uses a zFS file system log to verify or correct the
structure of an aggregate. This recovery is invoked by an operator command,
ioeagslv
.

IOEZADM utility
This utility program is specified in batch JCL and allows the zFS
zfsadm
command to be
issued, for example:
//USERIDA JOB ,'zfsadm attach',
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//AGGRINFO EXEC PGM=IOEZADM,REGION=0M,
// PARM=('attach -aggregate OMVS.PRV.AGGR001.LDS0001')
// ...................
IOEAGFMT - utility program to format an aggregate
IOEAGSLV - utility program to scan an aggregate and
report inconsistencies
IOEZADM - utility program that allows:
zfsadm commands to be issued using JCL
Running from within a TSO/E environment
zfsadm - z/OS UNIX shell command
Installation of zFS consideration for zfsadm commands
ln -s /usr/lpp/dfs/global/bin/zfsadm /bin/zfsadm

322

ABCs of z/OS System Programming: Volume 9
The zfsadm command
This command is an administrative command that can be used from the UNIX shell to
customize and display the zFS environment.
zFS installation consideration
Verify that during your z/OS Distributed File Service installation a symbolic link was created
for access to the
zfsadm
commands. If for some reason this was not done, issue the following
command to create a symbolic link in the /bin directory:
#> ln -s /usr/lpp/dfs/global/bin/zfsadm /bin/zfsadm
Note:
Although zfsadm and IOEZADM are physically different modules, they contain
identical code. Whenever we reference zfsadm as a zFS administration command in this
book, we mean both
zfsadm
and IOEZADM.

Therefore, IOEZADM can be used as a
TSO/E command; it performs the same functions as the
zfsadm
command.

Chapter 7. zFS file systems
323
7.7 zfsadm command
Figure 7-7 The zfsadm command and its subcommands
zfsadm command
The zfsadm commands have the same general structure:
command {-option1 argument...| -option2 {argument1 | argument2}..}
[-optional_information]
A command consists of the command suite (
zfsadm
in the figure and a subcommand such as
detach
). The command suite and the command name must be separated by a space. The
command suite specifies the group of related commands.
zFS provides utility programs and z/OS UNIX commands to assist in the customization of the
aggregates and file systems. These utilities and commands are to be used by system
administrators.
The
zfsadm
command and the IOEZADM utility program can be used to manage file systems
and aggregates. The
zfsadm
command can be run as a UNIX shell command from:

A z/OS UNIX System Services shell (OMVS) or a (z/OS UNIX) telnet session

A batch job using the BPXBATCH utility program

TSO foreground or in batch mode using z/OS UNIX APIs (SYSCALL commands, Callable
Services)
zFS file systems can be created using JCL, or by using the
zfsadm
command. Figure 7-7
shows the
zfsadm
command with its subcommands.
zfsadm attach Attach an aggregate
zfsadm apropos Display first line of help entry
zfsadm detach Detach an aggregate
zfsadm grow Grow an aggregate
zfsadm aggrinfo Obtain information on an attached aggregate
zfsadm clone Clone a filesystem
zfsadm clonesys Clone multiple filesystems
zfsadm create Create a filesystem
zfsadm delete Delete a filesystem
zfsadm define Create a VSAM linear data set aggregate
zfsadm format Format an aggregate
zfsadm help Get help on commands
zfsadm lsaggr List all currently attached aggregates
zfsadm lsfs List all file systems on an aggregate or all
zfsadm lsquota List filesystem information
zfsadm quiesce Quiesce an aggregate and all file systems
zfsadm rename Rename a file system
zfsadm setquota Set the quota for a file system
zfsadm unquiesce Make the aggregate and all file systems available
zfsadm config Change value of zFS configuration (IOEFSPRM) in memory
zfsadm configquery Query the current value of zFS configuration option
zfsadm query Query or reset the performance counters

324

ABCs of z/OS System Programming: Volume 9
7.8 Allocate Linear VSAM data set
Figure 7-8 How to allocate a linear VSAM data set
Creating a zFS aggregate
A zFS aggregate is created by defining a VSAM linear data set (LDS) and then formatting that
VSAM LDS as an aggregate. This is done once for each zFS aggregate. You cannot assign
more than one VSAM LDS per aggregate. An aggregate can contain one or more zFS file
systems. A zFS file system is equivalent to an HFS file system.
Using JCL
The VSAM LDS is allocated with the VSAM utility program IDCAMS, as shown in Figure 7-8.
The JCL shows the allocation of both types of aggregates.
Using the zfsadm command
The
zfsadm define
command defines a VSAM LDS. The VSAM LDS is available to be
formatted as a zFS aggregate. The command creates a DEFINE CLUSTER command string
for a VSAM LDS with SHAREOPTIONS(2) and passes it to the IDCAMS utility. If a failure
occurs, the
zfsadm define
command may display additional messages from IDCAMS
indicating the reason for the failure.
Note:
The issuer of the
zfsadm define
command requires sufficient authority to create the
VSAM LDS.
//RFRZAL JOB (999,POK),'R F',CLASS=A,MSGCLASS=U,NOTIFY=&SYSUID,
// REGION=0M
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//DISK DD DISP=OLD,UNIT=3390,VOL=SER=ZFSVOL
//SYSIN DD *
DEFINE CLUSTER -
(NAME (OMVS.CMP01.ZFS) VOL(ZFSVOL) -
LINEAR CYL(200 0) SHAREOPTIONS(3))

zfsadm command - zfsadm define
$> zfsadm define -a OMVS.CMP01.ZFS -volumes totzf1 -cylinders 10 1
IOEZ00248E VSAM linear dataset OMVS.CMP01.ZFS successfully created.
Allocate using IDCAMS in JCL
.

Chapter 7. zFS file systems
325
7.9 Create the aggregate from ISHELL
Figure 7-9 How to allocate a zFS aggregate from the ISHELL
Allocate zFS aggregate from the ISHELL
The panel shown in Figure 7-9, new with z/OS V1R4, allows you to allocate a zFS aggregate
from the ISHELL.
Once you enter the ISHELL, place the cursor under File_systems and press Enter. Then
select Option
4
(New zFS) and the panel shown in the figure appears. Type in the information
to create the aggregate. When you specify the parameters, you now have a linear VSAM data
set.
Specify the appropriate parameters to allocate a data set for an aggregate, format the
aggregate, and create a file system in that aggregate. The aggregate is initially created as a
compatibility mode. The file system defined in the aggregate is the same name as the
aggregate and data set. See
z/OS Distributed File Service zSeries File System
Administration
, SC24-5989 for detailed information on zFS aggregates, file systems, and their
attributes.
Format of aggregate
This ISHELL panel function also formats the aggregate and creates the file system; it just
needs to be mounted before it can be used.
File_systems - Option 4 - New zFS

326

ABCs of z/OS System Programming: Volume 9
7.10 Format VSAM space - create aggregate
Figure 7-10 Formatting a zFS aggregate
Formatting aggregates
The VSAM linear data set must be formatted to be used as a zFS aggregate. Two options are
available for formatting an aggregate and they use the same parameters:

The IOEAGFMT format utility

The
zfsadm format
command, as follows:
zfsadm format -aggregate name
[-initialempty blocks] [-size blocks] [-logsize blocks]
[-owner {uid | name}] [-group {gid | name}]
[-perms decimal | octal | hex_number] [-grow blocks]
[-system system name] [-compat] [-overwrite] [-newauditfid] [-level]#>
zfsadm format -a OMVS.CMP01.ZFS -compat -owner 316 -p o755
IOEZ00077I HFS-compatibility aggregate OMVS.CMP01.ZFS has been successfully
created
The formatting of aggregates can be done without the colony address space (the zFS
address space) being active. The IOEFSPRM file, or the BPXPRMxx PARMLIB member, are
not required for the format to take place.
Creating aggregates and file systems
A zFS file system is created in a zFS aggregate (which is a VSAM linear data set). When
using compatibility mode aggregates, the aggregate and the file system are created at the
same time during the format.
Stand alone utility to format allocated space:
IOEAGFMT format utility
zfsadm command to format the allocated space
#> zfsadm format -a OMVS.CMP01.ZFS -compat -owner 316 -p o755
Does not need zFS colony address space to be active
Does not use the IOEFSPRM configuration file - or
IOEPRMxx parmlib member
zfsadm format -aggregate name
[-initialempty blocks] [-size blocks] [-logsize blocks]
[-owner {uid | name}] [-group {gid | name}]
[-perms decimal | octal | hex_number] [-grow blocks]
[-system system name] [-compat] [-overwrite] [-newauditfid] [-level]

Chapter 7. zFS file systems
327
Formatting space
This utility formats the primary allocation and, if requested by using the
-size
parameter (with
a value greater than the primary allocation), a single
extension
. An extension is a single call to
the Media Manager to extend the data set to the size specified in the
-size
parameter. It is
completely independent of the number of cylinders specified in the secondary allocation when
the data set was defined (the secondary allocation could have been 0).
After you have allocated the space for an aggregate, the default size is the number of 8 K
blocks that fits into the primary allocation. You can specify a
-size
option giving the number of
8 K blocks for the aggregate. If you specify a number that is less than (or equal to) the number
of blocks that fit into the primary allocation, the primary allocation size is used. If you specify a
number that is larger than the number of 8 K blocks that fit into the primary allocation, the
VSAM LDS is extended to the size specified. This occurs during its initial formatting.
When an aggregate is initially formatted using the IOEAGFMT format utility or the
zfsadm
format
command, the formatting takes place as follows:

The default size formatted is the number of blocks that will fit into the primary allocation.

Using the
-size
parameter, if the number of blocks to be formatted is less than the default,
it is rounded up to the default.

If a number greater than the default is specified, a single extent of the VSAM LDS is
attempted after the primary allocation is formatted.

328

ABCs of z/OS System Programming: Volume 9
7.11 Format the aggregate
Figure 7-11 JCL to format an aggregate
Formatting aggregates using JCL
This is a batch utility that formats a VSAM Linear Data Set to become an HFS compatibility
mode aggregate or a multifile system aggregate.
Figure 7-11 shows the JCL for formatting compatibility mode aggregates.
The following parameters are possible:
-aggregate name
Specifies the name of the data set to format. This is also the aggregate
name. The aggregate name is always translated to upper case.
-compat
Indicates that a compatibility mode aggregate should be created. This
means that in addition to formatting the VSAM LDS as a zFS
aggregate, a zFS file system by the same name (the aggregate name)
is created and its quota is set to the size of the available blocks on the
aggregate.
-group gid | name
Specifies the group owner for the root directory of the file system. This
is used with the -compat option; otherwise it is ignored. It can be
specified as a z/OS group name or as a gid. The default is the gid of
the issuer of ioeagfmt. If only the -owner name is specified, the group
is that owner's default group. If only the -owner uid is specified, the
group is the issuer's group.
A compatibility mode aggregate is formatted with this JCL:
//ROGERSA JOB (999,POK),'R F',CLASS=A,MSGCLASS=U,NOTIFY=&SYSUID,
// REGION=0M
//STEP1 EXEC PGM=IOEAGFMT,
// PARM=(' -aggregate ROGERS.AAA.ZFS -compat ')
//SYSPRINT DD SYSOUT=*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//
JCL can be used to format aggregates
PARM parameters must be lower case
-compat required for compatibility aggregates

Chapter 7. zFS file systems
329
-grow blocks
Specifies the number of 8 K blocks that zFS will use as the increment
for extension when the -size option specifies a size greater than the
primary allocation.
-help
Prints the online help for this command. All other valid options
specified with this option are ignored.
-initialempty blocks
Specifies the number of 8 K blocks that will be left empty at the
beginning of the aggregate. The default is 1. If you specify 0, you will
get 1 block. This option is not normally specified.
-level
Prints the level of the
ioeagfmt
command. This is useful when you are
diagnosing a problem. All other valid options specified with -level are
ignored.
-logsize blocks
Specifies the size in 8 K blocks of the log. The default is 1% of the
aggregate size. However, the logsize will never be smaller than 14
blocks and it will never be larger than 16,384 blocks (128 megabytes).
This is normally sufficient. However, a small aggregate that is grown to
be very large will still have a small log. You might want to specify a
larger log if you expect the aggregate to grow very large.
-newauditfid
Specifies that the aggregate should be formatted with the zFS auditfid
and stored in the aggregate.
-overwrite
Required if you are reformatting an existing aggregate. Use this option
with caution; it destroys any existing data. This option is not usually
specified.
-owner uid | name
Specifies the owner for the root directory of the file system. This is
used with the -compat option; otherwise it is ignored. It can be
specified as a z/OS user ID or as a uid. The default is the uid of the
issuer of
ioeagfmt
.
-perms number
Specifies the permissions for the root directory of the file system. This
is used with the -compat option, otherwise it is ignored. The number
can be specified as octal (for example, o755), as hexadecimal (for
example, x1ED), or as decimal (for example, 493). The default is o755
(owner read-write-execute, group read-execute, other read-execute).
-size blocks
Specifies the number of 8 K blocks that should be formatted to form
the zFS aggregate. The default is the number of blocks that will fit in
the primary allocation of the VSAM Linear Data Set (LDS). If a number
less than the default is specified, it is rounded up to the default. If a
number greater than the default is specified, a single extend of the
VSAM LDS is attempted after the primary allocation is formatted
unless the -grow option is specified. In that case, multiple extensions
of the amount specified in the -grow option will be attempted until the
-size is satisfied. The size can be rounded up to a control area (CA)
boundary by DFSMS. It is not necessary to specify a secondary
allocation size on the DEFINE of the VSAM LDS for this extension to
occur. Space must be available on the volume.

330

ABCs of z/OS System Programming: Volume 9
7.12 Ioeagfmt successful messages
Figure 7-12 zFS formatting messages
Formatting messages
When you format a compatibility mode aggregate (output of the JCL shown in the figure), the
following processing is done:

The aggregate is attached and then detached.

A file system is created for the aggregate with the same name as the aggregate.
The ioeagfmt utility
The
ioeagfmt
utility is used to format an existing VSAM LDS as a zFS aggregate. All zFS
aggregates must be formatted before use (including HFS compatibility mode aggregates).
You can run
ioeagfmt
even if the zFS PFS is not active on the system. The size of the
aggregate is as many 8 K blocks as fit in the primary allocation of the VSAM LDS or as
specified in the -size option. The -size option can cause one additional extension to occur
during formatting. To extend it further, use the
zfsadm grow
command. If -overwrite is
specified, all existing primary and secondary allocations are formatted and the size includes
all of that space. If the VSAM LDS has a SHAREOPTIONS value of other than 3,
ioeagfmt

will change it to SHAREOPTIONS 3 during format.
IOEZ00004I Formatting to 8K block number 1800 for primary extent of ROGERS.AAA.ZFS.
IOEZ00005I Primary extent loaded successfully for ROGERS.AAA.ZFS.
IOEZ00535I *** Using initialempty value of 1.
*** Using 1799 (8192-byte) blocks
*** Defaulting to 17 log blocks(maximum of 1 concurrent transactions).
IOEZ00327I Done. ROGERS.AAA.ZFS is now a zFS aggregate.
IOEZ00048I Detaching aggregate ROGERS.AAA.ZFS
IOEZ00071I Attaching aggregate ROGERS.AAA.ZFS to create HFS-compatible file system
IOEZ00074I Creating file system of size 14207K, owner id 0, group id 2, permissions
IOEZ00048I Detaching aggregate ROGERS.AAA.ZFS
IOEZ00077I HFS-compatibility aggregate ROGERS.AAA.ZFS has been successfully created
The following messages are displayed in the
SYSPRINT data set of the JCL job
To use the file system, it must be mounted

Chapter 7. zFS file systems
331
Using a batch job
For a batch job, the
ioeagfmt
options are specified in the EXEC PARM as a single
subparameter (a single character string enclosed in apostrophes with no commas separating
the options). You cannot put the ending apostrophe in column 72. If it needs to go to the next
line, use a continuation character in column 72 (continuing in column 16 with the ending
apostrophe on the second line). Remember that a JCL EXEC PARM is limited to 100
characters.
Privilege required
The user must have ALTER authority to the VSAM LDS or must be UID 0 or have READ
authority to the SUPERUSER.FILESYS.PFSCTL profile in the z/OS UNIXPRIV class. In fact,
UPDATE authority to the VSAM LDS is sufficient for format, but zFS will not be able to set the
zFS bit in the catalog unless the issuer has ALTER authority.
If you are changing the owner or group to something other than the issuer or you are
changing the permissions to other than the default, you need UID 0 or READ authority to the
SUPERUSER.FILESYS.PFSCTL profile in the z/OS UNIXPRIV class.

332

ABCs of z/OS System Programming: Volume 9
7.13 Grow an aggregate
Figure 7-13 How to grow the size of an aggregate
Grow an aggregate
The format utility formats the primary allocation and, if requested by using the
-size
parameter (with a value greater than the primary allocation), a single extension. An extension
is a single call to the Media Manager to extend the data set to the size specified in the
-size

parameter. It is completely independent of the number of cylinders specified in the secondary
allocation when the data set was defined (the secondary allocation could have been
0
).
If a compatibility mode aggregate becomes full, the administrator can grow the aggregate
(that is, cause an additional allocation to occur and format it to be part of the aggregate). This
is accomplished with the
zfsadm grow
command. There must be space available on the
volume(s) to extend the aggregate's VSAM linear data set. The size specified on the
zfsadm
grow
command must be larger than the current size of the aggregate. In the example in
Figure 7-13, we used
-size 0
. Specifying a size of 0 indicates to use the secondary
allocation.
Grow example
For example, suppose a two-cylinder (primary allocation, 3390) aggregate has a total of 180
8K blocks and a (potential) secondary allocation of one cylinder. 180 8K blocks is 1440K
bytes. A
zfsadm aggrinfo
command for this aggregate might show 1440K.
zfsadm grow
does
this by calling DFSMS to allocate the additional DASD space. DFSMS requires a number of
reserved blocks. Therefore, specify a few blocks larger than the current size before an
allocation occurs.
#>
zfsadm grow -aggregate OMVS.CMP02.ZFS -size 0

IOEZ00173I Aggregate OMVS.CMP02.ZFS successfully grown
OMVS.CMP02.ZFS (R/W COMP): 61598 K free out of total 62072 (2000 reserved)
Aggregates can be grown via a z/OS UNIX command:
zfsadm grow
command
Grow the size of an aggregate
Size 0 - Indicates to use secondary extent allocation

Chapter 7. zFS file systems
333
7.14 Dynamic aggregate extension
Figure 7-14 Growing the aggregate size dynamically
Growing an aggregate dynamically
If aggregates become full they can be grown by using the
zfsadm grow
command. You need to
specify a larger size or specify zero for the size to get a secondary allocation size extension.
You have the possibility of dynamically growing an aggregate if it becomes full. The aggregate
is extended automatically when an operation cannot complete because the aggregate is full.
Specifying the dynamic aggregate grow option
An administrator can specify that an aggregate should be dynamically grown if it becomes
full. This is specified by the
-aggrgrow
option on the
zfsadm

attach
command, or the
aggrgrow

suboption of the
define_aggr
option of the IOEFSPRM file, or globally by the
aggrgrow
option
of the IOEFSPRM file. The aggregate (that is, the VSAM Linear Data Set) must have
secondary allocation specified when it is defined, and space must be available on the
volume(s). The aggregate will be extended when an operation cannot complete because the
aggregate is full. If the extension is successful, the operation is redriven transparent to the
application.
Important:
To dynamically grow an aggregate when it becomes full, the VSAM LDS must
have a secondary allocation and have space on the volumes.
Grow an aggregates dynamically without commands
VSAM LDS must have a secondary allocation + space
Ways to specify aggregate extension
zfsadm config
command
aggrgrow on | off
An option in the IOEFSPRM file
aggrgrow=on|off
mount command - parm('aggrgrow')
mount filesystem('omvs.test.zfs') mountpoint('/tmp/test')
type(zfs) mode(rdwr) parm('aggrgrow')
Aggregate is extended using a secondary allocation
Secondary allocation is formatted becomes available

334

ABCs of z/OS System Programming: Volume 9
Ways to specify the dynamic option
Dynamic aggregate extension can be enabled in the following ways:

In the IOEFSPRM configuration file, you can dynamically extend an aggregate when it
becomes full by specifying one of the following options:
– Specify a new option,
aggrgrow=on | off
. The default value is off.

Using the
mount
command, in the PARM keyword you can specify either
aggrgrow
or
noaggrgrow
, as shown in the following example:
mount filesystem('omvs.test.zfs') mountpoint('/tmp/test') type(zfs) mode
(rdwr) parm('aggrgrow')
Example of the dynamic grow option
When an aggregate fills and dynamic aggregate extension has been specified using one of
the options, the aggregate is extended using secondary allocation extensions, and the
extensions taken are formatted and become available transparently to the application. The
messages issued indicating the process are as follows:
IOEZ00312I Dynamic growth of aggregate OMVS.TEST.ZFS in progress, (by user
AYVIVAR).
IOEZ00329I Attempting to extend OMVS.TEST.ZFS by a secondary extent.
IOEZ00324I Formatting to 8K block number 360 for secondary extents of
OMVS.TEST.ZFS
IOEZ00309I Aggregate OMVS.TEST.ZFS successfully dynamically grown (by user
AYVIVAR).
Note:
The option specified here is the default if none of the following ways of speci-
fying the
aggrgrow | noaggrgrow
options are used.
Note:
This
aggrgrow | noaggrgrow
option can only be used with compatibility mode
aggregates.

Chapter 7. zFS file systems
335
7.15 The -grow option
Figure 7-15 Specifying the -grow option
A -grow example
Since the
-size
parameter specified can only be allocated in the primary allocation and one
extension, and you wanted to format a 3-volume aggregate with the IOEAGFMT utility—this
was not possible because it requires a primary and at least two extensions.

However, a new
-grow
option is provided with z/OS V1R4 for the IOEAGFMT utility and the
zfsadm format

command to allow specification of the increment that can be used for extension of the
aggregate when
-size
is larger than the primary allocation. This allows the extension by the
-grow
amount until
-size
is satisfied.
-grow
Specifies the number of 8K blocks that zFS uses as the increment for an extension
when the
-size
option specifies a size greater than the primary allocation.
Other examples of -grow
To illustrate the before and after using the
-grow
option, the following example has a VSAM
LDS defined with 2 cylinders of primary space and 1 cylinder of secondary space.
300240 8K blocks 300240 8K blocks 300240 8K blocks
When an aggregate is initially formatted using
IOEAGFMT or the zfsadm format command
Size, -size specified must be able to be allocated in
the primary allocation and one extension
If you wanted to format a 3-volume aggregate with
IOEAGFMT - not possible
Requires a primary and at least two extensions
Need to use the
zfsadm format
command to specify:
zfsadm format -size 900720 -grow 300240

336

ABCs of z/OS System Programming: Volume 9
The file created has two extents: the first one corresponds to the primary space specified in
the define process (30 tracks), and a second one with 30 tracks.
With the new
-grow
parameter, you are allowed to specify the increment that will be used for
an extension size larger than the primary allocation. That is, after the primary space is
allocated, multiple extensions of the amount specified by the
-grow
parameter rounded up to
a multiple of the secondary space defined will be attempted until the total number of blocks
specified by the
-size
parameter is satisfied.
Replacing the example shown previously, use the
-grow
parameter on the format process, as
follows:
Now the VSAM LDS has three extensions, the first corresponding to the primary space
specified and the next two by the
-grow
amount.
//AYVIVAR2 JOB CLASS=J,MSGCLASS=A,NOTIFY=AYVIVAR
/*JOBPARM S=SC65
//P010 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER(NAME(OMVS.TESTA.ZFS) VOLUMES(SBOX43) -
LINEAR CYL(2,1) SHAREOPTIONS(2))
//
//AYVIVAR2 JOB CLASS=J,MSGCLASS=V,NOTIFY=AYVIVAR
/*JOBPARM S=SC65
//FORMAT EXEC PGM=IOEAGFMT,REGION=0M,
// PARM=('-aggregate OMVS.TESTA.ZFS -size 276 -grow 90 -compat')
//SYSPRINT DD SYSOUT=*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
Note:
The default for the size of the aggregate is the number of 8K blocks that fit in the
primary allocation. You can specify a
-size
option giving the number of 8K blocks for the
aggregate. If you specify a number that is less than (or equal to) the number of blocks that
fit into the primary allocation, the primary allocation size is used. If you specify a number
that is larger than the number of 8K blocks that fit into the primary allocation, the VSAM
LDS is extended to the size specified if the total size will fit in the primary allocation and a
single extension. The single extension must be no larger than a single volume. This occurs
during its initial formatting.

Chapter 7. zFS file systems
337
7.16 -grow option for formatting
Figure 7-16 The -grow option for formatting
The -grow option for format
There are many allocations of VSAM linear data sets where you may want to format the entire
extent during the initial format. The
-grow
option allows you to specify that you want to do this
during the format of the aggregate.
Use the
-grow
option to specify the size of a secondary allocation. This causes the format
routine to continue formatting the specified allocation until the entire allocation is completely
formatted.
The -size option
To format the entire allocation, use the
-size
option, together with the
-grow
option, as
follows:
zfsadm format -size 900720 -grow 300240
The
-size
option specifies the number of 8K blocks that should be formatted to form the zFS
aggregate. The default is the number of blocks that will fit in the primary allocation of the
VSAM LDS. If a number less than the default is specified, it is rounded up to the default. If a
number greater than the default is specified, a single extend of the VSAM LDS is attempted
after the primary allocation is formatted unless the
-grow
option is specified. In that case,
multiple extensions of the amount specified in the
-grow
option will be attempted until the
-size
is satisfied. The size may be rounded up to a control area (CA) boundary by DFSMS. It
is not necessary to specify a secondary allocation size on DEFINE of the VSAM LDS for this
extension to occur. Space must be available on the volumes.
Now, IOEAGFMT and
zfsadm format
provide the
-grow option
Specifies the increment that will be used for extension
when -size is larger than the primary allocation
Extends by -grow amount until -size is satisfied
primary
-grow
-size
300240 8K blocks 300240 8K blocks 300240 8K blocks

338

ABCs of z/OS System Programming: Volume 9
7.17 Mounting the file system
Figure 7-17 Mounting a file system
Mounting a file system
The zFS file system can now be mounted into the z/OS UNIX hierarchy. This can be
accomplished in the following ways:

With the TSO/E MOUNT command

Using an OMVS shell
mount
command

Using the ISHELL

A mount statement in the BPXPRMxx PARMLIB member

An automount policy
This assumes that the directory mountpoint exists. The TYPE parameter of the MOUNT
command specifies ZFS. This is required for any zFS file system. All other forms of the mount
function are also supported (for example, the
/usr/sbin/mount
command, the automount
facility, etc.). Once the zFS file system is mounted, applications and commands can be
executed and files and directories can be accessed in zFS just as in HFS.
Note:
When the file system is mounted, it causes the aggregate to be attached.
Once a compatibility aggregate is formatted
The file system is created
The aggregate is not attached
When mounting the file system
The aggregate is attached
Note: Do not manually attach a compatibility
mode aggregate

Chapter 7. zFS file systems
339
7.18 ISHELL support for zFS
Figure 7-18 Managing zFS aggregates from the ISHELL
Manage zFS aggregates
With the ISPF shell (ISHELL), a user or system programmer can use ISPF dialogs instead of
shell commands to perform many tasks, especially those related to file systems and files. An
ordinary user can use the ISPF shell to work with zFS file system aggregates.
Use the ISHELL command in the ISPF Option 6 Menu to invoke the ISPF shell, which is a
panel interface that helps you to set up and manage z/OS UNIX System Services functions.
In the pull-down under File_systems is the new option 5. To make use of it, select
Option 5
in
the File_systems menu, and press Enter; the panel shown in Figure 7-19 on page 340 is
displayed. This panel enables you to work with all the attached aggregates from the ISHELL.
Similar information about the aggregates can also be obtained with the
zfsadm
command
from the OMVS shell session.
ISHELL provides ability to manage zFS aggregates

340

ABCs of z/OS System Programming: Volume 9
7.19 Panel of attached zFS aggregates
Figure 7-19 ISHELL panel showing attached zFS aggregates
Attached zFS aggregate ISHELL panel
This panel shows the aggregate list of all zFS aggregates that are currently attached explicitly
or implicitly as compatibility aggregates. The amount of free space and total space is also
shown, in units of kilobytes. From this panel you can select an option of one or more
aggregates with an action code.
The valid action codes are:
A
Show the attributes for the aggregate.
L
List the file systems in the aggregate. The file system list will allow you to perform
actions on file systems.
D
Detach an aggregate that is not in use.
E
Extend the size of the aggregate.
The available options are:
1.
Attach aggregate
: Select this option to specify an aggregate to attach.
2.
Create aggregate
: Select this option to create an HFS-compatible aggregate. Note that
an HFS-compatible aggregate also contains a file system with the same name as the
aggregate. Additional file systems can be created in that aggregate if it has been explicitly
attached, and the original file system can also be deleted.
Attached zFS Aggregates Row 1 to 20 of 10
3

Select an aggregate with a line command or select an option.
A=Attributes L=List file systems D=Detach E=Extend

Option: _ 1. Attach aggregate 2. Create aggregate

S Aggregate Name Free Space Total Space
_ BBRR7064.SBBOHFS 297303 2376000
_ BB16164.SBBOHFS 159201 1699200
_ BB26163.SBBOHFS 159201 1699200
_ BB36163.SBBOHFS 310246 2347200
_ HFS.ZOSR1A.Z1ARA1.JAVA31V5 23670 292320
_ HFS.ZOSR1A.Z1ARA1.JAVA64V5 22518 276480
_ HFS.ZOSR1A.Z1ARA1.JV390 20195 220320
_ HFS.ZOSR1A.Z1ARA1.ROOT 27174 2517840
_ HFS.ZOSR1A.Z1ARA1.SBBN7ZFS 92824 1728000
_ HFS.ZOSR1A.Z1ARA1.SIZUZFS 13025 57600
_ HFS.ZOSR1A.Z1ARA1.XML 102641 1314720
_ HFS.ZOSR1B.Z1BRA1.JAVA31V5 11729 283680
_ HFS.ZOSR1B.Z1BRA1.JAVA31V6 18804 408240
_ HFS.ZOSR1B.Z1BRA1.JAVA64V5 11377 268560
_ HFS.ZOSR1B.Z1BRA1.JAVA64V6 20097 455760
_ HFS.ZOSR1B.Z1BRA1.ROOT 343945 2863440

Chapter 7. zFS file systems
341
7.20 Display aggregate attributes
Figure 7-20 Display of an aggregate’s attributes
Display attributes for an aggregate
Figure 7-20 shows the screen returned when you specify
A
- Attributes for an aggregate from
the previous screen and press Enter.
For detailed information about zFS aggregates, file systems, and their attributes, see
z/OS
Distributed File Service zSeries File System Administration
, SC24-5989.
The zfsadm command
If you use the
zfsadm aggrinfo
command to display the aggregate information to list the
aggregate attributes, the result is as follows:
ROGERS @ SC70:/u/rogers>zfsadm aggrinfo BBRR7064.SBBOHFS -long
BBRR7064.SBBOHFS (R/W COMP): 297303 K free out of total 2376000
version 1.4
auditfid E2C2D6E7 F1D8009F 0000

31627 free 8k blocks; 44287 free 1K fragments
23776 K log file; 64 K filesystem table
336 K bitmap file

342

ABCs of z/OS System Programming: Volume 9
7.21 Display attached aggregates
Figure 7-21 Displaying attached aggregates
Displaying attached aggregates
The
zfsadm lsaggr
command lists all currently attached aggregates for zFS.
This command displays a separate line for each aggregate. Each line displays the following
information:

The aggregate name

The system name where the aggregate is attached

The access mode - R/W is Read/Write
You can use the
zfsadm aggrinfo
command to display information about the amount of disk
space available on a specific aggregate or on all aggregates on a system.
ROGERS @ SC70:/u/rogers>zfsadm lsaggr
IOEZ00106I A total of 103 aggregates are attached
OMVS.DB2V9.SDAHHFS1.D070806 SC63 R/W
OMVS.DB2V9.SDAHHFS1.D090309 SC63 R/W
OMVS.RADTOOL7.HFS SC63 R/W
ZFSFR.ZFSA.ZFS SC65 R/W
ZFSFR.ZFSB.ZFS SC65 R/W
OMVS.DB2V9.SDSNWORF.D071020 SC63 R/W
ZFSFR.ZFSC.ZFS SC65 R/W
ZFSFR.ZFSD.ZFS SC65 R/W
ZFSFR.ZFSE.ZFS SC65 R/W
ZFSFR.ZFSF.ZFS SC65 R/W
ZFSFR.ZFSG.ZFS SC65 R/W
OMVS.TWS820.TWSCE2EW.HFS SC63 R/W
OMVS.TWS820.TWSCTPRK.HFS SC63 R/W
OMVS.DB2V9.SDSNWORF.D081006 SC63 R/W
OMVS.DB2V9.SDSNWORF.D080701 SC63 R/W
OMVS.DB2V9.SDSNMQLS.D071020 SC63 R/W
===>


Chapter 7. zFS file systems
343
7.22 List file systems
Figure 7-22 Displaying zFS file systems
Displaying file systems
The
zfsadm lsfs
command lists all the file systems on a given aggregate or all attached
aggregates.
Using the
-a
option and specifying the file system name is shown in Figure 7-22. If you
specify an aggregate name that is used to retrieve file system information, the aggregate
name is not case sensitive and is always translated to uppercase. If this option is not
specified, the command displays information for all attached aggregates.
The
-fast
option causes the output of the command to be shortened to display only the
aggregate name if it contains one or more file systems, or a message indicating that there are
no file systems contained in the aggregate.
ROGERS @ SC65:/u/rogers> zfsadm lsfs -a ROGERS.HARRY.ZFS
IOEZ00129I Total of 1 file systems found for aggregate ROGERS.HARRY.ZFS
ROGERS.HARRY.ZFS RW (Mounted R/W) 9 K alloc 9 K quota On-line
Total file systems on-line 1; total off-line 0; total busy 0; total mounted 1
ROGERS @ SC65:/u/rogers>
===>
ROGERS @ SC65:/u/rogers> zfsadm lsfs -fast
IOEZ00369I A total of 5 aggregates are attached to the sysplex.
ROGERS.HARRY.ZFS
TWS.TWSAWRK.RVA.ZFS
OMVS.HERING.TEST.ZFS
ROGERS.TEST.ZFS
ROGERS.AAA.ZFS
ROGERS @ SC65:/u/rogers>
===>
The -fast option just lists the aggregate names -
For compat mode aggregates - same as file system nam
e

344

ABCs of z/OS System Programming: Volume 9
7.23 zFS aggregate space commands
Figure 7-23 Aggregate space commands
zFS commands to determine aggregate space
Each file system has a quota represented in 1 KB fragments. The quota of a file system is a
logical number and can be smaller or larger than the size of the disk (if the size of the disk
were expressed in 1 KB fragments).
The
zfsadm lsquota
command shows the quota in 1 KB units and also shows the aggregate
size and usage in 1 KB units (it shows the amount of space used for the three special objects
in Figure 7-23 also).
A zFS aggregate is an array of 8 K blocks. Three special objects are present in all zFS
aggregates. These objects take up space in an aggregate, which means that space cannot be
used for user files:

Log file - Records metadata changes. By default, its size is 1% of the disk size. However, it
will never be smaller than 14 blocks and it will never be larger than 16,384 blocks
(128 MB).

Bitmap - Lists the blocks that are free on disk. The file size depends on the size of the
aggregate.

Aggregate File System List - Describes the file systems contained in the aggregate. For
compatibility mode aggregates it is usually only one 8 KB block. For multifile system
aggregates, its size depends on how many file systems are in the aggregate.
ROGERS @ SC65:/u/rogers>
zfsadm aggrinfo ZFSFR.ZFSG.ZFS

ZFSFR.ZFSG.ZFS (R/W COMP): 6374 K free out of total 7200
ROGERS @ SC65:/u/rogers>
zfsadm lsquota ZFSFR.ZFSG.ZFS

Filesys Name Quota Used Percent Used Aggregate
ZFSFR.ZFSG.ZFS 7047 673 9 11 = 826/7200 (zFS)
AGGRINFO - Displays information about an aggregate
LSQUOTA - Shows quota information about file
systems and aggregates
Space usage on all aggregates
zfsadm aggrinfo
zfsadm aggrinfo shows aggregate disk space usage
Based on the number of 8K blocks
Subtracts the space reserved for the 3 objects


Chapter 7. zFS file systems
345
For compatibility mode aggregates the file system quota is set to be the following size:
Total disk size (in 1 KB units) - size of the above three special objects (in 1 KB units)
zFS aggregate disk usage
zFS stores files on disk in one of three ways:

Inline - If the file is 52 bytes or less, it is stored in the same data structure on disk that
holds the file status (things such as owner, size, and permissions). A file of 52 bytes or
less takes no extra disk space.

Fragmented - If the file is 7 KB or less and has never been larger than 7 KB, it is stored in
1 KB fragments (hence it is stored in part of an 8 KB block). Multiple small files can share
the same 8 KB block on disk.

Blocked - If the file is over 7 KB, it is stored as an array of 8 KB blocks.
Aggregate File System List
- This describes the file systems contained in the aggregate.
For compatibility mode aggregates it is usually only one 8 KB block. For multifile system
aggregates, its size depends on how many file systems there are.
The aggrinfo subcommand
The
zfsadm aggrinfo
command displays information about an aggregate, or all attached
aggregates, if there is no specific aggregate specified. This is based on the number of 8 KB
blocks. The command shows output in units of 1 KB blocks.
The
zfsadm aggrinfo
command shows aggregate disk space usage. This is based on the
number of 8 KB blocks. It subtracts the space reserved for the above three objects in its
calculations (and tells you this in the output). The command shows output in units of 1 KB
blocks.
ROGERS @ SC65:/u/rogers>zfsadm aggrinfo
IOEZ00368I A total of 1 aggregates are attached.
ZFSFR.ROOT.ZFS (R/W COMP): 292908 K free out of total 1440000
The -long option
If you use the
-long
option of the
zfsadm aggrinfo
command, it shows the number of free 8 K
blocks, the number of free 1 K fragments and the size (in K) taken up by the log file, the file
system table, and the bitmap, as follows:
PAUL @ SC65:/>zfsadm aggrinfo ZFSFR.ZFSG.ZFS -long
ZFSFR.ZFSG.ZFS (R/W COMP): 6374 K free out of total 7200
version 1.4
749 free 8k blocks; 382 free 1K fragments
112 K log file; 24 K filesystem table
The lsquota subcommand
The
zfsadm lsquota
command displays quota and usage information about a file system. The
command also provides usage information about the aggregate in which the file system
resides. The file system does not need to be mounted to use this command. The aggregate
containing the file system must be attached.
The
zfsadm lsquota
command displays the name of the file system, the quota and the quota
used (in kilobytes) of the file system, and the percentage of the quota in use. It also displays
the information about the percentage of the aggregate in use, the number of kilobytes in use
on the aggregate and the number of available kilobytes on the aggregate in which the file
system resides. It also reports that the file system is zFS.

346

ABCs of z/OS System Programming: Volume 9
7.24 Command for aggregate display
Figure 7-24 Display aggregate usage for the specified file system
zFS command to display aggregate usage
The
F ZFS
command enables you to query internal zFS counters and values. They are
displayed on the system log. It also allows you to initiate or gather debugging information. The
zFS PFS must be running to use this command.
The F ZFS,AGGRINFO command
Using this command, you can display information about specific aggregates.
The IOEZ00438I message just indicates that AGGRINFO is the keyword for running a query
command.
This command provides a detailed breakdown of the space utilization in the zFS aggregate
that is specified containing a file system.
F ZFS,AGGRINFO,ROGERS.LARGE.ZFS
IOEZ00438I Starting Query Command AGGRINFO.
Total 8K blocks on aggregate: 70470 (563760K bytes)
Number of 8K blocks used for log file: 705 (indirect blocks 1)
Number of 8K blocks reserved for cross-system serialization: 1
Number of 8K blocks used for filesystem table: 6
Number of 1K fragments used for bad-block file: 1
Number of 8K blocks used for bitmap file: 11
Number of 8K blocks free for use on aggregate: 5711
Number of free 1K fragments available for use on aggregate: 14

Filesystem inode table 8K quota limit 557975K used 512273K
name=ROGERS.LARGE.ZFS

IOEZ00025I zFS kernel: MODIFY command - AGGRINFO,ROGERS.LARGE.ZFS
completed successfully


Chapter 7. zFS file systems
347
7.25 zFS threshold monitoring space usage
Figure 7-25 Monitoring aggregate space usage
zFS monitoring aggregate space usage
The zFS threshold monitoring function
aggrfull
reports space usage based on total
aggregate disk size. It incorporates the space for the above three special objects when
showing total disk space and the amount used on disk in its messages. The
aggrfull

message shows units in 8 K blocks.
The aggrfull parameter
The
aggrfull
parameter specifies the threshold and increment for reporting aggregate full
error messages to the operator. The default is the
aggrfull
specification in the IOEFSPRM
file.This parameter only applies to compatibility mode aggregates or file systems.
The following message is issued to the operator when issuing the following command:
zfsadm configquery -aggrfull
IOEZ00078E zFS aggregate Name exceeds Threshold% full (blocks1/blocks2)
(WARNING)
The message indicates that a zFS aggregate used space has exceeded the
administrator-defined threshold specified on the
aggrfull
option. The numbers in
parentheses are the number of 8 K blocks used in the aggregate and the number of 8 K
blocks in the total aggregate, respectively.
zFS threshold monitoring function aggrfull reports:
Space usage based on total aggregate disk size
Has the space for the three special objects - total disk
space and amount used on disk in its messages
The aggrfull message shows units in 8K blocks
Number of 8K blocks used in the aggregate
Number of 8K blocks in the total aggregate
ROGERS @ SC65:/u/rogers>zfsadm configquery -aggrfull
IOEZ00317I The value for configuration option -aggrfull is
(80,5).
ROGERS @ SC65:/u/rogers>
zfsadm config -aggrfull "(80,5)"
IOEZ00300I Successfully set -aggrfull to (80,5)
IOEZ00078E zFS aggregate Name exceeds Threshold% full (blocks1/blocks2)(WARNING)

348

ABCs of z/OS System Programming: Volume 9
7.26 Dynamic configuration parameters
Figure 7-26 Changing the zFS IOEFSPRM member parameters dynamically
zfsadm commands
The
zfsadm
commands, with subcommands
config
and
configquery
, are used to change
configuration values dynamically without a shutdown and restart of the zFS PFS, and to
display the current value of the zFS configuration options, as follows:

The
zfsadm config
command changes the value of zFS configuration options in memory
that were specified in the
IOEFSPRM
file (or defaulted) or the IOEPRMxx PARMLIB member.

The
zfsadm configquery
command displays the current value of zFS configuration
options retrieved from the zFS address space memory, rather than from the
IOEFSPRM
file
or the IOEPRMxx PARMLIB member.
Changing parameters dynamically
The
zfsadm configquer
y command displays the current value of zFS configuration options.
The value is retrieved from zFS address space memory rather than from the
IOEFSPRM
file.
You can specify that the configuration option query request should be sent to another system
with the
-system
option.
Note:
If you are using an
IOEFSPRM
file in your zFS PROC, the issuer must have READ
authority to the data set that contains the
IOEFSPRM
file. If you are using PARMLIB
(IOEPRMxx), the issuer does not need special superuser authorization.
Commands to display and modify parms
The zfsadm configquery command queries the current
value of zFS configuration options
The zfsadm config command changes the value of zFS
configuration (IOEFSPRM) options in memory
The commands require the following access authority
and zfsadm requires superuser authority
Command
Command description
IOEFSPRM
SU mode
zfsadm config
Modify current
configuration options
READ
YES
zfsadm configquery
Display current
configuration options
READ
NO

Chapter 7. zFS file systems
349
Using PARMLIB (IOEPRMxx)
The preferred alternative to the IOEZPRM DDNAME specification is specifying the
IOEFSPRM member as a true PARMLIB member. In this case, the member has the name
IOEPRMxx, where xx is specified in the PARMLIB member list.
When the IOEFSPRM is specified in the IOEZPRM DD statement of the zFS PROC, there
can only be one
IOEFSPRM
file for each member of a sysplex. Using PARMLIB, zFS
configuration options can be specified in a list of configuration parm files. This allows an
installation to specify configuration options that are common among all members of the
sysplex (for example, adm_threads) in a shared IOEPRMxx member, and configuration
options that are system-specific (for example, define_aggr) in a separate, system-specific
IOEPRMxx member. If a configuration option is specified more than once, the first one found
is taken.

350

ABCs of z/OS System Programming: Volume 9
7.27 zfsadm configquery command options
Figure 7-27 zfsadm configquery command options
The zfsadm configquery command
The
zfsadm configquery
command queries the current value of zFS configuration options
that you specify in either the IOEFSPRM DD statement in the procedure or the IOEPRMxx
PARMLIB member. The command displays the current value of zFS configuration options.
The value is retrieved from zFS address space memory rather than from the
IOEFSPRM
file.
You can specify that the configuration option query request should be sent to another system
by using the
-system
option.
sysplex_state parameter
Displays the sysplex state of zFS, as follows:
Zero (0
Indicates that zFS is not in a shared file system environment (normal for V1R6
and prior releases and for single system configurations including monoplex and
xcflocal).
One (1)
Indicates that zFS is in a shared file system environment (normal for V1R7 and
above in a shared file system environment). This also indicates that zFS is
non-sysplex aware for RW file systems; that is, either sysplex=off is specified or is
the default.
Two (2)
Indicates that zFS is running in a sysplex-aware environment with sysplex=on.
Three (3)
Indicates that zFS is running in a sysplex-aware environment with sysplex=filesys.
Note:
Use
zfsadm configquery -all
to display all of the parameter definitions.
$> zfsadm configquery -sysplex_state
IOEZ00317I The value for configuration option -sysplex_state is 3.
$> zfsadm configquery -all ---- (Display all of the parms)
[-system system name] [-adm_threads] [-aggrfull] [-aggrgrow]
[-all] [-auto_attach] [-client_cache_size] [-client_reply_storage]
[-cmd_trace] [-convert_auditfid] [-debug_dsn] [-file_threads]
[-fsfull] [-fsgrow] [-group] [-log_cache_size] [-meta_cache_size]
[-metaback_cache_size] [-msg_input_dsn] [-msg_output_dsn] [-nbs]
[-romount_recovery] [-sync_interval] [-syslevel]
[-sysplex_filesys_sharemode] [-sysplex_state] [-token_cache_size]
[-trace_dsn] [-trace_table_size] [-tran_cache_size]
[-user_cache_readahead] [-user_cache_size] [-vnode_cache_size]
[-level] [-help]
Queries the current value of zFS configuration options
Use the zfsadm configquery -sysplex_state command to:
Indicate 2 or 3 if zFS is running sysplex-aware or 1 if it is not

Chapter 7. zFS file systems
351
7.28 zfsadm config command options
Figure 7-28 The IOEFSPRM member or IOEPRMxx parameters
zfsadm config command options
The
zfsadm config
command changes the configuration options (in memory) that were
specified in the
IOEFSPRM
file (or defaulted) or in the IOEPRMxx PARMLIB member. The
IOEFSPRM
file is not changed. If you want the configuration specification to be permanent, you
need to modify the
IOEFSPRM
file or the IOEPRMxx PARMLIB member since ZFS reads the
one that you use to determine the configuration values the next time ZFS is started.
Note:
//ZFS PROC REGSIZE=0M
//*
//ZFZGO EXEC PGM=BPXVCLNY,REGION=&REGSIZE,TIME=1440
//* ----------------------------------------------------------------
//*STEPLIB DD DISP=SHR,DSN=IOE.SIOELMOD
//*
//* Using the parmlib search function instead of explicit IOEZPRM DD
//* by specifying IOEPRMxx members in the filesystype definition of
//* zFS and making the next line just a comment...
//*IOEZPRM DD DISP=SHR,DSN=SYS1.TEST.IOEFSZFS(IOEFSPRM)
//* ----------------------------------------------------------------
[-admin_threads number] [-user_cache_size number[,fixed]]
[-meta_cache_size number[,fixed]] [-log_cache_size number[,fixed]]
[-sync_interval number] [-vnode_cache_size number] [-nbs {on|off}]
[-fsfull threshold,increment] [-aggrfull threshold,increment]
[-trace_dsn PDSE_dataset_name] [-tran_cache_size number]
[-msg_output_dsn Seq_dataset_name] [-user_cache_readahead {on|off}]
[-metaback_cache_size number[,fixed]] [-fsgrow increment,times]
[-aggrgrow {on|off}] [-romount_recovery {on|off}]
[-convert_auditfid {on|off}] [-client_reply_storage storage size]
[-file_threads number] [-client_cache_size cache size[,fixed]]
[-token_cache_size cache size] [-sysplex_filesys_sharemode
{rwshare|norwshare}] [-system system name] [-level] [-help]
Change the value of zFS configuration (IOEFSPRM)
options in memory
zfsadm config -------- option ---------
ioezadm -------- option --------

352

ABCs of z/OS System Programming: Volume 9
Authorization required
The issuer must have READ authority to the data set that contains the
IOEFSPRM
file and must
be root or have READ authority to the SUPERUSER.FILESYS.PFSCTL profile in the
UNIXPRIV class.
The ioezadm command
The
zfsadm
command is executed from the z/OS UNIX shell. It can also be invoked from
TSO/E by using the program name IOEZADM or as a batch job by using PGM=IOEZADM.
For a batch job, the
zfsadm
options are specified in the EXEC PARM as a single
subparameter (a single character string enclosed in apostrophes with no commas separating
the options). You cannot put the ending apostrophe in column 72. If it needs one, go to the
next line, use a continuation character in column 72 (continuing in column 16 with the ending
apostrophe on the second line). Remember that a JCL EXEC PARM is limited to 100
characters.

Chapter 7. zFS file systems
353
7.29 Defining IOEFSPRM options
Figure 7-29 IOEFSPRM file options and defaults
IOEFSPRM file options
The best and only reasonable option is to define IOEFSPRM as a member of a PDS data set.
This allows updates while the zFS PFS is active.
Figure 7-29 lists the processing options for the zFS PFS. There is no mandatory information
in this file, therefore it is not required. The options all have defaults. Aggregates can all be
compatibility mode aggregates (which do not need definitions). However, if you need to
specify any options (for tuning purposes, for example), you need to have an IOEFSPRM file.
The location of the IOEFSPRM file is specified by the IOEZPRM DD statement in the ZFS
PROC. The IOEFSPRM file is normally a PDS member, so the IOEZPRM DD might look like
the following:
//IOEZPRM DD DSN=SYS4.PVT.PARMLIB(IOEFSPRM),DISP=SHR
New parameters with z/OS V1R11
The new parameters that are added with z/OS V1R11 are as follows:

sysplex = {on | off} - Can be set on if SYSPLEX(YES) in BPXPRMxx

token_cache_size = vnode_cache_size x 2

file_threads = 40

client_cache_size=128M

client_reply_storage = 40M
[-admin_threads number] [-user_cache_size number[,fixed]]
[-meta_cache_size number[,fixed]] [-log_cache_size
number[,fixed]] [-sync_interval number] [-vnode_cache_size
number] [-nbs {on|off}] [-fsfull threshold,increment]
[-aggrfull threshold,increment] [-trace_dsn
PDSE_dataset_name] [-tran_cache_size number]
[-msg_output_dsn Seq_dataset_name] [-user_cache_readahead
{on|off}] [-metaback_cache_size number[,fixed]] [-fsgrow
increment,times] [-aggrgrow {on|off}] [-romount_recovery
{on|off}] [-convert
_
auditfid {on|off}] [-client
_
reply
_
storage
storage size] [-file_threads number] [-client_cache_size
cache size[,fixed]] [-token_cache_size cache size]
[-sysplex_filesys_sharemode {rwshare|norwshare}]
[-system system name] [-level] [-help]
A IOEFSPRM file and parameters in the file are optional
Parameter file is referenced by the
DDNAME=IOEZPRM statement in PROC JCL for zFS

354

ABCs of z/OS System Programming: Volume 9
7.30 Logical PARMLIB support
Figure 7-30 Logical PARMLIB support
IOEPRMxx PARMLIB member
As an alternative to the IOEZPRM DDNAME specification, the IOEFSPRM member can be
specified as a true PARMLIB member. In this case, the member has the name IOEPRMxx,
where xx is specified in the PARMLIB member list.
When the
IOEFSPRM
file is specified in the IOEZPRM DD statement of the ZFS PROC, there
can only be one
IOEFSPRM
file for each member of a sysplex.
Using PARMLIB, zFS configuration options can be specified in a list of configuration parm
files. This allows an installation to specify configuration options that should be common
among all members of the sysplex (for example, adm_threads) in a shared IOEPRMxx
member; and configuration options that should be system-specific (for example, define_aggr)
in a separate, system-specific IOEPRMxx member. If a configuration option is specified more
than once, the first one found is taken.
A logical parmlib search is used
Member names are in the form IOEPRMxx
Multiple members can be specified
Allows installation to have a common parmlib member
that is shared among members of the sysplex but also
have an additional member that is unique
The logical parmlib concatination is a set of up to 10 partitioned
data sets defined by PARMLIB statements in the LOADxx
member of SYSn.IPLPARM or SYS1.PARMLIB

Chapter 7. zFS file systems
355
7.31 Specifying PARMLIB members
Figure 7-31 Examples of PARMLIB members
PARMLIB member examples
The IOEPRMxx files are contained in the logical PARMLIB concatenation, which is a set of up
to 10 partitioned data sets defined by PARMLIB statements in the LOADxx member of either
SYSn.IPLPARM or SYS1.PARMLIB. The logical PARMLIB concatenation contains zFS
IOEPRMyy members, which contain zFS configuration statements. Columns 73-80 are
ignored in the IOEPRM
yy
member. The
yy
is specified in the PARM option of the
FILESYSTYPE statement for ZFS (in the BPXPRMxx). The PARM string is case sensitive.
You must enter the string in upper case. For example:
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(01,02,03)')
Up to 32 member suffixes can be specified. You can also use any system symbol that
resolves to two characters. For example:
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(01,&SYSCLONE.)')
If &SYSCLONE.=AB, this specifies that PARMLIB member IOEPRMAB should be searched
after PARMLIB member IOEPRM01. IOEPRM01 could contain common configuration options
and IOEPRMAB could contain configuration options that are specific to system AB. If a
PARMLIB member is not found, the search for the configuration option continues with the next
PARMLIB member.
List of member (suffixes) is specified in the
FILESYSTYPE statement for ZFS in a BPXPRMxx
member
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(01,02,03)')
FILESYSTYPE TYPE(ZFS) ENTRYPOINT(IOEFSCM)
ASNAME(ZFS,'SUB=MSTR')
PARM('PRM=(AA,&SYSCLONE.)')

356

ABCs of z/OS System Programming: Volume 9
PARMLIB search
If no PRM suffix list is specified (and no IOEZPRM DD is specified in the ZFS PROC), then
member IOEPRM00 is read. PARMLIB support is only used when the IOEZPRM DD
statement is not specified in the ZFS PROC. When an IOEZPRM DD is specified in the ZFS
PROC, the single IOEFSPRM file specified in the DD is used, as previously.
Coexistence
Coexistence between IOEFSPRM in the procedure and IOEPRMxx when using the
FILESYSTYPE PARM PRM specification is ignored in previous releases. Therefore, if you
specify it in a BPXPRMxx member that is shared between this release and previous releases
(and no IOEZPRM DD is specified in the ZFS PROC), the PRM specification will be honored
in this release but will be ignored in previous releases. This means that the IOEPRMxx
members will be searched for zFS configuration parameters in this release, but defaults will
be taken in previous releases. Also, if the ZFS FILESYSTYPE PARM has no PRM
specification (and no IOEZPRM DD is specified in the ZFS PROC), then ZFS will attempt to
use the IOEPRM00 member in this release, but will take defaults in the previous releases. If
IOEPRM00 is not found, defaults are used.

Chapter 7. zFS file systems
357
7.32 Add a volume to a zFS aggregate
Figure 7-32 Adding a volume to a zFS aggregate
Add space to a zFS aggregate
To add a candidate volume to a zFS aggregate, use the IDCAMS utility ALTER command with
the ADDVOLUMES parameter. The sample job shown in Figure 7-32 adds two volumes to the
(SMS-managed) OMVS.ROGERS.TEST zFS aggregate.
In this case, DFSMS is choosing the particular candidate volumes. If you want to specify the
volumes, use their volume serials in place of the asterisks. See z
/OS DFSMS: Access
Method Services for Catalogs
, SC26-7394 for additional information on IDCAMS ALTER
ADDVOLUMES. DFSMS states that if an ALTER ADDVOLUMES is done to a data set already
opened and allocated, the data set must be closed, unallocated, reallocated, and reopened
before VSAM can extend onto the newly-added candidate volume.
For zFS, this means that if the zFS aggregate is already attached when the ALTER
ADDVOLUMES is done, it must be detached and attached again before zFS can extend to
the newly-added candidate volume(s). Compatibility mode aggregates must be UNMOUNTed
and MOUNTed again (since that is when they are detached and attached). If a backup file
system (created by the clone operation) is mounted, it must also be unmounted when the
read-write file system is unmounted. Otherwise, the aggregate will not be detached.
//ROGERSA JOB (ACCTNO),'SYSPROG',CLASS=A,
// MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//STEP01 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ALTER OMVS.ROGERS.TEST.DATA
-
ADDVOLUMES(* *)
/*
Use the IDCAMS utility ALTER command
With the ADDVOLUMES parameter
Add two volumes to aggregate -
OMVS.ROGERS.TEST

358

ABCs of z/OS System Programming: Volume 9
7.33 zFS migration considerations
Figure 7-33 zFS migration from HFS considerations
zFS migration considerations
zFS can be used for all levels of the z/OS UNIX System Services hierarchy (including the root
file system) when all members are at the z/OS V1R7 level. Because zFS has higher
performance characteristics than HFS and is the strategic file system, HFS may no longer be
supported in future releases and you will have to migrate the remaining HFS file systems to
zFS.
HFS may no longer be supported in future releases. At that time, you will have to migrate the
remaining HFS file systems to zFS.
Beginning with z/OS V1R7, you can use the file system type HFS as a generic file system
type that can mean either HFS or zFS. Mount processing will direct the mount to the correct
PFS.
Migrate from HFS file systems to zFS file systems
(recommended) - because zFS is planned to become
a requirement in a future release
zFS is the strategic file system
HFS may no longer be supported in future releases
and you will have to migrate the remaining HFS file
systems to zFS
HFS and zFS file system types in mount statements
and command operands are now generic file system
types that can mean either HFS or zFS
Based on the data set type, the system will determine
which is appropriate

Chapter 7. zFS file systems
359
7.34 HFS/zFS as generic file system type
Figure 7-34 Using HFS/zFS as a generic file system type
Generic file system type
HFS is now a generic file system type that can be HFS or zFS.
Mount processing will recognize a substitutable token in the file system name if the file
system type is HFS and substitute zFS for HFS as appropriate, based on data set existence.
Mount processing will first search for a data set matching the file system name. If the data set
is not an HFS data set and zFS has been started, the file system type is changed to ZFS and
the mount proceeds to zFS. If the data set was not found, the mount proceeds to zFS
(assuming zFS is started). If zFS is not started, the type is not changed and the mount
proceeds to HFS.
Note:
If the zFS data set names are to be the same as the HFS data set names, it is likely
that scripts or policies that are used to mount file systems would not need to be changed.
They can be used for either HFS or ZFS
Mount processing first searches for a data set
matching the file system name
If the data set is not an HFS data set and zFS has
been started, the filesystem type is changed to ZFS
and the mount proceeds to zFS
If the data set was not found, the mount proceeds to
zFS (assuming zFS is started)
If zFS is not started, the type is not changed and the
mount proceeds to HFS

360

ABCs of z/OS System Programming: Volume 9
7.35 Migration considerations
Figure 7-35 Migration considerations for zFS file systems
Migration considerations
Several considerations are in order regarding file system naming conventions and very large
VSAM linear data sets.
File system names
Given that during migration there are now two data sets, it is likely that some installations may
want to have a different naming standard for their zFS data sets than their HFS data sets if
the file type is part of the file name. It is also likely that they prefer keeping the names just as
they are. If the installation chooses to have a new naming convention, then any mount policy
or mount scripts (including from PARMLIB) have to be altered to mount the correct file system
name.
If you decide to have a new naming convention, then you must change mount policies and
mount scripts (including from the BPXPRMxx PARMLIB) to mount the correct file system
name. You will have to look at your automount policies very carefully. You may need to modify
the generic entry, migrate all file systems at one time, or add specific entries for each
migrated file system.
zFS file systems
zFS file systems that will span volumes must be preallocated prior to invoking the tool.
zFS file systems that are greater than 4 GB (about 4825 cylinders of a 3390) must be defined
with a data class that includes extended addressability. zFS file systems cannot be striped.
Often the file system type is used in a portion of the
file system name
With the change to a file type of zFS, PARMLIB
members, mount scripts and policies are affected as
well as the file system name
You may prefer to keep the current file system name
and then no changes to mount scripts
Migration tool will help with handling these changes
zFS file systems that span volumes must be
preallocated prior to invoking the tool
zFS file systems that are greater than 4 GB must be
defined with a data class that includes extended
addressability
zFS file systems cannot be striped

Chapter 7. zFS file systems
361
7.36 Migration tool
Figure 7-36 Migration tool with z/OS V1R7
Migration tool from HFS to zFS
To assist with the migration, a new tool, BPXWH2Z, is provided in the form of an ISPF dialog.
It is expected that this tool will have a limited life both within the product stream and especially
for any specific customer since it is only there for HFS to zFS migration. For this reason, for
service purposes, it should be handled similar to the way samples are handled.
A panel interface allows you to alter the space allocation, placement, SMS classes, and data
set names. The actual migration could run either in the TSO foreground or UNIX background.
To understand the panels, there is help information with sample information filled in. The
panel syntax is explained in the help information.
This tool uses
pax
to perform the actual copy operation. New functions are in
pax
copy mode
to ensure the migration tool performs the conversion.
Use a migration tool to handle many details needed
for the migration of HFS file systems to zFS,
including the actual copy operation - z/OS V1R7
Migration tool - BPXWH2Z
An ISPF based tool for migration from an HFS file
system to zFS
It has a panel interface that enables you to alter the
space allocation, placement, SMS classes, and data
set names
A HELP panel is provided
Uses a new pax utility for copy

362

ABCs of z/OS System Programming: Volume 9
7.37 Migration checks file system type
Figure 7-37 Migration placeholder for file system names
Migration placeholder for file system names
Support is added in z/OS V1R7 to provide the capability to specify a file system name with
substitution place holders. The place holder is /// and represents the string HFS or ZFS as
appropriate, if the file system type is specified as HFS.
/// is selected because it is the same number of characters as ZFS and HFS, / is not a
character that is processed by the shell, and / is not used in a data set name. Where /// is
used, mount processing will first substitute ZFS and check to see if the data set exists and is
not an HFS data set. If this is the case it proceeds with that name and directs the mount to
ZFS. Otherwise, mount processing substitutes HFS in the name and checks the status of that
data set name. If that data set exists and is not an HFS, it directs the mount to ZFS;
otherwise, it directs the mount to HFS.
Since this is a migration scenario, mount processing first checks for the ZFS file system type
under the assumption that if that data set exists, the migration has been done. In order to
revert back to using the HFS, that data set must be renamed or removed.
MOUNT FILESYSTEM('ZOSR17.MAN.///')
TYPE(HFS)
MODE(READ)
MOUNTPOINT('/usr/man')
For migration scenario, mount processing first checks for
ZFS; if that data set exists, migration has been done
To revert back to using HFS, that data set must be
renamed or removed
A new place holder, ///, is created to represent the string
HFS or ZFS
If type is HFS, as shown in the following mount statement
or mount command
Mount processing first substitutes ZFS to see if data set
exists - If no, HFS is used to see if the data set exists
Mount is directed to zFS or HFS

Chapter 7. zFS file systems
363
7.38 Migration tool enhancements with APAR OA18196
Figure 7-38 Migration tool enhancements
Migration tool implementation
Before this APAR was introduced, the migration tool BPXWH2Z had the following
requirements that are fixed by this APAR:

Support needed to migrate multi-volume HFS file systems to multi-volume zFS file
systems. The tool currently requires the zFS file systems to be preallocated for
multi-volume HFS file system migration.

The tool currently tries to convert an HFS file system that is too small for a zFS file system
and fails on zFS allocation. The minimum supported size for zFS file systems is 6 tracks.
The tool does not validate the minimum zFS allocation.

When the BPXWH2Z tool is invoked via the ISPF batch job, all the HFS file system names
that start with the input HFS file system name are included for migration. There is no way
to include or exclude the HFS file systems from the migration list.
Migration tool enhancements
The BPXWH2Z tool is enhanced to provide the following new functions:

Migration of SMS-managed multi-volume HFS file systems to SMS-managed multi-volume
zFS file systems. If your HFS file system is multi-volume, then make sure that it is
SMS-managed before you use this tool to do the migration. Your zFS will be allocated
Note:
APAR OA18196 applies to z/OS V1R7 and z/OS V1R8.
New Function - BPXWH2Z HFS to ZFS Migration Utility
Enhancements are as follows:
1) Multi-volume conversion support
Pre-allocation of a multi-volume zFS no longer required
2) Minimum zFS allocation verification
An HFS file system that is too small for zFS file system and
fails on zFS allocation - minimum is 6 tracks
3) Panel usability enhancements
New zFS name can be changed on change allocation panel
4) New option for exact HFS name match
New -e option on BPXWH2Z call

364

ABCs of z/OS System Programming: Volume 9
based upon the allocation attributes of the HFS and you will have an opportunity to modify
these attributes via the Change Allocation Attributes panel.

The tool ensures that the zFS file system allocation is no less than the minimum allocation
supported by the zFS file system.

The Data Set List panel in the BPXWH2Z tool is enhanced to display the “final zFS” field.
If you select an HFS data set with character A to change the attributes, you will be able to
modify the final zFS name. The Change Allocation Attributes panel is also enhanced to
display and modify the Final zFS name field. When a substitution string is specified, the
Data Set List panel will be primed such that the HFS will be saved as it is and the final zFS
name will be changed according to the specified substitution string. You have the option to
change the saved HFS name, the final zFS name as well as the allocation attributes by
specifying the character A in front of the HFS name in the Data Set List panel and
modifying it in the Change Allocation Attributes panel.
3.A new option, -e, is added to the BPXWH2Z tool to exactly match the HFS file system
name. When the new option is used during the invocation of the BPXWH2Z tool, it will
match the input HFS file system name as exact name and will not consider it as a pattern
string (default behavior).
The new zFS data set is now being allocated under a user's authority. Therefore, the user
must have authority to create, rename, and delete the new zFS data sets. Otherwise, the
BPXWH2Z tool will fail.
When a zFS data set is preallocated, the Initial zFS name field and the Final zFS name
field in the Change Allocation Attributes panel must be the same.

Chapter 7. zFS file systems
365
7.39 REXX exec - BPXWH2Z
Figure 7-39 Using the BPXWH2Z migration tool
Using the migration tool
From the ISPF Option 6 command line, enter
bpxwh2z
to begin to use the migration tool. The
tool is a REXX exec that is located in library SYS1.SBPXEXEC, which is concatenated to
SYSPROC.
Command line options for bpxwh2z
The first argument can specify option flags. The option flags are preceded by a dash (-),
followed immediately by the flags. The flags are as follows:
-v
Additional messages are issued at various points in processing.
-c
Summary information goes to a file when background selected; if this is not specified,
summary information goes to the console.
Specify the line options as follows:
bpxwh2z -v or bpxwh2z -c or bpxwh2z -e or bpxwh2z -vce
You can specify any combination of -v, -c, and -e.
The REXX is located in library SYS1.SBPXEXEC
which is concatenated to SYSPROC
ISPF Option 6 command line, Enter bpxwh2z
Command line flag options:
-v Additional messages are issued at various points
in processing
-c Summary information goes to a file when
background (bg) is selected once you are in the
application. If this is not specified, summary
information goes to the console
bpxwh2z -c - bpxwh2z -v - bpxwh2z -e
bpxwh2z -cve

366

ABCs of z/OS System Programming: Volume 9
7.40 BPXWH2Z panels
Figure 7-40 Using BPXWH2Z panels
Using BPXWH2Z panels
If the HFS file system is mounted, either unmount it or switch it to read-only mode. The
migration switches it to R/O mode if not done manually.
If the file system is not mounted, the tool makes a directory for it and mounts it in R/O mode.
The tool creates a temporary directory for the zFS file system in /tmp for the mountpoint and
deletes it when migration is complete).
Size of HFS being migrated
The tool checks the allocation attributes of the HFS file system. It then defines a new zFS file
system with appropriate allocation attributes, as follows:

The tool defaults these to the same attributes as the HFS file system if its utilization is
below about 75% full, otherwise it adds about 10% to the new zFS if it’s below 90%.

The tool adds 20% to the zFS if the HFS is above 90% full.
It is difficult to determine the exact size necessary for a zFS file system to contain all of the
data within an HFS file system. Depending on the number of files, directories, ACLs,
symlinks, and file sizes, zFS can consume either more or less space than HFS. zFS also has
a log in the aggregate. For general purpose file systems, it appears that they consume about
the same amount of space.
Panels allow for customization of space allocation,
placement SMS class and data set name
Tool makes the zFS a little larger if it sees the HFS is
near capacity by:
10% if it is over 75% full and under 90% and 20% if over
This is a precaution since zFS is a logging file system and
includes the log in the aggregate
If unmounted it creates a mountpoint in /tmp and mounts
it read only for the migration, then deletes the mountpoint
If there are file systems mounted below the migrating file
system, they are unmounted for migration
The mount points are created in the new file system and
when complete, the file systems are remounted

Chapter 7. zFS file systems
367
7.41 Space allocations - HFS versus zFS
Figure 7-41 Space allocation between HFS and zFS
Space allocations - HFS versus zFS
Define zFS aggregates by default to be approximately the same size as the HFS. The new
allocation size can be increased or decreased.
Depending on the number of files, directories, ACLs, symlinks, and file sizes, zFS can
consume either more or less space than HFS. zFS also has a log in the aggregate. For
general purpose file systems, it appears that they consume about the same amount of space.
Assistance with space and other data set management issues is a consideration during the
migration. This includes having the DASD space available to perform the migrations. You may
need to change automatic class selection (ACS) routines to direct allocations to desired
storage classes with the right attributes, and security changes that may be necessary for new
data set profiles.
It is difficult to determine the exact size necessary
for a zFS file system to contain all of the data within
an HFS file system
Depending on number of files, directories, ACLs,
symlinks, and file sizes, zFS can consume either
more or less space than HFS
zFS also has a log in the aggregate
For general purpose file systems, it appears that
they consume about the same amount of space
Two data sets will exist during the migration, so
plan for space for two file systems about same size

368

ABCs of z/OS System Programming: Volume 9
7.42 Using the migration tool
Figure 7-42 Using the migration tool first panel
Migration tool first panel
The utility can be run with no arguments; it will prompt for an HFS file system name. You can
also specify one or more file system names as an argument. The names can be simple
names or patterns that you might use for the ISPF data set list panel. However, an asterisk (*)
must be specified at the end to find data sets with additional characters at the end of the
name.
Using the tool
To use the migration tool, enter
bpxhw2x
on the ISPF Option 6 command line; the panel shown
in Figure 7-42 is displayed.
To migrate a file system, specify the file system name on the panel as shown:
ROGERS.TEST10.HFS
Then press Enter to display the next panel.
From ISPF Option 6, Enter:
bpxwh2z
When the first panel is displayed
Enter HFS data set name to migrate - Then hit Enter

Chapter 7. zFS file systems
369
7.43 BPXWH2Z panels
Figure 7-43 Using BPXWH2Z panels
Using BPXWH2Z panels
By default, the panels are initialized such that your HFS data set will be renamed with a .SAV
suffix and the zFS data set will be renamed to the original HFS name.
You can preallocate the zFS file system or specify a character substitution string. If you
specify a substitution string, the panel will be primed such that the data sets will not be
renamed. The substitution string is specified as the first argument on the command line as:
/fromstring/tostring/
For example, if your data set is OMVS.HFS.WJS and you want your zFS data set to be
named OMVS.DB2.HFS you can specify a command argument, as follows:
/hfs/zfs/ omvs.db2.hfs
The resulting new zFS data set name will be OMVS.DB2.ZFS.
Attention:
Be careful—all strings matching the
fromstring
in the data set name will be
replaced.
A substitution string can be specified as the first
argument on the command line as follows:
/fromstring /tostring/ datasetname
For example, if your data set is OMVS.DB2.HFS
and you want your zFS data set to be named
OMVS.DB2.ZFS, you can specify the following:
bpxwh2z -cv /hfs/zfs/ omvs.db2.hfs

370

ABCs of z/OS System Programming: Volume 9
7.44 Using SMS if required
Figure 7-44 Specify SMS classes and volume if required
Using SMS classes
There are panel interfaces that allow the user to alter the space allocation, placement, SMS
classes, and data set names.
With this panel, you can specify either a default volume or SMS classes to determine where
the new zFS data set will be placed.
Otherwise, the new zFS will be placed to the same place as the HFS data set.
When you press Enter, the panel shown in Figure 7-45 is displayed.
Alter SMS classes and volume if required
Then hit the Enter key to see the allocations

Chapter 7. zFS file systems
371
7.45 Migrate in the foreground
Figure 7-45 Migrating the HFS data set in the foreground
Migrate in the foreground
This panel displays the HFS and zFS allocations. You may alter these allocations for the new
zFS data set. To begin the migration, enter the command FG or BG to run the migration in the
foreground or background. If it is run in the background, the tool will keep a standard output
log and also a summary log. The prefix for the pathnames is displayed. The commands D or
A may be specified for each HFS data set to delete items from the migration list or to alter
allocation parameters for the items.
Each table entry shows the data set names that will be used, current HFS space utilization
and space allocation, and allocation parameters that will be used to create the zFS file
system. Select a row to alter the allocation attributes or data set names. Rows can also be
deleted. Additional rows cannot be added.
The commands that can be used on this panel are as follows:
D
To delete items from this migration list.
A
To alter allocation parameters for the items, enter an
A
on the action character line to
alter the space allocation. A new panel is displayed and is shown in Figure 7-49 on
page 375.
FG
To begin migration in the TSO/E foreground, enter FG on the command line.
BG
To begin migration in the UNIX background, enter BG on the command line.
When you press Enter on this panel using the current specifications, the messages shown
are issued on a blank panel.
A - Alter allocation
Migrating ROGERS.TEST10.HFS 14:14:40
creating zFS ROGERS.TEST10.HFS.TMP
copying ROGERS.TEST10.HFS to ROGERS.TEST10.HFS.TMP Blocks to copy: 5
IDC0531I ENTRY ROGERS.TEST10.HFS.TMP ALTERED
IDC0531I ENTRY ROGERS.TEST10.HFS.TMP.DATA ALTERED
Migration complete for ROGERS.TEST10.HFS 14:14:49
***
fg

372

ABCs of z/OS System Programming: Volume 9
7.46 Migration steps
Figure 7-46 Migration steps
Migration steps
Following are the steps taken by the migration tool to migrate HFS data sets to zFS data sets:
1.If the HFS file system is mounted, either unmount it or switch it to read-only mode. The
tool will switch it to R/O mode.
2.If the file system is not mounted, make a directory for it and mount it in R/O mode. The tool
will create a temporary directory in /tmp for the mountpoint and delete it when migration is
complete.
3.Create a temporary directory for the zFS file system. The tool will create a temporary
directory in /tmp for the mountpoint and delete it when migration is complete.
4.Check the allocation attributes for the HFS file system. See “Size of HFS being migrated”
on page 366.
If the HFS file system is mounted, either unmount it or
switch it to read-only mode
The migration tool switches it to R/O
If the file system is not mounted make a directory for it
and mount it in R/O mode
The migration tool creates a temporary directory in /tmp
for the mountpoint and deletes it when the migration is
complete
Create a temporary directory for the zFS file system
The migration tool creates a temporary directory in /tmp
for the mountpoint and deletes it when the migration is
complete
Check the allocation attributes of the HFS file system

Chapter 7. zFS file systems
373
7.47 Migration steps
Figure 7-47 Migration steps continued
Migration steps continued
5.Define a new zFS file system with appropriate allocation attributes.
6.Mount the zFS file system on its temporary mountpoint.
7.Use the
pax
utility to copy the HFS contents to the zFS by entering the shell and then
change the directory to the HFS mountpoint and run the new
pax
utility. The
pax
command
is as follows:
pax -rw -X -E . /tmp/zfsmountpoint
The previous
pax -X
option caused
pax
to write only those files that are on the same
device as the parent directory. Invoking this option causes active mountpoints to be
ignored when
pax
is in copy mode. However, in z/OS V1R7, the new
pax
option causes an
empty directory to be created on the target for these mountpoints.
pax
reads the specified path name and copies it to the target directory. The target directory
must already exist and you must have write access to it. If a path name is a directory,
pax

copies all the files and subdirectories in that directory, as well as the directory itself, to the
target directory.
8.If the HFS contains active mountpoints, do an
mkdir
for each of these in the zFS file
system and set directory attributes as required. Set attributes for the zFS based on the
HFS that was copied. Note that this must include all extended attributes, ACLs, owner,
group, code page, and mode bits.
Define a new zFS file system with the appropriate
allocation attributes
Mount the zFS file system on its temporary
mountpoint (a pre-existing zFS cannot already be
mounted)
Use the pax utility to copy the HFS contents to the
zFS by entering the shell, change directory to the HFS
mountpoint, and run the pax utility - The pax
command you can use is:
pax -rw -X -E . /tmp/zfsmountpoint
If the HFS contains active mountpoints, do an mkdir
for each of these in the zFS file system and set
directory attributes as required

374

ABCs of z/OS System Programming: Volume 9
7.48 Migration steps continued
Figure 7-48 Migration steps continued
Migration steps continued
9.Unmount the zFS file system.
10.Unmount the HFS file system. Note that if it contains active mountpoints, those file
systems and any hierarchy below them must be unmounted first.
11.Remove any temporary directories used as mountpoints.
12.Rename the data sets as appropriate and ensure that all mount scripts and policies have
been updated as needed. The migration tool will not modify or search for any type of
mount scripts or policies.
13.If the HFS file system was originally mounted, mount the zFS file system in that same
location along with any hierarchy that also had to be unmounted to unmount that HFS.
Unmount the zFS file system
Unmount the HFS file system
Remove any temporary directories used as
mountpoints
Rename the data sets as appropriate and ensure all
mount scripts and policies have been updated as
needed
The migration tool does not modify or search for any
type of mount scripts or policies
If the HFS file system was originally mounted, mount
the zFS file system in that same location along with
any hierarchy that also had to be unmounted to
unmount the HFS

Chapter 7. zFS file systems
375
7.49 Alter allocation parameters panel
Figure 7-49 Panel to alter allocations of new zFS
Alter allocation parameters panel
This panel allows you to change the allocation options that were initially determined by the
migration tool. The values shown in the figure were filled in by the migration tool. You may
change these parameters by overtyping the shown specifications.
Migrating to a multivolume zFS
If your HFS is multivolume, you no longer must preallocate your zFS in order to have similar
attributes and multivolume with APAR OA18196. This panel is shown when you specify A for
alter allocation on the panel shown in Figure 7-45 on page 371.
Alter allocations of the zFS data set with APAR OA18196
This panel is required if the zFS is going to be multi-volume
multi-volume
change zFS
name

376

ABCs of z/OS System Programming: Volume 9
7.50 APAR OA18196 - Exact data set match
Figure 7-50 Using the -e option to select an exact data set match
Exact data set match (-e) option
Notice that the migration tool, BPXWH2Z, can be used from TSO ready, as shown in
Figure 7-50. Using the -e option indicates that when selecting the HFS file system to migrate,
the data set name must be an exact match.
The name specified to migrate is OMVS.HERING.HFS.TEST. As shown in the example, data
set name OMVS.HERING.HFS.TEST is migrated and data set name
OMVS.HERING.HFS.TEST.FS2, which is almost an exact match, is not migrated.
Note:
In the example, note that the HLQ, OMVS, indicates that the data set is
SMS-managed.
The new option (-e) is available with APAR OA18196 to specify the HFS data set
name exactly. In the example,two HFSes are involved and just that one exactly
matching is selected:
READY
ISPSTART CMD(BPXWH2Z -eVC OMVS.HERING.HFS.TEST)
Not running UID=0 - attempting to set UID=0
-getting ds list for OMVS.HERING.HFS.TEST
Skipping matching patterns of input data set name OMVS.HERING.HFS.TEST.FS2
-getting ds info for OMVS.HERING.HFS.TEST
-getting ds info for OMVS.HERING.HFS.TEST.SAV
-getting ds info for OMVS.HERING.HFS.TEST.TMP
Migrating OMVS.HERING.HFS.TEST 15:50:18
creating zFS OMVS.HERING.HFS.TEST.TMP
copying OMVS.HERING.HFS.TEST to OMVS.HERING.HFS.TEST.TMP Blocks to copy: 220
- cd /tmp/bpxwh2z.HERING.15:50:18.hfs; /bin/pax -rw -peW -XCM .
/tmp/bpxwh2z.HERING.15:50:18.zfs
IDC0531I ENTRY OMVS.HERING.HFS.TEST.TMP ALTERED
IDC0531I ENTRY OMVS.HERING.HFS.TEST.TMP.DATA ALTERED
Migration complete for OMVS.HERING.HFS.TEST 15:50:27
HERING.HERIJOB.JOB04075.D0000103.? was preallocated (no free was done).
READY
END

Chapter 7. zFS file systems
377
7.51 Migrating a list of data sets
Figure 7-51 A list of data sets to migrate
Migrating a list of data sets
When you have a list of data sets to migrate that have very similar names, you can use a
wildcard, * , to specify the list, as shown in the figure. After getting the list of data sets to
migrate, the migration tool obtains data set information on each data set. The tool does not
migrate the following types of data sets:

That do not exist

Are HSM migrated

Are not HFS data sets
The resulting data set list is presented in a table, shown in Figure 7-52 on page 378.
OMVS.ROGERS.TEST1
OMVS.ROGERS.TEST2
OMVS.ROGERS.TEST3
OMVS.ROGERS.TEST4
OMVS.ROGERS.TEST5
OMVS.ROGERS.TEST6
OMVS.ROGERS.TEST7
List of data sets to migrate:

378

ABCs of z/OS System Programming: Volume 9
7.52 Data set list displayed
Figure 7-52 List of data sets displayed using a data set name with a wildcard
List of data sets
Use your normal up/down to scroll through the list. Each table entry shows the following:

Data set names that will be used

Current HFS space utilization

Space allocation and allocation parameters
These are used to create the zFS file system. Select a row to alter the allocation attributes or
data set names. Rows can also be deleted. Additional rows cannot be added.
To begin the migrations, enter the command FG or BG to run the migration in the foreground
or background. Note the copy process may take a long time. If this is run in the background,
the tool keeps a standard output log and also a summary log. The prefix for the pathnames is
displayed.
pax
is used to do the copy.
Use the HELP command for full usage information on this tool
Select items with D to delete items from this migration list
Select items with A to alter allocation parameters for the items
Enter command FG or BG to begin migration in foreground or UNIX background
------------------------------------------------------------------------------
_ HFS data set ..: OMVS.ROGERS.TEST Utilized: 62%
Save HFS as ..: OMVS.ROGERS.TEST.SAV
Initial zFS ..: OMVS.ROGERS.TEST.TMP Allocated: N
HFS space Primary : 25 Secondary: 5 Units ..: CYL
zFS space Primary : 25 Secondary: 5 Units ..: CYL
Dataclas : HFS Mgmtclas : HFS Storclas: OPENMVS
MOUNTED Volume : SBOX1F Vol count: 1
------------------------------------------------------------------------------
_ HFS data set ..: OMVS.ROGERS.TEST1 Utilized: 62%
Save HFS as ..: OMVS.ROGERS.TEST1.SAV
Initial zFS ..: OMVS.ROGERS.TEST1.TMP Allocated: N
HFS space Primary : 25 Secondary: 5 Units ..: CYL
zFS space Primary : 25 Secondary: 5 Units ..: CYL
Dataclas : HFS Mgmtclas : HFS Storclas: OPENMVS
Volume : SBOX1E Vol count: 1
--------------------------- DATA SET LIST ------------------------------------------------------------- Row 1 to 3 of 8
Command ===> fg

............................. more data sets ..............

Chapter 7. zFS file systems
379
7.53 Health Checker USS_HFS_DETECTED
Figure 7-53 Health Checker USS_HFS_DETECTED
Health Checker USS_HFS_DETECTED
Beginning with z/OS V1R5, HFS was no longer considered the strategic file system, and zFS
became the strategic file system. This check is used to highlight any HFS file systems that are
still being used so that they can be migrated to zFS. This new check verifies that all file
systems are mounted and issues an exception message if any HFS file systems are found.
The check only looks for HFS file systems that are owned on the system running the health
check.
This check runs any time an HFS file system is successfully mounted, unless overridden by
the RUN_ON_MOUNT=NO parameter. The check will also run any time a
F
BPXOINIT,FILESYS=REINIT
command is issued. The check does not run after the
F
OMVS,NEWROOT=xxx
command is issued.
This Health Checker routine is run with setting Low Severity once a day. The check will be
scheduled to run every 24 hours.
The check will run after a
F BPXOINIT,FILESYS=REINIT
command is issued. This can only be
on the system where the command is issued.
Check reason:
HFS file systems are no longer the strategic file systems. All HFS file
systems should be migrated to zFS. This check is a quick way to identify which HFS file
systems are mounted on the system and a reminder to migrate to zFS.
Beginning with z/OS V1R5, HFS was no longer
considered the strategic file system, and zFS became
the strategic file system
This new check verifies all file systems mounted and
issues an exception message if any HFS file systems
are found
This check runs any time an HFS file system is
successfully mounted
Unless overridden by the RUN_ON_MOUNT=NO
parameter
The check will also run any time a F
BPXOINIT,FILESYS=REINIT command is issued

380

ABCs of z/OS System Programming: Volume 9
7.54 Health Checker USS_HFS_DETECTED
Figure 7-54 Health Checker USS_HFS_DETECTED
Health Checker USS_HFS_DETECTED
Two parameters can be specified with this health check, as follows:
RUN_ON_MOUNT
This indicates wether the check should run after the successful mount
of an HFS file system. You can specify
YES
or
NO
.
DEFAULT:
RUN_ON_MOUNT=YES

HFS_LIST
You can specify a list of HFS file systems that you wish to ignore for
this check. A file system specified for this parameter will not cause the
check to issue an exception message. This parameter is limited to 23
file systems and by the health check limit of 256 characters for a
check’s parameters. Following is an example for specifying this
parameter:
HFS_LIST=(OMVS.TEST1.HFS,OMVS.TEST2.HFS)
Defining the health check
The following shows keywords you can use to override check values on either a POLICY
statement in the HZSPRMxx parmlib member or on a
MODIFY
command. This statement may
be copied and modified to override the check defaults:
UPDATE
CHECK(IBMUSS,USS_HFS_DETECTED)
SEVERITY(LOW)
INTERVAL(24:00)
This check is a quick way to identify which HFS file
systems are mounted on the system and a reminder to
migrate to zFS
This check is run with setting Low Severity once a day
The check is scheduled to run every 24 hours
The check has two parameters
RUN_ON_MOUNT - This indicates wether the check
should run after the successful mount of an HFS file
system - You can specify YES or NO
HFS_LIST - You can specify a list of HFS file systems
that you wish to ignore for this check - A file system
specified for this parameter will not cause the check to
issue an exception message.

Chapter 7. zFS file systems
381
PARM('RUN_ON_MOUNT=YES’)
DATE(20090427)
REASON('your reason for making the update ’)
USS_HFS_DETECTED messages
Three specific messages can be displayed with this health check. The messages are used as
follows:

BPXH067I is displayed in the health checker report when everything is okay. This means
that no mounted HFS file systems (except those in the HFS_LIST) have been found.
BPXH067I No HFS file systems are mounted.

BPXH069I is displayed in the health checker report if at least one HFS file system has
been found. The message is followed by the list of the mounted HFS file systems.
BPXH069I The following HFS file systems were found

BPXH068E is an exception message that is shown when errors are found. This means
that message BPXH069I is displayed as well. This exception message is listed in the
health checker report and is also displayed in the SYSLOG or OPERLOG.
BPXH068E One or more HFS file systems mounted.

382

ABCs of z/OS System Programming: Volume 9
7.55 Check with RUN_ON_MOUNT=YES
Figure 7-55 Check with RUN_ON_MOUNT=YES
Check with RUN_ON_MOUNT=YES
You can force running the check if
RUN_ON_MOUNT=YES
is specified, as shown in Figure 7-56.
Figure 7-56 Mounting an HFS file system
This results in the messages shown in Figure 7-57 going to the SYSLOG.
Figure 7-57 USS_HFS_DETECTED messages in the syslog
Excerpts of the corresponding Health Checker report output are displayed in Figure 7-58 on
page 383.
#> /usr/sbin/mount -f hering.testmnt.hfs test
#> df -v test | head -l3 | tail -1
HFS, Read/Write, Device:197, ACLS=Y
#>
HZS0001I CHECK(IBMUSS,USS_HFS_DETECTED): 235
BPXH068E One or more HFS file systems mounted.
#> /usr/sbin/mount -f hering.testmnt.hfs test
#> df -v test | head -l3 | tail -1
HFS, Read/Write, Device:197, ACLS=Y
HZS0001I CHECK(IBMUSS,USS_HFS_DETECTED): 235
BPXH068E One or more HFS file systems mounted.
BPXH069I The following HFS file systems were found:
----------------------------------------------------
HERING.TESTMNT.HFS
OMVS.SC74.VAR
OMVS.SC74.ETC
OMVS.DB2V8.UK05586.HFS
Response in SYSLOG to the mount
Part of the output in the SDSF health check display

Chapter 7. zFS file systems
383
Figure 7-58 USS_HFS_DETECTED Health Checker output
You can also explicitly run this health check, as shown in Figure 7-59.
Figure 7-59 Running health check USS_HFS_DETECTED using F HZSPROC
CHECK(IBMUSS,USS_HFS_DETECTED)
START TIME: 05/14/2010 15:41:10.052735
CHECK DATE: 20090427 CHECK SEVERITY: LOW
CHECK PARM: RUN_ON_MOUNT=YES
BPXH003I z/OS UNIX System Services was initialized using OMVS=(2A),
where each 2-character item is a BPXPRMxx suffix.
BPXH069I The following HFS file systems were found:
-----------------------------------------------------------
HERING.TESTMNT.HFS
OMVS.SC74.VAR
OMVS.SC74.ETC
OMVS.DB2V8.UK05586.HFS
* Low Severity Exception *
BPXH068E One or more HFS file systems mounted.
Explanation: The USS_HFS_DETECTED check found one or more active HFS
file systems on the current system.
System Action: The system continues processing.
...
(17 lines have been removed)
Check Reason: HFS file systems are no longer the strategic file
system. All HFS file systems should be migrated to zFS.
END TIME: 05/14/2010 15:41:10.053512 STATUS: EXCEPTION-LOW
F HZSPROC,RUN,CHECK=(IBMUSS,USS_HFS_DETECTED)
HZS0400I CHECK(IBMUSS,USS_HFS_DETECTED): 261
RUN PROCESSING HAS BEEN COMPLETED
HZS0001I CHECK(IBMUSS,USS_HFS_DETECTED): 262
BPXH068E One or more HFS file systems mounted.

384

ABCs of z/OS System Programming: Volume 9
7.56 Special characters in zFS aggregates
Figure 7-60 Special characters in file system names
Special characters
When specifying a new zFS file system name for the read-write file system, the name must be
unique within the sysplex (or system, if not in a sysplex).
With z/OS v1R7, the following characters can now be included in the name of a file system:

The at sign (@)

The number sign (#)

The dollar sign ($)
Previously, you could not have a zFS aggregate or
file system name that contained special characters
Support in z/OS V1R7 for special characters:
(@ # $)
# zfsadm define -aggr OMVS.HERING.@TEST.ZFS -volumes CFC000 -cyl 10
IOEZ00248E VSAM linear datase PLEX.JMS.AGGR#06.LDS0006 successfully
created.
# zfsadm format -aggr OMVS.HERING.@TEST.ZFS -compat
IOEZ00077I HFS-compatibility aggregate OMVS.HERING.@TEST.ZFS has been
successfully created

Chapter 7. zFS file systems
385
7.57 BPXMTEXT shell command
Figure 7-61 BPXMTEXT command change with z/OS V1R8
The BPXMTEXT command
BPXMTEXT displays the description and action text for a reason code returned from the
kernel. It supports reason codes from z/OS UNIX System Services, TCPIP, and now with
z/OS V1R8 for zFS. This command is intended as an aid for problem determination.
zFS reason codes
The reason_code is specified as 8 hexadecimal characters. Leading zeros may be omitted. If
no text is available for the reason code, a blank line is displayed. An argument that is not 1-8
hex digits will result in a usage message. This message will not be translated.
Distributed File Service reason code qualifiers are found in the range X'EF01' to X'EFFF' for
the zSeries File System (zFS).
Note:
In addition to displaying z/OS UNIX System Services reason codes, the z/OS UNIX
System Services shell command,
bpxmtext
, also displays the text and action of zFS reason
codes (EFxxnnnn) returned from the kernel. zFS does not use the xx part of the reason
code to display a module name. It always displays zFS. If you only know the nnnn part of
the zFS reason code, you can use EF00nnnn as the reason code. The date and time
returned with the zFS reason code matches the date and time returned from the zFS
kernel (displayed with operator command F ZFS,QUERY,LEVEL).
Previously, the bpxmtext command could not display
the meaning of a zFS reason codes
With z/OS V1R8, support is added to allow the
bpxmtext command to display the meaning of zFS
reason codes
ROGERS @ SC75:/u/rogers>bpxmtext EF096800

zFS Fri Jul 28 10:36:15 EDT 2006
Description: Mount for file system contain in multi-file system
aggregate is not allowed

A
ction: Using a release of z/OS prior to z/OS V1R8, attach the
aggregate, mount the file system and copy the file system data to a
compatibility mode aggregate.

386

ABCs of z/OS System Programming: Volume 9

© Copyright IBM Corp. 2011. All rights reserved.
387
Chapter 8.
File sharing in a sysplex
This chapter describes the hierarchical file system and how to customize it to your
requirements. zFS supports a shared file system capability in a multisystem sysplex
environment. The term shared file system environment refers to a sysplex that has a
BPXPRMxx specification of SYSPLEX(YES).
That is, users in a sysplex can access zFS data that is owned by another system in the
sysplex. For full sysplex support, zFS must be running on all systems in the sysplex in a
shared file system environment and all zFS file systems must be compatibility mode file
systems (that is, they cannot be file systems in multifile system aggregates). zFS multifile
system aggregates are not supported by automount.
8

388

ABCs of z/OS System Programming: Volume 9
8.1 Shared file systems in a sysplex
Figure 8-1 Shared sysplex environment file systems
File systems in a sysplex sharing mode
The three file systems in Figure 8-1 are as follows:
1.This is the sysplex root HFS data set, which was created by running the BPXISYSR job.
AUTOMOVE is the default and therefore is not specified, allowing another system to take
ownership of this file system when the owning system goes down.
2.This is the system-specific HFS data set, which was created by running the BPXISYSS
job. It must be mounted read-write. NOAUTOMOVE is specified because this file system is
system-specific and ownership of the file system should not move to another system
should the owning system go down. The MOUNTPOINT statement
/&SYSNAME.
will resolve
to /SC64 during PARMLIB processing. This mount point is created dynamically at system
initialization.
3.This is the old root HFS (version HFS). The recommendation is that it should be mounted
read-only. Its mount point is created dynamically and the name of the HFS is the value
specified on the VERSION statement in the BPXPRMxx member. AUTOMOVE is the
default and therefore is not specified, allowing another system to take ownership of this file
system when the owning system goes down.
Filesystem data sets
that exist in a Sysplex
(1). Sysplex root
- only 1 for all sharing systems
Contains directories and symlinks
Redirects addressing to other directories
(2). System-specific
Contains data specific to each system
Directories for /dev, /tmp, /var, /etc (mount points)
(3). Version
Contains system code and binaries(/bin, /usr, /lib, /opt,
and /samples)
Same function as the root in a non-sysplex system

Chapter 8. File sharing in a sysplex
389
8.2 Sysplex environment setup
Figure 8-2 Steps required to set up the shared sysplex environment
Defining the shared sysplex environment
Figure 8-2 shows the steps involved in defining the HFS data sets for sharing in read/write
mode in a sysplex environment. Some details are included in the following sections.
Sysplex root
The sysplex root is an HFS data set that is used as the sysplex-wide root. This HFS data set
must be mounted read-write and designated AUTOMOVE. Only one sysplex root is allowed
for all systems participating in a shared file system environment. The sysplex root is created
by invoking the BPXISYSR sample job in SYS1.SAMPLIB.
The sysplex root provides access to all directories. Each system in a sysplex can access
directories through the symbolic links that are provided. Essentially, the sysplex root provides
redirection to the appropriate directories, and it should be kept very stable; updates and
changes to the sysplex root should be made as infrequently as possible.
Version HFS
The version HFS is the IBM-supplied root HFS data set. To avoid confusion with the sysplex
root HFS data set, “root HFS” has been renamed to “version HFS.”
Note:
No files or code reside in the sysplex root data set. It consists of directories and
symbolic links only, and it is a small data set.
Create the Sysplex Root zFS
Create the system-specific zFS
Version HFS supplied by ServerPac
Create OMVS couple data set (CDS)
Define OMVS CDS to XCF
Additional recommendations
Use standard naming convention for zFS data sets
Do not use &SYSNAME as a Root zFS qualifier
Update BPXPRMxx member

390

ABCs of z/OS System Programming: Volume 9
System-specific HFS
Directories in the system-specific HFS data set are used as mount points, specifically for /etc,
/var, /tmp, and /dev. To create the system-specific HFS, run the BPXISYSS sample job in
SYS1.SAMPLIB on each participating system (in other words, you must run the sample job
separately for each system that will participate in a shared file system environment). IBM
recommends that the name of the system-specific data set contain the system name as one
of the qualifiers. This allows you to use the &SYSNAME. symbolic (defined in IEASYMxx) in
BPXPRMxx.
OMVS couple data set
The couple data set (CDS) contains the sysplex-wide mount table and information about all
participating systems, and all mounted file systems in the sysplex. To allocate and format a
CDS, customize and invoke the BPXISCDS sample job in SYS1.SAMPLIB. The job will create
two CDSs: one is the primary and the other is a backup that is referred to as the alternate. In
BPXISCDS, you also specify the number of mount records that are supported by the CDS.
Define CDS to XCF
Following is the sample JCL with comments to define the CDS to XCF.
BPXPRMxx member
You should also be aware that when SYSPLEX(YES) is specified in BPXPRMxx, each
FILESYSTYPE in use within the participating group must be defined for all systems
participating in a shared file system environment. The easiest way to accomplish this is to
create a single BPXPRMxx member that contains file system information for each system
participating in a shared file system environment.
//STEP10 EXEC PGM=IXCL1DSU
//STEPLIB DD DSN=SYS1.MIGLIB,DISP=SHR
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
/* Begin definition for OMVS couple data set(1) */
DEFINEDS SYSPLEX(PLEX1)
/* Name of the sysplex in which the OMVS couple data set is to be used
DSN(SYS1.OMVS.CDS01) VOLSER(3390x1)
/* The name and volume for the OMVS couple data set.
The utility will allocate a new data set by the name specified on the
volume specified.*/
MAXSYSTEMS(8)
/* Specifies the number of systems to be supported by the OMVS CDS.
Default = 8 */
NOCATALOG
/* Default is not to CATALOG */
DATA TYPE(BPXMCDS)
/* The type of data in the data set being created for OMVS.
BPXMCDS is the TYPE for OMVS. */
ITEM NAME(MOUNTS) NUMBER(500)
/* Specifies the number of MOUNTS that can be supported by OMVS.*/
Default = 100
Suggested minimum = 10
Suggested maximum = 35000 */
ITEM NAME(AMTRULES) NUMBER(50)
/* Specifies the number of automount rules that can be supported by OMV
Default = 50
Minimum = 50
Maximum = 1000 */

Chapter 8. File sharing in a sysplex
391
8.3 File systems in a shared sysplex
Figure 8-3 Shared sysplex HFS data sets
Sysplex root
No files or code reside in the sysplex root data set. It consists of directories and symbolic links
only, and it is a small data set. The sysplex root provides access to all directories. Each
system in a sysplex can access directories through the symbolic links that are provided.
Essentially, the sysplex root provides redirection to the appropriate directories, and it should
be kept very stable; updates and changes to the sysplex root should be made as infrequently
as possible. The presence of symbolic links is transparent to the user.
System-specific zFS
The system-specific zFS data set should be mounted read-write, and should be designated
NOAUTOMOVE. /etc, /var, /tmp, and /dev should also be mounted NOAUTOMOVE. In
addition, IBM recommends that the name of the system-specific data set contains the system
name as one of the qualifiers. This allows you to use the &SYSNAME. symbolic (defined in
IEASYMxx) in BPXPRMxx.
Version root zFS
The version HFS is the IBM-supplied root zFS data set. To avoid confusion with the sysplex
root zFS data set, “root HFS” has been renamed to “version zFS.” IBM supplies the version
HFS in ServerPac. CBPDO users obtain the version HFS by following directions in the
Program Directory. There is one “version HFS” for each set of systems participating in a
shared file system environment and that are at the same release level (that is, using the same
SYSRES volume).
$SYSNAME/tmp
$SYSNAME/var
$SYSNAME/etc
$SYSNAME/dev
$VERSION/samples
$VERSION/bin
$VERSION/lib
$VERSION/usr
$VERSION/opt
$SYSNAME/
$VERSION/
/
OMVS.SC64.SYSTEM.HFS
symlinks
/samples
/bin
/lib
/usr
/opt
OMVS.SC64.DEV
OMVS.SC64.ETC
OMVS.SC64.VAR
OMVS.SC64.TMP
/
symlinks
OMVS.Z19RA1.ROOT.HFS
$SYSNAME/tmp
$SYSNAME/var
$SYSNAME/etc
$SYSNAME/dev
/
symlinks
OMVS.SYSPLEX.ROOT
symlinks symlinks
Z19RA1
BIN
SAMPLES
LIB USR
OPT U
$VERSION
$SYSNAME
SC64
DEV
TMP VAR ETC
BIN
SAMPLES LIB USR
OPT
DEV
TMP
ETC
VAR
BIN
SAMPLES
LIB USR
OPT
U
VAR
SYSTEM
DEV
TMP
ETC
VAR
OMVS Couple
Data Set

392

ABCs of z/OS System Programming: Volume 9
8.4 Multiple systems: Different versions
Figure 8-4 Shared sysplex with different z/OS levels
Using multiple roots in a shared environment
The version zFS is the IBM-supplied root HFS data set. To avoid confusion with the sysplex
root zFS data set, “root zFS” has been renamed to “version zFS.”
IBM supplies the version HFS in ServerPac. CBPDO users obtain the version HFS by
following directions in the Program Directory. There is one version zFS for each set of
systems participating in a shared file system environment and that are at the same release
level (that is, using the same SYSRES volume).
In Figure 8-4, there are two systems in the sysplex, SC64 and SC65. There are also two
different z/OS releases, one on each system for z/OS V1R10 and z/OS V1R11. Therefore,
there are two version roots mounted off of the sysplex root. The directories in the sysplex root
are defined in the BPXPRMxx member for each system with the VERSION= statement, as
follows:
VERSION(‘Z10RA1’) VERSION(‘Z11RA1’)
SYSPLEX(YES) SYSPLEX(YES)
OMVS.SYSPLEX.ROOT
Z11RA1
/
SC63
SC65
OMVS.SC65.SYSTEM.ZFS
OMVS.Z12RA1.ROOT.ZFS
OMVS.Z11RA1.ROOT.ZFS
OMVS.SC65.ETC
OMVS.SC65.VAR
OMVS.SC65.TMP
OMVS.SC65.DEV
OMVS.SC63.ETC
OMVS.SC64.VAR
OMVS.SC63.TMP
OMVS.SC63.DEV
OMVS.SC63.SYSTEM.ZFS
/dev
/tmp
/var
/etc
/dev
/tmp
/var
/etc
/dev -- $SYSNAME/dev
/tmp -- $SYSNAME/tmp
/var -- $SYSNAME/var
/etc -- $SYSNAME/etc
/dev -- $SYSNAME/dev
/tmp -- $SYSNAME/tmp
/var -- $SYSNAME/var
/etc -- $SYSNAME/etc
/dev -- $SYSNAME/dev
/tmp -- $SYSNAME/tmp
/var -- $SYSNAME/var
/etc -- $SYSNAME/etc
(3)
(2)
(1)
shared file system
environment
Z12RA1

Chapter 8. File sharing in a sysplex
393
8.5 Update BPXPRMxx for sysplex
Figure 8-5 BPXPRMxx definitions for sysplex sharing
BPXPRMxx member for sysplex sharing
Sysplex sharing enables you to use one BPXPRMxx member to define all the file systems in
the sysplex. This means that each participating system has its own BPXPRMxx member to
define system limits, but shares a common BPXPRMxx member to define the file systems for
the sysplex. This is done through the use of system symbolics, as shown in Figure 8-5. You
can also have multiple BPXPRMxx members defining the file systems for individual systems
in the sysplex. The following parameters set up HFS sharing in a sysplex:
SYSPLEX(YES)
sets up sysplex sharing for those who are participating in HFS or zFS data
sharing. To participate in HFS data sharing, the systems must be at the OS/390 V2R9
level or later. Those systems that specify
SYSPLEX(YES)
make up the participating group for
the sysplex.
VERSION('nnnn')
allows multiple releases and service levels of the binaries to coexist and
participate in HFS sharing.
nnnn
is a qualifier to represent a level of the version HFS. The
most appropriate values for
nnnn
are the name of the target zone, &SYSR1., or another
qualifier meaningful to the system programmer. A directory with the value nnnn specified
on VERSION will be dynamically created at system initialization under the sysplex root
and will be used as a mount point for the version HFS.
BPXISYSR and BPXISYSS are provided as sample jobs to build root and system-specific
HFS in SYS1.SAMPLIB.
Jobs BPXISYS1 and BPXISYS2 are also provided to build root and system-specific HFS
directories and symlinks.
VERSION('&SYSR1')
SYSPLEX(YES)
ROOT
FILESYSTEM('OMVS.SYSPLEX.ROOT')
TYPE (ZFS) MODE(RDWR)
M
OUNT
FILESYSTEM('OMVS.&SYSNAME..SYSTEM.ZFS')
TYPE(ZFS) MODE(RDWR) UNMOUNT
M
OUNTPOINT('/&SYSNAME.')
M
OUNT
FILESYSTEM('OMVS.&SYSR1..ROOT.ZFS')
TYPE(ZFS) MODE(READ)
M
OUNTPOINT('/$VERSION')
M
OUNT
FILESYSTEM('OMVS.&SYSNAME..ETC')
TYPE(ZFS) MODE(RDWR) UNMOUNT
M
OUNTPOINT('/&SYSNAME./etc')
Created by BPXISYSR job
Created by BPXISYSS job
Version Root
System-specific /etc files

394

ABCs of z/OS System Programming: Volume 9
AUTOMOVE options
The AUTOMOVE|NOAUTOMOVE|UNMOUNT parameters on ROOT and MOUNT indicate
what happens to the file system if the system that owns that file system goes down, as
follows:

AUTOMOVE specifies that ownership of the file system is automatically moved to another
system. It is the default.

NOAUTOMOVE specifies that the file system will not be moved if the owning system goes
down and the file system is not accessible.

UNMOUNT specifies that the file system will be unmounted when the system leaves the
sysplex. This option is not available for automounted file systems.
You should define your version and sysplex root HFS data as AUTOMOVE, and define your
system-specific file systems as UNMOUNT. Do not define a file system as NOAUTOMOVE or
UNMOUNT and a file system underneath it as AUTOMOVE. If you do, the file system defined
as AUTOMOVE will not be recovered after a system failure until that failing system has been
restarted.
Attention:
The system-specific file system should be mounted read-write, and should be
designated AUTOMOVE(UNMOUNT). Also, /etc, /var, /tmp, and /dev should be mounted
AUTOMOVE(UNMOUNT).

Chapter 8. File sharing in a sysplex
395
8.6 OMVS couple data set
Figure 8-6 Defining the OMVS couple data set
Defining an OMVS couple data set
Shared sysplex support uses a type BPXMCDS couple data set (CDS) to maintain data about
mounted file systems in the sysplex configuration. The primary and alternate CDSs are
formatted, using the IXCL1DSU utility, with a maximum number of mount entries as specified
in

the

NUMBER

value that specifies the number of mounts, as shown in Figure 8-6.
In previous releases, users needed the capability to determine when the number of file
system mounts in a shared sysplex was approaching the configured limit. Before z/OS V1R3
there was no way to easily determine when the mount limit specified in the BPXMCDS CDS
was being approached. z/OS V1R3 introduced the possibility of monitoring the shared file
system environment mount limits, specified in the CDS, by issuing a console message when
the limit has almost been reached.
Once the mount limit is reached, no more file systems can be mounted in the sysplex until a
larger type BPXMCDS CDS is enabled. Mount table limit monitoring allows an installation to
detect when a primary CDS is reaching its mount table limit in order to begin corrective
actions before denial of service.
ITEM NAME(MOUNTS) NUMBER(500)
/* Specifies the number of MOUNTS that can be supported by OMVS.*/
Default = 100
Suggested minimum = 10
Suggested maximum = 35000 */
ITEM NAME(AMTRULES) NUMBER(50)
/* Specifies the number of automount rules that can be supported by OMVS */
Default = 50
Minimum = 50
Maximum = 1000 */
OMVS couple data set
BPXMCDS
BPXMCDS
Display status: f bpxoinit,filesys=display,global

396

ABCs of z/OS System Programming: Volume 9
Displaying the OMVS couple data set information
You can display the number of mount entries and the number in use by issuing the
F BPXOINIT,FILESYS=DISPLAY,GLOBAL command.
f bpxoinit,filesys=display,global
BPXM027I COMMAND ACCEPTED.
BPXF242I 2007/10/13 19.18.53 MODIFY BPXOINIT,FILESYS=DISPLAY,GLOBAL
SYSTEM LFS VERSION ---STATUS--------------------- RECOMMENDED ACTION
SC64 1. 9. 0 VERIFIED NONE
SC65 1. 9. 0 VERIFIED NONE
SC70 1. 9. 0 VERIFIED NONE
SC63 1. 9. 0 VERIFIED NONE
CDS VERSION= 2 MIN LFS VERSION= 1. 9. 0
DEVICE NUMBER OF LAST MOUNT= 558
MAXIMUM MOUNT ENTRIES= 1000 MOUNT ENTRIES IN USE= 222
MAXIMUM AMTRULES= 50 AMTRULES IN USE= 2
MAXSYSTEM= 8
BPXF040I MODIFY BPXOINIT,FILESYS PROCESSING IS COMPLETE.

Chapter 8. File sharing in a sysplex
397
8.7 OMVS couple data set commands
Figure 8-7 OMVS couple data set command changes in z/OS V1R9
OMVS CDS display command
In a sysplex environment, the OMVS couple data sets are defined when using shared file
system support. To avoid a single point of failure in the sysplex, there is a primary CDS and
an alternate CDS. These CDSs are formatted by a utility provided by z/OS. The alternate
CDS must be compatible with the primary CDS (for example, formatted with equal or greater
capacity). If the primary CDS fails, the sysplex automatically makes the alternate CDS the
primary. The SETXCF COUPLE,PSWITCH command is issued to dynamically make the
alternate CDS the primary in case they need to expand the size of the primary CDS, or
change the CDS to a different device to circumvent device errors, or take advantage of a
different device, in a non-disruptive way.
With z/OS V1R9, the D XCF,COUPLE,TYPE=BPXMCDS command now makes it possible,
on a query of the OMVS CDS, to display the VERSION (system software) and the value
keywords (MOUNTS and AMTRULES) used to format the CDS.
Previously, when using commands to bring a new CDS into a sysplex that is somehow not
compatible with the one that is currently used, the response only described the mismatch in
terms of internal information which does not help to determine any incompatibilities with the
alternate CDS.
The enhancement displays the output to include the version and current value of MOUNTS
and AMTRULES for both the primary and alternate CDS.
Output of D XCF,COUPLE,TYPE=BPXMCDS
command has been enhanced to include the USS
CDS information
Provide USS CDS information to help you manage the
shared file system configuration to make the functions
easier to understand and use and improve system
programmer and operator productivity
Output of SETXCF COUPLE,ACOUPLE=
(AlternateCDS),TYPE=BPXMCDS command has
been enhanced to better describe the specific error
BPXMCDS
OMVS couple data sets
BPXMCDS
Primary
Alternate

398

ABCs of z/OS System Programming: Volume 9
8.8 D XCF,COUPLE,TYPE=BPXMCDS
Figure 8-8 D XCF,COUPLE,TYPE=BPXMCDS command
The D XCF,COUPLE,TYPE=BPXMCDS command
Figure 8-8 shows an example of an invocation of the D XCF,COUPLE,TYPE=BPXMCDS
command. The following message text is the enhanced output:
FORMAT DATA
VERSION(2)
MOUNTS(500) AMTRULES(50)
z/OS UNIX provides the version, and the value of MOUNTS and AMTRULES, which are
keywords for the z/OS UNIX format utility. z/OS UNIX provides a sample JCL job to format the
CDS in SYS1.SAMPLIB(BPXISCDS)). The old respond text used to be
NOT PROVIDED
.
The output shown is for the primary and alternate CDS data sets.
IXC358I 18.21.35 DISPLAY XCF 182
BPXMCDS COUPLE DATA SETS
PRIMARY DSN: SYS1.XCF.OMVS02
VOLSER: SBOX63 DEVN: 836F
FORMAT TOD MAXSYSTEM
12/18/2003 10:29:20 8
ADDITIONAL INFORMATION:
FORMAT DATA
VERSION(2)
MOUNTS(1000) AMTRULES(50)
ALTERNATE DSN: SYS1.XCF.OMVS03
VOLSER: SBOX64 DEVN: 8068
FORMAT TOD MAXSYSTEM
12/18/2003 10:29:21 8
ADDITIONAL INFORMATION:
FORMAT DATA
VERSION(2)
MOUNTS(1000) AMTRULES(50)
BPXMCDS IN USE BY ALL SYSTEMS

Chapter 8. File sharing in a sysplex
399
8.9 Change to the SETXCF command
Figure 8-9 Changes to the SETXCF command
The SETXCF command
Figure 8-9 shows an example of a SETXCF
COUPLE,ACOUPLE=(Alternate_CDS),TYPE=BPXMCDS command.
In this example, the primary CDS was formatted with a MOUNTS value of 500 and an
AMTRULES value of 50, but the alternate CDS was formatted with a MOUNTS value of 400
and an AMTRULES value of 50.
Incompatibility in this example
The alternate CDS is not compatible with the primary because it has a smaller value for
MOUNTS. So the command fails, because the alternate CDS must be formatted with equal or
greater values for MOUNTS and AMTRULES in order for this command to work. Before this
enhancement in z/OS V1R9, the information provided for the reason of the failure was the
following:
ALLOWABLE SIZE OF BPXFSMPT RECORDS IS LESS THAN CURRENT PRIMARY RELEVANT
BPXMCDS COUPLE DATA SET FORMAT INFORMATION
BPXFSMPT RECORDS is the internal record name of USS. With this message, it was not
easy to determine why the alternate CDS was incompatible.
In this example, the primary CDS was formatted with
MOUNTS value of 500 and AMTRULES value of 50
The alternate CDS was formatted with MOUNTS value
of 400 and AMTRULES value of 50
The alternate CDS is not compatible with the primary
because it has a smaller value for MOUNTS
SETXCF COUPLE,ACOUPLE… fails because the
alternate CDS must be formatted with an equal or
greater value for MOUNTS and AMTRULES with the
following message:
SETXCF COUPLE,ACOUPLE=(POSIX.OMVS.CDS03,AUXVOL),TYPE=BPXMCDS
ALLOWABLE SIZE OF BPXFSMPT RECORDS IS LESS THAN CURRENT
PRIMARY RELEVANT BPXMCDS COUPLE DATA SET FORMAT INFORMATION

400

ABCs of z/OS System Programming: Volume 9
8.10 New message for command failure
Figure 8-10 New message when command fails
New failure message with z/OS V1R9
In this example, the primary CDS was formatted with a MOUNTS value of 500 and an
AMTRULES value of 50, but the alternate CDS was formatted with a MOUNTS value of 400
and an AMTRULES value of 50.
The alternate CDS is not compatible with the primary because it has a smaller value for
MOUNTS, so the command SETXCF COUPLE,ACOUPLE… failed, because the alternate
CDS must be formatted with equal or greater values for MOUNTS and AMTRULES in order
for this command to work.
The new message shown in the command output for the failure is:
IXC250I ALTERNATE COUPLE DATA SET REQUEST FAILED FOR DATA SET 408
POSIX.OMVS.CDS03 FOR BPXMCDS:
CONSISTENCY CHECKING FAILED FOR THE NEW ALTERNATE DATA SET
SETXCF COUPLE,ACOUPLE=(POSIX.OMVS.CDS03,AUXVOL),TYPE=BPXMCDS
IXC309I SETXCF COUPLE,ACOUPLE REQUEST FOR BPXMCDS WAS ACCEPTED
IXC260I ALTERNATE COUPLE DATA SET REQUEST FROM SYSTEM 405
SY1 FOR BPXMCDS IS NOW BEING PROCESSED.
DATA SET: POSIX.OMVS.CDS03
IEF196I IEF237I 0483 ALLOCATED TO SYS00038
IXC255I UNABLE TO USE DATA SET 407
POSIX.OMVS.CDS03
AS THE ALTERNATE FOR BPXMCDS:
ALLOWABLE SIZE OF BPXFSMPT RECORDS IS LESS THAN CURRENT PRIMARY
RELEVANT BPXMCDS COUPLE DATA SET FORMAT INFORMATION
PRIMARY
FORMAT LEVEL: VERSION(2)
FORMAT KEYWORDS: MOUNTS(500) AMTRULES(50)
ALTERNATE
FORMAT LEVEL: VERSION(2)
FORMAT KEYWORDS: MOUNTS(400) AMTRULES(50)
IXC250I ALTERNATE COUPLE DATA SET REQUEST FAILED FOR DATA SET 408
POSIX.OMVS.CDS03 FOR BPXMCDS:
CONSISTENCY CHECKING FAILED FOR THE NEW ALTERNATE DATA SET
IEF196I IEF285I POSIX.OMVS.CDS03 KEPT
IEF196I IEF285I VOL SER NOS= AUXVOL.

Chapter 8. File sharing in a sysplex
401
8.11 File sharing in a sysplex
Figure 8-11 File sharing in a sysplex environment
File sharing in a sysplex
Before OS/390 UNIX V2R9, users could have read/write access only to data in file systems
mounted on their own system. With a shared file system environment, users have greater
access to the file systems in a sysplex. They have read/write access to file systems that are
mounted on other systems.
With a shared file system environment, all file systems that are mounted by a system
participating in a shared file system environment are available to all participating systems. In
other words, once a file system is mounted by a participating system, that file system is
accessible by any other participating system. It is not possible to mount a file system so that it
is restricted to just one of those systems. Consider a sysplex that consists of three systems,
SC63, SC64, and SC65:

A user logged onto any system can make changes to file systems mounted on

/u, and
those changes are visible to all systems.

The system programmer who manages maintenance for the sysplex can change entries in
both

/etc file systems from either system.
The couple data set (CDS) contains the sysplex-wide mount table and information about all
participating systems, and all mounted file systems in the sysplex. To allocate and format a
CDS, customize and invoke the BPXISCDS sample job in SYS1.SAMPLIB. The job will create
two CDSs: one is the
primary
and the other is a backup that is referred to as the
alternate
. In
BPXISCDS, you also specify the number of mount records that are supported by the CDS.
The CDS must be defined in the COUPLExx PARMLIB member. A shared file system
environment must be defined in the BPXPRMxx PARMLIB member.
BPXPRMxx
SYSPLEX=YES
ZFS
SC65
ZFS
SC63
SC64
z/OS V1R11
ZFS
DATA TYPE(BPXMCDS)
PCOUPLE(SYS1.OMVS.CDS01,VLOMV1)
ACOUPLE(SYS1.OMVS.CDS02,VLOMV2)
COUPLExx
OMVS couple data set
BPXMCDS
File1
/
File2
OMVS.CMP01.ZFS
F
F
F
F F
/
HFS
HFS
zFS
OMVS
(HFS)
OMVS
(HFS)
OMVS
(HFS)
z/OS V1R11
z/OS V1R11

402

ABCs of z/OS System Programming: Volume 9
8.12 Mounting shared sysplex file systems
Figure 8-12 Shared sysplex mounted file systems
Shared sysplex environment
With a shared sysplex environment, sharing HFS and zFS file systems, each system must
have specific HFS data sets for each of these file systems, meaning the two systems each
have HFS data sets for /etc, /tmp, /var, and /dev. The file systems are then mounted under the
system-specific HFS, as shown in Figure 8-12. With shared file system environment support,
one system can access system-specific file systems on another system. For example, while
logged onto SC65, you can gain read-write access to SC64's /tmp by specifying /SC64/tmp/.
BPXPRMxx PARMLIB specification
You should also be aware that when SYSPLEX(YES) is specified, each FILESYSTYPE in use
within the participating group must be defined for all systems participating in a shared file
system environment. The easiest way to accomplish this is to create a single BPXPRMxx
member that contains file system information for each system participating in a shared file
system environment. If you decide to define a BPXPRMxx member for each system, the
FILESYSTYPE statements must be identical on each system.
The sysplex root provides access to all directories. Each system in a sysplex can access
directories through the symbolic links that are provided. Essentially, the sysplex root provides
redirection to the appropriate directories, and it should be kept very stable; updates and
changes to the sysplex root should be made as infrequently as possible.
Note:
The first system that IPLs in the sysplex becomes the owner of the sysplex root.
XCF
Sysplex Root
Version Root
OMVS CDS
/dev-/tmp-/var-/etc/dev-/tmp-/var-/etc
OWNER
(Coordinator)
SC64 SC65
System Specific
System Specific
BPXPRMxx
SYSPLEX=YES
XCF

Chapter 8. File sharing in a sysplex
403
8.13 Accessing shared sysplex file systems
Figure 8-13 Accessing shared sysplex mounted file systems
Accessing file systems
The intersystem communication required to provide the additional availability and
recoverability associated with z/OS UNIX in a shared file system environment support affects
response time and throughput on R/W file systems being shared in a sysplex.
For example, assume that a user on SC64 requests a read on a file system mounted R/W and
owned by SC65. Using shared file system environment support, SC64 sends a message
requesting this read to SC65 via an XCF messaging function:
SC64 ===> (XCF messaging function) ===> SC65
After SC65 gets this message, it issues the read on behalf of SC64, and gathers the data
from the file. It then returns the data via the same route the request message took:
SC65 ===> (XCF messaging function) ===> SC64
R/W Request
Webserver
Lotus
SAP
Customer data
(digital data, multimedia)
others
SC64 <== (XCF messaging function) <== SC65
SC64 ==> (XCF messaging function) ==> SC65
Sysplex Root
Version Root
OMVS CDS
UNIX Data
OWNER
(Coordinator)
XCF
SC64
ls /bin/
SC65
XCF

404

ABCs of z/OS System Programming: Volume 9
8.14 Shared file system AUTOMOVE takeover
Figure 8-14 AUTOMOVE options in a shared sysplex
AUTOMOVE takeover of file systems
File system recovery in a shared file system environment takes into consideration file system
specifications such as AUTOMOVE, NOAUTOMOVE, UNMOUNT, and whether or not the file
system is mounted read-only or read-write.
Generally, when an owning system fails, ownership over its automove-mounted file system is
moved to another system and the file is usable. However, if a file system is mounted
read-write and the owning system fails, then all file system operations for files in that file
system will fail. This happens because data integrity is lost when the file system owner fails.
All files should be closed (BPX1CLO) and reopened (BPX1OPN) when the file system is
recovered.
Read-only file systems
For file systems that are mounted read-only, specific I/O operations that were in progress at
the time the file system owner failed may need to be started again.
Moving file systems
In some situations, even though a file system is mounted AUTOMOVE, ownership of the file
system may not be immediately moved to another system. This may occur, for example, when
a physical I/O path from another system to the volume where the file system resides is not
available. As a result, the file system becomes unowned; if this happens, you will see
message BPXF213E. This is true if the file system is mounted either read-write or read-only.
The file system still exists in the file system hierarchy so that any dependent file systems that
OWNER
(Coordinator)
XCF
SC64
R/W Request
New OWNER
OMVS CDS
Webserver
Lotus
SAP
Customer data
(digital data, multimedia)
others
Sysplex RootVersion Root
ls /bin/
SC65
XCF

Chapter 8. File sharing in a sysplex
405
are owned by another system are still usable. However, all file operations for the unowned file
system will fail until a new owner is established. The shared file system environment support
will continue to attempt recovery of AUTOMOVE file systems on all systems in the sysplex
that are enabled for a shared file system environment. Should a subsequent recovery attempt
succeed, the file system transitions from the unowned to the active state.
NOAUTOMOVE file systems
File systems that are mounted NOAUTOMOVE or UNMOUNT will become unowned when
the file system owner exits the sysplex. The file system will remain unowned until the original
owning system restarts or until the unowned file system is unmounted. Because the file
system still exists in the file system hierarchy, the file system mount point is still in use.
An unowned file system is a mounted file system that does not have an owner. The file
system still exists in the file system hierarchy. As such, you can recover or unmount an
unowned file system.

406

ABCs of z/OS System Programming: Volume 9
8.15 Moving file systems in a sysplex
Figure 8-15 Command to move a file system in a sysplex environment
Commands to move file systems
You may need to change ownership of the file system for recovery or re-IPLing. To check for
file systems that have already been mounted, use the
df
command from the shell. The
setomvs
command used with the
FILESYS
,
FILESYSTEM
,
mount point
and
SYSNAME
parameters
can be used to move a file system in a sysplex, or you can use the
chmount
command from
the shell. However, do not move these two types of file systems:

System-specific file systems.

File systems that are being exported by DFS. You have to unexport them from DFS first
and then move them.
Examples of moving file systems are:

To move ownership of the file system that contains /u/user1 to SC64:
chmount -d SC64 /u/user1

To move ownership of the payroll file system from the current owner to SC64 using
SETOMVS
, issue:
SETOMVS FILESYS,FILESYSTEM='POSIX.PAYROLL.HFS',SYSNAME=SC64

Assuming the mount point is over directory /PAYROLL:
SETOMVS FILESYS,mountpoint='/PAYROLL',SYSNAME=SC64

Move the root file system:
SETOMVS FILESYS,FILESYSTEM='OMVS.Z19RA1.ROOT.HFS',SYSNAME=SC64
Need to change ownership for recovery or re-IPL
Use the SETOMVS command with SYSNAME
parameter
Re-IPL SC64
R/W Request
SETOMVS FILESYS,FILESYSTEM='OMVS.Z19RA1.ROOT.HFS',SYSNAME=SC64
Sysplex Root
Version Root
OMVS CDS
OWNER
(Coordinator)
XCF
SC64
ls /bin/
SC65
XCF

Chapter 8. File sharing in a sysplex
407
8.16 Requests to LFS to PFS to files
Figure 8-16 The logical file system
Logical file system (LFS)
The PFS interface is a set of protocols and calling interfaces between the logical file system
(LFS) and the PFSs that are installed on z/OS UNIX. PFSs mount and unmount file systems
and perform other file operations.
The LFS is called by POSIX programs, non-POSIX z/OS UNIX programs, and VFS servers.
LFS implementation
Changes were made to LFS termination of a PFS, such as zFS, in order to improve the
availability of file systems on the system where a PFS is terminating.
The old design of PFS termination is that file systems for the terminating PFS, and subtrees
of those file systems, get moved to another system (if locally owned), and then get locally
unmounted and become unavailable on the system where the PFS is terminating. If they
could not be moved, then they became globally unmounted.
This new design is that the ownership of these file systems can be moved to another system
in the sysplex, and then allow for function-shipping requests on the system where a PFS is
terminating and avoid the local unmounts. This provides improved availability of file systems.
read
write open close
auto-
mount
TFS
IP
sockets
Local
sockets
NFS
client
ZFS
HFSVOL
HFSVOL
ZFSVOL
ZFSVOL
F
F
/
F
F
F
F
F
/
F
F
F
F
Physical File Systems
HFS
z/OS Callable Services Interface
Logical File System
z/OS UNIX-PFS Interface
Kernel
Migration
HFS to zFS

408

ABCs of z/OS System Programming: Volume 9
8.17 Systems accessing file systems
Figure 8-17 zFS environment with three systems accessing two file systems
Example of file access
Function shipping is the process of requesting function from the owning file system and
returning the response to the requester through XCF communications.
For read/write mounted file systems, file requests are function shipped to the owning system.
The owning system is the only system where the file system is locally mounted and the only
system have a longer path length through XCF communications. Read/write mounted file
systems are referred to as being non-sysplex aware.
In Figure 8-17 you see a USS sysplex sharing environment with three systems that share two
zFS file systems. In this example, the following is taking place:

System SY1 owns the zFS file systems OMVS.TEST1.ZFS (R/W) and OMVS.TEST2.ZFS
(R/O).

The other two systems, SY2 and SY3, have the R/O zFS file system locally mounted as
read (R/O).

Any R/W requests from SY2 and SY3 to the R/W file system owned by SY1 must be
passed through the XCF messaging function, which are referred to as function-shipping
requests.
ZFS
SC64
z/OS V1R11
ZFS
SC65
z/OS V1R11
OMVS.TEST2.ZFS
F
/
F
F
F
F
OWNER
(Coordinator)
XCF
ZFS
SC70
z/OS V1R11
OMVS.TEST1.ZFS
F
/
F
F
F
F
XCF
Function-ships
R/W requests
Locally mounted
Read (R/O)
Locally mounted
Read (R/O)
R/O
R/W
Function-ships
R/W requests

Chapter 8. File sharing in a sysplex
409
8.18 zFS sharing mode terminology
Figure 8-18 Sysplex-unaware mounted file system
Sysplex-unaware file systems
A file system is non-sysplex aware (or sysplex-unaware) if the PFS (Physical File System)
supporting that file system requires it to be accessed through the remote owning system from
all other systems in a sysplex (allowing only one connection for update at a time) for a
particular mode (read-only or read-write).
The system that connects to the file system is called the file system owner. Other systems’
access is provided through XCF communication with the file system owner. In non-sysplex
aware zFS, file requests for read-write mounted file systems are function shipped to the
owning system by z/OS UNIX. The owning system is the only system where the file system is
locally mounted and the only system that does I/O to the file system.
Sysplex-unaware
A file system is sysplex-unaware if the PFS supporting
that file system requires it to be accessed through the
remote owning system from all other systems in a
sysplex (allowing only one connection for update at a
time) for a particular mode (read-only or read-write).
Access from a system not being the owner (sometimes
referred to as being a client) is provided through XCF
communication to the owning system (sometimes
called “function shipping”) - This is controlled by z/OS
UNIX and the interface is also known as a PFS named
XPFS (“Cross System PFS”)

410

ABCs of z/OS System Programming: Volume 9
8.19 Defining zFS as sysplex-unaware
Figure 8-19 Shared file systems in a sysplex
Function shipping in a sysplex
For read/write mounted file systems, file requests are function shipped to the owning system.
The owning system is the only system where the file system is locally mounted and the only
system that does I/O to the file system. File requests from systems other than the owning
system have a longer path length through XCF communications. Read/write mounted file
systems are referred to as being non-sysplex aware.
When a file system is mounted read/write (as shown in Figure 8-19), the mount request is
sent to the local physical file system (in this case, zFS) and zFS opens the file system data
set (for read/write). If the mount is successful on that system, z/OS UNIX sends a signal to
the other sysplex member systems to issue a catch-up mount on each system. Each z/OS
UNIX on each other system then reads the CDS and determines that it needs to record that
the file system is mounted read/write and that system is the owning system. The local zFS on
the other systems does not receive a local mount request. The mount on that system is
“logically” mounted on each of the other systems.
Catch-up mount
A catch-up mount is when a file system mount is successful on a system in a shared file
system environment. z/OS UNIX automatically issues a corresponding local mount, the
catch-up mount, to every other system's PFS that is running sysplex-aware for that mode
(read-write or read-only). If the corresponding local mount is successful, z/OS UNIX does not
function ship from that system to the z/OS UNIX owning system when that file system is
accessed.


Application
USS
zFS
Application
USS
zFS
F
/
F
F
F
F
Application
USS

zFS
Admin Admin
R/W
Function
Ship
Function
Ship

Chapter 8. File sharing in a sysplex
411
8.20 zFS File systems with APAR OA29712
Figure 8-20 Sysplex-aware mounted file systems
Sysplex-aware file systems
A PFS (Physical File System) that is sysplex-aware for a particular mode (read-only or
read-write) allows file requests for file systems that are mounted in that mode to be handled
by that local PFS (that is, they are locally mounted on that system). z/OS UNIX does not
function ship those file requests to the z/OS UNIX owning system. Note that if the file system
volume is not online to a system, then the system becomes a client to the file system through
function shipping with the owner because the local mount is unsuccessful. Beginning with
z/OS V1R11, you can enable zFS to be sysplex-aware for read-write mounted file systems.
File systems mounted as R/O have been sysplex-aware from the beginning, and HFS and
zFS file systems mounted in R/W mode were sysplex-unaware in all releases prior to z/OS
V1R11.
Note:
With z/OS V1R11, if you enable zFS sysplex-aware for read/write zFS file systems,
you see a performance improvement in most shared file system environments.
If you decide to run zFS sysplex-aware for read/write, roll this support through all your
sysplex members (this assumes all your members are using z/OS V1R11). You cannot
change from zFS non-sysplex aware to zFS sysplex-aware dynamically.
Beginning with z/OS V1R11, zFS introduced the ability
zFS read-write filesystems to be sysplex-aware
This means that USS sends all file requests directly down
to the local zFS physical file system (PFS)
It does not “function ship” the requests
For z/OS V1R11 - APAR OA29712 updates the support
that was shipped with V1R11
USS SPE OA29712 is a pre-requisite zFS SPE OA29619
Conditioning APAR OA29786 must be installed and active
on all your z/OS V1R9 and V1R10 systems
z/OS V1R12 contains OA29712 making V1R11 and
V1R12 at equivalent levels for zFS

412

ABCs of z/OS System Programming: Volume 9
APAR 29712
APAR OA29712 updates the support that was shipped with V1R11 for zFS. Before you can
run zFS sysplex-aware on a file system basis, you must have z/OS V1R11 zFS APAR
OA29619 and z/OS V1R11 UNIX APAR OA29712 installed and active on all of your z/OS
V1R11 systems. In addition, conditioning APAR OA29786 must be installed and active on all
your z/OS V1R9 and V1R10 systems for subsequent zFS V1R11 APAR OA29619. Finally, if
you use the SMB server, APAR OA31112 must also be installed.
APAR 29786
APAR OA29786 will verify that all zFS systems in the sysplex are capable of using the new
zOS V1R11 zFS IOEFSPRM option, SYSPLEX=FILESYS, which will allow sysplex support
on a file system basis. When this new function is shipped on zFS V1R11, OA29786 will allow
zFS V1R9 and zFS V1R10 to be able to also specify a new zFS parameter that indicates a
specific file system will use the sysplex file support.
APAR 29619
zFS APAR OA29619 provides the capability of setting read-write sysplex-awareness on a file
system (mount) basis, which requires the USS support provided with this APAR. USS is
providing support for allowing a PFS to set the read-write sysplex-awareness of a file system
during a mount. Prior to this support, the sysplex-awareness of a PFS that was set during
PFS initialization would apply to all file systems mounted on that system for that PFS. This
affects all flows where USS sends a vfs_mount to the PFS, which includes mount, catchup
mount, remount, dead system recovery, unowned file system recovery or catchup,
newroot/altroot, move, and PFS termination/restart.
Note:
z/OS V1R12 contains OA29712, setting V1R11 and V1R12 at equivalent levels for
zFS, thus setting z/OS V1R11 and z/OS V1R12 at equivalent levels for zFS.

Chapter 8. File sharing in a sysplex
413
8.21 Defining zFS as sysplex-aware
Figure 8-21 Defining zFS as sysplex-aware
zFS as sysplex-aware
For read-write mounted file systems, file requests are sent directly to zFS, which in turn
function ships the request to the zFS owning system. In many cases, zFS does not need to
function ship the request to the owning zFS system because the data is in the local cache.
zFS caches data to avoid frequent forwarding to an owner, and this typically improves
performance for most workloads. The zFS owning system is the only system that does I/O to
the file system. In this case, zFS is running sysplex-aware for read-write mounted file
systems.
Beginning with z/OS V1R11, you can enable zFS to run sysplex-aware for zFS read-write file
systems. When a file system is mounted read-write sysplex-aware (for example, on SY2), the
mount request is sent to the local zFS and zFS opens the file system data set (for read-write).
If the mount is successful on that system, z/OS UNIX sends a signal to the other sysplex
member systems telling them to issue a catch-up mount on each system. Each z/OS UNIX on
each other system then reads the CDS and determines that it needs to send a mount request
to the local zFS for that file system. Each local mount causes zFS to open the data set (for
read-write). In this way, the mount on SY2 causes the file system to be mounted on every
member of the sysplex.
sysplex=on
zFS can be sysplex-aware for read-write mounted file systems. zFS can be configured (zFS
IOEFSPRM option sysplex=on) to treat all zFS read-write mounted file systems owned on
that system as sysplex-aware file systems.


Application
USS
Application
USS
zFS
Application
USS
zFS
F
/
F
F
F
F

zFS
File
Admin Admin
R/W
SY1
SY2
SY3
owning system
Cache
sysplex=on
owning system
Systems are V1R11
or can be V1R12
V1R10
OMVS CDS

414

ABCs of z/OS System Programming: Volume 9
8.22 APAR OA29619
Figure 8-22 APAR OA29619
APAR OA29619
To enable zFS sysplex-aware on a file system basis, specify sysplex=filesys in the
IOEFSPRM configuration file. Leave the sysplex_filesys_sharemode with its default of
norwshare. You can specify it in a shared
IOEFSPRM
configuration file and each system picks
up the specification in a rolling IPL. The sysplex option is ignored by previous releases. Any
z/OS V1R9 or V1R10 systems in the shared file system environment must have zFS APAR
OA29786 active before you can have zFS sysplex=filesys active on any z/OS V1R11 system.
When you run sysplex=filesys, the zFS PFS runs sysplex-aware, but each zFS file system is
mounted non-sysplex-aware (by default). zFS is enabled to allow zFS read-write file systems
to be sysplex-aware but it must be explicitly requested on a file system basis. Note that
although it is possible to change the sysplex_filesys_sharemode from its default of norwshare
to rwshare at IPL using the IOEFSPRM option or dynamically using the zfsadm config
command, this is not recommended while migrating from sysplex=off to sysplex=filesys
because it can cause performance problems.
After you have sysplex=filesys active on all your systems, you can consider which zFS
read-write file systems you want to be sysplex-aware. Good candidates are zFS read-write
file systems that are accessed from multiple systems or are mounted with AUTOMOVE and
might be moved by z/OS UNIX (as a result of a shutdown or IPL) to systems that do not
necessarily do the most accesses.
APAR OA29619 provides a new function that allows
users to specify which zFS read-write file systems are
to be made sysplex-aware
You can choose individual file systems to be
sysplex-aware (requires zFS APAR OA29619)
You can choose to have all zFS file systems be
sysplex-aware
To enable zFS sysplex-aware on a file system basis,
specify sysplex=filesys in the IOEFSPRM
You can specify it in a shared IOEFSPRM and each
system picks up the specification in a rolling IPL - The
sysplex option is ignored by previous releases

Chapter 8. File sharing in a sysplex
415
8.23 New zFS configuration options (OA29619)
Figure 8-23 New configuration with APAR OA29619
APAR OA29619 configuration options
Following are new configuration options that can be defined either in the IOEPRMxx parmlib
member or in the IOEFSPRM DD member in the ZFS procedure. These parameters are
changed as indicated by z/OS V1R11 and with APAR OA29619.
Sysplex options, filesys and on
Sysplex=filesys specifies whether zFS should run sysplex-aware and if so, whether zFS is
sysplex-aware on a file system basis (sysplex=filesys) or sysplex-aware on a system basis
(sysplex=on). When sysplex=off, zFS does not automatically move zFS ownership of the
aggregate.
The sysplex_filesys_sharemode option
This option specifies the default for the mount PARM for a zFS read-write file system mounted
on a sysplex=filesys system. You can override this setting at mount time by specifying an
alternate value in the actual mount PARM.
Note:
If you decide to run zFS non-sysplex aware, shared file system support works as in
prior releases. Ensure that you do not specify sysplex=on or sysplex=filesys in your zFS
IOEFSPRM
configuration options file.
Options changed with V1R11 and OA29619
sysplex = {on | off |
filesys
} - Default is
OFF
sysplex_filesys_sharemode
= norwshare
| rwshare
sysplex_admin_level = 0 | 1 | 2 | 3
token_cache_size = vnode_cache_size x 2
file_threads = 40
client_cache_size =128M -------->
client_reply_storage =
10M
----> (changed from 40M)
recovery_max_storage = 256M
Cache
Underlined
options are with OA29619

416

ABCs of z/OS System Programming: Volume 9
The NORWSHARE file system is a non-sysplex-aware file system; it is only locally mounted
on the z/OS UNIX owner and requests from z/OS UNIX clients are function shipped to the
z/OS UNIX owner by z/OS UNIX.
sysplex_admin_level
Specifies the zFS XCF communication interface level that zFS is running as sysplex-aware.
This is only valid for systems running zFS V1R9 or V1R10 with the proper APARs applied.
One (1) indicates that zFS running on z/OS V1R9 or V1R10 is in preconditioning state and is
using interface level 1. zFS uses the existing XCF protocol but also supports enough of the
new XCF protocol for zFS interface level 2 to run properly. Two (2) indicates that zFS running
on z/OS V1R9 or V1R10 is in toleration mode and is using interface level 2. zFS uses the new
XCF protocol and is able to communicate with other zFS instances running at interface level 1
to display aggregate information for aggregates owned by zFS interface level 1 systems. At
level 2, zFS is able to communicate with other zFS instances running at z/OS V1R11 (level 3).
The value must be 2 on all members of the sysplex in order to bring z/OS V1R11 zFS into the
shared file system environment.
client_cache_size
This parameter specifies the amount of storage used to cache sysplex client user data. You
can also specify a fixed option that indicates that the pages are permanently fixed for
performance. When zFS is running sysplex-aware for read-write file systems, a new cache is
added to zFS controlled by the client_cache_size IOEFSPRM configuration option. The
client_cache_size option is used to cache user data when zFS files are accessed from a
system that is not the zFS owner of the file system. The default size is 128 MB.
Note:
When you run zFS sysplex-aware on a file system basis (sysplex=filesys) on all your
members, the zFS PFS initializes as sysplex-aware. However, it can determine which
individual file system is sysplex-aware and which is not based on the RWSHARE or
NORWSHARE mount parm or the sysplex_filesys_sharemode option if that MOUNT
PARM is not specified.
The following example shows the mount of a zFS read-write file system with a mount
PARM of RWSHARE:
MOUNT FILESYSTEM('OMVS.PRV.COMPAT.AGGR001') TYPE(ZFS) MODE(RDWR)
MOUNTPOINT('/usr/mountpt1') PARM('RWSHARE')

Chapter 8. File sharing in a sysplex
417
8.24 Admin levels in a mixed sysplex
Figure 8-24 Admin levels in a sysplex
Admin levels in a sysplex
In z/OS V1R11, you must apply the zFS sysplex administration function using the following
two-step APAR procedure:
1.Install APAR OA25026 on all z/OS V1R9 and z/OS V1R10 systems. This is a conditioning
function for zFS on z/OS V1R11. Make APAR OA25026 active on all systems through a
rolling IPL. You are now running with zFS sysplex_admin_level=1.
2.After APAR OA25026 is active on each z/OS V1R9 and V1R10 system, specify the
sysplex_admin_level=2 configuration option in the
IOEFSPRM
file. Make this level active on
all z/OS V1R9 and V1R10 systems through another rolling IPL. This is the toleration
function for zFS on z/OS V1R11 (the default for sysplex_admin_level is
sysplex_admin_level=1).
Note:
You cannot skip step 1 and do only step 2 if you are running any z/OS V1R9 or
V1R10 systems that do not have APAR OA25026 installed and active.

Your systems must be running zFS V1R9 and above to support a zFS V1R11
environment. In other words, zFS V1R11 is not compatible with V1R8 and below.

The sysplex_admin_level configuration option cannot be specified dynamically through
the zfsadm config command.
zFS in V1R9 or V1R10 with sysplex_admin_level=1
Uses and follows the XCF Admin protocol among systems
with level 0 and 1 and does not initialze if a system with
XCF Admin level 3 is active in the sysplex
zFS in V1R9 or V1R10 with sysplex_admin_level=2
Uses and follows the new XCF Admin protocol among
systems with levels 2 or 3 and does not initialze if a
system with XCF Admin level 0 is active in the sysplex
zFS in R11 and R12 running with sysplex_admin_level=3
By default follows the new XCF Admin protocol with
systems at levels 2 or 3 and does not initialze if a system
with XCF Admin level 0 or 1 is active in the sysplex

418

ABCs of z/OS System Programming: Volume 9
sysplex_admin_level
The sysplex_admin_level parameter specifies the zFS XCF communication interface level
that zFS is running as sysplex-aware. This is only valid for systems running zFS V1R9 or
V1R10 with the proper APARs applied. The sysplex_admin_level option is ignored in z/OS
V1R11 because zFS runs at sysplex_admin_level 3 on z/OS V1R11.
The sysplex_admin_level is specified as follows:
1.Indicates that zFS running on z/OS V1R9 or V1R10 is in preconditioning state and is using
interface level 1. zFS uses the existing XCF protocol but also supports enough of the new
XCF protocol for zFS interface level 2 to run properly. Two (2) indicates that zFS running
on z/OS V1R9 or V1R10 is in toleration mode and is using interface level 2. zFS uses the
new XCF protocol and is able to communicate with other zFS instances running at
interface level 1 to display aggregate information for aggregates owned by zFS interface
level 1 systems.
2.At level 2, zFS is able to communicate with other zFS instances running at z/OS V1R11
(level 3). The value must be 2 on all members of the sysplex in order to bring z/OS V1R11
zFS into the shared file system environment.
3.The default value is 3 in z/OS V1R11 and z/OS V1R12. The default level is 1 in z/OS V1R9
and V1R10.
Note:
The expected value in z/OS V1R11and z/OS V1R12 is 3 and this option is ignored.
In z/OS V1R9 and V1R10, the level is 1 or 2.

Chapter 8. File sharing in a sysplex
419
8.25 Defing zFS as syplex-aware
Figure 8-25 zFS as sysplex-aware with sysplex=filesys
zFS as sysplex-aware with sysplex=filesys
If you are running your sysplex in a shared file system environment, that is BPXPRMxx
specifies SYSPLEX(YES), you can set zFS V1R11 or any system above to run in one of the
following modes:

Non-sysplex aware for read-write zFS file systems as in previous releases (the default).

Sysplex-aware on a file system basis—that is, enabling zFS to run sysplex-aware, but
individually choosing which file systems are sysplex-aware for read-write and which ones
are not (enable by specifying sysplex=filesys in your IOEFSPRM and then perform a
rolling IPL).

Sysplex-aware for all read-write zFS file systems—that is, enabling zFS to run
sysplex-aware, and having all zFS read-write file systems mounted sysplex-aware (enable
by specifying sysplex=on in your IOEFSPRM and then perform a rolling IPL).
Typically, if you make a zFS read-write file system sysplex-aware, you see a performance
improvement in most shared file system environments when accessing the data from a
system that is not the zFS owner. There are, however, some servers that are not transparent
to zFS sysplex-aware for read-write support.
Recommendation:
Run sysplex-aware on a file system basis because that gives you the
most control and flexibility in deciding which zFS file systems should be sysplex-aware. It
also avoids the restriction noted below.


Application
USS
Application
USS
zFS
Application
USS
zFS
F
/
F
F
F
F

zFS
File
File
Admin Admin
R/W
SY1
SY2
SY3
owning system
Cache
Cache
sysplex=filesys
owning system
All systems
are V1R11
or above

420

ABCs of z/OS System Programming: Volume 9
Sysplex-aware PFS
A physical file system (PFS), for example zFS, is sysplex-aware or non-sysplex aware for a
particular mount mode (read-only or read-write) in a shared file system environment. When it
is sysplex-aware, it means that the PFS is capable of handling a local mount on the system
that is not the z/OS UNIX owning system. The PFS that is sysplex-aware can avoid z/OS
UNIX function shipping for that mode. All physical file systems are always sysplex-aware for
read-only mounts. HFS is always non-sysplex aware for read-write mounts and always results
in z/OS UNIX function shipping from systems that are not the z/OS UNIX owning system.
Sysplex-aware file system
A file system can be mounted sysplex-aware or non-sysplex aware. When a file system is
mounted sysplex-aware, it means that the file system is locally mounted on every system
(when the PFS is capable of handling a local mount on every system—that is, the PFS is
running sysplex-aware) and therefore, file requests are handled by the local PFS. All
read-only mounted file systems are always mounted sysplex-aware. HFS read-write mounted
file systems are always mounted non-sysplex aware. This means that file requests from
non-z/OS UNIX owning systems are always function shipped by z/OS UNIX to the z/OS UNIX
owning system where the file system is locally mounted and the I/O is actually done.
Beginning with z/OS V1R11, zFS read-write mounted file systems can be mounted
sysplex-aware.
zFS can run sysplex-aware for read-write mounted file systems in the following ways:

Sysplex-aware on a file system basis (sysplex=filesys)
Selected zFS read-write file systems are sysplex-aware.

Non-sysplex aware by default)
zFS read-write file systems that specify the RWSHARE mount PARM are sysplex-aware.

Sysplex-aware on a system basis (sysplex=on)
Every zFS read-write file system owned on the system is sysplex-aware.
When running in a shared file system environment, configure all your systems with the same
zFS sysplex option. That is, run in one of the following ways:

All your systems with sysplex=filesys (recommended)

All your systems with sysplex=off

All your systems with sysplex=on

Chapter 8. File sharing in a sysplex
421
8.26 Using the sysplex=filesys parameter
Figure 8-26 Using the sysplex=filesys parameter
Using the sysplex=filesys parameter
Beginning with z/OS V1R11, zFS can be sysplex-aware for read-write mounted file systems.
zFS can be configured (zFS IOEFSPRM option sysplex=on) to treat all zFS read-write
mounted file systems owned on that system as sysplex-aware file systems or it can be
configured (zFS IOEFSPRM option sysplex=filesys) to allow some zFS read-write mounted
file systems owned on that system to be sysplex-aware file systems and some to be
non-sysplex aware file systems. zFS must be running sysplex-aware for read-write in order to
allow a zFS read-write file system to be mounted as sysplex-aware.
To enable zFS sysplex-aware on a file system basis, specify sysplex=filesys in the
IOEFSPRM configuration file. Leave the sysplex_filesys_sharemode with its default of
norwshare. You can specify it in a shared IOEFSPRM configuration file and each system
picks up the specification in a rolling IPL. The sysplex option is ignored by previous releases.
Any z/OS V1R9 or V1R10 systems in the shared file system environment must have zFS
APAR OA29786 active before you can have zFS sysplex=filesys active on any z/OS V1R11 or
later system.
If you are migrating from a shared file system environment with all systems running zFS
sysplex=on to a shared file system environment with all systems running zFS sysplex=filesys,
you should specify sysplex_filesys_sharemode=rwshare on each sysplex=filesys system
before you migrate with a rolling IPL. This way, each zFS read-write file system will be
(remain) sysplex-aware as you roll each system to sysplex=filesys even if you must unmount
and mount the file system.
To enable zFS sysplex-aware on a file system basis
Specify sysplex=filesys in the IOEFSPRM
configuration file
Leave the sysplex_filesys_sharemode with its default
of norwshare
You can specify it in a shared IOEFSPRM
configuration file and each system picks up the
specification in a rolling IPL
The sysplex option is ignored by previous releases
Any z/OS V1R9 or V1R10 systems in the shared file
system environment must have zFS APAR OA29786
active before you can have zFS sysplex=filesys active
on any
z/OS V1R11 system

422

ABCs of z/OS System Programming: Volume 9
8.27 Using the sysplex=filesys parameter
Figure 8-27 Using the sysplex=filesys parameter
Using sysplex=filesys
If you have (at least) APAR OA29619 and you intend to run zFS sysplex-aware on a file
system basis (sysplex=filesys), you must ensure that you have (at least) APAR OA29786 on
your prior releases.
When the BPXPRMxx parmlib member specifies SYSPLEX(YES), you can specify
sysplex=on or sysplex=filesys in the IOEFSPRM configuration file and perform an IPL. After
changing IOEFSPRM, you must perform an IPL or a restart of zFS. IPL is the recommended
method because in many ways it is less disruptive than a restart of zFS, which can cause zFS
file systems to become unmounted. This allows you to have zFS read-write sysplex-aware file
systems and z/OS UNIX does not forward file requests to the z/OS UNIX owning system.
Rather, z/OS UNIX typically sends requests to the local zFS and lets zFS take the
responsibility to forward the request, if necessary.
Sysplex-aware on a file system basis
zFS V1R11 to run in one of the following modes:

Sysplex-aware on a file system basis—that is, enabling zFS to run sysplex-aware, but
individually choosing which file systems are sysplex-aware for read-write and which ones
are not (enable by specifying sysplex=filesys in your IOEFSPRM and then perform a
rolling IPL).
sysplex=filesys - zFS can be configured
sysplex=filesys to allow some zFS read-write
mounted file systems owned on that system to be
sysplex-aware file systems and some to be
non-sysplex aware file systems
When you run sysplex=filesys, the zFS PFS runs
sysplex-aware, but each zFS file system is mounted
non-sysplex aware (by default)
zFS is enabled to allow zFS read-write file systems to
be sysplex-aware but it must be explicitly requested
on a file system basis

Chapter 8. File sharing in a sysplex
423

Sysplex-aware for all read-write zFS file systems—that is, enabling zFS to run
sysplex-aware, and having all zFS read-write file systems mounted sysplex-aware (enable
by specifying sysplex=on in your
IOEFSPRM
and then perform a rolling IPL).
Using sysplex-aware on a file system basis
If you decide that you want some zFS read-write file systems to be sysplex-aware, you can
run zFS sysplex-aware on a file system basis. Roll this support through all your sysplex
members (this assumes all your members are at z/OS V1R11 with the V1R11 APAR
OA29619 applied). You cannot change from zFS non-sysplex aware to zFS sysplex-aware on
a file system basis dynamically. After changing
IOEFSPRM
, you must perform an IPL or a restart
of zFS. IPL is the recommended method because in many ways it is less disruptive than a
restart of zFS, which can cause zFS file systems to become unmounted.
To enable zFS sysplex-aware on a file system basis, specify sysplex=filesys in the
IOEFSPRM

configuration file. Leave the sysplex_filesys_sharemode with its default of norwshare. You can
specify it in a shared
IOEFSPRM
configuration file and each system picks up the specification in
a rolling IPL. The sysplex option is ignored by previous releases. Any z/OS V1R9 or V1R10
systems in the shared file system environment must have zFS APAR OA29786 active before
you can have zFS sysplex=filesys active on any z/OS V1R11 system.
Note:
If you decide to run zFS non-sysplex aware, shared file system support works as in
prior releases. Ensure that you do not specify sysplex=on or sysplex=filesys in your zFS
IOEFSPRM configuration options file.

424

ABCs of z/OS System Programming: Volume 9
8.28 The sysplex_filesys_sharemode parameter
Figure 8-28 The sysplex_filesys_sharemode parameter
The sysplex_filesys_sharemode parameter
The sysplex_filesys_sharemode option on a system specifies whether a zFS read-write file
system will be mounted sysplex-aware when a MOUNT is issued on that system without
specifying either NORWSHARE or RWSHARE in the MOUNT PARM.
The default value for sysplex_filesys_sharemode is norwshare. This means that a MOUNT for
a zFS read-write file system that does not have NORWSHARE or RWSHARE specified in the
MOUNT PARM will result in the file system being non-sysplex aware. If you want all zFS
read-write mounts to be sysplex-aware, then specify sysplex_filesys_sharemode=rwshare.
This option can be specified in the IOEFSPRM configuration options file and takes effect on
the next IPL (or restart of zFS). It can also be specified dynamically with the
zfsadm config

-sysplex_filesys_sharemode command. Typically, you should have the same
sysplex_filesys_sharemode value on all your systems. Otherwise, z/OS UNIX file system
ownership movement might change the sysplex-awareness of a file system that does not
have NORWSHARE or RWSHARE specified in the MOUNT PARM).
If you decide that you want some zFS read-write file systems to be sysplex-aware, you can
run zFS sysplex-aware on a file system basis. Roll this support through all your sysplex
members (this assumes all your members are at z/OS V1R11 with the V1R11 APAR
OA29619 applied). You cannot change from zFS non-sysplex aware to zFS sysplex-aware on
a file system basis dynamically. After changing IOEFSPRM, you must perform an IPL or a
restart of zFS. IPL is the recommended method because in many ways it is less disruptive
than a restart of zFS, which can cause zFS file systems to become unmounted.
RWSHARE | NORWSHARE
Specifies whether a zFS read-write mounted file
system will be mounted sysplex-aware or
non-sysplex aware
zFS must be running sysplex-aware on a file system
basis (IOEFSPRM specifies sysplex=filesys) for this
parameter to take effect
The default for sysplex_filesys_sharemode is:
norwshare when running zFS as sysplex=filesys or
<no value>
Otherwise specify in the IOEFSPRM file, or
subsequently using the zfsadm config command

Chapter 8. File sharing in a sysplex
425
8.29 sysplex_filesys_sharemode considerations
Figure 8-29 sysplex_filesys_sharemode considerations
sysplex_filesys_sharemode considerations
The sysplex_filesys_sharemode option on a system specifies whether a zFS read-write file
system will be mounted sysplex-aware when a MOUNT is issued on that system without
specifying either NORWSHARE or RWSHARE in the MOUNT PARM. The default value for
sysplex_filesys_sharemode is norwshare. This means that a MOUNT for a zFS read-write file
system that does not have NORWSHARE or RWSHARE specified in the MOUNT PARM will
result in the file system being non-sysplex aware.
Sysplex-aware with rwshare
If you want all zFS read-write mounts to be sysplex-aware, then specify
sysplex_filesys_sharemode=rwshare. This option can be specified in the IOEFSPRM
configuration options file and takes effect on the next IPL (or restart of zFS). It can also be
specified dynamically with the
zfsadm config
-sysplex_filesys_sharemode command.
Typically, you should have the same sysplex_filesys_sharemode value on all your systems.
Otherwise, z/OS UNIX file system ownership movement might change the sysplex-awareness
of a file system that does not have NORWSHARE or RWSHARE specified in the MOUNT
PARM).
Do not make any zFS (R/W) file systems
sysplex-aware until you have all systems in the
shared file system environment at z/OS V1R11+
with sysplex=filesys active
To make a zFS read-write file system sysplex-aware
when running sysplex=filesys on all systems
You must unmount the file system
Specify RWSHARE as a mount PARM
Then mount the file system
The following TSO/E example shows a zFS mount
PARM of RWSHARE:
MOUNT FILESYSTEM('OMVS.PRV.COMPAT.AGGR001') TYPE(ZFS)
MOUNTPOINT('/etc/mountpt') PARM('RWSHARE')

426

ABCs of z/OS System Programming: Volume 9
Using sysplex-aware on all file systems
Do not make any zFS read-write file systems sysplex-aware until you have all systems in the
shared file system environment at z/OS V1R11 with sysplex=filesys active. To make a zFS
read-write file system sysplex-aware when running sysplex=filesys on all systems, you must
unmount the file system, specify RWSHARE as a mount PARM and then mount the file
system. The following TSO/E example shows a zFS mount PARM of RWSHARE:
MOUNT FILESYSTEM('OMVS.PRV.COMPAT.AGGR001') TYPE(ZFS)
MOUNTPOINT('/etc/mountpt') PARM('RWSHARE')
Note:
Although it is possible to change the sysplex_filesys_sharemode from its default of
norwshare to rwshare at IPL using the IOEFSPRM option or dynamically using the
zfsadm
config
command, this is not recommended while migrating from sysplex=off to
sysplex=filesys because it can cause performance problems.

Chapter 8. File sharing in a sysplex
427
8.30 sysplex_filesys_sharemode considerations
Figure 8-30 sysplex_filesys_sharemode considerations
sysplex_filesys_sharemode considerations
If you are migrating from a shared file system environment with all systems running zFS
sysplex=on to a shared file system environment with all systems running zFS sysplex=filesys,
you should specify sysplex_filesys_sharemode=rwshare on each sysplex=filesys system
before you migrate with a rolling IPL. This way, each zFS read-write file system will be
(remain) sysplex-aware as you roll each system to sysplex=filesys even if you must unmount
and mount the file system.
Mounts without specifying rwshare or norwshare
The sysplex_filesys_sharemode option on a system specifies whether zFS read-write file
system will be mounted sysplex-aware when a MOUNT is issued on that system without
specifying either NORWSHARE or RWSHARE in the MOUNT PARM.
The default value for sysplex_filesys_sharemode is norwshare. This means that a MOUNT for
a zFS read-write file system that does not have NORWSHARE or RWSHARE specified in the
MOUNT PARM will result in the file system being non-sysplex aware. If you want all zFS
read-write mounts to be sysplex-aware, then specify sysplex_filesys_sharemode=rwshare.
This option can be specified in the
IOEFSPRM
configuration options file and takes effect on the
next IPL (or restart of zFS). It can also be specified dynamically with the zfsadm config
-sysplex_filesys_sharemode command. Typically, you should have the same
sysplex_filesys_sharemode value on all your systems. Otherwise, z/OS UNIX file system
ownership movement might change the sysplex-awareness of a file system that does not
have NORWSHARE or RWSHARE specified in the MOUNT PARM).
If you are migrating from a shared file system
environment with all systems running zFS sysplex=on to
a shared file system environment with all systems
running zFS sysplex=filesys
You should specify sysplex_filesys_sharemode=rwshare
on each sysplex=filesys system before you migrate with
a rolling IPL
This way, each zFS read-write file system (remains)
sysplex-aware as you roll each system to sysplex=filesys
even if you must unmount and mount the file system
Sysplex root considerations

428

ABCs of z/OS System Programming: Volume 9
Rolling IPL
If you decide that you want all your zFS read-write file systems to be sysplex-aware, roll this
support as quickly as you can through all your sysplex members (this assumes all your
members are using z/OS V1R11 or later). You cannot change from zFS non-sysplex aware to
zFS sysplex-aware dynamically. After changing
IOEFSPRM
, you must perform an IPL or a
restart of zFS. IPL is the recommended method because in many ways it is less disruptive
than a restart of zFS, which can cause zFS file systems to become unmounted. To make all
your zFS read-write file systems sysplex-aware, specify sysplex=on in the
IOEFSPRM

configuration file. You can specify it in a shared
IOEFSPRM
configuration file and each system
picks up the specification in a rolling IPL. The sysplex option is ignored by previous releases.
Sysplex root considerations
Your sysplex root file system should be read-only. However, if your sysplex root file system is
normally read-write, you should make it sysplex-aware. You cannot unmount the sysplex root
file system, so you need an alternative method. One method is to replace your sysplex root
using the
MODIFY OMVS,NEWROOT
operator command, which is described in
z/OS UNIX System
Services Planning
, GA22-7800 and
z/OS MVS System Commands
, SA22-7627.
First move z/OS UNIX ownership of the file system, if necessary, to a system running zFS
sysplex=filesys that has sysplex_filesys_sharemode=rwshare. Then, replace your sysplex
root with a zFS sysplex root file system. Another method is to remount your sysplex root to
read-only, move z/OS UNIX ownership of the file system, if necessary, to a system running
zFS sysplex=filesys that has sysplex_filesys_sharemode=rwshare, and then remount the
sysplex root back to read-write.

Chapter 8. File sharing in a sysplex
429
8.31 zFS mixed environment
Figure 8-31 Running some zFS sysplex-aware and some zFS non-sysplex aware
Running some zFS sysplex-aware and some zFS non-sysplex aware
You can decide to run in a mixed environment with some systems running zFS sysplex-aware
(sysplex=on) and some systems running zFS non-sysplex aware (sysplex=off). In this
scenario, some zFS read-write file systems would be sysplex-aware and some zFS read-write
file systems would be non-sysplex aware.
However, a mixed environment is not recommended and is not necessary. That is, when you
have all systems at z/OS V1R11 with zFS APAR OA29619 applied, you can run all systems
zFS sysplex-aware on a file system basis (sysplex=filesys). A mixed environment can cause a
reduction in performance. If you want to continue to run a prior release in your sysplex, you
should keep running zFS non-sysplex aware. If you want to run the SMB server or the IBM
HTTP Server with Fast Response Cache Accelerator you should keep running zFS
non-sysplex aware or run all systems with zFS sysplex-aware on a file system basis.
If you still want to run with some systems running zFS sysplex-aware and some systems
running zFS non-sysplex aware, you will see a reduction in performance and you will have a
more complex environment. You will need to be more concerned with z/OS UNIX ownership
of zFS file systems. There are additional restrictions on file system ownership movement
when some systems are running zFS sysplex-aware and some systems are running zFS
non-sysplex aware. Typically, after a zFS file system is owned by a system running zFS
sysplex-aware, the file system cannot be moved to a system running zFS non-sysplex aware
without unmounting it, and then mounting the file system on the system running zFS
non-sysplex aware. This causes the failure of explicit moves (for example, the z/OS UNIX
chmount
command or the SETOMVS FILESYS operator command) and could cause implicit


Application
USS
Application
USS
zFS
Application
USS
zFS

zFS
F
/
F
F
F
F
R/W
Cache
Function
Ship
sysplex=on
SY1 SY2 SY3
sysplex=onsysplex=off
zFS owner
USS owner
client running
sysplex=off

430

ABCs of z/OS System Programming: Volume 9
moves during shutdown, recovery, or PFS termination (for example, for a file system mounted
AUTOMOVE with a system list) to fail.
zFS mixed configuration considerations
There are performance implications with running in a mixed environment. In some cases, the
performance might be poorer than running all zFS file systems non-sysplex aware. One
reason for this is that z/OS UNIX only performs caching of directory information on z/OS
UNIX clients when the read-write file system is non-sysplex aware. If the read-write file
system is sysplex-aware, z/OS UNIX does not perform directory caching. Any z/OS UNIX
client lookup request goes to the z/OS UNIX owning system through XCF communications
rather than potentially being satisfied in the local z/OS UNIX directory cache. This means that
explicitly choosing which system should be the z/OS UNIX owner of a read-write file system
in a mixed environment is a trade-off between the following two options:

Getting the benefit of zFS sysplex-aware among the zFS sysplex-aware systems by
making the zFS file system sysplex-aware.

Getting the benefit of z/OS UNIX directory caching for all systems and no benefit of zFS
sysplex-aware by making the zFS file system non-sysplex aware.
This is further complicated by the fact that after a zFS file system is sysplex-aware, you
cannot explicitly move it to a system running zFS non-sysplex aware, unless every other
system is doing z/OS UNIX function shipping to this system for that file system; that is, every
other system shows Client=Y for that file system. In general, if there are more systems
running zFS sysplex-aware than not, it is most likely better to have the zFS read-write file
system be sysplex-aware for overall sysplex z/OS UNIX application performance. If you let
z/OS UNIX choose the system to own the zFS read-write file system (for example, during
shutdown or dead system recovery), z/OS UNIX chooses the z/OS UNIX owner randomly
(unless, of course, you have specified a system list on MOUNT). Normally, after a read-write
file system is sysplex-aware, it is only moved to systems running zFS sysplex-aware.

Chapter 8. File sharing in a sysplex
431
8.32 zFS cache management
Figure 8-32 zFS cache management
zFS cache management
z/OS UNIX typically sends requests to the local zFS and lets zFS take the responsibility to
forward the request, if necessary. Cache consistency is maintained through a token
management mechanism. This typically provides improved performance in a shared file
system environment.
When zFS is running sysplex-aware for read-write file systems, a new cache is added to zFS
controlled by the client_cache_size IOEFSPRM configuration option. The client_cache_size
option is used to cache user data when zFS files are accessed from a system that is not the
zFS owner of the file system. The default size is 128 MB. This is in addition to the existing
user_cache_size option, which is used when zFS files are accessed from a system that is the
zFS owner of the file system.
For read-write mounted file systems, file requests are sent directly to zFS, which in turn
function ships the request to the zFS owning system. In many cases, zFS does not need to
function ship the request to the owning zFS system because the data is in the local cache.
zFS caches data to avoid frequent forwarding to an owner, and this typically improves
performance for most workloads. The zFS owning system is the only system that does I/O to
the file system. In this case, zFS is running sysplex-aware for read-write mounted file
systems.
Cache consistency is maintained through a token management mechanism. This typically
provides improved performance in a shared file system environment.
When the zFS PFS is sysplex-aware
z/OS UNIX sends requests to the local zFS and zFS takes
on the responsibility to forward the request, if necessary
For many requests, it is not necessary because zFS
caches data locally and satisfies the request from its cache
Cache consistency is maintained through a token
management mechanism and may provide improved
performance in a shared file system environment
If it is a read or lookup or readdir and the data is contained
in the cache, the request can be satisfied without
communication with the zFS owning system
Write requests are written forwarded to the owner system
Caching improves performance

432

ABCs of z/OS System Programming: Volume 9
8.33 zFS sysplex-aware on a file system basis
Figure 8-33 zFS sysplex-aware on a file system basis
zFS sysplex-aware on a file system basis
With z/OS V1R12 and V1R11, to enable zFS sysplex-aware on a file system basis, specify
sysplex=filesys in the
IOEFSPRM
configuration file. Leave the sysplex_filesys_sharemode with
its default of norwshare. You can specify it in a shared
IOEFSPRM
configuration file and each
system picks up the specification in a rolling IPL. The sysplex option is ignored by previous
releases. Any V1R10 systems in the shared file system environment must have zFS APAR
OA29786 active before you can have zFS sysplex=filesys active on any z/OS V1R11 and
z/OS V1R12 systems.
When you run zFS sysplex-aware on a file system basis on all your members, the zFS
Physical File System initializes as sysplex-aware but it can individually determine which file
system is sysplex-aware and which is not based on the mount parameters rwshare and
norwshare.
Note:
MOUNT commands for file systems in Figure 8-33.

For file system FS2
MOUNT FILESYSTEM('OMVS.PRV2.COMPAT.AGGR001') TYPE(ZFS)
MODE(RDWR) MOUNTPOINT('/usr/mountpt2') PARM('RWSHARE')

For file system FS1
MOUNT FILESYSTEM('OMVS.PRV1.COMPAT.AGGR001') TYPE(ZFS)
MODE(RDWR) MOUNTPOINT('/usr/mountpt1') PARM('NORWSHARE')


Application
USS
Application
USS
zFS
Application
USS
zFS
F
/
F
F
F
F

zFS
File
File
Admin Admin
FS1 - R/W, norwshare
SY1
SY2
SY3
owning system,
FS1 and FS2
Cache
Cache
owning system,
FS2
F
/
F
F
F
F
FS2 - R/W, rwshare
sysplex-unaware
sysplex-aware
sysplex=filesys

Chapter 8. File sharing in a sysplex
433
Mixed sysplex example - sysplex-aware on a file system basis
Figure 8-33 shows three systems with zFS sysplex-aware on a file system basis
(
sysplex=filesys
). There are two zFS read-write file systems on a sysplex running zFS
sysplex-aware on a file system basis on all members. One file system is mounted
NORWSHARE

and the other is mounted
RWSHARE
. They are both z/OS UNIX owned by system SY2.
The norwshare file system is a non-sysplex-aware file system. It is only locally mounted on
the z/OS UNIX owner and requests from z/OS UNIX clients are function shipped to the z/OS
UNIX owner by z/OS UNIX.
The other file system shown in Figure 8-33 on page 432 is mounted rwshare. It is a
sysplex-aware file system and locally mounted on all systems; and z/OS UNIX never function
ships requests to the z/OS UNIX owner.
After you have sysplex=filesys active on all your systems, you can consider which zFS
read-write file systems you want to be sysplex-aware. Good candidates are zFS read-write
file systems that are accessed from multiple systems or are mounted with AUTOMOVE and
might be moved by z/OS UNIX (as a result of a shutdown or IPL) to systems that do not
necessarily do the most accesses.
If you decide that you want some zFS read-write file systems to be sysplex-aware, you can
run zFS sysplex-aware on a file system basis. Roll this support through all your sysplex
members (this assumes all your members are at z/OS V1R11 with the V1R11 APAR
OA29619 applied). You cannot change from zFS non-sysplex aware to zFS sysplex-aware on
a file system basis dynamically. After changing
IOEFSPRM
, you must perform an IPL or a restart
of zFS. IPL is the recommended method because in many ways it is less disruptive than a
restart of zFS, which can cause zFS file systems to become unmounted.
Note:
To enable zFS sysplex-aware on a file system basis, specify sysplex=filesys in the
IOEFSPRM
configuration file. Leave the sysplex_filesys_sharemode with its default of
norwshare. You can specify it in a shared
IOEFSPRM
configuration file and each system
picks up the specification in a rolling IPL. The sysplex option is ignored by previous
releases. Any z/OS V1R9 or V1R10 systems in the shared file system environment must
have zFS APAR OA29786 active before you can have zFS sysplex=filesys active on any
z/OS V1R11 system.
Attention:
When you run sysplex=filesys, the zFS PFS runs sysplex-aware, but each zFS
file system is mounted non-sysplex aware (by default). zFS is enabled to allow zFS
read-write file systems to be sysplex-aware but it must be explicitly requested on a file
system basis. Note that although it is possible to change the sysplex_filesys_sharemode
from its default of norwshare to rwshare at IPL using the IOEFSPRM option or dynamically
using th z
fsadm config
command, this is not recommended while migrating from
sysplex=off to sysplex=filesys because it can cause performance problems.

434

ABCs of z/OS System Programming: Volume 9
8.34 Automatic movement of file systems
Figure 8-34 Automatic movement of file systems
Automatic movement of file systems
Figure 8-34 shows again the three systems with zFS sysplex-aware on a file system basis
(
sysplex=filesys
). However, this time the sysplex-aware zFS has two different owners.
Beginning with z/OS V1R11, as a part of supporting read-write mounted file systems that are
accessed as sysplex-aware, zFS automatically moves zFS ownership of a zFS file system to
the system that has more read-write activity coming from it compared to the total amount from
all systems.
This is because zFS can move its ownership of zFS read-write sysplex-aware file systems
dynamically based on system usage among zFS systems where the file systems are locally
mounted. If one sysplex member is a better fit for ownership, because more requests to the
file system are being done there than on any other sysplex member, then zFS dynamically
moves the zFS ownership to that system.


Application
USS
Application
USS
zFS
Application
USS
zFS
F
/
F
F
F
F

zFS
File
File
Admin Admin
SY1
SY2
SY3
Cache
sysplex=filesys
F
/
F
F
F
F
automatic move
owning system,
FS1 and FS2
owning system,
FS2
FS1 - R/W, norwshare
FS2 - R/W, rwshare
Cache

© Copyright IBM Corp. 2011. All rights reserved.
435
Chapter 9.
Managing file systems
This chapter describes the hierarchical file system and how to customize it to your
requirements. In addition to providing an introduction to HFS concepts, it provides details on
how to:

Manage and create a hierarchical file system

Use commands to display useful information

Perform space management for a hierarchical file system
9

436

ABCs of z/OS System Programming: Volume 9
9.1 Hierarchical file system (HFS)
Figure 9-1 Hierarchical file system structure
Hierarchical file system structure
The z/OS UNIX file system is hierarchical and byte-oriented. Finding a file in the file system is
done by searching a directory or a series of directories. There is no concept of a z/OS catalog
that points directly to a file.
z/FS and HFS are both UNIX file systems and both can participate in shared sysplexes.
However, while HFS always has a single file system per data set, zFS may have multiple file
systems in a single data set. These data sets are called
aggregates
and are a collection of
data sets.
A path name identifies a file and consists of directory names and a file name. A fully qualified
file name, which consists of the name of each directory in the path to a file plus the file name
itself, can be up to 1023 bytes long, for example: /u/joe/projects/p1/prog1.
The hierarchical file system allows for file names in mixed case. The files in the hierarchical
file system are sequential files, and they are accessed as byte streams. A record concept
does not exist with these files, other than the structure defined by an application.
The files can be text files or binary files. In a text file, each line is separated by a
newline
delimiter
. A binary file consists of sequences of binary words, and the application reading or
writing to the file is responsible for the format of the data.
A file name can be up to 255 characters long. HFS data sets, zFS data sets, and z/OS data
sets can reside on the same SMS-managed DASD volume.
HFS data set or zFS data set
Directory
Directory
Directory
Directory
Directory
Directory
File
File
File
File
File
File
File
File
File
File

Chapter 9. Managing file systems
437
9.2 File linking
Figure 9-2 File linking
File linking
A
link
is a new pathname, or directory entry, for an existing file. The new directory entry can
be in the same directory that holds the file, or in a different directory. You can access the file
under the old pathname or the new one. After you have a link to a file, any changes you make
to the file are evident when it is accessed under any other name. Links are useful when:

A file is moved and you want users to be able to access the file under the old name.

You want to create a link with a short pathname (an alias) for a file that has a long
pathname.
You can use the
ln
command to create a hard link or a symbolic link. A file can have an
unlimited number of links to it.
Hard link
A
hard link
is a new name for an existing file. You cannot create a hard link to a directory, and
you cannot create a hard link to a file on a different mounted file system.
Symbolic link
A
symbolic link
is another file that contains the pathname for the original file—in essence, a
reference to the file. A symbolic link can refer to a pathname for a file that does not exist.
External link
A file can be an
external link
to a sequential data set, a PDS, or a PDS member.
Hard link
ln oldfile newfile
newfile becomes a new pathname for the existing file
oldfile - If oldfile names a symbolic link, link creates a
hard link to the file
Symbolic link
A symbolic link is another file that contains the
pathname for the original file
External link
An external link is a special type of symbolic link, a
file that contains the name of an object outside of the
hierarchical file system

438

ABCs of z/OS System Programming: Volume 9
9.3 Hard links
Figure 9-3 Hard link example
Hard links
A hard link is a new name for an existing file. You cannot create a hard link to a directory, and
you cannot create a hard link to a file on a different mounted file system.
All the hard link names for a file are as important as its original name. They are all real names
for the one original file. To create a hard link to a file, use this command format:
ln old new
When you create a hard link to a file, the new filename shares the inode number of the
original physical file. Because an inode number represents a physical file in a specific file
system, you cannot make hard links to other mounted file systems.
INODE
The
inode
is the internal structure that describes the individual files in the operating system;
there is one inode for each file. An inode contains the node, type, owner, access times,
number of links, and location of a file. A table of inodes is stored near the beginning of a file
system. The file system is used to store data and organize it in a hierarchical way by using file
system entries such as directories and files. These file system entries have certain attributes,
such as ownership, permission bits, and access time stamps. The data and the attributes of a
file are stored with the file in the file system. All file attributes are stored in a control block that
is sometimes called the inode.
The inode number specifies a particular inode file in the file system.
Hard link - Used to define an alternate path to a file (alias)
l
n /place/zoo/cage/lion /place/house/cat
/
place
zoo
cage
cat
house
lion
hard link
primary
path
alternate
path
(inode 1023)
(inode 1023)

Chapter 9. Managing file systems
439
9.4 Symbolic links
Figure 9-4 Symbolic link examples
Symbolic links
A symbolic link is a type of file system entry that contains the pathname of, and acts as a
pointer to another file or directory.
You can create a symbolic link to a file or a directory. Additionally, you can create a symbolic
link across mounted file systems, which you cannot do with a hard link. A symbolic link is
another file that contains the pathname for the original file—in essence, a reference to the file.
A symbolic link can refer to a pathname for a file that does not exist. To create a symbolic link
to a file, use this command format:
ln -s old new
where
new
is the name of the new file containing the reference to the file named
old
. In
Figure 9-4, /house/room/cat is the name of the new file that contains the reference to
/place/zoo/cage/lion.
When you create a symbolic link, you create a new physical file with its own inode number, as
shown in the figure. Because a symbolic link refers to a file by its pathname rather than by its
inode number, a symbolic link can refer to files in other mounted file systems.
/
place
zoo
cage
lion
/
house
room
cat
symbolic link
ln -s /place/zoo/cage/lion /house/room/cat
(inode 1043)
(inode 1023)
Symbolic link refers to a file by its pathname rather than its inode number
A symbolic link can refer to a file in another mounted file system
HFS1 or zFS1
HFS2 or zFS2

440

ABCs of z/OS System Programming: Volume 9
9.5 External links
Figure 9-5 Defining external links
External links
An external link is a special type of symbolic link. It is a file that contains the name of an
object that is outside of the hierarchical file system.
DFSMS/NFS uses this link to access z/OS data sets.
An example of defining an external link is to make a link between an HFS file and an MVS
program, as follows:

Define an HFS file as:
/usr/lpp/db2/db2910

Where the MVS program name IMWYWWS is an external link, the command to define the
external link is:
ln -e DSNAQLDA /usr/lpp/db2/db2910/lib/libdb2os390j2.so
When you are done, you have created an external link that can be used to access an MVS
load library.
Using an external link, you associate that object with a pathname. For example,
setlocale()

searches for locale object files in the HFS, but if you want to keep your locale object files in a
partitioned data set, you can create an external link in the HFS that points to the PDS. This
will improve performance by shortening the search that
setlocale()
makes.
Links to an object outside of the HFS
ln -e DSNAQLDA /usr/lpp/db2/db2910/lib/libdb2os390j2.so
old
/usr/lpp/db2/db2910
/lib
libdb2os390j2.so
new
DB2.SDSNLOD2
PDSE
(DSNAQLDA)
Search order for module:
STEPLIB
LPA
LNKLST

Chapter 9. Managing file systems
441
A file can be an external link to a sequential data set, a PDS, PDSE, or a PDS member.
External link examples
Consider the following examples:
ln -e SYS1.PRIVATE.PGMA /u/ggi/plib/pgma
ln -e PGMPDS /u/ggi/plib/pgm
The second example assumes that the PGMPDS member will be found in a PDS library,
using the traditional z/OS search order. Because of performance considerations, put the
library into the LPA or LNKLST.

442

ABCs of z/OS System Programming: Volume 9
9.6 File system structure
Figure 9-6 File system structure
File system structure
The z/OS UNIX file system can consist of multiple file systems joined together to form a
hierarchical file system. Connecting one file system to another is called
mounting
.
The root file system is the first file system that is mounted, and subsequent file systems can
be mounted on a directory in a file system that is already mounted. The file systems will form
a hierarchy of file systems. A file system must be mounted before anybody can access it.
An HFS or zFS data set is a mountable file system. A mountable file system can be logically
mounted to a mount point, which is a directory in another file system, with a TSO/E MOUNT
command. A mountable file system can be unmounted from a mount point with a TSO/E
UNMOUNT command. ISPF users can also perform these tasks using the ISPF shell.
Build a directory in the root file system. A directory can be used as a mount point for a
mountable file system. The mount point should be an empty directory; otherwise, its contents
will be hidden for the duration of any subsequent mounts.
Note:
If you want to unmount ZFS1, you first have to unmount ZFS2 or the system will tell
you that the resource is busy. However, you can unmount by using the immediate option or
the force option without first unmounting ZFS2. If users are working on those directories,
they will get errors trying to list the current directories.
Dir
Dir
Dir
Dir
Dir
F
F
F
F
F
Dir
Dir
F
F
Dir
/
HFS1
HFS1
Dir
F
F
Dir
ZFS1
F
F
F
ZFS2
/
/
/
Multiple HFS, zFS data sets

Chapter 9. Managing file systems
443
9.7 Temporary directory space
Figure 9-7 Temporary file system and temporary directory space
Temporary directory space
When compiling C programs, the compiler will use the /tmp directory for temporary files.
When compiling large applications, the /tmp directory can use a lot of space. Use a separate
file system for temporary data. In this way, a maximum of one volume will be used for
temporary space.
Separate file system
Placing the /tmp directory in a separate file system can also improve performance in a system
with a large number of interactive z/OS UNIX users, where the I/O activity can be very high on
the /tmp directory. Do this with the following procedure:

Allocate an HFS data set for the temporary data file system, for example:
OMVS.<SYSNAME>.TMP.HFS

Mount this data set on the /tmp directory in the root file system. When data is written to
files in the /tmp directory, the data will be physically located in the
OMVS.<SYSNAME>.TMP.HFS file system.
Temporary file system (TFS)
When you have a large number of interactive users, the /tmp directory can sustain large
amounts of I/O activity. There are several approaches you can take:
tmp
/
Root-HFS
OMVS.<SYSNAME>.TMP.HFS
Can be a real HFS or a TFS
$HOME/tmp

444

ABCs of z/OS System Programming: Volume 9

Mount a temporary file system (TFS) over /tmp in the HFS, so that you have a high-speed
file system for temporary files. The temporary file system is an in-memory file system that
is not written to DASD.

Place the /tmp directory in its own mountable file system and put the file system on its own
pack.

Reduce /tmp activity by setting the TMPDIR environment variable to $HOME/tmp in each
user's .profile. This causes various utilities to put temporary files in the user's $HOME/tmp
directory rather than in the common /tmp directory.
Recommendations
It is suggested that you place the temporary data in a separate file system. In this way, it will
be easier to manage the space used by temporary files. How much temporary space is
needed will depend on how z/OS UNIX is used. When the C compiler is invoked from the
z/OS UNIX shell, the /tmp directory will be used for temporary data. Miscellaneous shell
commands use the /tmp directory as well. If the z/OS UNIX shell is not installed, there will
probably not be that much activity in the /tmp directory.
Another reason for placing the /tmp in a separate file system is to improve file system
performance. If there is a lot of I/O activity on the /tmp directory, it would improve the
performance if the OMVS.<SYSNAME>.TMP.HFS file system is placed on a different volume
than the root file system.

Chapter 9. Managing file systems
445
9.8 Temporary file system (TFS)
Figure 9-8 Temporary file system and temporary file system address space
Temporary file system (TFS)
The /tmp (temporary) directory is where many programs running on the system keep
temporary copies of files or data. Users often use the tmp directory for working space
knowing that they should not put anything out there that they want to keep. Currently the /tmp
directory is part of the root HFS data set. The data in /tmp is not automatically deleted unless
you have set up some mechanism (like the cron automation daemon) to delete the data at
certain intervals. If the data is not deleted, you could run into space problems over time.
The TFS is an in-memory physical file system that supports in-storage mountable file
systems. Because it is an in-memory file system, all data that is written to a TFS is lost over
an IPL. This makes it a good candidate for the /tmp directory. Not only do you get a new clean
/tmp file system at each IPL, you also get very high I/O access because it resides in a data
space that is part of the kernel address space.
Creating a TFS
The ServerPac installation jobs already defined the following FILESYSTYPE definition in
SYS1.PARMLIB(BPXPRMFS):
FILESYSTYPE TYPE(TFS) ENTRYPOINT(BPXTFS)
FILESYSTYPE TYPE(TFS) ENTRYPOINT(BPXTFS)
MOUNT FILESYSTEM('/TMP') TYPE(TFS)
MOUNTPOINT('/tmp')
PARM(' -s 10')
BPXPRMxx
tmp
/
TFS
Root-HFS
TFS address space
TFS

446

ABCs of z/OS System Programming: Volume 9
Edit SYS1.PARMLIB(BPXPRMFS), that is, add the mount statement to mount an in-memory
file system at the /tmp mount point. You can add the following mount statement right under
the FILESYSTYPE TYPE(TFS) definition:
MOUNT FILESYSTEM('/TMP')
MOUNTPOINT('/tmp')
TYPE(TFS)
PARM('-s 10')
(-s 10) allocates 10MB of storage.
Figure 9-8 shows the mount command for a TFS. Normally this would be included in
BPXPRMxx. Key points to remember are the following:

The file system name should be unique. If you use the pathname of the mount point, it will
simplify the understanding of the output of the
df
command.

Type must be a
TFS
.

Mountpoint is /tmp.
Parm
specifies how much virtual storage the TFS should use. The default is 1 MB;
PARM
(-s 10)
specifies 10 MB.

You cannot mount a TFS using a DDname.

If unmounted, all data stored in a TFS is lost; when remounted, the file system has only
dot(.) and dot-dot(..) entries.

Chapter 9. Managing file systems
447
9.9 Colony address space
Figure 9-9 Colony address spaces
z/OS UNIX colony address spaces
The standard z/OS UNIX Physical File Systems (PFS) run as tasks in the kernel address
space. However, it is possible to package a physical file system component in a separate
address space, called a
colony address space
.
The Logical File System in the kernel provides the linkage to the new PFS in the colony
address space. To a z/OS UNIX user application, there is no difference in interaction between
accessing the standard PFS and one in a colony address space.
Running a PFS in a colony address space has some advantages, as follows:

It is a simpler way for other components to add a new PFS to z/OS UNIX environment.

A PFS can use a different security ID to kernel, and allocate its own z/OS data sets.

A PFS can run as a standard process with normal C/C++ SYSCALL linkages.
When a PFS runs in a colony address space, an extra address space is created, and each
PFS operation has a slightly longer path length.
Note:
The cataloged procedure (named with ASNAME) must contain the statement:
EXEC PGM=BPXVCLNY
BPXPRMxx
FILESYSTYPE TYPE(NFS)
ENTRYPOINT(GFSCINIT)
ASNAME(NFSCLNT)
FILESYSTYPE TYPE(TFS)
ENTRYPOINT(BPXTFS)
ASNAME(TFSPROC)
Procedure name
in SYS1.PROCLIB
MOUNT FILESYSTEM('/SPEED') TYPE(TFS)
MOUNTPOINT('/speed')
PARM(' -s 10')
Logical File
System
Physical
File
Systems
HFS
I/O
syscall
NFS
Client
SYS1.PROCLIB
NFSCLNT
TFS
TFSPROC
OMVS Kernel

448

ABCs of z/OS System Programming: Volume 9
Creating colony address spaces
The following tasks must be performed to run the colony address space:

Define FILESYSTYPE TYPE(TFS) in BPXPRMxx.

Use a procedure name for the TFS, in the ASNAME in the BPXPRMxx.

Define a profile in the started class for the procedure name.

Add the MOUNT FILESYSTEM('/xxxx') to the BPXPRMxx.

IPL the system.
The RACF profile for started class could look like:
RDEFINE STARTED TFSPROC.** -
STDATA(USER(OMVSKERN) GROUP(OMVSGRP) TRUSTED(NO))
For physical file systems that do not run in the kernel address space, ASNAME specifies the
name of the procedure in SYS1.PROCLIB used to start the address space in which this PFS
will be initialized. The procedure name is also used as the name of the address space. For
example, for the NFS client, you must create a procedure to run a PFS in a colony address
space.

Chapter 9. Managing file systems
449
9.10 Mounting file systems
Figure 9-10 Ways to mount zFS file systems
Ways to mount file system
A file system is the entire set of directories and files, consisting of all HFS files shipped with
the product and all those created by the system programmer and users. The system
programmer (superuser) defines the root file system; subsequently, a superuser can mount
other mountable file systems on directories within the file hierarchy. Altogether, the root file
system and mountable file systems comprise the file hierarchy used by shell users and
applications.
Figure 9-10 shows the different methods of mounting file systems.
UNIX shell mounts
The REXX exec
/usr/sbin/unmount
performs essentially the same functions that the TSO/E
mount
command performs. You can run it from the shell.
For hierarchical file systems, you can use the
chmount
command to logically mount, or add, a
mountable file system to the file system hierarchy. This is the same command used by the
REXX exec
/usr/sbin/mount
.
TSO mounts
Have an authorized user enter a TSO/E
mount
command to logically mount the file system.
Using the File Systems pull-down from the ISHELL panel and Option 3, you can perform the
mount for a file system.
Using the usr/sbin/mount REXX exec from the shell
Using the TSO MOUNT command
Using the mount shell command (/usr/sbin)
Using the ISHELL File_Systems pull-down
Adding a mount statement to the BPXPRMxx
member in SYS1.PARMLIB so that it will be
mounted when the system re-IPLs
Direct mount
Automount facility

450

ABCs of z/OS System Programming: Volume 9
PARMLIB mounts
The MOUNT statement defines the hierarchical file systems to be mounted at initialization
and where in the file hierarchy they are to be mounted. It is up to the installation to ensure that
all HFS data sets specified on MOUNT statements in the BPXPRMxx PARMLIB member are
available at IPL time.
z/OS UNIX mounting
For a direct mount, you need to allocate an intermediate HFS data set to be mounted
between the root file system and all user file systems. Create a mount point using the
mkdir

command and issue the
mount
command. (To make the mount permanent you will also need
to add the HFS data set name and its mount point to the BPXPRMxx member of PARMLIB.)
Using the automount facility simplifies management of file systems. You do not need to mount
most file systems at initialization and you do not need to request that operators perform
mounts for other file systems. In addition, it is easier to add new users because you can keep
your PARMLIB specification stable. You can establish a simple automount policy to manage
user home directories.

Chapter 9. Managing file systems
451
9.11 Mount and unmount
Figure 9-11 Mounting of file system considerations
Mounting and unmounting file systems
A file system must be mounted before it can be accessed. When z/OS UNIX is started, the
root file system is mounted as the first file system. All other file systems included on the
MOUNT statements in the BPXPRMxx members or mounted with the TSO command
MOUNT will be mounted on the root file system or on other file systems.
A file system can be mounted in read/write mode or in read-only mode. If it is mounted in
read-only mode, nobody can update any files or directories in the file system. To change the
mount mode, the file system must be unmounted and then remounted with a mode of
read/write.
A file system must be mounted on a directory; this is called a
mount point.
Use empty
directories as mount points. If a directory is not empty, the existing files will be overlapped by
the file system which is mounted on the directory. When this file system is unmounted, the
existing files will be accessible and visible again.
Superuser authority is required to mount or unmount a file system. That means the user must
have a OMVS UID(0) or have a RACF profile that defines superuser authority for the user.
If the file system does not need to be updated, it could be mounted in a read-only mode. This
will improve the performance. However, if a file system mounted as read-only needs updates,
it must be unmounted and remounted again.
ZFS
F
Dir
Dir
Dir
Dir
Dir
F
F
F
F
F
Dir
F
F
Dir
Dir
Dir
F
Dir
/
ZFS
ZFS
mount
points
F
F
When the ZFS is
mounted, these files
will be hidden and
will no longer be
accessable until the
ZFS is unmounted.
(superuser authority required for mounts)
/
/

452

ABCs of z/OS System Programming: Volume 9
9.12 Managing user file systems
Figure 9-12 Managing the mounting of file systems of z/OS UNIX users
Ways to mount
When a user requires an HFS or zFS file system to be accessed, you need to get it mounted
at a mount point off of the root directory to make it available. The preferred place to mount all
user HFS or zFS file systems is the
/u
mount point. In z/OS UNIX, there are two ways to
accomplish this:
Direct mount
Allocate an intermediate HFS data set to be mounted between the root file
system and all user file systems.
Create a mount point using the
mkdir
command and issue the
mount

command. To make the mount permanent you will also need to add the
HFS data set name and its mount point to the BPXPRMxx member of
PARMLIB.
Automount
You need to customize the automount facility to control all user file systems
to automatically mount them when they are needed. This is the preferred
method to manage user HFS data sets because it saves administration
time.
The automount facility lets you designate directories as containing only
mount points. This is the preferred method of managing user HFS file
systems. As each of these mount points is accessed, an appropriate file
system is mounted. The mount point directories are internally created as
they are required. Later, when the file system is no longer in use, the mount
point directories are deleted.
Mount user file systems at the /u mount point
Two ways to mount:
(1). Direct mount (2) Automount facility
joe
bill
u

Chapter 9. Managing file systems
453
9.13 User file systems: Direct mount
Figure 9-13 Mounting user file systems with direct mount
Direct mount
You should set up the root file system so that it does not require frequent changes. This can
be accomplished by putting user data in user file systems. The
/u
directory contains the user
home directories; if these directories are placed in separate file systems, most of the user
data will be kept out of the Root file system.
The UNIX System Service programmer can choose to use only one HFS for all users, or use
one HFS per user. If the user HFS is too small, you can mount some of the users to another
user's HFS, or increase the user space for the HFS. This will make it easier to manage the
HFS.
User home directory
A recommendation is to name the user home directories
/u/userid
with the user ID in
lowercase, for example
/u/joe
for user JOE as shown in the visual.
Following is a suggested method for creating user file systems:

Leave the /u directory in the root file system empty.

Create an HFS file called OMVS.<SYSNAME>.USERS.HFS.
jane
bill
joe
Dir
F
F
Dir
Dir
F
F
F
Dir
Dir
F
F
Dir
Dir
F
OMVS.<SYSNAME>.USERS.HFS
u
/
Root-HFS
OMVS.<SYSNAME>.JOE.HFS
OMVS.<SYSNAME>.BILL.HFS
OMVS.<SYSNAME>.JANE.HFS

454

ABCs of z/OS System Programming: Volume 9
This file system will contain the home directories for all users, and will be mount points for
the user file systems. The reason for keeping these home directories in a separate file
system is to avoid updating the root file system each time a new home directory is created
or deleted. The second qualifier of the DSNAME identifies the z/OS system image it
relates to.

Create a file system for each user or for a department, depending on what is best for the
installation. The user file systems can be called OMVS.<SYSNAME>.<userid>.HFS.
The user file systems will be mounted on the home directories in the
OMVS.<SYSNAME>.USERS.HFS file system.
Define a file system for user directories
You should have a separate file system just to contain the user's home directories. These
home directories will be empty, and they will act as mount points for the user file systems.
Depending on how the installation is organized and on the need for user space, each user
can have their own file system, or users in a department can share a system. It is easier to
control space usage when each user has their own file system. It can be compared to users
having their own z/OS data set for user data, or their own minidisk on VM. How large it should
be depends entirely on who will use it and what the user will do. If multiple users share an
HFS data set, it is not possible to guarantee space for each user. One user can dominate the
space in a file system shared between multiple users.
When making plans for a file structure, it is important to think about a naming convention for
the HFS data sets. If the automount facility will be used, one of the data set qualifiers should
be equal to the directory name where the file system will be mounted.

Chapter 9. Managing file systems
455
9.14 Mounting file systems
Figure 9-14 How to mount file systems
Mounting from the ISHELL
The ISHELL is a powerful application based on ISPF. You can do many things with the menu
shown at the top of Figure 9-14. The eight menu options have the following meanings:
File
Edit, browse, delete, copy, rename, print, run, and so on
Directory
List, create, rename, print, find string, and so on
Special_file
New FIFO, link, Attribute, delete, rename, and so on
Tools
Processes, Shell commands, run programs, and so on
File_systems
Mount, unmount, change attribute, allocate HFS, and so on
Options
Directory list, edit, browse, settings, and so on
Setup
User and Group Admin., create TTY, RACF permit Field, and so on
Help
Action code, Help, Keys help, About, and so on
Mounting from TSO/E
A file system can be mounted by using the TSO/E MOUNT command or the ISHELL.
Superuser authority is required for mounting or unmounting a file system.
The options for the MOUNT command are the same as for the MOUNT statement in
BPXPRMxx, except for an additional option called
WAIT
or
NOWAIT
. This option specifies
whether to wait for an asynchronous mount to complete before returning.
MOUNT FILESYSTEM('OMVS.JANE.HFS')
MOUNTPOINT('/u/jane') TYPE(HFS) MODE(RDWR)
UNMOUNT FILESYSTEM('OMVS.JOE.HFS') NORMAL
TSO/E Commands
3

456

ABCs of z/OS System Programming: Volume 9
The syntax for the UNMOUNT command is as follows:
UNMOUNT FILESYSTEM(file_system_name)
DRAIN | FORCE | IMMEDIATE | NORMAL | REMOUNT(RDWR | READ) | RESET
DRAIN
Specifies that an unmount drain request is to be made. The system will wait
for all use of the file system to be ended normally before the unmount
request is processed or until another UNMOUNT command is issued.
FORCE
Specifies that the system is to unmount the file system immediately. Any
users accessing files in the specified file system receive failing return
codes. All data changes to files in the specified file system are saved, if
possible. If the data changes to the files cannot be saved, the unmount
request continues and data is lost.
IMMEDIATE
Specifies that the system is to unmount the file system immediately. Any
users accessing files in the specified file system receive failing return
codes. All data changes to files in the specified file system are saved. If the
data changes to files cannot be saved, the unmount request fails.
NORMAL
Specifies that if no user is accessing any of the files in the specified file
system, the system processes the unmount request. Otherwise, the system
rejects the unmount request. This is the default.
REMOUNT
(RDWR|READ) Specifies that the specified file system be remounted,
changing its mount mode. REMOUNT takes an optional argument of
RDWR or READ. If you specify either argument, the file system is
remounted in that mode if it is not already in that mode. If you specify
REMOUNT without any arguments, the mount mode is changed from
RDWR to READ or READ to RDWR.
RESET
A reset request stops a previous UNMOUNT DRAIN request.
WAIT
Specifies that MOUNT is to wait for the mount to complete before returning.
WAIT is the default.
NOWAIT
Specifies that if the file system cannot be mounted immediately (for
example, a network mount must be done), then the command will return
with a return code indicating that an asynchronous mount is in progress.

Chapter 9. Managing file systems
457
9.15 Option 3: Mount
Figure 9-15 Mounting file systems from the ISHELL with Option 3
Mounting from the ISHELL
The ISHELL command invokes the z/OS ISPF shell, a panel interface that helps you to set up
and manage z/OS UNIX System Services functions such as mounting of file systems.
To mount a file system, you must be a superuser.
If you are a user with an MVS background, you may prefer to use the ISPF shell panel
interface instead of shell commands or TSO/E commands to work with the file system. The
ISPF shell also provides the administrator with a panel interface for setting up users for z/OS
UNIX access, for setting up the root file system, and for mounting and unmounting a file
system.
Select the options you require on the panel. The mount point must be a directory. If it is not
an empty directory, files in that directory are not accessible while the file system is mounted.
Only one file system can be mounted at a directory (mount point) at any one time.
ZFS

458

ABCs of z/OS System Programming: Volume 9
9.16 Automount facility
Figure 9-16 Using the automount facility
Automount facility
Use the automount facility to simplify management of your file system. With this facility, you
do not need to mount most file systems at initialization and you do not need to request that
operators perform mounts for other file systems. In addition, the facility simplifies the addition
of new users because you can keep your PARMLIB specification stable. You can establish a
simple automount policy to manage user home directories.
The automount facility also helps you to avoid consuming resources until they are requested.
A file system that is managed by the automount facility remains unmounted until its mount
point is accessed.
In addition, the automount facility helps you to reclaim system resources used by a mount if
that file system has not been used for some period of time. You can specify how long the file
system should remain mounted after its last use.
The automount facility lets you designate directories as containing only mount points. This is
the preferred method of managing user HFS data sets. As each of these mount points is
accessed, an appropriate file system is mounted. The mount point directories are internally
created as they are required. Later, when the file system is no longer in use, the mount point
directories are deleted.
Try to think of automount as an administrator that has total control over a directory. When a
name is accessed in this directory, it looks up in its policy what file system is supposed to be
associated with that name. If it finds one, it (logically) performs a
mkdir
followed by a
mount
,
then quietly moves out of the way. Once out of the way, the root directory of that newly
mounted file system is now accessed as that name.
Used to simplify management of your filesystems
Eliminates mounting files at initialization
Eliminates operators performing mounts
Easier to add a new user's file system
Files not mounted until required
Use BPXPRMxx and two definition files
/etc/auto.master
/etc/auto.map

Chapter 9. Managing file systems
459
automount definition files
You need to customize the configuration files before you can start using the automount facility,
as follows:
/etc/auto.master
This file contains the directory or directories that the automount facility
will monitor. It also contains an associated MapName file that contains
the mount parameters.
It specifies that the automount facility is to manage the
/u
directory. If
someone using kernel services tries to access a directory in the
/u

directory, the automount facility automatically mounts the data set
based on the MapName policy in:
/u /etc/u.map
The name of the map file can be specified as a data set name, which
must be specified as a fully qualified name and can be uppercase or
lowercase. Single quotation marks are not needed.
Example:
/u //sys1.parmlib(amtmapu)

460

ABCs of z/OS System Programming: Volume 9
9.17 Automount setup
Figure 9-17 Automount facility policy setup
Setting up the automount policy
To use the automount facility, the following statement must be added to the BPXPRMxx
member:
FILESYSTYPE TYPE(AUTOMNT) ENTRYPOINT(BPXTAMD)
Automount policy files
Automount uses two HFS files for specifying the policy for which file systems should be
automatically mounted when referenced:
/etc/auto.master
Contains a list of directories to be managed, along with their MapName
files.
/etc/u.map
Is the MapName file for a directory.
The MapName file contains the mapping between a subdirectory of a directory managed by
the automount facility and the mount parameters. It can contain both specific entries and a
generic entry. When the automount facility tries to resolve a lookup request, it attempts to find
a specific entry. If a specific entry does not exist for the name being looked up, it will then
attempt to use the generic entry, as follows:
###
ZFS automount map file for mount point /u ###. The use of the # symbol indicates a
comment statement in the map file.
FILESYSTYPE TYPE(AUTOMNT) ENTRYPOINT(BPXTAMD)
BPXPRMxx
1.
/u /etc/auto.map

/etc/auto.master
2.
<asis_name>
### zFS automount map file for mount point
/u
###
name *
type ZFS
filesystem OMVS.<uc_name>.ZFS
mode rdwr
duration nolimit
delay 60
setuid no | yes
allocany space(10,5) tracks
/etc/auto.map
3.
allocuser
file system name = any naming convention you choose

Chapter 9. Managing file systems
461
name
The name of the mount point directory. An asterisk (*) specifies a generic
entry for the automount-managed directory.
type
File system type. The default is HFS.
filesystem
Data set name of the file system to mount. Two special symbols are
supported to provide name substitution:
<asis_name>
Used to represent the name exactly, as is.
<uc_name>
Used to represent the name in uppercase characters.
These can be used when specifying a file system name or file system
parameter that has a specific form, with the name inserted as a qualifier.
mode
Mount mode.
duration
The minimum amount of time in minutes to leave the file system mounted.
The default is nolimit.
delay
The minimum amount of time in minutes to leave the file system mounted
after the duration has expired and the file system is no longer in use. The
default is 0.
setuid
Can be specified as yes or no. This will support or ignore the SETUID and
SETGID mode bits on executable files loaded from the file system.
&SYSNAME
Indicates that system symbols are supported in the map file.
allocany
This will cause an allocation if the zFS data set does not exist for any name
looked up in the automount managed directory.
allocuser
This will cause an allocation to occur only if the name looked up matches
the user ID of the current user.
allocuser allocation-spec
- Specifies the allocation parameters when using
automount to allocate HFS or zFS file systems, keeping in mind that zFS is the
preferred file system. allocuser will cause an allocation to occur only if the name
looked up matches the user ID of the current user.
Where:
allocation-spec
is a string that specifies allocation keywords. Keywords can be specified in
the string, as follows:
space(primary-alloc[,secondary alloc])
cyl | tracks | block(block size)
vol(volser[,volser]...)
maxvol(num-volumes)
unit(unit-name)
storclas(storage-class)
mgmtclas(management-class)
dataclas(data-class)
The next four keywords are automatically added:
dsn(filesystem)
dsntype(hfs)
dir(1)
new

462

ABCs of z/OS System Programming: Volume 9
9.18 Generic match on lowercase names
Figure 9-18 Specification of the automount map file keywords
Keywords in automount policy
Four special symbols are supported to provide name substitution:
<asis_name>
Used to represent the name exactly, as is.
<uc_name>
Used to represent the name in uppercase characters.
<sysname>
Used to substitute the system name.
&SYSNAME.
Used to substitute the system name. This is new with z/OS V1R3.
You can use these when specifying a file system name or file system parameter that has a
specific form with the name inserted as a qualifier.
lowercase [Yes|No]
- It indicates the case for names that can match the * specification. This
keyword is valid on any specification, but is only meaningful on the generic entry.
Yes
Only names composed of lowercase characters can match the * specification
(numbers and special characters may also be used). When this is specified,
uppercase characters are not allowed.
No
Any names can match the * specification. This is the default.
Attention:
IBM recommends that you use &SYSNAME. <sysname> is only temporarily
supported for compatibility.
<asis_name>
This represents the exact name of the subdirectory to be
“automounted”. If name is in uppercase, the substitution
name in the file system name is in uppercase. If the name is
in lowercase, the substitution name results in lowercase.
<uc_name>
This represents the name of the subdirectory to be
“automounted” in uppercase characters. In this case,
/u/user1 and /u/USER1 mount point directories map the
same file system
lowercase[YES]
This indicates that only names in lowercase (special
characters are also allowed) match the * specification
lowercase[NO]
This is the default and indicates that any names will match
the * specification.

Chapter 9. Managing file systems
463
9.19 Automount facility overview
Figure 9-19 An overview of automount facility processing
Overview of automount facility processing
The automount facility simplifies the management of mountable file systems.
With automount, an installation defines the directories that should be managed in a policy file.
These directories must be the parent directories of the mount point directories. When a mount
point directory (which is a subdirectory of a managed directory) is referenced in a pathname,
the system creates the mount point directory and mounts the proper file system.
The root directory cannot be managed by automount.
With automount, it is also possible to specify how long a file system should remain
unreferenced before it is automatically unmounted. When a mounted file system is
unmounted, the mount point directory is deleted.
==> ls -al /u/jane
Check automount
policy
MOUNT FILESYSTEM('OMVS.JANE.ZFS')
MOUNTPOINT('/u/jane') TYPE(ZFS)
MODE(RDWR)
z/OS UNIX Shell user JANE:
z/OS UNIX
OK
Result from ls -al command:
/etc/auto.master
/etc/auto.map
-rwxr-xr-x 2 JANE SYS1 668 Oct 26 08:07 vi1.txt
-rwxr-xr-x 2 JANE SYS1 240 Oct 26 08:07 wc.c
-rwxr-xr-x 2 JANE SYS1 202 Oct 26 08:07 wc.l

464

ABCs of z/OS System Programming: Volume 9
9.20 Activating automount
Figure 9-20 Activating the automount facility when a user accesses a file system
Activating the automount policy
The
automount
command is used to configure the z/OS UNIX automount facility. When run
with no arguments, automount reads the /etc/auto.master file to determine all directories that
are to be configured for automounting and the filenames that contain their configuration
specifications.
automount -s
can be specified to check the syntax of the configuration file. No automount is
performed when using the -s option.
The
automount
command requires superuser authority.The automount command is located in
the /usr/sbin directory. The superuser should have this directory in their PATH environment
variable.
When the HFS is first allocated for a new user and
automount
is used to dynamically allocate
a mount point, the new mountpoint directory has permission bits of 700 and the owner is the
superuser. A
chown
command will have to be issued to change the ownership.
After the
automount
command is done, the system will automatically mount a file system if the
mount point directory is managed by the automount facility.
z/OS shell
joe
bill
u
jane
Before JANE accesses => ls -al/u/jane:
After JANE accesses => ls -al/u/jane:
OMVS.ROOT.ZFS
*AMD/u
u
*AMD/u
OMVS.JOE.ZFS
4.
/usr/sbin/automount
5.
joe
bill
u
6.
OMVS.ROOT.ZFS
OMVS.JANE.ZFS
OMVS.BILL.ZFS
OMVS.JOE.ZFS
OMVS.BILL.ZFS

Chapter 9. Managing file systems
465
9.21 SETOMVS RESET=xx implementation
Figure 9-21 Option to start a PFS with an operator command
Defining automount in BPXPRMxx member
The
setomvs
command enables you to modify BPXPRMxx PARMLIB settings without
re-IPLing. So if you need to add the automount physical file system to your environment, the
setomvs
command can be used with the reset= keyword. For example:
setomvs reset=xx
You can use the
setomvs reset
command to dynamically add the FILESYSTYPE,
NETWORK, and SUBFILESYSTYPE statements without having to re-IPL. You place those
statements in a BPXPRMxx member, say BPXPRMtt, and issues the command, as follows:
setomvs reset=tt
However, if you change the values in the PARMLIB member, a re-IPL will be necessary.
To make the dynamic changes when you use the
setomvs
command permanent, you will have
to edit the BPXPRMxx member that is used for IPLs.
SETOMVS RESET=L1
Designed to be used with a subset
of the BPXPRMxx
parmlib statements to add Physical File Systems to a
configuration
FILESYSTYPE
- Basic PFS Definition Statement
SUBFILESYSTYPE
- Stack Definitions under Cinet
NETWORK
- Socket Stack Domain Parameters
System limits - MAXPROCSYS, etc...
Logical extension of SET OMVS=(xx,yy,...)
Only one keyword and member allowed:
SETOMVS RESET=(xx)

466

ABCs of z/OS System Programming: Volume 9
9.22 Issue the SETOMVS command
Figure 9-22 Example of issuing the SETOMVS command
Activate the automount physical file system
These steps show how to set up the automount facility to mount user file systems:

Add the FILESYSTYPE statement to the BPXPRMxx member as follows:
FILESYSTYPE TYPE(AUTOMNT)
ENTRYPOINT(BPXTAMD)

Use the
setomvs
command to dynamically specify the new FILESYSTYPE statements;
this changes the current system settings. (You cannot use the
setomvs
or
set omvs
command to specify the new statements.)

Issue the
setomvs reset=
command to dynamically create to AUTOMNT physical file
system.
To make a permanent change, edit the BPXPRMxx member used for IPLs by placing the
FILESYSTYPE statement into it.
The SET OMVS command
Another way to dynamically reconfigure parameters is to use the
SET OMVS
command to
specify a BPXPRMxx PARMLIB member to make changes in your system dynamically. With
the
SET OMVS
command, you can have multiple BPXPRMxx definitions and use them to easily
reconfigure a set of the z/OS UNIX system characteristics. You can keep the reconfiguration
settings in a permanent location for later reference or reuse.
SET OMVS=xx can be used to execute the ROOT, MOUNT, FILESYSTYPE,
SUBFILESYSTYPE, and NETWORK statements in the BPXPRMxx PARMLIB member.
FILESYSTYPE TYPE(AUTOMNT)
ENTRYPOINT(BPXTAMD)
Add an automnt physical file system to a new
BPXPRMtt member
Issue system command:
SETOMVS RESET=(tt)
With this command, you can mount the following:
SET OMVS=tt
ROOT, MOUNT, FILESYSTYPE, SUBFILESYSTYPE,
and NETWORK statements

Chapter 9. Managing file systems
467
9.23 Updating an existing automount policy
Figure 9-23 New options to update an existing automount policy
Update automount policy in storage
The
automount
command is used to configure the automount facility. This facility can
automatically mount file systems at the time they are accessed, and also unmount them later.
You can use a single automount policy to manage both HFS and zFS file systems.
/usr/sbin/automount
When run with no arguments,
automount
reads the
/etc/auto.master
file to determine all
directories that are to be configured for automounting and the file names that contain their
configuration specifications.
Operands to update a policy
Two new operands can be used to update an automount policy, as follows:
-a
Indicates that the policy being loaded is to be appended to the existing policy rather
than replace the existing policy. For example:
/usr/sbin/automount -a
-q
Displays the current automount policy.
The operands -q and -a are mutually exclusive.
An option (-a) added to the command line:
"-a" - option indicates that the policy being loaded is
to be appended
Example: /usr/sbin/automount -a
Option “-a” is mutually exclusive with query option “-q”
New option (-q) added to command line
"-q" - option displays current active policy

468

ABCs of z/OS System Programming: Volume 9
9.24 Example of new options
Figure 9-24 Example showing changing the auto.map file while policy is active
Changing the auto.map file
The first command in Figure 9-24 displays the current active automount auto.map file, as
follows:
ROGERS @ SC65:/u/rogers>/usr/sbin/automount -q
The next command entered from the OMVS shell is to edit the current auto.map file. During
the edit of the file, the duration is changed from 1440 to 600.
The next command, with the -a option, causes the changed auto.map file to replace the
current active auto.map file in storage with the changed one.
The last command in the figure displays the current active auto.map file which shows the
changed duration.
Changed duration to 600
/u
name *
filesystem OMVS.<uc_name>.ZFS
type ZFS
allocuser space(1,1) storclas(OPENMVS)
mode rdwr
duration 1440
delay 360

ROGERS @ SC65:/u/rogers>oedit /etc/u.map
ROGERS @ SC65:/u/rogers>/usr/sbin/automount -a
FOMF0107I Processing file /etc/u.map
FOMF0108I Managing directory /u
ROGERS @ SC65:/u/rogers>/usr/sbin/automount -q

/u
name *
filesystem OMVS.<uc_name>.ZFS
type ZFS
allocuser space(1,1) storclas(OPENMVS)
mode rdwr
duration 600
delay 360
ROGERS @ SC65:/u/rogers>/usr/sbin/automount -q

Chapter 9. Managing file systems
469
9.25 One auto.master for a sysplex
Figure 9-25 One auto.master for a sysplex
auto.master for a sysplex
The default file name of the master file is /etc/auto.master. It contains the directory or
directories that the automount facility will monitor. It also contains an associated MapName
file that contains the mount parameters.
Option to use an MVS data set
Figure 9-25 shows an example of a /etc/auto.master file that is placed in an MVS data set. It
specifies that the automount facility is to manage the /u directory. If someone using kernel
services tries to access a directory in the /u directory, the automount facility automatically
mounts the data set based on the MapName policy shown in the visual.
This change makes it possible in a sysplex to share the
auto.master
file and allow protection
against simultaneous updates from each system.
The name of the map file can be specified as a data set name. The data set name must be
specified as a fully qualified name and can be uppercase or lowercase. Single quotes are not
needed.
The syntax is enhanced to indicate a master file name
as a data set name:
Master file name is specified on the command line
Data set name can be sequential or member of PDS
Convention of // preceding the data set name is used
Data set name must be a fully qualified name and can
be in upper or lower case
/usr/sbin/automount “//auto.mapfile(automap)”
auto.master contains - /u //auto.mapfile(automap)

470

ABCs of z/OS System Programming: Volume 9
9.26 HFS to zFS automount
Figure 9-26 Using a single auto.map file for automounting HFS and zFS file systems
Single auto.map file for HFS and zFS
You can use a single automount policy to manage both HFS and zFS file systems in the same
managed directory. Automount is changed such that when HFS or zFS is specified as the file
system TYPE, the data set will be checked to determine what type of data set it is, and direct
the mount to the appropriate physical file system (HFS or zFS).
This allows automount managed file systems to be changed from HFS to zFS without
changing the file system name and without changing the automount policy. If the file system
name must be changed, it will be necessary to add a specific entry in the automount policy for
this file system or manage it on another managed directory.
Change automount to set the file system type to
either HFS or zFS when either of those is specified
based on the type of data set that is being mounted
Specify and manage both HFS and zFS file systems
in one automount policy
Facilitates migration from HFS to zFS over time
rather than all file systems at once
Determine whether the data set is a HFS type or not:
If it is, then set the file system type to HFS
If it is not, then set the file system type to zFS

Chapter 9. Managing file systems
471
9.27 HFS to zFS automount
Figure 9-27 HFS to zFS automount policy
HFS to zFS automount policy
Automount recognizes the
type
specification in the automount map files of HFS and zFS as
potentially interchangeable file system types.
At the time automount applies the specification for the mount it will determine if the file system
is the name of either an HFS or zFS data set and alter the type as appropriate.
If the data set does not exist and
allocany
or
allocuser
is not specified, the type will
generally be assumed to be zFS. If either
allocany
or
allocuser
is specified, a new file
system is allocated as before, of the file system type specified in
type
. If your preference is to
have new file systems allocated as zFS file systems, the automount policy should be changed
to specify type zFS.
allocuser
The automount facility recognizes the type specification in the automount map files of HFS
and zFS as potentially interchangeable file system types. At the time automount applies the
specification for the mount, it will determine whether the file system is the name of either a
zFS or HFS file system and alter the type as appropriate. If the data set does not exist and if
allocany
or
allocuser
is not specified, a new file system is allocated as the file system type
as specified in type. Allocation is only done if
allocuser
or
allocany
is specified. If it is
preferred to have new file systems allocated as zFS file systems, the automount policy should
be changed to specify type zFS. The following keywords can be specified in the string:
space(primary-alloc[,secondary alloc])
/u
name *
filesystem OMVS.<uc_name>.HFS
type ZFS
allocuser space(1,1)
storclas(OPENMVS)
mode rdwr
duration 1440
delay 360
New support is used when HFS or zFS is specified as
the file system type in the automount policy
If "allocany" or "allocuser" is specified, a new file
system is allocated using the file system type
specified in the automount policy
If the data set already exists, a check is done to see
whether it is an HFS file system or a zFS aggregate
and then the mount is directed to the appropriate PFS

472

ABCs of z/OS System Programming: Volume 9
cyl | tracks | block(block size)
vol(volser[,volser]...)
maxvol(num-volumes )
unit(unit-name)
storclas(storage-class)
mgmtclas(management-class)
dataclas(data-class)
The next four keywords are automatically added:
dsn(filesystem)
dsntype(hfs)
dir(1)
new
allocany
allocany
specifies the allocation parameters when using automount to allocate HFS or zFS
file systems, keeping in mind that zFS is the preferred file system.
allocany
will cause an
allocation if the data set does not exist for any name looked up in the automount-managed
directory. The following keywords can be specified in the string:
space(primary-alloc[,secondary alloc])
cyl | tracks | block(block size)
vol(volser[,volser]...)
maxvol(num-volumes)
unit(unit-name)
storclas(storage-class)
mgmtclas(management-class)
dataclas(data-class)
The next four keywords are added as appropriate:
dsn(filesystem)
dsntype(hfs)
dir(1)
new

Chapter 9. Managing file systems
473
9.28 Automount migration considerations
Figure 9-28 Automount policy migration considerations
Automount policy for migration
Automount does have support for recalling migrated data sets and will recall data sets as
necessary. The automount processing for HFS file system types is as follows:

If the file system name does not contain any substitution strings, the data set status is
determined to see if the data set is migrated. If migrated, a recall is done.
– If the data set is an HFS data set, the mount is directed to the HFS PFS.
– If the data set is not an HFS data set, the mount is directed to the ZFS PFS.

If the file system name contains substitution strings, the data set status is determined after
substitution is performed substituting ZFS for any /// in the name.
– If the data set exists (migrated or not), the mount is directed to ZFS without automount
performing the recall (recall is done by zFS).

If the file system name contains substitution strings and is for type HFS, the data set
status is determined for data set names after substitution is performed substituting HFS for
any /// in the name. If the data set is migrated, a recall is done.
– If the data set is an HFS data set, the mount is directed to HFS.
– If the data set is not an HFS data set, the mount is directed to ZFS.
name *
type ZFS
filesystem OMVS.<uc_name>.///
mode rdwr
duration 1440
delay 360
File system name contains substitution strings
Data set status is determined after substitution is
performed substituting ZFS or HFS for any /// in the
name

474

ABCs of z/OS System Programming: Volume 9
9.29 How to mount zFS file systems
Figure 9-29 Methods to use when mounting zFS file systems
Mounting file systems
After you have created your zFS file systems, you need to get them mounted at a mount point
off the root directory to make them available. The first consideration for mounting zFS file
systems is to decide where in the root file system to create the starting mount point.
Compatibility mode aggregates
A zFS file system in a compatibility mode aggregate can be mounted, using the
mount

command, at an installation-created mount point. A zFS file system in a compatibility mode
aggregate can also be AUTOMOVEed or automounted using the automount facility.
A preferred place to mount all user flie systems is a user directory under the
/u
user directory.
Therefore, we describe both methods for the mounting of zFS file systems, since some
installations may already be using direct mount while others may be using the automount
facility. We suggest that you use one of the following methods:

Direct mount

Automount facility using zFS
z/OS UNIX mounting for zFS
(1). Direct mount
(2). Automount facility
For all zFS file systems

Chapter 9. Managing file systems
475
9.30 Using direct mount commands
Figure 9-30 Direct mount commands
Direct mount commands
After a user's file system is allocated, you need to get it mounted at a mount point off the root
directory to make it available. Mount points are created by using the
mkdir
command. The
preferred place to mount all individual user file systems is a user directory under the /u user
directory, such as /u/john, for example. The root file system should be set up so that it does
not require frequent changes or updates (outside of SMP/E maintenance).
Mount command example
An example of a direct mount from a shell session for file system OMVS.JOHN follows:
# /usr/sbin/mount /u/john omvs.user1
OMVS.JOHN is now mounted at
/u/john
# df -P
Filesystem 512-blocks Used Available Capacity Mounted
OMVS.JOHN 12960 40 12920 1% /u/john
OMVS.ROOT 82800 79608 3192 97% /
# chown user1:grpoe /u/john
# ls -l /u/john
total 16
drwx------ 2 JOHN GRPOE 0 Nov 7 09:09 john
#
Using the usr/sbin/mount REXX exec from the shell
/usr/sbin/mount /u omvs.users.zfs
Using the mount shell command
Using the ISHELL File_Systems pull-down
Adding an entry to the BPXPRMxx member in
SYS1.PARMLIB so that it will be mounted when the
system re-IPLs
Makes the mount permanent at IPL time
Requires an ID that has superuser authority

476

ABCs of z/OS System Programming: Volume 9
Permanent mounts
To make a mount permanent you will also need to add the file system name and its mount
point to the BPXPRMxx parmlib member, as follows:
MOUNT FILESYSTEM('OMVS.JOHN')
TYPE(HFS)
MOUNTPOINT('/u/john')
MODE(RDWR)
Note:
Since only superusers can mount file systems, in order for JOHN to use this new file
system, the superuser must issue the
chown
command to change the ownership and to
change the group to the user's default group. Issue this command to set the owner and
group fields of this mount point directory for the JOHN user ID. The need to issue the
chown

command is only once because the values will be saved in the new file system and will be
reused even when the file system is remounted later.

Chapter 9. Managing file systems
477
9.31 Mounting zFS file systems
Figure 9-31 Mounting zFS file system with direct mount
Mounting zFS file systems
In Figure 9-31 we show multiple zFS file systems mounted at specified mount points. For the
multi-file system aggregates, we are using single-qualifier file system names.
To create the directories and issue the mounts, the example continues as follows:
#>\u
#>\u>md zfs
#>\u>cd zfs
#>\u\zfs>md cmp01
#>\u\zfs>cd cmp01
#> \u\zfs\cmp01Mounted file system
As shown in Figure 9-31, the compatibility mode aggregate, of course, has only one file
system, which is named the same as the aggregate name.
Attention:
In this direct mount example, we are using a different naming convention for the
aggregate names and file system names. We have also not shown the creation of the
aggregates and file systems.
OMVS.USERS.ZFS
Compat mode
OMVS.CMP01.ZFS
zfs
u
/
cmp01
z/OS UNIX shell
#>\u
#>\u>md zfs
#>\u>cd zfs
#>\u\zfs>md cmp01
#>\u\zfs>cd cmp01
#> \u\zfs\cmp01

478

ABCs of z/OS System Programming: Volume 9
9.32 MOUNT commands
Figure 9-32 Issuing a mount command
TSO mount commands
Once your zFS file systems have been defined, you can make the following decisions on how
to mount them:

You can issue the
mount
command from TSO/E for the compatibility mode file system as
follows:

MOUNT FILESYSTEM(‘OMVS.CMP01.ZFS’) TYPE(ZFS) MODE(RDWR)
MOUNTPOINT('/u/zfs/cmp01')

IPL the system and use the startup of z/OS UNIX to have them mounted.

Use the
mount
command from TSO/E or the
mount
command from the

OMVS shell.
Mounting file systems
Mountable file systems are subsets of the file hierarchy that are added and deleted by mount
and unmount. Each has its own root and hierarchical directory structure. One such file system
serves as the root of the whole file hierarchy, and mounts are done upon the directories of
other mounted file systems.
Note:
There are some further possibilities for mounting file systems. You can use option 3
in the File_systems action menu of the ISHELL, for example.

MOUNT FILESYSTEM('OMVS.CMP01.ZFS') TYPE(ZFS)
MODE(RDWR) MOUNTPOINT('/u/zfs/cmp01')
Mount a compatibility mode file system
Mounts could be done via
/etc/rc
BPXPRMxx parmlib member
MOUNT FILESYSTEM(file_system_name) or DDNAME(ddname)
TYPE(file_system_type)
MOUNTPOINT(pathname)
MODE(READ | RDWR)
PARM(parameter_string)
SETUID | NOSETUID

Chapter 9. Managing file systems
479
Mounts in the BPXPRMxx parmlib member
A mount may be issued from the BPXPRMxx parmlib member that is used with the start of
z/OS UNIX, by a user through ISHELL, by the TSO/E MOUNT command, by automount, or by
a program using the mount() function. The latter function is restricted to users with
appropriate privileges.
Here is the syntax of a MOUNT statement, showing the parameters that are important to this
discussion:
MOUNT FILESYSTEM(file_system_name) or DDNAME(ddname)
TYPE(file_system_type)
MOUNTPOINT(pathname)
MODE(READ | RDWR)
PARM(parameter_string)
SETUID | NOSETUID

480

ABCs of z/OS System Programming: Volume 9
9.33 zFS file system clone
Figure 9-33 zFS file system clone
zFS file system clone
A clone is an optional function. zFS allows the administrator to make a read-only clone of a
file system in the same data set. This clone file system can be made available to users to
provide a read-only point-in-time copy of a file system. The clone operation happens relatively
quickly and does not take up too much additional space because only the metadata is copied.
Cloning a file system
zFS provides the ability to clone a file system with the
zfsadm clone
command. When you
clone a file system, you create a copy of the file system in the same aggregate. There must
be enough physical space available in the aggregate for the clone to be successful. This copy
of the file system is read-only and is called a backup file system. The name of the backup file
system is the same as the original (read-write) file system with .bak (in lower case) appended
to the file system name. This means that you need to limit the length of the file system name
to 40 characters if you want to clone it.
The zFS file system, which is the source file system for the clone, is referred to as the
read-write file system. The backup file system is a read-only file system and can only be
mounted as read-only. You can create a backup file system for every read-write file system
that exists.
The aggregate containing the read-write file system to be cloned must be attached. Creating
a file system clone is accomplished with the
zfsadm clone
command, as follows:
zfsadm clone -filesystem OMVS.CMP01.ZFS
zFS file system clone is a "copy" of a zFS file system
In the same aggregate
The clone file system is R/O
Only the metadata is copied
The cloned file system is called filename.bak
ZFSVOL
ZFSVOL
metadata
metadata
OMVS.PAY.ZFS.bak
OMVS.PAY.ZFS
F
/
F
F
F
F

Chapter 9. Managing file systems
481
IOEZ00225I File system OMVS.CMP01.ZFS successfully cloned.
Clone a file system name
When a file system is cloned, a copy of the file system is created in the same aggregate;
space must be available in the aggregate for the clone to be successful. The file system name
of the backup file system is the same as the original (read-write) file system with .bak (in
lower case) appended to the file system name, as shown in Figure 9-33 on page 480. The
clone operation happens relatively quickly and does not take up too much additional space
because only the metadata is copied. Metadata consists of things such as owner,
permissions, and data block pointers.
The backup file system’s data block pointers point to the same data blocks that the read-write
file system’s data block pointers point to. After a clone operation, if the read-write file system
user data is updated, zFS ensures that new physical blocks are allocated to hold the updates,
while maintaining the backup file system’s data pointers to the original data. The backup file
system remains a point-in-time read-only copy in the face of updates to the read-write file
system. This backup file system can be mounted (read-only) so that users with the authority
to perform mounts of the read-write file system can have an online backup of that file system
available. That is, if a user accidently erases a file from the read-write file system, they can
simply copy the file from the backup into the read-write file system to restore the file to the
time the backup was created.
Clone considerations
The read-write file system can be cloned again (recloned). When a backup file system
already exists, it is replaced during the clone operation. One backup file system can exist for
each read-write file system. Backup file systems cannot be mounted during the clone
operation.
If a failure occurs during a clone of the file system (causing the clone to be only partially
created), zFS will delete the partial clone on the next mount. If the file system contains many
files, the delete of the partial clone might delay the mount.
You can clone or reclone a set of file systems with the
zfsadm clonesys
command. This can
be specified in terms of file systems with a file system name prefix or file systems in an
aggregate or both.

482

ABCs of z/OS System Programming: Volume 9
9.34 Backup file system - zFS clone
Figure 9-34 zFS clone
zFS clone
This command creates a backup version, or clone, of the indicated read-write zFS file system.
It names the new backup version by adding a .bak extension to the name of its read-write
source file system. It places the backup version on the same aggregate as the read-write
version. The aggregate that the read-write file system is contained in must be attached. The
read-write file system may or may not be mounted when the clone operation is issued. The
backup file system cannot be mounted when the clone operation is issued.
After the clone operation, the backup file system can be mounted read-only. The
zfsadm
clone
command cannot clone non-zFS file systems.
Permission to clone
The issuer must have READ authority to the data set that contains the IOEFSPRM file and
must be root or must have READ authority to the SUPERUSER.FILESYS.PFSCTL profile in
the z/OS UNIXPRIV class. For more information about this authority, see “Authorization for
administrators for zFS commands” on page 307.
RDEFINE UNIXPRIV SUPERUSER.FILESYS.PFSCTL UACC(NONE)
PERMIT SUPERUSER.FILESYS.PFSCTL CLASS(UNIXPRIV) ID(ROGERS) ACCESS(READ)
ZFSVL1
ZFSVL1
File1
/
File2
metadata
metadata
OMVS.CMP01.ZFS
OMVS.CMP01.ZFS.bak
zfsadm clone -filesystem OMVS.CMP01.ZFS
IOEZ00225I File system OMVS.CMP01.ZFS successfully cloned.
RDEFINE UNIXPRIV SUPERUSER.FILESYS.PFSCTL UACC(NONE)
PERMIT SUPERUSER.FILESYS.PFSCTL CLASS(UNIXPRIV) ID(ROGERS) ACCESS(READ)

Chapter 9. Managing file systems
483
9.35 zFS clone mounted
Figure 9-35 A mounted zFS clone
Mounted zFS clones
Once you have created the clone, it must be mounted before anyone can use it. You can use
the TSO/E MOUNT command for the backup file system (clone), as follows:
MOUNT FILESYSTEM('''OMVS.CMP01.ZFS.bak''') MOUNTPOINT('/u/zfs/c01cl') TYPE(ZFS)
MODE(READ) NOAUTOMOVE
The clone must be mounted NOAUTOMOVE.
If you prefer to use an OMVS
mount
command for the clone, enter:
/usr/sbin/mount -t ZFS -r -a no -f OMVS.CMP01.ZFS.bak /u/zfs/c01cl
Note:
Using the TSO/E MOUNT command for a clone requires that you use three quotes
around the file system name. This is required because the file system name is mixed case
with .bak being lower case.
Note:
The backup file system or clone can be mounted (read-only) so that users of the
read-write file system can have an online backup of that file system available without
administrative intervention.
ZFSVL1
ZFSVL1
OMVS.USERS.HFS
/
File1
/
metadata
metadata
OMVS.CMP01.ZFS
OMVS.CMP01.ZFS.bak
File2
c01
zfs
u
c01cl
MOUNT FILESYSTEM('''OMVS.CMP01.ZFS.bak''')
MOUNTPOINT('/u/zfs/c01cl') TYPE(ZFS) MODE(READ) NOAUTOMOVE

484

ABCs of z/OS System Programming: Volume 9
9.36 Using the clone
Figure 9-36 Using the clone
Using a clone
The clone uses a small amount of space since only the metadata is copied, not the user data.
The backup file system's data block pointers point to the same data blocks that the read-write
file system's data block pointers point to. After a clone operation creates the backup file
system, then if the read-write file system user data is updated, zFS does the following:

Makes sure that new physical blocks are allocated to hold the updates.

Maintains the backup file system's data pointers to the original data.

Keeps the backup file system as an exact copy (at the point-in-time the clone was made)
when updates to the read-write file system are made.
If a user accidentally erases a file from the read-write file system, they can simply copy the file
from the clone into the read-write file system to restore the file to the time the backup was
created.
The read-only clone of a file system resides in the same data set as the file system that is
cloned. This clone file system can be made available to users to provide a read-only
point-in-time copy of a file system.
Updating the clone
The read-write file system can be cloned again (reclone). If the clone file system already
exists, it is replaced during this clone operation. Backup file systems cannot be mounted
during the clone operation.
After a clone operation creates the backup file
system, if the read-write file system user data is
updated, zFS does the following:
Makes sure that new physical blocks are allocated
to hold the updates
Maintains the backup file system's data pointers to
the original data
Keeps the backup file system as an exact copy at
the point-in-time the clone was made when updates
to the read-write file system are made
zfsadm clonesys -aggregate OMVS.CMP01.ZFS
---- Update previous clone ----

Chapter 9. Managing file systems
485
9.37 Mounting File Systems - (HFS - zFS)
Figure 9-37 Options when mounting file systems
Changes to the MOUNT command
The parameters that have been added to the MOUNT processing commands apply only in a
sysplex where systems are participating in a shared file system environment. They indicate
what happens if the system that owns a file system goes down.
AUTOMOVE(indicator,sysname1,sysname2,...,sysnameN)
This new AUTOMOVE feature of z/OS V1R4 allows for a list of systems to be included or
excluded (indicated by the indicator field) from being AUTOMOVEd. The
include
indicator
and system list provides an ordered list of systems that should be moved to if the file system's
owning system should leave the sysplex. The
exclude
indicator and system list provides a list
of systems that the file system should not be moved to if the file system's owning system
should leave the sysplex.
SYSNAME
For systems participating in a shared file system environment, SYSNAME specifies the
particular system on which a mount should be performed. This system will then become the
owner of the file system mounted. This system must be IPLed with SYSPLEX(YES). IBM
recommends that you specify SYSNAME(&SYSNAME.) or omit the SYSNAME parameter. In
this case, the system that processes the mount request mounts the file system and becomes
its owner.
MOUNT file system(file
_
system
_
name)
MOUNTPOINT(pathname)
TYPE(file
_
system
_
type)
MODE(RDWR|READ)
PARM(parameter
_
string)
TAG(NOTEXT|TEXT,ccsid)
SETUID|NOSETUID
WAIT|NOWAIT
SECURITY|NOSECURITY
SYSNAME (sysname)
AUTOMOVE|AUTOMOVE(indicator,sysname1,sysname2,...,sysnameN
NOAUTOMOVE|UNMOUNT
Functions added in shared HFS
AUTOMOVE - NOAUTOMOVE - SYSNAME
UNMOUNT - AUTOMOVE (syslist)

486

ABCs of z/OS System Programming: Volume 9
9.38 MOUNT command options
Figure 9-38 MOUNT command options for the shared sysplex environment
AUTOMOVE
When AUTOMOVE is specified for a file system and the file system’s owner goes down,
AUTOMOVE indicates that ownership of the file system can be automatically moved to
another system participating in shared sysplex HFS or zFS. AUTOMOVE is the default.
NOAUTOMOVE
When NOAUTOMOVE is specified for a file system, it indicates that ownership should not be
moved to another system participating in a shared file system environment if the file system's
owner should crash.
UNMOUNT
When UNMOUNT is specified for a file system, this indicates that the file system will not be
moved and will be unmounted if the file system's owner should crash. This file system and
any file systems mounted within its subtree will be unmounted.
The alternate CDS is not compatible with the primary because it has a smaller value for
MOUNTS, so the command SETXCF COUPLE,ACOUPLE failed, because the alternate CDS
must be formatted with equal or greater values for MOUNTS and AMTRULES in order for this
command to work.
Note:
AUTOMOVE is not supported for zFS file systems mounted in a multi-system mode
aggregate. They must be mounted NOAUTOMOVE.
AUTOMOVE - Specifies that ownership of the file
system is automatically moved to another system. It
is the default
NOAUTOMOVE
- Specifies that the file system will
not be moved if the owning system goes down and
the file system is not accessible
UNMOUNT
- Specifies that the file system will be
unmounted when the system leaves the sysplex
Note: This option is not available for automounted
file systems

Chapter 9. Managing file systems
487
9.39 UNMOUNT option
Figure 9-39 UNMOUNT option on mount command
Unmount option
When a file system is mounted with the UNMOUNT parameter, attempts will not be made to
keep the file system active when the current owner fails. The file system will be unmounted
when the owner is no longer active in the participating group, as well as all the file systems
mounted within it. It is suggested for use on mounts for system-specific file systems, such as
those that would be mounted at /etc, /dev, /tmp, and /var.
Because the file system still exists in the file system hierarchy, the file system mount point is
still in use.
An unowned file system is a mounted file system that does not have an owner. The file
system still exists in the file system hierarchy. As such, you can recover or unmount an
unowned file system.
Note:
AUTOMOVE and UNMOUNT are the only options you can use for file systems that
are mounted in a mode for which they are capable of being directly mounted to the PFS on
all systems (sysplex-aware). If you specify any other option on a MOUNT, it is ignored and
you will see message BPXF234I.
Requirement: Unmount certain file systems
associated with a failed system, rather than
recovering and converting to "unowned" status
Solution:
Provide UNMOUNT option on MOUNT
command and change partition recovery to unmount
these file systems
Partition recovery will unmount Automount managed
file systems if owner fails and no application on active
systems is referencing
Partition recovery will unmount all file systems
associated with a PFS that does not support "move"
(e.g. TFS)

488

ABCs of z/OS System Programming: Volume 9
9.40 UNMOUNT option support
Figure 9-40 UNMOUNT option support for activation
BPXPRMxx PARMLIB MOUNT statement
The AUTOMOVE | NOAUTOMOVE | UNMOUNT parameters on ROOT and MOUNT
statements indicate what happens to the file system if the system that owns that file system
goes down. UNMOUNT specifies that the file system will be unmounted when the system
leaves the sysplex. This option is not available for automounted file systems. AUTOMOVE is
the default.
TSO/E MOUNT command
The options are: AUTOMOVE | NOAUTOMOVE | UNMOUNT. The AUTOMOVE |
NOAUTOMOVE parameters apply only in a sysplex where systems are participating in a
shared file system environment. They indicate what happens if the system that owns a file
system goes down. The default setting is AUTOMOVE.
The mount shell command
The
mount
shell command, located in /usr/sbin, is used to mount a file system or list all
mounts over a file system. A mount user must have UID(0) or at least have READ access to
the SUPERUSER.FILESYS.MOUNT resource found in the UNIXPRIV class.
Specify unmount to allow a specified file system (and any file systems mounted on it) to be
unmounted when its owning system leaves the sysplex due to a system outage.
The options are:
-a yes|no|unmount
. The default is
yes
.
BPXPRMxx parmlib MOUNT statement
MOUNT FILESYSTEM('OMVS.&SYSNAME..SYSTEM.HFS')
TYPE(HFS) MODE(RDWR) UNMOUNT
MOUNTPOINT('/&SYSNAME.')
TSO/E MOUNT command
MOUNT filesystem(OMVS.VIVAR.HFS)
mountpoint('/u/vivar') type(HFS) mode(rdwr)
UNMOUNT
mount shell command
mount [–t fstype][–rv][–a yes|no|
unmount
][–o
fsoptions][–d destsys][–s nosecurity|nosetuid] –f
fsname pathname

Chapter 9. Managing file systems
489
9.41 UNMOUNT option support
Figure 9-41 UNMOUNT options for activation
UNMOUNT options
The UNMOUNT option can be used on the following commands:

The SETOMVS command used with the FILESYS, FILESYSTEM, mount point and
SYSNAME parameters can be used to move a file system in a sysplex.

You can use the
chmount
command from the shell.
In a shared file system environment,
-a yes
allows the system to automatically move
logical ownership for a specified file system due to a system outage.
-a unmount
specifies
that this file system is to be unmounted when the file system's owner leaves the sysplex.

The ISHELL can be used to set the UNMOUNT option, as shown in Figure 9-42 on
page 490.
Note:
A
chmount
user must have UID(0) or at least have read access to the
SUPERUSER.FILESYS.MOUNT resource found in the UNIXPRIV class.
SETOMVS command
SETOMVS FILESYS,FILESYS=filesystem,AUTOMOVE=YES|NO|
UNMOUNT
Shell chmount command:
chmount [–R [–D |–d destsys][–a
yes|no|
unmount
]pathname...
The ISHELL mount interface in the Mount File System
panel is accessed by ISHELL panel -> File System
pulldown Menu -> Option 3 - Mount). The new mount
option is: Automove unmount file system

490

ABCs of z/OS System Programming: Volume 9
9.42 Mount file system panel
Figure 9-42 Mount file system panel in the ISHELL
ISHELL mount file system panel
Figure 9-42 shows the panel used to mount a file system. Beginning with z/OS V1R6, this
panel changed with the removal of the option that appeared above the Set automove
attribute, as follows:
Do not automove file system
Set automove attribute
The field Automove indicates whether the system can automatically move the file system to
another system owner, remain local and unowned, or be unmounted. Other indications are an
include list and exclude list for system selection for automoved file systems.
Automatic move processing is normally done when a system fails and it is the owner of some
file systems. The file systems that contain /dev should never be moved. This should always
be a local file system. Automove should be unmount for this file system. There are some other
file systems where this is also the case.

Chapter 9. Managing file systems
491
9.43 Set AUTOMOVE options
Figure 9-43 Setting the AUTOMOVE options
Setting the AUTOMOVE options
The field Automove indicates whether the system can automatically move the file system to
another system owner, remain local and unowned, or be unmounted. Other indications are an
include list and an exclude list for system selection for automoved file systems.
Automatic move processing is normally done when a system fails and it is the owner of some
file systems. The file systems that contain /dev should never be moved. This should always
be a local file system. Automove should be Unmount for this file system. There are some
other file systems where this is also the case.
Automove Unmount means that when a system fails and if this file system is not in use, it will
be unmounted. If the file system contains mount points, this file system and all file systems
under it will be unmounted.
Automove can also specify a list of systems that may be included when selecting a system for
the target of the move. It can also specify a list of systems that are to be excluded as move
targets. If the list is long, the display may be truncated. All system names can be viewed and
modified by using the Modify file system action code and selecting Automove for change. If
the last system name is specified as * for an include list, the system will treat this as a list of
all remaining eligible systems.
The field Owning system is the name of the system that owns this file system.

492

ABCs of z/OS System Programming: Volume 9
9.44 AUTOMOVE system list (syslist)
Figure 9-44 AUTOMOVE system list specifications
AUTOMOVE system list
When mounting file systems, you can specify an automove system list to indicate where the
file system should or should not be moved when a system leaves the sysplex. Previously, on
a system failure, with more than one system capable of taking over ownership, it was random
which system was the new owner.
The automove system list can be specified in many different ways to automove a file system.
The list begins with an indicator to either
include
or
exclude
(abbreviated as

i

or
e
) followed by
a list of system names. Specify the indicator as follows:
i
Use this indicator with a prioritized list of systems to which the file system may be moved if
the owning system goes down. If none of the systems specified in the list can take over as
the new owner, the file system will be unmounted.
e
Use this indicator with a list of systems to which the file system may
not
be moved.
In a shared sysplex environment, AUTOMOVE(YES)
on MOUNT moves the ownership of the filesystem to
some other system in the sysplex if the current server
system for that filesystem is brought down
syslist provides the capability to specify which system
or systems in a sysplex will takeover as server for a
filesystem
Specify a system list on the AUTOMOVE parameter for
MOUNT
The list begins with either include or exclude,
(abbreviated i or e) followed by a list of system names

Chapter 9. Managing file systems
493
9.45 AUTOMOVE parameters for mounts
Figure 9-45 AUTOMOVE specifications for system lists
Specifying AUTOMOVE on MOUNT commands
When mounting file systems in the sysplex, you can specify a prioritized automove system list
to indicate where the file system should or should not to moved to when the owning system
leaves the sysplex. There are different ways to specify the automove system list, as follows:

On the MOUNT statement in BPXPRMxx, specify the AUTOMOVE keyword, including the
indicator and system list.

For the TSO MOUNT command, specify the AUTOMOVE keyword, including the indicator
and system list.

Use the
mount
shell command.

Use the ISHELL MOUNT interface.

Specify the MNTE_SYSLIST variable for REXX.

Specify the indicator and system list for the automove option in the
chmount
shell
command.

Specify the indicator and system list for the automove option in the SETOMVS operator
command.
BPXPRMXX PARMLIB member MOUNT statement or
TSO/E MOUNT command
Shell mount command
ISHELL panels for mounts
C program, assembler program, or REXX program
AUTOMOVE(indicator, name1, name2,.....)
i
- Provides a prioritized list of systems where the
file system may be moved - If no system can takeover
as the new owner, the file system is unmounted
e - This system list provides a list of systems to
where the file system may not be moved

494

ABCs of z/OS System Programming: Volume 9
9.46 AUTOMOVE wildcard support
Figure 9-46 AUTOMOVE wildcard support
AUTOMOVE wildcard support
You can use the wildcard support on all methods of mounts, including the MOUNT statement
in BPXPRMxx, the TSO MOUNT command, the
mount
shell command, the ISHELL MOUNT
interface, the MNTE_SYSLIST variable for REXX, C program, and assembler program.
Using AUTOMOVE wildcard support, the customer can specify only those systems in the
INCLUDE list that should have priority in file system takeover, and use the wildcard ‘*’ to
specify all remaining systems:
AUTOMOVE(INCLUDE,SY1,SY3,*)
A wildcard character is permitted as an only item or as a last item of the AUTOMOVE Include
Syslist in place of a system name.
Advantages of using AUTOMOVE wildcard support
With wildcard support, the remaining systems do not have to be explicitly listed in the Include
system list, which can reduce typing errors.
Note:
The wildcard is only allowed with an Include list, not with an Exclude list.
Wildcard support for system lists:
Explicitly list the systems and include the remaining systems
using wildcard character in the include system list:
Parmlib member
TSO MOUNT command
Shell - chmount
ISHELL
C program
REXX
Assembler program
SETOMVS FILESYS,FILESYSTEM=‘X.Y.Z’,AUTOMOVE=(I,*)
Automove syslist wildcard support is invoked by:
SETOMVS FILESYS,FILESYSTEM=‘X.Y.Z’,SYSNAME=*
F BPXOINIT, SHUTDOWN=FILESYS
F OMVS,SHUTDOWN

Chapter 9. Managing file systems
495
9.47 AUTOMOVE wildcard examples
Figure 9-47 AUTOMOVE wildcard examples
Examples of wildcard usage
If you have a large number of systems in your sysplex, you can specify only the systems that
should have priority and use a wildcard to indicate the rest of the systems.
In the examples, at first glance, AUTOMOVE INCLUDE (*) appears to work the same way as
AUTOMOVE(YES) because all of the systems will try to take over the file system. However,
with AUTOM0VE INCLUDE (*), if none of the systems can take over the file system, it will be
unmounted. If AUTOMOVE(YES) is used, the file system will become unowned.
Note:
All systems must be at the V1R6 level or later. Otherwise, results will be
unpredictable.
Wildcard character permitted as an only item or as a
last item of the Automove
Include
Syslist in place of a
system name
The wildcard is only allowed with an Include list, not
with an
Exclude
list:
Examples
AUTOMOVE(include,sy2,*)
AUTOMOVE(include,*)
AUTOMOVE(i,sy1,sy2,sy3,*)
AUTOMOVE(i,sy*)

496

ABCs of z/OS System Programming: Volume 9
9.48 Stopping zFS
Figure 9-48 Ways zFS address space stops running
Stopping zFS
zFS can be stopped using the F OMVS,STOPPFS=ZFS operator command. zFS file systems
should be unmounted or moved to another sysplex member before zFS is actually stopped by
z/OS UNIX. When zFS is stopped, you receive the following message:
nn BPXF032D FILESYSTYPE ZFS TERMINATED. REPLY 'R' WHEN READY TO RESTART. REPLY
'I' TO IGNORE.
In general, you should not stop zFS. Stopping zFS is disruptive to applications that are using
zFS file systems. zFS stops automatically when you shut down z/OS UNIX. If you want to
shut down an LPAR or re-IPL an LPAR, use the
F OMVS,SHUTDOWN
operator command to shut
down z/OS UNIX. This synchronizes data to the file systems and unmounts or moves
ownership in a shared file system environment. A planned system shutdown must include the
unmount or move of all owned file systems and the shutdown of zFS. The
F OMVS,SHUTDOWN

command unmounts and moves the owned file systems and shuts down zFS. For shutdown
procedures using
F OMVS,SHUTDOWN
, see the topic on Planned shutdowns using
F
OMVS,SHUTDOWN
in
z/OS UNIX System Services Planning
, GA22-7800.
File system ownership
zFS can be stopped using the F OMVS,STOPPFS=ZFS operator command. Automatic
ownership movement can occur for both the z/OS UNIX owner and the zFS owner. See
z/OS
UNIX System Services Planning
, GA22-7800 for information about the various AUTOMOVE
settings for z/OS UNIX file system ownership. zFS aggregate ownership will move unless the
Use the F OMVS,STOPPFS=ZFS operator command
ZFS address space can have an internal failure
File system status if ZFS address space goes away
All zFS file systems on that system will be unmounted
Or moved if AUTOMOVE in a sysplex is specified
Issuing P ZFS
IOEZ00523I zFS no longer supports the P ZFS stop
command. Please issue f omvs,stoppfs=zfs

Chapter 9. Managing file systems
497
file system is unmounted by z/OS UNIX. zFS file systems that become unmounted will need
to be mounted again after zFS is restarted.
ZFS address space fails
If the ZFS colony address space has an internal failure, it may abnormally terminate and stop.
Normally, the ZFS colony address space restarts automatically. Otherwise, message
BPXF032D (the same message you receive when the F OMVS,STOPPFS=ZFS operator
command is used) is issued and a reply is requested.
File system status
If the F OMVS,STOPPFS=ZFS operator command is issued, all ZFS file systems on that
system will be unmounted (or moved if AUTOMOVE in a sysplex is specified). Applications
with an open file on these file systems will receive I/O errors until the file is closed. Once zFS
is restarted, the operator must remount any file systems that were locally mounted (that is, file
systems that were owned by that system and were not moved). This can be done with the
F BPXOINIT,FILESYS=REINIT operator command. This causes a remount for each file
system that was mounted through a BPXPRMxx parmlib statement.
New stop command
This command is introduced to stop the ZFS address space, as follows:
F OMVS,STOPPFS=ZFS
This new operator command allows z/OS UNIX to move file system ownership
(non-disruptively) to another system before the PFS is terminated. This allows applications
that are accessing file systems owned on the system where the zFS PFS is being terminated
to continue to proceed without I/O errors in a shared file system environment.
After receiving the
stop
command, the system invokes a sync to all local mounted zFS file
systems. Afterward, all zFS file systems are unmounted in a single system. When you are in a
shared file system environment, all AUTOMOVE-defined file systems will be moved to
another system. Before the file system move starts, a new message, BPXI068D, appears to
confirm the file system shutdown.
F OMVS,STOPPFS=ZFS
*010 BPXI078D STOP OF ZFS REQUESTED. REPLY 'Y' TO PROCEED. ANY OTHER REPLY WILL
CANCEL THIS STOP
R 10,Y
IEE600I REPLY TO 010 IS;Y
IOEZ00048I Detaching aggregate LUTZ.ZFS
IOEZ00048I Detaching aggregate PELEG.ZFS
IOEZ00048I Detaching aggregate DAURCES.ZFS
IOEZ00048I Detaching aggregate TEMEL.ZFS
IOEZ00048I Detaching aggregate VAINI.ZFS
IOEZ00050I zFS kernel: Stop command received.
IOEZ00057I zFS kernel program IOEFSCM is ending
IEF352I ADDRESS SPACE UNAVAILABLE
IEA989I SLIP TRAP ID=X33E MATCHED. JOBNAME=*UNAVAIL, ASID=0057.
*011 BPXF032D FILESYSTYPE ZFS TERMINATED. REPLY 'R' WHEN READY TO RESTART.

498

ABCs of z/OS System Programming: Volume 9
9.49 Restarting the PFS
Figure 9-49 zFS PFS termination message and operator replies
zFS PFS termination message
When the PFS terminates, there is a system prompt message waiting for a reply to be
answered in system SC70, for example:
*015 BPXF032D FILESYSTYPE ZFS TERMINATED. REPLY 'R' WHEN READY TO RESTART.
REPLY 'I' TO IGNORE.

If the reply to re-start the PFS is
I
(do not restart the PFS), then the file systems will be
locally unmounted as before.

If the reply to re-start the PFS is
R
, then any sysplex-aware file systems will convert back
from function-shipping to local mount. Sysplex-unaware file systems continue
function-shipping to the current owner.
The SET OMVS= command
This command, available with z/OS V1R7, can be used to start the ZFS PFS if it has not been
started at IPL. It can also be used to redefine it if it has been terminated by replying
i
to the
BPXF032D operator message (after stopping the ZFS PFS). The suffix SS is a BPXPRMxx
member of PARMLIB that contains the FILESYSTYPE statement for the ZFS PFS.
When the zFS address space stops either by the operator or abnormally and you are not in
sysplex sharing mode, all zFS file systems are unmounted as the aggregates are detached.
Note:
Beginning with z/OS V1R8, the
p zfs
command is only supported in a non-sysplex
sharing mode.
If the reply to restart the PFS is "I"
(Do not restart the PFS), then the file systems are
locally unmounted as before
If the reply to restart the PFS is "R"
Then any sysplex-aware file systems converts back
from function-shipping to local mount
Sysplex-unaware file systems remain function-shipping
to the current owner
Restart the zFS PFS with if the "I" option terminates it
Issue a SET OMVS=SS command
BPXPRMSS contains the FILESYSTYPE statement

Chapter 9. Managing file systems
499
9.50 Mounting file systems with SET OMVS
Figure 9-50 Mounting file systems using the SET OMVS command
BPXPRMSS PARMLIB member
The following BPXPRMSS PARMLIB member is used to restart zFS and mount critical file
systems. The SET OMVS=SS operator command is used to read the member, execute the
mount statements, and start the ZFS PFS following a
p zfs
command.
FILESYSTYPE TYPE(ZFS) /* Type of file system to start */
ENTRYPOINT(IOEFSCM) /* Entry Point of load module */
ASNAME(ZFS) /* Procedure name */
ROOT FILESYSTEM('OMVS.&SYSNAME..&SYSR1..ROOT.ZFS')
/* z/OS root filesystem */
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write */
MOUNT FILESYSTEM('OMVS.&SYSNAME..ETC.ZFS')
/* ZFS for /etc directory */
MOUNTPOINT('/etc')
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write */
MOUNT FILESYSTEM('OMVS.&SYSNAME..VAR.ZFS')
/* ZFS for /var directory */
MOUNTPOINT('/var')
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write
The SET OMVS command enables use of a
BPXPRMxx parmlib member without re-IPLing
Allows mounts from a BPXPRMxx member from an
operator console
FILESYSTYPE TYPE(ZFS) /* Type of file system to start */
ENTRYPOINT(IOEFSCM) /* Entry Point of load module */
ASNAME(ZFS) /* Procedure name */
ROOT FILESYSTEM('OMVS.&SYSNAME..&SYSR1..ROOT.ZFS')
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write */
MOUNT FILESYSTEM('OMVS.&SYSNAME..ETC.ZFS')

MOUNTPOINT('/etc')
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write */
MOUNT FILESYSTEM('OMVS.&SYSNAME..VAR.ZFS')

MOUNTPOINT('/var')
TYPE(ZFS) /* Filesystem type ZFS */
MODE(RDWR) /* Mounted for read/write */


500

ABCs of z/OS System Programming: Volume 9
9.51 Messages from shutdown of a ZFS single system
Figure 9-51 Shutdown of the ZFS address space
Messages from the restart of zFS
After stopping zFS and issuing the SET OMVS command the following messages are issued:
P ZFS
IOEZ00541I 729
zFS filesystems owned on this system should be unmounted or moved
before stopping zFS. If you do not applications may fail.
*005 IOEZ00542D Are you sure you want to stop zFS? Reply Y or N
IEE600I REPLY TO 005 IS;Y
IOEZ00050I zFS kernel: Stop command received.
IOEZ00048I Detaching aggregate OMVS.TC7.VAR.ZFS
IOEZ00048I Detaching aggregate OMVS.TC7.ETC.ZFS
IOEZ00048I Detaching aggregate OMVS.TC7.TRNRS1.ROOT.ZFS
IOEZ00057I zFS kernel program IOEFSCM is ending
*006 BPXF032D FILESYSTYPE ZFS TERMINATED. REPLY 'R' WHEN READY TO
RESTART. REPLY 'I' TO IGNORE.
IEF352I ADDRESS SPACE UNAVAILABLE
$HASP395 ZFS ENDED
$HASP250 ZFS PURGED -- (JOB KEY WAS BE68CA18)
R 6,I
IEE600I REPLY TO 006 IS;I
SET OMVS=SS
IEE252I MEMBER BPXPRMSS FOUND IN SYS1.PARMLIB
BPXO032I THE SET OMVS COMMAND WAS SUCCESSFUL.
P ZFS
IOEZ00541I 729
zFS filesystems owned on this system should be unmounted or moved
before stopping zFS. If you do not applications may fail.
*005 IOEZ00542D Are you sure you want to stop zFS? Reply Y or N
IEE600I REPLY TO 005 IS;Y
IOEZ00050I zFS kernel: Stop command received.
IOEZ00048I Detaching aggregate OMVS.TC7.VAR.ZFS
IOEZ00048I Detaching aggregate OMVS.TC7.ETC.ZFS
IOEZ00048I Detaching aggregate OMVS.TC7.TRNRS1.ROOT.ZFS
IOEZ00057I zFS kernel program IOEFSCM is ending
*006 BPXF032D FILESYSTYPE ZFS TERMINATED. REPLY 'R' WHEN READY TO
RESTART. REPLY 'I' TO IGNORE.
IEF352I ADDRESS SPACE UNAVAILABLE
$HASP395 ZFS ENDED
$HASP250 ZFS PURGED -- (JOB KEY WAS BE68CA18)
R 6,I
IEE600I REPLY TO 006 IS;I
SET OMVS=SS
IEE252I MEMBER BPXPRMSS FOUND IN SYS1.PARMLIB
BPXO032I THE SET OMVS COMMAND WAS SUCCESSFUL.

Chapter 9. Managing file systems
501
9.52 Messages for the restart of ZFS
Figure 9-52 Messages during restart of the ZFS address space
ZFS address space restart messages
Reading the BPXPRMSS PARMLIB member uses the FILESYSTYPE statement to start the
ZFS address space. The mount statements in the member are used to start the other file
systems that were stopped when the
P ZFS
command was issued.
Figure 9-53 Example of stopping a zFS file system
$HASP100 ZFS ON STCINRDR
$HASP373 ZFS STARTED
IOEZ00052I zFS kernel: Initializing z/OS zSeries File System
Version 01.07.00 Service Level OA12872 - HZFS370.
Created on Mon Sep 26 16:19:25 EDT 2005.
IOEZ00178I SYS1.TC7.IOEFSZFS(IOEFSPRM) is the configuration dataset
currently in use.
IOEZ00055I zFS kernel: initialization complete.
BPXF013I FILE SYSTEM OMVS.TC7.TRNRS1.ROOT.ZFS 768
WAS SUCCESSFULLY MOUNTED.
BPXF013I FILE SYSTEM OMVS.TC7.ETC.ZFS 769
WAS SUCCESSFULLY MOUNTED.
BPXF013I FILE SYSTEM OMVS.TC7.VAR.ZFS 770
WAS SUCCESSFULLY MOUNTED.
$HASP100 ZFS ON STCINRDR
$HASP373 ZFS STARTED
IOEZ00052I zFS kernel: Initializing z/OS zSeries File System
Version 01.07.00 Service Level OA12872 - HZFS370.
Created on Mon Sep 26 16:19:25 EDT 2005.
IOEZ00178I SYS1.TC7.IOEFSZFS(IOEFSPRM) is the configuration dataset
currently in use.
IOEZ00055I zFS kernel: initialization complete.
BPXF013I FILE SYSTEM OMVS.TC7.TRNRS1.ROOT.ZFS 768
WAS SUCCESSFULLY MOUNTED.
BPXF013I FILE SYSTEM OMVS.TC7.ETC.ZFS 769
WAS SUCCESSFULLY MOUNTED.
BPXF013I FILE SYSTEM OMVS.TC7.VAR.ZFS 770
WAS SUCCESSFULLY MOUNTED.

502

ABCs of z/OS System Programming: Volume 9
9.53 Shutdown and recovery scenarios
Figure 9-54 Recovery scenarios
File system recovery scenarios
File system recovery in a shared file system environment takes into consideration file system
characteristics such as the PFS capabilities and whether the file system was mounted as
read-write or read-only.
Recovering file systems in a shared file system takes into consideration file system
specifications such as the sysplex awareness capability, the AUTOMOVE value, and whether
or not the file system is mounted read-only or read/write.
Generally, when an owning system fails, ownership of a file system that is mounted as
AUTOMOVE is moved to another system and the file system remains usable. However, if a
file system is mounted as read-write and the owning system fails, then all file system
operations for files in that file system will fail. This happens because data integrity is lost when
the file system owner fails.
When mounting file systems in the sysplex, you can specify a prioritized system list to
indicate where the file system should or should not be moved to when the owning system
leaves the sysplex changes due to any of the following:

A soft shutdown request has been issued.

Dead system takeover occurs (when a system leaves the sysplex without a prior soft
shutdown).

A PFS terminates on the owning system.
“Soft shutdown processing”
F BPXOINIT,SHUTDOWN=FILESYS
F BPXOINIT,SHUTDOWN=FILEOWNER
F OMVS,SHUTDOWN
Member gone recovery on hard failures
PFS termination
Multiple file system moves using:
SETOMVS FILESYS,FROMSYS=SY1,SYSNAME=SY2

Chapter 9. Managing file systems
503

A request to move ownership of the file system is issued. The following command can be
used:
SETOMVS FILESYS,FROMSYS=sysname,SYSNAME=sysname|*
FROMSYS=sysname
in a sysplex environment is a parameter that indicates the system where
all the file systems will be moved from. The file systems will be moved to the system
identified by the sysname keyword.
Soft shutdown
Soft shutdown is done by issuing one of the following MODIFY (F) commands:
F BPXOINIT,SHUTDOWN=FILESYS
F BPXOINIT,SHTUDOWN=FILEOWNER
F OMVS,SHUTDOWN
Automount-managed file systems are unmounted by a soft shutdown operation if the file
system is not referenced by any other system in the sysplex. If it is referenced by another
system or systems, ownership of the file system is moved. If the move fails, an unmount is not
attempted and ownership does not change.
PFS termination
If a PFS terminates on one system, it can affect file system availability on other systems. If a
PFS terminates on one system, any file systems of that type that are owned by other systems
are not affected. File systems of that type are moved to new owners whenever possible if they
are owned by the system where the PFS is terminating and if they can be automoved. These
file systems remain accessible to other systems. If they cannot be moved to new owners, they
are unmounted across the sysplex. It may not be possible to move a file system due to a lack
of connectivity from other systems, or if the file system containing the mount point for the file
system needed to be moved but could not be.

504

ABCs of z/OS System Programming: Volume 9
9.54 zFS commands in a sysplex
Figure 9-55 Command changes in a sysplex
zfsadm commands in a sysplex
Previously,
zfsadm
commands (and the pfsctl APIs) could only display or change information
that is located or owned on the current member of the sysplex. The pfsctl (BPX1PCT)
application programming interface is used to send physical file system specific requests to a
physical file system. zFS pfsctl APIs do not work across sysplex members. zFS pfsctl APIs
can query and set information on the current system only. However, if all systems are running
z/OS V1R7, zFS pfsctl APIs will work across sysplex members.
DFSMS backups
A particular problem is quiescing of a zFS aggregate. When DFSMS is used to back up a zFS
aggregate, the aggregate is quiesced by DFSMS before the backup. Currently, in order for
this quiesce to be successful, it must be issued on the system that owns the aggregate. If it is
issued on any other system in the sysplex, the quiesce fails (and the backup fails). It is a
problem to issue the backup on the owning system because ownership can change at
anytime as a result of operator command or system failure.
zfsadm
command forwarding
allows the quiesce (or any other zfsadm command) to be issued from any member of the
sysplex. This function is used by:

DFSMS backup (ADRDSSU)

ISHELL

zFS Administrators
Previously, zfsadm commands (and the pfsctl APIs)
could only display or change information that is located
or owned on the current member of the sysplex
Only issued from the owning system
When DFSMS is used to back up a zFS aggregate, the
aggregate is quiesced by DFSMS before the backup
In order for this quiesce to be successful, it must be
issued on the system that owns the aggregate

Chapter 9. Managing file systems
505
9.55 zfsadm command changes for sysplex
Figure 9-56 Sysplex support for zfsadm commands
zfsadm commands with sysplex sharing
All
zfsadm
commands work across sysplex members. The
zfsadm
commands act globally and
report or modify all zFS objects on any system in the sysplex.
However, there are configuration dependencies. Whether
zfsadm
commands act globally
across the sysplex depends on the BPXPRMxx SYSPLEX option. If SYSPLEX(YES) is
specified, then you are in a shared file system environment and
zfsadm
commands will act
globally. If the IOEFSPRM sysplex=off is specified, or if the BPXPRMxx SYSPLEX option
specifies SYSPLEX(NO), then
zfsadm
commands will not act globally.
All
zfsadm
commands that apply to zFS aggregates or file systems work against all
aggregates and file systems across the sysplex. The following
zfsadm
commands can
optionally direct their operation to a particular member of the sysplex: aggrinfo, attach,
clonesys, config, configquery, define, detach, format, lsaggr, lsfs, and query.
New -system option
The -system system name specifies the name of the system the report request will be sent to,
to retrieve the data requested.
If you are in a shared file system environment,
zfsadm commands and zFS pfsctl APIs generally
work across the sysplex
There are two main changes:
The zfsadm commands act globally and report or
modify all zFS objects across the sysplex
They support a new –system option that limits output
to zFS objects on a single system or sends a request
to a single system
-system system name

506

ABCs of z/OS System Programming: Volume 9
9.56 zfsadm command changes
Figure 9-57 New options with the zfsadm configquery command
zfsadm command options
The
zfsadm configquery
command displays the current value of zFS configuration options.
The value is retrieved from ZFS address space memory rather than from the IOEFSPRM file
or BPXPRMxx PARMLIB member. You can specify that the configuration option query request
should be sent to another system by using the -system option.
The
zfsadm configquery
command has the following new options:
-system system name
Specifies the name of the system the report request will be sent to,
to retrieve the data requested.
-group
Displays the XCF group used by ZFS for communication between
sysplex members.
-sysplex_state
Displays the sysplex state of ZFS. Zero (0) indicates that ZFS is not
in a shared file system environment. One (1) indicates that ZFS is
in a shared file system environment.
zfsadm configquery command options
-group
-system system name
-sysplex_state
-sysplex_state
Displays the sysplex state of ZFS. Zero (0) indicates that
ZFS is not in a shared file system environment. One (1)
indicates that ZFS is in a shared file system environment
$> zfsadm configquery -sysplex_state
IOEZ00317I The value for configuration option -sysplex_state is 1.

Chapter 9. Managing file systems
507
9.57 Configuration options
Figure 9-58 Examples of new command configuration options for sysplex
Command forwarding with z/OS v1R7
Using the -system system name as a parameter with the
zfsadm
command, it specifies which
system to route the command to. The following command displays the attached aggregates
on system SC70. The command was issued from system SC65.
PAUL @ SC65:/>zfsadm aggrinfo -system sc70
IOEZ00368I A total of 1 aggregates are attached to system SC70.
ROGERS.HARRY.ZFS (R/W COMP): 3438 K free out of total 3600
Sysplex group
Beginning with z/OS V1 R7, zFS administration commands use XCF communications to
exchange zFS aggregate and file system information between members of the sysplex.
During zFS initialization, zFS must contact each other zFS system that is active in the sysplex
group to announce itself to the other members of the group and to receive information about
attached aggregates from the other members of the group. The zFS group name can be
defined in the IOEFSPRM file or the IOEPRMxx PARMLIB member. The following command
displays the group and IOEZFS is the default if not specified.
PAUL @ SC65:/>zfsadm configquery -group
IOEZ00317I The value for configuration option -group is IOEZFS.
-system system name
Specifies the name of the system the report request will be
sent to, to retrieve the data requested
-group
Display XCF group for communication between members
Default Value: IOEZFS
Expected Value: 1 to 8 characters
PAUL @ SC65:/>zfsadm configquery -group
IOEZ00317I The value for configuration option -group is IOEZFS.
PAUL @ SC65:/>zfsadm aggrinfo -system sc70
IOEZ00368I A total of 1 aggregates are attached to system SC70.
ROGERS.HARRY.ZFS (R/W COMP): 3438 K free out of total 3600

508

ABCs of z/OS System Programming: Volume 9
9.58 Command forwarding support
Figure 9-59 Other functions enhanced by the command forwarding support
Command forwarding
Command forwarding support is an enhancement in z/OS V1R7. This allows zFS commands
to be issued from any system in a sysplex without regard to which system owns the file
system. DFSMS backup (ADRDSSU) now automatically exploits this function. Backups can
now be issued from any member of the sysplex
DFSMS backup with ARDRSSU
If any systems in the sysplex are running a release of z/OS lower than Version 1 Release 7,
the job must be run on the sysplex member where the aggregate(s) is attached. If the job is
not run on the same member of the sysplex, the quiesce will fail and the job will terminate.
However, if all systems in the sysplex are running z/OS Version 1 Release 7, you can run the
backup job on any member of the sysplex.
zfsadm commands will now display and work with
zFS aggregates and file systems across the sysplex
This enhancement is exploited by:
DFSMS backup (ADRDSSU)
Backups can now be issued from any member of the
sysplex when all members are at z/OS V1R7
regardless of which member owns the file system
ISHELL
zFS administrators

Chapter 9. Managing file systems
509
9.59 Indirect volsers with zFS data sets
Figure 9-60 Indirect volsers with zFS data sets
Indirect volsers with zFS data sets
Starting with z/OS V1R12, you can make a clone, or copy, of a zFS data set and use indirect
volume serials to access it. This lets you define a catalog entry for a zFS to specify different
volume serials for different systems, which might allow the use of existing processes for
cloning systems when zFS is used for the version root file system.
To make cloning of zFS data sets to different systems easier, decide which volumes to copy
zFS data sets to and review your copy jobs.
Use system symbols
Ensure you have a system symbol defined for the target volume. It is best to use the
ADRDSSU COPY utility with the PHYSINDYNAM option to copy your zFS data sets if you are
using this function.
Note:
This support is limited to single-volume zFS data sets.
Cloning of zFS data sets to different systems
Decide which volumes to copy zFS data sets to
Ensure you have a system symbol defined for the
target volume
It is best to use the ADRDSSU COPY utility with the
PHYSINDYNAM option to copy your zFS data sets
A single catalog entry (for zFS VSAM LDS data sets)
can represent different volumes on various systems
This support is limited to single volume zFS data sets

510

ABCs of z/OS System Programming: Volume 9
9.60 Using indirect volume serials with cloned zFS data sets
Figure 9-61 Indirect volsers with cloned zFS data sets
Indirect volsers with cloned zFS data sets
Clone a zFS by making copies of the existing zFS data sets using COPY with the
PHYSINDYNAM (PIDY) parameter for the following reasons:

Using PHSYINDYNAM creates an uncataloged copy of the data set. You need the
uncataloged version so that it can be accessed by the catalog entry with the indirect
volser.

Using PHYSINDYNAM (PIDY) lets you use the same name for your original and copied
zFS.
Specifying symbolic volsers for zFS data sets
To use an indirect VOLSER for zFS data sets, you need to set up a system symbolic in an
IEASYMxx member of SYS1.PARLMLIB. The following example shows how to define a
symbolic using the SYMDEF statement for IEASYMxx. In this example, the symbolic name is
&VOL01 and it is assigned a specific volume serial number of 1P0301 to be used on that
system.
SYSDEF SYMDEF(&VOL01.='1P0301')
Note:
The symbol must be set to the whole volume number. The period at the end of the
symbolic is optional.
Clone a zFS by making copies of the existing zFS
data sets using COPY with the PHYSINDYNAM
(PIDY) parameter for the following reasons:
Using PHSYINDYNAM creates an uncataloged copy of
the data set
You need the uncataloged version so that it can be
accessed by the catalog entry with the indirect volser
Using PHYSINDYNAM (PIDY) lets you use the same
name for your original and copied zFS
Create a system symbolic in IEASYMxx for &VOL01
for each system that has a copy of the zFS data set
SYSDEF SYMDEF(&VOL01.=‘1P0301')

Chapter 9. Managing file systems
511
IEASYMxx parmib member
To use the IEASYMxx parmlib member on a given system, append the 2-character xx
identifier to the IEASYM parameter in the LOADxx parmlib member of SYS1.IPLPARM. The
LOADxx member specifies the IEASYMxx member(s) to search for any symbolic definitions
used on that system.
JCL for the COPY command
The following JCL shows a recommended COPY command to clone a zFS.
//STEPT07 EXEC PGM=ADRDSSU
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
COPY DS(INC(ZFS.LDS)) -
PIDY ( -
(1P0301) -
) -
OUTDY ( -
(1P0302) -
) -
REPLACEU -
ALLDATA(*) -
ALLEXCP

512

ABCs of z/OS System Programming: Volume 9
9.61 Define a VSAM LDS and format
Figure 9-62 Define a VSAM LDS and format it
Define a VSAM LDS and format
The
DEFINE CLUSTER
command builds a cluster entry and a data entry to define the linear data
set cluster. The parameters are:

NAME specifies that the cluster's name is ZFS.LDS.

VOLUMES specifies that the cluster is to reside on volume IP0301.

STORCLAS for SMS-managed data sets gives the 1-8 character name of the storage
class. When possible, allow STORCLAS to default through the ACS routines established
by your storage administrator. Attributes assigned through storage class and the ACS
routines replace storage attributes such as UNIT and VOLUME. If SMS is not active, the
system checks the syntax and then ignores the STORCLAS parameter.

LINEAR specifies that the cluster's data organization is to be linear.
IOEAGFMT utility
This is a batch utility that formats a VSAM linear data set to become a compatibility mode
aggregate.

-aggregate name - Specifies the name of the data set to format. This is also the aggregate
name.

-compat - Indicates that a compatibility mode aggregate should be created. This means
that in addition to formatting the VSAM LDS as a zFS aggregate, a zFS file system by the
same name (the aggregate name) is created.
Define a VSAM LDS using the real volume serial
Run the USS IOEAGFMT utility against the data set
This formats the LDS as a zFS data set by setting the
zFS indicator in the catalog record for the data set
DEFINE CLUSTER (NAME(ZFS.LDS) CYL(1 1) -
VOLUMES(1P0301) STORCLAS(S1P03S02) -
LINEAR)
//CREATE EXEC PGM=IOEAGFMT,REGION=0M,
// PARM=('-aggregate ZFS.LDS -compat')
//SYSPRINT DD SYSOUT=*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//CEEDUMP DD SYSOUT=*

Chapter 9. Managing file systems
513
9.62 Delete the data set and IDCAMS DEFINE
Figure 9-63 Delete the data set and IDCAMS DEFINE
Delete the data set and IDCAMS DEFINE
Use an IDCAMS DELETE NOSCRATCH against the data set, as follows:
DELETE ZFS.LDS NOSCRATCH
This deletes the catalog entry of the data set.
An existing data set can be cataloged through the access method services DEFINE
RECATALOG command. Next, you should then run an IDCAMS DEFINE RECATALOG using
the system symbolic (indirect volser) against the data set, as follows:
DEFINE ZFS.LDS VOLUMES(&VOL01) RECATALOG
This defines the data set with the system symbolic.
Note:
On each system set the value of the system symbolic to a different value. You then
will have a single catalog entry (for zFS VSAM LDS data sets) that represents different
volumes on various systems. You can then use this to clone volumes.
Run an IDCAMS DELETE NOSCRATCH against the
data set
DELETE ZFS.LDS NOSCRATCH
This deletes the catalog entry of the data set
Next - run an IDCAMS DEFINE RECATALOG using the
system symbolic (indirect volser) against the data set
DEFINE ZFS.LDS VOLUMES(&VOL01) RECATALOG
This defines the data set with the system symbolic

514

ABCs of z/OS System Programming: Volume 9
9.63 Centralized BRLM support
Figure 9-64 Centralized BRLM support
Centralized BRLM
The byte-range lock manager (BRLM) is used to lock all or part of a file that you are
accessing for read-write purposes.
As a default, the lock manager is initialized on only one system in the sysplex. The first
system that enters the sysplex initializes the BRLM and becomes the system that owns the
manager. This is called a centralized BRLM.
In a sysplex environment, a single BRLM handles all byte-range locking in the shared file
system environment group. If the BRLM server crashes, or if the system that owns the BRLM
is partitioned out of the sysplex, the BRLM is reactivated on another system in the group. All
locks that were held under the old BRLM server are lost. An application that accesses a file
that was previously locked receives an I/O error, and has to close and reopen the file before
continuing.
Lock all or part of a file that you are accessing for:
Read-write purposes
As a default, the lock manager is initialized on only
one system in the sysplex
The first system that enters the sysplex initializes the
BRLM and becomes the system that owns the
manager - This is called a centralized BRLM
If the BRLM server crashes, or owning system
partitioned out of the sysplex
BRLM is reactivated on another system in the group
All locks that were held are lost
An application that accesses a file previously locked
receives an I/O error - must close and reopen the file

Chapter 9. Managing file systems
515
9.64 Distributed BRLM
Figure 9-65 Distributed BRLM
Distributed BRLM
You can choose to have distributed BRLM initialized on every system in the sysplex. Each
BRLM is responsible for handling locking requests for files whose file systems are mounted
locally in that system. Use distributed BRLM if you have applications that lock files that are
mounted and owned locally.
For distributed BRLM to be activated, the z/OS UNIX couple data set (BPXMCDS) must be
updated and the supported code must be installed and running on each system. See APAR
OW52293 for more information.
BRLM with z/OS V1R4
z/OS R1V4 implements the first phase of moveable BRLM in a sysplex. Moveable BRLM
provides the capability of maintaining the byte range locking history of applications, even
when a member of the sysplex dies. This first phase will focus on distributing the locking
history across all members of the sysplex. As a result, many applications that lock files that
are locally mounted will be unaffected when a remote sysplex member dies. Movement away
from a centralized to a distributed BRLM will provide greater flexibility and reliability.
Can have distributed BRLM initialized on every
system in the sysplex
Each BRLM is responsible for handling locking
requests for files whose file systems are mounted
locally in that system
Use distributed BRLM if you have applications that
lock files that are mounted and owned locally
To activate distributed BRLM
z/OS UNIX couple data set (BPXMCDS) must be
updated
Supported code must be installed and running on
each system - See APAR OW52293 for more
information

516

ABCs of z/OS System Programming: Volume 9
9.65 Define BRLM option in CDS
Figure 9-66 BRLM and the OMVS couple data set
BRLM and OMVS couple data set
This support allows you to change to using distributed BRLM (rather than a single, central
BRLM) in the sysplex. With distributed BRLM, each system in the sysplex runs a separate
BRLM, which is responsible for locking files in the file systems that are owned and mounted
on that system. Because most applications (including cron, inetd, and Lotus® Domino) lock
local files, the dependency on having a remote BRLM up and running is removed. Running
with distributed BRLM is optional.
OMVS couple data set
ITEM NAME(DISTBRLM) NUMBER(1)

/*Enables conversion to a distributed BRLM.
1, distributed BRLM enabled,
0, distributed BRLM is not enabled during next sysplex IPL
Default = 0 */
Applications (including cron, inetd, and Lotus Domino)
lock local files
BPXMCDS
See http://www-03.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty2.html
for the rangelks REXX tool to identify currently running lock holders

Chapter 9. Managing file systems
517
9.66 BRLM problems in a sysplex
Figure 9-67 Moving byte range locks in z/OS V1R6
Byte-range locks with z/OS V1R6
With V1R6, the lock manager is initialized on every system in the sysplex. This is known as
distributed BRLM, and it is the only supported byte-range locking method when all systems
are at the V1R6 level. Each BRLM is responsible for handling locking requests for files whose
file systems are mounted locally in that system. Distributed BRLM was an option on previous
levels of z/OS, and central BRLM was formerly the default.
When a system failure occurs, all byte-range locks are lost for files in file systems owned by
that system. To maintain locking integrity for those locked files that are still open on surviving
systems, z/OS UNIX prevents further locking or I/O on those files. In addition, the applications
are signaled, in case they never issue locking requests or I/O. Running applications that did
not issue locking requests and did not have files open are not affected.
If you are already running with a z/OS UNIX CDS indicating that distributed BRLM is enabled,
there is no change required to activate distributed BRLM for V1R6. Likewise, if your sysplex
only has systems at the V1R6 level, there is no change required because distributed BRLM is
the default. V1R6 systems ignore the z/OS UNIX CDS DISTBRLM setting.
However, if you migrate to V1R6 by running mixed levels in a sysplex, you should enable
distributed BRLM before IPLing the V1R6 system because a V1R6 system may attempt to
activate distributed BRLM when the central BRLM server leaves the sysplex, regardless of
the z/OS UNIX CDS setting.
A file system cannot be moved in a sysplex when an
application holds byte range locks in that file system
Moving of locks was not supported with distributed
BRLM
Also, applications holding byte range locks in a
remote file system are exposed when that remote
sysplex member normally terminates
The locks are lost and the application is notified
Solution z/OS V1R6:
Distributed BRLM is enhanced to support moving byte
range locks

518

ABCs of z/OS System Programming: Volume 9
9.67 z/OS V1R8 BRLM recovery of locks
Figure 9-68 BRLM recovery of locks
BRLM lock recovery
Management of locks in a z/OS UNIX environment began with OS/390 V2R9 using central
BRLM in a shared HFS sysplex that included support for one BRLM. This implementation
became a single point of failure. z/OS V1R4 offered distributed BRLM, which provided one
BRLM per system in a sysplex where lock commands are routed to the file system owner. In
z/OS V1R6, distributed BRLM with moveable locks was introduced and the locks moved when
the file system moved. Distributed BRLM then became the default in a z/OS V1R6 sysplex.
In z/OS V1R8, the ability to recover file locks when the remote system fails is implemented.
The order for a remote file lock occurs in the following way:
1.An application issues a lock for a file owned by another system.
2.USS forwards the lock to that system’s BRLM.
3.USS forwards the lock to the owner system’s BRLM.
4.…... file owner system fails.
5.USS recovers the file system and declares a new owning system.
6.USS re-issues the lock to the new owner.
Attention:
When the file system containing the file is owned remotely, the lock will also be
remote.
When an USS application locks a remote file, the
lock is lost when the remote system is lost
Solution: Back up remote locks locally, and recover
them when a system fails
An application issues a lock for a file owned by
another system
USS forwards the lock to that systems BRLM
USS forwards the lock to the owner systems BRLM
…... file owner system fails
USS recovers the file system and declares a new
owning system
USS re-issues the lock to new owner

Chapter 9. Managing file systems
519
9.68 File system access
Figure 9-69 Accessing file system data from different methods
Accessing file system data
We have seen how we can customize the HFS for use. But who can use the HFS and the
z/OS UNIX? The z/OS UNIX file system can be used or accessed by using any of the
following:
TSO/E
TSO/E has commands for browsing and editing HFS files, for copying
data between HFS files and MVS data sets, to mount file systems, to
invoke the z/OS UNIX shell. There is also a command called ISHELL
which provides an ISPF menu-driven interface to the file system.
JCL
JCL provides keywords which support the specification of HFS path
names.
REXX
REXX has a set of z/OS UNIX extensions (
syscall
commands) to access
z/OS UNIX callable services.
z/OS UNIX shell
The shell is the UNIX interface to the file system. It contains commands
and utilities to access HFS files.
C programs
z/OS UNIX supports many C functions to access HFS files.
Shell scripts
Shell scripts are similar to REXX execs. z/OS UNIX System Services
shell commands and utilities can be stored in a text file that can be
executed.
REXX
execs
Shell
scripts
TSO
z/OS Shell
JCL
programs
MOUNT
MKDIR
OGET
OPUT
OCOPY
OEDIT
OBROWSE
ISHELL
PATHNAME
PATHDISP
PATHMODE
PATHOPTS
DSNTYPE
open()
read()
write()
close()
ls -l /u/op251
mkdir /u/op251/dir1
cd /u/op251/dir1
oedit 'newfile'
cat newfile
Clists
JAVA
prg.
TCP/IP
Dir
Dir
Dir
F
F
F
F
Dir
F

520

ABCs of z/OS System Programming: Volume 9
The HFS data set cannot be OPENed by any MVS utilities. Only DFSMSdss can be used to
dump and restore this data set type. The internal structure of an HFS data set is only
accessible via z/OS UNIX System Services.

Chapter 9. Managing file systems
521
9.69 File access
Figure 9-70 File system access versus MVS data set access
File access comparison
Figure 9-70 shows corresponding file access methods in z/OS and the POSIX standard.
The big difference is only the file handling. While OS/390 gives you file handle methods (you
do not have to implement this), the POSIX standard does not define the file handling
methods. So any application running on the POSIX standard is responsible for storing and
retrieving data from and to the file.
ALLOCATION
OPEN
GET
PUT
ENQ
CLOSE
UNALLOCATION
Security VIA
DATA SET
PROFILES
EXCP
BDAM
BSAM
VSAM
VTAM
z/OS UNIX
open()
read()
write()
fcntl() advisory
locking
close()
permission bits
on each file
RECORD
ORIENTED
KSDS
ESDS
byte stream
file organization is the
applications resposibility
z/OS

522

ABCs of z/OS System Programming: Volume 9
9.70 List file and directory information
Figure 9-71 Command to access file and directory information
Displaying files and directories
Figure 9-71 shows the output of the
ls -alEW
command.

File type describes the type of file (for example,
d
Directory,
l
Symbol link,
c
Character
special file,
f
Regular file, and so on).

File permissions are Read Write Execute for user group and other. Sticky Bit.

Owner audit (f for failed, s for successful access if audit attribute is set).

Auditor audit is the same as for owner audit.

External attributes.

Links are the number of links to the file.

Owner user ID shows which user ID owns the file or directory.

Owner Group ID shows the name of the group that owns this file or directory.

File size is the size of the file in bytes.

Date and Time shows the date and time of change or creation.

Name specifies a file name or link pointing to the file name.
GGI:TC4:/:==>ls -alEW
-rw------- fff--- --s 1 OMVSKERN SYS1 43 Jan 28 09:23 .sh_history
drw------- fff--- 2 OMVSKERN SYS1 0 Jan 22 14:34 \TFS
drwxr-xr-x fff--- 4 OMVSKERN OMVSGRP 0 Jul 27 1998 bin
drwxr-xr-x fff--- 2 OMVSKERN OMVSGRP 0 Jul 26 1998 dev
drwxr-xr-x fff--- 9 OMVSKERN OMVSGRP 0 Jan 25 08:40 etc
lrwxrwxrwx fff--- 1 OMVSKERN SYS1 16 Jan 22 14:04 krb5 -> etc/

dce/var/krb5
File
type
File
permissions
Links
Owner
userid
Owner
groupid
File
size
Date
and
time
Name
Owner
audit
-W
Extended
attributes
- E
Auditor
audit
- W

Chapter 9. Managing file systems
523
9.71 File security packet - extattr bits
Figure 9-72 Extended attribute bits in the FSP
extattr bits in the FSP
The extended attributes are kept in the file security packet (FSP). The extended attributes
give special authorities to the files. The
extattr
command is used to set these attributes.
a
When this attribute is set (+a) on an executable program file (load module), it behaves as
if loaded from an APF-authorized library. For example, if this program is exec()ed at the
job step level and the program is linked with the AC=1 attribute, the program will be
executed as APF-authorized. To be able to use the
extattr
command for the +a option,
you must have at least READ access to the BPX.FILEATTR.APF FACILITY class profile.
l
When this attribute is set (+l) on an executable program file (load module), it will be loaded
from the shared library region. To be able to use the extattr command for the +l option,
you must have at least READ access to the BPX.FILEATTR.SHARELIB FACILITY class.

p
When this attribute is set (+p) on an executable program file (load module), it causes the
program to behave as if an RDEFINE had been done for the load module to the
PROGRAM class. When this program is brought into storage, it does not cause the
environment to be marked dirty. To be able to use the extattr command for the +p option,
you must have at least READ access to the BPX.FILEATTR.PROGCTL FACILITY class.
s
If the extended attribute for the shared address space is not set, the program will not run
in a shared address space, regardless of the setting of _BPX_SHAREAS. The attribute is
set by extattr +s and reset by extattr -s.
F
The
extattr
command is used to set a file format for a file, but it cannot be set for
symlinks and directories.
File Permission Bits
File Mode
extattr
(FSP)
File
Owner
UID
File
Owner
GID
S
e
t
U
I
D
S
e
t
G
I
D
S
t
i
c
k
y
r
w
x
r
w
x
r
w x
Owner Group Other
extattr
File
Owner
RACF
Auditor
ACLs
extattr bits control the following for files:
APF authorization
Program control
Programs sharing address spaces
Programs sharing libraries
Sticky bit: executable is to be searched
in z/OS LPA and Libraries
(STEPLIB, LPA, LNKLST)
SetGID: the effective GID is the file
owner's GID during execution
SetUID: the effective UID is the file
owner's UID during execution
p: the executable is
'program controlled'
a: the executables is
APF authorized
s: the program does not
run in shared address
space if bit is off
l : shared library program
File format (New)
F: File format

524

ABCs of z/OS System Programming: Volume 9
9.72 Extended attributes
Figure 9-73 Listing the extended attributes
Extended attributes bits
The extended attributes give special authorities to the files. Four different extended attributes
are defined:
APF Authorized programs
The behavior of these programs is the same as other
programs that are loaded from APF-authorized libraries.
Program-controlled program
All programs that are loaded into an address space that
requires daemon authority need to be marked as “controlled.”
Shared AS
The program shares its address space with other programs.
Shared library
Programs using shared libraries contain references to the
library routines that are resolved by the loader at run time.
File format
The file format can now be specified as any of the following
formats: binary data, newline, carriage return, line feed,
carriage return followed by line feed, line feed followed by
carriage return, or carriage return followed by newline.
Extended attribute bits - (ls -E)
The
ls -E
shell command has an option that displays these attributes:
a
Program runs APF-authorized if linked AC=1
p
Program is considered program-controlled
APF Authorized
Prg Controlled
File format
shared library
Shared AS
rwx rwx rwx fff---
a p s l
F
filename
a
p
s
l
ls -EH
extattr command
F

Chapter 9. Managing file systems
525
s
Program runs in a shared address space
l
Program is loaded from the shared library region
Extended attribute bits - (ls -H)
In Figure 9-74 on page 525 you can see the output of the
ls
command using the
-H
option,
which allows the file format to be displayed for a file.
Figure 9-74 Sample output of ls -H
Figure 9-75 Sample output of ls -EH
extattr command
To set the extended attribute bits, the
extattr
command can be used.
Displaying extended attributes
The status of the extended attributes can be shown with the following commands:
ls
Sticky Bit and Set UID/GID Bit
ls -E
APF Auth., Program Control, Shared AS, and shared library
l
s -W
RACF Audit
Setting the extended attributes
With the following commands you can set the different extended attributes:
chmod
Sticky Bit, Set UID/GID
mkdir
Sticky Bit
extattr
Program Control, APF authorized, Shared AS
ROGERS @ SC75:/u/rogers>extattr -F CRLF maxcore
ROGERS @ SC75:/u/rogers>ls -H
total 160
-rwxr-xr-x crlf 1 SYSPROG SYS1 73728 Apr 21 16:08 maxcore
ROGERS @ SC75:/u/rogers>
ROGERS @ SC64:/u/rogers>ls -EH
total 240
-rw-r--r-- --s- nl 1 HAIMO SYS1 1570 Jun 14 2006 CEEDUMP.2006061
4.094113.67305623
-rwxr-xr-x a-s- ---- 1 HAIMO SYS1 0 Aug 17 2005 apf.file
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 28 2006 cache1
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 28 2006 cache2
drwxr-xr-x 2 HAIMO SYS1 8192 Mar 2 2006 cachex
drwxr-xr-x 2 HAIMO SYS1 8192 Mar 2 2006 cachey
-rwx------ --s- nl 1 HAIMO SYS1 729 Aug 2 11:32 cbprnt
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 21 2006 fill
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 21 2006 fill3
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 21 2006 fill4
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 23 2006 fill5
-rwx------ --s- nl 1 HAIMO SYS1 648 Sep 4 01:31 gener
drwxr-xr-x 2 HAIMO SYS1 8192 Feb 8 2006 largezfs

526

ABCs of z/OS System Programming: Volume 9
9.73 APF-authorized attribute
Figure 9-76 APF-authorized attribute
APF-authorized bit
The entire HFS is considered as an unauthorized library. You can authorize individual
programs within the HFS as APF-authorized by setting the APF-extended attribute. If a
program running in an APF-authorized address space attempts to load a program from the
HFS that does not have the APF-extended attribute set, the load is rejected. This applies to
non-jobstep exec local spawn, attach_exec, and DLL loads.
In order to activate APF authorization, the RACF profile BPX.FILEATTR.APF must be
defined. The z/OS UNIX administrator must have read access to this profile to execute the
extattr
command, as follows:

To turn on the APF-authorized program bit, issue:
extattr +a filename

To remove the APF-authorized program bit, issue:
extattr -a filename
You can link-edit the program into an APF-authorized library and turn on the sticky bit in the
HFS. You can use the
extattr
shell command to set the APF-authorized extended attribute of
the file.
If an APF-authorized program is the first program to be executed in an address space, then
you also need to set the Authorization Code to 1 (AC=1) when your program is link-edited. If a
program is loaded into an APF-authorized address space but is not the first program to be
executed, it should not have the AC=1 attribute set.
SETROPTS RACLIST(FACILITY) REFRESH
RDEFINE FACILITY -
BPX.FILEATTR.APF -
UACC(NONE)
PERMIT BPX.FILEATTR.APF -
CLASS(FACILITY) ID(UNIXSYS) -
ACCESS(READ)
AC=1
extattr +a filename
User: UNIXSYS
extattr +a filename
ext
ext
rwxrwxrwx a--- filename

Chapter 9. Managing file systems
527
9.74 Activate program control
Figure 9-77 Program control extended attribute
Program control attribute bit
All programs loaded into an address space that requires daemon authority need to be marked
as controlled. This means that user programs and any run-time library modules that are
loaded must be marked as controlled.
You can mark programs in HFS files as controlled by turning on the extended attribute that
allows you to run program-controlled. To turn this extended attribute on:
extattr +p filename
extattr +p /user/sbin/proga
Only users with the correct permission can turn on the extended attribute. The example above
shows the RACF command used to give this permission to z/OS UNIX administrator
UNIXSYS. To turn off the extended attribute, use the
extattr
shell command:
extattr -p filename
extattr -p /user/sbin/su
After a file is marked program-controlled, any activity that can change its contents results in
the extended attribute being turned off. If this occurs, a system programmer with the
appropriate privilege will have to verify that the file is still correct and reissue the
extattr

command to mark the file as program-controlled.
All modules loaded from LPA are considered to be controlled.
RACF Security
z/OS UNIX
SETROPTS RACLIST(FACILITY) REFRESH
RDEFINE FACILITY -
BPX.FILEATTR.PROGCTL -
UACC(NONE)
PERMIT BPX.FILEATTR.PROGCTL -
CLASS(FACILITY) ID(UNIXSYS) -
ACCESS(READ)
User: UNIXSYS
extattr +p filename
rwxrwxrwx -p- filename
extattr +p filename
ext
ext

528

ABCs of z/OS System Programming: Volume 9
9.75 Shared address space attribute
Figure 9-78 Shared AS extended attribute
Shared address space attribute bit
To improve the performance in the shell, the extended attribute for shared AS can be set. The
program will share this address space with other programs.
To turn this extended attribute on:
extattr +s filename
To turn off the bit:
extattr -s filename
When this attribute is not set (-s), the _BPX_SHAREAS environment variable is ignored when
the file is spawn()ed. By default, this attribute is set (+s) for all executable files.
To improve performance for all shell users, it is recommended that /etc/profile or
$HOME/.profile set the environment variable.
z/OS UNIX profile
extattr +s filename
User: UNIXSYS
extattr +s filename
rwxrwxrwx --sfilename
z/OS UNIX
_BPX_SHAREAS=....
exattr -s filename
/etc/profile
or $HOME/.profile
export _BPX_SHAREAS=YES
(2). Set bit
ext
ext
(1). If bit is not set, turn it on

Chapter 9. Managing file systems
529
9.76 Shared library attribute
Figure 9-79 Shared library extended attribute
Shared library attribute bit
When this attribute is set (
+l
) on an executable program file (load module), it will be loaded
from the shared library region.
To be able to use the
extattr
command for the
+l
option, you must have at least READ
access to the BPX.FILEATTR.SHARELIB FACILITY class. For more information, see
z/OS
UNIX System Services Planning,
GA22-7800.
The BPX.FILEATTR.SHARELIB FACILITY class profile controls who can set the shared
library extended attribute. The following example shows the RACF command that was used to
give READ access to user Ralph Smorg with user ID SMORG:
RDEFINE FACILITY BPX.FILEATTR.SHARELIB UACC(NONE)
PERMIT BPX.FILEATTR.SHARELIB CLASS(FACILITY) ID(SMORG) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
To set the shared library attribute, issue the
extattr
command with the
+l
option. In the
following example,
proga
is the name of the file.
extattr +l /user/sbin/proga
Note:

l
is a lower case L, not the numeral one or an upper case i.
z/OS UNIX Shell
SETROPTS RACLIST(FACILITY) REFRESH
RDEFINE FACILITY -
BPX.FILEATTR.SHARELIB -
UACC(NONE)
PERMIT BPX.FILEATTR.SHARELIB -
CLASS(FACILITY) ID(UNIXSYS) -
ACCESS(READ)
User: UNIXSYS
extattr +l /user/sbin/proga
rwxrwxrwx -l-/user/sbin/proga
extattr +l /user/sbin/proga
ext
ext

530

ABCs of z/OS System Programming: Volume 9
9.77 File format attribute
Figure 9-80 Specifying the file format attribute
File format attribute
Prior to z/OS V1R8, there was no supported commands to set the file format from the OMVS
shell. The
extattr
command is enhanced to accept a –F option with values consistent with
the
cp
command to indicate the format of the file.
To copy file f1 to a fully qualified sequential data set 'turbo.gammalib' and treat it as a binary:
cp -F bin f1 "//'turbo.gammalib'"
The syntax for the
extattr
command is as follows:
extattr [+alps] [-alps] [-F] file
Specifying the file format option
The format option can be specified in lowercase, uppercase, or in mixed case. The format
option can also be specified with a space or no space after the file format flag (-F). For
example, by specifying -F with line feed (LF) and carriage return (cr), as follows:
extattr -FLFcr filename
The file format flag (-F) can be used with other
extattr
flags (+alps/-alps), but it must be
separated by a space or tab. For example:
extattr +aps -F BIN filename (is a valid entry)
extattr -apsF NA filename (is not a valid entry)
Support the file format from the OMVS shell
extattr command is enhanced to accept a –F option
Values - consistent with the cp command to indicate
the format of the file
extattr –F command from the shell
For format you can specify:
NA - Not specified
BIN - Binary data
Or the following text data delimeters:
NL – New Line
CR - Carriage Return
LF - Line Feed
CRLF - Carriage Return followed by Line Feed
LFCR - Line Feed followed by Carriage Return
CRNL - Carriage Return followed by New Line

Chapter 9. Managing file systems
531
So the option -F can have the values shown in Table 9-1 on page 531.
Table 9-1 Possible -F options for extattr
The setting of a file format flag has no impact on the contents of the file. You can easily set the
file format flag as follows:
extattr -F CRLF extattr.test
In this example, the file extattr.test is set as a text file that contains carriage returns and file
feed—also known as a regular text file.
Value Format options
NA Not specified
BIN Binary data file
Value Text data delimeters
NL New line
CR Carriage return
LF Line feed
CRLF Carriage return followed by line feed
LFCR Line feed followed by carriage return
CRNL Carriage return followed by new line

532

ABCs of z/OS System Programming: Volume 9
9.78 Extended attribute command example
Figure 9-81 Extended attributes displayed
Display of extended attributes
Setting the file format flag on a file does not modify the data in the file. The file format can be
displayed via the
ls -H
command.
Figure 9-81 shows a
ls -alHE
command that displays all five extended attributes.
-E
displays
the original four attributes.
In the output,
--s-
is the shared address space attribute for the files.
The file, maxcore, has the attributes
--s- crlf
, where
crlf
is the file format carriage return
and line feed.
ROGERS @ SC75:/u/rogers>ls -alHE
total 184
drwxr-x--- 7 SYSPROG SYS1 544 Sep 13 14:15 .
dr-xr-xr-x 7 SYSPROG TTY 0 Sep 13 13:54 ..
-rw------- --s- ---- 1 SYSPROG SYS1 638 Sep 15 13:35 .sh_history
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 14:15 00000100
drwxr-xr-x 5 SYSPROG OMVSGRP 1120 Jul 26 21:57 ITSO-link
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 14:06 db2
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 14:05 echo
drwxr-xr-x 2 SYSPROG SYS1 256 Sep 13 14:15 ims
-rwx------ --s- ---- 1 SYSPROG SYS1 0 Aug 28 09:31 inetd-stderr
-rwx------ --s- ---- 1 SYSPROG SYS1 0 Aug 28 09:31 inetd-stdout
-rwxr-xr-x --s- crlf 1 SYSPROG SYS1 73728 Apr 21 16:08 maxcore
Example shows now both sets of extattr values
extattr -F CRLF maxcore

Chapter 9. Managing file systems
533
9.79 Sticky bit
Figure 9-82 Using the sticky bit
Sticky bit for files
The
sticky bit
is a file access permission bit that allows multiple users to share a single copy
of an executable file.
For frequently used programs in the HFS, you can use the
chmod
command to set the sticky
bit. This reduces I/O and improves performance. When the bit is set on, z/OS UNIX searches
for the program in the user's STEPLIB, the link pack area, or the link list concatenation.
Sticky bit for directories
Using the
mkdir
, MKDIR, or
chmod
command, you can set the sticky bit “on” in a directory to
control permission to remove or rename files or subdirectories in the directory. When the bit
is set, a user can remove or rename a file or remove a subdirectory only if one of these is
true:

The user owns the file or subdirectory.

The user owns the directory.

The user has superuser authority.
The
mkdir
command creates a new directory for each named directory argument. The mode
for a directory created by
mkdir
is determined by taking the initial mode setting of 777 (a=rwx)
or the value of
-m
if specified and applying the umask to it.
Control File Access
Performance
Improvement
Rename or remove
not allowed, unless:
user's STEPLIB
LINK PACK AREA
LINK LIST
Concat.
Searches in:
chmod a+t [file | directory]
mkdir -m a+t directory
The user owns the file
The user owns the directory
The user has superuser
authority
X bit on
X bit off
rwxrw-rw t --- ...filename
rwxrw-rw T --- ...directory

534

ABCs of z/OS System Programming: Volume 9
The sticky bit is also set for frequently used programs in the file system, to reduce I/O and
improve performance. When the bit is set on, z/OS UNIX searches for the program in the